@visual-z/xeno 0.3.0 → 0.5.0

package/src/core/completion-review.ts

@@ -12,8 +12,7 @@
  */
 import type { GuidanceEvent, LogEvent } from "./events.ts";
 import type { AcceptanceState } from "./acceptance.ts";
-import { changedPaths } from "./checkpoints.ts";
-import { resolveEvidence } from "./evidence.ts";
+import { deriveRequestState, type RequestState } from "./request-state.ts";
 
 /**
  * Wording that hands the task back instead of finishing it. Ported from
@@ -40,43 +39,53 @@ export function completionReview(
   remainingRequests: number,
   options?: { strictVerification?: boolean; acceptance?: AcceptanceState; taskAware?: boolean },
 ): Pick<GuidanceEvent, "reason" | "text" | "sources"> | null {
-  if (remainingRequests < 1) return null;
-  const start = events.findLastIndex((event) => event.t === "user");
-  if (start < 0) return null;
-  const current = events.slice(start);
-  if (current.some((event) => event.t === "guidance" && event.reason === "completion_review")) return null;
-  const final = current.findLast((event) => event.t === "assistant");
-  if (final?.t !== "assistant" || final.blocks.some((block) => block.type === "tool_use")) return null;
+  const state = deriveRequestState([{ node: 0, events }]);
+  const decision = state ? requestCompletion(state, remainingRequests, options) : { action: "finish" as const };
+  return decision.action === "continue" ? decision.guidance : null;
+}
+
+export type RequestCompletion = { action: "finish" } |
+  { action: "continue"; guidance: Pick<GuidanceEvent, "reason" | "text" | "sources"> };
 
-  const text = final.blocks.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n").trim();
-  const usedTools = current.some((event) => event.t === "tool_result");
-  const lastEdit = current.findLastIndex((event) => event.t === "tool_result" && event.effect?.kind === "edit" ||
-    event.t === "checkpoint" && event.phase === "applied" && changedPaths(event.changes).length > 0);
-  const verifiedAfter = lastEdit >= 0 && current.slice(lastEdit + 1)
-    .some((event) => event.t === "tool_result" && event.effect?.kind === "command" && event.effect.exit === 0 &&
-      resolveEvidence(current, { command: event.effect.cmd }).ok &&
-      (!options?.strictVerification || event.effect.gate !== undefined));
+/** Q23: loop termination and the public request view consume the same evidence. */
+export function requestCompletion(state: RequestState, remainingRequests: number,
+  options?: { strictVerification?: boolean; acceptance?: AcceptanceState; taskAware?: boolean }): RequestCompletion {
+  const finish = { action: "finish" as const };
+  if (remainingRequests < 1 || state.reviewed || state.status === "blocked") return finish;
+  const final = state.final;
+  if (!final || final.has_tools || state.execution?.reason !== "model_end" && state.execution?.reason !== "unknown") return finish;
+  const text = final.text;
+  const verifiedAfter = state.commands.some(command => command.status === "pass" && (!options?.strictVerification || command.gate !== undefined));
 
   const gaps: string[] = [];
-  if (usedTools && text.length === 0) gaps.push("the final reply is empty");
-  if (lastEdit >= 0 && !verifiedAfter && !options?.acceptance) gaps.push("files were changed but no command has succeeded since the last edit");
-  const acceptance = options?.acceptance;
+  const acceptance = options?.acceptance ?? state.acceptance;
+  const missingCommands = acceptance?.status === "needs_work" ? acceptance.criteria.flatMap(item =>
+    item.kind === "command" && item.status !== "pass" ? [{ id: item.id, command: item.command, status: item.status }] : []) : [];
+  if (state.used_tools && text.length === 0) gaps.push("the final reply is empty");
+  if (state.changed && !verifiedAfter && !acceptance) gaps.push("files were changed but no command has succeeded since the last edit");
   if (acceptance?.status === "needs_work") gaps.push(`declared acceptance criteria need evidence: ${[
-    ...acceptance.criteria.filter(item => item.kind === "command" && item.status !== "pass").map(item => `${item.id}=${item.status}`),
+    ...missingCommands.map(item => `${item.id}=${item.status}`),
     ...(acceptance.targets ?? []).filter(target => target.status !== "ready").map(target => `target ${target.id}=${target.status}`),
   ].join(", ")}`);
   if (text.length > 0 && looksLikeHandBack(text) && acceptance?.status !== "awaiting_human") gaps.push(options?.taskAware
     ? "the reply deferred the request; check whether authorized work remains or a specific blocker requires the user"
     : "the reply handed the task back instead of finishing it; no one will answer");
-  if (gaps.length === 0) return null;
-  return {
+  if (gaps.length === 0) return finish;
+  // D11 / O.11: a declared command needs its exact receipt even when the
+  // request has no recorded edit. Compound shell success is not that receipt.
+  const next = missingCommands.length > 0
+    ? "Obtain a fresh successful receipt for each missing command. Run each command exactly as a separate invocation without adding other commands:\n" +
+      missingCommands.map(item => `- ${item.id}: ${JSON.stringify(item.command)}`).join("\n") +
+      "\nIf verification cannot run, report the specific blocker. "
+    : options?.taskAware && !state.changed
+      ? "Use original sources for research and full inputs for calculations; do not invent command evidence. Finish with the result or the specific blocker. "
+      : "Run the command that verifies the result, or finish with the specific blocker that prevents verification. ";
+  return { action: "continue", guidance: {
     reason: "completion_review",
-    sources: [current[0]!.id, final.id],
+    sources: [state.request.event, final.source.event],
     text: `Harness completion check: ${gaps.join("; ")}. ` +
-      `Re-read the original request (event ${current[0]!.id}) and check each requirement against evidence in this session. ` +
-      (options?.taskAware && lastEdit < 0
-        ? "Use original sources for research and full inputs for calculations; do not invent command evidence. Required human acceptance remains pending. Finish with the result or the specific blocker. "
-        : "Run the command that verifies the result, or finish with the specific blocker that prevents verification. ") +
+      `Re-read the original request (event ${state.request.event}) and check each requirement against evidence in this session. ` +
+      next + (acceptance?.criteria.some(item => item.kind === "human" && item.status !== "accepted") ? "Required human acceptance remains pending. " : "") +
       "This check runs once per request.",
-  };
+  } };
 }

