@awebai/oats 0.30.2 → 0.30.3

package/bin/oats.mjs

@@ -27,7 +27,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, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, 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, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
   writeFileAtomic, LOCK_FILE, readLock, writeLock, resolvePackages, memoizedRemote,
@@ -1792,6 +1792,9 @@ async function status() {
       console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : i.running ? "RUNNING" : "idle"}  (branch ${i.branch || "?"}, ${i.work || "?"})`);
       const key = i.home ?? `${a.name}/${i.instance}`;
       if (i.identity) console.log(`          identity: ${servedIdentityLine(i.identity)}`);
+      // The kernel the home's plain `oats` runs (its last launch's), when it is not this one.
+      const launchedBy = i.home ? recordedKernelBin(i.home) : null;
+      if (typeof launchedBy === "string" && (verbose || launchedBy !== CLI_BIN)) console.log(`          kernel: ${launchedBy}${launchedBy !== CLI_BIN ? " (not this oats)" : ""}`);
       const s = ws?.soul.get(key);
       if (s && (verbose || s.status !== "current")) console.log(`          ${soulDriftLine(s, a.name)}`);
       const rows = ws?.drift.get(key) || [];
@@ -1803,6 +1806,31 @@ async function status() {
   }
 }
 
+/** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
+ *  `--instance` is refused by a local spawn (with its replacement) but still travels to an older
+ *  host through `--server`, whose route reads it. */
+const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "herdr-socket", "idempotency-key", "instance", "launch-config", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
+const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
+/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
+ *  soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
+ *  flag() reads it; a missing value is the flag's own check. */
+function spawnArgvProblem(argv) {
+  const soul = argv[0];
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--provider") { i += 2; continue; }
+    if (a.startsWith("--")) {
+      const name = a.slice(2);
+      if (SPAWN_SWITCHES.has(name)) continue;
+      if (!SPAWN_VALUE_FLAGS.has(name)) return `oats spawn: unknown flag ${a}`;
+      if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
+      continue;
+    }
+    if (/^[A-Za-z0-9_.-]+=/.test(a)) return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: a capability setting is given as --provider <capability> key=value (here: --provider <capability> ${a})`;
+    return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: spawn takes one soul`;
+  }
+  return undefined;
+}
 async function spawnCmd() {
   // JSON mode: contract envelope, stable error codes, stderr-only progress.
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -1831,6 +1859,7 @@ async function spawnCmd() {
   // The slug rule is checked here too, before any side effect (soul fetch).
   if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
   if (args.includes("--ephemeral")) bail("E_BAD_ARGS", "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics");
+  { const problem = spawnArgvProblem(args.slice(1)); if (problem) bail("E_BAD_ARGS", problem); }
   let root;
   // A spawn needs a workspace deployment (lead decision c3-1): no oats-local.yaml
   // in reach is E_LOCAL_MISSING, before anything else is read. The agents root is
@@ -3084,6 +3113,12 @@ async function serverRouteCmd() {
     const r = spawnSyncProc(route.argv[0], route.argv.slice(1), { stdio: "inherit" });
     process.exit(r.status ?? 1);
   }
+  // A spawn's argv is checked here, before the server is contacted.
+  if (cmd === "spawn") {
+    const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
+    const problem = spawnArgvProblem(local);
+    if (problem) bail("E_BAD_ARGS", problem);
+  }
   // Everything after the command word travels, minus the routing flags; a
   // local --task-file is read here and travels as --task text, since the
   // remote cannot read this machine's files.

package/docs/configuration.md

@@ -151,10 +151,27 @@ source variable must be set on the host (`E_LAUNCH_ENV_MISSING`, before
 anything is created or stopped), and only the harness's pane receives it.
 `list` and `preview` redact every environment value, literals included.
 
+**The instance's `oats`.** Every launch (`oats spawn`, `session start`,
+`session restart`, locally or through `--server`) writes `<home>/.oats/bin/oats`,
+a link to the launching kernel's `bin/oats.mjs`, and runs the harness with
+`<home>/.oats/bin` first on `PATH` and the rest of `PATH` unchanged. Plain
+`oats` inside an instance is therefore the kernel that launched it, even on a
+machine whose `PATH` finds another kernel first. A launch configuration's own
+`PATH` (literal or `fromEnv`) comes after it. A restart by a different kernel
+re-points the link to that kernel; `spawn --no-launch` writes it too. The
+recipe in `instance.json` records the target as `launch.kernelBin` (no JSON
+answer carries it); `oats status` prints it
+(`kernel:`) under `--verbose`, or when it is not the `oats` running the status.
+A launch that cannot write the link fails with `E_LAUNCH_SHIM` naming the path
+and the cause: a spawn is rolled back, a start starts nothing. The recorded
+`command` does not carry the `PATH`; the kernel adds it when it runs the
+command. Hooks still receive `OATS_CLI_BIN`, unchanged.
+
 **The launch recipe.** A spawn records what a start is made of in
 `instance.json` under `launch`: the harness, the configuration and where it
 came from, the executable, args, env, model, yolo, and each capability's
-launch contribution with its settings and trust. One renderer turns it into
+launch contribution with its settings and trust, and the kernel that launched
+it (`kernelBin`, re-written by every start). One renderer turns it into
 the `command`. Configuration `args` go after the harness's own options and
 before capability arguments; every argument is single-quoted.
 

package/docs/desktop-cli-api.md

@@ -1157,6 +1157,9 @@ it to a temporary copy (`soulFetched: true`).
   repeatable, `a.b=c` nests): a malformed pair is `E_BAD_ARGS`; a capability
   the soul does not resolve is `E_CAPABILITY_MISSING {capability, soul,
   modules}`.
+- Any other positional after the soul, or a flag spawn does not read, is
+  `E_BAD_ARGS` naming the argument, before anything is resolved; a bare
+  `key=value` is refused with the `--provider <capability> key=value` form.
 
 ### The decision
 
@@ -1239,7 +1242,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 
 | Code | Details | When |
 |---|---|---|
-| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory or removed flags |
+| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul |
 | `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
 | `E_SOUL_UNKNOWN` | `{name, members, packages}` | no such soul, or not at `--agents-root` |
 | `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
@@ -1262,6 +1265,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
 | `E_SPAWN_INCOMPLETE` | `{instance, home, launched}` | |
 | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
+| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
 | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
 | `E_SPAWN_FAILED` | | anything else |
 
@@ -1670,8 +1674,9 @@ selection flags. See [the start workflow](desktop-instance-start.md).
 - A lost response does not mean the launch failed: check status before a
   retry. A remote home's saved route names its execution host.
 - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
-  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*`,
-  `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
+  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
+  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
+  started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
 
 ### Upload
 

package/docs/execution-targets.md

@@ -59,9 +59,15 @@ id distinguishes a replacement occupant of the same pane.
   (default `~/.config/...`) and starts `herdr --session oats server` if no
   server is running there.
 - The adapter speaks the Herdr socket API at an explicit protocol version,
-  with no negotiation. New sessions use protocol 20. A recorded session target
-  may carry protocol 20 or 22, and each call checks that the server's snapshot
-  reports the recorded protocol.
+  20 or 22. A new session records the protocol its server reports (20 for
+  Herdr 0.8, 22 for 0.9) and refuses any other; before 0.30.3 it always
+  selected 20, so Herdr 0.9 could not be spawned on. A recorded target is
+  never renegotiated: each call, the kernel's and the Desktop's, checks that
+  the server's snapshot reports the recorded protocol.
+- Herdr cannot give a pane a command at creation, so OATS types the launch
+  command into the pane's shell. It waits until the shell has drawn its prompt
+  (`herdr pane read`, at most 10 s): text typed earlier is cut at the
+  terminal's line-buffer limit.
 
 ## Lifecycle
 

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

@@ -0,0 +1,75 @@
+# OATS 0.30.3
+
+## Changed
+
+- **Desktop: the whole app works from the keyboard, with a Linux-sane keymap.**
+  Changed Linux and Windows defaults: the command palette is now Ctrl+Shift+P
+  on Linux and Windows; close tab Ctrl+Shift+W; split Ctrl+Shift+E /
+  Ctrl+Shift+O (close the split Ctrl+Shift+Alt+W); Spawn instance
+  Ctrl+Shift+N; the theme cycle has no default chord (on macOS too; the palette
+  keeps it). No default chord takes a key a program in the terminal reads:
+  plain Ctrl+W, Ctrl+K, Ctrl+\, Ctrl+P and Ctrl+B, F6, Alt+digit and
+  Ctrl+PgUp/PgDn (and ⌃digits on macOS) always reach the program, and nothing
+  binds Super. New: go to tab (⌥⌘1–⌥⌘9 / Alt+1–Alt+9), Ctrl+PgDn / Ctrl+PgUp,
+  ⌘3 / Ctrl+3 for Automations, and F6 / Shift+F6 to move between the sidebar,
+  the instances, the main area and the instance panel; from a terminal,
+  ⇧⌘F6 / Ctrl+Shift+F6 leaves it for the next region. Your own rebinds are
+  kept; one that now clashes with another shortcut is flagged in the shortcuts
+  editor, never changed for you. Quick Open (⌘P / Ctrl+P)
+  now opens the spawn dialog for the soul you pick, and Esc takes you back to
+  where you were; ⌘↵ / Ctrl+Enter spawns from any field, and Tab walks the
+  form in the order you see it. Keyboard gaps found in an audit are closed:
+  roster rows of unknown state, Independent nodes in the Active overview, the
+  Automations row menu, the schedule form and focus lost after switching tabs
+  or views. The keymap and the audit are in
+  `packages/desktop/docs/desktop-keyboard.md`.
+- **Desktop: the spawn dialog says why each capability is there.** In "What
+  will be created", each Capabilities row shows a muted reason tag beside its
+  source: **Soul**, **Workspace default**, or, for a workspace default that
+  fills a core slot, **Workspace default · messaging** (knowledge, messaging or
+  tasks). It is the preview's `composedFrom`, read only from a CLI that reports
+  `preview-composed-from`; with an older CLI the rows show no tag, never a
+  guess. The Core capabilities table is unchanged.
+- **Desktop: clearer overview lines, a centred rail, pinned Workspace controls.**
+  The Active overview draws parent links as smooth curves from a parent's
+  bottom to its child's top, with dashed arcs between siblings, in a colour
+  that is visible in every theme. The collapsed instance panel's icons sit
+  on its centre line. In Workspace, the Capabilities section pills and search
+  and the Teams header stay in view while the content scrolls, and scrolling
+  to the end of a list no longer moves the whole window.
+
+## Fixes
+
+- **Plain `oats` inside an instance is the kernel that launched it.** On a
+  machine with two kernels side by side (a global 0.24 for classic
+  deployments and a 0.30 prefix install), an agent typing `oats` got whatever
+  `PATH` found first: `oats aweb teams` answered `E_UNKNOWN_COMMAND` in a 0.30
+  home. Every launch (spawn, `session start`, `session restart`) now writes
+  `<home>/.oats/bin/oats`, a link to the launching kernel, and runs the harness
+  with `<home>/.oats/bin` first on `PATH`. A restart by another kernel
+  re-points it. The recipe records the target as `launch.kernelBin`, and
+  `oats status` shows it (`kernel:`) when it is not the running `oats`. A
+  launch that cannot write the link fails with `E_LAUNCH_SHIM`. Existing homes
+  get the link at their next start or restart.
+- **`oats spawn` refuses an argument it does not read.** A positional after
+  the soul, or a flag spawn does not know, is `E_BAD_ARGS` naming it, before
+  anything is resolved or created. `oats spawn <soul> join=oats` used to be
+  accepted and the bare `join=oats` ignored, so the instance joined nothing;
+  the refusal now names the form that was meant, `--provider <capability>
+  key=value`. A routed spawn (`--server`) is refused on this machine, before
+  the server is contacted.
+- **Herdr 0.9 spawns work.** A new Herdr session was always opened at protocol
+  20, so `oats spawn --backend herdr` against Herdr 0.9, which speaks protocol
+  22, failed with "Herdr snapshot does not match selected protocol 20". A new
+  session now records the protocol its server reports when it is one OATS
+  supports (20 or 22), and refuses any other by name. A recorded session is
+  still checked against its recorded protocol on every call and is never
+  renegotiated. The Desktop attaches to protocol-22 sessions too; it accepted
+  only protocol 20 before. An instance recorded at protocol 20 is unreachable
+  after an in-place Herdr 0.8 → 0.9 upgrade until it is respawned.
+- **A Herdr launch no longer arrives cut.** OATS typed the launch command into
+  the new pane before its shell had started. The terminal's line buffer
+  (1024 bytes on macOS) dropped the rest of the longer command, so the harness
+  never started: the shell waited on an unclosed quote. On Herdr 0.9, 0 of 5
+  fresh panes ran a 2000-character command intact. A launch now waits, up to
+  10 s, until the pane has drawn its prompt, then types; 5 of 5 ran intact.

package/docs/souls-and-instances.md

@@ -29,6 +29,7 @@ that model.
 | Instance operating doc | `<home>/AGENTS.md` (generated) |
 | Instance skills | `<home>/.agents/skills/` |
 | Instance modules | `<home>/.oats/modules/<capability>/` (the copies this instance runs) |
+| Instance `oats` | `<home>/.oats/bin/oats` (a link to the kernel that last launched it) |
 | Instance record | `<home>/instance.json` (`modules`, `providers`, `workspace`, `teams`) |
 
 ## Soul anatomy
@@ -126,6 +127,7 @@ full copy** of every capability the soul resolved to:
     <skill>/SKILL.md               # one level deep, where every harness discovers skills
   .claude/skills → ../.agents/skills
   .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
   instance.json                    # provenance (below); `soulDir` = the soul directory hooks get as OATS_SOUL
@@ -244,7 +246,10 @@ it would bind, `providers` (the `--provider` map exactly as given) and
 the apply refuses with `E_DECISION_STALE` if a member
 moved in between. `--provider <cap> key=value` (repeatable; dotted keys nest)
 must name a capability the soul resolves (`E_CAPABILITY_MISSING` otherwise) and
-needs a workspace deployment. The full DTOs are in
+needs a workspace deployment. Spawn takes one soul and the flags it reads:
+another positional, or a flag it does not know, is `E_BAD_ARGS` naming the
+argument, before anything is created (a bare `key=value` is a provider
+setting given without `--provider <capability>`). The full DTOs are in
 [desktop-cli-api.md](desktop-cli-api.md#workspace-model-workspaceapi-2).
 
 Examples of spawn hooks:

package/lib/core.mjs

@@ -1537,7 +1537,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
           // Hooks also run through direct core callers (not only bin/oats).
           // Author this from the running kernel, never PATH, ambient env or
           // a caller's extraEnv: those may point at a different executable.
-          OATS_CLI_BIN: realpathSync(join(PKG_ROOT, "bin", "oats.mjs")),
+          OATS_CLI_BIN: kernelBin(),
           OATS_SETTINGS: JSON.stringify(cap.settings || {}),
           // Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
           // manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
@@ -2191,6 +2191,53 @@ export function launchEnvRefs(recipe, env = process.env) {
 export function launchEnvTmuxFlags(recipe, env) { return launchEnvRefs(recipe, env).map((r) => ` -e ${shq(`${r.name}=${r.value}`)}`).join(""); }
 export function launchEnvExports(recipe, env) { return launchEnvRefs(recipe, env).map((r) => `export ${r.name}=${shq(r.value)}; `).join(""); }
 
+/** The canonical path of this kernel's CLI: what the home's shim points at, and OATS_CLI_BIN. */
+export function kernelBin() { return realpathSync(join(PKG_ROOT, "bin", "oats.mjs")); }
+/** Where a home's `oats` lives: first on its harness's PATH, so plain `oats` inside an instance is
+ *  the kernel that launched it, whatever other `oats` the host's PATH finds first. */
+export const kernelShimDir = (home) => join(home, ".oats", "bin");
+/** Write <home>/.oats/bin/oats, a symlink to this kernel's CLI, replacing any shim a previous
+ *  launch (perhaps by another kernel) left: built aside, then renamed over. `.oats` and `.oats/bin`
+ *  must be directories of the home itself: a link there would carry the write outside the home.
+ *  The target, or E_LAUNCH_SHIM naming the path and the cause (a launch never runs with the
+ *  wrong `oats`), before anything outside the home is touched. */
+export function writeKernelShim(home) {
+  const dir = kernelShimDir(home), shim = join(dir, "oats");
+  let target, aside;
+  try {
+    target = kernelBin();
+    for (const d of [join(home, ".oats"), dir]) {
+      let st;
+      try { st = lstatSync(d); }
+      catch (e) { if (e.code !== "ENOENT") throw e; mkdirSync(d); st = lstatSync(d); }
+      if (!st.isDirectory()) throw new Error(`${d} is ${st.isSymbolicLink() ? "a symbolic link" : "not a directory"}`);
+    }
+    if (realpathSync(dir) !== join(realpathSync(home), ".oats", "bin")) throw new Error(`${dir} resolves outside the home`);
+    aside = join(dir, `.oats-${randomUUID()}`);
+    symlinkSync(target, aside);
+    renameSync(aside, shim);
+    return target;
+  } catch (e) {
+    if (aside) rmSync(aside, { force: true });
+    throw oatsError("E_LAUNCH_SHIM", `cannot write the kernel shim ${shim}${target ? ` (to ${target})` : ""}: ${e.message}; nothing was started`);
+  }
+}
+/** A parsed launch command's environment prefix with the home's shim directory first on PATH: a
+ *  configuration's PATH (literal or reference) follows it, else the PATH the command runs under. */
+function shimPathPrefix(tokens, binary, home) {
+  const dir = shq(kernelShimDir(home));
+  const prefix = tokens.slice(0, binary);
+  const texts = prefix.map((t) => t.name !== "PATH" ? t.text : t.kind === "env" ? `PATH=${dir}:${shq(t.value)}` : `PATH=${dir}:"$${t.source}"`);
+  if (!prefix.some((t) => t.name === "PATH")) texts.push(`PATH=${dir}:"$PATH"`);
+  return texts;
+}
+/** The persisted launch command as a shell runs it: the same command, with the home's kernel shim
+ *  first on PATH. The persisted bytes never carry it (they stay a shape parseLaunchCommand reads). */
+export function launchShellCommand(command, home) {
+  const { tokens, binary } = parseLaunchCommand(command);
+  return [...shimPathPrefix(tokens, binary, home), ...tokens.slice(binary).map((t) => t.text)].join(" ");
+}
+
 /** The harness command line of a recipe. With no configuration the bytes
  *  equal what spawn rendered before recipes: env prefix, the executable, the
  *  harness's own arguments, capability launch args, the task prompt. A
@@ -2234,14 +2281,15 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
 
 /** Execution, not preview: mark pending before dispatch, then resolve native
  * storage inside the backend shell under the actual command environment.
- * The original executable/argv is exec'd unchanged after recording succeeds. */
+ * The original executable/argv is exec'd unchanged after recording succeeds,
+ * 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 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 ${tokens.slice(binary).map(t => t.text).join(" ")}`;
-  return `${tokens.slice(0, binary).map(t => t.text).join(" ")} /bin/sh -c ${shq(inner)}`;
+  return `${shimPathPrefix(tokens, binary, home).join(" ")} /bin/sh -c ${shq(inner)}`;
 }
 
 
