@visual-z/xeno 0.2.0 → 0.3.0

package/src/runtime/recovery-coverage.ts

@@ -0,0 +1,71 @@
+/** R12c: collect all started trials, including crash prefixes, without provider access. */
+import { join, resolve } from "node:path";
+import { requestAccounting, summarizeRecoveryCoverage, type TrialCoverage } from "../core/evaluation-coverage.ts";
+import { deriveRecoveryMetrics } from "../core/recovery-evaluation.ts";
+import type { EvalResult } from "../core/experiment.ts";
+import { isTrialLifecycle } from "../core/trial-lifecycle.ts";
+import { readCursor } from "../store/log.ts";
+import { readNodeHistory } from "../store/restore.ts";
+import { auditEvalJob, auditEvalRequests, evalDirectory, type EvalPlan, type EvalEnd } from "./harness-eval.ts";
+import type { GatewayRecord } from "./harness-comparison.ts";
+import { verifiedRecoveryRetrievals } from "./recovery-evidence.ts";
+
+export function requestPrefix(body: string): { records: GatewayRecord[]; tail: "complete" | "truncated" } {
+  const chunks = body.split("\n"), records: GatewayRecord[] = [];
+  let tail: "complete" | "truncated" = "complete";
+  for (const [index, line] of chunks.entries()) {
+    if (!line && index === chunks.length - 1) continue;
+    try { records.push(JSON.parse(line) as GatewayRecord); }
+    catch {
+      if (index !== chunks.length - 1) throw Error("corrupt request ledger interior");
+      tail = "truncated";
+    }
+  }
+  return { records, tail };
+}
+
+export async function inspectRecoveryTrials(output: string, plan: EvalPlan, audit = false) {
+  if (![2, 5].includes(plan.version)) throw Error("complete coverage needs protocol v2 or v5");
+  const trials: TrialCoverage[] = [], results: EvalResult[] = [];
+  let charged = 0, halted = false;
+  for (const job of plan.jobs) {
+    const directory = evalDirectory(output, job), startPath = join(directory, "trial-start.json");
+    const requestsPath = join(directory, "requests.jsonl"), resultPath = join(directory, "result.json"), endPath = join(directory, "end.json");
+    if (!await Bun.file(startPath).exists()) {
+      if (await Bun.file(requestsPath).exists() || await Bun.file(resultPath).exists() || await Bun.file(endPath).exists()) throw Error("trial evidence lacks start identity");
+      continue;
+    }
+    const start = await Bun.file(startPath).json() as { job: string; ledgerBefore: number };
+    if (start.job !== job.id || start.ledgerBefore !== charged || halted) throw Error("global recovery ledger sequence changed");
+    const prefix = requestPrefix(await Bun.file(requestsPath).exists() ? await Bun.file(requestsPath).text() : "");
+    const end = await Bun.file(endPath).exists() ? await Bun.file(endPath).json() as EvalEnd : undefined;
+    if (end?.lifecycle && !isTrialLifecycle(end.lifecycle)) throw Error("invalid recovery lifecycle");
+    const accounting = requestAccounting(prefix.records, start.ledgerBefore);
+    if (end && (end.ledgerBefore !== start.ledgerBefore || end.ledgerAfter !== accounting.charged || prefix.tail !== "complete")) throw Error("recovery end differs from request ledger");
+    let result: EvalResult | undefined;
+    if (await Bun.file(resultPath).exists()) {
+      if (!end || prefix.tail !== "complete" || accounting.unsettledRequests) throw Error("final result lacks settled source");
+      result = audit ? await auditEvalJob(directory, plan, job) : await Bun.file(resultPath).json() as EvalResult;
+      if (result.id !== job.id) throw Error("result identity changed");
+      results.push(result);
+    } else if (audit) await auditEvalRequests(directory, plan, job, { records: prefix.records, ledgerBefore: start.ledgerBefore, allowPending: true });
+    let partialMetrics: EvalResult["recovery"];
+    // During request callbacks the cursor can be behind the active append; only
+    // an offline audit reads incomplete tool metrics and labels its outcome unknown.
+    if (audit && !result) {
+      const cursor = await readCursor(join(directory, "log"));
+      if (cursor) {
+        const history = await readNodeHistory(join(directory, "log"), cursor.node, undefined, "context");
+        if (!history.ok) throw Error(history.error);
+        const originals = await verifiedRecoveryRetrievals(directory, history.nodes, plan.limits.maxOutputBytes!);
+        partialMetrics = deriveRecoveryMetrics(history.nodes, new Set(originals.keys()), null, path => resolve(directory, "workspace", path));
+      }
+    }
+    trials.push({ id: job.id, accounting, tail: prefix.tail, ...(result ? { result } : {}),
+      ...(partialMetrics ? { partialMetrics } : {}), interruption: end?.lifecycle?.interruption?.source ?? null });
+    charged = accounting.charged;
+    halted = end === undefined || end.ledgerHalted === true || !accounting.fullyMeasured || prefix.tail === "truncated" ||
+      prefix.records.some(row => row.kind === "settled" && (row.failure !== null || row.measured !== null && row.measured > row.reservation));
+  }
+  return { trials, results, ledger: { budget: plan.budget, charged, halted }, summary: summarizeRecoveryCoverage(plan.jobs, trials, plan.mechanicalOnly) };
+}

package/src/runtime/recovery-evidence.ts

