@awebai/oats 0.34.0 → 0.34.1

package/bin/oats.mjs

@@ -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 });
@@ -2324,8 +2325,8 @@ function retireCmd() {
   }
   // The calling instance knows its own home: self-retire never needs to
   // disambiguate a same-named twin by hand.
-  if (homeFlag === undefined && process.env.OATS_INSTANCE_HOME && (process.env.PI_AGENT_INSTANCE === name || process.env.OATS_INSTANCE === name)) homeFlag = process.env.OATS_INSTANCE_HOME;
-  const isSelf = process.env.PI_AGENT_INSTANCE === name || process.env.OATS_INSTANCE === name;
+  if (homeFlag === undefined && process.env.OATS_INSTANCE_HOME && process.env.OATS_INSTANCE === name) homeFlag = process.env.OATS_INSTANCE_HOME;
+  const isSelf = process.env.OATS_INSTANCE === name;
   if (isSelf && !args.includes("--self")) die(`"${name}" is the calling instance — self-retire is irreversible; if your task is complete and you were told to retire, re-run with --self (finish your memory files FIRST; your session dies ~8s after)`);
   if (!isSelf && args.includes("--self")) die(`--self given but "${name}" is not the calling instance`);
   const root = ensureRoot(dirFlag());
@@ -2851,9 +2852,12 @@ async function capabilityCommand() {
     let activeIds;
     let context = process.cwd();
     let teamCtx, homeMeta, homeTeamCtx;
-    // OATS_INSTANCE_HOME is the canonical identity; the older names still count. With none set
-    // (a harness that strips the session env), the home enclosing the cwd.
-    const instanceHome = process.env.OATS_INSTANCE_HOME || process.env.PI_AGENT_HOME || process.env.OATS_HOME || enclosingInstanceHome(logicalCwd());
+    // OATS_INSTANCE_HOME is the identity; OATS_HOME still counts. With neither set (a harness that
+    // strips the session env), the home enclosing the cwd. What chose the home is named in every
+    // refusal about it.
+    const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
+    const instanceHome = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
+    const chosenBy = homeVariable ?? "the working directory";
     const metaFile = instanceHome && join(instanceHome, "instance.json");
     // Capability-id keyed — never answer for `constructor`/`toString`. Belt and
     // braces: the ids come from instance.json, which spawn wrote from resolved
@@ -2872,11 +2876,19 @@ async function capabilityCommand() {
         if (!isWorkspaceHome(meta)) { const e = preWorkspaceHome(instanceHome, "nothing was dispatched"); bail(e.code, e.message); }
         context = meta.repo || context;
         soulDir = instanceSoulDir(instanceHome, meta);
+        const ws = meta.workspace && typeof meta.workspace === "object" ? meta.workspace : {};
+        // Inside a home the namespace is the home's, so a --soul for another soul is refused, never
+        // ignored (as inspect's --soul against --home is). The home's own soul, by any of its names, is fine.
+        const soulFlag = flag("soul");
+        if (soulFlag === true) bail("E_BAD_ARGS", "--soul needs a soul name", { flag: "--soul" });
+        if (typeof soulFlag === "string" && !(await import("../lib/instance-resolution.mjs")).homeSoulMatches(soulFlag, meta)) {
+          bail("E_HOME_MISMATCH", `--soul ${soulFlag} is not the soul of the instance home ${instanceHome} (${meta.agent}), which ${chosenBy} chose; to run "${cmd}" as a spawn of ${soulFlag} would, run it outside the instance home with OATS_INSTANCE_HOME and OATS_HOME unset`,
+            { home: instanceHome, soul: meta.agent, chosenBy, flag: "--soul" });
+        }
         // The team/workspace facts the home recorded at spawn, as its hooks got them, with the
         // recorded eligible teams (OATS_TEAMS_SOURCE=recorded). Only the home's MESSAGING module
         // gets them live (below): its team verbs (join/leave/teams) must see what the workspace
         // allows now, and no other command pays a remote read for them.
-        const ws = meta.workspace && typeof meta.workspace === "object" ? meta.workspace : {};
         const messaging = (meta.capabilities || []).find((c) => c.layer === "messaging")?.id;
         homeMeta = { meta, messaging };
         homeTeamCtx = (t) => teamEnv({ workspace: { key: ws.key, name: ws.name, deployment: ws.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.source });
@@ -2894,7 +2906,7 @@ async function capabilityCommand() {
     // Workspace model: an instance's own materialized modules are the command
     // namespaces available to it (instance.json.modules → <home>/.oats/modules).
     const mans = Object.values(capabilityManifests(instanceHome)).filter((m) => m.command === cmd && m.commands);
-    if (!mans.length) return NOT_DISPATCHED;
+    if (!mans.length) bail("E_UNKNOWN_COMMAND", `oats ${cmd}: no capability of the instance home ${instanceHome} (soul ${homeMeta.meta.agent}), which ${chosenBy} chose, provides "${cmd}"`, { home: instanceHome, chosenBy, namespace: cmd });
     if (mans.length > 1) bail("E_DUPLICATE_NAMESPACE", `duplicate operational command namespace "${cmd}": ${mans.map((m) => m.capability).join(", ")}`);
     const m = mans[0];
     if (!activeIds.includes(m.capability)) bail("E_CAPABILITY_INACTIVE", `${m.capability} command namespace is not active in the current context/instance`);

package/docs/execution-targets.md

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

package/docs/implementation.md

@@ -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

package/docs/knowledge.md

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

package/docs/official-catalog.md

@@ -12,7 +12,7 @@ or workspace membership alone does not make a package official.
 | `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
 | `oats.aweb` | `v1.17.5` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.4.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
 | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |

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

@@ -4,7 +4,11 @@
  * APPROACH (one approach, used for every remote kind — local bare repos and
  * https/ssh remotes alike):
  *   1. `observeRemote` resolves `at` with `git ls-remote --symref <url> …` —
- *      never a fetch when the caller already gave a full OID.
+ *      never a fetch when the caller already gave a full OID. A HEAD observation
+ *      speaks protocol v0 unless the operator pinned `protocol.version` (one round
+ *      trip instead of v2's two; what is kept of the advertisement is bounded, and a
+ *      remote over budget, or one that timed out under v0, is observed under v2:
+ *      observeLive).
  *   2. Every read (`readRemoteFile`, `listRemoteTree`, `fetchRemoteTree`) needs the
  *      commit locally. `ensureCommit` does a shallow, partial
  *      `git fetch --depth 1 --no-tags --filter=blob:limit=64k origin <oid>` into a
@@ -168,6 +172,10 @@ export const GIT_FETCH_TIMEOUT_MS = 600_000;
 /** The remote budget of a deployment read (`oats status`, `oats workspace status`): its session's `deadline` is
  *  this long after the session starts, so the command answers inside a caller's own limit (the Desktop's 30 s). */
 export const READ_REMOTE_BUDGET_MS = 12_000;
+/** What OATS keeps of a v0 ref advertisement (git's stdout, `maxBuffer`). It bounds memory, not the wire: git
+ *  reads the whole advertisement before printing it, so one over budget is transferred once, then git is killed
+ *  and the remote observed under v2, its server-side filter, from then on (observeLive). */
+export const V0_ADVERTISEMENT_BUDGET = 4 * 1024 * 1024;
 /** A session's tree index: the output budget of one `ls-tree -r -t -l -z <commit>`. */
 export const TREE_INDEX_BUDGET = 64 * 1024 * 1024;
 /** `--max-age` bounds (seconds). */
@@ -752,7 +760,7 @@ function pinRef(oid) { return `refs/oats/commits/${oid}`; }
 
 class ReadSession {
   constructor({ maxAge = 0, now = Date.now, fingerprint = null, treeIndexBudget = TREE_INDEX_BUDGET, parsedLimits = null, batchTimeoutMs = GIT_TIMEOUT_MS,
-    cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null } = {}) {
+    cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null, v0AdvertisementBudget = V0_ADVERTISEMENT_BUDGET } = {}) {
     if (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > MAX_AGE_LIMIT) throw new TypeError(`maxAge must be an integer from 0 to ${MAX_AGE_LIMIT}`);
     if (deadline !== null && !Number.isFinite(deadline)) throw new TypeError("deadline must be null or a time in Date.now() milliseconds");
     this.maxAge = maxAge;
@@ -764,6 +772,8 @@ class ReadSession {
     this.cacheWriteWaitMs = cacheWriteWaitMs; // tests shorten it: how long a write waits for another live writer of its cache
     this.fetchTimeoutMs = fetchTimeoutMs;  // tests shorten it: a fetch's own timeout
     this.deadline = deadline;              // null, or when every remote step of the command must be over (remaining())
+    this.v0AdvertisementBudget = v0AdvertisementBudget; // tests lower it: the largest v0 ref advertisement read
+    this.protocolPins = new WeakMap();     // exec → Promise<whether protocol.version is pinned> (observeLive)
     this.parsedLimits = parsedLimits;      // tests inject small prune bounds
     this.observations = new Map();         // memo key → Promise<head observation>
     this.used = new Map();                 // memo key → { observedAt, reused }: the heads this command used
@@ -853,7 +863,8 @@ class ReadSession {
 
 /** One command's read session (see the module header). `maxAge` seconds (0 = observe live). `deadline` (Date.now()
  *  milliseconds, or null): every remote step ends by then (the module header's DEADLINE). Test seams: `now`,
- *  `fingerprint`, `treeIndexBudget`, `parsedLimits`, `batchTimeoutMs`, `cacheWriteWaitMs`, `fetchTimeoutMs`. */
+ *  `fingerprint`, `treeIndexBudget`, `parsedLimits`, `batchTimeoutMs`, `cacheWriteWaitMs`, `fetchTimeoutMs`,
+ *  `v0AdvertisementBudget`. */
 export function createReadSession(options = {}) { return new ReadSession(options); }
 /** An observation the command no longer wants (its session closed, or its prefetch abandoned): never adopted
  *  by a caller that is still reading, so its shape only has to be a typed remote failure. */
@@ -1390,7 +1401,7 @@ function parseLsRemote(stdout) {
 }
 
 function resolveAt(parsed, at) {
-  if (at === undefined || at === null || at === "" || at === "HEAD") {
+  if (isHeadAt(at)) {
     const oid = parsed.oids.get("HEAD");
     return oid ? { commit: oid, ref: parsed.symrefs.get("HEAD") ?? null } : null;
   }
@@ -1434,7 +1445,7 @@ export async function observeRemote(refText, { at, ...options } = {}) {
 
 /** The `ls-remote` argv of a head observation (`at`: HEAD, a tag or a branch; never a full OID). */
 function lsRemoteArgs(ref, at) {
-  const wantHead = at === undefined || at === null || at === "" || at === "HEAD";
+  const wantHead = isHeadAt(at);
   if (!wantHead && AT_BAD_RE.test(at)) throw fail("E_REPO_REF", `at must be a full OID or a plain tag/branch name, got ${JSON.stringify(at)}`, { at });
   const args = ["ls-remote", "--symref", ref.url];
   if (wantHead) args.push("HEAD");
@@ -1518,19 +1529,115 @@ async function observeInSession(ref, args, at, options, session, prefetch = null
   } finally { session.observeDone(); }
 }
 
+/** Whether `at` asks for the remote's default branch (a HEAD observation). */
+const isHeadAt = (at) => at === undefined || at === null || at === "" || at === "HEAD";
+
+/** Whether the operator pinned `protocol.version` (env, global, system or the working directory's repo config:
+ *  `git config --get`, in the observation's own environment): asked once per command (its session) and exec, or
+ *  once per exec without a session. Unset (exit 1) → false; any value, or a read that fails otherwise (an abort
+ *  included) → true: today's argv, never an error. */
+const protocolPins = new WeakMap();
+function protocolPinned(exec, session) {
+  const memo = session?.protocolPins ?? protocolPins;
+  let pinned = memo.get(exec);
+  if (!pinned) {
+    pinned = Promise.resolve().then(() => sessionExec(exec, session, ["config", "--get", "protocol.version"], { timeout: GIT_TIMEOUT_MS, ...(session ? { signal: session.signal } : {}) }))
+      .then(() => true, (error) => error?.code !== 1);
+    memo.set(exec, pinned);
+  }
+  return pinned;
+}
+
+/** The records that a remote is observed under protocol v2 only: `<cacheRoot>/.ls-remote/<sha256(key)>.<reason>.json`,
+ *  beside the cache repos and their `.locks/` (written when no cache repo exists yet, and gone with a wiped cache
+ *  root), each { protocol: "v2", reason, recordedAt }. `overflow` (its v0 advertisement is over budget) holds for
+ *  good; `timeout` (a v0 observation timed out, which load alone can cause) for LS_REMOTE_TIMEOUT_RECORD_MS. One
+ *  file per reason, so a timeout recorded by a command already in flight never replaces a permanent overflow.
+ *  Written atomically (temp + rename) with no lock: concurrent writers of one file write the same fact. A record
+ *  that cannot be read, is corrupt or has expired is no record: v0 is tried, never an error. */
+const LS_REMOTE_TIMEOUT_RECORD_MS = 7 * 24 * 3600 * 1000;
+const lsRemoteRecordFile = (root, ref, reason) => join(root, ".ls-remote", `${sha256(ref.key)}.${reason}.json`);
+function lsRemoteV2Recorded(root, ref, now) {
+  const record = (reason) => {
+    const rec = readStoreFile(lsRemoteRecordFile(root, ref, reason));
+    return rec && typeof rec === "object" && rec.protocol === "v2" && rec.reason === reason ? rec : null;
+  };
+  if (record("overflow")) return true;
+  const rec = record("timeout");
+  const at = typeof rec?.recordedAt === "string" ? Date.parse(rec.recordedAt) : NaN;
+  return Number.isFinite(at) && at <= now + 5000 && now - at < LS_REMOTE_TIMEOUT_RECORD_MS;
+}
+function recordLsRemoteV2(root, ref, reason, now) {
+  writeAtomicQuiet(lsRemoteRecordFile(root, ref, reason), JSON.stringify({ protocol: "v2", reason, recordedAt: new Date(now).toISOString() }) + "\n");
+}
+
+/** A v0 HEAD observation's failure that is final, exactly as under v2: the remote is slow, refuses us or has no
+ *  such repository, our cache failed, or the command gave the read up. Anything else is retried under v2. */
+const V0_FINAL_REASONS = new Set(["timeout", "auth", "not-found", "cache"]);
+
+/**
+ * `ls-remote` the remote and resolve `at`. A HEAD observation (`at` HEAD or unset) speaks protocol v0 when the
+ * operator has not pinned `protocol.version` and the remote has no v2 record: one round trip, the whole ref
+ * advertisement (`-c protocol.version=0 ls-remote --symref <url>`, no pattern), resolved to exactly what v2's
+ * filtered answer gives, HEAD's symref included (v0's symref capability).
+ *   - V0_ADVERTISEMENT_BUDGET bounds what is kept (`maxBuffer`), not what crosses the wire: git reads the whole
+ *     advertisement before it prints a ref. Over budget, git is killed, the remote is observed again under v2,
+ *     recorded for good (`overflow`) and said once: an over-budget remote costs its advertisement once.
+ *   - A v0 timeout is today's error (no retry, never a second timeout), recorded for a week (`timeout`) and said.
+ *   - Any other failure in V0_FINAL_REASONS (or an abort) is today's error; any other is retried once under v2
+ *     and said once if the retry succeeds.
+ * `args` (lsRemoteArgs) stays the observation's identity everywhere (records, memo keys) and is the v2 argv; tags
+ * and branches always use it.
+ */
 async function observeLive(ref, args, at, options) {
   const exec = options.exec ?? runGit;
-  const signal = sessionOf(options)?.signal;
-  let out;
-  try { out = await sessionExec(exec, sessionOf(options), args, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}) }); }
-  catch (error) { throw unreadable(ref, error, { at: at ?? null }); }
+  const session = sessionOf(options);
+  const signal = session?.signal;
+  // Every git call takes what is left of the session's deadline, if it has one (sessionExec).
+  const run = (argv, extra = {}) => sessionExec(exec, session, argv, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}), ...extra });
+  const root = cacheRootOf(options);
+  const now = () => (session ? session.now() : Date.now());
+  const url = redactUrl(ref.url);
+  const say = (notice) => { if (session && !session.notices.includes(notice)) session.notices.push(notice); };
+  let out = null, retried = null;
+  const v0 = isHeadAt(at) && !lsRemoteV2Recorded(root, ref, now()) && !(await protocolPinned(exec, session));
+  // A command given up while its protocol was asked starts no ls-remote.
+  if (signal?.aborted) throw unreadable(ref, abortError(signal), { at: at ?? null });
+  if (v0) {
+    const budget = session?.v0AdvertisementBudget ?? V0_ADVERTISEMENT_BUDGET;
+    // A read whose timeout the command's deadline cuts (status, workspace status) may time out for that alone,
+    // which says nothing about the remote: its timeout is not recorded.
+    const cut = session ? session.remaining(GIT_TIMEOUT_MS) < GIT_TIMEOUT_MS : false;
+    try { out = await run(["-c", "protocol.version=0", "ls-remote", "--symref", ref.url], { maxBuffer: budget }); }
+    catch (error) {
+      if (error?.overflowed === true || error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+        recordLsRemoteV2(root, ref, "overflow", now());
+        say(`${url} sends a ref advertisement over ${formatBytes(budget)}; OATS observes it with protocol v2`);
+      } else {
+        const reason = classifyRemoteFailure(error);
+        const aborted = error?.code === "ABORT_ERR" || signal?.aborted;
+        if (!aborted && reason === "timeout" && !cut) {
+          recordLsRemoteV2(root, ref, "timeout", now());
+          say(`${url} timed out under protocol v0; OATS observes it with protocol v2 for 7 days`);
+        }
+        if (aborted || V0_FINAL_REASONS.has(reason)) throw unreadable(ref, error, { at: at ?? null });
+        retried = reason;
+      }
+    }
+  }
+  if (!out) {
+    try { out = await run(args); }
+    catch (error) { throw unreadable(ref, error, { at: at ?? null }); }
+  }
   const parsed = parseLsRemote(out.stdout);
   const hit = resolveAt(parsed, at);
   if (!hit) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} has no ref matching ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
   if (!OID_RE.test(hit.commit)) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} returned a non-OID for ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
   const { commit } = await ensureCommit(ref, hit.commit, options);
+  if (retried) say(`${url} failed under protocol v0 (${retried}); observed with protocol v2`);
   return { key: ref.key, url: ref.url, commit, ref: hit.ref, observedAt: new Date().toISOString() };
 }
+const formatBytes = (n) => (n % (1024 * 1024) === 0 ? `${n / (1024 * 1024)} MiB` : `${n} bytes`);
 
 // ---------------------------------------------------------------------------
 // tree reading

package/package-catalog.json

@@ -28,7 +28,7 @@
     },
     "oats.engineering": {
       "url": "https://github.com/awebai/oats-engineering.git",
-      "ref": "v1.4.0",
+      "ref": "v1.5.0",
       "path": "oats-package"
     },
     "oats.framework": {

package/package.json

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