@awebai/oats 0.24.12 → 0.25.0

package/lib/packages.mjs

@@ -1,207 +1,105 @@
 /**
- * OATS distribution packages — WS2 policy layer (config bootstrap and workspace
- * reconciliation) over the package ENGINE in lib/core.mjs.
+ * OATS packages — versions, lock v3, approval (workspace model v2).
  *
- * The engine owns source parsing, manifests, the store, lock v2, acquisition,
- * exact restore, capability indexing, and trust (docs/design/
- * package-engine-contract.md + package-runtime-api.md). This module carries
- * ONLY what the Decision assigns to workstream 2:
- *   - config profile selection/validation/provenance and the report-only diff;
- *   - team-boundary workspace scope discovery (pruned, deterministic);
- *   - host-requirement consent policy (identity/conflict fail-closed, plans).
+ * Contract: docs/design/2026-09-23-workspace-module-contracts.md §4.
+ * Decision: agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md.
  *
- * Runtime-neutral and dependency-free, like lib/core.mjs.
+ * A package is a place to fetch from WITH a version attached. Nothing is
+ * installed: `resolvePackages` turns each `workspace.packages` entry into an
+ * exact (commit, integrity) pair recorded in `oats-lock.json`
+ * (lockfileVersion 3), and the one-time executable approval per version lives
+ * next to the commit it approved. A moved tag (same version string, different
+ * commit) fails integrity and asks again.
+ *
+ * This module is synchronous except `resolvePackages`, shells out to nothing,
+ * and depends only on `node:*`. Remote access is INJECTED (`remote` option) so
+ * callers pass `lib/remote.mjs` and tests pass an in-memory fake.
+ *
+ * Lock v3 shape (exactly as the contract):
+ *
+ *   {
+ *     lockfileVersion: 3,
+ *     packages: {
+ *       <id>: {
+ *         source:       "catalog:<id>" | "git:<key>@<ref>",
+ *         url:          "<repo url the package was read from>",   // repo identity: resolve/materialize need no catalog
+ *         path:         "<dir of oats-package.json inside the repo>",
+ *         version:      "<version string, no leading v>",
+ *         commit:       "<full 40-hex OID>",
+ *         integrity:    "sha256-<hex>",          // contentDigest of the package tree at <path>
+ *         capabilities: ["<cap name>", …],        // sorted
+ *         approved:     { executables: "sha256-<hex>", at: "<ISO-8601 UTC>" } | null
+ *       }
+ *     }
+ *   }
+ *
+ * `packageTree` (input of `executablesDigest`):
+ *
+ *   { manifests: [ { name: "<cap name>", manifest: <parsed oats.json>, files: Map<relpath, Buffer> } ] }
+ *
+ *   `files` holds the bytes of the capability directory, keyed by POSIX
+ *   relative path from that directory (e.g. "bin/tool.mjs"). Each
+ *   `manifest.commands[<cmd>]` value is "<relpath> [args…]"; the FIRST token is
+ *   the executable target whose bytes are digested. Only command targets are
+ *   digested — skills, injects and other files are covered by `integrity`.
+ *
+ * Deprecated shims: every name the 0.24 kernel still imports from this module
+ * is exported below as a thin function throwing E_REMOVED so nothing breaks at
+ * import time; callers are deleted in the next phase.
  */
