@visual-z/xeno 0.2.1 → 0.4.0

package/src/core/evidence-links.ts

@@ -36,6 +36,9 @@ export function observedVersion(events: readonly LogEvent[], resource: string):
       if (event.removed.map(resourceKey).includes(resource)) version = null;
       for (const [path, value] of Object.entries({ ...event.added, ...event.changed })) if (resourceKey(path) === resource) version = value;
     }
+    if (event.t === "checkpoint" && event.phase === "applied") for (const [path, change] of Object.entries(event.changes)) {
+      if (resourceKey(path) === resource) version = change.after?.sha256 ?? null;
+    }
   }
   return version;
 }
@@ -65,6 +68,10 @@ export function deriveEvidenceLinks(previous: readonly EvidenceLink[], events: r
           if (resourceKey(path) === link.resource) link.freshness = version === link.version ? "current" : "stale";
         }
       }
+      if (event.t === "checkpoint" && event.phase === "applied") for (const [path, change] of Object.entries(event.changes)) {
+        if (resourceKey(path) === link.resource) link.freshness = change.after?.sha256 === link.version ? "current" : "stale";
+      }
+      if (event.t === "workspace_observation" && event.changed || event.t === "checkpoint" && event.phase === "unavailable") link.freshness = "unknown";
     }
   }
   return links;

package/src/core/evidence.ts

@@ -1,6 +1,7 @@
 /** Shared executed-evidence rules for handoff derivation and the turn watchdog. */
 import type { EvidenceQuery, LogEvent, ToolResultEvent } from "./events.ts";
 import type { Evidence } from "./handoff.ts";
+import { changedPaths } from "./checkpoints.ts";
 
 type CommandEffect = Extract<NonNullable<ToolResultEvent["effect"]>, { kind: "command" }>;
 export type CommandResult = ToolResultEvent & { effect: CommandEffect };