@@ -0,0 +1,76 @@
+/** R12c: offline evidence readers verify source bytes and never rerun commands. */
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import type { LogEvent } from "../core/events.ts";
+import { historyEntries } from "../core/history-query.ts";
+import { readObservation } from "../store/observations.ts";
+import { isRuntimeTargetReceipt } from "../core/runtime-target.ts";
+
+export function recoveryWorkEvents(events: readonly LogEvent[], last: string | undefined): LogEvent[] {
+  const at = events.findIndex(event => event.id === last);
+  if (at < 0 || events.slice(at + 1).some(event => !["process_exit", "target_observation"].includes(event.t)))
+    throw Error("invalid recovery work boundary");
+  return events.slice(0, at + 1);
+}
+const equal = (left: unknown, right: unknown) => JSON.stringify(left) === JSON.stringify(right);
+const originalFields = (entry: unknown) => {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
+  // Consumption-time freshness is metadata around the immutable event, not
+  // part of the original observation whose bytes this metric verifies.
+  const { environment: _freshness, ...original } = entry as Record<string, unknown>;
+  return original;
+};
+export async function verifiedRecoveryRetrievals(directory: string, nodes: readonly { node: number; events: readonly LogEvent[] }[], maxOutputBytes: number) {
+  const result = new Map<string, { source: string; text: string }>();
+  const calls = new Map<string, { name: string; input: unknown }>();
+  const prefix: { node: number; events: LogEvent[] }[] = [];
+  for (const part of nodes) {
+    const seen: LogEvent[] = []; prefix.push({ node: part.node, events: seen });
+    for (const event of part.events) {
+      if (event.t === "assistant") for (const block of event.blocks) if (block.type === "tool_use") calls.set(`${part.node}:${block.call_id}`, block);
+      if (event.t === "tool_invocation") calls.set(`${part.node}:${event.call_id}`, { name: event.name, input: event.input ?? calls.get(`${part.node}:${event.call_id}`)?.input });
+      if (event.t === "tool_result" && event.ok) {
+        const call = calls.get(`${event.invocation_ref?.node ?? part.node}:${event.call_id}`);
+        const input = call?.input as Record<string, unknown> | undefined;
+        if (call?.name === "history" && input) {
+          if (typeof input["artifact"] === "string") {
+            const page = await readObservation(join(directory, "observations"), input["artifact"], Number(input["offset"] ?? 0), Math.max(1, Math.floor(maxOutputBytes / 3)));
+            // Only bytes actually delivered to the model count; an archived but
+            // clipped response still requires another retrieval by the agent.
+            let delivered: unknown;
+            try { delivered = JSON.parse(event.content); }
+            catch {
+              // JSON escaping can make even a bounded byte page exceed the
+              // preview. Verify its archive, but do not credit unseen bytes.
+              if (!event.content_ref) throw Error("unreadable recovery artifact receipt");
+              const stored = await Bun.file(event.content_ref.path).text();
+              if (createHash("sha256").update(stored).digest("hex") !== event.content_ref.sha256 || !equal(JSON.parse(stored), page))
+                throw Error("recovery artifact archive differs from original bytes");
+            }
+            if (delivered !== undefined && !equal(delivered, page)) throw Error("recovery artifact receipt differs from original bytes");
+            if (delivered !== undefined && page.base64) result.set(`${part.node}:${event.id}`, { source: page.sha256, text: page.text });
+          } else if (typeof input["event"] === "string" || Array.isArray(input["events"])) {
+            const entries = historyEntries(prefix), ids = typeof input["event"] === "string" ? [input["event"]] : input["events"] as unknown[];
+            const originals = ids.map(id => entries.find(entry => entry.event === id));
+            let delivered: unknown;
+            try { delivered = JSON.parse(event.content); } catch { /* a clipped index is not a complete original event */ }
+            const batch = delivered as { items?: unknown[]; missing?: unknown[] } | undefined;
+            const actual = typeof input["event"] === "string" ? [delivered] : Array.isArray(batch?.items) && equal(batch?.missing, []) ? batch.items : [];
+            if (originals.every(Boolean) && equal(actual.map(originalFields), originals)) result.set(`${part.node}:${event.id}`,
+              { source: originals.map(entry => entry!.event).join(","), text: originals.map(entry => entry!.text).join("\n") });
+          }
+        }
+      }
+      if (event.t === "target_observation" && event.observation.state === "ready") {
+        const receipt = event.observation;
+        if (!isRuntimeTargetReceipt(receipt) || !receipt.manifest) throw Error("invalid target receipt");
+        const body = await Bun.file(receipt.manifest.path).text();
+        if (createHash("sha256").update(body).digest("hex") !== receipt.manifest.sha256) throw Error("target observation source changed");
+        const archived = JSON.parse(body) as { observation: unknown }, { manifest: _manifest, ...original } = receipt;
+        if (!equal(archived.observation, original)) throw Error("target observation differs from archived capture");
+      }
+      seen.push(event);
+    }
+  }
+  return result;
+}

package/src/runtime/recovery-fixtures.ts

