@aiwg/cli 2026.10.10 → 2026.10.11

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;
+}

package/tools/ralph-external/session-launcher.mjs

@@ -51,6 +51,9 @@ export { assertManagedWorkerLaunch } from './lib/managed-worker-attempt.mjs';
 import { buildSessionEnvironment } from './lib/session-environment.mjs';
 import { withWorkerPath, boundedPrivateRead } from './lib/worker-inputs.mjs';
 import { collectWorkerFinal } from './lib/worker-final.mjs';
+import { verifyRetryPredecessor } from './lib/worker-retry-evidence.mjs';
+import { observeWorkerTermination, terminationRemedy } from './lib/worker-termination.mjs';
+import { buildWorkerInvocationEnvironment, WORKER_INVOCATION_MARKER } from './lib/worker-invocation-processes.mjs';
 import { resolveRetryReference } from './lib/worker-launch-cli.mjs';
 import { launcherRecoveryEvidence, observeLauncherRecoveryOutcome, recordLauncherRecoveryHint } from './lib/launcher-recovery-evidence.mjs';
 export { observeLauncherRecoveryOutcome } from './lib/launcher-recovery-evidence.mjs';
@@ -375,6 +378,23 @@ async function launchOneWorker(owner, options) {
   const { assertConductorWorkerPlan } = await importImpl(import.meta.url, 'serve/worker-invocation-paths.js');
   await assertConductorWorkerPlan(saved, options.invocationPath, inputs.drivers);
   const invocation = await validate(saved, inputs.snapshot, inputs.drivers, now, options.invocationPath);
+  // #3685 round 2: the worker CLI's AIWG bootstrap must be present in the
+  // worker workdir before any spawn — a context-free worker would run with
+  // no project rules/skills/hooks. Opt-in per entry point (the
+  // `--launch-worker` CLI enables it via `options.ensureWorkerContext`);
+  // absent means "no ensure", never a default deploy, so pinned baselines
+  // and synthetic launches are unaffected. A failed ensure throws the
+  // typed `OG_WORKER_CONTEXT_UNAVAILABLE` diagnostic (with remedy) and the
+  // worker never spawns.
+  if (options.ensureWorkerContext) {
+    const { ensureWorkerContextForLaunch } = await import('./lib/worker-context.mjs');
+    await ensureWorkerContextForLaunch({
+      workdir: invocation.cwd,
+      cli: invocation.selected?.cli,
+      config: inputs.snapshot?.config ?? null,
+      ...(typeof options.ensureWorkerContext === 'object' ? options.ensureWorkerContext : {}),
+    });
+  }
   if (invocation.mode === 'managed' || options.managedAdmission) {
     const admitted = await assertManagedWorkerLaunch(options, invocation, inputs, options.projectRoot ?? process.cwd());
     options = { ...options, scopedBreaker: null, managedInvocationId: admitted.metadata.invocationId,
@@ -409,7 +429,7 @@ async function launchOneWorker(owner, options) {
   let verifiedPreviousAttemptId = null;
   if (options?.retryOf !== undefined) {
     const exitRecord = await verifyRetryPredecessor(await resolveRetryReference(options.retryOf, { inspect }),
-      { newInvocationPath: options?.invocationPath, inspect, workerWritableRoots: writableRoots });
+      { newInvocationPath: options?.invocationPath, inspect, workerWritableRoots: writableRoots, checkDescendants: options.checkDescendants });
     verifiedPreviousAttemptId = exitRecord.invocationId;
   }
   const paths = (await importImpl(import.meta.url, 'serve/worker-invocation-paths.js')).workerOutputPaths(invocation);
@@ -675,13 +695,13 @@ async function launchOneWorker(owner, options) {
       executedArgvDigest: qualificationDigest(artifacts.argv),
       artifacts: (invocation.artifacts ?? []).map(artifact => ({ name: artifact.name,
         byteLength: Buffer.byteLength(artifact.content), sha256: bytesDigest(artifact.content) })),
-      envNames: invocation.envNames, stdin: invocation.stdin,
+      envNames: [...new Set([...invocation.envNames, WORKER_INVOCATION_MARKER])], stdin: invocation.stdin,
       prompt: { path: invocation.briefPath, digest: invocation.briefDigest }, cwd: invocation.cwd,
       worktree: { path: invocation.cwd, baseRevision: null }, paths, captures, outputFraming: profile.health?.outputFraming ?? 'opaque',
       health: invocation.health ?? null, transport: invocation.transport,
       isolation: { mode: isolation.mode, memoryMaxGb: isolation.mode === 'native-sandbox' ? null : options.memoryMaxGb ?? 4 },
       limits: invocation.limits, maxOutputBytes: Math.min(invocation.maxOutputBytes ?? 10485760, 10485760) });
-    await publish('process.json', { invocationId, origin: 'launcher', supervisor, worker: null,
+    await publish('process.json', { invocationId, invocationMarker: invocationId, origin: 'launcher', supervisor, worker: null,
       launchTime, monotonicStart, ownership: 'unknown', isolation: isolation.mode });
     // All captures (including the reserved final) open successfully BEFORE spawn.
     for (const filename of [...Object.values(paths), ...Object.values(captures)]) {
@@ -695,8 +715,7 @@ async function launchOneWorker(owner, options) {
       paths: await Promise.all([invocation.cwd, runDir].map(workerDispatchPath)) });
     if (!gate.ok) throw workerDispatchRefusal(gate);
     if (bytesDigest(await boundedPrivateRead(invocation.briefPath, 262144, inspect)) !== invocation.briefDigest) throw new Error('Worker prompt changed before spawn');
-    const environment = Object.fromEntries(invocation.envNames.filter(name => process.env[name] !== undefined)
-      .map(name => [name, process.env[name]]));
+    const environment = buildWorkerInvocationEnvironment(invocation.envNames, invocationId);
     const baselineContent = await sampleOwnedWorktreeContent(invocation.cwd, { files: options.healthArtifacts });
     // #2915 round 8 (D2, replaces the former "debit immediately before this
     // call" comment): the ledger debit now happens INSIDE the dispatch-
@@ -757,7 +776,7 @@ async function launchOneWorker(owner, options) {
       command: artifacts.argv[0], args: artifacts.argv.slice(1), cwd: invocation.cwd,
       memoryMaxGb: options.memoryMaxGb ?? 4, gate, config: inputs.snapshot.config, isolation, workerGroup: invocation.selected.group,
       allowDegraded: !!options.allowDegraded, attached: true, ownedGroup: true,
-      env: environment, envNames: invocation.envNames, stdin: invocation.stdin, runDir,
+      ...environment, stdin: invocation.stdin, runDir,
       ...(onDispatchCommit ? { onDispatchCommit } : {}) });
     outcome = typeof launchResult?.then === 'function' ? await launchResult : launchResult;
     if (!outcome?.child) throw workerLaunchRefusal(outcome);
@@ -1088,7 +1107,7 @@ async function captureOneWorker(owner, ctx) {
   for (const stream of streams) stream.on('error', () => { errorCode = 'CAPTURE_WRITE'; stop(); });
   child.stdin?.on('error', error => { if (error.code !== 'EPIPE') { errorCode = 'STDIN_WRITE'; stop(); } });
   child.stdin?.end(ctx.stdinBytes ?? undefined);
-  const recordProcess = () => publish('process.json', { invocationId, origin: 'launcher', supervisor,
+  const recordProcess = () => publish('process.json', { invocationId, invocationMarker: invocationId, origin: 'launcher', supervisor,
     transportProcess: hasTransport ? sampleWorkerIdentity(child.pid) : null,
     nativeSupervisor,
     worker: identity ?? reportedWorker, identityObservation, launchTime, monotonicStart, ownership: identity ? 'owned-group' : 'unknown',
@@ -1113,12 +1132,14 @@ async function captureOneWorker(owner, ctx) {
     await drainChildStdio(child, graceMs);
     child.stdout.destroy(); child.stderr.destroy(); child.stdin?.destroy(); child.unref();
     for (const stream of streams) await new Promise(resolve => { if (stream.destroyed) resolve(); else stream.end(resolve); });
-    const native = outcome.mode === 'systemd-unit' ? readNative() : null;
+    // Prefer the unit's retained state whenever a unit name is recorded
+    // (#3674 round 4): launch-mode selection is unchanged, but unit (cgroup)
+    // evidence is used wherever it is available.
+    const native = outcome.unit ? readNative() : null;
     const members = identity ? sampleWorkerGroup(identity.pgid) : null;
-    // An unconfined group can escape via setsid. Empty PGID alone never proves
-    // descendant termination; keep the explicit degraded stop uncertain.
-    const confirmed = outcome.mode === 'systemd-unit' ? native?.active === false && [1, 2, 3].includes(native.execMainCode)
-      : child.pid === undefined;
+    // Require positive kernel evidence of owned containment being empty.
+    const confirmed = (outcome.mode !== 'systemd-unit' && child.pid === undefined) || observeWorkerTermination({ mode: outcome.mode, native,
+      workerExited: sawExit, identity, supervisor, invocationId }).confirmed;
     // `worker-exit.json`/`worker-identity.json` are written into a directory
     // the worker itself can reach (same UID, no filesystem confinement), so a
     // worker can plant either file before the trusted transport ever writes
@@ -1154,7 +1175,7 @@ async function captureOneWorker(owner, ctx) {
       : outcome.mode === 'systemd-unit' && native?.execMainCode === 1 ? native.execMainStatus : waitCode;
     const result = { invocationId, exitCode, signal: resultSignal,
       endedAt: new Date().toISOString(), termination: confirmed ? 'confirmed' : 'uncertain',
-      descendants: confirmed ? 'stopped' : 'unknown', timedOut: resultTimedOut,
+      descendants: confirmed ? 'none' : 'unknown', timedOut: resultTimedOut,
       cancelled: stopReason === 'CANCELLED', stopReason, errorCode: errorCode ?? null, capturedBytes: Math.min(total, output.length),
       // Unauthenticated: reported by the worker-writable transport record, not
       // kernel-observed. Never used above for exitCode/signal/termination.
@@ -1173,9 +1194,8 @@ async function captureOneWorker(owner, ctx) {
     // ExecMainCode/Status when applicable, launcher-detected errors,
     // timeout and explicit cancellation) — never worker stderr/stdout text
     // or worker-writable records. A degraded-isolation attempt can reach
-    // 'succeeded' here even though its `termination` stays 'uncertain'
-    // forever (no descendant-stop confirmation is possible without a
-    // systemd unit) — this is exactly the #2915 final-review fix: "give
+    // 'succeeded' here even when descendant-stop evidence is unavailable.
+    // This preserves the #2915 final-review fix: "give
     // degraded successful execution a valid recovery-success path without
     // falsely declaring descendant termination confirmed."
     const directChildCleanExit = sawExit && waitCode === 0 && waitSignal == null;
@@ -1555,13 +1575,13 @@ async function launchOneWorkerBaseline(owner, options, ctx) {
       executedArgvDigest: qualificationDigest(artifacts.argv),
       artifacts: (invocation.artifacts ?? []).map(artifact => ({ name: artifact.name,
         byteLength: Buffer.byteLength(artifact.content), sha256: bytesDigest(artifact.content) })),
-      envNames: invocation.envNames, stdin: invocation.stdin,
+      envNames: [...new Set([...invocation.envNames, WORKER_INVOCATION_MARKER])], stdin: invocation.stdin,
       prompt: { path: invocation.briefPath, digest: invocation.briefDigest }, cwd: invocation.cwd,
       worktree: { path: invocation.cwd, baseRevision: null }, paths, captures, outputFraming: profile.health?.outputFraming ?? 'opaque',
       health: invocation.health ?? null, transport: invocation.transport,
       isolation: { mode: isolation.mode, memoryMaxGb: isolation.mode === 'native-sandbox' ? null : options.memoryMaxGb ?? 4 },
       limits: invocation.limits, maxOutputBytes: Math.min(invocation.maxOutputBytes ?? 10485760, 10485760) });
-    await publish('process.json', { invocationId, origin: 'launcher', supervisor, worker: null,
+    await publish('process.json', { invocationId, invocationMarker: invocationId, origin: 'launcher', supervisor, worker: null,
       launchTime, monotonicStart, ownership: 'unknown', isolation: isolation.mode });
     // All captures (including the reserved final) open successfully BEFORE spawn.
     for (const filename of [...Object.values(paths), ...Object.values(captures)]) {
@@ -1575,8 +1595,7 @@ async function launchOneWorkerBaseline(owner, options, ctx) {
       paths: await Promise.all([invocation.cwd, runDir].map(workerDispatchPath)) });
     if (!localGate.ok) throw workerDispatchRefusal(localGate);
     if (bytesDigest(await boundedPrivateRead(invocation.briefPath, 262144, inspect)) !== invocation.briefDigest) throw new Error('Worker prompt changed before spawn');
-    const environment = Object.fromEntries(invocation.envNames.filter(name => process.env[name] !== undefined)
-      .map(name => [name, process.env[name]]));
+    const environment = buildWorkerInvocationEnvironment(invocation.envNames, invocationId);
     const baselineContent = await sampleOwnedWorktreeContent(invocation.cwd, { files: options.healthArtifacts });
     // The real `launchIsolatedWorker`, called with no `onDispatchCommit`
     // (never passed anywhere in this frozen function), is synchronous —
@@ -1598,7 +1617,7 @@ async function launchOneWorkerBaseline(owner, options, ctx) {
         options.managedDeadlineAtMs = Math.min(options.managedDeadlineAtMs, admitted.deadlineAtMs);
       } } : {}),
       ...(options.managedAdmission ? { onSpawnAttempt: () => { managedSpawnAttempted = true; } } : {}),
-      env: environment, envNames: invocation.envNames, stdin: invocation.stdin, runDir });
+      ...environment, stdin: invocation.stdin, runDir });
     outcome = typeof launchResult?.then === 'function' ? await launchResult : launchResult;
     if (!outcome?.child) throw workerLaunchRefusal(outcome);
     return await captureOneWorkerBaseline(owner, { child: outcome.child, outcome, invocation, invocationId, supervisor,
@@ -1757,7 +1776,7 @@ async function captureOneWorkerBaseline(owner, ctx) {
   for (const stream of streams) stream.on('error', () => { errorCode = 'CAPTURE_WRITE'; stop(); });
   child.stdin?.on('error', error => { if (error.code !== 'EPIPE') { errorCode = 'STDIN_WRITE'; stop(); } });
   child.stdin?.end(ctx.stdinBytes ?? undefined);
-  const recordProcess = () => publish('process.json', { invocationId, origin: 'launcher', supervisor,
+  const recordProcess = () => publish('process.json', { invocationId, invocationMarker: invocationId, origin: 'launcher', supervisor,
     transportProcess: hasTransport ? sampleWorkerIdentity(child.pid) : null,
     nativeSupervisor,
     worker: identity ?? reportedWorker, identityObservation, launchTime, monotonicStart, ownership: identity ? 'owned-group' : 'unknown',
@@ -1783,10 +1802,13 @@ async function captureOneWorkerBaseline(owner, ctx) {
     await drainChildStdio(child, graceMs);
     child.stdout.destroy(); child.stderr.destroy(); child.stdin?.destroy(); child.unref();
     for (const stream of streams) await new Promise(resolve => { if (stream.destroyed) resolve(); else stream.end(resolve); });
-    const native = outcome.mode === 'systemd-unit' ? readNative() : null;
+    // Prefer the unit's retained state whenever a unit name is recorded
+    // (#3674 round 4): launch-mode selection is unchanged, but unit (cgroup)
+    // evidence is used wherever it is available.
+    const native = outcome.unit ? readNative() : null;
     const members = identity ? sampleWorkerGroup(identity.pgid) : null;
-    const confirmed = outcome.mode === 'systemd-unit' ? native?.active === false && [1, 2, 3].includes(native.execMainCode)
-      : child.pid === undefined;
+    const confirmed = (outcome.mode !== 'systemd-unit' && child.pid === undefined) || observeWorkerTermination({ mode: outcome.mode, native,
+      workerExited: sawExit, identity, supervisor, invocationId }).confirmed;
     const workerExit = hasTransport ? await transportRecord('worker-exit.json') : null;
     if (!identity && hasTransport && nativeSupervisor) {
       const workerStart = await transportRecord('worker-identity.json');
@@ -1805,7 +1827,7 @@ async function captureOneWorkerBaseline(owner, ctx) {
     const result = { invocationId, exitCode, signal: resultSignal,
       ...(options.managedAdmission ? { managedAdmission: options.managedAdmission } : {}),
       endedAt: new Date().toISOString(), termination: confirmed ? 'confirmed' : 'uncertain',
-      descendants: confirmed ? 'stopped' : 'unknown', timedOut: resultTimedOut,
+      descendants: confirmed ? 'none' : 'unknown', timedOut: resultTimedOut,
       cancelled: stopReason === 'CANCELLED', stopReason, errorCode: errorCode ?? null, capturedBytes: Math.min(total, output.length),
       workerTermination: hasTransport ? workerExit && !workerExit.errorCode ? 'confirmed' : 'uncertain' : sawExit ? 'confirmed' : 'uncertain',
       workerReportedExit: workerExit ? { exitCode: workerExit.exitCode, signal: workerExit.signal, errorCode: workerExit.errorCode ?? null } : null,
@@ -2015,13 +2037,13 @@ export const UNBOUND_RETRY_EVIDENCE_CODE = 'UNBOUND_RETRY_EVIDENCE';
  * retry and is surfaced with a code the conductor can act on — it must never
  * silently spawn a duplicate writer.
  */
-export function stopBeforeRetryGate(previousResult, { expectedInvocationId = null } = {}) {
+export function stopBeforeRetryGate(previousResult, { expectedInvocationId = null, runDir, missing } = {}) {
   if (previousResult?.termination !== 'confirmed') {
     return {
       ok: false,
       code: STOP_BEFORE_RETRY_CODE,
       reason: `Previous attempt termination is '${previousResult?.termination ?? 'unknown'}', not confirmed: `
-        + 'retry is blocked until owned stop is proven (no duplicate writer while the old tree may continue).',
+        + 'retry is blocked until owned stop is proven (no duplicate writer while the old tree may continue). ' + (missing ? `Missing: ${missing}. ` : '') + terminationRemedy(previousResult, runDir),
       previousResult: previousResult === undefined ? undefined : (previousResult ?? null),
     };
   }
@@ -3138,74 +3160,7 @@ export async function releaseLedgerPolicy({ captureRoot, taskChainDigest } = {})
  * Returns the predecessor's verified `exit.json` record on success; throws
  * on any refusal.
  */
-export async function verifyRetryPredecessor(retryOf, { newInvocationPath, inspect, workerWritableRoots } = {}) {
-  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;
-    try {
-      const newPlanBytes = await boundedPrivateRead(newInvocationPath, 1048576, inspect);
-      const 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) fail('predecessor task does not match the new attempt (task-chain binding)');
-  }
-  assertStopBeforeRetry(exitRecord, { expectedInvocationId: prevId });
-  return exitRecord;
-}
+export { verifyRetryPredecessor } from './lib/worker-retry-evidence.mjs';
 
 /**
  * One corrected startup retry (#2915, 03 §11.5 step 1). A failed start may