Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

19.3 KB
Raw Blame
/**
 * A person's one Buddy's folder (docs/specs/2026-10-31-one-buddy-per-swarm.md, Folder; Dee, 10-31). The Buddy reads every
 * project its person reads, so its folder is no project's checkout: it holds `projects/<name>`, one detached worktree per
 * project whose checkout is already on this machine, each made from that project's own checkout, so no two projects' files
 * ever mix. Nothing is cloned for it. Each copy follows its project's default branch (refreshBuddyHome): a worktree made once
 * and kept read days-old code, and the Buddy kept telling its person so (Scholes, 11-02). A Buddy works in it as its owner
 * would, with full access on their own machine (task #2832): a copy it changed is left where it is. A project its person no
 * longer reads leaves the folder before the Buddy's next turn (pruneBuddyHome).
 */
import { execFile } from 'node:child_process'
import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { isAbsolute, join } from 'node:path'
import { promisify } from 'node:util'
import { launchEnvironment } from '../engines/kit/launchExecutable.js'
import { folderTrust } from '../engines/launchPrep.js'
import { gitEnv, insideGitCheckout, originDefaultRef, remoteBranch } from '../lib/gitProject.js'

const run = promisify(execFile)
/** A project as the backend lists it in a Swarm-wide Buddy's start (AgentStartRequest.buddyProjects). */
export interface BuddyProject { id: string; name: string; cwd: string }
/** Each worktree's project, so a later pass knows which folder is whose. */
interface Listed { id: string; name: string; dir: string }
/** The folder's list of its worktrees' projects: a person's one Buddy's folder is the one that holds it. */
export const BUDDY_HOME_MANIFEST = '.buddy-projects.json'
const MANIFEST = BUDDY_HOME_MANIFEST
/** The folder in Harness's worktrees folder that holds the one Buddies' folders, one per start (start.ts). */
export const BUDDY_HOMES = 'buddy-home'
/** At most this many, as the backend lists (machines.ts MAX_BUDDY_PROJECTS). */
export const MAX_BUDDY_PROJECTS = 50
const ID = /^[A-Za-z0-9_-]{1,64}$/
/** What the Buddy reads to learn where each copy is. A file, as a copy moves while it runs and its prompt is fixed at its start,
 *  and the main Buddy's shell has no repository to run git in (spec 2026-10-31, Folder). Its age also says when the last pass
 *  was, so "at most hourly" holds across a daemon restart. */
export const BUDDY_COPIES_FILE = 'project-copies.txt'
const REFRESH_EVERY_MS = 60 * 60_000
/** All of one pass's fetches share this: 50 projects offline must not hold a Buddy's start for 50 timeouts. */
/**
 * A hooks folder that holds none, for every git command on a Buddy's copy: the person's hooks are written for their own work.
 * `worktree add` ran their post-checkout in the copy (WinTest3348's diagnostic, #3815). On Windows `/dev/null` names C:\dev\null,
 * a folder any account may make, so there it is the NUL device, which can hold no hook.
 */
const NO_HOOKS = process.platform === 'win32' ? 'NUL' : '/dev/null'
const FETCH_BUDGET_MS = 30_000
const FETCH_TIMEOUT_MS = 20_000
const FETCHES_AT_ONCE = 4

/** The projects a start lists, as far as they are well formed: an id, a name and a folder absolute by this machine's own rules.
 *  A Windows checkout (C:\…, \\server\share\…) was dropped when this asked for a leading /, so a Buddy there had no copy of it
 *  (#3815); on a Mac or Linux those names are relative, resolved from the service's folder (Linuxtest2), and stay dropped. */
export function buddyProjectsOf(request: Record<string, unknown>): BuddyProject[] {
  const listed = Array.isArray(request.buddyProjects) ? request.buddyProjects : []
  return listed.flatMap(entry => {
    const p = entry as Record<string, unknown>
    return typeof p?.id === 'string' && ID.test(p.id) && typeof p.name === 'string' && typeof p.cwd === 'string' && isAbsolute(p.cwd)
      ? [{ id: p.id, name: p.name, cwd: p.cwd }] : []
  }).slice(0, MAX_BUDDY_PROJECTS)
}

