@awebai/oats 0.33.0 → 0.34.0

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`
@@ -1027,9 +1029,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 +1052,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 +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);
@@ -1667,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. */
@@ -2946,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", "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 +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")) {
@@ -3606,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

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/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` |
@@ -104,6 +105,19 @@ 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` overrides it for tests). Every
+  remote step then gets what is left of it instead of its own default: each
+  git call's timeout (`sessionExec`: ls-remote, fetch, ls-tree, the cache's
+  plumbing; none starts once nothing is left), the git version probe
+  (`readVersion`), the batch readers' answers, the cache write lock's wait,
+  the half-initialised cache's wait and the lock-race backoff. What the
+  deadline ends is a `timeout` (a peel or version it ended is never read as a
+  missing commit or an older git), so an unread member degrades as any
+  unreadable one. A cut wait never changes what it judges: past the deadline
+  no lock is taken or reclaimed (live, stale or unreadable), and a cache
+  directory waited for less than in full is not taken for a crash's leftover;
 - every git child is ended with SIGTERM first and SIGKILL only after a
   grace (`terminateGroup`): git removes its own lock files on SIGTERM, and
   a git killed outright leaves one that blocks every later write. The

package/docs/release-notes/v0.34.0.md

@@ -0,0 +1,63 @@
+# OATS 0.34.0
+
+## Added
+
+- **`oats capabilities show <name>`** (feature `capability-show`,
+  `capabilityShowApi: 1`). It answers what one capability of the catalog
+  ships: its inject text exactly as committed, and each skill, enumerated as
+  a spawn enumerates it, with its SKILL.md description and its files with
+  their sizes. `--file <path>` returns the text of one file the show lists
+  (the inject or a skill file) and refuses any other file of the capability.
+  The rows are `oats capabilities`'s own (`--member <repoKey>` or `--package
+  <id>` picks one when names collide, and `--max-age` is accepted), and the
+  reads take the trust path spawn takes: a member at the row's commit, a
+  package at its locked commit after spawn's lock check (`E_PACKAGE_INTEGRITY`),
+  always through the remote cache, never a working clone. Every text and
+  description is untrusted repository content: render it as plain text or
+  through a sanitising Markdown renderer. The Desktop's capability page reads
+  it ([desktop-cli-api.md](../desktop-cli-api.md#oats-capabilities-show)).
+  `oats capabilities --json` is unchanged; an unknown word after
+  `oats capabilities` is now `E_BAD_ARGS`. A skill path with a `.git`
+  component, which a spawn's fetch refuses, now gives `skills: null` on that
+  catalog row too.
+
+- **The Desktop's capability page shows what a capability ships.** A new
+  *Contents* section, between *Provides* and *Used by*, lists the injected
+  instructions and every skill's files on the left and shows the selected
+  file on the right: Markdown rendered (a SKILL.md's front matter as a small
+  table), other text as highlighted code. A relative link to another listed
+  file opens it in place. The content is untrusted repository text, so no raw
+  HTML, script or image is rendered. The section reads `oats capabilities
+  show` (feature `capability-show`) and needs this release's CLI; with an
+  older one it says so and reads nothing. Remote workspaces show it later
+  ([desktop-file-viewer.md](../../packages/desktop/docs/desktop-file-viewer.md#rendering-rendererviewsmarkdownmjs)).
+  *Provides* above it is now one compact card, with every skill, command and
+  hook as its own chip.
+
+## Changed
+
+- **The Desktop's Instance tab says how an instance works in one sentence.**
+  "Where it works" becomes **Work**: the work mode's tile and a sentence,
+  for example "Works in its own worktree of oats, on branch main." or "Has its
+  own folder, not tied to one repository". Folder and Home move into a closed
+  **Paths** disclosure, each with Copy. The ahead/behind counts stay on the
+  Developer tab. **Messaging & Teams** shows the instance's **Messaging ID**
+  with Copy, then its **Teams**, introduced as the messaging teams its soul is
+  allowed to join.
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.35.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.34.0 together: the
+  Desktop 0.33.x refuses a 0.34 CLI.
+
+## Fixed
+
+- **`oats status` and `oats workspace status` answer within 12 s of remote
+  work, even under load.** Each git call they made had its own 30 s limit, and
+  a read could wait up to 11 minutes behind another process fetching the same
+  remote, so the Desktop's 30 s limit could end them (`E_CLI_TIMEOUT`). Now
+  every remote step of these two reads gets what is left of a 12 s budget: a
+  member not read by then is a `cannot-read` row (`… (timeout)`) and its git is
+  ended, and the command still answers. A workspace definition not read by then
+  fails as an unreadable one does today (`reason: "timeout"`). Another
+  process's write to the remote cache is waited for only as long, never taken
+  over. Spawn, sync and the other verbs are unchanged.

package/lib/capability-show.mjs

@@ -0,0 +1,208 @@
+/**
+ * lib/capability-show.mjs — `oats capabilities show` (feature capability-show, capabilityShowApi 1): what one
+ * catalog row of `oats capabilities` ships — its inject text and each skill's files — and one file's text on
+ * request, read at the row's commit through the read path a spawn uses. Contract: docs/desktop-cli-api.md
+ * "`oats capabilities show`".
+ *
+ * - A member row is read from its member repository at the row's commit, a package row at the LOCKED commit,
+ *   after the lock check a spawn makes (lockedCapability: the package's capability list there is the lock's).
+ *   The package's full-tree digest is not recomputed: `oats sync` proved the lock's integrity over the tree of
+ *   exactly that commit, and the commit id content-addresses the tree.
+ * - Skills are the spawn's enumeration (capabilitySkills over enumerateSkills, lib/resolve.mjs); a skill's
+ *   files are every regular file under its directory (listRemoteFiles), at most FILES_PER_SKILL.
+ * - Every read goes through lib/remote.mjs at a full commit id: nothing reads a working clone and nothing is
+ *   written outside the remote cache.
+ * - Paths in the answers are POSIX and relative to the capability directory. `--file` reads only a path the
+ *   show lists (the inject, a listed skill file): no other file of the capability is readable through it.
+ *
+ * Every text is untrusted repository content; a consumer renders it as plain text or through a sanitising
+ * renderer (the docs say so).
+ */
+import { posix } from "node:path";
+import YAML from "yaml";
+import { oatsError } from "./errors.mjs";
+import { bindRemote } from "./packages.mjs";
+import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifestFilePath, memberRef, unsafeRelPath } from "./resolve.mjs";
+import { memberRowByKey } from "./workspace.mjs";
+
+export const CAPABILITY_SHOW_API = 1;
+/** A text is cut to at most this many UTF-8 bytes; binary detection examines this many + 3. */
+export const TEXT_LIMIT = 262144;
+/** A skill lists at most this many files (`filesTruncated` beyond). */
+export const FILES_PER_SKILL = 200;
+/** A skill's `description` is cut to at most this many UTF-8 bytes. */
+export const DESCRIPTION_LIMIT = 1024;
+
+function fail(code, message, details) {
+  const e = oatsError(code, message, details);
+  if (details !== undefined) e.details = details;
+  return e;
+}
+const isOatsError = (e) => typeof e?.code === "string" && e.code.startsWith("E_");
+const decoder = () => new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const isContinuation = (byte) => (byte & 0xc0) === 0x80;
+
+/** The cut of `bytes` at most `limit` long, on a code point boundary (bytes are valid UTF-8 there). */
+function cutAt(bytes, limit) {
+  if (bytes.length <= limit) return bytes.length;
+  let cut = limit;
+  while (cut > 0 && isContinuation(bytes[cut])) cut--;
+  return cut;
+}
+
+/**
+ * A file's bytes as the answers carry them: → { text, binary, truncated }. Binary when the examined bytes (the
+ * first TEXT_LIMIT + 3) hold a NUL or are not valid UTF-8 (TextDecoder fatal, BOM kept); otherwise `text` is
+ * the content cut to at most TEXT_LIMIT bytes on a code point boundary, `truncated` when cut. The examined
+ * bytes include the whole code point that straddles the limit, so the cut is decided on the same bytes.
+ */
+export function decodeText(bytes, limit = TEXT_LIMIT) {
+  const head = bytes.subarray(0, limit + 3);
+  const binary = { text: null, binary: true, truncated: false };
+  if (head.includes(0)) return binary;
+  // A file longer than the examined bytes may continue a valid sequence they end inside of: `stream` accepts
+  // such an incomplete tail, and still refuses every invalid byte among them.
+  try { decoder().decode(head, { stream: bytes.length > head.length }); }
+  catch { return binary; }
+  const cut = cutAt(bytes, limit);
+  return { text: decoder().decode(bytes.subarray(0, cut)), binary: false, truncated: cut < bytes.length };
+}
+
+/** `text` cut to at most `limit` UTF-8 bytes on a code point boundary. */
+export function cutUtf8(text, limit) {
+  const bytes = Buffer.from(text, "utf8");
+  return bytes.length <= limit ? text : bytes.subarray(0, cutAt(bytes, limit)).toString("utf8");
+}
+
+const FRONT_MATTER_RE = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/;
+/** The `description` of a SKILL.md's leading `---` YAML front matter (a string only), cut to DESCRIPTION_LIMIT
+ *  bytes; null when there is no front matter, it does not parse, or the key is absent or not a string. */
+export function skillDescription(text) {
+  if (typeof text !== "string") return null;
+  const m = FRONT_MATTER_RE.exec(text.replace(/^\uFEFF/, ""));
+  if (!m) return null;
+  let data;
+  try { data = YAML.parse(m[1] ?? "", { logLevel: "error" }); } catch { return null; }
+  if (data === null || typeof data !== "object" || Array.isArray(data) || typeof data.description !== "string") return null;
+  return cutUtf8(data.description, DESCRIPTION_LIMIT);
+}
+
+/** A `--file` path no listing could hold (lib/resolve.mjs unsafeRelPath): absolute, empty, a `.`/`..`/`.git`
+ *  component (any case), an empty component, a trailing slash, a backslash or a NUL. */
+export const unsafeFilePath = unsafeRelPath;
+
+/** The text a SKILL.md's description is parsed from: the whole readable file (its front matter may run past the
+ *  display cut), null when the file is binary by decodeText's rule. */
+function skillText(bytes) {
+  if (decodeText(bytes).binary) return null;
+  return new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
+}
+
+/** The catalog row a show reads: rows named `name`, narrowed by `--member <repoKey>` (a member row of that
+ *  repository) or `--package <id>` (that package's row). 0 → E_CAPABILITY_UNKNOWN; >1 → E_CAPABILITY_AMBIGUOUS. */
+export function selectCapabilityRow(rows, name, { member = null, package: pkg = null } = {}) {
+  let matches = rows.filter((r) => r.name === name);
+  if (member !== null) matches = matches.filter((r) => r.kind === "member" && r.repoKey === member);
+  if (pkg !== null) matches = matches.filter((r) => r.kind === "package" && r.package === pkg);
+  const selector = member !== null ? { member } : pkg !== null ? { package: pkg } : {};
+  if (matches.length === 0) {
+    const where = member !== null ? ` from member ${member}` : pkg !== null ? ` from package ${pkg}` : "";
+    throw fail("E_CAPABILITY_UNKNOWN", `no capability ${JSON.stringify(name)}${where} in this workspace's catalog (\`oats capabilities\` lists them; a package's capabilities appear after \`oats sync\`)`, { name, ...selector });
+  }
+  if (matches.length > 1) {
+    const candidates = matches.map((r) => (r.kind === "package" ? { kind: r.kind, package: r.package, origin: r.origin } : { kind: r.kind, repoKey: r.repoKey, origin: r.origin }));
+    throw fail("E_CAPABILITY_AMBIGUOUS", `${matches.length} capabilities are named ${JSON.stringify(name)} (${candidates.map((c) => c.origin).join("; ")}): choose one with --member <repoKey> or --package <id>`, { name, candidates });
+  }
+  return matches[0];
+}
+
+/**
+ * Where a catalog row is read from: → { name, kind, repoKey, package, version, commit, ref, dir, manifest,
+ * missingCode }. A member row from discovery (its capability path and manifest, the member's ref); a package
+ * row from its manifests at the locked commit, after the spawn's lock check (E_PACKAGE_INTEGRITY).
+ */
+export async function capabilitySource(row, { discovery, lock, catalog = null, remote, remoteOptions }) {
+  if (row.kind === "package") {
+    const entry = lock?.packages?.[row.package];
+    if (!entry) throw fail("E_CAPABILITY_UNKNOWN", `package ${row.package} is not in the lock — run \`oats sync\``, { name: row.name, package: row.package });
+    const { ref, capabilities } = await lockedPackageCapabilities(row.package, entry, { catalog, remote, remoteOptions });
+    const cap = lockedCapability(row.name, row.package, entry, capabilities);
+    return { name: row.name, kind: "package", repoKey: remote.parseRepoRef(ref).key, package: row.package, version: entry.version, commit: entry.commit, ref, dir: cap.dir, manifest: cap.manifest, missingCode: "E_PACKAGE_MANIFEST" };
+  }
+  const cap = memberRowByKey(discovery.members, row.repoKey)?.capabilities.find((c) => c.name === row.name);
+  if (!cap) throw fail("E_CAPABILITY_UNKNOWN", `no capability ${JSON.stringify(row.name)} in member ${row.repoKey}`, { name: row.name, member: row.repoKey });
+  return { name: row.name, kind: "member", repoKey: row.repoKey, package: null, version: null, commit: row.commit, ref: memberRef(discovery, remote, row.repoKey), dir: cap.path, manifest: cap.manifest, missingCode: "E_CAPABILITY_MISSING" };
+}
+
+const problemOf = (e, path) => ({ code: e.code, message: e.message, path });
+
+/** What a source lists, without reading any file's content: → { inject: { path (null when unsafe), safe } | null,
+ *  skills: [{ name, path, files: [{ path, bytes }] | null, filesTruncated }] | null, problems }. */
+async function listing(source, { remote, remoteOptions }) {
+  const r = bindRemote(remote, remoteOptions);
+  const { ref, commit, dir, manifest, missingCode } = source;
+  const problems = [];
+  let inject = null;
+  if (typeof manifest.inject === "string" && manifest.inject) {
+    const path = manifestFilePath(manifest.inject);
+    // An unsafe declared path is never put in a `path` field (every path in the answers is safe): null, and the
+    // raw value only inside the problem's message.
+    inject = { path, safe: path !== null };
+    if (!path) problems.push({ code: missingCode, message: `${source.name} declares inject ${JSON.stringify(manifest.inject)}, which is not a relative path inside the capability`, path: null });
+  }
+  const { skills: found, problem } = await capabilitySkills({ ref, commit, dir, manifest, remote, remoteOptions, missingCode });
+  if (!found) problems.push(problemOf(problem, null));
+  const skills = found && [];
+  for (const skill of found ?? []) {
+    // A skill whose files cannot be listed has `files: null` (and a problem): never "listed nothing".
+    // Only the listed files' sizes are learned: nothing past FILES_PER_SKILL is fetched (#409).
+    let listed = null;
+    try { listed = await r.listRemoteFiles(ref, commit, posix.join(dir, skill.path), { limit: FILES_PER_SKILL }); }
+    catch (e) { if (!isOatsError(e)) throw e; problems.push(problemOf(e, skill.path)); }
+    skills.push({ name: skill.name, path: skill.path, files: listed && listed.files.map((f) => ({ path: `${skill.path}/${f.path}`, bytes: f.size })), filesTruncated: listed !== null && listed.total > FILES_PER_SKILL });
+  }
+  return { inject, skills, problems };
+}
+
+const header = (source) => ({ capabilityShowApi: CAPABILITY_SHOW_API, name: source.name, kind: source.kind });
+
+/** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
+export async function capabilityShow(source, { remote, remoteOptions }) {
+  const r = bindRemote(remote, remoteOptions);
+  const { ref, commit, dir } = source;
+  const listed = await listing(source, { remote, remoteOptions });
+  const problems = [...listed.problems];
+  let inject = null;
+  if (listed.inject) {
+    inject = { path: listed.inject.path, bytes: null, text: null, binary: false, truncated: false };
+    if (listed.inject.safe) {
+      try { const { bytes, size } = await r.readRemoteFile(ref, commit, posix.join(dir, inject.path)); inject = { path: inject.path, bytes: size, ...decodeText(bytes) }; }
+      catch (e) { if (!isOatsError(e)) throw e; problems.push(problemOf(e, inject.path)); }
+    }
+  }
+  let skills = null;
+  if (listed.skills) {
+    skills = [];
+    for (const skill of listed.skills) {
+      let description = null;
+      try {
+        const { bytes } = await r.readRemoteFile(ref, commit, posix.join(dir, skill.path, "SKILL.md"));
+        description = skillDescription(skillText(bytes));
+      } catch (e) { if (!isOatsError(e)) throw e; }
+      skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
+    }
+  }
+  return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems };
+}
+
+/** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.
+ *  E_CAPABILITY_FILE_UNSAFE for a path no listing could hold; E_CAPABILITY_FILE_UNKNOWN for one it does not
+ *  list; the remote's own refusal (E_REMOTE_FILE_OVERSIZE, …) for one it lists but cannot read. */
+export async function capabilityFile(source, path, { remote, remoteOptions }) {
+  if (unsafeFilePath(path)) throw fail("E_CAPABILITY_FILE_UNSAFE", `${JSON.stringify(path)} is not a relative path inside the capability`, { path });
+  const listed = await listing(source, { remote, remoteOptions });
+  const known = (listed.inject?.safe && listed.inject.path === path) || (listed.skills ?? []).some((s) => (s.files ?? []).some((f) => f.path === path));
+  if (!known) throw fail("E_CAPABILITY_FILE_UNKNOWN", `${path} is not a file \`oats capabilities show ${source.name}\` lists (the inject, or a skill's files)`, { path, name: source.name });
+  const { bytes, size } = await bindRemote(remote, remoteOptions).readRemoteFile(source.ref, source.commit, posix.join(source.dir, path));
+  return { ...header(source), commit: source.commit, file: { path, bytes: size, ...decodeText(bytes) } };
+}

