@awebai/oats 0.31.0 → 0.33.0

package/docs/configuration.md

@@ -50,6 +50,11 @@ launch-configs:                              # named ways this host starts a har
       CLAUDE_CONFIG_DIR: { fromEnv: PERSONAL_CLAUDE_DIR }
     model: opus
     yolo: false
+  mine:
+    harness: claude
+    default: true                            # this host's baseline for every claude launch (0.32)
+    env:
+      CLAUDE_CONFIG_DIR: /home/ana/.claude-personal
 ```
 
 Schema: [`oats-local.schema.json`](oats-local.schema.json). Unknown keys are
@@ -70,7 +75,7 @@ refused (`E_WORKSPACE_SCHEMA`).
 | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
 | `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
 | `triggers.disabled`, `schedules.disabled` | Workspace triggers and schedules (`<member>/<id>`) this host does not run, without a commit. Written by `oats trigger disable` / `oats schedule disable`. |
-| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. See [Launch configurations](#launch-configurations). |
+| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. `default: true` makes it this host's baseline for its harness (0.32). See [Launch configurations](#launch-configurations). |
 | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
 
 How teams are resolved, and what a messaging provider does with them, is in
@@ -81,8 +86,9 @@ How teams are resolved, and what a messaging provider does with them, is in
 An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
 (a bare name looked up on `PATH`, or a path relative to this deployment
 directory), `args` (literal, no shell), `env` (a literal string, or
-`{ fromEnv: NAME }` resolved on the host at start), `model` and `yolo`. A
-launch configuration is a host choice: a soul never names one.
+`{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
+`default` (0.32; see [the harness default](#the-harness-default)). A launch
+configuration is a host choice: a soul never names one.
 
 - Select one with `--launch-config <name>` on `oats spawn`,
   `oats session start` and `oats session restart`. A named configuration is
@@ -104,6 +110,50 @@ launch configuration is a host choice: a soul never names one.
 - The old key `runtime` is still read as `harness`, with a
   `deprecated-runtime-name` warning.
 
+### The harness default
+
+`default: true` makes a configuration this host's baseline for its harness
+(0.32, feature `launch-config-default`). Use it for what every launch of a
+harness on this machine needs, whatever soul or preference chose it: an
+account directory (`CLAUDE_CONFIG_DIR`), a wrapper `executable`, an argument.
+
+- **When it applies:** a new launch that picks the harness without naming a
+  configuration: a soul's `launch:`, an inline `souls.launch` preference,
+  `--harness` (on a spawn, or on `session start|restart` of an existing
+  home), `--reselect-launch`, and the host default (`pi`). It supplies the
+  executable, args, env and `yolo`. A `yolo` recorded from a default stays
+  with it: a later `--launch-config none` or another harness does not carry
+  it over.
+- **The model** comes from whatever picked the harness (`--model`, then the
+  preference); the default's `model` is the last fallback, before the
+  harness's own.
+- **A named configuration runs as declared**: `--launch-config <name>` or a
+  `souls.launch` name never inherits from the default. `--launch-config none`
+  (or a `souls.launch` entry of `none`) asks for the bare harness and
+  bypasses it.
+- **One per harness.** A second `default: true` for the same harness is
+  refused (`E_LAUNCH_CONFIG_INVALID`, naming both); move it by clearing the
+  old one first.
+- **Existing homes keep their launch** until `--reselect-launch` or a
+  respawn, like any change of preference. Declaring a default is such a
+  change: `oats readiness --home` warns `launch-changed` on each existing
+  home the default would now apply to, until it is restarted with
+  `--reselect-launch` or respawned.
+- **It is visible.** `oats launch-config list` marks it; `spawn --preview`,
+  `launch-config preview`, `instance.json` and `oats inspect --home` say when
+  a launch's configuration came from the default (`launchConfigDefault`).
+  A default with `yolo: true` turns yolo on for every launch of that harness
+  here: the preview shows it.
+- **Every kernel that reads the deployment needs OATS 0.32+.** OATS 0.31
+  and older refuse the whole `oats-local.yaml` (`E_WORKSPACE_SCHEMA`) once a
+  configuration declares `default`.
+
+`oats-claude-config` (a one-line file naming the claude binary, found walking
+up from the deployment) is no longer read. A new claude launch with one in
+reach is refused (`E_CLAUDE_CONFIG_REMOVED`) naming the file: declare the
+name it holds as the claude default (`executable: <name>`, `default: true`)
+and delete the file. Homes launched with it keep their recorded executable.
+
 ### Launch preferences
 
 A soul says what its role should run on, and each machine may override it
@@ -128,9 +178,11 @@ souls:
   harness and replaces only its model.
 - A **launch configuration** name runs that configuration's full recipe. An
   **inline or soul preference** runs its harness the way this host starts it
-  without a configuration (the executable on `PATH`, no args, no env), with
-  its `model`. A preference without `model` uses the harness's own model; it
-  never borrows a lower layer's.
+  without a configuration: [the harness default](#the-harness-default) if
+  one is declared, else the executable on `PATH` with no args and no env,
+  with the preference's `model`. A preference without `model` uses the
+  harness default's model, else the harness's own; it never borrows a lower
+  layer's.
 - **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`
   names the layer that chose it and the fix (install the harness, or override
   it here in `souls.launch`). `oats souls` still lists the soul, with the
@@ -274,5 +326,10 @@ oats spawn <soul> --preview    # the exact modules, teams and provider payloads
 oats doctor                    # this deployment's files and the lock
 ```
 
-Environment: `OATS_REMOTE_CACHE` relocates the fetch cache;
-`OATS_PACKAGE_CATALOG` names an alternative package catalog file.
+Environment: `OATS_REMOTE_CACHE` relocates the fetch cache (which also holds
+the bounded parsed-read cache and the observations `--max-age` reuses; all of
+it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
+catalog file. The read verbs (`status`, `workspace status`, `souls`,
+`capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
+`spawn --preview`) take `--max-age <seconds>` to reuse a remote head observed that recently
+([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)).

