@cluesmith/codev 3.3.1 → 3.3.3

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

@@ -26,7 +26,7 @@ import { getBuilders, setArchitectByName } from '../state.js';
 import { DEFAULT_COLS, defaultSessionOptions } from '../../terminal/index.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 { isRateLimited, normalizeWorkspacePath, getLanguageForExt, getMimeTypeForFile, serveStaticFile, persistableCommand, logSessionIdentity, } from './tower-utils.js';
 import { handleTunnelEndpoint } from './tower-tunnel.js';
 import { getWorktreeConfig, getActivityHooks } from '../utils/config.js';
 import { ensureCodevConfigWatcher } from './codev-config-watcher.js';
@@ -35,16 +35,18 @@ import { fetchTeamGitHubData } from '../../lib/team-github.js';
 import { resolveTarget, resolveAgentInRegistry, broadcastMessage, isResolveError } from './tower-messages.js';
 import { handleCommandRoute, COMMAND_ROUTE } from './command-relay.js';
 import { handleCanvasRoute, CANVAS_ROUTE_PREFIX } from './canvas-relay.js';
-import { formatArchitectMessage, formatBuilderMessage, formatUserViaVsCodeMessage } from '../utils/message-format.js';
+import { formatArchitectMessage, formatArchitectToBuilderMessage, formatBuilderMessage, formatUserViaVsCodeMessage, isSafeSenderId, messageTooLargeError, MAX_MESSAGE_BYTES, } 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';
+import { formatVerdict } from '@cluesmith/codev-sdk/hold-verdict';
+// Spec 1273 per-terminal submission lock. Originally the anti-fusion lock for the two
+// explicit human-bypass paths (escape + interrupt); since Issue #1365 the gated mailbox
+// delivery path takes it too, so it now serializes the whole write edge of a terminal.
+// The operator paths pass a wait ceiling — see OPERATOR_SUBMIT_WAIT_CEILING_MS.
+import { submitToSession, OPERATOR_SUBMIT_WAIT_CEILING_MS } 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
@@ -649,7 +651,12 @@ 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, command ?? null);
+                    // PIR #1475: prefer the identity the shellper reports. A fresh spawn is
+                    // the no-op case (it reports back what we just asked for), but routing
+                    // it through the same accessor keeps one rule everywhere: the row
+                    // records what is RUNNING, not what was requested.
+                    logSessionIdentity(ctx.log, 'terminal-create', session.id, ptySession, command ?? null);
+                    saveTerminalSession(session.id, workspacePath, termType, roleId, shellperInfo.pid, shellperInfo.socketPath, shellperInfo.pid, shellperInfo.startTime, label ?? null, cwd ?? null, persistableCommand(ptySession) ?? command ?? null);
                     ctx.log('INFO', `Registered shellper terminal ${session.id} as ${termType} "${roleId}" for workspace ${workspacePath}`);
                 }
             }
