@aiwg/cli 2026.10.9 → 2026.10.10

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

@@ -0,0 +1,209 @@
+/** Materialize bounded artifacts; quarantine entries before checking ownership or removing them. */
+import { constants } from 'node:fs';
+import { open, mkdir, mkdtemp, lstat, readdir, unlink, rmdir, rename } from 'node:fs/promises';
+import path from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+
+const { validateWorkerArtifacts } = await importImpl(import.meta.url, 'serve/worker-artifacts.mjs');
+const directoryFlags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+
+export async function materializeWorkerArtifacts(invocation, runDir) {
+  const artifacts = validateWorkerArtifacts(invocation);
+  const targets = new Map(artifacts.map(artifact => [artifact.name, artifact.location === 'workspace-relative'
+    ? path.join(invocation.cwd, artifact.relativePath) : path.join(runDir, `artifact-${artifact.name}`)]));
+  const argv = invocation.argv.map(token => {
+    if (!token.includes('${artifact:')) return token;
+    const match = /^\$\{artifact:([A-Za-z0-9][A-Za-z0-9_-]{0,63})\}$/.exec(token);
+    if (!match || !targets.has(match[1])) throw new Error('Undeclared worker artifact placeholder');
+    return targets.get(match[1]);
+  });
+  const handles = [], created = [], directories = [], filenames = new Map();
+  let cleaned = false, quarantine, quarantinePath, sequence = 0;
+  const remember = (handle, filename) => { handles.push(handle); if (filename) filenames.set(handle, filename); return handle; };
+  // Linux can address relocated pinned parents. Other POSIX hosts use checked
+  // paths, retaining artifacts if a parent's identity cannot be recovered.
+  const childPath = (parent, name) => process.platform === 'linux'
+    ? `/proc/self/fd/${parent.fd}/${name}` : path.join(filenames.get(parent), name);
+  async function pinDirectory(filename) {
+    if (!path.isAbsolute(filename) || path.normalize(filename) !== filename || filename.includes('\0')) throw new Error('Invalid worker artifact root');
+    let directory = remember(await open('/', directoryFlags), '/');
+    for (const component of filename.split('/').filter(Boolean)) {
+      const target = childPath(directory, component), resolved = path.join(filenames.get(directory), component);
+      directory = remember(await open(target, directoryFlags), resolved);
+    }
+    return directory;
+  }
+  async function rewalk(cwd, chain) {
+    let directory = await pinDirectory(cwd);
+    if (!sameFile(await directory.stat({ bigint: true }), chain[0].stat)) throw new Error('cwd changed');
+    for (const entry of chain.slice(1)) {
+      const target = childPath(directory, entry.component), filename = path.join(filenames.get(directory), entry.component);
+      const next = remember(await open(target, directoryFlags), filename);
+      if (!sameFile(await next.stat({ bigint: true }), entry.stat)
+        || !sameFile(await lstat(target, { bigint: true }), entry.stat)) throw new Error('ancestor changed');
+      directory = next;
+    }
+    return directory;
+  }
+  async function workspaceParent(root, relativePath) {
+    let directory = root;
+    const rootStat = await root.stat({ bigint: true });
+    const quarantineStat = await quarantine.stat({ bigint: true });
+    if (rootStat.dev !== quarantineStat.dev) throw new Error('Worker artifact quarantine must be on the cwd filesystem');
+    const chain = [{ stat: rootStat }];
+    const components = relativePath.split('/').slice(0, -1);
+    for (const [i, component] of components.entries()) {
+      const target = childPath(directory, component);
+      const invocationDirectory = i === components.length - 1;
+      let made = false;
+      // Rewalk BEFORE mkdir too; a pinned parent alone is not cwd authority.
+      await rewalk(invocation.cwd, chain);
+      try { await mkdir(target, { mode: 0o700 }); made = true; }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        if (invocationDirectory) throw Object.assign(new Error('Worker artifact directory collision (existing entry preserved)'), { code: 'EEXIST' });
+      }
+      const before = await lstat(target, { bigint: true });
+      const next = remember(await open(target, directoryFlags), path.join(filenames.get(directory), component));
+      const stat = await next.stat({ bigint: true });
+      try {
+        if (!before.isDirectory() || !sameFile(before, stat)) throw new Error('directory substituted');
+        if (made && (await readdir(childPath(next, '.'))).length) throw new Error('new directory is not empty');
+        const checkedParent = await rewalk(invocation.cwd, chain);
+        if (!sameFile(await lstat(childPath(checkedParent, component), { bigint: true }), stat)
+          || !sameFile(await lstat(target, { bigint: true }), stat)) throw new Error('directory substituted');
+      } catch (cause) { throw new Error('Worker artifact path changed; directory identity verification failed (unproven entry retained)', { cause }); }
+      if (stat.dev !== quarantineStat.dev) throw new Error('Worker artifact quarantine must share every parent filesystem');
+      // Only the verified invocation directory is owned. Leave shared prefixes.
+      if (invocationDirectory) directories.push({ target, stat, parent: directory });
+      chain.push({ component, stat });
+      directory = next;
+    }
+    return { directory, chain };
+  }
+  async function verifyPath(cwd, chain, leaf, identity) {
+    try {
+      // Re-open cwd from / as well: a relocated cwd descriptor is not authority.
+      const directory = await rewalk(cwd, chain);
+      const file = remember(await open(childPath(directory, leaf), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK));
+      if (!sameFile(await file.stat({ bigint: true }), identity)) throw new Error('leaf changed');
+    } catch (cause) { throw new Error('Worker artifact path changed; containment verification failed', { cause }); }
+  }
+  async function quarantineEntry(entry, directory = false) {
+    if (process.platform !== 'linux') {
+      try {
+        const current = await pinDirectory(filenames.get(entry.parent));
+        if (!sameFile(await current.stat({ bigint: true }), await entry.parent.stat({ bigint: true }))) throw new Error('parent identity mismatch');
+      } catch (cause) { throw new Error('Worker artifact parent changed; artifact retained', { cause }); }
+    }
+    const captured = childPath(quarantine, `entry-${sequence++}`);
+    // The source can change up to rename; inspect only the privately captured entry.
+    await rename(entry.target, captured);
+    if (!sameFile(await lstat(captured, { bigint: true }), entry.stat)) {
+      throw new Error(`Worker artifact replacement preserved in quarantine: ${quarantinePath}/${path.basename(captured)}`);
+    }
+    if (directory) await rmdir(captured); else await unlink(captured);
+  }
+  const closeHandles = async () => {
+    const results = await Promise.allSettled(handles.reverse().map(handle => handle.close()));
+    const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+    if (errors.length) throw new AggregateError(errors, 'Worker artifact descriptor close failed');
+  };
+  const cleanup = async ({ confirmedStop = true } = {}) => {
+    if (cleaned) return;
+    cleaned = true;
+    if (!confirmedStop) {
+      await closeHandles();
+      return { status: 'retained', reason: 'stop-proof-uncertain', paths: [...targets.values()] };
+    }
+    const errors = [];
+    try {
+      for (const [entries, directory] of [[created, false], [directories, true]]) {
+        for (const entry of entries.reverse()) {
+          try { await quarantineEntry(entry, directory); }
+          catch (error) { if (error.code !== 'ENOENT') errors.push(error); }
+        }
+      }
+      if (quarantinePath) {
+        try { await rmdir(quarantinePath); }
+        catch (error) { if (error.code !== 'ENOTEMPTY') errors.push(error); }
+      }
+    } finally {
+      try { await closeHandles(); } catch (error) { errors.push(error); }
+    }
+    if (errors.length) throw new AggregateError(errors, `Worker artifact cleanup failed; preserved entries: ${quarantinePath}`);
+  };
+  try {
+    const run = await pinDirectory(runDir);
+    const stat = await run.stat();
+    if (stat.uid !== process.getuid() || (stat.mode & 0o077)) throw new Error('Worker artifact directory must be private and owned');
+    if (artifacts.length) {
+      quarantinePath = await mkdtemp(childPath(run, '.artifact-quarantine-'));
+      quarantine = remember(await open(quarantinePath, directoryFlags), path.join(runDir, path.basename(quarantinePath)));
+      // Keep the diagnostic path meaningful after descriptors close.
+      quarantinePath = path.join(runDir, path.basename(quarantinePath));
+    }
+    let workspace;
+    for (const artifact of artifacts) {
+      let parent = run, chain;
+      let leaf = `artifact-${artifact.name}`;
+      if (artifact.location === 'workspace-relative') {
+        if (!workspace) {
+          const { realBeneath } = await importImpl(import.meta.url, 'serve/worker-invocation-paths.js');
+          if (await realBeneath(invocation.cwd, runDir)) throw new Error('Worker artifact quarantine must be outside worker-writable cwd');
+          workspace = await pinDirectory(invocation.cwd);
+        }
+        ({ directory: parent, chain } = await workspaceParent(workspace, artifact.relativePath));
+        leaf = path.basename(artifact.relativePath);
+      }
+      const target = childPath(parent, leaf);
+      let handle;
+      try { handle = await open(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+      catch (error) {
+        if (error.code === 'EEXIST') throw Object.assign(new Error(`Worker artifact collision: ${targets.get(artifact.name)} (existing file preserved)`), { code: 'EEXIST' });
+        throw error;
+      }
+      // Keep the descriptor until cleanup so an unlinked inode cannot be reused.
+      remember(handle);
+      const identity = await handle.stat({ bigint: true });
+      created.push({ target, stat: identity, parent });
+      if (chain) await verifyPath(invocation.cwd, chain, leaf, identity);
+      await handle.writeFile(artifact.content); await handle.sync();
+      if (chain) await verifyPath(invocation.cwd, chain, leaf, identity);
+    }
+    return { argv, cleanup };
+  } catch (error) {
+    try { await cleanup(); } catch (cleanupError) { throw new AggregateError([error, cleanupError], `${error.message}; worker artifact creation and cleanup failed`); }
+    throw error;
+  }
+}
+
+/** Gate artifact removal on launcher-owned stop evidence and report retention. */
+export class WorkerArtifactLifecycle {
+  constructor(invocation, invocationId = invocation.invocationId) {
+    this.invocationId = invocationId;
+    this.invocation = invocation;
+    this.confirmedStop = true; // Materialization precedes any dispatch.
+    this.result = null;
+  }
+  spawning() { this.confirmedStop = false; }
+  observe(name, value) {
+    if (name !== 'exit.json') return;
+    this.confirmedStop = value.invocationId === this.invocationId && value.termination === 'confirmed';
+    this.result = value;
+    if (this.invocation.artifacts?.length) value.artifactCleanup = this.status();
+  }
+  status() {
+    return this.confirmedStop ? { status: 'eligible' }
+      : { status: 'retained', reason: 'stop-proof-uncertain' };
+  }
+  failure(error) {
+    if (this.invocation.artifacts?.length && !this.confirmedStop) error.artifactCleanup = this.status();
+  }
+  async finish(artifacts) {
+    if (this.result?.termination === 'uncertain') this.confirmedStop = false;
+    if (this.result && this.invocation.artifacts?.length) this.result.artifactCleanup = this.status();
+    return artifacts?.cleanup({ confirmedStop: this.confirmedStop });
+  }
+}

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

@@ -0,0 +1,143 @@
+// Collect workerClaims candidates only after schema and on-disk artifact validation.
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+import { boundedPrivateRead, withWorkerPath } from './worker-inputs.mjs';
+import { parseStrictWorkerJson } from './strict-worker-json.mjs';
+
+const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const escapePointer = key => key.replace(/~/g, '~0').replace(/\//g, '~1');
+
+// The shared validator renders Ajv instancePath; required/additional fields
+// identify the child in params, rendered in its existing diagnostic text.
+function schemaDiagnostic(error) {
+  const match = /^(\/\S*) (must (?:have required|NOT have additional) propert(?:y|ies) '([^']+)'.*)$/.exec(error);
+  return match ? `${match[1] === '/' ? '' : match[1]}/${escapePointer(match[3])} ${match[2]}` : error;
+}
+
+async function artifactErrors(claims, workdir) {
+  const errors = [];
+  for (const [index, artifact] of claims.artifacts.entries()) {
+    const pointer = `/artifacts/${index}`;
+    const filename = resolve(workdir, artifact.path);
+    const within = relative(workdir, filename);
+    if (!within || within === '..' || within.startsWith('../') || isAbsolute(within) || artifact.path.includes('\0')) {
+      errors.push(`${pointer}/path Artifact must name a file beneath the worker tree`);
+      continue;
+    }
+    try {
+      // Pin every ancestor and refuse symlinks, hardlinks and special files.
+      const actual = await withWorkerPath(filename, async target => {
+        const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+          const before = await handle.stat({ bigint: true });
+          if (!before.isFile() || before.nlink !== 1n) throw new Error('Artifact must be an unaliased regular file');
+          const hash = createHash('sha256');
+          for await (const chunk of handle.createReadStream({ autoClose: false })) hash.update(chunk);
+          const after = await handle.stat({ bigint: true });
+          if (before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs) {
+            throw new Error('Artifact changed while hashing');
+          }
+          return `sha256:${hash.digest('hex')}`;
+        } finally { await handle.close(); }
+      });
+      if (actual !== artifact.digest) errors.push(`${pointer}/digest Artifact digest mismatch: expected ${artifact.digest}, actual ${actual}`);
+    } catch (error) {
+      errors.push(`${pointer}/path Cannot hash artifact in worker tree: ${error.message}`);
+    }
+  }
+  return errors;
+}
+
+export async function collectWorkerFinal({ path, workdir, driver, output, invocationId, result, inspect, handle, publish, outputFraming }) {
+  const { validateWorkerPayload, WORKER_MAX_JSON_BYTES, WORKER_MAX_NESTING_DEPTH, assertWorkerTerminal } =
+    await importImpl(import.meta.url, 'mission-protocol/index.js');
+  const scan = bytes => parseStrictWorkerJson(
+    new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes), WORKER_MAX_NESTING_DEPTH);
+  let finalBytes, extracted = false, parsedClaims, parseError;
+  const evidence = () => ({ invocationId, path, digest: finalBytes ? digest(finalBytes) : null,
+    source: extracted ? 'adapter-extraction' : 'worker-output', candidate: true, verified: false });
+  try {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > WORKER_MAX_JSON_BYTES) throw new Error('Invalid final output');
+    await inspect(path, 'file');
+    let claims;
+    if (stat.size === 0 && driver.extractFinal) {
+      claims = driver.extractFinal(output.toString('utf8'));
+      if (claims === null || claims === undefined || claims.success === false) throw new Error('Missing or unsuccessful final extraction');
+      const bytes = JSON.stringify({ invocationId, source: 'adapter-extraction', candidate: true, verified: false, result: claims });
+      if (Buffer.byteLength(bytes) > WORKER_MAX_JSON_BYTES) throw new Error('Final exceeds bound');
+      await handle.writeFile(bytes); extracted = true;
+    }
+    finalBytes = await boundedPrivateRead(path, WORKER_MAX_JSON_BYTES, inspect, true);
+    if (!finalBytes.length) throw new Error('Missing final output');
+    if (extracted) {
+      if (driver.parseWorkerFinal) {
+        try {
+          // The adapter owns framing (including text preambles) and strict
+          // decoding. Invoke it once with the launcher's actual exit status.
+          parsedClaims = await driver.parseWorkerFinal(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(output), {
+            format: outputFraming === 'jsonl' ? 'jsonl' : 'json', observation: { transport: 'shell',
+              status: result.exitCode === 0 && !result.errorCode && !result.timedOut ? 'completed' : 'failed',
+              termination: result.termination, exitCode: result.exitCode },
+            // Content validation precedes the independent terminal assertion
+            // below, so degraded termination cannot hide artifact mismatches.
+            assertTerminal: () => {},
+          });
+          claims = parsedClaims;
+        } catch (error) {
+          parseError = error;
+          // A decoded claims document must satisfy the schema. A non-claims
+          // text candidate retains exit-only evidence and a rejected strict
+          // parse; it can never authorize health completion or recovery.
+          if (/^Invalid workerClaims:|Duplicate worker JSON|nesting depth|byte bound/.test(error.message)) throw error;
+          claims = undefined;
+        }
+      } else {
+        // Without a strict adapter hook, scan original bytes before trusting
+        // synchronous extraction, which may have discarded duplicate keys.
+        if (outputFraming === 'jsonl') {
+          const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(output);
+          for (const line of text.split('\n')) if (line.trim()) scan(Buffer.from(line));
+        } else scan(output);
+      }
+    } else {
+      const decoded = scan(finalBytes);
+      claims = driver.extractFinal ? driver.extractFinal(finalBytes.toString('utf8')) : decoded;
+    }
+    if (!parseError) {
+      const validation = validateWorkerPayload('workerClaims', claims);
+      const errors = validation.errors.map(schemaDiagnostic);
+      if (validation.valid) errors.push(...await artifactErrors(claims, workdir));
+      if (errors.length) {
+        result.finalOutputErrors = errors;
+        throw new Error('Invalid workerClaims');
+      }
+    }
+  } catch (error) {
+    result.errorCode ??= 'FINAL_OUTPUT_INVALID';
+    // Preserve the existing missing/empty-final failure: there is no
+    // candidate document (and therefore no schema pointer) to record.
+    if (!finalBytes?.length) throw error;
+    // Adapter decoding uses assertValidWorkerPayload's existing rendered
+    // diagnostics; retain its pointers when validation fails inside it.
+    const schemaErrors = /^Invalid workerClaims: (.*)\.$/.exec(error.message)?.[1];
+    result.finalOutputErrors ??= schemaErrors ? schemaErrors.split('; ').map(schemaDiagnostic) : [`/ ${error.message}`];
+    await publish('final-evidence.json', { ...evidence(), terminalSuccess: false,
+      errorCode: 'FINAL_OUTPUT_INVALID', errors: result.finalOutputErrors });
+    throw error;
+  }
+  await publish('final-evidence.json', { ...evidence(),
+    terminalSuccess: result.exitCode === 0 && !result.timedOut && !result.errorCode });
+  // Reuse the adapter's content result without a second hook invocation.
+  // Keep the existing health path's terminal assertion independent of content.
+  const parseFinal = async (bytes, options) => {
+    if (!extracted) return driver.parseWorkerFinal(bytes, options);
+    if (parseError) throw parseError;
+    assertWorkerTerminal(options.observation);
+    return parsedClaims;
+  };
+  return { finalBytes, extracted, parseFinal };
+}

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

