@awebai/oats 0.33.0 → 0.34.1

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`
@@ -389,7 +391,7 @@ async function workspaceTarget(bail, { command, liveTeams = true }) {
     try { meta = JSON.parse(readFileSync(join(homeFlag, "instance.json"), "utf8")); } catch (e) { return bail("E_SESSION_UNKNOWN", `${homeFlag} is not an OATS instance home (${e.code === "ENOENT" ? "no instance.json" : e.message})`); }
     if (isCapturedHome(meta)) { const e = capturedHomeRefusal(homeFlag, "nothing was read"); return bail(e.code, e.message, e.details); }
     if (!meta || typeof meta.modules !== "object" || meta.modules === null) return bail("E_UNSUPPORTED_MODE", `${homeFlag} is not a workspace-model home (it records no modules): it was spawned by an earlier kernel — re-spawn it from the deployment`);
-    if (soulFlag && soulFlag !== meta.agent) return bail("E_HOME_MISMATCH", `--soul ${soulFlag} is not the soul of ${homeFlag} (${meta.agent})`);
+    if (soulFlag && !(await import("../lib/instance-resolution.mjs")).homeSoulMatches(soulFlag, meta)) return bail("E_HOME_MISMATCH", `--soul ${soulFlag} is not the soul of ${homeFlag} (${meta.agent})`);
     const deployment = dirname(dirname(dirname(dirname(realOrResolved(homeFlag)))));
     // A v2 home lives at <deployment>/agents/<soul>/instances/<name>: its deployment is
     // derived, so it must hold oats-local.yaml EXACTLY there (never found by walking up).
@@ -535,8 +537,9 @@ async function workspaceOperation(t, { bail, address, layer, opName }) {
   const settings = lp.settings;
   const cwd = op.context === "home" ? t.home : t.deployment;
   const env = { ...lp.env(mod.name, settings), OATS_OPERATION: address, OATS_CONTEXT: t.deployment, OATS_ROOT: t.agentsRoot, PI_AGENTS_ROOT: t.agentsRoot };
-  if (op.context === "home") Object.assign(env, { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home, OATS_HOME: t.home, PI_AGENT_INSTANCE: t.meta.instance, PI_AGENT_HOME: t.home });
-  else for (const k of ["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]) delete env[k];
+  // The home's identity, never one inherited from the caller (the reserved PI_AGENT_* names included).
+  for (const k of ["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]) delete env[k];
+  if (op.context === "home") Object.assign(env, { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home, OATS_HOME: t.home });
   await readSession?.closeBatches(); // no idle `git cat-file --batch` child held for the provider's whole run
   const r = spawnSync("node", [abs, ...rest, ...argFlags, "--json"], { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 16 * 1024 * 1024, timeout: OPERATION_TIMEOUT_MS, killSignal: "SIGTERM" });
   finishOperation({ r, bail, address, provider, op, argFlags, cwd, home: t.home, meta: t.meta, api: INSPECT_OPERATIONS_API });
@@ -1027,9 +1030,13 @@ 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 });
+    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();
@@ -1046,7 +1053,7 @@ function sayReadNotices() {
 }
 /** 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, spawn --preview, 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})`;
@@ -1645,14 +1652,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);
@@ -1667,6 +1685,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. */
@@ -2239,8 +2325,8 @@ function retireCmd() {
   }
   // The calling instance knows its own home: self-retire never needs to
   // disambiguate a same-named twin by hand.
-  if (homeFlag === undefined && process.env.OATS_INSTANCE_HOME && (process.env.PI_AGENT_INSTANCE === name || process.env.OATS_INSTANCE === name)) homeFlag = process.env.OATS_INSTANCE_HOME;
-  const isSelf = process.env.PI_AGENT_INSTANCE === name || process.env.OATS_INSTANCE === name;
+  if (homeFlag === undefined && process.env.OATS_INSTANCE_HOME && process.env.OATS_INSTANCE === name) homeFlag = process.env.OATS_INSTANCE_HOME;
+  const isSelf = process.env.OATS_INSTANCE === name;
   if (isSelf && !args.includes("--self")) die(`"${name}" is the calling instance — self-retire is irreversible; if your task is complete and you were told to retire, re-run with --self (finish your memory files FIRST; your session dies ~8s after)`);
   if (!isSelf && args.includes("--self")) die(`--self given but "${name}" is not the calling instance`);
   const root = ensureRoot(dirFlag());
