@citadel-labs/citadel 0.1.0

package/dist/core/fo-retry-policy.d.ts

@@ -0,0 +1,17 @@
+import type { NudgeBead, TributeBead } from '../types/index.js';
+export type RetryDecision = 'success' | 'retry' | 'escalate';
+export interface RetryPolicyResult {
+    decision: RetryDecision;
+    tribute: TributeBead;
+    errors: string[];
+}
+/**
+ * Process a TRIBUTE_WRITTEN nudge through the retry policy.
+ *
+ * SUCCESS -> return 'success' (caller handles broadcast + slot-open)
+ * PARTIAL (under ceiling) -> issue TRIBUTE_INVALID + retry mail, return 'retry'
+ * FAILED (under ceiling) -> issue TRIBUTE_INVALID + retry mail, return 'retry'
+ * At max retries -> return 'escalate'
+ */
+export declare function applyRetryPolicy(citadelRoot: string, nudge: NudgeBead): Promise<RetryPolicyResult>;
+//# sourceMappingURL=fo-retry-policy.d.ts.map

package/dist/core/fo-retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-retry-policy.d.ts","sourceRoot":"","sources":["../../src/core/fo-retry-policy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAyB,WAAW,EAA6B,MAAM,mBAAmB,CAAC;AAElH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,iBAAiB,CAAC,CAkF5B"}

package/dist/core/fo-retry-policy.js

@@ -0,0 +1,89 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { readBeads, appendBead, mintBeadId } from './append-bead.js';
+import { validateTribute } from './validate-tribute.js';
+import { GrandArchives } from './grand-archives.js';
+import { reconstructState } from './fo-state.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+/**
+ * Process a TRIBUTE_WRITTEN nudge through the retry policy.
+ *
+ * SUCCESS -> return 'success' (caller handles broadcast + slot-open)
+ * PARTIAL (under ceiling) -> issue TRIBUTE_INVALID + retry mail, return 'retry'
+ * FAILED (under ceiling) -> issue TRIBUTE_INVALID + retry mail, return 'retry'
+ * At max retries -> return 'escalate'
+ */
+export async function applyRetryPolicy(citadelRoot, nudge) {
+    const payload = nudge.payload;
+    // Load config for retry policy
+    const archives = new GrandArchives(citadelRoot);
+    const foConfig = await archives.loadFirstOfficerConfig();
+    const maxRetries = foConfig.retry_policy.max_retries;
+    // Read the tribute
+    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 === payload.outpost);
+    if (!outpost)
+        throw new Error(`Outpost "${payload.outpost}" not found`);
+    const tributePath = path.join(outpost.path, '.beads', 'tribute', `${payload.task_id}_tribute.jsonl`);
+    const tributes = await readBeads(tributePath);
+    const tribute = tributes.find(t => t.bead_id === payload.tribute_bead_id);
+    if (!tribute)
+        throw new Error(`Tribute "${payload.tribute_bead_id}" not found`);
+    // Find the originating TASK_ASSIGNMENT mail
+    const state = await reconstructState(citadelRoot);
+    const task = state.tasks.find(t => t.taskId === payload.task_id);
+    if (!task)
+        throw new Error(`Task "${payload.task_id}" not found`);
+    // Validate
+    const validation = validateTribute(tribute, task.assignmentMail);
+    // SUCCESS
+    if (tribute.status === 'SUCCESS' && validation.valid) {
+        return { decision: 'success', tribute, errors: [] };
+    }
+    // At ceiling?
+    if (tribute.attempt >= maxRetries) {
+        console.log(`[FO] Task "${payload.task_id}" at retry ceiling (${tribute.attempt}/${maxRetries}). Escalating to Commander.`);
+        return { decision: 'escalate', tribute, errors: validation.errors };
+    }
+    // PARTIAL or FAILED -> retry
+    const errors = validation.errors.length > 0
+        ? validation.errors
+        : [`Tribute status: ${tribute.status}`];
+    // Write TRIBUTE_INVALID mail
+    const invalidMail = {
+        bead_id: mintBeadId('MAIL'),
+        bead_type: 'MAIL',
+        schema_version: SCHEMA_VERSION,
+        created_at: new Date().toISOString(),
+        task_id: payload.task_id,
+        mail_type: 'TRIBUTE_INVALID',
+        from: 'citadel',
+        to: payload.outpost,
+        subject: `Tribute invalid for task ${payload.task_id}`,
+        read: false,
+        retry_of: null,
+        spawn_hint: task.assignmentMail.spawn_hint,
+        payload: {
+            tribute_ref: tribute.bead_id,
+            errors,
+            suggested_action: 'RETRY',
+        },
+    };
+    const mailPath = path.join(outpost.path, '.beads', 'mail', `invalid-${invalidMail.bead_id}.jsonl`);
+    await appendBead(mailPath, invalidMail);
+    // Write retry TASK_ASSIGNMENT
+    const retryMail = {
+        ...task.assignmentMail,
+        bead_id: mintBeadId('MAIL'),
+        created_at: new Date().toISOString(),
+        read: false,
+        retry_of: task.assignmentMail.bead_id,
+    };
+    const retryPath = path.join(outpost.path, '.beads', 'mail', `retry-${retryMail.bead_id}.jsonl`);
+    await appendBead(retryPath, retryMail);
+    console.log(`[FO] Retry issued for task "${payload.task_id}" (attempt ${tribute.attempt + 1}/${maxRetries})`);
+    return { decision: 'retry', tribute, errors };
+}
+//# sourceMappingURL=fo-retry-policy.js.map