@@ -0,0 +1,116 @@
+/** R12c: sanitized, executable analogues of the audit's failure mechanisms. */
+import {createHash} from "node:crypto";
+import {seededRandom} from "../core/experiment.ts";
+import {recoveryCase,RECOVERY_TASKS,RECOVERY_SOURCE_REPORT,type RecoveryTask} from "../core/recovery-corpus.ts";
+import type {AcceptanceContract} from "../core/acceptance.ts";
+import type {EvalFixture,EvalPlan} from "./harness-eval.ts";
+import type {ComparisonBackend} from "./harness-comparison.ts";
+
+const digest=(text:string)=>createHash("sha256").update(text).digest("hex");
+export const RECOVERY_SYSTEM="Solve the supplied recovery task using actual file and tool evidence. Preserve the fixture and verifier inputs. " +
+  "Inspect failed-call premises before retrying. A clipped preview is not the complete source. Recover closed process evidence without replaying its effects. " +
+  "Verify the requested artifacts with bun run gate. Building, observing a running target, and the user's acceptance are separate facts. " +
+  "Report unavailable capabilities or pending human review honestly. Work within this session without delegation.";
+export function recoveryFixture(seed:number,task:RecoveryTask,repeat:number):EvalFixture{
+  const specification=recoveryCase(task)!,random=seededRandom(seed+RECOVERY_TASKS.indexOf(task)*1000+repeat);
+  const answer=Array.from({length:4},()=>Math.floor(random()*0x100000000).toString(16).padStart(8,"0")).join("")+"\n";
+  const files:Record<string,string>={"source.txt":`CODE=${answer}`,"package.json":JSON.stringify({scripts:{gate:"bun verify.ts",build:"bun build.ts"}})+"\n"};
+  const goals:Record<string,string>={"answer.txt":digest(answer)},mutable=["answer.txt"];
+  let scenario="Copy the CODE value from source.txt to answer.txt with one trailing newline. ";
+  if(task==="recovery-missing-path"){
+    files["answer.txt"]="pending\n";scenario+="Replace pending in answer.txt; an earlier editor request omitted path. Use the actual file identity. ";
+  }else if(task==="recovery-stale-version"){
+    files["draft.txt"]="before\nexternal change\n";mutable.push("draft.txt");goals["draft.txt"]=digest("after\nexternal change\n");
+    scenario+=`Change before to after in draft.txt while retaining its other line. An old observation had sha256 ${digest("before\n")}; it may be stale. `;
+  }else if(task==="recovery-long-output"){
+    files["source.txt"]="x".repeat(5000)+`CODE=${answer.trim()}`+"y".repeat(10000)+"\n";
+    scenario="Recover the 32 hexadecimal characters after CODE= in source.txt and put them in answer.txt with one trailing newline. The line exceeds a preview; use immutable original evidence when needed. ";
+  }else if(task==="recovery-api-mismatch"){
+    files["compat.ts"]='// Portable legacy API fixture; the optional filter flag is unsupported.\n'+
+      'if(Bun.argv.some(arg=>arg.startsWith("--filter")))throw new TypeError("extract() does not support the filter option");\n'+
+      'const source=await Bun.file("source.txt").text();await Bun.write("answer.txt",source.slice(5));\n';
+    scenario+="The local compat.ts implements a legacy API; a suggested invocation was bun compat.ts --filter=safe. Inspect what this installed implementation supports before using it. ";
+  }else if(task==="recovery-closed-process"){
+    files["producer.ts"]='const count=Number(await Bun.file("counter.txt").text().catch(()=>"0"));await Bun.write("counter.txt",String(count+1));console.log((await Bun.file("source.txt").text()).trim());\n';
+    goals["counter.txt"]=digest("1");mutable.push("counter.txt");
+    scenario="Run bun producer.ts exactly once to obtain CODE. It increments a counter and exits. Recover its terminal receipt if further process input fails; do not launch it again. Put CODE in answer.txt with one newline. ";
+  }else if(task==="recovery-unchanged-retry"){
+    files["draft.txt"]="present\n";mutable.push("draft.txt");goals["draft.txt"]=digest("fixed\n");
+    scenario+="Change the actual draft.txt anchor to fixed. A proposed old_string was absent; changing only new_string would not repair a missing anchor. ";
+  }else if(task==="recovery-runtime-acceptance"){
+    files["app-source.js"]='console.log("fixture preview ready");setInterval(()=>{},1000);\n';
+    files["build.ts"]='import {mkdir,copyFile} from "node:fs/promises";await mkdir("dist",{recursive:true});await copyFile("app-source.js","dist/app.js");\n';
+    goals["dist/app.js"]=digest(files["app-source.js"]);
+    scenario+="Build with bun run build, recording artifacts {paths:[\"dist/app.js\"],output_roots:[\"dist\"]}, and start the declared preview with target. A previous build or a missing target does not prove this instance is ready. Leave its human review pending. The harness closes the temporary preview after this trial. ";
+  }else if(task==="recovery-eof")scenario+="A suggested read starts at line 999; recover from the real file boundary rather than assuming that line exists. ";
+  files["verify.ts"]=`import {createHash} from "node:crypto";const goals=${JSON.stringify(goals)};for(const [path,sha] of Object.entries(goals)){const text=await Bun.file(path).text().catch(()=>"");if(createHash("sha256").update(text).digest("hex")!==sha)process.exit(1);}\n`;
+  return {task,repeat,files,digests:Object.fromEntries(Object.entries(files).filter(([path])=>!mutable.includes(path)).map(([path,text])=>[path,digest(text)])),
+    answerSha256:digest(answer),prompts:[scenario+"Preserve verifier and fixture inputs, run bun run gate, and report the actual acceptance state."],
+    recovery:{sourceReport:RECOVERY_SOURCE_REPORT,specification,answer,goalDigests:goals,mutableFiles:mutable}};
+}
+export function recoveryContract(plan:EvalPlan):AcceptanceContract{
+  if(!plan.runtime.bunExecutable)throw Error("recovery runtime identity missing");
+  return {version:1,id:"recovery-preview",criteria:[
+    {id:"gate",kind:"command",command:"bun run gate",description:"The requested outputs pass the frozen verifier"},
+    {id:"build",kind:"command",command:"bun run build",description:"The current preview is built"},
+    {id:"review",kind:"human",target:"preview",description:"The author reviews this exact running preview"}],
+    targets:[{id:"preview",build:"build",artifacts:{paths:["dist/app.js"],output_roots:["dist"]},entry:"dist/app.js",interpreter:plan.runtime.bunExecutable}]};
+}
+
+/** A deterministic driver tests the protocol and grader, not model competence. */
+export function recoveryFixtureBackend(input:EvalFixture):ComparisonBackend{
+  if(!input.recovery)throw Error("recovery fixture metadata missing");
+  const answer=input.recovery.answer;let step=0;
+  return async payload=>{
+    const messages=payload["messages"] as {role:string;content?:unknown}[];
+    const text=messages.filter(message=>message.role==="tool").map(message=>typeof message.content==="string"?message.content:JSON.stringify(message.content)).join("\n");
+    const required=(pattern:RegExp)=>{const match=pattern.exec(text);if(!match)throw Error("fixture driver could not find the original tool receipt");return match[1]!;};
+    const calls:{name:string;input:unknown}[]=[],index=step++;
+    const call=(name:string,args:unknown)=>calls.push({name,input:args});
+    const read=()=>call("read",{path:"source.txt"}),write=()=>call("write",{path:"answer.txt",content:answer}),gate=()=>call("exec_command",{cmd:"bun run gate",yield_time_ms:1000});
+    switch(input.task){
+      case "recovery-missing-path":
+        if(index===0)call("edit",{old_string:"pending",new_string:answer.trim()});
+        if(index===1){read();call("read",{path:"answer.txt"});}
+        if(index===2)call("edit",{path:"answer.txt",old_string:"pending",new_string:answer.trim()});
+        if(index===3)gate();break;
+      case "recovery-stale-version":
+        if(index===0)call("edit",{path:"draft.txt",expected_sha256:digest("before\n"),old_string:"before",new_string:"after"});
+        if(index===1)call("read",{path:"draft.txt"});
+        if(index===2)call("edit",{path:"draft.txt",old_string:"before",new_string:"after"});
+        if(index===3)read();if(index===4)write();if(index===5)gate();break;
+      case "recovery-long-output":
+        if(index===0)read();
+        if(index===1)call("history",{artifact:required(/sha256: ([a-f0-9]{64})/),offset:4500});
+        if(index===2)write();if(index===3)gate();break;
+      case "recovery-api-mismatch":
+        if(index===0)call("exec_command",{cmd:"bun compat.ts --filter=safe",yield_time_ms:1000});
+        if(index===1)call("read",{path:"compat.ts"});
+        if(index===2)call("exec_command",{cmd:"bun compat.ts",yield_time_ms:1000});
+        if(index===3)gate();break;
+      case "recovery-closed-process":
+        if(index===0)call("exec_command",{cmd:"bun producer.ts",yield_time_ms:5000});
+        if(index===1)call("history",{recent:true,tool:"exec_command"});
+        if(index===2||index===3)call("write_stdin",{session_id:Number(required(/"session_id"\s*:\s*(\d+)/)),chars:index===2?"repeat\n":"",yield_time_ms:100});
+        if(index===4)write();if(index===5)gate();break;
+      case "recovery-unchanged-retry":
+        if(index===0||index===3)call("read",{path:"draft.txt"});
+        if(index===1||index===2)call("edit",{path:"draft.txt",old_string:"absent",new_string:index===1?"first":"second"});
+        if(index===4)call("edit",{path:"draft.txt",old_string:"present",new_string:"fixed"});
+        if(index===5)read();if(index===6)write();if(index===7)gate();break;
+      case "recovery-runtime-acceptance":
+        if(index===0||index===4)call("target",{action:"start",target:"preview",yield_time_ms:100});
+        if(index===1)read();if(index===2)write();
+        if(index===3)call("exec_command",{cmd:"bun run build",artifacts:{paths:["dist/app.js"],output_roots:["dist"]},yield_time_ms:1000});
+        if(index===5)gate();break;
+      case "recovery-eof":
+        if(index===0)call("read",{path:"source.txt",start:999});
+        if(index===1)read();if(index===2)write();if(index===3)gate();break;
+      default:throw Error("not a recovery fixture");
+    }
+    return {id:`recovery-${index}`,model:"eval-mechanical",choices:[{index:0,message:{role:"assistant",
+      content:calls.length?null:input.task==="recovery-runtime-acceptance"?"Preview preparation ended; the author's acceptance is pending.":"Recovery fixture finished.",
+      ...(calls.length?{tool_calls:calls.map((item,i)=>({id:`recovery-${index}-${i}`,type:"function",function:{name:item.name,arguments:JSON.stringify(item.input)}}))}:{})},
+      finish_reason:calls.length?"tool_calls":"stop"}],usage:{prompt_tokens:200,completion_tokens:32,prompt_cache_hit_tokens:0}};
+  };
+}

