@citadel-labs/citadel 0.1.0

package/dist/core/fo-dispatch.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { nanoid } from 'nanoid';
+import { appendBead, mintBeadId } from './append-bead.js';
+import { GrandArchives } from './grand-archives.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+/**
+ * First Officer dispatch: select archetype, mint citizen_id, compose TASK_ASSIGNMENT mail,
+ * write to outpost inbox. Respects max_citizens ceiling.
+ */
+export async function dispatch(opts) {
+    const { citadelRoot, outpostSlug, task, processRegistry } = opts;
+    // Resolve outpost from registry
+    const outpostsPath = path.join(citadelRoot, '.citadel', 'outposts.json');
+    const raw = await fs.readFile(outpostsPath, 'utf-8');
+    const registry = JSON.parse(raw);
+    const outpost = registry.outposts.find((o) => o.slug === outpostSlug);
+    if (!outpost)
+        throw new Error(`Outpost "${outpostSlug}" not found`);
+    // Check ceiling
+    const maxCitizens = outpost.max_citizens ?? 3;
+    const activeCount = processRegistry.countActive(outpostSlug);
+    if (activeCount >= maxCitizens) {
+        console.log(`[FO dispatch] Ceiling reached for "${outpostSlug}": ${activeCount}/${maxCitizens}. Mail queued in inbox.`);
+    }
+    // Select archetype
+    let archetypeKey = opts.archetype ?? outpost.default_archetype;
+    if (!archetypeKey) {
+        // Auto-select: use first active archetype from registry
+        const archives = new GrandArchives(citadelRoot);
+        const archetypeRegistry = await archives.listArchetypes();
+        const active = archetypeRegistry.archetypes.find(a => a.status === 'active');
+        if (!active)
+            throw new Error('No active archetypes in registry');
+        archetypeKey = active.key;
+    }
+    // Mint citizen_id
+    const citizenId = `citizen-${nanoid()}`;
+    const taskId = `task-${nanoid()}`;
+    // Compose TASK_ASSIGNMENT mail
+    const payload = {
+        archetype: archetypeKey,
+        citizen_id: citizenId,
+        priority: task.priority ?? 'MEDIUM',
+        title: task.title,
+        description: task.description,
+        acceptance_criteria: task.acceptanceCriteria,
+        context_refs: task.contextRefs ?? [],
+        dependencies: task.dependencies ?? [],
+        timeout_seconds: task.timeoutSeconds ?? 1800,
+    };
+    const mail = {
+        bead_id: mintBeadId('MAIL'),
+        bead_type: 'MAIL',
+        schema_version: SCHEMA_VERSION,
+        created_at: new Date().toISOString(),
+        task_id: taskId,
+        mail_type: 'TASK_ASSIGNMENT',
+        from: 'citadel',
+        to: outpostSlug,
+        subject: task.title,
+        read: false,
+        retry_of: null,
+        spawn_hint: {
+            archetype: archetypeKey,
+            citizen_id: citizenId,
+        },
+        payload,
+    };
+    // Write to outpost inbox
+    const mailPath = path.join(outpost.path, '.beads', 'mail', `${taskId}.jsonl`);
+    await appendBead(mailPath, mail);
+    console.log(`[FO dispatch] Task "${task.title}" -> outpost "${outpostSlug}" (citizen: ${citizenId}, archetype: ${archetypeKey})`);
+    return mail;
+}
+//# sourceMappingURL=fo-dispatch.js.map

package/dist/core/fo-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-dispatch.js","sourceRoot":"","sources":["../../src/core/fo-dispatch.ts"],"names":[],"mappings":"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"}

package/dist/core/fo-escalation.d.ts

@@ -0,0 +1,20 @@
+import type { TributeBead, ResolveAction } from '../types/index.js';
+export interface EscalationReport {
+    taskId: string;
+    outpost: string;
+    attempts: TributeBead[];
+    lastStatus: string;
+    recommendation: string;
+}
+/**
+ * Build an escalation report for a task that has hit the retry ceiling.
+ */
+export declare function buildEscalationReport(citadelRoot: string, taskId: string): Promise<EscalationReport>;
+/**
+ * Resolve a task per Commander decision:
+ * - retry: override ceiling for one more attempt
+ * - abandon: log closure, no further action
+ * - rewrite: new TASK_ASSIGNMENT with Commander note
+ */
+export declare function resolveTask(citadelRoot: string, taskId: string, action: ResolveAction, note?: string): Promise<void>;
+//# sourceMappingURL=fo-escalation.d.ts.map

