@awebai/oats 0.25.1 → 0.25.2

package/bin/oats.mjs

@@ -1948,15 +1948,39 @@ async function lockedExecutablesDigest(id, entry, workspace, catalog, remoteOpti
   return { digest, targets };
 }
 
-/** One yes/no question on the terminal (TTY only; the caller checks). */
+/** One yes/no question on the terminal (TTY only; the caller checks). Ctrl+D / a closed
+ *  stdin at the prompt is "no" (readline rejects the question with AbortError, or simply
+ *  closes without an answer — neither is a crash; both are the operator declining). */
 async function askYesNo(question) {
   const rl = createInterface({ input: process.stdin, output: process.stderr });
   try {
-    const answer = (await rl.question(question)).trim().toLowerCase();
-    return answer === "y" || answer === "yes";
+    const closed = new Promise((resolveClosed) => rl.once("close", () => resolveClosed(null)));
+    const answer = await Promise.race([rl.question(question).catch((e) => { if (e?.code === "ABORT_ERR" || e?.name === "AbortError") return null; throw e; }), closed]);
+    if (answer === null) { process.stderr.write("\n"); return false; }
+    const a = String(answer).trim().toLowerCase();
+    return a === "y" || a === "yes";
   } finally { rl.close(); }
 }
 
+/** `--approve <id>@<version>` (repeatable) → Map<id, version>. Exactly one "@" splits the two;
+ *  the digest is never taken from the operator — it is computed over the locked tree. */
+function approveFlags(bail) {
+  const out = new Map();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== "--approve") continue;
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith("--")) return bail("E_BAD_ARGS", "--approve needs <id>@<version> (the package id and the version exactly as `packages:` / the lock spell them)");
+    const at = v.indexOf("@");
+    const id = at > 0 ? v.slice(0, at) : "";
+    const version = at > 0 ? v.slice(at + 1) : "";
+    if (!id || !version || version.includes("@")) return bail("E_BAD_ARGS", `--approve ${JSON.stringify(v)}: expected <id>@<version>`, { value: v });
+    if (out.has(id) && out.get(id) !== version) return bail("E_BAD_ARGS", `--approve names ${id} twice with different versions (${out.get(id)}, ${version})`, { id, versions: [out.get(id), version] });
+    out.set(id, version);
+    i++;
+  }
+  return out;
+}
+
 /** The body of `oats sync` — shared by `sync` and `onboard` (which onboards, then syncs the same
  * way). Given a v2 deployment context: discover over the remotes, confirm membership, resolve
  * `packages:` against the lock, approve (TTY) or list what needs approval, write the lock.
@@ -1983,6 +2007,16 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
   let lock = resolved.lock;
   const approvalNeeded = [];
   const interactive = !JSON_MODE && process.stdin.isTTY && process.stdout.isTTY;
+  // `--approve <id>@<version>`: approve what is THERE — every named pair must be a locked entry
+  // at exactly that version (E_BAD_ARGS otherwise); the digest recorded is the one computed over
+  // the locked tree, never anything the operator typed. Works without a terminal.
+  const approveWanted = approveFlags(bail);
+  for (const [id, version] of approveWanted) {
+    const entry = lock.packages[id];
+    if (!entry) return bail("E_BAD_ARGS", `--approve ${id}@${version}: ${id} is not a package of this ${discovery.standalone === true ? "standalone view" : "workspace"} (locked: ${Object.keys(lock.packages).sort().join(", ") || "none"})`, { id, version, locked: Object.keys(lock.packages).sort() });
+    if (entry.version !== version) return bail("E_BAD_ARGS", `--approve ${id}@${version}: the lock resolves ${id} to version ${entry.version} (@ ${short(entry.commit)}) — approve what is there: --approve ${id}@${entry.version}`, { id, version, locked: entry.version, commit: entry.commit });
+  }
+  const approvedNow = [];
   for (const id of Object.keys(lock.packages)) {
     const entry = lock.packages[id];
     if (entry.approved) continue;
@@ -1992,6 +2026,7 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
       if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
       throw e;
     }
+    if (approveWanted.has(id)) { lock = approvePackage(lock, id, digest); approvedNow.push({ id, version: entry.version, commit: entry.commit, executables: digest, targets }); continue; }
     if (interactive) {
       console.error(`\n${id} ${entry.version} @ ${short(entry.commit)} needs executable approval (${targets.length} executable${targets.length === 1 ? "" : "s"}, digest ${digest}):`);
       for (const t of targets) console.error(`  ${t}`);
@@ -2002,12 +2037,27 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
   }
   let lockFile;
   try { lockFile = writeLock(ctx.deploymentDir, lock); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  // The deployment's instance root: <deployment>/agents/ (findRoot's marker). A hand-written
+  // oats-local.yaml + sync is a complete deployment; spawn must not answer E_NO_DEPLOYMENT after it.
+  try { mkdirSync(join(ctx.deploymentDir, "agents"), { recursive: true }); } catch { /* reported by spawn's E_NO_DEPLOYMENT remedy if it matters */ }
   const members = memberRows(discovery);
   const packages = packageRows(lock);
   const changes = resolved.changes;
   const items = workspaceItems(discovery, lock, { includePrivate: true });
-  const report = { syncApi: 1, standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, approvalNeeded, problems };
-  return { report, lock, discovery, approvalNeeded, interactive, items, lockFile, problems };
+  const report = { syncApi: 1, standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, approvalNeeded, ...(approvedNow.length ? { approved: approvedNow } : {}), problems };
+  return { report, lock, discovery, approvalNeeded, approvedNow, interactive, items, lockFile, problems };
+}
+
+/** The one-line standalone explanation (decision 10). `standaloneReason` says WHY the view is
+ *  standalone: asked for (`standalone:` in oats-local.yaml) or forced (the host is unreadable —
+ *  then the access failure is named). Never "cannot be read" when nothing was refused. */
+function standaloneNote(discovery, { from = "" } = {}) {
+  if (discovery?.standalone !== true) return null;
+  const who = memberLabel(discovery.key);
+  if (discovery.standaloneReason === "explicit") return `standalone view of ${who} (explicit in oats-local.yaml): its own souls + oats.core`;
+  const hf = discovery.hostFailure;
+  const why = hf ? ` (${hf.code ?? "E_REMOTE_UNREADABLE"}${hf.reason ? `: ${hf.reason}` : ""}${hf.url ? ` — ${hf.url}` : ""})` : "";
+  return `standalone — the workspace of ${who} cannot be read${from}${why}; its own souls + oats.core`;
 }
 
 /** The human §8 report of a sync (text mode). */
