@awebai/oats 0.23.1 → 0.24.0

package/lib/core.mjs

@@ -35,11 +35,65 @@ import { accessSync, constants as fsConstants } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
+import { initializeNativeHistory, prepareNativeStart, nativeHistoryPath } from "../packages/record/lib/native-history.mjs";
+import { PI_SDK_HOST, isPiSdkHost, validatePiHostRecipe, piHostArgv, resolvePiSdkEntry } from "./pi-sdk-host.mjs";
+import { capturedPiSessionDirectory, requireCapturedPiRecordSupport, inspectCapturedPiRoot, prepareCapturedPiStart } from "./captured-pi-custody.mjs";
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
 import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
+import { oatsError } from "./errors.mjs";
+const CAPTURED_NATIVE_START = Symbol("captured-native-start");
+import { renderInstructionText } from "./instruction-composition.mjs";
+import { loadCapturedAction } from "./captured-dispatch.mjs";
+import { materializeCapturedDirectoryScaffold, validateCapturedDirectoryTarget } from "./captured-scaffold.mjs";
+import { buildCapturedInvocationContext, withCapturedInvocationContextFile } from "./captured-invocation-context.mjs";
+import { readCapturedInstanceIndex, readCapturedInstanceMetadata, readCapturedInstanceAuthority, assertCapturedInstanceCustody,
+  recordCapturedCustodyFailure, markCapturedNativeScaffold, failCapturedNativeIntent, observeCapturedNativeTarget, setCapturedInstanceStatus, admitCapturedInstanceAction, beginCapturedIntent, settleCapturedIntent } from "./captured-instance-index.mjs";
+import { validateExecutionBinding } from "./schedule-capsule.mjs";
+import { validateIntentRef } from "./captured-admission-shape.mjs";
+export { readCapturedInstanceIndex, readCapturedInstanceMetadata, beginCapturedIntent, settleCapturedIntent };
+export { buildCapturedInvocationContext, withCapturedInvocationContextFile };
+import { approveAvailableCapability as approveAvailableArtifact } from "./artifact-approvals.mjs";
+import { prepareComposition } from "./prepare-composition.mjs";
+import { completePreparedResources } from "./prepared-resources.mjs";
+import { validateCapturedLaunchRequest } from "./captured-launch-request.mjs";
+import { validateCapabilityInputDeclarations } from "./capability-inputs.mjs";
+import { validateCapturedSessionBackend, validateCapturedSessionTarget, assertCapturedSessionPlacement } from "./captured-session-backend.mjs";
+import { createRepositoryTransaction } from "./repository-observation.mjs";
+import { readLock3 } from "./portable-lock.mjs";
+import { portableScope, portableStateDirectory } from "./portable-state.mjs";
+import { objectAt } from "./portable-shape.mjs";
+import { validateBindingInterface } from "./provider-binding.mjs";
+import { invokeProviderBinding } from "./provider-binding-broker.mjs";
+import { withCapturedBindingFile } from "./captured-binding-file.mjs";
+import { validateCapturedSourceReceipt, withCapturedSourceReceiptFile } from "./captured-source-receipt-file.mjs";
+export { withCapturedBindingFile, validateCapturedSourceReceipt, withCapturedSourceReceiptFile };
+import { executableSurfaceOf, hasExecutableSurface } from "./capability-execution.mjs";
+import { createCapabilityMaterializer } from "./package-materialization.mjs";
+import { resolvePackageClosure } from "./package-closure.mjs";
+import { canonicalJson, parseStrictJson, decodeUtf8 } from "./portable-values.mjs";
+import { treeIntegrity } from "./portable-digest.mjs";
+import { readPortableBytes } from "./portable-files.mjs";
+import { capabilityArtifactIntegrity, copyTreeSafe, removeOwnedStaging } from "./artifact-tree.mjs";
+import {
+  CAPABILITIES_DIRNAME, INSTALLED_SUBDIR,
+  isMaterializedCapabilityId, capabilityIdViolation, CAPABILITY_INSTALLATION_FILE,
+  normalizePackagePath, parseLockSource, PACKAGE_ID_RE,
+  validateLockEntry, validateCapabilityLockEntry, verifyCapabilityInstallation,
+} from "./capability-provenance.mjs";
+import { decodeLegacyLockBytes, legacyCapabilityEntryViolation } from "./legacy-lock-codec.mjs";
+// Keep the existing public core surface; internal data helpers are not re-exported.
+export { oatsError } from "./errors.mjs";
+export { legacyCapabilityEntryViolation } from "./legacy-lock-codec.mjs";
+export { capabilityArtifactIntegrity, copyTreeSafe } from "./artifact-tree.mjs";
+export {
+  CAPABILITIES_DIRNAME, INSTALLED_SUBDIR, CAPABILITY_ID_RE,
+  isMaterializedCapabilityId, capabilityIdViolation, CAPABILITY_INSTALLATION_FILE,
+  normalizePackagePath, validateLockEntry, validateCapabilityLockEntry,
+  verifyCapabilityInstallation,
+} from "./capability-provenance.mjs";
+
 export const RESERVED = new Set(["bin", "local-agents", "tmp-agents"]);
 /** The work modes spawn accepts — also the enum a quarantine cleanup descriptor
  * must satisfy, so the retry cannot skip Git cleanup on an unrecognised value. */