package/dist/core/fo-escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-escalation.d.ts","sourceRoot":"","sources":["../../src/core/fo-escalation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,WAAW,EAAmB,aAAa,EAAyB,MAAM,mBAAmB,CAAC;AAEtH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,CAAC,CAiB3B;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAmDf"}

package/dist/core/fo-escalation.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { appendBead, mintBeadId } from './append-bead.js';
+import { reconstructState } from './fo-state.js';
+/**
+ * Build an escalation report for a task that has hit the retry ceiling.
+ */
+export async function buildEscalationReport(citadelRoot, taskId) {
+    const state = await reconstructState(citadelRoot);
+    const task = state.tasks.find(t => t.taskId === taskId);
+    if (!task)
+        throw new Error(`Task "${taskId}" not found`);
+    const lastStatus = task.latestTribute?.status ?? 'unknown';
+    const recommendation = lastStatus === 'PARTIAL'
+        ? 'Consider retry with adjusted criteria or rewrite the task'
+        : 'Consider abandoning or rewriting with different approach';
+    return {
+        taskId,
+        outpost: task.outpost,
+        attempts: task.tributes,
+        lastStatus,
+        recommendation,
+    };
+}
+/**
+ * Resolve a task per Commander decision:
+ * - retry: override ceiling for one more attempt
+ * - abandon: log closure, no further action
+ * - rewrite: new TASK_ASSIGNMENT with Commander note
+ */
+export async function resolveTask(citadelRoot, taskId, action, note) {
+    const state = await reconstructState(citadelRoot);
+    const task = state.tasks.find(t => t.taskId === taskId);
+    if (!task)
+        throw new Error(`Task "${taskId}" not found`);
+    const outpostsPath = path.join(citadelRoot, '.citadel', 'outposts.json');
+    const raw = await fs.readFile(outpostsPath, 'utf-8');
+    const registry = JSON.parse(raw);
+    const outpost = registry.outposts.find(o => o.slug === task.outpost);
+    if (!outpost)
+        throw new Error(`Outpost "${task.outpost}" not found`);
+    switch (action) {
+        case 'retry': {
+            // Override ceiling: re-issue TASK_ASSIGNMENT with retry_of
+            const retryMail = {
+                ...task.assignmentMail,
+                bead_id: mintBeadId('MAIL'),
+                created_at: new Date().toISOString(),
+                read: false,
+                retry_of: task.assignmentMail.bead_id,
+            };
+            const mailPath = path.join(outpost.path, '.beads', 'mail', `resolve-retry-${retryMail.bead_id}.jsonl`);
+            await appendBead(mailPath, retryMail);
+            console.log(`[FO] Ceiling override retry for task "${taskId}"`);
+            break;
+        }
+        case 'abandon': {
+            console.log(`[FO] Task "${taskId}" abandoned by Commander${note ? `: ${note}` : ''}`);
+            break;
+        }
+        case 'rewrite': {
+            // New TASK_ASSIGNMENT with note appended to description
+            const origPayload = task.assignmentMail.payload;
+            const newMail = {
+                ...task.assignmentMail,
+                bead_id: mintBeadId('MAIL'),
+                created_at: new Date().toISOString(),
+                read: false,
+                retry_of: null,
+                subject: `[REWRITE] ${task.assignmentMail.subject}`,
+                payload: {
+                    ...origPayload,
+                    description: `${origPayload.description}\n\n[Commander rewrite note]: ${note ?? 'No additional notes.'}`,
+                },
+            };
+            const mailPath = path.join(outpost.path, '.beads', 'mail', `rewrite-${newMail.bead_id}.jsonl`);
+            await appendBead(mailPath, newMail);
+            console.log(`[FO] Task "${taskId}" rewritten by Commander${note ? `: ${note}` : ''}`);
+            break;
+        }
+    }
+}
+//# sourceMappingURL=fo-escalation.js.map

package/dist/core/fo-escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-escalation.js","sourceRoot":"","sources":["../../src/core/fo-escalation.ts"],"names":[],"mappings":"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"}

package/dist/core/fo-handlers/ceiling-hit.d.ts