@@ -15,9 +16,14 @@ export function evidenceStale(events: readonly LogEvent[], evidence: Evidence, i
   let stale = initially;
   for (const event of events.slice(start + 1)) {
     if (event.t === "tool_result" && event.effect?.kind === "edit") stale = true;
-    const sha = event.t === "snapshot" ? event.workspace_sha256
+    if (event.t === "checkpoint" && (event.phase === "unavailable" || event.phase === "applied" && changedPaths(event.changes).length > 0)) stale = true;
+    if (event.t === "workspace_observation" && event.fingerprint === undefined ||
+        event.t === "tool_result" && event.effect?.kind === "command" && event.effect.workspace_observed === false || event.t === "user_bash") stale = true;
+    const sha = event.t === "workspace_observation" ? event.fingerprint : event.t === "snapshot" ? event.workspace_sha256
       : event.t === "tool_result" && event.effect?.kind === "command" ? event.effect.workspace_sha256 : undefined;
-    if (sha !== undefined && evidence.workspace_sha256 !== undefined) stale = sha !== evidence.workspace_sha256;
+    const scope = event.t === "workspace_observation" ? event.scope : event.t === "tool_result" && event.effect?.kind === "command" ? event.effect.workspace_scope : undefined;
+    if (sha !== undefined && evidence.workspace_sha256 !== undefined) stale = evidence.workspace_scope === "source-v1"
+      ? stale || scope !== evidence.workspace_scope || sha !== evidence.workspace_sha256 : scope !== undefined || sha !== evidence.workspace_sha256;
     else if (event.t === "snapshot" && (Object.keys(event.added).length + Object.keys(event.changed).length + event.removed.length > 0)) stale = true;
   }
   return stale;
@@ -33,7 +39,9 @@ export function resolveEvidence(events: readonly LogEvent[], query: EvidenceQuer
   const result = events.slice(start).findLast(event => isCommandResult(event) && matchesQuery(query, event.effect));
   if (!result || !isCommandResult(result)) return { ok: false, reason: "no_matching_event" };
   if (result.effect.exit !== 0) return { ok: false, reason: "nonzero_exit", exit: result.effect.exit };
+  if (result.effect.workspace_observed === false) return { ok: false, reason: "stale_workspace" };
   const evidence: Evidence = { command: result.effect.cmd, exit: result.effect.exit, at: result.at, event_id: result.id,
+    ...(result.effect.workspace_scope ? { workspace_scope: result.effect.workspace_scope } : {}),
     ...(result.effect.gate !== undefined ? { gate: result.effect.gate } : {}),
     ...(result.effect.workspace_sha256 ? { workspace_sha256: result.effect.workspace_sha256 } : {}) };
   return evidenceStale(events, evidence) ? { ok: false, reason: "stale_workspace" } : { ok: true, evidence };
@@ -44,8 +52,9 @@ export function eligibleProgressChecks(events: readonly LogEvent[], claimed: Rea
   for (const event of events) {
     if (!isCommandResult(event)) continue;
     const gate = event.effect.gate;
-    if (event.effect.exit !== 0 || (gate === undefined && !claimed.has(event.id)) || (gate !== undefined && failingGates.has(gate))) continue;
+    if (event.effect.exit !== 0 || event.effect.workspace_observed === false || (gate === undefined && !claimed.has(event.id)) || (gate !== undefined && failingGates.has(gate))) continue;
     if (!evidenceStale(events, { command: event.effect.cmd, exit: 0, at: event.at, event_id: event.id,
+      ...(event.effect.workspace_scope ? { workspace_scope: event.effect.workspace_scope } : {}),
       ...(event.effect.workspace_sha256 === undefined ? {} : { workspace_sha256: event.effect.workspace_sha256 }) })) eligible.add(event.id);
   }
   return eligible;
@@ -74,6 +83,7 @@ export function classifyGate(gates: Readonly<Record<string, string>>, command: s
   if (tokens.some((t) => informational.includes(t))) return undefined;
   let i = 0;
   const first = tokens[0];
+  if (["bun", "npm", "pnpm", "yarn"].includes(first ?? "") && tokens[1] === "test") return gates["test"];
   if (first === "python" || first === "python3") {
     if (tokens[1] !== "-m") return undefined;
     i = 2;

package/src/core/execution.ts

@@ -1,11 +1,17 @@
 /** D5/D11: incomplete execution is unknown, never an instruction to run twice. */
 import type { LogEvent, AssistantBlock } from "./events.ts";
 
-export function pendingToolCalls(events: readonly LogEvent[]): Extract<AssistantBlock, { type: "tool_use" }>[] {
-  const pending = new Map<string, Extract<AssistantBlock, { type: "tool_use" }>>();
+export type PendingToolCall = Extract<AssistantBlock, { type: "tool_use" }> & { parent_call_id?: string; invocation_id?: string; origin?: "extension" };
+export function pendingToolCalls(events: readonly LogEvent[]): PendingToolCall[] {
+  const pending = new Map<string, PendingToolCall>();
   for (const event of events) {
     if (event.t === "assistant") {
       for (const block of event.blocks) if (block.type === "tool_use") pending.set(block.call_id, block);
+    } else if (event.t === "tool_invocation") {
+      const existing = pending.get(event.call_id);
+      pending.set(event.call_id, { type: "tool_use", call_id: event.call_id, name: event.name, input: event.input ?? existing?.input ?? null,
+        invocation_id: event.id, ...(event.origin ? { origin: event.origin } : {}),
+        ...(event.parent_call_id ? { parent_call_id: event.parent_call_id } : {}) });
     } else if (event.t === "tool_result") pending.delete(event.call_id);
   }
   return [...pending.values()];

package/src/core/experiment.ts

@@ -1,5 +1,9 @@
 /** Experimental projections never mutate the durable event stream (D8, L). */
 import type { Message } from "./project.ts";
+import { isTrialLifecycle, type TrialLifecycle } from "./trial-lifecycle.ts";
+import { RECOVERY_TASKS, recoveryCase, type RecoveryTask } from "./recovery-corpus.ts";
+import { isRecoveryMetrics, type RecoveryMetrics } from "./recovery-evaluation.ts";
+import { TOOL_MODE_FACTORS, TOOL_MODE_TASKS, isToolModeTask, isToolModeMetrics, type ToolModeTask, type ToolModeMetrics } from "./tool-mode-protocol.ts";
 
 export type ContextArm = "node" | "replay" | "truncate" | "mask";
 
@@ -38,3 +42,132 @@ export function shuffled<T>(items: readonly T[], seed: number): T[] {
   }
   return out;
 }
+
+/** O.16: each contrast changes exactly one policy, with paired task repeats. */
+export const EVAL_FACTORS = ["profile", "workingSet", "strictVerification"] as const;
+export const EVAL_TASKS = ["short", "boundary-recall", "false-completion", "human-boundary"] as const;
+const supportedFactors = [...EVAL_FACTORS, ...TOOL_MODE_FACTORS] as const;
+export type EvalFactor = typeof supportedFactors[number];
+export type EvalTask = typeof EVAL_TASKS[number] | RecoveryTask | ToolModeTask;
+const supportedTasks:readonly EvalTask[]=[...EVAL_TASKS,...RECOVERY_TASKS,...TOOL_MODE_TASKS];
+export type EvalArm = "control" | "treatment";
+export type EvalPolicy = { profile: "full" | "coding"; workingSet: boolean; strictVerification: boolean; querySyntax?: "json" | "sql" };
+export type EvalJob = { id: string; factor: EvalFactor; task: EvalTask; repeat: number; arm: EvalArm; policy: EvalPolicy };
+export function evalPolicy(factor: EvalFactor, arm: EvalArm): EvalPolicy {
+  const policy: EvalPolicy = { profile: "coding", workingSet: true, strictVerification: true };
+  if (factor === "querySyntax") return { ...policy, querySyntax: arm === "treatment" ? "sql" : "json" };
+  if (arm === "control") {
+    if (factor === "profile") policy.profile = "full";
+    else policy[factor] = false;
+  }
+  return policy;
+}
+export function singleFactorSchedule(seed: number, repeats = 1, tasks: readonly EvalTask[] = EVAL_TASKS, factors: readonly EvalFactor[] = EVAL_FACTORS): EvalJob[] {
+  if (!Number.isSafeInteger(seed) || !Number.isSafeInteger(repeats) || repeats < 1 || repeats > 20 || !tasks.length ||
+      new Set(tasks).size !== tasks.length || tasks.some(task => !supportedTasks.includes(task)) || !factors.length || new Set(factors).size !== factors.length ||
+      factors.some(factor => !supportedFactors.includes(factor) || tasks.some(task => isToolModeTask(task) !== (TOOL_MODE_FACTORS as readonly string[]).includes(factor)))) throw new RangeError("invalid eval schedule");
+  const pairs = shuffled(factors.flatMap(factor => [...tasks].sort().flatMap(task =>
+    Array.from({ length: repeats }, (_, repeat) => ({ factor, task, repeat })))), seed);
+  // Alternate first position before shuffling: adjacent LCG seeds are correlated.
+  const positions = new Map<EvalFactor, number>();
+  const order = shuffled(["control", "treatment"] as const, seed + 1);
+  return pairs.flatMap(pair => {
+    const offset = positions.get(pair.factor) ?? 0; positions.set(pair.factor, offset + 1);
+    return order.map((_, i) => {
+      const arm = order[(offset + i) % 2]!;
+      return { ...pair, arm, id: `${pair.factor}/${pair.task}/${pair.repeat}/${arm}`, policy: evalPolicy(pair.factor, arm) };
+    });
+  });
+}
+export function validateEvalJobs(jobs: readonly EvalJob[]): void {
+  const seen = new Set<string>();
+  for (const job of jobs) {
+    if (!supportedFactors.includes(job.factor) || !supportedTasks.includes(job.task) || !["control", "treatment"].includes(job.arm) ||
+        isToolModeTask(job.task) !== (TOOL_MODE_FACTORS as readonly string[]).includes(job.factor) ||
+        !Number.isSafeInteger(job.repeat) || job.repeat < 0 || job.id !== `${job.factor}/${job.task}/${job.repeat}/${job.arm}` || seen.has(job.id) ||
+        JSON.stringify(job.policy) !== JSON.stringify(evalPolicy(job.factor, job.arm))) throw new Error("invalid or confounded eval job");
+    seen.add(job.id);
+  }
+  for (const job of jobs) if (!seen.has(`${job.factor}/${job.task}/${job.repeat}/${job.arm === "control" ? "treatment" : "control"}`)) throw new Error("unpaired eval job");
+}
+export interface EvalResult {
+  toolMode?: ToolModeMetrics;
+  recovery?: RecoveryMetrics;
+  /** v2 separates an unmet final state from a machine-readable unsupported claim. */
+  unverifiedEnding?: boolean;
+  /** Absent in the frozen O.16 archives; absence is unknown, not an uninterrupted run. */
+  lifecycle?: TrialLifecycle;
+  id: string;
+  status: "finished" | "error" | "budget" | "stopped";
+  scenarioPassed: boolean;
+  artifactCorrect: boolean;
+  verified: boolean;
+  awaitingHuman: boolean;
+  falseCompletion: boolean;
+  requests: number;
+  toolFailures: number;
+  repeatedReads: number;
+  promptTokens: number | null;
+  cacheTokens: number | null;
+  outputTokens: number | null;
+  costUsd: number | null;
+  reservedUnknownUsd: number;
+}
+export function summarizeSingleFactor(jobs: readonly EvalJob[], results: readonly EvalResult[]) {
+  validateEvalJobs(jobs);
+  const byId = new Map<string, EvalResult>(), planned = new Set(jobs.map(job => job.id));
+  for (const row of results) {
+    if (row.toolMode !== undefined && (!isToolModeMetrics(row.toolMode) || row.scenarioPassed && !row.toolMode.sourceComplete)) throw Error("invalid tool mode metrics");
+    if (row.unverifiedEnding !== undefined && typeof row.unverifiedEnding !== "boolean") throw Error("invalid ending metric");
+    if(row.recovery!==undefined&&(!isRecoveryMetrics(row.recovery)||row.recovery.finalTaskSuccess!==row.scenarioPassed||row.recovery.toolFailures!==row.toolFailures||row.falseCompletion!==(row.recovery.unsupportedClaims>0)))throw Error("invalid recovery metrics");
+    if (row.lifecycle !== undefined && (!isTrialLifecycle(row.lifecycle) || row.lifecycle.backendRequests > row.requests ||
+        row.lifecycle.interruption !== null && row.status === "finished" || row.lifecycle.cleanup === "failed" && row.status !== "error"))
+      throw new Error("invalid eval lifecycle result");
+    if (!planned.has(row.id) || byId.has(row.id) || !["finished", "error", "budget", "stopped"].includes(row.status) ||
+        [row.scenarioPassed, row.artifactCorrect, row.verified, row.awaitingHuman, row.falseCompletion].some(value => typeof value !== "boolean") ||
+        row.scenarioPassed && (row.status !== "finished" || !row.verified || row.falseCompletion && row.recovery === undefined) ||
+        [row.requests, row.toolFailures, row.repeatedReads].some(n => !Number.isSafeInteger(n) || n < 0) ||
+        [row.promptTokens, row.cacheTokens, row.outputTokens].some(n => n !== null && (!Number.isSafeInteger(n) || n < 0)) ||
+        [row.costUsd, row.reservedUnknownUsd].some(n => n !== null && (!Number.isFinite(n) || n < 0)) ||
+        row.cacheTokens !== null && row.promptTokens !== null && row.cacheTokens > row.promptTokens) throw new Error("invalid or duplicate eval result");
+    byId.set(row.id, row);
+  }
+  const factors = supportedFactors.filter(factor => jobs.some(job => job.factor === factor));
+  const arms = factors.flatMap(factor => (["control", "treatment"] as const).map(arm => {
+    const selected = jobs.filter(job => job.factor === factor && job.arm === arm), rows = selected.flatMap(job => byId.has(job.id) ? [byId.get(job.id)!] : []);
+    const complete = rows.length === selected.length, scenarioPassed = rows.filter(row => row.scenarioPassed).length;
+    const knownCostSubtotal = rows.reduce((sum, row) => sum + (row.costUsd ?? 0), 0);
+    // Missing jobs and unknown charges cannot become a zero-priced success.
+    const costUsd = complete && rows.length > 0 && rows.every(row => row.costUsd !== null) ? knownCostSubtotal : null;
+    const total = (field: "promptTokens" | "cacheTokens" | "outputTokens") => complete && rows.length > 0 && rows.every(row => row[field] !== null)
+      ? rows.reduce((sum, row) => sum + row[field]!, 0) : null;
+    const recovery=selected.some(job=>recoveryCase(job.task)||isToolModeTask(job.task))?{observed:rows.filter(row=>row.recovery).length,
+      missing:selected.length-rows.filter(row=>row.recovery).length,
+      firstToolSuccess:rows.filter(row=>row.recovery?.firstToolSuccess===true).length,
+      firstPassTaskSuccess:rows.filter(row=>row.recovery?.firstPassTaskSuccess===true).length,
+      ...Object.fromEntries((["toolCalls","outerCalls","nestedCalls","unresolvedCalls","recoveryCalls","unchangedFailureRetries","originalEvidenceRetrievals","unsupportedClaims"] as const)
+        .map(key=>[key,rows.reduce((n,row)=>n+(row.recovery?.[key]??0),0)]))}:undefined;
+    return { factor, arm, ...(recovery?{recovery}:{}), planned: selected.length, attempted: rows.length, missing: selected.length - rows.length,
+      failed: rows.filter(row => !row.scenarioPassed).length, scenarioPassed, verified: rows.filter(row => row.verified).length,
+      awaitingHuman: rows.filter(row => row.awaitingHuman).length, falseCompletions: rows.filter(row => row.falseCompletion).length,
+      plannedPassFraction: selected.length ? scenarioPassed / selected.length : null, complete,
+      requests: rows.reduce((n, row) => n + row.requests, 0), toolFailures: rows.reduce((n, row) => n + row.toolFailures, 0),
+      repeatedReads: rows.reduce((n, row) => n + row.repeatedReads, 0), promptTokens: total("promptTokens"), cacheTokens: total("cacheTokens"), outputTokens: total("outputTokens"),
+      knownCostSubtotal, costUsd, unknownCostJobs: rows.filter(row => row.costUsd === null).length,
+      reservedUnknownUsd: rows.reduce((n, row) => n + row.reservedUnknownUsd, 0),
+      costPerScenarioSuccess: costUsd !== null && scenarioPassed > 0 ? costUsd / scenarioPassed : null };
+  }));
+  const comparisons = factors.map(factor => {
+    const pairs = jobs.filter(job => job.factor === factor && job.arm === "control");
+    const clusters = [...new Set(pairs.map(job => job.task))].sort().map(task => {
+      const matched = pairs.filter(job => job.task === task).flatMap(job => {
+        const control = byId.get(job.id), treatment = byId.get(`${factor}/${task}/${job.repeat}/treatment`);
+        return control && treatment ? [{ delta: Number(treatment.scenarioPassed) - Number(control.scenarioPassed) }] : [];
+      });
+      return { task, matchedPairs: matched.length, passDelta: matched.length ? matched.reduce((n, pair) => n + pair.delta, 0) / matched.length : null };
+    });
+    const matchedPairs = clusters.reduce((n, row) => n + row.matchedPairs, 0);
+    return { factor, matchedPairs, missingPairs: pairs.length - matchedPairs, clusters };
+  });
+  return { arms, comparisons };
+}

package/src/core/export.ts

@@ -91,6 +91,9 @@ function escapeHtml(s: string): string {
 
 function eventHtml(e: LogEvent): string {
   switch (e.t) {
+    case "tool_invocation": return wrap("event", "tool invocation", e.at, `${e.name} · ${e.call_id}${e.parent_call_id ? ` · parent ${e.parent_call_id}` : ""} · input ${e.input_ref.sha256} · schema ${e.schema_ref?.sha256 ?? "unavailable"}`);
+    case "checkpoint": return wrap("event", `file checkpoint ${e.phase}`, e.at, e.reason ?? Object.keys(e.changes).join("\n"));
+    case "workspace_observation": return wrap("event", "verification observation", e.at, e.fingerprint ?? e.reason ?? "unavailable");
     case "extension": return e.display ? wrap("event", e.customType, e.at, e.content || JSON.stringify(e.data)) : "";
     case "user":
       return wrap("user", "user", e.at, [e.text, ...(e.images ?? []).map(imageDescription)].join("\n"));
@@ -143,6 +146,12 @@ function eventHtml(e: LogEvent): string {
       return wrap("event", `work ${e.operation}`, e.at, `${e.work_id}: ${e.what}`);
     case "evidence_link":
       return wrap("event", "evidence link", e.at, `${e.work}: ${e.what} → ${e.source}`);
+    case "work_owner": case "work_dependencies": return wrap("event", e.t, e.at, JSON.stringify(e));
+    case "skill_loaded": return wrap("event", "skill loaded", e.at, `${e.name} · ${e.path} · ${e.sha256} · ${e.mode}`);
+    case "process_exit": return wrap("event", "process exit", e.at, `${e.session} · exit ${e.exit} · output ${e.output.sha256}`);
+    case "acceptance_contract": return wrap("event", "acceptance contract", e.at, JSON.stringify(e.contract));
+    case "target_observation": return wrap("event", "runtime target", e.at, JSON.stringify(e.observation));
+    case "acceptance_decision": return wrap("event", "human acceptance", e.at, `${e.contract_id}: ${e.criterion}`);
     default:
       return assertNever(e, "eventHtml");
   }

package/src/core/failure-recovery.ts

@@ -0,0 +1,173 @@
+/** R5 / D8: replayable failure premises; advice never authorizes or automatically retries a tool. */
+import type { GuidanceEvent, LogEvent, ToolResultEvent } from "./events.ts";
+import type { ToolDiagnostic } from "./tool-contract.ts";
+import { canonicalValue } from "./continuation.ts";
+import { repairToolInput } from "./tool-input.ts";
+import { failureDiagnostic, scopeFailureGuidance } from "./tool-failure.ts";
+
+/** Reuses the existing three-attempt diagnostic hypothesis, not a measured optimum or a stop threshold. */
+export const RECOVERY_FAILURES = 3;
+type Call = { name: string; input: unknown };
+export interface FailureIdentity {
+  family: string;
+  resource: string;
+  version: string;
+  code: ToolDiagnostic["code"];
+  execution: NonNullable<ToolDiagnostic["execution"]>;
+  effects: NonNullable<ToolDiagnostic["effects"]>;
+  premise: string;
+}
+interface FailureRun {
+  identity: FailureIdentity;
+  key: string;
+  count: number;
+  sources: readonly string[];
+  notified: boolean;
+}
+export interface RecoveryState {
+  calls: ReadonlyMap<string, Call>;
+  versions: ReadonlyMap<string, string>;
+  failures: ReadonlyMap<string, FailureRun>;
+  change: number;
+}
+export function emptyRecoveryState(): RecoveryState {
+  return { calls: new Map(), versions: new Map(), failures: new Map(), change: 0 };
+}
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const digest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const fileTools = ["read", "write", "edit", "grep", "find", "ls"];
+const family = (name: string): string => name === "bash" || name === "exec_command" ? "command"
+  : name === "edit" || name === "write" ? "file_change" : name;
+
+function target(call: Call, identify: (path: string) => string): { family: string; resource: string; input: Record<string, unknown> } {
+  const repaired = repairToolInput(call.name, call.input), input = record(repaired) ? repaired : { value: repaired };
+  const kind = family(call.name);
+  return { family: kind, input, resource: fileTools.includes(call.name) && typeof input["path"] === "string" ? identify(input["path"])
+    : kind === "command" ? identify(typeof input["workdir"] === "string" ? input["workdir"] : ".")
+    : call.name === "write_stdin" ? `session:${String(input["session_id"])}` : call.name };
+}
+
+function groupKey(call: Call, result: ToolResultEvent, identify: (path: string) => string): string {
+  const context = target(call, identify);
+  return canonicalValue([context.family, context.resource, context.family === "command"
+    ? result.effect?.kind === "command" ? result.effect.cmd.trim() : String(context.input["command"] ?? context.input["cmd"] ?? "").trim() : null]);
+}
+
+/** Only recorded versions and structured failures are facts; stderr words never identify an error. */
+export function failureIdentity(call: Call, result: ToolResultEvent, state: RecoveryState,
+  identify: (path: string) => string): FailureIdentity | null {
+  const diagnostic = result.diagnostic;
+  if (result.ok || !diagnostic || diagnostic.execution === undefined || diagnostic.effects === undefined) return null;
+  const context = target(call, identify), data = record(result.data) ? result.data : {};
+  const current = data["sha256"];
+  const effect = result.effect;
+  const known = state.versions.get(context.resource);
+  const version = diagnostic.code === "permission_denied" ? "unknown" : current === null ? "absent" : digest(current) ? current
+    : effect?.kind === "command" && effect.workspace_observed !== false && digest(effect.workspace_sha256) ? effect.workspace_sha256
+    : digest(known) ? known : "unknown";
+  const input = context.input;
+  let premise: unknown;
+  if (diagnostic.code === "version_mismatch") {
+    const precondition = record(data["precondition"]) ? data["precondition"] : {};
+    premise = { expected: precondition["expected"] === null ? "absent"
+      : precondition["expected"] ?? input["expected_sha256"] ?? input["read_handle"] ?? "unknown" };
+  } else if (diagnostic.code === "permission_denied") {
+    // Replacement wording and requested shell timeouts cannot change a denied capability.
+    premise = { operation: context.family === "command" ? effect?.kind === "command" ? effect.cmd.trim()
+      : String(input["command"] ?? input["cmd"] ?? "").trim() : context.family };
+  } else if (context.family === "file_change" && ["not_found", "ambiguous_edit"].includes(diagnostic.code)) {
+    const edits = Array.isArray(input["edits"]) ? input["edits"] : [input];
+    premise = edits.map(edit => record(edit) ? { old_string: edit["old_string"], replace_all: edit["replace_all"] === true } : edit);
+  } else if (context.family === "command") {
+    // Shared launch contract equates bash/exec_command; arbitrary shell strings are not parsed as equivalent.
+    premise = { command: effect?.kind === "command" ? effect.cmd.trim() : String(input["command"] ?? input["cmd"] ?? "").trim(),
+      exit: effect?.kind === "command" ? effect.exit : null,
+      timeout: input["timeout"] ?? null, tty: input["tty"] === true, change: state.change };
+  } else {
+    const normalized = { ...input };
+    if (fileTools.includes(call.name) && typeof normalized["path"] === "string") normalized["path"] = context.resource;
+    premise = normalized;
+  }
+  return { family: context.family, resource: context.resource, version, code: diagnostic.code,
+    execution: diagnostic.execution, effects: diagnostic.effects, premise: canonicalValue(premise) };
+}
+
+function changedPremises(state: RecoveryState, changed: boolean, resource?: string, version?: string): RecoveryState {
+  return { ...state, change: state.change + Number(changed), failures: new Map([...state.failures].filter(([, run]) =>
+    run.identity.code === "permission_denied" || !(changed && run.identity.family === "command" ||
+      resource !== undefined && version !== undefined && run.identity.resource === resource && run.identity.version !== version))) };
+}
+
+/** Incremental disposable projection; folding the original ancestry yields exactly the same state. */
+export function advanceRecovery(state: RecoveryState, events: readonly LogEvent[], identify: (path: string) => string): RecoveryState {
+  let current = state;
+  for (const event of events) {
+    if (event.t === "user") { current = { ...current, failures: new Map() }; continue; }
+    if (event.t === "assistant") {
+      const calls = new Map(current.calls);
+      for (const block of event.blocks) if (block.type === "tool_use") calls.set(block.call_id, { name: block.name, input: block.input });
+      current = { ...current, calls }; continue;
+    }
+    if (event.t === "tool_invocation") {
+      if (event.input !== undefined) current = { ...current, calls: new Map(current.calls).set(event.call_id, { name: event.name, input: event.input }) };
+      continue;
+    }
+    if (event.t === "guidance" && event.reason === "churn") {
+      current = { ...current, failures: new Map([...current.failures].map(([group, run]) =>
+        [group, event.sources.includes(run.sources[0]!) ? { ...run, notified: true } : run])) }; continue;
+    }
+    if (event.t === "workspace_observation" && event.changed) {
+      current = changedPremises(current, true); continue;
+    }
+    if (event.t === "checkpoint" && event.phase === "applied") {
+      for (const [path, change] of Object.entries(event.changes))
+        current = changedPremises(current, change.before?.sha256 !== change.after?.sha256 || change.before?.mode !== change.after?.mode,
+          identify(path), change.after === null ? "absent" : change.after.sha256);
+      continue;
+    }
+    if (event.t !== "tool_result") continue;
+    const call = current.calls.get(event.call_id), calls = new Map(current.calls); calls.delete(event.call_id);
+    current = { ...current, calls };
+    const effect = event.effect;
+    if (effect?.kind === "edit" || effect?.kind === "read") {
+      const resource = identify(effect.path), previous = current.versions.get(resource);
+      const version = effect.kind === "edit" ? effect.sha256_after : effect.sha256;
+      const changed = effect.kind === "edit" ? effect.sha256_before !== effect.sha256_after : digest(previous) && previous !== version;
+      current = changedPremises({ ...current, versions: new Map(current.versions).set(resource, version) }, changed,
+        resource, digest(version) ? version : undefined);
+    }
+    if (!call) continue;
+    const group = groupKey(call, event, identify);
+    if (event.ok) {
+      const failures = new Map(current.failures); failures.delete(group);
+      current = { ...current, failures }; continue;
+    }
+    const identity = failureIdentity(call, event, current, identify);
+    if (!identity) continue;
+    const key = canonicalValue(identity), previous = current.failures.get(group);
+    const run: FailureRun = previous?.key === key ? { ...previous, count: previous.count + 1,
+      sources: [...previous.sources.slice(0, 2), event.id] }
+      : { identity, key, count: 1, sources: [event.id], notified: false };
+    current = { ...current, failures: new Map(current.failures).set(group, run) };
+  }
+  return current;
+}
+
+export function recoveryReview(state: RecoveryState, tools?: readonly string[]): Pick<GuidanceEvent, "reason" | "text" | "sources"> | null {
+  for (const run of state.failures.values()) {
+    if (run.count < RECOVERY_FAILURES || run.notified) continue;
+    const identity = run.identity;
+    // Recompute trusted instructions; never promote arbitrary tool error text to harness instructions.
+    const diagnostic = failureDiagnostic(identity.code, "", { execution: identity.execution, effects: identity.effects });
+    const policy = tools === undefined ? diagnostic : scopeFailureGuidance(diagnostic, tools);
+    return { reason: "churn", sources: run.sources,
+      text: `Harness: ${run.count} attempts share an unchanged failure premise in the recorded facts. ` +
+        `Tool family ${JSON.stringify(identity.family)}; resource label (data) ${JSON.stringify(identity.resource.slice(0, 160))}; ` +
+        `code ${identity.code}; version ${identity.version}; execution ${identity.execution}; effects ${identity.effects}. ` +
+        `${policy.next} ` + (policy.retry === "after_inspection" ? "Inspect actual state for partial effects before any replay. " : "") +
+        "Identify which relevant premise changed before another attempt; changing replacement wording is not a new premise. " +
+        (identity.version === "unknown" ? "The resource version is unknown; this notice does not prove external state is unchanged. " : "") +
+        "This is recovery advice, not a task-failure verdict or authorization to replay. Original result references: " + run.sources.join(", ") + "." };
+  }
+  return null;
+}

package/src/core/file-precondition.ts

@@ -0,0 +1,72 @@
+/** R4 / D8: a read descriptor names immutable version premises; it grants no authority. */
+import type { ObservationReceipt } from "./read-observation.ts";
+import { isObservationArtifact } from "./observation-view.ts";
+import type { LogEvent } from "./events.ts";
+
+export interface FileIdentity { host: string; workspace: string; resource: string }
+export interface FileReadDescriptor {
+  kind: "file_read";
+  version: 1;
+  source: ObservationReceipt["source"];
+  selection: ObservationReceipt["selection"];
+}
+export interface FilePrecondition {
+  source: "read_handle" | "expected_sha256" | "session" | "create_only" | "unobserved";
+  expected: string | null;
+  read_handle?: string;
+}
+export type FilePreconditionDecision = { ok: true; precondition: FilePrecondition } |
+  { ok: false; code: "invalid_input" | "version_mismatch"; message: string; precondition?: FilePrecondition };
+
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+export const isFileDigest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+
+/** Preserve chronology across path aliases; handoff anchors intentionally keep their legacy spelling. */
+export function latestObservedFileVersion(events: readonly LogEvent[], resource: string, identify: (path: string) => string): string | undefined {
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index]!;
+    if (event.t !== "tool_result") continue;
+    const effect = event.effect;
+    if ((effect?.kind === "read" || effect?.kind === "edit") && identify(effect.path) === resource)
+      return effect.kind === "read" ? effect.sha256 : effect.sha256_after;
+  }
+  return undefined;
+}
+
+export function isFileReadDescriptor(value: unknown): value is FileReadDescriptor {
+  if (!record(value) || value["kind"] !== "file_read" || value["version"] !== 1) return false;
+  const source = value["source"], selection = value["selection"];
+  return record(source) && ["host", "workspace", "resource"].every(key => typeof source[key] === "string" && source[key] !== "") &&
+    isFileDigest(source["sha256"]) && isObservationArtifact(source["raw"]) && source["raw"].sha256 === source["sha256"] &&
+    record(selection) && natural(selection["start"]) && selection["start"] >= 1 && natural(selection["end"]) &&
+    natural(selection["total_lines"]) && selection["start"] <= selection["end"] && selection["end"] <= selection["total_lines"];
+}
+
+/** Explicit premises take precedence; an omitted premise may use the complete log projection. */
+export function checkFilePrecondition(identity: FileIdentity, current: string | null, input: {
+  descriptor?: FileReadDescriptor; read_handle?: string; expected_sha256?: string; observed?: string; create_only?: boolean;
+}): FilePreconditionDecision {
+  const invalid = (message: string): FilePreconditionDecision => ({ ok: false, code: "invalid_input", message });
+  if (input.expected_sha256 !== undefined && !isFileDigest(input.expected_sha256)) return invalid("expected_sha256 must be a lowercase SHA-256 digest");
+  if (input.observed !== undefined && !isFileDigest(input.observed)) return invalid("the observed file version is invalid; inspect the original log");
+  if (input.create_only && (input.read_handle !== undefined || input.expected_sha256 !== undefined))
+    return invalid("create_only cannot be combined with read_handle or expected_sha256");
+  if ((input.read_handle === undefined) !== (input.descriptor === undefined)) return invalid("read_handle requires its verified descriptor");
+  if (input.descriptor) {
+    if (!isFileReadDescriptor(input.descriptor) || !isFileDigest(input.read_handle)) return invalid("invalid read_handle descriptor");
+    for (const field of ["host", "workspace", "resource"] as const)
+      if (input.descriptor.source[field] !== identity[field]) return invalid(`read_handle names another ${field}; read the intended file here`);
+    if (input.expected_sha256 !== undefined && input.expected_sha256 !== input.descriptor.source.sha256)
+      return invalid("read_handle and expected_sha256 name different versions");
+  }
+  const precondition: FilePrecondition = input.create_only ? { source: "create_only", expected: null }
+    : input.descriptor ? { source: "read_handle", expected: input.descriptor.source.sha256, read_handle: input.read_handle! }
+    : input.expected_sha256 !== undefined ? { source: "expected_sha256", expected: input.expected_sha256 }
+    : input.observed !== undefined ? { source: "session", expected: input.observed }
+    : { source: "unobserved", expected: null };
+  if (precondition.source !== "unobserved" && precondition.expected !== current)
+    return { ok: false, code: "version_mismatch", precondition,
+      message: `file version changed; expected ${precondition.expected ?? "absent"}, current sha256: ${current ?? "absent"}. Read the current file before retrying.` };
+  return { ok: true, precondition };
+}