@rubytech/create-maxy-code 0.1.542 → 0.1.544

package/payload/platform/services/claude-session-manager/dist/http-server.js

@@ -27,7 +27,7 @@ import { parseWaChannelBody, sessionIdFieldsFor } from './public-spawn-session.j
 import { buildWebchatChannelMcpServers, buildWebchatChannelArgv, webchatChannelMcpConfigPath, WEBCHAT_CHANNEL_SERVER_NAME } from './webchat-channel-mcp.js';
 import { buildTelegramChannelMcpServers, buildTelegramChannelArgv, telegramChannelMcpConfigPath, TELEGRAM_CHANNEL_SERVER_NAME } from './telegram-channel-mcp.js';
 import { buildChannelMcpServers, buildChannelArgv, channelMcpConfigPath, CHANNEL_SERVER_NAME } from './channel-mcp.js';
-import { buildRcPublicLockdownArgv, formatToolAllowlistLine } from './rc-public-lockdown.js';
+import { buildRcPublicLockdownArgv, formatToolAllowlistLine, PUBLIC_ALLOWED_TOOLS_ENV, allowedToolsFromArgv, formatRoleResolutionLine, } from './rc-public-lockdown.js';
 import { mergeTarget, isMultiTarget, targetKinds } from './channel-targets.js';
 import { randomUUID, createHash } from 'node:crypto';
 import { execFile, execFileSync } from 'node:child_process';
