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.

21.0 KB
Raw Blame
import { execFileSync } from 'node:child_process'
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { TeamConfig } from '../team/config.js'
import { agentTmpFolder, agentTmpLaunch, agentTmpRoot, agentTmpState, buddyTmpEnv, buddyTmpFolder, buddyTmpOf, buddyTmpParent, prepareAgentTmp, resetAgentTmpSweep, sweepAgentTmp, sweepTmpFolders, type AgentTmpDeps } from './agentTmp.js'

const made: string[] = []
afterEach(() => { for (const dir of made.splice(0)) rmSync(dir, { recursive: true, force: true }); resetAgentTmpSweep() })
const scratch = () => { const dir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-tmp-'))); made.push(dir); return dir }

const config = { user: 'harnessteam' } as TeamConfig
const deps = (dataDir: string, over: Partial<AgentTmpDeps> = {}): AgentTmpDeps => ({
  platform: 'darwin', dataDir, config: () => config, user: () => 'owner-placeholder', log: vi.fn(), now: () => 1_000_000_000_000, ...over,
})

const none = { env: {}, args: [] }

describe('who gets the private temporary folder', () => {
  // Task #4395: since #4215 an agent starts in its owner's own settings, which on the Mac Studio block reads outside the working
  // directories, and since v3 there is no Team computer, so agents used the system's folder and stopped at Claude Code's
  // question for their own mktemp file (Authorder, 11-07). Each Swarm agent gets a folder of its own, added to the engine's
  // working directories: Claude Code reads an added folder's own skills and settings, so one shared folder would let an
  // agent plant them for the others.
  it('a Swarm agent, with no Team account here: a 0700 folder of its own as TMPDIR, added to Claude Code\'s and Codex\'s working directories', () => {
    const data = scratch()
    const launch = agentTmpLaunch('claude', { role: 'agent', key: 'one' }, deps(data, { config: () => null }))
    const folder = launch.env.TMPDIR!
    expect(folder.startsWith(`${realpathSync(agentTmpFolder(data))}/`)).toBe(true)
    expect(statSync(folder).mode & 0o777).toBe(0o700)
    expect(statSync(agentTmpFolder(data)).mode & 0o777).toBe(0o700)
    // Joined to its flag: Claude Code's takes several values and would swallow what follows it.
    expect(launch).toEqual({ env: { TMPDIR: folder }, args: [`--add-dir=${folder}`] })
    expect(agentTmpLaunch('codex', { role: 'coordinator', key: 'one' }, deps(data, { platform: 'linux', config: () => null })))
      .toEqual({ env: { TMPDIR: folder }, args: [`--add-dir=${folder}`] })
    // The same agent's relaunch finds the same folder; another agent has its own, in the same workspace too: a person's
    // Regular agents all start in that person's home folder (security review of #3506). On a Mac too, only that folder is
    // added, never the account's own temporary folder, which every agent and app of the account shares.
    const another = agentTmpLaunch('claude', { role: 'agent', key: 'two' }, deps(data, { config: () => null })).env.TMPDIR
    expect(another).not.toBe(folder)
    expect(another!.startsWith(`${realpathSync(agentTmpFolder(data))}/`)).toBe(true)
  })

  it('an engine that takes no such folder gets the folder alone', () => {
    const data = scratch()
    const launch = agentTmpLaunch('opencode', { role: 'agent', key: 'one' }, deps(data, { config: () => null }))
    expect(launch.args).toEqual([])
    expect(launch.env.TMPDIR!.startsWith(`${realpathSync(agentTmpFolder(data))}/`)).toBe(true)
  })

  it('nobody else gets an added folder: a Buddy, whose guard closes the data folder; a terminal; a person\'s own session; Windows', () => {
    const data = scratch()
    expect(agentTmpLaunch('claude', { role: 'buddy', key: 'one' }, deps(data))).toEqual(none)
    expect(agentTmpLaunch('terminal', { role: 'agent', key: 'one' }, deps(data))).toEqual(none)
    expect(agentTmpLaunch('claude', undefined, deps(data, { config: () => null }))).toEqual(none)
    expect(agentTmpLaunch('claude', { role: 'agent', key: 'one' }, deps(data, { platform: 'win32' }))).toEqual(none)
    expect(existsSync(agentTmpFolder(data))).toBe(false)
  })

  it('a person\'s own session on a computer with a Team account keeps the shared folder, with nothing added', () => {
    const data = scratch()
    expect(agentTmpLaunch('claude', undefined, deps(data))).toEqual({ env: { TMPDIR: agentTmpFolder(data) }, args: [] })
    expect(agentTmpLaunch('claude', undefined, deps(data, { user: () => 'harnessteam' }))).toEqual(none)
  })

  it('a config that cannot be read counts as no Team account, and the agent still starts', () => {
    const data = scratch()
    expect(agentTmpLaunch('claude', undefined, deps(data, { config: () => { throw new Error('unreadable') } }))).toEqual(none)
  })

  it('is a root for what agents drop wherever agents are given it, never on Windows', () => {
    const data = scratch()
    expect(agentTmpRoot(deps(data))).toBe(agentTmpFolder(data))
    expect(agentTmpRoot(deps(data, { config: () => null }))).toBe(agentTmpFolder(data))
    expect(agentTmpRoot(deps(data, { platform: 'win32' }))).toBeNull()
  })
})

describe('the folder itself', () => {
  it('closes a folder someone left open', () => {
    const folder = join(scratch(), 'agent-tmp')
    mkdirSync(folder, { mode: 0o777 })
    chmodSync(folder, 0o777)
    expect(prepareAgentTmp(folder)).toBe(true)
    expect(statSync(folder).mode & 0o777).toBe(0o700)
  })

  it('refuses a link in its place, and the agent falls back to the system\'s folder with nothing added, saying so', () => {
    const data = scratch(), elsewhere = scratch()
    symlinkSync(elsewhere, agentTmpFolder(data))
    const d = deps(data)
    expect(agentTmpLaunch('claude', undefined, d)).toEqual(none)
    expect(agentTmpLaunch('claude', { role: 'agent', key: 'one' }, d)).toEqual(none)
    expect(d.log).toHaveBeenCalledWith(expect.stringContaining('private temporary folder'))
    chmodSync(elsewhere, 0o755)
    expect(statSync(elsewhere).mode & 0o777).toBe(0o755)
  })

  it('refuses a folder another account owns', () => {
    const folder = join(scratch(), 'agent-tmp')
    mkdirSync(folder, { mode: 0o700 })
    expect(prepareAgentTmp(folder, 99_999)).toBe(false)
  })

  it('refuses a file in its place', () => {
    const folder = join(scratch(), 'agent-tmp')
    writeFileSync(folder, 'x')
    expect(prepareAgentTmp(folder)).toBe(false)
  })

  it('reports its state for harness team status', () => {
    const data = scratch(), folder = agentTmpFolder(data)
    expect(agentTmpState(folder)).toEqual({ path: folder, state: 'not-made', mode: null })
    mkdirSync(folder, { mode: 0o700 })
    chmodSync(folder, 0o700)
    expect(agentTmpState(folder)).toEqual({ path: folder, state: 'private', mode: 0o700 })
    // Another account's 0700 folder is not this account's private one.
    expect(agentTmpState(folder, 99_999)).toEqual({ path: folder, state: 'open', mode: 0o700 })
    chmodSync(folder, 0o755)
    expect(agentTmpState(folder)).toEqual({ path: folder, state: 'open', mode: 0o755 })
    rmSync(folder, { recursive: true })
    symlinkSync(scratch(), folder)
    expect(agentTmpState(folder)).toEqual({ path: folder, state: 'open', mode: null })
  })
})

describe('what deletes it', () => {
  const DAY = 24 * 60 * 60_000
  const NOW = Date.now()
  // ctime cannot be set, so an idle file is one the sweep sees from 8 days on, and a recent one has its mtime set to that day.
  const LATER = NOW + 8 * DAY
  const recentThen = (path: string) => { const at = new Date(LATER); utimesSync(path, at, at) }

  it('deletes what nothing has changed in for 7 days, and keeps anything with a recent file inside', async () => {
    const folder = scratch()
    writeFileSync(join(folder, 'stale.log'), 'x')
    mkdirSync(join(folder, 'stale-dir/inner'), { recursive: true })
    writeFileSync(join(folder, 'stale-dir/inner/a'), 'x')
    writeFileSync(join(folder, 'fresh.log'), 'x'); recentThen(join(folder, 'fresh.log'))
    mkdirSync(join(folder, 'in-use/inner'), { recursive: true })
    writeFileSync(join(folder, 'in-use/inner/recent'), 'x'); recentThen(join(folder, 'in-use/inner/recent'))
    expect(await sweepAgentTmp(folder, LATER)).toBe(2)
    expect(existsSync(join(folder, 'stale.log'))).toBe(false)
    expect(existsSync(join(folder, 'stale-dir'))).toBe(false)
    expect(existsSync(join(folder, 'fresh.log'))).toBe(true)
    expect(existsSync(join(folder, 'in-use/inner/recent'))).toBe(true)
  })

  it('keeps what was just unpacked with an old mtime, as tar, cp -p and rsync -t leave it', async () => {
    const folder = scratch()
    mkdirSync(join(folder, 'tool'))
    writeFileSync(join(folder, 'tool/bin'), 'x')
    writeFileSync(join(folder, 'loose'), 'x')
    const long = new Date(NOW - 400 * DAY)
    for (const path of ['tool/bin', 'tool', 'loose']) utimesSync(join(folder, path), long, long)
    expect(await sweepAgentTmp(folder, NOW)).toBe(0)
    expect(existsSync(join(folder, 'tool/bin'))).toBe(true)
    expect(existsSync(join(folder, 'loose'))).toBe(true)
  })

  it('deletes a link, never what it points at', async () => {
    const folder = scratch(), target = scratch()
    writeFileSync(join(target, 'kept'), 'x')
    symlinkSync(target, join(folder, 'link'))
    expect(await sweepAgentTmp(folder, LATER)).toBe(1)
    expect(existsSync(join(folder, 'link'))).toBe(false)
    expect(existsSync(join(target, 'kept'))).toBe(true)
  })

  it('deletes nothing through a link in the folder\'s place', async () => {
    const target = scratch(), folder = join(scratch(), 'agent-tmp')
    writeFileSync(join(target, 'kept'), 'x')
    symlinkSync(target, folder)
    expect(await sweepAgentTmp(folder, LATER)).toBe(0)
    expect(existsSync(join(target, 'kept'))).toBe(true)
  })

  it('still sweeps once the Team account is gone', async () => {
    const data = scratch(), folder = agentTmpFolder(data)
    mkdirSync(folder, { mode: 0o700 })
    writeFileSync(join(folder, 'stale'), 'x')
    expect(agentTmpLaunch('claude', undefined, deps(data, { config: () => null, now: () => LATER }))).toEqual(none)
    await vi.waitFor(() => expect(existsSync(join(folder, 'stale'))).toBe(false))
  })

  // Task #4395: each agent's folder is its TMPDIR while it runs, however quiet, as a Buddy's is: what is in it goes after 7
  // days, the folder itself only once it has been empty for 30.
  it('keeps a quiet agent\'s own folder, sweeping what is in it', async () => {
    const data = scratch()
    const mine = agentTmpLaunch('claude', { role: 'agent', key: 'one' }, deps(data, { config: () => null })).env.TMPDIR!
    writeFileSync(join(mine, 'stale'), 'x')
    await sweepTmpFolders(agentTmpFolder(data), Date.now() + 8 * DAY)
    expect(existsSync(join(mine, 'stale'))).toBe(false)
    expect(existsSync(mine)).toBe(true)
    await sweepTmpFolders(agentTmpFolder(data), Date.now() + 31 * DAY)
    expect(existsSync(mine)).toBe(false)
    // Its next launch makes it again.
    expect(agentTmpLaunch('claude', { role: 'agent', key: 'one' }, deps(data, { config: () => null })).env.TMPDIR).toBe(mine)
    expect(existsSync(mine)).toBe(true)
  })

  it('sweeps from a launch at most once a day', async () => {
    const data = scratch(), folder = agentTmpFolder(data)
    let now = LATER - DAY - 1
    const d = deps(data, { now: () => now })
    agentTmpLaunch('claude', undefined, d)
    writeFileSync(join(folder, 'stale'), 'x')
    // The day's sweep already ran: this launch starts none, though the file's 7 days are nearly up.
    now = LATER - DAY / 2
    agentTmpLaunch('claude', undefined, d)
    await new Promise(resolve => setTimeout(resolve, 50))
    expect(existsSync(join(folder, 'stale'))).toBe(true)
    now = LATER
    agentTmpLaunch('claude', undefined, d)
    await vi.waitFor(() => expect(existsSync(join(folder, 'stale'))).toBe(false))
  })

  it('a sweep of a folder that cannot be read deletes nothing and does not throw', async () => {
    expect(await sweepAgentTmp(join(scratch(), 'missing'), NOW)).toBe(0)
  })
})

describe('a Buddy\'s private temporary folder', () => {
  const DAY = 24 * 60 * 60_000
  /** A data folder in a scratch folder of its own, so the sibling `-buddy-tmp` is cleaned with it. */
  const dataIn = () => join(scratch(), 'data')

  it('is a 0700 folder under a 0700 parent, for Claude Code\'s own files too, outside the data folder', () => {
    const data = dataIn()
    const env = buddyTmpEnv('claude', '/work/one', deps(data))
    expect(env).toEqual({ TMPDIR: buddyTmpFolder('/work/one', data), CLAUDE_CODE_TMPDIR: buddyTmpFolder('/work/one', data) })
    expect(statSync(env.TMPDIR!).mode & 0o777).toBe(0o700)
    expect(statSync(buddyTmpParent(data)).mode & 0o777).toBe(0o700)
    expect(statSync(env.TMPDIR!).uid).toBe(process.geteuid!())
    expect(env.TMPDIR!.startsWith(`${data}/`)).toBe(false)
  })

  it('is one per Buddy, and stays the same across a relaunch', () => {
    const data = dataIn()
    expect(buddyTmpFolder('/work/one', data)).not.toBe(buddyTmpFolder('/work/two', data))
    expect(buddyTmpOf('/work/one', deps(data))).toBe(buddyTmpOf('/work/one', deps(data)))
  })

  it('gives another engine TMPDIR alone', () => {
    const data = dataIn()
    expect(buddyTmpEnv('codex', '/work/one', deps(data))).toEqual({ TMPDIR: buddyTmpFolder('/work/one', data) })
  })

  it('is only for the owner\'s account on a computer with a Team account, on macOS and Linux', () => {
    const data = dataIn()
    expect(buddyTmpEnv('claude', '/work/one', deps(data, { config: () => null }))).toEqual({})
    expect(buddyTmpEnv('claude', '/work/one', deps(data, { user: () => 'harnessteam' }))).toEqual({})
    expect(buddyTmpEnv('claude', '/work/one', deps(data, { platform: 'win32' }))).toEqual({})
    expect(buddyTmpOf('/work/one', deps(data, { config: () => null }))).toBeNull()
    expect(existsSync(buddyTmpParent(data))).toBe(false)
  })

  // Not yet run in Linux's sandbox (bubblewrap): a folder it would not open breaks every command of a Buddy (review of #2563).
  it('leaves Linux on the system\'s folder until the sandbox has been tried there', () => {
    const data = dataIn()
    expect(buddyTmpEnv('claude', '/work/one', deps(data, { platform: 'linux' }))).toEqual({})
    expect(buddyTmpOf('/work/one', deps(data, { platform: 'linux' }))).toBeNull()
    expect(existsSync(buddyTmpParent(data))).toBe(false)
  })

  it('names the folder by its real path when the data folder is reached through a link, as the guard compares real paths', () => {
    const at = scratch(), real = join(at, 'real'), data = join(at, 'data')
    mkdirSync(real); symlinkSync(real, data)
    expect(buddyTmpOf('/work/one', deps(data))).toBe(join(`${data}-buddy-tmp`, buddyTmpFolder('/work/one', data).split('/').at(-1)!))
    const linked = join(scratch(), 'link'), parentReal = scratch()
    symlinkSync(scratch(), linked)
    const nested = join(parentReal, 'real-data'), viaLink = join(scratch(), 'via')
    mkdirSync(nested); symlinkSync(parentReal, viaLink)
    expect(buddyTmpOf('/work/one', deps(join(viaLink, 'real-data')))).toBe(join(`${nested}-buddy-tmp`, buddyTmpFolder('/work/one', nested).split('/').at(-1)!))
  })

  it('closes a folder someone left open, and a parent too', () => {
    const data = dataIn(), folder = buddyTmpFolder('/work/one', data)
    mkdirSync(folder, { recursive: true, mode: 0o777 })
    chmodSync(folder, 0o777); chmodSync(buddyTmpParent(data), 0o777)
    expect(buddyTmpOf('/work/one', deps(data))).toBe(folder)
    expect(statSync(folder).mode & 0o777).toBe(0o700)
    expect(statSync(buddyTmpParent(data)).mode & 0o777).toBe(0o700)
  })

  it.each(['the folder', 'the parent'])('refuses a link in place of %s, and the Buddy keeps the system\'s folder, saying so', (which) => {
    const data = dataIn(), elsewhere = scratch(), folder = buddyTmpFolder('/work/one', data)
    if (which === 'the folder') { mkdirSync(buddyTmpParent(data), { recursive: true, mode: 0o700 }); symlinkSync(elsewhere, folder) } else { mkdirSync(data, { recursive: true }); symlinkSync(elsewhere, buddyTmpParent(data)) }
    chmodSync(elsewhere, 0o755)
    const d = deps(data)
    expect(buddyTmpOf('/work/one', d)).toBeNull()
    expect(buddyTmpEnv('claude', '/work/one', d)).toEqual({})
    expect(d.log).toHaveBeenCalledWith(expect.stringContaining('private temporary folder'))
    expect(statSync(elsewhere).mode & 0o777).toBe(0o755)
  })

  it('deletes what nothing has changed in for 7 days inside each Buddy\'s folder, keeping the folder a live Buddy has as its TMPDIR', async () => {
    const data = dataIn(), folder = buddyTmpOf('/work/one', deps(data))!
    writeFileSync(join(folder, 'stale'), 'x')
    const later = Date.now() + 8 * DAY
    writeFileSync(join(folder, 'fresh'), 'x'); utimesSync(join(folder, 'fresh'), new Date(later), new Date(later))
    expect(await sweepTmpFolders(buddyTmpParent(data), later)).toBe(1)
    expect(existsSync(join(folder, 'stale'))).toBe(false)
    expect(existsSync(join(folder, 'fresh'))).toBe(true)
    expect(existsSync(folder)).toBe(true)
  })

  it('removes a Buddy\'s folder only when empty and idle for 30 days', async () => {
    const data = dataIn(), folder = buddyTmpOf('/work/one', deps(data))!
    await sweepTmpFolders(buddyTmpParent(data), Date.now() + 8 * DAY)
    expect(existsSync(folder)).toBe(true)
    await sweepTmpFolders(buddyTmpParent(data), Date.now() + 31 * DAY)
    expect(existsSync(folder)).toBe(false)
  })

  it('sweeps nothing through a link, in the parent\'s place or among the Buddies\' folders', async () => {
    const data = dataIn(), target = scratch()
    writeFileSync(join(target, 'kept'), 'x')
    mkdirSync(buddyTmpParent(data), { recursive: true, mode: 0o700 })
    symlinkSync(target, join(buddyTmpParent(data), 'link'))
    await sweepTmpFolders(buddyTmpParent(data), Date.now() + 40 * DAY)
    expect(existsSync(join(target, 'kept'))).toBe(true)
    const other = join(scratch(), 'parent')
    symlinkSync(target, other)
    expect(await sweepTmpFolders(other, Date.now() + 40 * DAY)).toBe(0)
    expect(existsSync(join(target, 'kept'))).toBe(true)
  })

  it('is swept by a launch, with the Team account gone too', async () => {
    const data = dataIn(), folder = buddyTmpOf('/work/one', deps(data))!
    writeFileSync(join(folder, 'stale'), 'x')
    resetAgentTmpSweep()
    agentTmpLaunch('claude', undefined, deps(data, { config: () => null, now: () => Date.now() + 8 * DAY }))
    await vi.waitFor(() => expect(existsSync(join(folder, 'stale'))).toBe(false))
  })
})

describe('a script written to the folder runs as it would in the system\'s', () => {
  // The data folder is under ~/.harness/cli, whose package.json says "type": "module". An extensionless script a spec wrote
  // to TMPDIR (the fake grid) loaded as an ES module and died on require, so specs failed for agents and passed in CI (#4356).
  const DAY = 24 * 60 * 60_000
  const inModulePackage = () => { const root = scratch(); writeFileSync(join(root, 'package.json'), '{"type":"module"}'); return join(root, 'data') }
  const runs = (folder: string) => {
    const script = join(folder, 'fake-grid')
    writeFileSync(script, "#!/usr/bin/env node\nconst { join } = require('node:path')\nprocess.stdout.write(join('a', 'b'))\n")
    return execFileSync(process.execPath, [script], { encoding: 'utf8' })
  }

  it('an extensionless require() script in an agent\'s folder runs', () => {
    expect(runs(agentTmpLaunch('claude', undefined, deps(inModulePackage())).env.TMPDIR!)).toBe(join('a', 'b'))
  })

  // Task #4395: each Swarm agent's own folder is in the shared parent, whose marker covers it.
  it('in a Swarm agent\'s own folder too, by the marker in their parent', () => {
    const data = inModulePackage()
    const folder = agentTmpLaunch('claude', { role: 'agent', key: 'one' }, deps(data, { config: () => null })).env.TMPDIR!
    expect(runs(folder)).toBe(join('a', 'b'))
    expect(existsSync(join(folder, 'package.json'))).toBe(false)
    expect(existsSync(join(agentTmpFolder(data), 'package.json'))).toBe(true)
  })

  it('in a Buddy\'s folder too', () => {
    expect(runs(buddyTmpOf('/work/one', deps(inModulePackage()))!)).toBe(join('a', 'b'))
  })

  it('keeps a package.json already there', () => {
    const data = inModulePackage(), folder = agentTmpFolder(data)
    mkdirSync(folder, { recursive: true, mode: 0o700 })
    writeFileSync(join(folder, 'package.json'), '{"type":"commonjs","name":"kept"}')
    agentTmpLaunch('claude', undefined, deps(data))
    expect(readFileSync(join(folder, 'package.json'), 'utf8')).toContain('kept')
  })

  it('no sweep deletes the folders\' own package.json however old; a tool\'s goes like any file', async () => {
    const data = inModulePackage(), folder = agentTmpFolder(data), parent = buddyTmpParent(data)
    agentTmpLaunch('claude', undefined, deps(data))
    const buddy = buddyTmpOf('/work/one', deps(data))!
    writeFileSync(join(buddy, 'package.json'), '{"type":"module"}')
    const later = Date.now() + 8 * DAY
    expect(await sweepTmpFolders(folder, later)).toBe(0)
    expect(await sweepTmpFolders(parent, later)).toBe(1)
    expect(existsSync(join(folder, 'package.json'))).toBe(true)
    expect(existsSync(join(parent, 'package.json'))).toBe(true)
    expect(existsSync(join(buddy, 'package.json'))).toBe(false)
  })
})