@awebai/oats 0.29.4 → 0.30.1

package/docs/servers.md

@@ -1,148 +1,130 @@
 # Servers: running instances on another machine
 
-A **server** is another machine with its own installed OATS, reached over an
-OpenSSH host alias. Registering one lets `oats spawn`, `oats retire` and
-`oats status` run there with the same flags and the same JSON envelope as
-locally, and lets the Desktop offer it at spawn time. The contract behind
-this is the execution-targets contract (`docs/execution-targets.md`, landing
-with the transport work).
+A **server** is another machine with its own OATS and deployment, reached
+over OpenSSH. `--server <id>` runs a command on that machine's OATS with the
+same flags and JSON envelope as a local call. The server's kernel does the
+work ([execution-targets.md](execution-targets.md)); this machine routes and
+keeps a saved route per remote instance.
 
 ## Register
 
 ```bash
 oats server add build --ssh build-host --workspace /srv/team --oats /usr/local/bin/oats
-oats server check build      # ssh reachability, remote oats version, workspace roster; no mutation
+oats server check build      # ssh reachability, remote version, workspace roster; changes nothing
 oats server list
+oats server remove build
 ```
 
-- `--ssh` is an OpenSSH host alias or host name. Keys, users, ports and host
-  verification live in your `~/.ssh/config`; the registry stores none of it and
-  refuses `user@host` or option-shaped values. Connections are non-interactive
-  (`BatchMode=yes`): a host that would prompt fails fast with ssh's message.
-- `--workspace` is the absolute path of an OATS workspace on the server: the
-  same team repository checked out there, with its own `agents/`.
-- `--oats` is the remote executable (default `oats` on the login shell's PATH).
-- `--path` names directories to prepend to the remote PATH for every routed
-  command (`~/.local/bin:/opt/pi/bin`). A non-interactive ssh command runs in
-  the login shell's minimal PATH, and the remote kernel's spawn preflight looks
-  for the harness binary (`claude`, `pi`, `codex`) there; without this, a
-  harness installed under the user's home is "not found" even though it runs
-  fine in an interactive shell on that host.
+- `--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.
+- `--workspace` is the absolute path of the deployment directory on the
+  server: the directory that holds its `oats-local.yaml`
+  ([configuration.md](configuration.md)). Routed commands run there as
+  `--dir <workspace>`.
+- `--oats` is the remote executable (default: `oats` on the remote PATH).
+- `--path` prepends directories to the minimal remote PATH of every routed
+  command (`~/.local/bin:/opt/pi/bin`), where the remote spawn looks for the
+  harness binary.
+- `--herdr` records the remote Herdr path in the registration and in each
+  saved route. Routed commands do not pass it on; the remote kernel finds
+  `herdr` on its own PATH.
+- `--label` sets a display name. `--replace` overwrites an existing id.
 - Registrations live in `~/.oats/servers.json` on this machine, never in a
-  repository scope.
+  repository.
 
 ## Run there
 
 ```bash
 oats spawn dev --server build --purpose fix-123 --task-file task.md
 oats status --server build
+oats session attach --server build --instance dev-fix-123
 oats retire dev-fix-123 --server build
 ```
 
-The remote kernel does the work in its registered workspace: composition,
-worktree, identity, launch, retirement. The local side only routes: a local
-`--task-file` travels as text, every argument is quoted for the remote login
-shell, and the remote's version and envelope are checked before either
-mutation (spawn and retire). A spawn is also held to what the remote
-advertises: a harness it does not list (including the soul's own default as
-the remote roster reports it), a session backend it lacks, or a launch option
-such as `--yolo` it does not know is refused with `E_REMOTE_INCOMPATIBLE`
-saying what was established. A remote that advertises nothing (any kernel
-before 0.22.2) is assumed to run pi and claude on tmux with no options, and
-the refusal says so rather than claiming the remote lacks the feature; a soul
-the remote roster does not list with a harness is validated by the remote
-kernel itself at spawn. `--dir` and `--server` do not combine; the remote
-workspace comes from the registration.
+Arguments are quoted for the remote shell. Local files (`--task-file`,
+`--wake-file`, a schedule or launch-configuration `--file`) are read here and
+sent as text or on stdin, never as paths.
+
+| Command | Where it runs | The server must advertise |
+|---|---|---|
+| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule |
+| `status` | registered workspace | |
+| `retire` | saved route | `retire-home` to retire by exact home |
+| `session inspect`, `session attach` | saved route | `session` |
+| `session start`, `session restart` | saved route | `session-start`; `session-restart`; `launch-config` when `--launch-config`, `--harness` or `--yolo` is given |
+| `session upload` | saved route | `session-upload` |
+| `okf harvest --instance <name>` | the saved home | `harvest` |
+| `schedule ...` | registered workspace | `schedule` |
+| `launch-config list\|set\|remove\|preview` | `--dir`, a saved route, or the registered workspace | `launch-config` |
+| `inspect`, `operation run` | `--dir`, a saved route, or the registered workspace | `operations` |
+
+Before every routed command except `status`, the kernel reads the server's
+`oats version --json`. A remote OATS older than 0.22.1 is refused, and so is a
+missing feature (`E_REMOTE_INCOMPATIBLE`), before anything is sent. A spawn is
+checked against the harness it would use (the flag, or the soul's default as
+the remote roster reports it). A host that advertises no harness list is
+assumed to run only pi and claude, on tmux, with no launch options.
+
+**Addressing an instance.** Instance commands take `--instance <name>` (spawned
+from this machine) or `--home </remote/home>`. The home is the identity; use it
+when two souls on the host own same-named instances. A name and a home that
+disagree are refused (`E_HOME_MISMATCH`).
+
+**`--dir` with `--server`.** For `inspect`, `operation` and `launch-config`,
+an explicit `--dir` names a directory on the server and travels as is. Every
+other routed command refuses `--dir`; its scope comes from the registration.
+
+**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
+the ssh command without running it.
+
+## The roster and harvest
 
 ```bash
-oats session attach --server build --instance dev-fix-123   # viewer through an ssh PTY
+oats server roster --json                                # one group per server and target
+oats okf harvest --server build --instance dev-fix-123   # the harvest, run in the saved home
 ```
 
-The viewer runs the execution host's own `oats session attach` (Herdr terminal
-or an isolated tmux linked viewer) over `ssh -t`, addressed by the saved route:
-the remote binary and path come from the snapshot, never from the caller.
-Address the home rather than the name (`--home </remote/home>`) when two
-souls on the host own an instance of the same name: the home is the identity,
-the saved route that owns it supplies the target, and a name given together
-with a home that is not its saved route is refused. The
-`oats session` commands ship in kernel 0.22.2: against an older server both
-session routes refuse with `E_REMOTE_INCOMPATIBLE` before connecting a viewer,
-and `ssh -t <host> tmux attach -t oats` remains the way in.
+The **roster** is what the Desktop shows: one group per server id and route
+target (host and workspace), with the registration (present or not), the
+probe result, the remote souls, the instances joined with saved routes
+(`savedRoute`, `running` or `null` when unknown, `retirePending`,
+`rollbackIncomplete`, `missingRemotely`), and `retireFailures` (deferred
+self-retirements that failed there). A removed or edited registration keeps
+its group from the saved routes. State is pulled on every call within
+`--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
+not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.
 
-```bash
-oats server roster --json                                  # every remote group, one status pull each
-oats okf harvest --server build --instance dev-fix-123     # the knowledge harvest, run in the saved home
-```
-
-The **roster** is what the Desktop projects: one group per server id and
-route target (host and workspace), each with the registration (present or
-not), the probe (`ok`, or the error that stopped it), the souls the remote
-reports with their `agentsRoot`, the instances joined with this machine's
-saved routes (`savedRoute`; `running` true/false, or `null` when the remote
-could not be asked; `retirePending`; `rollbackIncomplete` for a quarantined
-home; `missingRemotely` when a saved route names an instance the reachable
-remote no longer lists), and `retireFailures` (deferred self-retirements
-that failed there and need `oats retire` again). A registration that was
-removed or edited keeps its group from the saved routes alone, so nothing
-spawned through it disappears from view. Remote state is pulled every time,
-never cached, within a budget: each group gets at most `--per-target` (20 s)
-of a `--budget` (45 s) total, and groups the budget cannot reach are reported
-with `E_ROSTER_BUDGET` rather than dropped or waited for. **Harvest** runs
-the knowledge package's own `okf harvest --json` in the instance's saved home
-on the host (a route that outlives the registration, like retire): the home
-comes from the route saved at spawn, never from the caller, the remote must
-advertise `harvest` in its version probe (0.22.3), and the package's envelope
-is relayed as is. **Retire** through a saved route sends that route's home as
-`--home` when the remote advertises `retire-home` in its probe `features`, so
-a same-named twin under another agent on the host is never the one retired;
-locally, `oats retire <name> --home <path>` does the same and a bare name that
-resolves to several homes is refused.
+**Harvest** runs the knowledge capability's `okf harvest --json` in the
+instance's saved home on the server and relays its envelope.
 
 ## What this machine keeps
 
-A **route snapshot** per remote instance under `~/.oats/remote/<server>/`,
-taken at spawn: the ssh host, workspace and oats path the instance was spawned
-through, plus the remote home. Later `retire --server` uses the snapshot, not
-today's registry, so editing or removing a registration never orphans a remote
-home; the snapshot is removed only when the remote kernel reports the home
-gone. Remote state is never cached: `status --server` pulls it every time and
-appends this machine's snapshots for that server.
-
-A registration edited to a different host or workspace (`server add
---replace`) while saved routes still point at the old target is refused at
-the next `spawn --server` with `E_ROUTE_CHANGED`: a new snapshot under the
-same server id would silently retarget them. Register the new target under a
-new id, or retire the old instances first; the roster shows both targets
-until then. A saved route whose instance is gone on the host (the roster
-shows it `missingRemotely`) cannot be retired away: drop it on purpose with
-`oats server forget <id> --instance <name>`. Saved routes are keyed by name
-under their server id: spawning an explicit `--instance` name that already
-has a route there is refused (`E_ROUTE_EXISTS`), and a generated name that
-collides with another soul's route on the same host leaves the new instance
-without a saved route (`routeConflict` in the result, a warning naming the
-host-side retire), never overwriting the existing one. The roster gives a
-route to the remote row with the same name and home only; a same-named twin
-under another soul is observed only.
+A **saved route** per remote instance, under `~/.oats/remote/<server>/`,
+written at spawn: the ssh host, workspace, oats path, optional Herdr path and
+PATH prefix, and the remote home. Retire, harvest and session commands use
+the saved route, not the current registration, so editing or removing a
+registration never orphans a remote home. The route is removed when the
+remote kernel reports the home gone.
+
+- `oats server add --replace` to a different host or workspace, while saved
+  routes still point at the old one, makes the next `spawn --server` fail with
+  `E_ROUTE_CHANGED`. Register the new target under a new id, or retire the old
+  instances first.
+- A saved route is never pointed at a different home. A spawn whose name already
+  has a route under that server leaves the new instance without one
+  (`routeConflict` in the result, with a warning naming the host-side retire).
+- A saved route whose instance is gone on the host (`missingRemotely`) cannot
+  be retired. Drop it with `oats server forget <id> --instance <name>`.
+- `retire --server` sends the saved home as `--home`, so a same-named
+  instance under another soul is never the one retired.
 
 ## Limits
 
-- Routed: `spawn`, `retire`, `status`, `okf harvest`, and, against a 0.22.2
-  or later server, `session inspect` (the execution host's envelope, relayed;
-  a Desktop preflight before attaching) and `session attach`; against a
-  server whose version probe advertises the `session-start` feature (0.22.9
-  or later), `session start` (the execution host starts the stopped instance
-  in its saved home; `--model` travels). Session input
-  runs on the execution host, where the wake broker calls it. `server roster`
-  is local (registrations and saved routes, one status pull per group). The
-  version probe's `remote` list names this kernel's remote-side surface
-  (`roster` and `harvest` from 0.22.3).
-- No Git over SSH: repository operations always run on the server, by its
-  kernel, in its workspace.
-- A remote needs an OATS at least 0.22.1 (`MIN_REMOTE_VERSION`) for spawn,
-  retire and status, 0.22.2 for the session routes, and 0.22.3 for harvest
-  and for the exact-home retire; the record commands
-  (`capture`, `recall`) need Node 22.5+ there for `node:sqlite`, which
-  lifecycle routing does not.
-- Lifecycle actions on a remote instance need a saved route from this
-  machine; an instance the remote reports that was spawned elsewhere shows in
-  the roster without one (`savedRoute: false`) and is read-only here.
+- Lifecycle actions need a saved route from this machine. An instance the
+  remote reports but that was spawned elsewhere appears in the roster with
+  `savedRoute: false` and is read-only here.
+- No Git runs over SSH: repository operations always run on the server, by
+  its kernel, in its deployment.

package/docs/soul.schema.json

@@ -7,13 +7,13 @@
   "required": ["schemaVersion", "name", "description", "work"],
   "additionalProperties": false,
   "properties": {
+    "launch": { "description": "The soul's launch preference (0.30; feature launch-preference): what the role should run on. Only harness and model: args, env, yolo and the executable stay host facts (launch configurations). A machine overrides it in oats-local.yaml souls.launch; explicit flags win over both. A committed soul gains it only when every deployment runs 0.30 (0.29 refuses the key).",  "type": "object", "additionalProperties": false, "required": ["harness"], "properties": { "harness": { "enum": ["pi", "claude", "codex"], "description": "The harness the role should run on." }, "model": { "type": "string", "minLength": 1, "pattern": "^[^\\s-][^\\s]*$", "description": "A model id for that harness; absent: the harness's own model." } } },
     "schemaVersion": { "const": 2 },
     "name": { "$ref": "#/$defs/slug" },
     "description": { "type": "string" },
     "work": { "enum": ["worktree", "checkout", "directory", "workspace"] },
-    "team": { "$ref": "#/$defs/teamLabels", "description": "Team label, or a non-empty list of distinct labels (the first is the primary); overrides the repo's default from oats-membership.yaml. Each label's messaging payload reaches the provider as an eligible team (OATS_TEAMS); joining is the provider's explicit act." },
     "private": { "type": "boolean", "deprecated": true,
-      "description": "Ignored since 0.26.0: souls have no private mode. Every soul of a confirmed member is listed and spawnable; discovery warns soul-private-ignored. Accepted so existing files still validate; remove it." },
+      "description": "Tolerated and ignored: souls have no private mode. Every soul of a confirmed member is listed and spawnable; discovery warns soul-private-ignored. Accepted so existing files still validate; remove it." },
     "capabilities": {
       "type": "object",
       "propertyNames": { "$ref": "#/$defs/capabilityName" },
@@ -31,13 +31,6 @@
   },
   "$defs": {
     "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
-    "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
-    "teamLabels": {
-      "anyOf": [
-        { "$ref": "#/$defs/label" },
-        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/label" } }
-      ]
-    },
     "capabilityName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
     "repoKey": { "type": "string", "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$" },
     "fromLocation": {