@cluesmith/codev 3.2.3 → 3.3.0

package/dist/agent-farm/servers/mailbox-wiring.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Live-Tower wiring for mailbox delivery (Spec 1313, Phase 4).
+ *
+ * `mailbox-delivery.ts` holds the PURE orchestration (persist → gate → deliver |
+ * hold) behind the {@link DeliveryPorts} seam. This module binds those ports to
+ * the real Tower — the live terminal registry, the render-gate, paced PTY writes,
+ * and the WebSocket message bus — and owns the backstop drainer's lifecycle,
+ * which replaces the retired in-memory `SendBuffer`.
+ *
+ * Keeping the wiring here (not in the pure module) is what lets the orchestration
+ * be unit-tested without a live Tower, and lets `handleSend` and the drainer share
+ * exactly one delivery path (and one per-agent write serializer).
+ */
+import { type PtySession } from '../../terminal/pty-session.js';
+import { type GateProfile, type GateVerdict } from './render-gate.js';
+import { MailboxDrainer, type DeliveryPorts, type DeliverySession } from './mailbox-delivery.js';
+type LogFn = (level: 'INFO' | 'ERROR' | 'WARN', message: string) => void;
+/**
+ * The SSE broadcast fn (Tower's `broadcastNotification`), wired once at boot via
+ * {@link setMailboxBroadcaster}. Mirrors `codev-config-watcher.ts`'s
+ * `setCodevConfigNotifier` pattern: the pure delivery module and the boot-time drainer
+ * have no `RouteContext`, so the two held-set SSE events they raise
+ * (`overview-changed` on a held-state change, `mailbox-escalation` on an age crossing)
+ * are fanned out through this module singleton instead. Undefined until boot wires it,
+ * so `makeDeliveryPorts` is safe to call before Tower is up (unit tests never set it,
+ * making the ports genuine no-ops).
+ */
+type MailboxBroadcastFn = (n: {
+    type: string;
+    title: string;
+    body: string;
+    workspace?: string;
+}) => void;
+/** Wire the SSE broadcast fn once at Tower startup (see {@link MailboxBroadcastFn}). */
+export declare function setMailboxBroadcaster(fn: MailboxBroadcastFn): void;
+/**
+ * The live, writable {@link PtySession} for an agent in a workspace, or `null`
+ * when there is no usable live PTY — unknown agent, an exited session (the
+ * PtyManager keeps an exited session for 30 s, so a stale hit is still filtered
+ * here), or a session whose shellper connection is down (#1198). A `null` result
+ * makes the delivery hold `no-live-pty` rather than write into the void.
+ *
+ * `toAgent` is the canonical identity stored on the row (a builder id or a
+ * specific architect name), so an exact key match against the routing sub-maps is
+ * correct — and because rows address the AGENT, a respawned terminal (new id, same
+ * builder id) transparently drains its predecessor's held mail.
+ */
+export declare function resolveLiveSessionForAgent(workspacePath: string, toAgent: string): PtySession | null;
+/**
+ * The inverse of {@link resolveLiveSessionForAgent}: reverse-map a live session id to
+ * the agent it serves (`{ workspacePath, toAgent }`), or `null` when the id belongs to
+ * no registered agent — a plain shell nobody addresses, or a session already torn
+ * down. Drives the Phase 5 fast triggers: a submit/quiescence signal carries only the
+ * session id, and delivery is keyed on the canonical agent, so the id must be resolved
+ * back before scheduling a drain. Iterates the routing registry (agents per active
+ * workspace — small) which is cheap at trigger frequency and coalesced downstream. The
+ * agent name it returns is the same canonical identity the row is addressed to, so a
+ * respawned terminal's signal still resolves to the right held mail.
+ */
+export declare function resolveAgentForSession(sessionId: string): {
+    workspacePath: string;
+    toAgent: string;
+} | null;
+/**
+ * The classifier profile for a session, resolving the wrapped-launch case. A real
+ * builder runs through `.builder-start.sh`, so `session.command` is the shell, not
+ * the agent, and the pure {@link resolveProfile} returns `null`. We then read the
+ * launch script (exactly as `afx reset` does) to recover the underlying harness
+ * command and resolve against that. Still `null` → the delivery holds `no-profile`
+ * (fail-safe by construction: an unknown agent is held and surfaced, never guessed
+ * — this is what correctly trips on wrapper/boot/relaunch screens too).
+ *
+ * Stale-identity note (Spec 1313): `session.command` is now sourced from the
+ * persisted `terminal_sessions.command` on reconnect. If it ever goes stale (a
+ * user re-points `shell.architect` at a different harness and the shellper later
+ * auto-restarts into it while the row still names the old one), this can resolve
+ * the WRONG profile — but it fails CLOSED today, not misdelivered: CLAUDE_PROFILE
+ * and CODEX_PROFILE are behaviourally identical (same marker + region patterns),
+ * and any cross-family mismatch (e.g. agy's `> ` marker) fails the composer-marker
+ * test → not clean → held. That safety is a property of the current profile TABLE,
+ * not of this design; the day codex/claude markers diverge, stale identity becomes
+ * a live bug and the authoritative fix is WELCOME-frame hydration (see review).
+ */
+export declare function resolveProfileForSession(session: DeliverySession): GateProfile | null;
+/**
+ * Classify a session's CURRENT screen for the gate (Spec 1313 render-gate round 2). Reads the
+ * session's persistent {@link SessionScreen} mirror — a bounded headless Terminal fed the
+ * session's output from birth — and runs the shared classifier on its viewport. This replaces
+ * the old whole-ring re-render (`classifyScreen(ringBuffer.getAll()…)`), which #1205's 2 MiB
+ * partial cap could hand a TORN frame → a permanent false-`busy` hold for the busiest agents.
+ *
+ * The delivery path only ever calls this with a live session resolved by
+ * {@link resolveLiveSessionForAgent} — always a `PtySession`, which carries the mirror — so the
+ * cast is sound. A session that has produced NO output yet has no mirror (`gateScreen` is null);
+ * that is not a verified-empty prompt, so it classifies not-clean (`no-composer-marker`), exactly
+ * as an empty replay always did. `SessionScreen.read()` flushes the parser, so the buffer the
+ * shared {@link classifyBuffer} reads reflects every byte counted by the change token the
+ * delivery path sampled — the property its gate→write TOCTOU relies on.
+ */
+export declare function classifyAgentScreen(session: DeliverySession, profile: GateProfile): Promise<GateVerdict>;
+/**
+ * Build the {@link DeliveryPorts} bound to the live Tower. Cheap (closures over
+ * module singletons), so `handleSend` may construct one per request and the
+ * drainer one at boot; the shared state that matters (the per-agent write
+ * serializer) lives in `mailbox-delivery.ts`, not here.
+ */
+export declare function makeDeliveryPorts(log: LogFn): DeliveryPorts;
+/**
+ * Start the mailbox drainer (replaces `startSendBuffer`). Called once on Tower boot:
+ * prunes terminal rows, begins the periodic held-row backstop that redelivers on the
+ * first clean gate after a line clears, and subscribes the Phase 5 fast triggers so a
+ * held message drains within a microtask of a user submit or output quiescence rather
+ * than waiting for the next backstop tick.
+ */
+export declare function startMailboxDrainer(log: LogFn): void;
+/**
+ * Stop the mailbox drainer (replaces `stopSendBuffer`). Detaches the fast triggers and
+ * stops the backstop timer — there is NO shutdown force-flush, because every held row
+ * is already persisted in SQLite and will be redelivered after restart on a clean gate.
+ */
+export declare function stopMailboxDrainer(): void;
+/** The live drainer (liveness-telemetry streaks; Phase 7 surfaces them). */
+export declare function getMailboxDrainer(): MailboxDrainer;
+export {};
+//# sourceMappingURL=mailbox-wiring.d.ts.map

