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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* The agents' private temporary folders. Each Swarm agent has its own (task #4395): since #4215 an agent starts in its owner's
* own settings, which can block reads outside the working directories, so its folder is added to the engine's working
* directories as well as given as its TMPDIR, which `mktemp` uses. A person's own session gets the shared folder, beside a
* Harness Team account only (audit M1, docs/plans/2026-11-02-team-private-temp-and-status-plan.md).
*
* The daemon runs with no TMPDIR on a Mac (launchd sets none here), so agents and their tools wrote to /private/tmp, which
* every account shares: on the Mac Studio the Team account could read 654 of the owner's entries there, and could create a
* file at a name an owner's agent later wrote to or ran. A 0700 folder closes both for whatever honours TMPDIR, and the
* Swarm's skills tell agents not to name /tmp themselves.
*
* In the data folder because a wide Buddy's guard already closes that folder (lib/buddyGuard.ts), so a Buddy cannot read other
* agents' temporary files here. A Buddy has its own folder beside the data folder, one per Buddy, since its files come from a
* person's private work and must not reach another person's Buddy (buddyTmpOf; docs/plans/2026-11-02-buddy-private-temp-plan.md).
*/
import { createHash } from 'node:crypto'
import { chmodSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
import { lstat, readdir, rm, rmdir } from 'node:fs/promises'
import { userInfo } from 'node:os'
import { basename, dirname, join } from 'node:path'
import { env } from '../config/env.js'
import { isTerminalEngine, type AgentEngine } from '../engines/types.js'
import { readTeamConfig, type TeamConfig } from '../team/config.js'
import type { SwarmSkill } from './savedSkill.js'
/** Nothing changed in this long, and a top-level entry is deleted: longer than a task runs, as /tmp's own cleaners are. */
const KEEP_MS = 7 * 24 * 60 * 60_000
const SWEEP_EVERY_MS = 24 * 60 * 60_000
/** A Buddy's empty folder is kept this long: it is a live Buddy's TMPDIR while the Buddy runs, however quiet. */
const KEEP_EMPTY_BUDDY_MS = 30 * 24 * 60 * 60_000
/** These folders are under ~/.harness/cli, whose package.json says "type": "module": without one of their own, an extensionless
* script written here (a spec's fake grid) loaded as an ES module and died on require, as it never does in the system's (#4356). */
const PACKAGE = 'package.json'
const COMMONJS = '{"type":"commonjs"}\n'
export interface AgentTmpDeps {
platform: NodeJS.Platform
dataDir: string
config(): TeamConfig | null
/** The account this process runs as. */
user(): string
log(line: string): void
now(): number
}
const realDeps: AgentTmpDeps = {
platform: process.platform, dataDir: env.ADAPTER_DATA_DIR, config: () => readTeamConfig(), user: () => userInfo().username,
log: (line) => console.log(`[agent-tmp] ${line}`), now: () => Date.now(),
}
export const agentTmpFolder = (dataDir: string = env.ADAPTER_DATA_DIR): string => join(dataDir, 'agent-tmp')
/** Where every Buddy's folder is: beside the data folder, which a wide Buddy's guard and sandbox close whole. */
export const buddyTmpParent = (dataDir: string = env.ADAPTER_DATA_DIR): string => `${dataDir}-buddy-tmp`
/** The folder of the Buddy that runs in [root], by its real path, so a relaunch finds it. Short: some tools make sockets in TMPDIR. */
export function buddyTmpFolder(root: string, dataDir: string = env.ADAPTER_DATA_DIR): string {
return join(buddyTmpParent(dataDir), createHash('sha256').update(realOfFolder(root)).digest('hex').slice(0, 16))
}
/** [path]'s real path: of the nearest folder that exists, with the rest added, so a Buddy's folder removed before its cleanup
* still names the same temporary folder. */
export function realOfFolder(path: string): string {
let at = path, rest = ''
for (;;) {
try { return join(realpathSync(at), rest) } catch { /* not there: its folder decides */ }
if (dirname(at) === at) return path
rest = join(basename(at), rest)
at = dirname(at)
}
}
/** This account is the owner of a computer with a Team account. Windows' temporary folder is already the account's own. */
function ownerOfTeamComputer(deps: AgentTmpDeps): boolean {
if (deps.platform === 'win32') return false
try {
const config = deps.config()
return !!config && config.user !== deps.user()
} catch { return false }
}
/** Makes [folder] this account's alone. False when it is not: a link, a file, or another account's, which is left as it is. */
export function prepareAgentTmp(folder: string, uid: number | undefined = process.geteuid?.()): boolean {
try {
mkdirSync(folder, { recursive: true, mode: 0o700 })
const stat = lstatSync(folder)
if (!stat.isDirectory() || stat.isSymbolicLink() || (uid !== undefined && stat.uid !== uid)) return false
if ((stat.mode & 0o777) !== 0o700) chmodSync(folder, 0o700)
return true
} catch { return false }
}
/** Gives [folder] its own CommonJS package.json, keeping one already there. Exclusive create: a link in its place is not followed. */
function markCommonJs(folder: string, deps: AgentTmpDeps): void {
try { writeFileSync(join(folder, PACKAGE), COMMONJS, { flag: 'wx', mode: 0o600 }) } catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
deps.log(`could not write ${join(folder, PACKAGE)} (${(error as NodeJS.ErrnoException).code}); scripts there load as ES modules`)
}
}
}
/** The package.json markCommonJs wrote, which no sweep deletes however old. Another, a tool's, is swept like any file. */
function isMarker(folder: string, name: string): boolean {
if (name !== PACKAGE) return false
try { return readFileSync(join(folder, name), 'utf8') === COMMONJS } catch { return false }
}
/** Whether anything at [path] changed since [cutoff]. Stops at the first that did. What cannot be read counts as changed. The
* newer of the two times: `tar`, `cp -p` and `rsync -t` keep an old mtime, so a tool unpacked a minute ago looked 7 days idle
* by mtime alone (review of #2546). */
async function changedSince(path: string, cutoff: number): Promise<boolean> {
try {
const stat = await lstat(path)
if (Math.max(stat.mtimeMs, stat.ctimeMs) >= cutoff) return true
if (!stat.isDirectory()) return false
for (const name of await readdir(path)) if (await changedSince(join(path, name), cutoff)) return true
return false
} catch { return true }
}
/** Deletes the top-level entries of [folder] with nothing changed for 7 days, and says how many went. A link goes, never what
* it points at (`rm` does not follow one). Only ever this folder: /tmp is not touched. */
export async function sweepAgentTmp(folder: string, now: number): Promise<number> {
let names: string[]
try {
// Never through a link in its place, which would delete what it points at, or in a folder that is not this account's.
const stat = await lstat(folder)
if (!stat.isDirectory() || stat.uid !== process.geteuid?.()) return 0
names = await readdir(folder)
} catch { return 0 }
let removed = 0
for (const name of names) {
const path = join(folder, name)
if (isMarker(folder, name) || await changedSince(path, now - KEEP_MS)) continue
try { await rm(path, { recursive: true, force: true }); removed++ } catch { /* the next sweep tries again */ }
}
return removed
}
/** Each folder in [parent], each Buddy's or agent's, swept as `sweepAgentTmp` sweeps one. The folder stays, as it is a live
* Buddy's or agent's TMPDIR, until it has been empty and idle for 30 days; a relaunch makes it again. Anything else at the top
* goes when idle, a link without what it points at. */
export async function sweepTmpFolders(parent: string, now: number): Promise<number> {
let names: string[]
try {
const stat = await lstat(parent)
if (!stat.isDirectory() || stat.uid !== process.geteuid?.()) return 0
names = await readdir(parent)
} catch { return 0 }
let removed = 0
for (const name of names) {
const path = join(parent, name)
try {
if (!(await lstat(path)).isDirectory()) {
if (!isMarker(parent, name) && !(await changedSince(path, now - KEEP_MS))) { await rm(path, { force: true }); removed++ }
continue
}
removed += await sweepAgentTmp(path, now)
// Fails, as it should, on a folder with anything in it.
if (!(await changedSince(path, now - KEEP_EMPTY_BUDDY_MS))) await rmdir(path)
} catch { /* not empty, or gone: the next sweep looks again */ }
}
return removed
}
let lastSweep: number | null = null
export function resetAgentTmpSweep(): void { lastSweep = null }
function sweepWhenDue(folder: string, deps: AgentTmpDeps): void {
const now = deps.now()
if (lastSweep !== null && now >= lastSweep && now - lastSweep < SWEEP_EVERY_MS) return
lastSweep = now
// Never in the launch's way: an agent's start does not wait on a walk of old files.
void Promise.all([sweepTmpFolders(folder, now), sweepTmpFolders(buddyTmpParent(deps.dataDir), now)])
.then(([agents, buddies]) => { if (agents + buddies) deps.log(`removed ${agents + buddies} entries nothing had changed in for 7 days`) })
}
/** How an engine is told of one more working directory, joined to its flag: Claude Code's `--add-dir` takes several values and
* would otherwise swallow what follows it. An engine not here gets the folder as its TMPDIR alone. */
const ADDED_FOLDER: Partial<Record<AgentEngine, (folder: string) => string[]>> = {
claude: folder => [`--add-dir=${folder}`],
codex: folder => [`--add-dir=${folder}`],
}
/** The private folder of the Swarm agent whose creation key is [key], made and closed, by its real path, or null when it cannot
* be, which the log says. Named by the key, which every relaunch carries, so a relaunch finds it; never by the workspace, as a
* person's Regular agents all start in that person's home folder. Claude Code reads an added folder's own skills and settings,
* so a folder two agents shared would let one plant them for the other. */
export function agentTmpOf(key: string, deps: AgentTmpDeps = realDeps): string | null {
const parent = agentTmpFolder(deps.dataDir)
const folder = join(parent, createHash('sha256').update(key).digest('hex').slice(0, 16))
// The parent first: making the folder through a link in the parent's place would make it where that link points.
// The marker in the parent covers every agent's folder, which stays free to empty out and go (#4356).
try {
if (prepareAgentTmp(parent) && prepareAgentTmp(folder)) {
markCommonJs(parent, deps)
return realpathSync(folder)
}
} catch { /* said below */ }
deps.log(`the private temporary folder ${folder} could not be made private; this agent uses the system's`)
return null
}
/**
* What gives an agent its private folder: the variables, and the arguments that add the folder to the engine's working
* directories, or none. A Swarm agent (not a Buddy, which has its own) gets its own folder, both. A person's own session
* gets the shared folder as TMPDIR beside a Team account only, as before. A folder that cannot be made private does not stop
* the agent: it starts on the system's folder, the daemon's log says why, and `harness team status` shows ✗.
*/
export function agentTmpLaunch(engine: AgentEngine, skill: Pick<SwarmSkill, 'role' | 'key'> | undefined,
deps: AgentTmpDeps = realDeps): { env: Record<string, string>; args: string[] } {
const none = { env: {}, args: [] }
if (deps.platform === 'win32') return none
const shared = agentTmpFolder(deps.dataDir)
// Whoever launches, and with the Team account gone too: what is left here must still go.
sweepWhenDue(shared, deps)
if (isTerminalEngine(engine) || skill?.role === 'buddy') return none
if (skill) {
const folder = agentTmpOf(skill.key, deps)
return folder ? { env: { TMPDIR: folder }, args: ADDED_FOLDER[engine]?.(folder) ?? [] } : none
}
if (!ownerOfTeamComputer(deps)) return none
if (!prepareAgentTmp(shared)) {
deps.log(`the private temporary folder ${shared} could not be made private; this agent uses the system's`)
return none
}
markCommonJs(shared, deps)
return { env: { TMPDIR: shared }, args: [] }
}
/**
* The private folder of the Buddy that runs in [root], made and closed, or null: on a computer with no Team account, in the
* Team account itself, on Windows or Linux, or when it cannot be made private, which the log says. Null opens nothing in its guard.
*/
export function buddyTmpOf(root: string, deps: AgentTmpDeps = realDeps): string | null {
if (deps.platform === 'win32') return null
sweepWhenDue(agentTmpFolder(deps.dataDir), deps)
// macOS alone until the sandbox has been tried with bubblewrap: a folder it would not open breaks every command of a Buddy.
if (deps.platform !== 'darwin' || !ownerOfTeamComputer(deps)) return null
const folder = buddyTmpFolder(root, deps.dataDir)
// The parent first: making the folder through a link in the parent's place would make it where that link points.
// By its real path, as the guard compares real paths: a data folder reached through a link would refuse its own reads.
// The marker in the parent covers every Buddy's folder, which stays free to empty out and go.
try {
if (prepareAgentTmp(buddyTmpParent(deps.dataDir)) && prepareAgentTmp(folder)) {
markCommonJs(buddyTmpParent(deps.dataDir), deps)
return realpathSync(folder)
}
} catch { /* said below */ }
deps.log(`the private temporary folder ${folder} could not be made private; this Buddy uses the system's`)
return null
}
/** A Buddy's launch variables for that folder. Claude Code keeps its own files in /tmp/claude-<uid> whatever TMPDIR says. */
export function buddyTmpEnv(engine: AgentEngine, root: string, deps: AgentTmpDeps = realDeps): Record<string, string> {
const folder = buddyTmpOf(root, deps)
return folder ? { TMPDIR: folder, ...(engine === 'claude' ? { CLAUDE_CODE_TMPDIR: folder } : {}) } : {}
}
/** The folder agents here are given (every Swarm agent's is in it): a place they drop files that a person may then open
* (./pathContainment.ts). None on Windows, whose temporary folder is the account's own. */
export function agentTmpRoot(deps: AgentTmpDeps = realDeps): string | null {
return deps.platform === 'win32' ? null : agentTmpFolder(deps.dataDir)
}
export interface AgentTmpState { path: string; state: 'private' | 'open' | 'not-made'; mode: number | null }
/** What `harness team status` shows. A link, or another account's folder, is open whatever its mode says. */
export function agentTmpState(folder: string = agentTmpFolder(), uid: number | undefined = process.geteuid?.()): AgentTmpState {
try {
const stat = lstatSync(folder)
if (!stat.isDirectory()) return { path: folder, state: 'open', mode: null }
const mode = stat.mode & 0o777
// Another account's 0700 folder is private from this one, not for it (prepareAgentTmp refuses it).
if (uid !== undefined && stat.uid !== uid) return { path: folder, state: 'open', mode }
return { path: folder, state: mode === 0o700 ? 'private' : 'open', mode }
} catch (error) {
return { path: folder, state: (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'not-made' : 'open', mode: null }
}
}