@awebai/oats 0.24.13 → 0.25.1

package/bin/oats.mjs

@@ -3,43 +3,45 @@
  * oats — the OATS command line.
  *
  *   oats doctor [dir] [--json]              show the resolved config with origins
- *   oats install <name|url|path> [...]      acquire + exact-lock a capability
- *   oats trust <capability>                approve locked executable surfaces
- *   oats use <capability> [...]            activate/exclude for global/group/soul
- *   oats init [--raw]                      create an oats-config.yaml here
+ *   oats onboard [<dir>] --workspace <ref>  realize a workspace here (oats-local.yaml +
+ *                                          agents/), then sync
+ *   oats sync [--dir <d>] [--json]          discover the workspace, confirm membership,
+ *                                          resolve packages, approve, write the lock
+ *   oats package add|remove ...            edit `packages:` in the workspace file
+ *   oats workspace status                  membership table, packages, approval
+ *   oats capabilities | oats souls         every visible item of the workspace
  *
- * `use` and `init` edit the oats-config.yaml at the detected level root:
- * cwd is your home dir → laptop; cwd has .git → repo; otherwise → workspace.
- * The kernel resolves per-key closest-wins from wherever agents actually run,
- * so binding at a level scopes the capability to everything under it.
+ * Workspace model v2 (docs/design/2026-09-23-workspace-module-contracts.md §6):
+ * nothing is installed. `oats-local.yaml` names the workspace, `oats sync`
+ * observes it over Git remotes and writes `oats-lock.json` (lockfileVersion 3).
+ * `init` / `use` / `install` / `restore` / `list` / `catalog` / `remove` /
+ * `migrate` / `trust` / `inject` are gone with the installed-capability tier.
  */
