@aiwg/cli 2026.10.9 → 2026.10.11

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

@@ -42,50 +42,8 @@ import { buildSystemdClientEnv, resolveSystemdClient, resolveSystemdRun, CONNECT
 
 const UNIT_SAFE = /[^A-Za-z0-9:_.@-]/g;
 const transportBootstrapVariables = ['NODE_OPTIONS', 'NODE_PATH', 'LD_PRELOAD', 'LD_LIBRARY_PATH', 'LD_AUDIT', 'LD_DEBUG', 'LD_DEBUG_OUTPUT'];
-const nativeSandboxProbes = new Map();
-let nativeSandboxProbeSequence = 0;
-export const NATIVE_SANDBOX_UNAVAILABLE = 'OG_NATIVE_SANDBOX_UNAVAILABLE';
-
-export function workerNeedsNativeNamespaces(adapter, permissions = {}, platform = process.platform) {
-  return platform === 'linux' && adapter?.provider === 'codex'
-    && (permissions.transport ?? 'shell') === 'shell'
-    && ['read-only', 'workspace-write'].includes(permissions.sandbox ?? 'workspace-write');
-}
-
-export function nativeSandboxFailure(text) {
-  return /loopback: Failed RTM_NEWADDR: Operation not permitted|uid_map[^\n]*Operation not permitted/i.test(text);
-}
-
-export function nativeSandboxProbeMessage(result) {
-  return `${NATIVE_SANDBOX_UNAVAILABLE}: Native sandbox unavailable: restricted unprivileged user namespaces inside systemd user units (host AppArmor policy may restrict userns). Probe: ${String(result.detail ?? 'failed').replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 512)}. Select parallelism.groups.<group>.execution.launchMode="native-sandbox" with a verified enforcing CLI sandbox, or configure a host AppArmor allowance for the systemd worker launch path.`;
-}
-
-/** No inference: exercise user/network namespaces through the worker's unit and client environment path. */
-export function probeWorkerNativeSandbox({ spawn = spawnSync, env = process.env, envNames = ['PATH', 'HOME'], cwd,
-  cache = spawn === spawnSync ? nativeSandboxProbes : undefined } = {}) {
-  const key = JSON.stringify([cwd, [...envNames].sort()]);
-  if (cache?.has(key)) return cache.get(key);
-  let result;
-  try {
-    const managerEnvNames = resolveManagerEnvNames({ spawn });
-    const command = process.execPath;
-    const args = [fileURLToPath(import.meta.url), '--worker-environment', JSON.stringify(unitEnvironmentNames(envNames)),
-      '--', '/usr/bin/unshare', '--user', '--map-root-user', '--net', '/usr/bin/true'];
-    const argv = buildWorkerIsolationArgs({ unit: proposeWorkerUnitName(`sandbox-probe-${process.pid}-${++nativeSandboxProbeSequence}`),
-      command, args, cwd, env, envNames, managerEnvNames, memoryMaxGb: 0.25, attached: true,
-      extraProperties: ['RuntimeMaxSec=5s', 'TimeoutStopSec=1s'] });
-    const observed = spawn(resolveSystemdRun(), ['--collect', ...argv.slice(1)], {
-      encoding: 'utf8', timeout: 8000, maxBuffer: 4096, env: buildSystemdClientEnv({ env, envNames }) });
-    result = observed.status === 0 && !observed.error ? { ok: true, mode: 'systemd-unit' }
-      : { ok: false, mode: 'systemd-unit', code: NATIVE_SANDBOX_UNAVAILABLE,
-        detail: String(observed.error?.message ?? (String(observed.stderr ?? '').trim() || `exit ${observed.status}`)).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 512) };
-  } catch (error) {
-    result = { ok: false, mode: 'systemd-unit', code: NATIVE_SANDBOX_UNAVAILABLE,
-      detail: String(error.message).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 512) };
-  }
-  cache?.set(key, result);
-  return result;
-}
+export { NATIVE_SANDBOX_UNAVAILABLE, workerNeedsNativeNamespaces, nativeSandboxFailure,
+  nativeSandboxProbeMessage, probeWorkerNativeSandbox } from './worker-native-sandbox.mjs';
 
 /** Derive a unit-safe `aiwg-worker-<name>-<epoch>` unit name. */
 export function proposeWorkerUnitName(name, nowSeconds = Math.floor(Date.now() / 1000)) {
@@ -598,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
@@ -650,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

@@ -0,0 +1,49 @@
+// Parse one-shot launch options and derive retry IDs from launcher records.
+import { join, isAbsolute } from 'node:path';
+import { boundedPrivateRead } from './worker-inputs.mjs';
+
+export function parseWorkerLaunchArgs(args) {
+  const result = {};
+  const seen = new Set();
+  let retryOfInvocationId;
+  let retryOfRunDir;
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    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',
+      '--retry-of': '__retryOfInvocationId', '--retry-of-run-dir': '__retryOfRunDir' }[flag];
+    if (!key) throw new Error(`Unsupported worker launch option: ${flag}`);
+    const value = args[++i];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+    if (key === '__retryOfInvocationId') retryOfInvocationId = value;
+    else if (key === '__retryOfRunDir') retryOfRunDir = value;
+    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] [--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;
+}
+
+export async function resolveRetryReference(retryOf, { inspect }) {
+  if (!retryOf || typeof retryOf !== 'object' || retryOf.invocationId !== undefined) return retryOf;
+  if (!isAbsolute(retryOf.runDir ?? '')) throw new Error('Retry run directory must be absolute');
+  const bytes = await boundedPrivateRead(join(retryOf.runDir, 'invocation.json'), 1048576, inspect, true, true);
+  const record = JSON.parse(bytes.toString('utf8'));
+  if (record.origin !== 'launcher' || typeof record.invocationId !== 'string' || !record.invocationId) {
+    throw new Error('Retry predecessor invocation.json must contain a launcher invocationId');
+  }
+  // Derivation is not acceptance: verifyRetryPredecessor still checks ownership,
+  // task-chain identity, matching records, writable roots and confirmed stop.
+  return { ...retryOf, invocationId: record.invocationId };
+}

