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.

Agents never stop on Claude's folder-trust question (#3341)

harness-for-autonomous[bot]acbcf853e68f
diff --git a/cli/src/superTabs/agentFolder.spec.ts b/cli/src/superTabs/agentFolder.spec.ts
new file mode 100644
index 000000000..b0a39b953
--- /dev/null
+++ b/cli/src/superTabs/agentFolder.spec.ts
@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { worktreeFolderName } from '../lib/agentNames.js'
+import { AGENT_FOLDER_MARK, AGENT_FOLDERS, agentFolderFor, prepareAgentFolder, removableAgentFolder, temporaryFolder } from './agentFolder.js'
+
+const made: string[] = []
+afterEach(() => { for (const dir of made.splice(0)) rmSync(dir, { recursive: true, force: true }) })
+const temp = (prefix: string) => { const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix))); made.push(dir); return dir }
+
+// Scholes, 11-06 (#3713): project computer's agent Dee started in a Claude scratchpad, a temporary folder Claude asks
+// "Do you trust this folder?" about on every run, in a terminal no Swarm view shows.
+describe('a temporary folder', () => {
+ it('is one under the system temporary folders, as written or resolved', () => {
+ for (const path of ['/tmp/x', '/private/tmp/claude-501/-Users-mac/abc/scratchpad', '/var/tmp/a', '/var/folders/ab/xy/T/x',
+ '/private/var/folders/ab/xy/T/x', join(tmpdir(), 'x')]) expect(temporaryFolder(path), path).toBe(true)
+ })
+
+ it('is not a project, the person\'s own folder, or a folder only named like one', () => {
+ for (const path of ['/Users/me/work', '/tmp-not/x', '/Users/me/tmp/x', '/home/me/harnesses/worktrees/repo/leaf', 'relative/tmp', '/tmp'])
+ expect(temporaryFolder(path), path).toBe(false)
+ })
+})
+
+describe('the folder Harness makes for an agent whose start named a temporary one', () => {
+ it('is named for its start, in Harness\'s own agent-home folder', () => {
+ expect(agentFolderFor('/root', 's1')).toBe(join('/root', 'worktrees', AGENT_FOLDERS, worktreeFolderName('super-tab/s1')))
+ })
+
+ it('is made private, marked as Harness\'s, and trusted alone in Claude\'s settings', async () => {
+ const root = temp('agent-root-'), claude = temp('agent-claude-')
+ // Claude Code writes .claude.json on its first run; a machine that ran it has one (kit/folderTrust.ts leaves none made).
+ writeFileSync(join(claude, '.claude.json'), '{}')
+ const folder = agentFolderFor(root, 's1')
+ await prepareAgentFolder(folder, 'claude', { HOME: root, CLAUDE_CONFIG_DIR: claude })
+ expect(statSync(folder).mode & 0o777).toBe(0o700)
+ expect(existsSync(join(folder, AGENT_FOLDER_MARK))).toBe(true)
+ const projects = JSON.parse(readFileSync(join(claude, '.claude.json'), 'utf8')).projects as Record<string, { hasTrustDialogAccepted?: boolean }>
+ expect(Object.keys(projects)).toEqual([folder])
+ expect(projects[folder].hasTrustDialogAccepted).toBe(true)
+ })
+
+ // Security review of #3341 (Readycheck): a folder or link already at that path was marked and trusted, and a link wrote
+ // the mark outside. Only a folder Harness made, or one it made and marked before, is ever used.
+ it('refuses a link or an unmarked folder already where it would go, and writes nothing through it', async () => {
+ const root = temp('agent-root-'), outside = temp('agent-outside-'), claude = temp('agent-claude-')
+ writeFileSync(join(claude, '.claude.json'), '{}')
+ const env = { HOME: root, CLAUDE_CONFIG_DIR: claude }
+ const linked = agentFolderFor(root, 'linked')
+ mkdirSync(join(linked, '..'), { recursive: true })
+ symlinkSync(outside, linked)
+ await expect(prepareAgentFolder(linked, 'claude', env)).rejects.toThrow()
+ expect(existsSync(join(outside, AGENT_FOLDER_MARK))).toBe(false)
+ const planted = agentFolderFor(root, 'planted')
+ mkdirSync(planted, { recursive: true })
+ await expect(prepareAgentFolder(planted, 'claude', env)).rejects.toThrow()
+ expect(existsSync(join(planted, AGENT_FOLDER_MARK))).toBe(false)
+ expect(readFileSync(join(claude, '.claude.json'), 'utf8')).toBe('{}')
+ // A link above it, in place of agent-home itself.
+ const other = temp('agent-root-')
+ mkdirSync(join(other, 'worktrees'), { recursive: true })
+ symlinkSync(outside, join(other, 'worktrees', AGENT_FOLDERS))
+ await expect(prepareAgentFolder(agentFolderFor(other, 'above'), 'claude', env)).rejects.toThrow()
+ // Its own folder, made and marked by an earlier try of the same start, is used again.
+ const again = agentFolderFor(root, 'again')
+ await prepareAgentFolder(again, 'claude', env)
+ await expect(prepareAgentFolder(again, 'claude', env)).resolves.toBeUndefined()
+ })
+
+ it('may be removed only when it is a marked folder directly in agent-home', async () => {
+ const root = temp('agent-root-')
+ const folder = agentFolderFor(root, 's2')
+ mkdirSync(folder, { recursive: true })
+ expect(removableAgentFolder(folder, root)).toBe(false)
+ writeFileSync(join(folder, AGENT_FOLDER_MARK), '')
+ expect(removableAgentFolder(folder, root)).toBe(true)
+ for (const other of [join(root, 'worktrees', AGENT_FOLDERS), join(root, 'worktrees', 'repo', 'leaf'), join(folder, 'inner'), '/tmp'])
+ expect(removableAgentFolder(other, root), other).toBe(false)
+ })
+})
diff --git a/cli/src/superTabs/agentFolder.ts b/cli/src/superTabs/agentFolder.ts
new file mode 100644
index 000000000..13c33bbf9
--- /dev/null
+++ b/cli/src/superTabs/agentFolder.ts
@@ -0,0 +1,77 @@
+/**
+ * A Swarm agent's own folder, made when its start names a temporary one (task #3713). Scholes, 11-06: project computer's
+ * agent Dee started in a Claude scratchpad, a folder under /private/tmp that Claude Code asks "Do you trust this folder?"
+ * about on every run, in a terminal no Swarm view shows, so the agent waited on nobody. The core trusts only a Git checkout
+ * or a Harness worktree (core/agents/create.ts `swarmFolder`), and a scratchpad is neither.
+ *
+ * As a Buddy's home (buddyHome.ts), the folder is Harness's, made for this start in its worktrees folder and marked as its,
+ * and trusted alone: never a parent, the home folder or a folder a person made. It goes when its agent stops, once nothing
+ * of the agent's work is left in it (machines.ts).
+ */
+import { lstatSync, mkdirSync, readdirSync, realpathSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, isAbsolute, join, normalize, sep } from 'node:path'
+import { folderTrust } from '../engines/launchPrep.js'
+import { launchEnvironment } from '../engines/kit/launchExecutable.js'
+import { worktreeFolderName } from '../lib/agentNames.js'
+
+/** The folder of agent folders, beside Buddy homes in Harness's worktrees folder. */
+export const AGENT_FOLDERS = 'agent-home'
+/** The file that says a folder is Harness's agent folder: only a marked one is ever removed. */
+export const AGENT_FOLDER_MARK = '.harness-agent-folder'
+
+const TEMPORARY_ROOTS = ['/tmp', '/private/tmp', '/var/tmp', '/private/var/tmp', '/var/folders', '/private/var/folders']
+
+/** Whether [path] is inside a temporary folder, as written or with its links resolved; a temporary root itself is not. */
+export function temporaryFolder(path: string, tmp: string = tmpdir()): boolean {
+ if (!isAbsolute(path)) return false
+ const roots = [...TEMPORARY_ROOTS, normalize(tmp)]
+ const inside = (candidate: string) => roots.some((root) => candidate !== root && candidate.startsWith(`${root.replace(/[\\/]+$/, '')}${sep}`))
+ let resolved = path
+ try { resolved = realpathSync(path) } catch { /* not there yet: as written */ }
+ return inside(normalize(path)) || inside(resolved)
+}
+
+/** The folder for [startId]'s agent: named for its start, as a Buddy's home is, never for anything a request names. */
+export function agentFolderFor(root: string, startId: string): string {
+ return join(root, 'worktrees', AGENT_FOLDERS, worktreeFolderName(`super-tab/${startId}`))
+}
+
+/**
+ * Makes [folder] private and marked as Harness's, and answers Claude Code's folder question for it alone. Only a folder this
+ * makes now, or one it made and marked for the same start before, is used: a link or an unmarked folder already there, or a
+ * link in place of agent-home, is refused before anything is written, so neither a mark nor a trust lands elsewhere (security
+ * review of #3341). Throws when it refuses; a failed trust write only leaves the question.
+ */
+export async function prepareAgentFolder(folder: string, engine: unknown, environment?: NodeJS.ProcessEnv): Promise<void> {
+ const home = dirname(folder), worktrees = dirname(home)
+ mkdirSync(worktrees, { recursive: true, mode: 0o700 })
+ try { mkdirSync(home, { mode: 0o700 }) } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
+ if (!realDirectory(home) || realpathSync(home) !== join(realpathSync(worktrees), basename(home))) throw new Error('the agent-home folder is not Harness\'s own')
+ let made = false
+ try { mkdirSync(folder, { mode: 0o700 }); made = true } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
+ if (!realDirectory(folder) || realpathSync(folder) !== join(realpathSync(home), basename(folder))) throw new Error('the agent folder is not one Harness made')
+ const mark = join(folder, AGENT_FOLDER_MARK)
+ if (made) writeFileSync(mark, 'A Swarm agent\'s folder, made by Harness; removed when the agent stops and nothing of its work is left.\n', { flag: 'wx', mode: 0o600 })
+ else if (!lstatSync(mark, { throwIfNoEntry: false })?.isFile()) throw new Error('the agent folder is not one Harness made')
+ if (engine !== 'claude') return
+ // The environment the launch reads its Claude home from (a CLAUDE_CONFIG_DIR its login shell sets), as a Buddy's home is.
+ try { folderTrust('claude', undefined, environment ?? await launchEnvironment() ?? undefined)?.record(folder) }
+ catch (error) { console.warn(`[super-tabs] could not answer the folder question for an agent: ${(error as Error).message}`) }
+}
+
+const realDirectory = (path: string): boolean => { const info = lstatSync(path, { throwIfNoEntry: false }); return !!info && info.isDirectory() && !info.isSymbolicLink() }
+
+/** Whether [folder] holds nothing but Harness's mark: an agent folder whose work is all gone, which a stop may remove. */
+export function agentFolderEmpty(folder: string): boolean {
+ try { const names = readdirSync(folder); return names.length === 1 && names[0] === AGENT_FOLDER_MARK } catch { return false }
+}
+
+/** Whether [path] is an agent folder Harness may remove: a real folder (no link) directly in its agent-home folder, marked. */
+export function removableAgentFolder(path: string, root: string): boolean {
+ try {
+ const home = realpathSync(join(root, 'worktrees', AGENT_FOLDERS))
+ const here = realpathSync(path)
+ return dirname(here) === home && lstatSync(path).isDirectory() && lstatSync(join(here, AGENT_FOLDER_MARK)).isFile()
+ } catch { return false }
+}
diff --git a/cli/src/superTabs/machines.spec.ts b/cli/src/superTabs/machines.spec.ts
index e355f2cbe..64c23e585 100644
--- a/cli/src/superTabs/machines.spec.ts
+++ b/cli/src/superTabs/machines.spec.ts
@@ -1,3 +1,4 @@
+import { AGENT_FOLDER_MARK, agentFolderFor } from './agentFolder.js'
import { RELAY_REASONS } from './relayHealth.js'
import { execFileSync } from 'node:child_process'
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
@@ -2190,6 +2191,56 @@ describe('removed machine cleanup', () => {
expect(readFileSync(join(m.ownWorktree, 'unpushed.txt'), 'utf8')).toBe('work')
})
+ // #3713: an agent whose start named a temporary folder ran in a folder Harness made for it (agentFolder.ts); its stop
+ // removes it, and only it: a folder of Harness's agent-home, with its mark, that no session works in.
+ describe('a stopped agent\'s own folder', () => {
+ const agentFolder = (m: ReturnType<typeof machine>, startId: string, marked = true) => {
+ const folder = agentFolderFor(join(m.home, 'harnesses'), startId)
+ mkdirSync(folder, { recursive: true })
+ writeFileSync(join(folder, 'notes.md'), 'the agent\'s work')
+ if (marked) writeFileSync(join(folder, AGENT_FOLDER_MARK), '')
+ return folder
+ }
+
+ // Security review of #3341 (Readycheck): a stop deleted the agent's work with its folder. Only an empty one goes.
+ it('keeps the folder, with its record, while it holds the agent\'s work', async () => {
+ const m = machine()
+ m.setLive([])
+ const folder = agentFolder(m, 'with-work')
+ addRecord(m, { tabId: 'tab', startId: 'with-work', harnessId: 'h-work', source: folder, path: folder, kind: 'agent-folder' })
+ await m.open().removeStoppedWorktree('tab', 'h-work')
+ expect(readFileSync(join(folder, 'notes.md'), 'utf8')).toBe('the agent\'s work')
+ expect(startIds(m)).toContain('with-work')
+ })
+
+ it('goes with its record once no session works in it and it holds nothing of the agent\'s', async () => {
+ const m = machine()
+ const folder = agentFolder(m, 'agent-start')
+ rmSync(join(folder, 'notes.md'))
+ addRecord(m, { tabId: 'tab', startId: 'agent-start', harnessId: 'h-agent', source: folder, path: folder, kind: 'agent-folder' })
+ m.setLive([session('h-agent', join(folder, 'sub'), 'agent')])
+ await m.open().removeStoppedWorktree('tab', 'h-agent')
+ expect(existsSync(folder)).toBe(true)
+ m.setLive([])
+ await m.open().removeStoppedWorktree('tab', 'h-agent')
+ expect(existsSync(folder)).toBe(false)
+ expect(startIds(m)).not.toContain('agent-start')
+ })
+
+ it('is kept, with its record, when it is not one Harness marked as an agent\'s, wherever its record says it is', async () => {
+ const m = machine()
+ m.setLive([])
+ const unmarked = agentFolder(m, 'unmarked', false)
+ addRecord(m, { tabId: 'tab', startId: 'unmarked', harnessId: 'h-unmarked', source: unmarked, path: unmarked, kind: 'agent-folder' })
+ addRecord(m, { tabId: 'tab', startId: 'own', harnessId: 'h-own', source: m.own, path: m.own, kind: 'agent-folder' })
+ await m.open().removeStoppedWorktree('tab', 'h-unmarked')
+ await m.open().removeStoppedWorktree('tab', 'h-own')
+ expect(readFileSync(join(unmarked, 'notes.md'), 'utf8')).toBe('the agent\'s work')
+ expect(existsSync(m.own)).toBe(true)
+ expect(startIds(m)).toEqual(expect.arrayContaining(['unmarked', 'own']))
+ })
+ })
+
// #2284: a folder whose .git proof disappeared is kept with its record and logged without its path.
it('keeps and logs a recorded worktree whose .git proof file is missing without exposing its path', async () => {
const m = machine()
diff --git a/cli/src/superTabs/machines.ts b/cli/src/superTabs/machines.ts
index 8716a70a5..072c720f6 100644
--- a/cli/src/superTabs/machines.ts
+++ b/cli/src/superTabs/machines.ts
@@ -1,6 +1,6 @@
import { createHash } from 'node:crypto'
import { spawn } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
import { homedir } from 'node:os'
import { lstat, readdir, readFile, realpath, rm, stat } from 'node:fs/promises'
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
@@ -20,6 +20,7 @@ import { readAuthSession } from '../lib/authSession.js'
import { createSwarmCloneTrustRepair, swarmCloneRoots } from './cloneTrust.js'
import { git, sweepOne, WorktreeKept } from '../lib/worktreeSweep.js'
import { projectsRoot } from '../lib/projectFolder.js'
+import { agentFolderEmpty, removableAgentFolder } from './agentFolder.js'
import { worktreeFolderName } from '../lib/agentNames.js'
import { teamPrivacyObserver } from '../team/observer.js'
import { teamRelayed } from '../team/relay.js'
@@ -80,7 +81,8 @@ const POOLS_FRESH_MS = 2_000
/** The worktrees this machine's Swarm starts made, by tab: what a removal may delete besides the tab's Swarm folders. */
export const swarmWorktreesFile = (dataDir: string, machineId: string) => join(dataDir, 'super-tabs', `swarm-worktrees-${machineId}.json`)
-type SwarmWorktree = { tabId: string; startId: string; harnessId: string; source: string; path: string }
+/** `kind: 'agent-folder'`: a folder Harness made for an agent whose start named a temporary one (agentFolder.ts, #3713). */
+type SwarmWorktree = { tabId: string; startId: string; harnessId: string; source: string; path: string; kind?: 'agent-folder' }
function readWorktrees(file: string): SwarmWorktree[] {
let saved: unknown
try { saved = JSON.parse(readFileSync(file, 'utf8')) } catch { return [] }
@@ -1133,6 +1135,7 @@ export class ContributedMachines {
// Diego, 10-30: a folder deleted by hand kept its record for good, and every later stop tried it again. Only a folder
// that is not there drops it; one that cannot be read for any other reason keeps it. Nothing on disk is touched.
if (await folderGone(record.path)) return writeWorktrees(file, readWorktrees(file).filter(w => !mine(w)))
+ if (record.kind === 'agent-folder') return this.removeAgentFolder(file, record, mine)
if (!await swarmWorktree(record.path, record.source, record.startId)) {
// The record no longer proves this belongs to Harness. Keep it; never loosen the proof to recover it.
if (await folderGone(record.path)) return writeWorktrees(file, readWorktrees(file).filter(w => !mine(w)))
@@ -1154,13 +1157,30 @@ export class ContributedMachines {
writeWorktrees(file, readWorktrees(file).filter(w => !mine(w)))
}
- /** A removal deletes only what is provably the Swarm's: the record says which worktree each start made. */
+ /** An agent's own folder (#3713), only when it is still the one Harness made and marked in its agent-home folder, and no
+ * session, live or paused, works in it: it holds nothing but that agent's own work. A record that no longer proves that
+ * is kept, its folder untouched; the log names no path. */
+ private async removeAgentFolder(file: string, record: SwarmWorktree, mine: (w: SwarmWorktree) => boolean): Promise<void> {
+ if (!removableAgentFolder(record.path, projectsRoot())) { this.log('Kept an agent folder: AGENT_FOLDER_UNPROVEN'); return }
+ const used = this.core.agents.live().some(a => !!a.cwd && within(record.path, a.cwd))
+ || this.core.agents.all().some(a => a.agentId !== record.harnessId && !!a.cwd && within(record.path, a.cwd))
+ if (used) return
+ // The agent's work is never deleted with its folder (security review of #3341): one that holds any is kept, with its
+ // record, for its person, as a worktree with uncommitted changes is.
+ if (!agentFolderEmpty(record.path)) { this.log('Kept an agent folder: AGENT_FOLDER_HAS_WORK'); return }
+ try { rmSync(record.path, { recursive: true, force: true }) } catch { this.log('Kept an agent folder: AGENT_FOLDER_REMOVAL_FAILED'); return }
+ writeWorktrees(file, readWorktrees(file).filter(w => !mine(w)))
+ }
+
+ /** A removal deletes only what is provably the Swarm's: the record says which worktree, or agent folder, each start made. */
private recordWorktree(tabId: string, startId: string, harnessId: string, request: Record<string, unknown>) {
const path = this.core.agents.byAgent(harnessId)?.cwd
- if (request.worktree !== true || typeof request.cwd !== 'string' || !path) return
+ const agentFolder = request.worktree !== true && !!path && removableAgentFolder(path, projectsRoot())
+ if ((request.worktree !== true && !agentFolder) || typeof request.cwd !== 'string' || !path) return
try {
const file = swarmWorktreesFile(this.core.dataDir, this.machineId), worktrees = readWorktrees(file)
- if (!worktrees.some(w => w.tabId === tabId && w.startId === startId)) writeWorktrees(file, [...worktrees, { tabId, startId, harnessId, source: request.cwd, path }])
+ if (!worktrees.some(w => w.tabId === tabId && w.startId === startId)) writeWorktrees(file, [...worktrees, { tabId, startId, harnessId,
+ source: request.cwd, path, ...(agentFolder ? { kind: 'agent-folder' as const } : {}) }])
} catch (error) { this.log(`Could not record the worktree of Swarm start ${startId}: ${error instanceof Error ? error.message : String(error)}`) }
}
private log(message: string) { (this.deps.log ?? (line => console.warn(`[super-tabs] ${line}`)))(message) }
diff --git a/cli/src/superTabs/start.spec.ts b/cli/src/superTabs/start.spec.ts
index 5dfcce286..125d295d4 100644
--- a/cli/src/superTabs/start.spec.ts
+++ b/cli/src/superTabs/start.spec.ts
@@ -1,3 +1,5 @@
+import { AGENT_FOLDER_MARK, agentFolderFor } from './agentFolder.js'
+import { projectsRoot } from '../lib/projectFolder.js'
import { describe, expect, it, vi } from 'vitest'
import { dirname, join } from 'node:path'
import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
@@ -776,6 +778,13 @@ describe('which branch a worktree starts from', () => {
expect(payload).toMatchObject({ projectSource: 'worktree', branchRef: 'refs/remotes/origin/feat/mobile' })
expect(payload).not.toHaveProperty('branchBase')
})
+ // Scholes, 11-06 (#3713): computer's Dee started in a Claude scratchpad, asked "Do you trust this folder?" on every run.
+ it('is a permanent folder Harness makes and marks when the folder named is a temporary one', async () => {
+ const [payload] = await created(request => { request.worktree = false; request.cwd = '/private/tmp/claude-501/-Users-mac/abc/scratchpad' })
+ const folder = agentFolderFor(projectsRoot(), 'start')
+ expect(payload).toMatchObject({ cwd: folder })
+ expect(existsSync(join(folder, AGENT_FOLDER_MARK))).toBe(true)
+ })
it('is not asked for when the agent works in the folder itself', async () => {
const [payload] = await created(request => { request.worktree = false })
expect(payload).toMatchObject({ cwd: '/repo' })
diff --git a/cli/src/superTabs/start.ts b/cli/src/superTabs/start.ts
index c30b1f4fa..b52d83617 100644
--- a/cli/src/superTabs/start.ts
+++ b/cli/src/superTabs/start.ts
@@ -10,6 +10,7 @@ import { permissionModeFlags } from '../lib/engineLaunch.js'
import type { AgentEngine } from '../engines/types.js'
import { isSwarmSkillMode, swarmSkillUse, wireRole, type SwarmSkillMode } from '../lib/swarmSkills.js'
import { isTeamDaemon, pmEngineHome } from './teamDaemon.js'
+import { agentFolderFor, prepareAgentFolder, temporaryFolder } from './agentFolder.js'
import { BUDDY_COPIES_FILE, BUDDY_HOMES, buddyProjectsOf, prepareBuddyHome, trustBuddyHome } from './buddyHome.js'
import { projectsRoot } from '../lib/projectFolder.js'
import { worktreeFolderName } from '../lib/agentNames.js'
@@ -428,6 +429,16 @@ async function startOnce(input: Json, scoped: ScopedRequest, where: Where, open:
if (buddy && (homeFolder || request.worktree)) markBuddyOwner(worktreeFolderName(`super-tab/${startId}`), String(object(request.buddyOf).personId))
const home = homeFolder ? await prepareBuddyHome(homeFolder, buddyProjectsOf(request)) : null
if (homeFolder) await trustBuddyHome(homeFolder, request.engine)
+ // A start that works in the folder it names, when that folder is a temporary one: a scratchpad, which Claude Code asks
+ // about on every run and nobody answers (computer's Dee, Scholes 11-06, #3713). The agent gets a permanent folder of its
+ // own, made, marked and trusted here, and removed when it stops (agentFolder.ts, machines.ts).
+ const agentFolder = !homeFolder && request.worktree !== true && typeof request.cwd === 'string' && temporaryFolder(request.cwd)
+ ? agentFolderFor(projectsRoot(), startId) : null
+ // A folder there Harness did not make is refused, and so is the start: it never runs, or trusts, in someone else's folder.
+ if (agentFolder) {
+ try { await prepareAgentFolder(agentFolder, request.engine) }
+ catch { return { error: 'START_FAILED', startId, detail: 'This agent\'s folder could not be made safely on this machine.' } }
+ }
// A project's Product Manager (backend leadStart.ts): the Lead of its project's conversation once it runs.
const lead = !buddy && !!request.leadFor && typeof request.leadFor === 'object'
const handoffNote = lead && typeof request.handoffNote === 'string' && request.handoffNote.length <= 32_000
@@ -460,7 +471,7 @@ async function startOnce(input: Json, scoped: ScopedRequest, where: Where, open:
: home ? swarmBuddyPrompt(String(input.tabId), String(request.conversationId), home, mode)
: buddyPrompt(String(input.tabId), String(request.conversationId), mode))
: `${lead ? leadPrompt(String(input.tabId), String(request.conversationId), roleName) : workerPrompt(String(input.tabId), String(request.conversationId), roleName)}${github ? ` ${githubPromptLine()}` : ''}${handoffPrompt}`,
- ...(homeFolder ? { cwd: homeFolder } : request.worktree ? { projectSource: 'worktree', gitSource: request.cwd, branchName: `super-tab/${startId}`,
+ ...(homeFolder ? { cwd: homeFolder } : agentFolder ? { cwd: agentFolder } : request.worktree ? { projectSource: 'worktree', gitSource: request.cwd, branchName: `super-tab/${startId}`,
// No branch named: the repository's default branch, fetched, not the host checkout's old HEAD.
...(request.branchRef ? { branchRef: request.branchRef } : { branchBase: 'default' }) } : { cwd: request.cwd }),
}
diff --git a/docs/plans/2026-11-06-agent-folder-trust-plan.md b/docs/plans/2026-11-06-agent-folder-trust-plan.md
new file mode 100644
index 000000000..43502033a
--- /dev/null
+++ b/docs/plans/2026-11-06-agent-folder-trust-plan.md
@@ -0,0 +1,97 @@
+# Agents never stop on Claude's folder-trust question: Implementation Plan
+
+> Way of working: this project's Engineer role. Each plan task is implemented test first, by
+> superpowers:test-driven-development: the failing test is committed and watched fail before its code. Steps use checkbox
+> (`- [ ]`) syntax.
+
+**Goal:** A Claude agent the Swarm starts never stops on "Do you trust this folder?". When its start names a temporary folder
+(a scratchpad), it starts in a permanent folder Harness makes for it and trusts. Task #3713, reported by Scholes for
+project computer's agent Dee.
+
+**Architecture:** A Swarm start without a worktree passes the requested `cwd` through unchanged (`superTabs/start.ts`). The
+core trusts a Swarm agent's folder only when it is a Git checkout in the projects root, or a worktree Harness made
+(`core/agents/create.ts` `swarmFolder`). A scratchpad is neither, so Claude asks on every run, in a terminal no Swarm view
+shows. The fix follows the Buddy home (`superTabs/buddyHome.ts`), the one folder Harness already makes and trusts for a start:
+- When the requested folder is temporary, the start makes `<projectsRoot>/worktrees/agent-home/<leaf of super-tab/<startId>>`
+ with a marker file, trusts that folder alone in Claude's settings, and launches there.
+- The start records it beside its worktrees, so the agent's stop removes it: only that folder, only with its marker, and only
+ when no session works in it.
+
+**Tech Stack:** TypeScript, vitest.
+
+**Spec:** task #3713's brief.
+
+## Global Constraints
+
+- Trust only the folder Harness created for the agent, never a parent folder or the home folder.
+- Leave the person's own Claude settings unchanged for folders Harness didn't create.
+- Never print a secret.
+- Only a folder inside Harness's own agent-home area, with its marker, is ever removed; anything else is kept.
+
+## Review Focus
+
+1. A requested folder that is not temporary (a project checkout, the person's own folder) is passed through as before, and is
+ never trusted or removed by this change. Task 1 and Task 2 pin it.
+2. A temporary folder is recognised as written and with links resolved (`/tmp`, `/private/tmp`, `/var/tmp`, the OS temp
+ folder, the macOS `/var/folders` and `/private/var/folders`). Task 1 pins it.
+3. A folder named by a request can never be the one Harness removes: the path is made from the start id, inside
+ agent-home. Task 3 pins it.
+4. A folder another live or paused session works in is kept. Task 3 pins it.
+5. Trust is recorded for that exact folder, in the Claude home the launch reads. Task 2 pins it.
+
+---
+
+### Task 1: The agent folder
+
+**Files:**
+- Create: `cli/src/superTabs/agentFolder.ts`
+- Test: `cli/src/superTabs/agentFolder.spec.ts`
+
+**Interfaces:**
+- Produces: `AGENT_FOLDERS = 'agent-home'`, `AGENT_FOLDER_MARK = '.harness-agent-folder'`.
+- Produces: `temporaryFolder(path: string, tmp?: string): boolean`.
+- Produces: `agentFolderFor(root: string, startId: string): string`.
+- Produces: `prepareAgentFolder(folder: string, engine: unknown): Promise<void>`, which makes the folder (0700) and its mark,
+ and records Claude's trust for it.
+- Produces: `removableAgentFolder(path: string, root: string): boolean`.
+
+- [ ] **Step 1: Write the failing tests:**
+ - `temporaryFolder` is true for `/tmp/x`, `/private/tmp/claude-501/a/scratchpad`, `/var/folders/ab/T/x` and `<tmpdir>/x`.
+ - It is false for `/Users/me/work`, `/tmp-not/x` and `<root>/worktrees/repo/leaf`.
+ - `agentFolderFor(root, 's1')` is `<root>/worktrees/agent-home/<worktreeFolderName('super-tab/s1')>`.
+ - `prepareAgentFolder` makes the folder with mode 700 and the mark, and records trust for it alone in a temp Claude home.
+ - `removableAgentFolder` is true only for a marked folder directly in `<root>/worktrees/agent-home`.
+- [ ] **Step 2: Run** `npx vitest run src/superTabs/agentFolder.spec.ts` and watch it fail.
+- [ ] **Step 3: Implement** in `agentFolder.ts`, with trust through `folderTrust('claude', …).record(folder)`, as `trustBuddyHome` does.
+- [ ] **Step 4: Run and see it pass.** Commit the test first, then the code.
+
+### Task 2: The Swarm start uses it
+
+**Files:**
+- Modify: `cli/src/superTabs/start.ts` (the payload's `cwd`)
+- Test: `cli/src/superTabs/start.spec.ts`
+
+- [ ] **Step 1: Write the failing test:** a Claude start with `worktree: false` and a scratchpad `cwd` creates the agent with
+ `cwd` set to `agentFolderFor(projectsRoot(), startId)`, and that folder exists and is trusted. The same start with a
+ non-temporary `cwd` keeps it as before.
+- [ ] **Step 2: Run** `npx vitest run src/superTabs/start.spec.ts` and watch it fail.
+- [ ] **Step 3: Implement:** compute `agentFolder` only for a start that is not a Buddy home and not a worktree, whose `cwd` is
+ temporary; prepare it; send `cwd: agentFolder`.
+- [ ] **Step 4: Run and see it pass.** Commit the test first, then the code.
+
+### Task 3: The agent folder goes when its agent stops
+
+**Files:**
+- Modify: `cli/src/superTabs/machines.ts` (`recordWorktree`, `removeWorktreeOnce`)
+- Test: `cli/src/superTabs/machines.spec.ts`
+
+- [ ] **Step 1: Write the failing tests:**
+ - A start whose agent runs in a removable agent folder is recorded with `kind: 'agent-folder'`.
+ - Its stop removes that folder once no session uses it.
+ - A record whose path is not a removable agent folder is kept and its folder untouched.
+- [ ] **Step 2: Run and watch them fail.**
+- [ ] **Step 3: Implement:**
+ - `recordWorktree` also records an agent folder.
+ - `removeWorktreeOnce` removes a record of `kind: 'agent-folder'` with `rmSync(recursive)`, only when
+ `removableAgentFolder(path, projectsRoot())` holds and no session works in it, then drops the record.
+- [ ] **Step 4: Run and see them pass.** Commit the test first, then the code.