@awebai/oats 0.38.1 → 0.39.0

package/docs/release-notes/v0.39.0.md

@@ -0,0 +1,99 @@
+# OATS 0.39.0
+
+## Changed (breaking)
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.40.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.39.0 together: the
+  Desktop 0.38.x refuses a 0.39 CLI.
+
+## Added
+
+- **`oats server connect`: put this workspace on another machine and register
+  it, in one run** (awebai/oats#517, feature `server-connect`). From a
+  deployment, `oats server connect <id> --ssh <host>` takes a machine you reach
+  over ssh, even one with no OATS and no deployment, to a registered, synced
+  deployment of the same workspace. Six steps (`ssh`, `oats`, `git`,
+  `deployment`, `register`, `readiness`) are re-checked on every run, and each
+  does only what is missing. `--install-oats` installs exactly this kernel's
+  version with npm on the host. The deployment goes to `~/Agents/<this
+  deployment's directory name>` there unless `--dir` says otherwise; a
+  non-empty directory is never written into. What only a person can do (Git
+  credentials on the host, a provider's configuration) comes back as
+  `needs-human` with the exact remedy; run the same command again afterwards.
+  See docs/servers.md, "Connect a machine".
+
+- **A registration knows which workspace it serves** (feature
+  `servers-per-workspace`). `~/.oats/servers.json` registrations record
+  `workspaceKey`, the canonical workspace key the host's deployment reports.
+  It is learned from the host, never typed: `server add` records it when the
+  host answers, `server check` fills it in when it is missing, and a host that
+  reports a different key is refused with `E_SERVER_WORKSPACE_MISMATCH`
+  without rewriting the registration. `oats server list --workspace-ref <ref>`
+  lists one workspace's servers and reports `unknownWorkspace`.
+
+- **Capability commands run on a server with `--server <id>`** (feature
+  `capability-route`). For example, `oats aweb setup --join aweb
+  --invite-stdin --soul dev --server altair-aweb` runs `oats aweb setup …` in
+  the registered deployment on that machine, with stdin forwarded untouched
+  and the host's output, exit status and `--json` envelope relayed. Invite
+  values are redacted wherever the command line is printed.
+
+- **macOS hosts say why a private remote is unreadable over ssh.** On macOS,
+  in a session without a terminal (every routed command runs in one), Git
+  cannot open the login keychain where its credential helper keeps the forge
+  token. An `auth` failure there now carries `details.hint:
+  "keychain-non-interactive"` and names the remedies: 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 with `SSH_AUTH_SOCK` pointed at
+  it in the shell's startup file). `oats server check` reports whether the
+  host's Git reads the workspace remote (`workspaceReadable`).
+
+- **A capability command from a deployment no longer needs `--soul`**
+  (feature `operator-default-soul`). Without it, `oats <namespace> …` runs as
+  the first soul of the deployment, by name, not disabled there, that provides
+  the namespace, and says which on stderr. An explicit `--soul` still wins.
+  When no soul provides the namespace the command is refused with `E_BAD_ARGS`
+  naming it. This is what lets `oats aweb setup … --server <id>` and the
+  Desktop's `oats aweb connect` run without naming a soul.
+
+- `oats onboard <dir> [--workspace <ref>] --check --json` answers, without
+  writing anything, where `<dir>` is, what is there, and whether this
+  machine's Git reads the workspace remote. `server connect` asks it of the
+  host.
+
+- **The Desktop shows each workspace's own machines** (awebai/oats#517). With
+  a CLI that has `servers-per-workspace` and `server-connect`, a window's
+  spawn dialog (**Where to run**) and Workspace › Setup (**Machines**) list
+  only the machines whose registration reports that window's workspace key,
+  and **Add a machine to this workspace…** runs `oats server connect` (then
+  `oats aweb connect` for oats.aweb messaging), showing each step and what to
+  do for any that needs you. Without those features the Desktop behaves as
+  before. See docs/desktop.md.
+
+- **oats.aweb 1.21.0: `oats aweb connect <server-id>` gives a deployment on
+  another machine its messaging** (awebai/oats#517). After `oats server
+  connect` has created the workspace's deployment on a registered server, one
+  command from the local deployment gives that deployment membership in its
+  default team. It runs through the kernel's capability route
+  (`oats aweb … --server <id>`) and reports its steps (`aw`, `invite`, `join`,
+  `readiness`) in the server-connect status vocabulary, with every runnable
+  remedy in backticks. It checks aw on the host and installs it with
+  `--install-aw`. It mints a hosted invite from this deployment's root for the
+  host's default team; nothing is minted when the host is already a member.
+  It joins on the host with `oats aweb setup --join <label> --invite-stdin`,
+  then checks again. On this machine and in transit the invite token exists
+  only in memory and on the routed command's stdin; on the host,
+  `aw id team accept-invite` takes it as an argument, so it is visible in the
+  host's process list while that call runs. The join half works on its own: `setup --invite-stdin`,
+  `setup --install-aw [--aw-version <v>]` and `setup --check-only --json`.
+  `setup --join` also recovers a per-team root left connected but unrecorded
+  by an interrupted join.
+
+## Upgrading
+
+- Install the CLI and the Desktop 0.39 together. An older kernel on the same
+  machine refuses a `servers.json` holding `workspaceKey` (an unknown field),
+  so don't downgrade once 0.39 has written registrations; removing the
+  `workspaceKey` lines by hand makes the file readable to an older kernel
+  again.

package/docs/servers.md

@@ -10,11 +10,14 @@ keeps a saved route per remote instance.
 
 ```bash
 oats server add build --ssh build-host --workspace /srv/team --oats /usr/local/bin/oats
-oats server check build      # ssh reachability, remote version, workspace roster; changes nothing
-oats server list
+oats server check build      # ssh reachability, remote version, workspace roster and Git readability
+oats server list [--workspace-ref <ref>]
 oats server remove build
 ```
 
+To put a workspace on a machine that has no deployment yet, use
+[`oats server connect`](#connect-a-machine) instead of `server add`.
+
 - `--ssh` is an OpenSSH host alias or host name, never `user@host` or an
   option. Users, keys and host verification belong in `~/.ssh/config`.
   Connections are non-interactive (`BatchMode=yes`): a prompt fails fast.
@@ -31,7 +34,117 @@ oats server remove build
   is ignored, never written or printed.
 - `--label` sets a display name. `--replace` overwrites an existing id.
 - Registrations live in `~/.oats/servers.json` on this machine, never in a
-  repository.
+  repository. Every change to the file (add, remove, a learned workspace key,
+  connect) is a short read-modify-write of the file as it is then, under the
+  lock directory `~/.oats/servers.lock`, so concurrent commands never lose each
+  other's registrations. A lock still held after 5 s, or left by a process
+  that died, is refused with `E_SERVERS_BUSY`, naming the directory to remove
+  once no oats process is changing the registry.
+
+**Which workspace a server serves.** A registration records `workspaceKey`:
+the canonical key of the workspace its host deployment realizes, as the
+host's own `oats status --json` reports it (`workspace.key`). It is learned,
+never typed:
+
+- `server add` asks the host after writing the registration. A host that does
+  not answer one (unreachable, no deployment at `--workspace`, a kernel before
+  0.38) is registered without it, with a warning.
+- `server check` records it when the registration has none, and `server
+  connect` writes it.
+- A key is recorded only on the registration that was asked: if the
+  registration is removed or pointed elsewhere while the host is being asked,
+  the answer is dropped (`server add` warns), never written onto the new
+  entry or used to bring a removed one back.
+- A host reporting a different key than the recorded one is
+  `E_SERVER_WORKSPACE_MISMATCH` (`details: {recorded, reported}`) and the
+  registration is not rewritten. If the host now serves another workspace,
+  register it again with `server add <id> --replace`.
+- `server list --workspace-ref <ref>` lists the servers whose key is the
+  canonical key of `<ref>` (any spelling of the same repository matches), and
+  `unknownWorkspace` names the ids whose key is not known yet. One host can
+  carry several registrations, one per deployment.
+
+`server check` also asks the host whether its Git reads the workspace remote
+(`workspaceReadable`; the host's [`onboard --check`](#what-connect-runs-on-the-host)),
+which is where a [macOS keychain](#git-on-a-macos-host) problem shows up.
+
+## Connect a machine
+
+```bash
+oats server connect altair-aweb --ssh altair --path /opt/homebrew/bin --install-oats
+```
+
+Run from a deployment, `server connect` puts that deployment's workspace on
+the machine behind `--ssh` and registers it, from a host with nothing but
+ssh access and Node.js. Every run re-checks every step and does only what is
+missing, so after a human step you run the same command again.
+
+| Option | Default |
+|---|---|
+| `--workspace-ref <ref>` | this deployment's `oats-local.yaml` `workspace:` |
+| `--dir <path>` | `~/Agents/<this deployment's directory name>`; absolute or `~/…`, resolved by the host |
+| `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses |
+| `--install-oats` | off: a missing or older OATS is a human step |
+| `--replace` | off: an id registered for another host or directory is refused |
+
+The steps, in order:
+
+| Step | Checks | When something is missing |
+|---|---|---|
+| `ssh` | the host answers a non-interactive ssh | `failed` `E_SSH` |
+| `oats` | `oats version --json` there is this kernel's version or newer and advertises `server-connect` (a build of the same version without it is not enough) | with `--install-oats`: runs `npm install -g @awebai/oats@<this version>` there (`done`); without it, or with no `npm` on the host's PATH: `needs-human` with the command to run |
+| `git` | the host's Git reads the workspace remote | `needs-human` with the remedy (and the [keychain hint](#git-on-a-macos-host)) |
+| `deployment` | `--dir` holds a deployment of this workspace | an absent or empty directory is onboarded there (`done`); a deployment of another workspace is `failed` `E_SERVER_WORKSPACE_MISMATCH`; a non-empty directory without `oats-local.yaml` is `failed` `E_DIR_NOT_EMPTY` and nothing is written into it |
+| `register` | the registration exists, with its `workspaceKey` | written (`done`); an id registered for another target is `failed` `E_SERVER_EXISTS` unless `--replace` (checked before anything else, so a requested id never reports ready while it routes elsewhere); a new id whose host and directory are already registered under another id is reported (`ok`, naming that id; the text result then names that id to spawn with) and not registered twice |
+| `readiness` | each soul of the host deployment (disabled souls skipped) passes `oats readiness` there | each failing or unknown required item becomes a `needs-human` line, once for all the souls that share it; the listing and the checks share one 60 s budget, and souls it does not reach (a check it cuts off included) become one line naming the command to check them; a broken link still fails the run (`E_SSH`) |
+
+A step is `ok` (already so), `done` (this run did it), `needs-human` (its
+`remedy` says what to run where; later steps are `skipped`, waiting for it)
+or `failed` (the run ends). The result is `ready` when no step needs a
+human. Connect never handles credentials: what Git on the host cannot read
+is always a human step there. The `--json` shape is in
+[desktop-cli-api.md](desktop-cli-api.md#oats-server-connect).
+
+### What connect runs on the host
+
+Besides `version --json`, `status --json`, `souls --json` and `readiness
+--json`, connect runs two commands there:
+
+- `oats onboard <dir> --workspace <ref> --check --json`, read-only: where
+  `<dir>` is (a leading `~` is the host's home), whether it is absent, empty,
+  not empty, not a directory or a deployment, and whether the host's Git
+  reads the workspace remote. An unreadable remote is part of the answer
+  (`remote.readable: false` with the error), not a failure. Without
+  `--workspace`, a deployment's own workspace is read.
+- `oats onboard <dir> --workspace <ref> --json`, only when the directory is
+  absent or empty. This is the only way connect onboards on a host; `onboard`
+  itself is not routed with `--server`.
+
+### Git on a macOS host
+
+Git on macOS usually keeps the forge token in the login keychain, through
+its credential helper. A session without a terminal (an ssh command, which is
+how every routed command runs, or a background job) cannot open that
+keychain, so reading a private remote fails as `auth` even though the same
+command works in a terminal on that Mac.
+
+When a remote read fails as `auth` on macOS in a session with no terminal on
+stdin or with `SSH_CONNECTION` set, `E_REMOTE_UNREADABLE` carries
+`details.hint: "keychain-non-interactive"` and `details.remedy`, and the
+message names the two ways out, run once on that Mac:
+
+```bash
+gh auth login --insecure-storage   # keep the token in gh's own file, not the keychain
+gh auth setup-git                  # let Git use gh's token
+```
+
+or read the remote with an SSH key the session can reach. A key with a
+passphrase fails in the same sessions for the same reason: an ssh session has
+no `SSH_AUTH_SOCK` of its own, so it cannot reach the desktop login's
+ssh-agent. Use a key without a passphrase, or point `SSH_AUTH_SOCK` at the
+login agent in the shell's startup file (for zsh, `~/.zshenv`, which
+non-interactive sessions read). OATS never reads or changes credentials
+itself; the hint is about where Git ran, not a probe of the keychain.
 
 ## Connections
 
@@ -139,6 +252,25 @@ explicit `--dir` names a directory on the server and travels as is. Every
 other routed command refuses `--dir`; its scope comes from the
 registration.
 
+**Capability commands.** Any capability command routes with `--server`:
+
+```bash
+oats aweb setup --join aweb --invite-stdin --soul dev --server altair-aweb < invite.txt
+```
+
+The host runs the same argv, minus `--server <id>` (or `--server=<id>`;
+after a `--` the argv is the provider's and is never read), as `oats <namespace>
+<command> …` from the registered workspace directory: the kernel's
+capability dispatch finds the deployment from its working directory, so no
+`--dir` is added to the provider's argv. `--soul` and every other flag go
+through untouched. Stdin is forwarded as is and never read or logged here;
+when stdin is a terminal nothing is forwarded and the host's stdin is
+closed. The host's stdout, stderr and exit status are relayed; with
+`--json` its envelope is relayed verbatim, and when nothing comes back this
+side answers one envelope (`E_SSH`, or `E_REMOTE_ENVELOPE`). Wherever this
+side prints the argv, `--invite` values are replaced by `<redacted>`.
+Kernel commands keep the table above.
+
 **Not routed.** `session input` runs on the execution host, where schedules
 and messaging capabilities call it. `session restart --stop-grace` is refused
 with `--server`; the remote default applies. `session attach --print` shows

package/lib/dir-lock.mjs

@@ -0,0 +1,36 @@
+/**
+ * A mkdir lock for short read-modify-write sections over files several oats
+ * processes share (the host schedule state, the server registry).
+ */
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+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. A lock still
+ *  held after `retryMs` is refused with `busy(why)`, the caller's own error. */
+export function withDirLock(dir, what, fn, { retryMs = 0, busy } = {}) {
+  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; }
+      throw busy(!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`);
+    }
+  }
+  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(); }
+}