package/docs/design/2026-09-23-workspace-module-contracts.md

@@ -55,8 +55,9 @@ symlink enters as `symlink:<target>`; empty directories and a top-level `.git/`
 ### 1.3 Access, cache, failures
 
 - Git uses the operator's own configuration and credentials; `GIT_TERMINAL_PROMPT=0`,
-  `GIT_ASKPASS=/usr/bin/false` and ssh `-o BatchMode=yes` mean nothing prompts. 30 s per git call.
-- A commit is fetched depth 1 (no blob filter) into a bare cache `<cacheDir>/<sha256(key)>/` (default
+  `GIT_ASKPASS=/usr/bin/false` and ssh `-o BatchMode=yes` mean nothing prompts. 30 s per git call; 10 minutes for the fetch of a commit.
+- A commit is fetched depth 1 with its trees and its blobs up to 64 KiB (larger blobs on demand, when a read
+  needs them; whole trees from a server without partial fetches; awebai/oats#384) into a bare cache `<cacheDir>/<sha256(key)>/` (default
   `~/.cache/oats/remotes`; the CLI honours `OATS_REMOTE_CACHE`) and pinned as `refs/oats/commits/<oid>`.
   The cache may be wiped at any time. Operations on one cache repo are serialized.
 - Failures: `E_REMOTE_UNREADABLE { url, key, reason }`, `reason` ∈ `auth`, `not-found`, `network`,

package/docs/desktop-cli-api.md

@@ -38,7 +38,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
              "instance-events-2","schedule-history","schedule-read-2","spawn-preview-2","spawn-idempotency","spawn-idempotency-2","spawn-apply-2",
              "workspace-v2","instance-modules","spawn-provider-payload","served-identity","packages-no-approval","spawn-name","settings-origins",
              "team-model-2","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
-             "preview-composed-from"],
+             "preview-composed-from","observe-max-age","spawn-preview-max-age"],
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2}
 ```
@@ -95,6 +95,8 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `desktop-facts` | the facts under [Desktop facts](#desktop-facts-feature-desktop-facts-oats-0290) | |
 | `launch-preference` | soul and local launch preferences; `launch`, `launchCurrent`, `launchFrom`; `--reselect-launch`; `key` on soul and agent rows ([Launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) | |
 | `preview-composed-from` | `composedFrom` on preview `modules[]` ([Composition](#the-preview)) | |
+| `observe-max-age` | `--max-age <s>` on the read verbs and their `observation` block ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)) | |
+| `spawn-preview-max-age` | `--max-age <s>` on `spawn --preview` and its `observation` block ([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311), [The preview](#the-preview)) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -181,6 +183,94 @@ an inherited `OATS_DEPLOYMENT` or `OATS_RESOLUTION` (`details.inherited`).
 homes in `problems[]`: `legacy-captured-home {code, instances, homes,
 message}` and `legacy-local-agents {code, dirs, instances, message}`.
 
+<a id="observation-reuse-feature-observe-max-age-oats-0311"></a>
+### Observation reuse (feature `observe-max-age`, OATS 0.32.0)
+
+Every read asks each remote for its current head (`git ls-remote`). With
+`--max-age <seconds>` a read verb reuses a head this machine observed at most
+that many seconds ago instead, so a refresh right after another costs no
+network round trip. Gate the flag on the feature: an older kernel may ignore
+it and answer live, without the block.
+
+```text
+oats status | workspace status | souls | capabilities | inspect --soul|--home
+     | teams | soul teams <soul>   … --max-age <seconds> --json
+oats spawn <soul> … --preview --max-age <seconds> --json    (feature spawn-preview-max-age)
+```
+
+- **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
+  Anything else is `E_BAD_ARGS` (`--max-age needs a value: whole seconds from 0
+  to 86400`, `--max-age takes whole seconds from 0 to 86400, got "<v>"`).
+- **The block:** with the flag (`0` included) the document gains one key,
+  `observation: {observedAt, reused, localRevision}`: in the result of an
+  envelope, at the top level of the roster (after `agents`). `observedAt` is the
+  OLDEST remote head the answer used, so the answer is at least that fresh
+  everywhere; `reused` is `true` when any head came from an earlier observation.
+  A command that read no remote head reports the time it started and
+  `reused: false`. Without the flag the key is absent and every document is
+  exactly as before. A refusal (`E_SOUL_UNKNOWN`, any error envelope) never
+  carries the block.
+- **Spawn preview** (feature `spawn-preview-max-age`, OATS 0.33.0): the
+  preview's `result` gains the same block, so you can say "as of
+  `<observedAt>`". The `decision` covers the heads the preview used, reused
+  or live: a reused head the member has since moved from makes the apply
+  (which always observes live) refuse `E_DECISION_STALE`, and the apply
+  records the head it observed, so the next preview under `--max-age` shows
+  it with a new `decision.revision`. The apply itself refuses the flag.
+- **`localRevision`:** 24 lowercase hex characters, opaque. It digests every
+  piece of local configuration the kernel read for this answer:
+  `oats-local.yaml` (and each closer `oats-local.yaml` it looked for and did
+  not find), `oats-lock.json`, an `OATS_PACKAGE_CATALOG` file, and the
+  automations snapshot. Only what the verb actually read counts. The same inputs
+  give the same revision; any byte change, or one of those files appearing or
+  disappearing, gives another. It names no path and no content. Different verbs
+  read different inputs (`workspace status` also reads the automations
+  snapshot; `inspect --home` reads no lock), so compare revisions of the same
+  verb and arguments only. Keep what you
+  hold (catalogs, inspect results) keyed on it: a different revision means the
+  deployment's configuration changed outside you (a `teams` edit, a sync, a
+  hand edit). A kernel upgrade shows through the probe (`oats version --json`),
+  not through `localRevision`: the bundled catalog is not an input. Instance
+  homes, member clones and tmux are not inputs either, because the answer
+  itself reports them.
+- **What is reused:** only remote heads (the commit a branch or tag named),
+  never local state. Instances, `oats-local.yaml` and the lock are read afresh
+  by every command. A member's backlink (`oats-membership.yaml`) is read at
+  the member's observed head, which may be a reused one: a backlink removed
+  less than `<s>` seconds ago can still show the member `confirmed` under
+  `--max-age <s>`. Only the backlink's comparison with this workspace is made
+  afresh. A reused head's
+  `observedAt` (for example `workspace.observedAt` in `workspace status`) is
+  the time it was observed, not now.
+- **When a head is not reused:** it is older than the flag allows (or dated
+  more than 5 s in the future); it was observed through a different URL
+  spelling of the same repository (ssh vs https) or for a different ref; its
+  commit can no longer be fetched. Each is observed live, as without the flag.
+  A live observation that fails is the usual error, never an older head.
+- **Refusals:** every other command, a spawn apply (with or without
+  `--expect-decision`; the form named is `spawn`), every edit form (`teams add|remove|default`,
+  `soul teams --add|--remove|--default|--clear-default`) and any `--server`
+  invocation refuse the flag before reading or writing anything, with
+  `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
+  verbs reuse observations (status, workspace status, souls, capabilities,
+  inspect --soul|--home, spawn --preview, and the read forms of teams and soul
+  teams)" and,
+  with `--server`, "--max-age cannot be combined with --server: observation
+  reuse is local to this machine".
+  A capability command's argv (`oats <namespace> …`) is its provider's: the
+  kernel neither reads nor refuses `--max-age` there. The same holds for
+  `capture`, `recall`, `setup` and `experimental`, which parse their own argv:
+  `capture`, `setup` and `experimental` refuse it as an unknown argument (not
+  `E_BAD_ARGS`), and `recall` ignores unknown flags.
+
+The observations are kept under the remote cache
+(`$OATS_REMOTE_CACHE`, default `~/.cache/oats/remotes`), in `.observed/`,
+beside the bounded parsed-read cache in `.parsed/`. An observation record
+keeps a digest of the fetch URL, never the URL. A parsed entry keeps repository
+content as committed (member refs included), and a value that carries a
+credential-bearing URL (userinfo on http(s), or `user:password@` on any
+scheme) is never written. Deleting either is always safe.
+
 <a id="inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260"></a>
 ## Inspect, readiness and operation run
 