package/dist/core/fo-retry-policy.js.map

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

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

@@ -0,0 +1,25 @@
+import type { MailBead, TributeBead } from '../types/index.js';
+export type TaskState = 'in_flight' | 'pending' | 'succeeded' | 'failed' | 'partial';
+export interface ReconstructedTask {
+    taskId: string;
+    outpost: string;
+    state: TaskState;
+    assignmentMail: MailBead;
+    tributes: TributeBead[];
+    latestTribute: TributeBead | null;
+    attempt: number;
+}
+export interface FirstOfficerState {
+    tasks: ReconstructedTask[];
+    inFlight: ReconstructedTask[];
+    pending: ReconstructedTask[];
+    succeeded: ReconstructedTask[];
+    failed: ReconstructedTask[];
+    partial: ReconstructedTask[];
+}
+/**
+ * Reconstruct First Officer state from Mail + Tribute only.
+ * Never reads Nudge history.
+ */
+export declare function reconstructState(citadelRoot: string): Promise<FirstOfficerState>;
+//# sourceMappingURL=fo-state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fo-state.d.ts","sourceRoot":"","sources":["../../src/core/fo-state.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAmB,MAAM,mBAAmB,CAAC;AAEhF,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAErF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,cAAc,EAAE,QAAQ,CAAC;IACzB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0FtF"}

