@awebai/oats 0.38.2 → 0.39.1

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/release-notes/v0.39.1.md

@@ -0,0 +1,42 @@
+# OATS 0.39.1
+
+## Changed
+
+- **oats.aweb 1.21.1: a Claude Code start says that it will wait at Claude
+  Code's development-channels confirmation** (awebai/oats-aweb#44). Under
+  `delivery: channel`, Claude Code loads the `aweb-channel` plugin with
+  `--dangerously-load-development-channels`, because the plugin is not on
+  Claude Code's approved channel list. Claude Code then stops at its "Loading
+  development channels" confirmation before the session starts, and waits
+  until someone answers it in the instance's terminal. Unattended starts
+  (Desktop starts and restarts, automations, successors) waited there with
+  nothing saying so. Now:
+  - every spawn or start that adds the flag carries the warning
+    `channel-dev-confirmation` once;
+  - `oats readiness` reports it, without changing the status, for a home
+    whose last start was Claude Code under `channel`.
+
+  Nothing answers the confirmation on the human's behalf. Launch arguments
+  and settings are unchanged. `--channels` registers only plugins on Claude
+  Code's approved list; for a plugin not on it, Claude Code prints a startup
+  warning and the channel does not register. That list is Anthropic's
+  default, or a Team/Enterprise organization's managed
+  `allowedChannelPlugins`, which replaces the default and requires
+  `channelsEnabled: true`.
+
+## Fixed
+
+- **`oats readiness` no longer fails package souls on membership**
+  (awebai/oats#533). A package soul (`oats.okf/knowledge-maintainer`,
+  `oats.engineering/code-reviewer`, …) failed its `member` check with
+  "member <its package's repository>: not a member of the workspace", and the
+  remedy asked to list the package's repository in `members:`. A package
+  soul is trusted through the workspace's `packages:` pin, never through
+  membership (see [the non-collapse rule](../workspaces.md#member-tier-vs-package-tier-the-non-collapse-rule)).
+  Its `member` item is now `package <package>/<soul>`. It passes when the
+  package is declared and locked, ships the soul at the locked commit, and
+  the soul's copy matches its digest: for `--soul`, the copy a spawn would
+  link against the lock; for `--home`, the home's copy against the digest it
+  recorded, and the lock against that same digest while it still pins the
+  same commit. A mismatch fails with `E_PACKAGE_INTEGRITY`. Member and
+  external souls are unchanged. Spawn already applied this rule.

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-inspect.mjs

@@ -15,7 +15,7 @@ import { accessSync, constants as fsConstants, existsSync, readFileSync, realpat
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
-import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
+import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, soulCopyDigests } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility } from "./resolve.mjs";
 import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
@@ -133,7 +133,8 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
     kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent, session: newSessionDefaults(deployment),
     recordedDefaultTeam: recordedTeams(meta).defaultTeam, teamModel: model, teamKey,
     subject: { kind: "instance", instance: meta.instance, home, soul: meta.agent },
-    soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems] },
+    soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems],
+      ...(obj(ws.soul?.package) && typeof ws.soul.package.id === "string" ? { package: { id: ws.soul.package.id, soul: ws.soul.name ?? meta.agent, version: ws.soul.package.version ?? null, commit: ws.soul.package.commit ?? ws.soul.commit ?? null, integrity: ws.soul.package.digest ?? null } } : {}) },
     workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
     modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: join(realHome, ".oats", "modules", name) })),
     payloads: obj(meta.providers) ? meta.providers : {},
@@ -189,7 +190,8 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
     kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
     subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
     soul: { name: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, external: soulEntry.external === true, path: soulEntry.path ?? null,
-      soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}) },
+      soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}),
+      ...(typeof soulEntry.package === "string" ? { package: { id: soulEntry.package, soul: soulEntry.name, version: soulEntry.version ?? null, commit: soulEntry.commit ?? null, integrity: soulEntry.digest ?? null } } : {}) },
     workspace: { key: discovery?.key ?? null, name: discovery?.workspace?.name ?? null, deployment, commit: discovery?.commit ?? null, standalone: discovery?.standalone === true },
     modules: (res?.modules || []).map((m) => ({ name: m.name, from: m.from ?? null, manifest: m.manifest ?? null, dir: null, module: m })).sort((a, b) => a.name.localeCompare(b.name)),
     payloads: obj(res?.payloads) ? res.payloads : {}, payloadOrigins: obj(res?.payloadOrigins) ? res.payloadOrigins : {}, slots: obj(res?.slots) ? res.slots : Object.fromEntries(LAYERS.map((l) => [l, null])), slotsFrom: obj(res?.slotsFrom) ? res.slotsFrom : {},
