Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

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.ts
index 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.ts
index 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)!.displayName
const 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 * MINUTE
await 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_001
const 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 * MINUTE
const 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 const
export 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 = 20
diff --git a/backend/src/superTabs/deliverySettle.ts b/backend/src/superTabs/deliverySettle.ts
index 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_000
const 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.ts
index 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.ts
index 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, s
type 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: SuperTabStat
const 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 watchersLost
diff --git a/backend/src/superTabs/noticeDigest.test.ts b/backend/src/superTabs/noticeDigest.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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, may
import { 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 './cachedRe
import { 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) return
const 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 false
const 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 false
const generation = 'generation' in sender ? sender.generation : sender.membershipGeneration
return 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 = false
if (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 = 0
for (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 the
diff --git a/backend/vitest.super-tabs.config.ts b/backend/vitest.super-tabs.config.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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_000
const 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_000
export 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<number
return 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 = null
export 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) return
lastSweep = 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) : null
diff --git a/cli/src/lib/buddyGuard.ts b/cli/src/lib/buddyGuard.ts
index 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 allow
diff --git a/cli/src/lib/buddyGuard.wide.claude.spec.ts b/cli/src/lib/buddyGuard.wide.claude.spec.ts
index 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 Buddy
const 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 Buddy
git(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.ts
index 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).permissionDecision
const 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.ts
index 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 (audit
expect(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.ts
index 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.ts
index 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.ts
index 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): voi
const 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.ts
index 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 no
diff --git a/cli/src/superTabs/inCore/teamPurge.ts b/cli/src/superTabs/inCore/teamPurge.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 | null
env: NodeJS.ProcessEnv
tokenFile?: string | null
timeoutMs?: 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 = false
const finish = (error: Error | null, reply?: Record<string, unknown>): void => {
diff --git a/companions/src/companion/mcp.spec.ts b/companions/src/companion/mcp.spec.ts
index 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.ts
index 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.ts
index 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.ts
index 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.dart
index 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.dart
index 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.dart
index 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.dart
index 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.dart
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.mjs
index 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:fs
import { 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, inheri
socket.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 refused
diff --git a/store/agents/autonomous-grid/lib/localDaemon.mjs b/store/agents/autonomous-grid/lib/localDaemon.mjs
new file mode 100644
index 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.mjs
index 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 = discover
socket.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.mjs
index 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 characters
const 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.mjs
index 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, 'a
await 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.mjs
index 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:fs
import { 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 false
try {
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, forceReconnect
const 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 = null
let opened = false
@@ -161,7 +166,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnect
clearTimeout(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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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:fs
import { 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.mjs
new file mode 100644
index 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.mjs
index 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 } fr
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(), '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.mjs
index 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:fs
import { 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 false
try {
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, forceReconnect
const 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 = null
let opened = false
@@ -162,7 +167,7 @@ function openSession(machineId, { env, timeoutMs, WebSocketImpl, forceReconnect
clearTimeout(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.mjs
new file mode 100644
index 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.mjs
index 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.md
index 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/st
Daemon-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`).
```sh
diff --git a/store/tools/dsh-delete.mjs b/store/tools/dsh-delete.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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 refuse
diff --git a/store/tools/local-credential.test.mjs b/store/tools/local-credential.test.mjs
index 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 report
assert.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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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)
+ }
+})