create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/acp/ndjson-stdio-transport.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// Newline-delimited JSON (ND-JSON) stdio transport — the ACP primitive (D-1, D-5).
+//
+// One JSON object per line over a child process's stdin/stdout. It is deliberately NOT a
+// PTY: a PTY echoes input back and rewrites "\n" as "\r\n", which corrupts JSON-RPC
+// framing. stdout carries the protocol only; stderr is line-split into `onStderrLine` so
+// the caller can keep a bounded diagnostic tail without polluting the protocol stream.
+//
+// Extracted from lib/codex-app-server-client.js's spawnCodexTransport (WP-1 of
+// docs/deepseek-harness-acp-agent-2026-10-28.html §6.1); that function is now a thin
+// wrapper over this one so both the Codex app-server client and the ACP client share
+// exactly one framing implementation.
+//
+// Decoding uses StringDecoder('utf8') so a multi-byte character split across two chunks
+// is reassembled instead of becoming U+FFFD. A partial trailing line waits for more data.
+
+const { spawn: defaultSpawn } = require('child_process');
+const { StringDecoder } = require('string_decoder');
+
+/**
+ * @param {object} opts
+ * @param {string} opts.command
+ * @param {string[]} [opts.args=[]]
+ * @param {string} [opts.cwd]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {Function} [opts.spawnFn=require('child_process').spawn]
+ * @param {(line: string) => void} [opts.onStderrLine]   // default: no-op; called once per complete stderr line
+ * @returns {{ write(json: string): boolean, onLine(cb: (line: string) => void): void,
+ *             onExit(cb: (info: {code: number|null, signal: string|null, error?: Error}) => void): void,
+ *             endInput(): void, kill(signal?: string): void, pid: number|undefined, _child: object }}
+ */
+function spawnNdjsonTransport(opts = {}) {
+  const {
+    command,
+    args = [],
+    cwd,
+    env,
+    spawnFn = defaultSpawn,
+    onStderrLine = () => {},
+  } = opts;
+
+  let child = null;
+  let spawnFailure = null;
+  try {
+    child = spawnFn(command, args, { stdio: ['pipe', 'pipe', 'pipe'], cwd, env });
+  } catch (error) {
+    // A spawnFn that throws synchronously (rather than emitting 'error') is reported
+    // through the same onExit channel, asynchronously so a caller can subscribe first.
+    spawnFailure = error;
+    child = null;
+  }
+
+  const stdoutDecoder = new StringDecoder('utf8');
+  const stderrDecoder = new StringDecoder('utf8');
+  let stdoutBuf = '';
+  let stderrBuf = '';
+  let lineCb = null;
+  const queuedLines = [];
+  let exitInfo = null;
+  let exitCbs = [];
+  let stdinClosed = false;
+  let stdinErrored = false;
+
+  function emitLine(line) {
+    if (lineCb) lineCb(line);
+    else queuedLines.push(line);
+  }
+
+  function stripCr(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+  }
+
+  function drainStdout() {
+    let nl;
+    while ((nl = stdoutBuf.indexOf('\n')) >= 0) {
+      const line = stripCr(stdoutBuf.slice(0, nl));
+      stdoutBuf = stdoutBuf.slice(nl + 1);
+      if (line.trim() === '') continue;
+      emitLine(line);
+    }
+  }
+
+  function drainStderr() {
+    let nl;
+    while ((nl = stderrBuf.indexOf('\n')) >= 0) {
+      const line = stripCr(stderrBuf.slice(0, nl));
+      stderrBuf = stderrBuf.slice(nl + 1);
+      try {
+        onStderrLine(line);
+      } catch (error) {
+        // expected: a broken stderr observer must never stop the stderr pump.
+        void error;
+      }
+    }
+  }
+
+  function fireExit(info) {
+    if (exitInfo) return;
+    exitInfo = info;
+    const cbs = exitCbs;
+    exitCbs = [];
+    for (const cb of cbs) {
+      try {
+        cb(info);
+      } catch (error) {
+        // expected: one exit observer must not prevent the others from running.
+        void error;
+      }
+    }
+  }
+
+  if (child) {
+    if (child.stdout && typeof child.stdout.on === 'function') {
+      child.stdout.on('data', (chunk) => {
+        stdoutBuf += stdoutDecoder.write(chunk);
+        drainStdout();
+      });
+      child.stdout.on('end', () => {
+        stdoutBuf += stdoutDecoder.end();
+        const tail = stripCr(stdoutBuf);
+        stdoutBuf = '';
+        if (tail.trim() !== '') emitLine(tail);
+      });
+    }
+    if (child.stderr && typeof child.stderr.on === 'function') {
+      child.stderr.on('data', (chunk) => {
+        stderrBuf += stderrDecoder.write(chunk);
+        drainStderr();
+      });
+      child.stderr.on('end', () => {
+        stderrBuf += stderrDecoder.end();
+        const tail = stripCr(stderrBuf);
+        stderrBuf = '';
+        if (tail.trim() !== '') {
+          try {
+            onStderrLine(tail);
+          } catch (error) {
+            // expected: a broken stderr observer must never stop the stderr pump.
+            void error;
+          }
+        }
+      });
+    }
+    // A child that dies mid-write makes stdin emit EPIPE; without a listener that is an
+    // uncaught exception that takes the whole process down.
+    if (child.stdin && typeof child.stdin.on === 'function') {
+      child.stdin.on('error', () => {
+        stdinErrored = true;
+      });
+    }
+    // 'close', not 'exit': Node emits 'exit' as soon as the process is gone, while stdout
+    // may still hold buffered data — the final response line of the turn (e.g. the
+    // session/close reply) would then be delivered after the caller was already told the
+    // child died, and the client would reject that request with acp_child_exited even
+    // though its answer was in flight. 'close' fires once every stdio stream has closed and
+    // carries the same (code, signal). A spawn failure emits 'error' (handled below) and is
+    // followed by 'close'; fireExit is idempotent, so the second call is a no-op.
+    child.on('close', (code, signal) => {
+      fireExit({ code: code == null ? null : code, signal: signal == null ? null : signal });
+    });
+    child.on('error', (error) => {
+      fireExit({ code: null, signal: null, error });
+    });
+  } else if (spawnFailure) {
+    queueMicrotask(() => fireExit({ code: null, signal: null, error: spawnFailure }));
+  }
+
+  function write(json) {
+    if (!child || !child.stdin || exitInfo || stdinClosed || stdinErrored) return false;
+    try {
+      return child.stdin.write(`${json}\n`);
+    } catch (error) {
+      // expected: writing to a child that already exited raises EPIPE; report it as false.
+      void error;
+      return false;
+    }
+  }
+
+  function onLine(cb) {
+    lineCb = cb;
+    while (queuedLines.length) cb(queuedLines.shift());
+  }
+
+  function onExit(cb) {
+    if (exitInfo) {
+      cb(exitInfo);
+      return;
+    }
+    exitCbs.push(cb);
+  }
+
+  function endInput() {
+    if (!child || !child.stdin || exitInfo || stdinClosed) return;
+    stdinClosed = true;
+    try {
+      child.stdin.end();
+    } catch (error) {
+      // expected: ending an already-closed stdin is a no-op.
+      void error;
+    }
+  }
+
+  function kill(signal = 'SIGTERM') {
+    if (!child || exitInfo || typeof child.kill !== 'function') return;
+    try {
+      child.kill(signal);
+    } catch (error) {
+      // expected: a child that already exited cannot be signalled.
+      void error;
+    }
+  }
+
+  return {
+    write,
+    onLine,
+    onExit,
+    endInput,
+    kill,
+    pid: child ? child.pid : undefined,
+    _child: child,
+  };
+}
+
+module.exports = { spawnNdjsonTransport };

