@awebai/oats 0.32.0 → 0.34.0

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

@@ -0,0 +1,174 @@
+# OATS 0.33.0
+
+## Added
+
+- **`oats spawn <soul> --preview --max-age <seconds>`** (feature
+  `spawn-preview-max-age`). A preview reuses member heads this machine
+  observed at most that many seconds ago, as the read verbs do since 0.32.0,
+  so a warm preview asks no remote. With the flag the preview's JSON carries
+  the read verbs' `observation {observedAt, reused, localRevision}` block;
+  without it the preview is unchanged. The decision still covers the heads
+  the preview used: an apply with `--expect-decision` observes live and
+  refuses `E_DECISION_STALE` when a reused head has moved, and a re-preview
+  then shows the new head. The apply refuses `--max-age` (`E_BAD_ARGS`), and
+  the refusal message of every form that refuses the flag now lists
+  `spawn --preview` among the read forms.
+
+## Changed
+
+- **OATS fetches only what it reads from a remote** (awebai/oats#384). A
+  commit comes with its trees and its files up to 64 KiB; a larger file is
+  fetched when a read or a module needs it. The first spawn from a large
+  workspace host downloads megabytes instead of its whole tree (tsm: 13 MB in
+  3 s, instead of 2.4 GB in 6.5 minutes). A server that cannot serve partial
+  fetches (a default `git daemon`, an old self-hosted git), or a local git
+  older than 2.45, gets whole trees as before, with one `oats: warning` per
+  repository.
+
+- **Installing a soul's modules reads their files without a process per
+  file.** `oats spawn` copies each module's files from the remote cache
+  through the command's one `git cat-file --batch` reader per repository,
+  as the reads and discovery already do, instead of one `git cat-file blob`
+  per file. A Desktop developer spawn on this deployment ran 50 to 59
+  processes instead of 81 (34 per-file reads became 3 to 7 readers).
+  Budgets, digests, partial caches and errors are unchanged.
+
+- **oats.engineering 1.4.0** (catalog and workspace pin, and the bundled
+  mirrors): the developer's loop REQUIRES loading `/understand-the-spec` and
+  `/execution-strategy` before implementation.
+
+- **oats.aweb 1.17.5** (catalog and workspace pin, and the bundled mirror;
+  1.17.4 and 1.17.5): a faster spawn and retire. The spawn hook mints the identity with one
+  `aw init --join-from` instead of `aw team invite` + `aw team join` +
+  `aw init`, so the invite token no longer appears in any argv. The aw floor
+  check stops at `aw version`'s version line instead of waiting on its GitHub
+  update check. Retire deletes by workspace id, with `aw wake deregister`
+  running at the same time. Measured spawn hook: 7.72 s to 4.62 s mean
+  (awebai/oats-aweb#31). Hook output, compensation and the aw floor (1.36.13)
+  are unchanged. The mint now has one 120 s budget where three calls had
+  about 210 s; raise `OATS_AWEB_JOIN_TIMEOUT_MS` on a slow network. Since the
+  hook no longer holds the invite token, 1.17.5 always records the alias it
+  requested and warns, without quoting the reply, when aw reports another
+  (awebai/oats-aweb#32).
+
+- **Pressing Spawn (Cmd-Enter) closes the spawn dialog at once.** The spawn
+  completes in the background: a pending row ("Spawning…") appears in the
+  sidebar roster where the instance will stand, and is replaced in place by
+  the real row once the roster reports it. Outcomes arrive as notifications:
+  "<name> spawned" with Open, what didn't finish for a partial or incomplete
+  spawn (with View schedules for a wake that wasn't saved), and, for a
+  refused or failed spawn, the reason with **Reopen spawn**, which restores
+  the whole draft. An unknown outcome keeps the row, reading "Outcome
+  unknown", with Check result. Prepare reuses the dialog's fresh preview
+  instead of reading it again, and the kernel's `--expect-decision` still
+  refuses a decision that changed. Dialog previews use `--max-age 60` when the
+  CLI supports it (feature `spawn-preview-max-age`)
+  ([desktop-spawn-preview.md](../../packages/desktop/docs/desktop-spawn-preview.md#background-spawn-the-dialog-closes-on-spawn)).
+
+- **The spawn dialog never waits on the preview while you edit.** The last
+  preview stays visible while it updates, Spawn stays pressable, and answers
+  are reused for 60 s (#378).
+
+- **Core capabilities and Capabilities read as one system** on the soul page,
+  the capability page, the instance inspector and the spawn preview. Every
+  core row says why it's there, including a slot the soul empties or that has
+  no default. The capability page opened from a soul gains a "Why" row.
+  Workspace › Capabilities lists Repo owned before Packages (#377).
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.34.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.33.0 together: the
+  Desktop 0.32.x refuses a 0.33 CLI.
+
+- **Unattended claude and codex launches** (awebai/oats#341,
+  [souls-and-instances.md](../souls-and-instances.md#unattended-launches-folder-trust)).
+  - Every codex launch passes `-c check_for_update_on_startup=false`, so
+    Codex's update prompt no longer blocks it.
+  - Codex does not apply a trusted parent to the folders below it. When
+    `~/.codex/config.toml` trusts the deployment or an ancestor, a codex
+    launch now trusts its new home for that session; the file is never
+    written.
+  - A claude or codex spawn whose home is not covered by the operator's
+    one-time trust of the deployment warns `the <harness> session will stop
+    at its folder-trust prompt: trust <deployment> once (…)`. `oats readiness`
+    reports the same as a `harness-trust` item in `checks.configured` (not
+    required).
+
+- **The Desktop names an OATS cache problem, and keeps the roster through an
+  unreadable remote.** When the kernel can't read a remote
+  (`E_REMOTE_UNREADABLE`), the sidebar roster keeps the instances it last
+  observed instead of going empty. A cache problem (`details.reason: "cache"`)
+  reads "Couldn't refresh instances · OATS cache problem · observed <age>",
+  with the kernel's message in full (it names the lock file or the process
+  holding it, and the remedy) and Retry. With nothing observed yet, the failed
+  state shows that message. A network failure or a timeout reads "Couldn't
+  reach <host> · showing what was read <age>", with the raw code behind
+  Details. Of the kernel's structured `details`, only the reason and the
+  host of the remote cross to the window; the kernel's message is shown as
+  given, with the file or process it names
+  ([desktop-cli-api.md](../desktop-cli-api.md#workspace)).
+
+## Fixed
+
+- **A background spawn never fails silently, and a soul can't be spawned
+  twice at once** (awebai/oats#383). While a spawn of a soul is in flight,
+  opening Spawn for it shows the press disabled with "A spawn of <soul> is in
+  progress" and a link to its pending row; it re-enables when the spawn
+  settles. After a window reload, a spawn whose outcome wasn't known yet comes
+  back as a pending row and its outcome is reported, a failure included, even
+  when it settled while another workspace was on screen; Reopen spawn then
+  restores the soul and the name. Quitting the Desktop mid-spawn
+  still loses an unreported failure
+  ([desktop-spawn-preview.md](../../packages/desktop/docs/desktop-spawn-preview.md#background-spawn-the-dialog-closes-on-spawn)).
+
+- **A git that the system kills is no longer reported as a timeout**
+  (awebai/oats#387). A remote read reports `timeout` only when OATS's own
+  timer stopped git. When something else kills git (an out-of-memory kill
+  during a large fetch, for example), the error now reads `cannot read remote
+  <url> (killed): git was killed (signal SIGKILL)`, with `reason: killed` and
+  `details.signal`. Before, it said `(timeout)`.
+
+- **Codex sessions see their instance** (awebai/oats#342). Codex can run tool
+  commands under its shared app-server daemon, without the session's
+  environment, so `oats aweb roster` inside Codex asked for `--soul`.
+  - A codex launch now sets the instance environment for tool commands with
+    `shell_environment_policy.set`: `OATS_INSTANCE`/`OATS_INSTANCE_HOME`, the
+    capabilities' launch environment (`AWEB_IDENTITY_HOME`, `AWEB_DELIVERY`)
+    and the launch configuration's literals.
+  - It also sets `PATH` with the home's `.oats/bin` first. The user's login
+    shell may put its profile's entries ahead of it.
+  - A capability command with no home in its environment finds the home from
+    its working directory.
+
+- The partial-fetch tests now pass on a host whose git is older than 2.45
+  (awebai/oats#389). The kernel already fell back to whole trees there; the
+  tests now read the kernel's own git probe:
+  - on an older git they assert that fallback (whole trees, one warning per
+    repository);
+  - they skip the partial-cache mechanics that cannot happen there, and name
+    why;
+  - under CI, an older git fails those tests instead.
+
+- **A killed fetch no longer leaves a remote cache unusable** (awebai/oats#386).
+  OATS ends git with SIGTERM first, so git removes its own lock files, and
+  SIGKILL only after a grace. A lock left by a git killed earlier is removed
+  once it is older than the longest fetch, with an `oats: warning` naming it.
+  A younger one is never removed: the error names the file and says it is
+  safe to remove once no oats or git process is running.
+
+- **Ending git leaves no survivor in its process group** (awebai/oats#386). After
+  git's own output closes, OATS keeps checking git's process group until the grace
+  ends: a member that ignores SIGTERM and holds no pipe is still killed, and a
+  group seen empty is never signalled again (its id may already belong to another
+  process).
+
+- **Processes making the first fetch from one remote at once all succeed**
+  (two spawns, two Desktop previews). Every write to a cache takes a
+  per-cache lock: a live holder is waited for, a dead one's lock is reclaimed,
+  and the cache repo appears whole. A failure to write the local cache is now
+  reported as `E_REMOTE_UNREADABLE` with the new reason `cache`, never as
+  `network`.
+
+- Fetching a commit into the remote cache may take 10 minutes instead of 30 s, so
+  the first spawn from a large workspace host no longer fails with `cannot read
+  remote … (timeout)`; the timeout error names the fetch and the elapsed time
+  (awebai/oats#362).

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/docs/souls-and-instances.md

@@ -204,6 +204,70 @@ the harness's own precedence. The `CLAUDE.md → AGENTS.md` and
 `.claude/skills → ../.agents/skills` aliases are kept. OATS composes
 instructions and pins model/provider settings; it excludes nothing.
 
+### Unattended launches: folder trust
+
+Claude Code and Codex ask before they work in a folder they have not seen, and
+every instance home is new. A launch stopped at that prompt waits for a human,
+so the operator trusts the **deployment directory** (where `oats-local.yaml`
+is) once per harness. OATS only reads the harnesses' configuration; it never
+writes it.
+
+- **Claude Code** looks for an accepted entry for its folder or an ancestor, up
+  to a git root. Instance homes are not inside a git repository, so one entry
+  for the deployment covers every home under it. To add it, run `claude` in the
+  deployment once and accept the prompt. That records
+  `projects["<deployment>"].hasTrustDialogAccepted` in `~/.claude.json`
+  (`$CLAUDE_CONFIG_DIR/.claude.json` when that is set).
+- **Codex** applies only an exact entry: a trusted parent does not cover the
+  folders below it. To give the operator's consent, run `codex` in the
+  deployment once and choose "Trust and continue". That records
+  `[projects."<deployment>"] trust_level = "trusted"` in
+  `~/.codex/config.toml` (`$CODEX_HOME/config.toml`). With that entry, or one
+  for an ancestor of the deployment, each codex launch trusts its own new home
+  for that session (`-c 'projects={"<home>"={trust_level="trusted"}}'`) and
+  leaves the config file unchanged. A yolo launch always does this. The plan
+  re-reads the entry at every start.
+- Every codex launch also passes `-c check_for_update_on_startup=false`, so
+  Codex's "Update available" choice cannot block it.
+
+When a claude or codex home is not covered, the spawn says so (text and
+`--json` `warnings`): `the <harness> session will stop at its folder-trust
+prompt: trust <deployment> once (<the step>)`. `oats readiness` reports the
+same in `checks.configured` (code `harness-trust`, not required).
+
+### Codex tool commands and the instance environment
+
+Codex can run tool commands under its shared app-server daemon rather than as
+children of the session OATS launched, and then they do not inherit the
+session's environment. Codex (0.157.1) runs a session that has `-c` overrides
+embedded, without the daemon, and every kernel codex launch has them, so an
+OATS codex session does not appear in `codex agents`. So that the environment
+does not depend on this, a codex launch also sets it for tool
+commands explicitly with `-c shell_environment_policy.set.<NAME>="<value>"`:
+
+- the instance: `OATS_INSTANCE`, `OATS_INSTANCE_HOME`, `PI_AGENT_INSTANCE`,
+  `PI_AGENT_HOME`;
+- every capability's launch environment (for example the messaging
+  provider's identity home and delivery mode);
+- the launch configuration's literal values. A reference's value never goes
+  on a command line.
+
+`PATH` comes from the launching shell, with the home's `.oats/bin` first, so
+only the execution passes it; the persisted command does not carry it. Codex
+runs tool commands through the user's login shell, and a profile that prepends
+directories puts those entries ahead of `.oats/bin`. A second `oats` in such a
+directory is found first.
+
+A capability command (`oats <namespace> …`) run with none of
+`OATS_INSTANCE_HOME`, `PI_AGENT_HOME` or `OATS_HOME` set finds its instance
+from the working directory. It uses the nearest enclosing directory laid out as
+`<agents-root>/<soul>/instances/<name>` whose `instance.json` records that
+name, and validates it like a home named by the environment. The walk uses the
+directory as the shell names it (`$PWD`). That matters for an attached
+instance, whose `work/` links into its owner's tree: below it, the physical
+path is the owner's. A process that has no `$PWD` there would act as the
+owner, so an attached instance runs capability commands from its home.
+
 ## Lifecycle
 
 ### Spawn

package/docs/workspaces.md

@@ -183,7 +183,7 @@ as `confirmed` or the reason it is not:
 | `not-listed` | the workspace does not list the repo |
 | `no-backlink` | no (or invalid) `oats-membership.yaml` at the member's default branch |
 | `backlink-elsewhere` | the member names a different workspace (a case-only difference is flagged: repo paths are case-sensitive identities) |
-| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout) |
+| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory), or this machine's remote cache could not be written (cache) |
 
 An unconfirmed member contributes nothing but its row: its souls are invisible,
 its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).

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) } };
+}