@cluesmith/codev 3.3.2 → 3.3.4

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

@@ -21,13 +21,16 @@ import { decodeWorkspacePath } from '../lib/tower-client.js';
 import { readCloudConfig } from '../lib/cloud-config.js';
 import { fileURLToPath } from 'node:url';
 import { version } from '../../version.js';
+import { sanitizeAgentEnv } from '../../lib/agent-env.js';
 const execAsync = promisify(exec);
 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 { handleIdeApi } from './ide-server.js';
+import { matchIdePrefix, forwardIdeHttp } from './ide-forward.js';
 import { getWorktreeConfig, getActivityHooks } from '../utils/config.js';
 import { ensureCodevConfigWatcher } from './codev-config-watcher.js';
 import { hasTeam, loadTeamMembers, loadMessages } from '../../lib/team.js';
@@ -35,12 +38,13 @@ 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, formatArchitectToBuilderMessage, formatBuilderMessage, formatUserViaVsCodeMessage, messageTooLargeError, MAX_MESSAGE_BYTES, } from '../utils/message-format.js';
-import { writeMessageToSession, writeEscapeToSession } from './message-write.js';
-import { makeDeliveryPorts, getMailboxDrainer } from './mailbox-wiring.js';
+import { formatArchitectMessage, formatArchitectToBuilderMessage, formatBuilderMessage, formatUserViaVsCodeMessage, isSafeSenderId, messageTooLargeError, MAX_MESSAGE_BYTES, } from '../utils/message-format.js';
+import { writeMessageToSession, writeEscapeToSession, writeStrategyForApp } from './message-write.js';
+import { makeDeliveryPorts, getMailboxDrainer, resolveProfileForSession } 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';
+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.
@@ -54,7 +58,7 @@ import { submitToSession, OPERATOR_SUBMIT_WAIT_CEILING_MS } from './session-subm
 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, fetchPR, searchIssues, fetchPRList, fetchCurrentUser, parseLinkedIssue, parseArea, } from '../../lib/github.js';