package/lib/instance-resolution.mjs

@@ -112,25 +112,30 @@ export function homeSoulMatches(name, meta) {
  *  souls. A bare name must be unique across all three (else E_SOUL_AMBIGUOUS naming each
  *  qualified form); `<repo>/<soul>` names a member (its key, a key suffix or its member name)
  *  or an external source, `<package>/<soul>` a package soul. */
-export function findSoulEntry(discovery, name) {
-  const [repoPart, soulPart] = splitSoulName(name);
-  const hits = [];
-  // A standalone view's one row is the repo's own (unconfirmed by definition — the
-  // workspace could not be read); resolveSoul admits exactly that case.
+/** Every soul a discovery offers, each with the rule a typed name matches it by: the confirmed
+ *  members' souls (a standalone view's one row is the repo's own, unconfirmed by definition — the
+ *  workspace could not be read; resolveSoul admits exactly that case), the external souls, and the
+ *  package souls. → [{ entry, matches(name) }] */
+export function soulCandidates(discovery) {
+  const out = [];
   const standaloneOwn = discovery.standalone === true ? discovery.key : null;
   for (const m of discovery.members || []) {
     if (!m.confirmed && m.key !== standaloneOwn) continue;
-    for (const s of m.souls || []) {
-      if (!soulNameMatches(name, { name: s.name, repoKey: m.key })) continue;
-      hits.push({ ...s, repoKey: m.key, memberCommit: m.commit, external: false });
-    }
+    for (const s of m.souls || []) out.push({ entry: { ...s, repoKey: m.key, memberCommit: m.commit, external: false }, matches: (name) => soulNameMatches(name, { name: s.name, repoKey: m.key }) });
   }
   for (const x of discovery.external || []) {
-    if (x.soul?.name === soulPart && (!repoPart || (x.source && String(x.source).includes(repoPart)))) hits.push({ ...x.soul, repoKey: x.soul.repoKey ?? parseRepoRef(x.source.replace(/@.*$/, "")).key, commit: x.commit, external: true });
-  }
-  for (const s of discovery.packageSouls || []) {
-    if (soulNameMatches(name, { name: s.name, package: s.package })) hits.push({ ...s, external: false });
+    if (!x.soul?.name) continue;
+    out.push({
+      entry: { ...x.soul, repoKey: x.soul.repoKey ?? parseRepoRef(x.source.replace(/@.*$/, "")).key, commit: x.commit, external: true },
+      matches: (name) => { const [repoPart, soulPart] = splitSoulName(name); return x.soul.name === soulPart && (!repoPart || (x.source && String(x.source).includes(repoPart))); },
+    });
   }
+  for (const s of discovery.packageSouls || []) out.push({ entry: { ...s, external: false }, matches: (name) => soulNameMatches(name, { name: s.name, package: s.package }) });
+  return out;
+}
+
+export function findSoulEntry(discovery, name) {
+  const hits = soulCandidates(discovery).filter((c) => c.matches(name)).map((c) => c.entry);
   if (hits.length === 0) throw err("E_SOUL_UNKNOWN", `no soul ${JSON.stringify(name)} among the confirmed members, external souls or package souls of this workspace`, { name, members: (discovery.members || []).filter((m) => m.confirmed).map((m) => m.key), packages: [...new Set((discovery.packageSouls || []).map((s) => s.package))].sort() });
   if (hits.length > 1) {
     const qualified = hits.map(qualifiedSoulName);
@@ -473,13 +478,13 @@ export async function soulSpawnability(local, discovery, lock, soulEntry, { remo
 
 /** The async half of a spawn: everything that touches the network. Returns a
  *  PREPARED object that `spawnInstance` consumes synchronously. */
-export async function prepareInstance(contextDir, soulName, { spawn = {}, remoteOptions, remote, local: localOverride, discovery: discoveryOverride } = {}) {
+export async function prepareInstance(contextDir, soulName, { spawn = {}, remoteOptions, remote, local: localOverride, discovery: discoveryOverride, soulEntry: entryOverride } = {}) {
   const found = localOverride ? { path: null, local: localOverride } : loadLocal(contextDir);
   const local = found.local;
   const deployment = found.path ? dirname(found.path) : resolvePath(contextDir);
   const lock = readLockIfPresent(deployment);
   const discovery = discoveryOverride ?? await discoverOrStandalone(local, { lock, remoteOptions, remote });
-  const soulEntry = findSoulEntry(discovery, soulName);
+  const soulEntry = entryOverride ?? findSoulEntry(discovery, soulName);
   const disabled = disabledEntry(local, soulEntry);
   if (disabled !== null) throw err("E_SOUL_DISABLED", `soul ${qualifiedSoulName(soulEntry)} is disabled on this machine (oats-local.yaml souls.disabled: ${disabled}) — remove it from that list to spawn it here`, { name: soulEntry.name, qualifiedName: qualifiedSoulName(soulEntry), entry: disabled });
   const resolution = await resolveSoul(discovery, soulEntry, { local, lock, spawn, remoteOptions, remote });
@@ -488,6 +493,26 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
   return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn, launch };
 }
 
+/** The first soul of the deployment, by name (then qualified name), not disabled here, whose
+ *  resolution `provides(resolution)`: each soul is prepared in turn over one discovery, and the search
+ *  stops at the first that does. A soul whose resolution is refused cannot provide anything and is
+ *  skipped, named with its code. → { prepared | null, skipped: [{ soul, code }] } */
+export async function prepareFirstProviding(contextDir, provides, { remoteOptions, remote } = {}) {
+  const found = loadLocal(contextDir);
+  const deployment = dirname(found.path);
+  const discovery = await discoverOrStandalone(found.local, { lock: readLockIfPresent(deployment), remoteOptions, remote });
+  const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : qualifiedSoulName(a) < qualifiedSoulName(b) ? -1 : 1);
+  const entries = soulCandidates(discovery).map((c) => c.entry).filter((e) => disabledEntry(found.local, e) === null).sort(byName);
+  const skipped = [];
+  for (const soulEntry of entries) {
+    let prepared;
+    try { prepared = await prepareInstance(contextDir, null, { remoteOptions, remote, discovery, soulEntry }); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) { skipped.push({ soul: qualifiedSoulName(soulEntry), code: e.code }); continue; } throw e; }
+    if (provides(prepared.resolution)) return { prepared, skipped };
+  }
+  return { prepared: null, skipped };
+}
+
 /** E_REMOTE_UNREADABLE reasons (lib/remote.mjs classifyRemoteFailure) that mean "the
  *  operator's access context cannot see this host" — the ONLY reasons that turn a
  *  workspace spawn into the standalone view. `network` / `timeout` are transient: the

package/lib/operator-dispatch.mjs

@@ -24,7 +24,7 @@ import { loadLocal } from "./workspace.mjs";
 import { packageRef, refForKey } from "./resolve.mjs";
 import { MODULES_DIR } from "./materialize.mjs";
 import * as defaultRemote from "./remote.mjs";
-import { prepareInstance } from "./instance-resolution.mjs";
+import { prepareFirstProviding, prepareInstance, qualifiedSoulName } from "./instance-resolution.mjs";
 
 function err(code, message, details) { const e = oatsError(code, message, details); e.details = details; return e; }
 
@@ -105,32 +105,42 @@ export async function ensureModuleTree(deployment, module, lock, { catalog = nul
  *
  *   contextDir  — where the operator stands (oats-local.yaml is found walking up)
  *   namespace   — the `<ns>` the operator typed (`okf`)
- *   soulName    — the value of --soul; REQUIRED (undefined/true/"" → E_BAD_ARGS)
+ *   soulName    — the value of --soul (true or "" → E_BAD_ARGS). Absent: the first soul of the
+ *                 deployment, by name, not disabled here, whose resolution provides the namespace
+ *                 (feature operator-default-soul); none → E_BAD_ARGS
  *
  * → { deployment, soul: { name, repoKey, commit, team }, module, manifest, commands,
- *     settings: <resolution.payloads[cap] or {}>, resolution, prepared,
- *     ensureTree(): Promise<dir> }   — or null when no module of the soul's
+ *     settings: <resolution.payloads[cap] or {}>, resolution, prepared, defaultSoul,
+ *     ensureTree(): Promise<dir> }   — or null when no module of the named soul's
  *     resolution claims the namespace (the caller answers E_UNKNOWN_COMMAND).
+ *     `defaultSoul` is the qualified name of the soul chosen without --soul, else null.
  * Two modules claiming one namespace → E_DUPLICATE_NAMESPACE. Everything
  * prepareInstance can throw (E_SOUL_UNKNOWN,
  * E_REMOTE_UNREADABLE, …) propagates untouched.
  */
 export async function resolveOperatorDispatch(contextDir, namespace, soulName, { remoteOptions, remote, catalog = null, fetch, prepare = prepareInstance } = {}) {
   if (typeof namespace !== "string" || !namespace) throw err("E_BAD_ARGS", "a command namespace is required");
-  if (typeof soulName !== "string" || !soulName.trim()) {
-    throw err("E_BAD_ARGS", `oats ${namespace}: outside an instance home a capability command resolves as a spawn would — pass --soul <name> (the soul whose resolution provides the "${namespace}" namespace)`, { namespace, flag: "--soul" });
+  const claimantsOf = (resolution) => (resolution.modules || []).filter((m) => m?.manifest && m.manifest.command === namespace && m.manifest.commands && typeof m.manifest.commands === "object");
+  let prepared, defaultSoul = null;
+  if (soulName === undefined) {
+    const first = await prepareFirstProviding(resolvePath(contextDir), (resolution) => claimantsOf(resolution).length > 0, { remoteOptions, remote });
+    if (!first.prepared) throw err("E_BAD_ARGS", `no soul of this deployment provides the ${namespace} namespace; pass --soul <name>`, { namespace, flag: "--soul", ...(first.skipped.length ? { skipped: first.skipped } : {}) });
+    prepared = first.prepared;
+    defaultSoul = qualifiedSoulName(prepared.soulEntry);
+  } else {
+    if (typeof soulName !== "string" || !soulName.trim()) throw err("E_BAD_ARGS", `oats ${namespace}: --soul needs a soul name (the soul whose resolution provides the "${namespace}" namespace)`, { namespace, flag: "--soul" });
+    prepared = await prepare(resolvePath(contextDir), soulName, { remoteOptions, remote });
   }
-  const prepared = await prepare(resolvePath(contextDir), soulName, { remoteOptions, remote });
   const { resolution, lock } = prepared;
   const deployment = prepared.deployment ?? dirname(loadLocal(contextDir).path);
-  const claimants = (resolution.modules || []).filter((m) => m?.manifest && m.manifest.command === namespace && m.manifest.commands && typeof m.manifest.commands === "object");
+  const claimants = claimantsOf(resolution);
   if (!claimants.length) return null;
   if (claimants.length > 1) throw err("E_DUPLICATE_NAMESPACE", `duplicate operational command namespace "${namespace}": ${claimants.map((m) => m.name).join(", ")}`, { namespace, modules: claimants.map((m) => m.name) });
   const module = claimants[0];
   const payload = resolution.payloads?.[module.name];
   const settings = payload && typeof payload === "object" ? { ...payload } : {};
   return {
-    deployment, soul: resolution.soul, module, manifest: module.manifest, commands: module.manifest.commands, settings, resolution, prepared,
+    deployment, soul: resolution.soul, module, manifest: module.manifest, commands: module.manifest.commands, settings, resolution, prepared, defaultSoul,
     ensureTree: () => ensureModuleTree(deployment, module, lock, { catalog, remote, remoteOptions: remoteOptions ?? prepared.remoteOptions, fetch }),
   };
 }

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>`),

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. */