/** A folder name for [name]: letters, digits, dots, dashes and underscores, never empty, `..` or a hidden name; [taken] keeps
 *  two projects of the same name apart. */
export function folderName(name: string, taken: ReadonlySet<string>): string {
  const base = name.normalize('NFKC').replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^[.-]+|-+$/g, '').slice(0, 60) || 'project'
  let dir = base
  for (let n = 2; taken.has(dir); n++) dir = `${base}-${n}`
  return dir
}

/** A folder name this file could have made (folderName): never a path, `..` or a hidden name, so a changed list can never
 *  point a removal outside `projects/` (security review 1 of #2436). */
const SAFE_DIR = /^[\p{L}\p{N}_][\p{L}\p{N}._-]{0,79}$/u
const listed = (home: string): Listed[] => {
  try {
    const rows = JSON.parse(readFileSync(join(home, MANIFEST), 'utf8')) as unknown
    return Array.isArray(rows) ? rows.filter((r): r is Listed => !!r && typeof r.id === 'string' && ID.test(r.id) && typeof r.dir === 'string'
      && SAFE_DIR.test(r.dir) && typeof r.name === 'string') : []
  } catch { return [] }
}
function writeListed(home: string, rows: Listed[]): void {
  const path = join(home, MANIFEST), next = `${path}.next`
  rmSync(next, { force: true })
  writeFileSync(next, `${JSON.stringify(rows)}\n`, { mode: 0o600 })
  renameSync(next, path)
}

/**
 * Makes [home] with a worktree of each of [projects] whose checkout is on this machine, and says which are there and which
 * are not (their code is not on this machine; the Buddy still reads their chats and tasks). A worktree made before is kept and
 * brought to its project's default branch, as a new one is (refreshBuddyHome); one that cannot be made is left out, never
 * retried in a loop. The person's own working files and branches are never touched.
 */
export async function prepareBuddyHome(home: string, projects: readonly BuddyProject[]): Promise<{ ready: string[]; missing: string[] }> {
  await refreshing.get(home)?.done
  ownFolders(home, true)
  mkdirSync(join(home, 'projects'), { recursive: true, mode: 0o700 })
  ownFolders(home)
  // A project its person no longer reads leaves before the Buddy's first turn, not only before a delivery (security review 1
  // of #2436): a relaunch starts from the list the start names now.
  await pruneBuddyHome(home, new Set(projects.map(p => p.id)))
  const rows = listed(home), ready: string[] = [], missing: string[] = []
  const taken = new Set(rows.map(r => r.dir))
  for (const project of projects) {
    const known = rows.find(r => r.id === project.id)
    // Kept only while it is still the folder made here: a link in its place is taken out and the worktree made again.
    const kept = known && lstatSync(join(home, 'projects', known.dir), { throwIfNoEntry: false })
    if (kept && kept.isDirectory()) { ready.push(project.name); continue }
    if (kept) await removeWorktree(home, known!.dir)
    if (!(await insideGitCheckout(project.cwd).catch(() => false))) { missing.push(project.name); continue }
    const dir = known?.dir ?? folderName(project.name, taken)
    taken.add(dir)
    try {
      // A folder of this name removed before (a link taken out, a folder deleted) may still be listed by its checkout.
      await run('git', ['-C', project.cwd, 'worktree', 'prune'], { timeout: 60_000 }).catch(() => undefined)
      await run('git', ['-c', `core.hooksPath=${NO_HOOKS}`, '-C', project.cwd, 'worktree', 'add', '--detach', '--', join(home, 'projects', dir), 'HEAD'], { timeout: 120_000 })
      if (!known) rows.push({ id: project.id, name: project.name, dir })
      ready.push(project.name)
    } catch { missing.push(project.name) }
  }
  writeListed(home, rows)
  await refreshBuddyHome(home)
  return { ready, missing }
}

