@cluesmith/codev 3.2.3 → 3.3.0

package/dist/agent-farm/servers/architect-session-holder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architect-session-holder.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/architect-session-holder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5D;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAG/E;AAsBD,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAc5F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAgBnD;AAED,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,YAAY,EAAE,CAAC;CAC7B,GAAG,2BAA2B,CAqB9B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,YAAY,EAAE,CAAC;CAC7B,GAAG,MAAM,EAAE,CAcX;AA6BD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE;IACL,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;IACrD,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAE1F;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CAAC,IAAI,EAAE;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,YAAY,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C,GAAG,OAAO,CAAC;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA4B/D"}

package/dist/agent-farm/servers/architect-session-holder.js

@@ -0,0 +1,268 @@
+/**
+ * Issue #1224: detect and reclaim live processes that hold an architect's
+ * conversation session id, so an architect launch never bakes a colliding
+ * `claude --resume <id>` into a permanent crash loop.
+ *
+ * Two holder classes were observed after a workspace restart (forensic timeline
+ * on the issue):
+ *   1. OUR OWN superseded shellper for the same architect identity — a remnant
+ *      from before the restart, or a previous crash-looping instance. Its claude
+ *      child dies within seconds of every respawn, so the child is absent most
+ *      of the time; the durable evidence is the *shellper parent's* argv, which
+ *      carries the session id in its JSON config (`"--session-id","<id>"`).
+ *   2. A FOREIGN process — e.g. an interactive `claude` the user started by hand
+ *      on their own tty (holder case in incident 3). This must NEVER be touched:
+ *      it is not ours to kill.
+ *
+ * The policy: reclaim (kill + resume) only OUR OWN superseded shellper, proven
+ * by shellper-main.js + matching session id + matching cwd + matching
+ * CODEV_ARCHITECT_NAME. Anything else that holds the id is foreign → mint fresh.
+ */
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+/** Marker identifying a Codev shellper process in a `ps` command line. */
+const SHELLPER_MARKER = 'shellper-main.js';
+/**
+ * The session-flag needle forms a live holder's argv can carry the id in:
+ *   - `--session-id <id>` / `--resume <id>` — a claude CHILD's shell argv
+ *   - `--session-id=<id>` / `--resume=<id>` — the `=`-joined shell variant
+ *   - `"--session-id","<id>"` / `"--resume","<id>"` — the shellper PARENT's
+ *     JSON config argv (Issue #1224: catches a remnant shellper whose child is
+ *     dead between crash-loop respawns).
+ */
+export function sessionIdNeedles(sessionId) {
+    return ['--session-id', '--resume'].flatMap((flag) => [
+        `${flag} ${sessionId}`,
+        `${flag}=${sessionId}`,
+        `"${flag}","${sessionId}"`,
+    ]);
+}
+/** True when a process's argv references `sessionId` as a session-flag argument. */
+export function cmdlineHoldsSession(cmdline, sessionId) {
+    const needles = sessionIdNeedles(sessionId);
+    return needles.some((needle) => cmdline.includes(needle));
+}
+/** Canonicalize a path for comparison; fall back to the input when realpath fails. */
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Extract a `"key":"value"` string field from a shellper's JSON config as it
+ * appears verbatim in the `ps` argv. Regex rather than JSON.parse: the config
+ * embeds the full process env, so the blob is large and a partial/edge `ps`
+ * line must degrade to "field absent" rather than throw.
+ */
+function extractJsonStringField(cmdline, key) {
+    const m = cmdline.match(new RegExp(`"${key}"\\s*:\\s*"([^"]+)"`));
+    return m ? m[1] : null;
+}
+/**
+ * True when `cmdline` is one of OUR OWN shellper processes for `identity`:
+ * a `shellper-main.js` whose JSON config carries the matching workspace cwd and
+ * `CODEV_ARCHITECT_NAME`. The cwd match tolerates symlink variants (macOS
+ * `/tmp` vs `/private/tmp`), mirroring verifySessionOwnership.
+ *
+ * This is the airtight-identity gate before any kill: if any field cannot be
+ * positively confirmed, this returns false and the caller must not reclaim.
+ */
+export function isOwnArchitectShellper(cmdline, identity) {
+    if (!cmdline.includes(SHELLPER_MARKER))
+        return false;
+    const cfgName = extractJsonStringField(cmdline, 'CODEV_ARCHITECT_NAME');
+    if (cfgName !== identity.architectName)
+        return false;
+    const cfgCwd = extractJsonStringField(cmdline, 'cwd');
+    if (!cfgCwd)
+        return false;
+    const wanted = new Set([identity.workspacePath, realpathOrSelf(identity.workspacePath)]);
+    const got = new Set([cfgCwd, realpathOrSelf(cfgCwd)]);
+    const cwdMatches = [...got].some((g) => wanted.has(g));
+    if (!cwdMatches)
+        return false;
+    return true;
+}
+/**
+ * Snapshot every running process as {pid, cmdline}. `ps -ww` prevents argv
+ * truncation (the shellper config blob is large) on both BSD and coreutils.
+ * Throws on `ps` failure; callers decide how to degrade.
+ */
+export function listProcessEntries() {
+    const out = execFileSync('ps', ['-ww', '-eo', 'pid=,args='], {
+        encoding: 'utf-8',
+        timeout: 5000,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    const entries = [];
+    for (const line of out.split('\n')) {
+        const trimmed = line.trimStart();
+        const sp = trimmed.indexOf(' ');
+        if (sp <= 0)
+            continue;
+        const pid = parseInt(trimmed.slice(0, sp), 10);
+        if (Number.isNaN(pid) || pid <= 0)
+            continue;
+        entries.push({ pid, cmdline: trimmed.slice(sp + 1) });
+    }
+    return entries;
+}
+/**
+ * Classify every live holder of `sessionId` into reclaimable-own vs foreign.
+ * A holder is reclaimable only when it is one of our own architect shellpers
+ * (identity-matched); any other holder (a bare `claude`, a shellper for a
+ * different identity, an unparseable match) is foreign.
+ *
+ * On `ps` failure returns `{reclaimable: [], foreign: false}` — no positive
+ * evidence, so the caller resumes as it would have before this guard existed.
+ */
+export function classifyArchitectSessionHolder(opts) {
+    const list = opts.list ?? listProcessEntries;
+    let entries;
+    try {
+        entries = list();
+    }
+    catch {
+        return { reclaimable: [], foreign: false };
+    }
+    const reclaimable = [];
+    let foreign = false;
+    for (const { pid, cmdline } of entries) {
+        if (opts.selfPid !== undefined && pid === opts.selfPid)
+            continue;
+        if (!cmdlineHoldsSession(cmdline, opts.sessionId))
+            continue;
+        if (isOwnArchitectShellper(cmdline, opts.identity)) {
+            reclaimable.push(pid);
+        }
+        else {
+            foreign = true;
+        }
+    }
+    return { reclaimable, foreign };
+}
+/**
+ * Find PIDs of OUR OWN architect shellpers for `identity`, regardless of which
+ * session they hold. Used by remove-architect to reap a live-process-without-a-
+ * registry-row zombie (Issue #1224 symptom B) — there is no stored session id to
+ * key on, so identity (shellper-main.js + cwd + CODEV_ARCHITECT_NAME) is the key.
+ */
+export function findOwnArchitectShellpers(opts) {
+    const list = opts.list ?? listProcessEntries;
+    let entries;
+    try {
+        entries = list();
+    }
+    catch {
+        return [];
+    }
+    const pids = [];
+    for (const { pid, cmdline } of entries) {
+        if (opts.selfPid !== undefined && pid === opts.selfPid)
+            continue;
+        if (isOwnArchitectShellper(cmdline, opts.identity))
+            pids.push(pid);
+    }
+    return pids;
+}
+/** Whether a pid is still alive (signal 0 probe). */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH → gone; EPERM → alive but not ours to signal (treat as alive).
+        return err.code === 'EPERM';
+    }
+}
+/** Kill a shellper's whole process group (leader is detached), best-effort. */
+function killProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // Group gone or not permitted — fall back to the single pid.
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            /* already dead */
+        }
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Reap the given superseded-shellper PIDs: SIGTERM the process group, poll for
+ * death, then SIGKILL any survivor. Resolves once every pid is gone (or the
+ * SIGKILL grace elapses). The wait matters: the killed shellper's child must
+ * release the session lock before the caller's fresh `claude --resume` runs,
+ * else the collision recurs.
+ *
+ * Seams (`isAlive`, `kill`, `wait`) keep it unit-testable without real signals.
+ */
+export async function reapShellpers(pids, opts) {
+    if (pids.length === 0)
+        return;
+    const isAlive = opts?.isAlive ?? pidAlive;
+    const kill = opts?.kill ?? killProcessGroup;
+    const wait = opts?.wait ?? sleep;
+    const graceMs = opts?.graceMs ?? 3000;
+    const killGraceMs = opts?.killGraceMs ?? 2000;
+    const pollMs = opts?.pollMs ?? 100;
+    const pollUntilDead = async (deadlineMs) => {
+        let waited = 0;
+        while (waited < deadlineMs && pids.some((pid) => isAlive(pid))) {
+            await wait(pollMs);
+            waited += pollMs;
+        }
+    };
+    for (const pid of pids)
+        kill(pid, 'SIGTERM');
+    await pollUntilDead(graceMs);
+    const survivors = pids.filter((pid) => isAlive(pid));
+    if (survivors.length > 0) {
+        for (const pid of survivors)
+            kill(pid, 'SIGKILL');
+        // Confirm SIGKILL actually took effect before returning: the caller resumes
+        // `claude --resume <id>` next, and a holder still in the kernel's exit path
+        // has not yet released the session lock — returning early would re-open the
+        // very collision race this reap exists to close (codex review, Issue #1224).
+        await pollUntilDead(killGraceMs);
+    }
+}
+/**
+ * Reconcile a stored architect session id against the live process table before
+ * launch, resolving whether the caller may resume it.
+ *
+ * - A FOREIGN holder → `{ foreignHolder: true }`: the caller must mint fresh
+ *   (the session is genuinely in use by something we must not touch).
+ * - Only OUR OWN superseded shellper(s) hold it → reap them and return
+ *   `{ foreignHolder: false }`: the session is now free, resume it (mint-or-
+ *   RECLAIM, preserving the conversation instead of abandoning it).
+ * - No holder → `{ foreignHolder: false }`: resume as usual.
+ */
+export async function reconcileArchitectSessionHolder(opts) {
+    const { reclaimable, foreign } = classifyArchitectSessionHolder({
+        sessionId: opts.sessionId,
+        identity: opts.identity,
+        selfPid: opts.selfPid,
+        list: opts.list,
+    });
+    const shortId = opts.sessionId.slice(0, 8);
+    if (foreign) {
+        opts.log?.('WARN', `Architect '${opts.identity.architectName}' session ${shortId}… is held by a foreign process; minting a fresh session (holder left untouched) in ${opts.identity.workspacePath}`);
+        return { foreignHolder: true, reclaimedPids: [] };
+    }
+    if (reclaimable.length === 0) {
+        return { foreignHolder: false, reclaimedPids: [] };
+    }
+    opts.log?.('WARN', `Architect '${opts.identity.architectName}' session ${shortId}… is held by our own superseded shellper(s) [${reclaimable.join(', ')}]; reaping to reclaim the conversation in ${opts.identity.workspacePath}`);
+    const reap = opts.reap ?? ((pids) => reapShellpers(pids));
+    await reap(reclaimable);
+    return { foreignHolder: false, reclaimedPids: reclaimable };
+}
+//# sourceMappingURL=architect-session-holder.js.map