package/dist/core/fo-state.js

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { readBeads } from './append-bead.js';
+/**
+ * Reconstruct First Officer state from Mail + Tribute only.
+ * Never reads Nudge history.
+ */
+export async function reconstructState(citadelRoot) {
+    const outpostsPath = path.join(citadelRoot, '.citadel', 'outposts.json');
+    let registry;
+    try {
+        const raw = await fs.readFile(outpostsPath, 'utf-8');
+        registry = JSON.parse(raw);
+    }
+    catch {
+        return emptyState();
+    }
+    const allMail = [];
+    const allTributes = [];
+    // Scan all outpost bead dirs
+    for (const outpost of registry.outposts) {
+        // Mail
+        const mailDir = path.join(outpost.path, '.beads', 'mail');
+        try {
+            const files = await fs.readdir(mailDir);
+            for (const file of files) {
+                if (!file.endsWith('.jsonl'))
+                    continue;
+                const beads = await readBeads(path.join(mailDir, file));
+                allMail.push(...beads);
+            }
+        }
+        catch { /* no mail dir */ }
+        // Tributes
+        const tributeDir = path.join(outpost.path, '.beads', 'tribute');
+        try {
+            const files = await fs.readdir(tributeDir);
+            for (const file of files) {
+                if (!file.endsWith('.jsonl'))
+                    continue;
+                const beads = await readBeads(path.join(tributeDir, file));
+                allTributes.push(...beads);
+            }
+        }
+        catch { /* no tribute dir */ }
+    }
+    // Find all TASK_ASSIGNMENT mails (downward)
+    const assignments = allMail.filter(m => m.mail_type === 'TASK_ASSIGNMENT');
+    // Group tributes by task_id
+    const tributesByTask = new Map();
+    for (const t of allTributes) {
+        const existing = tributesByTask.get(t.task_id) ?? [];
+        existing.push(t);
+        tributesByTask.set(t.task_id, existing);
+    }
+    const tasks = [];
+    for (const mail of assignments) {
+        const taskId = mail.task_id ?? mail.bead_id;
+        const tributes = (tributesByTask.get(taskId) ?? [])
+            .sort((a, b) => a.created_at.localeCompare(b.created_at));
+        const latest = tributes.length > 0 ? tributes[tributes.length - 1] : null;
+        let state;
+        if (!latest) {
+            state = 'in_flight';
+        }
+        else if (latest.status === 'SUCCESS') {
+            state = 'succeeded';
+        }
+        else if (latest.status === 'FAILED') {
+            state = 'failed';
+        }
+        else {
+            state = 'partial';
+        }
+        // Find outpost for this task
+        const outpost = mail.to; // TASK_ASSIGNMENT goes to outpost
+        tasks.push({
+            taskId,
+            outpost,
+            state,
+            assignmentMail: mail,
+            tributes,
+            latestTribute: latest,
+            attempt: tributes.length,
+        });
+    }
+    return {
+        tasks,
+        inFlight: tasks.filter(t => t.state === 'in_flight'),
+        pending: tasks.filter(t => t.state === 'in_flight' && !t.latestTribute), // subset
+        succeeded: tasks.filter(t => t.state === 'succeeded'),
+        failed: tasks.filter(t => t.state === 'failed'),
+        partial: tasks.filter(t => t.state === 'partial'),
+    };
+}
+function emptyState() {
+    return { tasks: [], inFlight: [], pending: [], succeeded: [], failed: [], partial: [] };
+}
+//# sourceMappingURL=fo-state.js.map

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

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

package/dist/core/fo-task-report.d.ts

@@ -0,0 +1,16 @@
+import type { MailBead } from '../types/index.js';
+export interface TaskReportResult {
+    status: string;
+    action: 'logged' | 'escalated';
+    commandBeadPath?: string;
+}
+/**
+ * Handle TASK_REPORT mail from a Citizen.
+ *
+ * - IN_PROGRESS: log status update
+ * - BLOCKED: escalate to Commander with blocker details
+ * - NEEDS_INPUT: escalate to Commander with questions
+ * - COMPLETE: log note (actual completion comes via Tribute)
+ */
+export declare function handleTaskReport(citadelRoot: string, reportMail: MailBead): Promise<TaskReportResult>;
+//# sourceMappingURL=fo-task-report.d.ts.map

package/dist/core/fo-task-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fo-task-report.d.ts","sourceRoot":"","sources":["../../src/core/fo-task-report.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAqB,MAAM,mBAAmB,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,QAAQ,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAiC3B"}

