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
Merge batch 11-06 j0820: #3223 (#3261)
0xken15470438920e76
diff --git a/backend/integration/superTabBuddies.test.ts b/backend/integration/superTabBuddies.test.tsindex ff89241b4..c4e005aac 100644--- a/backend/integration/superTabBuddies.test.ts+++ b/backend/integration/superTabBuddies.test.ts@@ -682,9 +682,9 @@ describe('a person\'s Buddy chat before any Buddy, and the PM\'s private lines (expect((await f.store.messages(peer, f.tab, chat!, {})).messages.map(m => m.text)).toEqual(['First.', 'Second.'])})- // Any agent of the project tells a person now (project instructions, phase 4): its quiet Buddy chat is loaded for that- // agent's line too, not only the coordinator's (final review of the branch).- it('takes any agent\'s line in a quiet chat rather than opening a second one', async () => {+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts, task #3404): another agent's line is the PM's crew need, and the+ // PM's next line still lands in the quiet chat rather than opening a second one.+ it('takes the PM\'s line in a quiet chat rather than opening a second one, and gives the PM another agent\'s', async () => {const f = await swarm()const engineer = String((await f.execute({ type: 'agent.add', conversationId: 'lead', machineId: 'owner-mac', harnessId: randomUUID(), name: 'Engineer',configuration: config, lead: false })).result.agentId)@@ -694,8 +694,12 @@ describe('a person\'s Buddy chat before any Buddy, and the PM\'s private lines (const [chat] = await chats()await db.swarmGroup.updateMany({ where: { tabId: f.tab, key: chat }, data: { dormant: true } })await f.execute(tell('From the Engineer.'), owner, engineer)+ const needs = (await db.superTabMessage.findMany({ where: { tabId: f.tab, conversationId: 'lead' } }))+ .filter(m => (m.source as { kind?: string } | null)?.kind === 'crew-need')+ expect(needs).toEqual([expect.objectContaining({ recipientIds: [f.lead], source: expect.objectContaining({ crewNeed: expect.objectContaining({ agentId: engineer, personIds: [peer.sub] }) }) })])+ await f.execute(tell('Again.'), owner, f.lead)expect(await chats()).toEqual([chat])- expect((await f.store.messages(peer, f.tab, chat!, {})).messages.map(m => m.text)).toEqual(['First.', 'From the Engineer.'])+ expect((await f.store.messages(peer, f.tab, chat!, {})).messages.map(m => m.text)).toEqual(['First.', 'Again.'])})})diff --git a/backend/integration/superTabRead.test.ts b/backend/integration/superTabRead.test.tsindex 3e5fa6a5b..ec4ae0f13 100644--- a/backend/integration/superTabRead.test.ts+++ b/backend/integration/superTabRead.test.ts@@ -109,6 +109,12 @@ async function scene<T = void>(extra: (s: ReturnType<typeof swarm>, ids: { web:if (!report.ok) throw new Error(report.error)return { tabId, lead, worker, web, done, secretGroup, privateId, buddyId, secret, leads: state.leadsConversationId!, more }}+/** [scene]'s project with its PM gone from the project chat: with no PM, a worker asks a person itself, as before (crewNeeds.ts,+ * task #3404). */+const withoutPm = (s: ReturnType<typeof swarm>) => s.edit(state => {+ const chat = state.conversations.find(c => c.id === 'lead')!+ chat.agentIds = chat.agentIds.filter(id => id !== chat.leadId)+})const get = async (url: string, as: AuthUser = owner) => {const response = await app.inject({ method: 'GET', url, headers: { authorization: `Bearer ${as.sub}` } })return { status: response.statusCode, body: response.json() as { data: any; error?: { code: string; message: string } } }@@ -818,7 +824,7 @@ describe('decisions asked of one person (v2)', () => {})it('takes the person\'s one-tap answer once, and the answer reaches the asking worker and the Lead', async () => {- const s = await scene()+ const s = await scene(withoutPm)clock = Date.now()const assignmentId = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.groups.find((g: { key: string }) => g.key === s.web).data.assignment.idconst needs = await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship to everyone?',@@ -916,7 +922,7 @@ describe('decisions asked of one person (v2)', () => {})it('takes an answer in a conversation that went quiet with its task still waiting, counts it on a fresh first load, and tells both agents', async () => {- const s = await scene()+ const s = await scene(withoutPm)clock = Date.now()const assignmentId = (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.groups.find((g: { key: string }) => g.key === s.web).data.assignment.idawait post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship to everyone?',@@ -1251,7 +1257,7 @@ describe('decisions asked of one person (v2)', () => {})it('at the cap, a worker\'s needs-human update still records its status, tells the Lead and renews its lease, asking nothing new', async () => {- const s = await scene()+ const s = await scene(withoutPm)clock = Date.now()const assignment = async () => (await get(`/api/super-tabs/${s.tabId}/parts`, owner)).body.data.groups.find((g: { key: string }) => g.key === s.web).data.assignmentconst assignmentId = (await assignment()).id as string@@ -1294,7 +1300,7 @@ describe('decisions asked of one person (v2)', () => {expect(left.map(d => d.id)).toEqual(expect.arrayContaining(['recent', 'waiting']))})- it('keeps a decision of its own for another asker, another task, or other options with the same question text', async () => {+ it('keeps a decision of its own for other options with the same question text, and a worker\'s goes to the PM', async () => {const s = await scene()clock = Date.now()const [lead] = (await post(s.tabId, { type: 'decision.ask', conversationId: s.web, personId: peer.sub, questions: [question('Ship how?')] }, owner, s.lead))@@ -1305,11 +1311,12 @@ describe('decisions asked of one person (v2)', () => {expect((await post(s.tabId, { type: 'work.status', conversationId: s.web, assignmentId, status: 'needs_human', hold: { kind: 'reset', what: 'quota', at: '2026-11-06T09:00:00.000Z' }, result: 'Ship how?',ask: { personId: peer.sub, options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' } }, owner, s.worker)).status).toBe(200)const open = await decisions(s.tabId, peer)- expect(open).toHaveLength(3)- expect(new Set([lead, other, ...open.map(d => d.id)]).size).toBe(3)- // The worker reads its own question, and its answer reaches it.- const [mine] = await decisions(s.tabId, owner, 'open', s.worker)- expect(mine).toMatchObject({ askerAgentId: s.worker, assignmentId, options: ['Behind a flag', 'To everyone'] })+ // The worker's same question is the PM's crew need (crewNeeds.ts, task #3404): it opens nothing for peer.+ expect(open).toHaveLength(2)+ expect(new Set([lead, other, ...open.map(d => d.id)]).size).toBe(2)+ expect(await decisions(s.tabId, owner, 'open', s.worker)).toEqual([])+ const status = await db.superTabMessage.findFirst({ where: { tabId: s.tabId, conversationId: s.web }, orderBy: { sequence: 'desc' } })+ expect(status).toMatchObject({ recipientIds: [s.lead], source: { status: 'needs_human', crewNeed: { agentId: s.worker, personIds: [peer.sub] } } })})it('counts an open decision in a quiet conversation on a change read, which loads only some conversations', async () => {diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 6ef044664..2824e5998 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -4707,10 +4707,12 @@ describe('leaderboard credits written by the store (leaderboard/record.ts)', ()expect(await unblocks(tab, 'lead')).toEqual([expect.objectContaining({ personId: peer.sub, kind: 'decision', item: decisionId })])})+ // In a project with no PM a worker asks a person itself, as before (crewNeeds.ts, task #3404).it('credits a worker\'s question asked again after it moved on once, when its decision is answered', async () => {const { tab } = await fixture()await invite(tab)- const group = (await run(tab, { type: 'conversation.create', title: 'Release', brief: 'Ship it.', checks: [{ description: 'Shipped.', independent: false }] })).result.conversationId as string+ const quiet = (await run(tab, { type: 'project.create', name: 'Quiet', visibility: 'public', brief: '' })).result.projectId as string+ const group = (await run(tab, { type: 'conversation.create', projectId: quiet, title: 'Release', brief: 'Ship it.', checks: [{ description: 'Shipped.', independent: false }] })).result.conversationId as stringconst worker = (await run(tab, { type: 'agent.add', conversationId: group, machineId: 'test-host', harnessId: randomUUID(),name: 'Builder', configuration: config, lead: false })).result.agentId as stringconst assignmentId = (await run(tab, { type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId as stringdiff --git a/backend/src/superTabs/buddies.test.ts b/backend/src/superTabs/buddies.test.tsindex f18819f3a..72392004a 100644--- a/backend/src/superTabs/buddies.test.ts+++ b/backend/src/superTabs/buddies.test.ts@@ -1207,7 +1207,7 @@ describe('the PM\'s private line to a person (Ken, 10-29)', () => {expect(f.run(tell('peer', 'Again.'), agentActor(f.pm)).messages.map(m => [m.conversationId, m.recipients])).toEqual([[swarm.id, []], [older.id, []]])})- it('is any agent\'s of the project, never a person\'s, to a person in the Swarm, and needs a line', () => {+ it('is the PM\'s, never a person\'s, to a person in the Swarm, and needs a line', () => {const f = fresh()const worker = f.run({ type: 'agent.add', conversationId: f.group, harnessId: 'worker-harness', machineId: 'machine', name: 'Worker',configuration, lead: false }).result.agentId as string@@ -1215,8 +1215,11 @@ describe('the PM\'s private line to a person (Ken, 10-29)', () => {expect(() => f.run(tell('stranger'), agentActor(f.pm))).toThrow('person in this Swarm')expect(() => f.run(tell('peer', ' '), agentActor(f.pm))).toThrow()expect(f.state.conversations.filter(c => c.kind === 'buddy' || c.kind === 'swarm-buddy')).toEqual([])- // Who tells a person is workflow (project instructions, phase 4).- expect(f.run(tell(), agentActor(worker)).messages).toEqual([expect.objectContaining({ conversationId: peerSwarmChat, text: 'Your fix is merged.', recipients: [] }),+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts, task #3404): another agent's line is the PM's crew need, in the+ // project chat, and reaches no Buddy chat of the person.+ expect(f.run(tell(), agentActor(worker)).messages).toEqual([expect.objectContaining({ conversationId: f.app.conversationId, recipients: [f.pm],+ source: expect.objectContaining({ kind: 'crew-need' }) })])+ expect(f.run(tell(), agentActor(f.pm)).messages).toEqual([expect.objectContaining({ conversationId: peerSwarmChat, text: 'Your fix is merged.', recipients: [] }),expect.objectContaining({ conversationId: buddyChatId(f.app.projectId, { id: 'peer', generation: 'first' }), text: 'Your fix is merged.', recipients: [] })])})diff --git a/backend/src/superTabs/commands.test.ts b/backend/src/superTabs/commands.test.tsindex 0446e7221..877ef7ed6 100644--- a/backend/src/superTabs/commands.test.ts+++ b/backend/src/superTabs/commands.test.ts@@ -2398,10 +2398,12 @@ describe('any agent of the project', () => {expect(JSON.stringify(f.state)).toBe(before)})- it('lets any agent tell a person of its project', () => {- const { f, E } = project()+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts, task #3404): another agent's line is the PM's crew need.+ it('lets the PM tell a person of its project, and turns another agent\'s line into a crew need', () => {+ const { f, E } = project(), pm = f.leadActorf.invite()- const told = f.run({ type: 'person.tell', personId: 'peer', text: 'Your fix is merged.' }, E)+ expect(f.run({ type: 'person.tell', personId: 'peer', text: 'Your fix is merged.' }, E).messages.map(m => m.source?.kind)).toEqual(['crew-need'])+ const told = f.run({ type: 'person.tell', personId: 'peer', text: 'Your fix is merged.' }, pm)// In their one Buddy chat, marked with its project, and in their older chat there for older apps (Dee, 10-31).const swarm = f.state.conversations.find(c => c.kind === 'swarm-buddy')!, chat = f.state.conversations.find(c => c.kind === 'buddy')!expect(told.messages).toEqual([@@ -4312,10 +4314,13 @@ describe('Lead mentions', () => {expect(f.run(send('lead', []), as(lead)).messages[0]).not.toHaveProperty('mentions')})- it('lets any agent of the project tag, and refuses another project’s Lead and the removed Leads conversation; a person tags (mentions.test.ts)', () => {+ it('lets the PM tag, routes another agent’s tag to the PM, and refuses another project’s Lead and the removed Leads conversation; a person tags (mentions.test.ts)', () => {const { f, lead, secret } = swarm(), group = f.group(), worker = f.add('worker', 'owner', group)expect(f.run(send(group, ['peer'])).messages[0]!.mentions).toEqual(['peer'])- expect(f.run(send(group, ['peer']), as(worker)).messages[0]!.mentions).toEqual(['peer'])+ // People talk only to the PM (crewNeeds.ts, task #3404): the worker's tag is the PM's crew need.+ const byWorker = f.run(send(group, ['peer']), as(worker)).messages+ expect(byWorker.flatMap(m => m.mentions ?? [])).toEqual([])+ expect(byWorker.filter(m => m.source?.kind === 'crew-need').map(m => m.recipients)).toEqual([[lead]])expect(() => f.run(send(group, ['owner']), as(secret.lead))).toThrow('This conversation is unavailable.')expect(() => f.run(send(storeOldLeads(f.state), ['owner']), as(lead))).toThrow(expect.objectContaining({ code: 'LEADS_CONVERSATION_REMOVED' }))})diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex b5ab7c313..c7b93f5c2 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -29,6 +29,7 @@ import { projectRulesSchema, rulesDiff, rulesEqual, SEED_RULES, type ProjectRuleimport { accessRefusal, changeAccess, expireAccess, taskAccess } from './machineAccess.js'import { MAX_ATTACHMENTS, type Attachment } from './attachments.js'import { agentsNamedIn, checkMentions, MAX_MENTIONS, namedIn, saysName, textTags, withTags, type MentionTarget } from './mentions.js'+import { CREW_NEED_KIND, crewNeedPlace, crewNeedText, routedLine, routesToPm, type CrewNeed } from './crewNeeds.js'import { checkReason, heldReason, missingReason } from './heldReason.js'import { answerDecision, askDecisions, checkAsker, decisionChoices, decisionQuestion, MAX_OPEN_DECISIONS, MAX_QUESTIONS, type DecisionTarget } from './decisions.js'import { leadOf, TERMINAL_KEYS, terminalAlert, terminalRequest, terminalResult, toLead, type TerminalRequest, workedAgain } from './terminal.js'@@ -1045,6 +1046,15 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,...(attachments?.length ? { attachments } : {}), ...(mentions?.length ? { mentions } : {}), ...(holdMentions ? { holdMentions } : {}) })result.messageId = operationId}+ /** A crew need for the PM (crewNeeds.ts): its own row, to the PM alone, and the agent's result says where it went. Its+ * messageId is where the agent asked; an ask or a line with no message of its own points at this row. */+ const crewNeed = (group: Conversation, pm: string, need: Omit<CrewNeed, 'agentId' | 'messageId'> & { messageId?: string }, words: string,+ id = stableId(operationId, 'crew-need')) => {+ const full: CrewNeed = { agentId: actor.kind === 'agent' ? actor.agentId : '', ...need, messageId: need.messageId ?? id }+ effects.messages.push({ id, conversationId: crewNeedPlace(state, group, pm), author: sender, replyTo: null, recipients: [pm],+ text: crewNeedText(state, need.personIds, words, need.options, need.recommended), source: { kind: CREW_NEED_KIND, crewNeed: full } })+ effects.result.routedToPm = routedLine(state, need.personIds)+ }/** A route, start or assignment on a task by any agent of its project, or a post there by its coordinator, with its time:* it ends a person's held tags there (mentions.ts dropHeldTags) and restarts an unstarted start's clock (liveness.ts). Any* agent's post would end them while nobody handled the task (final review). It rides on the write each makes anyway. */@@ -2540,8 +2550,18 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,}case 'decision.ask': {const group = open(state, command.conversationId)- effects.decisions = askDecisions(state, group, command.personId, command.questions,+ const drafts = askDecisions(state, group, command.personId, command.questions,{ operationId, askerAgentId: checkAsker(state, actor, group), assignmentId: null })+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts): another agent's questions are the PM's crew needs, one+ // each, checked as a decision would be and opened for nobody.+ const pmInstead = routesToPm(state, actor, group)+ if (pmInstead) {+ command.questions.forEach((q, i) => crewNeed(group, pmInstead, { personIds: [command.personId], conversationId: group.id,+ question: q.question, options: q.options, recommended: q.recommended }, q.question, stableId(operationId, 'crew-need', String(i))))+ result.decisionIds = []+ break+ }+ effects.decisions = draftsresult.decisionIds = effects.decisions.map(d => d.id)break}@@ -2967,6 +2987,13 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,const project = projectOf(state, projectId)const to = state.people.find(p => p.id === command.personId) ?? fail('INVALID_PERSON', 'Tell a person in this Swarm.', 400)if (!canReadProject(state, { kind: 'person', userId: to.id, email: to.email }, project)) fail('INVALID_PERSON', `${usernameOf(state, to.id)} cannot read this project.`, 400)+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts): another agent's line is the PM's crew need, in the project chat.+ const projectChat = state.conversations.find(c => c.id === project.leadConversationId)+ const pmInstead = projectChat ? routesToPm(state, actor, projectChat) : null+ if (projectChat && pmInstead) {+ crewNeed(projectChat, pmInstead, { personIds: [to.id], conversationId: projectChat.id }, command.text)+ break+ }// To nobody: the person reads it; their Buddy, if they have one, is not asked to answer for them. In their one Buddy chat,// marked with its project so it hides once they lose it (buddies.ts hiddenProjectRow), and in their older chat there,// which older apps and the phone still show (spec: Older apps).@@ -3643,11 +3670,17 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,// Every username is worked out at once, and only for a post that names or picks someone.const names = picked.length || command.text.includes('@') ? swarmUsernames(state) : new Map<string, string>()const named = namedIn(state, command.text, names)- const unsaid = picked.filter(id => !named.includes(id) && !saysName(command.text, names.get(id)!))- const text = voice ? context.voiceWords?.[voice.id] ?? '' : withTags(unsaid.map(id => `@${names.get(id)}`), command.text)// A tag would tell a person about an agent-only notice they cannot see.const mentions = [...new Set([...picked, ...command.agentOnly ? [] : textTags(state, actor, group, named)])].slice(0, MAX_MENTIONS)if (command.mentionsIfNoWorker && !mentions.length) fail('INVALID_MENTION', 'Hold a tag only for a message that tags someone.', 400)+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts): an agent other than the PM tags only the person it answers,+ // and its other tags go to the PM as a crew need, written after the post below.+ const pmInstead = command.agentOnly ? null : routesToPm(state, actor, group)+ const answering = pmInstead && (command.replyTo || command.answers) && context.reply?.author.kind === 'person' ? context.reply.author.id : null+ const tagged = pmInstead ? mentions.filter(id => id === answering) : mentions+ const routedTags = mentions.filter(id => !tagged.includes(id))+ const unsaid = picked.filter(id => tagged.includes(id) && !named.includes(id) && !saysName(command.text, names.get(id)!))+ const text = voice ? context.voiceWords?.[voice.id] ?? '' : withTags(unsaid.map(id => `@${names.get(id)}`), command.text)if (command.replyTo && (!context.reply || context.reply.id !== command.replyTo || context.reply.conversationId !== group.id)) {fail('INVALID_REPLY', 'Reply to a message in this conversation.', 400)}@@ -3725,8 +3758,13 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,}if (command.notice && !command.agentOnly) fail('VALIDATION_ERROR', 'A skills notice is an agent-only notice to the agent itself.', 400)// The transcript still accepts a human message while the lead is unavailable. The UI can say why no delivery was created.- message(group.id, text, recipients, command.replyTo, command.agentOnly ? { ...AGENT_ONLY, ...command.notice ? { notice: command.notice } : {} } : undefined, attachments, mentions, command.mentionsIfNoWorker)+ message(group.id, text, recipients, command.replyTo, command.agentOnly ? { ...AGENT_ONLY, ...command.notice ? { notice: command.notice } : {} } : undefined, attachments, tagged,+ tagged.length ? command.mentionsIfNoWorker : undefined)if (!command.agentOnly) effects.messages.at(-1)!.post = true+ // After the post is marked: the crew need is the server's row for the PM, never a post of its own.+ if (pmInstead && routedTags.length) {+ crewNeed(group, pmInstead, { personIds: routedTags, messageId: operationId, conversationId: group.id }, text)+ }// After the person's message: nobody answers it, so its person is told why (Dee, review of #2447).if (buddyDown) buddyDownLine(group, buddyDown)if (poster && !command.agentOnly && !recipients.length) effects.result.reachedNoAgent = REACHED_NO_AGENT@@ -3946,10 +3984,17 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,// "no reason"; a reason that is sent is still checked. The refusal follows once the CLI sends one.if (holding && command.hold) checkReason(state, group, command.hold, context.now)let asked: string | undefined+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts): an agent's needs_human, whoever's assignment it is, when that+ // agent is not the PM, is the PM's crew need, and its question opens no decision for the person it names (review of #3223).+ const pmInstead = command.status === 'needs_human' ? routesToPm(state, actor, group) : nullif (command.ask) {if (command.status !== 'needs_human' || !command.result || actor.kind !== 'agent') {fail('INVALID_DECISION', 'An agent asks a person for a decision only when its work needs a human, with the question as its result.', 400)}+ // For the PM to ask: the person must be in the Swarm, as a decision's would.+ if (pmInstead) person(state, command.ask.personId)+ }+ if (command.ask && !pmInstead && command.result && actor.kind === 'agent') {const { personId, ...choices } = command.askconst drafts = askDecisions(state, group, personId, [{ question: command.result, ...choices }],{ operationId, askerAgentId: actor.agentId, assignmentId: assignment.id })@@ -3970,6 +4015,7 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,delete assignment.reviewFoundAt// And a task that came back to its Engineer is picked up, or handed over again (handed.ts).pickUp(assignment)+ // Whom the work waits on, for the board and liveness, even when the PM asks them: a record, which notifies nobody.if (command.ask) assignment.askedOf = command.ask.personIdelse if (command.status !== 'needs_human') delete assignment.askedOf// Why it waits lasts as long as the wait: the next status clears it.@@ -4003,9 +4049,20 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,: own ? (lead && ['needs_human', 'blocked', 'done'].includes(command.status) ? [lead] : []): [...command.status === 'stopped' ? [] : [assignment.agentId], ...lead ? [lead] : []]const recipients = [...new Set(told)].filter(id => actor.kind !== 'agent' || id !== actor.agentId)- const asked = !command.ask ? '' : effects.result.notAsked ? `\n\n${effects.result.notAsked}` : `\n\nAsked ${agentWrittenNameOf(state, person(state, command.ask.personId).id)}.`+ const askedName = command.ask ? agentWrittenNameOf(state, person(state, command.ask.personId).id) : ''+ const asked = !command.ask ? '' : pmInstead ? `\n\nFor the PM to ask ${askedName}.`+ : effects.result.notAsked ? `\n\n${effects.result.notAsked}` : `\n\nAsked ${askedName}.`+ // A needs_human for the PM is its crew need: on this row when the row reaches the PM, else on a row of its own there.+ const need = pmInstead ? { personIds: command.ask ? [command.ask.personId] : [], conversationId: group.id,+ ...command.result ? { question: command.result } : {}, ...command.ask ? { options: command.ask.options, recommended: command.ask.recommended } : {} } : null+ const onRow = need && pmInstead && actor.kind === 'agent' && recipients.includes(pmInstead)+ ? { crewNeed: { agentId: actor.agentId, ...need, messageId: operationId } } : {}// The status set, on the row: a Done waits for the coordinator's next digest, what needs someone does not (store.ts writeMessages).- message(group.id, `${label}${command.result ? `\n\n${command.result}` : ''}${asked}`, recipients, null, { ...SYSTEM_ROW, status: command.status })+ message(group.id, `${label}${command.result ? `\n\n${command.result}` : ''}${asked}`, recipients, null, { ...SYSTEM_ROW, status: command.status, ...onRow })+ if (need && pmInstead) {+ if (onRow.crewNeed) effects.result.routedToPm = routedLine(state, need.personIds)+ else crewNeed(group, pmInstead, { ...need, messageId: operationId }, command.result ?? label)+ }// The server opens a task's review steps when its pull request's files were read (openReviewSteps, below); when// they were not, the agent whose work is ready opens and assigns them (project instructions, phase 4). When no machine the project may use can start either engine, or soon none// will, the project's coordinator hears it once, in its chat (reviewCapacity.ts).diff --git a/backend/src/superTabs/crewNeeds.test.ts b/backend/src/superTabs/crewNeeds.test.tsnew file mode 100644index 000000000..ba92ef490--- /dev/null+++ b/backend/src/superTabs/crewNeeds.test.ts@@ -0,0 +1,174 @@+import { describe, expect, it } from 'vitest'+import { applyCommand, type Command, type CommandContext } from './commands.js'+import { CREW_NEED_KIND, crewNeedOf } from './crewNeeds.js'+import { agentOnly, createSuperTab, type Actor, type MessageDraft } from './model.js'++// People talk only to the PM (anh Dee, 2026-11-05; task #3404, River's ruling): an agent's tag of a person, its needs_human,+// its decision.ask and its person.tell become a crew need for the PM, and the agent is told. The PM tags anyone; any other+// agent tags only the person it is answering. With no PM in the project, everything stays as before.++const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }+const peer: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'peer', email: '[email protected]' }+const third: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'third', email: '[email protected]' }+const configuration = { engine: 'claude', model: null, effort: null, contextWindow: null, engineVersion: null }+const asAgent = (agentId: string): Actor => ({ kind: 'agent', agentId, machineOwnerId: 'owner' })+const choices = { options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'The release' }++function fixture() {+ let state = createSuperTab('tab', 'Pilot', { id: 'owner', email: owner.email }, 'prod')+ let next = 0+ const run = (command: Command, actor: Actor = owner, context: Partial<CommandContext> = {}) => {+ const effects = applyCommand(state, actor, command, { operationId: `op${next++}`, now: 1000,+ contribution: { machineOwnerId: 'owner', contributorId: actor.kind === 'person' ? actor.userId : 'owner' }, ...context })+ state = effects.state+ return effects+ }+ for (const who of [peer, third]) {+ const invited = run({ type: 'invite.create', email: who.email, role: 'collaborator', conversationId: 'lead' })+ run({ type: 'invite.accept', inviteId: invited.result.inviteId as string }, who)+ }+ const project = (name: string) => run({ type: 'project.create', name, visibility: 'public', brief: '' }).result as { projectId: string; conversationId: string }+ const add = (conversationId: string, harnessId: string, lead: boolean) => run({ type: 'agent.add', conversationId, harnessId, machineId: 'machine',+ name: harnessId, lead, configuration }).result.agentId as string+ const app = project('App')+ const pm = add(app.conversationId, 'pm', true)+ const worker = add(app.conversationId, 'worker', false)+ const group = run({ type: 'conversation.create', projectId: app.projectId, title: 'Copy', brief: '', checks: [] }).result.conversationId as string+ run({ type: 'conversation.agent', conversationId: group, agentId: worker, present: true, lead: false })+ /** A post, with the context the store gives a reply or an answer: the message it answers. */+ const post = (actor: Actor, text: string, extra: Partial<Extract<Command, { type: 'message.send' }>> = {}, reply?: MessageDraft, conversationId = group) =>+ run({ type: 'message.send', conversationId, text, replyTo: null, recipientIds: [], ...extra }, actor,+ reply ? { reply: { id: reply.id, conversationId: reply.conversationId, author: reply.author, createdAt: 1000, thread: reply.thread ?? reply.id } } : {})+ return { run, add, project, post, app, pm, worker, group, get state() { return state } }+}++const own = (effects: { messages: MessageDraft[] }, conversationId: string) => effects.messages.find(m => m.conversationId === conversationId && !m.source)!+const needs = (effects: { messages: MessageDraft[] }) => effects.messages.filter(m => crewNeedOf(m.source))++describe('an agent’s tag of a person goes to the PM', () => {+ it('writes no tag for the person, and a crew need reaches the PM alone, saying so to the agent', () => {+ const f = fixture()+ for (const sent of [f.post(asAgent(f.worker), '@peer please confirm the copy'), f.post(asAgent(f.worker), 'Please confirm the copy', { mentions: ['peer'] })]) {+ const message = own(sent, f.group)+ expect(message.mentions ?? []).toEqual([])+ // A tag picked but not said is not written into the text either: the person would read it as a tag.+ expect(message.text).not.toContain('@peer please confirm the copy\n')+ expect(needs(sent)).toHaveLength(1)+ const [need] = needs(sent)+ expect(need).toMatchObject({ conversationId: f.group, recipients: [f.pm], source: { kind: CREW_NEED_KIND } })+ expect(need!.mentions ?? []).toEqual([])+ expect(agentOnly(need!.source, need!.recipients)).toBe(true)+ expect(crewNeedOf(need!.source)).toEqual({ agentId: f.worker, personIds: ['peer'], messageId: message.id, conversationId: f.group })+ expect(need!.text).toContain('peer')+ expect(sent.result.routedToPm).toMatch(/PM/)+ }+ })++ it('keeps the PM’s tags, a person’s tags, and an agent’s tag of the person it answers', () => {+ const f = fixture()+ const byPm = f.post(asAgent(f.pm), '@peer please confirm')+ expect(own(byPm, f.group).mentions).toEqual(['peer'])+ expect(needs(byPm)).toEqual([])+ const byPerson = f.post(owner, '@peer please confirm')+ expect(own(byPerson, f.group).mentions).toEqual(['peer'])+ expect(needs(byPerson)).toEqual([])+ // The worker answers peer's question: peer is tagged; third, whom it did not answer, goes to the PM.+ const question = own(f.post(peer, 'Is the copy final?'), f.group)+ const answer = f.post(asAgent(f.worker), '@peer yes, and @third should check it', { answers: question.id }, question)+ expect(own(answer, f.group).mentions).toEqual(['peer'])+ expect(needs(answer).map(m => crewNeedOf(m.source)!.personIds)).toEqual([['third']])+ const inThread = f.post(asAgent(f.worker), '@peer it is in', { replyTo: question.id }, question)+ expect(inThread.messages.find(m => !m.source)!.mentions).toEqual(['peer'])+ expect(needs(inThread)).toEqual([])+ })++ it('leaves tags as they are in a project with no PM', () => {+ const f = fixture()+ const other = f.project('Other')+ const helper = f.add(other.conversationId, 'helper', false)+ const task = f.run({ type: 'conversation.create', projectId: other.projectId, title: 'Docs', brief: '', checks: [] }).result.conversationId as string+ f.run({ type: 'conversation.agent', conversationId: task, agentId: helper, present: true, lead: false })+ const sent = f.post(asAgent(helper), '@peer please confirm', {}, undefined, task)+ expect(own(sent, task).mentions).toEqual(['peer'])+ expect(needs(sent)).toEqual([])+ expect(sent.result.routedToPm).toBeUndefined()+ })++ it('still brings a person’s reply to the agent it answers', () => {+ const f = fixture()+ const asked = own(f.post(asAgent(f.worker), 'Which copy do we ship?'), f.group)+ const reply = f.post(peer, 'The short one', { replyTo: asked.id }, asked)+ expect(reply.messages.find(m => !m.source)!.recipients).toContain(f.worker)+ const below = f.post(peer, 'The short one', { answers: asked.id }, asked)+ expect(own(below, f.group).recipients).toContain(f.worker)+ })+})++describe('an agent’s needs_human, decision ask and line to a person go to the PM', () => {+ const assigned = () => {+ const f = fixture()+ const assignmentId = f.run({ type: 'work.assign', conversationId: f.group, agentId: f.worker }).result.assignmentId as string+ return Object.assign(f, { assignmentId })+ }++ it('opens no decision for the person; the status row to the PM carries the crew need', () => {+ const f = assigned()+ const sent = f.run({ type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'needs_human',+ result: 'Ship to everyone, or behind a flag?', ask: { personId: 'peer', ...choices } }, asAgent(f.worker))+ expect(sent.decisions ?? []).toEqual([])+ const row = sent.messages.find(m => (m.source as { status?: string } | null)?.status === 'needs_human')!+ expect(row.recipients).toEqual([f.pm])+ expect(row.text).not.toContain('Asked peer')+ expect(crewNeedOf(row.source)).toEqual({ agentId: f.worker, personIds: ['peer'], messageId: row.id, conversationId: f.group,+ question: 'Ship to everyone, or behind a flag?', options: choices.options, recommended: 0 })+ expect(sent.result.routedToPm).toMatch(/PM/)+ // Whom it waits on stays on the task for the board, which notifies nobody.+ expect(f.state.conversations.find(c => c.id === f.group)!.assignment!.askedOf).toBe('peer')+ // Without a person named, the needs_human is the PM's crew need as well.+ const plain = f.run({ type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'needs_human', result: 'Which database?' }, asAgent(f.worker))+ const plainRow = plain.messages.find(m => (m.source as { status?: string } | null)?.status === 'needs_human')!+ expect(crewNeedOf(plainRow.source)).toMatchObject({ agentId: f.worker, personIds: [], question: 'Which database?' })+ })++ // Review of #3223, Important 1: routing is by who sends it, not whose assignment it is.+ it('routes another agent’s needs_human on the task to the PM as well, and keeps the PM’s own', () => {+ const f = assigned()+ const other = f.add(f.app.conversationId, 'other', false)+ f.run({ type: 'conversation.agent', conversationId: f.group, agentId: other, present: true, lead: false })+ const ask = (actor: Actor) => f.run({ type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'needs_human',+ result: 'Ship to everyone, or behind a flag?', ask: { personId: 'peer', ...choices } }, actor)+ const byOther = ask(asAgent(other))+ expect(byOther.decisions ?? []).toEqual([])+ expect(byOther.messages.map(m => crewNeedOf(m.source)).filter(Boolean)).toEqual([expect.objectContaining({ agentId: other, personIds: ['peer'] })])+ expect(byOther.result.routedToPm).toMatch(/PM/)+ f.run({ type: 'work.status', conversationId: f.group, assignmentId: f.assignmentId, status: 'working', result: null }, asAgent(f.worker))+ const byPm = ask(asAgent(f.pm))+ expect(byPm.decisions).toHaveLength(1)+ expect(byPm.messages.filter(m => crewNeedOf(m.source))).toEqual([])+ })++ it('turns a worker’s decision ask into a crew need, and keeps the PM’s', () => {+ const f = assigned()+ const question = { question: 'Ship how?', ...choices }+ const byWorker = f.run({ type: 'decision.ask', conversationId: f.group, personId: 'peer', questions: [question] }, asAgent(f.worker))+ expect(byWorker.decisions ?? []).toEqual([])+ expect(needs(byWorker).map(m => [m.recipients, crewNeedOf(m.source)])).toEqual([[[f.pm],+ { agentId: f.worker, personIds: ['peer'], messageId: needs(byWorker)[0]!.id, conversationId: f.group, question: 'Ship how?', options: choices.options, recommended: 0 }]])+ expect(byWorker.result.routedToPm).toMatch(/PM/)+ const byPm = f.run({ type: 'decision.ask', conversationId: f.group, personId: 'peer', questions: [question] }, asAgent(f.pm))+ expect(byPm.decisions).toHaveLength(1)+ expect(needs(byPm)).toEqual([])+ })++ it('turns a worker’s line to a person into a crew need in the project chat, and keeps the PM’s', () => {+ const f = assigned()+ const byWorker = f.run({ type: 'person.tell', personId: 'peer', text: 'Look at the mockup in #12' }, asAgent(f.worker))+ // Nothing lands in the person's Buddy chats: the crew need is the command's only message.+ expect(byWorker.messages.filter(m => !crewNeedOf(m.source))).toEqual([])+ expect(needs(byWorker).map(m => [m.conversationId, m.recipients, crewNeedOf(m.source)!.personIds])).toEqual([[f.app.conversationId, [f.pm], ['peer']]])+ expect(byWorker.result.routedToPm).toMatch(/PM/)+ const byPm = f.run({ type: 'person.tell', personId: 'peer', text: 'Look at the mockup in #12' }, asAgent(f.pm))+ expect(needs(byPm)).toEqual([])+ expect(byPm.messages.length).toBeGreaterThan(0)+ })+})diff --git a/backend/src/superTabs/crewNeeds.ts b/backend/src/superTabs/crewNeeds.tsnew file mode 100644index 000000000..1b627dbf2--- /dev/null+++ b/backend/src/superTabs/crewNeeds.ts@@ -0,0 +1,71 @@+/** People talk only to the PM (anh Dee, 2026-11-05; task #3404, River's ruling). When an agent other than its project's PM+ * tags a person, needs a person (needs_human), asks a person a decision or sends a person a line, the person is not told:+ * the PM gets a crew need, and the agent's command result says so. This routes; it never refuses. The PM tags anyone. Any+ * other agent may still tag the person it is answering (the author of the message it answers or replies to). A project with+ * no PM in its chat routes nothing, so its tags reach people as before.+ *+ * A crew need is either its own row (source kind `crew-need`: a tag, a decision ask, a line to a person) or the needs_human+ * status row the agent already writes to the PM (`source.crewNeed`). `crewNeedOf` reads both; the PM's inbox (#3403) lists+ * them. Neither is gathered into the notice digest (noticeDigest.ts DIGEST_KINDS). */+import { isBuddyChat } from './buddies.js'+import type { Actor, Conversation, SuperTabState } from './model.js'+import { agentWrittenNameOf } from './personNames.js'+import { groupProject } from './projects.js'++export const CREW_NEED_KIND = 'crew-need'+/** How much of the agent's words a crew need's text quotes; the PM reads the rest at its message. */+const QUOTE_MAX = 600++/** What the PM's inbox lists for one crew need. [messageId] is where the agent asked: its post, its status row, or the crew-need+ * row itself for an ask or a line that has no message of its own. */+export interface CrewNeed {+ agentId: string+ personIds: string[]+ messageId: string+ conversationId: string+ question?: string+ options?: string[]+ recommended?: number+}++/** The crew need a stored message's source carries, in either shape, or null. */+export function crewNeedOf(source: unknown): CrewNeed | null {+ const need = (source as { crewNeed?: unknown } | null | undefined)?.crewNeed as Partial<CrewNeed> | undefined+ return need && typeof need.agentId === 'string' && Array.isArray(need.personIds) && typeof need.messageId === 'string'+ && typeof need.conversationId === 'string' ? need as CrewNeed : null+}++/** The PM of [group]'s project: the lead of the project's chat, while it is in that chat; null when the project has none. */+export function projectPm(state: SuperTabState, group: Conversation): string | null {+ const project = groupProject(state, group)+ const chat = state.conversations.find(c => c.id === project.leadConversationId)+ return chat?.leadId && chat.agentIds.includes(chat.leadId) ? chat.leadId : null+}++/** The PM [actor]'s words to people in [group] go to instead, or null when they reach people as before: a person, the PM+ * itself, a Buddy chat, a project with no PM. */+export function routesToPm(state: SuperTabState, actor: Actor, group: Conversation): string | null {+ if (actor.kind !== 'agent' || isBuddyChat(group)) return null+ const pm = projectPm(state, group)+ return pm && pm !== actor.agentId ? pm : null+}++/** Where the PM reads a crew need about [group]: there when the PM is one of its members, else the project's chat. */+export function crewNeedPlace(state: SuperTabState, group: Conversation, pm: string): string {+ return group.agentIds.includes(pm) ? group.id : groupProject(state, group).leadConversationId+}++const namesOf = (state: SuperTabState, personIds: readonly string[]) => personIds.map(id => agentWrittenNameOf(state, id) ?? id).join(', ')+const quoted = (text: string) => text.length <= QUOTE_MAX ? text : `${text.slice(0, QUOTE_MAX - 1).trimEnd()}…`++/** A crew need row's text, for the PM: who it is for and the agent's words. */+export function crewNeedText(state: SuperTabState, personIds: readonly string[], words: string, options?: readonly string[], recommended?: number): string {+ const choices = options?.length ? `\n\nOptions: ${options.map((o, i) => i === recommended ? `${o} (recommended)` : o).join(' / ')}` : ''+ return `Crew need for ${namesOf(state, personIds) || 'a person'}, through you (people talk only to the PM):\n\n${quoted(words)}${choices}`+}++/** What the agent is told in its command's result. */+export function routedLine(state: SuperTabState, personIds: readonly string[]): string {+ const who = personIds.length ? namesOf(state, personIds) : 'a person'+ return `Sent to the PM as a crew need, not to ${who}: people talk only to the PM, who asks them and brings the answer back to you.`+}diff --git a/backend/src/superTabs/decisions.test.ts b/backend/src/superTabs/decisions.test.tsindex 2bde667ea..37611615e 100644--- a/backend/src/superTabs/decisions.test.ts+++ b/backend/src/superTabs/decisions.test.ts@@ -68,13 +68,14 @@ describe('asking a person for decisions', () => {questions: Array.from({ length: 11 }, (_, i) => question(`Question ${i}`)) }).success).toBe(false)})- it('opens a decision for the named person when a worker needs one on its own task, and still tells the Lead', () => {+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts, task #3404): a worker's question is the PM's crew need, and+ // opens no decision for the person it names.+ it('tells the Lead a worker needs a person on its own task, for the Lead to ask them', () => {const s = swarm()const needs = s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'needs_human', hold: HOLD, result: 'Ship to everyone, or behind a flag?',ask: { personId: 'peer', options: ['Behind a flag', 'To everyone'], recommended: 0, unblocks: 'Turning the feature on' } }, asAgent(s.worker))- expect(needs.decisions).toEqual([expect.objectContaining({ personId: 'peer', askerAgentId: s.worker, assignmentId: s.assignmentId,- question: 'Ship to everyone, or behind a flag?', recommended: 0, unblocks: 'Turning the feature on' })])- expect(needs.messages[0]).toMatchObject({ text: 'Needs a human\n\nShip to everyone, or behind a flag?\n\nAsked peer.', recipients: [s.lead] })+ expect(needs.decisions ?? []).toEqual([])+ expect(needs.messages[0]).toMatchObject({ text: 'Needs a human\n\nShip to everyone, or behind a flag?\n\nFor the PM to ask peer.', recipients: [s.lead] })// Without a person and options it reaches the Lead as before, who asks.const plain = s.run({ type: 'work.status', conversationId: s.group, assignmentId: s.assignmentId, status: 'needs_human', hold: HOLD, result: 'Which database?' }, asAgent(s.worker))expect(plain.decisions ?? []).toEqual([])@@ -82,13 +83,15 @@ describe('asking a person for decisions', () => {ask: { personId: 'peer', options: ['A', 'B'], recommended: 0, unblocks: 'X' } }, asAgent(s.worker))).toThrow('needs a human')})- // Who asks a person is workflow (project instructions, phase 4): any agent of the project, in its own project only.- it('lets any agent of the project ask a person', () => {+ // Who asks a person is workflow (project instructions, phase 4): any agent of the project, in its own project only, and+ // another agent than the PM asks through the PM (crewNeeds.ts, task #3404).+ it('lets any agent of the project ask, a worker through the PM', () => {const s = swarm()const task = s.state.conversations.find(c => c.id === s.group)!expect(checkAsker(s.state, asAgent(s.worker), task)).toBe(s.worker)const asked = s.run({ type: 'decision.ask', conversationId: s.group, personId: 'peer', questions: [question('Ship how?')] }, asAgent(s.worker))- expect(asked.decisions).toEqual([expect.objectContaining({ askerAgentId: s.worker, conversationId: s.group })])+ expect(asked.decisions ?? []).toEqual([])+ expect(asked.messages.map(m => [m.source?.kind, m.recipients])).toEqual([['crew-need', [s.lead]]])const other = s.run({ type: 'project.create', name: 'Other', visibility: 'public', brief: '' }).result as { projectId: string }const elsewhere = s.run({ type: 'conversation.create', projectId: other.projectId, title: 'Elsewhere', brief: '', checks: [] }).result.conversationId as stringconst state = structuredClone(s.state), leadsId = storeOldLeads(state), leads = state.conversations.find(c => c.id === leadsId)!diff --git a/backend/src/superTabs/mentions.test.ts b/backend/src/superTabs/mentions.test.tsindex b78642344..4aaf19496 100644--- a/backend/src/superTabs/mentions.test.ts+++ b/backend/src/superTabs/mentions.test.ts@@ -77,13 +77,14 @@ describe('people tagging people', () => {})// Who tags a person is workflow (project instructions, phase 4): any agent of the project, in its own project only.- it('lets any agent of the project tag people', () => {+ it('checks any agent’s tags, and routes a worker’s to the PM', () => {const f = fixture()const worker: Actor = { kind: 'agent', agentId: f.worker, machineOwnerId: 'owner' }const group = (id: string) => f.state.conversations.find(c => c.id === id)!expect(checkMentions(f.state, worker, group(f.group), ['peer', 'third', 'peer'])).toEqual(['peer', 'third'])- expect(f.send(f.group, ['peer'], worker).mentions).toEqual(['peer'])- expect(f.say(f.group, '@third please confirm', worker).mentions).toEqual(['third'])+ // People talk only to the PM (crewNeeds.ts, task #3404): the worker's tags are checked as before, and go to the PM.+ expect(f.send(f.group, ['peer'], worker).mentions ?? []).toEqual([])+ expect(f.say(f.group, '@third please confirm', worker).mentions ?? []).toEqual([])expect(() => checkMentions(f.state, worker, group(storeOldLeads(f.state)), ['peer'])).toThrow(expect.objectContaining({ code: 'INVALID_MENTION' }))})@@ -173,13 +174,14 @@ describe('tags in the text', () => {expect(f.say(f.group, '@owner and @peer').mentions).toEqual(['peer'])})- it('tags from the text of any agent of the project', () => {+ it('tags from the text of the PM, and not of another agent', () => {const f = fixture()const lead = { kind: 'agent' as const, agentId: f.lead, machineOwnerId: 'owner' }expect(f.say(f.app.conversationId, '@peer please confirm', lead).mentions).toEqual(['peer'])- // A worker posts in a task: the project chat holds only its coordinator among agents (#2207).+ // A worker posts in a task: the project chat holds only its coordinator among agents (#2207). People talk only to the PM+ // (crewNeeds.ts, task #3404): its tag is the PM's crew need, and its words are kept.const worker = f.say(f.group, '@peer please confirm', { kind: 'agent', agentId: f.worker, machineOwnerId: 'owner' })- expect(worker.mentions).toEqual(['peer'])+ expect(worker.mentions ?? []).toEqual([])expect(worker.text).toBe('@peer please confirm')})diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex f41f4919b..d896f22c8 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -701,6 +701,8 @@ export const NOTICE_READERS = {'pair-loop': 'recipients',// The server's routine notices to the coordinator, gathered into one message (noticeDigest.ts).'notice-digest': 'recipients',+ // An agent's tag, ask or line to a person, routed to the PM instead (crewNeeds.ts): the PM's alone. Never gathered.+ 'crew-need': 'recipients',// Each its own case in commands.ts, decided by the row (forRecipients): statuses, briefs, merges, starts, removals.system: 'people',// A save of the project's instructions was posted in the project chat until #3132 (Dee and Ken, 11-05): the rows storeddiff --git a/backend/src/superTabs/postRecipients.test.ts b/backend/src/superTabs/postRecipients.test.tsindex 7ab89aa59..05e23a7d9 100644--- a/backend/src/superTabs/postRecipients.test.ts+++ b/backend/src/superTabs/postRecipients.test.ts@@ -155,9 +155,13 @@ describe('the PM\'s deliveries in a fixture hour', () => {]const asked = post(f.lead, f.task, 'Is the migration reversible?', [f.dev])[0]!rows.push(...post(f.dev, f.task, 'Yes.', [], { id: asked.id, author: asked.author as never }))- const agentPosts = rows.filter(m => m.author.kind === 'agent' && m.source?.kind !== 'system')+ const agentPosts = rows.filter(m => m.author.kind === 'agent' && m.source?.kind !== 'system' && m.source?.kind !== 'crew-need')expect(agentPosts).toHaveLength(18)expect(agentPosts.filter(m => m.recipients.includes(f.lead))).toHaveLength(3)+ // The Engineer's tag of the owner is the PM's crew need instead (crewNeeds.ts, task #3404): one more for the PM, and the+ // owner is not tagged.+ expect(rows.filter(m => m.source?.kind === 'crew-need').map(m => m.recipients)).toEqual([[f.lead]])+ expect(rows.flatMap(m => m.mentions ?? [])).toEqual([])})})diff --git a/backend/src/superTabs/taskLine.test.ts b/backend/src/superTabs/taskLine.test.tsindex 753b97146..27f3a5b8d 100644--- a/backend/src/superTabs/taskLine.test.ts+++ b/backend/src/superTabs/taskLine.test.ts@@ -185,10 +185,35 @@ describe('ordinary task messages and progress replies', () => {.toEqual(['Stuck: The build machine is offline. Next: the PM is looking at it.'])})- it('tags the person a decision waits on, with its default', () => {+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts, task #3404): a builder's question is the PM's crew need.+ it('says the PM is on a builder\'s question, and tags nobody', () => {const f = fixture(), id = f.group(), root = f.task(id).cards!.line!.messageIdconst builder = f.add('Kai', id)f.run({ type: 'work.assign', conversationId: id, agentId: builder })+ const asked = f.status(id, builder, 'needs_human', 'Keep drafts for a week?', { ask: { personId: 'owner', options: ['A week', 'A month'], recommended: 1,+ unblocks: 'how long drafts are kept' } })+ expect(thread(asked, root)).toEqual([expect.stringMatching(/^Needs a decision: Keep drafts for a week\? Next: .+ is on it\.$/)])+ })++ // Review of #3223, Minor 1: the line follows the decision, so the PM's own question on a builder's task still tags.+ it('tags the person the PM asks on a builder\'s task, with its default', () => {+ const f = fixture(), id = f.group(), root = f.task(id).cards!.line!.messageId+ const builder = f.add('Kai', id)+ f.run({ type: 'work.assign', conversationId: id, agentId: builder })+ const asked = f.status(id, f.pm, 'needs_human', 'Keep drafts for a week?', { ask: { personId: 'owner', options: ['A week', 'A month'], recommended: 1,+ unblocks: 'how long drafts are kept' } })+ expect(thread(asked, root)).toEqual(['@dee Your call: Keep drafts for a week? Default: A month.'])+ })++ it('tags the person a decision waits on, with its default, in a project with no PM', () => {+ const f = fixture()+ const project = f.run({ type: 'project.create', name: 'Quiet', visibility: 'private', brief: '' }).result.projectId as string+ const chat = f.state.projects!.find(p => p.id === project)!.leadConversationId+ const id = f.run({ type: 'conversation.create', projectId: project, title: 'Offline drafts', brief: 'Keep drafts.', checks: [], requestMessageId: 'quiet-ask' } as Command,+ owner, { request: f.request('quiet-ask', chat) } as Partial<CommandContext>).result.conversationId as string+ const root = f.task(id).cards!.line!.messageId+ const builder = f.add('Kai', id)+ f.run({ type: 'work.assign', conversationId: id, agentId: builder })const asked = f.status(id, builder, 'needs_human', 'Keep drafts for a week?', { ask: { personId: 'owner', options: ['A week', 'A month'], recommended: 1,unblocks: 'how long drafts are kept' } })expect(thread(asked, root)).toEqual(['@dee Your call: Keep drafts for a week? Default: A month.'])diff --git a/backend/src/superTabs/taskLine.ts b/backend/src/superTabs/taskLine.tsindex 9794f028e..a8fedeb99 100644--- a/backend/src/superTabs/taskLine.ts+++ b/backend/src/superTabs/taskLine.ts@@ -1,3 +1,4 @@+import { projectPm } from './crewNeeds.js'import { agentDisplayName } from './agentNames.js'import { isBuddyChat } from './buddies.js'import { shippedNotice } from './buddyNews.js'@@ -79,8 +80,12 @@ function progress(state: SuperTabState, effects: CommandEffects, group: Conversaif (was?.id !== assignment.id) return nullswitch (assignment.status) {case 'needs_human': {- const asked = assignment.askedOf && usernameOf(state, assignment.askedOf)const decision = effects.decisions?.find(d => d.conversationId === group.id && d.assignmentId === assignment.id)+ // People talk only to the PM (anh Dee, 11-05; crewNeeds.ts): with a PM, a question that opened no decision for a person is+ // the PM's crew need, so its line tells nobody it is their call. The line follows the decision, as commands.ts routes by+ // who asked (review of #3223).+ if (projectPm(state, group) && !decision) return `Needs a decision: ${sentence(assignment.result) || 'a decision is needed.'} Next: ${pm} is on it.`+ const asked = assignment.askedOf && usernameOf(state, assignment.askedOf)const fallback = decision && decision.options[decision.recommended]return `${asked ? `@${asked} ` : ''}Your call: ${sentence(assignment.result) || 'a decision is needed.'}${fallback ? ` Default: ${sentence(fallback)}` : ''}`}diff --git a/docs/plans/2026-11-05-crew-needs-plan.md b/docs/plans/2026-11-05-crew-needs-plan.mdnew file mode 100644index 000000000..3547833f9--- /dev/null+++ b/docs/plans/2026-11-05-crew-needs-plan.md@@ -0,0 +1,76 @@+# Agents ask people through the PM: implementation plan++> Written by the writing-plans skill. The Engineer implements it task by task, test first (test-driven-development).++**Goal:** Only the PM reaches people. When any other agent tags a person, needs a person, asks a person a decision or sends+a person a line, that becomes a crew need in the PM's inbox, and the agent is told it was routed there. The person is not+notified. This is routing, not a refusal (anh Dee, 2026-11-05; task #3404).++**Architecture:** A new module, `backend/src/superTabs/crewNeeds.ts`, decides who routes and builds the crew-need row.+`commands.ts` calls it from `message.send`, `work.status` (needs_human), `decision.ask` and `person.tell`. A crew need is a+message row with source kind `crew-need`, to the coordinator alone (`NOTICE_READERS` `recipients`), delivered at once (not+in `DIGEST_KINDS`). An agent's needs_human is the status row it already writes to the PM, now with `source.crewNeed` set.+`crewNeedOf(source)` reads both shapes for the inbox (#3403).++**Tech Stack:** TypeScript, vitest, the Super Tab command reducer (`applyCommand`).++**Spec:** the task brief of #3404 and River's ruling in the task (2026-11-05):+- The PM may tag anyone. Any other agent may tag only the person it is answering: the author of the message it answers+ (`--answers`) or replies to (`--reply-to`).+- Every other tag, and an agent's needs_human, decision.ask or person.tell, becomes a crew need for the PM.+- Without a PM in the project (no coordinator in its chat), everything stays as today.+- The 30-minute "PM owes it" rule belongs to the owed-asks task; crew-need rows carry enough for the inbox to list them.++## Global Constraints++- No new `*_FORBIDDEN` code; `removedRefusals.test.ts` stays green. A routed post, status, ask or tell succeeds.+- People's own tags still notify.+- A person's reply to an agent still reaches that agent.+- Swarm code stays in `backend/src/superTabs/`.++## Design++- growth: crew needs are message rows, deleted with their conversation like any message; no new collection.+- concurrency: written inside the command's transaction, like every message.+- read cost: no new read; one scan of the project's chat for its coordinator, already in state.+- scale: one row per routed post; at 10x posts the PM's turn count is the first warning, and the inbox (#3403) batches.+- compatibility: an older app shows a `crew-need` row only to its recipient (agent-only by kind); an older server ignores+ `source.crewNeed`.+- migration + rollback: none; rolling back only lets agents' tags reach people again.+- audience: the server decides routing from the actor, never from the client.+- identity: routing keys on the agent id and the project's coordinator, never a machine owner's login.+- failure: the agent's command result says where its tag or question went (`routedToPm`); with no PM, nothing routes.+- platforms: server only.++## Review Focus++- Every agent path that reached a person directly is covered: text tags, `--mention`, `mentionsIfNoWorker`, needs_human+ with or without ask, decision.ask, person.tell.+- The answered-person exemption cannot be used to tag anyone else.+- People's own tags and replies to agents behave as before.++## Task 1: Agent tags become crew needs++**Files:** `backend/src/superTabs/crewNeeds.ts` (new), `crewNeeds.test.ts` (new), `commands.ts` (message.send), `model.ts`+(`NOTICE_READERS`).++**Interfaces:** `coordinatorFor(state, group): { agentId, conversationId } | null`; `routesToPm(state, actor, group): boolean`;+`crewNeedOf(source): CrewNeed | null`; `CREW_NEED_KIND = 'crew-need'`.++- [ ] Failing test: a worker's tag (text and picked) writes no mention for the person; a crew-need row reaches the PM; the+ result says it was routed.+- [ ] Failing test: the PM's tag still tags; a person's tag still tags; a worker's tag of the person it answers still tags.+- [ ] Failing test: with no PM in the project, a worker's tag still tags.+- [ ] Regression test: a person's reply to an agent's message still reaches that agent.+- [ ] Implement.++## Task 2: needs_human, decision.ask and person.tell become crew needs++**Files:** `crewNeeds.ts`, `crewNeeds.test.ts`, `commands.ts` (work.status, decision.ask, person.tell).++- [ ] Failing test: a worker's needs_human with ask opens no decision; its status row to the PM carries `crewNeed` with the+ person, question and options; the result says it was routed.+- [ ] Failing test: a worker's decision.ask opens no decision and writes a crew need; the PM's still opens one.+- [ ] Failing test: a worker's person.tell writes nothing in the person's Buddy chat and writes a crew need; the PM's still+ reaches them.+- [ ] Implement.