@visual-z/xeno 0.7.2 → 0.8.0

package/src/core/project.ts

@@ -72,7 +72,7 @@ export interface ProjectInput {
   handoff: Handoff | null;
   events: readonly LogEvent[];
   /** Source locations and versioned recovery guidance; workspace search does not index the log. */
-  logHint?: { manifestPath: string; segmentPath: string; scopedGuidance?: true };
+  logHint?: { manifestPath: string; segmentPath: string };
 }
 
 export interface ProjectResult {
@@ -138,7 +138,7 @@ export function toolCallIdentityViolations(blocks: readonly AssistantBlock[]): P
  * two things". It is a following message rather than a mutation of the user
  * turn so appending the event only appends to the projection (P7).
  */
-type ReplayEvent = Extract<LogEvent, { t: "acceptance_contract" | "acceptance_decision" | "user" | "user_bash" | "guidance" | "interrupt" | "assistant" | "tool_result" | "rewind" | "snapshot" | "extension" }>;
+type ReplayEvent = Extract<LogEvent, { t: "acceptance_contract" | "acceptance_decision" | "user" | "user_bash" | "guidance" | "interrupt" | "assistant" | "tool_result" | "rewind" | "extension" }>;
 
 function replayable(e: LogEvent): e is ReplayEvent {
   if (e.t === "tool_result" && (e.parent_call_id !== undefined || e.origin === "extension")) return false;
@@ -146,7 +146,6 @@ function replayable(e: LogEvent): e is ReplayEvent {
   if (e.t === "extension") return e.inContext;
   if (e.t === "user_bash") return !e.excludeFromContext;
   if (e.t === "rewind") return e.mode !== "both";
-  if (e.t === "snapshot") return e.undeclared.length > 0;
   return e.t === "user" || e.t === "guidance" || e.t === "interrupt" || e.t === "assistant" || e.t === "tool_result";
 }
 
@@ -228,7 +227,7 @@ export function renderRewindMessage(e: Extract<LogEvent, { t: "rewind" }>): Mess
  */
 export function renderHandoffMessage(
   handoff: Handoff,
-  logHint?: { manifestPath: string; segmentPath: string; scopedGuidance?: true },
+  logHint?: { manifestPath: string; segmentPath: string },
 ): Message {
   const yaml = emitHandoff(handoff);
 
@@ -251,10 +250,7 @@ export function renderHandoffMessage(
       "detail this state does not carry, read it rather than guessing:",
       `  - segment index: ${logHint.manifestPath}`,
       `  - previous segment: ${logHint.segmentPath}`,
-      ...(logHint.scopedGuidance !== true ? [
-        "Each line is one JSON event. Search it with history; read a line range with read,",
-        "or filter with bash and jq. The grep tool skips the log directory.",
-      ] : ["Each line is one JSON event. Recover originals using the declared tools' contracts; if evidence is inaccessible, state the gap instead of guessing."]),
+      "Each line is one JSON event. Recover originals using the declared tools' contracts; if evidence is inaccessible, state the gap instead of guessing.",
     );
   }
 
@@ -329,13 +325,6 @@ export function projectContext(input: ProjectInput): ProjectResult {
       append({ role: "user", content: [{ type: "text", text: `User ran: ${e.command}\n${e.content}` }] }, [e.id]);
       continue;
     }
-    if (e.t === "snapshot") {
-      flushPending();
-      append({ role: "user", content: [{ type: "text",
-        text: `Workspace observation: changes outside declared file edits: ${e.undeclared.join(", ")}. ${REREAD_INSTRUCTION}`,
-      }] }, [e.id]);
-      continue;
-    }
     if (e.t === "rewind") {
       // Flushed first for the same reason a user turn is: it opens a user
       // message, and a pending tool_result batch has to close before it.
@@ -396,7 +385,8 @@ export function projectContext(input: ProjectInput): ProjectResult {
     pending.push({
       type: "tool_result",
       tool_use_id: e.call_id,
-      content: diagnosticContent(e.content, e.diagnostic) + (e.warnings?.length ? "\nObserver warnings (operation result retained): " + JSON.stringify(e.warnings) : ""),
+      content: diagnosticContent(e.content, e.diagnostic) + (e.warnings?.length ? "\nObserver warnings (operation result retained): " + JSON.stringify(e.warnings) : "") +
+        (e.instructions ? "\n\n" + e.instructions.text : ""),
       ...(e.ok ? {} : { is_error: true }),
     });
     // Images follow the paired text result, so APIs without image tool outputs receive a user image.

package/src/core/read-bounds.ts

@@ -10,6 +10,15 @@ export function readBounds(total: number, first: unknown, last: unknown):
   if (start > total) return { ok: false, message: `read start ${start} is beyond end of file (${bounds}); choose a start in that range` };
   if (end < start) return { ok: false, message: `read end ${end} precedes start ${start} (${bounds})` };
   const actualEnd = Math.min(end, total);
-  return { ok: true, start, end: actualEnd,
-    notice: `[Read selection: lines ${start}-${actualEnd}; total lines: ${total}; ${actualEnd < total ? `next start: ${actualEnd + 1}` : "end of file"}.]` };
+  return { ok: true, start, end: actualEnd, notice: readNotice(start, actualEnd, total) };
+}
+
+/**
+ * The selection header. `budget` names the byte limit when it, rather than the
+ * requested range, ended the selection, so "next start" is never mistaken for
+ * the end of what was asked.
+ */
+export function readNotice(start: number, end: number, total: number, budget?: number): string {
+  const rest = end < total ? `next start: ${end + 1}${budget === undefined ? "" : `; stopped at the ${budget}-byte output budget`}` : "end of file";
+  return `[Read selection: lines ${start}-${end}; total lines: ${total}; ${rest}.]`;
 }

package/src/core/read-observation.ts

@@ -65,6 +65,30 @@ export function previewReadObservation(header: string, lines: readonly string[],
     visible, next_offset: next === source ? null : next } };
 }
 
+/**
+ * How many of `lines` a read shows whole within `maxBytes`. OpenCode and Pi cut
+ * a file read at a line boundary and name the next offset; eliding the middle
+ * lets a receipt claim "end of file" while hiding the lines between, so the
+ * model re-reads them and the stall ledger, trusting the claimed range, counts
+ * that as no progress. At least one line is kept: a single line over budget
+ * is still cut inside itself, with its recovery reference.
+ */
+export function linesWithin(header: (count: number) => string, lines: readonly string[], start: number,
+  maxBytes: number, maxLineChars = READ_MAX_LINE_CHARS, tools?: readonly string[]): number {
+  // Rendered without a byte cut, so only the budget decides; a line cut at
+  // maxLineChars is already part of the rendering. Any 64-hex artifact name
+  // renders recovery references at their final length.
+  const fits = (count: number) => size(previewReadObservation(header(count), lines.slice(0, count), start, "0".repeat(64),
+    Number.MAX_SAFE_INTEGER, maxLineChars, tools).text) <= maxBytes;
+  if (lines.length === 0 || fits(lines.length)) return lines.length;
+  let low = 1, high = lines.length - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (fits(mid)) low = mid; else high = mid - 1;
+  }
+  return low;
+}
+
 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;
 const digest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);