@@ -214,7 +304,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
 ### `oats inspect`
 
 ```text
-oats inspect (--home <abs> | --soul <name> [--dir <d>]) --json
+oats inspect (--home <abs> | --soul <name> [--dir <d>]) [--max-age <s>] --json
 ```
 
 An instance subject, abridged:
@@ -445,7 +535,25 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
   `E_LOCAL_MISSING {dir, searched}`.
 - The workspace is read over Git remotes with the operator's credentials,
   never prompting: `E_REMOTE_UNREADABLE {url, reason: "auth" | "not-found" |
-  "network" | "timeout"}`.
+  "network" | "timeout" | "killed" | "cache" | "unknown"}`. `killed` (the
+  system killed git, for example out of memory) also carries `signal`.
+  `cache` (OATS 0.33.0) is local: the
+  remote cache on this machine could not be written (a git lock still held,
+  another oats process still writing it, or a lock file one left when it
+  died); `details.cacheDir` and, when known, `details.lock`,
+  `details.guard` or `details.holderPid` say which, and the message says
+  what to do.
+- **How the Desktop reads it** (0.33.0). Of an `E_REMOTE_UNREADABLE` from
+  `status` / `workspace status`, the Desktop keeps the `message` (shown as
+  given) and only a bounded cause: `details.reason` (matching
+  `^[a-z][a-z-]{0,31}$`) and the host of `details.url`. No path, pid, lock,
+  `cacheDir` or other detail field crosses to the renderer. It keys only on
+  `code` + `details.reason`: `cache` words the roster "OATS cache
+  problem" with the message in full; `network` / `timeout` read "Couldn't
+  reach <host>"; any other reason keeps the generic wording. When the
+  deployment was observed before, the failed read keeps that observation:
+  `/api/panel` serves it with `error` (the message) and `errorCause {code,
+  reason, host?}`, and the roster shows it stale instead of empty.
 - There is no package approval: declaring a package is the trust decision.
   No payload carries `approvalNeeded`, `approval` or `approved`.
 - A **standalone view** is a member repository whose workspace is not read
@@ -597,7 +705,7 @@ discovers the workspace over the network to check. Other errors: `E_USAGE`,
 ### `oats workspace status`
 
 ```text