@@ -0,0 +1,8 @@
+import type { NudgeBead } from '../../types/index.js';
+/**
+ * Handle PARALLELISM_CEILING_HIT nudge.
+ * Log contention and do nothing — pending work stays in inbox.
+ * Dispatch resumes automatically when a slot opens via TRIBUTE_WRITTEN SUCCESS.
+ */
+export declare function handleCeilingHit(nudge: NudgeBead): Promise<void>;
+//# sourceMappingURL=ceiling-hit.d.ts.map

package/dist/core/fo-handlers/ceiling-hit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceiling-hit.d.ts","sourceRoot":"","sources":["../../../src/core/fo-handlers/ceiling-hit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAgC,MAAM,sBAAsB,CAAC;AAEpF;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAKtE"}

package/dist/core/fo-handlers/ceiling-hit.js

@@ -0,0 +1,10 @@
+/**
+ * Handle PARALLELISM_CEILING_HIT nudge.
+ * Log contention and do nothing — pending work stays in inbox.
+ * Dispatch resumes automatically when a slot opens via TRIBUTE_WRITTEN SUCCESS.
+ */
+export async function handleCeilingHit(nudge) {
+    const payload = nudge.payload;
+    console.log(`[FO] Ceiling hit on outpost "${payload.outpost}": ${payload.active_count}/${payload.ceiling} active citizens. Pending work queued.`);
+}
+//# sourceMappingURL=ceiling-hit.js.map

package/dist/core/fo-handlers/ceiling-hit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceiling-hit.js","sourceRoot":"","sources":["../../../src/core/fo-handlers/ceiling-hit.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAgB;IACrD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAuC,CAAC;IAC9D,OAAO,CAAC,GAAG,CACT,gCAAgC,OAAO,CAAC,OAAO,MAAM,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,OAAO,wCAAwC,CACrI,CAAC;AACJ,CAAC"}

package/dist/core/fo-handlers/slot-open.d.ts

@@ -0,0 +1,13 @@
+import { ProcessRegistry } from '../process-registry.js';
+import type { NudgeBead } from '../../types/index.js';
+export interface SlotOpenResult {
+    dispatched: boolean;
+    taskId?: string;
+}
+/**
+ * Handle TRIBUTE_WRITTEN nudge — slot-open dispatch.
+ * On SUCCESS: check for pending TASK_ASSIGNMENT mail and dispatch if under ceiling.
+ * PRD §3.3.3/§3.3.4
+ */
+export declare function handleSlotOpen(nudge: NudgeBead, citadelRoot: string, processRegistry?: ProcessRegistry): Promise<SlotOpenResult | undefined>;
+//# sourceMappingURL=slot-open.d.ts.map

package/dist/core/fo-handlers/slot-open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-open.d.ts","sourceRoot":"","sources":["../../../src/core/fo-handlers/slot-open.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAuF,MAAM,sBAAsB,CAAC;AAE3I,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAyDrC"}

package/dist/core/fo-handlers/slot-open.js

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { readBeads } from '../append-bead.js';
+/**
+ * Handle TRIBUTE_WRITTEN nudge — slot-open dispatch.
+ * On SUCCESS: check for pending TASK_ASSIGNMENT mail and dispatch if under ceiling.
+ * PRD §3.3.3/§3.3.4
+ */
+export async function handleSlotOpen(nudge, citadelRoot, processRegistry) {
+    const payload = nudge.payload;
+    // Read the tribute to check status
+    const outpostsPath = path.join(citadelRoot, '.citadel', 'outposts.json');
+    let outpostEntry;
+    let outpostPath = '';
+    try {
+        const raw = await fs.readFile(outpostsPath, 'utf-8');
+        const registry = JSON.parse(raw);
+        outpostEntry = registry.outposts.find(o => o.slug === payload.outpost);
+        if (outpostEntry)
+            outpostPath = outpostEntry.path;
+    }
+    catch {
+        return;
+    }
+    if (!outpostPath || !outpostEntry)
+        return;
+    // Read tribute file
+    const tributePath = path.join(outpostPath, '.beads', 'tribute', `${payload.task_id}_tribute.jsonl`);
+    const tributes = await readBeads(tributePath);
+    const latest = tributes[tributes.length - 1];
+    if (!latest || latest.status !== 'SUCCESS') {
+        console.log(`[FO] Tribute for task "${payload.task_id}" is not SUCCESS (${latest?.status ?? 'none'}), no slot opened`);
+        return { dispatched: false };
+    }
+    // Check inbox for pending unread TASK_ASSIGNMENT
+    const mailDir = path.join(outpostPath, '.beads', 'mail');
+    const pendingMails = [];
+    try {
+        const files = await fs.readdir(mailDir);
+        for (const file of files) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const mails = await readBeads(path.join(mailDir, file));
+            pendingMails.push(...mails.filter(m => m.mail_type === 'TASK_ASSIGNMENT' && !m.read));
+        }
+    }
+    catch { /* no mail dir */ }
+    // Sort by created_at to get oldest first
+    pendingMails.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    console.log(`[FO] Slot opened on outpost "${payload.outpost}" (task "${payload.task_id}" completed). ${pendingMails.length} pending task(s) in inbox.`);
+    // If pending work exists and we have a process registry, check ceiling and dispatch
+    if (pendingMails.length > 0 && processRegistry) {
+        const maxCitizens = outpostEntry.max_citizens ?? 3;
+        const activeCount = processRegistry.countActive(payload.outpost);
+        if (activeCount < maxCitizens) {
+            const oldest = pendingMails[0];
+            console.log(`[FO] Dispatching pending task "${oldest.task_id}" on slot open`);
+            return { dispatched: true, taskId: oldest.task_id };
+        }
+    }
+    return { dispatched: pendingMails.length > 0 };
+}
+//# sourceMappingURL=slot-open.js.map

