@visual-z/xeno 0.7.2 → 0.8.1

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/openai.ts

@@ -23,7 +23,7 @@ import type { Message, ContentBlock, FrozenPrefix } from "../core/project.ts";
 import { imageData } from "./images.ts";
 import type { AssistantBlock } from "../core/events.ts";
 import { assertNever } from "../core/exhaustive.ts";
-import type { Provider, ProviderConfig, Turn, ToolSchema, OnDelta } from "./provider.ts";
+import { coherentTurn, type Provider, type ProviderConfig, type Turn, type ToolSchema, type OnDelta } from "./provider.ts";
 import { DEFAULT_COMPAT, type Compat, type Effort, type ModelSpec } from "./model.ts";
 import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
 import type { ProviderSendOptions } from "./provider-tool-policy.ts";
@@ -502,7 +502,7 @@ export class OpenAICompletionsProvider implements Provider {
     }
 
     const assembled = await readCompletionsSse(response.body, onDelta);
-    return parseResponse(assembled, node, Date.now() - started);
+    return coherentTurn(parseResponse(assembled, node, Date.now() - started), assembled.usage !== undefined);
   }
 }
 

package/src/runtime/pi-provider.ts

@@ -20,7 +20,7 @@ import { providerRequest } from "./provider-request.ts";
 import { grokVersionHint } from "./oauth.ts";
 import type { ResolveEffects } from "./auth.ts";
 import { imageData } from "./images.ts";
-import { FailedResponseError, type OnDelta, type Provider, type ProviderConfig, type ToolSchema, type Turn } from "./provider.ts";
+import { coherentTurn, FailedResponseError, type OnDelta, type Provider, type ProviderConfig, type ToolSchema, type Turn } from "./provider.ts";
 import { DEFAULT_RETRY, withRetry, type RetryPolicy } from "./retry.ts";
 import { HttpError, StreamError } from "./openai.ts";
 import type { UsageSample } from "./usage.ts";
@@ -392,7 +392,7 @@ export class PiProvider implements Provider {
     if (identityErrors.length) throw new ProviderIntegrityError(identityErrors, hasKnownUsage ? usage : undefined);
     // The SDK has already classified native STOP/end_turn/toolUse/length values. The loop consumes
     // xeno's closed completion vocabulary, never a raw native spelling that could skip tool execution.
-    return { blocks: piBlocks(completed, originalArguments.values), stopReason: completed.stopReason === "length" ? "max_tokens" : completed.stopReason === "toolUse" ? "tool_use" : "end_turn",
-      usage };
+    return coherentTurn({ blocks: piBlocks(completed, originalArguments.values), stopReason: completed.stopReason === "length" ? "max_tokens" : completed.stopReason === "toolUse" ? "tool_use" : "end_turn",
+      usage }, hasKnownUsage);
   }
 }

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/provider.ts

@@ -35,10 +35,12 @@ import type { Message, ContentBlock, FrozenPrefix } from "../core/project.ts";
 import { imageData } from "./images.ts";
 import type { AssistantBlock } from "../core/events.ts";
 import { assertNever } from "../core/exhaustive.ts";
+import { isToolStopWithoutCall } from "../core/response-recovery.ts";
 import type { UsageSample } from "./usage.ts";
 import { type Effort, type ModelSpec, CLAUDE_OPUS_5 } from "./model.ts";
 import { withRetry, DEFAULT_RETRY, type RetryPolicy } from "./retry.ts";
 import { anthropicOAuthHeaders } from "./oauth.ts";
+import { XENO_VERSION } from "./version.ts";
 import type { ProviderSendOptions } from "./provider-tool-policy.ts";
 
 export interface ToolSchema {
@@ -159,6 +161,27 @@ export class FailedResponseError extends Error {
   }
 }
 