package/dist/core/fo-task-report.js

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import { appendBead, mintBeadId } from './append-bead.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+/**
+ * Handle TASK_REPORT mail from a Citizen.
+ *
+ * - IN_PROGRESS: log status update
+ * - BLOCKED: escalate to Commander with blocker details
+ * - NEEDS_INPUT: escalate to Commander with questions
+ * - COMPLETE: log note (actual completion comes via Tribute)
+ */
+export async function handleTaskReport(citadelRoot, reportMail) {
+    const payload = reportMail.payload;
+    const taskId = reportMail.task_id ?? 'unknown';
+    const from = reportMail.from;
+    switch (payload.status) {
+        case 'IN_PROGRESS': {
+            console.log(`[FO] TASK_REPORT from "${from}": task "${taskId}" in progress — ${payload.summary}`);
+            return { status: 'IN_PROGRESS', action: 'logged' };
+        }
+        case 'BLOCKED': {
+            console.log(`[FO] TASK_REPORT from "${from}": task "${taskId}" BLOCKED — ${payload.blockers.join(', ')}`);
+            const cmdPath = await writeEscalation(citadelRoot, taskId, from, payload);
+            return { status: 'BLOCKED', action: 'escalated', commandBeadPath: cmdPath };
+        }
+        case 'NEEDS_INPUT': {
+            console.log(`[FO] TASK_REPORT from "${from}": task "${taskId}" NEEDS_INPUT — ${payload.questions.join(', ')}`);
+            const cmdPath = await writeEscalation(citadelRoot, taskId, from, payload);
+            return { status: 'NEEDS_INPUT', action: 'escalated', commandBeadPath: cmdPath };
+        }
+        case 'COMPLETE': {
+            console.log(`[FO] TASK_REPORT from "${from}": task "${taskId}" reports COMPLETE — awaiting Tribute`);
+            return { status: 'COMPLETE', action: 'logged' };
+        }
+        default: {
+            console.warn(`[FO] Unknown TASK_REPORT status "${payload.status}" from "${from}" for task "${taskId}"`);
+            return { status: payload.status, action: 'logged' };
+        }
+    }
+}
+/**
+ * Write an escalation bead to .citadel/escalations/ for the Commander.
+ */
+async function writeEscalation(citadelRoot, taskId, fromOutpost, payload) {
+    const escalation = {
+        bead_id: mintBeadId('MAIL'),
+        bead_type: 'MAIL',
+        schema_version: SCHEMA_VERSION,
+        created_at: new Date().toISOString(),
+        task_id: taskId,
+        mail_type: 'TASK_REPORT',
+        from: fromOutpost,
+        to: 'commander',
+        subject: `[${payload.status}] Task ${taskId}`,
+        read: false,
+        retry_of: null,
+        payload,
+    };
+    const escalationPath = path.join(citadelRoot, '.citadel', 'escalations', `${payload.status.toLowerCase()}-${escalation.bead_id}.jsonl`);
+    await appendBead(escalationPath, escalation);
+    return escalationPath;
+}
+//# sourceMappingURL=fo-task-report.js.map

package/dist/core/fo-task-report.js.map

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

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

@@ -0,0 +1,22 @@
+import type { TributeBead } from '../types/index.js';
+export interface WebhookConfig {
+    url: string;
+    timeout_ms?: number;
+}
+export interface WebhookPayload {
+    event: 'task.success';
+    task_id: string;
+    outpost: string;
+    summary: string;
+    pr_url?: string;
+    attempt: number;
+    citizen_id: string;
+    elapsed_seconds: number;
+    timestamp: string;
+}
+/**
+ * POST a SUCCESS tribute summary to an optional webhook URL.
+ * Fails silently — webhook is best-effort notification.
+ */
+export declare function broadcastWebhook(tribute: TributeBead, webhook: WebhookConfig | undefined): Promise<boolean>;
+//# sourceMappingURL=fo-webhook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fo-webhook.d.ts","sourceRoot":"","sources":["../../src/core/fo-webhook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,aAAa,GAAG,SAAS,GACjC,OAAO,CAAC,OAAO,CAAC,CAuClB"}

