@awebai/oats 0.33.0 → 0.34.1

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/release-notes/v0.34.1.md

@@ -0,0 +1,57 @@
+# OATS 0.34.1
+
+## Changed
+
+- **Reading a remote's current head takes one round trip instead of two.**
+  `oats spawn` (preview and apply) and the read verbs ask each workspace
+  member for its head with Git's protocol v0, which returns the whole ref list
+  in one request, where protocol v2 takes two. On a 6-member deployment the
+  live phase of a spawn preview went from 0.77 s to 0.49 s (median of 5). Tags
+  and branches are read as before. If your Git configuration sets
+  `protocol.version`, OATS uses it as set. A remote whose ref list is over
+  4 MiB is read with protocol v2 from then on (remembered in the remote
+  cache). A remote that times out under v0 fails as before and is read with
+  v2 for the next 7 days; a read ended by the 12 s budget of `oats status` or
+  `oats workspace status` is not counted as the remote's timeout. One that
+  fails under v0 for another reason than an
+  authentication refusal, a missing repository or the local cache is read
+  again with v2. Each case is one `oats: warning`. What a read observes is
+  unchanged, and an apply still observes every member live. Known limit: the
+  4 MiB bounds what OATS keeps, not what Git downloads, so a remote with a
+  larger ref list transfers it once before OATS switches to protocol v2.
+- **oats.engineering 1.5.0** (catalog and workspace pin, and the bundled
+  mirrors): developers keep each dynamic workflow under 10 agents and ask
+  their human for permission first for more. Within the cap they run
+  workflows without asking where the harness allows it; where it requires the
+  human's opt-in (Claude Code's workflow tool does), they use a standing
+  opt-in the human configured, or ask once per task.
+- **The `oats-setup-admin` soul has knowledge and is harvested.** It drops
+  `oats.developer` and `knowledge: none` and takes the workspace's oats.okf
+  knowledge slot, owning the new `oats/oats-setup-admin` node (the judgement
+  of administering a workspace's config, never deployment state) and reading
+  the operator, expert and kernel nodes. This reverses the 0.29.1 opt-out:
+  deployment specifics are kept out of the base at promotion, by the node's
+  charter and the reviewed harvest PR, instead of by not harvesting the soul.
+  It needs `oats/oats-setup-admin` in the bound `oats` base
+  (awebai/oats-knowledge#51); new instances only.
+
+- **`PI_AGENT_INSTANCE` and `PI_AGENT_HOME` are gone.** No launch sets them,
+  for any harness, pi included. (A home that records only its launch command,
+  from before launch recipes, keeps running that command as recorded.) The identity is `OATS_INSTANCE` and
+  `OATS_INSTANCE_HOME`, and the pi bridge (`@awebai/oats-pi`) reads
+  `OATS_INSTANCE_HOME`.
+  - Upgrade the CLI and the pi bridge together (`oats update` does both). A
+    0.34.0 pi bridge under a 0.34.1 kernel does not find its instance home.
+  - Capability commands no longer read `PI_AGENT_HOME`. A leftover one in an
+    operator's shell no longer pins a command to that instance.
+  - The names stay reserved: a launch configuration still cannot set them.
+
+## Fixed
+
+- **A capability command inside an instance home says which home, and why.**
+  - A `--soul` naming another soul than the home's was silently ignored; it
+    is now refused with `E_HOME_MISMATCH`.
+  - A namespace the home does not have answered `unknown command`; it is now
+    `E_UNKNOWN_COMMAND` naming the home.
+  - Both name what chose the home: `OATS_INSTANCE_HOME`, `OATS_HOME` or the
+    working directory.

package/docs/souls-and-instances.md

@@ -245,8 +245,7 @@ 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`;
+- the instance: `OATS_INSTANCE`, `OATS_INSTANCE_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
@@ -258,9 +257,9 @@ 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
+A capability command (`oats <namespace> …`) runs in the instance home that
+`OATS_INSTANCE_HOME` names, else `OATS_HOME`. With neither set, it 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
@@ -268,6 +267,13 @@ 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.
 
+Inside an instance home the namespace is that home's. A `--soul` naming
+another soul is refused (`E_HOME_MISMATCH`), and a namespace the home does
+not have is `E_UNKNOWN_COMMAND`. Both name the home and what chose it (the
+variable, or the working directory). To run a command as a spawn of another
+soul would, run it from the deployment with `OATS_INSTANCE_HOME` and
+`OATS_HOME` unset.
+
 ## Lifecycle
 
 ### Spawn
@@ -561,9 +567,10 @@ Every instance is told its own home as **`OATS_INSTANCE_HOME`** (absolute), and
 instructions refer to it as `<instance-home>`. The two environments differ, so
 they are stated separately:
 
-- **Runtime session**: `OATS_INSTANCE_HOME` and `PI_AGENT_HOME` (plus
-  `OATS_INSTANCE`/`PI_AGENT_INSTANCE`). The `PI_`-prefixed names are
-  compatibility aliases for the separately published pi extension.
+- **Runtime session**: `OATS_INSTANCE_HOME` and `OATS_INSTANCE`, for every
+  harness. The pi extension reads `OATS_INSTANCE_HOME` too; the `PI_AGENT_*`
+  names are not set (they stay reserved, so a launch configuration cannot set
+  them).
 - **Lifecycle hooks**: `OATS_INSTANCE_HOME` and `OATS_HOME`, alongside the rest of
   the hook contract. `OATS_HOME` predates `OATS_INSTANCE_HOME` and is kept because
   shipped capability hooks read it; it is **not** exported to harness sessions.

package/docs/workspaces.md

@@ -174,7 +174,18 @@ from *outside* that boundary, and **declaring one in the workspace's
 access context.** The kernel reads both halves over the remotes
 (`git ls-remote`, shallow fetches, the operator's own credential helpers,
 never a prompt). A half that cannot be read makes the member *unconfirmed*,
-never a half-success. `oats workspace status` and `oats sync` show each member
+never a half-success. A remote's current head is read with Git's protocol v0
+(one round trip) unless your Git configuration sets `protocol.version`, which
+is then used as set; a tag or branch is read as before. A remote whose v0 ref
+advertisement is over 4 MiB is read with protocol v2 from then on: the 4 MiB
+bounds what OATS keeps, not the download, so the first read transfers that
+advertisement once before falling back. A remote that times out under v0
+fails as before and is read with protocol v2 for the next 7 days; a read
+ended by the 12 s budget of `oats status` or `oats workspace status` is not
+the remote's own timeout, and is neither remembered nor warned about. One that
+fails under v0 for another reason than an authentication refusal, a missing
+repository or the local cache is read again with v2. Each case prints one
+`oats: warning`; the first two are remembered in the remote cache. `oats workspace status` and `oats sync` show each member
 as `confirmed` or the reason it is not:
 
 | status | meaning |

package/lib/capability-contract.mjs

@@ -13,7 +13,7 @@
 export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch"]);
 export const PORTABLE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 export const CAPABILITY_ENV_ID_RE = /^[a-z][a-z0-9]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
-export const CORE_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]);
+export const CORE_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME"]);
 export const PROCESS_BOOTSTRAP_ENV = new Set([
   "PATH", "HOME", "SHELL", "TMPDIR", "TMP", "TEMP", "PWD", "OLDPWD", "SHLVL", "_",
   "ENV", "BASH_ENV", "BASHOPTS", "SHELLOPTS", "CDPATH", "IFS", "PROMPT_COMMAND", "PS4", "ZDOTDIR",

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/core.mjs

@@ -2354,7 +2354,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
   // The launch's environment, in prefix order: the instance, the capabilities' env, the
   // configuration's env (a reference by reference, never by value).
   const hookEnv = recipe.hooks?.env || {};
-  const env = [["OATS_INSTANCE", instance], ["OATS_INSTANCE_HOME", home], ["PI_AGENT_INSTANCE", instance], ["PI_AGENT_HOME", home]].map(([name, value]) => ({ name, value }));
+  const env = [["OATS_INSTANCE", instance], ["OATS_INSTANCE_HOME", home]].map(([name, value]) => ({ name, value }));
   for (const name of Object.keys(hookEnv).sort()) env.push({ name, value: redact ? "<redacted>" : hookEnv[name] });
   for (const name of Object.keys(recipe.env || {}).sort()) {
     const v = recipe.env[name];
@@ -2561,7 +2561,7 @@ export function describeLaunchCommand(command) {
  *  stay references); a command the parser refuses is withheld whole. */
 /** The identity environment every launch carries: public facts (instance
  *  name, home path), shown in public renderings; everything else is withheld. */
-export const IDENTITY_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]);
+export const IDENTITY_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME"]);
 export function redactLaunchCommand(command) {
   try { return parseLaunchCommand(command).tokens.map((t) => t.kind === "env" && !IDENTITY_LAUNCH_ENV.has(t.name) ? `${t.name}='<redacted>'` : t.text).join(" "); }
   catch { return "<unparseable launch command withheld>"; }
@@ -2720,7 +2720,7 @@ function* spawnBody(root, agent, o = {}) {
   // decision: an attached agent shares its owner's work tree and is ALWAYS the
   // owner's child — relation flags that say anything else are contradictory and
   // rejected. Ambient env
-  // (OATS_INSTANCE/PI_AGENT_INSTANCE) is deliberately NOT consulted: any shell
+  // (OATS_INSTANCE) is deliberately NOT consulted: any shell
   // opened inside an agent's tmux window inherits those vars, and env inheritance
   // is not evidence of intent — human spawns from such shells were misattributed
   // as instance-origin. Manual spawns land top-level unless a relation is

package/lib/instance-resolution.mjs

@@ -85,21 +85,43 @@ export function qualifiedSoulName(entry) {
   return `${memberNameOf(entry?.repoKey ?? "")}/${entry?.name}`;
 }
 
+/** A soul name as an operator gives it: `[repoPart, soulPart]`, repoPart null for a bare name. */
+function splitSoulName(name) {
+  return name.includes("/") && !name.startsWith("/") ? [name.slice(0, name.lastIndexOf("/")), name.slice(name.lastIndexOf("/") + 1)] : [null, name];
+}
+/** Whether `name` names the member or package soul `{ name, repoKey }` / `{ name, package }`: a
+ *  bare name, `<repo>/<soul>` with the member's key, a key suffix or its member name, or
+ *  `<package>/<soul>` for a package soul. findSoulEntry's rule for each candidate. */
+export function soulNameMatches(name, soul) {
+  const [repoPart, soulPart] = splitSoulName(name);
+  if (soulPart !== soul.name) return false;
+  if (!repoPart) return true;
+  if (typeof soul.package === "string") return repoPart === soul.package;
+  const key = soul.repoKey ?? "";
+  return key === repoPart || key.endsWith(repoPart) || memberNameOf(key) === repoPart;
+}
+/** Whether `name` names the soul an instance home was spawned from (its instance.json `meta`): any name
+ *  a spawn accepts for it, or the home's agent directory name. */
+export function homeSoulMatches(name, meta) {
+  if (name === meta?.agent) return true;
+  const soul = meta?.workspace?.soul ?? {};
+  return soulNameMatches(name, soul.package && typeof soul.package === "object" ? { name: soul.name, package: soul.package.id } : { name: meta?.agent, repoKey: soul.repoKey });
+}
+
 /** Find the soul named `name` in a discovery: confirmed members, external souls and package
  *  souls. A bare name must be unique across all three (else E_SOUL_AMBIGUOUS naming each
  *  qualified form); `<repo>/<soul>` names a member (its key, a key suffix or its member name)
  *  or an external source, `<package>/<soul>` a package soul. */
 export function findSoulEntry(discovery, name) {
-  const [repoPart, soulPart] = name.includes("/") && !name.startsWith("/") ? [name.slice(0, name.lastIndexOf("/")), name.slice(name.lastIndexOf("/") + 1)] : [null, name];
+  const [repoPart, soulPart] = splitSoulName(name);
   const hits = [];
   // A standalone view's one row is the repo's own (unconfirmed by definition — the
   // workspace could not be read); resolveSoul admits exactly that case.
   const standaloneOwn = discovery.standalone === true ? discovery.key : null;
-  const memberMatches = (key) => !repoPart || key === repoPart || key.endsWith(repoPart) || memberNameOf(key) === repoPart;
   for (const m of discovery.members || []) {
     if (!m.confirmed && m.key !== standaloneOwn) continue;
     for (const s of m.souls || []) {
-      if (s.name !== soulPart || !memberMatches(m.key)) continue;
+      if (!soulNameMatches(name, { name: s.name, repoKey: m.key })) continue;
       hits.push({ ...s, repoKey: m.key, memberCommit: m.commit, external: false });
     }
   }
@@ -107,7 +129,7 @@ export function findSoulEntry(discovery, name) {
     if (x.soul?.name === soulPart && (!repoPart || (x.source && String(x.source).includes(repoPart)))) hits.push({ ...x.soul, repoKey: x.soul.repoKey ?? parseRepoRef(x.source.replace(/@.*$/, "")).key, commit: x.commit, external: true });
   }
   for (const s of discovery.packageSouls || []) {
-    if (s.name === soulPart && (!repoPart || repoPart === s.package)) hits.push({ ...s, external: false });
+    if (soulNameMatches(name, { name: s.name, package: s.package })) hits.push({ ...s, external: false });
   }
   if (hits.length === 0) throw err("E_SOUL_UNKNOWN", `no soul ${JSON.stringify(name)} among the confirmed members, external souls or package souls of this workspace`, { name, members: (discovery.members || []).filter((m) => m.confirmed).map((m) => m.key), packages: [...new Set((discovery.packageSouls || []).map((s) => s.package))].sort() });
   if (hits.length > 1) {

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) => {