-import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { enableTmuxMouse, tmuxConfigPath, tmuxMouseEnabled } from "../lib/tmux-config.mjs";
 import {
-  LAYERS, WORK_MODES, LEGACY_HOME_CAPABILITIES_DIR, OATS_LOCK_FILE, OATS_VERSION, OAS_SCOPE_REMEDY, RETIRED_CAPABILITIES, detectOasScopes, retiredCapabilityReason, configChain, configCapabilityEntries, manifestOperations,
-  acquireCapability, restoreCapabilities, marketplaceCapabilities,
-  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityIntegrity, capabilityTrust, capabilityExecutablePath, activateCapturedScaffold, loadCapturedDispatch, inspectPortableOnboarding, prepareCapturedComposition, resolveCapturedHelper, capturedNativeSessionAvailability, scaffoldCapturedInstance, startCapturedInstanceSession, withCapturedBindingFile, withCapturedInvocationContextFile,
-  readCapabilityLocks, writeCapabilityLock, admitCapturedAction, beginCapturedIntent, settleCapturedIntent,
-  parsePackageSource, inspectGitSourceRoot, acquirePackage, restorePackages, listInstalledPackages, readPackageLocks, readLockedConfigTemplates,
-  officialCapabilityPackage, officialPackageCatalog, describeOfficialCatalog, DEFAULT_PACKAGE_PATH,
-  approveCapability, approveAvailableCapability, updatePackage, removePackage, migrateLegacyLock, applyLegacyLockMigration,
-  packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir, installedCapabilitiesDir, ownedCapabilitiesDir, loadPackageManifestAt,
-  resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, planInstanceResources, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
+  LAYERS, WORK_MODES, LEGACY_HOME_CAPABILITIES_DIR, OATS_VERSION, OAS_SCOPE_REMEDY, RETIRED_CAPABILITIES, detectOasScopes, retiredCapabilityReason, configChain, configCapabilityEntries, manifestOperations,
+  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityTrust, capabilityExecutablePath, activateCapturedScaffold, loadCapturedDispatch, inspectPortableOnboarding, prepareCapturedComposition, resolveCapturedHelper, capturedNativeSessionAvailability, scaffoldCapturedInstance, startCapturedInstanceSession, withCapturedBindingFile, withCapturedInvocationContextFile,
+  readCapabilityLocks, admitCapturedAction, beginCapturedIntent, settleCapturedIntent, listInstalledPackages, readPackageLocks,
+  officialPackageCatalog, describeOfficialCatalog, approveAvailableCapability,
+  packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir,
+  resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, parseYamlNested, assertSafeConfigValue, stripInternalAnnotations, withConfigFile, teamAgentRoots,
   findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions,
   ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
-  spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS, validateLaunchConfig, resolveLaunchSelection, resolveLaunchExecutable, checkLaunchExecutable, missingLaunchEnvRefs, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_RUNTIMES, LAUNCH_RECIPE_VERSION, parseLaunchCommand, resolveYolo, planLaunch, redactLaunchCommand, restartInstanceSession,
+  spawnInstance, spawnInstanceAsync, findModuleCapabilityAgent, capabilityAgentFromDir, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS, validateLaunchConfig, resolveLaunchSelection, resolveLaunchExecutable, checkLaunchExecutable, missingLaunchEnvRefs, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_RUNTIMES, LAUNCH_RECIPE_VERSION, parseLaunchCommand, resolveYolo, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
-  aggregateMissingRequirements, applyFromOasScope, beginRunJournal, discoverMigrationScopes, discoverOasScopes, discoverWorkspaceScopes, planFromOasScope,
-  adoptedTemplateDir, applyConfigMerge, lockedPackageCapabilities, planConfigMerge, readAdoptedTemplate, requirementInstallPlan,
-  assertNoSymlinkedParents, copyFileAtomic, writeFileAtomic,
-  runRequirementInstall, selectConfigTemplate, validateConfigTemplate, writeAdoptedTemplate,
-} from "../lib/packages.mjs";
+  assertNoSymlinkedParents, writeFileAtomic,
+  LOCK_FILE, readLock, writeLock, resolvePackages, approve as approvePackage,
+  classifyPackageValue, parsePackageRequest, executablesDigestAt } from "../lib/packages.mjs";
+import { loadLocal, discoverWorkspace, validateWorkspace } from "../lib/workspace.mjs";
+import * as remoteModule from "../lib/remote.mjs";
+import { createInterface } from "node:readline/promises";
+import YAML from "yaml";
 import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
 import { spawnSync as spawnSyncProc } from "node:child_process";
 import { parseEnvelopeText, scheduleScopeOf, listSchedules, describe as describeSchedule, addSchedule, updateSchedule, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
@@ -49,26 +51,22 @@ import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_
 import { capturedSelector } from "../lib/captured-selector.mjs";
 import { inspectCapturedPiOutcome } from "../lib/captured-pi-host.mjs";
 import { readCapturedResolution } from "../lib/captured-resolutions.mjs";
-import { readLock3 } from "../lib/portable-lock.mjs";
 import { oatsError } from "../lib/errors.mjs";
-import { readPortableBytes } from "../lib/portable-files.mjs";
-import { canonicalJson, parseStrictJson } from "../lib/portable-values.mjs";
+import { canonicalJson } from "../lib/portable-values.mjs";
 import { readPortablePreparationRequest } from "../lib/portable-onboarding-request.mjs";
 import { portableScope } from "../lib/portable-state.mjs";
 import { CAPTURED_OPERATION_TIMEOUT_MS, runCapturedOperationProcess } from "../lib/captured-operation-process.mjs";
 import { approveCapturedCapability } from "../lib/artifact-approvals.mjs";
-import { loadSetupExpertEdition, SETUP_EXPERT, SETUP_CAPABILITIES } from "../lib/setup-expert-source.mjs";
 import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
 import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
 const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
 import { readinessOf, policyOf } from "../lib/readiness.mjs";
 import { readEvents } from "../lib/instance-events.mjs";
-import { parsePortableSource } from "../lib/source-spec.mjs";
 
 const args = process.argv.slice(2);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
-const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "instance", "operation", "readiness", "soul", "launch-config", "experimental", "onboard", "init", "inject", "install", "list", "catalog", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
+const KERNEL_COMMANDS = new Set(["prepare", "capture", "capabilities", "create", "doctor", "inspect", "instance", "operation", "package", "readiness", "soul", "souls", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "type", "update", "version", "workspace"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
@@ -83,6 +81,7 @@ function valueFlag(name) {
   return value;
 }
 const die = (msg) => { console.error(`oats: ${msg}`); process.exit(1); };
+const cmdFail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
 /** Resolve the --dir flag with central validation: a value-taking flag given
  * no value (flag() → true) is E_BAD_ARGS inside the JSON boundary, never an
  * uncaught resolve(true) TypeError (reviewer-6f0a3bd). */
@@ -506,26 +505,6 @@ function scaffoldConfigName(dir) {
   return assertSafeConfigValue(basename(dir), `the scaffolded name from the directory basename ${JSON.stringify(basename(dir))}`);
 }
 
-function offerTmuxMouseScrolling() {
-  if (args.includes("--no-tmux-mouse")) return;
-  const configPath = tmuxConfigPath();
-  const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
-  if (tmuxMouseEnabled(current)) return;
-
-  let accepted = args.includes("--tmux-mouse");
-  if (!accepted) {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) return;
-    process.stdout.write("Enable normal mouse/trackpad scrolling in tmux agent windows? [Y/n] ");
-    const buffer = Buffer.alloc(256);
-    const length = readSync(process.stdin.fd, buffer, 0, buffer.length);
-    accepted = !buffer.subarray(0, length).toString("utf8").trim().toLowerCase().startsWith("n");
-  }
-  if (!accepted) return;
-
-  const result = enableTmuxMouse(configPath);
-  console.log(`Enabled tmux mouse scrolling in ${shortPath(result.configPath)}${result.reloaded ? " (reloaded)" : ""}`);
-}
-
 // ---------- doctor ----------
 /** Doctor must diagnose, not crash: a stale activation of a retired
  * capability fails config resolution — surface the cleanup instruction
@@ -560,31 +539,32 @@ function doctorComposition(ctx, soulName) {
   if (!agent) throw new Error(`unknown soul "${soulName}" for doctor composition`);
   return composeInstanceAgentsMd(join(agent._dir, "soul"), ctx, agent.name, agent.work || "checkout", agent.kind);
 }
-/** WS2 package-layer doctor data — the ONE source for both human and --json
- * doctor output: lock v2 packages, adopted-profile provenance, available-but-
- * unapplied profiles, and missing host requirements with structured plans. */
-/** Guided-upgrade readiness for the legacy official capabilities visible from a
- * scope (release contract §4): which legacy `marketplace:` locks exist, which
- * official package supplies each one, and whether this release's catalog can
- * map them all yet. `null` when there is no legacy official state at all. */
-function officialMigrationState(legacyLocks, { teamScope, ctx }) {
-  const capabilities = [];
-  for (const l of legacyLocks) {
-    for (const [id, entry] of Object.entries(l.capabilities || {})) {
-      if (typeof entry?.source !== "string" || !entry.source.startsWith("marketplace:")) continue;
-      let m;
-      try { m = officialCapabilityPackage(id); }
-      catch (e) { return { status: "unavailable", capabilities: [], command: null, reason: `the official package catalog is unreadable: ${e.message}` }; }
-      capabilities.push({ capability: id, package: m.package, via: m.via, available: m.available, file: l.file, level: l.level });
-    }
+
+/** Workspace-model v2 doctor data, OFFLINE: the deployment declaration found
+ * walking up from ctx (oats-local.yaml) and the lock v3 beside it. Doctor never
+ * goes to the network; membership and discovery are `oats sync` / `oats workspace status`. */
+function doctorLockData(ctx) {
+  const out = { local: null, localError: null, lockFile: null, packages: [], lockError: null };
+  let lockDir = ctx;
+  try {
+    const found = loadLocal(ctx);
+    out.local = { path: found.path, workspace: found.local.workspace };
+    lockDir = dirname(found.path);
+  } catch (e) {
+    if (e?.code === "E_WORKSPACE_SCHEMA") out.localError = { code: e.code, message: e.message };
+    else if (e?.code !== "E_LOCAL_MISSING") throw e;
+  }
+  const file = join(lockDir, LOCK_FILE);
+  if (!existsSync(file)) return out;
+  out.lockFile = file;
+  try {
+    const lock = readLock(lockDir);
+    out.packages = Object.entries(lock.packages).map(([id, p]) => ({ id, version: p.version, source: p.source, path: p.path, commit: p.commit, integrity: p.integrity, capabilities: p.capabilities, approved: p.approved }));
+  } catch (e) {
+    if (e?.code !== "E_LOCK_SCHEMA") throw e;
+    out.lockError = { code: e.code, message: e.message, file: e.details?.file ?? file };
   }
-  if (!capabilities.length) return null;
-  const boundary = teamScope || ctx;
-  const command = `oats migrate --official --recursive --dir ${shellQuote(boundary)}`;
-  const missing = capabilities.filter((c) => !c.available);
-  return missing.length
-    ? { status: "unavailable", capabilities, command: null, reason: `no official package mapping yet for ${missing.map((c) => c.capability).join(", ")} — this release keeps the legacy capabilities working; migration becomes available when the catalog publishes them` }
-    : { status: "ready", capabilities, command, reason: null };
+  return out;
 }
 
 /** The health of ONE materialized capability, against the rows it was projected
@@ -608,7 +588,7 @@ function hasExecutableSurface(manifest) {
 }
 function capabilityHealth(level, cap, capRow, pkgRow) {
   const dir = installedCapabilityDir(level, cap.id);
-  if (!cap.installed) return { status: "missing", code: "missing-capability-artifact", dir, detail: `capability ${cap.id} is locked but not materialized — run \`oats install\` to re-materialize it` };
+  if (!cap.installed) return { status: "missing", code: "missing-capability-artifact", dir, detail: `capability ${cap.id} is locked but not materialized — run \`oats sync\` to re-materialize it` };
   let integrity;
   try { integrity = capabilityArtifactIntegrity(dir); }
   catch (e) { return { status: "broken", code: e.code || "invalid-capability-artifact", dir, detail: `capability ${cap.id}: ${e.message}` }; }
@@ -622,113 +602,10 @@ function capabilityHealth(level, cap, capRow, pkgRow) {
     catch (e) { return { status: "provenance-mismatch", code: e.code || "invalid-lock", dir, integrity, detail: `capability ${cap.id}: ${e.message}` }; }
   }
   const executable = hasExecutableSurface(cap.manifest);
-  if (executable && !cap.trusted) return { status: "untrusted", code: "untrusted-surface", dir, integrity, detail: `capability ${cap.id}: executable surface UNTRUSTED — \`oats trust ${cap.id}\`` };
+  if (executable && !cap.trusted) return { status: "untrusted", code: "untrusted-surface", dir, integrity, detail: `capability ${cap.id}: executable surface UNTRUSTED — approve it in \`oats sync\`` };
   return { status: "ok", code: null, dir, integrity, detail: null };
 }
 
-function doctorPackagesData(ctx, chain, { teamScope } = {}) {
-  // reviewer-455ba15 fix 4: the ENGINE diagnostics the human doctor renders
-  // (invalid locks, missing artifacts, integrity/runtime-closure drift,
-  // capability-list mismatches, untrusted surfaces, legacy-lock states)
-  // are computed HERE so doctor --json exposes them structurally — machine
-  // consumers see every state the human report calls broken. Fail-closed
-  // reads are diagnosed, never consumed as data and never swallowed.
-  let pkgLocks = { packages: {}, legacy: [] };
-  let installedPkgs = [];
-  let lockBroken = null;
-  try { pkgLocks = readPackageLocks(ctx); installedPkgs = listInstalledPackages(ctx); }
-  catch (e) {
-    const prov = Array.isArray(e.provenance) ? e.provenance[0] : undefined;
-    lockBroken = { code: e.code || "invalid-lock", message: String(e.message || e), file: prov?.file || null, provenance: e.provenance || null };
-  }
-  const packages = [];
-  for (const p of installedPkgs) {
-    // SCOPE-EXACT, like `oats list` and `oats trust` above: `p` was derived from
-    // the lock AT `p.level`, and its artifacts live under that scope, so only
-    // that scope's rows can judge them. The MERGED maps resolve each identity
-    // closest-scope-first — right for "which capability is active here", wrong
-    // here — so a chain holding one package id at two scopes (a direct
-    // acquisition outside, the same id pulled in by a dependency closure
-    // inside, each with its own source spelling) would compare an outer
-    // artifact's provenance against the inner row it was never projected from
-    // and report a self-consistent pair as invalid-lock.
-    const rows = levelRows(pkgLocks, p.level);
-    const lock = Object.hasOwn(rows.packages, p.package) ? { ...rows.packages[p.package], _file: join(p.level, OATS_LOCK_FILE), _level: p.level } : undefined;
-    const problems = [];
-    if (!lock) problems.push({ code: "invalid-lock", detail: "installed but not locked — reacquire it" });
-    else {
-      // There is no persistent package root to hash: the package row exact-locks
-      // a remote payload, and the only bytes on disk are the flat capability
-      // artifacts. So every health check is per capability, against the artifact
-      // integrity the engine recorded for it.
-      for (const c of p.capabilities) {
-        const h = capabilityHealth(p.level, c, Object.hasOwn(rows.capabilities, c.id) ? rows.capabilities[c.id] : undefined, lock);
-        if (h.status !== "ok") problems.push({ code: h.code, detail: h.detail });
-      }
-    }
-    packages.push({
-      id: p.package, version: p.version || null, level: p.level, source: lock?.source || null,
-      path: lock?.path || null, commit: lock?.commit || null, capabilities: p.capabilities.map((c) => c.id),
-      dependencies: lock?.dependencies || [],
-      status: problems.length ? "broken" : "ok", problems,
-    });
-  }
-  for (const [id, lock] of Object.entries(pkgLocks.packages)) {
-    if (!installedPkgs.some((p) => p.package === id)) {
-      // Capability rows carry the provider back-reference — the package row has
-      // no capability list to read any more.
-      const provided = Object.entries(pkgLocks.capabilities).filter(([, c]) => c.package === id).map(([capId]) => capId);
-      packages.push({ id, version: lock.version || null, level: lock._level, source: lock.source || null, path: lock.path || null, commit: lock.commit || null, capabilities: provided, dependencies: lock.dependencies || [], status: "broken", problems: [{ code: "missing-locked-package", detail: `locked in ${lock._file} but not installed — run oats install` }] });
-    }
-  }
-  // Supported v1 scopes — empty or not — are pending an explicit LOCK-FORMAT
-  // migration (maintainer ruling). There is no second view beside this one:
-  // migration never produces residue, and the superseded transitional v2 shape
-  // is rejected wholesale by the strict reader, so it reaches doctor as the
-  // single `lockError` diagnosis above rather than as partially parsed entries.
-  const legacyLockFiles = pkgLocks.legacy
-    .map((l) => ({ file: l.file, level: l.level, lockfileVersion: l.lockfileVersion ?? 1, empty: !Object.keys(l.capabilities || {}).length, status: "pending-format-migration", action: `oats migrate --dir ${l.level}` }));
-  // Adoption provenance now comes from the visible, commit-safe adopted base —
-  // not from a provenance comment the local config could lose to an edit.
-  const adoptedTemplates = [];
-  for (const cfg of chain) {
-    const level = dirname(cfg._file);
-    let adopted;
-    try { adopted = readAdoptedTemplate(level); }
-    catch (e) { adoptedTemplates.push({ level, file: cfg._file, status: "broken", code: e.code || "E_ADOPTION_INVALID", detail: e.message }); continue; }
-    if (!adopted) continue;
-    let localChanges = null;
-    try { localChanges = readFileSync(cfg._file, "utf8") !== adopted.baseText; } catch { /* unreadable config is reported elsewhere */ }
-    adoptedTemplates.push({
-      level, file: cfg._file, package: adopted.package, template: adopted.template,
-      base: adopted.baseFile, source: adopted.metadata?.source || null,
-      version: adopted.metadata?.version || null, commit: adopted.metadata?.commit || null,
-      hash: adopted.metadata?.hash || null, localChanges, status: "ok",
-    });
-  }
-  // NOTE: doctor deliberately does NOT enumerate templates a package exports but
-  // nobody adopted. In the materialized model there is no package root on disk,
-  // so that list only exists behind a network fetch of the locked source — and
-  // a diagnostic command must never go to the network to render a hint.
-  const missingHostRequirements = aggregateMissingRequirements([ctx]).map((req) => ({
-    command: req.command, why: req.why || null, docs: req.docs || null,
-    requestedBy: req.requestedBy,
-    plan: req.plan && !req.plan.unavailable
-      ? { manager: req.plan.manager, argv: req.plan.argv, steps: req.plan.steps || [req.plan.argv], source: req.plan.source, version: req.plan.version || null, scope: req.plan.scope }
-      : null,
-    invalid: req.invalid || null,
-    conflict: req.conflict || null,
-    unavailable: req.plan?.unavailable || null,
-    // Context-complete + shell-safe: the copyable command pins the resolved
-    // scope with --dir so it cannot target another deployment from a
-    // different cwd. Command and ctx are validated/quoted for safe copying.
-    consentCommand: req.plan && !req.plan.unavailable && !req.invalid && !req.conflict
-      ? `oats install --accept-requirement ${req.command} --dir ${shellQuote(ctx)}`
-      : null,
-  }));
-  return { lockError: lockBroken, packages, legacyLockFiles, adoptedTemplates, missingHostRequirements, officialMigration: officialMigrationState(pkgLocks.legacy, { teamScope, ctx }) };
-}
-
 // ---------- inspect: one authoritative answer for GUIs ----------
 /** Souls, capabilities (installed state and health, separately from
  *  activation), effective layer bindings and declared operations for a
@@ -937,7 +814,7 @@ function computeInspect({ onFail } = {}) {
   // Capabilities: installed state and health from the package engine (exactly
   // what `oats list` reports), owned/path manifests beside them, and the
   // ACTIVATION for the selected soul (or global) from the resolver.
-  const mans = capabilityManifests(ctx);
+  const mans = capabilityManifests(manifestSource(meta, home, ctx));
   let lockError = null;
   const byId = new Map();
   try {
@@ -998,7 +875,7 @@ function computeInspect({ onFail } = {}) {
     const operations = manifestOperations(m).map((op) => {
       let reason = null;
       if (!active) reason = disabledLayer ? `layer ${entry.layer} is disabled${disabledLayer.level ? ` at ${disabledLayer.level}` : " for this home"}` : `${entry.id} is not activated for ${meta ? `home ${basename(home)}` : soulName ? `soul ${soulName}` : "this scope"}`;
-      else if (!entry.health.trusted) reason = `${entry.id} executable surface is not trusted (oats trust ${entry.id})`;
+      else if (!entry.health.trusted) reason = `${entry.id} executable surface is not trusted (approve it in oats sync)`;
       else if (entry.health.status !== "ok") reason = entry.health.detail || entry.health.status;
       else if (missingRequires.length) reason = `${entry.id} requires ${missingRequires.map((x) => `"${x.command}" on PATH${x.why ? ` (${x.why})` : ""}`).join(", ")}`;
       else if (op.context === "home" && !home) reason = "needs a running home (--home)";
@@ -1201,7 +1078,7 @@ function operationCmd() {
   }
   // Provider resolution: the snapshot's active capabilities for a home, the
   // config for a soul/scope.
-  const mans = capabilityManifests(ctx);
+  const mans = capabilityManifests(manifestSource(meta, home, ctx));
   let provider, settings, team, disabled = null;
   if (meta) {
     const ids = (meta.capabilities || []).map((c) => c.id);
@@ -1222,7 +1099,7 @@ function operationCmd() {
   const op = manifestOperations(provider).find((o) => o.name === opName);
   if (!op) bail("E_OPERATION_UNKNOWN", `${provider.capability} declares no operation ${JSON.stringify(opName)} (declared: ${manifestOperations(provider).map((o) => o.name).join(", ") || "none"})`);
   const trust = capabilityTrust(provider, ctx);
-  if (!trust.trusted) bail("E_CAPABILITY_BLOCKED", `${provider.capability} executable surface is blocked: ${trust.reason || "not trusted"} (oats trust ${provider.capability})`);
+  if (!trust.trusted) bail("E_CAPABILITY_BLOCKED", `${provider.capability} executable surface is blocked: ${trust.reason || "not trusted"} (approve it in oats sync)`);
   const missingReq = capabilityMissingRequires(provider.capability, ctx);
   if (missingReq.length) bail("E_CAPABILITY_REQUIRES", `${provider.capability} requires ${missingReq.map((m) => `"${m.command}" on PATH${m.why ? ` (${m.why})` : ""}${m.install ? ` [install: ${m.install}]` : ""}`).join(", ")}; ${address} was not run`);
   if (op.context === "home" && !meta) bail("E_OPERATION_UNAVAILABLE", `${address} runs in an instance home; pass --home <abs>`);
@@ -1347,11 +1224,14 @@ async function soulCmd() {
 function doctorJson(dir) {
   const ctx = resolve(dir || process.cwd());
   const soulName = flag("soul");
+  const ws = doctorLockData(ctx);
+  // A v2 deployment (oats-local.yaml found walking up) has NO config chain, layers,
+  // acquired packages or installed tier: those keys are omitted, not emitted empty.
+  if (ws.local) { console.log(JSON.stringify(doctorWorkspaceJson(ctx, soulName, ws), null, 2)); return; }
   const r = resolveForDoctor(ctx, soulName, { json: true });
   const mans = capabilityManifests(ctx);
   const composition = doctorComposition(ctx, soulName);
   const chain = configChain(ctx);
-  const pkg = doctorPackagesData(ctx, chain, { teamScope: r.team?.scope });
   const oasScopes = detectOasScopes(ctx);
   console.log(JSON.stringify({
     schemaVersion: 1,
@@ -1377,34 +1257,77 @@ retiredLocks: (() => { try { return Object.entries(readCapabilityLocks(ctx)); }
     retiredArtifacts: Object.entries(mans)
       .filter(([id]) => retiredCapabilityReason(id))
       .map(([id, m]) => ({ id, dir: m._dir, origin: m._origin, reason: retiredCapabilityReason(id) })),
-    // Shared WS2+engine package payload (fix 4: human and JSON doctor derive
-    // from ONE computation; fail-closed reads are diagnosed via lockError —
-    // doctorPackagesData carries the engine's legacy-lock shapes).
-    packages: pkg.packages,
-    lockError: pkg.lockError,
-    legacyLockFiles: pkg.legacyLockFiles,
-    officialMigration: pkg.officialMigration,
-    adoptedTemplates: pkg.adoptedTemplates,
-    missingHostRequirements: pkg.missingHostRequirements,
+    // Workspace model v2 (offline view): the lock (v3) and the deployment
+    // declaration. Human and JSON doctor derive from ONE computation; a
+    // fail-closed lock read is diagnosed via lockError, never consumed as data.
+    workspace: ws.local ? { file: ws.local.path, ref: ws.local.workspace } : null,
+    workspaceError: ws.localError,
+    lockFile: ws.lockFile,
+    packages: ws.packages,
+    lockError: ws.lockError,
     composedInstructions: composition?.text,
     instructionBlocks: composition?.blocks,
   }, null, 2));
 }
 
+/** The v2 doctor payload: the deployment declaration + lock (offline) and, with
+ *  --soul, the composed instructions. No v1 keys (chain/layers/acquired/injects…). */
+function doctorWorkspaceJson(ctx, soulName, ws) {
+  const composition = doctorComposition(ctx, soulName);
+  return {
+    schemaVersion: 1, workspaceApi: 2, context: ctx,
+    workspace: { file: ws.local.path, ref: ws.local.workspace },
+    workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
+    information: operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : [],
+    composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
+  };
+}
+/** Kernel/bridge version skew (published in lockstep from one tag). */
+function doctorVersionSkew() {
+  const piPkgFile = join(homedir(), ".pi", "agent", "npm", "node_modules", "@awebai", "oats-pi", "package.json");
+  if (!existsSync(piPkgFile)) return;
+  const bridge = JSON.parse(readFileSync(piPkgFile, "utf8")).version;
+  if (bridge !== OATS_VERSION) console.log(`WARNING: version skew — kernel ${OATS_VERSION}, pi bridge ${bridge}; run \`oats update\` (they publish in lockstep)\n`);
+}
+/** The "Workspace (v2, offline view)" + "Locked packages" sections, shared by both doctor shapes. */
+function printDoctorWorkspace(ws) {
+  console.log("\nWorkspace (v2, offline view):");
+  if (ws.local) console.log(`  oats-local.yaml  ${shortPath(ws.local.path)}  → workspace ${ws.local.workspace}`);
+  else if (ws.localError) console.log(`  ERROR: ${ws.localError.message} [${ws.localError.code}]`);
+  else console.log("  (no oats-local.yaml found walking up — this scope realizes no v2 workspace; run `oats sync` from one that does)");
+  console.log("\nLocked packages (oats-lock.json v3):");
+  if (ws.lockError) {
+    console.log(`  ERROR: ${ws.lockError.message} [${ws.lockError.code}]`);
+    if (ws.lockError.file) console.log(`         the lock is never auto-repaired; delete ${shortPath(ws.lockError.file)} and run \`oats sync\``);
+  } else if (!ws.packages.length) console.log(ws.lockFile ? "  (none)" : "  (no lock yet — run `oats sync`)");
+  for (const p of ws.packages) {
+    console.log(`  ${p.id} ${p.version}  ${p.source}  @ ${p.commit.slice(0, 12)}  ${p.approved ? `approved ${p.approved.at}` : "APPROVAL NEEDED (oats sync)"}`);
+    if (p.capabilities.length) console.log(`             capabilities: ${p.capabilities.join(", ")}`);
+  }
+  console.log("  membership, discovery and drift need the remotes: `oats workspace status`, `oats sync`.");
+}
 function doctor(dir) {
   const ctx = resolve(dir || process.cwd());
   const soulName = flag("soul");
+  const ws = doctorLockData(ctx);
+  console.log(`oats doctor — resolved from ${shortPath(ctx)}\n`);
+  doctorVersionSkew();
+  if (ws.local) {
+    // A v2 deployment: nothing is installed and there is no config chain — the v1
+    // sections (Config chain / Layers / Kernel injection / Acquired packages / lock
+    // warnings) would describe a tier this deployment does not have.
+    const composition = doctorComposition(ctx, soulName);
+    printDoctorWorkspace(ws);
+    if (soulName) {
+      const information = operationalKnowledgeNote(composition, soulName);
+      if (information) console.log(`\nINFO: ${information}`);
+      console.log(`\nFinal composed AGENTS.md for ${soulName}:\n\n${composition.text}`);
+    } else console.log("\nPass --soul <name> to inspect final composed AGENTS.md.");
+    return;
+  }
   const chain = configChain(ctx);
   const r = resolveForDoctor(ctx, soulName);
   const composition = doctorComposition(ctx, soulName);
-  console.log(`oats doctor — resolved from ${shortPath(ctx)}\n`);
-
-  // Kernel/bridge version skew (published in lockstep from one tag).
-  const piPkgFile = join(homedir(), ".pi", "agent", "npm", "node_modules", "@awebai", "oats-pi", "package.json");
-  if (existsSync(piPkgFile)) {
-    const bridge = JSON.parse(readFileSync(piPkgFile, "utf8")).version;
-    if (bridge !== OATS_VERSION) console.log(`WARNING: version skew — kernel ${OATS_VERSION}, pi bridge ${bridge}; run \`oats update\` (they publish in lockstep)\n`);
-  }
 
   console.log("Config chain (closest first):");
   if (chain.length === 0) console.log("  (none — no oats-config.yaml found walking up)");
@@ -1485,7 +1408,7 @@ function doctor(dir) {
   for (const [id, lock] of Object.entries(locks)) {
     const retiredReason = retiredCapabilityReason(id);
     if (retiredReason) { console.log(`  WARNING: ${id} is locked in ${shortPath(lock._file)} but ${retiredReason}`); continue; }
-    if (!mans[id]) console.log(`  WARNING: ${id} is locked in ${shortPath(lock._file)} but not acquired — run \`oats install\``);
+    if (!mans[id]) console.log(`  WARNING: ${id} is locked in ${shortPath(lock._file)} but not acquired — run \`oats sync\``);
   }
   for (const [id, m] of Object.entries(mans)) {
     if (!String(m._origin).startsWith("installed:")) continue;
@@ -1500,54 +1423,10 @@ function doctor(dir) {
   }
   if (existsSync(LEGACY_HOME_CAPABILITIES_DIR)) console.log(`  WARNING: legacy ~/.oats/capabilities exists and is no longer discovered — reinstall its packages at a config scope and remove it`);
 
-  // Distribution packages: package failures are distinguished from capability
-  // failures. Doctor is the DIAGNOSIS surface — human and JSON render the SAME
-  // doctorPackagesData computation (reviewer-455ba15 fix 4); fail-closed
-  // invalid-lock raises are diagnosed here, never consumed as data.
-  console.log("\nInstalled packages:");
-  const pkg = doctorPackagesData(ctx, chain, { teamScope: r.team?.scope });
-  if (pkg.lockError) {
-    console.log(`  ERROR: ${pkg.lockError.message} [${pkg.lockError.code}]`);
-    if (pkg.lockError.file) console.log(`         fix or remove the offending entry in ${shortPath(pkg.lockError.file)} — the lock is never auto-repaired; package operations fail closed until it is valid`);
-  }
-  if (!pkg.lockError && !pkg.packages.length && !pkg.legacyLockFiles.length) console.log("  (none)");
-  for (const p of pkg.packages) {
-    console.log(`  ${p.id}@${p.version}  [${levelOf(p.level)} ${shortPath(p.level)}]`);
-    for (const prob of p.problems) {
-      if (prob.code === "untrusted-surface") console.log(`             ${prob.detail}`);
-      else console.log(`             ERROR: ${prob.detail} [${prob.code}]`);
-    }
-  }
-  for (const l of pkg.legacyLockFiles) {
-    if (l.empty) console.log(`  WARNING: ${shortPath(l.file)} is an empty lockfileVersion ${l.lockfileVersion} file — pending lock-format migration: run \`oats migrate --dir ${shortPath(l.level)}\` (converts to canonical v2)`);
-    else console.log(`  WARNING: ${shortPath(l.file)} is lockfileVersion ${l.lockfileVersion} — \`oats migrate\` maps its capability locks to packages`);
-  }
-  if (pkg.officialMigration) {
-    const om = pkg.officialMigration;
-    console.log(`\nOfficial capability migration (0.18 bundled capabilities → official packages):`);
-    for (const c of om.capabilities) {
-      console.log(`  ${c.capability} → package ${c.package}${c.via === "alias" ? " (catalog alias)" : ""}  ${c.available ? "[mapped]" : "[no catalog mapping yet]"}  [${shortPath(c.level)}]`);
-    }
-    if (om.status === "ready") console.log(`  READY: migrate with \`${om.command}\` (plan it first with --dry-run; approvals are re-earned afterwards)`);
-    else console.log(`  NOT YET AVAILABLE: ${om.reason}`);
-  }
-  for (const a of pkg.adoptedTemplates) {
-    if (a.status === "broken") {
-      console.log(`\nAdopted config template: BROKEN at ${shortPath(a.level)} — ${a.detail}`);
-      continue;
-    }
-    const drift = a.localChanges === null ? "" : a.localChanges ? " — local edits present (`oats config diff`)" : " — no local edits yet";
-    console.log(`\nAdopted config template: ${shortPath(a.file)} adopted ${a.package}:${a.template}${a.version ? `@${a.version}` : ""}${drift}`);
-    console.log(`  recorded base ${shortPath(a.base)} (commit it — \`oats config sync\` compares against it; package updates never rewrite your config)`);
-  }
-  if (pkg.missingHostRequirements.length) {
-    console.log("\nMissing host commands (active capabilities):");
-    for (const req of pkg.missingHostRequirements) {
-      console.log(`  ${req.command} — ${req.why || "required"} (requested by: ${req.requestedBy.map((r) => r.capability).join(", ")})`);
-      if (req.plan) console.log(`             install with consent: ${req.consentCommand}  (runs: ${req.plan.argv.join(" ")})`);
-      else if (req.docs) console.log(`             install docs: ${req.docs}`);
-    }
-  }
+  // Workspace model v2: nothing is installed. Doctor reports the lock (v3) and
+  // the deployment declaration OFFLINE — membership, discovery and package
+  // resolution go to the remotes and belong to `oats sync` / `oats workspace status`.
+  printDoctorWorkspace(ws);
 
   if (soulName) {
     const information = operationalKnowledgeNote(composition, soulName);
@@ -1557,86 +1436,6 @@ function doctor(dir) {
 }
 
 // ---------- config editing (structural: parse → mutate → re-serialize the capabilities block) ----------
-function originToFrom(origin) {
-  const o = String(origin || "");
-  if (o.startsWith("installed:")) return "installed";
-  if (o.startsWith("owned:")) return "owned";
-  if (o.startsWith("path:")) return undefined; // path declarations stay hand-authored
-  return undefined;
-}
-
-function serializeBinding(value, indent) {
-  if (value === true || value === false) return ` ${value}`;
-  const lines = [""];
-  if (value.enabled !== undefined) lines.push(`${indent}enabled: ${value.enabled}`);
-  if (value.settings && Object.keys(value.settings).length) {
-    lines.push(`${indent}settings:`);
-    for (const [k, v] of Object.entries(value.settings)) lines.push(`${indent}  ${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`);
-  }
-  return lines.join("\n");
-}
-
-/** Serialize one capability entry map at the given base indent, with the conventional injection comment. */
-function serializeCapabilityEntry(id, entry, baseIndent) {
-  const i = baseIndent;
-  const lines = [];
-  if (entry.capability) lines.push(`${i}capability: ${entry.capability}`);
-  if (entry.from) lines.push(`${i}from: ${entry.from}`);
-  if (entry.global !== undefined) lines.push(`${i}global:${serializeBinding(entry.global, i + "  ")}`);
-  const types = entry["agent-types"];
-  if (types && Object.keys(types).length) {
-    lines.push(`${i}agent-types:`);
-    for (const [t, v] of Object.entries(types)) lines.push(`${i}  ${t}:${serializeBinding(v, i + "    ")}`);
-  }
-  if (entry.souls && Object.keys(entry.souls).length) {
-    lines.push(`${i}souls:`);
-    for (const [s, v] of Object.entries(entry.souls)) lines.push(`${i}  ${s}:${serializeBinding(v, i + "    ")}`);
-  }
-  if (entry.settings && Object.keys(entry.settings).length) {
-    lines.push(`${i}settings:`);
-    for (const [k, v] of Object.entries(entry.settings)) lines.push(`${i}  ${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`);
-  }
-  if (entry["injection-override"] !== undefined) lines.push(`${i}injection-override: ${entry["injection-override"]}`);
-  else if (entry.from === "owned" || String(entry.from || "").startsWith("path:"))
-    lines.push(`${i}# injection edited at source: .agents/capabilities/owned/${id}/injects/`);
-  else lines.push(`${i}# injection-override: .agents/injections/capabilities/${id}.md`);
-  return lines;
-}
-
-/** Re-serialize the whole `capabilities:` block from its parsed model. */
-function serializeCapabilities(caps) {
-  const lines = ["capabilities:", "  # Fundamental layers — exclusive slots; a capability entry or an explicit none.", "  layers:"];
-  for (const layer of LAYERS) {
-    const entry = caps.layers?.[layer];
-    if (entry === undefined) continue;
-    if (entry === "none") { lines.push(`    ${layer}: none`); continue; }
-    lines.push(`    ${layer}:`);
-    lines.push(...serializeCapabilityEntry(entry.capability, entry, "      "));
-  }
-  const additive = Object.entries(caps.additive || {});
-  if (additive.length) {
-    lines.push("  additive:");
-    for (const [id, entry] of additive) {
-      lines.push(`    ${id}:`);
-      lines.push(...serializeCapabilityEntry(id, entry, "      "));
-    }
-  }
-  return lines.join("\n") + "\n";
-}
-
-/** Replace (or append) the top-level capabilities: block in config text. */
-function replaceCapabilitiesBlock(text, caps) {
-  const serialized = serializeCapabilities(caps);
-  const lines = text.replace(/\n*$/, "\n").split("\n");
-  const start = lines.findIndex((l) => /^capabilities:\s*(#.*)?$/.test(l));
-  if (start < 0) return text.replace(/\n*$/, "\n\n") + serialized;
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^[^\s#]/.test(lines[i])) { end = i; break; }
-    if (/^#/.test(lines[i]) && i + 1 < lines.length && /^[^\s]/.test(lines[i + 1] || "")) { end = i; break; }
-  }
-  return [...lines.slice(0, start), ...serialized.replace(/\n$/, "").split("\n"), "", ...lines.slice(end)].join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "\n");
-}
 /** Replace (or append, or drop with "") the top-level launch-configs block:
  *  the span from its key line (bare, quoted, or the inline `launch-configs: {...}`
  *  form) to the next top-level line is replaced; every byte before and after
@@ -1887,2248 +1686,570 @@ async function launchConfigCmd() {
 }
 
 
-/** Load the parsed capabilities model of a config file ({layers:{}, additive:{}}). */
-function readCapabilitiesModel(file) {
-  if (!existsSync(file)) return { layers: {}, additive: {} };
-  const cfg = withConfigFile(file, () => parseYamlNested(readFileSync(file, "utf8")));
-  const caps = cfg.capabilities || {};
-  return { layers: { ...(caps.layers || {}) }, additive: { ...(caps.additive || {}) } };
-}
-
-// ---------- use / activation ----------
-function use() {
-  const requested = args[1];
-  if (!requested || requested.startsWith("--")) cmdFail("E_USAGE", "usage: oats use <capability|none> [--global|--type <agent-type>|--soul <name>] [--disable|--inherit] [--layer <name>] [--settings k=v [k2=v2 ...]] [--dir <dir>] [--json]");
-  const dir = dirFlag();
-  const level = levelOf(dir);
-  const file = join(dir, "oats-config.yaml");
-  const layer = flag("layer");
-  if (layer && !LAYERS.includes(layer)) cmdFail("E_BAD_ARGS", `--layer must be one of: ${LAYERS.join(", ")}`);
-  const inherit = args.includes("--inherit");
-  if (inherit && args.includes("--disable")) cmdFail("E_BAD_ARGS", "choose --inherit (remove this level's binding) or --disable (explicit exclusion), not both");
-  let text = existsSync(file) ? readFileSync(file, "utf8") : `name: ${scaffoldConfigName(dir)}\n`;
-  const caps = readCapabilitiesModel(file);
-  // The receipt names what this level said before and after, and what is
-  // effective afterwards, so a GUI never has to re-read the file to know.
-  const effectiveAfter = (soulName, layerName, capId) => {
+/** `oats instance <git|diff> <instance>` — K1: read-only Git observation of one
+ *  instance's work tree. The instance is addressed qualified: an explicit
+ *  --home, or a name under the --dir scope (team roots included) that resolves
+ *  to exactly one home; several homes refuse with every candidate named. */
+function instanceCmd() {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  const sub = args[1], name = args[2];
+  const usage = "usage: oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json]";
+  if (!["git", "diff", "stop", "events"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
+  dropAmbientRoot();
+  if (sub === "events") {
+    // K7: typed producer events, bounded window; nothing inferred.
+    const homeOpt = flag("home"); if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+    let root; try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
+    const limit = flag("limit"); const since = flag("since");
+    if (limit === true || since === true) return bail("E_BAD_ARGS", usage);
     try {
-      const r = resolveOatsConfig(dir, soulName);
-      if (layerName) return { layer: layerName, id: r.layers[layerName]?.id || null, provenance: r.provenance[layerName] || null, disabled: !!r.layerDisabled?.[layerName] };
-      const c = r.capabilities.find((x) => x.id === capId);
-      return { capability: capId, enabled: !!c, provenance: c?.provenance || [], settings: c?.settings || {} };
-    } catch (e) { return { error: e.message }; }
-  };
-  const answer = (receipt, line) => { if (JSON_MODE) jsonOk(receipt); else console.log(line); };
-  if (requested === "none") {
-    if (!layer) cmdFail("E_BAD_ARGS", "oats use none requires --layer <name>");
-    // A layer `none` is a LEVEL statement; there is no per-soul or per-type
-    // none, so a target here must be refused, never silently widened.
-    if (flag("soul") !== undefined || flag("type") !== undefined) cmdFail("E_BAD_ARGS", `oats use none --layer ${layer} disables the layer for this whole level; it takes no --soul or --type (exclude one capability for a soul with oats use <capability> --soul <name> --disable)`);
-    const before = caps.layers[layer] === "none" ? "none" : caps.layers[layer] ? caps.layers[layer].capability : null;
-    if (inherit) {
-      if (caps.layers[layer] !== "none") cmdFail("E_NOT_BOUND", `layer ${layer} is not explicitly none at ${level} level (${shortPath(file)}); nothing to inherit from`);
-      delete caps.layers[layer];
-      writeFileSync(file, replaceCapabilitiesBlock(text, caps));
-      answer({ capability: null, action: "inherit", target: "layer", layer, level, file, before: { layer: before }, after: { layer: null, effective: effectiveAfter(undefined, layer) } }, `Layer ${layer} at ${level} level now inherits (${shortPath(file)})`);
+      const { resolveInstance } = await_import_lifecycle();
+      // K7b: --home is an ADDRESS claim, checked like K1 — it must be a home of
+      // exactly this name under the scope (E_HOME_MISMATCH otherwise).
+      const home = resolveInstance(dirFlag(), root, name, homeOpt ? { home: homeOpt } : {}).home;
+      const ev = readEvents(home, { ...(limit !== undefined ? { limit: Math.max(1, Math.min(2000, Number(limit) || 200)) } : {}), ...(since ? { since } : {}) });
+      if (JSON_MODE) { jsonOk(ev); return; }
+      console.log(`${ev.instance}: ${ev.returned} of ${ev.count} event(s)${ev.truncated ? " (window truncated)" : ""}${ev.waitingOnYou ? ` — waiting on you since ${ev.waitingOnYou.since} (${ev.waitingOnYou.producer})` : ""}`);
+      for (const e of ev.events) console.log(`  ${e.at ?? "?"}  ${e.kind.padEnd(20)} ${e.producer}${e.data ? `  ${JSON.stringify(e.data).slice(0, 120)}` : ""}`);
       return;
-    }
-    caps.layers[layer] = "none";
-    writeFileSync(file, replaceCapabilitiesBlock(text, caps));
-    answer({ capability: null, action: "layer-none", target: "layer", layer, level, file, before: { layer: before }, after: { layer: "none", effective: effectiveAfter(undefined, layer) } }, `Disabled fundamental layer ${layer} at ${level} level (${shortPath(file)})`);
-    return;
+    } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
   }
-  const manifest = capabilityManifest(requested, dir);
-  if (!manifest) {
-    // A scope with NO oats-config.yaml anywhere in its chain is not a config
-    // level, so `capabilityManifests` — which walks the chain — never opens this
-    // scope's installed store: a capability acquired and locked right here would
-    // otherwise be reported as never acquired. Diagnose the missing chain
-    // instead. `oats use` still writes nothing: authoring an adopter's first
-    // config is `oats init`'s job, and guessing it here would be policy.
-    if (!configChain(dir).length && ownScopeCapabilityManifest(dir, requested)) {
-      // The remedy is `--raw` on purpose: it is offline, deterministic, and
-      // writes only the minimal config this scope is missing. It never names
-      // `--package <pkg>` — that arm read the provider out of the MERGED lock
-      // chain while this gate reads own-scope only, and it dead-ends whenever
-      // the provider exports no config template. Both scope mentions use the
-      // same rendering, so the printed command is copyable verbatim.
-      cmdFail("E_NO_CONFIG", `capability "${requested}" is present in the capability store at ${shellQuote(dir)}, but there is no oats-config.yaml at this scope or any level above it — \`oats use\` activates into a config file and this scope has none. Create the minimal one with \`oats init --raw --dir ${shellQuote(dir)}\`, then re-run \`oats use ${requested}\`.`);
+  if (sub === "stop") {
+    // K3: plan → apply. The plan is what a confirmation shows; apply carries
+    // its revision back and refuses if reality moved.
+    const homeOpt = flag("home");
+    if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+    let root; try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
+    const recursive = !args.includes("--no-recursive");
+    const wantPlan = args.includes("--plan"), wantApply = args.includes("--apply");
+    if (wantPlan === wantApply) return bail("E_BAD_ARGS", "stop needs exactly one of --plan or --apply");
+    try {
+      if (wantPlan) {
+        const plan = planStop(dirFlag(), root, name, { home: homeOpt, recursive });
+        if (JSON_MODE) { jsonOk(plan); return; }
+        console.log(`stop ${name}${recursive ? " (and recorded children)" : ""} — plan ${plan.planRevision}`);
+        for (const t of plan.targets) console.log(`  ${"  ".repeat(t.depth)}${t.instance}: session ${t.session.state}${t.work.observed ? `, ${t.work.changed} changed / ${t.work.untracked} untracked on ${t.work.branch ?? "detached"}` : ", work not observed"}${t.midTask === true ? " — mid-task" : t.midTask === "unknown" ? " — activity unknown" : ""}`);
+        for (const n of plan.notes) console.log(`  note: ${n}`);
+        console.log(`apply with: oats instance stop ${name} --apply --plan-revision ${plan.planRevision} --idempotency-key <key>`);
+        return;
+      }
+      const rev = flag("plan-revision"), key = flag("idempotency-key"), grace = flag("grace-ms");
+      if (rev === true || key === true || grace === true) return bail("E_BAD_ARGS", usage);
+      const receipt = applyStop(dirFlag(), root, name, { home: homeOpt, recursive, planRevision: rev, idempotencyKey: key, ...(grace !== undefined ? { graceMs: Number(grace) } : {}) });
+      if (JSON_MODE) { jsonOk(receipt); return; }
+      for (const r of receipt.results) console.log(`  ${r.instance}: ${r.ok ? (r.stopped ? "stopped" : `already ${r.state}`) : `${r.code} — ${r.message}`}`);
+      console.log(receipt.ok ? `stopped${receipt.replayed ? " (replayed receipt)" : ""}; home, work, transcript and launch configuration retained — restart with \`oats session restart\`` : "some targets are still running; nothing was escalated");
+      if (!receipt.ok) process.exit(1);
       return;
-    }
-    cmdFail("E_UNKNOWN_CAPABILITY", `unknown capability "${requested}" (acquired: ${Object.keys(capabilityManifests(dir)).join(", ") || "none"}) — acquire it with \`oats install ${requested}\` (marketplace: ${Object.keys(marketplaceCapabilities()).join(", ")})`);
-  }
-  if (layer && manifest.layer !== layer) cmdFail("E_LAYER_MISMATCH", `capability "${manifest.capability}" declares layer "${manifest.layer || "none"}", not "${layer}"`);
-  const targets = [["agent-types", flag("type")], ["souls", flag("soul")]].filter(([, value]) => value);
-  if (args.includes("--global")) targets.push(["global", undefined]);
-  if (targets.length > 1) cmdFail("E_BAD_ARGS", "choose exactly one of --global, --type, or --soul");
-  const [targetKind, targetName] = targets[0] || ["global", undefined];
-  const targetLabel = targetKind === "global" ? "global" : `${targetKind === "agent-types" ? "type" : "soul"}:${targetName}`;
-  const soulForEffective = targetKind === "souls" ? targetName : undefined;
-  const enabled = !args.includes("--disable");
-  const bindingOf = (e) => (!e ? undefined : targetKind === "global" ? e.global : e[targetKind]?.[targetName]);
-  const stateOf = (e) => ({ bound: bindingOf(e) !== undefined, enabled: bindingOf(e) === undefined ? null : (typeof bindingOf(e) === "object" ? bindingOf(e).enabled !== false : !!bindingOf(e)), settings: e?.settings && typeof e.settings === "object" ? { ...e.settings } : {} });
-  // --inherit removes THIS level's binding for the addressed target (and the
-  // whole entry once no target is left), so outer scopes and targets apply
-  // again. Distinct from --disable, which writes an explicit exclusion.
-  if (inherit) {
-    const existing = manifest.layer ? caps.layers[manifest.layer] : caps.additive[manifest.capability];
-    const entry0 = existing && existing !== "none" && (!manifest.layer || existing.capability === manifest.capability) ? existing : undefined;
-    const before = stateOf(entry0);
-    if (!entry0 || !before.bound) cmdFail("E_NOT_BOUND", `${manifest.capability} has no ${targetLabel} binding at ${level} level (${shortPath(file)}); nothing to inherit from`);
-    // Only the addressed target goes. Every other binding the entry carries
-    // (an explicit global, other souls, types) is policy this command cannot
-    // tell from intent, so it stays; the receipt names what still applies.
-    if (targetKind === "global") delete entry0.global;
-    else { delete entry0[targetKind][targetName]; if (!Object.keys(entry0[targetKind]).length) delete entry0[targetKind]; }
-    const remaining = [...(entry0.global !== undefined ? [`global: ${entry0.global}`] : []), ...Object.entries(entry0["agent-types"] || {}).map(([t, v]) => `type:${t}: ${JSON.stringify(v)}`), ...Object.entries(entry0.souls || {}).map(([n, v]) => `soul:${n}: ${JSON.stringify(v)}`)];
-    const targetsLeft = remaining.length > 0;
-    if (!targetsLeft) { if (manifest.layer) delete caps.layers[manifest.layer]; else delete caps.additive[manifest.capability]; }
-    writeFileSync(file, replaceCapabilitiesBlock(text, caps));
-    const note = targetsLeft ? `this level still binds ${manifest.capability}: ${remaining.join(", ")}; remove them with oats use ${manifest.capability} --inherit --global|--type <t>|--soul <s> if the intent is full inheritance` : null;
-    answer({ capability: manifest.capability, action: "inherit", target: targetLabel, layer: manifest.layer || null, level, file, entryRemoved: !targetsLeft, remaining, note, before, after: { bound: false, enabled: null, settings: targetsLeft ? before.settings : {}, effective: effectiveAfter(soulForEffective, manifest.layer, manifest.capability) } },
-      `${manifest.capability} ${targetLabel} binding removed at ${level} level${targetsLeft ? `; still bound here: ${remaining.join(", ")}` : " (entry removed)"} (${shortPath(file)})`);
-    return;
+    } catch (e) { return bail(e.code || "E_LIFECYCLE_FAILED", e.message, e.plan ? { plan: e.plan } : e.candidates ? { candidates: e.candidates } : undefined); }
   }
-  // Locate or create the entry in the right subtree.
-  let entry;
-  if (manifest.layer) {
-    const existing = caps.layers[manifest.layer];
-    var entryExisted = !!(existing && existing !== "none" && existing.capability === manifest.capability);
-    entry = entryExisted ? existing : { capability: manifest.capability };
-    // One entry per layer per level: another capability's entry is never
-    // overwritten, not even by an exclusion, and the remedy is exact.
-    if (existing && existing !== "none" && existing.capability !== manifest.capability) {
-      cmdFail("E_LAYER_BOUND", `fundamental layer ${manifest.layer} already binds ${existing.capability} at ${level} level (${shortPath(file)}); remove that binding first with oats use ${existing.capability} --inherit --global (and --type/--soul for each of its targets), or disable the layer here with oats use none --layer ${manifest.layer}, then use ${manifest.capability}`);
-    }
-    caps.layers[manifest.layer] = entry;
-  } else {
-    entry = caps.additive[manifest.capability] || {};
-    caps.additive[manifest.capability] = entry;
-  }
-  const beforeState = stateOf(entryExisted || !manifest.layer ? entry : undefined);
-  const from = originToFrom(manifest._origin);
-  if (from && !entry.from) entry.from = from;
-  const settingsArgs = [];
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] !== "--settings") continue;
-    let consumed = 0;
-    for (let j = i + 1; j < args.length && !args[j].startsWith("--"); j++, consumed++) settingsArgs.push(args[j]);
-    if (!consumed) cmdFail("E_BAD_ARGS", "--settings expects one or more key=value pairs");
-    i += consumed;
-  }
-  if (settingsArgs.length) {
-    entry.settings = entry.settings && typeof entry.settings === "object" ? entry.settings : {};
-    for (const kv of settingsArgs) {
-      const eq = kv.indexOf("=");
-      if (eq <= 0) cmdFail("E_BAD_ARGS", `--settings expects key=value, got "${kv}"`);
-      // WRITE side of the refusals the readers enforce. Two distinct hazards on
-      // this one line:
-      //   - `--settings __proto__=x` assigned through the inherited setter,
-      //     which swallowed the entry, and the command reported success for a
-      //     setting it never wrote;
-      //   - the VALUE is rendered verbatim into one `key: value` line, so a
-      //     newline-bearing value stopped being a value and became document —
-      //     a crafted one added a whole second capability entry.
-      // Both fail closed, before anything is written.
-      const key = assertSafeConfigWriteKey(kv.slice(0, eq), `--settings key ${JSON.stringify(kv.slice(0, eq))}`);
-      entry.settings[key] = assertSafeConfigValue(kv.slice(eq + 1), `--settings value for ${JSON.stringify(key)}`);
+  let home = flag("home");
+  if (home === true) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+  if (home !== undefined && !isAbsolute(home)) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+  if (home === undefined) {
+    let root;
+    try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
+    let r; try { r = resolveOatsConfig(dirFlag()); } catch (e) { return bail(e.code || "E_CONFIG_BROKEN", e.message); }
+    const roots = [...new Set([root, ...(r.team ? teamAgentRoots(r.team.scope) : [])].map((p) => realOrResolved(p)))];
+    const candidates = [];
+    for (const rt of roots) for (const hit of findInstanceHomes(rt, name)) candidates.push({ root: rt, agent: hit.agent?.name ?? null, home: hit.home });
+    if (!candidates.length) return bail("E_SESSION_UNKNOWN", `no instance ${JSON.stringify(name)} under ${roots.join(", ")}`);
+    if (candidates.length > 1) return bail("E_AMBIGUOUS_INSTANCE", `instance ${JSON.stringify(name)} has ${candidates.length} homes; pass --home <abs>`, { candidates });
+    home = candidates[0].home;
+  } else if (basename(home) !== name) return bail("E_HOME_MISMATCH", `--home ${home} is not the home of instance ${JSON.stringify(name)}`);
+  try {
+    if (sub === "git") {
+      const observed = observeInstanceGit(home);
+      if (JSON_MODE) { jsonOk(observed); return; }
+      const o = observed.observation;
+      console.log(`${observed.instance} — ${shortPath(o.worktree)} @ ${o.branch ?? (o.detached ? `detached ${o.revision.slice(0, 12)}` : "unborn")}`);
+      console.log(`  upstream: ${observed.upstream.ref ? `${observed.upstream.ref} +${observed.upstream.ahead} -${observed.upstream.behind}` : "none (ahead/behind unknown)"}`);
+      console.log(`  base: ${observed.base.ref ? `${observed.base.ref} +${observed.base.ahead} -${observed.base.behind} (merge-base ${observed.base.mergeBase?.slice(0, 12)})` : "unknown"}`);
+      console.log(`  files: ${observed.files.length} (${Object.entries(observed.summary).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "clean"})`);
+      for (const f of observed.files) console.log(`    ${f.xy} ${f.origPath ? `${f.origPath} -> ` : ""}${f.path}  [${f.id}]`);
+      for (const n of observed.notes) console.log(`  note: ${n}`);
+      return;
     }
+    const fileId = flag("file"), revision = flag("revision"), indexRevision = flag("index-revision");
+    if (fileId === true || revision === true || indexRevision === true) return bail("E_BAD_ARGS", usage);
+    const d = diffInstanceFile(home, { fileId, revision, indexRevision });
+    if (JSON_MODE) { jsonOk(d); return; }
+    console.log(`${d.file.origPath ? `${d.file.origPath} -> ` : ""}${d.file.path} (${d.file.kind}, against ${d.against})${d.binary ? " [binary]" : ""}${d.truncated ? ` [truncated at ${d.limit} bytes]` : ""}`);
+    if (!d.binary) process.stdout.write(d.patch);
+  } catch (e) {
+    bail(e.code || "E_GIT_FAILED", e.message, e.observation ? { observation: e.observation } : undefined);
   }
-  if (targetKind === "global") entry.global = enabled;
-  else {
-    // An EXISTING layer entry with no explicit targets is implicitly global:
-    // materialize that before narrowing, so adding a soul/type binding does not
-    // silently drop everyone else. An entry this command just created (the
-    // layer was `none` or another capability) has no implicit global to keep:
-    // a targeted first binding is written as global: false, explicitly.
-    if (manifest.layer && entry.global === undefined && !entry["agent-types"] && !entry.souls) entry.global = entryExisted;
-    entry[targetKind] = entry[targetKind] && typeof entry[targetKind] === "object" ? entry[targetKind] : {};
-    // Same write-side refusal, and for the same two reasons: `--soul
-    // __proto__` was swallowed by the inherited setter and reported as
-    // activated, and a `--soul`/`--type` NAME is written as a mapping key, so a
-    // newline in it injects document exactly like a settings value does.
-    entry[targetKind][assertSafeConfigWriteKey(targetName, `--${targetKind === "agent-types" ? "type" : "soul"} name ${JSON.stringify(String(targetName))}`)] = enabled;
-  }
-  writeFileSync(file, replaceCapabilitiesBlock(text, caps));
-  const afterState = stateOf(entry);
-  const missing = capabilityMissingRequires(manifest.capability, dir);
-  answer({ capability: manifest.capability, action: enabled ? "enable" : "disable", target: targetLabel, layer: manifest.layer || null, level, file, settings: entry.settings || {}, before: beforeState, after: { ...afterState, effective: effectiveAfter(soulForEffective, manifest.layer, manifest.capability) }, missingRequires: missing },
-    `${enabled ? "Activated" : "Excluded"} ${manifest.capability} for ${targetKind === "global" ? "global" : `${targetKind === "agent-types" ? "type" : "soul"} ${targetName}`} at ${level} level (${shortPath(file)})`);
-  if (JSON_MODE) return;
-  for (const miss of missing) console.log(`WARNING: required command "${miss.command}" not on PATH — ${miss.why || ""}${miss.install ? ` (install: ${miss.install})` : ""}`);
-  console.log("New instances receive the resolved capability; committed souls are unchanged.");
 }
-
-// ---------- install / trust / list / remove / migrate ----------
-const cmdFail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
-/** `oats install <source>`: distribution-package acquisition (exact-lock closure,
- * activates nothing). Marketplace capability ids keep the legacy capability path
- * until workstream 3 publishes the official packages. */
-function install() {
-  const src = args[1];
-  const dir = dirFlag();
-  if (!src || src.startsWith("--")) {
-    // Usage errors surface BEFORE any restore/network side effect: a malformed
-    // --accept-requirement must not mutate the deployment and then report E_USAGE.
-    flagAll("accept-requirement");
-    reconcile(dir);
-    return;
-  }
-  const retiredReason = retiredCapabilityReason(src);
-  if (retiredReason) cmdFail("retired-capability", retiredReason);
-  // Package source? (git/path with an oats-package.json, or a catalog id) — otherwise legacy capability acquisition.
-  let parsedSrc;
-  try { parsedSrc = parsePackageSource(src); } catch { parsedSrc = undefined; }
-  const catalogId = parsedSrc?.kind === "catalog" ? parsedSrc.id : undefined;
-  const hasOfficialPackage = !!catalogId && Object.hasOwn(officialPackageCatalog(), catalogId);
-  // Once an official package catalog entry exists it becomes the default
-  // acquisition route for that short id. Existing v1 installs keep working,
-  // but a deliberate `oats install oats.okf` now acquires the package rather than
-  // creating another legacy capability lock.
-  const isMarketplaceCap = parsedSrc?.kind === "catalog" && !!marketplaceCapabilities()[catalogId] && !hasOfficialPackage;
-  const isLocalPackage = parsedSrc?.kind === "path" && existsSync(join(parsedSrc.path, "oats-package.json"));
-  const isCatalogPackage = parsedSrc?.kind === "catalog" && !isMarketplaceCap;
-  let gitInspection;
-  if (parsedSrc && (parsedSrc.kind === "git" || isLocalPackage || isCatalogPackage)) {
-    // Remote Git may be either a distribution package or the documented
-    // legacy standalone-capability repository. Inspect the fetched ROOT before
-    // any scope lock preflight; never infer root layout from closure errors.
-    if (parsedSrc.kind === "git") {
-      try { gitInspection = inspectGitSourceRoot(src); }
-      catch (e) { cmdFail(e.code || "invalid-source", e.message || e); return; }
-      if (gitInspection.payloadPackage) {
-        try { installPackage(dir, src, { rootSnapshot: gitInspection }); }
-        finally { gitInspection.cleanup(); }
-        return;
-      }
-      // Legacy standalone-capability repositories predate contained package
-      // roots, so the fallback only applies to a REPOSITORY-ROOT capability
-      // that was not asked for a specific path. A repo whose root carries
-      // oats-package.json must never silently downgrade to capability
-      // acquisition just because the selected path holds no package.
-      if (gitInspection.explicitPath || gitInspection.package || !gitInspection.capability) {
-        const where = `package path "${gitInspection.path}"`;
-        const reason = gitInspection.package
-          ? `Git source ${src} has an oats-package.json at the repository ROOT but no package at ${where}${gitInspection.explicitPath ? "" : " (the default)"} — select the root explicitly with \`${src}#.\``
-          : gitInspection.explicitPath
-            ? `Git source ${src} has no oats-package.json at ${where}`
-            : `Git source ${src} has no oats-package.json at ${where} (the default package path) and no oats.json at its root`;
-        gitInspection.cleanup();
-        cmdFail("invalid-package-manifest", reason); return;
-      }
-      // Standalone capability: hand the SAME fetched snapshot to legacy
-      // acquisition (which re-verifies that exact root layout before copying).
-    } else { installPackage(dir, src); return; }
-  }
-  let known;
-  try { known = gitInspection ? undefined : capabilityManifest(src, dir); }
-  catch (e) { gitInspection?.cleanup(); cmdFail(e.code || "invalid-lock", e.message || e); return; }
-  if (known) {
-    if (JSON_MODE) { jsonOk({ alreadyAcquired: known.capability, version: known.version || null }); return; }
-    console.log(`Already acquired capability ${known.capability} (${known.version || "unversioned"}); not activated or updated.`);
-    return;
+/** `oats readiness [--soul <name> [--agents-root <abs>]] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json` — K5. */
+function readinessCmd() {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  dropAmbientRoot();
+  // A captured incarnation's readiness comes from its retained resolution, not
+  // from the current configuration this command reads; refuse before inspecting.
+  const homeArg = flag("home");
+  if (homeArg && homeArg !== true) {
+    let capturedMeta = null; try { capturedMeta = JSON.parse(readFileSync(join(String(homeArg), "instance.json"), "utf8")); } catch { /* computeInspect reports the unreadable home */ }
+    if (capturedMeta?.executionBinding || capturedMeta?.captured) return bail("E_UNSUPPORTED_MODE", `${basename(String(homeArg))} is a captured incarnation: its readiness is the retained resolution's, not the current configuration's (inspect it with oats operation --deployment/--resolution)`, { home: String(homeArg), captured: true });
   }
-  let r;
-  try { r = acquireCapability(dir, src, { rootSnapshot: gitInspection }); }
-  catch (e) { cmdFail(e.code || "invalid-source", e.message); return; }
-  finally { gitInspection?.cleanup(); }
-  const lock = {
-    source: r.source,
-    version: r.manifest.version || null,
-    ...(r.commit ? { commit: r.commit } : {}), integrity: r.integrity,
-    // Marketplace packages ship with the kernel you already installed — they are
-    // trusted at acquisition; third-party git/path installs need explicit `oats trust`.
-    trustedExecutables: !!r.marketplace,
-  };
-  if (r.marketplace && r.manifest.environment?.length) {
-    (JSON_MODE ? console.error : console.log)(`Requested launch environment: ${r.manifest.environment.join(", ")}`);
+  const inspect = computeInspect({ onFail: bail });
+  if (!inspect) return;
+  const soul = flag("soul") === true ? null : flag("soul") || inspect.selected?.soul || null;
+  const verify = args.includes("--verify-signatures");
+  let catalog = null; try { catalog = describeOfficialCatalog(); catalog = { packages: Object.fromEntries(catalog.packages.map((p) => [p.package, p])) }; } catch { catalog = null; }
+  const deploymentDir = inspect.scope?.context ?? null;
+  // Echo the exact selector this read was made with, so a consumer can bind the
+  // result to its own admitted target without inventing a revision.
+  // Every field is the argument AS GIVEN (no realpath): a consumer compares it
+  // byte-exact with what it sent. The canonical scope is subject.context.
+  const given = (name) => { const v = flag(name); return v && v !== true ? String(v) : null; };
+  const agentsRootArg = given("agents-root"), dirArg = given("dir");
+  const selector = homeArg && homeArg !== true ? { kind: "home", home: String(homeArg), soul, agentsRoot: agentsRootArg }
+    : soul ? { kind: "soul", soul, agentsRoot: agentsRootArg, dir: dirArg }
+    : { kind: "scope", dir: dirArg };
+  const readiness = readinessOf(inspect, { soul, verifySignatures: verify, catalog, deploymentDir, selector });
+  if (args.includes("--policy")) {
+    const homeOpt = flag("home");
+    let meta = null;
+    if (homeOpt && homeOpt !== true) { try { meta = JSON.parse(readFileSync(join(homeOpt, "instance.json"), "utf8")); } catch (e) { return bail("E_SESSION_UNKNOWN", `${homeOpt}: ${e.message}`); } }
+    readiness.policy = policyOf({ instanceMeta: meta, soul: soul ? inspect.souls.find((s) => s.name === soul) : null }).policy;
+    readiness.notes.push("policy: a lifecycle-authority claim enforced by the spawn route, not an OS sandbox");
   }
-  let lockFile;
-  try { lockFile = writeCapabilityLock(dir, r.manifest.capability, lock); }
-  catch (e) {
-    // Refused lock write (e.g. legacy-lock: a converted scope rejects a NEW v1
-    // capability entry) must
-    // not strand the acquired artifact — compensate before failing.
-    rmSync(r.dest, { recursive: true, force: true });
-    cmdFail(e.code || "legacy-lock", e.message); return;
-  }
-  if (JSON_MODE) { jsonOk({ capability: r.manifest.capability, version: r.manifest.version || null, integrity: r.integrity, source: r.source, dir: r.dest, lockFile, marketplace: !!r.marketplace, trustedExecutables: !!r.marketplace }); return; }
-  console.log(`Acquired ${r.manifest.capability} → ${shortPath(r.dest)}`);
-  console.log(`Locked ${r.manifest.version || r.commit || "exact artifact"} (${r.integrity}) in ${shortPath(lockFile)}; not activated.`);
-  if (r.marketplace) console.log("Marketplace package: executables trusted at acquisition.");
-  else if (r.manifest.commands || r.manifest.hooks || r.manifest.environment?.length) {
-    if (r.manifest.environment?.length) console.log(`Future trust request includes launch environment: ${r.manifest.environment.join(", ")}`);
-    console.log(`Executable surface is blocked until: oats trust ${r.manifest.capability} --dir ${shortPath(dir)}`);
+  if (JSON_MODE) { jsonOk(readiness); return; }
+  console.log(`readiness — ${readiness.subject.kind === "soul" ? `soul ${readiness.subject.name}` : shortPath(readiness.subject.context)}: ${readiness.summary.ready ? "READY" : `${readiness.summary.fail} failing, ${readiness.summary.unknown} unknown of ${readiness.summary.required} required`}`);
+  for (const [name, check] of Object.entries(readiness.checks)) {
+    console.log(`  ${name}: ${check.status}`);
+    for (const i of check.items) console.log(`    ${i.status.padEnd(14)} ${i.subject}${i.required ? "" : " (optional)"}${i.reason ? ` — ${i.reason}` : ""}${i.signature ? ` · signature ${i.signature.status}${i.signature.signer?.label ? ` by ${i.signature.signer.label}` : ""}` : ""}${i.remedy ? `  → ${i.remedy}` : ""}`);
   }
+  if (readiness.policy) console.log(`  policy: child spawns ${readiness.policy.childSpawns.allowed ? "allowed" : "disabled"} (${readiness.policy.childSpawns.origin.kind}${readiness.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${readiness.policy.worktrees.allowed === null ? "unknown" : readiness.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
+  for (const n of readiness.notes) console.log(`  note: ${n}`);
 }
+// ---------- workspace model v2: sync / package / workspace status / capabilities / souls ----------
+// Contract: docs/design/2026-09-23-workspace-module-contracts.md §6. Nothing is
+// installed: `oats-local.yaml` names the workspace, discovery runs over the Git
+// remotes (lib/workspace.mjs), packages resolve to exact commits (lib/packages.mjs,
+// lock v3) and the only persisted state is `oats-lock.json` beside oats-local.yaml.
 
-/** Lock-file levels from dir upward (closest last — outermost first), like restoreCapabilities' walk. */
-function lockLevelsUp(dir) {
-  const levels = [];
-  for (let d = resolve(dir); ; d = dirname(d)) {
-    if (existsSync(join(d, OATS_LOCK_FILE))) levels.push(d);
-    if (dirname(d) === d) break;
-  }
-  return levels.reverse();
+/** Remote options threaded into every remote call. OATS_REMOTE_CACHE relocates
+ * the content-addressed fetch cache (tests never touch ~/.cache). */
+function remoteOptionsFromEnv() {
+  const cacheDir = process.env.OATS_REMOTE_CACHE;
+  return cacheDir ? { cacheDir: resolve(cacheDir) } : {};
 }
 
-/** Check/restore one level's v2 package locks via the ENGINE's restorePackages
- * (exact restore, no ref advancement, staging + integrity/capability/deps
- * verification inside). The engine walks the lock chain from the given dir;
- * reconciliation calls it per deduplicated level and keeps that level's rows. */
-/** Map engine restore rows to WS2 report items (kind package). */
-const pkgRow = (r) => ({
-  id: r.package, level: r.level, package: true, dir: r.dir,
-  status: r.status === "ok" ? "present" : r.status, reason: r.reason, code: r.code,
-});
-
-/** Restore-and-partition for reconciliation (reviewer-455ba15 fix 1): the
- * engine's restorePackages walks the WHOLE lock chain from a directory and has
- * no exact-level option, so invoke it ONCE per deepest scope and PARTITION the
- * report rows by lock level — never re-invoke per level (each re-invocation
- * re-runs restore side effects for every ancestor lock). Returns a Map
- * level(resolved) → rows. */
-function partitionedPackageRestore(deepestDir) {
-  const byLevel = new Map();
-  const add = (level, row) => {
-    const key = resolve(level);
-    if (!byLevel.has(key)) byLevel.set(key, []);
-    byLevel.get(key).push(row);
-  };
-  for (const r of restorePackages(deepestDir)) add(r.level, pkgRow(r));
-  // EMPTY v1 lock files surface too (maintainer ruling): the engine's restore
-  // report only rows NON-empty v1 files. Walk the raw lock chain (a lock-only
-  // scope has no config, so configChain-based reads cannot see it) and emit a
-  // LEGACY row for each empty v1 file so reconciliation shows the pending
-  // lock-format migration.
-  for (const level of lockLevelsUp(deepestDir)) {
-    try {
-      const parsed = JSON.parse(readFileSync(join(level, OATS_LOCK_FILE), "utf8"));
-      if (parsed.lockfileVersion !== 2 && !Object.keys(parsed.capabilities || {}).length) {
-        add(level, { id: null, level, package: true, status: "legacy", reason: `empty lockfileVersion ${parsed.lockfileVersion ?? 1} file — pending lock-format migration: oats migrate --dir ${level}` });
-      }
-    } catch { /* malformed locks raise via restorePackages above */ }
+/** The v2 deployment context at --dir: { dir, localPath, local, deploymentDir, remoteOptions }. */
+function workspaceContext(bail) {
+  const dir = dirFlag();
+  let found;
+  try { found = loadLocal(dir); }
+  catch (e) { return bail(e.code || "E_LOCAL_MISSING", e.message, e.details); }
+  return { dir, localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() };
+}
+
+/** The official catalog's package map (package-catalog.json; OATS_PACKAGE_CATALOG overrides). */
+function catalogForSync(bail) {
+  try { return officialPackageCatalog(); }
+  catch (e) { return bail(e.code || "E_PACKAGE_MISSING", e.message); }
+}
+
+/** The package requests of a standalone view: the catalog's own pin of the package
+ *  providing oats.core (decision 25) — nothing else, since the version list lives in
+ *  the workspace file we cannot read. The request is written as resolvePackages
+ *  expects a CATALOG entry: the bare version (`v1.1.3`), never the catalog's raw ref
+ *  (`oats-framework/v1.1.3` is a tag PATH the one grammar refuses); parsePackageRequest
+ *  recomposes the tag from the catalog's own convention.
+ *  → { packages: { <id>: <version> }, problems: [ { code: "E_PACKAGE_MISSING", … } ] } */
+function standalonePackages(catalog) {
+  let id = "oats.framework", file = process.env.OATS_PACKAGE_CATALOG || null;
+  try { const d = describeOfficialCatalog(); file = d.catalog.file; id = d.capabilityAliases.find((a) => a.capability === "oats.core")?.package ?? id; } catch { /* the catalog is diagnosed below */ }
+  const version = standaloneCatalogVersion(catalog?.[id]?.ref);
+  if (version) return { packages: { [id]: version }, problems: [] };
+  const why = catalog?.[id] ? `its ref ${JSON.stringify(catalog[id].ref)} carries no version` : `it has no entry ${JSON.stringify(id)}`;
+  return { packages: {}, problems: [{ code: "E_PACKAGE_MISSING", id, reason: "no-catalog", catalog: file, path: `/packages/${id}`, message: `the catalog has no package providing oats.core (OATS_PACKAGE_CATALOG=${file ?? "<bundled>"}): ${why}; standalone spawns will be refused until it does` }] };
+}
+/** The bare version of a catalog ref: its LAST path segment when that is a version
+ *  (`v1.1.3` → `v1.1.3`; `oats-framework/v1.1.3` → `v1.1.3`; `main` → null). */
+function standaloneCatalogVersion(ref) {
+  if (typeof ref !== "string" || !ref.trim()) return null;
+  const tail = ref.trim().split("/").filter(Boolean).pop() ?? "";
+  return classifyPackageValue(tail).kind === "catalog" ? tail : null;
+}
+
+/** Discover the workspace named by oats-local.yaml over the real remote. */
+async function discoverForCli(ctx, bail) {
+  // The standalone case (decisions 10/25) is a discovery too: the repo's own view
+  // plus the kernel's oats.core default — discoverOrStandalone decides.
+  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); return await discoverOrStandalone(ctx.local, { remoteOptions: ctx.remoteOptions }); }
+  catch (e) {
+    if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
+    throw e;
   }
-  return byLevel;
 }
 
-function installPackage(dir, src, opts = {}) {
-  const bail = (e) => (JSON_MODE ? jsonFail(e.code || "invalid-source", e.message || e) : die(e.message || e));
-  let r;
-  try { r = acquirePackage(dir, src, opts); }
-  catch (e) { bail(e); return true; }
-  // Packages are transport; capabilities are what lands on disk. Report both,
-  // and let the CAPABILITY rows carry the provenance an operator acts on.
-  if (JSON_MODE) { jsonOk({ root: r.root, installed: r.installed, capabilities: r.capabilities, lockFile: r.lockFile, depWarnings: r.depWarnings || [] }); return true; }
-  for (const p of r.installed) {
-    console.log(`${p.kept ? "ok       " : "Acquired "}${p.package}@${p.version}`);
-    console.log(`  locked ${p.commit === "local" ? "local tree" : p.commit} at path ${p.path} (${p.integrity})`);
-    for (const c of r.capabilities.filter((x) => x.package === p.package)) {
-      console.log(`  capability ${c.capability}@${c.version}${c.layer ? `  layer: ${c.layer}` : ""} → ${shortPath(c.dir)}  (${c.integrity})`);
-    }
-    if (!r.capabilities.some((x) => x.package === p.package)) console.log("  capabilities: (none)");
-  }
-  for (const w of r.depWarnings || []) console.log(`WARNING: ${w}`);
-  console.log(`Locked in ${shortPath(r.lockFile)}; nothing activated.`);
-  // Read the executable surface off the ENGINE's projection, not a config-chain
-  // manifest lookup: at a scope with no config yet, that lookup sees nothing.
-  const executables = r.capabilities
-    .filter((c) => c.executableSurface?.commands?.length || c.executableSurface?.hooks?.length || c.executableSurface?.environment?.length)
-    .map((c) => c.capability);
-  if (executables.length) console.log(`Executable surfaces blocked until trusted: ${executables.map((c) => `oats trust ${c}`).join("; ")}`);
-  return true;
+const short = (oid) => (typeof oid === "string" ? oid.slice(0, 8) : "?");
+/** Where a reader takes capability manifests from: the instance home's own
+ *  materialized modules when the home has them (workspace model), else the
+ *  context directory (classic chain). */
+const manifestSource = (meta, home, ctx) => (meta && meta.modules && typeof meta.modules === "object" && home ? realOrResolved(home) : ctx);
+/** Display name of a discovery: the workspace's name, or the standalone label (decision 10). */
+const workspaceName = (discovery) => discovery.workspace?.name ?? `standalone:${memberLabel(discovery.key)}`;
+const memberLabel = (key) => String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/, "") || String(key);
+const teamLabel = (team) => team ?? "unassigned";
+const originOf = (item) => (item.package ? `package ${item.package} v${item.version}` : `member ${item.repoKey} @ ${short(item.commit)}`);
+
+/** Rows of every non-private soul/capability of confirmed members + locked package capabilities. */
+function workspaceItems(discovery, lock, { includePrivate = false } = {}) {
+  const souls = [];
+  const capabilities = [];
+  for (const m of discovery.members) {
+    if (!m.confirmed && !(discovery.standalone === true && m.key === discovery.key)) continue;
+    for (const s of m.souls) if (includePrivate || !s.private) souls.push({ name: s.name, origin: originOf(s), kind: "member", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null });
+    for (const c of m.capabilities) if (includePrivate || !c.private) capabilities.push({ name: c.name, origin: originOf(c), kind: "member", repoKey: c.repoKey, commit: c.commit, team: teamLabel(c.team), private: c.private, path: c.path, layer: c.manifest.layer ?? null, version: c.manifest.version ?? null });
+  }
+  for (const ext of discovery.external || []) {
+    const s = ext.soul;
+    if (includePrivate || !s.private) souls.push({ name: s.name, origin: `external ${s.repoKey} @ ${short(s.commit)}`, kind: "external", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null });
+  }
+  for (const [id, entry] of Object.entries(lock?.packages || {})) {
+    for (const name of entry.capabilities) capabilities.push({ name, origin: originOf({ package: id, version: entry.version }), kind: "package", package: id, version: entry.version, commit: entry.commit, team: teamLabel(null), private: false, approved: !!entry.approved });
+  }
+  const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0);
+  souls.sort(byName);
+  capabilities.sort(byName);
+  return { souls, capabilities };
 }
 
-/** Bare `oats install` chain restore: engine packages (lock v2) + legacy locked
- * capabilities (v1). Returns { report, failed }; output goes to stdout (human)
- * or stderr (JSON mode) — the reconcile envelope owns stdout in JSON mode. */
-function restore(dir) {
-  const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
-  // Fail-closed locks: restorePackages/restoreCapabilities RAISE typed
-  // invalid-lock — let the reconcile boundary surface the code verbatim
-  // (never softened to empty); this throw is caught by reconcile().
-  const pkgReport = restorePackages(dir).map((r) => ({
-    id: r.package, level: r.level, package: true, dir: r.dir,
-    status: r.status === "ok" ? "present" : r.status, reason: r.reason, code: r.code,
+/** Membership rows for `sync` / `workspace status`. */
+function memberRows(discovery) {
+  return discovery.members.map((m) => ({
+    key: m.key, name: memberLabel(m.key), commit: m.commit ?? null, confirmed: m.confirmed, status: m.confirmed ? "confirmed" : m.reason, detail: m.detail ?? null, team: m.team ?? null,
+    souls: m.souls.map((s) => s.name), capabilities: m.capabilities.map((c) => c.name), publishes: m.publishes ?? null,
   }));
-  const report = [...restoreCapabilities(dir), ...pkgReport];
-  if (!report.length) note("Nothing to restore — no locked capabilities in the config chain.");
-  let failed = 0;
-  for (const r of report) {
-    const what = r.package ? `package ${r.id ?? "(lock)"}` : r.id;
-    if (r.status === "present") note(`ok        ${what}  (${shortPath(r.dir)})`);
-    else if (r.status === "restored") note(`restored  ${what} → ${shortPath(r.dir)}${r.integrity ? `  (${r.integrity})` : ""}`);
-    else if (r.status === "legacy") note(`LEGACY    ${shortPath(join(r.level, OATS_LOCK_FILE))}: ${r.reason}`);
-    else if (r.status === "retired") { failed++; note(`RETIRED   ${what}  ${r.reason}`); }
-    else { failed++; note(`FAILED    ${what}  ${r.reason}`); }
-  }
-  return { report, failed };
 }
 
-/** Unsuccessful restore statuses and their frozen taxonomy codes (reviewer-6f0a3bd:
- * "unrestorable" and "retired" must not report ok). */
-const UNSUCCESSFUL_RESTORE = { failed: undefined, unrestorable: "invalid-source", retired: "retired-capability" };
+/** Package rows for `sync` / `workspace status` from the lock. */
+function packageRows(lock) {
+  return Object.entries(lock.packages).map(([id, p]) => ({ id, version: p.version, source: p.source, commit: p.commit, integrity: p.integrity, capabilities: p.capabilities, approved: p.approved }));
+}
 
-/** One artifact report item → the machine shape (kind capability|package). */
-const artifactJson = (r) => ({
-  id: r.id, kind: r.package ? "package" : "capability", level: r.level,
-  status: r.status, ...(r.dir ? { dir: r.dir } : {}), ...(r.reason ? { reason: r.reason } : {}),
-  ...(Object.hasOwn(UNSUCCESSFUL_RESTORE, r.status) ? { code: r.code || UNSUCCESSFUL_RESTORE[r.status] || "integrity-drift" } : {}),
-});
+/** Print a padded table: rows are arrays of strings. */
+function printTable(header, rows) {
+  const all = [header, ...rows];
+  const widths = header.map((_, i) => Math.max(...all.map((r) => String(r[i] ?? "").length)));
+  for (const r of all) console.log("  " + r.map((c, i) => String(c ?? "").padEnd(widths[i])).join("  ").trimEnd());
+}
 
-/** Emit the reconcile/restore result: human exit or the single-envelope JSON contract.
- * Full success → { ok: true, result }. ANY artifact or consented-install failure →
- * nonzero with error.code E_RECONCILE_FAILED and the SAME complete report under
- * error.details — partial outcomes are never lost. */
-function emitReconcileResult({ boundary, boundaryKind, scopes, requirements, failures }) {
-  const result = { boundary, boundaryKind, scopes, requirements, failures };
-  if (JSON_MODE) {
-    if (failures.length) {
-      console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code: "E_RECONCILE_FAILED", message: `${failures.length} failure${failures.length > 1 ? "s" : ""} during restore/reconciliation`, details: result } }));
-      process.exit(1);
-    }
-    jsonOk(result);
-    return;
-  }
-  if (failures.length) {
-    console.log("\nFailures by scope:");
-    for (const f of failures) console.log(`  ${shortPath(f.scope)}: ${f.id} — ${f.reason}`);
-    die(`${failures.length} failure${failures.length > 1 ? "s" : ""} during restore/reconciliation`);
-  }
+/** Executables digest of a locked package, read over the remote at its locked commit. */
+async function lockedExecutablesDigest(id, entry, workspace, catalog, remoteOptions) {
+  // ONE definition of the approval digest (lib/packages.mjs executablesDigestAt) — the
+  // same function resolveSoul re-runs at spawn (M3), so sync and spawn can never disagree.
+  const req = parsePackageRequest(id, workspace.packages[id], catalog);
+  const { digest, executables } = await executablesDigestAt(remoteModule, req.remoteRef, entry.commit, entry.path, entry.capabilities ?? null, { remoteOptions });
+  const targets = executables.map((x) => `${x.capability}: ${x.kind} ${x.name} → ${x.target}`);
+  return { digest, targets };
 }
 
-/** Bare `oats install` at a team boundary: reconcile the whole workspace — restore the
- * boundary scope's graph (its ancestor chain), then every descendant scope's own
- * lock graph EXACTLY ONCE, in deterministic path order, with pruned discovery;
- * verify v2 package locks against the installed package store; validate
- * config-referenced capabilities against visible locked packages; aggregate
- * missing requirements and failures by scope.
- * Non-team scopes keep current-chain behavior unless --recursive names a boundary. */
-/** Bare `oats install` (no source): current-chain restore or team-boundary
- * reconciliation. JSON-mode boundary: ANY throw before emitReconcileResult
- * (malformed lock/config, discovery failures) must still yield the single
- * envelope — never empty stdout with a stack trace. */
-function reconcile(dir) {
-  try { reconcileInner(dir); }
+/** One yes/no question on the terminal (TTY only; the caller checks). */
+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";
+  } finally { rl.close(); }
+}
+
+/** 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.
+ * `bail` never returns (it exits the process with the caller's error shape).
+ * → { report, lock, discovery, approvalNeeded, interactive, items, lockFile } */
+async function performSync(ctx, bail, { onDiscovered } = {}) {
+  const catalog = catalogForSync(bail);
+  const discovery = await discoverForCli(ctx, bail);
+  onDiscovered?.(discovery);
+  let previous;
+  try { previous = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  let resolved;
+  // Standalone: no workspace file → the only package request is the kernel's
+  // default, at the catalog's pinned version (decision 25). A catalog that cannot
+  // name it is a PROBLEM of this sync (reported, exit unchanged), not a silent empty lock.
+  const standalone = discovery.standalone === true ? standalonePackages(catalog) : null;
+  const packageSource = standalone ? { packages: standalone.packages } : discovery.workspace;
+  const problems = [...discovery.problems, ...(standalone?.problems ?? [])];
+  try { resolved = await resolvePackages(packageSource, { catalog, lock: previous, remoteOptions: ctx.remoteOptions }); }
   catch (e) {
-    if (JSON_MODE) {
-      console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code: e.code || "E_RECONCILE_FAILED", message: String(e.message || e) } }));
-      process.exit(1);
+    if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
+    throw e;
+  }
+  let lock = resolved.lock;
+  const approvalNeeded = [];
+  const interactive = !JSON_MODE && process.stdin.isTTY && process.stdout.isTTY;
+  for (const id of Object.keys(lock.packages)) {
+    const entry = lock.packages[id];
+    if (entry.approved) continue;
+    let digest, targets;
+    try { ({ digest, targets } = await lockedExecutablesDigest(id, entry, packageSource, catalog, ctx.remoteOptions)); }
+    catch (e) {
+      if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
+      throw e;
     }
-    die(e.message || e);
+    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}`);
+      if (targets.length === 0) console.error("  (no commands or hooks — nothing runs unattended)");
+      if (await askYesNo(`approve ${id} ${entry.version}? [y/N] `)) { lock = approvePackage(lock, id, digest); continue; }
+    }
+    approvalNeeded.push({ id, version: entry.version, commit: entry.commit, executables: digest, targets });
   }
-}
-
-function reconcileInner(dir) {
-  const cfgFile = join(dir, "oats-config.yaml");
-  const declaresTeamHere = existsSync(cfgFile) && !!withConfigFile(cfgFile, () => parseYamlNested(readFileSync(cfgFile, "utf8"))).team;
-  const recursive = args.includes("--recursive");
-  if (!declaresTeamHere && !recursive) {
-    // Current-chain behavior, plus the requirements gate for this chain's active capabilities.
-    const { report, failed } = restore(dir);
-    const requirements = requirementsGate([dir]);
-    const failures = [
-      // "legacy" is informational (v1 locks restore via the capability path);
-      // every other unsuccessful status is a failure (incl. retired/unrestorable
-      // per reviewer-6f0a3bd — they must not report ok).
-      ...report.filter((r) => Object.hasOwn(UNSUCCESSFUL_RESTORE, r.status)).map((r) => ({ scope: r.level, id: r.package ? `package ${r.id}` : r.id, reason: r.reason, code: r.code || UNSUCCESSFUL_RESTORE[r.status] })),
-      ...requirements.filter((q) => q.outcome === "failed").map((q) => ({ scope: dir, id: `requirement ${q.command}`, reason: q.reason || "consented install failed" })),
-    ];
-    void failed;
-    emitReconcileResult({
-      boundary: dir, boundaryKind: "chain",
-      scopes: [{ scope: dir, artifacts: report.map(artifactJson) }],
-      requirements, failures,
-    });
-    return;
-  }
-  const boundary = dir;
-  const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
-  // The chosen boundary is printed BEFORE any network or host work — always.
-  note(`Workspace reconciliation boundary: ${shortPath(boundary)}${declaresTeamHere ? " (team scope)" : " (--recursive)"}`);
-  const scopes = [boundary, ...discoverWorkspaceScopes(boundary)];
-  const failures = [];
-  const scopeReports = [];
-  let reportedAny = false;
-  const restoredLevels = new Set(); // each lock level's graph restores exactly once
-  const packageCheckedLevels = new Set(); // each level's package-lock rows consumed exactly once
-  // reviewer-455ba15 fix 1 — partition-not-rerun: run the engine's chain-walking
-  // package restore as FEW times as the API allows and hand out each level's
-  // rows exactly once. One invocation covers a scope's entire ancestor chain;
-  // rows are stashed so no level is ever REPORTED twice and no already-walked
-  // level triggers a re-invocation. RESIDUAL (pending WS1's exact-levels API,
-  // relayed as a want): a descendant owning its own lock necessarily re-walks
-  // its ancestors inside the engine — present/valid ancestor artifacts re-verify
-  // with local reads only, but a FAILED ancestor fetch may retry once per
-  // lock-owning descendant. The exact-once reporting contract holds.
-  const pendingPkgRows = new Map(); // level(resolved) → rows not yet consumed
-  const packageRowsFor = (scope, levels) => {
-    const wanted = levels.map((l) => resolve(l)).filter((l) => !packageCheckedLevels.has(l));
-    if (!wanted.length) return [];
-    if (wanted.some((l) => !pendingPkgRows.has(l))) {
-      // One restore invocation covers scope's whole chain; stash every level's
-      // rows so later scopes never re-invoke for already-walked levels.
-      for (const [lvl, rows] of partitionedPackageRestore(scope)) {
-        if (!pendingPkgRows.has(lvl)) pendingPkgRows.set(lvl, rows);
-      }
-    }
-    const out = [];
-    for (const l of wanted) {
-      packageCheckedLevels.add(l);
-      out.push(...(pendingPkgRows.get(l) || []));
-    }
-    return out;
-  };
-  for (const scope of scopes) {
-    // Boundary: full ancestor chain (current-chain semantics). Descendants: their
-    // own level only — every level between boundary and descendant is either the
-    // boundary chain or an earlier discovered scope, so no level repeats and no
-    // failed ancestor restore is retried (or hidden) per descendant.
-    const chainLevels = scope === boundary ? undefined : [scope];
-    const report = restoreCapabilities(scope, chainLevels ? { levels: chainLevels.filter((l) => !restoredLevels.has(resolve(l))) } : undefined)
-      .filter((r) => !restoredLevels.has(resolve(r.level)));
-    // v2 package locks: every lock level this scope covers (the boundary covers
-    // its whole ancestor chain), each restored/verified exactly once.
-    report.push(...packageRowsFor(scope, scope === boundary ? lockLevelsUp(boundary) : [scope]));
-    for (const r of report) {
-      reportedAny = true;
-      const what = r.package ? `package ${r.id ?? "(lock)"}` : r.id;
-      if (r.status === "present") note(`ok        ${what}  [${shortPath(r.level)}]`);
-      else if (r.status === "restored") note(`restored  ${what} → ${shortPath(r.dir)}  [${shortPath(r.level)}]`);
-      else if (r.status === "legacy") note(`LEGACY    ${shortPath(join(r.level, OATS_LOCK_FILE))}: ${r.reason}`);
-      else if (r.status === "retired") { failures.push({ scope: r.level, id: what, reason: r.reason, code: "retired-capability" }); note(`RETIRED   ${what}  ${r.reason}  [${shortPath(r.level)}]`); }
-      else { failures.push({ scope: r.level, id: what, reason: r.reason, code: r.code }); note(`FAILED    ${what}  ${r.reason}  [${shortPath(r.level)}]`); }
-    }
-    if (scope === boundary) for (const cfg of configChain(boundary)) restoredLevels.add(resolve(cfg._level));
-    for (const r of report) restoredLevels.add(resolve(r.level));
-    restoredLevels.add(resolve(scope));
-    // Validate: every config-referenced installed capability supplied by a visible locked package/capability lock.
-    if (existsSync(join(scope, "oats-config.yaml"))) {
-      try {
-        const supplied = lockedPackageCapabilities(scope);
-        const capLocks = readCapabilityLocks(scope);
-        for (const cfg of configChain(scope)) {
-          if (resolve(cfg._level) !== resolve(scope)) continue;
-          for (const [slot, entry] of Object.entries(cfg.capabilities?.layers || {})) {
-            if (entry && typeof entry === "object" && entry.from === "installed" && !supplied.has(entry.capability) && !capLocks[entry.capability]) {
-              failures.push({ scope, id: entry.capability, reason: `referenced by capabilities.layers.${slot} but supplied by no visible locked package` });
-            }
-          }
-          for (const [id, entry] of Object.entries(cfg.capabilities?.additive || {})) {
-            if (entry && typeof entry === "object" && entry.from === "installed" && !supplied.has(id) && !capLocks[id]) {
-              failures.push({ scope, id, reason: "referenced in config but supplied by no visible locked package" });
-            }
-          }
-        }
-      } catch (e) { failures.push({ scope, id: "(config)", reason: e.message }); }
-    }
-    scopeReports.push({ scope, artifacts: report.map(artifactJson) });
-  }
-  if (!reportedAny && scopes.length === 1) note("Nothing to restore — no locked capabilities or packages found in the boundary.");
-  const requirements = requirementsGate(scopes);
-  for (const q of requirements) {
-    if (q.outcome === "failed") failures.push({ scope: boundary, id: `requirement ${q.command}`, reason: q.reason || "consented install failed" });
-  }
-  emitReconcileResult({
-    boundary, boundaryKind: declaresTeamHere ? "team" : "recursive",
-    scopes: scopeReports, requirements, failures,
-  });
-}
-
-/** Host-requirement consent gate. Requirements are considered only for capabilities
- * activated somewhere in the reconciled scopes, deduplicated by command. Interactive
- * runs prompt per requirement with the exact command/source/version and state scope;
- * non-interactive runs NEVER install by default — automation names each accepted
- * requirement via --accept-requirement <command>; --no-requirements skips entirely.
- * Skipping leaves an actionable doctor warning (doctor recomputes missing commands).
- * Returns structured entries with a stable outcome enum:
- *   "installed"        consented install ran and the command verified on PATH
- *   "failed"           consented install errored or PATH verification missed (→ reconcile failure)
- *   "consent-required" not explicitly accepted — nothing installed
- *   "skipped"          --no-requirements, or no safe installer for this host
- * JSON plan data equals the human prompt plan (argv/source/version/scope/requestedBy;
- * never shell text). In JSON mode all prose goes to stderr. */
-function requirementsGate(scopes) {
-  // Malformed repeatable flags are usage errors regardless of which branch
-  // runs — validate up front so --no-requirements cannot mask them.
-  const accepted = new Set(flagAll("accept-requirement"));
-  // Explicitly named requirements bypass runtime scoping, so the remediation
-  // command a failed spawn prints actually installs something.
-  const missing = aggregateMissingRequirements(scopes, { accepted });
-  if (!missing.length) return [];
-  const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
-  const entryOf = (req, outcome, extra = {}) => ({
-    command: req.command, kind: req.kind || "host-command",
-    runtime: req.runtime || null, package: req.package || null, why: req.why || null,
-    // `steps` is the ORDERED sequence runRequirementInstall actually executes;
-    // `argv` is only its last command. Serializing argv alone hid a
-    // `claude plugin marketplace add <source>` — a lower-trust source
-    // registration — from every client consenting through the JSON API
-    // (reviewer-final0130bc8). Always present, exactly as doctor renders it, so
-    // single- and multi-step plans have one shape.
-    plan: req.plan && !req.plan.unavailable
-      ? { manager: req.plan.manager, argv: req.plan.argv, steps: req.plan.steps || [req.plan.argv], source: req.plan.source, version: req.plan.version || null, scope: req.plan.scope }
-      : null,
-    requestedBy: req.requestedBy, docs: req.docs || null, outcome, ...extra,
-  });
-  // Fail-closed identity/conflict policy (E_REQUIREMENT_POLICY): invalid command
-  // tokens and same-command conflicting plans are NEVER consentable or installable
-  // — they fail reconciliation deterministically with provenance, even under
-  // --no-requirements (skipping consent does not skip safety validation).
-  const policyEntries = [];
-  for (const req of missing) {
-    if (req.invalid) {
-      note(`  INVALID requirement command ${JSON.stringify(req.command)} — ${req.invalid} (requested by: ${req.requestedBy.map((r) => `${r.capability} [${shortPath(r.scope)}]`).join(", ")})`);
-      policyEntries.push(entryOf(req, "failed", { reason: req.invalid, code: "E_REQUIREMENT_POLICY" }));
-    } else if (req.conflict) {
-      note(`  CONFLICT for command "${req.command}": capabilities request non-identical install plans — no install is offered`);
-      // Show the FULL sequence: two capabilities can agree on the final install
-      // command while registering different third-party sources before it.
-      for (const p of req.conflict.plans) {
-        const shown = p.steps?.length ? p.steps.map((a) => a.join(" ")).join("  &&  ") : (p.argv ? p.argv.join(" ") : p.unavailable || "no plan");
-        note(`      ${p.capability} [${shortPath(p.scope)}]: ${shown}`);
-      }
-      policyEntries.push(entryOf(req, "failed", { reason: "conflicting install plans for the same command", code: "E_REQUIREMENT_POLICY", conflict: req.conflict }));
-    }
-  }
-  const consentable = missing.filter((req) => !req.invalid && !req.conflict);
-  if (args.includes("--no-requirements")) return [...policyEntries, ...consentable.map((req) => entryOf(req, "skipped", { reason: "--no-requirements" }))];
-  const interactive = !JSON_MODE && process.stdin.isTTY && process.stdout.isTTY;
-  const out = [...policyEntries];
-  if (consentable.length) note(`\nMissing requirements for active capabilities (${consentable.length}):`);
-  for (const req of consentable) {
-    const requesters = req.requestedBy.map((r) => `${r.capability} [${shortPath(r.scope)}]`).join(", ");
-    note(`  ${req.command} — ${req.why || "required"} (requested by: ${requesters})`);
-    const plan = req.plan;
-    if (!plan || plan.unavailable) {
-      note(`    no safe installer: ${plan?.unavailable || "no recipe"}${req.docs ? ` — install docs: ${req.docs}` : ""}`);
-      out.push(entryOf(req, "skipped", { reason: plan?.unavailable || "no safe installer" }));
-      continue;
-    }
-    // Show EVERY step: installing a Claude plugin also registers a third-party
-    // marketplace, and consent to that must be visible, not implied.
-    const shown = (plan.steps?.length ? plan.steps : [plan.argv]).map((a) => a.join(" ")).join("  &&  ");
-    note(`    installer: ${shown}  (source: ${plan.source}${plan.version ? `, version ${plan.version}` : ""}; ${plan.scope})`);
-    let consent = accepted.has(req.command);
-    if (!consent && interactive) {
-      process.stdout.write(`    Run this install now? [y/N] `);
-      const buf = Buffer.alloc(64);
-      let answer = "";
-      try { answer = buf.toString("utf8", 0, readSync(process.stdin.fd, buf, 0, 64)).trim().toLowerCase(); } catch { /* EOF */ }
-      consent = answer === "y" || answer === "yes";
-    }
-    if (!consent) {
-      note(`    skipped — ${interactive ? "not consented" : "non-interactive; pass --accept-requirement " + req.command + " to install"}; \`oats doctor\` will keep warning until ${req.command} is ${req.kind === "runtime-package" ? `installed for ${req.runtime}` : "on PATH"}`);
-      out.push(entryOf(req, "consent-required"));
-      continue;
-    }
-    try {
-      const r = runRequirementInstall(plan, JSON_MODE ? { stdio: ["ignore", 2, 2] } : {});
-      // A runtime package is verified in its runtime's package list, never on
-      // PATH — saying "on PATH" for one would be false either way it lands.
-      const where = req.kind === "runtime-package" ? `installed for ${req.runtime}` : "on PATH";
-      if (r.onPath) { note(`    installed — ${req.command} verified ${where}`); out.push(entryOf(req, "installed", { onPath: true })); }
-      else { note(`    FAILED: install ran but ${req.command} is still not ${where}${req.kind === "runtime-package" ? "" : " — check your shell PATH/prefix"}`); out.push(entryOf(req, "failed", { onPath: false, reason: `install ran but the requirement is still not ${where}` })); }
-    } catch (e) {
-      note(`    FAILED: ${e.message}`);
-      out.push(entryOf(req, "failed", { onPath: false, reason: e.message }));
-    }
-  }
-  note("Requirement consent is separate from capability trust — installing a binary does not activate or approve any capability.");
-  return out;
-}
-
-/** oats trust <capability> | oats trust <package> --all-capabilities */
-function trust() {
-  const id = args[1];
-  if (!id || id.startsWith("--")) { cmdFail("E_USAGE", "usage: oats trust <capability> [--dir <dir>] | oats trust <package> --all-capabilities [--dir <dir>]"); return; }
-  const dir = dirFlag();
-  const all = args.includes("--all-capabilities");
-  // A v3 deployment needs an EXPLICIT immutable artifact-set selection. Never
-  // guess one or reinterpret its lock through the classic approval engine.
-  try {
-    for (const scope of lockLevelsUp(dir).reverse()) {
-      // Discriminate with the shared bounded decoder only. Classic readers
-      // retain all v1/v2 validation, including implicit (versionless) v1 locks.
-      let version;
-      try { version = parseStrictJson(readPortableBytes(join(scope, OATS_LOCK_FILE)))?.lockfileVersion; }
-      catch { continue; } // Let the existing classic reader diagnose its input.
-      if (version !== 3) continue;
-      const portable = readLock3(scope).lock;
-      if (!portable) throw oatsError("selection-changed", "selection lock disappeared; repeat explicit trust selection");
-      const sets = [...new Set(Object.values(portable.selections).map(row => row.available).filter(key => key && Object.hasOwn(portable.artifactSets[key].capabilities, id)))].sort();
-      const commands = sets.map(artifactSet => ({ artifactSet,
-        command: `oats trust ${shellQuote(id)} --deployment ${shellQuote(scope)} --artifact-set ${shellQuote(artifactSet)}` }));
-      const message = commands.length && !all
-        ? `lock v3 requires exact artifact-set approval; run ${commands.map(item => item.command).join(" or ")}`
-        : `lock v3 approvals are per capability; use prepare's selections[].artifactSet for each capability in approvalRequired[]: oats trust <capability> --deployment ${shellQuote(scope)} --artifact-set <sha256-artifact-set>`;
-      if (JSON_MODE) jsonFail("needs-configuration", message, { deployment: scope, commands });
-      die(message);
-    }
-  } catch (error) { cmdFail(error.code || "invalid-lock", error.message); return; }
-  // Package-backed approval path (per-capability, or explicit bulk on a package id).
-  let pkgs, locks;
-  try { pkgs = listInstalledPackages(dir); locks = readPackageLocks(dir); } catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
-  // findLast: the listing runs outermost → innermost, and an identity resolves
-  // to the CLOSEST scope that locks it — the same rule the merged lock maps use.
-  const backing = all ? pkgs.findLast((p) => p.package === id) : pkgs.findLast((p) => p.capabilities.some((c) => c.id === id));
-  if (backing) {
-    // Approval is per capability unless --all-capabilities is explicit. Print
-    // exactly the authority this invocation will persist, before persisting it;
-    // JSON mode uses stderr so stdout remains one machine envelope.
-    const requested = all ? backing.capabilities : backing.capabilities.filter((c) => c.id === id);
-    const out = JSON_MODE ? console.error : console.log;
-    out(`Package ${backing.package}@${backing.version} ${all ? "full" : "requested"} executable surface:`);
-    for (const c of requested) {
-      const cmds = Object.keys(c.manifest.commands || {});
-      const hooks = Object.keys(c.manifest.hooks || {});
-      const environment = c.manifest.environment || [];
-      out(`  ${c.id}: commands [${cmds.join(", ") || "none"}], hooks [${hooks.join(", ") || "none"}], launch environment [${environment.join(", ") || "none"}]`);
-    }
-    // FAIL CLOSED BEFORE APPROVING. The engine binds approval to the artifact's
-    // integrity, but integrity alone cannot see a `.oats-installation.json` that
-    // claims a different origin than the lock — and approving a capability whose
-    // own provenance is disputed is exactly the thing trust must not do.
-    const trustRows = levelRows(locks, backing.level);
-    const disputed = backing.capabilities
-      .filter((c) => all || c.id === id)
-      .map((c) => capabilityHealth(backing.level, c, trustRows.capabilities[c.id], trustRows.packages[backing.package]))
-      .filter((h) => h.status !== "ok" && h.status !== "untrusted");
-    if (disputed.length) { cmdFail(disputed[0].code || "invalid-lock", `refusing to trust: ${disputed.map((h) => h.detail).join("; ")}`); return; }
-    let r;
-    try { r = approveCapability(dir, id, { allCapabilities: all }); } catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
-    // Approval binds to each capability's exact MATERIALIZED ARTIFACT, so the
-    // integrity reported is per capability — there is no package-level digest
-    // to approve against and none to print.
-    const approvedIntegrity = {};
-    for (const c of backing.capabilities) if (r.approved.includes(c.id)) approvedIntegrity[c.id] = c.integrity || null;
-    if (JSON_MODE) {
-      // The engine's own surface, not a re-derivation: what it approved and what
-      // it saw must be the same object.
-      jsonOk({ package: r.package, level: r.level, approved: r.approved, skipped: r.skipped, approvedIntegrity, executableSurface: r.executableSurface, file: r.file });
-      return;
-    }
-    for (const c of r.approved) console.log(`Trusted executable surface for ${c} (from package ${r.package}, artifact ${approvedIntegrity[c] || "?"}).`);
-    if (r.skipped.length) console.log(`No executable surface (artifact integrity suffices, no approval needed): ${r.skipped.join(", ")}`);
-    return;
-  }
-  if (all) { cmdFail("unknown-capability", `no installed package "${id}" — --all-capabilities takes a package identity`); return; }
-  // Legacy standalone capability path.
-  const manifest = capabilityManifest(id, dir);
-  if (!manifest) { cmdFail("unknown-capability", `unknown capability "${id}"`); return; }
-  const lock = readCapabilityLocks(dir)[manifest.capability];
-  if (!lock) { cmdFail("invalid-lock", `${manifest.capability} is not locked in ${OATS_LOCK_FILE}`); return; }
-  const integrity = capabilityIntegrity(manifest._dir);
-  if (integrity !== lock.integrity) { cmdFail("integrity-drift", `integrity changed (${lock.integrity} → ${integrity}); reacquire explicitly before trusting`); return; }
-  const { _file, ...clean } = lock;
-  if (manifest.environment?.length) (JSON_MODE ? console.error : console.log)(`Requested launch environment: ${manifest.environment.join(", ")}`);
-  try { writeCapabilityLock(dirname(_file), manifest.capability, { ...clean, trustedExecutables: true }); }
-  catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
-  if (JSON_MODE) { jsonOk({ capability: manifest.capability, integrity, legacy: true, environment: [...(manifest.environment || [])] }); return; }
-  console.log(`Trusted executable surface for ${manifest.capability} at ${integrity}.`);
-}
-
-// ---------- package config profiles (oats init --package / oats config diff) ----------
-/** Collect every value of a repeatable flag (e.g. --accept-requirement a --accept-requirement b).
- * A missing or flag-shaped value is a usage error — one E_USAGE envelope in JSON mode. */
-function flagAll(name) {
-  const out = [];
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] !== `--${name}`) continue;
-    if (args[i + 1] && !args[i + 1].startsWith("--")) out.push(args[i + 1]);
-    else (JSON_MODE ? jsonFail("E_USAGE", `--${name} needs a value`) : die(`--${name} needs a value`));
-  }
-  return out;
-}
-
-/** Dependency-closure PROVIDER RECORDS for config-template validation.
- *
- * The flat model made this much smaller than its package-root ancestor: the
- * engine's lock reader walks raw lock-owning scopes rather than the config
- * chain, so a configless scope being initialized now sees its OWN lock without
- * the manual merge this used to need, and capability rows carry the provider
- * back-reference directly instead of package rows carrying capability lists.
- *
- * `staged` supplies the capabilities projected by THIS run's acquisition, which
- * are not locked yet when the pre-commit gate validates the template.
- * Returns { capabilities: Map<capabilityId, capabilityManifest|null> } — null
- * means lock-visible but not materialized, so layer agreement is unverifiable.
- */
-function dependencyClosureProviders(rootId, dir, staged = []) {
-  const capabilities = new Map();
-  let locks = { packages: {}, capabilities: {} };
-  try { locks = readPackageLocks(dir); } catch { /* invalid lock surfaces at acquire */ }
-
-  const closure = new Set();
-  const visit = (pkgId) => {
-    if (!pkgId || closure.has(pkgId) || !Object.hasOwn(locks.packages, pkgId)) return;
-    closure.add(pkgId);
-    for (const dep of locks.packages[pkgId].dependencies || []) visit(dep);
-  };
-  visit(rootId);
-
-  for (const [capId, row] of Object.entries(locks.capabilities)) {
-    if (!closure.has(row.package)) continue;
-    let manifest = null;
-    try {
-      const artifact = installedCapabilityDir(row._level, capId);
-      if (existsSync(join(artifact, "oats.json"))) manifest = JSON.parse(readFileSync(join(artifact, "oats.json"), "utf8"));
-    } catch { /* unreadable artifact is a doctor problem, not a validation input */ }
-    capabilities.set(capId, manifest);
-  }
-  // Same-run acquisition visibility: the root's own exports exist only in
-  // staging while the gate runs, and a template that binds them must validate.
-  // Preview rows carry the declared `layer` (null when none) — the minimum the
-  // layer-agreement check needs — so a staged capability is represented by that
-  // one field rather than a manifest the engine deliberately does not expose.
-  for (const c of staged) capabilities.set(c.capability, c.manifest ?? { layer: c.layer ?? null });
-  return { capabilities };
-}
-
-/** Adopt a template from a package ALREADY locked at this scope: read its exact
- * locked templates, validate, then write config + base + metadata under the run
- * journal. Nothing is fetched beyond the locked source, and nothing is
- * re-acquired — the lock is already the truth about what is installed here. */
-function initPackageFromLock(packageId, dir, file, lockedRoot, configFlag, bail, note) {
-  let locked, chosen;
-  try { locked = readLockedConfigTemplates(dir, packageId); }
-  catch (e) { bail(e.code || "E_TEMPLATE_READ_FAILED", e.message); return; }
-  try { chosen = selectConfigTemplate(locked.templates, configFlag, packageId); }
-  catch (e) { bail(e.code || "E_TEMPLATE_AMBIGUOUS", e.message); return; }
-
-  const errors = validateConfigTemplate(chosen, packageId, {
-    dependencyProviders: dependencyClosureProviders(packageId, dir).capabilities,
-  });
-  if (errors.length) bail("E_TEMPLATE_INVALID", `config template "${chosen.template}" of package ${packageId} failed validation:\n  - ${errors.join("\n  - ")}`);
-
-  note(`Package ${packageId}${locked.version ? `@${locked.version}` : ""} is already locked here — adopting its config template "${chosen.template}" without re-acquiring.`);
-
-  let journal;
-  try { journal = beginRunJournal(dir); }
-  catch (e) { bail(e.code || "E_JOURNAL_FAILED", e.message); return; }
-  let adoption;
-  try {
-    adoption = writeAdoptedTemplate(dir, file, {
-      package: packageId, template: chosen,
-      root: { source: locked.source, version: locked.version, commit: locked.commit, path: locked.path },
-    });
-    journal.finalize();
-  } catch (e) {
-    const report = journal.rollback();
-    bail("E_ADOPT_FAILED", report.complete ? e.message : `${e.message} — ${report.summary}`);
-    return;
-  }
-
-  const locks = readPackageLocks(dir);
-  const capabilities = Object.entries(locks.capabilities).filter(([, c]) => c.package === packageId).map(([id]) => id);
-  note(`Created ${shortPath(file)} (${levelOf(dir)} level) from config template ${packageId}:${chosen.template}`);
-  if (JSON_MODE) {
-    jsonOk({
-      package: packageId, version: locked.version || null, commit: locked.commit || null,
-      template: chosen.template, adopted: true, file, capabilities,
-      adoptedBase: adoption.baseFile, adoptionMetadata: adoption.metadataFile,
-      contentIntegrity: chosen.contentIntegrity,
-      lockFile: lockedRoot._file || join(dir, OATS_LOCK_FILE), lockedPackages: Object.keys(locks.packages),
-    });
-    return;
-  }
-  offerTmuxMouseScrolling();
-}
-
-/** oats init --package <source> [--config <name>]: acquire a package AND adopt
- * one of its config templates as this scope's local config.
- *
- * This command is adoption, not an install alias: `oats install <package>`
- * installs capabilities and applies no template, while this one always adopts
- * exactly one — the named template, else the single marked default, else the
- * only one. Several unmarked templates are E_TEMPLATE_AMBIGUOUS and a package
- * with none is E_NO_TEMPLATES; both refuse inside the pre-commit gate, so the
- * scope is never touched.
- *
- * Transaction shape: the outer journal opens BEFORE acquisition, so its
- * snapshot is the pre-command state. A gate refusal or acquire failure rolls it
- * back (the engine is zero-mutation there, so this mainly closes the backup); a
- * failure while writing the adoption files rolls back the lock, the capability
- * store, the ignore file, the config and the adopted base together — the
- * newly acquired state disappears and every pre-existing byte returns.
- * finalize() runs only after every adoption write has succeeded.
- *
- * JSON mode: one compact envelope. CLI codes E_TEMPLATE_INVALID /
- * E_TEMPLATE_AMBIGUOUS / E_TEMPLATE_NOT_FOUND / E_NO_TEMPLATES; engine codes
- * pass through verbatim. Fully noninteractive. */
-function initPackage(src, dir, file) {
-  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
-  const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
-  const configFlag = flag("config");
-  if (configFlag === true) bail("E_USAGE", "--config needs a template name");
-
-  let chosen = null;      // the selected+validated template descriptor
-  let rootRecord = null;  // the acquired root package row
-  let projected = [];     // projected capability rows
-
-  /** The pre-commit gate. Everything that can refuse refuses HERE, while the
-   * scope is still untouched. It THROWS rather than exiting: the process-exit
-   * path would strand the journal's backup, and the engine propagates a gate
-   * throw unchanged with nothing mutated. */
-  const assertCommittable = (preview) => {
-    rootRecord = preview.packages.find((p) => p.package === preview.root) || null;
-    projected = preview.capabilities || [];
-    const templates = (preview.configTemplates || []).filter((t) => t.package === preview.root);
-
-    note(`Package ${preview.root}${rootRecord?.version ? `@${rootRecord.version}` : ""} — installs ${projected.length} capability(ies): ${projected.map((c) => c.capability).join(", ") || "(none)"}`);
-    const executable = projected.filter((c) => c.executableSurface?.commands?.length || c.executableSurface?.hooks?.length || c.executableSurface?.environment?.length);
-    if (executable.length) note(`  executable surfaces needing separate approval: ${executable.map((c) => c.capability).join(", ")} (\`oats trust <id>\`)`);
-
-    chosen = selectConfigTemplate(templates, configFlag, preview.root); // throws typed codes
-    // Every check now refuses PRE-COMMIT, layer agreement included: preview
-    // capability rows carry the declared layer, so a template binding a slot to
-    // one of the package's own staged capabilities is validated here, with the
-    // scope untouched and no rollback needed.
-    const errors = validateConfigTemplate(chosen, preview.root, {
-      dependencyProviders: dependencyClosureProviders(preview.root, dir, projected).capabilities,
-    });
-    if (errors.length) {
-      const e = new Error(`config template "${chosen.template}" of package ${preview.root} failed validation:\n  - ${errors.join("\n  - ")}`);
-      e.code = "E_TEMPLATE_INVALID";
-      throw e;
-    }
-    note(`Config template "${chosen.template}"${chosen.description ? `: ${chosen.description}` : ""} — validated (${chosen.contentIntegrity})`);
-    note(`  it becomes YOUR local ${shortPath(file)}: every copied setting is editable, and package updates never rewrite it.`);
-  };
-
-  // Opened BEFORE acquisition: a snapshot taken afterwards would record the new
-  // lock, artifacts and ignore bytes as the "pre-existing" state and could
-  // never undo them.
-  // An id already locked at this scope is adopted from the LOCK, not
-  // re-acquired: its exact source/commit is already pinned, the capabilities are
-  // already materialized, and going to the network (or the catalog) to re-fetch
-  // what the lock already names would be a different package than the one
-  // installed here. This is the `oats init --package <id>` half of the documented
-  // <id|path|git-url> form.
-  let lockedRoot = null;
-  try { lockedRoot = readPackageLocks(dir).packages[src] || null; }
-  catch { /* an invalid lock surfaces with its own typed code below */ }
-  if (lockedRoot) { initPackageFromLock(src, dir, file, lockedRoot, configFlag, bail, note); return; }
-
-  // Constructed inside its own guard: a journal that cannot be built (a symlink
-  // component, an unreadable snapshot, a backup that would land inside the
-  // scope) must still leave the command with exactly one JSON envelope. There
-  // is nothing to roll back yet, so its typed code goes straight to bail.
-  let journal;
-  try { journal = beginRunJournal(dir); }
-  catch (e) { bail(e.code || "E_JOURNAL_FAILED", e.message); return; }
-
-  /** Undo the run, then report. `code` is the engine's verbatim code for
-   * acquisition failures and a stable CLI code for our own write failures — a
-   * raw errno like ENOTDIR is not a contract automation can branch on. */
-  const abort = (e, code) => {
-    const report = journal.rollback();
-    const detail = code === "E_ADOPT_FAILED" ? `adopting the config template failed after the package was installed: ${e.message}` : e.message;
-    bail(code || e.code || "E_INIT_FAILED", report.complete ? detail : `${detail} — ${report.summary}`);
-  };
-
-  let acq;
-  try { acq = acquirePackage(dir, src, { assertCommittable }); }
-  catch (e) { abort(e); return; }
-
-  note(`Acquired + locked: ${acq.installed.map((p) => `${p.package}@${p.version}`).join(", ")} → ${shortPath(acq.lockFile)}`);
-  const capabilities = acq.capabilities.map((c) => c.capability);
-
-  // DEFENCE IN DEPTH, not the primary check. The gate above already validated
-  // every binding against the preview's declared layers; this re-checks them
-  // against the manifests actually written to disk, so a projection that
-  // disagreed with its own preview cannot leave a broken config behind. It
-  // should never fire — and if it does, the journal restores the scope
-  // completely, so nothing of the run survives.
-  const materialized = new Map();
-  for (const c of acq.capabilities) {
-    let manifest = null;
-    try { manifest = JSON.parse(readFileSync(join(installedCapabilityDir(dir, c.capability), "oats.json"), "utf8")); }
-    catch { /* unreadable artifact is reported by doctor; leave it unverifiable */ }
-    materialized.set(c.capability, manifest);
-  }
-  for (const [id, m] of dependencyClosureProviders(acq.root, dir).capabilities) if (!materialized.has(id)) materialized.set(id, m);
-  const lateErrors = validateConfigTemplate(chosen, acq.root, { dependencyProviders: materialized });
-  if (lateErrors.length) {
-    const e = new Error(`config template "${chosen.template}" of package ${acq.root} failed validation:\n  - ${lateErrors.join("\n  - ")}`);
-    e.code = "E_TEMPLATE_INVALID";
-    abort(e);
-    return;
-  }
-
-  let adoption;
-  try {
-    adoption = writeAdoptedTemplate(dir, file, { package: acq.root, template: chosen, root: rootRecord });
-    journal.finalize();
-  } catch (e) { abort(e, "E_ADOPT_FAILED"); return; }
-
-  note(`Created ${shortPath(file)} (${levelOf(dir)} level) from config template ${acq.root}:${chosen.template}`);
-  note(`Recorded the adopted base at ${shortPath(adoption.baseFile)} — commit it; \`oats config diff\` and \`oats config sync\` compare against it.`);
-  if (JSON_MODE) {
-    jsonOk({
-      package: acq.root, version: rootRecord?.version || null, commit: rootRecord?.commit || null,
-      template: chosen.template, adopted: true, file, capabilities,
-      adoptedBase: adoption.baseFile, adoptionMetadata: adoption.metadataFile,
-      contentIntegrity: chosen.contentIntegrity,
-      lockFile: acq.lockFile, lockedPackages: acq.installed.map((p) => p.package),
-    });
-    return;
-  }
-  offerTmuxMouseScrolling();
-}
-
-/** `oats config <diff|sync|adopt>` — the guided three-way template lane.
- *
- * All three share one comparison: the recorded adopted base, the current local
- * oats-config.yaml, and the selected template read from the CURRENT EXACT LOCK.
- * Only `sync` and `adopt` mutate, and both present the complete plan first.
- */
-function configCmd() {
-  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
-  const sub = args[1];
-  if (!["diff", "sync", "adopt"].includes(sub)) {
-    bail("E_USAGE", "usage: oats config <diff|sync|adopt> [--config <template>] [--dir <dir>] [--json]");
-  }
-  const dir = resolve(flag("dir") || process.cwd());
-  const file = join(dir, "oats-config.yaml");
-  if (!existsSync(file)) bail("E_NO_CONFIG", `no oats-config.yaml at ${shortPath(dir)} — adopt one with \`oats init --package <source> --config <name>\``);
-  const localText = readFileSync(file, "utf8");
-
-  let adopted;
-  try { adopted = readAdoptedTemplate(dir); }
-  catch (e) { bail(e.code || "E_ADOPTION_INVALID", e.message); }
-
-  // `adopt` switches base; the others need an existing one.
-  const adoptTarget = sub === "adopt" ? args[2] : undefined;
-  if (sub === "adopt" && (!adoptTarget || adoptTarget.startsWith("--"))) {
-    bail("E_USAGE", "usage: oats config adopt <package> [--config <template>] — the package must already be installed at this scope");
-  }
-  if (sub !== "adopt" && !adopted) {
-    bail("E_NO_ADOPTED_BASE", `${shortPath(file)} was not adopted from a config template, so there is no recorded base to compare against — adopt one with \`oats config adopt <package> --config <name>\``);
-  }
-
-  const packageId = sub === "adopt" ? adoptTarget : adopted.package;
-  const templateFlag = flag("config");
-  if (templateFlag === true) bail("E_USAGE", "--config needs a template name");
-  const wanted = templateFlag || (sub === "adopt" ? undefined : adopted.template);
-
-  // Exact locked read — never the network-free guess, never a package root.
-  let locked;
-  try { locked = readLockedConfigTemplates(dir, packageId); }
-  catch (e) { bail(e.code || "E_TEMPLATE_READ_FAILED", e.message); }
-  let chosen;
-  try { chosen = selectConfigTemplate(locked.templates, wanted, packageId); }
-  catch (e) { bail(e.code || "E_TEMPLATE_AMBIGUOUS", e.message); }
-
-  // Switching base rebases the ONE local config against the new template.
-  //
-  // With no adopted base there is NO common ancestor, and pretending the local
-  // file is one is the dangerous answer: a three-way merge whose base equals
-  // local classifies every difference as upstream-only, so a first adopt would
-  // silently replace a handcrafted config wholesale — no conflicts, no consent,
-  // no preview of what was lost. An EMPTY base states the truth instead: every
-  // existing local byte is local work, and anything the template also wants to
-  // put there is a conflict the operator must resolve explicitly.
-  const baseText = adopted ? adopted.baseText : "";
-  const plan = planConfigMerge(baseText, localText, chosen.content);
-
-  const describe = (r) => ({
-    id: r.id, kind: r.kind, recommended: r.recommended, digest: r.digest,
-    startLine: r.local.start + 1, lines: r.local.end - r.local.start,
-    base: r.base.text, local: r.local.text, package: r.template.text,
-  });
-
-  if (sub === "diff") {
-    if (JSON_MODE) {
-      jsonOk({
-        package: packageId, template: chosen.template, version: locked.version || null, commit: locked.commit || null,
-        file, adoptedBase: adopted?.baseFile || null, contentIntegrity: chosen.contentIntegrity,
-        clean: plan.clean, counts: plan.counts, conflicts: plan.conflicts,
-        regions: plan.regions.map(describe), planDigest: plan.planDigest,
-      });
-      return;
-    }
-    console.log(`oats config diff — ${shortPath(file)} vs ${packageId}:${chosen.template}${locked.version ? `@${locked.version}` : ""} (report only; nothing is written)\n`);
-    if (!plan.regions.length) { console.log("No differences: your config, the adopted base, and the package template agree."); return; }
-    for (const r of plan.regions) renderMergeRegion(r);
-    console.log(`\n${plan.counts.upstream} upstream-only, ${plan.counts.local} local-only, ${plan.counts.conflict} conflict(s), ${plan.counts.agreed} already agreed.`);
-    console.log(plan.clean
-      ? "Apply the upstream changes with `oats config sync` (local-only edits are kept)."
-      : "`oats config sync` needs an explicit choice for each conflict — it will never pick one for you.");
-    return;
-  }
-
-  // ---- sync / reset / adopt: everything below MUTATES, so plan first ----
-
-  const decisions = {};
-  for (const spec of flagAll("accept")) {
-    const m = /^([^=]+)=(local|package)$/.exec(spec);
-    if (!m) bail("E_USAGE", `--accept takes <regionId>=<local|package>, got "${spec}"`);
-    decisions[m[1]] = m[2];
-  }
-  const assumeYes = args.includes("--yes");
-  const isReset = args.includes("--reset");
-
-  // The recoverable backup survives a SUCCESSFUL run: the run journal is for
-  // undoing failures, this is for the adopter who changes their mind.
-  const backupFile = `${file}.bak`;
-
-  if (isReset) {
-    // Reset previews everything it will destroy, then demands explicit consent.
-    const lost = plan.regions.filter((r) => r.kind === "local" || r.kind === "conflict");
-    if (JSON_MODE || !process.stdin.isTTY) {
-      if (!assumeYes) {
-        bail("E_RESET_NOT_CONFIRMED", `oats config sync --reset would discard ${lost.length} local change region(s) in ${shortPath(file)} and replace it with ${packageId}:${chosen.template} verbatim — pass --yes to accept that noninteractively`);
-      }
-    } else if (!assumeYes) {
-      console.log(`This DISCARDS ${lost.length} local change region(s) in ${shortPath(file)}:\n`);
-      for (const r of lost) renderMergeRegion(r);
-      const answer = promptLine(`Type the word "discard" to replace it with ${packageId}:${chosen.template}: `);
-      if (answer.trim() !== "discard") bail("E_RESET_NOT_CONFIRMED", "reset cancelled — nothing was changed");
-    }
-    const journal = openJournal(dir, bail);
-    try {
-      // NEVER copyFileSync onto a fixed backup path: it opens the destination
-      // for write and therefore FOLLOWS it, so a pre-planted
-      // `oats-config.yaml.bak` symlink would redirect this copy onto whatever it
-      // points at. The atomic form replaces the entry itself.
-      if (existsSync(file)) copyFileAtomic(file, backupFile);
-      writeFileAtomic(file, chosen.content);
-      recordAdoption(dir, file, packageId, chosen, locked, adopted);
-      journal.finalize();
-    } catch (e) { abortRun(journal, e, bail); return; }
-    if (JSON_MODE) { jsonOk({ action: "reset", package: packageId, template: chosen.template, file, backup: backupFile, discardedRegions: lost.length, contentIntegrity: chosen.contentIntegrity }); return; }
-    console.log(`Reset ${shortPath(file)} to ${packageId}:${chosen.template} verbatim. Previous contents saved at ${shortPath(backupFile)}.`);
-    return;
-  }
-
-  // sync / adopt share the three-way apply.
-  const unresolved = plan.conflicts.filter((id) => !Object.hasOwn(decisions, id));
-  if (unresolved.length) {
-    if (JSON_MODE || !process.stdin.isTTY) {
-      bail("E_SYNC_AMBIGUOUS", `${unresolved.length} conflict(s) need an explicit choice (${unresolved.join(", ")}) — pass --accept <id>=<local|package> for each; this command will never choose for you`);
-    }
-    for (const id of unresolved) {
-      const region = plan.regions.find((r) => r.id === id);
-      renderMergeRegion(region);
-      const answer = promptLine(`[${id}] keep (l)ocal or take (p)ackage? `).trim().toLowerCase();
-      if (answer === "l" || answer === "local") decisions[id] = "local";
-      else if (answer === "p" || answer === "package") decisions[id] = "package";
-      else bail("E_SYNC_AMBIGUOUS", `no choice made for ${id} — nothing was changed`);
-    }
-  }
-
-  let merged;
-  try { merged = applyConfigMerge(localText, plan, decisions); }
-  catch (e) { bail(e.code || "E_SYNC_FAILED", e.message); return; }
-
-  // Advancing the recorded base is the POINT of a sync, not a side effect of
-  // changing bytes. Deciding "keep local" on every conflict changes nothing on
-  // disk, but the decision must still be recorded — otherwise the base stays
-  // behind and the identical conflict is re-presented on every future sync,
-  // forever. So "nothing to do" means nothing applied AND the base already at
-  // this exact template.
-  const baseIsCurrent = adopted?.package === packageId
-    && adopted?.template === chosen.template
-    && adopted?.baseText === chosen.content;
-  if (!merged.applied.length && baseIsCurrent) {
-    if (JSON_MODE) { jsonOk({ action: sub, package: packageId, template: chosen.template, file, changed: false, baseAdvanced: false, applied: [], backup: null }); return; }
-    console.log(`Nothing to do: ${shortPath(file)} and the recorded base are already at ${packageId}:${chosen.template}.`);
-    return;
-  }
-
-  if (!JSON_MODE) {
-    console.log(`Plan for ${shortPath(file)} vs ${packageId}:${chosen.template}:`);
-    for (const a of merged.applied) console.log(`  [${a.id}] ${a.kind} → ${a.choice}`);
-    console.log("");
-  }
-
-  const changed = merged.text !== localText;
-  const journal = openJournal(dir, bail);
-  try {
-    // Back up only when bytes actually change — a backup identical to the file
-    // it shadows is noise the adopter has to reason about later.
-    if (changed) copyFileAtomic(file, backupFile);
-    if (changed) writeFileAtomic(file, merged.text);
-    recordAdoption(dir, file, packageId, chosen, locked, adopted);
-    journal.finalize();
-  } catch (e) { abortRun(journal, e, bail); return; }
-
-  if (JSON_MODE) {
-    jsonOk({
-      action: sub, package: packageId, template: chosen.template, file, changed,
-      baseAdvanced: true, applied: merged.applied, backup: changed ? backupFile : null,
-      adoptedBase: join(adoptedTemplateDir(dir, packageId, chosen.template), "oats-config.yaml"),
-      contentIntegrity: chosen.contentIntegrity,
-    });
-    return;
-  }
-  if (changed) console.log(`Applied ${merged.applied.length} change region(s) to ${shortPath(file)}; previous contents saved at ${shortPath(backupFile)}.`);
-  else console.log(`No bytes changed in ${shortPath(file)} — you kept every local choice.`);
-  console.log(`Adopted base advanced to ${packageId}:${chosen.template}, so these decisions will not be asked again. Local edits outside the applied regions are untouched.`);
-}
-
-/** Open the run journal with the command's one-envelope guarantee intact. */
-function openJournal(dir, bail) {
-  try { return beginRunJournal(dir); }
-  catch (e) { bail(e.code || "E_JOURNAL_FAILED", e.message); throw e; }
-}
-
-/** Undo a failed config mutation and report truthfully. */
-function abortRun(journal, e, bail) {
-  const report = journal.rollback();
-  bail(e.code || "E_CONFIG_WRITE_FAILED", report.complete ? e.message : `${e.message} — ${report.summary}`);
-}
-
-/** Write the adopted base + metadata for the template just synced against, and
- * retire any previously adopted base so exactly one survives. */
-function recordAdoption(dir, file, packageId, chosen, locked, previous) {
-  const written = writeAdoptedTemplate(dir, file, {
-    package: packageId, template: chosen,
-    root: { source: locked.source, version: locked.version, commit: locked.commit, path: locked.path },
-  }, { writeConfig: false });
-  if (previous && (previous.package !== packageId || previous.template !== chosen.template)) {
-    rmSync(previous.dir, { recursive: true, force: true });
-    const parent = dirname(previous.dir);
-    try { if (!readdirSync(parent).length) rmSync(parent, { recursive: true, force: true }); } catch { /* sibling templates remain */ }
-  }
-  return written;
-}
-
-/** Read one line from the terminal (human confirmation paths only). */
-function promptLine(question) {
-  process.stdout.write(question);
-  const buf = Buffer.alloc(1024);
-  let read = 0;
-  try { read = readSync(0, buf, 0, buf.length, null); } catch { return ""; }
-  return buf.subarray(0, read).toString("utf8").replace(/\n.*$/s, "");
-}
-
-/** One merge region, rendered for a human deciding what to do about it. */
-function renderMergeRegion(r) {
-  const label = {
-    upstream: "UPSTREAM ONLY  — the package template changed this; your config did not",
-    local: "LOCAL ONLY     — you changed this; the package template did not (it stays)",
-    conflict: "CONFLICT       — both changed this; an explicit choice is required",
-    agreed: "ALREADY AGREED — you and the package made the same change",
-  }[r.kind];
-  console.log(`[${r.id}] line ${r.local.start + 1}: ${label}`);
-  const block = (title, text) => {
-    if (!text) { console.log(`    ${title}: (nothing)`); return; }
-    for (const line of text.replace(/\n$/, "").split("\n")) console.log(`    ${title}: ${line}`);
-  };
-  if (r.kind !== "local") block("package", r.template.text);
-  if (r.kind !== "upstream") block("yours  ", r.local.text);
-  console.log("");
-}
-
-/** oats list — installed packages, exported capabilities, scopes. */
-/** `oats catalog [--json]` — the effective official package catalog, read-only.
- *  Identity/discovery for consumers that cannot import the kernel (Desktop):
- *  never acquires, never trusts, never fetches. */
-/** `oats instance <git|diff> <instance>` — K1: read-only Git observation of one
- *  instance's work tree. The instance is addressed qualified: an explicit
- *  --home, or a name under the --dir scope (team roots included) that resolves
- *  to exactly one home; several homes refuse with every candidate named. */
-function instanceCmd() {
-  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
-  const sub = args[1], name = args[2];
-  const usage = "usage: oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json]";
-  if (!["git", "diff", "stop", "events"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
-  dropAmbientRoot();
-  if (sub === "events") {
-    // K7: typed producer events, bounded window; nothing inferred.
-    const homeOpt = flag("home"); if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
-    let root; try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
-    const limit = flag("limit"); const since = flag("since");
-    if (limit === true || since === true) return bail("E_BAD_ARGS", usage);
-    try {
-      const { resolveInstance } = await_import_lifecycle();
-      // K7b: --home is an ADDRESS claim, checked like K1 — it must be a home of
-      // exactly this name under the scope (E_HOME_MISMATCH otherwise).
-      const home = resolveInstance(dirFlag(), root, name, homeOpt ? { home: homeOpt } : {}).home;
-      const ev = readEvents(home, { ...(limit !== undefined ? { limit: Math.max(1, Math.min(2000, Number(limit) || 200)) } : {}), ...(since ? { since } : {}) });
-      if (JSON_MODE) { jsonOk(ev); return; }
-      console.log(`${ev.instance}: ${ev.returned} of ${ev.count} event(s)${ev.truncated ? " (window truncated)" : ""}${ev.waitingOnYou ? ` — waiting on you since ${ev.waitingOnYou.since} (${ev.waitingOnYou.producer})` : ""}`);
-      for (const e of ev.events) console.log(`  ${e.at ?? "?"}  ${e.kind.padEnd(20)} ${e.producer}${e.data ? `  ${JSON.stringify(e.data).slice(0, 120)}` : ""}`);
-      return;
-    } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
-  }
-  if (sub === "stop") {
-    // K3: plan → apply. The plan is what a confirmation shows; apply carries
-    // its revision back and refuses if reality moved.
-    const homeOpt = flag("home");
-    if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
-    let root; try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
-    const recursive = !args.includes("--no-recursive");
-    const wantPlan = args.includes("--plan"), wantApply = args.includes("--apply");
-    if (wantPlan === wantApply) return bail("E_BAD_ARGS", "stop needs exactly one of --plan or --apply");
-    try {
-      if (wantPlan) {
-        const plan = planStop(dirFlag(), root, name, { home: homeOpt, recursive });
-        if (JSON_MODE) { jsonOk(plan); return; }
-        console.log(`stop ${name}${recursive ? " (and recorded children)" : ""} — plan ${plan.planRevision}`);
-        for (const t of plan.targets) console.log(`  ${"  ".repeat(t.depth)}${t.instance}: session ${t.session.state}${t.work.observed ? `, ${t.work.changed} changed / ${t.work.untracked} untracked on ${t.work.branch ?? "detached"}` : ", work not observed"}${t.midTask === true ? " — mid-task" : t.midTask === "unknown" ? " — activity unknown" : ""}`);
-        for (const n of plan.notes) console.log(`  note: ${n}`);
-        console.log(`apply with: oats instance stop ${name} --apply --plan-revision ${plan.planRevision} --idempotency-key <key>`);
-        return;
-      }
-      const rev = flag("plan-revision"), key = flag("idempotency-key"), grace = flag("grace-ms");
-      if (rev === true || key === true || grace === true) return bail("E_BAD_ARGS", usage);
-      const receipt = applyStop(dirFlag(), root, name, { home: homeOpt, recursive, planRevision: rev, idempotencyKey: key, ...(grace !== undefined ? { graceMs: Number(grace) } : {}) });
-      if (JSON_MODE) { jsonOk(receipt); return; }
-      for (const r of receipt.results) console.log(`  ${r.instance}: ${r.ok ? (r.stopped ? "stopped" : `already ${r.state}`) : `${r.code} — ${r.message}`}`);
-      console.log(receipt.ok ? `stopped${receipt.replayed ? " (replayed receipt)" : ""}; home, work, transcript and launch configuration retained — restart with \`oats session restart\`` : "some targets are still running; nothing was escalated");
-      if (!receipt.ok) process.exit(1);
-      return;
-    } catch (e) { return bail(e.code || "E_LIFECYCLE_FAILED", e.message, e.plan ? { plan: e.plan } : e.candidates ? { candidates: e.candidates } : undefined); }
-  }
-  let home = flag("home");
-  if (home === true) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
-  if (home !== undefined && !isAbsolute(home)) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
-  if (home === undefined) {
-    let root;
-    try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
-    let r; try { r = resolveOatsConfig(dirFlag()); } catch (e) { return bail(e.code || "E_CONFIG_BROKEN", e.message); }
-    const roots = [...new Set([root, ...(r.team ? teamAgentRoots(r.team.scope) : [])].map((p) => realOrResolved(p)))];
-    const candidates = [];
-    for (const rt of roots) for (const hit of findInstanceHomes(rt, name)) candidates.push({ root: rt, agent: hit.agent?.name ?? null, home: hit.home });
-    if (!candidates.length) return bail("E_SESSION_UNKNOWN", `no instance ${JSON.stringify(name)} under ${roots.join(", ")}`);
-    if (candidates.length > 1) return bail("E_AMBIGUOUS_INSTANCE", `instance ${JSON.stringify(name)} has ${candidates.length} homes; pass --home <abs>`, { candidates });
-    home = candidates[0].home;
-  } else if (basename(home) !== name) return bail("E_HOME_MISMATCH", `--home ${home} is not the home of instance ${JSON.stringify(name)}`);
-  try {
-    if (sub === "git") {
-      const observed = observeInstanceGit(home);
-      if (JSON_MODE) { jsonOk(observed); return; }
-      const o = observed.observation;
-      console.log(`${observed.instance} — ${shortPath(o.worktree)} @ ${o.branch ?? (o.detached ? `detached ${o.revision.slice(0, 12)}` : "unborn")}`);
-      console.log(`  upstream: ${observed.upstream.ref ? `${observed.upstream.ref} +${observed.upstream.ahead} -${observed.upstream.behind}` : "none (ahead/behind unknown)"}`);
-      console.log(`  base: ${observed.base.ref ? `${observed.base.ref} +${observed.base.ahead} -${observed.base.behind} (merge-base ${observed.base.mergeBase?.slice(0, 12)})` : "unknown"}`);
-      console.log(`  files: ${observed.files.length} (${Object.entries(observed.summary).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "clean"})`);
-      for (const f of observed.files) console.log(`    ${f.xy} ${f.origPath ? `${f.origPath} -> ` : ""}${f.path}  [${f.id}]`);
-      for (const n of observed.notes) console.log(`  note: ${n}`);
-      return;
-    }
-    const fileId = flag("file"), revision = flag("revision"), indexRevision = flag("index-revision");
-    if (fileId === true || revision === true || indexRevision === true) return bail("E_BAD_ARGS", usage);
-    const d = diffInstanceFile(home, { fileId, revision, indexRevision });
-    if (JSON_MODE) { jsonOk(d); return; }
-    console.log(`${d.file.origPath ? `${d.file.origPath} -> ` : ""}${d.file.path} (${d.file.kind}, against ${d.against})${d.binary ? " [binary]" : ""}${d.truncated ? ` [truncated at ${d.limit} bytes]` : ""}`);
-    if (!d.binary) process.stdout.write(d.patch);
-  } catch (e) {
-    bail(e.code || "E_GIT_FAILED", e.message, e.observation ? { observation: e.observation } : undefined);
-  }
-}
-/** `oats readiness [--soul <name> [--agents-root <abs>]] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json` — K5. */
-function readinessCmd() {
-  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
-  dropAmbientRoot();
-  // A captured incarnation's readiness comes from its retained resolution, not
-  // from the current configuration this command reads; refuse before inspecting.
-  const homeArg = flag("home");
-  if (homeArg && homeArg !== true) {
-    let capturedMeta = null; try { capturedMeta = JSON.parse(readFileSync(join(String(homeArg), "instance.json"), "utf8")); } catch { /* computeInspect reports the unreadable home */ }
-    if (capturedMeta?.executionBinding || capturedMeta?.captured) return bail("E_UNSUPPORTED_MODE", `${basename(String(homeArg))} is a captured incarnation: its readiness is the retained resolution's, not the current configuration's (inspect it with oats operation --deployment/--resolution)`, { home: String(homeArg), captured: true });
-  }
-  const inspect = computeInspect({ onFail: bail });
-  if (!inspect) return;
-  const soul = flag("soul") === true ? null : flag("soul") || inspect.selected?.soul || null;
-  const verify = args.includes("--verify-signatures");
-  let catalog = null; try { catalog = describeOfficialCatalog(); catalog = { packages: Object.fromEntries(catalog.packages.map((p) => [p.package, p])) }; } catch { catalog = null; }
-  const deploymentDir = inspect.scope?.context ?? null;
-  // Echo the exact selector this read was made with, so a consumer can bind the
-  // result to its own admitted target without inventing a revision.
-  // Every field is the argument AS GIVEN (no realpath): a consumer compares it
-  // byte-exact with what it sent. The canonical scope is subject.context.
-  const given = (name) => { const v = flag(name); return v && v !== true ? String(v) : null; };
-  const agentsRootArg = given("agents-root"), dirArg = given("dir");
-  const selector = homeArg && homeArg !== true ? { kind: "home", home: String(homeArg), soul, agentsRoot: agentsRootArg }
-    : soul ? { kind: "soul", soul, agentsRoot: agentsRootArg, dir: dirArg }
-    : { kind: "scope", dir: dirArg };
-  const readiness = readinessOf(inspect, { soul, verifySignatures: verify, catalog, deploymentDir, selector });
-  if (args.includes("--policy")) {
-    const homeOpt = flag("home");
-    let meta = null;
-    if (homeOpt && homeOpt !== true) { try { meta = JSON.parse(readFileSync(join(homeOpt, "instance.json"), "utf8")); } catch (e) { return bail("E_SESSION_UNKNOWN", `${homeOpt}: ${e.message}`); } }
-    readiness.policy = policyOf({ instanceMeta: meta, soul: soul ? inspect.souls.find((s) => s.name === soul) : null }).policy;
-    readiness.notes.push("policy: a lifecycle-authority claim enforced by the spawn route, not an OS sandbox");
-  }
-  if (JSON_MODE) { jsonOk(readiness); return; }
-  console.log(`readiness — ${readiness.subject.kind === "soul" ? `soul ${readiness.subject.name}` : shortPath(readiness.subject.context)}: ${readiness.summary.ready ? "READY" : `${readiness.summary.fail} failing, ${readiness.summary.unknown} unknown of ${readiness.summary.required} required`}`);
-  for (const [name, check] of Object.entries(readiness.checks)) {
-    console.log(`  ${name}: ${check.status}`);
-    for (const i of check.items) console.log(`    ${i.status.padEnd(14)} ${i.subject}${i.required ? "" : " (optional)"}${i.reason ? ` — ${i.reason}` : ""}${i.signature ? ` · signature ${i.signature.status}${i.signature.signer?.label ? ` by ${i.signature.signer.label}` : ""}` : ""}${i.remedy ? `  → ${i.remedy}` : ""}`);
-  }
-  if (readiness.policy) console.log(`  policy: child spawns ${readiness.policy.childSpawns.allowed ? "allowed" : "disabled"} (${readiness.policy.childSpawns.origin.kind}${readiness.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${readiness.policy.worktrees.allowed === null ? "unknown" : readiness.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
-  for (const n of readiness.notes) console.log(`  note: ${n}`);
-}
-function catalogCmd() {
-  const described = describeOfficialCatalog();
-  if (JSON_MODE) { jsonOk(described); return; }
-  console.log(`Official package catalog (${described.catalog.origin}: ${shortPath(described.catalog.file)})`);
-  for (const p of described.packages) console.log(`  ${p.package}  ${p.url ?? "?"}@${p.ref ?? "?"}  path: ${p.path}`);
-  if (described.capabilityAliases.length) {
-    console.log("Capability aliases:");
-    for (const a of described.capabilityAliases) console.log(`  ${a.capability} -> ${a.package}${a.capabilityInPackage !== a.capability ? ` (exports ${a.capabilityInPackage})` : ""}${a.available ? "" : "  [package not in catalog]"}`);
-  }
-  console.log("Catalog identity grants no executable trust; acquire with `oats install <package>` and approve separately.");
-}
-function listCmd() {
-  const dir = dirFlag();
-  // FAIL-CLOSED (maintainer finding 3): list RAISES on invalid locks — an
-  // invalid lock must never render as usable/absent data.
-  let pkgs, locks;
-  try { pkgs = listInstalledPackages(dir); locks = readPackageLocks(dir); }
-  catch (e) { JSON_MODE ? jsonFail(e.code || "invalid-lock", e.message || e) : die(e.message); return; }
-  // Packages are TRANSPORT; capabilities are what is installed. So the listing
-  // is capability-first: every row names its own provider, artifact, integrity,
-  // trust and health, and the package rows keep only what the transport itself
-  // pins. Trust is per capability — there is no package-level approval to list.
-  const capabilities = [];
-  for (const p of pkgs) {
-    const rows = levelRows(locks, p.level);
-    for (const c of p.capabilities) {
-      const h = capabilityHealth(p.level, c, rows.capabilities[c.id], rows.packages[p.package]);
-      capabilities.push({
-        capability: c.id, version: c.version || null, package: p.package, level: p.level,
-        path: c.path || null, dir: h.dir, integrity: c.integrity || null,
-        installedIntegrity: h.integrity ?? null,
-        layer: c.manifest?.layer || null, trusted: c.trusted === true, installed: c.installed,
-        executableSurface: {
-          commands: Object.keys(c.manifest?.commands || {}),
-          hooks: Object.keys(c.manifest?.hooks || {}),
-          environment: [...(c.manifest?.environment || [])],
-        },
-        status: h.status, code: h.code, detail: h.detail,
-      });
-    }
-  }
-  if (JSON_MODE) {
-    jsonOk({
-      packages: pkgs.map((p) => ({ package: p.package, version: p.version, level: p.level, source: p.source || null, path: p.path || null, commit: p.commit || null, integrity: p.integrity || null, locked: p.locked, dependencies: p.dependencies, capabilities: p.capabilities.map((c) => c.id) })),
-      capabilities,
-      legacy: locks.legacy.map((l) => ({ file: l.file, level: l.level, lockfileVersion: l.lockfileVersion, capabilities: Object.keys(l.capabilities) })),
-    });
-    return;
-  }
-  if (!pkgs.length) console.log("No installed packages in this config chain.");
-  const byPackage = new Map();
-  for (const c of capabilities) {
-    if (!byPackage.has(c.package)) byPackage.set(c.package, []);
-    byPackage.get(c.package).push(c);
-  }
-  for (const p of pkgs) {
-    console.log(`${p.package}@${p.version}  [${levelOf(p.level)} ${shortPath(p.level)}]${p.locked ? "" : "  UNLOCKED (no lock entry — reacquire)"}`);
-    if (p.source) console.log(`  source: ${p.source}  path: ${p.path || "?"}  commit: ${p.commit || "?"}`);
-    for (const c of byPackage.get(p.package) || []) {
-      const executable = c.executableSurface.commands.length || c.executableSurface.hooks.length || c.executableSurface.environment.length;
-      const trust = executable ? (c.trusted ? "  [trusted]" : "  [executable — needs oats trust]") : "";
-      console.log(`  capability ${c.capability}${c.layer ? `  layer: ${c.layer}` : ""}${trust}`);
-      // A capability whose bytes or provenance disagree with the lock is named
-      // as broken HERE — never rendered as an ordinary usable row.
-      if (c.status !== "ok" && c.status !== "untrusted") console.log(`    ${c.status.toUpperCase()}: ${c.detail}`);
-    }
-    if (p.dependencies.length) console.log(`  depends on: ${p.dependencies.join(", ")}`);
-  }
-  for (const l of locks.legacy) console.log(`Legacy capability locks (lockfileVersion ${l.lockfileVersion ?? 1}) in ${shortPath(l.file)}: ${Object.keys(l.capabilities).join(", ")} — \`oats migrate\` maps them to packages`);
-}
-
-/** oats remove <package> — refuses while config or dependent packages reference it. */
-function removeCmd() {
-  const id = args[1];
-  if (!id || id.startsWith("--")) JSON_MODE ? jsonFail("E_USAGE", "usage: oats remove <package> [--dir <dir>]") : die("usage: oats remove <package> [--dir <dir>]");
-  const dir = dirFlag();
-  let r;
-  try { r = removePackage(dir, id); } catch (e) { cmdFail(e.code || "remove-blocked", e.message || e); return; }
-  if (JSON_MODE) { jsonOk(r); return; }
-  // There is no package directory to name — a package is transport, and what
-  // actually leaves the disk is its materialized capability artifacts.
-  console.log(`Removed package ${r.package} from ${shortPath(r.lockFile)}.`);
-  console.log(r.capabilities.length
-    ? `  capabilities de-materialized: ${r.capabilities.join(", ")}`
-    : "  it supplied no capabilities at this scope.");
-}
-
-/** The team boundary a guided migration walks, when the scope declares one.
- * A config the kernel refuses to resolve is not a reason to abort a migration
- * that only reads locks — discovery falls back to the explicit scope and says so. */
-function migrationTeamScope(dir, warnings) {
-  try { return resolveOatsConfig(dir)?.team?.scope || undefined; }
-  catch (e) { warnings.push(`team boundary not resolved from ${shortPath(dir)} (${e.message}) — discovery covers this scope and its lock-owning ancestors only`); return undefined; }
-}
-
-const migratePlanRow = (s) => ({
-  capability: s.capabilityId, action: s.action,
-  package: s.package?.id || null, spec: s.package?.spec || null, via: s.package?.via || null,
-  migratesTo: s.migratesTo || null,
-  source: s.v1?.source || null, reason: s.reason || null, note: s.note || null,
-});
-
-/** `oats migrate --official` / `--recursive` — the guided existing-user upgrade.
- *
- * Plans EVERY visible lock-owning scope first (deterministic, side-effect
- * free), prints the complete per-scope plan, then applies scope by scope. Each
- * scope keeps the engine's transactional guarantee on its own: one scope's
- * failure leaves that scope byte-identical, never stops the others from being
- * reported truthfully, and makes the aggregate result nonzero. */
-function guidedMigrateCmd({ dir, dryRun, official, recursive }) {
-  const out = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
-  const opts = official ? { official: true } : {};
-  const warnings = [];
-  const teamScope = recursive ? migrationTeamScope(dir, warnings) : undefined;
-  let scopes;
-  try {
-    scopes = recursive
-      ? discoverMigrationScopes(dir, { teamScope })
-      : (existsSync(join(dir, OATS_LOCK_FILE)) ? [resolve(dir)] : []);
-  } catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
-  // Un-migrated OAS scopes are invisible to lock discovery (they own no
-  // oats-lock.json), and silence would read as "nothing to migrate" — the
-  // exact false success this probe exists to prevent (aweb-abfy.1).
-  const oasScopes = recursive ? discoverOasScopes(dir, { teamScope }) : detectOasScopes(dir);
-
-  // ---- plan every scope BEFORE touching any of them ----
-  const planned = [];
-  for (const scope of scopes) {
-    const file = join(scope, OATS_LOCK_FILE);
-    try {
-      const { plan, warnings: w } = migrateLegacyLock(scope, opts);
-      const held = plan.filter((s) => s.action === "hold");
-      const acquire = plan.filter((s) => s.action === "acquire");
-      const formatOnly = plan.some((s) => s.action === "convert-format");
-      const keep = plan.filter((s) => s.action === "retain" || s.action === "manual");
-      // Both modes are ALL-OR-NOTHING: a v2 lock has no residue container, so a
-      // scope converts completely or stays v1 in full. `keep` entries therefore
-      // make a scope unconvertible rather than partially convertible — apply
-      // refuses it, and the plan says so rather than promising "ready".
-      // Official mode also never rewrites a scope it has no official work in.
-      const convertible = acquire.length || formatOnly || (!official && plan.length);
-      const status = held.length ? "held"
-        : (convertible && !keep.length) ? "ready"
-        : convertible ? "blocked"
-        : "nothing";
-      planned.push({ scope, file, status, plan, acquire, keep, held, warnings: w });
-    } catch (e) {
-      planned.push({ scope, file, status: "failed", plan: [], acquire: [], keep: [], held: [], warnings: [], error: { code: e.code || "invalid-lock", message: String(e.message || e) } });
-    }
-  }
-  const planRows = planned.map((p) => ({
-    level: p.scope, levelKind: levelOf(p.scope), file: p.file, status: p.status,
-    plan: p.plan.map(migratePlanRow), warnings: p.warnings, error: p.error || null,
-  }));
-
-  const actionable = planned.filter((p) => p.status === "ready" || p.status === "format-only");
-  out(`oats migrate${official ? " --official" : ""}${recursive ? " --recursive" : ""} — ${scopes.length} lock-owning scope${scopes.length === 1 ? "" : "s"} from ${shortPath(dir)}`);
-  for (const w of warnings) out(`WARNING: ${w}`);
-  if (!scopes.length) out(oasScopes.length
-    ? "  (no oats-lock.json found — but this is NOT an empty scope: un-migrated OAS files are present, see below)"
-    : "  (no oats-lock.json found — nothing to migrate)");
-  for (const f of oasScopes) {
-    out(`\n  ${shortPath(f.dir)}  UN-MIGRATED OAS SCOPE  (${f.files.join(", ")})`);
-    out(`    HELD       ${OAS_SCOPE_REMEDY}`);
-  }
-  for (const p of planned) {
-    out(`\n  ${shortPath(p.scope)}  [${levelOf(p.scope)}]  ${shortPath(p.file)}`);
-    if (p.status === "failed") { out(`    ERROR      ${p.error.message} [${p.error.code}]`); continue; }
-    for (const s of p.plan) {
-      if (s.action === "convert-format") out(`    format     ${s.note}`);
-      else if (s.action === "acquire") out(`    migrate    ${s.capabilityId} → package ${s.package.id || s.package.spec}${s.migratesTo ? `  (catalog alias: package ${s.package.id} exports ${s.migratesTo}, replacing ${s.capabilityId})` : s.package.via === "alias" ? `  (catalog alias: package ${s.package.id} exports ${s.capabilityId})` : s.package.via === "identity" ? "  (official catalog)" : ""}`);
-      else if (s.action === "hold") out(`    HELD       ${s.capabilityId} — ${s.reason}`);
-      else out(`    keep       ${s.capabilityId}${s.v1?.source ? `  (${s.v1.source})` : ""} — not converted, entry kept unchanged`);
-    }
-    if (p.status === "nothing") out("    (nothing to migrate at this scope)");
-    if (p.status === "blocked") {
-      out(`    BLOCKED    this scope mixes convertible work with ${p.keep.length} entr${p.keep.length === 1 ? "y" : "ies"} that must stay lockfileVersion 1`);
-      out("               a capability-materialization lock has no place for them, so converting the rest would drop them — the WHOLE scope stays v1 and keeps working");
-    }
-    if (p.status === "ready") {
-      const renames = p.plan.filter((s) => s.migratesTo);
-      if (renames.length) out(`    config     ${shortPath(join(p.scope, "oats-config.yaml"))} is NOT rewritten — but renamed ids must be updated by hand after applying: ${renames.map((s) => `${s.capabilityId} → ${s.migratesTo}`).join(", ")}`);
-      else out(`    config     ${shortPath(join(p.scope, "oats-config.yaml"))} is NOT rewritten — capability ids, layers, targets, settings, exclusions and overrides stay valid (packages export the same ids)`);
-      out("    trust      executable approvals are NOT carried over — they are re-earned after migrating (exact commands below)");
-    }
-    for (const w of p.warnings) out(`    WARNING: ${w}`);
-  }
-
-  const result = {
-    mode: official ? "official" : "generic", recursive, dryRun,
-    boundary: resolve(dir), scopes: planRows, oasScopes, oasRemedy: oasScopes.length ? OAS_SCOPE_REMEDY : null,
-    trust: [], requirements: [], nextCommands: [], warnings,
-  };
-  if (dryRun) {
-    const failed = planned.filter((p) => p.status === "failed");
-    const held = planned.filter((p) => p.status === "held");
-    result.nextCommands = actionable.length ? [`oats migrate${official ? " --official" : ""}${recursive ? " --recursive" : ""} --dir ${shellQuote(dir)}`] : [];
-    // A held or unplannable scope is NOT a ready migration: the dry run says so
-    // with a nonzero result in both modes, so automation can never read
-    // "planned successfully" as "this deployment can migrate now"
-    // (reviewer-90dbb36). The complete plan travels under error.details.
-    const mixed = planned.filter((p) => p.status === "blocked");
-    const blocked = [
-      ...(held.length ? [`${held.length} scope${held.length > 1 ? "s" : ""} held (no official package mapping yet)`] : []),
-      ...(mixed.length ? [`${mixed.length} scope${mixed.length > 1 ? "s" : ""} blocked (entries that must stay lockfileVersion 1)`] : []),
-      ...(failed.length ? [`${failed.length} scope${failed.length > 1 ? "s" : ""} could not be planned`] : []),
-      ...(oasScopes.length ? [`${oasScopes.length} un-migrated OAS scope${oasScopes.length > 1 ? "s" : ""} detected (${oasScopes.map((f) => shortPath(f.dir)).join(", ")}) — no oas-* name is recognized and there is no automatic path yet; see docs/migration-from-oas.md`] : []),
-    ];
-    if (JSON_MODE) {
-      if (blocked.length) { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code: "E_MIGRATE_FAILED", message: `${blocked.join("; ")} (${actionable.length} ready)`, details: result } })); process.exit(1); }
-      jsonOk(result);
-      return;
-    }
-    out(`\nDry run — nothing was changed. ${actionable.length} scope${actionable.length === 1 ? "" : "s"} ready${held.length ? `, ${held.length} held` : ""}${mixed.length ? `, ${mixed.length} blocked` : ""}${failed.length ? `, ${failed.length} failed` : ""}.`);
-    if (actionable.length) out(`Apply with: oats migrate${official ? " --official" : ""}${recursive ? " --recursive" : ""} --dir ${shellQuote(dir)}`);
-    if (held.length) out("Held scopes stay on their v1 locks and their legacy capabilities keep working — re-run when the catalog publishes their packages.");
-    if (mixed.length) out("Blocked scopes stay on their v1 locks IN FULL and keep working — migration is all-or-nothing because a v2 lock has no place for an unconverted entry.");
-    if (blocked.length) die(`${blocked.join("; ")} (${actionable.length} ready)`);
-    return;
-  }
-
-  // ---- apply, scope by scope (each independently transactional) ----
-  const failures = [];
-  // An un-migrated OAS scope is a failure, not an absence: apply must never
-  // report overall success while one sits in the migrated universe.
-  for (const f of oasScopes) {
-    failures.push({ scope: f.dir, code: "oas-scope-unmigrated", message: `un-migrated OAS scope (${f.files.join(", ")}) — ${OAS_SCOPE_REMEDY}` });
-  }
-  for (const [i, p] of planned.entries()) {
-    const row = planRows[i]; // planRows is built from planned, in order
-    if (p.status === "failed") { row.status = "failed"; failures.push({ scope: p.scope, code: p.error.code, message: p.error.message }); continue; }
-    if (p.status === "held") {
-      row.status = "held";
-      failures.push({ scope: p.scope, code: "official-mapping-unavailable", message: `held: ${p.held.map((s) => `${s.capabilityId} (${s.reason})`).join("; ")}` });
-      out(`\nHELD      ${shortPath(p.scope)} — left unchanged; its legacy capabilities keep working`);
-      continue;
-    }
-    if (p.status === "nothing") {
-      // No official work here, so nothing is applied and nothing is rewritten.
-      // Say what the scope KEPT — `retained`, never `residue`: these entries
-      // were not left beside a conversion, there simply was no conversion.
-      row.status = "skipped";
-      if (p.keep.length) row.retained = p.keep.map((k) => k.capabilityId).filter(Boolean);
-      continue;
-    }
-    let r;
-    try { r = applyLegacyLockMigration(p.scope, opts); }
-    catch (e) {
-      row.status = "failed";
-      row.error = { code: e.code || "legacy-lock", message: String(e.message || e) };
-      failures.push({ scope: p.scope, code: row.error.code, message: row.error.message });
-      out(`\nFAILED    ${shortPath(p.scope)} — ${row.error.message}`);
-      continue;
-    }
-    row.status = r.skipped ? "skipped" : r.formatConverted ? "format-converted" : "migrated";
-    row.migrated = r.migrated;
-    // `retained` exists only for a SKIPPED scope left entirely on v1; a scope
-    // that converts leaves nothing behind, and a mixed one is refused above.
-    if (r.retained) row.retained = r.retained;
-    row.warnings = r.warnings;
-    for (const t of r.trust || []) result.trust.push({ ...t, command: `oats trust ${t.capability} --dir ${shellQuote(p.scope)}` });
-    out(`\n  ${shortPath(p.scope)}:`);
-    for (const m of r.migrated) out(`    migrated   ${m.capability} → package ${m.package}@${m.version}${m.migratedTo ? `  (as ${m.migratedTo})` : ""}`);
-    for (const c of r.retained || []) out(`    retained   ${c}  (this scope stays lockfileVersion 1, unchanged)`);
-    for (const w of r.warnings) out(`    WARNING: ${w}`);
-    if (r.formatConverted) out(`    format     empty lockfileVersion 1 file → canonical v2`);
-    else if (!r.skipped) out(`    ${shortPath(r.file)} is now lockfileVersion 2 — config activation (from: installed) is unchanged`);
-  }
-
-  // ---- exact next commands: trust first, then the requirement/install pass ----
-  const migratedScopes = planRows.filter((r) => r.status === "migrated").map((r) => r.level);
-  let requirements = [];
-  try { requirements = migratedScopes.length ? aggregateMissingRequirements(migratedScopes) : []; }
-  catch (e) { result.warnings.push(`host requirements not aggregated: ${e.message}`); }
-  result.requirements = requirements.map((req) => ({
-    command: req.command, requestedBy: req.requestedBy,
-    consentCommand: req.plan && !req.plan.unavailable && !req.invalid && !req.conflict
-      ? `oats install --accept-requirement ${req.command} --dir ${shellQuote(dir)}` : null,
-  }));
-  result.nextCommands = [
-    ...result.trust.map((t) => t.command),
-    ...result.requirements.filter((q) => q.consentCommand).map((q) => q.consentCommand),
-    `oats install --dir ${shellQuote(dir)}`,
-  ];
-
-  if (JSON_MODE) {
-    if (failures.length) { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code: "E_MIGRATE_FAILED", message: `${failures.length} scope${failures.length > 1 ? "s" : ""} not migrated (${planRows.filter((r) => r.status === "migrated").length} migrated)`, details: result } })); process.exit(1); }
-    jsonOk(result);
-    return;
-  }
-  out("\nNext steps:");
-  if (result.trust.length) {
-    out("  1. Review and approve the executable surfaces (approvals are never carried over):");
-    for (const t of result.trust) out(`       ${t.command}`);
-  } else out("  1. No executable surfaces to approve.");
-  for (const q of result.requirements) {
-    if (q.consentCommand) out(`  *  Missing host command ${q.command}: ${q.consentCommand}`);
-  }
-  out(`  2. Verify the runtime closure and host requirements (already-installed requirements are not reinstalled):`);
-  out(`       oats install --dir ${shellQuote(dir)}`);
-  if (failures.length) {
-    out("\nFailures by scope:");
-    for (const f of failures) out(`  ${shortPath(f.scope)}: ${f.message} [${f.code}]`);
-    die(`${failures.length} scope${failures.length > 1 ? "s" : ""} not migrated (${planRows.filter((r) => r.status === "migrated").length} migrated)`);
-  }
-}
-
-/** `oats migrate --from-oas` — one transactional conversion per scope: rename
- * the OAS-named artifacts (breaks 1-3 of docs/migration-from-oas.md), then
- * chain the guided v1→v2 lock conversion under the SAME journal, so a failure
- * in either phase restores the original OAS bytes. Break 4 (stale v1
- * integrity) is resolved by re-acquisition, never by recomputing integrity. */
-function fromOasCmd({ dir, dryRun, recursive }) {
-  const out = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
-  const warnings = [];
-  const teamScope = recursive ? migrationTeamScope(dir, warnings) : undefined;
-  let scopes;
-  if (recursive) scopes = discoverOasScopes(dir, { teamScope }).map((f) => f.dir);
-  else {
-    const chain = detectOasScopes(dir);
-    scopes = chain.filter((f) => f.dir === resolve(dir)).map((f) => f.dir);
-    if (!scopes.length && chain.length) {
-      cmdFail("E_BAD_ARGS", `no OAS scope files at ${resolve(dir)}, but an ancestor has them (${chain.map((f) => shortPath(f.dir)).join(", ")}) — run with --dir <that scope>, or --recursive to convert every visible OAS scope`);
-      return;
-    }
-  }
-  if (!scopes.length) {
-    // Idempotency contract: a second run finds nothing and says so, exit 0.
-    if (JSON_MODE) { jsonOk({ mode: "from-oas", recursive, dryRun, boundary: resolve(dir), scopes: [], trust: [], nextCommands: [], warnings }); return; }
-    console.log("no oas-config.yaml / oas-lock.json found — nothing to migrate from OAS");
-    return;
-  }
-
-  const results = [];
-  const trust = [];
-  let failures = 0;
-  for (const scope of scopes) {
-    const plan = planFromOasScope(scope);
-    const row = { scope, status: null, steps: plan.steps.map((s) => ({ kind: s.kind, from: s.from, to: s.to, note: s.note })), errors: plan.errors, plan: [], migrated: [], warnings: [] };
-    results.push(row);
-    if (plan.errors.length) { row.status = "failed"; failures++; continue; }
-    if (dryRun) {
-      // Phase-2 preview against a temp mirror of the lock alone — guided
-      // planning reads nothing else, so the preview is exact and touch-free.
-      const lockStep = plan.steps.find((s) => s.to.endsWith(OATS_LOCK_FILE));
-      if (lockStep) {
-        const mirror = mkdtempSync(join(tmpdir(), "oats-from-oas-plan-"));
-        try {
-          copyFileSync(lockStep.from, join(mirror, OATS_LOCK_FILE));
-          const { plan: mplan, warnings: mw } = migrateLegacyLock(mirror, { official: true });
-          row.plan = mplan.map(migratePlanRow);
-          row.warnings = mw;
-          row.status = mplan.some((s) => s.action === "hold" || s.action === "manual") ? "held" : "ready";
-          if (row.status === "held") failures++;
-        } catch (e) { row.status = "failed"; row.errors.push(String(e.message || e)); failures++; }
-        finally { rmSync(mirror, { recursive: true, force: true }); }
-      } else row.status = "ready";
-      continue;
-    }
-    let journal;
-    try { journal = applyFromOasScope(scope, plan); }
-    catch (e) { row.status = "failed"; row.errors.push(String(e.message || e)); failures++; continue; }
-    try {
-      const r = applyLegacyLockMigration(scope, { official: true });
-      journal.finalize();
-      row.status = "migrated";
-      row.migrated = r.migrated;
-      // Phase 1 already rewrote the config's capability ids, so the guided
-      // "update references in oats-config.yaml" warnings are satisfied here.
-      row.warnings = r.warnings.filter((w) => !/update references in oats-config\.yaml/.test(w));
-      for (const t of r.trust || []) trust.push({ ...t, command: `oats trust ${t.capability} --dir ${shellQuote(scope)}` });
-    } catch (e) {
-      journal.rollback();
-      row.status = "failed";
-      row.errors.push(`${String(e.message || e)} — scope restored to its original OAS state`);
-      failures++;
-    }
-  }
-
-  out(`oats migrate --from-oas${recursive ? " --recursive" : ""}${dryRun ? " --dry-run" : ""} — ${scopes.length} OAS scope${scopes.length === 1 ? "" : "s"} from ${shortPath(dir)}`);
-  for (const w of warnings) out(`WARNING: ${w}`);
-  for (const row of results) {
-    out(`\n  ${shortPath(row.scope)}  [${row.status}]`);
-    for (const s of row.steps) out(`    ${s.kind === "rewrite" ? "rewrite " : "rename  "}  ${shortPath(s.from)} → ${shortPath(s.to)}  (${s.note})`);
-    for (const p of row.plan) out(`    migrate    ${p.capability} → package ${p.package}${p.migratesTo ? ` (as ${p.migratesTo})` : ""}  [${p.action}]`);
-    for (const m of row.migrated) out(`    migrated   ${m.capability} → package ${m.package}@${m.version}${m.migratedTo ? `  (as ${m.migratedTo})` : ""}`);
-    for (const e of row.errors) out(`    ERROR      ${e}`);
-    for (const w of row.warnings) out(`    WARNING: ${w}`);
-  }
-  const nextCommands = [...trust.map((t) => t.command), ...(results.some((r) => r.status === "migrated") ? [`oats install --dir ${shellQuote(dir)}`] : [])];
-  const result = { mode: "from-oas", recursive, dryRun, boundary: resolve(dir), scopes: results, trust, nextCommands, warnings };
-  if (JSON_MODE) {
-    if (failures) { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code: "E_FROM_OAS_FAILED", message: `${failures} scope${failures > 1 ? "s" : ""} not converted (${results.filter((r) => r.status === "migrated" || r.status === "ready").length} ${dryRun ? "ready" : "converted"})`, details: result } })); process.exit(1); }
-    jsonOk(result);
-    return;
-  }
-  if (!dryRun && nextCommands.length) {
-    out("\nNext steps:");
-    for (const c of nextCommands) out(`  ${c}`);
-  }
-  if (dryRun) out(`\nDry run — nothing was changed. Apply with: oats migrate --from-oas${recursive ? " --recursive" : ""} --dir ${shellQuote(dir)}`);
-  if (failures) die(`${failures} scope${failures > 1 ? "s" : ""} not converted`);
-}
-
-/** oats migrate — map this scope's v1 marketplace capability locks to package locks. */
-function migrateCmd() {
-  const dir = dirFlag();
-  const dryRun = args.includes("--dry-run");
-  if (args.includes("--from-oas")) { fromOasCmd({ dir, dryRun, recursive: args.includes("--recursive") }); return; }
-  if (args.includes("--official") || args.includes("--recursive")) {
-    guidedMigrateCmd({ dir, dryRun, official: args.includes("--official"), recursive: args.includes("--recursive") });
-    return;
-  }
-  if (dryRun) {
-    let plan, warnings;
-    try { ({ plan, warnings } = migrateLegacyLock(dir)); }
-    catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
-    if (!plan.length) {
-      // "Nothing to migrate" on an OAS scope is a false success: the scope is
-      // not empty, it is pre-rename, and this kernel cannot read it (aweb-abfy.1).
-      const oas = detectOasScopes(dir);
-      if (oas.length) { cmdFail("oas-scope-unmigrated", `nothing this command can migrate here, but un-migrated OAS scope files exist (${oas.map((f) => `${shortPath(f.dir)}: ${f.files.join(", ")}`).join("; ")}) — ${OAS_SCOPE_REMEDY}`); return; }
+  let lockFile;
+  try { lockFile = writeLock(ctx.deploymentDir, lock); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  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 };
+}
+
+/** The human §8 report of a sync (text mode). */
+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(`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);
+    return `${p.id} ${p.version} ✓ (${p.approved ? "approved" : need ? "approval needed" : "unapproved"})`;
+  }).join("   ") || "(none)"}`);
+  const changed = changes.filter((c) => c.to !== null && c.from !== c.to).map((c) => `${c.id}  ${c.from ?? "—"} → ${c.to} (@ ${short(c.commit)})`);
+  const removed = changes.filter((c) => c.to === null).map((c) => `${c.id}  ${c.from} → removed`);
+  console.log(`changed    ${[...changed, ...removed].join("   ") || "(nothing — the lock already described this workspace)"}`);
+  const memberSouls = items.souls.filter((s) => s.kind === "member");
+  const externalSouls = items.souls.filter((s) => s.kind === "external");
+  const privateSouls = memberSouls.filter((s) => s.private);
+  const disabledHere = items.souls.filter((s) => disabled.has(s.name));
+  console.log(`souls      ${items.souls.length} discovered (${memberSouls.length} members, ${externalSouls.length} external, ${disabledHere.length} disabled here) · ${privateSouls.length} private${privateSouls.length ? ` (${privateSouls.map((s) => `${s.name}, ${memberLabel(s.repoKey)} only`).join("; ")})` : ""}`);
+  const teams = new Map();
+  for (const s of items.souls) { const t = teams.get(s.team) || { souls: 0, capabilities: 0 }; t.souls++; teams.set(s.team, t); }
+  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}`);
+  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)}`);
+}
+
+/** `oats sync [--dir] [--json]` — contract §6. */
+async function syncCmd() {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  const ctx = workspaceContext(bail);
+  const synced = await performSync(ctx, bail);
+  // One envelope (or the §8 report), then the exit status: 2 = the lock is written but approvals
+  // are pending. exitCode (not process.exit) lets stdout drain when it is a pipe.
+  if (JSON_MODE) jsonOk(synced.report); else printSyncReport(ctx, synced);
+  process.exitCode = synced.approvalNeeded.length ? 2 : 0;
+}
+
+/** Walk up from dir for oats-workspace.yaml INSIDE a Git checkout → { file, root } | null. */
+function workspaceCheckoutFrom(dir) {
+  let current = resolve(dir);
+  for (;;) {
+    const candidate = join(current, "oats-workspace.yaml");
+    if (existsSync(candidate)) {
+      // The file is edited in place only when it is TRACKED by the checkout it sits in (an untracked
+      // copy inside some repository is not the shared workspace file).
+      let inCheckout = false;
+      for (let d = current; ; d = dirname(d)) { if (existsSync(join(d, ".git"))) { inCheckout = true; break; } if (dirname(d) === d) break; }
+      if (!inCheckout) return null;
+      const tracked = spawnSync("git", ["-C", current, "ls-files", "--error-unmatch", "--", "oats-workspace.yaml"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
+      return tracked.status === 0 ? { file: candidate, root: current } : null;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** `oats package add <id> <version|git:<repo>@<ref>> | remove <id> [--dir]` — contract §6. */
+async function packageCmd() {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  const sub = args[1];
+  const id = args[2];
+  const value = sub === "add" && typeof args[3] === "string" && !args[3].startsWith("--") ? args[3] : undefined;
+  const usage = "usage: oats package add <id> <version|git:<repo>@<ref>> [--dir <d>] | oats package remove <id> [--dir <d>]";
+  if (!["add", "remove"].includes(sub) || !id || id.startsWith("--")) return bail("E_USAGE", usage);
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) return bail("E_WORKSPACE_SCHEMA", `package id ${JSON.stringify(id)} must match ^[a-z0-9][a-z0-9._-]*$`, { id });
+  if (sub === "add") {
+    if (!value || value.startsWith("--")) return bail("E_USAGE", usage);
+    const c = classifyPackageValue(value);
+    if (c.problem) return bail("E_WORKSPACE_SCHEMA", `packages.${id}: ${c.problem} (a package is a bare version like v2.1.3 or git:<repo>@<ref>)`, { id, value });
+    if (c.kind === "git") { try { remoteModule.parseRepoRef(c.repo); } catch (e) { return bail(e.code || "E_REPO_REF", e.message, e.details ?? e.provenance); } }
+  }
+  const line = sub === "add" ? `  ${id}: ${YAML.stringify(value).trim()}` : null;
+  const checkout = workspaceCheckoutFrom(dirFlag());
+  if (!checkout) {
+    // Untracked branch (the workspace file is shared through Git, not edited here). A `remove`
+    // still checks the id against the DISCOVERED workspace when this directory realizes one
+    // (oats-local.yaml): removing what is not declared is E_PACKAGE_MISSING, as in the tracked branch.
+    if (sub === "remove") {
+      let ctx = null; try { const found = loadLocal(dirFlag()); ctx = { dir: dirFlag(), localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() }; }
+      catch (e) { if (e?.code !== "E_LOCAL_MISSING") return bail(e.code || "E_WORKSPACE_SCHEMA", e.message, e.details); }
+      if (ctx) {
+        const discovery = await discoverForCli(ctx, bail);
+        const declared = discovery.standalone === true ? standalonePackages(catalogForSync(bail)).packages : (discovery.workspace?.packages || {});
+        if (!Object.hasOwn(declared, id)) return bail("E_PACKAGE_MISSING", `packages.${id} is not declared by workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${discovery.standalone === true ? " — standalone: only the kernel's default package is requested" : ""}`, { id, workspace: discovery.key, declared: Object.keys(declared).sort() });
+      }
     }
-    if (JSON_MODE) { jsonOk({ dryRun: true, plan, warnings }); return; }
-    if (!plan.length) { console.log("Nothing to migrate at this scope."); return; }
-    for (const s of plan) console.log(s.action === "convert-format" ? `${s.action.padEnd(14)} ${s.note}` : `${s.action.padEnd(10)} ${s.capabilityId}${s.package ? `  → ${s.package.spec}` : ""}`);
-    for (const w of warnings) console.log(`WARNING: ${w}`);
-    return;
-  }
-  let r;
-  try { r = applyLegacyLockMigration(dir); }
-  catch (e) {
-    const oas = detectOasScopes(dir);
-    const oasNote = oas.length ? ` NOTE: un-migrated OAS scope files exist (${oas.map((f) => `${shortPath(f.dir)}: ${f.files.join(", ")}`).join("; ")}) — ${OAS_SCOPE_REMEDY}` : "";
-    cmdFail(e.code || "legacy-lock", `${e.message || e}${oasNote}`); return;
-  }
-  if (JSON_MODE) { jsonOk(r); return; }
-  for (const m of r.migrated) console.log(`migrated  ${m.capability} → package ${m.package}@${m.version}`);
-  for (const w of r.warnings) console.log(`WARNING: ${w}`);
-  if (r.formatConverted) { console.log(`${shortPath(r.file)} was an empty lockfileVersion 1 file — converted to canonical v2.`); return; }
-  if (r.file) console.log(`${shortPath(r.file)} is now lockfileVersion 2. Config activation (from: installed) is unchanged; re-run \`oats trust\` for executable capabilities — package integrity approvals are not carried over.`);
-}
-
-/** oats update <package> — transactional package update with diff + trust reset. */
-function updatePackageCmd(id) {
-  const dir = dirFlag();
-  // --to <selector>: move a catalog-sourced lock to another catalog ref
-  // (tag) through the same transactional update. A lock with an explicit
-  // selector keeps it on a plain update by design; this is the operator's
-  // way to advance it without remove + reinstall.
-  // Two spellings: `oats update <id> <id>@<selector>` (the engine's own spec
-  // form) or `oats update <id> --to <selector>`.
-  const to = flag("to");
-  if (to === true) { cmdFail("E_BAD_ARGS", "--to needs a catalog selector, e.g. --to v1.10.1"); return; }
-  if (to !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(to)) { cmdFail("E_BAD_ARGS", `--to selector ${JSON.stringify(to)} is not a catalog ref`); return; }
-  const positional = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
-  if (positional && to !== undefined) { cmdFail("E_BAD_ARGS", "give either <id>@<selector> or --to <selector>, not both"); return; }
-  const spec = positional || (to !== undefined ? `${id}@${to}` : undefined);
-  let r;
-  try { r = updatePackage(dir, id, spec ? { spec } : {}); } catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
-  if (JSON_MODE) { jsonOk(r); return; }
-  // A moved package root is reported even when the bytes are identical: the
-  // lock now points somewhere else in the repository, and that is exactly the
-  // change an operator must see (contract §7).
-  const pathLine = () => console.log(`  package path ${r.before.path} → ${r.after.path} (the selected package root MOVED in the source)`);
-  if (!r.changed) {
-    console.log(`${r.package} is already up to date (${r.after.version}, ${r.after.integrity}).`);
-    if (r.pathChanged) pathLine();
+    if (JSON_MODE) { jsonOk({ action: sub, id, value: value ?? null, edited: false, file: null, line: sub === "add" ? `packages:\n${line}` : null, hint: "oats-workspace.yaml is not in this checkout; commit the change in the workspace repo, then `oats sync`" }); return; }
+    if (sub === "add") console.log(`oats-workspace.yaml is not in this checkout. Add under packages: in the workspace repo, then \`oats sync\`:\n\npackages:\n${line}`);
+    else console.log(`oats-workspace.yaml is not in this checkout. Remove \`${id}\` from packages: in the workspace repo, then \`oats sync\`.`);
     return;
   }
-  console.log(`Updated ${r.package}: ${r.before.version} (${r.before.commit}) → ${r.after.version} (${r.after.commit})`);
-  console.log(`  integrity ${r.before.integrity} → ${r.after.integrity}`);
-  if (r.pathChanged) pathLine();
-  if (r.addedCapabilities.length) console.log(`  + capabilities: ${r.addedCapabilities.join(", ")}`);
-  if (r.removedCapabilities.length) console.log(`  - capabilities: ${r.removedCapabilities.join(", ")}`);
-  for (const w of r.depWarnings || []) console.log(`WARNING: ${w}`);
-  if (r.invalidatedApprovals.length) console.log(`  APPROVALS INVALIDATED (integrity changed): ${r.invalidatedApprovals.join(", ")} — re-approve with \`oats trust\` after review.`);
-}
-
-// ---------- init ----------
-/**
- * oats init [--raw] [--dir <dir>] [--knowledge <id>] [--messaging <id>] [--tasks <id>]
- *
- * Per-layer flags name a canonical capability ID or "none". A layer is filled by
- * a capability already at this scope (own store first — no config exists yet, so
- * the config-chain walk cannot see it), otherwise by acquiring the official
- * PACKAGE that supplies it through the materialization engine. Acquisition is
- * not activation, not executable trust and not requirement consent, and the
- * whole run is one transaction that rolls back on any failure.
- */
-/** Resolve a template (name via outer-config `templates:` maps, local path, or git URL's
- * main-branch oats-config.yaml) into snapshot text with a provenance comment. */
-function loadTemplateConfig(spec, dir) {
-  // THROWS typed errors rather than exiting: `oats init --template` reports
-  // through the same single JSON envelope as every other init form.
-  const fail = (code, message) => { const e = new Error(message); e.code = code; throw e; };
-  let source = spec;
-  const isDirect = /^(https?:\/\/|git@|ssh:\/\/)/.test(spec) || spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("~");
-  if (!isDirect) {
-    let named;
-    for (const cfg of configChain(dir)) {
-      if (cfg.templates?.[spec]) { named = { value: cfg.templates[spec], level: cfg._level }; break; }
-    }
-    if (!named) fail("E_UNKNOWN_TEMPLATE", `unknown template "${spec}" — declare it under templates: in an outer oats-config.yaml, or pass a path/git URL`);
-    source = /^(https?:\/\/|git@|ssh:\/\/)/.test(named.value) || named.value.startsWith("/") || named.value.startsWith("~")
-      ? named.value : resolve(named.level, named.value);
-  }
-  let body, provenance;
-  if (/^(https?:\/\/|git@|ssh:\/\/)/.test(source)) {
-    const tmp = mkdtempSync(join(tmpdir(), "oats-template-"));
-    try {
-      execFileSync("git", ["clone", "-q", "--depth", "1", source, tmp], { stdio: "inherit" });
-      const cfgFile = join(tmp, "oats-config.yaml");
-      if (!existsSync(cfgFile)) fail("E_TEMPLATE_SOURCE", `template repo has no oats-config.yaml on its default branch: ${source}`);
-      body = readFileSync(cfgFile, "utf8");
-      const commit = execFileSync("git", ["-C", tmp, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
-      provenance = `${source}@${commit.slice(0, 12)}`;
-    } finally { rmSync(tmp, { recursive: true, force: true }); }
+  const text = readFileSync(checkout.file, "utf8");
+  let doc;
+  try { doc = YAML.parseDocument(text, { keepSourceTokens: true }); } catch (e) { return bail("E_WORKSPACE_SCHEMA", `${checkout.file}: ${e.message}`, { path: checkout.file }); }
+  if (doc.errors?.length) return bail("E_WORKSPACE_SCHEMA", `${checkout.file}: ${doc.errors.map((e) => e.message).join("; ")}`, { path: checkout.file });
+  const root = doc.contents;
+  if (!YAML.isMap(root)) return bail("E_WORKSPACE_SCHEMA", `${checkout.file}: top level must be a mapping`, { path: checkout.file, problems: [{ path: "", message: "top level must be a mapping" }] });
+  const packagesNode = root.get("packages", true);
+  if (packagesNode !== undefined && packagesNode !== null && !(YAML.isScalar(packagesNode) && packagesNode.value === null) && !YAML.isMap(packagesNode)) {
+    return bail("E_WORKSPACE_SCHEMA", `${shortPath(checkout.file)}: packages: must be a mapping of <package-id>: <version>, found ${YAML.isSeq(packagesNode) ? "a sequence" : JSON.stringify(packagesNode.toJSON?.() ?? String(packagesNode))}`, { path: checkout.file, problems: [{ path: "/packages", message: "must be an object" }] });
+  }
+  const previous = YAML.isMap(packagesNode) ? packagesNode.toJSON() : null;
+  const had = previous && Object.hasOwn(previous, id) ? previous[id] : undefined;
+  if (sub === "add") {
+    if (!YAML.isMap(packagesNode)) root.set("packages", doc.createNode({ [id]: value }));
+    else packagesNode.set(id, value);
   } else {
-    // Replacer FUNCTION, not a replacement string: `$&`, `$'`, `` $` `` and
-    // `$1` are substitution syntax in String.replace, and a home directory may
-    // legally contain them.
-    const path = resolve(source.replace(/^~\//, () => `${homedir()}/`));
-    if (!existsSync(path)) fail("E_TEMPLATE_SOURCE", `template config not found: ${path}`);
-    body = readFileSync(path, "utf8");
-    provenance = path;
-  }
-  // Snapshot: strip template-registry keys that make no sense in the seeded config.
-  const lines = body.replace(/\n*$/, "\n").split("\n");
-  const scaffoldName = scaffoldConfigName(dir);
-  const out = []; let skipping = false;
-  for (const line of lines) {
-    if (/^templates:\s*$/.test(line)) { skipping = true; continue; }
-    if (skipping) { if (/^\S/.test(line) && line.trim()) skipping = false; else continue; }
-    // Replacer FUNCTION, not a replacement string — this is a WRITE, so a
-    // directory named `x$&y` would otherwise persist a corrupted `name:` line
-    // (`name: xname: template-namey`).
-    out.push(line.replace(/^name:.*$/, () => `name: ${scaffoldName}`));
-  }
-  return `# template: ${provenance} (snapshot — later template edits do not propagate)\n${out.join("\n").replace(/\n*$/, "\n")}`;
+    if (had === undefined) return bail("E_PACKAGE_MISSING", `packages.${id} is not in ${shortPath(checkout.file)}`, { id, path: checkout.file });
+    root.get("packages").delete(id);
+    if (root.get("packages")?.items?.length === 0) root.delete("packages");
+  }
+  const next = doc.toString();
+  const problems = validateWorkspace(YAML.parse(next), { remote: remoteModule });
+  if (problems.length) return bail("E_WORKSPACE_SCHEMA", `${shortPath(checkout.file)} would be invalid: ${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}`, { path: checkout.file, problems });
+  writeFileAtomic(checkout.file, next);
+  const receipt = { action: sub, id, value: value ?? null, previous: had ?? null, edited: true, file: checkout.file };
+  if (JSON_MODE) { jsonOk(receipt); return; }
+  console.log(sub === "add"
+    ? `${had === undefined ? "Added" : `Changed (${had} →)`} packages.${id}: ${value} in ${shortPath(checkout.file)}. Commit it, then \`oats sync\` (the lock resolves the version to a commit and asks approval once).`
+    : `Removed packages.${id} (${had}) from ${shortPath(checkout.file)}. Commit it, then \`oats sync\`.`);
 }
 
-function init() {
-  const raw = args.includes("--raw");
-  const dir = dirFlag();
-  const file = join(dir, "oats-config.yaml");
-  const pkgSrc = flag("package");
-  // Every init form — classic, --template and --package — reports through the
-  // SAME one-envelope JSON boundary; nothing here may print two documents.
-  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
-  const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
-  if (existsSync(file)) bail("E_CONFIG_EXISTS", `${shortPath(file)} already exists — edit it or use \`oats use\``);
-  // The scaffolded `name:` value is FILESYSTEM input. Refuse it up front, before
-  // any init form mutates anything — a basename that cannot stay one YAML scalar
-  // must abort the run, not be discovered halfway through a transaction.
-  try { scaffoldConfigName(dir); }
-  catch (e) { bail(e.code, e.message); return; }
-
-  if (pkgSrc && pkgSrc !== true) { initPackage(pkgSrc, dir, file); return; }
-  if (pkgSrc === true) { bail("E_USAGE", "--package needs a package id, local path, or git URL"); return; }
-
-  const template = flag("template");
-  if (template && template !== true) {
-    let text;
-    try { text = loadTemplateConfig(template, dir); }
-    catch (e) { bail(e.code || "E_TEMPLATE_SOURCE", e.message); return; }
-    // Seeding is a transaction too. A template can carry keys this kernel
-    // refuses, or lock entries that will not restore; either way the config this
-    // run wrote must not be left behind for the next command to trip over, and
-    // the failure must be a typed error rather than an uncaught stack.
-    let journal;
-    try { journal = beginRunJournal(dir); }
-    catch (e) { bail(e.code || "E_JOURNAL_FAILED", e.message); return; }
-    let activated = [];
-    try {
-      writeFileSync(file, text);
-      note(`Created ${shortPath(file)} (${levelOf(dir)} level) from template ${template}`);
-      // The GATE is that the kernel can read this config: a template carrying a
-      // retired key or a broken shape is a broken template, and leaving it
-      // behind would break every later command at this scope.
-      configChain(dir);
-      restore(dir);
-      // Activation is NOT a gate. A template's whole point is to seed policy you
-      // then acquire — a capability it activates but nothing supplies yet is the
-      // expected state right after seeding, not a reason to refuse the config.
-      try { activated = resolveOatsConfig(dir).capabilities.map((c) => ({ capability: c.id, layer: c.layer || null })); }
-      catch (e) { note(`NOTE: ${shortPath(file)} does not resolve yet — ${e.message}. Acquire what it activates (\`oats install <source>\`), then re-check with \`oats doctor\`.`); }
-      journal.finalize();
-    } catch (e) {
-      const report = journal.rollback();
-      const detail = `${shortPath(file)} could not be seeded from template ${template}: ${e.message}`;
-      bail(e.code || "E_TEMPLATE_UNUSABLE", report.complete ? detail : `${detail} — ${report.summary}`);
-      return;
-    }
-    if (JSON_MODE) { jsonOk({ file, level: levelOf(dir), raw, adopted: false, template, acquired: [], activated, requirements: [] }); return; }
-    offerTmuxMouseScrolling();
-    return;
-  }
-  if (template === true) { bail("E_USAGE", "--template needs a name, local config path, or git URL"); return; }
-
-  // Per-layer overrides: --knowledge oats.okf, --messaging none, --tasks oats.jira …
-  const overrides = {};
-  const market = marketplaceCapabilities();
-  // Own-scope manifests are read DIRECTLY: no oats-config.yaml exists here yet,
-  // so the config-chain walk cannot see this scope's own store, and a
-  // capability already installed here would look unknown.
-  // Object.assign onto a null prototype, never an object spread: `{ ...map }`
-  // re-plainifies the null-prototype sources, and `mans[v]` is then indexed with
-  // a `--<layer>` value the operator typed — `--knowledge constructor` would
-  // read Object.prototype.constructor as a manifest and report a layer mismatch
-  // for a capability that does not exist.
-  const mans = Object.assign(Object.create(null), market, capabilityManifests(dir), ownScopeCapabilityManifests(dir));
-  for (const layer of LAYERS) {
-    const v = flag(layer);
-    if (v === undefined) continue;
-    if (v === true || String(v).startsWith("--")) bail("E_USAGE", `--${layer} needs a canonical capability ID or "none"`);
-    if (v !== "none") {
-      // Known locally: its declared layer is checkable right now, before any
-      // mutation. Otherwise the official catalog may still supply it, and the
-      // layer is verified against the MATERIALIZED manifest after acquisition —
-      // inside the run transaction, so a disagreement rolls the whole run back.
-      if (mans[v]) {
-        if (mans[v].layer !== layer) bail("E_LAYER_MISMATCH", `capability "${v}" declares layer "${mans[v].layer || "none"}", not "${layer}"`);
-      } else if (!officialCapabilityPackage(v).available) {
-        bail("E_UNKNOWN_CAPABILITY", `unknown capability "${v}" for --${layer} — it is not acquired at ${shortPath(dir)}, not in the marketplace (${Object.keys(market).join(", ") || "empty"}), and no official package supplies it (catalog: ${Object.keys(officialPackageCatalog()).join(", ") || "empty"})`);
-      }
-    }
-    overrides[layer] = v;
-  }
-
-  const defaults = raw
-    ? { knowledge: "none", messaging: "none", tasks: "none" }
-    : { knowledge: "oats.okf", messaging: "oats.aweb", tasks: undefined };
-  let layers = { ...defaults, ...overrides };
-
-  // Interactive TTY with no explicit layer flags: present each default and ask.
-  // Non-interactive contexts (agents, CI) keep flags-or-silent-defaults — never hang.
-  if (!raw && !JSON_MODE && process.stdin.isTTY && process.stdout.isTTY && !Object.keys(overrides).length) {
-    const byLayer = (l) => Object.values(mans).filter((m) => m.layer === l).map((m) => m.capability);
-    console.log("Fundamental layers for this scope — Enter keeps the default, or type a capability id / \"none\":");
-    const ask = (prompt) => {
-      process.stdout.write(prompt);
-      const buffer = Buffer.alloc(256);
-      let length = 0;
-      try { length = readSync(process.stdin.fd, buffer, 0, buffer.length); } catch { /* EOF */ }
-      return buffer.subarray(0, length).toString("utf8").trim();
-    };
-    for (const layer of LAYERS) {
-      const options = byLayer(layer);
-      const def = layers[layer] || "none";
-      while (true) {
-        const answer = ask(`  ${layer.padEnd(10)} [${def}]  (options: ${[...options, "none"].join(", ")}): `);
-        if (!answer) break;
-        if (answer === "none" || options.includes(answer)) { layers[layer] = answer; break; }
-        console.log(`    unknown "${answer}" — pick one of: ${[...options, "none"].join(", ")}`);
-      }
-    }
-    if ((layers.messaging || "none") !== "none") console.log("  (messaging via aweb: after init, run `oats aweb setup` for guided onboarding)");
-  }
-  // ---- Everything below MUTATES. It is ONE run-level transaction: the config
-  // file, the lock, the flat capability artifacts, the capability .gitignore
-  // and any `.agents` anchor this run creates roll back together. A capability
-  // that was already installed at this scope before the run is restored
-  // byte-identically — this run only ever undoes its own changes. ----
-  let journal;
-  try { journal = beginRunJournal(dir); }
-  catch (e) { bail(e.code || "E_JOURNAL_FAILED", e.message); return; }
-  const abort = (e, code) => {
-    const report = journal.rollback();
-    bail(code || e.code || "E_INIT_FAILED", report.complete ? e.message : `${e.message} — ${report.summary}`);
-  };
-
-  const acquisitions = [];
-  let resolved;
-  const lines = [
-    `name: ${scaffoldConfigName(dir)}`,
-    "",
-    "# ── Agent types (families) — declared here by name (or via `oats type add`);",
-    "# each soul opts in via `type: <name>` in its soul.yaml. Capability entries can target them.",
-    "# agent-types:",
-    "#   reviewers:",
-    "#     description: Agents that review changes",
-    "",
-    "capabilities:",
-    "  # Fundamental layers — exclusive slots; a capability entry or an explicit none.",
-    "  layers:",
-  ];
-  try {
-    for (const layer of LAYERS) {
-      const selected = layers[layer];
-      if (!selected) { lines.push(`    # ${layer}: (unset — inherits from outer config scopes; set an entry or "none")`); continue; }
-      if (selected === "none") { lines.push(`    ${layer}: none`); continue; }
-      // Already here (own scope first — see above), or acquired now.
-      const manifest = ownScopeCapabilityManifest(dir, selected)
-        || capabilityManifest(selected, dir)
-        || acquireLayerCapability(dir, selected, layer, acquisitions, note);
-      lines.push(`    ${layer}:`);
-      lines.push(`      capability: ${manifest.capability}`);
-      if (String(manifest._origin).startsWith("installed:")) { lines.push("      from: installed"); lines.push(`      # injection-override: .agents/injections/capabilities/${manifest.capability}.md`); }
-      else if (String(manifest._origin).startsWith("owned:")) { lines.push("      from: owned"); lines.push(`      # injection edited at source: .agents/capabilities/owned/${manifest.capability}/injects/`); }
-    }
-    lines.push(
-      "  # Additive capabilities — non-exclusive; target global, agent-types, or souls.",
-      "  # additive:",
-      "  #   <capability-id>:",
-      "  #     from: installed",
-      "  #     global: true",
-      "  #     # injection-override: .agents/injections/capabilities/<capability-id>.md",
-      "",
-      "# ── Work modes — optional per-mode env bootstrap.",
-      "# `setup:` runs inside each NEW worktree right after `git worktree add` — use it",
-      "# for env setup scripts (installs, .env copying, direnv, mise, etc.).",
-      "# The path is relative to this config's directory.",
-      "work-modes:",
-      "  worktree:",
-      "    # setup: scripts/setup-worktree.sh",
-      "",
-      "# ── OATS defaults — the framework's baseline instruction block.",
-      "oats:",
-      "  # injection-override: .agents/injections/oats-defaults/oats.md",
-    );
-    writeFileSync(file, lines.join("\n") + "\n");
-    // Resolve INSIDE the transaction: a config this run wrote that cannot
-    // resolve is a broken scope, so it fails the init and rolls back rather
-    // than being left behind for the next command to trip over.
-    resolved = resolveOatsConfig(dir);
-    journal.finalize();
-  } catch (e) { abort(e); return; }
-
-  note(`Created ${shortPath(file)} (${levelOf(dir)} level${raw ? ", raw" : ""})`);
-  // Acquisition is not activation, not executable trust, and not requirement
-  // consent — say so per acquisition rather than implying the layer is ready.
-  for (const a of acquisitions) {
-    if (!a.executableSurface.length) continue;
-    note(`Executable surfaces from ${a.package || "the marketplace"} are blocked until trusted: ${a.executableSurface.map((c) => `oats trust ${c}`).join("; ")}`);
-  }
-
-  const r = resolved;
-  const activated = [];
-  for (const cap of r.capabilities) {
-    activated.push({ capability: cap.id, layer: cap.layer || null });
-    note(`Activated: ${cap.id}${cap.layer ? ` → ${cap.layer}` : ""}`);
-    for (const miss of cap.missingRequires) note(`WARNING: required command "${miss.command}" not on PATH — ${miss.why || ""}${miss.install ? ` (install: ${miss.install})` : ""}`);
-  }
-  if (JSON_MODE) {
-    jsonOk({
-      file, level: levelOf(dir), raw, adopted: false,
-      layers: Object.fromEntries(LAYERS.map((l) => [l, layers[l] ?? null])),
-      acquired: acquisitions, activated,
-      // Same facts the human run prints, in the same run: who asked, why, and
-      // the ONE copyable command that consents to installing it. Init never
-      // runs it — reporting a requirement and acting on it are separate steps,
-      // and an agent reading this envelope must be able to tell them apart.
-      requirements: r.capabilities.flatMap((c) => c.missingRequires.map((m) => ({
-        capability: c.id, command: m.command, why: m.why || null, install: m.install || null,
-        consentCommand: `oats install --accept-requirement ${m.command} --dir ${shellQuote(dir)}`,
-      }))),
-    });
-    return;
-  }
-  offerTmuxMouseScrolling();
+/** `oats workspace status [--dir] [--json]` — contract §6. */
+async function workspaceCmd() {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  if (args[1] !== "status") return bail("E_USAGE", "usage: oats workspace status [--dir <d>] [--json]");
+  const ctx = workspaceContext(bail);
+  const discovery = await discoverForCli(ctx, bail);
+  let lock;
+  try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  const members = memberRows(discovery);
+  const packages = packageRows(lock);
+  // Standalone (decision 10): there is no workspace file — the declared packages are the
+  // kernel's own default (decision 25) and there are no teams.
+  const standalone = discovery.standalone === true;
+  const declared = Object.keys(standalone ? standalonePackages(catalogForSync(bail)).packages : (discovery.workspace?.packages || {})).sort();
+  const locked = new Set(packages.map((p) => p.id));
+  const unsynced = declared.filter((id) => !locked.has(id));
+  const stale = packages.filter((p) => !declared.includes(p.id)).map((p) => p.id);
+  const approval = { approved: packages.filter((p) => p.approved).map((p) => p.id), needed: packages.filter((p) => !p.approved).map((p) => p.id) };
+  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`);
+  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}`);
+  console.log("\nPackages:");
+  if (!packages.length) console.log(unsynced.length ? `  (none locked yet — \`oats sync\` resolves ${unsynced.join(", ")})` : "  (none)");
+  else printTable(["package", "version", "source", "commit", "approval", "capabilities"], packages.map((p) => [p.id, p.version, p.source, short(p.commit), p.approved ? `approved ${p.approved.at.slice(0, 10)}` : "NEEDED", p.capabilities.join(",")]));
+  if (packages.length && unsynced.length) console.log(`  declared but not locked (run \`oats sync\`): ${unsynced.join(", ")}`);
+  if (stale.length) console.log(`  locked but no longer declared (run \`oats sync\`): ${stale.join(", ")}`);
+  if (result.external.length) console.log(`\nExternal: ${result.external.map((e) => `${e.soul} (${e.source.replace(/@([0-9a-f]{40})$/, (_, o) => `@${short(o)}`)}, ${e.team})`).join("   ")}`);
+  if (discovery.problems.length) { console.log("\nProblems:"); for (const p of discovery.problems) console.log(`  ${p.code}  ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path}  ${p.message}`); }
+}
+
+/** `oats capabilities` / `oats souls` [--dir] [--json] — contract §6. */
+async function itemsCmd(kind) {
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
+  const ctx = workspaceContext(bail);
+  const discovery = await discoverForCli(ctx, bail);
+  let lock;
+  try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  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`);
+  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 ?? "—"]));
+  const unsynced = Object.keys(discovery.workspace?.packages || {}).filter((id) => !lock.packages[id]);
+  if (kind === "capabilities" && unsynced.length) console.log(`\n  package capabilities of ${unsynced.join(", ")} appear after \`oats sync\``);
 }
 
-/** Acquire the capability backing one fundamental layer at classic-init time.
- *
- * Catalog-first: when an official package supplies the capability it comes
- * through the package engine — flat materialization, a capability-materialization
- * lock, and NO implicit executable trust. The legacy standalone-capability route
- * survives only for marketplace capabilities the official catalog cannot supply
- * today, and it is the only branch that still writes a v1 lock.
- *
- * Throws on every failure: the caller holds the run journal, and exiting here
- * would strand its backup. */
-function acquireLayerCapability(dir, capId, layer, acquired, note) {
-  const fail = (code, message) => { const e = new Error(message); e.code = code; throw e; };
-  const official = officialCapabilityPackage(capId);
-  if (official.available) {
-    const acq = acquirePackage(dir, official.package);
-    if (!acq.capabilities.some((c) => c.capability === capId)) {
-      fail("E_LAYER_NOT_EXPORTED", `package ${official.package} does not export capability "${capId}" — it exports ${acq.capabilities.map((c) => c.capability).join(", ") || "nothing"}`);
-    }
-    // The layer is verified against the manifest actually WRITTEN TO DISK, never
-    // against the marketplace copy or the catalog's word for it.
-    const manifest = ownScopeCapabilityManifest(dir, capId);
-    if (!manifest) fail("E_LAYER_UNREADABLE", `capability "${capId}" was materialized but its manifest under ${shortPath(installedCapabilityDir(dir, capId))} is unreadable`);
-    if (manifest.layer !== layer) fail("E_LAYER_MISMATCH", `capability "${capId}" declares layer "${manifest.layer || "none"}", not "${layer}"`);
-    const executableSurface = acq.capabilities
-      .filter((c) => c.executableSurface?.commands?.length || c.executableSurface?.hooks?.length || c.executableSurface?.environment?.length)
-      .map((c) => c.capability);
-    acquired.push({
-      layer, capability: capId, route: "package", package: official.package, via: official.via,
-      packages: acq.installed.map((p) => ({ package: p.package, version: p.version || null, commit: p.commit || null })),
-      lockFile: acq.lockFile, trusted: false, executableSurface,
-    });
-    note(`Acquired package ${official.package} for the ${layer} layer → ${capId} (${acq.installed.map((p) => `${p.package}@${p.version}`).join(", ")}) → ${shortPath(acq.lockFile)}`);
-    return { ...manifest, _origin: `installed:${dir}` };
+// ---------- 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). */
+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 deploymentDir = dirname(ctx.path);
+  let lock = null;
+  try { if (existsSync(join(deploymentDir, LOCK_FILE))) lock = readLock(deploymentDir); } catch { lock = null; }
+  let discovery;
+  // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
+  // instance is computed against its member's current state, not reported "unreachable".
+  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) } };
   }
-  const market = marketplaceCapabilities();
-  if (!market[capId]) {
-    fail("E_UNKNOWN_CAPABILITY", `capability "${capId}" is not acquired at ${shortPath(dir)}, is not in the marketplace (${Object.keys(market).join(", ") || "empty"}), and no official package supplies it`);
+  const { driftOf } = await import("../lib/materialize.mjs");
+  const drift = 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 */ }
   }
-  // Legacy route: kernel-bundled marketplace capabilities predate the official
-  // packages, ship with the kernel already installed, and keep their v1 lock and
-  // acquisition-time trust until the catalog covers them.
-  const r = acquireCapability(dir, capId);
-  try {
-    writeCapabilityLock(dir, r.manifest.capability, {
-      source: r.source, version: r.manifest.version || null, integrity: r.integrity, trustedExecutables: true,
-    });
-  } catch (e) { rmSync(r.dest, { recursive: true, force: true }); throw e; }
-  if (r.manifest.layer !== layer) fail("E_LAYER_MISMATCH", `capability "${capId}" declares layer "${r.manifest.layer || "none"}", not "${layer}"`);
-  acquired.push({ layer, capability: capId, route: "marketplace", package: null, via: "marketplace", packages: [], lockFile: join(dir, OATS_LOCK_FILE), trusted: true, executableSurface: [] });
-  note(`Acquired ${r.manifest.capability}@${r.manifest.version} from the marketplace → ${shortPath(r.dest)}`);
-  return { ...r.manifest, _origin: `installed:${dir}` };
+  return { drift, unreachable: null };
 }
-
-/** Capability manifests physically present at THIS scope's own store.
- *
- * `capabilityManifests` walks the config chain, so during `oats init` — when no
- * oats-config.yaml exists at the target scope yet — this scope is not a level and
- * its own installed/ and owned/ capabilities are invisible. Init reads them
- * directly instead, which is also what makes a same-run acquisition visible to
- * the rest of the run. */
-function ownScopeCapabilityManifests(dir) {
-  // Capability-id keyed — never answer for `constructor`/`toString`. Belt and
-  // braces on the write side (store directory names are identity-validated at
-  // acquisition); it matters on the read side, where `oats init` indexes this
-  // map with a `--<layer>` flag value the operator typed.
-  const out = Object.create(null);
-  for (const [sub, origin] of [[installedCapabilitiesDir(dir), "installed"], [ownedCapabilitiesDir(dir), "owned"]]) {
-    if (!existsSync(sub)) continue;
-    let entries;
-    try { entries = readdirSync(sub, { withFileTypes: true }); } catch { continue; }
-    for (const e of entries) {
-      // Dot-prefixed entries are transaction staging, never installed content.
-      if (!e.isDirectory() || e.name.startsWith(".")) continue;
-      let raw;
-      try { raw = JSON.parse(readFileSync(join(sub, e.name, "oats.json"), "utf8")); } catch { continue; }
-      if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
-      // Strip BEFORE the spread. `_dir` and `_origin` are reassigned just after
-      // it, but every OTHER annotation in the namespace — `_capabilityLock`,
-      // `_package`, `_soulDir` … — would flow straight out of an
-      // artifact-controlled document. That is the exact shape the kernel's own
-      // manifest reader was fixed for, and this map is merged OVER that
-      // stripped one, so leaving it raw kept the forgery carrier alive.
-      const m = stripInternalAnnotations(raw);
-      if (typeof m.capability === "string") out[m.capability] = { ...m, _dir: join(sub, e.name), _origin: `${origin}:${dir}` };
-    }
-  }
-  return out;
+/** One `modules:` line per module. */
+function driftLine(row) {
+  const from = row.from || {};
+  const origin = from.kind === "package" ? `package ${from.package} v${from.version}` : memberLabel(row.recorded?.repoKey ?? from.repoKey ?? "?");
+  const base = `modules: ${row.module} from ${origin} @ ${short7(row.recorded?.commit)}`;
+  if (row.status === "moved") return `${base}  [${from.kind === "package" ? "package" : "member"} moved since (now @ ${short7(row.current?.commit)})]`;
+  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;
 }
-const ownScopeCapabilityManifest = (dir, capId) => ownScopeCapabilityManifests(dir)[capId];
+const short7 = (oid) => (typeof oid === "string" ? oid.slice(0, 7) : "?");
 
-// ---------- roster: status / spawn / retire / create ----------
-function status() {
+async function status() {
   if (args.includes("--team")) return statusTeam();
-  const root = ensureRoot(dirFlag());
+  let root;
+  try { root = ensureRoot(dirFlag()); }
+  catch (e) { if (e?.code === "E_NO_DEPLOYMENT") { if (JSON_MODE) jsonFail("E_NO_DEPLOYMENT", e.message, e.details ?? e.provenance); die(e.message); } throw e; }
   const data = listInstances(root);
-  if (args.includes("--json")) { console.log(JSON.stringify({ root, agents: data }, null, 2)); return; }
+  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 } : {}) })); }
+    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 || "?"}]`);
     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}`) || [];