@@ -2015,7 +2065,7 @@ function printSyncReport(ctx, synced) {
   const { report, discovery, approvalNeeded, interactive, items, lockFile } = synced;
   const { members, packages, changes } = report;
   const disabled = new Set(ctx.local.souls?.disabled || []);
-  console.log(`workspace  ${discovery.workspace?.name ?? `(standalone — the workspace of ${memberLabel(discovery.key)} cannot be read; its own souls + oats.core)`}  (${discovery.key} @ ${short(discovery.commit)})`);
+  console.log(`workspace  ${discovery.workspace?.name ?? `(${standaloneNote(discovery)})`}  (${discovery.key} @ ${short(discovery.commit)})`);
   console.log(`members    ${members.map((m) => m.confirmed ? `${m.name} ✓↔ (@ ${short(m.commit)})` : `${m.name} ✗ (${m.status})`).join("   ") || "(none)"}`);
   console.log(`packages   ${packages.map((p) => {
     const need = approvalNeeded.find((a) => a.id === p.id);
@@ -2034,6 +2084,7 @@ function printSyncReport(ctx, synced) {
   for (const c of items.capabilities.filter((c) => c.kind === "member")) { const t = teams.get(c.team) || { souls: 0, capabilities: 0 }; t.capabilities++; teams.set(c.team, t); }
   console.log(`teams      ${[...teams.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([team, n]) => `${team} ${n.souls} soul${n.souls === 1 ? "" : "s"}${n.capabilities ? `, ${n.capabilities} capabilit${n.capabilities === 1 ? "y" : "ies"}` : ""}`).join(" · ") || "(none)"}`);
   for (const p of synced.problems ?? discovery.problems) console.log(`problem    ${p.code}  ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path}  ${p.message}`);
+  for (const a of synced.approvedNow ?? []) console.log(`approved   ${a.id} ${a.version} @ ${short(a.commit)}  (--approve; ${a.targets.length} executable${a.targets.length === 1 ? "" : "s"}, digest ${a.executables})`);
   if (approvalNeeded.length) {
     console.log(`\nApproval needed for ${approvalNeeded.map((a) => `${a.id} ${a.version}`).join(", ")} — ${interactive ? "declined; " : "not a terminal; "}the lock records them unapproved. Run \`oats sync\` in a terminal to approve their executables (spawns of souls using them are refused until then).`);
   } else console.log(`\nlock       ${shortPath(lockFile)}`);
@@ -2157,7 +2208,7 @@ async function workspaceCmd() {
   const result = { workspaceStatusApi: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, teams: Object.keys(discovery.workspace?.teams || {}) }, members, packages, declaredPackages: declared, unsynced, stale, approval, external: (discovery.external || []).map((e) => ({ source: e.source, soul: e.soul.name, team: teamLabel(e.soul.team) })), problems: discovery.problems };
   if (JSON_MODE) { jsonOk(result); return; }
   console.log(`workspace ${workspaceName(discovery)}  (${discovery.key} @ ${short(discovery.commit)})  local ${shortPath(ctx.localPath)}\n`);
-  if (standalone) console.log(`  (standalone — the workspace of ${memberLabel(discovery.key)} cannot be read; its own souls + oats.core)\n`);
+  if (standalone) console.log(`  (${standaloneNote(discovery)})\n`);
   console.log("Members:");
   printTable(["member", "status", "commit", "team", "souls", "capabilities", "publishes"], members.map((m) => [m.name, m.status, short(m.commit), m.team ?? "—", m.souls.join(",") || "—", m.capabilities.join(",") || "—", m.publishes ? `${m.publishes.package} v${m.publishes.version ?? "?"}` : "—"]));
   for (const m of members.filter((m) => !m.confirmed)) console.log(`    ${m.name}: ${m.detail}`);
@@ -2180,7 +2231,7 @@ async function itemsCmd(kind) {
   const items = workspaceItems(discovery, lock)[kind];
   const standalone = discovery.standalone === true;
   if (JSON_MODE) { jsonOk({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems: discovery.problems }); return; }
-  console.log(`${kind} of workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${standalone ? `  — standalone: the workspace of ${memberLabel(discovery.key)} cannot be read` : ""}\n`);
+  console.log(`${kind} of workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${standalone ? `  — ${standaloneNote(discovery)}` : ""}\n`);
   if (!items.length) console.log("  (none)");
   else if (kind === "souls") printTable(["name", "origin", "team", "work"], items.map((s) => [s.name, s.origin, s.team, s.work ?? "—"]));
   else printTable(["name", "origin", "team", "layer"], items.map((c) => [c.name, c.origin, c.team, c.layer ?? "—"]));
@@ -2191,13 +2242,25 @@ async function itemsCmd(kind) {
 // ---------- roster: status / spawn / retire / create ----------
 /** Workspace drift for `oats status` (decision 17: shown, not prevented). ONE discovery over
  *  the remotes serves every instance; `driftOf` compares each instance's recorded modules to
- *  the members' current state (and package modules to the lock). Offline → { unreachable }.
- *  Returns null when the deployment is not a workspace deployment (no oats-local.yaml). */
+ *  the members' current state (and package modules to the lock), `soulDriftOf` the instance's
+ *  recorded SOUL SOURCE (instance.json.workspace.soul) to its member's current commit. Offline →
+ *  { unreachable }. Returns null when the deployment is not a workspace deployment (no
+ *  oats-local.yaml). `souls` maps each workspace soul NAME (agents/<name>/.oats-soul-source.json
+ *  present) to its stamp — the roster's `repo:` column for a workspace soul. */
 async function statusDrift(data) {
   let ctx;
   try { ctx = loadLocal(dirFlag()); } catch (e) { if (e?.code === "E_LOCAL_MISSING") return null; throw e; }
-  const hasModules = data.some((a) => (a.instances || []).some((i) => i.modules && typeof i.modules === "object" && Object.keys(i.modules).length));
-  if (!hasModules) return { drift: new Map(), unreachable: null };
+  const hasModules = (i) => i.modules && typeof i.modules === "object" && Object.keys(i.modules).length > 0;
+  const hasSoul = (i) => i.workspace && typeof i.workspace === "object" && i.workspace.soul && typeof i.workspace.soul === "object" && typeof i.workspace.soul.repoKey === "string";
+  // Workspace souls of this roster: the stamp ensureWorkspaceSoul leaves beside the soul pointer.
+  const souls = new Map();
+  for (const a of data) {
+    if (!a.dir) continue;
+    try { const stamp = JSON.parse(readFileSync(join(a.dir, ".oats-soul-source.json"), "utf8")); if (stamp && typeof stamp.repoKey === "string") souls.set(a.name, { repoKey: stamp.repoKey, commit: typeof stamp.commit === "string" ? stamp.commit : null, path: stamp.path ?? null }); }
+    catch { /* not a workspace soul (classic, capability agent, or unreadable stamp) */ }
+  }
+  const anything = data.some((a) => (a.instances || []).some((i) => hasModules(i) || hasSoul(i)));
+  if (!anything) return { drift: new Map(), soul: new Map(), souls, unreachable: null };
   const deploymentDir = dirname(ctx.path);
   let lock = null;
   try { if (existsSync(join(deploymentDir, LOCK_FILE))) lock = readLock(deploymentDir); } catch { lock = null; }
@@ -2207,15 +2270,22 @@ async function statusDrift(data) {
   try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); discovery = await discoverOrStandalone(ctx.local, { remoteOptions: remoteOptionsFromEnv() }); }
   catch (e) {
     const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
-    return { drift: new Map(), unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) } };
+    return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) } };
   }
