@awebai/oats 0.22.0 → 0.22.2

package/README.md

@@ -14,11 +14,12 @@ 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. Every conversation an agent has is
-captured into an append-only, searchable **turn record** that outlives models,
-harnesses, and this repository's own designs.
+lifecycle, and coordination topology. On machines where `oats setup` has run,
+the append-only, searchable **turn record** captures supported local transcripts
+and aw client logs. It outlives models, harnesses, and this repository's own
+designs.
 
 ## Contents
 
@@ -44,7 +45,7 @@ harnesses, and this repository's own 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.
@@ -63,56 +64,34 @@ harnesses, and this repository's own designs.
   `sibling` relationships, can carry cross-machine identities through a
   messaging layer such as `oats.aweb`, and are visible together in OATS
   Desktop.
-- **Everything is on the record.** Claude Code, Pi, and Codex sessions, plus
-  aweb mail and chat, are captured as signed turns with exact provenance and
-  searched locally with `oats recall`.
+- **Supported conversations stay on the record.** On machines where `oats
+  setup` has run, OATS captures Claude Code, Pi, and Codex transcripts plus aw
+  client logs. It skips sources matched by the local record's ignore list.
+  Native session turns are content-addressed, not signed, and carry exact
+  provenance. Projected aweb mail and chat keep their original message
+  signatures verbatim. Search the captured content locally with `oats recall`.
 
 ## Quick start
 
-Requires Node.js 22 or newer and tmux.
+Follow [Run your first OATS team](docs/first-team.md) for the tested path:
+install the kernel and runtimes, adopt a development configuration, select
+an available harvester model, connect your team, and complete a real task
+through review, harvest, and retirement.
 
 ```bash
 npm install -g @awebai/oats@latest
-pi install npm:@awebai/oats-pi@latest   # only if you run agents in Pi
-```
-
-Initialize a workspace and check it:
-
-```bash
-cd my-workspace
-oats init
-oats doctor
-```
-
-Create a specialist and put it to work:
-
-```bash
-oats create backend-expert --type developers --repo . --work worktree
-oats spawn backend-expert --purpose implement --task "Add rate limiting to the public API"
-oats status --team
-oats retire <instance>
-```
-
-Or adopt a complete reference configuration from an official package:
-
-```bash
+pi install npm:@awebai/oats-pi@latest
+cd /path/to/project
 oats init --package oats.dev --config default
-oats install
 ```
 
-`oats init --package` acquires and exact-locks the full closure, validates the
-chosen template against its providers, writes it as your local
-`oats-config.yaml`, and records the adopted base so `oats config diff` and
-`oats config sync` can compare against it later.
+Continue with the guide's model, team, and executable-trust setup before
+spawning. Initialization acquires packages; it does not authenticate a
+runtime or join a messaging team.
 
-Start capturing the turn record on this machine:
-
-```bash
-oats setup
-oats recall "rate limiting"
-```
-
-A Pi agent can also load the `oats-getting-started` skill and guide the setup.
+See [the first-team example](docs/first-team-demo.md) for the real Pi and
+Claude tasks behind the guide. Existing OAS users: start with
+[the migration command](docs/migration-from-oas.md).
 
 ## How it works
 
@@ -166,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
 
@@ -207,10 +187,13 @@ Bare `oats install` restores the exact lock and never advances source state.
 
 ## The turn record
 
