@awebai/oats 0.32.0 → 0.34.0

package/lib/core.mjs

@@ -46,6 +46,7 @@ import { killGroup } from "./process-group.mjs";
 import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
 import { envRows, recordedTeams, teamsEnv } from "./teams.mjs";
 import { harnessUnavailable, launchConfigUnknown, launchLayers, launchReport, selectionFrom } from "./launch-preference.mjs";
+import { claudeTrusts, codexTrustsRoot, harnessTrustWarning } from "./harness-trust.mjs";
 async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
 // Capability rows for a PREPARED spawn (workspace model): the one function that
 // turns a Resolution's modules into the row shape hooks/environment/requirements/
@@ -2287,11 +2288,43 @@ function shimPathPrefix(tokens, binary, home) {
   if (!prefix.some((t) => t.name === "PATH")) texts.push(`PATH=${dir}:"$PATH"`);
   return texts;
 }
+/** codex runs tool commands with the PATH it is given here, the one the launching shell has (the
+ *  shim first): its value is this host's, so only the execution carries it. The user's login shell,
+ *  which Codex runs tool commands through, may still put its own profile entries ahead of it. */
+const CODEX_TOOL_PATH = `-c "shell_environment_policy.set.PATH=\\"$PATH\\""`;
+/** The binary and its arguments as the execution runs them. */
+function executionArgv(tokens, binary, harness) {
+  const texts = tokens.slice(binary).map((t) => t.text);
+  if (harness === "codex") texts.splice(1, 0, CODEX_TOOL_PATH);
+  return texts;
+}
 /** The persisted launch command as a shell runs it: the same command, with the home's kernel shim
  *  first on PATH. The persisted bytes never carry it (they stay a shape parseLaunchCommand reads). */
