@cluesmith/codev 3.2.4 → 3.3.1

package/dist/agent-farm/servers/tower-routes.js

@@ -24,21 +24,36 @@ import { version } from '../../version.js';
 const execAsync = promisify(exec);
 import { getBuilders, setArchitectByName } from '../state.js';
 import { DEFAULT_COLS, defaultSessionOptions } from '../../terminal/index.js';
-import { parseJsonBody, isRequestAllowed } from '../utils/server-utils.js';
+import { parseJsonBody, isRequestAllowed, isAllowedOrigin, isAllowedHost, getExpectedKey, escapeHtml } from '../utils/server-utils.js';
+import { TOWER_KEY_HEADER, LEGACY_WEB_KEY_HEADER, VSCODE_USER_SENDER } from '@cluesmith/codev-types';
 import { isRateLimited, normalizeWorkspacePath, getLanguageForExt, getMimeTypeForFile, serveStaticFile, } from './tower-utils.js';
 import { handleTunnelEndpoint } from './tower-tunnel.js';
 import { getWorktreeConfig, getActivityHooks } from '../utils/config.js';
 import { ensureCodevConfigWatcher } from './codev-config-watcher.js';
 import { hasTeam, loadTeamMembers, loadMessages } from '../../lib/team.js';
 import { fetchTeamGitHubData } from '../../lib/team-github.js';
-import { resolveTarget, broadcastMessage, isResolveError } from './tower-messages.js';
+import { resolveTarget, resolveAgentInRegistry, broadcastMessage, isResolveError } from './tower-messages.js';
 import { handleCommandRoute, COMMAND_ROUTE } from './command-relay.js';
-import { formatArchitectMessage, formatBuilderMessage } from '../utils/message-format.js';
-import { SendBuffer } from './send-buffer.js';
-import { writeMessageToSession } from './message-write.js';
-import { getKnownWorkspacePaths, getInstances, getDirectorySuggestions, launchInstance, killTerminalWithShellper, stopInstance, addArchitect, removeArchitect, } from './tower-instances.js';
+import { handleCanvasRoute, CANVAS_ROUTE_PREFIX } from './canvas-relay.js';
+import { formatArchitectMessage, formatBuilderMessage, formatUserViaVsCodeMessage } from '../utils/message-format.js';
+import { writeMessageToSession, writeEscapeToSession } from './message-write.js';
+import { makeDeliveryPorts, getMailboxDrainer } from './mailbox-wiring.js';
+import { deliverAgentMailSerialized } from './mailbox-delivery.js';
+import { deliverCronMail, CRON_SENDER } from './cron-delivery.js';
+import { enqueue as enqueueMailbox, getById as getMailboxById, markDelivered as markMailboxDelivered, listHeld as listHeldMailbox, dismiss as dismissMailbox, } from '../db/mailbox.js';
+// Spec 1273 per-terminal submission lock — preserved across the Spec 1313 merge for
+// the two explicit human-bypass paths (escape + interrupt), which do NOT route
+// through the mailbox's per-agent serializer and so need their own anti-fusion lock.
+import { submitToSession } from './session-submit.js';
+// Spec 1307 `--delay` — Tower-side deferred delivery, re-homed onto the Spec 1313
+// mailbox (the merge that carried this feature was flattened by a later rebase, so it
+// is grafted here explicitly): the due-time callback enqueues to the mailbox and
+// triggers a gated drain (see handleSend), so a delayed message delivers onto a
+// render-verified empty prompt like any normal send — never force-injected.
+import { scheduleDelayedSend, validateDelaySeconds } from './delayed-send.js';
+import { getKnownWorkspacePaths, getInstances, getDirectorySuggestions, launchInstance, killTerminalWithShellper, instancesReady, stopInstance, addArchitect, removeArchitect, } from './tower-instances.js';
 import { OverviewCache } from './overview.js';
-import { fetchIssue, searchIssues, fetchPRList, fetchCurrentUser, parseLinkedIssue, parseArea, } from '../../lib/github.js';
+import { fetchIssue, fetchPR, searchIssues, fetchPRList, fetchCurrentUser, parseLinkedIssue, parseArea, } from '../../lib/github.js';
 import { computeAnalytics } from './analytics.js';
 import { getAllTasks, executeTask, getTaskId } from './tower-cron.js';
 import { getGlobalDb } from '../db/index.js';
@@ -50,23 +65,6 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Singleton cache for overview endpoint (Spec 0126 Phase 4)
 const overviewCache = new OverviewCache();