@@ -404,6 +406,48 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
     || (res.status === "ready" && res.problems.length)) return invalid();
   return { outcome: "result", result: { status: res.status, problems: codeMessages(res.problems), warnings: codeMessages(res.warnings ?? []) } };
 }
+/** The `member` item of a package soul. A package soul is trusted through the workspace's
+ *  `packages:` pin (the lock's commit and integrity), never through membership: its
+ *  repository is not a member and need not be (docs/workspaces.md, the non-collapse rule).
+ *  It passes when the discovery lists the soul from the lock (the package declared and
+ *  locked, the soul shipped at the locked commit) and the soul's copy is intact: for a
+ *  soul, the copy a spawn would link matches the locked digest; for a home, its copy
+ *  matches the digest it recorded, and a lock still at that commit records the same one.
+ *  A copy is digested every read: a complete copy is reused, never refetched. */
+function packageSoulItem(t, d) {
+  const p = t.soul.package;
+  const subject = `package ${p.id}/${p.soul}`;
+  const from = { kind: "package", package: p.id, version: p.version, commit: p.commit, integrity: p.integrity };
+  const evidence = { repoKey: t.soul.repoKey, workspace: d?.key ?? null, commit: p.commit, version: p.version, integrity: p.integrity, from };
+  if (!d) return item(subject, "unknown", { producer: "workspace discovery", reason: t.discoveryError ? `the workspace could not be read: ${t.discoveryError.message}` : "no workspace observation", evidence });
+  if (d.standalone === true) return item(subject, "not-applicable", { required: false, producer: "workspace discovery", reason: `standalone view (${d.standaloneReason ?? "explicit"}): the workspace's packages: is not read, so the package pin is recorded, not observed`, evidence });
+  const shipped = (d.packageSouls || []).filter((s) => s.package === p.id);
+  const live = shipped.find((s) => s.name === p.soul);
+  if (!live) {
+    return item(subject, "fail", { producer: "workspace lock", evidence,
+      reason: shipped.length ? `the version of ${p.id} locked in this workspace does not ship the soul ${p.soul}` : `${p.id} is not locked in this workspace's packages:`,
+      remedy: shipped.length ? `pin a release of ${p.id} that ships ${p.soul} in the workspace's packages:, then oats sync` : `declare ${p.id} in the workspace's packages:, then oats sync` });
+  }
+  const integrity = (reason, remedy) => item(subject, "fail", { producer: "workspace lock", code: "E_PACKAGE_INTEGRITY", reason, evidence, remedy });
+  const lockRemedy = "oats sync (a lock that was edited: remove the entry and sync again)";
+  const copy = t.soul.copyError;
+  if (copy?.code === "E_PACKAGE_INTEGRITY") return integrity(copy.message, lockRemedy);
+  const dir = t.soul.soulDir;
+  if (!dir) return item(subject, "unknown", { producer: "workspace lock", reason: "the soul's copy is not available, so its integrity cannot be checked", evidence });
+  const expected = t.home ? "recorded" : "locked";
+  let digests;
+  try { digests = soulCopyDigests(dir); }
+  catch (e) { return integrity(`the soul's copy at ${dir} cannot be digested: ${e.message}`, `move ${dir} aside, then spawn again (a fresh copy is fetched and verified)`); }
+  if (!digests.includes(p.integrity)) {
+    return integrity(`the soul's copy at ${dir} digests ${digests.at(-1)}, not the ${expected} ${p.integrity}${t.home ? "" : " (the lock's)"}`,
+      t.home ? `the copy changed after its spawn, and a spawn reuses it: move ${dir} aside, then spawn a new instance of ${p.id}/${p.soul} (a fresh copy is fetched and verified against the lock)` : `move ${dir} aside, then spawn again (a fresh copy is fetched and verified against the lock); if the lock was edited: ${lockRemedy}`);
+  }
+  if (t.home && live.commit === p.commit && live.digest !== p.integrity) {
+    return integrity(`the lock records ${live.digest} for the same commit ${String(p.commit).slice(0, 12)}; this home recorded ${p.integrity} at its spawn`, lockRemedy);
+  }
+  return item(subject, "pass", { producer: "workspace lock", evidence });
+}
+
 /** The total time the providers check may take in one readiness read. */
 export const PROVIDER_CHECK_BUDGET_MS = 60_000;
 
