@awebai/oats 0.23.2 → 0.24.1

package/bin/oats.mjs

@@ -23,11 +23,11 @@ import { enableTmuxMouse, tmuxConfigPath, tmuxMouseEnabled } from "../lib/tmux-c
 import {
   LAYERS, WORK_MODES, LEGACY_HOME_CAPABILITIES_DIR, OATS_LOCK_FILE, OATS_VERSION, OAS_SCOPE_REMEDY, RETIRED_CAPABILITIES, detectOasScopes, retiredCapabilityReason, configChain, configCapabilityEntries, manifestOperations,
   acquireCapability, restoreCapabilities, marketplaceCapabilities,
-  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityIntegrity, capabilityTrust, capabilityExecutablePath,
-  readCapabilityLocks, writeCapabilityLock,
+  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityIntegrity, capabilityTrust, capabilityExecutablePath, activateCapturedScaffold, loadCapturedDispatch, inspectPortableOnboarding, prepareCapturedComposition, resolveCapturedHelper, capturedNativeSessionAvailability, scaffoldCapturedInstance, startCapturedInstanceSession, withCapturedBindingFile, withCapturedInvocationContextFile,
+  readCapabilityLocks, writeCapabilityLock, admitCapturedAction, beginCapturedIntent, settleCapturedIntent,
   parsePackageSource, inspectGitSourceRoot, acquirePackage, restorePackages, listInstalledPackages, readPackageLocks, readLockedConfigTemplates,
   officialCapabilityPackage, officialPackageCatalog,
-  approveCapability, updatePackage, removePackage, migrateLegacyLock, applyLegacyLockMigration,
+  approveCapability, approveAvailableCapability, updatePackage, removePackage, migrateLegacyLock, applyLegacyLockMigration,
   packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir, installedCapabilitiesDir, ownedCapabilitiesDir, loadPackageManifestAt,
   resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
   findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, listCapabilityAgents, workspaceOf,
@@ -46,9 +46,18 @@ import { parseEnvelopeText, scheduleScopeOf, listSchedules, describe as describe
 import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
 import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
 
+import { capturedSelector } from "../lib/captured-selector.mjs";
+import { inspectCapturedPiOutcome } from "../lib/captured-pi-host.mjs";
+import { readCapturedResolution } from "../lib/captured-resolutions.mjs";
+import { readPortablePreparationRequest } from "../lib/portable-onboarding-request.mjs";
+import { portableScope } from "../lib/portable-state.mjs";
+import { CAPTURED_OPERATION_TIMEOUT_MS, runCapturedOperationProcess } from "../lib/captured-operation-process.mjs";
+import { approveCapturedCapability } from "../lib/artifact-approvals.mjs";
+
 const args = process.argv.slice(2);
-const cmd = args[0];
+let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
+const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "operation", "soul", "launch-config", "experimental", "init", "inject", "install", "list", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
@@ -86,6 +95,342 @@ const CLI_BIN = realpathSync(fileURLToPath(import.meta.url));
 const jsonFail = (code, message, details) => { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message), ...(details !== undefined ? { details } : {}) } })); process.exit(1); };
 const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result })); };
 