/** The folder of project [id] in a one Buddy's [home], when its code is there: where a file for that project's PM may come from,
 *  so no file of another project in the same home goes with it. */
export function buddyProjectFolder(home: string, id: string): string | null {
  const row = listed(home).find(r => r.id === id)
  return row ? join(home, 'projects', row.dir) : null
}

/** Where one copy stands after a pass, for the Buddy's file and the pass's one log line. */
type CopyState = { name: string; revision: string | null; state: 'latest' | 'noRemote' | 'changed' | 'failed' }
const refreshing = new Map<string, { stop: AbortController; done: Promise<void> }>()

/**
 * Brings each of [home]'s copies to its project's default branch and writes what the Buddy reads about them. Only one pass runs
 * per folder; a second call joins it. It never throws: a copy that cannot move stays as it is, says so in the file, and the pass
 * logs one line, with no retry before the next start or the next due delivery. Offline is ordinary.
 */
export function refreshBuddyHome(home: string): Promise<void> {
  const running = refreshing.get(home)
  if (running) return running.done
  const stop = new AbortController()
  const done = refreshPass(home, stop.signal)
    .catch((error: unknown) => { console.warn(`[super-tabs] a Buddy's project copies were not refreshed: ${(error as NodeJS.ErrnoException).code ?? 'error'}`) })
    .finally(() => { refreshing.delete(home) })
  refreshing.set(home, { stop, done })
  return done
}

/** Whether the last pass was an hour ago. Read at a delivery, not on a timer, as only then does anything read the copies: an idle
 *  Buddy costs its person no fetches. */
export function buddyHomeDue(home: string, now = Date.now()): boolean {
  const last = lstatSync(join(home, BUDDY_COPIES_FILE), { throwIfNoEntry: false })?.mtimeMs
  return last === undefined || now < last || now - last >= REFRESH_EVERY_MS
}

/** The pass running in [home], if any. */
export const buddyHomeRefreshing = (home: string): Promise<void> | undefined => refreshing.get(home)?.done

/** Whether [home] holds a project outside [readable], so that it must be pruned before its Buddy's next turn. */
export const buddyHomeHoldsLost = (home: string, readable: ReadonlySet<string>): boolean => listed(home).some(row => !readable.has(row.id))

/** Tells a running pass to stop, without waiting for it: the delivery loop serves every agent on the machine (review of #2524). */
export function stopBuddyHomeRefresh(home: string): void { refreshing.get(home)?.stop.abort() }

async function refreshPass(home: string, signal: AbortSignal): Promise<void> {
  ownFolders(home)
  const rows = listed(home), states: CopyState[] = [], deadline = Date.now() + FETCH_BUDGET_MS
  let next = 0
  const worker = async () => {
    while (next < rows.length && !signal.aborted) {
      const at = next++, row = rows[at]!
      states[at] = await refreshCopy(join(home, 'projects', row.dir), row.name, deadline, signal)
    }
  }
  await Promise.all(Array.from({ length: FETCHES_AT_ONCE }, worker))
  // Stopped because a project is leaving: its name must not go back in the file, and the next pass writes a whole one.
  if (signal.aborted) return
  writeCopies(home, states)
  const failed = states.filter(state => state.state === 'failed' || state.state === 'changed').length
  // A count alone: git's own words can hold a remote's address, and an address can hold a token.
  if (failed) console.warn(`[super-tabs] ${failed} of ${states.length} of a Buddy's project copies were left where they are.`)
}

/** One copy. The fetch runs in the Buddy's own worktree: git keeps FETCH_HEAD per worktree, so of the person's checkout it moves
 *  only the one remote-tracking ref named. Their hooks do not run: a post-checkout hook is written for their own work. */
