@visual-z/xeno 0.7.2 → 0.8.0

package/src/runtime/oauth.ts

@@ -16,9 +16,7 @@
 import { createServer, type Server } from "node:http";
 import { pollDeviceCode } from "./oauth-device.ts";
 import { parseDeviceAuthorization, parseOAuthTokens } from "../core/oauth-fields.ts";
-
-/** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.7.2";
+import { XENO_VERSION } from "./version.ts";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge

package/src/runtime/provider-request.ts

@@ -1,7 +1,8 @@
 import { providerEnvironment, resolveKeyValue, type ResolveEffects } from "./auth.ts";
 import { providerAccess } from "./provider-access.ts";
 import type { ModelSpec } from "./model.ts";
-import { XENO_VERSION, GROK_PROVIDER, GROK_BASE_URL, GROK_PROTOCOL_VERSION } from "./oauth.ts";
+import { GROK_PROVIDER, GROK_BASE_URL, GROK_PROTOCOL_VERSION } from "./oauth.ts";
+import { XENO_VERSION } from "./version.ts";
 
 const SDK_IDENTITY_HEADERS = ["x-app", "editor-version", "editor-plugin-version", "copilot-integration-id", "http-referer", "x-title"];
 

package/src/runtime/runtime-target.ts

@@ -13,7 +13,7 @@ import { executionOutcome } from "../core/outcome.ts";
 import { archiveCommandArtifacts, artifactExclusions, observeArtifactFiles, observeArtifactInputs } from "../store/command-artifacts.ts";
 import { readObservation } from "../store/observations.ts";
 import { targetDirectory, targetProgram, observeRuntimeIdentity } from "../store/runtime-target.ts";
-import { findSession, startSession, pollSession } from "./exec-sessions.ts";
+import { findSession, startSession, pollSession, yieldWait } from "./exec-sessions.ts";
 import { sessionResult, type ToolContext, type ToolResult } from "./tools.ts";
 
 type History = readonly { node: number; events: readonly LogEvent[] }[];
@@ -63,7 +63,7 @@ export class RuntimeTargets {
         const live: LiveTarget = { request: state.request, contract: state.contract_event, build: receipt.build!.event,
           instance: { id: randomUUID(), session: session.id, pid: session.pid, source, entry: { path: entryPath, sha256: entry.sha256 }, program } };
         this.live.set(target.id, live);
-        const taken = await pollSession(session, archive, ctx.maxOutputBytes, input.yield_time_ms ?? 1000, "", ctx.signal);
+        const taken = await pollSession(session, archive, ctx.maxOutputBytes, yieldWait(input.yield_time_ms ?? 1000).ms, "", ctx.signal);
         raw.push(taken.stored.ref);
         processResult = await sessionResult(ctx, session.command, session.timeoutMs, taken);
       }

package/src/runtime/session-control.ts

@@ -9,7 +9,7 @@ import type { PermissionRequest } from "../core/permissions.ts";
 import type { ExecutionOutcome } from "../core/outcome.ts";
 import type { LogEvent } from "../core/events.ts";
 import { readNodeHistory } from "../store/restore.ts";
-import type { Session, LoopEvent } from "./loop.ts";
+import type { Session, LoopEvent, RequestOptions } from "./loop.ts";
 import type { ApprovalChoice } from "./tools.ts";
 import { validateQuestionReply, type QuestionRequest, type QuestionReply } from "../core/question.ts";
 import type { QuestionSlot } from "./question-tool.ts";
@@ -87,7 +87,7 @@ export class SessionControl {
     // Ancestors are sealed. The live segment must share the cursor's publication
     // boundary: a disk read can finish between append and in-memory publication.
     const parts = history.nodes.map(part => part.node === node ? { node, events: structuredClone(s.state.events) } : part);
-    const projectedGoal = goalView(parts);
+    const projectedGoal = goalView(parts, { strict: s.config.strictVerification === true, blind: s.config.blindChecks !== undefined });
     const goal = this.active && projectedGoal?.state.request.event !== this.active.id ? null : projectedGoal;
     return { version: "xeno-control/0.1", threadId: this.threadId, streamId: this.streamId, sequence: this.sequence, node,
       activeTurnId: this.activeTurnId, goal, waiting: this.waiting, workflowMode: s.config.tools.workflowMode ?? "build",
@@ -107,7 +107,7 @@ export class SessionControl {
   }
 
   /** Both local and remote turns pass through this iterator; Session remains the execution owner. */