+function inspectOnboardingCmd() {
+  const fail = (code, message) => JSON_MODE ? jsonFail(code, message) : die(message);
+  let file;
+  for (let index = 1; index < args.length; index++) {
+    if (args[index] === "--json") continue;
+    if (args[index] !== "--request" || file !== undefined || !args[index + 1] || args[index + 1].startsWith("--")) fail("E_BAD_ARGS", "source inspection accepts one --request <absolute-json> and --json only");
+    file = args[++index];
+  }
+  try {
+    const input = readPortablePreparationRequest({ file });
+    const result = inspectPortableOnboarding(input);
+    if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+  } catch (error) { fail(error.code || "E_INSPECT_FAILED", error.message); }
+}
+
+function prepareCmd() {
+  const fail = (code, message, details) => JSON_MODE ? jsonFail(code, message, details) : die(message);
+  const values = new Map(), allowed = new Set(["request", "dir", "source", "revision", "export", "alias", "workspace", "workspace-revision", "work"]);
+  for (let index = 1; index < args.length; index++) {
+    if (args[index] === "--json") continue;
+    const key = args[index].startsWith("--") ? args[index].slice(2) : "";
+    if (!allowed.has(key) || values.has(key) || !args[index + 1] || args[index + 1].startsWith("--")) fail("E_BAD_ARGS", "prepare needs unique named source/context arguments; use prepare --help");
+    values.set(key, args[++index]);
+  }
+  try {
+    let input;
+    if (values.has("request")) {
+      // The shared leaf owns request bytes/exclusivity; this router alone owns
+      // argv and has already refused explicit captured selectors.
+      input = readPortablePreparationRequest({ file: values.get("request"),
+        inputFlags: Object.fromEntries([...values].filter(([key]) => key !== "request")) });
+    } else {
+      const deployment = values.get("dir"), alias = values.get("alias"), source = values.get("source");
+      if (!deployment || !isAbsolute(deployment) || !alias) fail("E_BAD_ARGS", "prepare needs --dir <absolute deployment> and --alias <name>");
+      if (source ? !values.get("revision") || !values.get("export") : !values.get("workspace") || values.has("revision") || values.has("export")) fail("E_BAD_ARGS", "choose a complete source/revision/export reference or a workspace-advertised alias");
+      if (values.has("workspace-revision") && !values.has("workspace")) fail("E_BAD_ARGS", "--workspace-revision requires --workspace");
+      const origin = { kind: "operator", document: { kind: "operator", id: "oats-prepare" }, pointer: "/source" };
+      input = { deployment, source: source ? { source, revision: values.get("revision"), soul: values.get("export"), alias } : alias, origin,
+        ...(values.has("work") ? { mode: values.get("work") } : {}),
+        ...(values.has("workspace") ? { workspace: { source: values.get("workspace"), origin: { ...origin, pointer: "/workspace" },
+          ...(values.has("workspace-revision") ? { revision: values.get("workspace-revision") } : {}) } } : {}) };
+    }
+    // Pass the whole request to the one public validator/resolver. Unknown
+    // fields are refused there, never filtered or filled from ambient state.
+    const result = prepareCapturedComposition(input);
+    if (!result.resolution) fail("needs-configuration", "preparation is incomplete; no executable resolution was published", result);
+    if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+  } catch (error) { fail(error.code || "E_PREPARE_FAILED", error.message); }
+}
+
+/** Run one provider operation from immutable captured authority. A home is an
+ * explicit target only: its stored binding must name this exact record. */
+function capturedOperation(selector, load, bail) {
+  if (args[1] !== "run") bail("E_USAGE", "usage: oats operation run <layer>:<name> --deployment <abs> --resolution <id> [--home <abs>] [--arg k=v ...] [--retry-intent <saved-id>] [--json]");
+  const address = args[2], match = typeof address === "string" ? OPERATION_ADDRESS_RE.exec(address) : null;
+  if (!match) bail("E_BAD_ARGS", `operation address must be <layer>:<name> with layer one of ${LAYERS.join(", ")} (got ${JSON.stringify(address)})`);
+  const [, slot, name] = match, given = Object.create(null);
+  let home, retryExecutionId;
+  for (let index = 3; index < args.length; index++) {
+    const token = args[index];
+    if (token === "--json") continue;
+    if (token === "--home") {
+      const value = args[++index];
+      if (home !== undefined || !value || value.startsWith("--") || !isAbsolute(value)) bail("E_BAD_ARGS", "--home needs one absolute instance home");
+      home = resolve(value); continue;
+    }
+    if (token === "--retry-intent") {
+      const value = args[++index];
+      if (retryExecutionId !== undefined || !value || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) bail("E_BAD_ARGS", "--retry-intent requires one saved executionId");
+      retryExecutionId = value; continue;
+    }
+    if (token === "--arg") {
+      const value = args[++index], eq = value?.indexOf("=") ?? -1;
+      if (eq < 1) bail("E_BAD_ARGS", "--arg expects name=value");
+      const key = value.slice(0, eq);
+      if (Object.hasOwn(given, key)) bail("E_BAD_ARGS", `duplicate operation arg ${JSON.stringify(key)}`);
+      given[key] = value.slice(eq + 1); continue;
+    }
+    bail("E_BAD_ARGS", `unsupported captured operation argument ${JSON.stringify(token)}`);
+  }
+  let meta;
+  if (home) {
+    const metaFile = join(home, "instance.json");
+    if (!existsSync(metaFile)) bail("E_SESSION_UNKNOWN", `${home} is not an OATS instance home (no instance.json)`);
+    try { meta = JSON.parse(readFileSync(metaFile, "utf8")); } catch (error) { bail("E_SESSION_UNKNOWN", `${metaFile}: ${error.message}`); }
+    if (!meta || typeof meta !== "object" || Array.isArray(meta) || typeof meta.instance !== "string" || !meta.instance) bail("E_SESSION_UNKNOWN", `${metaFile}: invalid instance metadata`);
+    const binding = meta.executionBinding;
+    if (!binding) bail("migration-required", `${home} has no captured executionBinding; current configuration was not used`);
+    if (binding.schemaVersion !== 1 || typeof binding.deployment !== "string" || !isAbsolute(binding.deployment)
+      || realOrResolved(binding.deployment) !== realOrResolved(selector.deployment)
+      || binding.resolution?.schemaVersion !== 1 || binding.resolution.id !== selector.resolution.id) {
+      bail("E_HOME_MISMATCH", `${home} is not bound to captured resolution ${selector.resolution.id} in ${selector.deployment}`);
+    }
+  }
+  // Inspect is static: validate target and arguments before the action load runs
+  // the provider's mutable readiness check.
+  const inspected = load({ kind: "inspect" }), providerId = inspected.record.bindings[slot]?.capability;
+  const provider = providerId ? inspected.manifests.get(providerId) : undefined;
+  if (!provider) bail("capability-not-selected", `no captured ${slot} provider is selected`);
+  const operation = manifestOperations(provider).find((entry) => entry.name === name);
+  if (!operation) bail("operation-not-found", "captured provider does not declare this operation");
+  if (operation.context === "home" && !meta) bail("E_OPERATION_UNAVAILABLE", `${address} runs in an instance home; pass --home <abs>`);
+  if (operation.context === "scope" && meta) bail("E_BAD_ARGS", `${address} is a scope operation and does not accept --home`);
+  const declared = new Map(operation.args.map((entry) => [entry.name, entry]));
+  for (const key of Object.keys(given)) if (!declared.has(key)) bail("E_BAD_ARGS", `${address} takes no arg ${JSON.stringify(key)} (declared: ${[...declared.keys()].join(", ") || "none"})`);
+  for (const entry of operation.args) if (entry.required && given[entry.name] === undefined) bail("E_BAD_ARGS", `${address} needs --arg ${entry.name}=<value>: ${entry.description || "required"}`);
+  const action = { kind: "operation", slot, name };
+  const argFlags = operation.args.flatMap((entry) => given[entry.name] === undefined ? [] : [entry.flag, given[entry.name]]), cwd = home || selector.deployment;
+  if (operation.kind === "action" && !home) bail("admission-required", "scope mutation has no qualified incarnation/admission path; use an instance-scoped operation");
+  if (retryExecutionId !== undefined && operation.kind !== "action") bail("E_BAD_ARGS", "read-only operations do not retry mutation intents");
+  const admission = operation.kind === "action" ? admitCapturedAction({ deployment: selector.deployment, resolution: selector.resolution, home, action, input: { arguments: argFlags },
+    ...(retryExecutionId !== undefined ? { retryExecutionId } : {}) }) : null;
+  let settlement;
+  const admittedBail = (code, message, details) => bail(code, message, { ...details, ...(admission ? { intent: admission.intent } : {}),
+    ...(settlement ? { settlement, unconfirmed: settlement.state === "unconfirmed" } : {}) });
+  if (admission?.replayed) {
+    settlement = { state: "completed", receipt: admission.receipt };
+    if (!admission.replayable) admittedBail("needs-configuration", "completed operation cannot replay its retained outcome");
+    finishOperation({ r: { status: 0, stdout: JSON.stringify(admission.receipt) }, bail: admittedBail, address, provider, op: operation, argFlags, cwd, home, meta, intent: admission.intent }); return;
+  }
+  let loaded;
+  try { loaded = load(action, { invocationTarget: meta ? { home, work: join(home, "work"), name: meta.instance, agent: meta.agent } : null,
+    ...(admission ? { intent: admission.intent, priorReceipt: admission.receipt } : {}) }); }
+  catch (error) {
+    if (admission) {
+      settleCapturedIntent({ deployment: selector.deployment, home, intent: admission.intent, action, state: "blocked", receipt: admission.receipt });
+      settlement = { state: "blocked", receipt: admission.receipt };
+    }
+    admittedBail(error.code || "provider-unavailable", error.message);
+  }
+  const { capability, executable } = loaded;
+  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, {
+    OATS_DEPLOYMENT: selector.deployment, OATS_RESOLUTION: selector.resolution.id,
+    OATS_CAPABILITY: capability.id, OATS_CAPABILITY_ROOT: capability.manifest._dir,
+    OATS_SETTINGS: JSON.stringify(capability.settings), OATS_CLI_BIN: CLI_BIN,
+    OATS_OPERATION: address, OATS_CONTEXT: selector.deployment, OATS_LEVEL: selector.deployment,
+    OATS_WORKSPACE: selector.deployment,
+  });
+  if (meta) Object.assign(env, { OATS_INSTANCE: meta.instance, OATS_INSTANCE_HOME: home, OATS_HOME: home,
+    PI_AGENT_INSTANCE: meta.instance, PI_AGENT_HOME: home, ...(meta.agent ? { OATS_AGENT: meta.agent } : {}) });
+  const invocation = loaded.invocation;
+  let child, cleanupError, started = false;
+  try {
+    child = withCapturedInvocationContextFile(invocation, contextEnv => withCapturedBindingFile(loaded, bindingEnv => {
+      if (admission) { beginCapturedIntent({ deployment: selector.deployment, home, intent: admission.intent, action }); started = true; }
+      return runCapturedOperationProcess({ file: executable.file, args: [...executable.args, ...argFlags, "--json"], cwd, env: { ...env, ...contextEnv, ...bindingEnv } });
+    }));
+  } catch (error) {
+    if (!error?.invocationCompleted) {
+      if (admission) {
+        settleCapturedIntent({ deployment: selector.deployment, home, intent: admission.intent, action, state: started ? "unconfirmed" : "blocked", receipt: admission.receipt });
+        settlement = { state: started ? "unconfirmed" : "blocked", receipt: admission.receipt };
+      }
+      admittedBail(error.code || "E_OPERATION_RESULT", error.message, { unconfirmed: started });
+    }
+    child = error.invocationResult; cleanupError = error;
+  }
+  if (admission) {
+    let envelope; try { envelope = JSON.parse(String(child.stdout || "").trim()); } catch { /* unconfirmed below */ }
+    const completed = !cleanupError && !child.error && child.status === 0 && envelope?.schemaVersion === 1 && envelope.ok === true;
+    const state = completed ? "completed" : "unconfirmed", receipt = envelope ?? parseEnvelopeText(String(child.stdout || "")) ?? admission.receipt;
+    try {
+      settleCapturedIntent({ deployment: selector.deployment, home, intent: admission.intent, action, state, receipt, replayable: completed });
+      settlement = { state, receipt };
+    }
+    catch (error) { admittedBail("E_OPERATION_RESULT", "operation ran but outcome custody could not be confirmed", { unconfirmed: true, envelope, custody: { code: error.code, message: error.message } }); }
+  }
+  finishOperation({ r: child, bail: admittedBail, address, provider: capability.manifest, op: operation, argFlags, cwd, home, meta, cleanupError, settlement, ...(admission ? { intent: admission.intent } : {}) });
+}
+
+/** Fresh explicit captured scaffold + spawn hooks. Placement is supplied by
+ * the operator; launch and non-directory work remain unsupported. */
+function capturedSpawn(selector, load, bail) {
+  const subject = args[1]; let home; let noLaunch = false;
+  if (!subject || subject.startsWith("-")) bail("E_BAD_ARGS", "captured spawn needs the retained subject name");
+  for (let index = 2; index < args.length; index++) {
+    const token = args[index];
+    if (token === "--json") continue;
+    if (token === "--no-launch") { if (noLaunch) bail("E_BAD_ARGS", "duplicate --no-launch"); noLaunch = true; continue; }
+    if (token === "--home") {
+      const value = args[++index];
+      if (home !== undefined || !value || value.startsWith("--") || !isAbsolute(value)) bail("E_BAD_ARGS", "--home needs one absolute new instance home");
+      home = resolve(value); continue;
+    }
+    bail("E_BAD_ARGS", `unsupported captured spawn argument ${JSON.stringify(token)}`);
+  }
+  if (!home || !noLaunch) bail("E_BAD_ARGS", "captured spawn currently requires --home <absolute new home> and --no-launch");
+  const inspected = load({ kind: "inspect" }), expected = inspected.record.subject.kind === "persistent" ? inspected.record.subject.soul.alias : inspected.record.subject.name;
+  if (subject !== expected) bail("E_HOME_MISMATCH", `captured resolution subject is ${expected}, not ${subject}`);
+  const scaffold = scaffoldCapturedInstance({ deployment: selector.deployment, resolution: selector.resolution, home, instance: basename(home) });
+  let activated;
+  try {
+    activated = activateCapturedScaffold({ deployment: selector.deployment, resolution: selector.resolution, home,
+      extraEnv: process.env.OATS_HOME_DIR ? { OATS_HOME_DIR: process.env.OATS_HOME_DIR } : {} });
+  } catch (error) {
+    if (error?.home) bail(error.code || "E_SPAWN_FAILED", error.message, { home: error.home, cleanupRequired: true, failures: error.provenance || [],
+      ...(error.capturedCustody ? { unconfirmed: true, custody: error.capturedCustody } : {}) });
+    throw error;
+  }
+  const result = { ...scaffold, hooksPending: activated.hooksPending, cleanupRequired: activated.cleanupRequired, launchPending: true,
+    hookIntents: activated.hooks.intents, hookOrder: activated.hooks.order, warnings: activated.hooks.warnings };
+  if (JSON_MODE) jsonOk(result); else console.log(`Scaffolded ${result.instance} at ${result.home}; ${result.hooksPending ? "captured hook custody requires retry/reconciliation" : "captured hooks complete"}, launch pending`);
+}
+
+/** Native continuation of an already owned captured home. A helper selector is
+ * an exact edge from the SOURCE record, not a name/current-config resolver. */
+function capturedSession(selector, bail) {
+  const inspecting = args[1] === "inspect";
+  if (!["start", "restart", "inspect"].includes(args[1])) bail("unsupported-action", "captured session supports start/restart or explicit Pi outcome inspect; no current-context fallback was used");
+  const values = new Map(), allowed = new Set(inspecting ? ["home", "helper", "native-record"] : ["home", "helper", "request", "retry-intent"]);
+  for (let index = 2; index < args.length; index++) {
+    if (args[index] === "--json") continue;
+    const key = args[index].startsWith("--") ? args[index].slice(2) : "", value = args[index + 1];
+    if (!allowed.has(key) || values.has(key) || !value || value.startsWith("--")) bail("E_BAD_ARGS", "captured session needs unique named home/helper/request/retry arguments");
+    values.set(key, value); index++;
+  }
+  const home = values.get("home"), retry = values.get("retry-intent");
+  if (!home || !isAbsolute(home) || resolve(home) !== home || home.includes("\0")) bail("E_BAD_ARGS", "captured session needs a normalized absolute --home");
+  if (retry !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(retry)) bail("E_BAD_ARGS", "--retry-intent requires one saved executionId");
+  if (inspecting && !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(values.get("native-record") ?? "")) bail("E_BAD_ARGS", "captured Pi outcome inspect requires one explicit --native-record UUID");
+  const sourceExecutionBinding = { schemaVersion: 1, deployment: portableScope(selector.deployment), resolution: selector.resolution };
+  // Pure retained-subject check, before request files, provider or native calls.
+  // Dedicated helper IDs remain valid for scaffolding, not edge-less dispatch.
+  if (!values.has("helper") && readCapturedResolution(sourceExecutionBinding.deployment, sourceExecutionBinding.resolution).subject.kind === "helper") {
+    bail("helper-not-selected", "captured helper session needs SOURCE selectors plus --helper EXACT_SOURCE_HELPER_KEY");
+  }
+  // Reuse the same bounded strict object-file transport. Preparation and native
+  // request schemas remain separate; reject unknown fields before projection.
+  let request = {};
+  if (values.has("request")) {
+    const input = readPortablePreparationRequest({ file: values.get("request") });
+    if (input.schemaVersion !== 1 || Object.keys(input).some(key => !["schemaVersion", "backend", "task", "stopGraceMs"].includes(key))) bail("E_BAD_ARGS", "native request must be version1 with only backend/task/stopGraceMs");
+    if (Object.hasOwn(input, "backend") && (!input.backend || typeof input.backend !== "object" || Array.isArray(input.backend))) bail("E_BAD_ARGS", "a supplied native backend must be an explicit object, not omission");
+    const { schemaVersion, ...fields } = input; request = fields;
+  }
+  const helperSelection = values.has("helper") ? resolveCapturedHelper({ executionBinding: sourceExecutionBinding, helper: values.get("helper") }) : null;
+  const executionBinding = helperSelection?.executionBinding ?? sourceExecutionBinding;
+  try {
+    if (inspecting) {
+      const outcome = inspectCapturedPiOutcome(home, { ...executionBinding, nativeRecordId: values.get("native-record") });
+      const result = { outcome, executionBinding, ...(helperSelection ? { sourceExecutionBinding: helperSelection.sourceExecutionBinding, helper: helperSelection.helper } : {}) };
+      if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const native = startCapturedInstanceSession(home, { ...request, deployment: executionBinding.deployment, resolution: executionBinding.resolution,
+      restart: args[1] === "restart", ...(retry !== undefined ? { retryExecutionId: retry } : {}) });
+    const result = { ...native, executionBinding, ...(helperSelection ? { sourceExecutionBinding: helperSelection.sourceExecutionBinding, helper: helperSelection.helper } : {}) };
+    if (JSON_MODE) jsonOk(result); else console.log(`${result.replayed ? "Replayed captured dispatch receipt for" : "Dispatched captured native session for"} ${home}`);
+  } catch (error) {
+    bail(error.code || "E_SESSION_START_FAILED", error.message, { home: error.home ?? home, executionBinding,
+      ...(helperSelection ? { sourceExecutionBinding: helperSelection.sourceExecutionBinding, helper: helperSelection.helper } : {}),
+      ...(error.capturedCustody ? { custody: error.capturedCustody } : {}),
+      ...(error.nativeCustody ? { unconfirmed: true, nativeCustody: error.nativeCustody } : {}) });
+  }
+}
+
+/** Exact-selector dispatch enters before any current-context resolver. Its
+ * child receives the same selector, never an invoking agent's ambient identity. */
+function capturedCommand(selector) {
+  const fail = (code, message, details) => JSON_MODE ? jsonFail(code, message, details) : die(message);
+  try {
+    const end = args.indexOf("--"), head = end < 0 ? args : args.slice(0, end);
+    const permitsHome = cmd === "operation" || cmd === "spawn" || cmd === "session";
+    const forbiddenContext = permitsHome ? ["--dir", "--server", "--soul", "--agents-root"] : ["--dir", "--home", "--server", "--soul", "--agents-root"];
+    if (head.some((arg) => forbiddenContext.includes(arg.split("=")[0]))) {
+      fail("E_BAD_ARGS", "captured selectors cannot be mixed with current-context selectors");
+    }
+    if (selector.artifactSet !== undefined) {
+      if (cmd !== "trust" || !args[1] || args[1].startsWith("-") || args.slice(2).some((arg) => arg !== "--json")) fail("E_BAD_ARGS", "artifact-set selectors support only explicit trust of one capability");
+      const result = approveAvailableCapability(selector.deployment, selector.artifactSet, args[1], {
+        kind: "operator", document: { kind: "operator", id: "oats-trust-artifact-set" }, pointer: "/capability",
+      });
+      if (JSON_MODE) jsonOk(result); else console.log(`${args[1]}: ${result.status}`);
+      return;
+    }
+    const target = { deployment: selector.deployment, resolution: selector.resolution };
+    const load = (action, extra = {}) => loadCapturedDispatch({ ...target, action, ...extra });
+    if (cmd === "inspect") {
+      let helperKey;
+      for (let index = 1; index < args.length; index++) {
+        if (["--json", "--composition"].includes(args[index])) continue;
+        if (args[index] !== "--helper" || helperKey !== undefined || !args[index + 1] || args[index + 1].startsWith("--")) fail("E_BAD_ARGS", "captured inspect accepts --json, --composition and one --helper <exact-map-key>");
+        helperKey = args[++index];
+      }
+      const helperSelection = helperKey === undefined ? null : resolveCapturedHelper({ executionBinding: { schemaVersion: 1, ...target }, helper: helperKey });
+      const selected = helperSelection?.executionBinding ?? target;
+      const loaded = loadCapturedDispatch({ deployment: selected.deployment, resolution: selected.resolution, action: { kind: args.includes("--composition") ? "compose" : "inspect" } });
+      const result = { resolution: loaded.resolution, capture: loaded.record.capture, nativeSession: capturedNativeSessionAvailability(),
+        ...(helperSelection ? { helperSelection } : {}),
+        capabilities: [...loaded.capabilities.values()].map(({ id, manifest }) => ({ id, version: manifest.version,
+          approval: loaded.approvals.find((entry) => entry.artifact.capability === id).status })),
+        helpers: Object.entries(loaded.record.helpers).map(([key, resolution]) => ({ key, resolution })),
+        hasComposition: !!loaded.record.dispatch.composition,
+        ...(loaded.composition ? { composition: loaded.composition } : {}) };
+      if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (cmd === "trust") {
+      if (!args[1] || args[1].startsWith("-") || args.slice(2).some((arg) => arg !== "--json")) fail("E_BAD_ARGS", "captured trust needs one capability ID");
+      load({ kind: "inspect" }); // complete manifest validation before approval
+      const result = approveCapturedCapability(selector.deployment, selector.resolution, args[1], {
+        kind: "operator", document: { kind: "operator", id: "oats-trust" }, pointer: "/capability",
+      });
+      if (JSON_MODE) jsonOk(result); else console.log(`${args[1]}: ${result.status}`);
+      return;
+    }
+    if (cmd === "operation") { capturedOperation(selector, load, fail); return; }
+    if (cmd === "spawn") { capturedSpawn(selector, load, fail); return; }
+    if (cmd === "session") { capturedSession(selector, fail); return; }
+    if (!cmd || cmd.startsWith("-") || KERNEL_COMMANDS.has(cmd)) fail("unsupported-action", "this kernel command has not yet adopted captured selectors; no current-context fallback was used");
+    if (!args[1] || args[1] === "--json" || head.some((arg) => HELP_WORDS.has(arg))) {
+      const loaded = load({ kind: "inspect" });
+      const matches = [...loaded.manifests.values()].filter((manifest) => manifest.command === cmd);
+      if (matches.length !== 1) fail("capability-not-selected", "captured command namespace is absent or ambiguous");
+      const result = { capability: matches[0].capability, commands: Object.keys(matches[0].commands || {}), help: "manifest only; no executable ran" };
+      if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const loaded = load({ kind: "command", namespace: cmd, name: args[1] });
+    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, { OATS_DEPLOYMENT: selector.deployment, OATS_RESOLUTION: selector.resolution.id,
+      OATS_CAPABILITY: loaded.capability.id, OATS_CAPABILITY_ROOT: loaded.capability.manifest._dir,
+      OATS_SETTINGS: JSON.stringify(loaded.capability.settings),
+      OATS_CLI_BIN: CLI_BIN, OATS_CONTEXT: selector.deployment, OATS_LEVEL: selector.deployment });
+    const forwarded = args.slice(2); if (forwarded[0] === "--") forwarded.shift();
+    const child = withCapturedInvocationContextFile(loaded.invocation, contextEnv => withCapturedBindingFile(loaded, bindingEnv => spawnSync(process.execPath, [loaded.executable.file, ...loaded.executable.args, ...forwarded], {
+      cwd: selector.deployment, env: { ...env, ...contextEnv, ...bindingEnv }, stdio: "inherit",
+    })));
+    if (child.error) fail("E_CAPABILITY_BROKEN", child.error.message);
+    process.exit(child.status ?? 1);
+  } catch (error) { fail(error.code || "E_CAPABILITY_BROKEN", error.message); }
+}
+
 /** Level of a directory: laptop (home), repo (.git), else workspace. */
 function levelOf(dir) {
   const d = resolve(dir);
@@ -637,7 +982,55 @@ const OPERATION_ADDRESS_RE = /^(knowledge|messaging|tasks):([a-z][a-z0-9-]*)$/;
 const reportsRetainedEffectsText = (message) => /INCOMPLETE|quarantin|retain|could not (?:be )?(?:verif|confirm)/i.test(String(message || ""));
 // Comfortably below the scheduler's 5-minute command bound and any GUI
 // proxy, so the receipt always reaches the caller before a wrapper gives up.
-const OPERATION_TIMEOUT_MS = 4 * 60 * 1000;
+const OPERATION_TIMEOUT_MS = CAPTURED_OPERATION_TIMEOUT_MS;
+function finishOperation({ r, bail, address, provider, op, argFlags, cwd, home, meta, cleanupError, intent, settlement }) {
+  const stderr = String(r.stderr || "").trim();
+  const timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && ["SIGTERM", "SIGKILL"].includes(r.signal) && (!settlement || !r.error));
+  const base = { operation: address, capability: provider.capability, version: provider.version || null, argv: [provider.command, op.command, ...argFlags], cwd, target: home ? { home, instance: meta.instance } : null };
+  // Unconfirmed outcomes (a timeout, no valid receipt, a receipt contradicted
+  // by the exit status) carry what WAS observed in error.details, so a
+  // scheduler can keep the slot as unknown and reconcile by any name the
+  // provider managed to answer; they are never confirmed failures.
+  const observed = (envelope) => ({ exit: r.status, signal: r.signal || null, unconfirmed: true, ...(envelope && typeof envelope === "object" ? { envelope } : {}),
+    ...(stderr ? { stderr: stderr.slice(0, 2000) } : {}), ...(cleanupError ? { cleanup: { code: cleanupError.code || "E_OPERATION_CLEANUP", message: String(cleanupError.message || cleanupError).slice(0, 1000) } } : {}) });
+  if (r.error && !timedOut) bail("E_CAPABILITY_BROKEN", `${address}: ${r.error.message || r.error}`, settlement ? observed(parseEnvelopeText(String(r.stdout || ""))) : undefined);
+  if (timedOut) bail("E_OPERATION_TIMEOUT", `${address} (${provider.capability} ${op.command}) did not finish within ${OPERATION_TIMEOUT_MS / 1000} s; its effects are unconfirmed`, observed(parseEnvelopeText(String(r.stdout || ""))));
+  // Exactly one JSON-v1 envelope on stdout, nothing else, and an exit status
+  // that agrees with it: contaminated output or a success envelope from a
+  // process that then failed is not a receipt.
+  let envelope;
+  try { envelope = JSON.parse(String(r.stdout || "").trim()); } catch { envelope = undefined; }
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope) || envelope.schemaVersion !== 1 || typeof envelope.ok !== "boolean") bail("E_OPERATION_RESULT", `${address} (${provider.capability} ${op.command}) did not answer exactly one JSON-v1 envelope on stdout (exit ${r.status}); its effects are unconfirmed${stderr ? `: ${stderr.slice(0, 400)}` : ""}`, observed(parseEnvelopeText(String(r.stdout || ""))));
+  if (cleanupError) bail("E_OPERATION_RESULT", `${address} (${provider.capability} ${op.command}) answered, but private invocation cleanup could not be confirmed; its effects are unconfirmed`, observed(envelope));
+  // A provider's own failure is relayed with its code; its WHOLE envelope
+  // (a partial receipt such as result.instance of something it launched
+  // before failing, and any details it gave) travels in error.details so a
+  // scheduler can keep an unconfirmed outcome and reconcile that target.
+  if (!envelope.ok) bail(envelope.error?.code || "E_OPERATION_FAILED", `${address}: ${envelope.error?.message || "failed"}`, { exit: r.status, envelope, ...(reportsRetainedEffectsText(envelope.error?.message) ? { unconfirmed: true } : {}) });
+  if (r.status !== 0) bail("E_OPERATION_RESULT", `${address} (${provider.capability} ${op.command}) answered ok but exited ${r.status}; the receipt is not trusted and its effects are unconfirmed${stderr ? `: ${stderr.slice(0, 400)}` : ""}`, observed(envelope));
+  const result = envelope.result && typeof envelope.result === "object" ? envelope.result : {};
+  if (op.kind === "view") {
+    const docs = result.documents;
+    const bad = !Array.isArray(docs) || docs.some((d) => !d || typeof d !== "object" || typeof d.label !== "string" || !d.label
+      || (d.kind !== undefined && !["markdown", "text"].includes(d.kind))
+      || (d.path !== undefined && d.path !== null && (typeof d.path !== "string" || !isAbsolute(d.path)))
+      || (d.text !== undefined && d.text !== null && typeof d.text !== "string"));
+    if (bad) bail("E_OPERATION_RESULT", `${address} is a view operation but ${provider.capability} ${op.command} did not answer { documents: [{label, kind?, path?, text?}] }`);
+  }
+  // A launch receipt in the delegated result (a harvester the provider
+  // spawned) is surfaced as top-level instance/home so the scheduler tracks
+  // it exactly as it tracks a command job's launch; the source home itself
+  // is `target`, never a launch.
+  const receipt = {};
+  if (typeof result.instance === "string" && result.instance !== meta?.instance) receipt.instance = result.instance;
+  if (typeof result.home === "string" && result.home !== home) receipt.home = result.home;
+  const out = { ...base, ...receipt, result, ...(intent ? { intent } : {}), ...(stderr ? { stderr: stderr.slice(0, 2000) } : {}) };
+  if (JSON_MODE) { jsonOk(out); return; }
+  console.log(`${address} via ${provider.capability}@${provider.version || "?"} (${provider.command} ${op.command}) in ${shortPath(cwd)}: ok`);
+  if (op.kind === "view") for (const d of result.documents) console.log(`  - ${d.label}${d.path ? ` (${shortPath(d.path)})` : ""}${d.text ? `: ${String(d.text).split("\n")[0].slice(0, 100)}` : ""}`);
+  else console.log(JSON.stringify(result, null, 2));
+  if (stderr) console.error(stderr);
+}
 function operationCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   dropAmbientRoot();