@@ -430,9 +474,11 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
   }
   configured.push(...teamItems(t), ...launchItems(t), ...folderTrustItems(t));
   // member — the soul's member repository is a confirmed member of the workspace
-  // (oats-membership.yaml backlink observed over the remotes).
+  // (oats-membership.yaml backlink observed over the remotes); a package soul's is its
+  // package instead (packageSoulItem).
   const d = t.discovery;
-  if (t.soul.external) member.push(item(`soul ${t.soul.name}`, "not-applicable", { required: false, producer: "workspace discovery", reason: "an external soul is declared by the workspace; it has no member repository", evidence: { repoKey: t.soul.repoKey } }));
+  if (t.soul.package) member.push(packageSoulItem(t, d));
+  else if (t.soul.external) member.push(item(`soul ${t.soul.name}`, "not-applicable", { required: false, producer: "workspace discovery", reason: "an external soul is declared by the workspace; it has no member repository", evidence: { repoKey: t.soul.repoKey } }));
   else if (!d) member.push(item(`member ${t.soul.repoKey ?? "?"}`, "unknown", { producer: "workspace discovery", reason: t.discoveryError ? `the workspace could not be read: ${t.discoveryError.message}` : "no workspace observation", evidence: { repoKey: t.soul.repoKey } }));
   // A standalone view is an allowed mode (decision 10): membership cannot be confirmed
   // there by definition, so it is not a readiness requirement (as for an external soul).

package/lib/instance-resolution.mjs

@@ -16,7 +16,7 @@
  *
  *  Nothing here reads `oats-config.yaml`, an installed-capability directory or a
  *  per-soul `source:` — those do not exist in this model. */
-import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
 import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
 import { oatsError } from "./errors.mjs";
 import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo, observeWorkspace } from "./workspace.mjs";
@@ -25,7 +25,7 @@ import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, record
 import { launchLayers } from "./launch-preference.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { materialize, moduleSkills, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
-import { fetchRemoteTree } from "./remote.mjs";
+import { contentDigest, fetchRemoteTree } from "./remote.mjs";
 import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
@@ -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);
@@ -227,6 +232,19 @@ async function fetchSoulSource(prepared, dest) {
   if (!existsSync(join(dest, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(dest, "CLAUDE.md"));
 }
 
+/** The digests a soul copy may carry as its source was fetched (fetchSoulSource): the copy itself, and,
+ *  when it holds the CLAUDE.md → AGENTS.md alias, the copy without it, since fetchSoulSource adds that
+ *  alias to a source that has none. A package soul's copy is intact when one of them is its digest. */
+export function soulCopyDigests(dir) {
+  const options = { allowSymlinks: SOUL_ALIAS_SYMLINK };
+  const alias = join(dir, "CLAUDE.md");
+  let aliased = false;
+  try { aliased = lstatSync(alias).isSymbolicLink() && readlinkSync(alias) === "AGENTS.md"; } catch { aliased = false; }
+  const digests = [contentDigest(dir, options)];
+  if (aliased) digests.push(contentDigest(dir, { ...options, omit: (rel) => rel === "CLAUDE.md" }));
+  return digests;
+}
+
 /** A preview's soul source. A preview writes NOTHING in the deployment (K6b), so it
  *  never populates the per-commit cache or moves the `soul` pointer: it reads the
  *  cache entry for the prepared commit when one is already complete, else fetches
@@ -473,13 +491,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 +506,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 }),
   };
 }