@awebai/oats 0.34.0 → 0.34.2

package/docs/souls-and-instances.md

@@ -129,7 +129,7 @@ full copy** of every capability the soul resolved to:
   .oats/modules/<capability>/      # the whole capability: oats.json, bin/, injects/, skills/ (hooks run from here)
   .oats/bin/oats → <kernel>/bin/oats.mjs  # the kernel that last launched this home: first on the harness's PATH
   work/                            # worktree, checkout symlink, attached tree, or private directory
-  TASK.md                          # briefing and task
+  TASK.md                          # briefing and task (0600; the home itself is 0700)
   instance.json                    # provenance (below); `soulDir` = the soul directory hooks get as OATS_SOUL
   STATE.md, log.md, notes/         # optional, from the knowledge capability
 ```
@@ -152,8 +152,8 @@ composed skills and instructions, a spawn records:
       "commit": "3f2a9c1e…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.118Z"
     },
     "oats.okf": {
-      "from": { "kind": "package", "package": "oats.okf", "version": "4.0.5", "commit": "26d8216f…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
-      "commit": "26d8216f…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
+      "from": { "kind": "package", "package": "oats.okf", "version": "4.0.6", "commit": "2a62df8e…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
+      "commit": "2a62df8e…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
     }
   },
   "providers": {
@@ -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

@@ -55,7 +55,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
 
 packages:                                  # the ONLY versioned things
   oats.framework: v1.4.1                   # bare version → resolves through the official catalog
-  oats.okf: v4.0.5
+  oats.okf: v4.0.6
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # SHARED teams: the same provider team for everyone
@@ -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/canonical-json.mjs

@@ -103,6 +103,8 @@ export function canonicalJson(value, options) {
   return chunks.join("");
 }
 
+/** The 1-based line of character `offset` in `text`: where a reader's error points. */
+export function lineAt(text, offset) { return text.slice(0, offset).split("\n").length; }
 /** JSON.parse alone cannot detect duplicate decoded keys. This small JSON
  * decoder preserves that check and budgets; YAML must use it for JSON input,
  * not maintain another permissive JSON reader. Objects have null prototypes. */
@@ -114,7 +116,7 @@ export function parseStrictJson(input, options) {
   }
   const text = decodeUtf8(data);
   let at = 0, entries = 0;
-  const bad = () => { throw oatsError("invalid-declaration", `invalid JSON at character ${at}`); };
+  const bad = () => { throw oatsError("invalid-declaration", `invalid JSON at character ${at}`, { offset: at }); };
   const space = () => { while (at < text.length && /[\x20\t\r\n]/.test(text[at])) at++; };
   const string = () => {
     const start = at++;

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/config-data.mjs

@@ -3,7 +3,7 @@
  * Legacy core readers are unchanged until the explicit consumer migration. */
 import { Composer, CST, Lexer, Parser, isAlias, isMap, isScalar, isSeq } from "yaml";
 import { bytesIntegrity } from "./digest.mjs";
-import { byteView, canonicalJson, dataLimits, decodeUtf8, parseStrictJson } from "./canonical-json.mjs";
+import { byteView, canonicalJson, dataLimits, decodeUtf8, lineAt, parseStrictJson } from "./canonical-json.mjs";
 import { oatsError } from "./errors.mjs";
 
 const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
@@ -71,7 +71,9 @@ export function parseConfigData(input, { format = "auto", origin = null, limits:
     }
     if (document.errors.length || document.warnings.length || document.directives.yaml.version !== "1.2") {
       const issue = document.errors[0] ?? document.warnings[0];
-      throw oatsError("invalid-declaration", `invalid portable YAML${issue ? ` (${issue.code})` : " version"}`);
+      const offset = issue?.pos?.[0];
+      const line = Number.isInteger(offset) ? lineAt(source, offset) : undefined;
+      throw oatsError("invalid-declaration", `invalid portable YAML${issue ? ` (${issue.code}${line ? ` at line ${line}` : ""})` : " version"}`);
     }
     const decode = (node, pointer, depth) => {
       mark(pointer, depth, node);

package/lib/core.mjs

@@ -63,7 +63,7 @@ import { validateBindingInterface } from "./provider-binding.mjs";
 /** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home). */
 export { fingerprintTree };
 
-import { canonicalJson, parseStrictJson } from "./canonical-json.mjs";
+import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
 import { readPortableBytes } from "./bounded-read.mjs";
 import { copyTreeSafe } from "./tree-copy.mjs";
 /** The package and capability id grammar (namespaced, lowercase): an id names a
@@ -89,6 +89,10 @@ function capabilityAgentDirs(root) {
   return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".") && !RESERVED.has(e.name) && !existsSync(join(root, e.name, "soul", "soul.yaml")))
     .map((e) => ({ name: e.name, dir: join(root, e.name) }));
 }
+/** The names of the non-hidden directories in `d` ([] when it cannot be read). */
+function subdirs(d) {
+  try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; }
+}
 /** What OATS 0.25 left under <scope>/local-agents/ (and the nested <root>/local-agents|
  *  tmp-agents) for the agents root `root`: one `legacy-local-agents` problem naming the
  *  instance homes there, or null. Names only — nothing there is read, spawned into or
@@ -97,7 +101,6 @@ export function legacyLocalAgents(root) {
   if (!root) return null;
   const bases = [join(dirname(root), LEGACY_LOCAL_AGENTS_DIR), join(root, LEGACY_LOCAL_AGENTS_DIR), join(root, "tmp-agents")];
   const dirs = [], instances = [];
-  const subdirs = (d) => { try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; } };
   for (const base of bases) {
     let st; try { st = lstatSync(base); } catch { continue; }
     if (!st.isDirectory()) continue;
@@ -109,12 +112,32 @@ export function legacyLocalAgents(root) {
   return { code: "legacy-local-agents", dirs, instances,
     message: `${instances.length} instance home${instances.length === 1 ? "" : "s"} under local-agents/ ${instances.length === 1 ? "is" : "are"} from OATS 0.25 and ${instances.length === 1 ? "is" : "are"} not managed by this kernel; retire ${instances.length === 1 ? "it" : "them"} with the 0.25 kernel or delete the directory once ${instances.length === 1 ? "it is" : "they are"} stopped${instances.length ? ` (${instances.join(", ")})` : ""}` };
 }
+/** The instance homes under the agents root `root` (a directory <root>/<agent>/instances/<name>
+ *  whose instance.json records that name) that other users on the machine can read or enter (any
+ *  group or other permission bit): one `home-readable` problem naming them, with the exact chmod,
+ *  or null. A home holds identity keys, TASK.md and transcripts; spawn creates it 0700. Only
+ *  reported: the operator decides. */
+export function readableInstanceHomes(root) {
+  if (!root) return null;
+  const homes = [];
+  for (const agent of subdirs(root)) for (const name of subdirs(join(root, agent, "instances"))) {
+    const home = join(root, agent, "instances", name);
+    try {
+      if (JSON.parse(readFileSync(join(home, "instance.json"), "utf8"))?.instance !== name) continue;
+      if (lstatSync(home).mode & 0o077) homes.push(home);
+    } catch { /* no readable instance.json, or gone meanwhile: not a home */ }
+  }
+  if (!homes.length) return null;
+  homes.sort();
+  const fix = `chmod 700 ${homes.map(shq).join(" ")}`;
+  return { code: "home-readable", homes, fix,
+    message: `${homes.length} instance home${homes.length === 1 ? " can" : "s can"} be read by other users on this machine (${homes.length === 1 ? "it holds" : "they hold"} identity keys, TASK.md and transcripts); fix: ${fix}` };
+}
 /** The captured homes (the 0.24–0.25 captured/portable path, removed in 0.26) under the
  *  agents root `root`: one `legacy-captured-home` problem naming them, or null. They have
  *  no 0.26 runtime (start, inspect and in-home commands refuse them); retire still works. */
 export function legacyCapturedHomes(root) {
   if (!root) return null;
-  const subdirs = (d) => { try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; } };
   const homes = [];
   for (const agent of subdirs(root)) for (const inst of subdirs(join(root, agent, "instances"))) {
     const home = join(root, agent, "instances", inst);
@@ -883,11 +906,21 @@ function readCatalogFile() {
   // catalog belongs to the kernel install.
   const override = !!process.env.OATS_PACKAGE_CATALOG;
   if (!existsSync(file)) { if (override) recordLocalInput(file, null); return empty; }
-  let doc;
   const text = readFileSync(file, "utf8");
   if (override) recordLocalInput(file, text);
+  return parsePackageCatalog(text, file);
+}
+/** A package catalog's text, parsed and checked as the kernel reads it (named `file` in errors):
+ *  { packages, capabilities, file }, both maps null-prototype; invalid-source when it is broken. */
+export function parsePackageCatalog(text, file) {
+  let doc;
   try { doc = JSON.parse(text); }
-  catch (e) { throw oatsError("invalid-source", `broken package catalog ${file}: ${e.message}`); }
+  catch (e) {
+    // JSON.parse does not say where; the kernel's strict reader (same grammar) locates the error.
+    let line;
+    try { parseStrictJson(text, { maxBytes: 64 * 1024 * 1024 }); } catch (s) { if (Number.isInteger(s.provenance?.offset)) line = lineAt(text, s.provenance.offset); }
+    throw oatsError("invalid-source", `broken package catalog ${file}${line ? ` (line ${line})` : ""}: ${e.message}`);
+  }
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw oatsError("invalid-source", `broken package catalog ${file}: root must be a JSON object`);
   const out = { packages: Object.create(null), capabilities: Object.create(null), file };
   const packages = doc.packages;
@@ -2082,6 +2115,12 @@ export function upgradeHomeMeta(meta, home) {
   return { ...rest, ...(runtime !== undefined || meta.harness !== undefined ? { harness: meta.harness ?? runtime } : {}), ...(meta.launch !== undefined ? { launch: upgradeLaunchRecipe(meta.launch) } : {}) };
 }
 const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
+/** The fixed prompt a codex launch starts with: it names the task file, never its text (argv is
+ *  readable by every local user). Codex reads the file with a tool. */
+export const CODEX_TASK_PROMPT = "Read TASK.md in this directory first: it is your briefing and your task.";
+/** The prompt each harness gets, so the task's text never travels in argv: Claude Code inlines an
+ *  `@file` mention; codex is pointed at the file. pi takes `@TASK.md` among its own arguments. */
+const TASK_PROMPT = Object.freeze({ claude: "@TASK.md", codex: CODEX_TASK_PROMPT });
 
 /** The executable a launch uses: a configuration's declared one (a bare name
  *  on PATH; a path against the deployment directory when relative) or the
@@ -2354,7 +2393,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];
@@ -2362,7 +2401,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
   }
   let cmdline;
   if (harness === "claude") {
-    cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
+    cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- ${shq(TASK_PROMPT.claude)}`;
   } else if (harness === "codex") {
     const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
     // Codex may run tool commands outside the session's process (its shared app-server daemon),
@@ -2370,7 +2409,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
     // never goes on argv, and PATH is the execution's (CODEX_TOOL_PATH: the shim first).
     const toolEnvArgs = env.filter((e) => !e.reference && e.name !== "PATH")
       .map((e) => ` -c ${shq(`shell_environment_policy.set.${e.name}=${JSON.stringify(e.value)}`)}`).join("");
-    cmdline = `${shq(executable)} --cd ${shq(home)} -c check_for_update_on_startup=false${yolo ? " --yolo" : ""}${yolo || trustHome ? ` -c ${shq(codexTrust)}` : ""}${toolEnvArgs}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
+    cmdline = `${shq(executable)} --cd ${shq(home)} -c check_for_update_on_startup=false${yolo ? " --yolo" : ""}${yolo || trustHome ? ` -c ${shq(codexTrust)}` : ""}${toolEnvArgs}${model ? ` --model ${shq(model)}` : ""}${tail} -- ${shq(TASK_PROMPT.codex)}`;
   } else {
     // Decision 13: pi starts NORMALLY — its own skill discovery (~/.pi/agent/skills,
     // .agents/skills up the tree, so the instance's copied capability skills are
@@ -2387,7 +2426,7 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
  * with the home's kernel shim first on PATH (every launch runs through here). */
 function nativeRecordCommand(command, home, harness) {
   const { tokens, binary } = parseLaunchCommand(command);
-  const args = tokens.slice(binary + 1).filter(t => t.kind !== "prompt").map(t => t.value ?? t.text);
+  const args = tokens.slice(binary + 1).map(t => t.value ?? t.text);
   const id = prepareNativeStart(home, harness);
   const recorder = join(PKG_ROOT, "packages", "record", "bin", "record-native-start.mjs");
   const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(harness)} ${shq(JSON.stringify(args))} && exec ${executionArgv(tokens, binary, harness).join(" ")}`;
@@ -2561,7 +2600,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 +2759,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
@@ -3102,7 +3141,8 @@ function* spawnBody(root, agent, o = {}) {
   // apply of the same decision, or anything else) got here first, and this one
   // has touched nothing.
   mkdirSync(dirname(home), { recursive: true });
-  try { mkdirSync(home); }
+  // 0700: the home holds the instance's identity keys, TASK.md and transcripts.
+  try { mkdirSync(home, { mode: 0o700 }); }
   catch (e) {
     if (e?.code === "EEXIST") throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} already exists at ${home} (a concurrent spawn won the placement); nothing was created by this call`), { instance, home });
     throw e;
@@ -3606,7 +3646,7 @@ You are instance "${instance}" of agent "${agent.name}".
 - Home: ${home}
 - Work tree: ./work — ${workDesc}
 - Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${harness === "codex" ? "\n## Harness notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
-${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`);
+${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`, { mode: 0o600 }); // human text: the owner's only
 
     // Launch command. Spawn IS session start: the recipe is persisted in
     // instance.json beside its rendering, which is executed in the instance's
@@ -4564,8 +4604,18 @@ export function inputInstanceSession(home, text) {
 
 // ---------------------------------------------------------------- session start
 
-/** The exact prompt token spawn renders for claude and codex launches. */
+/** The prompt token of a recorded claude or codex command that hands the harness the task's own
+ *  text in argv, where any local user can read it: `"$(cat TASK.md)"`. It is parsed, and replaced
+ *  when the home starts (withSafeTaskPrompt). */
 const LAUNCH_PROMPT_TOKEN = '"$(cat TASK.md)"';
+/** A recorded command with its harness's safe task prompt: a `"$(cat TASK.md)"` token becomes
+ *  TASK_PROMPT[harness]. Applied when a home starts from its recorded command, which is saved so. */
+export function withSafeTaskPrompt(command, harness) {
+  const { tokens } = parseLaunchCommand(command);
+  if (!tokens.some((t) => t.kind === "prompt")) return command;
+  if (!Object.hasOwn(TASK_PROMPT, harness)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `a ${harness} command never carried the task as "$(cat TASK.md)"; inspect the saved command in instance.json`);
+  return renderLaunchCommand(tokens.map((t) => t.kind === "prompt" ? { kind: "word", value: TASK_PROMPT[harness], quoted: true, text: shq(TASK_PROMPT[harness]) } : t));
+}
 
 /** Tokenize a persisted OATS launch command. The grammar is exactly what
  *  spawn renders: space-separated tokens that are env assignments NAME='v',
@@ -5004,6 +5054,8 @@ export function startInstanceSession(home, o = {}) {
       command = withLaunchModel(command, resolved);
       model = resolved; explicitModelFrom = "start";
     } else parseLaunchCommand(command);
+    // A recorded command starts, and is saved, with its harness's safe task prompt.
+    if (!launchPlan) command = withSafeTaskPrompt(command, harness);
     // References recorded for this home must resolve on this host on every
     // start path, and the source variables go to the pane, not the command.
     const recipeForEnv = launchPlan?.recipe || (meta.launch && typeof meta.launch === "object" ? meta.launch : null);
@@ -5098,7 +5150,7 @@ export function startInstanceSession(home, o = {}) {
     }
     target = { backend: "tmux", session, window, socket: resolve(socket) };
     // Keep launch evidence until the command exits or the target disappears.
-    // A transient child (for example cat TASK.md) is not proof that startup
+    // A transient child (for example the native-start recorder) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.
     try { return { ...record(meta, { id, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false), warnings }; }
     catch (e) {

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/lib/workspace.mjs

@@ -334,8 +334,9 @@ function schemaHint(kind, value) {
   }
   return "";
 }
-/** Parse + validate a declaration file → { value } | { problems }. Never throws. */
-function readDeclaration(kind, bytes, origin, validateOptions) {
+/** Parse + validate a declaration file (`kind` workspace | membership | soul | local) → { value } |
+ *  { problems }. Never throws. The reader `oats sync` uses, exported for the repository's validate. */
+export function readDeclaration(kind, bytes, origin, validateOptions) {
   const decoded = decodeDocument(bytes, origin);
   if (decoded.problems) return decoded;
   const problems = FILE_KINDS[kind].validate(decoded.value, validateOptions);