@@ -754,50 +1147,7 @@ function operationCmd() {
   });
   if (op.context === "home") Object.assign(env, { OATS_INSTANCE: meta.instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, PI_AGENT_INSTANCE: meta.instance, PI_AGENT_HOME: home });
   const r = spawnSync("node", [abs, ...rest, ...argFlags, "--json"], { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 16 * 1024 * 1024, timeout: OPERATION_TIMEOUT_MS, killSignal: "SIGTERM" });
-  const stderr = String(r.stderr || "").trim();
-  const timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && r.signal === "SIGTERM");
-  if (r.error && !timedOut) bail("E_CAPABILITY_BROKEN", `${address}: ${r.error.message || r.error}`);
-  const base = { operation: address, capability: provider.capability, version: provider.version || null, argv: [provider.command, op.command, ...argFlags], cwd, target: home ? { home, instance: meta.instance } : null };
-  // Unconfirmed outcomes (a timeout, no valid receipt, a receipt contradicted
-  // by the exit status) carry what WAS observed in error.details, so a
-  // scheduler can keep the slot as unknown and reconcile by any name the
-  // provider managed to answer; they are never confirmed failures.
-  const observed = (envelope) => ({ exit: r.status, signal: r.signal || null, unconfirmed: true, ...(envelope && typeof envelope === "object" ? { envelope } : {}), ...(stderr ? { stderr: stderr.slice(0, 2000) } : {}) });
-  if (timedOut) bail("E_OPERATION_TIMEOUT", `${address} (${provider.capability} ${op.command}) did not finish within ${OPERATION_TIMEOUT_MS / 1000} s; its effects are unconfirmed`, observed(parseEnvelopeText(String(r.stdout || ""))));
-  // Exactly one JSON-v1 envelope on stdout, nothing else, and an exit status
-  // that agrees with it: contaminated output or a success envelope from a
-  // process that then failed is not a receipt.
-  let envelope;
-  try { envelope = JSON.parse(String(r.stdout || "").trim()); } catch { envelope = undefined; }
-  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope) || envelope.schemaVersion !== 1 || typeof envelope.ok !== "boolean") bail("E_OPERATION_RESULT", `${address} (${provider.capability} ${op.command}) did not answer exactly one JSON-v1 envelope on stdout (exit ${r.status}); its effects are unconfirmed${stderr ? `: ${stderr.slice(0, 400)}` : ""}`, observed(parseEnvelopeText(String(r.stdout || ""))));
-  // A provider's own failure is relayed with its code; its WHOLE envelope
-  // (a partial receipt such as result.instance of something it launched
-  // before failing, and any details it gave) travels in error.details so a
-  // scheduler can keep an unconfirmed outcome and reconcile that target.
-  if (!envelope.ok) bail(envelope.error?.code || "E_OPERATION_FAILED", `${address}: ${envelope.error?.message || "failed"}`, { exit: r.status, envelope, ...(reportsRetainedEffectsText(envelope.error?.message) ? { unconfirmed: true } : {}) });
-  if (r.status !== 0) bail("E_OPERATION_RESULT", `${address} (${provider.capability} ${op.command}) answered ok but exited ${r.status}; the receipt is not trusted and its effects are unconfirmed${stderr ? `: ${stderr.slice(0, 400)}` : ""}`, observed(envelope));
-  const result = envelope.result && typeof envelope.result === "object" ? envelope.result : {};
-  if (op.kind === "view") {
-    const docs = result.documents;
-    const bad = !Array.isArray(docs) || docs.some((d) => !d || typeof d !== "object" || typeof d.label !== "string" || !d.label
-      || (d.kind !== undefined && !["markdown", "text"].includes(d.kind))
-      || (d.path !== undefined && d.path !== null && (typeof d.path !== "string" || !isAbsolute(d.path)))
-      || (d.text !== undefined && d.text !== null && typeof d.text !== "string"));
-    if (bad) bail("E_OPERATION_RESULT", `${address} is a view operation but ${provider.capability} ${op.command} did not answer { documents: [{label, kind?, path?, text?}] }`);
-  }
-  // A launch receipt in the delegated result (a harvester the provider
-  // spawned) is surfaced as top-level instance/home so the scheduler tracks
-  // it exactly as it tracks a command job's launch; the source home itself
-  // is `target`, never a launch.
-  const receipt = {};
-  if (typeof result.instance === "string" && result.instance !== meta?.instance) receipt.instance = result.instance;
-  if (typeof result.home === "string" && result.home !== home) receipt.home = result.home;
-  const out = { ...base, ...receipt, result, ...(stderr ? { stderr: stderr.slice(0, 2000) } : {}) };
-  if (JSON_MODE) { jsonOk(out); return; }
-  console.log(`${address} via ${provider.capability}@${provider.version || "?"} (${provider.command} ${op.command}) in ${shortPath(cwd)}: ok`);
-  if (op.kind === "view") for (const d of result.documents) console.log(`  - ${d.label}${d.path ? ` (${shortPath(d.path)})` : ""}${d.text ? `: ${String(d.text).split("\n")[0].slice(0, 100)}` : ""}`);
-  else console.log(JSON.stringify(result, null, 2));
-  if (stderr) console.error(stderr);
+  finishOperation({ r, bail, address, provider, op, argFlags, cwd, home, meta });
 }
 
 // ---------- soul set: runtime defaults and instructions of an editable soul ----------
