@awebai/oats 0.32.0 → 0.33.0

package/README.md

@@ -208,7 +208,7 @@ Begin with a small team and a real piece of work:
 4. Create instances for their assignments.
 5. Verify that work, communication, learning and handoff behave as intended.
 
-On a machine with Node.js 22+, Git and tmux, and a workspace repository to point at:
+On a machine with Node.js 22+, Git (2.45+ to fetch only what OATS reads; an older git fetches whole trees) and tmux, and a workspace repository to point at:
 
 ```bash
 npm install -g @awebai/oats

package/bin/oats.mjs

@@ -28,7 +28,7 @@ import {
   LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
-  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
   writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
@@ -789,7 +789,7 @@ function launchPreview(bail) {
   let plan;
   try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
   const { recipe } = plan;
-  const command = renderLaunchRecipe(recipe, { home, instance, redact: true });
+  const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
   const d = describeLaunchCommand(command);
   const environment = d.environment.map((e) => e.reference && recipe.env[e.name]?.fromEnv ? { name: e.name, fromEnv: recipe.env[e.name].fromEnv } : e);
   jsonOk({ context, selected, selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
@@ -1030,7 +1030,7 @@ let maxAgeGiven = null;
 function commandSession() {
   if (!readSession) {
     readSession = remoteModule.createReadSession({ maxAge: maxAgeGiven ?? 0 });
-    process.on("exit", () => readSession.closeNow());
+    process.on("exit", () => { sayReadNotices(); readSession.closeNow(); });
     for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
       readSession.closeNow();
       // Another handler (a scheduler lock's release) exits on its own after this one.
@@ -1039,15 +1039,22 @@ function commandSession() {
   }
   return readSession;
 }
+/** What the read session found worth telling the operator (a remote that cannot serve partial fetches),
+ *  once, on stderr when the command ends: stdout, and so every JSON answer, is unchanged. */
+function sayReadNotices() {
+  for (const notice of readSession?.notices.splice(0) ?? []) process.stderr.write(`oats: warning: ${notice}\n`);
+}
 /** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
  *  → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`. */
