@awebai/oats 0.31.0 → 0.33.0

package/docs/oats-local.schema.json

@@ -60,7 +60,8 @@
             "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops."
           },
           "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
-          "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." }
+          "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." },
+          "default": { "type": "boolean", "description": "This host's baseline for its harness (0.32, feature launch-config-default): a new launch that picks this harness without naming a configuration (a soul's or souls.launch preference, --harness, the host default) runs this configuration's executable, args, env and yolo; its model is the last fallback. At most one per harness. `--launch-config none` bypasses it. OATS 0.31 and older refuse the key." }
         }
       }
     },

package/docs/official-catalog.md

@@ -11,8 +11,8 @@ or workspace membership alone does not make a package official.
 |---|---|---|---|
 | `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.17.3` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.3.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.aweb` | `v1.17.5` | `oats.aweb` (messaging) | |
+| `oats.engineering` | `v1.4.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
 | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |

package/docs/packages.md

@@ -76,7 +76,7 @@ members:
 packages:
   oats.framework: v1.4.1
   oats.okf: v4.0.5
-  oats.aweb: v1.17.3
+  oats.aweb: v1.17.5
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.17.3                         # a catalog version
+oats package add oats.aweb v1.17.5                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```

package/docs/plans/0.30-close-out.md

@@ -69,8 +69,11 @@ Found by the rehearsals, and fixed before the tag:
 ## After the tag
 - **Flag day:** the oats.engineering release with the souls' `launch:` (experts on Claude Code +
   Opus 5.5; `code-reviewer` on Codex + Astra; compat `>=0.30.0`), and committing the shared team id.
-- **0.30.1:**
-  - the kernel items that miss the tag: retire of homes whose session is gone, automations.trust;
+- **0.30.1:** one release, cut when the Desktop load work has merged (the kernel read-path PR with
+  `observe-max-age` and `observation.localRevision`, Desktop #321 and #322), or on 2026-09-30 18:00 UTC,
+  whichever comes first; what has not merged by then goes to 0.30.2. Retire of homes whose session is
+  gone (#299) and automations.trust (#300) shipped in 0.30.0. The kernel items below have no owner yet:
+  each rides 0.30.1 only if it merges before the cut.
   - deployment-scope capability commands without `--soul`;
   - the case-8 pre-check (`E_TEAM_UNCONFIGURED`).
   - the kernel refuses an unrecognised spawn argument (a bare `join=oats` without
@@ -79,5 +82,5 @@ Found by the rehearsals, and fixed before the tag:
     FIRST on the instance's PATH and records it in the launch recipe, so plain `oats` inside an
     instance is the kernel that made it (two kernels side by side: a 0.30 home ran the global 0.24.6
     and `oats aweb` was `E_UNKNOWN_COMMAND`; the injected instructions tell agents to run plain `oats`).
-- **Parked:** item L (`git rm agents/`, cli-dev-v2-native). It needs the GitHub `workflow` token
-  scope from the human on the lead's machine.
+- **Done:** item L merged in #314 (d4f68da9): the remaining legacy `agents/` soul trees and the
+  `validate:okf` gate are removed.

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

@@ -0,0 +1,137 @@
+# OATS 0.32.0
+
+## Added
+
+- **A default launch configuration per harness.** `default: true` on a
+  launch configuration in `oats-local.yaml` makes it this machine's baseline
+  for its harness. Every new launch of that harness that names no
+  configuration runs its executable, args, env and `yolo`: a soul's own
+  `launch:`, an inline `souls.launch` preference, `--harness`, the host
+  default. For example, every claude instance on a machine runs with its
+  `CLAUDE_CONFIG_DIR`:
+
+  ```yaml
+  launch-configs:
+    mine:
+      harness: claude
+      default: true
+      env: { CLAUDE_CONFIG_DIR: /home/me/.claude-personal }
+  ```
+
+  The model still comes from whatever chose the harness; the default's
+  `model` is only the last fallback. A named configuration runs as declared,
+  and `--launch-config none` asks for the bare harness. One default per
+  harness (a second is refused, naming both). `oats launch-config list`,
+  `spawn --preview`, `launch-config preview`, `instance.json` and
+  `oats inspect --home` say when a launch came from the default
+  (`launchConfigDefault`), yolo included. Existing instances keep their
+  launch until `--reselect-launch` or a respawn, and meanwhile show the
+  `launch-changed` readiness warning. Feature
+  `launch-config-default`
+  ([configuration.md](../configuration.md#the-harness-default)).
+  **Declaring a default needs OATS 0.32+ for every kernel that reads this
+  deployment:** OATS 0.31 and older refuse the whole `oats-local.yaml`
+  (`E_WORKSPACE_SCHEMA`). A routed `launch-config set --server` with
+  `default: true` to an older host is refused (`E_REMOTE_INCOMPATIBLE`)
+  before anything is sent.
+
+- **Every instance a server reports is first-class in the Desktop, whoever
+  spawned it.** A remote row opens its terminal, starts, restarts, stops and
+  retires, and shows its readiness, activity, Git and diffs, just like a local
+  one; only its pull request is not read here, since the forge reads this
+  computer's clones. Stop and Remove keep their confirmations: the plan and
+  its guarded apply run on the instance's machine. Every command goes to the
+  server by the instance's home (`--server <id> --home <path>`), never by a
+  bare name, so two instances with the same name stay apart. While a read is
+  in flight, the view says "Reading from <server>…". When the server refuses,
+  it shows the server's code and message under a headline that usually names
+  the server; it never falls back to a local read. A remote stop or remove
+  that loses its link reads as an unknown outcome, never a failure, and the
+  server's roster is read again at once
+  ([desktop.md](../desktop.md#instances-on-servers)).
+- **A row that can't be opened says why, on the row.** The roster shows a short
+  reason where it said "state unknown": Herdr no longer supported, gone from
+  <server>, not reachable on <server>, or <server> not reached. The full
+  sentence stays in the row's tooltip and its actions menu. For an instance a
+  server no longer lists, it names the command that removes it from this
+  computer (`oats server forget <server> --instance <name>`).
+- **This computer's OATS 0.31 decides which server rows can be used.** The
+  Desktop accepts OATS CLIs up to 0.32.x. With a local OATS before 0.31, which
+  does not report that fact, an instance spawned from this computer stays
+  usable through its saved route, as before; its routed reads and plans ask you
+  to update OATS here.
+- **A team card lists its members wherever they run.** On a local workspace's
+  Teams page, each team with a provider id lists every instance in it: this
+  workspace's, and every registered server's whose messaging identity is in
+  that team. They are grouped by machine ("This computer" first), with each
+  one's state in words. A member's name shows its roster row, where every
+  action lives; **Terminal** opens a running member there. A server whose
+  last roster read failed keeps its last-known members under "<server> · not
+  reached"; servers with nothing to show are named under the page head. The
+  card's count reads "N members · M on other machines". The Desktop reads
+  this from what it already holds and runs nothing new
+  ([desktop-teams.md](../../packages/desktop/docs/desktop-teams.md#team-members)).
+- **The spawn dialog asks "Where to run" up front** (it was "Run on", under
+  Developer settings). "This computer" comes first, then each registered
+  server. A server is disabled, with the reason, when it wasn't reached or
+  the roster knows only an older registration of it. With a server chosen,
+  the dialog says where the instance will run, and the relationship picker
+  lists only that server's instances: a relation never crosses machines. When
+  the server refuses the spawn (a soul it doesn't offer, for example), the
+  dialog says so in the server's own words.
+- **The Desktop keeps and sets a harness's default launch configuration.**
+  Editing a configuration marked `default: true` saves it with its default
+  intact, and with an OATS that has `launch-config-default` the editor offers
+  "Default for <harness> on this machine" for this computer's own
+  configurations. A remote host's default survives editing too, but is set on
+  that host. A second default for the same harness is refused in OATS's own
+  words; unset the old one first.
+
+- **Faster read verbs, and `--max-age <s>` to reuse recent remote heads**
+  (feature `observe-max-age`). `status`, `workspace status`, `souls`,
+  `capabilities` and `inspect` start far fewer git processes, cache what
+  they parse by commit, and start the members' remote reads together with the
+  host's. With `--max-age` they reuse a head observed in the last `<s>`
+  seconds and report `observation {observedAt, reused, localRevision}`
+  (`localRevision` changes whenever the local configuration read for the
+  answer does). See
+  [Observation reuse](../desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311).
+
+## Fixed
+
+- **A remote spawn with an empty opening instruction starts it waiting**, as
+  the dialog says. It was refused ("--task needs a value").
+- **Focus stays put on the Workspace's Teams, Capabilities and Setup pages.**
+  Every roster poll rebuilt the page, since the workspace status it compared
+  carries a fresh observation time each time, so keyboard focus (and the
+  caret in the add-team form) fell back to the page every few seconds.
+- **A click on a Desktop instance's actions menu does what it says.** With the
+  pointer over the open menu, the row no longer counted as hovered, so its
+  tools, the menu included, went hidden and a click on an item did nothing;
+  the keyboard still worked.
+- **The Stop and Remove confirmations show only their own choices.** Stop
+  showed Remove's "delete the worktree" and "delete the local branch" options
+  (enabled, and ignored), and Remove showed Stop's "include recorded children".
+
+- **A remote read that times out no longer leaves its ssh or https helper
+  running.** The kernel killed git but not the ssh or `git-remote-https` it
+  had started, which stayed connected to an unreachable host until its own
+  connection gave up. Git now runs as its own process group, and a timeout
+  (or the end of the command) kills the whole group.
+
+- **A capability command whose provider dies of a signal exits as the shell
+  reports it** (128 + the signal number, 130 for a Ctrl-C), not 1.
+
+- **`oats --help` piped into another program is no longer cut off at 8 KB.**
+  The top-level usage (about 20 KB) now arrives whole, including the
+  "Observation reuse" section; exit codes are unchanged.
+
+## Removed
+
+- **`oats-claude-config` is no longer read.** The one-line file that named
+  the claude binary for every deployment below it is replaced by the claude
+  default launch configuration. A new claude launch with one in reach is
+  refused with `E_CLAUDE_CONFIG_REMOVED`, naming the file and the
+  configuration to declare instead (`harness: claude`, `executable: <the
+  name it held>`, `default: true`); then delete the file. Instances already
+  launched with it keep their recorded executable.

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/automations.mjs

@@ -34,6 +34,7 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { recordLocalInput } from "./local-inputs.mjs";
 import YAML from "yaml";
 import { parseConfigData } from "./config-data.mjs";
 
@@ -192,8 +193,11 @@ export function soulOriginOf(index, soul) {
 
 export const snapshotPath = (dep) => join(dep, ".agents", "automations", "snapshot.json");
 export function readSnapshot(dep) {
+  let text;
+  try { text = readFileSync(snapshotPath(dep), "utf8"); } catch { recordLocalInput(snapshotPath(dep), null); return null; }
+  recordLocalInput(snapshotPath(dep), text);
   try {
-    const doc = JSON.parse(readFileSync(snapshotPath(dep), "utf8"));
+    const doc = JSON.parse(text);
     return isObject(doc) && KIND_NAMES.every((k) => Array.isArray(doc[`${k}s`])) ? doc : null;
   } catch { return null; }
 }