@awebai/oats 0.30.2 → 0.31.0

package/lib/servers.mjs

@@ -18,9 +18,9 @@
 
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { parseStrictJson } from "./canonical-json.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
 
@@ -30,8 +30,66 @@ export const REMOTE_SNAPSHOT_DIR = () => join(OATS_HOME_DIR(), "remote");
 
 /** Every ssh invocation is non-interactive: a host that needs a password or a
  *  first-time key confirmation fails fast with ssh's own message, instead of
- *  a lifecycle call hanging on a prompt nobody will answer. */
-const SSH_OPTS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=15"];
+ *  a lifecycle call hanging on a prompt nobody will answer. Keepalives end a
+ *  call (an attached viewer included) whose link died without a reset: three
+ *  unanswered 15 s probes, not a hang until TCP gives up. */
+const SSH_OPTS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=15", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3"];
+
+/** Every routed call to one host shares one per-user control master: the
+ *  probe, the command and an attached viewer ride one authenticated
+ *  connection, kept 60 s after the last client leaves. Explicit -o wins over
+ *  a user's own Control* settings in ~/.ssh/config. */
+const SSH_CONTROL_DIR = () => join(OATS_HOME_DIR(), "ssh");
+const controlOpts = () => ["-o", "ControlMaster=auto", "-o", `ControlPath=${join(SSH_CONTROL_DIR(), "%C")}`, "-o", "ControlPersist=60"];
+// Without the master, sharing is switched off outright: a user's own
+// ControlMaster/ControlPath in ~/.ssh/config would otherwise still apply.
+const NO_CONTROL_OPTS = ["-o", "ControlPath=none"];
+// ssh binds the master at `<ControlPath>.<16 random chars>` in a sun_path of
+// 104 bytes (macOS; Linux has 108), NUL included, and a path that does not
+// fit is fatal to the call. %C expands to 40 hex characters.
+const SOCKET_PATH_LIMIT = 104;
+const BIND_SUFFIX = 17;
+const controlSocketBytes = () => Buffer.byteLength(join(SSH_CONTROL_DIR(), "x".repeat(40)));
+// ssh reads an -o value as configuration syntax (whitespace splits it,
+// quotes and # are syntax) and then expands %tokens and ${VAR} in the path:
+// only a directory made of characters it takes literally is the path it binds.
+const LITERAL_PATH_RE = /^[A-Za-z0-9._\/+,:@=-]+$/;
+
+/** Why the control socket cannot live under the control directory, or null. */
+function controlPathProblem() {
+  const dir = SSH_CONTROL_DIR();
+  if (!LITERAL_PATH_RE.test(dir)) return `the control directory ${dir} has characters ssh reads as syntax (only letters, digits and . _ / + , : @ = - are taken literally); set an OATS_HOME_DIR (or HOME) without them`;
+  if (controlSocketBytes() + BIND_SUFFIX >= SOCKET_PATH_LIMIT) return `the control socket path ${join(dir, "%C")} expands to ${controlSocketBytes()} bytes, and ssh needs it to fit in ${SOCKET_PATH_LIMIT - BIND_SUFFIX - 1} (the ${SOCKET_PATH_LIMIT}-byte socket path limit less ssh's ${BIND_SUFFIX}-byte bind suffix); set a shorter OATS_HOME_DIR (or HOME)`;
+  return null;
+}
+
+/** Whether this call may use the control master: the socket path is
+ *  literal to ssh and fits, and the directory exists, private to this user (created 0700; one owned by
+ *  someone else or writable by others is never handed to ssh). Otherwise the
+ *  call runs with sharing off, with one warning per process per server:
+ *  reuse is an optimisation and must never break routing. */
+const controlWarned = new Set();
+function controlUsable(target, io = {}) {
+  let problem = controlPathProblem();
+  if (!problem) {
+    const dir = SSH_CONTROL_DIR();
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      const st = lstatSync(dir);
+      if (!st.isDirectory()) problem = `${dir} is not a directory`;
+      else if (typeof process.getuid === "function" && st.uid !== process.getuid()) problem = `${dir} is owned by another user`;
+      else if (st.mode & 0o022) problem = `${dir} is writable by group or others (mode ${(st.mode & 0o777).toString(8)}); make it private with chmod 700`;
+    } catch (e) { problem = `${dir} cannot be created: ${e.message}`; }
+  }
+  if (!problem) return true;
+  const key = io.serverId ?? target.sshHost;
+  if (!controlWarned.has(key)) {
+    controlWarned.add(key);
+    const warn = io.warn || ((m) => process.stderr.write(`oats: warning: ${m}\n`));
+    warn(`ssh to ${key} runs without connection reuse: ${problem}`);
+  }
+  return false;
+}
 
 const ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const SSH_HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/; // an OpenSSH alias or host name, never a user@ or option
@@ -55,28 +113,43 @@ export function readServers() {
   if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
     throw serverError("E_SERVERS_UNREADABLE", `${file} must be { "servers": { <id>: {...} } }`);
   }
