@awebai/oats 0.23.2 → 0.24.0

package/lib/captured-binding-file.mjs

@@ -0,0 +1,36 @@
+/** Private invocation projection, not a new binding store or action permit.
+ * The synchronous caller has already loaded/qualified its exact captured action. */
+import { lstatSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { portableStateDirectory } from './portable-state.mjs';
+import { canonicalJson } from './portable-values.mjs';
+import { validateProviderBinding } from './resolution-shape.mjs';
+import { BINDING_LIMITS } from './provider-binding-wire.mjs';
+import { oatsError } from './errors.mjs';
+
+export function withCapturedBindingFile({deployment,record,capability},run) {
+  const bindings=Object.values(record.bindings).filter(binding=>binding.capability===capability.id);
+  if (!bindings.length) return run({});
+  if (bindings.length !== 1) throw oatsError('invalid-resolution','one capability cannot consume contradictory slot bindings');
+  const binding=validateProviderBinding(bindings[0]),bytes=canonicalJson(binding,BINDING_LIMITS);
+  const directory=mkdtempSync(join(portableStateDirectory(deployment,true),'.binding-'));
+  const owned=lstatSync(directory),file=join(directory,'binding.json');let primary,result,completed=false;
+  try {
+    writeFileSync(file,bytes,{flag:'wx',mode:0o600});
+    result=run({OATS_BINDING_FILE:file});completed=true;return result;
+  } catch(error) {primary=error;throw error;}
+  finally {
+    try {
+      const current=lstatSync(directory);
+      if (!current.isDirectory() || current.dev!==owned.dev || current.ino!==owned.ino) throw oatsError('integrity-drift','binding invocation directory ownership changed');
+      rmSync(directory,{recursive:true});
+    } catch(cleanup) {
+      if (!primary) {
+        const error=new AggregateError([cleanup],'captured binding cleanup failed after invocation',{cause:cleanup});
+        error.code=cleanup.code;error.invocationCompleted=completed;error.invocationResult=result;throw error;
+      }
+      const error=new AggregateError([primary,cleanup],'captured command and binding cleanup failed',{cause:primary});
+      error.code=primary.code;if(primary.invocationCompleted){error.invocationCompleted=true;error.invocationResult=primary.invocationResult;}throw error;
+    }
+  }
+}

package/lib/captured-dispatch.mjs

@@ -0,0 +1,66 @@
+/** One exact action-loading boundary. No current config, lock or marketplace
+ * lookup. Core supplies its complete codecs and native host checks. */
+import { canonicalJson } from "./portable-values.mjs";
+import { validateCapturedAction } from "./captured-action-shape.mjs";
+import { verifyResolutionInputs } from "./captured-resolutions.mjs";
+import { readApprovalLedger, evaluateCapturedApprovals } from "./artifact-approvals.mjs";
+import { composeCapturedInstructions } from "./instruction-composition.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function loadCapturedAction({ deployment, resolution, action }, codecs) {
+  validateCapturedAction(action);
+  const verified = verifyResolutionInputs(deployment, resolution), { record } = verified;
+  if (record.capture !== "prepared") throw oatsError("migration-required", "reconstructed dispatch requires the dedicated migration evidence verifier");
+  const manifests = new Map(), capabilities = new Map();
+  for (const [id, row] of Object.entries(record.artifacts.capabilities)) {
+    const root = verified.roots.get(canonicalJson(row.artifact));
+    const manifest = codecs.manifest(root);
+    if (!manifest || manifest.capability !== id || manifest.version !== row.version) throw oatsError("invalid-resolution", "compiled manifest differs from captured identity/version");
+    const settings = Object.fromEntries(Object.entries(record.dispatch.settingsChoices[id] ?? {}).map(([name, key]) => [name, record.choices[key].value]));
+    codecs.settings(manifest, settings);
+    manifests.set(id, manifest); capabilities.set(id, { id, manifest, settings });
+  }
+  // Complete static validation applies even to inspection; neither inspection
+  // nor input verification is an excuse to accept an unsafe launch recipe.
+  if (record.dispatch.launch !== null) codecs.launch(record.dispatch.launch);
+  const approvals = evaluateCapturedApprovals({ ...verified, manifests }, readApprovalLedger(deployment).ledger);
+  const base = { ...verified, manifests, capabilities, approvals, resolution, deployment };
+  if (action.kind === "inspect") return base;
+  if (action.kind === "compose") return { ...base, composition: composeCapturedInstructions(verified) };
+  let id = action.capability;
+  if (action.kind === "operation") id = record.bindings[action.slot]?.capability;
+  if (action.namespace !== undefined) {
+    const matches = [...manifests].filter(([, manifest]) => manifest.command === action.namespace);
+    if (matches.length > 1) throw oatsError("duplicate-namespace", "captured command namespace is ambiguous");
+    id = matches[0]?.[0];
+  }
+  if (typeof id !== "string" || !capabilities.has(id)) throw oatsError("capability-not-selected", "action capability is not selected by this resolution");
+  const capability = capabilities.get(id), manifest = capability.manifest;
+  let name = action.name, operation;
+  if (action.kind === "operation") {
+    operation = codecs.operations(manifest).find((entry) => entry.name === name);
+    if (!operation) throw oatsError("operation-not-found", "captured provider does not declare this operation");
+    name = operation.command;
+  }
+  const declarations = action.kind === "hook" ? codecs.hooks(manifest) : manifest.commands;
+  if (!declarations || !Object.hasOwn(declarations, name)) throw oatsError("command-not-found", "captured capability does not declare this action");
+  const approval = approvals.find((entry) => entry.artifact.capability === id);
+  if (approval.status !== "approved") throw oatsError("approval-required", "action needs current approval for its exact capability artifact");
+  // Provider-owned payload/credential/member qualification is a separate ABI.
+  // Until its adapter is supplied, report the missing gate rather than execute
+  // using an ambient binding file or treating captured choices as enrollment.
+  const invocation = typeof codecs.invocation === "function" ? codecs.invocation(base, action, capability) : undefined;
+  const bindings = Object.entries(record.bindings).filter(([, binding]) => binding.capability === id);
+  if (bindings.length) {
+    if (typeof codecs.bindings !== "function") throw oatsError("provider-not-qualified", "captured provider binding qualification is unavailable");
+    codecs.bindings(bindings, capability, record, invocation);
+  }
+  const missing = codecs.host(capability);
+  if (missing.length) throw oatsError("host-requirement-missing", "captured action has unmet host command requirements", missing);
+  const spec = declarations[name];
+  if (typeof spec !== "string" || !spec.trim() || spec.includes("\0")) throw oatsError("invalid-resolution", "captured executable declaration is not valid text");
+  const [script, ...args] = spec.trim().split(/\s+/), file = codecs.executable(manifest, script);
+  if (!file) throw oatsError("resource-not-found", "captured executable is absent");
+  if (![...verified.resources.values()].includes(file)) throw oatsError("resolution-incomplete", "captured executable is absent from the resource inventory");
+  return { ...base, action, capability, operation, executable: { file, args }, ...(invocation ? { invocation } : {}) };
+}