-const MAX_AGE_READS = "status, workspace status, souls, capabilities, inspect --soul|--home, and the read forms of teams and soul teams";
+const MAX_AGE_READS = "status, workspace status, souls, capabilities, inspect --soul|--home, spawn --preview, and the read forms of teams and soul teams";
 function maxAgeRefusal(command, head) {
   const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
   const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
   if (head.includes("--server")) return "--max-age cannot be combined with --server: observation reuse is local to this machine";
   switch (command) {
     case "status": case "souls": case "capabilities": case "inspect": return null;
+    // A preview reads (feature spawn-preview-max-age); an apply always observes live.
+    case "spawn": return head.includes("--preview") ? null : refuse("spawn");
     case "workspace": return word(1) === "status" ? null : refuse(["workspace", word(1)].filter(Boolean).join(" "));
     case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
     case "soul": {
@@ -1884,8 +1891,9 @@ async function status() {
 const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
 /** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
  *  `--instance` is refused by a local spawn (with its replacement) but still travels to an older
- *  host through `--server`, whose route reads it. */
-const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
+ *  host through `--server`, whose route reads it. `--max-age` reaches here only on a preview: the
+ *  dispatch allow-list (maxAgeRefusal) refuses it on an apply. */
+const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
 const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
 /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
  *  soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
@@ -2141,7 +2149,7 @@ async function spawnCmd() {
       // A workspace preview may have fetched the soul's SOURCE to a temporary copy
       // (the deployment's cache had no entry for its commit): the result says so.
       if (prepared) r.soulFetched = soulFetched;
-      if (JSON_MODE) { jsonOk(r); return; }
+      if (JSON_MODE) { jsonOk(withObservation(r)); return; }
       console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) harness ${r.harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (this machine's ${r.harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
       return;
     }
@@ -2758,8 +2766,9 @@ async function capabilityCommand() {
     let activeIds;
     let context = process.cwd();
     let teamCtx, homeMeta, homeTeamCtx;
-    // OATS_INSTANCE_HOME is the canonical identity; the older names still count.
-    const instanceHome = process.env.OATS_INSTANCE_HOME || process.env.PI_AGENT_HOME || process.env.OATS_HOME;
+    // OATS_INSTANCE_HOME is the canonical identity; the older names still count. With none set
+    // (a harness that strips the session env), the home enclosing the cwd.
+    const instanceHome = process.env.OATS_INSTANCE_HOME || process.env.PI_AGENT_HOME || process.env.OATS_HOME || enclosingInstanceHome(logicalCwd());
     const metaFile = instanceHome && join(instanceHome, "instance.json");
     // Capability-id keyed — never answer for `constructor`/`toString`. Belt and
     // braces: the ids come from instance.json, which spawn wrote from resolved
@@ -2937,7 +2946,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "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", "launch-config-default"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "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", "spawn-preview-max-age", "launch-config-default"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3543,6 +3552,9 @@ Usage:
       [--provider <capability> <key>=<value>]  a provider setting for this spawn only
                                             (repeatable; dotted keys nest; recorded in
                                             instance.json providers.<capability>)
+      [--preview [--max-age <s>]]           decide everything, create nothing; the JSON's
+                                            decision binds an apply (--expect-decision <rev>);
+                                            --max-age reuses recent heads (preview only)
   oats retire <instance> [--force]           retire an instance (window, hooks,
       [--self] [--delete-branch]            worktree, home); --self = retire the
       [--keep-dir] [--json]                 CALLING instance: the window dies, then
@@ -3660,15 +3672,17 @@ The turn record (core — every conversation captured, searchable, replicated):
 
 Observation reuse (feature observe-max-age):
   --max-age <seconds>                        on the read verbs only — status, workspace status,
-                                            souls, capabilities, inspect --soul|--home, and the
-                                            read forms of teams and soul teams — reuse a remote
-                                            head observation up to <seconds> old (0–86400; 0 is
-                                            live) instead of asking the remote again; the JSON
+                                            souls, capabilities, inspect --soul|--home,
+                                            spawn --preview (feature spawn-preview-max-age),
+                                            and the read forms of teams and soul teams —
+                                            reuse a remote head observation up to <seconds>
+                                            old (0–86400; 0 is live) instead of asking the
+                                            remote again; the JSON
                                             then carries observation { observedAt (the oldest
                                             head used), reused, localRevision (a digest of
                                             the local configuration read) }. Refused
                                             (E_BAD_ARGS) by every other command, an edit form,
-                                            and with --server
+                                            a spawn apply, and with --server
 
 Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
 }
@@ -3681,5 +3695,6 @@ Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspa
   die(e.message);
 } finally {
   // The command's read session: every `git cat-file --batch` child ends before the process does.
+  sayReadNotices();
   if (readSession) await readSession.close();
 }

package/docs/capabilities.md

@@ -355,6 +355,11 @@ for this contract. Hyphenated vendors are also excluded because translating a
 hyphen to `_` would let `aweb-evil.*` collide with names already inside
 `aweb.*`'s `AWEB_*` namespace.
 
+Hook environment values must not be secrets. A codex launch also passes them
+to Codex as command-line arguments (`-c shell_environment_policy.set.<NAME>=…`,
+so its tool commands see them), and any local user can read those. A secret
+reaches a launch through a launch configuration's environment reference.
+
 A manifest's `settings.<key>` may carry `hostOnly: true`. Such a
 key is a fact about the machine — a custody directory, a state root — and the
 resolver accepts it only from the deployment's own `oats-local.yaml`

package/docs/configuration.md

@@ -330,6 +330,6 @@ 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`, and the read forms of `teams` and `soul teams`)
-take `--max-age <seconds>` to reuse a remote head observed that recently
+`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","observe-max-age"],
+             "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}
 ```
@@ -96,6 +96,7 @@ 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)) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -194,6 +195,7 @@ 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.
@@ -206,7 +208,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 +247,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,
+  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 +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
@@ -1162,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
@@ -1250,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,

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) |
@@ -58,6 +58,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 +94,29 @@ 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;
+- 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 +125,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
 ```