package/src/core/request-budget.ts

@@ -1,7 +1,11 @@
-/** D6 / Q.26: finalization spends the existing budget and cannot admit new work. */
+/**
+ * D6 / Q.26: finalization spends the existing budget and cannot admit new work.
+ * `Infinity` is no cap (S.6 item 1): there is no final request to reserve, and
+ * the stall watchdog is what ends a run that stops producing evidence.
+ */
 export function requestPhase(index: number, limit: number): "work" | "finalize" | "exhausted" {
-  if (!Number.isSafeInteger(limit) || limit < 1 || !Number.isSafeInteger(index) || index < 0)
-    throw new RangeError("request budget requires positive integer limit and nonnegative index");
+  if (!(Number.isSafeInteger(limit) || limit === Infinity) || limit < 1 || !Number.isSafeInteger(index) || index < 0)
+    throw new RangeError("request budget requires a positive integer or unbounded limit and a nonnegative index");
   if (index >= limit) return "exhausted";
   // One request cannot both investigate and close. Preserve that work opportunity;
   // its deterministic outcome is the exit, without a second paid request.
@@ -11,3 +15,9 @@ export function requestPhase(index: number, limit: number): "work" | "finalize"
 export function finalizationNotice(): string {
   return "Harness: this is the final request in the existing budget. Tools are disabled by the host. Give the user a concise answer from the observations already recorded: what is established, what remains unresolved, and the next useful action. Do not claim unobserved execution or verified completion.";
 }
+
+/** Without a request cap the stall watchdog is the only backstop, so it cannot be off (S.6 item 1). */
+export function validateRequestBudget(limit: number, stallLimit: number): void {
+  requestPhase(0, limit);
+  if (limit === Infinity && stallLimit === 0) throw new RangeError("an unbounded request budget requires the stall watchdog");
+}

package/src/core/request-state.ts

@@ -1,7 +1,17 @@
-/** Q23 / D8 / D11: disposable request evidence, derived only from the selected log ancestry. */
+/**
+ * The request ledger (S.1, Q23 / D8 / D11): what the current request has
+ * evidence for, derived only from the selected log ancestry.
+ *
+ * Every view of "is this request done" -- the completion check, the goal
+ * panel, terminal status, branch receipts -- maps from this one derivation,
+ * so they cannot disagree. Only harness-observed facts move it: command
+ * receipts with their workspace fingerprints, file versions, and the user's
+ * acceptance decisions. A model note can describe a blocker; it never changes
+ * the status.
+ */
 import type { LogEvent } from "./events.ts";
-import { deriveAcceptance, type AcceptanceState } from "./acceptance.ts";
-import { changedPaths } from "./checkpoints.ts";
+import { counterVerdict, deriveAcceptance, type AcceptanceState, type CounterVerdict } from "./acceptance.ts";
+import { changedPaths, workspaceChanged } from "./checkpoints.ts";
 import { evidenceStale, isCommandResult, resolveEvidence } from "./evidence.ts";
 import { executionOutcome, modelOutcome, type ExecutionOutcome } from "./outcome.ts";
 import { deriveWorkItems, type WorkItem } from "./work-state.ts";
@@ -14,18 +24,74 @@ export type RequestCommand = {
 };
 export type RequestArtifact = { source: RequestSource; path: string; sha256: string | null;
   kind: "read" | "edit" | "checkpoint" | "command_output" };
+
+/**
+ * One requirement this request must meet. With a declared contract these are
+ * its criteria. Without one, a request that changed the workspace still has
+ * one requirement: a successful check after its last change.
+ */
+export type RequestCriterion = {
+  id: string; kind: "command" | "human" | "fresh_check"; description: string;
+  status: "pass" | "fail" | "stale" | "not_run" | "awaiting_human" | "accepted";
+  command?: string; evidence?: string;
+  /** A declared guard: it must pass before and after the work, rather than fail before it (S.7). */
+  guard?: true;
+  /** The latest counter-check of this criterion in the request, when one ran, read against its role. */
+  counter?: CounterVerdict;
+  /**
+   * Consecutive runs of this exact command that failed with the same exit code
+   * against the same workspace. Two or more mean rerunning it unchanged will
+   * not change the answer: the work, or the check itself, must change.
+   */
+  repeated_failures?: number;
+  /** A fresh check under strict verification: only a configured gate counts (O.11). */
+  gate_only?: true;
+};
+
+/** The rungs of the evidence ladder this derivation can establish. */
+export type RequestEvidence = {
+  /** Every required check ran successfully against the current workspace. */
+  ran: "pass" | "fail" | "stale" | "missing" | "not_applicable";
+  /** Every required human criterion was accepted by the user. */
+  human: "accepted" | "pending" | "not_required";
+  /**
+   * Every passing check meant to test the change failed once this request's
+   * changes were undone (feat-counter-check). `missing`: every check is a guard
+   * that held, so nothing shows the work changed anything (S.7).
+   */
+  discriminating: "pass" | "vacuous" | "unavailable" | "not_run" | "missing" | "not_applicable";
+  /** Blind checks the model never touched passed on the final result (feat-blind-checks). */
+  independent: "pass" | "fail" | "exposed" | "unavailable" | "not_run" | "not_applicable";
+};
+
+export type RequestStatus = "not_applicable" | "unchecked" | "checked" | "needs_work" | "awaiting_human" | "verified";
+
 export type RequestState = {
   request: RequestSource; inputs: RequestSource[];
-  status: "verified" | "awaiting_human" | "needs_work" | "blocked" | "unverified" | "not_applicable";
+  /**
+   * Without a contract: not_applicable (nothing changed), unchecked, or
+   * checked. With one: needs_work, awaiting_human, verified, or
+   * not_applicable for a changes-scoped contract over an unchanged workspace.
+   */
+  status: RequestStatus;
+  criteria: RequestCriterion[]; evidence: RequestEvidence; unmet: string[];
   execution?: ExecutionOutcome; acceptance?: AcceptanceState;
   commands: RequestCommand[]; artifacts: RequestArtifact[]; work: WorkItem[];
+  /** What the model said blocks it. Shown to the user; never a verdict (D11). */
   reported_blockers: { source: RequestSource; reason: string }[];
   progress: RequestProgress;
   changed: boolean; used_tools: boolean; reviewed: boolean;
   final?: { source: RequestSource; text: string; has_tools: boolean };
 };
 
-/** New steering events refer to their original user event. Legacy users remain separate requests. */
+export type LedgerOptions = {
+  /** The CLI's strict verification: only a configured gate command counts as the fresh check. */
+  strict?: boolean;
+  /** The session declares blind checks, so their absence means "not run" rather than "not applicable". */
+  blind?: boolean;
+};
+
+/** New steering events refer to their original user event. A user event without that link opens a request. */
 export function currentRequestRecords(parts: readonly RequestPart[]): RequestRecord[] {
   const records = parts.flatMap(part => part.events.map(event => ({ node: part.node, event })));
   const last = records.findLastIndex(({ event }) => event.t === "user");
@@ -38,7 +104,18 @@ export function currentRequestRecords(parts: readonly RequestPart[]): RequestRec
   return records.slice(start);
 }
 
-export function deriveRequestState(parts: readonly RequestPart[]): RequestState | undefined {
+/**
+ * The current request's events in one flat stream: the one slicer every
+ * per-request notice uses, so steering never restarts a request's budget,
+ * notices or failure counts. Empty when the stream holds no user event.
+ */
+export function currentRequestEvents(events: readonly LogEvent[]): LogEvent[] {
+  return currentRequestRecords([{ node: 0, events }]).map(record => record.event);
+}
+
+const FRESH_CHECK = "a successful check after the last change";
+
+export function deriveRequestState(parts: readonly RequestPart[], options: LedgerOptions = {}): RequestState | undefined {
   const records = currentRequestRecords(parts);
   const first = records[0];
   if (!first) return undefined;
@@ -46,7 +123,7 @@ export function deriveRequestState(parts: readonly RequestPart[]): RequestState
   const source = ({ node, event }: RequestRecord): RequestSource => ({ node, event: event.id });
   const request = source(first);
   const acceptance = deriveAcceptance(undefined, events.filter(event => event.t !== "acceptance_contract" || event.request === request.event));
-  const commands: RequestCommand[] = [], artifacts: RequestArtifact[] = [];
+  const commands: (RequestCommand & { index: number })[] = [], artifacts: RequestArtifact[] = [];
   const lastCommands = new Map<string, string>();
   for (const event of events) if (isCommandResult(event)) lastCommands.set(event.effect.cmd, event.id);
   let work: WorkItem[] = [];
@@ -56,7 +133,7 @@ export function deriveRequestState(parts: readonly RequestPart[]): RequestState
     work = deriveWorkItems(work, part.events);
     for (let index = 0; index < part.events.length; index++) {
       const event = part.events[index]!;
-      // Legacy completed claims supersede a same-named blocker only when the
+      // Untyped completed claims supersede a same-named blocker only when the
       // original same-segment evidence resolves, just as in deriveHandoff.
       if (event.t === "claim" && event.work_id === undefined && ids.has(event.id) &&
           resolveEvidence(part.events.slice(0, index), event.evidence).ok) completed.add(event.what);
@@ -64,8 +141,8 @@ export function deriveRequestState(parts: readonly RequestPart[]): RequestState
   }
   work = work.filter(item => ids.has(item.opened_at) || ids.has(item.updated_at));
   const reported_blockers: RequestState["reported_blockers"] = [];
-  let execution: ExecutionOutcome | undefined, final: RequestState["final"], changed = false;
-  for (const record of records) {
+  let execution: ExecutionOutcome | undefined, final: RequestState["final"], changed = false, lastChange = -1;
+  records.forEach((record, index) => {
     const event = record.event, ref = source(record);
     if (event.t === "user") { execution = undefined; final = undefined; }
     else if (event.t === "assistant") {
@@ -78,12 +155,13 @@ export function deriveRequestState(parts: readonly RequestPart[]): RequestState
     if (event.t === "blocked" && (event.work_id ? work.some(item => item.id === event.work_id && item.status === "blocked") : !completed.has(event.what))) {
       reported_blockers.push({ source: ref, reason: event.reason });
     }
+    if (workspaceChanged(event)) { changed = true; lastChange = index; }
     if (isCommandResult(event)) {
       const effect = event.effect;
       const evidence = { command: effect.cmd, exit: effect.exit, event_id: event.id, at: event.at,
         ...(effect.workspace_sha256 === undefined ? {} : { workspace_sha256: effect.workspace_sha256 }),
         ...(effect.workspace_scope === undefined ? {} : { workspace_scope: effect.workspace_scope }) };
-      commands.push({ source: ref, command: effect.cmd, exit: effect.exit,
+      commands.push({ index, source: ref, command: effect.cmd, exit: effect.exit,
         status: !event.ok || effect.exit !== 0 ? "fail" : effect.workspace_observed === false || evidenceStale(events, evidence) ? "stale"
           : lastCommands.get(effect.cmd) !== event.id ? "superseded" : "pass",
         ...(effect.gate === undefined ? {} : { gate: effect.gate }),
@@ -95,20 +173,101 @@ export function deriveRequestState(parts: readonly RequestPart[]): RequestState
     } else if (event.t === "tool_result" && (event.effect?.kind === "read" || event.effect?.kind === "edit")) {
       const effect = event.effect;
       artifacts.push({ source: ref, path: effect.path, sha256: effect.kind === "read" ? effect.sha256 : effect.sha256_after, kind: effect.kind });
-      if (effect.kind === "edit" && effect.sha256_before !== effect.sha256_after) changed = true;
     } else if (event.t === "checkpoint" && event.phase === "applied") {
       for (const path of changedPaths(event.changes)) artifacts.push({ source: ref, path, sha256: event.changes[path]!.after?.sha256 ?? null, kind: "checkpoint" });
-      changed ||= changedPaths(event.changes).length > 0;
-    } else if (event.t === "workspace_observation") changed ||= event.changed;
-    else if (event.t === "snapshot") changed ||= Object.keys(event.added).length + Object.keys(event.changed).length + event.removed.length > 0;
+    }
+  });
+
+  const ledger = acceptance ? contractLedger(acceptance) : freshCheckLedger(commands, changed, lastChange, options);
+  const { criteria, status } = ledger;
+  for (const event of events) if (event.t === "counter_check" && event.request === request.event) {
+    const criterion = criteria.find(item => item.id === event.criterion && item.kind === "command");
+    if (criterion) criterion.counter = counterVerdict(event);
+  }
+  for (const criterion of criteria) if (criterion.kind === "command" && criterion.command && criterion.status === "fail") {
+    const runs = commands.filter(command => command.command === criterion.command);
+    const last = runs.at(-1);
+    let streak = 0;
+    for (let i = runs.length - 1; i >= 0; i--) {
+      const run = runs[i]!;
+      if (run.status !== "fail" || run.exit !== last!.exit || run.workspace_sha256 === undefined || run.workspace_sha256 !== last!.workspace_sha256) break;
+      streak++;
+    }
+    if (streak >= 2) criterion.repeated_failures = streak;
   }
+  const blind = new Map<string, Extract<LogEvent, { t: "blind_check" }>>();
+  for (const event of events) if (event.t === "blind_check" && event.request === request.event) blind.set(event.check, event);
+  const blindRuns = [...blind.values()];
+  const independent: RequestEvidence["independent"] = blindRuns.length === 0 ? (options.blind ? "not_run" : "not_applicable")
+    : blindRuns.some(run => "exit" in run && run.exit !== 0) ? "fail" : blindRuns.some(run => "reason" in run) ? "unavailable"
+    : blindRuns.some(run => run.exposed) ? "exposed" : "pass";
+  const evidence: RequestEvidence = { ...ledger.evidence, independent, discriminating: testsTheChange(criteria) };
+  const unmet = criteria.filter(item => item.status !== "pass" && item.status !== "accepted").map(item => `${item.description}: ${item.status}`);
   return { request, inputs: records.filter(record => record.event.t === "user").map(source),
-    // Work notes can describe a later phase the user explicitly asked to defer.
-    // Only the declared request contract defines what must finish in this request.
-    status: reported_blockers.length ? "blocked" : acceptance?.status ?? "unverified",
+    status, criteria, evidence, unmet,
     ...(execution ? { execution } : {}), ...(acceptance ? { acceptance } : {}),
-    commands, artifacts, work, reported_blockers, progress: deriveRequestProgress(records), changed,
+    commands: commands.map(({ index: _index, ...command }) => command), artifacts, work, reported_blockers,
+    progress: deriveRequestProgress(records), changed,
     used_tools: events.some(event => event.t === "tool_result"),
     reviewed: events.some(event => event.t === "guidance" && event.reason === "completion_review"),
     ...(final ? { final } : {}) };
 }
+
+/**
+ * The discriminating rung (S.1, S.7), decided by the checks meant to test the
+ * change: each must fail once the request's changes are undone. A guard that
+ * held is what a guard should do, so it neither fails the rung nor holds it
+ * back. A guard that did not hold does test the change -- the observation
+ * outranks the declaration (D11) -- so it counts for the rung. With only
+ * guards, all held, nothing shows the work changed anything: missing. A
+ * passing fresh check is a check like any declared command and must test the
+ * change too.
+ */
+function testsTheChange(criteria: readonly RequestCriterion[]): RequestEvidence["discriminating"] {
+  const tests = criteria.filter(item => item.kind === "command" && !item.guard || item.kind === "fresh_check" && item.status === "pass");
+  const guards = criteria.filter(item => item.kind === "command" && item.guard);
+  if (tests.length === 0 && guards.length === 0) return "not_applicable";
+  if (tests.some(item => item.counter === "vacuous")) return "vacuous";
+  if (tests.some(item => item.counter === "unavailable")) return "unavailable";
+  if (tests.some(item => item.counter !== "discriminating")) return "not_run";
+  if (tests.length > 0 || guards.some(item => item.counter === "not_held")) return "pass";
+  if (guards.some(item => item.counter === "unavailable")) return "unavailable";
+  return guards.every(item => item.counter === "held") ? "missing" : "not_run";
+}
+
+/** A declared contract defines what this request must finish (O.11); nothing is inferred beyond it. */
+type LedgerCore = Pick<RequestState, "criteria" | "status"> & { evidence: Omit<RequestEvidence, "discriminating" | "independent"> };
+
+function contractLedger(acceptance: AcceptanceState): LedgerCore {
+  const criteria: RequestCriterion[] = acceptance.criteria.map(item => ({ id: item.id, kind: item.kind, description: item.description,
+    status: item.status, ...(item.kind === "command" ? { command: item.command, ...(item.guard ? { guard: true as const } : {}) } : {}),
+    ...(item.evidence ? { evidence: item.evidence.event_id } : item.accepted_event ? { evidence: item.accepted_event } : {}) }));
+  const checks = criteria.filter(item => item.kind === "command"), humans = criteria.filter(item => item.kind === "human");
+  const targetsReady = (acceptance.targets ?? []).every(target => target.status === "ready");
+  const ran: RequestEvidence["ran"] = checks.length === 0 ? "not_applicable"
+    : checks.every(item => item.status === "pass") && targetsReady ? "pass"
+    : checks.some(item => item.status === "fail") ? "fail" : checks.some(item => item.status === "stale") ? "stale" : "missing";
+  return { criteria, status: acceptance.status,
+    evidence: { ran, human: humans.length === 0 ? "not_required" : humans.every(item => item.status === "accepted") ? "accepted" : "pending" } };
+}
+
+/**
+ * Without a contract, a request that changed the workspace still owes one
+ * thing: a successful check against the changed workspace. That is all an
+ * exit code can say -- not that the request's words were met -- so the status
+ * is "checked", never "verified".
+ */
+function freshCheckLedger(commands: readonly (RequestCommand & { index: number })[], changed: boolean, lastChange: number,
+  options: LedgerOptions): LedgerCore {
+  const none = { human: "not_required" as const };
+  if (!changed) return { criteria: [], status: "not_applicable", evidence: { ran: "not_applicable", ...none } };
+  const after = commands.filter(command => command.index > lastChange && (!options.strict || command.gate !== undefined));
+  const pass = after.find(command => command.status === "pass");
+  const status: RequestCriterion["status"] = pass ? "pass" : after.some(command => command.status === "fail") ? "fail"
+    : after.some(command => command.status === "stale") ? "stale" : "not_run";
+  const criterion: RequestCriterion = { id: "fresh-check", kind: "fresh_check",
+    description: options.strict ? `${FRESH_CHECK} (a configured gate)` : FRESH_CHECK, status, ...(options.strict ? { gate_only: true as const } : {}),
+    ...(pass ? { command: pass.command, evidence: pass.source.event } : {}) };
+  return { criteria: [criterion], status: pass ? "checked" : "unchecked",
+    evidence: { ran: status === "pass" ? "pass" : status === "not_run" ? "missing" : status, ...none } };
+}

package/src/core/response-recovery.ts

@@ -1,5 +1,6 @@
 /** N.12: a returned response is durable evidence, not necessarily a completed action. */
 import type { GuidanceEvent, LogEvent } from "./events.ts";
+import { currentRequestEvents } from "./request-state.ts";
 
 // One appended attempt is an operational assumption, not a measured optimum.
 // It shares the existing request ceiling and never replays a tool automatically.
@@ -34,7 +35,7 @@ export function knownUnexecutedTool(events: readonly LogEvent[], callId: string)
 export function outputRecoveryNotice(events: readonly LogEvent[], limit: number, remainingRequests: number):
   Pick<GuidanceEvent, "reason" | "sources" | "text"> | null {
   validateOutputRecoveryLimit(limit);
-  const current = events.slice(events.findLastIndex(event => event.t === "user") + 1);
+  const current = currentRequestEvents(events).slice(1);
   const assistant = current.findLast(event => event.t === "assistant");
   const notices = current.filter(event => event.t === "guidance" && event.reason === "output_recovery");
   if (assistant?.t !== "assistant" || !isOutputLimit(assistant.stop_reason) || notices.length >= limit || remainingRequests < 1 ||

package/src/core/session-entry.ts

@@ -43,13 +43,18 @@ export interface SavedModel {
   provider?: string;
 }
 
-/** Legacy logs have only an ID; accepting one requires a unique catalog match. */
+/**
+ * S.3: every cursor of this session format names its provider, so a resume
+ * restores exactly that provider/model and never guesses one from a model ID
+ * that several providers serve.
+ */
 export function restoreSessionModel<T extends { id: string; provider: string }>(
   saved: SavedModel,
   catalog: readonly T[],
 ): T {
-  const matches = catalog.filter((m) => m.id === saved.model && (saved.provider === undefined || m.provider === saved.provider));
-  const label = saved.provider === undefined ? saved.model : `${saved.provider}/${saved.model}`;
+  if (saved.provider === undefined) throw new Error(`saved model ${saved.model} names no provider, which this session format always records. Start a new session`);
+  const matches = catalog.filter((m) => m.id === saved.model && m.provider === saved.provider);
+  const label = `${saved.provider}/${saved.model}`;
   if (matches.length === 0) throw new Error(`saved model ${label} is unavailable. Restore its catalog entry, or start a new session`);
   if (matches.length !== 1) throw new Error(`saved model ${label} is ambiguous across providers. Restore an unambiguous catalog before resuming`);
   return matches[0]!;

package/src/core/session-exit.ts

@@ -2,17 +2,33 @@
 import type { LogEvent } from "./events.ts";
 import { pendingToolCalls } from "./execution.ts";
 import { modelOutcome } from "./outcome.ts";
+import { currentRequestEvents } from "./request-state.ts";
 
 export const DEFAULT_FULLSCREEN_EXIT_OUTPUT = "resume-hint";
 
+/** The identifiers `--session-id` accepts; anything else is printed as a path. */
+const PLAIN_ID = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+
+/**
+ * The command a person retypes to come back. Claude Code prints
+ * `claude --resume <id>` and Codex `codex resume <id>`: an id, not a path.
+ * `--resume <id>` resolves only inside the sessions directory of the shell's
+ * cwd, so a session stored anywhere else (`--session-dir`, `--state-dir`,
+ * `-w` elsewhere) keeps the explicit path rather than a command that cannot
+ * find it.
+ */
+export function resumeCommand(session: { id: string; directory: string; path: string }, cwdSessions: string): string {
+  return session.directory === cwdSessions && PLAIN_ID.test(session.id)
+    ? `xeno --resume ${session.id}` : `xeno --session ${JSON.stringify(session.path)}`;
+}
+
 /** Terminal controls and arbitrarily large reason text do not own the shell surface. */
 export function exitLine(text: string, limit = 180): string {
   return text.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim().slice(0, limit);
 }
 
 export function sessionExitStatus(events: readonly LogEvent[]): string {
-  const start = events.findLastIndex(event => event.t === "user");
-  const current = events.slice(Math.max(0, start));
+  const current = currentRequestEvents(events);
   const outcome = current.findLast(event => event.t === "outcome" || event.t === "user_bash");
   if (outcome?.t === "outcome") return exitLine(`${outcome.outcome.status} · ${outcome.outcome.reason} · ${outcome.reason}`);
   if (outcome?.t === "user_bash") return `${outcome.outcome.status} · ${outcome.outcome.reason} · command exit ${outcome.exit}`;
@@ -22,5 +38,5 @@ export function sessionExitStatus(events: readonly LogEvent[]): string {
     const result = modelOutcome(assistant.stop_reason ?? null);
     return result.reason === "model_end" ? "model finished · verification remains in session evidence" : `${result.status} · ${result.reason}`;
   }
-  return start < 0 ? "session saved" : "unfinished · inspect recorded receipts before continuing";
+  return current.length === 0 ? "session saved" : "unfinished · inspect recorded receipts before continuing";
 }