@awebai/oats 0.22.2 → 0.22.3

package/bin/oats.mjs

@@ -39,7 +39,7 @@ 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 { 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);
@@ -2777,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`);
@@ -2785,9 +2790,10 @@ 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, { self: isSelf, deleteBranch: args.includes("--delete-branch"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") });
+  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.
@@ -3118,10 +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.
-    // `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"] }));
+    // `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)`);
@@ -3167,8 +3176,41 @@ async function experimentalCmd() {
 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);
+  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") {
@@ -3227,6 +3269,22 @@ function serverRouteCmd() {
   // 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") {
@@ -3278,7 +3336,7 @@ function serverRouteCmd() {
   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)}`);
+    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") {
@@ -3321,7 +3379,7 @@ function serverRouteCmd() {
 // blame` pointing at the commit that last changed each command.
 const TYPED_CLI_FAILURES = new Set(["unsafe-config-key", "unsafe-config-value"]);
 try {
-if (flag("server") !== undefined && ["spawn", "retire", "status", "session"].includes(cmd)) serverRouteCmd();
+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;
@@ -3373,6 +3431,16 @@ Usage:
   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

package/capabilities/oats-aweb/bin/oats-aweb.mjs

@@ -37,7 +37,8 @@
  * identity joined moments before the failure must still be deletable.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
+import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { join, dirname, resolve, delimiter } from "node:path";
 
 /** Run a command as ARGV — never a shell string. Team ids, aliases, instance
@@ -66,6 +67,10 @@ const run = (argv, cwd, timeout = 45000, { secrets = [], secretSafe = false } =
     const why = secretSafe ? "" : (scrub(e.stderr).trim() || (e.status === undefined ? String(e.code || "failed") : ""));
     const err = new Error(`${where} failed${e.status === undefined ? "" : ` (exit ${e.status})`}${why ? `: ${why}` : ""}${secretSafe ? " (output withheld: this command handles credentials)" : ""}`);
     err.status = e.status;
+    // A classification, never the text: the caller may name a KNOWN failure
+    // class (an alias that still holds a certificate) without any output of a
+    // credential-handling command reaching a log.
+    err.aliasConflict = /already|exists|conflict|422|active certificate/i.test(String(e.stderr ?? "") + String(e.stdout ?? ""));
     throw err;
   }
 };
@@ -97,6 +102,17 @@ const fatal = (m, meta) => out({ ...(meta ? { meta } : {}), warning: `oats-aweb:
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
 const home = process.env.OATS_HOME || process.cwd();
+// Effective capability settings, injected by kernel dispatch (OATS_SETTINGS).
+// delivery: "channel" (default) keeps the native channel packages waking the
+// instance; "session" hands delivery to the host wake broker (aweb-abil):
+// AWEB_DELIVERY=session goes into the launch environment, the Claude channel
+// flag is omitted, and nothing wakes the instance until the broker exists.
+let settings = {};
+try { settings = JSON.parse(process.env.OATS_SETTINGS || "{}"); } catch { settings = {}; }
+const deliveryMode = (() => {
+  const v = settings.delivery === undefined || settings.delivery === null || settings.delivery === "" ? "channel" : String(settings.delivery);
+  return v === "session" ? "session" : "channel";
+})();
 
 /**
  * The aweb root (minting authority). BOUNDED candidates — the deployment's team
@@ -148,7 +164,165 @@ if (!onPath("aw")) {
   warn(`aw CLI not on PATH — no identity minted; ${AW_INSTALL}`);
 }
 
+// ---------------------------------------------------------------------------
+// Retained identity (explicit per-soul opt-in): a standing seat keeps its
+// did:aw and address when re-seated as an OATS instance. Per aweb's contract
+// (2026-09-05): copy exactly the identity-authority files from the source
+// .aw into the home's .aw, reconnect the coordination binding with
+// `aw workspace connect`, verify online, heartbeat and status show the new
+// path, and hold a lock BESIDE the source so no second seat can take it.
+// Never copy workspace.yaml, caches or locks; never delete the source; never
+// team-join (that is the mint path, which would try to create the alias
+// again). Retire releases the lock and leaves the identity alone.
+const IDENTITY_AUTHORITY = ["signing.key", "identity.yaml", "teams.yaml", "team-certs", "encryption.yaml", "encryption-keys"];
+// Session delivery registers the home with the host wake broker (aweb-abil:
+// `aw wake register --home <abs> --identity-home <abs> --delivery session
+// [--backend tmux|herdr]`, durable even when the daemon is down). An aw
+// without `aw wake` cannot deliver in session mode: refuse, never silently
+// turn a working channel into a poll-only instance.
+// Throws, never exits: both callers run it inside a try whose catch performs
+// the rollback (the seat path restores the binding; the mint path hands the
+// minted identity to compensation).
+function wakeRegister(instanceHome, identityHome) {
+  const backend = process.env.OATS_BACKEND;
+  try {
+    run(["aw", "wake", "register", "--home", instanceHome, "--identity-home", identityHome, "--delivery", "session", ...(backend ? ["--backend", backend] : [])], instanceHome, 60000);
+  } catch (e) {
+    throw new Error(`delivery: session needs an aw with the wake broker CLI (aw wake register), which this aw does not provide (${e.message || e}); install the aweb release that ships aw wake, or use delivery: channel`);
+  }
+}
+function wakeDeregister(instanceHome) {
+  try { run(["aw", "wake", "deregister", "--home", instanceHome], instanceHome, 60000); return true; } catch { return false; }
+}
+const seatLockPath = (source) => join(dirname(source), ".aw-retained-seat.json");
+const yamlScalar = (text, key) => {
+  const m = String(text).match(new RegExp(`^${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`, "m"));
+  return m ? m[1].trim() : undefined;
+};
+function retainedSeatSpawn(source, takeOver) {
+  if (typeof source !== "string" || !source.startsWith("/")) fatal("identity.source must be the absolute path of the legacy .aw directory to retain");
+  if (!existsSync(join(source, "signing.key"))) fatal(`identity.source ${source} holds no signing.key, so there is no identity to retain`);
+  const lockPath = seatLockPath(source);
+  let takenOver;
+  if (existsSync(lockPath)) {
+    let held; try { held = JSON.parse(readFileSync(lockPath, "utf8")); } catch { held = {}; }
+    const holderHome = held.home;
+    // Held means the holder's home still exists: retire removes both the lock
+    // and the home, so a home that is there is a seat that was never retired.
+    // No process liveness is inferred (the spawner's pid says nothing about the
+    // runtime). The only escape is the explicit, warned take-over for a seat
+    // whose runtime is known to be dead.
+    if (holderHome && existsSync(holderHome)) {
+      if (takeOver !== true) fatal(`identity at ${source} is already held by ${holderHome} (${lockPath}); a seat is never taken from a holder whose home exists — retire that instance first, or set identity.takeOver: true only if you know its runtime is dead`);
+      takenOver = holderHome;
+    }
+  }
+  const srcWorkspace = existsSync(join(source, "workspace.yaml")) ? readFileSync(join(source, "workspace.yaml"), "utf8") : "";
+  const service = process.env.OATS_AWEB_URL || yamlScalar(srcWorkspace, "aweb_url");
+  if (!service) fatal(`cannot determine the aweb service for ${source} (no aweb_url in its workspace.yaml)`);
+  const role = yamlScalar(srcWorkspace, "role_name");
+  let team = process.env.OATS_TEAM_ID;
+  if (!team && existsSync(join(source, "teams.yaml"))) team = yamlScalar(readFileSync(join(source, "teams.yaml"), "utf8"), "active_team") || yamlScalar(readFileSync(join(source, "teams.yaml"), "utf8"), "active");
+  if (!team || !team.includes(":")) fatal(`cannot determine the team for the retained identity (set team.id in oats-config.yaml, or an active team in ${join(source, "teams.yaml")})`);
+  const dest = join(home, ".aw");
+  const legacyHome = dirname(source);
+  // The lock is taken FIRST: a concurrent second spawn must see it before any
+  // byte of the identity is copied.
+  // Exclusive creation (wx): two concurrent spawns cannot both pass the
+  // existence check and overwrite each other; the loser fails here having
+  // copied nothing. A take-over replaces the stale lock first, deliberately.
+  if (takenOver) { try { rmSync(lockPath, { force: true }); } catch { /* replaced below */ } }
+  try {
+    writeFileSync(lockPath, JSON.stringify({ home, instance, team, takenAt: new Date().toISOString(), host: hostname(), ...(takenOver ? { tookOverFrom: takenOver } : {}) }, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+  } catch (e) {
+    fatal(`identity at ${source} was taken by another spawn a moment ago (${lockPath} exists); nothing copied`);
+  }
+  let connected = false;
+  const rollback = () => {
+    // After `aw workspace connect` the server binding points at the new home;
+    // deleting the copy alone would leave the identity bound to nothing. Put
+    // the binding back where it was, from the legacy home, then remove the
+    // copy; if the restore fails, KEEP the copy so the seat stays recoverable.
+    let restored = !connected;
+    if (connected) {
+      try { run(["aw", "workspace", "connect", "--service", service, "--team", team, ...(role ? ["--role", role] : [])], legacyHome, 60000); restored = true; }
+      catch { restored = false; }
+    }
+    if (restored) { try { rmSync(dest, { recursive: true, force: true }); } catch { /* best effort */ } try { rmSync(lockPath, { force: true }); } catch { /* best effort */ } }
+    return restored;
+  };
+  try {
+    mkdirSync(dest, { recursive: true, mode: 0o700 });
+    chmodSync(dest, 0o700);
+    for (const name of IDENTITY_AUTHORITY) {
+      const from = join(source, name);
+      if (!existsSync(from)) continue; // encryption material may be absent on an identity that never had it
+      const to = join(dest, name);
+      if (statSync(from).isDirectory()) {
+        cpSync(from, to, { recursive: true }); chmodSync(to, 0o700);
+        for (const f of readdirSync(to)) { const p = join(to, f); if (statSync(p).isFile()) chmodSync(p, 0o600); } // private keys inside, whatever the source modes were
+      } else { copyFileSync(from, to); chmodSync(to, 0o600); }
+    }
+    for (const forbidden of ["workspace.yaml", "context", "interaction-log.jsonl", "channel-delivered-ids.json", "chat-delivered-ids.json"]) {
+      if (existsSync(join(dest, forbidden))) rmSync(join(dest, forbidden), { recursive: true, force: true });
+    }
+    run(["aw", "workspace", "connect", "--service", service, "--team", team, ...(role ? ["--role", role] : [])], home, 60000);
+    connected = true;
+    run(["aw", "check", "--online"], home, 60000);
+    run(["aw", "heartbeat"], home, 60000);
+    const status = run(["aw", "workspace", "status", "--json"], home, 60000);
+    // Thrown, not fatal: the catch below rolls the copy and the lock back first.
+    // Verified by parsing: the workspace row's path must be this home. The
+    // hostname the row records is whatever the binding stored (on hosted
+    // teams it need not equal this OS hostname), so it is reported, not judged.
+    let st; try { st = JSON.parse(String(status)); } catch { throw new Error(`aw workspace status from ${home} answered no JSON, so the seat is not connected; nothing is briefed`); }
+    const ws = st.workspace && typeof st.workspace === "object" ? st.workspace : st;
+    const shownPath = String(ws.workspace_path || ws.path || "");
+    const same = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
+    if (!shownPath || !same(shownPath, home)) throw new Error(`aw workspace status from ${home} shows workspace_path ${JSON.stringify(shownPath)} not this home, so the seat is not connected; nothing is briefed`);
+    const hostNote = ws.hostname && ws.hostname !== hostname() && ws.hostname.split(".")[0] !== hostname().split(".")[0] ? ` (workspace row hostname ${ws.hostname}, this host ${hostname()})` : "";
+    const identityText = readFileSync(join(dest, "identity.yaml"), "utf8");
+    const expectedDid = yamlScalar(identityText, "did");
+    const expectedAddress = yamlScalar(identityText, "address");
+    // The same-identity check the contract is for: `aw whoami --json` from the
+    // new home reports the did and address the CLI now acts as (workspace
+    // status carries no did); both must equal the copied identity.yaml.
+    let who; try { who = JSON.parse(String(run(["aw", "whoami", "--json"], home, 60000))); } catch (e) { throw new Error(`aw whoami from ${home} answered no JSON (${e.message || e}); the seat is not verified`); }
+    const shownDid = who.did || who.identity?.did;
+    const shownAddress = who.address || who.identity?.address;
+    if (expectedDid && shownDid !== expectedDid) throw new Error(`aw whoami shows did ${shownDid || "(none)"}, not the retained identity's ${expectedDid}; the seat is not the same identity`);
+    if (expectedAddress && shownAddress !== expectedAddress) throw new Error(`aw whoami shows address ${shownAddress || "(none)"}, not the retained identity's ${expectedAddress}; the seat is not the same identity`);
+    const aliasRaw = String(ws.alias || st.alias || (expectedAddress || "").split("/").pop() || instance);
+    if (!/^[a-z0-9][a-z0-9._-]{0,127}$/i.test(aliasRaw)) throw new Error(`aw workspace status reports an alias that is not a plausible alias; the seat is not briefed`);
+    const alias = aliasRaw;
+    if (expectedAddress && !expectedAddress.endsWith(`/${alias}`)) throw new Error(`aw workspace status shows alias ${alias}, not the retained identity's address ${expectedAddress}; the seat is not the same identity`);
+    writeFileSync(lockPath, JSON.stringify({ home, instance, alias, team, takenAt: new Date().toISOString(), host: hostname(), ...(takenOver ? { tookOverFrom: takenOver } : {}) }, null, 2) + "\n", { mode: 0o600 });
+    const launch = (process.env.OATS_RUNTIME || "") === "claude" && deliveryMode === "channel"
+      ? { claude: "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" }
+      : undefined;
+    const env = deliveryMode === "session" ? { AWEB_DELIVERY: "session" } : undefined;
+    const deliveryBrief = deliveryMode === "session"
+      ? ` Notification delivery: external (AWEB_DELIVERY=session); until the host wake broker registers this instance NOTHING wakes you: check \`aw mail inbox\` and \`aw chat pending\` at every task boundary.`
+      : "";
+    if (deliveryMode === "session") wakeRegister(home, dest);
+    const warnings = [];
+    if (takenOver) warnings.push(`oats-aweb: took over the retained identity from ${takenOver} on identity.takeOver: true; if that runtime was still alive there are now two seats with one key — stop the old one`);
+    if (hostNote) warnings.push(`oats-aweb: seated${hostNote}`);
+    out({
+      meta: { team, alias, retained: true, source, lock: lockPath, delivery: deliveryMode, ...(takenOver ? { tookOverFrom: takenOver } : {}) },
+      ...(env ? { env } : {}),
+      brief: `Comms: you are the retained seat of the existing aweb identity "${alias}" on team ${team} (same did and address as the seat you replace; its contacts, routes and conversations are yours).${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill).`,
+      ...(launch ? { launch } : {}),
+      ...(warnings.length ? { warning: warnings.join(" | ") } : {}),
+    });
+  } catch (e) {
+    const restored = rollback();
+    fatal(`retained identity could not be seated from ${source}: ${e.message || e}${connected ? (restored ? " (the server binding was restored to the legacy home and the copy removed)" : ` (the server binding still points at ${home} and the copy was KEPT there so the seat is recoverable: run aw workspace connect from ${legacyHome} to restore it, or retry the spawn)`) : ""}`);
+  }
+}
+
 if (event === "spawn") {
+  if (settings.identity && typeof settings.identity === "object" && settings.identity.source) retainedSeatSpawn(String(settings.identity.source), settings.identity.takeOver === true);
   let minted;                 // external identity, once `aw team join` succeeds
   const root = awebRoot();
   if (!root) fatal(`no initialized aweb root (.aw) among the bounded candidates (home, its git repo, context repo, workspace ${process.env.OATS_WORKSPACE || "?"}), so no identity could be minted and this instance would have no messaging — run \`oats aweb setup\` for guided onboarding`);
@@ -173,7 +347,18 @@ if (event === "spawn") {
     // so neither their output nor their diagnostics may reach a log.
     const inv = parseSecretJson(run(["aw", "team", "invite", "--team-id", team, "--json"], root, 45000, { secretSafe: true }), "aw team invite");
     if (!inv?.token || typeof inv.token !== "string") fatal("aw team invite returned no usable token, so no identity could be minted");
-    const raw = parseSecretJson(run(["aw", "team", "join", inv.token, "--name", instance, "--json"], home, 45000, { secrets: [inv.token], secretSafe: true }), "aw team join");
+    let raw;
+    try {
+      raw = parseSecretJson(run(["aw", "team", "join", inv.token, "--name", instance, "--json"], home, 45000, { secrets: [inv.token], secretSafe: true }), "aw team join");
+    } catch (e) {
+      // A retired alias keeps its certificate until aweb-abim ships, so a
+      // re-spawn under the same name is refused by AWID. Say that, and the
+      // remedy, instead of relaying a bare join error.
+      if (e.aliasConflict) {
+        fatal(`alias "${instance}" already holds a certificate on ${team} (a retired instance of that name is not reusable until aweb-abim ships), so no identity could be minted — spawn with a fresh --purpose instead`);
+      }
+      throw e;
+    }
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) fatal("aw team join returned no usable result, so no identity could be minted", minted);
     // The RESPONSE is not a safe place to take strings from. Suppressing the
     // failure paths does nothing if a successful reply is copied into meta and
@@ -203,13 +388,21 @@ if (event === "spawn") {
     // spawn, which is exactly the silent host mutation the consent gate exists
     // to prevent. By the time this runs the kernel has already proven the plugin
     // is present and enabled, so contributing the flag is safe.
-    const launch = (process.env.OATS_RUNTIME || "") === "claude"
+    // Session delivery: no channel flag, AWEB_DELIVERY=session in the launch
+    // environment (declared in the manifest), and the truth about waking.
+    const launch = (process.env.OATS_RUNTIME || "") === "claude" && deliveryMode === "channel"
       ? { claude: "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" }
       : undefined;
+    const env = deliveryMode === "session" ? { AWEB_DELIVERY: "session" } : undefined;
     const channelWarning = undefined;
+    if (deliveryMode === "session") wakeRegister(home, join(home, ".aw"));
+    const deliveryBrief = deliveryMode === "session"
+      ? ` Notification delivery: external (AWEB_DELIVERY=session): the host wake broker (aw wake) is registered for this home and nudges you when mail or chat arrives; the native aweb channel is not running. If you have waited long with nothing arriving, check \`aw mail inbox\` and \`aw chat pending\` yourself at task boundaries.`
+      : "";
     out({
-      meta: { team: joined.team_id, alias },
-      brief: `Comms: you have an aweb identity — alias "${alias}" on team ${joined.team_id}.${mismatch} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
+      meta: { team: joined.team_id, alias, delivery: deliveryMode },
+      ...(env ? { env } : {}),
+      brief: `Comms: you have an aweb identity — alias "${alias}" on team ${joined.team_id}.${mismatch}${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
       ...(launch ? { launch } : {}),
       ...(mismatch ? { warning: `oats-aweb: team mismatch — joined ${joined.team_id}, expected ${team}` } : channelWarning ? { warning: channelWarning } : {}),
     });
@@ -221,6 +414,14 @@ if (event === "spawn") {
   }
 } else if (event === "retire") {
   const meta = JSON.parse(process.env.OATS_META || "{}");
+  // A retained seat: release the lock and leave the identity alone. Never
+  // aw workspace delete (it would soft-delete the standing identity's row)
+  // and never team retire; the source .aw stays until a human removes it.
+  if (meta.delivery === "session") { if (!wakeDeregister(home)) process.stderr.write("oats-aweb: aw wake deregister failed; the broker treats a retired home as inactive on its own\n"); }
+  if (meta.retained) {
+    if (meta.lock) { try { rmSync(meta.lock, { force: true }); } catch { /* the lock may already be gone */ } }
+    out({ meta: { retired: true, retained: true, identityReleased: true, ...(meta.tookOverFrom ? { tookOverFrom: meta.tookOverFrom } : {}) }, warning: `oats-aweb: released the retained identity "${meta.alias}" (lock ${meta.lock || "?"} removed); the identity itself and ${meta.source || "its source"} are untouched${meta.tookOverFrom ? `; this seat had taken over from ${meta.tookOverFrom}` : ""}` });
+  }
   // No alias means the spawn hook never reported an identity: nothing exists to
   // undo, which is completion. An alias WITH no local `.aw` is the opposite —
   // the remote record exists and its key is gone, so the self-delete cannot be
@@ -233,7 +434,11 @@ if (event === "spawn") {
     // Self-delete from inside the home, authenticated by its own key — a remote
     // delete would 409 until the server marks the workspace stale.
     run(["aw", "workspace", "delete", meta.alias], home);
-    out({ meta: { retired: true } });
+    // Honest: the workspace row is deleted, but a hosted local member cannot
+    // revoke its own AWID certificate (aweb-abim), so the alias is NOT
+    // reusable. retired stays true because the cleanup is as complete as the
+    // platform allows; the field and the line carry the truth.
+    out({ meta: { retired: true, aliasReusable: false }, warning: `oats-aweb: workspace "${meta.alias}" deleted; its certificate is not revoked (aweb-abim), so the alias is not reusable — spawn successors with a fresh --purpose` });
   } catch (e) {
     // Exit nonzero: during a required-hook rollback this is the signal that
     // compensation did NOT complete, so the spawn is not reported as cleanly

package/capabilities/oats-aweb/injects/aweb.md

@@ -40,6 +40,12 @@ Aliases are instance names (e.g. `dev-coordinator-1`). Discovery:
 `oats status --team` lists this machine's live instances; `oats aweb roster`
 lists the aweb team across machines.
 
+**Notification delivery.** Your instance briefing (TASK.md, the Comms line)
+says how messages reach you. If it carries "Notification delivery: external",
+the native channel is NOT running in this session and, until the host wake
+broker registers you, nothing wakes you: check `aw mail inbox` and
+`aw chat pending` at every task boundary. Otherwise the rule below applies.
+
 **Never sleep, poll, or busy-wait for another agent's reply.** Send your
 message, finish your turn, and go idle when a delivery channel is configured
 (you saw `✓ aweb connected` at startup). Native Codex has no aweb channel:

package/capabilities/oats-aweb/oats.json

@@ -1,9 +1,9 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "compatibility": {
-    "oats": ">=0.19.0"
+    "oats": ">=0.22.3"
   },
   "layer": "messaging",
   "description": "Messaging layer via aweb: per-instance team identities + native aw mail/chat skills + cross-machine team roster.",
@@ -16,15 +16,32 @@
     {
       "runtime": "pi",
       "package": "npm:@awebai/pi",
-      "why": "the aweb channel extension for pi sessions — real-time mail/chat awakenings; without it a pi instance can send with `aw` but is never woken by incoming messages",
-      "install": "https://aweb.ai/docs (installed into pi with `pi install npm:@awebai/pi`)"
+      "why": "the aweb channel extension for pi sessions \u2014 real-time mail/chat awakenings; without it a pi instance can send with `aw` but is never woken by incoming messages",
+      "install": "https://aweb.ai/docs (installed into pi with `pi install npm:@awebai/pi`)",
+      "when": {
+        "delivery": "channel"
+      }
     },
     {
       "runtime": "claude",
       "package": "aweb-channel@awebai-marketplace",
       "marketplace": "awebai/claude-plugins",
-      "why": "the aweb channel plugin for Claude Code sessions — real-time mail/chat awakenings; without it a Claude instance can send with `aw` but is never woken by incoming messages",
-      "install": "https://aweb.ai/docs (installs the awebai marketplace and the aweb-channel plugin into Claude Code)"
+      "why": "the aweb channel plugin for Claude Code sessions \u2014 real-time mail/chat awakenings; without it a Claude instance can send with `aw` but is never woken by incoming messages",
+      "install": "https://aweb.ai/docs (installs the awebai marketplace and the aweb-channel plugin into Claude Code)",
+      "when": {
+        "delivery": "channel"
+      }
+    },
+    {
+      "runtime": "pi",
+      "package": "npm:@awebai/pi",
+      "minVersion": "0.3.10",
+      "when": {
+        "delivery": "session"
+      },
+      "why": "an ambient aweb pi extension, if one is installed, must honour AWEB_DELIVERY=session (0.3.10 and later); an older one would open a second event stream beside the wake broker; no extension at all is fine",
+      "install": "pi install npm:@awebai/pi@latest",
+      "ifInstalled": true
     }
   ],
   "skills": [
@@ -43,5 +60,21 @@
       "required": true
     },
     "retire": "bin/oats-aweb.mjs retire"
-  }
+  },
+  "environment": [
+    "AWEB_DELIVERY"
+  ],
+  "settings": {
+    "delivery": {
+      "default": "channel",
+      "values": [
+        "channel",
+        "session"
+      ],
+      "description": "channel: the native aweb channel packages wake the instance (default). session: delivery is external (AWEB_DELIVERY=session), no channel flag; the host wake broker registers the instance once it exists."
+    }
+  },
+  "environmentNamespaces": [
+    "AWEB_"
+  ]
 }

package/docs/capability-manifest.schema.json

@@ -119,6 +119,20 @@
               "marketplace": {
                 "type": "string",
                 "description": "Optional source to register before installing (Claude marketplaces). Shown at the consent prompt, since registering a third-party source is part of what is being agreed to."
+              },
+              "when": {
+                "type": "object",
+                "description": "Applies only when every named capability setting has the given effective value (a requirement conditional on configuration, e.g. delivery: channel).",
+                "additionalProperties": {}
+              },
+              "minVersion": {
+                "type": "string",
+                "description": "Lowest acceptable installed version of the package, read from the package.json under the install directory the runtime's listing names; an older or absent manifest fails the requirement with the install remedy.",
+                "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+"
+              },
+              "ifInstalled": {
+                "type": "boolean",
+                "description": "When true, an absent package satisfies the row; the row's minVersion and loadability checks apply only to a package that is installed (an ambient extension that must honour a contract if present)."
               }
             },
             "additionalProperties": false
