@cluesmith/codev 3.2.4 → 3.3.1

package/dist/agent-farm/db/mailbox.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Mailbox repository (Spec 1313 — mailbox-first delivery).
+ *
+ * Pure, unit-testable data operations over the `mailbox` table. Every `afx send`
+ * is persisted here *before* the send response returns, so nothing is lost to a
+ * Tower crash, restart, or shutdown. This module is deliberately decoupled from
+ * delivery: it never writes to a PTY and never runs the render-gate. The delivery
+ * orchestration (Phase 4) wires against these proven operations.
+ *
+ * Design notes:
+ * - Functions take an explicit `db` handle first (matching `db/consolidate.ts`),
+ *   which keeps them trivially testable against any better-sqlite3 database.
+ * - Timestamps are epoch-ms integers supplied by the caller (defaulting to
+ *   `Date.now()`), so ordering and age math are deterministic and test-injectable.
+ * - `workspace_path` is treated as an opaque addressing key: callers pass a
+ *   canonical path (the send boundary canonicalizes in Phase 4), mirroring how
+ *   `cron_tasks` scopes by workspace. This module does not canonicalize.
+ * - The lifecycle state machine (`held → delivered | superseded | dismissed`) is
+ *   enforced here: every transition targets only `held` rows, so a terminal row
+ *   can never revert (no `delivered → held`) and `supersede` only replaces a row
+ *   that is still `held`.
+ */
+import type Database from 'better-sqlite3';
+import type { DbMailbox, MailboxReason } from './types.js';
+/**
+ * Fields a caller supplies to persist a new held row. The repository fills in the
+ * id, `held` status, `escalated=0`, and the timestamps.
+ */
+export interface EnqueueInput {
+    workspacePath: string;
+    toAgent: string;
+    /** Raw message body (never logged). */
+    body: string;
+    /** Exact bytes written to the PTY on delivery. */
+    formattedMessage: string;
+    /** Last-known PTY hint; the recipient is the agent, not this terminal. */
+    terminalId?: string | null;
+    fromAgent?: string | null;
+    fromWorkspace?: string | null;
+    /** Stage the text without submitting (no trailing Enter). */
+    noEnter?: boolean;
+    /** Initial why-held reason; null if it will be delivered immediately. */
+    reason?: MailboxReason | null;
+    /** Cron-only coalescing key; null for direct sends. */
+    supersedeKey?: string | null;
+    /**
+     * Delayed-send due time in epoch-ms (Spec 1313 round 3 — `--delay`). null means
+     * deliver-ASAP (every non-delayed send). A row is deliverable only once
+     * `not_before IS NULL OR not_before <= now`; a delayed send persists this at REQUEST
+     * time so the delay is durable across a Tower restart.
+     */
+    notBefore?: number | null;
+}
+/**
+ * Persist a new `held` row and return it. This is the persist-first step: the row
+ * exists (and survives a crash) before any delivery is attempted.
+ */
+export declare function enqueue(db: Database.Database, input: EnqueueInput, now?: number): DbMailbox;
+/** Fetch a single row by id, or null if it does not exist. */
+export declare function getById(db: Database.Database, id: string): DbMailbox | null;
+/**
+ * List all currently-held rows, oldest first. Scoped to `workspacePath` when
+ * provided, else workspace-wide (for `afx inbox`). `id` breaks created_at ties
+ * for deterministic ordering.
+ */
+export declare function listHeld(db: Database.Database, workspacePath?: string): DbMailbox[];
+/**
+ * ELIGIBLE held rows addressed to a specific agent, in enqueue order (`created_at ASC`).
+ * This is the per-agent drain order a delivery pass walks.
+ *
+ * Spec 1313 round 3 (`--delay`): a row is deliverable only when
+ * `not_before IS NULL OR not_before <= now` — a pre-due delayed send is EXCLUDED here, so it
+ * neither delivers early nor blocks a later normal message (the drainer picks `held[0]`, the
+ * oldest ELIGIBLE row). It becomes eligible on the first pass at/after its due time. `now`
+ * defaults to `Date.now()` and is injectable for deterministic tests.
+ */
+export declare function findHeldForAgent(db: Database.Database, workspacePath: string, toAgent: string, now?: number): DbMailbox[];
+/**
+ * Held rows whose escalation age ({@link ESCALATION_START_SQL} → now) has crossed `maxAgeMs`
+ * and that have NOT yet been escalated. Tower-global (every workspace) — the drainer's
+ * escalation pass walks these once per tick to flip `escalated` and emit the visibility
+ * broadcast. Bounded by the (small) held set, so a full scan is fine. Oldest effective-start
+ * escalates first.
+ *
+ * Spec 1313 round 3: a PRE-DUE delayed row never escalates — its effective start is its
+ * future `not_before`, which cannot be `< cutoff` (cutoff = now − maxAgeMs ≤ now), so the
+ * age filter excludes it by construction. A delayed row escalates only after it has been
+ * deliverable-but-stuck (past its due time) for the window.
+ */
+export declare function findEscalatable(db: Database.Database, maxAgeMs: number, now?: number): DbMailbox[];
+/** Per-agent held tally within a workspace (drives the overview's live indicator). */
+export interface HeldAgentCount {
+    toAgent: string;
+    count: number;
+    /** True if any of this agent's held rows has crossed the escalation age. */
+    escalated: boolean;
+}
+/** Workspace-level held summary: total, whether any row is escalated, and the per-agent split. */
+export interface WorkspaceHeldSummary {
+    total: number;
+    escalated: boolean;
+    byAgent: HeldAgentCount[];
+}
+/**
+ * Count currently-held rows for a workspace, grouped by recipient agent, with an
+ * escalation flag. Counts only — **no message bodies** are read or returned, so this is
+ * safe to fold into the overview payload that the dashboard/VSCode indicator renders
+ * (spec: the indicator is count-only; bodies live only in `afx inbox`). Aggregated in
+ * SQL so cost is bounded by the (small) held set, not the row bodies.
+ *
+ * ELIGIBLE rows only (Spec 1313 round 3): a PRE-DUE delayed send (`not_before` in the
+ * future) is "scheduled, not stuck" and must NOT inflate the attention count/indicator —
+ * this is the same `not_before IS NULL OR not_before <= now` eligibility every other
+ * count/alarm surface uses (`findHeldForAgent`, `findEscalatable`, `findStarvingAgents`),
+ * so `afx status` / the dashboard badge report deliverable-but-stuck mail, not scheduled
+ * sends. (Pre-due rows are still visible in `afx inbox`, which lists ALL held rows and
+ * labels these "scheduled" — only the count/alarm surfaces exclude them.) The `escalated`
+ * flag was already pre-due-safe (a pre-due row never escalates); this aligns the raw count.
+ */
+export declare function heldSummaryForWorkspace(db: Database.Database, workspacePath: string, now?: number): WorkspaceHeldSummary;
+/**
+ * Transition a held row to `delivered` (clearing its why-held reason and stamping
+ * `resolved_at`). Returns true if it transitioned; false if the row was already
+ * terminal or does not exist — so a re-delivery attempt (backstop racing a submit
+ * trigger) is a safe no-op and can never revert or double-deliver a row.
+ */
+export declare function markDelivered(db: Database.Database, id: string, now?: number): boolean;
+/**
+ * Refresh the why-held `reason` on a still-held row (informational — the value
+ * `afx inbox` shows and the send response reports). Only touches `held` rows, so
+ * it can never relabel or resurrect a terminal row. Returns true if a held row was
+ * updated. The delivery pass calls this so a held row's reason tracks the current
+ * gate verdict (e.g. `busy` → `no-live-pty` when the terminal dies).
+ */
+export declare function setHeldReason(db: Database.Database, id: string, reason: MailboxReason | null, now?: number): boolean;
+/**
+ * Flag a still-held row as escalated — **visibility only, NEVER affects delivery**. The
+ * drainer's escalation pass calls this when a row crosses the escalation age, then emits
+ * the escalation broadcast; the row still delivers only on a later clean gate pass.
+ * Held-only and idempotent (the `escalated = 0` guard), so a terminal or already-escalated
+ * row is untouched. Returns true if it flipped.
+ */
+export declare function markEscalated(db: Database.Database, id: string, now?: number): boolean;
+/**
+ * Supersede-key prefix for architect starvation notices (Spec 1313 round 3, change 3). A
+ * notice row carries `${NOTICE_SUPERSEDE_PREFIX}<starving-agent>` so (a) one pending notice
+ * per starving agent coalesces via {@link supersede}, and (b) notice rows are recognizable by
+ * prefix and EXCLUDED from {@link findStarvingAgents} — a notice can never itself trigger a
+ * notice ("no notice about a notice"). Cron uses bare task names as keys, which never collide
+ * with this prefix.
+ */
+export declare const NOTICE_SUPERSEDE_PREFIX = "mailbox-notice:";
+/** Per-agent aggregate over an agent's ELIGIBLE, non-notice held rows (Spec 1313 round 3). */
+export interface StarvingAgent {
+    workspacePath: string;
+    toAgent: string;
+    /**
+     * Escalation-start ({@link ESCALATION_START_SQL}) of the OLDEST eligible held row — the
+     * moment this agent's oldest deliverable mail became stuck. Its age is `now - stuckSince`.
+     */
+    stuckSince: number;
+    /** How many eligible non-notice rows are held for this agent. */
+    count: number;
+    /** Representative why-held reason (held rows for one agent share the gate's verdict). */
+    reason: MailboxReason | null;
+}
+/**
+ * Per-agent view of currently-STARVING mail (Spec 1313 round 3, change 3): agents with at
+ * least one ELIGIBLE (`not_before IS NULL OR not_before <= now`) held row that is NOT itself a
+ * notice ({@link NOTICE_SUPERSEDE_PREFIX}). Tower-global (every workspace), aggregated in SQL
+ * so cost is bounded by the (small) held set. The drainer's notice pass compares each agent's
+ * `stuckSince` against the owner-notice threshold to decide whether to alarm, and uses the
+ * membership of the returned set to decide when a prior notice can be cleared (agent no longer
+ * has any eligible non-notice held row → drained). PRE-DUE delayed rows are excluded (not
+ * stuck), so a scheduled send never trips the alarm nor keeps one alive.
+ */
+export declare function findStarvingAgents(db: Database.Database, now?: number): StarvingAgent[];
+/**
+ * Dismiss every still-`held` row matching `(workspacePath, supersedeKey)` (Spec 1313 round 3).
+ * Used to clear a pending architect notice once its starving agent recovers (the notice is
+ * moot). Audit-preserving (soft transition), and a no-op on an already-delivered notice.
+ * Returns the number of rows dismissed.
+ */
+export declare function dismissHeldWithKey(db: Database.Database, workspacePath: string, supersedeKey: string, now?: number): number;
+/**
+ * Dismiss every still-`held` row addressed to an agent (Spec 1313 round 3, take-now B). Called
+ * when an agent is cleaned up (`afx cleanup`) so its orphaned held rows stop pinning
+ * `heldCount`/escalated forever — the terminal-row prune only removes delivered/superseded/
+ * dismissed rows, never held ones. Audit-preserving. Returns the number of rows dismissed.
+ */
+export declare function dismissHeldForAgent(db: Database.Database, workspacePath: string, toAgent: string, now?: number): number;
+/**
+ * Transition a held row to `dismissed` (operator-cleared via `afx inbox dismiss`).
+ * The why-held reason is preserved for audit. Returns true if it transitioned;
+ * a dismissed row is never delivered.
+ */
+export declare function dismiss(db: Database.Database, id: string, now?: number): boolean;
+/**
+ * Count currently-`held` rows sharing `(workspacePath, supersedeKey)`. Cron reads
+ * this immediately before {@link supersede} — with no `await` between the two calls,
+ * so on better-sqlite3's synchronous, single-threaded handle the pair cannot
+ * interleave with another run — to log an honest outcome: a newer run that finds a
+ * prior held row of the same task reports `superseded`, otherwise `held`. The
+ * `(supersede_key)` index keeps this cheap.
+ */
+export declare function countHeldWithKey(db: Database.Database, workspacePath: string, supersedeKey: string): number;
+/**
+ * Replace the held row sharing `(workspacePath, supersedeKey)` — if any — with a
+ * fresh held row carrying the same key, atomically. Only `held` rows are
+ * superseded (a delivered/dismissed row is untouched), so a newer cron run
+ * collapses a stale backlog without disturbing history. When no held row matches,
+ * this is just an enqueue. Returns the newly-enqueued replacement row.
+ */
+export declare function supersede(db: Database.Database, workspacePath: string, supersedeKey: string, input: EnqueueInput, now?: number): DbMailbox;
+/**
+ * Delete terminal rows (delivered/superseded/dismissed) whose `resolved_at` is
+ * older than `retentionDays`. Held rows are never removed — the `status != 'held'`
+ * and `resolved_at IS NOT NULL` guards make that impossible even if a held row
+ * somehow carried a stale timestamp. Returns the number of rows deleted.
+ */
+export declare function pruneTerminal(db: Database.Database, retentionDays: number, now?: number): number;
+//# sourceMappingURL=mailbox.d.ts.map