package/lib/captured-instance-index.mjs

@@ -0,0 +1,277 @@
+/** Bounded lifecycle custody in the existing deployment index. No source/config
+ * discovery, user database, provider policy or automatic legacy backfill. */
+import { closeSync, constants, fsyncSync, lstatSync, openSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, join, resolve } from "node:path";
+import { readPortableBytes } from "./portable-files.mjs";
+import { compareUtf8, canonicalJson, parseStrictJson } from "./portable-values.mjs";
+import { jsonIntegrity } from "./portable-digest.mjs";
+import { portableScope, portableStateDirectory, withPortableStateWrite, writeGuardedPortableDocument } from "./portable-state.mjs";
+import { validateExecutionBinding } from "./schedule-capsule.mjs";
+import { validateIncarnationId, validateIntentRef } from "./captured-admission-shape.mjs";
+import { validateCapturedAction } from "./captured-action-shape.mjs";
+import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
+import { objectAt, stringAt } from "./portable-shape.mjs";
+import { oatsError } from "./errors.mjs";
+
+const FILE = "instance-references.json";
+const STATUSES = new Set(["scaffolded-hooks-pending", "spawn-hooks-running", "spawned-launch-pending", "spawned-cleanup-required", "spawn-failed-cleanup-required", "retire-running", "retire-failed-cleanup-required", "start-running", "start-dispatched", "start-failed-cleanup-required"]);
+const INTENT_STATES = new Set(["admitted", "running", "completed", "unconfirmed", "blocked"]);
+const LIMITS = Object.freeze({ maxBytes: 4 * 1024 * 1024, maxDepth: 32, maxEntries: 40_000 });
+const RECEIPT_LIMITS = Object.freeze({ maxBytes: 128 * 1024, maxDepth: 24, maxEntries: 8192 });
+const same = (a,b) => canonicalJson(a) === canonicalJson(b);
+
+export function capturedDirectoryIdentity(path) {
+  const stat = lstatSync(path);
+  if (!stat.isDirectory()) throw oatsError("integrity-drift", "captured home/work must remain real directories");
+  return { dev: stat.dev, ino: stat.ino };
+}
+function directoryIdentity(value) {
+  objectAt(value,["dev","ino"],["dev","ino"]);
+  for (const key of ["dev","ino"]) if (!Number.isSafeInteger(value[key]) || value[key] < 0) throw oatsError("invalid-declaration","invalid directory identity witness");
+}
+function human(value) {
+  if (value === null) return;
+  objectAt(value,["provider","id"],["provider","id"]);stringAt(value.provider,"/human/provider");stringAt(value.id,"/human/id");
+}
+function intentRef(row,intent) { return {schemaVersion:1,executionId:intent.executionId,incarnationId:row.incarnationId,attempt:intent.attempt}; }
+function validateAdmittedAction(action,capability) {
+  if(action?.kind==='session'){
+    objectAt(action,['kind','name'],['kind','name']);
+    if(!['start','restart'].includes(action.name)||capability!==null)throw oatsError('invalid-declaration','invalid kernel session admission');
+  }else{
+    validateCapturedAction(action);
+    if(!isMaterializedCapabilityId(capability)||action.capability!==undefined&&action.capability!==capability)throw oatsError('invalid-declaration','invalid intent capability owner');
+  }
+}
+function validateIntent(intent) {
+  objectAt(intent,["executionId","capability","action","inputIntegrity","state","attempt","receipt","replayable"],["executionId","capability","action","inputIntegrity","state","attempt","receipt","replayable"]);
+  if(typeof intent.replayable!=="boolean")throw oatsError("invalid-declaration","invalid intent replay evidence");
+  validateAdmittedAction(intent.action,intent.capability);
+  stringAt(intent.executionId,"/executionId",{pattern:/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/});
+  if (!["command","operation","hook","session"].includes(intent.action.kind) || !INTENT_STATES.has(intent.state)) throw oatsError("invalid-declaration","invalid admitted action/state");
+  if (!Number.isSafeInteger(intent.attempt) || intent.attempt < 1) throw oatsError("invalid-declaration","invalid intent attempt");
+  objectAt(intent.inputIntegrity,["format","value"],["format","value"]);
+  if (intent.inputIntegrity.format !== "oats.json.v1" || !/^sha256-[a-f0-9]{64}$/.test(intent.inputIntegrity.value)) throw oatsError("invalid-declaration","invalid intent input integrity");
+  canonicalJson(intent.receipt,RECEIPT_LIMITS);
+}
+export function validateCapturedInstanceReference(row) {
+  objectAt(row,["home","instance","agent","kind","status","executionBinding","responsibleHuman","incarnationId","custody","intents","custodyFailure","nativeScaffold"],
+    ["home","instance","agent","kind","status","executionBinding","responsibleHuman","incarnationId","custody","intents"]);
+  for(const key of ["home","instance","agent"]) stringAt(row[key],`/${key}`);
+  if(!isAbsolute(row.home)||resolve(row.home)!==row.home) throw oatsError("invalid-declaration","captured home must be normalized absolute");
+  if(!['persistent','helper'].includes(row.kind)||!STATUSES.has(row.status)) throw oatsError("invalid-declaration","invalid captured instance kind/status");
+  validateIncarnationId(row.incarnationId);validateExecutionBinding(row.executionBinding);human(row.responsibleHuman);
+  if(row.nativeScaffold!==undefined){
+    objectAt(row.nativeScaffold,['schemaVersion','directories'],['schemaVersion','directories']);
+    if(row.nativeScaffold.schemaVersion!==1)throw oatsError('invalid-declaration','invalid native scaffold witness');
+    const names=['historyRoot','history','retirementRoot','baselines'];objectAt(row.nativeScaffold.directories,names,names);
+    for(const value of Object.values(row.nativeScaffold.directories))directoryIdentity(value);
+  }
+  if(row.custodyFailure!==undefined){
+    objectAt(row.custodyFailure,["code","message"],["code","message"]);
+    for(const key of ["code","message"]){stringAt(row.custodyFailure[key],`/custodyFailure/${key}`);if(row.custodyFailure[key].length>200)throw oatsError("resource-limit","custody diagnostic exceeds bound");}
+  }
+  objectAt(row.custody,["home","work"],["home","work"]);directoryIdentity(row.custody.home);directoryIdentity(row.custody.work);
+  if(!Array.isArray(row.intents)||row.intents.length>128) throw oatsError("resource-limit","captured instance intent retention limit reached");
+  const ids=new Set();let pending=0;
+  for(const intent of row.intents){validateIntent(intent);if(ids.has(intent.executionId))throw oatsError("invalid-declaration","duplicate intent ID");ids.add(intent.executionId);if(intent.state!=="completed")pending++;}
+  if(pending>1) throw oatsError("invalid-declaration","multiple unsettled captured intents");
+  return row;
+}
+function validateIndex(value) {
+  canonicalJson(value,LIMITS);objectAt(value,["schemaVersion","instances"],["schemaVersion","instances"]);
+  if(value.schemaVersion!==2) throw oatsError("migration-required","captured instance index lacks incarnation/admission evidence; no automatic backfill");
+  if(!Array.isArray(value.instances)) throw oatsError("invalid-declaration","invalid captured instance index");
+  const ids=new Set();let prior;
+  for(const row of value.instances){validateCapturedInstanceReference(row);if(ids.has(row.incarnationId)||(prior!==undefined&&compareUtf8(prior,row.home)>=0))throw oatsError("invalid-declaration","duplicate/unordered captured instance references");ids.add(row.incarnationId);prior=row.home;}
+  return value;
+}
+export function readCapturedInstanceIndex(deployment) {
+  const root=portableStateDirectory(deployment,false);
+  if(!root)return {schemaVersion:2,instances:[]};
+  const bytes=readPortableBytes(join(root,FILE),{allowMissing:true});
+  return bytes===null?{schemaVersion:2,instances:[]}:validateIndex(parseStrictJson(bytes,LIMITS));
+}
+
+/** Read and verify current owned metadata; old/unwitnessed homes are evidence,
+ * never newly minted identities. Recheck roots after the descriptor read. */
+export function readCapturedInstanceMetadata(home) {
+  if(typeof home!=="string"||!isAbsolute(home))throw oatsError("invalid-declaration","captured home must be explicit and absolute");
+  const actual=portableScope(home),homeIdentity=capturedDirectoryIdentity(home),workIdentity=capturedDirectoryIdentity(join(home,"work"));
+  const metadata=parseStrictJson(readPortableBytes(join(actual,"instance.json")),LIMITS);
+  if(!metadata.incarnationId||!metadata.captured?.custody)throw oatsError("migration-required","captured home lacks incarnation custody; explicit reprovisioning required without deleting prior data");
+  validateIncarnationId(metadata.incarnationId);validateExecutionBinding(metadata.executionBinding);
+  if(typeof metadata.home!=="string"||portableScope(metadata.home)!==actual||metadata.work!=="directory"
+    ||!same(metadata.captured.custody,{home:homeIdentity,work:workIdentity})
+    ||!same(capturedDirectoryIdentity(home),homeIdentity)||!same(capturedDirectoryIdentity(join(home,"work")),workIdentity))throw oatsError("integrity-drift","captured home/work ownership changed");
+  return metadata;
+}
+function matchedRow(index,home) {
+  const metadata=readCapturedInstanceMetadata(home),actual=portableScope(home),row=index.instances.find(item=>item.home===actual);
+  if(!row)throw oatsError("invalid-resolution","captured incarnation is not indexed");
+  if(row.incarnationId!==metadata.incarnationId||row.instance!==metadata.instance||row.agent!==metadata.agent||row.kind!==metadata.kind
+    ||!same(row.custody,metadata.captured.custody)||!same(row.executionBinding,metadata.executionBinding)||!same(row.responsibleHuman,metadata.responsibleHuman))throw oatsError("invalid-resolution","captured index differs from current incarnation metadata");
+  return {row,metadata};
+}
+export function readCapturedInstanceAuthority(deployment,home) {
+  return matchedRow(readCapturedInstanceIndex(deployment),home);
+}
+const AUTHORITY_FIELDS = ["home","instance","agent","kind","executionBinding","responsibleHuman","incarnationId","custody"];
+function sameAuthority(a,b){return AUTHORITY_FIELDS.every(key=>same(a[key],b[key]))&&same(a.nativeScaffold??null,b.nativeScaffold??null);}
+export function assertCapturedInstanceCustody(original) {
+  for(const [key,path] of [["home",original.home],["work",join(original.home,"work")]]){
+    if(!same(capturedDirectoryIdentity(path),original.custody[key]))throw oatsError("integrity-drift","captured home/work changed after preflight");
+  }
+  const {row}=readCapturedInstanceAuthority(original.executionBinding.deployment,original.home);
+  if(!sameAuthority(original,row))throw oatsError("integrity-drift","captured instance authority changed after preflight");
+  return row;
+}
+
+/** Failure reporting deliberately does NOT read/resolve the home: it may now
+ * belong to someone else. Match the original indexed authority and attempt,
+ * preserve receipts there, and never use this path to certify success. */
+export function recordCapturedCustodyFailure(original,{meta={},intents={},code="integrity-drift",message="captured home/work custody changed"}={}) {
+  validateCapturedInstanceReference(original);objectAt(meta,null,[]);objectAt(intents,null,[]);
+  return withPortableStateWrite(original.executionBinding.deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),row=index.instances.find(item=>item.incarnationId===original.incarnationId);
+    if(!row||!sameAuthority(original,row))throw oatsError("selection-changed","original indexed custody no longer matches failure report");
+    // This reporter owns only the activation transition it acquired before
+    // hooks. Check it before changing ANY receipt/status, even on failure.
+    if(row.status!=="spawn-hooks-running")throw oatsError("selection-changed","activation no longer owns the indexed lifecycle state");
+    for(const [capability,ref] of Object.entries(intents)){
+      const intent=matchedIntent(row,ref);
+      if(intent.capability!==capability)throw oatsError("invalid-resolution","observed receipt owner differs from admitted capability");
+      if(Object.hasOwn(meta,capability)){canonicalJson(meta[capability],RECEIPT_LIMITS);intent.receipt=meta[capability];}
+      if(intent.state==="running"||intent.state==="admitted"){intent.state="unconfirmed";intent.replayable=false;}
+    }
+    for(const capability of Object.keys(meta))if(!Object.hasOwn(intents,capability))throw oatsError("invalid-resolution","observed receipt lacks its admitted intent");
+    row.status="spawn-failed-cleanup-required";
+    row.custodyFailure={code:String(code).slice(0,200)||"integrity-drift",message:String(message).slice(0,200)||"custody failure"};
+    save(context,index);return {home:row.home,incarnationId:row.incarnationId,executionBinding:row.executionBinding,custodyFailure:row.custodyFailure};
+  });
+}
+/** Sync only already-owned metadata paths. If synchronization fails after
+ * publication, callers retain custody rather than claim admission completed. */
+export function syncCapturedMetadata(path) {
+  const stat=lstatSync(path);
+  if(!stat.isFile()&&!stat.isDirectory())throw oatsError("integrity-drift","captured metadata sync target changed");
+  const fd=openSync(path,constants.O_RDONLY|(constants.O_NOFOLLOW??0));
+  try{fsyncSync(fd);}finally{closeSync(fd);}
+}
+function save(context,index){
+  validateIndex(index);const file=join(context.root,FILE);
+  writeGuardedPortableDocument(context,file,index);
+  for(const path of [file,context.root,dirname(context.root),context.deployment])syncCapturedMetadata(path);
+}
+export function registerCapturedInstance(deployment,home) {
+  return withPortableStateWrite(deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),metadata=readCapturedInstanceMetadata(home),actual=portableScope(home);
+    if(index.instances.some(row=>row.home===actual))throw oatsError("selection-changed","captured home has retained lifecycle obligations; no replacement/backfill");
+    if(portableScope(metadata.executionBinding.deployment)!==context.deployment)throw oatsError("invalid-resolution","incarnation deployment mismatch");
+    const row={home:actual,instance:metadata.instance,agent:metadata.agent,kind:metadata.kind,status:"scaffolded-hooks-pending",executionBinding:metadata.executionBinding,
+      responsibleHuman:metadata.responsibleHuman,incarnationId:metadata.incarnationId,custody:metadata.captured.custody,intents:[]};
+    validateCapturedInstanceReference(row);index.instances.push(row);index.instances.sort((a,b)=>compareUtf8(a.home,b.home));save(context,index);return row;
+  });
+}
+export function markCapturedNativeScaffold(deployment,home,proof) {
+  return withPortableStateWrite(deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),{row,metadata}=matchedRow(index,home);
+    if(row.nativeScaffold||row.status!=='scaffolded-hooks-pending'||row.intents.length)throw oatsError('selection-changed','native scaffold cannot be backfilled after admission');
+    if(!same(metadata.captured.nativeScaffold,proof))throw oatsError('invalid-resolution','native scaffold proof differs from owned metadata');
+    row.nativeScaffold=proof;save(context,index);return row;
+  });
+}
+export function setCapturedInstanceStatus(deployment,home,status,{expectedStatus}={}) {
+  if(!STATUSES.has(status))throw oatsError("invalid-declaration","invalid captured lifecycle status");
+  return withPortableStateWrite(deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,home);
+    if(expectedStatus!==undefined&&row.status!==expectedStatus)throw oatsError("selection-changed","captured lifecycle status changed");
+    row.status=status;save(context,index);return row;
+  });
+}
+
+/** New intent or EXPLICIT retry; input commits only bounded nonsecret request
+ * data, never runtime environment or credential values. */
+export function admitCapturedInstanceAction({deployment,home,executionBinding,capability,action,input={},retryExecutionId,expectedStatus}) {
+  validateExecutionBinding(executionBinding);
+  if(expectedStatus!==undefined&&!STATUSES.has(expectedStatus))throw oatsError('invalid-declaration','invalid admission source state');
+  validateAdmittedAction(action,capability);canonicalJson(input,{maxBytes:128*1024,maxDepth:24,maxEntries:8192});
+  const inputIntegrity=jsonIntegrity(input);
+  return withPortableStateWrite(deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),{row,metadata}=matchedRow(index,home);
+    if(!same(row.executionBinding,executionBinding))throw oatsError("invalid-resolution","admission selection differs from current indexed incarnation");
+    if(expectedStatus!==undefined&&(row.status!==expectedStatus||metadata.captured.lifecycle!==expectedStatus)){
+      const error=oatsError('selection-changed','native admission no longer owns matching source lifecycle');error.home=row.home;
+      error.capturedCustody={incarnationId:row.incarnationId,executionBinding:row.executionBinding,indexedStatus:row.status,metadataStatus:metadata.captured.lifecycle,expectedStatus,held:true};
+      throw error;
+    }
+    let intent;
+    if(retryExecutionId!==undefined){
+      intent=row.intents.find(item=>item.executionId===retryExecutionId);
+      if(!intent||intent.capability!==capability||!same(intent.action,action)||!same(intent.inputIntegrity,inputIntegrity))throw oatsError("invalid-resolution","retry does not match the admitted action/input");
+      if(intent.state==="completed")return {intent:intentRef(row,intent),replayed:true,replayable:intent.replayable,receipt:intent.receipt};
+      if(!["unconfirmed","blocked"].includes(intent.state))throw oatsError("selection-changed","intent is admitted/running; explicit reconciliation is required before retry");
+      intent.attempt++;intent.state="admitted";
+    }else{
+      if(row.intents.some(item=>item.state!=="completed"))throw oatsError("selection-changed","an unsettled captured intent must be reconciled/retried, not replaced");
+      if(row.intents.length>=128)throw oatsError("resource-limit","captured intent history is full; no automatic pruning");
+      const previous=row.intents.findLast(item=>item.capability===capability);
+      const receipt=previous?previous.receipt:capability!==null&&metadata.capabilityMeta&&Object.hasOwn(metadata.capabilityMeta,capability)?metadata.capabilityMeta[capability]:null;
+      canonicalJson(receipt,RECEIPT_LIMITS);
+      intent={executionId:randomUUID(),capability,action,inputIntegrity,state:"admitted",attempt:1,receipt,replayable:false};row.intents.push(intent);
+    }
+    save(context,index);return {intent:intentRef(row,intent),replayed:false,receipt:intent.receipt};
+  });
+}
+function matchedIntent(row,ref,action) {
+  validateIntentRef(ref);const intent=row.intents.find(item=>item.executionId===ref.executionId);
+  if(row.incarnationId!==ref.incarnationId||!intent||intent.attempt!==ref.attempt||(action&&!same(intent.action,action)))throw oatsError("invalid-resolution","intent reference differs from indexed incarnation/action/attempt");
+  return intent;
+}
+export function readCapturedIntent({deployment,home,intent:ref,action}) {
+  const {row}=matchedRow(readCapturedInstanceIndex(deployment),home),intent=matchedIntent(row,ref,action);
+  return {...intent,incarnationId:row.incarnationId};
+}
+export function failCapturedNativeIntent(original,ref,receipt) {
+  canonicalJson(receipt,RECEIPT_LIMITS);
+  return withPortableStateWrite(original.executionBinding.deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),row=index.instances.find(item=>item.incarnationId===original.incarnationId);
+    if(!row||!sameAuthority(original,row))throw oatsError('selection-changed','native failure lost original indexed authority');
+    if(row.status!=='start-running')throw oatsError('selection-changed','native failure no longer owns lifecycle state');
+    const intent=matchedIntent(row,ref);
+    if(intent.action.kind!=='session'||intent.capability!==null)throw oatsError('invalid-resolution','native failure is not its session intent');
+    if(intent.state!=='completed'){intent.state='unconfirmed';intent.receipt=receipt;intent.replayable=false;}
+    row.status='start-failed-cleanup-required';save(context,index);return intentRef(row,intent);
+  });
+}
+/** An allocated native target is retained under the running logical intent
+ * BEFORE launch. It is an observation, not completion or a new identity. */
+export function observeCapturedNativeTarget(original,ref,receipt) {
+  validateCapturedInstanceReference(original);canonicalJson(receipt,RECEIPT_LIMITS);
+  return withPortableStateWrite(original.executionBinding.deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,original.home);
+    if(!sameAuthority(original,row)||row.status!=='start-running')throw oatsError('selection-changed','native target observation lost original lifecycle custody');
+    const intent=matchedIntent(row,ref);
+    if(intent.capability!==null||intent.action.kind!=='session'||intent.state!=='running')throw oatsError('selection-changed','native target observation needs the running admitted session');
+    intent.receipt=receipt;intent.replayable=false;save(context,index);return intentRef(row,intent);
+  });
+}
+export function beginCapturedIntent({deployment,home,intent:ref,action}) {
+  return withPortableStateWrite(deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,home),intent=matchedIntent(row,ref,action);
+    if(intent.state!=="admitted")throw oatsError("selection-changed","captured intent has already begun or settled");
+    intent.state="running";save(context,index);return intentRef(row,intent);
+  });
+}
+export function settleCapturedIntent({deployment,home,intent:ref,action,state,receipt,replayable=false}) {
+  if(typeof replayable!=="boolean")throw oatsError("invalid-declaration","invalid intent replay evidence");
+  if(!["completed","unconfirmed","blocked"].includes(state))throw oatsError("invalid-declaration","invalid captured intent outcome");
+  canonicalJson(receipt,RECEIPT_LIMITS);
+  return withPortableStateWrite(deployment,context=>{
+    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,home),intent=matchedIntent(row,ref,action);
+    if((state==="blocked"&&intent.state!=="admitted")||(state!=="blocked"&&intent.state!=="running"))throw oatsError("selection-changed","intent outcome does not match its admitted/running attempt");
+    intent.state=state;intent.receipt=receipt;intent.replayable=state==="completed"&&replayable;save(context,index);return intentRef(row,intent);
+  });
+}