package/dist/agent-farm/servers/mailbox-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-wiring.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/mailbox-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAIzF,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQtF,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EAKrB,MAAM,uBAAuB,CAAC;AAa/B,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzE;;;;;;;;;GASG;AACH,KAAK,kBAAkB,GAAG,CAAC,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAGzG,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI,CAElE;AA2BD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAQpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAChB;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASnD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,GAAG,IAAI,CAMrF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAK9G;AAcD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,KAAK,GAAG,aAAa,CAe3D;AAwND;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,IAAI,cAAc,CAElD"}

package/dist/agent-farm/servers/mailbox-wiring.js

@@ -0,0 +1,425 @@
+/**
+ * Live-Tower wiring for mailbox delivery (Spec 1313, Phase 4).
+ *
+ * `mailbox-delivery.ts` holds the PURE orchestration (persist → gate → deliver |
+ * hold) behind the {@link DeliveryPorts} seam. This module binds those ports to
+ * the real Tower — the live terminal registry, the render-gate, paced PTY writes,
+ * and the WebSocket message bus — and owns the backstop drainer's lifecycle,
+ * which replaces the retired in-memory `SendBuffer`.
+ *
+ * Keeping the wiring here (not in the pure module) is what lets the orchestration
+ * be unit-tested without a live Tower, and lets `handleSend` and the drainer share
+ * exactly one delivery path (and one per-agent write serializer).
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { loadConfig } from '../../lib/config.js';
+import { terminalDeliverySignals } from '../../terminal/pty-session.js';
+import { getWorkspaceTerminals, getTerminalManager } from './tower-terminals.js';
+import { broadcastMessage, resolveAgentInRegistry, isResolveError } from './tower-messages.js';
+import { writeMessagePaced } from './message-write.js';
+import { classifyBuffer } from './render-gate.js';
+import { resolveProfile } from './gate-profiles.js';
+import { harnessFromLaunchScript } from '../commands/reset/context.js';
+import { getGlobalDb } from '../db/index.js';
+import { getArchitectByName } from '../state.js';
+import { formatBuilderMessage } from '../utils/message-format.js';
+import { supersede as supersedeMailbox, dismissHeldWithKey, NOTICE_SUPERSEDE_PREFIX } from '../db/mailbox.js';
+import path from 'node:path';
+import { MailboxDrainer, } from './mailbox-delivery.js';
+/**
+ * "Recent output" window for the liveness diagnostic (Spec 1313, Phase 7 — spec line
+ * 91). A `no-profile` streak only raises the loud log/broadcast when the session emitted
+ * output within this window: that distinguishes a genuinely broken/unknown classifier on
+ * a LIVE, producing app (worth alarming) from a dormant unknown session (still visible in
+ * `afx inbox`, but no loud alarm). Sized well above the streak's own duration
+ * (threshold × backstop interval ≈ 15s) so an actively-failing app comfortably qualifies.
+ */
+const LIVENESS_RECENT_OUTPUT_MS = 30_000;
+let mailboxBroadcaster;
+/** Wire the SSE broadcast fn once at Tower startup (see {@link MailboxBroadcastFn}). */
+export function setMailboxBroadcaster(fn) {
+    mailboxBroadcaster = fn;
+}
+/**
+ * A node-fs adapter for {@link harnessFromLaunchScript}. Only `.read` is exercised
+ * by that function, but `exists`/`listDirs` are implemented faithfully so the port
+ * is honest and reusable rather than a lying stub.
+ */
+const NODE_FS_PORT = {
+    exists: (p) => existsSync(p),
+    read: (p) => {
+        try {
+            return readFileSync(p, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    },
+    listDirs: (p) => {
+        try {
+            return readdirSync(p, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => d.name);
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * The live, writable {@link PtySession} for an agent in a workspace, or `null`
+ * when there is no usable live PTY — unknown agent, an exited session (the
+ * PtyManager keeps an exited session for 30 s, so a stale hit is still filtered
+ * here), or a session whose shellper connection is down (#1198). A `null` result
+ * makes the delivery hold `no-live-pty` rather than write into the void.
+ *
+ * `toAgent` is the canonical identity stored on the row (a builder id or a
+ * specific architect name), so an exact key match against the routing sub-maps is
+ * correct — and because rows address the AGENT, a respawned terminal (new id, same
+ * builder id) transparently drains its predecessor's held mail.
+ */
+export function resolveLiveSessionForAgent(workspacePath, toAgent) {
+    const entry = getWorkspaceTerminals().get(workspacePath);
+    if (!entry)
+        return null;
+    const tid = entry.builders.get(toAgent) ?? entry.architects.get(toAgent) ?? entry.shells.get(toAgent);
+    if (!tid)
+        return null;
+    const session = getTerminalManager().getSession(tid);
+    if (!session || !session.writable)
+        return null;
+    return session;
+}
+/**
+ * The inverse of {@link resolveLiveSessionForAgent}: reverse-map a live session id to
+ * the agent it serves (`{ workspacePath, toAgent }`), or `null` when the id belongs to
+ * no registered agent — a plain shell nobody addresses, or a session already torn
+ * down. Drives the Phase 5 fast triggers: a submit/quiescence signal carries only the
+ * session id, and delivery is keyed on the canonical agent, so the id must be resolved
+ * back before scheduling a drain. Iterates the routing registry (agents per active
+ * workspace — small) which is cheap at trigger frequency and coalesced downstream. The
+ * agent name it returns is the same canonical identity the row is addressed to, so a
+ * respawned terminal's signal still resolves to the right held mail.
+ */
+export function resolveAgentForSession(sessionId) {
+    for (const [workspacePath, entry] of getWorkspaceTerminals()) {
+        for (const registry of [entry.builders, entry.architects, entry.shells]) {
+            for (const [agent, tid] of registry) {
+                if (tid === sessionId)
+                    return { workspacePath, toAgent: agent };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The classifier profile for a session, resolving the wrapped-launch case. A real
+ * builder runs through `.builder-start.sh`, so `session.command` is the shell, not
+ * the agent, and the pure {@link resolveProfile} returns `null`. We then read the
+ * launch script (exactly as `afx reset` does) to recover the underlying harness
+ * command and resolve against that. Still `null` → the delivery holds `no-profile`
+ * (fail-safe by construction: an unknown agent is held and surfaced, never guessed
+ * — this is what correctly trips on wrapper/boot/relaunch screens too).
+ *
+ * Stale-identity note (Spec 1313): `session.command` is now sourced from the
+ * persisted `terminal_sessions.command` on reconnect. If it ever goes stale (a
+ * user re-points `shell.architect` at a different harness and the shellper later
+ * auto-restarts into it while the row still names the old one), this can resolve
+ * the WRONG profile — but it fails CLOSED today, not misdelivered: CLAUDE_PROFILE
+ * and CODEX_PROFILE are behaviourally identical (same marker + region patterns),
+ * and any cross-family mismatch (e.g. agy's `> ` marker) fails the composer-marker
+ * test → not clean → held. That safety is a property of the current profile TABLE,
+ * not of this design; the day codex/claude markers diverge, stale identity becomes
+ * a live bug and the authoritative fix is WELCOME-frame hydration (see review).
+ */
+export function resolveProfileForSession(session) {
+    const direct = resolveProfile({ command: session.command, args: session.launchArgs });
+    if (direct)
+        return direct;
+    const harness = harnessFromLaunchScript(NODE_FS_PORT, session.cwd);
+    if (!harness)
+        return null;
+    return resolveProfile({ command: harness });
+}
+/**
+ * Classify a session's CURRENT screen for the gate (Spec 1313 render-gate round 2). Reads the
+ * session's persistent {@link SessionScreen} mirror — a bounded headless Terminal fed the
+ * session's output from birth — and runs the shared classifier on its viewport. This replaces
+ * the old whole-ring re-render (`classifyScreen(ringBuffer.getAll()…)`), which #1205's 2 MiB
+ * partial cap could hand a TORN frame → a permanent false-`busy` hold for the busiest agents.
+ *
+ * The delivery path only ever calls this with a live session resolved by
+ * {@link resolveLiveSessionForAgent} — always a `PtySession`, which carries the mirror — so the
+ * cast is sound. A session that has produced NO output yet has no mirror (`gateScreen` is null);
+ * that is not a verified-empty prompt, so it classifies not-clean (`no-composer-marker`), exactly
+ * as an empty replay always did. `SessionScreen.read()` flushes the parser, so the buffer the
+ * shared {@link classifyBuffer} reads reflects every byte counted by the change token the
+ * delivery path sampled — the property its gate→write TOCTOU relies on.
+ */
+export async function classifyAgentScreen(session, profile) {
+    const screen = session.gateScreen;
+    if (!screen)
+        return { clean: false, reason: 'busy', detail: 'no-composer-marker' };
+    const { term, cols, rows } = await screen.read();
+    return classifyBuffer(term, cols, rows, profile);
+}
+/** Convert a delivered-message frame to the WebSocket bus shape and broadcast it. */
+function broadcastDelivered(frame) {
+    broadcastMessage({
+        type: 'message',
+        from: { project: frame.from.project ?? 'unknown', agent: frame.from.agent ?? 'unknown' },
+        to: frame.to,
+        content: frame.content,
+        metadata: { source: 'mailbox' },
+        timestamp: new Date(frame.timestamp).toISOString(),
+    });
+}
+/**
+ * Build the {@link DeliveryPorts} bound to the live Tower. Cheap (closures over
+ * module singletons), so `handleSend` may construct one per request and the
+ * drainer one at boot; the shared state that matters (the per-agent write
+ * serializer) lives in `mailbox-delivery.ts`, not here.
+ */
+export function makeDeliveryPorts(log) {
+    return {
+        getSessionForAgent: (ws, agent) => resolveLiveSessionForAgent(ws, agent),
+        resolveProfile: (session) => resolveProfileForSession(session),
+        classify: (session, profile) => classifyAgentScreen(session, profile),
+        writeMessage: (session, msg, noEnter) => writeMessagePaced(session, msg, noEnter),
+        broadcast: (frame) => broadcastDelivered(frame),
+        onHeldStateChange: () => broadcastHeldStateChange(),
+        onEscalation: (info) => broadcastEscalation(info),
+        onLiveness: (info) => surfaceLiveness(info, log),
+        escalateHeldToOwner: (info) => escalateHeldToOwner(info, log),
+        clearHeldOwnerNotice: (ws, agent) => clearHeldOwnerNotice(ws, agent),
+        log: (m) => log('INFO', m),
+        now: () => Date.now(),
+    };
+}
+/** Pseudo-sender identity for owner starvation notices (Spec 1313 round 3, change 3). */
+const NOTICE_SENDER = 'af-mailbox';
+/** Supersede key for the single pending owner notice ABOUT a starving `toAgent`. */
+function noticeSupersedeKey(toAgent) {
+    return `${NOTICE_SUPERSEDE_PREFIX}${toAgent}`;
+}
+/** Human-readable notice body (metadata only — never the starved messages' contents). */
+function formatOwnerNoticeBody(info) {
+    const mins = Math.max(1, Math.round(info.ageMs / 60_000));
+    const plural = info.heldCount === 1 ? 'message' : 'messages';
+    return (`Mailbox delivery is STUCK for builder '${info.toAgent}' @ ${path.basename(info.workspacePath)}. ` +
+        `${info.heldCount} ${plural} held ~${mins}m (reason: ${info.reason ?? 'held'}) — its composer never classifies as a ready prompt, ` +
+        `so nothing is being delivered (cron nudges included). ` +
+        `Remedy: run 'afx inbox' to inspect; 'afx interrupt ${info.toAgent}' clears a stuck composer.`);
+}
+/**
+ * Raise a starvation notice to a starving agent's OWNER architect (Spec 1313 round 3, change
+ * 3). Skips agents that are themselves architects — the alarm would land in the same starved
+ * mailbox, and `afx status` covers that case. Resolves the recipient EXACTLY as `afx send
+ * architect` does — the starving builder's spawning architect (affinity), else the workspace's
+ * `main`, else the first-registered architect — via the shared registry resolver. Then enqueues
+ * ONE coalesced (supersede-keyed), GATE-delivered mailbox row: visibility only, never a force
+ * path. No-op when no architect can be resolved (nowhere to send).
+ *
+ * RETURNS `true` iff a notice row was enqueued; `false` on every no-op path (recipient is
+ * itself an architect / no architect resolvable / would notify the agent about itself). The
+ * drainer arms its once-per-episode guard only on `true`, so a no-op retries next tick rather
+ * than silently suppressing the alarm for the episode.
+ */
+function escalateHeldToOwner(info, log) {
+    // An architect-addressed row gets no notice (it would starve in the same mailbox).
+    if (getArchitectByName(info.workspacePath, info.toAgent))
+        return false;
+    // Resolve the owner architect the same way `afx send architect` does (bare `architect` form
+    // with the starving builder as sender → spawning affinity, else main, else first).
+    const owner = resolveAgentInRegistry('architect', info.workspacePath, info.toAgent);
+    if (isResolveError(owner)) {
+        log('INFO', `[mailbox] starvation notice for ${info.toAgent} skipped: no architect to notify (${owner.message})`);
+        return false;
+    }
+    if (owner.agent === info.toAgent)
+        return false; // defensive: never notify an agent about itself
+    const body = formatOwnerNoticeBody(info);
+    supersedeMailbox(getGlobalDb(), info.workspacePath, noticeSupersedeKey(info.toAgent), {
+        workspacePath: info.workspacePath,
+        toAgent: owner.agent,
+        body,
+        formattedMessage: formatBuilderMessage(NOTICE_SENDER, body),
+        fromAgent: NOTICE_SENDER,
+        fromWorkspace: info.workspacePath,
+    });
+    broadcastHeldStateChange();
+    // Deliver the notice promptly through the SAME gate (it holds if the architect is busy).
+    void ensureDrainer().scheduleDrain(owner.workspacePath, owner.agent);
+    log('WARN', `[mailbox] STARVATION notice → ${owner.agent} about ${info.toAgent} @ ${path.basename(info.workspacePath)} ` +
+        `(${info.heldCount} held ~${Math.round(info.ageMs / 1000)}s, reason ${info.reason ?? 'held'})`);
+    return true;
+}
+/**
+ * Clear (dismiss) any still-held owner notice about `toAgent` once its starvation is over
+ * (Spec 1313 round 3). A no-op on an already-delivered notice — the architect already saw it.
+ */
+function clearHeldOwnerNotice(workspacePath, toAgent) {
+    const dismissed = dismissHeldWithKey(getGlobalDb(), workspacePath, noticeSupersedeKey(toAgent));
+    if (dismissed > 0)
+        broadcastHeldStateChange();
+}
+/**
+ * Fire the `overview-changed` SSE event so the held-count indicator refetches its
+ * count (Spec 1313, Phase 7). Cheap and idempotent (it only triggers a refetch), so
+ * the delivery path fires it freely on any held-set change. No-op until the broadcaster
+ * is wired at boot.
+ */
+function broadcastHeldStateChange() {
+    mailboxBroadcaster?.({
+        type: 'overview-changed',
+        title: 'Held mail changed',
+        body: 'Mailbox held-set changed',
+    });
+}
+/**
+ * Fire the `mailbox-escalation` SSE event when a held row crosses the escalation age
+ * (Spec 1313, Phase 7) — a VISIBILITY signal that moves the dashboard/VSCode indicator
+ * into its attention state; it never triggers delivery. Carries metadata only (ids +
+ * age + reason), never the message body, per the spec's redaction rule. No-op until the
+ * broadcaster is wired at boot.
+ */
+function broadcastEscalation(info) {
+    const payload = {
+        workspacePath: info.workspacePath,
+        toAgent: info.toAgent,
+        mailboxId: info.mailboxId,
+        ageMs: info.ageMs,
+        reason: info.reason,
+    };
+    mailboxBroadcaster?.({
+        type: 'mailbox-escalation',
+        title: 'Message held past escalation age',
+        body: JSON.stringify(payload),
+        workspace: info.workspacePath,
+    });
+}
+/**
+ * Surface the liveness diagnostic (Spec 1313, Phase 7 — spec line 91). Applies the spec's
+ * "with recent output" gate: only when the agent's live session emitted output within
+ * {@link LIVENESS_RECENT_OUTPUT_MS} — proving a genuinely broken/unknown classifier on a
+ * PRODUCING app, not a dormant unknown session — does it raise the loud log AND a broadcast.
+ * The broadcast rides the existing generic `notification` SSE channel (human title/body, no
+ * body-of-message), so it is immediately visible in the dashboard's notification surface
+ * without any new event type or client wiring. An idle unknown session raises nothing here —
+ * its held row is still discoverable in `afx inbox`, per the metadata-only visibility model.
+ */
+function surfaceLiveness(info, log) {
+    const session = resolveLiveSessionForAgent(info.workspacePath, info.toAgent);
+    const hasRecentOutput = session != null && Date.now() - session.lastDataAt <= LIVENESS_RECENT_OUTPUT_MS;
+    if (!hasRecentOutput)
+        return; // dormant unknown session → no loud alarm (still in `afx inbox`)
+    const where = `${info.toAgent} @ ${path.basename(info.workspacePath)}`;
+    log('WARN', `[mailbox] LIVENESS: ${where} held no-profile for ${info.streak} consecutive checks with recent output — ` +
+        `unrecognized app; its mail will not deliver until a classifier profile matches (check for a TUI update)`);
+    mailboxBroadcaster?.({
+        type: 'notification',
+        title: 'Mailbox: delivery blocked (unrecognized app)',
+        body: `${where} — its screen never classifies as a ready prompt, so held messages will not deliver. A classifier profile may need updating.`,
+        workspace: info.workspacePath,
+    });
+}
+// The single backstop drainer instance (replaces the retired SendBuffer). Created
+// lazily so it picks up the configured retention window (below) at first use.
+let drainer;
+/**
+ * The terminal-row retention window (days) for the prune. This is a Tower-GLOBAL
+ * policy — the drainer prunes rows across every workspace in the user-global
+ * `global.db` — so it is read from the user-global `~/.codev/config.json` layer via
+ * `loadConfig` (rooted at home), not any single workspace's config. Spec default 30
+ * (already `DEFAULT_CONFIG.mailbox.retentionDays`). A malformed config never stops
+ * the drainer from booting — it falls back to the default.
+ */
+function configuredRetentionDays() {
+    try {
+        return loadConfig(homedir()).mailbox?.retentionDays ?? 30;
+    }
+    catch {
+        return 30;
+    }
+}
+/**
+ * The held-row escalation age in ms (Spec 1313, Phase 7). Like the retention window
+ * this is a Tower-GLOBAL policy read from the user-global config layer, default 60s
+ * (matching today's max-age; `DEFAULT_CONFIG.mailbox.escalationSeconds`). A malformed
+ * config never stops the drainer from booting — it falls back to the default.
+ */
+function configuredEscalationMs() {
+    try {
+        return (loadConfig(homedir()).mailbox?.escalationSeconds ?? 60) * 1000;
+    }
+    catch {
+        return 60_000;
+    }
+}
+function ensureDrainer() {
+    if (!drainer) {
+        drainer = new MailboxDrainer({
+            pruneRetentionDays: configuredRetentionDays(),
+            escalationMs: configuredEscalationMs(),
+        });
+    }
+    return drainer;
+}
+// Phase 5 fast-trigger bus handler. Held at module scope so `stopMailboxDrainer` can
+// detach it: re-subscribing on every start would accumulate duplicate listeners across
+// Tower restarts within one process (and the tests do start/stop/start).
+let deliverySignalHandler;
+/**
+ * Subscribe the fast submit/quiescence triggers (Spec 1313 Phase 5) to the drainer.
+ * Each signal names only the emitting session; we reverse-map it to its agent and
+ * schedule a coalesced, gated drain. Idempotent — a second call while already
+ * subscribed is a no-op, so the single-listener invariant (which arms the
+ * per-session quiescence timers) holds.
+ */
+function subscribeDeliverySignals() {
+    if (deliverySignalHandler)
+        return;
+    const handler = (sessionId) => {
+        const target = resolveAgentForSession(sessionId);
+        if (target)
+            void ensureDrainer().scheduleDrain(target.workspacePath, target.toAgent);
+    };
+    deliverySignalHandler = handler;
+    terminalDeliverySignals.on('submit', handler);
+    terminalDeliverySignals.on('quiescence', handler);
+}
+/** Detach the Phase 5 trigger handler so a subsequent start re-subscribes cleanly. */
+function unsubscribeDeliverySignals() {
+    if (!deliverySignalHandler)
+        return;
+    terminalDeliverySignals.off('submit', deliverySignalHandler);
+    terminalDeliverySignals.off('quiescence', deliverySignalHandler);
+    deliverySignalHandler = undefined;
+}
+/**
+ * Start the mailbox drainer (replaces `startSendBuffer`). Called once on Tower boot:
+ * prunes terminal rows, begins the periodic held-row backstop that redelivers on the
+ * first clean gate after a line clears, and subscribes the Phase 5 fast triggers so a
+ * held message drains within a microtask of a user submit or output quiescence rather
+ * than waiting for the next backstop tick.
+ */
+export function startMailboxDrainer(log) {
+    ensureDrainer().start(makeDeliveryPorts(log), getGlobalDb());
+    subscribeDeliverySignals();
+    log('INFO', '[mailbox] backstop drainer started');
+}
+/**
+ * Stop the mailbox drainer (replaces `stopSendBuffer`). Detaches the fast triggers and
+ * stops the backstop timer — there is NO shutdown force-flush, because every held row
+ * is already persisted in SQLite and will be redelivered after restart on a clean gate.
+ */
+export function stopMailboxDrainer() {
+    unsubscribeDeliverySignals();
+    drainer?.stop();
+}
+/** The live drainer (liveness-telemetry streaks; Phase 7 surfaces them). */
+export function getMailboxDrainer() {
+    return ensureDrainer();
+}
+//# sourceMappingURL=mailbox-wiring.js.map

package/dist/agent-farm/servers/mailbox-wiring.js.map

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

package/dist/agent-farm/servers/message-write.d.ts

@@ -6,8 +6,39 @@
  */
 /** Minimal writable session interface — avoids coupling to PtySession. */
 export interface WritableSession {
-    write(data: string): void;
+    /**
+     * Write input to the underlying PTY. Returns `false` when the write was dropped
+     * (#1198: a shellper-backed session whose socket has died still reports status
+     * 'running', yet its writes silently no-op). {@link writeMessagePaced} threads this
+     * boolean so a mailbox delivery whose bytes never reached the terminal is held, not
+     * marked delivered (Spec 1313 integration review — the silent-loss finding).
+     */
+    write(data: string): boolean;
 }
+/** ESC keystroke — ends the agent's current turn (Spec 1273). */
+export declare const ESC = "\u001B";
+/**
+ * Delay between the ESC and the Enter that follows it. Matches the short-message
+ * Enter delay: ESC has to be processed by the TUI before Enter is meaningful.
+ */
+export declare const ESCAPE_ENTER_DELAY_MS = 50;
+/**
+ * Write a bare ESC keystroke to a PTY session (Spec 1273).
+ *
+ * This is the verified mid-turn recovery for a wedged agent: ESC interrupts the
+ * running tool and ends the turn, after which queued messages process. It is the
+ * command form of `afx send <builder> --raw "$(printf '\x1b')"`.
+ *
+ * The trailing Enter is sent by default and is load-bearing, not incidental —
+ * it is what lets already-queued input through once ESC has ended the turn. Pass
+ * `noEnter` to write ESC alone.
+ *
+ * Deliberately not routed through `writeMessageToSession`: ESC is a control byte,
+ * not text, so line-pacing and paste-detection logic do not apply to it.
+ *
+ * @returns ms timestamp (from call time) when all writes complete
+ */
+export declare function writeEscapeToSession(session: WritableSession, noEnter: boolean): number;
 /**
  * Write a message to a PTY session, pacing multi-line output to prevent
  * the terminal from treating it as a paste (Bugfix #584).
@@ -21,4 +52,25 @@ export interface WritableSession {
  * @returns            ms timestamp (from call time) when all writes complete
  */
 export declare function writeMessageToSession(session: WritableSession, message: string, noEnter: boolean, delayOffset?: number): number;
+/**
+ * Paced write of a message (text + trailing Enter unless `noEnter`) that reports
+ * whether every byte reached the PTY. Resolves `true` when the whole submit landed,
+ * `false` when ANY scheduled write was dropped (#1198: a shellper socket that died
+ * mid-pace). This is the delivery layer's authoritative success signal — a mailbox
+ * delivery holds a row whose bytes never made it instead of marking it delivered
+ * (Spec 1313 integration review — the silent-loss finding).
+ *
+ * `writeMessageToSession` fires the text, any subsequent lines, and the trailing
+ * Enter across `setTimeout` gaps (10–130ms+), and a t=0 `writable` precheck cannot
+ * see a socket that dies *during* that sequence. So wrap the session and record
+ * whether any of those writes returned false. The returned promise resolves at the
+ * final scheduled offset (`doneMs`); `writeMessageToSession` registers the Enter's
+ * `setTimeout` at that same offset *before* this resolve is scheduled, so the Enter
+ * executes first and its result is observed by resolution time.
+ *
+ * Awaiting the promise is also what makes the per-agent write serializer's
+ * completion-chaining real — the next delivery cannot begin until this submit
+ * (Enter included) is entirely on the wire.
+ */
+export declare function writeMessagePaced(session: WritableSession, message: string, noEnter: boolean): Promise<boolean>;
 //# sourceMappingURL=message-write.d.ts.map

package/dist/agent-farm/servers/message-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-write.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/message-write.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,SAAI,GAC3E,MAAM,CAqCR"}
+{"version":3,"file":"message-write.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/message-write.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAUD,iEAAiE;AACjE,eAAO,MAAM,GAAG,WAAS,CAAC;AAE1B;;;GAGG;AACH,eAAO,MAAM,qBAAqB,KAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAKvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,SAAI,GAC3E,MAAM,CAqCR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAC1D,OAAO,CAAC,OAAO,CAAC,CAWlB"}