package/src/runtime/runtime-target.ts

@@ -0,0 +1,149 @@
+/** R8: live capabilities stay with their Session; only observations cross a log boundary. */
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import type { LogEvent, ArtifactRef } from "../core/events.ts";
+import { deriveAcceptance, type AcceptanceState } from "../core/acceptance.ts";
+import { canonicalValue } from "../core/continuation.ts";
+import { isCommandArtifactReceipt, sameArtifactIdentity, type CommandArtifactReceipt } from "../core/command-artifacts.ts";
+import { targetIsReady, type RuntimeTarget, type RuntimeTargetReceipt, type RuntimeInstance } from "../core/runtime-target.ts";
+import { failureDiagnostic, ToolFault, NOT_STARTED, UNKNOWN_EFFECT } from "../core/tool-failure.ts";
+import { commandTimeout } from "../core/command-contract.ts";
+import { executionOutcome } from "../core/outcome.ts";
+import { archiveCommandArtifacts, artifactExclusions, observeArtifactFiles, observeArtifactInputs } from "../store/command-artifacts.ts";
+import { readObservation } from "../store/observations.ts";
+import { targetDirectory, targetProgram, observeRuntimeIdentity } from "../store/runtime-target.ts";
+import { findSession, startSession, pollSession } from "./exec-sessions.ts";
+import { sessionResult, type ToolContext, type ToolResult } from "./tools.ts";
+
+type History = readonly { node: number; events: readonly LogEvent[] }[];
+type LiveTarget = { request: string; contract: string; build: string; instance: RuntimeInstance };
+type Request = { action: "start" | "inspect"; target: string; session_id?: number; yield_time_ms?: number; timeout?: number };
+// Assumed bound for the small build manifest; binaries are observed separately, never read from log JSON.
+const MANIFEST_BYTES = 256 * 1024;
+
+export class RuntimeTargets {
+  private readonly live = new Map<string, LiveTarget>();
+
+  async perform(ctx: ToolContext, history: History, input: Request): Promise<{ result: ToolResult; observation: RuntimeTargetReceipt }> {
+    const events = history.flatMap(part => [...part.events]);
+    const state = deriveAcceptance(undefined, events);
+    const contract = events.find(event => event.id === state?.contract_event);
+    const target = contract?.t === "acceptance_contract" ? contract.contract.targets?.find(item => item.id === input.target) : undefined;
+    if (!state || !target) throw new ToolFault("invalid_input", "target must name a runtime in the current trusted acceptance contract", NOT_STARTED);
+    const archive = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
+    const receipt: RuntimeTargetReceipt = { kind: "runtime_target", version: 1, target: target.id,
+      request: state.request, contract_event: state.contract_event, state: "unknown", reason: "runtime has not been observed",
+      observed_at: new Date().toISOString(), source: { host: ctx.hostId ?? hostname(), workspace: resolve(ctx.root), cwd: resolve(ctx.root, target.workdir ?? "."), runtime: `bun/${Bun.version}` },
+      ...(target.port === undefined ? {} : { port: target.port }),
+      checks: { build: false, inputs: false, artifacts: false, process: false, image: false, port: target.port === undefined ? null : false } };
+    const raw: ArtifactRef[] = [];
+    let processResult: ToolResult | undefined;
+    let launched = false;
+    try {
+      const build = await this.build(ctx, history, state, target, receipt);
+      const existing = this.live.get(target.id);
+      if (input.action === "start") {
+        if (input.session_id !== undefined) throw Error("start does not accept a session_id; inspect an existing handle instead");
+        if (existing && findSession(existing.instance.session, ctx.execOwner)?.alive()) throw Error(`target already owns session ${existing.instance.session}; inspect or stop that handle before starting another`);
+        if (!build) throw Error(receipt.reason);
+        const cwd = await targetDirectory(ctx.root, target.workdir ?? ".");
+        const entryPath = join(await targetDirectory(ctx.root, "."), target.entry);
+        const program = await targetProgram(target.interpreter ?? entryPath, ctx.signal);
+        if (ctx.signal?.aborted) throw Error("target start cancelled before execution");
+        const argv = [program.path, ...(target.interpreter ? [entryPath] : []), ...(target.args ?? [])];
+        const command = argv.map(arg => `'${arg.replaceAll("'", "'\\''")}'`).join(" ");
+        const source = { ...receipt.source, cwd };
+        const session = await startSession({ argv, command, cwd, tty: false, spoolDir: archive, source,
+          timeoutMs: commandTimeout(input.timeout, ctx.timeoutMs, ctx.maxTimeoutMs), ...(ctx.execOwner ? { owner: ctx.execOwner } : {}) });
+        if ("error" in session) throw Error(session.error);
+        launched = true;
+        const entry = build.outputs.find(output => output.path === target.entry)!.after;
+        if (entry.state !== "observed") throw Error("target entry observation missing");
+        const live: LiveTarget = { request: state.request, contract: state.contract_event, build: receipt.build!.event,
+          instance: { id: randomUUID(), session: session.id, pid: session.pid, source, entry: { path: entryPath, sha256: entry.sha256 }, program } };
+        this.live.set(target.id, live);
+        const taken = await pollSession(session, archive, ctx.maxOutputBytes, input.yield_time_ms ?? 1000, "", ctx.signal);
+        raw.push(taken.stored.ref);
+        processResult = await sessionResult(ctx, session.command, session.timeoutMs, taken);
+      }
+      const live = this.live.get(target.id);
+      if (!live || live.request !== state.request || live.contract !== state.contract_event) throw Error("no live target capability in this Session; historical PID observations are not reattached");
+      receipt.instance = live.instance; receipt.source = live.instance.source;
+      if (input.session_id !== undefined && live.instance.session !== input.session_id) throw Error("requested handle is not this target instance");
+      if (!build || live.build !== receipt.build?.event) { receipt.state = "stale"; throw Error("the running instance is not bound to the current successful build"); }
+      const session = findSession(live.instance.session, ctx.execOwner);
+      if (!session || !session.alive() || session.exit !== null) { receipt.state = "stale"; throw Error("owned runtime exited or its live capability was lost"); }
+      const actual = await observeRuntimeIdentity(session.pid, live.instance.program, target.port, archive, ctx.signal);
+      raw.push(...actual.raw);
+      // Recheck after OS inspection: neither an exec nor a file replacement during a probe can inherit readiness.
+      const current = await targetProgram(target.interpreter ?? live.instance.entry.path, ctx.signal);
+      const currentBuild = await this.build(ctx, history, state, target, receipt);
+      receipt.checks.process = findSession(session.id, ctx.execOwner) === session && session.alive() && session.exit === null;
+      receipt.checks.image = actual.image && canonicalValue(current) === canonicalValue(live.instance.program);
+      receipt.checks.port = actual.port;
+      receipt.reason = !currentBuild ? receipt.reason : !receipt.checks.process ? "owned runtime exited during observation" :
+        !receipt.checks.image ? "runtime executable identity changed or could not be established" : actual.reason;
+      receipt.state = targetIsReady(receipt) ? "ready" : !actual.known ? "unknown" : !currentBuild || !receipt.checks.process ? "stale" : "not_ready";
+    } catch (error) { receipt.reason = error instanceof Error ? error.message : "target observation failed"; }
+    // Cancellation can arrive during a bounded file/OS probe, after the first
+    // poll released its listener. Finish through the same owned process path.
+    if (ctx.signal?.aborted) {
+      const live = this.live.get(target.id);
+      const session = live && live.request === state.request && live.contract === state.contract_event ? findSession(live.instance.session, ctx.execOwner) : undefined;
+      if (session) {
+        const taken = await pollSession(session, archive, ctx.maxOutputBytes, 0, "", ctx.signal);
+        raw.push(taken.stored.ref); processResult = await sessionResult(ctx, session.command, session.timeoutMs, taken);
+      }
+      receipt.state = "unknown"; receipt.checks.process = false; receipt.reason = "target observation cancelled";
+    }
+    receipt.observed_at = new Date().toISOString();
+    try { receipt.manifest = await archiveCommandArtifacts(archive, { observation: receipt, raw }); }
+    catch { receipt.state = "unknown"; receipt.reason = "runtime observation archive unavailable"; }
+    const content = `target ${target.id}: ${receipt.state}; ${receipt.reason}\n` +
+      `build ${receipt.build?.event ?? "none"}; entry ${receipt.instance?.entry.path ?? target.entry}; ` +
+      `session ${receipt.instance?.session ?? "none"}; pid ${receipt.instance?.pid ?? "unknown"}; port ${target.port ?? "not declared"}` +
+      (receipt.manifest ? `\nObservation: history artifact=${receipt.manifest.sha256}` : "") +
+      (receipt.state === "ready" ? "\nAwaiting explicit user acceptance of this instance." : "");
+    const result: ToolResult = { ...processResult, ok: receipt.state === "ready", content: content + (processResult ? `\n${processResult.content}` : ""),
+      // Process exit and target readiness are different operations. Keep the
+      // actual exit in effect/data; only the target owns this tool's outcome.
+      outcome: processResult?.outcome?.reason === "cancelled" || processResult?.outcome?.reason === "timeout" ? processResult.outcome :
+        executionOutcome(ctx.signal?.aborted ? "cancelled" : receipt.state === "ready" ? "tool_completed" : "tool_failed"),
+      ...(processResult?.data ? {} : { data: receipt }),
+      ...(receipt.state === "ready" ? {} : { diagnostic: failureDiagnostic(ctx.signal?.aborted ? "cancelled" : "unknown_effect", receipt.reason, launched ? UNKNOWN_EFFECT : NOT_STARTED) }) };
+    // The original stream reference must still match the process receipt. The
+    // separate target event/manifest preserves the richer runtime observation.
+    return { result, observation: receipt };
+  }
+
+  private async build(ctx: ToolContext, history: History, state: AcceptanceState, target: RuntimeTarget, receipt: RuntimeTargetReceipt): Promise<CommandArtifactReceipt | undefined> {
+    const criterion = state.criteria.find(item => item.id === target.build);
+    const part = history.find(part => part.events.some(event => event.id === criterion?.evidence?.event_id));
+    const event = part?.events.find(event => event.id === criterion?.evidence?.event_id);
+    const build = event?.t === "tool_result" && event.ok && event.effect?.kind === "command" && event.effect.exit === 0 ? event.effect.artifacts : undefined;
+    if (criterion?.status !== "pass" || !isCommandArtifactReceipt(build) || build.state !== "observed" || !build.manifest || !part || !event ||
+      criterion.kind !== "command" || build.command !== criterion.command || build.source.host !== receipt.source.host ||
+      build.source.workspace !== resolve(ctx.root) || canonicalValue(build.plan) !== canonicalValue(target.artifacts)) {
+      receipt.reason = `run the exact build condition ${target.build} with artifacts=${JSON.stringify(target.artifacts)} on this host and workspace`; return undefined;
+    }
+    receipt.build = { node: part.node, event: event.id, manifest: build.manifest };
+    const exclusions = artifactExclusions(ctx.root, target.artifacts, [...(ctx.ownedStatePaths ?? []), ctx.outputStore ?? join(ctx.root, ".xeno", "observations")]);
+    const { manifest, ...original } = build;
+    if (manifest.bytes > MANIFEST_BYTES) throw Error("build manifest exceeds runtime verification budget");
+    const page = await readObservation(ctx.outputStore ?? join(ctx.root, ".xeno", "observations"), manifest.sha256, 0, MANIFEST_BYTES);
+    if (page.next !== null || page.bytes !== manifest.bytes || canonicalValue(JSON.parse(page.text)) !== canonicalValue(original) ||
+      canonicalValue(exclusions) !== canonicalValue(build.inputs.exclusions)) throw Error("build observation scope or archived manifest does not match its original receipt");
+    receipt.checks.build = true;
+    const inputs = await observeArtifactInputs(ctx.root, exclusions, ctx.signal);
+    const files = await observeArtifactFiles(ctx.root, target.artifacts.paths, ctx.signal);
+    receipt.checks.inputs = inputs.sha256 !== null && inputs.sha256 === build.inputs.after;
+    receipt.checks.artifacts = build.outputs.every((output, i) => {
+      const file = files[i];
+      return file?.state === "observed" && output.after.state === "observed" && file.sha256 === output.after.sha256 &&
+        file.bytes === output.after.bytes && sameArtifactIdentity(file.identity, output.after.identity);
+    });
+    if (!receipt.checks.inputs || !receipt.checks.artifacts) { receipt.state = "stale"; receipt.reason = "build inputs or artifact bytes/identity changed; rebuild before launching or accepting"; return undefined; }
+    return build;
+  }
+}

