@awebai/oats 0.32.0 → 0.33.0

package/docs/release-notes/v0.33.0.md

@@ -0,0 +1,174 @@
+# OATS 0.33.0
+
+## Added
+
+- **`oats spawn <soul> --preview --max-age <seconds>`** (feature
+  `spawn-preview-max-age`). A preview reuses member heads this machine
+  observed at most that many seconds ago, as the read verbs do since 0.32.0,
+  so a warm preview asks no remote. With the flag the preview's JSON carries
+  the read verbs' `observation {observedAt, reused, localRevision}` block;
+  without it the preview is unchanged. The decision still covers the heads
+  the preview used: an apply with `--expect-decision` observes live and
+  refuses `E_DECISION_STALE` when a reused head has moved, and a re-preview
+  then shows the new head. The apply refuses `--max-age` (`E_BAD_ARGS`), and
+  the refusal message of every form that refuses the flag now lists
+  `spawn --preview` among the read forms.
+
+## Changed
+
+- **OATS fetches only what it reads from a remote** (awebai/oats#384). A
+  commit comes with its trees and its files up to 64 KiB; a larger file is
+  fetched when a read or a module needs it. The first spawn from a large
+  workspace host downloads megabytes instead of its whole tree (tsm: 13 MB in
+  3 s, instead of 2.4 GB in 6.5 minutes). A server that cannot serve partial
+  fetches (a default `git daemon`, an old self-hosted git), or a local git
+  older than 2.45, gets whole trees as before, with one `oats: warning` per
+  repository.
+
+- **Installing a soul's modules reads their files without a process per
+  file.** `oats spawn` copies each module's files from the remote cache
+  through the command's one `git cat-file --batch` reader per repository,
+  as the reads and discovery already do, instead of one `git cat-file blob`
+  per file. A Desktop developer spawn on this deployment ran 50 to 59
+  processes instead of 81 (34 per-file reads became 3 to 7 readers).
+  Budgets, digests, partial caches and errors are unchanged.
+
+- **oats.engineering 1.4.0** (catalog and workspace pin, and the bundled
+  mirrors): the developer's loop REQUIRES loading `/understand-the-spec` and
+  `/execution-strategy` before implementation.
+
+- **oats.aweb 1.17.5** (catalog and workspace pin, and the bundled mirror;
+  1.17.4 and 1.17.5): a faster spawn and retire. The spawn hook mints the identity with one
+  `aw init --join-from` instead of `aw team invite` + `aw team join` +
+  `aw init`, so the invite token no longer appears in any argv. The aw floor
+  check stops at `aw version`'s version line instead of waiting on its GitHub
+  update check. Retire deletes by workspace id, with `aw wake deregister`
+  running at the same time. Measured spawn hook: 7.72 s to 4.62 s mean
+  (awebai/oats-aweb#31). Hook output, compensation and the aw floor (1.36.13)
+  are unchanged. The mint now has one 120 s budget where three calls had
+  about 210 s; raise `OATS_AWEB_JOIN_TIMEOUT_MS` on a slow network. Since the
+  hook no longer holds the invite token, 1.17.5 always records the alias it
+  requested and warns, without quoting the reply, when aw reports another
+  (awebai/oats-aweb#32).
+
+- **Pressing Spawn (Cmd-Enter) closes the spawn dialog at once.** The spawn
+  completes in the background: a pending row ("Spawning…") appears in the
+  sidebar roster where the instance will stand, and is replaced in place by
+  the real row once the roster reports it. Outcomes arrive as notifications:
+  "<name> spawned" with Open, what didn't finish for a partial or incomplete
+  spawn (with View schedules for a wake that wasn't saved), and, for a
+  refused or failed spawn, the reason with **Reopen spawn**, which restores
+  the whole draft. An unknown outcome keeps the row, reading "Outcome
+  unknown", with Check result. Prepare reuses the dialog's fresh preview
+  instead of reading it again, and the kernel's `--expect-decision` still
+  refuses a decision that changed. Dialog previews use `--max-age 60` when the
+  CLI supports it (feature `spawn-preview-max-age`)
+  ([desktop-spawn-preview.md](../../packages/desktop/docs/desktop-spawn-preview.md#background-spawn-the-dialog-closes-on-spawn)).
+
+- **The spawn dialog never waits on the preview while you edit.** The last
+  preview stays visible while it updates, Spawn stays pressable, and answers
+  are reused for 60 s (#378).
+
+- **Core capabilities and Capabilities read as one system** on the soul page,
+  the capability page, the instance inspector and the spawn preview. Every
+  core row says why it's there, including a slot the soul empties or that has
+  no default. The capability page opened from a soul gains a "Why" row.
+  Workspace › Capabilities lists Repo owned before Packages (#377).
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.34.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.33.0 together: the
+  Desktop 0.32.x refuses a 0.33 CLI.
+
+- **Unattended claude and codex launches** (awebai/oats#341,
+  [souls-and-instances.md](../souls-and-instances.md#unattended-launches-folder-trust)).
+  - Every codex launch passes `-c check_for_update_on_startup=false`, so
+    Codex's update prompt no longer blocks it.
+  - Codex does not apply a trusted parent to the folders below it. When
+    `~/.codex/config.toml` trusts the deployment or an ancestor, a codex
+    launch now trusts its new home for that session; the file is never
+    written.
+  - A claude or codex spawn whose home is not covered by the operator's
+    one-time trust of the deployment warns `the <harness> session will stop
+    at its folder-trust prompt: trust <deployment> once (…)`. `oats readiness`
+    reports the same as a `harness-trust` item in `checks.configured` (not
+    required).
+
+- **The Desktop names an OATS cache problem, and keeps the roster through an
+  unreadable remote.** When the kernel can't read a remote
+  (`E_REMOTE_UNREADABLE`), the sidebar roster keeps the instances it last
+  observed instead of going empty. A cache problem (`details.reason: "cache"`)
+  reads "Couldn't refresh instances · OATS cache problem · observed <age>",
+  with the kernel's message in full (it names the lock file or the process
+  holding it, and the remedy) and Retry. With nothing observed yet, the failed
+  state shows that message. A network failure or a timeout reads "Couldn't
+  reach <host> · showing what was read <age>", with the raw code behind
+  Details. Of the kernel's structured `details`, only the reason and the
+  host of the remote cross to the window; the kernel's message is shown as
+  given, with the file or process it names
+  ([desktop-cli-api.md](../desktop-cli-api.md#workspace)).
+
+## Fixed
+
+- **A background spawn never fails silently, and a soul can't be spawned
+  twice at once** (awebai/oats#383). While a spawn of a soul is in flight,
+  opening Spawn for it shows the press disabled with "A spawn of <soul> is in
+  progress" and a link to its pending row; it re-enables when the spawn
+  settles. After a window reload, a spawn whose outcome wasn't known yet comes
+  back as a pending row and its outcome is reported, a failure included, even
+  when it settled while another workspace was on screen; Reopen spawn then
+  restores the soul and the name. Quitting the Desktop mid-spawn
+  still loses an unreported failure
+  ([desktop-spawn-preview.md](../../packages/desktop/docs/desktop-spawn-preview.md#background-spawn-the-dialog-closes-on-spawn)).
+
+- **A git that the system kills is no longer reported as a timeout**
+  (awebai/oats#387). A remote read reports `timeout` only when OATS's own
+  timer stopped git. When something else kills git (an out-of-memory kill
+  during a large fetch, for example), the error now reads `cannot read remote
+  <url> (killed): git was killed (signal SIGKILL)`, with `reason: killed` and
+  `details.signal`. Before, it said `(timeout)`.
+
+- **Codex sessions see their instance** (awebai/oats#342). Codex can run tool
+  commands under its shared app-server daemon, without the session's
+  environment, so `oats aweb roster` inside Codex asked for `--soul`.
+  - A codex launch now sets the instance environment for tool commands with
+    `shell_environment_policy.set`: `OATS_INSTANCE`/`OATS_INSTANCE_HOME`, the
+    capabilities' launch environment (`AWEB_IDENTITY_HOME`, `AWEB_DELIVERY`)
+    and the launch configuration's literals.
+  - It also sets `PATH` with the home's `.oats/bin` first. The user's login
+    shell may put its profile's entries ahead of it.
+  - A capability command with no home in its environment finds the home from
+    its working directory.
+
+- The partial-fetch tests now pass on a host whose git is older than 2.45
+  (awebai/oats#389). The kernel already fell back to whole trees there; the
+  tests now read the kernel's own git probe:
+  - on an older git they assert that fallback (whole trees, one warning per
+    repository);
+  - they skip the partial-cache mechanics that cannot happen there, and name
+    why;
+  - under CI, an older git fails those tests instead.
+
+- **A killed fetch no longer leaves a remote cache unusable** (awebai/oats#386).
+  OATS ends git with SIGTERM first, so git removes its own lock files, and
+  SIGKILL only after a grace. A lock left by a git killed earlier is removed
+  once it is older than the longest fetch, with an `oats: warning` naming it.
+  A younger one is never removed: the error names the file and says it is
+  safe to remove once no oats or git process is running.
+
+- **Ending git leaves no survivor in its process group** (awebai/oats#386). After
+  git's own output closes, OATS keeps checking git's process group until the grace
+  ends: a member that ignores SIGTERM and holds no pipe is still killed, and a
+  group seen empty is never signalled again (its id may already belong to another
+  process).
+
+- **Processes making the first fetch from one remote at once all succeed**
+  (two spawns, two Desktop previews). Every write to a cache takes a
+  per-cache lock: a live holder is waited for, a dead one's lock is reclaimed,
+  and the cache repo appears whole. A failure to write the local cache is now
+  reported as `E_REMOTE_UNREADABLE` with the new reason `cache`, never as
+  `network`.
+
+- Fetching a commit into the remote cache may take 10 minutes instead of 30 s, so
+  the first spawn from a large workspace host no longer fails with `cannot read
+  remote … (timeout)`; the timeout error names the fetch and the elapsed time
+  (awebai/oats#362).

package/docs/souls-and-instances.md

@@ -204,6 +204,70 @@ the harness's own precedence. The `CLAUDE.md → AGENTS.md` and
 `.claude/skills → ../.agents/skills` aliases are kept. OATS composes
 instructions and pins model/provider settings; it excludes nothing.
 
+### Unattended launches: folder trust
+
+Claude Code and Codex ask before they work in a folder they have not seen, and
+every instance home is new. A launch stopped at that prompt waits for a human,
+so the operator trusts the **deployment directory** (where `oats-local.yaml`
+is) once per harness. OATS only reads the harnesses' configuration; it never
+writes it.
+
+- **Claude Code** looks for an accepted entry for its folder or an ancestor, up
+  to a git root. Instance homes are not inside a git repository, so one entry
+  for the deployment covers every home under it. To add it, run `claude` in the
+  deployment once and accept the prompt. That records
+  `projects["<deployment>"].hasTrustDialogAccepted` in `~/.claude.json`
+  (`$CLAUDE_CONFIG_DIR/.claude.json` when that is set).
+- **Codex** applies only an exact entry: a trusted parent does not cover the
+  folders below it. To give the operator's consent, run `codex` in the
+  deployment once and choose "Trust and continue". That records
+  `[projects."<deployment>"] trust_level = "trusted"` in
+  `~/.codex/config.toml` (`$CODEX_HOME/config.toml`). With that entry, or one
+  for an ancestor of the deployment, each codex launch trusts its own new home
+  for that session (`-c 'projects={"<home>"={trust_level="trusted"}}'`) and
+  leaves the config file unchanged. A yolo launch always does this. The plan
+  re-reads the entry at every start.
+- Every codex launch also passes `-c check_for_update_on_startup=false`, so
+  Codex's "Update available" choice cannot block it.
+
+When a claude or codex home is not covered, the spawn says so (text and
+`--json` `warnings`): `the <harness> session will stop at its folder-trust
+prompt: trust <deployment> once (<the step>)`. `oats readiness` reports the
+same in `checks.configured` (code `harness-trust`, not required).
+
+### Codex tool commands and the instance environment
+
+Codex can run tool commands under its shared app-server daemon rather than as
+children of the session OATS launched, and then they do not inherit the
+session's environment. Codex (0.157.1) runs a session that has `-c` overrides
+embedded, without the daemon, and every kernel codex launch has them, so an
+OATS codex session does not appear in `codex agents`. So that the environment
+does not depend on this, a codex launch also sets it for tool
+commands explicitly with `-c shell_environment_policy.set.<NAME>="<value>"`:
+
+- the instance: `OATS_INSTANCE`, `OATS_INSTANCE_HOME`, `PI_AGENT_INSTANCE`,
+  `PI_AGENT_HOME`;
+- every capability's launch environment (for example the messaging
+  provider's identity home and delivery mode);
+- the launch configuration's literal values. A reference's value never goes
+  on a command line.
+
+`PATH` comes from the launching shell, with the home's `.oats/bin` first, so
+only the execution passes it; the persisted command does not carry it. Codex
+runs tool commands through the user's login shell, and a profile that prepends
+directories puts those entries ahead of `.oats/bin`. A second `oats` in such a
+directory is found first.
+
+A capability command (`oats <namespace> …`) run with none of
+`OATS_INSTANCE_HOME`, `PI_AGENT_HOME` or `OATS_HOME` set finds its instance
+from the working directory. It uses the nearest enclosing directory laid out as
+`<agents-root>/<soul>/instances/<name>` whose `instance.json` records that
+name, and validates it like a home named by the environment. The walk uses the
+directory as the shell names it (`$PWD`). That matters for an attached
+instance, whose `work/` links into its owner's tree: below it, the physical
+path is the owner's. A process that has no `$PWD` there would act as the
+owner, so an attached instance runs capability commands from its home.
+
 ## Lifecycle
 
 ### Spawn

package/docs/workspaces.md

@@ -183,7 +183,7 @@ as `confirmed` or the reason it is not:
 | `not-listed` | the workspace does not list the repo |
 | `no-backlink` | no (or invalid) `oats-membership.yaml` at the member's default branch |
 | `backlink-elsewhere` | the member names a different workspace (a case-only difference is flagged: repo paths are case-sensitive identities) |
-| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout) |
+| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory), or this machine's remote cache could not be written (cache) |
 
 An unconfirmed member contributes nothing but its row: its souls are invisible,
 its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).

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;