@@ -2766,9 +2852,12 @@ 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. 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());
+    // OATS_INSTANCE_HOME is the identity; OATS_HOME still counts. With neither set (a harness that
+    // strips the session env), the home enclosing the cwd. What chose the home is named in every
+    // refusal about it.
+    const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
+    const instanceHome = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
+    const chosenBy = homeVariable ?? "the working directory";
     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
@@ -2787,11 +2876,19 @@ async function capabilityCommand() {
         if (!isWorkspaceHome(meta)) { const e = preWorkspaceHome(instanceHome, "nothing was dispatched"); bail(e.code, e.message); }
         context = meta.repo || context;
         soulDir = instanceSoulDir(instanceHome, meta);
+        const ws = meta.workspace && typeof meta.workspace === "object" ? meta.workspace : {};
+        // Inside a home the namespace is the home's, so a --soul for another soul is refused, never
+        // ignored (as inspect's --soul against --home is). The home's own soul, by any of its names, is fine.
+        const soulFlag = flag("soul");
+        if (soulFlag === true) bail("E_BAD_ARGS", "--soul needs a soul name", { flag: "--soul" });
+        if (typeof soulFlag === "string" && !(await import("../lib/instance-resolution.mjs")).homeSoulMatches(soulFlag, meta)) {
+          bail("E_HOME_MISMATCH", `--soul ${soulFlag} is not the soul of the instance home ${instanceHome} (${meta.agent}), which ${chosenBy} chose; to run "${cmd}" as a spawn of ${soulFlag} would, run it outside the instance home with OATS_INSTANCE_HOME and OATS_HOME unset`,
+            { home: instanceHome, soul: meta.agent, chosenBy, flag: "--soul" });
+        }
         // The team/workspace facts the home recorded at spawn, as its hooks got them, with the
         // recorded eligible teams (OATS_TEAMS_SOURCE=recorded). Only the home's MESSAGING module
         // gets them live (below): its team verbs (join/leave/teams) must see what the workspace
         // allows now, and no other command pays a remote read for them.
-        const ws = meta.workspace && typeof meta.workspace === "object" ? meta.workspace : {};
         const messaging = (meta.capabilities || []).find((c) => c.layer === "messaging")?.id;
         homeMeta = { meta, messaging };
         homeTeamCtx = (t) => teamEnv({ workspace: { key: ws.key, name: ws.name, deployment: ws.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.source });
@@ -2809,7 +2906,7 @@ async function capabilityCommand() {
     // Workspace model: an instance's own materialized modules are the command
     // namespaces available to it (instance.json.modules → <home>/.oats/modules).
     const mans = Object.values(capabilityManifests(instanceHome)).filter((m) => m.command === cmd && m.commands);
-    if (!mans.length) return NOT_DISPATCHED;
+    if (!mans.length) bail("E_UNKNOWN_COMMAND", `oats ${cmd}: no capability of the instance home ${instanceHome} (soul ${homeMeta.meta.agent}), which ${chosenBy} chose, provides "${cmd}"`, { home: instanceHome, chosenBy, namespace: cmd });
     if (mans.length > 1) bail("E_DUPLICATE_NAMESPACE", `duplicate operational command namespace "${cmd}": ${mans.map((m) => m.capability).join(", ")}`);
     const m = mans[0];
     if (!activeIds.includes(m.capability)) bail("E_CAPABILITY_INACTIVE", `${m.capability} command namespace is not active in the current context/instance`);
@@ -2946,7 +3043,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", "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 }));
+    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)`);
@@ -3349,6 +3446,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")) {
@@ -3606,6 +3707,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

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

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","spawn-preview-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
@@ -97,6 +98,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `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
@@ -196,6 +198,7 @@ it and answer live, without the block.
 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.