package/src/core/control-protocol.ts

@@ -0,0 +1,62 @@
+/** Q24: the experimental wire contract and its validator share one schema. No SDK dependency (D13). */
+const text = { type: "string", minLength: 1, maxLength: 65536 } as const;
+const identity = { type: "string", minLength: 1, maxLength: 128 } as const;
+const object = (properties: Record<string, unknown>, required: readonly string[] = Object.keys(properties)) =>
+  ({ type: "object", properties, required, additionalProperties: false });
+const thread = { threadId: identity };
+const turn = { ...thread, turnId: identity };
+
+export const CONTROL_METHODS = {
+  initialize: object({ clientInfo: object({ name: identity, version: identity }) }),
+  initialized: object({}),
+  "thread/read": object(thread),
+  "thread/subscribe": object({ ...thread, after: object({ streamId: identity, sequence: { type: "integer", minimum: 0 } }) }, ["threadId"]),
+  "turn/start": object({ ...thread, input: text }),
+  "turn/steer": object({ ...turn, input: text }),
+  "turn/interrupt": object(turn),
+  "approval/respond": object({ ...turn, approvalId: identity, choice: { enum: ["once", "command", "tool", "deny"] } }),
+  "acceptance/accept": object({ ...thread, requestId: identity, criterionId: identity }),
+  "context/read": object({ ...thread, focus: { enum: ["messages", "omitted", "history"] }, offset: { type: "integer", minimum: 0 },
+    limit: { type: "integer", minimum: 1, maximum: 100 } }, ["threadId", "focus"]),
+  "item/list": object({ ...thread, after: object({ node: { type: "integer", minimum: 0 }, event: identity }),
+    limit: { type: "integer", minimum: 1, maximum: 100 } }, ["threadId"]),
+  "item/read": object({ ...thread, node: { type: "integer", minimum: 0 }, event: identity }),
+} as const;
+export const CONTROL_SCHEMA = { protocol: "xeno-control/0.1", experimental: true,
+  transport: "JSONL; JSON-RPC envelopes with jsonrpc omitted", methods: CONTROL_METHODS,
+  notifications: ["turn/started", "turn/event", "item/completed", "turn/completed", "turn/error", "turn/steeringQueued", "approval/request", "approval/resolved", "thread/statusChanged"],
+  recovery: "subscribe first, then use the returned snapshot cursor; gaps or a new streamId require a snapshot and paginated item/list, never replaying commands",
+  identity: "threadId hashes the resolved session directory path; turnId is the original user event ID; item identity is node plus event ID",
+  limits: { frameBytes: 1048576, queuedRequests: 32, outputBytes: 2097152 } } as const;
+
+export type RpcId = string | number;
+export type ControlRequest = { id?: RpcId; method: keyof typeof CONTROL_METHODS; params: Record<string, unknown> };
+export class ControlProtocolError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string) { super(message); this.code = code; }
+}
+function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function matches(value: unknown, schemaValue: unknown): boolean {
+  const schema = schemaValue as Record<string, unknown>;
+  if (Array.isArray(schema["enum"])) return schema["enum"].includes(value);
+  if (schema["type"] === "string") return typeof value === "string" && value.length >= Number(schema["minLength"]) && value.length <= Number(schema["maxLength"]);
+  if (schema["type"] === "integer") return typeof value === "number" && Number.isSafeInteger(value) && value >= Number(schema["minimum"]) && (schema["maximum"] === undefined || value <= Number(schema["maximum"]));
+  if (schema["type"] === "object") {
+    if (!record(value)) return false;
+    const properties = schema["properties"] as Record<string, unknown>, required = schema["required"] as string[];
+    return required.every(key => Object.hasOwn(value, key)) && Object.keys(value).every(key => Object.hasOwn(properties, key) && matches(value[key], properties[key]));
+  }
+  return false;
+}
+export function parseControlRequest(value: unknown): ControlRequest {
+  if (!record(value) || typeof value["method"] !== "string" || Object.keys(value).some(key => !["id", "method", "params"].includes(key)))
+    throw new ControlProtocolError(-32600, "invalid request envelope");
+  const id = value["id"], method = value["method"];
+  if (id !== undefined && !(typeof id === "string" && id.length <= 128 || typeof id === "number" && Number.isSafeInteger(id)))
+    throw new ControlProtocolError(-32600, "invalid request id");
+  if (!Object.hasOwn(CONTROL_METHODS, method)) throw new ControlProtocolError(-32601, "unknown method");
+  const name = method as ControlRequest["method"], params = value["params"] ?? {};
+  if ((name === "initialized") !== (id === undefined)) throw new ControlProtocolError(-32600, "only initialized is a client notification");
+  if (!matches(params, CONTROL_METHODS[name])) throw new ControlProtocolError(-32602, `invalid parameters for ${name}`);
+  return { ...(id === undefined ? {} : { id }), method: name, params: params as Record<string, unknown> };
+}

