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
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.tsindex 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 agentdiff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 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.waitingif (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.tsindex 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?: trueerror: 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.tsnew file mode 100644index 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.tsindex 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_PICKEDdiff --git a/cli/src/core/agents/launches.spec.ts b/cli/src/core/agents/launches.spec.tsindex 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.tsindex 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, preconst launchModel = status.state === 'created' ? receipts.createdLaunchModel(creationId) : nullreply({ 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.tsindex 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) => voiddiff --git a/cli/src/lib/agentCreationReceipt.ts b/cli/src/lib/agentCreationReceipt.tsindex 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.tsindex 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.tsindex 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) ?? beganif (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.tsindex 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.tsindex 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, accoconst 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 probesdiff --git a/cli/src/superTabs/start.spec.ts b/cli/src/superTabs/start.spec.tsindex 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.tsindex 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 = nulllet 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.mdnew file mode 100644index 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.