-  async *send(input: UserInput, signal?: AbortSignal, pull?: (phase: Phase) => Promise<UserInput | null>): AsyncGenerator<LoopEvent> {
+  async *send(input: UserInput, signal?: AbortSignal, pull?: (phase: Phase) => Promise<UserInput | null>, options?: RequestOptions): AsyncGenerator<LoopEvent> {
     if (this.busy) throw Error("a turn is already running");
     const active = { id: this.session.clock.nextId(), abort: new AbortController(), queue: [] as UserInput[] };
     this.active = active;
@@ -123,7 +123,7 @@ export class SessionControl {
         const text = data.map(value => value.text).join("\n\n"), images = data.flatMap(value => value.images ?? []);
         return images.length ? { text, images } : text || null;
       };
-      for await (const event of this.session.send(input, signals, steering, active.id)) {
+      for await (const event of this.session.send(input, signals, steering, active.id, options)) {
         this.emit("turn/event", { event });
         if (event.kind === "done") outcome = event.outcome;
         yield event;

package/src/runtime/tools.ts

@@ -28,20 +28,20 @@ import { archiveObservation, readObservation, type ArchivedObservation } from ".
 import { blobAddress } from "../store/blobs.ts";
 import { commandHeader, headTailView } from "../core/observation-view.ts";
 import {
-  DEFAULT_YIELD_MS, MAX_YIELD_MS, MIN_YIELD_MS, findSession, closedSession, runningSessions, startSession, pollSession,
+  yieldWait, findSession, closedSession, runningSessions, startSession, pollSession,
 } from "./exec-sessions.ts";
 import { recoverProcessReceipt, type ProcessReceipt, type latestProcessReceipt } from "../core/process-receipt.ts";
 import { observeCommand, observeArgvCommand } from "../store/command.ts";
 import { executionOutcome, type ExecutionOutcome } from "../core/outcome.ts";
 import { commandCompletion, commandTimeout } from "../core/command-contract.ts";
-import { previewReadObservation, readObservationText, type ObservationReceipt } from "../core/read-observation.ts";
+import { linesWithin, previewReadObservation, readObservationText, type ObservationReceipt } from "../core/read-observation.ts";
 import { checkFilePrecondition, isFileDigest, isFileReadDescriptor, type FileReadDescriptor, type FilePrecondition } from "../core/file-precondition.ts";
 import { previewSearchObservation, searchObservationText } from "../core/search-observation.ts";
 import { waitForAdmission } from "./execution-control.ts";
 import { assertNever } from "../core/exhaustive.ts";
 import { artifactRecovery, toolDescription, type ToolGuidance } from "../core/prompt-policy.ts";
 import { classifyGate } from "../core/evidence.ts";
-import { readBounds } from "../core/read-bounds.ts";
+import { readBounds, readNotice } from "../core/read-bounds.ts";
 import { closestName, inputError, isJsonValue, minimalInput, type JsonValue, type ToolDiagnostic } from "../core/tool-contract.ts";
 import { failureDiagnostic, failureFromError, scopeFailureGuidance, NOT_STARTED, READ_ATTEMPTED, UNKNOWN_EFFECT, type FailureFacts } from "../core/tool-failure.ts";
 import { planEdits, type EditSpec } from "../core/edit-plan.ts";
@@ -66,7 +66,7 @@ import { imageDescription } from "../core/images.ts";
 import { attachImageBytes } from "./images.ts";
 import { detectSupportedImageMimeType } from "../vendor/pi-rich/mime.ts";
 import { find as findFiles, grep, ls, MAX_FILE_BYTES, MAX_SEARCH_CAPTURE_BYTES, type SearchResult } from "../store/search.ts";
-import { scanWorkspace, workspaceVersion, DEFAULT_IGNORE } from "../store/workspace.ts";
+import { DEFAULT_IGNORE } from "../store/workspace.ts";
 import { observeWorkspace } from "../store/workspace-observation.ts";
 import { readEditableFile, replaceFile } from "../store/file-checkpoints.ts";
 import type { WorkspaceLifecycle } from "./workspace-lifecycle.ts";
@@ -98,14 +98,26 @@ export interface ToolResult {
   data?: JsonValue;
   diagnostic?: ToolDiagnostic;
   warnings?: readonly ToolDiagnostic[];
+  /** Scoped instructions attached to a read-only call that ran (S.6 item 3). */
+  instructions?: { keys: readonly string[]; text: string };
 }
 
+/**
+ * What target-scoped instruction discovery decided for one call: hold a change
+ * back until the rules are read, or let a read-only call run and carry them.
+ */
+export type InstructionCheck =
+  | { kind: "block"; result: ToolResult }
+  | { kind: "attach"; instructions: { keys: readonly string[]; text: string } };
+
 export interface ToolContext {
   historyEvents?: () => Promise<import("../core/events.ts").LogEvent[]>;
   checkpointBlobs?: string;
   frozenSystem?: () => string;
-  instructionCheck?: (ctx: ToolContext, name: string, input: unknown) => Promise<ToolResult | null>;
+  instructionCheck?: (ctx: ToolContext, name: string, input: unknown) => Promise<InstructionCheck | null>;
   workflowMode?: "build" | "plan";
+  /** What a Plan-mode refusal tells the model instead of the default "select Build". */
+  planHint?: string;
   /** CLI owns its approval defaults; SDK callers retain their supplied host policy across reload. */
   appOwnsPermissions?: true;
   hostPermissionRules?: PermissionRule[];
@@ -121,8 +133,6 @@ export interface ToolContext {
   /** P.3: admitted execution owns file recovery; extensions cannot supply model-authored effects. */
   workspace?: WorkspaceLifecycle;
   ownedStatePaths?: readonly string[];
-  /** Historical fingerprint compatibility, never enabled by the normal CLI. */
-  legacyWorkspace?: boolean;
   /** O.15: optional disposable view; the reader still validates the original log. */
   historyCache?: HistoryCache;
   /** O.14: opaque process ownership is supplied by Session, never by model input. */
@@ -349,7 +359,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     input_schema: { type: "object", required: ["action", "target"], properties: {
       action: { type: "string", enum: ["start", "inspect"] }, target: { type: "string" },
       session_id: { type: "integer", minimum: 1, description: "Inspect this exact previously returned handle; never adopts a process" },
-      yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "Milliseconds to wait for launch; default 10000, distinct from the hard timeout" },
+      yield_time_ms: { type: "integer", description: "Milliseconds to wait for launch; default 1000, distinct from the hard timeout; effective range 100-30000, values outside are clamped" },
       timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Hard process lifetime in seconds; defaults to the session command timeout" },
     } },
   },
@@ -620,7 +630,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
         artifacts: commandArtifactsSchema,
         workdir: { type: "string", description: "Directory to run in; default the workspace root" },
         tty: { type: "boolean", description: "Run in a pseudo-terminal; default false" },
-        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "Milliseconds to wait before returning; default 10000" },
+        yield_time_ms: { type: "integer", description: "Milliseconds to wait before returning; default 10000; effective range 100-30000, values outside are clamped" },
         timeout: { type: "integer", minimum: 1, maximum: 3600, description: "Seconds before the session is killed; default 300" },
       },
       required: ["cmd"],
@@ -640,7 +650,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
       properties: {
         session_id: { type: "integer", minimum: 1 },
         chars: { type: "string", description: "Characters to write; empty to poll" },
-        yield_time_ms: { type: "integer", minimum: 100, maximum: 30000, description: "Bounded wait when sending input or using low-level polling; agent empty waits are owned until an observation changes" },
+        yield_time_ms: { type: "integer", description: "Bounded wait when sending input or using low-level polling; effective range 100-30000, values outside are clamped; agent empty waits are owned until an observation changes" },
       },
       required: ["session_id"],
     },
@@ -831,11 +841,16 @@ async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promi
   // cannot take the whole observation budget; the notice names the next start.
   const first = input["start"] ?? 1;
   const end = input["end"] === undefined && Number.isSafeInteger(first) ? (first as number) + READ_DEFAULT_LINES - 1 : input["end"];
-  const selected = readBounds(lines.length, input["start"], end);
-  if (!selected.ok) return failure("invalid_input", selected.message, READ_ATTEMPTED);
-  const { start } = selected;
-  const slice = lines.slice(start - 1, selected.end);
+  const bounds = readBounds(lines.length, input["start"], end);
+  if (!bounds.ok) return failure("invalid_input", bounds.message, READ_ATTEMPTED);
+  const { start } = bounds;
   const version = sha256(bytes);
+  // The selection is what fits whole, so the receipt's range is the range shown.
+  const sized = (count: number, handle: string) =>
+    `${readNotice(start, start + count - 1, lines.length, count < bounds.end - start + 1 ? ctx.maxOutputBytes : undefined)}\nsha256: ${version}\nread_handle: ${handle}\n`;
+  const shown = linesWithin(count => sized(count, "0".repeat(64)), lines.slice(start - 1, bounds.end), start, ctx.maxOutputBytes, undefined, adviceTools(ctx));
+  const selected = { end: start + shown - 1 };
+  const slice = lines.slice(start - 1, selected.end);
   const store = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
   async function* one(value: Uint8Array): AsyncGenerator<Uint8Array> { yield value; }
   // Archive actual bytes before either presentation cut. Re-reading the current file is not recovery.
@@ -844,7 +859,7 @@ async function toolRead(ctx: ToolContext, input: Record<string, unknown>): Promi
   const selection = { start, end: selected.end, total_lines: lines.length };
   const descriptor: FileReadDescriptor = { kind: "file_read", version: 1, source, selection };
   const handle = await archiveObservation(store, one(new TextEncoder().encode(JSON.stringify(descriptor))), 0);
-  const header = `${selected.notice}\nsha256: ${version}\nread_handle: ${handle.ref.sha256}\n`;
+  const header = sized(shown, handle.ref.sha256);
   const full = new TextEncoder().encode(readObservationText(header, slice, start));
   const observation = await archiveObservation(store, one(full), 0);
   const preview = previewReadObservation(header, slice, start, observation.ref.sha256, ctx.maxOutputBytes, undefined, adviceTools(ctx));
@@ -1048,19 +1063,6 @@ async function toolBash(ctx: ToolContext, input: Record<string, unknown>): Promi
   };
 }
 
