@awebai/oats 0.25.0 → 0.25.1

package/bin/oats.mjs

@@ -36,9 +36,8 @@ import {
 } from "../lib/core.mjs";
 import {
   assertNoSymlinkedParents, writeFileAtomic,
-  LOCK_FILE, readLock, writeLock, resolvePackages, approve as approvePackage, executablesDigest, readPackageTree,
-  classifyPackageValue, manifestExecutables, parsePackageRequest,
-} from "../lib/packages.mjs";
+  LOCK_FILE, readLock, writeLock, resolvePackages, approve as approvePackage,
+  classifyPackageValue, parsePackageRequest, executablesDigestAt } from "../lib/packages.mjs";
 import { loadLocal, discoverWorkspace, validateWorkspace } from "../lib/workspace.mjs";
 import * as remoteModule from "../lib/remote.mjs";
 import { createInterface } from "node:readline/promises";
@@ -1941,10 +1940,12 @@ function printTable(header, rows) {
 
 /** Executables digest of a locked package, read over the remote at its locked commit. */
 async function lockedExecutablesDigest(id, entry, workspace, catalog, remoteOptions) {
+  // ONE definition of the approval digest (lib/packages.mjs executablesDigestAt) — the
+  // same function resolveSoul re-runs at spawn (M3), so sync and spawn can never disagree.
   const req = parsePackageRequest(id, workspace.packages[id], catalog);
-  const tree = await readPackageTree(remoteModule, req.remoteRef, entry.commit, entry.path, { remoteOptions });
-  const targets = tree.manifests.flatMap((m) => manifestExecutables(m.manifest).map((x) => `${m.name}: ${x.kind} ${x.name} → ${x.target}`));
-  return { digest: executablesDigest(tree), targets };
+  const { digest, executables } = await executablesDigestAt(remoteModule, req.remoteRef, entry.commit, entry.path, entry.capabilities ?? null, { remoteOptions });
+  const targets = executables.map((x) => `${x.capability}: ${x.kind} ${x.name} → ${x.target}`);
+  return { digest, targets };
 }
 
 /** One yes/no question on the terminal (TTY only; the caller checks). */
@@ -3001,18 +3002,27 @@ function createCmd() {
  * oats <namespace> <command> [args…] — run a command an active capability
  * declares in its manifest (`commands: { name: "script args" }`).
  * Kernel subcommands take precedence over capability namespaces.
+ *
+ * Three contexts, one contract (OATS_CAPABILITY / OATS_SETTINGS / OATS_CLI_BIN):
+ *   - inside an instance home: the home's materialized modules (instance.json.modules);
+ *   - from a v2 DEPLOYMENT (oats-local.yaml in reach, no home): operator-level
+ *     dispatch — resolve exactly as `oats spawn --soul <x>` would, fetch the
+ *     namespace's capability into <deployment>/.oats/modules/<cap>@<commit12>/
+ *     and run THAT copy with the soul's merged payload (lib/operator-dispatch.mjs;
+ *     contracts doc, "Post-0.25.0 clarifications");
+ *   - otherwise the classic config chain.
  */
-function capabilityCommand() {
+async function capabilityCommand() {
   // JSON-aware boundary: in --json mode every dispatch failure — inactive or
   // untrusted capability, duplicate namespace, unknown subcommand, broken
   // metadata/manifests, malformed command values — must still emit exactly
   // one envelope object on stdout. The WHOLE dispatcher runs inside the
   // boundary; only "no namespace matched" escapes (returns false to the help
   // fallthrough).
-  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   const NOT_DISPATCHED = Symbol("not-dispatched");
   let outcome;
-  try { outcome = dispatch(); }
+  try { outcome = await dispatch(); }
   catch (e) {
     // Unexpected throw from discovery/trust/decoding: keep the envelope contract.
     bail("E_CAPABILITY_BROKEN", e.message || e);
@@ -3020,7 +3030,23 @@ function capabilityCommand() {
   }
   return outcome !== NOT_DISPATCHED;
 
-  function dispatch() {
+  /** Operator-level dispatch from a deployment directory (no instance home). */
+  async function operatorDispatch() {
+    let hit;
+    try {
+      const { resolveOperatorDispatch } = await import("../lib/operator-dispatch.mjs");
+      let catalog = null; try { catalog = officialPackageCatalog(); } catch { /* the lock carries url for catalog packages */ }
+      hit = await resolveOperatorDispatch(process.cwd(), cmd, flag("soul"), { remoteOptions: remoteOptionsFromEnv(), catalog });
+    } catch (e) {
+      if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details);
+      throw e;
+    }
+    if (!hit) return NOT_DISPATCHED;
+    const teamCtx = hit.soul?.team ? { name: hit.soul.team } : undefined;
+    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, hit.settings, teamCtx, hit.ensureTree);
+  }
+
+  async function dispatch() {
     let activeIds;
     let context = process.cwd();
     let teamCtx;
@@ -3032,6 +3058,7 @@ function capabilityCommand() {
     // namespace the operator typed on the command line.
     let capSettings = Object.create(null);
     let instanceModules = false;
+    let deployment = null;
     try {
       if (metaFile && existsSync(metaFile)) {
         const meta = JSON.parse(readFileSync(metaFile, "utf8"));
@@ -3043,12 +3070,19 @@ function capabilityCommand() {
         // spawned before a team: block was declared have no snapshot.
         teamCtx = meta.team || resolveOatsConfig(context).team;
       } else {
-        const resolved = resolveOatsConfig(context, flag("soul"));
-        activeIds = resolved.capabilities.map((c) => c.id);
-        for (const c of resolved.capabilities) capSettings[c.id] = c.settings || {};
-        teamCtx = resolved.team;
+        // Not inside a home: a v2 deployment (oats-local.yaml in reach) resolves
+        // through the workspace, exactly as a spawn of --soul would (below).
+        try { const { deploymentOf } = await import("../lib/operator-dispatch.mjs"); deployment = deploymentOf(context); }
+        catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
+        if (!deployment) {
+          const resolved = resolveOatsConfig(context, flag("soul"));
+          activeIds = resolved.capabilities.map((c) => c.id);
+          for (const c of resolved.capabilities) capSettings[c.id] = c.settings || {};
+          teamCtx = resolved.team;
+        }
       }
     } catch (e) { bail("E_CONFIG_BROKEN", e.message || e); throw e; }
+    if (deployment) return operatorDispatch();
     // Workspace model: an instance's own materialized modules are the command
     // namespaces available to it (instance.json.modules → <home>/.oats/modules).
     const mans = Object.values(capabilityManifests(instanceModules ? instanceHome : context)).filter((m) => m.command === cmd && m.commands);
@@ -3058,6 +3092,14 @@ function capabilityCommand() {
     if (!activeIds.includes(m.capability)) bail("E_CAPABILITY_INACTIVE", `${m.capability} command namespace is not active in the current context/instance`);
     const trust = capabilityTrust(m, context);
     if (!trust.trusted) bail("E_CAPABILITY_BLOCKED", `${m.capability} executable command is blocked: ${trust.reason}`);
+    return runManifestCommand(m, capSettings[m.capability] || {}, teamCtx, () => m._dir);
+  }
+
+  /** Help / unknown-command / spec validation / exec — shared by every context.
+   *  `m` is the manifest (with `capability`; `_dir` may be absent until `ensureDir`
+   *  resolves the directory holding the executable — the operator branch fetches
+   *  the module tree only when a command is actually going to run). */
+  async function runManifestCommand(m, settings, teamCtx, ensureDir) {
     const sub = args[1];
     const cmds = Object.keys(m.commands);
     // `oats <ns> --help` and `oats <ns> <cmd> --help` answer from the manifest
@@ -3083,17 +3125,22 @@ function capabilityCommand() {
     const spec = m.commands[sub];
     if (typeof spec !== "string" || !spec.trim()) bail("E_CAPABILITY_BROKEN", `oats ${cmd} ${sub}: manifest command must be a non-empty string (got ${JSON.stringify(spec)})`);
     const [script, ...rest] = spec.trim().split(/\s+/);
+    let dir;
+    try { dir = await ensureDir(); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
+    const withDir = { ...m, _dir: dir };
     let abs;
-    try { abs = capabilityExecutablePath(m, script); }
+    try { abs = capabilityExecutablePath(withDir, script); }
     catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
-    if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(m._dir, script)})`);
+    if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
     const r = spawnSync("node", [abs, ...rest, ...args.slice(2)], { stdio: "inherit", env: {
       ...process.env, OATS_CAPABILITY: m.capability,
       // Package-runtime boundary: dispatched commands receive the active
-      // capability's EFFECTIVE settings (instance snapshot or resolved context),
-      // same contract as lifecycle hooks — capabilities read their settings
-      // here instead of importing the kernel resolver.
-      OATS_SETTINGS: JSON.stringify(capSettings[m.capability] || {}),
+      // capability's EFFECTIVE settings (instance snapshot, resolved context, or
+      // the soul's merged payload on operator-level dispatch), same contract as
+      // lifecycle hooks — capabilities read their settings here instead of
+      // importing the kernel resolver.
+      OATS_SETTINGS: JSON.stringify(settings || {}),
       // PATH is not a trusted runtime boundary (maintainer finding 1): pass the
       // canonical absolute executable of THIS CLI; official consumers execFile
       // it directly and never resolve `oats` from PATH or a shell.
@@ -3675,7 +3722,7 @@ else if (cmd && Object.hasOwn(REMOVED_VERBS, cmd)) {
   console.log(usageText());
   process.exit(1);
 }
-else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && capabilityCommand()) { /* dispatched */ }
+else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && await capabilityCommand()) { /* dispatched */ }
 // No matching kernel command or capability namespace: in --json mode the help
 // text must NOT contaminate stdout — still one envelope object, nonzero exit.
 else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", `unknown command "${cmd}" — no kernel subcommand or active capability namespace matches`);

package/docs/conventions.md

@@ -31,43 +31,70 @@ instance/.claude/skills -> ../.agents/skills
 
 Spawn copies kernel + soul-private + active capability skills into real
 instance-local directories there. Directory symlinks are not used because
-harness recursive discovery may not descend through them. Packages retain
-skills in their own artifact; activation selects them for materialization. Config-level `.agents/skills` is not an OATS capability source
+harness recursive discovery may not descend through them. Under the workspace
+model (0.25) every capability is copied whole into
+`instance/.oats/modules/<capability>/` and its skills into
+`instance/.agents/skills/<capability>/<skill>/`; nothing is installed at a
+config level. Config-level `.agents/skills` is not an OATS capability source
 or an ambient runtime discovery root.
 
-Pi starts spawned sessions with ambient skill and context discovery disabled
-and the one instance path explicit; its globally configured extensions remain
-enabled. Claude runs provider-native: it reads the instance's `.claude/skills`
-and `CLAUDE.md` symlinks, and the operator's own user and project
-configuration — skills, plugins, settings — stays in effect. Neither runtime
-gets a redirected config home. `composition.materialized.runtimePosture` in
-`instance.json` records what each instance actually exposes.
-`oats-getting-started` is the sole pre-workspace ambient bootstrap.
-
-Duplicate skill directory names are errors unless config's `skill-overrides`
-selects a source.
+Harnesses start normally (workspace-model decision 13, and the behaviour of
+every launch a 0.25 kernel performs, classic homes included): Pi starts with
+cwd = the instance home, the composed `AGENTS.md` appended to its system
+prompt, and its own skill, context and extension discovery intact — the
+instance's copied skills are found because they sit under cwd; machine-level
+and repo-level skills resolve exactly as without OATS. *(0.24 kernels started
+Pi with ambient skill and context discovery disabled and the one instance path
+explicit; that exclusion is gone.)* Claude runs provider-native: it reads the
+instance's `.claude/skills` and `CLAUDE.md` symlinks, and the operator's own
+user and project configuration — skills, plugins, settings — stays in effect.
+Neither runtime gets a redirected config home.
+`composition.materialized.runtimePosture` in `instance.json` records what each
+instance actually exposes. `oats-getting-started` is the sole pre-workspace
+ambient bootstrap.
+
+Duplicate skill directory names within the OATS-composed set are errors
+(`E_SKILL_DUPLICATE`, naming both capabilities) unless the classic config's
+`skill-overrides` selects a source; between a composed skill and an ambient
+repo/machine skill the harness's own precedence decides (decision 16).
 
 ## Package locations
 
+**Workspace model (0.25, current):** nothing is installed. A capability lives
+where its owner keeps it and is copied whole into each instance at spawn:
+
+```text
+<member repo>/capabilities/<name>/oats.json           # member-tier capability, latest state (membership is the trust)
+<package repo>/oats-package/oats-package.json         # package-tier: versioned via oats-workspace.yaml packages:
+<deployment>/oats-lock.json                           # lockfileVersion 3: package commit, integrity, per-version approval
+<instance>/.oats/modules/<capability>/                # the copy this instance runs
+```
+
+**Classic 0.24 layout** (still launched by the 0.24 kernel; a 0.25 kernel
+reads none of it as configuration — see [rebuild-to-v2.md](rebuild-to-v2.md)):
+
 ```text
 <package>/capabilities/<name>/oats.json                 # the official marketplace (install source, not ambient)
 <level>/.agents/capabilities/installed/<name>/oats.json # acquired (gitignored, restorable)
 <level>/.agents/capabilities/owned/<name>/oats.json     # authored at this scope (source; committed where the scope is a repo)
-<level>/oats-lock.json                                  # external source/integrity/trust
+<level>/oats-lock.json                                  # lockfileVersion 2: external source/integrity/trust
 ```
 
 ## Quick map
 
-| Thing | Canonical location |
-|---|---|
-| Config | `<level>/oats-config.yaml` |
-| Acquisition lock | `<level>/oats-lock.json` |
-| Soul operating doc | `soul/AGENTS.md` |
-| Soul Claude view | `soul/CLAUDE.md -> AGENTS.md` |
-| Soul-private skills | `soul/skills/` |
-| Instance operating doc | `instance/AGENTS.md` (generated) |
-| Instance skill set | `instance/.agents/skills/` |
-| Instance metadata | `instance/instance.json` |
+| Thing | Canonical location (0.25 workspace model) | 0.24 classic |
+|---|---|---|
+| Shared declaration | `oats-workspace.yaml` in the host repo; `oats-membership.yaml` in every member | `oats-config.yaml` chain, `oats.yaml` |
+| Per-machine config | `<deployment>/oats-local.yaml` (uncommitted) | `oats-config.yaml` `settings:` |
+| Acquisition lock | `<deployment>/oats-lock.json` (v3) | `<level>/oats-lock.json` (v2) |
+| Soul source | `<member repo>/souls/<name>/` | `agents/<name>/soul/` |
+| Soul operating doc | `souls/<name>/AGENTS.md` | `soul/AGENTS.md` |
+| Soul Claude view | `souls/<name>/CLAUDE.md -> AGENTS.md` | `soul/CLAUDE.md -> AGENTS.md` |
+| Soul-private skills | `souls/<name>/skills/` | `soul/skills/` |
+| Instance operating doc | `instance/AGENTS.md` (generated) | same |
+| Instance skill set | `instance/.agents/skills/` | same |
+| Instance modules | `instance/.oats/modules/<capability>/` | `.agents/capabilities/installed/` (shared) |
+| Instance metadata | `instance/instance.json` (`modules{}`, `providers{}`, `workspace{}`) | `instance/instance.json` |
 
 Symlinks prevent compatibility paths from drifting. Generated regular files
 separate canonical portable identity from scope-dependent runtime policy.

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-23 17:40Z · **Workspace model v2 phases A–C ON MAIN (`59ae22df`, PR99) → `v0.25.0` tagged (release run in flight)** · Phase D next (framework repos as the first workspace; six expert souls; `oats.core`/`oats.setup` rewrite) · ⏸ parity pipeline still paused except 10B-0 (→ 0.24.14 when the engineer hands off; note: 0.24.14 must be cut from the 0.24 line, not main).
+**Last update:** 2026-09-23 17:40Z · **Workspace model v2 phases A–C ON MAIN (`59ae22df`, PR99) → **`v0.25.0` PUBLISHED** (bump `dc333e4e`)** · Phase D next (framework repos as the first workspace; six expert souls; `oats.core`/`oats.setup` rewrite) · ⏸ parity pipeline still paused except 10B-0 (→ 0.24.14 when the engineer hands off; note: 0.24.14 must be cut from the 0.24 line, not main).
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/design/2026-09-23-simplified-workspace-model.md

@@ -510,7 +510,7 @@ Today's `capabilities.layers.messaging.{capability, from, global, souls, setting
 |---|---|---|
 | True of every instance of the soul | `soul.yaml` → `messaging:` / `knowledge:` | `messaging: { channels: [northwind-eng] }`, `knowledge: { owns: release-manager }` |
 | A fact about this machine | `oats-local.yaml` → `settings.<capability>.<key>` (absolute paths refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
-| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` → `instance.json` `providers.<cap>` (the Desktop's confirmed apply carries the same map) | `--provider oats.aweb identity.source=retained:release-seat` — one instance takes the retained seat; other instances of the soul mint fresh |
+| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` → `instance.json` `providers.<cap>` (the Desktop's confirmed apply carries the same map) | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` — one instance takes the retained seat; other instances of the soul mint fresh |
 
 The provider's `binding` contract (`normalize → bind → check`) runs over the merged payload exactly as today; the provider still enforces its own rules (e.g. a state root outside the work tree).
 

package/docs/design/2026-09-23-workspace-module-contracts.md

@@ -307,3 +307,154 @@ Appended, not edited in place; each item names the section it refines. Decision
 **§6 `oats package remove <id>` (M15).** BOTH branches — the file tracked by the checkout (edited) and untracked/absent (not edited) — answer `E_PACKAGE_MISSING { id, path? }` when `<id>` is not declared in `packages:`. The tracked receipt is `{ action: "remove", id, value: null, previous: <old value>, edited: true, file }`; the untracked receipt is `{ action: "remove", id, value: null, edited: false, file: null, line: null, hint }` — `previous` is absent and `line` is `null` (a removal has no line to add).
 
 **§6 features.** `catalog` is no longer advertised in `oats version --json` `features` (the verb is removed; the official catalog is reached through `packages:` + `sync`, not a command).
+
+## Post-0.25.0 clarifications (team review, 2026-09-23)
+
+**Capability commands outside an instance home (`oats <ns> <cmd>` from the
+deployment).** Inside an instance home the dispatcher resolves the namespace from
+the home's materialized modules (`instance.json.modules` → `<home>/.oats/modules`);
+that shipped in 0.25.0. Outside a home — the operator acts a knowledge layer needs
+before any instance exists (`oats okf init`, base migration) — the intended rule
+is: **resolve exactly as a spawn of `--soul <name>` would** (`prepareInstance` →
+the soul's Resolution), fetch the namespace's capability into the deployment's
+module store `<deployment>/.oats/modules/<cap>@<commit>/` (the same per-commit
+store capability-defined agents use), and dispatch to that copy with the soul's
+merged payload as `OATS_SETTINGS`. Never "the newest instance's copy" (an
+instance is not an authority for the deployment) and never an unlocked cache
+read (the lock's approval is the gate, as for spawn). `--soul` is required when
+the namespace's capability is not a workspace default. **Status: 0.25.x
+follow-up** — 0.25.0 still answers `E_CAPABILITY_INACTIVE` there (the pre-v2
+chain); the interim is to run the module binary directly with `OATS_SETTINGS`
+and `OATS_CLI_BIN`, as the tarball smoke does.
+
+**`work: workspace` is kept.** A coordination soul's `./work` is the deployment
+boundary — the directory holding `oats-local.yaml` (the taught
+`<name>-workspace/`, with member clones beside it) — read-only across member
+clones, no branch recorded. The clone map in `oats-local.yaml` (`clones:`) is
+how such a soul finds a member whose clone is elsewhere. **Status: the
+directory link is the intent; 0.25.0's kernel still derives the boundary from
+the classic `team:` scope (`docs/souls-and-instances.md` open thread) — 0.25.x
+follow-up binds it to the `oats-local.yaml` directory.**
+
+**`identity.source` (oats.aweb) is the absolute path of the `.aw` directory to
+retain**, given per spawn (`--provider oats.aweb identity.source=/abs/.aw`) or
+per machine (`oats-local.yaml settings.oats.aweb.identity.source`); the kernel
+resolves no symbolic seat names. Absolute paths never enter the workspace file
+(decision 14).
+
+**Member capabilities are a code-execution boundary** (decision 2: membership is
+the trust; hooks and scripts of every member's default branch run on every
+operator's machine at spawn). For a mixed public/private organisation the
+recommendation is: **souls only in public members; executable capabilities come
+from packages (approved per version) or from private members.** The onboarding
+skill (Phase E) states this beside the hosting rule (decision 26).
+
+
+### 0.25.1 fix round (team review, 2026-09-23) — appended, not edited in place
+
+Each item names the section it refines and the review finding it closes. The
+implementation lands in kernel 0.25.1 (`docs/release-notes/v0.25.1.md`); no
+API integer or feature name changes.
+
+**§3 slot `none` (L1).** A soul's `none` for a slot **empties the slot and drops
+any layer-bearing capability the WORKSPACE DEFAULTS contributed for that
+layer** — whether it arrived through `defaults.<slot>`, `defaults.capabilities`
+or `defaults.byTeam[team].capabilities`. A layer-bearing capability **the soul
+itself declares** in its own `capabilities:` alongside `none` for that layer is
+`E_SLOT_CONFLICT { reason: "none" }` (spell `<cap>: off` to remove it). This
+replaces the Phase B reading under which a layered default arriving via
+`defaults.capabilities` was itself a conflict: the workspace's choice is a
+default and `none` is the soul's answer to it; only the soul contradicting
+itself is loud.
+
+**§2/§5 per-commit soul cache (M1).** `ensureWorkspaceSoul` fetches a soul's
+source at `(repoKey, commit)` into `<deployment>/agents/<name>/souls/<commit12>/`
+— **immutable once written** (staged, then renamed in; never removed by the
+kernel) — and maintains `<deployment>/agents/<name>/soul` as a **symlink to the
+current commit's directory**, swapped atomically (symlink to a temp name +
+rename over) so classic readers (`findAgent`, `doctor`, the classic spawn path)
+keep seeing "current". A spawned home's `<home>/soul` links **its own commit's
+directory** (the realpath of `souls/<commit12>/`), never the swapped pointer:
+a running instance's soul never changes under it (decision 7), a `--preview`
+may fetch a new commit and swap the pointer without touching any directory an
+instance links, and OKF 2's owner pin (`owners.json` = `realpath(<home>/soul)`)
+stays valid for the instance that registered it. `.oats-soul-source.json`
+remains the stamp of "current". A 0.25.0 layout (`agents/<name>/soul` a real
+directory, no `souls/`) is migrated in place on first use: the directory moves
+to `souls/<commit from the stamp, else unknown>/` and the pointer replaces it.
+A soul symlink whose target lies inside the same `agents/<name>/souls/` is the
+one kernel-owned symlink soul readers accept.
+
+**§1 transport (M2).** `parseRepoRef(ref).key` is unchanged — `<host>/<path>`
+is the identity everywhere and every comparison is by key. The **fetch url
+honours the form written**: `git@host:org/repo(.git)` and `ssh://…` fetch over
+SSH as written; `https://…` fetches over HTTPS; the bare scheme
+`git:host/org/repo` fetches over HTTPS by default **unless
+`remoteOptions.transport === "ssh"`** (a per-machine choice; `oats-local.yaml`
+may carry it once the schema admits it — reported by lane 3, not landed here).
+The operator's SSH access is therefore used when the operator wrote an SSH ref,
+and a private repo no longer degrades to `not-found` → standalone through an
+unintended HTTPS probe. When the standalone fallback engages the discovery
+carries `standaloneReason`/`hostFailure { code, reason, url }` so the CLI can
+print *why*.
+
+**§3/§4 approval re-verified at spawn (M3).** For a `from: package` module
+`resolveSoul` recomputes `executablesDigest` over the package tree **at the
+locked `entry.commit`** and requires equality with `entry.approved.executables`
+→ else `E_PACKAGE_UNAPPROVED { reason: "digest-mismatch", approved, actual }`.
+The one digest definition is `lib/packages.mjs#executablesDigestAt(remote, ref,
+commit, path, capabilities)`, shared by `sync` and `resolve`; a hand-edited lock
+(same id/version, different commit, copied approval) can no longer materialize
+and run unapproved hooks. Cached per `(id, commit)` within a process.
+
+**§1 peeled commit OIDs (M4).** `observeRemote(ref, { at })` accepts an
+annotated tag's OID (or name) but **records the peeled commit** (`<oid>^{commit}`)
+as `commit` — in its result, in the lock, in `fetchRemoteTree`'s errors and in
+every `instance.json` record. A tag OID is never stored where a commit is
+expected.
+
+**§1 listing hygiene (L3, L4).** `listRemoteTree` filters by depth **before**
+asserting entry-name safety, so one unsafe deep name does not blank a member's
+souls (unsafe names at the kept depth are still `E_REMOTE_TREE_UNSAFE`). A git
+child killed for `maxBuffer` (`ENOBUFS`) is not reported as `timeout`; an
+unclassified listing failure is wrapped as `E_REMOTE_UNREADABLE { reason:
+"unknown" }` so discovery records a problem row instead of aborting.
+
+**§2 `validateWorkspace` absolute paths (L2).** The absolute-path refusal
+applies to **ref/path fields only** — `members[]`, `packages` values, `stores`
+values, `external[].source` / `external[].soul`, `defaults.*.from` — never to
+`teams.<label>.description` or to the opaque `messaging` payload.
+
+**§3 revision (L6).** `Resolution.revision = hash(declRevision, payloadRevision)`
+where `declRevision` covers the declarations (member/package commits, the
+composed capability set, skills, injects) and `payloadRevision` covers the
+payload layers (soul slot payloads ⊕ `oats-local.yaml settings` ⊕
+`--provider`). Both are exposed on the Resolution; decision binding keeps using
+`revision`, so a settings-only difference still refuses a stale apply, while
+`spawn --preview` can say **`changed since: declarations | payload | both`**
+instead of a bare `changedSince`.
+
+**§6 operator-level dispatch (B3, implements the rule stated above).** Outside a
+home, with `oats-local.yaml` present, `oats <ns> <cmd> … --soul <name>` runs
+`prepareInstance(dir, name)`, picks the module whose `manifest.command === <ns>`,
+ensures its tree in `<deployment>/.oats/modules/<cap>@<commit12>/` (member: the
+member repo at `module.from.commit`, `module.dir`; package: the lock entry) and
+dispatches to that copy with `OATS_SETTINGS = resolution.payloads[cap]` and
+`OATS_CLI_BIN`. `--soul` absent → `E_BAD_ARGS` naming it; a namespace no module
+provides → `E_UNKNOWN_COMMAND`. Trust is the resolution's (membership;
+`E_PACKAGE_UNAPPROVED` for an unapproved package).
+
+**§5/§6 `work: workspace` under v2 (B2, implements the rule stated above).**
+With `prepared` present, a `work: workspace` soul's `./work` links the
+deployment directory (`prepared.deployment`, the one holding `oats-local.yaml`);
+no branch is recorded; the "needs a declared boundary" remedy names
+`oats-local.yaml`, not `oats-config.yaml`. The classic root is unchanged.
+
+**Decision 13 reach (L7).** "Harnesses start normally" is a property of the
+0.25 **launcher**: every `pi` launch a 0.25 kernel performs — module homes and
+classic 0.24 homes alike — starts pi with cwd = home, the composed `AGENTS.md`
+appended, and pi's own skill/context discovery intact. Consequently `oats
+session recompose` refuses a **module home** (`instance.json.modules` present)
+with `E_UNSUPPORTED_MODE` ("re-spawn"); the `session-recompose` feature name
+stays advertised because the verb still serves classic homes
+(`docs/desktop-cli-api.md`).

package/docs/design/2026-09-23-workspace-v2-implementation-plan.md

@@ -15,7 +15,7 @@ A clean v2 of the kernel's declaration, resolution and launch path: read `oats-w
 
 ## Work packages
 
-Each is one PR (or two small ones), reviewed by me, on `main`, behind the v2 seam until W7. Order is dependency order; W1–W3 can proceed in parallel lanes.
+Each is one PR (or two small ones), reviewed by me, on `main`, as canonical code from the first phase (no seam — see the approach above). Order is dependency order; W1–W3 can proceed in parallel lanes. **Status (2026-09-23): W1–W8 and W10 shipped in OATS 0.25.0 (PR99 `59ae22df`); W8's last part — folding the classic no-`oats-local.yaml` spawn path into the one pipeline and deleting the v1 residue — is a follow-up; W9/W9b/W11/W12 are Phases D–F.**
 
 | # | Package | Delivers | Owner | Size |
 |---|---|---|---|---|
@@ -52,7 +52,7 @@ Each phase = one developer-swarm workflow (parallel agents, disjoint files, agai
 | Risk | Mitigation |
 |---|---|
 | Remote access context is subtle (SSH vs HTTPS vs `gh` token; private repos) | W2 uses git itself (`git ls-remote`, `git archive`/shallow fetch) with the operator's configured credential helpers — no new credential store; typed `cannot read` never guesses |
-| `core.mjs` entanglement makes W8 risky | W8 is deletion behind a green W7; the seam guarantees nothing live depends on what is deleted; CI + the Northwind fixture + Desktop suites are the gate |
+| `core.mjs` entanglement makes W8 risky | W8 is deletion behind a green W7; `rg` proof of zero importers per module before each deletion (the v1-residue table from the Phase C review); CI + the Northwind fixture + Desktop suites are the gate |
 | Package approval UX ("asks once") in non-interactive spawns | `oats sync` is where approval is asked; `spawn` refuses `E_PACKAGE_UNAPPROVED` pointing at `sync` — never prompts mid-spawn |
 | Latest-state members drift between preview and apply | The resolution records the member commit; apply re-observes and refuses `E_DECISION_STALE` if it moved — same mechanism as today's decision revision |
 | Desktop relying on "installed" | Removed as a state in W12; until then the Capabilities view keeps working on 0.24.x DTOs (contracts unchanged) |

package/docs/desktop-cli-api.md

@@ -450,6 +450,26 @@ the pre-fix marker and is never accepted for dispatch.
 
 ## Readiness quartet, signatures, enforced policy (`oats readiness`, `readinessApi: 1`, OATS 0.24.8+)
 
+> **0.25 status — the producers below are the 0.24 tier.** The readiness DTO
+> (`readinessApi: 1`) still ships unchanged, but its four checks are *produced*
+> by the classic observers: `installed` by `oats list` over the
+> `.agents/capabilities/installed/` tier, `trusted` by the per-artifact approval
+> that `oats trust` wrote, `configured` by `oats-config.yaml` activation, and
+> `enrolled` by the `oats.yaml` backlink. On a **workspace deployment**
+> (`oats-local.yaml` present) none of those sources exists: nothing is installed,
+> approval is per package version in `oats-lock.json` v3 (`oats sync`), activation
+> is derived (workspace defaults ⊕ soul `capabilities:`), and membership is
+> `oats-membership.yaml` observed over the remotes. `oats list` and `oats trust`
+> are removed verbs (`E_UNKNOWN_COMMAND`), so a `remedy` naming them cannot be
+> run. Treat the field names and producer strings as the stable wire shape they
+> are; for the workspace-model facts read `oats spawn <soul> --preview --json`
+> (`modules[]` with from/commit/digest — the "installed" and "configured"
+> truth), `oats sync --json` `approvalNeeded[]` (the "trusted" truth) and
+> `oats workspace status --json` (the "enrolled" truth). Re-basing the quartet on
+> those producers is an open thread of [the workspace model](#workspace-model-workspaceapi-2);
+> when it lands it will be announced as a new feature name, not a silent change of
+> `readinessApi: 1`.
+
 `oats readiness [--soul <name>] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json`
 is the first-run readiness view (frame 09) and the Capabilities readiness rows
 (frame 04). Every fact is derived from the **same** data `oats inspect` reports
@@ -1026,6 +1046,18 @@ refreshes the home in place:
   schedule; the receipt's `note` says so. Refuses a retiring home
   (`E_INSTANCE_RETIRING`), captured incarnations and capability-defined souls
   (`E_UNSUPPORTED_MODE`: those are refreshed by a new resolution / package).
+- **Module homes (0.25+) are `E_UNSUPPORTED_MODE` too.** A home whose
+  `instance.json` carries `modules{}` (spawned on a workspace deployment,
+  `instance-modules`) answers `E_UNSUPPORTED_MODE` ("recompose from
+  materialized modules is not supported yet; re-spawn"): its `AGENTS.md` was
+  composed from the soul at a recorded member commit plus the materialized
+  modules' injects, and the instance never changes under itself (decision 7).
+  The refresh path for such a home is a new spawn (the soul is re-fetched at
+  the member's current commit). `session-recompose` **stays advertised** in
+  `features[]` because the verb still works for classic homes; gate the UI
+  action on the feature AND on the absence of `instance.json.modules`
+  (`oats status --json` `instances[].modules` is non-empty for a module home),
+  and render the typed refusal otherwise.
 - Gate on `features.includes("session-recompose")`. It is an **operator
   action** (the human or the instance's parent), never something a Desktop
   poll or an agent runs on itself.

package/docs/desktop-succession.md

@@ -12,10 +12,17 @@ the OATS Desktop app (`packages/desktop/` in the framework repo):
 
 ## Migrating a deployment that used `oats.web`
 
+Under the **0.25 workspace model** there is nothing to uninstall: remove
+`oats.web` from `oats-workspace.yaml` `packages:` / `defaults.capabilities`
+and from any `soul.yaml` `capabilities:`, run `oats sync` (the lock v3 entry
+disappears with the declaration), and use the Desktop app (step 3 below).
+
+For a **0.24 classic** deployment:
+
 1. Remove the `oats.web` entry from `capabilities.additive` in every
    `oats-config.yaml` in your config chain.
-2. Remove the `oats.web` entry from `oats-lock.json` at the same scope(s), and
-   delete any stale installed copy under `.agents/capabilities/installed/`.
+2. Remove the `oats.web` entry from `oats-lock.json` (v2) at the same scope(s),
+   and delete any stale installed copy under `.agents/capabilities/installed/`.
 3. Use the OATS Desktop app instead: `cd packages/desktop && npm install &&
    npm run rebuild && npm start` (see `packages/desktop/README.md`).
 

package/docs/desktop.md

@@ -84,10 +84,15 @@ The probe/mutation contract is specified in
 
 The app starts on the directory it was launched with (its own folder by
 default). To view a deployment, open the workspace switcher in the sidebar
-and choose **Add workspace → Browse**, then point it at an OATS workspace —
-a directory containing `agents/`, or `local-agents/` for machine-local
-souls, or a team scope whose `oats-config.yaml` declares `team:`. Team scopes
-show every member repo's agents under one roster with a workspace switcher.
+and choose **Add workspace → Browse**, then point it at an OATS deployment —
+a directory containing `agents/` (under the 0.25 workspace model that is the
+`<name>-workspace/` directory holding `oats-local.yaml` and `agents/`;
+under 0.24, an `agents/` root, a `local-agents/` root for machine-local souls,
+or a team scope whose `oats-config.yaml` declares `team:`). *The Desktop's own
+multi-repo roster ("team scopes show every member repo's agents under one
+roster") still keys on the 0.24 `oats-config.yaml` `team:` declaration; reading
+the member set from `oats-local.yaml` / `oats workspace status` is the Phase F
+follow-up named in the [0.25.0 notes](release-notes/v0.25.0.md#desktop).*
 Added workspaces are remembered and offered as suggestions next time.
 
 Local souls (uncommitted, machine-local agents under `local-agents/`) are

package/docs/execution-targets.md

@@ -231,10 +231,22 @@ and needs equivalent registration glue when switched to session delivery.
 
 ## Shared permission setting
 
-Set `yolo: true` in an `oats-config.yaml` to apply it to that scope. The closest
-scope wins; an optional `yolo` in soul.yaml overrides it; `oats spawn --yolo` or
-`--no-yolo` overrides both. `oats create` accepts those flags too. Desktop offers
-the same per-launch choice. With no setting, native policy is retained.
+The opt-in is per launch or per soul: `oats spawn --yolo` / `--no-yolo`
+(`oats create` accepts the same flags), an optional `yolo` in `soul.yaml`
+(0.24 schema; the v2 `soul.yaml` schema does not carry it — use the spawn flag
+or a launch configuration), and the Desktop's per-launch choice. With no
+setting, native policy is retained.
+
+*0.24 classic deployments* may also set `yolo: true` in an `oats-config.yaml`
+to apply it to that scope; the closest scope wins, soul overrides scope, the
+spawn flag overrides both. *Under the workspace model* `oats-config.yaml` is
+not configuration ([configuration.md](configuration.md)); the kernel's
+`composeInstance` still consults the classic chain for the machine-level knobs
+`yolo` and `launch-configs` when such a file happens to sit above the
+deployment, but nothing writes one and the rebuild guide tells you to delete
+it — treat a scope-level `yolo` as a 0.24 feature and prefer the explicit
+spawn flag.
+
 Autonomous or unattended execution is not permission to synthesize `yolo: true`.
 Explicit user CLI/UI input or a user-selected configuration is the opt-in; explicit
 `false` remains false.