create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/session-park.js

@@ -0,0 +1,738 @@
+'use strict';
+
+// Landing-throughput WP-6 shard S12 (design doc §5 D-10 "move-only", §6 "Shard module
+// seam"): the session-park cluster (parkSession + its five private helpers) moves out of
+// server.js VERBATIM into this module behind the same configure(deps) seam as
+// lib/api/session-attach.js and lib/terminal-attach-geometry.js (S6), lib/walle-history-serve.js
+// (S8), lib/codex-rollout-history.js (S9), lib/terminal-input-prepared.js (S10) and
+// lib/idle-notify.js (S11). It registers NO route and NO socket handler: server.js keeps the
+// pass-through call sites as sessionPark.parkSession(...) (plus sessionPark._lifecycleProcessGroupId
+// in _signalLifecycleProcessGroup's default parameter), and this configure() seam.
+// Bodies are identical to server.js declarations 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('./...')` (S8 precedent: one move-only DIFF per rebased require -- the
+// remainder is proven by re-running against a copy with
+// `sed "s#require('\./#require('./lib/#g"` applied).
+//
+// The module deliberately lives at lib/session-park.js and NOT under lib/ws/: parkSession is
+// the session-park transaction, not a ws-router handler.
+//
+// Injected deps, per function:
+//   _prepareLifecycleTranscript: _heartbeatTokenPath, _lifecycleResumeTarget, _mainTranscriptReads, detectAgentType, resumeTranscriptPaths, sessions
+//   _verifyLifecycleTranscriptPhysical: readRestoreFileFingerprint, resumeTranscriptPaths
+//   _lifecycleTranscriptStat: _mainTranscriptReads, resumeTranscriptPaths
+//   _auditParkedProcessGroup: _lifecycleOrphanEvents, _lifecycleOrphanGroups, _sessionResourceSampler, recordSessionDiagnostic
+//   _lifecycleProcessGroupId: (none)
+//   parkSession: SESSION_TRANSCRIPT_TRASH_ROOT, _RESTORE_STORM_GRACE_MS, _applyPersistedSnapshotToPlaceholder, _broadcastLifecyclePressureStatus, _codingSessionModelRuntime, _connectedLifecycleClientCount, _createDeferredRestoreSession, _destroySession, _dropDeferredRuntimeInputs, _getHeadlessRows, _lastLifecycleRelief, _lifecycleConfig, _lifecycleDiagnostics, _lifecycleJournalGate, _lifecycleJournalHost, _lifecyclePressure, _lifecycleResumeTarget, _lifecycleVisibilityGrace, _liveLifecycleSessions, _promoteDeferredRuntimeInputs, _readScrollbackSnapshotForRestoreAsync, _restoreCompletedAt, _restoreInProgress, _sampleLifecycleResources, _scheduleDeferredRestoreStart, _sessionLifecycleView, _sessionResourceSampler, _signalLifecycleProcessGroup, _snapshotSessionScrollbackToFile, _waitForLifecycleExit, _writeLifecyclePty, _wsSend, agentSessionKernel, armParkFollowup, broadcastSessionList, broadcastToSession, canResumeAgent, cleanAutoApprovalBuffer, cleanIdleNotify, copyWorkerMarkers, createParkAttemptRecorder, dbModule, detectAgentType, drainDeferredInputs, errorSink, evaluateManualPark, evaluatePark, getResumeSpec, getSession, matchesSessionModelParkPrecondition, parkedSessionMessage, readComposerDraft, recordSessionDiagnostic, restoreRuntime, sendDeferredRestoreStatus, sessionDiagnostics, sessionInputAuthority, sessionPolicy, sessions
+//
+// Mutable module state (D-10 rule 2 / S9 lesson 7): _restoreInProgress and _restoreCompletedAt are
+// server.js `let`s reassigned during boot/restore, so they are injected as GETTERS -- never
+// copies. TWO moved bodies WRITE a server.js binding: parkSession assigns _lastLifecycleRelief
+// (inside the park-followup onFollowup callback) and _auditParkedProcessGroup increments
+// _lifecycleOrphanEvents, so both are injected as a GET/SET pair. Every other dep is a by-value
+// reference. Calls between the six moved functions stay direct (no `_deps.`).
+
+let _deps = null;
+
+function configure(deps = {}) {
+  _deps = deps;
+}
+
+async function _prepareLifecycleTranscript(session) {
+  const unavailable = () => Object.assign(new Error('Lifecycle transcript preparation is unavailable'), {
+    code: 'transcript_preparation_unavailable', statusCode: 503,
+  });
+  const agentType = _deps.detectAgentType(session?.cmd || '');
+  const runtimePath = String(
+    session?.jsonlPath || _deps._heartbeatTokenPath(session, agentType) || '',
+  ).trim();
+  let candidates = _deps.resumeTranscriptPaths([
+    session?._resumeTranscriptPath,
+    runtimePath,
+  ]);
+  const resumeId = _deps._lifecycleResumeTarget(session, agentType);
+  let codexRolloutPath = '';
+  let codexStateUnavailable = false;
+  if (agentType === 'codex' && resumeId) {
+    const codex = await _deps._mainTranscriptReads.prepareCodexLink({
+      threadId: resumeId, ctmSessionId: session.id, liveAgentSessionId: session._claudeSessionId || '',
+      cwd: session.cwd || '', createdAtMs: session._ctmOriginalCreatedAt || session.createdAt || '',
+      liveCtmSessionIds: [..._deps.sessions.keys()],
+    });
+    if (!codex) throw unavailable();
+    codexRolloutPath = String(codex.resolved?.rolloutPath || '').trim();
+    codexStateUnavailable = codex.status === 'state_db_unavailable' && !codexRolloutPath;
+    candidates = _deps.resumeTranscriptPaths([candidates, codexRolloutPath]);
+  }
+  if (candidates.length > 3) throw unavailable();
+  const rows = await _deps._mainTranscriptReads.statPaths(candidates, { requireAvailable: true });
+  if (!(rows instanceof Map)) throw unavailable();
+  for (const p of candidates) {
+    const row = rows.get(p);
+    if (!row || !['plain', 'archived', 'trashed', 'missing'].includes(row.state)
+      || typeof row.exists !== 'boolean' || row.exists !== (row.state !== 'missing')
+      || row.size < 0 || !['size', 'mtimeMs', 'birthtimeMs'].every((key) => Number.isFinite(row[key]))) throw unavailable();
+  }
+  const found = candidates.find((p) => rows.get(p).exists);
+  if (!found && codexStateUnavailable) throw unavailable();
+  const row = found ? rows.get(found) : null;
+  const transcript = { filePath: found || candidates[0] || '', size: row?.size || 0,
+    mtimeMs: row?.mtimeMs || 0, modifiedAt: row ? new Date(Math.round(row.mtimeMs)).toISOString() : '',
+    missing: !found, unknown: false, candidates };
+  return { rows, candidates, transcript, codexRolloutPath };
+}
+
+async function _verifyLifecycleTranscriptPhysical(prepared) {
+  // Narrow mutation verification only: the existing writer-owned physical fingerprint API
+  // never waits for a worker, consults manifests or parses/decodes transcript content.
+  const candidates = _deps.resumeTranscriptPaths(prepared.candidates);
+  let physical = null;
+  let retainedArchive = null;
+  let diagnostic = prepared.transcript;
+  let unknown = false;
+  for (const p of candidates) {
+    const prior = prepared.rows.get(p);
+    let observed;
+    try { observed = await _deps.readRestoreFileFingerprint(p); }
+    catch { observed = { state: 'unavailable' }; /* expected: unavailable physical evidence cannot authorize fresh */ }
+    if (observed.state === 'file') {
+      if (!physical) physical = { filePath: p, size: observed.size, mtimeMs: observed.mtimeMs,
+        modifiedAt: new Date(Math.round(observed.mtimeMs)).toISOString() };
+    } else if (observed.state === 'missing') {
+      if (!retainedArchive && prior?.exists && ['archived', 'trashed'].includes(prior.state)) {
+        retainedArchive = { filePath: p, size: prior.size, mtimeMs: prior.mtimeMs,
+          modifiedAt: new Date(Math.round(prior.mtimeMs)).toISOString() };
+      }
+    } else {
+      unknown = true;
+    }
+    if (prior?.exists && (!diagnostic || diagnostic.missing)) {
+      diagnostic = { filePath: p, size: prior.size, mtimeMs: prior.mtimeMs,
+        modifiedAt: new Date(Math.round(prior.mtimeMs)).toISOString() };
+    }
+  }
+  const found = physical || retainedArchive;
+  if (unknown) return { ...(found || diagnostic), missing: false, unknown: true, candidates };
+  if (found) return { ...found, missing: false, unknown: false, candidates };
+  return { filePath: candidates[0] || '', size: 0, mtimeMs: 0, modifiedAt: '', missing: true, unknown: false, candidates };
+}
+
+async function _lifecycleTranscriptStat(prepared) {
+  const candidates = _deps.resumeTranscriptPaths(prepared?.candidates || []);
+  const unavailable = () => ({ filePath: prepared?.transcript?.filePath || candidates[0] || '',
+    size: Number(prepared?.transcript?.size || 0), mtimeMs: 0, missing: false, unknown: true, candidates });
+  if (!candidates.length) {
+    // No candidate path exists at all, so there is nothing the at-signal re-check could observe
+    // appearing or mutating. An adopted session can also lack a known transcript path:
+    // `_resumeTranscriptPath` comes from create-path preflight, which host adoption skips, and
+    // its other runtime/durable path fields can be empty. This is a verdict about the fixed
+    // candidate set; the native resume identity and normal snapshot/signal guards still apply.
+    // `_verifyLifecycleTranscriptPhysical` already
+    // reached this same verdict (`missing: true, unknown: false`) for the identical empty set, so
+    // reporting `unknown` here would refuse a park that the physical check just authorized.
+    return { filePath: '', size: 0, mtimeMs: 0, missing: true, unknown: false, candidates: [] };
+  }
+  if (candidates.length > 3) return unavailable();
+  let rows;
+  try { rows = await _deps._mainTranscriptReads.statPaths(candidates, { requireAvailable: true }); }
+  catch { return unavailable(); }
+  if (!(rows instanceof Map)) return unavailable();
+  for (const candidate of candidates) {
+    const row = rows.get(candidate);
+    if (!row || !['plain', 'archived', 'trashed', 'missing'].includes(row.state)
+        || typeof row.exists !== 'boolean' || row.exists !== (row.state !== 'missing')
+        || !Number.isFinite(row.size) || row.size < 0
+        || !['mtimeMs', 'birthtimeMs'].every((key) => Number.isFinite(row[key]))) return unavailable();
+  }
+  const filePath = candidates.find((candidate) => rows.get(candidate).exists) || '';
+  const row = filePath ? rows.get(filePath) : null;
+  return { filePath: filePath || candidates[0], size: row?.size || 0,
+    mtimeMs: row?.mtimeMs || 0, missing: !filePath, unknown: false, candidates };
+}
+
+async function _auditParkedProcessGroup(sessionId, pgid, rssBeforeMB = 0, descendantPidsBefore = []) {
+  if (!pgid) return { pgid: 0, rssMB: 0, procCount: 0, pids: [] };
+  let group;
+  try {
+    group = await _deps._sessionResourceSampler.sampleProcessGroup(pgid, descendantPidsBefore);
+  } catch (error) {
+    console.warn(`[lifecycle] park-audit-failed id=${String(sessionId).slice(0, 8)} pgid=${pgid} error=${error.message}`);
+    return { pgid, rssMB: 0, procCount: 0, pids: [], auditFailed: true };
+  }
+  const orphanMB = Number(group.rssMB || 0);
+  const victimRssMB = Math.max(0, Number(rssBeforeMB || 0));
+  // D-5: rows captured by the pre-signal descendant census that are still alive but do NOT share the
+  // agent's pgid — the ones the pgid rollup is structurally blind to.
+  const survivorPids = Array.isArray(group.survivorPids) ? group.survivorPids : [];
+  if (group.procCount > 0) {
+    _deps._lifecycleOrphanGroups.set(pgid, group);
+    _deps._lifecycleOrphanEvents += 1;
+  } else {
+    _deps._lifecycleOrphanGroups.delete(pgid);
+  }
+  console.log(`[lifecycle] park-victimRssMB=${victimRssMB.toFixed(1)} park-orphanMB=${orphanMB.toFixed(1)} id=${String(sessionId).slice(0, 8)} pgid=${pgid}`);
+  if (group.procCount > 0) {
+    console.warn(`[lifecycle] park-orphan id=${String(sessionId).slice(0, 8)} pgid=${pgid} pids=${group.pids.join(',')}`);
+    _deps.recordSessionDiagnostic(sessionId, 'park-orphan', { pgid, pids: group.pids, orphanMB, victimRssMB, survivorPids });
+  } else {
+    _deps.recordSessionDiagnostic(sessionId, 'park-process-group-gone', { pgid, orphanMB: 0, victimRssMB });
+  }
+  return { ...group, victimRssMB, orphanMB };
+}
+
+function _lifecycleProcessGroupId(session) {
+  const ptyProcess = session?.ptyProcess;
+  if (ptyProcess && Object.prototype.hasOwnProperty.call(ptyProcess, 'started') && ptyProcess.started !== true) return 0;
+  const pgid = Number(ptyProcess?.pid || session?.pid || 0);
+  return Number.isInteger(pgid) && pgid > 1 ? pgid : 0;
+}
+
+async function parkSession(sessionId, options = {}) {
+  const session = _deps.getSession(String(sessionId || ''));
+  const reason = String(options.reason || 'manual').slice(0, 32);
+  // WP-2 (S-15, design doc §5 D-3): warn-tier parks now select victims with the plain idle
+  // predicate (config), not the stripped pressure-relief predicate -- labeled 'idle' here,
+  // same as the idle/freeze-expired lanes, so a journal reader sees which predicate actually
+  // ran rather than the generic 'pressure' label critical still carries.
+  const configName = options.manual === true
+    ? 'manual'
+    : (reason === 'cap' ? 'cap' : (reason === 'idle' || reason === 'freeze-expired' || reason === 'warn' ? 'idle' : 'pressure'));
+  const journalHost = _deps._lifecycleJournalHost();
+  const recordParkAttempt = _deps.createParkAttemptRecorder({ enabled: _deps._lifecycleConfig.parkJournal });
+  const finishParkAttempt = (result, decision = null, event = null) => {
+    const eventName = event || (result?.ok && result?.alreadyParked !== true ? 'park' : 'park-refused');
+    const recorded = recordParkAttempt({
+      event: eventName,
+      id: String(session?.id || sessionId || ''),
+      reason,
+      code: result?.code || null,
+      gate: _deps._lifecycleJournalGate(session, decision, configName),
+      host: journalHost,
+      victimRssMB: Number(session?.rssMB) || 0,
+      // WP-2 (S-14 item 5): the preceding trim's freedMB, so a warn-tier park record shows
+      // whether trim had already tried and failed. Absent (null) for every other reason.
+      trim: options.trim || null,
+    });
+    if (recorded && eventName === 'park' && result?.ok && result?.alreadyParked !== true) {
+      _deps.armParkFollowup({
+        id: String(session?.id || sessionId || ''),
+        reason,
+        beforeHost: journalHost,
+        sampleHost: () => _deps._sampleLifecycleResources({ force: true }),
+        runtime: () => {
+          const liveSessions = _deps._liveLifecycleSessions();
+          return {
+            pressureLevel: _deps._lifecyclePressure.level,
+            liveCount: liveSessions.length,
+            liveRssMB: liveSessions.reduce((sum, item) => sum + Number(item.rssMB || 0), 0),
+          };
+        },
+        onFollowup: (record) => {
+          _deps._lastLifecycleRelief = {
+            at: record.at || new Date().toISOString(),
+            sessionId: String(session?.id || sessionId || ''),
+            deltaFreeMB: record.deltaFreeMB,
+            deltaSwapPct: record.deltaSwapPct,
+          };
+          _deps._broadcastLifecyclePressureStatus(true);
+        },
+      });
+    }
+    return result;
+  };
+  if (!session) return finishParkAttempt({ ok: false, code: 'session_not_found', statusCode: 404 });
+  // WP-2A: an OMITTED precondition keeps the legacy park behaviour; a PRESENT one (even an explicit
+  // null/undefined) is validated against the SAME canonical runtime's owner generation AND thread.
+  const expectedThreadId = String(options.sourceProviderThreadId || '');
+  const parkOwnerMatches = () => {
+    if (_deps.sessions.get(String(sessionId || '')) !== session || options.signal?.aborted) return false;
+    if (!_deps.matchesSessionModelParkPrecondition({ provided: Object.hasOwn(options, 'sourceGeneration'),
+      expectedGeneration: options.sourceGeneration, expectedThreadId,
+      owner: _deps._codingSessionModelRuntime?.publicFields?.(session)?.model_owner || null })) return false;
+    if (expectedThreadId) {
+      const recipeThread = session._modelExecutionRecipe?.providerThreadId || '';
+      const liveThread = _deps._lifecycleResumeTarget(session, _deps.detectAgentType(session.cmd || '')) || '';
+      if (String(recipeThread || liveThread) !== expectedThreadId) return false;
+    }
+    return true;
+  };
+  if (!parkOwnerMatches()) return finishParkAttempt({ ok: false, code: 'park_owner_changed', statusCode: 409 });
+  if (session._restoreDeferred) return finishParkAttempt({ ok: true, alreadyParked: true, sessionId: session.id });
+  if (!session.ptyProcess || session._parking) return finishParkAttempt({ ok: false, code: 'session_not_live', statusCode: 409 });
+  if (!_deps.sessionPolicy(session).parkable) return finishParkAttempt({ ok: false, code: 'session_not_parkable', statusCode: 409 });
+
+  const now = Date.now();
+  const policyConfig = options.prewarmExpiry === true
+    ? {
+      ..._deps._lifecycleConfig,
+      idleParkAfterMs: 0,
+      disconnectCollapseMs: 0,
+      parkCooldownMs: 0,
+    }
+    : (options.policyConfig || _deps._lifecycleConfig);
+  const parkDecision = (at) => {
+    const view = _deps._sessionLifecycleView(session, { now: at });
+    if (view.state === 'parking') view.state = 'live';
+    if (options.manual === true) {
+      return _deps.evaluateManualPark(
+        view,
+        { now: at, connectedClients: _deps._connectedLifecycleClientCount() },
+        _deps._lifecycleConfig,
+      );
+    } else if (options.prewarmExpiry === true) {
+      // Speculative activation must not protect itself. User intent still does.
+      view.isMru = false;
+      view.recentNonStatusActivityAt = 0;
+      view.lastActivatedAt = 0;
+    }
+    return _deps.evaluatePark(view, { now: at, connectedClients: _deps._connectedLifecycleClientCount() }, policyConfig);
+  };
+  // D-3: read the agent's own composer row immediately before the decision -- flush the mirror
+  // feed first, then the bounded read. `session._parkComposerDraft` is the verdict the decision
+  // (and the sweep's views + /api/diagnostics/lifecycle) reads.
+  session._parkComposerDraft = await _deps.readComposerDraft(session, { getRows: _deps._getHeadlessRows });
+  const decision = parkDecision(now);
+  if (!decision.eligible) {
+    const composerVerdict = session._parkComposerDraft || { state: 'unread', reason: 'none' };
+    console.log(`[lifecycle] park-refused id=${String(session.id).slice(0, 8)} reason=${reason} composer=${composerVerdict.state}/${composerVerdict.reason} protections=${decision.protections.join(',')}`);
+    return finishParkAttempt(
+      { ok: false, code: 'session_protected', statusCode: 409, protections: decision.protections, retryAt: decision.protections.includes('restore') ? _deps.restoreRuntime.restoreProtectionUntil(session, { restoreInProgress: _deps._restoreInProgress, restoreCompletedAt: _deps._restoreCompletedAt, graceMs: _deps._RESTORE_STORM_GRACE_MS }) : null },
+      decision,
+    );
+  }
+
+  const agentType = _deps.detectAgentType(session.cmd || '');
+  const resumeId = _deps._lifecycleResumeTarget(session, agentType);
+  const resumeSpec = _deps.canResumeAgent(agentType) ? _deps.getResumeSpec(agentType, resumeId) : null;
+  const deferredLaunchOwnership = require('./deferred-restore-attempt').captureDeferredRestoreLaunchOwnership(session);
+  if (session._modelExecutionRecipe && !deferredLaunchOwnership) {
+    return finishParkAttempt({ ok: false, code: 'launch_ownership_unavailable', statusCode: 409 }, decision);
+  }
+  const lifetime = { ptyProcess: session.ptyProcess, provider: session._providerId || '',
+    agentId: session._claudeSessionId || '', resumeId: session._providerResumeId || '',
+    generation: Number(session._launchPlanGeneration || 0), cmd: session.cmd, cwd: session.cwd };
+  const lifetimeMatches = (allowExitedPty = false) => _deps.getSession(session.id) === session
+    && (session.ptyProcess === lifetime.ptyProcess || (allowExitedPty && session.ptyProcess === null))
+    && (session._providerId || '') === lifetime.provider
+    && (session._claudeSessionId || '') === lifetime.agentId && (session._providerResumeId || '') === lifetime.resumeId
+    && Number(session._launchPlanGeneration || 0) === lifetime.generation && session.cmd === lifetime.cmd && session.cwd === lifetime.cwd;
+  const lifetimeCurrent = () => !session._parking && lifetimeMatches();
+  let prepared;
+  let freshSpec;
+  try {
+    prepared = await _prepareLifecycleTranscript(session);
+    freshSpec = await require('./park-fresh-relaunch').planFreshRelaunch({ session, agentType, resumeId,
+      transcript: prepared.transcript, codexRolloutPath: prepared.codexRolloutPath,
+      storedTask: _deps.dbModule.getStartupTask(session.id, { includeParked: true }),
+      resolveRung: (input) => require('./resume-from-store-client').resolveResumeRungOffThread({ ...input,
+        dbPath: _deps.dbModule.getDbPath(), trashRoot: _deps.SESSION_TRANSCRIPT_TRASH_ROOT }), diagnostic: _deps.recordSessionDiagnostic });
+  } catch (error) {
+    return finishParkAttempt({ ok: false, code: 'transcript_preparation_unavailable', statusCode: 503 }, decision);
+  }
+  if (!lifetimeCurrent()) return finishParkAttempt({ ok: false, code: 'park_lifetime_changed', statusCode: 409 }, decision);
+  if (!resumeSpec && !freshSpec) return finishParkAttempt({ ok: false, code: 'session_not_resumable', statusCode: 409 }, decision);
+  const transcriptBefore = await _verifyLifecycleTranscriptPhysical(prepared);
+  if (!lifetimeCurrent()) return finishParkAttempt({ ok: false, code: 'park_lifetime_changed', statusCode: 409 }, decision);
+  const preparedDecision = parkDecision(Date.now());
+  if (!preparedDecision.eligible) return finishParkAttempt({ ok: false, code: 'session_protected', statusCode: 409,
+    protections: preparedDecision.protections }, preparedDecision);
+  if (transcriptBefore.unknown) return finishParkAttempt({ ok: false, code: 'transcript_verification_unavailable', statusCode: 503 }, preparedDecision);
+  if (!transcriptBefore.missing && !resumeSpec) return finishParkAttempt({ ok: false, code: 'session_not_resumable', statusCode: 409 }, preparedDecision);
+  // WP-2 (docs/composer-freeze-followups-load-sigstop-attribution-2026-10-20.html §5 D-B1..D-B4): a giant rollout used to divert
+  // here into the deleted SIGSTOP "frozen" state. There is no such state any more -- the park
+  // falls through to the one kill ladder below (SIGTERM -> parkTermGraceMs -> SIGKILL).
+  const rolloutSizeBytes = Math.max(
+    0,
+    Number(session._resumeLoadingFileSize || session.fileSize || session.file_size) || 0,
+    Number(prepared.transcript?.size || 0),
+    Number(transcriptBefore.size || 0),
+  );
+
+  if (options.prewarmExpiry === true && session._prewarmExpiryTimer) {
+    clearTimeout(session._prewarmExpiryTimer);
+    session._prewarmExpiryTimer = null;
+  }
+  const pgid = _lifecycleProcessGroupId(session);
+  if (!pgid) return finishParkAttempt({ ok: false, code: 'process_group_unavailable', statusCode: 409 }, decision);
+  const rssBeforeMB = Number(session.rssMB || 0);
+  const inputGeneration = Math.max(1, Number(session._terminalLifecycleCounter || 0) + 1);
+  let resolveParkingTransition;
+  const parkingTransition = new Promise(resolve => { resolveParkingTransition = resolve; });
+  session._parking = true;
+  session._parkingPromise = parkingTransition;
+  session._parkingSignalSent = false;
+  session._parkingAbortRequested = false;
+  session._parkingInputQueue = [];
+  session._parkingInputGeneration = inputGeneration;
+  session._parkExitedAt = 0;
+  session._lifecycleState = 'parking';
+  // Register exit observation before the first park await. A provider may exit
+  // while snapshots are flushing, and that exit must complete this transaction.
+  const exitPromise = _deps._waitForLifecycleExit(session);
+  // D-4 (session-park-busy-background-shell-truth-2026-10-14): ONE ps read, the agent's descendant pid
+  // set, taken BEFORE any signal, so the post-kill audit can name survivors that lead their own process
+  // group. Placed here rather than beside `rssBeforeMB` above: this is the transaction's first await, so
+  // it must come AFTER `session._parking = true` (otherwise a re-entrant parkSession would still observe
+  // `_parking === false` and start a second transaction) and after the exit observation is registered (a
+  // provider exit during this await must still complete this transaction). Best-effort: a failed census
+  // degrades to the pgid-only rollup this audit has always done.
+  let descendantPidsBefore = [];
+  try { descendantPidsBefore = (await _deps._sessionResourceSampler.sampleDescendants(pgid)).descendantPids; }
+  catch (error) { console.warn(`[lifecycle] park-descendant-sample-failed id=${String(session.id).slice(0, 8)} pgid=${pgid} error=${error.message}`); }
+  const finishTransition = (result) => {
+    if (resolveParkingTransition) resolveParkingTransition(result);
+    resolveParkingTransition = null;
+    return result;
+  };
+  const abortBeforeSignal = (code, protections = []) => {
+    const ownsFields = session._parkingPromise === parkingTransition;
+    const sameProcess = ownsFields && lifetimeMatches() && parkOwnerMatches();
+    const queued = _deps.drainDeferredInputs(ownsFields ? session._parkingInputQueue : [], inputGeneration);
+    if (ownsFields) {
+      session._parkingInputQueue = [];
+      session._parkingAbortRequested = false;
+      session._parking = false;
+      session._parkingPromise = null;
+      session._lifecycleInputInFlight = false;
+      session._lifecycleState = session._parkExitedAt ? 'exited' : 'live';
+      session._lastActivatedAt = Date.now();
+    }
+    if (sameProcess && !session._parkExitedAt && session.ptyProcess) {
+      // T-B5: the one byte retention D-7 leaves -- park aborted before the TERM signal, the PTY
+      // is still the SAME live process, so the parked composer bytes are written, not refused.
+      for (const data of queued.data) _deps._writeLifecyclePty(session, data, 'park-abort');
+      _deps._promoteDeferredRuntimeInputs(session, queued.entries, 'park_abort_flush');
+    } else if (queued.entries.length && sameProcess) {
+      // D-6: the PTY did not survive the abort after all -- tell the client, don't drop silently.
+      _deps._dropDeferredRuntimeInputs(session, queued.entries, 'park_abort_pty_missing');
+    } else if (queued.entries.length) {
+      _deps._dropDeferredRuntimeInputs(session, queued.entries, 'park_generation_mismatch');
+    }
+    _deps._dropDeferredRuntimeInputs(session, queued.stale, 'park_generation_mismatch');
+    if (ownsFields) _deps.broadcastSessionList(true, { reason: 'park-abort' });
+    return finishParkAttempt(
+      finishTransition({ ok: false, code, statusCode: 409, protections }),
+      { ...decision, protections },
+    );
+  };
+  const postSignalCurrent = () => session._parkingPromise === parkingTransition
+    && lifetimeMatches(true) && parkOwnerMatches();
+  const finishStaleAfterSignal = (queueBeforeAwait, code = 'park_lifetime_changed') => {
+    const ownsFields = session._parkingPromise === parkingTransition;
+    // Enqueue is copy-on-append: observe the current old-owned queue. If another
+    // promise owns the fields, only the pre-await snapshot belongs to this cleanup.
+    const queued = _deps.drainDeferredInputs(ownsFields ? session._parkingInputQueue : queueBeforeAwait, inputGeneration);
+    if (ownsFields) {
+      session._parkingInputQueue = [];
+      session._parking = false;
+      session._parkingPromise = null;
+      session._parkingAbortRequested = false;
+      session._lifecycleInputInFlight = false;
+      if (session._lifecycleState === 'parking') session._lifecycleState = session.ptyProcess ? 'live' : 'exited';
+    }
+    _deps._dropDeferredRuntimeInputs(session, queued.entries, 'park_generation_mismatch');
+    _deps._dropDeferredRuntimeInputs(session, queued.stale, 'park_generation_mismatch');
+    return finishParkAttempt(finishTransition({ ok: false, code, statusCode: 409 }), decision);
+  };
+  const abortAfterSignal = (code) => {
+    const queueBeforeAwait = Array.isArray(session._parkingInputQueue) ? session._parkingInputQueue.slice() : [];
+    if (!postSignalCurrent() || !parkOwnerMatches()) return finishStaleAfterSignal(queueBeforeAwait, code);
+    session._parking = false;
+    session._parkingPromise = null;
+    if (session._lifecycleState === 'parking') session._lifecycleState = session.ptyProcess ? 'live' : 'exited';
+    return finishParkAttempt(finishTransition({ ok: false, code, statusCode: 409 }));
+  };
+  // The descendant census is an await before these helpers are available. Revalidate the captured
+  // parking owner before publishing anything so a replacement, user abort, or PTY exit during ps
+  // cannot announce parking or proceed into snapshot/signal work for a stale lifetime.
+  if (session._parkingPromise !== parkingTransition || !session._parking || !lifetimeMatches()) {
+    return abortBeforeSignal('park_lifetime_changed');
+  }
+  if (!parkOwnerMatches()) return abortBeforeSignal('park_owner_changed');
+  if (session._parkExitedAt || session._exited || !session.ptyProcess) {
+    return abortBeforeSignal('park_lifetime_changed');
+  }
+  if (session._parkingAbortRequested) {
+    const censusDecision = parkDecision(Date.now());
+    return abortBeforeSignal('park_race_protected', censusDecision.protections || []);
+  }
+  _deps.broadcastToSession(session.id, session, { type: 'session-parking', id: session.id, reason });
+  _deps.broadcastSessionList(true, { reason: 'park-start' });
+  // Give input already in flight from the parking notification a deterministic
+  // chance to reach _handleInputPrepared before the irreversible TERM signal.
+  const preSignalGraceMs = Math.max(0, Number(_deps._lifecycleConfig.parkPreSignalGraceMs || 0));
+  if (preSignalGraceMs > 0) {
+    await new Promise(resolve => setTimeout(resolve, preSignalGraceMs));
+  }
+  if (session._parkingPromise !== parkingTransition) return abortBeforeSignal('park_lifetime_changed');
+  if (!lifetimeMatches()) return abortBeforeSignal('park_lifetime_changed');
+  if (!parkOwnerMatches()) return abortBeforeSignal('park_owner_changed');
+  const transcriptAtSignal = await _lifecycleTranscriptStat(prepared);
+  if (session._parkingPromise !== parkingTransition) return abortBeforeSignal('park_lifetime_changed');
+  if (!lifetimeMatches()) return abortBeforeSignal('park_lifetime_changed');
+  if (!parkOwnerMatches()) return abortBeforeSignal('park_owner_changed');
+  if (transcriptAtSignal.unknown) return abortBeforeSignal('transcript_verification_unavailable');
+  let snapshotWritten = false;
+  try {
+    if (typeof session._drainPtyData === 'function') session._drainPtyData(true);
+    if (typeof session._flushHeadlessFeed === 'function') session._flushHeadlessFeed();
+    if (typeof session._flushScrollbackToDb === 'function') session._flushScrollbackToDb();
+    // WP-0 (session-runtime-reset-regression-triage-2026-09-06.html) deleted the WP-4
+    // pre-park flush-tail step that used to run here (_flushSessionTailBeforeDeath) -- it was
+    // dangling (deleted by the runtime reset merge, 16a10a4b9, while this call site survived).
+    // Restoring the flush-tail behavior itself is out of WP-0's scope; the snapshot below is
+    // unaffected and still runs, just without that pre-park archive top-up.
+    snapshotWritten = await _deps._snapshotSessionScrollbackToFile(session.id, 5_000);
+  } catch (error) {
+    console.warn(`[lifecycle] pre-park snapshot failed id=${String(session.id).slice(0, 8)} error=${error.message}`);
+    return abortBeforeSignal('snapshot_failed');
+  }
+  if (!snapshotWritten) {
+    return abortBeforeSignal('snapshot_unavailable');
+  }
+  if (session._parkingPromise !== parkingTransition) return abortBeforeSignal('park_lifetime_changed');
+  if (!lifetimeMatches()) return abortBeforeSignal('park_lifetime_changed');
+  if (!parkOwnerMatches()) return abortBeforeSignal('park_owner_changed');
+
+  const finalSnapshot = await _deps._readScrollbackSnapshotForRestoreAsync(
+    session.id,
+    resumeId,
+    'lifecycle-park-placeholder',
+  );
+  if (session._parkingPromise !== parkingTransition) return abortBeforeSignal('park_lifetime_changed');
+  if (!lifetimeMatches()) return abortBeforeSignal('park_lifetime_changed');
+  if (!parkOwnerMatches()) return abortBeforeSignal('park_owner_changed');
+  // pre-signal: close the snapshot race. Approval, draft, input, queue, focus,
+  // or work that arrived while flushing aborts before any signal is delivered.
+  // D-3: re-read the composer here too, so text typed during the flush window still refuses.
+  session._parkComposerDraft = await _deps.readComposerDraft(session, { getRows: _deps._getHeadlessRows });
+  const preSignalDecision = parkDecision(Date.now());
+  if (session._parkingAbortRequested || !preSignalDecision.eligible) {
+    return abortBeforeSignal('park_race_protected', preSignalDecision.protections);
+  }
+  if (!lifetimeMatches()) return abortBeforeSignal('park_lifetime_changed');
+  if (!parkOwnerMatches()) return abortBeforeSignal('park_owner_changed');
+  session._parkingSignalSent = true;
+  if (!_deps._signalLifecycleProcessGroup(session, 'SIGTERM', pgid)) {
+    return abortBeforeSignal('term_signal_failed');
+  }
+  let exited = await Promise.race([
+    exitPromise.then(() => true),
+    new Promise(resolve => setTimeout(() => resolve(false), _deps._lifecycleConfig.parkTermGraceMs)),
+  ]);
+  if (!exited) {
+    if (!parkOwnerMatches() || !lifetimeMatches(true)) return abortAfterSignal('park_owner_changed_after_term');
+    _deps._signalLifecycleProcessGroup(session, 'SIGKILL', pgid);
+    exited = await Promise.race([
+      exitPromise.then(() => true),
+      new Promise(resolve => setTimeout(() => resolve(false), 2_000)),
+    ]);
+  }
+  if (!parkOwnerMatches() || !lifetimeMatches(true)) return abortAfterSignal('park_owner_changed_after_exit_wait');
+  if (!exited) {
+    const queueBeforeAudit = Array.isArray(session._parkingInputQueue) ? session._parkingInputQueue.slice() : [];
+    const audit = await _auditParkedProcessGroup(session.id, pgid, rssBeforeMB, descendantPidsBefore);
+    if (!postSignalCurrent()) return finishStaleAfterSignal(queueBeforeAudit);
+    // D-4: survivors outside the agent's pgid are reported, never a reason to refuse the park — this
+    // branch keeps asking only whether the agent's OWN process group is gone (pre-D-4 semantics).
+    const groupProcCount = Number(audit.procCount || 0) - (Array.isArray(audit.survivorPids) ? audit.survivorPids.length : 0);
+    if (audit.auditFailed === true || groupProcCount !== 0) {
+      session._parking = false;
+      session._parkingPromise = null;
+      session._lifecycleState = 'live';
+      return finishParkAttempt(
+        finishTransition({ ok: false, code: 'process_exit_timeout', statusCode: 500 }),
+        decision,
+      );
+    }
+    session._lifecycleState = 'exited';
+    session.ptyProcess = null;
+    _deps.sessionInputAuthority.observeProvider({ sessionId: session.id, status: 'exited' });
+    session._exited = true;
+    exited = true;
+  }
+
+  const queueBeforeVerification = Array.isArray(session._parkingInputQueue) ? session._parkingInputQueue.slice() : [];
+  const observedTranscriptAfter = await _lifecycleTranscriptStat(prepared);
+  if (!postSignalCurrent() || !parkOwnerMatches()) return finishStaleAfterSignal(queueBeforeVerification);
+  if (observedTranscriptAfter.unknown) return abortAfterSignal('transcript_verification_unavailable');
+  const transcriptAfter = await _verifyLifecycleTranscriptPhysical(prepared);
+  if (!postSignalCurrent()) return finishStaleAfterSignal(queueBeforeVerification);
+  if (!resumeSpec && (transcriptAfter.unknown || transcriptAfter.missing !== true)) {
+    // Unknown or newly appeared history without a resume identity cannot use the earlier
+    // fresh plan. Preserve explicit exited state/startup identity and refuse deferred bytes.
+    const queued = _deps.drainDeferredInputs(session._parkingInputQueue, inputGeneration);
+    session._parkingInputQueue = [];
+    session._parking = false;
+    session._parkingPromise = null;
+    session._parkingAbortRequested = false;
+    session._lifecycleInputInFlight = false;
+    session._lifecycleState = 'exited';
+    session._exited = true;
+    session.ptyProcess = null;
+    session.fileSize = Math.max(Number(session.fileSize || 0), Number(transcriptBefore?.size || 0),
+      Number(transcriptAfter.size || 0), Number(observedTranscriptAfter?.size || 0), rolloutSizeBytes);
+    session._resumeLoadingFileSize = Math.max(Number(session._resumeLoadingFileSize || 0), session.fileSize);
+    _deps.sessionInputAuthority.observeProvider({ sessionId: session.id, status: 'exited' });
+    _deps._dropDeferredRuntimeInputs(session, queued.entries, 'pty-missing');
+    _deps._dropDeferredRuntimeInputs(session, queued.stale, 'park_generation_mismatch');
+    _deps.broadcastSessionList(true, { reason: 'park-verify-unavailable' });
+    return finishParkAttempt(finishTransition({ ok: false, code: 'transcript_verification_unavailable', statusCode: 503 }), decision);
+  }
+  const lastOutputAt = Number(session.lastPtyActivity || 0);
+  const verifiedTranscriptMtimeMs = Number(transcriptAfter?.mtimeMs || observedTranscriptAfter?.mtimeMs || 0);
+  if (verifiedTranscriptMtimeMs > 0 && (!transcriptAfter || !transcriptAfter.missing) && lastOutputAt > 0
+      && verifiedTranscriptMtimeMs + 1_000 < lastOutputAt) {
+    console.warn(`[lifecycle] park-verify id=${String(session.id).slice(0, 8)} transcriptMtime=${Math.floor(verifiedTranscriptMtimeMs)} lastOutputAt=${lastOutputAt}`);
+  } else if ((transcriptAtSignal?.filePath || transcriptBefore?.filePath)
+      && (!transcriptAfter || transcriptAfter.missing)) {
+    console.warn(`[lifecycle] park-verify id=${String(session.id).slice(0, 8)} transcript unavailable after TERM`);
+  }
+
+  const restoreSpec = freshSpec && transcriptAfter?.missing === true && !transcriptAfter.unknown ? freshSpec : resumeSpec;
+  const task = {
+    session_id: session.id,
+    label: session.title || session.label || '',
+    cmd: restoreSpec.cmd || session.cmd,
+    args: Array.isArray(restoreSpec.args) ? restoreSpec.args.slice() : [],
+    cwd: session.cwd,
+    created_at: new Date(Number(session._ctmOriginalCreatedAt || session.createdAt || now)).toISOString(),
+    model_id: session.model_id || null,
+    model_provider: session.model_provider || null,
+    model_registry_id: session.model_registry_id || '',
+    model_provider_id: session.model_provider_id || '',
+    type: session.type || 'pty',
+    branch: session.branch || null,
+    worktree_path: session.worktree_path || null,
+    attention_dismissed_at: session._attentionDismissedAt || 0,
+    attention_dismissed_input_at: session._attentionDismissedInputAt || 0,
+    last_user_prompt_input_at: session._lastUserPromptInputAt || 0,
+    last_meaningful_activity_at: session.lastMeaningfulActivityAt || now,
+    lifecycle_pinned: session._lifecyclePinned ? 1 : 0,
+  };
+  const clients = Array.isArray(session.clients) ? session.clients.slice() : [];
+  const queuedParkingInputs = Array.isArray(session._parkingInputQueue) ? session._parkingInputQueue.slice() : [];
+  // S-19 (design doc §5/§9 WP-1): persist the last footprint sample the sweep cache had
+  // for this session before it's torn down, so a park doesn't simply lose it. Nullable
+  // (no sample yet) writes through as NULL, same as the in-memory field's own contract.
+  try {
+    // `void`: the injected dbModule is db-owner-client, whose invokeOwnerMutation already attaches the
+    // detached-error reporter to the returned promise; the try/catch keeps the sync (pre-arm) path covered.
+    void _deps.dbModule.updateSessionLastFootprint(session.id, session.footprintMB == null ? null : session.footprintMB);
+  } catch (error) {
+    // REPORT: best-effort diagnostic write -- must never block the park teardown below.
+    _deps.errorSink.report('lifecycle:persist-last-footprint', error, { sessionId: session.id });
+  }
+  // C-4: parkSession replaces the live aggregate with a deferred-restore placeholder and
+  // carries the live sockets forward (`placeholder.clients = clients` below) -- the
+  // session-runtime aggregate must survive the teardown so those carried-forward viewers
+  // stay attached, or planFrameFanout has nobody to deliver to until the client
+  // reconnects from scratch.
+  await _deps._destroySession(session.id, 'process-teardown', { retireRuntime: false });
+  _deps._lifecycleVisibilityGrace.delete(session.id);
+  const placeholder = _deps._createDeferredRestoreSession(task, task.args, agentType, {
+    restoreCwd: session.cwd,
+    restoreSnapshot: finalSnapshot,
+  });
+  _deps.copyWorkerMarkers(session, placeholder); // D-2: a parked worker keeps its markers, DB-free
+  if (!placeholder) {
+    _deps.sessions.set(session.id, session);
+    session._parking = false;
+    session._parkingPromise = null;
+    session._lifecycleState = 'exited';
+    session._exited = true;
+    session.ptyProcess = null;
+    _deps.sessionInputAuthority.observeProvider({ sessionId: session.id, status: 'exited' });
+    return finishParkAttempt(
+      finishTransition({ ok: false, code: 'placeholder_create_failed', statusCode: 500 }),
+      decision,
+    );
+  }
+  if (deferredLaunchOwnership
+      && !require('./deferred-restore-attempt').transferDeferredRestoreLaunchOwnership(
+        deferredLaunchOwnership, placeholder)) {
+    _deps.recordSessionDiagnostic(session.id, 'park-launch-ownership-transfer-failed', {
+      sourceGeneration: deferredLaunchOwnership.processGeneration,
+    });
+    // A normal placeholder remains recoverable, but cannot authorize a history move without
+    // this in-memory source receipt. The handoff controller will fail closed on the missing
+    // source recipe/context rather than guessing from the durable startup task.
+  }
+  placeholder.clients = clients;
+  placeholder._lifecycleState = 'parked';
+  placeholder._parkedAt = Date.now();
+  placeholder._parkReason = reason;
+  placeholder._lastActivatedAt = session._lastActivatedAt || 0;
+  placeholder._lastActivation = session._lastActivation || null;
+  placeholder._lastFocusedAt = session._lastFocusedAt || 0;
+  placeholder.lastMeaningfulActivityAt = session.lastMeaningfulActivityAt || now;
+  placeholder._lifecyclePinned = !!session._lifecyclePinned;
+  placeholder._lastClientDisconnectAt = Number(session._lastClientDisconnectAt || 0);
+  placeholder._deferredInputGeneration = inputGeneration;
+  // WP-2 (D-4/D-7): park completed -- the parked composer bytes are NOT carried into the
+  // placeholder for later replay (no server queue retains terminal bytes across a PTY
+  // lifecycle any more). They are refused, with a reason of 'parked', and the sender is told
+  // now that the outcome is final.
+  if (queuedParkingInputs.length) _deps._dropDeferredRuntimeInputs(placeholder, queuedParkingInputs, 'parked');
+  placeholder._lifecycleInputInFlight = false;
+  placeholder._resumeLoadingFileSize = Math.max(
+    0,
+    Number(transcriptAfter?.size || transcriptBefore?.size || rolloutSizeBytes || 0),
+  );
+  placeholder.fileSize = placeholder._resumeLoadingFileSize;
+  placeholder.rssMB = 0;
+  placeholder.cpuPct = 0;
+  placeholder.procCount = 0;
+  placeholder.resourceSampledAt = Date.now();
+  // WP-6 (D-7/S-15): the park-time content fingerprint at the SAME dims as the snapshot
+  // (the scrollback-snapshot-store writer computes this alongside the serialized blob --
+  // see lib/scrollback-snapshot-store.js `fp`). This is the strongest server-side content
+  // identity that survives a stop: the headless mirror is torn down at park
+  // (`_destroySession` posts `{type:'destroy'}` to the worker), so
+  // there is no live mirror to sample against for a `_restoreDeferred` session -- only this
+  // stored fp. Only comparable when the activation grid still equals cols/rows above.
+  _deps._applyPersistedSnapshotToPlaceholder(placeholder, finalSnapshot);
+  session._parking = false;
+  session._parkingPromise = null;
+  finishTransition({ ok: true, sessionId: session.id, reason, parkedAt: placeholder._parkedAt });
+  _deps.cleanAutoApprovalBuffer(session.id);
+  _deps.cleanIdleNotify(session.id);
+  _deps.agentSessionKernel.forgetSession(session.id);
+  _deps.sessionDiagnostics.clear(session.id); // WP-3/S2: the ring survives park unless swept here
+  _deps._lifecycleDiagnostics.recordPark({ id: session.id, reason, idleMs: decision.idleMs });
+  console.log(`[lifecycle] park id=${String(session.id).slice(0, 8)} reason=${reason} idleMin=${Math.floor(decision.idleMs / 60_000)} victimRssMB=${Math.round(Number(session.rssMB || 0))}`);
+  for (const client of clients) {
+    if (client?.readyState === 1) {
+      _deps.sendDeferredRestoreStatus(client, placeholder, session.id, placeholder._ptyCols, placeholder._ptyRows, 'park', {
+        reason,
+        message: _deps.parkedSessionMessage(reason, Math.floor(decision.idleMs / 60_000)),
+      });
+      try {
+        _deps._wsSend(client, JSON.stringify({
+          type: 'session-parked',
+          id: session.id,
+          reason,
+          parkedAt: placeholder._parkedAt,
+          idleMin: Math.floor(decision.idleMs / 60_000),
+        }));
+      } catch { /* expected: client disconnected during lifecycle broadcast */ }
+    }
+  }
+  _deps.broadcastSessionList(true, { reason: 'session-parked' });
+  await _auditParkedProcessGroup(session.id, pgid, rssBeforeMB, descendantPidsBefore);
+  if (queuedParkingInputs.length) {
+    _deps._scheduleDeferredRestoreStart(placeholder, { source: 'queued-input', clientKind: 'desktop' });
+  }
+  return finishParkAttempt({ ok: true, sessionId: session.id, reason, parkedAt: placeholder._parkedAt }, decision);
+}
+
+module.exports = {
+  configure,
+  _prepareLifecycleTranscript,
+  _verifyLifecycleTranscriptPhysical,
+  _lifecycleTranscriptStat,
+  _auditParkedProcessGroup,
+  _lifecycleProcessGroupId,
+  parkSession,
+};