package/dist/agent-farm/servers/architect-session-holder.js.map

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

package/dist/agent-farm/servers/cron-delivery.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cron message delivery through the mailbox + gate (Spec 1313, Phase 6).
+ *
+ * Cron is today the most unguarded message writer: it wrote straight to the PTY with
+ * no idle check and logged "delivered" unconditionally. This phase makes it an
+ * ordinary mailbox sender — every cron notification is persisted and then delivered
+ * through the SAME single gated path (`deliverAgentMailSerialized`) that `handleSend`
+ * and the backstop drainer use, so a cron message can never land mid-draft or fuse
+ * with a human's half-typed line. There is no force path: a busy/menu/wrapper screen
+ * holds the message for the backstop, exactly like any other send.
+ *
+ * Two cron-specific twists on top of the shared path:
+ *  - **Supersede key = task name** (Baked Decision 6): a newer run of a task replaces
+ *    its own older *held* row instead of queueing a backlog. Supersede keys are
+ *    cron-only in this project — no non-cron send ever supplies one.
+ *  - **Honest run outcome**: the caller logs the real fate (`delivered` / `held` /
+ *    `superseded`) rather than an unconditional "delivered".
+ *
+ * This module holds the registry-free orchestration core behind the Phase-4
+ * {@link DeliveryPorts} seam, so it is unit-testable against a real mailbox DB with
+ * fake edges (no live Tower). The identity resolution that needs the live routing
+ * registry (`resolveTarget` + the architect reverse-map + the dead-session registry
+ * fallback) lives in `tower-routes.ts`'s `deliverCronMessage`, which calls this.
+ */
+import type Database from 'better-sqlite3';
+import type { MailboxReason } from '../db/types.js';
+import { type DeliveryPorts } from './mailbox-delivery.js';
+/** The pseudo-agent identity every cron notification is sent as. */
+export declare const CRON_SENDER = "af-cron";
+/** The real fate of one cron run's message (what the run log records). */
+export type CronOutcome = 'delivered' | 'held' | 'superseded' | 'unresolved';
+/** Outcome of routing a cron notification through the mailbox + gate. */
+export interface CronDeliveryResult {
+    /**
+     * `delivered` — written to a render-verified empty prompt now; `held` — this run's
+     * message is held for the backstop (line busy / menu / no profile / no live PTY);
+     * `superseded` — held, and it replaced a still-held row from an earlier run of the
+     * same task (no backlog); `unresolved` — the target could not be resolved at all
+     * (nothing persisted).
+     */
+    outcome: CronOutcome;
+    /** Why held, when `held`/`superseded`; null when `delivered`/`unresolved`. */
+    reason: MailboxReason | null;
+    /** The persisted row id (audit); null only when `unresolved`. */
+    mailboxId: string | null;
+}
+/** A resolved cron recipient plus the bytes to persist. */
+export interface CronTarget {
+    workspacePath: string;
+    /** Canonical recipient agent id (a builder id or a specific architect name). */
+    toAgent: string;
+    /** Last-known PTY hint; null when the recipient has no live terminal. */
+    terminalId: string | null;
+    /** Raw message body (never logged). */
+    body: string;
+    /** Exact bytes written to the PTY on delivery. */
+    formattedMessage: string;
+    /** Per-task coalescing key (Baked Decision 6) — the task name. */
+    supersedeKey: string;
+}
+/**
+ * Persist a cron notification (superseding any still-held row from an earlier run of
+ * the same task) and attempt one gated delivery, returning the run's real outcome.
+ *
+ * The corruption-safety is entirely inherited from {@link deliverAgentMailSerialized}:
+ * the body is only ever written to a render-verified empty prompt, and the per-agent
+ * serializer means a concurrent send can never interleave with this write. A busy or
+ * unclassifiable screen simply leaves the row held for the backstop — there is no
+ * force path here, by construction.
+ */
+export declare function deliverCronMail(ports: DeliveryPorts, db: Database.Database, target: CronTarget): Promise<CronDeliveryResult>;
+//# sourceMappingURL=cron-delivery.d.ts.map