-export function launchShellCommand(command, home) {
+export function launchShellCommand(command, home, harness) {
   const { tokens, binary } = parseLaunchCommand(command);
-  return [...shimPathPrefix(tokens, binary, home), ...tokens.slice(binary).map((t) => t.text)].join(" ");
+  return [...shimPathPrefix(tokens, binary, home), ...executionArgv(tokens, binary, harness)].join(" ");
+}
+
+/** The deployment directory a home belongs to: the one its spawn recorded, else the nearest
+ *  ancestor holding oats-local.yaml, else the agents root's parent. */
+function deploymentOfHome(home, meta) {
+  if (typeof meta?.workspace?.deployment === "string" && meta.workspace.deployment) return realPathOrNearest(meta.workspace.deployment);
+  for (let d = dirname(resolve(home)); ; d = dirname(d)) {
+    if (existsSync(join(d, "oats-local.yaml"))) return realPathOrNearest(d);
+    if (dirname(d) === d) return realPathOrNearest(dirname(dirname(dirname(dirname(resolve(home))))));
+  }
+}
+/** Folder trust for a launch in `home` (lib/harness-trust.mjs, read-only): `trustHome` — the
+ *  codex launch trusts the home, because the operator trusts its deployment root or an
+ *  ancestor — and the warning when the session will stop at its harness's folder-trust prompt. */
+export function launchFolderTrust({ harness, home, meta, yolo, env = process.env }) {
+  const root = deploymentOfHome(home, meta);
+  if (harness === "codex") {
+    const trustHome = codexTrustsRoot(root, { env });
+    return { trustHome, warning: harnessTrustWarning({ harness, root, covered: trustHome || yolo === true }) };
+  }
+  if (harness === "claude") return { trustHome: false, warning: harnessTrustWarning({ harness, root, covered: claudeTrusts(home, { env }) }) };
+  return { trustHome: false, warning: null };
 }
 
 /** The harness command line of a recipe. With no configuration the bytes
@@ -2306,19 +2339,38 @@ export function launchShellCommand(command, home) {
  *  under <home>/.agents/skills are found from cwd=home like any repo's — and OATS
  *  contributes only the composed AGENTS.md (--append-system-prompt). The task
  *  positional goes ahead of contributed options because pi has no `--`. claude gets `--` before the prompt so a
- *  greedy contributed flag cannot eat it. codex keeps its native policy;
- *  yolo also trusts this generated home for the launch (projects=...). */
-export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
+ *  greedy contributed flag cannot eat it. codex keeps its native policy; it
+ *  never stops at Codex's update prompt, and the generated home is trusted for
+ *  the launch (projects=...) under yolo or `trustHome`: the operator trusts the
+ *  deployment root or an ancestor in Codex's config (lib/harness-trust.mjs),
+ *  which Codex itself does not apply to the homes below it. Codex's own form
+ *  of the override is the inline table: a dotted projects."<home>" key is not
+ *  honoured (codex-cli 0.157.1). */
+export function renderLaunchRecipe(recipe, { home, instance, redact = false, trustHome = false }) {
   const { harness, executable, model, yolo } = recipe;
   const cfgArgs = (recipe.args || []).map(shq).join(" ");
   const hookArgs = recipe.hooks?.launch?.[harness] || "";
   const tail = `${cfgArgs ? ` ${cfgArgs}` : ""}${hookArgs ? ` ${hookArgs}` : ""}`;
+  // The launch's environment, in prefix order: the instance, the capabilities' env, the
+  // configuration's env (a reference by reference, never by value).
+  const hookEnv = recipe.hooks?.env || {};
+  const env = [["OATS_INSTANCE", instance], ["OATS_INSTANCE_HOME", home], ["PI_AGENT_INSTANCE", instance], ["PI_AGENT_HOME", home]].map(([name, value]) => ({ name, value }));
+  for (const name of Object.keys(hookEnv).sort()) env.push({ name, value: redact ? "<redacted>" : hookEnv[name] });
+  for (const name of Object.keys(recipe.env || {}).sort()) {
+    const v = recipe.env[name];
+    env.push(typeof v === "string" ? { name, value: redact ? "<redacted>" : v } : { name, reference: true });
+  }
   let cmdline;
   if (harness === "claude") {
     cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
   } else if (harness === "codex") {
     const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
-    cmdline = `${shq(executable)} --cd ${shq(home)}${yolo ? ` --yolo -c ${shq(codexTrust)}` : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
+    // Codex may run tool commands outside the session's process (its shared app-server daemon),
+    // so the env the prefix below gives the session is also set for them. A reference's value
+    // never goes on argv, and PATH is the execution's (CODEX_TOOL_PATH: the shim first).
+    const toolEnvArgs = env.filter((e) => !e.reference && e.name !== "PATH")
+      .map((e) => ` -c ${shq(`shell_environment_policy.set.${e.name}=${JSON.stringify(e.value)}`)}`).join("");
+    cmdline = `${shq(executable)} --cd ${shq(home)} -c check_for_update_on_startup=false${yolo ? " --yolo" : ""}${yolo || trustHome ? ` -c ${shq(codexTrust)}` : ""}${toolEnvArgs}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
   } else {
     // Decision 13: pi starts NORMALLY — its own skill discovery (~/.pi/agent/skills,
     // .agents/skills up the tree, so the instance's copied capability skills are
@@ -2326,13 +2378,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
     // the composed instructions.
     cmdline = `${shq(executable)} --append-system-prompt ${shq(join(home, "AGENTS.md"))} --approve --name ${shq(instance)}${model ? ` --model ${shq(model)}` : ""} ${shq("@TASK.md")}${tail}`;
   }
-  const hookEnv = recipe.hooks?.env || {};
-  const envTokens = Object.keys(hookEnv).sort().map((name) => `${name}=${shq(redact ? "<redacted>" : hookEnv[name])}`);
-  for (const name of Object.keys(recipe.env || {}).sort()) {
-    const v = recipe.env[name];
-    envTokens.push(typeof v === "string" ? `${name}=${shq(redact ? "<redacted>" : v)}` : `${name}="$${LAUNCH_REF_PREFIX}${name}"`);
-  }
-  return `OATS_INSTANCE=${shq(instance)} OATS_INSTANCE_HOME=${shq(home)} PI_AGENT_INSTANCE=${shq(instance)} PI_AGENT_HOME=${shq(home)}${envTokens.length ? ` ${envTokens.join(" ")}` : ""} ${cmdline}`;
+  return `${env.map((e) => e.reference ? `${e.name}="$${LAUNCH_REF_PREFIX}${e.name}"` : `${e.name}=${shq(e.value)}`).join(" ")} ${cmdline}`;
 }
 
 /** Execution, not preview: mark pending before dispatch, then resolve native
@@ -2344,7 +2390,7 @@ function nativeRecordCommand(command, home, harness) {
   const args = tokens.slice(binary + 1).filter(t => t.kind !== "prompt").map(t => t.value ?? t.text);
   const id = prepareNativeStart(home, harness);
   const recorder = join(PKG_ROOT, "packages", "record", "bin", "record-native-start.mjs");
-  const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(harness)} ${shq(JSON.stringify(args))} && exec ${tokens.slice(binary).map(t => t.text).join(" ")}`;
+  const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(harness)} ${shq(JSON.stringify(args))} && exec ${executionArgv(tokens, binary, harness).join(" ")}`;
   return `${shimPathPrefix(tokens, binary, home).join(" ")} /bin/sh -c ${shq(inner)}`;
 }
 
@@ -2485,9 +2531,10 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     ...(frozen?.legacy ? { legacy: { ...frozen.legacy, ...(hooks.refreshed?.length ? { replacedBy: hooks.refreshed } : {}) } } : {}),
   };
   const inst = instance || meta?.instance || basename(home);
-  const command = renderLaunchRecipe(recipe, { home, instance: inst });
+  const { trustHome } = launchFolderTrust({ harness, home, meta, yolo: recipe.yolo, env });
+  const command = renderLaunchRecipe(recipe, { home, instance: inst, trustHome });
   const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.harness) ? "frozen" : "config") : "config";
-  return { recipe, command, harness, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: hooks.warnings || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
+  return { recipe, command, trustHome, harness, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: hooks.warnings || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
 }
 /** The environment a planned launch runs under: the host's base, the
  *  capabilities' validated env, the configuration's literals and its
@@ -3577,7 +3624,9 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       prompt: LAUNCH_PROMPT, kernelBin: shimTarget,
     };
     if (triggerEventFile) recipe.env.OATS_TRIGGER_EVENT_FILE = triggerEventFile;
-    const cmdline = renderLaunchRecipe(recipe, { home, instance });
+    const folderTrust = launchFolderTrust({ harness, home, meta: { workspace: { deployment: o.prepared?.deployment } }, yolo });
+    if (folderTrust.warning) warnings.push(folderTrust.warning);
+    const cmdline = renderLaunchRecipe(recipe, { home, instance, trustHome: folderTrust.trustHome });
 
     // Module skills as materialize landed them (flat, .agents/skills/<skill>/),
     // beside the soul's own: per-skill provenance `module:<cap>` (lead decision c3),
@@ -3884,6 +3933,29 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
   return out;
 }
 
+/** The working directory as the shell names it: $PWD when it is the process's own directory, else
+ *  the physical cwd. A path through a symlink (an attached instance's work/, which links into its
+ *  owner's tree) then still belongs to the instance it was entered from. */
+export function logicalCwd() {
+  const cwd = process.cwd(), pwd = process.env.PWD;
+  try { if (pwd && isAbsolute(pwd) && realpathSync(pwd) === realpathSync(cwd)) return pwd; } catch { /* a stale PWD */ }
+  return cwd;
+}
+/** The instance home enclosing `dir` (itself or its nearest such ancestor): a directory laid out
+ *  as <agents-root>/<agent>/instances/<name> whose instance.json records `instance: <name>`.
+ *  For a process whose harness strips the session env (Codex's shared app-server daemon runs
+ *  tool commands outside the session); the caller validates the home as it does one named by
+ *  OATS_INSTANCE_HOME. undefined when no such directory encloses `dir`. */
+export function enclosingInstanceHome(dir) {
+  for (let d = resolve(dir); ; d = dirname(d)) {
+    if (basename(dirname(d)) === "instances" && INSTANCE_NAME_RE.test(basename(d))) {
+      try { if (JSON.parse(readFileSync(join(d, "instance.json"), "utf8"))?.instance === basename(d)) return d; }
+      catch { /* no readable instance.json: not a home */ }
+    }
+    if (dirname(d) === d) return undefined;
+  }
+}
+
 // Locate an instance home under an agents root, including capability-defined
 // agents homing under <root>/<name>/ WITHOUT a soul there (listAgents cannot
 // see those). Shared by retireInstance and `oats spawn --parent`.

package/lib/harness-trust.mjs

@@ -0,0 +1,139 @@
+/** Folder trust for the claude and codex harnesses (#341): whether a new instance home is
+ *  covered by the operator's one-time trust of the deployment root, so the launched session
+ *  does not stop at the harness's folder-trust prompt.
+ *
+ *  The operator's harness configuration is only read, never written: trusting the deployment
+ *  root is the operator's act. A configuration that is missing, unreadable or in a form this
+ *  reader does not know counts as not trusted, so a launch is warned about rather than
+ *  silently stalled.
+ *
+ *  - Claude walks up from its working directory, stopping at a git root, and honours
+ *    `projects["<dir>"].hasTrustDialogAccepted` in ~/.claude.json
+ *    ($CLAUDE_CONFIG_DIR/.claude.json when that is set). Instance homes are not inside a git
+ *    repository, so one entry for the deployment root covers every home under it.
+ *  - Codex honours only an exact `[projects."<dir>"] trust_level = "trusted"` entry in
+ *    ~/.codex/config.toml ($CODEX_HOME/config.toml), never a parent's. A per-invocation
+ *    override does trust a home, so the kernel's codex launch adds one for the home when the
+ *    operator trusts the deployment root or an ancestor of it (renderLaunchRecipe). */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+const userHome = (env) => env.HOME || homedir();
+
+/** `dir` and its ancestors, nearest first. */
+function* upwards(dir) {
+  for (let d = real(dir); ; d = dirname(d)) { yield d; if (dirname(d) === d) return; }
+}
+
+/** Whether Claude Code trusts `home` without asking: an accepted trust entry for the home or
+ *  an ancestor, up to and including the nearest git root. */
+export function claudeTrusts(home, { env = process.env } = {}) {
+  const file = env.CLAUDE_CONFIG_DIR ? join(env.CLAUDE_CONFIG_DIR, ".claude.json") : join(userHome(env), ".claude.json");
+  let projects;
+  try { projects = JSON.parse(readFileSync(file, "utf8"))?.projects; } catch { return false; }
+  if (!projects || typeof projects !== "object") return false;
+  for (const d of upwards(home)) {
+    if (Object.hasOwn(projects, d) && projects[d]?.hasTrustDialogAccepted === true) return true;
+    if (existsSync(join(d, ".git"))) return false;
+  }
+  return false;
+}
+
+/** A TOML key: bare, "basic" (JSON-compatible escapes) or 'literal'. null when not a key. */
+function tomlKey(text) {
+  const t = text.trim();
+  if (/^[A-Za-z0-9_-]+$/.test(t)) return t;
+  if (/^'[^']*'$/.test(t)) return t.slice(1, -1);
+  if (/^"(?:[^"\\]|\\.)*"$/.test(t)) { try { return JSON.parse(t); } catch { return null; } }
+  return null;
+}
+/** A dotted TOML key path, split on the dots outside quotes. null when any part is not a key. */
+function tomlPath(text) {
+  const parts = [];
+  let cur = "", quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) { cur += c; if (c === "\\" && quote === '"') cur += text[++i] ?? ""; else if (c === quote) quote = null; }
+    else if (c === '"' || c === "'") { quote = c; cur += c; }
+    else if (c === ".") { parts.push(cur); cur = ""; }
+    else cur += c;
+  }
+  if (quote) return null;
+  parts.push(cur);
+  const keys = parts.map(tomlKey);
+  return keys.includes(null) ? null : keys;
+}
+const tomlString = (text) => { const t = text.trim(); return /^'[^']*'$/.test(t) || /^"(?:[^"\\]|\\.)*"$/.test(t) ? tomlKey(t) : null; };
+/** The text of a line before a `#` comment that is outside quotes. */
+function uncommented(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) { if (c === "\\" && quote === '"') i++; else if (c === quote) quote = null; }
+    else if (c === '"' || c === "'") quote = c;
+    else if (c === "#") return line.slice(0, i);
+  }
+  return line;
+}
+/** `key = value` split at the first `=` outside quotes. */
+function assignment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) { if (c === "\\" && quote === '"') i++; else if (c === quote) quote = null; }
+    else if (c === '"' || c === "'") quote = c;
+    else if (c === "=") return [line.slice(0, i), line.slice(i + 1)];
+  }
+  return null;
+}
+
+/** The directories config.toml marks `trust_level = "trusted"`, in the forms Codex writes and
+ *  their plain TOML equivalents: `[projects."<dir>"]` tables, `"<dir>" = { trust_level = … }`
+ *  under `[projects]`, and dotted `projects."<dir>".trust_level` keys. */
+function codexTrustedDirs(text) {
+  const trusted = new Set();
+  let table = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = uncommented(raw).trim();
+    if (!line) continue;
+    if (line.startsWith("[")) {
+      const m = /^\[\s*([^[\]]+?)\s*\]$/.exec(line);
+      table = m && !line.startsWith("[[") ? tomlPath(m[1]) ?? [null] : [null];
+      continue;
+    }
+    const kv = assignment(line);
+    if (!kv) continue;
+    const key = tomlPath(kv[0].trim());
+    if (!key) continue;
+    const path = [...table, ...key], value = kv[1].trim();
+    if (path.length === 3 && path[0] === "projects" && path[2] === "trust_level" && tomlString(value) === "trusted") trusted.add(path[1]);
+    const inline = /^\{\s*trust_level\s*=\s*("[^"]*"|'[^']*')\s*\}$/.exec(value);
+    if (path.length === 2 && path[0] === "projects" && inline && tomlString(inline[1]) === "trusted") trusted.add(path[1]);
+  }
+  return trusted;
+}
+
+/** Whether Codex's config trusts the deployment `root` or one of its ancestors: the operator's
+ *  one-time consent for the kernel to trust each new home under it at launch. */
+export function codexTrustsRoot(root, { env = process.env } = {}) {
+  const file = join(env.CODEX_HOME || join(userHome(env), ".codex"), "config.toml");
+  let trusted;
+  try { trusted = codexTrustedDirs(readFileSync(file, "utf8")); } catch { return false; }
+  for (const d of upwards(root)) if (trusted.has(d)) return true;
+  return false;
+}
+
+/** The step that trusts the deployment root, per harness. */
+const TRUST_STEP = {
+  claude: (root) => `run \`claude\` in ${root} and accept its folder-trust prompt; one entry covers every instance home under it`,
+  codex: (root) => `run \`codex\` in ${root} and choose "Trust and continue"; OATS then trusts each new home under it at launch`,
+};
+
+/** The spawn and readiness warning for a home its harness will not trust without asking;
+ *  null when `covered`, or for a harness without a folder-trust prompt. */
+export function harnessTrustWarning({ harness, root, covered }) {
+  if (covered || !Object.hasOwn(TRUST_STEP, harness)) return null;
+  return `the ${harness} session will stop at its folder-trust prompt: trust ${root} once (${TRUST_STEP[harness](root)})`;
+}