async function refreshCopy(path: string, name: string, deadline: number, signal: AbortSignal): Promise<CopyState> {
  const state = (next: CopyState['state'], revision: string | null = null): CopyState => ({ name, revision, state: next })
  const entry = lstatSync(path, { throwIfNoEntry: false })
  if (!entry || !entry.isDirectory()) return state('failed')
  const words = (args: string[]) => ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', `core.hooksPath=${NO_HOOKS}`, '-C', path, ...args]
  const git = async (args: string[], options: { timeout?: number; signal?: AbortSignal } = {}) => (await run('git', words(args),
    { timeout: options.timeout ?? 60_000, maxBuffer: 64 * 1024 * 1024, env: gitEnv(process.env), ...(options.signal ? { signal: options.signal } : {}) })).stdout.trim()
  let at: string | null = null
  const here = async () => await git(['log', '-1', '--no-show-signature', '--format=%h %cs']).catch(() => null)
  try {
    // A folder that lost its .git would otherwise find whichever repository is above it, and move that one. Compared as the
    // file system resolves them: git reports a folder's real, long name, and on Windows a path can hold a short one
    // (C:\Users\HARNES~1) or another letter case, which made every copy there "another repository" (#3815).
    if (realpathSync.native(await git(['rev-parse', '--show-toplevel'])) !== realpathSync.native(path)) return state('failed')
    at = await here()
    const detached = await git(['symbolic-ref', '--quiet', 'HEAD']).then(() => false, () => true)
    if (!detached || await git(['status', '--porcelain'])) return state('changed', at)
    const remote = remoteBranch(await originDefaultRef(path) ?? undefined)
    if (!remote) return state('noRemote', at)
    const left = deadline - Date.now()
    if (left <= 0 || signal.aborted) return state('failed', at)
    await git(['-c', 'gc.auto=0', '-c', 'maintenance.auto=false', 'fetch', '--quiet', '--no-tags', '--no-prune', '--no-recurse-submodules', remote.remote, remote.refspec],
      { timeout: Math.min(left, FETCH_TIMEOUT_MS), signal })
    const [from, to] = [await git(['rev-parse', 'HEAD']), await git(['rev-parse', `refs/remotes/${remote.remote}/${remote.branch}^{commit}`])]
    if (from !== to && !signal.aborted) await git(['checkout', '--quiet', '--detach', '--no-recurse-submodules', to], { timeout: 120_000 })
    return state(await git(['rev-parse', 'HEAD']) === to ? 'latest' : 'failed', await here())
  } catch { return state('failed', at) }
}

function writeCopies(home: string, states: readonly CopyState[]): void {
  const line = (copy: CopyState) => {
    const name = copy.name.replace(/\s+/g, ' ')
    const at = copy.revision ? `at ${copy.revision}` : 'revision not known'
    if (copy.state === 'latest') return `${name}: ${at}. This is the latest default branch.`
    if (copy.state === 'noRemote') return `${name}: ${at}. This checkout has no remote default branch to follow.`
    return `${name}: ${at}. It could not be updated at the last refresh, so it may be behind the default branch.`
  }
  const path = join(home, BUDDY_COPIES_FILE), next = `${path}.next`
  rmSync(next, { force: true })
  writeFileSync(next, `Your copy of each project's code, refreshed ${new Date().toISOString()}:\n${states.map(line).join('\n')}\n`, { mode: 0o444 })
  // Windows will not rename over a read-only file (EPERM), and the last pass left this one read-only, so every later pass failed.
  // A plain file alone: chmod follows a link, and the Buddy can write in this folder, so one here could name a private file.
  if (process.platform === 'win32' && lstatSync(path, { throwIfNoEntry: false })?.isFile()) chmodSync(path, 0o644)
  renameSync(next, path)
}

/** A running pass stops before any more fetches or moves, and its running move finishes: a move killed part way would leave a
 *  half-moved copy that every later pass reads as changed. */
async function stopRefresh(home: string): Promise<void> {
  const running = refreshing.get(home)
  if (!running) return
  running.stop.abort()
  await running.done
}

