@awebai/oats 0.31.0 → 0.33.0

package/lib/core.mjs

@@ -33,6 +33,7 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { accessSync, constants as fsConstants } from "node:fs";
+import { recordLocalInput } from "./local-inputs.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
@@ -45,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/
@@ -183,7 +185,13 @@ export function slug(s) {
   const r = String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return r || "agent";
 }
-function which(bin) { return shTry(`command -v ${shq(bin)}`); }
+/** `command -v <bin>`, once per (bin, PATH) in this process: the answer only changes with PATH. */
+const whichMemo = new Map();
+function which(bin) {
+  const key = `${bin}\0${process.env.PATH ?? ""}`;
+  if (!whichMemo.has(key)) whichMemo.set(key, shTry(`command -v ${shq(bin)}`));
+  return whichMemo.get(key);
+}
 
 // ---------- yaml-ish ----------
 /** `__proto__` is never data in a plain-object mapping: assigning it REWRITES
@@ -525,7 +533,7 @@ export const LAYERS = ["knowledge", "messaging", "tasks"];
 // deployment's oats-local.yaml (lead decision 2: a spawn-time HOST choice,
 // never a soul field). Selected at spawn or session start/restart by name.
 export const LAUNCH_HARNESSES = ["pi", "claude", "codex"];
-export const LAUNCH_CONFIG_KEYS = new Set(["harness", "runtime", "executable", "args", "env", "model", "yolo"]);
+export const LAUNCH_CONFIG_KEYS = new Set(["harness", "runtime", "executable", "args", "env", "model", "yolo", "default"]);
 /** A launch configuration's harness: `harness`, or `runtime`, its pre-0.27 name (0.26.0
  *  deployments wrote it) — read either (lead call 6). */
 export const launchConfigHarness = (entry) => (Object.hasOwn(entry, "harness") ? entry.harness : entry.runtime);
@@ -541,7 +549,7 @@ export function validateLaunchConfig(name, entry, where) {
   if (typeof name !== "string" || !LAUNCH_CONFIG_NAME.test(name)) bad("has an invalid name (letters, digits, dot, underscore, dash; up to 64 characters)");
   if (name === "none") bad("cannot be named none: that word selects no configuration");
   if (!entry || typeof entry !== "object" || Array.isArray(entry)) bad("must be a map");
-  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (harness, executable, args, env, model, yolo)`);
+  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (harness, executable, args, env, model, yolo, default)`);
   if (Object.hasOwn(entry, "harness") && Object.hasOwn(entry, "runtime") && entry.harness !== entry.runtime) bad(`names harness ${JSON.stringify(entry.harness)} and runtime ${JSON.stringify(entry.runtime)}: \`runtime\` is the pre-0.27 name of \`harness\` — keep one`);
   if (!LAUNCH_HARNESSES.includes(launchConfigHarness(entry))) bad(`needs harness: one of ${LAUNCH_HARNESSES.join(", ")}`);
   const text = (v, what) => { if (typeof v !== "string" || !v.trim() || v.includes("\0")) bad(`${what} must be non-empty text`); };
@@ -562,12 +570,25 @@ export function validateLaunchConfig(name, entry, where) {
   }
   if (entry.model !== undefined) text(entry.model, "model");
   if (entry.yolo !== undefined && typeof entry.yolo !== "boolean") bad("yolo must be true or false");
+  if (entry.default !== undefined && typeof entry.default !== "boolean") bad("default must be true or false");
   return entry;
 }