+import { fetchIssue, fetchPR, searchIssues, fetchPRList, fetchCurrentUser, probeGhGraphqlRateLimit, 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';
@@ -65,7 +69,8 @@ import { getWorkspaceTerminals, getTerminalManager, getWorkspaceTerminalsEntry,
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Singleton cache for overview endpoint (Spec 0126 Phase 4)
-const overviewCache = new OverviewCache();
+// #1645: the gh reset probe is enabled here, in Tower, and nowhere else.
+const overviewCache = new OverviewCache({ probe: probeGhGraphqlRateLimit });
 const ROUTES = {
     'GET /health': (_req, res, _url, ctx) => handleHealthCheck(res, ctx),
     'GET /api/shellpers/husks': (_req, res, _url, ctx) => handleHuskPreview(res, ctx),
@@ -158,6 +163,18 @@ export async function handleRequest(req, res, ctx) {
             return await handler(req, res, url, ctx);
         }
         // Pattern-based routes (require regex or prefix matching)
+        // IDE management endpoint: /api/ide (Issue #1668). Local-only — blocked from
+        // the tunnel in tunnel-client (like /api/tunnel/*) — and reached only after
+        // the isRequestAllowed key check above. Drives the IDE server lifecycle.
+        if (url.pathname === '/api/ide') {
+            return await handleIdeApi(req, res, ctx.log);
+        }
+        // IDE prefix forward: /ide/* → local IDE server (Issue #1668). A post-auth
+        // handler: isRequestAllowed above is the whole trust boundary (the forward
+        // adds no per-folder authorization). Path + query forwarded unchanged.
+        if (matchIdePrefix(url.pathname)) {
+            return await forwardIdeHttp(req, res, ctx.log);
+        }
         // Tunnel endpoints: /api/tunnel/* (Spec 0097 Phase 4)
         if (url.pathname.startsWith('/api/tunnel/')) {
             const tunnelSub = url.pathname.slice('/api/tunnel/'.length);
@@ -609,9 +626,11 @@ async function handleTerminalCreate(req, res, ctx) {
         if (requestPersistence && shellperManager && command && cwd) {
             try {
                 const sessionId = crypto.randomUUID();
-                // Strip CLAUDECODE so spawned Claude processes don't detect nesting
-                const sessionEnv = { ...(env || process.env) };
-                delete sessionEnv['CLAUDECODE'];
+                // Strip Claude Code session markers so spawned Claude processes don't
+                // detect nesting and disable transcript saving (#1219). `env` is normally
+                // absent — `createPtySession` sends no env — so this is the path by which
+                // Tower's own environment becomes every builder's environment.
+                const sessionEnv = sanitizeAgentEnv(env || process.env);
                 const client = await shellperManager.createSession({
                     sessionId,
                     command,
@@ -650,7 +669,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}`);
                 }
             }
@@ -661,7 +685,7 @@ async function handleTerminalCreate(req, res, ctx) {
         // Fallback: non-persistent session (graceful degradation per plan)
         // Shellper is the only persistence backend for new sessions.
         if (!info) {
-            info = await manager.createSession({ command, args, cols, rows, cwd, env, label });
+            info = await manager.createSession({ command, args, cols, rows, cwd, env: env && sanitizeAgentEnv(env), label });
             persistent = false;
             if (workspacePath && termType && roleId) {
                 const entry = getWorkspaceTerminalsEntry(normalizeWorkspacePath(workspacePath));
@@ -744,6 +768,9 @@ async function handleTerminalRoutes(req, res, url, match) {
                 res.end(JSON.stringify({ error: 'NOT_FOUND', message: `Session ${terminalId} not found` }));
                 return;
             }
+            // Deliberately the default `'external'` origin (Issue #1473): this is a foreign writer, so
+            // its bytes count as input at the delivery gate and are reply-filtered on the way — both
+            // for free, because the recording lives inside `write()` rather than at each call site.
             session.write(body.data);
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ ok: true }));
@@ -765,8 +792,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' });
@@ -1282,6 +1321,11 @@ function liveTargetIdentity(result) {
  * 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
@@ -1290,8 +1334,12 @@ function formatMessageForTarget(isArchitectTarget, from, toAgent, message, raw)
         return formatUserViaVsCodeMessage(toAgent, message, undefined, raw);
     if (isArchitectTarget && from)
         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 formatArchitectToBuilderMessage(toAgent, message, undefined, raw); // any → builder
+        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
 }
 /**
@@ -1347,7 +1395,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
@@ -1368,6 +1416,10 @@ 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'),
     });
@@ -1561,6 +1613,25 @@ async function handleSend(req, res, ctx) {
     }
     // 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
@@ -1787,7 +1858,10 @@ async function handleSend(req, res, ctx) {
         let degraded = false;
         await submitToSession(result.terminalId, () => {
             session.write('\x03'); // Ctrl+C
-            return writeMessageToSession(session, formattedMessage, noEnter, 100);
+            // Issue #1567: the same per-harness write strategy the gated path uses — an
+            // interrupt to an opted-out harness must not be bracketed just because it bypassed
+            // the gate.
+            return writeMessageToSession(session, formattedMessage, noEnter, 100, writeStrategyForApp(resolveProfileForSession(session)?.app));
         }, undefined, {
             waitCeilingMs: OPERATOR_SUBMIT_WAIT_CEILING_MS,
             onCeilingExpired: (waitedMs) => {
@@ -1813,6 +1887,7 @@ 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 } : {}),
@@ -1842,14 +1917,25 @@ 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
         // 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}`);
     }
+    // Issue #1473: this pass ran OUTSIDE the drainer, so hand it the outcome — otherwise a hold
+    // on recent terminal input arms no re-drain here, and the send an operator is watching falls
+    // through to the quiescence trigger or the backstop instead of clearing after one settle.
+    // That is exactly the latency the re-drain exists to remove, in the case where somebody is
+    // waiting for it. A no-op for every other outcome.
+    if (outcome)
+        getMailboxDrainer().noteOutcome(result.workspacePath, toAgent, outcome);
     const stored = getMailboxById(db, row.id);
     if (stored?.status === 'delivered') {
         ctx.log('INFO', `Message delivered: ${from ?? 'unknown'} → ${toAgent} (terminal ${result.terminalId.slice(0, 8)}...)`);
@@ -1863,11 +1949,33 @@ async function handleSend(req, res, ctx) {
             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 }
+                : {}),
+            // Issue #1473. `verified` alone was not enough for the SENDER — the case that motivated
+            // it is a human's Enter submitting our half-written body, where the header landed, so
+            // `verified` is `true` (or absent) and this human read a plain "Message delivered". The
+            // cause says which flag it is: `input-raced` (may be truncated or submitted early) or
+            // `no-echo` (header never appeared). Same id guard as `verified` — reported only when
+            // THIS pass is the one that delivered THIS row.
+            ...(outcome?.delivered.includes(row.id) && outcome.unverifiedCause !== undefined
+                ? { unverifiedCause: outcome.unverifiedCause }
+                : {}),
         });
         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.
@@ -1880,6 +1988,7 @@ async function handleSend(req, res, ctx) {
         delivered: false,
         held: true,
         reason,
+        detail,
         mailboxId: row.id,
         bodyLength,
     });
@@ -1894,20 +2003,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.
@@ -1973,6 +2117,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,
@@ -2392,6 +2537,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);
@@ -2576,9 +2734,9 @@ async function handleWorkspaceShellCreate(res, ctx, workspacePath) {
         if (shellperManager) {
             try {
                 const sessionId = crypto.randomUUID();
-                // Strip CLAUDECODE so spawned Claude processes don't detect nesting
-                const shellEnv = { ...process.env };
-                delete shellEnv['CLAUDECODE'];
+                // Strip Claude Code session markers so spawned Claude processes don't
+                // detect nesting and disable transcript saving (#1219).
+                const shellEnv = sanitizeAgentEnv(process.env);
                 // Inject session identity for afx rename (Spec 468)
                 shellEnv['SHELLPER_SESSION_ID'] = sessionId;
                 shellEnv['TOWER_PORT'] = String(ctx.port);
@@ -2612,7 +2770,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({
@@ -2637,7 +2797,7 @@ async function handleWorkspaceShellCreate(res, ctx, workspacePath) {
                 args: shellArgs,
                 cwd: workspacePath,
                 label: `Shell ${shellId.replace('shell-', '')}`,
-                env: process.env,
+                env: sanitizeAgentEnv(process.env),
             });
             const entry = getWorkspaceTerminalsEntry(workspacePath);
             entry.shells.set(shellId, session.id);