package/dist/core/fo-handlers/slot-open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-open.js","sourceRoot":"","sources":["../../../src/core/fo-handlers/slot-open.ts"],"names":[],"mappings":"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"}

package/dist/core/fo-nudge-watcher.d.ts

@@ -0,0 +1,19 @@
+import type { NudgeBead, NudgeSignalType } from '../types/index.js';
+export type NudgeHandler = (nudge: NudgeBead) => Promise<void>;
+export declare class NudgeWatcher {
+    private citadelRoot;
+    private handlers;
+    private running;
+    private pollIntervalMs;
+    private intervalHandle;
+    constructor(citadelRoot: string, pollIntervalMs?: number);
+    /** Register a handler for a specific signal type */
+    on(signalType: NudgeSignalType, handler: NudgeHandler): void;
+    /** Start the watcher loop */
+    start(): void;
+    /** Stop the watcher loop */
+    stop(): void;
+    /** Process unprocessed nudges in arrival order */
+    private processNudges;
+}
+//# sourceMappingURL=fo-nudge-watcher.d.ts.map

package/dist/core/fo-nudge-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-nudge-watcher.d.ts","sourceRoot":"","sources":["../../src/core/fo-nudge-watcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/D,qBAAa,YAAY;IAOrB,OAAO,CAAC,WAAW;IANrB,OAAO,CAAC,QAAQ,CAA4C;IAC5D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAA+C;gBAG3D,WAAW,EAAE,MAAM,EAC3B,cAAc,GAAE,MAAY;IAK9B,oDAAoD;IACpD,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAI5D,6BAA6B;IAC7B,KAAK,IAAI,IAAI;IAUb,4BAA4B;IAC5B,IAAI,IAAI,IAAI;IAQZ,kDAAkD;YACpC,aAAa;CAoC5B"}

