@awebai/oats 0.32.0 → 0.34.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

@@ -10,6 +10,8 @@
  *   oats package add|remove ...            edit `packages:` in the workspace file
  *   oats workspace status                  membership table, packages
  *   oats capabilities | oats souls         every visible item of the workspace
+ *   oats capabilities show <name> [--member <repoKey> | --package <id>] [--file <path>] [--json]
+ *                                          what one capability ships (inject text, skill files)
  *
  * Workspace model v2 (docs/design/2026-09-23-workspace-module-contracts.md §6):
  * nothing is installed. `oats-local.yaml` names the workspace, `oats sync`
@@ -28,7 +30,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 +791,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 });
@@ -1027,10 +1029,14 @@ async function readinessCmd() {
 let readSession = null;
 /** The validated `--max-age` seconds (checked once at dispatch: maxAgeRefusal), null when not given. */
 let maxAgeGiven = null;
+/** The remote budget of this command's reads (ms), or null: only the deployment reads `status` and `workspace
+ *  status` have one (remote.mjs READ_REMOTE_BUDGET_MS; OATS_READ_REMOTE_BUDGET_MS overrides it), so they answer
+ *  inside a caller's own limit. Spawn, sync and every other verb read with no deadline. */
+let readBudgetMs = null;
 function commandSession() {
   if (!readSession) {
-    readSession = remoteModule.createReadSession({ maxAge: maxAgeGiven ?? 0 });
-    process.on("exit", () => readSession.closeNow());
+    readSession = remoteModule.createReadSession({ maxAge: maxAgeGiven ?? 0, ...(readBudgetMs !== null ? { deadline: Date.now() + readBudgetMs } : {}) });
+    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 +1045,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, capabilities show, 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": {
@@ -1638,14 +1651,25 @@ async function soulCmd() {
   if (doc.teams.length) printTable(["team", "id", "from", "why"], doc.teams.map((t) => [t.default ? `${t.label} (default)` : t.label, t.team ?? "(no id yet)", t.from, t.via.join(",")]));
 }
 
-/** `oats capabilities` / `oats souls` [--dir] [--json] — contract §6. */
-async function itemsCmd(kind) {
-  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+/** The catalog's rows of `kind` ("capabilities" | "souls") as `oats capabilities` / `oats souls` list them:
+ *  one discovery (honouring --max-age), the lock, workspaceItems. → { ctx, discovery, lock, items }. */
+async function catalogRows(kind, bail) {
   const ctx = workspaceContext(bail);
   const discovery = await discoverForCli(ctx, bail);
   let lock;
   try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
-  const items = workspaceItems(discovery, lock, ctx.local, ctx.deploymentDir)[kind];
+  return { ctx, discovery, lock, items: workspaceItems(discovery, lock, ctx.local, ctx.deploymentDir)[kind] };
+}
+
+/** `oats capabilities` / `oats souls` [--dir] [--json] — contract §6. */
+async function itemsCmd(kind) {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  if (kind === "capabilities") {
+    const { words } = capabilitiesArgv();
+    if (words[0] === "show") return capabilityShowCmd(bail);
+    if (words.length) return bail("E_BAD_ARGS", `unknown capabilities subcommand ${JSON.stringify(words[0])}: \`oats capabilities\` lists the catalog, \`oats capabilities show <name>\` reads one capability`, { subcommand: words[0] });
+  }
+  const { ctx, discovery, lock, items } = await catalogRows(kind, bail);
   // One command's reads at a commit are shared: many souls resolve over the same manifests and listings.
   const remote = memoizedRemote(remoteModule);
   if (kind === "capabilities") await capabilityFacts(items, discovery, lock, ctx, remote);
@@ -1660,6 +1684,74 @@ async function itemsCmd(kind) {
   if (kind === "capabilities" && unsynced.length) console.log(`\n  package capabilities of ${unsynced.join(", ")} appear after \`oats sync\``);
 }
 
+/** `oats capabilities` argv after the command: its words (the subcommand first) with every flag and a value
+ *  flag's value set aside, and the first flag neither form takes (`unknown`). */
+function capabilitiesArgv() {
+  const VALUE_FLAGS = new Set(["--member", "--package", "--file", "--dir", "--max-age", "--server"]);
+  const words = [];
+  let unknown;
+  for (let i = 1; i < args.length; i++) {
+    if (VALUE_FLAGS.has(args[i])) { if (args[i + 1] !== undefined && !args[i + 1].startsWith("--")) i++; continue; }
+    if (args[i].startsWith("--")) { if (args[i] !== "--json") unknown ??= args[i]; continue; }
+    words.push(args[i]);
+  }
+  return { words, unknown };
+}
+
+/** `oats capabilities show <name> [--member <repoKey> | --package <id>] [--file <path>] [--dir] [--json]`
+ *  (feature capability-show, capabilityShowApi 1; lib/capability-show.mjs): what one catalog row ships, read
+ *  at that row's commit — the rows are `oats capabilities`'s own (catalogRows). */
+async function capabilityShowCmd(bail) {
+  const S = await import("../lib/capability-show.mjs");
+  if (flag("server") !== undefined) return bail("E_BAD_ARGS", "oats capabilities show reads this machine's workspace only: --server is not accepted");
+  const { words, unknown } = capabilitiesArgv();
+  if (unknown) return bail("E_BAD_ARGS", `oats capabilities show: unknown flag ${unknown}`, { flag: unknown });
+  const positionals = words.slice(1);
+  if (positionals.length !== 1) return bail("E_BAD_ARGS", positionals.length ? `oats capabilities show takes one capability name, got ${positionals.map((p) => JSON.stringify(p)).join(" ")}` : "oats capabilities show needs a capability name (`oats capabilities` lists them)");
+  const name = positionals[0];
+  const memberArg = valueFlag("member"), packageArg = valueFlag("package"), file = valueFlag("file");
+  if (memberArg !== undefined && packageArg !== undefined) return bail("E_BAD_ARGS", "choose --member <repoKey> or --package <id>, not both");
+  if (file !== undefined && S.unsafeFilePath(file)) return bail("E_CAPABILITY_FILE_UNSAFE", `${JSON.stringify(file)} is not a relative path inside the capability`, { path: file });
+  const { ctx, discovery, lock, items } = await catalogRows("capabilities", bail);
+  // --member takes the repo key a row shows, or any ref spelling of it (compared on the canonical key).
+  let member = memberArg ?? null;
+  if (member !== null && !items.some((r) => r.repoKey === member)) { try { member = remoteModule.parseRepoRef(member).key; } catch { /* matches no row */ } }
+  const remote = memoizedRemote(remoteModule);
+  const catalog = (() => { try { return officialPackageCatalog(); } catch { return null; } })();
+  let doc;
+  try {
+    const row = S.selectCapabilityRow(items, name, { member, package: packageArg ?? null });
+    const source = await S.capabilitySource(row, { discovery, lock, catalog, remote, remoteOptions: ctx.remoteOptions });
+    doc = file === undefined ? await S.capabilityShow(source, { remote, remoteOptions: ctx.remoteOptions }) : await S.capabilityFile(source, file, { remote, remoteOptions: ctx.remoteOptions });
+  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance); throw e; }
+  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
+  if (file !== undefined) {
+    const f = doc.file;
+    if (f.binary) console.log(`(${f.path}: binary, ${formatBytes(f.bytes)} — not shown)`);
+    else {
+      process.stdout.write(f.text.endsWith("\n") || f.text === "" ? f.text : `${f.text}\n`);
+      if (f.truncated) console.log(`(${f.path}: truncated — ${formatBytes(f.bytes)}, the first ${formatBytes(S.TEXT_LIMIT)} shown)`);
+    }
+    return;
+  }
+  console.log(`${doc.name} — ${doc.kind === "member" ? `member ${doc.repoKey}` : `package ${doc.package} v${doc.version} (${doc.repoKey})`} @ ${short(doc.commit)}, ${doc.path}\n`);
+  const size = (bytes) => (bytes === null ? "unreadable" : formatBytes(bytes));
+  console.log(`  inject: ${doc.inject ? `${doc.inject.path ?? "(unsafe path)"} (${size(doc.inject.bytes)}${doc.inject.binary ? ", binary" : ""}${doc.inject.truncated ? ", truncated" : ""})` : "(none)"}`);
+  if (doc.skills === null) console.log("  skills: (cannot be listed — see problems)");
+  else if (!doc.skills.length) console.log("  skills: (none)");
+  else {
+    console.log("  skills:");
+    for (const skill of doc.skills) {
+      console.log(`    ${skill.name}  ${skill.path}`);
+      if (skill.files === null) console.log("      (files cannot be listed — see problems)");
+      for (const f of skill.files ?? []) console.log(`      ${f.path}  ${size(f.bytes)}`);
+      if (skill.filesTruncated) console.log(`      … more files (the first ${S.FILES_PER_SKILL} are listed)`);
+    }
+  }
+  for (const p of doc.problems) console.log(`  problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
+  console.log(`\n  a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
+}
+
 /** Capability rows' manifest facts (feature desktop-facts): layer, description, and what each provides
  *  (skills, commands, hooks by name) — member rows from discovery's manifest, package rows from the manifest
  *  at the locked commit (the sync cache; no network beyond sync's). An unreadable package leaves its rows' facts null. */
@@ -1884,8 +1976,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 +2234,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 +2851,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 +3031,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", "capability-show"], 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, capabilityShowApi: 1 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3340,6 +3434,10 @@ try {
     maxAgeGiven = Number(raw);
     activateLocalInputs(); // observation.localRevision: every local config read from here on is recorded
   }
+  if (kernelArgv && !head.includes("--server") && (cmd === "status" || (cmd === "workspace" && head[1] === "status"))) {
+    const override = Number(process.env.OATS_READ_REMOTE_BUDGET_MS);
+    readBudgetMs = Number.isSafeInteger(override) && override > 0 ? override : remoteModule.READ_REMOTE_BUDGET_MS;
+  }
   const inherited = ["OATS_RESOLUTION", "OATS_DEPLOYMENT"].filter((k) => process.env[k]);
   if (inherited.length && cmd !== "version") refuse(`this environment carries a captured context (${inherited.join(", ")}): the captured/portable path was removed in 0.26, and nothing is run against the current context in its place — retire the captured home and re-spawn it from the deployment`, { inherited });
   if (cmd === "inspect" && head.includes("--request")) {
@@ -3543,6 +3641,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
@@ -3594,6 +3695,10 @@ Usage:
   oats capabilities [--dir <d>] [--json]     every capability of every confirmed member (a
       [--max-age <s>]                       private one is listed as repo-owned: usable only by
                                             its own repo's souls) + the locked packages
+  oats capabilities show <name> [--member <repoKey> | --package <id>] [--file <path>]
+      [--dir <d>] [--json] [--max-age <s>]  what one capability of that list ships, at its commit:
+                                            its inject (text) and each skill's files (sizes);
+                                            --file <path>: one listed file's text
   oats souls [--dir <d>] [--json]            every soul of every confirmed member + external souls
       [--max-age <s>]                       (souls have no private mode), with origin
                                             (member <key> @ <commit> | package <id> v<ver>) and its
@@ -3660,15 +3765,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 +3788,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

@@ -246,6 +246,23 @@ discovery; the details are in [souls-and-instances.md](souls-and-instances.md).
 Change a capability's inject or skills in its repository, then spawn a new
 instance: the generated files are not a source.
 
+See what a capability ships before any instance has it:
+
+```bash
+oats capabilities show oats.okf                          # inject path and size, each skill's files, problems
+oats capabilities show oats.okf --file injects/okf.md    # one listed file's text
+oats capabilities show nw-house-style --member github.com/nw/agents --json
+```
+
+`oats capabilities show <name>` reads one row of `oats capabilities` at that
+row's commit (a package at its locked commit, after spawn's lock check): the
+inject text exactly as committed, and each skill, enumerated as a spawn
+enumerates it, with its description and files. `--file <path>` prints one
+file the show lists (the inject or a skill file), and no other file of the
+capability. Use `--member <repoKey>` or `--package <id>` when two rows share
+the name. The JSON contract is in
+[desktop-cli-api.md](desktop-cli-api.md#oats-capabilities-show).
+
 Inspect a composition before it exists:
 
 ```bash
@@ -355,6 +372,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`,