@@ -764,8 +771,20 @@ async function handleTerminalRoutes(req, res, url, match) {
             }
             const info = manager.resizeSession(terminalId, body.cols, body.rows);
             if (!info) {
-                res.writeHead(404, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'NOT_FOUND', message: `Session ${terminalId} not found` }));
+                // Issue #1482: a resize that did not reach the process is NOT a missing session, and it
+                // is not a success either — echoing back the requested dimensions (what a 200 here used
+                // to do) is how Tower came to believe a geometry the TUI never adopted.
+                if (!manager.getSession(terminalId)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'NOT_FOUND', message: `Session ${terminalId} not found` }));
+                }
+                else {
+                    res.writeHead(409, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        error: 'RESIZE_DROPPED',
+                        message: `Session ${terminalId} did not accept the resize (no live process or dropped shellper write); dimensions unchanged`,
+                    }));
+                }
                 return;
             }
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1274,17 +1293,33 @@ 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) {
+/**
+ * Format a message per sender/target — preserves the pre-1313 formatting rules.
+ *
+ * #1574: `toAgent` is the CANONICAL recipient the mailbox row is keyed on (the
+ * architect reverse-map for architect targets, the resolved agent id otherwise),
+ * so the header a recipient reads names the same identity the row was addressed
+ * to. Passing anything else here would make the frame attest to a fiction.
+ *
+ * #1478: `from` is the SENDER, and it is threaded on the any → builder path too —
+ * that branch used to discard it, so an `architect:<name>` origin reached the
+ * builder's composer as a bare `ARCHITECT INSTRUCTION`. The two are complementary:
+ * #1574 answers "was this addressed to me?", #1478 answers "who sent it?".
+ */
+function formatMessageForTarget(isArchitectTarget, from, toAgent, 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);
+        return formatUserViaVsCodeMessage(toAgent, message, undefined, raw);
     if (isArchitectTarget && from)
-        return formatBuilderMessage(from, message, undefined, raw); // builder → architect
+        return formatBuilderMessage(from, toAgent, message, undefined, raw); // builder → architect
+    // any → builder: thread the sender so an `architect:<name>` origin is named in the
+    // header (issue #1478) instead of collapsing to a bare `ARCHITECT INSTRUCTION`.
     if (!isArchitectTarget)
-        return formatArchitectMessage(message, undefined, raw); // any → builder
-    return raw ? message : formatArchitectMessage(message, undefined, false); // unknown → architect
+        return formatArchitectToBuilderMessage(toAgent, message, undefined, raw, from); // any → builder
+    // unknown → architect: `from` is absent by construction on this branch, so there is
+    // no sender to name.
+    return raw ? message : formatArchitectMessage(toAgent, message, undefined, false); // unknown → architect
 }
 /**
  * Route a cron notification through the Spec 1313 mailbox + gate — the Tower-wired
@@ -1304,9 +1339,12 @@ export async function deliverCronMessage(task, message, log) {
     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.
+    //
+    // #1574: the frame names its recipient, which is only known AFTER resolution —
+    // so it is built per-branch rather than once up front. `base` carries everything
+    // that does not depend on the target.
     const base = {
         body: message,
-        formattedMessage: formatBuilderMessage(CRON_SENDER, message),
         supersedeKey: task.name,
     };
     const live = resolveTarget(task.target, task.workspacePath);
@@ -1314,6 +1352,7 @@ export async function deliverCronMessage(task, message, log) {
         const { toAgent } = liveTargetIdentity(live);
         return deliverCronMail(ports, db, {
             ...base,
+            formattedMessage: formatBuilderMessage(CRON_SENDER, toAgent, message),
             workspacePath: live.workspacePath,
             toAgent,
             terminalId: live.terminalId,
@@ -1327,6 +1366,7 @@ export async function deliverCronMessage(task, message, log) {
         if (!isResolveError(reg)) {
             return deliverCronMail(ports, db, {
                 ...base,
+                formattedMessage: formatBuilderMessage(CRON_SENDER, reg.agent, message),
                 workspacePath: reg.workspacePath,
                 toAgent: reg.agent,
                 terminalId: null,
@@ -1334,7 +1374,7 @@ export async function deliverCronMessage(task, message, log) {
         }
     }
     log('WARN', `Cron '${task.name}': target '${task.target}' not found — message not delivered`);
-    return { outcome: 'unresolved', reason: null, mailboxId: null };
+    return { outcome: 'unresolved', reason: null, detail: null, mailboxId: null };
 }
 /**
  * Persist a `held` mailbox row and write the Spec 1313 `held` send response. Used
@@ -1355,9 +1395,31 @@ function holdAndRespond(res, ctx, input, reason) {
         delivered: false,
         held: true,
         reason,
+        // A hold from THIS path is always a non-gate one (no live PTY), so it carries no gate
+        // detail (Issue #1482). Reported explicitly rather than omitted so the held response has
+        // one shape whichever path produced it.
+        detail: null,
         mailboxId: row.id,
+        bodyLength: Buffer.byteLength(input.body, 'utf8'),
     });
 }
+/** Machine-readable reason paired with `degraded: true` on an operator send response. */
+const DEGRADED_SUBMIT_REASON = 'submit-wait-ceiling-expired';
+/**
+ * Announce that an operator submission gave up waiting for the per-terminal lock and wrote
+ * unserialized (Issue #1365).
+ *
+ * This is the degraded path, and it is deliberately loud. The ceiling arms only against a
+ * DELIVERY write (behind another operator the wait stays unbounded, as before #1365), so what
+ * expiry falls back to is exactly the pre-#1365 operator-vs-delivery behaviour: two disjoint
+ * locks, no serialization. That one pair is therefore no worse than the old status quo — but
+ * it used to be invisible, and now it is not, here and in the `degraded` flag on the response.
+ */
+function logCeilingExpired(ctx, action, toAgent, terminalId, waitedMs) {
+    ctx.log('WARN', `${action} → ${toAgent} (terminal ${terminalId.slice(0, 8)}...) waited ${waitedMs}ms for an in-flight ` +
+        `write and proceeded UNSERIALIZED — it may interleave with that write. A message long enough to ` +
+        `hold the line this long is the usual cause.`);
+}
 /**
  * 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
@@ -1420,7 +1482,7 @@ function handleDelayedSend(res, ctx, db, params) {
         sendJson(res, statusCode, { error: errorCode, message: live.message });
         return;
     }
-    const formattedMessage = formatMessageForTarget(isArchitectTarget, from, message, raw);
+    const formattedMessage = formatMessageForTarget(isArchitectTarget, from, toAgent, message, raw);
     // Persist NOW, at request time, with the due time. reason=null → SCHEDULED, not stuck.
     const row = enqueueMailbox(db, {
         workspacePath,
@@ -1462,6 +1524,17 @@ function handleDelayedSend(res, ctx, db, params) {
                     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
+                }, undefined, 
+                // The same operator ceiling as the immediate paths (Issue #1365). This one fires
+                // UNATTENDED, so it is the writer most likely to meet a gated delivery mid-pace —
+                // which is precisely why the delayed `^C` must take this lock at all.
+                {
+                    waitCeilingMs: OPERATOR_SUBMIT_WAIT_CEILING_MS,
+                    onCeilingExpired: (waitedMs) => logCeilingExpired(ctx, 'delayed interrupt ^C', toAgent, terminalId, waitedMs),
+                    // This is the one operator path whose write can be a NO-OP (the liveness re-check
+                    // above). A degraded no-op raced nobody, so it must not bump the bypass counter —
+                    // that would make a concurrent delivery hold and re-deliver for nothing.
+                    wroteBytes: () => fired,
                 })
                     .then(() => ctx.log('INFO', fired
                     ? `Delayed interrupt ^C fired → ${toAgent} (terminal ${terminalId.slice(0, 8)}...); body delivers via the gate`
@@ -1488,6 +1561,7 @@ function handleDelayedSend(res, ctx, db, params) {
         deliverAfter,
         mailboxId: row.id,
         notBefore,
+        bodyLength: Buffer.byteLength(params.message, 'utf8'),
     });
 }
 async function handleSend(req, res, ctx) {
@@ -1505,8 +1579,38 @@ async function handleSend(req, res, ctx) {
         res.end(JSON.stringify({ error: 'INVALID_PARAMS', message: 'Missing or empty "message" field' }));
         return;
     }
+    // Issue #1573: refuse an over-large body LOUDLY, here at the route rather than only at the
+    // CLI — `/api/send` is a public local route, and the CLI is not its only caller. Nothing
+    // downstream bounded message size, so an oversized body used to be paced onto the line one
+    // line at a time and reported delivered whatever the composer made of it. Rejecting is the
+    // only honest option: truncating would reproduce #1564 on purpose.
+    const bodyLength = Buffer.byteLength(message, 'utf8');
+    if (bodyLength > MAX_MESSAGE_BYTES) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'MESSAGE_TOO_LARGE', message: messageTooLargeError(bodyLength) }));
+        return;
+    }
     // Optional fields
     const from = typeof body.from === 'string' ? body.from : undefined;
+    // Maintainer review (PR #1486): `from` was the one unguarded field on this route — the
+    // body above is bounded by MAX_MESSAGE_BYTES, but the sender was taken verbatim, and
+    // `/api/send` is a public local route whose only well-behaved caller is the CLI. It is
+    // stored on the mailbox row and rendered by every attribution surface, and `afx inbox`
+    // now sizes its `FROM → TO` column to the widest value it holds — so an unbounded
+    // identity is a rendering cost paid by every row, not just its own. Enforced with the
+    // SAME predicate the header formatter uses, so the boundary and the renderer cannot
+    // disagree about what an identity is. Refused rather than silently dropped or
+    // truncated: a message delivered under a quietly-discarded sender is exactly the
+    // unattributed frame this PR exists to fix.
+    if (from !== undefined && !isSafeSenderId(from)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            error: 'INVALID_PARAMS',
+            message: 'Invalid "from" field: a sender identity must be 1-128 characters of ' +
+                '[A-Za-z0-9._:-] (no whitespace, brackets or newlines).',
+        }));
+        return;
+    }
     const workspace = typeof body.workspace === 'string' ? body.workspace : undefined;
     const fromWorkspace = typeof body.fromWorkspace === 'string' ? body.fromWorkspace : undefined;
     const options = typeof body.options === 'object' && body.options !== null
@@ -1571,7 +1675,7 @@ async function handleSend(req, res, ctx) {
                     workspacePath: reg.workspacePath,
                     toAgent: reg.agent,
                     body: message,
-                    formattedMessage: formatMessageForTarget(reg.kind === 'architect', from, message, raw),
+                    formattedMessage: formatMessageForTarget(reg.kind === 'architect', from, reg.agent, message, raw),
                     fromAgent: from ?? null,
                     fromWorkspace: senderWorkspace,
                     noEnter,
@@ -1609,7 +1713,7 @@ async function handleSend(req, res, ctx) {
             workspacePath: result.workspacePath,
             toAgent,
             body: message,
-            formattedMessage: formatMessageForTarget(isArchitectTarget, from, message, raw),
+            formattedMessage: formatMessageForTarget(isArchitectTarget, from, toAgent, message, raw),
             fromAgent: from ?? null,
             fromWorkspace: senderWorkspace,
             noEnter,
@@ -1634,7 +1738,7 @@ async function handleSend(req, res, ctx) {
             workspacePath: result.workspacePath,
             toAgent,
             body: message,
-            formattedMessage: formatMessageForTarget(isArchitectTarget, from, message, raw),
+            formattedMessage: formatMessageForTarget(isArchitectTarget, from, toAgent, message, raw),
             fromAgent: from ?? null,
             fromWorkspace: senderWorkspace,
             noEnter,
@@ -1650,7 +1754,17 @@ async function handleSend(req, res, ctx) {
     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));
+        // Issue #1365: escape is an operator submission — it blocks behind an in-flight write
+        // (including a gated mailbox delivery, which now takes this same lock) so its ESC and
+        // Enter can no longer truncate a delivery mid-pace, but only up to the wait ceiling.
+        let escapeDegraded = false;
+        await submitToSession(result.terminalId, () => writeEscapeToSession(session, noEnter), undefined, {
+            waitCeilingMs: OPERATOR_SUBMIT_WAIT_CEILING_MS,
+            onCeilingExpired: (waitedMs) => {
+                escapeDegraded = true;
+                logCeilingExpired(ctx, 'ESC', toAgent, result.terminalId, waitedMs);
+            },
+        });
         broadcastMessage({
             type: 'message',
             from: { project: path.basename(senderWorkspace), agent: from ?? 'unknown' },
@@ -1660,10 +1774,16 @@ async function handleSend(req, res, ctx) {
             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 });
+        sendJson(res, 200, {
+            ok: true,
+            terminalId: result.terminalId,
+            resolvedTo: toAgent,
+            deferred: false,
+            ...(escapeDegraded ? { degraded: true, degradedReason: DEGRADED_SUBMIT_REASON } : {}),
+        });
         return;
     }
-    const formattedMessage = formatMessageForTarget(isArchitectTarget, from, message, raw);
+    const formattedMessage = formatMessageForTarget(isArchitectTarget, from, toAgent, 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.
@@ -1701,15 +1821,29 @@ async function handleSend(req, res, ctx) {
         // 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).
+        //   Scope of the guarantee (Issue #1365 — this used to end at "interrupt vs interrupt/escape"):
+        //   the gated mailbox delivery path now takes this SAME per-terminal lock, so an interrupt is
+        //   serialized against a concurrent delivery too. That closes the case where a `^C` landed
+        //   inside a delivery's own text→Enter window, clearing the composer while every byte still
+        //   reported success — the row read `delivered` for a message the agent never saw. The lock
+        //   order is per-agent → per-terminal (the delivery takes this one as a leaf), never the
+        //   reverse, so there is no cycle. See session-submit.ts for the full boundary.
+        // Whether this interrupt gave up waiting and wrote unserialized. It must reach the SENDER,
+        // not just the Tower log (codex review of PR #1492): the row above was claimed `delivered`
+        // before the write, so a degraded interrupt would otherwise report an unqualified success
+        // for a body that may have interleaved with the delivery it skipped. We keep the
+        // claim-first tradeoff (un-claiming risks a double delivery — see above) and tell the
+        // truth about it instead.
+        let degraded = false;
         await submitToSession(result.terminalId, () => {
             session.write('\x03'); // Ctrl+C
             return writeMessageToSession(session, formattedMessage, noEnter, 100);
+        }, undefined, {
+            waitCeilingMs: OPERATOR_SUBMIT_WAIT_CEILING_MS,
+            onCeilingExpired: (waitedMs) => {
+                degraded = true;
+                logCeilingExpired(ctx, 'interrupt', toAgent, result.terminalId, waitedMs);
+            },
         });
         broadcastMessage({
             type: 'message',
@@ -1729,6 +1863,10 @@ async function handleSend(req, res, ctx) {
             held: false,
             mailboxId: row.id,
             reason: null,
+            detail: null,
+            bodyLength,
+            // Additive and present only when it happened, so older clients are unaffected.
+            ...(degraded ? { degraded: true, degradedReason: DEGRADED_SUBMIT_REASON } : {}),
         });
         return;
     }
@@ -1755,8 +1893,12 @@ async function handleSend(req, res, ctx) {
         ...basePorts,
         getSessionForAgent: (ws, agent) => ws === result.workspacePath && agent === toAgent ? session : basePorts.getSessionForAgent(ws, agent),
     };
+    // Issue #1584: keep the outcome — it carries whether the delivered message's header was
+    // actually seen on the receiving terminal, which is the only thing the sender can act on now
+    // that an unconfirmed delivery is recorded rather than re-written.
+    let outcome = null;
     try {
-        await deliverAgentMailSerialized(ports, db, result.workspacePath, toAgent);
+        outcome = await deliverAgentMailSerialized(ports, db, result.workspacePath, toAgent);
     }
     catch (err) {
         // A gate/write error leaves the row HELD (markDelivered only runs on a
@@ -1775,11 +1917,25 @@ async function handleSend(req, res, ctx) {
             held: false,
             mailboxId: row.id,
             reason: null,
+            bodyLength,
+            // Additive (Issue #1584). `false` means the bytes were written and accepted but the header
+            // never appeared on the terminal — delivered, flagged, and NOT re-written. Reported only
+            // when THIS row is the one our own pass delivered: a pass picks the agent's OLDEST held
+            // row, so without the id check a concurrent drainer delivery of this row could be
+            // reported with another message's verification. Absent (verification skipped, or someone
+            // else's pass delivered it) reads exactly as it did before this field existed.
+            ...(outcome?.delivered.includes(row.id) && outcome.verified !== undefined
+                ? { verified: outcome.verified }
+                : {}),
         });
         return;
     }
     const reason = stored?.reason ?? 'busy';
-    ctx.log('INFO', `Message held (${reason}): ${from ?? 'unknown'} → ${toAgent} (mailbox ${row.id.slice(0, 8)}...)`);
+    // Issue #1482: read the detail back off the row the delivery pass just refreshed, rather
+    // than re-deriving it — the row is the record every other surface reads, so the sender's
+    // response and `afx inbox` can never disagree about the same hold.
+    const detail = stored?.detail ?? null;
+    ctx.log('INFO', `Message held (${formatVerdict(reason, detail)}): ${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.
@@ -1792,7 +1948,9 @@ async function handleSend(req, res, ctx) {
         delivered: false,
         held: true,
         reason,
+        detail,
         mailboxId: row.id,
+        bodyLength,
     });
 }
 /**
@@ -1805,20 +1963,55 @@ async function handleSend(req, res, ctx) {
  * 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.
+ *
+ * Issue 1450: `workspaceOverride` lets the workspace-scoped route
+ * (`/workspace/<base64>/api/inbox`, which backs the dashboard's held-mail popover) pass the
+ * workspace resolved from the URL prefix, exactly as `handleOverview` / `handleAnalytics` do.
+ * The override arrives already normalized by the prefix decoder, so `normalizeWorkspacePath`
+ * re-running on it is a safe no-op.
+ *
+ * Two separate widening hazards are closed here, because a scoped caller must never receive
+ * another workspace's held mail:
+ *   - `??` (not `||`) means `?workspace=` can never take effect once an override was passed.
+ *   - An EMPTY override does not fall through to the unscoped all-workspaces listing; it
+ *     scopes to a path that matches nothing. Today the dispatcher 400s a missing prefix so
+ *     this is unreachable, but "unreachable" is a property of the caller, not of this
+ *     function, and the safe failure for a scoped call is zero rows, never every row.
+ * The all-workspaces listing therefore remains reachable only when NO override was passed —
+ * the Tower-level route without `?workspace=`, the direct-caller convenience the CLI never uses.
+ *
+ * NOTE: this lists ALL held rows, including pre-due `--delay` rows, while the badge count
+ * (`heldSummaryForWorkspace`) excludes them — see the `HeldMessage` type for why the two
+ * legitimately disagree.
  */