+/** At most one `default: true` per harness (0.32, feature launch-config-default): the host's baseline for
+ *  that harness has one source. `map` is name → entry; entries are validated first. */
+export function validateLaunchConfigDefaults(map, where) {
+  const byHarness = new Map();
+  for (const [name, entry] of Object.entries(map || {})) {
+    if (entry?.default !== true) continue;
+    const harness = launchConfigHarness(entry);
+    if (byHarness.has(harness)) throw Object.assign(oatsError("E_LAUNCH_CONFIG_INVALID", `launch configurations ${JSON.stringify(byHarness.get(harness))} and ${JSON.stringify(name)}${where ? ` in ${where}` : ""} are both default: true for ${harness}; keep one default per harness`), { details: { harness, configurations: [byHarness.get(harness), name] } });
+    byHarness.set(harness, name);
+  }
+}
 function validateLaunchConfigs(map, file) {
   if (map === undefined) return;
   if (!map || typeof map !== "object" || Array.isArray(map)) throw oatsError("E_LAUNCH_CONFIG_INVALID", `launch-configs in ${file} must be a map of name to configuration`);
   for (const [name, entry] of Object.entries(map)) validateLaunchConfig(name, entry, file);
+  validateLaunchConfigDefaults(map, file);
 }
 /** The launch configurations effective at `dir`: the `launch-configs:` of the
  *  oats-local.yaml found walking up from it (the deployment), validated. None
@@ -585,7 +606,7 @@ export function launchConfigsAt(dir) {
   const source = dirname(found.path);
   for (const [name, entry] of Object.entries(map || {})) {
     if (!Object.hasOwn(entry, "harness")) noteRuntimeName(`launch-configs.${name}.runtime in ${found.path}`);
-    out[name] = { name, harness: launchConfigHarness(entry), ...(entry.executable !== undefined ? { executable: entry.executable } : {}), args: [...(entry.args || [])], env: { ...(entry.env || {}) }, ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.yolo !== undefined ? { yolo: entry.yolo } : {}), source, shadows: [] };
+    out[name] = { name, harness: launchConfigHarness(entry), ...(entry.executable !== undefined ? { executable: entry.executable } : {}), args: [...(entry.args || [])], env: { ...(entry.env || {}) }, ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.yolo !== undefined ? { yolo: entry.yolo } : {}), ...(entry.default === true ? { default: true } : {}), source, shadows: [] };
   }
   return out;
 }
@@ -858,9 +879,14 @@ export function officialPackageCatalog() {
 function readCatalogFile() {
   const file = officialCatalogFile();
   const empty = { packages: Object.create(null), capabilities: Object.create(null), file };
-  if (!existsSync(file)) return empty;
+  // An OATS_PACKAGE_CATALOG override is local configuration (observation.localRevision); the bundled
+  // catalog belongs to the kernel install.
+  const override = !!process.env.OATS_PACKAGE_CATALOG;
+  if (!existsSync(file)) { if (override) recordLocalInput(file, null); return empty; }
   let doc;
-  try { doc = JSON.parse(readFileSync(file, "utf8")); }
+  const text = readFileSync(file, "utf8");
+  if (override) recordLocalInput(file, text);
+  try { doc = JSON.parse(text); }
   catch (e) { throw oatsError("invalid-source", `broken package catalog ${file}: ${e.message}`); }
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw oatsError("invalid-source", `broken package catalog ${file}: root must be a JSON object`);
   const out = { packages: Object.create(null), capabilities: Object.create(null), file };
@@ -1247,7 +1273,7 @@ export const HARNESS_PACKAGE_MANAGERS = {
      * different marketplaces into one identity. */
     identity: (spec) => String(spec || "").trim(),
     safeSpec: (spec) => typeof spec === "string" && /^[a-z0-9][\w.-]*@[a-z0-9][\w.-]*$/i.test(spec),
-    /** The executable is CONTEXT-SELECTED (oats-claude-config may name a wrapper
+    /** The executable is SELECTED by the launch (a configuration may name a wrapper
      * such as `claude-personal`). Probing and installing through the literal
      * `claude` would inspect a DIFFERENT account's plugins than the session
      * actually launches with — passing preflight while the real harness lacks
@@ -1848,20 +1874,21 @@ export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
  * Spawn an instance of `agent` (as returned by findAgent/listAgents).
  * o: { instance?, purpose?, name?, repo?, work?, harness?, model?, task?, taskFile?, branch?, launch?, tmuxSession? }
  */