package/dist/agent-farm/db/mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/mailbox.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/db/mailbox.js

@@ -0,0 +1,304 @@
+/**
+ * Mailbox repository (Spec 1313 — mailbox-first delivery).
+ *
+ * Pure, unit-testable data operations over the `mailbox` table. Every `afx send`
+ * is persisted here *before* the send response returns, so nothing is lost to a
+ * Tower crash, restart, or shutdown. This module is deliberately decoupled from
+ * delivery: it never writes to a PTY and never runs the render-gate. The delivery
+ * orchestration (Phase 4) wires against these proven operations.
+ *
+ * Design notes:
+ * - Functions take an explicit `db` handle first (matching `db/consolidate.ts`),
+ *   which keeps them trivially testable against any better-sqlite3 database.
+ * - Timestamps are epoch-ms integers supplied by the caller (defaulting to
+ *   `Date.now()`), so ordering and age math are deterministic and test-injectable.
+ * - `workspace_path` is treated as an opaque addressing key: callers pass a
+ *   canonical path (the send boundary canonicalizes in Phase 4), mirroring how
+ *   `cron_tasks` scopes by workspace. This module does not canonicalize.
+ * - The lifecycle state machine (`held → delivered | superseded | dismissed`) is
+ *   enforced here: every transition targets only `held` rows, so a terminal row
+ *   can never revert (no `delivered → held`) and `supersede` only replaces a row
+ *   that is still `held`.
+ */
+import { randomUUID } from 'node:crypto';
+const INSERT_SQL = `
+  INSERT INTO mailbox (
+    id, workspace_path, to_agent, terminal_id, from_agent, from_workspace,
+    body, formatted_message, no_enter, status, reason, supersede_key,
+    escalated, not_before, created_at, updated_at, resolved_at
+  ) VALUES (
+    @id, @workspace_path, @to_agent, @terminal_id, @from_agent, @from_workspace,
+    @body, @formatted_message, @no_enter, @status, @reason, @supersede_key,
+    @escalated, @not_before, @created_at, @updated_at, @resolved_at
+  )
+`;
+function buildRow(input, now) {
+    return {
+        id: randomUUID(),
+        workspace_path: input.workspacePath,
+        to_agent: input.toAgent,
+        terminal_id: input.terminalId ?? null,
+        from_agent: input.fromAgent ?? null,
+        from_workspace: input.fromWorkspace ?? null,
+        body: input.body,
+        formatted_message: input.formattedMessage,
+        no_enter: input.noEnter ? 1 : 0,
+        status: 'held',
+        reason: input.reason ?? null,
+        supersede_key: input.supersedeKey ?? null,
+        escalated: 0,
+        not_before: input.notBefore ?? null,
+        created_at: now,
+        updated_at: now,
+        resolved_at: null,
+    };
+}
+/**
+ * Persist a new `held` row and return it. This is the persist-first step: the row
+ * exists (and survives a crash) before any delivery is attempted.
+ */
+export function enqueue(db, input, now = Date.now()) {
+    const row = buildRow(input, now);
+    db.prepare(INSERT_SQL).run(row);
+    return row;
+}
+/** Fetch a single row by id, or null if it does not exist. */
+export function getById(db, id) {
+    const row = db.prepare('SELECT * FROM mailbox WHERE id = ?').get(id);
+    return row ?? null;
+}
+/**
+ * List all currently-held rows, oldest first. Scoped to `workspacePath` when
+ * provided, else workspace-wide (for `afx inbox`). `id` breaks created_at ties
+ * for deterministic ordering.
+ */
+export function listHeld(db, workspacePath) {
+    if (workspacePath !== undefined) {
+        return db
+            .prepare("SELECT * FROM mailbox WHERE workspace_path = ? AND status = 'held' ORDER BY created_at ASC, id ASC")
+            .all(workspacePath);
+    }
+    return db
+        .prepare("SELECT * FROM mailbox WHERE status = 'held' ORDER BY created_at ASC, id ASC")
+        .all();
+}
+/**
+ * ELIGIBLE held rows addressed to a specific agent, in enqueue order (`created_at ASC`).
+ * This is the per-agent drain order a delivery pass walks.
+ *
+ * Spec 1313 round 3 (`--delay`): a row is deliverable only when
+ * `not_before IS NULL OR not_before <= now` — a pre-due delayed send is EXCLUDED here, so it
+ * neither delivers early nor blocks a later normal message (the drainer picks `held[0]`, the
+ * oldest ELIGIBLE row). It becomes eligible on the first pass at/after its due time. `now`
+ * defaults to `Date.now()` and is injectable for deterministic tests.
+ */
+export function findHeldForAgent(db, workspacePath, toAgent, now = Date.now()) {
+    return db
+        .prepare("SELECT * FROM mailbox WHERE workspace_path = ? AND to_agent = ? AND status = 'held' AND (not_before IS NULL OR not_before <= ?) ORDER BY created_at ASC, id ASC")
+        .all(workspacePath, toAgent, now);
+}
+/**
+ * SQL for a held row's escalation-age START — the moment it became *deliverable-but-stuck*.
+ * For a normal row that is `created_at` (born held then). For a delayed row (`not_before`
+ * set) it is the DUE time, so a still-scheduled row's clock has not started (Spec 1313 round
+ * 3: "measure escalation age from max(created_at, not_before)"). `not_before` is always ≥
+ * `created_at` when set (due = created + delay), so MAX == COALESCE(not_before, created_at);
+ * MAX is kept so a hand-written earlier not_before can never move the start before enqueue.
+ */
+const ESCALATION_START_SQL = 'MAX(created_at, COALESCE(not_before, created_at))';
+/**
+ * Held rows whose escalation age ({@link ESCALATION_START_SQL} → now) has crossed `maxAgeMs`
+ * and that have NOT yet been escalated. Tower-global (every workspace) — the drainer's
+ * escalation pass walks these once per tick to flip `escalated` and emit the visibility
+ * broadcast. Bounded by the (small) held set, so a full scan is fine. Oldest effective-start
+ * escalates first.
+ *
+ * Spec 1313 round 3: a PRE-DUE delayed row never escalates — its effective start is its
+ * future `not_before`, which cannot be `< cutoff` (cutoff = now − maxAgeMs ≤ now), so the
+ * age filter excludes it by construction. A delayed row escalates only after it has been
+ * deliverable-but-stuck (past its due time) for the window.
+ */
+export function findEscalatable(db, maxAgeMs, now = Date.now()) {
+    const cutoff = now - maxAgeMs;
+    return db
+        .prepare(`SELECT * FROM mailbox WHERE status = 'held' AND escalated = 0 AND ${ESCALATION_START_SQL} < ? ORDER BY ${ESCALATION_START_SQL} ASC, id ASC`)
+        .all(cutoff);
+}
+/**
+ * Count currently-held rows for a workspace, grouped by recipient agent, with an
+ * escalation flag. Counts only — **no message bodies** are read or returned, so this is
+ * safe to fold into the overview payload that the dashboard/VSCode indicator renders
+ * (spec: the indicator is count-only; bodies live only in `afx inbox`). Aggregated in
+ * SQL so cost is bounded by the (small) held set, not the row bodies.
+ *
+ * ELIGIBLE rows only (Spec 1313 round 3): a PRE-DUE delayed send (`not_before` in the
+ * future) is "scheduled, not stuck" and must NOT inflate the attention count/indicator —
+ * this is the same `not_before IS NULL OR not_before <= now` eligibility every other
+ * count/alarm surface uses (`findHeldForAgent`, `findEscalatable`, `findStarvingAgents`),
+ * so `afx status` / the dashboard badge report deliverable-but-stuck mail, not scheduled
+ * sends. (Pre-due rows are still visible in `afx inbox`, which lists ALL held rows and
+ * labels these "scheduled" — only the count/alarm surfaces exclude them.) The `escalated`
+ * flag was already pre-due-safe (a pre-due row never escalates); this aligns the raw count.
+ */
+export function heldSummaryForWorkspace(db, workspacePath, now = Date.now()) {
+    const rows = db
+        .prepare("SELECT to_agent AS toAgent, COUNT(*) AS count, MAX(escalated) AS esc FROM mailbox WHERE workspace_path = ? AND status = 'held' AND (not_before IS NULL OR not_before <= ?) GROUP BY to_agent")
+        .all(workspacePath, now);
+    let total = 0;
+    let escalated = false;
+    const byAgent = rows.map((r) => {
+        total += r.count;
+        const rowEsc = r.esc === 1;
+        if (rowEsc)
+            escalated = true;
+        return { toAgent: r.toAgent, count: r.count, escalated: rowEsc };
+    });
+    return { total, escalated, byAgent };
+}
+/**
+ * Transition a held row to `delivered` (clearing its why-held reason and stamping
+ * `resolved_at`). Returns true if it transitioned; false if the row was already
+ * terminal or does not exist — so a re-delivery attempt (backstop racing a submit
+ * trigger) is a safe no-op and can never revert or double-deliver a row.
+ */
+export function markDelivered(db, id, now = Date.now()) {
+    const info = db
+        .prepare("UPDATE mailbox SET status = 'delivered', reason = NULL, updated_at = ?, resolved_at = ? WHERE id = ? AND status = 'held'")
+        .run(now, now, id);
+    return info.changes > 0;
+}
+/**
+ * Refresh the why-held `reason` on a still-held row (informational — the value
+ * `afx inbox` shows and the send response reports). Only touches `held` rows, so
+ * it can never relabel or resurrect a terminal row. Returns true if a held row was
+ * updated. The delivery pass calls this so a held row's reason tracks the current
+ * gate verdict (e.g. `busy` → `no-live-pty` when the terminal dies).
+ */
+export function setHeldReason(db, id, reason, now = Date.now()) {
+    const info = db
+        .prepare("UPDATE mailbox SET reason = ?, updated_at = ? WHERE id = ? AND status = 'held'")
+        .run(reason, now, id);
+    return info.changes > 0;
+}
+/**
+ * Flag a still-held row as escalated — **visibility only, NEVER affects delivery**. The
+ * drainer's escalation pass calls this when a row crosses the escalation age, then emits
+ * the escalation broadcast; the row still delivers only on a later clean gate pass.
+ * Held-only and idempotent (the `escalated = 0` guard), so a terminal or already-escalated
+ * row is untouched. Returns true if it flipped.
+ */
+export function markEscalated(db, id, now = Date.now()) {
+    const info = db
+        .prepare("UPDATE mailbox SET escalated = 1, updated_at = ? WHERE id = ? AND status = 'held' AND escalated = 0")
+        .run(now, id);
+    return info.changes > 0;
+}
+/**
+ * Supersede-key prefix for architect starvation notices (Spec 1313 round 3, change 3). A
+ * notice row carries `${NOTICE_SUPERSEDE_PREFIX}<starving-agent>` so (a) one pending notice
+ * per starving agent coalesces via {@link supersede}, and (b) notice rows are recognizable by
+ * prefix and EXCLUDED from {@link findStarvingAgents} — a notice can never itself trigger a
+ * notice ("no notice about a notice"). Cron uses bare task names as keys, which never collide
+ * with this prefix.
+ */
+export const NOTICE_SUPERSEDE_PREFIX = 'mailbox-notice:';
+/**
+ * Per-agent view of currently-STARVING mail (Spec 1313 round 3, change 3): agents with at
+ * least one ELIGIBLE (`not_before IS NULL OR not_before <= now`) held row that is NOT itself a
+ * notice ({@link NOTICE_SUPERSEDE_PREFIX}). Tower-global (every workspace), aggregated in SQL
+ * so cost is bounded by the (small) held set. The drainer's notice pass compares each agent's
+ * `stuckSince` against the owner-notice threshold to decide whether to alarm, and uses the
+ * membership of the returned set to decide when a prior notice can be cleared (agent no longer
+ * has any eligible non-notice held row → drained). PRE-DUE delayed rows are excluded (not
+ * stuck), so a scheduled send never trips the alarm nor keeps one alive.
+ */
+export function findStarvingAgents(db, now = Date.now()) {
+    return db
+        .prepare(`SELECT workspace_path AS workspacePath, to_agent AS toAgent,
+              MIN(${ESCALATION_START_SQL}) AS stuckSince,
+              COUNT(*) AS count,
+              MAX(reason) AS reason
+         FROM mailbox
+        WHERE status = 'held'
+          AND (not_before IS NULL OR not_before <= ?)
+          AND (supersede_key IS NULL OR supersede_key NOT LIKE ?)
+        GROUP BY workspace_path, to_agent`)
+        .all(now, `${NOTICE_SUPERSEDE_PREFIX}%`);
+}
+/**
+ * Dismiss every still-`held` row matching `(workspacePath, supersedeKey)` (Spec 1313 round 3).
+ * Used to clear a pending architect notice once its starving agent recovers (the notice is
+ * moot). Audit-preserving (soft transition), and a no-op on an already-delivered notice.
+ * Returns the number of rows dismissed.
+ */
+export function dismissHeldWithKey(db, workspacePath, supersedeKey, now = Date.now()) {
+    const info = db
+        .prepare("UPDATE mailbox SET status = 'dismissed', updated_at = ?, resolved_at = ? WHERE workspace_path = ? AND supersede_key = ? AND status = 'held'")
+        .run(now, now, workspacePath, supersedeKey);
+    return info.changes;
+}
+/**
+ * Dismiss every still-`held` row addressed to an agent (Spec 1313 round 3, take-now B). Called
+ * when an agent is cleaned up (`afx cleanup`) so its orphaned held rows stop pinning
+ * `heldCount`/escalated forever — the terminal-row prune only removes delivered/superseded/
+ * dismissed rows, never held ones. Audit-preserving. Returns the number of rows dismissed.
+ */
+export function dismissHeldForAgent(db, workspacePath, toAgent, now = Date.now()) {
+    const info = db
+        .prepare("UPDATE mailbox SET status = 'dismissed', updated_at = ?, resolved_at = ? WHERE workspace_path = ? AND to_agent = ? AND status = 'held'")
+        .run(now, now, workspacePath, toAgent);
+    return info.changes;
+}
+/**
+ * Transition a held row to `dismissed` (operator-cleared via `afx inbox dismiss`).
+ * The why-held reason is preserved for audit. Returns true if it transitioned;
+ * a dismissed row is never delivered.
+ */
+export function dismiss(db, id, now = Date.now()) {
+    const info = db
+        .prepare("UPDATE mailbox SET status = 'dismissed', updated_at = ?, resolved_at = ? WHERE id = ? AND status = 'held'")
+        .run(now, now, id);
+    return info.changes > 0;
+}
+/**
+ * Count currently-`held` rows sharing `(workspacePath, supersedeKey)`. Cron reads
+ * this immediately before {@link supersede} — with no `await` between the two calls,
+ * so on better-sqlite3's synchronous, single-threaded handle the pair cannot
+ * interleave with another run — to log an honest outcome: a newer run that finds a
+ * prior held row of the same task reports `superseded`, otherwise `held`. The
+ * `(supersede_key)` index keeps this cheap.
+ */
+export function countHeldWithKey(db, workspacePath, supersedeKey) {
+    const row = db
+        .prepare("SELECT COUNT(*) AS n FROM mailbox WHERE workspace_path = ? AND supersede_key = ? AND status = 'held'")
+        .get(workspacePath, supersedeKey);
+    return row.n;
+}
+/**
+ * Replace the held row sharing `(workspacePath, supersedeKey)` — if any — with a
+ * fresh held row carrying the same key, atomically. Only `held` rows are
+ * superseded (a delivered/dismissed row is untouched), so a newer cron run
+ * collapses a stale backlog without disturbing history. When no held row matches,
+ * this is just an enqueue. Returns the newly-enqueued replacement row.
+ */
+export function supersede(db, workspacePath, supersedeKey, input, now = Date.now()) {
+    const run = db.transaction(() => {
+        db.prepare("UPDATE mailbox SET status = 'superseded', updated_at = ?, resolved_at = ? WHERE workspace_path = ? AND supersede_key = ? AND status = 'held'").run(now, now, workspacePath, supersedeKey);
+        return enqueue(db, { ...input, workspacePath, supersedeKey }, now);
+    });
+    return run();
+}
+/**
+ * Delete terminal rows (delivered/superseded/dismissed) whose `resolved_at` is
+ * older than `retentionDays`. Held rows are never removed — the `status != 'held'`
+ * and `resolved_at IS NOT NULL` guards make that impossible even if a held row
+ * somehow carried a stale timestamp. Returns the number of rows deleted.
+ */
+export function pruneTerminal(db, retentionDays, now = Date.now()) {
+    const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+    const info = db
+        .prepare("DELETE FROM mailbox WHERE status != 'held' AND resolved_at IS NOT NULL AND resolved_at < ?")
+        .run(cutoff);
+    return info.changes;
+}
+//# sourceMappingURL=mailbox.js.map