@@ -2374,7 +2422,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null,
     executable: executable.path || executable.declared || harness, executableDeclared: executable.declared ?? null, executableResolvedFrom: executable.resolvedFrom,
     args: [...(config?.args || [])], env: { ...configEnv }, model: model || null, ...(yolo !== undefined ? { yolo } : {}),
-    hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT,
+    hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT, kernelBin: kernelBin(),
     ...(frozen?.legacy ? { legacy: { ...frozen.legacy, ...(hooks.refreshed?.length ? { replacedBy: hooks.refreshed } : {}) } } : {}),
   };
   const inst = instance || meta?.instance || basename(home);
@@ -2412,11 +2460,18 @@ 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>"; }
 }
-/** The recipe with every environment value withheld. */
+/** The recipe as answers carry it: every environment value withheld, and without `kernelBin`
+ *  (the home's record keeps it; human `oats status` reads it from there). */
 export function redactLaunchRecipe(recipe) {
   const env = Object.fromEntries(Object.keys(recipe.env || {}).sort().map((n) => [n, typeof recipe.env[n] === "string" ? { redacted: true } : { fromEnv: recipe.env[n].fromEnv }]));
   const hooks = recipe.hooks ? { ...recipe.hooks, env: Object.fromEntries(Object.keys(recipe.hooks.env || {}).sort().map((n) => [n, { redacted: true }])) } : undefined;
-  return { ...recipe, env, ...(hooks ? { hooks } : {}) };
+  const { kernelBin: _recorded, ...answered } = recipe;
+  return { ...answered, env, ...(hooks ? { hooks } : {}) };
+}
+/** The kernel a home's last launch pointed its `oats` at (instance.json launch.kernelBin), or null. */
+export function recordedKernelBin(home) {
+  try { const bin = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"))?.launch?.kernelBin; return typeof bin === "string" ? bin : null; }
+  catch { return null; }
 }
 /** Spawn. With `o.prepared` (workspace model: a resolution prepared by
  *  instance-resolution.mjs) this is ASYNC — capabilities are fetched and copied
@@ -3477,6 +3532,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     // instance.json beside its rendering, which is executed in the instance's
     // tmux window. Capabilities contributed harness-specific arguments and
     // environment through their spawn hook; both are recorded with provenance.
+    // The home's `oats` is this kernel, launched now or later (--no-launch).
+    const shimTarget = writeKernelShim(home);
     const recipe = {
       version: LAUNCH_RECIPE_VERSION, harness,
       launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null,
@@ -3484,7 +3541,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       args: [...(launchConfig?.args || [])], env: { ...(launchConfig?.env || {}) },
       model: model || null, ...(yolo !== undefined ? { yolo } : {}),
       hooks: { launch: { ...hookRes.launch }, env: { ...hookRes.env }, contributions: hookRes.contributions || [] },
-      prompt: LAUNCH_PROMPT,
+      prompt: LAUNCH_PROMPT, kernelBin: shimTarget,
     };
     if (triggerEventFile) recipe.env.OATS_TRIGGER_EVENT_FILE = triggerEventFile;
     const cmdline = renderLaunchRecipe(recipe, { home, instance });
@@ -4893,6 +4950,9 @@ export function startInstanceSession(home, o = {}) {
       try { state = inspectSessionTarget(target, o.io); } catch (e) { if (backend === "tmux" && lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; } else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
       if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
     }
+    // The kernel that launches the harness is the one the agent's plain `oats` runs.
+    checkRoots();
+    writeKernelShim(realHome);
     const startedAt = new Date().toISOString();
     const id = randomUUID();
     checkRoots();

package/lib/herdr.mjs

@@ -1,11 +1,12 @@
 /** Herdr 0.8.x/0.9.x host-local backend (explicit protocols 20/22).
- * SSH belongs to the CLI router; protocol selection is never negotiation. */
+ * SSH belongs to the CLI router. A new session records the server's protocol once; a recorded
+ * target is never renegotiated. */
 import { execFileSync, spawn } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
-// Keep the existing legacy/default protocol literal; captured callers select one.
+// The legacy protocol literal; a new session records the protocol its server reports (ensureHerdr).
 export const HERDR_PROTOCOL = 20;
 export const HERDR_SUPPORTED_PROTOCOLS = Object.freeze([20, 22]);
 export const isSupportedHerdrProtocol = (value) => HERDR_SUPPORTED_PROTOCOLS.includes(value);
@@ -21,10 +22,15 @@ export function herdrSocket(session = "oats") {
   return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "herdr", "sessions", session, "herdr.sock");
 }
 