-// Singleton send buffer for typing-aware message delivery (Spec 403)
-const sendBuffer = new SendBuffer();
-/** Deliver a buffered message to a session (write + broadcast + log).
- *  Returns the ms timestamp when all writes complete (for serialization). */
-function deliverBufferedMessage(session, msg, delayOffset = 0) {
-    const endTime = writeMessageToSession(session, msg.formattedMessage, msg.noEnter, delayOffset);
-    broadcastMessage(msg.broadcastPayload);
-    return endTime;
-}
-/** Start the send buffer flush timer (called from tower-server during init). */
-export function startSendBuffer(log) {
-    sendBuffer.start((id) => getTerminalManager().getSession(id), deliverBufferedMessage, log);
-}
-/** Stop the send buffer and deliver remaining messages (called from tower-server during shutdown). */
-export function stopSendBuffer() {
-    sendBuffer.stop();
-}
 const ROUTES = {
     'GET /health': (_req, res, _url, ctx) => handleHealthCheck(res, ctx),
     'GET /api/shellpers/husks': (_req, res, _url, ctx) => handleHuskPreview(res, ctx),
@@ -78,6 +76,7 @@ const ROUTES = {
     'GET /api/version': (_req, res, _url, ctx) => handleVersion(res, ctx),
     'GET /api/overview': (_req, res, url, ctx) => handleOverview(res, url, undefined, ctx),
     'GET /api/issue': (_req, res, url) => handleIssueView(res, url),
+    'GET /api/pr': (_req, res, url) => handlePRView(res, url),
     'GET /api/issue-search': (_req, res, url) => handleIssueSearch(res, url),
     'GET /api/worktree-config': (_req, res, url) => handleWorktreeConfigView(res, url),
     'GET /api/activity-hooks': (_req, res, url) => handleActivityHooksView(res, url),
@@ -90,35 +89,65 @@ const ROUTES = {
     'POST /api/launch': (req, res) => handleLaunchInstance(req, res),
     'POST /api/stop': (req, res) => handleStopInstance(req, res),
     'POST /api/send': (req, res, _url, ctx) => handleSend(req, res, ctx),
+    'GET /api/inbox': (_req, res, url) => handleInboxList(res, url),
     'GET /api/cron/tasks': (_req, res, url) => handleCronList(res, url),
     'GET /': (_req, res, _url, ctx) => handleDashboard(res, ctx),
     'GET /index.html': (_req, res, _url, ctx) => handleDashboard(res, ctx),
 };
+/**
+ * Issue #1261: tell "Tower isn't wired up yet" apart from "no such thing".
+ * A route that needs the instances module must not report a missing terminal
+ * (404) or a successful kill (204) when the truth is that it could not act at
+ * all. 503 + Retry-After says so, and matches what `stopInstance()` already
+ * returns in the same situation.
+ *
+ * Tower's readiness gate holds requests until boot completes, so these guards
+ * should be unreachable in practice — they exist so the failure mode, if the
+ * gate is ever bypassed, is honest rather than misleading.
+ */
+function respondStartingUp(res) {
+    res.writeHead(503, { 'Content-Type': 'application/json', 'Retry-After': '1' });
+    res.end(JSON.stringify({
+        error: 'STARTING_UP',
+        message: 'Tower is still starting up. Try again shortly.',
+    }));
+}
 // ============================================================================
 // Main request handler
 // ============================================================================
 export async function handleRequest(req, res, ctx) {
-    // Security: Validate Host and Origin headers
-    if (!isRequestAllowed(req)) {
-        res.writeHead(403, { 'Content-Type': 'text/plain' });
-        res.end('Forbidden');
-        return;
-    }
-    // CORS headers — allow localhost and tunnel proxy origins
+    // CORS headers — reflect only allowlisted origins (advisory Layer 3).
     const origin = req.headers.origin;
-    if (origin && (origin.startsWith('http://localhost:') ||
-        origin.startsWith('http://127.0.0.1:') ||
-        origin.startsWith('https://'))) {
+    if (origin && isAllowedOrigin(origin)) {
         res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
     }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+    res.setHeader('Access-Control-Allow-Headers', `Content-Type, ${TOWER_KEY_HEADER}, ${LEGACY_WEB_KEY_HEADER}`);
     res.setHeader('Cache-Control', 'no-store');
+    // A CORS preflight carries no credentials and performs no action, so it is
+    // answered before the key check — otherwise browser clients could never
+    // complete the preflight that precedes an authenticated request.
     if (req.method === 'OPTIONS') {
         res.writeHead(200);
         res.end();
         return;
     }
+    // Request authentication (advisory GHSA-xvjp-7748-v88v): every route outside
+    // the narrow public-route allowlist must present the shared local key. This
+    // is the single HTTP choke point every route passes through. CORS above is
+    // defense-in-depth only — a no-preflight "simple" request still lands here.
+    if (!isRequestAllowed(req)) {
+        // Log the reason so a broken legitimate client (disallowed Host vs missing
+        // key) is diagnosable — a bare 401 is indistinguishable from either side.
+        const reason = isAllowedHost(req.headers.host)
+            ? 'missing or invalid key'
+            : `disallowed Host "${req.headers.host ?? ''}"`;
+        ctx.log('WARN', `401 ${req.method ?? 'GET'} ${req.url ?? '/'} — ${reason}`);
+        res.writeHead(401, { 'Content-Type': 'text/plain' });
+        res.end('Unauthorized');
+        return;
+    }
     const url = new URL(req.url || '/', `http://localhost:${ctx.port}`);
     try {
         // Exact-match route dispatch (O(1) lookup)
@@ -140,6 +169,12 @@ export async function handleRequest(req, res, ctx) {
         if (url.pathname === COMMAND_ROUTE) {
             return await handleCommandRoute(req, res, url, ctx);
         }
+        // Canvas command channel: /api/canvas/* — same self-routing shape as the command relay, but
+        // targeted rather than broadcast: it keeps a registry of live canvas views so it can resolve
+        // exactly one and answer when none is open (spec 1401).
+        if (url.pathname.startsWith(CANVAS_ROUTE_PREFIX)) {
+            return await handleCanvasRoute(req, res, url, ctx);
+        }
         // Workspace API: /api/workspaces/:encodedPath/activate|deactivate|status (Spec 0090 Phase 1)
         const workspaceApiMatch = url.pathname.match(/^\/api\/workspaces\/([^/]+)\/(activate|deactivate|status)$/);
         if (workspaceApiMatch) {
@@ -165,6 +200,18 @@ export async function handleRequest(req, res, ctx) {
         if (cronTaskMatch) {
             return await handleCronTaskAction(req, res, url, cronTaskMatch);
         }
+        // Inbox dismiss: POST /api/inbox/:id/dismiss (Spec 1313, Phase 7)
+        const inboxDismissMatch = url.pathname.match(/^\/api\/inbox\/([^/]+)\/dismiss$/);
+        if (inboxDismissMatch) {
+            return handleInboxDismiss(req, res, ctx, inboxDismissMatch);
+        }
+        // Inbox show: GET /api/inbox/:id — a single row INCLUDING its body (Spec 1313 §178).
+        // Checked AFTER the dismiss match, so /:id/dismiss never falls through here (its
+        // trailing segment can't match this single-segment pattern anyway).
+        const inboxShowMatch = url.pathname.match(/^\/api\/inbox\/([^/]+)$/);
+        if (inboxShowMatch) {
+            return handleInboxShow(req, res, inboxShowMatch);
+        }
         // Workspace routes: /workspace/:base64urlPath/* (Spec 0090 Phase 4)
         if (url.pathname.startsWith('/workspace/')) {
             return await handleWorkspaceRoutes(req, res, ctx, url);
@@ -581,6 +628,11 @@ async function handleTerminalCreate(req, res, ctx) {
                 const session = manager.createSessionRaw({
                     label: label || `terminal-${sessionId.slice(0, 8)}`,
                     cwd,
+                    // Spec 1313: thread the launch command so the render-gate can resolve
+                    // this session's profile (builders keep the `.builder-start.sh` backstop
+                    // too; this makes identity direct and restart-safe via the persisted row).
+                    command,
+                    args,
                 });
                 const ptySession = manager.getSession(session.id);
                 if (ptySession) {
@@ -597,7 +649,7 @@ async function handleTerminalCreate(req, res, ctx) {
                     else {
                         entry.shells.set(roleId, session.id);
                     }
-                    saveTerminalSession(session.id, workspacePath, termType, roleId, shellperInfo.pid, shellperInfo.socketPath, shellperInfo.pid, shellperInfo.startTime, label ?? null, cwd ?? null);
+                    saveTerminalSession(session.id, workspacePath, termType, roleId, shellperInfo.pid, shellperInfo.socketPath, shellperInfo.pid, shellperInfo.startTime, label ?? null, cwd ?? null, command ?? null);
                     ctx.log('INFO', `Registered shellper terminal ${session.id} as ${termType} "${roleId}" for workspace ${workspacePath}`);
                 }
             }
@@ -619,7 +671,7 @@ async function handleTerminalCreate(req, res, ctx) {
                 else {
                     entry.shells.set(roleId, info.id);
                 }
-                saveTerminalSession(info.id, workspacePath, termType, roleId, info.pid, null, null, null, null, cwd ?? null);
+                saveTerminalSession(info.id, workspacePath, termType, roleId, info.pid, null, null, null, null, cwd ?? null, command ?? null);
                 ctx.log('WARN', `Terminal ${info.id} for ${workspacePath} is non-persistent (shellper unavailable)`);
             }
         }
@@ -656,6 +708,12 @@ async function handleTerminalRoutes(req, res, url, match) {
     }
     // DELETE /api/terminals/:id - Kill terminal (disable shellper auto-restart if applicable)
     if (req.method === 'DELETE' && (!subpath || subpath === '')) {
+        // Issue #1261: without this, a not-yet-wired Tower answers 404 for a
+        // terminal that exists — the exact symptom the issue reports.
+        if (!instancesReady()) {
+            respondStartingUp(res);
+            return;
+        }
         if (!(await killTerminalWithShellper(manager, terminalId))) {
             res.writeHead(404, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'NOT_FOUND', message: `Session ${terminalId} not found` }));
@@ -852,7 +910,7 @@ async function handleOverview(res, url, workspaceOverride, ctx) {
         // every collection field is required ('never undefined' for `architects`,
         // Issue 1104), so emit them all empty rather than a partial payload.
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ builders: [], pendingPRs: [], backlog: [], recentlyClosed: [], architects: [] }));
+        res.end(JSON.stringify({ builders: [], pendingPRs: [], backlog: [], recentlyClosed: [], architects: [], heldCount: 0, mailboxEscalated: false, queuedFeedback: {}, feedbackMode: 'forward' }));
         return;
     }
     // Build set of active builder role_ids (lowercased) from live terminal sessions.
@@ -921,6 +979,30 @@ async function handleIssueView(res, url) {
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(issue));
 }
+async function handlePRView(res, url) {
+    // Mirror of handleIssueView for PRs: same workspace resolution, same
+    // ?number= param, routed through the `pr-view` forge concept. Powers the
+    // VSCode `codev.openPRById` / QuickPick "View PR #N" browser-open flow.
+    let workspaceRoot = url.searchParams.get('workspace');
+    if (!workspaceRoot) {
+        const knownPaths = getKnownWorkspacePaths();
+        workspaceRoot = knownPaths.find(p => !p.includes('/.builders/')) || null;
+    }
+    const number = url.searchParams.get('number');
+    if (!workspaceRoot || !number) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Missing workspace or number' }));
+        return;
+    }
+    const pr = await fetchPR(number, { cwd: workspaceRoot });
+    if (!pr) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `PR #${number} not found or forge unavailable` }));
+        return;
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(pr));
+}
 /**
  * GET /api/issue-search — the data source for the VSCode "Search Backlog"
  * editor-tab webview (#920). Returns the issue set for the requested
@@ -1161,6 +1243,253 @@ async function handleNotify(req, res, ctx) {
 // ============================================================================
 // POST /api/send — send a message to a resolved agent terminal
 // ============================================================================
+/** Minimal JSON responder for the send route. */
+function sendJson(res, status, payload) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(payload));
+}
+/**
+ * The specific architect NAME whose live terminal is `terminalId`, or null when
+ * `terminalId` is a builder/shell terminal. Reverse-maps via the routing registry
+ * (Spec 1313): storing the canonical architect name on a mailbox row is what lets
+ * held mail redeliver to the right terminal after a respawn, and it also tells an
+ * architect target from a builder target for message formatting.
+ */
+function architectNameForTerminal(workspacePath, terminalId) {
+    const entry = getWorkspaceTerminals().get(workspacePath);
+    if (!entry)
+        return null;
+    for (const [name, tid] of entry.architects) {
+        if (tid === terminalId)
+            return name;
+    }
+    return null;
+}
+/**
+ * The canonical mailbox identity of a live-resolved target: architect targets are
+ * stored under their SPECIFIC architect name (reverse-mapped from the terminal),
+ * everything else under its resolved agent id.
+ */
+function liveTargetIdentity(result) {
+    const archName = architectNameForTerminal(result.workspacePath, result.terminalId);
+    return { toAgent: archName ?? result.agent, isArchitectTarget: archName !== null };
+}
+/** Format a message per sender/target — preserves the pre-1313 formatting rules. */
+function formatMessageForTarget(isArchitectTarget, from, message, raw) {
+    // #1494: a human's approval relayed by the VS Code extension gets its own
+    // header, so the architect can tell it from a peer-architect instruction.
+    if (isArchitectTarget && from === VSCODE_USER_SENDER)
+        return formatUserViaVsCodeMessage(message, undefined, raw);
+    if (isArchitectTarget && from)
+        return formatBuilderMessage(from, message, undefined, raw); // builder → architect
+    if (!isArchitectTarget)
+        return formatArchitectMessage(message, undefined, raw); // any → builder
+    return raw ? message : formatArchitectMessage(message, undefined, false); // unknown → architect
+}
+/**
+ * Route a cron notification through the Spec 1313 mailbox + gate — the Tower-wired
+ * front half of {@link deliverCronMail} (Phase 6). Resolves the task's target to a
+ * canonical recipient agent: a live terminal via {@link resolveTarget} plus the
+ * architect reverse-map ({@link liveTargetIdentity}, because a bare `architect`
+ * target resolves to the generic id, which the mailbox can't address), or — when the
+ * agent is known but has no live PTY — via {@link resolveAgentInRegistry}, so the
+ * message HOLDS as `no-live-pty` instead of vanishing (spec decision 9). Then it
+ * hands off to the registry-free core. Cron is a non-builder sender, so no
+ * sender-affinity or spoofing check applies. Wired into the cron scheduler as its
+ * `deliver` port (see `initCron`), keeping the scheduler ignorant of mailbox
+ * internals and giving cron exactly one gated path shared with `handleSend`.
+ */
+export async function deliverCronMessage(task, message, log) {
+    const db = getGlobalDb();
+    const ports = makeDeliveryPorts(log);
+    // Preserve the pre-1313 cron framing: a message FROM the `af-cron` pseudo-builder,
+    // regardless of whether the target is an architect or a builder.
+    const base = {
+        body: message,
+        formattedMessage: formatBuilderMessage(CRON_SENDER, message),
+        supersedeKey: task.name,
+    };
+    const live = resolveTarget(task.target, task.workspacePath);
+    if (!isResolveError(live)) {
+        const { toAgent } = liveTargetIdentity(live);
+        return deliverCronMail(ports, db, {
+            ...base,
+            workspacePath: live.workspacePath,
+            toAgent,
+            terminalId: live.terminalId,
+        });
+    }
+    // Live resolution failed. A NOT_FOUND target may still be a known agent with no
+    // live PTY (Tower restarting, builder between respawns) — hold its mail so a
+    // respawn drains it, instead of the old blind drop-with-WARN (decision 9).
+    if (live.code === 'NOT_FOUND') {
+        const reg = resolveAgentInRegistry(task.target, task.workspacePath);
+        if (!isResolveError(reg)) {
+            return deliverCronMail(ports, db, {
+                ...base,
+                workspacePath: reg.workspacePath,
+                toAgent: reg.agent,
+                terminalId: null,
+            });
+        }
+    }
+    log('WARN', `Cron '${task.name}': target '${task.target}' not found — message not delivered`);
+    return { outcome: 'unresolved', reason: null, mailboxId: null };
+}
+/**
+ * Persist a `held` mailbox row and write the Spec 1313 `held` send response. Used
+ * for both dead-session cases (no live PTY, held `no-live-pty`). The row exists
+ * before the response returns, so the backstop drainer will redeliver it once the
+ * agent has a clean prompt — nothing is dropped.
+ */
+function holdAndRespond(res, ctx, input, reason) {
+    const row = enqueueMailbox(getGlobalDb(), { ...input, reason });
+    ctx.log('INFO', `Message held (${reason}) → ${input.toAgent} @ ${path.basename(input.workspacePath)} (mailbox ${row.id.slice(0, 8)}...)`);
+    // A new held row appeared → refresh the held-count indicator (Spec 1313, Phase 7).
+    ctx.broadcastNotification({ type: 'overview-changed', title: 'Held mail changed', body: `held ${reason}` });
+    sendJson(res, 200, {
+        ok: true,
+        terminalId: input.terminalId ?? null,
+        resolvedTo: input.toAgent,
+        deferred: true, // back-compat: a held message is "deferred" to old binaries
+        delivered: false,
+        held: true,
+        reason,
+        mailboxId: row.id,
+    });
+}
+/**
+ * Handle a delayed (`--delay`) send (Spec 1307, re-homed onto the Spec 1313 mailbox; round 3
+ * durable rework). The row is RESOLVED, authorized (the builder-spoofing check inside
+ * `resolveTarget`), formatted, and PERSISTED here at REQUEST time with `not_before = now +
+ * delay*1000` — the security property the immediate path documents (a delayed send must not
+ * defer an authorization check past the conditions that would fail it) is preserved, and only
+ * DELIVERY is deferred. Persisting at request time is what makes `--delay` DURABLE across a
+ * Tower restart (the conscious, architect+maintainer-approved reversal of Spec 1307's
+ * drop-on-restart semantics): the render gate still guarantees a post-restart delivery only
+ * ever lands on a verified-empty prompt, and a pre-due row is visible/cancellable in
+ * `afx inbox`.
+ *
+ * Resolution is live-first then registry (a known agent with no live PTY) so a
+ * dead/unwritable/registry-only target schedules UNIFORMLY — a delayed send does not require a
+ * live session now. reason is left null: the row is SCHEDULED, not held-for-a-reason; the
+ * drainer re-evaluates liveness at due time.
+ *
+ * The body is NEVER written from here. A normal delayed send is delivered by the gated
+ * backstop drainer once `not_before` passes (≤ one 1.5 s tick after due — the delay is a lower
+ * bound). A delayed `--interrupt` (change 2 reshape) additionally keeps a small in-memory timer
+ * that fires ONLY the Ctrl+C at due time (guarded by `isStillLive` + a re-fetched writable
+ * session, inside the submission lock); the ^C ends the turn and the body then delivers through
+ * the SAME gate every send uses — nothing is marked delivered here, so a #1198 dropped write or
+ * a shutdown during the wait can never falsely report delivery or double-deliver. A restart
+ * during the wait loses only the ^C nudge, never the message.
+ */
+function handleDelayedSend(res, ctx, db, params) {
+    const { to, workspace, from, message, raw, noEnter, interrupt, deliverAfter, senderWorkspace } = params;
+    const now = Date.now();
+    const notBefore = now + deliverAfter * 1000;
+    // Resolve to a canonical AGENT — live first, then registry (known agent, no live PTY yet).
+    let workspacePath;
+    let toAgent;
+    let isArchitectTarget;
+    let terminalId;
+    const live = resolveTarget(to, workspace, from);
+    if (!isResolveError(live)) {
+        const identity = liveTargetIdentity(live);
+        workspacePath = live.workspacePath;
+        toAgent = identity.toAgent;
+        isArchitectTarget = identity.isArchitectTarget;
+        terminalId = live.terminalId;
+    }
+    else if (live.code === 'NOT_FOUND') {
+        const reg = resolveAgentInRegistry(to, workspace, from);
+        if (isResolveError(reg)) {
+            const statusCode = reg.code === 'AMBIGUOUS' ? 409 : reg.code === 'NO_CONTEXT' ? 400 : 404;
+            const errorCode = reg.code === 'NO_CONTEXT' ? 'INVALID_PARAMS' : reg.code;
+            sendJson(res, statusCode, { error: errorCode, message: reg.message });
+            return;
+        }
+        workspacePath = reg.workspacePath;
+        toAgent = reg.agent;
+        isArchitectTarget = reg.kind === 'architect';
+        terminalId = null;
+    }
+    else {
+        const statusCode = live.code === 'AMBIGUOUS' ? 409 : live.code === 'NO_CONTEXT' ? 400 : 404;
+        const errorCode = live.code === 'NO_CONTEXT' ? 'INVALID_PARAMS' : live.code;
+        sendJson(res, statusCode, { error: errorCode, message: live.message });
+        return;
+    }
+    const formattedMessage = formatMessageForTarget(isArchitectTarget, from, message, raw);
+    // Persist NOW, at request time, with the due time. reason=null → SCHEDULED, not stuck.
+    const row = enqueueMailbox(db, {
+        workspacePath,
+        toAgent,
+        body: message,
+        formattedMessage,
+        fromAgent: from ?? null,
+        fromWorkspace: senderWorkspace,
+        noEnter,
+        terminalId,
+        notBefore,
+    });
+    // A new held (scheduled) row appeared → refresh the held-count indicator (Phase 7).
+    ctx.broadcastNotification({ type: 'overview-changed', title: 'Held mail changed', body: 'scheduled' });
+    if (interrupt) {
+        // Change 2 reshape: an in-memory timer that fires ONLY the Ctrl+C at due time. It writes
+        // no message body and marks nothing delivered — the body delivers through the gated
+        // drainer after the ^C ends the turn. Everything the ^C depends on — `isStillLive`
+        // (delayed-send.ts's generation guard), the session's existence, and its writability — is
+        // re-checked INSIDE the submission lock, right before the write, so a shutdown OR a session
+        // teardown/respawn during the lock-wait writes nothing (invariant 2; the directive's
+        // preferred shape). Diagnostics arg falls back to toAgent when the target has no terminal
+        // id yet.
+        scheduleDelayedSend(deliverAfter, terminalId ?? toAgent, (isStillLive) => {
+            if (!isStillLive())
+                return; // shutdown before/at due → drop the ^C nudge (body survives)
+            if (terminalId) {
+                let fired = false;
+                void submitToSession(terminalId, () => {
+                    // Re-check EVERYTHING inside the lock: the queued submission can acquire the lock only
+                    // AFTER a shutdown or a session teardown/respawn that landed while it waited behind an
+                    // in-flight write. Re-fetch the session and re-check live + writable here; bail with no
+                    // ^C otherwise (the body still delivers via the gate).
+                    if (!isStillLive())
+                        return 0;
+                    const live = getTerminalManager().getSession(terminalId);
+                    if (!live || !live.writable)
+                        return 0;
+                    live.write('\x03'); // Ctrl+C only — end the turn; body follows via the gate
+                    fired = true;
+                    return 0; // no body, no Enter on this path
+                })
+                    .then(() => ctx.log('INFO', fired
+                    ? `Delayed interrupt ^C fired → ${toAgent} (terminal ${terminalId.slice(0, 8)}...); body delivers via the gate`
+                    : `Delayed interrupt for ${toAgent}: session not live/writable at write time — body delivers via the gate on the next clean pass`))
+                    .catch((err) => ctx.log('ERROR', `Delayed interrupt ^C failed for ${toAgent}: ${err.message}`));
+            }
+            else {
+                ctx.log('INFO', `Delayed interrupt for ${toAgent}: no live terminal at due time — body delivers via the gate on the next clean pass`);
+            }
+            // Nudge the gated drainer so the now-due body delivers promptly (gated — a spurious
+            // nudge onto a busy/mid-turn screen simply re-holds; the backstop is the ultimate net).
+            void getMailboxDrainer().scheduleDrain(workspacePath, toAgent);
+        });
+    }
+    // A normal delayed send keeps NO timer: the persisted `not_before` row is delivered by the
+    // gated backstop drainer once due — durable across restart by construction.
+    ctx.log('INFO', `Message scheduled (+${deliverAfter}s): ${from ?? 'unknown'} → ${toAgent} (mailbox ${row.id.slice(0, 8)}...)`);
+    sendJson(res, 200, {
+        ok: true,
+        terminalId,
+        resolvedTo: toAgent,
+        deferred: false,
+        scheduled: true,
+        deliverAfter,
+        mailboxId: row.id,
+        notBefore,
+    });
+}
 async function handleSend(req, res, ctx) {
     const body = await parseJsonBody(req);
     // Validate required fields
@@ -1186,111 +1515,381 @@ async function handleSend(req, res, ctx) {
     const raw = options.raw === true;
     const noEnter = options.noEnter === true;
     const interrupt = options.interrupt === true;
-    // Resolve the target address to a terminal ID.
+    const escape = options.escape === true;
+    // Spec 1307 `--delay` (re-homed onto the mailbox): optional deferred delivery.
+    // Validated here as well as at the CLI boundary — /api/send is a public route, so an
+    // unvalidated value would become a setTimeout that fires instantly (NaN) or never
+    // (Infinity). `escape` cannot be combined with a delay: an ESC interrupts the CURRENT
+    // turn by design, so deferring it is contradictory — refuse rather than silently drop
+    // one of the two (a quietly-dropped delay would look like it worked).
+    let deliverAfter;
+    if (options.deliverAfter !== undefined && options.deliverAfter !== null) {
+        const delayError = validateDelaySeconds(options.deliverAfter);
+        if (delayError) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'INVALID_PARAMS', message: delayError }));
+            return;
+        }
+        if (escape) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: 'INVALID_PARAMS',
+                message: 'escape cannot be combined with a delay: an ESC keystroke bypasses buffering by design so that it interrupts the CURRENT turn. Send the ESC now, or send a delayed message without escape.',
+            }));
+            return;
+        }
+        deliverAfter = options.deliverAfter;
+    }
+    const db = getGlobalDb();
+    const senderWorkspace = fromWorkspace ?? workspace ?? 'unknown';
+    // Spec 1313 round 3: a delayed send (`--delay`) is RESOLVED, authorized, formatted, and
+    // PERSISTED here at REQUEST time, then deferred — it does NOT require a live session now,
+    // so it is handled BEFORE the immediate live/dead/unwritable/escape/interrupt branches
+    // below (those would 404/503 a delayed send to a target that has no live PTY yet). Only
+    // DELIVERY is deferred, through the same render gate every send uses; the row's `not_before`
+    // makes the delay durable across a Tower restart.
+    if (deliverAfter !== undefined) {
+        handleDelayedSend(res, ctx, db, {
+            to, workspace, from, message, raw, noEnter, interrupt, deliverAfter, senderWorkspace,
+        });
+        return;
+    }
+    // Resolve the target address against LIVE terminals.
     // Spec 755: pass `from` so architect resolution is sender-affinity-aware
     // when the sender is a builder. Non-builder senders see unchanged behavior.
     const result = resolveTarget(to, workspace, from);