package/dist/agent-farm/db/mailbox.js.map

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

package/dist/agent-farm/db/schema.d.ts

@@ -19,5 +19,5 @@ export declare const LOCAL_SCHEMA = "\n-- Schema versioning\nCREATE TABLE IF NOT
  * Global registry schema (global.db)
  * Stores terminal sessions and migrations across all workspaces
  */
-export declare const GLOBAL_SCHEMA = "\n-- Schema versioning\nCREATE TABLE IF NOT EXISTS _migrations (\n  version INTEGER PRIMARY KEY,\n  applied_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Terminal sessions (Spec 0090 TICK-001)\n-- Tracks all terminal sessions across all workspaces for persistence and reconciliation\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,                    -- terminal UUID from PtyManager\n  workspace_path TEXT NOT NULL,           -- workspace this terminal belongs to\n  type TEXT NOT NULL                      -- 'architect', 'builder', 'shell'\n    CHECK(type IN ('architect', 'builder', 'shell')),\n  role_id TEXT,                           -- builder ID or shell ID (null for architect)\n  pid INTEGER,                            -- process ID of the terminal\n  shellper_socket TEXT,                   -- Unix socket path for shellper process\n  shellper_pid INTEGER,                   -- shellper process PID\n  shellper_start_time INTEGER,            -- shellper process start time (epoch ms)\n  label TEXT,                             -- custom display label (Spec 468)\n  cwd TEXT,                               -- working directory of the terminal (Bugfix #506)\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_workspace ON terminal_sessions(workspace_path);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);\n\n-- File tabs (Spec 0099 Phase 4)\nCREATE TABLE IF NOT EXISTS file_tabs (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  file_path TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_file_tabs_workspace ON file_tabs(workspace_path);\n\n-- Known workspaces (persistent workspace registry)\nCREATE TABLE IF NOT EXISTS known_workspaces (\n  workspace_path TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  last_launched_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Cron tasks (Spec 399)\n-- Tracks scheduled task state across all workspaces\nCREATE TABLE IF NOT EXISTS cron_tasks (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  task_name TEXT NOT NULL,\n  last_run INTEGER,\n  last_result TEXT,\n  last_output TEXT,\n  enabled INTEGER NOT NULL DEFAULT 1,\n  UNIQUE(workspace_path, task_name)\n);\n\n-- ===========================================================================\n-- Issue #1118: tables absorbed from the retired per-workspace state.db.\n-- architect/utils/annotations move as-is; builders is RESHAPED to be\n-- workspace-scoped (composite PK), mirroring architect (Bugfix #826) \u2014 builder\n-- ids are <protocol>-<issueNumber>, unique within a workspace but reused across\n-- repos, so a single shared table must disambiguate by workspace_path.\n-- ===========================================================================\n\n-- Architect sessions (Spec 755 multi-architect; Bugfix #826 workspace-scoped;\n-- Issue #832 session_id). id is the architect's name ('main', siblings).\nCREATE TABLE IF NOT EXISTS architect (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  pid INTEGER NOT NULL,\n  port INTEGER NOT NULL,\n  cmd TEXT NOT NULL,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  terminal_id TEXT,\n  session_id TEXT,\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_architect_workspace ON architect(workspace_path);\n\n-- Builder sessions. Issue #1118: workspace_path + composite PK so the same\n-- builder id can exist in multiple workspaces without collision.\nCREATE TABLE IF NOT EXISTS builders (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  status TEXT NOT NULL DEFAULT 'spawning'\n    CHECK(status IN ('spawning', 'implementing', 'blocked', 'pr', 'complete')),\n  phase TEXT NOT NULL DEFAULT '',\n  worktree TEXT NOT NULL,\n  branch TEXT NOT NULL,\n  type TEXT NOT NULL DEFAULT 'spec'\n    CHECK(type IN ('spec', 'task', 'protocol', 'shell', 'worktree', 'bugfix', 'pir')),\n  task_text TEXT,\n  protocol_name TEXT,\n  issue_number TEXT,\n  terminal_id TEXT,\n  spawned_by_architect TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_builders_status ON builders(status);\nCREATE INDEX IF NOT EXISTS idx_builders_port ON builders(port);\n\nCREATE TRIGGER IF NOT EXISTS builders_updated_at\n  AFTER UPDATE ON builders\n  FOR EACH ROW\n  BEGIN\n    UPDATE builders SET updated_at = datetime('now')\n      WHERE workspace_path = NEW.workspace_path AND id = NEW.id;\n  END;\n\n-- Utility terminals (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS utils (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  terminal_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Annotations / file viewers (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS annotations (\n  id TEXT PRIMARY KEY,\n  file TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  parent_type TEXT NOT NULL CHECK(parent_type IN ('architect', 'builder', 'util')),\n  parent_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n";
+export declare const GLOBAL_SCHEMA = "\n-- Schema versioning\nCREATE TABLE IF NOT EXISTS _migrations (\n  version INTEGER PRIMARY KEY,\n  applied_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Terminal sessions (Spec 0090 TICK-001)\n-- Tracks all terminal sessions across all workspaces for persistence and reconciliation\nCREATE TABLE IF NOT EXISTS terminal_sessions (\n  id TEXT PRIMARY KEY,                    -- terminal UUID from PtyManager\n  workspace_path TEXT NOT NULL,           -- workspace this terminal belongs to\n  type TEXT NOT NULL                      -- 'architect', 'builder', 'shell'\n    CHECK(type IN ('architect', 'builder', 'shell')),\n  role_id TEXT,                           -- builder ID or shell ID (null for architect)\n  pid INTEGER,                            -- process ID of the terminal\n  shellper_socket TEXT,                   -- Unix socket path for shellper process\n  shellper_pid INTEGER,                   -- shellper process PID\n  shellper_start_time INTEGER,            -- shellper process start time (epoch ms)\n  label TEXT,                             -- custom display label (Spec 468)\n  cwd TEXT,                               -- working directory of the terminal (Bugfix #506)\n  command TEXT,                           -- launch command; render-gate identity seam (Spec 1313)\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_workspace ON terminal_sessions(workspace_path);\nCREATE INDEX IF NOT EXISTS idx_terminal_sessions_type ON terminal_sessions(type);\n\n-- File tabs (Spec 0099 Phase 4)\nCREATE TABLE IF NOT EXISTS file_tabs (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  file_path TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_file_tabs_workspace ON file_tabs(workspace_path);\n\n-- Known workspaces (persistent workspace registry)\nCREATE TABLE IF NOT EXISTS known_workspaces (\n  workspace_path TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  last_launched_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Cron tasks (Spec 399)\n-- Tracks scheduled task state across all workspaces\nCREATE TABLE IF NOT EXISTS cron_tasks (\n  id TEXT PRIMARY KEY,\n  workspace_path TEXT NOT NULL,\n  task_name TEXT NOT NULL,\n  last_run INTEGER,\n  last_result TEXT,\n  last_output TEXT,\n  enabled INTEGER NOT NULL DEFAULT 1,\n  UNIQUE(workspace_path, task_name)\n);\n\n-- ===========================================================================\n-- Issue #1118: tables absorbed from the retired per-workspace state.db.\n-- architect/utils/annotations move as-is; builders is RESHAPED to be\n-- workspace-scoped (composite PK), mirroring architect (Bugfix #826) \u2014 builder\n-- ids are <protocol>-<issueNumber>, unique within a workspace but reused across\n-- repos, so a single shared table must disambiguate by workspace_path.\n-- ===========================================================================\n\n-- Architect sessions (Spec 755 multi-architect; Bugfix #826 workspace-scoped;\n-- Issue #832 session_id). id is the architect's name ('main', siblings).\nCREATE TABLE IF NOT EXISTS architect (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  pid INTEGER NOT NULL,\n  port INTEGER NOT NULL,\n  cmd TEXT NOT NULL,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  terminal_id TEXT,\n  session_id TEXT,\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_architect_workspace ON architect(workspace_path);\n\n-- Builder sessions. Issue #1118: workspace_path + composite PK so the same\n-- builder id can exist in multiple workspaces without collision.\nCREATE TABLE IF NOT EXISTS builders (\n  workspace_path TEXT NOT NULL,\n  id TEXT NOT NULL,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  status TEXT NOT NULL DEFAULT 'spawning'\n    CHECK(status IN ('spawning', 'implementing', 'blocked', 'pr', 'complete')),\n  phase TEXT NOT NULL DEFAULT '',\n  worktree TEXT NOT NULL,\n  branch TEXT NOT NULL,\n  type TEXT NOT NULL DEFAULT 'spec'\n    CHECK(type IN ('spec', 'task', 'protocol', 'shell', 'worktree', 'bugfix', 'pir')),\n  task_text TEXT,\n  protocol_name TEXT,\n  issue_number TEXT,\n  terminal_id TEXT,\n  spawned_by_architect TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY (workspace_path, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_builders_status ON builders(status);\nCREATE INDEX IF NOT EXISTS idx_builders_port ON builders(port);\n\nCREATE TRIGGER IF NOT EXISTS builders_updated_at\n  AFTER UPDATE ON builders\n  FOR EACH ROW\n  BEGIN\n    UPDATE builders SET updated_at = datetime('now')\n      WHERE workspace_path = NEW.workspace_path AND id = NEW.id;\n  END;\n\n-- Utility terminals (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS utils (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  terminal_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Annotations / file viewers (UUID-keyed; moved as-is).\nCREATE TABLE IF NOT EXISTS annotations (\n  id TEXT PRIMARY KEY,\n  file TEXT NOT NULL,\n  port INTEGER NOT NULL DEFAULT 0,\n  pid INTEGER NOT NULL DEFAULT 0,\n  parent_type TEXT NOT NULL CHECK(parent_type IN ('architect', 'builder', 'util')),\n  parent_id TEXT,\n  started_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- Mailbox (Spec 1313): durable home for every 'afx send'.\n-- Persist-first delivery \u2014 a row is written before the send response returns, so\n-- nothing is lost to a Tower crash/restart/shutdown (the retired in-memory\n-- SendBuffer lost held messages on both). Rows address AGENTS (to_agent within\n-- workspace_path), not PTYs, so a respawned terminal drains its predecessor's\n-- mail. Delivery is authorized elsewhere by the render-gate (Phases 2/4); this\n-- table is pure durable state. Timestamps are epoch-ms integers (not SQLite\n-- datetime) so ordering and age math are trivial. Additive new table \u2014 fresh\n-- installs get it here; existing installs get it from migration v15.\nCREATE TABLE IF NOT EXISTS mailbox (\n  id TEXT PRIMARY KEY,                    -- uuid\n  workspace_path TEXT NOT NULL,           -- addressing scope\n  to_agent TEXT NOT NULL,                 -- recipient agent identity (drains across respawn)\n  terminal_id TEXT,                       -- last-known PTY hint (nullable; not the identity)\n  from_agent TEXT,\n  from_workspace TEXT,\n  body TEXT NOT NULL,                     -- raw message (never logged)\n  formatted_message TEXT NOT NULL,        -- what gets written to the PTY\n  no_enter INTEGER NOT NULL DEFAULT 0,\n  status TEXT NOT NULL DEFAULT 'held'\n    CHECK(status IN ('held', 'delivered', 'superseded', 'dismissed')),\n  reason TEXT CHECK(reason IN ('busy', 'no-profile', 'no-live-pty')),  -- why-held; null once delivered\n  supersede_key TEXT,                     -- cron-only; null for direct sends\n  escalated INTEGER NOT NULL DEFAULT 0,   -- set once escalation age crossed (visibility only)\n  not_before INTEGER,                     -- epoch ms; delayed-send due time (Spec 1313 round 3, --delay). null = deliver ASAP; a row is deliverable only when not_before IS NULL OR not_before <= now\n  created_at INTEGER NOT NULL,            -- epoch ms (enqueue order per agent)\n  updated_at INTEGER NOT NULL,\n  resolved_at INTEGER                     -- delivered/superseded/dismissed timestamp\n);\n\nCREATE INDEX IF NOT EXISTS idx_mailbox_workspace_status ON mailbox(workspace_path, status);\nCREATE INDEX IF NOT EXISTS idx_mailbox_agent_drain ON mailbox(workspace_path, to_agent, status);\nCREATE INDEX IF NOT EXISTS idx_mailbox_supersede ON mailbox(supersede_key);\n";
 //# sourceMappingURL=schema.d.ts.map