/** Takes out of [home] each worktree whose project is not in [readable] (ids): its person lost it, or it was deleted. */
export async function pruneBuddyHome(home: string, readable: ReadonlySet<string>): Promise<string[]> {
  const rows = listed(home)
  const gone = rows.filter(r => !readable.has(r.id))
  if (!gone.length) return []
  ownFolders(home)
  // No pass may be working in, or naming, a project on its way out.
  await stopRefresh(home)
  for (const row of gone) await removeWorktree(home, row.dir)
  writeListed(home, rows.filter(r => readable.has(r.id)))
  // It names the lost project. Gone, the next pass is due and writes a whole one.
  rmSync(join(home, BUDDY_COPIES_FILE), { force: true })
  return gone.map(r => r.name)
}

/**
 * Answers Claude Code's question about [home], in the file it reads, as its launch would otherwise wait on it. That question
 * is asked in a terminal no Swarm view shows, so the Buddy sat at it until its start timed out (MacBookPro2021, 2026-11-02).
 * This is an exception to "never a folder with content" (engines/kit/folderTrust.ts): the folder is Harness's, made for the
 * start its person pressed, and what the question guards against cannot happen in it: its own root holds no project's settings,
 * hooks or MCP servers (each project's copy is a folder below it), and the folder goes with the Buddy. Claude Code and Codex
 * alike, as both run a Buddy (task #2832). On a computer where Claude Code never ran there is no settings file to extend: it is
 * made, holding this folder alone (task #3737). A failure here only leaves the question.
 */
export async function trustBuddyHome(home: string, engine: unknown): Promise<void> {
  if (engine !== 'claude' && engine !== 'codex') return
  try { folderTrust(engine, undefined, await launchEnvironment() ?? undefined)?.record(home, { create: true }) }
  catch (error) { console.warn(`[super-tabs] could not answer the folder question for a Buddy: ${(error as Error).message}`) }
}

/** Takes every worktree out of [home] and removes it: its Buddy ended. */
export async function removeBuddyHome(home: string): Promise<void> {
  await stopRefresh(home)
  // Through a link nothing is removed but the link itself (rm never follows one inside the folder it removes).
  const own = (() => { try { ownFolders(home); return true } catch { return false } })()
  if (own) for (const row of listed(home)) await removeWorktree(home, row.dir)
  rmSync(home, { recursive: true, force: true })
}

/** Refuses a Buddy folder, or its `projects/`, that is not a folder of its own: a link there would lead the worktrees made
 *  and removed in it somewhere else (security review 1 re-check of #2436). [mayBeMissing]: before the folder is made. */
function ownFolders(home: string, mayBeMissing = false): void {
  for (const path of [home, join(home, 'projects')]) {
    const entry = lstatSync(path, { throwIfNoEntry: false })
    if (!entry && mayBeMissing) return
    if (!entry || entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`BUDDY_FOLDER_NOT_OWN: ${path} is not a folder of its own; it is left as it is.`)
  }
}

/** Removes one worktree, read-only files included, and its checkout's record of it. A folder git no longer knows is removed.
 *  Only a folder directly in a Buddy folder's `projects/`, by a name this file makes. */
async function removeWorktree(home: string, dir: string): Promise<void> {
  if (!SAFE_DIR.test(dir)) return
  ownFolders(home)
  const path = join(home, 'projects', dir)
  // A link is never followed: a project folder that became a link to another worktree loses the link alone, and git is never
  // asked to remove what it points at (security re-check 2 of #2436).
  const entry = lstatSync(path, { throwIfNoEntry: false })
  if (!entry) return
  if (!entry.isDirectory()) { rmSync(path, { force: true }); return }
  await run('git', ['-C', path, 'worktree', 'remove', '--force', '--force', '--', path], { timeout: 60_000 }).catch(() => undefined)
  rmSync(path, { recursive: true, force: true })
}