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.

A start that can't launch says why, and the PM sees it (#3404)

harness-for-autonomous[bot]fcb8a1d21ba1
diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.ts
index 75d2f602c..05a0814b8 100644
--- a/backend/src/superTabs/commands.test.ts
+++ b/backend/src/superTabs/commands.test.ts
@@ -1127,6 +1127,46 @@ describe('the last action of the project\'s agents on a task', () => {
f.run({ type: 'agent.startFailed', startId, error: 'Could not prepare the worktree' }, f.leadActor, { contribution: f.contribution, now: 7000 })
expect(task().liveness).toEqual({ state: 'orphaned', why: 'start-failed', since: 7000 })
})
+
+ // Task #3861: a start stayed Queued for hours with its machine's fault only in that machine's log. Its host reports why it waits.
+ describe('a start its machine reports waiting', () => {
+ const FOLDER = 'CREATION_STORAGE_FAILED: The creation folder ~/.harness/cli/data/agent-creations is not usable by this account (permissions). It must belong to this account with mode 700; the owner of this computer fixes that, Harness does not change it.'
+ const started = () => {
+ const f = routed(), group = f.group()
+ f.define(group)
+ const request = { conversationId: group, machineId: 'machine', engine: 'claude', name: 'Builder', cwd: '/repo', worktree: true,
+ requirements: { memoryBytes: 100, diskBytes: 200, maxCpuPercent: 80, tools: ['git'], devices: [], quotaRequired: false } }
+ const startId = f.run({ type: 'agent.start', request, ...via }, f.leadActor, { contribution: f.contribution, ...decisionIn(group) }).result.startId as string
+ const start = () => f.state.starts!.find(s => s.id === startId)!
+ return { f, startId, start, wait: (reason: string, now = 5000) => f.run({ type: 'agent.startWaiting', startId, reason }, f.leadActor, { contribution: f.contribution, now }) }
+ }
+
+ it('keeps the reason and when it was first told, on the start', () => {
+ const { start, wait } = started()
+ wait(FOLDER, 5000)
+ expect(start().waiting).toEqual({ reason: FOLDER, at: 5000 })
+ wait(FOLDER, 9000)
+ expect(start().waiting).toEqual({ reason: FOLDER, at: 5000 })
+ wait('CREATION_STORAGE_FAILED: other', 9500)
+ expect(start().waiting).toEqual({ reason: 'CREATION_STORAGE_FAILED: other', at: 9500 })
+ })
+ it('is read whole by its coordinator and as what it means by anyone else', () => {
+ const { f, start, wait } = started()
+ f.invite()
+ wait(FOLDER)
+ expect(visibleState(f.state, f.leadActor).starts!.find(s => s.id === start().id)!.waiting!.reason).toBe(FOLDER)
+ expect(visibleState(f.state, peer).starts!.find(s => s.id === start().id)!.waiting!.reason).toContain("Its machine's creation folder ~/.harness/cli/data/agent-creations is not usable")
+ })
+ it('ends with the start: failed or started', () => {
+ const { f, startId, start, wait } = started()
+ wait(FOLDER)
+ f.run({ type: 'agent.startFailed', startId, error: FOLDER }, f.leadActor, { contribution: f.contribution, now: 6000 })
+ expect(start().waiting).toBeUndefined()
+ // A report that arrives after the start ended changes nothing.
+ wait(FOLDER, 7000)
+ expect(start().waiting).toBeUndefined()
+ })
+ })
})
// The Lead's ruling, 2026-10-29: the project chat and the Leads chat carry only what people read or decide on, and agent
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index 097288c57..47bb478c9 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -419,6 +419,8 @@ export const commandSchema = z.discriminatedUnion('type', [
z.object({ type: z.literal('agent.startSettled'), startId: id, warning: z.string().max(2000).nullable(),
configuration: configuration.optional() }).strict(),
z.object({ type: z.literal('agent.startFailed'), startId: id, error: text }).strict(),
+ // Why its machine holds a start it has not launched, told once per reason (cli superTabs/machines.ts): shown on the start until it ends.
+ z.object({ type: z.literal('agent.startWaiting'), startId: id, reason: text }).strict(),
z.object({ type: z.literal('agent.stopLease'), agentId: id, releaseId: id }).strict(),
z.object({ type: z.literal('agent.switchClaim'), agentId: id, switchId: id }).strict(),
// The source PM's host sends the prepared handoff to the candidate start; it is not a general chat message or visible to readers.
@@ -546,6 +548,7 @@ export const WORDS: Partial<Record<Command['type'], readonly string[]>> = {
'work.lane': ['lane'],
'agent.start': ['request.name', 'request.roleName', 'overrideReason'],
'agent.startFailed': ['error'],
+ 'agent.startWaiting': ['reason'],
'agent.switchResult': ['error'],
'agent.screenResult': ['error'],
'agent.inputResult': ['error'],
@@ -3822,10 +3825,17 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
case 'agent.startDispatch':
case 'agent.started':
case 'agent.startSettled':
+ case 'agent.startWaiting':
case 'agent.startFailed': {
const start = state.starts?.find(s => s.id === command.startId) ?? fail('NOT_FOUND', 'This agent start is unavailable.', 404)
if (!mayResumeStart(state, actor, start)) fail('FORBIDDEN', 'Only whoever made this start, or its project\'s coordinator, carries it on.', 403)
if (person(state, start.contributorId).generation !== start.membershipGeneration) fail('FORBIDDEN', 'This contribution was withdrawn.', 403)
+ if (command.type === 'agent.startWaiting') {
+ // A start that ended says so itself; a late report changes nothing. A reason told again keeps when it was first told.
+ if (!start.harnessId && !start.error && start.waiting?.reason !== command.reason) start.waiting = { reason: command.reason, at: context.now }
+ break
+ }
+ delete start.waiting
if (command.type === 'agent.startDispatch') {
if (state.paused) fail('PAUSED', 'New work is paused in this Super Tab.')
if (!['claude', 'codex'].includes(start.request.engine)) {
diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.ts
index b564ef9b3..7e88cf363 100644
--- a/backend/src/superTabs/model.ts
+++ b/backend/src/superTabs/model.ts
@@ -261,6 +261,9 @@ export interface AgentStart {
/** When it was asked for (absent on starts from before 2026-10-29): a Buddy's fails if its machine never takes it, and a
* task's start never launched leaves the task orphaned (liveness.ts). */
requestedAt?: number
+ /** Why its machine holds it without launching it, from the machine's report (cli superTabs/machines.ts), with when it was first
+ * told: gone once the start launches or fails. Read whole by the readers of its raw reason, as what it means by the rest. */
+ waiting?: { reason: string; at: number }
/** On reads only, never stored: its machine's fresh report says it is preparing (machines.ts startPreparing). */
preparing?: true
error: string | null
@@ -1320,7 +1323,9 @@ export function visibleState(state: SuperTabState, actor: Actor, now = Date.now(
}
if (actor.kind !== 'person' || actor.userId !== state.ownerId) visible.invitations = []
for (const start of visible.starts ?? []) {
- if (start.error && !readsRawReason(actor, start, state.conversations.find(c => c.id === start.request.conversationId))) start.error = publicReason(start.error)
+ const raw = readsRawReason(actor, start, state.conversations.find(c => c.id === start.request.conversationId))
+ if (start.error && !raw) start.error = publicReason(start.error)
+ if (start.waiting && !raw) start.waiting = { ...start.waiting, reason: publicReason(start.waiting.reason) }
}
// A Buddy brainstorms; where agents run and how work is routed are none of its business (buddies.ts). A start names the
// machine and the folder on it, so it reads none, though it reads their workgroups.
diff --git a/backend/src/superTabs/startFailure.test.ts b/backend/src/superTabs/startFailure.test.ts
new file mode 100644
index 000000000..0656a3d0e
--- /dev/null
+++ b/backend/src/superTabs/startFailure.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { failureNotice, MACHINE_FAILED, publicReason } from './startFailure.js'
+
+// Task #3861 (River, 11-06): five starts failed on four machines in a day and their notices said only "could not prepare or launch
+// it". A host's words can name a machine, a folder or a token (publicReason), so only the fixed shapes this CLI writes for a fault of
+// the machine itself are told, and never anything a host adds to them.
+describe('what a group member reads of a fault of the machine', () => {
+ const folder = '~/.harness/cli/data/agent-creations'
+ const storage = (path = folder) => `CREATION_STORAGE_FAILED: The creation folder ${path} is not usable by this account (permissions). It must belong to this account with mode 700; the owner of this computer fixes that, Harness does not change it.`
+
+ it('tells the unusable creation folder and that its owner fixes it', () => {
+ expect(publicReason(storage())).toBe(`Its machine's creation folder ${folder} is not usable by its account (permissions): the owner of that computer fixes its owner and mode.`)
+ expect(failureNotice('Heron', storage(), undefined)).toContain('creation folder ~/.harness/cli/data/agent-creations is not usable')
+ })
+ it('tells a clone that stopped, without the words git added', () => {
+ const clone = "This machine could not clone the project repository with the Harness GitHub App's token: Cloning stopped making progress (git's last words: fatal: unable to access 'https://x-access-token:[email protected]/o/r.git'). Check the connection and retry."
+ expect(publicReason(clone)).toBe("Its machine could not clone the project repository with the Harness GitHub App's token.")
+ expect(publicReason(clone)).not.toContain('SECRET')
+ })
+ it('tells nothing else a host wrote: a path outside the home folder, or anything appended', () => {
+ expect(publicReason(storage('/Users/stone/.harness/cli/data/agent-creations'))).toBe(MACHINE_FAILED)
+ expect(publicReason(`${storage()} token=abc123`)).toBe(MACHINE_FAILED)
+ expect(publicReason(storage('~/a b; rm -rf /'))).toBe(MACHINE_FAILED)
+ expect(publicReason('CREATION_STORAGE_FAILED: see /Users/stone/secret')).toBe(MACHINE_FAILED)
+ })
+})
diff --git a/backend/src/superTabs/startFailure.ts b/backend/src/superTabs/startFailure.ts
index f865b7289..26feaead4 100644
--- a/backend/src/superTabs/startFailure.ts
+++ b/backend/src/superTabs/startFailure.ts
@@ -40,8 +40,18 @@ export const NO_PM_RELAY = 'The owner\'s subscription relay is not available on
* 2026-10-28, where "could not prepare or launch it" sent people looking for a fault). */
const MEMORY_SHORT = /^Not enough free memory: (\d+(?:\.\d)? GiB) free, (\d+(?:\.\d)? GiB) needed\./
+/** Faults of the machine itself, in the fixed words this CLI writes (cli superTabs/start.ts, lib/agentCreationReceipt.ts,
+ * superTabs/projectFolder.ts), told to every reader (task #3861): the creation folder, only under the home folder as `~/...` in plain
+ * path characters and with nothing after the sentence, and a clone that failed, without whatever git said after. Anything else
+ * a host adds is not told. */
+const CREATION_FOLDER = /^CREATION_STORAGE_FAILED: The creation folder (~\/[\w.-]+(?:\/[\w.-]+){0,6}) is not usable by this account \(permissions\)\. It must belong to this account with mode 700; the owner of this computer fixes that, Harness does not change it\.$/
+const CLONE_FAILED = /^This machine could not clone the project repository with the Harness GitHub App's token(?::|$)/
+
export function publicReason(error: string): string {
if (error === MACHINE_REMOVED || error === ABANDONED || error === NO_PM_RELAY) return error
+ const folder = CREATION_FOLDER.exec(error)
+ if (folder) return `Its machine's creation folder ${folder[1]} is not usable by its account (permissions): the owner of that computer fixes its owner and mode.`
+ if (CLONE_FAILED.test(error)) return "Its machine could not clone the project repository with the Harness GitHub App's token."
const memory = MEMORY_SHORT.exec(error)
if (memory) return `Its machine has only ${memory[1]} of memory free, and it needs ${memory[2]}.`
if (LEAD_PICKUP.test(error)) return LEAD_NOT_PICKED
diff --git a/cli/src/core/agents/launches.spec.ts b/cli/src/core/agents/launches.spec.ts
index ab80c3160..a743ddffb 100644
--- a/cli/src/core/agents/launches.spec.ts
+++ b/cli/src/core/agents/launches.spec.ts
@@ -1141,6 +1141,12 @@ describe('agent_create_status', () => {
const broken = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), run: vi.fn(), status: vi.fn(() => { throw new Error('bug') }) } })
expect(await broken.status({ creationId: CREATION })).toStrictEqual({ error: 'INTERNAL' })
})
+
+ it('tells the host why when the status read fails on a permissions problem (task #3861)', async () => {
+ const detail = 'The creation folder ~/.harness/cli/data/agent-creations is not usable by this account (permissions).'
+ const storage = setup({ receipts: { has: vi.fn(() => false), creator: vi.fn(), createdLaunchModel: vi.fn(() => null), runIntent: vi.fn(), pendingIntents: vi.fn(), pendingIntent: vi.fn(), cancelIntent: vi.fn(), run: vi.fn(), status: vi.fn(() => { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED', detail) }) } })
+ expect(await storage.status({ creationId: CREATION })).toStrictEqual({ error: 'CREATION_STORAGE_FAILED', detail })
+ })
})
describe('agent_resume and agent_restart', () => {
diff --git a/cli/src/core/agents/launches.ts b/cli/src/core/agents/launches.ts
index 996e71f45..72b6fe300 100644
--- a/cli/src/core/agents/launches.ts
+++ b/cli/src/core/agents/launches.ts
@@ -308,7 +308,8 @@ export function createLaunchRequests({ receipts, createAgent, prepareCreate, pre
const launchModel = status.state === 'created' ? receipts.createdLaunchModel(creationId) : null
reply({ creationId, ...await creationStatusPayload(status), ...(launchModel ? { launchModel } : {}) })
} catch (error) {
- reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL' })
+ // The reason travels with the code, so the host can tell the Swarm why the start waits (task #3861).
+ reply({ error: error instanceof AgentCreationReceiptError ? error.code : 'INTERNAL', ...error instanceof AgentCreationReceiptError && error.detail ? { detail: error.detail } : {} })
}
}
diff --git a/cli/src/lib/agentCreationReceipt.spec.ts b/cli/src/lib/agentCreationReceipt.spec.ts
index 371d1b9c2..da288c7d3 100644
--- a/cli/src/lib/agentCreationReceipt.spec.ts
+++ b/cli/src/lib/agentCreationReceipt.spec.ts
@@ -1,9 +1,9 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import * as fs from 'node:fs'
-import { mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { AgentCreationReceipts, creationFingerprint, type AgentCreationOutcome } from './agentCreationReceipt.js'
+import { AgentCreationReceiptError, AgentCreationReceipts, creationFingerprint, type AgentCreationOutcome } from './agentCreationReceipt.js'
const roots: string[] = []
function fixture() {
@@ -23,6 +23,34 @@ vi.mock('node:fs', async (original) => {
afterEach(() => vi.restoreAllMocks())
describe('agent creation receipts', () => {
+ // Task #3861 (stone7890's Mac, 11-06): the folder was owned by root, every status read threw CREATION_STORAGE_FAILED with nothing
+ // else, and the start stayed Queued for hours. The error now names the folder and that it is a permissions problem.
+ it.skipIf(process.getuid?.() === 0)('names the folder and the permissions when the account cannot open the receipts folder', () => {
+ const { directory, receipts } = fixture()
+ mkdirSync(directory, { mode: 0o700 })
+ chmodSync(directory, 0o000)
+ try {
+ let thrown: unknown
+ try { receipts.status(id) } catch (error) { thrown = error }
+ expect(thrown).toBeInstanceOf(AgentCreationReceiptError)
+ const error = thrown as AgentCreationReceiptError
+ expect(error.code).toBe('CREATION_STORAGE_FAILED')
+ expect(error.detail).toContain(directory)
+ expect(error.detail).toMatch(/permission/i)
+ expect(error.detail).toContain('mode 700')
+ expect(error.detail).not.toMatch(/sudo/)
+ } finally { chmodSync(directory, 0o700) }
+ })
+
+ it('gives no detail for a storage failure that is not about permissions', () => {
+ const { directory, receipts } = fixture()
+ mkdirSync(directory, { mode: 0o700 })
+ writeFileSync(join(directory, `${id}.json`), '{not json', { mode: 0o600 })
+ let thrown: unknown
+ try { receipts.status(id) } catch (error) { thrown = error }
+ expect((thrown as AgentCreationReceiptError).detail).toBeUndefined()
+ })
+
it('shares an in-flight launch and recovers its result after a lost reply and daemon restart', async () => {
const { directory, receipts } = fixture()
let finish!: (outcome: AgentCreationOutcome) => void
diff --git a/cli/src/lib/agentCreationReceipt.ts b/cli/src/lib/agentCreationReceipt.ts
index 606cbca28..f7cbcfb68 100644
--- a/cli/src/lib/agentCreationReceipt.ts
+++ b/cli/src/lib/agentCreationReceipt.ts
@@ -1,6 +1,7 @@
import { createHash, randomUUID } from 'node:crypto'
import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { opendir } from 'node:fs/promises'
+import { homedir } from 'node:os'
import { dirname, join } from 'node:path'
import { readPrivateStateFile, secureStateDirectory, syncStateDirectory } from './secureState.js'
import type { LaunchModel } from './launchModel.js'
@@ -59,11 +60,24 @@ function validOutcome(outcome: AgentCreationOutcome | undefined): outcome is Age
}
export class AgentCreationReceiptError extends Error {
- constructor(readonly code: 'INVALID_CREATION_ID' | 'CREATION_CONFLICT' | 'CREATION_STORAGE_FAILED') {
+ /** `detail`: for a storage failure that is a permissions problem, the folder and what its owner does (task #3861). Never a secret. */
+ constructor(readonly code: 'INVALID_CREATION_ID' | 'CREATION_CONFLICT' | 'CREATION_STORAGE_FAILED', readonly detail?: string) {
super(code)
}
}
+/** A storage failure of the folder [directory]: with the folder and the fix when the account is refused it or does not own it
+ * (stone7890's Mac, 11-06: root-owned, so every start waited for hours on a bare code). Harness never changes a person's folder
+ * permissions: the owner of this computer does, and the words say how. */
+function storageFailure(directory: string, error: unknown): AgentCreationReceiptError {
+ const { code, message } = error as { code?: string; message?: string }
+ const permissions = code === 'EACCES' || code === 'EPERM' || /unsafe owner|writable/.test(message ?? '')
+ if (!permissions) return new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
+ const home = homedir(), shown = directory === home || directory.startsWith(`${home}/`) ? `~${directory.slice(home.length)}` : directory
+ return new AgentCreationReceiptError('CREATION_STORAGE_FAILED',
+ `The creation folder ${shown} is not usable by this account (permissions). It must belong to this account with mode 700; the owner of this computer fixes that, Harness does not change it.`)
+}
+
export function validCreationId(value: unknown): value is string {
return typeof value === 'string' && /^[a-zA-Z0-9_-]{16,96}$/.test(value)
}
@@ -396,7 +410,7 @@ export class AgentCreationReceipts {
}
this.syncDirectory()
return true
- } catch { throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED') }
+ } catch (error) { throw error instanceof AgentCreationReceiptError ? error : storageFailure(this.directory, error) }
finally { if (opened) rmSync(temporary, { force: true }) }
}
@@ -476,7 +490,7 @@ export class AgentCreationReceipts {
try { secureStateDirectory(this.directory, false) }
catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !completedIntent) return null
- throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
+ throw storageFailure(this.directory, error)
}
try {
const value = JSON.parse(readPrivateStateFile(file, 262_144)) as Partial<Receipt> | Partial<IntentReceipt>
@@ -505,7 +519,7 @@ export class AgentCreationReceipts {
} catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !completedIntent
&& !this.readIntentPart(this.intentFile(id, 'claim')) && !this.readIntentPart(this.intentFile(id, 'result'))) return null
- throw new AgentCreationReceiptError('CREATION_STORAGE_FAILED')
+ throw storageFailure(this.directory, error)
}
}
diff --git a/cli/src/superTabs/machines.spec.ts b/cli/src/superTabs/machines.spec.ts
index a4c39c8a8..dca361325 100644
--- a/cli/src/superTabs/machines.spec.ts
+++ b/cli/src/superTabs/machines.spec.ts
@@ -1711,6 +1711,48 @@ describe('contributed machine executor', () => {
error: 'The selected agent engine is not installed on this machine. CPU use is 97%; the requested maximum is 85%.' } }])
})
+ // Task #3861 (stone7890's Mac, 11-06): a start stayed Queued for hours, its machine's fault only in the host log. The Swarm is
+ // told the reason, once, and the start fails with it after 5 minutes, so the Lead starts it elsewhere.
+ describe('on a fault of this machine', () => {
+ const fault = { error: 'START_MACHINE_FAULT', startId: 'start', creationId: 'creation-0000000000000001',
+ detail: 'CREATION_STORAGE_FAILED: The creation folder ~/.harness/cli/data/agent-creations is not usable by this account (permissions).' }
+ const waiting = (f: ReturnType<typeof fixture>) => f.backend.mock.calls.filter(c => c[1] === 'POST' && c[2] === '/api/super-tabs/hosts/host/starts/tab/start')
+ .map(c => (c[3] as { command: { type: string; startId: string; reason: string } }).command).filter(command => command.type === 'agent.startWaiting')
+
+ it('tells the Swarm the reason once, and fails the start with it after five minutes', async () => {
+ const f = fixture()
+ f.start.mockResolvedValue(fault as never)
+ await f.machine.tick()
+ for (let i = 0; i < 4; i++) { f.step(60_000); await f.machine.tick() }
+ expect(waiting(f)).toEqual([{ type: 'agent.startWaiting', startId: 'start', reason: fault.detail }])
+ expect(failures(f)).toEqual([])
+ f.step(60_000); await f.machine.tick()
+ expect(failures(f)).toEqual([{ operationId: 'refused-start', command: { type: 'agent.startFailed', startId: 'start', error: fault.detail } }])
+ })
+
+ it('never fails a start already dispatched, whose launch may have happened', async () => {
+ const f = fixture()
+ f.pool.starts[0]!.dispatched = true
+ f.start.mockResolvedValue(fault as never)
+ await f.machine.tick()
+ for (let i = 0; i < 6; i++) { f.step(60_000); await f.machine.tick() }
+ expect(failures(f)).toEqual([])
+ })
+
+ it('goes on when the Swarm\'s server does not know the report', async () => {
+ const f = fixture()
+ f.start.mockResolvedValue(fault as never)
+ const post = f.backend.getMockImplementation()!
+ f.backend.mockImplementation(async (...args: Parameters<typeof post>) => {
+ if ((args[3] as { command?: { type?: string } } | undefined)?.command?.type === 'agent.startWaiting') throw new SuperTabHostError('VALIDATION_ERROR', 'Unknown command', 400)
+ return post(...args)
+ })
+ await f.machine.tick()
+ for (let i = 0; i < 5; i++) { f.step(60_000); await f.machine.tick() }
+ expect(failures(f)).toHaveLength(1)
+ })
+ })
+
it('starts its minute again after a pass that did not refuse it, and never fails one whose launch is uncertain or pending', async () => {
const f = fixture()
f.start.mockResolvedValue({ error: 'CONTRIBUTION_REQUIRED', startId: 'start', detail: 'Ask the machine owner to use Add machine in this Swarm.' } as never)
diff --git a/cli/src/superTabs/machines.ts b/cli/src/superTabs/machines.ts
index 6c4e73406..84e6e9837 100644
--- a/cli/src/superTabs/machines.ts
+++ b/cli/src/superTabs/machines.ts
@@ -59,6 +59,10 @@ const BEAT_LIMIT_MS = 3 * 60_000
* busy CPU or memory may pass, and routing saw this machine able a moment ago. A refusal no one reported left starts
* "Queued" for hours (DESKTOP-0TFH0OJ, 2026-10-23). */
const START_REFUSED_MS = 60_000
+/** How long a fault of this machine (its creation folder cannot be used, say) may hold an undispatched start before it fails with the
+ * fault's reason, so the Lead starts it elsewhere: longer than a refusal, since a person may fix the machine meanwhile. stone7890's
+ * Mac held one for four hours with only the host log to say why (task #3861). */
+const START_FAULT_MS = 5 * 60_000
/** What a start answers while its launch may already have happened or is under way: never failed from here, or an agent
* could run with no start to show for it. The failures already reported say so themselves. */
const NOT_REFUSED = new Set(['START_UNCERTAIN', 'START_PENDING', 'START_REFUSED', 'START_FAILED', 'SWARM_ENGINE'])
@@ -233,6 +237,8 @@ export class ContributedMachines {
private readonly toolCache = new Map<string, { value: boolean | null; detail?: string; until: number }>()
/** Per waiting start, why it was last not started, so the log says it once per reason, not every pass. */
private readonly waiting = new Map<string, string>()
+ /** Per waiting start, the fault reason the Swarm has been told, so it hears each once (agent.startWaiting). */
+ private readonly told = new Map<string, string>()
/** Per tab, why its last reading did not reach the backend, so the log says it once per error and once when it clears. */
private readonly readingFailures = new Map<string, string>()
/** Per waiting start, since when this machine has refused it without a break. */
@@ -428,6 +434,18 @@ export class ContributedMachines {
this.waiting.set(startId, reason)
this.log(`Swarm start ${startId} is waiting: ${reason}`)
}
+ /** Tells the Swarm why a start waits on this machine, once per reason: the PM sees it on the start and in the route instead of
+ * only "Queued". A server that does not know the report (an older backend) is not asked again; any other failure is retried. */
+ private async tell(scoped: ScopedRequest, startId: string, reason: string) {
+ if (this.told.get(startId) === reason) return
+ try {
+ await scoped({ action: 'command', operationId: `waiting-${startId}-${createHash('sha256').update(reason).digest('hex').slice(0, 12)}`,
+ command: { type: 'agent.startWaiting', startId, reason } })
+ } catch (error) {
+ if (!(error instanceof SuperTabHostError && error.status >= 400 && error.status < 500)) return
+ }
+ this.told.set(startId, reason)
+ }
private async reportStartFailure(startId: string, path: string, input: Record<string, unknown>): Promise<void> {
let report = this.failureReports.get(startId)
if (!report) {
@@ -526,6 +544,7 @@ export class ContributedMachines {
const pendingIds = new Set(pools.flatMap(row => startsOf(row).map(start => start.id)))
for (const id of this.failureReports.keys()) if (!pendingIds.has(id)) this.failureReports.delete(id)
for (const id of this.waiting.keys()) if (!pendingIds.has(id)) this.waiting.delete(id)
+ for (const id of this.told.keys()) if (!pendingIds.has(id)) this.told.delete(id)
for (const id of this.refusedSince.keys()) if (!pendingIds.has(id)) this.refusedSince.delete(id)
for (const id of this.preparing) if (!pendingIds.has(id)) this.preparing.delete(id)
for (const id of this.refused.keys()) if (!pendingIds.has(id)) this.refused.delete(id)
@@ -851,9 +870,11 @@ export class ContributedMachines {
} else if (result.ok !== true) {
const reason = String(result.detail ?? (Array.isArray(result.reasons) ? result.reasons.join(' ') : result.error))
this.noteWaiting(start.id, reason)
+ const fault = result.error === 'START_MACHINE_FAULT'
+ if (fault) await this.tell(scoped, start.id, reason)
const since = this.refusedSince.get(start.id) ?? began
if (refused) this.refusedSince.set(start.id, since)
- if (refused && began - since >= START_REFUSED_MS) {
+ if (refused && began - since >= (fault ? START_FAULT_MS : START_REFUSED_MS)) {
await scoped({ action: 'command', operationId: `refused-${start.id}`, command: { type: 'agent.startFailed', startId: start.id, error: reason } })
}
}
diff --git a/cli/src/superTabs/routeCommand.spec.ts b/cli/src/superTabs/routeCommand.spec.ts
index 454c60a48..6f044719c 100644
--- a/cli/src/superTabs/routeCommand.spec.ts
+++ b/cli/src/superTabs/routeCommand.spec.ts
@@ -4,7 +4,7 @@ import { mkdtemp, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { PM_ACCOUNT_NOTE } from './pmAccounts.js'
-import { ELSEWHERE, heldByStarts, heldLocalModels, leftOut, localProbes, NO_SWARM_AGENTS_ON, noteClause, offlineModels, routeAnswer, routeTask, routingSection, servedModels, STALL_RETRY_MS, stalled } from './routeCommand.js'
+import { ELSEWHERE, heldByStarts, heldLocalModels, leftOut, localProbes, NO_SWARM_AGENTS_ON, noteClause, offlineModels, routeAnswer, routeTask, routingSection, servedModels, STALL_RETRY_MS, faulted, stalled } from './routeCommand.js'
import type { describeScmProject } from '../scm/scmProjects.js'
import { admission, quotaOf, USED_UP_WINDOW } from './capacity.js'
import { NONE_COVERS, OTHER_REPOSITORY, type Catalog, type Probe, type RoutePlugin } from './route.js'
@@ -551,6 +551,36 @@ describe('routeTask', () => {
expect(rows.filter(r => r.machineId === 'm1' && r.title.startsWith('New agent'))).not.toHaveLength(0)
expect(rows.find(r => r.title.startsWith('Multiply'))!.label).not.toContain('last 2 starts')
})
+ // Task #3861 (River, 11-06): a start that failed on this machine's own storage or clone sent the next one to the same machine, five
+ // times in a day. One such failure is enough to leave it out, with the reason, until it is fixed.
+ describe('a machine whose last start failed on its own storage or clone', () => {
+ const now = Date.parse('2026-11-06T10:00:00Z')
+ const fault = (id: string, error: string, at = now - 60_000, version?: string) => ({ id, request: { machineId: 'm1' }, harnessId: null, dispatched: true, error,
+ dispatchedAt: at, ...(version ? { dispatchedVersion: version } : {}) })
+ const storage = 'CREATION_STORAGE_FAILED: The creation folder ~/.harness/cli/data/agent-creations is not usable by this account (permissions). It must belong to this account with mode 700; the owner of this computer fixes that, Harness does not change it.'
+ const clone = "This machine could not clone the project repository with the Harness GitHub App's token: Cloning stopped making progress. Check the connection and retry."
+
+ it.each([[storage, 'creation folder'], [clone, 'clone the project repository']])('is left out by one such failure, with why (%#)', (error, said) => {
+ const reason = faulted([fault('s1', error)], 'm1', {}, now)
+ expect(reason).toContain(said)
+ expect(reason).toContain('30 minutes')
+ })
+ it('is not left out for any other failure, an older one, or one a later start got past', () => {
+ expect(faulted([fault('s1', 'The engine did not start.')], 'm1', {}, now)).toBeNull()
+ expect(faulted([fault('s1', storage, now - STALL_RETRY_MS - 1)], 'm1', {}, now)).toBeNull()
+ expect(faulted([fault('s1', storage), { ...fault('s2', ''), error: null, harnessId: 'h' }], 'm1', {}, now)).toBeNull()
+ expect(faulted([fault('s1', storage, now - 60_000, '0.5.1')], 'm1', { clientVersion: '0.5.6' }, now)).toBeNull()
+ expect(faulted([fault('s1', storage)], 'm2', {}, now)).toBeNull()
+ })
+ it('keeps the machine out of the route\'s new agents, naming the reason', async () => {
+ const t = tab(); Object.assign(t.state, { starts: [fault('s', clone, Date.now() - 60_000)] })
+ const s = scoped({ tab: t })
+ await routeTask({ ...input, assessment: { ...input.assessment, difficulty: 'high' } }, s, where, opener())
+ const decision = recorded(s).command.decision
+ expect(decision.candidates.some((c: { title: string; machineId: string }) => c.title.startsWith('New agent') && c.machineId === 'm1')).toBe(false)
+ expect(JSON.stringify(decision.excluded)).toContain('clone the project repository')
+ })
+ })
// Mac Auto, Swarm autonomous-harness, 2026-10-29: two starts failed on Harness bugs later fixed and released, and the machine
// stayed out of every route until a person started an agent there by hand.
it('lets a machine back into routes once its failed starts say nothing about it: updated since, or 30 minutes old', () => {
diff --git a/cli/src/superTabs/routeCommand.ts b/cli/src/superTabs/routeCommand.ts
index 4a3796851..f63b0d7b3 100644
--- a/cli/src/superTabs/routeCommand.ts
+++ b/cli/src/superTabs/routeCommand.ts
@@ -169,6 +169,25 @@ export function heldByStarts(starts: Json[], machineId: string, now = Date.now()
return held
}
+/** What a start's reason says when its machine could not use its own storage or clone the project (task #3861): the fixed openings
+ * this CLI writes (superTabs/start.ts, projectFolder.ts), which say a fault of the machine and not of the request. */
+const MACHINE_FAULTS: Array<[RegExp, string]> = [
+ [/^CREATION_STORAGE_FAILED: /, 'its creation folder cannot be used'],
+ [/^This machine could not clone the project repository with the Harness GitHub App's token/, 'it could not clone the project repository'],
+]
+/** Why [machineId] takes no new agents after its last start failed on a fault of the machine itself, else null: one such failure
+ * is enough, since the next start would meet the same fault (River, 11-06: five re-routes in a day). It clears as [stalled] does:
+ * a later start that launched, its daemon on another version than the failure was dispatched to, or [STALL_RETRY_MS]. */
+export function faulted(starts: Json[], machineId: string, pool: Json = {}, now = Date.now()): string | null {
+ const newest = starts.filter(s => object(s.request).machineId === machineId && !MODEL_NOT_OFFERED.test(String(s.error ?? ''))).at(-1)
+ if (!newest || newest.harnessId || typeof newest.error !== 'string') return null
+ const fault = MACHINE_FAULTS.find(([pattern]) => pattern.test(newest.error as string))
+ if (!fault) return null
+ if (typeof pool.clientVersion === 'string' && typeof newest.dispatchedVersion === 'string' && newest.dispatchedVersion !== pool.clientVersion) return null
+ const at = finite(newest.dispatchedAt) ? newest.dispatchedAt : finite(newest.requestedAt) ? newest.requestedAt : null
+ if (at !== null && now - at >= STALL_RETRY_MS) return null
+ return `Its last start on this machine failed: ${fault[1]}; its owner can check the machine. This clears once a start there succeeds, its Harness is updated, or 30 minutes pass.`
+}
export function stalled(starts: Json[], machineId: string, pool: Json = {}, now = Date.now()): boolean {
const last = starts.filter(s => object(s.request).machineId === machineId && !MODEL_NOT_OFFERED.test(String(s.error ?? ''))).slice(-2)
if (last.length !== 2 || !last.every(s => !s.harnessId && (!!s.error || s.dispatched !== true))) return false
@@ -406,6 +425,8 @@ export async function routeTask(input: { tabId: string; conversationId: string;
machine.accessNotes = productionNotes(listed, listed && macPoolOf(listed), needed)
}
machine.stalled = stalled(list(state.starts), machineId, list(state.machines).find(m => m.machineId === machineId))
+ const fault = faulted(list(state.starts), machineId, list(state.machines).find(m => m.machineId === machineId))
+ if (fault) machine.unready = { ...(machine.unready ?? READY), all: [...(machine.unready ?? READY).all, fault] }
machine.held = heldByStarts(list(state.starts), machineId)
}
// One machine (docs/plans/2026-10-24-swarm-team-account.md): a Mac's Harness Team account is that Mac, under its name. A
@@ -841,7 +862,7 @@ async function probeMachine(machineId: string, { name: machineName, status, acco
const os = String(resources.os)
const unfit = NO_SWARM_AGENTS_ON.includes(os) ? [`Swarm agents do not run on ${os} yet.`] : []
const allowance = quotaOf2(inspected.quota)
- probes.push(newProbe(m, [...(inspected.allowed ? [] : reasons), ...unfit, ...unreached], allowance, inspected.unknown.length === 0 && inspected.quota.known, load,
+ probes.push(newProbe(m, [...(inspected.allowed ? [] : reasons), ...unfit, ...unready.all, ...unreached], allowance, inspected.unknown.length === 0 && inspected.quota.known, load,
[...(stuck ? [STALLED] : []), ...usedUp(allowance)]))
}
return probes
diff --git a/cli/src/superTabs/start.spec.ts b/cli/src/superTabs/start.spec.ts
index da85df99f..a8a6f69d0 100644
--- a/cli/src/superTabs/start.spec.ts
+++ b/cli/src/superTabs/start.spec.ts
@@ -266,6 +266,24 @@ describe('Swarm permission mode', () => {
expect(f.open).not.toHaveBeenCalled()
})
+ // Task #3861: a daemon whose creation folder is unusable answers the status check with its code and no creationId. That is a
+ // fault of this machine, said with the daemon's own words, and not an uncertain launch.
+ it('returns the daemon\'s code and reason when its receipts cannot be read, as a fault of this machine', async () => {
+ const f = fixture()
+ const detail = 'The creation folder ~/.harness/cli/data/agent-creations is not usable by this account (permissions).'
+ f.request.mockImplementation(async (type: string) => type === 'agent_create_status' ? { error: 'CREATION_STORAGE_FAILED', detail } : {})
+ const result = await startAgent({ action: 'resume', tabId: 'tab', startId: 'start' }, f.scoped, where, f.open)
+ expect(result).toMatchObject({ error: 'START_MACHINE_FAULT', startId: 'start', creationId: f.start.creationId })
+ expect(result.detail).toBe(`CREATION_STORAGE_FAILED: ${detail}`)
+ expect(f.request.mock.calls.map(c => c[0])).toEqual(['agent_create_status'])
+ })
+
+ it('still reads a status answer without a creationId or a code as uncertain', async () => {
+ const f = fixture()
+ f.request.mockImplementation(async (type: string) => type === 'agent_create_status' ? {} : {})
+ expect(await startAgent({ action: 'resume', tabId: 'tab', startId: 'start' }, f.scoped, where, f.open)).toMatchObject({ error: 'START_UNCERTAIN' })
+ })
+
it.each(['opencode', 'kilo'])('keeps a dispatched legacy %s start uncertain without marking it failed', async engine => {
const f = fixture()
Object.assign(f.start.request, { engine })
diff --git a/cli/src/superTabs/start.ts b/cli/src/superTabs/start.ts
index cc95fee8f..d59cd7b32 100644
--- a/cli/src/superTabs/start.ts
+++ b/cli/src/superTabs/start.ts
@@ -342,8 +342,16 @@ async function startOnce(input: Json, scoped: ScopedRequest, where: Where, open:
try {
let refusal: string | null = null
let native = await target.request('agent_create_status', { creationId }, 10_000)
- if (native.creationId !== creationId) return { error: 'START_UNCERTAIN', startId, creationId,
- detail: 'The machine did not confirm the requested creation receipt. Nothing was dispatched.' }
+ if (native.creationId !== creationId) {
+ // A daemon that answers with its own code (its receipts folder cannot be used) has a fault the Swarm can be told, not an
+ // uncertain launch: stone7890's Mac waited hours on "did not confirm" (task #3861). Its words carry no secret.
+ if (typeof native.error === 'string' && /^[A-Z_]{3,60}$/.test(native.error)) {
+ const detail = typeof native.detail === 'string' ? `: ${native.detail.slice(0, 400)}` : ''
+ return { error: 'START_MACHINE_FAULT', startId, creationId, detail: `${native.error}${detail}` }
+ }
+ return { error: 'START_UNCERTAIN', startId, creationId,
+ detail: 'The machine did not confirm the requested creation receipt. Nothing was dispatched.' }
+ }
if (native.state === 'missing') {
if (start.dispatched) return { error: 'START_UNCERTAIN', startId, creationId,
detail: 'This start was submitted but its machine has no receipt. Inspect the machine before creating another agent.' }
diff --git a/docs/plans/2026-11-06-start-says-why-plan.md b/docs/plans/2026-11-06-start-says-why-plan.md
new file mode 100644
index 000000000..46c81cfbc
--- /dev/null
+++ b/docs/plans/2026-11-06-start-says-why-plan.md
@@ -0,0 +1,38 @@
+# A start that can't launch says why, and the PM sees it — Plan
+
+**Goal:** A start stuck on a machine fault shows the fault's reason (the daemon's code and, for a permissions problem, the folder and the fix) to the PM and the route, and fails within 5 minutes so the PM can route elsewhere.
+
+**Architecture:** The daemon's `agent_create_status` answers `{ error: 'CREATION_STORAGE_FAILED' }` without the creationId when its receipts folder cannot be used; the host's start turned that into `START_UNCERTAIN` ("did not confirm the receipt"), which machines.ts never fails. (1) The receipt error carries a `detail` for a permissions problem: the folder (home shown as `~`) and what its owner does, never an automatic chmod or sudo. (2) The daemon replies with it, the host's start returns `START_MACHINE_FAULT` with the code and detail. (3) machines.ts reports the reason to the server (`agent.startWaiting`) and fails a start that is not dispatched after 5 minutes of the same fault. (4) The backend stores the reason on the start, shows it in status and the route, clears it when the start settles or fails, and a failed start counts as one.
+
+**Tech Stack:** TypeScript, vitest (cli/src, backend/src).
+
+**Spec:** task #3861.
+
+## Global Constraints
+- No secret in a reason: the folder name, the daemon's code, the fix in words. Never fix permissions automatically or with sudo.
+- A start already dispatched (a launch may have happened) is never failed from here.
+- Placement (a Team-only entry never lands on the own-account entry) waits for the concrete case from the PM; backend `ownAccountTeamEntry` (#3060) already refuses the named case.
+
+## Review Focus
+- No secret or path beyond the creation folder in a reason; the failure cannot be triggered by another account.
+- `START_MACHINE_FAULT` is not in `NOT_REFUSED` semantics by accident: only an undispatched start is failed.
+
+## Task 1: the receipt error says which folder and why (cli/src/lib/agentCreationReceipt.ts, core/agents/launches.ts)
+- [ ] Failing tests: a folder the account cannot open throws `CREATION_STORAGE_FAILED` with a detail naming the folder and permissions, no sudo; the status reply carries the detail.
+- [ ] Implement.
+
+## Task 2: the start returns the fault (cli/src/superTabs/start.ts)
+- [ ] Failing test: a status answer with an error code and detail returns `START_MACHINE_FAULT` with both, not `START_UNCERTAIN`.
+- [ ] Implement.
+
+## Task 3: the host reports it and fails after 5 minutes (cli/src/superTabs/machines.ts)
+- [ ] Failing tests: the first pass sends `agent.startWaiting` once per reason; 5 minutes on, an undispatched start gets `agent.startFailed` with the reason; a dispatched one does not.
+- [ ] Implement.
+
+## Task 4: the backend stores and shows it (backend/src/superTabs)
+- [ ] Failing tests: `agent.startWaiting` sets `waiting` on the start; status and the route show it; settling or failing clears it; the failed start counts like any other.
+- [ ] Implement.
+
+## Task 5 (added by the PM, 11-06): every failure carries its reason; the route skips a faulted machine
+- [ ] Failing tests: `publicReason` tells the creation-folder and clone faults in their fixed words and nothing a host appends (backend `startFailure.test.ts`); the route leaves out a machine whose last start failed on its own storage or clone, naming why, until a start succeeds, its Harness updates, or 30 minutes pass (`faulted` in `routeCommand.ts`).
+- [ ] Implement.