@awebai/oats 0.25.4 → 0.25.6

package/capabilities/oats-okf/lib/stores.mjs

@@ -3,7 +3,7 @@ import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { fs, join, dirname, safePath, readJSON, save, atomic, tree, materialize, digest, hash, withLock, exec, cleanEnv, fail, relPath, overlaps, resolve } from './io.mjs';
-import { metadata, noGit } from './config.mjs';
+import { metadata, noGit, gitTimeoutMs } from './config.mjs';
 const validator = fileURLToPath(new URL('../skills/okf/scripts/okf-validate.mjs', import.meta.url));
 // Never let local replace refs reinterpret frozen OIDs, including inside Git's
 // transport subprocesses. Override even an explicitly supplied command env.
@@ -17,11 +17,19 @@ export function validateBase(root, base) {
   if(result.errors.length || result.warnings.length) fail('E_VALIDATION', [...result.errors,...result.warnings].join('; '));
   return {files,meta,digest:digest(files)};
 }
-function rawBlob(cwd,oid) {
-  const result=spawnSync('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-C',cwd,'cat-file','blob',oid],{cwd,env:gitEnv(),timeout:30000,maxBuffer:16*1024*1024});
+/** Write a blob straight to a file descriptor: no in-memory buffer, so object
+ *  size never limits what a base may hold. The remote budget applies because a
+ *  partial clone fetches a missing blob on its first read. */
+function writeBlob(cwd,oid,target,mode) {
+  const fd=fs.openSync(target,'wx',mode);
+  let result; try { result=spawnSync('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-C',cwd,'cat-file','blob',oid],{cwd,env:gitEnv(),timeout:gitTimeoutMs(),stdio:['ignore',fd,'pipe']}); } finally { fs.closeSync(fd); }
   if(result.error || result.status!==0) fail('E_COMMAND','Git object read failed');
-  return result.stdout;
+  fs.chmodSync(target,mode);
 }
