@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/query-eval-verifier.ts

@@ -0,0 +1,28 @@
+/** Q.21: emit the isolated Bun verifier; it owns file I/O and process exit. */
+import type { queryEvalContract } from "../core/query-eval-contract.ts";
+
+export function queryEvalVerifier(contract: ReturnType<typeof queryEvalContract>): string {
+  // The standalone fixture carries only shape expectations and a one-way oracle
+  // digest. Diagnostics never expose expected numeric values to the model.
+  return `import { createHash } from "node:crypto";
+const paths = ${JSON.stringify(contract.paths)}, columns = ${JSON.stringify(contract.columns)}, rowCount = ${contract.rowCount};
+const fail = (reason, detail = {}) => { console.error(JSON.stringify({ok:false, reason, ...detail})); process.exit(1); };
+const body = await Bun.file("answer.txt").text().catch(() => fail("answer_missing"));
+let value; try { value = JSON.parse(body); } catch { fail("invalid_json"); }
+if (!Array.isArray(value) || value.length !== paths.length) fail("source_count", {expected:paths.length, actual:Array.isArray(value)?value.length:null});
+for (let i = 0; i < paths.length; i++) {
+  const item = value[i];
+  if (!item || typeof item !== "object" || JSON.stringify(Object.keys(item)) !== '["path","rows"]') fail("item_columns", {index:i, expected:["path","rows"]});
+  if (item.path !== paths[i]) fail("source_order", {index:i, expected:paths[i]});
+  if (!Array.isArray(item.rows) || item.rows.length !== rowCount) fail("row_count", {path:paths[i], expected:rowCount, actual:Array.isArray(item.rows)?item.rows.length:null});
+  for (let row = 0; row < item.rows.length; row++) {
+    const record = item.rows[row];
+    if (!record || typeof record !== "object" || JSON.stringify(Object.keys(record)) !== JSON.stringify(columns)) fail("result_columns", {path:paths[i], row, expected:columns, actual:record&&typeof record==="object"?Object.keys(record):null});
+    if (columns.some(column => column === "team" ? typeof record[column] !== "string" : !Number.isFinite(record[column]))) fail("result_type", {path:paths[i], row});
+  }
+}
+if (body !== JSON.stringify(value) + "\\n") fail("serialization", {expected:"compact JSON with one trailing newline"});
+if (createHash("sha256").update(body).digest("hex") !== ${JSON.stringify(contract.answerSha256)}) fail("value_mismatch", {next:"Recheck the original task, source rows, filter and aggregation. The result shape is correct; at least one value or row order differs."});
+console.log(JSON.stringify({ok:true}));
+`;
+}

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;
+  }
+}