@awebai/oats 0.25.9 → 0.27.0

package/docs/design/launch-configurations.md

@@ -1,12 +1,16 @@
 # Launch configurations and launch recipes
 
-A **launch configuration** is a named way to start a harness, declared per
-scope under `launch-configs:` in `oats-config.yaml` (see
-docs/configuration.md): runtime, an executable, literal arguments,
-environment (literals or `{fromEnv}` references), model, yolo. It is
-independent of any soul; a soul may name one as its default
-(`launch-config:` in soul.yaml, `oats soul set --launch-config`), and a
-spawn, start or restart selects one by name.
+A **launch configuration** is a named way to start a harness, declared by
+the host under `launch-configs:` in the deployment's `oats-local.yaml` (see
+docs/configuration.md; 0.26.0, lead decision 2 — earlier kernels read it
+from a scope's `oats-config.yaml`): runtime, an executable, literal
+arguments, environment (literals or `{fromEnv}` references), model, yolo.
+It is independent of any soul, and a spawn, start or restart selects one by
+name (`--launch-config`, or the Desktop's per-launch choice). A launch
+configuration is a spawn-time host choice, never a soul field: `launch-config:`
+is not a field of a workspace-model soul.yaml (docs/soul.schema.json; discovery
+refuses it), so a v2 soul cannot name one, not even as a default. (A classic
+0.25 soul.yaml could name a preferred entry; 0.26.0 reads no such field.)
 
 A **launch recipe** is what a start is made of, recorded in the instance's
 `instance.json` under `launch` beside the rendered `command`:
@@ -15,9 +19,9 @@ A **launch recipe** is what a start is made of, recorded in the instance's
 {
   "version": 1,
   "runtime": "claude",
-  "launchConfig": "personal", "launchConfigSource": "/scope",
-  "executable": "/scope/tools/claude-wrapper.sh",
-  "executableDeclared": "./tools/claude-wrapper.sh", "executableResolvedFrom": "relative to /scope",
+  "launchConfig": "personal", "launchConfigSource": "/deployment",
+  "executable": "/deployment/tools/claude-wrapper.sh",
+  "executableDeclared": "./tools/claude-wrapper.sh", "executableResolvedFrom": "relative to /deployment",
   "args": ["--settings", "/abs/settings.json"],
   "env": { "KEY": { "fromEnv": "SRC" }, "LIT": "plain" },
   "model": "claude-opus-5", "yolo": true,
@@ -55,16 +59,16 @@ shows them: `list` and `preview` redact every environment value.
   that disagrees with the configuration's runtime is refused
   (`E_LAUNCH_CONFIG_MISMATCH`) before anything happens; the same runtime may
   be repeated; `--model` and `--yolo` override the configuration's fields.
-- Without `--launch-config`: a spawn takes the soul's `launch-config` default
-  or none; an existing home keeps its recorded configuration, except that
+- Without `--launch-config`: a spawn uses no configuration (the runtime's
+  defaults; a soul names none); an existing home keeps its recorded configuration, except that
   `--runtime` alone deliberately leaves it behind and renders the new
   runtime's defaults (no old executable or args are carried).
 - Model: explicit, else the configuration's, else on an existing home the
   recorded model when the runtime is unchanged, else the runtime's native
-  default; a spawn without either resolves the soul's preference for the
-  runtime. A model never crosses runtimes.
+  default; a spawn without either uses the runtime's native default (a
+  workspace-model soul declares no model). A model never crosses runtimes.
 - Executable: the configuration's (bare name on PATH; a path resolved against
-  the declaring scope when relative) or the runtime's default (claude through
+  the deployment directory when relative) or the runtime's default (claude through
   `oats-claude-config`). It must be a regular executable file; it is never
   run to probe it. Capability runtime-package requirements are checked with
   the runtime's default binary, as at spawn.
@@ -87,7 +91,7 @@ re-run by a start or restart.
 Read-only; nothing is locked or started. `--home ABS` describes an existing
 home under a selection (`selection.source`: `frozen` when nothing was
 selected, `config` when re-resolved, `frozen-command` for a home that
-predates recipes, whose selection needs the restart conversion);
+predates recipes, where a selection answers `E_LAUNCH_LEGACY`: re-spawn it);
 `--soul NAME [--dir SCOPE] [--agents-root ABS]` describes a new instance.
 Answer: `{context, selected, selection:{source, launchConfig, runtime,
 model, yolo}, runtime, model, modelSource, yolo, launchConfig,

package/docs/design/operations-contract.md

@@ -97,15 +97,16 @@ are listed. `use none --layer l` is a level statement and takes no soul or
 type. A layer bound to another capability at a level is never overwritten
 (`E_LAYER_BOUND` with the exact remedy).
 
+*(0.24/0.25 only — `oats soul set` was removed in 0.26.0: a soul is edited in its member repository, then `oats sync`. Kept for history.)*
 `oats soul set <name> [--dir] [--agents-root] [--runtime] [--model |
 --no-model] [--yolo | --no-yolo] [--backend] [--description |
---no-description] [--instructions-file <path>] --json` edits only the given
-`soul.yaml` lines and replaces `AGENTS.md`; packaged souls are refused
-(`E_SOUL_READONLY`). The receipt carries before/after and sha256s.
+--no-description] [--instructions-file <path>] --json` edited only the given
+`soul.yaml` lines and replaced `AGENTS.md`; packaged souls were refused
+(`E_SOUL_READONLY`). The receipt carried before/after and sha256s.
 
 ## Remote
 
-`inspect`, `operation`, `use` and `soul` route with `--server <id>` through
+`inspect` and `operation` route with `--server <id>` through
 the saved route. The gate is the destination's `features` list containing
 `operations` and its `operationsApi: 1` (`E_REMOTE_INCOMPATIBLE` before
 anything is sent): `features` describes what a kernel can do locally, which
@@ -113,12 +114,28 @@ is what runs on the host. The probe's `remote` list describes what a CLI
 can ROUTE to a server and is what a GUI checks on the local CLI before
 offering remote actions; it is not a gate on the destination. An explicit `--dir` is the exact member context and
 travels as is; `--home` is its own context; otherwise the registered
-workspace is the scope. Soul instructions travel as bytes on the ssh stdin
-(`--instructions-stdin` on the host), never as a local path.
+workspace is the scope.
 
 ## Replaceability
 
-`test/inspect.test.mjs`, `test/operation.test.mjs` and
-`test/operations-routing.test.mjs` use an owned alternative knowledge
-provider (namespace `notes`, one `MEMORY.md`, operations `harvest` and
-`inspect`) and never mention the official provider.
+`test/operation.test.mjs` runs the real CLI on the Northwind fixture and
+replaces the provider in a spawned home's module copy (what `operation run
+--home` executes) with a recording provider of its own: the runner is generic
+and assumes nothing about the official provider's operations.
+
+## Workspace model (0.26.0)
+
+On a workspace deployment, and for a home whose `instance.json` records
+`modules`, `oats inspect`, `oats readiness` and `oats operation run` read the
+workspace model's own records instead of the config chain:
+- the subject is `--home` (instance.json plus its module copies) or `--soul`
+  (the soul resolved as its spawn would be), never a scope;
+- `operationsApi` is 2 (also on the run result), and each soul row carries
+  `soulsApi: 2`;
+- there is no trust gate (`E_CAPABILITY_BLOCKED` is gone);
+- no `scope`, `chain`, `activation`, `snapshot` or `currentConfig` block.
+
+The payloads are specified in
+[desktop-cli-api.md](../desktop-cli-api.md#inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260).
+The sections above describe the classic path, which is removed with the classic
+config chain.