@citadel-labs/citadel 0.1.0

package/dist/cli/tribute.js

@@ -0,0 +1,160 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readBeads } from '../core/append-bead.js';
+async function loadOutposts(citadelDir) {
+    try {
+        const raw = await fs.readFile(path.join(citadelDir, 'outposts.json'), 'utf-8');
+        const registry = JSON.parse(raw);
+        return registry.outposts;
+    }
+    catch {
+        return [];
+    }
+}
+async function listJsonlFiles(dirPath) {
+    try {
+        const entries = await fs.readdir(dirPath);
+        return entries
+            .filter((e) => e.endsWith('.jsonl'))
+            .map((e) => path.join(dirPath, e));
+    }
+    catch {
+        return [];
+    }
+}
+async function readAllBeadsFromDir(dirPath) {
+    const files = await listJsonlFiles(dirPath);
+    const results = [];
+    for (const file of files) {
+        const beads = await readBeads(file);
+        results.push(...beads);
+    }
+    return results;
+}
+function nudgePayloadHasTaskId(payload, taskId) {
+    if ('task_id' in payload && payload.task_id === taskId) {
+        return true;
+    }
+    return false;
+}
+function commandBeadReferencesTask(bead, taskId) {
+    const args = bead.args;
+    return args.task_id === taskId;
+}
+export function registerTributeCommand(program) {
+    program
+        .command('tribute')
+        .description('List tributes for a task')
+        .requiredOption('--task <id>', 'Task ID to look up')
+        .action(async (opts) => {
+        const citadelDir = path.resolve('.citadel');
+        try {
+            await fs.access(citadelDir);
+        }
+        catch {
+            console.error('Not a Citadel workspace');
+            process.exit(1);
+        }
+        const outposts = await loadOutposts(citadelDir);
+        const allTributes = [];
+        for (const op of outposts) {
+            const tributeDir = path.join(op.path, '.beads', 'tribute');
+            const tributes = await readAllBeadsFromDir(tributeDir);
+            allTributes.push(...tributes);
+        }
+        const matched = allTributes
+            .filter((t) => t.task_id === opts.task)
+            .sort((a, b) => a.created_at.localeCompare(b.created_at));
+        if (matched.length === 0) {
+            console.log(`No tributes found for task ${opts.task}`);
+            return;
+        }
+        for (const t of matched) {
+            const criteria = t.acceptance_met
+                .map((met) => (met ? '[x]' : '[ ]'))
+                .join(' ');
+            console.log(`--- Attempt ${t.attempt} ---`);
+            console.log(`  status:       ${t.status}`);
+            console.log(`  citizen_id:   ${t.citizen_id}`);
+            console.log(`  elapsed:      ${t.elapsed_seconds}s`);
+            console.log(`  summary:      ${t.summary}`);
+            console.log(`  acceptance:   ${criteria}`);
+        }
+    });
+    program
+        .command('trace')
+        .description('Show full event timeline for a task')
+        .requiredOption('--task <id>', 'Task ID to trace')
+        .action(async (opts) => {
+        const citadelDir = path.resolve('.citadel');
+        try {
+            await fs.access(citadelDir);
+        }
+        catch {
+            console.error('Not a Citadel workspace');
+            process.exit(1);
+        }
+        const events = [];
+        const outposts = await loadOutposts(citadelDir);
+        // 1. CommandBeads from .citadel/commands/*.jsonl
+        const commandBeads = await readAllBeadsFromDir(path.join(citadelDir, 'commands'));
+        for (const cb of commandBeads) {
+            if (commandBeadReferencesTask(cb, opts.task)) {
+                events.push({
+                    created_at: cb.created_at,
+                    bead_type: 'COMMAND',
+                    summary: `${cb.command} (${cb.bead_id})`,
+                });
+            }
+        }
+        // 2. MailBeads from all outposts
+        for (const op of outposts) {
+            const mailDir = path.join(op.path, '.beads', 'mail');
+            const mails = await readAllBeadsFromDir(mailDir);
+            for (const m of mails) {
+                if (m.task_id === opts.task) {
+                    events.push({
+                        created_at: m.created_at,
+                        bead_type: 'MAIL',
+                        summary: `${m.mail_type} from=${m.from} to=${m.to} "${m.subject}"`,
+                    });
+                }
+            }
+        }
+        // 3. TributeBeads from all outposts
+        for (const op of outposts) {
+            const tributeDir = path.join(op.path, '.beads', 'tribute');
+            const tributes = await readAllBeadsFromDir(tributeDir);
+            for (const t of tributes) {
+                if (t.task_id === opts.task) {
+                    events.push({
+                        created_at: t.created_at,
+                        bead_type: 'TRIBUTE',
+                        summary: `attempt=${t.attempt} status=${t.status} "${t.summary}"`,
+                    });
+                }
+            }
+        }
+        // 4. NudgeBeads from .citadel/nudges.jsonl
+        const nudges = await readBeads(path.join(citadelDir, 'nudges.jsonl'));
+        for (const n of nudges) {
+            if (nudgePayloadHasTaskId(n.payload, opts.task)) {
+                events.push({
+                    created_at: n.created_at,
+                    bead_type: 'NUDGE',
+                    summary: `${n.signal_type} (${n.bead_id})`,
+                });
+            }
+        }
+        // Sort and print
+        events.sort((a, b) => a.created_at.localeCompare(b.created_at));
+        if (events.length === 0) {
+            console.log(`No trace found for task ${opts.task}`);
+            return;
+        }
+        for (const e of events) {
+            console.log(`[${e.created_at}] [${e.bead_type}] ${e.summary}`);
+        }
+    });
+}
+//# sourceMappingURL=tribute.js.map