+      for (const r of rows) if (verbose || r.status !== "current") console.log(`          ${driftLine(r)}`);
     }
     for (const f of a.retireFailures || []) {
       console.log(`      ! deferred retirement of ${f.instance} FAILED${f.completedAt ? ` at ${f.completedAt}` : ""}: ${f.error || (f.incomplete || []).join("; ") || "see result file"} — retry with \`oats retire ${f.instance}\``);
@@ -4159,7 +2280,7 @@ function statusTeam() {
   }
 }
 
-function spawnCmd() {
+async function spawnCmd() {
   // JSON mode: contract envelope, stable error codes, stderr-only progress.
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
@@ -4195,6 +2316,52 @@ function spawnCmd() {
     root = hit.root;
   }
   let agent = findAgent(root, name);
+  // Workspace model: with an oats-local.yaml the soul is ALWAYS discovered over the
+  // remotes and resolved (member = latest state, package = locked+approved) — never
+  // "whatever <agents-root>/<name>/soul/ happens to hold": that copy is a per-commit
+  // cache (ensureWorkspaceSoul refreshes it when the member moved), so a second
+  // spawn sees the member's CURRENT soul, not the first spawn's. A preview runs the
+  // same read-only discovery+resolution; the fetched soul copy it may leave under
+  // <agents-root>/<name>/soul/ is not an instance (reported as soulFetched).
+  const providerPairs = [];
+  for (let i = 0; i < args.length; i++) if (args[i] === "--provider") { if (!args[i + 1] || !args[i + 2]) bail("E_BAD_ARGS", "--provider needs <capability> <key>=<value>"); providerPairs.push([args[i + 1], args[i + 2]]); i += 2; }
+  let wsPrepared, soulFetched = false, wsSoulUnknown = null;
+  let hasLocal = true;
+  {
+    try { loadLocal(dirFlag()); } catch (e) { if (e?.code === "E_LOCAL_MISSING") hasLocal = false; else bail(e.code || "E_WORKSPACE_SCHEMA", e.message, e.details); }
+    if (hasLocal) {
+      let discovery = null;
+      try {
+        const { prepareInstance, ensureWorkspaceSoul, parseProviderFlags, discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
+        const remoteOptions = remoteOptionsFromEnv();
+        const { local } = loadLocal(dirFlag());
+        discovery = await discoverOrStandalone(local, { remoteOptions });
+        wsPrepared = await prepareInstance(dirFlag(), name, { spawn: { providers: parseProviderFlags(providerPairs) }, remoteOptions, discovery });
+        const soulName = wsPrepared.soulEntry.name;
+        const stampFile = join(root, soulName, ".oats-soul-source.json");
+        const stampBefore = (() => { try { return JSON.parse(readFileSync(stampFile, "utf8")); } catch { return null; } })();
+        const soulDir = await ensureWorkspaceSoul(wsPrepared, root);
+        soulFetched = !stampBefore || stampBefore.commit !== wsPrepared.soulEntry.commit || stampBefore.repoKey !== wsPrepared.soulEntry.repoKey;
+        if (!agent || soulFetched || agent._dir !== dirname(soulDir)) agent = findAgent(root, soulName);
+        if (!agent) bail("E_SOUL_UNKNOWN", `soul "${name}" was fetched to ${shortPath(soulDir)} but is not readable as a soul there`);
+        note(`(workspace soul: "${name}" from ${wsPrepared.soulEntry.repoKey} @ ${String(wsPrepared.soulEntry.commit).slice(0, 12)}${wsPrepared.soulEntry.team ? `, team ${wsPrepared.soulEntry.team}` : ""}${soulFetched ? "; soul source fetched" : ""})`);
+      } catch (e) {
+        // Standalone (decisions 10/25): the ONLY package request is the kernel's own
+        // default; when the catalog cannot name it, say so instead of "add it to packages:"
+        // (there is no workspace file to add it to).
+        if (e?.code === "E_PACKAGE_MISSING" && discovery?.standalone === true) {
+          let file = process.env.OATS_PACKAGE_CATALOG || null; try { file = describeOfficialCatalog().catalog.file; } catch { /* keep the env value */ }
+          bail(e.code, `${e.details?.capability ?? "oats.core"}: the catalog has no package providing oats.core (OATS_PACKAGE_CATALOG=${file ?? "<bundled>"}) — standalone spawns resolve only the kernel's default package from the catalog`, { ...(e.details ?? {}), standalone: true, reason: "no-catalog", catalog: file });
+        }
+        // Not a workspace soul: a capability-defined agent (a module's `agents:`
+        // soul, resolved below from a materialized copy) or a local-only soul
+        // (--instructions-file/--def-file) may still answer to this name.
+        if (e?.code === "E_SOUL_UNKNOWN" && !isPreview) { wsSoulUnknown = e; }
+        else if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details);
+        else throw e;
+      }
+    } else if (providerPairs.length) bail("E_BAD_ARGS", "--provider needs a workspace deployment (oats-local.yaml); this directory has none");
+  }
   if (agentsRootFlag !== undefined && !agent) bail("E_SOUL_UNKNOWN", `soul "${name}" is not at agents root ${String(agentsRootFlag)}`);
   if (isPreview && !agent) bail("E_SOUL_UNKNOWN", `soul "${name}" is not in ${shortPath(root)}; a preview never creates or imports a soul (known: ${listAgents(root).map((a) => a.name).join(", ") || "none"})`);
   if (isPreview && (flag("instructions-file") !== undefined || flag("def-file") !== undefined)) bail("E_BAD_ARGS", "--preview does not take --instructions-file/--def-file: a preview never writes a soul");
@@ -4208,6 +2375,33 @@ function spawnCmd() {
       note(`(capability agent: "${name}" from ${capAgent.capability} — fresh soul, instances home locally)`);
     }
   }
+  if (!agent && !instrFile && !defFile && hasLocal) {
+    // Workspace model: the agent is declared by a capability some INSTANCE already
+    // materialized (the --parent home first, then any home under this root) —
+    // OKF's memory-harvest worker spawned by a knowledge source, for example.
+    const anchorName = flag("parent") || flag("relative-to");
+    const anchorHome = anchorName ? (findInstanceHome(root, String(anchorName)) ?? null) : null;
+    let modAgent;
+    try { modAgent = findModuleCapabilityAgent(root, name, { anchorHome }); }
+    catch (e) { bail(e.code || "E_CAPABILITY_BROKEN", e.message, e.details); }
+    if (modAgent) {
+      agent = modAgent;
+      note(`(capability agent: "${name}" from ${modAgent.capability}, materialized in ${shortPath(modAgent._manifestSource)} — fresh soul, instances home locally)`);
+    } else {
+      // No instance carries it: resolve from the deployment's LOCK — an approved
+      // package whose capability declares agents/<name> is fetched into the
+      // deployment's module store and read from there.
+      try {
+        const { resolvePackageCapabilityAgent } = await import("../lib/instance-resolution.mjs");
+        const hit = await resolvePackageCapabilityAgent(dirFlag(), name, { remoteOptions: remoteOptionsFromEnv(), catalog: (() => { try { return officialPackageCatalog(); } catch { return null; } })() });
+        if (hit) {
+          agent = capabilityAgentFromDir(hit.dir, name, root, { module: { from: { kind: "package", package: hit.package, version: hit.version, commit: hit.commit } } });
+          if (agent) note(`(capability agent: "${name}" from ${hit.capability} — package ${hit.package} v${hit.version}, fetched to ${shortPath(hit.dir)} — fresh soul, instances home locally)`);
+        }
+      } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details); throw e; }
+    }
+  }
+  if (!agent && wsSoulUnknown && !instrFile && !defFile) bail(wsSoulUnknown.code, wsSoulUnknown.message, wsSoulUnknown.details);
   if (!agent && !instrFile && !defFile) {
     // Cross-repo lookup: the soul may live in a sibling repo of the team scope.
     // Unique match wins; the instance homes with its owning repo's agents root.
@@ -4303,11 +2497,26 @@ function spawnCmd() {
     }
     if (wake && (typeof wake.message !== "string" || !wake.message.trim())) bail("E_SCHEDULE_INVALID", "wake message: non-empty text is required");
   } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message); throw e; }