+    // --- Resolution failed against live terminals ---
     if (isResolveError(result)) {
-        const statusCode = result.code === 'AMBIGUOUS' ? 409
-            : result.code === 'NO_CONTEXT' ? 400
-                : 404;
+        // Spec 1313 dead-session seam: a NOT_FOUND target may still be a KNOWN agent
+        // with no live PTY (e.g. registered in global.db while Tower restarts). Hold
+        // its mail instead of 404ing. escape/interrupt act on a live session only, so
+        // an unresolved target keeps the original error for them.
+        if (result.code === 'NOT_FOUND' && !escape && !interrupt) {
+            const reg = resolveAgentInRegistry(to, workspace, from);
+            if (!isResolveError(reg)) {
+                holdAndRespond(res, ctx, {
+                    workspacePath: reg.workspacePath,
+                    toAgent: reg.agent,
+                    body: message,
+                    formattedMessage: formatMessageForTarget(reg.kind === 'architect', from, message, raw),
+                    fromAgent: from ?? null,
+                    fromWorkspace: senderWorkspace,
+                    noEnter,
+                    terminalId: null,
+                }, 'no-live-pty');
+                return;
+            }
+            if (reg.code === 'AMBIGUOUS') {
+                sendJson(res, 409, { error: 'AMBIGUOUS', message: reg.message });
+                return;
+            }
+            // else: fall through to the original live-resolution error below.
+        }
+        const statusCode = result.code === 'AMBIGUOUS' ? 409 : result.code === 'NO_CONTEXT' ? 400 : 404;
         // Map NO_CONTEXT to INVALID_PARAMS per plan's error contract
         const errorCode = result.code === 'NO_CONTEXT' ? 'INVALID_PARAMS' : result.code;
-        res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: errorCode, message: result.message }));
+        sendJson(res, statusCode, { error: errorCode, message: result.message });
         return;
     }
