@awebai/oats 0.22.1 → 0.22.3

package/README.md

@@ -14,7 +14,7 @@ specialist, a maintainer, a reviewer, a package owner, or any other role, each
 with a precise curriculum, durable knowledge, and a full provider-native
 session you can enter and steer.
 
-OATS works with **Pi** and **Claude Code**. A team may mix providers and models
+OATS launches **Pi**, **Claude Code**, and **Codex**. A team may mix providers and models
 while sharing the same souls, package and config contracts, instance
 lifecycle, and coordination topology. On machines where `oats setup` has run,
 the append-only, searchable **turn record** captures supported local transcripts
@@ -45,7 +45,7 @@ designs.
   instantiated many times without losing its identity or accumulated
   expertise.
 - **Instances are real sessions, not hidden subagent calls.** Each instance is
-  a disposable incarnation with a full Pi or Claude Code session hosted in
+  a disposable incarnation with a full Pi, Claude Code, or Codex session hosted in
   tmux, an explicit task, its own home, and a repository or workspace view.
   You can attach to it, steer it, message it, stop it, and inspect exactly
   what it received.
@@ -145,7 +145,8 @@ template discovery curtailed while operator-configured extensions remain
 enabled. Claude Code keeps the operator's settings, skills, plugins, MCP,
 hooks, and memory, and OATS adds its canonical composed resources. The
 guarantee is an exact OATS-managed curriculum, not identical ambient behavior
-across providers.
+across providers. Codex uses native instructions, skills and approval settings;
+its launch support currently requires agents to check `aw` themselves for new messages.
 
 ### Configuration and layers
 
@@ -361,3 +362,9 @@ AGENTS.md, Agent Skills, and OKF.
 ## License
 
 [MIT](LICENSE) © 2026 OATS Framework
+
+Session backends and unattended launches are described in
+[execution targets](docs/execution-targets.md). Use `oats spawn <soul> --backend
+herdr --yolo` for a Herdr-hosted unattended Codex/Claude session, or put
+`yolo: true` in the scope's oats-config.yaml. Aweb owns shared event delivery;
+terminal transport alone does not enable a messaging broker.

package/bin/oats.mjs

@@ -31,7 +31,7 @@ import {
   resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
   findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, listCapabilityAgents, workspaceOf,
   ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
-  spawnInstance, retireInstance, upsertLocalAgent, defaultRepo, RELATIONS,
+  spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS,
 } from "../lib/core.mjs";
 import {
   aggregateMissingRequirements, applyFromOasScope, beginRunJournal, discoverMigrationScopes, discoverOasScopes, discoverWorkspaceScopes, planFromOasScope,
@@ -39,6 +39,8 @@ import {
   assertNoSymlinkedParents, copyFileAtomic, writeFileAtomic,
   runRequirementInstall, selectConfigTemplate, validateConfigTemplate, writeAdoptedTemplate,
 } from "../lib/packages.mjs";
+import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
+import { spawnSync as spawnSyncProc } from "node:child_process";
 
 const args = process.argv.slice(2);
 const cmd = args[0];
@@ -47,6 +49,15 @@ const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
 };
