@awebai/oats 0.31.0 → 0.32.0

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"],
  "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,7 @@ 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)) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -181,6 +182,83 @@ 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
+```
+
+- **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.
+- **`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, 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, 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 +292,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:
@@ -597,7 +675,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 +724,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 +913,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 +952,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
@@ -1135,6 +1214,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
@@ -1346,10 +1431,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 +1898,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/implementation.md

@@ -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` |
@@ -62,6 +63,63 @@ 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, killed through `process-group.mjs` on timeout and at close);
+- 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.
+
+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/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/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/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; }
 }