+  // Workspace model: when this deployment has an oats-local.yaml, the soul's
+  // capabilities are resolved over the workspace's remotes (member = latest,
+  // 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;
+  if (wsPrepared) {
+    try {
+      const { toCapabilityRows, modulesPreview } = 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;
+    } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details); throw e; }
+  }
   let r;
   try {
     if (args.includes("--allow-child-spawns") && args.includes("--no-child-spawns")) bail("E_BAD_ARGS", "--allow-child-spawns and --no-child-spawns contradict");
     if (flag("base") === true) bail("E_BAD_ARGS", "--base needs a ref");
-    r = spawnInstance(root, agent, {
+    { const spawnOpts = {
+      prepared,
       purpose: flag("purpose"), task: taskText, taskFile: taskFileFlag, relation, relativeTo, relativeRoot,
       ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
       // Directory execution uses deployment configuration, not an ambient Git
@@ -4326,8 +2535,16 @@ function spawnCmd() {
       ...(flag("expect-decision") !== undefined && flag("expect-decision") !== true ? { expectDecision: String(flag("expect-decision")) } : {}),
       // K6c: with --idempotency-key, a retry of the SAME confirmed decision replays the recorded home instead of spawning twice.
       ...(flag("idempotency-key") !== undefined && flag("idempotency-key") !== true ? { idempotencyKey: String(flag("idempotency-key")) } : {}),
-    });
-    if (args.includes("--preview")) { if (JSON_MODE) { jsonOk(r); return; } console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) runtime ${r.runtime}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}; nothing was created`); return; }
+    };
+      r = prepared ? await spawnInstanceAsync(root, agent, spawnOpts) : spawnInstance(root, agent, spawnOpts); }
+    if (args.includes("--preview")) {
+      // A workspace preview may have fetched the soul's SOURCE under <agents-root>/<name>/soul/
+      // (a per-commit cache, not an instance): the result says so.
+      if (prepared) r.soulFetched = soulFetched;
+      if (JSON_MODE) { jsonOk(r); return; }
+      console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) runtime ${r.runtime}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}; nothing was created${soulFetched ? ` (the soul source was fetched to ${shortPath(join(root, r.agent, "soul"))} — a per-commit copy, not an instance)` : ""}`);
+      return;
+    }
   } catch (e) {
     // A typed CLI failure keeps ITS OWN code: re-badging an unsafe-config-key
     // (raised by the readers spawn walks) as E_SPAWN_FAILED tells an agent
@@ -4604,143 +2821,141 @@ async function paneCmd() {
   die("`oats pane` has been retired — the OATS Desktop app (packages/desktop) is the control panel now.");
 }
 
-function onboardCmd() {
-  const fail = (code, message, details) => JSON_MODE ? jsonFail(code, message, details) : die(message);
-  const values = new Map();
+/** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
+ *
+ * Realizes a workspace on this machine in the taught `<name>-workspace/` layout
+ * (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
+ * remotes, confirm membership, resolve `packages:`, approve (TTY) or list what
+ * needs approval (exit 2), write `oats-lock.json`. Nothing is installed, no soul
+ * is created, nothing is spawned, no `oats-config.yaml` is written: the member
+ * clones and the setup expert are the operator's next steps, printed here. */
+async function onboardCmd() {
+  const bail = (code, message, details) => (JSON_MODE ? jsonFail(code, message, details) : die(message));
+  const usage = "usage: oats onboard [<dir>] --workspace <repo ref> [--json]   (or --dir <dir>)";
+  let positional, workspaceRef, dirValue;
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
-    if (["--json", "--force-existing"].includes(arg)) { values.set(arg.slice(2), true); continue; }
-    if (!["--dir", "--workspace"].includes(arg) || values.has(arg.slice(2)) || !args[i + 1] || args[i + 1].startsWith("--")) {
-      fail("E_BAD_ARGS", "usage: oats onboard [--dir <deployment>] [--workspace <git:source[@revision]>] [--force-existing] [--json]");
-    }
-    values.set(arg.slice(2), args[++i]);
-  }
-  dropAmbientRoot();
-  let deployment, root, acquired, created, configFile, configBefore, configWritten;
+    if (arg === "--json") continue;
+    if (arg === "--dir" || arg === "--workspace") {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith("--")) return bail("E_BAD_ARGS", `--${arg.slice(2)} needs a value\n${usage}`);
+      if (arg === "--dir") { if (dirValue !== undefined) return bail("E_BAD_ARGS", usage); dirValue = value; }
+      else { if (workspaceRef !== undefined) return bail("E_BAD_ARGS", usage); workspaceRef = value; }
+      i++; continue;
+    }
+    if (arg.startsWith("--")) return bail("E_BAD_ARGS", `unknown flag ${arg}\n${usage}`);
+    if (positional !== undefined) return bail("E_BAD_ARGS", usage);
+    positional = arg;
+  }
+  if (positional !== undefined && dirValue !== undefined) return bail("E_BAD_ARGS", `give the deployment directory once, as <dir> or --dir\n${usage}`);
+  if (!workspaceRef || !workspaceRef.trim()) return bail("E_BAD_ARGS", `--workspace <repo ref> is required (the repository hosting oats-workspace.yaml)\n${usage}`);
+  workspaceRef = workspaceRef.trim();
+  // The ref must be one lib/remote.mjs understands BEFORE anything is written.
+  try { remoteModule.parseRepoRef(workspaceRef); }
+  catch (e) { return bail(e.code || "E_REPO_REF", e.message, e.details ?? e.provenance); }
+
+  const dir = resolve(positional ?? dirValue ?? process.cwd());
+  const localFile = join(dir, "oats-local.yaml");
+  // (1) Refuse to onboard twice: THIS directory's oats-local.yaml is the mark (an enclosing
+  // deployment's file does not count — a nested directory is a different deployment).
+  let existing = null;
+  try { existing = lstatSync(localFile); } catch (e) { if (e.code !== "ENOENT") return bail("E_ONBOARD_FAILED", `cannot inspect ${localFile}: ${e.message}`); }
+  if (existing) return bail("E_ALREADY_ONBOARDED", `${shortPath(localFile)} already exists — this directory realizes a workspace; run \`oats sync --dir ${shortPath(dir)}\` to refresh it`, { local: localFile, dir });
+  if (existsSync(dir) && !lstatSync(dir).isDirectory()) return bail("E_ONBOARD_FAILED", `${shortPath(dir)} exists and is not a directory`, { dir });
+
+  // (2) The two files/dirs onboarding owns. Written atomically; rolled back if the sync
+  // that follows cannot even read the workspace (a typo'd ref must not leave a
+  // half-onboarded directory that looks finished).
+  const created = [];
   try {
-    // Like create: an existing enclosing roster wins, otherwise bootstrap at
-    // the enclosing Git root or explicit directory. Canonicalize existing parents.
-    const requested = resolve(values.get("dir") || process.cwd()), missing = [];
-    let parent = requested;
-    while (!existsSync(parent)) { missing.unshift(basename(parent)); parent = dirname(parent); }
-    const start = join(realpathSync(parent), ...missing);
-    root = findRoot(start) || join(defaultRepo(start) || start, "agents");
-    deployment = dirname(root);
-    assertNoSymlinkedParents(deployment, root, "onboard agents root");
-    assertNoSymlinkedParents(deployment, join(deployment, "local-agents", SETUP_EXPERT), "local setup soul");
-    const assertSetupAbsent = () => {
-      for (const candidate of [join(deployment, "local-agents", SETUP_EXPERT), join(root, SETUP_EXPERT), join(root, "local-agents", SETUP_EXPERT), join(root, "tmp-agents", SETUP_EXPERT)]) {
-        let present = false;
-        try { lstatSync(candidate); present = true; } catch (error) { if (error.code !== "ENOENT") throw error; }
-        if (present) throw Object.assign(new Error(`existing or incomplete setup expert is preserved at ${candidate}; it will not be overwritten`), { code: "E_AGENT_EXISTS" });
-      }
-    };
-    assertSetupAbsent();
-    const agents = listAgents(root);
-    if (agents.length && !values.get("force-existing")) throw Object.assign(new Error("deployment already has agents; use --force-existing to add the setup expert without replacing them"), { code: "E_DEPLOYMENT_NOT_EMPTY" });
-    if (findAgent(root, SETUP_EXPERT)) throw Object.assign(new Error("oats-setup-expert already exists; it will not be overwritten"), { code: "E_AGENT_EXISTS" });
-    const edition = loadSetupExpertEdition(values.get("workspace"));
-    for (const key of ["description", "runtime", "model"]) if (edition.declaration[key] !== undefined) assertSafeConfigValue(edition.declaration[key], `setup edition ${key}`);
-    const catalog = officialPackageCatalog();
-    // Catalog precedence: an explicit OATS_PACKAGE_CATALOG override, else the entry the WORKSPACE
-    // publishes at the edition's revision, else the kernel's bundled snapshot. The bundled copy lags
-    // every oats.framework release cut after this kernel's tag, and a second operator has no main
-    // checkout to point an override at (0.24.5; second-operator finding).
-    const bundledEntry = catalog["oats.framework"];
-    const entry = process.env.OATS_PACKAGE_CATALOG ? bundledEntry : (edition.catalogEntry ?? bundledEntry);
-    const catalogOrigin = process.env.OATS_PACKAGE_CATALOG ? "override" : edition.catalogEntry ? "workspace" : "bundled";
-    if (!Object.hasOwn(catalog, "oats.framework") || !entry?.url || !entry.ref
-        || SETUP_CAPABILITIES.some(id => { const m = officialCapabilityPackage(id); return !m.available || m.package !== "oats.framework" || m.migratedCapability !== id; })) {
-      throw Object.assign(new Error("official oats.framework with core/setup aliases and a published revision is required"), { code: "needs-configuration" });
-    }
-    const catalogSource = parsePortableSource(`git:${entry.url}@${entry.ref}#${entry.path ?? DEFAULT_PACKAGE_PATH}`);
-    const file = join(deployment, "oats-config.yaml");
-    if (existsSync(file) && !lstatSync(file).isFile()) throw Object.assign(new Error("onboard will not replace a non-regular deployment configuration"), { code: "E_CONFIG_BROKEN" });
-    const before = existsSync(file) ? readFileSync(file, "utf8") : null;
-    configFile = file; configBefore = before;
-    const caps = readCapabilitiesModel(file), previous = resolveOatsConfig(deployment, SETUP_EXPERT);
-    // Exclusions are for the NEW soul only. Never turn off an existing root's
-    // global provider/layer just to make bootstrap work under --force-existing.
-    for (const cap of previous.capabilities) {
-      if (SETUP_CAPABILITIES.includes(cap.id)) continue;
-      let target;
-      if (cap.layer) {
-        const existing = caps.layers[cap.layer];
-        if (existing && (existing === "none" || existing.capability !== cap.id)) throw Object.assign(new Error(`cannot safely exclude ${cap.id} for the setup soul at this level; choose a fresh deployment`), { code: "needs-configuration" });
-        target = caps.layers[cap.layer] ||= { capability: cap.id };
-      } else target = caps.additive[cap.id] ||= {};
-      target.souls = { ...target.souls, [SETUP_EXPERT]: false };
-    }
-    if (before === null && !agents.length) for (const layer of LAYERS) caps.layers[layer] ??= "none";
-    for (const id of SETUP_CAPABILITIES) {
-      const target = caps.additive[id] ||= {};
-      if (target.from && target.from !== "installed") throw Object.assign(new Error(`${id} already selects another provenance; choose a fresh deployment`), { code: "needs-configuration" });
-      target.from = "installed"; target.souls = { ...target.souls, [SETUP_EXPERT]: true };
-    }
-    const text = replaceCapabilitiesBlock(before ?? `name: ${scaffoldConfigName(deployment)}\n`, caps);
-    mkdirSync(deployment, { recursive: true });
-    acquired = acquirePackage(deployment, "oats.framework", { expectPackage: "oats.framework",
-      catalog(id, selector) {
-        const selected = id === "oats.framework" ? entry : (Object.hasOwn(catalog, id) ? catalog[id] : null);
-        return selected?.url ? { url: selected.url, ref: selector || selected.ref, path: selected.path } : undefined;
-      },
-      assertCommittable(plan) {
-      const pkg = plan.packages.find(p => p.package === "oats.framework");
-      if (edition.packageIntegrity && pkg?.integrity !== edition.packageIntegrity) {
-        const lag = catalogOrigin === "bundled" ? " (the kernel's bundled catalog entry lags the edition's package; onboard from the workspace or point OATS_PACKAGE_CATALOG at the reviewed list)" : "";
-        throw Object.assign(new Error(`selected edition's same-repository package differs from the official acquisition; align the reviewed source and catalog explicitly${lag}`),
-          { code: "integrity-drift", details: { catalogOrigin, catalogRef: entry.ref, acquiredIntegrity: pkg?.integrity ?? null, editionPackageIntegrity: edition.packageIntegrity } });
-      }
-      for (const id of SETUP_CAPABILITIES) {
-        const cap = plan.capabilities.find(c => c.capability === id);
-        if (!cap || cap.package !== "oats.framework" || cap.layer || Object.values(cap.executableSurface || {}).some(value => Array.isArray(value) && value.length)) {
-          throw Object.assign(new Error(`setup bootstrap needs resources-only ${id}; executable surfaces require a separate explicit approval path`), { code: "approval-required" });
-        }
-      }
-    } });
-    if ((existsSync(file) ? readFileSync(file, "utf8") : null) !== before) throw Object.assign(new Error("deployment configuration changed during acquisition; nothing was activated"), { code: "E_CONFIG_CHANGED" });
-    writeFileAtomic(file, text); configWritten = text;
-    const selected = resolveOatsConfig(deployment, SETUP_EXPERT);
-    if (selected.capabilities.length !== 2 || SETUP_CAPABILITIES.some(id => !selected.capabilities.some(c => c.id === id))) {
-      throw Object.assign(new Error("setup expert's effective configuration contains other capabilities; no soul or hook was created"), { code: "needs-configuration" });
-    }
-    // Required capabilities were checked resources-only before acquisition: no
-    // unrelated or executable soul-scaffold hooks can run during local creation.
-    assertNoSymlinkedParents(deployment, root, "onboard agents root");
-    assertNoSymlinkedParents(deployment, join(deployment, "local-agents", SETUP_EXPERT), "local setup soul");
-    assertSetupAbsent();
-    mkdirSync(root, { recursive: true });
-    created = coreCreateAgent(root, { name: SETUP_EXPERT, local: true, oatsCore: false, repo: deployment, work: "directory",
-      runtime: edition.declaration.runtime, model: edition.declaration.model, yolo: false,
-      description: edition.declaration.description, instructions: edition.instructions });
-    const pkg = acquired.installed.find(p => p.package === "oats.framework");
-    const source = parsePortableSource(`git:${catalogSource.url}@${pkg.commit}#${pkg.path}`);
-    const requires = { capabilities: Object.fromEntries(SETUP_CAPABILITIES.map(id => [id, { source: `${source.source}#${source.path}` }])) };
-    const soulFile = join(created.soul, "soul.yaml");
-    writeFileAtomic(soulFile, readFileSync(soulFile, "utf8") + `requires: ${JSON.stringify(requires)}\ndefaults: ${JSON.stringify(edition.declaration.defaults)}\n`
-      + `provenance: ${JSON.stringify({ kind: edition.source.kind, source: edition.source.source, revision: edition.source.revision, path: edition.source.path, ...(edition.source.workspaceRevision ? { workspaceRevision: edition.source.workspaceRevision } : {}) })}\n`);
-    const agent = findAgent(root, SETUP_EXPERT), composition = composeInstanceAgentsMd(created.soul, deployment, SETUP_EXPERT, "directory", "local");
-    planInstanceResources({ resolved: composition.resolved, soulDir: created.soul, agent, contextDir: deployment, composition });
-    const argv = [process.execPath, CLI_BIN, "spawn", SETUP_EXPERT, "--dir", deployment, "--no-yolo", "--task", "Help me configure this deployment and adopt my workspace with explicit approvals."];
-    const result = { mode: "classic", captured: false, deployment, agentsRoot: root, ...created, source: edition.source, catalog: { origin: catalogOrigin, ref: entry.ref },
-      package: { id: pkg.package, version: pkg.version, commit: pkg.commit, path: pkg.path }, lockFile: acquired.lockFile,
-      capabilities: [...SETUP_CAPABILITIES], launched: false, next: { argv, command: argv.map(shellQuote).join(" ") } };
-    if (JSON_MODE) jsonOk(result);
-    else { console.log(`Created local ${SETUP_EXPERT} in ${deployment} (classic bootstrap, not captured preparation).`); console.log(`No model was launched. Next:\n${result.next.command}`); }
-  } catch (error) {
-    // Roll back only configuration bytes still exactly owned by this attempt.
-    // Acquired artifacts/locks and any incomplete new soul remain visible evidence.
-    let configRestored = false;
-    if (configWritten !== undefined) {
-      try {
-        if (lstatSync(configFile).isFile() && readFileSync(configFile, "utf8") === configWritten) {
-          if (configBefore === null) rmSync(configFile); else writeFileAtomic(configFile, configBefore);
-          configRestored = true;
-        }
-      } catch { /* never erase another writer's change or hide a failed rollback */ }
+    if (!existsSync(dir)) { mkdirSync(dir, { recursive: true }); created.push(dir); }
+    const local = { schemaVersion: 2, workspace: workspaceRef };
+    writeFileAtomic(localFile, YAML.stringify(local));
+    created.push(localFile);
+    const agentsDir = join(dir, "agents");
+    if (!existsSync(agentsDir)) { mkdirSync(agentsDir); created.push(agentsDir); }
+  } catch (e) {
+    rollback();
+    return bail(e.code && String(e.code).startsWith("E_") ? e.code : "E_ONBOARD_FAILED", `cannot write ${shortPath(dir)}: ${e.message}`, { dir });
+  }
+  /** Only what THIS onboard created, only while still exactly ours: our local file, an EMPTY
+   * agents/, an otherwise-empty <dir> (rmdirSync refuses a non-empty directory — evidence stays). */
+  function rollback() {
+    for (const p of [...created].reverse()) {
+      try { if (p === localFile) rmSync(p, { force: true }); else rmdirSync(p); }
+      catch { /* leave evidence rather than erase another writer's work */ }
     }
-    fail(error.code || "E_ONBOARD_FAILED", error.message, { deployment, agentsRoot: root, packageAcquired: !!acquired, soul: created?.soul, configRestored, launched: false, ...(error.details && typeof error.details === "object" ? error.details : {}) });
   }
+  const bailRollback = (code, message, details) => { rollback(); return bail(code, message, { ...(details && typeof details === "object" ? details : {}), dir, rolledBack: true }); };
+
+  // (3) Exactly the `oats sync` body over the deployment just written. A failure while
+  // DISCOVERING (unreadable remote, not a workspace host) rolls the two files back; once the
+  // workspace has been read, the files stay (a lock may already be written).
+  let ctx;
+  try {
+    const found = loadLocal(dir);
+    ctx = { dir, localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() };
+  } catch (e) { return bailRollback(e.code || "E_LOCAL_MISSING", e.message, e.details); }
+  let discovered = false;
+  const syncBail = (code, message, details) => (discovered
+    ? bail(code, message, { ...(details && typeof details === "object" ? details : {}), dir, local: localFile })
+    : bailRollback(code, message, details));
+  const synced = await performSync(ctx, syncBail, { onDiscovered: () => { discovered = true; } });
+
+  // (4) The taught layout as next steps (design doc §4), and the envelope.
+  const standalone = synced.discovery.standalone === true;
+  const members = synced.report.members;
+  // The setup expert is suggested only when THIS workspace lists a soul by that name (a
+  // confirmed member's or, standalone, the repo's own); otherwise any listed soul is spawnable.
+  const soulNames = synced.items.souls.map((s) => s.name);
+  const setupExpert = soulNames.includes("oats-setup-expert");
+  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).
+  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) }));
+  // 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
+  // cannot see forge visibility, so it states the rule rather than judging.
+  const hostIsMember = members.some((m) => m.key === synced.discovery.key);
+  const hosting = { host: synced.discovery.key, hostIsMember, rule: "If any member is private, host oats-workspace.yaml in a private repo that is not a public member (a dedicated <org>/workspace repo); public contributors then use the standalone case (from: here capabilities + oats.core)." };
+  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`);
+  printSyncReport(ctx, synced);
+  console.log(`
+Layout (the taught convention — the kernel finds clones through oats-local.yaml, so any layout works):
+  ${shortPath(dir)}/
+  ├── 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)
+
+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> }.
+  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).
+  3. ${setupExpert ? "Spawn the setup expert to guide the rest (souls, teams, provider settings, approvals):" : "No soul named oats-setup-expert is listed here —"}
+       ${spawnHint ?? anySoulHint}${synced.approvalNeeded.length ? `\n  (first: \`oats sync --dir ${shortPath(dir)}\` in a terminal to approve ${synced.approvalNeeded.map((a) => `${a.id} ${a.version}`).join(", ")})` : ""}`);
+  process.exitCode = synced.approvalNeeded.length ? 2 : 0;
+}
+
+/** The clone URL of a member row: what the remote observed (from the workspace's members: refs;
+ *  standalone, the one repo oats-local.yaml named). */
+function memberUrlOf(discovery, key) {
+  for (const ref of discovery.workspace?.members || []) {
+    try { const parsed = remoteModule.parseRepoRef(ref); if (parsed.key === key) return parsed.url; } catch { /* schema already validated */ }
+  }
+  if (discovery.standalone === true && discovery.key === key) return discovery.url ?? null;
+  return null;
 }
 
 function createCmd() {
@@ -4773,7 +2988,7 @@ function createCmd() {
   // step here, not only at the refusal.
   const declared = r.declaredCapabilities || [];
   const inactive = declared.filter((id) => !(resolveOatsConfig(workspaceOf(root), name).capabilities || []).some((c) => c.id === id));
-  const next = inactive.length ? [{ code: "next-step", message: `${name} declares ${inactive.join(", ")}; before spawning, acquire if needed (oats install oats.framework) and activate: ${inactive.map((id) => `oats use ${id} --soul ${name}`).join(" && ")}` }] : [];
+  const next = inactive.length ? [{ code: "next-step", message: `${name} declares ${inactive.join(", ")}; before spawning, pin their packages in oats-workspace.yaml packages: and declare them in soul.yaml capabilities: { <cap>: { from } } (workspace model v2)` }] : [];
   const notes = [...(r.notes || []), ...next];
   if (args.includes("--json")) { console.log(JSON.stringify({ ...r, ...(notes.length ? { notes } : {}), ...(bootstrapped ? { agentsRoot: root } : {}) }, null, 2)); return; }
   for (const information of notes) console.error(`[${information.code}] ${information.message}`);
@@ -4787,18 +3002,27 @@ function createCmd() {
  * oats <namespace> <command> [args…] — run a command an active capability
  * declares in its manifest (`commands: { name: "script args" }`).
  * Kernel subcommands take precedence over capability namespaces.
+ *
+ * Three contexts, one contract (OATS_CAPABILITY / OATS_SETTINGS / OATS_CLI_BIN):
+ *   - inside an instance home: the home's materialized modules (instance.json.modules);
+ *   - from a v2 DEPLOYMENT (oats-local.yaml in reach, no home): operator-level
+ *     dispatch — resolve exactly as `oats spawn --soul <x>` would, fetch the
+ *     namespace's capability into <deployment>/.oats/modules/<cap>@<commit12>/
+ *     and run THAT copy with the soul's merged payload (lib/operator-dispatch.mjs;
+ *     contracts doc, "Post-0.25.0 clarifications");
+ *   - otherwise the classic config chain.
  */
-function capabilityCommand() {
+async function capabilityCommand() {
   // JSON-aware boundary: in --json mode every dispatch failure — inactive or
   // untrusted capability, duplicate namespace, unknown subcommand, broken
   // metadata/manifests, malformed command values — must still emit exactly
   // one envelope object on stdout. The WHOLE dispatcher runs inside the
   // boundary; only "no namespace matched" escapes (returns false to the help
   // fallthrough).
-  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
+  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   const NOT_DISPATCHED = Symbol("not-dispatched");
   let outcome;
-  try { outcome = dispatch(); }
+  try { outcome = await dispatch(); }
   catch (e) {
     // Unexpected throw from discovery/trust/decoding: keep the envelope contract.
     bail("E_CAPABILITY_BROKEN", e.message || e);
@@ -4806,7 +3030,23 @@ function capabilityCommand() {
   }
   return outcome !== NOT_DISPATCHED;
 
-  function dispatch() {
+  /** Operator-level dispatch from a deployment directory (no instance home). */
+  async function operatorDispatch() {
+    let hit;
+    try {
+      const { resolveOperatorDispatch } = await import("../lib/operator-dispatch.mjs");
+      let catalog = null; try { catalog = officialPackageCatalog(); } catch { /* the lock carries url for catalog packages */ }
+      hit = await resolveOperatorDispatch(process.cwd(), cmd, flag("soul"), { remoteOptions: remoteOptionsFromEnv(), catalog });
+    } catch (e) {
+      if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details);
+      throw e;
+    }
+    if (!hit) return NOT_DISPATCHED;
+    const teamCtx = hit.soul?.team ? { name: hit.soul.team } : undefined;
+    return runManifestCommand({ capability: hit.module.name, ...hit.manifest }, hit.settings, teamCtx, hit.ensureTree);
+  }
+
+  async function dispatch() {
     let activeIds;
     let context = process.cwd();
     let teamCtx;
@@ -4817,9 +3057,12 @@ function capabilityCommand() {
     // manifests. Null-prototype because the dispatcher indexes it with the
     // namespace the operator typed on the command line.
     let capSettings = Object.create(null);
+    let instanceModules = false;
+    let deployment = null;
     try {
       if (metaFile && existsSync(metaFile)) {
         const meta = JSON.parse(readFileSync(metaFile, "utf8"));
+        instanceModules = !!(meta.modules && typeof meta.modules === "object");
         activeIds = (meta.capabilities || []).map((c) => c.id);
         for (const c of meta.capabilities || []) capSettings[c.id] = c.settings || {};
         context = meta.repo || context;
@@ -4827,19 +3070,36 @@ function capabilityCommand() {
         // spawned before a team: block was declared have no snapshot.
         teamCtx = meta.team || resolveOatsConfig(context).team;
       } else {
-        const resolved = resolveOatsConfig(context, flag("soul"));
-        activeIds = resolved.capabilities.map((c) => c.id);
-        for (const c of resolved.capabilities) capSettings[c.id] = c.settings || {};
-        teamCtx = resolved.team;
+        // Not inside a home: a v2 deployment (oats-local.yaml in reach) resolves
+        // through the workspace, exactly as a spawn of --soul would (below).
+        try { const { deploymentOf } = await import("../lib/operator-dispatch.mjs"); deployment = deploymentOf(context); }
+        catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
+        if (!deployment) {
+          const resolved = resolveOatsConfig(context, flag("soul"));
+          activeIds = resolved.capabilities.map((c) => c.id);
+          for (const c of resolved.capabilities) capSettings[c.id] = c.settings || {};
+          teamCtx = resolved.team;
+        }
       }
     } catch (e) { bail("E_CONFIG_BROKEN", e.message || e); throw e; }
-    const mans = Object.values(capabilityManifests(context)).filter((m) => m.command === cmd && m.commands);
+    if (deployment) return operatorDispatch();
+    // Workspace model: an instance's own materialized modules are the command
+    // namespaces available to it (instance.json.modules → <home>/.oats/modules).
+    const mans = Object.values(capabilityManifests(instanceModules ? instanceHome : context)).filter((m) => m.command === cmd && m.commands);
     if (!mans.length) return NOT_DISPATCHED;
     if (mans.length > 1) bail("E_DUPLICATE_NAMESPACE", `duplicate operational command namespace "${cmd}": ${mans.map((m) => m.capability).join(", ")}`);
     const m = mans[0];
     if (!activeIds.includes(m.capability)) bail("E_CAPABILITY_INACTIVE", `${m.capability} command namespace is not active in the current context/instance`);
     const trust = capabilityTrust(m, context);
     if (!trust.trusted) bail("E_CAPABILITY_BLOCKED", `${m.capability} executable command is blocked: ${trust.reason}`);
+    return runManifestCommand(m, capSettings[m.capability] || {}, teamCtx, () => m._dir);
+  }
+
+  /** Help / unknown-command / spec validation / exec — shared by every context.
+   *  `m` is the manifest (with `capability`; `_dir` may be absent until `ensureDir`
+   *  resolves the directory holding the executable — the operator branch fetches
+   *  the module tree only when a command is actually going to run). */
+  async function runManifestCommand(m, settings, teamCtx, ensureDir) {
     const sub = args[1];
     const cmds = Object.keys(m.commands);
     // `oats <ns> --help` and `oats <ns> <cmd> --help` answer from the manifest
@@ -4865,17 +3125,22 @@ function capabilityCommand() {
     const spec = m.commands[sub];
     if (typeof spec !== "string" || !spec.trim()) bail("E_CAPABILITY_BROKEN", `oats ${cmd} ${sub}: manifest command must be a non-empty string (got ${JSON.stringify(spec)})`);
     const [script, ...rest] = spec.trim().split(/\s+/);
+    let dir;
+    try { dir = await ensureDir(); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
+    const withDir = { ...m, _dir: dir };
     let abs;
-    try { abs = capabilityExecutablePath(m, script); }
+    try { abs = capabilityExecutablePath(withDir, script); }
     catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
-    if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(m._dir, script)})`);
+    if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
     const r = spawnSync("node", [abs, ...rest, ...args.slice(2)], { stdio: "inherit", env: {
       ...process.env, OATS_CAPABILITY: m.capability,
       // Package-runtime boundary: dispatched commands receive the active
-      // capability's EFFECTIVE settings (instance snapshot or resolved context),
-      // same contract as lifecycle hooks — capabilities read their settings
-      // here instead of importing the kernel resolver.
-      OATS_SETTINGS: JSON.stringify(capSettings[m.capability] || {}),
+      // capability's EFFECTIVE settings (instance snapshot, resolved context, or
+      // the soul's merged payload on operator-level dispatch), same contract as
+      // lifecycle hooks — capabilities read their settings here instead of
+      // importing the kernel resolver.
+      OATS_SETTINGS: JSON.stringify(settings || {}),
       // PATH is not a trusted runtime boundary (maintainer finding 1): pass the
       // canonical absolute executable of THIS CLI; official consumers execFile
       // it directly and never resolve `oats` from PATH or a shell.
@@ -4935,59 +3200,6 @@ function typeCmd() {
   console.log(`Souls join it with: oats create <agent> --type ${name} (or type: ${name} in soul.yaml)`);
 }
 
-// ---------- injection eject ----------
-function injectCmd() {
-  const sub = args[1];
-  const target = args[2];
-  if (sub !== "eject" || !target || target.startsWith("--")) die("usage: oats inject eject <capability-id|oats> [--dir <dir>]");
-  const dir = dirFlag();
-  const file = join(dir, "oats-config.yaml");
-  if (!existsSync(file)) die(`no oats-config.yaml at ${shortPath(dir)} — run oats init first`);
-  if (["checkout", "worktree", "attached", "workspace"].includes(target)) die("work-mode injection overrides were removed — the packaged briefings are the contract; work modes support only setup: (env bootstrap script)");
-  const isWorkMode = false;
-  const isKernel = target === "oats";
-  const src = isKernel ? packagedInject("oats", dir) : isWorkMode ? packagedInject(`work-${target}`, dir) : packagedInject(target, dir);
-  if (!src) die(`no packaged default injection found for "${target}"`);
-  const rel = isKernel ? ".agents/injections/oats-defaults/oats.md" : isWorkMode ? `.agents/injections/workmodes/${target}.md` : `.agents/injections/capabilities/${target}.md`;
-  const destAbs = join(dir, rel);
-  if (existsSync(destAbs)) die(`${shortPath(destAbs)} already exists — edit it directly (it is already your override)`);
-  let text = readFileSync(file, "utf8");
-  if (!isWorkMode && !isKernel) {
-    const caps = readCapabilitiesModel(file);
-    const entry = Object.values(caps.layers).find((e) => e && e !== "none" && e.capability === target) || caps.additive[target];
-    if (!entry) die(`capability "${target}" has no entry in ${shortPath(file)} — activate it first (oats use ${target})`);
-    const m = capabilityManifest(target, dir);
-    const owned = entry.from === "owned" || String(entry.from || "").startsWith("path:") || String(m?._origin || "").startsWith("owned:") || String(m?._origin || "").startsWith("path:");
-    if (owned) die(`"${target}" is owned/path-sourced — you own its source; edit its injects/ file directly instead of ejecting`);
-    entry["injection-override"] = rel;
-    text = replaceCapabilitiesBlock(text, caps);
-  } else {
-    const lines = text.replace(/\n*$/, "\n").split("\n");
-    const headRe = isKernel ? /^oats:\s*(#.*)?$/ : /^work-modes:\s*(#.*)?$/;
-    let idx = lines.findIndex((l) => headRe.test(l));
-    if (idx < 0) { lines.push("", isKernel ? "oats:" : "work-modes:"); idx = lines.length - 1; }
-    if (isKernel) {
-      lines.splice(idx + 1, 0, `  injection-override: ${rel}`);
-      const c = lines.findIndex((l, i2) => i2 > idx + 1 && l.trim() === `# injection-override: ${rel}`);
-      if (c >= 0) lines.splice(c, 1);
-    } else {
-      let mIdx = lines.findIndex((l, i2) => i2 > idx && new RegExp(`^  ${target}:`).test(l));
-      if (mIdx < 0) { lines.splice(idx + 1, 0, `  ${target}:`, `    injection-override: ${rel}`); }
-      else {
-        lines.splice(mIdx + 1, 0, `    injection-override: ${rel}`);
-        const c = lines.findIndex((l, i2) => i2 > mIdx + 1 && l.trim() === `# injection-override: ${rel}`);
-        if (c >= 0) lines.splice(c, 1);
-      }
-    }
-    text = lines.join("\n").replace(/\n*$/, "\n");
-  }
-  mkdirSync(dirname(destAbs), { recursive: true });
-  writeFileSync(destAbs, readFileSync(src, "utf8"));
-  writeFileSync(file, text);
-  console.log(`Ejected packaged injection → ${shortPath(destAbs)}`);
-  console.log(`Set injection-override in ${shortPath(file)}. Edit the ejected file; it no longer tracks package updates.`);
-}
-
 // ---------- update ----------
 function updateCmd() {
   const checkOnly = args.includes("--check");
@@ -5038,7 +3250,10 @@ function versionCmd() {
     // on it (an older CLI without the surface must fail closed with a
     // reason, not an argument error). `features`: kernel abilities a peer
     // must see before relying on them (retire-home: retire --home).
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "catalog", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "session-recompose", "readiness-verify", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2"], instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
+    // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
+    // runs on resolve/materialize (contract §6); a feature the binary does not implement is
+    // never listed.
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "session-recompose", "readiness-verify", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload"], workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -5176,7 +3391,7 @@ async function serverRouteCmd() {
   // The operations contract addresses an exact member context on the host,
   // so its explicit --dir travels; every other routed command takes its
   // scope from the registration.
-  const explicitScopeOk = ["inspect", "operation", "use", "soul", "launch-config"].includes(cmd);
+  const explicitScopeOk = ["inspect", "operation", "soul", "launch-config"].includes(cmd);
   if (!explicitScopeOk && (flag("dir") !== undefined || args.some((a) => a.startsWith("--dir=")))) bail("E_BAD_ARGS", "--dir cannot be combined with --server: the remote workspace comes from the server registration");
   if (cmd === "launch-config") {
     const action = args[1];
@@ -5402,6 +3617,8 @@ async function serverRouteCmd() {
 // added lines rather than ~150 lines of pure whitespace churn, and keeps `git
 // blame` pointing at the commit that last changed each command.
 const TYPED_CLI_FAILURES = new Set(["unsafe-config-key", "unsafe-config-value"]);
+/** Removed 0.24 verbs → their v2 replacement (workspace model v2, decision 5). Checked before capability dispatch. */
+const REMOVED_VERBS = { install: "oats sync", restore: "oats sync", init: "oats-local.yaml + oats sync", use: "soul.yaml capabilities: { <cap>: { from } } + workspace defaults", trust: "oats sync (approval is asked once per package version)", list: "oats workspace status | oats capabilities", catalog: "oats package add <id> <version> (bare versions resolve through package-catalog.json)", remove: "oats package remove <id>", migrate: "a rebuild (no migration: docs/design/2026-09-23-workspace-module-contracts.md)", config: "oats-local.yaml (host settings) and oats-workspace.yaml (shared)", inject: "injection overrides are not part of the workspace model yet; edit the capability inject in its member repo" };
 try {
 // Inspect explicit selectors with the existing parser before new-work routing,
 // including selectors before the command. Inherited captures are not prepare inputs.
@@ -5431,12 +3648,13 @@ if (cmd === "prepare" || captured?.args[0] === "prepare") {
 }
 if (cmd === "onboard" || captured?.args[0] === "onboard") {
   if (captured) {
-    if (JSON_MODE) jsonFail("E_BAD_ARGS", "onboard is explicit classic bootstrap and cannot use captured selectors");
-    die("onboard is explicit classic bootstrap and cannot use captured selectors");
+    if (JSON_MODE) jsonFail("E_BAD_ARGS", "onboard is explicit workspace bootstrap and cannot use captured selectors");
+    die("onboard is explicit workspace bootstrap and cannot use captured selectors");
   }
   if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
-  onboardCmd(); process.exit(0);
+  await onboardCmd();
 }
+else {
 // Other commands retain their existing explicit/inherited selection rules.
 try { captured ??= capturedSelector(args); }
 catch (error) {
@@ -5455,7 +3673,7 @@ if (captured) {
 // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
 const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
 if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
-if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "use", "soul", "launch-config"].includes(cmd)) await serverRouteCmd();
+if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "soul", "launch-config"].includes(cmd)) await serverRouteCmd();
 else if (cmd === "server") serverCmd();
 else if (cmd === "inspect") inspectCmd();
 else if (cmd === "operation") operationCmd();
@@ -5465,35 +3683,29 @@ else if (cmd === "doctor") {
   const doctorDir = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
   args.includes("--json") ? doctorJson(doctorDir) : doctor(doctorDir);
 }
-else if (cmd === "use") use();
 else if (cmd === "update") {
+  // `oats update <package>` left with the installed tier (packages are pinned in
+  // the workspace file: `oats package add`); only the kernel self-update remains.
   const t = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
-  // A selector without a package must never fall through to the kernel
-  // self-update (a different product) with the flag silently ignored.
-  if (!t && flag("to") !== undefined) { cmdFail("E_BAD_ARGS", "oats update --to needs a package: oats update <package> --to <ref> (or <package> <package>@<ref>)"); process.exit(1); }
-  t ? updatePackageCmd(t) : updateCmd();
+  if (t || flag("to") !== undefined) { cmdFail("E_BAD_ARGS", "oats update takes no package: pin package versions in oats-workspace.yaml (`oats package add <id> <version>`), then `oats sync`; bare `oats update [--check] [--yes]` updates the kernel"); process.exit(1); }
+  updateCmd();
 }
 else if (cmd === "type") typeCmd();
-else if (cmd === "inject") injectCmd();
-else if (cmd === "install") install();
-else if (cmd === "config") configCmd();
-else if (cmd === "trust") trust();
-else if (cmd === "list") listCmd();
-else if (cmd === "catalog") catalogCmd();
 else if (cmd === "readiness") readinessCmd();
 else if (cmd === "instance") instanceCmd();
-else if (cmd === "remove") removeCmd();
-else if (cmd === "migrate") migrateCmd();
 else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
-else if (cmd === "init") init();
-else if (cmd === "status") status();
+else if (cmd === "sync") await syncCmd();
+else if (cmd === "package") await packageCmd();
+else if (cmd === "workspace") await workspaceCmd();
+else if (cmd === "capabilities" || cmd === "souls") await itemsCmd(cmd);
+else if (cmd === "status") await status();
 else if (cmd === "pane") await paneCmd();
 else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
 // Same rule as the inner catch: a typed CLI failure surfaces with its own code
 // through the shared boundary, never re-badged as a spawn-mechanism failure.
 else if (cmd === "session") await sessionCmd();
 else if (cmd === "schedule") scheduleCmd();
-else if (cmd === "spawn") { try { spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e); throw e; } }
+else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e); throw e; } }
 else if (cmd === "retire") retireCmd();
 else if (cmd === "create") createCmd();
 else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
@@ -5502,14 +3714,24 @@ else if (cmd === "experimental") await experimentalCmd();
 // word, so without this it reaches the capability dispatch, which resolves the
 // config chain and reads every lock in it — and a scope whose lock the kernel
 // refuses could then not print its own usage, which is exactly when you need it.
-else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && capabilityCommand()) { /* dispatched */ }
+// A removed 0.24 verb names its v2 replacement in BOTH modes, before any capability namespace could shadow it.
+else if (cmd && Object.hasOwn(REMOVED_VERBS, cmd)) {
+  const message = `unknown command "${cmd}" — removed by the workspace model v2; use ${REMOVED_VERBS[cmd]}`;
+  if (JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", message, { removed: cmd, replacement: REMOVED_VERBS[cmd] });
+  console.error(`oats: ${message}\n`);
+  console.log(usageText());
+  process.exit(1);
+}
+else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && await capabilityCommand()) { /* dispatched */ }
 // No matching kernel command or capability namespace: in --json mode the help
 // text must NOT contaminate stdout — still one envelope object, nonzero exit.
 else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", `unknown command "${cmd}" — no kernel subcommand or active capability namespace matches`);
 else {
+  if (cmd && !HELP_WORDS.has(cmd) && !cmd.startsWith("--")) console.error(`oats: unknown command "${cmd}" — no kernel subcommand or active capability namespace matches\n`);
   console.log(usageText());
   process.exit(cmd && !HELP_WORDS.has(cmd) ? 1 : 0);
 }
+} // end: every command but onboard
 
 /** The usage lines for one kernel command (its `oats <cmd> ...` lines and
  *  their indented continuations), or the whole usage when none match. */
@@ -5559,7 +3781,7 @@ Usage:
   oats session start --server <id>           start a stopped remote instance in its existing home
       --instance <name> | --home <abs>       over its saved route; the server must advertise
       [--model <m>] [--json]                 session-start (oats 0.22.9 or later)
-  oats inspect|operation|use|soul --server <id>   the same commands on a registered server over its
+  oats inspect|operation|soul --server <id>   the same commands on a registered server over its
       ... [--dir <remote member>] [--home <abs>]  saved route (an explicit --dir travels as is; a --home
                                             is its own context; else the registered workspace);
                                             soul set --instructions-file streams the bytes; the
@@ -5568,9 +3790,11 @@ Usage:
       --instance <name> | --home <abs>       attachments over its saved route (bytes stream on
       --file <path> [--json]                 ssh stdin; sha256 verified); the server must
                                             advertise session-upload (oats 0.22.13 or later)
-  oats onboard [--dir <deployment>]          bootstrap a LOCAL setup expert from official
-      [--workspace <git:source[@revision]>]   capabilities; classic path, not captured prepare;
-      [--force-existing] [--json]            prints the next spawn command, never launches
+  oats onboard [<dir>] --workspace <repo ref> realize a workspace here: writes <dir>/oats-local.yaml
+      [--json]                               and agents/, then runs the oats sync path (lock v3;
+                                            exit 2 while approvals are pending) and prints the
+                                            next steps (clone members you work IN, spawn
+                                            oats-setup-expert); creates no soul, spawns nothing
   oats create <name> [--local] [--no-oats-core] create an agent soul; --local = full
       [--description <d>] [--repo <r>]      soul under local-agents/ (uncommitted,
       [--work <mode>] [--runtime pi|claude|codex] gitignored; same memory + lifecycle)
@@ -5654,28 +3878,21 @@ Usage:
                                             --soul shows final composed AGENTS.md
   oats update [--check] [--yes]              check npm for a newer kernel+pi bridge and
                                             optionally run the update; then run oats doctor
-  oats install [<source>] [--dir <d>]        acquire + exact-lock a package closure
-                                            (git:host/org/repo@ref[#<path>], git URL,
-                                            local path, official catalog id) or a legacy
-                                            marketplace capability; never activates
-                                            #<path> selects the contained package root
-                                            (default oats-package; #. = repository root;
-                                            local paths are always exact directories)
-      [--recursive] [--no-requirements]     bare \`oats install\` exactly restores this
-      [--accept-requirement <cmd> ...]      chain's locked packages + capabilities; at a
-      [--json]                              team: scope (or with --recursive) it reconciles
-                                            the whole workspace — descendant scopes restore
-                                            once in path order (pruned discovery), then the
-                                            host-requirement consent gate runs;
-                                            --no-requirements = package-only (CI);
-                                            non-interactive runs never install host tools
-                                            unless each requirement is named explicitly;
-                                            --json = one envelope (failures carry the full
-                                            report under error.details)
-  oats list [--dir <d>] [--json]             installed packages, exported capabilities,
-                                            scopes, trust state
-  oats catalog [--json]                      the effective official package catalog (read-only:
-                                               identity/discovery, no acquisition or trust)
+  oats sync [--dir <d>] [--json]             workspace model v2: observe the workspace named by
+                                            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
+  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)
+  oats workspace status [--dir <d>] [--json] membership table (confirmed / no-backlink /
+                                            cannot-read / backlink-elsewhere), packages, approval
+  oats capabilities [--dir <d>] [--json]     every non-private capability of every confirmed
+  oats souls [--dir <d>] [--json]            member + the locked packages, with origin
+                                            (member <key> @ <commit> | package <id> v<ver>) and team
   oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
                                              read-only Git observation of the instance's work
                                              tree: branch, status (renames kept), ahead/behind
@@ -5713,68 +3930,8 @@ Usage:
                                              <workspace>/.agents/worktrees/<repo>/<branch>)
                                              unless discarded; --delete-branch deletes the
                                              worktree's verified branch and implies discard
-  oats update <package> [<package>@<ref>]    transactional package update: temp fetch,
-      [--to <ref>] [--dir <d>]              closure validation, diff, lock replace,
-                                            all capability approvals invalidated; a
-                                            spec or --to moves a catalog lock to <ref>
-  oats remove <package> [--dir <d>]          remove a package (refuses while config or
-                                            dependent packages reference it)
-  oats migrate [--dry-run] [--dir <d>]       map this scope's v1 capability locks to
-                                            package locks (preserves config activation)
-  oats migrate --official [--recursive]      guided upgrade of 0.18 bundled official
-      [--dry-run] [--dir <d>] [--json]      capabilities to official packages: plans every
-                                            visible lock-owning scope first, applies each
-                                            transactionally, keeps custom/owned entries
-                                            untouched, and prints the exact trust/install
-                                            follow-up (held when the catalog cannot map yet)
-  oats migrate --from-oas [--recursive]      convert a pre-rename OAS deployment in place:
-      [--dry-run] [--dir <d>] [--json]      renames oas-* files, the oas: config key and
-                                            capability ids, then chains the guided package
-                                            conversion — one transaction per scope, any
-                                            failure restores the original OAS bytes
-  oats config diff [--config <template>]     three-way report: your config vs the recorded
-      [--dir <d>] [--json]                  adopted base vs the template in the current exact
-                                            lock — reports only, never writes; the adopted
-                                            base supplies the package/template defaults
-  oats config sync [--accept <r>=local|package] apply the template's changes to your config,
-      [--dir <d>] [--json]                  region by region, preserving every untouched local
-                                            byte, comment and ordering; local-only edits stay;
-                                            conflicts need an explicit --accept and are never
-                                            chosen for you; advances the recorded base
-  oats config sync --reset --yes             replace your config with the template verbatim;
-      [--config <template>] [--dir <d>]     previews every local change it discards, refuses
-      [--json]                              without --yes, and keeps a recoverable .bak
-  oats config adopt <package>                switch to another installed package's template,
-      [--config <template>] [--accept ...]  rebasing your one local config; exactly one adopted
-      [--dir <d>] [--json]                  base survives, and a failed switch changes nothing
-  oats trust <capability> [--dir <dir>]      approve that capability's commands, hooks, and
-                                            launch-environment authority at
-                                            the provider package's exact integrity
-  oats trust <package> --all-capabilities    explicit bulk approval with a full
-                                            executable-surface summary
-  oats use <capability>                      activate for one config-owned target
-      [--global|--type <t>|--soul <s>]      (--global is default); --disable excludes
-      [--disable] [--settings k=v [k2=v2 ...]] [--dir <d>]
-  oats use none --layer <layer>              explicitly disable a fundamental layer
   oats type add <name> [--description <d>]   declare an agent type (family) in config;
   oats type list                             souls join via create --type / soul.yaml
-  oats inject eject <cap|work-mode|oats>      copy a packaged injection to the conventional
-      [--dir <d>]                           .agents/injections/ path and set injection-override
-  oats init [--raw] [--dir <dir>] [--json]   create an oats-config.yaml here. Fundamental
-      [--knowledge <id|none>]               layers are filled from what is already at this
-      [--messaging <id|none>]               scope, else acquired from the official package
-      [--tasks <id|none>]                   that supplies them — capabilities materialize
-      [--tmux-mouse|--no-tmux-mouse]        flat, executable surfaces stay untrusted, and
-                                            the whole run rolls back on any failure.
-      [--package <id|path|git-url>]         instead: adopt one config TEMPLATE from a package
-      [--config <template>]                 as your own local config and record the exact
-                                            adopted base (named template, else the marked
-                                            default, else the only one).
-      [--template <name|path|git-url>]      instead: seed from a template config (named via an
-                                            outer templates: map, a local file, or a git repo's
-                                            default-branch oats-config.yaml).
-                                            Every form refuses to overwrite an existing config;
-                                            --json = exactly one result envelope, noninteractive.
   oats root                                  print this package's install root
                                             (adapters resolve the kernel from it)
 
@@ -5832,7 +3989,7 @@ The turn record (core — every conversation captured, searchable, replicated):
   oats <namespace> <command> [args…]         run an operational command only when its
                                             capability is active (e.g. oats okf harvest)
 
-Layers: ${LAYERS.join(", ")}. Level detection: ~ → laptop, .git → repo, else workspace.`;
+Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
 }
 } catch (e) {
   if (!TYPED_CLI_FAILURES.has(e?.code)) throw e;