package/dist/core/fo-nudge-watcher.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { readBeads } from './append-bead.js';
+export class NudgeWatcher {
+    citadelRoot;
+    handlers = new Map();
+    running = false;
+    pollIntervalMs;
+    intervalHandle = null;
+    constructor(citadelRoot, pollIntervalMs = 500) {
+        this.citadelRoot = citadelRoot;
+        this.pollIntervalMs = pollIntervalMs;
+    }
+    /** Register a handler for a specific signal type */
+    on(signalType, handler) {
+        this.handlers.set(signalType, handler);
+    }
+    /** Start the watcher loop */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.intervalHandle = setInterval(() => {
+            this.processNudges().catch(err => {
+                console.warn(`[NudgeWatcher] error: ${err.message}`);
+            });
+        }, this.pollIntervalMs);
+    }
+    /** Stop the watcher loop */
+    stop() {
+        this.running = false;
+        if (this.intervalHandle) {
+            clearInterval(this.intervalHandle);
+            this.intervalHandle = null;
+        }
+    }
+    /** Process unprocessed nudges in arrival order */
+    async processNudges() {
+        const nudgesPath = path.join(this.citadelRoot, '.citadel', 'nudges.jsonl');
+        const nudges = await readBeads(nudgesPath);
+        const unprocessed = nudges.filter(n => !n.processed);
+        if (unprocessed.length === 0)
+            return;
+        // Sort by created_at (arrival order)
+        unprocessed.sort((a, b) => a.created_at.localeCompare(b.created_at));
+        let modified = false;
+        for (const nudge of unprocessed) {
+            const handler = this.handlers.get(nudge.signal_type);
+            if (handler) {
+                try {
+                    await handler(nudge);
+                }
+                catch (err) {
+                    console.warn(`[NudgeWatcher] handler error for ${nudge.signal_type}: ${err.message}`);
+                }
+            }
+            else {
+                console.warn(`[NudgeWatcher] unrecognized signal: ${nudge.signal_type}, skipping`);
+            }
+            // Mark as processed
+            nudge.processed = true;
+            modified = true;
+        }
+        // Write back if any were processed
+        if (modified) {
+            const allLines = nudges.map(n => JSON.stringify(n)).join('\n') + '\n';
+            await fs.writeFile(nudgesPath, allLines, 'utf-8');
+        }
+    }
+}
+//# sourceMappingURL=fo-nudge-watcher.js.map

package/dist/core/fo-nudge-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-nudge-watcher.js","sourceRoot":"","sources":["../../src/core/fo-nudge-watcher.ts"],"names":[],"mappings":"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"}

package/dist/core/fo-nudge-wiring.d.ts

@@ -0,0 +1,13 @@
+import { NudgeWatcher } from './fo-nudge-watcher.js';
+import { ProcessRegistry } from './process-registry.js';
+export interface NudgeWiringOptions {
+    citadelRoot: string;
+    processRegistry: ProcessRegistry;
+    webhookUrl?: string;
+}
+/**
+ * Wire all 7 NudgeSignalType handlers to a NudgeWatcher instance.
+ * PRD §3.3.4: FO decision flow routes each signal to its handler.
+ */
+export declare function wireNudgeHandlers(watcher: NudgeWatcher, opts: NudgeWiringOptions): void;
+//# sourceMappingURL=fo-nudge-wiring.d.ts.map

package/dist/core/fo-nudge-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-nudge-wiring.d.ts","sourceRoot":"","sources":["../../src/core/fo-nudge-wiring.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAUrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMxD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,eAAe,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,kBAAkB,GACvB,IAAI,CAoGN"}

package/dist/core/fo-nudge-wiring.js