package/src/core/control-view.ts

@@ -0,0 +1,42 @@
+/** Q24: control surfaces inspect original facts; they never own a second goal or context. */
+import { currentRequestRecords, deriveRequestState, type RequestPart, type RequestState } from "./request-state.ts";
+import { contextDetail } from "./context-detail.ts";
+import { projectContext } from "./project.ts";
+import { assertNever } from "./exhaustive.ts";
+
+export type GoalView = { text: string; state: RequestState; gaps: string[] };
+
+export function goalView(parts: readonly RequestPart[]): GoalView | null {
+  const state = deriveRequestState(parts);
+  const first = currentRequestRecords(parts)[0]?.event;
+  if (!state || first?.t !== "user") return null;
+  const gaps = state.acceptance
+    ? state.acceptance.criteria.filter(item => item.status !== "pass" && item.status !== "accepted").map(item => `${item.description}: ${item.status}`)
+    : ["No acceptance contract; command success does not verify the goal."];
+  gaps.push(...state.reported_blockers.map(item => `Reported blocker: ${item.reason}`));
+  return { text: first.text, state, gaps };
+}
+
+export type ContextLens = ReturnType<typeof contextLens>;
+export type LensFocus = "messages" | "omitted" | "history";
+
+export function contextLens(input: Parameters<typeof contextDetail>[0]) {
+  const detail = contextDetail(input);
+  const projected = projectContext(input);
+  return { ...detail,
+    messages: projected.messages.map((message, index) => ({ index, role: message.role, sources: detail.sources[index] ?? [],
+      reason: detail.sources[index]?.some(id => id.startsWith("handoff:")) ? "boundary handoff with recovery references" : "original events in the current segment" })),
+    omitted: detail.omittedEvents.map(id => ({ id, type: input.events.find(event => event.id === id)?.t ?? "unknown",
+      reason: "not replayed as a model message; original event remains in the log" })),
+  };
+}
+
+/** A lens filters the inspector only; it cannot change the provider projection (D1/D8). */
+export function selectLens(lens: ContextLens, focus: LensFocus): readonly unknown[] {
+  switch (focus) {
+    case "messages": return lens.messages;
+    case "omitted": return lens.omitted;
+    case "history": return lens.sections;
+    default: return assertNever(focus, "context lens");
+  }
+}

package/src/core/event-validation.ts

