@visual-z/xeno 0.7.2 → 0.8.1

package/src/core/session-format.ts

@@ -0,0 +1,169 @@
+/**
+ * S.3: a session directory holds exactly one on-disk format, and this build
+ * reads only that one. A directory written in any other format is refused
+ * with its location -- never reinterpreted under today's defaults. Reading old
+ * logs leniently is how a resumed session once ran without its stall watchdog:
+ * new sessions wrote stallLimit 12 while the resume path restored an absent
+ * field as 0.
+ *
+ * The format covers the metadata journal (whose first record declares it),
+ * the frozen session context parsed below, events and handoffs. Changing any
+ * of them incompatibly means bumping SESSION_FORMAT, not adding a fallback.
+ */
+import { parseAcceptanceContract, type AcceptanceContract } from "./acceptance.ts";
+import type { BoundaryConfig } from "./boundary.ts";
+import { isContextPolicy, type ContextPolicy } from "./context-policy.ts";
+import type { FrozenPrefix } from "./project.ts";
+import { validateOutputRecoveryLimit } from "./response-recovery.ts";
+import { schedulingWindow } from "./scheduling.ts";
+import type { Skill } from "./skills.ts";
+import { isBlindChecks, type BlindChecks } from "./blind-checks.ts";
+import { emptyStallState, stallDecision } from "./stall.ts";
+
+export const SESSION_FORMAT = 1;
+
+export type FoundFormat = number | "undeclared";
+
+export function sessionFormatMessage(dir: string, found: FoundFormat): string {
+  const written = found === "undeclared" ? "a layout from before session formats were declared" : `session format ${found}`;
+  return `${dir} holds ${written}; this xeno reads session format ${SESSION_FORMAT} only. ` +
+    "The log is intact and was not modified. Start a new session with --fresh.";
+}
+
+/** Raised before any read or write of a directory in another format. */
+export class SessionFormatError extends Error {
+  readonly dir: string;
+  readonly found: FoundFormat;
+  constructor(dir: string, found: FoundFormat) {
+    super(sessionFormatMessage(dir, found));
+    this.name = "SessionFormatError";
+    this.dir = dir;
+    this.found = found;
+  }
+}
+
+/**
+ * What a session freezes at start and restores on resume. Required fields
+ * are written by every session of this format, so resume restores them as
+ * recorded; there is no default to drift from what was written.
+ */
+export interface SessionContext {
+  frozen: FrozenPrefix;
+  gates: Record<string, string>;
+  shellCheckpoints: boolean;
+  skills: readonly Skill[];
+  strictVerification: boolean;
+  workingSet: boolean;
+  workNamespace: string;
+  maxParallelTools: number;
+  contextPolicy: ContextPolicy;
+  stallLimit: number;
+  outputRecoveryLimit: number;
+  acceptanceContract?: AcceptanceContract;
+  workflowMode?: "build" | "plan";
+  agentProfile?: { name: string; workflowExplicit: boolean };
+  workflowToolProfile?: "foundation";
+  boundary?: Partial<BoundaryConfig>;
+  guidance?: boolean;
+  blindChecks?: BlindChecks;
+}
+
+const REQUIRED = ["frozen", "gates", "shellCheckpoints", "skills", "strictVerification", "workingSet",
+  "workNamespace", "maxParallelTools", "contextPolicy", "stallLimit", "outputRecoveryLimit"] as const;
+const OPTIONAL = ["acceptanceContract", "workflowMode", "agentProfile", "workflowToolProfile", "boundary", "guidance", "blindChecks"] as const;
+const BOUNDARY_KEYS = ["triggerTokens", "hardTokens", "minNodeWorkTokens"] as const;
+
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every(item => typeof item === "string");
+
+function invalid(field: string, why: string): never {
+  throw new Error(`invalid session context: ${field} ${why}`);
+}
+
+function skill(value: unknown, index: number): Skill {
+  const field = `skills[${index}]`;
+  if (!record(value)) invalid(field, "must be an object");
+  const text = (key: string): string => { const v = value[key]; if (typeof v !== "string") invalid(`${field}.${key}`, "must be a string"); return v; };
+  const disable = value["disableModelInvocation"];
+  if (typeof disable !== "boolean") invalid(`${field}.disableModelInvocation`, "must be a boolean");
+  const out: { -readonly [K in keyof Skill]: Skill[K] } = { name: text("name"), description: text("description"), filePath: text("filePath"), body: text("body"), disableModelInvocation: disable };
+  const invocable = value["userInvocable"];
+  if (invocable !== undefined) { if (typeof invocable !== "boolean") invalid(`${field}.userInvocable`, "must be a boolean"); out.userInvocable = invocable; }
+  if (value["context"] !== undefined) { if (value["context"] !== "fork") invalid(`${field}.context`, "must be fork"); out.context = "fork"; }
+  for (const key of ["allowedTools", "disallowedTools"] as const) {
+    const names = value[key];
+    if (names !== undefined) { if (!strings(names)) invalid(`${field}.${key}`, "must be strings"); out[key] = [...names]; }
+  }
+  if (value["sourceText"] !== undefined) out.sourceText = text("sourceText");
+  return out;
+}
+
+/** Strict: every required field present and typed, no field this format does not define. */
+export function parseSessionContext(value: unknown): SessionContext {
+  if (!record(value)) invalid("context", "must be an object");
+  for (const key of Object.keys(value)) {
+    if (!(REQUIRED as readonly string[]).includes(key) && !(OPTIONAL as readonly string[]).includes(key)) invalid(key, "is not part of this session format");
+  }
+  for (const key of REQUIRED) if (value[key] === undefined) invalid(key, "is missing");
+
+  const frozen = value["frozen"];
+  const system = record(frozen) ? frozen["system"] : undefined, tools = record(frozen) ? frozen["tools"] : undefined;
+  if (typeof system !== "string" || !Array.isArray(tools)) invalid("frozen", "must hold a system string and a tools array");
+  const gates = value["gates"], gateMap: Record<string, string> = {};
+  if (!record(gates)) invalid("gates", "must map names to commands");
+  for (const [name, command] of Object.entries(gates)) { if (typeof command !== "string") invalid(`gates.${name}`, "must be a command string"); gateMap[name] = command; }
+  const flag = (key: "shellCheckpoints" | "strictVerification" | "workingSet"): boolean => { const v = value[key]; if (typeof v !== "boolean") invalid(key, "must be a boolean"); return v; };
+  if (!Array.isArray(value["skills"])) invalid("skills", "must be an array");
+  const skills = value["skills"].map(skill);
+  const namespace = value["workNamespace"];
+  if (typeof namespace !== "string" || namespace.length === 0) invalid("workNamespace", "must be a non-empty string");
+  const limit = (key: "maxParallelTools" | "stallLimit" | "outputRecoveryLimit", check: (n: number) => void): number => {
+    const n = value[key];
+    if (typeof n !== "number") invalid(key, "must be a number");
+    try { check(n); } catch (error) { invalid(key, error instanceof Error ? `is out of range: ${error.message}` : "is out of range"); }
+    return n;
+  };
+  const maxParallelTools = limit("maxParallelTools", n => schedulingWindow([], 0, n));
+  const stallLimit = limit("stallLimit", n => stallDecision(emptyStallState(), n));
+  const outputRecoveryLimit = limit("outputRecoveryLimit", validateOutputRecoveryLimit);
+  const policy = value["contextPolicy"];
+  if (!isContextPolicy(policy)) invalid("contextPolicy", "is not a known policy");
+
+  const context: SessionContext = {
+    frozen: { system, tools }, gates: gateMap, shellCheckpoints: flag("shellCheckpoints"),
+    skills, strictVerification: flag("strictVerification"), workingSet: flag("workingSet"),
+    workNamespace: namespace, maxParallelTools, contextPolicy: policy, stallLimit, outputRecoveryLimit,
+  };
+  if (value["acceptanceContract"] !== undefined) {
+    try { context.acceptanceContract = parseAcceptanceContract(value["acceptanceContract"]); }
+    catch (error) { invalid("acceptanceContract", error instanceof Error ? `is invalid: ${error.message}` : "is invalid"); }
+  }
+  const mode = value["workflowMode"];
+  if (mode !== undefined) { if (mode !== "build" && mode !== "plan") invalid("workflowMode", "must be build or plan"); context.workflowMode = mode; }
+  const profile = value["agentProfile"];
+  if (profile !== undefined) {
+    const name = record(profile) ? profile["name"] : undefined, explicit = record(profile) ? profile["workflowExplicit"] : undefined;
+    if (!record(profile) || Object.keys(profile).length !== 2 || typeof name !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(name) || typeof explicit !== "boolean")
+      invalid("agentProfile", "must name a profile and whether its workflow was explicit");
+    context.agentProfile = { name, workflowExplicit: explicit };
+  }
+  if (value["workflowToolProfile"] !== undefined) {
+    if (value["workflowToolProfile"] !== "foundation") invalid("workflowToolProfile", "must be foundation");
+    context.workflowToolProfile = "foundation";
+  }
+  const boundary = value["boundary"];
+  if (boundary !== undefined) {
+    if (!record(boundary)) invalid("boundary", "must be an object");
+    const thresholds: Partial<BoundaryConfig> = {};
+    for (const [key, n] of Object.entries(boundary)) {
+      if (!(BOUNDARY_KEYS as readonly string[]).includes(key)) invalid(`boundary.${key}`, "is not a boundary threshold");
+      if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 0) invalid(`boundary.${key}`, "must be a non-negative integer");
+      thresholds[key as keyof BoundaryConfig] = n;
+    }
+    context.boundary = thresholds;
+  }
+  const guidance = value["guidance"], blind = value["blindChecks"];
+  if (guidance !== undefined) { if (typeof guidance !== "boolean") invalid("guidance", "must be a boolean"); context.guidance = guidance; }
+  if (blind !== undefined) { if (!isBlindChecks(blind)) invalid("blindChecks", "is not a frozen blind check set"); context.blindChecks = blind; }
+  return context;
+}