-import {
-  chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync,
-  readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, lstatSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { execFileSync } from "node:child_process";
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
-import {
-  DEFAULT_PACKAGE_PATH, OATS_LOCK_FILE, OAS_SCOPE_FILES, detectOasScopes, findRoot, installedCapabilitiesDir, listAgents, listInstalledPackages, loadPackageManifestAt, officialCapabilityAliases, packageSpecIdentity,
-  gitCheckoutExactRef, parsePackageSource, resolveClaudeBinary, resolvePackageRoot,
-  OATS_VERSION, parseYamlNested, readPackageLocks, resolveOatsConfig, RUNTIME_PACKAGE_MANAGERS,
-  runtimePackageInstalled, runtimePackageIdentity, runtimePackageStatus, safeRuntimePackageSpec,
-  safeRuntimeSourceRef, validateConfigShape, withConfigFile,
-} from "./core.mjs";
-
-// Runtime-package primitives live in the ENGINE (core.mjs) so spawn can use them
-// without this policy module being imported from there. Re-exported here because
-// the consent policy is this module's public surface.
-export { packageSpecIdentity, RUNTIME_PACKAGE_MANAGERS, runtimePackageIdentity, runtimePackageInstalled, runtimePackageStatus, safeRuntimePackageSpec };
-
-/** Throw an Error carrying a stable contract error code (engine taxonomy §4 + WS2 codes). */
-function fail(code, message) {
-  const e = new Error(message);
-  e.code = code;
-  throw e;
-}
+import { oatsError as baseOatsError } from "./errors.mjs";
+import * as defaultRemote from "./remote.mjs";
 
-const AGENT_TYPE_RE = /^[a-z][a-z0-9-]*$/;
+export const LOCK_FILE = "oats-lock.json";
+export const LOCK_VERSION = 3;
+export const PACKAGE_MANIFEST = "oats-package.json";
+export const CAPABILITY_MANIFEST = "oats.json";
+/** Default location of `oats-package.json` inside a package repo when the
+ * workspace value carries no path (the catalog supplies one for catalog ids). */
+export const DEFAULT_PACKAGE_PATH = "oats-package";
 
-// ---------- config templates (selection, validation, adoption) ----------
-//
-// Both engine readers — acquisition's staged `configTemplates` and
-// `readLockedConfigTemplates` — produce the SAME descriptor, so everything here
-// takes descriptors and never cares which reader produced them.
+const OID_RE = /^[0-9a-f]{40}$/;
+const DIGEST_RE = /^sha256-[0-9a-f]{64}$/;
+const CONTRACT_DOC = "docs/design/2026-09-23-workspace-module-contracts.md";
 
-/** Scope-relative home of adopted template bases. Visible and commit-safe by
- * design: sync's three-way comparison needs the original base under review. */
-export const ADOPTED_TEMPLATES_DIRNAME = join(".agents", "config-templates", "adopted");
-export const ADOPTION_METADATA_FILE = "adoption.json";
+/** `oatsError` with details attached as BOTH `e.provenance` (today's field) and
+ * `e.details` (the contract's name) so callers can read either. */
+function oatsError(code, message, details) {
+  const e = baseOatsError(code, message, details);
+  if (details !== undefined) e.details = details;
+  return e;
+}
 
-/** Package and template names become PATH SEGMENTS under the adopted root, so
- * they get the same directory-name grammar a capability id gets. */
-const ADOPTED_TOKEN_RE = /^[a-z0-9][a-z0-9._-]*$/;
+// ---------- generic file-safety helpers (kept: used by bin/oats.mjs outside package code) ----------
 
-export const adoptedTemplateDir = (levelDir, packageId, templateName) => {
-  for (const [what, token] of [["package", packageId], ["template", templateName]]) {
-    if (typeof token !== "string" || !ADOPTED_TOKEN_RE.test(token)) {
-      fail("E_ADOPTED_PATH_UNSAFE", `adopted template path refused: ${what} token ${JSON.stringify(token)} is not a safe directory name (expected ${ADOPTED_TOKEN_RE.source})`);
-    }
-  }
-  return join(levelDir, ADOPTED_TEMPLATES_DIRNAME, packageId, templateName);
-};
+const isInside = (base, target) => target === base || target.startsWith(base + sep);
 
-/** Positively validate every EXISTING parent from the scope down to `leafDir`,
- * immediately before a write.
- *
- * An adopted base is written under a path the operator controls, and any
- * intermediate component could be a symlink — placed deliberately, or left over
- * from an unrelated tool. Following one writes the run's bytes somewhere nobody
- * asked for. The check refuses ANY intermediate symlink, contained or escaping:
- * a link that happens to stay inside the scope today is still a redirection
- * this code never sanctioned, and distinguishing the two only adds a way to be
- * wrong. Components that do not exist yet are fine — this run creates them.
- *
- * Deliberately re-run immediately before each write rather than cached: the
- * gap between checking and writing is exactly where a swap would land. */
+/** Refuse to write below `scopeDir` through any symlinked path component of
+ * `leafDir`. Components that do not exist yet are fine — this run creates them.
+ * Re-run immediately before each write rather than cached. */
 export function assertNoSymlinkedParents(scopeDir, leafDir, what) {
   const base = resolve(scopeDir);
   const leaf = resolve(leafDir);
-  if (!isInside(base, leaf)) fail("E_ADOPTED_PATH_UNSAFE", `${what} resolves outside the scope: ${leaf}`);
+  if (!isInside(base, leaf)) throw oatsError("E_ADOPTED_PATH_UNSAFE", `${what} resolves outside the scope: ${leaf}`, { scope: base, path: leaf });
   const rel = relative(base, leaf);
   let cur = base;
-  // The scope root itself is the caller's own anchor, so the walk starts BELOW
-  // it and covers every component this code is responsible for.
   for (const part of rel ? rel.split(sep) : []) {
     cur = join(cur, part);
     let st;
-    try { st = lstatSync(cur); } catch { return; } // absent from here down: this run creates it
+    try { st = lstatSync(cur); } catch { return; }
     if (st.isSymbolicLink()) {
-      fail("E_ADOPTED_PATH_UNSAFE", `${what} passes through a symlink at ${cur} — OATS never writes through a link it did not create; remove or replace that entry`);
-    }
-    if (!st.isDirectory()) fail("E_ADOPTED_PATH_UNSAFE", `${what} passes through ${cur}, which is not a directory`);
-  }
-}
-
-/** Replace a file with an exact copy of another, never writing THROUGH the
- * destination. `copyFileSync` opens the destination for write and therefore
- * FOLLOWS it: a pre-planted `oats-config.yaml.bak` symlink would redirect the
- * copy onto whatever it points at. Sibling temp + rename replaces the entry. */
-export function copyFileAtomic(from, to) {
-  writeFileAtomic(to, readFileSync(from));
-}
-
-/** Choose a template: explicit name, else the single marked default, else the
- * only one. Several unmarked templates need an explicit choice — guessing would
- * silently adopt a policy nobody picked. */
-export function selectConfigTemplate(templates, name, packageId, bail) {
-  const refuse = (code, msg) => (bail ? bail(code, msg) : fail(code, msg));
-  const list = templates || [];
-  if (!list.length) return refuse("E_NO_TEMPLATES", `package ${packageId} exports no config templates`);
-  if (name) {
-    const hit = list.find((t) => t.template === name);
-    if (!hit) return refuse("E_TEMPLATE_NOT_FOUND", `package ${packageId} has no config template "${name}" (templates: ${list.map((t) => t.template).join(", ")})`);
-    return hit;
-  }
-  const marked = list.filter((t) => t.default);
-  if (marked.length === 1) return marked[0];
-  if (list.length === 1) return list[0];
-  return refuse("E_TEMPLATE_AMBIGUOUS", `package ${packageId} exports several config templates and none is marked default (${list.map((t) => t.template).join(", ")}) — pass --config <name>`);
-}
-
-/** Validate one config template's CONTENT before adoption. Same policy checks
- * the profile validator carried, now reading a descriptor's bytes rather than a
- * package directory: config schema; every referenced installed capability
- * supplied by the closure; layer agreement against the real provider manifest;
- * agent-type syntax; no scope-escaping paths.
- * `deferUnknownLayers` exists because acquisition's PREVIEW capability rows
- * carry no capability manifest, so a template binding a layer to one of the
- * package's OWN not-yet-materialized capabilities cannot have that binding
- * checked inside the pre-commit gate. Refusing there would make every package
- * whose template binds a layer unadoptable, and accepting silently would be
- * fail-open — so the gate defers exactly those bindings and the caller
- * re-validates against the real materialized manifests before finalizing,
- * rolling the whole run back if they disagree. Same user-visible outcome as a
- * gate refusal (nothing persists), just paid for after the copy.
- * Returns a list of error strings (empty = valid). */
-export function validateConfigTemplate(descriptor, packageId, { dependencyProviders = new Map(), deferUnknownLayers = false } = {}) {
-  const where = `config template "${descriptor.template}" of package ${packageId}`;
-  let cfg;
-  try {
-    // A template is config SOURCE MATERIAL read from package bytes, so it hits
-    // the same typed key refusal as a config on disk — and it must name the
-    // template, not just "a mapping key". Same rendering as validateConfigShape
-    // below, which already carries the template path.
-    cfg = withConfigFile(`${where} (${descriptor.path})`, () => parseYamlNested(String(descriptor.content)));
-    validateConfigShape(cfg, `${where} (${descriptor.path})`);
-  } catch (e) { return [e.message]; }
-  return validateAdoptableConfig(cfg, where, dependencyProviders, deferUnknownLayers);
-}
-
-/** The shared config-policy checks, over an already-parsed config. */
-function validateAdoptableConfig(cfg, where, dependencyProviders, deferUnknownLayers = false) {
-  const errors = [];
-  const supplied = new Set(dependencyProviders.keys());
-  const entries = [];
-  const caps = cfg.capabilities || {};
-  for (const [layer, entry] of Object.entries(caps.layers || {})) {
-    if (entry && typeof entry === "object") entries.push({ id: entry.capability, entry, slot: layer });
-  }
-  for (const [id, entry] of Object.entries(caps.additive || {})) entries.push({ id, entry: entry && typeof entry === "object" ? entry : {}, slot: undefined });
-
-  for (const { id, entry, slot } of entries) {
-    const from = String(entry.from || "installed");
-    if (from.startsWith("path:")) { errors.push(`${where}: capability ${id} uses "from: ${from}" — templates must reference installed capabilities, not host paths`); continue; }
-    if (from === "installed" && !supplied.has(id)) {
-      errors.push(`${where}: capability ${id} is not supplied by the package or its dependency closure (supplied: ${[...supplied].join(", ") || "none"})`);
-      continue;
-    }
-    if (slot) {
-      const capMan = dependencyProviders.get(id) ?? null;
-      if (capMan && capMan.layer !== slot) errors.push(`${where}: layer ${slot} binds ${id}, but its manifest declares layer "${capMan.layer || "none"}"`);
-      else if (capMan === null && supplied.has(id) && !deferUnknownLayers) {
-        errors.push(`${where}: layer ${slot} binds ${id}, but its provider manifest is not available to verify the layer — install the provider first`);
-      }
-    }
-    const override = entry["injection-override"];
-    if (typeof override === "string" && (isAbsolute(override) || override.split(/[\\/]/).includes(".."))) {
-      errors.push(`${where}: capability ${id} injection-override escapes the target scope: ${override}`);
+      throw oatsError("E_ADOPTED_PATH_UNSAFE", `${what} passes through a symlink at ${cur} — OATS never writes through a link it did not create; remove or replace that entry`, { path: cur });
     }
+    if (!st.isDirectory()) throw oatsError("E_ADOPTED_PATH_UNSAFE", `${what} passes through ${cur}, which is not a directory`, { path: cur });
   }
-  for (const [name] of Object.entries(cfg["agent-types"] || {})) {
-    if (!AGENT_TYPE_RE.test(name)) errors.push(`${where}: agent type "${name}" must be lowercase alphanumeric/hyphens`);
-  }
-  for (const [mode, wm] of Object.entries(cfg["work-modes"] || {})) {
-    const setup = wm && typeof wm === "object" ? wm.setup : undefined;
-    if (typeof setup === "string" && (isAbsolute(setup) || setup.split(/[\\/]/).includes(".."))) {
-      errors.push(`${where}: work-modes.${mode}.setup escapes the target scope: ${setup}`);
-    }
-  }
-  const oatsOverride = cfg.oats && typeof cfg.oats === "object" ? cfg.oats["injection-override"] : undefined;
-  if (typeof oatsOverride === "string" && (isAbsolute(oatsOverride) || oatsOverride.split(/[\\/]/).includes(".."))) {
-    errors.push(`${where}: oats.injection-override escapes the target scope: ${oatsOverride}`);
-  }
-  return errors;
 }
 
-/** Atomically replace one file, never writing THROUGH it: a protected path may
- * be a symlink, and opening it for write would follow the link and clobber
- * whatever it points at. Sibling temp + rename replaces the entry itself. */
+/** Sibling temp + rename: replaces the directory entry itself, never writing
+ * THROUGH a pre-planted symlink at `file`. */
 export function writeFileAtomic(file, contents) {
   mkdirSync(dirname(file), { recursive: true });
   const tmp = join(dirname(file), `.${basename(file)}.oats-tmp-${process.pid}`);
@@ -211,1165 +109,495 @@ export function writeFileAtomic(file, contents) {
   } finally { rmSync(tmp, { force: true }); }
 }
 
-/** Write the active config plus the exact adopted base and its metadata.
- *
- * The base is the template's EXACT bytes — not the local config — because the
- * three-way sync compares against it; a base that drifted toward local would
- * silently turn upstream changes into conflicts. The metadata copies the
- * engine's `contentIntegrity` verbatim rather than inventing a second digest,
- * and carries nothing machine-local: no absolute path, no host, no secret. */
-export function writeAdoptedTemplate(levelDir, configFile, { package: packageId, template, root }, { writeConfig = true } = {}) {
-  const baseDir = adoptedTemplateDir(levelDir, packageId, template.template);
-  const baseFile = join(baseDir, "oats-config.yaml");
-  const metadataFile = join(baseDir, ADOPTION_METADATA_FILE);
-  // A `path:` source is one developer's filesystem layout. This file is meant to
-  // be COMMITTED, so recording it would leak a machine path into the repository
-  // and mean nothing on any other checkout — record that the adoption was local
-  // instead of where it happened. Git and catalog sources are portable and are
-  // recorded verbatim.
-  const rawSource = root?.source ?? null;
-  const localSource = typeof rawSource === "string" && rawSource.startsWith("path:");
-  const metadata = {
-    package: packageId,
-    template: template.template,
-    templatePath: template.path,
-    source: localSource ? null : rawSource,
-    ...(localSource ? { localSource: true } : {}),
-    version: root?.version ?? null,
-    commit: root?.commit ?? null,
-    packagePath: root?.path ?? null,
-    hash: template.contentIntegrity,
-    ...(template.legacySpelling ? { legacySpelling: true } : {}),
-    adoptedWith: `oats ${OATS_VERSION}`,
-  };
-  // IMMEDIATELY before the writes, not once at command entry: every existing
-  // component from the scope down to the template directory must be a real
-  // directory this code can own.
-  assertNoSymlinkedParents(levelDir, baseDir, `adopted base for ${packageId}:${template.template}`);
-  // `sync` writes the MERGED config itself; only first adoption and reset copy
-  // the template verbatim into place.
-  if (writeConfig) writeFileAtomic(configFile, template.content);
-  writeFileAtomic(baseFile, template.content);
-  writeFileAtomic(metadataFile, `${JSON.stringify(metadata, null, 2)}\n`);
-  return { baseDir, baseFile, metadataFile, metadata };
+/** Exact copy via `writeFileAtomic` (copyFileSync would follow a destination symlink). */
+export function copyFileAtomic(from, to) {
+  writeFileAtomic(to, readFileSync(from));
 }
 
-/** Read this scope's adopted base + metadata, or null when nothing is adopted.
- * At most one adopted base may exist; more than one is a typed failure rather
- * than a guess about which is current. */
-export function readAdoptedTemplate(levelDir) {
-  const root = join(levelDir, ADOPTED_TEMPLATES_DIRNAME);
-  if (!existsSync(root)) return null;
-  const found = [];
-  for (const pkg of readdirSync(root, { withFileTypes: true })) {
-    if (!pkg.isDirectory()) continue;
-    for (const tpl of readdirSync(join(root, pkg.name), { withFileTypes: true })) {
-      if (!tpl.isDirectory()) continue;
-      const dir = join(root, pkg.name, tpl.name);
-      if (existsSync(join(dir, ADOPTION_METADATA_FILE))) found.push({ package: pkg.name, template: tpl.name, dir });
-    }
-  }
-  if (!found.length) return null;
-  if (found.length > 1) {
-    fail("E_MULTIPLE_ADOPTED_BASES", `scope ${levelDir} records ${found.length} adopted config templates (${found.map((f) => `${f.package}:${f.template}`).join(", ")}) — exactly one may be current; remove the stale ones under ${ADOPTED_TEMPLATES_DIRNAME}`);
-  }
-  const hit = found[0];
-  let metadata;
-  try { metadata = JSON.parse(readFileSync(join(hit.dir, ADOPTION_METADATA_FILE), "utf8")); }
-  catch (e) { fail("E_ADOPTION_METADATA_INVALID", `adopted template metadata at ${join(hit.dir, ADOPTION_METADATA_FILE)} is unreadable: ${e.message}`); }
-  const baseFile = join(hit.dir, "oats-config.yaml");
-  if (!existsSync(baseFile)) fail("E_ADOPTION_BASE_MISSING", `adopted template ${hit.package}:${hit.template} has metadata but no recorded base at ${baseFile}`);
-  return { ...hit, metadata, baseFile, baseText: readFileSync(baseFile, "utf8") };
-}
+// ---------- lock v3 ----------
 
-// ---------- config template three-way merge (byte-preserving) ----------
-//
-// `oats config sync` compares three texts: the recorded ADOPTED BASE, the
-// current LOCAL oats-config.yaml, and the TEMPLATE from the currently locked
-// package. The Decision's binding rule is that untouched local bytes stay
-// byte-identical — comments, key ordering, blank lines, indentation style and
-// the presence or absence of a trailing newline all survive. That forbids the
-// obvious implementation (parse YAML, merge objects, reserialize): a round trip
-// through the kernel's YAML subset would rewrite the whole file even when one
-// key changed. So the merge is a line-level three-way diff whose output is
-// built by splicing ONLY the selected regions into the original local line
-// array; every other byte is copied verbatim from the local file.
-//
-// This half is deliberately engine-independent: pure text in, text out, no lock
-// reads, no filesystem, no package identity. The CLI supplies the three texts.
+const emptyLock = () => ({ lockfileVersion: LOCK_VERSION, packages: {} });
+const plainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
 
-/** Guard for the O(n*m) LCS tables below. Configs are tens to hundreds of lines;
- * anything past this is not a config being synchronized and must fail closed
- * rather than allocate gigabytes. */
-const MERGE_MAX_LINE_PRODUCT = 4_000_000;
+function sortedObject(obj) {
+  const out = {};
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k];
+  return out;
+}
 
-/** Split text into lines that RETAIN their exact terminators, so that
- * splitConfigLines(t).join("") === t for any t — including CRLF files and a
- * final line with no newline. Line identity is therefore byte identity: a line
- * that differs only in its terminator is a real difference, not a match. */
-export function splitConfigLines(text) {
-  const s = String(text);
-  const lines = [];
-  let start = 0;
-  for (let i = 0; i < s.length; i++) {
-    if (s[i] === "\n") { lines.push(s.slice(start, i + 1)); start = i + 1; }
+/** Structural validation of a lock v3 object. Throws E_LOCK_SCHEMA naming the
+ * offending path; a v1/v2 lock names its version and points at the rebuild. */
+export function validateLock(lock, { file } = {}) {
+  const where = file ? ` (${file})` : "";
+  if (!plainObject(lock)) throw oatsError("E_LOCK_SCHEMA", `oats-lock.json must be a JSON object${where}`, { file, path: "/" });
+  const v = lock.lockfileVersion;
+  if (v !== LOCK_VERSION) {
+    const shown = v === undefined ? "missing" : JSON.stringify(v);
+    throw oatsError("E_LOCK_SCHEMA",
+      `oats-lock.json lockfileVersion ${shown} is not supported: this kernel reads lockfileVersion ${LOCK_VERSION} only (workspace model v2; no migration — delete the lock and run \`oats sync\`)${where}`,
+      { file, path: "/lockfileVersion", found: v, expected: LOCK_VERSION });
+  }
+  if (!plainObject(lock.packages)) throw oatsError("E_LOCK_SCHEMA", `oats-lock.json "packages" must be an object${where}`, { file, path: "/packages" });
+  for (const [id, entry] of Object.entries(lock.packages)) {
+    const at = `/packages/${id}`;
+    const bad = (field, why) => oatsError("E_LOCK_SCHEMA", `oats-lock.json ${at}/${field}: ${why}${where}`, { file, path: `${at}/${field}`, id });
+    if (!plainObject(entry)) throw oatsError("E_LOCK_SCHEMA", `oats-lock.json ${at} must be an object${where}`, { file, path: at, id });
+    if (typeof entry.source !== "string" || !/^(catalog:|git:)/.test(entry.source)) throw bad("source", 'must be "catalog:<id>" or "git:<key>@<ref>"');
+    if (entry.url !== undefined && (typeof entry.url !== "string" || !entry.url)) throw bad("url", "must be a non-empty repo url when present");
+    if (typeof entry.path !== "string" || !entry.path) throw bad("path", "must be a non-empty string");
+    if (typeof entry.version !== "string" || !entry.version) throw bad("version", "must be a non-empty string");
+    if (typeof entry.commit !== "string" || !OID_RE.test(entry.commit)) throw bad("commit", "must be a full 40-hex OID");
+    if (typeof entry.integrity !== "string" || !DIGEST_RE.test(entry.integrity)) throw bad("integrity", "must be sha256-<hex>");
+    if (!Array.isArray(entry.capabilities) || entry.capabilities.some((c) => typeof c !== "string" || !c)) throw bad("capabilities", "must be an array of capability names");
+    if (entry.approved !== null) {
+      if (!plainObject(entry.approved)) throw bad("approved", "must be null or { executables, at }");
+      if (typeof entry.approved.executables !== "string" || !DIGEST_RE.test(entry.approved.executables)) throw bad("approved/executables", "must be sha256-<hex>");
+      if (typeof entry.approved.at !== "string" || Number.isNaN(Date.parse(entry.approved.at))) throw bad("approved/at", "must be an ISO-8601 timestamp");
+    }
   }
-  if (start < s.length) lines.push(s.slice(start));
-  return lines;
+  return lock;
 }
 
-/** Regions where `b` differs from `a`, as {aStart,aEnd,bStart,bEnd} half-open
- * line ranges. A pure insertion is a zero-width `a` range; a pure deletion a
- * zero-width `b` range. */
-function changeRegions(a, b) {
-  const n = a.length, m = b.length;
-  if (n * m > MERGE_MAX_LINE_PRODUCT) {
-    fail("E_SYNC_TOO_LARGE", `config texts are too large to merge line-by-line (${n} x ${m} lines)`);
-  }
-  const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
-  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) {
-    lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+/** Read `<dir>/oats-lock.json`. A missing file is an empty v3 lock; anything
+ * else is validated (E_LOCK_SCHEMA). Returns a fresh object every call. */
+export function readLock(dir) {
+  const file = join(resolve(dir), LOCK_FILE);
+  if (!existsSync(file)) return emptyLock();
+  let parsed;
+  try { parsed = JSON.parse(readFileSync(file, "utf8")); } catch (e) {
+    throw oatsError("E_LOCK_SCHEMA", `oats-lock.json is not valid JSON (${file}): ${e.message}`, { file, path: "/" });
   }
-  const regions = [];
-  let cur = null;
-  const flush = () => { if (cur) { regions.push(cur); cur = null; } };
-  let i = 0, j = 0;
-  while (i < n && j < m) {
-    if (a[i] === b[j]) { flush(); i++; j++; continue; }
-    if (!cur) cur = { aStart: i, aEnd: i, bStart: j, bEnd: j };
-    if (lcs[i + 1][j] >= lcs[i][j + 1]) cur.aEnd = ++i;
-    else cur.bEnd = ++j;
-  }
-  if (i < n || j < m) {
-    if (!cur) cur = { aStart: i, aEnd: i, bStart: j, bEnd: j };
-    cur.aEnd = n; cur.bEnd = m;
-  }
-  flush();
-  return regions;
+  return validateLock(parsed, { file });
 }
 
-/** Line-count delta a region introduces on the non-base side. */
-const regionDelta = (r) => (r.bEnd - r.bStart) - (r.aEnd - r.aStart);
+/** Canonical lock text: sorted package ids, sorted capability names, 2-space indent, trailing newline. */
+export function canonicalLock(lock) {
+  validateLock(lock);
+  const packages = {};
+  for (const id of Object.keys(lock.packages).sort()) {
+    const e = lock.packages[id];
+    packages[id] = {
+      source: e.source, ...(typeof e.url === "string" && e.url ? { url: e.url } : {}), path: e.path, version: e.version, commit: e.commit, integrity: e.integrity,
+      capabilities: [...e.capabilities].sort(),
+      approved: e.approved ? { executables: e.approved.executables, at: e.approved.at } : null,
+    };
+  }
+  return { lockfileVersion: LOCK_VERSION, packages };
+}
 
-function digestOf(...parts) {
-  const hash = createHash("sha256");
-  for (const part of parts) { hash.update(String(part)); hash.update("\0"); }
-  return `sha256-${hash.digest("hex")}`;
+/** Write `<dir>/oats-lock.json` atomically in canonical form. Returns the file path. */
+export function writeLock(dir, lock) {
+  const file = join(resolve(dir), LOCK_FILE);
+  writeFileAtomic(file, JSON.stringify(canonicalLock(lock), null, 2) + "\n");
+  return file;
 }
 
-/** Three-way merge PLAN for one config: what changed where, and what a caller
- * may decide about it. Nothing is written and nothing is chosen here.
- *
- * Each returned region carries the exact text of all three sides plus:
- *   kind      "upstream" — only the template moved away from the base; may be offered
- *             "local"    — only the local file moved; it always stays (never offered away)
- *             "conflict" — both moved, differently; needs an explicit local/package/edit choice
- *             "agreed"   — both moved to the same text; already in sync, nothing to do
- *   recommended  the decision applyConfigMerge uses when the caller passes none —
- *                null for conflicts, which therefore cannot be resolved silently
- *   digest       binds the decision to the exact three texts the plan was built
- *                from, so a stored automation answer cannot be replayed onto
- *                shifted content
- *
- * Region `local` ranges are indices into splitConfigLines(localText); they are
- * what applyConfigMerge splices, which is why round-tripping a plan with no
- * upstream application returns the local bytes unchanged. */
-export function planConfigMerge(baseText, localText, templateText) {
-  const base = splitConfigLines(baseText);
-  const local = splitConfigLines(localText);
-  const template = splitConfigLines(templateText);
+// ---------- workspace `packages:` values ----------
 
-  const localRegions = changeRegions(base, local);
-  const templateRegions = changeRegions(base, template);
+/** Strip a single leading "v" from a semver-ish tag ("v2.1.3" → "2.1.3"). */
+const versionOf = (text) => text.replace(/^v(?=\d)/, "");
 
-  // Group by overlapping-or-touching BASE range. Touching counts: an insertion
-  // at line p (zero-width base range) and a replacement starting at p are the
-  // same disputed spot, and treating them as independent would interleave two
-  // sides' edits at one point without either side ever agreeing to it.
-  const marked = [
-    ...localRegions.map((r) => ({ side: "local", r })),
-    ...templateRegions.map((r) => ({ side: "template", r })),
-  ].sort((x, y) => x.r.aStart - y.r.aStart || x.r.aEnd - y.r.aEnd);
+/** The two — and only two — `packages:` value forms (contract §2, non-collapse rule):
+ *   catalog version:  v2.1.3 | 2.1.3 | v1.0.0-rc.1        (resolves through the official catalog)
+ *   direct git ref:   git:<repo>@<ref>                    (<repo> = any ref lib/remote.mjs understands;
+ *                                                          <ref> = tag/branch name or full OID)
+ * Shared by lib/workspace.mjs (schema validation) and resolvePackages. */
+export const CATALOG_VERSION_RE = /^v?\d+(?:\.\d+)*(?:[-+][0-9A-Za-z.-]+)?$/;
+const REF_NAME_RE = /^(?![-/.])(?!.*\.\.)(?!.*[\s~^:?*[\\\x00-\x1f\x7f])(?!.*@\{)(?!.*\/\.)(?!.*\.lock(?:\/|$))(?!.*\/\/)[^/]+(?:\/[^/]+)*(?<!\/|\.)$/;
 
-  const groups = [];
-  for (const item of marked) {
-    const last = groups[groups.length - 1];
-    if (last && item.r.aStart <= last.aEnd) {
-      last.aEnd = Math.max(last.aEnd, item.r.aEnd);
-      last.items.push(item);
-    } else {
-      groups.push({ aStart: item.r.aStart, aEnd: item.r.aEnd, items: [item] });
-    }
+/**
+ * Classify one `packages:` value WITHOUT touching the catalog or the network.
+ * → { kind: "catalog", version } | { kind: "git", repo, at } | { problem: "<why>" }
+ * `repo` is the remainder after `git:` when that remainder is itself a full ref
+ * (`/abs/bare.git`, `file:///…`, `https://…`, `git@host:…`), else `git:<host>/<path>` as written.
+ */
+export function classifyPackageValue(value) {
+  if (typeof value !== "string" || !value.trim()) return { problem: "must be a non-empty string" };
+  const text = value.trim();
+  if (text !== value) return { problem: "must not carry surrounding whitespace" };
+  if (text.startsWith("git:")) {
+    const atIdx = text.lastIndexOf("@");
+    if (atIdx <= "git:".length) return { problem: "a git package must be written git:<repo>@<ref> (no @<ref> found)" };
+    const rest = text.slice("git:".length, atIdx);
+    const at = text.slice(atIdx + 1);
+    if (!at) return { problem: "a git package must be written git:<repo>@<ref> (empty <ref>)" };
+    if (rest.includes("@") && !/^git@[^@/:]+:/.test(rest)) return { problem: "a git package carries exactly one @<ref> (a repo ref has no @ except the git@host: ssh form)" };
+    if (!OID_RE.test(at) && !REF_NAME_RE.test(at)) return { problem: `${JSON.stringify(at)} is not a tag/branch name or full OID` };
+    if (!rest) return { problem: "a git package must be written git:<repo>@<ref> (empty <repo>)" };
+    // `git:` + an already-complete ref form: hand the remainder to parseRepoRef unchanged.
+    const repo = /^(?:\/|file:\/\/|https?:\/\/|git@)/.test(rest) ? rest : `git:${rest}`;
+    return { kind: "git", repo, at };
+  }
+  if (/^(?:https?:\/\/|file:\/\/|git@|\/)/.test(text) || text.includes("@") || text.includes("/")) {
+    return { problem: "a package outside the catalog must be written git:<repo>@<ref>" };
+  }
+  if (!CATALOG_VERSION_RE.test(text)) return { problem: `${JSON.stringify(text)} is neither a version (v2.1.3) nor git:<repo>@<ref>` };
+  return { kind: "catalog", version: versionOf(text) };
+}
+
+/** Split a catalog ref into a prefix and its version tail:
+ * "v2.1.3" → { prefix: "", vee: true } ; "oats-framework/v1.1.3" → { prefix: "oats-framework/", vee: true }. */
+function refPattern(catalogRef) {
+  const m = /^(.*?)(v?)(\d[^/]*)$/.exec(catalogRef);
+  if (!m) return null;
+  return { prefix: m[1], vee: m[2] === "v" };
+}
+
+/** Recompose a catalog ref for a requested version, keeping the catalog's tag convention. */
+function catalogRefFor(entry, requested) {
+  const pat = refPattern(entry.ref || "");
+  const bare = versionOf(requested);
+  if (!pat) return requested; // catalog ref carries no version tail — the request is the ref
+  return `${pat.prefix}${pat.vee ? "v" : ""}${bare}`;
+}
+
+/** Accept either the file shape ({ policy, packages: {…} }) or a bare id → entry map. */
+function catalogPackages(catalog) {
+  if (!plainObject(catalog)) return {};
+  if (plainObject(catalog.packages) && !("url" in catalog.packages)) return catalog.packages;
+  return catalog;
+}
+
+/** Interpret one `workspace.packages` value for package `id`.
+ *  - "<version>"            → catalog lookup; ref recomposed from the catalog's tag convention
+ *  - "git:<repo>@<ref>"     → direct ref; `<repo>` is any repo ref `lib/remote.mjs` understands
+ *                             (git:host/path, https://…, git@host:…, /abs/bare.git, file:///…)
+ * Nothing else is accepted (E_WORKSPACE_SCHEMA for a malformed value, E_REPO_REF for a bad git form).
+ * → { kind: "catalog"|"git", remoteRef, at, path } */
+export function parsePackageRequest(id, value, catalog) {
+  const c = classifyPackageValue(value);
+  if (c.problem) {
+    const code = typeof value === "string" && value.trim().startsWith("git:") ? "E_REPO_REF" : "E_WORKSPACE_SCHEMA";
+    throw oatsError(code, `packages.${id}: ${c.problem}, got ${JSON.stringify(value)}`, { id, value, path: `/packages/${id}`, problems: [c.problem] });
+  }
+  if (c.kind === "git") return { kind: "git", remoteRef: c.repo, at: c.at, path: DEFAULT_PACKAGE_PATH };
+  const text = value.trim();
+  const entry = catalogPackages(catalog)[id];
+  if (!plainObject(entry) || typeof entry.url !== "string") {
+    throw oatsError("E_PACKAGE_MISSING", `packages.${id}: ${JSON.stringify(text)} is a catalog version but the catalog has no package ${JSON.stringify(id)} — use git:<repo>@<ref> for a package outside the catalog`, { id, value: text });
+  }
+  return { kind: "catalog", remoteRef: entry.url, at: catalogRefFor(entry, text), path: typeof entry.path === "string" && entry.path ? entry.path : DEFAULT_PACKAGE_PATH };
+}
+
+// ---------- reading a package over the injected remote ----------
+
+const pjoin = (...parts) => posix.normalize(posix.join(...parts));
+
+const byCodepoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function assertRelPath(what, rel, details) {
+  if (typeof rel !== "string" || !rel || isAbsolute(rel) || /^[\\/]/.test(rel) || /[\x00]/.test(rel) || rel.split(/[\\/]/).some((p) => p === ".." || /^[A-Za-z]:$/.test(p))) {
+    throw oatsError("E_PACKAGE_MANIFEST", `${what} must be a relative path inside the package, got ${JSON.stringify(rel)}`, details);
+  }
+}
+
+/** Read + parse a JSON file of the package. A missing file is E_PACKAGE_MANIFEST (the
+ * package is malformed), never a leaked E_REMOTE_PATH_MISSING. */
+async function readJson(remote, remoteRef, commit, path, what, details) {
+  let bytes;
+  try { ({ bytes } = await remote.readRemoteFile(remoteRef, commit, path)); } catch (e) {
+    if (e?.code === "E_REMOTE_PATH_MISSING") throw oatsError("E_PACKAGE_MANIFEST", `${what} is missing: no ${path} in ${typeof remoteRef === "string" ? remoteRef : remoteRef?.key}@${String(commit).slice(0, 12)}`, { ...details, path, cause: e.code });
+    throw e;
   }
-
-  // Offsets of each side relative to the base, accumulated across groups: every
-  // line outside a group is common to base and that side, so the mapping is
-  // exact rather than approximate.
-  let localOffset = 0, templateOffset = 0;
-  const regions = [];
-  for (const [index, group] of groups.entries()) {
-    const span = group.aEnd - group.aStart;
-    const localItems = group.items.filter((it) => it.side === "local").map((it) => it.r);
-    const templateItems = group.items.filter((it) => it.side === "template").map((it) => it.r);
-    const localStart = group.aStart + localOffset;
-    const templateStart = group.aStart + templateOffset;
-    const localLen = span + localItems.reduce((sum, r) => sum + regionDelta(r), 0);
-    const templateLen = span + templateItems.reduce((sum, r) => sum + regionDelta(r), 0);
-    localOffset += localLen - span;
-    templateOffset += templateLen - span;
-
-    const baseSlice = base.slice(group.aStart, group.aEnd).join("");
-    const localSlice = local.slice(localStart, localStart + localLen).join("");
-    const templateSlice = template.slice(templateStart, templateStart + templateLen).join("");
-
-    const localChanged = localItems.length > 0;
-    const templateChanged = templateItems.length > 0;
-    let kind;
-    if (localChanged && templateChanged) kind = localSlice === templateSlice ? "agreed" : "conflict";
-    else if (templateChanged) kind = "upstream";
-    else kind = "local";
-
-    regions.push({
-      id: `h${index + 1}`,
-      kind,
-      recommended: kind === "conflict" ? null : kind === "upstream" ? "package" : "local",
-      digest: digestOf(baseSlice, localSlice, templateSlice),
-      base: { start: group.aStart, end: group.aEnd, text: baseSlice },
-      local: { start: localStart, end: localStart + localLen, text: localSlice },
-      template: { start: templateStart, end: templateStart + templateLen, text: templateSlice },
-    });
+  try { return JSON.parse(Buffer.from(bytes).toString("utf8")); } catch (e) {
+    throw oatsError("E_PACKAGE_MANIFEST", `${what} at ${path} is not valid JSON: ${e.message}`, { ...details, path });
   }
-
-  const counts = { upstream: 0, local: 0, conflict: 0, agreed: 0 };
-  for (const r of regions) counts[r.kind]++;
-  return {
-    regions,
-    counts,
-    conflicts: regions.filter((r) => r.kind === "conflict").map((r) => r.id),
-    // "clean" means a caller can apply the recommendations without asking anyone.
-    clean: counts.conflict === 0,
-    localDigest: digestOf(localText),
-    planDigest: digestOf(baseText, localText, templateText),
-  };
 }
 
-/** Apply a plan's decisions to the LOCAL text, byte-preservingly.
- *
- * decisions: { [regionId]: "local" | "package" | { edit: "<replacement text>" } }
- * Regions with no decision fall back to `recommended`; a conflict has none, so
- * an unresolved conflict is a typed failure (E_SYNC_AMBIGUOUS) rather than a
- * silent pick — that is the noninteractive fail-closed rule.
- *
- * Returns { text, applied }. `applied` lists the regions that actually changed
- * bytes. With no decisions and no upstream regions, text === localText exactly,
- * byte for byte. */
-export function applyConfigMerge(localText, plan, decisions = {}) {
-  const local = splitConfigLines(localText);
-  // A plan carries the digest of the local text it was computed against. Line
-  // indices are meaningless against any other text, so applying a plan the user
-  // reviewed before the file changed under them must fail, not splice at the
-  // old offsets.
-  if (plan.localDigest && plan.localDigest !== digestOf(localText)) {
-    fail("E_SYNC_STALE_PLAN", "the local oats-config.yaml changed after this merge plan was computed — re-run the diff and review the plan again");
-  }
-
-  const byId = new Map(plan.regions.map((r) => [r.id, r]));
-  for (const id of Object.keys(decisions)) {
-    if (!byId.has(id)) fail("E_SYNC_UNKNOWN_REGION", `no such change region "${id}" in this plan (regions: ${[...byId.keys()].join(", ") || "none"})`);
+/** Read `oats-package.json` and every capability manifest it lists.
+ * → { manifest, capabilities: [{ name, dir, manifest }] } (sorted by name, codepoint order).
+ * Two capability dirs declaring the same name → E_PACKAGE_MANIFEST { duplicate }. */
+export async function readPackageManifests(remote, remoteRef, commit, path, details = {}) {
+  const manifestPath = pjoin(path, PACKAGE_MANIFEST);
+  const manifest = await readJson(remote, remoteRef, commit, manifestPath, "package manifest", details);
+  if (!plainObject(manifest) || typeof manifest.package !== "string" || !Array.isArray(manifest.capabilities)) {
+    throw oatsError("E_PACKAGE_MANIFEST", `package manifest at ${manifestPath} must declare "package" and "capabilities"`, { ...details, path: manifestPath });
   }
-
-  const chosen = [];
-  for (const region of plan.regions) {
-    const raw = Object.hasOwn(decisions, region.id) ? decisions[region.id] : region.recommended;
-    if (raw === null || raw === undefined) {
-      fail("E_SYNC_AMBIGUOUS", `change region ${region.id} is a conflict — the local file and the package template both changed it, so it needs an explicit local/package/edit choice`);
+  const capabilities = [];
+  const seen = new Map();
+  for (const rel of manifest.capabilities) {
+    assertRelPath(`${manifestPath} capabilities[]`, rel, { ...details, path: manifestPath });
+    const dir = pjoin(path, rel);
+    const capManifest = await readJson(remote, remoteRef, commit, pjoin(dir, CAPABILITY_MANIFEST), "capability manifest", details);
+    if (!plainObject(capManifest) || typeof capManifest.capability !== "string" || !capManifest.capability) {
+      throw oatsError("E_PACKAGE_MANIFEST", `capability manifest at ${pjoin(dir, CAPABILITY_MANIFEST)} must declare "capability"`, { ...details, path: dir });
     }
-    if (typeof raw === "object") {
-      if (typeof raw.edit !== "string") fail("E_SYNC_BAD_DECISION", `change region ${region.id}: an edit decision needs { edit: "<text>" }`);
-      chosen.push({ region, choice: "edit", text: raw.edit });
-      continue;
+    if (seen.has(capManifest.capability)) {
+      throw oatsError("E_PACKAGE_MANIFEST", `package ${manifest.package} declares capability ${JSON.stringify(capManifest.capability)} twice (${seen.get(capManifest.capability)} and ${dir})`, { ...details, path: dir, duplicate: capManifest.capability, other: seen.get(capManifest.capability) });
     }
-    if (raw !== "local" && raw !== "package") fail("E_SYNC_BAD_DECISION", `change region ${region.id}: decision must be "local", "package", or { edit }, not ${JSON.stringify(raw)}`);
-    chosen.push({ region, choice: raw, text: raw === "local" ? region.local.text : region.template.text });
-  }
-
-  const out = [];
-  const applied = [];
-  let cursor = 0;
-  for (const { region, choice, text } of chosen) {
-    out.push(local.slice(cursor, region.local.start).join(""));
-    let replacement = text;
-    const isTail = region.local.end >= local.length;
-    // A replacement that does not end in a newline while local content follows
-    // would glue two YAML lines together. Terminate it instead of emitting a
-    // corrupt config; the tail region legitimately may end without a newline.
-    if (replacement && !replacement.endsWith("\n") && !isTail) replacement += "\n";
-    out.push(replacement);
-    if (replacement !== region.local.text) applied.push({ id: region.id, kind: region.kind, choice });
-    cursor = region.local.end;
+    seen.set(capManifest.capability, dir);
+    capabilities.push({ name: capManifest.capability, dir, manifest: capManifest });
   }
-  out.push(local.slice(cursor).join(""));
-  return { text: out.join(""), applied };
-}
-
-// ---------- run-level rollback journal (CLI-private) ----------
-//
-// A multi-step init or template adoption touches several artifacts that no
-// single engine call spans: the active config, the lock, the flat installed
-// capability store, the capability .gitignore, and the adopted template base
-// plus its metadata. Engine operations are individually atomic and expose no
-// transaction handle, so the RUN-level guarantee — "a later failure rolls back
-// only this run's changes and preserves pre-existing bytes/artifacts" — is the
-// CLI's to keep. This journal is that mechanism, deliberately private to this
-// lane rather than a public kernel API.
-//
-// It is engine-independent by construction: paths in, bytes out. It knows the
-// scope layout and nothing about locks, packages, or capabilities.
-
-/** Scope-relative artifacts a run-level transaction must be able to undo. */
-export const RUN_JOURNAL_PATHS = Object.freeze([
-  "oats-config.yaml",
-  "oats-lock.json",
-  ".agents/capabilities/installed",
-  ".agents/capabilities/.gitignore",
-  ".agents/config-templates/adopted",
-  // The recoverable backup is run state too. Without it a failed sync could
-  // leave a .bak from THIS run behind (or destroy one an earlier run left),
-  // and rollback would report a clean failure that was not clean.
-  "oats-config.yaml.bak",
-]);
-
-/** The anchor whose creation is itself part of the run's changes. */
-const AGENTS_ANCHOR = ".agents";
-
-const isInside = (base, p) => p === base || p.startsWith(base.endsWith(sep) ? base : base + sep);
-
-/** Record what a path IS without following it: absent, symlink (+target), dir, or file (+mode). */
-function classifyPath(p) {
-  let st;
-  try { st = lstatSync(p); } catch { return { kind: "absent" }; }
-  if (st.isSymbolicLink()) return { kind: "symlink", target: readlinkSync(p), mode: st.mode & 0o7777 };
-  if (st.isDirectory()) return { kind: "dir", mode: st.mode & 0o7777 };
-  return { kind: "file", mode: st.mode & 0o7777 };
+  capabilities.sort((a, b) => byCodepoint(a.name, b.name));
+  return { manifest, capabilities };
 }
 
-/** Reject ANY symlink in an INTERMEDIATE component of a protected path.
- *
- * One escaping out of the scope is the obvious danger: restoring through it
- * would delete or rewrite outer-scope state this run never owned. But a
- * CONTAINED alias is refused too, because it makes two protected paths address
- * the same bytes — restoring one entry then silently deletes or overwrites
- * another entry's artifact, and the outcome depends on entry order. A journal
- * whose entries can overlap cannot promise byte-exact restoration, so the only
- * safe posture is to refuse the layout rather than guess an ordering.
- *
- * A symlink AT the protected path itself is fine: it is captured and restored
- * verbatim and never written through. */
-function assertJournalContainment(scopeReal, rel) {
-  const parts = rel.split("/").filter(Boolean);
-  let cur = scopeReal;
-  for (const part of parts.slice(0, -1)) {
-    cur = join(cur, part);
-    let st;
-    try { st = lstatSync(cur); } catch { return; } // absent from here down: nothing to alias or escape through
-    if (!st.isSymbolicLink()) continue;
-    if (!isInside(scopeReal, realpathSync(cur))) {
-      fail("E_JOURNAL_PATH_ESCAPE", `refusing to journal ${rel}: "${part}" is a symlink leaving ${scopeReal}`);
+/** Content digest of the package tree at `path`: the digest `fetchRemoteTree` reports for a
+ * copy into a scratch directory (contract §1: `contentDigest(dir)` is the local-directory form;
+ * the remote has no digest-without-copy primitive yet — see the deferred note in the review). */
+async function packageIntegrity(remote, remoteRef, commit, path) {
+  if (typeof remote.fetchRemoteTree !== "function") {
+    throw oatsError("E_PACKAGE_INTEGRITY", "remote must provide fetchRemoteTree() to compute a package's integrity", { path: "/remote" });
+  }
+  const scratch = mkdtempSync(join(tmpdir(), "oats-pkg-"));
+  const dest = join(scratch, "tree");
+  try {
+    const { digest } = await remote.fetchRemoteTree(remoteRef, commit, path, dest, { allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
+    return digest;
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+
+/** Depth bound for reading a capability directory: deep enough for any real layout. */
+export const PACKAGE_TREE_DEPTH = 64;
+
+/** Build a `packageTree` (see module header) for `executablesDigest` from the remote.
+ * Reads every blob under each capability directory. */
+export async function readPackageTree(remote, remoteRef, commit, path, { depth = PACKAGE_TREE_DEPTH, remoteOptions } = {}) {
+  remote = bindRemote(remote, remoteOptions);
+  const { capabilities } = await readPackageManifests(remote, remoteRef, commit, path);
+  const manifests = [];
+  for (const cap of capabilities) {
+    const listing = await remote.listRemoteTree(remoteRef, commit, cap.dir, { depth });
+    const files = new Map();
+    for (const item of listing) {
+      if (item.type !== "blob") continue;
+      const { bytes } = await remote.readRemoteFile(remoteRef, commit, pjoin(cap.dir, item.path));
+      files.set(item.path, Buffer.from(bytes));
     }
-    fail("E_JOURNAL_SYMLINK_COMPONENT", `refusing to journal ${rel}: "${part}" is a symlink aliasing another directory inside ${scopeReal} — two journal entries could then address the same bytes`);
+    manifests.push({ name: cap.name, manifest: cap.manifest, files });
   }
+  return { manifests };
 }
 
-/** Normalize one journalled relative path and reject anything ambiguous.
- * Fail-closed on purpose: this is a private API whose callers are in this
- * repository, so a malformed path is a bug to surface, never to interpret. */
-function canonicalJournalRel(rel, seen) {
-  if (typeof rel !== "string") fail("E_JOURNAL_BAD_PATH", `journalled path must be a string, got ${typeof rel}`);
-  const trimmed = rel.trim();
-  if (!trimmed) fail("E_JOURNAL_BAD_PATH", "journalled path must be a nonempty relative path");
-  if (trimmed.includes("\\")) fail("E_JOURNAL_BAD_PATH", `journalled path must use "/" separators: ${rel}`);
-  if (isAbsolute(trimmed)) fail("E_JOURNAL_PATH_ESCAPE", `journalled path must stay inside the scope: ${rel}`);
-  const parts = trimmed.split("/").filter((p) => p !== "" && p !== ".");
-  if (parts.includes("..")) fail("E_JOURNAL_PATH_ESCAPE", `journalled path must stay inside the scope: ${rel}`);
-  if (!parts.length) fail("E_JOURNAL_BAD_PATH", `journalled path resolves to the scope itself: ${rel}`);
-  const canonical = parts.join("/");
-  if (seen.has(canonical)) fail("E_JOURNAL_DUPLICATE_PATH", `journalled path listed more than once: ${canonical}`);
-  seen.add(canonical);
-  return canonical;
+// ---------- resolvePackages ----------
+
+function assertDigest(what, value, details) {
+  if (typeof value !== "string" || !DIGEST_RE.test(value)) throw oatsError("E_PACKAGE_INTEGRITY", `${what} is not a sha256-<hex> digest: ${JSON.stringify(value)}`, details);
+  return value;
 }
 
-/** Copy preserving type, symlink targets, modes, and timestamps.
- *
- * Hand-walked rather than fs.cpSync: cpSync's native recursion ABORTS THE
- * PROCESS with an uncatchable C++ filesystem_error when it meets an unreadable
- * directory (measured on node 22). A capability store with one bad-permission
- * directory would then kill the whole command with a libc++ message and no
- * cleanup, instead of a typed failure this journal can compensate. readdirSync
- * raises an ordinary catchable EACCES, which is what the constructor's cleanup
- * needs to work at all. */
-function copyExact(from, to) {
-  const st = lstatSync(from);
-  mkdirSync(dirname(to), { recursive: true });
-  if (st.isSymbolicLink()) { symlinkSync(readlinkSync(from), to); return; }
-  if (st.isDirectory()) {
-    mkdirSync(to, { recursive: true });
-    for (const name of readdirSync(from)) copyExact(join(from, name), join(to, name));
-    // Mode and times go on AFTER the children: a read-only directory set first
-    // would reject its own contents.
-    chmodSync(to, st.mode & 0o7777);
-    utimesSync(to, st.atime, st.mtime);
-    return;
+/** Bind `remoteOptions` (cacheDir, exec, …) into every call of a contract-§1 remote. */
+export function bindRemote(remote, remoteOptions) {
+  if (!remoteOptions || Object.keys(remoteOptions).length === 0) return remote;
+  const bound = { ...remote };
+  for (const name of ["observeRemote", "readRemoteFile", "listRemoteTree", "fetchRemoteTree"]) {
+    if (typeof remote[name] !== "function") continue;
+    bound[name] = (...args) => {
+      const arity = { observeRemote: 1, readRemoteFile: 3, listRemoteTree: 3, fetchRemoteTree: 4 }[name];
+      const opts = { ...(args[arity] || {}), ...remoteOptions };
+      return remote[name](...args.slice(0, arity), opts);
+    };
   }
-  if (!st.isFile()) fail("E_JOURNAL_UNSUPPORTED_ENTRY", `cannot journal ${from}: not a regular file, directory, or symlink`);
-  copyFileSync(from, to);
-  chmodSync(to, st.mode & 0o7777);
-  utimesSync(to, st.atime, st.mtime);
+  return bound;
 }
 
-/** Open a run-level rollback journal over one scope.
+/**
+ * Resolve every `workspace.packages` entry to an exact commit + integrity and
+ * merge into the lock (immutably — the input lock is never mutated).
  *
- * Snapshots every artifact in RUN_JOURNAL_PATHS (plus any `extraPaths`) exactly
- * as it is right now — bytes, file type, symlink targets, and mode bits — into a
- * backup directory OUTSIDE the protected tree, and records which ancestor
- * directories (including the `.agents` anchor) this run would be creating.
+ * options.catalog: package-catalog.json (file shape or its `packages` map)
+ * options.lock:    current lock (v3) — defaults to an empty lock
+ * options.remote:  { observeRemote, readRemoteFile, listRemoteTree, fetchRemoteTree } — defaults to
+ *                  lib/remote.mjs; tests pass an in-memory fake. options.remoteOptions (cacheDir, exec, …)
+ *                  is threaded into every remote call.
  *
- * Then exactly one of:
- *   rollback()  restore every snapshot, remove everything the run created, and
- *               report truthfully — including partial failure.
- *   finalize()  the run succeeded: discard the backup. Call it only after every
- *               command-owned write has finished, because it is the point of no
- *               return.
- * Both are idempotent; rollback after finalize is a caller bug and throws. */
-export function beginRunJournal(scopeDir, { backupRoot = tmpdir(), extraPaths = [] } = {}) {
-  const scope = resolve(scopeDir);
-  if (!existsSync(scope)) fail("E_JOURNAL_NO_SCOPE", `cannot journal a run at ${scope}: the scope directory does not exist`);
-  const scopeReal = realpathSync(scope);
-
-  // Validate and canonicalize BEFORE staging anything, so a malformed call
-  // never creates a backup directory it then has to clean up.
-  const seen = new Set();
-  const rels = [...RUN_JOURNAL_PATHS, ...extraPaths].map((rel) => canonicalJournalRel(rel, seen));
-
-  // Directories that already existed. Anything NOT here that exists at rollback
-  // time was created by this run and must be pruned once it is empty — which is
-  // also what makes "remove a run-created .agents anchor only when empty" fall
-  // out rather than being a special case.
-  const preexistingDirs = new Set();
-  const noteAncestors = (rel) => {
-    const parts = rel.split("/").filter(Boolean);
-    let cur = scope;
-    for (const part of parts.slice(0, -1)) {
-      cur = join(cur, part);
-      if (existsSync(cur)) preexistingDirs.add(cur);
-    }
-  };
-
-  const backupDir = mkdtempSync(join(backupRoot, "oats-run-journal-"));
-  const entries = [];
-  let anchorExisted;
-  try {
-    // The backup must not live inside the tree it protects: restoring a
-    // directory means deleting it first, which would delete the backup with it.
-    if (isInside(scopeReal, realpathSync(backupDir))) {
-      fail("E_JOURNAL_BACKUP_INSIDE_SCOPE", `run-journal backup ${backupDir} would live inside the protected scope ${scopeReal}`);
-    }
-    for (const [index, rel] of rels.entries()) {
-      assertJournalContainment(scopeReal, rel);
-      noteAncestors(rel);
-      const path = join(scope, rel);
-      const state = classifyPath(path);
-      // Keyed by INDEX, never by a flattened path: "a/b" and "a__b" are
-      // different artifacts and any separator-substitution scheme collides them,
-      // which would restore one entry's bytes over the other's.
-      const backup = state.kind === "absent" ? null : join(backupDir, String(index));
-      if (backup) copyExact(path, backup);
-      entries.push({ rel, path, backup, ...state });
-    }
-    const anchorPath = join(scope, AGENTS_ANCHOR);
-    anchorExisted = preexistingDirs.has(anchorPath) || existsSync(anchorPath);
-    if (anchorExisted) preexistingDirs.add(anchorPath);
-  } catch (e) {
-    // A half-built journal protects nothing, so it must not outlive the
-    // failure: leaving the partial backup behind would strand a copy of the
-    // scope's bytes in the temp tree with no owner to clean it up.
-    rmSync(backupDir, { recursive: true, force: true });
-    throw e;
-  }
-
-  const anchorPath = join(scope, AGENTS_ANCHOR);
-
-  let state = "open";
+ * → { lock, changes: [{ id, from, to, commit, approvalNeeded }] }
+ *   - `from` is the previously locked version or null; `to` is the resolved version
+ *     (null when the package was removed from the workspace and dropped from the lock).
+ *   - `approvalNeeded` = the entry's `approved` is null.
+ *   - A locked entry whose version string is unchanged but whose commit or
+ *     integrity moved → E_PACKAGE_INTEGRITY { id, version, locked, observed }.
+ *   - Unchanged entries keep their approval ONLY when the recorded executables digest still
+ *     matches the tree (else E_PACKAGE_UNAPPROVED); a new version starts unapproved.
+ *   - A value resolving to a BRANCH → E_PACKAGE_INTEGRITY { why: "branch" }: versions are immutable.
+ */
+export async function resolvePackages(workspace, { catalog = {}, lock = emptyLock(), remote = defaultRemote, remoteOptions } = {}) {
+  if (!remote || typeof remote.observeRemote !== "function" || typeof remote.readRemoteFile !== "function") {
+    throw new TypeError("resolvePackages: remote must provide observeRemote()/readRemoteFile() (module contract §1)");
+  }
+  remote = bindRemote(remote, remoteOptions);
+  const previous = validateLock(lock);
+  const requests = plainObject(workspace?.packages) ? workspace.packages : {};
+  const ids = Object.keys(requests).sort();
+  const nextPackages = {};
+  const changes = [];
 
-  /** Restore one entry to exactly what it was; absence is itself a state to restore. */
-  const restoreEntry = (entry, report) => {
-    // Absent then, absent now: nothing to undo. Every other case is restored
-    // unconditionally — comparing first would only save work, and a comparison
-    // that is subtly wrong silently skips a restore the run depended on.
-    if (entry.kind === "absent" && classifyPath(entry.path).kind === "absent") return;
-    try {
-      // Remove whatever is there now. On a symlink this unlinks the link
-      // itself, so a hostile link target is never written through.
-      rmSync(entry.path, { recursive: true, force: true });
-      if (entry.kind === "absent") { report.removed.push(entry.rel); return; }
-      copyExact(entry.backup, entry.path);
-      if (entry.kind !== "symlink") chmodSync(entry.path, entry.mode);
-      report.restored.push(entry.rel);
-    } catch (e) {
-      report.failures.push({ path: entry.rel, error: e.message });
+  for (const id of ids) {
+    const req = parsePackageRequest(id, requests[id], catalog);
+    const details = { id, value: requests[id] };
+    const obs = await remote.observeRemote(req.remoteRef, { at: req.at });
+    if (!obs || typeof obs.commit !== "string" || !OID_RE.test(obs.commit)) {
+      throw oatsError("E_PACKAGE_INTEGRITY", `packages.${id}: remote did not yield a full commit OID for ${req.remoteRef}@${req.at}`, { ...details, observed: obs?.commit });
     }
-  };
-
-  /** Remove directories this run created, deepest first, and only while empty. */
-  const pruneCreatedDirs = (report) => {
-    const candidates = new Set();
-    for (const { rel } of entries) {
-      const parts = rel.split("/").filter(Boolean);
-      let cur = scope;
-      for (const part of parts.slice(0, -1)) { cur = join(cur, part); candidates.add(cur); }
+    // A package version must be immutable: a branch is a moving target and is refused up front
+    // (a tag that later moves is caught below as E_PACKAGE_INTEGRITY).
+    if (typeof obs.ref === "string" && /^refs\/heads\//.test(obs.ref)) {
+      throw oatsError("E_PACKAGE_INTEGRITY", `packages.${id}: ${req.at} is a branch (${obs.ref}), not a version — pin a tag or a full commit OID`, { ...details, why: "branch", ref: obs.ref, commit: obs.commit });
     }
-    candidates.add(anchorPath);
-    for (const dir of [...candidates].sort((a, b) => b.length - a.length)) {
-      if (preexistingDirs.has(dir) || !existsSync(dir)) continue;
-      try {
-        if (readdirSync(dir).length) continue; // not ours to empty — owned/ or a stranger's file lives here
-        rmdirSync(dir);
-        report.removed.push(dir.slice(scope.length + 1) || AGENTS_ANCHOR);
-      } catch (e) {
-        report.failures.push({ path: dir.slice(scope.length + 1) || AGENTS_ANCHOR, error: e.message });
+    const source = req.kind === "catalog" ? `catalog:${id}` : `git:${obs.key}@${req.at}`;
+    const version = req.kind === "catalog" ? versionOf(requests[id].trim()) : versionOf(req.at);
+    const old = previous.packages[id] || null;
+
+    // Same version + same source + same path as locked: the lock must still describe reality.
+    if (old && old.version === version && old.source === source && old.path === req.path) {
+      if (old.commit !== obs.commit) {
+        throw oatsError("E_PACKAGE_INTEGRITY",
+          `packages.${id} ${version} is locked at ${old.commit} but ${source} now resolves to ${obs.commit} — the tag moved; a version string must change when its content does`,
+          { ...details, version, locked: { commit: old.commit, integrity: old.integrity }, observed: { commit: obs.commit } });
       }
+      const integrity = assertDigest(`packages.${id} integrity`, await packageIntegrity(remote, req.remoteRef, obs.commit, old.path), details);
+      if (integrity !== old.integrity) {
+        throw oatsError("E_PACKAGE_INTEGRITY",
+          `packages.${id} ${version} @ ${obs.commit}: content digest ${integrity} does not match the locked ${old.integrity}`,
+          { ...details, version, locked: { commit: old.commit, integrity: old.integrity }, observed: { commit: obs.commit, integrity } });
+      }
+      // A recorded approval must describe THESE executables, not merely any well-formed digest.
+      if (old.approved) {
+        const executables = executablesDigest(await readPackageTree(remote, req.remoteRef, obs.commit, old.path));
+        if (executables !== old.approved.executables) {
+          throw oatsError("E_PACKAGE_UNAPPROVED",
+            `packages.${id} ${version}: the recorded approval ${old.approved.executables} does not match the package's executables ${executables} — approve again`,
+            { ...details, version, commit: obs.commit, approved: old.approved, executables });
+        }
+      }
+      nextPackages[id] = clone(old);
+      continue;
     }
-  };
-
-  return {
-    scope,
-    backupDir,
-    anchorCreatedByRun: !anchorExisted,
-    /** What the journal is protecting, for previews and diagnostics. */
-    protected: entries.map(({ rel, kind }) => ({ path: rel, was: kind })),
-    get state() { return state; },
-
-    /** Undo this run. Attempts EVERY step even after one fails, so a partial
-     * failure is reported in full rather than hidden behind the first error. */
-    rollback() {
-      if (state === "finalized") fail("E_JOURNAL_FINALIZED", "this run was already finalized — its backup is gone and it cannot be rolled back");
-      const report = { restored: [], removed: [], failures: [], complete: true, summary: "" };
-      if (state === "rolled-back") { report.summary = "nothing to roll back (already rolled back)"; return report; }
-      for (const entry of entries) restoreEntry(entry, report);
-      pruneCreatedDirs(report);
-      report.complete = report.failures.length === 0;
-      report.summary = report.complete
-        ? `rolled back ${report.restored.length} restored, ${report.removed.length} removed`
-        : `ROLLBACK INCOMPLETE — ${report.failures.length} of ${entries.length} artifact(s) could not be restored: ${report.failures.map((f) => `${f.path} (${f.error})`).join("; ")}`;
-      // The backup survives an incomplete rollback: it is the only remaining
-      // copy of the pre-run bytes, so destroying it would turn a recoverable
-      // failure into permanent loss.
-      if (report.complete) { rmSync(backupDir, { recursive: true, force: true }); state = "rolled-back"; }
-      return report;
-    },
-
-    /** The run succeeded — drop the backup. Point of no return. */
-    finalize() {
-      if (state === "rolled-back") fail("E_JOURNAL_ROLLED_BACK", "this run was already rolled back and cannot be finalized");
-      rmSync(backupDir, { recursive: true, force: true });
-      state = "finalized";
-    },
-  };
-}
-
-/** Capability ids supplied by the visible locked packages of a scope.
- *
- * Reads the CAPABILITY rows, not the package rows: in the revised lock a
- * package row carries no capability list at all, and the capability row's
- * `package` back-reference is the single provider truth — which is exactly why
- * the two levels can no longer disagree. */
-export function lockedPackageCapabilities(startDir) {
-  const out = new Map(); // capability id → [package ids]
-  for (const [capId, row] of Object.entries(readPackageLocks(startDir).capabilities)) {
-    if (!out.has(capId)) out.set(capId, []);
-    out.get(capId).push(row.package);
-  }
-  return out;
-}
 
-/** Resolve a package id/path to its ENGINE-loaded manifest for profile
- * adoption/diff. Installed ids resolve through listInstalledPackages (the
- * engine's indexed store); local paths load directly. Git URLs are cloned by
- * the caller (adoption acquires; diff uses a temp clone). */
-export function resolveProfilePackage(src, dir, { clone } = {}) {
-  // Classify through the ENGINE's parser, never a local regex: a diff that
-  // disagreed with acquisition about what a source spells (which git
-  // spellings count, which contained root is selected) would compare the
-  // adopted snapshot against a profile the install never used.
-  // A malformed source is a typed failure, never a fall-through to the
-  // installed-id lookup: "#../escape" must report path-escape, not "not an
-  // installed package id".
-  const parsedSrc = parsePackageSource(src);
-  if (parsedSrc.kind === "path") {
-    const abs = parsedSrc.path; // absolute, tilde already expanded
-    const manifest = loadPackageManifestAt(abs); // throws invalid-package-manifest with the engine code
-    return { manifest, commit: "local", source: `path:${abs}` };
-  }
-  const isUrl = parsedSrc.kind === "git";
-  if (isUrl) {
-    if (!clone) fail("invalid-source", "git package sources need a clone directory (internal)");
-    // Select the CONTAINED package root exactly the way acquisition does — the
-    // profile a diff compares against must come from the same directory the
-    // install would lock, not from whatever sits at the repository root.
-    // The REF matters for the same reason: reading HEAD's profile while the
-    // returned provenance claims "@v1" compares the snapshot against a version
-    // the install never used. A shallow clone cannot check out an arbitrary
-    // ref, so only the unpinned case stays shallow.
-    // The ref is resolved and verified by the ENGINE before checkout: a
-    // caller-supplied ref must never reach git as an option-capable argument
-    // (see gitCheckoutExactRef).
-    const ref = parsedSrc.ref;
-    execFileSync("git", ["clone", "-q", ...(ref ? [] : ["--depth", "1"]), parsedSrc.url, clone], { stdio: ["ignore", "pipe", "pipe"] });
-    const commit = ref
-      ? gitCheckoutExactRef(clone, ref, src)
-      : execFileSync("git", ["-C", clone, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
-    const manifest = loadPackageManifestAt(resolvePackageRoot(clone, parsedSrc.packagePath ?? DEFAULT_PACKAGE_PATH, src));
-    return { manifest, commit, source: parsedSrc.normalized };
+    const { capabilities } = await readPackageManifests(remote, req.remoteRef, obs.commit, req.path, details);
+    const integrity = assertDigest(`packages.${id} integrity`, await packageIntegrity(remote, req.remoteRef, obs.commit, req.path), details);
+    nextPackages[id] = {
+      source, url: obs.url, path: req.path, version, commit: obs.commit, integrity,
+      capabilities: capabilities.map((c) => c.name).sort(),
+      approved: null,
+    };
+    changes.push({ id, from: old ? old.version : null, to: version, commit: obs.commit, approvalNeeded: true });
   }
-  // Installed/locked package id visible from dir (engine indexing).
-  // findLast: closest scope wins for a package identity (the listing is
-  // outermost → innermost and may hold the same id at two levels).
-  const pkg = listInstalledPackages(dir).findLast((p) => p.package === src);
-  if (!pkg) fail("invalid-source", `"${src}" is not an installed package id, local path, or git URL at ${dir} — acquire it first with \`oats install <source>\``);
-  return { manifest: pkg.manifest, commit: pkg.commit || "local", source: pkg.source };
-}
-
-// ---------- team-boundary workspace scope discovery ----------
-
-/** Directory names pruned during descendant scope discovery (dependency/vendor trees). */
-export const PRUNED_DIR_NAMES = new Set([".git", "node_modules", "vendor", ".venv", "venv", "bower_components", ".direnv"]);
-
-const isScopeDir = (dir) => existsSync(join(dir, "oats-config.yaml")) || existsSync(join(dir, OATS_LOCK_FILE));
-const declaresTeam = (dir) => {
-  const file = join(dir, "oats-config.yaml");
-  if (!existsSync(file)) return false;
-  try { return !!parseYamlNested(readFileSync(file, "utf8")).team; } catch { return false; }
-};
-
-/** A distribution package ROOT — the directory carrying the oats-package.json
- * manifest. Everything BELOW it is package PAYLOAD (see its use in
- * walkBoundaryDirs). The literal filename matches the engine's readers in
- * lib/core.mjs; there is no custom manifest name in the contract. */
-const isPackageRoot = (dir) => existsSync(join(dir, "oats-package.json"));
-
-/** The one pruned walk under a team boundary: .git, generated stores
- * (.agents), dependency/vendor dirs, agent instance homes/worktrees,
- * local-agents, nested team boundaries, and package PAYLOAD (anything under an
- * oats-package.json manifest) are skipped. `visit` is called on every surviving
- * directory in deterministic path order; the boundary itself is not visited. */
-function walkBoundaryDirs(boundary, visit) {
-  const walk = (dir) => {
-    let entries;
-    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
-    const names = entries.filter((e) => e.isDirectory() && !e.isSymbolicLink()).map((e) => e.name).sort((x, y) => x.localeCompare(y));
-    for (const name of names) {
-      if (PRUNED_DIR_NAMES.has(name)) continue;
-      const child = join(dir, name);
-      // Generated stores (.agents: capability/package stores, injections) never
-      // contain deployment scopes; agent instance homes/worktrees and local
-      // souls are runtime state, not workspace repositories.
-      if (name === ".agents") continue;
-      if (name === "local-agents") continue;
-      if (name === "instances" && existsSync(join(dir, "soul"))) continue;
-      // Nested team boundary: a descendant scope declaring its own team: is its own reconciliation unit.
-      if (declaresTeam(child)) continue;
-      visit(child);
-      // Package PAYLOAD is content the package exports, not deployment scopes.
-      // A member repo shipping a package carries config TEMPLATES (declared via
-      // configTemplates, canonically under config-templates/) whose layers name
-      // capabilities the adopting deployment has not installed. Reconciling one
-      // as a live scope reported phantom "supplied by no visible locked package"
-      // failures for the whole team. The rule is the MANIFEST, not the literal
-      // template path: custom payload roots exist and one repo may ship several
-      // packages at different paths. A config whose containing ANCESTOR holds an
-      // oats-package.json is payload — so a repo root that is itself a package
-      // root (no manifest ancestor) is still visited above.
-      if (isPackageRoot(child)) continue;
-      walk(child);
-    }
-  };
-  // A boundary that is itself a package root makes every descendant payload.
-  if (!isPackageRoot(boundary)) walk(boundary);
-}
 
-/** Deterministic path-order discovery of descendant scopes inside a team boundary.
- * Prunes .git, generated stores (.agents), dependency/vendor dirs, agent
- * instance homes/worktrees, local-agents, nested team boundaries, and package
- * PAYLOAD (anything under an oats-package.json manifest). The boundary itself
- * is NOT included. Returns sorted absolute paths. */
-export function discoverWorkspaceScopes(boundary) {
-  const out = [];
-  walkBoundaryDirs(boundary, (child) => { if (isScopeDir(child)) out.push(child); });
-  return out;
-}
-
-/** Every VISIBLE lock-owning scope a guided migration must consider, in
- * deterministic path order (ancestors sort before their descendants):
- *   - the explicit scope's ancestor chain, so an outer repo/laptop lock that
- *     the deployment actually reads is migrated too, not silently left on v1;
- *   - the team boundary when the scope declares one;
- *   - descendant config/lock scopes under that boundary, using the same pruned
- *     discovery reconciliation uses (nested team boundaries stay self-owned).
- * Only directories that actually own an oats-lock.json are returned — a scope
- * with no lock has nothing to migrate. */
-export function discoverMigrationScopes(startDir, { teamScope } = {}) {
-  const ownsLock = (dir) => existsSync(join(dir, OATS_LOCK_FILE));
-  const out = new Set();
-  for (let d = resolve(startDir); ; d = dirname(d)) {
-    if (ownsLock(d)) out.add(d);
-    if (dirname(d) === d) break;
+  for (const id of Object.keys(previous.packages).sort()) {
+    if (!(id in requests)) changes.push({ id, from: previous.packages[id].version, to: null, commit: null, approvalNeeded: false });
   }
-  const boundary = resolve(teamScope || startDir);
-  if (ownsLock(boundary)) out.add(boundary);
-  for (const s of discoverWorkspaceScopes(boundary)) if (ownsLock(s)) out.add(resolve(s));
-  // Plain code-unit sort: deterministic, and a parent path is a prefix of its
-  // children so ancestors are always planned and applied first.
-  return [...out].sort();
-}
 
-/** Un-migrated OAS scopes a guided migration must never read as "nothing to
- * do": the ancestor chain plus the same pruned boundary walk migration scope
- * discovery uses. Returns [{dir, files}] in deterministic path order. */
-export function discoverOasScopes(startDir, { teamScope } = {}) {
-  const oasFiles = (dir) => OAS_SCOPE_FILES.filter((f) => existsSync(join(dir, f)));
-  const found = new Map();
-  for (const f of detectOasScopes(startDir)) found.set(f.dir, f.files);
-  const boundary = resolve(teamScope || startDir);
-  const boundaryFiles = oasFiles(boundary);
-  if (boundaryFiles.length) found.set(boundary, boundaryFiles);
-  walkBoundaryDirs(boundary, (child) => {
-    const files = oasFiles(child);
-    if (files.length) found.set(resolve(child), files);
-  });
-  return [...found.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([dir, files]) => ({ dir, files }));
+  return { lock: { lockfileVersion: LOCK_VERSION, packages: sortedObject(nextPackages) }, changes };
 }
 
-// ---------- oats migrate --from-oas (aweb-abfy.3) ----------
-
-/** Legacy id → successor id, straight from the catalog's renaming aliases.
- * The catalog is the ONLY place that knows about renames; nothing here may
- * hard-code an oas.* → oats.* pair. */
-export function oasRenameMap() {
-  const map = Object.create(null);
-  for (const [legacy, target] of Object.entries(officialCapabilityAliases())) {
-    if (target && typeof target === "object" && target.capability && target.capability !== legacy) map[legacy] = target.capability;
-  }
-  return map;
-}
+// ---------- executables digest + approval ----------
 
-/** Pure line transform of an oas-config.yaml: the top-level `oas:` defaults
- * block becomes `oats:`, and capability ids with catalog renames become their
- * successors — in `capability:` values and in additive map keys. Line-based
- * on purpose: comments, ordering and every unrelated byte survive. */
-export function transformOasConfigText(text, renames) {
-  const changes = [];
-  const lines = text.split("\n").map((line) => {
-    let out = line;
-    if (/^oas:\s*(#.*)?$/.test(line)) out = line.replace(/^oas:/, "oats:");
-    else {
-      const cap = line.match(/^(\s*capability:\s*)([A-Za-z0-9_.-]+)(\s*(?:#.*)?)$/);
-      if (cap && renames[cap[2]]) out = cap[1] + renames[cap[2]] + cap[3];
-      else {
-        const key = line.match(/^(\s+)([A-Za-z0-9_.-]+):(\s*(?:#.*)?)$/);
-        if (key && renames[key[2]]) out = key[1] + renames[key[2]] + ":" + key[3];
-      }
-    }
-    if (out !== line) changes.push({ from: line.trim(), to: out.trim() });
-    return out;
-  });
-  return { text: lines.join("\n"), changes };
+/** First token of a `commands` value is the executable target (e.g. "bin/x.mjs cut" → "bin/x.mjs"). */
+export function commandTarget(specification) {
+  return String(specification).trim().split(/\s+/)[0] || "";
 }
 
-/** Everything `oats migrate --from-oas` would change at ONE scope, as explicit
- * steps, plus the validation of every transformed artifact BEFORE anything is
- * touched. Pure read. Steps cover breaks 1-3 of docs/migration-from-oas.md:
- *   - oas-config.yaml → oats-config.yaml (line transform, validated);
- *   - oas-lock.json → oats-lock.json (verbatim — entry ids stay oas.*; the
- *     chained guided migration converts them via the renaming aliases);
- *   - installed capability dirs: oas.json → oats.json (verbatim);
- *   - agents/`*`/soul and local-agents/`*`/soul: .oas-scaffold-owners.json →
- *     .oats-scaffold-owners.json with owner ids mapped to their successors.
- * Break 4 (stale v1 integrity) is deliberately NOT recomputed: the chained
- * migration re-acquires every official capability, which supersedes the
- * artifacts the integrity covered. */
-export function planFromOasScope(scope) {
-  const renames = oasRenameMap();
-  const steps = [];
-  const errors = [];
-  const addStep = (from, to, note, content) => {
-    if (existsSync(to)) { errors.push(`${to} already exists — refusing to overwrite; resolve by hand`); return; }
-    steps.push({ kind: content !== undefined ? "rewrite" : "rename", from, to, note, content });
-  };
-
-  const cfg = join(scope, "oas-config.yaml");
-  if (existsSync(cfg)) {
-    const t = transformOasConfigText(readFileSync(cfg, "utf8"), renames);
-    try {
-      const parsed = parseYamlNested(t.text);
-      validateConfigShape(parsed, join(scope, "oats-config.yaml"));
-    } catch (e) { errors.push(`transformed oats-config.yaml does not validate: ${e.message}`); }
-    addStep(cfg, join(scope, "oats-config.yaml"), t.changes.length ? `${t.changes.length} line change${t.changes.length === 1 ? "" : "s"} (oas: block, capability ids)` : "renamed, content unchanged", t.text);
-  }
-
-  const lock = join(scope, "oas-lock.json");
-  if (existsSync(lock)) {
-    try { JSON.parse(readFileSync(lock, "utf8")); }
-    catch (e) { errors.push(`oas-lock.json is not valid JSON: ${e.message}`); }
-    addStep(lock, join(scope, OATS_LOCK_FILE), "verbatim — entry ids stay oas.* for the chained guided migration to convert");
-  }
-
-  const store = installedCapabilitiesDir(scope);
-  if (existsSync(store)) {
-    for (const e of readdirSync(store, { withFileTypes: true })) {
-      if (!e.isDirectory() || e.name.startsWith(".")) continue;
-      const manifest = join(store, e.name, "oas.json");
-      if (existsSync(manifest)) addStep(manifest, join(store, e.name, "oats.json"), "manifest filename");
-    }
-  }
-
-  for (const root of ["agents", "local-agents"]) {
-    const rootDir = join(scope, root);
-    if (!existsSync(rootDir)) continue;
-    for (const e of readdirSync(rootDir, { withFileTypes: true })) {
-      if (!e.isDirectory()) continue;
-      const owners = join(rootDir, e.name, "soul", ".oas-scaffold-owners.json");
-      if (!existsSync(owners)) continue;
-      let mapped;
-      try {
-        const doc = JSON.parse(readFileSync(owners, "utf8"));
-        mapped = Object.fromEntries(Object.entries(doc).map(([rel, owner]) => [rel, renames[owner] || owner]));
-      } catch (err) { errors.push(`${owners} is not valid JSON: ${err.message}`); continue; }
-      addStep(owners, join(rootDir, e.name, "soul", ".oats-scaffold-owners.json"), "owner ids mapped to successors", JSON.stringify(mapped, null, 2) + "\n");
-    }
+/** Every executable a manifest can make the kernel run: `commands.*` targets AND `hooks.*.command`
+ * targets (hooks run automatically at spawn/retire — the executables an approver most needs to see).
+ * → [{ kind: "command"|"hook", name, target }] in canonical order. */
+export function manifestExecutables(manifest) {
+  const out = [];
+  const commands = plainObject(manifest?.commands) ? manifest.commands : {};
+  for (const cmd of Object.keys(commands).sort(byCodepoint)) out.push({ kind: "command", name: cmd, target: commandTarget(commands[cmd]), spec: commands[cmd] });
+  const hooks = plainObject(manifest?.hooks) ? manifest.hooks : {};
+  for (const hook of Object.keys(hooks).sort(byCodepoint)) {
+    // A hook is { command, ... } (schema: required command) or a bare string. A hook object WITHOUT
+    // `command` is malformed — it enters the list with spec undefined so executablesDigest refuses it
+    // (E_PACKAGE_MANIFEST), never an invisible no-op an approver does not see.
+    const spec = plainObject(hooks[hook]) ? hooks[hook].command : hooks[hook];
+    out.push({ kind: "hook", name: hook, target: spec === undefined || spec === null ? "" : commandTarget(spec), spec });
   }
-
-  return { scope: resolve(scope), steps, errors };
+  return out;
 }
 
-/** Apply one scope's --from-oas rename plan under the run journal and return
- * the OPEN journal: the caller chains the guided v1→v2 migration and only
- * then finalizes, so the whole scope conversion is one transaction — any
- * failure in either phase restores the original OAS-named bytes. */
-export function applyFromOasScope(scope, plan) {
-  const scopeAbs = resolve(scope);
-  // Journal every touched path not already covered by the standard set — an
-  // exact repeat or a path nested under a journalled directory would be
-  // E_JOURNAL_DUPLICATE_PATH / a redundant double snapshot.
-  const covered = (rel) => RUN_JOURNAL_PATHS.some((p) => rel === p || rel.startsWith(`${p}/`));
-  const extraPaths = new Set();
-  for (const s of plan.steps) {
-    for (const p of [s.from, s.to]) {
-      const rel = relative(scopeAbs, p);
-      if (!rel.startsWith("..") && !covered(rel)) extraPaths.add(rel);
-    }
+/**
+ * sha256 over every capability manifest's executables' bytes — `commands` targets and
+ * `hooks.*.command` targets — in canonical codepoint order (manifest name, kind, entry name).
+ * Locale-independent: the same tree digests identically on every machine.
+ * Input is a `packageTree` (module header). A target missing from `files` →
+ * E_PACKAGE_MANIFEST { capability, command, target }. Empty set → the digest of nothing.
+ */
+export function executablesDigest(packageTree) {
+  if (!plainObject(packageTree) || !Array.isArray(packageTree.manifests)) {
+    throw oatsError("E_PACKAGE_MANIFEST", "executablesDigest expects { manifests: [{ name, manifest, files }] }", { path: "/manifests" });
   }
-  const journal = beginRunJournal(scopeAbs, { extraPaths: [...extraPaths] });
-  try {
-    for (const s of plan.steps) {
-      if (s.kind === "rewrite") { writeFileSync(s.to, s.content); rmSync(s.from); }
-      else renameSync(s.from, s.to);
+  const hash = createHash("sha256");
+  const manifests = [...packageTree.manifests].sort((a, b) => byCodepoint(String(a.name), String(b.name)));
+  for (const { name, manifest, files } of manifests) {
+    for (const { kind, name: entry, target, spec } of manifestExecutables(manifest)) {
+      const label = kind === "hook" ? `hooks.${entry}.command` : `commands.${entry}`;
+      const details = { capability: name, command: entry, kind, target };
+      if (typeof spec !== "string") throw oatsError("E_PACKAGE_MANIFEST", `${name}: ${label} must be a string, got ${typeof spec}`, details);
+      assertRelPath(`${name} ${label}`, target, details);
+      const bytes = files instanceof Map ? files.get(target) : (plainObject(files) && Object.hasOwn(files, target) ? files[target] : undefined);
+      if (bytes === undefined) throw oatsError("E_PACKAGE_MANIFEST", `${name}: ${label} targets ${target}, which is not in the package`, details);
+      const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+      // Hooks enter the framing under "hooks.<name>" so a hook and a command of the same name never collide.
+      hash.update(`${name}\0${kind === "hook" ? `hooks.${entry}` : entry}\0${target}\0${buf.length}\0`);
+      hash.update(buf);
+      hash.update("\0");
     }
-  } catch (e) {
-    journal.rollback();
-    fail(e.code || "E_FROM_OAS_APPLY", `--from-oas rename phase failed at ${scopeAbs} and was rolled back: ${e.message}`);
-  }
-  return journal;
-}
-
-// ---------- host requirements (structured, consented) ----------
-
-/** Allowlisted install methods. Recipes are data; commands are argv arrays (no shell, no sudo, no auth).
- * Null-prototype: `method.manager` is manifest input, and an ALLOWLIST that
- * answers for inherited `constructor`/`toString` is not an allowlist. */
-export const REQUIREMENT_MANAGERS = {
-  __proto__: null,
-  "npm-global": {
-    scope: "user-level (npm global prefix)",
-    plan: (method) => {
-      const pkg = String(method.package || "");
-      if (!/^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*(@[\w.^~><=-]+)?$/i.test(pkg)) throw new Error(`npm-global package spec is not a plain package name: "${pkg}"`);
-      return { argv: ["npm", "install", "-g", pkg], source: `npm registry (${pkg})` };
-    },
-  },
-  brew: {
-    scope: "user-level (Homebrew prefix)",
-    plan: (method) => {
-      const formula = String(method.formula || method.package || "");
-      if (!/^[a-z0-9][\w.@/-]*$/i.test(formula)) throw new Error(`brew formula is not a plain formula name: "${formula}"`);
-      return { argv: ["brew", "install", formula], source: `Homebrew (${formula})` };
-    },
-  },
-  "download-checksum": {
-    scope: "user-level",
-    plan: () => { throw new Error("download-with-checksum installs are not implemented yet — use the documented install URL"); },
-  },
-};
-
-/** Which runtimes would actually RUN a capability in this scope?
- *
- * A runtime-package requirement must never mutate a host that does not use that
- * runtime: a Claude-only deployment with oats.aweb active is not asked to install
- * a pi package. Capability targeting is per-soul (global/type/soul), so the
- * answer comes from resolving the capability against each known soul and
- * collecting the runtimes of the souls it is actually active for.
- *
- * POLICY when a scope has no souls, or none that the capability targets: the
- * requirement is NOT raised. A fresh deployment cannot know which runtimes its
- * future souls will use, and prompting every host for every runtime is exactly
- * the mutation this exists to avoid. Spawn performs the final, authoritative
- * check against the instance's ACTUAL runtime — which `--runtime` can override
- * after any reconciliation — so a genuinely needed package is still caught
- * there, with a pointed, separately consentable remedy. */
-export function capabilityRuntimeTargets(scope, capId) {
-  const requesters = [];
-  const runtimes = new Set();
-  let souls = 0;
-  let root;
-  try { root = findRoot(scope); } catch { root = undefined; }
-  if (!root) return { runtimes, souls, requesters };
-  let list = [];
-  try { list = listAgents(root); } catch { list = []; }
-  for (const soul of list) {
-    souls++;
-    try {
-      const resolved = resolveOatsConfig(scope, soul.name);
-      if (!(resolved.capabilities || []).some((c) => c.id === capId)) continue;
-      const runtime = soul.runtime || "pi";   // soul default; spawn may override
-      runtimes.add(runtime);
-      requesters.push({ soul: soul.name, runtime });
-    } catch { /* unresolvable souls are reported by the reconciler */ }
   }
-  return { runtimes, souls, requesters };
-}
-
-/** Normalize a manifest `requires` entry to the structured form.
- * Legacy shape: { command, why, install: "https://…" }.
- * A present-but-invalid command (empty, null, non-string) returns a typed
- * invalid record so the fail-closed policy sees it — only a fully ABSENT
- * command key is dropped as "not a requirement". */
-export function normalizeRequirement(req) {
-  if (!req || typeof req !== "object") return undefined;
-  // Runtime-package requirement: satisfied by the RUNTIME's package manager, not
-  // by a command on PATH. `runtime` scopes it — a Claude-only deployment is never
-  // asked to install a pi package. The identity used for dedup, consent and
-  // conflict detection is "<runtime>:<package identity>", version selector
-  // stripped, so @latest and a pinned version are one requirement.
-  if ("runtime" in req && req.runtime !== undefined) {
-    const runtime = typeof req.runtime === "string" ? req.runtime : JSON.stringify(req.runtime);
-    const pkg = typeof req.package === "string" ? req.package : req.package === undefined ? "" : JSON.stringify(req.package);
-    return {
-      kind: "runtime-package", runtime, package: pkg, why: req.why,
-      marketplace: req.marketplace,
-      command: `${runtime}:${runtimePackageIdentity(runtime, pkg)}`,   // identity/consent key
-      install: { docs: typeof req.install === "string" ? req.install : req.install?.docs, methods: [] },
-      _invalid: !RUNTIME_PACKAGE_MANAGERS[runtime]
-        ? `unknown runtime "${runtime}" (known: ${Object.keys(RUNTIME_PACKAGE_MANAGERS).join(", ")})`
-        : !safeRuntimePackageSpec(pkg, runtime)
-          ? `runtime package spec is not a plain source token for ${runtime}: ${JSON.stringify(pkg)}`
-          : req.marketplace !== undefined && !safeRuntimeSourceRef(req.marketplace)
-            ? `marketplace is not a plain source reference: ${JSON.stringify(req.marketplace)}`
-            : undefined,
-    };
-  }
-  // JSON manifests cannot carry undefined; a programmatic undefined counts as absent.
-  if (!("command" in req) || req.command === undefined) return undefined;
-  const nonString = typeof req.command !== "string";
-  const command = nonString ? JSON.stringify(req.command) : req.command;
-  const install = req.install;
-  const base = { command, why: req.why, ...(nonString ? { _nonStringCommand: true } : {}) };
-  if (typeof install === "string" || install === undefined) {
-    return { ...base, install: { docs: typeof install === "string" ? install : undefined, methods: [] } };
-  }
-  if (typeof install !== "object") return { ...base, install: { methods: [] } };
-  const methods = Array.isArray(install.methods) ? install.methods.filter((m) => m && typeof m === "object") : [];
-  return { ...base, install: { docs: install.docs, methods } };
+  return `sha256-${hash.digest("hex")}`;
 }
 
-/** Is a command on PATH? (dependency-free `which`). */
-export function commandOnPath(cmd, env = process.env) {
-  if (!cmd || /[\\/]/.test(cmd)) return false;
-  for (const dir of String(env.PATH || "").split(delimiter)) {
-    if (!dir) continue;
-    try { const st = statSync(join(dir, cmd)); if (st.isFile() && (st.mode & 0o111)) return true; } catch { /* keep looking */ }
-  }
-  return false;
+/** Record the executable approval for package `id`. Returns a NEW lock; the input is untouched. */
+export function approve(lock, id, digest, at = new Date().toISOString()) {
+  validateLock(lock);
+  const entry = lock.packages[id];
+  if (!entry) throw oatsError("E_PACKAGE_MISSING", `cannot approve ${JSON.stringify(id)}: not in the lock — run \`oats sync\` first`, { id });
+  if (typeof digest !== "string" || !DIGEST_RE.test(digest)) throw oatsError("E_PACKAGE_INTEGRITY", `approval digest for ${id} must be sha256-<hex>`, { id, digest });
+  const ms = Date.parse(at);
+  if (Number.isNaN(ms)) throw oatsError("E_LOCK_SCHEMA", `approval timestamp for ${id} is not ISO-8601: ${JSON.stringify(at)}`, { id, at });
+  const next = clone(lock);
+  next.packages[id] = { ...next.packages[id], approved: { executables: digest, at: new Date(ms).toISOString() } };
+  return next;
 }
 
-/** Build the informed-consent install plan for one requirement on this host, or an explanation why none applies.
- * Never uses sudo, shell strings, or authentication. */
-export function requirementInstallPlan(req, { platform = process.platform, context } = {}) {
-  const r = normalizeRequirement(req);
-  if (!r) return undefined;
-  if (r.kind === "runtime-package") {
-    // Never build an executable plan for an invalid entry — the fail-closed
-    // policy must see it as unconsentable, not as an install recipe.
-    if (r._invalid) return { command: r.command, why: r.why, docs: r.install.docs, unavailable: r._invalid };
-    const mgr = RUNTIME_PACKAGE_MANAGERS[r.runtime];
-    // Some runtimes need more than one command (Claude registers a marketplace
-    // before installing). `steps` is the truth; `argv` stays the final command
-    // so existing consumers keep working.
-    // Same executable the session will launch with — see verifyRuntimePackages.
-    const opts = { context, ...(r.runtime === "claude" && context ? { bin: resolveClaudeBinary(context) } : {}) };
-    const steps = mgr.steps ? mgr.steps(r.package, req, opts) : [mgr.argv(r.package, req, opts)];
-    return {
-      command: r.command, why: r.why, docs: r.install.docs,
-      manager: r.runtime, steps, argv: steps[steps.length - 1], source: `${r.runtime} package (${r.package})`,
-      // Carried so POST-INSTALL verification probes the same executable and
-      // context the install ran through. Without it, an install performed via
-      // `claude-personal` is verified against the literal `claude` and reported
-      // failed (or falsely successful) purely by which account holds the plugin
-      // (reviewer-165d668).
-      probe: opts,
-      scope: mgr.scope, runtime: r.runtime, package: r.package, marketplace: r.marketplace,
-      version: r.runtime === "pi" ? (String(r.package).slice(packageSpecIdentity(r.package).length).match(/^@(.+)$/) || [])[1] : undefined,
-    };
-  }
-  const applicable = (r.install.methods || []).filter((m) => !m.platform || m.platform === platform);
-  for (const method of applicable) {
-    const manager = REQUIREMENT_MANAGERS[method.manager];
-    if (!manager) continue; // non-allowlisted methods are ignored, never executed
-    try {
-      const { argv, source } = manager.plan(method);
-      return {
-        command: r.command, why: r.why, docs: r.install.docs,
-        manager: method.manager, argv, source, scope: manager.scope,
-        version: (String(method.package || method.formula || "").match(/.@([^@]+)$/) || [])[1],
-      };
-    } catch (e) {
-      return { command: r.command, why: r.why, docs: r.install.docs, unavailable: e.message };
-    }
+/** Which locked package provides capability `capName`? → { id, entry } | null.
+ * Two packages providing the same name is ambiguous and fails closed:
+ * E_PACKAGE_MISSING { capability, ambiguous: [ids] } — never a silent first-by-id pick. */
+export function packageProviding(lock, capName) {
+  if (!plainObject(lock?.packages)) return null;
+  const providers = Object.keys(lock.packages).sort().filter((id) => Array.isArray(lock.packages[id]?.capabilities) && lock.packages[id].capabilities.includes(capName));
+  if (providers.length === 0) return null;
+  if (providers.length > 1) {
+    throw oatsError("E_PACKAGE_MISSING", `capability ${JSON.stringify(capName)} is provided by ${providers.length} locked packages (${providers.join(", ")}) — a soul cannot say which; keep one of them in packages:`, { capability: capName, ambiguous: providers });
   }
-  return { command: r.command, why: r.why, docs: r.install.docs, unavailable: applicable.length ? "no allowlisted install method for this host" : "no install method matches this platform" };
+  return { id: providers[0], entry: lock.packages[providers[0]] };
 }
 
-/** Gate: a requirement's command must be a safe executable basename/CLI token —
- * no path separators, whitespace, leading dash, or shell syntax. Fail closed. */
-export function safeRequirementCommand(cmd) {
-  return typeof cmd === "string" && /^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(cmd);
-}
+// ---------- deprecated shims (phase A only; callers are deleted next phase) ----------
 
-/** Aggregate missing host requirements across reconciled scopes, only for
- * capabilities activated somewhere in those scopes, deduplicated by command.
- * Returns [{ command, why, docs, plan, requestedBy: [{ capability, scope }],
- *            invalid?, conflict? }].
- * Fail-closed identity rules:
- * - a command that is not a safe executable token is flagged { invalid } with
- *   NO install plan — it can never be consented or executed;
- * - two active capabilities requesting the SAME command with NON-identical
- *   plans produce one deterministic conflict entry ({ conflict: { plans } },
- *   provenance-rich, no plan, no consent) — identical plans merge requestedBy. */
-export function aggregateMissingRequirements(scopes, { platform = process.platform, env = process.env, accepted = new Set() } = {}) {
-  const byCommand = new Map();
-  for (const scope of scopes) {
-    // Capabilities targeted by agent-type or soul are INVISIBLE to a
-    // soul-less scope resolution, so resolving the scope alone silently skipped
-    // their requirements entirely — for host commands as much as for runtime
-    // packages. Union the scope-level set with every soul's set, keeping one
-    // entry per capability id.
-    const active = new Map();
-    try { for (const cap of resolveOatsConfig(scope).capabilities || []) active.set(cap.id, cap); }
-    catch { continue; /* scope failures are reported by the reconciler */ }
-    let root;
-    try { root = findRoot(scope); } catch { root = undefined; }
-    for (const soul of root ? listAgents(root) : []) {
-      try { for (const cap of resolveOatsConfig(scope, soul.name).capabilities || []) if (!active.has(cap.id)) active.set(cap.id, cap); }
-      catch { /* unresolvable souls are reported by the reconciler */ }
-    }
-    for (const cap of active.values()) {
-      for (const raw of cap.manifest?.requires || []) {
-        const r = normalizeRequirement(raw);
-        if (!r) continue;
-        if (r.kind === "runtime-package") {
-          if (r._invalid) {
-            const key = `\u0000invalid:${r.command}`;
-            if (!byCommand.has(key)) byCommand.set(key, { kind: "runtime-package", command: r.command, why: r.why, docs: r.install.docs, plan: null, invalid: r._invalid, requestedBy: [] });
-            const bad = byCommand.get(key);
-            if (!bad.requestedBy.some((x) => x.capability === cap.id && x.scope === scope)) bad.requestedBy.push({ capability: cap.id, scope });
-            continue;
-          }
-          // RUNTIME SCOPING: raise this only for a deployment that actually runs
-          // the named runtime, or a Claude-only host with oats.aweb active gets
-          // prompted for a pi package — the provider-agnostic contract must not
-          // mutate a host for an adapter it never uses.
-          const targets = capabilityRuntimeTargets(scope, cap.id);
-          // EXPLICIT CONSENT OVERRIDES SCOPING. Spawn can be given `--runtime pi`
-          // for a soul whose default is claude, and it then emits
-          // `oats install --accept-requirement pi:<pkg>`. If scoping also filtered
-          // that named requirement out, the remedy we printed would install
-          // nothing and the retry would fail identically (reviewer-ad1b9f0).
-          // Naming a requirement IS the statement that this host needs it.
-          if (!targets.runtimes.has(r.runtime) && !accepted.has(r.command)) continue;
-          // Satisfied by the runtime's own package list, not by PATH.
-          const probeOpts = { context: scope, ...(r.runtime === "claude" ? { bin: resolveClaudeBinary(scope) } : {}) };
-          if (runtimePackageInstalled(r.runtime, r.package, env, probeOpts)) continue;
-          const plan = requirementInstallPlan(raw, { platform, context: scope });
-          if (!byCommand.has(r.command)) byCommand.set(r.command, { kind: "runtime-package", command: r.command, runtime: r.runtime, package: r.package, why: r.why, docs: r.install.docs, plan, requestedBy: [], _plans: [] });
-          const agg = byCommand.get(r.command);
-          agg._plans.push({ plan, capability: cap.id, scope });
-          if (!agg.requestedBy.some((x) => x.capability === cap.id && x.scope === scope)) {
-            // Provenance names the souls that pulled it in, so a mixed pi+claude
-            // deployment shows ONE deduped requirement explaining why it applies.
-            agg.requestedBy.push({ capability: cap.id, scope, souls: targets.requesters.filter((t) => t.runtime === r.runtime).map((t) => t.soul) });
-          }
-          continue;
-        }
-        if (r._nonStringCommand || !safeRequirementCommand(r.command)) {
-          const key = `\u0000invalid:${r.command}`;
-          if (!byCommand.has(key)) byCommand.set(key, { command: r.command, why: r.why, docs: r.install.docs, plan: null, invalid: "requirement command is not a safe executable name (no paths, whitespace, dashes-first, or shell syntax)", requestedBy: [] });
-          const bad = byCommand.get(key);
-          if (!bad.requestedBy.some((x) => x.capability === cap.id && x.scope === scope)) bad.requestedBy.push({ capability: cap.id, scope });
-          continue;
-        }
-        if (commandOnPath(r.command, env)) continue;
-        const plan = requirementInstallPlan(raw, { platform });
-        if (!byCommand.has(r.command)) {
-          byCommand.set(r.command, { command: r.command, why: r.why, docs: r.install.docs, plan, requestedBy: [], _plans: [{ plan, capability: cap.id, scope }] });
-        } else {
-          const agg = byCommand.get(r.command);
-          // Retain EVERY requester's plan so conflict provenance is complete for 3+
-          // requesters; the conflict itself derives from the collected set below.
-          agg._plans.push({ plan, capability: cap.id, scope });
-        }
-        const agg = byCommand.get(r.command);
-        if (!agg.requestedBy.some((x) => x.capability === cap.id && x.scope === scope)) agg.requestedBy.push({ capability: cap.id, scope });
-      }
-    }
-  }
-  // Derive conflicts AFTER collection so provenance covers every requester
-  // (3+ capabilities included). Plan identity = the executable argv (or
-  // unavailability); non-identical plans for one command are never
-  // installable or consentable.
-  // steps is authoritative: two capabilities can require the same plugin while
-  // registering its marketplace from DIFFERENT sources, which collapses to one
-  // requirement if only the final argv is compared (reviewer-6f1bb9c).
-  const planKey = (p) => JSON.stringify(p?.steps || (p?.argv ? [p.argv] : null) || p?.unavailable || null);
-  for (const agg of byCommand.values()) {
-    if (!agg._plans) continue;
-    const keys = new Set(agg._plans.map((x) => planKey(x.plan)));
-    if (keys.size > 1) {
-      agg.conflict = { plans: agg._plans.map((x) => ({ capability: x.capability, scope: x.scope, argv: x.plan?.argv || null, steps: x.plan?.steps || null, unavailable: x.plan?.unavailable || null })) };
-      agg.plan = null;
-    }
-  }
-  // Canonical string sort key: commands may be JSON.stringify'd non-strings.
-  return [...byCommand.values()].map(({ _plans, ...rest }) => rest).sort((a, b) => String(a.command).localeCompare(String(b.command)));
-}
+const removed = (name) => function removedByWorkspaceModel() {
+  throw oatsError("E_REMOVED", `${name} was removed by the workspace model; see ${CONTRACT_DOC}`, { name, contract: CONTRACT_DOC });
+};
 
-/** Execute one consented install plan (argv, no shell) and verify the command lands on PATH. */
-export function runRequirementInstall(plan, { env = process.env, stdio = "inherit" } = {}) {
-  if (!plan || !plan.argv) throw new Error(`no executable install plan for "${plan?.command}"`);
-  for (const step of plan.steps?.length ? plan.steps : [plan.argv]) {
-    if (step?.length) execFileSync(step[0], step.slice(1), { stdio, env });
-  }
-  // Verify what the requirement actually promised. A runtime package never
-  // lands on PATH, so verifying it there would report every successful install
-  // as a failure.
-  const onPath = plan.runtime
-    ? runtimePackageInstalled(plan.runtime, plan.package, env, plan.probe || {})
-    : commandOnPath(plan.command, env);
-  return { command: plan.command, installed: true, onPath };
-}
+export const aggregateMissingRequirements = removed("aggregateMissingRequirements");
+export const applyConfigMerge = removed("applyConfigMerge");
+export const applyFromOasScope = removed("applyFromOasScope");
+export const beginRunJournal = removed("beginRunJournal");
+export const capabilityRuntimeTargets = removed("capabilityRuntimeTargets");
+export const commandOnPath = removed("commandOnPath");
+export const discoverMigrationScopes = removed("discoverMigrationScopes");
+export const discoverOasScopes = removed("discoverOasScopes");
+export const discoverWorkspaceScopes = removed("discoverWorkspaceScopes");
+export const lockedPackageCapabilities = removed("lockedPackageCapabilities");
+export const normalizeRequirement = removed("normalizeRequirement");
+export const oasRenameMap = removed("oasRenameMap");
+export const packageSpecIdentity = removed("packageSpecIdentity");
+export const planConfigMerge = removed("planConfigMerge");
+export const planFromOasScope = removed("planFromOasScope");
+export const readAdoptedTemplate = removed("readAdoptedTemplate");
+export const requirementInstallPlan = removed("requirementInstallPlan");
+export const runRequirementInstall = removed("runRequirementInstall");
+export const runtimePackageInstalled = removed("runtimePackageInstalled");
+export const runtimePackageStatus = removed("runtimePackageStatus");
+export const selectConfigTemplate = removed("selectConfigTemplate");
+export const splitConfigLines = removed("splitConfigLines");
+export const transformOasConfigText = removed("transformOasConfigText");
+export const validateConfigTemplate = removed("validateConfigTemplate");
+export const writeAdoptedTemplate = removed("writeAdoptedTemplate");
+export const adoptedTemplateDir = removed("adoptedTemplateDir");
+/** Was a constant table; any property access throws E_REMOVED. */
+export const REQUIREMENT_MANAGERS = new Proxy(Object.freeze({}), {
+  get(_t, prop) { if (typeof prop === "symbol" || prop === "then") return undefined; removed("REQUIREMENT_MANAGERS")(); },
+  has() { removed("REQUIREMENT_MANAGERS")(); },
+});