@@ -59,7 +59,40 @@ import { claudeStateRoot, projectSlugForCwd, jsonlPathForSessionId, sidecarPathF
 import { basename, dirname, join } from 'node:path';
 import { validateUserTitle } from './user-title-store.js';
 import { credentialsPathForConfigDir, snapshotAuthForFailureReason } from './auth-snapshot.js';
+// Task 2325 — the wire subset of AgentRole. `passive` is a persona role
+// resolved at the /public-spawn boundary from role:'public' plus the passive
+// flag; it is deliberately absent here so no client can POST it directly.
 const ROLES = ['admin', 'public'];
+/** Task 2325 — the rc-spawn role, as supplied by the request body. Task 1468
+ *  widened this position to allow `undefined` because rc-spawn's role was
+ *  absent for a non-admin/non-public request; null now means "the body named
+ *  none", and the handler resolves it against the prior sidecar before
+ *  deciding whether that is an error. `passive` is not accepted here:
+ *  rc-spawn composes no persona at all (its --append-system-prompt segments
+ *  are reseat / voice / specialist-domains / authenticated-identity
+ *  fragments, never composeAppendSystemPrompt). */
+export function parseRcSpawnRole(body) {
+    return body.role === 'admin' || body.role === 'public' ? body.role : null;
+}
+/** Task 2325 — the single place a /public-spawn wire role becomes a typed one.
+ *  Returns the wire role (always 'admin' or 'public', narrowed by the ROLES
+ *  allowlist above) and the persona role the spawn composes from. They differ
+ *  only for a passive spawn. Anything the allowlist does not name returns null
+ *  and the caller refuses; nothing falls through to 'admin'.
+ *
+ *  The passive condition reproduces the Task 1483 invariant exactly, moved
+ *  here from pty-spawner: a passive spawn rides `role:'public'` on the wire
+ *  and is never a specialist, so a passive flag on any other role or on a
+ *  specialist is ignored rather than silently registering a different (e.g.
+ *  full-admin) server surface while the allowlist locks to work-create. */
+export function parseSpawnRole(body, specialist) {
+    const raw = body.role;
+    if (typeof raw !== 'string' || !ROLES.includes(raw))
+        return null;
+    const role = raw;
+    const agentRole = body.passive === true && role === 'public' && specialist === undefined ? 'passive' : role;
+    return { role, agentRole };
+}
 const CHANNELS = ['browser', 'whatsapp', 'telegram', 'webchat', 'email'];
 // Task 382 — body.conversationNodeId shape gate. The value is the
 // sessionId UUID (v4) minted by createNewAdminConversation in
@@ -1037,12 +1070,21 @@ export function buildHttpApp(deps) {
         const userId = typeof body.userId === 'string' && body.userId.length > 0 && body.userId.length <= 128
             ? body.userId
             : undefined;
-        const role = typeof body.role === 'string' ? body.role : '';
         const channel = typeof body.channel === 'string' ? body.channel : '';
         const hidden = body.hidden === true;
         const specialist = typeof body.specialist === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(body.specialist)
             ? body.specialist
             : undefined;
+        // Task 2325 — one parse, before any other use of the role. `role` is what
+        // arrived on the wire; `agentRole` is which persona it resolves to. They
+        // differ only for a passive spawn. `role` keeps its string-or-empty shape
+        // so every existing read of it, including the spawn-request log line's
+        // `role=${role || 'missing'}`, is unchanged.
+        const parsedRole = parseSpawnRole(body, specialist);
+        const role = parsedRole?.role ?? '';
+        const agentRole = parsedRole?.agentRole ?? null;
+        // Task 2325 — recorded before the guard so a refused spawn is counted.
+        deps.roleCensus?.record(agentRole);
         // Task 956 — public sessions are pinned to Sonnet 5 (operator decision:
         // admin-only Bypass/Opus; public stays Sonnet + fail-closed dontAsk). The
         // role==='public' force is the chokepoint covering every public spawn
@@ -1128,6 +1170,13 @@ export function buildHttpApp(deps) {
         // webchatChannel above. This door could attach webchat but never WhatsApp,
         // which is why the public WhatsApp route had nowhere to land before.
         const waChannel = parseWaChannelBody(body.waChannel);
+        // Task 2338 — the telegram twin. `parseWaChannelBody` is shape-identical
+        // for telegram (senderId + http gateway + absolute server path), so it is
+        // reused rather than duplicated. pty-spawner has accepted a
+        // `telegramChannel` arg since the public allowlist gained its telegram arm
+        // (pty-spawner.ts:844, public-allowlist.ts:24); this route could not supply
+        // one, so a public telegram spawn fell through to the deny-basis allowlist.
+        const telegramChannel = parseWaChannelBody(body.telegramChannel);
         // Task 2262 — the caller's deterministic per-sender id, so a public visitor
         // keeps one conversation across cold starts instead of meeting a fresh agent
         // every time. Shape-gated to the same UUID v4 pattern the other id fields on
@@ -1152,10 +1201,42 @@ export function buildHttpApp(deps) {
             : body.dormantPlugins == null ? 'absent' : typeof body.dormantPlugins;
         const initialMessageBytes = typeof body.initialMessage === 'string' ? Buffer.byteLength(body.initialMessage, 'utf8') : 0;
         deps.logger(`spawn-request senderId=${senderId || 'missing'} userId=${userId ? userId.slice(0, 8) : 'absent'} role=${role || 'missing'} channel=${channel || 'missing'} permissionMode=${typeof body.permissionMode === 'string' ? body.permissionMode : 'default'} channels=${Array.isArray(body.channels) ? body.channels.length : 0} attachmentDir=${typeof body.attachmentDir === 'string' ? 'set' : 'absent'} aboutOwner=${aboutOwnerShape} dormantPlugins=${dormantPluginsShape} tunnelUrl=${typeof body.tunnelUrl === 'string' ? 'set' : (body.tunnelUrl === null ? 'null' : 'absent')} initialMessageBytes=${initialMessageBytes}`);
-        if (!senderId || !ROLES.includes(role) || !CHANNELS.includes(channel)) {
+        if (!senderId || parsedRole === null || agentRole === null || !CHANNELS.includes(channel)) {
+            // Task 2325 — emitted only when the ROLE is what failed. The guard also
+            // covers a missing senderId and a bad channel, and naming those
+            // `role-unresolved` would make the line lie about its own cause, which
+            // is the exact defect class this task exists to remove. The 400 body
+            // below still reports all three fields.
+            if (parsedRole === null) {
+                deps.logger(`[spawn] op=role-unresolved sessionId=new role=${typeof body.role === 'string' ? body.role : String(body.role)} site=public-spawn`);
+            }
             timed(deps.logger, 'POST', '/public-spawn', 400, Date.now() - start);
             return c.json({ error: 'invalid-arguments', detail: { senderId: !!senderId, role, channel } }, 400);
         }
+        // Task 2274 — a public spawn may not name a specialist. `isPublic` and
+        // `isSpecialistSpawn` are independent in pty-spawner and the specialist
+        // branch wins at two of the four lockdown levers: the `--allowed-tools` push
+        // is skipped entirely, and `effectiveMode` resolves the caller-supplied mode
+        // (defaulting to `bypassPermissions`) instead of the fail-closed `dontAsk`.
+        // The `permissionMode` this body may also carry is parsed further down and
+        // would be honoured on that branch, which is why the refusal sits above the
+        // parse rather than beside it.
+        //
+        // Neither production issuer sends the combination: the channel bridge
+        // (`manager-client.ts`) is the only one whose role can be 'public' and it
+        // carries no `specialist` field, while the cookie-auth wrapper
+        // (`claude-sessions.ts`) types its role as the literal 'admin'. Refusing
+        // states that invariant at the door; `spawnClaudeSession` refuses the same
+        // pairing again at the chokepoint, so a future route cannot reinherit it.
+        //
+        // `specialist` here is the shape-gated value, so a body whose field failed
+        // the slug pattern resolved to undefined and is an ordinary public spawn —
+        // the same value the spawner would have seen.
+        if (role === 'public' && specialist !== undefined) {
+            deps.logger(`[spawn] op=public-specialist-refused site=public-spawn specialist=${specialist} channel=${channel} senderId=${senderId}`);
+            timed(deps.logger, 'POST', '/public-spawn', 400, Date.now() - start);
+            return c.json({ error: 'specialist-not-permitted-on-public', detail: { specialist } }, 400);
+        }
         // Task 1489 — a passive intake spawn rides role:'public' on this path but is
         // a trusted, sub-account-bound account manager, not an anonymous visitor. It
         // is exempt from the anonymous-visitor limiter: `!passive` keeps a manager's
@@ -1266,6 +1347,22 @@ export function buildHttpApp(deps) {
                 deps.logger(`[spawn] op=agent-account-scope route=public-spawn account=${agentAccountId} applied=true`);
             }
         }
+        // Task 2338 — the write-through /rc-spawn has always made (:3336, :3346,
+        // :3355) and this route never did. Without it a session first spawned here
+        // has no binding on disk, so the stuck-turn recycler has nothing to re-post
+        // and the respawn loses the visitor's reply transport. A public spawn is
+        // wa XOR webchat XOR telegram (pty-spawner.ts:1893), so at most one of
+        // these fires. Gated on a caller-supplied sessionId because that is the
+        // only id that exists before the spawn returns; a route that mints its own
+        // id has no session to key on and no recycler re-post to serve.
+        if (callerSessionId) {
+            if (waChannel)
+                deps.waChannelStore.set(callerSessionId, waChannel);
+            if (webchatChannel)
+                deps.webchatChannelStore?.set(callerSessionId, webchatChannel);
+            if (telegramChannel)
+                deps.telegramChannelStore?.set(callerSessionId, telegramChannel);
+        }
         const result = await spawnClaudeSession({
             ...deps,
             spawnCwd,
@@ -1282,7 +1379,7 @@ export function buildHttpApp(deps) {
                 if (!passive) {
                     // Task 2271 — `spawnCwd` here is the re-scoped value, so the audit
                     // follows a public-agent session into its own account's slug.
-                    attachPublicAudit(deps, tracker.sessionId, role, spawnCwd);
+                    attachPublicAudit(deps, tracker.sessionId, parsedRole.role, spawnCwd);
                     // Task 2262 — the exit notify is webchat machinery: the route it
                     // calls resolves the sessionId against the WEBCHAT gateway's
                     // publicSessions map to fire a slice-review, so a WhatsApp public
@@ -1292,7 +1389,7 @@ export function buildHttpApp(deps) {
                     // because a WhatsApp visitor's realised tool surface is exactly what
                     // Task 2260 wants audited.
                     if (channel !== 'whatsapp') {
-                        attachPublicExitNotify(tracker.sessionId, role, deps.logger);
+                        attachPublicExitNotify(tracker.sessionId, parsedRole.role, deps.logger);
                     }
                 }
                 attachSpecialistEndTurnAutoArchive(deps, tracker.sessionId, tracker.specialist);
@@ -1304,7 +1401,10 @@ export function buildHttpApp(deps) {
         }, {
             senderId,
             userId,
-            role: role,
+            // Task 2325 — the PERSONA role the spawn composes from, resolved by
+            // the boundary parse above. No cast: `agentRole` is non-null past the
+            // guard. The wire role stays on the sidecar (pty-spawner maps it back).
+            role: agentRole,
             channel: channel,
             channels,
             permissionMode,
@@ -1324,9 +1424,9 @@ export function buildHttpApp(deps) {
             visitorId,
             webchatChannel,
             waChannel,
+            telegramChannel,
             ...sessionIdFields,
             previousContext,
-            passive,
             targetAccountId,
             // Task 2271 — the RESOLVED variable, not the parsed field: when the
             // same-slug rule declines the re-scope, the sidecar stays at the house
@@ -2692,7 +2792,11 @@ export function buildHttpApp(deps) {
         // session-end review) supply no channel and get no sidecar. Task 852 widens
         // the accepted role to 'public' (authenticated-public WhatsApp person) and
         // the sidecar records the actual role.
-        const rcRole = body.role === 'admin' || body.role === 'public' ? body.role : undefined;
+        // Task 2325 — the BODY's role. Null when absent or unrecognised. A
+        // channel-bound resume legitimately omits it and inherits from its prior
+        // sidecar, so the refusal is not here; it is where both sources have been
+        // consulted, just below `priorSidecar`.
+        const rcRole = parseRcSpawnRole(body);
         const adminChannel = typeof body.channel === 'string' && CHANNELS.includes(body.channel)
             ? body.channel
             : undefined;
@@ -3035,11 +3139,67 @@ export function buildHttpApp(deps) {
         // yields null; the gate degrades to the not-resolvable identity form.
         // Task 1214 — widened from webchat-only to any channel-bound session so the
         // admin-role signal resolves for WhatsApp/Telegram resumes that omit role
-        // too (the voice-contract gate below keys on `adminBinding`). Every
-        // channel-less resume still skips the disk touch.
-        const priorSidecar = sessionId && (effectiveWebchatChannel || effectiveWaChannel || effectiveTelegramChannel)
-            ? readSidecar(sidecarPathForSessionId(effectiveAccountDir, sessionId), deps.logger).sidecar
+        // too (the voice-contract gate below keys on `adminBinding`).
+        // Task 2325 — widened again to EVERY resume, channel-bound or not, so the
+        // role can be inherited from disk before the refusal below. The dropped
+        // "channel-less resumes skip the disk touch" optimisation cost one small
+        // readFileSync on a path that then spawns a PTY. Without it, the bare
+        // `{ sessionId }` resumes that wedged-session recovery (index.ts, the
+        // recoverWedgedSession resumeSpawn) and the re-seat route send would be
+        // refused for carrying no role, when their role has been on disk all along.
+        // Task 2267 — the whole read outcome, not just the sidecar. `readSidecar`
+        // returns `ok` | `missing` | `parse-failed` and both failure verdicts yield
+        // a null sidecar, so collapsing to `.sidecar` here made a damaged file
+        // indistinguishable from a session that legitimately has none. The lockdown
+        // gate below and the resolution line both read the verdict.
+        const priorSidecarRead = sessionId
+            ? readSidecar(sidecarPathForSessionId(effectiveAccountDir, sessionId), deps.logger)
             : null;
+        const priorSidecar = priorSidecarRead?.sidecar ?? null;
+        // Task 2325 — the session's role, from the body or inherited from disk.
+        // The refusal sits here rather than at the body parse because an absent
+        // `role` has THREE legitimate readings and only one of them is an error:
+        //   1. a channel-bound resume, which inherits from `priorSidecar` (Task
+        //      2260's own words: "a resume omits `role` in the body");
+        //   2. a one-shot admin job, which is not a channel conversation — those
+        //      now pass role:'admin' and are told apart by their absent `channel`,
+        //      which is what the classification-sidecar gate below reads;
+        //   3. a caller that simply supplied none on a FRESH spawn, which is the
+        //      error. Before this it became `undefined` and rode on, and
+        //      `sessionRole=undefined` was documented (Task 1468) as a value to
+        //      preserve rather than treated as a fault.
+        //
+        // The `mode === 'fresh'` half of the gate is load-bearing, not caution. A
+        // resume that inherits nothing is the claude.ai/code bridge: the bare
+        // admin-host branch of session-rc-spawn.ts posts `{ sessionId, name }`
+        // with no role and no channel, and wedged-session recovery posts
+        // `{ sessionId }`. Both resume a session whose role predates the request.
+        // Refusing them would take out a core operator surface to close a hole
+        // that only a fresh spawn can open: a resume composes no new persona,
+        // and rc-spawn composes none at all.
+        const effectiveRcRole = rcRole ?? priorSidecar?.role ?? null;
+        // Task 2325 — recorded before the refusal so a refused spawn is counted.
+        deps.roleCensus?.record(effectiveRcRole);
+        if (effectiveRcRole === null && mode === 'fresh') {
+            deps.logger(`[rc-spawn] op=role-unresolved sessionId=${sessionId ? sessionId.slice(0, 8) : 'new'} role=${String(body.role)} site=rc-spawn`);
+            timed(deps.logger, 'POST', '/rc-spawn', 400, Date.now() - start);
+            return c.json({ error: 'invalid-arguments', detail: { role: body.role ?? null } }, 400);
+        }
+        // Task 2267 — one line per channel-bound rc-spawn naming where the role came
+        // from. Emitted only for a channel-bound spawn: a one-shot admin job has no
+        // channel and no sidecar, so a line on every rc-spawn would be dominated by
+        // that benign case. `source=unresolved` is the fail-closed spawn, and the
+        // outcome behind it separates a deleted sidecar from a corrupted one.
+        // Hoisted from the Task 1214 voice gate below, which reads the same value
+        // and now shares this one binding.
+        const channelBound = !!(effectiveWebchatChannel || effectiveWaChannel || effectiveTelegramChannel);
+        if (sessionId && channelBound) {
+            deps.logger(formatRoleResolutionLine({
+                sessionId,
+                source: rcRole ? 'body' : priorSidecar?.role ? 'sidecar' : 'unresolved',
+                outcome: priorSidecarRead?.outcome ?? 'missing',
+            }));
+        }
         // Task 850 — assemble the bound target set and choose the channel server:
         //   - ≥2 kinds: ONE unified `channel` server (one reply tool fanning to every
         //     target's existing gateway endpoint). The mature per-kind servers are
@@ -3136,7 +3296,9 @@ export function buildHttpApp(deps) {
                     gatewayUrl: effectiveTelegramChannel.gatewayUrl,
                     serverPath: effectiveTelegramChannel.serverPath,
                     nodeBin: deps.nodeBin,
-                    role: rcRole,
+                    // Task 2325 — the body role, unchanged in meaning; `?? undefined`
+                    // only bridges null to the optional parameter this builder declares.
+                    role: rcRole ?? undefined,
                 });
                 telegramPath = telegramChannelMcpConfigPath(sessionId, tmpdir());
                 try {
@@ -3158,9 +3320,28 @@ export function buildHttpApp(deps) {
         // the first. `priorSidecar` is already read for any channel-bound session,
         // which is every public spawn that can reply. Pushed after the channel argv
         // so `--strict-mcp-config` leaves exactly the per-spawn channel server
-        // registered; `admin` and roleless spawns produce byte-identical argv.
-        const effectiveRcRole = rcRole ?? priorSidecar?.role;
-        const publicLockdown = effectiveRcRole === 'public' ? buildRcPublicLockdownArgv(channelServerName) : null;
+        // registered; an `admin` spawn produces byte-identical argv.
+        // Task 2325 — resolved once, above, beside the refusal.
+        //
+        // Task 2267 — a null role on a channel-bound spawn takes the lockdown too.
+        // `effectiveRcRole` is null when neither the body nor the sidecar produced a
+        // role, and a live public session always had a sidecar written at spawn
+        // (pty-spawner kills the PTY when that write throws), so null on a
+        // channel-bound session means the file was damaged after the spawn
+        // succeeded, not that the session is legitimately roleless. Reaching here
+        // with null is always a resume: a fresh spawn with no resolvable role is
+        // refused with a 400 above, so no mode test is added. A roleless spawn with
+        // NO channel binding — the one-shot admin jobs and the bare claude.ai/code
+        // bridge resume — still produces byte-identical argv.
+        //
+        // The cost is stated rather than hidden. A channel-bound ADMIN resume whose
+        // sidecar is unreadable comes back holding only its channel reply tool, and
+        // stays that way on every later resume, because the sidecar write below is
+        // itself gated on a non-null role and so never repairs the file. The
+        // `op=role-resolution` line above is what makes that state greppable.
+        const publicLockdown = effectiveRcRole === 'public' || (effectiveRcRole === null && channelBound)
+            ? buildRcPublicLockdownArgv(channelServerName)
+            : null;
         if (publicLockdown) {
             // A re-seat fork pushes its own caller-picked --permission-mode above,
             // before the role is known. Two conflicting flags do not reliably
@@ -3202,7 +3383,9 @@ export function buildHttpApp(deps) {
         // overlay: a missing/empty/headingless file degrades to no voice segment and
         // never fails the spawn. `voiceBytes` rides the op=argv line as the
         // at-a-glance present/absent signal whose absence hid this bug.
-        const channelBound = !!(effectiveWebchatChannel || effectiveWaChannel || effectiveTelegramChannel);
+        // Task 2267 — `channelBound` was declared here; it is now resolved once,
+        // beside the role resolution above, because the public lockdown gate needs
+        // the same value earlier. Same expression, same meaning.
         let voiceBytes = 0;
         if (adminBinding && channelBound) {
             let voice = null;
@@ -3279,7 +3462,25 @@ export function buildHttpApp(deps) {
         // (effectiveAccountId !== house) spawns — fail-closed, no escalation.
         const acctIsHouse = isHouseAccount(deps.platformRoot, effectiveAccountId);
         const rcHouseAdminScope = houseAdminScopeFor({
-            role: rcRole,
+            // Task 2335 — the SESSION's role (body, else prior sidecar), not the
+            // body's `rcRole` alone. A resume that omits the role — the stuck-turn
+            // recycler posts `{ sessionId, targetAccountId }` — used to fail the
+            // `role === 'admin'` test and come back with no cross-account authority
+            // while the same session's fresh spawn carried it. That divergence was
+            // measured on one house session as a single `inject=false` line between
+            // four `inject=true` lines, on the recycle resume 21s after a wedge kill.
+            // Inheriting is not a widening, for two reasons that hold together. The
+            // sidecar is read from `sidecarPathForSessionId(effectiveAccountDir, …)`
+            // above — the SAME account that decides `isHouse` — so an inherited role
+            // can only come from the resolved account's own record of this session;
+            // a sub-account session resumed against the house account finds no
+            // sidecar there and resolves null. And that record is read back through
+            // the `['admin','public']` allowlist in `parseSidecar`, which rejects the
+            // whole row on anything else, so the only role that can arrive here from
+            // disk and open the gate is the `admin` this session's own fresh spawn
+            // asserted on this account. `isHouse` still excludes every sub-account
+            // resume on top of that.
+            role: effectiveRcRole,
             accountId: effectiveAccountId,
             isHouse: acctIsHouse,
             isSpecialist: false,
@@ -3290,7 +3491,12 @@ export function buildHttpApp(deps) {
         // line makes the rc-spawn decision greppable per spawn.
         deps.logger(formatHouseScopeInjectLine({
             sessionId,
-            sessionRole: rcRole,
+            // Task 2325 — the session's role, so this line can no longer render
+            // `sessionRole=undefined`. A resume that inherits no role renders the
+            // explicit token `none`, matching the idiom this handler already uses
+            // for the same value below. A stringified absence read as a formatting
+            // artefact, which is how an unnamed role stayed invisible for two tasks.
+            sessionRole: effectiveRcRole ?? 'none',
             acctIsHouse,
             inject: rcHouseAdminScope !== null,
         }));
@@ -3424,6 +3630,15 @@ export function buildHttpApp(deps) {
             strictMcp: publicLockdown !== null,
             mode: effectiveRcPermissionMode,
         }));
+        // Task 2339 — the realised-surface hook's only input. `tool-allowlist` above
+        // records the surface this spawn was GIVEN; nothing recorded the surface it
+        // REALISES, so five tools ran under a one-tool allowlist and produced no
+        // line. Stamped here rather than inside buildRcChildEnv so it lands after
+        // the last argv push and the value is this spawn's final `--allowed-tools`
+        // set. Public spawns only; its presence is the signal the hook keys on.
+        if (publicLockdown) {
+            env[PUBLIC_ALLOWED_TOOLS_ENV] = allowedToolsFromArgv(argv).join(',');
+        }
         deps.logger(`[rc-spawn] op=argv unitToken=${unitToken} cwd=${effectiveAccountDir} permissionMode=${effectiveRcPermissionMode} model=${effectiveRcModel ?? 'unset'} effort=${effectiveRcEffort ?? 'unset'} positionalBytes=${positionalBytes} voiceBytes=${voiceBytes} argv=${JSON.stringify([deps.claudeBin, ...argv])}`);
         emitRcLife(deps.logger, 'argv', 'rc-spawn', 'node-pty', rcLifeMode, unitToken, {
             cwd: effectiveAccountDir,
@@ -3509,18 +3724,31 @@ export function buildHttpApp(deps) {
         // when one exists. Non-fatal: the PTY here is already serving a live thread —
         // a failed classification sidecar must not tear it down, so it logs and the
         // session keeps running (the pre-fix reader-blind behaviour, no worse).
-        const classifyChannel = rcRole !== undefined ? adminChannel : undefined;
+        // Task 2325 — the sidecar is written for a channel conversation. What
+        // distinguishes one from a one-shot admin job is the CHANNEL, not whether
+        // a role was supplied: the LinkedIn ingest and the public session-end
+        // review are role:'admin' and pass no channel, and they still get no
+        // sidecar. Before this the absent role carried both meanings at once.
+        const classifyChannel = adminChannel;
         const classifySenderId = adminSenderId ?? effectiveWaChannel?.senderId ?? effectiveWebchatChannel?.key ?? effectiveTelegramChannel?.senderId;
-        if (sessionId && classifyChannel && classifySenderId) {
+        // Task 2325 — `effectiveRcRole !== null` joins the guard rather than being
+        // cast away. The sidecar's `role` is read back through an allowlist that
+        // rejects the whole row on a bad value, so a session with no resolvable
+        // role gets NO sidecar rather than one recording an absence.
+        if (sessionId && classifyChannel && classifySenderId && effectiveRcRole !== null) {
             const classifySidecarPath = sidecarPathForSessionId(effectiveAccountDir, sessionId);
             if (!existsSync(classifySidecarPath)) {
                 try {
                     writeSidecar(classifySidecarPath, {
                         senderId: classifySenderId,
-                        // Task 852 — the actual role from the body ('admin' | 'public'),
-                        // not a hardcoded 'admin'; rcRole is defined whenever
-                        // classifyChannel is.
-                        role: rcRole,
+                        // Task 852 — the actual role, not a hardcoded 'admin'. Task 2325
+                        // — the effective role (body, else inherited from disk),
+                        // non-null by the guard above. The old
+                        // `rcRole as 'admin' | 'public'` relied on this gate being
+                        // role-derived; the gate now reads the channel, so without the
+                        // guard a resume with a channel and no body role would have
+                        // written a cast `undefined` into the sidecar.
+                        role: effectiveRcRole,
                         channel: classifyChannel,
                         url: null,
                         startedAt: new Date().toISOString(),
@@ -3562,6 +3790,11 @@ export function buildHttpApp(deps) {
                         // into the child env above (rcHouseAdminScope), so env and sidecar
                         // are one decision with two consumers and can never drift again.
                         houseAdminScope: rcHouseAdminScope,
+                        // Task 2338 — the route that produced this process. Only
+                        // /public-spawn composes a persona, so a `public` role recorded
+                        // here with route `rc-spawn` is a session running without its
+                        // soul file, which is what the persona audit counts.
+                        spawnRoute: 'rc-spawn',
                     }, deps.logger);
                     deps.watcher.refreshSidecar?.(sessionId);
                 }
@@ -3578,6 +3811,34 @@ export function buildHttpApp(deps) {
                     deps.watcher.refreshSidecar?.(sessionId);
             }
         }
+        // Task 2338 — the route stamp sits OUTSIDE the classification block above,
+        // and that placement is the whole point. That block is gated on a channel
+        // in the request BODY (`adminChannel`, :3037), and the resume shapes that
+        // matter here carry none: the claude.ai/code bridge posts
+        // `{ sessionId, name }` and wedged-session recovery posts `{ sessionId }`
+        // (see the note at :3390). Inside the block, a bare resume of a public
+        // session would leave `spawnRoute` reading `public-spawn` and the persona
+        // audit would report zero through a live defect — which is exactly the
+        // 2026-08-01 sequence this task exists to make visible.
+        //
+        // Patched, never written fresh: with no prior sidecar there is no row to
+        // record a route on, and inventing one here would bypass the role/channel
+        // allowlist the write above enforces. Patched only when the value would
+        // change, so a repeated rc-spawn resume does not rewrite the file each turn.
+        if (sessionId && priorSidecar && priorSidecar.spawnRoute !== 'rc-spawn') {
+            const routeSidecarPath = sidecarPathForSessionId(effectiveAccountDir, sessionId);
+            try {
+                const patched = updateSidecar(routeSidecarPath, { spawnRoute: 'rc-spawn' }, deps.logger);
+                if (patched)
+                    deps.watcher.refreshSidecar?.(sessionId);
+            }
+            catch (err) {
+                // Non-fatal, same contract as the classification write: the PTY here is
+                // already serving a live thread and a diagnostic write must not tear it
+                // down.
+                deps.logger(`[rc-spawn] op=spawn-route-patch-failed sessionId=${sessionId.slice(0, 8)} err=${JSON.stringify(err instanceof Error ? err.message : String(err))}`);
+            }
+        }
         // Task 626 — one-shot job (LinkedIn ingest, public session-end review):
         // stop the PTY once its single assistant turn lands `end_turn`. closeAfterTurn
         // implies a sessionId (validated above), so trackerKey === sessionId and the