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-02 1102-k: #2563 #2560 #2566 #2567 (#2575)
0xken15e6abca76a0f0
diff --git a/backend/integration/superTabIndexes.test.ts b/backend/integration/superTabIndexes.test.tsindex 6ea081309..a2803afcb 100644--- a/backend/integration/superTabIndexes.test.ts+++ b/backend/integration/superTabIndexes.test.ts@@ -11,6 +11,7 @@ import { costRows } from '../src/superTabs/costs/read.js'import { readEvidence } from '../src/superTabs/evidence/store.js'import { recentDecisions } from '../src/superTabs/routeDecisions.js'import { settleStuckDeliveries } from '../src/superTabs/deliverySettle.js'+import { listNamedIndexes } from '../src/superTabs/parts/indexed.js'import { revokeNativeContexts } from '../src/superTabs/native.js'import { outsider, owner, peer, richSwarm, swarm } from '../src/superTabs/read/fixture.test-support.js'import { threadSummaries } from '../src/superTabs/threads.js'@@ -231,21 +232,24 @@ describe('the delivery poll order', () => {describe('the delivery pass', () => {it('reads the open deliveries through the status index, examining only those it judges, with their dates as Dates', async () => {- const open = ['queued', 'claimed', 'uncertain'].map((status, i) => ({ _id: `A-open-${i}`, tabId: 'A', conversationId: 'g1', messageId: 'A-m900',+ const open = ['queued', 'claimed', 'uncertain', 'gathered'].map((status, i) => ({ _id: `A-open-${i}`, tabId: 'A', conversationId: 'g1', messageId: 'A-m900',agentId: `agent-${i}`, machineId: 'host', membershipGeneration: 'gen', authorKind: 'person', authorId: 'owner', authorGeneration: 'gen', status,...status === 'claimed' ? { claimId: 'claim', holdReason: 'team_waiting_user', holdSince: { $date: new Date(T0 + 1000).toISOString() } } : {},createdAt: { $date: new Date(T0).toISOString() }, updatedAt: { $date: new Date(T0 + 2000).toISOString() } }))await db.$runCommandRaw({ insert: 'SuperTabDelivery', documents: open })const judged: Array<{ tabId: string; rows: unknown[] }> = []const store = { settleDeliveries: async (tabId: string, rows: unknown[]) => { judged.push({ tabId, rows }); return 0 } }+ // As the worker has at startup: its plan is named, or a fourth status plans it on `compaction` and sorts.+ await listNamedIndexes(db)const [, profile] = await profiled('SuperTabDelivery', () => settleStuckDeliveries(db, store, T0))await db.superTabDelivery.deleteMany({ where: { messageId: 'A-m900' } })- // One scan of the index per open status, merged in id order.- expect(profile).toEqual({ plans: [Array(3).fill('IXSCAN { status: 1, _id: 1 }').join(', ')], docsExamined: 3, returned: 3 })+ // One scan of the index per unfinished status, merged in id order.+ expect(profile).toEqual({ plans: [Array(4).fill('IXSCAN { status: 1, _id: 1 }').join(', ')], docsExamined: 4, returned: 4 })expect(judged).toEqual([{ tabId: 'A', rows: [expect.objectContaining({ id: 'A-open-0', status: 'queued', holdSince: null, createdAt: new Date(T0), updatedAt: new Date(T0 + 2000) }),expect.objectContaining({ id: 'A-open-1', status: 'claimed', holdReason: 'team_waiting_user', holdSince: new Date(T0 + 1000) }),expect.objectContaining({ id: 'A-open-2', status: 'uncertain', conversationId: 'g1', agentId: 'agent-2' }),+ expect.objectContaining({ id: 'A-open-3', status: 'gathered' }),] }])})})diff --git a/backend/integration/superTabLiveness.test.ts b/backend/integration/superTabLiveness.test.tsindex ecb01858a..6d96f77f1 100644--- a/backend/integration/superTabLiveness.test.ts+++ b/backend/integration/superTabLiveness.test.ts@@ -81,11 +81,14 @@ async function swarm({ legacy = false, client = db, hooks, independent = false,/** The member name people and the Lead read for an agent. */const name = async (agentId: string) => (await timed.read(owner, tab)).state.agents.find(a => a.id === agentId)!.displayNameconst assignment = async () => (await timed.read(owner, tab)).state.conversations.find(c => c.id === group)!.assignment!- /** What the Lead's host receives now (this poll is also the Lead's wake-up path), with each row's text. */+ /** What the Lead's host receives now (this poll is also the Lead's wake-up path), with each row's text, and what it hears in a+ * digest (noticeDigest.ts): gathered for one, or named by one. Those of no digest of its own come first, in the order written. */const leadInbox = async () => {const rows = await timed.deliveries(host, tab, lead)- const messages = await db.superTabMessage.findMany({ where: { id: { in: rows.map(r => r.messageId) } } })- return rows.map(r => messages.find(m => m.id === r.messageId)!)+ const digest = await db.superTabDelivery.findMany({ where: { tabId: tab, agentId: lead, status: { in: ['gathered', 'digested'] } }, orderBy: { createdAt: 'asc' } })+ const ids = [...rows, ...digest].map(r => r.messageId)+ const messages = await db.superTabMessage.findMany({ where: { id: { in: ids } } })+ return ids.map(id => messages.find(m => m.id === id)!).filter(m => (m.source as { kind?: string } | null)?.kind !== 'notice-digest')}const lostRows = async () => (await db.superTabMessage.findMany({ where: { tabId: tab }, orderBy: { sequence: 'asc' } })).filter(m => (m.source as { kind?: string } | null)?.kind === 'work-lost')@@ -1088,7 +1091,8 @@ describe('a start that never runs', () => {f.clock.now = dispatched + 3 * MINUTEawait f.leadInbox()expect((await f.timed.read(owner, f.tab)).state.starts!.find(s => s.id === startId)!.error).toBeNull()- f.clock.now = dispatched + 3 * MINUTE + 1+ // Nothing open for its Lead, so its next full poll is the sweep's, 30 s on.+ f.clock.now = dispatched + 3 * MINUTE + 30_001const told = (await f.leadInbox()).find(m => (m.source as { kind?: string }).kind === 'start-timeout')!// 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 on fixture-model: its machine did not start it within 3 minutes.' })@@ -1640,6 +1644,9 @@ describe('the delivery poll of an agent with a held delivery', () => {}f.clock.now += 6 * MINUTEconst expectedIds = assignments.map(assignment => stableId(stableId('work-lost', assignment, String(f.clock.now)), 'lead'))+ await f.timed.deliveries(host, f.tab, f.lead)+ // Gathered for a digest; each goes on its own after the settle pass's 30 minutes, the ones these cases are about.+ await db.superTabDelivery.updateMany({ where: { tabId: f.tab, agentId: f.lead, status: 'gathered' }, data: { status: 'queued' } })const first = (await f.timed.deliveries(host, f.tab, f.lead)).filter(row => expectedIds.includes(row.messageId))expect(first).toHaveLength(3)await f.timed.delivery(host, f.tab, f.lead, first[0]!.id, { type: 'claim', claimId: 'claim-1' })@@ -1717,6 +1724,9 @@ describe('the push for a new delivery', () => {// Each loss notice is named by its task and the time of the loss (this poll).const expectedIds = assignments.map(assignment => stableId(stableId('work-lost', assignment, String(f.clock.now)), 'lead'))// One poll expires all three assignments and inserts their messages/deliveries together.+ await f.timed.deliveries(host, f.tab, f.lead)+ // Gathered for a digest; each goes on its own after the settle pass's 30 minutes, the ones these cases are about.+ await db.superTabDelivery.updateMany({ where: { tabId: f.tab, agentId: f.lead, status: 'gathered' }, data: { status: 'queued' } })const first = (await f.timed.deliveries(host, f.tab, f.lead)).filter(row => expectedIds.includes(row.messageId))expect(first).toHaveLength(3)expect(new Set(first.map(row => row.messageId))).toEqual(new Set(expectedIds))diff --git a/backend/integration/superTabNoticeDigest.test.ts b/backend/integration/superTabNoticeDigest.test.tsnew file mode 100644index 000000000..675c03386--- /dev/null+++ b/backend/integration/superTabNoticeDigest.test.ts@@ -0,0 +1,687 @@+import { randomUUID } from 'node:crypto'+import { execFile } from 'node:child_process'+import { promisify } from 'node:util'+import { join } from 'node:path'+import { tmpdir } from 'node:os'+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'+import { MongoMemoryReplSet } from 'mongodb-memory-server-core'+import { PrismaClient } from '@prisma/client'+import type { AuthUser } from '../src/lib/ssoAuth.js'+import { SuperTabStore, transaction } from '../src/superTabs/store.js'+import type { Command } from '../src/superTabs/commands.js'+import { poolRows } from './hostRows.test-support.js'+import { settleStuckDeliveries } from '../src/superTabs/deliverySettle.js'+import { compactDeliveries } from '../src/superTabs/deliveryCompaction.js'+import { revokeNativeContexts } from '../src/superTabs/native.js'+import { stableId, type MessageDraft, type SuperTabState } from '../src/superTabs/model.js'+import { logger } from '../src/utils/logger.js'++// Ken, 2026-11-02 (docs/plans/2026-11-02-pm-notice-digest-design.md): the server's routine notices to a project's coordinator+// go in one message at most every 5 minutes; what someone waits on still goes at once. A fresh loopback replica set, created here.+let replica: MongoMemoryReplSet+let db: PrismaClient+const owner: AuthUser = { sub: '210000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+const host: AuthUser = { sub: '210000000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }+const config = { engine: 'codex', model: 'fixture-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }+const MINUTE = 60_000+const DUE = 5 * MINUTE++beforeAll(async () => {+ replica = await MongoMemoryReplSet.create({ binary: { version: '7.0.24', downloadDir: join(tmpdir(), 'harness-super-tab-mongodb-binaries') },+ replSet: { count: 1, ip: '127.0.0.1', storageEngine: 'wiredTiger' } })+ const uri = replica.getUri(`swarm_digest_test_${randomUUID().replaceAll('-', '_')}`)+ await promisify(execFile)(join(process.cwd(), 'node_modules/.bin/prisma'), ['db', 'push', '--skip-generate'], {+ env: { ...process.env, DATABASE_URL: uri }, timeout: 60000,+ })+ db = new PrismaClient({ datasources: { db: { url: uri } } })+ for (const user of [owner, host]) await db.user.create({ data: { id: user.sub, externalId: `fixture-${user.sub}`, email: user.email, autonomousEnv: user.autonomousEnv } })+ for (const machineId of ['lead-host', 'test-host']) {+ await db.machine.create({ data: { machineId, userId: host.sub, apiKey: `fixture-${machineId}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })+ await db.machineShare.create({ data: { machineId, ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email] } })+ }+})+afterAll(async () => {+ await db?.$disconnect()+ await replica?.stop()+})++/** A Swarm whose coordinator runs on one machine and whose worker, on another, works on task "Ship the parser". The coordinator's+ * first update request (for the assignment) has gone, so nothing merges with a digest in the next 15 minutes, unless [fresh]. */+async function swarm({ fresh = false, told }: { fresh?: boolean; told?: string[] } = {}) {+ let now = Date.parse('2026-11-02T06:30:00.000Z')+ const timed = new SuperTabStore(db, () => now, null, told ? { deliveriesWaiting: w => { told.push(w.agentId) } } : {})+ const tab = (await timed.create(owner, randomUUID(), 'Digest', 'public')).id+ const execute = (command: Command, user = owner, asAgentId?: string) => timed.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)+ const invitation = await execute({ type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })+ await execute({ type: 'invite.accept', inviteId: invitation.result.inviteId as string }, host)+ for (const [machineId, name] of [['lead-host', 'Lead Mac'], ['test-host', 'Worker Mac']]) {+ await execute({ type: 'machine.contribute', machineId: machineId!, name: name!, cwd: '/repo', engines: ['codex'], maxAgents: 4 }, host)+ }+ const generations = new Map<string, string>()+ for (const machineId of ['lead-host', 'test-host']) generations.set(machineId, (await poolRows(timed, host, machineId)).find(p => p.tabId === tab)!.machine.generation)+ const harnessOf = new Map<string, string>()+ const add = async (conversationId: string, machineId: string, name: string, lead = false) => {+ const harnessId = randomUUID()+ const agentId = String((await execute({ type: 'agent.add', conversationId, machineId, harnessId, name, configuration: config, lead })).result.agentId)+ harnessOf.set(machineId, harnessId)+ return agentId+ }+ const lead = await add('lead', 'lead-host', 'Lead', true)+ const group = String((await execute({ type: 'conversation.create', title: 'Ship the parser', brief: 'Implement it',+ checks: [] })).result.conversationId)+ const worker = await add(group, 'test-host', 'Worker')+ const assignmentId = String((await execute({ type: 'work.assign', conversationId: group, agentId: worker })).result.assignmentId)+ const clock = { get now() { return now }, set now(value: number) { now = value } }+ /** Its machines report, as live ones do. */+ const report = async () => {+ // Its own first: a machine's report also judges the others', and one not heard from in 2 minutes loses its work.+ for (const machineId of ['test-host', 'lead-host']) await timed.observeMachine(host, tab, machineId, { generation: generations.get(machineId)!,+ resources: { cpuPercent: 10, memoryTotalBytes: 32e9, memoryUsedBytes: 4e9, diskFreeBytes: 120e9, diskTotalBytes: 500e9, projectDiskFreeBytes: 120e9, deviceType: 'Laptop', chip: 'Fixture', os: 'macOS', gpuPercent: null },+ quotas: [], tools: {}, runningHarnessIds: [harnessOf.get(machineId)!], stoppedHarnessIds: [] })+ }+ const poll = async () => {+ // Its worker keeps saying where it is, as a live one does; a finished task refuses the line and nothing changes.+ await execute({ type: 'work.status', conversationId: group, assignmentId, status: 'working', result: randomUUID() }, host, worker).catch(() => {})+ await report()+ return timed.deliveries(host, tab, lead)+ }+ const status = (s: 'done' | 'blocked' | 'needs_human' | 'working', result = 'A result') =>+ execute({ type: 'work.status', conversationId: group, assignmentId, status: s, result }, host, worker)+ if (!fresh) {+ clock.now += DUE + 1_000+ await poll()+ const early = await rowsOf(tab, { status: 'gathered' })+ expect(await Promise.all(early.map(d => db.superTabMessage.findUnique({ where: { id: d.messageId } }).then(m => [m?.text, m?.source])))).toEqual([])+ }+ /** Writes one message as the store writes every message, for a notice no short command here sets off. */+ const write = async (source: Record<string, unknown> | undefined, recipient: string, conversationId = group, text = 'A notice.') => {+ const id = randomUUID().replaceAll('-', '').slice(0, 24)+ await transaction(db, async tx => {+ const store = timed as unknown as { load(tx: unknown, user: AuthUser, tab: string, named?: unknown): Promise<{ state: SuperTabState }>+ writeMessages(tx: unknown, tab: string, state: SuperTabState, messages: MessageDraft[], sequences: Map<string, number>): Promise<void> }+ const { state } = await store.load(tx, host, tab, { groupIds: [conversationId] })+ const sender = state.agents.find(a => a.id === worker)!+ await store.writeMessages(tx, tab, state, [{ id, conversationId, text, replyTo: null, recipients: [recipient], ...source ? { source } : {},+ author: { kind: 'agent', id: worker, name: 'Worker', displayName: 'Worker', membershipGeneration: sender.membershipGeneration } } as MessageDraft],+ new Map([[id, 90_000 + Math.floor(Math.random() * 100_000)]]))+ })+ return id+ }+ return { timed, tab, execute, lead, group, worker, assignmentId, clock, poll, status, write }+}++const rowsOf = (tabId: string, where: Record<string, unknown> = {}) => db.superTabDelivery.findMany({ where: { tabId, ...where }, orderBy: { createdAt: 'asc' } })+const deliveryOf = (messageId: string, agentId: string) => db.superTabDelivery.findUniqueOrThrow({ where: { id: stableId(messageId, agentId) } })+const kindOf = (message: { source: unknown }) => (message.source as { kind?: string } | null)?.kind+const digests = async (tabId: string) => (await db.superTabMessage.findMany({ where: { tabId }, orderBy: { sequence: 'asc' } })).filter(m => kindOf(m) === 'notice-digest')+const statusRow = async (tabId: string, conversationId: string, label: string) => (await db.superTabMessage.findMany({ where: { tabId, conversationId }, orderBy: { sequence: 'desc' } }))+ .find(m => m.text.startsWith(label))!++describe('which messages to the coordinator are gathered', () => {+ it.each(['work-stalled', 'work-lost', 'work-resumed', 'idle', 'review-failed', 'review-capacity', 'overlap', 'note-removed'])('a %s notice is gathered for the coordinator, and queued for another agent', async kind => {+ const f = await swarm()+ const gathered = await f.write({ kind }, f.lead)+ expect((await deliveryOf(gathered, f.lead)).status).toBe('gathered')+ const other = await f.write({ kind }, f.worker)+ expect((await deliveryOf(other, f.worker)).status).toBe('queued')+ })++ it('an Engineer\'s Done is gathered, and its row says so; the message is written at once for its readers', async () => {+ const f = await swarm()+ await f.status('done', 'PR 2515 at 30a9942')+ const row = await statusRow(f.tab, f.group, 'Done')+ expect(row.source).toMatchObject({ kind: 'system', status: 'done' })+ expect((await deliveryOf(row.id, f.lead)).status).toBe('gathered')+ expect((await f.timed.messages(owner, f.tab, f.group, {})).messages.map(m => m.id)).toContain(row.id)+ })++ it.each(['needs_human', 'blocked'] as const)('a %s row goes at once', async status => {+ const f = await swarm()+ await f.status(status)+ const row = await statusRow(f.tab, f.group, status === 'blocked' ? 'Stuck' : 'Needs a human')+ expect(row.source).toMatchObject({ kind: 'system', status })+ expect((await deliveryOf(row.id, f.lead)).status).toBe('queued')+ })++ it.each(['pair-loop', 'terminal-alert', 'buddy-proposal', 'update-request', 'digest-request', 'agent-only', 'instructions', 'system'])('a %s row goes at once', async kind => {+ const f = await swarm()+ const id = await f.write({ kind }, f.lead)+ expect((await deliveryOf(id, f.lead)).status).toBe('queued')+ })++ it('an agent\'s post, and a status row written before the status was recorded, go at once', async () => {+ const f = await swarm()+ const sent = await f.execute({ type: 'message.send', conversationId: f.group, text: 'A question', replyTo: null, recipientIds: [f.lead] }, host, f.worker)+ const posted = String(sent.result.messageId)+ expect((await deliveryOf(posted, f.lead)).status).toBe('queued')+ expect((await deliveryOf(await f.write(undefined, f.lead), f.lead)).status).toBe('queued')+ })++ it('never lists a gathered delivery to a host, an old daemon\'s included', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ expect((await f.poll()).map(d => d.messageId)).not.toContain(id)+ f.clock.now += MINUTE+ expect((await f.poll()).map(d => d.messageId)).not.toContain(id)+ })++ it('a gathered delivery does not make an agent busy for its idle notice', async () => {+ const f = await swarm({ fresh: true })+ // Agent.add stands for a person's own session; the idle check counts a Swarm-started one.+ const part = await db.swarmAgent.findFirstOrThrow({ where: { tabId: f.tab, key: f.worker } })+ await db.swarmAgent.update({ where: { id: part.id }, data: { data: { ...part.data as object,+ startedSession: { creationId: 'c', sessionId: 's', createdAt: new Date(f.clock.now).toISOString() } } } })+ await f.status('done')+ await db.superTabDelivery.updateMany({ where: { tabId: f.tab, agentId: f.worker }, data: { status: 'delivered' } })+ const id = await f.write({ kind: 'idle' }, f.worker)+ await db.superTabDelivery.update({ where: { id: stableId(id, f.worker) }, data: { status: 'gathered' } })+ f.clock.now += 16 * MINUTE+ await f.poll()+ const told = (await db.superTabMessage.findMany({ where: { tabId: f.tab } })).filter(m => kindOf(m) === 'idle' && m.text.includes('no open task'))+ expect(told).toHaveLength(1)+ })+})++describe('the coordinator\'s poll releases what was gathered', () => {+ it('sends nothing before 5 minutes, counted from the first notice, not a clock', async () => {+ const f = await swarm()+ await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += 4 * MINUTE+ await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += MINUTE - 1_000+ await f.poll()+ expect(await digests(f.tab)).toEqual([])+ expect(await rowsOf(f.tab, { status: 'gathered' })).toHaveLength(2)+ f.clock.now += 1_000+ await f.poll()+ expect((await digests(f.tab))[0]!.source).toMatchObject({ kind: 'notice-digest', count: 2 })+ })++ it('at 5 minutes one digest names every notice by its task and message id, and the host gets it as one message', async () => {+ const f = await swarm()+ await f.status('done', 'PR 2515 at 30a9942')+ const done = await statusRow(f.tab, f.group, 'Done')+ const idle = await f.write({ kind: 'idle' }, f.lead, 'lead', 'Tester has had no open task for 15 minutes.')+ const number = (await f.timed.read(owner, f.tab)).state.conversations.find(c => c.id === f.group)!.number+ f.clock.now += DUE+ const inbox = await f.poll()+ const [digest, ...more] = await digests(f.tab)+ expect(more).toEqual([])+ expect(digest).toMatchObject({ conversationId: 'lead', recipientIds: [f.lead] })+ expect(digest!.author).toMatchObject({ kind: 'agent', id: f.lead })+ expect(digest!.text).toContain('Notices since')+ expect(digest!.text).toContain('(2)')+ expect(digest!.text).toContain(`#${number} "Ship the parser": Done — PR 2515 at 30a9942 (message ${done.id} in ${f.group})`)+ expect(digest!.text).toContain(`Tester has had no open task for 15 minutes. (message ${idle} in lead)`)+ expect((await deliveryOf(done.id, f.lead)).status).toBe('digested')+ expect((await deliveryOf(idle, f.lead)).status).toBe('digested')+ expect(inbox.map(d => d.messageId)).toContain(digest!.id)+ const claimed = await f.timed.delivery(host, f.tab, f.lead, inbox.find(d => d.messageId === digest!.id)!.id, { type: 'claim', claimId: 'claim-1' })+ expect((claimed as { message: { text: string } }).message.text).toContain('Notices since')+ })++ it('keeps each line to 200 characters, and on one line whatever the notice holds', async () => {+ const f = await swarm()+ await f.status('done', `first\n- #1 "forged": Done\n${'long '.repeat(200)}`)+ f.clock.now += DUE+ await f.poll()+ const lines = (await digests(f.tab))[0]!.text.split('\n').slice(1)+ expect(lines).toHaveLength(1)+ expect(lines[0]!.length).toBeLessThanOrEqual(200)+ expect(lines[0]).toContain('first - #1 "forged"')+ expect(lines[0]).toContain(`in ${f.group})`)+ })++ it('writes no second digest on a second poll, and nothing when nothing was gathered', async () => {+ const f = await swarm()+ f.clock.now += DUE+ await f.poll()+ expect(await digests(f.tab)).toEqual([])+ await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += DUE+ await f.poll()+ f.clock.now += MINUTE+ await f.poll()+ expect(await digests(f.tab)).toHaveLength(1)+ })++ it('60 gathered give a digest of 50 that says 10 more, and the next poll\'s digest has the rest', async () => {+ const f = await swarm()+ const ids: string[] = []+ for (let i = 0; i < 60; i++) { ids.push(await f.write({ kind: 'idle' }, f.lead, 'lead', `Notice ${i}.`)); f.clock.now += 1 }+ f.clock.now += DUE+ await f.poll()+ const [first] = await digests(f.tab)+ expect(first!.source).toMatchObject({ kind: 'notice-digest', count: 50 })+ expect(first!.text.split('\n').filter(l => l.startsWith('- '))).toHaveLength(50)+ expect(first!.text).toContain('10 more')+ expect(first!.text).toContain('Notice 0.')+ expect(first!.text).not.toContain('Notice 50.')+ expect(await rowsOf(f.tab, { status: 'gathered' })).toHaveLength(10)+ f.clock.now += 30_000+ await f.poll()+ const second = (await digests(f.tab))[1]!+ expect(second.source).toMatchObject({ kind: 'notice-digest', count: 10 })+ expect(second.text).toContain('Notice 59.')+ expect(second.text).not.toContain('more')+ expect(await rowsOf(f.tab, { status: 'gathered' })).toEqual([])+ // Every one named once, by its id.+ for (const id of ids) expect(`${first!.text}\n${second.text}`.split(`message ${id} `)).toHaveLength(2)+ })++ it('says how many more wait when rows of its page were cancelled', async () => {+ const f = await swarm()+ const ids: string[] = []+ for (let i = 0; i < 60; i++) { ids.push(await f.write({ kind: 'idle' }, f.lead, 'lead', `Notice ${i}.`)); f.clock.now += 1 }+ for (const id of ids.slice(0, 5)) await db.superTabDelivery.update({ where: { id: stableId(id, f.lead) }, data: { membershipGeneration: 'an earlier agent' } })+ f.clock.now += DUE+ await f.poll()+ const [first] = await digests(f.tab)+ expect(first!.source).toMatchObject({ count: 45 })+ expect(first!.text).toContain('And 10 more')+ })++ it('logs each release with the rows it cancelled, a release of cancels alone too', async () => {+ const f = await swarm()+ const gone = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabDelivery.update({ where: { id: stableId(gone, f.lead) }, data: { membershipGeneration: 'an earlier agent' } })+ const logged = vi.spyOn(logger, 'info')+ f.clock.now += DUE+ await f.poll()+ expect(logged).toHaveBeenCalledWith('[swarm-deliveries] notice digest', expect.objectContaining({ tabId: f.tab, count: 0, cancelled: 1 }))+ logged.mockClear()+ await f.write({ kind: 'idle' }, f.lead)+ const other = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabDelivery.update({ where: { id: stableId(other, f.lead) }, data: { authorGeneration: 'an earlier sender' } })+ f.clock.now += DUE+ await f.poll()+ expect(logged).toHaveBeenCalledWith('[swarm-deliveries] notice digest', expect.objectContaining({ tabId: f.tab, count: 1, cancelled: 1 }))+ logged.mockRestore()+ })++ it('names a message that cannot be read by its id alone, and digests it', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabMessage.delete({ where: { id } })+ f.clock.now += DUE+ await f.poll()+ expect((await digests(f.tab))[0]!.text).toContain(`(message ${id} in ${f.group})`)+ expect((await deliveryOf(id, f.lead)).status).toBe('digested')+ })++ it('leaves the rows gathered when the digest cannot be written, and the next poll tries again', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += DUE+ const stuck = stableId('notice-digest', f.lead, stableId(id, f.lead))+ await db.superTabMessage.create({ data: { id: stuck, tabId: f.tab, conversationId: 'lead', sequence: 1, text: 'In the way', replyTo: null,+ recipientIds: [], mentions: [], thread: stuck, author: { kind: 'person', id: owner.sub, name: owner.email, membershipGeneration: 'g' } } })+ await expect(f.poll()).rejects.toThrow()+ expect((await deliveryOf(id, f.lead)).status).toBe('gathered')+ await db.superTabMessage.delete({ where: { id: stuck } })+ await f.poll()+ expect((await deliveryOf(id, f.lead)).status).toBe('digested')+ expect(await digests(f.tab)).toHaveLength(1)+ })++ it('two polls racing write one digest and digest each row once', async () => {+ const f = await swarm()+ await f.write({ kind: 'idle' }, f.lead)+ await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += DUE+ await Promise.all([f.poll(), f.poll(), f.poll()])+ const all = await digests(f.tab)+ expect(all).toHaveLength(1)+ expect(all[0]!.source).toMatchObject({ count: 2 })+ expect((await rowsOf(f.tab, { messageId: all[0]!.id }))).toHaveLength(1)+ })++ it('a digest is the coordinator\'s alone: no person or other agent reads it', async () => {+ const f = await swarm()+ await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += DUE+ await f.poll()+ const [digest] = await digests(f.tab)+ const page = async (user: AuthUser, asAgentId?: string) => (await f.timed.messages(user, f.tab, 'lead', { messageId: digest!.id }, asAgentId)).messages.map(m => m.id)+ expect(await page(host, f.lead)).toEqual([digest!.id])+ for (const user of [owner, host]) expect(await page(user)).toEqual([])+ expect(digest!.source).toMatchObject({ recipientsOnly: true })+ })++ it('a reply to a gathered notice answers it, so the digest does not name it again', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await f.execute({ type: 'message.send', conversationId: f.group, text: 'Seen', replyTo: id, recipientIds: [] }, host, f.lead)+ expect((await deliveryOf(id, f.lead)).status).toBe('answered')+ f.clock.now += DUE+ await f.poll()+ expect(await digests(f.tab)).toEqual([])+ })++ it('finds a notice whose group went to sleep since, rather than cancelling it', async () => {+ const f = await swarm()+ await f.status('done', 'PR 1')+ const done = await statusRow(f.tab, f.group, 'Done')+ await db.swarmGroup.updateMany({ where: { tabId: f.tab, key: f.group }, data: { dormant: true } })+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(done.id, f.lead)).status).toBe('digested')+ expect((await digests(f.tab))[0]!.text).toContain('"Ship the parser": Done')+ })+})++describe('the same rules as a delivery, at digest time', () => {+ it('cancels a row whose recipient generation no longer holds, and leaves it out', async () => {+ const f = await swarm()+ const kept = await f.write({ kind: 'idle' }, f.lead, f.group, 'Kept.')+ const gone = await f.write({ kind: 'idle' }, f.lead, f.group, 'Gone.')+ await db.superTabDelivery.update({ where: { id: stableId(gone, f.lead) }, data: { membershipGeneration: 'an earlier agent under this id' } })+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(gone, f.lead)).status).toBe('cancelled')+ expect((await deliveryOf(kept, f.lead)).status).toBe('digested')+ const [digest] = await digests(f.tab)+ expect(digest!.source).toMatchObject({ count: 1 })+ expect(digest!.text).not.toContain(gone)+ expect(digest!.text).not.toContain('Gone.')+ })++ it('cancels a row whose sender no longer holds, and leaves it out', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabDelivery.update({ where: { id: stableId(id, f.lead) }, data: { authorGeneration: 'an earlier sender' } })+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ expect(await digests(f.tab)).toEqual([])+ })++ it('cancels a row of a group whose conversation became unreadable, with no title in the digest', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead, f.group, 'A secret notice.')+ await db.superTabMessage.update({ where: { id }, data: { text: 'A secret notice.' } })+ // Archived with no command, as an older server could leave it: nothing cancelled it first.+ const part = await db.swarmGroup.findFirstOrThrow({ where: { tabId: f.tab, key: f.group } })+ await db.swarmGroup.update({ where: { id: part.id }, data: { data: { ...part.data as object, archived: true } } })+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ expect(await digests(f.tab)).toEqual([])+ })++ it('refuses a row of another project\'s group, and leaks neither its title nor its text', async () => {+ const f = await swarm()+ const project = String((await f.execute({ type: 'project.create', name: 'Other', visibility: 'private', brief: '' })).result.projectId)+ const other = String((await f.execute({ type: 'conversation.create', projectId: project, title: 'Their secret task', brief: 'x', checks: [] })).result.conversationId)+ const id = randomUUID().replaceAll('-', '').slice(0, 24)+ const sender = (await f.timed.read(host, f.tab)).state.agents.find(a => a.id === f.worker)+ await db.superTabMessage.create({ data: { id, tabId: f.tab, conversationId: other, sequence: 1, text: 'Their secret text', replyTo: null, recipientIds: [f.lead], mentions: [], thread: id,+ author: { kind: 'agent', id: f.worker, name: 'Worker', membershipGeneration: sender!.membershipGeneration } } })+ const lead = (await f.timed.read(host, f.tab)).state.agents.find(a => a.id === f.lead)!+ await db.superTabDelivery.create({ data: { id: stableId(id, f.lead), tabId: f.tab, conversationId: other, messageId: id, agentId: f.lead, machineId: 'lead-host', machineOwnerId: host.sub,+ membershipGeneration: lead.membershipGeneration, authorKind: 'agent', authorId: f.worker, authorGeneration: sender!.membershipGeneration, status: 'gathered', createdAt: new Date(f.clock.now) } })+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ expect(await digests(f.tab)).toEqual([])+ })+})++describe('a gathered row never outlives its reason', () => {+ it('archiving its conversation cancels it', async () => {+ const f = await swarm()+ await f.execute({ type: 'work.cancel', conversationId: f.group, assignmentId: f.assignmentId, reason: 'Moved' })+ await f.execute({ type: 'conversation.archive', conversationId: f.group, archived: false })+ const id = await f.write({ kind: 'idle' }, f.lead)+ await f.execute({ type: 'conversation.archive', conversationId: f.group, archived: true })+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ })++ it('its task ending cancels it', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabDelivery.update({ where: { id: stableId(id, f.lead) }, data: { assignmentId: f.assignmentId } })+ await f.execute({ type: 'work.cancel', conversationId: f.group, assignmentId: f.assignmentId, reason: 'Done elsewhere' })+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ })++ it('its task\'s host confirming a stop cancels it', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabDelivery.update({ where: { id: stableId(id, f.lead) }, data: { assignmentId: f.assignmentId } })+ const part = await db.swarmGroup.findFirstOrThrow({ where: { tabId: f.tab, key: f.group } })+ const data = part.data as { assignment: { execution: { machineOwnerId?: string } } }+ await db.swarmGroup.update({ where: { id: part.id }, data: { data: { ...data, assignment: { ...data.assignment, execution: { ...data.assignment.execution, machineOwnerId: host.sub } } } } })+ await f.timed.stopped(host, f.tab, f.assignmentId, 'receipt')+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ })++ it('the agent leaving its conversation cancels it', async () => {+ const f = await swarm()+ // A project's coordinator does not leave its chats' work to chance (LEAD_PROTECTED): a row left on an agent that lost the role since.+ await f.execute({ type: 'work.cancel', conversationId: f.group, assignmentId: f.assignmentId, reason: 'Moved' })+ const id = await f.write({ kind: 'idle' }, f.worker)+ await db.superTabDelivery.update({ where: { id: stableId(id, f.worker) }, data: { status: 'gathered' } })+ await f.execute({ type: 'conversation.agent', conversationId: f.group, agentId: f.worker, present: false, lead: false })+ expect((await deliveryOf(id, f.worker)).status).toBe('cancelled')+ })++ it('the agent being removed cancels it', async () => {+ const f = await swarm()+ // A coordinator is not removed as such (a project's PM stays): a row left on an agent that lost the role since.+ await f.execute({ type: 'work.cancel', conversationId: f.group, assignmentId: f.assignmentId, reason: 'Moved' })+ const id = await f.write({ kind: 'idle' }, f.worker)+ await db.superTabDelivery.update({ where: { id: stableId(id, f.worker) }, data: { status: 'gathered' } })+ await f.execute({ type: 'agent.remove', agentId: f.worker })+ expect((await deliveryOf(id, f.worker)).status).toBe('cancelled')+ })++ it('its sender being removed cancels a routine notice, at digest time', async () => {+ const f = await swarm()+ await f.execute({ type: 'work.cancel', conversationId: f.group, assignmentId: f.assignmentId, reason: 'Moved' })+ const id = await f.write({ kind: 'idle' }, f.lead)+ await f.execute({ type: 'agent.remove', agentId: f.worker })+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ expect(await digests(f.tab)).toEqual([])+ })++ // Done is how the PM hears, once (project instructions): an agent stopped inside the 5 minutes must not take it along (review of #2560).+ it('its sender being removed keeps a Done, named by its label and ids, with no result', async () => {+ const f = await swarm()+ await f.status('done', 'PR 2515 and a private result')+ const done = await statusRow(f.tab, f.group, 'Done')+ await f.execute({ type: 'agent.remove', agentId: f.worker })+ expect((await deliveryOf(done.id, f.lead)).status).toBe('gathered')+ // The settle pass, which runs inside those 5 minutes too, leaves it for the digest.+ await settleStuckDeliveries(db, f.timed, f.clock.now)+ expect((await deliveryOf(done.id, f.lead)).status).toBe('gathered')+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(done.id, f.lead)).status).toBe('digested')+ const [digest] = await digests(f.tab)+ expect(digest!.text).toContain(`"Ship the parser": Done (message ${done.id} in ${f.group})`)+ expect(digest!.text).not.toContain('private result')+ })++ it('a Done whose recipient no longer holds is cancelled, whatever its sender', async () => {+ const f = await swarm()+ await f.status('done', 'PR 1')+ const done = await statusRow(f.tab, f.group, 'Done')+ await db.superTabDelivery.update({ where: { id: stableId(done.id, f.lead) }, data: { membershipGeneration: 'an earlier agent', authorGeneration: 'an earlier sender' } })+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(done.id, f.lead)).status).toBe('cancelled')+ expect(await digests(f.tab)).toEqual([])+ })++ it('a Done past the 30 minutes with its sender gone ends there: no host could be handed it', async () => {+ const f = await swarm()+ await f.status('done', 'PR 1')+ const done = await statusRow(f.tab, f.group, 'Done')+ await f.execute({ type: 'agent.remove', agentId: f.worker })+ f.clock.now += 30 * MINUTE + 1_000+ await settleStuckDeliveries(db, f.timed, f.clock.now)+ expect((await deliveryOf(done.id, f.lead)).status).toBe('cancelled')+ })++ it('a revoked native context cancels it', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabNativeContext.create({ data: { id: `native-${f.tab}`, tabId: f.tab, conversationId: f.group, agentId: f.worker, userId: owner.sub, binding: {}, revoked: false } })+ await db.superTabDelivery.update({ where: { id: stableId(id, f.lead) }, data: { nativeContextId: `native-${f.tab}` } })+ const { state } = await f.timed.read(owner, f.tab)+ const after = { ...state, agents: state.agents.filter(a => a.id !== f.worker) }+ await transaction(db, tx => revokeNativeContexts(tx, state, after))+ expect((await db.superTabNativeContext.findUniqueOrThrow({ where: { id: `native-${f.tab}` } })).revoked).toBe(true)+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ })+})++describe('the settle pass, when the coordinator stopped polling', () => {+ it('sets a delivery gathered over 30 minutes back to queued, and its host then lists it', async () => {+ const told: string[] = []+ const f = await swarm({ told })+ const old = await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += 25 * MINUTE+ const recent = await f.write({ kind: 'idle' }, f.lead)+ await settleStuckDeliveries(db, f.timed, f.clock.now)+ expect((await deliveryOf(old, f.lead)).status).toBe('gathered')+ f.clock.now += 5 * MINUTE + 1_000+ told.length = 0+ expect(await settleStuckDeliveries(db, f.timed, f.clock.now)).toBeGreaterThan(0)+ expect((await deliveryOf(old, f.lead)).status).toBe('queued')+ expect((await deliveryOf(recent, f.lead)).status).toBe('gathered')+ expect(told).toContain(f.lead)+ const claim = await f.timed.delivery(host, f.tab, f.lead, stableId(old, f.lead), { type: 'claim', claimId: 'claim-old' })+ expect((claim as { delivery: { status: string } }).delivery.status).toBe('claimed')+ })++ it('cancels a gathered delivery nobody may read any more', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await db.superTabDelivery.update({ where: { id: stableId(id, f.lead) }, data: { membershipGeneration: 'an earlier agent' } })+ await settleStuckDeliveries(db, f.timed, f.clock.now)+ expect((await deliveryOf(id, f.lead)).status).toBe('cancelled')+ })++ it('leaves a digested delivery alone, and compaction treats it as finished', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += DUE+ await f.poll()+ expect((await deliveryOf(id, f.lead)).status).toBe('digested')+ f.clock.now += 60 * MINUTE+ await settleStuckDeliveries(db, f.timed, f.clock.now)+ expect((await deliveryOf(id, f.lead)).status).toBe('digested')+ await db.$runCommandRaw({ update: 'SuperTabDelivery', updates: [{ q: { _id: stableId(id, f.lead) }, u: { $set: { updatedAt: { $date: new Date(Date.now() - 15 * 86_400_000).toISOString() } } } }] })+ expect((await compactDeliveries(db, Date.now())).compacted).toBeGreaterThan(0)+ expect(await db.superTabDelivery.findUnique({ where: { id: stableId(id, f.lead) } })).toBeNull()+ // Compacted, it is refused just the same.+ await expect(f.timed.delivery(host, f.tab, f.lead, stableId(id, f.lead), { type: 'claim', claimId: 'late' })).rejects.toMatchObject({ code: 'DELIVERY_RESOLVED' })+ })+})++describe('a host claiming by id', () => {+ it('is refused a gathered row and a digested one, which stay as they are', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ const delivery = stableId(id, f.lead)+ await expect(f.timed.delivery(host, f.tab, f.lead, delivery, { type: 'claim', claimId: 'a-claim' })).rejects.toMatchObject({ code: 'DELIVERY_RESOLVED' })+ expect((await deliveryOf(id, f.lead))).toMatchObject({ status: 'gathered', claimId: null })+ f.clock.now += DUE+ await f.poll()+ await expect(f.timed.delivery(host, f.tab, f.lead, delivery, { type: 'claim', claimId: 'a-claim' })).rejects.toMatchObject({ code: 'DELIVERY_RESOLVED' })+ expect((await deliveryOf(id, f.lead))).toMatchObject({ status: 'digested', claimId: null })+ })+})++describe('when the coordinator changes', () => {+ // No command replaces a live PM yet (LEAD_PROTECTED); a coming one (#2527) will. The step takes the states a command leaves.+ const change = async (f: Awaited<ReturnType<typeof swarm>>, next: string | null) => {+ const { state } = await f.timed.read(owner, f.tab)+ const after = { ...state, conversations: state.conversations.map(c => c.id === 'lead' ? { ...c, leadId: next } : c) }+ await transaction(db, tx => (f.timed as unknown as { requeueFormerLeads(tx: unknown, tab: string, before: SuperTabState, after: SuperTabState): Promise<void> })+ .requeueFormerLeads(tx, f.tab, state, after))+ }++ it('the old lead\'s gathered rows go back to queued, for it to hear one by one', async () => {+ const told: string[] = []+ const f = await swarm({ told })+ const id = await f.write({ kind: 'idle' }, f.lead)+ told.length = 0+ await change(f, f.worker)+ expect((await deliveryOf(id, f.lead)).status).toBe('queued')+ expect(told).toContain(f.lead)+ })++ it('a project chat left with no lead does the same', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await change(f, null)+ expect((await deliveryOf(id, f.lead)).status).toBe('queued')+ })++ it('a command refused for protecting the lead changes nothing', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await expect(f.execute({ type: 'conversation.agent', conversationId: 'lead', agentId: f.worker, present: true, lead: true })).rejects.toMatchObject({ code: 'LEAD_PROTECTED' })+ expect((await deliveryOf(id, f.lead)).status).toBe('gathered')+ })++ it('changes nothing for anyone when the lead stays', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ await f.execute({ type: 'conversation.rename', conversationId: f.group, title: 'New title' })+ expect((await deliveryOf(id, f.lead)).status).toBe('gathered')+ })+})++describe('with the update request', () => {+ it('goes as one message when both are due in one poll, and the report still answers it', async () => {+ const f = await swarm({ fresh: true })+ await f.status('done', 'PR 2515')+ const done = await statusRow(f.tab, f.group, 'Done')+ f.clock.now += DUE+ const inbox = await f.poll()+ expect(await digests(f.tab)).toEqual([])+ const requests = (await db.superTabMessage.findMany({ where: { tabId: f.tab } })).filter(m => kindOf(m) === 'update-request')+ expect(requests).toHaveLength(1)+ const [request] = requests+ expect(request!.text).toContain('Work changed in project')+ expect(request!.text.indexOf('Work changed')).toBeLessThan(request!.text.indexOf('Notices since'))+ expect(request!.text).toContain(`"Ship the parser": Done — PR 2515 (message ${done.id} in ${f.group})`)+ expect(request!.source).toMatchObject({ kind: 'update-request', notices: 1 })+ expect((await deliveryOf(done.id, f.lead)).status).toBe('digested')+ expect(inbox.filter(d => d.messageId === request!.id)).toHaveLength(1)+ // One new message for the coordinator.+ expect(inbox.filter(d => !d.messageId.startsWith(request!.id)).filter(d => d.conversationId === 'lead' && d.status === 'queued' && d.createdAt.getTime() === f.clock.now)).toEqual([])+ const through = (request!.source as { through: Record<string, number> }).through+ await f.execute({ type: 'project.report', projectId: (await f.timed.read(host, f.tab, undefined, f.lead)).state.projects![0]!.id, through, text: null }, host, f.lead)+ expect((await deliveryOf(request!.id, f.lead)).status).toBe('answered')+ })++ it('goes alone when the update request is not due', async () => {+ const f = await swarm()+ const id = await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += DUE+ await f.poll()+ expect(await digests(f.tab)).toHaveLength(1)+ expect((await deliveryOf(id, f.lead)).status).toBe('digested')+ })++ it('does not merge into an update request already stored under its id, so no line is lost and the poll still goes', async () => {+ const f = await swarm({ fresh: true })+ const id = await f.write({ kind: 'idle' }, f.lead)+ f.clock.now += DUE+ const { projectUpdateRequest } = await import('../src/superTabs/projectUpdates.js')+ const { state } = await f.timed.read(host, f.tab, undefined, f.lead)+ const draft = projectUpdateRequest(state, state.agents.find(a => a.id === f.lead)!, f.clock.now)!+ await db.superTabMessage.create({ data: { id: draft.id, tabId: f.tab, conversationId: draft.conversationId, sequence: 1, text: draft.text, replyTo: null, recipientIds: draft.recipients,+ mentions: [], thread: draft.id, source: draft.source as object, author: draft.author as object } })+ await f.poll()+ expect((await digests(f.tab))[0]!.text).toContain(`message ${id} `)+ expect((await deliveryOf(id, f.lead)).status).toBe('digested')+ })+})diff --git a/backend/integration/superTabTidy.test.ts b/backend/integration/superTabTidy.test.tsindex 0afd8f264..307ffcd8d 100644--- a/backend/integration/superTabTidy.test.ts+++ b/backend/integration/superTabTidy.test.ts@@ -100,11 +100,12 @@ describe('an agent left idle', () => {await f.timed.deliveries(host, f.tab, f.lead)expect(await f.lines()).toEqual([])f.clock.now += MINUTE + 1_000- const inbox = await f.timed.deliveries(host, f.tab, f.lead)+ await f.timed.deliveries(host, f.tab, f.lead)const lines = await f.lines()expect(lines).toEqual([expect.objectContaining({ conversationId: 'lead', recipientIds: [f.lead], text: 'Worker has had no open task for 15 minutes.',source: { kind: 'idle', agentId: f.worker } })])- expect(inbox.map(d => d.messageId)).toContain(lines[0]!.id)+ // It waits for the coordinator's next digest (noticeDigest.ts).+ expect((await db.superTabDelivery.findMany({ where: { tabId: f.tab, messageId: lines[0]!.id } })).map(d => d.status)).toEqual(['gathered'])const member = await f.member()expect(member.workDecision).toBe('awaiting')expect(member.releaseId).toBeUndefined()diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 09dc12b0c..c2b296b44 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -3513,7 +3513,8 @@ describe('Product Managers chat, removed (Dee, 2026-10-31)', () => {// The Lead that made the overlap knows it; the other project's Lead hears it in its own project chat, written as itself.expect(alerts).toEqual([expect.objectContaining({ conversationId: docsChat, recipientIds: [docsLead],author: expect.objectContaining({ id: docsLead }), text: expect.stringContaining('"Agents filter" (Pilot') })])- expect((await store.deliveries(host, tab, docsLead)).filter(d => d.messageId === alerts[0]!.id)).toHaveLength(1)+ // Nobody waits on it within minutes: it goes in that Lead's next digest (noticeDigest.ts).+ expect(await db.superTabDelivery.findMany({ where: { tabId: tab, agentId: docsLead, messageId: alerts[0]!.id, status: 'gathered' } })).toHaveLength(1)// The two Leads' to settle (Ken, 2026-10-29): the Lead it reaches reads it; people in the project chat do not.expect((await store.messages(host, tab, docsChat, {}, docsLead)).messages.map(m => m.id)).toContain(alerts[0]!.id)expect((await store.messages(owner, tab, docsChat, {})).messages.map(m => m.id)).not.toContain(alerts[0]!.id)diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.tsindex 2cb392dda..66f212c6f 100644--- a/backend/src/superTabs/commands.ts+++ b/backend/src/superTabs/commands.ts@@ -2966,7 +2966,8 @@ export function applyCommand(original: SuperTabState, actor: Actor, input: Comma: [...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 ${person(state, command.ask.personId).email}.`- message(group.id, `${label}${command.result ? `\n\n${command.result}` : ''}${asked}`, recipients, null, SYSTEM_ROW)+ // 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 })// The server opens no review by itself: the agent whose work is ready opens and assigns it, as the project's instructions// say (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/deliveryCompaction.ts b/backend/src/superTabs/deliveryCompaction.tsindex 721d2c66c..7df66492b 100644--- a/backend/src/superTabs/deliveryCompaction.ts+++ b/backend/src/superTabs/deliveryCompaction.ts@@ -11,7 +11,7 @@ import { retryTransient } from './retry.js'* row (pageReads.ts). `delivered` and `confirmed` are not finished (a reply or a project report moves them to `answered`),* nor are the open ones.*/-export const FINAL_DELIVERY = ['answered', 'cancelled', 'superseded'] as const+export const FINAL_DELIVERY = ['answered', 'cancelled', 'superseded', 'digested'] as constexport const COMPACT_AFTER_MS = 14 * 86_400_000/** Batches per hourly run: up to 10 k deliveries, so the first runs also clear the backlog. Prod finishes ≤ 3.4 k a day. */const BATCHES_PER_RUN = 20diff --git a/backend/src/superTabs/deliverySettle.ts b/backend/src/superTabs/deliverySettle.tsindex f1b8f2b98..030ca3f95 100644--- a/backend/src/superTabs/deliverySettle.ts+++ b/backend/src/superTabs/deliverySettle.ts@@ -1,4 +1,5 @@-import type { PrismaClient, SuperTabDelivery } from '@prisma/client'+import type { Prisma, PrismaClient, SuperTabDelivery } from '@prisma/client'+import { readBy } from './parts/indexed.js'import { ms } from './parts/light.js'import type { SuperTabStore } from './store.js'import { logger } from '../utils/logger.js'@@ -21,7 +22,8 @@ export const UNCERTAIN_LIMIT_MS = 60 * 60_000* answering busy (prod 10-30, v1.3.71: every person's messages to their own Buddy sat queued for 2 hours, and nothing said so). */export const CLAIM_FAILING_ALARM_MS = 5 * 60_000const SETTLE_EVERY_MS = 5 * 60_000-const OPEN = ['queued', 'claimed', 'uncertain']+// Gathered ones too: nothing else settles a row its coordinator stopped polling for (store.ts settleDeliveries).+const OPEN = ['queued', 'claimed', 'uncertain', 'gathered']const BATCH = 500/** Whether an open delivery can no longer move. [reachable]: its recipient may still read it there (store.ts deliveryAllowed). */@@ -43,8 +45,8 @@ export function claimsFailing(delivery: Pick<SuperTabDelivery, 'status' | 'claim/** A page of open deliveries, by id. Read by their own index (status, id) with a plain match: Prisma sends `status in` as an* $expr $or that no index can bound (pageReads.ts), and a pass must not read every delivery ever sent. */async function openDeliveries(db: PrismaClient, after: string | null): Promise<SuperTabDelivery[]> {- const rows = await db.superTabDelivery.aggregateRaw({ pipeline: [{ $match: { status: { $in: OPEN }, ...after ? { _id: { $gt: after } } : {} } },- { $sort: { _id: 1 } }, { $limit: BATCH }] }) as unknown as Array<Record<string, unknown>>+ const rows = await readBy(db as unknown as Prisma.TransactionClient, 'SuperTabDelivery', 'settle', [{ $match: { status: { $in: OPEN }, ...after ? { _id: { $gt: after } } : {} } },+ { $sort: { _id: 1 } }, { $limit: BATCH }])const date = (value: unknown) => value == null ? null : new Date(ms(value))return rows.map(({ _id, ...row }) => ({ ...row, id: _id as string, holdSince: date(row.holdSince), claimFailingSince: date(row.claimFailingSince), claimFailedAt: date(row.claimFailedAt), deliveredAt: date(row.deliveredAt),answeredAt: date(row.answeredAt), createdAt: date(row.createdAt)!, updatedAt: date(row.updatedAt)! }) as unknown as SuperTabDelivery)diff --git a/backend/src/superTabs/model.ts b/backend/src/superTabs/model.tsindex a6e426150..85da1b11b 100644--- a/backend/src/superTabs/model.ts+++ b/backend/src/superTabs/model.ts@@ -520,6 +520,8 @@ export const NOTICE_READERS = {'update-request': 'recipients', 'digest-request': 'recipients', overlap: 'recipients',// Two agents that may be talking in a loop, told to the coordinator (commands.ts pairLoop, project instructions phase 1).'pair-loop': 'recipients',+ // The server's routine notices to the coordinator, gathered into one message (noticeDigest.ts).+ 'notice-digest': '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, with its summary: the team sees it without opening the document (instructions.ts).diff --git a/backend/src/superTabs/native.ts b/backend/src/superTabs/native.tsindex 2ad80e935..8baf0d37a 100644--- a/backend/src/superTabs/native.ts+++ b/backend/src/superTabs/native.ts@@ -7,6 +7,7 @@ import { activeWork, agent, appendPullRequestUrls, author, conversation, fail, stype Actor, type Agent, type Author, type Conversation, type SuperTabState } from './model.js'import { accessInputs, canReadGroup, readConversation, watchersLost } from './projects.js'import { mayDrive } from './terminal.js'+import { CANCELLABLE_DELIVERY } from './pageReads.js'import { cloneData } from './cloneData.js'import { numberMessages, type Touch } from './parts/commit.js'import { redactCredentials } from './credentials.js'@@ -277,7 +278,7 @@ export async function revokeNativeContexts(tx: Transaction, before: SuperTabStatconst revoked = await tx.superTabNativeContext.findMany({ where, select: { id: true } })await tx.superTabNativeContext.updateMany({ where, data: { revoked: true } })if (revoked.length) await tx.superTabDelivery.updateMany({ where: { tabId: before.id,- nativeContextId: { in: revoked.map(r => r.id) }, status: { in: ['queued', 'claimed', 'uncertain'] } },+ nativeContextId: { in: revoked.map(r => r.id) }, status: { in: [...CANCELLABLE_DELIVERY] } },data: { status: 'cancelled', holdReason: null, holdSince: null } })}return watchersLostdiff --git a/backend/src/superTabs/noticeDigest.test.ts b/backend/src/superTabs/noticeDigest.test.tsnew file mode 100644index 000000000..be76fe78e--- /dev/null+++ b/backend/src/superTabs/noticeDigest.test.ts@@ -0,0 +1,91 @@+import { readFileSync } from 'node:fs'+import { join } from 'node:path'+import { describe, expect, it } from 'vitest'+import { agentOnly, type Conversation, type SuperTabState } from './model.js'+import { digestIsDue, digestMessage, digestText, gatheredNotice, NOTICE_DIGEST_MS, noticeLine } from './noticeDigest.js'++const task = { id: 'task', title: 'Web app: an account menu that opens everywhere and keeps going on', number: 1959 } as Conversation+const step = { id: 'step', title: 'Review: Buddy copies', number: 1991, reviewOf: 'task', step: 'Review' } as Conversation+const state = { id: 'tab', conversations: [task, step, { id: 'lead', title: 'Project' }], projects: [{ id: 'p', leadConversationId: 'lead' }] } as unknown as SuperTabState+const row = (conversationId: string, messageId = 'a'.repeat(24)) => ({ conversationId, messageId })++describe('what is gathered', () => {+ it.each(['work-stalled', 'work-lost', 'work-resumed', 'idle', 'review-failed', 'review-capacity', 'overlap', 'note-removed'])('%s', kind => {+ expect(gatheredNotice({ kind })).toBe(true)+ })+ it('a Done status row, and no other status', () => {+ expect(gatheredNotice({ kind: 'system', status: 'done' })).toBe(true)+ for (const status of ['needs_human', 'blocked', 'working', 'review', 'stopped']) expect(gatheredNotice({ kind: 'system', status })).toBe(false)+ })+ it.each(['pair-loop', 'terminal-alert', 'buddy-proposal', 'update-request', 'digest-request', 'agent-only', 'system', 'instructions', 'notice-digest', 'from-a-newer-server'])('not %s', kind => {+ expect(gatheredNotice({ kind })).toBe(false)+ })+ it('not a row with no source: a post', () => {+ for (const source of [undefined, null]) expect(gatheredNotice(source)).toBe(false)+ expect(gatheredNotice({ status: 'done' })).toBe(false)+ })+})++describe('when it is due', () => {+ const at = (ms: number) => ({ createdAt: new Date(ms) })+ it('5 minutes after the oldest, not before', () => {+ expect(digestIsDue(undefined, 1e9)).toBe(false)+ expect(digestIsDue(at(1e9), 1e9 + NOTICE_DIGEST_MS - 1)).toBe(false)+ expect(digestIsDue(at(1e9), 1e9 + NOTICE_DIGEST_MS)).toBe(true)+ })+})++describe('a line', () => {+ it('names the task, shortens its title, and turns a status row into one sentence', () => {+ const line = noticeLine(state, row('task'), 'Done\n\nPR 2515 at 30a9942')+ expect(line).toMatch(/^- #1959 "Web app: an account menu[^"]{1,20}…": Done — PR 2515 at 30a9942 \(message a{24} in task\)$/)+ expect(line).not.toContain('keeps going on')+ })+ it('names a step with its task', () => {+ expect(noticeLine(state, row('step'), 'Jasper 2 lost its task.')).toContain('- #1991 "Review: Buddy copies" (step Review of #1959): Jasper 2 lost its task.')+ })+ it('names no task in the project chat', () => {+ expect(noticeLine(state, row('lead'), 'Tester has had no open task for 15 minutes.')).toBe(`- Tester has had no open task for 15 minutes. (message ${'a'.repeat(24)} in lead)`)+ })+ it('names a message it could not read by its id alone', () => {+ expect(noticeLine(state, row('lead'), null)).toBe(`- (message ${'a'.repeat(24)} in lead)`)+ expect(noticeLine(state, row('task'), null)).toMatch(/…" \(message a{24} in task\)$/)+ })+ it('stays one line whatever a step is called, its name raw or its title (review of #2560)', () => {+ const named = { id: 'forged', title: 'x', number: 7, reviewOf: 'task', step: 'Review\n- #1 "forged": Done' } as Conversation+ const untitled = { id: 'untitled', title: 'Check\n- #2 "forged": Done', number: 8, reviewOf: 'task' } as Conversation+ const forging = { ...state, conversations: [...state.conversations, named, untitled] } as SuperTabState+ for (const id of ['forged', 'untitled']) expect(noticeLine(forging, row(id), 'A notice.').split('\n')).toHaveLength(1)+ })+ it('stays one line of at most 200 characters, its ids whole', () => {+ const line = noticeLine(state, row('step'), `Done\n\nfirst\n- #1 "forged"\n${'word '.repeat(500)}`)+ expect(line).not.toContain('\n')+ expect(line.length).toBeLessThanOrEqual(200)+ expect(line.endsWith(`(message ${'a'.repeat(24)} in step)`)).toBe(true)+ })+})++describe('the digest', () => {+ it('says since when, how many, and how many wait', () => {+ expect(digestText(new Date('2026-11-02T06:30:12Z'), ['- one', '- two'], 0)).toBe(+ 'Notices since 06:30 UTC (2). Read one in full: harness super-tab message GROUP MESSAGE_ID.\n- one\n- two')+ expect(digestText(new Date('2026-11-02T06:30:12Z'), ['- one'], 10).split('\n').at(-1)).toBe('And 10 more, in the next digest.')+ })+ it('is its recipient\'s alone, on a backend that knows the marker whatever the kind', () => {+ const message = digestMessage('lead-agent', 'oldest', 'lead', { kind: 'agent', id: 'lead-agent', name: 'Lead', membershipGeneration: 'g' }, 'text', 3)+ expect(message).toMatchObject({ conversationId: 'lead', recipients: ['lead-agent'], source: { kind: 'notice-digest', count: 3, recipientsOnly: true } })+ expect(agentOnly(message.source, message.recipients)).toBe(true)+ expect(agentOnly({ kind: 'notice-digest' }, ['lead-agent'])).toBe(true)+ })+})++// A new cancel written by hand with the three open statuses would leave a gathered row to wait out the backstop, for nothing.+describe('every cancel', () => {+ it('ends gathered rows too', () => {+ for (const file of ['store.ts', 'native.ts']) {+ const source = readFileSync(join(process.cwd(), 'src/superTabs', file), 'utf8')+ expect(source).not.toMatch(/status: \{ in: \['queued', 'claimed', 'uncertain'\] \}[^\n]*\n?[^\n]*status: 'cancelled'/)+ expect(source).not.toMatch(/status: \{ in: \[\.\.\.OPEN_DELIVERY\] \} \},\s*data: \{ status: 'cancelled'/)+ }+ })+})diff --git a/backend/src/superTabs/noticeDigest.ts b/backend/src/superTabs/noticeDigest.tsnew file mode 100644index 000000000..9010b733c--- /dev/null+++ b/backend/src/superTabs/noticeDigest.ts@@ -0,0 +1,77 @@+import type { SuperTabDelivery } from '@prisma/client'+import { forRecipients, stableId, type Author, type Conversation, type MessageDraft, type SuperTabState } from './model.js'+import { projectsOf } from './projects.js'++// The server's routine notices to a project's coordinator go in one message at most every 5 minutes, and what someone waits on+// still goes at once (Ken, 2026-11-02; docs/plans/2026-11-02-pm-notice-digest-design.md): every message starts a new turn of a+// long-context session, and in 20 minutes 10 of 23 were notices like these. Only the server's own notices: never a post.++/** How long after the first notice gathered its digest is due: never on a fixed clock, and nothing when nothing was gathered. */+export const NOTICE_DIGEST_MS = 5 * 60_000+/** Past this a gathered delivery goes back to queued (store.ts settleDeliveries): its coordinator stopped polling. */+export const GATHERED_LIMIT_MS = 30 * 60_000+/** The notices in one digest; the rest go in the next. */+export const NOTICE_DIGEST_MAX = 50+const LINE_MAX = 200+const TITLE_MAX = 40+const STEP_MAX = 20++/** Notices nobody waits on within minutes. Not `pair-loop`, `terminal-alert`, `buddy-proposal`, `update-request`, `digest-request`+ * (throttled already, with instructions of their own) nor `agent-only`: each delivers at once, as any kind not listed does. */+export const DIGEST_KINDS: ReadonlySet<unknown> = new Set(['work-stalled', 'work-lost', 'work-resumed', 'idle', 'review-failed', 'review-capacity', 'overlap', 'note-removed'])++/** Whether a message to a coordinator waits for the digest: a routine notice, or a `work.status` row saying Done. Needs a human+ * and Blocked go at once; so does a status row written before rows said their status. */+export function gatheredNotice(source: unknown): boolean {+ const row = source as { kind?: unknown } | null | undefined+ return DIGEST_KINDS.has(row?.kind) || doneRow(source)+}++/** A `work.status` row saying Done: the one notice that outlives its sender (store.ts releasableNotices). */+export function doneRow(source: unknown): boolean {+ const row = source as { kind?: unknown; status?: unknown } | null | undefined+ return row?.kind === 'system' && row.status === 'done'+}++/** Whether the oldest gathered delivery has waited long enough. */+export const digestIsDue = (oldest: Pick<SuperTabDelivery, 'createdAt'> | undefined, now: number): boolean =>+ !!oldest && now - oldest.createdAt.getTime() >= NOTICE_DIGEST_MS++const shortened = (text: string, max: number) => text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1)).trimEnd()}…`++/** How a line names its task, as the update request does (projectUpdates.ts reportedAs), with its title; nothing for a chat with+ * no task, such as the project chat. */+function taskName(state: SuperTabState, group: Conversation | undefined): string {+ if (!group || projectsOf(state).some(p => p.leadConversationId === group.id)) return ''+ const named = (g: Conversation) => g.number !== undefined ? `#${g.number}` : JSON.stringify(shortened(g.title, TITLE_MAX))+ const title = group.number !== undefined ? ` ${JSON.stringify(shortened(group.title, TITLE_MAX))}` : ''+ const task = group.reviewOf ? state.conversations.find(c => c.id === group.reviewOf) : undefined+ return `${named(group)}${title}${task ? ` (step ${shortened(group.step ?? group.title, STEP_MAX)} of ${named(task)})` : ''}`+}++/** One notice as one line of at most 200 characters, whatever it holds: a worker's result collapses to one line, so it cannot+ * write a line of its own. [text] is null for a message that could not be read, which its ids still name. */+export function noticeLine(state: SuperTabState, delivery: Pick<SuperTabDelivery, 'conversationId' | 'messageId'>, text: string | null): string {+ const group = state.conversations.find(c => c.id === delivery.conversationId)+ // A step with no step name goes by its raw title, which may hold a newline (review of #2560).+ const name = taskName(state, group).replace(/\s+/g, ' ')+ const ids = ` (message ${delivery.messageId} in ${delivery.conversationId})`+ // A status row is its label, a blank line and its result (commands.ts work.status).+ const body = (text ?? '').trim().replace(/\s*\n\s*\n\s*/, ' — ').replace(/\s+/g, ' ')+ const head = `- ${name}${name && body ? ': ' : ''}`+ return `${head}${shortened(body, LINE_MAX - head.length - ids.length)}${ids}`.replace(/^- +/, '- ')+}++/** What a digest says: when it starts, how many, each notice oldest first, and how many wait for the next one. */+export function digestText(since: Date, lines: readonly string[], more: number): string {+ const at = since.toISOString().slice(11, 16)+ return [`Notices since ${at} UTC (${lines.length}). Read one in full: harness super-tab message GROUP MESSAGE_ID.`, ...lines,+ ...more > 0 ? [`And ${more} more, in the next digest.`] : []].join('\n')+}++/** The digest as its own message, in the project's Lead conversation, the coordinator's alone. Its id is its agent's and its oldest+ * delivery's: a retried poll writes it once, and that delivery is never gathered again. */+export function digestMessage(agentId: string, oldestDeliveryId: string, conversationId: string, sender: Author, text: string, count: number): MessageDraft {+ return { id: stableId('notice-digest', agentId, oldestDeliveryId), conversationId, author: sender, text, replyTo: null, recipients: [agentId],+ source: forRecipients({ kind: 'notice-digest', count }) }+}diff --git a/backend/src/superTabs/pageReads.ts b/backend/src/superTabs/pageReads.tsindex 3137fed12..92cd8aa0c 100644--- a/backend/src/superTabs/pageReads.ts+++ b/backend/src/superTabs/pageReads.ts@@ -86,6 +86,20 @@ export async function compactedDelivery(tx: Transaction, tabId: string, agentId:/** The deliveries a host is still told about (the rest are answered, cancelled or confirmed). */export const OPEN_DELIVERY = ['queued', 'claimed', 'uncertain'] as const+/** The deliveries a cancel ends: the open ones, and those gathered for a digest (noticeDigest.ts), which hosts are not told about+ * yet: a gathered delivery outlives its reason no more than an open one. */+export const CANCELLABLE_DELIVERY = [...OPEN_DELIVERY, 'gathered'] as const++/** An agent's deliveries gathered for its digest, oldest first, at most [limit]: one indexed read, the agent's as its open ones are. */+export async function agentGatheredDeliveries(tx: Transaction, tabId: string, agentId: string, limit: number): Promise<SuperTabDelivery[]> {+ const rows = await readBy(tx, 'SuperTabDelivery', 'agentOpen', [{ $match: { tabId, agentId, status: 'gathered' } }, { $sort: { createdAt: 1 } }, { $limit: limit }])+ return inConversationOrder(tx, tabId, rows.map(row => prismaRow<SuperTabDelivery>('SuperTabDelivery', row)))+}++/** How many deliveries an agent has gathered: read only when a digest is full, to say how many more wait. */+export async function agentGatheredCount(tx: Transaction, tabId: string, agentId: string): Promise<number> {+ return Number((await readBy(tx, 'SuperTabDelivery', 'agentOpen', [{ $match: { tabId, agentId, status: 'gathered' } }, { $count: 'n' }]))[0]?.n ?? 0)+}/** An agent's open deliveries, oldest first and each conversation's tied rows in its order: one indexed read, and the tied* messages' sequences only when there are ties. */diff --git a/backend/src/superTabs/parts/indexed.ts b/backend/src/superTabs/parts/indexed.tsindex fa4b284ef..5c93f1659 100644--- a/backend/src/superTabs/parts/indexed.ts+++ b/backend/src/superTabs/parts/indexed.ts@@ -70,6 +70,9 @@ export const NAMED_INDEX = {agentOpen: { tabId: 1, agentId: 1, status: 1, createdAt: 1 },/** Finished deliveries by their last change: those old enough to compact (deliveryCompaction.ts). */compaction: { status: 1, updatedAt: 1 },+ /** Unfinished deliveries in id order, a page at a time (deliverySettle.ts). Named: with a fourth status Mongo planned the pass on+ * `compaction` and sorted, reading far more than a page. */+ settle: { status: 1, _id: 1 },},/** Compacted receipts (pageReads.ts): a page's by message id, and a host's by the compacted delivery's id. */SuperTabReceipt: {diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 437b246b1..52b1279bf 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -15,7 +15,7 @@ import { applyCommand, authorizeCommandAccess, IGNORED_NOTE, LOOP_NOTICE_AT, mayimport { redactCredentials } from './credentials.js'import type { AvatarUpload } from './profile.js'import { reactionCounts, type ReactionTarget } from './reactions.js'-import { agentOpenDeliveries, compactedDelivery, deliveredCopies, messagesById, messagesPast, OPEN_DELIVERY, type MessageEdge, pageDeliveries, pageReactions, pageThreads, refreshReplies, type PageDelivery } from './pageReads.js'+import { agentGatheredCount, agentGatheredDeliveries, agentOpenDeliveries, CANCELLABLE_DELIVERY, compactedDelivery, deliveredCopies, messagesById, messagesPast, OPEN_DELIVERY, type MessageEdge, pageDeliveries, pageReactions, pageThreads, refreshReplies, type PageDelivery } from './pageReads.js'import { deliveriesByMessage } from './read/pageDeliveries.js'import { restoreDelivery } from './deliveryCompaction.js'import { threadSummaries } from './threads.js'@@ -58,12 +58,13 @@ import { DIRECT, readLastChangedAt, readParts, type ReadNamed } from './cachedReimport { revokeNativeContexts, SuperTabNativeStore } from './native.js'import { activeMember, addMember, hasWorkspaceAccess, listWorkspaces, memberId, WORKSPACE_ACCESS_REVOKED, workspaceForNewSwarm, requireWorkspaceAccess, requireWorkspaceRole, SwarmWorkspaces } from './workspaceStore.js'import { WORKSPACE_LABEL, type WorkspaceRole } from './workspaces.js'-import {+import { STATUS_LABELS,activeWork, actorKey, agent, agentOnly, appendPullRequestUrls, author, conversation, createSuperTab, fail, person, stableId, visibleState, finishWorker,SuperTabError, isLeads, knownKind, parkLaterConversations, type Actor, type Agent, type Assignment, type Author, type CommandEffects, type Conversation, type MessageDraft, type Person, type SuperTabState,} from './model.js'import { QUIET_CLAIM, type HoldReason } from './holdReason.js'import { stuck } from './deliverySettle.js'+import { digestIsDue, digestMessage, digestText, doneRow, GATHERED_LIMIT_MS, gatheredNotice, NOTICE_DIGEST_MAX, noticeLine } from './noticeDigest.js'import { agentDisplayName } from './agentNames.js'import { endedHolds, HOLDING, startedHolds, type WorkHold } from '../github/holds.js'import { accrueLent, addLent, lentAgents, lentProjects } from './leaderboard/lent.js'@@ -1515,7 +1516,7 @@ export class SuperTabStore {&& c.archived && !original.conversations.find(o => o.id === c.id)?.archived).map(c => c.id) : []// One plain match per conversation: an `in` on this hot collection is sent as $expr, which no index bounds (hotFilters).for (const conversationId of unreadable ? [command.conversationId, ...archivedSteps] : []) {- await tx.superTabDelivery.updateMany({ where: { tabId, conversationId, status: { in: ['queued', 'claimed', 'uncertain'] },+ await tx.superTabDelivery.updateMany({ where: { tabId, conversationId, status: { in: [...CANCELLABLE_DELIVERY] },...(command.type === 'conversation.agent' ? { agentId: command.agentId } : {}) },data: { status: 'cancelled', holdReason: null, holdSince: null } })}@@ -1524,7 +1525,7 @@ export class SuperTabStore {// Keep immutable history and operation receipts for audit/replay; all// reads require a live conversation. No removed group can deliver work.await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: { in: removedGroups.map(c => c.id) },- status: { in: ['queued', 'claimed', 'uncertain'] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })+ status: { in: [...CANCELLABLE_DELIVERY] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })}// Each conversation numbers its own messages. Only a change of a work group's state wakes its coordinator, read through// its latest message; an ordinary message never does (Dee, 2026-10-31).@@ -1690,8 +1691,9 @@ export class SuperTabStore {// On 2026-10-20 a Lead answered a message it had already read, then answered it again when the held// delivery was finally typed. An agent's reply settles that agent's own deliveries of the message.if (command.type === 'message.send' && command.replyTo && actor.kind === 'agent') {+ // A notice gathered for the digest and answered before it (read in its chat): the digest does not name it again.await tx.superTabDelivery.updateMany({ where: { tabId, messageId: command.replyTo, agentId: actor.agentId,- status: { in: ['queued', 'claimed', 'uncertain', 'delivered', 'confirmed'] } },+ status: { in: ['queued', 'claimed', 'uncertain', 'delivered', 'confirmed', 'gathered'] } },data: { status: 'answered', answeredAt: new Date(context.now), holdReason: null, holdSince: null } })}if (command.type === 'project.report' && actor.kind === 'agent') {@@ -1710,10 +1712,12 @@ export class SuperTabStore {.map(a => ({ authorKind: 'agent', authorId: a.id, authorGeneration: a.membershipGeneration })),]const cancelled: Prisma.SuperTabDeliveryWhereInput[] = [- ...revoked, ...(effects.cancelledAgents.length ? [{ agentId: { in: effects.cancelledAgents } }] : []),+ // A gathered row whose sender went stays for its digest, which judges it: a Done outlives the agent that sent it (review of #2560).+ ...revoked.map(sender => ({ ...sender, status: { not: 'gathered' } })), ...(effects.cancelledAgents.length ? [{ agentId: { in: effects.cancelledAgents } }] : []),]if (cancelled.length) await tx.superTabDelivery.updateMany({ where: { tabId,- status: { in: ['queued', 'claimed', 'uncertain'] }, OR: cancelled }, data: { status: 'cancelled', holdReason: null, holdSince: null } })+ status: { in: [...CANCELLABLE_DELIVERY] }, OR: cancelled }, data: { status: 'cancelled', holdReason: null, holdSince: null } })+ await this.requeueFormerLeads(tx, tabId, original, effects.state)for (const attempt of effects.previousAttempts) {await tx.superTabAttempt.create({ data: { id: attempt.assignment.id, tabId, conversationId: attempt.conversationId, snapshot: json(attempt) } })}@@ -2279,7 +2283,7 @@ export class SuperTabStore {if (!assignmentIds.length) returnconst assignmentId = { in: assignmentIds }await tx.superTabRun.deleteMany({ where: { tabId, assignmentId } })- await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId, status: { in: ['queued', 'claimed', 'uncertain'] } },+ await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId, status: { in: [...CANCELLABLE_DELIVERY] } },data: { status: 'cancelled', holdReason: null, holdSince: null } })}@@ -2316,12 +2320,16 @@ export class SuperTabStore {for (const recipient of [...message.recipients, ...message.buddyRecipients ?? []]) {const target = agent(state, recipient)const group = conversation(state, message.conversationId)+ // Written as ever, so its readers see the message at once; only its coordinator's delivery waits for the digest (noticeDigest.ts).+ // At the store's time, which the release and the settle pass measure from. No host lists it, so none is told.+ const gathered = gatheredNotice(message.source) && !!ledProject(state, recipient)deliveries.push({ id: stableId(message.id, recipient), tabId,conversationId: message.conversationId, messageId: message.id, agentId: recipient, machineId: target.machineId,machineOwnerId: target.machineOwnerId,assignmentId: activeWork(group) && group.assignment?.agentId === recipient ? group.assignment.id : null,membershipGeneration: target.membershipGeneration, authorKind: message.author.kind,- authorId: message.author.id, authorGeneration: message.author.membershipGeneration })+ authorId: message.author.id, authorGeneration: message.author.membershipGeneration,+ ...gathered ? { status: 'gathered', createdAt: new Date(this.now()) } : {} })}}if (rows.length) await tx.superTabMessage.createMany({ data: rows })@@ -2342,7 +2350,7 @@ export class SuperTabStore {deliveries = deliveries.filter(d => !have.has(d.id))}if (deliveries.length) await tx.superTabDelivery.createMany({ data: deliveries })- for (const delivery of deliveries) this.announce(tx, { machineId: delivery.machineId, tabId, agentId: delivery.agentId })+ for (const delivery of deliveries) if (delivery.status !== 'gathered') this.announce(tx, { machineId: delivery.machineId, tabId, agentId: delivery.agentId })}/** A Buddy thread session's first deliveries (buddySessions.ts): its person's messages sent in its thread while it started,@@ -2997,7 +3005,8 @@ export class SuperTabStore {return allowed}- private deliveryAllowed(state: SuperTabState, delivery: SuperTabDelivery): boolean {+ /** Whether a delivery's recipient may still read it there. */+ private recipientAllowed(state: SuperTabState, delivery: SuperTabDelivery): boolean {const target = state.agents.find(a => a.id === delivery.agentId)const group = state.conversations.find(c => c.id === delivery.conversationId)if (!target || target.membershipGeneration !== delivery.membershipGeneration || !group || group.archived) return false@@ -3005,6 +3014,13 @@ export class SuperTabStore {if (isLeads(group)) return false// A Buddy also hears its person's news outside its chat (buddyNews.ts), only where it reads as its person would (below).if (!group.agentIds.includes(target.id) && !isBuddy(target)) return false+ return canReadAgent(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }, target) &&+ canReadGroup(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }, group)+ }++ private deliveryAllowed(state: SuperTabState, delivery: SuperTabDelivery): boolean {+ if (!this.recipientAllowed(state, delivery)) return false+ const group = state.conversations.find(c => c.id === delivery.conversationId)!const sender = delivery.authorKind === 'person' ? state.people.find(p => p.id === delivery.authorId) : state.agents.find(a => a.id === delivery.authorId)if (!sender) return falseconst actor: Actor = delivery.authorKind === 'person'@@ -3012,8 +3028,6 @@ export class SuperTabStore {: { kind: 'agent', agentId: delivery.authorId, machineOwnerId: (sender as Agent).machineOwnerId }// A private conversation's sender and receiver must still be in its audience or be its Lead (projects.ts canReadGroup).if (!canReadGroup(state, actor, group)) return false- if (!canReadAgent(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }, target) ||- !canReadGroup(state, { kind: 'agent', agentId: target.id, machineOwnerId: target.machineOwnerId }, group)) return falseconst generation = 'generation' in sender ? sender.generation : sender.membershipGenerationreturn generation === delivery.authorGeneration && (!('role' in sender) || sender.role !== 'viewer')}@@ -3094,6 +3108,11 @@ export class SuperTabStore {// due: it loads nothing for it, or every poll repeats the loads over a growing window (Diego's issue file, 2026-10-27).const led = ledProject(loaded.state, agentId)let asked: Array<{ conversationId: string; personId: string; count: number }> = []+ // What this coordinator gathered, oldest first (noticeDigest.ts): one indexed read per coordinator poll.+ const gathered = led ? await agentGatheredDeliveries(tx, tabId, agentId, NOTICE_DIGEST_MAX) : []+ const release = digestIsDue(gathered[0], this.now()) ? gathered : []+ // A due digest reads its notices where they were written: a group asleep since is not cancelled for not being loaded.+ const groupIds = new Set(release.map(d => d.conversationId))const due = led && !loaded.state.paused ? digestDue(led, this.now()) : null// A day's digest stored while its project was not marked sent (its time moved later that day, on an older server) went// out: it only gets marked, or every poll would read for it again and fail on the duplicate (prod slow log, 2026-10-28).@@ -3103,9 +3122,10 @@ export class SuperTabStore {{ $project: { _id: 0, key: 1 } }]) as unknown as Array<{ key: string }>// A decision waits in its conversation even once that conversation went quiet.asked = await waitingInProject(tx, tabId, led.id)- const groupIds = [...new Set([...finished.map(g => g.key), ...asked.map(d => d.conversationId)])]- if (groupIds.length) loaded = await this.ensure(tx, loaded, { groupIds })+ for (const id of [...finished.map(g => g.key), ...asked.map(d => d.conversationId)]) groupIds.add(id)}+ // One load for both: a second would drop the first's groups.+ if (groupIds.size) loaded = await this.ensure(tx, loaded, { groupIds: [...groupIds] })const state = cloneData(loaded.state)if (sentAlready) {const project = projectOf(state, led!.id)@@ -3119,6 +3139,8 @@ export class SuperTabStore {// It reads no asleep group: only loaded groups' active work keeps an agent from being idle (project instructions, phase 4).if (led) written.push(...idleNotices(state, led.id, this.now(), new Set((await tx.superTabDelivery.findMany({where: { tabId, status: { in: [...OPEN_DELIVERY] } }, select: { agentId: true }, distinct: ['agentId'] })).map(d => d.agentId))))+ // Before the update request, which may carry them. Same rules as a listed delivery; a refused row ends as a refused one does.+ const { notices, refused } = await this.releasableNotices(tx, state, release)const update = projectUpdateRequest(state, target, this.now())let woken = falseif (update) {@@ -3136,6 +3158,26 @@ export class SuperTabStore {woken = true}}+ if (notices.length) {+ // After this page's cancels, before its rows are marked: all that remain, less what this digest names.+ const more = gathered.length === NOTICE_DIGEST_MAX ? await agentGatheredCount(tx, tabId, agentId) - notices.length : 0+ const text = digestText(notices[0]!.delivery.createdAt, notices.map(n => n.line), more)+ // One message when an update request goes in this poll: the PM gets one turn, not two. Never into one already stored: its row+ // would be kept as it is, with no lines, or fail the poll (writeMessages keepStored).+ const merged = woken && !await tx.superTabMessage.findUnique({ where: { id: update!.id }, select: { id: true } })+ if (merged) {+ update!.text = `${update!.text}\n\n${text}`+ update!.source = { ...update!.source, notices: notices.length }+ } else {+ written.push(digestMessage(agentId, gathered[0]!.id, projectOf(state, led!.id).leadConversationId, author(state, { kind: 'agent', agentId, machineOwnerId: target.machineOwnerId }), text, notices.length))+ }+ // By status too: two polls racing digest each row once. One by one: no `in` on this hot collection (hotFilters).+ for (const { delivery } of notices) await tx.superTabDelivery.updateMany({ where: { id: delivery.id, tabId, status: 'gathered' }, data: { status: 'digested' } })+ afterCommit(tx, () => logger.info('[swarm-deliveries] notice digest', { tabId, count: notices.length, cancelled: refused, more, length: text.length, merged }))+ } else if (refused) {+ // Every row of the page refused: no digest, and still seen.+ afterCommit(tx, () => logger.info('[swarm-deliveries] notice digest', { tabId, count: 0, cancelled: refused }))+ }// The morning digest is due once a day; recording it as sent is part of this same write, so it is sent once.const digest = digestRequest(state, target, this.now(), asked)if (digest) {@@ -3162,6 +3204,40 @@ export class SuperTabStore {})}+ /** An agent no longer its project's coordinator: its poll releases no digest now, so what it gathered is delivered to it one by+ * one, as before digests. It stays running, and they were written for it. Whatever command changed the lead, after that command's+ * cancels, so a row they ended stays ended. */+ private async requeueFormerLeads(tx: Transaction, tabId: string, before: SuperTabState, after: SuperTabState) {+ for (const project of projectsOf(before)) {+ const lead = (state: SuperTabState) => state.conversations.find(c => c.id === project.leadConversationId)?.leadId+ const was = lead(before)+ if (!was || lead(after) === was) continue+ const requeued = await tx.superTabDelivery.updateMany({ where: { tabId, agentId: was, status: 'gathered' }, data: { status: 'queued' } })+ const target = after.agents.find(a => a.id === was)+ if (requeued.count && target) this.announce(tx, { machineId: target.machineId, tabId, agentId: was })+ }+ }++ /** Of [rows], what a digest may name, each with its line, and how many were refused. A row that fails a listed delivery's checks is+ * cancelled, and left out. A Done whose sender alone fails them stays, by its label and ids: it is how the coordinator hears, once,+ * and its agent may be stopped within the 5 minutes; its result is that sender's, so it goes (review of #2560). Each message by+ * its id (no `in` on a hot collection); one that cannot be found is named by its id alone. */+ private async releasableNotices(tx: Transaction, state: SuperTabState, rows: SuperTabDelivery[]) {+ const notices: Array<{ delivery: SuperTabDelivery; line: string }> = []+ let refused = 0+ for (const delivery of rows) {+ const message = this.recipientAllowed(state, delivery)+ ? await tx.superTabMessage.findUnique({ where: { id: delivery.messageId }, select: { text: true, source: true } }) : undefined+ const allowed = message !== undefined && this.deliveryAllowed(state, delivery) && await this.senderAllowed(tx, state, delivery)+ if (!allowed && !(message && doneRow(message.source))) {+ refused += (await tx.superTabDelivery.updateMany({ where: { id: delivery.id, tabId: delivery.tabId, status: 'gathered' }, data: { status: 'cancelled', holdReason: null, holdSince: null } })).count+ continue+ }+ notices.push({ delivery, line: noticeLine(state, delivery, allowed ? message?.text ?? null : STATUS_LABELS.done) })+ }+ return { notices, refused }+ }+/** The agent's open deliveries, and those of them its Swarm still lets reach it. */private async allowedDeliveries(tx: Transaction, state: SuperTabState, tabId: string, agentId: string) {const open = await openDeliveries(tx, tabId, agentId)@@ -3256,6 +3332,8 @@ export class SuperTabStore {if (!delivery || !this.deliveryAllowed(state, delivery) || delivery.status === 'cancelled' && !typedAsEnded ||!await this.senderAllowed(tx, state, delivery)) fail('DELIVERY_REVOKED', 'This instruction is no longer authorized.', 403)if (delivery.status === 'answered') fail('DELIVERY_RESOLVED', 'This message was already answered.')+ // Never listed to a host: one claiming it by id never types it. It reaches the agent in a digest (noticeDigest.ts).+ if (delivery.status === 'gathered' || delivery.status === 'digested') fail('DELIVERY_RESOLVED', 'This notice goes in a digest.')if (delivery.status === 'confirmed' || delivery.status === 'superseded') {fail('DELIVERY_RESOLVED', 'A person has already resolved this delivery.')}@@ -3434,7 +3512,7 @@ export class SuperTabStore {const sequences = numberMessages(state, rows, now)if (!dirtyGroups(state, groupProject(state, group)).includes(group)) group.dormant = true// As a person's archive does (execute): a claim of a delivery here conflicts with this write.- await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: groupId, status: { in: [...OPEN_DELIVERY] } },+ await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: groupId, status: { in: [...CANCELLABLE_DELIVERY] } },data: { status: 'cancelled', holdReason: null, holdSince: null } })// A review's close also writes the work it reviews (review of #2322): a Ready for review committed since the load linked// a new pull request and saw this review still open, so it opened none. The touch makes one of the two writes retry,@@ -3460,6 +3538,17 @@ export class SuperTabStore {let settled = 0for (const delivery of rows) {const reachable = !!state && this.deliveryAllowed(state, delivery)+ // Inside its limit a gathered row its recipient may read waits for the digest, which judges its sender (releasableNotices).+ // Past it, its coordinator stopped polling (its machine off, the agent stopped): each goes on its own, once a host lists it.+ if (delivery.status === 'gathered' && !!state && this.recipientAllowed(state, delivery)) {+ if (now - delivery.createdAt.getTime() <= GATHERED_LIMIT_MS) continue+ if (reachable) {+ const requeued = await tx.superTabDelivery.updateMany({ where: { id: delivery.id, tabId, status: 'gathered' }, data: { status: 'queued' } })+ settled += requeued.count+ if (requeued.count) this.announce(tx, { machineId: delivery.machineId, tabId, agentId: delivery.agentId })+ continue+ }+ }if (!stuck(delivery, reachable, now)) continue// A held claim is the same while its claim and hold are: its live host claims it again on every poll (cli// superTabs/host.ts), so its write time would let it outrun the pass for good. Any other is as last written.@@ -3500,7 +3589,7 @@ export class SuperTabStore {assignment.result = 'The execution host confirmed that this harness stopped.'await tx.superTabRun.deleteMany({ where: { tabId, assignmentId } })await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId,- status: { in: ['queued', 'claimed', 'uncertain'] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })+ status: { in: [...CANCELLABLE_DELIVERY] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })await closeAssignment(tx, tabId, assignmentId, 'stopped', this.now())// No agent command closes this attempt, so nobody was told: in the two-account E2E of 2026-10-19// the Lead learned of a stopped worker only by re-reading status. Say it in the group, as thediff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.tsindex 9eb93b912..088962c28 100644--- a/backend/vitest.super-tabs.config.ts+++ b/backend/vitest.super-tabs.config.ts@@ -7,6 +7,6 @@ export default defineConfig({ test: { include: ['integration/superTabs.test.ts','integration/superTabObserver.test.ts', 'integration/productUsageConflicts.test.ts', 'integration/productUsageReceipts.test.ts', 'integration/schemaRelease.test.ts', 'integration/superTabBuddies.test.ts', 'integration/superTabNotAvailable.test.ts','integration/superTabBuddyProbes.test.ts', 'integration/superTabBuddySessions.test.ts', 'integration/superTabSwarmBuddy.test.ts', 'integration/superTabCosts.test.ts', 'integration/harnessSharesList.test.ts', 'integration/atlasSnapshot.test.ts', 'integration/queryStats.test.ts','integration/superTabEvidence.test.ts', 'integration/superTabAttemptModels.test.ts', 'integration/superTabNamedReads.test.ts', 'integration/swarmSweepPlans.test.ts', 'integration/workerIndexPlans.test.ts', 'integration/superTabReflection.test.ts',- 'integration/superTabMessagePages.test.ts', 'integration/superTabDeliveryCompaction.test.ts', 'integration/superTabThreads.test.ts',+ 'integration/superTabMessagePages.test.ts', 'integration/superTabDeliveryCompaction.test.ts', 'integration/superTabNoticeDigest.test.ts', 'integration/superTabThreads.test.ts','integration/superTabInstructions.test.ts', 'integration/superTabWorkflow.test.ts', 'integration/superTabDeletion.test.ts'], hookTimeout: 120000, testTimeout: 30000, setupFiles: ['integration/cacheOn.test-support.ts', 'src/lib/noRedis.test-support.ts'],fileParallelism: false, env: { NODE_ENV: 'test', HARNESS_CREDENTIAL_ENCRYPTION_KEY: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' } } })diff --git a/cli/src/core/agents/create.spec.ts b/cli/src/core/agents/create.spec.tsindex 4c7dd9cbd..212148530 100644--- a/cli/src/core/agents/create.spec.ts+++ b/cli/src/core/agents/create.spec.ts@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import { installedDsh } from '../../dsh/installed.js'-import { agentTmpEnv } from '../../lib/agentTmp.js'+import { agentTmpEnv, buddyTmpEnv } from '../../lib/agentTmp.js'import { dshPinnedPermissionMode } from '../../dsh/manifest.js'import { incompatibleHarnessEngine } from '../../dsh/compatibility.js'import { createAndRegisterPane } from '../../lib/createAgentPane.js'@@ -259,6 +259,17 @@ describe('creating an agent', () => {expect(vi.mocked(createAndRegisterPane).mock.calls.at(-1)![0].env).toMatchObject({ HARNESS_DSH: 'blender', TMPDIR: '/data/agent-tmp' })})+ // A Buddy's folder of its own, named for the folder it runs in, and never the owner's agents' shared one.+ it('gives a Buddy its own private temporary folder, and the launch\'s own variables win', async () => {+ vi.mocked(installedDsh).mockReturnValueOnce(installed() as never).mockReturnValueOnce(installed() as never)+ vi.mocked(buddyTmpEnv).mockReturnValueOnce({ TMPDIR: '/data-buddy-tmp/one', CLAUDE_CODE_TMPDIR: '/data-buddy-tmp/one', HARNESS_DSH: 'mine' })+ const calls = vi.mocked(agentTmpEnv).mock.calls.length+ expect(await setup().create(request({ dsh: 'blender', swarmRole: 'buddy' }))).toMatchObject({ ok: true })+ expect(buddyTmpEnv).toHaveBeenLastCalledWith('claude', expect.any(String))+ expect(vi.mocked(createAndRegisterPane).mock.calls.at(-1)![0].env).toMatchObject({ TMPDIR: '/data-buddy-tmp/one', CLAUDE_CODE_TMPDIR: '/data-buddy-tmp/one', HARNESS_DSH: 'blender' })+ expect(vi.mocked(agentTmpEnv).mock.calls.length).toBe(calls)+ })+it('keeps a selected Store harness when attaching a Swarm skill', async () => {vi.mocked(installedDsh).mockReturnValueOnce(installed() as never).mockReturnValueOnce(installed() as never)expect(await setup().create(request({ dsh: 'blender', swarmRole: 'agent' }))).toMatchObject({ ok: true })diff --git a/cli/src/core/agents/create.ts b/cli/src/core/agents/create.tsindex 097b0f941..f0e014249 100644--- a/cli/src/core/agents/create.ts+++ b/cli/src/core/agents/create.ts@@ -7,7 +7,7 @@ import type { NativeLaunch, NativeLaunchResult, NativeLaunchSource } from '../..** Moved verbatim out of `runForeground` (the core boundary, step 11: docs/design/2026-10-03-harnessd.md).*/-import { agentTmpEnv } from '../../lib/agentTmp.js'+import { agentTmpEnv, buddyTmpEnv } from '../../lib/agentTmp.js'import { realpathSync, statSync } from 'node:fs'import { readdir, stat } from 'node:fs/promises'import { dirname, join } from 'node:path'@@ -439,7 +439,7 @@ export function createAgentCreator({paneLaunch: windowsPaneLaunch(engine, { ...launchOptions, held: isWindowsHeldPane(argv) }),// Windows: the variables the argv's `/usr/bin/env` prefix carries elsewhere, last (engineLaunchEnv).// The private temporary folder first, so the launch's own variables win over it (lib/agentTmp.ts).- env: mergedLaunchEnv(mergedLaunchEnv(agentTmpEnv(engine, swarmSkill?.role), freshHarnessEnvironment(engine, mergedLaunchEnv(mergedLaunchEnv(gridLaunch?.env ?? mergedLaunchEnv(codexHome ? profileEnvironment(engine, codexHome) : undefined, relay?.env), dshEnv),+ env: mergedLaunchEnv(mergedLaunchEnv(swarmSkill?.role === 'buddy' ? buddyTmpEnv(engine, cwd) : agentTmpEnv(engine, swarmSkill?.role), freshHarnessEnvironment(engine, mergedLaunchEnv(mergedLaunchEnv(gridLaunch?.env ?? mergedLaunchEnv(codexHome ? profileEnvironment(engine, codexHome) : undefined, relay?.env), dshEnv),mergedLaunchEnv(mergedLaunchEnv(scmLaunchEnv(scmLaunchRecord), swarmGitHub?.env), native?.environment)), !!grid,permissionMode ?? (bypassPermission ? DEFAULT_HARNESS_PERMISSION : 'ask'))), engineLaunchEnv(engine, native)),grid: grid ? { baseUrl: grid.baseUrl, model: grid.model ?? null } : null,diff --git a/cli/src/lib/agentTmp.spec.ts b/cli/src/lib/agentTmp.spec.tsindex 64795d1b8..982d93a97 100644--- a/cli/src/lib/agentTmp.spec.ts+++ b/cli/src/lib/agentTmp.spec.ts@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterEach, describe, expect, it, vi } from 'vitest'import type { TeamConfig } from '../team/config.js'-import { agentTmpEnv, agentTmpFolder, agentTmpRoot, agentTmpState, prepareAgentTmp, resetAgentTmpSweep, sweepAgentTmp, type AgentTmpDeps } from './agentTmp.js'+import { agentTmpEnv, agentTmpFolder, agentTmpRoot, agentTmpState, buddyTmpEnv, buddyTmpFolder, buddyTmpOf, buddyTmpParent, prepareAgentTmp, resetAgentTmpSweep, sweepAgentTmp, sweepBuddyTmp, type AgentTmpDeps } from './agentTmp.js'const made: string[] = []afterEach(() => { for (const dir of made.splice(0)) rmSync(dir, { recursive: true, force: true }); resetAgentTmpSweep() })@@ -175,3 +175,118 @@ describe('what deletes it', () => {expect(await sweepAgentTmp(join(scratch(), 'missing'), NOW)).toBe(0)})})++describe('a Buddy\'s private temporary folder', () => {+ const DAY = 24 * 60 * 60_000+ /** A data folder in a scratch folder of its own, so the sibling `-buddy-tmp` is cleaned with it. */+ const dataIn = () => join(scratch(), 'data')++ it('is a 0700 folder under a 0700 parent, for Claude Code\'s own files too, outside the data folder', () => {+ const data = dataIn()+ const env = buddyTmpEnv('claude', '/work/one', deps(data))+ expect(env).toEqual({ TMPDIR: buddyTmpFolder('/work/one', data), CLAUDE_CODE_TMPDIR: buddyTmpFolder('/work/one', data) })+ expect(statSync(env.TMPDIR!).mode & 0o777).toBe(0o700)+ expect(statSync(buddyTmpParent(data)).mode & 0o777).toBe(0o700)+ expect(statSync(env.TMPDIR!).uid).toBe(process.geteuid!())+ expect(env.TMPDIR!.startsWith(`${data}/`)).toBe(false)+ })++ it('is one per Buddy, and stays the same across a relaunch', () => {+ const data = dataIn()+ expect(buddyTmpFolder('/work/one', data)).not.toBe(buddyTmpFolder('/work/two', data))+ expect(buddyTmpOf('/work/one', deps(data))).toBe(buddyTmpOf('/work/one', deps(data)))+ })++ it('gives another engine TMPDIR alone', () => {+ const data = dataIn()+ expect(buddyTmpEnv('codex', '/work/one', deps(data))).toEqual({ TMPDIR: buddyTmpFolder('/work/one', data) })+ })++ it('is only for the owner\'s account on a computer with a Team account, on macOS and Linux', () => {+ const data = dataIn()+ expect(buddyTmpEnv('claude', '/work/one', deps(data, { config: () => null }))).toEqual({})+ expect(buddyTmpEnv('claude', '/work/one', deps(data, { user: () => 'harnessteam' }))).toEqual({})+ expect(buddyTmpEnv('claude', '/work/one', deps(data, { platform: 'win32' }))).toEqual({})+ expect(buddyTmpOf('/work/one', deps(data, { config: () => null }))).toBeNull()+ expect(existsSync(buddyTmpParent(data))).toBe(false)+ })++ // Not yet run in Linux's sandbox (bubblewrap): a folder it would not open breaks every command of a Buddy (review of #2563).+ it('leaves Linux on the system\'s folder until the sandbox has been tried there', () => {+ const data = dataIn()+ expect(buddyTmpEnv('claude', '/work/one', deps(data, { platform: 'linux' }))).toEqual({})+ expect(buddyTmpOf('/work/one', deps(data, { platform: 'linux' }))).toBeNull()+ expect(existsSync(buddyTmpParent(data))).toBe(false)+ })++ it('names the folder by its real path when the data folder is reached through a link, as the guard compares real paths', () => {+ const at = scratch(), real = join(at, 'real'), data = join(at, 'data')+ mkdirSync(real); symlinkSync(real, data)+ expect(buddyTmpOf('/work/one', deps(data))).toBe(join(`${data}-buddy-tmp`, buddyTmpFolder('/work/one', data).split('/').at(-1)!))+ const linked = join(scratch(), 'link'), parentReal = scratch()+ symlinkSync(scratch(), linked)+ const nested = join(parentReal, 'real-data'), viaLink = join(scratch(), 'via')+ mkdirSync(nested); symlinkSync(parentReal, viaLink)+ expect(buddyTmpOf('/work/one', deps(join(viaLink, 'real-data')))).toBe(join(`${nested}-buddy-tmp`, buddyTmpFolder('/work/one', nested).split('/').at(-1)!))+ })++ it('closes a folder someone left open, and a parent too', () => {+ const data = dataIn(), folder = buddyTmpFolder('/work/one', data)+ mkdirSync(folder, { recursive: true, mode: 0o777 })+ chmodSync(folder, 0o777); chmodSync(buddyTmpParent(data), 0o777)+ expect(buddyTmpOf('/work/one', deps(data))).toBe(folder)+ expect(statSync(folder).mode & 0o777).toBe(0o700)+ expect(statSync(buddyTmpParent(data)).mode & 0o777).toBe(0o700)+ })++ it.each(['the folder', 'the parent'])('refuses a link in place of %s, and the Buddy keeps the system\'s folder, saying so', (which) => {+ const data = dataIn(), elsewhere = scratch(), folder = buddyTmpFolder('/work/one', data)+ if (which === 'the folder') { mkdirSync(buddyTmpParent(data), { recursive: true, mode: 0o700 }); symlinkSync(elsewhere, folder) } else { mkdirSync(data, { recursive: true }); symlinkSync(elsewhere, buddyTmpParent(data)) }+ chmodSync(elsewhere, 0o755)+ const d = deps(data)+ expect(buddyTmpOf('/work/one', d)).toBeNull()+ expect(buddyTmpEnv('claude', '/work/one', d)).toEqual({})+ expect(d.log).toHaveBeenCalledWith(expect.stringContaining('private temporary folder'))+ expect(statSync(elsewhere).mode & 0o777).toBe(0o755)+ })++ it('deletes what nothing has changed in for 7 days inside each Buddy\'s folder, keeping the folder a live Buddy has as its TMPDIR', async () => {+ const data = dataIn(), folder = buddyTmpOf('/work/one', deps(data))!+ writeFileSync(join(folder, 'stale'), 'x')+ const later = Date.now() + 8 * DAY+ writeFileSync(join(folder, 'fresh'), 'x'); utimesSync(join(folder, 'fresh'), new Date(later), new Date(later))+ expect(await sweepBuddyTmp(buddyTmpParent(data), later)).toBe(1)+ expect(existsSync(join(folder, 'stale'))).toBe(false)+ expect(existsSync(join(folder, 'fresh'))).toBe(true)+ expect(existsSync(folder)).toBe(true)+ })++ it('removes a Buddy\'s folder only when empty and idle for 30 days', async () => {+ const data = dataIn(), folder = buddyTmpOf('/work/one', deps(data))!+ await sweepBuddyTmp(buddyTmpParent(data), Date.now() + 8 * DAY)+ expect(existsSync(folder)).toBe(true)+ await sweepBuddyTmp(buddyTmpParent(data), Date.now() + 31 * DAY)+ expect(existsSync(folder)).toBe(false)+ })++ it('sweeps nothing through a link, in the parent\'s place or among the Buddies\' folders', async () => {+ const data = dataIn(), target = scratch()+ writeFileSync(join(target, 'kept'), 'x')+ mkdirSync(buddyTmpParent(data), { recursive: true, mode: 0o700 })+ symlinkSync(target, join(buddyTmpParent(data), 'link'))+ await sweepBuddyTmp(buddyTmpParent(data), Date.now() + 40 * DAY)+ expect(existsSync(join(target, 'kept'))).toBe(true)+ const other = join(scratch(), 'parent')+ symlinkSync(target, other)+ expect(await sweepBuddyTmp(other, Date.now() + 40 * DAY)).toBe(0)+ expect(existsSync(join(target, 'kept'))).toBe(true)+ })++ it('is swept by a launch, with the Team account gone too', async () => {+ const data = dataIn(), folder = buddyTmpOf('/work/one', deps(data))!+ writeFileSync(join(folder, 'stale'), 'x')+ resetAgentTmpSweep()+ agentTmpEnv('claude', undefined, deps(data, { config: () => null, now: () => Date.now() + 8 * DAY }))+ await vi.waitFor(() => expect(existsSync(join(folder, 'stale'))).toBe(false))+ })+})diff --git a/cli/src/lib/agentTmp.ts b/cli/src/lib/agentTmp.tsindex f4a419d9d..84bb8ba14 100644--- a/cli/src/lib/agentTmp.ts+++ b/cli/src/lib/agentTmp.ts@@ -8,12 +8,14 @@* Swarm's skills tell agents not to name /tmp themselves.** In the data folder because a wide Buddy's guard already closes that folder (lib/buddyGuard.ts), so a Buddy cannot read other- * agents' temporary files here. The same guard would refuse it writes here, so a Buddy keeps the system's folder.+ * agents' temporary files here. A Buddy has its own folder beside the data folder, one per Buddy, since its files come from a+ * person's private work and must not reach another person's Buddy (buddyTmpOf; docs/plans/2026-11-02-buddy-private-temp-plan.md).*/-import { chmodSync, lstatSync, mkdirSync } from 'node:fs'-import { lstat, readdir, rm } from 'node:fs/promises'+import { createHash } from 'node:crypto'+import { chmodSync, lstatSync, mkdirSync, realpathSync } from 'node:fs'+import { lstat, readdir, rm, rmdir } from 'node:fs/promises'import { userInfo } from 'node:os'-import { join } from 'node:path'+import { basename, dirname, join } from 'node:path'import { env } from '../config/env.js'import { isTerminalEngine, type AgentEngine } from '../engines/types.js'import { readTeamConfig, type TeamConfig } from '../team/config.js'@@ -21,6 +23,8 @@ import { readTeamConfig, type TeamConfig } from '../team/config.js'/** Nothing changed in this long, and a top-level entry is deleted: longer than a task runs, as /tmp's own cleaners are. */const KEEP_MS = 7 * 24 * 60 * 60_000const SWEEP_EVERY_MS = 24 * 60 * 60_000+/** A Buddy's empty folder is kept this long: it is a live Buddy's TMPDIR while the Buddy runs, however quiet. */+const KEEP_EMPTY_BUDDY_MS = 30 * 24 * 60 * 60_000export interface AgentTmpDeps {platform: NodeJS.Platform@@ -39,6 +43,26 @@ const realDeps: AgentTmpDeps = {export const agentTmpFolder = (dataDir: string = env.ADAPTER_DATA_DIR): string => join(dataDir, 'agent-tmp')+/** Where every Buddy's folder is: beside the data folder, which a wide Buddy's guard and sandbox close whole. */+export const buddyTmpParent = (dataDir: string = env.ADAPTER_DATA_DIR): string => `${dataDir}-buddy-tmp`++/** The folder of the Buddy that runs in [root], by its real path, so a relaunch finds it. Short: some tools make sockets in TMPDIR. */+export function buddyTmpFolder(root: string, dataDir: string = env.ADAPTER_DATA_DIR): string {+ return join(buddyTmpParent(dataDir), createHash('sha256').update(realOfFolder(root)).digest('hex').slice(0, 16))+}++/** [path]'s real path: of the nearest folder that exists, with the rest added, so a Buddy's folder removed before its cleanup+ * still names the same temporary folder. */+export function realOfFolder(path: string): string {+ let at = path, rest = ''+ for (;;) {+ try { return join(realpathSync(at), rest) } catch { /* not there: its folder decides */ }+ if (dirname(at) === at) return path+ rest = join(basename(at), rest)+ at = dirname(at)+ }+}+/** This account is the owner of a computer with a Team account. Windows' temporary folder is already the account's own. */function ownerOfTeamComputer(deps: AgentTmpDeps): boolean {if (deps.platform === 'win32') return false@@ -91,6 +115,31 @@ export async function sweepAgentTmp(folder: string, now: number): Promise<numberreturn removed}+/** Each Buddy's folder swept as `sweepAgentTmp` sweeps one. The folder stays, as it is a live Buddy's TMPDIR, until it has been+ * empty and idle for 30 days; a relaunch makes it again. Anything else at the top goes when idle, a link without what it points at. */+export async function sweepBuddyTmp(parent: string, now: number): Promise<number> {+ let names: string[]+ try {+ const stat = await lstat(parent)+ if (!stat.isDirectory() || stat.uid !== process.geteuid?.()) return 0+ names = await readdir(parent)+ } catch { return 0 }+ let removed = 0+ for (const name of names) {+ const path = join(parent, name)+ try {+ if (!(await lstat(path)).isDirectory()) {+ if (!(await changedSince(path, now - KEEP_MS))) { await rm(path, { force: true }); removed++ }+ continue+ }+ removed += await sweepAgentTmp(path, now)+ // Fails, as it should, on a folder with anything in it.+ if (!(await changedSince(path, now - KEEP_EMPTY_BUDDY_MS))) await rmdir(path)+ } catch { /* not empty, or gone: the next sweep looks again */ }+ }+ return removed+}+let lastSweep: number | null = nullexport function resetAgentTmpSweep(): void { lastSweep = null }@@ -99,7 +148,8 @@ function sweepWhenDue(folder: string, deps: AgentTmpDeps): void {if (lastSweep !== null && now >= lastSweep && now - lastSweep < SWEEP_EVERY_MS) returnlastSweep = now// Never in the launch's way: an agent's start does not wait on a walk of old files.- void sweepAgentTmp(folder, now).then((removed) => { if (removed) deps.log(`removed ${removed} entries nothing had changed in for 7 days`) })+ void Promise.all([sweepAgentTmp(folder, now), sweepBuddyTmp(buddyTmpParent(deps.dataDir), now)])+ .then(([agents, buddies]) => { if (agents + buddies) deps.log(`removed ${agents + buddies} entries nothing had changed in for 7 days`) })}/**@@ -119,6 +169,29 @@ export function agentTmpEnv(engine: AgentEngine, role: string | undefined, deps:return { TMPDIR: folder }}+/**+ * The private folder of the Buddy that runs in [root], made and closed, or null: on a computer with no Team account, in the+ * Team account itself, on Windows or Linux, or when it cannot be made private, which the log says. Null opens nothing in its guard.+ */+export function buddyTmpOf(root: string, deps: AgentTmpDeps = realDeps): string | null {+ if (deps.platform === 'win32') return null+ sweepWhenDue(agentTmpFolder(deps.dataDir), deps)+ // macOS alone until the sandbox has been tried with bubblewrap: a folder it would not open breaks every command of a Buddy.+ if (deps.platform !== 'darwin' || !ownerOfTeamComputer(deps)) return null+ const folder = buddyTmpFolder(root, deps.dataDir)+ // The parent first: making the folder through a link in the parent's place would make it where that link points.+ // By its real path, as the guard compares real paths: a data folder reached through a link would refuse its own reads.+ try { if (prepareAgentTmp(buddyTmpParent(deps.dataDir)) && prepareAgentTmp(folder)) return realpathSync(folder) } catch { /* said below */ }+ deps.log(`the private temporary folder ${folder} could not be made private; this Buddy uses the system's`)+ return null+}++/** A Buddy's launch variables for that folder. Claude Code keeps its own files in /tmp/claude-<uid> whatever TMPDIR says. */+export function buddyTmpEnv(engine: AgentEngine, root: string, deps: AgentTmpDeps = realDeps): Record<string, string> {+ const folder = buddyTmpOf(root, deps)+ return folder ? { TMPDIR: folder, ...(engine === 'claude' ? { CLAUDE_CODE_TMPDIR: folder } : {}) } : {}+}+/** The folder, where agents here are given it: a place they drop files that a person may then open (./pathContainment.ts). */export function agentTmpRoot(deps: AgentTmpDeps = realDeps): string | null {return ownerOfTeamComputer(deps) ? agentTmpFolder(deps.dataDir) : nulldiff --git a/cli/src/lib/buddyGuard.ts b/cli/src/lib/buddyGuard.tsindex 7365dfe84..3c8db3015 100644--- a/cli/src/lib/buddyGuard.ts+++ b/cli/src/lib/buddyGuard.ts@@ -3,6 +3,7 @@ import { createHash, randomUUID } from 'node:crypto'import { chmodSync, closeSync, existsSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, rmSync, statSync,writeFileSync } from 'node:fs'import { basename, dirname, isAbsolute, join, relative } from 'node:path'+import { buddyTmpParent } from './agentTmp.js'import { homedir, tmpdir } from 'node:os'import { isTeamAccount } from '../team/config.js'import { buddyAccountFile } from './buddyAccount.js'@@ -75,7 +76,7 @@ const SYSTEM_READABLE = process.platform === 'darwin'* agent records stay closed), [tmpDirs] where Claude Code keeps other sessions' tool output, and [repos] the project's repositories (owner/name), the only ones gh api reads. */export function buddyWideOf(input: { home: string; dataDir: string; tmpDirs: readonly string[]; repos: readonly string[]; hosts?: readonly string[];system?: readonly string[]; launch?: string; closed?: readonly string[]; otherSessions?: readonly string[] }): BuddyWide {- return { home: input.home, launch: input.launch ?? randomUUID(), accountFile: buddyAccountFile(input.dataDir), readable: [input.home, ...(input.system ?? SYSTEM_READABLE)], repos: input.repos, hosts: input.hosts ?? [], sessionTemp: input.tmpDirs, denied: [...CLOSED_IN_HOME.map(path => join(input.home, path)), input.dataDir, ...input.tmpDirs, ...(input.closed ?? [])],+ return { home: input.home, launch: input.launch ?? randomUUID(), accountFile: buddyAccountFile(input.dataDir), readable: [input.home, ...(input.system ?? SYSTEM_READABLE)], repos: input.repos, hosts: input.hosts ?? [], sessionTemp: input.tmpDirs, denied: [...CLOSED_IN_HOME.map(path => join(input.home, path)), input.dataDir, buddyTmpParent(input.dataDir), ...input.tmpDirs, ...(input.closed ?? [])],approvalsDir: join(input.dataDir, 'buddy-approvals'), ...(input.otherSessions?.length ? { otherSessions: input.otherSessions } : {}) }}@@ -208,7 +209,7 @@ const TOOL_SIGN_INS = ['.config/gh', '.config/argocd', '.argocd', '.kube']* command of the session. Ken chose it over running those tools outside the sandbox (10-30), so the sandbox's no-writes* and host list hold for them too.*/-export function buddySandboxSettings(root: string, wide: BuddyWide): Record<string, unknown> {+export function buddySandboxSettings(root: string, wide: BuddyWide, ownTemp: string | null = null): Record<string, unknown> {// Open to the sandbox: the tools' own sign-ins, and Claude Code's temporary folder, where every command's output goes// (with it closed, even cat failed: "cat: stdout: Operation not permitted", Claude Code 2.1.314). The guard keeps both// closed to the Buddy's own reads.@@ -222,7 +223,8 @@ export function buddySandboxSettings(root: string, wide: BuddyWide): Record<stri// temporary folder (both found by the real sandbox test, review of #2310). That folder itself stays writable: Claude// Code writes a file there for each command from inside the sandbox ("/bin/bash: /tmp/claude-501/cwd-…: Operation not// permitted" without it).- filesystem: { allowWrite: [], denyWrite: [...new Set([root, ...cloneOf(root), ...wide.sessionTemp.map(path => `${path}/-*`)])],+ // Beside a Team account its own temporary folder is the one exception, out of every Buddy's, which stay closed (lib/agentTmp.ts).+ filesystem: { allowWrite: ownTemp ? [ownTemp] : [], ...(ownTemp ? { allowRead: [ownTemp] } : {}), denyWrite: [...new Set([root, ...cloneOf(root), ...wide.sessionTemp.map(path => `${path}/-*`)])],denyRead: wide.denied.filter(path => !signIns.has(path)) },}}@@ -281,7 +283,7 @@ const KEPT_MS = 24 * 60 * 60 * 1000/** The folder that holds the one Buddies' folders (superTabs/buddyHome.ts BUDDY_HOMES, which a spec keeps equal): this file's* guard is written from lib, which imports nothing of superTabs. */const ONE_BUDDY_HOMES = 'buddy-home'-export const buddyGuardSource = (root: string, reads: BuddyReads, wide: BuddyWide | null = null): string => String.raw`#!/usr/bin/env node+export const buddyGuardSource = (root: string, reads: BuddyReads, wide: BuddyWide | null = null, ownTemp: string | null = null): string => String.raw`#!/usr/bin/env node// A Buddy's guard, written by Harness (cli/src/lib/buddyGuard.ts). Do not edit: Harness writes it again at each launch.import { createHash } from 'node:crypto'import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readSync, realpathSync, statSync } from 'node:fs'@@ -296,6 +298,8 @@ const KEPT_MS = ${KEPT_MS}// Wide mode (docs/specs/2026-10-30-buddy-read-access.md): null keeps every read in the folder. Set only for a Buddy on its// person's own machine, under their own account; it names their home and the places in it that stay closed.const WIDE = ${JSON.stringify(wide)}+// Its own private temporary folder beside a Team account (lib/agentTmp.ts), null elsewhere: read here, in either mode, and no other Buddy's.+const OWN_TEMP = ${JSON.stringify(ownTemp)}// A person's one Buddy or plain session: its folder holds every project's code, and a proposal goes to any one project's PM.const ONE_BUDDY = ${JSON.stringify(basename(dirname(root)) === ONE_BUDDY_HOMES)}const TOOLS = new Set(['TodoWrite', 'ToolSearch'])@@ -377,6 +381,17 @@ function inside(path) {}}+// Whether [path] is in its own temporary folder: named whole, by its real path, so a link or a ".." out is out, and with no+// secret's name below that folder. 'file': one regular file, for content search, which in a folder would read those names too.+function ownTemp(path, kind) {+ if (!OWN_TEMP || typeof path !== 'string' || !isAbsolute(path)) return false+ const real = realOf(path)+ if (!real || !under(real, OWN_TEMP)) return false+ if (secretName(relative(OWN_TEMP, real)) || secretName(relative(OWN_TEMP, resolve(path)))) return false+ if (kind !== 'file') return true+ try { return statSync(real).isFile() } catch { return false }+}+// Whether [part], read as a path from the folder, leaves it: absolute (the machine's files, /dev), a ".." part, or, by its// real path when the guard answers, a link out (one a pull brought after launch too), a broken link, or a path under one.// What another process changes after that answer is outside the guard (see the top of this file).@@ -809,12 +824,12 @@ function decide(input) {if (TOOLS.has(input.tool_name)) return true// Its read tools, in its folder: Read a file there, Grep and Glob there (their folder by default), LS a folder there.// Read opens what its person sent it too, and the Artifact tool reads the links they sent.- if (input.tool_name === 'Read') return inside(tool.file_path) || attached(tool.file_path) || outsideAllowed(tool.file_path, 'any')+ if (input.tool_name === 'Read') return inside(tool.file_path) || attached(tool.file_path) || ownTemp(tool.file_path, 'any') || outsideAllowed(tool.file_path, 'any')if (input.tool_name === 'Artifact') return artifactAllowed(tool)- if (input.tool_name === 'LS') return inside(tool.path) || outsideAllowed(tool.path, 'dir')- if (input.tool_name === 'Grep') return tool.path === undefined || inside(tool.path) || outsideAllowed(tool.path, 'file')+ if (input.tool_name === 'LS') return inside(tool.path) || ownTemp(tool.path, 'any') || outsideAllowed(tool.path, 'dir')+ if (input.tool_name === 'Grep') return tool.path === undefined || inside(tool.path) || ownTemp(tool.path, 'file') || outsideAllowed(tool.path, 'file')if (input.tool_name === 'Glob') {- return (tool.path === undefined || inside(tool.path) || outsideAllowed(tool.path, 'tree')) && typeof tool.pattern === 'string'+ return (tool.path === undefined || inside(tool.path) || ownTemp(tool.path, 'any') || outsideAllowed(tool.path, 'tree')) && typeof tool.pattern === 'string'&& !outward(tool.pattern)}// A command never leaves Claude Code's sandbox (wide mode's, lib/buddyGuard.ts buddySandboxSettings): the guard's allowdiff --git a/cli/src/lib/buddyGuard.wide.claude.spec.ts b/cli/src/lib/buddyGuard.wide.claude.spec.tsindex 810ce13eb..b35f24842 100644--- a/cli/src/lib/buddyGuard.wide.claude.spec.ts+++ b/cli/src/lib/buddyGuard.wide.claude.spec.ts@@ -4,6 +4,7 @@ import type { AddressInfo } from 'node:net'import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterAll, beforeAll, describe, expect, it } from 'vitest'+import { buddyTmpParent } from './agentTmp.js'import { PERMISSION_MODES } from './engineLaunch.js'import { prepareSwarmSkill } from './swarmSkills.js'import { buddyAccountFile, buddyApprovalsOf, buddyLaunchOf, buddyLaunchWide, buddyReadsOf, grantBuddyWide, judgeBuddyApprovals, recordBuddyApprovals,@@ -38,13 +39,14 @@ describe.skipIf(!claudeBin || process.platform !== 'darwin')('a wide-mode Buddyconst ranOf = (name: string) => existsSync(join(ran, name)) ? readFileSync(join(ran, name), 'utf8') : ''/** Runs [calls] through Claude Code in [at] (the Buddy's folder), as a Buddy launches, and answers what each returned. */- async function drive(calls: Call[], at: string) {+ async function drive(calls: Call[], at: string, temp?: string) {const api = fakeModel(calls)await new Promise<void>((resolve) => api.server.listen(0, '127.0.0.1', resolve))const env: NodeJS.ProcessEnv = {PATH: `${bin}:/usr/bin:/bin:/usr/sbin:/sbin`, HOME: home, SHELL: '/bin/bash', CLAUDE_CONFIG_DIR: join(root, 'config'), ANTHROPIC_API_KEY: API_KEY,ANTHROPIC_BASE_URL: `http://127.0.0.1:${(api.server.address() as AddressInfo).port}`, GIT_CONFIG_GLOBAL: '/dev/null', DISABLE_AUTOUPDATER: '1',- TMPDIR: root,+ TMPDIR: temp ?? root,+ ...(temp ? { CLAUDE_CODE_TMPDIR: temp } : {}),}const claude = spawn(claudeBin!, ['-p', 'go', ...PERMISSION_MODES.claude!.buddy, '--model', 'claude-sonnet-4-5', '--output-format', 'json'],{ cwd: at, env, stdio: ['ignore', 'pipe', 'pipe'] })@@ -54,7 +56,7 @@ describe.skipIf(!claudeBin || process.platform !== 'darwin')('a wide-mode Buddy}// A Buddy's folder is a worktree of its person's clone, as Harness creates it (review of #2310).- function buddyFolder(name: string) {+ function buddyFolder(name: string, ownTemp: string | null = null) {const clone = join(root, `${name}-clone`), at = join(root, name)mkdirSync(clone)git(clone, 'init', '-q', '-b', 'main')@@ -64,7 +66,7 @@ describe.skipIf(!claudeBin || process.platform !== 'darwin')('a wide-mode Buddygit(clone, 'worktree', 'add', '-q', '-b', name, at)// Harness prepares it in wide mode, as on its person's own Mac: their home is the throwaway one.prepareSwarmSkill(at, { role: 'buddy', key }, (folderRoot) => buddyLaunchWide(folderRoot, { platform: 'darwin', team: false, home,- dataDir: process.env.ADAPTER_DATA_DIR!, uid: process.getuid?.() ?? 0, hasBwrap: false, engineHomes: [] }))+ dataDir: process.env.ADAPTER_DATA_DIR!, uid: process.getuid?.() ?? 0, hasBwrap: false, engineHomes: [] }), () => ownTemp)return realpathSync(at)}@@ -154,6 +156,51 @@ describe.skipIf(!claudeBin || process.platform !== 'darwin')('a wide-mode Buddy})})+ // Beside a Team account: Claude Code and its tools keep their temporary files in the Buddy's own folder, and the sandbox+ // opens that one alone, with the guard taken out too.+ describe('its private temporary folder, in the sandbox', () => {+ const steps = { own: bash(''), read: bash(''), viaTmpdir: bash('touch "$TMPDIR/through-tmpdir"'), other: bash(''), otherKey: bash(''), system: bash('') }+ let run: Awaited<ReturnType<typeof drive>>, own: string, other: string+ const shared = join('/private/tmp', `planted-${process.pid}-${Date.now()}`)++ beforeAll(async () => {+ const parent = buddyTmpParent(process.env.ADAPTER_DATA_DIR!)+ own = join(parent, 'own-buddy'); other = join(parent, 'other-buddy')+ for (const dir of [own, other]) mkdirSync(dir, { recursive: true, mode: 0o700 })+ writeFileSync(join(other, 'output'), `${KEY}-other-buddy\n`)+ own = realpathSync(own); other = realpathSync(other)+ const at = buddyFolder('with-temp', own)+ steps.own.input.command = `touch '${join(own, 'made-here')}'`+ steps.read.input.command = `cat '${join(own, 'made-here')}'`+ steps.other.input.command = `touch '${join(other, 'planted')}'`+ steps.otherKey.input.command = `cat '${join(other, 'output')}'`+ steps.system.input.command = `touch '${shared}'`+ const settingsFile = join(at, '.claude', 'settings.local.json')+ const settings = JSON.parse(readFileSync(settingsFile, 'utf8'))+ chmodSync(settingsFile, 0o600)+ writeFileSync(settingsFile, JSON.stringify({ ...settings, hooks: {}, permissions: { defaultMode: 'dontAsk', allow: ['Bash'] } }))+ run = await drive(Object.values(steps), at, own)+ }, 180_000)++ it('lets commands write and read there, TMPDIR included', () => {+ for (const step of [steps.own, steps.read, steps.viaTmpdir]) expect(run.result(step)?.is_error, step.input.command as string).toBeFalsy()+ expect(existsSync(join(own, 'made-here'))).toBe(true)+ })++ it('refuses another Buddy\'s folder and the shared /tmp', () => {+ for (const step of [steps.other, steps.otherKey, steps.system]) expect(run.result(step)?.is_error, step.input.command as string).toBe(true)+ expect(existsSync(join(other, 'planted'))).toBe(false)+ expect(existsSync(shared)).toBe(false)+ expect(run.bodies.join('\n')).not.toContain(`${KEY}-other-buddy`)+ })++ afterAll(() => rmSync(buddyTmpParent(process.env.ADAPTER_DATA_DIR!), { recursive: true, force: true }))++ it('leaves Claude Code\'s own files for this session in that folder', () => {+ expect(existsSync(join(own, `claude-${process.getuid?.() ?? 0}`))).toBe(true)+ })+ })+// The second line: the folder's settings without the guard, every Bash call allowed. The sandbox alone must still// refuse each write, and reach no host off its list.describe('its sandbox, with the guard taken out', () => {diff --git a/cli/src/lib/buddyGuard.wide.spec.ts b/cli/src/lib/buddyGuard.wide.spec.tsindex 908909a62..6f448d823 100644--- a/cli/src/lib/buddyGuard.wide.spec.ts+++ b/cli/src/lib/buddyGuard.wide.spec.ts@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os'import { ENGINES } from '../engines/types.js'import { basename, dirname, join } from 'node:path'import { afterAll, beforeEach, describe, expect, it } from 'vitest'+import { buddyTmpParent } from './agentTmp.js'import { BUDDY_ENGINE_HOMES, markBuddyNarrow, allowBuddyReads, engineHomesOutsideDefaults, buddyApprovalsOf, buddyGuardSource, buddyLaunchWide, buddySandboxSettings, buddyWideOf, grantBuddyWide, hasBuddyApprovals,judgeBuddyApprovals, recordBuddyApprovals, revokeBuddyWide, writeBuddyAccount } from './buddyGuard.js'@@ -78,6 +79,67 @@ function answer(tool: string, input: Record<string, unknown>, guard = script): {const decide = (tool: string, input: Record<string, unknown>, guard = script) => answer(tool, input, guard).permissionDecisionconst bash = (command: string, guard = script) => decide('Bash', { command, description: 'x' }, guard)+describe('its private temporary folder, beside a Team account', () => {+ const tmpParent = buddyTmpParent(dataDir), own = join(tmpParent, 'own-buddy'), theirs = join(tmpParent, 'other-buddy')+ const ownGuard = join(parent, 'buddy-guard-own-tmp.mjs'), ownNarrow = join(parent, 'buddy-guard-own-tmp-narrow.mjs')+ mkdirSync(own, { recursive: true }); mkdirSync(theirs, { recursive: true }); mkdirSync(join(dataDir, 'agent-tmp'), { recursive: true })+ const realOwn = realpathSync(own)+ writeFileSync(join(own, 'output.txt'), 'mine'); writeFileSync(join(own, '.env'), 'SECRET=1'); writeFileSync(join(theirs, 'output.txt'), 'theirs')+ writeFileSync(join(dataDir, 'agent-tmp', 'output.txt'), 'an agent\'s'); writeFileSync(join(dataDir, 'lists.json'), '{}')+ symlinkSync(join(home, '.ssh', 'id_ed25519'), join(own, 'key-link')); symlinkSync(join(theirs, 'output.txt'), join(own, 'their-link'))+ writeFileSync(ownGuard, buddyGuardSource(root, reads, wide, realOwn)); writeFileSync(ownNarrow, buddyGuardSource(root, reads, null, realOwn))++ it.each([['wide', ownGuard], ['narrow', ownNarrow]])('%s: reads its own folder with Read, LS, Grep and Glob', (_, guard) => {+ expect(decide('Read', { file_path: join(realOwn, 'output.txt') }, guard)).toBe('allow')+ expect(decide('LS', { path: realOwn }, guard)).toBe('allow')+ expect(decide('Grep', { pattern: 'x', path: join(realOwn, 'output.txt') }, guard)).toBe('allow')+ // Content search takes one file: a folder could hold a secret's name that Read refuses.+ expect(decide('Grep', { pattern: 'x', path: realOwn }, guard)).toBe('deny')+ expect(decide('Glob', { pattern: '*', path: realOwn }, guard)).toBe('allow')+ })++ it.each([['wide', ownGuard], ['narrow', ownNarrow]])('%s: still refuses every other agent\'s and the data folder', (_, guard) => {+ for (const path of [join(theirs, 'output.txt'), join(dataDir, 'agent-tmp', 'output.txt'), join(dataDir, 'lists.json'), join(tmpClaude, 'output.txt')]) {+ expect(decide('Read', { file_path: path }, guard), path).toBe('deny')+ }+ for (const path of [theirs, tmpParent, join(dataDir, 'agent-tmp'), dataDir]) {+ expect(decide('LS', { path }, guard), path).toBe('deny')+ expect(decide('Grep', { pattern: 'x', path }, guard), path).toBe('deny')+ expect(decide('Glob', { pattern: '*', path }, guard), path).toBe('deny')+ }+ })++ it.each([['wide', ownGuard], ['narrow', ownNarrow]])('%s: refuses a link out, a .. out and a secret\'s name inside it', (_, guard) => {+ for (const path of [join(realOwn, 'key-link'), join(realOwn, 'their-link'), `${realOwn}/../other-buddy/output.txt`, join(realOwn, '.env')]) {+ expect(decide('Read', { file_path: path }, guard), path).toBe('deny')+ }+ })++ it('never lets it write there, by a tool or by the shell', () => {+ expect(decide('Write', { file_path: join(realOwn, 'x'), content: 'x' }, ownGuard)).toBe('deny')+ expect(decide('Edit', { file_path: join(realOwn, 'output.txt'), old_string: 'm', new_string: 'n' }, ownGuard)).toBe('deny')+ expect(bash(`cat ${join(realOwn, 'output.txt')} > ${join(realOwn, 'x')}`, ownGuard)).toBe('deny')+ expect(bash(`rm ${join(realOwn, 'output.txt')}`, ownGuard)).toBe('deny')+ })++ it('without one, as on a computer with no Team account, the folder stays closed', () => {+ expect(decide('Read', { file_path: join(realOwn, 'output.txt') })).toBe('deny')+ expect(decide('Read', { file_path: join(realOwn, 'output.txt') }, narrow)).toBe('deny')+ })++ it('closes every Buddy\'s folder to a wide Buddy, and its sandbox opens only its own', () => {+ expect(wide.denied).toContain(tmpParent)+ const closed = buddySandboxSettings(root, wide) as { filesystem: Record<string, string[] | undefined> }+ expect(closed.filesystem.allowWrite).toEqual([])+ expect(closed.filesystem.allowRead ?? []).toEqual([])+ const open = buddySandboxSettings(root, wide, realOwn) as { filesystem: Record<string, string[]> }+ expect(open.filesystem.allowWrite).toEqual([realOwn])+ expect(open.filesystem.allowRead).toEqual([realOwn])+ expect(open.filesystem.denyRead).toContain(tmpParent)+ expect(open.filesystem.denyWrite).toContain(root)+ })+})+describe('wide mode: reading outside the folder', () => {it('reads a file outside the folder only in wide mode', () => {const notes = join(home, 'work', 'notes.txt')diff --git a/cli/src/lib/launchOverrides.spec.ts b/cli/src/lib/launchOverrides.spec.tsindex 88fe3ba31..405ae3be2 100644--- a/cli/src/lib/launchOverrides.spec.ts+++ b/cli/src/lib/launchOverrides.spec.ts@@ -1,5 +1,5 @@import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'-import { agentTmpEnv } from './agentTmp.js'+import { agentTmpEnv, buddyTmpEnv } from './agentTmp.js'import { tmpdir } from 'node:os'import { join } from 'node:path'import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'@@ -571,10 +571,21 @@ describe('buildLaunchOverrides — the owner\'s private temporary folder (auditexpect(agentTmpEnv).toHaveBeenLastCalledWith('claude', undefined)})- it('names the saved role, so a Buddy relaunches without it', async () => {+ it('names the saved role of an agent', async () => {const swarm = { args: () => [], prepare: () => ({ instructions: 'x' }) }- await buildLaunchOverrides(deps({ swarm } as never).d, 'claude', { cwd: '/w', swarmSkill: { role: 'buddy', key: 'k' } as never }, 'a')- expect(agentTmpEnv).toHaveBeenLastCalledWith('claude', 'buddy')+ await buildLaunchOverrides(deps({ swarm } as never).d, 'claude', { cwd: '/w', swarmSkill: { role: 'agent', key: 'k' } as never }, 'a')+ expect(agentTmpEnv).toHaveBeenLastCalledWith('claude', 'agent')+ })++ // A restart, update, resume or fork of a Buddy keeps its own folder: its guard still names it (review of #2563).+ it('keeps a relaunched Buddy in its own folder, and the launch\'s own variables win', async () => {+ const swarm = { args: () => [], prepare: () => ({ instructions: 'x' }) }+ const agents = vi.mocked(agentTmpEnv).mock.calls.length+ vi.mocked(buddyTmpEnv).mockReturnValueOnce({ TMPDIR: '/data-buddy-tmp/one', CLAUDE_CODE_TMPDIR: '/data-buddy-tmp/one' })+ expect(await buildLaunchOverrides(deps({ swarm } as never).d, 'claude', { cwd: '/w', swarmSkill: { role: 'buddy', key: 'k' } as never }, 'a'))+ .toMatchObject({ ok: true, overrides: { env: { TMPDIR: '/data-buddy-tmp/one', CLAUDE_CODE_TMPDIR: '/data-buddy-tmp/one' } } })+ expect(buddyTmpEnv).toHaveBeenLastCalledWith('claude', '/w')+ expect(vi.mocked(agentTmpEnv).mock.calls.length).toBe(agents)})it('gives way to the launch\'s own variables', async () => {diff --git a/cli/src/lib/launchOverrides.ts b/cli/src/lib/launchOverrides.tsindex 63400b891..9cea8e67e 100644--- a/cli/src/lib/launchOverrides.ts+++ b/cli/src/lib/launchOverrides.ts@@ -13,7 +13,7 @@ import type { SwarmSkill } from './savedSkill.js'* backend's capabilities and the config directory writer) are exactly the parts worth stubbing in a spec.*/-import { agentTmpEnv } from './agentTmp.js'+import { agentTmpEnv, buddyTmpEnv } from './agentTmp.js'import type { NativeLaunch, NativeLaunchResult, NativeLaunchSource } from '../engines/nativeLaunch.js'import type { AgentEngine } from '../engines/types.js'import { subscriptionModelLaunch } from './subscriptionModel.js'@@ -326,7 +326,7 @@ export async function prepareLaunchOverrides(})if (told.length) overrides = { ...overrides, extraArgs: joinedInstructions(engine, [...overrides.extraArgs, ...told]) }// The launch's own variables win over the private temporary folder, as at agent_create.- const launchEnv = { ...agentTmpEnv(engine, source.swarmSkill?.role), ...overrides.env, ...native?.environment }+ const launchEnv = { ...(source.swarmSkill?.role === 'buddy' && source.cwd ? buddyTmpEnv(engine, source.cwd) : agentTmpEnv(engine, source.swarmSkill?.role)), ...overrides.env, ...native?.environment }return { ok: true, overrides: { ...overrides, ...(native ? { native } : {}), env: launchEnv, clearEnv: [...overrides.clearEnv, ...harnessEnvToClear(overrides.env)] } }} }}diff --git a/cli/src/lib/swarmSkills.spec.ts b/cli/src/lib/swarmSkills.spec.tsindex c7893db7a..37919fec9 100644--- a/cli/src/lib/swarmSkills.spec.ts+++ b/cli/src/lib/swarmSkills.spec.ts@@ -917,6 +917,23 @@ describe('a Buddy\'s folder (Lead\'s ruling on the privacy review of #1992)', ()expect(statSync(join(root, '.claude', 'buddy-launch')).mode & 0o222).toBe(0)})+ it('tells a Buddy\'s guard and sandbox its own private temporary folder, and no other', () => {+ const workspace = fixture()+ const root = realpathSync(workspace), own = join(root, '..', 'own-temp')+ const wide = buddyWideOf({ home: join(root, 'home'), dataDir: process.env.ADAPTER_DATA_DIR!, tmpDirs: [], repos: [], hosts: [] })+ const asked: string[] = []+ prepareSwarmSkill(workspace, { role: 'buddy', key: 'session' }, () => wide, (at) => { asked.push(at); return own })+ expect(asked).toEqual([root])+ expect(JSON.parse(readFileSync(join(workspace, '.claude', 'settings.local.json'), 'utf8')).sandbox).toEqual(buddySandboxSettings(root, wide, own))+ expect(readFileSync(join(root, '.claude', 'buddy-guard.mjs'), 'utf8')).toBe(buddyGuardSource(root, buddyReadsOf('session'), wide, own))+ })++ it('asks for no folder for a role other than Buddy', () => {+ const asked: string[] = []+ prepareSwarmSkill(fixture(), { role: 'agent', key: 'session' }, () => null, (at) => { asked.push(at); return null })+ expect(asked).toEqual([])+ })+it('takes back at each launch the grant a session had before it', () => {const workspace = fixture()const reads = buddyReadsOf('relaunched')diff --git a/cli/src/lib/swarmSkills.ts b/cli/src/lib/swarmSkills.tsindex c0095e76c..cc120498a 100644--- a/cli/src/lib/swarmSkills.ts+++ b/cli/src/lib/swarmSkills.ts@@ -1,5 +1,6 @@/** Built into the CLI so contributed machines need no separately installed plugin. */import { ignoreHarnessRuntime } from './harnessRuntimeIgnore.js'+import { buddyTmpOf } from './agentTmp.js'import { buddyGuardCommand, buddyGuardSource, buddyLaunchFile, buddyLaunchWide, buddyReadsOf, buddySandboxSettings, revokeBuddyWide, type BuddyWide } from './buddyGuard.js'import { managedNodePath } from './nodeRuntime.js'import { isMessagesCommand } from '../engines/kit/messagesHook.js'@@ -710,11 +711,12 @@ const modeOf = (skill: SwarmSkill, version: string) =>* A new file holds the text of the session's saved mode; a kept one is described by the text it holds, so the prompt line* never names one mode while the file holds the other. No project-wide native skill links: two roles may share a workspace. *//** [wideOf]: whether a Buddy launched here reads beyond its folder (lib/buddyGuard.ts buddyLaunchWide); tests name it. */-export function prepareSwarmSkill(workspace: string, saved: SavedSwarmSkill, wideOf: (root: string) => BuddyWide | null = buddyLaunchWide): { file: string; instructions: string } {+export function prepareSwarmSkill(workspace: string, saved: SavedSwarmSkill, wideOf: (root: string) => BuddyWide | null = buddyLaunchWide,+ tmpOf: (root: string) => string | null = buddyTmpOf): { file: string; instructions: string } {const skill = skillOf(saved)const root = realpathSync(workspace)// First, so a skill that cannot be prepared still leaves a Buddy's folder locked (re-check of #1992).- if (skill.role === 'buddy') lockBuddyFolder(root, skill.key, wideOf(root))+ if (skill.role === 'buddy') lockBuddyFolder(root, skill.key, wideOf(root), tmpOf(root))const dir = skillDirectory(root, skill, true)!ignoreHarnessRuntime(root)const file = join(dir, 'SKILL.md')@@ -807,7 +809,7 @@ function ignoreBuddyFiles(root: string): void {writeFileSync(file, BUDDY_IGNORE, { mode: 0o600 })}-function lockBuddyFolder(root: string, key: string, wide: BuddyWide | null): void {+function lockBuddyFolder(root: string, key: string, wide: BuddyWide | null, ownTemp: string | null): void {const settings = join(root, '.claude', 'settings.local.json'), guard = join(root, '.claude', 'buddy-guard.mjs')mkdirSync(join(root, '.claude'), { recursive: true })// Both were made read-only by the last launch, and both are written again: a relaunch runs this release's guard.@@ -818,8 +820,8 @@ function lockBuddyFolder(root: string, key: string, wide: BuddyWide | null): voiconst launchFile = buddyLaunchFile(root)if (existsSync(launchFile)) chmodSync(launchFile, 0o600)if (wide) writeFileSync(launchFile, `${wide.launch}\n`, { mode: 0o600 }); else rmSync(launchFile, { force: true })- writeFileSync(guard, buddyGuardSource(root, buddyReadsOf(key), wide), { mode: 0o600 })- writeFileSync(settings, `${JSON.stringify(buddyClaudeSettings(guard, wide ? buddySandboxSettings(root, wide) : null), null, 2)}\n`, { mode: 0o600 })+ writeFileSync(guard, buddyGuardSource(root, buddyReadsOf(key), wide, ownTemp), { mode: 0o600 })+ writeFileSync(settings, `${JSON.stringify(buddyClaudeSettings(guard, wide ? buddySandboxSettings(root, wide, ownTemp) : null), null, 2)}\n`, { mode: 0o600 })ignoreBuddyFiles(root)const walk = (dir: string) => {for (const entry of readdirSync(dir, { withFileTypes: true })) {diff --git a/cli/src/superTabs/inCore/teamPurge.spec.ts b/cli/src/superTabs/inCore/teamPurge.spec.tsindex cbcdbb1c9..300d98a55 100644--- a/cli/src/superTabs/inCore/teamPurge.spec.ts+++ b/cli/src/superTabs/inCore/teamPurge.spec.ts@@ -1,4 +1,5 @@-import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'+import { buddyTmpFolder, buddyTmpParent } from '../../lib/agentTmp.js'+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync, realpathSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { describe, expect, it, vi } from 'vitest'@@ -72,6 +73,39 @@ const call = (cwd: string, name: string, input: Record<string, string>) => JSON./** What a failed sweep of a shared transcript folder answers. */const left = (kind: keyof typeof SHARED_LEFT) => SHARED_LEFT[kind]+describe('a Buddy\'s private temporary folder when its session ends', () => {+ // A plain session of the one Buddy chat shares its folder with the main Buddy and closes itself when idle (review of #2563).+ const claudeFiles = (temp: string, folder: string, session: string) =>+ join(temp, `claude-${process.getuid?.() ?? 0}`, realpathSync(folder).replace(/[^A-Za-z0-9]/g, '-'), session)++ it('keeps it while its Buddy folder is there, another session may run in it, and removes only this session\'s output', async () => {+ const home = dir(), folder = join(dir(), 'buddy-one')+ mkdirSync(folder)+ const temp = buddyTmpFolder(folder), SESSION = '11111111-1111-4111-8111-111111111111', OTHER = '22222222-2222-4222-8222-222222222222'+ for (const session of [SESSION, OTHER]) { mkdirSync(claudeFiles(temp, folder, session), { recursive: true }); writeFileSync(join(claudeFiles(temp, folder, session), 'output'), 'private') }+ writeFileSync(join(temp, 'a-tool'), 'x')+ await scrubClaudeSession(home, target({ sessionId: SESSION, cwd: folder }))+ expect(existsSync(claudeFiles(temp, folder, SESSION))).toBe(false)+ expect(existsSync(claudeFiles(temp, folder, OTHER))).toBe(true)+ expect(existsSync(join(temp, 'a-tool'))).toBe(true)+ await scrubClaudeSession(home, target({ sessionId: null, cwd: folder }))+ expect(existsSync(temp)).toBe(true)+ rmSync(buddyTmpParent(), { recursive: true, force: true })+ })++ it('goes whole once its Buddy folder is gone, and another Buddy\'s stays', async () => {+ const home = dir(), folder = join(dir(), 'buddy-one'), other = join(dir(), 'buddy-two')+ mkdirSync(folder); mkdirSync(other)+ const mine = buddyTmpFolder(folder), theirs = buddyTmpFolder(other)+ for (const at of [mine, theirs]) { mkdirSync(at, { recursive: true }); writeFileSync(join(at, 'output'), 'private') }+ rmSync(folder, { recursive: true })+ await scrubClaudeSession(home, target({ sessionId: null, cwd: folder }))+ expect(existsSync(mine)).toBe(false)+ expect(existsSync(theirs)).toBe(true)+ rmSync(buddyTmpParent(), { recursive: true, force: true })+ })+})+describe('scrubbing a Claude Code session from the Team user\'s shared home', () => {// Security review 2 of #2375: Claude Code's transcript folder name makes every '/' and '.' a dash, so a removed worktree// `<worktrees>/old/notes` shares it with an unrelated `~/harnesses/worktrees-old/notes`. Only transcripts that record nodiff --git a/cli/src/superTabs/inCore/teamPurge.ts b/cli/src/superTabs/inCore/teamPurge.tsindex 942262ac7..64025fa8d 100644--- a/cli/src/superTabs/inCore/teamPurge.ts+++ b/cli/src/superTabs/inCore/teamPurge.ts@@ -13,6 +13,7 @@* reviewed purge drops the session from the stopped catalog, so a retry after a failed sweep had nothing left to scrub from.* Everything here reads and writes asynchronously: a Team home holds gigabytes of transcripts, and this runs in the core.*/+import { buddyTmpFolder, realOfFolder } from '../../lib/agentTmp.js'import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, type Dirent } from 'node:fs'import { readdir, readFile, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'import { basename, dirname, join } from 'node:path'@@ -316,6 +317,14 @@ export async function scrubClaudeSession(home: string, target: PurgeTarget, past})for (const hash of new Set([...pastes, ...found])) if (SESSION.test(hash)) await rm(join(claude, 'paste-cache', `${hash}.txt`), { force: true })if (folder) await removeTranscripts(join(claude, 'projects', claudeSlug(folder)), folder, told)+ // Its private temporary folder beside a Team account: command output from its person's private work (lib/agentTmp.ts). A plain+ // session shares its Buddy's folder, and this one's TMPDIR with it, so the whole folder goes only once that folder has; the+ // sweep takes what a tool left meanwhile (review of #2563).+ if (folder) {+ const temp = buddyTmpFolder(folder)+ if (!existsSync(folder)) await rm(temp, { recursive: true, force: true })+ else if (sessionId) await rm(join(temp, `claude-${process.getuid?.() ?? 0}`, claudeSlug(realOfFolder(folder)), sessionId), { recursive: true, force: true })+ }if (sessionId) {for (const sub of ['file-history', 'session-env']) await rm(join(claude, sub, sessionId), { recursive: true, force: true })await rm(join(claude, 'debug', `${sessionId}.txt`), { force: true })diff --git a/cli/vitest.setup.ts b/cli/vitest.setup.tsindex 0ec79e6e6..6d2f4847e 100644--- a/cli/vitest.setup.ts+++ b/cli/vitest.setup.ts@@ -72,5 +72,8 @@ vi.mock('./src/lib/agentTmp.js', async (importOriginal) => {agentTmpEnv: vi.fn((engine: Parameters<typeof real.agentTmpEnv>[0], role: string | undefined, deps?: Parameters<typeof real.agentTmpEnv>[2]) =>deps ? real.agentTmpEnv(engine, role, deps) : {}),agentTmpRoot: vi.fn((deps?: Parameters<typeof real.agentTmpRoot>[0]) => deps ? real.agentTmpRoot(deps) : null),+ buddyTmpEnv: vi.fn((engine: Parameters<typeof real.buddyTmpEnv>[0], root: string, deps?: Parameters<typeof real.buddyTmpEnv>[2]) =>+ deps ? real.buddyTmpEnv(engine, root, deps) : {}),+ buddyTmpOf: vi.fn((root: string, deps?: Parameters<typeof real.buddyTmpOf>[1]) => deps ? real.buddyTmpOf(root, deps) : null),}})diff --git a/companions/src/application/lessons/propose.spec.ts b/companions/src/application/lessons/propose.spec.tsindex 4f2c94266..80cbefd46 100644--- a/companions/src/application/lessons/propose.spec.ts+++ b/companions/src/application/lessons/propose.spec.ts@@ -471,7 +471,7 @@ describe('harness pair lessons', () => {}const out: string[] = []const errors: string[] = []- const base = { port: 1, machineId: async () => 'machine-a', connect, env: {} as NodeJS.ProcessEnv, output: (l: string) => out.push(l), error: (l: string) => errors.push(l) }+ const base = { port: 1, socketPath: null, machineId: async () => 'machine-a', connect, env: {} as NodeJS.ProcessEnv, output: (l: string) => out.push(l), error: (l: string) => errors.push(l) }vi.useRealTimers()expect(await pairCommand(['lessons', 'approve', 'beef01', '--json'], base)).toBe(1)expect(out.pop()).toContain('"error":"CONFIRM"')diff --git a/companions/src/companion/client.spec.ts b/companions/src/companion/client.spec.tsindex 5237f9a77..3bf76437d 100644--- a/companions/src/companion/client.spec.ts+++ b/companions/src/companion/client.spec.ts@@ -55,7 +55,7 @@ function daemon(reply: (payload: Json) => Json) {const base = (connect: (url: string) => PairSocket, over: Partial<PairCommandDeps> = {}): PairCommandDeps & { out: string[]; err: string[] } => {const out: string[] = []const err: string[] = []- return { port: 4242, machineId: async () => 'machine-a', connect, env: {}, output: (l) => out.push(l), error: (l) => err.push(l), out, err, ...over }+ return { port: 4242, socketPath: null, machineId: async () => 'machine-a', connect, env: {}, output: (l) => out.push(l), error: (l) => err.push(l), out, err, ...over }}let dirs: string[] = []@@ -87,6 +87,19 @@ describe('pairRequest: one request, settled once', () => {expect(d.connect).toHaveBeenLastCalledWith('ws://127.0.0.1:4242/api/local-ws', { 'X-Harness-Local': 'c'.repeat(43) })})+ it('goes over the daemon\'s socket where it has one, and shows the port nothing, credential or not', async () => {+ const d = daemon(() => ({ ok: true }))+ await pairRequest(base(d.connect, { socketPath: '/data/daemon-4242.sock', socketPrivate: () => true, localCredential: 'c'.repeat(43) }), { verb: 'status' })+ expect(d.connect).toHaveBeenCalledTimes(1)+ expect(d.connect).toHaveBeenCalledWith('ws+unix:///data/daemon-4242.sock:/api/local-ws', {})+ })++ it('a socket that is missing or not private is not used, and the port is not tried', async () => {+ const d = daemon(() => ({ ok: true }))+ await expect(pairRequest(base(d.connect, { socketPath: '/nonexistent/daemon-4242.sock', localCredential: 'c'.repeat(43) }), { verb: 'status' })).rejects.toThrow(/not private/)+ expect(d.connect).not.toHaveBeenCalled()+ })+it('an error rejects with it; a close after it changes nothing and closes once', async () => {const d = scripted((frame, s) => {if (frame.type === 'machine_select') queueMicrotask(() => { s.error(new Error('ECONNREFUSED')); s.close(1006, '') })diff --git a/companions/src/companion/client.ts b/companions/src/companion/client.tsindex 65ff19e70..0784f65a1 100644--- a/companions/src/companion/client.ts+++ b/companions/src/companion/client.ts@@ -8,6 +8,8 @@* daemon refuses them (TOKEN_REQUIRED). The daemon decides everything; this file only asks.*/import { randomUUID } from 'node:crypto'+import { lstatSync } from 'node:fs'+import { dirname } from 'node:path'import { CONTROL_TOOLS } from './control.js'import { harnessPaneEnv } from '../shared/approval.js'import { presentedToken } from './token.js'@@ -27,23 +29,42 @@ export interface PairClientDeps {port: number/** This computer's machine id, as its daemon knows it; resolved from /api/status when absent. */machineId: () => Promise<string | null>- /** A loopback socket to the daemon carrying [headers]: its local credential, which a TCP connection- * must show (cli/src/lib/localCredential.ts). */+ /** A socket to the daemon at [url], carrying [headers]: nothing over its Unix socket, or over TCP its local credential. */connect: (url: string, headers: Record<string, string>) => PairSocket- /** The daemon's local credential, read by the caller from its data dir (`hook-credential`). */+ /** The daemon's 0600 Unix socket (cli/src/lib/localSocket.ts `unixSocketPath`), null only where it can have none: Windows, or a data+ * folder too long for one. Required, so no caller reaches TCP by forgetting: any account can hold that port (audit H1). */+ socketPath: string | null+ /** Whether [socketPath] is the daemon's, by the rule every client uses; a test's stand-in. */+ socketPrivate?: (path: string) => boolean+ /** The daemon's local credential, read by the caller from its data dir (`hook-credential`), shown only where there is no socket. */localCredential?: string | nullenv: NodeJS.ProcessEnvtokenFile?: string | nulltimeoutMs?: number}+/** A socket of this account's, owner only, in a real folder nobody else can write to (store/tools/local-daemon.mjs, the same rule). */+function socketIsPrivate(path: string): boolean {+ const uid = process.getuid?.()+ try {+ const folder = lstatSync(dirname(path)), file = lstatSync(path)+ return folder.isDirectory() && (folder.mode & 0o022) === 0 && file.isSocket() && (file.mode & 0o077) === 0+ && (uid === undefined || (folder.uid === uid && file.uid === uid))+ } catch {+ return false+ }+}+/** One `pair` request to this computer's daemon. Resolves its reply; rejects only when it cannot be asked. */export async function pairRequest(deps: PairClientDeps, payload: Record<string, unknown>): Promise<Record<string, unknown>> {const machineId = await deps.machineId()if (!machineId) throw new Error('Harness is not running on this computer. Start it with `harness start`.')const token = presentedToken(deps.env, deps.tokenFile)+ if (deps.socketPath && !(deps.socketPrivate ?? socketIsPrivate)(deps.socketPath)) throw new Error('Harness is not running on this computer, or its socket is not private. Start it with `harness start`.')return new Promise((resolve, reject) => {- const socket = deps.connect(`ws://127.0.0.1:${deps.port}/api/local-ws`, deps.localCredential ? { 'X-Harness-Local': deps.localCredential } : {})+ const socket = deps.socketPath+ ? deps.connect(`ws+unix://${deps.socketPath}:/api/local-ws`, {})+ : deps.connect(`ws://127.0.0.1:${deps.port}/api/local-ws`, deps.localCredential ? { 'X-Harness-Local': deps.localCredential } : {})const requestId = randomUUID()let settled = falseconst finish = (error: Error | null, reply?: Record<string, unknown>): void => {diff --git a/companions/src/companion/mcp.spec.ts b/companions/src/companion/mcp.spec.tsindex d64e15040..ca5a630ee 100644--- a/companions/src/companion/mcp.spec.ts+++ b/companions/src/companion/mcp.spec.ts@@ -98,7 +98,7 @@ describe('harness pair <verb>', () => {it('asks as a tool client, and carries the token only when this process holds one', async () => {const daemon = fakeDaemon(() => ({ ok: true }))- const deps = { port: 1, machineId: async () => 'machine-a', connect: daemon.connect, env: {} as NodeJS.ProcessEnv }+ const deps = { port: 1, socketPath: null, machineId: async () => 'machine-a', connect: daemon.connect, env: {} as NodeJS.ProcessEnv }expect(await pairRequest(deps, { verb: 'list_harnesses' })).toEqual({ ok: true })expect(daemon.sent[0]).toEqual({ type: 'machine_select', payload: { machineId: 'machine-a', localProtocolVersion: 1, tool: true } })expect(daemon.sent[1]).toMatchObject({ type: 'pair', payload: { verb: 'list_harnesses' } })@@ -131,7 +131,7 @@ describe('harness pair <verb>', () => {it('prints the reply, exits 1 on a refusal and 2 on a usage error', async () => {const daemon = fakeDaemon((p) => p.verb === 'stop_turn' ? { ok: false, error: 'TOKEN_REQUIRED' } : { ok: true })const out: string[] = []- const deps = { port: 1, machineId: async () => 'machine-a', connect: daemon.connect, env: {} as NodeJS.ProcessEnv, output: (l: string) => out.push(l), error: (l: string) => out.push(l) }+ const deps = { port: 1, socketPath: null, machineId: async () => 'machine-a', connect: daemon.connect, env: {} as NodeJS.ProcessEnv, output: (l: string) => out.push(l), error: (l: string) => out.push(l) }expect(await pairCommand(['list_machines', '--json'], deps)).toBe(0)expect(out.pop()).toBe('{"ok":true}')expect(await pairCommand(['stop_turn', 'api', '--json'], deps)).toBe(1)diff --git a/companions/src/memory/lessons/borrow.more.spec.ts b/companions/src/memory/lessons/borrow.more.spec.tsindex 7ef668a53..4cf4d7a73 100644--- a/companions/src/memory/lessons/borrow.more.spec.ts+++ b/companions/src/memory/lessons/borrow.more.spec.ts@@ -8,10 +8,8 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest'import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { dirname, join } from 'node:path'-import { mangleClaudeProjectDir } from '../../../../cli/src/lib/claudeProject.js'import {- BORROW_MAX_FILE_BYTES, LessonBorrower, borrowSignal, hermesProvenance, parseFrontmatter, readClaudeMemory, readCodexMemories, readHermesSkills,-} from './borrow.js'+ BORROW_MAX_FILE_BYTES, LessonBorrower, borrowSignal, hermesProvenance, parseFrontmatter, readClaudeMemory, readCodexMemories, readHermesSkills, mangleClaudeProjectDir } from './borrow.js'import { LessonStore } from './store.js'import { projectHash } from './types.js'diff --git a/companions/src/memory/lessons/borrow.spec.ts b/companions/src/memory/lessons/borrow.spec.tsindex 674f06ed1..6132a46f0 100644--- a/companions/src/memory/lessons/borrow.spec.ts+++ b/companions/src/memory/lessons/borrow.spec.ts@@ -6,10 +6,8 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest'import { mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { dirname, join } from 'node:path'-import { mangleClaudeProjectDir } from '../../../../cli/src/lib/claudeProject.js'import {- BORROW_PENDING_MAX, BORROW_PER_PASS, LessonBorrower, borrowSignal, hermesProvenance, parseFrontmatter, readClaudeMemory, readCodexMemories, readHermesSkills,-} from './borrow.js'+ BORROW_PENDING_MAX, BORROW_PER_PASS, LessonBorrower, borrowSignal, hermesProvenance, parseFrontmatter, readClaudeMemory, readCodexMemories, readHermesSkills, mangleClaudeProjectDir } from './borrow.js'import { LessonStore } from './store.js'import { projectHash } from './types.js'diff --git a/companions/src/memory/lessons/borrow.ts b/companions/src/memory/lessons/borrow.tsindex 10741647b..cc4912b49 100644--- a/companions/src/memory/lessons/borrow.ts+++ b/companions/src/memory/lessons/borrow.ts@@ -24,12 +24,14 @@*/import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs'import { basename, join } from 'node:path'-import { mangleClaudeProjectDir } from '../../../../cli/src/lib/claudeProject.js'import { guardLesson, slug, type DistillWhy } from './distill.js'import { untrusted } from '../../shared/guard.js'import type { LessonRecord, LessonStore } from './store.js'import { contentHash, projectHash, projectName, type Signal } from './types.js'+/** Claude Code's folder for a project: the path with every other character a dash (cli engines/claude/discoveryContract.ts). */+export const mangleClaudeProjectDir = (cwd: string): string => cwd.replace(/[^A-Za-z0-9]/g, '-')+export type BorrowEngine = 'hermes' | 'claude' | 'codex'/** A file bigger than this is not a lesson. */diff --git a/desktop/lib/super_tabs/machine_allowance.dart b/desktop/lib/super_tabs/machine_allowance.dartindex ce9ddf9ac..b8613f445 100644--- a/desktop/lib/super_tabs/machine_allowance.dart+++ b/desktop/lib/super_tabs/machine_allowance.dart@@ -10,6 +10,13 @@ const kAllowanceWaiting = 'Waiting for a new reading';/// A host that sends no reason for an unknown allowance predates them (cli superTabs/capacity.ts quotaUnknownReason).const kAllowanceUpdate = 'Update Harness on this machine to see it';+/// An engine this machine has installed but has sent no reading of: the figure comes with its next reading.+const kAllowanceNotRead = 'Not read yet';++/// The same for an offline machine, and the Subscriptions block of an offline machine that sent no reading at all.+const kAllowanceNotReadOffline =+ 'Not read yet. Shows when the machine is back online';+/// Why [quota], one engine's entry in a machine's reading (null when it reported none), shows no figure. [reason] is/// the machine's own words for an unknown allowance (its reading's `quotaReasons`), which name no account or plan.String superMachineAllowanceReason(diff --git a/desktop/lib/super_tabs/machines.dart b/desktop/lib/super_tabs/machines.dartindex cbe360cf6..62aa94ba4 100644--- a/desktop/lib/super_tabs/machines.dart+++ b/desktop/lib/super_tabs/machines.dart@@ -1049,9 +1049,24 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {superTabMap(raw)['engine'] as String: superTabMap(raw),};final configured = (pool?['engines'] as List?)?.whereType<String>();+ // What the machine has installed (its readiness, probed by the CLI), per engine.+ final readiness = observation['readiness'];+ final installed = {+ for (final raw+ in (readiness is Map ? readiness['engines'] : null) as List? ?? [])+ if (raw is Map && raw['installed'] == true) raw['engine'],+ };+ // A list that still names a retired engine (OpenCode) cannot say which of the two it offers: Claude and Codex+ // come from what it reported or has installed.final allowed =configured?.any((engine) => !_chipEngines.contains(engine)) == true- ? quotas.keys.toList()+ ? [+ for (final engine in _chipEngines)+ if (configured!.contains(engine) ||+ quotas.containsKey(engine) ||+ installed.contains(engine))+ engine,+ ]: configured?.where(_chipEngines.contains).toList();var accounts =_usage?.rows@@ -1109,10 +1124,14 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {null => _unfigured(engine,poolId,- superMachineAllowanceReason(- quotas[engine],- reasons is Map ? reasons[engine] : null,- ),+ quotas[engine] == null &&+ !(reasons is Map && reasons[engine] != null) &&+ (stale || installed.contains(engine))+ ? (stale ? kAllowanceNotReadOffline : kAllowanceNotRead)+ : superMachineAllowanceReason(+ quotas[engine],+ reasons is Map ? reasons[engine] : null,+ ),struck: suspended[engine],),},@@ -1960,7 +1979,27 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {/// screen of rows. The list opens over the sidebar, grouped by what each is doing.Widget _agentCount(_MachineView view) {final count = view.agents.length;- final label = count == 1 ? '1 agent' : '$count agents';+ final total = count == 1 ? '1 agent' : '$count agents';+ // What is happening now, not only how many exist. A machine that reads offline runs nothing, whatever its agents+ // last did, unless a session this Desktop holds says one is working (the list below says the same); one the+ // Desktop cannot read says only the total, since nothing is known of what they do.+ final working = view.agents+ .where(+ (agent) => switch (_activity(view, agent)) {+ HarnessActivity.working || HarnessActivity.starting => true,+ _ => false,+ },+ )+ .length;+ final offline =+ view.status == SuperTabMachineStatus.offline && working == 0;+ final label = offline+ ? '$total · none running, machine offline'+ : view.status == SuperTabMachineStatus.live ||+ view.status == SuperTabMachineStatus.late ||+ view.status == SuperTabMachineStatus.offline+ ? '$total · $working working'+ : total;return LayoutBuilder(builder: (context, constraints) {final width = constraints.maxWidth.clamp(240.0, 320.0);@@ -2008,7 +2047,9 @@ class _SuperTabMachinesState extends State<SuperTabMachines> {label,maxLines: 1,overflow: TextOverflow.ellipsis,- style: DesktopChrome.control(),+ style: DesktopChrome.control(+ color: offline ? DesktopChrome.muted : null,+ ),),),Icon(@@ -2819,10 +2860,19 @@ class _MachineReadings extends StatelessWidget {),('Subscriptions',- view.allowances.isEmpty ? null : view.subscriptionsAside,+ view.allowances.isEmpty+ ? (view.status == SuperTabMachineStatus.offline ? 'offline' : null)+ : view.subscriptionsAside,(width) => view.allowances.isEmpty? Text(- 'No Claude or Codex allowance reported for this machine',+ // Only a machine read just now is known to have none; one offline, out of reach or being read again+ // may have an allowance it cannot report at this moment.+ switch (view.status) {+ SuperTabMachineStatus.live || SuperTabMachineStatus.late =>+ 'No Claude or Codex allowance reported for this machine',+ SuperTabMachineStatus.offline => kAllowanceNotReadOffline,+ _ => kAllowanceNotRead,+ },style: DesktopChrome.text(size: 11,height: 1.3,diff --git a/desktop/test/super_tab_machine_subscriptions_test.dart b/desktop/test/super_tab_machine_subscriptions_test.dartindex 4e4b550c4..fc45eba87 100644--- a/desktop/test/super_tab_machine_subscriptions_test.dart+++ b/desktop/test/super_tab_machine_subscriptions_test.dart@@ -33,6 +33,7 @@ Map<String, dynamic> _pool(List<String> engines = const ['claude', 'codex'],List<Map<String, dynamic>> quotas = const [],Map<String, String>? reasons,+ Map<String, bool>? installed,String? host,int age = 0,}) => {@@ -48,6 +49,13 @@ Map<String, dynamic> _pool('receivedAt': DateTime.now().millisecondsSinceEpoch - age,'quotas': quotas,'quotaReasons': ?reasons,+ if (installed != null)+ 'readiness': {+ 'engines': [+ for (final e in installed.entries)+ {'engine': e.key, 'installed': e.value, 'signedIn': e.value},+ ],+ },},'hostMachineId': ?host,'teamWork': {'allowed': true},@@ -270,4 +278,110 @@ void main() {await _unmount(tester, c);},);++ testWidgets(+ 'an offline machine with no Claude or Codex reading says it is not read yet, with offline beside the heading',+ (tester) async {+ final c = await _mount(tester, [+ _pool('m', engines: ['opencode'], age: _offlineAge),+ ]);+ expect(find.textContaining('Subscriptions · offline'), findsOneWidget);+ expect(+ find.text('Not read yet. Shows when the machine is back online'),+ findsOneWidget,+ );+ expect(+ find.text('No Claude or Codex allowance reported for this machine'),+ findsNothing,+ );+ await _unmount(tester, c);+ },+ );++ testWidgets(+ 'a machine whose list still names a retired engine shows its Claude and Codex cards from what is installed',+ (tester) async {+ final c = await _mount(tester, [+ _pool(+ 'm',+ engines: ['opencode'],+ installed: {'claude': true, 'codex': true, 'opencode': true},+ age: _offlineAge,+ ),+ _pool(+ 'half',+ engines: ['opencode'],+ installed: {'claude': true, 'codex': false},+ ),+ _pool(+ 'live',+ engines: ['opencode'],+ installed: {'claude': true, 'codex': true},+ quotas: [_quota('claude', used: 38)],+ ),+ ]);+ expect(_card('m', 'claude'), findsOneWidget);+ expect(_card('m', 'codex'), findsOneWidget);+ const unread = 'Not read yet. Shows when the machine is back online';+ expect(_inCard('m', 'claude', unread), findsOneWidget);+ expect(+ find.text('No Claude or Codex allowance reported for this machine'),+ findsNothing,+ );+ // Only what is installed: Codex is not on this one.+ expect(_card('half', 'claude'), findsOneWidget);+ expect(_card('half', 'codex'), findsNothing);+ // A reading it did send still shows, beside the installed engine that sent none.+ expect(_figure(tester, 'live', 'claude'), '62%');+ expect(_card('live', 'codex'), findsOneWidget);+ await _unmount(tester, c);+ },+ );++ testWidgets(+ 'an offline machine that lists Claude and Codex but sent no reading and no install report says it is not read yet, never to update',+ (tester) async {+ final c = await _mount(tester, [_pool('m', age: _offlineAge)]);+ const unread = 'Not read yet. Shows when the machine is back online';+ expect(_inCard('m', 'claude', unread), findsOneWidget);+ expect(_inCard('m', 'codex', unread), findsOneWidget);+ expect(find.textContaining('Update Harness'), findsNothing);+ await _unmount(tester, c);+ },+ );++ testWidgets(+ 'a machine the Swarm cannot be read for does not claim to have no allowance',+ (tester) async {+ final server = ConversationServer();+ (server.state['people'] as List).add({+ 'id': 'peer',+ 'email': '[email protected]',+ 'role': 'collaborator',+ });+ server.state['machines'] = [+ _pool('m', engines: ['opencode']),+ ];+ final c = server.controller(account: 'owner');+ await c.refresh();+ c.toggleMachineExpanded('m');+ server.failReads = true;+ await c.refresh();+ expect(c.backendUnreachable, isTrue);+ await tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: SuperTabMachines(controller: c, onAddAgent: (_) {}),+ ),+ ),+ );+ await tester.pumpAndSettle();+ expect(+ find.text('No Claude or Codex allowance reported for this machine'),+ findsNothing,+ );+ expect(find.text('Not read yet'), findsOneWidget);+ await _unmount(tester, c);+ },+ );}diff --git a/desktop/test/super_tab_machines_test.dart b/desktop/test/super_tab_machines_test.dartindex 472ef727a..804e370dc 100644--- a/desktop/test/super_tab_machines_test.dart+++ b/desktop/test/super_tab_machines_test.dart@@ -505,6 +505,7 @@ void main() {WidgetTester tester,int agents, {int buddies = 0,+ Duration age = Duration.zero,}) async {final server = ConversationServer();server.state['agents'] = [@@ -530,7 +531,8 @@ void main() {'name': 'Studio Mac','contributorId': 'owner','observation': {- 'receivedAt': DateTime.now().millisecondsSinceEpoch,+ 'receivedAt':+ DateTime.now().millisecondsSinceEpoch - age.inMilliseconds,'resources': {'cpuPercent': 12},},},@@ -575,12 +577,45 @@ void main() {await unmount(tester, c);});+ testWidgets(+ 'an offline machine keeps its total and says nothing is running, in the muted ink',+ (tester) async {+ final c = await mount(tester, 34, age: const Duration(minutes: 10));+ final text = find.descendant(+ of: line,+ matching: find.text('34 agents · none running, machine offline'),+ );+ expect(text, findsOneWidget);+ expect(+ tester.widget<Text>(text).style?.color,+ DesktopChrome.control(color: DesktopChrome.muted).color,+ );+ expect(find.textContaining('working'), findsNothing);+ await unmount(tester, c);+ },+ );++ testWidgets(+ 'one agent on an offline machine reads "1 agent · none running"',+ (tester) async {+ final c = await mount(tester, 1, age: const Duration(minutes: 10));+ expect(+ find.descendant(+ of: line,+ matching: find.text('1 agent · none running, machine offline'),+ ),+ findsOneWidget,+ );+ await unmount(tester, c);+ },+ );+testWidgets('one: "1 agent" with a chevron, no avatar and no agent row', (tester,) async {final c = await mount(tester, 1);expect(- find.descendant(of: line, matching: find.text('1 agent')),+ find.descendant(of: line, matching: find.text('1 agent · 0 working')),findsOneWidget,);expect(@@ -602,7 +637,10 @@ void main() {(tester) async {final c = await mount(tester, 2, buddies: 3);expect(- find.descendant(of: line, matching: find.text('2 agents')),+ find.descendant(+ of: line,+ matching: find.text('2 agents · 0 working'),+ ),findsOneWidget,);await tester.tap(line);@@ -629,7 +667,7 @@ void main() {final c = await mount(tester, 20);expect(line, findsOneWidget);expect(- find.descendant(of: line, matching: find.text('20 agents')),+ find.descendant(of: line, matching: find.text('20 agents · 0 working')),findsOneWidget,);for (var i = 0; i < 20; i++) {@@ -704,7 +742,10 @@ void main() {);await tester.pump();expect(- find.descendant(of: line, matching: find.text('4 agents')),+ find.descendant(+ of: line,+ matching: find.text('4 agents · 2 working'),+ ),findsOneWidget,);expect(find.text('Nova'), findsNothing);diff --git a/desktop/test/super_tab_team_machine_test.dart b/desktop/test/super_tab_team_machine_test.dartindex 5da1eb672..4a02fa924 100644--- a/desktop/test/super_tab_team_machine_test.dart+++ b/desktop/test/super_tab_team_machine_test.dart@@ -131,7 +131,7 @@ void main() {await tester.pumpAndSettle();final count = find.byKey(const ValueKey('super-machine-agents-mac'));expect(- find.descendant(of: count, matching: find.text('2 agents')),+ find.descendant(of: count, matching: find.text('2 agents · 0 working')),findsOneWidget,);await tester.tap(count);@@ -177,7 +177,7 @@ void main() {await tester.pumpAndSettle();final count = find.byKey(const ValueKey('super-machine-agents-mac'));expect(- find.descendant(of: count, matching: find.text('2 agents')),+ find.descendant(of: count, matching: find.text('2 agents · 0 working')),findsOneWidget,);await tester.tap(count);diff --git a/docs/plans/2026-11-02-buddy-private-temp-plan.md b/docs/plans/2026-11-02-buddy-private-temp-plan.mdnew file mode 100644index 000000000..0a19e2e66--- /dev/null+++ b/docs/plans/2026-11-02-buddy-private-temp-plan.md@@ -0,0 +1,43 @@+# A Buddy's private temporary folder Implementation Plan++**Goal:** On a computer with a Team account, a Buddy's temporary files stay in a 0700 folder of its own, not the shared `/tmp`.++**Architecture:** `lib/agentTmp.ts` gains one folder per Buddy, `<data>-buddy-tmp/<hash of its folder>`. The launch sets `TMPDIR` to it, plus `CLAUDE_CODE_TMPDIR` for Claude Code, which otherwise uses `/tmp/claude-<uid>` whatever `TMPDIR` says. The guard and the sandbox are told that one folder; every other Buddy's stays closed.++**Tech stack:** TypeScript, vitest, Claude Code's sandbox settings.++**Spec:** task #2079; audit finding M1 in `docs/plans/2026-11-02-team-private-temp-and-status-plan.md`.++## Decisions++- **Beside the data folder, not in it.** The wide guard and sandbox close the data folder. Opening a hole in that rule would be riskier than a folder they never opened. The new parent is closed the same way, so a Buddy opens only its own child.+- **One folder per Buddy, not one shared.** A shared folder would show one person's private work to another person's Buddy.+- **The guard adds reads only: Read, LS, Grep and Glob.** Write and Edit stay refused, and the shell's word-by-word rules do not change. Real paths decide, so a link out is refused, and secret names stay closed.+- **The sandbox** gets `allowWrite` and `allowRead` for that one folder.+- **Same gate as `agent-tmp`.** Owner's account, not Windows. If the folder cannot be made private, the Buddy starts on the system's folder, the log says so, and the guard opens nothing.++## Design++- **Growth:** the daily sweep deletes a Buddy folder's entries with nothing changed for 7 days, and a folder left empty for 30 days. Ending a Claude Buddy session removes that session's output, and the whole folder once the Buddy's own folder is gone: a plain session shares it with the main Buddy.+- **Concurrency:** no locks. One folder per Buddy; `mkdir` and `chmod` repeat safely. A sweep and a writer race as in `agent-tmp`, and recent files are kept.+- **Read cost:** one walk per day, off the launch path.+- **Scale:** 10x Buddies is 10x small folders. The metric that warns first is the size of `<data>-buddy-tmp`.+- **Compatibility:** only new launches change. A running Buddy keeps its guard and environment until relaunched.+- **Migration and rollback:** none. Removing the code leaves a folder the sweep no longer visits, which is safe to delete.+- **Audience:** file modes enforce it (0700, owner checked); no server is involved.+- **Identity:** the folder belongs to the daemon's account, checked by uid; no login is used.+- **Failure:** a folder that cannot be private logs a line, and the Buddy runs on the system's folder as today.+- **Platforms:** macOS only for now. Linux stays on the system's folder until the real sandbox spec has run with bubblewrap. Windows' temporary folder is already the account's own.++## Limits++- A teammate's Buddy running under the Team account itself is unchanged: this gate is the owner's account.+- M1 stays open for Buddies on Linux. Claude Code before 2.1.77 has no `allowRead`, and a wide Buddy on it would fail closed: its commands break, nothing leaks.+- A tool that names `/tmp` itself ignores `TMPDIR`. A wide Buddy's sandbox refuses that write; a narrow Buddy's guard refuses such commands.++## Tasks++- [ ] **Folder and environment:** failing `agentTmp.spec.ts` tests for 0700 parent and child, per-Buddy paths, engines, gates, links and sweep; then the code.+- [ ] **Guard and sandbox:** failing `buddyGuard.wide.spec.ts` tests for own reads, other Buddies, the data folder, `agent-tmp`, links, secret names and writes; then the code.+- [ ] **Launch and cleanup:** failing `swarmSkills`, `create` and `teamPurge` tests; then the wiring.+- [ ] **Real sandbox:** `buddyGuard.wide.claude.spec.ts` with real Claude Code: own folder writable and readable, another Buddy's refused.diff --git a/docs/plans/2026-11-02-offline-machines-plan.md b/docs/plans/2026-11-02-offline-machines-plan.mdnew file mode 100644index 000000000..af2037092--- /dev/null+++ b/docs/plans/2026-11-02-offline-machines-plan.md@@ -0,0 +1,38 @@+# Desktop Machines: an offline machine never looks busy or without a subscription++**Goal:** Dee's Mac 1, offline, showed "34 agents" and "No Claude or Codex allowance reported for this machine".+Both read as facts about now. The machine is off, so nothing runs there, and its allowance is unknown.++**Scope:** `desktop/lib/super_tabs/machines.dart` (agent count and Subscriptions builders), the two strings in+`machine_allowance.dart`, and their Desktop tests. Row layout is out.++## What changes++1. Agents line keeps the total and says what happens now. Online: `N agents · K working` (K is the Working group of+ the list below, so the two agree). Offline: `N agents · none running, machine offline`, in the muted ink. If a+ session this Desktop holds says an agent is working, the machine is not shown as idle (the list says Working).+ A machine the Desktop cannot read (unknown, refreshing) shows the total only.+2. Subscriptions with no Claude or Codex card: an offline machine says `Not read yet. Shows when the machine is back+ online`, with `offline` beside the heading. `No Claude or Codex allowance reported for this machine` stays for an+ online machine only.+3. A machine whose engine list still names a retired engine (OpenCode) showed an empty block unless it had quotas.+ Its Claude and Codex cards now come from its quotas, its configured Claude/Codex, and what it has installed+ (`observation.readiness.engines[].installed`, already reported by the CLI). An installed engine with no reading says+ `Not read yet` (offline: the longer line), not "Update Harness".++## Tests (written first, each fails on main)++- `super_tab_machines_test.dart`: offline total + muted ink (34 and 1 agent); online `N agents · K working` with+ native sessions.+- `super_tab_machine_subscriptions_test.dart`: offline machine with no reading; retired-engine list with installed+ Claude+Codex (offline), only Claude installed, and a live reading beside an installed engine that sent none.++## Design++- growth, concurrency, read cost, migration: N/A because it only changes what a build derives from the snapshot the+ screen already holds; nothing is stored, synced or read more.+- compatibility: hosts before `readiness` send none, so they behave as before (an empty or quota-listed block).+- audience / identity: N/A because it reads no new field of another person's data; `readiness` is the machine's+ own engine probe, already in the pool every viewer reads.+- failure: an unreadable machine shows the total only, never "none running".+- platforms: Desktop and web share these widgets; the phone has no copy of these strings (searched).diff --git a/docs/plans/2026-11-02-pm-notice-digest-design.md b/docs/plans/2026-11-02-pm-notice-digest-design.mdnew file mode 100644index 000000000..41d6d807e--- /dev/null+++ b/docs/plans/2026-11-02-pm-notice-digest-design.md@@ -0,0 +1,200 @@+# The PM hears routine notices in one message every 5 minutes++Status: design, 2026-11-02. Requested by Ken.++## Why++Every message delivered to a project's coordinator (the PM) starts a new turn for it: an Opus session with a very long+context, interrupted each time. In 20 minutes on 2026-11-02 the openharness PM received 23 messages, and 10 of them were+notices the server writes on its own. Most of those need no answer within minutes: a task quiet for 30 minutes, an agent+idle for 15, an Engineer's Done. Ken: gather the server's own routine notices to the PM and deliver them as one message+at most every 5 minutes; deliver at once what someone is waiting on.++## What Ken decided++- **Scope:** only messages the server itself sends the PM. Posts by agents and people are unchanged.+- **Gathered:** routine notices, delivered as one message.+- **Delivered at once:** anything a person or an agent is waiting on.+- **Interval:** 5 minutes, measured from the first notice gathered, never on a fixed clock. Nothing is sent when nothing+ was gathered. On the 2026-11-02 sample, 11 deliveries in 20 minutes become 5.+- **Where it runs:** on the server, not in the PM's daemon. The daemon's exactly-once delivery (claim, lease, receipt,+ journal) stays one message per delivery. The PM polling on a timer was rejected: it would wake the PM every 5 minutes+ with nothing to read, and it depends on the PM remembering to poll.++## Goals++- Fewer turns for the PM, with nothing lost: every gathered notice is named in the digest by its task and message id.+- A notice anyone waits on still arrives as fast as today.+- Old daemons, old Desktop and phone builds keep working unchanged.++## Non-goals++- Gathering agents' or people's posts.+- Changing what the notices say, or which ones are written.+- Gathering for agents other than a project's coordinator.++## Anti-goals++- A notice silently never delivered: held forever, or dropped by a rollback.+- An urgent notice (Stuck, Needs a human) delayed by the digest.++## Which notices++Gathered (`DIGEST_KINDS`, by the message's `source.kind`, plus Done status rows):++| Source | What |+|---|---|+| `work-stalled`, `work-lost`, `work-resumed` | a task quiet 30 minutes, lost or resumed (liveness.ts) |+| `idle` | an agent with no open task for 15 minutes (tidy.ts) |+| `review-failed`, `review-capacity`, `overlap`, `note-removed` | the coordinator's information notices |+| a `work.status` row with status `done` | an Engineer's (or a step's) Done |++Delivered at once, as today:+- `work.status` rows `needs_human` and `blocked`;+- `pair-loop` (two agents looping);+- `terminal-alert`, `buddy-proposal`;+- `update-request` and `digest-request` (already throttled, and they carry their own instructions);+- `agent-only` notices: decisions answered and instructions changed, written by daemons with no kind of their own;+- every post by an agent or a person.++To tell Done apart, `work.status` system rows gain `source.status` (the status set). Rows written before have none and are+delivered at once.++## How++### Gathering++In `store.ts` `writeMessages`, a delivery whose recipient is its project's coordinator (`ledProject(state, recipient)`)+and whose message is gathered (above) is created with `status: 'gathered'` instead of the default `queued`. The message+itself is written as today, in its conversation, so people and other readers see it at once.++A gathered delivery is never listed to a host: hosts list only open statuses (`OPEN_DELIVERY`: queued, claimed, uncertain),+so old daemons ignore it too. It does not count as work waiting for the agent: `idleNotices`'s `busy` reads open+statuses only.++### Releasing++On the coordinator's own poll (`store.ts` `fullDeliveries`, which already writes the Lead's time checks, idle notices+and update requests in one transaction), the server reads the agent's gathered deliveries, oldest first:+`{ tabId, agentId, status: 'gathered' }` by the existing index `[tabId, agentId, status, createdAt]`, at most 50.++When the oldest is at least `NOTICE_DIGEST_MS` (5 minutes) old:+1. It reads each gathered delivery's message by its id, one `findUnique` each (no `in` filter on a hot collection,+ `hotFilters.test.ts`). It reads the task's number and title from the loaded state.+2. It writes one digest message in the project's Lead conversation:+ - author: the coordinator, as `update-request` is;+ - `source: { kind: 'notice-digest', count }`, recipients `[coordinator]`;+ - `NOTICE_READERS['notice-digest'] = 'recipients'`.+3. It marks those gathered deliveries `status: 'digested'`, a settled status, in the same transaction.++Digest text, one line per notice, oldest first, each line at most 200 characters:++```+Notices since 06:30 UTC (4). Read one in full: harness super-tab message GROUP MESSAGE_ID.+- #1959 "Web app: an account menu…": Done — PR 2515 at 30a9942… (message 1a2b… in 6f3c…)+- #1991 "Review: Buddy copies…" (step Review of #1978): Jasper 2 lost its task: no progress for 30 minutes (message …)+- Tester has had no open task for 15 minutes (message …)+```++More than 50 gathered: the digest names the first 50 and says how many more; the rest go in the next digest.++Word chosen (design call): the status is `gathered`, not `held`. "Held" already means a claimed delivery a host cannot+type yet (`holdReason`, `holdSince`, the host's `hold`, store.ts ~3021 and ~3277).++### Same rules as a delivery++At digest time each gathered row passes the checks a listed delivery passes today: `deliveryAllowed` and `senderAllowed`+(store.ts ~2982-3009, ~3148-3154). A row that fails is set `cancelled`, as a refused delivery is, and is left out of the+digest.++`gathered` joins every place that cancels open deliveries, so no gathered row outlives its reason:+- archive and an agent leaving (store.ts ~1505);+- removed groups (~1513);+- agent removal (~1702);+- task end (~2266, ~3485);+- ~3419;+- native revoke (native.ts ~279).++`digested` joins `FINAL_DELIVERY`, so compaction (deliveryCompaction.ts) and the settle pass treat it as finished.+`deliver()` (the claim, store.ts ~3237) refuses a `gathered` or `digested` row as it refuses a resolved one, so a host+claiming one by id never types it.++### With the update request++When an update request (projectUpdates.ts) is due in the same poll as a digest, the two go as one message: the update+request's text, then "Notices since …" and the lines. The PM gets one turn, not two. A Done is often in both (the update+request asks to read that task's new messages); the digest line stays, as it is what the merge waits on.++### Who counts as coordinator++The project's Lead conversation's `leadId` (`ledProject`). When the lead changes (commands.ts conversation.agent with+`lead`), the old lead's gathered rows go back to `queued` in that command's write: they are delivered to it one by one,+as before this design. It stays in the chat and running (commands.ts ~2421), and they were written for it.++### Stuck gathered deliveries++If the coordinator stops polling (its machine off, the agent stopped), gathered rows must not wait forever. The delivery+settle pass, which runs every 5 minutes (deliverySettle.ts), sets every row `gathered` for more than 30 minutes back to+`queued`. Each is then delivered on its own, as before this design, once a host lists it. The hourly Swarm sweep would+have let one wait about 90 minutes.++## Design++- **Growth:** a gathered row is the delivery row that would have existed anyway. A digest (normally within 5 minutes),+ the 30-minute backstop, or any cancel settles it. `digested` rows are compacted like other finished ones. One digest+ message per release.+- **Concurrency:** holding happens inside the existing message write. Releasing happens inside the coordinator's poll+ transaction, which already writes; the `gathered → digested` update is guarded by `status: 'gathered'`, so two polls racing+ digest each row once. The digest message id is `stableId('notice-digest', agentId, oldest gathered delivery id)`, so a+ retried poll writes it once.+- **Read cost:** one indexed read of at most 50 rows per coordinator poll. When a digest is due, one message read per+ gathered row (at most 50). Nothing for any other agent.+- **Scale (10x):** 10x notices means up to about 100 gathered per 5 minutes, so digests cap at 50 lines and roll over. The+ metric that warns first: the size of digest messages and how often one rolls over (logged).+- **Compatibility:**+ - Old daemons never see `gathered` rows and get the digest as an ordinary message.+ - Clients never classify kinds: the server hides rows (`readsRow`, store.ts ~427). The digest also carries the+ `forRecipients` marker (model.ts ~541), so a backend that knows the marker hides it from people whatever the kind.+ On an older backend without it, an unknown kind reads as people's.+- **Migration and rollback:** no migration. An older backend neither lists, settles nor releases `gathered`. A rollback+ therefore runs `db.SuperTabDelivery.updateMany({status:'gathered'},{$set:{status:'queued'}})` after the last new pod+ and the worker have stopped. Run any earlier and rows written in between are lost. The rollback note goes in the+ release PR.+- **Audience:** the digest is the coordinator's alone (`recipients`). Each line names only messages the coordinator was+ already a recipient of.+- **Identity:** the digest is authored as the coordinator, as the existing update request is; no person's identity is+ used.+- **Failure:**+ - A digest that cannot be written (the transaction fails) leaves the rows gathered; the next poll tries again.+ - A message that cannot be read is named by its id alone.+ - The 30-minute sweep is the backstop.+ - Each digest is logged with its count.+- **Platforms:** server only.++## Tests++- `writeMessages`:+ - a gathered notice to the coordinator is gathered;+ - the same notice to another agent is queued;+ - `needs_human` and `blocked` rows to the coordinator are queued;+ - `pair-loop`, `terminal-alert`, `update-request`, an `agent-only` message and an agent's post are queued;+ - a `done` status row is gathered.+- Coordinator poll:+ - nothing is released before 5 minutes;+ - at 5 minutes, one digest names every gathered notice with its task and message id, and the gathered rows become `digested`;+ - a second poll writes no second digest;+ - 60 gathered rows give a digest of 50 that says 10 more, and the next poll's digest has the rest.+- Gathered deliveries:+ - they are never listed to a host;+ - they do not make an agent busy for `idleNotices`.+- Settle pass: a delivery gathered over 30 minutes becomes `queued`.+- Cancels: archiving the conversation, a task ending, the agent leaving or being removed cancels its gathered rows.+- Checks: a gathered row whose conversation became unreadable is cancelled at digest time and left out.+- Claim: `deliver()` refuses `gathered` and `digested` rows.+- Lead change: the old lead's gathered rows become `queued`.+- An update request and a digest due in the same poll go as one message.++## Left to the builder++- The digest's exact wording within the shape above.+- Where `DIGEST_KINDS` and `NOTICE_DIGEST_MS` live (`notices.ts` or a new `noticeDigest.ts`).diff --git a/docs/plans/2026-11-02-pm-notice-digest-plan.md b/docs/plans/2026-11-02-pm-notice-digest-plan.mdnew file mode 100644index 000000000..1d08b39dd--- /dev/null+++ b/docs/plans/2026-11-02-pm-notice-digest-plan.md@@ -0,0 +1,44 @@+# The PM hears routine notices in one message every 5 minutes: plan++Design: [2026-11-02-pm-notice-digest-design.md](2026-11-02-pm-notice-digest-design.md) (Ken). Backend only; no client changes:+Desktop and the phone show nothing for a delivery status they do not know (`message_receipt.dart`, `swarm_message_receipt.dart`).++## Decisions left to the builder++- `DIGEST_KINDS`, `NOTICE_DIGEST_MS` and the digest's wording live in a new `backend/src/superTabs/noticeDigest.ts`.+- Each line carries full ids, as `harness super-tab message GROUP MESSAGE_ID` needs them. Whitespace in a notice collapses to one+ line, so a worker's result cannot forge a digest line.++## Found while reading the code, beyond the design++These keep to the design's goals ("nothing lost", no notice held forever):++1. **Dormant groups at digest time.** A coordinator's poll loads only awake groups; `deliveryAllowed` refuses a group missing from+ the state, so a gathered row in a group asleep since would be cancelled. A due digest loads its rows' groups first (one `ensure`,+ shared with the morning digest's, since a second `ensure` would drop the first's groups).+2. **Any lead change, not only `conversation.agent`.** Today `conversation.agent` refuses to replace a live PM (`LEAD_PROTECTED`);+ the lead changes on removal, and #2527 will add a switch. The requeue compares each project chat's lead before and after every+ command in `execute` (`requeueFormerLeads`), so every path is covered, and its tests call that step with the two states.+3. **A reply to a gathered notice answers it.** The coordinator may read and answer a notice before its digest; the reply moves the+ row to `answered`, as it does a queued one, and the digest does not name it again.+4. **A merged update request already stored.** `writeMessages` keeps a stored message of the same id and source, which would lose the+ lines, and fails on a different source, which would stop every poll. An update request whose id is already stored is not merged.+5. **Gathered rows carry the store's clock.** `createdAt` is set from `this.now()`, the time the release and the backstop measure from.+6. **A Done outlives its sender (review).** Done is how the coordinator hears, once, and its agent may be stopped within the 5 minutes.+ A sender's removal leaves gathered rows to the digest. A Done whose sender alone fails the checks is named by its label and ids,+ with no result; a routine notice is cancelled. Past the 30 minutes no host could be handed it, so it ends there.+7. **Paused Swarm.** Delivery is not paused by a pause, so a digest still goes out: it stands for deliveries that would have gone.++## Steps (test first)++1. Integration tests in `backend/integration/superTabNoticeDigest.test.ts` for every case the design lists; watch them fail.+2. `noticeDigest.ts`: which messages are gathered, each line, the digest's text and draft. Unit tests in `noticeDigest.test.ts`.+3. `commands.ts`: `source.status` on `work.status` rows. `model.ts`: `NOTICE_READERS['notice-digest']`.+4. `store.ts writeMessages`: `status: 'gathered'`, no announcement.+5. `store.ts fullDeliveries`: release; merge with a due update request.+6. `pageReads.ts`: `CANCELLABLE_DELIVERY`, used by every cancel (store.ts, native.ts). `deliveryCompaction.ts`: `digested` is final.+7. `store.ts deliver`: refuses `gathered` and `digested`.+8. `store.ts execute` (`requeueFormerLeads`): a lead change requeues.+9. `deliverySettle.ts` and `store.ts settleDeliveries`: 30-minute backstop; an unreachable gathered row is cancelled.+10. Update existing tests that expected a routine notice to reach the coordinator's inbox at once.+11. Full Super Tab integration suite (`npm run test:super-tabs`), red/green evidence on the PR, rollback note in the PR.diff --git a/docs/plans/2026-11-02-store-clients-daemon-socket-plan.md b/docs/plans/2026-11-02-store-clients-daemon-socket-plan.mdnew file mode 100644index 000000000..9f0b2b162--- /dev/null+++ b/docs/plans/2026-11-02-store-clients-daemon-socket-plan.md@@ -0,0 +1,55 @@+# Store agents and companions reach the daemon over its socket: plan++> Written by the writing-plans skill's rules. Task #2076, the second follow-up of audit H1 (#2550, task #2016).++**Goal:** no Store agent, Store tool or companion sends the daemon's local credential, or anything else, to whoever holds its+loopback port on macOS or Linux.++**Architecture:** one small file, `localDaemon.mjs`, copied into each Store package (a package stands alone and has no+dependencies) and pinned identical by a test. It finds the daemon's socket, checks it is private, and gives the package a+WebSocket and a `fetch` over it. Node's own WebSocket cannot dial a Unix socket, so the file has a minimal client. With the socket+gone the daemon is down, and the client says so. Nothing falls back to the port.++**Tech:** Node 22 built-ins only in Store packages; `ws` (already a dependency) in companions and the Store tools that use it.++## What moves++| Client | Today | After |+| --- | --- | --- |+| `autonomous-grid`, `harness-monitor`, `memories` | WebSocket on 18473 with the credential | Socket, no credential |+| `machine-monitor` | The same, plus REST on 18473 with the credential | Socket for both |+| `store/tools` (`dsh-*`, experience tests) | WebSocket on 18473 with the credential | Socket |+| `companions` `pairRequest` | WebSocket on the port with the credential | Socket when its caller names one |+| `tui` | Already socket only | Unchanged |++## Design++- Growth: N/A because nothing is stored.+- Concurrency: N/A because each client still holds its own connection; no shared state is added.+- Read cost: N/A because each message is the frame it was. A `stat` of the folder and socket per connection.+- Scale: 10x clients are 10x connections on a socket the daemon already serves. First warning: the daemon's connection count.+- Compatibility: old packages keep working on TCP from this account, and keep their own "credential refused" text. A new package+ on an older daemon uses the socket every released daemon on macOS and Linux has. The socket missing reads as the daemon being down.+- Migration + rollback: no data. Reverting returns the packages to TCP. The catalog ships packages apart from the CLI.+- Audience: the filesystem enforces it: a socket of this account's, owner only, in a folder only this account can write.+- Identity: the socket's owner is the OS account; no login is read.+- Failure: daemon down, a socket that is not private and a dropped connection each reach the package's existing sentence.+- Platforms: macOS and Linux. Windows, and a data folder too long for a socket, stay on TCP with the credential, as #2550 leaves them.++## Tasks++1. **Red test.** `store/tools/port-holder.test.mjs`: a listener on the port with a real credential in the data folder, each client+ run against it, the holder hears nothing, and each client works over a fake daemon on the socket. Fails on main.+2. **`localDaemon.mjs`.** Route, privacy check, WebSocket, fetch. Its own spec: frames split across chunks, ping, close, oversized.+3. **Move the four packages.** `localCredentialHeaders` gives nothing where a socket can exist, as the CLI's does.+4. **Move the tools and companions.**+5. **Real check.** A read-only `agents_list` against this Mac's own daemon through a package, from a scratch copy.++## Left open++- Rotating the old bridge key and moving cloud agents' bridge calls off the port belong to this task too (Lead, 11-02), and build on+ #2558 once it merges: a second pull request with its own plan.++- Windows clients still send the credential to the port; moving them needs a proof-checked pipe client: its own task.+- Packages already installed keep sending the credential until the catalog updates them; a daemon with #2550 refuses it from another account.+- The samples in `samples/hackathon-fo` are out of this task's scope.diff --git a/store/agents/autonomous-grid/lib/harness.mjs b/store/agents/autonomous-grid/lib/harness.mjsindex 301ae5b82..202b6877e 100644--- a/store/agents/autonomous-grid/lib/harness.mjs+++ b/store/agents/autonomous-grid/lib/harness.mjs@@ -4,6 +4,7 @@ import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fsimport { homedir } from 'node:os';import { join } from 'node:path';import { promisify } from 'node:util';+import { DaemonWebSocket, daemonSocketPath } from './localDaemon.mjs';const updateMessage = 'This machine needs a Harness version with Grid fleet support. Update Harness there, or configure an existing SSH target.';@@ -15,7 +16,7 @@ export async function discoverMachines() {}));}-/** Node's WebSocket talks only to Harness's loopback bridge; Harness owns pairing and encryption. */+/** Only Harness's own bridge, over its private socket (localDaemon.mjs); Harness owns pairing and encryption. */export function bridgeUrl(env = process.env) {const url = new URL(env.HARNESS_GRID_BRIDGE_URL || 'ws://127.0.0.1:18473/api/local-ws');if (url.protocol !== 'ws:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)@@ -35,6 +36,8 @@ export function bridgeUrl(env = process.env) {* The same function, by the same name, is in every Store package that talks to the daemon.*/export function localCredentialHeaders(env = process.env) {+ // Where a socket can be, nothing carries the credential: a holder of the TCP port would hear it (localDaemon.mjs).+ if (daemonSocketPath(65_535, env)) return {};const dir = env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data');const uid = typeof process.getuid === 'function' ? process.getuid() : null;// Windows reports every file as 0o666 and every folder as 0o777, so the mode checks below would always refuse@@ -63,7 +66,9 @@ export const CREDENTIAL_REFUSED = "Harness refused this process's local credenti/** Whether the daemon behind a bridge socket that would not open refused the credential: a WebSocket* cannot report the 401, so the same headers are shown once over plain HTTP, which can. */-export async function credentialRefused(url, headers) {+export async function credentialRefused(url, headers, env = process.env) {+ // Over the socket no credential is shown, and the port may be anyone's: there is nothing to ask it.+ if (daemonSocketPath(65_535, env)) return false;try {const answer = await fetch(url.replace(/^ws:/, 'http:'), { headers, signal: AbortSignal.timeout(2000) });await answer.body?.cancel();@@ -73,10 +78,10 @@ export async function credentialRefused(url, headers) {}}-export async function harnessExecute(machine, args, { timeoutMs = 15_000, inherit = false, signal, thinking, env = process.env, WebSocketImpl = globalThis.WebSocket } = {}) {+export async function harnessExecute(machine, args, { timeoutMs = 15_000, inherit = false, signal, thinking, env = process.env, WebSocketImpl = DaemonWebSocket } = {}) {if (!WebSocketImpl) return { ok: false, code: 127, stdout: '', stderr: '', error: 'Node 22 or newer is required for Harness machine connections.' };let socket, url, headers;- try { url = bridgeUrl(env); headers = localCredentialHeaders(env); socket = new WebSocketImpl(url, { headers }); }+ try { url = bridgeUrl(env); headers = localCredentialHeaders(env); socket = new WebSocketImpl(url, { headers, env }); }catch { return { ok: false, code: 127, stdout: '', stderr: '', error: 'Could not open the local Harness bridge.' }; }return await new Promise(resolve => {let done = false, running = false, selected = false, heartbeat, deadline;@@ -100,7 +105,7 @@ export async function harnessExecute(machine, args, { timeoutMs = 15_000, inherisocket.addEventListener('error', () => {const message = 'Harness connection failed. Start Harness and check the machine link.';if (opened) { fail(message); return; }- refusal = credentialRefused(url, headers).then(refused => fail(refused ? CREDENTIAL_REFUSED : message));+ refusal = credentialRefused(url, headers, env).then(refused => fail(refused ? CREDENTIAL_REFUSED : message));});socket.addEventListener('close', event => {if (done || refusal) return; // a refusal answers once it knows whether the credential was refuseddiff --git a/store/agents/autonomous-grid/lib/localDaemon.mjs b/store/agents/autonomous-grid/lib/localDaemon.mjsnew file mode 100644index 000000000..dc4cdf86d--- /dev/null+++ b/store/agents/autonomous-grid/lib/localDaemon.mjs@@ -0,0 +1,201 @@+/**+ * How a Store package reaches the Harness daemon on this computer: its Unix socket, owner only, and on macOS and Linux only that. Any+ * account can bind the daemon's TCP port while the daemon restarts, and would hear whatever is sent to it (audit H1). With the socket+ * gone the daemon is down, and the caller says so. TCP remains where a socket cannot be: Windows, or a data folder too long for one.+ *+ * One file, the same in every package that talks to the daemon, and in store/tools: a package stands alone and has no dependencies+ * (store/tools/port-holder.test.mjs pins the copies). The rules are the CLI's: cli/src/lib/localSocket.ts.+ */+import { createHash, randomBytes } from 'node:crypto'+import { lstatSync } from 'node:fs'+import { request } from 'node:http'+import { homedir } from 'node:os'+import { join } from 'node:path'++/** sockaddr_un has 104 bytes on macOS, and the daemon creates the socket under a name 4 bytes longer. */+const MAX_SOCKET_PATH_BYTES = 96+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'+/** Far above any answer a package reads: it only stops a runaway peer. */+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024+const CLOSE_WAIT_MS = 2000++export function daemonDataDir(env = process.env) {+ return env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')+}++/** The daemon's socket for `port`, or null where it can have none: Windows, or a path too long. */+export function daemonSocketPath(port, env = process.env, platform = process.platform) {+ if (platform === 'win32') return null+ const path = join(daemonDataDir(env), `daemon-${port}.sock`)+ return Buffer.byteLength(path) <= MAX_SOCKET_PATH_BYTES ? path : null+}++/** Whether `path` is the daemon's: a socket of this account's, owner only, in a real folder nobody else can write to. */+export function socketIsPrivate(path) {+ const uid = process.getuid?.()+ try {+ const folder = lstatSync(join(path, '..')), file = lstatSync(path)+ return folder.isDirectory() && (folder.mode & 0o022) === 0 && file.isSocket() && (file.mode & 0o077) === 0+ && (uid === undefined || (folder.uid === uid && file.uid === uid))+ } catch {+ return false+ }+}++const portOf = (url) => Number(url.port) || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80)++/** One client frame: clients mask (RFC 6455 5.3). */+function frame(opcode, payload) {+ const size = payload.length+ const head = size < 126 ? Buffer.from([0x80 | opcode, 0x80 | size])+ : size < 65_536 ? Buffer.from([0x80 | opcode, 0x80 | 126, size >> 8, size & 255])+ : Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(size)); return b })()])+ const mask = randomBytes(4), masked = Buffer.from(payload)+ for (let i = 0; i < masked.length; i++) masked[i] ^= mask[i % 4]+ return Buffer.concat([head, mask, masked])+}++class SocketEvent extends Event {+ constructor(type, fields) { super(type); Object.assign(this, fields) }+}++/** The WebSocket client these packages use, over the daemon's socket: open, message (text), error, close, send, close. */+class UnixWebSocket extends EventTarget {+ static CONNECTING = 0; static OPEN = 1; static CLOSING = 2; static CLOSED = 3+ readyState = 0+ #asked = null; #stream = null; #closed = false; #held = Buffer.alloc(0); #parts = []; #size = 0; #timer = null++ constructor(path, resource) {+ super()+ // Told after this returns, as a WebSocket always is: the caller adds its listeners first.+ if (!socketIsPrivate(path)) { queueMicrotask(() => this.#end(1006, new Error('The Harness socket is missing or not private.'))); return }+ const key = randomBytes(16).toString('base64')+ const asked = this.#asked = request({ socketPath: path, path: resource, headers: { Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Version': '13', 'Sec-WebSocket-Key': key } })+ asked.on('error', (error) => this.#end(1006, error))+ asked.on('response', (answer) => { answer.resume(); this.#end(1006, new Error(`The daemon answered ${answer.statusCode}.`)) })+ asked.on('upgrade', (answer, stream, head) => {+ // Given up on while it was on its way: the caller has been told, so it never comes back to life.+ if (this.#closed) { stream.destroy(); return }+ const accept = createHash('sha1').update(key + WS_GUID).digest('base64')+ if (answer.headers['sec-websocket-accept'] !== accept) { stream.destroy(); this.#end(1006, new Error('The daemon answered no WebSocket.')); return }+ this.#stream = stream+ this.readyState = 1+ stream.on('data', (chunk) => this.#read(chunk))+ stream.on('error', (error) => this.#end(1006, error))+ stream.on('close', () => this.#end(1006))+ this.dispatchEvent(new SocketEvent('open'))+ if (head.length) this.#read(head)+ })+ asked.end()+ }++ send(text) {+ if (this.readyState !== 1) throw new Error('The Harness connection is not open.')+ this.#stream.write(frame(1, Buffer.from(String(text))))+ }++ close(code = 1000) {+ if (this.readyState !== 1) { if (this.readyState === 0) this.#end(1006); return }+ this.readyState = 2+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ // A peer that never answers must not hold this process.+ this.#timer = setTimeout(() => this.#stream.destroy(), CLOSE_WAIT_MS)+ this.#timer.unref?.()+ }++ #end(code, error) {+ if (this.#closed) return+ this.#closed = true+ this.readyState = 3+ clearTimeout(this.#timer)+ // A request still waiting holds the process and could open after the caller was told it failed.+ this.#asked?.destroy()+ this.#stream?.destroy()+ if (error) this.dispatchEvent(new SocketEvent('error', { error, message: error.message }))+ this.dispatchEvent(new SocketEvent('close', { code, reason: '', wasClean: code !== 1006 }))+ }++ #read(chunk) {+ this.#held = this.#held.length ? Buffer.concat([this.#held, chunk]) : chunk+ while (!this.#closed) {+ const taken = this.#next()+ if (taken === 0) return+ this.#held = this.#held.subarray(taken)+ }+ }++ /** One whole server frame off the held bytes; how many bytes it took, or 0 until more come. */+ #next() {+ const held = this.#held+ if (held.length < 2) return 0+ const fin = (held[0] & 0x80) !== 0, opcode = held[0] & 0x0f, short = held[1] & 0x7f+ // A server never masks, and these packages negotiate no extension (RFC 6455 5.1, 5.2).+ if ((held[1] & 0x80) !== 0 || (held[0] & 0x70) !== 0) { this.#fail(1002); return 0 }+ const start = short === 126 ? 4 : short === 127 ? 10 : 2+ if (held.length < start) return 0+ const big = short === 127 ? held.readBigUInt64BE(2) : BigInt(short === 126 ? held.readUInt16BE(2) : short)+ if (big > BigInt(MAX_MESSAGE_BYTES)) { this.#fail(1009); return 0 }+ const size = Number(big)+ if (held.length < start + size) return 0+ const payload = held.subarray(start, start + size)+ if (opcode === 9) this.#stream.write(frame(10, payload))+ else if (opcode === 8) {+ const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005+ if (this.readyState === 1) { this.readyState = 2; this.#stream.write(frame(8, payload.subarray(0, 2))) }+ this.#end(code)+ } else if (opcode === 0 || opcode === 1 || opcode === 2) {+ this.#size += size+ if (this.#size > MAX_MESSAGE_BYTES) { this.#fail(1009); return 0 }+ this.#parts.push(Buffer.from(payload))+ if (fin) {+ const data = Buffer.concat(this.#parts)+ this.#parts = []; this.#size = 0+ this.dispatchEvent(new SocketEvent('message', { data: data.toString('utf8') }))+ }+ }+ return start + size+ }++ #fail(code) {+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ this.#end(code)+ }+}++/**+ * What a package opens to the daemon's `/api/local-ws`: `new DaemonWebSocket(url, { headers, env })`, over the socket where one can be.+ * Elsewhere Node's own WebSocket on `url`, with the headers given.+ */+export class DaemonWebSocket {+ constructor(url, { headers = {}, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ return path ? new UnixWebSocket(path, parsed.pathname) : new globalThis.WebSocket(url, { headers })+ }+}++/** `fetch` for the daemon's REST API at `url`, over its socket where one can be. Answers `status`, `ok`, `json()` and `text()`. */+export function daemonFetch(url, { method = 'GET', headers = {}, body, signal, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ if (!path) return fetch(url, { method, headers, ...(body === undefined ? {} : { body }), ...(signal ? { signal } : {}) })+ return new Promise((resolve, reject) => {+ if (!socketIsPrivate(path)) { reject(new Error('The Harness socket is missing or not private.')); return }+ const payload = body === undefined ? null : Buffer.from(body)+ const asked = request({ socketPath: path, method, path: `${parsed.pathname}${parsed.search}`, ...(signal ? { signal } : {}),+ headers: { ...headers, ...(payload ? { 'content-length': String(payload.length) } : {}) } }, (answer) => {+ const parts = []+ answer.on('data', (part) => parts.push(part))+ answer.on('error', reject)+ answer.on('end', () => {+ const text = Buffer.concat(parts).toString('utf8'), status = answer.statusCode ?? 502+ resolve({ status, ok: status >= 200 && status < 300, text: async () => text, json: async () => JSON.parse(text) })+ })+ })+ // As fetch rejects: the signal's own reason, so a caller can tell a timeout from a daemon that is down.+ asked.on('error', (error) => reject(signal?.aborted ? signal.reason : error))+ asked.end(payload ?? undefined)+ })+}diff --git a/store/agents/autonomous-grid/lib/wake.mjs b/store/agents/autonomous-grid/lib/wake.mjsindex fb1e80af6..52f661ffa 100644--- a/store/agents/autonomous-grid/lib/wake.mjs+++ b/store/agents/autonomous-grid/lib/wake.mjs@@ -1,5 +1,6 @@import { randomUUID } from 'node:crypto';import { bridgeUrl, CREDENTIAL_REFUSED, credentialRefused, discoverMachines, localCredentialHeaders } from './harness.mjs';+import { DaemonWebSocket } from './localDaemon.mjs';/*** The viewer's "Wake now": the one thing in this package that may start a sleeping grid, and only on a@@ -63,14 +64,14 @@ function ending(section) {* message is what the page says. Never throws.*/export async function daemonWake({ controller, grid, signal, discover = discoverMachines, env = process.env,- WebSocketImpl = globalThis.WebSocket, pollMs = WAKE_POLL_MS, giveUpMs = WAKE_GIVE_UP_MS }) {+ WebSocketImpl = DaemonWebSocket, pollMs = WAKE_POLL_MS, giveUpMs = WAKE_GIVE_UP_MS }) {const failed = message => ({ state: 'failed', message });let machineId;try { machineId = await controllerMachineId(controller, discover); } catch { return failed(UNREACHABLE); }if (!machineId) return failed(controller?.transport === 'local' ? UNREACHABLE : WAKE_FAILED);if (!WebSocketImpl || signal?.aborted) return failed(UNREACHABLE);let socket, url, headers;- try { url = bridgeUrl(env); headers = localCredentialHeaders(env); socket = new WebSocketImpl(url, { headers }); } catch { return failed(UNREACHABLE); }+ try { url = bridgeUrl(env); headers = localCredentialHeaders(env); socket = new WebSocketImpl(url, { headers, env }); } catch { return failed(UNREACHABLE); }return await new Promise(resolve => {// The section that answered `waking`: who every later sentence is about.let done = false, waking = null, requestId = null, next;@@ -96,7 +97,7 @@ export async function daemonWake({ controller, grid, signal, discover = discoversocket.addEventListener('open', () => { opened = true; socket.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1, relayIsolation: true } })); });socket.addEventListener('error', () => {if (opened) { lost(); return; }- refusal = credentialRefused(url, headers).then(refused => (refused ? settle(failed(CREDENTIAL_REFUSED)) : lost()));+ refusal = credentialRefused(url, headers, env).then(refused => (refused ? settle(failed(CREDENTIAL_REFUSED)) : lost()));});socket.addEventListener('close', () => { if (!refusal) lost(); });socket.addEventListener('message', event => {diff --git a/store/agents/autonomous-grid/test/credential.test.mjs b/store/agents/autonomous-grid/test/credential.test.mjsindex 3aed2d2a2..6e76fed94 100644--- a/store/agents/autonomous-grid/test/credential.test.mjs+++ b/store/agents/autonomous-grid/test/credential.test.mjs@@ -11,9 +11,9 @@ import { fakeBridge } from './fakes.mjs';const CREDENTIAL = `test-local-credential-${'a'.repeat(21)}`; // the CLI's shape: 43 base64url charactersconst machine = { id:'rig', name:'GPU rig', transport:'harness', machineId:'machine-123' };-/** A data folder as the CLI leaves it: 0700, holding a 0600 `hook-credential` (or none). */+/** A data folder as the CLI leaves it, too long to hold a socket: the one case on TCP, with the credential: 0700, holding a 0600 `hook-credential` (or none). */function dataDir({ credential = CREDENTIAL, mode = 0o600, folderMode = 0o700 } = {}) {- const dir = join(mkdtempSync(join(tmpdir(), 'grid-credential-')), 'data');+ const dir = join(mkdtempSync(join(tmpdir(), 'grid-credential-')), 'data-'.padEnd(120, 'x'));mkdirSync(dir, { mode:0o700 });if (credential !== null) { writeFileSync(join(dir, 'hook-credential'), `${credential}\n`, { mode:0o600 }); chmodSync(join(dir, 'hook-credential'), mode); }chmodSync(dir, folderMode);diff --git a/store/agents/autonomous-grid/test/wake.test.mjs b/store/agents/autonomous-grid/test/wake.test.mjsindex 8f62494e1..8958886e9 100644--- a/store/agents/autonomous-grid/test/wake.test.mjs+++ b/store/agents/autonomous-grid/test/wake.test.mjs@@ -64,6 +64,8 @@ async function listen(t, base) {}/** A viewer on a workspace looking at [grid], asleep, a fake `grid` it reads with, and a fake bridge. */+// Too long a path to hold a socket: the fake bridge here is on TCP.+const NO_SOCKET = join(tmpdir(), 'grid-wake-'.padEnd(120, 'x'));async function setup(t, respond, { grid = 'test-grid', verbs = verbsFor(grid, 'asleep'), bridgeUrl, giveUpMs = 5000, intervalMs = 50 } = {}) {const dir = await mkdtemp(join(tmpdir(), 'grid-wake-')), log = join(dir, 'calls.log');const binary = await fakeGrid(dir, 'grid', { verbs }, log);@@ -71,7 +73,7 @@ async function setup(t, respond, { grid = 'test-grid', verbs = verbsFor(grid, 'aawait atomicJson(join(workspace, 'grid-fleet.json'), { ...config, grid, machines:[{ ...config.machines[0], gridBinary:binary }] });const bridge = await fakeBridge(respond);const viewer = createViewer({ workspace, intervalMs, wakeOptions:{- env:{ HARNESS_GRID_BRIDGE_URL:bridgeUrl || bridge.url }, discover:async () => [{ machineId:'another', current:false }, { machineId:MACHINE, current:true }], pollMs:10, giveUpMs,+ env:{ HARNESS_GRID_BRIDGE_URL:bridgeUrl || bridge.url, ADAPTER_DATA_DIR:NO_SOCKET }, discover:async () => [{ machineId:'another', current:false }, { machineId:MACHINE, current:true }], pollMs:10, giveUpMs,} });// One hook, in this order (hooks run first-in-first-out, and a failed one skips the rest): a viewer// left polling keeps the test process alive, and writes into the workspace being removed.@@ -181,7 +183,7 @@ test('a bridge that is not there, or a daemon too old for the wake, is said plai});await t.test('a controller reached over SSH, or a computer Harness cannot name, has no daemon to ask', async t => {const bridge = await fakeBridge(daemon()); t.after(() => bridge.close());- const options = { grid:'test-grid', env:{ HARNESS_GRID_BRIDGE_URL:bridge.url }, pollMs:10, giveUpMs:300 };+ const options = { grid:'test-grid', env:{ HARNESS_GRID_BRIDGE_URL:bridge.url, ADAPTER_DATA_DIR:NO_SOCKET }, pollMs:10, giveUpMs:300 };const ssh = await daemonWake({ ...options, controller:{ id:'rig', name:'Rig', transport:'ssh', host:'rig.example' } });assert.equal(ssh.state, 'failed'); assert.match(ssh.message, /^Couldn't start it from here/);const unnamed = await daemonWake({ ...options, controller:{ id:'local', name:'This machine', transport:'local' }, discover:async () => { throw new Error('harness: not found'); } });diff --git a/store/agents/harness-monitor/lib/bridge.mjs b/store/agents/harness-monitor/lib/bridge.mjsindex b42f95751..2c02a4c58 100644--- a/store/agents/harness-monitor/lib/bridge.mjs+++ b/store/agents/harness-monitor/lib/bridge.mjs@@ -1,7 +1,7 @@/*** The daemon, over the loopback bridge Harness already serves.*- * Node's WebSocket talks only to `ws://127.0.0.1:18473/api/local-ws`; Harness owns pairing, encryption+ * This talks only to the daemon's `/api/local-ws`, over its private socket (localDaemon.mjs); Harness owns pairing, encryption* and every remote machine behind it. The handshake is the one the Grid harness uses — `machine_select`,* wait for `connected`, then typed request/reply frames whose answer is `<type>_result` carrying the* same `requestId`. Nothing here reaches the network. The one credential this file touches is the@@ -18,6 +18,7 @@ import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fsimport { homedir } from 'node:os'import { join } from 'node:path'import { promisify } from 'node:util'+import { DaemonWebSocket, daemonSocketPath } from './localDaemon.mjs'const exec = promisify(execFile)@@ -35,6 +36,8 @@ export const DEFAULT_BRIDGE = 'ws://127.0.0.1:18473/api/local-ws'* The same function, by the same name, is in every Store package that talks to the daemon.*/export function localCredentialHeaders(env = process.env) {+ // Where a socket can be, nothing carries the credential: a holder of the TCP port would hear it (localDaemon.mjs).+ if (daemonSocketPath(65_535, env)) return {}const dir = env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')const uid = typeof process.getuid === 'function' ? process.getuid() : null// Windows reports every file as 0o666 and every folder as 0o777, so the mode checks below would always refuse@@ -63,7 +66,9 @@ const CREDENTIAL_REFUSED = "Harness refused this process's local credential. Run/** Whether the daemon behind a bridge socket that would not open refused the credential: a WebSocket* cannot report the 401, so the same headers are shown once over plain HTTP, which can. */-async function credentialRefused(url, headers) {+async function credentialRefused(url, headers, env = process.env) {+ // Over the socket no credential is shown, and the port may be anyone's: there is nothing to ask it.+ if (daemonSocketPath(65_535, env)) return falsetry {const answer = await fetch(url.replace(/^ws:/, 'http:'), { headers, signal: AbortSignal.timeout(2000) })await answer.body?.cancel()@@ -137,7 +142,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnectconst byMachine = sessionsFor(WebSocketImpl)const url = bridgeUrl(env)const headers = localCredentialHeaders(env)- const socket = new WebSocketImpl(url, { headers })+ const socket = new WebSocketImpl(url, { headers, env })const pending = new Map()let closed = nulllet opened = false@@ -161,7 +166,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnectclearTimeout(deadline)const m = 'Could not open the local Harness bridge. Start Harness and try again.'if (opened) { fail(m); reject(new Error(m)); return }- refusal = credentialRefused(url, headers).then((refused) => { const why = refused ? CREDENTIAL_REFUSED : m; fail(why); reject(new Error(why)) })+ refusal = credentialRefused(url, headers, env).then((refused) => { const why = refused ? CREDENTIAL_REFUSED : m; fail(why); reject(new Error(why)) })})socket.addEventListener('close', (event) => {if (refusal) return // the error above answers, once it knows whether the credential was refused@@ -209,7 +214,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnect}/** The kept session for `machineId`, opening one if there is none. */-async function bridgeSession(machineId, { env = process.env, timeoutMs = 20_000, WebSocketImpl = globalThis.WebSocket, forceReconnect = false } = {}) {+async function bridgeSession(machineId, { env = process.env, timeoutMs = 20_000, WebSocketImpl = DaemonWebSocket, forceReconnect = false } = {}) {if (!WebSocketImpl) throw new Error('Node 22 or newer is required to reach the Harness bridge.')const existing = sessionsFor(WebSocketImpl).get(machineId)const session = existing ?? openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnect })@@ -221,7 +226,7 @@ async function bridgeSession(machineId, { env = process.env, timeoutMs = 20_000,* One socket, one machine, however many calls the caller needs, then closed — for a one-off job* that must not share the kept session (a script, a test). `fn` receives `rpc(type, payload)`.*/-export async function withBridge(machineId, fn, { env = process.env, timeoutMs = 20_000, WebSocketImpl = globalThis.WebSocket } = {}) {+export async function withBridge(machineId, fn, { env = process.env, timeoutMs = 20_000, WebSocketImpl = DaemonWebSocket } = {}) {if (!WebSocketImpl) throw new Error('Node 22 or newer is required to reach the Harness bridge.')// Its own world, never the shared map: a fresh key that nothing else will look up.const own = class extends WebSocketImpl {}diff --git a/store/agents/harness-monitor/lib/localDaemon.mjs b/store/agents/harness-monitor/lib/localDaemon.mjsnew file mode 100644index 000000000..dc4cdf86d--- /dev/null+++ b/store/agents/harness-monitor/lib/localDaemon.mjs@@ -0,0 +1,201 @@+/**+ * How a Store package reaches the Harness daemon on this computer: its Unix socket, owner only, and on macOS and Linux only that. Any+ * account can bind the daemon's TCP port while the daemon restarts, and would hear whatever is sent to it (audit H1). With the socket+ * gone the daemon is down, and the caller says so. TCP remains where a socket cannot be: Windows, or a data folder too long for one.+ *+ * One file, the same in every package that talks to the daemon, and in store/tools: a package stands alone and has no dependencies+ * (store/tools/port-holder.test.mjs pins the copies). The rules are the CLI's: cli/src/lib/localSocket.ts.+ */+import { createHash, randomBytes } from 'node:crypto'+import { lstatSync } from 'node:fs'+import { request } from 'node:http'+import { homedir } from 'node:os'+import { join } from 'node:path'++/** sockaddr_un has 104 bytes on macOS, and the daemon creates the socket under a name 4 bytes longer. */+const MAX_SOCKET_PATH_BYTES = 96+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'+/** Far above any answer a package reads: it only stops a runaway peer. */+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024+const CLOSE_WAIT_MS = 2000++export function daemonDataDir(env = process.env) {+ return env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')+}++/** The daemon's socket for `port`, or null where it can have none: Windows, or a path too long. */+export function daemonSocketPath(port, env = process.env, platform = process.platform) {+ if (platform === 'win32') return null+ const path = join(daemonDataDir(env), `daemon-${port}.sock`)+ return Buffer.byteLength(path) <= MAX_SOCKET_PATH_BYTES ? path : null+}++/** Whether `path` is the daemon's: a socket of this account's, owner only, in a real folder nobody else can write to. */+export function socketIsPrivate(path) {+ const uid = process.getuid?.()+ try {+ const folder = lstatSync(join(path, '..')), file = lstatSync(path)+ return folder.isDirectory() && (folder.mode & 0o022) === 0 && file.isSocket() && (file.mode & 0o077) === 0+ && (uid === undefined || (folder.uid === uid && file.uid === uid))+ } catch {+ return false+ }+}++const portOf = (url) => Number(url.port) || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80)++/** One client frame: clients mask (RFC 6455 5.3). */+function frame(opcode, payload) {+ const size = payload.length+ const head = size < 126 ? Buffer.from([0x80 | opcode, 0x80 | size])+ : size < 65_536 ? Buffer.from([0x80 | opcode, 0x80 | 126, size >> 8, size & 255])+ : Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(size)); return b })()])+ const mask = randomBytes(4), masked = Buffer.from(payload)+ for (let i = 0; i < masked.length; i++) masked[i] ^= mask[i % 4]+ return Buffer.concat([head, mask, masked])+}++class SocketEvent extends Event {+ constructor(type, fields) { super(type); Object.assign(this, fields) }+}++/** The WebSocket client these packages use, over the daemon's socket: open, message (text), error, close, send, close. */+class UnixWebSocket extends EventTarget {+ static CONNECTING = 0; static OPEN = 1; static CLOSING = 2; static CLOSED = 3+ readyState = 0+ #asked = null; #stream = null; #closed = false; #held = Buffer.alloc(0); #parts = []; #size = 0; #timer = null++ constructor(path, resource) {+ super()+ // Told after this returns, as a WebSocket always is: the caller adds its listeners first.+ if (!socketIsPrivate(path)) { queueMicrotask(() => this.#end(1006, new Error('The Harness socket is missing or not private.'))); return }+ const key = randomBytes(16).toString('base64')+ const asked = this.#asked = request({ socketPath: path, path: resource, headers: { Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Version': '13', 'Sec-WebSocket-Key': key } })+ asked.on('error', (error) => this.#end(1006, error))+ asked.on('response', (answer) => { answer.resume(); this.#end(1006, new Error(`The daemon answered ${answer.statusCode}.`)) })+ asked.on('upgrade', (answer, stream, head) => {+ // Given up on while it was on its way: the caller has been told, so it never comes back to life.+ if (this.#closed) { stream.destroy(); return }+ const accept = createHash('sha1').update(key + WS_GUID).digest('base64')+ if (answer.headers['sec-websocket-accept'] !== accept) { stream.destroy(); this.#end(1006, new Error('The daemon answered no WebSocket.')); return }+ this.#stream = stream+ this.readyState = 1+ stream.on('data', (chunk) => this.#read(chunk))+ stream.on('error', (error) => this.#end(1006, error))+ stream.on('close', () => this.#end(1006))+ this.dispatchEvent(new SocketEvent('open'))+ if (head.length) this.#read(head)+ })+ asked.end()+ }++ send(text) {+ if (this.readyState !== 1) throw new Error('The Harness connection is not open.')+ this.#stream.write(frame(1, Buffer.from(String(text))))+ }++ close(code = 1000) {+ if (this.readyState !== 1) { if (this.readyState === 0) this.#end(1006); return }+ this.readyState = 2+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ // A peer that never answers must not hold this process.+ this.#timer = setTimeout(() => this.#stream.destroy(), CLOSE_WAIT_MS)+ this.#timer.unref?.()+ }++ #end(code, error) {+ if (this.#closed) return+ this.#closed = true+ this.readyState = 3+ clearTimeout(this.#timer)+ // A request still waiting holds the process and could open after the caller was told it failed.+ this.#asked?.destroy()+ this.#stream?.destroy()+ if (error) this.dispatchEvent(new SocketEvent('error', { error, message: error.message }))+ this.dispatchEvent(new SocketEvent('close', { code, reason: '', wasClean: code !== 1006 }))+ }++ #read(chunk) {+ this.#held = this.#held.length ? Buffer.concat([this.#held, chunk]) : chunk+ while (!this.#closed) {+ const taken = this.#next()+ if (taken === 0) return+ this.#held = this.#held.subarray(taken)+ }+ }++ /** One whole server frame off the held bytes; how many bytes it took, or 0 until more come. */+ #next() {+ const held = this.#held+ if (held.length < 2) return 0+ const fin = (held[0] & 0x80) !== 0, opcode = held[0] & 0x0f, short = held[1] & 0x7f+ // A server never masks, and these packages negotiate no extension (RFC 6455 5.1, 5.2).+ if ((held[1] & 0x80) !== 0 || (held[0] & 0x70) !== 0) { this.#fail(1002); return 0 }+ const start = short === 126 ? 4 : short === 127 ? 10 : 2+ if (held.length < start) return 0+ const big = short === 127 ? held.readBigUInt64BE(2) : BigInt(short === 126 ? held.readUInt16BE(2) : short)+ if (big > BigInt(MAX_MESSAGE_BYTES)) { this.#fail(1009); return 0 }+ const size = Number(big)+ if (held.length < start + size) return 0+ const payload = held.subarray(start, start + size)+ if (opcode === 9) this.#stream.write(frame(10, payload))+ else if (opcode === 8) {+ const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005+ if (this.readyState === 1) { this.readyState = 2; this.#stream.write(frame(8, payload.subarray(0, 2))) }+ this.#end(code)+ } else if (opcode === 0 || opcode === 1 || opcode === 2) {+ this.#size += size+ if (this.#size > MAX_MESSAGE_BYTES) { this.#fail(1009); return 0 }+ this.#parts.push(Buffer.from(payload))+ if (fin) {+ const data = Buffer.concat(this.#parts)+ this.#parts = []; this.#size = 0+ this.dispatchEvent(new SocketEvent('message', { data: data.toString('utf8') }))+ }+ }+ return start + size+ }++ #fail(code) {+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ this.#end(code)+ }+}++/**+ * What a package opens to the daemon's `/api/local-ws`: `new DaemonWebSocket(url, { headers, env })`, over the socket where one can be.+ * Elsewhere Node's own WebSocket on `url`, with the headers given.+ */+export class DaemonWebSocket {+ constructor(url, { headers = {}, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ return path ? new UnixWebSocket(path, parsed.pathname) : new globalThis.WebSocket(url, { headers })+ }+}++/** `fetch` for the daemon's REST API at `url`, over its socket where one can be. Answers `status`, `ok`, `json()` and `text()`. */+export function daemonFetch(url, { method = 'GET', headers = {}, body, signal, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ if (!path) return fetch(url, { method, headers, ...(body === undefined ? {} : { body }), ...(signal ? { signal } : {}) })+ return new Promise((resolve, reject) => {+ if (!socketIsPrivate(path)) { reject(new Error('The Harness socket is missing or not private.')); return }+ const payload = body === undefined ? null : Buffer.from(body)+ const asked = request({ socketPath: path, method, path: `${parsed.pathname}${parsed.search}`, ...(signal ? { signal } : {}),+ headers: { ...headers, ...(payload ? { 'content-length': String(payload.length) } : {}) } }, (answer) => {+ const parts = []+ answer.on('data', (part) => parts.push(part))+ answer.on('error', reject)+ answer.on('end', () => {+ const text = Buffer.concat(parts).toString('utf8'), status = answer.statusCode ?? 502+ resolve({ status, ok: status >= 200 && status < 300, text: async () => text, json: async () => JSON.parse(text) })+ })+ })+ // As fetch rejects: the signal's own reason, so a caller can tell a timeout from a daemon that is down.+ asked.on('error', (error) => reject(signal?.aborted ? signal.reason : error))+ asked.end(payload ?? undefined)+ })+}diff --git a/store/agents/harness-monitor/test/credential.test.mjs b/store/agents/harness-monitor/test/credential.test.mjsindex e9639973f..bf0330cb4 100644--- a/store/agents/harness-monitor/test/credential.test.mjs+++ b/store/agents/harness-monitor/test/credential.test.mjs@@ -9,9 +9,9 @@ import { closeBridges, listAgents, localCredentialHeaders } from '../lib/bridge.const CREDENTIAL = `test-local-credential-${'a'.repeat(21)}` // the CLI's shape: 43 base64url characters-/** A data folder as the CLI leaves it: 0700, holding a 0600 `hook-credential` (or none). */+/** A data folder as the CLI leaves it, too long to hold a socket: the one case on TCP, with the credential: 0700, holding a 0600 `hook-credential` (or none). */function dataDir({ credential = CREDENTIAL, mode = 0o600, folderMode = 0o700 } = {}) {- const dir = join(mkdtempSync(join(tmpdir(), 'hps-credential-')), 'data')+ const dir = join(mkdtempSync(join(tmpdir(), 'hps-credential-')), 'data-'.padEnd(120, 'x'))mkdirSync(dir, { mode: 0o700 })if (credential !== null) { writeFileSync(join(dir, 'hook-credential'), `${credential}\n`, { mode: 0o600 }); chmodSync(join(dir, 'hook-credential'), mode) }chmodSync(dir, folderMode)diff --git a/store/agents/machine-monitor/lib/daemon.mjs b/store/agents/machine-monitor/lib/daemon.mjsindex d3ca7af1f..415641db9 100644--- a/store/agents/machine-monitor/lib/daemon.mjs+++ b/store/agents/machine-monitor/lib/daemon.mjs@@ -16,6 +16,7 @@ import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fsimport { readFile } from 'node:fs/promises';import { homedir } from 'node:os';import { join } from 'node:path';+import { DaemonWebSocket, daemonFetch, daemonSocketPath } from './localDaemon.mjs';const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);@@ -51,6 +52,8 @@ export function dataDir(env = process.env) {* The same function, by the same name, is in every Store package that talks to the daemon.*/export function localCredentialHeaders(env = process.env) {+ // Where a socket can be, nothing carries the credential: a holder of the TCP port would hear it (localDaemon.mjs).+ if (daemonSocketPath(65_535, env)) return {};const dir = dataDir(env);const uid = typeof process.getuid === 'function' ? process.getuid() : null;// Windows reports every file as 0o666 and every folder as 0o777, so the mode checks below would always refuse@@ -80,7 +83,9 @@ const CREDENTIAL_REFUSED = "Harness refused this process's local credential. Run/** Whether the daemon behind a bridge socket that would not open refused the credential: a WebSocket* cannot report the 401, so the same headers are shown once over plain HTTP, which can. */-async function credentialRefused(url, headers) {+async function credentialRefused(url, headers, env = process.env) {+ // Over the socket no credential is shown, and the port may be anyone's: there is nothing to ask it.+ if (daemonSocketPath(65_535, env)) return false;try {const answer = await fetch(url.replace(/^ws:/, 'http:'), { headers, signal: AbortSignal.timeout(2000) });await answer.body?.cancel();@@ -93,7 +98,8 @@ async function credentialRefused(url, headers) {async function call(method, path, { body, timeoutMs = 15_000, env = process.env } = {}) {let res;try {- res = await fetch(new URL(path, daemonBase(env)), {+ res = await daemonFetch(new URL(path, daemonBase(env)), {+ env,method,headers: { 'x-adapter-local': '1', ...localCredentialHeaders(env), ...(body === undefined ? {} : { 'content-type': 'application/json' }) },...(body === undefined ? {} : { body: JSON.stringify(body) }),@@ -202,7 +208,7 @@ function sessionsFor(WebSocketImpl) {function openSession(machineId, { env, WebSocketImpl, timeoutMs, forceReconnect = false }) {const byMachine = sessionsFor(WebSocketImpl);let socket, url, headers;- try { url = bridgeUrl(env); headers = localCredentialHeaders(env); socket = new WebSocketImpl(url, { headers }); }+ try { url = bridgeUrl(env); headers = localCredentialHeaders(env); socket = new WebSocketImpl(url, { headers, env }); }catch { return Promise.reject({ ok: false, error: DOWN }); }const session = { socket, waiters: new Map(), heartbeat: null };const fail = (answer) => {@@ -226,7 +232,7 @@ function openSession(machineId, { env, WebSocketImpl, timeoutMs, forceReconnect})); });socket.addEventListener('error', () => {if (opened) { settle(reject, { ok: false, error: DOWN }); fail({ ok: false, error: DOWN }); return; }- refusal = credentialRefused(url, headers).then(refused => {+ refusal = credentialRefused(url, headers, env).then(refused => {const answer = { ok: false, error: refused ? CREDENTIAL_REFUSED : DOWN };settle(reject, answer); fail(answer);});@@ -281,7 +287,7 @@ function ask(session, timeoutMs) {});}-export async function listHarnesses(machineId, { timeoutMs = 20_000, env = process.env, WebSocketImpl = globalThis.WebSocket } = {}) {+export async function listHarnesses(machineId, { timeoutMs = 20_000, env = process.env, WebSocketImpl = DaemonWebSocket } = {}) {if (!WebSocketImpl) return { ok: false, error: 'Node 22 or newer is required to read a machine roster.' };const byMachine = sessionsFor(WebSocketImpl);const existing = byMachine.get(machineId);diff --git a/store/agents/machine-monitor/lib/localDaemon.mjs b/store/agents/machine-monitor/lib/localDaemon.mjsnew file mode 100644index 000000000..dc4cdf86d--- /dev/null+++ b/store/agents/machine-monitor/lib/localDaemon.mjs@@ -0,0 +1,201 @@+/**+ * How a Store package reaches the Harness daemon on this computer: its Unix socket, owner only, and on macOS and Linux only that. Any+ * account can bind the daemon's TCP port while the daemon restarts, and would hear whatever is sent to it (audit H1). With the socket+ * gone the daemon is down, and the caller says so. TCP remains where a socket cannot be: Windows, or a data folder too long for one.+ *+ * One file, the same in every package that talks to the daemon, and in store/tools: a package stands alone and has no dependencies+ * (store/tools/port-holder.test.mjs pins the copies). The rules are the CLI's: cli/src/lib/localSocket.ts.+ */+import { createHash, randomBytes } from 'node:crypto'+import { lstatSync } from 'node:fs'+import { request } from 'node:http'+import { homedir } from 'node:os'+import { join } from 'node:path'++/** sockaddr_un has 104 bytes on macOS, and the daemon creates the socket under a name 4 bytes longer. */+const MAX_SOCKET_PATH_BYTES = 96+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'+/** Far above any answer a package reads: it only stops a runaway peer. */+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024+const CLOSE_WAIT_MS = 2000++export function daemonDataDir(env = process.env) {+ return env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')+}++/** The daemon's socket for `port`, or null where it can have none: Windows, or a path too long. */+export function daemonSocketPath(port, env = process.env, platform = process.platform) {+ if (platform === 'win32') return null+ const path = join(daemonDataDir(env), `daemon-${port}.sock`)+ return Buffer.byteLength(path) <= MAX_SOCKET_PATH_BYTES ? path : null+}++/** Whether `path` is the daemon's: a socket of this account's, owner only, in a real folder nobody else can write to. */+export function socketIsPrivate(path) {+ const uid = process.getuid?.()+ try {+ const folder = lstatSync(join(path, '..')), file = lstatSync(path)+ return folder.isDirectory() && (folder.mode & 0o022) === 0 && file.isSocket() && (file.mode & 0o077) === 0+ && (uid === undefined || (folder.uid === uid && file.uid === uid))+ } catch {+ return false+ }+}++const portOf = (url) => Number(url.port) || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80)++/** One client frame: clients mask (RFC 6455 5.3). */+function frame(opcode, payload) {+ const size = payload.length+ const head = size < 126 ? Buffer.from([0x80 | opcode, 0x80 | size])+ : size < 65_536 ? Buffer.from([0x80 | opcode, 0x80 | 126, size >> 8, size & 255])+ : Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(size)); return b })()])+ const mask = randomBytes(4), masked = Buffer.from(payload)+ for (let i = 0; i < masked.length; i++) masked[i] ^= mask[i % 4]+ return Buffer.concat([head, mask, masked])+}++class SocketEvent extends Event {+ constructor(type, fields) { super(type); Object.assign(this, fields) }+}++/** The WebSocket client these packages use, over the daemon's socket: open, message (text), error, close, send, close. */+class UnixWebSocket extends EventTarget {+ static CONNECTING = 0; static OPEN = 1; static CLOSING = 2; static CLOSED = 3+ readyState = 0+ #asked = null; #stream = null; #closed = false; #held = Buffer.alloc(0); #parts = []; #size = 0; #timer = null++ constructor(path, resource) {+ super()+ // Told after this returns, as a WebSocket always is: the caller adds its listeners first.+ if (!socketIsPrivate(path)) { queueMicrotask(() => this.#end(1006, new Error('The Harness socket is missing or not private.'))); return }+ const key = randomBytes(16).toString('base64')+ const asked = this.#asked = request({ socketPath: path, path: resource, headers: { Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Version': '13', 'Sec-WebSocket-Key': key } })+ asked.on('error', (error) => this.#end(1006, error))+ asked.on('response', (answer) => { answer.resume(); this.#end(1006, new Error(`The daemon answered ${answer.statusCode}.`)) })+ asked.on('upgrade', (answer, stream, head) => {+ // Given up on while it was on its way: the caller has been told, so it never comes back to life.+ if (this.#closed) { stream.destroy(); return }+ const accept = createHash('sha1').update(key + WS_GUID).digest('base64')+ if (answer.headers['sec-websocket-accept'] !== accept) { stream.destroy(); this.#end(1006, new Error('The daemon answered no WebSocket.')); return }+ this.#stream = stream+ this.readyState = 1+ stream.on('data', (chunk) => this.#read(chunk))+ stream.on('error', (error) => this.#end(1006, error))+ stream.on('close', () => this.#end(1006))+ this.dispatchEvent(new SocketEvent('open'))+ if (head.length) this.#read(head)+ })+ asked.end()+ }++ send(text) {+ if (this.readyState !== 1) throw new Error('The Harness connection is not open.')+ this.#stream.write(frame(1, Buffer.from(String(text))))+ }++ close(code = 1000) {+ if (this.readyState !== 1) { if (this.readyState === 0) this.#end(1006); return }+ this.readyState = 2+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ // A peer that never answers must not hold this process.+ this.#timer = setTimeout(() => this.#stream.destroy(), CLOSE_WAIT_MS)+ this.#timer.unref?.()+ }++ #end(code, error) {+ if (this.#closed) return+ this.#closed = true+ this.readyState = 3+ clearTimeout(this.#timer)+ // A request still waiting holds the process and could open after the caller was told it failed.+ this.#asked?.destroy()+ this.#stream?.destroy()+ if (error) this.dispatchEvent(new SocketEvent('error', { error, message: error.message }))+ this.dispatchEvent(new SocketEvent('close', { code, reason: '', wasClean: code !== 1006 }))+ }++ #read(chunk) {+ this.#held = this.#held.length ? Buffer.concat([this.#held, chunk]) : chunk+ while (!this.#closed) {+ const taken = this.#next()+ if (taken === 0) return+ this.#held = this.#held.subarray(taken)+ }+ }++ /** One whole server frame off the held bytes; how many bytes it took, or 0 until more come. */+ #next() {+ const held = this.#held+ if (held.length < 2) return 0+ const fin = (held[0] & 0x80) !== 0, opcode = held[0] & 0x0f, short = held[1] & 0x7f+ // A server never masks, and these packages negotiate no extension (RFC 6455 5.1, 5.2).+ if ((held[1] & 0x80) !== 0 || (held[0] & 0x70) !== 0) { this.#fail(1002); return 0 }+ const start = short === 126 ? 4 : short === 127 ? 10 : 2+ if (held.length < start) return 0+ const big = short === 127 ? held.readBigUInt64BE(2) : BigInt(short === 126 ? held.readUInt16BE(2) : short)+ if (big > BigInt(MAX_MESSAGE_BYTES)) { this.#fail(1009); return 0 }+ const size = Number(big)+ if (held.length < start + size) return 0+ const payload = held.subarray(start, start + size)+ if (opcode === 9) this.#stream.write(frame(10, payload))+ else if (opcode === 8) {+ const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005+ if (this.readyState === 1) { this.readyState = 2; this.#stream.write(frame(8, payload.subarray(0, 2))) }+ this.#end(code)+ } else if (opcode === 0 || opcode === 1 || opcode === 2) {+ this.#size += size+ if (this.#size > MAX_MESSAGE_BYTES) { this.#fail(1009); return 0 }+ this.#parts.push(Buffer.from(payload))+ if (fin) {+ const data = Buffer.concat(this.#parts)+ this.#parts = []; this.#size = 0+ this.dispatchEvent(new SocketEvent('message', { data: data.toString('utf8') }))+ }+ }+ return start + size+ }++ #fail(code) {+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ this.#end(code)+ }+}++/**+ * What a package opens to the daemon's `/api/local-ws`: `new DaemonWebSocket(url, { headers, env })`, over the socket where one can be.+ * Elsewhere Node's own WebSocket on `url`, with the headers given.+ */+export class DaemonWebSocket {+ constructor(url, { headers = {}, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ return path ? new UnixWebSocket(path, parsed.pathname) : new globalThis.WebSocket(url, { headers })+ }+}++/** `fetch` for the daemon's REST API at `url`, over its socket where one can be. Answers `status`, `ok`, `json()` and `text()`. */+export function daemonFetch(url, { method = 'GET', headers = {}, body, signal, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ if (!path) return fetch(url, { method, headers, ...(body === undefined ? {} : { body }), ...(signal ? { signal } : {}) })+ return new Promise((resolve, reject) => {+ if (!socketIsPrivate(path)) { reject(new Error('The Harness socket is missing or not private.')); return }+ const payload = body === undefined ? null : Buffer.from(body)+ const asked = request({ socketPath: path, method, path: `${parsed.pathname}${parsed.search}`, ...(signal ? { signal } : {}),+ headers: { ...headers, ...(payload ? { 'content-length': String(payload.length) } : {}) } }, (answer) => {+ const parts = []+ answer.on('data', (part) => parts.push(part))+ answer.on('error', reject)+ answer.on('end', () => {+ const text = Buffer.concat(parts).toString('utf8'), status = answer.statusCode ?? 502+ resolve({ status, ok: status >= 200 && status < 300, text: async () => text, json: async () => JSON.parse(text) })+ })+ })+ // As fetch rejects: the signal's own reason, so a caller can tell a timeout from a daemon that is down.+ asked.on('error', (error) => reject(signal?.aborted ? signal.reason : error))+ asked.end(payload ?? undefined)+ })+}diff --git a/store/agents/machine-monitor/test/credential.test.mjs b/store/agents/machine-monitor/test/credential.test.mjsindex 74b8070d3..1e2079851 100644--- a/store/agents/machine-monitor/test/credential.test.mjs+++ b/store/agents/machine-monitor/test/credential.test.mjs@@ -9,9 +9,9 @@ import { closeSessions, listHarnesses, listMachines, localCredentialHeaders } frconst CREDENTIAL = `test-local-credential-${'a'.repeat(21)}`; // the CLI's shape: 43 base64url characters-/** A data folder as the CLI leaves it: 0700, holding a 0600 `hook-credential` (or none). */+/** A data folder as the CLI leaves it, too long to hold a socket: the one case on TCP, with the credential: 0700, holding a 0600 `hook-credential` (or none). */function dataDir({ credential = CREDENTIAL, mode = 0o600, folderMode = 0o700 } = {}) {- const dir = join(mkdtempSync(join(tmpdir(), 'machine-monitor-credential-')), 'data');+ const dir = join(mkdtempSync(join(tmpdir(), 'machine-monitor-credential-')), 'data-'.padEnd(120, 'x'));mkdirSync(dir, { mode: 0o700 });if (credential !== null) { writeFileSync(join(dir, 'hook-credential'), `${credential}\n`, { mode: 0o600 }); chmodSync(join(dir, 'hook-credential'), mode); }chmodSync(dir, folderMode);diff --git a/store/agents/memories/lib/bridge.mjs b/store/agents/memories/lib/bridge.mjsindex f667ac62e..48fc1cb9f 100644--- a/store/agents/memories/lib/bridge.mjs+++ b/store/agents/memories/lib/bridge.mjs@@ -2,7 +2,7 @@* The daemon, over the loopback bridge Harness already serves (copied from Harness Monitor's lib/bridge.mjs:* a package installs alone, so each carries its own).*- * Node's WebSocket talks only to `ws://127.0.0.1:18473/api/local-ws`; Harness owns pairing, encryption+ * This talks only to the daemon's `/api/local-ws`, over its private socket (localDaemon.mjs); Harness owns pairing, encryption* and every remote machine behind it. The handshake is the one the Grid harness uses — `machine_select`,* wait for `connected`, then typed request/reply frames whose answer is `<type>_result` carrying the* same `requestId`. Nothing here reaches the network. The one credential this file touches is the@@ -19,6 +19,7 @@ import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fsimport { homedir } from 'node:os'import { join } from 'node:path'import { promisify } from 'node:util'+import { DaemonWebSocket, daemonSocketPath } from './localDaemon.mjs'const exec = promisify(execFile)@@ -36,6 +37,8 @@ export const DEFAULT_BRIDGE = 'ws://127.0.0.1:18473/api/local-ws'* The same function, by the same name, is in every Store package that talks to the daemon.*/export function localCredentialHeaders(env = process.env) {+ // Where a socket can be, nothing carries the credential: a holder of the TCP port would hear it (localDaemon.mjs).+ if (daemonSocketPath(65_535, env)) return {}const dir = env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')const uid = typeof process.getuid === 'function' ? process.getuid() : null// Windows reports every file as 0o666 and every folder as 0o777, so the mode checks below would always refuse@@ -64,7 +67,9 @@ const CREDENTIAL_REFUSED = "Harness refused this process's local credential. Run/** Whether the daemon behind a bridge socket that would not open refused the credential: a WebSocket* cannot report the 401, so the same headers are shown once over plain HTTP, which can. */-async function credentialRefused(url, headers) {+async function credentialRefused(url, headers, env = process.env) {+ // Over the socket no credential is shown, and the port may be anyone's: there is nothing to ask it.+ if (daemonSocketPath(65_535, env)) return falsetry {const answer = await fetch(url.replace(/^ws:/, 'http:'), { headers, signal: AbortSignal.timeout(2000) })await answer.body?.cancel()@@ -138,7 +143,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnectconst byMachine = sessionsFor(WebSocketImpl)const url = bridgeUrl(env)const headers = localCredentialHeaders(env)- const socket = new WebSocketImpl(url, { headers })+ const socket = new WebSocketImpl(url, { headers, env })const pending = new Map()let closed = nulllet opened = false@@ -162,7 +167,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnectclearTimeout(deadline)const m = 'Could not open the local Harness bridge. Start Harness and try again.'if (opened) { fail(m); reject(new Error(m)); return }- refusal = credentialRefused(url, headers).then((refused) => { const why = refused ? CREDENTIAL_REFUSED : m; fail(why); reject(new Error(why)) })+ refusal = credentialRefused(url, headers, env).then((refused) => { const why = refused ? CREDENTIAL_REFUSED : m; fail(why); reject(new Error(why)) })})socket.addEventListener('close', (event) => {if (refusal) return // the error above answers, once it knows whether the credential was refused@@ -210,7 +215,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnect}/** The kept session for `machineId`, opening one if there is none. */-async function bridgeSession(machineId, { env = process.env, timeoutMs = 20_000, WebSocketImpl = globalThis.WebSocket, forceReconnect = false } = {}) {+async function bridgeSession(machineId, { env = process.env, timeoutMs = 20_000, WebSocketImpl = DaemonWebSocket, forceReconnect = false } = {}) {if (!WebSocketImpl) throw new Error('Node 22 or newer is required to reach the Harness bridge.')const existing = sessionsFor(WebSocketImpl).get(machineId)const session = existing ?? openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnect })@@ -222,7 +227,7 @@ async function bridgeSession(machineId, { env = process.env, timeoutMs = 20_000,* One socket, one machine, however many calls the caller needs, then closed — for a one-off job* that must not share the kept session (a script, a test). `fn` receives `rpc(type, payload)`.*/-export async function withBridge(machineId, fn, { env = process.env, timeoutMs = 20_000, WebSocketImpl = globalThis.WebSocket } = {}) {+export async function withBridge(machineId, fn, { env = process.env, timeoutMs = 20_000, WebSocketImpl = DaemonWebSocket } = {}) {if (!WebSocketImpl) throw new Error('Node 22 or newer is required to reach the Harness bridge.')// Its own world, never the shared map: a fresh key that nothing else will look up.const own = class extends WebSocketImpl {}diff --git a/store/agents/memories/lib/localDaemon.mjs b/store/agents/memories/lib/localDaemon.mjsnew file mode 100644index 000000000..dc4cdf86d--- /dev/null+++ b/store/agents/memories/lib/localDaemon.mjs@@ -0,0 +1,201 @@+/**+ * How a Store package reaches the Harness daemon on this computer: its Unix socket, owner only, and on macOS and Linux only that. Any+ * account can bind the daemon's TCP port while the daemon restarts, and would hear whatever is sent to it (audit H1). With the socket+ * gone the daemon is down, and the caller says so. TCP remains where a socket cannot be: Windows, or a data folder too long for one.+ *+ * One file, the same in every package that talks to the daemon, and in store/tools: a package stands alone and has no dependencies+ * (store/tools/port-holder.test.mjs pins the copies). The rules are the CLI's: cli/src/lib/localSocket.ts.+ */+import { createHash, randomBytes } from 'node:crypto'+import { lstatSync } from 'node:fs'+import { request } from 'node:http'+import { homedir } from 'node:os'+import { join } from 'node:path'++/** sockaddr_un has 104 bytes on macOS, and the daemon creates the socket under a name 4 bytes longer. */+const MAX_SOCKET_PATH_BYTES = 96+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'+/** Far above any answer a package reads: it only stops a runaway peer. */+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024+const CLOSE_WAIT_MS = 2000++export function daemonDataDir(env = process.env) {+ return env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')+}++/** The daemon's socket for `port`, or null where it can have none: Windows, or a path too long. */+export function daemonSocketPath(port, env = process.env, platform = process.platform) {+ if (platform === 'win32') return null+ const path = join(daemonDataDir(env), `daemon-${port}.sock`)+ return Buffer.byteLength(path) <= MAX_SOCKET_PATH_BYTES ? path : null+}++/** Whether `path` is the daemon's: a socket of this account's, owner only, in a real folder nobody else can write to. */+export function socketIsPrivate(path) {+ const uid = process.getuid?.()+ try {+ const folder = lstatSync(join(path, '..')), file = lstatSync(path)+ return folder.isDirectory() && (folder.mode & 0o022) === 0 && file.isSocket() && (file.mode & 0o077) === 0+ && (uid === undefined || (folder.uid === uid && file.uid === uid))+ } catch {+ return false+ }+}++const portOf = (url) => Number(url.port) || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80)++/** One client frame: clients mask (RFC 6455 5.3). */+function frame(opcode, payload) {+ const size = payload.length+ const head = size < 126 ? Buffer.from([0x80 | opcode, 0x80 | size])+ : size < 65_536 ? Buffer.from([0x80 | opcode, 0x80 | 126, size >> 8, size & 255])+ : Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(size)); return b })()])+ const mask = randomBytes(4), masked = Buffer.from(payload)+ for (let i = 0; i < masked.length; i++) masked[i] ^= mask[i % 4]+ return Buffer.concat([head, mask, masked])+}++class SocketEvent extends Event {+ constructor(type, fields) { super(type); Object.assign(this, fields) }+}++/** The WebSocket client these packages use, over the daemon's socket: open, message (text), error, close, send, close. */+class UnixWebSocket extends EventTarget {+ static CONNECTING = 0; static OPEN = 1; static CLOSING = 2; static CLOSED = 3+ readyState = 0+ #asked = null; #stream = null; #closed = false; #held = Buffer.alloc(0); #parts = []; #size = 0; #timer = null++ constructor(path, resource) {+ super()+ // Told after this returns, as a WebSocket always is: the caller adds its listeners first.+ if (!socketIsPrivate(path)) { queueMicrotask(() => this.#end(1006, new Error('The Harness socket is missing or not private.'))); return }+ const key = randomBytes(16).toString('base64')+ const asked = this.#asked = request({ socketPath: path, path: resource, headers: { Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Version': '13', 'Sec-WebSocket-Key': key } })+ asked.on('error', (error) => this.#end(1006, error))+ asked.on('response', (answer) => { answer.resume(); this.#end(1006, new Error(`The daemon answered ${answer.statusCode}.`)) })+ asked.on('upgrade', (answer, stream, head) => {+ // Given up on while it was on its way: the caller has been told, so it never comes back to life.+ if (this.#closed) { stream.destroy(); return }+ const accept = createHash('sha1').update(key + WS_GUID).digest('base64')+ if (answer.headers['sec-websocket-accept'] !== accept) { stream.destroy(); this.#end(1006, new Error('The daemon answered no WebSocket.')); return }+ this.#stream = stream+ this.readyState = 1+ stream.on('data', (chunk) => this.#read(chunk))+ stream.on('error', (error) => this.#end(1006, error))+ stream.on('close', () => this.#end(1006))+ this.dispatchEvent(new SocketEvent('open'))+ if (head.length) this.#read(head)+ })+ asked.end()+ }++ send(text) {+ if (this.readyState !== 1) throw new Error('The Harness connection is not open.')+ this.#stream.write(frame(1, Buffer.from(String(text))))+ }++ close(code = 1000) {+ if (this.readyState !== 1) { if (this.readyState === 0) this.#end(1006); return }+ this.readyState = 2+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ // A peer that never answers must not hold this process.+ this.#timer = setTimeout(() => this.#stream.destroy(), CLOSE_WAIT_MS)+ this.#timer.unref?.()+ }++ #end(code, error) {+ if (this.#closed) return+ this.#closed = true+ this.readyState = 3+ clearTimeout(this.#timer)+ // A request still waiting holds the process and could open after the caller was told it failed.+ this.#asked?.destroy()+ this.#stream?.destroy()+ if (error) this.dispatchEvent(new SocketEvent('error', { error, message: error.message }))+ this.dispatchEvent(new SocketEvent('close', { code, reason: '', wasClean: code !== 1006 }))+ }++ #read(chunk) {+ this.#held = this.#held.length ? Buffer.concat([this.#held, chunk]) : chunk+ while (!this.#closed) {+ const taken = this.#next()+ if (taken === 0) return+ this.#held = this.#held.subarray(taken)+ }+ }++ /** One whole server frame off the held bytes; how many bytes it took, or 0 until more come. */+ #next() {+ const held = this.#held+ if (held.length < 2) return 0+ const fin = (held[0] & 0x80) !== 0, opcode = held[0] & 0x0f, short = held[1] & 0x7f+ // A server never masks, and these packages negotiate no extension (RFC 6455 5.1, 5.2).+ if ((held[1] & 0x80) !== 0 || (held[0] & 0x70) !== 0) { this.#fail(1002); return 0 }+ const start = short === 126 ? 4 : short === 127 ? 10 : 2+ if (held.length < start) return 0+ const big = short === 127 ? held.readBigUInt64BE(2) : BigInt(short === 126 ? held.readUInt16BE(2) : short)+ if (big > BigInt(MAX_MESSAGE_BYTES)) { this.#fail(1009); return 0 }+ const size = Number(big)+ if (held.length < start + size) return 0+ const payload = held.subarray(start, start + size)+ if (opcode === 9) this.#stream.write(frame(10, payload))+ else if (opcode === 8) {+ const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005+ if (this.readyState === 1) { this.readyState = 2; this.#stream.write(frame(8, payload.subarray(0, 2))) }+ this.#end(code)+ } else if (opcode === 0 || opcode === 1 || opcode === 2) {+ this.#size += size+ if (this.#size > MAX_MESSAGE_BYTES) { this.#fail(1009); return 0 }+ this.#parts.push(Buffer.from(payload))+ if (fin) {+ const data = Buffer.concat(this.#parts)+ this.#parts = []; this.#size = 0+ this.dispatchEvent(new SocketEvent('message', { data: data.toString('utf8') }))+ }+ }+ return start + size+ }++ #fail(code) {+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ this.#end(code)+ }+}++/**+ * What a package opens to the daemon's `/api/local-ws`: `new DaemonWebSocket(url, { headers, env })`, over the socket where one can be.+ * Elsewhere Node's own WebSocket on `url`, with the headers given.+ */+export class DaemonWebSocket {+ constructor(url, { headers = {}, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ return path ? new UnixWebSocket(path, parsed.pathname) : new globalThis.WebSocket(url, { headers })+ }+}++/** `fetch` for the daemon's REST API at `url`, over its socket where one can be. Answers `status`, `ok`, `json()` and `text()`. */+export function daemonFetch(url, { method = 'GET', headers = {}, body, signal, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ if (!path) return fetch(url, { method, headers, ...(body === undefined ? {} : { body }), ...(signal ? { signal } : {}) })+ return new Promise((resolve, reject) => {+ if (!socketIsPrivate(path)) { reject(new Error('The Harness socket is missing or not private.')); return }+ const payload = body === undefined ? null : Buffer.from(body)+ const asked = request({ socketPath: path, method, path: `${parsed.pathname}${parsed.search}`, ...(signal ? { signal } : {}),+ headers: { ...headers, ...(payload ? { 'content-length': String(payload.length) } : {}) } }, (answer) => {+ const parts = []+ answer.on('data', (part) => parts.push(part))+ answer.on('error', reject)+ answer.on('end', () => {+ const text = Buffer.concat(parts).toString('utf8'), status = answer.statusCode ?? 502+ resolve({ status, ok: status >= 200 && status < 300, text: async () => text, json: async () => JSON.parse(text) })+ })+ })+ // As fetch rejects: the signal's own reason, so a caller can tell a timeout from a daemon that is down.+ asked.on('error', (error) => reject(signal?.aborted ? signal.reason : error))+ asked.end(payload ?? undefined)+ })+}diff --git a/store/agents/memories/test/credential.test.mjs b/store/agents/memories/test/credential.test.mjsindex 5ca2db884..054e6507c 100644--- a/store/agents/memories/test/credential.test.mjs+++ b/store/agents/memories/test/credential.test.mjs@@ -9,9 +9,9 @@ import { closeBridges, listAgents, localCredentialHeaders } from '../lib/bridge.const CREDENTIAL = `test-local-credential-${'a'.repeat(21)}` // the CLI's shape: 43 base64url characters-/** A data folder as the CLI leaves it: 0700, holding a 0600 `hook-credential` (or none). */+/** A data folder as the CLI leaves it, too long to hold a socket: the one case on TCP, with the credential: 0700, holding a 0600 `hook-credential` (or none). */function dataDir({ credential = CREDENTIAL, mode = 0o600, folderMode = 0o700 } = {}) {- const dir = join(mkdtempSync(join(tmpdir(), 'memories-credential-')), 'data')+ const dir = join(mkdtempSync(join(tmpdir(), 'memories-credential-')), 'data-'.padEnd(120, 'x'))mkdirSync(dir, { mode: 0o700 })if (credential !== null) { writeFileSync(join(dir, 'hook-credential'), `${credential}\n`, { mode: 0o600 }); chmodSync(join(dir, 'hook-credential'), mode) }chmodSync(dir, folderMode)diff --git a/store/tools/README.md b/store/tools/README.mdindex e2220547e..21445f135 100644--- a/store/tools/README.md+++ b/store/tools/README.md@@ -28,9 +28,9 @@ Sources and visual-review notes are in [the asset guide](../../.github/assets/stDaemon-level checks over the same loopback WebSocket the desktop uses (`ws://127.0.0.1:18473/api/local-ws`).They need a running daemon with the harness installed on this machine, and `cli/node_modules` (for `ws`).-Run them as the OS user Harness runs as: since Harness 0.4.21 the loopback API refuses (401) any-request without the daemon's local credential, which they read from `hook-credential` in-`ADAPTER_DATA_DIR` (default `~/.harness/cli/data`) and send as `X-Harness-Local`+Run them as the OS user Harness runs as: they reach the daemon over its 0600 socket in `ADAPTER_DATA_DIR`+(default `~/.harness/cli/data`), `local-daemon.mjs`, and nothing goes to its TCP port, which any account can hold. Only where a+socket cannot be (Windows, or a folder too long for one) do they use the port, with `hook-credential` as `X-Harness-Local`(`local-credential.mjs`).```shdiff --git a/store/tools/dsh-delete.mjs b/store/tools/dsh-delete.mjsindex 6ef80753b..4f841bea0 100644--- a/store/tools/dsh-delete.mjs+++ b/store/tools/dsh-delete.mjs@@ -1,10 +1,11 @@-// Delete an agent over the daemon's loopback WebSocket. Usage: node dsh-delete.mjs <agentId>+// Delete an agent over the daemon's WebSocket. Usage: node dsh-delete.mjs <agentId>import ws_ from '../../cli/node_modules/ws/index.js'const { WebSocket } = ws_-import { CREDENTIAL_REFUSED, localCredentialHeaders } from './local-credential.mjs'+import { CREDENTIAL_REFUSED, daemonBridge } from './local-credential.mjs'const [agentId] = process.argv.slice(2)const machineId = process.argv[3] ?? (() => { console.error('usage: node dsh-delete.mjs <agentId> <machineId>'); process.exit(2) })()-const ws = new WebSocket('ws://127.0.0.1:18473/api/local-ws', { headers: localCredentialHeaders() })+const { url, headers } = daemonBridge()+const ws = new WebSocket(url, { headers })ws.on('unexpected-response', (_req, res) => { console.error(res.statusCode === 401 ? CREDENTIAL_REFUSED : `Unexpected server response: ${res.statusCode}`); process.exit(1) })ws.on('open', () => {ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId, localProtocolVersion: 1 } }))diff --git a/store/tools/dsh-discover.mjs b/store/tools/dsh-discover.mjsindex 728ac6733..f537d3144 100644--- a/store/tools/dsh-discover.mjs+++ b/store/tools/dsh-discover.mjs@@ -2,9 +2,10 @@import ws_ from '../../cli/node_modules/ws/index.js'const { WebSocket } = ws_import { randomBytes } from 'node:crypto'-import { CREDENTIAL_REFUSED, localCredentialHeaders } from './local-credential.mjs'+import { CREDENTIAL_REFUSED, daemonBridge } from './local-credential.mjs'const [machineId, workspace, action] = process.argv.slice(2)-const ws = new WebSocket('ws://127.0.0.1:18473/api/local-ws', { headers: localCredentialHeaders() })+const { url, headers } = daemonBridge()+const ws = new WebSocket(url, { headers })ws.on('unexpected-response', (_req, res) => { console.error(res.statusCode === 401 ? CREDENTIAL_REFUSED : `Unexpected server response: ${res.statusCode}`); process.exit(1) })const pending = new Map()const send = (type, payload) => ws.send(JSON.stringify({ type, payload }))diff --git a/store/tools/dsh-e2e.mjs b/store/tools/dsh-e2e.mjsindex bb6dfa24e..42e30cb9f 100644--- a/store/tools/dsh-e2e.mjs+++ b/store/tools/dsh-e2e.mjs@@ -4,7 +4,7 @@ import ws_ from '../../cli/node_modules/ws/index.js'const { WebSocket } = ws_import { randomBytes } from 'node:crypto'import { execFileSync } from 'node:child_process'-import { CREDENTIAL_REFUSED, localCredentialHeaders } from './local-credential.mjs'+import { CREDENTIAL_REFUSED, daemonBridge } from './local-credential.mjs'const [machineId, dshId, engine, workspace] = process.argv.slice(2)const keep = process.argv.includes('--keep')@@ -13,7 +13,8 @@ if (!machineId || !dshId || !engine || !workspace) {process.exit(2)}-const ws = new WebSocket('ws://127.0.0.1:18473/api/local-ws', { headers: localCredentialHeaders() })+const { url, headers } = daemonBridge()+const ws = new WebSocket(url, { headers })ws.on('unexpected-response', (_req, res) => { log(res.statusCode === 401 ? CREDENTIAL_REFUSED : `ws error Unexpected server response: ${res.statusCode}`); process.exit(1) })const pending = new Map()const agentFrames = []diff --git a/store/tools/experience-tests/daemon.mjs b/store/tools/experience-tests/daemon.mjsindex e49aa66c7..4c04c542c 100644--- a/store/tools/experience-tests/daemon.mjs+++ b/store/tools/experience-tests/daemon.mjs@@ -8,6 +8,7 @@ import { join, resolve } from "node:path";import { fileURLToPath } from "node:url";import { experiences } from "../build-experiences.mjs";import { CREDENTIAL_REFUSED, localCredentialHeaders } from "../local-credential.mjs";+import { DaemonWebSocket, daemonSocketPath } from "../local-daemon.mjs";const machineId = process.env.HARNESS_MACHINE_ID;if (!machineId)@@ -24,7 +25,7 @@ const output = resolve(await mkdir(output, { recursive: true });const bridge = "ws://127.0.0.1:18473/api/local-ws";const headers = localCredentialHeaders();-const socket = new WebSocket(bridge, { headers });+const socket = new DaemonWebSocket(bridge, { headers });const pending = new Map(),frames = [],results = [];@@ -72,8 +73,9 @@ await new Promise((resolve, reject) => {socket.addEventListener("error",() =>- fetch(bridge.replace(/^ws:/, "http:"), { headers })- .then((answer) => answer.status === 401, () => false)+ // Over the socket no credential is shown, and the port may be anyone's: there is nothing to ask it.+ (daemonSocketPath(18473) ? Promise.resolve(false) : fetch(bridge.replace(/^ws:/, "http:"), { headers })+ .then((answer) => answer.status === 401, () => false)).then((refused) =>reject(new Error(refused ? CREDENTIAL_REFUSED : "Could not open the local Harness bridge.")),),diff --git a/store/tools/local-credential.mjs b/store/tools/local-credential.mjsindex 315abf2ed..6f996c3e4 100644--- a/store/tools/local-credential.mjs+++ b/store/tools/local-credential.mjs@@ -8,8 +8,18 @@import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs'import { homedir } from 'node:os'import { join } from 'node:path'+import { daemonSocketPath, socketIsPrivate } from './local-daemon.mjs'++/** Where a check using the `ws` package opens the daemon's bridge, and what it shows: its private socket and nothing, where one can be+ * (a holder of the TCP port would hear anything sent to it, audit H1). */+export function daemonBridge(port = 18473, env = process.env) {+ const socket = daemonSocketPath(port, env)+ if (socket && !socketIsPrivate(socket)) throw new Error(`The Harness socket is missing or not private: ${socket}. Start Harness as this user.`)+ return socket ? { url: `ws+unix://${socket}:/api/local-ws`, headers: {} } : { url: `ws://127.0.0.1:${port}/api/local-ws`, headers: localCredentialHeaders(env) }+}export function localCredentialHeaders(env = process.env) {+ if (daemonSocketPath(65_535, env)) return {}const dir = env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')const uid = typeof process.getuid === 'function' ? process.getuid() : null// Windows reports every file as 0o666 and every folder as 0o777, so the mode checks below would always refusediff --git a/store/tools/local-credential.test.mjs b/store/tools/local-credential.test.mjsindex 394a59903..1bfda29e6 100644--- a/store/tools/local-credential.test.mjs+++ b/store/tools/local-credential.test.mjs@@ -3,14 +3,15 @@ import assert from 'node:assert/strict'import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'+import { createServer } from 'node:net'import { test } from 'node:test'-import { localCredentialHeaders } from './local-credential.mjs'+import { daemonBridge, localCredentialHeaders } from './local-credential.mjs'const CREDENTIAL = `test-local-credential-${'a'.repeat(21)}` // the CLI's shape: 43 base64url characters/** A data folder as the CLI leaves it: 0700, holding a 0600 `hook-credential` (or none). */function dataDir({ credential = CREDENTIAL, mode = 0o600, folderMode = 0o700 } = {}) {- const dir = join(mkdtempSync(join(tmpdir(), 'store-tools-credential-')), 'data')+ const dir = join(mkdtempSync(join(tmpdir(), 'store-tools-credential-')), 'data-'.padEnd(120, 'x'))mkdirSync(dir, { mode: 0o700 })if (credential !== null) { writeFileSync(join(dir, 'hook-credential'), `${credential}\n`, { mode: 0o600 }); chmodSync(join(dir, 'hook-credential'), mode) }chmodSync(dir, folderMode)@@ -35,3 +36,20 @@ test('on Windows the credential is read whatever mode the folder and file reportassert.deepEqual(localCredentialHeaders({ ADAPTER_DATA_DIR: dataDir({ mode: 0o666, folderMode: 0o777 }) }), { 'X-Harness-Local': CREDENTIAL })assert.deepEqual(localCredentialHeaders({ ADAPTER_DATA_DIR: dataDir({ credential: 'too-short', mode: 0o666 }) }), {}, 'the value is still checked')})++test('where a socket can be, a check opens it and shows nothing, and only if it is private', async (t) => {+ const short = mkdtempSync(join('/tmp', 'tools-'))+ writeFileSync(join(short, 'hook-credential'), `${CREDENTIAL}\n`, { mode: 0o600 })+ chmodSync(short, 0o700)+ const env = { ADAPTER_DATA_DIR: short }, path = join(short, 'daemon-18473.sock')+ assert.deepEqual(localCredentialHeaders(env), {})+ assert.throws(() => daemonBridge(18473, env), /missing or not private/, 'no socket: the daemon is down, and the port is not tried')+ const server = createServer()+ await new Promise(ready => server.listen(path, ready))+ t.after(() => server.close())+ chmodSync(path, 0o600)+ assert.deepEqual(daemonBridge(18473, env), { url: `ws+unix://${path}:/api/local-ws`, headers: {} })+ chmodSync(path, 0o666)+ assert.throws(() => daemonBridge(18473, env), /missing or not private/)+ assert.deepEqual(daemonBridge(18473, { ADAPTER_DATA_DIR: dataDir() }).headers, { 'X-Harness-Local': CREDENTIAL })+})diff --git a/store/tools/local-daemon.mjs b/store/tools/local-daemon.mjsnew file mode 100644index 000000000..dc4cdf86d--- /dev/null+++ b/store/tools/local-daemon.mjs@@ -0,0 +1,201 @@+/**+ * How a Store package reaches the Harness daemon on this computer: its Unix socket, owner only, and on macOS and Linux only that. Any+ * account can bind the daemon's TCP port while the daemon restarts, and would hear whatever is sent to it (audit H1). With the socket+ * gone the daemon is down, and the caller says so. TCP remains where a socket cannot be: Windows, or a data folder too long for one.+ *+ * One file, the same in every package that talks to the daemon, and in store/tools: a package stands alone and has no dependencies+ * (store/tools/port-holder.test.mjs pins the copies). The rules are the CLI's: cli/src/lib/localSocket.ts.+ */+import { createHash, randomBytes } from 'node:crypto'+import { lstatSync } from 'node:fs'+import { request } from 'node:http'+import { homedir } from 'node:os'+import { join } from 'node:path'++/** sockaddr_un has 104 bytes on macOS, and the daemon creates the socket under a name 4 bytes longer. */+const MAX_SOCKET_PATH_BYTES = 96+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'+/** Far above any answer a package reads: it only stops a runaway peer. */+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024+const CLOSE_WAIT_MS = 2000++export function daemonDataDir(env = process.env) {+ return env.ADAPTER_DATA_DIR || join(homedir(), '.harness', 'cli', 'data')+}++/** The daemon's socket for `port`, or null where it can have none: Windows, or a path too long. */+export function daemonSocketPath(port, env = process.env, platform = process.platform) {+ if (platform === 'win32') return null+ const path = join(daemonDataDir(env), `daemon-${port}.sock`)+ return Buffer.byteLength(path) <= MAX_SOCKET_PATH_BYTES ? path : null+}++/** Whether `path` is the daemon's: a socket of this account's, owner only, in a real folder nobody else can write to. */+export function socketIsPrivate(path) {+ const uid = process.getuid?.()+ try {+ const folder = lstatSync(join(path, '..')), file = lstatSync(path)+ return folder.isDirectory() && (folder.mode & 0o022) === 0 && file.isSocket() && (file.mode & 0o077) === 0+ && (uid === undefined || (folder.uid === uid && file.uid === uid))+ } catch {+ return false+ }+}++const portOf = (url) => Number(url.port) || (url.protocol === 'https:' || url.protocol === 'wss:' ? 443 : 80)++/** One client frame: clients mask (RFC 6455 5.3). */+function frame(opcode, payload) {+ const size = payload.length+ const head = size < 126 ? Buffer.from([0x80 | opcode, 0x80 | size])+ : size < 65_536 ? Buffer.from([0x80 | opcode, 0x80 | 126, size >> 8, size & 255])+ : Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(size)); return b })()])+ const mask = randomBytes(4), masked = Buffer.from(payload)+ for (let i = 0; i < masked.length; i++) masked[i] ^= mask[i % 4]+ return Buffer.concat([head, mask, masked])+}++class SocketEvent extends Event {+ constructor(type, fields) { super(type); Object.assign(this, fields) }+}++/** The WebSocket client these packages use, over the daemon's socket: open, message (text), error, close, send, close. */+class UnixWebSocket extends EventTarget {+ static CONNECTING = 0; static OPEN = 1; static CLOSING = 2; static CLOSED = 3+ readyState = 0+ #asked = null; #stream = null; #closed = false; #held = Buffer.alloc(0); #parts = []; #size = 0; #timer = null++ constructor(path, resource) {+ super()+ // Told after this returns, as a WebSocket always is: the caller adds its listeners first.+ if (!socketIsPrivate(path)) { queueMicrotask(() => this.#end(1006, new Error('The Harness socket is missing or not private.'))); return }+ const key = randomBytes(16).toString('base64')+ const asked = this.#asked = request({ socketPath: path, path: resource, headers: { Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Version': '13', 'Sec-WebSocket-Key': key } })+ asked.on('error', (error) => this.#end(1006, error))+ asked.on('response', (answer) => { answer.resume(); this.#end(1006, new Error(`The daemon answered ${answer.statusCode}.`)) })+ asked.on('upgrade', (answer, stream, head) => {+ // Given up on while it was on its way: the caller has been told, so it never comes back to life.+ if (this.#closed) { stream.destroy(); return }+ const accept = createHash('sha1').update(key + WS_GUID).digest('base64')+ if (answer.headers['sec-websocket-accept'] !== accept) { stream.destroy(); this.#end(1006, new Error('The daemon answered no WebSocket.')); return }+ this.#stream = stream+ this.readyState = 1+ stream.on('data', (chunk) => this.#read(chunk))+ stream.on('error', (error) => this.#end(1006, error))+ stream.on('close', () => this.#end(1006))+ this.dispatchEvent(new SocketEvent('open'))+ if (head.length) this.#read(head)+ })+ asked.end()+ }++ send(text) {+ if (this.readyState !== 1) throw new Error('The Harness connection is not open.')+ this.#stream.write(frame(1, Buffer.from(String(text))))+ }++ close(code = 1000) {+ if (this.readyState !== 1) { if (this.readyState === 0) this.#end(1006); return }+ this.readyState = 2+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ // A peer that never answers must not hold this process.+ this.#timer = setTimeout(() => this.#stream.destroy(), CLOSE_WAIT_MS)+ this.#timer.unref?.()+ }++ #end(code, error) {+ if (this.#closed) return+ this.#closed = true+ this.readyState = 3+ clearTimeout(this.#timer)+ // A request still waiting holds the process and could open after the caller was told it failed.+ this.#asked?.destroy()+ this.#stream?.destroy()+ if (error) this.dispatchEvent(new SocketEvent('error', { error, message: error.message }))+ this.dispatchEvent(new SocketEvent('close', { code, reason: '', wasClean: code !== 1006 }))+ }++ #read(chunk) {+ this.#held = this.#held.length ? Buffer.concat([this.#held, chunk]) : chunk+ while (!this.#closed) {+ const taken = this.#next()+ if (taken === 0) return+ this.#held = this.#held.subarray(taken)+ }+ }++ /** One whole server frame off the held bytes; how many bytes it took, or 0 until more come. */+ #next() {+ const held = this.#held+ if (held.length < 2) return 0+ const fin = (held[0] & 0x80) !== 0, opcode = held[0] & 0x0f, short = held[1] & 0x7f+ // A server never masks, and these packages negotiate no extension (RFC 6455 5.1, 5.2).+ if ((held[1] & 0x80) !== 0 || (held[0] & 0x70) !== 0) { this.#fail(1002); return 0 }+ const start = short === 126 ? 4 : short === 127 ? 10 : 2+ if (held.length < start) return 0+ const big = short === 127 ? held.readBigUInt64BE(2) : BigInt(short === 126 ? held.readUInt16BE(2) : short)+ if (big > BigInt(MAX_MESSAGE_BYTES)) { this.#fail(1009); return 0 }+ const size = Number(big)+ if (held.length < start + size) return 0+ const payload = held.subarray(start, start + size)+ if (opcode === 9) this.#stream.write(frame(10, payload))+ else if (opcode === 8) {+ const code = payload.length >= 2 ? payload.readUInt16BE(0) : 1005+ if (this.readyState === 1) { this.readyState = 2; this.#stream.write(frame(8, payload.subarray(0, 2))) }+ this.#end(code)+ } else if (opcode === 0 || opcode === 1 || opcode === 2) {+ this.#size += size+ if (this.#size > MAX_MESSAGE_BYTES) { this.#fail(1009); return 0 }+ this.#parts.push(Buffer.from(payload))+ if (fin) {+ const data = Buffer.concat(this.#parts)+ this.#parts = []; this.#size = 0+ this.dispatchEvent(new SocketEvent('message', { data: data.toString('utf8') }))+ }+ }+ return start + size+ }++ #fail(code) {+ const body = Buffer.alloc(2); body.writeUInt16BE(code)+ this.#stream.write(frame(8, body))+ this.#end(code)+ }+}++/**+ * What a package opens to the daemon's `/api/local-ws`: `new DaemonWebSocket(url, { headers, env })`, over the socket where one can be.+ * Elsewhere Node's own WebSocket on `url`, with the headers given.+ */+export class DaemonWebSocket {+ constructor(url, { headers = {}, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ return path ? new UnixWebSocket(path, parsed.pathname) : new globalThis.WebSocket(url, { headers })+ }+}++/** `fetch` for the daemon's REST API at `url`, over its socket where one can be. Answers `status`, `ok`, `json()` and `text()`. */+export function daemonFetch(url, { method = 'GET', headers = {}, body, signal, env = process.env } = {}) {+ const parsed = new URL(url)+ const path = daemonSocketPath(portOf(parsed), env)+ if (!path) return fetch(url, { method, headers, ...(body === undefined ? {} : { body }), ...(signal ? { signal } : {}) })+ return new Promise((resolve, reject) => {+ if (!socketIsPrivate(path)) { reject(new Error('The Harness socket is missing or not private.')); return }+ const payload = body === undefined ? null : Buffer.from(body)+ const asked = request({ socketPath: path, method, path: `${parsed.pathname}${parsed.search}`, ...(signal ? { signal } : {}),+ headers: { ...headers, ...(payload ? { 'content-length': String(payload.length) } : {}) } }, (answer) => {+ const parts = []+ answer.on('data', (part) => parts.push(part))+ answer.on('error', reject)+ answer.on('end', () => {+ const text = Buffer.concat(parts).toString('utf8'), status = answer.statusCode ?? 502+ resolve({ status, ok: status >= 200 && status < 300, text: async () => text, json: async () => JSON.parse(text) })+ })+ })+ // As fetch rejects: the signal's own reason, so a caller can tell a timeout from a daemon that is down.+ asked.on('error', (error) => reject(signal?.aborted ? signal.reason : error))+ asked.end(payload ?? undefined)+ })+}diff --git a/store/tools/local-daemon.test.mjs b/store/tools/local-daemon.test.mjsnew file mode 100644index 000000000..2a85b1649--- /dev/null+++ b/store/tools/local-daemon.test.mjs@@ -0,0 +1,189 @@+// node --test store/tools/local-daemon.test.mjs+// The small WebSocket and fetch every Store package reaches the daemon with, against raw frames on a real Unix socket.+import assert from 'node:assert/strict'+import { createHash } from 'node:crypto'+import { chmodSync, mkdtempSync, writeFileSync } from 'node:fs'+import { createServer } from 'node:http'+import { join } from 'node:path'+import { after, test } from 'node:test'+import { DaemonWebSocket, daemonFetch, daemonSocketPath, socketIsPrivate } from './local-daemon.mjs'++const closers = []+after(async () => { for (const close of closers) await close() })+const PORT = 4242++/** A daemon on a private socket: `upgrade(socket, unmaskedFramesSeen)`, and `rest` for plain requests. */+async function daemon({ upgrade, rest, accept } = {}) {+ const dir = mkdtempSync(join('/tmp', 'ld-'))+ chmodSync(dir, 0o700)+ const sockets = new Set(), seen = []+ const server = createServer(rest ?? ((_req, res) => res.writeHead(404).end()))+ server.on('upgrade', (req, socket) => {+ sockets.add(socket); socket.on('error', () => {})+ const good = createHash('sha1').update(`${req.headers['sec-websocket-key']}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest('base64')+ socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept ?? good}\r\n\r\n`)+ let held = Buffer.alloc(0)+ socket.on('data', chunk => {+ held = Buffer.concat([held, chunk])+ while (held.length >= 6) {+ const short = held[1] & 0x7f, start = short === 126 ? 4 : 2, size = short === 126 ? held.readUInt16BE(2) : short+ assert.ok(held[1] & 0x80, 'a client masks every frame')+ if (held.length < start + 4 + size) break+ const mask = held.subarray(start, start + 4), body = Buffer.from(held.subarray(start + 4, start + 4 + size))+ for (let i = 0; i < size; i++) body[i] ^= mask[i % 4]+ seen.push({ opcode: held[0] & 0x0f, body })+ held = held.subarray(start + 4 + size)+ }+ })+ upgrade?.(socket, seen)+ })+ const path = join(dir, `daemon-${PORT}.sock`)+ await new Promise(ready => server.listen(path, ready))+ chmodSync(path, 0o600)+ closers.push(() => new Promise(done => { for (const s of sockets) s.destroy(); server.closeAllConnections(); server.close(() => done()) }))+ return { env: { ADAPTER_DATA_DIR: dir }, path, seen }+}++const URL_ = `ws://127.0.0.1:${PORT}/api/local-ws`+const open = (env) => new DaemonWebSocket(URL_, { env })+const once = (socket, type) => new Promise(resolve => socket.addEventListener(type, resolve, { once: true }))+const eventually = async (check) => { for (let i = 0; i < 200; i++) { if (check()) return; await new Promise(r => setTimeout(r, 5)) } assert.fail('timed out') }+const frame = (opcode, body, fin = true) => {+ const data = Buffer.from(body)+ const head = data.length < 126 ? Buffer.from([(fin ? 0x80 : 0) | opcode, data.length]) : Buffer.from([(fin ? 0x80 : 0) | opcode, 126, data.length >> 8, data.length & 255])+ return Buffer.concat([head, data])+}++test('a message arrives whole, however the bytes are cut, and in pieces of a fragmented one', async () => {+ const whole = frame(1, 'x'.repeat(300))+ const d = await daemon({ upgrade: socket => {+ socket.write(whole.subarray(0, 1)); setTimeout(() => socket.write(whole.subarray(1, 3)), 5); setTimeout(() => socket.write(whole.subarray(3)), 10)+ setTimeout(() => { socket.write(frame(1, 'he', false)); socket.write(frame(0, 'llo')) }, 20)+ } })+ const socket = open(d.env), got = []+ socket.addEventListener('message', event => got.push(event.data))+ await eventually(() => got.length === 2)+ assert.deepEqual(got, ['x'.repeat(300), 'hello'])+ socket.close()+})++test('frames sent with the upgrade answer are not lost', async () => {+ const d = await daemon({ upgrade: socket => socket.write(frame(1, 'first')) })+ const socket = open(d.env), got = []+ socket.addEventListener('message', event => got.push(event.data))+ await eventually(() => got.length === 1)+ socket.close()+})++test('send masks, a ping gets a pong, and a server close reaches the caller with its code', async () => {+ const d = await daemon({ upgrade: socket => setTimeout(() => socket.write(frame(9, 'beat')), 5) })+ const socket = open(d.env)+ await once(socket, 'open')+ socket.send('hello')+ await eventually(() => d.seen.length >= 2)+ assert.deepEqual(d.seen.map(f => [f.opcode, f.body.toString()]).sort(), [[1, 'hello'], [10, 'beat']])+ socket.close()+})++test('a close code from the daemon, such as an unlinked machine, is what the caller reads', async () => {+ const code = Buffer.alloc(2); code.writeUInt16BE(4404)+ const d = await daemon({ upgrade: socket => setTimeout(() => socket.write(frame(8, code)), 5) })+ const closed = await once(open(d.env), 'close')+ assert.equal(closed.code, 4404)+})++test('a dropped connection closes, and sending then throws rather than vanishing', async () => {+ const d = await daemon({ upgrade: socket => setTimeout(() => socket.destroy(), 5) })+ const socket = open(d.env)+ const closed = await once(socket, 'close')+ assert.equal(closed.code, 1006)+ assert.throws(() => socket.send('late'))+})++test('a frame past the limit closes without being held', async () => {+ const huge = Buffer.alloc(10); huge[0] = 0x81; huge[1] = 127; huge.writeBigUInt64BE(1n << 40n, 2)+ const d = await daemon({ upgrade: socket => socket.write(huge) })+ assert.equal((await once(open(d.env), 'close')).code, 1009)+})++test('no socket, one anyone can reach, a wrong accept and a refusal are each an error, then a close', async () => {+ const dir = mkdtempSync(join('/tmp', 'ld-')); chmodSync(dir, 0o700)+ for (const socket of [open({ ADAPTER_DATA_DIR: dir })]) { const failed = once(socket, 'error'); await once(socket, 'close'); await failed }+ const open_ = await daemon(); chmodSync(open_.path, 0o666)+ assert.equal(socketIsPrivate(open_.path), false)+ await once(open(open_.env), 'error')+ await once(open((await daemon({ accept: 'wrong' })).env), 'error')+})++test('a socket in a folder others can write to is not private, and a symlink is not a socket', async () => {+ const d = await daemon()+ assert.equal(socketIsPrivate(d.path), true)+ chmodSync(join(d.path, '..'), 0o777)+ assert.equal(socketIsPrivate(d.path), false)+ chmodSync(join(d.path, '..'), 0o700)+ writeFileSync(`${d.path}.plain`, '')+ assert.equal(socketIsPrivate(`${d.path}.plain`), false)+})++test('close() gives up on a daemon that never answers it', async () => {+ const d = await daemon()+ const socket = open(d.env)+ await once(socket, 'open')+ socket.close()+ assert.equal((await once(socket, 'close')).code, 1006)+})++test('a connection the caller gave up on stays given up: no open, nothing sent, and the daemon sees it go', async () => {+ const dir = mkdtempSync(join('/tmp', 'ld-')); chmodSync(dir, 0o700)+ const events = [], path = join(dir, `daemon-${PORT}.sock`)+ const server = createServer()+ const gone = new Promise(resolve => server.on('upgrade', (req, stream) => {+ stream.on('error', () => {})+ // An http server's sockets stay half open: the peer's going is an `end`, which only a reader sees.+ stream.resume()+ stream.on('end', () => resolve(true))+ events.push('asked')+ // Answers late, as a daemon busy with a machine does: the caller has given up by then.+ setTimeout(() => {+ if (stream.destroyed || !stream.writable) return+ const accept = createHash('sha1').update(`${req.headers['sec-websocket-key']}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest('base64')+ stream.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`)+ }, 150)+ }))+ await new Promise(ready => server.listen(path, ready))+ chmodSync(path, 0o600)+ closers.push(() => new Promise(done => { server.closeAllConnections(); server.close(() => done()) }))+ const socket = open({ ADAPTER_DATA_DIR: dir })+ socket.addEventListener('open', () => events.push('open'))+ await eventually(() => events.includes('asked'))+ const closed = once(socket, 'close')+ socket.close()+ assert.equal((await closed).code, 1006)+ assert.equal(await Promise.race([gone, new Promise(r => setTimeout(() => r(false), 100))]), true, 'the request is cut, so nothing holds the process')+ await new Promise(r => setTimeout(r, 250))+ assert.deepEqual(events, ['asked'], 'no open after close')+ assert.equal(socket.readyState, 3)+ assert.throws(() => socket.send('late'))+})++test('fetch: a request and its body over the socket; the timeout reads as a timeout; nothing without the socket', async () => {+ const d = await daemon({ rest: (req, res) => {+ let raw = ''; req.on('data', c => { raw += c }); req.on('end', () => {+ if (req.url === '/slow') return+ res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ method: req.method, url: req.url, raw, local: req.headers['x-adapter-local'] }))+ })+ } })+ const base = `http://127.0.0.1:${PORT}`+ const answer = await daemonFetch(`${base}/api/x?y=1`, { env: d.env, method: 'POST', headers: { 'x-adapter-local': '1' }, body: '{"a":1}' })+ assert.equal(answer.ok, true)+ assert.deepEqual(await answer.json(), { method: 'POST', url: '/api/x?y=1', raw: '{"a":1}', local: '1' })+ await assert.rejects(daemonFetch(`${base}/slow`, { env: d.env, signal: AbortSignal.timeout(30) }), { name: 'TimeoutError' })+ const dir = mkdtempSync(join('/tmp', 'ld-')); chmodSync(dir, 0o700)+ await assert.rejects(daemonFetch(`${base}/api/x`, { env: { ADAPTER_DATA_DIR: dir } }), /not private/)+})++test('no socket on Windows or for a path too long; there the port is the only way', () => {+ assert.equal(daemonSocketPath(PORT, { ADAPTER_DATA_DIR: '/d' }, 'win32'), null)+ assert.equal(daemonSocketPath(PORT, { ADAPTER_DATA_DIR: `/${'x'.repeat(100)}` }, 'linux'), null)+ assert.equal(daemonSocketPath(PORT, { ADAPTER_DATA_DIR: '/d' }, 'linux'), `/d/daemon-${PORT}.sock`)+})diff --git a/store/tools/port-holder.test.mjs b/store/tools/port-holder.test.mjsnew file mode 100644index 000000000..4f0f8bffa--- /dev/null+++ b/store/tools/port-holder.test.mjs@@ -0,0 +1,131 @@+// node --test store/tools/port-holder.test.mjs+// Whoever holds the daemon's loopback port hears nothing from a Store package (audit H1), and each still works over the socket.+import assert from 'node:assert/strict'+import { createHash } from 'node:crypto'+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'+import { createServer } from 'node:http'+import { tmpdir } from 'node:os'+import { join } from 'node:path'+import { after, test } from 'node:test'+import { closeBridges, listAgents as monitorAgents } from '../agents/harness-monitor/lib/bridge.mjs'+import { closeBridges as closeMemories, listAgents as memoriesAgents } from '../agents/memories/lib/bridge.mjs'+import { closeSessions, listHarnesses, listMachines } from '../agents/machine-monitor/lib/daemon.mjs'+import { harnessExecute } from '../agents/autonomous-grid/lib/harness.mjs'++const CREDENTIAL = `test-local-credential-${'a'.repeat(21)}`+const closers = []+after(async () => { closeBridges(); closeMemories(); closeSessions(); for (const close of closers) await close() })++/** A data folder as the CLI leaves it, short enough to hold a socket, with a real credential a client could read. */+function dataDir() {+ const dir = join(mkdtempSync(join('/tmp', 'hold-')), 'd')+ mkdirSync(dir, { mode: 0o700 })+ writeFileSync(join(dir, 'hook-credential'), `${CREDENTIAL}\n`, { mode: 0o600 })+ chmodSync(join(dir, 'hook-credential'), 0o600)+ return dir+}++/** Another account on the port: it records everything and answers nothing useful. */+async function holder() {+ const heard = []+ const server = createServer((req, res) => { heard.push({ url: req.url, headers: req.headers }); res.writeHead(404).end() })+ server.on('upgrade', (req, socket) => { heard.push({ url: req.url, headers: req.headers }); socket.on('error', () => {}); socket.destroy() })+ await new Promise(ready => server.listen(0, '127.0.0.1', ready))+ closers.push(() => new Promise(done => { server.closeAllConnections(); server.close(() => done()) }))+ return { heard, port: server.address().port }+}++const envFor = (dir, port) => ({ ...process.env, ADAPTER_DATA_DIR: dir, HPS_BRIDGE_URL: `ws://127.0.0.1:${port}/api/local-ws`,+ MEMORIES_BRIDGE_URL: `ws://127.0.0.1:${port}/api/local-ws`, HARNESS_GRID_BRIDGE_URL: `ws://127.0.0.1:${port}/api/local-ws`,+ HARNESS_MACHINES_DAEMON: `http://127.0.0.1:${port}/` })++const text = (value) => {+ const body = Buffer.from(value)+ const head = body.length < 126 ? Buffer.from([0x81, body.length]) : Buffer.from([0x81, 126, body.length >> 8, body.length & 255])+ return Buffer.concat([head, body])+}+function unmasked(buffer) {+ if (buffer.length < 6) return null+ const short = buffer[1] & 0x7f, start = short === 126 ? 4 : 2+ const size = short === 126 ? buffer.readUInt16BE(2) : short+ if (buffer.length < start + 4 + size) return null+ const mask = buffer.subarray(start, start + 4), body = Buffer.from(buffer.subarray(start + 4, start + 4 + size))+ for (let i = 0; i < size; i++) body[i] ^= mask[i % 4]+ return { opcode: buffer[0] & 0x0f, text: body.toString(), size: start + 4 + size }+}++/** The real daemon's shape on its socket: no credential asked, the bridge's handshake, one roster and one REST answer. */+async function daemonOn(dir, port) {+ const got = []+ const server = createServer((req, res) => {+ got.push({ url: req.url, headers: req.headers })+ res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ data: { machines: [{ machineId: 'm' }] } }))+ })+ const upgraded = new Set()+ server.on('upgrade', (req, socket) => {+ got.push({ url: req.url, headers: req.headers })+ upgraded.add(socket)+ socket.on('error', () => {})+ const accept = createHash('sha1').update(`${req.headers['sec-websocket-key']}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest('base64')+ socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`)+ let held = Buffer.alloc(0)+ socket.on('data', (chunk) => {+ held = Buffer.concat([held, chunk])+ for (let frame = unmasked(held); frame; frame = unmasked(held)) {+ held = held.subarray(frame.size)+ if (frame.opcode === 8) { socket.end(); return }+ if (frame.opcode !== 1) continue+ const { type, payload } = JSON.parse(frame.text)+ got.push({ type })+ if (type === 'machine_select') socket.write(text(JSON.stringify({ type: 'connected', payload: { machineId: payload.machineId, relayIsolation: true } })))+ else if (payload?.requestId) socket.write(text(JSON.stringify({ type: `${type}_result`, payload: { requestId: payload.requestId, agents: [{ id: 'a1' }], harnesses: [], sampledAt: 1 } })))+ }+ })+ })+ const path = join(dir, `daemon-${port}.sock`)+ await new Promise(ready => server.listen(path, ready))+ chmodSync(path, 0o600)+ // An upgraded socket is no longer the server's to close.+ closers.push(() => new Promise(done => { for (const socket of upgraded) socket.destroy(); server.closeAllConnections(); server.close(() => done()) }))+ return { got }+}++const clients = {+ 'harness-monitor': env => monitorAgents('m', { env, timeoutMs: 1500 }),+ memories: env => memoriesAgents('m', { env, timeoutMs: 1500 }),+ 'machine-monitor rest': env => listMachines(env),+ 'machine-monitor bridge': env => listHarnesses('m', { env, timeoutMs: 1500 }),+ 'autonomous-grid': env => harnessExecute({ machineId: 'm' }, ['ls'], { env, timeoutMs: 1500 }),+}++for (const [name, run] of Object.entries(clients)) {+ test(`${name}: with the daemon down, a holder of its port hears nothing`, async () => {+ const dir = dataDir(), hold = await holder()+ await run(envFor(dir, hold.port)).catch(() => null)+ assert.deepEqual(hold.heard.map(h => ({ url: h.url, credential: h.headers['x-harness-local'] })), [], 'nothing reaches the port')+ })++ test(`${name}: works over the socket, with no credential, while another account holds the port`, async () => {+ const dir = dataDir(), hold = await holder(), daemon = await daemonOn(dir, hold.port)+ await run(envFor(dir, hold.port)).catch(() => null)+ assert.equal(hold.heard.length, 0, 'nothing reaches the port')+ assert.ok(daemon.got.length > 0, 'the daemon was reached over its socket')+ assert.ok(daemon.got.every(g => !g.headers?.['x-harness-local'] && !g.headers?.authorization), 'and shown no credential')+ })+}++test('a socket that is not private is not used, and nothing else is', async () => {+ const dir = dataDir(), hold = await holder(), daemon = await daemonOn(dir, hold.port)+ chmodSync(join(dir, `daemon-${hold.port}.sock`), 0o666)+ await monitorAgents('m', { env: envFor(dir, hold.port), timeoutMs: 1000 }).catch(() => null)+ assert.equal(hold.heard.length, 0)+ assert.equal(daemon.got.length, 0)+})++test('every package carries the same socket client', () => {+ const read = path => readFileSync(new URL(path, import.meta.url), 'utf8')+ const ours = read('./local-daemon.mjs')+ for (const name of ['harness-monitor', 'memories', 'machine-monitor', 'autonomous-grid']) {+ assert.equal(read(`../agents/${name}/lib/localDaemon.mjs`), ours, name)+ }+})