package/dist/cli/tribute.js.map

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

package/dist/cli/worktree.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerWorktreeCommand(program: Command): void;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/cli/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/cli/worktree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoE9D"}

package/dist/cli/worktree.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { WorktreeManager } from '../core/worktree-manager.js';
+export function registerWorktreeCommand(program) {
+    const worktree = program
+        .command('worktree')
+        .description('Manage git worktrees for outposts');
+    worktree
+        .command('list')
+        .description('List worktrees for an outpost')
+        .requiredOption('--outpost <slug>', 'Outpost slug')
+        .action(async (opts) => {
+        const citadelRoot = process.cwd();
+        const dotCitadel = path.join(citadelRoot, '.citadel');
+        try {
+            await fs.access(dotCitadel);
+        }
+        catch {
+            console.error('No .citadel/ directory found in current working directory.');
+            process.exit(1);
+        }
+        const manager = new WorktreeManager(citadelRoot);
+        const entries = await manager.list(opts.outpost);
+        if (entries.length === 0) {
+            console.log(`No worktrees for ${opts.outpost}`);
+            return;
+        }
+        for (const entry of entries) {
+            console.log(`${entry.path}  ${entry.branch}  ${entry.head.slice(0, 8)}`);
+        }
+    });
+    worktree
+        .command('prune')
+        .description('Prune orphaned worktrees')
+        .option('--outpost <slug>', 'Scope to a single outpost')
+        .action(async (opts) => {
+        const citadelRoot = process.cwd();
+        const dotCitadel = path.join(citadelRoot, '.citadel');
+        try {
+            await fs.access(dotCitadel);
+        }
+        catch {
+            console.error('No .citadel/ directory found in current working directory.');
+            process.exit(1);
+        }
+        const manager = new WorktreeManager(citadelRoot);
+        let slugs;
+        if (opts.outpost) {
+            slugs = [opts.outpost];
+        }
+        else {
+            const raw = await fs.readFile(path.join(dotCitadel, 'outposts.json'), 'utf-8');
+            const registry = JSON.parse(raw);
+            slugs = registry.outposts
+                .filter(o => o.status === 'ACTIVE')
+                .map(o => o.slug);
+        }
+        for (const slug of slugs) {
+            const pruned = await manager.pruneOrphaned(slug, new Set());
+            console.log(`Pruned ${pruned} worktree(s) from ${slug}`);
+        }
+    });
+}
+//# sourceMappingURL=worktree.js.map