package/dist/agent-farm/servers/cron-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-delivery.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/cron-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEvF,oEAAoE;AACpE,eAAO,MAAM,WAAW,YAAY,CAAC;AAErC,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC;AAE7E,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,EAAE,WAAW,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,iEAAiE;IACjE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,gBAAgB,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAgD7B"}

package/dist/agent-farm/servers/cron-delivery.js

@@ -0,0 +1,80 @@
+/**
+ * Cron message delivery through the mailbox + gate (Spec 1313, Phase 6).
+ *
+ * Cron is today the most unguarded message writer: it wrote straight to the PTY with
+ * no idle check and logged "delivered" unconditionally. This phase makes it an
+ * ordinary mailbox sender — every cron notification is persisted and then delivered
+ * through the SAME single gated path (`deliverAgentMailSerialized`) that `handleSend`
+ * and the backstop drainer use, so a cron message can never land mid-draft or fuse
+ * with a human's half-typed line. There is no force path: a busy/menu/wrapper screen
+ * holds the message for the backstop, exactly like any other send.
+ *
+ * Two cron-specific twists on top of the shared path:
+ *  - **Supersede key = task name** (Baked Decision 6): a newer run of a task replaces
+ *    its own older *held* row instead of queueing a backlog. Supersede keys are
+ *    cron-only in this project — no non-cron send ever supplies one.
+ *  - **Honest run outcome**: the caller logs the real fate (`delivered` / `held` /
+ *    `superseded`) rather than an unconditional "delivered".
+ *
+ * This module holds the registry-free orchestration core behind the Phase-4
+ * {@link DeliveryPorts} seam, so it is unit-testable against a real mailbox DB with
+ * fake edges (no live Tower). The identity resolution that needs the live routing
+ * registry (`resolveTarget` + the architect reverse-map + the dead-session registry
+ * fallback) lives in `tower-routes.ts`'s `deliverCronMessage`, which calls this.
+ */
+import { supersede, getById, countHeldWithKey } from '../db/mailbox.js';
+import { deliverAgentMailSerialized } from './mailbox-delivery.js';
+/** The pseudo-agent identity every cron notification is sent as. */
+export const CRON_SENDER = 'af-cron';
+/**
+ * Persist a cron notification (superseding any still-held row from an earlier run of
+ * the same task) and attempt one gated delivery, returning the run's real outcome.
+ *
+ * The corruption-safety is entirely inherited from {@link deliverAgentMailSerialized}:
+ * the body is only ever written to a render-verified empty prompt, and the per-agent
+ * serializer means a concurrent send can never interleave with this write. A busy or
+ * unclassifiable screen simply leaves the row held for the backstop — there is no
+ * force path here, by construction.
+ */
+export async function deliverCronMail(ports, db, target) {
+    const { workspacePath, toAgent, supersedeKey } = target;
+    // Did an earlier run of this task leave a row still held? Read it BEFORE the
+    // supersede, with no await between, so the pair is atomic on the synchronous DB
+    // handle (see countHeldWithKey). This only informs the log word — the "no backlog"
+    // correctness comes from supersede() being atomic regardless.
+    const replacedPrior = countHeldWithKey(db, workspacePath, supersedeKey) > 0;
+    const row = supersede(db, workspacePath, supersedeKey, {
+        workspacePath,
+        toAgent,
+        terminalId: target.terminalId,
+        body: target.body,
+        formattedMessage: target.formattedMessage,
+        fromAgent: CRON_SENDER,
+        fromWorkspace: workspacePath,
+    }, ports.now());
+    // The held set changed (a new row enqueued, possibly replacing a prior held one) →
+    // refresh the indicator count (Spec 1313, Phase 7). A clean delivery below fires it
+    // again when the row leaves the set; both are cheap, idempotent refetch triggers.
+    ports.onHeldStateChange();
+    try {
+        await deliverAgentMailSerialized(ports, db, workspacePath, toAgent);
+    }
+    catch (err) {
+        // A gate/write error leaves the row HELD (markDelivered only runs on a completed
+        // write); the backstop drainer retries. Mirrors handleSend — never throws upward.
+        ports.log(`[cron] delivery attempt errored for ${toAgent} (row ${row.id.slice(0, 8)}… stays held): ${String(err)}`);
+    }
+    const stored = getById(db, row.id);
+    if (stored?.status === 'delivered') {
+        return { outcome: 'delivered', reason: null, mailboxId: row.id };
+    }
+    // Held. `reason` is set by the delivery pass when it holds; default to `busy` for
+    // the rare case where an older row for the same agent delivered first and left ours
+    // queued behind it (its Enter makes the line busy for the next pass anyway).
+    return {
+        outcome: replacedPrior ? 'superseded' : 'held',
+        reason: stored?.reason ?? 'busy',
+        mailboxId: row.id,
+    };
+}
+//# sourceMappingURL=cron-delivery.js.map

