@aiwg/cli 2026.10.10 → 2026.10.12

package/tools/agents/providers/rule-delivery.mjs

@@ -12,7 +12,7 @@ import {
   addManagedMarker, contentHash, replaceBoundRulesBlock, deployEmulatedBehaviors, filterAgentFiles,
 } from './base.mjs';
 
-const { parseRuleFrontmatter, inferRuleActivation, RULE_BINDING_TYPES, readCoreBody, validateCoreSet, CORE_RULES_START, CORE_RULES_END } = await importImpl(import.meta.url, 'rules/activation.mjs');
+const { parseRuleFrontmatter, inferRuleActivation, readCoreBody, validateCoreSet, CORE_RULES_START, CORE_RULES_END } = await importImpl(import.meta.url, 'rules/activation.mjs');
 const { resolveDeployVersion } = await importImpl(import.meta.url, 'providers/deploy-version.mjs');
 const { trackTemporaryDirectory } = await importImpl(import.meta.url, 'utils/temporary-directory.js');
 const { loadRulePinConfigs, installedRuleCapabilities, resolveRulePins } = await importImpl(import.meta.url, 'rules/pins.mjs');
@@ -20,6 +20,8 @@ const { guardRulesInlineBudget } = await importImpl(import.meta.url, 'rules/inli
 const { userConfigFile } = await importImpl(import.meta.url, 'config/user-config-dir.mjs');
 const { resolveProjectAiwgDir } = await importImpl(import.meta.url, 'config/project-artifacts-runtime.mjs');
 import { writeContextFileSync, CONTEXT_STAGE_ENV } from './context-write.mjs';
+import { captureProviderPathDescriptors, setStagedProviderPath, restoreProviderPaths } from './provider-paths-staging.mjs';
+import { resolveDeliveryRuleBindings } from './rule-binding-targets.mjs';
 import { projectOnDemandReferences, renderRuleKernelIndex } from './rule-presentation.mjs';
 export { renderRuleKernelIndex } from './rule-presentation.mjs';
 const PREPARATION_HOOK = Symbol.for('aiwg.provider-preparation-hook.v1');
@@ -175,128 +177,7 @@ export async function prepareRuleDelivery(opts) {
     // All pins use native kernel projection, including legacy untagged rules.
     rule.tagged = true;
   }
-  const bindings = new Map();
-  const targets = [];
-  const targetKeys = new Set();
-  if (rules.some(rule => Object.values(rule.bound_to).some(ids => ids.length))) {
-    const { loadLocalCapabilityEntries, loadLocalOverrideCapabilityEntries, createRuleBindingTargetResolver } = await importImpl(import.meta.url, 'artifacts/query-engine.js');
-    const root = resolveAiwgRoot(opts.srcRoot) || opts.srcRoot;
-    // Framework graph paths are package-relative; project graph paths belong
-    // to the queried project. Normalize before merging so one source cannot
-    // become two apparently ambiguous targets after a source-index rebuild.
-    const indexEntries = new Map();
-    const entryPaths = new Map();
-    const loadEntries = (cwd, overridesOnly = false) => (overridesOnly
-      ? loadLocalOverrideCapabilityEntries(cwd)
-      : loadLocalCapabilityEntries(cwd, undefined, indexEntries)).map(entry => {
-      const anchor = entry.path.startsWith('agentic/code/') ? root : cwd;
-      const key = `${anchor}\0${entry.path}`;
-      if (!entryPaths.has(key)) entryPaths.set(key, path.resolve(anchor, entry.path));
-      const resolvedPath = entryPaths.get(key);
-      // Canonical IDs hash the indexed package-relative path. Keep it through
-      // resolution; the selected target is anchored to root below.
-      return { ...entry, path: entry.path.startsWith('agentic/code/') ? entry.path
-        : opts.mapInputPath ? opts.mapInputPath(resolvedPath) : resolvedPath };
-    });
-    let rebuilt = false;
-    const cacheDir = process.env.AIWG_RULE_BINDING_INDEX_CACHE;
-    const cacheFile = cacheDir && path.join(cacheDir, `${contentHash(opts.logicalInputPath ? opts.logicalInputPath(root) : root)}.json`);
-    const buildSourceEntries = async (refresh = false) => {
-      if (!refresh && cacheFile) {
-        try { return JSON.parse(fs.readFileSync(cacheFile, 'utf8')).map(entry => ({ ...entry, path: path.isAbsolute(entry.path) && opts.mapInputPath ? opts.mapInputPath(entry.path) : entry.path })); }
-        catch (error) {
-          if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
-        }
-      }
-      const { collectRuleBindingEntries } = await importImpl(import.meta.url, 'artifacts/index-builder.js');
-      const sourceEntries = await collectRuleBindingEntries(root,
-        root === opts.srcRoot && !fs.existsSync(path.join(root, 'agentic')) ? '.' : 'agentic/code');
-      rebuilt = true;
-      const entries = sourceEntries.map(entry => ({ ...entry, path: entry.path.startsWith('agentic/code/')
-        ? entry.path : path.resolve(root, entry.path) }));
-      if (cacheFile) {
-        fs.mkdirSync(cacheDir, { recursive: true });
-        // Workers may publish the same immutable source snapshot concurrently.
-        const temporary = `${cacheFile}.${process.pid}.tmp`;
-        fs.writeFileSync(temporary, JSON.stringify(entries.map(entry => ({ ...entry, path: opts.logicalInputPath ? opts.logicalInputPath(entry.path) : entry.path }))));
-        fs.renameSync(temporary, cacheFile);
-      }
-      return entries;
-    };
-    const localEntries = opts.bindingEntries || loadEntries(opts.target, Boolean(packageRelations));
-    let entries = [...localEntries];
-    if (!opts.bindingEntries) {
-      // The validated package table is authoritative for its exact source digest.
-      // Keep the canonical resolver for aliases, local overrides and ambiguity.
-      const sourceEntries = packageRelations
-        ? Object.values(packageRelations.index.artifacts).map(entry => ({ ...entry,
-          indexScope: 'packaged', indexGraph: 'framework' }))
-        : loadEntries(root);
-      // A relocated project graph may also be visible while querying the
-      // package root. Keep its project-anchored instance only.
-      const uniqueSources = sourceEntries.filter(entry => !(opts.sharedProjectGraph &&
-        entry.path.startsWith(path.join(root, '.aiwg') + path.sep) &&
-        localEntries.some(local => local.type === entry.type && local.name === entry.name)));
-      entries.push(...uniqueSources);
-      if (!sourceEntries.length) entries.push(...await buildSourceEntries());
-    }
-    // Project-local installed bundles are outside the package source index.
-    // Reuse the existing binding index builder only for those source roots.
-    if (!opts.bindingEntries) {
-      for (const entry of Object.values(configs.project.installed || {})) {
-        if (!entry.localPath) continue;
-        const localRoot = path.resolve(opts.target, entry.localPath);
-        if (localRoot === root || !fs.existsSync(localRoot)) continue;
-        const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'aiwg-local-rule-index-'));
-        try {
-          const { buildIndex } = await importImpl(import.meta.url, 'artifacts/index-builder.js');
-          await buildIndex(localRoot, { scope: '.', outputDir: temp, force: true, quiet: true });
-          const index = JSON.parse(read(path.join(temp, '.aiwg', '.index', 'metadata.json')));
-          const scoped = Object.values(index.entries).map(entry => ({ ...entry, path: path.resolve(localRoot, entry.path) }));
-          localEntries.push(...scoped);
-          entries.push(...scoped);
-        } finally { fs.rmSync(temp, { recursive: true, force: true }); }
-      }
-    }
-    // A stored index can predate the source tree (edge/dev checkouts). Rebuild once from source
-    // before reporting a binding target as missing.
-    const resolvedTargets = new Map();
-    let resolveBinding = createRuleBindingTargetResolver(entries);
-    const resolveTarget = async (type, id) => {
-      const key = `${type}:${id}`;
-      if (resolvedTargets.has(key)) return resolvedTargets.get(key);
-      let target;
-      try { target = resolveBinding(type, id); }
-      catch (error) {
-        if (packageRelations || rebuilt || opts.bindingEntries || !/^Missing /.test(error.message)) throw error;
-        indexEntries.clear();
-        entryPaths.clear();
-        entries = [...localEntries, ...await buildSourceEntries(true)];
-        rebuilt = true;
-        resolveBinding = createRuleBindingTargetResolver(entries);
-        target = resolveBinding(type, id);
-        // A rebuild replaces the input set for every lookup.
-        resolvedTargets.clear();
-      }
-      resolvedTargets.set(key, target);
-      return target;
-    };
-    for (const rule of rules.filter(rule => rule.tagged)) {
-      for (const [key, type] of Object.entries(RULE_BINDING_TYPES)) {
-        for (const id of rule.bound_to[key]) {
-          const target = await resolveTarget(type, id);
-          const source = path.isAbsolute(target.path) ? target.path : path.resolve(target.path.startsWith('agentic/code/') ? root : opts.target, target.path);
-          if (!fs.existsSync(source)) throw new Error(`${rule.file}: binding target content missing: ${source}`);
-          bindings.set(source, [...(bindings.get(source) || []), rule]);
-          const key = `${target.type}:${source}`;
-          if (!targetKeys.has(key)) {
-            targetKeys.add(key);
-            targets.push({ ...target, source });
-          }
-        }
-      }
-    }
-  }
+  const { bindings, targets } = await resolveDeliveryRuleBindings(opts, rules, configs, root, packageRelations);
   return { rules, bindings, targets, pins: pinned.rules, pinWarnings: pinned.warnings };
 }
 