-`packages/record` is the load-bearing layer. Every conversation an agent has
-is captured as signed turns in an append-only, content-addressed, replicated
-record with exact provenance, and searched locally through a SQLite full-text
-index. It has no runtime dependencies beyond Node.
+`packages/record` is the load-bearing layer. On each machine where `oats setup`
+has run, it captures Claude Code, Pi, and Codex transcripts plus aw client logs.
+It skips sources matched by that record root's ignore list. Native session
+turns are content-addressed, not signed, and carry exact provenance. Projected
+aweb mail and chat keep their original message signatures verbatim. The
+append-only record can be replicated and searched locally through a SQLite
+full-text index. It has no runtime dependencies beyond Node.
 
 ```bash
 oats setup                 # install capture hooks and the background watcher
@@ -323,6 +306,7 @@ forms. Do not hand-edit the lock or installed stores.
 - [OATS Desktop](docs/desktop.md)
 - [Migration from OAS](docs/migration-from-oas.md)
 - [Release notes](docs/release-notes/)
+- [Architecture proposal, 2026-09-03](docs/2026-09-03-architecture-proposal.md): components, contracts, and what may be replaced (proposal, not shipped behavior)
 
 ## Contributing
 
@@ -378,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, getServer, inspectRemote, listSnapshots, readServers, 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}`);
@@ -2768,6 +2788,16 @@ function retireCmd() {
     if (hit && resolve(hit.root) !== resolve(root)) { root = hit.root; console.log(`(cross-repo: instance homes at ${shortPath(root)})`); }
   }
   const r = retireInstance(root, name, { 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;
+  }
   // 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,30 +2825,56 @@ 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();
-  // --local can BOOTSTRAP a deployment: with no agents/ or local-agents/ yet,
-  // anchor at the enclosing git repo (else the start dir) — people can use OATS
-  // with local agents alone.
+  // `create` BOOTSTRAPS a deployment: with no agents/ or local-agents/ yet,
+  // anchor at the enclosing git repo (else the start dir). It is the command
+  // that populates the roster root, so it must not demand that the root
+  // already exist — that demand was the first thing a new user hit after
+  // `oats init` (a raw stack trace from ensureRoot). Local and committed souls
+  // anchor the same way; writeSoul creates the directories.
   let root = findRoot(startDir);
+  let bootstrapped = false;
   if (!root) {
-    if (!local) root = ensureRoot(startDir); // keeps the pointed error for committed souls
-    else root = join(defaultRepo(startDir) || resolve(startDir), "agents");
+    root = join(defaultRepo(startDir) || resolve(startDir), "agents");
+    bootstrapped = true;
   }
   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, null, 2)); return; }
+  if (args.includes("--json")) { console.log(JSON.stringify({ ...r, ...(bootstrapped ? { agentsRoot: root } : {}) }, null, 2)); return; }
+  if (bootstrapped) console.log(`Created deployment root ${shortPath(root)} (this scope had no agents/ yet)`);
   console.log(`Created ${r.kind === "local" ? "LOCAL agent (uncommitted — soul lives in local-agents/, gitignored)" : "agent"} "${r.agent}" — soul at ${shortPath(r.soul)}`);
   console.log(`Edit ${shortPath(join(r.soul, "AGENTS.md"))} to define its role, then: oats spawn ${r.agent} --task "..."`);
 }
@@ -3062,7 +3118,10 @@ 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`: the commands this kernel routes to a registered server with
+    // --server; a Desktop gates its remote path on it (an older CLI without
+    // the surface must fail closed with a reason, not an argument error).
+    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"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3101,6 +3160,152 @@ 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>  [--json]";
+  if (!["add", "list", "remove", "check"].includes(sub)) bail("E_USAGE", usage);
+  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 === "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: ${shortPath(r.snapshot)}`);
+    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
@@ -3116,7 +3321,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"].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);
 }
@@ -3137,6 +3344,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();
@@ -3158,24 +3366,36 @@ 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 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

package/capabilities/oats-authoring/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OATS Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/capabilities/oats-authoring/oats-package.json

@@ -0,0 +1,11 @@
+{
+  "package": "oats.authoring",
+  "version": "1.0.0",
+  "description": "Official additive OATS guidance for capability, skill, and soul authoring.",
+  "compatibility": {
+    "oats": ">=0.19.0"
+  },
+  "capabilities": [
+    "."
+  ]
+}

package/capabilities/oats-authoring/oats.json

@@ -1,12 +1,12 @@
 {
   "capability": "oats.authoring",
   "version": "1.0.0",
-  "compatibility": { "oats": ">=0.6.2" },
+  "compatibility": { "oats": ">=0.19.0" },
   "description": "Additive framework-authoring guidance for capability packages, agent skills, and souls.",
   "requires": [],
   "skills": [
-    "../../skills/integration-authoring",
-    "../../skills/skill-craft",
-    "../../skills/soul-craft"
+    "skills/integration-authoring",
+    "skills/skill-craft",
+    "skills/soul-craft"
   ]
 }