package/dist/core/fo-webhook.js

@@ -0,0 +1,43 @@
+/**
+ * POST a SUCCESS tribute summary to an optional webhook URL.
+ * Fails silently — webhook is best-effort notification.
+ */
+export async function broadcastWebhook(tribute, webhook) {
+    if (!webhook?.url)
+        return false;
+    const payload = {
+        event: 'task.success',
+        task_id: tribute.task_id,
+        outpost: tribute.outpost,
+        summary: tribute.summary,
+        pr_url: tribute.pr_url,
+        attempt: tribute.attempt,
+        citizen_id: tribute.citizen_id,
+        elapsed_seconds: tribute.elapsed_seconds,
+        timestamp: new Date().toISOString(),
+    };
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), webhook.timeout_ms ?? 5000);
+        const response = await fetch(webhook.url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) {
+            console.log(`[FO] Webhook POST to ${webhook.url} — ${response.status}`);
+            return true;
+        }
+        else {
+            console.warn(`[FO] Webhook POST failed: ${response.status} ${response.statusText}`);
+            return false;
+        }
+    }
+    catch (err) {
+        console.warn(`[FO] Webhook POST error: ${err.message}`);
+        return false;
+    }
+}
+//# sourceMappingURL=fo-webhook.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fo-webhook.js","sourceRoot":"","sources":["../../src/core/fo-webhook.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAoB,EACpB,OAAkC;IAElC,IAAI,CAAC,OAAO,EAAE,GAAG;QAAE,OAAO,KAAK,CAAC;IAEhC,MAAM,OAAO,GAAmB;QAC9B,KAAK,EAAE,cAAc;QACrB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC;QAEnF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;YACxC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,YAAY,CAAC,SAAS,CAAC,CAAC;QAExB,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,wBAAwB,OAAO,CAAC,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACxE,OAAO,IAAI,CAAC;QACd,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,6BAA6B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YACpF,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,4BAA6B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACnE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/core/grand-archives.d.ts

@@ -0,0 +1,14 @@
+import type { ArchetypeRegistry, FirstOfficerConfig, ResolvedArchetype } from '../types/index.js';
+export declare class GrandArchives {
+    private archivesRoot;
+    constructor(citadelRoot: string);
+    resolve(archetypeKey: string): Promise<ResolvedArchetype>;
+    /**
+     * Resolve and compose the full system prompt: preamble + body.
+     * PRD §4.8: [base-prompt-preamble.md] + [archetype/system-prompt.md]
+     */
+    resolveComposedPrompt(archetypeKey: string): Promise<string>;
+    loadFirstOfficerConfig(): Promise<FirstOfficerConfig>;
+    listArchetypes(): Promise<ArchetypeRegistry>;
+}
+//# sourceMappingURL=grand-archives.d.ts.map

package/dist/core/grand-archives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grand-archives.d.ts","sourceRoot":"","sources":["../../src/core/grand-archives.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,aAAa;IACxB,OAAO,CAAC,YAAY,CAAS;gBAEjB,WAAW,EAAE,MAAM;IAIzB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwD/D;;;OAGG;IACG,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAS5D,sBAAsB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAerD,cAAc,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAcnD"}

package/dist/core/grand-archives.js