package/dist/cli/worktree.js.map

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

package/dist/core/append-bead.d.ts

@@ -0,0 +1,13 @@
+import type { BaseBead } from '../types/index.js';
+/** Generate a bead ID with a type-specific prefix per PRD §3.1. */
+export declare function mintBeadId(beadType?: string): string;
+/**
+ * Append a bead as a single JSON line to the given file.
+ * Acquires a lockfile, appends, git commits, then releases.
+ */
+export declare function appendBead<T extends BaseBead>(filePath: string, bead: T): Promise<T>;
+/**
+ * Read a JSONL bead file and parse each line into T.
+ */
+export declare function readBeads<T extends BaseBead>(filePath: string): Promise<T[]>;
+//# sourceMappingURL=append-bead.d.ts.map

package/dist/core/append-bead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-bead.d.ts","sourceRoot":"","sources":["../../src/core/append-bead.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAYlD,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,QAAQ,EACjD,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,GACN,OAAO,CAAC,CAAC,CAAC,CAkCZ;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAChD,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,EAAE,CAAC,CAad"}

package/dist/core/append-bead.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { lock, unlock } from 'proper-lockfile';
+import { nanoid } from 'nanoid';
+const execFile = promisify(execFileCb);
+const BEAD_PREFIX_MAP = {
+    MAIL: 'mail_',
+    TRIBUTE: 'tribute_',
+    NUDGE: 'nudge_',
+    COMMAND: 'cmd_',
+    IDENTITY: 'identity_',
+};
+/** Generate a bead ID with a type-specific prefix per PRD §3.1. */
+export function mintBeadId(beadType) {
+    const prefix = beadType ? (BEAD_PREFIX_MAP[beadType] ?? 'bead-') : 'bead-';
+    return `${prefix}${nanoid()}`;
+}
+/**
+ * Append a bead as a single JSON line to the given file.
+ * Acquires a lockfile, appends, git commits, then releases.
+ */
+export async function appendBead(filePath, bead) {
+    const absPath = path.resolve(filePath);
+    const dir = path.dirname(absPath);
+    // Ensure the parent directory exists
+    await fs.mkdir(dir, { recursive: true });
+    // Ensure the file exists (lockfile requires it)
+    await fs.appendFile(absPath, '');
+    await lock(absPath, {
+        retries: { retries: 3, minTimeout: 50, maxTimeout: 200, factor: 2 },
+        stale: 5000,
+    });
+    try {
+        await fs.appendFile(absPath, JSON.stringify(bead) + '\n');
+        // Best-effort git commit
+        try {
+            await execFile('git', ['add', absPath], { cwd: dir });
+            await execFile('git', ['commit', '-m', `bead: ${bead.bead_type} ${bead.bead_id}`], { cwd: dir });
+        }
+        catch (err) {
+            console.warn(`[appendBead] git commit failed: ${err.message}`);
+        }
+    }
+    finally {
+        await unlock(absPath);
+    }
+    return bead;
+}
+/**
+ * Read a JSONL bead file and parse each line into T.
+ */
+export async function readBeads(filePath) {
+    const absPath = path.resolve(filePath);
+    let content;
+    try {
+        content = await fs.readFile(absPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    return content
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+        .map((line) => JSON.parse(line));
+}
+//# sourceMappingURL=append-bead.js.map

package/dist/core/append-bead.js.map

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

package/dist/core/blocked-outposts.d.ts

@@ -0,0 +1,15 @@
+import type { MailBead } from '../types/index.js';
+export interface BlockedTask {
+    outpost: string;
+    taskId: string;
+    mail: MailBead;
+}
+/**
+ * Find tasks across all ACTIVE outposts that are blocked on the given resolvedTaskId.
+ *
+ * A task is "blocked" if:
+ *   1. It has a TASK_ASSIGNMENT mail whose dependencies[] includes resolvedTaskId
+ *   2. It does NOT yet have a SUCCESS tribute
+ */
+export declare function getBlockedOutposts(citadelRoot: string, resolvedTaskId: string): Promise<BlockedTask[]>;
+//# sourceMappingURL=blocked-outposts.d.ts.map

package/dist/core/blocked-outposts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocked-outposts.d.ts","sourceRoot":"","sources":["../../src/core/blocked-outposts.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAsC,MAAM,mBAAmB,CAAC;AAEtF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,WAAW,EAAE,CAAC,CA+BxB"}

package/dist/core/blocked-outposts.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { readBeads } from './append-bead.js';
+import { getActiveOutposts } from './outpost-registry.js';
+/**
+ * Find tasks across all ACTIVE outposts that are blocked on the given resolvedTaskId.
+ *
+ * A task is "blocked" if:
+ *   1. It has a TASK_ASSIGNMENT mail whose dependencies[] includes resolvedTaskId
+ *   2. It does NOT yet have a SUCCESS tribute
+ */
+export async function getBlockedOutposts(citadelRoot, resolvedTaskId) {
+    const activeOutposts = await getActiveOutposts(citadelRoot);
+    const blocked = [];
+    for (const outpost of activeOutposts) {
+        const mailDir = path.join(outpost.path, '.beads', 'mail');
+        const tributeDir = path.join(outpost.path, '.beads', 'tribute');
+        // Read all mail beads
+        const mails = await readMailDir(mailDir);
+        // Find TASK_ASSIGNMENT mails that depend on resolvedTaskId
+        const dependentMails = mails.filter(m => {
+            if (m.mail_type !== 'TASK_ASSIGNMENT')
+                return false;
+            const payload = m.payload;
+            return payload.dependencies.includes(resolvedTaskId);
+        });
+        if (dependentMails.length === 0)
+            continue;
+        // Read tributes to check which tasks already succeeded
+        const succeededTaskIds = await getSucceededTaskIds(tributeDir);
+        for (const mail of dependentMails) {
+            const taskId = mail.task_id ?? mail.bead_id;
+            if (succeededTaskIds.has(taskId))
+                continue;
+            blocked.push({ outpost: outpost.slug, taskId, mail });
+        }
+    }
+    return blocked;
+}
+async function readMailDir(mailDir) {
+    let files;
+    try {
+        files = await fs.readdir(mailDir);
+    }
+    catch {
+        return [];
+    }
+    const mails = [];
+    for (const file of files) {
+        if (!file.endsWith('.jsonl'))
+            continue;
+        const beads = await readBeads(path.join(mailDir, file));
+        mails.push(...beads);
+    }
+    return mails;
+}
+async function getSucceededTaskIds(tributeDir) {
+    let files;
+    try {
+        files = await fs.readdir(tributeDir);
+    }
+    catch {
+        return new Set();
+    }
+    const succeeded = new Set();
+    for (const file of files) {
+        if (!file.endsWith('.jsonl'))
+            continue;
+        const beads = await readBeads(path.join(tributeDir, file));
+        for (const t of beads) {
+            if (t.status === 'SUCCESS')
+                succeeded.add(t.task_id);
+        }
+    }
+    return succeeded;
+}
+//# sourceMappingURL=blocked-outposts.js.map

package/dist/core/blocked-outposts.js.map

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

package/dist/core/citizen-bootstrap.d.ts

@@ -0,0 +1,17 @@
+import type { MailBead } from '../types/index.js';
+export interface CitizenContext {
+    citizenId: string;
+    outpost: string;
+    taskId: string;
+    worktree: string;
+    beadsRoot: string;
+    taskAssignment: MailBead | null;
+    isRetry: boolean;
+    retryErrors: string[];
+}
+/**
+ * Bootstrap a citizen: validate env, scan inbox, synthesize context.
+ * Called at the start of a citizen's lifecycle.
+ */
+export declare function citizenBootstrap(): Promise<CitizenContext>;
+//# sourceMappingURL=citizen-bootstrap.d.ts.map

package/dist/core/citizen-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citizen-bootstrap.d.ts","sourceRoot":"","sources":["../../src/core/citizen-bootstrap.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,cAAc,CAAC,CA8GhE"}

package/dist/core/citizen-bootstrap.js

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { readBeads, appendBead, mintBeadId } from './append-bead.js';
+import { SCHEMA_VERSION } from '../types/index.js';
+/**
+ * Bootstrap a citizen: validate env, scan inbox, synthesize context.
+ * Called at the start of a citizen's lifecycle.
+ */
+export async function citizenBootstrap() {
+    // 1. Check required env vars
+    const citizenId = requireEnv('CITADEL_CITIZEN_ID');
+    const beadsRoot = requireEnv('CITADEL_BEADS_ROOT');
+    const outpost = requireEnv('CITADEL_OUTPOST');
+    const taskId = requireEnv('CITADEL_TASK_ID');
+    const worktree = requireEnv('CITADEL_WORKTREE');
+    // 2. Resolve outpost path from outposts.json
+    const outpostsPath = path.join(beadsRoot, '.citadel', 'outposts.json');
+    let outpostPath = '';
+    try {
+        const raw = await fs.readFile(outpostsPath, 'utf-8');
+        const registry = JSON.parse(raw);
+        const entry = registry.outposts.find((o) => o.slug === outpost);
+        if (entry)
+            outpostPath = entry.path;
+    }
+    catch {
+        throw new Error('Cannot read outposts.json');
+    }
+    // 3. Scan inbox: read all mail files, sorted by created_at
+    const inboxDir = path.join(outpostPath, '.beads', 'mail');
+    const allMail = [];
+    try {
+        const files = await fs.readdir(inboxDir);
+        for (const file of files) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const beads = await readBeads(path.join(inboxDir, file));
+            allMail.push(...beads);
+        }
+    }
+    catch {
+        // no mail dir yet
+    }
+    // Sort by created_at
+    allMail.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    // 4. Find TASK_ASSIGNMENT for this citizen
+    const taskAssignment = allMail.find(m => m.mail_type === 'TASK_ASSIGNMENT' &&
+        m.spawn_hint?.citizen_id === citizenId) ?? null;
+    // If no TASK_ASSIGNMENT: write TASK_REPORT BLOCKED and return early
+    if (!taskAssignment) {
+        const reportMail = {
+            bead_id: mintBeadId('MAIL'),
+            bead_type: 'MAIL',
+            schema_version: SCHEMA_VERSION,
+            created_at: new Date().toISOString(),
+            mail_type: 'TASK_REPORT',
+            from: outpost,
+            to: 'citadel',
+            subject: `No task assignment found for citizen ${citizenId}`,
+            read: false,
+            retry_of: null,
+            payload: {
+                status: 'BLOCKED',
+                summary: `Citizen ${citizenId} found no TASK_ASSIGNMENT mail`,
+                blockers: ['No TASK_ASSIGNMENT mail in inbox'],
+                questions: [],
+                context_refs: [],
+            },
+        };
+        await appendBead(path.join(inboxDir, `report-${reportMail.bead_id}.jsonl`), reportMail);
+        return {
+            citizenId, outpost, taskId, worktree, beadsRoot,
+            taskAssignment: null,
+            isRetry: false,
+            retryErrors: [],
+        };
+    }
+    // 5. Check for TRIBUTE_INVALID (retry scenario)
+    let isRetry = false;
+    let retryErrors = [];
+    const tributeInvalid = allMail.find(m => m.mail_type === 'TRIBUTE_INVALID' && !m.read);
+    if (tributeInvalid) {
+        isRetry = true;
+        const payload = tributeInvalid.payload;
+        retryErrors = payload.errors ?? [];
+    }
+    // 6. Mark unread mail as read by appending a read marker line to the JSONL.
+    //    PRD §3.4.2 step 6: For each unread Mail, mark read via appendBead().
+    const unreadMail = allMail.filter(m => !m.read);
+    for (const mail of unreadMail) {
+        // Find which file this bead came from and append a read marker
+        const files = await fs.readdir(inboxDir).catch(() => []);
+        for (const file of files) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const filePath = path.join(inboxDir, file);
+            const beads = await readBeads(filePath);
+            if (beads.some(b => b.bead_id === mail.bead_id)) {
+                const readMarker = { ...mail, read: true };
+                await appendBead(filePath, readMarker);
+                break;
+            }
+        }
+    }
+    return {
+        citizenId, outpost, taskId, worktree, beadsRoot,
+        taskAssignment,
+        isRetry,
+        retryErrors,
+    };
+}
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`Missing required env var: ${name}`);
+    return value;
+}
+//# sourceMappingURL=citizen-bootstrap.js.map