@@ -3822,6 +4172,7 @@ function scheduleCmd() {
 
 async function sessionCmd() {
   try {
+    if (flag("native-record") !== undefined) throw Object.assign(new Error("--native-record outcome inspection requires exact captured deployment/resolution selectors"), { code: "E_BAD_ARGS" });
     const home = flag("home");
     let result;
     if (args[1] === "attach") {
@@ -4158,7 +4509,7 @@ function versionCmd() {
     // on it (an older CLI without the surface must fail closed with a
     // reason, not an argument error). `features`: kernel abilities a peer
     // must see before relying on them (retire-home: retire --home).
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations"], scheduleApi: SCHEDULE_API, operationsApi: 1 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations"], scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -4523,11 +4874,48 @@ async function serverRouteCmd() {
 // blame` pointing at the commit that last changed each command.
 const TYPED_CLI_FAILURES = new Set(["unsafe-config-key", "unsafe-config-value"]);
 try {
+// Inspect explicit selectors with the existing parser before new-work routing,
+// including selectors before the command. Inherited captures are not prepare inputs.
+let captured;
+try { captured = capturedSelector(args, {}); }
+catch (error) {
+  if (JSON_MODE) jsonFail(error.code || "E_BAD_ARGS", error.message);
+  die(error.message);
+}
+const sourceInspection = (cmd === "inspect" || captured?.args[0] === "inspect")
+  && args.some(arg => arg === "--request" || arg.startsWith("--request="));
+if (sourceInspection) {
+  if (captured) {
+    if (JSON_MODE) jsonFail("E_BAD_ARGS", "source inspection is explicit new work and cannot use captured selectors");
+    die("source inspection is explicit new work and cannot use captured selectors");
+  }
+  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
+  inspectOnboardingCmd(); process.exit(0);
+}
+if (cmd === "prepare" || captured?.args[0] === "prepare") {
+  if (captured) {
+    if (JSON_MODE) jsonFail("E_BAD_ARGS", "prepare is explicit new work and cannot use captured selectors");
+    die("prepare is explicit new work and cannot use captured selectors");
+  }
+  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
+  prepareCmd(); process.exit(0);
+}
+// Other commands retain their existing explicit/inherited selection rules.
+try { captured ??= capturedSelector(args); }
+catch (error) {
+  if (JSON_MODE) jsonFail(error.code || "E_BAD_ARGS", error.message);
+  die(error.message);
+}
+if (captured) {
+  args.splice(0, args.length, ...captured.args); cmd = args[0];
+  // Host protocol negotiation describes this executable, not a mutable
+  // configuration. An inherited capture must not break `oats version` probes.
+  if (captured.explicit || cmd !== "version") { capturedCommand(captured); process.exit(0); }
+}
 // `--help`/`-h` anywhere after a kernel command prints that command's usage
 // and exits 0 BEFORE any dispatch: a fresh operator inspects --help before
 // using a command, and `install --help` once ran the bare restore while
 // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
-const KERNEL_COMMANDS = new Set(["capture", "config", "create", "doctor", "inspect", "operation", "soul", "launch-config", "experimental", "init", "inject", "install", "list", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
 const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
 if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
 if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "use", "soul", "launch-config"].includes(cmd)) await serverRouteCmd();
@@ -4821,6 +5209,37 @@ The turn record (core — every conversation captured, searchable, replicated):
                                             design, repo checkout only; see
                                             packages/experimental/README.md
 
+  oats inspect --request <absolute-json-file> [--json]
+                                            read-only fresh source/workspace/member metadata;
+                                            no current config, provider execution or preparation authority
+  oats prepare --request <absolute-json-file> [--json]
+                                            complete public preparation input; no mixed flags,
+                                            inherited binding, implicit setup or launch authority
+  oats prepare --dir <abs> --source <git repo> --revision <ref> --export <path>
+      --alias <name> [--work <mode>] [--json]  prepare retained commands and curriculum,
+                                            no launch; provider gaps report incomplete
+  oats prepare --dir <abs> --workspace <git repo> --alias <advertised alias>
+      [--workspace-revision <ref>] [--work <mode>] [--json]
+                                            same preparation through workspace imports
+  oats inspect --deployment <abs> --resolution <id> [--composition] [--json]
+      [--helper <exact-map-key>]             inspect retained source/helper inputs, not today's configuration
+  oats trust <capability> --deployment <abs> --resolution <id> [--json]
+                                            explicitly approve that exact captured artifact
+  oats <namespace> <command> --deployment <abs> --resolution <id> -- [args…]
+                                            run the approved retained command; no ambient fallback
+  oats operation run <layer>:<name> --deployment <abs> --resolution <id>
+      [--home <abs>] [--arg k=v ...] [--retry-intent <saved-id>] [--json]
+                                            home actions admit distinct requests; explicit retry reuses intent
+                                            scope views stay read-only; scope mutation is not yet qualified
+  oats spawn <captured subject> --deployment <abs> --resolution <id>
+      --home <abs> --no-launch [--json]      create a fresh directory scaffold and run captured hooks
+  oats session inspect --deployment <abs> --resolution <id> --home <abs> --native-record <UUID> [--helper <exact-key>] --json
+                                           read-only Pi completion observation; not admission or readiness
+  oats session start|restart --deployment <abs> --resolution <id> --home <abs>
+      [--helper <exact-source-map-key>] [--request <abs-json>] [--retry-intent <saved-id>] [--json]
+                                            dispatch the owned captured home via existing native custody;
+                                            version1 request: backend/task/stopGraceMs, no model override
+
   oats <namespace> <command> [args…]         run an operational command only when its
                                             capability is active (e.g. oats okf harvest)
 

package/capabilities/oats-okf/bin/oats-okf-binding.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { runBindingWire } from '../lib/binding-wire.mjs';
+
+const args=process.argv.slice(2);
+if(args.includes('--help') || args.includes('-h')) {
+  process.stdout.write('oats okf provider binding phase (manifest-owned JSON stdin/stdout)\n');
+} else {
+  const phase=args[0];
+  if(args.length!==1) {
+    await runBindingWire(phase,[],process.stdout);
+  } else {
+    await runBindingWire(phase);
+  }
+}