The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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 } from 'vitest'
import { MongoMemoryReplSet } from 'mongodb-memory-server-core'
import { PrismaClient } from '@prisma/client'
import Fastify, { type FastifyInstance } from 'fastify'
import type { AuthUser } from '../src/lib/ssoAuth.js'
import { SuperTabStore } from '../src/superTabs/store.js'
import { noteChange, swarmTransaction } from '../src/superTabs/cache.js'
import { superTabRoutes } from '../src/routes/superTabs.js'
import { errorHandler } from '../src/middlewares/errorHandler.js'
import { commandSchema, type Command } from '../src/superTabs/commands.js'
import { appendRouting, FIRST_INSTRUCTIONS, instructionsHash } from '../src/superTabs/instructions.js'
import { stableId } from '../src/superTabs/model.js'
import { roleVersion } from '../src/superTabs/projects.js'
import { DEFAULT_ROUTING_POLICY } from '../src/superTabs/routingPolicy.js'
import { INSTRUCTIONS_TEMPLATE } from '../src/superTabs/instructionsTemplate.js'
import { rosterRows } from './hostRows.test-support.js'
import { SEED_RULES } from '../src/superTabs/policy.js'
import { plan, profiled, reads } from './plans.test-support.js'
// A fresh loopback replica set, created here. This suite never reads DATABASE_URL or an existing database.
// Project instructions, phase 2 (docs/plans/2026-10-30-project-instructions-plan.md): the document, its revisions, the
// coordinator's notes, role names and the migration job, against real transactions.
let replica: MongoMemoryReplSet
let db: PrismaClient
let store: SuperTabStore
let app: FastifyInstance
/** The store's clock: a test moves it to see a note expire. */
let now = Date.now()
const owner: AuthUser = { sub: '100000000000000000000001', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
const peer: AuthUser = { sub: '100000000000000000000002', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
const host: AuthUser = { sub: '100000000000000000000003', email: '[email protected]', autonomousEnv: 'prod', role: 'user' }
const config = { engine: 'codex', model: 'fixture-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }
const run = (tab: string, command: Command, user = owner, asAgentId?: string) =>
store.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)
/** [user]'s own Buddy, on a machine of theirs: it writes the server's notices in their private chat, where only they and it post
* (task #4558). */
async function ownBuddy(tab: string, user: AuthUser) {
const machineId = `${user.email.split('@')[0]}-mac`
await db.machine.upsert({ where: { machineId }, update: {}, create: { machineId, userId: user.sub, apiKey: `fixture-${randomUUID()}`, managerId: 'fixture', autonomousEnv: 'prod', authMode: 'remote' } })
const added = await run(tab, { type: 'buddy.create', machineId, engine: 'codex', setup: { name: 'Fixture Mac', cwd: '/fixture', engines: ['codex'] } }, user)
const startId = String(added.result.startId)
const onHost = (command: unknown) => store.execute(user, tab, { operationId: randomUUID(), command: commandSchema.parse(command) }, undefined, machineId)
await onHost({ type: 'agent.startDispatch', startId })
await onHost({ type: 'agent.started', startId, harnessId: randomUUID(), configuration: config })
await onHost({ type: 'agent.startSettled', startId, warning: null })
}
async function invite(tab: string) {
const invitation = await run(tab, { type: 'invite.create', email: peer.email, role: 'collaborator', conversationId: 'lead' })
await run(tab, { type: 'invite.accept', inviteId: invitation.result.inviteId as string }, peer)
}
async function withLead() {
const tab = (await store.create(owner, randomUUID(), 'Pilot')).id
const lead = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),
name: 'Lead', configuration: config, lead: true })).result.agentId as string
return { tab, lead }
}
const save = (baseRevision: number, text: string, summary = 'Changed.', projectId = 'lead'): Command =>
({ type: 'instructions.save', projectId, baseRevision, text, summary })
const get = (user: AuthUser, url: string) => app.inject({ method: 'GET', url, headers: { authorization: `Bearer ${user.sub}` } })
const post = (user: AuthUser, tab: string, command: Command) => app.inject({ method: 'POST', url: `/api/super-tabs/${tab}/commands`,
headers: { authorization: `Bearer ${user.sub}` }, payload: { operationId: randomUUID(), command } })
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(`instructions_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 } } })
store = new SuperTabStore(db, () => now)
for (const user of [owner, peer, host]) await db.user.create({ data: { id: user.sub, externalId: `fixture-${user.sub}`,
email: user.email, autonomousEnv: user.autonomousEnv } })
await db.machine.create({ data: { machineId: 'test-host', userId: host.sub, apiKey: 'fixture-only', managerId: 'fixture',
autonomousEnv: 'prod', authMode: 'remote' } })
await db.machineShare.create({ data: { machineId: 'test-host', ownerId: host.sub, autonomousEnv: 'prod', emails: [owner.email, peer.email] } })
app = Fastify()
app.setErrorHandler(errorHandler)
app.addHook('onRequest', async (request, reply) => {
const user = [owner, peer, host].find(u => `Bearer ${u.sub}` === request.headers.authorization)
if (!user) return reply.code(401).send({ success: false })
request.user = user
})
await app.register(superTabRoutes, { store, github: null })
await app.ready()
})
afterAll(async () => {
await app?.close()
await db?.$disconnect()
await replica?.stop()
})
describe('project instructions storage', () => {
it('starts a new Swarm\'s project and a new project on revision 1, a copy of the template, at the store\'s time', async () => {
// Both stamped by the store's clock, not the machine's (review of phase 2).
const was = now
now = Date.parse('2026-10-01T00:00:00.000Z')
const tab = (await store.create(owner, randomUUID(), 'Pilot')).id
const project = (await run(tab, { type: 'project.create', name: 'App', visibility: 'public', brief: '' })).result.projectId as string
now = was
for (const projectId of ['lead', project]) {
const stored = await db.superTabInstructions.findFirstOrThrow({ where: { tabId: tab, projectId } })
expect(stored).toMatchObject({ revision: 1, text: INSTRUCTIONS_TEMPLATE, hash: instructionsHash(INSTRUCTIONS_TEMPLATE) })
expect(await db.superTabInstructionsRevision.findMany({ where: { tabId: tab, projectId } })).toEqual([expect.objectContaining({
revision: 1, text: INSTRUCTIONS_TEMPLATE, writtenByKind: 'person', writtenBy: owner.sub, askedBy: owner.sub,
at: new Date('2026-10-01T00:00:00.000Z') })])
}
const head = (await store.read(owner, tab)).state.projects!
expect(head.map(p => p.instructionsRevision)).toEqual([1, 1])
})
it('refuses the second of two saves on the same revision with the first one\'s text, and posts no line for either save', async () => {
const tab = (await store.create(owner, randomUUID(), 'Pilot')).id
await invite(tab)
const first = await post(owner, tab, save(1, 'Reviews run on Opus.', 'Reviews run on Opus'))
expect(first.statusCode, first.body).toBe(200)
const second = await post(peer, tab, save(1, 'Tests run on the Mac.', 'Tests run on the Mac'))
expect(second.statusCode).toBe(409)
expect(second.json().error).toMatchObject({ code: 'INSTRUCTIONS_STALE', revision: 2, text: 'Reviews run on Opus.' })
expect((await post(peer, tab, save(2, 'Reviews run on Opus.\nTests run on the Mac.', 'Tests run on the Mac'))).statusCode).toBe(200)
// No chat line for a save (#3132); each stays a kept revision.
const lines = (await store.messages(owner, tab, 'lead', {})).messages.filter(m => (m.source as { kind?: string } | null)?.kind === 'instructions')
expect(lines).toEqual([])
expect((await db.superTabInstructionsRevision.findMany({ where: { tabId: tab, projectId: 'lead' }, orderBy: { revision: 'asc' } })).map(r => [r.revision, r.summary]))
.toEqual([[1, expect.any(String)], [2, 'Reviews run on Opus'], [3, 'Tests run on the Mac']])
expect((await db.superTabInstructions.findFirstOrThrow({ where: { tabId: tab, projectId: 'lead' } })).revision).toBe(3)
})
it('keeps the last 50 revisions and deletes everything with the project', async () => {
const tab = (await store.create(owner, randomUUID(), 'Pilot')).id
const project = (await run(tab, { type: 'project.create', name: 'App', visibility: 'public', brief: '' })).result.projectId as string
for (let base = 1; base <= 51; base++) await run(tab, save(base, `Revision ${base + 1}.`, `Revision ${base + 1}`, project))
const kept = await db.superTabInstructionsRevision.findMany({ where: { tabId: tab, projectId: project }, orderBy: { revision: 'asc' } })
expect(kept).toHaveLength(50)
expect([kept[0]!.revision, kept.at(-1)!.revision]).toEqual([3, 52])
expect(kept.at(-1)!.text).toBe('Revision 52.')
await run(tab, { type: 'project.delete', projectId: project })
expect(await db.superTabInstructions.count({ where: { tabId: tab, projectId: project } })).toBe(0)
expect(await db.superTabInstructionsRevision.count({ where: { tabId: tab, projectId: project } })).toBe(0)
expect(await db.superTabInstructions.count({ where: { tabId: tab, projectId: 'lead' } })).toBe(1)
})
})
// Task #3151: a save that drops a person's rule is refused, and goes through on that person's own message, read by the store,
// which tells them in their Buddy chats.
describe('configured rule approvals through the store', () => {
it('uses the saved decider and linked accounts, while refusing absent, agent and stale approvals', async () => {
const { tab, lead } = await withLead()
await invite(tab)
const invitation = await run(tab, { type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })
await run(tab, { type: 'invite.accept', inviteId: String(invitation.result.inviteId) }, host)
for (const account of [owner, host, peer]) await ownBuddy(tab, account)
await run(tab, { type: 'rules.set', projectId: 'lead', baseRevision: 0, rules: { ...structuredClone(SEED_RULES),
instructionApprovals: { topDeciderId: peer.sub, people: [{ name: 'Ken', accountIds: [owner.sub, host.sub] }] } }, summary: 'Explicit approval authority' })
const text = '# Rules\n\n- Always test before merging (Ken, 2026-11-04).'
await run(tab, save(1, text))
const drop = (revision: number, approvals: string[] = []) => run(tab, { ...save(revision, '# Rules\n'), askedBy: owner.sub, approvals } as Command, host, lead)
const message = async (user: AuthUser, asAgentId?: string) => String((await run(tab, { type: 'message.send', conversationId: 'lead', text: 'I approve removing this rule.', replyTo: null, recipientIds: [] }, user, asAgentId)).result.messageId)
await expect(drop(2)).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED' })
const agent = await message(host, lead)
await expect(drop(2, [agent])).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED' })
const stale = await message(peer)
const saved = await db.superTabInstructions.findFirstOrThrow({ where: { tabId: tab, projectId: 'lead' } })
await db.superTabMessage.update({ where: { id: stale }, data: { createdAt: new Date(saved.updatedAt.getTime() - 1) } })
await expect(drop(2, [stale])).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED' })
const decider = await message(peer)
const entries = await profiled(db, async () => expect((await drop(2, [decider])).result.revision).toBe(3))
const policyReads = plan(reads(entries, 'SuperTabProjectRules', ['tabId', 'projectId']))
expect(policyReads.length).toBeGreaterThan(0)
for (const read of policyReads) {
expect(read.plan).toContain('IXSCAN')
expect(read.docsExamined).toBe(1)
expect(read.returned).toBe(1)
}
const notices = await db.superTabMessage.findMany({ where: { tabId: tab, text: { contains: 'approved by peer' } } })
// Dee's approval tells the decider and both affected author accounts, through each person's two private Buddy chats, each
// line written by that person's own Buddy (task #4558).
expect(notices).toHaveLength(6)
for (const account of [owner, host, peer]) {
const visible = new Set((await store.read(account, tab)).state.conversations.map(c => c.id))
expect(notices.filter(n => visible.has(n.conversationId))).toHaveLength(2)
}
for (const notice of notices) {
expect(notice.text).toContain('Always test before merging')
expect(notice.text).not.toContain('as you approved')
}
for (const [index, account] of [owner, host].entries()) {
const revision = 4 + index * 2
await run(tab, save(revision - 1, text))
const approval = await message(account)
expect((await drop(revision, [approval])).result.revision).toBe(revision + 1)
}
})
})
describe('a person\'s rules in a save', () => {
it('refuses the PM\'s drop, then saves it on the person\'s own approval and tells them privately', async () => {
const { tab, lead } = await withLead()
await invite(tab)
await ownBuddy(tab, peer)
const rule = 'A bug that reaches stable is promoted back within the hour (peer, 2026-11-04).'
expect((await run(tab, save(1, `# Rules\n\n- ${rule}\n- Tests run first (owner, 4 Nov).`), peer)).result.revision).toBe(2)
const asLead = (approvals?: string[]) => store.execute(host, tab, { operationId: randomUUID(), command: { ...save(2, '# Rules\n\n- Tests run first (owner, 4 Nov).',
'Dropped the promote-back'), askedBy: owner.sub, ...(approvals ? { approvals } : {}) } }, lead)
await expect(asLead()).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED', details: { dropped: [{ rule, people: ['peer'], why: 'removed' }] } })
// The owner's message is not the peer's approval.
const ownerSaid = (await run(tab, { type: 'message.send', conversationId: 'lead', text: 'Drop it.', replyTo: null, recipientIds: [] })).result.messageId as string
await expect(asLead([ownerSaid])).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED' })
const peerSaid = (await run(tab, { type: 'message.send', conversationId: 'lead', text: 'Yes, drop my promote-back rule.', replyTo: null, recipientIds: [] }, peer))
.result.messageId as string
expect((await asLead([peerSaid])).result.revision).toBe(3)
// The History keeps what the save dropped, with its kind and who gave it (River, 11-05).
expect((await store.instructionRevision(owner, tab, 'lead', 3)).dropped).toEqual([{ text: rule, kind: 'rule', people: ['peer'] }])
// Revision 2 replaced the template: every template line it dropped is listed. One stored before the list was kept reads none.
expect((await store.instructionRevision(owner, tab, 'lead', 2)).dropped.length).toBeGreaterThan(10)
await db.superTabInstructionsRevision.updateMany({ where: { tabId: tab, projectId: 'lead', revision: 2 }, data: { dropped: null } })
expect((await store.instructionRevision(owner, tab, 'lead', 2)).dropped).toEqual([])
const notices = await db.superTabMessage.findMany({ where: { tabId: tab, text: { contains: 'as you approved' } } })
expect(notices.length).toBe(2)
for (const notice of notices) {
expect(notice.conversationId).not.toBe('lead')
expect(notice.text).toContain('A bug that reaches stable')
expect(notice.recipientIds).toEqual([])
}
// Only the peer reads them.
const chats = new Set(notices.map(n => n.conversationId))
for (const chat of chats) {
expect((await store.messages(peer, tab, chat, {})).messages.some(m => m.text.includes('as you approved'))).toBe(true)
await expect(store.messages(owner, tab, chat, {})).rejects.toBeTruthy()
}
})
})
describe('PM notes storage', () => {
it('keeps the coordinator\'s notes beside the project, deletes an expired one on the next write, and tells it of a removal', async () => {
const { tab, lead } = await withLead()
await invite(tab)
const add = async (text: string, expiresAt?: number) => (await run(tab, { type: 'note.add', projectId: 'lead', text, askedBy: peer.sub,
...(expiresAt ? { expiresAt: new Date(expiresAt).toISOString() } : {}) }, host, lead)).result.noteId as string
const lasting = await add('Do not use Codex on machine A.')
const tonight = await add('Hold releases until tonight.', now + 60_000)
expect((await db.superTabPmNote.findMany({ where: { tabId: tab, projectId: 'lead' }, orderBy: { at: 'asc' } })).map(n => n.id)).toEqual([lasting, tonight])
now += 120_000
const third = await add('Prefer the Studio for Desktop tests.')
expect((await db.superTabPmNote.findMany({ where: { tabId: tab, projectId: 'lead' } })).map(n => n.id).sort()).toEqual([lasting, third].sort())
await run(tab, { type: 'note.remove', projectId: 'lead', noteId: lasting }, peer)
expect(await db.superTabPmNote.count({ where: { tabId: tab, projectId: 'lead' } })).toBe(1)
const told = await db.superTabDelivery.findMany({ where: { tabId: tab, agentId: lead } })
const rows = await db.superTabMessage.findMany({ where: { tabId: tab, conversationId: 'lead' } })
const notice = rows.find(m => m.text === 'peer removed your note: "Do not use Codex on machine A."')!
expect(notice.recipientIds).toEqual([lead])
expect(told.some(d => d.messageId === notice.id)).toBe(true)
expect((await store.read(owner, tab)).state.projects![0]!.notesRevision).toBe(4)
})
})
describe('role names and the coordinator\'s name in reads', () => {
it('names each agent\'s role and its project\'s instructions in its host\'s rows and the members\' read', async () => {
const { tab, lead } = await withLead()
const tester = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),
name: 'Tester', configuration: config, lead: false, roleName: 'Tester' })).result.agentId as string
const rows = async () => (await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab) as Array<{ agent: { id: string }; roleName: string;
instructions: unknown }>
const of = async (id: string) => (await rows()).find(r => r.agent.id === id)!
expect(await of(lead)).toMatchObject({ roleName: 'PM', instructions: { projectId: 'lead', revision: 1, hash: instructionsHash(INSTRUCTIONS_TEMPLATE),
coordinatorName: 'Product Manager' } })
expect((await of(tester)).roleName).toBe('Tester')
await run(tab, { type: 'project.coordinatorName', projectId: 'lead', name: 'Lead engineer' }, host, lead)
await run(tab, save(1, 'Our own way.'))
expect((await of(tester)).instructions).toEqual({ projectId: 'lead', revision: 2, hash: instructionsHash('Our own way.'), coordinatorName: 'Lead engineer' })
const read = await get(owner, `/api/super-tabs/${tab}/parts`)
expect(read.statusCode, read.body).toBe(200)
const { head, derived } = read.json().data
expect(head.data.projects[0]).toMatchObject({ instructionsRevision: 2, coordinatorName: 'Lead engineer' })
expect(derived.agents[tester].roleName).toBe('Tester')
expect(derived.agents[lead].roleName).toBe('PM')
})
})
describe('reading the instructions', () => {
const doc = (tab: string, projectId = 'lead', asAgentId?: string) => `/api/super-tabs/${tab}/projects/${projectId}/instructions${asAgentId ? `?asAgentId=${asAgentId}` : ''}`
it('serves the text, the live notes and the history to who reads the project; a Buddy the text alone', async () => {
const { tab, lead } = await withLead()
await invite(tab)
await run(tab, save(1, 'Reviews run on Opus.', 'Reviews run on Opus'))
await run(tab, { type: 'instructions.save', projectId: 'lead', baseRevision: 2, text: 'Reviews run on Opus.\nTests on the Mac.', summary: 'Tests on the Mac',
askedBy: peer.sub }, host, lead)
const noted = (await run(tab, { type: 'note.add', projectId: 'lead', text: 'Not machine A.', askedBy: peer.sub }, host, lead)).result.noteId as string
await run(tab, { type: 'note.add', projectId: 'lead', text: 'Until soon.', askedBy: peer.sub, expiresAt: new Date(now + 1000).toISOString() }, host, lead)
now += 5000
for (const [user, as] of [[owner], [peer], [host, lead]] as Array<[AuthUser, string?]>) {
const answer = await get(user, doc(tab, 'lead', as))
expect(answer.statusCode, answer.body).toBe(200)
expect(answer.json().data).toMatchObject({ projectId: 'lead', revision: 3, hash: instructionsHash('Reviews run on Opus.\nTests on the Mac.'),
text: 'Reviews run on Opus.\nTests on the Mac.', template: false, coordinatorName: 'Product Manager', notesRevision: 2,
notes: [{ id: noted, text: 'Not machine A.', askedBy: peer.sub, expiresAt: null }] })
}
const history = await get(peer, `${doc(tab)}/revisions`)
expect(history.json().data.revisions.map((r: { revision: number }) => r.revision)).toEqual([3, 2, 1])
expect(history.json().data.revisions[0]).toEqual({ revision: 3, hash: instructionsHash('Reviews run on Opus.\nTests on the Mac.'), summary: 'Tests on the Mac',
writtenBy: { kind: 'agent', id: lead }, askedBy: peer.sub, at: expect.any(String) })
expect(history.json().data.revisions[0]).not.toHaveProperty('text')
const one = await get(peer, `${doc(tab)}/revisions/2`)
expect(one.json().data).toMatchObject({ revision: 2, text: 'Reviews run on Opus.', writtenBy: { kind: 'person', id: owner.sub }, askedBy: owner.sub })
expect((await get(peer, `${doc(tab)}/revisions/9`)).statusCode).toBe(404)
// A Buddy reads its member's project's document, as their helper: not the history, nor the coordinator's notes.
const helper = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),
name: 'Helper', configuration: config, lead: false })).result.agentId as string
const row = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: helper } })
const people = (await store.read(owner, tab)).state.people
await db.swarmAgent.update({ where: { id: row.id }, data: { data: { ...row.data as object,
buddyOf: { personId: owner.sub, generation: people.find(p => p.id === owner.sub)!.generation } } } })
const asBuddy = await get(host, doc(tab, 'lead', helper))
expect(asBuddy.statusCode, asBuddy.body).toBe(200)
expect(asBuddy.json().data).toMatchObject({ revision: 3, text: 'Reviews run on Opus.\nTests on the Mac.' })
expect(asBuddy.json().data).not.toHaveProperty('notes')
expect((await get(host, `${doc(tab, 'lead', helper).replace('?', '/revisions?')}`)).statusCode).toBe(404)
})
it('reads nothing of a project the reader cannot read, and the template for a project without a document yet', async () => {
const tab = (await store.create(owner, randomUUID(), 'Pilot')).id
await invite(tab)
const secret = (await run(tab, { type: 'project.create', name: 'Secret', visibility: 'private', brief: '' })).result.projectId as string
for (const url of [doc(tab, secret), `${doc(tab, secret)}/revisions`, `${doc(tab, secret)}/revisions/1`]) expect((await get(peer, url)).statusCode).toBe(404)
expect((await get(owner, doc(tab, secret))).statusCode).toBe(200)
// A project from before instructions, until the migration writes its document: the built-in template, revision 0, with the
// template's hash so a running daemon reads again when the template moves (agent-context design, section 3).
const head = await db.swarmHead.findFirstOrThrow({ where: { tabId: tab } })
const data = head.data as { projects: Array<Record<string, unknown>> }
await db.swarmHead.update({ where: { id: head.id }, data: { data: { ...data, projects: data.projects.map(({ instructionsRevision: _r, instructionsHash: _h, ...p }) => p) } as never } })
expect((await get(owner, doc(tab))).json().data).toMatchObject({ revision: 0, hash: FIRST_INSTRUCTIONS.instructionsHash, text: INSTRUCTIONS_TEMPLATE, template: true, notes: [] })
})
it('reads nothing to a Buddy whose person lost the private project, as every other Buddy read (review of phase 2)', async () => {
const tab = (await store.create(owner, randomUUID(), 'Pilot')).id
await invite(tab)
const secret = (await run(tab, { type: 'project.create', name: 'Secret', visibility: 'private', brief: '' })).result.projectId as string
await run(tab, { type: 'project.sharing', projectId: secret, visibility: 'private', memberIds: [peer.sub] })
const home = (await store.read(owner, tab)).state.projects!.find(p => p.id === secret)!.leadConversationId
const helper = (await run(tab, { type: 'agent.add', conversationId: home, machineId: 'test-host', harnessId: randomUUID(),
name: 'Helper', configuration: config, lead: false })).result.agentId as string
const row = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: helper } })
const people = (await store.read(owner, tab)).state.people
await db.swarmAgent.update({ where: { id: row.id }, data: { data: { ...row.data as object,
buddyOf: { personId: peer.sub, generation: people.find(p => p.id === peer.sub)!.generation } } } })
const asBuddy = () => get(host, doc(tab, secret, helper))
const before = await asBuddy()
expect(before.statusCode, before.body).toBe(200)
// The owner takes peer off the project; the Buddy stays, and its reads go with its person's.
await run(tab, { type: 'project.sharing', projectId: secret, visibility: 'private', memberIds: [] })
expect((await store.read(owner, tab)).state.agents.some(a => a.id === helper)).toBe(true)
expect((await asBuddy()).statusCode).toBe(404)
})
// Task #3024 (Leo, 11-05): his Buddy, asked which of lamp's rules its PM skipped, could not read lamp's instructions. A Buddy
// reads the instructions of every project its person reads, a session of one project's included, as they would read them;
// nothing else widens.
describe('a Buddy reads the instructions of every project its person reads (task #3024)', () => {
/** peer's Buddy in [conversationId], at peer's membership; `swarm` makes it their one Buddy for the whole Swarm. */
async function peersBuddy(tab: string, conversationId: string, swarm = false) {
const helper = (await run(tab, { type: 'agent.add', conversationId, machineId: 'test-host', harnessId: randomUUID(),
name: 'Helper', configuration: config, lead: false })).result.agentId as string
const row = await db.swarmAgent.findFirstOrThrow({ where: { tabId: tab, key: helper } })
const people = (await store.read(owner, tab)).state.people
await db.swarmAgent.update({ where: { id: row.id }, data: { data: { ...row.data as object,
buddyOf: { personId: peer.sub, generation: people.find(p => p.id === peer.sub)!.generation }, ...(swarm ? { buddyScope: 'swarm' } : {}) } } })
return helper
}
/** A Swarm whose first project has a document, peer in it, and two more projects: Lamp, which peer reads, and Secret, which
* peer does not. */
async function swarmOfThree() {
const { tab, lead } = await withLead()
await invite(tab)
await run(tab, save(1, 'Reviews run on Opus.', 'Reviews run on Opus'))
await run(tab, { type: 'note.add', projectId: 'lead', text: 'Not machine A.', askedBy: peer.sub }, host, lead)
const lamp = (await run(tab, { type: 'project.create', name: 'Lamp', visibility: 'private', brief: '' })).result.projectId as string
await run(tab, { type: 'project.sharing', projectId: lamp, visibility: 'private', memberIds: [peer.sub] })
await run(tab, save(1, 'Tag the builder\'s owner.', 'Tag owners', lamp))
const secret = (await run(tab, { type: 'project.create', name: 'Secret', visibility: 'private', brief: '' })).result.projectId as string
await run(tab, save(1, 'Only the owner reads this.', 'Owner only', secret))
const chatOf = async (projectId: string) => (await store.read(owner, tab)).state.projects!.find(p => p.id === projectId)!.leadConversationId
return { tab, lamp, secret, lampChat: await chatOf(lamp) }
}
it('reads, as a session of one project, another project its person reads: the text alone, as its person reads it', async () => {
const { tab, lamp, lampChat } = await swarmOfThree()
// A Buddy of Lamp's chat reads the first project's instructions too, as peer does.
const helper = await peersBuddy(tab, lampChat)
const asPeer = await get(peer, doc(tab, 'lead'))
const asBuddy = await get(host, doc(tab, 'lead', helper))
expect(asBuddy.statusCode, asBuddy.body).toBe(200)
expect(asBuddy.json().data).toMatchObject({ projectId: 'lead', revision: 2, text: asPeer.json().data.text, hash: asPeer.json().data.hash })
expect(asBuddy.json().data.text).toBe('Reviews run on Opus.')
// Never more than the document: not the coordinator's notes, nor the PM's built-in schedule.
expect(asBuddy.json().data).not.toHaveProperty('notes')
expect(asBuddy.json().data).not.toHaveProperty('builtIn')
// Its own project's, as before.
expect((await get(host, doc(tab, lamp, helper))).json().data).toMatchObject({ revision: 2, text: 'Tag the builder\'s owner.' })
})
it('reads, as its person\'s one Buddy, each project they read', async () => {
const { tab, lamp } = await swarmOfThree()
const helper = await peersBuddy(tab, 'lead', true)
for (const [projectId, text] of [['lead', 'Reviews run on Opus.'], [lamp, 'Tag the builder\'s owner.']] as const) {
const answer = await get(host, doc(tab, projectId, helper))
expect(answer.statusCode, answer.body).toBe(200)
expect(answer.json().data).toMatchObject({ projectId, revision: 2, text })
expect(answer.json().data).not.toHaveProperty('notes')
}
})
it('reads nothing of a project its person cannot read, in the words of one that does not exist', async () => {
const { tab, lamp, secret, lampChat } = await swarmOfThree()
for (const helper of [await peersBuddy(tab, lampChat), await peersBuddy(tab, 'lead', true)]) {
const [hidden, missing] = await Promise.all([secret, 'no-such-project'].map(projectId => get(host, doc(tab, projectId, helper))))
expect(hidden!.statusCode, hidden!.body).toBe(404)
expect(hidden!.json()).toMatchObject({ success: false, error: { code: 'NOT_FOUND' } })
expect(hidden!.body).toBe(missing!.body)
}
// Once peer leaves Lamp, a Buddy of another project reads none of Lamp's either.
const elsewhere = await peersBuddy(tab, 'lead')
expect((await get(host, doc(tab, lamp, elsewhere))).statusCode).toBe(200)
await run(tab, { type: 'project.sharing', projectId: lamp, visibility: 'private', memberIds: [] })
expect((await get(host, doc(tab, lamp, elsewhere))).statusCode).toBe(404)
})
it('still saves nothing, adds no note and reads no history, in its own project or another', async () => {
const { tab, lamp, lampChat } = await swarmOfThree()
for (const helper of [await peersBuddy(tab, lampChat), await peersBuddy(tab, 'lead', true)]) {
for (const projectId of ['lead', lamp]) {
await expect(run(tab, save(2, 'A Buddy\'s text.', 'Buddy', projectId), host, helper)).rejects.toMatchObject({ code: 'BUDDY_FORBIDDEN' })
await expect(run(tab, { type: 'instructions.save', projectId, baseRevision: 2, text: 'A Buddy\'s text.', summary: 'Buddy', askedBy: peer.sub }, host, helper))
.rejects.toMatchObject({ code: 'BUDDY_FORBIDDEN' })
await expect(run(tab, { type: 'note.add', projectId, text: 'A Buddy\'s note.', askedBy: peer.sub }, host, helper)).rejects.toMatchObject({ code: 'BUDDY_FORBIDDEN' })
for (const url of [`${doc(tab, projectId)}/revisions?asAgentId=${helper}`, `${doc(tab, projectId)}/revisions/1?asAgentId=${helper}`]) {
expect((await get(host, url)).statusCode).toBe(404)
}
}
}
// Nothing it sent was written: both documents are where they were.
for (const [projectId, text] of [['lead', 'Reviews run on Opus.'], [lamp, 'Tag the builder\'s owner.']] as const) {
expect((await get(peer, doc(tab, projectId))).json().data).toMatchObject({ revision: 2, text })
}
})
})
})
// An older client's saves (project instructions, phase 4, decision 3): a rule lands in the Routing section as a new revision;
// a policy, a skill set or a role is answered and kept nowhere.
// Task #4673 (anh Dee, 11-07): an agent reads its project's instructions and nothing the Swarm adds. The coordinator's read
// carried a built-in schedule beside the document, and its roster row that text's hash.
describe('the instructions read, with no built-in text', () => {
const doc = (tab: string, asAgentId?: string) => `/api/super-tabs/${tab}/projects/lead/instructions${asAgentId ? `?asAgentId=${asAgentId}` : ''}`
const withWorker = async () => {
const { tab, lead } = await withLead()
const worker = (await run(tab, { type: 'agent.add', conversationId: 'lead', machineId: 'test-host', harnessId: randomUUID(),
name: 'Worker', configuration: config, lead: false })).result.agentId as string
return { tab, lead, worker }
}
it('gives every reader the document alone, the coordinator included', async () => {
const { tab, lead, worker } = await withWorker()
for (const [user, as] of [[host, lead], [host, worker], [owner]] as Array<[AuthUser, string?]>) {
const answer = await get(user, doc(tab, as))
expect(answer.statusCode, answer.body).toBe(200)
expect(answer.json().data).toMatchObject({ revision: 1, text: INSTRUCTIONS_TEMPLATE, hash: instructionsHash(INSTRUCTIONS_TEMPLATE) })
expect(answer.json().data).not.toHaveProperty('builtIn')
}
})
it('names no built-in hash on any roster row, the coordinator\'s included', async () => {
const { tab, lead, worker } = await withWorker()
const rows = (await rosterRows(store, host, 'test-host')).filter(r => r.tabId === tab) as Array<{ agent: { id: string }; instructions: Record<string, unknown> }>
for (const id of [lead, worker]) expect(rows.find(r => r.agent.id === id)!.instructions).not.toHaveProperty('builtInHash')
})
it('takes a save holding the old built-in heading as the project\'s own text', async () => {
const { tab, lead } = await withLead()
const read = (await get(host, doc(tab, lead))).json().data
await run(tab, { type: 'instructions.save', projectId: 'lead', baseRevision: 1, text: `${read.text}\n\n## Built-in PM schedule (from the Swarm)\n\nOur own jobs.`,
summary: 'Our schedule', askedBy: owner.sub }, host, lead)
expect((await get(owner, doc(tab))).json().data).toMatchObject({ revision: 2, text: expect.stringContaining('Our own jobs.') })
})
})
describe('an older client\'s saves', () => {
it('takes an old Desktop\'s saves', async () => {
const { tab, lead } = await withLead()
const policy = await app.inject({ method: 'POST', url: '/api/super-tabs/routing-policy', headers: { authorization: `Bearer ${owner.sub}` },
payload: { revision: 0, policy: { ...DEFAULT_ROUTING_POLICY, quotaReserve: 30 } } })
expect(policy.statusCode, policy.body).toBe(200)
expect(policy.json().data).toMatchObject({ isDefault: true, revision: 0, ignored: true })
expect(await db.routingPolicy.count({ where: { userId: owner.sub } })).toBe(0)
const role = await post(owner, tab, { type: 'project.role.set', projectId: 'lead', role: { id: 'dev', name: 'Builder', kind: 'builder', text: 'Build.' } })
expect(role.statusCode, role.body).toBe(200)
expect(JSON.stringify(role.json())).toContain('"ignored":true')
expect(await db.superTabRoleText.count({ where: { tabId: tab } })).toBe(0)
// An old CLI's rule, from its Lead quoting the owner: a new revision the members' read serves.
const said = (await run(tab, { type: 'message.send', conversationId: 'lead', text: 'No Haiku, please.', replyTo: null, recipientIds: [] })).result.messageId as string
await run(tab, { type: 'rule.set', rule: { kind: 'forbidModel', model: 'haiku' }, text: 'No Haiku.', askedIn: { conversationId: 'lead', messageId: said } }, host, lead)
const read = (await get(owner, `/api/super-tabs/${tab}/projects/lead/instructions`)).json().data
expect(read).toMatchObject({ revision: 2, text: appendRouting(INSTRUCTIONS_TEMPLATE, 'No Haiku.') })
expect(await db.superTabInstructionsRevision.findFirstOrThrow({ where: { tabId: tab, projectId: 'lead', revision: 2 } }))
.toMatchObject({ askedBy: owner.sub, writtenByKind: 'agent', writtenBy: lead, summary: 'Routing: No Haiku.' })
expect((await store.read(owner, tab)).state).not.toHaveProperty('rules')
})
})
describe('the migration job', () => {
/** A Swarm as it was before instructions: no revision on its projects and no document, with rules, a policy and roles. */
async function oldSwarm() {
const tab = (await store.create(owner, randomUUID(), 'Old')).id
const custom = (await run(tab, { type: 'project.create', name: 'Custom', visibility: 'public', brief: '' })).result.projectId as string
// An open task that requires a device: not written into the document.
await run(tab, { type: 'conversation.create', title: 'Firmware', task: { goal: 'Flash it', changes: 'Firmware', constraints: 'None', owns: ['firmware'],
requires: { devices: ['/dev/tty.usbmodem-board'] } }, checks: [] })
await db.superTabInstructions.deleteMany({ where: { tabId: tab } })
await db.superTabInstructionsRevision.deleteMany({ where: { tabId: tab } })
// What older clients saved, as they stored it (those saves keep nothing now): a custom set with its texts, a rule, a policy.
const texts = { lead: 'Coordinate the work.', dev: 'Build one task at a time.' }
const roles = [{ id: 'lead', name: 'Coordinator', kind: 'lead', version: roleVersion(texts.lead) }, { id: 'dev', name: 'Builder', kind: 'builder', version: roleVersion(texts.dev) }]
for (const [roleId, text] of Object.entries(texts)) {
await db.superTabRoleText.create({ data: { id: stableId(tab, custom, roleId), tabId: tab, projectId: custom, roleId, version: roleVersion(text), text } })
}
const rules = [{ id: 'old-rule', projectId: 'lead', rule: { kind: 'preferIdle' }, text: 'Prefer idle agents before starting new ones.', askedBy: owner.sub,
askedIn: null, addedBy: `person:${owner.sub}`, createdAt: new Date(now).toISOString() }]
const head = await db.swarmHead.findFirstOrThrow({ where: { tabId: tab } })
const data = head.data as { projects: Array<Record<string, unknown>> }
const projects = data.projects.map(({ instructionsRevision: _r, instructionsHash: _h, ...p }) => p.id === custom ? { ...p, skillSet: 'custom', skillMode: 'default', roles } : p)
await db.swarmHead.update({ where: { id: head.id }, data: { data: { ...data, projects, rules, routingPolicy: { notes: 'Opus for hard work.', quotaReserve: 25 } } as never } })
return { tab, custom }
}
const rows = async (tab: string) => (await db.superTabInstructions.findMany({ where: { tabId: tab }, orderBy: { projectId: 'asc' } }))
.map(({ updatedAt: _at, ...row }) => row)
it('prints what it would write on a dry run, writes it once with --apply, and changes nothing when run again', async () => {
const { tab, custom } = await oldSwarm()
const later = (await store.create(owner, randomUUID(), 'New')).id
const { migrateInstructions } = await import('../src/superTabs/migration/instructions.js')
const dry = await migrateInstructions(db, { apply: false })
const mine = dry.documents.filter(d => d.tabId === tab)
expect(mine.map(d => [d.projectId, d.from]).sort()).toEqual([[custom, 'custom'], ['lead', 'template']].sort())
expect(dry.documents.some(d => d.tabId === later)).toBe(false)
expect(await rows(tab)).toEqual([])
const lead = mine.find(d => d.projectId === 'lead')!.text
expect(lead).toContain('- Prefer idle agents before starting new ones.')
expect(lead).toContain('- Routing notes: Opus for hard work.')
expect(lead).toContain('- Keep 25% of each engine\'s quota in reserve.')
expect(mine.map(d => d.text).join('')).not.toContain('usbmodem')
expect(mine.find(d => d.projectId === custom)!.text).toContain('### Coordinator\n\nCoordinate the work.\n\n### Builder\n\nBuild one task at a time.')
const applied = await migrateInstructions(db, { apply: true })
expect(applied.failed).toEqual([])
expect(applied.documents.filter(d => d.tabId === tab)).toEqual(mine)
const first = await rows(tab)
expect(first.map(r => [r.projectId, r.revision, r.text]).sort()).toEqual(mine.map(d => [d.projectId, 1, d.text]).sort())
const state = (await store.read(owner, tab)).state
for (const document of mine) expect(state.projects!.find(p => p.id === document.projectId)).toMatchObject({ instructionsRevision: 1,
instructionsHash: instructionsHash(document.text) })
expect(await db.superTabInstructionsRevision.findFirstOrThrow({ where: { tabId: tab, projectId: 'lead' } })).toMatchObject({ revision: 1,
writtenByKind: 'system', writtenBy: 'migration', askedBy: owner.sub })
// The members' read serves the migrated text.
expect((await get(owner, `/api/super-tabs/${tab}/projects/lead/instructions`)).json().data).toMatchObject({ revision: 1, text: lead, template: false })
const again = await migrateInstructions(db, { apply: true })
expect(again.documents).toEqual([])
expect(again.alreadyDone).toBeGreaterThanOrEqual(applied.alreadyDone + applied.documents.length)
expect(await rows(tab)).toEqual(first)
// A save since the migration is the team's: a later run leaves it.
await run(tab, save(1, 'Our own words.'))
expect((await migrateInstructions(db, { apply: true })).documents).toEqual([])
expect((await db.superTabInstructions.findFirstOrThrow({ where: { tabId: tab, projectId: 'lead' } })).text).toBe('Our own words.')
})
})
// Task #3392 (anh Dee, 11-05, decision 5): a person's rule may move into a code task, its line staying until that task merges.
// Task #3463 (review of #3220): merged as GitHub itself dates it, after the rule went into the task, read by the store at the
// save, so it works with tidying off; a merged task gone quiet counts once the save names it.
describe('a rule moved into a code task', () => {
const PR = 'https://github.com/acme/app/pull/7'
const leo = 'A bug that reaches stable ships its fix the same day (peer, 2026-11-04).'
const doc = (...rules: string[]) => ['# Project instructions', '', '## Rules', '', ...rules.map(r => `- ${r}`)].join('\n')
/** A Swarm whose project's repository is acme/app, tidying off, its instructions keeping peer's rule; a store whose GitHub
* says what [merges] holds; and a code task carrying the rule, linking PR. */
async function moved(carried = leo, repositoryUrl = 'https://github.com/acme/app') {
const merges: Record<string, number | null> = {}, read: string[][] = []
const github = new SuperTabStore(db, () => now, null, { pullRequestMerges: async (_env, _tab, _project, urls) => {
read.push(urls)
return Object.fromEntries(urls.filter(url => url in merges).map(url => [url, merges[url]!]))
} })
const { tab, lead } = await withLead()
await invite(tab)
await swarmTransaction(db, async tx => {
const head = await tx.swarmHead.findUniqueOrThrow({ where: { id: `${tab}:head` } }), data = head.data as { projects?: Array<{ id: string }> }
const repository = { machineId: 'test-host', cwd: '/repo', repositoryUrl }
await tx.swarmHead.update({ where: { id: head.id }, data: { version: head.version + 1, data: (data.projects
? { ...data, projects: data.projects.map(p => p.id === 'lead' ? { ...p, repository } : p) } : { ...data, project: repository }) as object } })
noteChange(tx, tab, 'main')
})
await run(tab, { type: 'tab.tidy', enabled: false })
await run(tab, save(1, doc(leo, 'Tests run first.')))
const task = (await run(tab, { type: 'conversation.create', title: 'Stable fixes', brief: `Goal:\nSame-day fixes.\n\nChanges:\n- ${carried}`,
checks: [] })).result.conversationId as string
// The PM records the merge with a link: its word alone frees nothing (River, review of #3220).
await run(tab, { type: 'conversation.merged', conversationId: task, pullRequestUrl: PR }, host, lead)
const briefAt = (await db.swarmGroup.findFirstOrThrow({ where: { tabId: tab, key: task } })).data as { briefAt?: number }
const drop = (tasks?: string[]) => github.execute(owner, tab, { operationId: randomUUID(), command: { type: 'instructions.save', projectId: 'lead',
baseRevision: 2, text: doc('Tests run first.'), summary: 'Moved the stable rule to its task', ...tasks ? { tasks } : {} } })
return { tab, task, merges, read, drop, briefAt: briefAt.briefAt! }
}
it('leaves, with tidying off, once GitHub says the task merged after the move, and not for an older merge', async () => {
const m = await moved()
expect(m.briefAt).toBe(now)
// GitHub: not merged. The line stays, naming the task.
m.merges[PR] = null
await expect(m.drop()).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED', details: { dropped: [{ why: 'waiting' }] } })
expect(m.read.at(-1)).toEqual([PR])
// Merged, but before the rule went into the task: it never carried it.
m.merges[PR] = m.briefAt - 60_000
await expect(m.drop()).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED', details: { dropped: [{ why: 'waiting' }] } })
// Merged after: the person's save drops the line, though no archive pass ever ran.
m.merges[PR] = m.briefAt + 60_000
expect((await m.drop()).result).toMatchObject({ revision: 3 })
})
// Review 2 of #3273: a project whose repository is not on GitHub has no GitHub merge of its own; a GitHub link frees nothing.
it('frees nothing for a project whose repository is not on GitHub, whatever a linked GitHub pull request did', async () => {
const m = await moved(leo, 'https://gitlab.com/acme/app')
m.merges[PR] = m.briefAt + 60_000
await expect(m.drop()).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED', details: { dropped: [{ why: 'waiting' }] } })
expect(m.read).toEqual([])
})
// Review 1 of #3273: the brief wraps the rule as the instructions wrap theirs, at 120 columns.
it('reads the merge of a task that carries the rule across wrapped lines', async () => {
const m = await moved('A bug that reaches stable ships its fix\n the same day (peer, 2026-11-04).')
m.merges[PR] = m.briefAt + 60_000
expect((await m.drop()).result).toMatchObject({ revision: 3 })
expect(m.read.at(-1)).toEqual([PR])
})
it('counts a merged task that went quiet once the save names it', async () => {
const m = await moved()
m.merges[PR] = m.briefAt + 60_000
const part = await db.swarmGroup.findFirstOrThrow({ where: { tabId: m.tab, key: m.task } })
await swarmTransaction(db, async tx => {
await tx.swarmGroup.update({ where: { id: part.id }, data: { dormant: true, version: part.version + 1, data: { ...part.data as object, dormant: true } } })
noteChange(tx, m.tab, 'main')
})
await expect(m.drop()).rejects.toMatchObject({ code: 'INSTRUCTIONS_RULES_DROPPED', details: { dropped: [{ why: 'removed' }] } })
expect((await m.drop([m.task])).result).toMatchObject({ revision: 3 })
})
})