-oats workspace status [--dir <d>] --json
+oats workspace status [--dir <d>] [--max-age <s>] --json
 ```
 
 Read-only (it writes no lock):
@@ -646,8 +754,8 @@ Read-only (it writes no lock):
 ### `oats capabilities` and `oats souls`
 
 ```text
-oats capabilities [--dir <d>] --json
-oats souls [--dir <d>] --json
+oats capabilities [--dir <d>] [--max-age <s>] --json
+oats souls [--dir <d>] [--max-age <s>] --json
 ```
 
 Every item of every confirmed member, the external souls, and the locked
@@ -835,7 +943,7 @@ soul subject), `""` when unknown.
 ### `oats teams`
 
 ```text
-oats teams [--dir <d>] --json
+oats teams [--dir <d>] [--max-age <s>] --json
 oats teams add <label> --team <id> [--description <d>] --json
 oats teams remove <label> --json
 oats teams default <label> --json
@@ -874,6 +982,7 @@ oats teams default <label> --json
 
 ```text
 oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default] [--dir <d>] --json
+oats soul teams <soul>|'*' [--dir <d>] [--max-age <s>] --json    (the read form only)
 ```
 
 ```json
@@ -1083,7 +1192,7 @@ the result with `oats inspect --soul <name> --json`.
 ### The preview
 
 ```text