-  for (const [id, s] of Object.entries(servers)) validateServer(id, s);
-  return servers;
+  const out = {};
+  for (const [id, s] of Object.entries(servers)) { out[id] = withoutHerdrPath(s); validateServer(id, out[id]); }
+  return out;
 }
 
 export function writeServers(servers) {
   const file = SERVERS_FILE();
+  // A registration whose target changes (server add --replace) is probed afresh.
+  let prior = {};
+  try { prior = readServers(); } catch { prior = {}; }
+  for (const [id, s] of Object.entries(prior)) {
+    if (!servers[id] || JSON.stringify(targetOf(servers[id])) !== JSON.stringify(targetOf(s))) dropRemoteProbes(id);
+  }
   mkdirSync(OATS_HOME_DIR(), { recursive: true });
   writeFileSync(file, JSON.stringify({ servers }, null, 2) + "\n", { mode: 0o600 });
 }
 
+/** A registration or saved route written before 0.31.0 may record `herdrPath` (Herdr was removed
+ *  then): it is read and dropped, never written, printed or passed. */
+function withoutHerdrPath(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry) || !Object.hasOwn(entry, "herdrPath")) return entry;
+  const { herdrPath: _ignored, ...rest } = entry;
+  return rest;
+}
+
 /** A registration names WHERE and HOW, never WITH WHAT credentials. */
 export function validateServer(id, s) {
   if (!ID_RE.test(String(id))) throw serverError("E_SERVER_INVALID", `server id ${JSON.stringify(id)} must be lowercase letters, digits and dashes`);
   if (!s || typeof s !== "object" || Array.isArray(s)) throw serverError("E_SERVER_INVALID", `server ${id}: entry must be an object`);
   if (typeof s.sshHost !== "string" || !SSH_HOST_RE.test(s.sshHost)) throw serverError("E_SERVER_INVALID", `server ${id}: sshHost must be an OpenSSH host alias or host name (no user@, no options)`);
   if (typeof s.workspace !== "string" || !s.workspace.startsWith("/")) throw serverError("E_SERVER_INVALID", `server ${id}: workspace must be an absolute path on the server`);
-  for (const k of ["oatsPath", "herdrPath", "label", "path"]) {
+  for (const k of ["oatsPath", "label", "path"]) {
     if (s[k] !== undefined && s[k] !== null && typeof s[k] !== "string") throw serverError("E_SERVER_INVALID", `server ${id}: ${k} must be a string`);
   }
   if (s.path !== undefined && s.path !== null && !s.path.split(":").every((d) => d.startsWith("/") || d.startsWith("~/"))) throw serverError("E_SERVER_INVALID", `server ${id}: path must be absolute directories on the server, colon-separated`);
   for (const k of Object.keys(s)) {
-    if (!["label", "sshHost", "workspace", "oatsPath", "herdrPath", "path"].includes(k)) throw serverError("E_SERVER_INVALID", `server ${id}: unknown field ${JSON.stringify(k)} (a registration holds label, sshHost, workspace, oatsPath, herdrPath, path and nothing else — never keys or passwords)`);
+    if (!["label", "sshHost", "workspace", "oatsPath", "path"].includes(k)) throw serverError("E_SERVER_INVALID", `server ${id}: unknown field ${JSON.stringify(k)} (a registration holds label, sshHost, workspace, oatsPath, path and nothing else — never keys or passwords)`);
   }
   return true;
 }
@@ -107,7 +180,6 @@ export function targetOf(server) {
     sshHost: server.sshHost,
     workspace: server.workspace,
     oatsPath: server.oatsPath || "oats",
-    ...(server.herdrPath ? { herdrPath: server.herdrPath } : {}),
     ...(server.path ? { path: server.path } : {}),
   };
 }
@@ -124,7 +196,7 @@ export function targetKey(target) {
   return createHash("sha256").update(`${target.sshHost}\0${target.workspace}`).digest("hex").slice(0, 12);
 }
 