-function handleInboxList(res, url) {
-    const rawWorkspace = url.searchParams.get('workspace');
+// Exported as a narrow test seam (Issue 1450): the empty-override branch below cannot be
+// reached through `handleRequest` — the workspace dispatcher rejects a missing or non-absolute
+// prefix with a 400 before this runs — so the only way to pin that guard's behaviour is to call
+// the handler directly. Production callers go through the two route tables, not this export.
+export function handleInboxList(res, url, workspaceOverride) {
+    const scoped = workspaceOverride !== undefined;
+    const rawWorkspace = workspaceOverride ?? 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;
+    // `scoped ? '' : undefined` on the empty branch: '' matches no workspace_path, so a scoped
+    // call with a blank override returns nothing rather than widening to every workspace.
+    const workspace = rawWorkspace
+        ? normalizeWorkspacePath(rawWorkspace)
+        : (scoped ? '' : undefined);
     const rows = listHeldMailbox(getGlobalDb(), workspace);
+    // Annotated, not inferred: `HeldMessage` is the shared contract this route owes its
+    // clients, so a projection that drifts from it (a dropped field, or a `body` slipping in)
+    // fails the server build rather than only surprising the dashboard at runtime.
     const projected = rows.map((r) => ({
         id: r.id,
         workspacePath: r.workspace_path,
         toAgent: r.to_agent,
         fromAgent: r.from_agent,
         reason: r.reason,
+        // Issue #1482: the gate verdict behind a `busy` hold, so `afx inbox` and the dashboard
+        // popover can distinguish an occupied composer from one the classifier could not read.
+        detail: r.detail,
         escalated: r.escalated === 1,
         createdAt: r.created_at,
         // Spec 1313 round 3: due time of a pre-due delayed (`--delay`) row; null = deliver-ASAP.
@@ -1884,6 +2077,7 @@ function handleInboxShow(req, res, match) {
         fromWorkspace: row.from_workspace,
         status: row.status,
         reason: row.reason,
+        detail: row.detail, // Issue #1482: the gate verdict behind a `busy` hold
         escalated: row.escalated === 1,
         body: row.body,
         createdAt: row.created_at,
@@ -2303,6 +2497,19 @@ async function handleWorkspaceRoutes(req, res, ctx, url) {
         if (req.method === 'GET' && apiPath === 'overview') {
             return handleOverview(res, url, workspacePath, ctx);
         }
+        // GET /api/inbox - held mailbox rows for THIS workspace (Issue 1450). Backs the
+        // dashboard's clickable held-mail counter. Reuses the Tower-level handler with the
+        // workspace resolved from the /workspace/<base64>/ prefix, the same way `overview`
+        // and `analytics` above do — the dashboard calls relative `./api/...` and has no
+        // absolute workspace path of its own to pass as `?workspace=`.
+        //
+        // Deliberately an EXACT match on 'inbox', not a prefix: `inbox/:id` (which returns the
+        // message BODY) and `inbox/:id/dismiss` (which mutates) do not match, fall through to
+        // the 404 below, and so stay off the dashboard surface. That is what keeps this read
+        // path inside Spec 1313's redaction rule and decision 8 (dismissal is CLI-only).
+        if (req.method === 'GET' && apiPath === 'inbox') {
+            return handleInboxList(res, url, workspacePath);
+        }
         // POST /api/overview/refresh - Invalidate overview cache (Spec 0126 Phase 4)
         if (req.method === 'POST' && apiPath === 'overview/refresh') {
             return handleOverviewRefresh(res, ctx);
@@ -2523,7 +2730,9 @@ 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, shellCmd);
+                // PIR #1475: hydrated identity wins; a fresh spawn reports back `shellCmd`.
+                logSessionIdentity(ctx.log, 'shell-create', session.id, ptySession, shellCmd);
+                saveTerminalSession(session.id, workspacePath, 'shell', shellId, shellperInfo.pid, shellperInfo.socketPath, shellperInfo.pid, shellperInfo.startTime, session.label, workspacePath, persistableCommand(ptySession) ?? shellCmd);
                 shellCreated = true;
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({