@cluesmith/codev 3.2.4 → 3.3.1

package/dist/agent-farm/servers/canvas-relay.js

@@ -0,0 +1,376 @@
+/**
+ * Canvas command relay + live view registry for Tower (spec 1401).
+ *
+ * Lets any CONTROLLER (a control device, a companion app, a test harness) drive an open
+ * artifact-canvas view over Tower's existing channels:
+ *   - host -> Tower:       REST on `/api/canvas/views` (register / heartbeat / unregister).
+ *   - controller -> Tower: REST POST `/api/canvas/command`.
+ *   - Tower -> host:       SSE `canvas-command` at /api/events, addressed to one resolved view.
+ *
+ * Why this is not just another verb on `command-relay.ts`: that relay is a fire-and-forget
+ * broadcast which answers `{ok:true}` whether or not anything is listening. It structurally
+ * cannot say "no canvas is open", and it cannot pick one view among several. Both are hard
+ * requirements here, so Tower keeps a registry of live views, resolves exactly ONE target, and
+ * reports which one it drove.
+ *
+ * The registry is deliberately in-memory and lease-based: a view is a live UI surface, not
+ * durable state, and a host that dies without unregistering must age out rather than linger as
+ * a ghost that silently swallows commands.
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { parseJsonBody } from '../utils/server-utils.js';
+// Wire names — the canonical contract lives in @cluesmith/codev-types
+// (CANVAS_COMMAND_ROUTE / CANVAS_VIEWS_ROUTE / CANVAS_COMMAND_EVENT) and must match these. They
+// are re-declared locally because codev runs UNBUNDLED from dist/ and codev-types is a
+// compile-time-only (type) dependency with no runtime dist on the codev side, so a runtime value
+// import from it would not resolve. Same reason command-relay.ts re-declares COMMAND_ROUTE.
+export const CANVAS_COMMAND_ROUTE = '/api/canvas/command';
+export const CANVAS_VIEWS_ROUTE = '/api/canvas/views';
+const CANVAS_COMMAND_EVENT = 'canvas-command';
+/** Everything under this prefix belongs to this module. */
+export const CANVAS_ROUTE_PREFIX = '/api/canvas/';
+/** How often a host should heartbeat to keep its lease alive. */
+export const CANVAS_VIEW_HEARTBEAT_MS = 30_000;
+/**
+ * How long a view survives without a heartbeat. Three missed beats: long enough to ride out a
+ * busy event loop or a paused debugger, short enough that a killed host's ghost view stops
+ * absorbing commands quickly.
+ */
+export const CANVAS_VIEW_LEASE_MS = 90_000;
+/**
+ * The closed command vocabulary as runtime data, so an unknown command can be rejected. The
+ * assertion below fails to compile if `CanvasCommand` gains a member that is missing here, which
+ * is what keeps Tower's validation from silently falling behind the contract.
+ */
+const CANVAS_COMMANDS = [
+    'block-next',
+    'block-prev',
+    'comment-next',
+    'comment-prev',
+    'heading-next',
+    'heading-prev',
+    'column-forward',
+    'column-back',
+    'viewport-down',
+    'viewport-up',
+    'doc-start',
+    'doc-end',
+    'composer-open',
+    'composer-submit',
+    'composer-cancel',
+    'composer-open-or-submit',
+    'reading-mode-toggle',
+];
+/** The commands `count` is valid on. Same drift protection as above. */
+const TRAVERSAL_COMMANDS = [
+    'block-next',
+    'block-prev',
+    'comment-next',
+    'comment-prev',
+    'heading-next',
+    'heading-prev',
+    'column-forward',
+    'column-back',
+    'viewport-down',
+    'viewport-up',
+];
+const views = new Map();
+let sequence = 0;
+let deps = null;
+let inited = false;
+/** Wire the module's dependencies. */
+export function initCanvasRelay(d) {
+    deps = d;
+    inited = true;
+}
+/** Tear down state (used by tests and shutdown). */
+export function shutdownCanvasRelay() {
+    views.clear();
+    sequence = 0;
+    deps = null;
+    inited = false;
+}
+/**
+ * Resolve a path the same way the file-tab registry does, so the two agree on what "the same
+ * file" means: follow symlinks, fall back to resolving the parent when the file itself does not
+ * exist, and finally to a plain absolute path.
+ */
+function canonicalPath(raw) {
+    try {
+        return fs.realpathSync(raw);
+    }
+    catch {
+        try {
+            return path.join(fs.realpathSync(path.dirname(raw)), path.basename(raw));
+        }
+        catch {
+            return path.resolve(raw);
+        }
+    }
+}
+/** Drop views whose lease has lapsed. Called on every access, so no timer is needed. */
+function sweep(nowMs) {
+    for (const [id, view] of views) {
+        if (nowMs - view.lastSeenAt > CANVAS_VIEW_LEASE_MS)
+            views.delete(id);
+    }
+}
+/**
+ * Pick the single view a command should go to.
+ *
+ * Zero matches is the caller's problem to hear about, not something to paper over. More than one
+ * match resolves to the most recently active view and NEVER fans out: delivering
+ * `composer-submit` to two views of one file would post the comment twice.
+ */
+function resolveTarget(workspace, file, nowMs) {
+    sweep(nowMs);
+    const ws = canonicalPath(workspace);
+    let wanted = null;
+    if (file !== undefined)
+        wanted = canonicalPath(file);
+    const matches = [];
+    for (const view of views.values()) {
+        if (view.workspace !== ws)
+            continue;
+        if (wanted !== null && view.file !== wanted)
+            continue;
+        matches.push(view);
+    }
+    if (matches.length === 0)
+        return null;
+    matches.sort((a, b) => {
+        if (b.lastActiveAt !== a.lastActiveAt)
+            return b.lastActiveAt - a.lastActiveAt;
+        return b.sequence - a.sequence;
+    });
+    return matches[0];
+}
+/**
+ * Single entry point for `/api/canvas/*`, delegated from tower-routes. Lazily initializes from
+ * the RouteContext on first hit, then dispatches.
+ */
+export async function handleCanvasRoute(req, res, url, ctx) {
+    if (!inited) {
+        initCanvasRelay({
+            broadcast: (type, body) => ctx.broadcastNotification({ type, title: type, body: JSON.stringify(body) }),
+            now: () => Date.now(),
+        });
+    }
+    if (req.method === 'POST' && url.pathname === CANVAS_COMMAND_ROUTE) {
+        return handleCanvasCommand(req, res);
+    }
+    if (req.method === 'POST' && url.pathname === CANVAS_VIEWS_ROUTE) {
+        return handleRegisterView(req, res);
+    }
+    const viewMatch = url.pathname.match(/^\/api\/canvas\/views\/([^/]+)(\/heartbeat)?$/);
+    if (viewMatch) {
+        const viewId = decodeURIComponent(viewMatch[1]);
+        if (req.method === 'POST' && viewMatch[2])
+            return handleHeartbeat(req, res, viewId);
+        if (req.method === 'DELETE' && !viewMatch[2])
+            return handleUnregisterView(res, viewId);
+    }
+    sendJson(res, 404, { ok: false, error: 'Unknown canvas route' });
+}
+/** POST /api/canvas/views — a host registers one live canvas view. */
+async function handleRegisterView(req, res) {
+    const d = requireDeps();
+    let parsed;
+    try {
+        parsed = await parseJsonBody(req);
+    }
+    catch {
+        return sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+    }
+    const body = asObject(parsed);
+    if (!body)
+        return sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+    if (!isNonEmptyString(body.workspace)) {
+        return sendJson(res, 400, { ok: false, error: 'Missing workspace' });
+    }
+    if (!isNonEmptyString(body.file)) {
+        return sendJson(res, 400, { ok: false, error: 'Missing file' });
+    }
+    const nowMs = d.now();
+    sweep(nowMs);
+    sequence += 1;
+    const viewId = `canvas-${randomUUID()}`;
+    const file = canonicalPath(body.file);
+    // One registration per VIEW, never per file: two panels showing the same document are two
+    // views with distinct ids, which is precisely the case the MRU rule exists to disambiguate.
+    views.set(viewId, {
+        viewId,
+        workspace: canonicalPath(body.workspace),
+        file,
+        lastActiveAt: nowMs,
+        lastSeenAt: nowMs,
+        sequence,
+    });
+    const result = { ok: true, viewId, file };
+    return sendJson(res, 200, result);
+}
+/**
+ * POST /api/canvas/views/:viewId/heartbeat — keep the lease alive.
+ *
+ * `focused: true` additionally makes this the most recently active view. Tower stamps both times
+ * itself; host clocks are never trusted, so MRU stays deterministic across hosts whose clocks
+ * disagree.
+ */
+async function handleHeartbeat(req, res, viewId) {
+    const d = requireDeps();
+    let parsed;
+    try {
+        parsed = await parseJsonBody(req);
+    }
+    catch {
+        // A bodyless heartbeat is valid and already parses as `{}` ("still here, not necessarily
+        // focused"), so reaching here means the body was genuinely malformed. Renewing the lease on
+        // a payload we could not read would be extending liveness on the strength of a broken
+        // request.
+        return sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+    }
+    const body = asObject(parsed);
+    if (!body)
+        return sendJson(res, 400, { ok: false, error: 'Invalid JSON' });
+    // `focused` is optional but typed: a non-boolean violates `CanvasViewHeartbeat`. Reject before
+    // touching the lease, matching how the command route treats a bad `count` — a payload that does
+    // not meet the contract should not buy liveness just because the rest of it parsed.
+    if (body.focused !== undefined && typeof body.focused !== 'boolean') {
+        return sendJson(res, 400, { ok: false, error: 'focused must be a boolean' });
+    }
+    const nowMs = d.now();
+    sweep(nowMs);
+    const view = views.get(viewId);
+    // 404 rather than a silent re-create: a host holding an id Tower has forgotten (a restart, an
+    // expired lease) must learn that and re-register, or it would heartbeat into the void forever.
+    if (!view)
+        return sendJson(res, 404, { ok: false, error: 'Unknown view' });
+    view.lastSeenAt = nowMs;
+    if (body.focused === true)
+        view.lastActiveAt = nowMs;
+    return sendJson(res, 200, { ok: true });
+}
+/** DELETE /api/canvas/views/:viewId — the host's view is gone. */
+function handleUnregisterView(res, viewId) {
+    const existed = views.delete(viewId);
+    if (!existed)
+        return sendJson(res, 404, { ok: false, error: 'Unknown view' });
+    return sendJson(res, 200, { ok: true });
+}
+/**
+ * POST /api/canvas/command — run one command against the resolved target view.
+ *
+ * Answers explicitly in every case: `no-canvas` (404) when the selector matches nothing,
+ * `invalid-request` (400) when the payload is malformed, and the resolved target on success.
+ * Delivery itself rides SSE and is best-effort; what is guaranteed is the ANSWER about targeting.
+ */
+async function handleCanvasCommand(req, res) {
+    const d = requireDeps();
+    let parsed;
+    try {
+        parsed = await parseJsonBody(req);
+    }
+    catch {
+        return sendJson(res, 400, invalidRequest('Invalid JSON'));
+    }
+    const raw = asObject(parsed);
+    if (!raw)
+        return sendJson(res, 400, invalidRequest('Invalid JSON'));
+    const invalid = validateCommandRequest(raw);
+    if (invalid)
+        return sendJson(res, 400, invalidRequest(invalid));
+    const workspace = raw.workspace;
+    const file = raw.file;
+    const command = raw.command;
+    const count = raw.count;
+    const nowMs = d.now();
+    const target = resolveTarget(workspace, file, nowMs);
+    if (!target) {
+        const noCanvas = {
+            ok: false,
+            code: 'no-canvas',
+            error: 'No canvas view is open for that workspace/file',
+        };
+        return sendJson(res, 404, noCanvas);
+    }
+    const event = { viewId: target.viewId, command };
+    if (count !== undefined)
+        event.count = count;
+    d.broadcast(CANVAS_COMMAND_EVENT, event);
+    // Driving a view is activity: it keeps that view the MRU target for the follow-up commands a
+    // controller is about to send, even though it never took focus in its host.
+    //
+    // It is deliberately NOT liveness. Delivery is fire-and-forget over SSE and proves nothing
+    // about the host still being alive, so refreshing the lease here would mean a ghost view kept
+    // renewing itself for as long as a controller kept driving it — exactly when the reviewer most
+    // needs to be told there is no canvas. Only a heartbeat, which only a live host can send,
+    // extends the lease.
+    target.lastActiveAt = nowMs;
+    const ok = {
+        ok: true,
+        target: { viewId: target.viewId, file: target.file },
+    };
+    return sendJson(res, 200, ok);
+}
+/** Returns an error message when the payload is not a valid command request, else null. */
+function validateCommandRequest(raw) {
+    if (!isNonEmptyString(raw.workspace))
+        return 'Missing workspace';
+    if (raw.file !== undefined && !isNonEmptyString(raw.file))
+        return 'Invalid file';
+    if (typeof raw.command !== 'string')
+        return 'Missing command';
+    if (!CANVAS_COMMANDS.includes(raw.command)) {
+        return `Unknown command: ${raw.command}`;
+    }
+    if (raw.count !== undefined) {
+        const count = raw.count;
+        if (typeof count !== 'number' || !Number.isInteger(count) || count < 1) {
+            return 'count must be a positive integer';
+        }
+        if (!TRAVERSAL_COMMANDS.includes(raw.command)) {
+            return `count is not valid for ${raw.command}`;
+        }
+    }
+    return null;
+}
+/** Every command-route failure carries a wire `code`; this keeps that impossible to forget. */
+function invalidRequest(error) {
+    return { ok: false, code: 'invalid-request', error };
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * `parseJsonBody` is typed as returning an object but will happily resolve a literal `null`, a
+ * bare array, or a number, since those are all valid JSON. Reading a field off `null` throws,
+ * which would escape as a 500 with no wire `code` — the one thing the error contract forbids.
+ */
+function asObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    return value;
+}
+/** Access the wired deps, throwing a clear error if init was skipped. */
+function requireDeps() {
+    if (!deps)
+        throw new Error('Canvas relay not initialized');
+    return deps;
+}
+/** Write a JSON response with the given status code. */
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+/** Live views, for tests and diagnostics. Never part of the wire surface. */
+export function listCanvasViewsForTest() {
+    return [...views.values()].map((v) => ({
+        viewId: v.viewId,
+        workspace: v.workspace,
+        file: v.file,
+        lastActiveAt: v.lastActiveAt,
+    }));
+}
+//# sourceMappingURL=canvas-relay.js.map