@@ -711,16 +765,20 @@ function bindingObject(value) {
 function hookDeclaration(value) {
   if (typeof value === "string") return { command: value, required: false };
   if (value && typeof value === "object" && typeof value.command === "string") {
-    return { command: value.command, required: value.required === true };
+    return { command: value.command, required: value.required === true, ...(Object.hasOwn(value, "inputs") ? { inputs: value.inputs } : {}) };
   }
   return undefined;
 }
+function manifestHookDeclarations(manifest) {
+  return Object.fromEntries(Object.entries(manifest?.hooks || {}).flatMap(([event, value]) => {
+    const declaration = hookDeclaration(value);
+    return APPROVED_HOOKS.has(event) && declaration ? [[event, declaration.command]] : [];
+  }));
+}
 function manifestHookCommands(manifest) {
   const out = {};
-  for (const [ev, value] of Object.entries(manifest?.hooks || {})) {
-    const decl = hookDeclaration(value);
-    if (!APPROVED_HOOKS.has(ev) || !decl) continue;
-    const [script, ...args] = decl.command.split(/\s+/);
+  for (const [ev, command] of Object.entries(manifestHookDeclarations(manifest))) {
+    const [script, ...args] = command.split(/\s+/);
     const abs = manifestPath(manifest, script);
     if (abs) out[ev] = ["node", shq(abs), ...args].join(" ");
   }
@@ -849,11 +907,7 @@ export function resolveCapabilities(contextDir, soulName) {
     if (![...enabledValues][0]) continue;
     // A declared value set is enforced for an ACTIVE capability: a misspelling
     // must not switch a conditional requirement off by matching nothing.
-    for (const [key, decl] of Object.entries(declaredSettings)) {
-      if (decl && typeof decl === "object" && Array.isArray(decl.values) && settings[key] !== undefined && !decl.values.some((v) => String(v) === String(settings[key]))) {
-        throw new Error(`capability setting ${id}.${key} is ${JSON.stringify(settings[key])}, not one of ${decl.values.map((v) => JSON.stringify(v)).join(", ")}`);
-      }
-    }
+    assertCapabilitySettingValues(manifest, settings);
     const compatibility = capabilityCompatibility(manifest);
     if (!compatibility.compatible) throw new Error(`capability "${id}" requires OATS ${compatibility.range}; running ${compatibility.version}`);
     const trust = capabilityTrust(manifest, contextDir);
@@ -988,33 +1042,10 @@ const OATS_HOME_DIR = process.env.OATS_HOME_DIR || join(homedir(), ".oats");
 /** Legacy pre-v0.8 laptop acquisition root — kept only so doctor can warn about it. */
 export const LEGACY_HOME_CAPABILITIES_DIR = join(OATS_HOME_DIR, "capabilities");
 export const OATS_LOCK_FILE = "oats-lock.json";
-/** Scope-relative capability store subtrees. */
-export const CAPABILITIES_DIRNAME = join(".agents", "capabilities");
-export const INSTALLED_SUBDIR = "installed";
 export const OWNED_SUBDIR = "owned";
 export const installedCapabilitiesDir = (level) => join(level, CAPABILITIES_DIRNAME, INSTALLED_SUBDIR);
 export const ownedCapabilitiesDir = (level) => join(level, CAPABILITIES_DIRNAME, OWNED_SUBDIR);
 
-/** THE identity grammar for a MATERIALIZED (revised-v2) capability.
- *
- * A materialized capability id is not merely a label: it becomes a DIRECTORY
- * NAME directly under `installed/`, so anything that can steer a filesystem
- * join must be impossible before the join happens. The grammar is deliberately
- * the package-id grammar — namespaced dots are fine, and `/`, `\`, `..`,
- * absolute forms, `@`, and percent-encoded spellings are all outside it.
- *
- * The LEGACY v1 / owned / `from: path:` grammar (loadManifestAt) stays looser
- * on purpose: those artifacts are named by `basename()` of their source, never
- * by the declared id, so the id never reaches a path there. Tightening it would
- * strand already-published standalone capabilities. */
-export const CAPABILITY_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
-export const isMaterializedCapabilityId = (id) => typeof id === "string" && CAPABILITY_ID_RE.test(id);
-/** Why a capability id was refused, in one sentence, for every caller's own
- * typed error (the lock parser raises invalid-lock, manifest validation raises
- * invalid-package-manifest — the code each consumer already branches on). */
-export const capabilityIdViolation = (id) =>
-  `${JSON.stringify(id)} is not a valid capability identity — expected ${CAPABILITY_ID_RE.source} (a namespaced id such as "oats.okf"; path separators, "..", absolute paths, "@" and encoded forms are refused because the id names a directory under ${INSTALLED_SUBDIR}/)`;
-
 const PORTABLE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 const CAPABILITY_ENV_ID_RE = /^[a-z][a-z0-9]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 const CORE_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]);
@@ -1108,17 +1139,18 @@ export function stripInternalAnnotations(parsed) {
   return out;
 }
 
-function loadManifestAt(idir, origin) {
+function loadManifestAt(idir, origin, { strict = false } = {}) {
   const mf = join(idir, "oats.json");
   if (!existsSync(mf)) return undefined;
   let raw;
-  try { raw = JSON.parse(readFileSync(mf, "utf8")); }
-  catch (e) { throw new Error(`invalid capability manifest JSON ${mf}: ${e.message}`); }
+  try { raw = strict ? parseStrictJson(readPortableBytes(mf)) : JSON.parse(readFileSync(mf, "utf8")); }
+  catch (e) { if (strict) throw e; throw new Error(`invalid capability manifest JSON ${mf}: ${e.message}`); }
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`capability manifest ${mf} must be a JSON object (got ${raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw})`);
   // BEFORE any validation or annotation: the artifact declares capability DATA,
   // never kernel annotations about itself.
   const m = stripInternalAnnotations(raw);
   const id = validateCapabilityManifest(m, mf);
+  validateCapabilityInputDeclarations(m);
   if (!m.version || !m.description) throw new Error(`capability ${id} manifest needs version and description`);
   const targetFields = ["global", "groups", "souls", "targets"].filter((key) => Object.prototype.hasOwnProperty.call(m, key));
   if (targetFields.length) throw new Error(`capability ${id} manifest cannot declare config-owned targets: ${targetFields.join(", ")}`);
@@ -1126,6 +1158,7 @@ function loadManifestAt(idir, origin) {
   if (m.command && !/^[a-z0-9][a-z0-9-]*$/.test(m.command)) throw new Error(`capability ${id} has invalid command namespace "${m.command}"`);
   for (const [hook, value] of Object.entries(m.hooks || {})) {
     if (!APPROVED_HOOKS.has(hook)) throw new Error(`capability ${id} declares unsupported hook "${hook}"`);
+    if (value && typeof value === "object") objectAt(value, ["command", "required", "inputs"], ["command"]);
     if (!hookDeclaration(value)) throw new Error(`capability ${id} hook "${hook}" must be a command string or { command, required }`);
     if (value && typeof value === "object" && value.required !== undefined && typeof value.required !== "boolean") {
       throw new Error(`capability ${id} hook "${hook}": "required" must be a boolean`);
@@ -1136,9 +1169,322 @@ function loadManifestAt(idir, origin) {
   }
   if (m.agents !== undefined && (!Array.isArray(m.agents) || m.agents.some((a) => typeof a !== "string"))) throw new Error(`capability ${id} "agents" must be an array of package-relative soul directories`);
   validateManifestOperations(m, id);
+  validateBindingInterface(m);
   return { ...m, _dir: idir, _origin: origin };
 }
 
+function assertCapabilitySettingValues(manifest, settings) {
+  for (const [key, decl] of Object.entries(manifest.settings || {})) {
+    if (decl && typeof decl === "object" && Array.isArray(decl.values) && Object.hasOwn(settings, key) && settings[key] !== undefined && !decl.values.some((v) => String(v) === String(settings[key]))) {
+      throw new Error(`capability setting ${manifest.capability}.${key} is ${JSON.stringify(settings[key])}, not one of ${decl.values.map((v) => JSON.stringify(v)).join(", ")}`);
+    }
+  }
+}
+
+function loadRetainedManifest(root) {
+  const manifest = loadManifestAt(root, "captured", { strict: true });
+  if (!manifest) throw oatsError("resolution-incomplete", "retained capability manifest is absent");
+  assertCapabilitySelfContained(root, manifest);
+  const compatible = capabilityCompatibility(manifest);
+  if (!compatible.compatible) throw oatsError("capability-incompatible", `captured capability requires OATS ${compatible.range}`);
+  return manifest;
+}
+
+export function approveAvailableCapability(deployment, artifactSet, capability, origin) {
+  return approveAvailableArtifact(deployment, artifactSet, capability, origin, loadRetainedManifest);
+}
+
+/** Explicit new-work preparation, with one frozen repository transaction.
+ * This first adapter captures command/curriculum profiles; provider-owned
+ * binding or distinct helper policy gaps return needs-configuration, never
+ * a fabricated complete record. No lifecycle side effects run here. */
+export function prepareCapturedComposition(input, { repositoryOptions = {} } = {}) {
+  canonicalJson(input);
+  objectAt(input, ["deployment", "source", "origin", "workspace", "member", "operator", "mode", "allowLocalPaths", "standaloneContextKey", "launch", "helperLaunches"], ["deployment", "source"]);
+  if (input.launch !== undefined) validateCapturedLaunchRequest(input.launch, validateLaunchConfig);
+  if (input.helperLaunches !== undefined) {
+    objectAt(input.helperLaunches, null, []);
+    for (const request of Object.values(input.helperLaunches)) validateCapturedLaunchRequest(request, validateLaunchConfig);
+  }
+  if (input.mode !== undefined && !WORK_MODES.includes(input.mode)) throw oatsError("invalid-declaration", "invalid preparation work mode");
+  const deployment = portableScope(input.deployment);
+  const previous = readLock3(deployment); // Old state refuses before scratch/fetch.
+  const directory = mkdtempSync(join(portableStateDirectory(deployment, true), ".prepare-")), owned = lstatSync(directory);
+  const origin = input.origin ?? { kind: "operator", document: { kind: "operator", id: "oats-prepare" }, pointer: "/source" };
+  let repositories, primary, catalog;
+  try {
+    repositories = createRepositoryTransaction({ ...repositoryOptions, directory, accessContextKey: repositoryOptions.accessContextKey ?? "native" });
+    return prepareComposition({ ...input, deployment, origin, directory }, { repositories, previous, kernel: {
+      loadPackageManifestAt, capabilityCompatibility, assertPlatformInvariantLocks, materializeCapability,
+      manifest: loadRetainedManifest,
+      binding: runCapturedProviderBinding,
+      catalog(id, selector) {
+        catalog ??= officialPackageCatalog();
+        if (!Object.hasOwn(catalog, id)) throw oatsError("invalid-source", "unknown package dependency catalog identity");
+        return { ...catalog[id], ...(selector === undefined ? {} : { ref: selector }) };
+      },
+      complete: data => completePreparedResources(data, { root: PKG_ROOT, workModes: WORK_MODES,
+        settings: assertCapabilitySettingValues, skills: skillEntriesIn, hooks: manifestHookDeclarations,
+        validateLaunchConfig, runtimeRequirements: applicableRequirements }),
+    } });
+  } catch (error) { primary = error; throw error; }
+  finally {
+    try {
+      repositories?.close();
+      const current = lstatSync(directory);
+      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("source-incomplete", "preparation scratch ownership changed");
+      removeOwnedStaging(directory);
+    } catch (cleanup) {
+      if (!primary) throw cleanup;
+      const error = new AggregateError([primary, cleanup], "preparation and owned scratch cleanup failed", { cause: primary });
+      error.code = primary.code; error.stagingPath = directory; throw error;
+    }
+  }
+}
+
+/** Load an exact record for one action, using the existing COMPLETE kernel
+ * manifest codecs. No scoped config, mutable install or marketplace fallback.
+ * Launch/lifecycle adoption and provider qualification are separate integration
+ * steps; unsupported actions refuse rather than switching to legacy dispatch. */
+function capturedCapabilityCodecs() {
+  return {
+    manifest: loadRetainedManifest,
+    settings: assertCapabilitySettingValues,
+    host: ({ manifest }) => (manifest.requires || []).filter((requirement) => requirement.command && !which(requirement.command)),
+    executable(manifest, relativePath) {
+      const file = capabilityExecutablePath(manifest, relativePath);
+      if (!file || !statSync(file).isFile()) throw oatsError("resource-not-found", "captured executable is not a regular file");
+      return realpathSync(file);
+    },
+  };
+}
+
+/** Exact prospective/captured binding phases; no partial record or ambient provider. */
+export function runCapturedProviderBinding(options) {
+  return invokeProviderBinding(options, capturedCapabilityCodecs());
+}
+
+function capturedDispatchCodecs(options, { admitting = false } = {}) {
+  return {
+    ...capturedCapabilityCodecs(),
+    launch(recipe) {
+      assertLaunchRecipe(recipe, "captured resolution");
+      validateLaunchConfig("captured", { runtime: recipe.runtime, executable: recipe.executable, args: recipe.args, env: recipe.env,
+        ...(recipe.model != null ? { model: recipe.model } : {}), ...(recipe.yolo !== undefined ? { yolo: recipe.yolo } : {}) }, "captured resolution");
+    },
+    operations: manifestOperations,
+    hooks: manifestHookDeclarations,
+    invocation(base, action, capability) {
+      return buildCapturedInvocationContext({ loaded: { ...base, capability }, action,
+        instance: options.invocationTarget ?? null, intent: options.intent ?? null,
+        ...(Object.hasOwn(options, "priorReceipt") ? { priorReceipt: options.priorReceipt } : {}) });
+    },
+    bindings(bindings, capability, record, invocation) {
+      // Admission is static authorization to ATTEMPT, not readiness or effects.
+      // The normal loader still checks readiness with the saved intent before execution.
+      if (admitting) return;
+      for (const [slot, binding] of bindings) {
+        if (capability.manifest.layer !== slot) throw oatsError("invalid-resolution", "captured binding slot differs from the manifest owner");
+        const result = runCapturedProviderBinding({ deployment: options.deployment, artifacts: record.artifacts,
+          capability: capability.id, phase: "check", settings: capability.settings,
+          input: { binding, context: record.context, action: options.action, ...(invocation ? { invocation } : {}) } });
+        if (result.status !== "ready") throw oatsError(result.problems[0]?.code ?? "provider-not-qualified", "captured provider is not ready for this action");
+      }
+    },
+  };
+}
+
+export function loadCapturedDispatch(options) {
+  return loadCapturedAction(options, capturedDispatchCodecs(options));
+}
+
+/** Admit against exact retained action/approval and current owned incarnation.
+ * No provider phase runs here; readiness/execution consume the persisted intent. */
+export function admitCapturedAction({ deployment, resolution, home, action, input = {}, retryExecutionId, ...rest }) {
+  canonicalJson(rest); objectAt(rest, ["priorReceipt"], []);
+  const metadata = readCapturedInstanceMetadata(home);
+  const options = { deployment, resolution, action,
+    invocationTarget: { home, work: join(home, "work"), name: metadata.instance, agent: metadata.agent },
+    ...(Object.hasOwn(rest, "priorReceipt") ? { priorReceipt: rest.priorReceipt } : {}) };
+  const loaded = loadCapturedAction(options, capturedDispatchCodecs(options, { admitting: true }));
+  if (!loaded.capability) throw oatsError("unsupported-action", "inspection/composition does not admit mutation");
+  return admitCapturedInstanceAction({ deployment, home, executionBinding: loaded.invocation.executionBinding,
+    capability: loaded.capability.id, action, input, ...(retryExecutionId !== undefined ? { retryExecutionId } : {}) });
+}
+
+/** Static callable API availability, not instance/provider/host readiness.
+ * This descriptor never probes a backend or admits a native request. */
+export function capturedNativeSessionAvailability() {
+  return { schemaVersion: 1, api: { contract: "oats.captured-session", version: 2, available: true, backends: ["tmux", "herdr"] }, readiness: { status: "not-checked" } };
+}
+
+/** Resolve only a source record's explicit helper edge. This is static retained
+ * authority inspection, never helper-name discovery, preparation or launch. */
+export function resolveCapturedHelper(input) {
+  canonicalJson(input);
+  objectAt(input, ["executionBinding", "helper", "name"], ["executionBinding", "helper"]);
+  validateExecutionBinding(input.executionBinding);
+  if (typeof input.helper !== "string" || !input.helper || input.helper.includes("\0")) throw oatsError("invalid-declaration", "helper must be an exact captured helper-map key");
+  if (Object.hasOwn(input, "name") && (typeof input.name !== "string" || !input.name)) throw oatsError("invalid-declaration", "expected helper name must be non-empty text");
+  const deployment = portableScope(input.executionBinding.deployment);
+  const source = loadCapturedDispatch({ deployment, resolution: input.executionBinding.resolution, action: { kind: "inspect" } });
+  if (!Object.hasOwn(source.record.helpers, input.helper)) throw oatsError("helper-not-selected", "source resolution does not select that helper key");
+  const resolution = source.record.helpers[input.helper];
+  const helper = loadCapturedDispatch({ deployment, resolution, action: { kind: "inspect" } });
+  if (helper.record.subject.kind !== "helper") throw oatsError("invalid-resolution", "captured helper edge does not name a dedicated helper");
+  if (input.name !== undefined && input.name !== helper.record.subject.name) throw oatsError("invalid-resolution", "captured helper name differs from requested name");
+  const responsibleHuman = helper.record.messagingChoice.enabled ? helper.record.messagingChoice.privateKey.human : null;
+  const sourceHuman = source.record.messagingChoice.enabled ? source.record.messagingChoice.privateKey.human : null;
+  if (canonicalJson(source.record.context) !== canonicalJson(helper.record.context) || canonicalJson(sourceHuman) !== canonicalJson(responsibleHuman)) {
+    throw oatsError("needs-configuration", "distinct helper context/human requires an explicit captured helper-request policy; no implicit inheritance was used");
+  }
+  if (!helper.record.dispatch.composition) throw oatsError("resolution-incomplete", "selected helper has no captured curriculum");
+  return {
+    schemaVersion: 1,
+    sourceExecutionBinding: { schemaVersion: 1, deployment, resolution: source.resolution },
+    executionBinding: { schemaVersion: 1, deployment, resolution },
+    helper: { key: input.helper, name: helper.record.subject.name, subject: helper.record.subject },
+    context: helper.record.context, responsibleHuman, workMode: helper.record.dispatch.composition.mode,
+    launchSelection: helper.record.dispatch.launch === null ? null : {
+      runtime: helper.record.dispatch.launch.runtime, model: helper.record.dispatch.launch.model,
+    },
+    launch: capturedNativeSessionAvailability(),
+  };
+}
+
+/** Bounded scaffold-only adoption of one exact captured composition. Placement
+ * is explicit and launch/hooks remain pending; unsupported work modes refuse. */
+export function scaffoldCapturedInstance({ deployment, resolution, home, instance }) {
+  const loaded = loadCapturedDispatch({ deployment, resolution, action: { kind: "compose" } });
+  const blocked = loaded.approvals.filter((entry) => !["approved", "not-required"].includes(entry.status));
+  if (blocked.length) throw oatsError("approval-required", "captured scaffold needs approval for every selected executable artifact", blocked);
+  validateCapturedDirectoryTarget(home, instance);
+  if (loaded.record.dispatch.composition?.mode !== "directory") throw oatsError("needs-configuration", "captured scaffold currently requires retained directory work mode");
+  if (existsSync(home)) throw oatsError("E_INSTANCE_EXISTS", `instance home already exists: ${home}`);
+  // Native evidence is initialized only for this newly created incarnation.
+  // Existing sidecars are retained obligations, never silent history backfill.
+  const history = nativeHistoryPath(home), baseline = retirementBaselinePath(home);
+  const parents = [dirname(history), dirname(dirname(baseline)), dirname(baseline)];
+  const parentGuard = (create = false) => {
+    for (const path of parents) {
+      if (create && !existsSync(path)) mkdirSync(path, { mode: 0o700 });
+      if (existsSync(path) && !lstatSync(path).isDirectory()) throw oatsError("integrity-drift", "native custody parent is not an owned directory");
+    }
+  };
+  parentGuard();
+  if (existsSync(history) || existsSync(baseline)) throw oatsError("migration-required", "native custody already exists at this home address; preserve it and select a fresh home");
+  const result = materializeCapturedDirectoryScaffold({ home, instance, loaded });
+  try {
+    const original = readCapturedInstanceAuthority(deployment, home).row;
+    const assertRoots = () => { assertCapturedInstanceCustody(original); parentGuard(); };
+    assertRoots(); parentGuard(true); initializeNativeHistory(home);
+    writeRetirementBaseline(home, join(home, "work"), "directory", {}, [], { launched: false },
+      { exclusive: true, incarnationId: original.incarnationId, executionBinding: original.executionBinding });
+    assertRoots();
+    const metadata = readCapturedInstanceMetadata(home);
+    const proof = { schemaVersion: 1, directories: { historyRoot: directoryIdentity(dirname(history)), history: directoryIdentity(history),
+      retirementRoot: directoryIdentity(dirname(dirname(baseline))), baselines: directoryIdentity(dirname(baseline)) } };
+    atomicWriteFileSync(join(home, "instance.json"), canonicalJson({ ...metadata, captured: { ...metadata.captured, nativeScaffold: proof } }), { assertRoots });
+    markCapturedNativeScaffold(deployment, home, proof);
+    return result;
+  } catch (error) { error.home = home; error.cleanupRequired = true; throw error; }
+}
+
+/** Run retained spawn hooks for an exact scaffold. Required-hook failure retains
+ * the home and its receipts for explicit compensation; launch stays pending. */
+export function activateCapturedScaffold(options) {
+  let { deployment, resolution, home, extraEnv = {} } = options;
+  home = resolve(home);
+  const file = join(home, "instance.json");
+  let metadata = readCapturedInstanceMetadata(home);
+  const original = readCapturedInstanceAuthority(deployment, home).row;
+  const retry = Object.hasOwn(options, "retryIntents"), retryIntents = retry ? options.retryIntents : {};
+  canonicalJson(retryIntents); objectAt(retryIntents, null, []);
+  const savedIntents = {};
+  for (const intent of original.intents.filter(entry => entry.action.kind === "hook" && entry.action.name === "spawn")) {
+    if (Object.hasOwn(savedIntents, intent.capability)) throw oatsError("invalid-resolution", "multiple spawn requests need explicit reconciliation, not inferred retry selection");
+    savedIntents[intent.capability] = { schemaVersion: 1, executionId: intent.executionId, incarnationId: original.incarnationId, attempt: intent.attempt };
+  }
+  for (const [id, intent] of Object.entries(metadata.captured.hookIntents || {})) {
+    if (savedIntents[id]?.executionId !== intent.executionId || intent.incarnationId !== original.incarnationId) throw oatsError("invalid-resolution", "saved spawn reference differs from indexed authority");
+  }
+  if (retry) {
+    const expected = Object.fromEntries(Object.entries(savedIntents).map(([id, intent]) => [id, intent.executionId]));
+    if (canonicalJson(expected) !== canonicalJson(retryIntents)) throw oatsError("invalid-resolution", "spawn retry must name every indexed hook intent exactly; no partial implicit new requests");
+  } else if (Object.keys(savedIntents).length) throw oatsError("invalid-resolution", "existing spawn obligations require an explicit retry");
+  const priorStatus = retry ? metadata.captured.lifecycle : "scaffolded-hooks-pending";
+  if (retry && !["spawn-failed-cleanup-required", "spawned-cleanup-required"].includes(priorStatus)) throw oatsError("invalid-resolution", "captured scaffold is not awaiting activation retry");
+  const inspected = loadCapturedDispatch({ deployment, resolution, action: { kind: "inspect" } });
+  const composed = loadCapturedDispatch({ deployment, resolution, action: { kind: "compose" } });
+  const subject = inspected.record.subject, expectedAgent = subject.kind === "persistent" ? subject.soul.alias : subject.name;
+  const expectedHuman = inspected.record.messagingChoice.enabled ? inspected.record.messagingChoice.privateKey.human : null;
+  let sameDeployment = false;
+  try { sameDeployment = portableScope(metadata.executionBinding?.deployment) === portableScope(deployment); } catch { /* refused below */ }
+  if (metadata.home !== home || metadata.instance !== basename(home) || metadata.agent !== expectedAgent
+    || metadata.captured?.lifecycle !== priorStatus || metadata.executionBinding?.resolution?.id !== resolution.id
+    || !sameDeployment || canonicalJson(metadata.responsibleHuman) !== canonicalJson(expectedHuman)) {
+    throw oatsError("invalid-resolution", "captured scaffold metadata differs from the requested resolution or home");
+  }
+  const assertRoots = () => {
+    const row = assertCapturedInstanceCustody(original);
+    if (row.status !== "spawn-hooks-running") throw oatsError("selection-changed", "activation no longer owns the indexed lifecycle state");
+    return row;
+  };
+  const reportFailure = (error, observed = {}) => {
+    const facts = { meta: observed.meta || {}, intents: observed.intents || {} };
+    let report, reportingFailure;
+    try { report = recordCapturedCustodyFailure(original, { ...facts, code: error.code || "E_CAPTURED_PUBLICATION", message: error.message }); }
+    catch (failure) { reportingFailure = { code: failure.code || "E_CAPTURED_CUSTODY", message: String(failure.message).slice(0, 200) }; }
+    // Independent ledger first; if that too is held, propagate the observed
+    // receipt through the existing caller error channel, not the foreign home.
+    error.home = home;
+    error.capturedCustody = { incarnationId: original.incarnationId, executionBinding: original.executionBinding,
+      ...facts, ...(report ? { report } : {}), ...(reportingFailure ? { reportingFailure } : {}) };
+    throw error;
+  };
+  const publish = (next, status, observed = {}) => {
+    try {
+      atomicWriteFileSync(file, canonicalJson(next), { assertRoots });
+      assertRoots();
+      setCapturedInstanceStatus(deployment, home, status, { expectedStatus: "spawn-hooks-running" });
+    } catch (error) { reportFailure(error, observed); }
+  };
+  setCapturedInstanceStatus(deployment, home, "spawn-hooks-running", { expectedStatus: priorStatus });
+  let hooks;
+  try {
+    hooks = runCapturedLifecycleHooks("spawn", { deployment, resolution, home, instance: metadata.instance, agentName: expectedAgent, retryIntents, assertRoots,
+      extraEnv: { ...extraEnv, OATS_WORK: "directory", OATS_KIND: subject.kind } });
+  } catch (error) {
+    const failure = { capability: "oats.kernel", event: "spawn", message: String(error.message || error).slice(0, 200), required: true, unconfirmed: true };
+    metadata = { ...metadata, capabilityMeta: { ...metadata.capabilityMeta, ...error.capturedHooks?.meta }, captured: { ...metadata.captured,
+      lifecycle: "spawn-failed-cleanup-required", hookOrder: error.capturedHooks?.order || [], hookFailures: [failure],
+      hookIntents: { ...savedIntents, ...error.capturedHooks?.intents } } };
+    publish(metadata, "spawn-failed-cleanup-required", error.capturedHooks);
+    error.home = home; throw error;
+  }
+  const required = hooks.failures.filter((failure) => failure.required);
+  let unsettled;
+  try {
+    const row = readCapturedInstanceIndex(deployment).instances.find(row => row.incarnationId === original.incarnationId);
+    if (!row) throw oatsError("selection-changed", "captured activation is no longer indexed");
+    unsettled = row.intents.some(intent => intent.state !== "completed");
+  } catch (error) { reportFailure(error, hooks); }
+  // Optional functionality can fail without a required-hook error, but custody
+  // remains explicitly nonterminal and the saved-map retry route stays usable.
+  const status = required.length ? "spawn-failed-cleanup-required" : unsettled ? "spawned-cleanup-required" : "spawned-launch-pending";
+  hooks.intents = { ...savedIntents, ...hooks.intents };
+  metadata = { ...metadata, capabilityMeta: { ...metadata.capabilityMeta, ...hooks.meta }, captured: { ...metadata.captured,
+    lifecycle: status, hookOrder: hooks.order, hookFailures: hooks.failures, hookIntents: hooks.intents } };
+  publish(metadata, status, hooks);
+  if (required.length) {
+    const error = oatsError("E_REQUIRED_HOOK_FAILED", "captured spawn hook failed; home and receipts are retained for explicit cleanup", required);
+    error.home = home; throw error;
+  }
+  return { home, instance: metadata.instance, agent: expectedAgent, incarnationId: metadata.incarnationId, executionBinding: metadata.executionBinding,
+    responsibleHuman: expectedHuman, launched: false, hooks, launchPending: true, functionalReady: true,
+    hooksPending: unsettled, cleanupRequired: unsettled };
+}
+
 /** `operations`: what a capability offers a GUI or scheduler by name, each
  *  delegating to one of its own `commands`. kind "action" runs something;
  *  kind "view" answers { documents: [...] } for presentation (a knowledge
@@ -1251,40 +1597,6 @@ export function capabilityManifest(name, startDir) {
   return capabilityManifests(startDir)[name];
 }
 
-/** Recursively copy a tree the way `cpSync(..., { recursive: true })` would —
- * except catchably.
- *
- * Node 22's recursive `cpSync` performs its recursion in native code, and on
- * macOS an unreadable directory inside the tree surfaces as an uncaught libc++
- * `filesystem_error` that TERMINATES THE PROCESS. No JS `catch` or `finally`
- * runs, so a transaction using it can never clean up staging or roll back the
- * store, the lock and the ignore file. Every package-, capability- and
- * user-shaped tree in the engine therefore goes through this hand-walk instead,
- * where an EACCES is an ordinary throwable error.
- *
- * Semantics chosen to be safe rather than maximally faithful:
- * - deterministic traversal (sorted entries), so two copies of one tree hash
- *   identically;
- * - symlinks are recreated VERBATIM — never followed, never rewritten — because
- *   the bytes about to be hashed must be the bytes the author wrote;
- * - FIFOs, sockets and device nodes are rejected fail-closed: they are not
- *   distributable content, and copying them has no defined meaning here;
- * - directory modes are applied AFTER their children, so a read-only source
- *   directory cannot block writing its own contents. */
-export function copyTreeSafe(src, dest) {
-  const st = lstatSync(src);
-  if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src), dest); return; }
-  if (st.isFile()) { copyFileSync(src, dest); chmodSync(dest, st.mode & 0o7777); return; }
-  if (!st.isDirectory()) {
-    throw oatsError("invalid-source", `${src} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);
-  }
-  mkdirSync(dest, { recursive: true });
-  for (const e of readdirSync(src, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-    copyTreeSafe(join(src, e.name), join(dest, e.name));
-  }
-  chmodSync(dest, st.mode & 0o7777);
-}
-
 /** Remove source-control metadata from the ROOT of a managed artifact.
  *
  * It must not be installed, and it must not become an integrity exclusion:
@@ -1588,14 +1900,6 @@ export function capabilityCompatibility(manifest, version = OATS_VERSION) {
 }
 
 // ---------- distribution packages (docs/design/package-engine-contract.md) ----------
-/** Kernel error with a stable machine-readable code (contract §4) and optional provenance. */
-export function oatsError(code, message, provenance) {
-  const e = new Error(message);
-  e.code = code;
-  if (provenance) e.provenance = provenance;
-  return e;
-}
-
 /** Where one materialized capability artifact lives at a scope.
  *
  * This is the LAST line of defence, and it is a positive proof rather than a
@@ -1614,10 +1918,6 @@ export const installedCapabilityDir = (levelDir, capabilityId) => {
   }
   return dir;
 };
-/** Generated provenance file inside every materialized artifact. It is INSIDE
- * the hashed tree, so tampering with it is integrity drift; the lock stays
- * authoritative. */
-export const CAPABILITY_INSTALLATION_FILE = ".oats-installation.json";
 /** Prefix of a transaction staging directory. It lives inside the (gitignored)
  * installed store so the commit phase is a same-filesystem rename, and it is
  * dot-prefixed so discovery skips it. */
@@ -1628,37 +1928,6 @@ const STAGING_PREFIX = ".staging-";
  * use site: every resolver reads the configured path and falls back here. */
 export const DEFAULT_PACKAGE_PATH = "oats-package";
 
-/** Normalize a configured package path to its canonical form, or throw.
- *
- * Canonical form is a POSIX-relative path with no redundant or trailing
- * separators; every spelling of the repository root ("", ".", "./", "./.")
- * normalizes to the single canonical "." so a root selection round-trips
- * identically through spec → lock → JSON → doctor/list/update (contract §4).
- *
- * Fail-closed: absolute paths, Windows drive paths, host-ambient "~" spellings,
- * backslash separators (ambiguous — a backslash is a legal POSIX filename
- * character, so accepting it as a separator would make containment checks
- * disagree with the filesystem) and NUL are rejected as invalid-source; ".."
- * traversal is path-escape. Returns undefined ONLY for an absent value, so the
- * caller can apply the source-appropriate default. */
-export function normalizePackagePath(raw, { where = "package path", code = "invalid-source" } = {}) {
-  // ABSENT means absent. A present `null` (JSON's way of spelling a malformed
-  // value) is a violation, not a fall-through to the caller's default — a
-  // catalog entry that says `"path": null` must fail, not silently install
-  // DEFAULT_PACKAGE_PATH.
-  if (raw === undefined) return undefined;
-  if (typeof raw !== "string") throw oatsError(code, `${where} must be a string (got ${Array.isArray(raw) ? "array" : raw === null ? "null" : typeof raw})`);
-  const s = raw.trim();
-  if (s.includes("\0")) throw oatsError(code, `${where} contains a NUL byte`);
-  if (s.startsWith("~")) throw oatsError(code, `${where} "${s}" is a host-ambient path — package paths are repository-relative`);
-  if (s.includes("\\")) throw oatsError(code, `${where} "${s}" uses backslashes — package paths are POSIX-relative (use "/")`);
-  if (/^[A-Za-z]:[/\\]/.test(s)) throw oatsError(code, `${where} "${s}" is an absolute drive path — package paths are repository-relative`);
-  if (isAbsolute(s)) throw oatsError(code, `${where} "${s}" is absolute — package paths are repository-relative`);
-  const segments = s.split("/").filter((seg) => seg !== "" && seg !== ".");
-  if (segments.includes("..")) throw oatsError("path-escape", `${where} "${s}" escapes the source root with ".."`);
-  return segments.length ? segments.join("/") : ".";
-}
-
 /** Split an optional `#<package-path>` fragment off a source spec. A source may
  * carry at most one fragment; the fragment is removed BEFORE `@ref` parsing so
  * a path can never be mistaken for part of a ref. */
@@ -1768,51 +2037,6 @@ export function inspectGitSourceRoot(spec) {
   } catch (e) { rmSync(tmp, { recursive: true, force: true }); throw e; }
 }
 
-/** Parse a lock entry's `source` against the EXACT normalized grammar the
- * writer produces. Strict on purpose: `updatePackage` turns this back into a
- * source spec, so a payload that merely "starts with catalog:" but is not a
- * valid catalog id gets RECLASSIFIED downstream — `catalog:../evil` would be
- * re-parsed as a host-relative local path and acquired from the operator's
- * filesystem. A lock also never carries a `#<path>` fragment: the selected
- * root is the entry's own `path` field, and a fragment here would produce a
- * double-fragment spec on update. */
-function parseLockSource(src) {
-  const s = String(src || "");
-  const bad = (why) => oatsError("invalid-source", `unknown lock source "${src}" — ${why}`);
-  if (s.includes("#")) throw bad(`lock sources carry no "#<path>" fragment; the selected package root is the entry's "path" field`);
-  if (s.startsWith("path:")) {
-    const p = s.slice(5);
-    if (!p) throw bad("empty path source");
-    if (!isAbsolute(p)) throw bad("path source must be an absolute directory (the writer always resolves it)");
-    return { kind: "path", path: p, normalized: s };
-  }
-  if (s.startsWith("catalog:")) {
-    const body = s.slice(8);
-    // Split at the FIRST "@", mirroring the public parser's regex: the catalog
-    // id grammar cannot contain "@", so everything after the first one is the
-    // selector. Splitting at the LAST "@" misreads a legitimate ref spelling
-    // such as `oats.okf@release@candidate` — which the writer does produce —
-    // as the id `oats.okf@release`.
-    const at = body.indexOf("@");
-    const id = at > 0 ? body.slice(0, at) : body;
-    const selector = at > 0 ? body.slice(at + 1) : undefined;
-    if (!PACKAGE_ID_RE.test(id)) throw bad(`"${id}" is not a valid official catalog id`);
-    if (at > 0 && !selector) throw bad("empty catalog selector");
-    return { kind: "catalog", id, selector, normalized: s };
-  }
-  if (s.startsWith("git:")) {
-    const body = s.slice(4);
-    const at = body.lastIndexOf("@") > body.lastIndexOf("/") ? body.lastIndexOf("@") : -1;
-    const url = at > 0 ? body.slice(0, at) : body;
-    const ref = at > 0 ? body.slice(at + 1) : undefined;
-    if (!url) throw bad("empty git url");
-    if (at > 0 && !ref) throw bad("empty git ref");
-    if (!/^(https?:\/\/|file:\/\/|git@|ssh:\/\/|git:\/\/)/.test(url)) throw bad(`"${url}" is not an http(s)/ssh/file/git URL`);
-    return { kind: "git", url, ref, normalized: s };
-  }
-  throw oatsError("invalid-source", `unknown lock source "${src}"`);
-}
-
 /** Official package catalog: identity + discovery ONLY — resolving through it
  * never advances a lock and never grants executable trust (contract §1).
  * Workstream 3 seeds the kernel-bundled catalog; OATS_PACKAGE_CATALOG points
@@ -1914,27 +2138,6 @@ export function packageIntegrity(dir) {
   return `sha256-${hash.digest("hex")}`;
 }
 
-/** Stable integrity of a MATERIALIZED capability artifact: every byte under
- * `.agents/capabilities/installed/<id>/`, with NO exclusions — capability source,
- * the materialized runtime closure (node_modules), and the generated
- * `.oats-installation.json` provenance file all count. This is the only digest
- * executable trust binds to, which is why a separate dependency digest does not
- * exist at capability level: the closure is inside the artifact, so tampering
- * with a dependency is ordinary artifact drift. */
-export function capabilityArtifactIntegrity(dir) {
-  const hash = createHash("sha256");
-  const walk = (d) => {
-    for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const p = join(d, e.name);
-      if (e.isDirectory()) walk(p);
-      else if (e.isFile()) { hash.update(relative(dir, p)); hash.update("\0file\0"); hash.update(readFileSync(p)); hash.update("\0"); }
-      else if (e.isSymbolicLink()) { hash.update(relative(dir, p)); hash.update("\0symlink\0"); hash.update(readlinkSync(p)); hash.update("\0"); }
-    }
-  };
-  walk(dir);
-  return `sha256-${hash.digest("hex")}`;
-}
-
 const PACKAGE_MANIFEST_KEYS = new Set(["package", "version", "description", "compatibility", "capabilities", "configTemplates", "configs", "dependencies"]);
 /** Canonical home of a package's config templates. Manifest paths are
  * repository-relative and always spelled with "/", on every platform. */
@@ -1959,12 +2162,12 @@ export function isCanonicalTemplatePath(p) {
  *                    whichever spelling the manifest used
  *   _capabilities    [{ id, rel, dir, manifest }]
  */
-export function loadPackageManifestAt(pdir) {
+export function loadPackageManifestAt(pdir, { strict = false } = {}) {
   const mf = join(pdir, "oats-package.json");
   if (!existsSync(mf)) throw oatsError("invalid-package-manifest", `${pdir} has no oats-package.json distribution manifest`);
   let m;
-  try { m = JSON.parse(readFileSync(mf, "utf8")); }
-  catch (e) { throw oatsError("invalid-package-manifest", `invalid JSON in ${mf}: ${e.message}`); }
+  try { m = strict ? parseStrictJson(readPortableBytes(mf)) : JSON.parse(readFileSync(mf, "utf8")); }
+  catch (e) { if (strict) throw e; throw oatsError("invalid-package-manifest", `invalid JSON in ${mf}: ${e.message}`); }
   // Hostile-input shapes: JSON null/scalar/array roots are valid JSON but not manifests.
   if (!m || typeof m !== "object" || Array.isArray(m)) throw oatsError("invalid-package-manifest", `${mf} must be a JSON object (got ${m === null ? "null" : Array.isArray(m) ? "array" : typeof m})`);
   if (typeof m.package !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(m.package)) throw oatsError("invalid-package-manifest", `${mf} needs a valid string "package" identity (lowercase [a-z0-9._-])`);
@@ -2015,7 +2218,7 @@ export function loadPackageManifestAt(pdir) {
   for (const rel of m.capabilities) {
     const dir = inside(rel, "capability");
     if (!existsSync(join(dir, "oats.json"))) throw oatsError("invalid-package-manifest", `package ${m.package} capability path ${rel} has no oats.json (not a capability)`);
-    const cm = loadManifestAt(dir, `package:${m.package}`);
+    const cm = loadManifestAt(dir, `package:${m.package}`, { strict });
     // A PACKAGE-exported id will be materialized as a directory name under
     // installed/, so it must satisfy the materialized grammar — stricter than
     // the legacy standalone-capability rule loadManifestAt applies, which still
@@ -2129,21 +2332,7 @@ export function assertCapabilitySelfContained(capDir, manifest) {
   }
 }
 
-const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
 export const LOCKFILE_VERSION = 2;
-/** Package rows lock the TRANSPORT unit only: no capability list (the capability
- * rows' `package` back-reference is the single provider truth) and no trust
- * (trust binds to materialized capability artifacts). */
-const LOCK_PACKAGE_KEYS = new Set(["source", "path", "version", "commit", "integrity", "dependencies"]);
-/** Capability rows lock the MATERIALIZED entity. */
-const LOCK_CAPABILITY_KEYS = new Set(["version", "package", "path", "integrity", "trusted"]);
-/** Own-property PRESENCE of any of these on a package row is forbidden
- * transitional evidence (contract §4.1) — never truthiness and never array
- * length, so an empty `capabilities: []` or a dependency-free old row still
- * classifies. Package-row `path`/`dependencies` are NEVER tells: the current
- * shape retains both. */
-const TRANSITIONAL_ROW_FIELDS = ["capabilities", "trustedCapabilities", "depsIntegrity"];
-
 /** A null-prototype copy of a raw parsed JSON map. Raw objects return inherited
  * `constructor`/`toString`/`valueOf` for `map[id]` even with no own entry, so
  * every ID-keyed map in the engine goes through this (or `Object.hasOwn`) before
@@ -2154,93 +2343,15 @@ function nullProtoMap(raw) {
   return out;
 }
 
-/** ONE strict lock parser for v1 and the capability-materialization v2: reads +
- * validates root shape, lockfile version, map shapes and keys, entry shapes
- * (full semantic pass incl. the dependency graph and the capability→package
- * back-references), and the v1 capability map. EVERY violation is a typed
- * invalid-lock with provenance, raised with NO side effects. Old locks are read
- * AS THEY ARE — never normalized, repaired or rewritten (the single exception is
- * the state-free empty transitional document, §4.1). Returns
- * { version, packages, capabilities, legacyCapabilities } (null-prototype and
- * validated) or null when the file does not exist. */
+/** Public bytes seam for evidence-grade migration. Ordinary consumers use the
+ * file wrapper below; both share the one acyclic legacy decoder. */
+export function parseLockBytesStrict(bytes, { file = "<oats-lock.json>", limits } = {}) {
+  return decodeLegacyLockBytes(bytes, { file, limits, retiredCapabilityReason });
+}
+
 export function parseLockFileStrict(file) {
   if (!existsSync(file)) return null;
-  const bad = (msg, extra = {}) => oatsError("invalid-lock", `${file}: ${msg}`, [{ file, violation: msg, ...extra }]);
-  let parsed;
-  try { parsed = JSON.parse(readFileSync(file, "utf8")); }
-  catch (e) { throw bad(`malformed JSON — ${e.message}`); }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw bad(`lock root must be a JSON object (got ${parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed})`);
-  const v = parsed.lockfileVersion;
-  if (v !== undefined && typeof v !== "number") throw bad(`lockfileVersion must be a number (got ${JSON.stringify(v)})`);
-  if (v !== undefined && v !== 1 && v !== 2) throw bad(`unsupported lockfileVersion ${v}`);
-  const version = v ?? 1;
-  if (parsed.capabilities !== undefined && (parsed.capabilities === null || typeof parsed.capabilities !== "object" || Array.isArray(parsed.capabilities))) {
-    throw bad(`"capabilities" must be an object map (got ${parsed.capabilities === null ? "null" : Array.isArray(parsed.capabilities) ? "array" : typeof parsed.capabilities})`);
-  }
-  const out = { version, packages: Object.create(null), capabilities: Object.create(null), legacyCapabilities: Object.create(null) };
-  if (version === 1) {
-    if (parsed.packages !== undefined) throw bad(`lockfileVersion 1 must not carry a "packages" map`);
-    // Validate the COMPLETE v1 map before ANY consumer sees it. Retirement
-    // intentionally wins over shape validation (the user is told to delete that
-    // entry), but every non-retired entry is strict — that keeps restore
-    // preflight atomic and stops a malformed entry from granting the
-    // marketplace/hoisted exemption during discovery (reviewer-12e2d86).
-    for (const id of Object.keys(parsed.capabilities || {})) {
-      const entry = parsed.capabilities[id];
-      if (!retiredCapabilityReason(id)) {
-        const violation = legacyCapabilityEntryViolation(entry);
-        if (violation) throw bad(`legacy entry "${id}" is malformed (${violation})`, { package: id });
-      }
-      out.legacyCapabilities[id] = entry;
-    }
-    return out;
-  }
-  const rawPackages = parsed.packages;
-  if (rawPackages === undefined || rawPackages === null || typeof rawPackages !== "object" || Array.isArray(rawPackages)) {
-    throw bad(`lockfileVersion 2 requires a "packages" object map (got ${rawPackages === undefined ? "undefined" : rawPackages === null ? "null" : Array.isArray(rawPackages) ? "array" : typeof rawPackages})`);
-  }
-  const packageKeys = Object.keys(rawPackages);
-  const hasCapabilityMap = Object.hasOwn(parsed, "capabilities");
-  const stateFree = !packageKeys.length && (!hasCapabilityMap || !Object.keys(parsed.capabilities).length);
-  // UNSUPPORTED TRANSITIONAL v2 (contract §4.1) — an exact OR predicate, decided
-  // centrally before any discovery or mutation. It is never converted and never
-  // partially interpreted; the operator recreates the scope.
-  const unsupported = (why) => bad(`unsupported transitional package-root lockfileVersion 2 (${why}). This is the superseded package-store lock shape; it is not converted or interpreted. Delete this lock (and any .agents/packages directory) and recreate the scope's state with \`oats install\`.`);
-  if (!stateFree) {
-    if (!hasCapabilityMap) throw unsupported(`no top-level "capabilities" map`);
-    for (const id of packageKeys) {
-      const row = rawPackages[id];
-      if (!row || typeof row !== "object" || Array.isArray(row)) continue; // shape error reported below
-      const tells = TRANSITIONAL_ROW_FIELDS.filter((f) => Object.hasOwn(row, f));
-      if (tells.length) throw unsupported(`package row "${id}" carries ${tells.join(", ")}`);
-    }
-  }
-  for (const id of packageKeys) {
-    if (!PACKAGE_ID_RE.test(id)) throw bad(`packages map has an invalid package key ${JSON.stringify(id)}`, { package: id });
-    const e = rawPackages[id];
-    if (!e || typeof e !== "object" || Array.isArray(e)) throw bad(`lock entry for "${id}" is not an object`, { package: id });
-    const extra = Object.keys(e).filter((k) => !LOCK_PACKAGE_KEYS.has(k));
-    if (extra.length) throw bad(`lock entry for "${id}" has unknown keys: ${extra.join(", ")}`, { package: id });
-    out.packages[id] = e;
-  }
-  for (const id of Object.keys(out.packages)) validateLockEntry(id, out.packages[id], out.packages, { file });
-  // A state-free empty transitional document carries nothing, so it reads as the
-  // canonical empty lock rather than failing (contract §4.1).
-  if (hasCapabilityMap) {
-    for (const id of Object.keys(parsed.capabilities)) {
-      // BEFORE any filesystem join anywhere downstream: a revised-v2 capability
-      // key names a directory under installed/, so the grammar is enforced here,
-      // in the one central reader, rather than at each consumer.
-      if (!isMaterializedCapabilityId(id)) throw bad(`capabilities map has an invalid capability key: ${capabilityIdViolation(id)}`);
-      const e = parsed.capabilities[id];
-      if (!e || typeof e !== "object" || Array.isArray(e)) throw bad(`capability lock entry for "${id}" is not an object`, { package: id });
-      const extra = Object.keys(e).filter((k) => !LOCK_CAPABILITY_KEYS.has(k));
-      if (extra.length) throw bad(`capability lock entry for "${id}" has unknown keys: ${extra.join(", ")}`, { package: id });
-      out.capabilities[id] = e;
-    }
-  }
-  for (const id of Object.keys(out.capabilities)) validateCapabilityLockEntry(id, out.capabilities[id], out.packages, { file });
-  return out;
+  return parseLockBytesStrict(readFileSync(file), { file });
 }
 
 /** Every lock-owning scope visible from a directory, outermost → innermost.
@@ -2753,108 +2864,13 @@ function pruneCreatedAnchors(createdAnchors) {
   }
 }
 
-/** The generated provenance carried INSIDE every materialized artifact.
- *
- * Because the file is part of the artifact's integrity, a future kernel
- * reprojecting the same locked bytes must produce it byte-for-byte. It therefore
- * contains NOTHING about the writing kernel — only lock-, source- and
- * manifest-derived values — and is serialized deterministically: exactly these
- * keys in this order, two-space JSON, one trailing newline, mode 0644.
- * `schemaVersion` is a constant of the format, bumped only by an explicit
- * contract change (which is itself an integrity change, so it is visible). */
-function capabilityInstallationRecord(cap, pkg) {
-  return {
-    schemaVersion: 1,
-    capability: cap.id,
-    version: cap.manifest.version,
-    package: pkg.package,
-    packageVersion: pkg.version,
-    source: pkg.source,
-    commit: pkg.commit,
-    packagePath: pkg.path,
-    capabilityPath: cap.rel,
-  };
-}
-function writeCapabilityInstallation(dest, cap, pkg) {
-  writeFileSync(join(dest, CAPABILITY_INSTALLATION_FILE), JSON.stringify(capabilityInstallationRecord(cap, pkg), null, 2) + "\n", { mode: 0o644 });
-}
-/** Read an artifact's provenance and check it AGREES with the lock rows it was
- * projected from. Disagreement is invalid-lock: the artifact and the lock claim
- * different origins, and neither may silently win. (A modified file also fails
- * integrity, but this gives the precise diagnosis.) */
-export function verifyCapabilityInstallation(dir, capabilityId, capRow, pkgRow) {
-  const file = join(dir, CAPABILITY_INSTALLATION_FILE);
-  if (!existsSync(file)) throw oatsError("invalid-lock", `materialized capability ${capabilityId} has no ${CAPABILITY_INSTALLATION_FILE} provenance — reproject it with \`oats install\``, [{ package: capabilityId, file }]);
-  let doc;
-  try { doc = JSON.parse(readFileSync(file, "utf8")); }
-  catch (e) { throw oatsError("invalid-lock", `materialized capability ${capabilityId} has malformed ${CAPABILITY_INSTALLATION_FILE}: ${e.message}`, [{ package: capabilityId, file }]); }
-  const expected = {
-    schemaVersion: 1, capability: capabilityId, version: capRow.version, package: capRow.package,
-    packageVersion: pkgRow.version, source: pkgRow.source, commit: pkgRow.commit,
-    packagePath: pkgRow.path, capabilityPath: capRow.path,
-  };
-  for (const [k, want] of Object.entries(expected)) {
-    if (doc?.[k] !== want) throw oatsError("invalid-lock", `materialized capability ${capabilityId}: ${CAPABILITY_INSTALLATION_FILE} "${k}" is ${JSON.stringify(doc?.[k])} but the lock records ${JSON.stringify(want)}`, [{ package: capabilityId, file, violation: k }]);
-  }
-  return doc;
-}
-
-/** The executable surface a capability manifest declares. */
-function executableSurfaceOf(manifest) {
-  return {
-    commands: Object.keys(manifest?.commands || {}),
-    hooks: Object.keys(manifest?.hooks || {}),
-    environment: [...(manifest?.environment || [])],
-    ...(manifest?.environmentNamespaces?.length ? { environmentNamespaces: [...manifest.environmentNamespaces] } : {}),
-  };
-}
-function hasExecutableSurface(manifest) {
-  const s = executableSurfaceOf(manifest);
-  return s.commands.length > 0 || s.hooks.length > 0 || s.environment.length > 0;
-}
-
-/** MATERIALIZE one capability out of a staged package payload into a flat,
- * self-contained artifact (Decision: "Materialized capabilities are
- * self-contained"). Everything happens in staging; nothing durable is touched.
- *
- * Order matters and is load-bearing:
- *   1. materialize the capability's own runtime closure (npm ci, no scripts);
- *   2. verify self-containment of every DECLARED resource, then symlink
- *      containment and the native-binary scan of the materialized closure —
- *      all against the CAPABILITY root, before any digest;
- *   3. move the validated root into the artifacts area;
- *   4. write .oats-installation.json provenance INSIDE the artifact;
- *   5. hash the finished artifact.
- * Hashing last is what makes provenance and closure tamper-evident.
- */
-function materializeCapability({ cap, pkg, artifactsDir }) {
-  const rep = materializeCapabilityDeps(cap.dir);
-  if (rep.error) throw oatsError("invalid-package-manifest", `runtime dependency materialization failed for capability "${cap.id}" of package "${pkg.package}": ${rep.error}`);
-  assertCapabilitySelfContained(cap.dir, cap.manifest);
-  assertMaterializedDepsContained(cap.dir);
-  assertNoNativeBinaries(cap.dir);
-  const dest = join(artifactsDir, cap.id);
-  mkdirSync(dirname(dest), { recursive: true });
-  if (cap.rel === ".") {
-    // Legacy flat layout: the capability root IS the staged package root, which
-    // other steps still need, so copy instead of moving it out. copyTreeSafe
-    // recreates symlinks verbatim — rewriting a link target would change bytes
-    // the integrity digest is about to cover — and stays catchable.
-    copyTreeSafe(cap.dir, dest);
-  } else renameSync(cap.dir, dest);
-  writeCapabilityInstallation(dest, cap, pkg);
-  return {
-    capability: cap.id, version: cap.manifest.version, package: pkg.package, path: cap.rel,
-    dir: dest, integrity: capabilityArtifactIntegrity(dest),
-    // The DECLARED fundamental layer, normalized to null when the capability
-    // declares none. A config template may bind a fundamental slot to one of the
-    // root package's own capabilities, and until the artifact is materialized
-    // there is nowhere else to read that from — so it belongs in the pre-commit
-    // preview, not in a post-commit validation with an outer rollback.
-    layer: cap.manifest.layer ?? null,
-    executableSurface: executableSurfaceOf(cap.manifest), manifest: cap.manifest,
-  };
-}
+/** One materializer for old acquisition/restore and the new preparation adapter:
+ * dependencies -> complete containment/native checks -> projection -> stable v1
+ * installation provenance -> digest. No source/selection/trust policy moves here. */
+const materializeCapability = createCapabilityMaterializer({
+  materializeCapabilityDeps, assertCapabilitySelfContained,
+  assertMaterializedDepsContained, assertNoNativeBinaries,
+});
 
 /** Config-template descriptors AND payload bytes, read from a staged package
  * before staging is discarded, so the config lane can offer or adopt a template
@@ -2938,10 +2954,14 @@ export function acquirePackage(levelDir, spec, opts = {}) {
   const { dir: staging, createdAnchors, ignore } = beginStaging(levelDir);
   const artifactsDir = join(staging, "artifacts");
   mkdirSync(artifactsDir, { recursive: true });
-  const resolved = new Map(); // identity → staged package record
   let counter = 0;
-  const resolveClosure = (srcSpec, chain, baseDir) => {
+  const readPackage = (srcSpec, parent, chain) => {
+    const baseDir = parent?.parsedSource.kind === "path" ? parent.parsedSource.path : undefined;
     const p = parsePackageSource(srcSpec, { baseDir });
+    if (parent) {
+      if (p.kind === "git" && !p.ref) throw oatsError("invalid-source", `package dependency must be pinned to a tag/commit: "${srcSpec}" (declared by ${parent.package})`);
+      if (p.kind === "path" && p.relative && !baseDir) throw oatsError("invalid-source", `package dependency "${srcSpec}" (declared by ${parent.package}) is a relative path, but ${parent.package} was not acquired from a local path — relative dependencies only work between co-located local packages`);
+    }
     const dest = join(staging, `pkg-${counter++}`);
     let commit, packagePath;
     if (!chain.length && opts.rootSnapshot) {
@@ -2962,7 +2982,6 @@ export function acquirePackage(levelDir, spec, opts = {}) {
     } else ({ commit, path: packagePath } = fetchPackageSource(p, dest, opts.catalog));
     const m = loadPackageManifestAt(dest);
     const id = m.package;
-    if (chain.includes(id)) throw oatsError("dependency-cycle", `package dependency cycle: ${[...chain, id].join(" → ")}`, [...chain, id]);
     // Preserve the ORIGINAL catalog spec in lock metadata: bare and explicit
     // selector forms must remain distinguishable for update. The resolved git
     // commit is already pinned separately in `commit`.
@@ -2971,36 +2990,21 @@ export function acquirePackage(levelDir, spec, opts = {}) {
     // contain several packages (contract §1.1), so two payload roots claiming one
     // package identity are a collision, not the same package resolved twice.
     const sourceKey = `${source}#${packagePath}`;
-    if (resolved.has(id)) {
-      const prev = resolved.get(id);
-      if (prev.sourceKey !== sourceKey) throw oatsError("duplicate-package-identity", `two sources claim package "${id}" at ${levelDir}: ${prev.sourceKey} and ${sourceKey}`, [prev.sourceKey, sourceKey]);
-      rmSync(dest, { recursive: true, force: true });
-      return id;
-    }
-    const compat = capabilityCompatibility(m);
-    if (!compat.compatible) throw oatsError("incompatible-oats", `package ${id} requires OATS ${compat.range} (running ${OATS_VERSION})`);
-    const deps = [];
-    for (const d of m.dependencies || []) {
-      // Relative local-path dependencies resolve against the DEPENDING PACKAGE'S
-      // source root (contract intent: package-relative), never the process CWD.
-      // For git/catalog parents there is no local base.
-      const depBase = p.kind === "path" ? p.path : undefined;
-      const dp = parsePackageSource(d, { baseDir: depBase });
-      if (dp.kind === "git" && !dp.ref) throw oatsError("invalid-source", `package dependency must be pinned to a tag/commit: "${d}" (declared by ${id})`);
-      // EVERY relative path dependency requires a local base — classified from
-      // the parsed payload so "path:sub" / whitespace spellings cannot resolve
-      // through the process CWD from a git/catalog manifest (reviewer-2a4adec).
-      if (dp.kind === "path" && dp.relative && !depBase) throw oatsError("invalid-source", `package dependency "${d}" (declared by ${id}) is a relative path, but ${id} was not acquired from a local path — relative dependencies only work between co-located local packages`);
-      deps.push(resolveClosure(d, [...chain, id], depBase));
-    }
-    resolved.set(id, {
+    return {
       package: id, dir: dest, manifest: m, source, path: packagePath, sourceKey, commit,
-      version: m.version, integrity: packageIntegrity(dest), deps, capabilities: m._capabilities,
-    });
-    return id;
+      version: m.version, capabilities: m._capabilities, parsedSource: p, dependencyRequests: m.dependencies || [],
+    };
   };
   try {
-    const rootId = resolveClosure(spec, [], undefined);
+    const { roots: [rootId], packages: resolved } = resolvePackageClosure({
+      requests: [spec], readPackage, context: levelDir,
+      validatePackage(record) {
+        const compat = capabilityCompatibility(record.manifest);
+        if (!compat.compatible) throw oatsError("incompatible-oats", `package ${record.package} requires OATS ${compat.range} (running ${OATS_VERSION})`);
+      },
+      finalizePackage: (record, deps) => ({ ...record, integrity: packageIntegrity(record.dir), deps }),
+      discardPackage: (record) => rmSync(record.dir, { recursive: true, force: true }),
+    });
     if (opts.expectPackage && rootId !== opts.expectPackage) {
       throw oatsError("duplicate-package-identity", `source ${spec} no longer provides root package "${opts.expectPackage}" (root resolved to "${rootId}")`);
     }
@@ -3187,97 +3191,6 @@ export function acquirePackage(levelDir, spec, opts = {}) {
   }
 }
 
-/** Semantic lock-entry validation for a PACKAGE row (runtime API addendum §4):
- * source/commit pairing, canonical path, dependency references (incl. self and
- * cycle over the locked graph), digest shapes, uniqueness. Run BEFORE restore,
- * trust/approval, update/remove/migration planning, the locked-template reader,
- * and doctor/list consumption. Fails closed with code "invalid-lock" carrying
- * file/package provenance; never normalizes or auto-repairs on read. */
-export function validateLockEntry(packageId, entry, allPackages = {}, opts = {}) {
-  const where = opts.file ? ` (${opts.file})` : "";
-  const bad = (msg) => oatsError("invalid-lock", `lock entry for package "${packageId}"${where} is invalid: ${msg}`, [{ package: packageId, file: opts.file, violation: msg }]);
-  if (!entry || typeof entry !== "object") throw bad("not an object");
-  for (const k of ["source", "path", "version", "commit", "integrity"]) if (!entry[k] || typeof entry[k] !== "string") throw bad(`missing ${k}`);
-  // The selected package root is a STRICT separate field (contract §1.1) stored
-  // in canonical form only — a lock is never normalized or repaired on read, so
-  // a non-canonical spelling ("./sub", "sub/", "") is invalid, not silently
-  // accepted. That is what makes the root representation round-trip.
-  {
-    let canonical;
-    try { canonical = normalizePackagePath(entry.path, { where: "path", code: "invalid-lock" }); }
-    catch (e) { throw bad(`invalid path ${JSON.stringify(entry.path)} — ${e.message}`); }
-    if (canonical !== entry.path) throw bad(`path ${JSON.stringify(entry.path)} is not in canonical form (expected ${JSON.stringify(canonical)})`);
-  }
-  if (!/^sha256-[0-9a-f]{64}$/.test(entry.integrity)) throw bad(`malformed integrity "${entry.integrity}"`);
-  // Present-but-wrong-typed optional fields are invalid — default ONLY when absent.
-  // `dependencies` is ALWAYS recorded (empty array when none), so a reader never
-  // has to distinguish absent from empty.
-  if (!Array.isArray(entry.dependencies)) throw bad("dependencies must be an array (empty when the package has none)");
-  for (const d of entry.dependencies) if (typeof d !== "string" || !PACKAGE_ID_RE.test(d)) throw bad(`dependencies contains an invalid package id ${JSON.stringify(d)}`);
-  if (new Set(entry.dependencies).size !== entry.dependencies.length) throw bad("dependencies contains duplicates");
-  // Package rows lock transport only. A capability list, a trust list or a
-  // dependency-closure digest here is the unsupported transitional shape — the
-  // central parser rejects those documents outright (contract §4.1); this is
-  // the entry-level backstop for a row reaching validation another way.
-  for (const gone of TRANSITIONAL_ROW_FIELDS) {
-    if (Object.hasOwn(entry, gone)) throw bad(`"${gone}" is a transitional package-root field — package rows lock transport only (capabilities and trust live on capability rows)`);
-  }
-  let src;
-  try { src = parseLockSource(entry.source); } catch { throw bad(`unrecognized source "${entry.source}"`); }
-  if (src.kind === "path" && !src.path) throw bad("empty path source");
-  if (src.kind === "git" && !src.url) throw bad("empty git source");
-  if (src.kind === "catalog" && !src.id) throw bad("empty catalog source");
-  if (src.kind === "path") {
-    if (entry.commit !== "local") throw bad(`path source requires commit "local", got "${entry.commit}"`);
-    // Local acquisition is exact-directory: the source string already names the
-    // package root, so the only valid contained path is the root itself.
-    if (entry.path !== ".") throw bad(`path source requires path "." (local sources are exact directories), got ${JSON.stringify(entry.path)}`);
-  }
-  else if (!/^[0-9a-f]{40}$/.test(entry.commit)) throw bad(`${src.kind} source requires an exact 40-hex commit, got "${entry.commit}"`);
-  for (const d of entry.dependencies || []) {
-    if (d === packageId) throw bad(`self-dependency "${d}"`);
-    // Object.hasOwn: a dependency literally named "constructor"/"__proto__"
-    // must not pass via Object.prototype.
-    if (!Object.hasOwn(allPackages, d)) throw bad(`dependency "${d}" is not locked in the same packages map`);
-  }
-  // Cycle over the locked dependency graph reachable from this entry.
-  const visiting = new Set();
-  const visited = new Set();
-  const walk = (id, chain) => {
-    if (visited.has(id)) return;
-    if (visiting.has(id)) throw bad(`dependency cycle in the locked graph: ${[...chain, id].join(" → ")}`);
-    visiting.add(id);
-    const deps = Object.hasOwn(allPackages, id) && Array.isArray(allPackages[id]?.dependencies) ? allPackages[id].dependencies : [];
-    for (const d of deps) if (Object.hasOwn(allPackages, d) || d === packageId) walk(d, [...chain, id]);
-    visiting.delete(id); visited.add(id);
-  };
-  walk(packageId, []);
-  return true;
-}
-
-/** Semantic validation of one CAPABILITY row against the whole document
- * (contract §4). The `package` back-reference must name a locked package: it is
- * the single provider truth, so a dangling reference would leave a materialized
- * artifact with no provenance to restore or verify it from. */
-export function validateCapabilityLockEntry(capabilityId, entry, allPackages = {}, opts = {}) {
-  const where = opts.file ? ` (${opts.file})` : "";
-  const bad = (msg) => oatsError("invalid-lock", `capability lock entry for "${capabilityId}"${where} is invalid: ${msg}`, [{ package: capabilityId, file: opts.file, violation: msg }]);
-  if (typeof capabilityId !== "string" || !capabilityId) throw bad("empty capability id");
-  if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw bad("not an object");
-  for (const k of ["version", "package", "path", "integrity"]) if (!entry[k] || typeof entry[k] !== "string") throw bad(`missing ${k}`);
-  if (!PACKAGE_ID_RE.test(entry.package)) throw bad(`provider package ${JSON.stringify(entry.package)} is not a valid package identity`);
-  if (!Object.hasOwn(allPackages, entry.package)) throw bad(`provider package "${entry.package}" is not locked in the same packages map`);
-  {
-    let canonical;
-    try { canonical = normalizePackagePath(entry.path, { where: "path", code: "invalid-lock" }); }
-    catch (e) { throw bad(`invalid path ${JSON.stringify(entry.path)} — ${e.message}`); }
-    if (canonical !== entry.path) throw bad(`path ${JSON.stringify(entry.path)} is not in canonical form (expected ${JSON.stringify(canonical)})`);
-  }
-  if (!/^sha256-[0-9a-f]{64}$/.test(entry.integrity)) throw bad(`malformed integrity "${entry.integrity}"`);
-  if (typeof entry.trusted !== "boolean") throw bad(`"trusted" must be a boolean (got ${JSON.stringify(entry.trusted)})`);
-  return true;
-}
-
 /** Fetch ONE locked package's exact provenance into staging and return the
  * verified payload root. Used by restore, update planning, migration and the
  * locked-template reader — every path that needs the exact bytes a package row
@@ -3661,33 +3574,27 @@ export function readLockedConfigTemplates(startDir, packageId, opts = {}) {
   } finally { rmSync(tmp, { recursive: true, force: true }); }
 }
 
-/** Validate one LEGACY (lockfileVersion 1) capability lock entry against the v1
- * schema shape; returns null when valid or a violation string.
- *
- * Engine-internal: the strict reader uses it so a malformed v1 entry is refused
- * before any consumer sees the map. It is deliberately NOT a "residue" check —
- * migration produces no residue, and the superseded transitional v2 shape is
- * rejected wholesale rather than partially parsed. */
-export function legacyCapabilityEntryViolation(entry) {
-  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return "not an object";
-  for (const k of ["source", "version", "integrity"]) if (typeof entry[k] !== "string" || !entry[k]) return `missing/invalid ${k}`;
-  if (!/^sha256-[0-9a-f]{64}$/.test(entry.integrity)) return `malformed integrity "${entry.integrity}"`;
-  if (entry.commit !== undefined && typeof entry.commit !== "string") return "invalid commit";
-  if (entry.trustedExecutables !== undefined && typeof entry.trustedExecutables !== "boolean") return "invalid trustedExecutables";
-  return null;
-}
-
 /** Atomic file replacement: write to a same-directory temp file, then rename
  * over the destination — an interrupted write leaves the original bytes intact
  * (reviewer-21849d4). */
-function atomicWriteFileSync(file, content) {
+function atomicWriteFileSync(file, content, { assertRoots } = {}) {
   const tmp = join(dirname(file), `.${basename(file)}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`);
+  let written = false;
   try {
-    writeFileSync(tmp, content);
+    assertRoots?.();
+    writeFileSync(tmp, content, assertRoots ? { flag: "wx", mode: 0o600 } : undefined); written = true;
+    assertRoots?.();
     renameSync(tmp, file);
-  } catch (e) {
-    rmSync(tmp, { force: true });
-    throw e;
+  } catch (error) {
+    // Never follow a replacement parent to clean up a same-named temp file.
+    // Unguarded legacy callers retain their existing behavior.
+    if (assertRoots && !written) throw error;
+    try { assertRoots?.(); rmSync(tmp, { force: true }); }
+    catch (cleanup) {
+      const failure = new AggregateError([error, cleanup], "metadata publication and owned cleanup failed", { cause: error });
+      failure.code = error.code || cleanup.code; throw failure;
+    }
+    throw error;
   }
 }
 
@@ -4170,15 +4077,8 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
     if (cap.inject && existsSync(cap.inject)) wanted.push([`capability:${cap.id}`, cap.inject]);
   }
   for (const inj of resolved.injects) wanted.push([`config:${inj.source}`, inj.file]);
-  let text = readFileSync(agentsMd, "utf8").replace(/\n*$/, "\n");
-  const blocks = [];
-  for (const [source, file] of wanted) {
-    const content = readFileSync(file, "utf8").trim();
-    const block = `<!-- oats:${source} src=${file} -->\n${content}\n<!-- /oats:${source} -->`;
-    text += `\n${block}\n`;
-    blocks.push({ source, file, content });
-  }
-  return { text, blocks, resolved };
+  const blocks = wanted.map(([source, file]) => ({ source, file, content: readFileSync(file, "utf8").trim() }));
+  return { text: renderInstructionText(readFileSync(agentsMd, "utf8"), blocks), blocks, resolved };
 }
 
 /** The skill entries a tree contributes — THE discovery rule, shared by preflight
@@ -4726,6 +4626,187 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
   return results;
 }
 
+/** Derive one selected supplemental input from the exact hook owner's binding
+ * and already-validated generic target. Never infer dependency from a slot/name. */
+function capturedHookSourceReceipt(loaded) {
+  const { record, capability, invocation } = loaded, target = invocation?.instance;
+  const declaration = capability && hookDeclaration(capability.manifest.hooks?.[invocation?.action.name]);
+  if (!target || invocation.action.kind !== "hook" || invocation.capability !== capability.id || declaration?.inputs?.sourceReceipt?.version !== 1) throw oatsError("invalid-resolution", "source receipt requires an opted-in exact owned hook target");
+  const binding = record.bindings[capability.manifest.layer];
+  if (!binding || binding.capability !== capability.id) throw oatsError("needs-configuration", "source receipt requires the opting capability's actual selected binding");
+  const roleFile = loaded.resources.get(record.dispatch.composition?.body);
+  if (!roleFile) throw oatsError("invalid-resolution", "selected source input lacks its canonical body resource");
+  return validateCapturedSourceReceipt({ schemaVersion: 1, kind: record.subject.kind,
+    home: target.home, work: target.work, context: invocation.executionBinding.deployment,
+    agent: target.agent, instance: target.name, sourceIdentity: record.subject.kind === "persistent" ? record.subject.soul.identity : null,
+    role: decodeUtf8(readPortableBytes(roleFile)), executionBinding: invocation.executionBinding,
+    responsibleHuman: invocation.responsibleHuman, binding });
+}
+
+/** Captured lifecycle execution uses the same hook result contract, but every
+ * executable/settings/binding input comes from one verified resolution. It
+ * preflights all applicable hooks before the first lifecycle side effect. */
+export function runCapturedLifecycleHooks(event, { deployment, resolution, home, instance, agentName, priorMeta = {}, extraEnv = {}, sourceReceipt, assertRoots, retryIntents = {} }) {
+  if (!APPROVED_HOOKS.has(event)) throw oatsError("unsupported-action", `unsupported captured lifecycle event ${JSON.stringify(event)}`);
+  for (const [name, value] of [["home", home], ["deployment", deployment]]) if (typeof value !== "string" || !isAbsolute(value)) throw oatsError("invalid-declaration", `${name} must be absolute`);
+  if (typeof instance !== "string" || !instance || typeof agentName !== "string" || !agentName) throw oatsError("invalid-declaration", "captured lifecycle needs instance and agent names");
+  if (sourceReceipt !== undefined) validateCapturedSourceReceipt(sourceReceipt);
+  const inspected = loadCapturedDispatch({ deployment, resolution, action: { kind: "inspect" } });
+  if (sourceReceipt) {
+    const { record } = inspected, persistent = record.subject.kind === "persistent";
+    const expectedAgent = persistent ? record.subject.soul.alias : record.subject.name;
+    const expectedIdentity = persistent ? record.subject.soul.identity : null;
+    const expectedHuman = record.messagingChoice.enabled ? record.messagingChoice.privateKey.human : null;
+    const expectedBinding = Object.values(record.bindings).find((binding) => binding.capability === sourceReceipt.binding.capability);
+    const bodyKey = record.dispatch.composition?.body, bodyFile = bodyKey ? inspected.resources.get(bodyKey) : undefined;
+    let role; try { role = bodyFile ? readFileSync(bodyFile, "utf8") : undefined; } catch { role = undefined; }
+    let sameDeployment = false;
+    try { sameDeployment = portableScope(sourceReceipt.executionBinding.deployment) === portableScope(deployment); } catch { /* invalid scope refuses below */ }
+    if (sourceReceipt.kind !== (persistent ? "persistent" : "helper") || sourceReceipt.home !== resolve(home)
+      || sourceReceipt.work !== join(resolve(home), "work") || sourceReceipt.agent !== expectedAgent || agentName !== expectedAgent || sourceReceipt.instance !== instance
+      || sourceReceipt.executionBinding.resolution.id !== resolution.id || !sameDeployment
+      || canonicalJson(sourceReceipt.sourceIdentity) !== canonicalJson(expectedIdentity)
+      || canonicalJson(sourceReceipt.responsibleHuman) !== canonicalJson(expectedHuman)
+      || !expectedBinding || canonicalJson(sourceReceipt.binding) !== canonicalJson(expectedBinding)
+      || role === undefined || sourceReceipt.role !== role) {
+      throw oatsError("invalid-resolution", "captured source receipt differs from the verified resolution or lifecycle target");
+    }
+  }
+  const ids = Object.keys(inspected.record.dispatch.providerManifests);
+  if (event === "retire") ids.reverse();
+  const entries = ids.flatMap((id) => {
+    const capability = inspected.capabilities.get(id), declaration = hookDeclaration(capability?.manifest?.hooks?.[event]);
+    return declaration ? [{ id, capability, declaration }] : [];
+  });
+  if (sourceReceipt && !entries.some(({ id, declaration }) => id === sourceReceipt.binding.capability && declaration.inputs?.sourceReceipt?.version === 1)) throw oatsError("invalid-resolution", "explicit source receipt requires a matching opted-in hook owner");
+  objectAt(retryIntents, entries.map(({ id }) => id), []);
+  const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [], intents: {} };
+  const checkRoots = () => {
+    try { assertRoots?.(); }
+    catch (error) { error.capturedHooks = { meta: results.meta, intents: results.intents, failures: results.failures, order: results.order }; throw error; }
+  };
+  const envOwners = new Map(), envDeclarations = new Map(entries.map(({ id, capability }) => [id, {
+    names: new Set(capability.manifest.environment || []), namespaces: [...(capability.manifest.environmentNamespaces || [])],
+  }]));
+  const ready = [];
+  for (const entry of entries) {
+    const options = { deployment, resolution, action: { kind: "hook", capability: entry.id, name: event },
+      invocationTarget: { home, work: join(home, "work"), name: instance, agent: agentName },
+      ...(Object.hasOwn(priorMeta, entry.id) ? { priorReceipt: priorMeta[entry.id] } : {}) };
+    let staticLoaded;
+    try {
+      // Check every static source/target/approval/executable before any effects.
+      // Readiness is action-specific and receives its admitted intent below.
+      staticLoaded = loadCapturedAction(options, capturedDispatchCodecs(options, { admitting: true }));
+    } catch (error) {
+      const detail = String(error.message || error).slice(0, 200);
+      results.warnings.push(`${entry.id} ${event} hook unavailable: ${detail}`);
+      results.failures.push({ capability: entry.id, event, message: detail, required: entry.declaration.required });
+      if (event === "spawn" && entry.declaration.required) return results;
+      continue;
+    }
+    // Selected-input authority failures are not optional hook functionality.
+    // Derive ALL requested owner inputs before any provider check/effect.
+    const selectedReceipt = entry.declaration.inputs?.sourceReceipt ? capturedHookSourceReceipt(staticLoaded) : null;
+    if (sourceReceipt?.binding.capability === entry.id && canonicalJson(sourceReceipt) !== canonicalJson(selectedReceipt)) throw oatsError("invalid-resolution", "explicit receipt differs from the derived opted-in input");
+    ready.push({ ...entry, options, selectedReceipt, instanceFacts: staticLoaded.invocation.instance });
+  }
+  for (const { id, capability, declaration, options, selectedReceipt, instanceFacts } of ready) {
+    checkRoots(); results.order.push(id);
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) if (key.startsWith("OATS_") || key.startsWith("PI_AGENT_") || key === "PI_AGENTS_ROOT") delete env[key];
+    Object.assign(env, extraEnv, {
+      OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
+      OATS_CAPABILITY: id, OATS_CAPABILITY_ROOT: capability.manifest._dir, OATS_LAYER: capability.manifest.layer || "",
+      OATS_CONTEXT: deployment, OATS_WORKSPACE: deployment, OATS_LEVEL: deployment,
+      OATS_DEPLOYMENT: deployment, OATS_RESOLUTION: resolution.id,
+      OATS_CLI_BIN: realpathSync(join(PKG_ROOT, "bin", "oats.mjs")), OATS_SETTINGS: JSON.stringify(capability.settings),
+      OATS_META: JSON.stringify(priorMeta[id] || {}),
+    });
+    // Caller extras cannot nominate an input file, including when no owner
+    // selected that input. Only private wrappers below supply these variables.
+    for (const key of ["OATS_SOURCE_RECEIPT_FILE", "OATS_INVOCATION_CONTEXT_FILE", "OATS_BINDING_FILE"]) delete env[key];
+    let admission, started = false;
+    try {
+      admission = admitCapturedAction({ deployment, resolution, home, action: options.action,
+        ...(Object.hasOwn(priorMeta, id) ? { priorReceipt: priorMeta[id] } : {}),
+        ...(Object.hasOwn(retryIntents, id) ? { retryExecutionId: retryIntents[id] } : {}) });
+      results.intents[id] = admission.intent;
+      if (admission.replayed) {
+        // Never re-execute completed hooks to reconstruct runtime contributions.
+        if (!admission.replayable) throw oatsError("needs-configuration", "completed hook has non-replayable runtime contributions");
+        if (admission.receipt !== null) results.meta[id] = admission.receipt;
+        continue;
+      }
+      const admittedOptions = { ...options, intent: admission.intent, priorReceipt: admission.receipt };
+      const admitted = loadCapturedAction(admittedOptions, capturedDispatchCodecs(admittedOptions, { admitting: true }));
+      if (canonicalJson(admitted.invocation.instance) !== canonicalJson(instanceFacts)) throw oatsError("selection-changed", "hook incarnation changed after input preflight");
+      if (selectedReceipt && canonicalJson(capturedHookSourceReceipt(admitted)) !== canonicalJson(selectedReceipt)) throw oatsError("selection-changed", "selected source input changed after admission");
+      const loaded = loadCapturedDispatch(admittedOptions);
+      env.OATS_META = JSON.stringify(admission.receipt ?? {});
+      const invoke = (snapshotEnv = {}) => withCapturedInvocationContextFile(loaded.invocation, contextEnv => withCapturedBindingFile(loaded, bindingEnv => {
+        checkRoots();
+        beginCapturedIntent({ deployment, home, intent: admission.intent, action: options.action }); started = true;
+        return execFileSync(process.execPath, [loaded.executable.file, ...loaded.executable.args], { cwd: home, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000, killSignal: "SIGKILL", env: { ...env, ...snapshotEnv, ...contextEnv, ...bindingEnv } });
+      }));
+      const stdout = selectedReceipt ? withCapturedSourceReceiptFile(home, selectedReceipt, invoke) : invoke();
+      const lastLine = String(stdout).trim().split("\n").filter(Boolean).pop() || "{}";
+      let output = {}; try { output = JSON.parse(lastLine); } catch { /* non-JSON hook output is allowed */ }
+      if (output.meta) results.meta[id] = output.meta;
+      if (output.brief) results.briefs.push(`- ${output.brief}`);
+      if (output.warning) results.warnings.push(output.warning);
+      if (output.launch && typeof output.launch === "object") for (const [runtime, values] of Object.entries(output.launch)) results.launch[runtime] = `${results.launch[runtime] ? `${results.launch[runtime]} ` : ""}${values}`;
+      if (event === "launch" || (output.launch && typeof output.launch === "object" && Object.keys(output.launch).length) || (output.env && typeof output.env === "object" && Object.keys(output.env).length)) {
+        results.contributions.push({ capability: id, layer: capability.manifest.layer || null, level: deployment, settings: { ...capability.settings },
+          trust: { trusted: true, integrity: inspected.record.artifacts.capabilities[id].artifact.integrity.value },
+          launch: output.launch && typeof output.launch === "object" ? { ...output.launch } : {}, env: output.env && typeof output.env === "object" ? Object.keys(output.env).sort() : [] });
+      }
+      if (output.env !== undefined) {
+        if (event !== "spawn" && event !== "launch") throw new HookEnvironmentContractError(`${id} hook env is supported only for spawn and launch, not ${event}`);
+        Object.assign(results.env, validateHookEnvironment(id, output.env, envOwners, envDeclarations));
+      }
+      settleCapturedIntent({ deployment, home, intent: admission.intent, action: options.action, state: "completed",
+        receipt: results.meta[id] ?? admission.receipt,
+        replayable: !Object.keys(output.env || {}).length && !Object.keys(output.launch || {}).length });
+    } catch (error) {
+      // A nested private-snapshot cleanup failure must not erase a hook's
+      // already-observed provider receipt. Unwrap bounded owned error causes;
+      // never reinterpret that receipt as a successful/fully cleaned lifecycle.
+      let observed, reported;
+      const seen = new Set(); let cause = error;
+      while (cause && typeof cause === "object" && !seen.has(cause) && seen.size < 16) {
+        seen.add(cause);
+        if (cause.invocationCompleted && typeof cause.invocationResult === "string") { observed = cause.invocationResult; break; }
+        if (typeof cause.stdout === "string" || Buffer.isBuffer(cause.stdout)) { observed = cause.stdout; break; }
+        cause = cause.cause;
+      }
+      try {
+        const output = JSON.parse(String(observed ?? "").trim().split("\n").filter(Boolean).pop() || "{}");
+        if (output?.meta) results.meta[id] = output.meta;
+        if (typeof output?.warning === "string" && output.warning.trim()) reported = output.warning.trim();
+      } catch { /* non-JSON hook failure output is allowed */ }
+      let custodyError;
+      if (admission && !admission.replayed) {
+        try { settleCapturedIntent({ deployment, home, intent: admission.intent, action: options.action,
+          state: started ? "unconfirmed" : "blocked", receipt: results.meta[id] ?? admission.receipt }); }
+        catch (failure) { custodyError = failure; } // Possibly published: retain, never erase/re-admit.
+      }
+      const environment = error instanceof HookEnvironmentContractError;
+      const cleanup = error instanceof AggregateError;
+      const required = environment || cleanup || !!custodyError || declaration.required;
+      const detail = reported || String(error.message || error).slice(0, 200);
+      results.warnings.push(`${id} ${event} hook ${environment ? "environment contract " : ""}failed: ${detail}`);
+      results.failures.push({ capability: id, event, message: detail, required,
+        ...(started || custodyError ? { unconfirmed: true } : {}),
+        ...(custodyError ? { custody: { code: custodyError.code || "E_INTENT_CUSTODY", message: String(custodyError.message).slice(0, 200) } } : {}),
+        ...(environment ? { contract: "environment" } : {}),
+        ...(cleanup ? { contract: "snapshot-cleanup", unconfirmed: true, cleanup: { code: error.code || "E_HOOK_CLEANUP", message: String(error.message || error).slice(0, 200) } } : {}) });
+      if (event === "spawn" && required) return results;
+    } finally { checkRoots(); }
+  }
+  return results;
+}
+
 // ---------- agents ----------
 /** All local-agent base dirs readable for a root: the scope sibling (canonical)
  * plus legacy nested locations. */
@@ -5452,7 +5533,9 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
   const hookArgs = recipe.hooks?.launch?.[runtime] || "";
   const tail = `${cfgArgs ? ` ${cfgArgs}` : ""}${hookArgs ? ` ${hookArgs}` : ""}`;
   let cmdline;
-  if (runtime === "claude") {
+  if (isPiSdkHost(recipe)) {
+    cmdline = `${shq(executable)} ${piHostArgv(recipe, { home, sessionDir: capturedPiSessionDirectory(home) }).map(shq).join(" ")}`;
+  } else if (runtime === "claude") {
     cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
   } else if (runtime === "codex") {
     const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
@@ -5472,15 +5555,27 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
 /** Execution, not preview: mark pending before dispatch, then resolve native
  * storage inside the backend shell under the actual command environment.
  * The original executable/argv is exec'd unchanged after recording succeeds. */
-function nativeRecordCommand(command, home, runtime) {
+function nativeRecordCommand(command, home, runtime, onPrepared, prepare = prepareNativeStart) {
   const { tokens, binary } = parseLaunchCommand(command);
   const args = tokens.slice(binary + 1).filter(t => t.kind !== "prompt").map(t => t.value ?? t.text);
-  const id = prepareNativeStart(home, runtime);
+  const id = prepare(home, runtime);
+  onPrepared?.(id);
   const recorder = join(PKG_ROOT, "packages", "record", "bin", "record-native-start.mjs");
   const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(runtime)} ${shq(JSON.stringify(args))} && exec ${tokens.slice(binary).map(t => t.text).join(" ")}`;
   return `${tokens.slice(0, binary).map(t => t.text).join(" ")} /bin/sh -c ${shq(inner)}`;
 }
 
+/** Common tmux/Herdr completion wrapper for the exact captured Pi SDK profile.
+ * Save the actual native chain's shell status BEFORE the observer. Reuse the
+ * original command environment (including its ORIGINAL attempt); no new intent
+ * or process identity is constructed. The observer never replaces this status. */
+export function renderCapturedPiCompletion(command, executionCommand, { home, nativeRecordId }) {
+  const { tokens, binary } = parseLaunchCommand(command);
+  const prefix = tokens.slice(0, binary).map(token => token.text).join(" ");
+  const args = ["--oats-pi-record-exit", "1", "--home", home, "--native-record", nativeRecordId].map(shq).join(" ");
+  return `${executionCommand}; oats_start_status=$?; ${prefix} ${shq(process.execPath)} ${shq(PI_SDK_HOST)} ${args} --exit-status "$oats_start_status"`;
+}
+
 /** A recorded recipe this kernel understands, or a refusal before anything
  *  is observed or stopped. */
 export function assertLaunchRecipe(recipe, what) {
@@ -6744,6 +6839,7 @@ function sessionDirectoryGuard(home) {
     let meta;
     try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); } catch { return; } // ordinary receipt validation reports this
     if ((meta.work === "directory") !== (baseline.directoryWork === true)) throw oatsError("E_WORK_INSPECTION_FAILED", "directory work mode disagrees with independent session authority");
+    if (baseline.executionBinding && (meta.incarnationId !== baseline.incarnationId || canonicalJson(meta.executionBinding ?? null) !== canonicalJson(baseline.executionBinding))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "captured native baseline differs from current incarnation binding");
   };
   check();
   return check;
@@ -6953,13 +7049,14 @@ function retirementDisposableRoots(work, workMode, capabilities) {
   return roots;
 }
 
-function writeRetirementBaseline(home, work, mode, workMode, capabilities, runtime) {
+function writeRetirementBaseline(home, work, mode, workMode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
   if (mode === "directory") assertDirectoryRoots(home);
   const isWorktree = mode === "worktree";
   const status = isWorktree && existsSync(work) ? worktreeStatus(work) : "";
   const disposableReceipts = isWorktree ? retirementDisposableRoots(work, workMode, capabilities) : [];
   const baseline = {
     version: RETIRE_BASELINE_VERSION,
+    ...(incarnationId ? { incarnationId, executionBinding } : {}),
     ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryIdentity(home), work: directoryIdentity(work) } } : {}),
     home: realPathOrNearest(home),
     homeFingerprint: fingerprintTree(home, { excludeRoot: new Set(["work"]) }),
@@ -6973,7 +7070,7 @@ function writeRetirementBaseline(home, work, mode, workMode, capabilities, runti
   };
   const path = retirementBaselinePath(home);
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(baseline, null, 2) + "\n", { mode: 0o600 });
+  writeFileSync(path, JSON.stringify(baseline, null, 2) + "\n", { mode: 0o600, ...(exclusive ? { flag: "wx" } : {}) });
 }
 
 function nestedGitRoots(root) {
@@ -7431,12 +7528,251 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
  *  per-home lock and pending receipt across stop and launch, every preflight
  *  before the stop, a bounded SIGTERM with no escalation, factual receipts.
  *  Not a retirement: home, work, identity and notes stay. */
+/** Exact captured plan, existing native session transaction. This is dispatch
+ * custody, not provider enrollment or proof that a model finished its task. */
+export function startCapturedInstanceSession(home, options = {}) {
+  objectAt(options, ["deployment", "resolution", "backend", "task", "retryExecutionId", "restart", "env", "io", "stopGraceMs"], []);
+  if (options.stopGraceMs !== undefined && (!Number.isSafeInteger(options.stopGraceMs) || options.stopGraceMs < 1 || options.stopGraceMs > 300000)) throw oatsError("E_BAD_ARGS", "captured stop grace must be 1-300000 milliseconds");
+  let metadata = readCapturedInstanceMetadata(home);
+  home = metadata.home;
+  const binding = metadata.executionBinding, deployment = portableScope(options.deployment ?? binding.deployment), resolution = options.resolution ?? binding.resolution;
+  if (canonicalJson({ schemaVersion: 1, deployment, resolution }) !== canonicalJson(binding)) throw oatsError("invalid-resolution", "captured start selector differs from the owned home");
+  const original = readCapturedInstanceAuthority(deployment, home).row;
+  if (!original.nativeScaffold || canonicalJson(metadata.captured.nativeScaffold ?? null) !== canonicalJson(original.nativeScaffold)) throw oatsError("migration-required", "captured home lacks fresh native scaffold evidence; no history backfill was performed");
+  const latestSession = original.intents.findLast(intent => intent.action.kind === "session");
+  const heldLifecycle = (message, indexedStatus = original.status) => {
+    const error = oatsError("selection-changed", message);
+    error.home = home;
+    error.capturedCustody = { incarnationId: original.incarnationId, executionBinding: binding,
+      indexedStatus, metadataStatus: metadata.captured.lifecycle, held: true,
+      ...(latestSession ? { intent: { schemaVersion: 1, executionId: latestSession.executionId, incarnationId: original.incarnationId, attempt: latestSession.attempt }, receipt: latestSession.receipt } : {}) };
+    throw error;
+  };
+  const sourceStatus = metadata.captured.lifecycle;
+  if (original.status !== sourceStatus || !["spawned-launch-pending", "start-dispatched", "start-failed-cleanup-required"].includes(sourceStatus)) heldLifecycle("captured native start requires matching permitted metadata/index lifecycle");
+  if (sourceStatus === "start-failed-cleanup-required") {
+    if (!latestSession || options.retryExecutionId !== latestSession.executionId) heldLifecycle("native cleanup requires its exact saved retry, not a new request");
+    if (latestSession.state === "completed") heldLifecycle("completed native dispatch still has publication debt; explicit reconciliation is required");
+  }
+  let ownedState = sourceStatus;
+  const assertRoots = () => {
+    const row = assertCapturedInstanceCustody(original);
+    if (row.status !== ownedState) heldLifecycle("native start no longer owns lifecycle state", row.status);
+    const history = nativeHistoryPath(home), baseline = retirementBaselinePath(home);
+    for (const [key, path] of Object.entries({ historyRoot: dirname(history), history, retirementRoot: dirname(dirname(baseline)), baselines: dirname(baseline) })) {
+      if (!lstatSync(path).isDirectory() || canonicalJson(directoryIdentity(path)) !== canonicalJson(original.nativeScaffold.directories[key])) throw oatsError("integrity-drift", "native custody directory was replaced");
+    }
+    // The strict Pi record owner validates its private manifest via the pinned
+    // inspect/prepare/started APIs. Its approved expected-ID claim legitimately
+    // advances v1 -> v2 INSIDE prepare's assertAuthority callbacks. This callback
+    // guards kernel custody, not a duplicate/reentrant record codec. Freezing
+    // record-owned bytes to v1 here makes every valid Pi claim fail mid-write.
+    // Literal legacy manifest custody stays unchanged for other runtimes.
+    if (!piHost) {
+      const manifest = parseStrictJson(readPortableBytes(join(history, "history.json")));
+      if (canonicalJson(manifest) !== canonicalJson({ version: 1, home, completeHistory: true })) throw oatsError("integrity-drift", "native history scaffold authority changed");
+    }
+    const current = readCapturedInstanceMetadata(home);
+    assertCapturedSessionPlacement(current, backend, knownTargets);
+    const saved = parseStrictJson(readPortableBytes(baseline)), authority = runtimeAuthorityOf(saved);
+    if (saved.version !== RETIRE_BASELINE_VERSION || saved.home !== home || saved.incarnationId !== original.incarnationId
+      || canonicalJson(saved.executionBinding) !== canonicalJson(binding) || !authority) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "native baseline differs from captured incarnation");
+    if (authority.launched) {
+      const target = authority.sessionTarget ?? { backend: "tmux", ...authority.tmux };
+      validateCapturedSessionTarget(target, backend, current.instance);
+      if (backend.backend === "herdr" && !knownTargets.some(known => canonicalJson(known) === canonicalJson(target))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "native baseline target lacks indexed custody");
+    } else if (current.launched || sessionHistory.some(intent => intent.state === "completed" && intent.receipt?.target)) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "native launch history contradicts an unlaunched baseline");
+    if (current.launched !== authority.launched && !existsSync(join(home, ".oats-start-pending.json"))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "native launch-state mismatch lacks pending recovery custody");
+    return row;
+  };
+  const loaded = loadCapturedDispatch({ deployment, resolution, action: { kind: "compose" } });
+  const record = loaded.record, expectedAgent = record.subject.kind === "persistent" ? record.subject.soul.alias : record.subject.name;
+  const human = record.messagingChoice.enabled ? record.messagingChoice.privateKey.human : null;
+  if (metadata.agent !== expectedAgent || metadata.kind !== record.subject.kind || canonicalJson(metadata.responsibleHuman) !== canonicalJson(human)) throw oatsError("invalid-resolution", "native target differs from captured subject/human");
+  if (record.dispatch.composition?.mode !== "directory") throw oatsError("needs-configuration", "captured native start requires supported owned directory work");
+  if (loaded.approvals.some(item => !["approved", "not-required"].includes(item.status))) throw oatsError("approval-required", "captured native start needs every exact executable approval");
+  if (!record.dispatch.launch) throw oatsError("needs-configuration", "captured record has no explicit launch inputs");
+  if (record.dispatch.runtimePackages.length || applicableRequirements(record.dispatch.launch.runtime, [...loaded.capabilities.values()]).length) throw oatsError("needs-configuration", "required managed runtime roots/loader are not yet qualified; no current package discovery was used");
+  if ([...loaded.capabilities.values()].some(cap => cap.manifest.hooks?.launch) || original.intents.some(intent => intent.action.kind === "hook" && intent.action.name === "spawn" && !intent.replayable)) throw oatsError("needs-configuration", "captured native hook contribution refresh is not qualified");
+  const recipe = structuredClone(record.dispatch.launch);
+  if (recipe.executableResource) {
+    const resource = loaded.resources.get(recipe.executableResource);
+    if (!resource) throw oatsError("resolution-incomplete", "captured native entrypoint resource is missing");
+    const manifest = loaded.manifests.get(recipe.entrypoint.capability), specification = manifest?.commands?.[recipe.entrypoint.command];
+    if (typeof specification !== "string") throw oatsError("invalid-resolution", "retained native entrypoint is not declared");
+    const [script, ...declaredArgs] = specification.trim().split(/\s+/), declaredFile = capabilityExecutablePath(manifest, script);
+    if (!declaredFile || realpathSync(declaredFile) !== resource) throw oatsError("invalid-resolution", "native entrypoint resource differs from retained command");
+    if (declaredArgs.length) throw oatsError("needs-configuration", "native entrypoint arguments require a qualified captured adapter");
+    recipe.executable = resource;
+  } else if (recipe.executableResolvedFrom !== "explicit-host" || !isAbsolute(recipe.executable)) throw oatsError("needs-configuration", "native executable is neither a retained entrypoint nor an explicit host tool");
+  if (!recipe.executableResource && existsSync(recipe.executable)) {
+    const actual = realpathSync(recipe.executable), managed = join(deployment, ".agents");
+    if (actual === managed || actual.startsWith(`${managed}${sep}`)) throw oatsError("needs-configuration", "an OATS-managed executable needs its retained resource reference, not a host-tool escape");
+  }
+  const broken = checkLaunchExecutable(recipe.executable);
+  if (broken) throw oatsError("E_LAUNCH_EXECUTABLE", broken);
+  const piHost = isPiSdkHost(recipe);
+  if (recipe.runtime === "pi" && !piHost) throw oatsError("needs-configuration", "captured Pi requires the explicitly selected strict SDK host; a Pi CLI recipe was not reinterpreted");
+  if (recipe.args.length && !piHost) throw oatsError("needs-configuration", "native extra arguments require a qualified captured adapter; no flags were inferred or ignored");
+  const piProfile = piHost ? validatePiHostRecipe(recipe) : null; // refuse retained contributions before normalization
+  recipe.hooks = { launch: {}, env: {}, contributions: [] };
+  const piSessionDir = piHost ? capturedPiSessionDirectory(home) : null;
+  if (piHost) {
+    resolvePiSdkEntry(piProfile); // public export metadata only; no SDK/auth/model import
+    requireCapturedPiRecordSupport(); // refuse before admission/backend when guards are absent
+    inspectCapturedPiRoot(home, { incarnationId: original.incarnationId, sessionDir: piSessionDir });
+  }
+  const baseEnv = { ...(options.env || process.env) };
+  for (const key of Object.keys(baseEnv)) if (/^(OATS_|OAS_|PI_AGENT_)/.test(key) || key === "PI_AGENTS_ROOT") delete baseEnv[key];
+  const missing = missingLaunchEnvRefs(recipe.env, baseEnv);
+  if (missing.length) throw oatsError("E_LAUNCH_ENV_MISSING", "captured native environment references are unavailable");
+  const backend = Object.hasOwn(options, "backend") ? options.backend : metadata.captured.nativeBackend;
+  if (backend === undefined) throw oatsError("needs-configuration", "first captured native start needs an explicit backend endpoint");
+  validateCapturedSessionBackend(backend);
+  if (checkLaunchExecutable(backend.binary)) throw oatsError("E_LAUNCH_EXECUTABLE", "selected native backend executable is unavailable");
+  if (Object.hasOwn(metadata.captured, "nativeBackend") && canonicalJson(metadata.captured.nativeBackend) !== canonicalJson(backend)) throw oatsError("invalid-resolution", "native backend relocation requires separate qualified custody");
+  const sessionHistory = original.intents.filter(intent => intent.action.kind === "session");
+  const targetReceipts = sourceStatus === "start-failed-cleanup-required" ? sessionHistory.slice(-2) : sessionHistory.slice(-1);
+  const knownTargets = backend.backend === "herdr" ? targetReceipts.flatMap(intent => intent.receipt?.target?.backend === "herdr"
+    ? [validateCapturedSessionTarget(intent.receipt.target, backend, metadata.instance)] : []) : [];
+  const nativeTarget = backend.backend === "tmux" ? { backend: "tmux", session: backend.session, window: metadata.instance, socket: backend.socket }
+    : latestSession?.receipt?.target?.backend === "herdr" ? validateCapturedSessionTarget(latestSession.receipt.target, backend, metadata.instance) : undefined;
+  assertCapturedSessionPlacement(metadata, backend, knownTargets);
+  if (options.restart !== undefined && typeof options.restart !== "boolean") throw oatsError("invalid-declaration", "restart must be boolean");
+  const taskFile = join(home, "TASK.md");
+  if (options.task !== undefined && typeof options.task !== "string") throw oatsError("invalid-declaration", "native task must be explicit text");
+  const task = options.task === undefined ? decodeUtf8(readPortableBytes(taskFile)) : options.task;
+  canonicalJson(task, { maxBytes: 512 * 1024 });
+  if (task.includes("\0")) throw oatsError("invalid-declaration", "native task contains NUL");
+  if (piHost && !task.trim()) throw oatsError("E_PI_HOST_TASK", "captured Pi print requires a nonempty task");
+  const taskBytes = Buffer.from(task);
+  const assertCurriculum = () => {
+    assertRoots();
+    if (decodeUtf8(readPortableBytes(join(home, "AGENTS.md"))) !== loaded.composition.text
+      || !lstatSync(join(home, "CLAUDE.md")).isSymbolicLink() || readlinkSync(join(home, "CLAUDE.md")) !== "AGENTS.md"
+      || !lstatSync(join(home, "soul")).isSymbolicLink() || realpathSync(join(home, "soul")) !== dirname(loaded.resources.get(record.dispatch.composition.body))) throw oatsError("integrity-drift", "native curriculum differs from retained composition");
+    const actual = readdirSync(join(home, ".agents/skills")).sort(), expected = loaded.composition.skills.map(skill => skill.name).sort();
+    if (canonicalJson(actual) !== canonicalJson(expected)) throw oatsError("integrity-drift", "native skill inventory differs from retained composition");
+    for (const skill of loaded.composition.skills) if (canonicalJson(treeIntegrity(join(home, ".agents/skills", skill.name))) !== canonicalJson(treeIntegrity(skill.path))) throw oatsError("integrity-drift", "native skill bytes differ from retained composition");
+  };
+  assertCurriculum();
+  const action = { kind: "session", name: options.restart ? "restart" : "start" };
+  const input = { backend, taskIntegrity: { format: "oats.bytes.v1", value: `sha256-${createHash("sha256").update(taskBytes).digest("hex")}` } };
+  const pendingPath = join(home, ".oats-start-pending.json");
+  const makeCommand = (intent) => `OATS_DEPLOYMENT=${shq(deployment)} OATS_RESOLUTION=${shq(resolution.id)} OATS_AGENT=${shq(metadata.agent)} OATS_CLI_BIN=${shq(realpathSync(join(PKG_ROOT, "bin/oats.mjs")))} OATS_INCARNATION_ID=${shq(original.incarnationId)} OATS_EXECUTION_ID=${shq(intent.executionId)} OATS_EXECUTION_ATTEMPT=${shq(String(intent.attempt))} ${renderLaunchRecipe(recipe, { home, instance: metadata.instance })}`;
+  if (existsSync(pendingPath)) {
+    const pending = parseStrictJson(readPortableBytes(pendingPath)), ref = pending.capturedIntent;
+    validateIntentRef(ref);
+    if (typeof pending.nativeRecordId !== "string" || !/^[a-f0-9-]{36}$/.test(pending.nativeRecordId)) throw oatsError("invalid-resolution", "pending native history reference is invalid");
+    const evidence = parseStrictJson(readPortableBytes(join(nativeHistoryPath(home), `${pending.nativeRecordId}.json`)));
+    if (evidence.version !== (piHost ? 2 : 1) || evidence.id !== pending.nativeRecordId || evidence.home !== home || evidence.runtime !== recipe.runtime || !(piHost ? ["pending", "root-established", "started"] : ["pending", "started"]).includes(evidence.state)) throw oatsError("invalid-resolution", "pending native history differs from captured start");
+    if (piHost && (evidence.incarnationId !== original.incarnationId || canonicalJson(evidence.intent) !== canonicalJson(ref))) throw oatsError("invalid-resolution", "Pi native witness differs from the original admitted intent");
+    const prior = original.intents.find(intent => intent.executionId === ref?.executionId);
+    if (!prior || prior.action.kind !== "session" || latestSession.executionId !== pending.id || ref.incarnationId !== original.incarnationId || pending.id !== ref.executionId || ref.attempt > prior.attempt
+      || canonicalJson(pending.launch) !== canonicalJson(recipe) || pending.command !== makeCommand(ref)) throw oatsError("invalid-resolution", "pending native receipt is not this captured launch");
+    if (pending.phase === "allocating") {
+      if (backend.backend !== "herdr" || canonicalJson(pending.endpoint) !== canonicalJson(backend)) throw oatsError("invalid-resolution", "pending allocation endpoint differs from admitted backend");
+      const error = oatsError("E_SESSION_UNKNOWN", "native allocation outcome is unknown; retain the same intent and reconcile, never allocate again");
+      error.home = home; error.nativeCustody = { intent: ref, pendingPath, observed: prior.receipt, unconfirmed: true }; throw error;
+    }
+    validateCapturedSessionTarget(pending.target, backend, metadata.instance);
+    if (backend.backend === "herdr" && (!prior.receipt?.target || canonicalJson(prior.receipt.target) !== canonicalJson(pending.target))) throw oatsError("invalid-resolution", "pending Herdr target lacks matching indexed observation");
+  }
+  // Static target/curriculum/backend/task validation precedes provider code.
+  // This read-only inspection is not a provider-native enrollment grant.
+  for (const [slot, providerBinding] of Object.entries(record.bindings)) {
+    const capability = loaded.capabilities.get(providerBinding.capability), inspection = { kind: "inspect" };
+    const invocation = buildCapturedInvocationContext({ loaded: { ...loaded, capability }, action: inspection,
+      instance: { home, work: join(home, "work"), name: metadata.instance, agent: metadata.agent } });
+    const checked = runCapturedProviderBinding({ deployment, artifacts: record.artifacts, capability: capability.id, phase: "check", settings: capability.settings,
+      input: { binding: providerBinding, context: record.context, action: inspection, invocation } });
+    if (checked.status !== "ready") throw oatsError(checked.problems[0]?.code || "provider-not-qualified", `captured ${slot} provider is unavailable`);
+  }
+  assertCurriculum();
+  const admission = admitCapturedInstanceAction({ deployment, home, executionBinding: binding, capability: null, action, input, expectedStatus: sourceStatus,
+    ...(options.retryExecutionId !== undefined ? { retryExecutionId: options.retryExecutionId } : {}) });
+  if (admission.replayed) return { ...admission.receipt, intent: admission.intent, replayed: true };
+  let observed = null, pendingObservation = null;
+  try {
+    ownedState = "start-running";
+    setCapturedInstanceStatus(deployment, home, ownedState, { expectedStatus: sourceStatus });
+    beginCapturedIntent({ deployment, home, intent: admission.intent, action });
+    atomicWriteFileSync(taskFile, task, { assertRoots });
+    metadata = { ...metadata, backend: backend.backend,
+      ...(backend.backend === "tmux" ? { tmux: { session: nativeTarget.session, window: nativeTarget.window, socket: nativeTarget.socket } } : {}),
+      captured: { ...metadata.captured, nativeBackend: backend } };
+    atomicWriteFileSync(join(home, "instance.json"), canonicalJson(metadata), { assertRoots });
+    const plan = { recipe, command: makeCommand(admission.intent), runtime: recipe.runtime, model: recipe.model, yolo: recipe.yolo };
+    const exec = (binary, args, executionOptions) => {
+      assertCurriculum();
+      if (!readPortableBytes(taskFile).equals(taskBytes)) throw oatsError("integrity-drift", "native task changed after admission");
+      if (existsSync(pendingPath)) {
+        const pending = parseStrictJson(readPortableBytes(pendingPath));
+        if (pending.id === admission.intent.executionId) pendingObservation = { id: pending.id, startedAt: pending.startedAt,
+          ...(pending.target ? { target: pending.target } : {}), ...(pending.endpoint ? { endpoint: pending.endpoint } : {}), ...(pending.phase ? { phase: pending.phase } : {}),
+          ...(pending.nativeRecordId ? { nativeRecordId: pending.nativeRecordId } : {}), unconfirmed: true };
+      }
+      const env = { ...baseEnv };
+      if (backend.backend === "herdr") {
+        delete env.HERDR_SESSION; delete env.HERDR_SOCKET_PATH;
+        if (binary === backend.binary) {
+          if (executionOptions.env?.HERDR_SOCKET_PATH !== backend.socket) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "Herdr transport socket differs from admitted endpoint");
+          env.HERDR_SOCKET_PATH = backend.socket;
+        }
+      }
+      return (options.io?.exec || execFileSync)(backend.backend === "tmux" && binary === "tmux" ? backend.binary : binary, args, { ...executionOptions, env });
+    };
+    const observeTarget = (target, facts) => {
+      validateCapturedSessionTarget(target, backend, metadata.instance);
+      pendingObservation = { ...facts, target, unconfirmed: true };
+      knownTargets.push(target); assertRoots();
+      observeCapturedNativeTarget(original, admission.intent, pendingObservation);
+    };
+    observed = startInstanceSession(home, { restart: !!options.restart, ...(options.stopGraceMs === undefined ? {} : { stopGraceMs: options.stopGraceMs }), env: baseEnv,
+      io: { ...options.io, exec, strictHerdrTarget: backend.backend === "herdr" },
+      [CAPTURED_NATIVE_START]: { plan, intent: admission.intent, endpoint: backend, target: nativeTarget, observeTarget, assertRoots,
+        ...(piHost ? { prepareNativeRecord: () => {
+          assertCurriculum();
+          return prepareCapturedPiStart(home, { incarnationId: original.incarnationId, intent: admission.intent, sessionDir: piSessionDir, assertAuthority: assertRoots });
+        } } : {}) } });
+    assertRoots();
+    settleCapturedIntent({ deployment, home, intent: admission.intent, action, state: "completed", receipt: observed, replayable: true });
+    const next = readCapturedInstanceMetadata(home);
+    atomicWriteFileSync(join(home, "instance.json"), canonicalJson({ ...next, captured: { ...next.captured, lifecycle: "start-dispatched", nativeIntent: admission.intent } }), { assertRoots });
+    setCapturedInstanceStatus(deployment, home, "start-dispatched", { expectedStatus: ownedState });
+    ownedState = "start-dispatched";
+    return { ...observed, intent: admission.intent, incarnationId: original.incarnationId, dispatchAccepted: true };
+  } catch (error) {
+    let reportingFailure;
+    try { failCapturedNativeIntent(original, admission.intent, observed ?? pendingObservation ?? admission.receipt); ownedState = "start-failed-cleanup-required"; }
+    catch (failure) { reportingFailure = failure.code || "E_NATIVE_CUSTODY"; }
+    try {
+      assertRoots(); const current = readCapturedInstanceMetadata(home);
+      atomicWriteFileSync(join(home, "instance.json"), canonicalJson({ ...current, captured: { ...current.captured, lifecycle: "start-failed-cleanup-required", nativeIntent: admission.intent } }), { assertRoots });
+    } catch { /* never write/clean a replacement home */ }
+    error.home = home; error.nativeCustody = { intent: admission.intent, pendingPath, observed, pendingObservation, unconfirmed: true, ...(reportingFailure ? { reportingFailure } : {}) };
+    throw error;
+  }
+}
+
 export function restartInstanceSession(home, o = {}) { return startInstanceSession(home, { ...o, restart: true }); }
 export function startInstanceSession(home, o = {}) {
   if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session start needs an absolute instance home");
-  // Check the sibling receipt BEFORE resolving a possibly substituted home.
   if (existsSync(directoryRollbackPath(home))) throw oatsError("E_INSTANCE_RETIRING", `${home} has retained directory cleanup; restore and retire it before starting anything there`);
-  const checkRoots = sessionDirectoryGuard(home);
+  const directoryGuard = sessionDirectoryGuard(home);
+  if (!o[CAPTURED_NATIVE_START]) {
+    let metadata; try { metadata = parseStrictJson(readPortableBytes(join(home, "instance.json"))); } catch { /* legacy receipt validation reports unreadable metadata */ }
+    if (metadata?.executionBinding) {
+      const portableOptions = { ...o };
+      for (const key of ["model", "runtime", "launchConfig", "yolo"]) {
+        if (portableOptions[key] !== undefined) throw oatsError("E_BAD_ARGS", "captured start cannot replace its recorded runtime/model/configuration");
+        delete portableOptions[key]; // Legacy callers pass omitted options as undefined.
+      }
+      return startCapturedInstanceSession(home, portableOptions);
+    }
+  }
+  const capturedStart = o[CAPTURED_NATIVE_START];
+  const checkRoots = () => { directoryGuard(); capturedStart?.assertRoots(); };
   const realHome = realPathOrNearest(home);
   let originalHomeIdentity;
   try { originalHomeIdentity = directoryIdentity(realHome); } catch { /* missing home reported below */ }
@@ -7460,7 +7796,7 @@ export function startInstanceSession(home, o = {}) {
   // The independent receipt first (retire and session consult it), then the
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
-  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, runtime: newRuntime, yolo: newYolo, stop }, clearPending = true) => {
+  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, runtime: newRuntime, yolo: newYolo, stop, nativeRecordId }, clearPending = true) => {
     checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
@@ -7478,9 +7814,10 @@ export function startInstanceSession(home, o = {}) {
       ...(launch ? { launch } : {}), ...(newRuntime ? { runtime: newRuntime } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}) };
     if (backend === "herdr") { next.sessionTarget = target; delete next.tmux; }
     else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
-    writeJsonAtomic(metaPath, next);
-    if (clearPending) rmSync(pendingPath, { force: true });
-    return { instance: meta.instance, agent: meta.agent, home: realHome, runtime: next.runtime, backend, model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, ...(stop ? { stop } : {}) };
+    if (capturedStart) atomicWriteFileSync(metaPath, canonicalJson(next), { assertRoots: checkRoots });
+    else writeJsonAtomic(metaPath, next);
+    if (clearPending) { checkRoots(); rmSync(pendingPath, { force: true }); }
+    return { instance: meta.instance, agent: meta.agent, home: realHome, runtime: next.runtime, backend, model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
   };
   try { mkdirSync(lock); }
   catch (e) {
@@ -7526,11 +7863,15 @@ export function startInstanceSession(home, o = {}) {
         const exited = existsSync(exitedPath) && readFileSync(exitedPath, "utf8").trim() === pending.id;
         if (!exited) throw oatsError("E_SESSION_START_BUSY", `${basename(realHome)} is still starting; refresh its status before retrying`);
       }
+      if (capturedStart && pending.id === capturedStart.intent.executionId && (!st.present || st.state === "shell")) throw oatsError("E_SESSION_UNKNOWN", "captured retry cannot turn a missing/exited pending target into a duplicate launch; retain and reconcile its evidence");
       // Reconcile even an exited target: the independent baseline may
       // already name it while metadata still names the old allocation.
       const meta = readMeta();
       const done = record(meta, { ...pending, backend: pbackend, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
       if (st.present && st.state !== "shell") {
+        // Same logical captured request already dispatched: adopting it is the
+        // retry outcome, even for restart. Only a DISTINCT restart may continue.
+        if (capturedStart && pending.id === capturedStart.intent.executionId) return done;
         if (o.restart) { rmSync(pendingPath, { force: true }); }
         else {
           // The recovered target runs what the receipt says; a choice made
@@ -7545,9 +7886,10 @@ export function startInstanceSession(home, o = {}) {
     // 2. The ordinary gate and observation, all under the lock.
     const receipt = instanceSessionTarget(realHome);
     const meta = readMeta();
-    const runtime = meta.runtime;
+    const runtime = capturedStart?.plan.runtime || meta.runtime;
     if (!["pi", "claude", "codex"].includes(runtime)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `instance ${meta.instance || realHome} records runtime ${JSON.stringify(runtime)}, which this kernel cannot relaunch`);
-    const backend = meta.sessionTarget || meta.backend === "herdr" ? "herdr" : "tmux";
+    const backend = capturedStart ? capturedStart.endpoint.backend : (meta.sessionTarget || meta.backend === "herdr" ? "herdr" : "tmux");
+    if (capturedStart && receipt.target && (!capturedStart.target || canonicalJson(receipt.target) !== canonicalJson(capturedStart.target))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "independent endpoint differs from admitted native target");
     let command = meta.command;
     let model = meta.model || undefined;
     // What this start launches: the frozen command (optionally with another
@@ -7556,8 +7898,9 @@ export function startInstanceSession(home, o = {}) {
     // preflight happens here, before anything is observed or stopped.
     const selected = o.launchConfig !== undefined || o.runtime !== undefined || o.yolo !== undefined;
     const hasRecipe = meta.launch && typeof meta.launch === "object";
-    let launchPlan = null;
-    if (selected || hasRecipe) {
+    let launchPlan = capturedStart?.plan || null;
+    if (capturedStart) { command = launchPlan.command; model = launchPlan.model; }
+    else if (selected || hasRecipe) {
       // Every start of a home with a recipe (ordinary, model-only, or under a
       // selection) goes through the one planner: recipe shape, the recorded
       // or selected executable, references, capability contributions under
@@ -7583,7 +7926,8 @@ export function startInstanceSession(home, o = {}) {
     const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
     const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
     checkRoots(); // launch hooks/preparation have run; no backend has been observed
-    const planExtra = launchPlan ? { launch: launchPlan.recipe, runtime: launchPlan.runtime, yolo: launchPlan.yolo } : {};
+    const planExtra = launchPlan ? { launch: launchPlan.recipe, runtime: launchPlan.runtime, yolo: launchPlan.yolo,
+      ...(capturedStart ? { capturedIntent: capturedStart.intent } : {}) } : {};
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
     let serverGone = false;
@@ -7607,28 +7951,40 @@ export function startInstanceSession(home, o = {}) {
       if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
     }
     const startedAt = new Date().toISOString();
-    const id = randomUUID();
+    const id = capturedStart?.intent.executionId || randomUUID();
     checkRoots();
-    const executionCommand = nativeRecordCommand(command, realHome, launchPlan?.runtime || runtime);
-    const completedCommand = `${executionCommand}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
+    const executionCommand = nativeRecordCommand(command, realHome, launchPlan?.runtime || runtime,
+      capturedStart ? id => { planExtra.nativeRecordId = id; } : undefined, capturedStart?.prepareNativeRecord);
+    const completedCommand = capturedStart && isPiSdkHost(launchPlan?.recipe)
+      ? renderCapturedPiCompletion(command, executionCommand, { home: realHome, nativeRecordId: planExtra.nativeRecordId })
+      : `${executionCommand}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
     let reused = "new";
     if (backend === "herdr") {
-      if (!target) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `this never-launched Herdr home has no saved server endpoint; no tmux fallback was started`);
+      if (!target && !capturedStart) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `this never-launched Herdr home has no saved server endpoint; no tmux fallback was started`);
+      const base = capturedStart?.endpoint ?? { backend: "herdr", binary: target.binary, socket: target.socket, protocol: target.protocol };
       if (state.present) { reused = "pane"; }
       else {
-        const base = { backend: "herdr", binary: target.binary, socket: target.socket, protocol: target.protocol };
         try { herdrSnapshot(base, o.io); }
-        catch (e) { throw oatsError("E_SESSION_UNKNOWN", `Herdr server on ${base.socket} is not reachable, so nothing was started: ${e.message}`); }
-        target = allocateHerdr(base, { home: realHome, instance: meta.instance }, o.io);
+        catch (e) {
+          if (capturedStart) throw oatsError("E_SESSION_UNKNOWN", "selected Herdr endpoint is unavailable or incompatible; no fallback was started");
+          throw oatsError("E_SESSION_UNKNOWN", `Herdr server on ${base.socket} is not reachable, so nothing was started: ${e.message}`);
+        }
+        if (capturedStart) {
+          checkRoots();
+          writeJsonAtomic(pendingPath, { id, phase: "allocating", endpoint: base, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
+        }
+        try { target = allocateHerdr(base, { home: realHome, instance: meta.instance }, o.io); }
+        catch (e) { if (capturedStart) throw launchFailure("Herdr allocation", e); throw e; }
       }
+      if (capturedStart) capturedStart.observeTarget(target, { id, startedAt, nativeRecordId: planExtra.nativeRecordId });
       checkRoots();
       writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
       try { launchHerdr(target, `${paneEnvExports}cd ${shq(realHome)} && ${completedCommand}; exit "$oats_start_status"`, o.io); }
       catch (e) { throw launchFailure("Herdr", e); }
     } else {
-      const session = target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
-      const window = target?.window || meta.tmux?.window || meta.instance;
-      let socket = target?.socket || meta.tmux?.socket;
+      const session = capturedStart?.target.session ?? (target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION);
+      const window = capturedStart?.target.window ?? (target?.window || meta.tmux?.window || meta.instance);
+      let socket = capturedStart?.target.socket ?? (target?.socket || meta.tmux?.socket);
       const windowCmd = `${completedCommand}; exec "\${SHELL:-/bin/zsh}"`;
       // A fallback shell (no harness descendant) or a retained dead pane is
       // the agent's own pane: the command runs there, no other window touched.