package/src/runtime/tool-broker.ts

@@ -0,0 +1,137 @@
+/** Pi A / D8 / D11: direct and nested execution share one admitted, durable call contract. */
+import type { AssistantBlock, ToolInvocationEvent } from "../core/events.ts";
+import { failureDiagnostic, NOT_STARTED, UNKNOWN_EFFECT, ToolFault } from "../core/tool-failure.ts";
+import { executionOutcome } from "../core/outcome.ts";
+import { finishToolResult, nativeCommandContext, NATIVE_COMMAND_NAME, normalizeToolInput, type ToolContext, type ToolResult, type NestedInvocationOptions } from "./tools.ts";
+import { ToolQueue } from "./tool-queue.ts";
+
+export type BrokerCall = Extract<AssistantBlock, { type: "tool_use" }>;
+type Mode = "parallel" | "exclusive";
+/** Inherits the existing extension limit, now shared by the entire invocation tree. */
+export const MAX_NESTED_CALLS = 32;
+export const MAX_NESTED_DEPTH = 32;
+/** Assumed per-call composition budget; direct large edits retain their existing interface. */
+export const MAX_NESTED_ARGUMENT_BYTES = 64 * 1024;
+/** Assumed log metadata bound; complete structured results are independent artifacts. */
+export const MAX_INLINE_RESULT_DATA_BYTES = 64 * 1024;
+
+export interface BrokerHost<Result extends ToolResult> {
+  parallelLimit: number;
+  callId(): string;
+  mode(call: BrokerCall): Mode;
+  invocation(call: BrokerCall, ctx: ToolContext, parent: ToolInvocationEvent | undefined): Promise<ToolInvocationEvent>;
+  /** Receives normalized input and must still apply admission, including Session-owned tools. */
+  prepare(call: BrokerCall, ctx: ToolContext): Promise<Result | (() => Promise<Result>)>;
+  /** Session annotations and branch receipts are accepted before their result becomes evidence. */
+  settle(result: Result): Promise<void>;
+  result(invocation: ToolInvocationEvent, result: Result): Promise<void>;
+}
+export interface BrokerReceipt<Result extends ToolResult> {
+  value: Result;
+  invocation: ToolInvocationEvent;
+  settle(): Promise<void>;
+  commit(): Promise<void>;
+}
+export type BrokerExecution<Result extends ToolResult> = (() => Promise<BrokerReceipt<Result>>) & { close(): Promise<void> };
+type Budget = { calls: number };
+type Parent = { invocation: ToolInvocationEvent; budget: Budget; depth: number };
+
+/** Scheduling belongs to a live scope; immutable requests/results belong to the host log. */
+export class ToolBroker<Result extends ToolResult = ToolResult> {
+  private readonly host: BrokerHost<Result>;
+  constructor(host: BrokerHost<Result>) { this.host = host; }
+
+  async prepare(call: BrokerCall, context: ToolContext, parent?: Parent): Promise<BrokerExecution<Result>> {
+    let actual = call;
+    let invalid: ToolResult | undefined;
+    try {
+      // Extension argument preparation cannot rewrite the already-recorded model
+      // request. Hooks receive the exact immutable value archived for admission.
+      actual = { ...call, input: freezeInput(structuredClone(normalizeToolInput(context, call.name, structuredClone(call.input)))) };
+    }
+    catch (error) { invalid = error instanceof ToolFault ? finishToolResult({ ok: false, content: error.message, diagnostic: error.diagnostic }) : refused(`Invalid ${call.name} arguments: ${String(error)}`); }
+    const invocation = await this.host.invocation(actual, context, parent?.invocation);
+    if (parent && invocation.input === undefined) invalid = refused("nested arguments exceed the inline composition budget or are not JSON; pass a bounded request or use the direct tool");
+    const budget = parent?.budget ?? { calls: 0 }, depth = (parent?.depth ?? 0) + 1;
+    const children = new ToolQueue(this.host.parallelLimit);
+    const pending = new Set<Promise<ToolResult>>();
+    const failures: string[] = [];
+    let incomplete = false;
+    const mode = this.host.mode(actual);
+    let open = true;
+    const invoke = (name: string, input: unknown, options?: NestedInvocationOptions, native = false): Promise<ToolResult> => {
+      if (!open) return Promise.resolve(refused("tool scope is closed; no invocation started"));
+      if (mode !== "exclusive") return Promise.resolve(refused("only an exclusive composing tool may request nested execution"));
+      if (depth >= MAX_NESTED_DEPTH || budget.calls >= MAX_NESTED_CALLS) return Promise.resolve(refused("nested tool budget exhausted; no invocation started"));
+      // Capture at submission, before an asynchronous queue can observe a
+      // caller's later mutation of the same object.
+      try { input = structuredClone(input); }
+      catch { return Promise.resolve(refused("nested arguments must be serializable; no invocation started")); }
+      budget.calls++;
+      const nested: BrokerCall = { type: "tool_use", call_id: this.host.callId(), name, input };
+      const signals = [ctx.signal, options?.signal].filter((signal): signal is AbortSignal => signal !== undefined);
+      const nestedContext: ToolContext = native ? nativeCommandContext(ctx, options?.signal) : { ...ctx,
+        ...(signals.length ? { signal: AbortSignal.any(signals) } : {}) };
+      const result = children.submit(this.host.mode(nested), async () => {
+        const execute = await this.prepare(nested, nestedContext, { invocation, budget, depth });
+        return async () => {
+          const receipt = await execute();
+          await receipt.settle(); await receipt.commit();
+          if (!receipt.value.ok) failures.push(`nested call ${receipt.invocation.call_id} failed`);
+          return { ...receipt.value, invocation: { call_id: receipt.invocation.call_id, event: receipt.invocation.id } };
+        };
+      });
+      pending.add(result);
+      // The broker owns the lifetime even when extension code drops the promise.
+      void result.then(() => pending.delete(result), error => { incomplete = true; failures.push(`nested execution or persistence failed: ${String(error)}`); pending.delete(result); });
+      return result;
+    };
+    const ctx: ToolContext = { ...context, callId: call.call_id,
+      ...(parent ? { parentCallId: parent.invocation.call_id } : {}),
+      invoke: (name, input, options) => invoke(name, input, options),
+      runOwnedCommand: execute => children.submit("exclusive", async () => execute),
+      drainNested: () => children.whenIdle(),
+      invokeHost: (input, signal) => invoke(NATIVE_COMMAND_NAME, input, signal ? { signal } : {}, true) };
+    let closing: Promise<void> | undefined;
+    const close = () => {
+      open = false;
+      return closing ??= (async () => { await children.close(); await Promise.allSettled(pending); })();
+    };
+    let prepared: ToolResult | (() => Promise<Result>);
+    try { prepared = invalid ?? await this.host.prepare(actual, ctx); }
+    catch (error) { prepared = finishToolResult({ ok: false, content: String(error), diagnostic: failureDiagnostic("unknown_effect", String(error), UNKNOWN_EFFECT) }); }
+    return Object.assign(async () => {
+      let value: Result;
+      try { value = (typeof prepared === "function" ? await prepared() : prepared) as Result; }
+      catch (error) {
+        value = finishToolResult({ ok: false, content: `tool ${call.name} failed: ${String(error)}`,
+          diagnostic: failureDiagnostic("unknown_effect", String(error), UNKNOWN_EFFECT) }) as Result;
+      } finally {
+        await close();
+      }
+      if (failures.length) value = { ...value, warnings: [...(value.warnings ?? []),
+        failureDiagnostic("unknown_effect", `${failures.length} nested failures; inspect the original invocation receipts. ${failures[0]}`, UNKNOWN_EFFECT)] };
+      if (incomplete) value = { ...value, ok: false, outcome: executionOutcome("unknown"),
+        diagnostic: failureDiagnostic("unknown_effect", "nested execution or persistence did not produce a complete receipt", UNKNOWN_EFFECT) };
+      let settled: Promise<void> | undefined, committed: Promise<void> | undefined;
+      const settle = () => settled ??= this.host.settle(value);
+      return { value, invocation, settle,
+        commit: () => committed ??= settle().then(() => this.host.result(invocation, value)) };
+    }, { close });
+  }
+}
+
+function refused(message: string): ToolResult {
+  return finishToolResult({ ok: false, content: message, diagnostic: failureDiagnostic("invalid_input", message, NOT_STARTED) });
+}
+
+function freezeInput(value: unknown, ancestors = new Set<unknown>()): unknown {
+  if (value !== null && typeof value === "object") {
+    if (ancestors.has(value)) throw new Error("cyclic tool arguments are not JSON");
+    ancestors.add(value);
+    for (const child of Object.values(value)) freezeInput(child, ancestors);
+    ancestors.delete(value);
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/runtime/tool-discovery.ts

@@ -0,0 +1,57 @@
+/** R11: a harness-owned discovery entry shares normal Session admission and result persistence. */
+import { createHash } from "node:crypto";
+import { discoverTools, MAX_DISCOVERY_QUERY, MAX_DISCOVERY_RESULTS, type DeclarationRequest } from "../core/tool-discovery.ts";
+import { decide } from "../core/permissions.ts";
+import { failureDiagnostic, NOT_STARTED } from "../core/tool-failure.ts";
+import type { ToolSchema } from "./provider.ts";
+import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
+
+export const DISCOVERY_TOOL_NAME = "tool_search";
+export const DISCOVERY_TOOL: ToolDefinition = {
+  name: DISCOVERY_TOOL_NAME,
+  description: "Find optional registered tools by name or purpose. Reads the local catalog without connecting to services or executing tools. Returns purpose, important input types and declaration status. Matching permitted tools become declared only after the complete tool batch, for the next model request; then call them with their actual schema. Discovery does not grant execution permission or prove service health. Example: {\"query\":\"issue tracker\",\"limit\":3}.",
+  input_schema: { type: "object", properties: {
+    query: { type: "string", minLength: 1, maxLength: MAX_DISCOVERY_QUERY },
+    limit: { type: "integer", minimum: 1, maximum: MAX_DISCOVERY_RESULTS, description: "Maximum matches to request; defaults to 5." },
+  }, required: ["query"] },
+  access: "state", execution: "exclusive", branch: "none",
+  run: async () => ({ ok: false, content: "Tool discovery requires a live Session checkpoint." }),
+};
+
+/** Bind a request to the observed contract; an edited/replaced registration needs another lookup. */
+export function discoveryFingerprint(tool: ToolSchema): string {
+  return createHash("sha256").update(JSON.stringify({ name: tool.name, description: tool.description, input_schema: tool.input_schema })).digest("hex");
+}
+export function discoveryPermitted(ctx: ToolContext, name: string): boolean {
+  return decide([...(ctx.sessionRules ?? []), ...(ctx.rules ?? [])], { tool: name }) !== "deny";
+}
+/** A directory entry without its matching live implementation is unavailable, regardless of history. */
+export function currentDeferredTools(ctx: ToolContext): readonly ToolSchema[] {
+  return (ctx.deferredTools ?? []).filter(tool => {
+    const definition = ctx.extensions?.get(tool.name);
+    return definition !== undefined && discoveryFingerprint(definition) === discoveryFingerprint(tool);
+  });
+}
+export function searchDeferredTools(ctx: ToolContext, input: Record<string, unknown>, declared: readonly string[]): ToolResult {
+  const catalog = currentDeferredTools(ctx);
+  let matches;
+  try { matches = discoverTools(catalog, input["query"] as string, input["limit"] as number | undefined); }
+  catch {
+    const content = "Discovery requires a nonblank query of at most 256 characters and an integer limit from 1 to 8.";
+    return { ok: false, content, diagnostic: failureDiagnostic("invalid_input", content, NOT_STARTED) };
+  }
+  const requested: DeclarationRequest[] = [];
+  const result = matches.map(match => {
+    const tool = catalog.find(item => item.name === match.name)!;
+    const permitted = discoveryPermitted(ctx, match.name);
+    const status = !permitted ? "permission_denied" : declared.includes(match.name) ? "declared" : "requested_for_next_request";
+    if (status === "requested_for_next_request") requested.push({ name: tool.name, fingerprint: discoveryFingerprint(tool) });
+    const health = ctx.extensions?.get(match.name)?.integrationHealth?.();
+    return { ...match, declaration: status, service_health: health?.state ?? "not_checked", ...(health ? { service_observation: health } : {}) };
+  });
+  return { ok: true, content: JSON.stringify({ matches: result, note: result.length
+    ? "Only declared tools can run. Requested schemas become available after the current batch at a checkpoint; execution permissions still apply."
+    : "No matching tools in the currently permitted discovery catalog. No service was contacted." }),
+    // Keep only small, original requests inline so cold recovery never depends on a generated summary.
+    data: { kind: "tool_discovery", version: 1, requested: requested.map(item => ({ ...item })) } };
+}