package/lib/captured-invocation-context.mjs

@@ -0,0 +1,130 @@
+/** Provider-neutral captured action/lifecycle context. Provider bindings remain in
+ * OATS_BINDING_FILE; this companion supplies record/target intent and prior
+ * opaque provider receipt without provider-specific kernel fields. */
+import { lstatSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { readCapturedInstanceAuthority, readCapturedIntent } from "./captured-instance-index.mjs";
+import { validateIncarnationId, validateIntentRef } from "./captured-admission-shape.mjs";
+import { isAbsolute, join, resolve } from "node:path";
+import { canonicalJson } from "./portable-values.mjs";
+import { objectAt, stringAt } from "./portable-shape.mjs";
+import { portableScope, portableStateDirectory } from "./portable-state.mjs";
+import { validateExecutionBinding } from "./schedule-capsule.mjs";
+import { validateCapturedSubject, validateCapturedContext, validateMessagingChoice } from "./resolution-shape.mjs";
+import { validateCapturedAction } from "./captured-action-shape.mjs";
+import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
+import { oatsError } from "./errors.mjs";
+
+export const CAPTURED_INVOCATION_CONTEXT_LIMITS = Object.freeze({ maxBytes: 512 * 1024, maxDepth: 32, maxEntries: 16_384 });
+export const CAPTURED_PRIOR_RECEIPT_LIMITS = Object.freeze({ maxBytes: 128 * 1024, maxDepth: 24, maxEntries: 8192 });
+const FIELDS = ["schemaVersion", "executionBinding", "subject", "instance", "context", "responsibleHuman", "messagingChoice", "capability", "action", "priorReceipt", "intent"];
+
+function human(value, pointer) {
+  if (value === null) return;
+  objectAt(value, ["provider", "id"], ["provider", "id"], pointer);
+  stringAt(value.provider, `${pointer}/provider`); stringAt(value.id, `${pointer}/id`);
+}
+
+export function validateCapturedInvocationContext(value) {
+  canonicalJson(value, CAPTURED_INVOCATION_CONTEXT_LIMITS); objectAt(value, FIELDS, FIELDS);
+  if (value.schemaVersion !== 1) throw oatsError("unsupported-wire-version", "captured invocation context schemaVersion must be 1");
+  validateExecutionBinding(value.executionBinding);
+  validateCapturedSubject(value.subject);
+  const subjectName = value.subject.kind === "persistent" ? value.subject.soul.alias : value.subject.name;
+  if (value.instance !== null) {
+    objectAt(value.instance, ["home", "work", "name", "agent", "incarnationId"], ["home", "work", "name", "agent", "incarnationId"], "/instance");
+    validateIncarnationId(value.instance.incarnationId);
+    for (const key of ["home", "work"]) {
+      stringAt(value.instance[key], `/instance/${key}`);
+      if (!isAbsolute(value.instance[key]) || resolve(value.instance[key]) !== value.instance[key] || value.instance[key].includes("\0")) throw oatsError("invalid-declaration", `captured invocation ${key} must be normalized absolute`);
+    }
+    stringAt(value.instance.name, "/instance/name"); stringAt(value.instance.agent, "/instance/agent");
+    if (value.instance.agent !== subjectName || value.instance.work !== join(value.instance.home, "work")) throw oatsError("invalid-resolution", "captured invocation target differs from its subject/home");
+  }
+  validateCapturedContext(value.context);
+  human(value.responsibleHuman, "/responsibleHuman");
+  // Reuse the existing messaging-choice codec, not another privacy/policy model.
+  const messagingProvider = value.messagingChoice?.enabled === true ? value.messagingChoice.privateKey?.provider : undefined;
+  if (messagingProvider !== undefined && !isMaterializedCapabilityId(messagingProvider)) throw oatsError("invalid-declaration", "invalid invocation messaging provider");
+  validateMessagingChoice(value.messagingChoice, { context: value.context,
+    bindings: messagingProvider === undefined ? {} : { messaging: { capability: messagingProvider } } });
+  const expectedHuman = value.messagingChoice.enabled ? value.messagingChoice.privateKey.human : null;
+  if (canonicalJson(value.responsibleHuman) !== canonicalJson(expectedHuman)) throw oatsError("invalid-resolution", "invocation responsible human differs from captured messaging choice");
+  if (!isMaterializedCapabilityId(value.capability)) throw oatsError("invalid-declaration", "invalid invocation capability");
+  validateCapturedAction(value.action);
+  if (value.action.capability !== undefined && value.action.capability !== value.capability) throw oatsError("invalid-resolution", "invocation action capability differs from its owner");
+  if (value.action.kind === "hook" && value.instance === null) throw oatsError("invalid-resolution", "captured instance hook requires instance facts");
+  if (value.intent !== null) {
+    validateIntentRef(value.intent);
+    if (value.instance === null || value.intent.incarnationId !== value.instance.incarnationId) throw oatsError("invalid-resolution", "intent belongs to a different incarnation");
+  }
+  canonicalJson(value.priorReceipt, CAPTURED_PRIOR_RECEIPT_LIMITS);
+  return value;
+}
+
+export function buildCapturedInvocationContext(input) {
+  const { loaded, action, instance = null } = input;
+  if (!loaded?.record || !loaded?.resolution || !loaded?.capability) throw oatsError("invalid-resolution", "captured invocation context requires one verified action");
+  const { record } = loaded, subject = record.subject;
+  const subjectName = subject.kind === "persistent" ? subject.soul.alias : subject.name;
+  if (instance !== null && instance.agent !== subjectName) throw oatsError("invalid-resolution", "captured invocation target agent differs from retained subject");
+  const expectedHuman = record.messagingChoice.enabled ? record.messagingChoice.privateKey.human : null;
+  let priorReceipt = null, target = null;
+  const intent = input.intent ?? null;
+  if (instance !== null) {
+    canonicalJson(instance);
+    objectAt(instance, ["home", "work", "name", "agent"], ["home", "work", "name", "agent"]);
+    if (typeof instance.home !== "string" || !isAbsolute(instance.home) || instance.work !== join(instance.home, "work")) throw oatsError("invalid-resolution", "captured invocation needs an explicit home/work target");
+    const home = portableScope(instance.home);
+    if (!lstatSync(instance.home).isDirectory()) throw oatsError("invalid-resolution", "captured invocation home must not be a symlink");
+    const { metadata, row } = readCapturedInstanceAuthority(loaded.deployment, home);
+    target = { ...instance, incarnationId: metadata.incarnationId };
+    validateExecutionBinding(metadata.executionBinding);
+    if (typeof metadata.home !== "string" || portableScope(metadata.home) !== home || metadata.instance !== instance.name
+      || metadata.agent !== instance.agent || metadata.kind !== subject.kind
+      || portableScope(metadata.executionBinding.deployment) !== portableScope(loaded.deployment)
+      || canonicalJson(metadata.executionBinding.resolution) !== canonicalJson(loaded.resolution)
+      || canonicalJson(metadata.responsibleHuman) !== canonicalJson(expectedHuman)) throw oatsError("invalid-resolution", "invocation target differs from captured instance metadata/record");
+    if (metadata.capabilityMeta !== undefined) objectAt(metadata.capabilityMeta, null, []);
+    const previous = row.intents.findLast(entry => entry.capability === loaded.capability.id);
+    priorReceipt = previous ? previous.receipt : metadata.capabilityMeta && Object.hasOwn(metadata.capabilityMeta, loaded.capability.id) ? metadata.capabilityMeta[loaded.capability.id] : null;
+  }
+  if (intent !== null) {
+    if (!target) throw oatsError("invalid-resolution", "admitted action requires an owned instance");
+    const admitted = readCapturedIntent({ deployment: loaded.deployment, home: instance.home, intent, action });
+    if (admitted.capability !== loaded.capability.id || !["admitted", "running"].includes(admitted.state)) throw oatsError("invalid-resolution", "invocation does not match an active admitted capability action");
+    priorReceipt = admitted.receipt;
+  }
+  if (Object.hasOwn(input, "priorReceipt") && canonicalJson(input.priorReceipt) !== canonicalJson(priorReceipt)) throw oatsError("invalid-resolution", "invocation prior receipt differs from stored provider receipt");
+  const value = { schemaVersion: 1,
+    executionBinding: { schemaVersion: 1, deployment: portableScope(loaded.deployment), resolution: loaded.resolution },
+    subject, instance: target, intent, context: record.context, responsibleHuman: expectedHuman,
+    messagingChoice: record.messagingChoice, capability: loaded.capability.id, action, priorReceipt };
+  return validateCapturedInvocationContext(structuredClone(value));
+}
+
+export function withCapturedInvocationContextFile(invocation, run) {
+  validateCapturedInvocationContext(invocation);
+  if (typeof run !== "function") throw oatsError("invalid-declaration", "captured invocation context consumer must be a function");
+  const directory = mkdtempSync(join(portableStateDirectory(invocation.executionBinding.deployment, true), ".invocation-context-"));
+  const owned = lstatSync(directory), file = join(directory, "context.json"); let primary, result, completed = false;
+  try {
+    writeFileSync(file, canonicalJson(invocation, CAPTURED_INVOCATION_CONTEXT_LIMITS), { flag: "wx", mode: 0o600 });
+    result = run({ OATS_INVOCATION_CONTEXT_FILE: file }); completed = true; return result;
+  } catch (error) { primary = error; throw error; }
+  finally {
+    try {
+      const current = lstatSync(directory);
+      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("integrity-drift", "invocation context directory ownership changed");
+      rmSync(directory, { recursive: true });
+    } catch (cleanup) {
+      if (!primary) {
+        const error = new AggregateError([cleanup], "captured invocation context cleanup failed after invocation", { cause: cleanup });
+        error.code = cleanup.code; error.invocationCompleted = completed; error.invocationResult = result; throw error;
+      }
+      const error = new AggregateError([primary, cleanup], "captured invocation context and cleanup failed", { cause: primary });
+      error.code = primary.code;
+      if (primary.invocationCompleted) { error.invocationCompleted = true; error.invocationResult = primary.invocationResult; }
+      throw error;
+    }
+  }
+}

package/lib/captured-launch-request.mjs

@@ -0,0 +1,46 @@
+/** Explicit portable launch input, not a current launch-config/model resolver.
+ * OATS-managed entrypoints are retained; external host tools are explicitly
+ * selected/preflighted, not forced into a new capability layer. */
+import { isAbsolute, resolve } from 'node:path';
+import { canonicalJson } from './portable-values.mjs';
+import { objectAt, stringAt } from './portable-shape.mjs';
+import { isMaterializedCapabilityId } from './capability-provenance.mjs';
+import { oatsError } from './errors.mjs';
+import { PI_SDK_HOST, validatePiHostRecipe } from './pi-sdk-host.mjs';
+
+export function validateCapturedLaunchRequest(value, validateConfig) {
+  canonicalJson(value,{maxBytes:128*1024,maxDepth:16,maxEntries:4096});
+  objectAt(value,['runtime','executable','args','env','model','yolo'],['runtime','executable','args','env','model','yolo']);
+  if(typeof value.executable==='string'){
+    stringAt(value.executable,'/launch/executable');
+    if(!isAbsolute(value.executable)||resolve(value.executable)!==value.executable||value.executable.includes('\0'))throw oatsError('invalid-declaration','host launch executable must be explicit normalized absolute text');
+  }else{
+    objectAt(value.executable,['capability','command'],['capability','command']);
+    if(!isMaterializedCapabilityId(value.executable.capability))throw oatsError('invalid-declaration','managed launch entrypoint must name a selected capability');
+    stringAt(value.executable.command,'/launch/executable/command');
+  }
+  stringAt(value.model,'/launch/model');
+  if(typeof value.yolo!=='boolean')throw oatsError('invalid-declaration','captured launch requires explicit yolo');
+  validateConfig('captured',{...value,executable:'captured-resource'},'explicit launch request');
+  if(value.executable===PI_SDK_HOST || value.args?.includes('--oats-pi-host'))validatePiHostRecipe(value);
+  // All kernel/provider invocation aliases remain kernel-owned on this new
+  // surface. The legacy launch-config validator has a narrower historical list.
+  for(const name of Object.keys(value.env))if(/^(OATS_|PI_AGENT_|OAS_)/.test(name)||name==='PI_AGENTS_ROOT')throw oatsError('invalid-declaration','launch environment cannot override captured authority');
+  return value;
+}
+
+export function compileCapturedLaunchRequest(request,{artifacts,manifests,settings,resources},kernel) {
+  if(request===undefined)return null;
+  validateCapturedLaunchRequest(request,kernel.validateLaunchConfig);
+  const required=kernel.runtimeRequirements(request.runtime,[...manifests].filter(([id])=>Object.hasOwn(artifacts.capabilities,id)).map(([id,manifest])=>({id,manifest,settings:settings[id]})));
+  if(required.length)throw oatsError('needs-configuration','runtime package requirements need retained runtime roots and a qualified loader; no ambient package discovery was used');
+  const base={version:1,runtime:request.runtime,args:request.args,env:request.env,model:request.model,yolo:request.yolo,
+    hooks:{launch:{},env:{},contributions:[],pending:true},prompt:{kind:'task-file',file:'TASK.md'}};
+  if(typeof request.executable==='string')return {...base,executable:request.executable,executableResolvedFrom:'explicit-host'};
+  const {capability:id,command}=request.executable,manifest=manifests.get(id);
+  if(!Object.hasOwn(artifacts.capabilities,id)||!manifest?.commands||!Object.hasOwn(manifest.commands,command))throw oatsError('capability-not-selected','launch entrypoint is not declared by a selected capability');
+  const key=`executable:${id}:command:${command}`;
+  if(!Object.hasOwn(resources,key)||resources[key].kind!=='file')throw oatsError('resolution-incomplete','launch entrypoint lacks a retained executable resource');
+  const [, ...declaredArgs]=manifest.commands[command].trim().split(/\s+/);
+  return {...base,executable:'captured-resource',executableResource:key,entrypoint:{capability:id,command},args:[...declaredArgs,...request.args]};
+}

package/lib/captured-operation-process.mjs

@@ -0,0 +1,15 @@
+/** Bounded runner for one already-verified captured provider operation. The
+ * caller owns receipt interpretation and invocation-snapshot cleanup. */
+import { spawnSync } from "node:child_process";
+import { oatsError } from "./errors.mjs";
+
+export const CAPTURED_OPERATION_TIMEOUT_MS = 4 * 60 * 1000;
+
+export function runCapturedOperationProcess({ file, args = [], cwd, env, timeoutMs = CAPTURED_OPERATION_TIMEOUT_MS }) {
+  if (typeof file !== "string" || !file || !Array.isArray(args) || args.some((arg) => typeof arg !== "string")) throw oatsError("invalid-declaration", "captured operation executable and arguments must be text");
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > CAPTURED_OPERATION_TIMEOUT_MS) throw oatsError("invalid-declaration", `captured operation timeout must be 1-${CAPTURED_OPERATION_TIMEOUT_MS}ms`);
+  return spawnSync(process.execPath, [file, ...args], {
+    cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 16 * 1024 * 1024, timeout: timeoutMs, killSignal: "SIGKILL",
+  });
+}

