@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/services/claude-session-manager/dist/pty-spawner.js

@@ -0,0 +1,2077 @@
+// Spawn a `claude --verbose` PTY child and resolve once the fs-watcher
+// reports the PID file Claude Code writes at process init
+// (`${CLAUDE_CONFIG_DIR}/sessions/<pid>.json` for entrypoint=cli). That
+// file carries the intrinsic sessionId, bridgeSessionId, agent, status
+// and cwd directly — earlier and more authoritatively than the
+// `/remote-control` URL banner. URL capture still runs in parallel so
+// the operator-facing iframe URL is populated, but it no longer gates
+// /spawn's response.
+//
+// The manager mints zero session ids. Both the intrinsic id and the
+// bridgeSessionId come from Claude Code's own state files.
+//
+// Task 147 — the recorder (database-operator) spawn is structurally
+// identical to a Sidebar "New session" spawn. Same /spawn body shape;
+// the recorder only differs by three overrides on the body
+// (`specialist`, `model`, `initialMessage`). No recorder-specific
+// preflight, no recorder-specific tool-surface gate, no
+// `originatingSessionId` discriminator, no `MAXY_IS_RECORDER` env stamp.
+// The PTY's own first-use error is the contract for tool absence.
+// Auto-archive on end_turn for the database-operator specialist is
+// applied in `http-server.ts` based on the resolved `specialist` value.
+//
+// Spawn failure surfaces (return 500 with `stderrTail`):
+//   which-claude-not-found, pty-spawn-failed, pid-file-timeout,
+//   host-context-unresolved, identity-unresolved, mcp-config-write-failed.
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { defaultSystemctlRunner, scopeUnitName, stopScopeUnit, } from './systemd-scope.js';
+import { startUrlCapture } from './url-capture.js';
+import { jsonlPathForSessionId, sidecarPathForSessionId, permissionModeLogPathForSessionId, projectsDirForCwd, } from './jsonl-path.js';
+import { readSidecar, writeSidecar, updateSidecar } from './session-sidecar.js';
+import { probeMcpServerTools, } from './mcp-tools-probe.js';
+// CSI (Cursor / Style) escape sequence: ESC `[` <args> <final-letter>.
+const PTY_TAIL_CSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+const PTY_TAIL_BYTES = 4 * 1024;
+const PTY_TAIL_LOG_BYTES = 1024;
+function attachPtyTail(pty) {
+    let buf = '';
+    let sub = pty.onData((data) => {
+        buf += data.replace(PTY_TAIL_CSI, '');
+        if (buf.length > PTY_TAIL_BYTES)
+            buf = buf.slice(buf.length - PTY_TAIL_BYTES);
+    });
+    return {
+        getTail: () => buf,
+        dispose: () => {
+            if (sub) {
+                sub.dispose();
+                sub = null;
+            }
+        },
+    };
+}
+function formatTailForLog(tail) {
+    const trimmed = tail.length > PTY_TAIL_LOG_BYTES ? tail.slice(-PTY_TAIL_LOG_BYTES) : tail;
+    return JSON.stringify(trimmed);
+}
+import { composeAppendSystemPrompt, } from './system-prompt.js';
+import { discoverHooks } from './hooks-discovery.js';
+import { CC_NATIVE_TOOLS } from './specialist-drift.js';
+// Task 609 — deny-basis sentinel for dontAsk public spawns whose resolved
+// allowlist is empty. Follows the mcp__<server>__<tool> allowlist grammar;
+// server `none` is never registered in any brand's .mcp.json, so the token
+// matches no real tool and grants nothing. It is absent from CC_NATIVE_TOOLS,
+// so an allowlist anchored on it stays native-excluding. Its only job is to
+// make `--allowed-tools` present and non-empty so dontAsk fails closed.
+const DONTASK_DENY_BASIS = 'mcp__none__deny-basis';
+// Task 612 / 615 — every public spawn gets ZERO tool surface (webchat,
+// whatsapp, telegram). Measured on realagent-code (claude 2.1.160, brand
+// settings.json permissions.allow:["*"]): a per-spawn permissions.deny in the
+// same --settings as the prompt-skip keys is the ONLY lever that beats the
+// brand allow:["*"] — a global deny:["*"] is a no-op (the `*`-vs-`*` collision
+// resolves to allow). Bare tool names gate command tools (Bash/Skill/Task) but
+// are no-ops for file/path tools, which need a Tool(//**) path form;
+// deny:["Read(//**)"] is absolute over any allow, so no attachment Read
+// carve-out survives (the carve-out is dropped — see Task 613). A server-scoped
+// mcp__<srv>__* wildcard gates the one MCP surface a public spawn could
+// otherwise expose (the memory plugin, short prefix mcp__memory__). The deny
+// list is enumerative and maintained in lockstep with CC_NATIVE_TOOLS (the
+// pty-spawner-public-deny audit test reconciles them).
+/** File tools that need a `Tool(//**)` path form alongside their bare name —
+ *  a bare deny of these is a no-op against a path-argument call. */
+const CC_FILE_PATH_TOOLS = [
+    'Read', 'Write', 'Edit', 'MultiEdit', 'Glob', 'Grep', 'LS', 'NotebookRead', 'NotebookEdit',
+];
+/** Harness/agent-framework tools that exist in a live public spawn but are NOT
+ *  in CC_NATIVE_TOOLS, so they are listed here and denied by bare name. Two
+ *  sources: the deferred-load set (`deferred_tools_delta.addedNames` — the
+ *  Cron, Enter/Exit, and Task families, Monitor, PushNotification,
+ *  RemoteTrigger, plus `ToolSearch`) and the EAGER agent-framework tools
+ *  `ScheduleWakeup` +
+ *  `Workflow`, which the Task 612 on-device acceptance probe found still
+ *  reachable after the deferred set was denied — `Workflow` spawns subagents,
+ *  so leaving it open is a privilege-escalation hole, not merely extra surface.
+ *  `LSP` (language-server code intelligence) was added by Task 614: a real
+ *  `claude` capture exposes it, and the deny-list reconciliation test
+ *  (public-deny-reconciliation.test.ts) flagged it as reachable-but-undenied.
+ *
+ *  Maintainer note: this list and CC_FILE_PATH_TOOLS are name-only. The
+ *  reconciliation test catches a NEW tool's bare-name omission, but a flat
+ *  registry cannot reveal which tools take a path argument — so classifying a
+ *  brand-new tool as a file tool that also needs a `(//**)` path form in
+ *  CC_FILE_PATH_TOOLS remains a maintainer responsibility (Task 614). */
+const CC_HARNESS_TOOLS = [
+    'ToolSearch', 'Monitor', 'PushNotification', 'RemoteTrigger',
+    'ScheduleWakeup', 'Workflow', 'LSP',
+    'EnterPlanMode', 'ExitPlanMode', 'EnterWorktree', 'ExitWorktree',
+    'CronCreate', 'CronDelete', 'CronList',
+    'TaskCreate', 'TaskGet', 'TaskList', 'TaskOutput', 'TaskStop', 'TaskUpdate',
+];
+/** Server-scoped MCP wildcard(s) for the public surface. The only MCP server a
+ *  public spawn could register is the memory plugin (short prefix). */
+const PUBLIC_DENY_MCP = ['mcp__memory__*'];
+/** The per-spawn `permissions.deny` set for a public session (any channel):
+ *  every CC native tool by bare name, a `(//**)` path form for every file tool,
+ *  every harness tool by bare name, and the memory MCP server wildcard. Sorted
+ *  and deduped so the emitted argv is stable and the audit test can compare. */
+export function buildPublicDeny() {
+    const entries = [
+        ...CC_NATIVE_TOOLS,
+        ...CC_HARNESS_TOOLS,
+        ...CC_FILE_PATH_TOOLS.map((t) => `${t}(//**)`),
+        ...PUBLIC_DENY_MCP,
+    ];
+    return [...new Set(entries)].sort();
+}
+// Task 455 — two-layer alive invariant for the `livePtys` map.
+//
+// Layer 1: PURGE-ON-EXIT. Both the natural-exit handler
+// (`handlePtyNaturalExit`) and the operator-request stop (`stopSession`)
+// delete the tracker from `livePtys` once its claude child has gone.
+// The delete is guarded by an identity check so a respawn that has
+// already replaced the entry under the same sessionId is never
+// clobbered.
+//
+// Layer 2: FILTER-ON-LOOKUP. Every reader that asks "is there a live
+// PTY for this sessionId?" — `isLive`, `livePidForSession`, the
+// `stopSession` lookup — goes through `resolveLiveTracker`, which
+// returns the entry only when it is present AND `exited` is false.
+// Layer 2 is the load-bearing layer: it handles the case where a
+// future write path sets `t.exited = true` without deleting (the
+// failure shape this task was filed against). Layer 1 hardens the
+// purge for callers that read `livePtys` directly, but the stop
+// route never does — every stop-relevant read flows through Layer 2.
+//
+// `priorExitedBySessionId` is the per-sessionId count of PTYs that
+// have exited inside this manager-process lifetime. It is bumped
+// by `handlePtyNaturalExit` and read by the /stop route's
+// observability line so the operator can see respawn history
+// when investigating a "stop did nothing" report.
+const livePtys = new Map();
+const priorExitedBySessionId = new Map();
+/** Task 558 — track when each tracker was registered (manager-process
+ *  wall clock, ms). The post-archive sweep uses this as the lower
+ *  bound for `heldSinceArchiveMs`: the master cannot have been held
+ *  longer than the manager has known about its tracker. Module-scoped
+ *  so the existing PtyTracker shape stays unchanged. */
+const trackerRegisteredAt = new Map();
+/** Task 455 — canonical alive resolver. Returns the tracker for
+ *  `sessionId` only when an entry exists AND it has not been marked
+ *  exited. Module-private; the public readers below thread through
+ *  it so the alive contract has exactly one definition site. */
+function resolveLiveTracker(sessionId) {
+    const t = livePtys.get(sessionId);
+    if (!t || t.exited)
+        return null;
+    return t;
+}
+/** Returns true when the manager has a live PtyHandle for `sessionId`.
+ *  False for exited rows (the tracker is removed) and for sessions the
+ *  manager never spawned (e.g. a JSONL-only archived row). */
+export function isLive(sessionId) {
+    return resolveLiveTracker(sessionId) !== null;
+}
+/** Task 271 — read-only PID accessor for the live PTY at `sessionId`.
+ *  Returns the PID when a tracker exists and has not exited, null
+ *  otherwise. Used by the /promote refusal path so the 409 payload can
+ *  identify the live process the operator must end first. Mirrors
+ *  `isLive`'s encapsulation rule: returns a primitive, not the handle. */
+export function livePidForSession(sessionId) {
+    return resolveLiveTracker(sessionId)?.pid ?? null;
+}
+/** Task 455 — count of prior PTYs that exited for this sessionId within
+ *  this manager-process lifetime. Read by the /stop route to surface a
+ *  one-line observability hit when the count is > 0, so operators can
+ *  see respawn history without changing the success-path log shape. */
+export function priorExitedCountForSession(sessionId) {
+    return priorExitedBySessionId.get(sessionId) ?? 0;
+}
+/** Test seam — read-only access to the tracker for a given session.
+ *  Production routes never call this; they use the dedicated mutation
+ *  exports (`writeInputToPty`, `killSession`, `onPtyExit`, etc.) so
+ *  the PtyHandle stays encapsulated inside the module. */
+export function getPtyTrackerForTests(sessionId) {
+    return livePtys.get(sessionId);
+}
+/** Register a callback to fire when the PTY for `sessionId` exits.
+ *  Returns true when the tracker exists (callback was wired); false
+ *  when no live PTY is tracked for that id (the caller's contract
+ *  fires regardless — e.g. `attachPublicAudit` skips on no-tracker).
+ *  Routes call this instead of reaching into the tracker for `.pty`. */
+export function onPtyExit(sessionId, cb) {
+    const t = livePtys.get(sessionId);
+    if (!t)
+        return false;
+    t.pty.onExit(cb);
+    return true;
+}
+/** Iterate every live tracker. Used by index.ts's shutdown loop to
+ *  SIGTERM each PTY synchronously, and by checkSlotsAndMaybeEvict's
+ *  LRU search to walk specialists when the cap is hit. */
+export function forEachLivePty(cb) {
+    for (const t of livePtys.values())
+        cb(t);
+}
+/** Count of live trackers. Surfaced by /healthz so the operator can
+ *  see process-side liveness without scanning the watcher's row index. */
+export function livePtyCount() {
+    return livePtys.size;
+}
+/** Test-only — clear the tracker map between vitest cases. Production
+ *  never invokes this; the only legitimate eviction is PTY exit.
+ *  Task 455 — also clears `priorExitedBySessionId` so tests that
+ *  predate the exit-history counter (and only call this reset) do
+ *  not leak counter state across vitest file boundaries. */
+export function __resetPtyTrackerForTests() {
+    livePtys.clear();
+    priorExitedBySessionId.clear();
+    trackerRegisteredAt.clear();
+}
+/** Test-only — clear the exit-history counter between vitest cases.
+ *  Production never invokes this; the counter resets naturally on
+ *  manager restart. `__resetPtyTrackerForTests` clears this map too;
+ *  this narrower export is retained for tests that want to reset
+ *  only the counter without touching the live tracker map. */
+export function __resetExitHistoryForTests() {
+    priorExitedBySessionId.clear();
+}
+/** Test-only — directly register a tracker without going through
+ *  `spawnClaudeSession`. Used by FD-release / natural-exit tests that
+ *  need to construct a known PtyHandle + tracker pair and exercise
+ *  `killSession` / `handlePtyNaturalExit` against it. */
+export function __registerPtyTrackerForTests(tracker) {
+    livePtys.set(tracker.sessionId, tracker);
+    trackerRegisteredAt.set(tracker.sessionId, Date.now());
+}
+/** Task 171 — specialists whose `--agent <name>` spawn has no human in the
+ *  loop: no operator browser tab, no chat channel, no `claude.ai/code/session_<id>`
+ *  URL to open. For these, `--remote-control` is dead weight (one outbound
+ *  WebSocket to Anthropic per spawn plus a PTY-byte regex that never matches)
+ *  and the URL-capture handler is not attached. Membership is by specialist
+ *  name — the values that `SpawnArgs.specialist` carries — sourced from
+ *  archive Task 085 (specialist plumbing) and this task. New headless
+ *  specialists register their name here; channel-facing specialists
+ *  (content-producer, librarian, personal-assistant, project-manager,
+ *  research-assistant) stay out.
+ */
+export const HEADLESS_ROLES = new Set([
+    'database-operator',
+    'citation-auditor',
+    'typed-edge-classifier',
+    'compiled-truth-rewriter',
+]);
+export const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'auto', 'bypassPermissions', 'dontAsk'];
+/** Task 165 — read the agent's `tools:` frontmatter line from
+ *  `$CLAUDE_CONFIG_DIR/agents/<specialist>.md`. Loud-fails when the file
+ *  is missing or when no `tools:` line exists in the frontmatter, since
+ *  either case means `--agent <name>` would silently fall back to the
+ *  admin surface — the exact defect Task 165 closes. Returns the tool
+ *  names in the order they were declared (the caller sorts before
+ *  emitting argv). */
+export function readSpecialistTools(claudeConfigDir, specialist) {
+    const path = join(claudeConfigDir, 'agents', `${specialist}.md`);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`[pty-spawner] specialist-agent-file-missing path=${path} err=${msg}`);
+    }
+    // Frontmatter delimited by lines that contain only `---`. Read tools:
+    // line within the first delimited block.
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---') {
+        throw new Error(`[pty-spawner] specialist-agent-no-frontmatter path=${path}`);
+    }
+    let toolsLine = null;
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '---')
+            break;
+        const m = line.match(/^tools:\s*(.+)$/);
+        if (m) {
+            toolsLine = m[1];
+            break;
+        }
+    }
+    if (toolsLine === null) {
+        throw new Error(`[pty-spawner] specialist-agent-no-tools-line path=${path}`);
+    }
+    return toolsLine
+        .split(',')
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+export function expandPlaceholders(raw, vars) {
+    return raw.replace(/\$\{([A-Z_][A-Z0-9_]*)\}/g, (m, name) => {
+        return Object.prototype.hasOwnProperty.call(vars, name) ? vars[name] : m;
+    });
+}
+/** Task 215 — pull the `<server>` segment out of a qualified MCP tool name
+ *  the way Claude Code's plugin-tool registry surfaces it. Two shapes
+ *  exist in the wild:
+ *
+ *   - Long prefix:  `mcp__plugin_<plugin>_<server>__<tool>` — emitted by
+ *     Claude Code when an MCP server is registered via plugin manifest
+ *     (post-Task-209 native plugin-system path; what `--agent <name>`
+ *     specialist spawns receive in Registry #1).
+ *   - Short prefix: `mcp__<server>__<tool>` — emitted by Claude Code when
+ *     an MCP server is registered via `--mcp-config <path>` (admin operator
+ *     spawns; what Registry #2 produces directly).
+ *
+ *  Both must resolve to the same `<server>` slug so the probe can match
+ *  the qualified name against `toolSurface.mcpServers` keys, which the
+ *  manager populates from PLUGIN.md basenames in `tool-surface.ts`. The
+ *  pre-Task-215 inline regex `/^mcp__(.+?)__/` extracted `plugin_<plugin>_<server>`
+ *  from the long-prefix shape (lazy match stops at the first `__`),
+ *  which never matched any tool-surface key — the failure mode this
+ *  helper closes.
+ *
+ *  Returns `null` for any name that matches neither shape. The caller
+ *  surfaces those names through the inventory line's `unparseable-tools=`
+ *  field so a malformed agent-frontmatter entry can't masquerade as a
+ *  missing server. */
+export function extractServerNameFromQualifiedTool(qualified) {
+    // Long prefix has the literal `plugin` marker between `mcp__` and the
+    // plugin slug — Claude Code stamps it for every plugin-manifest MCP
+    // server, even when plugin and server slugs are equal (the common
+    // maxy case: plugin=memory, server=memory).
+    const longMatch = qualified.match(/^mcp__plugin_([^_]+)_([^_]+)__/);
+    if (longMatch)
+        return longMatch[2];
+    // Short prefix has no `plugin` marker; the first segment IS the server
+    // slug. Used by admin's `--mcp-config` registrations and by any
+    // historical fixture that predates the plugin-manifest rename.
+    const shortMatch = qualified.match(/^mcp__([^_]+)__/);
+    if (shortMatch)
+        return shortMatch[1];
+    return null;
+}
+/** Task 215 — classify the agent's frontmatter `tools:` list against the
+ *  manager's tool-surface registry. Used by both the per-spawn `.mcp.json`
+ *  writer (admin) and the tool-inventory probe (specialist). Returns the
+ *  set of server names to spawn AND the two diagnostic sets the inventory
+ *  line surfaces when non-empty: tokens that didn't parse at all
+ *  (`unparseableTools`) and parseable tokens whose server isn't in the
+ *  registry (`missingServers`). Both diagnostic sets are empty in the
+ *  healthy case, so the existing log line shape stays unchanged for
+ *  passing spawns. */
+export function classifySpecialistTools(tools, toolSurfaceServers) {
+    const matchedServers = new Set();
+    const unparseable = [];
+    const missingSet = new Set();
+    for (const t of tools) {
+        const server = extractServerNameFromQualifiedTool(t);
+        if (server === null) {
+            unparseable.push(t);
+            continue;
+        }
+        if (toolSurfaceServers.has(server)) {
+            matchedServers.add(server);
+        }
+        else if (!missingSet.has(server)) {
+            missingSet.add(server);
+        }
+    }
+    return {
+        matchedServers,
+        unparseableTools: unparseable,
+        missingServers: Array.from(missingSet),
+    };
+}
+/** Builds the placeholder map for per-spawn `mcp.json` env substitution.
+ *  Exported for Task 142 unit coverage that asserts `PLATFORM_PORT` and
+ *  `MAXY_BRAND_PORT` resolve from the manager process env, and for
+ *  Task 476 unit coverage that asserts SESSION_ID equals the passed
+ *  sessionId and never the accountId. */
+export function buildMcpPlaceholders(p, env = process.env) {
+    const platformPort = env.PLATFORM_PORT;
+    const maxyBrandPort = env.MAXY_BRAND_PORT;
+    if (!platformPort) {
+        throw new Error('[claude-session-manager] PLATFORM_PORT not set — manager unit must stamp it (Task 142)');
+    }
+    if (!maxyBrandPort) {
+        throw new Error('[claude-session-manager] MAXY_BRAND_PORT not set — manager unit must stamp it');
+    }
+    // Task 205 — USER_ID lands in lockstep with ACCOUNT_ID. Empty string on
+    // silent-compaction / recorder spawns; never undefined, so JSON
+    // serialization of mcp.json yields a stable shape.
+    //
+    // Task 476 — SESSION_ID is the spawner-minted UUID, passed to claude via
+    // `--session-id` (fresh) or `--resume` (restored) so the value the
+    // plugin reads matches the value claude writes to its PID file and
+    // JSONL. The previous revision aliased this from the senderId field,
+    // which on admin spawns equals the accountId — every admin MCP child
+    // therefore read SESSION_ID === accountId and stamped that onto every
+    // graph write.
+    //
+    // Task 487 — AGENT_SLUG carries provenance ('admin' for the admin
+    // operator, so writes stamp `createdByAgent="admin"`); AGENT_SLUG_SCOPE
+    // carries read-scope (empty for the admin operator, so memory-search
+    // stays wide-open). They were one var until Task 487 split them.
+    // Task 492 — CDP_PORT reaches the `browser` plugin's MCP server so it can
+    // attach to the per-brand VNC Chromium. Unlike PLATFORM_PORT/MAXY_BRAND_PORT
+    // this does NOT throw when absent: buildMcpPlaceholders runs for every spawn,
+    // so a throw would break all agents brand-wide if the stamp ever regressed.
+    // CDP is Pi-only — a laptop native-display install has no VNC Chromium — so
+    // an empty value is a legitimate state where browser-render returns a loud
+    // cdp-unreachable, contained to that one tool.
+    return {
+        PLATFORM_ROOT: p.platformRoot,
+        PREMIUM_PLUGINS_ROOT: join(dirname(p.platformRoot), 'premium-plugins'),
+        ACCOUNT_ID: p.accountId,
+        USER_ID: p.userId ?? '',
+        SESSION_ID: p.sessionId,
+        AGENT_SLUG: p.agentSlug,
+        AGENT_SLUG_SCOPE: p.agentScopeSlug,
+        LOG_DIR: p.logDir,
+        PLATFORM_PORT: platformPort,
+        MAXY_BRAND_PORT: maxyBrandPort,
+        CDP_PORT: env.CDP_PORT ?? '',
+    };
+}
+function writePerSpawnMcpConfig(p) {
+    const serversForRole = [];
+    if (p.specialistTools !== null) {
+        // Task 165 — specialist spawn. Project the agent's `tools:`
+        // frontmatter to the set of plugin namespaces it references; include
+        // only those MCP servers. A specialist that only writes graph
+        // (database-operator: memory, contacts, work) does not get the
+        // dozens of other admin servers stamped into its mcp.json.
+        //
+        // Task 215 — uses `classifySpecialistTools` so post-Task-209
+        // long-prefix names (`mcp__plugin_<plugin>_<server>__<tool>`) resolve
+        // to their `<server>` slug rather than the legacy lazy-regex capture
+        // of `plugin_<plugin>_<server>`. This branch is dead for production
+        // (Task 207 dropped `.mcp.json` writes for specialists) but the
+        // classifier keeps it correct for any future caller and for tests
+        // that exercise the legacy path.
+        const { matchedServers } = classifySpecialistTools(p.specialistTools, p.toolSurface.mcpServers);
+        for (const [name, desc] of p.toolSurface.mcpServers) {
+            if (matchedServers.has(name))
+                serversForRole.push([name, desc]);
+        }
+    }
+    else if (p.role === 'admin') {
+        for (const [name, desc] of p.toolSurface.mcpServers)
+            serversForRole.push([name, desc]);
+    }
+    // Task 615 — the public agent is toolless by construction. Its per-spawn
+    // `.mcp.json` registers ZERO servers; booting any MCP child for a surface
+    // whose `--allowed-tools` is empty and whose permissions.deny blocks every
+    // tool wastes a process and would surface tools in inventory probes the
+    // session can never call. (No `else` branch: serversForRole stays empty.)
+    // Task 142 — placeholder set includes PLATFORM_PORT (internal loopback,
+    // == MAXY_UI_INTERNAL_PORT) and MAXY_BRAND_PORT (brand-public). Both
+    // are stamped on the manager systemd unit by
+    // `buildClaudeSessionManagerUnitFile`, so the manager process inherits
+    // them and the substitution can never silently fall back.
+    const placeholders = buildMcpPlaceholders(p);
+    const mcpServers = {};
+    for (const [name, desc] of serversForRole) {
+        const entry = {
+            command: expandPlaceholders(desc.command, placeholders),
+            args: desc.args.map((a) => expandPlaceholders(a, placeholders)),
+        };
+        if (desc.env) {
+            const env = {};
+            for (const [k, v] of Object.entries(desc.env))
+                env[k] = expandPlaceholders(v, placeholders);
+            entry.env = env;
+        }
+        mcpServers[name] = entry;
+    }
+    const payload = JSON.stringify({ mcpServers }, null, 2);
+    // Task 476 — filename uses the minted sessionId so two concurrent
+    // spawns never collide. Pre-476 this used `bridgeSuffixHint` (==
+    // senderId, == accountId on admin spawns), which DID collide between
+    // parallel admin sessions for the same account.
+    const fileName = `maxy-mcp-${p.sessionId.replace(/[^A-Za-z0-9_-]/g, '_')}.json`;
+    const target = join(p.targetDir, fileName);
+    try {
+        mkdirSync(p.targetDir, { recursive: true });
+        writeFileSync(target, payload, 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        p.logger(`mcp-config-write-failed target=${target} err=${JSON.stringify(msg)}`);
+        return { ok: false, detail: msg };
+    }
+    const resolvedServers = new Map();
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        resolvedServers.set(name, {
+            command: entry.command,
+            args: entry.args,
+            env: entry.env,
+        });
+    }
+    return {
+        ok: true,
+        path: target,
+        bytes: Buffer.byteLength(payload, 'utf8'),
+        serverCount: serversForRole.length,
+        resolvedServers,
+    };
+}
+/** Task 600 — minimum MemAvailable (MB) required to admit a new specialist
+ *  spawn. Calibrated for the 16GB minimum device spec: 4GB reserve keeps
+ *  room for one more heavy claude.exe session (~5GB peak) plus OS headroom. */
+const MIN_ADMISSION_MB = 4096;
+/** Read MemAvailable from /proc/meminfo and return in MB.
+ *  Returns null when /proc/meminfo does not exist (non-Linux). */
+function defaultReadMemAvailableMb() {
+    const MEMINFO_PATH = '/proc/meminfo';
+    try {
+        const content = readFileSync(MEMINFO_PATH, 'utf-8');
+        const match = content.match(/^MemAvailable:\s+(\d+)\s+kB/m);
+        if (!match)
+            return null;
+        return Math.floor(Number(match[1]) / 1024);
+    }
+    catch {
+        return null;
+    }
+}
+/** Pre-spawn slot accounting. Returns either a rejection (caller should
+ *  surface as 503) or undefined when the spawn may proceed. Eviction of an
+ *  idle specialist row, when needed, happens here too. Operator
+ *  (non-specialist) spawns are exempt from both guards. */
+function checkSlotsAndMaybeEvict(deps, args) {
+    const isSpecialistSpawn = typeof args.specialist === 'string' && args.specialist.length > 0;
+    if (!isSpecialistSpawn)
+        return undefined;
+    // Task 600 — memory gate: reject before touching PTY slots if the host
+    // does not have enough free RAM to safely accommodate another heavy session.
+    const readMem = deps.readMemAvailableMb ?? defaultReadMemAvailableMb;
+    const memAvailableMb = readMem();
+    if (memAvailableMb !== null && memAvailableMb < MIN_ADMISSION_MB) {
+        deps.logger(`[pty-cap] low-memory account=${deps.accountId} memAvailableMb=${memAvailableMb} thresholdMb=${MIN_ADMISSION_MB} rejected-specialist=${args.senderId}`);
+        return { kind: 'low-memory', memAvailableMb, thresholdMb: MIN_ADMISSION_MB };
+    }
+    const liveRows = deps.watcher.all().filter((r) => r.state === 'live');
+    const specialistRows = liveRows.filter((r) => r.agent !== null);
+    if (specialistRows.length >= deps.specialistCap) {
+        const idleOldest = specialistRows
+            .filter((r) => r.status === 'idle' && !existsSync(jsonlPathForSessionId(deps.spawnCwd, r.sessionId)))
+            .sort((a, b) => a.updatedAt - b.updatedAt)[0];
+        if (!idleOldest) {
+            deps.logger(`[pty-cap] specialist-cap-reached account=${deps.accountId} current=${specialistRows.length} cap=${deps.specialistCap} evicted=none`);
+            return { kind: 'specialist-cap-reached', currentCount: specialistRows.length, cap: deps.specialistCap };
+        }
+        const victim = livePtys.get(idleOldest.sessionId);
+        if (victim && !victim.exited) {
+            // Task 250 — eviction routes through systemctl stop of the scope
+            // unit, matching the operator-stop and reaper paths. Without this,
+            // an evicted specialist would only die when the manager process
+            // closes its master fd (and the SIGHUP wrap inside the scope makes
+            // it not die at all). systemctl stop gives systemd the cgroup-level
+            // SIGTERM→SIGKILL escalation, with TimeoutStopSec=5 as the ceiling.
+            // Task 451 — stopScopeUnit is async; eviction is fire-and-forget by
+            // design. The evicted scope is still active (the victim hasn't
+            // exited), so the in-cgroup TimeoutStopSec handles SIGTERM→SIGKILL.
+            // We don't await, but `.catch` avoids an unhandled-rejection warning.
+            // The pid is intentionally omitted: post-flight verify is reserved
+            // for the post-restart boot-seed and stopSession paths where the
+            // scope may already be collapsed.
+            const run = deps.runSystemctl ?? defaultSystemctlRunner;
+            void stopScopeUnit(run, victim.scopeUnitToken).catch(() => { });
+        }
+        livePtys.delete(idleOldest.sessionId);
+        trackerRegisteredAt.delete(idleOldest.sessionId);
+        deps.logger(`[pty-cap] specialist-cap-reached account=${deps.accountId} current=${specialistRows.length} cap=${deps.specialistCap} evicted=${idleOldest.sessionId} pty-tracker-size=${livePtys.size}`);
+    }
+    if (liveRows.length >= deps.totalPtyCap - deps.operatorReserve) {
+        deps.logger(`[pty-cap] operator-slots-reserved total=${liveRows.length} reserve=${deps.operatorReserve} totalCap=${deps.totalPtyCap} rejected-specialist=${args.senderId}`);
+        return {
+            kind: 'operator-slots-reserved',
+            total: liveRows.length,
+            reserve: deps.operatorReserve,
+            totalCap: deps.totalPtyCap,
+        };
+    }
+    return undefined;
+}
+/** Task 215 — single source of truth for matching probe results against
+ *  the frontmatter allowlist. Builds the `offered` set with BOTH short
+ *  and long prefix shapes so an agent file's `mcp__plugin_<plugin>_<server>__<tool>`
+ *  declaration intersects with the probe's per-tool reply regardless of
+ *  which Claude Code registry path registers the server at runtime.
+ *  `mcpListedCount` is incremented per actual tool, not per prefix variant
+ *  — the two prefixes refer to the same underlying tool. */
+function buildOfferedSet(result) {
+    const offered = new Set();
+    let mcpListedCount = 0;
+    for (const [serverName, tools] of result) {
+        for (const tool of tools) {
+            offered.add(`mcp__${serverName}__${tool}`);
+            offered.add(`mcp__plugin_${serverName}_${serverName}__${tool}`);
+            mcpListedCount++;
+        }
+    }
+    return { offered, mcpListedCount };
+}
+/** Task 215 — render the optional `unparseable-tools=` and `missing-servers=`
+ *  fields. Empty inputs return an empty string so the inventory line stays
+ *  exactly the legacy shape when the spawn is healthy (no need to teach
+ *  every operator-side grep to skip blank fields). */
+function buildDiagnosticFields(unparseable, missing) {
+    let out = '';
+    if (unparseable.length > 0)
+        out += ` unparseable-tools=${unparseable.join(',')}`;
+    if (missing.length > 0)
+        out += ` missing-servers=${missing.join(',')}`;
+    return out;
+}
+/** Task 178 — fire-and-forget aggregator. Probes each MCP server in the
+ *  spawn's resolved mcp.json for its `tools/list` reply, then emits one
+ *  `[pty-spawn-tool-inventory]` line per spawn. Specialist spawns only —
+ *  operator spawns have no agent frontmatter and the failure shape this
+ *  closes the gap on is recorder-specific. The function never throws;
+ *  probe errors emit a `[pty-spawn-tool-inventory-failed]` line on the
+ *  same logger so the gap is itself observable.
+ *
+ *  Task 215 — accepts `unparseableTools` and `missingServers` from the
+ *  caller's classifier so the line surfaces both diagnostic classes when
+ *  non-empty. The two paths catch different defects: an unparseable token
+ *  signals a malformed frontmatter entry; a missing server signals a typo
+ *  or a stale plugin name that no longer maps to a tool-surface registry
+ *  key. */
+function emitToolInventoryAsync(p) {
+    p.readMcpToolInventory({ servers: p.resolvedServers, timeoutMs: p.timeoutMs })
+        .then((result) => {
+        const { offered, mcpListedCount } = buildOfferedSet(result);
+        const exposed = [];
+        const notExposed = [];
+        for (const name of p.frontmatterAllowlist) {
+            if (offered.has(name))
+                exposed.push(name);
+            else
+                notExposed.push(name);
+        }
+        // Task 207 — `argv-tools=0` is now the literal truth for specialist
+        // spawns (no `--allowed-tools` push). The frontmatter list is implied
+        // by `exposed.length + notExposed.length`; the load-bearing signal is
+        // `mcp-listed-tools` (does the agent's plugin namespace resolve via
+        // plugin-system?) and `not-exposed` (does it match what the agent
+        // declared?). When both reach the brief's target values, the
+        // recorder turn produces real `tool_use` blocks.
+        const diag = buildDiagnosticFields(p.unparseableTools, p.missingServers);
+        p.logger(`[pty-spawn-tool-inventory] sessionId=${p.sessionId} specialist=${p.specialist} argv-tools=0 mcp-listed-tools=${mcpListedCount} exposed=${exposed.join(',')} not-exposed=${notExposed.join(',')}${diag}`);
+    })
+        .catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        p.logger(`[pty-spawn-tool-inventory-failed] sessionId=${p.sessionId} specialist=${p.specialist} err=${JSON.stringify(msg)}`);
+    });
+}
+const finalSnapshotState = new Map();
+/** Watchdog ceiling for "model never produced a first turn" — if no
+ *  `[recorder-turn]` lands within this window, the watchdog fires the
+ *  final snapshot with `reason=first-turn-timeout`. 60 s is the same
+ *  order-of-magnitude as the PID-file timeout and well below typical
+ *  operator patience; tunable in tests via `__setFirstTurnTimeoutMsForTests`. */
+const DEFAULT_FIRST_TURN_TIMEOUT_MS = 60_000;
+let firstTurnTimeoutMs = DEFAULT_FIRST_TURN_TIMEOUT_MS;
+/** Test seam. Production never calls this; the `__` prefix matches the
+ *  in-repo convention for non-API helpers. */
+export function __setFirstTurnTimeoutMsForTests(ms) {
+    firstTurnTimeoutMs = ms;
+}
+export function __resetFirstTurnTimeoutMsForTests() {
+    firstTurnTimeoutMs = DEFAULT_FIRST_TURN_TIMEOUT_MS;
+}
+/** Task 215 — fire the `[pty-spawn-tool-inventory-final]` line once per
+ *  specialist spawn. Idempotent: a second call (e.g. watchdog races a
+ *  late recorder-turn) is a no-op via the `fired` guard. Re-runs the
+ *  probe against the same resolvedServers map the spawn-time probe used,
+ *  so the line reports what the probe would observe AT first-turn
+ *  time — the timing question Phase 1 of Task 215 was filed to answer.
+ *
+ *  The probe is async and the PTY can exit while it's in flight. Both the
+ *  `.then` and `.catch` paths gate emission on `finalSnapshotState.has`
+ *  to suppress phantom lines for sessions whose PTY-exit cleanup ran
+ *  while the probe was still running. The captured `state` reference
+ *  still holds the logger, so the emission would mechanically work — but
+ *  it would lie about a dead session, which is worse than no line. */
+function fireFinalSnapshot(sessionId, reason) {
+    const state = finalSnapshotState.get(sessionId);
+    if (!state || state.fired)
+        return;
+    state.fired = true;
+    if (state.watchdog) {
+        clearTimeout(state.watchdog);
+        state.watchdog = null;
+    }
+    state.readMcpToolInventory({ servers: state.resolvedServers, timeoutMs: state.timeoutMs })
+        .then((result) => {
+        if (!finalSnapshotState.has(sessionId))
+            return;
+        const { offered, mcpListedCount } = buildOfferedSet(result);
+        const exposed = [];
+        const notExposed = [];
+        for (const name of state.frontmatterAllowlist) {
+            if (offered.has(name))
+                exposed.push(name);
+            else
+                notExposed.push(name);
+        }
+        const msSinceSpawn = Date.now() - state.spawnedAt;
+        const diag = buildDiagnosticFields(state.unparseableTools, state.missingServers);
+        state.logger(`[pty-spawn-tool-inventory-final] sessionId=${sessionId} specialist=${state.specialist} mcp-listed-tools=${mcpListedCount} exposed=${exposed.join(',')} not-exposed=${notExposed.join(',')} ms-since-spawn=${msSinceSpawn} reason=${reason}${diag}`);
+    })
+        .catch((err) => {
+        if (!finalSnapshotState.has(sessionId))
+            return;
+        const msg = err instanceof Error ? err.message : String(err);
+        state.logger(`[pty-spawn-tool-inventory-final-failed] sessionId=${sessionId} specialist=${state.specialist} reason=${reason} err=${JSON.stringify(msg)}`);
+    });
+}
+/** Test seam — clear any leftover per-spawn state between tests so a
+ *  failing test doesn't pollute the next one's Map. Production never
+ *  invokes this; the only legitimate eviction path is PTY exit. */
+export function __clearFinalSnapshotStateForTests() {
+    for (const state of finalSnapshotState.values()) {
+        if (state.watchdog)
+            clearTimeout(state.watchdog);
+    }
+    finalSnapshotState.clear();
+}
+export async function spawnClaudeSession(deps, args) {
+    const rejection = checkSlotsAndMaybeEvict(deps, args);
+    if (rejection) {
+        return { ok: false, rejected: rejection };
+    }
+    const startedAt = new Date().toISOString();
+    const start = Date.now();
+    // Task 476 — mint the canonical sessionId before any argv work. One
+    // UUID end-to-end: passed to claude via `--session-id <uuid>` (fresh)
+    // or `--resume <uuid>` (restored); substituted into `${SESSION_ID}` in
+    // the per-spawn mcp.json; used as the systemd scope unit token (Task
+    // 250); keyed onto the sidecar; returned to the caller. Resume spawns
+    // re-use the prior canonical sessionId. The PID file claude writes is
+    // asserted (fresh spawns only — see Task 258 comment below) to carry
+    // this same UUID; mismatch fails the spawn loudly.
+    const sessionId = args.resumeClaudeSessionId ?? randomUUID();
+    const sessionIdSource = args.resumeClaudeSessionId ? 'resume' : 'minted';
+    const unitToken = sessionId;
+    // Task 476/487 — two slugs, one derivation:
+    //  - agentSlug (provenance → ${AGENT_SLUG}): specialist name on subagent
+    //    spawns, public agent slug on public spawns, and the 'admin' sentinel
+    //    on the admin operator spawn so writes stamp `createdByAgent="admin"`
+    //    instead of "unknown".
+    //  - agentScopeSlug (read-scope → ${AGENT_SLUG_SCOPE}): the same slug for
+    //    specialist/public, but EMPTY for the admin operator so memory-search
+    //    stays wide-open (a non-empty slug activates the `$agentSlug IN
+    //    node.agents` filter in graph-search). This reproduces the pre-487
+    //    AGENT_SLUG value exactly — read-scope is unchanged for every role.
+    // Specialist/public spawns share one slug for both concerns; only the
+    // admin operator (no specialist, no public slug) splits 'admin' vs ''.
+    const agentSlug = args.specialist ?? args.agentSlug ?? 'admin';
+    const agentScopeSlug = args.specialist ?? args.agentSlug ?? '';
+    const composedHost = deps.tunnelUrlOverride !== undefined
+        ? { ...deps.host, tunnelUrl: deps.tunnelUrlOverride }
+        : deps.host;
+    // Task 165 — when the spawn is a specialist subagent (`--agent <name>`),
+    // the agent file at `$CLAUDE_CONFIG_DIR/agents/<name>.md` IS the prompt.
+    // Do not stack admin IDENTITY / SOUL / about-owner / plugin manifests on
+    // top: that scaffolding caused the recorder to behave as the admin agent
+    // on every turn since Task 147. Operator (non-specialist) spawns retain
+    // the full composer.
+    const isSpecialistSpawn = typeof args.specialist === 'string' && args.specialist.length > 0;
+    let appendSystemPrompt = '';
+    // The compose-system-prompt block carries per-section byte counts the
+    // [pty-spawn] log line emits later in this function. When the spawn is
+    // a specialist subagent we skip composeAppendSystemPrompt entirely, so
+    // those byte counts are zero — the agent file IS the prompt.
+    let composedBytes = { identity: 0, soul: 0, knowledge: 0, aboutOwner: 0, dormantPlugins: 0 };
+    if (!isSpecialistSpawn) {
+        const composed = composeAppendSystemPrompt(composedHost, 
+        // Task 638 — a public spawn composes from agents/<slug>; the slug is
+        // args.agentSlug (Task 346), falling back to the bundled default public
+        // agent 'public' when a public spawn arrives with no slug. Admin reads
+        // agents/admin and carries no slug.
+        args.role === 'public'
+            ? { accountDir: deps.accountDir, role: 'public', agentSlug: args.agentSlug ?? 'public' }
+            : { accountDir: deps.accountDir, role: 'admin' }, {
+            aboutOwner: args.aboutOwner,
+            dormantPlugins: args.dormantPlugins,
+            activePlugins: args.activePlugins,
+            specialistDomains: args.specialistDomains,
+            // role=public spawns surface the visitor's session_key as
+            // `<chat-session>` so first-party-link skills (Task 336 property-card
+            // click redirect) can correlate the click log to the recommend-fire
+            // log. Admin spawns have no visitor identity — sentinel suppressed.
+            chatSessionKey: args.role === 'public' ? args.senderId : undefined,
+        });
+        if (!composed.ok) {
+            if (composed.reason === 'host-unresolved') {
+                const stderrTail = deps.host.lanIPv4Diagnostic ?? 'append-system-prompt unresolved';
+                deps.logger(`spawn-failed reason=host-context-unresolved stderr-tail=${JSON.stringify(stderrTail)}`);
+                return { ok: false, reason: 'host-context-unresolved', stderrTail };
+            }
+            const sep = composed.detail.lastIndexOf(':');
+            const file = sep > 0 ? composed.detail.slice(0, sep) : composed.detail;
+            const err = sep > 0 ? composed.detail.slice(sep + 1) : '';
+            // Task 618 — public dud refusals (empty/missing SOUL or KNOWLEDGE) carry
+            // their own reason so creation/Test-Greet names the file to author. The
+            // visitor sees an unavailable state; the dud is never served.
+            if (composed.reason === 'soul-empty' ||
+                composed.reason === 'knowledge-missing' ||
+                composed.reason === 'knowledge-empty') {
+                deps.logger(`[pty-spawn] spawn-failed reason=${composed.reason} role=public slug=${agentSlug} file=${file} err=${err}`);
+                return { ok: false, reason: composed.reason, stderrTail: composed.detail };
+            }
+            deps.logger(`[pty-spawn] spawn-failed reason=identity-unresolved accountDir=${deps.accountDir} role=${args.role} file=${file} err=${err}`);
+            return { ok: false, reason: 'identity-unresolved', stderrTail: composed.detail };
+        }
+        appendSystemPrompt = composed.block;
+        composedBytes = {
+            identity: composed.identityBytes,
+            soul: composed.soulBytes,
+            knowledge: composed.knowledgeBytes,
+            aboutOwner: composed.aboutOwnerBytes,
+            dormantPlugins: composed.dormantPluginsBytes,
+        };
+        deps.logger(`compose-system-prompt-ok role=${args.role} accountDir=${deps.accountDir} appendSystemPromptBytes=${Buffer.byteLength(appendSystemPrompt, 'utf8')} identityBytes=${composed.identityBytes} soulBytes=${composed.soulBytes} knowledgeBytes=${composed.knowledgeBytes} aboutOwnerBytes=${composed.aboutOwnerBytes} dormantPluginsBytes=${composed.dormantPluginsBytes} pluginManifestBytes=${composed.pluginManifestBytes} specialistDomainsBytes=${composed.specialistDomainsBytes} chatSessionBytes=${composed.chatSessionBytes}`);
+        // Task 618 — one structured line per public compose carries the byte
+        // counts so "did KNOWLEDGE reach the prompt?" is answerable from logs
+        // without reproduction. knowledgeBytes=0 cannot occur on a successful
+        // public spawn (empty ⇒ refusal), so a 0 here would itself be the anomaly.
+        if (args.role === 'public') {
+            deps.logger(`[pty-spawn] op=public-prompt-compose role=public slug=${agentSlug} identityBytes=${composed.identityBytes} soulBytes=${composed.soulBytes} knowledgeBytes=${composed.knowledgeBytes}`);
+        }
+    }
+    else {
+        deps.logger(`compose-system-prompt-skipped role=${args.role} specialist=${args.specialist} reason=agent-file-is-the-prompt`);
+    }
+    // Task 171 — headless specialists drop --remote-control and the
+    // URL-capture handler. The flag is load-bearing only for spawns whose
+    // session_<id> URL an operator opens in a browser.
+    //
+    // Task 500 — public/visitor spawns also drop --remote-control. Visitors
+    // drive the conversation through the channel-pty bridge, never the
+    // session_<id> RC URL, so the flag is dead weight (one idle outbound
+    // WebSocket per visitor). Admin interactive sessions now run under the
+    // per-account `claude rc` daemon, not per-spawn --remote-control.
+    const headless = isSpecialistSpawn && HEADLESS_ROLES.has(args.specialist);
+    const remoteControl = !headless && args.role !== 'public';
+    const argv = ['--verbose'];
+    if (remoteControl)
+        argv.push('--remote-control');
+    if (!isSpecialistSpawn) {
+        argv.push('--append-system-prompt', appendSystemPrompt);
+    }
+    if (args.resumeClaudeSessionId) {
+        argv.push('--resume', args.resumeClaudeSessionId);
+    }
+    else {
+        // Task 476 — pass the minted sessionId to claude so its PID file and
+        // JSONL carry the same UUID the spawner already stamped into
+        // mcp.json, the sidecar key, and the systemd unit token. Without
+        // this, claude mints its own and the spawner had to scrape the PID
+        // file to learn it.
+        argv.push('--session-id', sessionId);
+    }
+    if (args.specialist) {
+        argv.push('--agent', args.specialist);
+    }
+    if (args.model) {
+        argv.push('--model', args.model);
+    }
+    if (args.channels && args.channels.length > 0) {
+        for (const ch of args.channels) {
+            argv.push('--channels', ch);
+        }
+    }
+    // Task 165 — specialist spawn narrows `--allowed-tools` to the agent's
+    // frontmatter `tools:` list, not the admin surface. Pre-165, every
+    // specialist (recorder, etc.) was launched with the full 131-tool admin
+    // allowlist, defeating the agent file's gate. Operator spawns retain
+    // the role-based surface.
+    let specialistTools = null;
+    let strippedCount = 0;
+    if (isSpecialistSpawn) {
+        try {
+            specialistTools = readSpecialistTools(deps.claudeConfigDir, args.specialist);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            deps.logger(`spawn-failed reason=identity-unresolved detail=${JSON.stringify(detail)}`);
+            return { ok: false, reason: 'identity-unresolved', stderrTail: detail };
+        }
+        // Task 173 — brand-excluded tools from boot-time drift land in
+        // deps.specialistToolStripList. Drop them before they reach argv so
+        // the spawn does not pass a `--allowed-tools` name whose MCP server
+        // is absent from this brand. The strip is per-specialist and exact-
+        // match by tool name; the drift assertion has already determined
+        // which tools belong here.
+        const stripSet = deps.specialistToolStripList?.get(args.specialist);
+        if (stripSet && stripSet.size > 0) {
+            const filtered = specialistTools.filter((t) => !stripSet.has(t));
+            strippedCount = specialistTools.length - filtered.length;
+            specialistTools = filtered;
+        }
+    }
+    // Task 207 — specialist spawns no longer push `--allowed-tools` argv.
+    // `--agent <name>` resolves the agent file's `tools:` frontmatter
+    // natively against Claude Code's plugin-tool registry (registry #1);
+    // the argv push was Task 165's belt-and-suspenders mirror that became
+    // load-bearing in the wrong direction after Task 203's `mcp__plugin_…`
+    // rename: the per-spawn `.mcp.json` registered servers under the
+    // bare-name namespace, so the renamed argv filter found zero matches
+    // and collapsed registry #2 to empty. Specialist agent-frontmatter
+    // tools are still READ above (jsonlTail.register consumes the array,
+    // strip-list observability still fires) but never reach argv.
+    // Operator (non-specialist) spawns retain the role-based push.
+    // Task 615 — every public spawn (any channel) gets ZERO tools. The per-spawn
+    // permissions.deny below is the authority; the allowlist exposes nothing and
+    // the attachment Read scope is dropped. Replaces the Task 346 liveMemory
+    // toggle, which only ever narrowed the public memory surface and is removed.
+    const isPublic = args.role === 'public';
+    const allowed = specialistTools !== null
+        ? Array.from(new Set(specialistTools)).sort()
+        : (() => {
+            // Task 615 — expose nothing for any public spawn. The Task 609 sentinel
+            // below keeps --allowed-tools non-empty so dontAsk stays fail-closed.
+            if (isPublic)
+                return [];
+            // Task 579 — the admin operator spawn unions in every Claude Code
+            // native tool. The PLUGIN.md-derived `toolSurface.admin` covers only
+            // MCP tools; without this union, `--allowed-tools` is set explicitly
+            // to that subset and the CLI silently denies the built-ins (LS,
+            // Glob, Read, Bash, …), so the admin seat could not enumerate its
+            // own disk.
+            const unioned = new Set(deps.toolSurface.admin);
+            for (const t of CC_NATIVE_TOOLS)
+                unioned.add(t);
+            return Array.from(unioned).sort();
+        })();
+    if (isSpecialistSpawn) {
+        deps.logger(`pty-spawn-allowlist specialist=${args.specialist} source=native-agent-flag count=skipped stripped=${strippedCount}`);
+    }
+    else {
+        for (const tool of allowed) {
+            argv.push('--allowed-tools', tool);
+        }
+        const excludedSample = args.role === 'public'
+            ? Array.from(deps.toolSurface.admin).filter((t) => !deps.toolSurface.public.has(t)).sort().slice(0, 5).join(',')
+            : '';
+        // Task 615 — every public spawn resolves an empty allowlist and denies the
+        // whole surface, so report the closed posture; the authority is the
+        // op=public-deny-injected line.
+        const memoryField = isPublic ? ` memory=denied(zero-tool-surface)` : '';
+        deps.logger(`tool-allowlist role=${args.role} count=${allowed.length} excluded=${excludedSample}${memoryField}`);
+    }
+    // Task 485 — observability for the gated/open public-spawn split. Mode
+    // is inferred from the presence of the slice token (caller's bridge has
+    // already gated the spawn on the cookie + accessMode). admin spawns are
+    // skipped — the line is only meaningful on `role=public`.
+    if (args.role === 'public') {
+        const mode = args.sliceToken && args.sliceToken.length > 0 ? 'gated' : 'open';
+        const sliceField = args.sliceToken && args.sliceToken.length > 0
+            ? args.sliceToken.slice(0, 8)
+            : 'none';
+        const personField = args.personId && args.personId.length > 0 ? args.personId : 'none';
+        deps.logger(`[pty-spawn] role=public mode=${mode} sliceToken=${sliceField} personId=${personField}`);
+    }
+    // Task 222 — the admin memory-write/update revoke that Task 213 implemented
+    // at this CLI boundary moved to a PreToolUse hook, which Task 575 then
+    // deleted entirely. Delegation boundaries (admin direct vs Task subagent)
+    // are now governed at the doctrine layer via IDENTITY.md. The CLI
+    // `--disallowed-tools` flag was load-bearing in the wrong direction: it
+    // filters the tool surface of the spawned Claude Code process AND every
+    // in-window Task subagent spawned from it, so the
+    // admin-delegates-graph-write-to-database-operator contract introduced
+    // by Task 214 stopped working — database-operator's frontmatter listed
+    // the writers, but the inherited CLI deny stripped them.
+    //
+    // Task 207 — `--permission-mode bypassPermissions` for specialist spawns
+    // when the caller has not explicitly set one. Headless specialists have
+    // no operator to consent to write-tool invocations; default mode blocks
+    // them with `Claude requested permissions to use mcp__plugin_…, but you
+    // haven't granted it yet` and the recorder turn ends with zero writes.
+    // Operator (non-specialist) spawns keep default mode — the operator IS
+    // the consenter.
+    //
+    // Task 211 / 232 / 236 — modes whose first-time entry shows a consent
+    // dialog pre-accept it by passing `--settings` (the `flagSettings`
+    // source in Claude Code's settings precedence chain) with the
+    // matching documented skip-prompt key. Without it the PTY hangs at the
+    // prompt until the fs-watcher pid-file 30 s timeout kills it. The
+    // Claude Code binary ships two such keys (`strings $(which claude) |
+    // grep '^skip[A-Z][a-zA-Z]*Prompt$'`):
+    //
+    //   bypassPermissions → skipDangerousModePermissionPrompt
+    //                       ("Yes, I accept / No, exit" disclaimer)
+    //   every other mode  → skipAutoPermissionPrompt
+    //                       ("Enable auto mode?" first-time consent)
+    //
+    // Task 576 — claude v2.1.158 surfaces the auto-mode consent on
+    // default-mode launches too, not only on `--permission-mode=auto`.
+    // Default-mode PTYs hung at the prompt with `flag-settings-bytes=0`
+    // until the fs-watcher killed them at the 30 s timeout.
+    //
+    // Task 605 — the brand's `settings.json` ships `permissions.defaultMode:
+    // bypassPermissions`. When the spawn argv omits `--permission-mode`
+    // (the `default` branch below skips it) Claude Code falls back to that
+    // `userSettings` value and the session is actually elevated to bypass —
+    // surfacing the dangerous-mode disclaimer, NOT the auto-mode prompt. A
+    // `default`-mode spawn that only waived `skipAutoPermissionPrompt` hung
+    // at the disclaimer until the 30 s timeout (public chat `cafe65db`).
+    // Because the effective mode at the binary depends on settings the
+    // spawner does not read, every mode now waives BOTH prompts — a skip
+    // key for a prompt that does not appear is a no-op. The waiver MUST
+    // stay per-spawn — writing it into the brand's
+    // `~/.<brand>/.claude/settings.json` (the `userSettings` source) would
+    // permanently waive the disclaimer for every Claude Code session under
+    // the brand. Task 232 added the bypass row; Task 236 added the auto
+    // row; Task 576 broadened to default/plan/acceptEdits; Task 605 made
+    // every mode waive both prompts. New keys land here by extending the
+    // map; no other call site needs to change.
+    // Task 506 — public web-chat sessions face untrusted internet input and
+    // have no operator to answer a permission prompt. Left in `default` mode
+    // they inherit the brand `settings.json` `permissions.defaultMode:
+    // bypassPermissions` + `allow: ["*"]` (seeded by Task 583 for the
+    // claude.ai/code admin surface), which nullifies the narrow public
+    // `--allowed-tools` list and grants the anonymous visitor full native
+    // tools (Bash/Write/Edit/Read) auto-approved — a fail-OPEN RCE-class
+    // exposure, and the agent flails with those tools until the 120 s webchat
+    // turn-timeout fires. `dontAsk` is fail-CLOSED: it never prompts and
+    // auto-denies any tool not in `--allowed-tools`, and the explicit
+    // `--permission-mode dontAsk` flag overrides the brand `defaultMode`.
+    // Verified on the device (claude 2.1.160): `dontAsk` denies Bash even with
+    // `allow: ["*"]` present. The gate is central here (the single spawn
+    // chokepoint) rather than threaded per-caller, and is scoped to
+    // `webchat` — WhatsApp/Telegram share the profile but stay `default`
+    // pending a separate decision (Task 506 scope). An explicit
+    // `args.permissionMode` (operator-selected) still wins.
+    // Task 612 / 615 — every public spawn is an anonymous, zero-tool surface; it
+    // is pinned to the strictest mode and is NOT operator-overridable. Forcing
+    // dontAsk here (rather than letting `args.permissionMode` win, as Task 506
+    // allowed) keeps the empty-allowlist 609 sentinel reachable and prevents a
+    // future caller from downgrading the surface to bypassPermissions, which would
+    // skip the per-spawn permissions.deny entirely. Other roles keep the
+    // operator-selected mode.
+    const effectiveMode = isSpecialistSpawn
+        ? (args.permissionMode ?? 'bypassPermissions')
+        : isPublic
+            ? 'dontAsk'
+            : (args.permissionMode ?? 'default');
+    const BOTH_PROMPTS = '{"skipDangerousModePermissionPrompt":true,"skipAutoPermissionPrompt":true}';
+    const FLAG_SETTINGS_BY_MODE = {
+        bypassPermissions: BOTH_PROMPTS,
+        auto: BOTH_PROMPTS,
+        default: BOTH_PROMPTS,
+        plan: BOTH_PROMPTS,
+        acceptEdits: BOTH_PROMPTS,
+        dontAsk: BOTH_PROMPTS,
+    };
+    let flagSettingsValue = FLAG_SETTINGS_BY_MODE[effectiveMode] ?? '';
+    // Task 612 / 615 — merge the zero-tool-surface permissions.deny into the SAME
+    // --settings that carries the prompt-skip keys. Measured: this per-spawn deny
+    // beats the brand allow:["*"] (the only lever that does). The gate binds on
+    // role=public (every channel), not on effectiveMode — an operator who
+    // hand-picks a non-dontAsk mode for a public spawn still gets the closed
+    // surface.
+    if (isPublic) {
+        const base = flagSettingsValue ? JSON.parse(flagSettingsValue) : {};
+        const deny = buildPublicDeny();
+        base.permissions = { ...(base.permissions ?? {}), deny };
+        flagSettingsValue = JSON.stringify(base);
+        deps.logger(`op=public-deny-injected count=${deny.length} tools=${deny.join(',')}`);
+    }
+    if (effectiveMode !== 'default') {
+        argv.push('--permission-mode', effectiveMode);
+    }
+    if (flagSettingsValue) {
+        argv.push('--settings', flagSettingsValue);
+    }
+    // Task 278 — when auto is requested, capture the binary's
+    // `[auto-mode] verifyAutoModeGateAccess: enabledState=...` debug line
+    // so the manager can derive `effectivePermissionMode` and surface a
+    // downgrade in the admin UI. The 2.1.150 binary writes `auto` to the
+    // JSONL `permission-mode` record whether or not it actually entered
+    // auto at runtime, so the JSONL is not a usable signal source. The
+    // `--debug=auto-mode` category filter narrows the file to one line per
+    // gate-check (about 237 bytes). Task 476 — sessionId is now known up
+    // front, so the debug file is written directly to its canonical
+    // `<sessionId>.permission-mode.log` path; the prior pending-path +
+    // post-waitForPid rename dance (Task 278) collapsed once unitToken
+    // and sessionId unified. Non-auto spawns are untouched.
+    if (effectiveMode === 'auto') {
+        const projectsDir = projectsDirForCwd(deps.spawnCwd);
+        mkdirSync(projectsDir, { recursive: true });
+        const permissionModeLogPath = permissionModeLogPathForSessionId(deps.spawnCwd, sessionId);
+        writeFileSync(permissionModeLogPath, '');
+        argv.push('--debug=auto-mode', `--debug-file=${permissionModeLogPath}`);
+    }
+    // Single MCP channel (Task 502). Admin and specialist spawns take platform
+    // MCPs only from installed plugins (long prefix `mcp__plugin_<p>_<p>__<t>`),
+    // never the per-spawn `.mcp.json` — registering the same server through both
+    // channels let the plugin channel win the name collision while the
+    // instructions referenced the short per-spawn name, so short-prefix calls
+    // failed until the model guessed the long name. Per-account env (ACCOUNT_ID,
+    // USER_ID, NEO4J_URI, NEO4J_PASSWORD, PLATFORM_ROOT, CLAUDE_CONFIG_DIR) rides
+    // the PTY env block below. Public spawns keep the per-spawn write so the
+    // toolless visitor boots ZERO MCP servers (Task 615): the written file carries
+    // an empty `mcpServers`, and `--strict-mcp-config` below blocks auto-discovery
+    // of any project `.mcp.json`, so no server reaches an anonymous visitor.
+    let mcpConfigResult = null;
+    if (args.role === 'public' && !isSpecialistSpawn) {
+        mcpConfigResult = writePerSpawnMcpConfig({
+            role: args.role,
+            toolSurface: deps.toolSurface,
+            accountId: deps.accountId,
+            userId: args.userId,
+            platformRoot: deps.platformRoot,
+            logDir: deps.logDir,
+            sessionId,
+            agentSlug,
+            agentScopeSlug,
+            targetDir: deps.mcpConfigDir ?? tmpdir(),
+            logger: deps.logger,
+            specialistTools,
+        });
+        if (!mcpConfigResult.ok) {
+            return { ok: false, reason: 'mcp-config-write-failed', stderrTail: mcpConfigResult.detail };
+        }
+        argv.push('--mcp-config', mcpConfigResult.path);
+        // Task 205 — surface whether the placeholder map received a non-empty
+        // USER_ID. Silent-compaction / recorder spawns legitimately stamp empty;
+        // a cookie-auth admin spawn with userId-present=no is a regression and
+        // names exactly which spawn produced the `MissingUserIdError` later.
+        deps.logger(`pty-spawn-mcp-config-env userId-present=${args.userId && args.userId.length > 0 ? 'yes' : 'no'}`);
+    }
+    // Task 502 — every pty-spawn passes `--strict-mcp-config` so Claude Code uses
+    // only explicit MCP sources and never auto-discovers a project `.mcp.json`.
+    // Admin + specialist spawns therefore take platform MCPs solely from installed
+    // plugins (long prefix); public spawns add their restricted `--mcp-config`
+    // above. The `claude rc` daemon no longer writes a project `.mcp.json` (its
+    // composer sessions ride installed plugins via the daemon child env), so there
+    // is no short-prefix project file left to collide with the long names.
+    argv.push('--strict-mcp-config');
+    const dirsToAdd = [...deps.agentsDirs[args.role]];
+    if (args.role === 'admin' && existsSync(deps.perAccountSpecialistsDir)) {
+        dirsToAdd.push(deps.perAccountSpecialistsDir);
+    }
+    for (const d of dirsToAdd) {
+        argv.push('--add-dir', d);
+        deps.logger(`pty-spawn-agents-dir role=${args.role} path=${d}`);
+    }
+    if (mcpConfigResult) {
+        deps.logger(`pty-spawn-mcp-config servers=${mcpConfigResult.serverCount} tools=${allowed.length} bytes=${mcpConfigResult.bytes} path=${mcpConfigResult.path}`);
+    }
+    else {
+        // Admin + specialist spawns omit the per-spawn .mcp.json (Task 502 / 207);
+        // their MCP registration is the installed-plugin channel (long prefix),
+        // visible via the plugin-manifest log chain at session start, not here.
+        deps.logger(`pty-spawn-mcp-config role=${args.role} specialist=${args.specialist ?? 'none'} source=installed-plugins`);
+    }
+    // Task 612 / 615 — every public spawn denies all native Read (no path-scoped
+    // carve-out survives the brand allow:["*"]), so no attachment --add-dir + Read
+    // scope is pushed on any public channel; redelivering uploads off native Read
+    // is Task 613.
+    // Task 609 — a public spawn runs in dontAsk (Task 506 / 615), which
+    // fail-closes only against tools NOT in an explicit --allowed-tools. The
+    // public surface now resolves empty on every channel (Task 615), so the loops
+    // above push NO --allowed-tools flag, leaving dontAsk nothing to deny against
+    // and the brand settings.json allow:["*"] re-opens every native tool to an
+    // anonymous visitor (fail-OPEN, the c11777df repro). Anchor the closed posture
+    // with one non-native deny-basis token: its MCP server `none` is never
+    // registered, so it grants nothing while making --allowed-tools present and
+    // non-empty. Native exclusion is checked by bare name against CC_NATIVE_TOOLS.
+    // Must precede the `--` prompt sentinel below, which ends option parsing. The
+    // guard binds on effectiveMode === 'dontAsk', not the channel — every public
+    // spawn resolves to dontAsk, and an operator-selected dontAsk admin spawn is
+    // anchored too; both are the correct fail-closed invariant.
+    if (effectiveMode === 'dontAsk') {
+        const emittedAllowed = [];
+        for (let k = 0; k < argv.length - 1; k++) {
+            if (argv[k] === '--allowed-tools')
+                emittedAllowed.push(argv[k + 1]);
+        }
+        if (emittedAllowed.length === 0) {
+            argv.push('--allowed-tools', DONTASK_DENY_BASIS);
+            emittedAllowed.push(DONTASK_DENY_BASIS);
+        }
+        const nativeExcluded = !emittedAllowed.some((t) => CC_NATIVE_TOOLS.has(t));
+        deps.logger(`op=dontask-allowlist-guard count=${emittedAllowed.length} nativeExcluded=${nativeExcluded}`);
+        // Brief-mandated backstop. Unreachable while the anchor above is
+        // unconditional; it exists so a future change that conditions the anchor
+        // away cannot silently reintroduce a fail-open dontAsk launch.
+        if (emittedAllowed.length === 0) {
+            deps.logger(`spawn-config-error reason=dontask-empty-allowlist sessionId=${sessionId} channel=${args.channel}`);
+            return { ok: false, reason: 'dontask-empty-allowlist', stderrTail: 'dontAsk spawn produced an empty --allowed-tools (Task 609)' };
+        }
+    }
+    // Task 153 / 162 — trailing positional `prompt`. The claude CLI signature
+    // is `claude [options] [command] [prompt]`; when set, the string becomes
+    // the session's first user turn at PTY startup. The POSIX `--` sentinel
+    // ends options parsing so the preceding variadic flags (`--add-dir`,
+    // `--allowed-tools`) cannot swallow the prompt as another value.
+    const promptBytes = Buffer.byteLength(args.initialMessage ?? '', 'utf8');
+    let promptPositional = false;
+    if (args.initialMessage && args.initialMessage.length > 0) {
+        argv.push('--', args.initialMessage);
+        promptPositional = true;
+    }
+    const hooksResolved = discoverHooks(deps.spawnCwd, process.env.CLAUDE_CONFIG_DIR);
+    // Task 205 — `userId` slug on the spawn-start line lets the operator
+    // pair a spawn with the subsequent jsonl. `absent` only on documented
+    // silent-compaction / recorder paths. Slice pattern matches the UI
+    // route's spawn-request-in log (claude-sessions.ts).
+    const userIdSlug = args.userId ? args.userId.slice(0, 8) : 'absent';
+    // Task 207 — assemble the PTY env once so the spawn-start log can name
+    // the explicit specialist-env keys before the spawn fires. The keys-only
+    // surface lets `grep env-keys=` on server.log confirm the contract at
+    // spawn time without leaking secret values into logs.
+    const spawnEnv = {
+        ...process.env,
+        TERM: 'xterm-256color',
+        MAXY_SESSION_ROLE: args.role,
+        MAXY_HIDDEN_SPAWN: args.hidden ? '1' : '0',
+        // Task 147 — Stop-hook gate against recursion now reads the
+        // specialist value, since the recorder is a Sidebar-equivalent
+        // spawn with `specialist=database-operator`. No standalone
+        // recorder-only env flag.
+        MAXY_SPECIALIST: args.specialist ?? '',
+        // Task 205 — admin operator's userId on the MCP child env so
+        // scheduling, memory, time-resolve etc. can key UserProfile reads
+        // by (accountId, userId). Empty string on silent-compaction /
+        // recorder paths; MCP module init must stay boot-tolerant per
+        // the Task 202 contract, so handlers refuse at first use rather
+        // than refusing at boot.
+        USER_ID: args.userId ?? '',
+        // Task 210 — disable Claude Code's default-on auto-memory feature
+        // on every spawn this manager creates. Operator knowledge writes
+        // are owned by the Stop-hook → database-operator → Neo4j pipeline
+        // (Task 081); the auto-memory directory at
+        // `<configDir>/projects/<slug>/memory/` is a competing parallel
+        // store that defeats the graph contract. The env knob is named
+        // in the claude binary's strings table and contracts that, when
+        // set, claude will not read from or write to the auto-memory dir.
+        CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1',
+    };
+    // Task 207 — specialist spawns inherit per-account env explicitly so
+    // plugin-system MCP children get a deterministic context without the
+    // per-spawn `.mcp.json` (dropped above). `{...process.env}` already
+    // covers the production case where the manager systemd unit sets
+    // these — the explicit overwrite documents the contract, plumbs the
+    // values through `deps` so unit tests can inject them, and surfaces
+    // them on the `env-keys=` log line below. Operator spawns are unchanged;
+    // their per-spawn `.mcp.json` continues to inject these via placeholders.
+    //
+    // Task 210 — `CLAUDE_CODE_DISABLE_AUTO_MEMORY` is a harness-control
+    // flag set on every spawn (operator + specialist), so it leads the
+    // env-keys list and the `env-keys=` field is always emitted. This
+    // lets `grep env-keys=CLAUDE_CODE_DISABLE_AUTO_MEMORY server.log`
+    // prove the auto-memory disable is in effect on the most recent
+    // spawn without inspecting the binary's behaviour.
+    const envKeys = ['CLAUDE_CODE_DISABLE_AUTO_MEMORY'];
+    // Task 335 — public spawns scope every graph read to `scope: "public"`
+    // via ALLOWED_SCOPES on the inherited env. The memory MCP server reads
+    // this and constrains memory-search results; without it a public agent
+    // would see admin-scoped nodes, breaking the public/admin boundary the
+    // role split exists to enforce.
+    if (args.role === 'public') {
+        spawnEnv.ALLOWED_SCOPES = 'public';
+        envKeys.push('ALLOWED_SCOPES');
+        // Task 485 — when the caller resolved an active gated grant, stamp the
+        // slice ringfence vars so the memory MCP server widens reads to the
+        // visitor's user-scoped slice and the session-end reviewer hook has the
+        // person id to dispatch with. Skipped on open-mode public spawns where
+        // the slice tokens are absent by definition.
+        if (args.sliceToken && args.sliceToken.length > 0) {
+            spawnEnv.ACCESS_SLICE_TOKEN = args.sliceToken;
+            envKeys.push('ACCESS_SLICE_TOKEN');
+        }
+        if (args.personId && args.personId.length > 0) {
+            spawnEnv.ACCESS_PERSON_ID = args.personId;
+            envKeys.push('ACCESS_PERSON_ID');
+        }
+    }
+    // Task 485 — the session-end reviewer (and any subagent it dispatches via
+    // Task, including database-operator) needs three env vars to stay inside
+    // the ringfence:
+    //   - RECORDER_SLICE_TOKEN: memory-write stamps sliceToken + scope=user
+    //     on every created node; memory-update loud-fails on cross-slice
+    //     mutation.
+    //   - ACCESS_SLICE_TOKEN + ALLOWED_SCOPES=public: memory-search WHERE
+    //     restricts to (n.sliceToken = $env OR n.scope = "public"), so the
+    //     reviewer reads ONLY the visitor's slice + public-scope agent
+    //     knowledge — never another visitor's user-scope rows, never
+    //     admin-scope rows. The reviewer runs as role=admin (so the admin
+    //     mcp.json gives it memory tools) but its read filter is the same
+    //     shape the gated public agent uses.
+    //
+    // The reviewer's `tools:` frontmatter still narrows the active surface to
+    // memory-search + Task; the env-level filter is defence-in-depth in case
+    // a future edit widens the agent template.
+    if (args.specialist === 'public-session-reviewer' && args.sliceToken && args.sliceToken.length > 0) {
+        spawnEnv.RECORDER_SLICE_TOKEN = args.sliceToken;
+        spawnEnv.ACCESS_SLICE_TOKEN = args.sliceToken;
+        spawnEnv.ALLOWED_SCOPES = 'public';
+        envKeys.push('RECORDER_SLICE_TOKEN', 'ACCESS_SLICE_TOKEN', 'ALLOWED_SCOPES');
+        if (args.personId && args.personId.length > 0) {
+            spawnEnv.ACCESS_PERSON_ID = args.personId;
+            envKeys.push('ACCESS_PERSON_ID');
+        }
+    }
+    // Task 502 — admin operator spawns now take platform MCPs from installed
+    // plugins (no per-spawn `.mcp.json`), so the per-account + per-spawn env that
+    // the admin `.mcp.json` used to inject via placeholders must instead ride the
+    // PTY process env: Claude Code substitutes `${ACCOUNT_ID}` / `${SESSION_ID}` /
+    // `${AGENT_SLUG}` / `${AGENT_SLUG_SCOPE}` etc. in each installed plugin's
+    // PLUGIN.md `mcp:` block from this spawnEnv. The same is true for every
+    // specialist spawn (Task 207/476/487). Without these stamps, plugin MCP
+    // children boot with empty context — graph writes record
+    // `createdBySession=unknown` / `createdByAgent=unknown`, and per-account
+    // handlers refuse at first use. Public operator spawns keep the per-spawn
+    // `.mcp.json` placeholder path, so they are excluded here. For specialists
+    // agentSlug === agentScopeSlug (the specialist name).
+    if (isSpecialistSpawn || args.role === 'admin') {
+        spawnEnv.ACCOUNT_ID = deps.accountId;
+        spawnEnv.PLATFORM_ROOT = deps.platformRoot;
+        spawnEnv.CLAUDE_CONFIG_DIR = deps.claudeConfigDir;
+        spawnEnv.NEO4J_URI = deps.brandedNeo4jUri ?? '';
+        spawnEnv.NEO4J_PASSWORD = deps.brandedNeo4jPassword ?? '';
+        spawnEnv.SESSION_ID = sessionId;
+        spawnEnv.AGENT_SLUG = agentSlug;
+        spawnEnv.AGENT_SLUG_SCOPE = agentScopeSlug;
+        envKeys.push('ACCOUNT_ID', 'USER_ID', 'PLATFORM_ROOT', 'CLAUDE_CONFIG_DIR', 'NEO4J_URI', 'NEO4J_PASSWORD', 'SESSION_ID', 'AGENT_SLUG', 'AGENT_SLUG_SCOPE');
+    }
+    // Task 382 — stamp SESSION_NODE_ID on both admin AND specialist spawn
+    // envs so the memory/contacts MCP wrappers see the active conversation's
+    // sessionId and auto-inject the inbound :PRODUCED edge on writes to
+    // gated labels (:Person, :Organization, etc.). The same env-var name covers
+    // both branches because the wrapper contract is single. Skipped when the
+    // arg is absent — autonomous spawns (cron, scheduled-task) without a parent
+    // conversation must thread `producedByTaskId` via `work-create` instead.
+    if (typeof args.conversationNodeId === 'string' && args.conversationNodeId.length > 0) {
+        spawnEnv.SESSION_NODE_ID = args.conversationNodeId;
+        envKeys.push('SESSION_NODE_ID');
+    }
+    const envKeysField = ` env-keys=${envKeys.join(',')}`;
+    deps.logger(`pty-spawn-start claudeBin=${deps.claudeBin} argv-count=${argv.length} append-system-prompt-bytes=${Buffer.byteLength(appendSystemPrompt, 'utf8')} permission-mode=${args.permissionMode ?? 'default'} flag-settings-bytes=${Buffer.byteLength(flagSettingsValue, 'utf8')} resume=${args.resumeClaudeSessionId ? 'yes' : 'no'} sessionId=${sessionId.slice(0, 8)} session-id-source=${sessionIdSource} agentSlug=${agentSlug || '-'} specialist=${args.specialist ?? 'none'} prompt-positional=${promptPositional ? 'yes' : 'no'} prompt-bytes=${promptBytes} userId=${userIdSlug} hooksResolved=${hooksResolved.join(',') || 'none'}${envKeysField}`);
+    const ptySpawnStart = Date.now();
+    let pty;
+    try {
+        pty = deps.spawnPty(deps.claudeBin, argv, spawnEnv, unitToken);
+    }
+    catch (err) {
+        const e = err;
+        const reason = e.code === 'ENOENT' ? 'which-claude-not-found' : 'pty-spawn-failed';
+        const stderrTail = e.message?.slice(-200) ?? '';
+        deps.logger(`spawn-failed reason=${reason} stderr-tail=${JSON.stringify(stderrTail)} pty-spawn-ms=${Date.now() - ptySpawnStart}`);
+        return { ok: false, reason, stderrTail };
+    }
+    deps.logger(`pty-spawned pid=${pty.pid} ms=${Date.now() - ptySpawnStart}`);
+    // Task 476 — register the minted sessionId with the watcher BEFORE
+    // waitForPid fires. Production fs-watcher ignores the hook (it learns
+    // sessionId from claude's PID file, which already carries this same
+    // UUID because `--session-id` was passed). Test mocks use it to
+    // build the synthetic row's sessionId, so the equality assertion
+    // below passes without each test harvesting `--session-id` from argv.
+    deps.watcher.registerPidSessionId?.(pty.pid, sessionId);
+    const tail = attachPtyTail(pty);
+    // URL capture runs in parallel; its result is patched onto the
+    // sidecar when (if) it fires. The spawn promise does not block on
+    // it. A timeout here is logged but not a failure — the operator's
+    // iframe URL falls back to UI-side construction from bridgeSessionId.
+    //
+    // Task 171 — headless spawns never emit the `/remote-control is active`
+    // banner (the flag is absent), so the handler is not attached and no
+    // PTY bytes are consumed by a regex that will never match. Task 500 —
+    // same for public spawns (remoteControl is false), so the gate keys off
+    // `remoteControl`, not `headless`.
+    //
+    // Task 260 — `capturedUrl` is the value SpawnedSession returns to the
+    // caller (the route includes it in the immediate /spawn response when
+    // the banner happens to land before the spawn promise resolves). The
+    // canonical surface is the sidecar; the captured value is also written
+    // there via `updateSidecar` so the watcher's row picks it up.
+    let capturedUrl = null;
+    // Mutable holder so the URL callback can find the row once sessionId
+    // is known. The PID-file event below sets sessionIdRef.current.
+    const sessionIdRef = { current: null };
+    if (remoteControl) {
+        startUrlCapture({
+            pty,
+            timeoutMs: deps.urlCaptureTimeoutMs,
+            logger: deps.logger,
+            onUrl: (url) => {
+                capturedUrl = url;
+                deps.logger(`url-captured pid=${pty.pid} url=${url}`);
+                const sid = sessionIdRef.current;
+                if (!sid)
+                    return;
+                const sidecarPath = sidecarPathForSessionId(deps.spawnCwd, sid);
+                const written = updateSidecar(sidecarPath, { url }, deps.logger);
+                if (!written) {
+                    deps.logger(`[session-sidecar] url-update-skipped sessionId=${sid.slice(0, 8)} reason=sidecar-missing`);
+                    return;
+                }
+                // Force the watcher to re-read the sidecar so its row index
+                // surfaces the new URL to /events and /list. fs.watch does not
+                // fire for sidecar writes (we only watch *.jsonl and PID files).
+                deps.watcher.refreshSidecar(sid);
+                deps.onUrlCaptured?.(sid);
+            },
+            onTimeout: () => {
+                deps.logger(`url-capture-timeout pid=${pty.pid} ms=${Date.now() - start}`);
+            },
+        });
+    }
+    // Wait for the watcher's PID-file event. The watcher resolves
+    // synchronously if the file already exists (race-safe boot scan).
+    // Task 476 — this wait is now a "claude has booted" signal, NOT the
+    // source of truth for sessionId. The spawner minted the sessionId at
+    // the top of pty-spawn and passed it to claude via `--session-id`
+    // (fresh) or `--resume` (resume); the assertion below confirms claude
+    // honoured it on fresh spawns. Task 258 still applies on resume:
+    // `claude --resume` can briefly write a fresh mint to its PID file
+    // before rewriting (per Task 186) to the prior canonical id. Resume
+    // spawns therefore tolerate the transient — equality is guaranteed
+    // by --resume semantics so the assertion would only false-positive on
+    // the race.
+    let row;
+    try {
+        row = await deps.watcher.waitForPid(pty.pid, deps.pidFileTimeoutMs);
+    }
+    catch (err) {
+        pty.kill('SIGKILL');
+        const stderrTail = tail.getTail();
+        tail.dispose();
+        const detail = err instanceof Error ? err.message : String(err);
+        deps.logger(`spawn-failed reason=pid-file-timeout pid=${pty.pid} detail=${JSON.stringify(detail)} stderr-tail=${formatTailForLog(stderrTail)}`);
+        return { ok: false, reason: 'pid-file-timeout', stderrTail };
+    }
+    // Task 476 — sessionId was minted at the top of pty-spawn and passed
+    // to claude via `--session-id` / `--resume`. The PID file's sessionId
+    // is asserted equal on fresh spawns; resume spawns tolerate a brief
+    // transient mismatch (Task 258: claude --resume can briefly write a
+    // fresh mint to the PID file before rewriting to the prior canonical
+    // id). A mismatch on a fresh spawn means the claude binary did not
+    // honour `--session-id` and is a loud spawn-failure, not silent
+    // rebinding.
+    if (sessionIdSource === 'minted' && row.sessionId !== sessionId) {
+        pty.kill('SIGKILL');
+        tail.dispose();
+        deps.logger(`spawn-failed reason=pid-file-session-mismatch minted=${sessionId.slice(0, 8)} pid-file=${row.sessionId.slice(0, 8)} pid=${pty.pid}`);
+        return { ok: false, reason: 'pid-file-session-mismatch', stderrTail: `pid-file sessionId=${row.sessionId} != minted=${sessionId}` };
+    }
+    sessionIdRef.current = sessionId;
+    const specialist = args.specialist ?? row.agent ?? null;
+    const hidden = args.hidden === true;
+    // Task 260 — write the sidecar BEFORE registering the tracker. The
+    // sidecar is the canonical record of spawn metadata; the watcher
+    // row will read it the moment the JSONL CREATE event fires (the
+    // first user turn flush). If the write fails — disk full, RO mount,
+    // unexpected eperm — refuse the spawn loudly rather than launch a
+    // metadata-less PTY that the wire payload could not honour. The
+    // PTY is killed in the catch so no orphan claude child remains.
+    //
+    // Task 342 — on a resume spawn, `claude --resume` does NOT reprint
+    // the `/remote-control is active` banner, so `capturedUrl` stays
+    // null and writing the sidecar fresh would wipe the URL captured
+    // during the original spawn. Read the prior sidecar and carry
+    // forward the URL when capture didn't fire. Field-by-field audit:
+    // only `url` is preserved — all other fields are either operator-
+    // settable on the resume body (senderId/role/channel/permissionMode/
+    // model/hidden/specialist) or re-derived by tails
+    // (effectivePermissionMode). `startedAt` re-stamps to this PTY's
+    // start time, the pre-existing behaviour.
+    const sidecarPath = sidecarPathForSessionId(deps.spawnCwd, sessionId);
+    const priorSidecar = args.resumeClaudeSessionId
+        ? readSidecar(sidecarPath, deps.logger).sidecar
+        : null;
+    const resolvedUrl = capturedUrl ?? priorSidecar?.url ?? null;
+    const urlSource = capturedUrl ? 'captured' : priorSidecar?.url ? 'prior-sidecar' : 'none';
+    deps.logger(`sidecar-url-source sessionId=${sessionId.slice(0, 8)} url-source=${urlSource} resume=${args.resumeClaudeSessionId ? 'yes' : 'no'}`);
+    const sidecar = {
+        senderId: args.senderId,
+        role: args.role,
+        channel: args.channel,
+        url: resolvedUrl,
+        startedAt,
+        permissionMode: args.permissionMode ?? null,
+        // Task 278 — null until `permission-mode-tail.ts` consumes the first
+        // `[auto-mode] verifyAutoModeGateAccess` debug line from the file
+        // we just renamed above (when effectiveMode === 'auto'). On non-auto
+        // spawns no capture exists, so the field stays null forever and the
+        // pane renders the requested mode plain.
+        effectivePermissionMode: null,
+        model: args.model ?? null,
+        hidden,
+        specialist,
+        // Task 451 — persist the scope token so boot-seed can reattach the
+        // surviving scope to this row after a manager restart, even when the
+        // unit token is a fresh-spawn UUID that does not equal `sessionId`.
+        scopeUnitToken: unitToken,
+        // Task 550 — composer bridge ULIDs are appended by the http-server's
+        // pid-file watcher subscription on /rc-spawn binds. A resume that
+        // already had bridgeIds keeps them; a fresh spawn starts empty.
+        bridgeIds: priorSidecar?.bridgeIds ?? [],
+    };
+    try {
+        writeSidecar(sidecarPath, sidecar, deps.logger);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        pty.kill('SIGKILL');
+        const stderrTail = tail.getTail();
+        tail.dispose();
+        deps.logger(`spawn-failed reason=sidecar-write-failed sessionId=${sessionId.slice(0, 8)} path=${sidecarPath} err=${JSON.stringify(detail)} stderr-tail=${formatTailForLog(stderrTail)}`);
+        return { ok: false, reason: 'sidecar-write-failed', stderrTail };
+    }
+    // Task 260 — the watcher's row was built BEFORE we wrote the sidecar
+    // (waitForPid resolved first), so its sidecar fields are still null.
+    // Force a re-read so subsequent /list and /events calls see the
+    // freshly-written senderId/role/channel/etc. Some test fixtures use
+    // a hand-built watcher mock that predates `refreshSidecar` on the
+    // interface — the optional-chain keeps them working without a forced
+    // sweep update.
+    deps.watcher.refreshSidecar?.(sessionId);
+    const tracker = {
+        sessionId,
+        bridgeSessionId: row.bridgeSessionId ?? `session_${sessionId}`,
+        bridgeSuffix: row.bridgeSuffix ?? sessionId,
+        pid: pty.pid,
+        pty,
+        exited: false,
+        fdReleased: false,
+        hidden,
+        specialist,
+        scopeUnitToken: unitToken,
+    };
+    livePtys.set(sessionId, tracker);
+    trackerRegisteredAt.set(sessionId, Date.now());
+    deps.logger(`[pty-tracker] op=spawn sessionId=${sessionId.slice(0, 8)} pid=${pty.pid} size=${livePtys.size}`);
+    if (hidden) {
+        deps.logger(`hidden-spawn specialist=${specialist ?? 'none'} sessionId=${sessionId} pid=${pty.pid}`);
+    }
+    // PTY exit: mark exited; the watcher will fire a delete event when
+    // claude removes its PID file, which the http-server subscriber
+    // translates into an archived row (JSONL still on disk if any turn ran).
+    pty.onExit((e) => {
+        const stderrTail = tail.getTail();
+        tail.dispose();
+        handlePtyNaturalExit({ logger: deps.logger }, tracker, e, stderrTail);
+    });
+    const responseMs = Date.now() - start;
+    deps.logger(`spawn-response-returned sessionId=${sessionId} pid=${pty.pid} ms=${responseMs}`);
+    deps.logger(`spawn pid=${pty.pid} sessionId=${sessionId} senderId=${args.senderId} role=${args.role} channel=${args.channel} permissionMode=${args.permissionMode ?? 'default'} remoteControl=${remoteControl} latency-ms=${responseMs}`);
+    deps.logger(`[pty-spawn] sessionId=${sessionId} appendSystemPromptBytes=${Buffer.byteLength(appendSystemPrompt, 'utf8')} identityBytes=${composedBytes.identity} soulBytes=${composedBytes.soul} knowledgeBytes=${composedBytes.knowledge} aboutOwnerBytes=${composedBytes.aboutOwner} dormantPluginsBytes=${composedBytes.dormantPlugins} accountDir=${deps.accountDir} role=${args.role} specialist=${args.specialist ?? 'none'} hostname=${deps.host.hostname} lanIPv4=${deps.host.lanIPv4} adminUrl=${deps.host.adminUrl} tunnelUrl=${composedHost.tunnelUrl ?? 'none'}`);
+    // Task 178 — emit [pty-spawn-tool-inventory] for specialist spawns. The
+    // probe runs in parallel with the real claude child's own MCP handshake
+    // and is fire-and-forget: it never blocks the spawn response, and its
+    // own failures emit a [pty-spawn-tool-inventory-failed] line. Operator
+    // (admin/public) spawns have no agent frontmatter — the failure shape
+    // this closes the gap on is recorder-specific (Task 174 §3).
+    //
+    // Task 207 — descriptors come from `deps.toolSurface.mcpServers`
+    // directly (narrowed to the plugin namespaces the agent file's
+    // `tools:` frontmatter references) instead of the per-spawn `.mcp.json`
+    // that this task drops for specialists. The probe still spawns its
+    // own MCP children to query `tools/list`; it does not — and cannot —
+    // inspect Claude Code's internal plugin-tool registry. `argv-tools` is
+    // now 0 for specialists (no `--allowed-tools` push); `mcp-listed-tools`
+    // continues to reflect what each MCP server actually offers. The
+    // not-exposed = (frontmatter ∖ offered) computation still surfaces
+    // namespace-mismatch regressions.
+    if (isSpecialistSpawn && specialistTools !== null) {
+        // Task 476 — the probe spawns transient MCP children to call
+        // tools/list. They share the same placeholder map as the live
+        // spawn so any write a plugin performs during boot lands with the
+        // same SESSION_ID + AGENT_SLUG as the live children would.
+        const placeholders = buildMcpPlaceholders({
+            platformRoot: deps.platformRoot,
+            accountId: deps.accountId,
+            userId: args.userId,
+            sessionId,
+            agentSlug,
+            agentScopeSlug,
+            logDir: deps.logDir,
+        });
+        // Task 215 — classify the frontmatter list once. `matchedServers` is
+        // the set of `toolSurface.mcpServers` keys to spawn for the probe;
+        // `unparseableTools` and `missingServers` ride downstream into both
+        // the spawn-time and end-of-first-turn inventory lines, so a future
+        // namespace drift (or an agent file with a typo) can be told apart
+        // from a real MCP boot failure by reading server.log alone.
+        const { matchedServers, unparseableTools, missingServers } = classifySpecialistTools(specialistTools, deps.toolSurface.mcpServers);
+        const resolvedServers = new Map();
+        for (const [name, desc] of deps.toolSurface.mcpServers) {
+            if (!matchedServers.has(name))
+                continue;
+            const probeEnv = desc.env
+                ? Object.fromEntries(Object.entries(desc.env).map(([k, v]) => [k, expandPlaceholders(v, placeholders)]))
+                : undefined;
+            resolvedServers.set(name, {
+                command: expandPlaceholders(desc.command, placeholders),
+                args: desc.args.map((a) => expandPlaceholders(a, placeholders)),
+                env: probeEnv,
+            });
+        }
+        const readInventory = deps.readMcpToolInventory
+            ?? ((req) => probeMcpServerTools({
+                servers: req.servers,
+                baseEnv: process.env,
+                timeoutMs: req.timeoutMs,
+            }));
+        const inventoryTimeoutMs = deps.toolInventoryProbeTimeoutMs ?? 5_000;
+        emitToolInventoryAsync({
+            sessionId: sessionId,
+            specialist: args.specialist,
+            frontmatterAllowlist: specialistTools,
+            resolvedServers,
+            unparseableTools,
+            missingServers,
+            readMcpToolInventory: readInventory,
+            timeoutMs: inventoryTimeoutMs,
+            logger: deps.logger,
+        });
+        // Task 215 — register the per-spawn state that the JsonlTail callback
+        // (or the watchdog timer) needs to fire the final snapshot. State is
+        // module-scoped so a stale entry past PTY exit is a leak; the exit
+        // handler below explicitly clears it. The watchdog covers the failure
+        // mode where the model emits zero useful content (the exact defect
+        // this task investigates): without the timer, a spawn that never
+        // produces a first turn would never emit a final snapshot, and the
+        // operator would have no signal at all for the broken case.
+        finalSnapshotState.set(sessionId, {
+            specialist: args.specialist,
+            frontmatterAllowlist: specialistTools,
+            resolvedServers,
+            unparseableTools,
+            missingServers,
+            readMcpToolInventory: readInventory,
+            timeoutMs: inventoryTimeoutMs,
+            logger: deps.logger,
+            spawnedAt: Date.now(),
+            fired: false,
+            watchdog: setTimeout(() => fireFinalSnapshot(sessionId, 'first-turn-timeout'), firstTurnTimeoutMs),
+        });
+    }
+    // Task 183 — register the specialist spawn with the JSONL tail. The
+    // tail's state must exist BEFORE any JSONL modify event fires so the
+    // first init-shaped record produces Line 1. Task 207 — `--allowed-tools`
+    // is no longer pushed for specialists, so `argvTools` is the empty array
+    // for them; `toolsArgvMissingFromExposed` becomes a no-op, which is the
+    // correct semantic (nothing was launched on argv, so nothing can be
+    // missing). Operator spawns do not register; the tail emits nothing for
+    // them.
+    //
+    // Task 215 — `onFirstTurn` fires the `[pty-spawn-tool-inventory-final]`
+    // snapshot when the model emits its first non-thinking assistant
+    // record. Paired with the watchdog timer set above (in the Task-178
+    // probe block); whichever fires first wins, the other is a no-op via
+    // the `fired` guard inside `fireFinalSnapshot`.
+    if (isSpecialistSpawn && deps.jsonlTail) {
+        deps.jsonlTail.register(sessionId, {
+            specialist: args.specialist,
+            argvTools: [],
+            onFirstTurn: () => fireFinalSnapshot(sessionId, 'first-turn'),
+        });
+        pty.onExit(() => deps.jsonlTail?.unregister(sessionId));
+    }
+    // Task 215 — PTY-exit cleanup for the final-snapshot state runs
+    // INDEPENDENTLY of the JsonlTail wiring. When `deps.jsonlTail` is
+    // undefined (test fixtures, partial-mock deployments), state was
+    // still registered above in the Task-178 probe block, and the
+    // watchdog timer needs to be canceled on exit to prevent a leak
+    // that fires `[pty-spawn-tool-inventory-final] reason=first-turn-timeout`
+    // against a long-dead session 60 s later.
+    if (isSpecialistSpawn && specialistTools !== null) {
+        pty.onExit(() => {
+            const state = finalSnapshotState.get(sessionId);
+            if (state?.watchdog)
+                clearTimeout(state.watchdog);
+            finalSnapshotState.delete(sessionId);
+        });
+    }
+    deps.onSessionReady?.(tracker);
+    return {
+        ok: true,
+        session: {
+            sessionId,
+            pid: pty.pid,
+            startedAt,
+            url: capturedUrl,
+            tracker,
+        },
+    };
+}
+/** Task 176 — natural-exit handler. Fires when the claude child exits on
+ *  its own (operator `/quit`, SIGINT in the PTY, crash, network drop on
+ *  `--remote-control`), with no operator `/stop` and no auto-archive in
+ *  flight. Mirrors `killSession`'s post-Task-170 fd-release + tracker
+ *  removal contract on the second exit branch the original task
+ *  explicitly out-of-scoped. Without this, the master fd lingers in
+ *  node-pty's internal socket until V8 GC finalises the IPty object,
+ *  and the tracker entry survives until manager shutdown — so the
+ *  shutdown loop SIGTERMs PIDs that already logged `process-exited`.
+ *
+ *  Side-effect order is load-bearing: set `exited` first so any
+ *  concurrent `killSession` sees the already-exited branch; release the
+ *  fd second (idempotent on a destroyed socket via the try/catch in
+ *  `releasePtyMasterFd`); drop the tracker third (Map.delete on a
+ *  missing key is a no-op, so the operator-request follow-up that
+ *  races us is harmless). The log line carries the same `master-fd=...`
+ *  suffix the operator-request path emits — every `kill … pid=<n>`
+ *  line in `server.log` now ends in `master-fd=...`, no exceptions.
+ *
+ *  Exported so `__tests__/stop-session-fd-release.test.ts` can verify
+ *  the contract end-to-end without re-implementing the handler in test
+ *  code. */
+export function handlePtyNaturalExit(deps, tracker, exit, stderrTail) {
+    tracker.exited = true;
+    // Task 455 — bump the exit-history counter as the second side effect,
+    // immediately after marking the tracker exited. Doing it here (rather
+    // than at the bottom) means a later throw between flag-set and the
+    // log line — `releasePtyMasterFd` is rescued today, but defense in
+    // depth shouldn't rely on that staying true forever — cannot suppress
+    // the observability signal the /stop route needs to surface respawn
+    // history. The counter tracks "how many earlier PTYs of this sessionId
+    // have already exited" relative to any future stop and is unconditional
+    // on the delete-on-identity race below.
+    priorExitedBySessionId.set(tracker.sessionId, (priorExitedBySessionId.get(tracker.sessionId) ?? 0) + 1);
+    // Skip if a racing `killSession` already released the fd — second
+    // destroy() on a destroyed node-pty socket throws "socket already
+    // destroyed" and would turn this line's suffix into a false
+    // `master-fd=close-failed`.
+    const fdSuffix = tracker.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(tracker);
+    if (fdSuffix === 'master-fd=closed')
+        tracker.fdReleased = true;
+    // Task 260 — only remove the tracker entry if it is still OUR tracker.
+    // A subsequent spawn could have replaced the entry under the same
+    // sessionId (LRU recycle in production; cross-fixture sessionId
+    // collision in tests).
+    if (livePtys.get(tracker.sessionId) === tracker) {
+        livePtys.delete(tracker.sessionId);
+        trackerRegisteredAt.delete(tracker.sessionId);
+    }
+    deps.logger(`kill pid=${tracker.pid} reason=process-exited exit-code=${exit.exitCode} signal=${exit.signal ?? 'none'} stderr-tail=${formatTailForLog(stderrTail)} ${fdSuffix}`);
+    deps.logger(`[pty-tracker] op=exit sessionId=${tracker.sessionId.slice(0, 8)} pid=${tracker.pid} size=${livePtys.size}`);
+}
+/** Release the pty master fd by destroying node-pty's internal socket.
+ *  Without this, the fd lingers until V8 GC finalizes the IPty object —
+ *  non-deterministic and accumulates under load. Returns the trailing
+ *  log suffix ("master-fd=closed" on success, "master-fd=close-failed
+ *  err=..." on throw). The throw path is rescued so a destroy failure
+ *  on a corner-case socket state cannot turn a logically-successful
+ *  stop into a 500. Task 170. */
+function releasePtyMasterFd(t) {
+    try {
+        t.pty.destroy?.();
+        return 'master-fd=closed';
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `master-fd=close-failed err=${JSON.stringify(msg)}`;
+    }
+}
+/** Task 558 — `op=archive-release` shape. The operator-archive (UI End
+ *  click → `/stop`) is the canonical and ONLY master-fd release point
+ *  for an rc-spawn or operator session. This helper performs the release
+ *  with full verification:
+ *
+ *    1. Snapshot `/proc/self/fd` BEFORE the destroy (set of fd numbers).
+ *    2. Run `releasePtyMasterFd` — captures `master-fd=<closed|close-failed>`.
+ *    3. Snapshot `/proc/self/fd` AFTER. The set-difference is the
+ *       released fd number(s); the single-fd case is the happy path.
+ *    4. Delete the tracker from `livePtys` + `trackerRegisteredAt` if
+ *       identity still matches (LRU-recycle guard).
+ *    5. Emit `[rc-spawn] op=archive-release sessionId=… pid=…
+ *       master-fd=<status> fdBefore=N fdAfter=N fdDelta=N
+ *       removedFds=<list> trackerRemoved=<bool> verified=<bool>`.
+ *
+ *  `verified=true` iff `master-fd=closed` AND `fdDelta>=1` AND
+ *  `trackerRemoved=true`. `master-fd=close-failed` is logged at error
+ *  level (`[rc-spawn-error]` prefix) — never swallowed; the next
+ *  post-archive sweep is the catch-net for that surface.
+ *
+ *  Procfs absent (darwin dev Mac): `readOpenFdSet()` returns an empty
+ *  Set, so `fdBefore`/`fdAfter`/`fdDelta` all report 0 and `verified`
+ *  collapses to `master-fd=closed && trackerRemoved`. The verification
+ *  is best-effort on platforms without procfs — the manager process
+ *  itself only runs on linux in production. */
+function archiveReleaseTracker(deps, t, sessionId) {
+    const fdBeforeSet = readOpenFdSet();
+    const suffix = t.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(t);
+    if (suffix === 'master-fd=closed')
+        t.fdReleased = true;
+    const fdAfterSet = readOpenFdSet();
+    let trackerRemoved = false;
+    if (livePtys.get(sessionId) === t) {
+        livePtys.delete(sessionId);
+        trackerRegisteredAt.delete(sessionId);
+        trackerRemoved = true;
+    }
+    const fdBefore = fdBeforeSet.size;
+    const fdAfter = fdAfterSet.size;
+    const fdDelta = fdBefore - fdAfter;
+    const removed = [];
+    for (const fd of fdBeforeSet)
+        if (!fdAfterSet.has(fd))
+            removed.push(fd);
+    const verified = suffix === 'master-fd=closed' && fdDelta >= 1 && trackerRemoved;
+    const prefix = suffix.startsWith('master-fd=close-failed') ? '[rc-spawn-error]' : '[rc-spawn]';
+    deps.logger(`${prefix} op=archive-release sessionId=${sessionId.slice(0, 8)} pid=${t.pid} ${suffix} fdBefore=${fdBefore} fdAfter=${fdAfter} fdDelta=${fdDelta} removedFds=${removed.length === 0 ? 'none' : removed.join(',')} trackerRemoved=${trackerRemoved} verified=${verified}`);
+    return { suffix, verified };
+}
+/** Task 250 + 260 — operator-request stop. Issues `systemctl --user
+ *  stop --no-block <scope>` against the PTY's scope unit (Task 250)
+ *  instead of `pty.kill('SIGTERM')`; the scope's TimeoutStopSec=5 handles
+ *  SIGTERM→SIGKILL escalation inside its own cgroup. Idempotent: a
+ *  no-such-unit response (exit code 5) is treated as success because
+ *  claude exited naturally and systemd retired the scope. The master fd
+ *  is still released locally — fd ownership stays with the manager
+ *  process and must be cleaned up there, irrespective of which process
+ *  killed claude.
+ *
+ *  Task 260 — looks up the tracker in the module-scoped `livePtys` map
+ *  (the metadata-rich SessionStore is gone). Deletes by identity (only
+ *  if `livePtys.get(sessionId) === t`) so an LRU recycle or a
+ *  cross-fixture sessionId collision in tests never clobbers a live
+ *  PTY whose tracker was registered after the current call resolved. */
+export async function stopSession(deps, sessionId) {
+    // Task 455 — alive filter: an entry with `exited=true` that somehow
+    // survived in `livePtys` is treated as a miss, so the stop never
+    // targets a stale pid. The natural-exit handler also purges on its
+    // own (layer 1); this filter is layer 2 of the two-layer invariant
+    // documented above the `livePtys` declaration.
+    const t = resolveLiveTracker(sessionId);
+    if (!t) {
+        // Task 427 — row-scope fallback. The PTY survived a manager restart
+        // (Task 250) and was reattached to its `SessionRow` by the boot-seed,
+        // but `livePtys` is module-scoped and is never repopulated. When the
+        // caller supplies the row's scope unit token, stop the scope directly
+        // — there is no master fd to release because the current manager
+        // never opened one for this process. A true miss (no row, no token)
+        // still returns `no-store-entry`.
+        const rowToken = deps.rowScopeUnitToken ?? null;
+        if (rowToken === null) {
+            return { existed: false, path: 'no-store-entry', scopeOutcome: 'no-store-entry', exitCode: null };
+        }
+        const start = Date.now();
+        const unit = scopeUnitName(rowToken);
+        const run = deps.runSystemctl ?? defaultSystemctlRunner;
+        const stop = await stopScopeUnit(run, rowToken, {
+            pid: deps.rowPid ?? null,
+            killGraceMs: deps.killGraceMs,
+        });
+        if (stop.outcome === 'error') {
+            deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=error exit-code=${stop.exitCode} ms=${Date.now() - start} sessionId=${sessionId} path=row-scope stderr=${JSON.stringify(stop.stderr.slice(-200))}`);
+            return { existed: true, path: 'row-scope', scopeOutcome: 'error', exitCode: stop.exitCode };
+        }
+        deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=${stop.outcome} ms=${Date.now() - start} sessionId=${sessionId} path=row-scope`);
+        return {
+            existed: true,
+            path: 'row-scope',
+            scopeOutcome: stop.outcome,
+            exitCode: stop.outcome === 'already-gone' ? stop.exitCode : 0,
+        };
+    }
+    const start = Date.now();
+    const unit = scopeUnitName(t.scopeUnitToken);
+    if (t.exited) {
+        // Task 176 short-circuit: if the natural-exit handler already
+        // released the fd, skip the second destroy() — on real node-pty it
+        // would throw "socket already destroyed" and we'd emit a false
+        // `master-fd=close-failed`. Defense in depth still holds: if the
+        // earlier destroy threw, fdReleased stays false and we retry here.
+        //
+        // Task 455 — the `resolveLiveTracker` filter above makes this
+        // branch unreachable on entry: an exited tracker never resolves.
+        // The check is kept as belt-and-braces in case `t.exited` flips
+        // to true during a future `await` inserted into the happy path.
+        const { suffix: fdSuffix } = archiveReleaseTracker({ logger: deps.logger }, t, sessionId);
+        deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=already-exited ms=${Date.now() - start} sessionId=${sessionId} pid=${t.pid} ${fdSuffix}`);
+        deps.logger(`[pty-tracker] op=exit sessionId=${sessionId.slice(0, 8)} pid=${t.pid} size=${livePtys.size}`);
+        return { existed: true, path: 'liveptys', scopeOutcome: 'already-gone', exitCode: null };
+    }
+    const run = deps.runSystemctl ?? defaultSystemctlRunner;
+    const stop = await stopScopeUnit(run, t.scopeUnitToken, {
+        pid: t.pid,
+        killGraceMs: deps.killGraceMs,
+    });
+    if (stop.outcome === 'error') {
+        deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=error exit-code=${stop.exitCode} ms=${Date.now() - start} sessionId=${sessionId} pid=${t.pid} stderr=${JSON.stringify(stop.stderr.slice(-200))}`);
+        return { existed: true, path: 'liveptys', scopeOutcome: 'error', exitCode: stop.exitCode };
+    }
+    // outcome=ok or already-gone — both mean the scope is on its way out (or
+    // already retired). Release the manager-side master fd and drop the
+    // tracker entry; the watcher will observe Claude Code's PID-file delete
+    // shortly and emit the archive transition. Task 558 routes the release
+    // through `archiveReleaseTracker` so every operator-stop emits a
+    // verified `op=archive-release` line — the only window a real
+    // master-fd leak can exist.
+    const { suffix: fdSuffix } = archiveReleaseTracker({ logger: deps.logger }, t, sessionId);
+    deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=${stop.outcome} ms=${Date.now() - start} sessionId=${sessionId} pid=${t.pid} ${fdSuffix}`);
+    deps.logger(`[pty-tracker] op=exit sessionId=${sessionId.slice(0, 8)} pid=${t.pid} size=${livePtys.size}`);
+    return {
+        existed: true,
+        path: 'liveptys',
+        scopeOutcome: stop.outcome,
+        exitCode: stop.outcome === 'already-gone' ? stop.exitCode : 0,
+    };
+}
+/** Task 260 — alias preserved during the http-server callsite rename
+ *  in this branch. The canonical export name is `stopSession` (Task 250). */
+export const killSession = stopSession;
+/** Task 557 — open file-descriptor count for the manager process. Reads
+ *  `/proc/self/fd` directly. Returns -1 on platforms that don't expose
+ *  procfs (darwin dev Mac) or on read failure. Used by `[fd-census]`
+ *  log lines so an rc-spawn leak is visible as `openFds` rising while
+ *  `livePtys` stays flat across successive spawns. */
+export function openFdCount() {
+    try {
+        return readdirSync('/proc/self/fd').length;
+    }
+    catch {
+        return -1;
+    }
+}
+/** Task 558 — set-valued companion to `openFdCount`. Returns the set of
+ *  fd numbers (as strings) in `/proc/self/fd`. Empty Set on platforms
+ *  without procfs (darwin) or on read failure — distinguishable from a
+ *  genuinely-empty fd set because the manager process always holds at
+ *  least stdin/stdout/stderr. Callers that need to identify a specific
+ *  closed fd take the set-difference (before − after). */
+function readOpenFdSet() {
+    try {
+        return new Set(readdirSync('/proc/self/fd'));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function runPostArchiveSweep(deps) {
+    const now = (deps.now ?? Date.now)();
+    const liveSessionIds = deps.liveSessionIds();
+    const liveSessionSet = new Set(liveSessionIds);
+    let archivedWithMaster = 0;
+    let escalated = 0;
+    for (const [sessionId, tracker] of livePtys.entries()) {
+        if (!deps.isArchived(sessionId))
+            continue;
+        archivedWithMaster++;
+        const archivedAt = deps.archivedAtMs(sessionId) ?? trackerRegisteredAt.get(sessionId) ?? now;
+        const heldSinceArchiveMs = Math.max(0, now - archivedAt);
+        deps.logger(`[fd-audit] op=orphan-master sessionId=${sessionId.slice(0, 8)} pid=${tracker.pid} archivedAt=${archivedAt} heldSinceArchiveMs=${heldSinceArchiveMs} fd=unknown`);
+        if (heldSinceArchiveMs >= deps.ageEscalateMs) {
+            escalated++;
+            deps.logger(`[fd-audit] op=orphan-master-escalate sessionId=${sessionId.slice(0, 8)} fd=unknown heldSinceArchiveMs=${heldSinceArchiveMs}`);
+        }
+    }
+    let orphanLiveSessionsNoMaster = 0;
+    for (const sessionId of liveSessionIds) {
+        if (!livePtys.has(sessionId))
+            orphanLiveSessionsNoMaster++;
+    }
+    let archivedSessions = 0;
+    for (const sessionId of livePtys.keys())
+        if (deps.isArchived(sessionId))
+            archivedSessions++;
+    const summary = {
+        archivedSessions,
+        orphanMasters: archivedWithMaster,
+        liveTrackers: livePtys.size,
+        liveSessions: liveSessionSet.size,
+        archivedWithMaster,
+        orphanLiveSessionsNoMaster,
+        escalated,
+    };
+    deps.logger(`[fd-audit] op=post-archive-sweep archivedSessions=${summary.archivedSessions} orphanMasters=${summary.orphanMasters} openFds=${openFdCount()} livePtys=${summary.liveTrackers}`);
+    deps.logger(`[fd-audit] op=master-reconcile liveTrackers=${summary.liveTrackers} liveSessions=${summary.liveSessions} archivedWithMaster=${summary.archivedWithMaster} orphanLiveSessionsNoMaster=${summary.orphanLiveSessionsNoMaster}`);
+    return summary;
+}
+/** Task 557 — register an rc-spawn PTY in the live tracker map so the
+ *  master fd has a defined owner and release path. Mirrors the tracker
+ *  shape `spawnClaudeSession` writes (Task 260), but skips the spawn
+ *  pipeline's sidecar/watcher/url-capture concerns — `/rc-spawn` is
+ *  fire-and-forget; claude registers itself with claude.ai/code as a
+ *  Remote Control entry without manager-side bookkeeping. The `pty.onExit`
+ *  hook lands on `handlePtyNaturalExit`, which marks the tracker exited,
+ *  releases the fd, and deletes the entry — closing the leak gap the
+ *  Task 552 non-PTY scope path created when it stopped registering a
+ *  tracker at all. */
+export function registerRcSpawnPty(deps, sessionId, pty, unitToken) {
+    const tracker = {
+        sessionId,
+        bridgeSessionId: `session_${sessionId}`,
+        bridgeSuffix: sessionId,
+        pid: pty.pid,
+        pty,
+        exited: false,
+        fdReleased: false,
+        hidden: false,
+        specialist: null,
+        scopeUnitToken: unitToken,
+    };
+    livePtys.set(sessionId, tracker);
+    trackerRegisteredAt.set(sessionId, Date.now());
+    deps.logger(`[pty-tracker] op=spawn sessionId=${sessionId.slice(0, 8)} pid=${pty.pid} size=${livePtys.size}`);
+    pty.onExit((e) => {
+        handlePtyNaturalExit(deps, tracker, e, '');
+    });
+    return tracker;
+}
+/** Task 558 — the rc-spawn `op=fd-release trigger=session-ready` path
+ *  (Task 557) is gone: the master IS the live session, not a reclaimable
+ *  spawn artifact. The tracker is now released only by `handlePtyNaturalExit`
+ *  (the slave exited on its own) or by `stopSession`'s `op=archive-release`
+ *  (operator teardown). This export remains only because tests under
+ *  `__tests__/` reach for it directly; its body is the same idempotent
+ *  release-and-detach, called solely from those tests. Once those tests
+ *  switch to the `op=archive-release` shape (Task 558 verification), this
+ *  export can go. */
+export function releaseAndUnregisterRcSpawnPty(deps, tracker, trigger) {
+    const suffix = tracker.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(tracker);
+    if (suffix === 'master-fd=closed')
+        tracker.fdReleased = true;
+    if (livePtys.get(tracker.sessionId) === tracker) {
+        livePtys.delete(tracker.sessionId);
+        trackerRegisteredAt.delete(tracker.sessionId);
+    }
+    deps.logger(`[pty-tracker] op=detach sessionId=${tracker.sessionId.slice(0, 8)} pid=${tracker.pid} trigger=${trigger} size=${livePtys.size}`);
+    return { suffix, openFds: openFdCount() };
+}
+export function writeInputToPty(sessionId, text, logger, channel) {
+    const t = livePtys.get(sessionId);
+    if (!t)
+        return { ok: false, error: 'not-found' };
+    if (t.exited)
+        return { ok: false, error: 'exited' };
+    const bytes = Buffer.byteLength(text, 'utf8');
+    // Task 122 — multi-line `text` must arrive at the TUI as one submitted
+    // turn, not as keystrokes. Claude's TUI treats embedded `\n` typed via
+    // `pty.write` as a bracketed-paste boundary that buffers and never
+    // submits. Wrapping the bytes in DEC bracketed-paste markers
+    // (\e[200~ ... \e[201~) and then sending `\r` makes the TUI treat the
+    // payload as a single paste followed by an explicit submit keystroke.
+    // Single-line text keeps the previous typed-keystroke path byte-for-byte
+    // so the Sidebar timestamp stimulus is unchanged.
+    const multiline = text.includes('\n');
+    const submitMode = multiline ? 'bracketed-paste' : 'typed';
+    try {
+        if (multiline) {
+            t.pty.write(`\x1b[200~${text}\x1b[201~\r`);
+        }
+        else {
+            t.pty.write(text + '\r');
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger(`input-failed pid=${t.pid} sessionId=${sessionId} message=${msg}`);
+        return { ok: false, error: 'write-failed', detail: msg };
+    }
+    logger(`input pid=${t.pid} sessionId=${sessionId} bytes=${bytes} channel=${channel ?? 'unknown'} multiline=${multiline} submit-mode=${submitMode}`);
+    return { ok: true, bytes };
+}
+//# sourceMappingURL=pty-spawner.js.map