@awebai/oats 0.32.0 → 0.34.0

package/docs/desktop-cli-api.md

@@ -38,9 +38,10 @@ 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","observe-max-age"],
+             "preview-composed-from","observe-max-age","spawn-preview-max-age","capability-show"],
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
- "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2}
+ "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
+ "capabilityShowApi":1}
 ```
 
 - The Desktop accepts `desktopApi === 1` and a released `version` inside
@@ -96,6 +97,8 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `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)) | |
+| `capability-show` | `oats capabilities show <name>` and its `--file` form, OATS 0.34.0 ([`oats capabilities show`](#oats-capabilities-show)) | `capabilityShowApi: 1` |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -194,6 +197,8 @@ 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)
+oats capabilities show <name> … --max-age <seconds> --json  (feature capability-show)
 ```
 
 - **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
@@ -206,7 +211,15 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
   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.
+  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
@@ -237,12 +250,14 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
   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`,
+- **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, and the read forms of teams and soul teams)" and,
+  capabilities show, 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
@@ -523,7 +538,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
@@ -704,6 +737,14 @@ Read-only (it writes no lock):
 ```
 
 - `members[]` and `packages[]` are the sync rows (packages from the lock).
+- **Remote budget (0.33.1).** `oats workspace status` and `oats status` finish
+  their remote work within 12 s of their first remote read, whatever the
+  machine's load or another process holding a remote's cache. A member not
+  read by then is a `cannot-read` row whose `detail` ends `(timeout)`, and its
+  git is ended; the command still answers. The workspace definition itself
+  (the host) not read by then fails the command as any unreadable host does
+  (`E_REMOTE_UNREADABLE`, `reason: "timeout"`). Spawn, sync and every other
+  verb have no such budget.
 - `declaredPackages`: the ids in `packages:` (standalone: the kernel's
   default). `unsynced`: declared, not locked. `stale`: locked, no longer
   declared. `external[]`: `{source, soul}`.
@@ -780,6 +821,175 @@ problem`, and (feature `launch-preference`) `key` and `launch`.
 This document keeps `soulsApi: 1`; the probe's `soulsApi: 2` is the inspect
 soul row's.
 
+### `oats capabilities show`
+
+Feature `capability-show`, `capabilityShowApi: 1`, OATS 0.34.0.
+
+```text
+oats capabilities show <name> [--member <repoKey> | --package <id>] [--dir <d>] [--max-age <s>] --json
+oats capabilities show <name> [--member <repoKey> | --package <id>] --file <path> [--dir <d>] [--max-age <s>] --json
+```
+
+What one capability ships: its inject text and each skill's files, and one
+file's text on request. The Desktop's capability page shows them without
+reading clones or caches itself.
+
+> **Every `text` and `description` is untrusted repository content.** Render
+> it as plain text (`textContent`), or through a sanitising Markdown renderer
+> that allows no raw HTML, no scripts and no remote images.
+
+**Selection.** The rows are exactly the rows of `oats capabilities --json`
+(one discovery, honouring `--max-age`), so the answer's `commit` equals that
+row's `commit`.
+
+- `<name>` alone selects the one row with that name.
+- `--member <repoKey>` selects a member row of that repository: the key as a
+  row shows it, or any ref spelling of the same repository.
+- `--package <id>` selects that package's row.
+- No row: `E_CAPABILITY_UNKNOWN`, `details: {name}` plus `member` or
+  `package` when one was given. An unsynced package is not in the catalog, so
+  its capabilities are `E_CAPABILITY_UNKNOWN` until `oats sync`.
+- More than one row: `E_CAPABILITY_AMBIGUOUS`, `details: {name, candidates}`,
+  each candidate `{kind, repoKey, origin}` (member) or `{kind, package,
+  origin}` (package). Choose one with `--member` or `--package`.
+- `E_BAD_ARGS` for `--member` with `--package`, a missing or second name, an
+  unknown flag, and `--server` (the verb reads this machine's workspace only).
+  An unknown word after `oats capabilities` (`oats capabilities foo`) is
+  `E_BAD_ARGS` too.
+
+**Trust path.** Every read goes through the remote cache at a full commit id;
+nothing reads a working clone.
+
+- A member capability is read from its member repository at the row's commit.
+- A package capability is read at the locked commit, the same trust path
+  spawn uses. First comes spawn's lock check: when the package manifest at
+  that commit does not list the capability, or its capability list differs
+  from the lock's, the show refuses `E_PACKAGE_INTEGRITY` with spawn's
+  details. The full-tree content digest is not recomputed per show: `oats
+  sync` proved the lock's integrity over the tree of exactly that commit, and
+  the commit id content-addresses the tree.
+
+**The show:**
+
+```json
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.0.5",
+ "commit":"26d8216f…","path":"oats-package/capabilities/oats-okf",
+ "inject":{"path":"injects/okf.md","bytes":2422,"text":"## Knowledge: OKF\n\nYou have two kinds of knowledge. …","binary":false,"truncated":false},
+ "skills":[{"name":"okf-consultation","path":"skills/okf-consultation","description":"Consulting your soul's knowledge with the `oats okf` CLI: …",
+            "files":[{"path":"skills/okf-consultation/SKILL.md","bytes":6947},{"path":"skills/okf-consultation/references/consult.md","bytes":4465}],
+            "filesTruncated":false},
+           {"name":"okf-instance-knowledge","path":"skills/okf-instance-knowledge","description":"Keeping this instance's own knowledge …",
+            "files":[{"path":"skills/okf-instance-knowledge/SKILL.md","bytes":4787}],"filesTruncated":false}],
+ "problems":[]}
+```
+
+- `kind` is `member` or `package`. `repoKey` is set for both kinds; for a
+  package it is the repository the package is read from. `package` and
+  `version` are the package id and locked version, `null` for a member.
+- `commit` is 40 hex and equals the catalog row's `commit`. `path` is the
+  capability directory, repository-relative.
+- `inject` is `{path, bytes, text, binary, truncated}` or `null`. `skills`
+  is a list of `{name, path, description, files, filesTruncated}`, each file
+  `{path, bytes}`, or `null`. `problems` is a list of `{code, message,
+  path}`.
+- With `--max-age` (`0` included) both the show and the `--file` answer gain
+  the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
+  block `{observedAt, reused, localRevision}`.
+
+**The `--file` answer:**
+
+```json
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"26d8216f…",
+ "file":{"path":"skills/okf-instance-knowledge/SKILL.md","bytes":4787,"text":"---\nname: okf-instance-knowledge\n…","binary":false,"truncated":false}}
+```
+
+**Rules.**
+
+- **Paths.** Every `path` in `inject`, `skills`, `file` and `problems` is
+  POSIX and relative to the capability directory, never the repository.
+  Every non-null `path` is a safe relative path: no `.`, `..` or `.git`
+  component (any case), no empty component, no `\`. A manifest's inject and
+  skill paths are reported as the module install reads them: a `\` is a
+  separator, and a leading `./` and trailing slashes are dropped
+  (`injects\guide.md` is `injects/guide.md`).
+- **The inject** is the committed file exactly: untrimmed and untemplated.
+  (Spawn composes it raw and trimmed, with no settings substitution.)
+  - `inject: null`: the manifest declares no inject.
+  - Declared but unreadable (missing, a symlink, a directory, over the read
+    budget): `inject: {path, bytes: null, text: null, binary: false,
+    truncated: false}` and a `problems[]` entry with the remote's code
+    (`E_REMOTE_PATH_MISSING`, `E_REMOTE_TREE_UNSAFE`, `E_REMOTE_FILE_OVERSIZE`,
+    …). The show still answers ok.
+  - Declared as a path that is not a safe relative path (spawn refuses it):
+    `inject: {path: null, bytes: null, text: null, binary: false, truncated:
+    false}` and a problem with spawn's code (`E_CAPABILITY_MISSING` for a
+    member, `E_PACKAGE_MANIFEST` for a package) and `path: null`. The raw
+    manifest value appears only inside `message`, JSON-quoted. So
+    `inject.path` is `null` only with a problem.
+- **Skills** are in the catalog row's order (by name, in codepoint order),
+  enumerated exactly as a spawn enumerates them. `skills` is `null` exactly
+  when the catalog row's `skills` is `null`, with a problem carrying spawn's
+  code (`E_CAPABILITY_MISSING` or `E_PACKAGE_MANIFEST`) or an `E_REMOTE_*`
+  code, and `path: null`. A skill whose path is not safe (a `.git`
+  directory) makes the skills unlistable the same way, in both answers.
+- **Files.** `files` is every regular file under the skill directory,
+  recursively (no symlinks, no submodules), sorted by path in codepoint order.
+  At most 200 per skill; beyond that `filesTruncated` is `true`. `bytes` is
+  the blob size. When a skill's files cannot be listed (an unsafe entry name
+  in the tree, an unreadable remote), `files` is `null`, `filesTruncated` is
+  `false`, and a problem's `path` is the skill's `path`: "could not list"
+  never collapses into "listed nothing".
+- **`description`** is the `description` key of SKILL.md's leading `---` YAML
+  front matter, when it is a string. It is parsed from the whole SKILL.md,
+  not from its 262144-byte text cut. It is `null` when the front matter is
+  absent or does not parse, the key is absent or not a string, or SKILL.md is
+  unreadable or binary (no problem is reported for it). It is cut to at most
+  1024 UTF-8 bytes on a code point boundary.
+- **Text.** A file is `binary: true, text: null` when it contains a NUL byte
+  or is not valid UTF-8. Only the first 262144 + 3 bytes are examined, so the
+  cut is decided on the same bytes; when the file is longer, a valid sequence
+  they end inside of is not held against it. Otherwise `text` is the content cut to at
+  most 262144 UTF-8 bytes on a code point boundary, with `truncated: true`
+  when cut. A byte order mark is kept in the text. `bytes` is always the real
+  size.
+- **Invariants** (pinned for the Desktop):
+  - `binary: true` ⇒ `text: null` and `truncated: false` (`truncated` is a
+    text-only flag).
+  - `truncated: true` ⇒ `text` is a string and `binary: false`.
+  - `bytes` is `null` only for an unreadable declared inject (with its
+    problem). In a `--file` answer it is always an integer.
+- **Large files.** A file over the read budget (4 MiB) is listed with its
+  size. `--file` refuses it with `E_REMOTE_FILE_OVERSIZE`, passed through
+  unchanged: its `details.path` is repository-relative, not
+  capability-relative.
+
+**`--file <path>`** reads one file the show lists, and nothing else.
+
+- A syntactically unsafe path is `E_CAPABILITY_FILE_UNSAFE`, `details:
+  {path}`, before anything is read: absolute, empty, a `.`, `..` or `.git`
+  component (any case), an empty component, a trailing slash, a `\` or a NUL.
+- Otherwise the path must be the inject's `path` or a path in some skill's
+  `files` as the show lists it (the 200 cap included). Anything else is
+  `E_CAPABILITY_FILE_UNKNOWN`, `details: {path, name}`. No other file of the
+  capability (`oats.json`, scripts, `bin/`) is readable through this verb.
+- A file the show does not list (beyond the 200 cap, a symlink, under a skill
+  whose files cannot be listed) is `E_CAPABILITY_FILE_UNKNOWN` by design:
+  show "not available", not an error.
+- A listed file the remote cannot read answers the remote's own code
+  (`E_REMOTE_FILE_OVERSIZE`, `E_REMOTE_PATH_MISSING`, `E_REMOTE_TREE_UNSAFE`,
+  …).
+
+**Failures.** Every failure is exactly one error envelope on stdout with a
+nonzero exit, as for every command: `E_BAD_ARGS`, `E_CAPABILITY_UNKNOWN`,
+`E_CAPABILITY_AMBIGUOUS`, `E_PACKAGE_INTEGRITY`, `E_CAPABILITY_FILE_UNSAFE`,
+`E_CAPABILITY_FILE_UNKNOWN`, an `E_REMOTE_*` code, and the workspace's own
+(`E_LOCAL_MISSING`, `E_LOCK_SCHEMA`, …).
+
+**Without `--json`** the show prints a short listing for an operator: the
+inject's path and size, each skill with its files and sizes, and the
+problems. `--file` prints the text; a binary file prints a one-line note
+instead, and a truncated file prints its text followed by a one-line note.
+
 <a id="desktop-facts-feature-desktop-facts-oats-0290"></a>
 ### Desktop facts
 
@@ -1162,7 +1372,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
@@ -1250,6 +1460,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,

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) |
@@ -48,6 +48,7 @@ published to npm. Its developer docs are in
 | `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` |
+| `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit |
 | `materialize.mjs` | copying modules into a home and composing it |
 | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata |
 | `instruction-composition.mjs` | the generated `AGENTS.md` |
@@ -58,6 +59,7 @@ 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
@@ -93,7 +95,42 @@ gets the plain per-call behaviour. Within a session:
 - 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);
+  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;
+- a session may have a `deadline` (`READ_REMOTE_BUDGET_MS`, 12 s after it
+  starts): the CLI gives one to `status` and `workspace status` only
+  (`readBudgetMs`; `OATS_READ_REMOTE_BUDGET_MS` overrides it for tests). Every
+  remote step then gets what is left of it instead of its own default: each
+  git call's timeout (`sessionExec`: ls-remote, fetch, ls-tree, the cache's
+  plumbing; none starts once nothing is left), the git version probe
+  (`readVersion`), the batch readers' answers, the cache write lock's wait,
+  the half-initialised cache's wait and the lock-race backoff. What the
+  deadline ends is a `timeout` (a peel or version it ended is never read as a
+  missing commit or an older git), so an unread member degrades as any
+  unreadable one. A cut wait never changes what it judges: past the deadline
+  no lock is taken or reclaimed (live, stale or unreadable), and a cache
+  directory waited for less than in full is not taken for a crash's leftover;
+- 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
@@ -102,6 +139,45 @@ gets the plain per-call behaviour. Within a session:
   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

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:

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
 ```