+function yoloFlag() {
+  if (args.includes("--yolo") && args.includes("--no-yolo")) cmdFail("E_BAD_ARGS", "choose --yolo or --no-yolo, not both");
+  return args.includes("--yolo") ? true : args.includes("--no-yolo") ? false : undefined;
+}
+function valueFlag(name) {
+  const value = flag(name);
+  if (value === true) cmdFail("E_BAD_ARGS", `--${name} needs a value`);
+  return value;
+}
 const die = (msg) => { console.error(`oats: ${msg}`); process.exit(1); };
 /** Resolve the --dir flag with central validation: a value-taking flag given
  * no value (flag() → true) is E_BAD_ARGS inside the JSON boundary, never an
@@ -2602,7 +2613,10 @@ function status() {
     console.log(`  ${a.name}${a.kind === "local" ? " (local)" : ""}  [work: ${a.work || "checkout"}, repo: ${a.repo || "?"}]`);
     if (a.description) console.log(`      ${a.description}`);
     for (const i of a.instances) {
-      console.log(`      • ${i.instance}  ${i.running ? "RUNNING" : "idle"}  (branch ${i.branch || "?"}, ${i.work || "?"})`);
+      console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : i.running ? "RUNNING" : "idle"}  (branch ${i.branch || "?"}, ${i.work || "?"})`);
+    }
+    for (const f of a.retireFailures || []) {
+      console.log(`      ! deferred retirement of ${f.instance} FAILED${f.completedAt ? ` at ${f.completedAt}` : ""}: ${f.error || (f.incomplete || []).join("; ") || "see result file"} — retry with \`oats retire ${f.instance}\``);
     }
   }
   const defs = listAgentDefs(process.cwd());
@@ -2624,7 +2638,8 @@ function statusTeam() {
     if (!agents.length) { console.log("    (no agents)"); continue; }
     for (const a of agents) {
       console.log(`    ${a.name}${a.kind === "local" ? " (local)" : ""}${a.description ? `  — ${a.description}` : ""}`);
-      for (const i of a.instances) console.log(`      • ${i.instance}  ${i.running ? "RUNNING" : "idle"}`);
+      for (const i of a.instances) console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : i.running ? "RUNNING" : "idle"}`);
+      for (const f of a.retireFailures || []) console.log(`      ! deferred retirement of ${f.instance} FAILED: ${f.error || (f.incomplete || []).join("; ") || "see result file"} — retry with \`oats retire ${f.instance}\``);
     }
   }
 }
@@ -2633,8 +2648,11 @@ function spawnCmd() {
   // JSON mode: contract envelope, stable error codes, stderr-only progress.
   const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
   const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
+  const yolo = yoloFlag();
+  const backend = valueFlag("backend"), herdrSocket = valueFlag("herdr-socket");
+  if (backend !== undefined && !["tmux", "herdr"].includes(backend)) bail("E_BAD_ARGS", "--backend must be tmux or herdr");
   const name = args[1];
-  if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace] [--work-dir <owner-work>] [--runtime pi|claude] [--model <m>] [--branch <b>] [--instructions-file <f>|--def-file <f>] [--no-launch] [--json]");
+  if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace] [--work-dir <owner-work>] [--runtime pi|claude|codex] [--backend tmux|herdr] [--herdr-socket <path>] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--instructions-file <f>|--def-file <f>] [--no-launch] [--json]");
   // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
   // ANY side effect — including root discovery and local-agent upsert (an
   // --instructions-file spawn must not scaffold/overwrite a local soul before
@@ -2676,7 +2694,7 @@ function spawnCmd() {
     } else if (!agent || agent.kind === "local") {
       agent = upsertLocalAgent(root, {
         name, file: defFile, instructions: instrFile ? readFileSync(instrFile, "utf8") : undefined,
-        repo: flag("repo"), work: flag("work"), runtime: flag("runtime"), model: flag("model"),
+        repo: flag("repo"), work: flag("work"), runtime: flag("runtime"), model: flag("model"), yolo: yoloFlag(),
       });
     } else {
       bail("E_BAD_ARGS", `"${name}" is a persistent agent — spawn it without --instructions-file/--def-file`);
@@ -2725,7 +2743,7 @@ function spawnCmd() {
     r = spawnInstance(root, agent, {
       purpose: flag("purpose"), task: taskText, taskFile: taskFileFlag, relation, relativeTo, relativeRoot,
       repo: flag("repo") || agent.repo || defaultRepo(workspaceOf(root)) || defaultRepo(process.cwd()),
-      work: flag("work"), workDir: flag("work-dir"), runtime: flag("runtime"), model: flag("model"), branch: flag("branch"),
+      work: flag("work"), workDir: flag("work-dir"), runtime: flag("runtime"), backend, herdrSocket, yolo, model: flag("model"), branch: flag("branch"),
       launch: !args.includes("--no-launch"),
     });
   } catch (e) {
@@ -2745,10 +2763,12 @@ function spawnCmd() {
       model: r.model || null, parent: r.parentInstance || null,
       sibling: r.siblingInstance || null, relation: r.relation || null,
       spawnOrigin: r.spawnOrigin, attach: r.attach,
+      ...(r.sessionTarget ? { sessionTarget: r.sessionTarget } : {}),
+      ...(r.yolo !== undefined ? { yolo: r.yolo } : {}),
     });
     return;
   }
-  console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
+  console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? r.sessionTarget ? ` — Herdr pane "${r.sessionTarget.paneId}"` : ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
   console.log(`  home:   ${shortPath(r.home)}`);
   if (!r.launched) console.log(`  launch: (cd ${shortPath(r.home)} && ${r.command})`);
   for (const w of r.warnings || []) console.log(`  WARNING: ${w}`);
@@ -2757,7 +2777,12 @@ function spawnCmd() {
 
 function retireCmd() {
   const name = args[1];
-  if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--self] [--delete-branch] [--keep-dir] [--force] [--json]");
+  if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--home <path>] [--self] [--delete-branch] [--keep-dir] [--force] [--json]");
+  let homeFlag = flag("home");
+  if (homeFlag === true) die("--home needs the instance home path");
+  // 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 (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`);
@@ -2765,9 +2790,20 @@ function retireCmd() {
   // Cross-repo: the instance may home in a sibling repo of the team scope.
   if (!listAgents(root).some((a) => existsSync(join(a._dir, "instances", name)))) {
     const hit = findTeamInstance(dirFlag(), name);
-    if (hit && resolve(hit.root) !== resolve(root)) { root = hit.root; console.log(`(cross-repo: instance homes at ${shortPath(root)})`); }
+    // Stdout carries only the envelope in JSON mode (the Desktop parses it).
+    if (hit && resolve(hit.root) !== resolve(root)) { root = hit.root; (args.includes("--json") ? console.error : console.log)(`(cross-repo: instance homes at ${shortPath(root)})`); }
+  }
+  const r = retireInstance(root, name, { home: homeFlag, self: isSelf, deleteBranch: args.includes("--delete-branch"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") });
+  // Deferred self-retire: nothing has been inspected, run, or removed yet. The
+  // caller's window dies first; a detached process then retires the instance
+  // as an external operator and writes its outcome beside the home.
+  if (r.deferred) {
+    if (args.includes("--json")) { console.log(JSON.stringify(r, null, 2)); return; }
+    console.log(`Retirement of ${r.retired} (agent ${r.agent}) is ${r.alreadyScheduled ? "already " : ""}scheduled — say any goodbyes now.`);
+    console.log(`  in ~${r.completesInSec}s a detached completion quiesces this runtime (that is what ends this window), preserves work, runs retire hooks and removes the home`);
+    console.log(`  if the completion fails, this window stays, the failure shows in \`oats status\` and at ${shortPath(r.resultPath)}, and \`oats retire ${r.retired}\` retries it`);
+    return;
   }
-  const r = retireInstance(root, name, { self: isSelf, deleteBranch: args.includes("--delete-branch"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") });
   // Forced removal past an incomplete cleanup: the home is gone because the
   // operator said so, but the external state it owed is still out there and
   // nobody else will mention it again.
@@ -2795,13 +2831,34 @@ function retireCmd() {
   if (isSelf) console.log("This window dies in ~8s — say any goodbyes now.");
 }
 
+async function sessionCmd() {
+  try {
+    const home = flag("home");
+    let result;
+    if (args[1] === "attach") {
+      if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
+      process.exitCode = await attachInstanceSession(home);
+      return;
+    }
+    if (args[1] === "inspect") result = inspectInstanceSession(home);
+    else if (args[1] === "input") {
+      const file = flag("text-file");
+      if (file === true) throw Object.assign(new Error("--text-file needs a path"), { code: "E_BAD_ARGS" });
+      if (!file && process.stdin.isTTY) throw Object.assign(new Error("provide --text-file or pipe input on stdin"), { code: "E_BAD_ARGS" });
+      result = inputInstanceSession(home, readFileSync(file || 0, "utf8"));
+    } else throw Object.assign(new Error("usage: oats session inspect|input|attach --home /absolute/home [--text-file path] [--json]"), { code: "E_BAD_ARGS" });
+    if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+  } catch (e) { cmdFail(e.code || "E_SESSION_FAILED", e.message); }
+}
+
 async function paneCmd() {
   die("`oats pane` has been retired — the OATS Desktop app (packages/desktop) is the control panel now.");
 }
 
 function createCmd() {
+  const yolo = yoloFlag();
   const name = args[1];
-  if (!name || name.startsWith("--")) die("usage: oats create <name> [--local] [--description <d>] [--type <agent-type>] [--repo <r>] [--work worktree|checkout|attached|workspace] [--runtime pi|claude] [--model <m>] [--instructions-file <f>]");
+  if (!name || name.startsWith("--")) die("usage: oats create <name> [--local] [--description <d>] [--type <agent-type>] [--repo <r>] [--work worktree|checkout|attached|workspace] [--runtime pi|claude|codex] [--model <m>] [--yolo|--no-yolo] [--instructions-file <f>]");
   const local = args.includes("--local");
   const startDir = dirFlag();
   // `create` BOOTSTRAPS a deployment: with no agents/ or local-agents/ yet,
@@ -2819,7 +2876,7 @@ function createCmd() {
   const instrFile = flag("instructions-file");
   const r = coreCreateAgent(root, {
     name, local, description: flag("description"), type: flag("type"), repo: flag("repo") || defaultRepo(process.cwd()),
-    work: flag("work"), runtime: flag("runtime"), model: flag("model"),
+    work: flag("work"), runtime: flag("runtime"), model: flag("model"), yolo,
     instructions: instrFile ? readFileSync(instrFile, "utf8") : undefined,
   });
   if (args.includes("--json")) { console.log(JSON.stringify({ ...r, ...(bootstrapped ? { agentsRoot: root } : {}) }, null, 2)); return; }
@@ -3067,7 +3124,13 @@ function versionCmd() {
   if (JSON_MODE) {
     // EXACT Desktop API v1 probe payload — one JSON object, nothing else on
     // stdout. Desktop accepts desktopApi === 1 and a compatible semver range.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1 }));
+    // `remote`: this kernel's remote-side surface: the commands it routes to
+    // a registered server with --server, plus `roster` (the local command
+    // over registrations and saved routes); a Desktop gates its remote path
+    // on it (an older CLI without the surface must fail closed with a
+    // reason, not an argument error). `features`: kernel abilities a peer
+    // must see before relying on them (retire-home: retire --home).
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "roster", "harvest"], features: ["retire-home"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3106,6 +3169,201 @@ async function experimentalCmd() {
   await import(url);
 }
 
+// ---------- servers: registry and remote routing (docs/execution-targets.md) ----------
+/** `oats server add|list|remove|check`. A registration is where and how:
+ *  an OpenSSH host alias, the remote workspace, the remote oats path. Keys
+ *  and passwords never enter it; ssh owns those. */
+function serverCmd() {
+  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
+  const sub = args[1];
+  const usage = "usage: oats server add <id> --ssh <host-alias> --workspace </abs/path> [--oats <path>] [--herdr <path>] [--path <dir:dir>] [--label <text>] [--replace] | list | remove <id> | check <id> | roster [--server <id>] | forget <id> --instance <name>  [--json]";
+  if (!["add", "list", "remove", "check", "roster", "forget"].includes(sub)) bail("E_USAGE", usage);
+  if (sub === "forget") {
+    // A saved route whose remote instance is gone can be dropped only by
+    // the operator: nothing routed can do it, and the changed-registration
+    // guard counts it until then.
+    const id = args[2];
+    const inst = flag("instance");
+    if (!id || id.startsWith("--") || !inst || inst === true) bail("E_USAGE", "usage: oats server forget <id> --instance <name> [--json]");
+    let snap;
+    try { snap = forgetSnapshot(id, inst); } catch (e) { bail(e.code || "E_SNAPSHOT_UNKNOWN", e.message); }
+    if (JSON_MODE) { jsonOk({ server: id, instance: inst, home: snap.home, target: snap.target, forgotten: true }); return; }
+    console.log(`Forgot the saved route of ${inst} through ${id} (${snap.target?.sshHost}:${snap.home}).`);
+    console.log(`  if that home still exists on the host it is no longer managed from here: retire it there with oats retire ${inst} --home ${snap.home}`);
+    return;
+  }
+  if (sub === "roster") {
+    // The remote roster for the Desktop and operators: grouped by saved route
+    // target, one bounded status pull per target, saved routes as the action
+    // authority. --server narrows to one registry id.
+    const only = flag("server") === true ? bail("E_BAD_ARGS", "--server needs a registered server id") : flag("server");
+    const ms = (name) => { const v = flag(name); if (v === undefined) return undefined; const n = Number(v); if (!Number.isInteger(n) || n < 1000) bail("E_BAD_ARGS", `--${name} takes whole milliseconds, at least 1000`); return n; };
+    let out;
+    try { out = rosterGroups({ server: only, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
+    if (JSON_MODE) { jsonOk(out); return; }
+    if (!out.groups.length) { console.log("no remote groups: no registrations and no saved routes"); return; }
+    for (const g of out.groups) {
+      console.log(`  ${g.server}${g.label && g.label !== g.server ? `  ${g.label}` : ""}  [${g.id}]  ssh ${g.target.sshHost}  workspace ${g.target.workspace}${g.registrationPresent ? "" : "  (registration removed or changed; saved routes only)"}`);
+      console.log(g.probe?.ok ? `      reachable, ${g.souls.length} soul(s)` : `      UNREACHABLE: ${g.probe?.error?.message || "?"}`);
+      for (const i of g.instances) console.log(`      • ${i.instance}  ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown"}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : "  (observed only, no saved route)"}${i.runtimeError ? `  ${i.runtimeError}` : ""}`);
+      for (const f of g.retireFailures || []) console.log(`      ! deferred retirement of ${f.instance} (${f.agent}) FAILED there${f.error?.message ? `: ${f.error.message}` : ""}${f.retry ? ` — retry on the host: ${f.retry}` : ""}`);
+    }
+    console.log(`  bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used${out.bounds.skipped ? `, ${out.bounds.skipped} target(s) not reached` : ""}`);
+    return;
+  }
+  let servers;
+  try { servers = readServers(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
+  if (sub === "list") {
+    const rows = Object.entries(servers).map(([id, s]) => ({ id, ...s, target: targetOf({ id, ...s }), snapshots: listSnapshots(id).length }));
+    if (JSON_MODE) { jsonOk({ file: SERVERS_FILE(), servers: rows }); return; }
+    if (!rows.length) { console.log(`no servers registered (${shortPath(SERVERS_FILE())}) — add one with \`oats server add <id> --ssh <alias> --workspace </path>\``); return; }
+    for (const r of rows) console.log(`  ${r.id}${r.label ? `  ${r.label}` : ""}\n      ssh ${r.sshHost}  workspace ${r.workspace}  oats ${r.target.oatsPath}${r.target.herdrPath ? `  herdr ${r.target.herdrPath}` : ""}${r.snapshots ? `  (${r.snapshots} remote instance${r.snapshots === 1 ? "" : "s"} spawned from here)` : ""}`);
+    return;
+  }
+  const id = args[2];
+  if (!id || id.startsWith("--")) bail("E_USAGE", usage);
+  if (sub === "add") {
+    const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
+    const entry = { sshHost: val("ssh"), workspace: val("workspace") };
+    for (const [k, f] of [["oatsPath", "oats"], ["herdrPath", "herdr"], ["path", "path"], ["label", "label"]]) { const v = val(f); if (v !== undefined) entry[k] = v; }
+    if (!entry.sshHost || !entry.workspace) bail("E_USAGE", usage);
+    try { validateServer(id, entry); } catch (e) { bail(e.code, e.message); }
+    if (servers[id] && !args.includes("--replace")) bail("E_SERVER_EXISTS", `server ${id} is already registered (pass --replace to overwrite; existing remote instances keep the route they were spawned with)`);
+    servers[id] = entry;
+    writeServers(servers);
+    if (JSON_MODE) { jsonOk({ id, ...entry, file: SERVERS_FILE() }); return; }
+    console.log(`Registered server ${id} → ssh ${entry.sshHost}, workspace ${entry.workspace} (${shortPath(SERVERS_FILE())}). Verify it with \`oats server check ${id}\`.`);
+    return;
+  }
+  if (sub === "remove") {
+    if (!servers[id]) bail("E_SERVER_UNKNOWN", `no server registered as ${id}`);
+    const snaps = listSnapshots(id);
+    delete servers[id];
+    writeServers(servers);
+    if (JSON_MODE) { jsonOk({ removed: id, remoteInstancesStillTracked: snaps.map((s) => s.instance) }); return; }
+    console.log(`Removed server ${id}${snaps.length ? ` — ${snaps.length} remote instance(s) spawned from it keep their snapshots and can still be retired with --server ${id}` : ""}`);
+    return;
+  }
+  // check: reachability and compatibility, no mutation
+  let server; try { server = getServer(id); } catch (e) { bail(e.code, e.message); }
+  const target = targetOf(server);
+  try {
+    const remote = checkRemote(target);
+    const status = routeCommand(id, "status", [], { server });
+    const agents = status.envelope.ok ? (status.envelope.result.agents || []).length : undefined;
+    if (JSON_MODE) { jsonOk({ id, target, remote, workspaceReachable: !!status.envelope.ok, agents, error: status.envelope.ok ? undefined : status.envelope.error }); return; }
+    console.log(`${id}: ssh ${target.sshHost} ok, remote oats ${remote.version} (envelope v${remote.schemaVersion})`);
+    console.log(status.envelope.ok ? `  workspace ${target.workspace}: ${agents} agent(s)` : `  workspace ${target.workspace}: ${status.envelope.error?.message || "not usable"}`);
+    if (!status.envelope.ok) process.exit(1);
+  } catch (e) { bail(e.code || "E_SSH", e.message); }
+}
+
+/** `oats <spawn|retire|status> --server <id> ...`: run the command on the
+ *  registered server's installed oats, same arguments, same envelope. The
+ *  local side only routes and keeps the route snapshot per remote instance. */
+function serverRouteCmd() {
+  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
+  const id = flag("server");
+  if (id === true || !id) bail("E_BAD_ARGS", "--server needs a registered server id (oats server list)");
+  if (flag("dir") !== undefined || args.some((a) => a.startsWith("--dir="))) bail("E_BAD_ARGS", "--dir cannot be combined with --server: the remote workspace comes from the server registration");
+  // Interactive viewer: `oats session attach --server <id> --instance <name>`
+  // (or --home </abs/remote/home>) runs the execution host's own attach
+  // through an ssh PTY with this terminal's stdio; nothing is captured.
+  if (cmd === "okf") {
+    // `oats okf harvest --server <id> --instance <name>`: the package's
+    // harvest command run in the instance's SAVED home on the host.
+    if (args[1] !== "harvest") bail("E_USAGE", "--server routes `okf harvest` only among the okf commands");
+    const inst = flag("instance");
+    if (!inst || inst === true) bail("E_BAD_ARGS", "okf harvest --server needs --instance <name> (spawned from here)");
+    let routed;
+    try { routed = routeCommand(id, "harvest", [inst]); } catch (e) { bail(e.code || "E_SSH", e.message); }
+    if (routed.stderr?.trim()) process.stderr.write(routed.stderr.endsWith("\n") ? routed.stderr : routed.stderr + "\n");
+    if (JSON_MODE) { console.log(JSON.stringify(routed.envelope, null, 2)); if (!routed.envelope.ok) process.exit(1); return; }
+    if (!routed.envelope.ok) die(`${id}: ${routed.envelope.error?.message || "harvest failed"} (${routed.envelope.error?.code || "E_REMOTE"})`);
+    const hr = routed.envelope.result;
+    console.log(`Harvest on ${id} for ${inst}: ${hr.harvest}${hr.reason ? ` (${hr.reason})` : ""}${hr.instance && hr.harvest === "spawned" ? ` — harvester ${hr.instance}` : ""}`);
+    if (hr.instance && hr.instance !== inst) console.log(`  the harvester ${hr.instance} runs on ${id}; retire it there when it is done, or let it self-retire`);
+    return;
+  }
+  if (cmd === "session") {
+    const addr = { instance: flag("instance") === true ? undefined : flag("instance"), home: flag("home") === true ? undefined : flag("home") };
+    if (args[1] === "inspect") {
+      // Desktop preflight before a remote attach: the execution host's own
+      // inspect, relayed as its envelope; a failure is a failure, nonzero.
+      let out;
+      try { out = inspectRemote(id, addr); } catch (e) { bail(e.code || "E_SSH", e.message); }
+      if (out.stderr?.trim()) process.stderr.write(out.stderr.endsWith("\n") ? out.stderr : out.stderr + "\n");
+      if (JSON_MODE) { console.log(JSON.stringify(out.envelope, null, 2)); if (!out.envelope.ok) process.exit(1); return; }
+      if (!out.envelope.ok) die(`${id}: ${out.envelope.error?.message || "inspect failed"} (${out.envelope.error?.code || "E_REMOTE"})`);
+      const r = out.envelope.result;
+      console.log(`${r.instance || r.home} on ${id}: ${r.present ? `present, ${r.state || "unknown"}` : "not present"}${r.backend ? ` (${r.backend})` : ""}`);
+      return;
+    }
+    if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect` and `session attach`; input runs on the execution host (the wake broker calls it there)");
+    let route;
+    try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
+    catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
+    if (args.includes("--print")) { console.log(route.argv.map(shellQuote).join(" ")); return; }
+    const r = spawnSyncProc(route.argv[0], route.argv.slice(1), { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+  }
+  // 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.
+  const rest = [];
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--server") { i++; continue; }
+    if (a === "--json") continue;
+    if (a === "--task-file") {
+      const f = args[++i];
+      if (!f || f.startsWith("--")) bail("E_BAD_ARGS", "--task-file needs a path");
+      if (!existsSync(f)) bail("E_BAD_ARGS", `task file not found: ${f}`);
+      rest.push("--task", readFileSync(f, "utf8"));
+      continue;
+    }
+    rest.push(a);
+  }
+  let routed;
+  try { routed = routeCommand(id, cmd, rest); }
+  catch (e) { bail(e.code || "E_SSH", e.message); }
+  const { envelope, stderr } = routed;
+  if (stderr && stderr.trim()) process.stderr.write(stderr.endsWith("\n") ? stderr : stderr + "\n");
+  if (JSON_MODE) { console.log(JSON.stringify(envelope, null, 2)); if (!envelope.ok || envelope.result?.rollbackIncomplete) process.exit(1); return; }
+  if (!envelope.ok && !(cmd === "retire" && envelope.result)) die(`${id}: ${envelope.error?.message || "remote command failed"} (${envelope.error?.code || "E_REMOTE"})`);
+  const r = envelope.result;
+  const target = r.target || {};
+  if (cmd === "spawn") {
+    console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
+    console.log(`  remote home: ${r.home}`);
+    console.log(`  route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
+    for (const w of r.warnings || []) console.log(`  WARNING: ${w}`);
+    console.log(`  attach: ssh -t ${r.target.sshHost} tmux attach -t ${r.tmux?.session || "oats"}`);
+  } else if (cmd === "retire") {
+    // Everything the local retireCmd tells the operator, for a remote home
+    // they cannot see: forced-incomplete state now theirs to remove by hand
+    // there, work preserved there and where, and incomplete cleanup.
+    if (r.forcedIncomplete) {
+      console.error(`Removed ${r.retired} on ${id} under --force with cleanup INCOMPLETE — this external state was NOT cleaned up and is now yours to remove by hand on ${target.sshHost}:`);
+      for (const f of r.forcedIncomplete) console.error(`  ${f}`);
+    }
+    console.log(`Retired ${r.retired} on ${id}${r.deferred ? " (deferred completion scheduled there)" : ""}${r.rollbackIncomplete ? " — cleanup INCOMPLETE on the server, home retained there" : ""}`);
+    for (const recovery of r.workRecoveries || (r.workRecovery ? [r.workRecovery] : [])) {
+      console.log(`Work that was not committed has been preserved on ${target.sshHost}: ${(recovery.classes || []).join(", ")}`);
+      console.log(`  ${recovery.path}`);
+    }
+    if (r.rollbackIncomplete) { for (const f of r.rollbackIncomplete) console.error(`  ${f}`); console.error(`Fix the cause there and re-run \`oats retire ${r.retired} --server ${id}\`.`); process.exit(1); }
+  } else {
+    console.log(`oats status — server ${id} (ssh ${r.target.sshHost}, workspace ${r.target.workspace})\n`);
+    for (const a of r.agents || []) {
+      console.log(`  ${a.name}  [work: ${a.work || "checkout"}, repo: ${a.repo || "?"}]`);
+      for (const i of a.instances || []) console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : i.running ? "RUNNING" : "idle"}`);
+    }
+    const snaps = r.snapshots || [];
+    if (snaps.length) console.log(`\n  spawned from this machine: ${snaps.map((s) => s.instance).join(", ")}`);
+  }
+}
+
 // ---------- main ----------
 // Typed config-shape failures are DEPLOYMENT state the operator can fix, not
 // kernel bugs: an unsafe mapping key anywhere in the visible config chain is
@@ -3121,7 +3379,9 @@ async function experimentalCmd() {
 // blame` pointing at the commit that last changed each command.
 const TYPED_CLI_FAILURES = new Set(["unsafe-config-key", "unsafe-config-value"]);
 try {
-if (cmd === "doctor") {
+if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf"].includes(cmd)) serverRouteCmd();
+else if (cmd === "server") serverCmd();
+else if (cmd === "doctor") {
   const doctorDir = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
   args.includes("--json") ? doctorJson(doctorDir) : doctor(doctorDir);
 }
@@ -3142,6 +3402,7 @@ else if (cmd === "pane") await paneCmd();
 else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
 // Same rule as the inner catch: a typed CLI failure surfaces with its own code
 // through the shared boundary, never re-badged as a spawn-mechanism failure.
+else if (cmd === "session") await sessionCmd();
 else if (cmd === "spawn") { try { spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e); throw e; } }
 else if (cmd === "retire") retireCmd();
 else if (cmd === "create") createCmd();
@@ -3163,24 +3424,46 @@ Usage:
                                             Desktop CLI API v1 probe payload
   oats status [--json]                       agents, souls, running instances
   oats status --team [--json]                whole-team roster across the team scope's repos
+  oats server add <id> --ssh <alias>         register another machine's OATS (OpenSSH alias,
+      --workspace </abs/path> [--oats <p>]   remote workspace, remote oats path; no keys stored;
+      [--path <dir:dir>]                    --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
+  oats server list|remove <id>|check <id>    registry; check = reachability + version, no mutation
+  oats spawn|retire|status ... --server <id> run that command on the server's installed oats
+                                            (same flags, same envelope; the saved route per
+                                            remote instance lives under ~/.oats/remote/)
+  oats server roster [--server <id>]         remote roster grouped by server and saved route
+      [--budget <ms>] [--per-target <ms>]   target: one status pull per group within a total
+      [--json]                              budget (45 s, 20 s per target); saved routes are
+                                            the authority for actions
+  oats server forget <id> --instance <name>  drop a saved route whose remote instance is gone
+                                            (the roster shows it as missingRemotely)
+  oats retire <instance> --home <path>       retire exactly that home when two agents own an
+                                            instance of the same name (else refused)
+  oats okf harvest --server <id>             run the knowledge harvest in a remote instance's
+      --instance <name> [--json]            saved home on its host
+  oats session inspect|attach --server <id>  inspect (envelope) or attach a viewer (ssh PTY) for a
+      --instance <name> | --home <abs>       remote instance over its saved route (--print shows
+                                            attach); the server needs oats 0.22.2 or later
   oats create <name> [--local]               create an agent soul; --local = full
       [--description <d>] [--repo <r>]      soul under local-agents/ (uncommitted,
-      [--work <mode>] [--runtime pi|claude] gitignored; same memory + lifecycle)
-      [--model <m>] [--instructions-file <f>]
-  oats spawn <agent> [--task <text>]         spawn an instance (tmux; --no-launch
+      [--work <mode>] [--runtime pi|claude|codex] gitignored; same memory + lifecycle)
+      [--model <m>] [--yolo|--no-yolo] [--instructions-file <f>]
+  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
+  oats spawn <agent> [--task <text>]         spawn an instance (tmux/Herdr; --no-launch
       [--purpose <slug>] [--repo <r>]       = scaffold only); --instructions-file/
       [--parent <instance>]                 --def-file creates a local agent;
       [--relation child|sibling|parent|unrelated]    --relation + --relative-to anchor the
       [--relative-to <instance>]            new instance to an existing one; --parent X
       [--relative-root <agents-root>]       disambiguates same-named team anchors
       [--work worktree|checkout|attached|workspace]  = sugar for --relative-to X --relation
-      [--work-dir <owner-work>] [--runtime pi|claude] [--model <m>] [--branch <b>]  child (default: unrelated, top-level)
+      [--work-dir <owner-work>] [--runtime pi|claude|codex] [--backend tmux|herdr] [--herdr-socket <path>] [--yolo|--no-yolo] [--model <m>] [--branch <b>]  child (default: unrelated, top-level)
       [--instructions-file <f>|--def-file <f>] [--no-launch] [--json]
                                             with team: declared, unknown local souls
                                             resolve across the team scope's repos
   oats retire <instance> [--force]           retire an instance (window, hooks,
       [--self] [--delete-branch]            worktree, home); --self = retire the
-      [--keep-dir] [--json]                 CALLING instance (delayed window kill)
+      [--keep-dir] [--json]                 CALLING instance: the window dies, then
+                                            a detached external retirement runs
   oats doctor [dir] [--soul <name>] [--json] resolved targets, trust, requirements;
                                             --soul shows final composed AGENTS.md
   oats update [--check] [--yes]              check npm for a newer kernel+pi bridge and