package/lib/instance-inspect.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
+import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
 import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility } from "./resolve.mjs";
@@ -308,6 +308,20 @@ function launchItems(t) {
     reason: `this instance runs ${show(a)}; its launch preference now says ${show(b)} (${t.launchCurrent.at ?? t.launchCurrent.from})`,
     remedy: "`oats session restart --reselect-launch`, or respawn", recorded: a, current: b, from: t.launchCurrent.from, at: t.launchCurrent.at })];
 }
+/** `harness-trust` (#341; a warning): the claude or codex session this subject launches will stop at
+ *  its folder-trust prompt, because the operator has not trusted the deployment. An instance's recorded
+ *  harness and home; a soul's launch here, for a home under the agents root. Reads, never writes, the
+ *  harness's configuration (lib/harness-trust.mjs). */
+function folderTrustItems(t) {
+  const harness = t.home ? t.meta?.harness : t.launch?.effective?.harness;
+  if (harness !== "claude" && harness !== "codex") return [];
+  const meta = t.home ? t.meta : { workspace: { deployment: t.deployment } };
+  // A soul's yolo is its selected launch configuration's (a host fact, never the soul's).
+  const config = () => { try { return launchConfigsAt(t.deployment)[t.launch?.effective?.launchConfig]; } catch { return undefined; } };
+  const yolo = t.home ? (t.meta?.yolo ?? t.meta?.launch?.yolo) : config()?.yolo;
+  const { warning } = launchFolderTrust({ harness, home: t.home ?? t.agentsRoot, meta, yolo });
+  return warning ? [item("launch", "fail", { required: false, producer: "harness folder trust", code: "harness-trust", reason: warning, harness, deployment: t.deployment })] : [];
+}
 function roll(items) {
   const req = items.filter((i) => i.required !== false);
   if (!items.length) return "not-applicable";
@@ -411,7 +425,7 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
         evidence: { command: req.command }, remedy: found ? null : req.install, ...cap(mod.name) }));
     }
   }