@@ -0,0 +1,120 @@
+import { processCommandBead } from './fo-command-processor.js';
+import { applyRetryPolicy } from './fo-retry-policy.js';
+import { handleSlotOpen } from './fo-handlers/slot-open.js';
+import { handleCeilingHit } from './fo-handlers/ceiling-hit.js';
+import { handleRelayRequest } from './fo-relay.js';
+import { handleTaskReport } from './fo-task-report.js';
+import { broadcastDependencyResolved } from './fo-broadcast.js';
+import { broadcastWebhook } from './fo-webhook.js';
+import { buildEscalationReport } from './fo-escalation.js';
+import { readBeads } from './append-bead.js';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+/**
+ * Wire all 7 NudgeSignalType handlers to a NudgeWatcher instance.
+ * PRD §3.3.4: FO decision flow routes each signal to its handler.
+ */
+export function wireNudgeHandlers(watcher, opts) {
+    const { citadelRoot, processRegistry } = opts;
+    // 1. TRIBUTE_WRITTEN -> retry policy -> broadcast/escalate -> slot-open
+    watcher.on('TRIBUTE_WRITTEN', async (nudge) => {
+        const result = await applyRetryPolicy(citadelRoot, nudge);
+        if (result.decision === 'success') {
+            await broadcastDependencyResolved(citadelRoot, result.tribute);
+            await broadcastWebhook(result.tribute, opts.webhookUrl ? { url: opts.webhookUrl } : undefined);
+        }
+        else if (result.decision === 'escalate') {
+            await buildEscalationReport(citadelRoot, result.tribute.task_id);
+        }
+        await handleSlotOpen(nudge, citadelRoot, processRegistry);
+    });
+    // 2. MAIL_RECEIVED -> route upward mail (RELAY_REQUEST, TASK_REPORT)
+    watcher.on('MAIL_RECEIVED', async (nudge) => {
+        const payload = nudge.payload;
+        if (payload.mail_type === 'RELAY_REQUEST') {
+            // Find the mail bead from the outpost
+            const outpostsPath = path.join(citadelRoot, '.citadel', 'outposts.json');
+            try {
+                const raw = await fs.readFile(outpostsPath, 'utf-8');
+                const registry = JSON.parse(raw);
+                for (const outpost of registry.outposts) {
+                    const mDir = path.join(outpost.path, '.beads', 'mail');
+                    try {
+                        const files = await fs.readdir(mDir);
+                        for (const file of files) {
+                            if (!file.endsWith('.jsonl'))
+                                continue;
+                            const mails = await readBeads(path.join(mDir, file));
+                            const match = mails.find(m => m.bead_id === payload.mail_bead_id);
+                            if (match) {
+                                await handleRelayRequest(citadelRoot, match);
+                                return;
+                            }
+                        }
+                    }
+                    catch { /* no mail dir */ }
+                }
+            }
+            catch { /* no outposts */ }
+        }
+        else if (payload.mail_type === 'TASK_REPORT') {
+            const outpostsPath = path.join(citadelRoot, '.citadel', 'outposts.json');
+            try {
+                const raw = await fs.readFile(outpostsPath, 'utf-8');
+                const registry = JSON.parse(raw);
+                for (const outpost of registry.outposts) {
+                    const mDir = path.join(outpost.path, '.beads', 'mail');
+                    try {
+                        const files = await fs.readdir(mDir);
+                        for (const file of files) {
+                            if (!file.endsWith('.jsonl'))
+                                continue;
+                            const mails = await readBeads(path.join(mDir, file));
+                            const match = mails.find(m => m.bead_id === payload.mail_bead_id);
+                            if (match) {
+                                await handleTaskReport(citadelRoot, match);
+                                return;
+                            }
+                        }
+                    }
+                    catch { /* no mail dir */ }
+                }
+            }
+            catch { /* no outposts */ }
+        }
+        console.log(`[FO] MAIL_RECEIVED: ${payload.mail_type} from ${payload.from}`);
+    });
+    // 3. COMMAND_RECEIVED -> process command bead
+    watcher.on('COMMAND_RECEIVED', async (nudge) => {
+        const payload = nudge.payload;
+        const commandPath = path.join(citadelRoot, '.citadel', 'commands', `${payload.command_bead_id}.jsonl`);
+        try {
+            const beads = await readBeads(commandPath);
+            const bead = beads.find(b => b.bead_id === payload.command_bead_id);
+            if (bead && !bead.processed) {
+                await processCommandBead(citadelRoot, bead, processRegistry);
+            }
+        }
+        catch {
+            console.warn(`[FO] Could not read command bead: ${payload.command_bead_id}`);
+        }
+    });
+    // 4. CITIZEN_EXIT_ERROR -> log error, trigger retry policy check
+    watcher.on('CITIZEN_EXIT_ERROR', async (nudge) => {
+        const payload = nudge.payload;
+        console.log(`[FO] CITIZEN_EXIT_ERROR: citizen "${payload.citizen_id}" on outpost "${payload.outpost}" exited with code ${payload.exit_code}`);
+    });
+    // 5. CITIZEN_TIMEOUT -> log timeout
+    watcher.on('CITIZEN_TIMEOUT', async (nudge) => {
+        const payload = nudge.payload;
+        console.log(`[FO] CITIZEN_TIMEOUT: citizen "${payload.citizen_id}" on outpost "${payload.outpost}" timed out`);
+    });
+    // 6. PARALLELISM_CEILING_HIT -> delegate to ceiling-hit handler
+    watcher.on('PARALLELISM_CEILING_HIT', handleCeilingHit);
+    // 7. NO_TASK_ASSIGNMENT -> log (no action needed)
+    watcher.on('NO_TASK_ASSIGNMENT', async (nudge) => {
+        const payload = nudge.payload;
+        console.log(`[FO] NO_TASK_ASSIGNMENT on outpost "${payload.outpost}"`);
+    });
+}
+//# sourceMappingURL=fo-nudge-wiring.js.map

package/dist/core/fo-nudge-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-nudge-wiring.js","sourceRoot":"","sources":["../../src/core/fo-nudge-wiring.ts"],"names":[],"mappings":"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"}

package/dist/core/fo-relay.d.ts