@@ -217,6 +231,33 @@
         "type": "string"
       },
       "description": "Package-relative soul directories (soul.yaml + AGENTS.md) \u2014 capability-defined agents; they resolve like local souls where the capability is active, souls stay read-only in the package, instances home under the scope's local-agents/."
+    },
+    "settings": {
+      "type": "object",
+      "description": "Declared capability settings: name to { default, values?, description }. Documentation for `oats use --settings`; undeclared settings are still accepted.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "default": {},
+          "values": {
+            "type": "array",
+            "description": "Accepted scalar values; an effective value outside the list is refused at resolution.",
+            "items": {}
+          },
+          "description": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "environmentNamespaces": {
+      "type": "array",
+      "description": "Additional environment-name prefixes this capability may declare besides its vendor's own (e.g. AWEB_ for the official oats.aweb integration). Each is an uppercase prefix ending in an underscore; the reserved core (OATS_, PI_AGENT_) and process bootstrap namespaces cannot be claimed. Disclosed at trust time with the environment list.",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Z][A-Z0-9]*_$"
+      }
     }
   },
   "additionalProperties": false

package/docs/execution-targets.md

@@ -179,3 +179,32 @@ inspection before attaching over SSH. Pending inspections share the terminal
 resource limit and duplicate requests share one inspection. Remote status and
 instance keys must include the server so identical paths on different hosts
 remain distinct.