package/dist/core/citizen-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citizen-bootstrap.js","sourceRoot":"","sources":["../../src/core/citizen-bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAcnD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,6BAA6B;IAC7B,MAAM,SAAS,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAEhD,6CAA6C;IAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;IACvE,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAClF,IAAI,KAAK;YAAE,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAED,2DAA2D;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,SAAS;YACvC,MAAM,KAAK,GAAG,MAAM,SAAS,CAAW,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IAED,qBAAqB;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjE,2CAA2C;IAC3C,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,iBAAiB;QACjC,CAAC,CAAC,UAAU,EAAE,UAAU,KAAK,SAAS,CAC5C,IAAI,IAAI,CAAC;IAEV,oEAAoE;IACpE,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,UAAU,GAAa;YAC3B,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC;YAC3B,SAAS,EAAE,MAAM;YACjB,cAAc,EAAE,cAAc;YAC9B,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,SAAS,EAAE,aAAa;YACxB,IAAI,EAAE,OAAO;YACb,EAAE,EAAE,SAAS;YACb,OAAO,EAAE,wCAAwC,SAAS,EAAE;YAC5D,IAAI,EAAE,KAAK;YACX,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE;gBACP,MAAM,EAAE,SAAS;gBACjB,OAAO,EAAE,WAAW,SAAS,gCAAgC;gBAC7D,QAAQ,EAAE,CAAC,kCAAkC,CAAC;gBAC9C,SAAS,EAAE,EAAE;gBACb,YAAY,EAAE,EAAE;aACjB;SACF,CAAC;QACF,MAAM,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,UAAU,CAAC,OAAO,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC;QAExF,OAAO;YACL,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS;YAC/C,cAAc,EAAE,IAAI;YACpB,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,EAAE;SAChB,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,WAAW,GAAa,EAAE,CAAC;IAC/B,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,iBAAiB,IAAI,CAAC,CAAC,CAAC,IAAI,CAClD,CAAC;IACF,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,OAAO,GAAG,cAAc,CAAC,OAA+B,CAAC;QAC/D,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IACrC,CAAC;IAED,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,+DAA+D;QAC/D,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAc,CAAC,CAAC;QACrE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,SAAS;YACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC3C,MAAM,KAAK,GAAG,MAAM,SAAS,CAAW,QAAQ,CAAC,CAAC;YAClD,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAChD,MAAM,UAAU,GAAa,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;gBACrD,MAAM,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;gBACvC,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS;QAC/C,cAAc;QACd,OAAO;QACP,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,EAAE,CAAC,CAAC;IACjE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/citizen-tribute.d.ts

@@ -0,0 +1,17 @@
+import type { TributeBead, TributeStatus } from '../types/index.js';
+export interface WriteTributeOptions {
+    originatingMailRef: string;
+    status: TributeStatus;
+    summary: string;
+    artifacts: string[];
+    acceptanceMet: boolean[];
+    elapsedSeconds: number;
+    prUrl?: string;
+}
+/**
+ * Write a Tribute bead from within a Citizen process.
+ * Reads env vars for context. Writes to <outpost_path>/.beads/tribute/<task_id>_tribute.jsonl
+ * Attempt number is determined from existing lines + 1.
+ */
+export declare function writeTribute(opts: WriteTributeOptions): Promise<TributeBead>;
+//# sourceMappingURL=citizen-tribute.d.ts.map

package/dist/core/citizen-tribute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citizen-tribute.d.ts","sourceRoot":"","sources":["../../src/core/citizen-tribute.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,aAAa,EAAE,OAAO,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0ClF"}