+/** A tree entry the store never materializes: outside the knowledge base root.
+ *  Its absence from a staging tree is by construction; its presence is a
+ *  worker's doing and is judged like any other change. */
+const outsideBase=(base,p)=>!(base.root==='.' || p===base.root || p.startsWith(base.root+'/'));
 function materializeGitObjects(base,dest,head) {
   immutableCommit(dest,head);
   const entries=gitTreeEntries(dest,head);
@@ -35,20 +43,32 @@ function materializeGitObjects(base,dest,head) {
   // Index/HEAD updates do not apply content filters. They preserve the normal
   // Git worktree needed by existing diff/publication guards without checkout.
   git(dest,['read-tree',head]);git(dest,['update-ref','--no-deref','HEAD',head]);
+  // Only the knowledge base is materialized: the index carries the whole tree
+  // for publication, but bytes outside the base root are never read, so the
+  // size of the rest of the repository does not matter. The scope checks know
+  // that an entry outside the root is expected to be absent (see outsideBase).
   for(const [p,entry] of entries) {
+    if(outsideBase(base,p)) continue;
     const target=safePath(join(dest,p));fs.mkdirSync(dirname(target),{recursive:true});
-    if(entry.mode==='160000') {fs.mkdirSync(target);continue;}
-    const bytes=rawBlob(dest,entry.oid);
-    if(entry.mode==='120000') fs.symlinkSync(bytes.toString('utf8'),target);
-    else {fs.writeFileSync(target,bytes,{flag:'wx',mode:entry.mode==='100755'?0o755:0o644});fs.chmodSync(target,entry.mode==='100755'?0o755:0o644);}
+    writeBlob(dest,entry.oid,target,entry.mode==='100755'?0o755:0o644);
   }
 }
 function clone(base, dest, selectedHead) {
   safePath(dest);
   if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
   fs.mkdirSync(dirname(dest),{recursive:true});
-  git(dirname(dest),['clone','--no-hardlinks','--no-checkout','--',base.repository,dest]);
-  git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+  // Fetch only what the store reads: the accepted branch, trees now and blobs
+  // on demand. Only a remote that does not offer object filtering gets a plain
+  // single-branch clone instead; any other failure is the failure it is. The
+  // ancestry the publication checks walk is present either way.
+  const cloneArgs=['clone','--no-hardlinks','--no-checkout','--single-branch','--branch',base.acceptedBranch];
+  try { git(dirname(dest),[...cloneArgs,'--filter=blob:none','--',base.repository,dest],{timeout:gitTimeoutMs()}); }
+  catch(e) {
+    if(e.code!=='E_COMMAND' || !/filter/i.test(e.message)) throw e;
+    fs.rmSync(dest,{recursive:true,force:true});
+    git(dirname(dest),[...cloneArgs,'--',base.repository,dest],{timeout:gitTimeoutMs()});
+  }
+  git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
   const head=selectedHead ?? git(dest,['rev-parse','FETCH_HEAD']);
   verifyRemote(base,dest);
   materializeGitObjects(base,dest,head);
@@ -142,7 +162,9 @@ function withVerificationIndex(cwd,fn) {
 }
 export function verifyGitScope(base, dest, baseline, { checkModes = true } = {}) {
   return withVerificationIndex(dest,read=>{
-    const names=read(['diff','--name-only','-z',baseline,'--']).split('\0').filter(Boolean);
+    // Entries outside the root are never materialized, so their absence is
+    // not a deletion; a present outside file that differs still is a change.
+    const names=read(['diff','--name-only','-z',baseline,'--']).split('\0').filter(Boolean).filter(p=>!(outsideBase(base,p) && !fs.existsSync(join(dest,p))));
     // A restored working file can conceal a staged, unauthorized index entry.
     names.push(...read(['diff','--cached','--name-only','-z',baseline,'--']).split('\0').filter(Boolean));
     names.push(...read(['ls-files','--others','--exclude-standard','-z']).split('\0').filter(Boolean));
@@ -303,7 +325,7 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
   const baseline=immutableCommit(cwd,stage.head);
   verifyPublicationTree(base,cwd,baseline.tree,baseline.tree,proposal.before);
   // Baseline must still be accepted. Never rebase model output without rejudging it.
-  git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+  git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
   const accepted=git(cwd,['rev-parse','FETCH_HEAD']);
   if(accepted!==stage.head) {
     // A known or uncertain previously created PR may be reconciled, but a
@@ -350,13 +372,13 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
   const publication=immutableCommit(cwd,receipt.commit);
   if(publication.parents.length!==1 || publication.parents[0]!==stage.head) fail('E_CONFIRM','publication commit must have exactly the frozen baseline as its parent');
   verifyPublicationTree(base,cwd,baseline.tree,publication.tree,proposal.after,proposal.before);
-  const remoteTip=()=>git(cwd,['ls-remote','--heads','origin',`refs/heads/${branch}`]).split(/\s/)[0] || null;
+  const remoteTip=()=>git(cwd,['ls-remote','--heads','origin',`refs/heads/${branch}`],{timeout:gitTimeoutMs()}).split(/\s/)[0] || null;
   let tip=remoteTip();
   if(tip && tip!==receipt.commit) fail('E_PR','publication branch has unexpected commit; never force push');
   if(tip!==receipt.commit) {
     beforePublish();
     receipt.status='push-intent'; persist();
-    try { verifyRemote(base,cwd);git(cwd,['push','--no-follow-tags','--recurse-submodules=no','origin',`${receipt.commit}:refs/heads/${branch}`]); }
+    try { verifyRemote(base,cwd);git(cwd,['push','--no-follow-tags','--recurse-submodules=no','origin',`${receipt.commit}:refs/heads/${branch}`],{timeout:gitTimeoutMs()}); }
     catch(e) { receipt.status='push-unknown'; receipt.error=e.message; persist(); throw e; }
     tip=remoteTip(); if(tip!==receipt.commit) {receipt.status='push-unknown';persist();fail('E_CONFIRM','pushed head not confirmed');}
   }
@@ -375,7 +397,7 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
   const pr=matching[0];receipt.pr=pr;receipt.status='delivered';receipt.deliveredAt ||= new Date().toISOString();persist();
   if(pr.state==='CLOSED' && !pr.mergedAt) {receipt.status='rejected';persist();fail('E_PR','PR closed without merge; retained proposal requires operator review');}
   if(pr.mergedAt) {
-    git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+    git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
     const merge=pr.mergeCommit?.oid;
     if(!merge) fail('E_CONFIRM','merged PR lacks merge commit');
     git(cwd,['merge-base','--is-ancestor',merge,'FETCH_HEAD']);

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "compatibility": {
     "oats": ">=0.24.4"
   },
@@ -26,6 +26,9 @@
     },
     "state-dir": {
       "description": "Absolute host-owned durable state directory for portable bindings. It is never derived from an instance home."
+    },
+    "git-timeout": {
+      "description": "Seconds allowed for each Git operation that talks to a remote (clone, fetch, push, ls-remote); default 600. Local object reads keep a short fixed limit. Raise it for large repositories behind slow links."
     }
   },
   "agents": [

package/capabilities/oats-okf/skills/okf/SKILL.md

@@ -121,8 +121,9 @@ captured ProviderBinding as execution authority:
   `payload.bindings`. Workspace, adoption, and operator values remain separate
   inputs to the shared resolver; OKF does not select their precedence.
 - Durable placement is explicit selected settings: physical absolute
-  `bindings-file` and `state-dir`, plus selected `harvest-runtime` and optional
-  `harvest-model`. Never derive state from an instance home.
+  `bindings-file` and `state-dir`, plus selected `harvest-runtime`, optional
+  `harvest-model` and optional `git-timeout` (seconds for remote Git
+  operations, default 600). Never derive state from an instance home.
 - Provider codecs run only after exact retained executable approval. Their
   populated binding is not proof of readiness, enrollment, credentials, privacy
   or publication authority. Respect typed non-ready results.

package/docs/capabilities.md

@@ -262,6 +262,17 @@ return `meta`, `brief`, `warning`, or runtime-specific `launch` arguments. A
 **spawn hook only** may also return an `env` object for the launched process;
 returning `env` from retire or soul-scaffold is an explicit contract error.
 
+A **launch hook** runs at every start and restart of a home for each provider
+captured at spawn (under its captured settings). Its `launch` arguments and
+`env` replace that provider's previous contribution whole. Its `meta`, when
+returned, replaces that provider's entry in `instance.json.capabilityMeta`
+after the start succeeds — the same record the spawn hook wrote and the retire
+hook later reads as `OATS_META` — so a provider that re-issues a credential at
+start (a renewed session grant, for example) leaves the CURRENT one on record. A
+launch hook that answers without `meta` keeps its previous entry; a start whose
+preparation fails changes nothing. (Kernel ≥ 0.25.5; earlier kernels collected
+launch `meta` and discarded it.)
+
 Hook environment values are strings, at most 8192 UTF-8 bytes, with no NUL or
 newlines. Names use the portable environment grammar and must belong to an
 unambiguous vendor namespace. Only a dotted capability ID participates: its
@@ -271,6 +282,14 @@ for this contract. Hyphenated vendors are also excluded because translating a
 hyphen to `_` would let `aweb-evil.*` collide with names already inside
 `aweb.*`'s `AWEB_*` namespace.
 
+A manifest's `settings.<key>` may carry `hostOnly: true` (decision 27). Such a
+key is a fact about the machine — a custody directory, a state root — and the
+resolver accepts it only from the deployment's own `oats-local.yaml`
+`settings.<capability>`; a committed workspace or soul file or a `--provider`
+flag carrying it is refused (`E_WORKSPACE_SCHEMA`, reason `host-only-key`).
+Declare it for any key whose value points at something a committed file must
+never be able to choose.
+
 A hook may return only names in its manifest's exact `environment` declaration.
 For package capabilities that declaration is part of the integrity-locked tree
 and of what the per-version approval showed; for member capabilities it is

package/docs/capability-manifest.schema.json

@@ -263,6 +263,10 @@
           },
           "description": {
             "type": "string"
+          },
+          "hostOnly": {
+            "type": "boolean",
+            "description": "When true, this key is a host fact (a custody path, a state directory): the resolver accepts it only from the deployment's oats-local.yaml settings.<capability> and refuses it in the workspace file, byTeam payloads, a soul's slot payload and --provider flags (E_WORKSPACE_SCHEMA reason host-only-key). Decision 27."
           }
         },
         "additionalProperties": false

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 20:00Z · **0.25.0–0.25.3 PUBLISHED** (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID) · **OKF 2.1.4 pending human GO** (owner pin by id, clone/timeout, retire-schedule seam; Antares writes the PRs) · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
+**Last update:** 2026-09-23 20:00Z · **0.25.0–0.25.5 PUBLISHED** (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID; quarantine-retry fix; launch meta + catalog pins) · **OKF v2.1.4 + oats.aweb v1.12.0 TAGGED and pinned** · **decision 27 accepted; K1′/K1″/K2 kernel PR next** · **oats.aweb 1.13.0 (#110) queued** · **Desktop 10B-0 resumed** · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

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

@@ -565,6 +565,33 @@ is a member; a soul that lives in it may need a work clone). Under an explicit
 `oats-local.yaml` `standalone:` header the next steps say the view is standalone
 and list only that repo.
 
+### 0.25.6 — decision 27: served identity is a messaging-layer fact (K1′, K1″, K2)
+
+- **K1′** `decision.effective.providers` = the resolution's merged per-module payloads
+  (exactly what reaches `OATS_SETTINGS`), bound by the decision revision. No new flag.
+- **K1″** manifest `settings.<key>.hostOnly: true` → the resolver refuses that key in
+  the workspace base, `byTeam[*]`, the soul's slot and `--provider` layers with
+  `E_WORKSPACE_SCHEMA { reason: "host-only-key", path, key, capability }`; only
+  `oats-local.yaml settings.<cap>` may carry it. Generalises decision 23's reserved
+  `byTeam` into a capability-declared attribute. Schema: `docs/capability-manifest.schema.json`.
+- **K2** `oats status --json instances[].identity` and `oats inspect … selected.identity`
+  copy `capabilityMeta[<cap>].identity` (messaging-layer capability preferred; `provider`
+  added); text `identity: acts as <address> via grant, expires <t>` / `alias <a> on <team>`.
+  Layer contract shape in `docs/integrations.md`.
+- `features[]` gains `served-identity`.
+
+### 0.25.5 — launch-hook `meta` is persisted
+
+`runLifecycleHooks("launch")` collected each capability's `meta` and the
+start/restart path discarded it (only `contributions` and `env` were consumed).
+From 0.25.5 a successful start merges `res.meta` per capability into
+`instance.json.capabilityMeta` — the record spawn writes and retire reads as
+`OATS_META`. A hook answering without `meta` keeps its prior entry; a failed
+launch preparation writes nothing. No new field, flag or hook event; this is
+the documented hook return finally honoured (decision 27, K3′). Driver: a
+provider renewing a session grant at every start would otherwise leave the
+original grant id on record and retire would revoke the wrong grant.
+
 ### 0.25.3 — `OATS_SOUL_ID` (stable soul identity for providers)
 
 The per-commit soul cache (0.25.1, M1) made `realpath(<home>/soul)` change with every

package/docs/design/2026-09-24-desktop-phase-f-boundary.md

@@ -0,0 +1,180 @@
+# Desktop Phase F — the Desktop is built FOR workspace model v2
+
+**Status**: boundary for the Desktop engineer, issued 2026-09-24 by the lead under
+the human's direction: *"the desktop should not just adapt to the new version,
+it should be natively built for it."* Supersedes the Phase 3 parity plan's
+assumptions about what the Desktop reads; keeps its visual deliverable (the
+redesign frames, excl. 05/06).
+
+**Human's second directive, verbatim intent**: make ultra sure the Desktop is set
+up to work in the new setup — new versions, new CLI, new deployment shape.
+
+## 0. Why this is a rebuild of the model, not a patch
+
+The Desktop today is a 0.24 product that *tolerates* 0.25 kernels: its
+`ACCEPT_RANGE` admits `0.25.x`, so it launches, and the few CLI verbs it drives
+(`version`, `session *`, `spawn`, `retire`, `schedule`, `catalog`) still answer.
+But its **model of a deployment is 0.24's**, reimplemented in
+`packages/desktop/server/deployment.mjs`: it reads `oats-config.yaml`,
+`agents/<name>/soul`, `local-agents/`, and capability manifests from
+`.agents/capabilities/installed/`, and derives the roster itself. None of these
+is how a v2 deployment is shaped:
+
+| 0.24 (what the Desktop reads) | v2 (what a deployment IS) |
+|---|---|
+| `oats-config.yaml` at the repo root | `oats-local.yaml` at the deployment directory → `workspace:` URL |
+| souls at `agents/<name>/soul` | souls at `souls/<name>` **in member repos**, materialised per commit into `agents/<name>/souls/<commit>` |
+| capabilities installed into `.agents/capabilities/installed/` | packages resolved through `oats-workspace.yaml` + the official catalog, locked in `oats-lock.json`, **copied whole into each instance home** (`.oats/modules/<cap>`) |
+| `team:` block | `oats-membership.yaml` `team:` label per member; `messaging.byTeam.<label>` payloads |
+| `oats catalog` DTO | removed; the catalog is `package-catalog.json` resolved by `oats sync` |
+| roster derived by the Desktop | `oats status --json` is the roster (agents, instances, `modules[]` drift, `soul` source drift, `identity`) |
+
+A Desktop that keeps the left column and adds a few right-column fields is the
+"adapt" outcome the human rejected. Phase F replaces the left column.
+
+## 1. The principle: the kernel is the model; the Desktop renders and drives it
+
+- **Read model**: every fact the Desktop shows about a deployment comes from
+  the kernel's JSON surfaces — `oats status --json`, `oats inspect --json`,
+  `oats workspace status --json`, `oats spawn --preview --json`, `oats
+  readiness --json`, `oats version --json`, `oats sync --json`. The Desktop
+  does not parse `oats-config.yaml`, `oats-local.yaml`, `soul.yaml`,
+  manifests or lock files itself. Where a fact is missing from a kernel
+  surface, the fix is a kernel PR (lead's lane), not a Desktop-side parser.
+- **Write model**: every mutation is a kernel verb with `--json`: `sync`,
+  `sync --approve`, `spawn` (preview → `--expect-decision` apply), `retire`,
+  `session start|restart|recompose`, `schedule *`, `onboard`. The Desktop
+  never writes a deployment file.
+- **Version contract**: `oats version --json` `features[]` is the capability
+  probe. The Desktop's `ACCEPT_RANGE` moves to `>=0.25.6 <0.27.0` (the first
+  kernel with `served-identity`), and each feature the UI depends on is gated
+  on its `features[]` name, not on a version number.
+
+## 2. Deliverables (slices; each is one PR against main, each reviewed by the lead)
+
+**F1 — Deployment model on kernel JSON.** Replace
+`server/deployment.mjs`'s own readers with `oats status --json` (+ `oats
+workspace status --json` for the workspace header: name, key, members, packages,
+lock state, `approvalNeeded`). Roster rows carry `modules[]` drift, `soul`
+source (`repo: <member> @ <c7>`, "member moved since"), `identity`. Legacy
+`local-agents/`/`tmp-agents/` paths are dropped. Remove `server/catalog.mjs`'s
+`oats catalog` DTO validation (the verb no longer exists).
+
+**F2 — Workspace onboarding and sync.** A "Open deployment" flow that: detects a
+directory with `oats-local.yaml` (v2), or offers `oats onboard` for one without
+(the kernel asks for the deployment directory and the workspace URL — the
+Desktop collects both, never invents a folder name; decision 9). A "Sync"
+action runs `oats sync --json`; exit 2 with `approvalNeeded[]` renders an
+approval sheet showing each package's `executables` digest and applies with
+`oats sync --approve <id>@<version>` (the version string is what
+`approvalNeeded[].version` reports — for a git-pinned package, the full OID).
+Lock drift and `E_PACKAGE_INTEGRITY` are surfaced verbatim.
+
+**F3 — Spawn dialog on the v2 preview.** The preview already carries
+`modules`, `providers`, `settings.<cap>`, `team`, `resolution`, `decision`.
+Render: which modules the instance will get and from where (package vs member,
+commit); the merged `settings.<cap>` per provider (read-only); **Identity**
+select (local | global) with a Resident field for global, prefilled from
+`settings.<messaging cap>.identity`, forwarded as `--provider <cap>
+identity.mode=… identity.resident=…` (decision 27 — there is no kernel flag);
+`decision.effective.providers` is what the confirm binds. `cli-adapter.mjs`
+`SPAWN_ARG_RULES` gains one `provider` rule (capability id, dotted key, value
+grammar); no identity-named rules. Work mode select includes `workspace`.
+
+**F4 — Instance card and roster on v2 facts.** The served-identity line (`acts
+as <address> via grant, expires <t>` / `alias <a> on <team>`); module rows with
+"moved since" markers and a **re-spawn** action (preview → apply, then retire
+the old instance — module homes answer `E_UNSUPPORTED_MODE` to
+`session recompose` by design; an instance never changes under itself); the
+soul-source row; quarantine state from `rollbackIncomplete` with the retry
+action (`oats retire`) and `--force` behind a confirm.
+
+**F5 — Redesign frames** (the original Phase 3 deliverable, excl. 05/06),
+implemented on top of F1–F4 rather than on the 0.24 model.
+
+**F6 — Version and doctor surface.** `oats version --json` and `oats doctor
+--json` in an About/Health pane; `ACCEPT_RANGE` and the three pins move to
+`>=0.25.6`; a kernel below the floor is refused with the upgrade command shown.
+
+Order: F1 → F2 → F3 → F4 → F5 → F6, or F1 then F3/F4 in parallel if the engineer
+spawns children (its call; the lead reviews each PR).
+
+## 3. What the engineer must LEARN first (before F1)
+
+Read, in this order, in the checked-out main:
+1. `docs/workspaces.md` — the v2 model end to end (deployment vs workspace,
+   members, packages, payloads, `byTeam`, hosting).
+2. `docs/rebuild-to-v2.md` — how an operator builds a deployment (this is the
+   flow F2 wraps).
+3. `docs/desktop-cli-api.md` — every JSON surface, with examples; note
+   `features[]`, `decision.effective.providers`, `instances[].identity`.
+4. `docs/design/2026-09-23-workspace-module-contracts.md` §0.25.x — what
+   changed per release and why.
+5. `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md` and
+   `…/served-identity-is-a-messaging-layer-fact.md` — the decisions.
+6. `test/fixtures/northwind/build.mjs` — the two-team fixture workspace; run
+   `node --test test/spawn-workspace.test.mjs` once and read what a v2 spawn
+   produces on disk (`.oats/modules/`, `instance.json` `modules`/`providers`/
+   `workspace.soul.id`).
+
+Then build a scratch deployment by hand with the CLI (`oats onboard`, `oats
+sync`, `oats sync --approve`, `oats spawn --preview`, `oats spawn --no-launch`,
+`oats status`, `oats inspect`, `oats retire`) against the Northwind fixture
+remotes, and keep the transcript: F1's tests are written against exactly those
+JSON shapes.
+
+## 3b. Native rework, not a compatibility layer (human, 2026-09-24)
+
+The human's rule, verbatim intent: *"do a native rework — do not keep v1-specific
+things, and no v1 modules calling v2 modules."* Concretely:
+
+- **Remove, do not wrap.** A 0.24 reader (`server/deployment.mjs`'s
+  `oats-config.yaml`/`soul.yaml`/manifest parsing, `local-agents/`,
+  `.agents/capabilities/installed/`, the `oats catalog` DTO) is deleted in the
+  slice that replaces it — never kept behind a flag, a fallback branch, or an
+  "if the kernel is old" path. The Desktop supports one kernel line
+  (`ACCEPT_RANGE` from 0.25.6) and refuses older ones with the upgrade command.
+- **No adapters between generations.** No module whose job is to translate a
+  v1-shaped object into a v2-shaped one or vice versa (no `legacyRosterToV2()`,
+  no `toOldCard()`); the v2 kernel JSON is consumed where it is read and shaped
+  once for rendering. If a v1 module still needs a v2 fact, the v1 module is
+  the thing being replaced — replace it, do not feed it.
+- **Names and types follow v2.** Types, fields and UI labels use the kernel's
+  vocabulary (workspace, member, package, module, deployment, soul source,
+  served identity); 0.24 vocabulary (installed capability, config chain, team
+  block, agents root as identity) leaves the codebase with the code that used
+  it. `git grep` for the old terms is part of each slice's exit check.
+- **Tests follow the same rule.** Fixtures shaped like 0.24 deployments are
+  deleted with the readers; new fixtures are v2 deployments produced by the
+  kernel (Northwind or a hand-built scratch deployment), not hand-written
+  JSON imitating old shapes.
+- **One exception, stated per case.** Where a 0.24 concept has a genuine v2
+  successor with the same meaning and the Desktop code is already correct for
+  it (a terminal broker, a tmux target admission), it stays — the PR names it
+  as "unchanged, v2-agnostic", not as "kept for compatibility".
+
+Exit check for Phase F as a whole: no file under `packages/desktop/` reads a
+deployment file, names a 0.24 concept, or contains a code path that exists
+only for a kernel below the floor.
+
+## 4. Rules that do not change
+
+- `packages/desktop/**` only; kernel gaps go to the lead as a written ask
+  (they become kernel PRs; the engineer never adds a Desktop-side parser to
+  work around one).
+- No native tmux/PTY/Electron execution by the agent; the lead's native gate
+  at review time is the acceptance.
+- Every slice: focused tests + the intended mutants on the new code; the
+  Desktop suite green; one PR per slice against main; lead's pr-review.
+- The design frames are the visual authority; the kernel JSON is the data
+  authority; where a frame shows a 0.24 concept (an "installed capability"
+  list, a `team:` block), the frame is adapted to the v2 concept and the
+  adaptation noted in the PR.
+
+## 5. Acceptance for Phase F as a whole
+
+The lead builds a fresh v2 deployment from the Northwind fixture using ONLY the
+Desktop (open → onboard → sync → approve → spawn with a global identity →
+inspect → retire) on kernel 0.25.6+, and every fact shown matches `oats status
+--json` / `oats inspect --json` byte for byte. Nothing in
+`packages/desktop/server` reads a deployment file.

package/docs/design/2026-09-24-phase-d-plan.md

@@ -0,0 +1,129 @@
+# Phase D — the OATS project runs on the architecture it offers (plan)
+
+**Status**: plan, 2026-09-24, lead. Decisions 18–22 of the workspace model, the
+five-soul roster and its 2026-09-24 amendment, the human's sequencing
+("knowledge centralisation first"; "do not retire live souls until their
+instances retire"). Mailed to the human and the OSS coordinator before the
+first swarm. Method per standing instruction: write → swarm build →
+adversarial-review swarm → PR → main; releases under delegated authority.
+
+## Slices, in order
+
+### D1 — Knowledge centralisation (IN PROGRESS)
+
+Goal: every roster soul's knowledge lives in the central base
+`awebai/oats-knowledge` (OKF 2.1.4), one owned node each; the in-repo
+`agents/*/soul/knowledge` bundles stop receiving writes and are decommissioned
+when no live instance links them.
+
+Done: nodes `oats-operator-expert` and `integrations-expert` chartered
+(oats-knowledge PR #3); eight attributed seeds landed in
+`agents/oats-expert/soul/knowledge/inbox` (oats PR #121); the roster amendment
+accepted; the rule "no per-soul knowledge merges" in force.
+
+Work:
+1. **Copy-migrate by judgement** (the 2026-09-21 method: two-part test plus the
+   2026-09-24 recipe refinement; not copying): `agents/oats-expert/soul/knowledge`
+   (~130 files) → node `oats-expert`; `agents/oats-desktop-engineer/soul/knowledge`
+   (~120) → `oats-desktop-expert`; `agents/cli-dev/soul/knowledge` (~155) →
+   `oats-kernel-expert`; `agents/integrations-expert/soul/knowledge` (13) →
+   `integrations-expert`. Others (`dev-coordinator`, `docs-expert`, `ux-designer`,
+   `lead`, `oats-coordinator`) are assessed for the few universal concepts they
+   hold and otherwise not carried. One PR per node on oats-knowledge, reviewed
+   by the lead; the OSS coordinator reviews the operator and integrations PRs.
+2. **Seed the operator node** — attributed to `oats-expert-antares`:
+   MOVE (not copy) from the oats-expert bundle: `lessons/the-aweb-team-root-must-sit-where-the-spawn-hook-looks`,
+   `lessons/okf-state-directory-must-sit-outside-every-work-tree`,
+   `lessons/capability-trust-hash-covers-the-installation-record`,
+   `lessons/a-locally-minted-oats-identity-has-no-cross-team-first-contact-address`,
+   `lessons/stale-checkout-serves-stale-soul`,
+   `playbooks/rebuild-a-deployment-in-scratch-against-local-bare-remotes`;
+   generalise the R1–R10 rebuild findings and the published-combination
+   verifications from `stewardship/delivery-log` (the log keeps the record).
+   From the inbox: `check-the-record-before-redesigning-identity`,
+   `grant-custody-service-and-renewal-belong-on-the-custody-host` (operator
+   half), `the-wake-broker-accepts-a-grant-home`.
+3. **Seed the integrations node** — from the inbox:
+   `a-merged-provider-payload-cannot-enforce-host-only-keys`,
+   `aw-grant-commands-resolve-the-identity-from-cwd-only` (discipline half),
+   `oats-runtime-requirements-for-grant-backed-resident-operation`; from the
+   integrations-expert bundle: `fake-aw-must-model-real-refusals` and the rest
+   of this week's harvested lessons.
+4. **Route the remainder of the inbox**: aweb package expert (D3) gets
+   `aweb-grants-are-team-bound-to-the-custody-identitys-active-team`,
+   `a-grant-signed-send-must-name-the-subject-as-sender` and the aw halves;
+   kernel expert gets `path-keyed-owner-registry-breaks-under-per-commit-soul-copies`.
+5. **Rebind the souls** in `souls/<name>/`: the `knowledge:` grammar there is
+   still 0.24's (`capability` + `source: git:…@v2.1.2#oats-package`); v2 is
+   `capabilities: { oats.okf: { from: package } }` plus `okf.json`
+   (`{ version: 1, owner: <node owner uuid>, owns: ["oats/<node>"], reads: [...] }`)
+   and the store `oats` naming `awebai/oats-knowledge` / `knowledge` / `main`.
+   Add `souls/oats-operator-expert` (rename of `oats-setup-expert`, keeps the
+   `oats.setup` charter) and `souls/integrations-expert`.
+6. **Do NOT delete** `agents/<n>/soul/knowledge` or the legacy souls while a
+   live instance links them (human rule). Record which are live; decommission
+   as they retire; new spawns use `souls/<n>`.
+7. **Release playbook** (`oats-expert` node, stewardship area): landing order
+   for provider PRs (tag → pin on the branch → squash; a bundled provider never
+   lands ahead of its tag), the version literals to bump on a catalog bump,
+   the mirror checker, the bump-PR step. First entries: today's two lessons.
+
+### D2 — The OATS workspace as a v2 workspace (decisions 18, 19, 21)
+
+`oats-workspace.yaml` at the `oats` repo (name `oats`; members = the seven
+framework repos incl. `oats` itself; `packages:` = oats.framework / okf / aweb /
+jira / linear / authoring / dev pinned from the catalog; `defaults.capabilities`
+= `oats.core` from package + knowledge `oats.okf`); `oats-membership.yaml` ×7
+(each package repo is a member AND a package publisher — non-collapse:
+`packages:` resolves it as a package, membership only grants trust and a soul).
+`package-catalog.json` stays the official marketplace (decision 21); the `oats`
+repo keeps `oats-dev` as dev capabilities. A fresh deployment directory (asked
+for, never named by convention — decision 9) is the acceptance: `oats onboard`
+→ `sync` → `approve` → spawn every roster soul `--no-launch`.
+
+### D3 — Souls to `souls/<name>` and the six package-expert souls (decision 20)
+
+Each package repo carries `souls/<pkg>-expert` (okf-expert, aweb-expert,
+jira-expert, linear-expert, authoring-expert, dev-expert), the expert in that
+package, with a node in the central base from day one. **Seams named in the
+charters** (roster amendment): `aweb-expert` READS
+`aweb-protocol-expert` in base `aweb-oss-knowledge` (repo
+`github.com/awebai/aweb`, root `knowledge/`, branch `main`, OKF 2.1.x
+descriptor at `knowledge/okf-base.json`; owner `1913b77b-…`) through a
+read-only store reference; `okf-expert` names its seam to the knowledge-theory
+material in `oats-expert`. Whether the aweb bookshelf decisions the program
+rests on are published into that node is the aweb side's call (asked).
+
+### D4 — `oats.core` and `oats.setup` rewritten (decision 22, W9b)
+
+Not patched: written for the v2 world. `oats.core`: home layout, `oats status`
+with modules/soul/identity rows, spawn preview → apply, `sync --approve`, the
+two-directory boundary, what a module is. `oats.setup` (held by
+`oats-operator-expert`): onboarding that ASKS for the deployment directory and
+the workspace URL, the hosting rule (decision 26), the public-member executable
+rule, the rebuild guide as procedure with the operator node as rationale.
+Developer souls in `oats.dev` gain `promotesTo: <node>` (roster amendment);
+the harvester delivers to that node as a PR the owning expert reviews.
+
+### D5 — Catalog update and 0.26.0
+
+Catalog pins for the new package versions; **widen Desktop `ACCEPT_RANGE` and
+the three pins FIRST** (minor bump rule); release notes; tag; the fresh
+deployment from D2 rebuilt on the published artefacts by the OSS coordinator
+(outsider verification) before the program board marks Phase D done.
+
+## Adversarial review (per slice)
+
+Each slice's swarm is followed by a review swarm with the standing lenses
+(direction against the decisions; correctness by reproduction; security —
+trust at acquisition, hoisted paths, hook approval, host-only keys; docs as
+contract — every guide claim has a test), plus two Phase-D-specific ones: **the
+outsider** (can a reader who was not in the room set OATS up from `oats.setup`
+alone?) and **the seam** (does every cross-project read resolve to a real node
+with a real owner?).
+
+## Out of scope
+
+Desktop (Phase F, its own boundary); oats.aweb 1.13.0 re-land (held on the
+aweb release); legacy `~/OATS` deployment cutover (the operator's, on the
+published 0.26.0).

package/docs/desktop-cli-api.md

@@ -376,12 +376,32 @@ the pre-fix marker and is never accepted for dispatch.
   import; `--instructions-file`/`--def-file` refused with `E_BAD_ARGS`). Test:
   the deployment tree is byte-identical after a success, a refusal and an
   unknown-soul preview.
+  **Workspace deployments (0.25.1+) — one stated exception**: the first preview
+  of a workspace soul may populate the deployment's per-commit soul cache
+  (`agents/<soul>/souls/<commit>/`, the swappable `agents/<soul>/soul` pointer,
+  `soulFetched: true` in the result). That cache is derived, content-addressed
+  and idempotent — the same member commit yields the same bytes, a later
+  preview of the same commit writes nothing — and nothing else moves: no lock,
+  no event, no home, no instance. A Desktop treats a preview as
+  side-effect-free for everything it shows; it must not assume the deployment
+  directory's byte-identity across the FIRST preview of a soul or commit.
 - **Exact root**: `spawn <soul> --agents-root <abs>` binds the soul to that root
   (as inspect/readiness take it) — no team-soul / capability-agent / importable-
   def fallback; mismatch → `E_SOUL_UNKNOWN`. The preview echoes
   `subject {soul, agentsRoot|null, dir|null}` **as given, byte-exact**.
 - **Decision binding**: `decision {instance, home, branch, base{ref,oid},
-  revision}` (24-hex). Apply with `spawn … --expect-decision <revision>`: the
+  effective{…, providers}, resolution, revision}` (24-hex). From 0.25.6
+  (`features: served-identity`) `effective.providers` is the merged
+  per-module payload each provider will receive (`{ "<cap>": {…} }`, exactly
+  `settings.<cap>` of the preview) — so a confirmed apply binds every
+  provider fact (an identity choice, a delivery mode) **by value**; a Desktop
+  that changes a provider field re-previews. `instances[].identity` (status)
+  and `selected.identity` (inspect) carry the served principal a messaging
+  provider reported: `{ mode: "local"|"global", alias, team, address|null,
+  resident|null, grant?: { id, expiresAt, scopes }, provider }`; absent when
+  no provider emitted one. A Desktop offers the identity choice as
+  `--provider <cap> identity.mode=… identity.resident=…` — there is no
+  kernel flag for it. Apply with `spawn … --expect-decision <revision>`: the
   kernel recomputes name/home/branch/base under the same placement path and
   refuses **`E_DECISION_STALE`** with `details.decision` (the fresh one) on ANY
   drift — no auto-suffix, no silent re-base, nothing created. A GUI re-previews
@@ -774,9 +794,12 @@ written. Captured selectors are refused (`E_BAD_ARGS`).
 
 - `sync` is the `syncApi: 1` report of the first sync (members, packages,
   changes, `approvalNeeded`, `problems`); `lock` is the lock it wrote.
-- **Exit `2` with `ok: true`** when `sync.approvalNeeded` is non-empty (approval
-  is interactive-only; tell the operator to run `oats sync --dir <dir>` in a
-  terminal). Exit `0` otherwise.
+- **Exit `2` with `ok: true`** when `sync.approvalNeeded` is non-empty. Approve
+  non-interactively with `oats sync --dir <dir> --approve <id>@<version> …`
+  (0.25.2+; `<version>` is `approvalNeeded[].version` verbatim — a catalog
+  version, or the full commit OID for a git-pinned package); a Desktop renders
+  `approvalNeeded[].executables` (the digest of the executable set it is
+  approving) and `targets`, then runs that command. Exit `0` otherwise.
 - `hosting` states decision 26 (the kernel cannot see forge visibility, so it
   reports `hostIsMember` and the rule rather than judging).
 - `next.clone[]` is one row per **confirmed** member (`url` = what the
@@ -801,9 +824,10 @@ written. Captured selectors are refused (`E_BAD_ARGS`).
 
 Discovers, confirms membership, resolves `packages:` to commits, writes
 `oats-lock.json` (lockfileVersion 3), reports. **Exit `2` with `ok: true`** when
-the lock was written but approvals are pending (`approvalNeeded` non-empty);
-approval is interactive-only, so a Desktop must tell the operator to run
-`oats sync` in a terminal. Exit `0` otherwise.
+the lock was written but approvals are pending (`approvalNeeded` non-empty).
+Approve with repeatable `--approve <id>@<version>` (0.25.2+, non-interactive;
+`<version>` = `approvalNeeded[].version` verbatim); the interactive prompt is
+the TTY fallback, not the contract. Exit `0` otherwise.
 
 ```json
 {"syncApi":1,
@@ -1052,6 +1076,10 @@ refreshes the home in place:
   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).
+  **Desktop contract (Phase F, F4)**: for a module home, show the drift rows
+  and offer *re-spawn* (preview → apply of the same soul/purpose, then retire
+  the old instance); do not offer "recompose". A kernel recompose for module
+  homes is not planned — an instance never changes under itself.
   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