@@ -0,0 +1,7 @@
+import type { MailBead } from '../types/index.js';
+/**
+ * Handle a RELAY_REQUEST mail from a Citizen: compose and write a PEER_RELAY
+ * mail to the intended outpost with spawn_hint.
+ */
+export declare function handleRelayRequest(citadelRoot: string, relayMail: MailBead): Promise<MailBead>;
+//# sourceMappingURL=fo-relay.d.ts.map

package/dist/core/fo-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-relay.d.ts","sourceRoot":"","sources":["../../src/core/fo-relay.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAyC,MAAM,mBAAmB,CAAC;AAEzF;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,QAAQ,GAClB,OAAO,CAAC,QAAQ,CAAC,CA2CnB"}

package/dist/core/fo-relay.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { appendBead, mintBeadId } from './append-bead.js';
+import { getActiveOutposts } from './outpost-registry.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+/**
+ * Handle a RELAY_REQUEST mail from a Citizen: compose and write a PEER_RELAY
+ * mail to the intended outpost with spawn_hint.
+ */
+export async function handleRelayRequest(citadelRoot, relayMail) {
+    const payload = relayMail.payload;
+    // Resolve target outpost path
+    const activeOutposts = await getActiveOutposts(citadelRoot);
+    const target = activeOutposts.find(o => o.slug === payload.intended_for);
+    if (!target) {
+        throw new Error(`Relay target outpost "${payload.intended_for}" not found or not ACTIVE`);
+    }
+    const peerPayload = {
+        origin_outpost: relayMail.from,
+        origin_mail_ref: relayMail.bead_id,
+        subject: payload.subject,
+        body: payload.body,
+        context_refs: payload.context_refs,
+    };
+    const peerMail = {
+        bead_id: mintBeadId('MAIL'),
+        bead_type: 'MAIL',
+        schema_version: SCHEMA_VERSION,
+        created_at: new Date().toISOString(),
+        task_id: relayMail.task_id,
+        mail_type: 'PEER_RELAY',
+        from: relayMail.from,
+        to: payload.intended_for,
+        subject: payload.subject,
+        read: false,
+        retry_of: null,
+        spawn_hint: {
+            archetype: target.default_archetype ?? 'software-engineer',
+            citizen_id: `citizen-relay-${mintBeadId()}`,
+        },
+        payload: peerPayload,
+    };
+    const mailPath = path.join(target.path, '.beads', 'mail', `relay-${peerMail.bead_id}.jsonl`);
+    await appendBead(mailPath, peerMail);
+    console.log(`[FO] PEER_RELAY: "${relayMail.from}" -> "${payload.intended_for}" (subject: "${payload.subject}")`);
+    return peerMail;
+}
+//# sourceMappingURL=fo-relay.js.map

package/dist/core/fo-relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-relay.js","sourceRoot":"","sources":["../../src/core/fo-relay.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAAmB,EACnB,SAAmB;IAEnB,MAAM,OAAO,GAAG,SAAS,CAAC,OAA8B,CAAC;IAEzD,8BAA8B;IAC9B,MAAM,cAAc,GAAG,MAAM,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACzE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,CAAC,YAAY,2BAA2B,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,WAAW,GAAqB;QACpC,cAAc,EAAE,SAAS,CAAC,IAAI;QAC9B,eAAe,EAAE,SAAS,CAAC,OAAO;QAClC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,YAAY,EAAE,OAAO,CAAC,YAAY;KACnC,CAAC;IAEF,MAAM,QAAQ,GAAa;QACzB,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC;QAC3B,SAAS,EAAE,MAAM;QACjB,cAAc,EAAE,cAAc;QAC9B,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,SAAS,EAAE,YAAY;QACvB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,EAAE,EAAE,OAAO,CAAC,YAAY;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,KAAK;QACX,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE;YACV,SAAS,EAAE,MAAM,CAAC,iBAAiB,IAAI,mBAAmB;YAC1D,UAAU,EAAE,iBAAiB,UAAU,EAAE,EAAE;SAC5C;QACD,OAAO,EAAE,WAAW;KACrB,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC;IAC7F,MAAM,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAErC,OAAO,CAAC,GAAG,CAAC,qBAAqB,SAAS,CAAC,IAAI,SAAS,OAAO,CAAC,YAAY,gBAAgB,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IAEjH,OAAO,QAAQ,CAAC;AAClB,CAAC"}