-export function herdrCommand(target, args, { timeout = 10000, exec = execFileSync } = {}) {
+/** One Herdr CLI call on the target's socket, its stdout as text. */
+function herdrOutput(target, args, { timeout = 10000, exec = execFileSync } = {}) {
   const env = { ...process.env, HERDR_SOCKET_PATH: target.socket };
   delete env.HERDR_SESSION;
-  const output = exec(target.binary || "herdr", args, { env, encoding: "utf8", timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+  return exec(target.binary || "herdr", args, { env, encoding: "utf8", timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+export function herdrCommand(target, args, io) {
+  const output = herdrOutput(target, args, io);
   // Some successful terminal mutations have no output; reads below require
   // their documented result shape independently.
   if (!output.trim()) return {};
@@ -42,9 +48,20 @@ export function herdrSnapshot(target, io) {
   return snapshot;
 }
 
-export function ensureHerdr({ binary = "herdr", socket, session = "oats" } = {}) {
-  const target = { backend: "herdr", binary, socket: resolve(socket || herdrSocket(session)), protocol: HERDR_PROTOCOL };
-  try { herdrSnapshot(target); return target; }
+/** The target for a NEW session on the server at `socket`: it records the supported protocol that server
+ * reports (Herdr 0.8 speaks 20, 0.9 speaks 22). Every later call checks the snapshot against that recorded
+ * protocol, so a recorded target is never renegotiated. */
+function newSessionTarget(target, io) {
+  const protocol = herdrCommand(target, ["api", "snapshot"], io).snapshot?.protocol;
+  if (!isSupportedHerdrProtocol(protocol)) throw Object.assign(new Error(`Herdr server speaks protocol ${protocol ?? "unknown"}; OATS supports ${HERDR_SUPPORTED_PROTOCOLS.join(" and ")}`), { unsupportedProtocol: true });
+  const selected = { ...target, protocol };
+  herdrSnapshot(selected, io);
+  return selected;
+}
+
+export function ensureHerdr({ binary = "herdr", socket, session = "oats", io } = {}) {
+  const target = { backend: "herdr", binary, socket: resolve(socket || herdrSocket(session)) };
+  try { return newSessionTarget(target, io); }
   catch (e) {
     // An explicit socket belongs to an operator-managed server. Never start a
     // different server when it cannot be inspected or is incompatible.
@@ -59,7 +76,8 @@ export function ensureHerdr({ binary = "herdr", socket, session = "oats" } = {})
   let error;
   for (let i = 0; i < 30; i++) {
     pause(100);
-    try { herdrSnapshot(target); return target; } catch (e) { error = e; }
+    // A server that answers with an unsupported protocol is up: waiting longer cannot change its answer.
+    try { return newSessionTarget(target, io); } catch (e) { if (e.unsupportedProtocol) throw e; error = e; }
   }
   throw new Error(`Herdr did not start: ${error?.message || "no socket"}`);
 }
@@ -81,8 +99,27 @@ export function inspectHerdr(target, io) {
   return { present: !!pane, pane, agent, status: agent?.agent_status || "unknown" };
 }
 
+/** Wait until a new pane's shell has drawn something (its prompt) before typing into it. Text typed
+ * earlier sits in the terminal's canonical line buffer, which drops a line past 1024 bytes on macOS:
+ * a launch command is longer than that, and arrived cut. Bounded; a Herdr that cannot read a pane
+ * leaves the old behaviour (type at once). */
+function awaitShellReady(target, io) {
+  const deadline = Date.now() + (io?.shellReadyMs ?? 10000);
+  for (;;) {
+    let text;
+    // `pane read` answers the screen as plain text, not a JSON envelope.
+    const remaining = Math.max(100, deadline - Date.now());
+    try { text = herdrOutput(target, ["pane", "read", target.paneId, "--source", "visible"], { ...io, timeout: Math.min(2000, remaining) }); }
+    catch { return; }
+    if (typeof text === "string" && text.trim()) return;
+    if (Date.now() >= deadline) return;
+    pause(100);
+  }
+}
+
 export function launchHerdr(target, command, io) {
   if (!inspectHerdr(target, io).present) throw new Error("Herdr launch pane disappeared");
+  awaitShellReady(target, io);
   // This is the allocated shell's one launch command. Exec avoids a fallback
   // shell that could accidentally consume a subsequent agent notification.
   herdrCommand(target, ["pane", "run", target.paneId, `exec /bin/sh -c ${quote(command)}`], io);

package/package.json

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