package/dist/agent-farm/db/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,0gGAqFxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,mvKAyIzB,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,0gGAqFxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,4nPA4KzB,CAAC"}

package/dist/agent-farm/db/schema.js

@@ -125,6 +125,7 @@ CREATE TABLE IF NOT EXISTS terminal_sessions (
   shellper_start_time INTEGER,            -- shellper process start time (epoch ms)
   label TEXT,                             -- custom display label (Spec 468)
   cwd TEXT,                               -- working directory of the terminal (Bugfix #506)
+  command TEXT,                           -- launch command; render-gate identity seam (Spec 1313)
   created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
@@ -241,5 +242,39 @@ CREATE TABLE IF NOT EXISTS annotations (
   parent_id TEXT,
   started_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
+
+-- Mailbox (Spec 1313): durable home for every 'afx send'.
+-- Persist-first delivery — a row is written before the send response returns, so
+-- nothing is lost to a Tower crash/restart/shutdown (the retired in-memory
+-- SendBuffer lost held messages on both). Rows address AGENTS (to_agent within
+-- workspace_path), not PTYs, so a respawned terminal drains its predecessor's
+-- mail. Delivery is authorized elsewhere by the render-gate (Phases 2/4); this
+-- table is pure durable state. Timestamps are epoch-ms integers (not SQLite
+-- datetime) so ordering and age math are trivial. Additive new table — fresh
+-- installs get it here; existing installs get it from migration v15.
+CREATE TABLE IF NOT EXISTS mailbox (
+  id TEXT PRIMARY KEY,                    -- uuid
+  workspace_path TEXT NOT NULL,           -- addressing scope
+  to_agent TEXT NOT NULL,                 -- recipient agent identity (drains across respawn)
+  terminal_id TEXT,                       -- last-known PTY hint (nullable; not the identity)
+  from_agent TEXT,
+  from_workspace TEXT,
+  body TEXT NOT NULL,                     -- raw message (never logged)
+  formatted_message TEXT NOT NULL,        -- what gets written to the PTY
+  no_enter INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL DEFAULT 'held'
+    CHECK(status IN ('held', 'delivered', 'superseded', 'dismissed')),
+  reason TEXT CHECK(reason IN ('busy', 'no-profile', 'no-live-pty')),  -- why-held; null once delivered
+  supersede_key TEXT,                     -- cron-only; null for direct sends
+  escalated INTEGER NOT NULL DEFAULT 0,   -- set once escalation age crossed (visibility only)
+  not_before INTEGER,                     -- epoch ms; delayed-send due time (Spec 1313 round 3, --delay). null = deliver ASAP; a row is deliverable only when not_before IS NULL OR not_before <= now
+  created_at INTEGER NOT NULL,            -- epoch ms (enqueue order per agent)
+  updated_at INTEGER NOT NULL,
+  resolved_at INTEGER                     -- delivered/superseded/dismissed timestamp
+);
+
+CREATE INDEX IF NOT EXISTS idx_mailbox_workspace_status ON mailbox(workspace_path, status);
+CREATE INDEX IF NOT EXISTS idx_mailbox_agent_drain ON mailbox(workspace_path, to_agent, status);
+CREATE INDEX IF NOT EXISTS idx_mailbox_supersede ON mailbox(supersede_key);
 `;
 //# sourceMappingURL=schema.js.map

package/dist/agent-farm/db/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqF3B,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyI5B,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/agent-farm/db/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqF3B,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4K5B,CAAC"}