-/**
- * Derived output a command's fingerprint leaves out.
- *
- * The fingerprint keys verification evidence to the source state it ran
- * against; build products and caches change on every build without the
- * sources changing, and walking them (a Rust `target/` or a virtualenv) costs
- * seconds after every command. Snapshots and rewind keep DEFAULT_IGNORE --
- * whether to restore derived files is their decision, not this one.
- */
-const FINGERPRINT_IGNORE: readonly string[] = [...DEFAULT_IGNORE,
-  "target", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox",
-  ".gradle", ".next", ".turbo", ".cache"];
-
 async function commitEdit(ctx: ToolContext, absolute: string, before: Awaited<ReturnType<typeof readEditableFile>>, after: Uint8Array): Promise<void> {
   const path = relative(ctx.root, absolute);
   if (ctx.workspace && path !== ".." && !path.startsWith(`..${sep}`)) await ctx.workspace.edit(path, before, after, ctx.signal);
@@ -1068,16 +1070,10 @@ async function commitEdit(ctx: ToolContext, absolute: string, before: Awaited<Re
 }
 
 async function commandFingerprint(ctx: ToolContext): Promise<{ workspace_sha256?: string; workspace_observed?: boolean; workspace_scope?: "source-v1" }> {
-  if (ctx.legacyWorkspace) {
-    const observed = await scanWorkspace(ctx.root, FINGERPRINT_IGNORE);
-    return observed.ok ? { workspace_sha256: workspaceVersion(observed.files) } : {};
-  }
   const observed = await observeWorkspace(ctx.root, ctx.signal, ctx.ownedStatePaths);
   return observed.ok ? { workspace_sha256: observed.fingerprint, workspace_observed: true, workspace_scope: "source-v1" } : { workspace_observed: false, workspace_scope: "source-v1" };
 }
 
-const clampYield = (value: unknown) =>
-  Math.min(MAX_YIELD_MS, Math.max(MIN_YIELD_MS, typeof value === "number" && Number.isFinite(value) ? value : DEFAULT_YIELD_MS));
 
 async function toolExec(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
   const command = String(input["cmd"] ?? "");
@@ -1093,7 +1089,8 @@ async function toolExec(ctx: ToolContext, input: Record<string, unknown>): Promi
     ...(artifactObserver ? { artifactObserver } : {}),
     ...(ctx.execOwner === undefined ? {} : { owner: ctx.execOwner }) });
   if ("error" in session) return failure("execution_failed", session.error);
