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.

47.4 KB
Raw Blame
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 })
  })
})