@@ -68,7 +68,7 @@ export function isLogEvent(value: unknown): value is LogEvent {
       (value["target_binding"] === undefined ? value["target_observation"] === undefined : has("target_binding", "target_observation"));
     case "target_observation": return isRuntimeTargetReceipt(value["observation"]);
     case "extension": return has("customType", "content") && typeof value["display"] === "boolean" && typeof value["inContext"] === "boolean" && (value["data"] === undefined || isJsonValue(value["data"]));
-    case "user": return has("text");
+    case "user": return has("text") && (value["request"] === undefined || typeof value["request"] === "string" && value["request"] !== "");
     case "outcome": return has("reason") && isExecutionOutcome(value["outcome"]);
     case "user_bash": {
       const ref = value["content_ref"];

package/src/core/events.ts

@@ -84,6 +84,8 @@ export interface UserEvent {
   id: EventId;
   at: IsoTime;
   text: string;
+  /** Q23: in-flight steering belongs to this original user event; legacy events open a request. */
+  request?: EventId;
   images?: readonly ImageRef[];
 }
 

package/src/core/harness-diagnostics.ts

@@ -0,0 +1,206 @@
+/** D11 / O.3: classify durable execution facts, never error words in tool output. */
+import type { LogEvent, ToolResultEvent } from "./events.ts";
+import type { BenchmarkUsage } from "./benchmark.ts";
+import { canonicalValue } from "./continuation.ts";
+
+export type ResultClass = "success" | "invalid_input" | "cancelled" | "timeout" | "command_nonzero" |
+  "execution_failed" | "rejected" | "unclassified_failure";
+
+export function classifyToolResult(event: ToolResultEvent): ResultClass {
+  const code = event.diagnostic?.code;
+  if (code === "invalid_input") return "invalid_input";
+  if (code === "cancelled" || event.outcome?.reason === "cancelled") return "cancelled";
+  if (code === "timeout" || event.outcome?.reason === "timeout") return "timeout";
+  if (event.effect?.kind === "command" && event.effect.exit !== 0) return "command_nonzero";
+  if (event.ok) return "success";
+  if (event.diagnostic?.execution === "not_started" ||
+    ["version_mismatch", "not_found", "ambiguous_edit", "permission_denied", "environment_missing"].includes(code ?? "")) return "rejected";
+  if (code === "execution_failed" || code === "unknown_effect" || event.outcome?.reason === "execution_error") return "execution_failed";
+  return "unclassified_failure";
+}
+
+export interface DiagnosticRequest {
+  request: number;
+  node: number | null;
+  usage: BenchmarkUsage | null;
+  responseModel: string | null;
+  failure: string | null;
+  firstDeltaMs: number | null;
+  wallMs: number | null;
+  prefixUnchanged: boolean | null;
+  sharedInputBytes: number | null;
+  frozenSha256: string | null;
+  /** Raw terminal counts can remain known when a cache breakdown is absent. */
+  reportedPromptTokens?: number | null;
+  reportedOutputTokens?: number | null;
+}
+export interface ToolCounters {
+  calls: number; providerCalls: number; invocations: number; nestedInvocations: number;
+  results: number; pairedCalls: number; orphanCalls: number; orphanResults: number;
+  duplicateProviderCalls: number; duplicateInvocations: number; duplicateResults: number;
+  repeatedProviderInputs: number; repeatedInvocationInputs: number;
+  classes: Record<ResultClass, number>;
+  diagnosticCodes: Record<string, number>;
+  commandExits: Record<string, number>;
+  expectedNonzeroCommands: number;
+  undeclaredNonzeroCommands: number;
+}
+const classes = (): Record<ResultClass, number> => ({ success: 0, invalid_input: 0, cancelled: 0, timeout: 0,
+  command_nonzero: 0, execution_failed: 0, rejected: 0, unclassified_failure: 0 });
+const counters = (): ToolCounters => ({ calls: 0, providerCalls: 0, invocations: 0, nestedInvocations: 0,
+  results: 0, pairedCalls: 0, orphanCalls: 0, orphanResults: 0, duplicateProviderCalls: 0,
+  duplicateInvocations: 0, duplicateResults: 0, repeatedProviderInputs: 0, repeatedInvocationInputs: 0,
+  classes: classes(), diagnosticCodes: {}, commandExits: {}, expectedNonzeroCommands: 0, undeclaredNonzeroCommands: 0 });
+function add(record: Record<string, number>, key: string): void { record[key] = (record[key] ?? 0) + 1; }
+const validCount = (value: number): boolean => Number.isSafeInteger(value) && value >= 0;
+const reportedCount = (value: number | null | undefined): number | null => typeof value === "number" && validCount(value) ? value : null;
+const validTime = (value: number | null): number | null => value !== null && Number.isFinite(value) && value >= 0 ? value : null;
+function observedUsage(usage: BenchmarkUsage | null): BenchmarkUsage | null {
+  return usage && [usage.input_tokens, usage.output_tokens, usage.cache_read_input_tokens,
+    usage.cache_creation_input_tokens].every(validCount) ? usage : null;
+}
+function quantile(values: readonly number[], q: number): number | null {
+  return values.length ? values.toSorted((a, b) => a - b)[Math.max(0, Math.ceil(values.length * q) - 1)]! : null;
+}
+interface Call {
+  name: string; provider: boolean; invocation: boolean; nested: boolean;
+  providerInput: string | null; invocationInput: string | null;
+}
+
+/**
+ * Inputs and outputs remain private. Equal-input counts use canonical original
+ * model arguments and immutable admitted-input hashes separately (O.3 / Pi A).
+ * Expected nonzero exits need an evaluator declaration; an exit alone cannot
+ * prove a command was accidental, and model prose cannot establish intent.
+ */
+export function summarizeHarnessDiagnostics(input: {
+  events: readonly LogEvent[]; requests: readonly DiagnosticRequest[];
+  expectedNonzeroCallIds?: readonly string[];
+}) {
+  const tools: Record<string, ToolCounters> = {};
+  const tool = (name: string): ToolCounters => tools[name] ??= counters();
+  const calls = new Map<string, Call>(), results = new Map<string, ToolResultEvent[]>(), seenEvents = new Set<string>();
+  const guidance: Record<string, number> = {}, cuts: Record<string, number> = {}, cleanupProcessExits: Record<string, number> = {};
+  let duplicateEvents = 0, interruptions = 0;
+  for (const event of input.events) {
+    if (seenEvents.has(event.id)) { duplicateEvents++; continue; }
+    seenEvents.add(event.id);
+    if (event.t === "guidance") add(guidance, event.reason);
+    if (event.t === "cut") add(cuts, event.reason);
+    if (event.t === "interrupt") interruptions++;
+    if (event.t === "process_exit") add(cleanupProcessExits, String(event.exit));
+    if (event.t === "assistant") for (const block of event.blocks) {
+      if (block.type !== "tool_use") continue;
+      const existing = calls.get(block.call_id), stats = tool(block.name);
+      if (existing?.provider) stats.duplicateProviderCalls++;
+      calls.set(block.call_id, { name: existing?.name ?? block.name, provider: true,
+        invocation: existing?.invocation ?? false, nested: existing?.nested ?? false,
+        providerInput: canonicalValue(block.input), invocationInput: existing?.invocationInput ?? null });
+    }
+    if (event.t === "tool_invocation") {
+      const existing = calls.get(event.call_id), stats = tool(event.name);
+      if (existing?.invocation) stats.duplicateInvocations++;
+      calls.set(event.call_id, { name: existing?.name ?? event.name, provider: existing?.provider ?? false,
+        invocation: true, nested: event.parent_call_id !== undefined,
+        providerInput: existing?.providerInput ?? null, invocationInput: event.input_ref.sha256 });
+    }
+    if (event.t === "tool_result") {
+      const found = results.get(event.call_id) ?? [];
+      found.push(event); results.set(event.call_id, found);
+    }
+  }
+  const providerInputs = new Map<string, Set<string>>(), invocationInputs = new Map<string, Set<string>>();
+  const repeat = (groups: Map<string, Set<string>>, name: string, key: string | null): boolean => {
+    if (key === null) return false;
+    const seen = groups.get(name) ?? new Set<string>(), repeated = seen.has(key);
+    seen.add(key); groups.set(name, seen); return repeated;
+  };
+  for (const [id, call] of calls) {
+    const stats = tool(call.name); stats.calls++;
+    if (call.provider) stats.providerCalls++;
+    if (call.invocation) stats.invocations++;
+    if (call.nested) stats.nestedInvocations++;
+    if (repeat(providerInputs, call.name, call.providerInput)) stats.repeatedProviderInputs++;
+    if (repeat(invocationInputs, call.name, call.invocationInput)) stats.repeatedInvocationInputs++;
+    if (results.has(id)) stats.pairedCalls++; else stats.orphanCalls++;
+  }
+  const expected = new Set(input.expectedNonzeroCallIds ?? []);
+  for (const [id, found] of results) {
+    const call = calls.get(id), stats = tool(call?.name ?? "<orphan>");
+    stats.duplicateResults += Math.max(0, found.length - 1);
+    for (const event of found) {
+      stats.results++;
+      if (!call) stats.orphanResults++;
+      stats.classes[classifyToolResult(event)]++;
+      if (event.diagnostic) add(stats.diagnosticCodes, event.diagnostic.code);
+      if (event.effect?.kind === "command") {
+        add(stats.commandExits, String(event.effect.exit));
+        if (event.effect.exit !== 0) {
+          if (expected.has(id)) stats.expectedNonzeroCommands++; else stats.undeclaredNonzeroCommands++;
+        }
+      }
+    }
+  }
+  const requestIds = new Set<number>(), requests: {
+    request: number; node: number | null; usageKnown: boolean; promptTokens: number | null;
+    cachedTokens: number | null; cacheWriteTokens: number | null; outputTokens: number | null;
+    cacheHitRate: number | null; responseModel: string | null; failure: string | null;
+    firstDeltaMs: number | null; wallMs: number | null; prefixUnchanged: boolean | null; sharedInputBytes: number | null;
+  }[] = [];
+  const models: Record<string, number> = {};
+  const usage = { knownRequests: 0, unknownRequests: 0, requestsWithCacheReads: 0, promptTokens: 0, cachedTokens: 0,
+    cacheWriteTokens: 0, outputTokens: 0, promptKnownRequests: 0, promptUnknownRequests: 0,
+    cacheCoveredPromptTokens: 0, cacheCoverageRate: null as number | null,
+    observedCacheHitRate: null as number | null, cacheHitRate: null as number | null };
+  const prefix = { sameNodeComparisons: 0, sameNodeMutations: 0, boundaryComparisons: 0, boundaryMutations: 0,
+    unknownComparisons: 0, sameNodeFrozenMutations: 0, boundaryFrozenMutations: 0 };
+  let previous: DiagnosticRequest | undefined, duplicateRequests = 0;
+  for (const request of input.requests.toSorted((a, b) => a.request - b.request)) {
+    if (requestIds.has(request.request)) { duplicateRequests++; continue; }
+    requestIds.add(request.request);
+    const observed = observedUsage(request.usage);
+    const prompt = reportedCount(request.reportedPromptTokens) ?? (observed ?
+      observed.input_tokens + observed.cache_read_input_tokens + observed.cache_creation_input_tokens : null);
+    const output = reportedCount(request.reportedOutputTokens) ?? observed?.output_tokens ?? null;
+    if (prompt !== null) { usage.promptKnownRequests++; usage.promptTokens += prompt; } else usage.promptUnknownRequests++;
+    if (output !== null) usage.outputTokens += output;
+    if (observed) {
+      usage.knownRequests++; usage.cacheCoveredPromptTokens += prompt!; usage.cachedTokens += observed.cache_read_input_tokens;
+      usage.cacheWriteTokens += observed.cache_creation_input_tokens;
+      if (observed.cache_read_input_tokens > 0) usage.requestsWithCacheReads++;
+    } else usage.unknownRequests++;
+    if (request.responseModel !== null) add(models, request.responseModel);
+    if (previous) {
+      if (previous.node === null || request.node === null || request.prefixUnchanged === null) prefix.unknownComparisons++;
+      else if (previous.node === request.node) { prefix.sameNodeComparisons++; if (!request.prefixUnchanged) prefix.sameNodeMutations++; }
+      else { prefix.boundaryComparisons++; if (!request.prefixUnchanged) prefix.boundaryMutations++; }
+      if (previous.frozenSha256 !== null && request.frozenSha256 !== null && previous.frozenSha256 !== request.frozenSha256) {
+        if (previous.node === request.node && request.node !== null) prefix.sameNodeFrozenMutations++;
+        else if (previous.node !== null && request.node !== null) prefix.boundaryFrozenMutations++;
+      }
+    }
+    previous = request;
+    requests.push({ request: request.request, node: request.node, usageKnown: observed !== null, promptTokens: prompt,
+      cachedTokens: observed?.cache_read_input_tokens ?? null, cacheWriteTokens: observed?.cache_creation_input_tokens ?? null,
+      outputTokens: output, cacheHitRate: observed && prompt ? observed.cache_read_input_tokens / prompt : null,
+      responseModel: request.responseModel, failure: request.failure, firstDeltaMs: validTime(request.firstDeltaMs),
+      wallMs: validTime(request.wallMs), prefixUnchanged: request.prefixUnchanged, sharedInputBytes: request.sharedInputBytes });
+  }
+  usage.observedCacheHitRate = usage.cacheCoveredPromptTokens > 0 ? usage.cachedTokens / usage.cacheCoveredPromptTokens : null;
+  usage.cacheCoverageRate = usage.promptUnknownRequests === 0 && usage.promptTokens > 0 ? usage.cacheCoveredPromptTokens / usage.promptTokens : null;
+  usage.cacheHitRate = usage.unknownRequests === 0 && usage.promptTokens > 0 ? usage.cachedTokens / usage.promptTokens : null;
+  const delta = requests.flatMap(r => r.firstDeltaMs === null ? [] : [r.firstDeltaMs]);
+  const totals = counters();
+  for (const stats of Object.values(tools)) {
+    for (const key of Object.keys(totals) as (keyof ToolCounters)[]) {
+      const value = stats[key];
+      if (typeof value === "number") (totals[key] as number) += value;
+    }
+    for (const key of Object.keys(stats.classes) as ResultClass[]) totals.classes[key] += stats.classes[key];
+    for (const key of Object.keys(stats.commandExits)) totals.commandExits[key] = (totals.commandExits[key] ?? 0) + stats.commandExits[key]!;
+    for (const key of Object.keys(stats.diagnosticCodes)) totals.diagnosticCodes[key] = (totals.diagnosticCodes[key] ?? 0) + stats.diagnosticCodes[key]!;
+  }
+  return { eventCount: seenEvents.size, duplicateEvents, tools, totals, guidance, cuts, interruptions, cleanupProcessExits,
+    requestCount: requests.length, duplicateRequests, models, usage, prefix, requests,
+    firstDeltaMs: { samples: delta.length, missing: requests.length - delta.length, p50: quantile(delta, 0.5), p95: quantile(delta, 0.95) } };
+}

package/src/core/model-preferences.ts

@@ -0,0 +1,28 @@
+/** User selections become startup preferences; restored session state stays in the log (D8/Q.25). */
+import { recordRecent } from "./model-picker.ts";
+import { modelKey } from "./session-position.ts";
+import { settingsToWrite, type Settings } from "./settings.ts";
+import type { ThinkingLevel } from "./thinking.ts";
+
+interface ModelIdentity { readonly provider: string; readonly id: string }
+
+/** Keep the effective effort with its model, without changing another model's saved effort. */
+export function modelPreferencePatch(model: ModelIdentity, recent: readonly string[], effort: ThinkingLevel): Settings {
+  return { defaultProvider: model.provider, defaultModel: model.id, recentModels: recordRecent(recent, modelKey(model)),
+    modelThinkingLevels: { [modelKey(model)]: effort } };
+}
+
+export function thinkingPreferencePatch(model: ModelIdentity, effort: ThinkingLevel): Settings {
+  return { defaultThinking: effort, modelThinkingLevels: { [modelKey(model)]: effort } };
+}
+
+/** Patch only known preferences; retain future keys and nested fields not owned by this selection. */
+export function mergePreferenceJson(previous: Readonly<Record<string, unknown>>, patch: Settings): Record<string, unknown> {
+  const next = { ...previous, ...settingsToWrite(patch) };
+  for (const key of ["terminal", "images", "markdown", "modelThinkingLevels"] as const) {
+    if (patch[key] === undefined) continue;
+    const old = previous[key];
+    next[key] = { ...(old !== null && typeof old === "object" && !Array.isArray(old) ? old : {}), ...patch[key] };
+  }
+  return next;
+}

package/src/core/oauth-fields.ts

@@ -0,0 +1,44 @@
+/** Validated wire data only; the runtime owns HTTP, time, polling and persistence. */
+export interface OAuthTokens { access: string; refresh: string; expiresIn: number }
+export interface DeviceAuthorization {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete?: string;
+  expiresIn: number;
+  interval?: number;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function positive(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value > 0; }
+function token(value: unknown): value is string { return typeof value === "string" && value.length > 0 && !/[\s\x00-\x1f\x7f]/.test(value); }
+
+/** Refresh rotation is optional; omission preserves the existing refresh capability. */
+export function parseOAuthTokens(value: unknown, previousRefresh?: string): OAuthTokens | undefined {
+  const data = record(value);
+  const access = data?.["access_token"], refresh = data?.["refresh_token"] ?? previousRefresh, expiresIn = data?.["expires_in"];
+  if (!token(access) || !token(refresh) || !positive(expiresIn)) return undefined;
+  return { access, refresh, expiresIn };
+}
+
+export function trustedOAuthUrl(value: unknown, origins: readonly string[]): value is string {
+  if (typeof value !== "string" || /[\x00-\x20\x7f]/.test(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password && origins.includes(url.origin);
+  } catch { return false; }
+}
+
+/** Never open an issuer-supplied arbitrary origin or print its control characters. */
+export function parseDeviceAuthorization(value: unknown, origins: readonly string[]): DeviceAuthorization | undefined {
+  const data = record(value);
+  const deviceCode = data?.["device_code"], userCode = data?.["user_code"], verificationUri = data?.["verification_uri"];
+  const complete = data?.["verification_uri_complete"], expiresIn = data?.["expires_in"], interval = data?.["interval"];
+  if (!token(deviceCode) || typeof userCode !== "string" || !/^[A-Za-z0-9-]+$/.test(userCode)
+    || !trustedOAuthUrl(verificationUri, origins) || !positive(expiresIn)
+    || (complete !== undefined && !trustedOAuthUrl(complete, origins)) || (interval !== undefined && !positive(interval))) return undefined;
+  return { deviceCode, userCode, verificationUri, expiresIn,
+    ...(typeof complete === "string" ? { verificationUriComplete: complete } : {}), ...(typeof interval === "number" ? { interval } : {}) };
+}

package/src/core/permissions.ts

@@ -3,8 +3,8 @@
  * call is allow / ask / deny.
  *
  * Approval is the last look at what is about to run, not a boundary.
- * Path tools are already confined to the workspace root; bash is not,
- * which is why bash defaults to ask and everything else to allow.
+ * Path tools are already confined to the workspace root; host commands
+ * are not, which is why shell entry points default to ask.
  *
  * This module must stay free of I/O, clocks, and randomness. The CLI
  * compiles flags and session memory into a rule list; this file only
@@ -75,8 +75,8 @@ export interface ToolSelection {
 export const ALLOW_TOOLS_FLAG = "--allow-tools";
 
 /**
- * Product default. bash asks because it is not confined to the workspace
- * root; every other built-in is allow because the path tools are.
+ * Product default. Shell entry points ask because their effects are not
+ * confined to the workspace root; path tools keep their own confinement.
  */
 export function defaultRules(): readonly PermissionRule[] {
   return [
@@ -91,9 +91,15 @@ export function defaultRules(): readonly PermissionRule[] {
 }
 
 /**
- * `--allow-tools` compiled to rules, in front of the defaults so they win.
+ * CLI opt-ins compiled to one process-scoped rule list. YOLO permits every
+ * tool; capability admission and path confinement still apply (D13).
+ * Neither this flag nor remembered approvals become a persisted policy.
  */
-export function rulesWithAllowTools(allowTools: readonly string[]): PermissionRule[] {
+export function rulesWithAllowTools(
+  allowTools: readonly string[],
+  options: { readonly yolo?: boolean } = {},
+): PermissionRule[] {
+  if (options.yolo === true) return [{ action: "allow" }];
   return [
     ...allowTools.map((tool) => ({ action: "allow" as const, tool })),
     ...defaultRules(),
@@ -109,7 +115,7 @@ export function ruleMatches(rule: PermissionRule, request: PermissionRequest): b
 /**
  * First matching rule wins. An empty list allows: the tool tests pass no
  * rules because they are testing the tool, not the gate. The CLI always
- * supplies defaultRules().
+ * supplies the current process's compiled policy.
  */
 export function decide(
   rules: readonly PermissionRule[],

package/src/core/program-status.ts

@@ -0,0 +1,31 @@
+/** OSC 7501 revision 0.2: program state, never a model's claim of goal completion (Q24/D11). */
+import type { ExecutionOutcome } from "./outcome.ts";
+
+export type ProgramStatus = { state: "idle" | "working" | "done" | "blocked" | "error" | "clear";
+  kind?: "permission" | "question" | "auth"; msg?: string };
+export function programStatus(input: { running: boolean; waiting?: "permission" | "question" | "auth" | null;
+  outcome?: ExecutionOutcome; goal?: string }): ProgramStatus {
+  if (input.waiting) return { state: "blocked", kind: input.waiting, msg: input.waiting === "auth" ? "Sign in to continue" : input.waiting === "permission" ? "Tool approval required" : "User input required" };
+  if (input.running) return { state: "working", msg: "Agent is working" };
+  if (input.outcome?.status === "cancelled") return { state: "idle", msg: "Turn cancelled" };
+  if (input.outcome?.status === "failed") return { state: "error", msg: "Turn failed; inspect the session" };
+  if (input.outcome?.status === "stopped") return { state: "blocked", kind: "question", msg: "Turn stopped; review evidence before continuing" };
+  if (input.goal === "awaiting_human" || input.goal === "blocked") return { state: "blocked", kind: "question", msg: "Goal awaits user review" };
+  if (input.outcome?.reason === "model_end") return { state: "done", msg: input.goal === "verified" ? "Goal verified against its contract" : "Turn finished; goal verification incomplete" };
+  return { state: "idle", msg: "Ready for a request" };
+}
+export const PROGRAM_STATUS_QUERY = "\x1b]7501;?\x1b\\";
+export function programStatusReply(sequence: string): boolean { return /^\x1b\]7501;\?[^\x00-\x1f\x7f]*(?:\x07|\x1b\\)$/.test(sequence); }
+
+export function encodeProgramStatus(status: ProgramStatus, id: string): string {
+  if (id.length > 128 || id.split("/").length > 8 || !id.split("/").every(part => /^[A-Za-z0-9_.+-]{1,32}$/.test(part))) throw Error("invalid program status id");
+  let message = "", size = 0;
+  // Protocol's decoded UTF-8 cap. Remove controls before encoding; never split a code point.
+  for (const point of (status.msg ?? "").replace(/[\x00-\x1f\x7f-\x9f\p{Cf}]/gu, " ")) {
+    const bytes = new TextEncoder().encode(point); if (size + bytes.length > 2048) break;
+    message += point; size += bytes.length;
+  }
+  const encoded = btoa(Array.from(new TextEncoder().encode(message), byte => String.fromCharCode(byte)).join(""));
+  return `\x1b]7501;state=${status.state}:app=xeno:id=${id}` +
+    (status.state === "blocked" && status.kind ? `:kind=${status.kind}` : "") + (message ? `:msg=${encoded}` : "") + "\x1b\\";
+}

package/src/core/project.ts

@@ -89,10 +89,31 @@ export interface ProjectResult {
 }
 
 export interface ProjectViolation {
-  code: "UNPAIRED_TOOL_USE" | "ORPHAN_TOOL_RESULT" | "EMPTY_PROJECTION";
+  code: "UNPAIRED_TOOL_USE" | "ORPHAN_TOOL_RESULT" | "EMPTY_PROJECTION" | "DUPLICATE_TOOL_USE" | "EMPTY_TOOL_USE_ID";
   detail: string;
 }
 
+/**
+ * D5: a receipt identifies exactly one call in its assistant batch. Validate
+ * before either the projection's Set or the runtime's scheduling Map can erase
+ * a collision; repairing IDs would invent provider protocol history.
+ */
+export function toolCallIdentityViolations(blocks: readonly AssistantBlock[]): ProjectViolation[] {
+  const violations: ProjectViolation[] = [], seen = new Map<string, number>();
+  for (const [index, block] of blocks.entries()) {
+    if (block.type !== "tool_use") continue;
+    if (block.call_id.trim().length === 0) {
+      violations.push({ code: "EMPTY_TOOL_USE_ID", detail: `tool_use block ${index} has an empty call_id` });
+      continue;
+    }
+    const previous = seen.get(block.call_id);
+    if (previous !== undefined) {
+      violations.push({ code: "DUPLICATE_TOOL_USE", detail: `tool_use block ${index} repeats the call_id of block ${previous}` });
+    } else seen.set(block.call_id, index);
+  }
+  return violations;
+}
+
 /**
  * The only event types that replay as messages.
  *
@@ -346,6 +367,9 @@ export function projectContext(input: ProjectInput): ProjectResult {
 
     if (e.t === "assistant") {
       flushPending();
+      violations.push(...toolCallIdentityViolations(e.blocks).map(violation => ({
+        ...violation, detail: `assistant turn ${e.id}: ${violation.detail}`,
+      })));
       if (awaiting.size > 0) {
         violations.push({
           code: "UNPAIRED_TOOL_USE",