create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/api/session-attach.js

@@ -0,0 +1,623 @@
+'use strict';
+
+// Landing-throughput WP-5 shard S6 (design doc §5 D-10 "move-only", §6 "Shard
+// module seam", §8 WP-6, §9 S-21..S-27): the HTTP attach handler
+// (apiAttachSession, POST /api/sessions/attach) moves out of server.js VERBATIM
+// into this module behind the same configure(deps) seam as
+// lib/api/session-messages.js (S3). It registers NO routes -- the route stays in
+// lib/api/sessions.js, whose configure() call in server.js now receives
+// sessionAttachApi.apiAttachSession. The body is identical to server.js's
+// declaration except for the `_deps.` prefix on every identifier that used to resolve
+// to a server.js top-level binding (D-10 rule 1), proven by
+// `node bin/move-only-check.js`. Four inline `require('./lib/...')` calls are rebased
+// to this module's own `require('../...')` (S1/S3 precedent: injecting server.js's
+// `require` is a loader-value transfer the public runtime closure guard refuses) -- the
+// one deviation from a pure move-only diff.
+//
+// Injected deps, per function:
+//   apiAttachSession: CTM_FLUSH_BYTE_CAP, OUTPUT_FLUSH_BULK_INPUT_MAX_BYTES,
+//     OUTPUT_FLUSH_MAX_BYTES, PORT, PROJECT_ENTRY_RE, WALLE_PORT, WorkerTurnCounter,
+//     _answerPtyDeviceQueries, _appendScrollbackOnDbOwner, _clearRestoreInterruption,
+//     _clearScrollbackOnDbOwner, _codingSessionGenerationRuntime, _destroySession,
+//     _ensureSessionOutputGapWatchdog, _executeGeometryRevokeGraceForSession,
+//     _executionLocalityEnv, _forceFlowResume, _hasBufferedBusyStatusPtyEvidence,
+//     _isActivePtyChunk, _isBusyStatusPtyChunk, _isPtyUserInputEchoActivitySuppressed,
+//     _isServerWaitingForInput, _isShuttingDown, _isStatusOnlyPtyChunk, _mainTranscriptReads,
+//     _markHeartbeatDirty, _markProviderBusyStatusEvidence, _markServerSessionResumedFromPty,
+//     _markServerSessionTurnClosed, _markServerSessionTurnEvidence, _noteTerminalBell,
+//     _parseSessionMetaBatchOffThread, _perfWrap, _prependWalleBinToSessionPath,
+//     _providerIdFromCmd, _recordPtyChunkStatus, _retireStartupTaskOnDbOwner,
+//     _samplePtyDetectionData, _scheduleSecondaryPush, _sessionHostOwnsLiveHeadless,
+//     _spawnSessionPty, _stampSpawnAgentBundle, _stripPtyOutputReplies,
+//     _suppressCtmUiRefreshActivity, _useSessionHostProcessForPty, _wheelRttSampler, _wsSend,
+//     agentSessionKernel, applyAgentBundleToSpawn, applyClaudeRestoreBakDecision,
+//     applyLaunchEffortOverride, applyLaunchModelPin, broadcastSessionList,
+//     buildClaudeRendererLaunchEnv, buildTelemetryEnv, checkAutoApproval, checkIdleNotify,
+//     cleanAutoApprovalBuffer, cleanIdleNotify, createBoundedFlushScheduler,
+//     createSessionWithStartupTaskWithRetry, crypto, dbModule, delegateWorker,
+//     ensureWalleMcpForAgentSession, formatWorkerTerminalOutput, handleCreatePrepared,
+//     headlessWorker, oauthProxySupervisor, path, planCappedOutputAppend,
+//     ptyRuntimeActivityDecision, queueEngine, recordSessionDiagnostic, resolveAgentCliCommand,
+//     resolveSpawnBundleForSession, restoreRuntime, sanitizeAnthropicAuth,
+//     sanitizeInheritedAgentEnv, serverConfig, sessionDiagnostics, sessionEvents,
+//     sessionInputAuthority, sessionPolicy, sessions, setupQueueForSession,
+//     splitMirrorAndBrowserChunks, terminalOutputFlushDelay, treeHex
+//
+// Mutable module state is injected as a GETTER (D-10 rule 2): `_isShuttingDown` is a
+// server.js `let` binding reassigned at runtime, so server.js injects
+// `get _isShuttingDown() { return _isShuttingDown; }` rather than a frozen copy.
+// No moved body assigns server.js state.
+
+let _deps = null;
+
+function configure(deps = {}) {
+  _deps = deps;
+}
+
+function apiAttachSession(req, res) {
+  let body = '';
+  req.on('data', chunk => { body += chunk; if (body.length > 1e6) req.destroy(); });
+  req.on('end', async () => {
+    try {
+      const { session_id, cwd: rawCwd } = JSON.parse(body);
+      if (!session_id) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'session_id required' }));
+        return;
+      }
+
+      if (typeof session_id !== 'string' || !_deps.PROJECT_ENTRY_RE.test(session_id) || session_id === '.' || session_id === '..') {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Invalid session_id format' }));
+        return;
+      }
+
+      const tabId = _deps.crypto.randomUUID();
+      const cwdDir = (rawCwd || _deps.serverConfig.HOME).replace(/^~/, _deps.serverConfig.HOME);
+      const env = { ...process.env, PWD: cwdDir };
+      _deps._prependWalleBinToSessionPath(env);
+      _deps.sanitizeInheritedAgentEnv(env);
+      const claudeCmd = _deps.resolveAgentCliCommand('claude');
+      _deps.sanitizeAnthropicAuth(env, claudeCmd);
+      Object.assign(env, _deps._executionLocalityEnv());
+      // Resume path: inject CTM telemetry env the same way as the create path.
+      Object.assign(env, _deps.buildTelemetryEnv(tabId, claudeCmd, _deps.PORT, env));
+      Object.assign(env, _deps.buildClaudeRendererLaunchEnv(claudeCmd, env)); // restore-seed-alt-screen-trap R-4
+      _deps.ensureWalleMcpForAgentSession({
+        cmd: claudeCmd,
+        wallePort: _deps.WALLE_PORT,
+        homeDir: env.HOME || _deps.serverConfig.HOME,
+        env,
+      });
+
+      // Restore .jsonl from .bak if needed (Claude Code migrates sessions to
+      // directory format, and an interrupted compaction can leave a live
+      // metadata-only stub while the conversation survives in .bak).
+      const claudeProjectsDir = _deps.path.join(_deps.serverConfig.HOME, '.claude', 'projects');
+      const unavailable = () => Object.assign(new Error('Session preparation is unavailable; retry shortly'), { code: 'READ_POOL_UNAVAILABLE', statusCode: 503 });
+      const entries = await _deps._mainTranscriptReads.listClaudeProjectDirectoryNames();
+      const candidates = entries.map((entry) => {
+        const livePath = _deps.path.join(claudeProjectsDir, entry, `${session_id}.jsonl`);
+        return { livePath, bakPath: `${livePath}.bak` };
+      });
+      const decisions = await _deps._mainTranscriptReads.prepareRestoreBackups(candidates, { requireAvailable: true });
+      const stats = await _deps._mainTranscriptReads.statPaths(candidates.flatMap((candidate) => [candidate.livePath, candidate.bakPath]), { requireAvailable: true });
+      if (!decisions || !stats || candidates.some((candidate) => [candidate.livePath, candidate.bakPath]
+        .some((p) => !stats.get(p) || stats.get(p).state === 'error'))) throw unavailable();
+      let chosen = null;
+      for (let i = 0; i < decisions.length; i++) {
+        const decision = decisions[i];
+        if (decision.reason === 'unavailable' || decision.live?.state === 'unavailable' || decision.bak?.state === 'unavailable') throw unavailable();
+        if (decision.eligible) {
+          const applied = await _deps.applyClaudeRestoreBakDecision(decision, { db: _deps.dbModule.getDb() });
+          // A failed apply can have renamed the stub already. Never reuse pre-apply exists=true.
+          if (!applied.restored) {
+            console.error('[attach] backup apply failed:', {
+              reason: applied.reason, errorCode: applied.errorCode || '', stubPath: applied.stubPath || '',
+            });
+            throw unavailable();
+          }
+          chosen = { filePath: decision.livePath, projectEntry: entries[i] };
+        } else if (stats.get(decision.livePath)?.exists) {
+          chosen = { filePath: decision.livePath, projectEntry: entries[i] };
+        }
+        if (chosen) break;
+      }
+
+      // Guard: `claude --resume <id>` exits 1 if the JSONL doesn't exist, which
+      // triggers an auto-restart loop with the same missing ID. Surface a clear 404
+      // instead of letting Claude Code crash. The identity row is KEPT (design D-1):
+      // vendor retention deletes transcripts, the conversation may still be stored.
+      if (!chosen) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Session JSONL not found on disk', session_id, identityKept: true }));
+        return;
+      }
+
+      // Prepare the existing DB/worker title before spawn: the new metadata await must not delay
+      // registration of the PTY's first output handler. Only the already-chosen path is parsed.
+      let label = '';
+      try {
+        const titleInfo = _deps.dbModule.getSessionTitleNew(session_id);
+        if (titleInfo && titleInfo.title) label = titleInfo.title;
+      } catch (e) { console.error('[attach] getSessionTitleNew error:', e.message); }
+      if (!label) {
+        try {
+          const results = await _deps._parseSessionMetaBatchOffThread([chosen], { metadataProfile: 'display' });
+          label = results?.find((row) => row?.filePath === chosen.filePath)?.parsed?.title || '';
+        } catch (e) { console.error('[attach] label preparation error:', e.message); }
+      }
+      if (!label) label = 'Attached: ' + session_id.slice(0, 8) + '...';
+
+      let ptyProcess;
+      const terminalOutputEpoch = _deps.crypto.randomUUID();
+      // WP-0b (design §9 S2, AC-0g): reserve BEFORE the PTY exists — a refused reservation leaves zero processes.
+      const attachLaunch = _deps._codingSessionGenerationRuntime.revalidateReservation(await _deps._codingSessionGenerationRuntime.prepareAttachedLaunch({ sessionId: tabId, providerThreadId: session_id, env }));
+      if (!attachLaunch.ok) { res.writeHead(503, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'Launch generation unavailable', session_id })); return; }
+      // WP-3 (docs/claude-resume-managed-model-pin-2026-10-16.html §6 D-7, §9 S-7): the attach path
+      // spawns outside createProviderSession, so the session's stored Claude lead-model pin is replayed
+      // here on THIS spawn's argv only. An adopted external session has no CTM row yet, so the read
+      // returns null and the argv is today's (design R-6). The `session.args` below and the startup
+      // task stay clean -- the pin is never stored.
+      // WP-2 (docs/claude-lead-model-pin-followups-2026-10-17.html §5.1 D-6b): the same spawn also
+      // replays the session's stored lead effort (`session_lead_effort`), because a plain `claude
+      // --resume` keeps neither the chosen model nor the chosen effort. The effort read has its OWN
+      // failure mode: an unreadable effort records lead-effort-read-failed and the spawn keeps the
+      // pinned argv. Neither value is persisted -- both reach this spawn's argv only.
+      // WP-4 (docs/agent-bundle-darwin-readonly-rename-2026-10-27.html §16 D-11/D-12, §17): the attach
+      // path spawns outside createProviderSession, so it applied no bundle and stamped no tree — an
+      // attached session silently ran without the hub's skills (census gap D-12). The SAME resolver,
+      // transform and diagnostic the create path uses (provider-process.js:687/:940), applied to THIS
+      // spawn's argv/env only: `session.args` below and the startup task stay clean, so a later restore
+      // re-resolves the hub's CURRENT pointer (D-7). No hub tree → null → today's argv/env byte for byte.
+      const attachBundle = await _deps.resolveSpawnBundleForSession(tabId, { report: (event, details) => _deps.recordSessionDiagnostic?.(tabId, event, details) });
+      let attachSpawnEnv = attachLaunch.env;
+      const attachSpawnArgs = (() => {
+        let args = ['--resume', session_id];
+        try {
+          if (typeof _deps.dbModule.getSessionLeadModel === 'function') {
+            args = _deps.applyLaunchModelPin({ agentType: 'claude', args: ['--resume', session_id],
+              pin: _deps.dbModule.getSessionLeadModel(tabId), env: attachLaunch.env }).args;
+          }
+        } catch (error) {
+          if (typeof _deps.recordSessionDiagnostic === 'function') _deps.recordSessionDiagnostic(tabId, 'lead-model-pin-read-failed', { message: String(error && error.message || error).slice(0, 200) });
+          /* REPORT: an unreadable pin never blocks an attach; the spawn keeps today's argv */
+        }
+        try {
+          const effort = _deps.dbModule.getSessionLeadEffort?.(tabId)?.effort;
+          if (typeof effort === 'string') args = _deps.applyLaunchEffortOverride(args, 'claude', effort).args;
+        } catch (error) {
+          if (typeof _deps.recordSessionDiagnostic === 'function') _deps.recordSessionDiagnostic(tabId, 'lead-effort-read-failed', { message: String(error && error.message || error).slice(0, 200) });
+          /* REPORT: an unreadable effort never blocks an attach; the spawn keeps the pinned argv */
+        }
+        // WP-4: pinned argv + the bundle's --add-dir is the ONE argv this spawn receives (last, after pin and effort).
+        const bundled = _deps.applyAgentBundleToSpawn({ launchArgs: args, spawnEnv: attachLaunch.env, agentType: 'claude', bundle: attachBundle }); attachSpawnEnv = bundled.spawnEnv; args = bundled.launchArgs;
+        if (bundled.applied) _deps.recordSessionDiagnostic?.(tabId, 'agent-bundle-applied', { treeHash: attachBundle.treeHash, hubPeerId: attachBundle.hubPeerId });
+        return args;
+      })();
+      try {
+        ptyProcess = _deps._spawnSessionPty({
+          sessionId: tabId,
+          cmd: claudeCmd,
+          args: attachSpawnArgs,
+          cols: 120,
+          rows: 30,
+          cwd: cwdDir,
+          env: attachSpawnEnv,
+          outputEpoch: terminalOutputEpoch,
+        });
+      } catch (e) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Failed to spawn: ' + e.message }));
+        return;
+      }
+
+      const attachedSessionSpawnedAt = Date.now();
+      const session = {
+        id: tabId,
+        ...attachLaunch.owner,
+        label,
+        cmd: 'claude',
+        args: ['--resume', session_id],
+        cwd: cwdDir,
+        pid: ptyProcess.pid,
+        ptyProcess,
+        // WI-3 (resume-grid-mismatch-render-churn): see the primary spawn site's comment.
+        _ptySpawnedAt: attachedSessionSpawnedAt,
+        clients: [],
+        // scrollback removed — headless terminal is source of truth (Phase 3D)
+        createdAt: attachedSessionSpawnedAt,
+        lastActivity: attachedSessionSpawnedAt,
+        lastPtyActivity: 0,
+        _ptyCols: 120,
+        _ptyRows: 30,
+        model_id: null,
+        model_provider: null,
+        _autoRestartCount: 0,
+        _terminalOutputEpoch: terminalOutputEpoch,
+      };
+      // WP-3/D-11, applied here by WP-4: the SAME spawn stamp the create path applies, so an attached
+      // session's bundle truth reaches the drift reconciler and `_sessionPayload.agentBundle` (and the
+      // store GC's live-set) exactly like a created one's. `treeHex` of a null bundle is null.
+      _deps._stampSpawnAgentBundle({ session, agentBundleTreeHash: _deps.treeHex(attachBundle?.treeHash) });
+
+      _deps.sessions.set(tabId, session);
+      _deps.sessionInputAuthority.observeProvider({ sessionId: tabId, status: 'ready' });
+      if (typeof ptyProcess.onStarted === 'function') {
+        ptyProcess.onStarted((started = {}) => {
+          session.pid = started.pid || session.pid || ptyProcess.pid;
+          session._hostPid = ptyProcess.hostPid || null;
+          _deps.broadcastSessionList(true, { reason: 'attach-started' });
+        });
+      }
+
+      // Create headless terminal for legacy PTYs. Hosted PTYs create their
+      // embedded headless terminal inside the child process before the PTY
+      // starts, so the primary process must not send a second create that could
+      // reset early output.
+      if (!_deps._sessionHostOwnsLiveHeadless(tabId)) {
+        _deps.headlessWorker.postMessage({ type: 'create', sessionId: tabId, cols: 120, rows: 30, outputEpoch: terminalOutputEpoch });
+      }
+
+      // Durable restore identity for crash-safe restore: the startup_tasks row AND the
+      // ctm_sessions/agent_sessions rows in ONE transaction, through the same helper the ordinary
+      // create path uses (lib/session-create/provider-process.js:1394). The attach route used to
+      // write ONLY the startup task, so an API-only attached tab had no agent_sessions owner row for
+      // the provider thread it actually resumed and every owner-keyed durable store refused it on its
+      // own read (lib/storage/coding-session-model-store.js's bind -> ownerRow requires the exact
+      // ctm_session_id + agent_session_id + provider tuple) -- the attached session could never
+      // publish durable model state.
+      // The identity is the REAL provider thread this child was launched with (`--resume session_id`),
+      // never the CTM tab UUID: the tab id is only the ctm_session_id. Fire-and-forget on purpose --
+      // the promise is exposed on the live session exactly like the create path's
+      // `session._startupPersistence`, and nothing is awaited between the spawn above and the
+      // onData/onExit registration below, which would risk losing early PTY bytes.
+      session._startupPersistence = _deps.createSessionWithStartupTaskWithRetry({
+        sessionId: tabId,
+        label,
+        cmd: 'claude',
+        args: ['--resume', session_id],
+        cwd: cwdDir,
+        sessionData: {
+          agentSessionId: session_id,
+          provider: 'claude',
+          cwd: cwdDir,
+          title: label,
+          projectEntry: chosen.projectEntry,
+          projectPath: cwdDir,
+        },
+      });
+
+      // Output batching (same as main session path)
+      let outputBuf2 = '';
+      let outputBufBytes2 = 0;
+      let outputFlushTimer2 = null;
+      let headlessFeedBuf2 = '';
+      let headlessFeedTimer2 = null;
+      let _sb2Seq = 0, _sb2Pending = [], _sb2Timer = null;
+      function _flushSb2() { _sb2Timer = null; if (!_sb2Pending.length) return; const w = _sb2Pending; _sb2Pending = []; _deps._appendScrollbackOnDbOwner(tabId, w); }
+      session._flushScrollbackToDb = _flushSb2;
+      function flushHeadlessFeed2() {
+        if (headlessFeedTimer2) {
+          clearTimeout(headlessFeedTimer2);
+          headlessFeedTimer2 = null;
+        }
+        if (!headlessFeedBuf2) return;
+        const batch = headlessFeedBuf2;
+        headlessFeedBuf2 = '';
+        if (!_deps.sessions.has(tabId) || _deps.sessions.get(tabId) !== session) return;
+        if (_deps._sessionHostOwnsLiveHeadless(tabId)) return;
+        _deps.headlessWorker.postMessage({ type: 'feed', sessionId: tabId, data: batch });
+      }
+      function enqueueHeadlessFeed2(data) {
+        if (!data) return;
+        headlessFeedBuf2 += data;
+        if (!headlessFeedTimer2) headlessFeedTimer2 = setTimeout(flushHeadlessFeed2, 16);
+      }
+      session._flushHeadlessFeed = flushHeadlessFeed2;
+      function flushOutput2() {
+        if (_deps.CTM_FLUSH_BYTE_CAP && outputFlushTimer2) clearTimeout(outputFlushTimer2);
+        outputFlushTimer2 = null;
+        if (!outputBuf2) return;
+        const batch = outputBuf2;
+        outputBuf2 = '';
+        outputBufBytes2 = 0;
+        _sb2Pending.push({ seq: _sb2Seq++, data: batch }); _deps.sessionEvents.emit('session:tail-dirty', { id: tabId });
+        if (!_sb2Timer) _sb2Timer = setTimeout(_flushSb2, 1000);
+        // State-sync delivers these bytes via the next 'frame' (the worker mirror, fed via
+        // enqueueHeadlessFeed2 / the session host, already holds them). Scrollback is persisted above;
+        // secondary viewers get a reflowed snapshot below.
+        // Render secondary viewers at their own width from a debounced reflowed
+        // snapshot (no-op + free when there are no secondaries).
+        if (_deps.serverConfig.CTM_DEBUG_SECPUSH) console.warn(`[flushout] ${tabId.slice(0,6)} hasSecondary=${!!session._hasSecondaryViewers} clients=${session.clients.length}`);
+        if (session._hasSecondaryViewers) _deps._scheduleSecondaryPush(session, tabId, 'output');
+      }
+      function flushForcedOutput2(batch) {
+        if (!batch) return;
+        const pending = outputBuf2;
+        const pendingBytes = outputBufBytes2;
+        const pendingTimer = outputFlushTimer2;
+        outputBuf2 = batch;
+        outputBufBytes2 = Buffer.byteLength(batch, 'utf8');
+        outputFlushTimer2 = null;
+        try {
+          flushOutput2();
+        } finally {
+          outputBuf2 = pending;
+          outputBufBytes2 = pendingBytes;
+          outputFlushTimer2 = pendingTimer;
+        }
+      }
+      const cappedFlushScheduler2 = _deps.createBoundedFlushScheduler({
+        flush: flushForcedOutput2,
+        onIdle: () => {
+          if (outputBuf2 && !outputFlushTimer2) {
+            outputFlushTimer2 = setTimeout(
+              flushOutput2,
+              _deps.terminalOutputFlushDelay(outputBuf2, session),
+            );
+          }
+        },
+      });
+
+      const attachedPtyDataHandler = _deps._perfWrap(`pty:onData:${tabId.slice(0, 8)}`, (data) => {
+        _deps._wheelRttSampler.onOutput(tabId);
+        const now = Date.now();
+        // RAW output recency for the mid-stream resize guard (_ptyOutputInFlight) —
+        // unfiltered on purpose; see the matching stamp in the queued onData path.
+        session._lastRawPtyOutputAt = now;
+        _deps._ensureSessionOutputGapWatchdog(session, tabId)?.notePtyOutput(
+          now,
+          Buffer.byteLength(String(data || ''), 'utf8'),
+        );
+        _deps._markHeartbeatDirty(session);
+        _deps._answerPtyDeviceQueries(session, tabId, data, 'feed-attached');
+        const rawTerminalData = _deps._stripPtyOutputReplies(session, tabId, data, 'feed-attached');
+        // Count raw worker turns before projection, then schedule progress checkpoints
+        // (spark-worker-latency-prompt-diet §8 WP-3).
+        if (session.agentRole === 'worker') {
+          session._workerTurnCounter ||= new _deps.WorkerTurnCounter({ agent: session._workerAgent });
+          if (session._workerTurnCounter.feed(rawTerminalData)) session._workerTurnCount = session._workerTurnCounter.count;
+          _deps.delegateWorker.scheduleWorkerObservation(session.id, session);
+        }
+        const terminalData = _deps.formatWorkerTerminalOutput(session, rawTerminalData);
+        // A BEL that terminates a stripped color reply is not an approval signal.
+        _deps._noteTerminalBell(tabId, session, terminalData);
+        const detectionData = _deps._samplePtyDetectionData(terminalData);
+        const activeChunk = _deps._isActivePtyChunk(session, detectionData);
+        const statusOnlyChunk = _deps._isStatusOnlyPtyChunk(session, detectionData);
+        const busyStatusChunk = _deps._isBusyStatusPtyChunk(session, detectionData);
+        const busyStatusEvidenceChunk = busyStatusChunk || _deps._hasBufferedBusyStatusPtyEvidence(session, detectionData, now);
+        const waitingForInput = _deps._isServerWaitingForInput(tabId, session);
+        const suppressedUiRefreshChunk = _deps._suppressCtmUiRefreshActivity(session, statusOnlyChunk);
+        const restoreActivitySuppressed = _deps.restoreRuntime.restoreActivitySuppressed(session, now);
+        const suppressedInputEchoChunk = _deps._isPtyUserInputEchoActivitySuppressed(session, detectionData, {
+          statusOnlyChunk,
+          busyStatusChunk,
+        });
+        if (busyStatusEvidenceChunk && !restoreActivitySuppressed && !suppressedInputEchoChunk) {
+          _deps._markProviderBusyStatusEvidence(
+            tabId,
+            session,
+            now,
+            suppressedUiRefreshChunk ? 'attached-pty-ui-refresh' : 'attached-pty'
+          );
+        }
+        const { activityChunk, runtimeActivityChunk } = _deps.ptyRuntimeActivityDecision({
+          activeChunk,
+          statusOnlyChunk,
+          busyStatusChunk,
+          waitingForInput,
+          suppressedUiRefreshChunk,
+          suppressedInputEchoChunk,
+          restoreActivitySuppressed,
+        });
+        if (busyStatusChunk && waitingForInput && !restoreActivitySuppressed && !suppressedInputEchoChunk) {
+          const providerId = session?._providerId || _deps._providerIdFromCmd(session?.cmd || '') || 'provider';
+          _deps._markServerSessionResumedFromPty(tabId, session, `${providerId}-busy-status`);
+        }
+        _deps._recordPtyChunkStatus(session, detectionData, {
+          now, waitingForInput, suppressedUiRefreshChunk, suppressedInputEchoChunk, restoreActivitySuppressed,
+        });
+        if (runtimeActivityChunk) {
+          session.lastActivity = now;
+          session.lastPtyActivity = now;
+          if (session._activeTurnOpen) _deps._markServerSessionTurnEvidence(session, now, 'attached-pty-activity', { ledger: false });
+          _deps.restoreRuntime.clearRestoreState(session);
+          _deps._clearRestoreInterruption(session, now, 'attached-pty-activity');
+        }
+        // TWO feeds, one chunk -- the same shared split as the primary feed site in
+        // lib/session-create/response.js. `mirrorData` feeds the headless MIRROR, the authority for
+        // the app's mouse-tracking mode (R-2) and therefore the one copy that must keep the
+        // ?1000/?1002/?1003/?1006/?1015 enables; `cleanData` feeds the BROWSER and is byte-identical
+        // to the pre-change computation (R-10). See splitMirrorAndBrowserChunks for why the
+        // transform order matters.
+        const { mirror: mirrorData, browser: cleanData } = _deps.splitMirrorAndBrowserChunks(
+          terminalData,
+          session.cmd || '',
+        );
+        if (!_deps.CTM_FLUSH_BYTE_CAP) {
+          outputBuf2 += cleanData;
+          if (!outputFlushTimer2) {
+            outputFlushTimer2 = setTimeout(flushOutput2, _deps.terminalOutputFlushDelay(cleanData, session));
+          }
+        } else if (cleanData) {
+          const bulkInputActive = Number(session._codexComposerBulkInputUntil || 0) > now;
+          const byteCap = bulkInputActive
+            ? _deps.OUTPUT_FLUSH_BULK_INPUT_MAX_BYTES
+            : _deps.OUTPUT_FLUSH_MAX_BYTES;
+          const appendPlan = _deps.planCappedOutputAppend(outputBuf2, cleanData, byteCap, outputBufBytes2);
+          if (appendPlan.flushes.length) {
+            if (outputFlushTimer2) clearTimeout(outputFlushTimer2);
+            outputFlushTimer2 = null;
+            cappedFlushScheduler2.enqueue(appendPlan.flushes);
+          }
+          outputBuf2 = appendPlan.pending;
+          outputBufBytes2 = appendPlan.pendingBytes;
+          if (outputBuf2 && !cappedFlushScheduler2.pending && !outputFlushTimer2) {
+            outputFlushTimer2 = setTimeout(flushOutput2, _deps.terminalOutputFlushDelay(cleanData, session));
+          }
+        }
+
+        if (!_deps._sessionHostOwnsLiveHeadless(tabId)) enqueueHeadlessFeed2(mirrorData);
+        // Mark cache stale on output (matches the primary feed site).
+        if (cleanData && cleanData.length) session._cachedSnapshotDirty = true;
+
+        // Feed output to queue engine for completion detection
+        _deps.queueEngine.feedOutput(tabId, detectionData);
+
+        // Feed output to auto-approval engine
+        _deps.checkAutoApproval(tabId, session, detectionData);
+
+        // Feed output to idle/waiting-for-input detection
+        _deps.checkIdleNotify(tabId, session, detectionData);
+      });
+      ptyProcess.onData(attachedPtyDataHandler);
+
+      // WP-1 §6.6 item 2: the owner + cleanup FACTORY are captured BEFORE this handler is installed
+      // (see lib/session-create/native-lead-server-wiring.js); the handler passes its FULL event through it.
+      const exitLeadOwner = require('../session-create/native-lead-server-wiring').captureExitLeadOwner(session);
+      const leadRouteCleanup = require('../session-create/native-lead-server-wiring').createLeadRouteCleanupForSession({ session, sessionId: session.id, ownership: session._leadRouteTokenOwnership, hosted: () => _deps._useSessionHostProcessForPty() === true });
+      ptyProcess.onExit(async (exitEvent) => {
+        const { exitCode, signal } = exitEvent || {};
+        _deps.sessionInputAuthority.observeProvider({ sessionId: tabId, status: 'exited' });
+        if (session.agentRole === 'worker') attachedPtyDataHandler('\n');
+        if (outputFlushTimer2) { clearTimeout(outputFlushTimer2); flushOutput2(); }
+        if (_sb2Timer) { clearTimeout(_sb2Timer); _flushSb2(); }
+        _deps._forceFlowResume(session, tabId, 'pty-exit');
+        // WP-2 (D-1, S-16): don't let a grace-deferred geometry revoke outlive the PTY it was
+        // guarding ownership of.
+        _deps._executeGeometryRevokeGraceForSession(tabId);
+        // WP-2 (delegated-implementation-workers-2026-09-24.html §5 D-7, §9 S-13): revoke a
+        // worker session's proxy token on PTY exit -- best-effort, never blocks teardown.
+        if (session.agentRole === 'worker' && session._workerToken) {
+          _deps.oauthProxySupervisor.revokeWorkerToken(session._workerToken).catch(() => { /* expected: best-effort token revoke on PTY exit -- an unreachable/already-down proxy must never block session teardown */ });
+        } else if (session.agentRole !== 'worker') {
+          // §6.6 item 2/§6.11: the FULL event goes through the captured factory BEFORE the park/shutdown
+          // early returns below; a hosted synthetic/unknown event revokes the exact owner and keeps files.
+          await require('../session-create/native-lead-lifetime').runLeadRouteLifetimeCleanup(leadRouteCleanup, exitEvent, { reason: 'pty-exit' });
+          // WP-4 D-8: drop the exited lead from the pick table (inline require: may run before the module-level const).
+          require('../session-create/subagent-pick-table').forget(session.id, exitLeadOwner)
+            .catch(() => { /* expected: subagent-pick-table forget never rejects -- it reports its own failures */ });
+        }
+        // Lifecycle WP-4 (delegated-worker-lifecycle-identity-observability-2026-09-27.html
+        // §5 D-7, §9 S-20): release this worker's admission slot -- and, on a 429 ending,
+        // record the throttle timestamp D-7 keys admission decisions off -- on every worker
+        // exit, attached-path or create-path (response.js has the twin call), regardless of
+        // `_isShuttingDown` below (a shutdown-time exit must still free the slot for the next
+        // process to admit correctly).
+        _deps.delegateWorker.releaseAdmissionOnExit(session, exitCode);
+        // Lifecycle WP-5 (delegated-worker-lifecycle-identity-observability-2026-09-27.html
+        // §5 D-10, §9 S-16): stamp terminal_at/terminal_status/failure_json (once) and arm
+        // the D-10 retirement timer -- right after the existing token revoke + admission
+        // release above, on every worker exit (attached path; response.js's create-path
+        // exit handler has the twin call), regardless of `_isShuttingDown` below (a
+        // shutdown-time exit must still schedule the hide so a worker that exited just
+        // before a restart isn't retained forever by a lost in-memory timer -- the boot
+        // re-arm below picks it back up from the persisted hide_at either way).
+        // getWorkerStatus derives its status off session._exitCode, not this closure's own
+        // `exitCode` param, so that has to be stamped here too -- harmless: the SAME
+        // assignment happens again, unconditionally, a few lines further down (line ~39135)
+        // once this early-return window has passed.
+        session._exitCode = exitCode; session._exitSignal = signal ?? null;
+        _deps.delegateWorker.retireWorkerOnExit(session);
+        if (_deps._isShuttingDown) return;
+
+        // A delegated worker's exit is terminal, never an interactive --resume auto-restart: a worker
+        // continuation does launch `-p --resume` / `exec resume`, but relaunching it here would start an
+        // INTERACTIVE session under the worker's identity, stuck at worker-status `starting`
+        // (lib/session-class.js: relaunchFromRestore=false). Stamp session._exitCode unconditionally
+        // (every exit path benefits) so delegate-worker.js's getWorkerStatus can derive 'failed' from it.
+        const isWorkerSession = session.agentRole === 'worker';
+        session._exitCode = exitCode; session._exitSignal = signal ?? null;
+
+        // Crash recovery for attached sessions (always Claude --resume)
+        const isCrash = !session._intentionalKill && exitCode !== 0;
+        const maxAutoRestarts = 3;
+        const restartCount = session._autoRestartCount || 0;
+        const shouldAutoRestart = _deps.sessionPolicy(session).relaunchFromRestore && isCrash && restartCount < maxAutoRestarts;
+
+        const payload = JSON.stringify({ type: shouldAutoRestart ? 'restarting' : 'exit', id: tabId, exitCode, signal });
+        for (const client of session.clients) {
+          if (client.readyState === 1) _deps._wsSend(client, payload);
+        }
+
+        if (shouldAutoRestart) {
+          console.log(`  Attached session ${tabId.slice(0, 8)} crashed (exit ${exitCode}) — auto-restarting (attempt ${restartCount + 1}/${maxAutoRestarts})...`);
+          const delay = Math.min(2000 * Math.pow(2, restartCount), 15000);
+          session._restartTimer = setTimeout(async () => {
+            // C-4: this teardown is immediately followed by a relaunch of the SAME
+            // tabId (handleCreatePrepared below) -- unlike the final-exit branch further
+            // down, the session-runtime aggregate must survive so the crashed session's
+            // attached viewers stay attached across the auto-restart instead of being
+            // dropped until they reconnect from scratch.
+            await _deps._destroySession(tabId, 'process-teardown', { retireRuntime: false });
+            _deps.queueEngine.onSessionExit(tabId);
+            _deps.cleanAutoApprovalBuffer(tabId);
+            _deps.cleanIdleNotify(tabId);
+            try {
+              // WP-2 (docs/claude-lead-model-pin-followups-2026-10-17.html §5.1 D-6a, §9 WP-2): this
+              // relaunch of an EXISTING session is a RESTORE, not a create -- the same shape the in-session
+              // auto-restart uses (lib/session-create/response.js:1180-1181). `_isRestore: true` makes
+              // provider-process replay the stored Claude lead-model pin AND the stored session lead effort
+              // on THIS spawn's argv (lib/session-create/provider-process.js:813, :826) and skips the
+              // startup_tasks re-insert whose created_at would otherwise be reset (provider-process.js:1373).
+              // Neither value is persisted: the ladder rebinds launchArgs only, never `args`.
+              await _deps.handleCreatePrepared(null, {
+                id: tabId,
+                title: session.title || session.label,
+                label: session.title || session.label,
+                cmd: 'claude',
+                args: ['--resume', session_id],
+                cwd: cwdDir,
+                _isRestore: true,
+                _ctmOriginalCreatedAt: session._ctmOriginalCreatedAt || session.createdAt,
+                _autoRestartCount: restartCount + 1,
+              });
+              console.log(`    ✓ Restarted attached session ${tabId.slice(0, 8)}`);
+            } catch (e) {
+              console.log(`    ✗ Restart failed: ${e.message}`);
+              _deps.broadcastSessionList(true, { reason: 'attach-restart-failed' });
+            }
+          }, delay);
+          return;
+        }
+
+        _deps._markServerSessionTurnClosed(session, Date.now(), 'attached-session-exit');
+        // A worker session keeps its in-memory row (deleteSession:false) so a caller
+        // polling worker-status right after this exit still finds session._exitCode --
+        // deleting it here would collapse getWorkerStatus's `!session` branch back to
+        // 'exited'/row-existence, which can't distinguish a genuine failure from a
+        // clean teardown. Cleanup of a stale worker session's memory footprint is the
+        // same tradeoff the crash-restart branch above already makes with
+        // retireRuntime:false; a worker session's lifetime is bounded (one trial run).
+        await _deps._destroySession(tabId, 'process-teardown', isWorkerSession ? { deleteSession: false } : undefined);
+        _deps.agentSessionKernel.forgetSession(tabId);
+        _deps.sessionDiagnostics.clear(tabId); // WP-3/S2: session fully retired -- ring must not outlive it
+        _deps._retireStartupTaskOnDbOwner(tabId, 'attached-session-exit').catch(() => {});
+        _deps._clearScrollbackOnDbOwner(tabId).catch(() => {});
+        _deps.queueEngine.onSessionExit(tabId);
+        _deps.cleanAutoApprovalBuffer(tabId);
+        _deps.cleanIdleNotify(tabId);
+        _deps.broadcastSessionList(true, { reason: 'attach-exit' });
+      });
+
+      // Wire up queue engine hooks if a queue exists for this session
+      _deps.setupQueueForSession(tabId);
+
+      _deps.broadcastSessionList(true, { reason: 'attach-created' });
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, tab_id: tabId, session_id }));
+    } catch (e) {
+      const status = e.statusCode || 500;
+      res.writeHead(status, { 'Content-Type': 'application/json', ...(status === 503 ? { 'Retry-After': '2' } : {}) });
+      res.end(JSON.stringify({ error: e.message, ...(status === 503 ? { retry: true } : {}) }));
+    }
+  });
+}
+
+module.exports = {
+  configure,
+  apiAttachSession,
+};