-  const { driftOf } = await import("../lib/materialize.mjs");
+  const { driftOf, soulDriftOf } = await import("../lib/materialize.mjs");
   const drift = new Map();
+  const soul = new Map();
   for (const a of data) for (const i of a.instances || []) {
-    if (!i.modules || typeof i.modules !== "object" || !Object.keys(i.modules).length) continue;
-    try { drift.set(i.home ?? `${a.name}/${i.instance}`, driftOf(i, discovery, { lock })); } catch { /* an unreadable module record shows as no drift rows */ }
+    const key = i.home ?? `${a.name}/${i.instance}`;
+    if (hasModules(i)) { try { drift.set(key, driftOf(i, discovery, { lock })); } catch { /* an unreadable module record shows as no drift rows */ } }
+    if (hasSoul(i)) { try { const row = soulDriftOf(i, discovery); if (row) soul.set(key, row); } catch { /* an unreadable soul record shows as no soul row */ } }
+  }
+  // The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
+  for (const [, stamp] of souls) {
+    const member = discovery.members.find((m) => m && m.key === stamp.repoKey);
+    if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
   }
-  return { drift, unreachable: null };
+  return { drift, soul, souls, unreachable: null };
 }
 /** One `modules:` line per module. */
 function driftLine(row) {
@@ -2226,6 +2296,20 @@ function driftLine(row) {
   if (row.status === "missing") return `${base}  [${row.reason === "capability-absent" ? "capability no longer present" : row.reason === "package-absent" ? "package no longer locked" : `member ${row.reason || "unconfirmed"}`}]`;
   return base;
 }
+/** The `soul:` line of an instance — decision 17 for the soul source. */
+function soulDriftLine(row, agentName) {
+  const base = `soul: ${row.name ?? agentName} from ${memberLabel(row.repoKey)} @ ${short7(row.commit)}`;
+  if (row.status === "moved") return `${base}  [member moved since (now @ ${short7(row.current?.commit)})]`;
+  if (row.status === "missing") return `${base}  [${row.reason === "soul-absent" ? "soul no longer present" : `member ${row.reason || "unconfirmed"}`}]`;
+  return base;
+}
+/** The roster's `[work: …, repo: …]` for a soul: a workspace soul names its member and commit. */
+function soulRepoLabel(a, ws) {
+  const stamp = ws?.souls?.get(a.name);
+  if (!stamp) return a.repo || "?";
+  const moved = stamp.current && stamp.commit && stamp.current !== stamp.commit ? ` (member now @ ${short7(stamp.current)})` : "";
+  return `${memberLabel(stamp.repoKey)} @ ${short7(stamp.commit)}${moved}`;
+}
 const short7 = (oid) => (typeof oid === "string" ? oid.slice(0, 7) : "?");
 
 async function status() {
@@ -2237,18 +2321,31 @@ async function status() {
   const ws = await statusDrift(data);
   const verbose = args.includes("--verbose");
   if (args.includes("--json")) {
-    if (ws) for (const a of data) for (const i of a.instances || []) { const rows = ws.drift.get(i.home ?? `${a.name}/${i.instance}`); if (rows) i.modules = rows.map((r) => ({ name: r.module, from: r.from, commit: r.recorded?.commit ?? null, current: r.current, status: r.status, ...(r.reason ? { reason: r.reason } : {}) })); }
+    if (ws) for (const a of data) {
+      const stamp = ws.souls.get(a.name);
+      if (stamp) a.soulSource = { repoKey: stamp.repoKey, commit: stamp.commit, path: stamp.path, ...(stamp.current ? { current: stamp.current, status: stamp.current === stamp.commit ? "current" : "moved" } : {}) };
+      for (const i of a.instances || []) {
+        const key = i.home ?? `${a.name}/${i.instance}`;
+        const rows = ws.drift.get(key);
+        if (rows) i.modules = rows.map((r) => ({ name: r.module, from: r.from, commit: r.recorded?.commit ?? null, current: r.current, status: r.status, ...(r.reason ? { reason: r.reason } : {}) }));
+        const s = ws.soul.get(key);
+        if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}) };
+      }
+    }
     console.log(JSON.stringify({ root, agents: data, ...(ws ? { workspace: ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true } } : {}) }, null, 2)); return;
   }
   console.log(`oats status — agents root ${shortPath(root)}\n`);
   if (ws?.unreachable) console.log(`  workspace: unreachable (${ws.unreachable.reason}) — drift unknown\n`);
   if (data.length === 0) { console.log("  (no agents — create one with `oats create <name>`)"); return; }
   for (const a of data) {
-    console.log(`  ${a.name}${a.kind === "local" ? " (local)" : ""}  [work: ${a.work || "checkout"}, repo: ${a.repo || "?"}]`);
+    console.log(`  ${a.name}${a.kind === "local" ? " (local)" : ""}  [work: ${a.work || "checkout"}, repo: ${soulRepoLabel(a, ws)}]`);
     if (a.description) console.log(`      ${a.description}`);
     for (const i of a.instances) {
       console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : i.running ? "RUNNING" : "idle"}  (branch ${i.branch || "?"}, ${i.work || "?"})`);
-      const rows = ws?.drift.get(i.home ?? `${a.name}/${i.instance}`) || [];
+      const key = i.home ?? `${a.name}/${i.instance}`;
+      const s = ws?.soul.get(key);
+      if (s && (verbose || s.status !== "current")) console.log(`          ${soulDriftLine(s, a.name)}`);
+      const rows = ws?.drift.get(key) || [];
       for (const r of rows) if (verbose || r.status !== "current") console.log(`          ${driftLine(r)}`);
     }
     for (const f of a.retireFailures || []) {
@@ -2502,13 +2599,20 @@ async function spawnCmd() {
   // package = locked+approved) and copied whole into the new home. Without one
   // (a bare agents root, tests) the classic soul-directory spawn proceeds.
   let prepared;
+  // Workspace model: a `work: worktree|checkout` soul works IN its member's clone on
+  // this machine (design doc §4): --repo, else oats-local.yaml `clones:`, else the
+  // convention <deployment>/<member name>. Never an ambient Git checkout around the
+  // deployment. Resolved once here so a preview sees exactly what the apply would.
+  let preparedRepo;
   if (wsPrepared) {
     try {
-      const { toCapabilityRows, modulesPreview } = await import("../lib/instance-resolution.mjs");
+      const { toCapabilityRows, modulesPreview, requireMemberClone } = await import("../lib/instance-resolution.mjs");
       prepared = wsPrepared;
       prepared.capabilityRows = []; // filled after materialization (paths live in the home); preview uses modulesPreview
       prepared.preview = modulesPreview(prepared.resolution, root, agent.name);
       prepared.toCapabilityRows = toCapabilityRows;
+      const effectiveWork = requestedWork || agent.work || "checkout";
+      if (effectiveWork === "worktree" || effectiveWork === "checkout") preparedRepo = requireMemberClone(prepared, { explicit: repo });
     } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details); throw e; }
   }
   let r;
@@ -2521,7 +2625,7 @@ async function spawnCmd() {
       ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
       // Directory execution uses deployment configuration, not an ambient Git
       // checkout (especially when invoked via --dir from a source instance).
-      repo: (requestedWork || agent.work) === "directory"
+      repo: preparedRepo !== undefined ? preparedRepo : (requestedWork || agent.work) === "directory"
         ? (repo ?? agent.repo) : repo || agent.repo || defaultRepo(workspaceOf(root)) || defaultRepo(process.cwd()),
       work: requestedWork, workDir, runtime: flag("runtime"), backend, herdrSocket, yolo, model: flag("model"), branch,
       launchConfig: valueFlag("launch-config"),
@@ -2823,7 +2927,7 @@ async function paneCmd() {
 
 /** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
  *
- * Realizes a workspace on this machine in the taught `<name>-workspace/` layout
+ * Realizes a workspace on this machine in the directory the operator chooses (decision 9)
  * (docs/design/2026-09-23-simplified-workspace-model.md §4): writes
  * `<dir>/oats-local.yaml` naming the workspace, creates `<dir>/agents/` (the
  * instance homes), then runs exactly the `oats sync` path — discover over the
@@ -2914,9 +3018,20 @@ async function onboardCmd() {
   const spawnHint = setupExpert ? `oats spawn oats-setup-expert --dir ${shortPath(dir)}` : null;
   const anySoulHint = `spawn any listed soul: oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
   // A member's clone goes beside oats-local.yaml under its repo name; `agents/` is the instance
-  // homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4).
+  // homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4). The HOST is
+  // listed exactly like any other member when it is one: a clone of it is needed only if someone
+  // works IN it — there is no special "workspace clone" (discovery reads the host over the remote).
   const cloneDirOf = (m) => join(dir, m.name === "agents" ? "agents-repo" : m.name);
-  const clones = members.filter((m) => m.confirmed || (standalone && m.key === synced.discovery.key)).map((m) => ({ key: m.key, name: m.name, url: memberUrlOf(synced.discovery, m.key), dir: cloneDirOf(m) }));
+  const clonePresent = (m, cloneDir) => {
+    const declared = ctx.local?.clones && typeof ctx.local.clones === "object" ? ctx.local.clones[m.key] : undefined;
+    const candidate = typeof declared === "string" && declared.trim() ? resolve(dir, declared) : cloneDir;
+    return existsSync(join(candidate, ".git")) ? candidate : null;
+  };
+  const clones = members.filter((m) => m.confirmed || (standalone && m.key === synced.discovery.key)).map((m) => {
+    const cloneDir = cloneDirOf(m);
+    const present = clonePresent(m, cloneDir);
+    return { key: m.key, name: m.name, url: memberUrlOf(synced.discovery, m.key), dir: present ?? cloneDir, present: present !== null, host: m.key === synced.discovery.key };
+  });
   // Decision 26: the host publishes the member list to whoever can read it. When the host is
   // itself a member (the common `agents` shape) that is fine for an all-private or all-public
   // organisation; a mixed one needs a private host that is NOT a public member. The kernel
@@ -2926,20 +3041,18 @@ async function onboardCmd() {
   const result = { onboardApi: 2, standalone: standalone || undefined, local: localFile, dir, agents: join(dir, "agents"), lock: synced.lockFile, sync: synced.report, hosting, next: { clone: clones, spawn: spawnHint, souls: soulNames.slice(0, 3) } };
   if (JSON_MODE) { jsonOk(result); process.exitCode = synced.approvalNeeded.length ? 2 : 0; return; }
 
-  console.log(`Onboarded ${shortPath(dir)} into workspace ${workspaceName(synced.discovery)} (${synced.discovery.key} @ ${short(synced.discovery.commit)}).${standalone ? `\n  (standalone — the workspace of ${memberLabel(synced.discovery.key)} cannot be read from here; you get its own souls + oats.core)` : ""}\n`);
+  console.log(`Onboarded ${shortPath(dir)} into workspace ${workspaceName(synced.discovery)} (${synced.discovery.key} @ ${short(synced.discovery.commit)}).${standalone ? `\n  (${standaloneNote(synced.discovery, { from: " from here" })})` : ""}\n`);
   printSyncReport(ctx, synced);
   console.log(`
-Layout (the taught convention — the kernel finds clones through oats-local.yaml, so any layout works):
-  ${shortPath(dir)}/
+This directory (${shortPath(dir)}) is your deployment — any layout works; it now holds what the kernel needs:
   ├── oats-local.yaml     which workspace this machine realizes (+ host settings, disabled souls)
   ├── oats-lock.json      exact commit + integrity + per-version executable approval per package
-  ├── agents/             instance homes, each self-contained
-  └── <member>/           clones of the members you will work IN (only those)
+  └── agents/             instance homes, each self-contained
+Member clones live wherever you keep them (here, or anywhere named in oats-local.yaml clones:).
 
 Next:
-  1. Clone the members you will work IN beside oats-local.yaml (discovery and resolution run over the
-     remotes; only a soul's work target needs a clone):${clones.map((c) => `\n       git clone ${c.url ?? c.key} ${shortPath(c.dir)}`).join("") || "\n       (no confirmed members yet — see the membership rows above)"}
-     A clone elsewhere is fine: point at it in oats-local.yaml under clones: { <repo key>: <abs path> }.
+  1. Members you will work IN need a clone (discovery and resolution run over the remotes; only a
+     soul's work target does):${clones.map((c) => c.present ? `\n       ${shortPath(c.dir)}  ✓ already here${c.host ? "  (the host — a member like the others)" : ""}` : `\n       git clone ${c.url ?? c.key} ${shortPath(c.dir)}   (or point oats-local.yaml clones: { ${c.key}: <abs path> } at an existing clone)${c.host ? "\n         ↑ the host is a member like the others: clone it only if someone works IN it — the workspace file is read over the remote" : ""}`).join("") || "\n       (no confirmed members yet — see the membership rows above)"}${!hostIsMember ? `\n       (the host ${synced.discovery.key} is not a member: nothing to clone — the workspace file is read over the remote)` : ""}
   2. Check who may read the host: ${synced.discovery.key}${hostIsMember ? " is itself a member" : " is a dedicated host"}. The workspace file
      names every member, so if any member is private the host must be a private repo that is not
      a public member; public contributors then get the standalone case (from: here + oats.core).
@@ -3879,12 +3992,15 @@ Usage:
   oats update [--check] [--yes]              check npm for a newer kernel+pi bridge and
                                             optionally run the update; then run oats doctor
   oats sync [--dir <d>] [--json]             workspace model v2: observe the workspace named by
-                                            oats-local.yaml over its Git remote, confirm every
+      [--approve <id>@<version>]...         oats-local.yaml over its Git remote, confirm every
                                             member (reciprocal oats-membership.yaml), resolve
                                             packages: to exact commits, ask executable approval
                                             once per package version (TTY; otherwise list what
                                             needs it and exit 2), write oats-lock.json (v3) and
-                                            report the diff
+                                            report the diff. --approve approves exactly that
+                                            package at exactly that locked version without a
+                                            terminal (the digest is computed over the locked
+                                            tree; an id@version not in the lock is E_BAD_ARGS)
   oats package add <id> <version|git:<repo>@<ref>>  edit packages: in oats-workspace.yaml when the
       | remove <id>  [--dir <d>]            workspace repo is the current checkout; otherwise
                                             print the line to add (the file travels through Git)

package/docs/configuration.md

@@ -21,7 +21,7 @@ converted: [rebuild-to-v2.md](rebuild-to-v2.md).
 schemaVersion: 2
 workspace: git:github.com/acme/agents        # REQUIRED — the workspace host, observed over the remote
 
-clones:                                      # optional — member clones outside the <name>-workspace/ convention
+clones:                                      # optional — member clones that are not beside oats-local.yaml under their repo name
   github.com/acme/platform: /Users/ana/src/acme-platform
 
 settings:                                    # optional — host-owned values per capability
@@ -41,7 +41,7 @@ refused (`E_WORKSPACE_SCHEMA`).
 | key | meaning |
 |---|---|
 | `workspace` | Repo ref of the workspace host (`git:host/org/repo`, `https://…`, `git@host:…`, `file:///…`, `/abs/bare.git`). Read with your own Git credentials; the repo need not be cloned. |
-| `clones` | `<canonical repo key>: <absolute path>` — where a member's clone lives when it is not at `<deployment>/<repo-name>/`. Only a soul's **work target** needs a clone. |
+| `clones` | `<canonical repo key>: <absolute path>` — where a member's clone lives when it is not at `<deployment>/<member name>/`. Only a soul's **work target** (`work: worktree \| checkout`) needs a clone. Lookup order: `spawn --repo`, then this map (keys normalised through `parseRepoRef`, so any ref spelling of the same repo matches), then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`, since `agents/` is the instance root); none → `E_CLONE_MISSING`; a directory whose `origin` is another repo → `E_CLONE_MISMATCH`. |
 | `settings.<cap>.<key>` | Host-owned provider values the capability's manifest asks for — absolute paths, state roots, delivery modes. The workspace file **refuses** absolute paths; this is where they go. Merged into the capability's provider payload after the soul's own payload and before any `--provider` flag (see [three homes](workspaces.md#provider-payloads-have-three-homes)). |
 | `souls.disabled` | Soul names not run on this machine; reported by `oats sync` ("disabled here"). |
 
@@ -56,7 +56,7 @@ deployment. Not found → `E_LOCAL_MISSING`. Beside it:
 ~/acme-workspace/
 ├── oats-local.yaml
 ├── oats-lock.json          # written by `oats sync` (lock v3; docs/packages.md)
-├── agents/                 # instance homes + fetched member-soul sources
+├── agents/                 # instance homes + fetched member-soul sources (created by `oats sync` / `oats onboard` if absent)
 └── <member clones>/        # only where someone works IN a repo
 ```
 

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` 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).
+**Last update:** 2026-09-23 20:00Z · **0.25.0 + 0.25.1 PUBLISHED** (workspace model A–C + team-review fixes) · 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-20-workspace-and-portable-adoption-plan.md

@@ -4,7 +4,7 @@
 
 **Status:** Phase1 implementation authorised by the human, using the existing developers under lead supervision/review. The workspace home is confirmed as `oats`; `oats-dev` remains development capabilities. This does not claim completed conversion or authorise unspecified new contracts, credential operations or live deployment mutations.
 
-> **2026-09-23 — direction change, read first.** Phases 1–3 delivered as written (workspace on Git, five souls + central knowledge, all contract-bearing Desktop parity slices, releases 0.24.7–0.24.13). Reviewing the result, the human judged the *declaration model* itself too heavy and, in one sitting, accepted a simplified **workspace model v2**: one workspace per org; reciprocal membership as the only gate and as the trust decision; a soul says `from:` (member repo | `here` | `package`) — a location, never a version; packages are the only versioned thing; **nothing is installed** — every capability is copied whole into the instance at spawn; discovery over Git remotes; teams as labels; harnesses start normally. Record: `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`; worked example: [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md). **Consequences for this plan:** P1.3's `oats.yaml` export indexes and P1.4's `oats-config.yaml` activation are superseded (→ `oats-membership.yaml`, derived activation); D1/D4 stand (`oats.core` becomes `from: package` by default; the catalog stays as discovery); D2's "explicit `oats.core` on every soul" is met by the workspace default; D3 gains the `<name>-workspace/` convention and clone-then-spawn. **No migration** — clean v2, the framework's own repos are the first workspace. A Phase 4 implementation plan is proposed to the human before any `lib/`/`bin/` change; the Desktop parity pipeline is paused meanwhile except for the in-flight 10B-0 security fix.
+> **2026-09-23 — direction change, read first.** Phases 1–3 delivered as written (workspace on Git, five souls + central knowledge, all contract-bearing Desktop parity slices, releases 0.24.7–0.24.13). Reviewing the result, the human judged the *declaration model* itself too heavy and, in one sitting, accepted a simplified **workspace model v2**: one workspace per org; reciprocal membership as the only gate and as the trust decision; a soul says `from:` (member repo | `here` | `package`) — a location, never a version; packages are the only versioned thing; **nothing is installed** — every capability is copied whole into the instance at spawn; discovery over Git remotes; teams as labels; harnesses start normally. Record: `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`; worked example: [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md). **Consequences for this plan:** P1.3's `oats.yaml` export indexes and P1.4's `oats-config.yaml` activation are superseded (→ `oats-membership.yaml`, derived activation); D1/D4 stand (`oats.core` becomes `from: package` by default; the catalog stays as discovery); D2's "explicit `oats.core` on every soul" is met by the workspace default; D3 gains the `the operator's deployment directory` convention and clone-then-spawn. **No migration** — clean v2, the framework's own repos are the first workspace. A Phase 4 implementation plan is proposed to the human before any `lib/`/`bin/` change; the Desktop parity pipeline is paused meanwhile except for the in-flight 10B-0 security fix.
 
 ## Goal and order
 

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

@@ -1,6 +1,6 @@
 # A simpler multi-repo model for OATS — brainstorm with a worked example
 
-**Status:** **ACCEPTED DIRECTION** — every question closed with the human on 2026-09-23; nothing implemented yet. This document is the worked example; the normative record is the Decision concept `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md` and the adoption plan. Implementation is a clean v2 (no migration), planned separately. **Decided so far (human, 2026-09-23):** (1) reciprocal membership stays a hard gate; (2) workspace-tier trust = membership, nothing more; (3) everything in a member is discoverable by default — a soul or capability that wants to stay internal says `private: true` in its own definition; (4) the repo's half of the handshake is a one-line **`oats-membership.yaml`** (replaces `oats.yaml`); (5) **no migration path** — a clean break to v2; (6) a soul names each capability **with where it comes from** (`from: <member repo>` or `from: package`) — a location, never a version; resolution is a handshake check + lookup, not a search; (7) **full per-instance materialization** — every capability (skills, injects, scripts, hooks) is copied into the instance at spawn; a running instance never changes under itself; (8) **nothing is "installed"** — a package is just a second kind of source, fetched at the pinned version and copied in like a member's capability; the lock records exact commit/integrity and the one-time executable approval per version; (9) **discovery and resolution work against Git remotes, never local clones** — the only thing that needs a clone is a soul's work target; the local layout is the operator's, with a taught convention (`<name>-workspace/`); (10) the handshake is *observed* with the operator's own read access to both halves — no access to the workspace repo means no membership from that seat, by design; (11) **members carry no revision** — a member is always its latest state; a team that wants frozen capabilities publishes them as a package and pins that; (12) **one workspace per org, teams are labels** — `team:` on a soul/capability (or a repo default in `oats-membership.yaml`) organises and can supply additive defaults, but never gates, restricts or partitions anything; (13) **harnesses start normally and resolve skills from their own default places** — OATS contributes materialized capability skills into the instance's `.agents/skills/` and stops excluding machine-level or repo-level skills. **All questions closed; ready to be written up as a Decision.**
+**Status:** **ACCEPTED DIRECTION** — every question closed with the human on 2026-09-23; nothing implemented yet. This document is the worked example; the normative record is the Decision concept `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md` and the adoption plan. Implementation is a clean v2 (no migration), planned separately. **Decided so far (human, 2026-09-23):** (1) reciprocal membership stays a hard gate; (2) workspace-tier trust = membership, nothing more; (3) everything in a member is discoverable by default — a soul or capability that wants to stay internal says `private: true` in its own definition; (4) the repo's half of the handshake is a one-line **`oats-membership.yaml`** (replaces `oats.yaml`); (5) **no migration path** — a clean break to v2; (6) a soul names each capability **with where it comes from** (`from: <member repo>` or `from: package`) — a location, never a version; resolution is a handshake check + lookup, not a search; (7) **full per-instance materialization** — every capability (skills, injects, scripts, hooks) is copied into the instance at spawn; a running instance never changes under itself; (8) **nothing is "installed"** — a package is just a second kind of source, fetched at the pinned version and copied in like a member's capability; the lock records exact commit/integrity and the one-time executable approval per version; (9) **discovery and resolution work against Git remotes, never local clones** — the only thing that needs a clone is a soul's work target; the local layout is the operator's — onboarding asks for the directory, no named convention; (10) the handshake is *observed* with the operator's own read access to both halves — no access to the workspace repo means no membership from that seat, by design; (11) **members carry no revision** — a member is always its latest state; a team that wants frozen capabilities publishes them as a package and pins that; (12) **one workspace per org, teams are labels** — `team:` on a soul/capability (or a repo default in `oats-membership.yaml`) organises and can supply additive defaults, but never gates, restricts or partitions anything; (13) **harnesses start normally and resolve skills from their own default places** — OATS contributes materialized capability skills into the instance's `.agents/skills/` and stops excluding machine-level or repo-level skills. **All questions closed; ready to be written up as a Decision.**
 **Date:** 2026-09-23
 **Author:** oats-expert, from a conversation with the human about the weight of the current declaration files.
 
@@ -419,10 +419,10 @@ Northwind adopts it through `external:` with a pinned revision. There is deliber
 
 **The only thing that needs a local clone is a soul's work target** — a soul with `work: worktree | checkout | directory` works *in* a repo, so that repo must be on disk. Spawning a soul whose repo is not yet cloned is therefore a *guided clone into the conventional place, then spawn*: a job for the onboarding skill (`oats-setup-expert`), not the kernel.
 
-The **taught default** — what onboarding sets up and what the docs show — is one folder named after the workspace with the member clones inside it:
+**The deployment directory is the operator's choice** (decision 9): an existing folder that already holds the member clones is the usual case; onboarding asks for it (`oats onboard <dir>`) and adds the three entries the kernel needs. Shown here as Ana's `~/northwind/`, with the member clones inside it:
 
 ```
-~/northwind-workspace/            ← "<name>-workspace"
+~/northwind/                      ← the directory Ana chose (any name, any place)
 ├── oats-local.yaml               ← which workspace this machine realizes + host paths + disabled souls
 ├── oats-lock.json                ← exact commit + integrity + per-version approval per package
 ├── agents/                       ← instance homes, each self-contained
@@ -565,7 +565,7 @@ OATS is a **skill contributor, not a skill sandbox**. Today the harness is launc
 - **Duplicate names** (team review): two *composed* capability skills with the same name are still a spawn error naming both (`skill-overrides` picks one). A composed skill and an ambient repo/machine skill with the same name is **not** an error — the harness's precedence decides; the preview lists composed names so a clash is visible.
 
 ```
-~/northwind-workspace/agents/release-manager/instances/release-manager-v3/
+~/northwind/agents/release-manager/instances/release-manager-v3/
 ├── AGENTS.md                             ← canonical, composed: soul AGENTS.md + capability injects
 ├── CLAUDE.md → AGENTS.md                 ← relative symlink (unchanged from today)
 ├── .agents/skills/                       ← canonical; where Pi (and Codex) look

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

@@ -328,8 +328,8 @@ 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
+boundary — the directory holding `oats-local.yaml` (whatever the operator
+named it, member clones beside it or named in `clones:`) — 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
@@ -458,3 +458,109 @@ 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`).
+
+### 0.25.2 operator-rebuild round (2026-09-24) — appended, not edited in place
+
+Source: an operator's first rebuild of a real two-team deployment on 0.25.0,
+following `docs/rebuild-to-v2.md` literally. **The guide is a contract the
+kernel must honour**: where the guide claimed behaviour the kernel lacked, the
+kernel changes; where the guide described keys no provider consumes, the guide
+changes. Findings R1–R10; kernel side in 0.25.2 (`docs/release-notes/v0.25.2.md`).
+No API integer or feature name changes; the only surface additions are
+additive fields (`spawn --preview` `providers` / `settings`, `oats status
+--json instances[].soul`) and the `sync --approve` flag.
+
+**§2/§5 member clone lookup (R1).** For a `work: worktree | checkout` soul the
+kernel finds the member clone in this order, first hit wins: (1) `oats spawn
+--repo <abs path>`; (2) `oats-local.yaml` `clones: { <repo key>: <abs path> }`,
+keys normalised through `parseRepoRef(...).key` so any spelling of the same
+repo addresses one entry; (3) the convention `<deployment>/<member name>` where
+`<member name>` is the last segment of the repo key — **a member named `agents`
+is looked for at `<deployment>/agents-repo`** (`<deployment>/agents/` is the
+instance root); (4) none → `E_CLONE_MISSING { repoKey, tried: [...], remedies }`
+naming the three remedies. A directory found by (2) or (3) whose `origin` remote
+resolves to a different repo key → `E_CLONE_MISMATCH { repoKey, path, origin }`
+— the kernel never spawns into a clone that is not the member. This order was
+stated by the guide and `docs/workspaces.md` before 0.25.2 and not implemented;
+it is now normative.
+
+**§6 `oats sync` creates `agents/` (R2).** `sync` (and therefore `onboard`,
+which runs the sync body) creates `<deployment>/agents/` when absent. A
+hand-written `oats-local.yaml` needs no `mkdir`.
+
+**§5 one "You run on OATS" block (R3).** When `oats.core` resolves as a module
+the composer suppresses the kernel's legacy `oats:kernel:oats` block; the
+module's inject is the one such block. Without `oats.core` (a soul saying `off`)
+the legacy block is composed as before, so no instance is left without the
+briefing.
+
+**§5/§6 soul-source drift (R4).** `driftOf` covers `instance.json.workspace.soul`
+as well as `modules`: `oats status` prints `soul: <name> from <member> @ <c7>`
+with `[member moved since …]` when the member's default branch is past the
+recorded commit (`[member unconfirmed]` / `[soul no longer present]` for the
+missing cases); `--json` adds `instances[].soul = { repoKey, commit, current:
+<commit>|null, status: "current"|"moved"|"missing" }`. A moved soul is
+information (decision 17): the instance keeps its own commit directory (M1).
+
+**§6 preview payload visibility (R5).** `oats spawn --preview` (text and
+`--json`) reports `providers` — the `--provider <cap> k=v` map exactly as given,
+nested — and `settings.<cap>` — `resolution.payloads[cap]`, the merged payload
+the provider's binding receives (`workspace.messaging` base ⊕ `byTeam[team]` ⊕
+soul slot payload ⊕ `local.settings[cap]` ⊕ `providers[cap]`). Additive fields;
+both empty objects when nothing applies.
+
+**§5/§6 `work: workspace` (R6, closed in 0.25.1 as B2).** Documented in the
+guide's §9: a coordination soul's `./work` is the deployment directory.
+
+**Provider payload delivery vs provider consumption (R7 — oats.aweb 1.11.2).**
+Decision 23 (`messaging.byTeam`) is **kernel semantics**: the kernel merges and
+delivers; the provider consumes what its binding declares. oats.aweb 1.11.2's
+spawn hook (a) locates the aweb root among `OATS_TEAM_SCOPE`, the home, the
+home's git root, `OATS_CONTEXT` and its git root, and `OATS_WORKSPACE` (under
+v2: the deployment directory) — none of which is a 0.24 team root; and (b)
+resolves the target team from `OATS_TEAM_ID`/`OATS_TEAM_NAME` (the removed
+`oats-config.yaml` `team:` block; empty under v2), else the **active team at
+the root it found** — it does **not** read `team` from `OATS_SETTINGS`. So for
+1.11.2 `byTeam` is delivered and recorded but a no-op; per-label minting is
+obtained only by placing a per-team `.aw` inside each team's member clone
+(gitignored) so it is found through the work repo, or one `.aw` at the
+deployment directory for a single team. The guide states this (§8b) and
+`docs/workspaces.md` states the general rule ("kernel-merged; whether a
+provider honours it is the provider's"). **oats.aweb follow-up**: read `team`
+(and honour `byTeam`'s result) from the payload; accept the deployment
+directory as a first-class root. The kernel does not paper over this with a
+`team:` env shim — the env block is removed with `oats-config.yaml`, and a
+provider contract is the provider's to grow.
+
+**OKF 2.1.3 reads `okf.json`, not a soul payload (R8 — corrects §2's `stores`
+comment and decision 24's `root` example).** `oats.okf` 2.1.3's spawn hook
+reads the soul's knowledge declaration from `<soul>/okf.json` (`{ version: 1,
+owner, owns: ["<base>/<node>"], reads: [...] }`, `lib/config.mjs#validateDeclaration`)
+and its settings from `OATS_SETTINGS`, admitting **only** `bindings-file`,
+`state-dir`, `harvest-runtime`, `harvest-model` (`oats.json#settings`) — any
+other key is `E_CONFIG unknown OATS_SETTINGS property`. Where a base lives
+inside a store repository is the **bindings file's** `bases.<alias>.repository`
++ `root`, not a soul payload key. Therefore: a soul.yaml `knowledge:` payload for
+OKF carries binding settings only (usually nothing — the workspace default
+fills the slot; `none` opts out); `owns`/`reads`/`store`/`root` examples on
+`soul.yaml` are removed from the guide, `workspaces.md`, `souls-and-instances.md`
+and `knowledge.md`; `okf.json` stays in `souls/<name>/` and travels with the
+soul into the per-commit cache (M1). A soul-payload grammar for OKF is an OKF
+follow-up that lands with an `oats.okf` release declaring it in its binding.
+The kernel's part — opaque forwarding of the merged payload — is unchanged and
+correct. §7b's fresh `state-dir` rule is confirmed by the operator's run.
+
+**§6 non-interactive approval (R9).** `oats sync --approve <id>@<version>`
+(repeatable) approves exactly the entry the current resolution contains for
+that id and version: the executables digest is always computed by `sync` over
+the fetched tree (`executablesDigestAt`) and recorded — never typed. An
+`--approve` naming an id/version the resolution does not contain → `E_BAD_ARGS`
+(nothing approved); entries not covered stay unapproved (exit `2`). At the
+interactive prompt **Ctrl+D (EOF) is a decline**: exit `2`, entry unapproved —
+never treated as "yes", never a hang.
+
+**§6 onboard next steps (R10).** `oats onboard` lists the workspace **host**
+in `next.clone` like any member that lacks a clone at the convention (the host
+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.

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

@@ -28,9 +28,9 @@ Each is one PR (or two small ones), reviewed by me, on `main`, as canonical code
 | **W7** | **CLI switch-over** | `oats sync`, `oats spawn` (preview/apply unchanged in shape, now fed by W4/W6), `oats capabilities` / `oats souls` with origin + team, `oats workspace status`; `oats status` shows `modules … @ commit` + `member moved since`; `oats version --json` advertises `workspaceApi: 2` + feature `workspace-v2`; **remove the v1 readers** (`oats.yaml`, per-soul `source:`, `oats-config.yaml` activation) — a v1 file at a v2 path errors naming the schema | lead | M |
 | **W8** | **Delete v1** | Remove `portable-*`, `source-spec`, `capability-provenance` (v1 parts), `prepared-resources`, migration stores/evidence, the installed tier in `packages.mjs`, classic config activation, their tests and docs; `core.mjs` loses everything that only served v1 | lead | L (mostly deletion) |
 | **W9** | **Framework repos as the first workspace (decisions 18–21)** | `oats-workspace.yaml` v2 in `oats` (drop the six imports; `packages:` pins oats.framework/okf/aweb/jira/linear/authoring/dev **as packages**; `teams:` global/engineering; `defaults`); `oats-membership.yaml` in ALL seven repos; the six soul editions rewritten (`oats.okf: {from: package}` etc. even though the repos are members); **a new expert soul in every package repo** — `okf-expert`, `aweb-expert`, `jira-expert`, `linear-expert`, `authoring-expert`, `dev-expert` (v2 `souls/<name>/`, team global, knows and evolves that capability); `package-catalog.json` kept as the official marketplace (bare-version `packages:` entries resolve through it) | lead (member-repo PRs to their owners; the expert souls' AGENTS.md drafted by me, reviewed by the package owner) | L |
-| **W9b** | **`oats.core` and `oats.setup` rewritten for the new architecture (human, 2026-09-23)** | The two official capabilities' skills and injects are rewritten to teach the *new* model, not patched: **`oats.core`** (`oats-operate`, `oats-souls`, the "you run on OATS" inject) — how an agent works inside an instance under this architecture: its home layout (`.oats/modules/`, `.agents/skills/`, `instance.json` modules/providers), the verbs it will actually use (`status`, `spawn --preview/--provider`, `retire`, `session`, `instance events`, `capabilities`, `souls`, `workspace status`), what a workspace/member/package/team is *from the agent's seat*, drift ("member moved since"), how to find and read other souls. **`oats.setup`** (`oats-config`/`oats-packages` → renamed to what they now are: `oats-workspace`, `oats-packages`, `oats-onboarding`) — the whole architecture and its best practices: workspace ↔ repo handshake and why, `oats-workspace.yaml` / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` field by field, teams as labels, member-tier vs package-tier and the non-collapse rule, `packages:` + lock v3 + per-version approval, the official catalog vs `git:` refs, `sync`/`package add`, the `<name>-workspace/` convention and clone-then-spawn, private items, external souls, the standalone case, provider payload homes (soul/machine/spawn), what is deliberately NOT versioned and why. Every skill is validated against the shipped CLI (`oats <verb> --help` snapshot test) so they cannot drift from the commands. | lead (swarm + review) | M |
-| **W10** | **Docs** | **`docs/rebuild-to-v2.md` — the rebuild guide (ships with the schemas; states that 0.24.x keeps spawning 0.24.x deployments)**; `docs/workspaces.md` rewritten around v2; `souls-and-instances.md`, `packages.md`, `configuration.md` (mostly deleted), `first-team.md` → the `<name>-workspace/` convention; DTO doc § Workspace v2; release notes | lead | M |
-| **W11** | **Onboarding skill** | `oats-setup-expert` / `oats.setup`: teach `<name>-workspace/`, `oats sync`, clone-then-spawn; **the hosting rule for mixed public/private organisations (decision 26): ask up front whether any member is private; if so the workspace file is hosted in a private repo that is NOT a public member (a dedicated private `workspace` repo is the honest shape), public contributors get the standalone case with `oats.core` by default (decision 25); `oats onboard` prints the same rule in its next-steps**; the `oats-operate` skill updated for the new verbs | lead | S |
+| **W9b** | **`oats.core` and `oats.setup` rewritten for the new architecture (human, 2026-09-23)** | The two official capabilities' skills and injects are rewritten to teach the *new* model, not patched: **`oats.core`** (`oats-operate`, `oats-souls`, the "you run on OATS" inject) — how an agent works inside an instance under this architecture: its home layout (`.oats/modules/`, `.agents/skills/`, `instance.json` modules/providers), the verbs it will actually use (`status`, `spawn --preview/--provider`, `retire`, `session`, `instance events`, `capabilities`, `souls`, `workspace status`), what a workspace/member/package/team is *from the agent's seat*, drift ("member moved since"), how to find and read other souls. **`oats.setup`** (`oats-config`/`oats-packages` → renamed to what they now are: `oats-workspace`, `oats-packages`, `oats-onboarding`) — the whole architecture and its best practices: workspace ↔ repo handshake and why, `oats-workspace.yaml` / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` field by field, teams as labels, member-tier vs package-tier and the non-collapse rule, `packages:` + lock v3 + per-version approval, the official catalog vs `git:` refs, `sync`/`package add`, the deployment directory (the operator's; no naming convention) and clone-then-spawn, private items, external souls, the standalone case, provider payload homes (soul/machine/spawn), what is deliberately NOT versioned and why. Every skill is validated against the shipped CLI (`oats <verb> --help` snapshot test) so they cannot drift from the commands. | lead (swarm + review) | M |
+| **W10** | **Docs** | **`docs/rebuild-to-v2.md` — the rebuild guide (ships with the schemas; states that 0.24.x keeps spawning 0.24.x deployments)**; `docs/workspaces.md` rewritten around v2; `souls-and-instances.md`, `packages.md`, `configuration.md` (mostly deleted), `first-team.md` → the operator's deployment directory; DTO doc § Workspace v2; release notes | lead | M |
+| **W11** | **Onboarding skill** | `oats-setup-expert` / `oats.setup`: ASK for the deployment directory (an existing folder with the operator's clones is the usual case — no named convention, decision 9), `oats sync`, clone-then-spawn; **the hosting rule for mixed public/private organisations (decision 26): ask up front whether any member is private; if so the workspace file is hosted in a private repo that is NOT a public member (a dedicated private `workspace` repo is the honest shape), public contributors get the standalone case with `oats.core` by default (decision 25); `oats onboard` prints the same rule in its next-steps**; the `oats-operate` skill updated for the new verbs | lead | S |
 | **W12** | **Desktop follow-through** | New kernel DTOs (from W7) consumed the usual way — engineer reads the merged head, files pins, wires: Capabilities/Souls origin + team columns; "installed" removed as a state; spawn preview shows modules (from/commit/hash) + team; Workspaces surface shows membership status | Desktop engineer, after W7 | M |
 
 **Team review (Antares, 2026-09-23) folded in:** rebuild guide (W10), **second review (two aweb teams, stores, soul layout, standalone, public/private hosting → decisions 23–26: `messaging.byTeam`, stores = repo + provider `root`, `souls/` only, `oats.core` standalone default, private host rule taught by onboarding),** `--provider` instance payload (W6/W7), drift display (W7), duplicate-name rule (W6), 0.24.x-keeps-working stated everywhere.