@@ -253,8 +256,8 @@ oats spawn <soul> … --preview --max-age <seconds> --json    (feature spawn-pre
   invocation refuse the flag before reading or writing anything, with
   `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
   verbs reuse observations (status, workspace status, souls, capabilities,
-  inspect --soul|--home, spawn --preview, and the read forms of teams and soul
-  teams)" and,
+  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
@@ -734,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}`.
@@ -810,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
 

package/docs/execution-targets.md

@@ -27,9 +27,9 @@ named launch configuration (`--launch-config <name>`); see
 [configuration.md](configuration.md#launch-configurations).
 `--model @native-default` uses the harness's own default model.
 
-The launch command sets `OATS_INSTANCE`, `OATS_INSTANCE_HOME`,
-`PI_AGENT_INSTANCE` and `PI_AGENT_HOME`, plus the environment that the launch
-configuration and capabilities contribute. The home's layout and what those
+The launch command sets `OATS_INSTANCE` and `OATS_INSTANCE_HOME`, plus the
+environment that the launch configuration and capabilities contribute. No
+`PI_AGENT_*` name is set, for any harness. The home's layout and what those
 variables point at are described in
 [souls-and-instances.md](souls-and-instances.md#instance-anatomy).
 

package/docs/implementation.md

@@ -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` |
@@ -71,6 +72,27 @@ Every CLI command owns one read session (`createReadSession` in
 CLI closes it when the command ends). A library caller without a session
 gets the plain per-call behaviour. Within a session:
 
+- a HEAD observation speaks protocol v0 when the operator has not pinned
+  `protocol.version` (`git config --get`, read once per command): the whole
+  ref advertisement in one round trip, resolved exactly as v2's filtered
+  answer. `V0_ADVERTISEMENT_BUDGET` (4 MiB, git's `maxBuffer`) bounds what
+  is kept, not the transfer: git reads the whole advertisement before it
+  prints a ref, so a remote over budget costs its advertisement once, then
+  git is killed, the remote observed again under v2 and recorded. A v0
+  timeout stays today's error (no retry) and is recorded too, unless the
+  session's `deadline` cut that read's timeout (the deadline, not the remote,
+  may have ended it). The
+  v0 read and its `protocol.version` check go through `sessionExec` like every
+  other git call. The record is
+  `<cacheRoot>/.ls-remote/<sha256(key)>.<reason>.json`, `{ protocol: "v2",
+  reason: "overflow" | "timeout", recordedAt }`, one file per reason (an
+  in-flight timeout never replaces an overflow), written atomically with no lock;
+  `overflow` is permanent, `timeout` expires after 7 days, and an unreadable,
+  corrupt or expired record is no record (v0 is tried). Another v0 failure
+  that is not final (auth, not-found, cache, an abort) is retried once under
+  v2. Each is a session notice. The v2 argv (`lsRemoteArgs`) stays the
+  observation's identity: records and memo keys do not depend on the
+  protocol;
 - a head is observed once per (cache repo, ref), and a commit peeled once; at
   most eight observations run at once (`OBSERVE_LIMIT`), each holding its slot
   for all its git work (the `ls-remote` and the fetch of the commit it names,
@@ -104,6 +126,20 @@ gets the plain per-call behaviour. Within a session:
   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` is a test and ops override,
+  not a contract). 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

package/docs/knowledge.md

@@ -220,8 +220,10 @@ identical copies in both role capabilities.
 - **From an instance home**, `oats okf …` runs the home's copy of the module
   with the settings recorded at spawn.
 - **From the deployment directory** (holding `oats-local.yaml`), in a shell
-  without another instance's `OATS_*` identity, every capability command
-  needs `--soul <name>` (`E_BAD_ARGS` without it). The kernel resolves the
+  where neither `OATS_INSTANCE_HOME` nor `OATS_HOME` is set (either one pins
+  the command to that instance home), every capability command needs
+  `--soul <name>` (`E_BAD_ARGS` without it). Inside an instance home, a
+  `--soul` naming another soul is refused (`E_HOME_MISMATCH`). The kernel resolves the
   soul as a spawn would, fetches its module at the locked commit into
   `<deployment>/.oats/modules/` and runs it with the soul's merged settings.
   An unlocked package is `E_PACKAGE_MISSING` until `oats sync`.

package/docs/official-catalog.md

@@ -12,7 +12,7 @@ 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.5` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.4.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.engineering` | `v1.5.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) | |