@aiwg/cli 2026.10.10 → 2026.10.12

package/tools/ralph-external/lib/worker-invocation-processes.mjs

@@ -0,0 +1,123 @@
+// Bind worker environments to an invocation and find surviving marked processes.
+import { opendirSync, statSync, openSync, readSync, closeSync, constants } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+import { classifyUnreadableWorkerProcess, readProcCgroup } from './worker-invocation-ancestry.mjs';
+
+export const WORKER_INVOCATION_MARKER = 'AIWG_WORKER_INVOCATION_ID';
+
+function startedBeforeWorker(fs, path, startTicks) {
+  if (typeof startTicks !== 'string' || !/^\d+$/.test(startTicks)) return false;
+  let fd;
+  try {
+    fd = fs.openSync(`${path}/stat`, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    const buffer = Buffer.alloc(4096);
+    const size = fs.readSync(fd, buffer, 0, buffer.length, null);
+    if (size === buffer.length) return false;
+    const stat = buffer.toString('utf8', 0, size);
+    // comm may contain spaces and parentheses; field 3 begins after its LAST ')'.
+    const end = stat.lastIndexOf(')');
+    const ticks = end < 0 ? undefined : stat.slice(end + 1).trim().split(/\s+/)[19];
+    return /^\d+$/.test(ticks ?? '') && BigInt(ticks) < BigInt(startTicks);
+  } catch { return false; }
+  finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+export function buildWorkerInvocationEnvironment(envNames, invocationId, inherited = process.env) {
+  if (typeof invocationId !== 'string' || !invocationId || invocationId.includes('\0')) {
+    throw new Error('Worker environment requires a non-empty NUL-free invocation ID');
+  }
+  const names = [...new Set([...envNames, WORKER_INVOCATION_MARKER])];
+  const env = Object.fromEntries(envNames.filter(name => inherited[name] !== undefined)
+    .map(name => [name, inherited[name]]));
+  return { env: { ...env, [WORKER_INVOCATION_MARKER]: invocationId }, envNames: names };
+}
+
+export function scanWorkerInvocationProcesses({ invocationId, startTicks, uid = process.getuid?.(),
+  platform = process.platform, procRoot = '/proc', now = () => performance.now(),
+  deadline = now() + 100, maxEntries = 4096, maxEnvironmentBytes = 1048576,
+  workerPid, workerPgid, workerSession, workerCgroup, selfCgroup, maxAncestryDepth,
+  fs = { opendirSync, statSync, openSync, readSync, closeSync } } = {}) {
+  const unknown = detail => ({ confirmed: false,
+    missing: `escaped-descendant evidence: ${detail}` });
+  if (platform !== 'linux') return unknown('same-uid invocation-marker scan requires Linux /proc');
+  if (!Number.isInteger(uid) || typeof invocationId !== 'string' || !invocationId || invocationId.includes('\0')) {
+    return unknown('launcher-bound invocation marker and uid');
+  }
+  // Ancestry discrimination needs the recorded worker leader. Without it the
+  // scan keeps the legacy fail-closed behaviour for every unreadable
+  // post-start process.
+  const workerKnown = Number.isSafeInteger(workerPid) && workerPid > 1
+    && typeof startTicks === 'string' && /^\d+$/.test(startTicks);
+  let resolvedWorkerCgroup = workerCgroup;
+  if (resolvedWorkerCgroup === undefined && workerKnown) {
+    resolvedWorkerCgroup = readProcCgroup(fs, `${procRoot}/${workerPid}`);
+  }
+  let resolvedSelfCgroup = selfCgroup;
+  if (resolvedSelfCgroup === undefined) resolvedSelfCgroup = readProcCgroup(fs, `${procRoot}/self`);
+  const marker = `${WORKER_INVOCATION_MARKER}=${invocationId}`;
+  const present = () => ({ ...unknown('same-uid process still carries invocation marker (possible escaped descendant)'), markerPresent: true });
+  const gone = error => ['ENOENT', 'ESRCH'].includes(error.code);
+  let directory, uncertain = null;
+  try {
+    directory = fs.opendirSync(procRoot);
+    // Stream entries and cap per-process reads; neither a huge PID set nor
+    // a large environment can turn this proof into an unbounded allocation.
+    const buffer = Buffer.alloc(Math.min(65536, maxEnvironmentBytes + 1));
+    for (let count = 0; ; count++) {
+      if (now() >= deadline) return unknown('same-uid invocation-marker scan time bound reached');
+      const entry = directory.readSync();
+      if (!entry) return uncertain ?? { confirmed: true, missing: null };
+      if (count >= maxEntries) return unknown('same-uid invocation-marker scan count bound reached');
+      if (!/^\d+$/.test(entry.name)) continue;
+      const path = `${procRoot}/${entry.name}`;
+      let fd, sameUid = false;
+      try {
+        if (fs.statSync(path).uid !== uid) continue;
+        sameUid = true;
+        fd = fs.openSync(`${path}/environ`, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+        let bytes = 0, tail = '';
+        const decoder = new StringDecoder('utf8');
+        for (;;) {
+          if (now() >= deadline) return unknown('same-uid invocation-marker scan time bound reached');
+          const size = fs.readSync(fd, buffer, 0, Math.min(buffer.length, maxEnvironmentBytes + 1 - bytes), null);
+          if (!size) break;
+          bytes += size;
+          if (bytes > maxEnvironmentBytes) {
+            uncertain = unknown('same-uid process environment exceeds scan byte bound'); break;
+          }
+          const fields = (tail + decoder.write(buffer.subarray(0, size))).split('\0');
+          tail = fields.pop();
+          if (fields.includes(marker)) return present();
+        }
+        if (tail + decoder.end() === marker) return present();
+      } catch (error) {
+        // An escaped descendant cannot predate its worker leader. Ownership
+        // failures and unreadable/missing start times still cannot prove absence.
+        if (gone(error)) continue;
+        if (!sameUid) {
+          uncertain = unknown('unreadable same-uid process environment or ownership');
+          continue;
+        }
+        if (!workerKnown) {
+          if (!startedBeforeWorker(fs, path, startTicks)) {
+            uncertain = unknown('unreadable same-uid process environment or ownership');
+          }
+          continue;
+        }
+        // Hardened (non-dumpable, e.g. Codex) processes hide their environment
+        // but not their stat/cgroup links: a parallel worker's tree reaches a
+        // live process that predates this worker and is provably not ours,
+        // while a genuine escapee still links to the leader, its session or
+        // group, or its private cgroup.
+        const verdict = classifyUnreadableWorkerProcess({ fs, procRoot, pid: Number(entry.name), uid,
+          workerPid, workerPgid, workerSession, workerStart: startTicks,
+          workerCgroup: resolvedWorkerCgroup, selfCgroup: resolvedSelfCgroup,
+          now, deadline, ...(maxAncestryDepth === undefined ? {} : { maxDepth: maxAncestryDepth }) });
+        if (verdict === 'possible-descendant') {
+          uncertain = unknown('unreadable same-uid process links to the worker (ancestry, session, group or cgroup)');
+        }
+      } finally { if (fd !== undefined) fs.closeSync(fd); }
+    }
+  } catch { return unknown('readable Linux /proc process inventory'); }
+  finally { directory?.closeSync(); }
+}

package/tools/ralph-external/lib/worker-isolation-status.mjs

@@ -0,0 +1,48 @@
+// Read retained unit exit state and its kernel-backed recursive task count.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { buildSystemdClientEnv, resolveSystemdClient } from './systemd-client.mjs';
+
+function emptyCgroup(fields, readCgroup) {
+  if (fields.TasksCurrent === '0') return true;
+  if (/^[1-9][0-9]*$/.test(fields.TasksCurrent ?? '')) return false;
+  if (!['inactive', 'failed'].includes(fields.ActiveState)) return false;
+  // A loaded inactive unit can have released its cgroup entirely.
+  if (fields.LoadState === 'loaded' && fields.ControlGroup === '') return true;
+  const group = fields.ControlGroup;
+  if (!group?.startsWith('/') || group === '/' || group.split('/').includes('..')) return false;
+  try { return /^populated 0$/m.test(readCgroup(`/sys/fs/cgroup${group}/cgroup.events`, 'utf8')); }
+  catch (error) { return error.code === 'ENOENT'; }
+}
+
+/**
+ * Read retained service state after launch/exit without reaping or mutation.
+ * `memoryMax` is bytes. Query failures throw rather than reporting success.
+ */
+export function getWorkerIsolationStatus(unit, { spawn = spawnSync, timeoutMs = 10000, readCgroup = readFileSync } = {}) {
+  if (typeof unit !== 'string' || !/^[A-Za-z0-9:_.@-]+$/.test(unit)) {
+    throw new Error('Worker isolation requires a unit-safe unit name');
+  }
+  const shown = spawn(resolveSystemdClient('systemctl'), ['--user', 'show', unit, '-p', 'ActiveState',
+    '-p', 'Result', '-p', 'ExecMainStatus', '-p', 'ExecMainCode', '-p', 'MainPID', '-p', 'MemoryMax', '-p', 'TasksCurrent', '-p', 'ControlGroup', '-p', 'LoadState'], { encoding: 'utf8', timeout: timeoutMs, env: buildSystemdClientEnv({ envNames: [] }) });
+  if (shown.error || shown.status !== 0) {
+    throw new Error(`worker status unavailable: ${shown.error?.message ?? String(shown.stderr ?? '').trim()}`);
+  }
+  const fields = Object.fromEntries(String(shown.stdout ?? '').trim().split('\n').map(line => {
+    const index = line.indexOf('=');
+    return [line.slice(0, index), line.slice(index + 1)];
+  }));
+  if (!fields.ActiveState || !fields.Result || !fields.MemoryMax) {
+    throw new Error('worker status unavailable: missing systemd properties');
+  }
+  return {
+    active: ['inactive', 'failed'].includes(fields.ActiveState) ? false
+      : ['active', 'activating', 'deactivating', 'reloading'].includes(fields.ActiveState) ? true : null,
+    ...(emptyCgroup(fields, readCgroup) ? { cgroupEmpty: true } : {}),
+    result: fields.Result,
+    ...(fields.ExecMainStatus ? { execMainStatus: Number(fields.ExecMainStatus) } : {}),
+    memoryMax: fields.MemoryMax === 'infinity' ? Infinity : Number(fields.MemoryMax),
+    ...(fields.MainPID ? { mainPid: Number(fields.MainPID) } : {}),
+    ...(fields.ExecMainCode ? { execMainCode: Number(fields.ExecMainCode) } : {}),
+  };
+}

package/tools/ralph-external/lib/worker-isolation.mjs

@@ -556,35 +556,7 @@ export function launchIsolatedWorker({
   });
 }
 
-/**
- * Read retained service state after launch/exit without reaping or mutation.
- * `memoryMax` is bytes. Query failures throw rather than reporting success.
- */
-export function getWorkerIsolationStatus(unit, { spawn = spawnSync, timeoutMs = 10000 } = {}) {
-  if (typeof unit !== 'string' || !/^[A-Za-z0-9:_.@-]+$/.test(unit)) {
-    throw new Error('Worker isolation requires a unit-safe unit name');
-  }
-  const shown = spawn(resolveSystemdClient('systemctl'), ['--user', 'show', unit, '-p', 'ActiveState',
-    '-p', 'Result', '-p', 'ExecMainStatus', '-p', 'ExecMainCode', '-p', 'MainPID', '-p', 'MemoryMax'], { encoding: 'utf8', timeout: timeoutMs, env: buildSystemdClientEnv({ envNames: [] }) });
-  if (shown.error || shown.status !== 0) {
-    throw new Error(`worker status unavailable: ${shown.error?.message ?? String(shown.stderr ?? '').trim()}`);
-  }
-  const fields = Object.fromEntries(String(shown.stdout ?? '').trim().split('\n').map(line => {
-    const index = line.indexOf('=');
-    return [line.slice(0, index), line.slice(index + 1)];
-  }));
-  if (!fields.ActiveState || !fields.Result || !fields.ExecMainStatus || !fields.MemoryMax) {
-    throw new Error('worker status unavailable: missing systemd properties');
-  }
-  return {
-    active: ['active', 'activating', 'deactivating', 'reloading'].includes(fields.ActiveState),
-    result: fields.Result,
-    execMainStatus: Number(fields.ExecMainStatus),
-    memoryMax: fields.MemoryMax === 'infinity' ? Infinity : Number(fields.MemoryMax),
-    ...(fields.MainPID ? { mainPid: Number(fields.MainPID) } : {}),
-    ...(fields.ExecMainCode ? { execMainCode: Number(fields.ExecMainCode) } : {}),
-  };
-}
+export { getWorkerIsolationStatus } from './worker-isolation-status.mjs';
 
 /**
  * Request the unit's cgroup be torn down (`KillMode=control-group` is already
@@ -608,6 +580,22 @@ export function stopWorkerUnit(unit, { spawn = spawnSync, timeoutMs = 10000 } =
     diagnostic: result.error ? result.error.message : String(result.stderr ?? '').trim() || null };
 }
 
+/**
+ * SIGKILL every process in the unit's cgroup and return without waiting.
+ * `stop` sends SIGTERM and then waits for the unit's stop timeout, which a
+ * worker that ignores SIGTERM outlasts (#3691).
+ */
+export function killWorkerUnit(unit, { spawn = spawnSync, timeoutMs = 10000, signal = 'SIGKILL' } = {}) {
+  if (typeof unit !== 'string' || !/^[A-Za-z0-9:_.@-]+$/.test(unit)) {
+    throw new Error('Worker isolation requires a unit-safe unit name');
+  }
+  if (!/^SIG[A-Z0-9]+$/.test(signal)) throw new Error('Worker isolation requires a named signal');
+  const result = spawn(resolveSystemdClient('systemctl'), ['--user', 'kill', '--kill-whom=all', `--signal=${signal}`, unit],
+    { encoding: 'utf8', timeout: timeoutMs, killSignal: 'SIGKILL', env: buildSystemdClientEnv({ envNames: [] }) });
+  return { ok: !result.error && result.status === 0,
+    diagnostic: result.error ? result.error.message : String(result.stderr ?? '').trim() || null };
+}
+
 /**
  * Read the kernel-reported `ControlGroup` systemd placed this unit's
  * processes under. This is the containment authority for `systemd-unit`

package/tools/ralph-external/lib/worker-launch-cli.mjs

@@ -12,6 +12,7 @@ export function parseWorkerLaunchArgs(args) {
     if (seen.has(flag)) throw new Error(`Duplicate worker launch option: ${flag}`);
     seen.add(flag);
     if (flag === '--launch-worker') continue;
+    if (flag === '--check-descendants') { result.checkDescendants = true; continue; }
     if (flag === '--allow-degraded-worker') { result.allowDegraded = true; continue; }
     // A run directory declares a retry; its launcher ID is derived before validation.
     const key = { '--invocation': 'invocationPath', '--run-dir': 'runDir',
@@ -24,11 +25,12 @@ export function parseWorkerLaunchArgs(args) {
     else result[key] = value;
   }
   if (!seen.has('--launch-worker') || !result.invocationPath || !result.runDir) {
-    throw new Error('Usage: ralph-external --launch-worker --invocation FILE --run-dir DIR [--allow-degraded-worker] [--retry-of-run-dir DIR [--retry-of ID]]');
+    throw new Error('Usage: ralph-external --launch-worker --invocation FILE --run-dir DIR [--allow-degraded-worker] [--check-descendants] [--retry-of-run-dir DIR [--retry-of ID]]');
   }
   if (retryOfInvocationId !== undefined && retryOfRunDir === undefined) {
     throw new Error('--retry-of and --retry-of-run-dir must be supplied together when an explicit ID is used');
   }
+  if (result.checkDescendants && retryOfRunDir === undefined) throw new Error('--check-descendants requires --retry-of-run-dir');
   if (retryOfRunDir !== undefined) result.retryOf = { runDir: retryOfRunDir, ...(retryOfInvocationId === undefined ? {} : { invocationId: retryOfInvocationId }) };
   return result;
 }

package/tools/ralph-external/lib/worker-overflow.mjs

@@ -1,15 +1,30 @@
 /** Stop authority and bounded termination proof for MCP stdout overflow. */
 import { importImpl } from '../../_resolve-impl.mjs';
-import { getWorkerIsolationStatus, stopWorkerUnit } from './worker-isolation.mjs';
+import { getWorkerIsolationStatus, killWorkerUnit, stopWorkerUnit } from './worker-isolation.mjs';
 import { signalOwnedWorker } from '../session-launcher.mjs';
 import { sampleWorkerChildren, sampleWorkerIdentity, sameWorkerIdentity } from '../process-monitor.mjs';
 const { signalChild } = await importImpl(import.meta.url, 'process/signal-child.mjs');
 
+// Only identities sampled beneath a verified live supervisor enter this cache.
+const ownedWorkers = new WeakMap();
+function hasBirthIdentity(worker) {
+  return Number.isSafeInteger(worker?.pid) && worker.pid > 1 && worker.pid !== process.pid
+    && Number.isSafeInteger(worker.pgid) && worker.pgid > 1
+    && Number.isSafeInteger(worker.uid) && worker.uid === process.getuid?.()
+    && Number.isSafeInteger(worker.sessionId) && worker.sessionId > 0
+    && typeof worker.startTicks === 'string' && /^\d+$/.test(worker.startTicks)
+    && ['bootId', 'host', 'executable'].every(key => typeof worker[key] === 'string' && worker[key].length > 0);
+}
+
 export async function stopOverflowWorker(launch, {
   deadlineMs = 2000, pollIntervalMs = 25,
-  stopUnit = stopWorkerUnit, unitStatus = getWorkerIsolationStatus,
+  // Kill and stop are one unit-stop authority: a caller that substitutes the stop
+  // also controls the kill, so the real systemctl never bypasses it.
+  stopUnit = stopWorkerUnit, killUnit = stopUnit === stopWorkerUnit ? killWorkerUnit : () => ({ ok: false }),
+  unitStatus = getWorkerIsolationStatus,
   sample = sampleWorkerIdentity, children = sampleWorkerChildren, platform = process.platform,
-  signal = signalOwnedWorker, clock = Date.now, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
+  signal = signalOwnedWorker, killPid = (pid, sig) => process.kill(pid, sig),
+  clock = Date.now, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
 } = {}) {
   let delivered = false;
   const uncertain = diagnostic => ({ termination: 'uncertain', diagnostic, delivered });
@@ -18,8 +33,13 @@ export async function stopOverflowWorker(launch, {
   // Subprocess timeouts cannot bound stalled kernel or /proc reads.
   const remaining = () => Math.max(1, deadline - clock());
   if (launch.mode === 'systemd-unit' && launch.unit) {
-    try { if (!(delivered = !!stopUnit(launch.unit, { timeoutMs: remaining() }).ok)) diagnostic = 'OG_WORKER_MCP_STOP_FAILED'; }
-    catch { diagnostic = 'OG_WORKER_MCP_STOP_FAILED'; }
+    // SIGKILL the unit's whole cgroup first. A plain stop sends SIGTERM and then
+    // waits out the unit's stop timeout, which a worker ignoring SIGTERM outlasts
+    // (#3691). The stop that follows only cleans up the dead unit.
+    let killed = false;
+    try { killed = !!killUnit(launch.unit, { timeoutMs: remaining() }).ok; } catch { killed = false; }
+    try { delivered = !!stopUnit(launch.unit, { timeoutMs: remaining() }).ok || killed; } catch { delivered = killed; }
+    if (!delivered) diagnostic = 'OG_WORKER_MCP_STOP_FAILED';
   } else {
     const child = launch.child;
     // The direct-child handle cannot prove descendant termination.
@@ -28,15 +48,30 @@ export async function stopOverflowWorker(launch, {
       catch { return uncertain('OG_WORKER_MCP_STOP_FAILED'); }
       return uncertain('OG_WORKER_MCP_STOP_UNCONFIRMED');
     }
-    const supervisor = sample(child?.pid);
-    if (!supervisor || supervisor.parentPid !== process.pid || supervisor.uid !== process.getuid?.()
-      || child.exitCode !== null || child.signalCode !== null) return uncertain('OG_WORKER_MCP_STOP_UNCONFIRMED');
-    const candidates = launch.transportSupervisor ? children(supervisor.pid) : [supervisor];
-    const worker = candidates?.length === 1 ? candidates[0] : null;
-    if (!worker || launch.transportSupervisor && worker.parentPid !== supervisor.pid
-      || !sameWorkerIdentity(supervisor, sample(supervisor.pid))) return uncertain('OG_WORKER_MCP_STOP_UNCONFIRMED');
+    let worker = launch.transportSupervisor ? ownedWorkers.get(launch) : null;
+    if (!worker) {
+      const supervisor = sample(child?.pid);
+      if (!supervisor || supervisor.parentPid !== process.pid || supervisor.uid !== process.getuid?.()
+        || child.exitCode !== null || child.signalCode !== null) return uncertain('OG_WORKER_MCP_STOP_UNCONFIRMED');
+      const candidates = launch.transportSupervisor ? children(supervisor.pid) : [supervisor];
+      worker = candidates?.length === 1 ? candidates[0] : null;
+      if (!worker || launch.transportSupervisor && (worker.parentPid !== supervisor.pid || !hasBirthIdentity(worker))
+        || !sameWorkerIdentity(supervisor, sample(supervisor.pid))) return uncertain('OG_WORKER_MCP_STOP_UNCONFIRMED');
+      if (launch.transportSupervisor) ownedWorkers.set(launch, worker = Object.freeze({ ...worker }));
+    }
     // Reuse the launcher's birth/session/UID checks; never signal a bare PID.
-    if (!(delivered = !!signal(worker, 'SIGKILL'))) return uncertain('OG_WORKER_MCP_STOP_FAILED');
+    if (!(delivered = !!signal(worker, 'SIGKILL'))) {
+      // #3691: reparenting changes ownership topology, not process birth.
+      // The cache pins birth/UID/session while the parent link is intact;
+      // compare every identity field except parentPid on a fresh kernel sample.
+      // This also works on retained-control retries after client.close() has
+      // killed the supervisor. Never refresh the pin from an orphan or disk.
+      const fresh = launch.transportSupervisor ? sample(worker.pid) : null;
+      if (fresh && sameWorkerIdentity(worker, { ...fresh, parentPid: worker.parentPid })) {
+        try { killPid(worker.pid, 'SIGKILL'); delivered = true; } catch { delivered = false; }
+      }
+      if (!delivered) return uncertain('OG_WORKER_MCP_STOP_FAILED');
+    }
     // Descendants can escape the group, so its termination stays uncertain.
     return uncertain('OG_WORKER_MCP_STOP_UNCONFIRMED');
   }

package/tools/ralph-external/lib/worker-retry-evidence.mjs

@@ -0,0 +1,103 @@
+// Authenticate predecessor records and optionally recheck owned descendant absence.
+import { join } from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+import { lstat } from 'node:fs/promises';
+import { boundedPrivateRead } from './worker-inputs.mjs';
+import { realBeneath, stableTaskChainDigest, assertStopBeforeRetry, publishWorkerRecord, UNBOUND_RETRY_EVIDENCE_CODE } from '../session-launcher.mjs';
+import { recheckWorkerTermination } from './worker-termination.mjs';
+
+async function matchesLegacyTask(record, plan) {
+  // Non-recovery launches retained a digest of the request including output paths.
+  // Reconstruct only those paths; all task fields and the brief content stay bound.
+  if (![record.prompt?.path, record.cwd, record.paths?.final].every(value => typeof value === 'string')
+    || record.prompt?.digest !== plan.invocation?.briefDigest) return false;
+  const { qualificationDigest } = await importImpl(import.meta.url, 'models/qualification-digest.mjs');
+  return record.taskDigest === qualificationDigest({ ...plan.request,
+    brief: record.prompt.path, workdir: record.cwd, final_output: record.paths.final });
+}
+
+export async function verifyRetryPredecessor(retryOf, { newInvocationPath, inspect, workerWritableRoots, checkDescendants = false } = {}) {
+  const fail = (reason) => {
+    const error = new Error(`Retry predecessor evidence refused: ${reason}`);
+    error.code = UNBOUND_RETRY_EVIDENCE_CODE;
+    throw error;
+  };
+  if (!retryOf || typeof retryOf.invocationId !== 'string' || !retryOf.invocationId
+    || typeof retryOf.runDir !== 'string' || !retryOf.runDir) {
+    fail('retryOf requires both a non-empty invocationId and runDir');
+  }
+  const { invocationId: prevId, runDir: prevRunDir } = retryOf;
+  // #2915 review 4 (finding 4): the minimal directory-authority repair —
+  // reject a predecessor location inside any worker-writable root, exactly
+  // like `launchOneWorker` already refuses for a NEW run directory. This
+  // closes the easiest forgery (planting a complete, well-formed fake
+  // predecessor inside the worktree the worker itself can write to) but is
+  // explicitly NOT a defense against an unconfined malicious same-UID
+  // worker in general: such a worker can still write anywhere this
+  // conductor process can (e.g. directly under a configured capture root,
+  // if that root is not itself outside every worker-writable path, or by
+  // racing a legitimate predecessor's own directory before this check
+  // runs). A real guarantee needs an enforced filesystem/process boundary
+  // protecting conductor-owned metadata, or a different execution
+  // identity — same-UID alone never provides it.
+  if (Array.isArray(workerWritableRoots)) {
+    for (const root of workerWritableRoots) {
+      if (await realBeneath(root, prevRunDir)) fail('predecessor location is inside a worker-writable root');
+    }
+  }
+  if (!await inspect(prevRunDir, 'directory')) fail('predecessor run directory is missing');
+  const dirStat = await lstat(prevRunDir);
+  if (dirStat.uid !== process.getuid() || (dirStat.mode & 0o077)) fail('predecessor run directory is not privately owned');
+  let ownerBytes, invocationBytes, exitBytes;
+  try {
+    // #2915 review 4 (finding 4): `rejectInsecureMode: true` — an insecure
+    // mode on predecessor metadata REFUSES the retry instead of silently
+    // chmod-repairing it and proceeding (the former behaviour the review
+    // found: "the probe's 0666 files were accepted and changed to 0600").
+    ownerBytes = await boundedPrivateRead(join(prevRunDir, '.launch-owner'), 256, inspect, true, true);
+    invocationBytes = await boundedPrivateRead(join(prevRunDir, 'invocation.json'), 1048576, inspect, true, true);
+    exitBytes = await boundedPrivateRead(join(prevRunDir, 'exit.json'), 1048576, inspect, true, true);
+  } catch (error) { fail(`predecessor metadata is missing, insecurely-moded, or not a bounded, privately-owned, unaliased regular file (${error.message})`); }
+  if (ownerBytes.toString('utf8') !== prevId) fail('.launch-owner does not match retryOf.invocationId');
+  let invocationRecord, exitRecord;
+  try {
+    invocationRecord = JSON.parse(invocationBytes.toString('utf8'));
+    exitRecord = JSON.parse(exitBytes.toString('utf8'));
+  } catch { fail('predecessor metadata is not valid JSON'); }
+  if (invocationRecord?.invocationId !== prevId || invocationRecord?.origin !== 'launcher') {
+    fail('invocation.json identity does not match retryOf (or is not launcher-written)');
+  }
+  if (exitRecord?.invocationId !== prevId) fail('exit.json identity does not match retryOf');
+  if (newInvocationPath !== undefined) {
+    // #2915 review 4 (finding 4): the SAME stable task-chain identity
+    // `launchOneWorker` publishes — role/task/group plus the brief CONTENT
+    // digest, never `final_output`/`brief`/`workdir` PATHS, which legitimately
+    // differ between a confirmed predecessor and this fresh attempt.
+    let newTaskDigest, newPlan;
+    try {
+      const newPlanBytes = await boundedPrivateRead(newInvocationPath, 1048576, inspect);
+      newPlan = JSON.parse(newPlanBytes.toString('utf8'));
+      newTaskDigest = await stableTaskChainDigest(newPlan.request, newPlan.invocation?.briefDigest ?? null);
+    } catch { fail('new attempt plan is missing or invalid; cannot bind the retry to a task'); }
+    if (invocationRecord.taskDigest !== newTaskDigest && !await matchesLegacyTask(invocationRecord, newPlan)) fail('predecessor task does not match the new attempt (task-chain binding)');
+  }
+  if (exitRecord.termination !== 'confirmed') {
+    let evidence = null;
+    if (checkDescendants) {
+      try {
+        const processRecord = JSON.parse((await boundedPrivateRead(join(prevRunDir, 'process.json'), 65536, inspect, true, true)).toString('utf8'));
+        evidence = await recheckWorkerTermination({ processRecord, exitRecord });
+      } catch (error) { evidence = { confirmed: false, missing: `readable, private launcher process.json (${error.message})` }; }
+      if (evidence.confirmed) {
+        exitRecord = { ...exitRecord, termination: 'confirmed', descendants: 'none',
+          ...(exitRecord.health ? { health: { ...exitRecord.health, termination: 'confirmed' } } : {}) };
+        await publishWorkerRecord(prevRunDir, 'exit.json', exitRecord, inspect);
+      }
+    }
+    if (exitRecord.termination !== 'confirmed') {
+      assertStopBeforeRetry(exitRecord, { expectedInvocationId: prevId, runDir: prevRunDir, missing: evidence?.missing });
+    }
+  }
+  assertStopBeforeRetry(exitRecord, { expectedInvocationId: prevId });
+  return exitRecord;
+}

package/tools/ralph-external/lib/worker-termination.mjs

@@ -0,0 +1,82 @@
+// Confirm owned containment is empty independently of semantic observer coverage.
+import { sampleWorkerIdentity, isSafeWorkerGroupTarget } from '../process-monitor.mjs';
+import { getWorkerIsolationStatus } from './worker-isolation-status.mjs';
+import { scanWorkerInvocationProcesses } from './worker-invocation-processes.mjs';
+
+export function observeWorkerTermination({ mode, native, workerExited, identity,
+  supervisor = sampleWorkerIdentity(process.pid), kill = process.kill, invocationId,
+  scan = scanWorkerInvocationProcesses, deadline } = {}) {
+  if (mode === 'systemd-unit') {
+    const exited = workerExited === true || [1, 2, 3].includes(native?.execMainCode);
+    return { confirmed: exited && native?.active === false && native?.cgroupEmpty === true,
+      missing: !exited ? 'launcher-observed exit or unit ExecMainCode exit evidence' : native?.active !== false
+        ? 'unit inactive evidence' : native?.cgroupEmpty !== true ? 'empty unit cgroup (TasksCurrent=0)' : null };
+  }
+  if (!workerExited) return { confirmed: false, missing: 'launcher-observed worker exit' };
+  if (!identity || identity.pid !== identity.pgid || identity.uid !== process.getuid?.()
+    || !supervisor || identity.host !== supervisor.host || identity.bootId !== supervisor.bootId
+    || !isSafeWorkerGroupTarget(identity.pgid, supervisor)) {
+    return { confirmed: false, missing: 'launcher-owned process group identity on this host and boot' };
+  }
+  try { kill(-identity.pgid, 0); }
+  catch (error) {
+    // Pass the recorded leader so the marker scan can tell a parallel
+    // hardened (non-dumpable) worker's tree apart from a genuine escapee via
+    // readable stat/cgroup links instead of failing closed on every
+    // unreadable post-start process.
+    if (error.code === 'ESRCH') {
+      return scan({ invocationId, startTicks: identity.startTicks, uid: identity.uid, deadline,
+        workerPid: identity.pid, workerPgid: identity.pgid, workerSession: identity.sessionId });
+    }
+    return { confirmed: false, missing: `empty owned process group (signal-0 returned ${error.code ?? 'unknown'})` };
+  }
+  return { confirmed: false, missing: 'empty owned process group (signal-0 still finds members)' };
+}
+
+export function terminationRemedy(result, runDir) {
+  const missing = result?.isolation === 'systemd-unit'
+    ? 'unit exit, inactive state and empty cgroup (TasksCurrent=0)'
+    : 'launcher-observed worker exit, empty owned process group (kill(-pgid, 0) = ESRCH) and escaped-descendant evidence (bounded same-uid invocation-marker scan in Linux /proc)';
+  return `Missing evidence: ${missing}. Repeat the original --launch-worker${runDir ? ` --retry-of-run-dir ${JSON.stringify(runDir)}` : ' --retry-of-run-dir DIR'} or --verify-worker${runDir ? ` --run-dir ${JSON.stringify(runDir)}` : ' --run-dir DIR'} command with --check-descendants for a bounded descendant check (at most 2 seconds); live or unknown descendants still refuse linkage. Missing launcher-owned group identity requires the original launch owner to establish containment; worker-reported identity cannot authorize this check.`;
+}
+
+export async function recheckWorkerTermination({ processRecord, exitRecord,
+  status = getWorkerIsolationStatus, observe = observeWorkerTermination,
+  now = () => performance.now(), wait = ms => new Promise(resolve => setTimeout(resolve, ms)) }) {
+  if (processRecord?.invocationId !== exitRecord.invocationId || processRecord.origin !== 'launcher') {
+    return { confirmed: false, missing: 'matching launcher process.json' };
+  }
+  const local = sampleWorkerIdentity(process.pid);
+  if (!local || processRecord.supervisor?.host !== local.host || processRecord.supervisor?.bootId !== local.bootId
+    || processRecord.supervisor?.uid !== local.uid || processRecord.isolation !== exitRecord.isolation
+    || !['systemd-unit', 'native-sandbox', 'degraded'].includes(processRecord.isolation)) {
+    return { confirmed: false, missing: 'launcher containment identity on this host and boot' };
+  }
+  const identity = processRecord.identityObservation === 'stable-owned-group'
+    && processRecord.ownership === 'owned-group' ? processRecord.worker : null;
+  if (processRecord.isolation !== 'systemd-unit' && processRecord.invocationMarker !== processRecord.invocationId) {
+    return { confirmed: false, missing: 'escaped-descendant evidence: launcher-bound invocation marker in process.json' };
+  }
+  const deadline = now() + 2000;
+  // Both elapsed time and sample count bound the check, including injected clocks.
+  let evidence;
+  for (let attempt = 0; attempt < 21; attempt++) {
+    if (evidence && now() >= deadline) return evidence;
+    let native = null;
+    // Use the unit's retained exit state whenever a unit name is recorded,
+    // not only when the recorded mode already says systemd-unit: launch-mode
+    // selection is unchanged, but unit (cgroup) evidence is preferred
+    // wherever it is available. Non-unit modes still ignore it below.
+    if (typeof processRecord.unit === 'string' && processRecord.unit !== '') {
+      try { native = status(processRecord.unit, { timeoutMs: Math.max(1, Math.min(100, deadline - now())) }); }
+      catch { /* Unavailable is never empty. */ }
+    }
+    evidence = observe({ mode: processRecord.isolation, native, identity, invocationId: processRecord.invocationId,
+      deadline: Math.min(deadline, now() + 100),
+      workerExited: Number.isInteger(exitRecord.exitCode) && exitRecord.exitCode >= 0 && exitRecord.exitCode <= 255
+        || exitRecord.captureCoverage === 'complete' && exitRecord.workerTermination === 'confirmed' && /^SIG[A-Z0-9]+$/.test(exitRecord.signal ?? '') });
+    if (evidence.confirmed || evidence.markerPresent || now() >= deadline || attempt === 20) return evidence;
+    await wait(Math.min(100, Math.max(0, deadline - now())));
+  }
+  return evidence;
+}