@awebai/oats 0.38.2 → 0.39.1

package/lib/remote.mjs

@@ -441,11 +441,24 @@ function classifyText(error) {
   return null;
 }
 
+/** What to do when git on a macOS host cannot reach its keychain: the credentials git uses must live
+ *  somewhere a session without a terminal can read. */
+export const KEYCHAIN_REMEDY = "on macOS a session without a terminal (an ssh command, a background job) cannot open the login keychain where git's credential helper keeps the forge token; store git credentials outside the keychain (`gh auth login --insecure-storage`, then `gh auth setup-git`), or use an SSH key the session can reach: one without a passphrase, or the desktop login's ssh-agent (point SSH_AUTH_SOCK at it in the shell's startup file)";
+
+/** "keychain-non-interactive" when an `auth` failure happened on macOS in a non-interactive session
+ *  (no terminal on stdin, or an ssh session), else null. A fact about where git ran, never a probe of
+ *  the keychain or of any credential. */
+export function keychainHint({ platform = process.platform, stdinIsTTY = process.stdin.isTTY, env = process.env, reason } = {}) {
+  if (platform !== "darwin" || reason !== "auth") return null;
+  return !stdinIsTTY || !!env.SSH_CONNECTION ? "keychain-non-interactive" : null;
+}
+
 function unreadable(ref, error, extra = {}) {
   const reason = classifyRemoteFailure(error), killed = reason === "killed";
   if (reason === "cache") return cacheFailure(ref, error, extra);
-  return fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (${reason})${killed ? `: git was killed (signal ${error.signal})` : ""}`,
-    { url: ref.url, key: ref.key, reason, ...(killed ? { signal: error.signal } : {}), ...extra });
+  const hint = keychainHint({ reason });
+  return fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (${reason})${killed ? `: git was killed (signal ${error.signal})` : ""}${hint ? `: ${KEYCHAIN_REMEDY}` : ""}`,
+    { url: ref.url, key: ref.key, reason, ...(killed ? { signal: error.signal } : {}), ...(hint ? { hint, remedy: KEYCHAIN_REMEDY } : {}), ...extra });
 }
 
 /** The lock file a git lock error names (`Unable to create '<path>.lock'`, `could not lock config file <path>`),
@@ -2126,7 +2139,8 @@ function createDigest() {
 }
 
 /** Same digest as fetchRemoteTree, computed over a local directory. Symlinks and
- * non-regular entries are refused (E_REMOTE_TREE_UNSAFE); a missing dir → E_REMOTE_PATH_MISSING. */
+ * non-regular entries are refused (E_REMOTE_TREE_UNSAFE); a missing dir → E_REMOTE_PATH_MISSING.
+ * `omit(relPath, absPath)` → true leaves an entry out (what a copy gained after its fetch). */
 function posixNormalize(p) {
   const out = [];
   for (const seg of p.split("/")) { if (!seg || seg === ".") continue; if (seg === "..") { if (out.length && out.at(-1) !== "..") out.pop(); else out.push(".."); } else out.push(seg); }
@@ -2142,7 +2156,7 @@ function posixNormalize(p) {
  */
 export const OATS_ALIAS_SYMLINK = (relPath) => typeof relPath === "string" && (relPath === "CLAUDE.md" || relPath.endsWith("/CLAUDE.md"));
 
-export function contentDigest(dir, { allowSymlinks = null } = {}) {
+export function contentDigest(dir, { allowSymlinks = null, omit = null } = {}) {
   if (typeof dir !== "string" || !isAbsolute(dir)) throw fail("E_REPO_REF", "contentDigest requires an absolute directory path", { path: dir });
   let st;
   try { st = lstatSync(dir); } catch { throw fail("E_REMOTE_PATH_MISSING", `${dir} does not exist`, { path: dir }); }
@@ -2152,6 +2166,7 @@ export function contentDigest(dir, { allowSymlinks = null } = {}) {
     for (const name of readdirSync(abs)) {
       if (!rel && name === ".git") continue; // a local checkout's metadata is not content
       const p = join(abs, name), r = rel ? `${rel}/${name}` : name, s = lstatSync(p);
+      if (typeof omit === "function" && omit(r, p)) continue;
       if (s.isSymbolicLink()) {
         // Refused by default (contract §1). The same narrow opt-in fetchRemoteTree
         // honours (a relative, non-escaping alias such as CLAUDE.md → AGENTS.md)

package/lib/schedule.mjs

@@ -30,6 +30,7 @@ import { Cron } from "croner";
 import { loadLocal } from "./workspace.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
 import { herdrSettingRemoved } from "./errors.mjs";
+import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
 import { tickTriggers } from "./triggers.mjs";
 import { resolveMemberClone } from "./instance-resolution.mjs";
 import { AUTOMATION_ID_RE, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
@@ -224,33 +225,9 @@ export function writeHostState(st) { writeJson(join(hostScheduleDir(), "state.js
 
 // ---------------------------------------------------------------- locks
 
-function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } }
-const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-
-/** A mkdir lock that is never reclaimed by another process: an existing
- *  lock whose owner is unreadable or dead is refused with the directory to
- *  remove, because the gap between mkdir and owner.json belongs to a live
- *  acquirer and a dead-owner reclaim races every other acquirer. The
- *  holder removes its own lock in finally and on SIGINT/SIGTERM. */
+/** Schedule locks (lib/dir-lock.mjs): a holder still there after the retry is E_SCHEDULER_BUSY. */
 function withDirLock(dir, what, fn, { retryMs = 0 } = {}) {
-  mkdirSync(dirname(dir), { recursive: true });
-  const deadline = Date.now() + retryMs;
-  for (;;) {
-    try { mkdirSync(dir); break; }
-    catch (e) {
-      if (e.code !== "EEXIST") throw e;
-      let owner; try { owner = JSON.parse(readFileSync(join(dir, "owner.json"), "utf8")); } catch { owner = undefined; }
-      if (owner?.pid && pidAlive(owner.pid) && Date.now() < deadline) { pause(50); continue; }
-      const why = !owner ? "its owner is not readable yet or the file is missing" : pidAlive(owner.pid) ? `pid ${owner.pid} holds it` : `its owner pid ${owner.pid} is gone`;
-      throw scheduleError("E_SCHEDULER_BUSY", `${what} is locked (${why}). If no oats schedule process is running, remove ${dir} and retry; nothing was changed.`);
-    }
-  }
-  writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid: process.pid, at: new Date().toISOString(), what }) + "\n");
-  const release = () => { try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } };
-  const onSignal = (sig) => { release(); process.exit(sig === "SIGINT" ? 130 : 143); };
-  process.once("SIGINT", onSignal); process.once("SIGTERM", onSignal);
-  try { return fn(); }
-  finally { process.off("SIGINT", onSignal); process.off("SIGTERM", onSignal); release(); }
+  return withSharedDirLock(dir, what, fn, { retryMs, busy: (why) => scheduleError("E_SCHEDULER_BUSY", `${what} is locked (${why}). If no oats schedule process is running, remove ${dir} and retry; nothing was changed.`) });
 }
 export function withHostLock(fn, { retryMs = 0 } = {}) { return withDirLock(join(hostScheduleDir(), "host.lock"), "the host scheduler", fn, { retryMs }); }
 /** Registry read-modify-write is serialized on its own short lock. */

package/lib/servers.mjs

@@ -16,13 +16,14 @@
  * nothing here runs Git against a remote path.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { parseStrictJson } from "./canonical-json.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
+import { withDirLock } from "./dir-lock.mjs";
 
 const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
 export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
@@ -130,6 +131,35 @@ export function writeServers(servers) {
   writeFileSync(file, JSON.stringify({ servers }, null, 2) + "\n", { mode: 0o600 });
 }
 
+/** Every read-modify-write of the registry: under one short lock, over the file as it is NOW (never a
+ *  copy read before a network call), written only when `change` altered it. `change(servers)`
+ *  mutates its argument and returns what the caller needs. */
+export function updateServers(change) {
+  const lock = join(OATS_HOME_DIR(), "servers.lock");
+  return withDirLock(lock, "the server registry", () => {
+    const servers = readServers();
+    const before = JSON.stringify(servers);
+    const out = change(servers);
+    if (JSON.stringify(servers) !== before) writeServers(servers);
+    return out;
+  }, { retryMs: 5000, busy: (why) => serverError("E_SERVERS_BUSY", `the server registry is locked (${why}); if no oats process is changing it, remove ${lock} and retry; nothing was changed`) });
+}
+
+/** Record the workspace key a host reported for registration `id`, only if the registration is still
+ *  the one that was asked (same host, workspace, oats path and PATH), so a registration changed or
+ *  removed meanwhile is never overwritten or brought back. → "recorded" | "same" | "changed" |
+ *  { mismatch: <the recorded key> } (a recorded key is never rewritten). */
+export function learnWorkspaceKey(id, asked, reported) {
+  return updateServers((servers) => {
+    const current = servers[id];
+    if (!current || JSON.stringify(targetOf(current)) !== JSON.stringify(targetOf(asked))) return "changed";
+    if (current.workspaceKey === reported) return "same";
+    if (current.workspaceKey) return { mismatch: current.workspaceKey };
+    current.workspaceKey = reported;
+    return "recorded";
+  });
+}
+
 /** 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) {
@@ -148,11 +178,33 @@ export function validateServer(id, s) {
     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`);
+  // The canonical key of the workspace the host deployment realizes, as its own `status --json` reported it.
+  if (s.workspaceKey !== undefined && (typeof s.workspaceKey !== "string" || !WORKSPACE_KEY_RE.test(s.workspaceKey))) throw serverError("E_SERVER_INVALID", `server ${id}: workspaceKey must be a canonical workspace key (as the host's oats status --json reports it)`);
   for (const k of Object.keys(s)) {
-    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)`);
+    if (!["label", "sshHost", "workspace", "oatsPath", "path", "workspaceKey"].includes(k)) throw serverError("E_SERVER_INVALID", `server ${id}: unknown field ${JSON.stringify(k)} (a registration holds label, sshHost, workspace, oatsPath, path, workspaceKey and nothing else — never keys or passwords)`);
   }
   return true;
 }
+const WORKSPACE_KEY_RE = /^[^\s\x00-\x1f\x7f]+$/;
+
+/** The workspace key a host deployment reports for itself (`status --json` → `workspace.key`,
+ *  feature workspace-identity): `{ key }`, or `{ key: null, why }` when the host answers none
+ *  (no deployment there, a kernel before 0.38, a failed status). ssh failures throw. */
+export function reportedWorkspaceKey(target, io = {}) {
+  const status = runRemote(target, ["status", "--json", "--dir", target.workspace], { ...io, input: undefined }).envelope;
+  return workspaceKeyOfStatus(status);
+}
+export function workspaceKeyOfStatus(status) {
+  if (!status.ok) return { key: null, why: `the host's status failed: ${status.error?.message || status.error?.code || "no reason given"}` };
+  const key = status.result?.workspace?.key;
+  if (typeof key === "string" && WORKSPACE_KEY_RE.test(key)) return { key };
+  return { key: null, why: "the host's oats reports no workspace key (no deployment at that path, or a kernel before 0.38)" };
+}
+
+/** A recorded key the host contradicts: never rewritten, the remedy named. */
+export function workspaceMismatch(id, server, reported) {
+  return Object.assign(serverError("E_SERVER_WORKSPACE_MISMATCH", `server ${id} is registered for workspace ${server.workspaceKey}, but the deployment at ${server.sshHost}:${server.workspace} reports ${reported}; the registration was not changed (register the deployment you mean with oats server add ${id} --replace …)`), { details: { recorded: server.workspaceKey, reported } });
+}
 
 export function getServer(id) {
   const servers = readServers();
@@ -261,6 +313,7 @@ export function runRemote(target, oatsArgs, io = {}) {
   let stderr = "";
   let status = 0;
   let started = true;
+  let timedOut = false;
   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.
@@ -273,7 +326,11 @@ export function runRemote(target, oatsArgs, io = {}) {
     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;
+    timedOut = e.code === "ETIMEDOUT";
   }
+  // The call's own deadline killed ssh: whatever it printed is cut short. Still ssh's failure to the
+  // envelope (E_SSH); `timedOut` lets a caller with a budget tell it from a broken link.
+  if (timedOut) throw Object.assign(serverError("E_SSH", `ssh to ${target.sshHost} did not finish within ${Math.round((io.timeoutMs || 300000) / 1000)} s`), { timedOut: true });
   if (String(stdout).trim()) {
     const envelope = parseRemoteEnvelope(stdout);
     // A bare `retire --json` answer with cleanup still owed exits 1 on the
@@ -1050,3 +1107,264 @@ export function attachArgv(serverId, { instance, home } = {}, io = {}) {
   // -t: allocate a PTY; placed before `--` with the other ssh options.
   return { argv: [bin, "-t", ...rest], target, home: remoteHome };
 }
+
+// ------------------------------------------------------------------ connect
+
+/** `oats server connect` (docs/servers.md): this workspace's deployment on a host, registered, in
+ *  one idempotent run of six steps, each re-checking its state before doing anything:
+ *  ssh → oats → git → deployment → register → readiness. A step answers ok (already so), done
+ *  (this run did it), needs-human (with the exact remedy: later steps are skipped, waiting for
+ *  it) or failed (the run ends: the error carries the steps so far). Nothing here touches
+ *  credentials: what git on the host cannot read is a human step. */
+export const CONNECT_STEPS = ["ssh", "oats", "git", "deployment", "register", "readiness"];
+/** The readiness step's whole allowance (all souls, one control connection). */
+export const CONNECT_READINESS_BUDGET_MS = 60000;
+const INSTALL_TIMEOUT_MS = 600000;
+
+/** One host command that is not the oats CLI (`true`, `npm`): its exit status and output, never an
+ *  envelope. The registration's --path applies as for oats; stdin is closed. */
+function runHostCommand(target, argv, io = {}) {
+  const exec = io.execFileSync || execFileSync;
+  const [bin, ...rest] = sshArgv({ ...target, oatsPath: argv[0] }, argv.slice(1), { control: controlUsable(target, io) });
+  try {
+    return { status: 0, stdout: String(exec(bin, rest, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 16 * 1024 * 1024, timeout: io.timeoutMs || 300000 }) ?? ""), stderr: "" };
+  } catch (e) {
+    return { status: typeof e.status === "number" ? e.status : 255, stdout: String(e.stdout || ""), stderr: String(e.stderr ?? e.message ?? "") };
+  }
+}
+const tail = (text) => String(text || "").trim().slice(-400) || "(no output)";
+
+/** A command a person copies out of a remedy: every argument quoted for a POSIX shell (remoteQuote),
+ *  so a value from a workspace reference or a host path is one literal argument and never shell
+ *  code, inside a Markdown code span no backtick in the command can end (the Desktop's copy buttons
+ *  read the spans). */
+/** A value written into a remedy's prose (a reference, a host's message): its backslashes escaped and
+ *  then its backticks, so no backtick in it is left active (a backslash of its own before one would
+ *  otherwise escape the escape) and it never opens a code span a copy button would offer as a command. */
+const inProse = (value) => String(value).replace(/\\/g, "\\\\").replace(/`/g, "\\`");
+export function runnable(argv) {
+  const command = argv.map(remoteQuote).join(" ");
+  const fence = "`".repeat(Math.max(0, ...(command.match(/`+/g) || []).map((run) => run.length)) + 1);
+  const pad = command.startsWith("`") || command.endsWith("`") ? " " : "";
+  return `${fence}${pad}${command}${pad}${fence}`;
+}
+const sshFailed = (target, r) => serverError("E_SSH", `ssh to ${target.sshHost} failed: ${tail(r.stderr)}`);
+
+/** The oats a host answers at the target's binary: `{ version, features }`, or `{ missing: true }` when
+ *  its shell finds nothing there to run (exit 126/127). */
+function probeHostOats(target, io) {
+  const r = runHostCommand(target, [target.oatsPath, "version", "--json"], { ...io, timeoutMs: 60000 });
+  if (r.status === 255) throw sshFailed(target, r);
+  if (r.status === 126 || r.status === 127) return { missing: true };
+  const probe = parseRemoteEnvelope(r.stdout).result || {};
+  if (probe.desktopApi !== 1 || typeof probe.version !== "string") throw serverError("E_REMOTE_INCOMPATIBLE", `${target.oatsPath} at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
+  return { version: probe.version, features: Array.isArray(probe.features) ? probe.features.map(String) : [] };
+}
+
+/** A host's failure envelope as a thrown error with its own code, message and details. */
+function relayedFailure(envelope, what) {
+  const e = serverError(envelope.error?.code || "E_REMOTE", envelope.error?.message || `${what} failed on the host`);
+  if (envelope.error?.details) e.details = envelope.error.details;
+  return e;
+}
+
+/**
+ * options: { id, sshHost, workspaceRef, dir (absolute, or ~/… resolved by the host), oatsPath?, path?,
+ *            label?, installOats?, replace?, localVersion (this kernel's: the version installed) }
+ * io: { execFileSync, now, readinessBudgetMs } (the transport and clock; tests inject them).
+ * → { id, ready, registration, steps, human }; a failed step throws its code with
+ *   details { ...the step's details, steps }.
+ */
+export function connectServer(options, io = {}) {
+  const { id, sshHost, workspaceRef, dir, oatsPath, path, label, installOats = false, replace = false, localVersion } = options;
+  const now = io.now || Date.now;
+  validateServer(id, { sshHost, workspace: "/", ...(oatsPath ? { oatsPath } : {}), ...(path ? { path } : {}), ...(label ? { label } : {}) });
+  if (typeof dir !== "string" || !(dir === "~" || dir.startsWith("~/") || dir.startsWith("/"))) throw serverError("E_BAD_ARGS", `--dir must be an absolute path or ~/… on the host (got ${JSON.stringify(dir)})`);
+  io = { ...io, serverId: id, input: undefined };
+  const target = { sshHost, workspace: dir, oatsPath: oatsPath || "oats", ...(path ? { path } : {}) };
+  const steps = [], human = [];
+  let blockedBy = null, check = null, reportedKey = null, registration = null, registeredAs = id;
+
+  const run = (name, fn) => {
+    if (blockedBy) { steps.push({ step: name, status: "skipped", detail: `waits for ${blockedBy}` }); return; }
+    let out;
+    try { out = fn(); }
+    catch (e) { out = { status: "failed", code: e.code || "E_CONNECT", detail: e.message, ...(e.details ? { details: e.details } : {}) }; }
+    const { lines, ...step } = { step: name, ...out };
+    steps.push(step);
+    if (step.status === "needs-human") { human.push(...(lines || [step.remedy])); blockedBy = name; }
+    if (step.status === "failed") throw Object.assign(serverError(step.code, step.detail), { details: { ...(step.details || {}), steps } });
+  };
+
+  run("ssh", () => {
+    const r = runHostCommand(target, ["true"], { ...io, timeoutMs: 60000 });
+    if (r.status !== 0) throw sshFailed(target, r);
+    return { status: "ok" };
+  });
+
+  // A kernel the rest of connect can use: this version or newer AND advertising server-connect (the
+  // commands connect runs there); a build of the same version without them is not taken for one.
+  run("oats", () => {
+    const found = probeHostOats(target, io);
+    const older = (p) => compareSemver(p.version, localVersion) < 0;
+    const usable = (p) => !!p.version && !older(p) && p.features.includes("server-connect");
+    if (usable(found)) return { status: "ok", detail: `oats ${found.version}${found.version === localVersion ? "" : ` (this kernel ${localVersion})`}` };
+    const npm = runHostCommand(target, ["npm", "--version"], { ...io, timeoutMs: 60000 });
+    if (npm.status === 255) throw sshFailed(target, npm);
+    const what = !found.version ? `no oats at ${target.oatsPath} on ${sshHost}`
+      : older(found) ? `oats ${found.version} at ${target.oatsPath} is older than this kernel (${localVersion})`
+        : `oats ${found.version} at ${target.oatsPath} on ${sshHost} does not advertise server-connect, which connect needs there`;
+    if (npm.status !== 0) return { status: "needs-human", detail: `${what}, and no npm on its PATH`, remedy: `install Node.js 22+ (npm) on ${sshHost}, or pass --path <the directory holding npm>` };
+    const install = ["npm", "install", "-g", `@awebai/oats@${localVersion}`];
+    if (!installOats) return { status: "needs-human", detail: what, remedy: `on ${sshHost}: ${runnable(install)} (or pass --install-oats)` };
+    const r = runHostCommand(target, install, { ...io, timeoutMs: INSTALL_TIMEOUT_MS });
+    if (r.status === 255) throw sshFailed(target, r);
+    if (r.status !== 0) throw serverError("E_REMOTE_INSTALL", `${install.join(" ")} failed on ${sshHost} (exit ${r.status}): ${tail(r.stderr || r.stdout)}`);
+    const after = probeHostOats(target, io);
+    if (!usable(after)) {
+      const still = !after.version ? "is still not found" : older(after) ? `still answers ${after.version}` : `still does not advertise server-connect (${after.version})`;
+      throw serverError("E_REMOTE_INSTALL", `npm installed @awebai/oats@${localVersion} on ${sshHost}, but ${target.oatsPath} there ${still}; pass --oats <the installed oats> or --path <npm's global bin directory>`);
+    }
+    const was = !found.version ? "was missing" : older(found) ? `was ${found.version}` : `was ${found.version} without server-connect`;
+    return { status: "done", detail: `installed @awebai/oats ${localVersion} (${was})` };
+  });
+
+  // The host's own answer about the directory and the workspace remote (onboard --check, read-only).
+  run("git", () => {
+    const { envelope } = runRemote(target, ["onboard", dir, "--workspace", workspaceRef, "--check", "--json"], io);
+    if (!envelope.ok) throw relayedFailure(envelope, "onboard --check");
+    check = envelope.result;
+    if (check.remote.readable) return { status: "ok", detail: `${check.workspace.key} readable at ${String(check.remote.commit).slice(0, 12)}` };
+    const err = check.remote.error || {};
+    const remedy = err.remedy || `make ${inProse(check.workspace.ref)} readable by git there (check the reference; give git there credentials or an SSH key for it), then confirm with ${runnable(["git", "ls-remote", check.workspace.url])}`;
+    return { status: "needs-human", code: err.code || "E_REMOTE_UNREADABLE", detail: err.message, remedy: `on ${sshHost}: ${remedy}`, ...(err.hint ? { hint: err.hint } : {}) };
+  });
+
+  run("deployment", () => {
+    const abs = check.dir, want = check.workspace.key;
+    const keyAt = () => reportedWorkspaceKey({ ...target, workspace: abs }, io).key;
+    if (check.state === "deployment") {
+      const key = keyAt();
+      if (key !== want) throw Object.assign(serverError("E_SERVER_WORKSPACE_MISMATCH", `${abs} on ${sshHost} is a deployment of ${key ?? "a workspace it does not report"}, not of ${want}; nothing was changed (choose another --dir)`), { details: { expected: want, reported: key ?? null, dir: abs } });
+      reportedKey = key;
+      return { status: "ok", detail: `${abs} realizes ${key}` };
+    }
+    if (check.state === "not-empty" || check.state === "not-a-directory") {
+      throw Object.assign(serverError("E_DIR_NOT_EMPTY", `${abs} on ${sshHost} ${check.state === "not-empty" ? "is not empty and holds no oats-local.yaml" : "exists and is not a directory"}; nothing was written there (choose another --dir)`), { details: { dir: abs, state: check.state } });
+    }
+    // The only place onboard runs on a host.
+    const { envelope } = runRemote(target, ["onboard", abs, "--workspace", workspaceRef, "--json"], { ...io, timeoutMs: INSTALL_TIMEOUT_MS });
+    if (!envelope.ok) throw relayedFailure(envelope, "onboard");
+    reportedKey = keyAt();
+    if (reportedKey !== want) throw Object.assign(serverError("E_SERVER_WORKSPACE_MISMATCH", `onboarded ${abs} on ${sshHost}, but it reports ${reportedKey ?? "no workspace key"}, not ${want}`), { details: { expected: want, reported: reportedKey ?? null, dir: abs } });
+    return { status: "done", detail: `onboarded ${abs} into ${reportedKey}` };
+  });
+
+  // One guarded update of the registry as it is now. The requested id comes first: an id registered for
+  // another target is refused (or replaced), never quietly answered by a twin that serves this target.
+  run("register", () => updateServers((servers) => {
+    const abs = check.dir;
+    const entry = { sshHost, workspace: abs, ...(oatsPath ? { oatsPath } : {}), ...(path ? { path } : {}), ...(label ? { label } : {}), workspaceKey: reportedKey };
+    const sameTarget = (s) => s.sshHost === sshHost && s.workspace === abs;
+    /** A registration of this very target: its key confirmed, or recorded; never contradicted. */
+    const keep = (regId, detail) => {
+      const existing = servers[regId];
+      if (existing.workspaceKey && existing.workspaceKey !== reportedKey) throw workspaceMismatch(regId, existing, reportedKey);
+      registeredAs = regId;
+      registration = existing;
+      if (existing.workspaceKey) return { status: "ok", ...(detail ? { detail } : {}) };
+      existing.workspaceKey = reportedKey;
+      return { status: "done", detail: [detail, `recorded workspace ${reportedKey}`].filter(Boolean).join("; ") };
+    };
+    const mine = servers[id];
+    if (mine && sameTarget(mine)) {
+      const differ = ["oatsPath", "path", "label"].filter((k) => entry[k] !== undefined && entry[k] !== mine[k]);
+      if (!differ.length || !replace) return keep(id, differ.length ? `${differ.join(", ")} differ from the registration and were not changed (--replace rewrites it)` : undefined);
+      if (mine.workspaceKey && mine.workspaceKey !== reportedKey) throw workspaceMismatch(id, mine, reportedKey);
+      servers[id] = entry; registration = entry;
+      return { status: "done", detail: `updated ${differ.join(", ")}` };
+    }
+    if (mine && !replace) throw Object.assign(serverError("E_SERVER_EXISTS", `server ${id} is already registered for ${mine.sshHost}:${mine.workspace} (pass --replace to point it at ${sshHost}:${abs}; instances spawned through it keep their saved routes)`), { details: { registered: { sshHost: mine.sshHost, workspace: mine.workspace } } });
+    const twin = Object.keys(servers).find((other) => other !== id && sameTarget(servers[other]));
+    if (twin && !mine) return keep(twin, `${sshHost}:${abs} is already registered as ${twin}; not registered again`);
+    validateServer(id, entry);
+    servers[id] = entry; registration = entry;
+    return { status: "done", detail: [mine ? `replaced ${mine.sshHost}:${mine.workspace}` : `registered ${id}`, twin ? `${sshHost}:${abs} is also registered as ${twin}` : null].filter(Boolean).join("; ") };
+  }));
+
+  // Every soul the host deployment lists (disabled ones skipped), one routed readiness each, within one
+  // budget; each failing or unknown required item is a human line, said once for the souls sharing it.
+  run("readiness", () => {
+    const regTarget = targetOf(registration);
+    const budget = io.readinessBudgetMs || CONNECT_READINESS_BUDGET_MS;
+    const started = now();
+    const left = () => budget - (now() - started);
+    const later = `run \`oats readiness --soul <s> --server ${registeredAs}\``;
+    // The budget's deadline cut the call short: a fact about time, not a failure. A broken link fails.
+    const withinBudget = (args) => {
+      try { return runRemote(regTarget, args, { ...io, timeoutMs: Math.max(1000, left()) }).envelope; }
+      catch (e) { if (e.timedOut) return null; throw e; }
+    };
+    const listed = withinBudget(["souls", "--json", "--dir", regTarget.workspace]);
+    if (!listed) return { status: "needs-human", detail: "readiness not checked", remedy: `readiness not checked: the host did not list its souls within ${Math.round(budget / 1000)} s; ${later} for each soul` };
+    if (!listed.ok) return { status: "needs-human", detail: "the host could not list its souls", remedy: `on ${sshHost}: ${runnable(["oats", "souls", "--dir", regTarget.workspace])} fails: ${inProse(listed.error?.message || listed.error?.code)}` };
+    const souls = (listed.result?.souls || []).filter((s) => s.problem?.code !== "E_SOUL_DISABLED").map((s) => s.qualifiedName || s.name);
+    const problems = new Map(), unchecked = [];
+    const add = (text, soul) => { if (!problems.has(text)) problems.set(text, []); if (!problems.get(text).includes(soul)) problems.get(text).push(soul); };
+    for (const soul of souls) {
+      if (unchecked.length || left() < 1000) { unchecked.push(soul); continue; }
+      const envelope = withinBudget(["readiness", "--soul", soul, "--dir", regTarget.workspace, "--json"]);
+      if (!envelope) { unchecked.push(soul); continue; }
+      if (!envelope.ok) { add(`readiness failed: ${envelope.error?.message || envelope.error?.code}`, soul); continue; }
+      for (const check of Object.values(envelope.result?.checks || {})) {
+        for (const item of check.items || []) {
+          if (item.required && (item.status === "fail" || item.status === "unknown")) add(`${item.subject}: ${item.reason ?? item.status}${item.remedy ? ` → ${item.remedy}` : ""}`, soul);
+        }
+      }
+    }
+    const lines = [...problems].map(([text, by]) => `${by.join(", ")}: ${text}`);
+    if (unchecked.length) lines.push(`readiness not checked for ${unchecked.length} soul${unchecked.length === 1 ? "" : "s"}: ${later} for ${unchecked.join(", ")}`);
+    if (!lines.length) return { status: "ok", detail: souls.length ? `${souls.length} soul${souls.length === 1 ? "" : "s"} ready` : "no souls listed" };
+    return { status: "needs-human", detail: `${lines.length} readiness problem${lines.length === 1 ? "" : "s"}`, remedy: lines.join("\n"), lines };
+  });
+
+  // `registeredAs`: the id that serves the target (another id's registration when it was already there).
+  return { id, ready: !steps.some((s) => s.status === "needs-human" || s.status === "failed"), registration, steps, human, registeredAs };
+}
+
+// ------------------------------------------------------- capability routing
+
+/** The routing flag of a capability command: the first `--server <id>` or `--server=<id>` before any
+ *  `--` (after it, the argv is the provider's), taken out → `{ id, argv }`, or null when there is none.
+ *  `id` is true when the flag has no value. */
+export function serverFlagOf(argv) {
+  const end = argv.indexOf("--");
+  const head = end < 0 ? argv.length : end;
+  for (let i = 0; i < head; i++) {
+    if (argv[i] === "--server") {
+      const value = i + 1 < head && !argv[i + 1].startsWith("--") ? argv[i + 1] : true;
+      return { id: value, argv: [...argv.slice(0, i), ...argv.slice(i + (value === true ? 1 : 2))] };
+    }
+    if (argv[i].startsWith("--server=")) return { id: argv[i].slice("--server=".length) || true, argv: [...argv.slice(0, i), ...argv.slice(i + 1)] };
+  }
+  return null;
+}
+
+/** An argv safe to print: every `--invite <v>` / `--invite=<v>` value replaced. */
+export function redactArgv(argv) {
+  return argv.map((a, i) => (argv[i - 1] === "--invite" ? "<redacted>" : a.startsWith("--invite=") ? "--invite=<redacted>" : a));
+}
+
+/** `oats <namespace> <command> … --server <id>` on the host: the same argv (the routing flag already
+ *  taken out) run in the registration's workspace, where the host's capability dispatch finds its
+ *  deployment. Stdin goes to the host as it is, never read here, unless it is a terminal: then nothing
+ *  is forwarded and the host's stdin is closed. stdout is relayed by the caller under --json (held, to
+ *  relay the host's envelope verbatim) and inherited otherwise; stderr is always inherited.
+ *  → { status, stdout } (stdout only under json). */
+export function routeCapability(serverId, argv, { server, spawnSync: spawn = spawnSync, stdinIsTTY = process.stdin.isTTY, json = false } = {}) {
+  const target = targetOf(server);
+  const [bin, ...rest] = sshArgv(target, argv, { cwd: target.workspace, control: controlUsable(target, { serverId }) });
+  const r = spawn(bin, rest, { stdio: [stdinIsTTY ? "ignore" : "inherit", json ? "pipe" : "inherit", "inherit"], maxBuffer: 64 * 1024 * 1024 });
+  if (r.error) throw serverError("E_SSH", `cannot run ssh to ${target.sshHost} for \`oats ${redactArgv(argv).join(" ")}\` on server ${serverId}: ${r.error.message}`);
+  return { status: typeof r.status === "number" ? r.status : 255, ...(json ? { stdout: r.stdout } : {}) };
+}

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.20.0",
+      "ref": "v1.21.1",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

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