@aiwg/cli 2026.10.9 → 2026.10.11

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

@@ -0,0 +1,237 @@
+/**
+ * Worker AIWG context loading and launch-time ensure, tools side (#3685).
+ *
+ * The provider-set UNION lives in `src/config/worker-context.ts` and the
+ * config loads through the existing `readAiwgConfig` loader (never ad-hoc
+ * JSON). Both cross the tools/src boundary through `importImpl`, so this
+ * module stays runnable from an installed package (`dist/src`) and a
+ * checkout (`src/`); every such seam is injectable for synthetic tests.
+ * `src/` must never import `tools/`, so the src module is always the
+ * callee, never the caller.
+ *
+ * Also home to the single-pass deploy, section verifier, and
+ * skip-worktree helpers extracted from `worktree-preparation.mjs` (which
+ * re-exports them) so that file stays agent-friendly.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+
+/** Load the project config through the existing loader. */
+async function defaultReadConfig(repoRoot) {
+  const { readAiwgConfig } = await importImpl(import.meta.url, 'config/aiwg-config.js');
+  return readAiwgConfig(repoRoot);
+}
+
+/** Resolve the provider union through the src-side pure function. */
+async function defaultResolveFromConfig(config) {
+  const { resolveWorkerContextProvidersFromConfig } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return resolveWorkerContextProvidersFromConfig(config);
+}
+
+/** Map one orchestration CLI id through the src-side registry mapping. */
+async function defaultMapCli(cli, parallelism) {
+  const { mapCliToProviderId } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return mapCliToProviderId(cli, parallelism);
+}
+
+/**
+ * Resolve the worker-context provider set (#3685 round 2): the union of
+ * `.aiwg/aiwg.config` `providers` and every CLI configured for
+ * orchestration (`parallelism.clis` keys/adapters and the `cli` of every
+ * `parallelism.groups.*.members[]`), mapped through the provider
+ * registry. An explicit list wins and is returned verbatim.
+ *
+ * @returns {Promise<{providers: string[], skipped: string[]}>}
+ */
+export async function resolveWorkerContextProviders({ repoRoot, providers = null, readConfig = null, resolveFromConfig = null } = {}) {
+  if (providers !== null && providers !== undefined) {
+    if (!Array.isArray(providers) || providers.length === 0
+      || providers.some(p => typeof p !== 'string' || p.length === 0 || p.includes('\0') || p.includes(','))) {
+      throw new Error('worker context providers must be a non-empty array of provider ids');
+    }
+    return { providers: [...new Set(providers)], skipped: [] };
+  }
+  if (typeof repoRoot !== 'string' || !repoRoot) {
+    throw new Error('worker context providers need a repoRoot or an explicit provider list');
+  }
+  const config = await (readConfig ?? defaultReadConfig)(repoRoot);
+  if (!config) {
+    throw new Error(`worker context deployment needs configured providers: cannot read ${path.join(repoRoot, '.aiwg', 'aiwg.config')} (missing or invalid); configure providers and orchestration CLIs, or pass an explicit provider list`);
+  }
+  return (resolveFromConfig ?? defaultResolveFromConfig)(config);
+}
+
+/**
+ * Ensure a worker workdir carries its CLI's AIWG bootstrap before launch.
+ * Resolves the worker CLI to its provider (from the project config, so
+ * orchestration CLIs map through the registry), checks presence, and
+ * deploys through the same one-pass helper when missing. The deploy
+ * target is always exactly `workdir` — never anywhere else.
+ *
+ * Injectable for synthetic tests: `ensureFn` stubs the whole ensure,
+ * otherwise `mapCli`, `readConfig`, `resolveFromConfig`, `deployFn`,
+ * `statusFn`, and `skipWorktreeFn` stub each seam.
+ *
+ * @returns {Promise<{ensured: boolean, provider: string, providers: string[], skippedBridges: string[], skipped: string[]}>}
+ */
+export async function ensureWorkerContextForLaunch({
+  workdir,
+  cli,
+  config = null,
+  repoRoot = null,
+  providers = null,
+  readConfig = null,
+  resolveFromConfig = null,
+  mapCli = null,
+  ensureFn = null,
+  statusFn = null,
+  deployFn = null,
+  skipWorktreeFn = null,
+  aiwgBin = process.env.AIWG_BIN ?? 'aiwg',
+} = {}) {
+  if (typeof workdir !== 'string' || !workdir) throw new Error('worker context ensure needs a workdir');
+  if (typeof cli !== 'string' || !cli) throw new Error('worker context ensure needs the worker CLI id');
+  let resolved = Array.isArray(providers) && providers.length > 0 ? { providers: [...new Set(providers)], skipped: [] } : null;
+  let loaded = config ?? null;
+  if (!resolved) {
+    if (!loaded && repoRoot) loaded = await (readConfig ?? defaultReadConfig)(repoRoot);
+    if (loaded) {
+      resolved = await (resolveFromConfig ?? defaultResolveFromConfig)(loaded);
+    }
+  }
+  const map = mapCli ?? defaultMapCli;
+  const mapped = await map(cli, loaded?.parallelism ?? null);
+  if (!('provider' in mapped) || !mapped.provider) {
+    // Typed-shaped refusal without importing the src error class (which
+    // would couple this sync-throwing path to the compiled `dist`
+    // layout): callers discriminate on `code`, never `instanceof`.
+    throw Object.assign(
+      new Error(`cannot ensure worker context: CLI '${cli}' maps to no AIWG provider (${mapped.skipped ?? 'unmapped'})`),
+      { code: 'OG_WORKER_CONTEXT_UNAVAILABLE',
+        remedy: `configure parallelism.clis.${cli} with a providers:<id> adapter, or use a CLI whose adapter maps to a known provider`,
+        workdir },
+    );
+  }
+  const provider = mapped.provider;
+  const deployProviders = resolved ? [...new Set([...resolved.providers, provider])] : [provider];
+  const ensure = ensureFn ?? (async (opts) => {
+    const { ensureWorkerContextBootstrap } = await importImpl(import.meta.url, 'config/worker-context.js');
+    return ensureWorkerContextBootstrap(opts);
+  });
+  const outcome = await ensure({
+    workdir, provider, providers: deployProviders, aiwgBin,
+    ...(statusFn ? { statusFn } : {}),
+    ...(deployFn ? { deployFn } : {}),
+    ...(skipWorktreeFn ? { skipWorktreeFn } : {}),
+  });
+  return { ...outcome, provider, skipped: resolved?.skipped ?? [] };
+}
+
+/** Materialize the union set into the worktree config through the src-side sync. */
+async function defaultSyncProviders(worktreePath, providers) {
+  const { syncWorkerContextProviders } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return syncWorkerContextProviders({ workdir: worktreePath, providers });
+}
+
+/** Single-pass argv through the src-side canonical builder (never `--providers`). */
+async function defaultDeployArgv(providers, worktreePath) {
+  const { buildWorkerContextDeployArgs } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return buildWorkerContextDeployArgs({ providers, target: worktreePath });
+}
+
+/**
+ * Default single-pass AIWG context deploy (#3685): sync the union set
+ * into the worktree config, then one `aiwg use all --target <worktree>`
+ * covering every configured provider. Never one deploy per provider:
+ * per-provider invocations rewrite AGENTS.md piecemeal and clobber each
+ * other's rule sections, while a single pass keeps them all. No
+ * `--providers` flag: it never reaches project-scope deploys
+ * (`executeCore` resolves from config), so the configured-provider path
+ * above is the supported mechanism. Injectable via
+ * `prepareWorkerWorktree()`'s `deployContextFn` for synthetic tests;
+ * `syncFn` stubs the config sync as `(worktreePath, providers)` and
+ * `argvFn` stubs the argv builder as `(providers, target)`.
+ *
+ * @returns {Promise<{providers: string[]}>}
+ */
+export async function defaultDeployWorkerContext({ worktreePath, providers, aiwgBin = 'aiwg', spawn = spawnSync, timeoutMs = 300000, syncFn = null, argvFn = null } = {}) {
+  if (typeof worktreePath !== 'string' || !worktreePath || typeof aiwgBin !== 'string' || !aiwgBin) {
+    throw new Error('worker context deploy requires a worktree path and an aiwg binary');
+  }
+  if (!Array.isArray(providers) || providers.length === 0) {
+    throw new Error('worker context deploy requires a non-empty provider list');
+  }
+  const sync = syncFn ?? defaultSyncProviders;
+  const synced = await sync(worktreePath, providers);
+  const syncedProviders = Array.isArray(synced?.providers) && synced.providers.length > 0 ? synced.providers : [...providers];
+  const buildArgv = argvFn ?? defaultDeployArgv;
+  const argv = await buildArgv(syncedProviders, worktreePath);
+  const result = spawn(aiwgBin, argv, { cwd: worktreePath, encoding: 'utf8', timeout: timeoutMs });
+  if (result.error) throw new Error(`aiwg ${argv.join(' ')} failed to run: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error(`aiwg ${argv.join(' ')} exited ${result.status}: ${String(result.stderr ?? '').trim().slice(0, 2000)}`);
+  }
+  return { providers: [...syncedProviders] };
+}
+
+/** AIWG-managed rule-section markers written into a deployed AGENTS.md. */
+const WORKER_CONTEXT_RULE_MARKER = /<!--\s*AIWG:[A-Za-z0-9_-]+:(start|end)\s*-->/;
+
+/**
+ * Verify a prepared worktree actually carries AIWG rule sections (#3685):
+ * the worktree's AGENTS.md must exist and contain AIWG-managed section
+ * markers. Throws before launch otherwise — a worktree without them would
+ * run the worker with no project rules/skills/hooks. Injectable via
+ * `prepareWorkerWorktree()`'s `verifyContextFn` for synthetic tests.
+ *
+ * @returns {{verified: boolean, providers: string[]}}
+ */
+export function verifyWorkerContextSections({ worktreePath, providers = [] } = {}) {
+  const agentsMd = path.join(worktreePath, 'AGENTS.md');
+  let content;
+  try {
+    content = readFileSync(agentsMd, 'utf8');
+  } catch {
+    throw new Error(`worker context verification failed: ${agentsMd} is missing; the worker would run without AIWG rule sections`);
+  }
+  if (!WORKER_CONTEXT_RULE_MARKER.test(content)) {
+    throw new Error(`worker context verification failed: ${agentsMd} has no AIWG rule sections (expected <!-- AIWG:<rule>:start --> markers for ${[...providers].join(',') || 'the configured providers'})`);
+  }
+  return { verified: true, providers: [...providers] };
+}
+
+/**
+ * Tracked files the context deploy modified, so the caller can hide them
+ * from the worker diff. Parses `git status --porcelain=v1` with untracked
+ * files excluded: every remaining entry is a tracked modification (the
+ * fresh worktree starts clean, so each one is deploy-caused).
+ *
+ * @returns {string[]} Repo-relative paths of tracked-modified files.
+ */
+export function listDeployDirtiedBridges({ worktreePath, spawn = spawnSync, timeoutMs = 30000 } = {}) {
+  // Raw spawn output, never a trimmed helper: trim would eat the
+  // significant leading space of the first porcelain line (` M AGENTS.md`
+  // trims to `M AGENTS.md`, shifting slice(3) one byte into the filename).
+  const result = spawn('git', ['status', '--porcelain=v1', '--untracked-files=no'], { cwd: worktreePath, encoding: 'utf8', timeout: timeoutMs });
+  if (result.error) throw new Error(`git status failed to run: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error(`git status exited ${result.status}: ${String(result.stderr ?? '').trim()}`);
+  }
+  const files = [];
+  for (const line of String(result.stdout ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    // `XY PATH` or `XY ORIG -> NEW` for renames; take the new path, which is
+    // what the worker diff would report.
+    const raw = line.slice(3);
+    const arrow = raw.indexOf(' -> ');
+    const rel = arrow >= 0 ? raw.slice(arrow + 4) : raw;
+    // Porcelain quotes paths with special bytes; a deploy that creates such
+    // a name is refused rather than mis-flagged.
+    if (!rel || rel.startsWith('"')) throw new Error(`worker context deploy dirtied an unflaggeable path: ${line}`);
+    files.push(rel);
+  }
+  return files;
+}

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-invocation-ancestry.mjs

@@ -0,0 +1,132 @@
+// Classify unreadable same-uid processes as possible escaped worker descendants or unrelated trees.
+import { constants } from 'node:fs';
+
+// Ancestry walks stay bounded: a pathological ppid chain can never turn this
+// proof into an unbounded scan. Depth and the caller's time bound both apply.
+export const MAX_WORKER_ANCESTRY_DEPTH = 32;
+
+const vanished = error => ['ENOENT', 'ESRCH'].includes(error?.code);
+
+function readSmallFile(fs, filename, maxBytes = 4096) {
+  let fd;
+  try {
+    fd = fs.openSync(filename, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    const buffer = Buffer.alloc(maxBytes + 1);
+    const chunks = [];
+    let bytes = 0;
+    for (;;) {
+      const size = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (!size) break;
+      chunks.push(buffer.subarray(0, size));
+      bytes += size;
+      if (bytes > maxBytes) return { tooLarge: true };
+    }
+    return { text: Buffer.concat(chunks).toString('utf8') };
+  } catch (error) { return { error }; }
+  finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+// Parse the link fields of /proc/<pid>/stat: ppid, process group, session and
+// start time. The comm field may contain spaces and parentheses, so field 3
+// begins after its LAST ')'. Returns null when the text is malformed.
+export function parseProcStatLink(text) {
+  if (typeof text !== 'string') return null;
+  const end = text.lastIndexOf(')');
+  if (end < 0) return null;
+  const fields = text.slice(end + 1).trim().split(/\s+/);
+  if (fields.length < 20) return null;
+  const [ppid, pgrp, session] = [fields[1], fields[2], fields[3]].map(Number);
+  const start = fields[19];
+  if (![ppid, pgrp, session].every(Number.isSafeInteger) || typeof start !== 'string' || !/^\d+$/.test(start)) return null;
+  return { ppid, pgrp, session, start };
+}
+
+// Read /proc/<pid>/cgroup verbatim (cgroup membership stays readable for
+// non-dumpable processes). Normalized like sampleProcessCgroup: the bare path
+// for the unified hierarchy, raw content otherwise. Null when unreadable.
+export function readProcCgroup(fs, path) {
+  const read = readSmallFile(fs, `${path}/cgroup`);
+  if (read.error || read.tooLarge) return null;
+  const raw = String(read.text ?? '').trim();
+  if (!raw) return null;
+  const unified = raw.split('\n').find(line => line.startsWith('0::'));
+  const group = unified ? unified.slice(3) : raw;
+  return group || null;
+}
+
+const isTicks = value => typeof value === 'string' && /^\d+$/.test(value);
+
+/**
+ * Decide whether an unreadable same-uid process could be an escaped descendant
+ * of the recorded worker leader, using only evidence that stays readable for
+ * non-dumpable (hardened, e.g. Codex) processes: /proc/<pid>/stat (ppid,
+ * process group, session, start time) and /proc/<pid>/cgroup.
+ *
+ * Returns 'predates' (started strictly before the worker: cannot descend from
+ * it), 'unrelated' (its readable ancestry reaches another live process that
+ * is not ours, e.g. a different conductor's worker), 'vanished' (it
+ * disappeared mid-scan), or 'possible-descendant' (fail closed: ancestry
+ * reaches the worker leader or the worker's original session/process group,
+ * shares the worker's private cgroup, is reparented to init/a subreaper with
+ * no other link, or any link in the chain is unreadable).
+ */
+export function classifyUnreadableWorkerProcess({ fs, procRoot, pid, uid, workerPid,
+  workerPgid, workerSession, workerStart, workerCgroup, selfCgroup,
+  now = () => performance.now(), deadline = now() + 100, maxDepth = MAX_WORKER_ANCESTRY_DEPTH } = {}) {
+  const path = `${procRoot}/${pid}`;
+  const first = readSmallFile(fs, `${path}/stat`);
+  if (first.error) return vanished(first.error) ? 'vanished' : 'possible-descendant';
+  const link = !first.tooLarge && parseProcStatLink(first.text);
+  if (!link) return 'possible-descendant';
+  if (!isTicks(workerStart)) return 'possible-descendant';
+  if (BigInt(link.start) < BigInt(workerStart)) return 'predates';
+  // A process still in the worker's original session or process group is
+  // treated as a possible descendant even when its ppid chain is broken
+  // (an orphan that never called setsid keeps both).
+  if ((Number.isSafeInteger(workerPgid) && workerPgid > 0 && link.pgrp === workerPgid)
+    || (Number.isSafeInteger(workerSession) && workerSession > 0 && link.session === workerSession)) {
+    return 'possible-descendant';
+  }
+  // A shared cgroup links the process to the worker only when the worker's
+  // own cgroup is private: a degraded worker shares its session cgroup with
+  // every sibling, so that match proves nothing and ancestry decides.
+  if (workerCgroup) {
+    const candidate = readProcCgroup(fs, path);
+    if (candidate !== null && candidate === workerCgroup && workerCgroup !== selfCgroup) return 'possible-descendant';
+  }
+  let current = link.ppid;
+  for (let depth = 0; ; depth++) {
+    if (now() >= deadline) return 'possible-descendant';
+    if (depth >= maxDepth) return 'possible-descendant';
+    if (current === workerPid) {
+      // A pid number alone is not proof: verify the generation, since the
+      // number may have been reused after the leader exited.
+      const leader = readSmallFile(fs, `${procRoot}/${current}/stat`);
+      if (leader.error || leader.tooLarge) return 'possible-descendant';
+      const leaderLink = parseProcStatLink(leader.text);
+      if (!leaderLink) return 'possible-descendant';
+      if (leaderLink.start === workerStart) return 'possible-descendant';
+      current = leaderLink.ppid;
+      continue;
+    }
+    // Reparented to init (or the kernel): with no other link this is the
+    // honest unknown case, never proof of absence.
+    if (!Number.isSafeInteger(current) || current <= 1) return 'possible-descendant';
+    let owner;
+    try { owner = fs.statSync(`${procRoot}/${current}`).uid; }
+    catch { return 'possible-descendant'; }
+    // Another identity's tree (including container shims and managers owned
+    // by a different uid) can never be our worker's descendant. A setuid
+    // escape across uids is out of scope for this same-uid scan.
+    if (owner !== uid) return 'unrelated';
+    const next = readSmallFile(fs, `${procRoot}/${current}/stat`);
+    if (next.error || next.tooLarge) return 'possible-descendant';
+    const nextLink = parseProcStatLink(next.text);
+    if (!nextLink) return 'possible-descendant';
+    // This ancestor predates the worker, so it cannot descend from it — and
+    // neither can anything reached through it (a sibling subtree, another
+    // conductor's parallel worker, a session manager).
+    if (BigInt(nextLink.start) < BigInt(workerStart)) return 'unrelated';
+    current = nextLink.ppid;
+  }
+}