-    // Get the terminal session
+    // --- Live target resolved; locate its session ---
     const manager = getTerminalManager();
     const session = manager.getSession(result.terminalId);
+    const { toAgent, isArchitectTarget } = liveTargetIdentity(result);
+    // Dead session: the routing entry resolved but the PTY is gone (exited > 30s).
+    // Hold a normal message; escape/interrupt need a live session → original 404.
     if (!session) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            error: 'NOT_FOUND',
-            message: `Terminal session ${result.terminalId} not found (agent '${result.agent}' resolved but terminal is gone).`,
-        }));
+        if (escape || interrupt) {
+            sendJson(res, 404, {
+                error: 'NOT_FOUND',
+                message: `Terminal session ${result.terminalId} not found (agent '${result.agent}' resolved but terminal is gone).`,
+            });
+            return;
+        }
+        holdAndRespond(res, ctx, {
+            workspacePath: result.workspacePath,
+            toAgent,
+            body: message,
+            formattedMessage: formatMessageForTarget(isArchitectTarget, from, message, raw),
+            fromAgent: from ?? null,
+            fromWorkspace: senderWorkspace,
+            noEnter,
+            terminalId: result.terminalId,
+        }, 'no-live-pty');
         return;
     }
     // #1198: a session whose shellper connection died still reports status