-/** The claude binary for a context: closest `oats-claude-config` (a one-line file
- * naming the binary, e.g. "claude-personal") walking up from contextDir wins; no
- * file → "claude". Local-only by design — a personal machine preference (account
- * selection), never committed config; keep it out of version control. */
-export function resolveClaudeBinary(contextDir) {
+/** `oats-claude-config` (a one-line file naming the claude binary, found walking up from the context) is no
+ *  longer read (0.32): a host names its claude executable in a default launch configuration. A file still in
+ *  reach of a new claude launch refuses it, naming the file and the configuration to declare instead. */
+export function legacyClaudeConfigRefusal(contextDir) {
   let d = resolve(contextDir);
   while (true) {
     const f = join(d, "oats-claude-config");
     if (existsSync(f)) {
-      const name = readFileSync(f, "utf8").split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#"));
-      if (name) return name;
+      let name = null;
+      try { name = readFileSync(f, "utf8").split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#")) || null; } catch {}
+      const exe = name ? `executable: ${name}, ` : "";
+      return Object.assign(oatsError("E_CLAUDE_CONFIG_REMOVED", `${f} is no longer read (OATS 0.32): declare this machine's claude default in oats-local.yaml instead — launch-configs: { <name>: { harness: claude, ${exe}default: true } } (oats launch-config set <name> --file <json>) — then delete ${f}`), { details: { file: f, executable: name, fix: `declare a claude default launch configuration (${exe}default: true), then delete ${f}` } });
     }
     const parent = dirname(d);
-    if (parent === d) return "claude";
+    if (parent === d) return null;
     d = parent;
   }
 }
@@ -1961,11 +1988,10 @@ function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {})
   const found = [];
   const problems = [];
   // The session launches with the SELECTED executable (a configuration's,
-  // or the context-selected one: oats-claude-config may name
-  // `claude-personal`), so probing another binary would inspect a different
+  // the host's harness default included), so probing another binary would inspect a different
   // account's packages than the instance will actually use. The probe is the
   // manager's controlled list subcommand; no launch argument is added to it.
-  const probeOpts = { context: contextDir, ...(bin ? { bin } : harness === "claude" ? { bin: resolveClaudeBinary(contextDir) } : {}) };
+  const probeOpts = { context: contextDir, ...(bin ? { bin } : {}) };
   for (const cap of resolved.capabilities || []) {
     for (const raw of cap.manifest?.requires || []) {
       if (!raw || typeof raw !== "object") continue;
@@ -2059,8 +2085,10 @@ const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
 
 /** The executable a launch uses: a configuration's declared one (a bare name
  *  on PATH; a path against the deployment directory when relative) or the
- *  harness's default (claude through oats-claude-config). Never executed. */
+ *  harness's name on PATH. Never executed. A new claude launch with a legacy `oats-claude-config` in reach
+ *  of its context is refused (E_CLAUDE_CONFIG_REMOVED, 0.32), whatever it declares. */
 export function resolveLaunchExecutable({ harness, declared, declaringDir, contextDir }) {
+  if (harness === "claude" && contextDir) { const refused = legacyClaudeConfigRefusal(contextDir); if (refused) throw refused; }
   if (declared) {
     if (declared.includes("/")) {
       const path = isAbsolute(declared) ? declared : resolve(declaringDir || contextDir, declared);
@@ -2069,10 +2097,8 @@ export function resolveLaunchExecutable({ harness, declared, declaringDir, conte
     const found = which(declared);
     return { path: found || null, declared, resolvedFrom: "PATH", missing: found ? undefined : `${declared} binary not found on PATH` };
   }
-  const claudeBin = harness === "claude" ? resolveClaudeBinary(contextDir) : undefined;
-  const name = harness === "claude" ? claudeBin : harness;
-  const found = which(name);
-  return { path: found || null, declared: null, resolvedFrom: harness === "claude" && claudeBin !== "claude" ? "oats-claude-config" : "PATH", missing: found ? undefined : `${name} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}` };
+  const found = which(harness);
+  return { path: found || null, declared: null, resolvedFrom: "PATH", missing: found ? undefined : `${harness} binary not found on PATH` };
 }
 /** null when `path` is a regular executable file; otherwise why not. */
 export function checkLaunchExecutable(path) {
@@ -2107,7 +2133,7 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
     // applies the current definition.
     // Named or not: the recorded executable (a saved wrapper, say), args and
     // env are what runs; later edits of the scope never change it.
-    config = { name: frozen.launchConfig || null, harness: frozen.harness, ...(frozen.executableDeclared ? { executable: frozen.executableDeclared } : {}), executablePath: frozen.executable, args: [...(frozen.args || [])], env: { ...(frozen.env || {}) }, ...(frozen.model ? { model: frozen.model } : {}), ...(frozen.yolo !== undefined ? { yolo: frozen.yolo } : {}), source: frozen.launchConfigSource || null, frozen: true };
+    config = { name: frozen.launchConfig || null, harness: frozen.harness, ...(frozen.executableDeclared ? { executable: frozen.executableDeclared } : {}), executablePath: frozen.executable, args: [...(frozen.args || [])], env: { ...(frozen.env || {}) }, ...(frozen.model ? { model: frozen.model } : {}), ...(frozen.yolo !== undefined ? { yolo: frozen.yolo } : {}), source: frozen.launchConfigSource || null, ...(frozen.launchConfigDefault === true ? { harnessDefault: true } : {}), frozen: true };
     wanted = "none";
   }
   if (wanted === undefined) wanted = frozen ? "none" : (agent?.["launch-config"] || "none");
@@ -2120,6 +2146,9 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
   // host default would: below the flags and a selected configuration.
   const harness = config?.harness || selection.harness || (frozen ? frozen.harness : preference?.harness || agent?.harness || "pi");
   if (!LAUNCH_HARNESSES.includes(harness)) bad("E_UNSUPPORTED_HARNESS", `unknown harness "${harness}" (pi|claude|codex)`);
+  // 0.32 (feature launch-config-default): a launch that selected no configuration runs this host's default
+  // for its harness, if one is declared. An explicit `--launch-config none` asks for the bare harness.
+  const harnessDefault = !config && !(selection.launchConfig === "none" && !preference) ? harnessDefaultConfig(launchConfigs, harness) : null;
   let model, modelSource;
   // K6: an EXPLICIT "use the harness's native default" is distinct from an
   // omitted model (which inherits the configuration's or soul's preference).
@@ -2145,8 +2174,19 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
     // is no proof it fits another one. Nothing is passed across.
     model = ""; modelSource = "native default (harness differs from the soul's)";
   } else { model = resolveModelPreference(agent?.model || "", harness); modelSource = model ? "soul default" : "native default"; }
+  // The harness default's model is the last fallback: below every layer that names one, above the harness's own.
+  if (harnessDefault?.model && !model && !nativeDefault) {
+    model = resolveModelPreference(harnessDefault.model, harness); modelSource = `launch-config ${harnessDefault.name}`;
+    if (!model) bad("E_MODEL_UNKNOWN", `launch configuration ${harnessDefault.name} (the ${harness} default) names model ${JSON.stringify(harnessDefault.model)}, which has no entry usable by harness ${harness}`);
+  }
+  if (harnessDefault) config = harnessDefault;
   return { config, harness, model, modelSource, configuredYolo: config?.yolo };
 }
+/** This host's default launch configuration for `harness` (`default: true`), marked `harnessDefault`, or null. */
+export function harnessDefaultConfig(launchConfigs, harness) {
+  const found = Object.values(launchConfigs || {}).find((c) => c?.default === true && c.harness === harness);
+  return found ? { ...found, harnessDefault: true } : null;
+}
 /** A home's launch layers now (feature launch-preference; --reselect-launch and inspect's launchCurrent): its
  *  RECORDED soul's launch (the soul copy it runs) and its deployment's oats-local.yaml souls.launch. */
 export function homeLaunchLayers(realHome, meta) {
@@ -2186,7 +2226,11 @@ export function launchReportFor({ layers, launchConfigs = {}, contextDir }) {
     if (!Object.hasOwn(launchConfigs, name)) { const e = launchConfigUnknown({ name, from: choice.from, at: choice.at }); return report("pi", null, null, { code: e.code, message: e.message, fix: `declare launch configuration ${name} (oats launch-config set), or change oats-local.yaml souls.launch` }); }
     config = launchConfigs[name]; harness = config.harness; model = typeof config.model === "string" && config.model ? config.model : null;
   } else if (choice.preference) { harness = choice.preference.harness; model = choice.preference.model ?? null; }
-  const exe = resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir });
+  // As a spawn: a layer naming "none" asks for the bare harness; otherwise no configuration is the harness default.
+  if (!config && !(choice.selection.launchConfig === "none" && !choice.preference)) { config = harnessDefaultConfig(launchConfigs, harness); if (config && !model) model = typeof config.model === "string" && config.model ? config.model : null; }
+  let exe;
+  try { exe = resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir }); }
+  catch (e) { if (e?.code !== "E_CLAUDE_CONFIG_REMOVED") throw e; return report(harness, model, config?.name, { code: e.code, message: e.message, fix: `declare a claude default launch configuration (oats launch-config set), then delete ${e.details.file}` }); }
   if (!exe.path && !config?.executable) { const e = harnessUnavailable({ harness, from: choice.from, at: choice.at, why: exe.missing }); return report(harness, model, config?.name, { code: e.code, message: e.message, fix: e.details.fix }); }
   if (!exe.path) return report(harness, model, config.name, { code: "E_LAUNCH_EXECUTABLE", message: `launch configuration ${config.name}: ${exe.missing}`, fix: `fix the executable of launch configuration ${config.name} (oats launch-config set)` });
   return report(harness, model, config?.name);
@@ -2244,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
@@ -2263,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
@@ -2283,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
@@ -2301,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)}`;
 }
 
@@ -2364,7 +2453,10 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     if (selection.launchConfig !== undefined || selection.harness !== undefined) launchChoice = { from: "flag", at: null, declared: meta?.launchDeclared ?? null };
   }
   const { config, harness, model, modelSource } = chosen;
-  const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozen.yolo : agentLike?.yolo ?? resolvedCfg?.yolo));
+  // A recorded yolo that came from a harness default belongs to that default: it never carries into a launch
+  // the default no longer decides (a bare --launch-config none, another harness).
+  const frozenYolo = frozen && !(frozen.launchConfigDefault === true && !config?.frozen) ? frozen.yolo : undefined;
+  const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozenYolo : agentLike?.yolo ?? resolvedCfg?.yolo));
   const executable = config?.frozen
     ? { path: config.executablePath, declared: frozen.executableDeclared ?? null, resolvedFrom: frozen.executableResolvedFrom || "recorded", missing: existsSync(config.executablePath) ? undefined : `${config.executablePath} (recorded) does not exist` }
     : resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir });
@@ -2432,16 +2524,17 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     } else problems.push({ check: "harness-packages", ok: true, detail: "no harness package requirement declared for this harness; nothing probed" });
   }
   const recipe = {
-    version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null,
+    version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null, ...(config?.harnessDefault ? { launchConfigDefault: true } : {}),
     executable: executable.path || executable.declared || harness, executableDeclared: executable.declared ?? null, executableResolvedFrom: executable.resolvedFrom,
     args: [...(config?.args || [])], env: { ...configEnv }, model: model || null, ...(yolo !== undefined ? { yolo } : {}),
     hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT, kernelBin: kernelBin(),
     ...(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
@@ -2984,7 +3077,7 @@ function* spawnBody(root, agent, o = {}) {
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
       decision, preflight,
       backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
-      harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
+      harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, launchConfigDefault: launchConfig?.harnessDefault === true, yolo, backend,
       launch: launchReport({ declared: launchChoice.declared, harness, model, launchConfig: launchConfig?.name, from: launchChoice.from, at: launchChoice.at }),
       branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
       relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
@@ -3523,7 +3616,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const shimTarget = writeKernelShim(home);
     const recipe = {
       version: LAUNCH_RECIPE_VERSION, harness,
-      launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null,
+      launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null, ...(launchConfig?.harnessDefault ? { launchConfigDefault: true } : {}),
       executable: bin, executableDeclared: executable.declared, executableResolvedFrom: executable.resolvedFrom,
       args: [...(launchConfig?.args || [])], env: { ...(launchConfig?.env || {}) },
       model: model || null, ...(yolo !== undefined ? { yolo } : {}),
@@ -3531,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),
@@ -3838,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";
@@ -265,7 +265,8 @@ export function inspectDocument(t, { kernel }) {
     // What a new tmux spawn here would open in: {tmuxSession} (0.31).
     session: t.session ?? null,
     knowledge: kcap ? { provider: kcap.id, version: kcap.version, operations: kcap.operations.map((o) => ({ name: o.name, kind: o.kind, available: o.available, reason: o.reason })) } : { provider: null, version: null, operations: [] },
-    instance: m ? { home: t.home, instance: m.instance, agent: m.agent, harness: m.harness || null, model: m.model ?? null, yolo: m.yolo ?? null, launched: !!m.launched, createdAt: m.createdAt || null,
+    instance: m ? { home: t.home, instance: m.instance, agent: m.agent, harness: m.harness || null, model: m.model ?? null, yolo: m.yolo ?? null,
+      launchConfig: m.launch?.launchConfig ?? null, launchConfigDefault: m.launch?.launchConfigDefault === true, launched: !!m.launched, createdAt: m.createdAt || null,
       resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
     ...(m ? { identity: servedIdentityOf(m) } : {}),
     problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.discoveryError ? [t.discoveryError] : []),
@@ -307,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";
@@ -410,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;