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
Swarm: a failed start tells the group a generic reason; only its Lead and machine owner read the raw one (#1851)
0xken15fc29730e30e1
diff --git a/backend/integration/superTabLiveness.test.ts b/backend/integration/superTabLiveness.test.tsindex 0f84d511b..bcacc4e10 100644--- a/backend/integration/superTabLiveness.test.ts+++ b/backend/integration/superTabLiveness.test.ts@@ -481,7 +481,7 @@ describe('an agent whose task was lost', () => {})describe('a start that never runs', () => {- it('fails 3 minutes after dispatch, naming its machine, and tells the Lead in its group', async () => {+ it('fails 3 minutes after dispatch, naming its machine to its Lead only, and tells the Lead in its group', async () => {const f = await swarm()await f.beat(f.clock.now)const decision = { assessment: { difficulty: 'low', risk: 'low', why: 'Small task.' },@@ -501,7 +501,9 @@ describe('a start that never runs', () => {expect((await f.timed.read(owner, f.tab)).state.starts!.find(s => s.id === startId)!.error).toBeNull()f.clock.now = dispatched + 3 * MINUTE + 1const told = (await f.leadInbox()).find(m => (m.source as { kind?: string }).kind === 'start-timeout')!- expect(told).toMatchObject({ conversationId: 'lead', text: 'Could not start Builder: Worker Mac did not start it within 3 minutes.' })+ // Every group member reads the notice, so it names no machine (review of #1847); the start's Lead reads which one.+ expect(told).toMatchObject({ conversationId: 'lead', text: 'Could not start Builder: its machine did not start it within 3 minutes.' })+ expect((await f.timed.start(host, f.tab, startId, f.lead)).error).toBe('Worker Mac did not start it within 3 minutes')await expect(onMachine({ type: 'agent.started', startId, harnessId: randomUUID(), configuration: config })).rejects.toMatchObject({ code: 'START_FAILED' })})diff --git a/backend/integration/superTabTeam.test.ts b/backend/integration/superTabTeam.test.tsindex 19b57c953..2f6a638f6 100644--- a/backend/integration/superTabTeam.test.ts+++ b/backend/integration/superTabTeam.test.ts@@ -404,7 +404,9 @@ describe('a teammate\'s work and the machines that take it', () => {await expect(hostRun(f.tab, { type: 'agent.startDispatch', startId: queued })).rejects.toMatchObject({ code: 'PRIVACY_CHECK_FAILED' })const failed = (await store.read(owner, f.tab)).state.starts!.find(s => s.id === queued)!expect(failed).toMatchObject({ dispatched: false, error: expect.stringContaining('is not private (gitconfig') })- expect((await store.messages(owner, f.tab, f.teamGroup, {})).messages.at(-1)!.text).toMatch(/^Could not start Builder: The Harness Team account on MacBook Pro · Team is not private/)+ // The group reads a generic reason: the check's detail names the machine and files on it (review of #1847).+ expect((await store.messages(owner, f.tab, f.teamGroup, {})).messages.at(-1)!.text)+ .toBe('Could not start Builder: its machine could not prepare or launch it. The Lead and the machine owner can read why.')expect((await poolRows(store, team, 'team-mac')).find(p => p.tabId === f.tab)!.starts.map(s => s.id)).not.toContain(queued)// A stale check may pass again by itself: that start keeps waiting for it.const passedAgain = { ...PASSED, checkedAt: Date.now() + 1 }diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex 21c0efe19..2897fc818 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -1610,7 +1610,7 @@ it('marks every row the system writes in the owner\'s name, so a Lead cannot quorun({ type: 'machine.contribute', machineId: 'mac', name: 'Mac', cwd: '/swarm', engines: ['codex'], maxAgents: 2 },{ contribution: { machineOwnerId: 'owner', contributorId: 'owner' }, abandonedStartIds: ['s2'] })expect(rows.map(r => r.text)).toEqual(expect.arrayContaining(['Builder never started and will not start now. Start it again if still needed.',- 'Could not start Builder: Launch refused.', 'owner removed worker from the Swarm.']))+ 'Could not start Builder: its machine could not prepare or launch it. The Lead and the machine owner can read why.', 'owner removed worker from the Swarm.']))expect(rows.filter(r => !r.source).map(r => r.text)).toEqual([])})@@ -1625,12 +1625,51 @@ it('delivers a failed start\'s notice to the Lead of its group, and to nobody whrequest: { conversationId, machineId: 'mac', name: 'Builder' }, error: null })f.state.starts = [start('s1', 'lead'), start('s2', group)] as neverexpect(f.run({ type: 'agent.startFailed', startId: 's1', error: 'Launch refused.' }, owner).messages)- .toMatchObject([{ conversationId: 'lead', text: 'Could not start Builder: Launch refused.', recipients: [lead] }])+ .toMatchObject([{ conversationId: 'lead', text: 'Could not start Builder: its machine could not prepare or launch it. The Lead and the machine owner can read why.', recipients: [lead] }])// A Lead that left the group's members is not told there, as a removed machine's notice is not (removeMachine).Object.assign(f.state.conversations.find(c => c.id === group)!, { leadId: lead, agentIds: [] })expect(f.run({ type: 'agent.startFailed', startId: 's2', error: 'Launch refused.' }, owner).messages).toMatchObject([{ conversationId: group, recipients: [] }])})+// A start's raw reason can name its machine, a folder on it or a token problem, and every group member reads the group+// (review of #1847): they read a generic reason, and only the Lead and the machine owner read the raw one.+describe('a failed start\'s reason', () => {+ const RAW = 'Studio (host-mac) could not prepare /Users/ken/swarm/project: the Harness GitHub App token ghs_abc123 is not in the form GitHub gives.'+ const failed = (f: ReturnType<typeof fixture>, error: string | null = null) => {+ f.state.starts = [{ id: 's1', actorKey: 'person:owner', contributorId: 'owner', membershipGeneration: f.state.people[0]!.generation,+ machineOwnerId: 'peer', request: { conversationId: 'lead', machineId: 'host-mac', name: 'Builder' }, harnessId: null, dispatched: true, error }] as never+ }+ it('tells the group a generic reason, never the machine, a folder, a token or the raw error', () => {+ const f = fixture(); f.invite()+ failed(f)+ const [notice] = f.run({ type: 'agent.startFailed', startId: 's1', error: RAW }, owner).messages+ expect(notice!.text).toBe('Could not start Builder: its machine could not prepare or launch it. The Lead and the machine owner can read why.')+ for (const hidden of ['Studio', 'host-mac', '/Users', 'token', 'ghs_', RAW]) expect(notice!.text).not.toContain(hidden)+ // The start keeps the raw reason for those who may read it.+ expect(f.state.starts![0]!.error).toBe(RAW)+ })+ it('hands the raw reason on the start only to its Lead and the machine owner', () => {+ const f = fixture(); f.invite()+ const lead = f.add('lead-agent', 'owner', 'lead', true), worker = f.add('worker', 'owner')+ failed(f, RAW)+ f.state.starts![0]!.actorKey = `agent:${lead}`+ const read = (actor: Actor) => visibleState(f.state, actor).starts![0]!.error+ expect(read({ kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' })).toBe(RAW)+ expect(read(peer)).toBe(RAW)+ // The tab's owner and another agent of the group read only what it means.+ expect(read(owner)).toBe('Its machine could not prepare or launch it.')+ expect(read({ kind: 'agent', agentId: worker, machineOwnerId: 'host-owner' })).toBe('Its machine could not prepare or launch it.')+ // The group's Lead reads it even when a person made the start by hand.+ f.state.starts![0]!.actorKey = 'person:someone'+ expect(read({ kind: 'agent', agentId: lead, machineOwnerId: 'host-owner' })).toBe(RAW)+ // A start its machine never ran reads as that; the server's own reasons name nothing and read as they are.+ f.state.starts![0]!.error = 'Studio did not start it within 3 minutes'+ expect(read(owner)).toBe('Its machine did not start it within 3 minutes.')+ f.state.starts![0]!.error = 'Its machine was removed from the Swarm.'+ expect(read(owner)).toBe('Its machine was removed from the Swarm.')+ })+})+describe('the owner\'s rules, after review', () => {const set = (rule: Record<string, unknown>, text = 'Rule.') => ({ type: 'rule.set', rule, text } as Command)const request = (patch: Record<string, unknown> = {}) => ({ conversationId: 'lead', machineId: 'machine', engine: 'claude', model: 'opus', effort: 'high', name: 'Builder',diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 4ae571b40..54b3edf69 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -14,6 +14,7 @@ import { checkMentions, MAX_MENTIONS, type MentionTarget } from './mentions.js'import { ANSWERED_NOTICE, answerDecision, askDecisions, checkAsker, decisionChoices, decisionQuestion, MAX_QUESTIONS, type DecisionTarget } from './decisions.js'import { TERMINAL_KEYS, terminalAlert, terminalRequest, terminalResult, toLead, type TerminalRequest } from './terminal.js'import { loseTasks, renewLease, renewOwnTask } from './liveness.js'+import { ABANDONED, failureNotice, MACHINE_REMOVED } from './startFailure.js'import { digestStartsAfter, knownTimeZone } from './digest.js'import { credentialResult, redactCredentials, type CredentialKind } from './credentials.js'import { dirtyGroups, reportGroups, summarize } from './projectUpdates.js'@@ -611,7 +612,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma// A launch already under way would arrive with nowhere to go; it finishes in moments.if (pending.some(s => s.dispatched)) fail('STARTS_PENDING', 'An agent is starting on this machine. Try again in a moment.')for (const start of pending) {- start.error = 'Its machine was removed from the Swarm.'+ start.error = MACHINE_REMOVEDeffects.messages.push({ id: stableId(operationId, 'start', start.id), conversationId: start.request.conversationId, author: sender,text: `${start.request.name} will not start: its machine was removed from the Swarm.`, replyTo: null, recipients: [], source: SYSTEM_ROW })}@@ -901,7 +902,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma// Before a machine was contributed, a Lead's start on it that never dispatched was left pending for good (12 on Ken's// Mac that day) and refused every contribution. Those finish as failed; a dispatched or recent start still blocks.const abandoned = (state.starts ?? []).filter(s => context.abandonedStartIds?.includes(s.id))- for (const start of abandoned) start.error = 'Abandoned before it started.'+ for (const start of abandoned) start.error = ABANDONED// Each project's Lead chat hears once about its own starts, whichever of its groups asked.const byLeadChat = new Map<string, Set<string>>()for (const start of abandoned) {@@ -1274,7 +1275,7 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma// name for nobody, this notice left the round-device group without a worker for an hour (2026-10-27).const group = conversation(state, start.request.conversationId)const lead = group.leadId && group.agentIds.includes(group.leadId) ? group.leadId : null- message(group.id, `Could not start ${start.request.name}: ${command.error}`, lead ? [lead] : [], null, SYSTEM_ROW)+ message(group.id, failureNotice(start.request.name, command.error), lead ? [lead] : [], null, SYSTEM_ROW)break}if (start.error) fail('START_FAILED', 'This start failed. Use a new start request.')diff --git a/backend/src/superTabs/liveness.ts b/backend/src/superTabs/liveness.tsindex 18752acab..3045aa71b 100644--- a/backend/src/superTabs/liveness.ts+++ b/backend/src/superTabs/liveness.ts@@ -1,6 +1,7 @@import { activeWork, stableId, type Agent, type Assignment, type Author, type Conversation, type MessageDraft,type SuperTabState } from './model.js'import { agentDisplayName } from './agentNames.js'+import { failureNotice, TIMED_OUT_SUFFIX } from './startFailure.js'import { leadOf, toLead } from './terminal.js'// Work never sits with a dead owner (design: "A Swarm that never stops", 2026-10-26). A worker's active assignment is held@@ -163,13 +164,13 @@ export function sweepLiveness(state: SuperTabState, now: number): MessageDraft[]function failStalledStarts(state: SuperTabState, now: number): MessageDraft[] {return (state.starts ?? []).flatMap(start => {if (!start.dispatched || start.harnessId || start.error || start.dispatchedAt === undefined || now - start.dispatchedAt <= START_RUN_MS) return []- start.error = `${machineName(state, start.request.machineId)} did not start it within 3 minutes`+ start.error = `${machineName(state, start.request.machineId)}${TIMED_OUT_SUFFIX}`// Never a lookup that throws: these checks run inside every machine's report.const group = state.conversations.find(c => c.id === start.request.conversationId)const lead = group?.leadId ? state.agents.find(a => a.id === group.leadId) : undefinedif (!group || !lead) return []return [reachable(state, { id: stableId('start-timeout', start.id), conversationId: group.id, replyTo: null,recipients: group.agentIds.includes(lead.id) ? [lead.id] : [], author: writtenBy(state, lead),- text: `Could not start ${start.request.name}: ${start.error}.`, source: { kind: 'start-timeout', startId: start.id } })]+ text: failureNotice(start.request.name, start.error), source: { kind: 'start-timeout', startId: start.id } })]})}diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex 6aaf36d77..7337c996b 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto'import type { RouteDecisionEffect } from './routeRecord.js'import { agentDisplayName, assignAgentDisplayNames } from './agentNames.js'import { downSince, expireRemovals } from './machines.js'+import { publicReason, readsRawReason } from './startFailure.js'import { agentProjectId, agentSetRole, canReadAgent, canReadGroup, canReadProject, groupProject, ledProject, placeRules, projectsOf, sharedWithLeads, skillSetOf, type ProjectVisibility, type SwarmProject } from './projects.js'export type Role = 'owner' | 'collaborator' | 'viewer'@@ -539,6 +540,9 @@ export function visibleState(state: SuperTabState, actor: Actor, now = Date.now(else delete target.roleId}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 seen = seenMachineIds(visible)visible.conversations = visible.conversations.map(c => withSeenRequirement(c, seen))return visiblediff --git a/backend/src/superTabs/startFailure.ts b/backend/src/superTabs/startFailure.tsnew file mode 100644index 000000000..a8e05ec2c--- /dev/null+++ b/backend/src/superTabs/startFailure.ts@@ -0,0 +1,29 @@+/** What a failed start's reason says to a group member who is neither its Lead nor its machine's owner. A host's raw reason+ * can name the machine, a folder on it or a token problem (a privacy check's gitconfig path, the GitHub App token on+ * 2026-10-27), and every member reads the group and its starts (review of #1847). */+import { actorKey, type Actor, type AgentStart, type Conversation } from './model.js'++export const MACHINE_FAILED = 'Its machine could not prepare or launch it.'+export const TIMED_OUT = 'Its machine did not start it within 3 minutes.'+/** liveness.ts writes `<machine name> did not start it within 3 minutes`. */+export const TIMED_OUT_SUFFIX = ' did not start it within 3 minutes'+/** Reasons the server writes itself, which name nothing (commands.ts removeMachine and machine.contribute). */+export const MACHINE_REMOVED = 'Its machine was removed from the Swarm.'+export const ABANDONED = 'Abandoned before it started.'++export function publicReason(error: string): string {+ if (error === MACHINE_REMOVED || error === ABANDONED) return error+ return error.endsWith(TIMED_OUT_SUFFIX) ? TIMED_OUT : MACHINE_FAILED+}++/** The group's notice of a failed start; its Lead, woken by it, reads the raw reason on the start. */+export function failureNotice(name: string, error: string): string {+ const reason = publicReason(error)+ return `Could not start ${name}: ${reason[0]!.toLowerCase()}${reason.slice(1)}${reason === MACHINE_FAILED ? ' The Lead and the machine owner can read why.' : ''}`+}++/** Who reads a start's raw reason: whoever made it, its group's Lead, and its machine's owner. */+export function readsRawReason(actor: Actor, start: AgentStart, group: Conversation | undefined): boolean {+ if (start.actorKey === actorKey(actor)) return true+ return actor.kind === 'agent' ? !!group?.leadId && group.leadId === actor.agentId : actor.userId === start.machineOwnerId+}