package/dist/agent-farm/servers/cron-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-delivery.js","sourceRoot":"","sources":["../../../src/agent-farm/servers/cron-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAExE,OAAO,EAAE,0BAA0B,EAAsB,MAAM,uBAAuB,CAAC;AAEvF,oEAAoE;AACpE,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAoCrC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAoB,EACpB,EAAqB,EACrB,MAAkB;IAElB,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAExD,6EAA6E;IAC7E,gFAAgF;IAChF,mFAAmF;IACnF,8DAA8D;IAC9D,MAAM,aAAa,GAAG,gBAAgB,CAAC,EAAE,EAAE,aAAa,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;IAC5E,MAAM,GAAG,GAAG,SAAS,CACnB,EAAE,EACF,aAAa,EACb,YAAY,EACZ;QACE,aAAa;QACb,OAAO;QACP,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,SAAS,EAAE,WAAW;QACtB,aAAa,EAAE,aAAa;KAC7B,EACD,KAAK,CAAC,GAAG,EAAE,CACZ,CAAC;IACF,mFAAmF;IACnF,oFAAoF;IACpF,kFAAkF;IAClF,KAAK,CAAC,iBAAiB,EAAE,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,0BAA0B,CAAC,KAAK,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,iFAAiF;QACjF,kFAAkF;QAClF,KAAK,CAAC,GAAG,CAAC,uCAAuC,OAAO,SAAS,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,kBAAkB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACtH,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IACnC,IAAI,MAAM,EAAE,MAAM,KAAK,WAAW,EAAE,CAAC;QACnC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;IACnE,CAAC;IACD,kFAAkF;IAClF,oFAAoF;IACpF,6EAA6E;IAC7E,OAAO;QACL,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM;QAC9C,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,MAAM;QAChC,SAAS,EAAE,GAAG,CAAC,EAAE;KAClB,CAAC;AACJ,CAAC"}