@@ -0,0 +1,79 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export class GrandArchives {
+    archivesRoot;
+    constructor(citadelRoot) {
+        this.archivesRoot = path.join(citadelRoot, 'grand-archives');
+    }
+    async resolve(archetypeKey) {
+        const configPath = path.join(this.archivesRoot, 'archetypes', archetypeKey, 'archetype.json');
+        let raw;
+        try {
+            raw = await fs.readFile(configPath, 'utf-8');
+        }
+        catch {
+            throw new Error(`Archetype config not found for "${archetypeKey}" at ${configPath}`);
+        }
+        const config = JSON.parse(raw);
+        const preamblePath = path.join(this.archivesRoot, config.system_prompt.preamble_ref);
+        const systemPromptPath = path.join(this.archivesRoot, config.system_prompt.body_ref);
+        const toolsetManifestPath = path.join(this.archivesRoot, config.toolset.override_ref);
+        // Resolve agent binary: archetype config > FO config > default 'claude'
+        let agentBinary = 'claude';
+        try {
+            const foConfig = await this.loadFirstOfficerConfig();
+            agentBinary = foConfig.agent ?? 'claude';
+        }
+        catch {
+            // FO config not found, use default
+        }
+        return {
+            key: config.key,
+            display_name: config.display_name,
+            preamble_path: preamblePath,
+            system_prompt_path: systemPromptPath,
+            toolset_manifest_path: toolsetManifestPath,
+            model: config.constraints.model,
+            agent_binary: agentBinary,
+            constraints: {
+                max_tokens_per_turn: config.constraints.max_tokens_per_turn,
+                temperature: config.constraints.temperature,
+            },
+        };
+    }
+    /**
+     * Resolve and compose the full system prompt: preamble + body.
+     * PRD §4.8: [base-prompt-preamble.md] + [archetype/system-prompt.md]
+     */
+    async resolveComposedPrompt(archetypeKey) {
+        const resolved = await this.resolve(archetypeKey);
+        const [preamble, body] = await Promise.all([
+            fs.readFile(resolved.preamble_path, 'utf-8'),
+            fs.readFile(resolved.system_prompt_path, 'utf-8'),
+        ]);
+        return `${preamble}\n${body}`;
+    }
+    async loadFirstOfficerConfig() {
+        const configPath = path.join(this.archivesRoot, 'first-officer', 'config.json');
+        let raw;
+        try {
+            raw = await fs.readFile(configPath, 'utf-8');
+        }
+        catch {
+            throw new Error(`First Officer config not found at ${configPath}`);
+        }
+        return JSON.parse(raw);
+    }
+    async listArchetypes() {
+        const registryPath = path.join(this.archivesRoot, 'registry.json');
+        let raw;
+        try {
+            raw = await fs.readFile(registryPath, 'utf-8');
+        }
+        catch {
+            throw new Error(`Archetype registry not found at ${registryPath}`);
+        }
+        return JSON.parse(raw);
+    }
+}
+//# sourceMappingURL=grand-archives.js.map

package/dist/core/grand-archives.js.map

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

package/dist/core/nudge.d.ts

@@ -0,0 +1,6 @@
+import type { NudgeBead, NudgeSignalType, NudgePayload } from '../types/index.js';
+/**
+ * Append a NudgeBead to .citadel/nudges.jsonl
+ */
+export declare function nudgeFirstOfficer(citadelRoot: string, signalType: NudgeSignalType, payload: NudgePayload): Promise<NudgeBead>;
+//# sourceMappingURL=nudge.d.ts.map

package/dist/core/nudge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge.d.ts","sourceRoot":"","sources":["../../src/core/nudge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElF;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,SAAS,CAAC,CAepB"}

package/dist/core/nudge.js

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import { appendBead, mintBeadId } from './append-bead.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+/**
+ * Append a NudgeBead to .citadel/nudges.jsonl
+ */
+export async function nudgeFirstOfficer(citadelRoot, signalType, payload) {
+    const bead = {
+        bead_id: mintBeadId('NUDGE'),
+        bead_type: 'NUDGE',
+        schema_version: SCHEMA_VERSION,
+        created_at: new Date().toISOString(),
+        signal_type: signalType,
+        payload,
+        processed: false,
+    };
+    return appendBead(path.join(citadelRoot, '.citadel', 'nudges.jsonl'), bead);
+}
+//# sourceMappingURL=nudge.js.map