package/dist/agent-farm/servers/canvas-relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-relay.js","sourceRoot":"","sources":["../../../src/agent-farm/servers/canvas-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,sEAAsE;AACtE,gGAAgG;AAChG,uFAAuF;AACvF,iGAAiG;AACjG,4FAA4F;AAC5F,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAC1D,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AACtD,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAE9C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAElD,iEAAiE;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAC/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAS3C;;;;GAIG;AACH,MAAM,eAAe,GAAG;IACtB,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,cAAc;IACd,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,aAAa;IACb,eAAe;IACf,aAAa;IACb,WAAW;IACX,SAAS;IACT,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,yBAAyB;IACzB,qBAAqB;CACsB,CAAC;AAM9C,wEAAwE;AACxE,MAAM,kBAAkB,GAAG;IACzB,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,cAAc;IACd,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,aAAa;IACb,eAAe;IACf,aAAa;CACiC,CAAC;AA6BjD,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;AAChD,IAAI,QAAQ,GAAG,CAAC,CAAC;AACjB,IAAI,IAAI,GAA2B,IAAI,CAAC;AACxC,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,IAAI,GAAG,CAAC,CAAC;IACT,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,mBAAmB;IACjC,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,QAAQ,GAAG,CAAC,CAAC;IACb,IAAI,GAAG,IAAI,CAAC;IACZ,MAAM,GAAG,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC;AAED,wFAAwF;AACxF,SAAS,KAAK,CAAC,KAAa;IAC1B,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;QAC/B,IAAI,KAAK,GAAG,IAAI,CAAC,UAAU,GAAG,oBAAoB;YAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,SAAiB,EAAE,IAAwB,EAAE,KAAa;IAC/E,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,MAAM,EAAE,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAErD,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,SAAS,KAAK,EAAE;YAAE,SAAS;QACpC,IAAI,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QACtD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,YAAY;YAAE,OAAO,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;QAC9E,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;IACjC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAyB,EACzB,GAAwB,EACxB,GAAQ,EACR,GAAmB;IAEnB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,eAAe,CAAC;YACd,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CACxB,GAAG,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9E,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,QAAQ,KAAK,oBAAoB,EAAE,CAAC;QACnE,OAAO,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,QAAQ,KAAK,kBAAkB,EAAE,CAAC;QACjE,OAAO,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACtF,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC;YAAE,OAAO,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;QACpF,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;YAAE,OAAO,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACzF,CAAC;IAED,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,sEAAsE;AACtE,KAAK,UAAU,kBAAkB,CAC/B,GAAyB,EACzB,GAAwB;IAExB,MAAM,CAAC,GAAG,WAAW,EAAE,CAAC;IACxB,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAC3E,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACtC,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IACtB,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,QAAQ,IAAI,CAAC,CAAC;IACd,MAAM,MAAM,GAAG,UAAU,UAAU,EAAE,EAAE,CAAC;IACxC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,0FAA0F;IAC1F,4FAA4F;IAC5F,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE;QAChB,MAAM;QACN,SAAS,EAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC;QACxC,IAAI;QACJ,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,KAAK;QACjB,QAAQ;KACT,CAAC,CAAC;IACH,MAAM,MAAM,GAAiC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACxE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,eAAe,CAC5B,GAAyB,EACzB,GAAwB,EACxB,MAAc;IAEd,MAAM,CAAC,GAAG,WAAW,EAAE,CAAC;IACxB,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,yFAAyF;QACzF,4FAA4F;QAC5F,sFAAsF;QACtF,WAAW;QACX,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAC3E,+FAA+F;IAC/F,gGAAgG;IAChG,oFAAoF;IACpF,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACpE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IACtB,KAAK,CAAC,KAAK,CAAC,CAAC;IACb,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,8FAA8F;IAC9F,+FAA+F;IAC/F,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAE3E,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IACxB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;QAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;IACrD,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,kEAAkE;AAClE,SAAS,oBAAoB,CAAC,GAAwB,EAAE,MAAc;IACpE,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAC9E,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,mBAAmB,CAChC,GAAyB,EACzB,GAAwB;IAExB,MAAM,CAAC,GAAG,WAAW,EAAE,CAAC;IACxB,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC,CAAC;IAEpE,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,OAAO;QAAE,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAEhE,MAAM,SAAS,GAAG,GAAG,CAAC,SAAmB,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAA0B,CAAC;IAC5C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAwB,CAAC;IAC7C,MAAM,KAAK,GAAG,GAAG,CAAC,KAA2B,CAAC;IAE9C,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IACtB,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,QAAQ,GAAwB;YACpC,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,gDAAgD;SACxD,CAAC;QACF,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,KAAK,GAAuB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACrE,IAAI,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;IAC7C,CAAC,CAAC,SAAS,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;IAEzC,6FAA6F;IAC7F,4EAA4E;IAC5E,EAAE;IACF,2FAA2F;IAC3F,8FAA8F;IAC9F,+FAA+F;IAC/F,0FAA0F;IAC1F,qBAAqB;IACrB,MAAM,CAAC,YAAY,GAAG,KAAK,CAAC;IAE5B,MAAM,EAAE,GAAwB;QAC9B,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;KACrD,CAAC;IACF,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,2FAA2F;AAC3F,SAAS,sBAAsB,CAAC,GAA4B;IAC1D,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACjE,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,cAAc,CAAC;IACjF,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC;IAC9D,IAAI,CAAE,eAAqC,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAClE,OAAO,oBAAoB,GAAG,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACvE,OAAO,kCAAkC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAE,kBAAwC,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACrE,OAAO,0BAA0B,GAAG,CAAC,OAAO,EAAE,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+FAA+F;AAC/F,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;AACvD,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrF,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED,yEAAyE;AACzE,SAAS,WAAW;IAClB,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wDAAwD;AACxD,SAAS,QAAQ,CAAC,GAAwB,EAAE,MAAc,EAAE,IAAa;IACvE,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC9D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB;IACpC,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACrC,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,YAAY,EAAE,CAAC,CAAC,YAAY;KAC7B,CAAC,CAAC,CAAC;AACN,CAAC"}

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"}