-    // 'running', but every write to it is dropped. Fail the send loudly
-    // instead of logging "Message sent" for a message that went nowhere.
+    // 'running', but every write is dropped. Hold a normal message (it delivers
+    // when the connection recovers); keep the loud 503 for escape/interrupt, which
+    // are operator actions that require the live PTY here and now.
     if (!session.writable) {
-        ctx.log('ERROR', `Message DROPPED: ${from ?? 'unknown'} → ${result.agent} (terminal ${result.terminalId.slice(0, 8)}...): terminal not writable (shellper connection down)`);
-        res.writeHead(503, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            error: 'TERMINAL_NOT_WRITABLE',
-            message: `Terminal for '${result.agent}' is not accepting input (its process connection is down). Retry shortly; if this persists, check Tower logs.`,
-        }));
+        if (escape || interrupt) {
+            ctx.log('ERROR', `Interrupt/ESC not deliverable: ${from ?? 'unknown'} → ${result.agent} (terminal not writable, shellper connection down)`);
+            sendJson(res, 503, {
+                error: 'TERMINAL_NOT_WRITABLE',
+                message: `Terminal for '${result.agent}' is not accepting input (its process connection is down). Retry shortly; if this persists, check Tower logs.`,
+            });
+            return;
+        }
+        holdAndRespond(res, ctx, {
+            workspacePath: result.workspacePath,
+            toAgent,
+            body: message,
+            formattedMessage: formatMessageForTarget(isArchitectTarget, from, message, raw),
+            fromAgent: from ?? null,
+            fromWorkspace: senderWorkspace,
+            noEnter,
+            terminalId: result.terminalId,
+        }, 'no-live-pty');
+        return;
+    }
+    // --- Live, writable session ---
+    // Spec 1273: `escape` delivers a bare ESC keystroke and returns. Explicit human
+    // bypass — no gate, no mailbox row. ESC ends the running turn so already-queued
+    // messages process; the trailing Enter (default) is what lets them through
+    // (matching the verified recovery `afx send <b> --raw "$(printf '\x1b')"`).
+    if (escape) {
+        // Awaited: the response must not claim delivery before the ESC and its
+        // Enter have actually been written (Spec 1273 verify).
+        await submitToSession(result.terminalId, () => writeEscapeToSession(session, noEnter));
+        broadcastMessage({
+            type: 'message',
+            from: { project: path.basename(senderWorkspace), agent: from ?? 'unknown' },
+            to: { project: path.basename(result.workspacePath), agent: toAgent },
+            content: '<ESC>',
+            metadata: { raw: true, source: 'api', escape: true },
+            timestamp: new Date().toISOString(),
+        });
+        ctx.log('INFO', `Interrupt (ESC) sent: ${from ?? 'unknown'} → ${toAgent} (terminal ${result.terminalId.slice(0, 8)}...)`);
+        sendJson(res, 200, { ok: true, terminalId: result.terminalId, resolvedTo: toAgent, deferred: false });
         return;
     }