package/dist/core/nudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge.js","sourceRoot":"","sources":["../../src/core/nudge.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,WAAmB,EACnB,UAA2B,EAC3B,OAAqB;IAErB,MAAM,IAAI,GAAc;QACtB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC;QAC5B,SAAS,EAAE,OAAO;QAClB,cAAc,EAAE,cAAc;QAC9B,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,WAAW,EAAE,UAAU;QACvB,OAAO;QACP,SAAS,EAAE,KAAK;KACjB,CAAC;IAEF,OAAO,UAAU,CACf,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,cAAc,CAAC,EAClD,IAAI,CACL,CAAC;AACJ,CAAC"}

package/dist/core/outpost-registry.d.ts

@@ -0,0 +1,16 @@
+import type { OutpostRegistry, OutpostRegistryEntry } from '../types/index.js';
+/**
+ * Read .citadel/outposts.json and return the parsed registry.
+ * Throws if the file is missing or malformed.
+ */
+export declare function loadOutpostRegistry(citadelRoot: string): Promise<OutpostRegistry>;
+/**
+ * Return ACTIVE outpost entries from the registry.
+ */
+export declare function getActiveOutposts(citadelRoot: string): Promise<OutpostRegistryEntry[]>;
+/**
+ * Return mail directory paths for all ACTIVE outposts.
+ * Each path is `<outpost.path>/.beads/mail`.
+ */
+export declare function getRegisteredOutpostMailDirs(citadelRoot: string): Promise<string[]>;
+//# sourceMappingURL=outpost-registry.d.ts.map

package/dist/core/outpost-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outpost-registry.d.ts","sourceRoot":"","sources":["../../src/core/outpost-registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAIvF;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAG5F;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGzF"}

package/dist/core/outpost-registry.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+/**
+ * Read .citadel/outposts.json and return the parsed registry.
+ * Throws if the file is missing or malformed.
+ */
+export async function loadOutpostRegistry(citadelRoot) {
+    const outpostsPath = path.join(citadelRoot, '.citadel', 'outposts.json');
+    const raw = await fs.readFile(outpostsPath, 'utf-8');
+    return JSON.parse(raw);
+}
+/**
+ * Return ACTIVE outpost entries from the registry.
+ */
+export async function getActiveOutposts(citadelRoot) {
+    const registry = await loadOutpostRegistry(citadelRoot);
+    return registry.outposts.filter(o => o.status === 'ACTIVE');
+}
+/**
+ * Return mail directory paths for all ACTIVE outposts.
+ * Each path is `<outpost.path>/.beads/mail`.
+ */
+export async function getRegisteredOutpostMailDirs(citadelRoot) {
+    const active = await getActiveOutposts(citadelRoot);
+    return active.map(o => path.join(o.path, '.beads', 'mail'));
+}
+//# sourceMappingURL=outpost-registry.js.map

package/dist/core/outpost-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outpost-registry.js","sourceRoot":"","sources":["../../src/core/outpost-registry.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGlC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,WAAmB;IAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,WAAmB;IACzD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACxD,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,WAAmB;IACpE,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/core/pre-spawn-check.d.ts

@@ -0,0 +1,16 @@
+import { ProcessRegistry } from './process-registry.js';
+import type { MailBead, OutpostRegistryEntry } from '../types/index.js';
+export interface PreSpawnResult {
+    canSpawn: boolean;
+    taskMail: MailBead | null;
+    reason?: string;
+}
+/**
+ * Pre-spawn check for an outpost:
+ * 1. Read unread TASK_ASSIGNMENT mail
+ * 2. If none, nudge NO_TASK_ASSIGNMENT
+ * 3. Check citizen ceiling
+ * 4. If at ceiling, nudge PARALLELISM_CEILING_HIT
+ */
+export declare function preSpawnCheck(citadelRoot: string, outpost: OutpostRegistryEntry, processRegistry: ProcessRegistry, maxCitizens: number): Promise<PreSpawnResult>;
+//# sourceMappingURL=pre-spawn-check.d.ts.map