-  return sessionResult(ctx, command, timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, clampYield(input["yield_time_ms"]), "", ctx.signal));
+  const wait = yieldWait(input["yield_time_ms"]);
+  return sessionResult(ctx, command, timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, wait.ms, "", ctx.signal), wait.note);
 }
 
 async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>): Promise<ToolResult> {
@@ -1111,8 +1108,9 @@ async function toolWriteStdin(ctx: ToolContext, input: Record<string, unknown>):
       data: { kind: "process", version: 1, session_id: id, state: "unknown", capability: "unknown", source: null, running: null, exit: null, replayed: true } };
   }
   const outputStore = ctx.outputStore ?? join(ctx.root, ".xeno", "observations");
-  return sessionResult(ctx, session.command, session.timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, clampYield(input["yield_time_ms"]), chars, ctx.signal,
-    ctx.processWait && chars.length === 0 ? { wake: ctx.processWait.wake(), onWaiting: active => ctx.onProcessWait?.(id, active) } : undefined));
+  const wait = yieldWait(input["yield_time_ms"]);
+  return sessionResult(ctx, session.command, session.timeoutMs, await pollSession(session, outputStore, ctx.maxOutputBytes, wait.ms, chars, ctx.signal,
+    ctx.processWait && chars.length === 0 ? { wake: ctx.processWait.wake(), onWaiting: active => ctx.onProcessWait?.(id, active) } : undefined), wait.note);
 }
 
 /** A successful historical query proves only that the receipt was found, never a new command exit. */
