@awebai/oats 0.34.0 → 0.34.2

package/bin/oats.mjs

@@ -30,7 +30,7 @@ import {
   LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
-  findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
   writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
@@ -391,7 +391,7 @@ async function workspaceTarget(bail, { command, liveTeams = true }) {
     try { meta = JSON.parse(readFileSync(join(homeFlag, "instance.json"), "utf8")); } catch (e) { return bail("E_SESSION_UNKNOWN", `${homeFlag} is not an OATS instance home (${e.code === "ENOENT" ? "no instance.json" : e.message})`); }
     if (isCapturedHome(meta)) { const e = capturedHomeRefusal(homeFlag, "nothing was read"); return bail(e.code, e.message, e.details); }
     if (!meta || typeof meta.modules !== "object" || meta.modules === null) return bail("E_UNSUPPORTED_MODE", `${homeFlag} is not a workspace-model home (it records no modules): it was spawned by an earlier kernel — re-spawn it from the deployment`);
-    if (soulFlag && soulFlag !== meta.agent) return bail("E_HOME_MISMATCH", `--soul ${soulFlag} is not the soul of ${homeFlag} (${meta.agent})`);
+    if (soulFlag && !(await import("../lib/instance-resolution.mjs")).homeSoulMatches(soulFlag, meta)) return bail("E_HOME_MISMATCH", `--soul ${soulFlag} is not the soul of ${homeFlag} (${meta.agent})`);
     const deployment = dirname(dirname(dirname(dirname(realOrResolved(homeFlag)))));
     // A v2 home lives at <deployment>/agents/<soul>/instances/<name>: its deployment is
     // derived, so it must hold oats-local.yaml EXACTLY there (never found by walking up).
@@ -537,8 +537,9 @@ async function workspaceOperation(t, { bail, address, layer, opName }) {
   const settings = lp.settings;
   const cwd = op.context === "home" ? t.home : t.deployment;
   const env = { ...lp.env(mod.name, settings), OATS_OPERATION: address, OATS_CONTEXT: t.deployment, OATS_ROOT: t.agentsRoot, PI_AGENTS_ROOT: t.agentsRoot };
-  if (op.context === "home") Object.assign(env, { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home, OATS_HOME: t.home, PI_AGENT_INSTANCE: t.meta.instance, PI_AGENT_HOME: t.home });
-  else for (const k of ["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]) delete env[k];
+  // The home's identity, never one inherited from the caller (the reserved PI_AGENT_* names included).
+  for (const k of ["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]) delete env[k];
+  if (op.context === "home") Object.assign(env, { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home, OATS_HOME: t.home });
   await readSession?.closeBatches(); // no idle `git cat-file --batch` child held for the provider's whole run
   const r = spawnSync("node", [abs, ...rest, ...argFlags, "--json"], { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 16 * 1024 * 1024, timeout: OPERATION_TIMEOUT_MS, killSignal: "SIGTERM" });
   finishOperation({ r, bail, address, provider, op, argFlags, cwd, home: t.home, meta: t.meta, api: INSPECT_OPERATIONS_API });
@@ -582,7 +583,8 @@ function legacyLayoutProblems(root) {
 }
 async function doctorWorkspaceJson(ctx, soulName, ws) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
-  const problems = legacyLayoutProblems(join(dirname(ws.local.path), "agents"));
+  const agentsRoot = join(dirname(ws.local.path), "agents");
+  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean);
   return {
     schemaVersion: 1, workspaceApi: 2, context: ctx,
     workspace: { file: ws.local.path, ref: ws.local.workspace },
@@ -621,7 +623,8 @@ async function doctor(dir) {
   doctorVersionSkew();
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg) => die(`${msg} [${code}]`));
   printDoctorWorkspace(ws);
-  for (const p of legacyLayoutProblems(join(dirname(ws.local.path), "agents"))) console.log(`\n! ${p.code}: ${p.message}`);
+  const agentsRoot = join(dirname(ws.local.path), "agents");
+  for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
   if (soulName) {
     const information = operationalKnowledgeNote(composition, soulName);
     if (information) console.log(`\nINFO: ${information}`);
@@ -768,11 +771,11 @@ function launchPreview(bail) {
     instance = meta.instance || basename(home);
     if (!(meta.launch && typeof meta.launch === "object") && !selectionGiven) {
       // A home that predates recipes, asked nothing: its frozen command is
-      // described as is. Under a selection the planner refuses it
-      // (E_LAUNCH_LEGACY: re-spawn it from the deployment).
-      let d;
-      try { d = describeLaunchCommand(meta.command); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
-      jsonOk({ context, selected, selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(meta.command), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
+      // described as a start runs it (with its harness's safe task prompt). Under a
+      // selection the planner refuses it (E_LAUNCH_LEGACY: re-spawn it from the deployment).
+      let d, frozen;
+      try { frozen = withSafeTaskPrompt(meta.command, meta.harness); d = describeLaunchCommand(frozen); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
+      jsonOk({ context, selected, selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
       return;
     }
     const agentsRoot = agentsRootOfHome(home);
@@ -2324,8 +2327,8 @@ function retireCmd() {
   }
   // The calling instance knows its own home: self-retire never needs to
   // disambiguate a same-named twin by hand.
-  if (homeFlag === undefined && process.env.OATS_INSTANCE_HOME && (process.env.PI_AGENT_INSTANCE === name || process.env.OATS_INSTANCE === name)) homeFlag = process.env.OATS_INSTANCE_HOME;
-  const isSelf = process.env.PI_AGENT_INSTANCE === name || process.env.OATS_INSTANCE === name;
+  if (homeFlag === undefined && process.env.OATS_INSTANCE_HOME && process.env.OATS_INSTANCE === name) homeFlag = process.env.OATS_INSTANCE_HOME;
+  const isSelf = process.env.OATS_INSTANCE === name;
   if (isSelf && !args.includes("--self")) die(`"${name}" is the calling instance — self-retire is irreversible; if your task is complete and you were told to retire, re-run with --self (finish your memory files FIRST; your session dies ~8s after)`);
   if (!isSelf && args.includes("--self")) die(`--self given but "${name}" is not the calling instance`);
   const root = ensureRoot(dirFlag());
@@ -2837,23 +2840,32 @@ async function capabilityCommand() {
     if (!hit) return NOT_DISPATCHED;
     // The same team/workspace facts a spawn hook receives (lead decision c3-7).
     const teamCtx = teamEnv(resolvedFromPrepared(hit.prepared, hit.deployment));
-    // No home, so no recorded soul: the soul's per-commit copy is OATS_SOUL when a spawn
-    // already fetched exactly this commit; otherwise the command gets none (never ambient).
-    // The agent directory is the soul entry's own (a package soul's is `<package>--<soul>`), never
-    // the bare name, which a same-named member soul's copy may occupy (as instance-inspect does).
-    const { agentDirOf } = await import("../lib/instance-resolution.mjs");
-    const entry = hit.prepared?.soulEntry;
-    const cachedSoul = entry?.commit ? join(hit.deployment, "agents", agentDirOf(entry), "souls", String(entry.commit).slice(0, 12)) : null;
-    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, { settings: hit.settings, origins: hit.resolution?.payloadOrigins?.[hit.module.name] }, teamCtx, hit.ensureTree, cachedSoul && existsSync(join(cachedSoul, "soul.yaml")) ? realpathSync(cachedSoul) : undefined);
+    // No home, so no recorded soul: OATS_SOUL is the soul's source at the resolved commit, read
+    // as a spawn preview reads it (the per-commit copy a spawn left under the agents root, else a
+    // temporary fetch removed when the command ends). Read only when the command runs (after its
+    // --help). A soul that cannot be read refuses the command: it never runs with OATS_SOUL unset.
+    const soul = async () => {
+      const { previewWorkspaceSoul } = await import("../lib/instance-resolution.mjs");
+      const entry = hit.prepared?.soulEntry;
+      try { const p = await previewWorkspaceSoul(hit.prepared, join(hit.deployment, "agents")); return { dir: p.soulDir, cleanup: p.cleanup }; }
+      catch (e) {
+        throw Object.assign(new Error(`oats ${cmd}: cannot read soul ${flag("soul")} at ${String(entry?.commit ?? "?").slice(0, 12)}, so the command would run without OATS_SOUL; nothing was run: ${e.message}`),
+          { code: typeof e?.code === "string" && e.code.startsWith("E_") ? e.code : "E_REMOTE_UNREADABLE", details: { soul: flag("soul"), repoKey: entry?.repoKey ?? null, commit: entry?.commit ?? null } });
+      }
+    };
+    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, { settings: hit.settings, origins: hit.resolution?.payloadOrigins?.[hit.module.name] }, teamCtx, hit.ensureTree, soul);
   }
 
   async function dispatch() {
     let activeIds;
     let context = process.cwd();
     let teamCtx, homeMeta, homeTeamCtx;
-    // OATS_INSTANCE_HOME is the canonical identity; the older names still count. With none set
-    // (a harness that strips the session env), the home enclosing the cwd.
-    const instanceHome = process.env.OATS_INSTANCE_HOME || process.env.PI_AGENT_HOME || process.env.OATS_HOME || enclosingInstanceHome(logicalCwd());
+    // OATS_INSTANCE_HOME is the identity; OATS_HOME still counts. With neither set (a harness that
+    // strips the session env), the home enclosing the cwd. What chose the home is named in every
+    // refusal about it.
+    const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
+    const instanceHome = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
+    const chosenBy = homeVariable ?? "the working directory";
     const metaFile = instanceHome && join(instanceHome, "instance.json");
     // Capability-id keyed — never answer for `constructor`/`toString`. Belt and
     // braces: the ids come from instance.json, which spawn wrote from resolved
@@ -2872,11 +2884,19 @@ async function capabilityCommand() {
         if (!isWorkspaceHome(meta)) { const e = preWorkspaceHome(instanceHome, "nothing was dispatched"); bail(e.code, e.message); }
         context = meta.repo || context;
         soulDir = instanceSoulDir(instanceHome, meta);
+        const ws = meta.workspace && typeof meta.workspace === "object" ? meta.workspace : {};
+        // Inside a home the namespace is the home's, so a --soul for another soul is refused, never
+        // ignored (as inspect's --soul against --home is). The home's own soul, by any of its names, is fine.
+        const soulFlag = flag("soul");
+        if (soulFlag === true) bail("E_BAD_ARGS", "--soul needs a soul name", { flag: "--soul" });
+        if (typeof soulFlag === "string" && !(await import("../lib/instance-resolution.mjs")).homeSoulMatches(soulFlag, meta)) {
+          bail("E_HOME_MISMATCH", `--soul ${soulFlag} is not the soul of the instance home ${instanceHome} (${meta.agent}), which ${chosenBy} chose; to run "${cmd}" as a spawn of ${soulFlag} would, run it outside the instance home with OATS_INSTANCE_HOME and OATS_HOME unset`,
+            { home: instanceHome, soul: meta.agent, chosenBy, flag: "--soul" });
+        }
         // The team/workspace facts the home recorded at spawn, as its hooks got them, with the
         // recorded eligible teams (OATS_TEAMS_SOURCE=recorded). Only the home's MESSAGING module
         // gets them live (below): its team verbs (join/leave/teams) must see what the workspace
         // allows now, and no other command pays a remote read for them.
-        const ws = meta.workspace && typeof meta.workspace === "object" ? meta.workspace : {};
         const messaging = (meta.capabilities || []).find((c) => c.layer === "messaging")?.id;
         homeMeta = { meta, messaging };
         homeTeamCtx = (t) => teamEnv({ workspace: { key: ws.key, name: ws.name, deployment: ws.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.source });
@@ -2894,7 +2914,7 @@ async function capabilityCommand() {
     // Workspace model: an instance's own materialized modules are the command
     // namespaces available to it (instance.json.modules → <home>/.oats/modules).
     const mans = Object.values(capabilityManifests(instanceHome)).filter((m) => m.command === cmd && m.commands);
-    if (!mans.length) return NOT_DISPATCHED;
+    if (!mans.length) bail("E_UNKNOWN_COMMAND", `oats ${cmd}: no capability of the instance home ${instanceHome} (soul ${homeMeta.meta.agent}), which ${chosenBy} chose, provides "${cmd}"`, { home: instanceHome, chosenBy, namespace: cmd });
     if (mans.length > 1) bail("E_DUPLICATE_NAMESPACE", `duplicate operational command namespace "${cmd}": ${mans.map((m) => m.capability).join(", ")}`);
     const m = mans[0];
     if (!activeIds.includes(m.capability)) bail("E_CAPABILITY_INACTIVE", `${m.capability} command namespace is not active in the current context/instance`);
@@ -2905,14 +2925,14 @@ async function capabilityCommand() {
       const live = await liveTeams(instanceHome, homeMeta.meta, { remoteOptions: remoteOptionsFromEnv() });
       teamCtx = homeTeamCtx(live);
     }
-    return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, soulDir);
+    return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, () => ({ dir: soulDir, cleanup: () => {} }));
   }
 
   /** Help / unknown-command / spec validation / exec — shared by every context.
    *  `m` is the manifest (with `capability`; `_dir` may be absent until `ensureDir`
    *  resolves the directory holding the executable — the operator branch fetches
    *  the module tree only when a command is actually going to run). */
-  async function runManifestCommand(m, { settings, origins }, teamCtx, ensureDir, soulDir) {
+  async function runManifestCommand(m, { settings, origins }, teamCtx, ensureDir, soul) {
     const sub = args[1];
     const cmds = Object.keys(m.commands);
     // `oats <ns> --help` and `oats <ns> <cmd> --help` answer from the manifest
@@ -2946,6 +2966,11 @@ async function capabilityCommand() {
     try { abs = capabilityExecutablePath(withDir, script); }
     catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
     if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
+    // The soul the command acts for → { dir, cleanup }: a home's recorded soul directory, or (operator
+    // dispatch) the soul read at its resolved commit, whose temporary copy goes when this process exits.
+    let soulDir;
+    try { const read = await soul(); soulDir = read.dir; process.once("exit", read.cleanup); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
     // OATS_SOUL is the recorded soul or nothing: an ambient value inherited from the
     // invoking process names some other soul (a coordinator's own), never this one.
     const { OATS_SOUL: _ambientSoul, ...inherited } = process.env;

package/docs/capabilities.md

@@ -533,7 +533,12 @@ passed as arguments; no shell is involved.
   - `OATS_SOUL`, the soul directory: a home's recorded one, or for a soul
     (`readiness --soul`, `inspect --soul`) its copy at the resolved commit,
     which the kernel materialises first as a spawn would (0.30; a copy that
-    cannot be made fails readiness under `installed`, producer `soul copy`);
+    cannot be made fails readiness under `installed`, producer `soul copy`).
+    An operator command (`oats <namespace> … --soul <name>` from the
+    deployment) gets the soul's source at the resolved commit too: the copy a
+    spawn left under the agents root, else a temporary copy removed when the
+    command ends. A soul that cannot be read refuses the command; it never
+    runs without `OATS_SOUL`;
   - for a home, `OATS_INSTANCE` and `OATS_INSTANCE_HOME`.
 - `OATS_TEAM_SCOPE` is the deployment directory; `OATS_TEAM_NAME` is always
   empty.

package/docs/desktop-cli-api.md

@@ -723,7 +723,7 @@ Read-only (it writes no lock):
              "souls":["rm"],"capabilities":["nw-house-style"],"publishes":null,"url":"https://github.com/nw/agents/tree/66566512…",
              "membershipFile":{"path":"oats-membership.yaml","url":"https://github.com/nw/agents/blob/66566512…/oats-membership.yaml"}}],
  "packages":[{"id":"oats.okf","version":"3.0.0","source":"catalog:oats.okf","commit":"ab897841…","integrity":"sha256-bada35…",
-              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.0.5","ref":"v4.0.5"}}],
+              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.0.6","ref":"v4.0.6"}}],
  "declaredPackages":["oats.framework","oats.okf"],"unsynced":["oats.framework"],"stale":[],
  "external":[{"source":"git:github.com/oss/experts@3c606e09…","soul":"security-reviewer"}],
  "problems":[],"warnings":[],
@@ -782,8 +782,8 @@ packages' capabilities and souls, sorted by name, then origin. Both carry
     "defaultTeam":{"label":"mine","team":"mine:ana.aweb.ai","from":"deployment"},
     "private":false,"path":"souls/writer","work":"directory","description":"Drafts campaigns.","harness":"pi","model":null,"harnessFrom":"kernel-default",
     "file":{"path":"souls/writer/soul.yaml","url":null},"spawnable":true,"problem":null},
-   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.0.5","kind":"package","package":"oats.okf",
-    "version":"4.0.5","repoKey":"github.com/awebai/oats-okf","commit":"26d8216f…","teams":null,"defaultTeam":null,"private":false,
+   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.0.6","kind":"package","package":"oats.okf",
+    "version":"4.0.6","repoKey":"github.com/awebai/oats-okf","commit":"2a62df8e…","teams":null,"defaultTeam":null,"private":false,
     "path":"oats-package/souls/knowledge-maintainer","work":"directory","description":"Reviews harvested knowledge.","harness":"pi","model":null,
     "harnessFrom":"kernel-default","file":{"path":"oats-package/souls/knowledge-maintainer/soul.yaml","url":null},
     "spawnable":false,"problem":{"code":"E_TEAM_UNKNOWN","message":"team \"reviewers\" is not declared (oats-local.yaml#/souls/teams/…)"}}],
@@ -872,8 +872,8 @@ nothing reads a working clone.
 **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",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.0.6",
+ "commit":"2a62df8e…","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}],
@@ -899,7 +899,7 @@ nothing reads a working clone.
 **The `--file` answer:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"26d8216f…",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"2a62df8e…",
  "file":{"path":"skills/okf-instance-knowledge/SKILL.md","bytes":4787,"text":"---\nname: okf-instance-knowledge\n…","binary":false,"truncated":false}}
 ```
 

package/docs/execution-targets.md

@@ -13,8 +13,8 @@ home. To run them on another machine, see [servers.md](servers.md).
 | Harness | `--harness` | Launched as |
 |---|---|---|
 | pi | `pi` (the default) | `pi --append-system-prompt <home>/AGENTS.md --approve --name <instance> [--model m] @TASK.md` |
-| Claude Code | `claude` | `claude [--model m] -- "$(cat TASK.md)"` |
-| Codex | `codex` | `codex --cd <home> [--model m] -- "$(cat TASK.md)"` |
+| Claude Code | `claude` | `claude [--model m] -- '@TASK.md'` |
+| Codex | `codex` | `codex --cd <home> [--model m] -- 'Read TASK.md in this directory first: it is your briefing and your task.'` |
 
 Each harness starts in the instance home with its own native settings,
 authentication and skill discovery. The command line also carries the
@@ -27,9 +27,9 @@ named launch configuration (`--launch-config <name>`); see
 [configuration.md](configuration.md#launch-configurations).
 `--model @native-default` uses the harness's own default model.
 
-The launch command sets `OATS_INSTANCE`, `OATS_INSTANCE_HOME`,
-`PI_AGENT_INSTANCE` and `PI_AGENT_HOME`, plus the environment that the launch
-configuration and capabilities contribute. The home's layout and what those
+The launch command sets `OATS_INSTANCE` and `OATS_INSTANCE_HOME`, plus the
+environment that the launch configuration and capabilities contribute. No
+`PI_AGENT_*` name is set, for any harness. The home's layout and what those
 variables point at are described in
 [souls-and-instances.md](souls-and-instances.md#instance-anatomy).
 
@@ -166,6 +166,18 @@ and `restart`, opens a new harness conversation on `TASK.md`. The instance
 resumes its work from its own state files, as its knowledge capability
 prescribes.
 
+The task's text never travels on a command line, where any local user could
+read it in the process list:
+
+- pi and Claude Code get `@TASK.md`, which each harness reads as the file.
+- Codex gets a fixed pointer to the file and reads it with a tool.
+- A home whose recorded command still hands over `"$(cat TASK.md)"` starts
+  with its harness's safe prompt instead, and the command is saved that way.
+
+The home is created `0700` and `TASK.md` `0600`. `oats doctor` reports an
+instance home that other users can read (`home-readable`), with the exact
+`chmod`; it never changes a home's mode itself.
+
 ## Permissions (yolo)
 
 Yolo is chosen per launch: `--yolo` / `--no-yolo` on `oats spawn`,

package/docs/implementation.md

@@ -72,6 +72,27 @@ Every CLI command owns one read session (`createReadSession` in
 CLI closes it when the command ends). A library caller without a session
 gets the plain per-call behaviour. Within a session:
 
+- a HEAD observation speaks protocol v0 when the operator has not pinned
+  `protocol.version` (`git config --get`, read once per command): the whole
+  ref advertisement in one round trip, resolved exactly as v2's filtered
+  answer. `V0_ADVERTISEMENT_BUDGET` (4 MiB, git's `maxBuffer`) bounds what
+  is kept, not the transfer: git reads the whole advertisement before it
+  prints a ref, so a remote over budget costs its advertisement once, then
+  git is killed, the remote observed again under v2 and recorded. A v0
+  timeout stays today's error (no retry) and is recorded too, unless the
+  session's `deadline` cut that read's timeout (the deadline, not the remote,
+  may have ended it). The
+  v0 read and its `protocol.version` check go through `sessionExec` like every
+  other git call. The record is
+  `<cacheRoot>/.ls-remote/<sha256(key)>.<reason>.json`, `{ protocol: "v2",
+  reason: "overflow" | "timeout", recordedAt }`, one file per reason (an
+  in-flight timeout never replaces an overflow), written atomically with no lock;
+  `overflow` is permanent, `timeout` expires after 7 days, and an unreadable,
+  corrupt or expired record is no record (v0 is tried). Another v0 failure
+  that is not final (auth, not-found, cache, an abort) is retried once under
+  v2. Each is a session notice. The v2 argv (`lsRemoteArgs`) stays the
+  observation's identity: records and memo keys do not depend on the
+  protocol;
 - a head is observed once per (cache repo, ref), and a commit peeled once; at
   most eight observations run at once (`OBSERVE_LIMIT`), each holding its slot
   for all its git work (the `ls-remote` and the fetch of the commit it names,
@@ -107,7 +128,8 @@ gets the plain per-call behaviour. Within a session:
   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
+  (`readBudgetMs`; `OATS_READ_REMOTE_BUDGET_MS` is a test and ops override,
+  not a contract). Every
   remote step then gets what is left of it instead of its own default: each
   git call's timeout (`sessionExec`: ls-remote, fetch, ls-tree, the cache's
   plumbing; none starts once nothing is left), the git version probe
@@ -203,7 +225,7 @@ scaling by call count.
 | `npm test` | every suite under `test/` (`node --test`), through `scripts/run-tests.mjs` |
 | `npm run check` | syntax of every shipped file |
 | `npm run check:pi` | the pi adapter's TypeScript |
-| `npm run validate` | the JSON schemas, the example manifests and configs, and every local link and anchor in the public docs |
+| `npm run validate` | the JSON schemas, the example manifests and configs, every local link and anchor in the public docs, the repository's own `oats-workspace.yaml` and `package-catalog.json` read by the kernel's readers, and no unresolved merge-conflict marker in a tracked text file (`scripts/check-workspace-files.mjs`) |
 | `npm run pack:check` | an `npm pack` dry run of both packages: nothing missing, nothing leaked |
 | `npm run smoke:tarball` | installs the packed tarballs outside the checkout and exercises them |
 

package/docs/integrations.md

@@ -40,8 +40,8 @@ arrives from.
 ```yaml
 # oats-workspace.yaml: one default per slot, for every soul
 packages:
-  oats.okf: v4.0.5
-  oats.aweb: v1.17.5
+  oats.okf: v4.0.6
+  oats.aweb: v1.17.6
   oats.linear: v1.0.1
   oats.jira: v1.0.1
 defaults:

package/docs/knowledge.md

@@ -26,7 +26,7 @@ The workspace pins the package and fills the slot for every soul by default:
 ```yaml
 # oats-workspace.yaml (excerpt)
 packages:
-  oats.okf: v4.0.5
+  oats.okf: v4.0.6
 defaults:
   knowledge: { oats.okf: { from: package } }
 stores:
@@ -220,10 +220,13 @@ identical copies in both role capabilities.
 - **From an instance home**, `oats okf …` runs the home's copy of the module
   with the settings recorded at spawn.
 - **From the deployment directory** (holding `oats-local.yaml`), in a shell
-  without another instance's `OATS_*` identity, every capability command
-  needs `--soul <name>` (`E_BAD_ARGS` without it). The kernel resolves the
+  where neither `OATS_INSTANCE_HOME` nor `OATS_HOME` is set (either one pins
+  the command to that instance home), every capability command needs
+  `--soul <name>` (`E_BAD_ARGS` without it). Inside an instance home, a
+  `--soul` naming another soul is refused (`E_HOME_MISMATCH`). The kernel resolves the
   soul as a spawn would, fetches its module at the locked commit into
-  `<deployment>/.oats/modules/` and runs it with the soul's merged settings.
+  `<deployment>/.oats/modules/` and runs it with the soul's merged settings
+  and `OATS_SOUL`, the soul's source at that commit.
   An unlocked package is `E_PACKAGE_MISSING` until `oats sync`.
 
 ### Consult

package/docs/official-catalog.md

@@ -10,9 +10,9 @@ or workspace membership alone does not make a package official.
 | package | release | capabilities | package souls |
 |---|---|---|---|
 | `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
-| `oats.okf` | `v4.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.17.5` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.4.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.okf` | `v4.0.6` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
+| `oats.aweb` | `v1.17.6` | `oats.aweb` (messaging) | |
+| `oats.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
 | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
@@ -27,7 +27,7 @@ no lock and adds nothing to an existing workspace.
 ## Find and use packages
 
 - A workspace pins an official package by **bare version** in its
-  `packages:` map (`oats.okf: v4.0.5`); `oats sync` resolves it through the
+  `packages:` map (`oats.okf: v4.0.6`); `oats sync` resolves it through the
   catalog to an exact commit, fetches it, verifies its integrity and locks it.
   A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
   not join a team or adopt the publisher's workspace. See

package/docs/packages.md

@@ -44,14 +44,14 @@ whole organisation:
 
 ```yaml
 packages:
-  oats.okf: v4.0.5                                    # bare version → the official catalog
+  oats.okf: v4.0.6                                    # bare version → the official catalog
   acme.tools: git:github.com/acme/tools@v0.4.0        # direct ref: git:<repo>@<tag or full OID>
 ```
 
-- **Bare version** (`v4.0.5`, `4.0.5`, `1.0.0-rc.1`): the id is looked up in
+- **Bare version** (`v4.0.6`, `4.0.6`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.0.5` or `oats-framework/v1.4.1`) and the payload path. An id
+  convention (`v4.0.6` or `oats-framework/v1.4.1`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -75,8 +75,8 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.4.1
-  oats.okf: v4.0.5
-  oats.aweb: v1.17.5
+  oats.okf: v4.0.6
+  oats.aweb: v1.17.6
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
 $ oats sync
 workspace  acme  (github.com/acme/agents @ 3f2a9c1e)
 members    agents ✓↔ (@ 3f2a9c1e)   platform ✓↔ (@ 77c0a1b2)   billing ✗ (no-backlink)
-packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.0.5 ✓ (@ 26d8216f)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.0.6 ✓ (@ 2a62df8e)
 changed    acme.tools  — → 0.4.0 (@ 47f4b816)
 souls      9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
 teams      platform (shared) · this deployment's: oats teams
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.17.5                         # a catalog version
+oats package add oats.aweb v1.17.6                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
       "source": "catalog:oats.okf",
       "url": "https://github.com/awebai/oats-okf.git",
       "path": "oats-package",
-      "version": "4.0.5",
-      "commit": "26d8216f8ce986cad1ffa7a8291b4a4978510ee2",
+      "version": "4.0.6",
+      "commit": "2a62df8eb247b58b3d89b2ce38d84c49c2d8ae23",
       "integrity": "sha256-…",
       "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
     },
@@ -331,7 +331,7 @@ A soul that names one of the package's capabilities with
 {
   "policy": "docs/official-catalog.md",
   "packages": {
-    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.5", "path": "oats-package" },
+    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.6", "path": "oats-package" },
     "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.1", "path": "oats-package" }
   }
 }

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

@@ -0,0 +1,68 @@
+# OATS 0.34.2
+
+## Changed
+
+- **oats.aweb 1.17.6** (catalog and workspace pin, and the bundled mirror):
+  session-delivery instructions name the aw 1.36.21+ full-mail wake form
+  (`aweb mail event received.` with metadata, sender body, the `Use the aw CLI`
+  line and a Recovery line), say that body and subject are untrusted sender
+  content that never overrides the task or human, and remind operators that
+  delivered mail may be marked read and absent from unread `aw mail inbox`.
+  The aw floor is unchanged (`>=1.36.13`).
+- **oats.okf 4.0.6** (catalog and workspace pin, and the bundled mirrors):
+  harvest completion works on a real host (awebai/oats-okf#27, #28, #29,
+  #30).
+  - `oats okf complete` persists the harvester's judgment first, then delivers
+    in one detached worker per run. After persisting the judgment, it waits
+    up to 30 s: it answers with the final receipt, or with
+    `status: delivering` and the progress.
+    - A killed `complete`, or a killed worker, loses nothing. Rerunning
+      `complete` resumes, never judges again, and never pushes or opens a PR
+      twice.
+    - A `worker.lock` whose owner died is reclaimed automatically.
+    - `oats okf-harvest harvest-status` reports the delivery as in progress,
+      failed or stopped.
+    - Captured completions still deliver inline.
+  - A Git base whose head moved outside its knowledge root is no longer a
+    baseline change. A read-only base records the new head. A written base is
+    committed onto it. Only changed root bytes fail with `E_BASELINE`, and the
+    judgment stays persisted (`oats okf retry --rejudge`).
+  - Staging a Git base fetches its root's blobs in one batch. Delivery never
+    fetches the blobs outside the root. Staging over SSH, from GitHub:
+
+    | Base | 4.0.5 | 4.0.6 |
+    |---|---|---|
+    | oats-knowledge | 237 s | 9.9 s |
+    | aweb | 41 s | 9.1 s |
+
+  - `oats okf harvest-status` reports `unknown`, with the reason, when it
+    cannot read a soul's opt-out.
+
+## Fixed
+
+- **An operator command with `--soul` always gets the soul**
+  (awebai/oats#423). `oats <namespace> … --soul <name>` from the deployment
+  passed `OATS_SOUL` only when a spawn had already fetched that soul at the
+  resolved commit, so `oats okf harvest-status --soul <s>` reported harvest
+  "off" for a soul no spawn had fetched yet. The soul is now read at the
+  resolved commit as a spawn preview reads it: the copy a spawn left, else a
+  temporary copy removed when the command ends. A soul that cannot be read
+  refuses the command; it never runs without `OATS_SOUL`.
+
+- **A task's text no longer appears in the process list** (awebai/oats#427).
+  Claude Code and Codex instances were launched with the whole `TASK.md` as a
+  command-line argument, which any local user can read. Now:
+  - Claude Code gets `@TASK.md` (it reads the file).
+  - Codex gets a fixed instruction to read `TASK.md`.
+  - A home recorded the old way starts with the safe prompt, and its saved
+    command is updated.
+  - New instance homes are created `0700` and `TASK.md` `0600`.
+  - `oats doctor` reports a home other users can read (`home-readable`) with
+    the exact `chmod`. Existing homes are not changed: run that `chmod`.
+
+- **`npm run validate` catches a broken workspace file** (a development
+  check). It reads the repository's own `oats-workspace.yaml` and
+  `package-catalog.json` with the kernel's readers, and fails on an unresolved
+  merge-conflict marker in any tracked text file, naming the file and the
+  line. A conflicted `oats-workspace.yaml` had passed check, validate, pack
+  and smoke. The kernel's YAML and catalog errors now name the line too.