-oats spawn <soul> [the flags of a real spawn] --preview --json
+oats spawn <soul> [the flags of a real spawn] --preview [--max-age <s>] --json
 ```
 
 Feature `spawn-preview-2`, `spawnPreviewApi: 2`. The preview runs every
@@ -1135,6 +1244,12 @@ it to a temporary copy (`soulFetched: true`).
   (absent when nothing sets it) are the resolved selection.
   `backendStatus` is `{name, installed, started: false}`, `null` with
   `--no-launch`. `executable` is the resolved harness binary.
+- `launchConfigDefault` (0.32, feature `launch-config-default`) is `true`
+  when `launchConfig` is this host's default for the harness (its
+  executable, args, env and `yolo` apply without being chosen), `false`
+  otherwise. Show it, and `yolo`, whenever it is `true`. An explicit
+  `--launch-config none` asks for the bare harness and bypasses the default;
+  to run the host's default, omit `--launch-config`.
 - `modelSource` is `"explicit"`, `"soul default"`, `"launch-config <name>"`,
   `"native default"` or `"native default (explicit)"` (`--model
   @native-default`). Omitting `--model` and asking for the native default are
@@ -1165,6 +1280,20 @@ it to a temporary copy (`soulFetched: true`).
   `payloadRevision` (the merged payloads). `workspace` is the host key;
   `standalone` marks a standalone view. `task` is the task text or `null`.
 
+**Observation reuse** (feature `spawn-preview-max-age`, OATS 0.33.0).
+- `--preview --max-age <s>` reuses member heads this machine observed at
+  most `<s>` seconds ago, as the read verbs do ([Observation
+  reuse](#observation-reuse-feature-observe-max-age-oats-0311): the same
+  values, refusals and fallbacks to a live observation). With the flag (`0`
+  included) the result gains `observation: {observedAt, reused,
+  localRevision}`, shaped exactly as the read verbs' block; without it the
+  preview is exactly as before, and no other field changes shape.
+- `decision.revision` covers the heads the preview used, reused or live.
+  Apply never reuses (it refuses `--max-age`): a head that moved since the
+  reused observation refuses `E_DECISION_STALE`, and the apply records what
+  it observed, so re-preview under `--max-age` to get the new head and
+  revision.
+
 **Provider settings.**
 - `providers` is the `--provider` map as typed.
 - `settings.<cap>`: the merged payload (manifest defaults, then workspace,
@@ -1346,10 +1475,11 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
 ### The roster (`oats status --json`)
 
 ```text
