@cluesmith/codev 3.3.0 → 3.3.2

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

@@ -24,7 +24,8 @@ 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';
@@ -33,16 +34,18 @@ import { hasTeam, loadTeamMembers, loadMessages } from '../../lib/team.js';
 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 { formatArchitectMessage, formatBuilderMessage } from '../utils/message-format.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 { 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 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
@@ -51,7 +54,7 @@ import { submitToSession } from './session-submit.js';
 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';
@@ -74,6 +77,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),
@@ -113,27 +117,38 @@ function respondStartingUp(res) {
 // 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)
@@ -155,6 +170,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) {
@@ -890,7 +911,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: [], heldCount: 0, mailboxEscalated: false }));
+        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.
@@ -959,6 +980,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
@@ -1230,13 +1275,24 @@ 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.
+ */
+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(toAgent, message, undefined, raw);
     if (isArchitectTarget && from)
-        return formatBuilderMessage(from, message, undefined, raw); // builder → architect
+        return formatBuilderMessage(from, toAgent, message, undefined, raw); // builder → architect
     if (!isArchitectTarget)
-        return formatArchitectMessage(message, undefined, raw); // any → builder
-    return raw ? message : formatArchitectMessage(message, undefined, false); // unknown → architect
+        return formatArchitectToBuilderMessage(toAgent, message, undefined, raw); // any → builder
+    return raw ? message : formatArchitectMessage(toAgent, message, undefined, false); // unknown → architect
 }
 /**
  * Route a cron notification through the Spec 1313 mailbox + gate — the Tower-wired
@@ -1256,9 +1312,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);
@@ -1266,6 +1325,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,
@@ -1279,6 +1339,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,
@@ -1308,8 +1369,26 @@ function holdAndRespond(res, ctx, input, reason) {
         held: true,
         reason,
         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
@@ -1372,7 +1451,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,
@@ -1414,6 +1493,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`
@@ -1440,6 +1530,7 @@ function handleDelayedSend(res, ctx, db, params) {
         deliverAfter,
         mailboxId: row.id,
         notBefore,
+        bodyLength: Buffer.byteLength(params.message, 'utf8'),
     });
 }
 async function handleSend(req, res, ctx) {
@@ -1457,6 +1548,17 @@ 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;
     const workspace = typeof body.workspace === 'string' ? body.workspace : undefined;
@@ -1523,7 +1625,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,
@@ -1561,7 +1663,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,
@@ -1586,7 +1688,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,
@@ -1602,7 +1704,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' },
@@ -1612,10 +1724,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.
@@ -1653,15 +1771,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',
@@ -1681,6 +1813,9 @@ async function handleSend(req, res, ctx) {
             held: false,
             mailboxId: row.id,
             reason: null,
+            bodyLength,
+            // Additive and present only when it happened, so older clients are unaffected.
+            ...(degraded ? { degraded: true, degradedReason: DEGRADED_SUBMIT_REASON } : {}),
         });
         return;
     }
@@ -1727,6 +1862,7 @@ async function handleSend(req, res, ctx) {
             held: false,
             mailboxId: row.id,
             reason: null,
+            bodyLength,
         });
         return;
     }
@@ -1745,6 +1881,7 @@ async function handleSend(req, res, ctx) {
         held: true,
         reason,
         mailboxId: row.id,
+        bodyLength,
     });
 }
 /**
@@ -1965,14 +2102,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
 // ============================================================================
@@ -2035,22 +2226,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;
         }
     }
@@ -2979,16 +3172,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));
@@ -3007,18 +3208,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' });