@@ -0,0 +1,55 @@
+// Read bounded worker inputs through pinned, no-follow directory handles.
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+
+// Linux directory handles pin each ancestor. O_NOFOLLOW on a pathname alone
+// cannot protect an ancestor that the worker replaces after inspection.
+export async function withWorkerPath(filename, operation) {
+  if (!isAbsolute(filename) || filename.includes('\0') || filename.split('/').includes('..')) throw new Error('Invalid worker path');
+  const components = filename.split('/').filter(Boolean);
+  const leaf = components.pop();
+  let directory = await open('/', constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try {
+    for (const component of components) {
+      const next = await open(`/proc/self/fd/${directory.fd}/${component}`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      await directory.close(); directory = next;
+    }
+    return await operation(`/proc/self/fd/${directory.fd}/${leaf ?? '.'}`);
+  } finally { await directory.close(); }
+}
+
+// #2915 review 4 (finding 4): `privateOutput: true` REPAIRS a loose mode
+// (chmod 0600) rather than rejecting it — correct for the worker's own
+// final-output file, which the launcher itself created and is free to
+// re-tighten. `rejectInsecureMode: true` additionally REFUSES a mode other
+// than exactly 0600 instead of repairing it, for evidence this launcher
+// did NOT create moments ago (retry predecessor metadata) — a 0666 file
+// there is itself a signal worth refusing on, not silently normalizing
+// away.
+export async function boundedPrivateRead(filename, limit, inspect, privateOutput = false, rejectInsecureMode = false) {
+  if (!await inspect(filename, 'file')) throw new Error('Required worker input is missing');
+  const handle = await withWorkerPath(filename, target => open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > limit) throw new Error('Worker input must be a bounded unaliased regular file');
+    if (privateOutput) {
+      if (stat.uid !== process.getuid()) throw new Error('Worker final must be conductor-owned');
+      if (rejectInsecureMode) {
+        if ((stat.mode & 0o777) !== 0o600) throw new Error('Worker input mode must already be exactly 0600; insecure modes are refused, not repaired');
+      } else {
+        await handle.chmod(0o600);
+      }
+    }
+    const buffer = Buffer.alloc(limit + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    if (length > limit) throw new Error('Worker input exceeds bound');
+    return buffer.subarray(0, length);
+  } finally { await handle.close(); }
+}
+

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)) {

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

@@ -0,0 +1,47 @@
+// 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 === '--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] [--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 (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;
+}