package/template/coding-task-manager/lib/adopted-host-redial.js

@@ -21,7 +21,14 @@
 // would have (`manager.hosts`, `manager._adoptedHostRedials`,
 // `manager._adoptedHostRedialAttempts`, `manager._terminatingAdoptedRedials`,
 // `manager._serverBootId`, `manager._routeAdoptedFrame`, `manager._unregister`,
-// `manager._removeHostRecordAsync`, `manager.logger`).
+// `manager._removeHostRecordAsync`, `manager.logger`, `manager.hostRecordForId`,
+// `manager.hostCompatibility`, `manager.emit`).
+
+// WP-3a: the exit event carries `hostPidAliveAtDeclare` -- the manager's own
+// observation of whether the host process was still alive when the host was
+// declared dead. Borrowed from lib/host-registry.js so there is exactly one
+// liveness probe in the codebase, never a re-implementation.
+const { isProcessAlive } = require('./host-registry');
 
 function _sleep(ms) {
   return new Promise((resolve) => {
@@ -49,24 +56,53 @@ const ADOPT_REDIAL_STABLE_MS = 5000;
 
 // Review round 1, fix (b) + reused by the dial-failure `.catch()` below: the
 // SAME terminal path a dead host's own close would otherwise have taken.
+//
+// WP-3a (live-defer-wake-adopted-host-death design, R-6/R-7): "declaring the
+// host dead" used to synthesize the exits immediately and never stop the host
+// process. If the host was only UNREACHABLE (CTM overloaded, dial ladder
+// exhausted) it is still running an agent on the same transcript while the
+// session is respawned with --resume -- two writers, one transcript. Repo
+// policy is "evacuate first, revive second, never keep" (see the header of
+// lib/host-health-revive.js), so the host is stopped through an INJECTED
+// collaborator (`manager.retireDeadHost`, wired by server.js) BEFORE any exit
+// is emitted, and the evidence travels on the exit event itself. Still
+// synchronous from the caller's point of view: returns true the moment the
+// adapters are unregistered, with the exits emitted once the retire settles.
 function _declareHostDead(manager, hostId, attemptNumber) {
   if (manager.isRecoveryProtectedHost?.(hostId)) return false;
   manager._adoptedHostRedialAttempts.delete(hostId);
-  manager.logger.warn?.(`[session-host-registry] adopted-host redial exhausted hostId=${hostId} after ${attemptNumber} attempts -- declaring host dead`);
+  // WP-3a: resolve the record BEFORE unregistering anything -- hostRecordForId()
+  // iterates manager.hosts, so once the loop below has unregistered the last
+  // adapter there is no record left to hand the retire collaborator.
+  const record = manager.hostRecordForId?.(hostId) || null;
+  const hostPidAliveAtDeclare = !!(record && isProcessAlive(record.pid));
+  manager.logger.warn?.(`[session-host-registry] adopted-host redial exhausted hostId=${hostId} after ${attemptNumber} attempts -- declaring host dead pidAlive=${hostPidAliveAtDeclare}`);
+  const victims = [];
   for (const [sessionId, adapter] of manager.hosts) {
     if (adapter._hostId !== hostId || !adapter._adopted || adapter.closed) continue;
     adapter.closed = true;
     manager._unregister(sessionId, adapter);
-    adapter._emitExitOnce({ exitCode: 1, signal: null, hostClosed: true, reason: 'adopted-redial-exhausted' });
+    victims.push(adapter);
   }
-  manager._removeHostRecordAsync(hostId);
-  // D-8 (stale-pty-host-evacuation design): a dead host leaves no retry behind --
-  // without its compat entry handoffStale() returns null and never re-arms a
-  // stale retry for a process that is already gone.
-  manager.hostCompatibility?.delete(hostId);
-  // I6 (host-readiness design): announce the death so the primary's readiness
-  // ledger forgets this hostId -- the ONE terminal path for an adopted host.
-  manager.emit?.('host-exit', { hostId, kind: 'adopted' });
+  Promise.resolve(manager.retireDeadHost ? manager.retireDeadHost(record) : false)
+    .catch((err) => { // REPORT: a failed retire is logged and the exits still fire (hostRetired:false)
+      manager.logger.warn?.(`[session-host-registry] retire dead host ${hostId} failed: ${err?.message || err}`);
+      return false;
+    })
+    .then((retired) => {
+      for (const adapter of victims) {
+        adapter._emitExitOnce({ exitCode: 1, signal: null, hostClosed: true, reason: 'adopted-redial-exhausted', hostRetired: retired === true, hostPidAliveAtDeclare });
+      }
+      manager._removeHostRecordAsync(hostId);
+      // D-8 (stale-pty-host-evacuation design): a dead host leaves no retry behind --
+      // without its compat entry handoffStale() returns null and never re-arms a
+      // stale retry for a process that is already gone.
+      manager.hostCompatibility?.delete(hostId);
+      // I6 (host-readiness design): announce the death so the primary's readiness
+      // ledger forgets this hostId -- the ONE terminal path for an adopted host.
+      manager.emit?.('host-exit', { hostId, kind: 'adopted' });
+    });
+  return true;
 }
 
 // Single-flight re-dial for an adopted host's write connection -- called from

package/template/coding-task-manager/lib/adopted-launch-environment.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// WP-2 of docs/launch-environment-host-carried-adoption-2026-10-26.html (§5 D-3/D-4/D-7, §6).
+//
+// ONE pure converter: the launch environment an adopted session keeps is DERIVED from the host-carried
+// record (adapter.launchEnvironment, WP-1), never frozen from a stamp a previous CTM wrote. The record
+// is the authority -- it holds the bytes the child actually received -- so the spawn receipt's
+// `sourceEnvironmentReference` is cross-checked (reported as `mismatch`), never allowed to override it.
+//
+// An adapter with NO record was spawned by a pre-design host (or restored from a manifest one wrote):
+// that is rule 1, converted on read by the stated rule below (§5 D-4). The four legacy rows are the
+// whole reason 'unknown' is no longer assignable at adoption: every adopted session leaves this module
+// with one of captured / captured-empty / unavailable. 'unknown' stays reserved for sessions whose
+// `_launchEnvOverrides` field CTM itself never wrote (API attach, lib/coding-session-generation-runtime.js;
+// named out of scope in §11) -- it is never produced here.
+//
+// The returned `overrides` is a NEW frozen object (the adapter's already-sanitized modelStorageRoots
+// plus the record's values); the caller may hand it to a session, never mutate it.
+
+const { LAUNCH_ENV_RULE, LAUNCH_ENV_STATES, captureLaunchEnvironment } = require('./launch-environment');
+
+// The two values lib/model-execution-recipe-metadata.js accepts for `sourceEnvironmentReference`, i.e. the
+// spawn receipt's own reading of the private environment. They are the receipt half of the cross-check.
+const REFERENCE_CAPTURED = 'private-owner-required';
+const REFERENCE_CAPTURED_EMPTY = 'captured-empty';
+
+// The launch environment is private only for a LEAD harness: a worker's environment is not CTM's to
+// reinterpret, and a shell/walle session is not a lead at all (§5 D-4).
+const LEAD_AGENT_TYPES = Object.freeze(['claude', 'codex']);
+
+// The sources, one per row R1..R6 of §6 -- exported data so a caller (or the gate's sentence map, WP-3)
+// never re-spells them.
+const ADOPTION_SOURCES = Object.freeze(['host-record', 'host-record-unavailable', 'legacy-recipe',
+  'legacy-reinterpreted', 'legacy-worker', 'legacy-no-receipt']);
+
+/** A record is trusted only as a well-formed observation in the launch-environment vocabulary with a rule
+ * this reader knows (1..LAUNCH_ENV_RULE); anything else (a tampered record, a rule newer than this code)
+ * has no record at all and the legacy rows decide. Never throws: it only reads own data properties. */
+function validRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  if (!Number.isInteger(value.rule) || value.rule < 1 || value.rule > LAUNCH_ENV_RULE) return null;
+  if (!LAUNCH_ENV_STATES.includes(value.state)) return null;
+  if (value.state === 'unavailable') {
+    if (typeof value.reason !== 'string' || !value.reason || value.values !== null) return null;
+    return { rule: value.rule, state: 'unavailable', values: null, reason: value.reason };
+  }
+  if (value.reason !== null) return null;
+  // The values are re-bounded by the rule-0 primitive: a record whose declared state no longer agrees
+  // with a re-capture is not a record.
+  const recaptured = captureLaunchEnvironment(value.values);
+  if (recaptured.state !== value.state) return null;
+  return { rule: value.rule, state: value.state, values: recaptured.values, reason: null };
+}
+
+/** The receipt half of the cross-check: under the record's rule a captured set is private-owner-required
+ * and an empty one is captured-empty, so a receipt that says otherwise disagrees with the bytes the child
+ * received. Absent/blank receipts carry no claim (an older CTM wrote none) and never disagree. */
+function receiptMismatch(reference, recordState) {
+  if (typeof reference !== 'string' || !reference) return null;
+  const expected = recordState === 'captured' ? REFERENCE_CAPTURED : REFERENCE_CAPTURED_EMPTY;
+  if (reference === expected) return null;
+  return Object.freeze({ receipt: reference, record: recordState });
+}
+
+/**
+ * The launch environment of an adopted session, derived row by row (§6; first match wins).
+ *
+ * R1 record && state in {captured, captured-empty} -> the record's values over the host storage roots
+ * R2 record && state === 'unavailable'             -> roots only, the record's own reason
+ * R3 !record && receipt === 'captured-empty'       -> captured-empty (rule 1: the receipt proves it)
+ * R4 !record && receipt === 'private-owner-required' && a lead harness (not a worker)
+ *                                                  -> captured-empty: under rule 1 the only lead-reachable
+ *                                                     private keys were the projected HOME/CODEX_HOME/TMPDIR
+ * R5 !record && receipt === 'private-owner-required' -> unavailable/'legacy_worker_private_env'
+ * R6 otherwise                                      -> unavailable/'legacy_no_receipt'
+ *
+ * @param {object} input
+ * @param {Readonly<Record>|undefined|null} input.launchEnvironment the host record, or undefined (legacy)
+ * @param {object|undefined|null} input.modelStorageRoots the adapter's sanitized storage roots
+ * @param {object|null|undefined} input.recipe the adopted (validated) execution recipe, or null
+ * @param {string|null|undefined} input.agentRole `session.agentRole` after _stampWorkerMarkers; 'worker'
+ *        is a worker
+ * @param {string|null|undefined} input.agentType 'claude' | 'codex' | 'shell' | 'walle'
+ * @returns {{overrides: Readonly<object>, state: 'captured'|'captured-empty'|'unavailable', reason:
+ *           string|null, source: string, fromRule: 1|2, mismatch: Readonly<{receipt: string, record:
+ *           string}>|null}} — frozen; `state` is never 'unknown'
+ */
+function deriveAdoptedLaunchEnvironment({ launchEnvironment, modelStorageRoots, recipe, agentRole, agentType } = {}) {
+  const roots = modelStorageRoots && typeof modelStorageRoots === 'object' && !Array.isArray(modelStorageRoots)
+    ? modelStorageRoots : {};
+  const overridesOf = (values) => Object.freeze({ ...roots, ...(values || {}) });
+  const record = validRecord(launchEnvironment);
+  const reference = recipe && typeof recipe === 'object' ? recipe.sourceEnvironmentReference : null;
+  // R1: the record holds the bytes the child received; the receipt is only cross-checked against it.
+  if (record && record.state !== 'unavailable') {
+    return Object.freeze({ overrides: overridesOf(record.values), state: record.state, reason: null,
+      source: 'host-record', fromRule: record.rule, mismatch: receiptMismatch(reference, record.state) });
+  }
+  // R2: the host itself could not capture this session's environment; its reason is carried verbatim.
+  if (record) {
+    return Object.freeze({ overrides: overridesOf(null), state: 'unavailable', reason: record.reason,
+      source: 'host-record-unavailable', fromRule: record.rule, mismatch: null });
+  }
+  // R3..R6: no record -- rule 1, reinterpreted by what the receipt says the source environment was.
+  if (reference === REFERENCE_CAPTURED_EMPTY) {
+    return Object.freeze({ overrides: overridesOf(null), state: 'captured-empty', reason: null,
+      source: 'legacy-recipe', fromRule: 1, mismatch: null });
+  }
+  if (reference === REFERENCE_CAPTURED && agentRole !== 'worker' && LEAD_AGENT_TYPES.includes(agentType)) {
+    return Object.freeze({ overrides: overridesOf(null), state: 'captured-empty', reason: null,
+      source: 'legacy-reinterpreted', fromRule: 1, mismatch: null });
+  }
+  if (reference === REFERENCE_CAPTURED) {
+    return Object.freeze({ overrides: overridesOf(null), state: 'unavailable',
+      reason: 'legacy_worker_private_env', source: 'legacy-worker', fromRule: 1, mismatch: null });
+  }
+  return Object.freeze({ overrides: overridesOf(null), state: 'unavailable', reason: 'legacy_no_receipt',
+    source: 'legacy-no-receipt', fromRule: 1, mismatch: null });
+}
+
+// LAUNCH_ENV_RULE is re-exported because the adoption block (server.js) stamps it on the launch-env-adopted
+// diagnostic; it is imported above from the launch-environment primitive, never re-defined here.
+module.exports = { deriveAdoptedLaunchEnvironment, ADOPTION_SOURCES, LAUNCH_ENV_RULE };

package/template/coding-task-manager/lib/agent-auto-update-runtime.js

@@ -6,7 +6,6 @@
 
 const path = require('path');
 const autoUpdate = require('./agent-auto-update');
-const { codexQualification } = require('./codex-harness-qualification');
 const { DEFAULT_AGENT_IDS } = require('./agent-definitions');
 const { refreshOutdatedHooks } = require('./agent-hooks-boot-prune');
 const hooksInstaller = require('./agent-hooks-installer');
@@ -44,8 +43,6 @@ function createAgentAutoUpdateRuntime({
         startJob: (agent) => agentVersionService.startUpgradeJob(agent, { ...versionOptions(), trigger: 'auto' }),
         hasRunningJob: (agent) => agentVersionService.listUpgradeJobs().jobs.some((j) => j.agent === agent && j.status === 'running'),
         liveSessionAgents: () => autoUpdate.liveAgentIds(sessions, isLive),
-        // WP-2 (D-6): only Codex is gated by the qualified-version table; every other agent is untouched.
-        qualificationFor: (agent, v) => (agent === 'codex' ? codexQualification(v) : null),
         isEnabled,
         readAttempts: async () => (await stateFile.read()).attempts,
         writeAttempts: (attempts) => stateFile.update((state) => ({ ...state, attempts })),

package/template/coding-task-manager/lib/agent-auto-update.js

@@ -16,10 +16,6 @@ const LIVE_SENSITIVE_MODES = new Set(['npm-global', 'homebrew', 'homebrew-cask']
 function createAutoUpdater({
   getStatus, startJob, hasRunningJob, liveSessionAgents, isEnabled,
   readAttempts, writeAttempts, report, log,
-  // WP-2 (D-6): the caller's qualified-version table reader, `(agent, version) => ({ state } | null)`.
-  // Optional: a caller that passes nothing keeps the pre-WP-2 chain exactly (no automatic version is
-  // ever deferred for qualification).
-  qualificationFor = null,
   setTimeoutImpl = setTimeout, clearTimeoutImpl = clearTimeout,
   now = Date.now,
 }) {
@@ -46,9 +42,6 @@ function createAutoUpdater({
           const attempts = (await readAttempts()) || {};
           const prior = attempts[agent];
           if (prior && prior.version === row.latestVersion) action = 'already_attempted';
-          // WP-2 (D-6): never start an automatic upgrade to a version outside the qualified table.
-          // The attempts file is untouched (no attempt was made) and a user click still upgrades (P-4).
-          else if (qualificationFor && qualificationFor(agent, row.latestVersion)?.state === 'unqualified') action = 'deferred_unqualified';
           else if (LIVE_SENSITIVE_MODES.has(row.upgradeMode) && liveSessionAgents().has(agent)) action = 'deferred_live_sessions';
           else if (hasRunningJob(agent)) action = 'job_running';
           else {
@@ -126,18 +119,38 @@ function createStateFile(filePath) {
   return { read, write, update };
 }
 
+/** The agent definition a session record belongs to, or null. Shared by liveAgentIds/liveSessionsFor. */
+function _sessionAgentDefinition(session) {
+  const bin = path.basename(String(session.cmd || '').trim().split(/\s+/)[0] || '');
+  return definitionForCli(bin) || definitionForCli(session.type) || null;
+}
+
 /** Agent ids (keys of AGENT_DEFINITIONS) that have a live session, from an iterable of session records. */
 function liveAgentIds(sessionMap, isLive) {
   const out = new Set();
   for (const session of sessionMap.values()) {
     if (!session || !isLive(session)) continue;
-    const bin = path.basename(String(session.cmd || '').trim().split(/\s+/)[0] || '');
-    const def = definitionForCli(bin) || definitionForCli(session.type);
+    const def = _sessionAgentDefinition(session);
     if (def) out.add(def.id);
   }
   return out;
 }
 
+/**
+ * WP-4 (D-9): the live sessions of ONE agent, as `[{ id, title, agent }]`, derived exactly like
+ * liveAgentIds above. The user-click upgrade path names them before it replaces a running install.
+ */
+function liveSessionsFor(sessionMap, isLive, agentId) {
+  const out = [];
+  for (const [id, session] of sessionMap.entries()) {
+    if (!session || !isLive(session)) continue;
+    const def = _sessionAgentDefinition(session);
+    if (!def || def.id !== agentId) continue;
+    out.push({ id: String(session.id || id), title: session.title || session.label || '', agent: def.id });
+  }
+  return out;
+}
+
 /** Record how an automatic job ended in the attempts file (no-op when no attempt matches). */
 async function recordJobOutcome(file, job) {
   if (!job || job.trigger !== 'auto') return;
@@ -150,5 +163,8 @@ async function recordJobOutcome(file, job) {
 
 module.exports = {
   TICK_MS, FIRST_TICK_MS,
-  createAutoUpdater, createStateFile, liveAgentIds, recordJobOutcome,
+  // WP-4 (S-13): exported so the user-click upgrade path (lib/agent-version-service.js) shares the
+  // tick's predicate instead of re-deriving it. Behaviour is unchanged; createAutoUpdater reads it.
+  LIVE_SENSITIVE_MODES,
+  createAutoUpdater, createStateFile, liveAgentIds, liveSessionsFor, recordJobOutcome,
 };