package/lib/captured-pi-custody.mjs

@@ -0,0 +1,29 @@
+/** Kernel side of the Pi record-witness seam. Record support is deliberately
+ * capability-checked before admission: older path-only readers cannot launch a
+ * protected host. The record-library implementation is separately owned. */
+import { basename, dirname, join } from "node:path";
+import * as records from "../packages/record/lib/native-history.mjs";
+import { oatsError } from "./errors.mjs";
+
+export function capturedPiSessionDirectory(home) {
+  const history = records.nativeHistoryPath(home);
+  return join(dirname(history), `${basename(history)}.pi`);
+}
+
+export function requireCapturedPiRecordSupport() {
+  if (records.CAPTURED_PI_RECORD_VERSION !== 2
+    || ["inspectCapturedPiRoot", "prepareCapturedPiStart", "assertCapturedPiStart"].some(name => typeof records[name] !== "function")) {
+    throw oatsError("E_PI_HOST_RECORD_UNAVAILABLE", "captured Pi requires complete versioned native-root discovery/read/capture guards; path-only record support cannot launch it");
+  }
+  return records;
+}
+
+export function inspectCapturedPiRoot(home, authority) {
+  return requireCapturedPiRecordSupport().inspectCapturedPiRoot(home, authority);
+}
+export function prepareCapturedPiStart(home, authority) {
+  return requireCapturedPiRecordSupport().prepareCapturedPiStart(home, authority);
+}
+export function assertCapturedPiStart(home, nativeRecordId, authority) {
+  return requireCapturedPiRecordSupport().assertCapturedPiStart(home, nativeRecordId, authority);
+}