package/lib/packages.mjs

@@ -452,7 +452,7 @@ export function memoizedRemote(remote) {
 export function bindRemote(remote, remoteOptions) {
   if (!remoteOptions || Object.keys(remoteOptions).length === 0) return remote;
   const bound = { ...remote };
-  const arities = { observeRemote: 1, readRemoteFile: 3, listRemoteTree: 3, fetchRemoteTree: 4, memoAtCommit: 4, lastObservedCommit: 1, peekAtCommit: 3, prefetchObservation: 1, abandonPrefetches: 0 };
+  const arities = { observeRemote: 1, readRemoteFile: 3, listRemoteTree: 3, listRemoteFiles: 3, fetchRemoteTree: 4, memoAtCommit: 4, lastObservedCommit: 1, peekAtCommit: 3, prefetchObservation: 1, abandonPrefetches: 0 };
   for (const name of Object.keys(arities)) {
     if (typeof remote[name] !== "function") continue;
     bound[name] = (...args) => {

package/lib/remote.mjs

@@ -117,7 +117,15 @@
  *     unref'd while idle and ended by session.close();
  *   - `maxAge` (seconds): > 0 lets observeRemote reuse a recorded head observation
  *     (the observation store below) no older than that;
- *   - the head observations used, for the `observation` output block.
+ *   - the head observations used, for the `observation` output block;
+ *   - `deadline` (DEADLINE; the deployment reads `oats status` and `oats workspace status` only, READ_REMOTE_BUDGET_MS
+ *     after their session starts): every remote step gets what is left of it, not its own default — each git call's
+ *     timeout (ls-remote, fetch, ls-tree, the batch readers' answers, every cache plumbing call, the git version
+ *     probe), the cache write lock's wait, the half-initialised cache's wait and the lock-race backoff. A step the deadline ends is a
+ *     `timeout` (git's group killed as any timeout kills it; a step not started yet starts no git), so a member
+ *     not read by then degrades as any unreadable member does (a peel or version the deadline ended is a timeout,
+ *     never a missing commit or an older git). A wait the deadline cuts never changes what it judges: past it no
+ *     lock is taken or reclaimed, and a cache directory is not taken for a crash's leftover.
  *
  * PARSED CACHE (`memoAtCommit`, session only): a value derived only from the bytes at
  * (repo key, commit) by a given kernel never changes, so it is kept on disk under
@@ -157,6 +165,9 @@ export const GIT_TIMEOUT_MS = 30_000;
 /** The fetch of a commit into the cache: the first one transfers the commit's whole tree, which for a
  *  large workspace host takes far longer than GIT_TIMEOUT_MS (awebai/oats#362). */
 export const GIT_FETCH_TIMEOUT_MS = 600_000;
+/** The remote budget of a deployment read (`oats status`, `oats workspace status`): its session's `deadline` is
+ *  this long after the session starts, so the command answers inside a caller's own limit (the Desktop's 30 s). */
+export const READ_REMOTE_BUDGET_MS = 12_000;
 /** A session's tree index: the output budget of one `ls-tree -r -t -l -z <commit>`. */
 export const TREE_INDEX_BUDGET = 64 * 1024 * 1024;
 /** `--max-age` bounds (seconds). */
@@ -376,6 +387,21 @@ function abortError(signal) {
   return Object.assign(new Error("The operation was aborted", { cause: signal?.reason }), { name: "AbortError", code: "ABORT_ERR", overflowed: false, timedOut: false });
 }
 
+/** A git call the session's deadline left no time for: shaped as runGit's own timeout (classified "timeout"). */
+function deadlineError(args) {
+  return Object.assign(new Error(`Command failed: git ${args.join(" ")} (the read budget ended before it ran)`),
+    { code: null, killed: false, signal: null, timedOut: true, overflowed: false, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) });
+}
+
+/** `exec(args, opts)` under the session's deadline: its timeout (opts.timeout, else GIT_TIMEOUT_MS) cut to what is
+ *  left, and no git started once nothing is. Without a deadline, exactly `exec(args, opts)`. */
+function sessionExec(exec, session, args, opts = {}) {
+  if (session?.deadline == null) return exec(args, opts);
+  const timeout = session.remaining(opts.timeout ?? GIT_TIMEOUT_MS);
+  if (timeout <= 0) return Promise.reject(deadlineError(args));
+  return exec(args, { ...opts, timeout });
+}
+
 function stderrText(error) {
   const s = error?.stderr;
   return Buffer.isBuffer(s) ? s.toString("utf8") : typeof s === "string" ? s : String(error?.message ?? "");
@@ -475,15 +501,17 @@ const isLockRace = (error) => /\.lock': File exists|Unable to create .*\.lock|an
  *  git that was killed: the wait covers the first, short writes; a fetch's lock is judged by its age. */
 const LOCK_WAIT_MS = 3_000;
 /** Run `fn` (one git call that writes the cache repo), again after a lost on-disk `.lock` race, until
- *  LOCK_WAIT_MS has passed (backoff up to 500 ms, jittered); a timeout or any other failure is never retried. */
-async function retryLockRace(fn) {
+ *  LOCK_WAIT_MS has passed (backoff up to 500 ms, jittered); a timeout or any other failure is never retried.
+ *  A session's deadline cuts the backoff: the next call then ends as its timeout (sessionExec). */
+async function retryLockRace(fn, session = null) {
   const deadline = Date.now() + LOCK_WAIT_MS;
   for (let attempt = 0; ; attempt++) {
     try { return await fn(); }
     catch (error) {
       if (!isLockRace(error) || error.timedOut) throw error;
       if (Date.now() >= deadline) throw error;
-      await sleep(Math.min(500, 50 * 2 ** attempt) * (0.5 + Math.random()));
+      const backoff = Math.min(500, 50 * 2 ** attempt) * (0.5 + Math.random());
+      await sleep(session ? session.remaining(backoff) : backoff);
     }
   }
 }
@@ -541,8 +569,18 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
   try { mkdirSync(dirname(lock), { recursive: true, mode: 0o700 }); } catch (error) { throw refuse(`cannot create ${dirname(lock)} (${error.code ?? error.message})`); }
   const deadline = Date.now() + (session?.cacheWriteWaitMs ?? CACHE_WRITE_WAIT_MS);
   let held = null, waited = false;
+  // The session's deadline ends the wait before anything is taken or reclaimed: the read is a timeout, and the
+  // lock (live, stale or unreadable) stays exactly as it is.
+  const budgetEnded = () => {
+    let now = held;
+    try { now = readCacheWriteLock(lock); } catch { /* as last seen */ }
+    const holder = now?.owner ? `oats process ${now.owner.pid}` : "another process";
+    return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} at ${dir} (timeout, ${stage}): the read budget ended ${now ? `while ${holder} held its write lock ${lock}` : `before it took its write lock ${lock}`}`,
+      { url: ref.url, key: ref.key, reason: "timeout", stage, cacheDir: dir, lock, ...(now?.owner ? { holderPid: now.owner.pid } : {}) });
+  };
   for (let attempt = 0; ; attempt++) {
     if (signal?.aborted) throw unreadable(ref, abortError(signal), { cacheDir: dir, stage });
+    if (session?.expired()) throw budgetEnded();
     const tmp = `${lock}.${owner.pid}.${owner.token}`;
     try {
       writeFileSync(tmp, JSON.stringify(owner) + "\n", { mode: 0o600 });
@@ -550,7 +588,7 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
     } catch (error) { throw refuse(`cannot take its write lock ${lock} (${error.code ?? error.message})`); }
     finally { try { unlinkSync(tmp); } catch { /* never written */ } }
     try { held = readCacheWriteLock(lock); } catch (error) { throw refuse(`cannot read its write lock ${lock} (${error.code ?? error.message}); remove it if no oats process is running`); }
-    if (held && isStaleLock(held)) {
+    if (held && isStaleLock(held) && !session?.expired()) {
       const abandoned = reclaimCacheWriteLock(lock, held, owner);
       if (abandoned) {
         throw refuse(`${abandoned.guard} was left by ${abandoned.pid ? `oats process ${abandoned.pid}, which died` : "an oats process that died"} while reclaiming the write lock ${lock}; it is safe to remove once no oats process is running`,
@@ -561,8 +599,10 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
       throw refuse(held?.owner ? `oats process ${held.owner.pid} has been writing it since ${held.owner.startedAt} (lock ${lock}); try again once it finishes`
         : `its write lock ${lock} is held; it is safe to remove once no oats process is running`, held?.owner ? { holderPid: held.owner.pid } : {});
     }
+    if (session?.expired()) throw budgetEnded();
     waited = true;
-    await sleep(Math.min(250, 25 * 2 ** attempt) * (0.5 + Math.random()));
+    const backoff = Math.min(250, 25 * 2 ** attempt) * (0.5 + Math.random());
+    await sleep(session ? Math.max(1, session.remaining(backoff)) : backoff);
   }
   try { return await fn({ waited }); }
   finally {
@@ -627,7 +667,7 @@ function reclaimGitLock(repo, lockFile) {
  *  the call made once more. Anything else is thrown as git raised it. */
 async function cacheGit(repo, args, opts = {}) {
   const run = () => repo.local(args, opts);
-  try { return await retryLockRace(run); }
+  try { return await retryLockRace(run, repo.session); }
   catch (error) {
     const lockFile = isLockRace(error) ? lockFileOf(error, repo.dir) : null;
     if (!lockFile || !reclaimGitLock(repo, lockFile)) throw error;
@@ -646,15 +686,16 @@ function redactUrl(url) {
 }
 
 function repoHandle(dir, exec, session) {
-  const local = (args, opts = {}) => exec(["-C", dir, "-c", "gc.auto=0", ...args], { cwd: dir, ...(session ? { signal: session.signal } : {}), ...opts });
+  const local = (args, opts = {}) => sessionExec(exec, session, ["-C", dir, "-c", "gc.auto=0", ...args], { cwd: dir, ...(session ? { signal: session.signal } : {}), ...opts });
   return { dir, exec, local, session };
 }
 
 async function cacheRepo(ref, options) {
   const exec = options.exec ?? runGit;
   const dir = cacheDirOf(cacheRootOf(options), ref);
-  if (!existsSync(join(dir, "HEAD"))) await initCacheRepo(ref, dir, exec);
-  return repoHandle(dir, exec, sessionOf(options));
+  const session = sessionOf(options);
+  if (!existsSync(join(dir, "HEAD"))) await initCacheRepo(ref, dir, exec, session);
+  return repoHandle(dir, exec, session);
 }
 
 /** How long a cache directory without HEAD is waited for (an older kernel initialising it in place) before it
@@ -669,12 +710,12 @@ const HALF_INIT_WAIT_MS = 2_000;
  * moved aside and replaced; the cache is disposable. Any other failure is E_REMOTE_UNREADABLE
  * { reason: "cache", stage: "init", cacheDir }.
  */
-async function initCacheRepo(ref, dir, exec) {
+async function initCacheRepo(ref, dir, exec, session = null) {
   const failInit = (error) => cacheFailure(ref, error, { cacheDir: dir, stage: "init" });
   const tmp = `${dir}.init-${process.pid}-${randomBytes(4).toString("hex")}`;
   try {
     try { mkdirSync(tmp, { recursive: true, mode: 0o700 }); } catch (error) { throw failInit(error); }
-    try { await exec(["init", "-q", "--bare", tmp]); } catch (error) { throw failInit(error); }
+    try { await sessionExec(exec, session, ["init", "-q", "--bare", tmp]); } catch (error) { throw failInit(error); }
     try { writeFileSync(join(tmp, "oats-remote.json"), JSON.stringify({ key: ref.key, url: redactUrl(ref.url) }, null, 2) + "\n"); } catch {}
     const deadline = Date.now() + HALF_INIT_WAIT_MS;
     for (;;) {
@@ -683,7 +724,13 @@ async function initCacheRepo(ref, dir, exec) {
         if (error?.code !== "ENOTEMPTY" && error?.code !== "EEXIST") throw failInit(error);
       }
       if (existsSync(join(dir, "HEAD"))) return; // another process created it first
-      if (Date.now() < deadline) { await sleep(50); continue; }
+      if (Date.now() < deadline) {
+        // The session's deadline never shortens the judgment: a directory waited for less than the whole wait is
+        // never taken for a leftover. The read ends as a timeout instead.
+        if (session?.expired()) throw failInit(deadlineError(["init", "-q", "--bare", dir]));
+        await sleep(Math.max(1, Math.min(50, session ? session.remaining(50) : 50)));
+        continue;
+      }
       // No HEAD after the wait: a leftover. Move it aside (atomic; a process racing to do the same loses
       // with ENOENT, which is fine) and take its place.
       const aside = `${dir}.stale-${process.pid}-${randomBytes(4).toString("hex")}`;
@@ -705,8 +752,9 @@ function pinRef(oid) { return `refs/oats/commits/${oid}`; }
 
 class ReadSession {
   constructor({ maxAge = 0, now = Date.now, fingerprint = null, treeIndexBudget = TREE_INDEX_BUDGET, parsedLimits = null, batchTimeoutMs = GIT_TIMEOUT_MS,
-    cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS } = {}) {
+    cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null } = {}) {
     if (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > MAX_AGE_LIMIT) throw new TypeError(`maxAge must be an integer from 0 to ${MAX_AGE_LIMIT}`);
+    if (deadline !== null && !Number.isFinite(deadline)) throw new TypeError("deadline must be null or a time in Date.now() milliseconds");
     this.maxAge = maxAge;
     this.now = now;
     this.startedAt = new Date(now()).toISOString();
@@ -715,6 +763,7 @@ class ReadSession {
     this.batchTimeoutMs = batchTimeoutMs;  // tests shorten it; a batch answer is otherwise waited for as long as any git call
     this.cacheWriteWaitMs = cacheWriteWaitMs; // tests shorten it: how long a write waits for another live writer of its cache
     this.fetchTimeoutMs = fetchTimeoutMs;  // tests shorten it: a fetch's own timeout
+    this.deadline = deadline;              // null, or when every remote step of the command must be over (remaining())
     this.parsedLimits = parsedLimits;      // tests inject small prune bounds
     this.observations = new Map();         // memo key → Promise<head observation>
     this.used = new Map();                 // memo key → { observedAt, reused }: the heads this command used
@@ -793,12 +842,18 @@ class ReadSession {
     this.retiring.clear();
     reapOnExit(); // no timer runs on the exit path: SIGTERM, a bounded synchronous grace, then SIGKILL
   }
+  /** What a wait or a git call of `ms` may take: `ms`, cut to what is left before the deadline (never below 0).
+   *  Without a deadline, `ms` itself. */
+  remaining(ms) { return this.deadline === null ? ms : Math.max(0, Math.min(ms, this.deadline - Date.now())); }
+  /** Whether the deadline has passed: every remote step not over by then ends as a `timeout`. */
+  expired() { return this.remaining(Infinity) === 0; }
   /** A session rides remoteOptions, which callers may serialise (memo keys): never its innards. */
   toJSON() { return "[oats read session]"; }
 }
 
-/** One command's read session (see the module header). `maxAge` seconds (0 = observe live). Test seams:
- *  `now`, `fingerprint`, `treeIndexBudget`, `parsedLimits`, `batchTimeoutMs`, `cacheWriteWaitMs`, `fetchTimeoutMs`. */
+/** One command's read session (see the module header). `maxAge` seconds (0 = observe live). `deadline` (Date.now()
+ *  milliseconds, or null): every remote step ends by then (the module header's DEADLINE). Test seams: `now`,
+ *  `fingerprint`, `treeIndexBudget`, `parsedLimits`, `batchTimeoutMs`, `cacheWriteWaitMs`, `fetchTimeoutMs`. */
 export function createReadSession(options = {}) { return new ReadSession(options); }
 /** An observation the command no longer wants (its session closed, or its prefetch abandoned): never adopted
  *  by a caller that is still reading, so its shape only has to be a typed remote failure. */
@@ -1106,7 +1161,7 @@ async function ensureCommit(ref, oid, options) {
     let peeled = false; // the object store was asked already, and said no
     const usable = async (repo) => {
       if (!existsSync(join(dir, "HEAD"))) return null;
-      if (!keepsPartialCache(await gitVersion(repo.exec)) && await fetchMode(repo) === "partial") return null;
+      if (!keepsPartialCache(await readVersion(repo, ref)) && await fetchMode(repo) === "partial") return null;
       peeled = true;
       return peelCommit(repo, oid);
     };
@@ -1116,7 +1171,7 @@ async function ensureCommit(ref, oid, options) {
     // waited for it finds what the holder fetched.
     return withCacheWriteLock(ref, dir, "fetch", session, async ({ waited }) => {
     let repo = await cacheRepo(ref, options);
-    const version = await gitVersion(repo.exec);
+    const version = await readVersion(repo, ref);
     // A partial cache is only safe where git cannot fetch a missing blob on its own: an older git rebuilds it whole.
     if (!keepsPartialCache(version) && await fetchMode(repo) === "partial") repo = await rebuildWhole(repo, ref, options, version);
     const cached = peeled && !waited ? null : await peelCommit(repo, oid);
@@ -1129,6 +1184,8 @@ async function ensureCommit(ref, oid, options) {
     if (mode === "partial" && /filtering not recognized by server/i.test(stderr.toString("utf8"))) await recordFullFetches(repo, ref);
     const commit = await peelCommit(repo, oid);
     if (!commit) {
+      // A peel the session's deadline ended is the read's timeout, never a missing commit.
+      if (session?.expired()) throw unreadable(ref, deadlineError(["rev-parse", `${oid}^{commit}`]), { commit: oid, cacheDir: repo.dir, stage: "fetch" });
       const type = await objectType(repo, oid);
       throw fail("E_REMOTE_UNREADABLE", `${oid} in ${ref.url} is ${type ? `a ${type}` : "missing"}, not a commit`, { url: ref.url, key: ref.key, reason: "not-found", commit: oid, type });
     }
@@ -1186,19 +1243,41 @@ async function recordFullFetches(repo, ref, notice = `${redactUrl(ref.url)} does
 const olderGitNotice = (version, ref) =>
   `git ${version?.text ?? "(unknown version)"} cannot keep a partial cache (it needs ${PARTIAL_FETCH_GIT.join(".")}); OATS fetches whole trees from ${redactUrl(ref.url)}`;
 
-/** `git --version` of the git `exec` runs, asked once per exec: → { text: "2.54.0", major, minor } | null. */
+/** `git --version` of the git `exec` runs, asked once per exec: → { text: "2.54.0", major, minor } | null.
+ *  `opts` (a timeout, a signal) go to the call that asks. A call that timed out says nothing about this git:
+ *  it answers null to its waiters and is asked again next time. */
 const gitVersions = new WeakMap();
-export function gitVersion(exec = runGit) {
+export function gitVersion(exec = runGit, opts = undefined) {
   let version = gitVersions.get(exec);
   if (!version) {
-    version = Promise.resolve().then(() => exec(["--version"])).then((out) => {
+    version = Promise.resolve().then(() => exec(["--version"], ...(opts ? [opts] : []))).then((out) => {
       const m = /git version ((\d+)\.(\d+)[^\s]*)/.exec(out.stdout.toString("utf8"));
       return m ? { text: m[1], major: Number(m[2]), minor: Number(m[3]) } : null;
-    }, () => null);
+    }, (error) => {
+      if (error?.timedOut && gitVersions.get(exec) === version) gitVersions.delete(exec);
+      return null;
+    });
     gitVersions.set(exec, version);
   }
   return version;
 }
+/** gitVersion for a read of `ref` in `repo`'s session. Under a deadline the probe gets what is left of it, and
+ *  is waited for no longer (another caller may own the probe): a version the deadline left unknown is the
+ *  read's timeout, never taken for an older git (which would rebuild a partial cache). */
+async function readVersion(repo, ref) {
+  const session = repo.session;
+  if (session?.deadline == null) return gitVersion(repo.exec);
+  const ended = () => unreadable(ref, deadlineError(["--version"]), { cacheDir: repo.dir, stage: "fetch" });
+  const left = session.remaining(GIT_TIMEOUT_MS);
+  if (left <= 0) throw ended();
+  let timer;
+  const late = new Promise((resolvePromise) => { timer = setTimeout(() => resolvePromise(ended), left); });
+  try {
+    const version = await Promise.race([gitVersion(repo.exec, { timeout: left, signal: session.signal }), late]);
+    if (version === ended || (version === null && session.expired())) throw ended();
+    return version;
+  } finally { clearTimeout(timer); }
+}
 /** Whether this git keeps a partial cache honest (GIT_NO_LAZY_FETCH): an unknown version does not. */
 export function keepsPartialCache(version) {
   const [major, minor] = PARTIAL_FETCH_GIT;
@@ -1443,7 +1522,7 @@ async function observeLive(ref, args, at, options) {
   const exec = options.exec ?? runGit;
   const signal = sessionOf(options)?.signal;
   let out;
-  try { out = await exec(args, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}) }); }
+  try { out = await sessionExec(exec, sessionOf(options), args, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}) }); }
   catch (error) { throw unreadable(ref, error, { at: at ?? null }); }
   const parsed = parseLsRemote(out.stdout);
   const hit = resolveAt(parsed, at);
@@ -1578,11 +1657,11 @@ function killChild(child) {
  * like repo.local (same `-C <dir> -c gc.auto=0`, cwd, helper-free gitEnv()); unref'd while idle, so it
  * never keeps the process alive. A header over `budget` rejects that request with `{ oversize }` and its
  * body is skipped, never buffered; a non-blob answers as `cat-file blob` would ("bad file"). `missing`,
- * the child dying (or never starting: ENOENT), or no answer within GIT_TIMEOUT_MS rejects EVERY pending
- * request with a git-shaped error (classifyRemoteFailure reads it as today: timeout → "timeout") and
- * ends the child; the next read starts a new one.
+ * the child dying (or never starting: ENOENT), or no answer within GIT_TIMEOUT_MS (cut to what is left of
+ * `session`'s deadline) rejects EVERY pending request with a git-shaped error (classifyRemoteFailure reads it
+ * as today: timeout → "timeout") and ends the child; the next read starts a new one.
  */
-function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS) {
+function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS, session = null) {
   // Detached, as its own process group: killChild's group kill also ends anything git started.
   const child = watchGroup(spawn("git", ["-C", dir, "-c", "gc.auto=0", "cat-file", "--batch"], { cwd: dir, env: gitEnv(), detached: true, stdio: ["pipe", "pipe", "pipe"] }));
   liveChildren.add(child);
@@ -1596,7 +1675,8 @@ function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS) {
   const arm = () => {
     clearTimeout(timer); timer = null;
     if (!queue.length) { idle(); return; }
-    timer = setTimeout(() => die(Object.assign(new Error(`git cat-file --batch: no answer within ${timeoutMs} ms`), { killed: true, signal: "SIGKILL", timedOut: true, stderr: Buffer.from(stderr) })), timeoutMs);
+    const ms = session ? session.remaining(timeoutMs) : timeoutMs;
+    timer = setTimeout(() => die(Object.assign(new Error(`git cat-file --batch: no answer within ${ms} ms`), { killed: true, signal: "SIGKILL", timedOut: true, stderr: Buffer.from(stderr) })), ms);
   };
   const die = (error) => {
     if (dead) return;
@@ -1686,7 +1766,8 @@ function catFileBatch(repo) {
   if (!session || session.closed || repo.exec !== runGit) return null;
   let reader = session.batches.get(repo.dir);
   if (reader && !reader.dead) { session.batches.delete(repo.dir); session.batches.set(repo.dir, reader); return reader; }
-  reader = openBatch(repo.dir, session.batchTimeoutMs);
+  if (session.expired()) return null; // a per-blob read, which ends as the deadline's timeout (sessionExec)
+  reader = openBatch(repo.dir, session.batchTimeoutMs, session);
   session.batches.set(repo.dir, reader);
   if (session.batches.size > BATCH_LIMIT) {
     for (const [dir, other] of session.batches) {
@@ -1795,6 +1876,42 @@ export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...op
   return result;
 }
 
+/**
+ * → { files: [{ path, size }], total } for the regular files (blobs) under <dir> at <commit>, recursively,
+ * relative to <dir>, sorted by path in codepoint order (feature capability-show): `total` of them in all, and
+ * `files` the first `limit` (every one without a limit). Symlinks and gitlinks are omitted; a name that could
+ * escape a checkout ANYWHERE below <dir> is refused (E_REMOTE_TREE_UNSAFE, as listRemoteTree), past the limit
+ * too. One listing (the session's tree index when it has one); the sizes a partial cache lacks are learned with
+ * ONE ensureBlobs call over the listed files only, so nothing past the limit is fetched. A missing dir, or one
+ * that is not a directory → { files: [], total: 0 }. Memoized at the commit (memoAtCommit), per limit.
+ */
+export async function listRemoteFiles(refText, commitArg, dir, { limit, ...options } = {}) {
+  const ref = parseRepoRef(refText, options);
+  requireCommit(commitArg);
+  if (limit !== undefined && (!Number.isInteger(limit) || limit < 0)) throw fail("E_REPO_REF", "limit must be a non-negative integer", { limit });
+  const rel = normalizeTreePath(dir, { allowRoot: true });
+  const none = { files: [], total: 0 };
+  return memoAtCommit(ref, commitArg, `files\0${rel}\0${limit ?? "all"}`, async () => {
+    const { repo, commit } = await ensureCommit(ref, commitArg, options);
+    if (rel) {
+      const entry = await entryAt(repo, commit, rel, ref);
+      if (!entry || entry.type !== "tree") return none;
+    }
+    const index = await treeIndex(repo, commit, ref);
+    const entries = index ? indexDescendants(index, rel) : await lsTree(repo, rel ? `${commit}:${rel}` : commit, { flags: ["-r"], ref, commit });
+    if (!entries) return none;
+    const blobs = [];
+    for (const e of entries) {
+      assertSafeEntryPath(e.path, ref, commit, rel ? `${rel}/${e.path}` : e.path);
+      if (e.type === "blob" && e.mode !== "120000") blobs.push({ ...e });
+    }
+    blobs.sort(byPath);
+    const listed = limit === undefined ? blobs : blobs.slice(0, limit);
+    await ensureBlobs(repo, ref, commit, listed);
+    return { files: listed.map((e) => ({ path: e.path, size: e.size })), total: blobs.length };
+  }, options);
+}
+
 // ---------------------------------------------------------------------------
 // digest
 // ---------------------------------------------------------------------------

package/lib/resolve.mjs

@@ -474,12 +474,29 @@ export function packageRef(id, entry, catalog, remote) {
 const SAFE_REL = (rel) => typeof rel === "string" && rel && !posix.isAbsolute(rel) && !/^[\\/]/.test(rel) && !/\0/.test(rel) && !rel.split(/[\\/]/).some((p) => p === "..");
 
 /** Normalize a manifest-declared relative path ("./skills/x/" → "skills/x"); null when unsafe. */
-function declaredPath(rel) {
+export function declaredPath(rel) {
   if (!SAFE_REL(rel)) return null;
   const n = posix.normalize(rel).replace(/\/+$/, "");
   return n === "." || n === "" || n.startsWith("../") ? null : n;
 }
 
+/** A relative path no listing of a checkout can hold: absolute, empty, a `.`/`..`/`.git` (any case) or empty
+ *  component, a trailing slash, a backslash or a NUL. */
+export function unsafeRelPath(path) {
+  if (typeof path !== "string" || path === "" || path.startsWith("/") || path.endsWith("/") || /[\\\0]/.test(path)) return true;
+  return path.split("/").some((c) => c === "" || c === "." || c === ".." || c.toLowerCase() === ".git");
+}
+
+/** A manifest-declared path as the module install reads it (lib/materialize.mjs modulePath: a backslash is a
+ *  separator, `./` and trailing slashes dropped), and only when the result is a safe POSIX path (unsafeRelPath);
+ *  else null. What `oats capabilities show` reports for an inject or a skill. */
+export function manifestFilePath(rel) {
+  const declared = declaredPath(rel);
+  if (!declared) return null;
+  const n = posix.normalize(declared.replace(/\\/g, "/")).replace(/^(?:\.\/)+/, "").replace(/\/+$/, "");
+  return unsafeRelPath(n) ? null : n;
+}
+
 /**
  * Skills declared by a manifest: each `skills[]` entry is a directory under the capability that either
  * IS a skill (holds SKILL.md) or holds skill directories (<entry>/<skill>/SKILL.md) — the same reading
@@ -525,14 +542,31 @@ async function enumerateSkills({ remote, ref, commit, dir, manifest, listing, mo
  *  would), commands and hooks. `skills` is null when its declared skills cannot be listed (a spawn of it
  *  would refuse; the listing does not). */
 export async function capabilityProvides({ ref, commit, dir, manifest, remote: injected, remoteOptions }) {
-  const remote = remoteOf({ remote: injected, remoteOptions });
   const keys = (o) => (isObject(o) ? Object.keys(o).sort(byCodepoint) : []);
-  let skills;
+  const { skills } = await capabilitySkills({ ref, commit, dir, manifest, remote: injected, remoteOptions });
+  return { skills: skills && skills.map((s) => s.name), commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
+}
+
+/** A capability's skills as a spawn enumerates them (enumerateSkills), sorted by name in codepoint order:
+ *  → { skills: [{ name, path }] (path relative to the capability directory), problem: null }, or
+ *  { skills: null, problem } when the declared skills cannot be enumerated — `problem` the oats error a spawn
+ *  would meet (`missingCode`: E_CAPABILITY_MISSING for a member, E_PACKAGE_MANIFEST for a package), or a skill
+ *  path that is not safe (manifestFilePath). Paths are as the install reads them. The one reading of
+ *  `manifest.skills` behind `oats capabilities` (capabilityProvides) and `oats capabilities show`. */
+export async function capabilitySkills({ ref, commit, dir, manifest, remote: injected, remoteOptions, missingCode = "E_CAPABILITY_MISSING" }) {
+  const remote = remoteOf({ remote: injected, remoteOptions });
+  const missing = (raw, why, text) => fail(missingCode, `${manifest.capability} ${text}`, { capability: manifest.capability, skill: raw, why });
   try {
-    const missing = (raw, why, text) => fail("E_CAPABILITY_MISSING", text, { skill: raw, why });
-    skills = (await enumerateSkills({ remote, ref, commit, dir, manifest, moduleName: manifest.capability, missing })).map((x) => x.name).sort(byCodepoint);
-  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) skills = null; else throw e; }
-  return { skills, commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
+    const skills = [];
+    for (const { name, path } of await enumerateSkills({ remote, ref, commit, dir, manifest, moduleName: manifest.capability, missing })) {
+      // A skill path is reported as the install reads it, and only when it is a safe POSIX path (a `.git`
+      // directory the remote serves is one a spawn's fetch refuses).
+      const safe = manifestFilePath(path);
+      if (!safe) throw missing(path, "unsafe", `declares skill ${show(name)} at ${show(path)}, which is not a safe path inside the capability`);
+      skills.push({ name, path: safe });
+    }
+    return { skills: skills.sort((a, b) => byCodepoint(a.name, b.name)), problem: null };
+  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return { skills: null, problem: e }; throw e; }
 }
 
 /** The capability manifests of a locked package, read at its locked commit (feature desktop-facts). */
@@ -543,6 +577,20 @@ export async function lockedPackageCapabilities(id, entry, { catalog = null, rem
   return { ref, capabilities };
 }
 
+/** The lock must describe the tree it names: the capability list a package's manifests declare at the locked
+ *  commit (`capabilities`, readPackageManifests) must equal the lock entry's, and must hold `name`, else
+ *  E_PACKAGE_INTEGRITY. → that capability { name, dir, manifest }. Spawn's check (resolveSoul), shared with
+ *  `oats capabilities show`. */
+export function lockedCapability(name, id, entry, capabilities, details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path }) {
+  const listed = capabilities.map((c) => c.name).sort(), locked = [...entry.capabilities].sort(); // validateLock guarantees the array
+  if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
+    throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides [${locked.join(", ")}], but ${entry.path}/oats-package.json at ${short(entry.commit)} declares [${listed.join(", ")}]`, { ...details, why: "capabilities", listed, locked });
+  }
+  const cap = capabilities.find((c) => c.name === name);
+  if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
+  return cap;
+}
+
 /* ───────────────────────────── resolveSoul ────────────────────────────── */
 
 /**
@@ -601,13 +649,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
       const ref = packageRef(id, entry, catalog, remote);
       const details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path };
       const { capabilities } = await readPackageManifests(remote, ref, entry.commit, entry.path, details);
-      // The lock must describe the tree it names: its capability list is what the package declares there.
-      const listed = capabilities.map((c) => c.name).sort(), locked = [...entry.capabilities].sort(); // validateLock guarantees the array
-      if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
-        throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides [${locked.join(", ")}], but ${entry.path}/oats-package.json at ${short(entry.commit)} declares [${listed.join(", ")}]`, { ...details, why: "capabilities", listed, locked });
-      }
-      const cap = capabilities.find((c) => c.name === name);
-      if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
+      const cap = lockedCapability(name, id, entry, capabilities, details);
       const layer = layerOf(cap.manifest);
       if (layer && emptied.has(layer) && via !== "soul") { turnedOff.push({ name, reason: "slot-none", slot: layer, overrides: fromOfVia(via) }); continue; }
       module = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",