+/**
+ * A 200 response that contradicts itself, such as a tool stop with no tool
+ * call. retry.ts treats it like a transient stream failure: a fresh sample is
+ * the remedy, and exhausting retries must surface as a provider error rather
+ * than reach the loop as a silent final answer. The output token count tells
+ * "generated but lost in transit" apart from "nothing generated".
+ */
+export class MalformedResponseError extends FailedResponseError {
+  constructor(detail: string, usage?: UsageSample) {
+    super(`malformed provider response: ${detail}${usage ? ` (${usage.output_tokens} output tokens)` : ""}`, usage);
+    this.name = "MalformedResponseError";
+  }
+}
+
+/** Every adapter returns through this, so no dialect can hand the loop a contradictory turn. */
+export function coherentTurn(turn: Turn, usageKnown = true): Turn {
+  if (isToolStopWithoutCall(turn.stopReason, turn.blocks))
+    throw new MalformedResponseError(`stop_reason ${JSON.stringify(turn.stopReason)} without a tool call`, usageKnown ? turn.usage : undefined);
+  return turn;
+}
+
 /** Thrown for a refusal, which arrives as HTTP 200 rather than an error. */
 export class RefusalError extends FailedResponseError {
   readonly category: string | null;
@@ -176,6 +199,12 @@ function buildAnthropicClient(
   apiKey: string | undefined,
   options: { fetch?: typeof fetch; oauth?: boolean; baseUrl?: string },
 ): AnthropicTransport {
+  // D18: the User-Agent, not SDK headers, identifies xeno on the wire. Left alone
+  // the SDK sends `Anthropic/JS <version>`, which model gateways fold into "custom
+  // client" attribution; provider-request.ts already stamps xeno's UA on the Pi
+  // path. Constructor defaultHeaders merge after the SDK's built-in UA, so this
+  // entry wins without touching per-request headers.
+  const identity = { "User-Agent": `xeno/${XENO_VERSION}` };
   if (options.oauth === true && apiKey) {
     // authToken is Bearer. Passing apiKey here would send x-api-key, which
     // an OAuth token is not accepted as.
@@ -183,7 +212,7 @@ function buildAnthropicClient(
       maxRetries: 0,
       ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
       authToken: apiKey,
-      defaultHeaders: anthropicOAuthHeaders(),
+      defaultHeaders: { ...anthropicOAuthHeaders(), ...identity },
       ...(options.fetch ? { fetch: options.fetch } : {}),
     });
   }
@@ -191,6 +220,7 @@ function buildAnthropicClient(
     maxRetries: 0,
     ...(options.baseUrl ? { baseURL: options.baseUrl } : {}),
     ...(apiKey ? { apiKey } : {}),
+    defaultHeaders: identity,
     ...(options.fetch ? { fetch: options.fetch } : {}),
   });
 }
@@ -319,11 +349,11 @@ export class AnthropicProvider implements Provider {
       throw new RefusalError(details?.category ?? null, details?.explanation ?? null, assembled.usageKnown ? usage : undefined);
     }
 
-    return {
+    return coherentTurn({
       blocks: assembled.blocks,
       stopReason: assembled.stopReason,
       usage,
-    };
+    }, assembled.usageKnown);
   }
 }
 

package/src/runtime/retry.ts

@@ -33,6 +33,11 @@ function isStreamFailure(error: unknown): error is Error & { code?: string } {
   return error instanceof Error && error.name === "StreamError";
 }
 
+/** provider.ts MalformedResponseError: a self-contradictory 200, structural for the same reason. */
+function isMalformedResponse(error: unknown): boolean {
+  return error instanceof Error && error.name === "MalformedResponseError";
+}
+
 export interface RetryPolicy {
   /**
    * Attempts after the first. Four means a request can take about 15s of
@@ -140,8 +145,10 @@ export function retryDecision(
   // A failure reported inside a 200 stream carries no status. Relays and
   // Anthropic's own `overloaded_error` use it for exactly the conditions a
   // 5xx would signal; anything else in a stream is a real rejection.
-  if (status === undefined && isStreamFailure(error)) {
-    if (!TRANSIENT_STREAM.test(`${error.code ?? ""} ${error.message}`)) {
+  if (status === undefined && (isStreamFailure(error) || isMalformedResponse(error))) {
+    // A contradictory response is a bad sample, not a rejection of the request:
+    // resend it like a dropped stream, and let the bound turn it into an error.
+    if (isStreamFailure(error) && !TRANSIENT_STREAM.test(`${error.code ?? ""} ${error.message}`)) {
       return { retry: false, reason: "the stream reported a non-transient error" };
     }
     const base = Math.min(0.5 * 2 ** attempt, 8) * 1000;

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/usage.ts

@@ -88,6 +88,34 @@ export function totalUsage(samples: readonly UsageSample[]): UsageTotals {
   return t;
 }
 
+/**
+ * Below this a request's speed is not shown: a response that returns at once
+ * (a test double, a local cache) would divide into thousands of tokens per
+ * second. Assumed, not measured.
+ */
+export const SPEED_MIN_MS = 250;
+
+/**
+ * Output tokens per second over a set of model requests, or undefined when
+ * none can be measured (feat-sidebar-goal-and-speed). OpenCode's built-in
+ * turnTokensPerSecond uses the same definition: output over the time the
+ * requests took, each request counted once. Not output over the time since
+ * the first visible output -- output counts include reasoning that providers
+ * do not always stream (OpenAI summaries arrive late, Anthropic can omit
+ * them), so that would keep reasoning tokens and drop reasoning time, and
+ * overstate. Whole request time never overstates; an overloaded upstream
+ * reads slow, which is what the user is waiting on.
+ */
+export function generationSpeed(samples: readonly UsageSample[]): number | undefined {
+  let tokens = 0, ms = 0;
+  for (const sample of samples) {
+    if (sample.output_tokens <= 0 || !(sample.ms >= SPEED_MIN_MS)) continue;
+    tokens += sample.output_tokens;
+    ms += sample.ms;
+  }
+  return ms > 0 ? tokens / (ms / 1000) : undefined;
+}
+
 /**
  * Cost in equivalent base-input tokens, the unit appendix A's model uses.
  *

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;