-oats status [--dir <d>] --json
+oats status [--dir <d>] [--max-age <s>] --json
 ```
 
-Not an envelope: `{root, agents, workspace?, problems?, warnings?}`.
+Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}`
+(`observation` only with [`--max-age`](#observation-reuse-feature-observe-max-age-oats-0311)).
 
 ```json
 {"root":"/w/agents",
@@ -1812,26 +1942,45 @@ accept `--server <id>`.
 {"context":"/w","level":"/w","file":"/w/oats-local.yaml","selected":null,
  "configurations":[{"name":"reviewers","harness":"claude","executable":null,"args":["--permission-mode","plan"],
                     "env":{"ANTHROPIC_API_KEY":{"fromEnv":"REVIEW_KEY"},"REVIEW_MODE":{"redacted":true}},
-                    "model":"opus","yolo":null,"source":"/w/oats-local.yaml","shadows":[]}]}
+                    "model":"opus","yolo":null,"default":false,"source":"/w/oats-local.yaml","shadows":[]}]}
 ```
 
 - **list**: `selected` is `null`, `{home, instance}` or `{soul, agentsRoot}`;
   `level` and `file` are `null` without an `oats-local.yaml` (the set is then
   empty). An environment literal is `{redacted: true}`, a reference
-  `{fromEnv}`; values never leave the file.
+  `{fromEnv}`; values never leave the file. `default` (0.32, feature
+  `launch-config-default`) is always a boolean: `true` marks this host's
+  default for the configuration's harness.
 - **set**/**remove**: `{name, action, level, file, before, after,
   effective}`. `set --file` takes `{harness, executable?, args?, env?, model?,
-  yolo?}` (`-` reads stdin). `--keep-env` keeps the declared environment when
-  `env` is omitted. Errors: `E_LOCAL_MISSING`, `E_BAD_ARGS` (including
-  `--home`/`--soul`), `E_LAUNCH_CONFIG_UNKNOWN`, `E_LAUNCH_CONFIG_INVALID`,
-  `E_CONFIG_BROKEN`, `E_HOME_UNKNOWN`.
+  yolo?, default?}` (`-` reads stdin); it replaces the whole entry and refuses
+  a key it does not know, so an editor sends `default` back to keep it.
+  `default: false` is written as its absence. A second `default: true` for a
+  harness is `E_LAUNCH_CONFIG_INVALID` with `details: {harness,
+  configurations: [<the declared one>, <this one>]}` and nothing is written;
+  moving the default is two writes, never an automatic move. `--keep-env`
+  keeps the declared environment when `env` is omitted. Routed with
+  `--server`, a definition with `default: true` to a host that does not
+  advertise `launch-config-default` is `E_REMOTE_INCOMPATIBLE` before
+  anything is sent (`default: false` is dropped). Errors: `E_LOCAL_MISSING`,
+  `E_BAD_ARGS` (including `--home`/`--soul`), `E_LAUNCH_CONFIG_UNKNOWN`,
+  `E_LAUNCH_CONFIG_INVALID`, `E_CONFIG_BROKEN`, `E_HOME_UNKNOWN`,
+  `E_REMOTE_INCOMPATIBLE`.
 - **preview** (read-only) answers `{context, selected, selection: {source,
   launchConfig, harness, model, yolo}, harness, model, modelSource, yolo,
-  launchConfig, launchConfigSource, executable: {path, declared,
-  resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
+  launchConfig, launchConfigSource, launchConfigDefault, executable: {path,
+  declared, resolvedFrom}, argv, environment: [{name, fromEnv} | {name, redacted:
   true} | {name, reference: true}], command (redacted), prompt, hooks,
   preflight: [{check, ok, detail}], ok}`.
 
+`launchConfigDefault` (0.32) is `true` when `launchConfig` is this host's
+default for the harness rather than a chosen configuration; the spawn preview
+carries the same top-level field, `instance.json` records it as
+`launch.launchConfigDefault: true`, and `inspect --json` of a home answers
+`instance.launchConfig` and `instance.launchConfigDefault`. The closed `Launch`
+object is unchanged: its `effective.launchConfig` names the default
+configuration.
+
 A successful envelope can carry `ok: false`: show the failed `preflight`
 checks. The prompt is named, never the task body. A home predating launch
 recipes answers its frozen command with `selection.source: "frozen-command"`

package/docs/desktop.md

@@ -110,6 +110,22 @@ registered remote workspace the timer and definitions live on that server, so
 they do not depend on the Mac staying awake. See [Schedules](schedules.md) for
 the CLI, cron semantics, observed outcomes and recovery commands.
 
+## Instances on servers
+
+Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
+can open its terminal, start, restart, stop and remove it, and read its readiness, activity, Git
+and diffs, as for a local one. Only its pull request is not read here, since the forge reads this
+computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
+<path>`), never by a bare name. Stop and Remove show the plan the server makes, and confirm
+against it.
+
+A read waits for the server: the view says "Reading from <server>…", and gives up after about
+45 seconds with "Couldn't reach <server>." When the server refuses, you see its code and message;
+nothing is read from this computer in its place. A row that can't be opened says why on the row:
+Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
+For an instance a server no longer lists, the reason names the command that removes it from this
+computer (`oats server forget <server> --instance <name>`).
+
 ## Remote terminals
 
 A terminal for an instance on a registered server is a viewer over ssh

package/docs/first-team.md

@@ -80,6 +80,23 @@ Host-owned provider values (absolute paths, state roots) go under `settings:` in
 `oats-local.yaml` afterwards — never in the workspace file, whose schema refuses
 them. Do not commit `oats-local.yaml`.
 
+**Trust the deployment once, for unattended launches.** Claude Code and Codex
+ask before they work in a folder they have not seen, and every instance home is
+new: a launch that stops at that prompt waits for a human. OATS never writes
+the harnesses' configuration, so trust the deployment directory yourself, once
+per harness you use:
+
+```bash
+cd ~/acme && claude    # accept the folder-trust prompt, then quit
+cd ~/acme && codex     # choose "Trust and continue", then quit
+```
+
+One entry covers every instance home under the deployment
+([souls-and-instances.md](souls-and-instances.md#unattended-launches-folder-trust)
+says how each harness applies it). Until then, a claude or codex spawn warns
+that its session will stop at the folder-trust prompt, and so does
+`oats readiness`.
+
 ## 3. Give the deployment a team
 
 With a messaging capability in the soul's composition, every instance lives in
@@ -117,8 +134,9 @@ oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run t
 oats status
 ```
 
-`--harness pi|claude|codex` picks the harness; complete any native folder
-trust or authentication prompt in the printed session. The instance home is
+`--harness pi|claude|codex` picks the harness; complete any native
+authentication prompt in the printed session (folder trust is the one-time step
+in section 2). The instance home is
 `agents/<soul>/instances/<instance>/`; `work/` is its repository view;
 `.oats/modules/<cap>/` are the copied capabilities and `.agents/skills/<skill>/` their skills;
 `instance.json` records `modules` (from, commit, digest), `providers` and

package/docs/implementation.md

@@ -30,7 +30,7 @@ published to npm. Its developer docs are in
 | `lib/` | the kernel (below) |
 | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
 | `skills/` | bootstrap skills shipped with the kernel |
-| `capabilities/` | this repository's own member capabilities (`oats-workspace-experts`), discovered at the member's latest state |
+| `capabilities/` | this repository's own member capabilities (`oats-desktop-ui`, `oats-workspace-experts`), discovered at the member's latest state |
 | `mirrors/` | generated byte mirrors of the official packages' capabilities (for example `oats-okf*`, checked by `scripts/check-okf-mirror.mjs`): release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package |
 | `oats-package/` | the `oats.framework` package |
 | `souls/` | this repository's own souls (a workspace member) |
@@ -44,6 +44,7 @@ published to npm. Its developer docs are in
 | module | owns |
 |---|---|
 | `remote.mjs` | repo refs, reading Git remotes, content digests |
+| `local-inputs.mjs` | the local configuration a command read, for `observation.localRevision` |
 | `workspace.mjs` | workspace, membership and soul files; discovery |
 | `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
 | `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
@@ -57,11 +58,130 @@ published to npm. Its developer docs are in
 | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
 | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation, the hook environment rules, the readiness wire |
 | `servers.mjs` | routing commands to a registered server |
+| `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
 
 The kernel is runtime-neutral: nothing in `lib/` depends on a harness or on
 a provider. Provider behaviour lives in capabilities; the kernel supplies
 their contracts ([layers](layers.md)).
 
+### The remote read path
+
+Every CLI command owns one read session (`createReadSession` in
+`remote.mjs`, carried to every remote call as `remoteOptions.session`; the
+CLI closes it when the command ends). A library caller without a session
+gets the plain per-call behaviour. Within a session:
+
+- a head is observed once per (cache repo, ref), and a commit peeled once; at
+  most eight observations run at once (`OBSERVE_LIMIT`), each holding its slot
+  for all its git work (the `ls-remote` and the fetch of the commit it names,
+  or the fetch of a reused record's commit);
+- a whole-workspace discovery prefetches its members' heads together with the
+  host's (`prefetchMembers` in `workspace.mjs`): the member list comes from the
+  host's last observation record and the parsed `workspace` entry at that
+  commit, never from a git process, and the answer still uses the list at the
+  host commit observed now. A prefetched failure is adopted by the member's own
+  observation, not retried in the command. A prefetch no caller adopts (the
+  host could not be observed, or the member was dropped since) is abandoned:
+  one still queued runs no git. `observeWorkspace` alone (the `teams` reads,
+  `inspect --home`) never prefetches;
+- closing the session (the end of the command, or `process.exit`) rejects
+  every queued observation and aborts every git child still running for it
+  (the session's `AbortSignal` rides every `runGit`). `runGit` starts git as
+  its own process group, so a timeout, an output overflow or an abort kills
+  git's ssh or remote helper with it; before a capability
+  command runs its provider, the CLI ends the idle batch readers
+  (`closeBatches`);
+- a commit's tree is listed once (`git ls-tree -r -t -l`, bounded by
+  `TREE_INDEX_BUDGET`; anything odd falls back to the per-path reads), and
+  blobs come from one `git cat-file --batch` reader per cache repo (at most
+  12 open, ended through `process-group.mjs` on timeout and at close);
+  `fetchRemoteTree` copies a module through it too, once `ensureBlobs` has
+  fetched what was missing (git re-reads its packs on a miss, so a reader
+  opened earlier finds the new blobs; one still missing answers `missing`,
+  never a fetch), with what is left of `TREE_BUDGET` as each read's bound;
+  a blob the reader answers `missing` or over its bound is read once more
+  alone, so the error is the one a copy without a session gives. A
+  command that ends normally awaits the close, so its readers are reaped
+  before it exits; a `process.exit` (every refusal) ends them in the
+  exit hook (`closeNow`), and the system reaps them once the process is gone;
+- every git child is ended with SIGTERM first and SIGKILL only after a
+  grace (`terminateGroup`): git removes its own lock files on SIGTERM, and
+  a git killed outright leaves one that blocks every later write. The
+  SIGKILL goes to the whole group even when git itself has exited, so a
+  descendant that ignores SIGTERM (ssh, a remote helper) still ends; but
+  never to a group seen empty, whose id may already lead an unrelated
+  group. Until git's `close` (`watchGroup`), a member holding its pipes
+  keeps the id ours; after it, the group is probed every 50 ms through the
+  grace (no pid is allocated while it is a live group's id): empty, and it
+  is never signalled again. git's pipes are drained on a kill, never
+  destroyed, so `close` keeps waiting for a pipe-holding descendant. The exit
+  hook cannot wait for a timer, so it waits a bounded 200 ms synchronously
+  (`reapOnExit`);
+- discovery reads members eight at a time (`DISCOVERY_CONCURRENCY`) with
+  serial results: declaration order, the first failure in that order. The
+  observations and the member reads are two pools, so a discovery runs at
+  most sixteen short-lived git processes at once (eight of them fetches at
+  most), plus up to twelve cat-file readers: twenty-eight git processes. One
+  shared pool would deadlock: a member read holding a slot waits on its
+  member's observation, which needs a slot of its own.
+
+The cache repos are partial: a commit is fetched with all its trees and
+only the blobs up to `SMALL_BLOB_LIMIT` (64 KiB), which covers every file
+discovery reads, so listings and discovery stay local after one fetch. A
+read that needs a larger blob, or a `fetchRemoteTree` of a module, fetches
+the missing blobs first in one fetch by id (`ensureBlobs`), then applies the
+budgets to their real sizes before anything is written. git never fetches a
+blob lazily (`GIT_NO_LAZY_FETCH=1`, and no url is stored in the cache: each
+fetch passes it with `-c remote.origin.url=`). A server without partial
+fetches gets whole trees; the cache records that (`oats.fetch = full` in its
+config) and the CLI prints the session's notice once, on stderr. Partial
+caches need git 2.45 or later (`PARTIAL_FETCH_GIT`, the first git with
+`GIT_NO_LAZY_FETCH`): with an older git every cache fetches whole trees, a
+partial cache it meets is deleted and fetched again whole, and the same
+notice says why.
+
+Every write to a cache repo (its `git init`, config, fetches and pins) holds
+the repo's cross-process write lock, `<cache>/.locks/<repo>.lock`
+(`withCacheWriteLock`): an exclusive file holding `{pid, token, startedAt}`,
+waited for while its holder lives (bounded by a whole fetch, then
+`reason: "cache"` naming the pid), reclaimed when the holder is dead, and
+released only by its owner. Reclaimers take a short guard,
+`<lock>.reclaim`, and check under it that the lock is still the dead
+record before removing it, so a reclaimer that paused cannot delete a
+live process's new lock. A guard whose holder died is never removed
+automatically (that removal would race the same way, with nothing left to
+serialize it): every write refuses at once, `reason: "cache"` naming the
+guard (`details.guard`), until a human removes it once no oats process is
+running. Reads take no lock. A cache repo appears whole
+(`git init` into a private directory, then a rename), so processes making
+the first fetch of one remote all succeed. A git `*.lock` a write meets is
+judged under that lock (`cacheGit`): older oats kernels take no write lock,
+so it is retried briefly, then removed only when it is inside the cache
+repo, a regular file and older than the longest fetch
+(`GIT_FETCH_TIMEOUT_MS` plus a margin): a git killed mid-write. A removal
+is said once as a warning. Anything else is `reason: "cache"` naming the
+file and when it is safe to remove; so is any other local write failure
+(a `FETCH_HEAD` git cannot open, a read-only or full disk), with git's own
+words.
+
+Across commands, `memoAtCommit` keeps parsed reads under
+`<cache>/.parsed/<kernel fingerprint>/`, keyed by (repo key, full commit,
+item). The items: `workspace` (the workspace file), `membership` (a member's
+backlink outcome), `enumerate` (a member's souls and capabilities),
+`package-soul` and `external-soul` (one soul file each; their error handling
+differs), `package-manifests` (a package's manifests), `list` (a skill
+listing) and `tree-oids` (the tree ids of a set of directories). An entry is only ever a pure function of those bytes and this kernel's
+code, never local state and never a transient error; it is written
+atomically, a corrupt one is a miss, and `pruneStores` bounds the store
+(`PARSED_LIMITS`, least recently used first). `--max-age` adds the observation
+store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
+one record per (repo key, ref args, url digest), so two spellings of one repo
+keep a record each; the url itself is never written. Adding a cached item
+means choosing an item name unique to its producer (the item string its
+call site passes to `memoAtCommit`, or to `atCommit` in `workspace.mjs`) and
+adding it to `test/parsed-cache.test.mjs`; `test/read-path-scale.test.mjs` pins the member
+scaling by call count.
+
 ## Tests and gates
 
 | command | what it checks |

package/docs/integrations.md

@@ -41,7 +41,7 @@ arrives from.
 # oats-workspace.yaml: one default per slot, for every soul
 packages:
   oats.okf: v4.0.5
-  oats.aweb: v1.17.3
+  oats.aweb: v1.17.5
   oats.linear: v1.0.1
   oats.jira: v1.0.1
 defaults: