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.

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.ts
index 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 + 1
const 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.ts
index 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.ts
index 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 quo
run({ 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 wh
request: { conversationId, machineId: 'mac', name: 'Builder' }, error: null })
f.state.starts = [start('s1', 'lead'), start('s2', group)] as never
expect(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.ts
index 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_REMOVED
effects.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.ts
index 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) : undefined
if (!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.ts
index 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 visible
diff --git a/backend/src/superTabs/startFailure.ts b/backend/src/superTabs/startFailure.ts
new file mode 100644
index 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
+}