@@ -1133,15 +1131,16 @@ function receiptResult(ctx: ToolContext, receipt: ProcessReceipt, chars: string)
  * carries no effect; only an observed exit does, exactly as bash's would (D11).
  */
 export async function sessionResult(ctx: ToolContext, command: string, timeoutMs: number,
-  taken: Awaited<ReturnType<typeof pollSession>>): Promise<ToolResult> {
+  taken: Awaited<ReturnType<typeof pollSession>>, waitNote = ""): Promise<ToolResult> {
   const { stored, exit } = taken;
   const id = taken.receipt.session_id;
   if (taken.receipt.replayed) return receiptResult(ctx, taken.receipt, "");
-  const header = exit === null
+  const shown = exit === null
     ? `running · session ${id} · ${(taken.wallMs / 1000).toFixed(1)}s elapsed; ` + (adviceTools(ctx).includes("write_stdin")
       ? `poll or send input with write_stdin(session_id=${id})`
       : "process-control capability unavailable; execution remains unfinished; do not replay")
     : commandHeader({ exit, wallMs: taken.wallMs, timeoutMs, managed: true, ...(taken.stopped ? { stopped: taken.stopped } : {}) }) + ` · session ${id} closed`;
+  const header = shown + waitNote;
   const artifactSummary = commandArtifactSummary(taken.receipt.artifacts);
   const content = header + artifactSummary + "\n" + observationView(stored, ctx.maxOutputBytes - utf8Length(header + artifactSummary) - 1, 0, adviceTools(ctx));
   const warnings = taken.receipt.capture === "partial" ? [failureDiagnostic("unknown_effect", "output capture is partial; full_output contains only captured bytes", UNKNOWN_EFFECT)] : [];
@@ -1338,7 +1337,7 @@ export async function gateTool(
   const definition = toolDefinition(name, ctx);
   if (ctx.workflowMode === "plan" && definition && definition.access !== "read" &&
     !(definition.access === "state" && (name === "note" || name === "question" && ctx.questionSlot)))
-    return failure("permission_denied", `${name} is unavailable in Plan mode; select Build at an idle checkpoint.`);
+    return failure("permission_denied", `${name} is unavailable in Plan mode; ${ctx.planHint ?? "select Build at an idle checkpoint."}`);
   input = repairToolInput(name, input);
   let invalid: string | null = null;
   if (definition?.validateInput) {
@@ -1434,11 +1433,13 @@ function observerValue<T>(value: T): T {
 export async function prepareNormalizedTool(ctx: ToolContext, name: string, input: unknown,
   prepareAction?: () => Promise<() => Promise<ToolResult>>): Promise<ToolResult | (() => Promise<ToolResult>)> {
   const scoped = <T>(action: () => T): T => ctx.extensionHooks?.scope ? ctx.extensionHooks.scope(ctx, action) : action();
+  let attached: ToolResult["instructions"];
   try {
     const gated = await gateTool(ctx, name, input);
     if (gated) return scopeToolAdvice(ctx, finishToolResult(gated));
     const instructions = await ctx.instructionCheck?.(ctx, name, input);
-    if (instructions) return scopeToolAdvice(ctx, finishToolResult(instructions));
+    if (instructions?.kind === "block") return scopeToolAdvice(ctx, finishToolResult(instructions.result));
+    if (instructions?.kind === "attach") attached = instructions.instructions;
     const veto = await scoped(() => ctx.extensionHooks?.before(name, observerValue(input), ctx.callId, ctx.parentCallId));
     await ctx.drainNested?.();
     if (veto) return scopeToolAdvice(ctx, finishToolResult(failure("permission_denied", veto)));
@@ -1488,7 +1489,8 @@ export async function prepareNormalizedTool(ctx: ToolContext, name: string, inpu
       else observed = finishToolResult(caughtFailure(error, UNKNOWN_EFFECT));
     }
     await Promise.all(updates);
-    return scopeToolAdvice(ctx, warnings.length ? { ...observed, warnings: [...(observed.warnings ?? []), ...warnings] } : observed);
+    const result = warnings.length ? { ...observed, warnings: [...(observed.warnings ?? []), ...warnings] } : observed;
+    return scopeToolAdvice(ctx, attached ? { ...result, instructions: attached } : result);
   };
 }
 

package/src/runtime/version.ts

@@ -0,0 +1,12 @@
+/**
+ * The one place xeno's version is known (S.4: a release edits package.json and
+ * nothing else). It is sent as the User-Agent (D18: xeno names itself
+ * honestly) and compared against npm for update notices.
+ *
+ * Read at load rather than imported: `bun run check` requires every import to
+ * be a literal relative `.ts` path. package.json ships in every install, so
+ * this resolves the same way from a checkout and from a global install.
+ */
+import { readFileSync } from "node:fs";
+
+export const XENO_VERSION: string = (JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version: string }).version;

package/src/runtime/workspace-lifecycle.ts

@@ -100,9 +100,40 @@ export class WorkspaceLifecycle {
       source: "git", phase: "unavailable", changes: {}, reason: "process ended without an observed checkpoint boundary" });
     this.pending.clear();
   }
+  /**
+   * A full source snapshot through the private Git checkpoint store, or null
+   * where Git checkpoints cannot run (not a Git working directory, over
+   * budget). Never touches the user's HEAD, index or stash (P.3).
+   */
+  async snapshot(signal?: AbortSignal): Promise<GitCheckpoint | null> {
+    try { return await this.git.capture(signal); } catch { return null; }
+  }
+
+  /** What changed between two snapshots, with both versions' bytes in the blob store. */
+  async snapshotChanges(before: GitCheckpoint, after: GitCheckpoint, signal?: AbortSignal): Promise<FileChanges> {
+    return this.git.changes(before, after, this.blobs, signal);
+  }
+
+  /**
+   * Records the workspace as a goal request begins, always: the state a
+   * counter-check must rebuild exactly before it may run (feat-counter-check).
+   */
+  async baseline(signal?: AbortSignal): Promise<void> {
+    const observation = await observeWorkspace(this.root, signal, this.ownedPaths);
+    const fingerprint = observation.ok ? observation.fingerprint : undefined;
+    await this.record({ t: "workspace_observation", scope: "source-v1", baseline: true,
+      changed: !observation.ok || this.fingerprint !== undefined && fingerprint !== this.fingerprint,
+      ...(observation.ok ? { fingerprint: observation.fingerprint } : { reason: observation.reason }) });
+    this.fingerprint = fingerprint;
+  }
+
   async observe(previous?: string, signal?: AbortSignal): Promise<void> {
     const observation = await observeWorkspace(this.root, signal, this.ownedPaths);
     const fingerprint = observation.ok ? observation.fingerprint : undefined;
+    // S.1: an observation identical to the last known fingerprint adds no fact.
+    // Failures, a first look without a baseline, and changes are still recorded.
+    const known = previous ?? this.fingerprint;
+    if (fingerprint !== undefined && known !== undefined && fingerprint === known) { this.fingerprint = fingerprint; return; }
     await this.record({ t: "workspace_observation", scope: "source-v1", changed: !observation.ok || (previous ?? this.fingerprint) !== undefined && fingerprint !== (previous ?? this.fingerprint),
       ...(observation.ok ? { fingerprint: observation.fingerprint } : { reason: observation.reason }) });
     this.fingerprint = fingerprint;

package/src/store/blind-checks.ts

@@ -0,0 +1,32 @@
+/**
+ * Reading a blind check directory (feat-blind-checks). It must sit outside
+ * the workspace -- a check inside it is a file the model can open -- and is
+ * frozen into the session with every file's digest, so a resumed session
+ * runs exactly the checks it started with.
+ */
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { BLIND_BYTES_LIMIT, BLIND_FILE_LIMIT, parseBlindManifest, type BlindChecks } from "../core/blind-checks.ts";
+import { blobAddress } from "./blobs.ts";
+
+export async function loadBlindChecks(dir: string, workspace: string): Promise<BlindChecks> {
+  const given = resolve(workspace, dir), root = await realpath(given), work = await realpath(workspace);
+  const inside = relative(work, root);
+  if (inside === "" || !inside.startsWith("..") && !isAbsolute(inside)) throw Error("--blind-checks must be outside the workspace, where the model cannot read it");
+  const files: Record<string, string> = {};
+  let bytes = 0;
+  const walk = async (path: string): Promise<void> => {
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      const full = join(path, entry.name), rel = relative(root, full);
+      if (entry.isDirectory()) { await walk(full); continue; }
+      if (!entry.isFile()) throw Error(`blind check ${rel} is not a regular file`);
+      if (Object.keys(files).length >= BLIND_FILE_LIMIT) throw Error(`--blind-checks holds more than ${BLIND_FILE_LIMIT} files`);
+      bytes += (await stat(full)).size;
+      if (bytes > BLIND_BYTES_LIMIT) throw Error(`--blind-checks holds more than ${BLIND_BYTES_LIMIT} bytes`);
+      files[rel] = blobAddress(await readFile(full));
+    }
+  };
+  await walk(root);
+  const manifest = parseBlindManifest(JSON.parse(await readFile(join(root, "blind.json"), "utf8")));
+  return { dir: root, aliases: given === root ? [] : [given], manifest, files };
+}

package/src/store/checkpoint-history.ts

@@ -1,6 +1,6 @@
 /** File ancestry is independent of model-context ancestry (P.3). */
 import { readNodeHistory, type RestoreTarget } from "./restore.ts";
-import { planFileTransition, type CheckpointEvent, type FileVersion, type FileChanges } from "../core/checkpoints.ts";
+import { planFileTransition, type CheckpointEvent, type FileChanges } from "../core/checkpoints.ts";
 
 export async function checkpointHistory(dir: string, target: RestoreTarget, visited = new Set<string>()): Promise<CheckpointEvent[]> {
   const position = typeof target === "number" ? { node: target } : target;
@@ -10,7 +10,6 @@ export async function checkpointHistory(dir: string, target: RestoreTarget, visi
   const history = await readNodeHistory(dir, position.node);
   if (!history.ok) throw new Error(history.error);
   let checkpoints: CheckpointEvent[] = [];
-  const legacy = new Map<string, FileVersion>();
   for (const node of history.nodes) {
     let events = node.events;
     if (node.node === position.node && position.atEvent !== undefined) {
@@ -23,16 +22,6 @@ export async function checkpointHistory(dir: string, target: RestoreTarget, visi
         checkpoints = await checkpointHistory(dir, { node: event.files_from.node,
           ...(event.files_from.at_event ? { atEvent: event.files_from.at_event } : {}) }, next);
       } else if (event.t === "checkpoint") checkpoints.push(event);
-      else if (event.t === "snapshot") {
-        // Interpret historical full snapshots without rewriting them or scanning today's disk.
-        const changes: FileChanges = Object.create(null) as FileChanges;
-        for (const [path, sha256] of Object.entries({ ...event.added, ...event.changed })) {
-          changes[path] = { before: legacy.get(path) ?? null, after: { sha256, mode: 0o644 } };
-          legacy.set(path, changes[path]!.after);
-        }
-        for (const path of event.removed) { changes[path] = { before: legacy.get(path) ?? null, after: null }; legacy.delete(path); }
-        checkpoints.push({ t: "checkpoint", id: event.id, at: event.at, operation: event.id, source: "git", phase: "applied", changes });
-      }
     }
   }
   return checkpoints;

package/src/store/file-index.ts

@@ -1,22 +1,31 @@
 /**
- * Candidate paths for @-file expansion.
+ * Candidate paths for @-file expansion and the walk search engine.
  *
  * A glob on every keystroke is a stall in a large repo (the card's rejected
  * alternative). Scan once, cache for the session. The snapshot scanner is a
  * different job -- it hashes contents and refuses to truncate -- so this walk
  * is its own function rather than a mode flag on scanWorkspace.
+ *
+ * Inside a Git work tree the candidates are Git's own listing: tracked plus
+ * untracked files that are not ignored (S.6 item 4). Claude Code's Grep,
+ * OpenCode (`rg --files`) and Pi (`fd`) follow .gitignore the same way; a
+ * walk that ignores it let an ignored worktree's build output fill the whole
+ * budget before the product's directories were reached
+ * (research-file-index-truncation).
  */
 
-import { readdir } from "node:fs/promises";
+import { lstat, readdir } from "node:fs/promises";
 import type { Dirent } from "node:fs";
-import { join, relative, sep } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 import { DEFAULT_IGNORE } from "./workspace.ts";
+import { gitBytes } from "./workspace-observation.ts";
 
 /**
- * Cap on indexed paths. Assumed, not measured: enough to fuzzy-search a
- * large repo; past this the picker is hiding a missing filter, not serving
- * one. Hitting it truncates and says so -- a silent cut would make @ miss
- * files that exist.
+ * Cap on paths from an unfiltered directory walk, outside Git. Assumed, not
+ * measured: enough to fuzzy-search a large tree; past this the walk is hiding
+ * a missing filter, not serving one. Hitting it truncates and says so -- a
+ * silent cut would make @ miss files that exist. A Git listing is already the
+ * filtered candidate set and is not capped unless the caller asks.
  */
 export const MAX_INDEX_ENTRIES = 20_000;
 
@@ -38,7 +47,79 @@ function isIgnored(rel: string, ignore: readonly string[]): boolean {
   return ignore.some((i) => parts.includes(i));
 }
 
+/** Git judges its own ignore rules; an error or a path outside any work tree is not ignored. */
+export async function gitIgnored(path: string, signal?: AbortSignal): Promise<boolean> {
+  try {
+    const info = await lstat(path);
+    await gitBytes(info.isDirectory() ? path : dirname(path), ["check-ignore", "-q", "--", path], undefined, signal);
+    return true;
+  } catch { return false; }
+}
+
+/** Git's listing under `dir`, relative to it, or null when `dir` is not a work tree that Git lists. */
+async function gitListing(dir: string, signal?: AbortSignal): Promise<string[] | null> {
+  try {
+    if (new TextDecoder().decode(await gitBytes(dir, ["rev-parse", "--is-inside-work-tree"], undefined, signal)).trim() !== "true") return null;
+    // Naming an ignored directory is an explicit request: walk it instead.
+    if (await gitIgnored(dir, signal)) return null;
+    const listed = new TextDecoder().decode(await gitBytes(dir, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], undefined, signal));
+    // An untracked nested repository is listed once, as "name/".
+    return [...new Set(listed.split("\0").filter(Boolean).map(path => path.replace(/\/$/, "")))].sort();
+  } catch { return null; }
+}
+
+/** Assumed: enough concurrent lstat calls to hide latency without exhausting descriptors. */
+const LSTAT_BATCH = 256;
+
+async function indexGitListing(root: string, listed: readonly string[], opts: IndexOptions): Promise<FileIndex> {
+  const ignore = opts.ignore ?? DEFAULT_IGNORE;
+  const max = opts.maxEntries ?? Infinity;
+  const paths: string[] = [], issues: { code: string; path?: string }[] = [];
+  // The index can name a path under a directory since replaced by a symlink;
+  // following it would read outside the tree, so every ancestor is checked once.
+  const directories = new Map<string, Promise<boolean>>([["", Promise.resolve(true)]]);
+  const plainDirectory = (rel: string): Promise<boolean> => {
+    let known = directories.get(rel);
+    if (known === undefined) {
+      const parent = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+      known = plainDirectory(parent).then(async ok => ok && await lstat(join(root, rel)).then(info => info.isDirectory() && !info.isSymbolicLink(), () => false));
+      directories.set(rel, known);
+    }
+    return known;
+  };
+  for (let offset = 0; offset < listed.length; offset += LSTAT_BATCH) {
+    if (opts.signal?.aborted || opts.deadline !== undefined && performance.now() >= opts.deadline) {
+      issues.push({ code: opts.signal?.aborted ? "cancelled" : "timeout" }); return { paths, truncated: true, issues };
+    }
+    const batch = listed.slice(offset, offset + LSTAT_BATCH).filter(rel => !isIgnored(rel.split("/").join(sep), ignore));
+    const kinds = await Promise.all(batch.map(async rel => {
+      const parent = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+      if (!await plainDirectory(parent)) return "skip";
+      // A tracked path deleted from the work tree is not a candidate.
+      const info = await lstat(join(root, rel)).catch(() => null);
+      return info === null || info.isSymbolicLink() ? "skip" : info.isDirectory() ? "nested" : info.isFile() ? "file" : "skip";
+    }));
+    for (let i = 0; i < batch.length; i++) {
+      const rel = batch[i]!;
+      if (kinds[i] === "nested") {
+        // A submodule or nested repository: its own listing, or a walk if it has none.
+        const nested = await buildFileIndex(join(root, rel), { ...opts, ...(max === Infinity ? {} : { maxEntries: max - paths.length }) });
+        paths.push(...nested.paths.map(path => `${rel}/${path}`));
+        issues.push(...(nested.issues ?? []).map(issue => issue.path === undefined ? issue : { ...issue, path: `${rel}/${issue.path}` }));
+        if (nested.truncated) return { paths, truncated: true, issues };
+        continue;
+      }
+      if (kinds[i] !== "file") continue;
+      if (paths.length >= max) { issues.push({ code: "file_index_limit" }); return { paths, truncated: true, issues }; }
+      paths.push(rel);
+    }
+  }
+  return { paths, truncated: false, ...(issues.length ? { issues } : {}) };
+}
+
 export async function buildFileIndex(root: string, opts: IndexOptions = {}): Promise<FileIndex> {
+  const listed = await gitListing(root, opts.signal);
+  if (listed !== null) return indexGitListing(root, listed, opts);
   const ignore = opts.ignore ?? DEFAULT_IGNORE;
   const max = opts.maxEntries ?? MAX_INDEX_ENTRIES;
   const paths: string[] = [];