-export function sshArgv(target, oatsArgs, { cwd } = {}) {
+export function sshArgv(target, oatsArgs, { cwd, control = false } = {}) {
   // A non-interactive ssh command runs in the login shell's minimal PATH,
   // which rarely includes user-local tool directories (~/.local/bin, where
   // claude and pi commonly live). A registration may name directories to
@@ -136,8 +208,10 @@ export function sshArgv(target, oatsArgs, { cwd } = {}) {
   const prefix = dirs.length ? `PATH=${dirs.join(":")}:"$PATH" ` : "";
   // An optional working directory for commands that read their instance
   // from cwd (oats okf harvest): a quoted cd, never a path from the caller.
+  // Sharing is on only when the caller checked the control directory
+  // (controlUsable); otherwise ControlPath=none.
   const cmd = (cwd ? `cd ${remoteQuote(cwd)} && ` : "") + prefix + [target.oatsPath, ...oatsArgs].map(remoteQuote).join(" ");
-  return ["ssh", ...SSH_OPTS, "--", target.sshHost, cmd];
+  return ["ssh", ...SSH_OPTS, ...(control && !controlPathProblem() ? controlOpts() : NO_CONTROL_OPTS), "--", target.sshHost, cmd];
 }
 
 // ------------------------------------------------------------------ running
@@ -182,18 +256,23 @@ export function parseRemoteEnvelope(stdout) {
  *  refused key, unknown host) surface as E_SSH with ssh's stderr. */
 export function runRemote(target, oatsArgs, io = {}) {
   const exec = io.execFileSync || execFileSync;
-  const [bin, ...argv] = sshArgv(target, oatsArgs, { cwd: io.cwd });
+  const [bin, ...argv] = sshArgv(target, oatsArgs, { cwd: io.cwd, control: controlUsable(target, io) });
   let stdout = "";
   let stderr = "";
   let status = 0;
+  let started = true;
   try {
     // `io.input` (a Buffer) streams to the remote command's stdin: the only
     // way bytes reach a host, as a quoted argument never could.
     stdout = exec(bin, argv, { encoding: "utf8", stdio: [io.input === undefined ? "ignore" : "pipe", "pipe", "pipe"], ...(io.input === undefined ? {} : { input: io.input }), maxBuffer: 16 * 1024 * 1024, timeout: io.timeoutMs || 300000 });
   } catch (e) {
     stdout = String(e.stdout || "");
-    stderr = String(e.stderr || e.message || "");
+    // The process's own stderr when it ran (possibly empty); the error's
+    // message only when there was no process to speak (ssh not found).
+    stderr = String(e.stderr ?? e.message ?? "");
     status = typeof e.status === "number" ? e.status : 255;
+    // Neither an exit status nor a signal: ssh never started (not installed, not executable).
+    started = typeof e.status === "number" || !!e.signal;
   }
   if (String(stdout).trim()) {
     const envelope = parseRemoteEnvelope(stdout);
@@ -207,22 +286,51 @@ export function runRemote(target, oatsArgs, io = {}) {
   }
   // ssh exits 255 for its own failures; the remote command's exit code is
   // relayed otherwise. Either way with no envelope there is nothing to trust.
-  throw serverError(status === 255 ? "E_SSH" : "E_REMOTE_ENVELOPE", `${status === 255 ? "ssh failed" : `remote oats exited ${status} with no envelope`}: ${stderr.trim().slice(0, 400) || "(no output)"}`);
+  // An ssh that never started is still E_SSH to callers, with `details: { sshStarted: false }` (it reaches
+  // the --json envelope): there is no link to come back. No details means ssh started.
+  const error = serverError(status === 255 ? "E_SSH" : "E_REMOTE_ENVELOPE", `${status === 255 ? `ssh to ${target.sshHost} failed` : `remote oats exited ${status} with no envelope`}: ${stderr.trim().slice(0, 400) || "(no output)"}`);
+  if (status === 255 && !started) error.details = { sshStarted: false };
+  throw error;
 }
 
 /** Version and envelope compatibility, checked BEFORE any mutation. The
  *  remote must answer `version --json` with the Desktop API v1 probe payload
  *  and a kernel the local side knows how to talk to. */
 export function checkRemote(target, io = {}) {
+  const probes = probesOf(io);
+  const key = probeKey(io.serverId, target);
+  const remote = probes.get(key) || probeRemote(target, io);
+  probes.set(key, remote);
+  const min = io.minVersion || MIN_REMOTE_VERSION;
+  if (compareSemver(remote.version, min) < 0) {
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} is older than the minimum ${min} this kernel routes to; upgrade it there`);
+  }
+  return remote;
+}
+
+/** The version probe is asked once per process per server id and target: a
+ *  command that probes, resolves and then acts asks the host once. The cache
+ *  belongs to the transport (the process's ssh, or a caller's injected one)
+ *  and holds successful answers only. */
+const probeCaches = new Map();
+const probesOf = (io) => {
+  const exec = io.execFileSync || execFileSync;
+  if (!probeCaches.has(exec)) probeCaches.set(exec, new Map());
+  return probeCaches.get(exec);
+};
+const probeKey = (serverId, target) => JSON.stringify([serverId ?? null, target.sshHost, target.workspace, target.oatsPath, target.path ?? null]);
+
+/** Forget every probe of a server id: its registration changed. */
+export function dropRemoteProbes(serverId) {
+  for (const probes of probeCaches.values()) for (const key of probes.keys()) if (JSON.parse(key)[0] === serverId) probes.delete(key);
+}
+
+function probeRemote(target, io) {
   const { envelope } = runRemote(target, ["version", "--json"], { ...io, timeoutMs: 60000 });
   const probe = envelope.result || {};
   if (probe.desktopApi !== 1 || typeof probe.version !== "string") {
     throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
   }
-  const min = io.minVersion || MIN_REMOTE_VERSION;
-  if (compareSemver(probe.version, min) < 0) {
-    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${probe.version} at ${target.sshHost} is older than the minimum ${min} this kernel routes to; upgrade it there`);
-  }
   // What the remote kernel advertises it can launch. A probe without these
   // fields is a 0.22.1-class kernel: pi and claude only, no session backend
   // choice, no launch options; nothing newer may be requested of it. The
@@ -239,6 +347,7 @@ export function checkRemote(target, io = {}) {
     features: list("features", []),
     operationsApi: [1, 2].includes(probe.operationsApi) ? probe.operationsApi : null,
     scheduleApi: [1, 2].includes(probe.scheduleApi) ? probe.scheduleApi : null,
+    ...Object.fromEntries(["readinessApi", "eventsApi", "instanceGitApi", "lifecycleApi"].map((k) => [k, Number.isInteger(probe[k]) ? probe[k] : null])),
     advertised: Array.isArray(probe[harnessKey]),
   };
 }
@@ -339,11 +448,18 @@ export function writeSnapshot(serverId, target, remote, spawnResult) {
 export function readSnapshot(serverId, instance) {
   const p = snapshotPath(serverId, instance);
   if (!existsSync(p)) return undefined;
+  let snap;
   try {
-    return JSON.parse(readFileSync(p, "utf8"));
+    snap = JSON.parse(readFileSync(p, "utf8"));
   } catch (e) {
     throw serverError("E_SNAPSHOT_UNREADABLE", `${p}: ${e.message}`);
   }
+  return savedRoute(snap);
+}
+
+/** A saved route as read: its frozen target without any recorded `herdrPath`. */
+function savedRoute(snap) {
+  return snap && typeof snap === "object" && !Array.isArray(snap) && snap.target ? { ...snap, target: withoutHerdrPath(snap.target) } : snap;
 }
 
 export function removeSnapshot(serverId, instance) {
@@ -368,7 +484,7 @@ export function listSnapshots(serverId) {
   for (const f of readdirSync(dir)) {
     if (!f.endsWith(".json")) continue;
     try {
-      out.push(JSON.parse(readFileSync(join(dir, f), "utf8")));
+      out.push(savedRoute(JSON.parse(readFileSync(join(dir, f), "utf8"))));
     } catch {
       out.push({ serverId, instance: f.replace(/\.json$/, ""), unreadable: true });
     }
@@ -386,6 +502,9 @@ export function listSnapshots(serverId) {
  *    when the remote kernel reports the home gone;
  *  - status: pulled from the remote kernel, never cached. */
 export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
+  io = { ...io, serverId };
+  // The host's reads and plans resolve their own route: a saved one needs no registration.
+  if (cmd === "readiness" || cmd === "instance" || (cmd === "retire" && oatsArgs.includes("--plan"))) return routeHostSurface(serverId, cmd, oatsArgs, io);
   // A retirement may outlive its registration: the snapshot taken at spawn
   // is the route, and it is consulted before the registry is required.
   const instanceArg = oatsArgs.find((a) => !a.startsWith("--"));
@@ -451,8 +570,20 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     const hi = oatsArgs.indexOf("--home");
     const explicitHome = hi >= 0 && oatsArgs[hi + 1] && !oatsArgs[hi + 1].startsWith("--") ? oatsArgs[hi + 1] : undefined;
     if (explicitHome && snap?.home && resolve(explicitHome) !== resolve(snap.home)) throw serverError("E_HOME_MISMATCH", `--home ${explicitHome} is not the saved route of ${name} on ${serverId} (${snap.home}); retire the saved one, or retire the other instance on the host by its own name`);
+    // A guarded apply carries the revision of a plan: the host must speak the lifecycle contract.
+    const guarded = oatsArgs.includes("--plan-revision") || oatsArgs.includes("--idempotency-key");
+    if (guarded) requireSurface(remote, target, HOST_SURFACES["retire plan"]);
     const remoteRetiresByHome = Array.isArray(remote?.features) && remote.features.includes("retire-home");
-    const wantHome = explicitHome || snap?.home;
+    // No saved route and no --home: the name resolves through the host's
+    // roster to its one home, so a same-named twin is never the one retired.
+    // A guarded apply whose name the host no longer lists goes as is: the
+    // host replays the receipt recorded under its key, or refuses.
+    let hostHome;
+    if (name && !explicitHome && !snap?.home) {
+      try { hostHome = instanceOnHost(serverId, name, { ...io, server }).home; }
+      catch (e) { if (!(guarded && e.code === "E_SNAPSHOT_UNKNOWN")) throw e; }
+    }
+    const wantHome = explicitHome || snap?.home || hostHome;
     if (wantHome && !remoteRetiresByHome) {
       // An older kernel ignores --home and retires by name, first match. It
       // is safe only when the name is unique there and is the saved home;
@@ -509,7 +640,7 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     const valueOf = (name) => { const i = args.indexOf(name); return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
     let route;
     if (valueOf("--home") !== undefined || valueOf("--instance") !== undefined) {
-      route = resolveRoute(serverId, { instance: valueOf("--instance"), home: valueOf("--home") }, cmd);
+      route = resolveRoute(serverId, { instance: valueOf("--instance"), home: valueOf("--home") }, cmd, io);
       target = route.target;
       const ii = args.indexOf("--instance");
       if (ii >= 0) { args.splice(ii, 2); if (valueOf("--home") === undefined) args.push("--home", route.home); }
@@ -522,7 +653,52 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     const { envelope, stderr } = runRemote(target, json([cmd, ...scoped]), io);
     return { envelope: envelope.result && typeof envelope.result === "object" ? { ...envelope, result: { ...envelope.result, server: serverId, ...(route ? { route: { home: route.home, instance: route.snapshot?.instance || null, frozen: !!route.snapshot } } : {}) } } : envelope, stderr };
   }
-  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect and operation only (not ${cmd})`);
+  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect, operation, readiness and instance only (not ${cmd})`);
+}
+
+/** The Desktop's per-instance reads and lifecycle plans, as the host's kernel
+ *  answers them: the feature and API number the host must advertise first. */
+const HOST_SURFACES = {
+  readiness: { feature: "readiness", api: "readinessApi", version: 2 },
+  "instance events": { feature: "instance-events-2", api: "eventsApi", version: 2 },
+  "instance git": { feature: "instance-git", api: "instanceGitApi", version: 1 },
+  "instance diff": { feature: "instance-git", api: "instanceGitApi", version: 1 },
+  "instance stop": { feature: "lifecycle-plans", api: "lifecycleApi", version: 1 },
+  "retire plan": { feature: "lifecycle-plans", api: "lifecycleApi", version: 1 },
+};
+
+function requireSurface(remote, target, surface) {
+  if (!remote.features.includes(surface.feature) || remote[surface.api] !== surface.version) {
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise ${surface.feature} (${surface.api} ${surface.version}); upgrade it there; nothing was sent`);
+  }
+}
+
+/** `readiness`, `instance events|git|diff|stop` and `retire --plan` on the
+ *  host: the instance is addressed as every routed session command addresses
+ *  it (its name through a saved route or the host's roster, or an exact
+ *  --home), the scope is an explicit --dir on the host or the registered
+ *  workspace (readiness of a home is its own context), and the host's
+ *  envelope is relayed unchanged. */
+function routeHostSurface(serverId, cmd, oatsArgs, io) {
+  const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
+  const surface = HOST_SURFACES[key];
+  if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff and stop only (not ${key})`);
+  const args = [...oatsArgs];
+  const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
+  const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
+  if (cmd !== "readiness" && (!name || name.startsWith("--"))) throw serverError("E_BAD_ARGS", `${key} --server needs the instance name`);
+  const home = valueOf("--home");
+  if (args.includes("--home") && home === undefined) throw serverError("E_BAD_ARGS", "--home needs an absolute instance home");
+  let target;
+  if (name !== undefined || home !== undefined) {
+    const route = resolveRoute(serverId, { instance: name, home }, key, io);
+    target = route.target;
+    if (home === undefined) args.push("--home", route.home);
+  } else target = targetOf(io.server || getServer(serverId));
+  requireSurface(checkRemote(target, io), target, surface);
+  if (!args.includes("--dir") && !(cmd === "readiness" && home !== undefined)) args.push("--dir", target.workspace);
+  const { envelope, stderr } = runRemote(target, [cmd, ...args, "--json"], io);
+  return { envelope, stderr };
 }
 
 // ------------------------------------------------------------------- roster
@@ -546,6 +722,12 @@ function listSnapshotServers() {
  *  false) and its instances from the snapshots (running null when the probe
  *  fails). Remote state is pulled, never cached; the saved route stays the
  *  action authority. */
+/** The facts a remote row relays from the host's `status --json` row, as the
+ *  host reported them; a fact the host does not supply is null, never
+ *  derived here. */
+export const REMOTE_ROW_FACTS = ["identity", "identityAddress", "teams", "startedAt", "createdAt", "model", "runtimeState", "parentInstance", "siblingInstance", "relation", "relativeTo", "spawnOrigin"];
+const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k, i[k] ?? null]));
+
 export function rosterGroups({ server, io = {} } = {}) {
   const started = Date.now();
   if (server && !ID_RE.test(server)) throw serverError("E_BAD_ARGS", `server id ${JSON.stringify(server)} is not a valid id`);
@@ -574,7 +756,7 @@ export function rosterGroups({ server, io = {} } = {}) {
       skipped++;
       g.probe = { ok: false, error: { code: "E_ROSTER_BUDGET", message: `not probed: the ${budgetMs} ms roster budget was used up by earlier targets` } };
     } else {
-      try { status = runRemote(g.target, ["status", "--json", "--dir", g.target.workspace], { ...io, timeoutMs: Math.min(perTargetTimeoutMs, remaining) }).envelope; }
+      try { status = runRemote(g.target, ["status", "--json", "--dir", g.target.workspace], { ...io, serverId: g.server, timeoutMs: Math.min(perTargetTimeoutMs, remaining) }).envelope; }
       catch (e) { g.probe = { ok: false, error: { code: e.code || "E_SSH", message: e.message } }; }
     }
     if (status && !status.ok) g.probe = { ok: false, error: status.error || { code: "E_REMOTE", message: "status failed" } };
@@ -596,10 +778,13 @@ export function rosterGroups({ server, io = {} } = {}) {
           const snap = routeOf(i);
           g.instances.push({
             server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: status.result.root,
-            harness: i.harness || i.runtime || null, backend: i.sessionTarget?.backend || (i.tmux ? "tmux" : null),
+            harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
             ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
             running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
-            retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, missingRemotely: false,
+            ...rowFacts(i),
+            // Every row the host reports is addressed by its home, saved
+            // route or not; savedRoute says only that it was spawned from here.
+            retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
           });
           if (snap) bySnapshot.delete(i.instance);
         }
@@ -609,7 +794,8 @@ export function rosterGroups({ server, io = {} } = {}) {
     // instance is gone there (retired, or its home removed) and the route is
     // stale; with a failed probe nothing is known. Same keys as remote rows.
     for (const snap of bySnapshot.values()) {
-      g.instances.push({ server: g.server, instance: snap.instance, agent: snap.agent, home: snap.home, agentsRoot: snap.agentsRoot, harness: snap.harness || snap.runtime || null, backend: null, running: null, retirePending: false, rollbackIncomplete: false, savedRoute: true, missingRemotely: g.probe?.ok === true });
+      // Addressable through its saved route unless the host said it is gone.
+      g.instances.push({ server: g.server, instance: snap.instance, agent: snap.agent, home: snap.home, agentsRoot: snap.agentsRoot, harness: snap.harness || snap.runtime || null, backend: null, running: null, ...rowFacts(), retirePending: false, rollbackIncomplete: false, savedRoute: true, addressable: g.probe?.ok !== true, missingRemotely: g.probe?.ok === true });
     }
     delete g._snapshots;
   }
@@ -624,21 +810,37 @@ export function rosterGroups({ server, io = {} } = {}) {
  *  when an instance name is given (spawned from here), else the registry's
  *  target with a caller-supplied absolute remote home. Nothing about the
  *  remote binary or path ever comes from the caller. */
-export function resolveRoute(serverId, { instance, home } = {}, what = "session") {
+export function resolveRoute(serverId, { instance, home } = {}, what = "session", io = {}) {
   // The home is the identity (same-named twins on one host are different
-  // instances); a name alone resolves through its saved route. With a home,
-  // the saved route that owns it supplies the target (a registration edited
-  // later never re-routes a viewer); a name AND a home must agree.
+  // instances). A name resolves through its saved route, else through the
+  // host's own roster. With a home, the saved route that owns it supplies the
+  // target (a registration edited later never re-routes a viewer); a home no
+  // saved route owns is addressed through the registration. A name AND a home
+  // must agree.
   let snap = instance ? readSnapshot(serverId, instance) : undefined;
-  if (instance && !snap) throw serverError("E_SNAPSHOT_UNKNOWN", `no remote instance ${JSON.stringify(instance)} spawned through server ${serverId} from this machine (oats status --server ${serverId})`);
   if (home && snap?.home && resolve(snap.home) !== resolve(home)) throw serverError("E_HOME_MISMATCH", `--home ${home} is not the saved route of ${instance} on ${serverId} (${snap.home})`);
   if (home && !snap) snap = listSnapshots(serverId).find((s) => s.home && resolve(s.home) === resolve(home));
-  const target = snap?.target || targetOf(getServer(serverId));
-  const remoteHome = home || snap?.home;
-  if (!remoteHome || !String(remoteHome).startsWith("/")) throw serverError("E_BAD_ARGS", `${what} --server needs --instance <name> (spawned from here) or --home </absolute/remote/home>`);
+  if (instance && snap && snap.instance !== instance) throw serverError("E_HOME_MISMATCH", `--home ${home} is the saved route of ${snap.instance} on ${serverId}, not of ${instance}`);
+  if (instance && !snap && home && basename(home) !== instance) throw serverError("E_HOME_MISMATCH", `--home ${home} is not the home of instance ${instance}`);
+  const remoteHome = home || snap?.home || (instance ? instanceOnHost(serverId, instance, io).home : undefined);
+  const target = snap?.target || targetOf(io.server || getServer(serverId));
+  if (!remoteHome || !String(remoteHome).startsWith("/")) throw serverError("E_BAD_ARGS", `${what} --server needs --instance <name> or --home </absolute/remote/home>`);
   return { target, home: remoteHome, snapshot: snap };
 }
 
+/** An instance with no saved route here, by name, through the host's own
+ *  roster (one `status --json` in the registered workspace): the one home of
+ *  that name there, or E_AMBIGUOUS naming every home, or E_SNAPSHOT_UNKNOWN. */
+export function instanceOnHost(serverId, name, io = {}) {
+  const target = targetOf(io.server || getServer(serverId));
+  const status = runRemote(target, ["status", "--json", "--dir", target.workspace], { ...io, serverId, input: undefined }).envelope;
+  if (!status.ok) throw serverError(status.error?.code || "E_REMOTE", `cannot resolve ${name} on server ${serverId}: ${status.error?.message || "status failed"}`);
+  const candidates = (status.result?.agents || []).flatMap((a) => (a.instances || []).filter((i) => i.instance === name).map((i) => ({ agent: a.name, home: i.home })));
+  if (!candidates.length) throw serverError("E_SNAPSHOT_UNKNOWN", `no instance ${JSON.stringify(name)} on server ${serverId}: neither a saved route here nor its roster names one (oats server roster --server ${serverId})`);
+  if (candidates.length > 1) throw Object.assign(serverError("E_AMBIGUOUS", `instance ${JSON.stringify(name)} names ${candidates.length} homes on server ${serverId}: ${candidates.map((c) => `${c.home} (${c.agent})`).join(", ")}; pass --home <one of them>`), { details: { candidates } });
+  return { target, home: candidates[0].home };
+}
+
 /** `session inspect` on the execution host for a remote instance: the same
  *  route resolution as attach, the standard envelope relayed as is (ok or
  *  not), never an ACK of anything. */
@@ -646,17 +848,31 @@ export function resolveRoute(serverId, { instance, home } = {}, what = "session"
  *  directly: a kernel that routes session itself also serves it. A silent
  *  probe (before 0.22.2) or one without session in the list is refused
  *  before any session command is sent. */
-function requireSessionRemote(target, io) {
+function requireSessionRemote(target, io, home) {
   const remote = checkRemote(target, io);
   if (!remote.remote.includes("session")) {
-    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the \`oats session\` commands (kernels from ${SESSION_REMOTE_VERSION} do); upgrade it there, or attach with ssh -t ${target.sshHost} tmux attach -t oats`);
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the \`oats session\` commands (kernels from ${SESSION_REMOTE_VERSION} do); upgrade it there, or attach with ssh -t ${target.sshHost} tmux attach -t ${recordedTmuxTarget(target, io, home)}`);
   }
   return remote;
 }
 
+/** Where a kernel without `oats session` put the instance's window: the tmux
+ *  session and window its roster records for that home, else its default
+ *  session (pi-agents, the default of every kernel before 0.31). */
+const OLD_KERNEL_TMUX_SESSION = "pi-agents";
+function recordedTmuxTarget(target, io, home) {
+  try {
+    const status = runRemote(target, ["status", "--json", "--dir", target.workspace], { ...io, input: undefined }).envelope;
+    const row = (status.ok ? status.result?.agents || [] : []).flatMap((a) => a.instances || []).find((i) => i.home && home && resolve(i.home) === resolve(home));
+    if (row?.tmux?.session) return row.tmux.window ? `${row.tmux.session}:${row.tmux.window}` : row.tmux.session;
+  } catch { /* the hint falls back to the default session */ }
+  return OLD_KERNEL_TMUX_SESSION;
+}
+
 export function inspectRemote(serverId, { instance, home } = {}, io = {}) {
-  const route = resolveRoute(serverId, { instance, home }, "session inspect");
-  requireSessionRemote(route.target, io);
+  io = { ...io, serverId };
+  const route = resolveRoute(serverId, { instance, home }, "session inspect", io);
+  requireSessionRemote(route.target, io, route.home);
   const { envelope, stderr } = runRemote(route.target, ["session", "inspect", "--home", route.home, "--json"], io);
   return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, instance: instance || route.snapshot?.instance, home: route.home } } : envelope, stderr, route };
 }
@@ -705,10 +921,11 @@ function requireRemoteFeature(remote, target, feature) {
 }
 
 function launchRemoteSession(serverId, action, choices, io) {
+  io = { ...io, serverId };
   const { instance, home, launchConfig, harness, yolo } = choices;
   const choiceArgs = remoteLaunchArgs(choices);
-  const route = resolveRoute(serverId, { instance, home }, `session ${action}`);
-  const remote = requireSessionRemote(route.target, io);
+  const route = resolveRoute(serverId, { instance, home }, `session ${action}`, io);
+  const remote = requireSessionRemote(route.target, io, route.home);
   if (!remote.features.includes("session-start")) {
     throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${route.target.sshHost} does not advertise session-start (kernels from ${SESSION_START_REMOTE_VERSION} do); upgrade it there, or start the instance on that host`);
   }
@@ -733,6 +950,7 @@ function hostLaunchDefinition(remote, definition) {
   return (remote?.features || []).includes("harness") ? { ...rest, harness: value } : { ...rest, runtime: value };
 }
 export function launchConfigRemote(serverId, options = {}, io = {}) {
+  io = { ...io, serverId };
   const { action, name, context, instance, home, soul, agentsRoot, definition, keepEnv } = options;
   if (!["list", "set", "remove", "preview"].includes(action)) throw serverError("E_BAD_ARGS", "unknown launch configuration action");
   const write = action === "set" || action === "remove";
@@ -764,7 +982,7 @@ export function launchConfigRemote(serverId, options = {}, io = {}) {
   if (soul !== undefined) add("--soul", soul);
   if (agentsRoot !== undefined) add("--agents-root", agentsRoot, true);
   if (action === "preview") args.push(...remoteLaunchArgs(options));
-  const route = homeSelected ? resolveRoute(serverId, { instance, home }, "launch-config") : undefined;
+  const route = homeSelected ? resolveRoute(serverId, { instance, home }, "launch-config", { ...io, input: undefined }) : undefined;
   const target = route?.target || targetOf(io.server || getServer(serverId));
   if (route) add("--home", route.home, true);
   else if (context === undefined) args.push("--dir", target.workspace);
@@ -784,6 +1002,7 @@ const CAPTURED_SCHEDULE_KEYS = ["definitionVersion", "recurrencePolicy", "execut
  *  before any remote mutation when the remote kernel does not advertise
  *  the schedule feature. The envelope is relayed as is. */
 export function scheduleRemote(serverId, oatsArgs, io = {}) {
+  io = { ...io, serverId };
   const server = io.server || getServer(serverId);
   const target = targetOf(server);
   const remote = checkRemote(target, io);
@@ -814,9 +1033,10 @@ export function scheduleRemote(serverId, oatsArgs, io = {}) {
 }
 
 export function attachArgv(serverId, { instance, home } = {}, io = {}) {
-  const { target, home: remoteHome } = resolveRoute(serverId, { instance, home }, "session attach");
-  if (!io.skipVersionCheck) requireSessionRemote(target, io);
-  const [bin, ...rest] = sshArgv(target, ["session", "attach", "--home", remoteHome]);
+  io = { ...io, serverId };
+  const { target, home: remoteHome } = resolveRoute(serverId, { instance, home }, "session attach", io);
+  if (!io.skipVersionCheck) requireSessionRemote(target, io, remoteHome);
+  const [bin, ...rest] = sshArgv(target, ["session", "attach", "--home", remoteHome], { control: controlUsable(target, io) });
   // -t: allocate a PTY; placed before `--` with the other ssh options.
   return { argv: [bin, "-t", ...rest], target, home: remoteHome };
 }

package/lib/session-input.mjs

@@ -2,7 +2,6 @@
 import { execFileSync } from "node:child_process";
 import { basename } from "node:path";
 import { randomUUID } from "node:crypto";
-import { inspectHerdr, inputHerdr, herdrCommand } from "./herdr.mjs";
 
 const shells = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "login"]);
 function tmux(target, args, { exec = execFileSync, input } = {}) {
@@ -14,16 +13,6 @@ function tmux(target, args, { exec = execFileSync, input } = {}) {
   });
 }
 export function inspectSessionTarget(target, io) {
-  if (target.backend === "herdr") {
-    const s = inspectHerdr(target, io);
-    let state = s.present ? s.status : "stopped";
-    if (s.present && !s.agent) {
-      const processes = herdrCommand(target, ["pane", "process-info", "--pane", target.paneId], io).process_info?.foreground_processes;
-      if (!Array.isArray(processes)) throw new Error("Herdr returned no process information");
-      if (!processes.length || processes.every((p) => shells.has(p.name))) state = "shell";
-    }
-    return { backend: "herdr", present: s.present, state, terminalId: target.terminalId };
-  }
   let rows;
   try {
     rows = tmux(target, ["list-panes", "-t", `=${target.session}:=${target.window}`, "-F", "#{pane_id}\t#{pane_dead}\t#{pane_current_command}\t#{pane_pid}"], io).trim().split("\n").filter(Boolean);
@@ -63,18 +52,15 @@ export function inspectSessionTarget(target, io) {
 export function inputSessionTarget(target, text, io) {
   const state = inspectSessionTarget(target, io);
   if (!state.present || state.state === "shell") throw new Error(`cannot submit input: session is ${state.state}`);
-  if (target.backend === "herdr") inputHerdr(target, text, io);
-  else {
-    // Bracketed paste preserves multiline input as one user message. No text
-    // is evaluated by a shell or interpreted as tmux key names.
-    const buffer = `oats-${randomUUID()}`;
-    try {
-      tmux(target, ["load-buffer", "-b", buffer, "-"], { ...io, input: text });
-      tmux(target, ["paste-buffer", "-p", "-b", buffer, "-t", state.paneId], io);
-      tmux(target, ["send-keys", "-t", state.paneId, "Enter"], io);
-    } finally {
-      try { tmux(target, ["delete-buffer", "-b", buffer], io); } catch { /* already consumed or disconnected */ }
-    }
+  // Bracketed paste preserves multiline input as one user message. No text
+  // is evaluated by a shell or interpreted as tmux key names.
+  const buffer = `oats-${randomUUID()}`;
+  try {
+    tmux(target, ["load-buffer", "-b", buffer, "-"], { ...io, input: text });
+    tmux(target, ["paste-buffer", "-p", "-b", buffer, "-t", state.paneId], io);
+    tmux(target, ["send-keys", "-t", state.paneId, "Enter"], io);
+  } finally {
+    try { tmux(target, ["delete-buffer", "-b", buffer], io); } catch { /* already consumed or disconnected */ }
   }
   return { ...state, submitted: true };
 }

package/lib/session-viewer.mjs

@@ -5,11 +5,6 @@ import { inspectSessionTarget } from "./session-input.mjs";
 
 export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
   if (!inspectSessionTarget(target, { exec }).present) throw new Error("session no longer exists");
-  if (target.backend === "herdr") {
-    const env = { ...process.env, HERDR_SOCKET_PATH: target.socket };
-    delete env.HERDR_SESSION;
-    return { binary: target.binary, args: ["terminal", "attach", target.terminalId], env, cleanup() {} };
-  }
   // UTF-8 mode (-u) like the shared session helper: a service without a
   // UTF-8 locale (launchd) otherwise mangles tmux output.
   const run = (args) => exec("tmux", ["-u", "-S", target.socket, ...args], {