+
+## Desktop remote roster and lifecycle
+
+Desktop uses the installed CLI's `server roster --json` feature when advertised.
+It refreshes one aggregate roster at a time, independently of terminal traffic;
+the CLI owns SSH deadlines, server registration and saved routes. Each target
+appears in the workspace selector with its souls and instances. An unreachable
+target stays visible with unknown runtime state and an error. A saved route
+remains visible after its registration is removed or changed.
+
+Choose the server workspace to spawn one of its souls. A successful launch
+switches to that workspace and opens the instance terminal once it appears in
+the roster. The instance action menu offers harvest and retirement, including
+for stopped agents. Remote harvest runs in the saved home on the execution host;
+retirement uses the same saved route and work-preservation rules as the CLI.
+Closing a viewer leaves the agent running.
+
+Desktop retirement requires the CLI's `retire-home` feature and always sends
+the exact selected home. The remote kernel must support that feature too;
+older kernels require an upgrade before the GUI can retire an instance.
+This keeps same-named instances distinct. Retirement feedback reports every
+preserved recovery path and its classes, including an incomplete cleanup.
+
+This first projection enables terminal and lifecycle actions only for remote
+instances with a route saved on this machine. Other observed instances are
+listed, but require the execution host's CLI to manage them. Remote brain files
+are accessed through the terminal. The roster and remote harvest require CLI
+feature tokens `roster` and `harvest`; the published 0.22.2 kernel has remote
+spawn, status, retirement and terminals, but not these two additions.