-    // Format the message based on sender/target
-    const isArchitectTarget = result.agent === 'architect';
-    let formattedMessage;
-    if (isArchitectTarget && from) {
-        // Builder → Architect
-        formattedMessage = formatBuilderMessage(from, message, undefined, raw);
-    }
-    else if (!isArchitectTarget) {
-        // Architect → Builder (or any → builder)
-        formattedMessage = formatArchitectMessage(message, undefined, raw);
-    }
-    else {
-        // Unknown sender to architect — use raw
-        formattedMessage = raw ? message : formatArchitectMessage(message, undefined, false);
-    }
-    // Build broadcast payload (used for both immediate and deferred delivery)
-    const senderWorkspace = fromWorkspace ?? workspace ?? 'unknown';
-    const broadcastPayload = {
-        type: 'message',
-        from: {
-            project: path.basename(senderWorkspace),
-            agent: from ?? 'unknown',
-        },
-        to: {
-            project: path.basename(result.workspacePath),
-            agent: result.agent,
-        },
-        content: message,
-        metadata: { raw, source: 'api' },
-        timestamp: new Date().toISOString(),
-    };
-    const logMessage = `Message sent: ${from ?? 'unknown'} → ${result.agent} (terminal ${result.terminalId.slice(0, 8)}...)`;
-    // Optionally interrupt first — bypass buffering entirely
+    const formattedMessage = formatMessageForTarget(isArchitectTarget, from, message, raw);
+    // NB: `--delay` (deliverAfter) is handled earlier by handleDelayedSend, before this
+    // immediate-path block — a delayed send is resolved + persisted at request time and does
+    // not fall through here.
+    // Spec 1313: `interrupt` is the explicit human bypass. Ctrl+C, then deliver
+    // WITHOUT the render-gate (the operator is looking at this terminal). A row is
+    // still persisted and marked delivered for audit parity — every send is a row.
     if (interrupt) {
-        session.write('\x03'); // Ctrl+C
-        await new Promise(resolve => setTimeout(resolve, 100));
-    }
-    // Check if user is idle — deliver immediately or buffer (Spec 403, Bugfix #450)
-    // Defer only when user has typed recently (within idle threshold).
-    // Bugfix #492: removed session.composing check — composing gets stuck true
-    // after non-Enter keystrokes (Ctrl+C, arrows, Tab), causing 60s delays.
-    const shouldDefer = !interrupt && !session.isUserIdle(sendBuffer.idleThresholdMs);
-    if (shouldDefer) {
-        // User is actively typing — buffer for deferred delivery
-        sendBuffer.enqueue({
-            sessionId: result.terminalId,
+        const row = enqueueMailbox(db, {
+            workspacePath: result.workspacePath,
+            toAgent,
+            body: message,
             formattedMessage,
+            fromAgent: from ?? null,
+            fromWorkspace: senderWorkspace,
             noEnter,
-            timestamp: Date.now(),
-            broadcastPayload,
-            logMessage,
+            terminalId: result.terminalId,
+        });
+        // Claim the row as delivered SYNCHRONOUSLY, before any await (CMAP round 2 — Codex): the
+        // interrupt writes the message itself (a gate bypass), so the row must never be visible to
+        // the mailbox drainer as `held`, or a concurrent backstop/scheduleDrain pass could gate-deliver
+        // the SAME row and put the bytes on the wire twice. enqueue→markDelivered are both synchronous
+        // (no await between), so there is no window for the drainer to pick it up before we own it.
+        // Tradeoff (CMAP round 3 — Codex/Claude): claiming BEFORE the write below means that if
+        // submitToSession throws/crashes, the row reads `delivered` for audit though no bytes reached
+        // the PTY — the message is lost, not retried. This is the deliberate choice: the write is not
+        // transactional, so a partial write may already have put bytes on the wire, and re-holding (the
+        // alternative) would let the backstop gate-deliver a SECOND copy. Losing a crashed interrupt is
+        // preferred over double-delivering it; `--interrupt` is the explicit human gate-bypass anyway.
+        markMailboxDelivered(db, row.id);
+        // Deliver the interrupt as ONE atomic critical section under the Spec 1273 per-terminal
+        // submission lock (CMAP round 1 — Gemini/Codex/Claude): the Ctrl+C, its 100 ms settle, and
+        // the message write all occur inside a single lock acquisition. Previously the \x03 + the
+        // settle sat OUTSIDE the lock, so a concurrent submission to the same terminal could land
+        // its Ctrl+C inside another submission's text→Enter window (killing that composer) or run
+        // during the 100 ms gap. `writeMessageToSession(..., 100)` schedules the text 100 ms after
+        // the ^C (the settle) and returns the completion offset, so the lock is held until the
+        // whole interrupt is on the wire; uncontended, it runs at once.
+        //   Scope of the guarantee: this serializes interrupt against interrupt/escape — the only
+        //   /api/send writers that take this per-terminal lock. It does NOT serialize against a
+        //   concurrent mailbox/backstop delivery (which writes through the per-AGENT serializer, a
+        //   disjoint lock); interrupt is the explicit gate-bypassing human action, and closing that
+        //   cross-path race would require the mailbox write edge to take this lock too (a separate,
+        //   larger change — flagged, not done here).
+        await submitToSession(result.terminalId, () => {
+            session.write('\x03'); // Ctrl+C
+            return writeMessageToSession(session, formattedMessage, noEnter, 100);
+        });
+        broadcastMessage({
+            type: 'message',
+            from: { project: path.basename(senderWorkspace), agent: from ?? 'unknown' },
+            to: { project: path.basename(result.workspacePath), agent: toAgent },
+            content: message,
+            metadata: { raw, source: 'api' },
+            timestamp: new Date().toISOString(),
         });
-        ctx.log('INFO', `Message deferred (user typing): ${from ?? 'unknown'} → ${result.agent} (terminal ${result.terminalId.slice(0, 8)}...)`);
+        ctx.log('INFO', `Message delivered (interrupt): ${from ?? 'unknown'} → ${toAgent} (terminal ${result.terminalId.slice(0, 8)}...)`);
+        sendJson(res, 200, {
+            ok: true,
+            terminalId: result.terminalId,
+            resolvedTo: toAgent,
+            deferred: false,
+            delivered: true,
+            held: false,
+            mailboxId: row.id,
+            reason: null,
+        });
+        return;
     }
-    else {
-        // User is idle (or interrupt) — deliver immediately.
-        // Bugfix #584: paces multi-line output to avoid paste detection.
-        writeMessageToSession(session, formattedMessage, noEnter);
-        broadcastMessage(broadcastPayload);
-        ctx.log('INFO', logMessage);
+    // Spec 1313 normal path: PERSIST first (survives a crash), then attempt gated
+    // delivery through the single serialized path. The response reports the row's
+    // real first outcome — a clean, render-verified empty prompt delivers now;
+    // anything else (busy/menu/wrapper/no-profile) stays held for the backstop.
+    const row = enqueueMailbox(db, {
+        workspacePath: result.workspacePath,
+        toAgent,
+        body: message,
+        formattedMessage,
+        fromAgent: from ?? null,
+        fromWorkspace: senderWorkspace,
+        noEnter,
+        terminalId: result.terminalId,
+    });
+    // Deliver to the session THIS request already resolved rather than re-resolving
+    // by agent: the base resolver would repeat the routing-map lookup (redundant) and
+    // could target a different terminal if the map changed mid-request. The backstop
+    // drainer, which only has the agent, still uses the base resolver.
+    const basePorts = makeDeliveryPorts(ctx.log);
+    const ports = {
+        ...basePorts,
+        getSessionForAgent: (ws, agent) => ws === result.workspacePath && agent === toAgent ? session : basePorts.getSessionForAgent(ws, agent),
+    };
+    try {
+        await deliverAgentMailSerialized(ports, db, result.workspacePath, toAgent);
     }
-    res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({
+    catch (err) {
+        // A gate/write error leaves the row HELD (markDelivered only runs on a
+        // completed write); the backstop drainer will retry. Report held, not a 500.
+        ctx.log('ERROR', `Delivery attempt errored for ${toAgent} (row ${row.id.slice(0, 8)}... stays held): ${err.message}`);
+    }
+    const stored = getMailboxById(db, row.id);
+    if (stored?.status === 'delivered') {
+        ctx.log('INFO', `Message delivered: ${from ?? 'unknown'} → ${toAgent} (terminal ${result.terminalId.slice(0, 8)}...)`);
+        sendJson(res, 200, {
+            ok: true,
+            terminalId: result.terminalId,
+            resolvedTo: toAgent,
+            deferred: false,
+            delivered: true,
+            held: false,
+            mailboxId: row.id,
+            reason: null,
+        });
+        return;
+    }
+    const reason = stored?.reason ?? 'busy';
+    ctx.log('INFO', `Message held (${reason}): ${from ?? 'unknown'} → ${toAgent} (mailbox ${row.id.slice(0, 8)}...)`);
+    // The message stayed held → a new held row is in the set; refresh the indicator
+    // count (Spec 1313, Phase 7). The delivered branch above needs no fire — the
+    // delivery path's onHeldStateChange already broadcast when the row left the set.
+    ctx.broadcastNotification({ type: 'overview-changed', title: 'Held mail changed', body: `held ${reason}` });
+    sendJson(res, 200, {
         ok: true,
         terminalId: result.terminalId,
-        resolvedTo: result.agent,
-        deferred: shouldDefer,
+        resolvedTo: toAgent,
+        deferred: true,
+        delivered: false,
+        held: true,
+        reason,
+        mailboxId: row.id,
+    });
+}
+/**
+ * GET /api/inbox — list held (undelivered) mailbox rows for a workspace. Backs the
+ * workspace-scoped `afx inbox` (Spec 1313 decision 8): `?workspace=<path>` selects the
+ * workspace (the CLI passes the current one by default); the path is normalized to the
+ * same realpath form the enqueue path stores, so a raw workspace root still matches its
+ * held rows. Omitting `?workspace=` lists every workspace — an API-level convenience the
+ * CLI never triggers, kept for direct callers. Metadata-only projection (Spec 1313
+ * redaction rule): id, addresses, why-held reason, escalation flag, and enqueue time —
+ * the message BODY is deliberately never surfaced here (it travels only over the live
+ * terminal stream on delivery). `escalated` is normalized from SQLite's 0/1 to a bool.
+ */
+function handleInboxList(res, url) {
+    const rawWorkspace = url.searchParams.get('workspace');
+    // Normalize to the stored realpath key (mailbox workspace_path is normalized at
+    // enqueue — tower-routes handleSend / holdAndRespond — matching overview.ts). Without
+    // this a symlinked workspace root would miss its own held rows.
+    const workspace = rawWorkspace ? normalizeWorkspacePath(rawWorkspace) : undefined;
+    const rows = listHeldMailbox(getGlobalDb(), workspace);
+    const projected = rows.map((r) => ({
+        id: r.id,
+        workspacePath: r.workspace_path,
+        toAgent: r.to_agent,
+        fromAgent: r.from_agent,
+        reason: r.reason,
+        escalated: r.escalated === 1,
+        createdAt: r.created_at,
+        // Spec 1313 round 3: due time of a pre-due delayed (`--delay`) row; null = deliver-ASAP.
+        // The CLI renders "in Ns" for a row whose notBefore is still in the future.
+        notBefore: r.not_before,
     }));
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(projected));
+}
+/**
+ * POST /api/inbox/:id/dismiss — mark a held row `dismissed` (operator-cleared via
+ * `afx inbox dismiss`). Soft transition: the row is marked, not deleted, and NEVER
+ * delivered. The dispatch matches this path for ANY method, so the method is guarded
+ * here: a non-POST request (e.g. GET) must not mutate state → 405. 404 when the id names
+ * no currently-held row (already terminal or unknown), so the CLI reports a clean error.
+ * On success, fires `overview-changed` so the held-count indicator drops immediately.
+ * Authorized at the workspace-human trust level — any local operator may dismiss any held
+ * row (Spec 1313 decision 8); no ownership check.
+ */
+function handleInboxDismiss(req, res, ctx, match) {
+    // Dismissal mutates state — only POST may reach it. The path match in the dispatch is
+    // method-agnostic, so without this guard a GET (or any method) to this URL would dismiss
+    // mail. Matches the method-guard convention used by the cron action routes.
+    if (req.method !== 'POST') {
+        sendJson(res, 405, { error: 'Method not allowed' });
+        return;
+    }
+    const id = decodeURIComponent(match[1]);
+    if (!dismissMailbox(getGlobalDb(), id)) {
+        sendJson(res, 404, { error: 'NOT_FOUND', message: `No held message with id '${id}'` });
+        return;
+    }
+    ctx.broadcastNotification({ type: 'overview-changed', title: 'Held mail changed', body: 'dismissed' });
+    ctx.log('INFO', `Inbox: dismissed held message ${id.slice(0, 8)}...`);
+    sendJson(res, 200, { ok: true });
+}
+/**
+ * GET /api/inbox/:id — return a single mailbox row INCLUDING its body. Backs
+ * `afx inbox show <id>` (Spec 1313 §178: `afx inbox` is a UI surface that legitimately
+ * displays message bodies over the local Tower connection — the redaction rule applies to
+ * logs/diagnostics/telemetry only, never this view). Mirrors dismiss's addressing model:
+ * by unique id at the workspace-human trust level, no per-recipient/workspace ownership
+ * check (decision 8). GET-only (the path match in the dispatch is method-agnostic, so a
+ * non-GET is rejected here); 404 when the id names no row. The body is returned to the
+ * caller but never logged.
+ */
+function handleInboxShow(req, res, match) {
+    if (req.method !== 'GET') {
+        sendJson(res, 405, { error: 'Method not allowed' });
+        return;
+    }
+    const id = decodeURIComponent(match[1]);
+    const row = getMailboxById(getGlobalDb(), id);
+    if (!row) {
+        sendJson(res, 404, { error: 'NOT_FOUND', message: `No message with id '${id}'` });
+        return;
+    }
+    sendJson(res, 200, {
+        id: row.id,
+        workspacePath: row.workspace_path,
+        toAgent: row.to_agent,
+        fromAgent: row.from_agent,
+        fromWorkspace: row.from_workspace,
+        status: row.status,
+        reason: row.reason,
+        escalated: row.escalated === 1,
+        body: row.body,
+        createdAt: row.created_at,
+        notBefore: row.not_before,
+        resolvedAt: row.resolved_at,
+    });
 }
 async function handleBrowse(res, url) {
     const inputPath = url.searchParams.get('path') || '';
@@ -1414,14 +2013,68 @@ function handleDashboard(res, ctx) {
     }
     try {
         const template = fs.readFileSync(ctx.templatePath, 'utf-8');
-        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-        res.end(template);
+        sendKeyInjectedHtml(res, template);
     }
     catch (err) {
         res.writeHead(500, { 'Content-Type': 'text/plain' });
         res.end('Error loading template: ' + err.message);
     }
 }
+/**
+ * Same-origin key injection (advisory GHSA-xvjp-7748-v88v Layer 4). Writes the
+ * shared local key into an HTML shell Tower serves (tower.html or the React SPA
+ * index.html) so the page can authenticate its own API/WebSocket calls, without
+ * embedding a readable secret in the shipped template. The key is hex, so
+ * JSON.stringify yields a safe `<script>`-embeddable literal.
+ *
+ * tower.html carries an explicit placeholder; the built SPA index.html does not,
+ * so the script is inserted before `</head>` there — ahead of the deferred SPA
+ * module, so `window.__CODEV_TOWER_KEY__` is set before the app's first request.
+ */
+function injectWebKey(html) {
+    const key = getExpectedKey();
+    // Only embed a well-formed hex key. `ensureLocalKey` always produces 64 hex
+    // chars; validating before embedding means a hand-edited or third-party-written
+    // key file containing e.g. `</script>` can never become stored XSS in a shell.
+    // A malformed key yields no injection (clients then fail closed with 401).
+    const injection = key && /^[0-9a-f]{64}$/.test(key)
+        ? `<script>window.__CODEV_TOWER_KEY__ = ${JSON.stringify(key)};</script>`
+        : '';
+    if (html.includes('<!-- CODEV_TOWER_KEY_INJECTION -->')) {
+        return html.replace('<!-- CODEV_TOWER_KEY_INJECTION -->', injection);
+    }
+    if (injection && html.includes('</head>')) {
+        return html.replace('</head>', `${injection}</head>`);
+    }
+    return html;
+}
+/**
+ * Send a key-injected HTML shell. Strips the CORS `Access-Control-Allow-Origin`
+ * header set by the front door: this response body carries the key, and the
+ * shell is only ever loaded by a same-origin navigation, so it must never be
+ * readable by a cross-origin `fetch` (advisory GHSA-xvjp-7748-v88v). Same-origin
+ * reads are unaffected; the key check still guards the actual API routes.
+ */
+function sendKeyInjectedHtml(res, template) {
+    res.removeHeader('Access-Control-Allow-Origin');
+    res.removeHeader('Vary');
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(injectWebKey(template));
+}
+/**
+ * Serve the React dashboard's index.html with the key injected (SPA shell + SPA
+ * client-side-routing fallback). Returns false if the file cannot be read.
+ */
+function serveDashboardIndex(dashboardPath, res) {
+    try {
+        const html = fs.readFileSync(path.join(dashboardPath, 'index.html'), 'utf-8');
+        sendKeyInjectedHtml(res, html);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 // ============================================================================
 // Workspace-scoped route handler
 // ============================================================================
@@ -1484,22 +2137,24 @@ async function handleWorkspaceRoutes(req, res, ctx, url) {
     // 3. React dashboard is available
     // 4. Workspace doesn't need to be running for static files
     if (!isApiCall && !isWsPath && ctx.hasReactDashboard) {
-        // Determine which static file to serve
-        let staticPath;
-        if (!subPath || subPath === '' || subPath === 'index.html') {
-            staticPath = path.join(ctx.reactDashboardPath, 'index.html');
+        // The SPA shell (index.html) is served with the shared key injected same-origin
+        // (advisory GHSA-xvjp-7748-v88v) so a direct navigation to a workspace URL can
+        // authenticate without first visiting the Tower root. Other static assets
+        // (JS/CSS/images) carry no secret and stream as-is.
+        const isIndex = !subPath || subPath === '' || subPath === 'index.html';
+        if (isIndex) {
+            if (serveDashboardIndex(ctx.reactDashboardPath, res)) {
+                return;
+            }
         }
         else {
-            // Check if it's a static asset
-            staticPath = path.join(ctx.reactDashboardPath, subPath);
-        }
-        // Try to serve the static file
-        if (serveStaticFile(staticPath, res)) {
-            return;
+            const staticPath = path.join(ctx.reactDashboardPath, subPath);
+            if (serveStaticFile(staticPath, res)) {
+                return;
+            }
         }
-        // SPA fallback: serve index.html for client-side routing
-        const indexPath = path.join(ctx.reactDashboardPath, 'index.html');
-        if (serveStaticFile(indexPath, res)) {
+        // SPA fallback: serve the (key-injected) index.html for client-side routing.
+        if (serveDashboardIndex(ctx.reactDashboardPath, res)) {
             return;
         }
     }
@@ -1854,6 +2509,13 @@ async function handleWorkspaceShellCreate(res, ctx, workspacePath) {
                 const session = manager.createSessionRaw({
                     label: `Shell ${shellId.replace('shell-', '')}`,
                     cwd: workspacePath,
+                    // Spec 1313: thread/persist for reconstruction symmetry with the other
+                    // createSessionRaw sites. A workspace-root shell resolves to no-profile
+                    // (its command is a shell, not an agent, and the cwd has no launch script),
+                    // so `afx send` correctly holds. (A shell whose cwd happened to be a builder
+                    // worktree would resolve that worktree's harness via the launch-script fallback.)
+                    command: shellCmd,
+                    args: shellArgs,
                 });
                 const ptySession = manager.getSession(session.id);
                 if (ptySession) {
@@ -1861,7 +2523,7 @@ async function handleWorkspaceShellCreate(res, ctx, workspacePath) {
                 }
                 const entry = getWorkspaceTerminalsEntry(workspacePath);
                 entry.shells.set(shellId, session.id);
-                saveTerminalSession(session.id, workspacePath, 'shell', shellId, shellperInfo.pid, shellperInfo.socketPath, shellperInfo.pid, shellperInfo.startTime, session.label, workspacePath);
+                saveTerminalSession(session.id, workspacePath, 'shell', shellId, shellperInfo.pid, shellperInfo.socketPath, shellperInfo.pid, shellperInfo.startTime, session.label, workspacePath, shellCmd);
                 shellCreated = true;
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({
@@ -1890,7 +2552,7 @@ async function handleWorkspaceShellCreate(res, ctx, workspacePath) {
             });
             const entry = getWorkspaceTerminalsEntry(workspacePath);
             entry.shells.set(shellId, session.id);
-            saveTerminalSession(session.id, workspacePath, 'shell', shellId, session.pid, null, null, null, session.label, workspacePath);
+            saveTerminalSession(session.id, workspacePath, 'shell', shellId, session.pid, null, null, null, session.label, workspacePath, shellCmd);
             ctx.log('WARN', `Shell ${shellId} for ${workspacePath} is non-persistent (shellper unavailable)`);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
@@ -2143,6 +2805,13 @@ async function handleWorkspaceTabDelete(res, ctx, workspacePath, tabId) {
         return;
     }
     if (terminalId) {
+        // Issue #1261: this path discards the kill result and answers 204 either
+        // way, so a not-yet-wired Tower would report a successful close for a
+        // terminal it never touched. Refuse instead.
+        if (!instancesReady()) {
+            respondStartingUp(res);
+            return;
+        }
         // Disable shellper auto-restart if applicable, then kill the PtySession
         await killTerminalWithShellper(manager, terminalId);
         // TICK-001: Delete from SQLite
@@ -2414,16 +3083,24 @@ function handleWorkspaceAnnotate(req, res, ctx, url, workspacePath, annotateMatc
             let html = fs.readFileSync(tplPath, 'utf-8');
             const fileName = path.basename(filePath);
             const fileSize = fs.statSync(filePath).size;
+            // The shell carries the injected key (advisory GHSA-xvjp-7748-v88v), so a
+            // maliciously-named file must not become XSS (which would read the key).
+            // HTML-escape values that land in markup/attributes (safe in the JS string
+            // contexts too — it blocks `<`, `"`, `'`), and for the JSON-in-<script>
+            // value escape `<` so a filename containing `</script>` can't break out.
+            const safeFileName = escapeHtml(fileName);
+            const safeFilePath = escapeHtml(filePath);
+            const filePathJson = JSON.stringify(filePath).replace(/</g, '\\u003c');
             if (is3D) {
-                html = html.replace(/\{\{FILE\}\}/g, fileName);
-                html = html.replace(/\{\{FILE_PATH_JSON\}\}/g, JSON.stringify(filePath));
-                html = html.replace(/\{\{FORMAT\}\}/g, ext);
+                html = html.replace(/\{\{FILE\}\}/g, safeFileName);
+                html = html.replace(/\{\{FILE_PATH_JSON\}\}/g, filePathJson);
+                html = html.replace(/\{\{FORMAT\}\}/g, escapeHtml(ext));
             }
             else {
-                html = html.replace(/\{\{FILE\}\}/g, fileName);
-                html = html.replace(/\{\{FILE_PATH\}\}/g, filePath);
+                html = html.replace(/\{\{FILE\}\}/g, safeFileName);
+                html = html.replace(/\{\{FILE_PATH\}\}/g, safeFilePath);
                 html = html.replace(/\{\{BUILDER_ID\}\}/g, '');
-                html = html.replace(/\{\{LANG\}\}/g, getLanguageForExt(ext));
+                html = html.replace(/\{\{LANG\}\}/g, escapeHtml(getLanguageForExt(ext)));
                 html = html.replace(/\{\{IS_MARKDOWN\}\}/g, String(isMarkdown));
                 html = html.replace(/\{\{IS_IMAGE\}\}/g, String(isImage));
                 html = html.replace(/\{\{IS_VIDEO\}\}/g, String(isVideo));
@@ -2442,18 +3119,22 @@ function handleWorkspaceAnnotate(req, res, ctx, url, workspacePath, annotateMatc
                     initScript = `initPdf(${fileSize});`;
                 }
                 else {
-                    initScript = `fetch('file').then(r=>r.text()).then(init);`;
+                    initScript = `fetch('file',{headers:authHeaders()}).then(r=>r.text()).then(init);`;
                 }
                 html = html.replace('// FILE_CONTENT will be injected by the server', initScript);
             }
-            // Handle ?line= query param for scroll-to-line
+            // Handle ?line= query param for scroll-to-line. Validate as a bare integer
+            // before interpolating into the script — untrusted query input must never
+            // reach the key-bearing shell's markup unescaped.
             const lineParam = url.searchParams.get('line');
-            if (lineParam) {
+            if (lineParam && /^\d+$/.test(lineParam)) {
                 const scrollScript = `<script>window.addEventListener('load',()=>{setTimeout(()=>{const el=document.querySelector('[data-line="${lineParam}"]');if(el){el.scrollIntoView({block:'center'});el.classList.add('highlighted-line');}},200);})</script>`;
                 html = html.replace('</body>', `${scrollScript}</body>`);
             }
-            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-            res.end(html);
+            // Same-origin key injection so the annotator's fetches can authenticate
+            // (advisory GHSA-xvjp-7748-v88v). The shell is public (iframe navigation);
+            // its data/media sub-routes stay keyed.
+            sendKeyInjectedHtml(res, html);
         }
         catch (err) {
             res.writeHead(500, { 'Content-Type': 'text/plain' });