package/dist/agent-farm/servers/delayed-send.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Due-time timer for the delayed `afx send --delay --interrupt` path (Spec 1307,
+ * reshaped by Spec 1313 round 3).
+ *
+ * ## What this module does NOW (and no longer does)
+ *
+ * The message *body* of every `--delay` send is persisted to the durable mailbox
+ * at REQUEST time, with a `not_before` due time, by `handleDelayedSend` in
+ * tower-routes.ts — NOT here, and NOT at fire time. The gated backstop drainer
+ * delivers that row once `not_before` passes, so a plain `--delay` keeps no timer
+ * at all and survives a Tower restart by construction.
+ *
+ * This module holds a due-time timer used by ONE caller: the delayed-`--interrupt`
+ * path. When it fires it writes only the Ctrl+C that ends the current turn — no
+ * message body, and it marks nothing `delivered`. The body then lands through the
+ * same render gate every send uses, after the ^C ends the turn.
+ *
+ * ## Why the registry exists at all
+ *
+ * A bare `setTimeout` would work until Tower shuts down, at which point the
+ * process would either hang on a pending timer or exit with a ^C half-scheduled
+ * and no record of it. The registry makes shutdown explicit.
+ *
+ * ## Shutdown drops the ^C nudge, never the message
+ *
+ * A pre-due `--delay` message is a persisted mailbox row: it survives a restart
+ * and delivers when the target's prompt is next clean. Only the in-memory ^C
+ * nudge is dropped on shutdown — recoverable (a human re-interrupts if it matters),
+ * and matching the documented "only the interrupt semantics gracefully degrade"
+ * boundary. This is the CONSCIOUS reversal of Spec 1307's original body-drop-on-
+ * restart trade (see review 1313): the render gate now supplies the protection that
+ * trade wanted — a post-restart delivery still only lands on a render-verified empty
+ * prompt, and a stale pending row is visible and cancellable in `afx inbox`.
+ */
+/**
+ * Upper bound on `--delay`, in seconds.
+ *
+ * One hour. Not a meaningful workflow limit — it exists so a typo (`--delay
+ * 1500` when 15 was meant) cannot park a message far in the future unnoticed.
+ * Under Spec 1313 round 3 a parked send IS listable and cancellable via
+ * `afx inbox` / `afx inbox dismiss` (it is a durable mailbox row), but the
+ * ceiling stays as a cheap guard against the typo case.
+ */
+export declare const MAX_DELAY_SECONDS = 3600;
+/**
+ * Validate a delay in seconds, returning null when acceptable or an error
+ * string naming the problem.
+ *
+ * `Number.isInteger` rather than a bare comparison chain: `NaN > 0` and
+ * `NaN <= 0` are both false, so a NaN slips through any single comparison
+ * written the obvious way and yields a `setTimeout` that fires immediately —
+ * silently converting a delayed send into an immediate one. Infinity is
+ * rejected for the same class of reason.
+ */
+export declare function validateDelaySeconds(value: unknown): string | null;
+/**
+ * Schedule `deliver` to run after `delaySeconds`.
+ *
+ * The callback is responsible for re-resolving the session and re-deciding how
+ * to deliver; this module guarantees only *when* it is invoked, and that it is
+ * invoked at most once.
+ */
+export declare function scheduleDelayedSend(delaySeconds: number, terminalId: string, 
+/**
+ * Invoked when the send comes due. Receives `isStillLive`, which it must
+ * re-check at the moment it actually writes (inside the submission lock): a
+ * delivery can acquire the lock only AFTER a shutdown that fired while it
+ * queued, and the generation check below only guards the moment BEFORE it
+ * enters the lock. Return value is ignored.
+ */
+deliver: (isStillLive: () => boolean) => unknown): void;
+/**
+ * Cancel every pending delayed send without delivering. Returns the count of
+ * still-timing sends dropped, so shutdown can log it rather than losing
+ * messages silently.
+ *
+ * Covers two states: sends still on their timer (cleared here) and sends whose
+ * timer has fired but whose delivery has not started — invalidated by bumping
+ * `generation`, which the delivery callback re-checks. A delivery already
+ * writing when this runs is NOT interrupted; see `generation`'s note.
+ */
+export declare function shutdownDelayedSends(): number;
+/** Number of pending delayed sends. Diagnostics and tests. */
+export declare function pendingDelayedSendCount(): number;
+//# sourceMappingURL=delayed-send.d.ts.map

package/dist/agent-farm/servers/delayed-send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delayed-send.d.ts","sourceRoot":"","sources":["../../../src/agent-farm/servers/delayed-send.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAwCH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAWlE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM;AAClB;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,OAAO,KAAK,OAAO,GAC/C,IAAI,CAmCN;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAQ7C;AAED,8DAA8D;AAC9D,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD"}