package/tools/ralph-external/lib/worker-native-sandbox.mjs

@@ -0,0 +1,83 @@
+/** Probe each CLI's native sandbox mechanism through the worker's transient unit. */
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { buildWorkerIsolationArgs, proposeWorkerUnitName, resolveManagerEnvNames } from './worker-isolation.mjs';
+import { buildSystemdClientEnv, resolveSystemdRun, unitEnvironmentNames } from './systemd-client.mjs';
+
+const nativeSandboxProbes = new Map();
+let sequence = 0;
+export const NATIVE_SANDBOX_UNAVAILABLE = 'OG_NATIVE_SANDBOX_UNAVAILABLE';
+
+/** Prefer the system bwrap allowed by Ubuntu's executable-specific AppArmor policy. */
+export function resolveWorkerBwrap({ env = process.env, executable = candidate => {
+  try { accessSync(candidate, constants.X_OK); return statSync(candidate).isFile(); } catch { return false; }
+} } = {}) {
+  for (const candidate of ['/usr/bin/bwrap', ...(env.PATH ?? '').split(path.delimiter)
+    .filter(directory => path.isAbsolute(directory)).map(directory => path.join(directory, 'bwrap'))]) {
+    if (executable(candidate)) return candidate;
+  }
+  throw new Error('bwrap is unavailable at /usr/bin/bwrap or on the worker PATH');
+}
+
+const bwrapProbe = options => ({ mechanism: 'bwrap', command: resolveWorkerBwrap(options),
+  args: ['--ro-bind', '/', '/', '--unshare-user', '--unshare-net', '--', '/usr/bin/true'] });
+
+// Hooks are owned by launcher code, never loaded from project configuration.
+export const workerNativeSandboxProbeHooks = { codex: bwrapProbe, muse: bwrapProbe };
+
+// CLIs without their own hook keep a generic user/network namespace probe: bwrap when the host
+// has it (allowed by Ubuntu's bwrap profile), else the previous unshare probe.
+const genericProbe = options => {
+  try { return bwrapProbe(options); }
+  catch { return { mechanism: 'unshare', command: '/usr/bin/unshare', args: ['--user', '--map-root-user', '--net', '/usr/bin/true'] }; }
+};
+
+export function workerNeedsNativeNamespaces(adapter, permissions = {}, platform = process.platform) {
+  return platform === 'linux' && Object.hasOwn(workerNativeSandboxProbeHooks, adapter?.provider ?? '')
+    && (permissions.transport ?? 'shell') === 'shell'
+    && ['read-only', 'workspace-write'].includes(permissions.sandbox ?? 'workspace-write');
+}
+
+export function nativeSandboxFailure(text) {
+  return /loopback: Failed RTM_NEWADDR: Operation not permitted|uid_map[^\n]*Operation not permitted/i.test(text);
+}
+
+const bounded = detail => String(detail).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 512);
+
+export function nativeSandboxProbeMessage(result) {
+  return `${NATIVE_SANDBOX_UNAVAILABLE}: Native sandbox unavailable: ${bounded(result.mechanism ?? 'CLI sandbox')} probe failed inside a systemd user unit. Probe: ${bounded(result.detail ?? 'failed')}. Verify that the named sandbox executable is installed and can create its sandbox in the worker unit environment.`;
+}
+
+/** Hooks return { mechanism, command, args }; the unit and environment path stay shared. */
+export function probeWorkerNativeSandbox({ adapter = { provider: 'codex' }, probeHooks = workerNativeSandboxProbeHooks,
+  spawn = spawnSync, env = process.env, envNames = ['PATH', 'HOME'], cwd,
+  cache = spawn === spawnSync ? nativeSandboxProbes : undefined } = {}) {
+  let mechanism = ['codex', 'muse'].includes(adapter.provider) ? 'bwrap' : `${adapter.provider} sandbox`;
+  let key;
+  let result;
+  try {
+    const hook = Object.hasOwn(probeHooks, adapter.provider) ? probeHooks[adapter.provider] : genericProbe;
+    const probe = hook({ env, cwd, adapter });
+    mechanism = probe.mechanism;
+    key = JSON.stringify([adapter.provider, probe, cwd, [...envNames].sort().map(name => [name, env[name]])]);
+    if (cache?.has(key)) return cache.get(key);
+    const managerEnvNames = resolveManagerEnvNames({ spawn });
+    const command = process.execPath;
+    const args = [fileURLToPath(new URL('./worker-isolation.mjs', import.meta.url)), '--worker-environment',
+      JSON.stringify(unitEnvironmentNames(envNames)), '--', probe.command, ...probe.args];
+    const argv = buildWorkerIsolationArgs({ unit: proposeWorkerUnitName(`sandbox-probe-${process.pid}-${++sequence}`),
+      command, args, cwd, env, envNames, managerEnvNames, memoryMaxGb: 0.25, attached: true,
+      extraProperties: ['RuntimeMaxSec=5s', 'TimeoutStopSec=1s'] });
+    const observed = spawn(resolveSystemdRun(), ['--collect', ...argv.slice(1)], {
+      encoding: 'utf8', timeout: 8000, maxBuffer: 4096, env: buildSystemdClientEnv({ env, envNames }) });
+    result = observed.status === 0 && !observed.error ? { ok: true, mode: 'systemd-unit', mechanism }
+      : { ok: false, mode: 'systemd-unit', mechanism, code: NATIVE_SANDBOX_UNAVAILABLE,
+        detail: bounded(observed.error?.message ?? (String(observed.stderr ?? '').trim() || `exit ${observed.status}`)) };
+  } catch (error) {
+    result = { ok: false, mode: 'systemd-unit', mechanism, code: NATIVE_SANDBOX_UNAVAILABLE, detail: bounded(error.message) };
+  }
+  if (key) cache?.set(key, result);
+  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;
+}