@citadel-labs/citadel 0.1.0

package/dist/__tests__/integration.test.js

@@ -0,0 +1,763 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { dispatch } from '../core/fo-dispatch.js';
+import { ProcessRegistry } from '../core/process-registry.js';
+import { appendBead, readBeads, mintBeadId } from '../core/append-bead.js';
+import { handleSlotOpen } from '../core/fo-handlers/slot-open.js';
+import { handleCeilingHit } from '../core/fo-handlers/ceiling-hit.js';
+import { preSpawnCheck } from '../core/pre-spawn-check.js';
+import { applyRetryPolicy } from '../core/fo-retry-policy.js';
+import { citizenBootstrap } from '../core/citizen-bootstrap.js';
+import { nudgeFirstOfficer } from '../core/nudge.js';
+import { broadcastDependencyResolved } from '../core/fo-broadcast.js';
+import { writeCommandBead } from '../core/command-bead.js';
+import { processCommandBead } from '../core/fo-command-processor.js';
+import { reconstructState } from '../core/fo-state.js';
+import { validateTribute } from '../core/validate-tribute.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+const execFile = promisify(execFileCb);
+async function setupTempCitadel(opts) {
+    const citadelRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'citadel-int-'));
+    const outpostSlug = 'test-outpost';
+    const outpostPath = path.join(citadelRoot, 'outposts', outpostSlug);
+    // Citadel structure
+    await fs.mkdir(path.join(citadelRoot, '.citadel'), { recursive: true });
+    await fs.mkdir(path.join(citadelRoot, 'grand-archives', 'archetypes', 'software-engineer'), {
+        recursive: true,
+    });
+    await fs.mkdir(path.join(citadelRoot, 'grand-archives', 'first-officer'), {
+        recursive: true,
+    });
+    // Grand archives registry
+    await fs.writeFile(path.join(citadelRoot, 'grand-archives', 'registry.json'), JSON.stringify({
+        schema_version: '1.0',
+        archetypes: [
+            { key: 'software-engineer', description: 'Features, bugs, tests, PRs.', status: 'active' },
+        ],
+    }));
+    // First Officer config
+    await fs.writeFile(path.join(citadelRoot, 'grand-archives', 'first-officer', 'config.json'), JSON.stringify({
+        schema_version: '1.0',
+        display_name: 'First Officer',
+        singleton: true,
+        assignable: false,
+        agent: 'claude-code',
+        system_prompt_ref: 'first-officer/system-prompt.md',
+        toolset_ref: 'first-officer/toolset.json',
+        model: 'claude-opus-4',
+        constraints: { temperature: 0.2, max_tokens_per_turn: 8192 },
+        retry_policy: {
+            max_retries: 3,
+            retry_on: ['PARTIAL', 'FAILED', 'TRIBUTE_INVALID'],
+            partial_strategy: 'remaining_criteria_only',
+            on_ceiling_reached: 'ESCALATE_TO_COMMANDER',
+        },
+        nudge_retention: 500,
+    }));
+    // Outpost registry
+    const outpostRegistry = {
+        schema_version: SCHEMA_VERSION,
+        outposts: [
+            {
+                slug: outpostSlug,
+                path: outpostPath,
+                status: 'ACTIVE',
+                registered_at: new Date().toISOString(),
+                default_archetype: 'software-engineer',
+                max_citizens: opts?.maxCitizens ?? 2,
+            },
+        ],
+    };
+    await fs.writeFile(path.join(citadelRoot, '.citadel', 'outposts.json'), JSON.stringify(outpostRegistry));
+    // Nudges file (empty)
+    await fs.writeFile(path.join(citadelRoot, '.citadel', 'nudges.jsonl'), '');
+    // Outpost structure
+    await fs.mkdir(path.join(outpostPath, '.beads', 'mail'), { recursive: true });
+    await fs.mkdir(path.join(outpostPath, '.beads', 'tribute'), { recursive: true });
+    await fs.mkdir(path.join(outpostPath, 'worktrees', 'citizen'), { recursive: true });
+    // Initialize git in outpost (appendBead does git add/commit)
+    await execFile('git', ['init'], { cwd: outpostPath });
+    await execFile('git', ['config', 'user.email', 'test@citadel.dev'], { cwd: outpostPath });
+    await execFile('git', ['config', 'user.name', 'Citadel Test'], { cwd: outpostPath });
+    // Initial commit so git add/commit works
+    await fs.writeFile(path.join(outpostPath, '.gitkeep'), '');
+    await execFile('git', ['add', '.'], { cwd: outpostPath });
+    await execFile('git', ['commit', '-m', 'init'], { cwd: outpostPath });
+    // Initialize git in citadel root (nudge writes to .citadel/nudges.jsonl)
+    await execFile('git', ['init'], { cwd: citadelRoot });
+    await execFile('git', ['config', 'user.email', 'test@citadel.dev'], { cwd: citadelRoot });
+    await execFile('git', ['config', 'user.name', 'Citadel Test'], { cwd: citadelRoot });
+    await execFile('git', ['add', '.'], { cwd: citadelRoot });
+    await execFile('git', ['commit', '-m', 'init'], { cwd: citadelRoot });
+    return { citadelRoot, outpostPath, outpostSlug };
+}
+async function setupMultiOutpostCitadel(slugs) {
+    const citadelRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'citadel-multi-'));
+    await fs.mkdir(path.join(citadelRoot, '.citadel'), { recursive: true });
+    await fs.mkdir(path.join(citadelRoot, 'grand-archives', 'archetypes', 'software-engineer'), { recursive: true });
+    await fs.mkdir(path.join(citadelRoot, 'grand-archives', 'first-officer'), { recursive: true });
+    await fs.writeFile(path.join(citadelRoot, 'grand-archives', 'registry.json'), JSON.stringify({
+        schema_version: '1.0',
+        archetypes: [{ key: 'software-engineer', description: 'Features', status: 'active' }],
+    }));
+    await fs.writeFile(path.join(citadelRoot, 'grand-archives', 'first-officer', 'config.json'), JSON.stringify({
+        schema_version: '1.0', display_name: 'First Officer', singleton: true, assignable: false,
+        agent: 'claude-code', system_prompt_ref: 'first-officer/system-prompt.md',
+        toolset_ref: 'first-officer/toolset.json', model: 'claude-opus-4',
+        constraints: { temperature: 0.2, max_tokens_per_turn: 8192 },
+        retry_policy: { max_retries: 3, retry_on: ['PARTIAL', 'FAILED', 'TRIBUTE_INVALID'], partial_strategy: 'remaining_criteria_only', on_ceiling_reached: 'ESCALATE_TO_COMMANDER' },
+        nudge_retention: 500,
+    }));
+    const outposts = [];
+    const registryEntries = [];
+    for (const slug of slugs) {
+        const outpostPath = path.join(citadelRoot, 'outposts', slug);
+        await fs.mkdir(path.join(outpostPath, '.beads', 'mail'), { recursive: true });
+        await fs.mkdir(path.join(outpostPath, '.beads', 'tribute'), { recursive: true });
+        await fs.mkdir(path.join(outpostPath, 'worktrees', 'citizen'), { recursive: true });
+        await execFile('git', ['init'], { cwd: outpostPath });
+        await execFile('git', ['config', 'user.email', 'test@citadel.dev'], { cwd: outpostPath });
+        await execFile('git', ['config', 'user.name', 'Citadel Test'], { cwd: outpostPath });
+        await fs.writeFile(path.join(outpostPath, '.gitkeep'), '');
+        await execFile('git', ['add', '.'], { cwd: outpostPath });
+        await execFile('git', ['commit', '-m', 'init'], { cwd: outpostPath });
+        outposts.push({ slug, path: outpostPath });
+        registryEntries.push({
+            slug, path: outpostPath, status: 'ACTIVE',
+            registered_at: new Date().toISOString(), default_archetype: 'software-engineer', max_citizens: 2,
+        });
+    }
+    const registry = { schema_version: SCHEMA_VERSION, outposts: registryEntries };
+    await fs.writeFile(path.join(citadelRoot, '.citadel', 'outposts.json'), JSON.stringify(registry));
+    await fs.writeFile(path.join(citadelRoot, '.citadel', 'nudges.jsonl'), '');
+    await execFile('git', ['init'], { cwd: citadelRoot });
+    await execFile('git', ['config', 'user.email', 'test@citadel.dev'], { cwd: citadelRoot });
+    await execFile('git', ['config', 'user.name', 'Citadel Test'], { cwd: citadelRoot });
+    await execFile('git', ['add', '.'], { cwd: citadelRoot });
+    await execFile('git', ['commit', '-m', 'init'], { cwd: citadelRoot });
+    return { citadelRoot, outposts };
+}
+function makeTaskDescription(title) {
+    return {
+        title,
+        description: `Implement ${title}`,
+        acceptanceCriteria: ['Tests pass', 'No regressions'],
+        priority: 'MEDIUM',
+    };
+}
+// ---------------------------------------------------------------------------
+// Test 1: Parallel Citizens on same Outpost
+// ---------------------------------------------------------------------------
+describe('parallel Citizens on same Outpost', () => {
+    let env;
+    let processRegistry;
+    beforeEach(async () => {
+        env = await setupTempCitadel({ maxCitizens: 2 });
+        processRegistry = new ProcessRegistry();
+    });
+    afterEach(async () => {
+        await fs.rm(env.citadelRoot, { recursive: true, force: true });
+    });
+    it('creates 2 separate mail files with unique task_id and citizen_id', async () => {
+        const mail1 = await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('Feature A'),
+            processRegistry,
+        });
+        const mail2 = await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('Feature B'),
+            processRegistry,
+        });
+        // Verify: 2 separate mail files created in .beads/mail/
+        const mailDir = path.join(env.outpostPath, '.beads', 'mail');
+        const files = await fs.readdir(mailDir);
+        const jsonlFiles = files.filter(f => f.endsWith('.jsonl'));
+        expect(jsonlFiles).toHaveLength(2);
+        // Verify: each has unique task_id
+        expect(mail1.task_id).toBeDefined();
+        expect(mail2.task_id).toBeDefined();
+        expect(mail1.task_id).not.toBe(mail2.task_id);
+        // Verify: each has unique citizen_id in spawn_hint
+        expect(mail1.spawn_hint?.citizen_id).toBeDefined();
+        expect(mail2.spawn_hint?.citizen_id).toBeDefined();
+        expect(mail1.spawn_hint.citizen_id).not.toBe(mail2.spawn_hint.citizen_id);
+        // Verify: both are TASK_ASSIGNMENT, unread
+        expect(mail1.mail_type).toBe('TASK_ASSIGNMENT');
+        expect(mail2.mail_type).toBe('TASK_ASSIGNMENT');
+        expect(mail1.read).toBe(false);
+        expect(mail2.read).toBe(false);
+        // Read back from disk to confirm persistence
+        const beads1 = await readBeads(path.join(mailDir, `${mail1.task_id}.jsonl`));
+        const beads2 = await readBeads(path.join(mailDir, `${mail2.task_id}.jsonl`));
+        expect(beads1).toHaveLength(1);
+        expect(beads2).toHaveLength(1);
+        expect(beads1[0].bead_id).toBe(mail1.bead_id);
+        expect(beads2[0].bead_id).toBe(mail2.bead_id);
+    });
+    it('dispatches a 3rd task when ceiling is hit — mail is still queued', async () => {
+        // Dispatch 2 tasks to fill the ceiling
+        await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('Task 1'),
+            processRegistry,
+        });
+        await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('Task 2'),
+            processRegistry,
+        });
+        // Register fake processes so processRegistry.countActive returns 2
+        processRegistry.set(env.outpostSlug, 'citizen-fake-1', {
+            pid: process.pid,
+            spawned_at: new Date().toISOString(),
+            worktree_path: '/tmp/wt1',
+            task_id: 'task-1',
+        });
+        processRegistry.set(env.outpostSlug, 'citizen-fake-2', {
+            pid: process.pid,
+            spawned_at: new Date().toISOString(),
+            worktree_path: '/tmp/wt2',
+            task_id: 'task-2',
+        });
+        expect(processRegistry.countActive(env.outpostSlug)).toBe(2);
+        // Dispatch 3rd task — should still write mail (queued), not throw
+        const mail3 = await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('Task 3'),
+            processRegistry,
+        });
+        expect(mail3.task_id).toBeDefined();
+        expect(mail3.mail_type).toBe('TASK_ASSIGNMENT');
+        // 3 mail files total
+        const mailDir = path.join(env.outpostPath, '.beads', 'mail');
+        const files = await fs.readdir(mailDir);
+        const jsonlFiles = files.filter(f => f.endsWith('.jsonl'));
+        expect(jsonlFiles).toHaveLength(3);
+    });
+});
+// ---------------------------------------------------------------------------
+// Test 2: Ceiling hit -> slot opens -> pending dispatched
+// ---------------------------------------------------------------------------
+describe('ceiling hit and slot-open auto-dispatch', () => {
+    let env;
+    let processRegistry;
+    beforeEach(async () => {
+        env = await setupTempCitadel({ maxCitizens: 1 });
+        processRegistry = new ProcessRegistry();
+    });
+    afterEach(async () => {
+        await fs.rm(env.citadelRoot, { recursive: true, force: true });
+    });
+    it('ceiling blocks spawn, then slot-open unblocks after tribute', async () => {
+        const outpostEntry = {
+            slug: env.outpostSlug,
+            path: env.outpostPath,
+            status: 'ACTIVE',
+            registered_at: new Date().toISOString(),
+            default_archetype: 'software-engineer',
+            max_citizens: 1,
+        };
+        // Dispatch 1 task — fills the single slot
+        const mail1 = await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('First task'),
+            processRegistry,
+        });
+        // Register a fake process for that citizen (simulates running citizen)
+        const citizenId1 = mail1.spawn_hint.citizen_id;
+        processRegistry.set(env.outpostSlug, citizenId1, {
+            pid: process.pid,
+            spawned_at: new Date().toISOString(),
+            worktree_path: path.join(env.outpostPath, 'worktrees', 'citizen', mail1.task_id),
+            task_id: mail1.task_id,
+        });
+        // Dispatch 2nd task — mail is written (queued), but ceiling is hit
+        const mail2 = await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('Second task'),
+            processRegistry,
+        });
+        expect(mail2.task_id).toBeDefined();
+        // preSpawnCheck should report ceiling hit (1 active, max 1)
+        const checkBlocked = await preSpawnCheck(env.citadelRoot, outpostEntry, processRegistry, 1);
+        expect(checkBlocked.canSpawn).toBe(false);
+        expect(checkBlocked.reason).toMatch(/Ceiling/i);
+        expect(checkBlocked.taskMail).not.toBeNull();
+        // handleCeilingHit logs the contention (should not throw)
+        const ceilingNudge = {
+            bead_id: mintBeadId(),
+            bead_type: 'NUDGE',
+            schema_version: SCHEMA_VERSION,
+            created_at: new Date().toISOString(),
+            signal_type: 'PARALLELISM_CEILING_HIT',
+            payload: {
+                outpost: env.outpostSlug,
+                active_count: 1,
+                ceiling: 1,
+            },
+            processed: false,
+        };
+        await handleCeilingHit(ceilingNudge);
+        // Now: write a SUCCESS tribute for the first task
+        const tribute = {
+            bead_id: mintBeadId(),
+            bead_type: 'TRIBUTE',
+            schema_version: SCHEMA_VERSION,
+            created_at: new Date().toISOString(),
+            citizen_id: citizenId1,
+            task_id: mail1.task_id,
+            originating_mail_ref: mail1.bead_id,
+            archetype: 'software-engineer',
+            outpost: env.outpostSlug,
+            worktree: `worktrees/citizen/${mail1.task_id}`,
+            attempt: 1,
+            status: 'SUCCESS',
+            summary: 'All tests pass',
+            artifacts: ['src/feature.ts'],
+            acceptance_met: [true, true],
+            elapsed_seconds: 120,
+        };
+        const tributePath = path.join(env.outpostPath, '.beads', 'tribute', `${mail1.task_id}_tribute.jsonl`);
+        await appendBead(tributePath, tribute);
+        // Create TRIBUTE_WRITTEN nudge
+        const tributeNudge = {
+            bead_id: mintBeadId(),
+            bead_type: 'NUDGE',
+            schema_version: SCHEMA_VERSION,
+            created_at: new Date().toISOString(),
+            signal_type: 'TRIBUTE_WRITTEN',
+            payload: {
+                outpost: env.outpostSlug,
+                tribute_bead_id: tribute.bead_id,
+                task_id: mail1.task_id,
+                worktree: tribute.worktree,
+            },
+            processed: false,
+        };
+        // Call handleSlotOpen — should log slot opening with pending count
+        await handleSlotOpen(tributeNudge, env.citadelRoot);
+        // Remove the fake process from registry (simulating citizen exit)
+        processRegistry.delete(env.outpostSlug, citizenId1);
+        expect(processRegistry.countActive(env.outpostSlug)).toBe(0);
+        // Now preSpawnCheck should return canSpawn=true for the remaining mail
+        const checkUnblocked = await preSpawnCheck(env.citadelRoot, outpostEntry, processRegistry, 1);
+        expect(checkUnblocked.canSpawn).toBe(true);
+        expect(checkUnblocked.taskMail).not.toBeNull();
+        expect(checkUnblocked.taskMail.mail_type).toBe('TASK_ASSIGNMENT');
+    });
+});
+// ---------------------------------------------------------------------------
+// Test 3: Retry with inherited worktree
+// ---------------------------------------------------------------------------
+describe('retry with inherited worktree', () => {
+    let env;
+    let processRegistry;
+    const savedEnv = {};
+    beforeEach(async () => {
+        env = await setupTempCitadel({ maxCitizens: 2 });
+        processRegistry = new ProcessRegistry();
+        // Save env vars we will set
+        for (const key of [
+            'CITADEL_CITIZEN_ID',
+            'CITADEL_BEADS_ROOT',
+            'CITADEL_OUTPOST',
+            'CITADEL_TASK_ID',
+            'CITADEL_WORKTREE',
+        ]) {
+            savedEnv[key] = process.env[key];
+        }
+    });
+    afterEach(async () => {
+        // Restore env vars
+        for (const [key, val] of Object.entries(savedEnv)) {
+            if (val === undefined) {
+                delete process.env[key];
+            }
+            else {
+                process.env[key] = val;
+            }
+        }
+        await fs.rm(env.citadelRoot, { recursive: true, force: true });
+    });
+    it('PARTIAL tribute triggers retry and bootstrap detects isRetry with errors', async () => {
+        // 1. Dispatch a task
+        const mail = await dispatch({
+            citadelRoot: env.citadelRoot,
+            outpostSlug: env.outpostSlug,
+            task: makeTaskDescription('Retry Feature'),
+            processRegistry,
+        });
+        const taskId = mail.task_id;
+        const citizenId = mail.spawn_hint.citizen_id;
+        // 2. Write a PARTIAL tribute (attempt 1, some acceptance criteria not met)
+        const tribute = {
+            bead_id: mintBeadId(),
+            bead_type: 'TRIBUTE',
+            schema_version: SCHEMA_VERSION,
+            created_at: new Date().toISOString(),
+            citizen_id: citizenId,
+            task_id: taskId,
+            originating_mail_ref: mail.bead_id,
+            archetype: 'software-engineer',
+            outpost: env.outpostSlug,
+            worktree: `worktrees/citizen/${taskId}`,
+            attempt: 1,
+            status: 'PARTIAL',
+            summary: 'Tests pass but regressions found',
+            artifacts: ['src/feature.ts'],
+            acceptance_met: [true, false], // second criterion not met
+            elapsed_seconds: 90,
+        };
+        const tributePath = path.join(env.outpostPath, '.beads', 'tribute', `${taskId}_tribute.jsonl`);
+        await appendBead(tributePath, tribute);
+        // 3. Create a TRIBUTE_WRITTEN nudge bead
+        const nudgeBead = await nudgeFirstOfficer(env.citadelRoot, 'TRIBUTE_WRITTEN', {
+            outpost: env.outpostSlug,
+            tribute_bead_id: tribute.bead_id,
+            task_id: taskId,
+            worktree: tribute.worktree,
+        });
+        // 4. Apply retry policy
+        const result = await applyRetryPolicy(env.citadelRoot, nudgeBead);
+        // 5. Verify: decision is 'retry'
+        expect(result.decision).toBe('retry');
+        expect(result.tribute.bead_id).toBe(tribute.bead_id);
+        expect(result.errors.length).toBeGreaterThan(0);
+        // 6. Verify: TRIBUTE_INVALID mail was written to .beads/mail/
+        const mailDir = path.join(env.outpostPath, '.beads', 'mail');
+        const mailFiles = await fs.readdir(mailDir);
+        const invalidFiles = mailFiles.filter(f => f.startsWith('invalid-'));
+        expect(invalidFiles).toHaveLength(1);
+        const invalidBeads = await readBeads(path.join(mailDir, invalidFiles[0]));
+        expect(invalidBeads).toHaveLength(1);
+        expect(invalidBeads[0].mail_type).toBe('TRIBUTE_INVALID');
+        expect(invalidBeads[0].task_id).toBe(taskId);
+        const invalidPayload = invalidBeads[0].payload;
+        expect(invalidPayload.errors.length).toBeGreaterThan(0);
+        // 7. Verify: a retry TASK_ASSIGNMENT mail was written (has retry_of set)
+        const retryFiles = mailFiles.filter(f => f.startsWith('retry-'));
+        expect(retryFiles).toHaveLength(1);
+        const retryBeads = await readBeads(path.join(mailDir, retryFiles[0]));
+        expect(retryBeads).toHaveLength(1);
+        expect(retryBeads[0].mail_type).toBe('TASK_ASSIGNMENT');
+        expect(retryBeads[0].retry_of).toBe(mail.bead_id);
+        const retryMail = retryBeads[0];
+        const retryCitizenId = retryMail.spawn_hint.citizen_id;
+        // 8. Simulate citizen bootstrap in retry: set env vars
+        process.env.CITADEL_CITIZEN_ID = retryCitizenId;
+        process.env.CITADEL_BEADS_ROOT = env.citadelRoot;
+        process.env.CITADEL_OUTPOST = env.outpostSlug;
+        process.env.CITADEL_TASK_ID = taskId;
+        process.env.CITADEL_WORKTREE = `worktrees/citizen/${taskId}`;
+        const ctx = await citizenBootstrap();
+        // 9. Verify: bootstrap detects isRetry=true with retryErrors from TRIBUTE_INVALID
+        expect(ctx.isRetry).toBe(true);
+        expect(ctx.retryErrors.length).toBeGreaterThan(0);
+        expect(ctx.taskAssignment).not.toBeNull();
+        expect(ctx.taskAssignment.mail_type).toBe('TASK_ASSIGNMENT');
+        expect(ctx.citizenId).toBe(retryCitizenId);
+        expect(ctx.worktree).toBe(`worktrees/citizen/${taskId}`);
+    });
+});
+// ---------------------------------------------------------------------------
+// Test 4: 2-Outpost dependency chain with DEPENDENCY_RESOLVED broadcast
+// ---------------------------------------------------------------------------
+describe('2-Outpost dependency chain', () => {
+    let multi;
+    let processRegistry;
+    beforeEach(async () => {
+        multi = await setupMultiOutpostCitadel(['backend', 'frontend']);
+        processRegistry = new ProcessRegistry();
+    });
+    afterEach(async () => {
+        await fs.rm(multi.citadelRoot, { recursive: true, force: true });
+    });
+    it('backend SUCCESS triggers DEPENDENCY_RESOLVED to frontend', async () => {
+        const backend = multi.outposts.find(o => o.slug === 'backend');
+        const frontend = multi.outposts.find(o => o.slug === 'frontend');
+        // 1. Dispatch backend task (no dependencies)
+        const backendMail = await dispatch({
+            citadelRoot: multi.citadelRoot,
+            outpostSlug: 'backend',
+            task: {
+                title: 'Build API endpoint',
+                description: 'Create /api/users endpoint',
+                acceptanceCriteria: ['Tests pass'],
+            },
+            processRegistry,
+        });
+        const backendTaskId = backendMail.task_id;
+        // 2. Dispatch frontend task WITH dependency on backend task
+        const frontendMail = await dispatch({
+            citadelRoot: multi.citadelRoot,
+            outpostSlug: 'frontend',
+            task: {
+                title: 'Build user list UI',
+                description: 'Create user list component consuming /api/users',
+                acceptanceCriteria: ['Renders users'],
+                dependencies: [backendTaskId],
+            },
+            processRegistry,
+        });
+        const frontendTaskId = frontendMail.task_id;
+        // Verify: frontend mail has dependency on backend task
+        const frontendPayload = frontendMail.payload;
+        expect(frontendPayload.dependencies).toContain(backendTaskId);
+        // 3. Backend completes — write SUCCESS tribute
+        const backendTribute = {
+            bead_id: mintBeadId(),
+            bead_type: 'TRIBUTE',
+            schema_version: SCHEMA_VERSION,
+            created_at: new Date().toISOString(),
+            citizen_id: backendMail.spawn_hint.citizen_id,
+            task_id: backendTaskId,
+            originating_mail_ref: backendMail.bead_id,
+            archetype: 'software-engineer',
+            outpost: 'backend',
+            worktree: `worktrees/citizen/${backendTaskId}`,
+            attempt: 1,
+            status: 'SUCCESS',
+            pr_url: 'https://github.com/org/repo/pull/10',
+            summary: 'API endpoint /api/users implemented with tests',
+            artifacts: ['src/api/users.ts', 'src/api/users.test.ts'],
+            acceptance_met: [true],
+            elapsed_seconds: 180,
+        };
+        const tributePath = path.join(backend.path, '.beads', 'tribute', `${backendTaskId}_tribute.jsonl`);
+        await appendBead(tributePath, backendTribute);
+        // 4. First Officer broadcasts DEPENDENCY_RESOLVED
+        const broadcastResult = await broadcastDependencyResolved(multi.citadelRoot, backendTribute);
+        // 5. Verify: exactly 1 DEPENDENCY_RESOLVED sent to frontend
+        expect(broadcastResult.sent).toBe(1);
+        expect(broadcastResult.recipients).toHaveLength(1);
+        expect(broadcastResult.recipients[0].outpost).toBe('frontend');
+        expect(broadcastResult.recipients[0].taskId).toBe(frontendTaskId);
+        // 6. Verify: DEPENDENCY_RESOLVED mail file exists in frontend's .beads/mail/
+        const frontendMailDir = path.join(frontend.path, '.beads', 'mail');
+        const frontendFiles = await fs.readdir(frontendMailDir);
+        const depResFiles = frontendFiles.filter(f => f.startsWith('depres-'));
+        expect(depResFiles).toHaveLength(1);
+        // 7. Verify: mail contents
+        const depResMails = await readBeads(path.join(frontendMailDir, depResFiles[0]));
+        expect(depResMails).toHaveLength(1);
+        const depRes = depResMails[0];
+        expect(depRes.mail_type).toBe('DEPENDENCY_RESOLVED');
+        expect(depRes.task_id).toBe(frontendTaskId);
+        expect(depRes.to).toBe('frontend');
+        expect(depRes.from).toBe('citadel');
+        const depPayload = depRes.payload;
+        expect(depPayload.resolved_task_id).toBe(backendTaskId);
+        expect(depPayload.resolved_by_outpost).toBe('backend');
+        expect(depPayload.tribute_ref).toBe(backendTribute.bead_id);
+        expect(depPayload.pr_url).toBe('https://github.com/org/repo/pull/10');
+        expect(depPayload.summary).toBe('API endpoint /api/users implemented with tests');
+        // 8. Verify: no DEPENDENCY_RESOLVED sent to backend (it has no dependencies)
+        const backendMailDir = path.join(backend.path, '.beads', 'mail');
+        const backendFiles = await fs.readdir(backendMailDir);
+        const backendDepRes = backendFiles.filter(f => f.startsWith('depres-'));
+        expect(backendDepRes).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// Test 5: Concurrent writes stress test — lockfile correctness
+// ---------------------------------------------------------------------------
+describe('concurrent writes stress test', () => {
+    let env;
+    beforeEach(async () => {
+        env = await setupTempCitadel({ maxCitizens: 10 });
+    });
+    afterEach(async () => {
+        await fs.rm(env.citadelRoot, { recursive: true, force: true });
+    });
+    it('concurrent appendBead calls to separate files — no data corruption', async () => {
+        const mailDir = path.join(env.outpostPath, '.beads', 'mail');
+        const count = 10;
+        // Fire all appends in parallel — each to a separate file (realistic scenario:
+        // multiple dispatches create separate mail files concurrently)
+        const promises = Array.from({ length: count }, (_, i) => {
+            const filePath = path.join(mailDir, `stress-${i}.jsonl`);
+            const bead = {
+                bead_id: `bead-stress-${i}`,
+                bead_type: 'MAIL',
+                schema_version: SCHEMA_VERSION,
+                created_at: new Date().toISOString(),
+                task_id: `task-stress-${i}`,
+                mail_type: 'TASK_ASSIGNMENT',
+                from: 'citadel',
+                to: env.outpostSlug,
+                subject: `Stress test ${i}`,
+                read: false,
+                retry_of: null,
+                payload: {
+                    archetype: 'software-engineer',
+                    citizen_id: `citizen-stress-${i}`,
+                    priority: 'MEDIUM',
+                    title: `Stress ${i}`,
+                    description: `Concurrent write ${i}`,
+                    acceptance_criteria: [],
+                    context_refs: [],
+                    dependencies: [],
+                    timeout_seconds: 1800,
+                },
+            };
+            return appendBead(filePath, bead);
+        });
+        const results = await Promise.all(promises);
+        // All 10 should have resolved
+        expect(results).toHaveLength(count);
+        // Read back each file and verify no data corruption
+        for (let i = 0; i < count; i++) {
+            const filePath = path.join(mailDir, `stress-${i}.jsonl`);
+            const beads = await readBeads(filePath);
+            expect(beads).toHaveLength(1);
+            expect(beads[0].bead_id).toBe(`bead-stress-${i}`);
+            // Verify valid JSON (no corruption from concurrent writes)
+            const raw = await fs.readFile(filePath, 'utf-8');
+            const lines = raw.split('\n').filter(l => l.trim() !== '');
+            expect(lines).toHaveLength(1);
+            expect(() => JSON.parse(lines[0])).not.toThrow();
+        }
+        // Verify total file count
+        const allFiles = (await fs.readdir(mailDir)).filter(f => f.startsWith('stress-'));
+        expect(allFiles).toHaveLength(count);
+    });
+    it('sequential writes to same file maintain data integrity', async () => {
+        const filePath = path.join(env.outpostPath, '.beads', 'mail', 'seq-stress.jsonl');
+        const count = 8;
+        // Sequential writes — each waits for the prior to finish
+        for (let i = 0; i < count; i++) {
+            const bead = {
+                bead_id: `bead-seq-${i}`,
+                bead_type: 'MAIL',
+                schema_version: SCHEMA_VERSION,
+                created_at: new Date().toISOString(),
+                task_id: `task-seq-${i}`,
+                mail_type: 'TASK_ASSIGNMENT',
+                from: 'citadel',
+                to: env.outpostSlug,
+                subject: `Sequential ${i}`,
+                read: false,
+                retry_of: null,
+                payload: {
+                    archetype: 'software-engineer',
+                    citizen_id: `citizen-seq-${i}`,
+                    priority: 'MEDIUM',
+                    title: `Seq ${i}`,
+                    description: `Sequential write ${i}`,
+                    acceptance_criteria: [],
+                    context_refs: [],
+                    dependencies: [],
+                    timeout_seconds: 1800,
+                },
+            };
+            await appendBead(filePath, bead);
+        }
+        // Read back
+        const beads = await readBeads(filePath);
+        expect(beads).toHaveLength(count);
+        // Verify order preserved (sequential guarantees order)
+        for (let i = 0; i < count; i++) {
+            expect(beads[i].bead_id).toBe(`bead-seq-${i}`);
+        }
+        // Verify no corruption
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const lines = raw.split('\n').filter(l => l.trim() !== '');
+        expect(lines).toHaveLength(count);
+        for (const line of lines) {
+            expect(() => JSON.parse(line)).not.toThrow();
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// Test 6: Headless full cycle — no Commander attached
+// ---------------------------------------------------------------------------
+describe('headless full cycle', () => {
+    let env;
+    let processRegistry;
+    beforeEach(async () => {
+        env = await setupTempCitadel({ maxCitizens: 2 });
+        processRegistry = new ProcessRegistry();
+        // Create commands dir
+        await fs.mkdir(path.join(env.citadelRoot, '.citadel', 'commands'), { recursive: true });
+    });
+    afterEach(async () => {
+        await fs.rm(env.citadelRoot, { recursive: true, force: true });
+    });
+    it('Command Bead -> dispatch -> Tribute -> state reconstruction, all headless', async () => {
+        // 1. Write a dispatch Command Bead (simulates CLI / API, no Commander)
+        const cmdBead = await writeCommandBead(env.citadelRoot, 'dispatch', {
+            outpost: env.outpostSlug,
+            task: 'Headless feature implementation',
+        });
+        expect(cmdBead.bead_type).toBe('COMMAND');
+        expect(cmdBead.command).toBe('dispatch');
+        expect(cmdBead.processed).toBe(false);
+        // 2. FO processes the command bead — dispatches task
+        await processCommandBead(env.citadelRoot, cmdBead, processRegistry);
+        // 3. Verify: TASK_ASSIGNMENT mail exists in outpost
+        const mailDir = path.join(env.outpostPath, '.beads', 'mail');
+        const mailFiles = (await fs.readdir(mailDir)).filter(f => f.endsWith('.jsonl'));
+        expect(mailFiles.length).toBeGreaterThanOrEqual(1);
+        // Read the dispatched mail
+        const allMails = [];
+        for (const file of mailFiles) {
+            const beads = await readBeads(path.join(mailDir, file));
+            allMails.push(...beads);
+        }
+        const taskMail = allMails.find(m => m.mail_type === 'TASK_ASSIGNMENT');
+        expect(taskMail).toBeDefined();
+        const taskId = taskMail.task_id;
+        const citizenId = taskMail.spawn_hint.citizen_id;
+        // 4. Simulate citizen work — write SUCCESS tribute
+        const tribute = {
+            bead_id: mintBeadId(),
+            bead_type: 'TRIBUTE',
+            schema_version: SCHEMA_VERSION,
+            created_at: new Date().toISOString(),
+            citizen_id: citizenId,
+            task_id: taskId,
+            originating_mail_ref: taskMail.bead_id,
+            archetype: 'software-engineer',
+            outpost: env.outpostSlug,
+            worktree: `worktrees/citizen/${taskId}`,
+            attempt: 1,
+            status: 'SUCCESS',
+            summary: 'Feature implemented and tested',
+            artifacts: ['src/headless.ts'],
+            acceptance_met: [],
+            elapsed_seconds: 200,
+        };
+        const tributePath = path.join(env.outpostPath, '.beads', 'tribute', `${taskId}_tribute.jsonl`);
+        await appendBead(tributePath, tribute);
+        // 5. Validate tribute against task mail (acceptance_criteria is [] from dispatch)
+        const validation = validateTribute(tribute, taskMail);
+        expect(validation.valid).toBe(true);
+        expect(validation.errors).toHaveLength(0);
+        // 6. Reconstruct state — verify task shows as succeeded
+        const state = await reconstructState(env.citadelRoot);
+        expect(state.tasks.length).toBeGreaterThanOrEqual(1);
+        const task = state.tasks.find(t => t.taskId === taskId);
+        expect(task).toBeDefined();
+        expect(task.state).toBe('succeeded');
+        expect(task.outpost).toBe(env.outpostSlug);
+        expect(task.tributes).toHaveLength(1);
+        expect(task.latestTribute.status).toBe('SUCCESS');
+        expect(task.attempt).toBe(1);
+        // 7. Verify succeeded list
+        expect(state.succeeded.map(t => t.taskId)).toContain(taskId);
+        expect(state.inFlight.map(t => t.taskId)).not.toContain(taskId);
+    });
+});
+//# sourceMappingURL=integration.test.js.map