@@ -1010,7 +891,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
   const mappings = [];
   const preimages = [...initialPreimages];
   let retained = false;
-  const originals = { ...provider.paths };
+  const originals = captureProviderPathDescriptors(provider);
   const logicalTarget = original.target;
   const priorAiwgRoot = process.env.AIWG_ROOT;
   const priorRegistry = process.env.AIWG_USER_REGISTRY_PATH;
@@ -1148,7 +1029,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
       if (!path.isAbsolute(dir)) continue;
       const to = path.join(temp, 'native', key);
       mount(dir, to);
-      provider.paths[key] = to;
+      setStagedProviderPath(provider, key, to);
     }
     let kernel = provider.kernelSkillsPath;
     if (kernel && path.isAbsolute(kernel)) {
@@ -1344,7 +1225,7 @@ export async function prepareRuleDeployment(original, provider, deploy) {
     return plan;
   } finally {
     if (priorContextStage === undefined) delete process.env[CONTEXT_STAGE_ENV]; else process.env[CONTEXT_STAGE_ENV] = priorContextStage;
-    Object.assign(provider.paths, originals);
+    restoreProviderPaths(provider, originals);
     if (priorAiwgRoot === undefined) delete process.env.AIWG_ROOT; else process.env.AIWG_ROOT = priorAiwgRoot;
     if (priorRegistry === undefined) delete process.env.AIWG_USER_REGISTRY_PATH; else process.env.AIWG_USER_REGISTRY_PATH = priorRegistry;
     if (priorArtifacts === undefined) delete process.env.AIWG_ARTIFACTS_PATH; else process.env.AIWG_ARTIFACTS_PATH = priorArtifacts;

package/tools/ralph-external/lib/muse-adapter.mjs

@@ -31,6 +31,13 @@
  *   - `--approval-mode <mode>` — common to both; "`muse exec` accepts both
  *     approval flags" (configuration). Opt-in only: the adapter sets NO
  *     approval posture by default (#230 out of scope: `--yolo` defaults).
+ *   - `--trust-workspace` — loads project rules, skills and hooks for the
+ *     workspace (#3685: untrusted Muse reports `rules.context_load`
+ *     `project_sources=0` with user skills only and empty hook admission;
+ *     trusted reports `project_sources=1` with project skills and hooks).
+ *     Tier 0 workspaces are conductor-prepared worker trees the conductor
+ *     owns, so the direct profile binds this flag by default through the
+ *     host-controlled trust mapping; the brief never supplies it.
  *   - `muse export --session <uuid> --out <path>` — offline,
  *     byte-deterministic transcript projection; `--last` and `--redacted`
  *     skip the picker / redact payload strings (cookbook:
@@ -173,6 +180,9 @@ export class MuseAdapter extends ProviderAdapter {
     if ((permissions.approval ?? 'never') !== 'never') throw new Error('Muse direct worker approval requires never');
     // Trust is a host-owned, qualification-bound control, like the schema.
     // Brief contents and CLI defaults cannot opt into workspace instructions.
+    // Tier 0 binds ["--trust-workspace"] because the workspace is always a
+    // conductor-prepared worker tree (#3685); untrusted trees stay refused
+    // at dispatch by the operator native-argv gate.
     let trust;
     try { trust = JSON.parse(profile.controls.trust.mapping); } catch { /* fail closed below */ }
     if (!Array.isArray(trust) || !(trust.length === 0 || trust.length === 1 && trust[0] === '--trust-workspace')) {

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