-  configured.push(...teamItems(t), ...launchItems(t));
+  configured.push(...teamItems(t), ...launchItems(t), ...folderTrustItems(t));
   // member — the soul's member repository is a confirmed member of the workspace
   // (oats-membership.yaml backlink observed over the remotes).
   const d = t.discovery;

package/lib/packages.mjs

@@ -452,7 +452,7 @@ export function memoizedRemote(remote) {
 export function bindRemote(remote, remoteOptions) {
   if (!remoteOptions || Object.keys(remoteOptions).length === 0) return remote;
   const bound = { ...remote };
-  const arities = { observeRemote: 1, readRemoteFile: 3, listRemoteTree: 3, fetchRemoteTree: 4, memoAtCommit: 4, lastObservedCommit: 1, peekAtCommit: 3, prefetchObservation: 1, abandonPrefetches: 0 };
+  const arities = { observeRemote: 1, readRemoteFile: 3, listRemoteTree: 3, listRemoteFiles: 3, fetchRemoteTree: 4, memoAtCommit: 4, lastObservedCommit: 1, peekAtCommit: 3, prefetchObservation: 1, abandonPrefetches: 0 };
   for (const name of Object.keys(arities)) {
     if (typeof remote[name] !== "function") continue;
     bound[name] = (...args) => {

package/lib/process-group.mjs

@@ -10,3 +10,57 @@ export function killGroup(child, signal = "SIGKILL") {
   try { process.kill(pid, signal); } catch { /* already gone */ }
   return true;
 }
+
+/** How long a group asked to end with SIGTERM gets before SIGKILL. */
+export const TERM_GRACE_MS = 2_000;
+
+/** Children whose 'close' has fired (watchGroup): the leader exited and was reaped, its stdio pipes shut. */
+const closedGroups = new WeakSet();
+
+/** Record a detached child's 'close': call it right after spawning a child that terminateGroup may end. → the child. */
+export function watchGroup(child) {
+  child.once("close", () => closedGroups.add(child));
+  return child;
+}
+
+/** How often terminateGroup checks, after the leader's 'close', whether its group is empty yet. */
+export const GROUP_PROBE_MS = 50;
+
+/** Whether a detached child's process group still has a member we may signal (ESRCH: empty; EPERM: not ours). */
+function groupAlive(child) {
+  try { process.kill(-child.pid, 0); return true; } catch { return false; }
+}
+
+/** End a detached child's whole process group gracefully: SIGTERM now, SIGKILL to the group after `graceMs`.
+ *  git removes its own lock files (`shallow.lock`, `config.lock`, a ref's `.lock`) on SIGTERM, never on SIGKILL:
+ *  a git killed outright leaves a lock that blocks every later write. The timers are unref'd, so they never keep
+ *  the process alive. A group seen empty is never signalled again: its id may then lead an unrelated group.
+ *  Returns whether anything was signalled. */
+export function terminateGroup(child, graceMs = TERM_GRACE_MS) {
+  // A child already closed may have left an empty group, whose id is free: send nothing.
+  if (closedGroups.has(child)) return false;
+  if (!signalGroup(child, "SIGTERM")) return false;
+  // Until 'close', the group holds a pipe-holding member (git, or its ssh or remote helper), so its id is ours and
+  // the SIGKILL may come. After 'close' the leader is gone but a member that ignores SIGTERM and holds no pipe may
+  // remain: no pid is allocated while it is a live group's id, so a group seen non-empty is still ours. It is probed
+  // until the grace ends: empty → no SIGKILL, ever; still there → SIGKILL. What remains is a group that empties and is
+  // reused within one GROUP_PROBE_MS.
+  let probe = null;
+  const done = () => { clearTimeout(timer); clearInterval(probe); };
+  const timer = setTimeout(() => { clearInterval(probe); signalGroup(child, "SIGKILL"); }, graceMs);
+  timer.unref?.();
+  child.once?.("close", () => {
+    if (!groupAlive(child)) { done(); return; }
+    probe = setInterval(() => { if (!groupAlive(child)) done(); }, GROUP_PROBE_MS);
+    probe.unref?.();
+  });
+  return true;
+}
+
+/** Signal a detached child's process group only (see killGroup for the pid-0 guard). → whether it was a real child. */
+export function signalGroup(child, signal) {
+  const pid = child?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(-pid, signal); } catch { /* the group is gone */ }
+  return true;
+}