package/src/core/settings.ts

@@ -7,7 +7,6 @@ export interface Settings {
   /** Presentation only: no animation is allowed to advance a log or block input. */
   readonly animations?: boolean;
   readonly thinking?: string;
-  readonly statusBar?: boolean;
   /** Look for a newer published xeno once a day and say so (docs/tasks/feat-update-check.md). Default on. */
   readonly updateCheck?: boolean;
   readonly hideThinkingBlock?: boolean;
@@ -25,11 +24,6 @@ export interface Settings {
   readonly fullscreenExitOutput?: "transcript" | "resume-hint";
   readonly fullscreenScrollbar?: "auto" | "always" | "hidden";
   readonly fullscreenCopyOnSelect?: boolean;
-  readonly fullscreenWheelScrollLines?: "auto" | number;
-  readonly editorPaddingX?: number;
-  readonly outputPad?: 0 | 1;
-  readonly autocompleteMaxVisible?: number;
-  readonly showHardwareCursor?: boolean;
   readonly quietStartup?: boolean;
   readonly doubleEscapeAction?: "tree" | "fork" | "none";
   readonly treeFilterMode?: "default" | "no-tools" | "user-only" | "labeled-only" | "all";
@@ -41,16 +35,15 @@ export interface Settings {
   readonly packages?: readonly PackageDeclaration[];
   readonly enableSkillCommands?: boolean;
   readonly defaultProjectTrust?: "ask" | "always" | "never";
-  readonly terminal?: { readonly clearOnShrink?: boolean; readonly showTerminalProgress?: boolean; readonly showImages?: boolean; readonly imageWidthCells?: number;
+  readonly terminal?: { readonly showImages?: boolean; readonly imageWidthCells?: number;
     /** How pictures are drawn; `auto` names them instead when the terminal can only draw block characters. */
     readonly imageProtocol?: "auto" | "kitty" | "sixel" | "blocks" };
   readonly images?: { readonly autoResize?: boolean; readonly blockImages?: boolean };
   readonly markdown?: { readonly mermaid?: "off" | "final" | "streaming" };
 }
-export const SETTINGS_KEYS = ["theme", "animations", "thinking", "statusBar", "updateCheck", "hideThinkingBlock", "showCacheMissNotices", "defaultProvider", "defaultModel", "defaultThinking",
+export const SETTINGS_KEYS = ["theme", "animations", "thinking", "updateCheck", "hideThinkingBlock", "showCacheMissNotices", "defaultProvider", "defaultModel", "defaultThinking",
   "modelThinkingLevels", "scopedModels", "recentModels", "steeringMode", "followUpMode", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar",
-  "fullscreenCopyOnSelect", "fullscreenWheelScrollLines", "editorPaddingX", "outputPad", "autocompleteMaxVisible",
-  "showHardwareCursor", "quietStartup", "doubleEscapeAction", "treeFilterMode", "externalEditor", "terminal", "images", "markdown",
+  "fullscreenCopyOnSelect", "quietStartup", "doubleEscapeAction", "treeFilterMode", "externalEditor", "terminal", "images", "markdown",
   "skills", "prompts", "themes", "extensions", "packages", "enableSkillCommands", "defaultProjectTrust"] as const;
 export type SettingsKey = (typeof SETTINGS_KEYS)[number];
 export interface SettingsLayers { readonly builtin: Settings; readonly user?: Settings; readonly project?: Settings; readonly cli?: Settings }
@@ -60,23 +53,17 @@ type Rule = { readonly kind: "boolean" | "string" | "strings" } | { readonly kin
 const levels: Rule = { kind: "enum", values: THINKING_LEVELS };
 const delivery: Rule = { kind: "enum", values: ["all", "one-at-a-time"] };
 const rules: Readonly<Record<string, Rule>> = {
-  theme: { kind: "string" }, animations: { kind: "boolean" }, thinking: levels, statusBar: { kind: "boolean" }, updateCheck: { kind: "boolean" },
+  theme: { kind: "string" }, animations: { kind: "boolean" }, thinking: levels, updateCheck: { kind: "boolean" },
   hideThinkingBlock: { kind: "boolean" }, showCacheMissNotices: { kind: "boolean" },
   defaultProvider: { kind: "string" }, defaultModel: { kind: "string" }, defaultThinking: levels,
   scopedModels: { kind: "strings" }, recentModels: { kind: "strings" }, steeringMode: delivery, followUpMode: delivery,
   tuiMode: { kind: "enum", values: ["auto", "regular", "fullscreen"] },
   fullscreenExitOutput: { kind: "enum", values: ["transcript", "resume-hint"] },
   fullscreenScrollbar: { kind: "enum", values: ["auto", "always", "hidden"] },
-  fullscreenCopyOnSelect: { kind: "boolean" },
-  // Pi's documented display bounds; these are not context/segment thresholds.
-  fullscreenWheelScrollLines: { kind: "integer", min: 1, max: 100, auto: true },
-  editorPaddingX: { kind: "integer", min: 0, max: 3 }, outputPad: { kind: "integer", min: 0, max: 1 },
-  autocompleteMaxVisible: { kind: "integer", min: 3, max: 20 },
-  showHardwareCursor: { kind: "boolean" }, quietStartup: { kind: "boolean" },
+  fullscreenCopyOnSelect: { kind: "boolean" }, quietStartup: { kind: "boolean" },
   doubleEscapeAction: { kind: "enum", values: ["tree", "fork", "none"] },
   treeFilterMode: { kind: "enum", values: ["default", "no-tools", "user-only", "labeled-only", "all"] },
-  externalEditor: { kind: "string" }, "terminal.clearOnShrink": { kind: "boolean" },
-  "terminal.showTerminalProgress": { kind: "boolean" },
+  externalEditor: { kind: "string" },
   "terminal.showImages": { kind: "boolean" }, "terminal.imageWidthCells": { kind: "integer", min: 1, max: 240 },
   "terminal.imageProtocol": { kind: "enum", values: ["auto", "kitty", "sixel", "blocks"] },
   "images.autoResize": { kind: "boolean" }, "images.blockImages": { kind: "boolean" },
@@ -102,16 +89,9 @@ export const DISPLAY_SETTINGS = [
   { id: "fullscreenExitOutput", label: "Fullscreen exit output", fallback: "resume-hint" },
   { id: "fullscreenScrollbar", label: "Fullscreen scrollbar", fallback: "hidden" },
   { id: "fullscreenCopyOnSelect", label: "Copy on select", fallback: "on" },
-  { id: "fullscreenWheelScrollLines", label: "Fullscreen wheel scroll lines", fallback: "auto" },
-  { id: "editorPaddingX", label: "Editor padding", fallback: "0" },
-  { id: "outputPad", label: "Output padding", fallback: "1" },
-  { id: "autocompleteMaxVisible", label: "Autocomplete rows", fallback: "5" },
-  { id: "showHardwareCursor", label: "Hardware cursor", fallback: "on" },
   { id: "quietStartup", label: "Quiet startup", fallback: "off" },
   { id: "doubleEscapeAction", label: "Double Escape", fallback: "tree" },
   { id: "treeFilterMode", label: "Tree filter", fallback: "default" },
-  { id: "terminal.clearOnShrink", label: "Clear on shrink", fallback: "off" },
-  { id: "terminal.showTerminalProgress", label: "Terminal progress", fallback: "on" },
 ] as const;
 /** Only fields with a real picker may be suggested without a value. Raw config keys remain writable explicitly. */
 export function interactiveSettingKeys(): string[] {
@@ -120,7 +100,7 @@ export function interactiveSettingKeys(): string[] {
     .filter(key => pickers.includes(key) || settingValues(key).length > 0);
 }
 
-export function defaultSettings(): Settings { return { theme: "dark", thinking: "high", statusBar: true }; }
+export function defaultSettings(): Settings { return { theme: "dark", thinking: "high" }; }
 export function mergeSettings(layers: SettingsLayers): Settings {
   const { defaultProjectTrust: _projectCannotGrantTrust, ...project } = layers.project ?? {};
   const all = [layers.builtin, layers.user ?? {}, project, layers.cli ?? {}];

package/src/core/stall.ts

@@ -4,6 +4,7 @@ import { pendingToolCalls } from "./execution.ts";
 import { exchangeProgressChecks } from "./evidence.ts";
 import { deriveProgress, type ProgressEvidence } from "./progress.ts";
 import { isProcessReceipt } from "./process-receipt.ts";
+import { canonicalValue } from "./continuation.ts";
 
 // A conservative hypothesis: enough room to change method after a mid-budget
 // notice, while bounding repeated paid requests. Not a task-quality classifier.
@@ -17,20 +18,42 @@ export interface StallState {
   failures: number;
   emptyWaits: number;
   warned: boolean;
+  /** The previous exchange's tool calls, canonical; empty after real user input. */
+  previous: string;
 }
 export function emptyStallState(): StallState {
-  return { evidence: [], pending: [], pendingNode: 0, consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false };
+  return { evidence: [], pending: [], pendingNode: 0, consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false, previous: "" };
 }
+
+/** Name and arguments of every call, order-independent: what the model asked for, not what came back. */
+function exchangeSignature(assistant: Extract<LogEvent, { t: "assistant" }>): string {
+  return assistant.blocks.flatMap(block => block.type === "tool_use" ? [`${block.name}:${canonicalValue(block.input)}`] : []).sort().join("\n");
+}
+
 export function finishStallExchange(state: StallState): StallState {
   const assistant = state.pending[0];
   if (assistant?.t !== "assistant" || pendingToolCalls(state.pending).length > 0) return state;
   if (!assistant.blocks.some((block) => block.type === "tool_use")) return { ...state, pending: [] };
-  const progress = deriveProgress(state.evidence, state.pending, state.pendingNode, exchangeProgressChecks(state.pending));
-  const results = state.pending.filter(event => event.t === "tool_result");
+  const checks = exchangeProgressChecks(state.pending);
+  const progress = deriveProgress(state.evidence, state.pending, state.pendingNode, checks);
+  const signature = exchangeSignature(assistant);
   const waits = new Set(assistant.blocks.flatMap(block => block.type === "tool_use" && block.name === "write_stdin" ? [block.call_id] : []));
-  return { ...state, pending: [], evidence: progress.evidence,
-    consecutive: progress.progressed ? 0 : state.consecutive + 1,
-    unproductive: state.unproductive + (progress.progressed ? 0 : 1),
+  // S.6 item 2: with no request cap this ledger is the only backstop. Asking
+  // for exactly what the previous exchange asked for is a rerun on an
+  // unchanged premise, so output that differs only by timing (a failing test's
+  // "[123ms]") is not news. Reads and edits are content-addressed and keep
+  // their own rules; waiting on a running process is not a rerun. Only the
+  // immediately previous exchange: an edit, in any tool, between two runs is
+  // what makes the second one worth running (Gemini, Cline, OpenCode and Roo
+  // detect identical consecutive calls the same way).
+  const rerun = signature === state.previous
+    ? deriveProgress(state.evidence, state.pending.filter(event => event.t !== "tool_result" || waits.has(event.call_id) ||
+        (event.effect?.kind !== "command" && !isProcessReceipt(event.data))), state.pendingNode, checks).progressed
+    : progress.progressed;
+  const results = state.pending.filter(event => event.t === "tool_result");
+  return { ...state, pending: [], evidence: progress.evidence, previous: signature,
+    consecutive: rerun ? 0 : state.consecutive + 1,
+    unproductive: state.unproductive + (rerun ? 0 : 1),
     failures: state.failures + results.filter(result => !result.ok).length,
     emptyWaits: state.emptyWaits + results.filter(result => waits.has(result.call_id) && isProcessReceipt(result.data) &&
       result.data.running === true && result.data.cursor !== undefined && result.data.cursor.start === result.data.cursor.end).length };
@@ -42,7 +65,7 @@ export function advanceStall(state: StallState, entries: readonly { node: number
   for (const { node, event } of entries) {
     if (event.t === "assistant" || event.t === "user" || event.t === "cut" || (event.t === "guidance" && event.reason === "stall")) {
       result = finishStallExchange(result);
-      if (event.t === "user") result = { ...result, pending: [], consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false };
+      if (event.t === "user") result = { ...result, pending: [], consecutive: 0, unproductive: 0, failures: 0, emptyWaits: 0, warned: false, previous: "" };
       if (event.t === "assistant") result = { ...result, pending: [event], pendingNode: node };
       if (event.t === "guidance") result = { ...result, warned: true };
     } else if (result.pending.length > 0) result = { ...result, pending: [...result.pending, event] };

package/src/core/stop-report.ts

@@ -2,10 +2,11 @@
 import type { LogEvent } from "./events.ts";
 import { isProcessReceipt, latestProcessReceipt } from "./process-receipt.ts";
 import { exitLine } from "./session-exit.ts";
+import { currentRequestEvents } from "./request-state.ts";
 
 export function stopReport(events: readonly LogEvent[], requests: number, limit: number, cause: string): string {
-  const start = events.findLastIndex(event => event.t === "user" && event.request === undefined);
-  const current = events.slice(Math.max(0, start));
+  const scoped = currentRequestEvents(events);
+  const current = scoped.length > 0 ? scoped : events;
   const results = current.filter(event => event.t === "tool_result");
   const failures = results.filter(event => !event.ok);
   const exits = results.filter(event => event.effect?.kind === "command" && event.effect.exit === 0).length;
@@ -16,7 +17,7 @@ export function stopReport(events: readonly LogEvent[], requests: number, limit:
   }
   const running = [...ids].filter(id => latestProcessReceipt([{ node: 0, events: current }], id)?.receipt.running === true);
   return [
-    `Stopped: ${exitLine(cause)} (${requests}/${limit} model requests).`,
+    `Stopped: ${exitLine(cause)} (${limit === Infinity ? requests : `${requests}/${limit}`} model requests).`,
     `Recorded evidence: ${results.length} tool receipts; ${exits} successful command exits; ${failures.length} failed tool receipts. Task completion is not verified by this stop.`,
     ...(failures.length ? [`Inspect failed receipts: ${failures.slice(-3).map(event => exitLine(event.id, 80)).join(", ")}.`] : []),
     ...(running.length ? [`Last observed running: ${running.slice(0, 3).join(", ")}${running.length > 3 ? ` (+${running.length - 3})` : ""}; inspect the process receipt before replaying a command.`] : []),

package/src/core/transcript.ts

@@ -1,5 +1,6 @@
 /** Human history is a separate pure log projection from the model's bounded context (D1, D8). */
-import type { LogEvent } from "./events.ts";
+import type { CounterCheckEvent, LogEvent } from "./events.ts";
+import { counterVerdict } from "./acceptance.ts";
 import { assertNever } from "./exhaustive.ts";
 import type { ImageRef } from "./images.ts";
 
@@ -74,8 +75,14 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
       case "acceptance_contract": items.push({ ...identity, kind: "notice", text: `Acceptance contract · ${event.contract.id}` }); break;
       case "target_observation": items.push({ ...identity, kind: "notice", text: `Target ${event.observation.target} · ${event.observation.state} · ${event.observation.reason}` }); break;
       case "acceptance_decision": items.push({ ...identity, kind: "notice", text: `User accepted · ${event.criterion}` }); break;
+      case "counter_check": items.push({ ...identity, kind: "notice", text: counterNotice(event) }); break;
+      case "blind_check": items.push({ ...identity, kind: "notice", text: "reason" in event ? `Blind check ${event.check} could not run: ${event.reason}`
+        : `Blind check ${event.check} ${event.exit === 0 ? "passed" : `failed (exit ${event.exit})`}${event.exposed ? " · the model touched the blind checks, so this is not independent" : ""}` }); break;
+      case "goal": items.push({ ...identity, kind: "notice", text: event.action === "set"
+        ? `Goal set · ${event.accepted.length} accepted${event.rejected.length ? `, ${event.rejected.length} rejected` : ""} · ${event.objective}`
+        : event.reason === "met" ? "Goal met · every accepted criterion has current evidence" : "Goal cleared" }); break;
       case "checkpoint": case "workspace_observation":
-      case "guidance": case "snapshot": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "work_owner": case "work_dependencies": case "evidence_link":
+      case "guidance": case "claim": case "decision": case "pitfall": case "blocked": case "question": case "next_action": case "work_status": case "work_owner": case "work_dependencies": case "evidence_link":
         // These remain inspectable via /state and /export; they are not chat messages.
         break;
       default: assertNever(event, "projectTranscript");
@@ -83,3 +90,16 @@ export function projectTranscript(events: readonly LogEvent[], entryTypes: Reado
   }
   return items;
 }
+
+/** One counter-check in the words of the criterion's role (S.7); the verdict is derived, never stored. */
+function counterNotice(event: CounterCheckEvent): string {
+  const verdict = counterVerdict(event);
+  switch (verdict) {
+    case "unavailable": return `Check ${event.criterion} could not be counter-checked: ${"reason" in event ? event.reason : "no observation"}`;
+    case "vacuous": return `Check ${event.criterion} also passes without this request's changes; it does not test them`;
+    case "discriminating": return `Check ${event.criterion} fails without this request's changes; it tests them`;
+    case "held": return `Guard ${event.criterion} also held before this request's changes, as a guard should`;
+    case "not_held": return `Guard ${event.criterion} did not hold before this request's changes; it tests them rather than guarding`;
+    default: return assertNever(verdict, "counterNotice");
+  }
+}

package/src/runtime/blind-check.ts

@@ -0,0 +1,36 @@
+/**
+ * Running blind checks (feat-blind-checks): in a disposable clone of the
+ * final workspace, with the blind files copied in under `.xeno-blind/`. The
+ * files are verified against the digests frozen when the session began, so a
+ * directory edited since then is reported rather than silently run.
+ */
+import { cp, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { BlindChecks } from "../core/blind-checks.ts";
+import { observeCommand } from "../store/command.ts";
+import { cloneWorkspace } from "../store/workspace-clone.ts";
+import { blobAddress } from "../store/blobs.ts";
+
+export type BlindCheckResult = { id: string; command: string } & ({ exit: number } | { reason: string });
+
+export async function runBlindChecks(input: { root: string; blind: BlindChecks; timeoutMs: number; maxOutputBytes: number;
+  outputStore: string; signal?: AbortSignal }): Promise<BlindCheckResult[]> {
+  const checks = input.blind.manifest.checks.map(check => ({ id: check.id, command: check.command }));
+  const unavailable = (reason: string) => checks.map(check => ({ ...check, reason }));
+  for (const [path, sha] of Object.entries(input.blind.files)) {
+    const bytes = await readFile(join(input.blind.dir, path)).catch(() => null);
+    if (bytes === null || blobAddress(bytes) !== sha) return unavailable(`blind check file ${path} changed or disappeared since the session began`);
+  }
+  const clone = await cloneWorkspace(input.root, input.signal);
+  if (!clone.ok) return unavailable(clone.reason);
+  try {
+    await cp(input.blind.dir, join(clone.path, ".xeno-blind"), { recursive: true });
+    const results: BlindCheckResult[] = [];
+    for (const check of checks) {
+      const captured = await observeCommand({ command: check.command, cwd: clone.path, outputStore: input.outputStore,
+        maxOutputBytes: input.maxOutputBytes, timeoutMs: input.timeoutMs, ...(input.signal ? { signal: input.signal } : {}) });
+      results.push(captured.stopped ? { ...check, reason: `the check did not finish (${captured.stopped})` } : { ...check, exit: captured.exit });
+    }
+    return results;
+  } finally { await clone.dispose(); }
+}

package/src/runtime/counter-check.ts

@@ -0,0 +1,74 @@
+/**
+ * Counter-checks: the discriminating rung of the evidence ladder (S.1).
+ *
+ * A check that passed is run once more against the workspace with this
+ * request's changes undone. If it still passes, it did not test the change --
+ * unless it is a guard, which must still pass there (S.7). That is the harness
+ * applying to the agent the rule verify-red applies to every card: "a test
+ * that cannot fail proves nothing". This module only runs the checks and
+ * reports their exit codes; what an exit code means for a criterion of a
+ * given role is decided in core (`counterVerdict`).
+ *
+ * Three rules keep the verdict honest:
+ * - Only commands that already ran and passed in this request are re-run --
+ *   checks the user accepted -- and only in a disposable clone.
+ * - The clone must be reverted exactly: after undoing the request's changes
+ *   its source fingerprint must equal the baseline recorded when the request
+ *   began. The undo comes from a snapshot taken at the start when there is
+ *   one, else from the journal; a change neither recorded (a shell command
+ *   writing files without a checkpoint, with no snapshot) cannot be undone,
+ *   so nothing runs and the result is unavailable rather than a guess.
+ * - The real workspace is never written.
+ */
+import { join, relative } from "node:path";
+import { changedPaths, planFileTransition, type CheckpointEvent, type FileChanges } from "../core/checkpoints.ts";
+import type { LogEvent } from "../core/events.ts";
+import { applyFileChanges } from "../store/file-checkpoints.ts";
+import { observeCommand } from "../store/command.ts";
+import { observeWorkspace } from "../store/workspace-observation.ts";
+import { cloneWorkspace } from "../store/workspace-clone.ts";
+
+export type CounterCheckInput = {
+  root: string; blobs: string; ownedPaths: readonly string[];
+  /** The request's events, in order. */
+  events: readonly LogEvent[];
+  /**
+   * The exact transition back to the request's starting state, when the
+   * caller took a snapshot at the start (fix-counter-check-own-baseline). It
+   * covers changes a shell command made. Absent: the request's journaled
+   * file changes are undone instead.
+   */
+  revert?: FileChanges;
+  checks: readonly { id: string; command: string; guard?: true }[];
+  timeoutMs: number; maxOutputBytes: number; outputStore: string; signal?: AbortSignal;
+};
+export type CounterCheckResult = { id: string; command: string; guard?: true } & ({ exit: number } | { reason: string });
+
+export async function counterCheck(input: CounterCheckInput): Promise<CounterCheckResult[]> {
+  const unavailable = (reason: string): CounterCheckResult[] => input.checks.map(check => ({ ...check, reason }));
+  if (input.checks.length === 0) return [];
+  const baseline = input.events.findLast(event => event.t === "workspace_observation" && event.baseline === true);
+  if (baseline?.t !== "workspace_observation" || baseline.fingerprint === undefined) return unavailable("no workspace baseline was recorded when this request began");
+  const applied = input.events.filter((event): event is CheckpointEvent => event.t === "checkpoint" && event.phase === "applied");
+  // Undoing every applied change of this request and replaying none is the journal's revert.
+  const revert = input.revert ?? planFileTransition(applied, []);
+  if (changedPaths(revert).length === 0) return unavailable("this request recorded no file changes to undo");
+  const clone = await cloneWorkspace(input.root, input.signal);
+  if (!clone.ok) return unavailable(clone.reason);
+  try {
+    try { await applyFileChanges(clone.path, input.blobs, revert, input.signal); }
+    catch (error) { return unavailable(`the recorded changes could not be undone: ${error instanceof Error ? error.message : String(error)}`); }
+    const owned = input.ownedPaths.map(path => { const rel = relative(input.root, path); return rel.startsWith("..") ? path : join(clone.path, rel); });
+    const observed = await observeWorkspace(clone.path, input.signal, owned);
+    if (!observed.ok) return unavailable(`the reverted copy could not be observed: ${observed.reason}`);
+    if (observed.fingerprint !== baseline.fingerprint) return unavailable(input.revert ? "the request's starting state could not be rebuilt exactly"
+      : "some changes were made outside tracked edits, so the request's starting state could not be rebuilt");
+    const results: CounterCheckResult[] = [];
+    for (const check of input.checks) {
+      const captured = await observeCommand({ command: check.command, cwd: clone.path, outputStore: input.outputStore,
+        maxOutputBytes: input.maxOutputBytes, timeoutMs: input.timeoutMs, ...(input.signal ? { signal: input.signal } : {}) });
+      results.push(captured.stopped ? { ...check, reason: `the check did not finish in the reverted copy (${captured.stopped})` } : { ...check, exit: captured.exit });
+    }
+    return results;
+  } finally { await clone.dispose(); }
+}

package/src/runtime/exec-sessions.ts

@@ -33,6 +33,17 @@ export const DEFAULT_YIELD_MS = 10_000;
 /** Bounds on a foreground poll or input send. Owned observation waits have no polling deadline. */
 export const MIN_YIELD_MS = 100;
 export const MAX_YIELD_MS = 30_000;
+
+/**
+ * The wait actually taken, clamped like Codex's `clamp_yield_time` (S.6
+ * item 5): an out-of-range value still runs the call, and `note` tells the
+ * model what it waited instead of what it asked for.
+ */
+export function yieldWait(value: unknown): { ms: number; note: string } {
+  const requested = typeof value === "number" && Number.isFinite(value) ? value : DEFAULT_YIELD_MS;
+  const ms = Math.min(MAX_YIELD_MS, Math.max(MIN_YIELD_MS, requested));
+  return { ms, note: ms === requested ? "" : ` · yield_time_ms ${requested} clamped to ${ms}` };
+}
 /**
  * Concurrent sessions. An assumption, not a measurement: comfortably above a
  * server + watcher + REPL, low enough that a runaway loop of starts is refused

package/src/runtime/foundation.ts

@@ -12,15 +12,27 @@ import { LspManager, parseLspConfig } from "./lsp-client.ts";
 import { validateFormatters } from "./formatter.ts";
 import { createFormatterTool } from "./formatter-tool.ts";
 import { permissionResourceAction } from "./permission-resources.ts";
-import type { ToolContext, ToolDefinition, ToolResult } from "./tools.ts";
+import type { InstructionCheck, ToolContext, ToolDefinition } from "./tools.ts";
 import { McpManager } from "./mcp-client.ts";
 import { parseMcpServers } from "../core/mcp-config.ts";
 import type { ExtensionRegistry } from "./extensions.ts";
 import { join } from "node:path";
 import { getBlob } from "../store/blobs.ts";
 
+/**
+ * Calls that only observe run and carry newly discovered rules (S.6 item 3:
+ * OpenCode, Gemini CLI and Claude Code do the same). A change is still held
+ * back until the rules have been read: the reason for blocking first was never
+ * to notify after a modification (foundation-editing research).
+ */
+const OBSERVING_TOOLS = new Set(["read", "query", "lsp"]);
+/** Assumed: more batches than any interleaving of live sessions sharing this runtime. */
+const RECENT_BATCHES = 16;
+
 export class FoundationRuntime {
   readonly questionSlot: QuestionSlot;
+  /** Per batch (assistant event id): instruction key -> the call that carried it. */
+  private readonly batches = new Map<string, Map<string, string>>();
   readonly mcp: McpManager;
   readonly tools: ToolDefinition[];
   readonly permissions: PermissionRule[];
@@ -47,14 +59,32 @@ export class FoundationRuntime {
     const discovered = await this.mcp.discover();
     for (const integration of discovered.integrations) registry.api("xeno-mcp").registerIntegration(integration);
   }
-  async instructions(ctx: ToolContext, name: string, input: unknown, noContextFiles: boolean): Promise<ToolResult | null> {
+  /** Calls are prepared one at a time in their batch, so "first to discover carries the rules" is deterministic. */
+  private claims(batch: string): Map<string, string> {
+    let claimed = this.batches.get(batch);
+    if (claimed === undefined) {
+      claimed = new Map();
+      this.batches.set(batch, claimed);
+      for (const old of this.batches.keys()) if (this.batches.size > RECENT_BATCHES) this.batches.delete(old);
+    }
+    return claimed;
+  }
+  async instructions(ctx: ToolContext, name: string, input: unknown, noContextFiles: boolean): Promise<InstructionCheck | null> {
     if (noContextFiles || !["read", "write", "edit", "apply_patch", "query", "format", "lsp"].includes(name) || !input || typeof input !== "object") return null;
     const args = input as Record<string, unknown>;
     const paths = name === "apply_patch" ? patchPaths(parsePatch(String(args["patchText"]))) : typeof args["path"] === "string" ? [args["path"]] : Array.isArray(args["paths"]) ? args["paths"].filter((path): path is string => typeof path === "string") : [];
     if (!paths.length) return null;
+    const blocked = (content: string): InstructionCheck => ({ kind: "block", result: { ok: false, content } });
     const known = new Set<string>();
-    for (const event of await ctx.historyEvents?.() ?? []) {
-      if (event.t !== "tool_result") continue;
+    const history = await ctx.historyEvents?.() ?? [];
+    // Rules count as read only once the model has seen them: results of this
+    // same batch may already be committed, but they reach the model together
+    // with this call's result. Within the batch, claims decide instead.
+    const batch = history.findLast(event => event.t === "assistant");
+    const sameBatch = new Set(batch?.t === "assistant" ? batch.blocks.flatMap(block => block.type === "tool_use" ? [block.call_id] : []) : []);
+    for (const event of history) {
+      if (event.t !== "tool_result" || sameBatch.has(event.call_id)) continue;
+      for (const key of event.instructions?.keys ?? []) known.add(key);
       let data: unknown = event.data;
       if (event.data_ref && ctx.outputStore) {
         const saved = await getBlob(ctx.outputStore, event.data_ref.sha256);
@@ -67,12 +97,20 @@ export class FoundationRuntime {
     }
     const found = await discoverTargetInstructions({ workspace: ctx.root, paths, known,
       canRead: async path => await permissionResourceAction(ctx.root, path, ctx.rules ?? [], ctx.sessionRules ?? []) === "allow" });
-    if (found.notices.some(notice => notice.kind === "skipped" && notice.reason === "instruction read permission is unavailable")) return { ok: false, content: "Scoped instructions require read permission before this operation." };
+    if (found.notices.some(notice => notice.kind === "skipped" && notice.reason === "instruction read permission is unavailable")) return blocked("Scoped instructions require read permission before this operation.");
     const files = found.files.filter(file => !ctx.frozenSystem?.().includes(file.content));
     if (!files.length) return null;
-    for (const file of files) if (await permissionResourceAction(ctx.root, file.path, ctx.rules ?? [], ctx.sessionRules ?? []) !== "allow") return { ok: false, content: "Scoped instructions require read permission before this operation." };
-    return { ok: false, content: "Scoped instructions were discovered. Read and follow them before deciding whether to retry the original operation. No original operation was executed.\n\n" + renderTargetInstructions(files),
-      data: { kind: "scoped_instructions", keys: files.map(file => file.key), files: files.map(file => ({ path: file.path, scope: file.scope, key: file.key, content: file.content, truncated: file.truncated })) } };
+    for (const file of files) if (await permissionResourceAction(ctx.root, file.path, ctx.rules ?? [], ctx.sessionRules ?? []) !== "allow") return blocked("Scoped instructions require read permission before this operation.");
+    // Once per batch: a later call in the same assistant message does not receive the same rules again.
+    const claimed = this.claims(batch?.id ?? "");
+    const fresh = files.filter(file => !claimed.has(file.key));
+    const carriers = [...new Set(files.flatMap(file => claimed.get(file.key) ?? []))];
+    for (const file of fresh) claimed.set(file.key, ctx.callId ?? name);
+    if (OBSERVING_TOOLS.has(name)) return fresh.length ? { kind: "attach", instructions: { keys: fresh.map(file => file.key), text: renderTargetInstructions(fresh) } } : null;
+    const earlier = carriers.length ? `Scoped instructions for this target were attached to the result of ${carriers.join(", ")} in this batch. ` : "";
+    if (!fresh.length) return blocked(`${earlier}No original operation was executed. Follow them, then retry.`);
+    return { kind: "block", result: { ok: false, content: `Scoped instructions were discovered. ${earlier}Read and follow them before deciding whether to retry the original operation. No original operation was executed.\n\n` + renderTargetInstructions(fresh),
+      data: { kind: "scoped_instructions", keys: fresh.map(file => file.key), files: fresh.map(file => ({ path: file.path, scope: file.scope, key: file.key, content: file.content, truncated: file.truncated })) } } };
   }
   async dispose(): Promise<void> { await Promise.all([this.lsp.dispose(), this.mcp.dispose()]); }
 }