@visual-z/xeno 0.1.0

package/src/core/benchmark.ts

@@ -0,0 +1,195 @@
+/** Evaluation contracts, separate from production policies (research M.3). */
+import { shuffled } from "./experiment.ts";
+
+export const LONGBENCH_SOURCE = {
+  revision: "2b48e494f2c7a2f0af81aae178e05c7e1dde0fe9",
+  sha256: "15d61c22d92c96900b3c4948b6aeea218d3214b676a65df48e7b8555604c7fe2",
+  scorerRevision: "2e00731f8d0bff23dc4325161044d0ed8af94c1e",
+} as const;
+
+export const BENCHMARK_ARMS = ["node", "replay", "mask"] as const;
+export type BenchmarkArm = typeof BENCHMARK_ARMS[number];
+export type Choice = "A" | "B" | "C" | "D";
+export interface BenchmarkItem {
+  _id: string;
+  domain: string;
+  sub_domain: string;
+  difficulty: "easy" | "hard";
+  length: "short" | "medium" | "long";
+  question: string;
+  choice_A: string;
+  choice_B: string;
+  choice_C: string;
+  choice_D: string;
+  answer: Choice;
+  context: string;
+}
+
+function isBenchmarkItem(value: unknown): value is BenchmarkItem {
+  if (typeof value !== "object" || value === null) return false;
+  const row = value as Record<string, unknown>;
+  for (const key of ["_id", "domain", "sub_domain", "question", "choice_A", "choice_B", "choice_C", "choice_D", "context"]) {
+    if (typeof row[key] !== "string" || row[key].length === 0) return false;
+  }
+  return (row["answer"] === "A" || row["answer"] === "B" || row["answer"] === "C" || row["answer"] === "D") &&
+    (row["difficulty"] === "easy" || row["difficulty"] === "hard") &&
+    (row["length"] === "short" || row["length"] === "medium" || row["length"] === "long");
+}
+
+export function parseBenchmark(data: unknown): BenchmarkItem[] {
+  if (!Array.isArray(data) || data.length === 0) throw new Error("empty or invalid benchmark");
+  const ids = new Set<string>();
+  return data.map((item: unknown) => {
+    if (!isBenchmarkItem(item)) throw new Error("invalid benchmark item");
+    if (ids.has(item._id)) throw new Error(`duplicate benchmark id: ${item._id}`);
+    ids.add(item._id);
+    return item;
+  });
+}
+
+/** Exact LongBench v2 pred.py extraction, pinned in docs/benchmarks.md (MIT). */
+export function extractBenchmarkAnswer(response: string): Choice | null {
+  const plain = response.replaceAll("*", "");
+  return (plain.match(/The correct answer is \(([A-D])\)/)?.[1] ??
+    plain.match(/The correct answer is ([A-D])/)?.[1] ?? null) as Choice | null;
+}
+
+/** Domain-balanced sampling; neither correctness nor answer labels enter selection. */
+export function sampleBenchmark(items: readonly BenchmarkItem[], count: number, seed: number): BenchmarkItem[] {
+  if (!Number.isSafeInteger(count) || count < 1 || count > items.length) throw new RangeError("invalid sample count");
+  const domains = [...new Set(items.map((item) => item.domain))].sort();
+  const buckets = shuffled(domains, seed).map((domain, index) => shuffled(
+    items.filter((item) => item.domain === domain).toSorted((a, b) => a._id.localeCompare(b._id)), seed + index + 1,
+  ));
+  const out: BenchmarkItem[] = [];
+  for (let round = 0; out.length < count; round++) {
+    for (const bucket of buckets) {
+      const item = bucket[round];
+      if (item !== undefined && out.length < count) out.push(item);
+    }
+  }
+  return out;
+}
+
+export interface BenchmarkJob { id: string; arm: BenchmarkArm }
+export type HarnessProfile = "control" | "enhanced";
+export interface HarnessJob { id: string; arm: "node" | "replay"; profile: HarnessProfile }
+
+/** A Latin rotation balances each treatment's position before running any model. */
+export function harnessSchedule(items: readonly BenchmarkItem[], seed: number): HarnessJob[] {
+  const treatments = shuffled([
+    { arm: "node", profile: "control" }, { arm: "replay", profile: "control" },
+    { arm: "node", profile: "enhanced" }, { arm: "replay", profile: "enhanced" },
+  ] as const, seed);
+  const offsets = shuffled(items.map((_, index) => index % treatments.length), seed + 1);
+  return items.flatMap((item, index) => treatments.map((_, position) => ({
+    id: item._id, ...treatments[(position + offsets[index]!) % treatments.length]!,
+  })));
+}
+
+export function summarizeHarness(plan: readonly HarnessJob[], results: readonly (BenchmarkOutcome & { profile: HarnessProfile })[]) {
+  return (["control", "enhanced"] as const).flatMap((profile) => summarizeBenchmark(
+    plan.filter((job) => job.profile === profile), results.filter((result) => result.profile === profile),
+  ).filter((row) => row.planned > 0).map((row) => ({ profile, ...row })));
+}
+/** Pair nearby in time, randomize treatment order inside each task, once before running. */
+export function benchmarkSchedule(items: readonly BenchmarkItem[], seed: number): BenchmarkJob[] {
+  // Balance all six orders before shuffling. Adjacent LCG seeds yield correlated
+  // first draws and can accidentally put the same arm last in every block.
+  const orders: readonly (readonly BenchmarkArm[])[] = [
+    ["node", "replay", "mask"], ["node", "mask", "replay"], ["replay", "node", "mask"],
+    ["replay", "mask", "node"], ["mask", "node", "replay"], ["mask", "replay", "node"],
+  ];
+  const balanced = shuffled(items.map((_, index) => orders[index % orders.length]!), seed);
+  return items.flatMap((item, index) => balanced[index]!.map((arm) => ({ id: item._id, arm })));
+}
+
+/** Split losslessly, including surrogate pairs; chunks are files, not a context truncation. */
+export function benchmarkChunks(context: string, size = 16_000): string[] {
+  if (!Number.isSafeInteger(size) || size < 2) throw new RangeError("chunk size must be at least two");
+  const chunks: string[] = [];
+  for (let start = 0; start < context.length;) {
+    let end = Math.min(context.length, start + size);
+    const last = context.charCodeAt(end - 1);
+    if (end < context.length && last >= 0xd800 && last <= 0xdbff) end--;
+    chunks.push(context.slice(start, end));
+    start = end;
+  }
+  return chunks;
+}
+
+/** Explicit field selection prevents evaluator-only metadata from leaking to the agent. */
+export function benchmarkPrompt(item: BenchmarkItem, chunks: number): string {
+  return `Answer the question using the complete source document in corpus/part-00000.txt through corpus/part-${String(chunks - 1).padStart(5, "0")}.txt. ` +
+    "The numbered files concatenate in order to the original document; none of it was removed. Use read and grep to examine the evidence.\n\n" +
+    `Question: ${item.question}\nChoices:\n(A) ${item.choice_A}\n(B) ${item.choice_B}\n(C) ${item.choice_C}\n(D) ${item.choice_D}\n\n` +
+    'Format your final response as follows: "The correct answer is (insert answer here)".';
+}
+
+export interface BenchmarkPrice { input: number; output: number; cacheRead: number }
+export interface BenchmarkUsage { input_tokens: number; output_tokens: number; cache_read_input_tokens: number; cache_creation_input_tokens: number }
+
+/** A conservative allowance, not a tokenizer: wire bytes plus framing, at uncached peak rates. */
+export function requestReservation(wireBytes: number, maxOutput: number, price: BenchmarkPrice): number {
+  if (!Number.isSafeInteger(wireBytes) || wireBytes < 0 || !Number.isSafeInteger(maxOutput) || maxOutput < 1) throw new RangeError("invalid request size");
+  return ((wireBytes + 4096) * price.input + maxOutput * price.output) / 1_000_000;
+}
+
+export function measuredCharge(usage: BenchmarkUsage, price: BenchmarkPrice): number | null {
+  const counts = [usage.input_tokens, usage.output_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens];
+  if (counts.some((value) => !Number.isSafeInteger(value) || value < 0) ||
+      usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens === 0 || usage.output_tokens === 0) return null;
+  return ((usage.input_tokens + usage.cache_creation_input_tokens) * price.input +
+    usage.cache_read_input_tokens * price.cacheRead + usage.output_tokens * price.output) / 1_000_000;
+}
+
+export function canReserve(charged: number, reserve: number, budget: number): boolean {
+  if (![charged, reserve, budget].every(Number.isFinite) || charged < 0 || reserve <= 0 || budget <= 0) return false;
+  return charged + reserve <= budget;
+}
+
+/** Unknown outcomes keep their reservation; an unexpectedly high bill is never clipped. */
+export function settledCharge(reserve: number, measured: number | null): number {
+  return measured === null ? reserve : measured;
+}
+
+export function wilsonInterval(correct: number, total: number): [number, number] | null {
+  if (!Number.isSafeInteger(total) || !Number.isSafeInteger(correct) || correct < 0 || total < correct) throw new RangeError("invalid score");
+  if (total === 0) return null;
+  const z = 1.959963984540054;
+  const p = correct / total;
+  const d = 1 + z * z / total;
+  const center = (p + z * z / (2 * total)) / d;
+  const radius = z * Math.sqrt(p * (1 - p) / total + z * z / (4 * total * total)) / d;
+  return [Math.max(0, center - radius), Math.min(1, center + radius)];
+}
+
+export interface BenchmarkOutcome {
+  id: string;
+  arm: BenchmarkArm;
+  status: "answered" | "error" | "budget" | "stopped";
+  correct: boolean;
+}
+
+export function summarizeBenchmark(plan: readonly BenchmarkJob[], outcomes: readonly BenchmarkOutcome[]) {
+  const planned = new Set(plan.map((job) => `${job.id}/${job.arm}`));
+  const seen = new Set<string>();
+  for (const outcome of outcomes) {
+    const key = `${outcome.id}/${outcome.arm}`;
+    if (!planned.has(key) || seen.has(key)) throw new Error("unknown or duplicate benchmark outcome");
+    if (outcome.correct && outcome.status !== "answered") throw new Error("unfinished result cannot be correct");
+    seen.add(key);
+  }
+  return BENCHMARK_ARMS.map((arm) => {
+    const rows = outcomes.filter((row) => row.arm === arm);
+    const total = plan.filter((job) => job.arm === arm).length;
+    const correct = rows.filter((row) => row.correct).length;
+    const attempted = rows.length;
+    const answered = rows.filter((row) => row.status === "answered").length;
+    return { arm, planned: total, attempted, answered, correct, missing: total - attempted,
+      accuracy: attempted > 0 ? correct / attempted : null,
+      interval95: wilsonInterval(correct, attempted),
+      plannedSolvedFraction: total > 0 ? correct / total : null,
+      complete: attempted === total };
+  });
+}

package/src/core/boundary.ts

@@ -0,0 +1,174 @@
+/**
+ * Explicit fixed-segment policy (decisions D1, D4, D5; new default in N.8).
+ *
+ * Pure. Given a token count and where the loop currently stands, decide whether
+ * to close the segment.
+ *
+ * Three rules, each with a reason:
+ *
+ *   ONLY AT A TURN BOUNDARY (D5). A cut between a tool_use and its tool_result
+ *   would produce an unpairable request. The gap between trigger and hard limit is
+ *   the headroom that makes waiting for the boundary safe.
+ *
+ *   THE MODEL MAY ADVANCE A CUT BUT NEVER DEFER ONE (D4). A checkpoint request at
+ *   a clean semantic boundary is usually better than an arbitrary threshold, so it
+ *   is honoured -- but the hard limit is checked first and cannot be overridden.
+ *
+ *   ABSOLUTE TOKENS, NOT A PERCENTAGE OF THE WINDOW. Cost and quality both argue
+ *   for tens of thousands of tokens, and neither argument scales with whatever
+ *   window the model happens to advertise.
+ *
+ * On the defaults below: the optimum from the cost model is L - H = 5*sqrt(H*d),
+ * where H is handoff size and d is per-turn growth. H was originally *assumed* to
+ * be ~10k, which put the optimum near 37k and the thresholds at 60k/80k.
+ * The original single-segment measurement (prev=null) yielded 366 to 3201
+ * tokens, 1.6-7.6% of L. It did not measure accumulation across boundaries.
+ * D20 adds bounded carried state and continuous-history measurements; full
+ * derivation state still grows with distinct facts. The old local cost optimum
+ * is a workload diagnostic, not proof of a globally optimal threshold.
+ *
+ * The defaults are 30k/40k rather than 15k/25k because the cost model prices only
+ * bytes. Two things it does not price argue for longer segments: the re-read a new
+ * segment usually needs before it can act (the digest check on file_anchors), and
+ * the fact that too-short segments break stateful work -- the documented failure
+ * mode of fresh-context loops is that extended debugging loses context that was
+ * load-bearing. 30k/40k is within 15% of the cost optimum for every re-read cost
+ * from 0 to 24k tokens per boundary, which 60k/80k is not.
+ */
+
+import type { CutReason } from "./events.ts";
+
+export interface BoundaryConfig {
+  /** Start looking for a turn boundary at or above this count. */
+  triggerTokens: number;
+  /** Cut at the next turn boundary regardless. Must exceed triggerTokens. */
+  hardTokens: number;
+  /**
+   * How much of the context a node must have produced itself before cutting is
+   * worth it.
+   *
+   * Every node starts with tokens it did not create: the frozen prefix plus,
+   * after the first cut, the handoff. Without this floor, a trigger set below
+   * that inherited weight makes the first turn of every node cut -- a real run
+   * produced 36 nodes for a five-file task, spending its budget on handoffs.
+   *
+   * The value follows the crossover: a handoff only pays for itself once the
+   * node's own history exceeds it. Measured handoffs ran 366-3201 tokens, so
+   * the default sits above the top of that range.
+   *
+   * This is also the floor for a model-requested checkpoint. A separate knob
+   * for that case would be the same idea written twice: a checkpoint on a node
+   * that has produced nothing costs a handoff write and discards the node's
+   * cache for no gain, which is exactly what this floor exists to prevent.
+   */
+  minNodeWorkTokens: number;
+}
+
+export const DEFAULT_BOUNDARY: BoundaryConfig = {
+  triggerTokens: 30_000,
+  hardTokens: 40_000,
+  minNodeWorkTokens: 5_000,
+};
+
+export interface BoundaryInput {
+  tokens: number;
+  /**
+   * Tokens the node did not produce: the frozen prefix, plus the rendered
+   * handoff for any node after the first. Cutting cannot reduce these, so they
+   * do not count toward the node having earned a boundary.
+   */
+  inheritedTokens?: number;
+  /** True only between a completed assistant/tool exchange and the next request. */
+  atTurnBoundary: boolean;
+  /** Set when the model called the checkpoint tool during this turn. */
+  checkpointRequested?: boolean;
+  config?: Partial<BoundaryConfig>;
+}
+
+export type BoundaryDecision =
+  | { cut: true; reason: CutReason }
+  | {
+      cut: false;
+      reason:
+        | "below_trigger"
+        | "awaiting_turn_boundary"
+        | "below_min_node_work"
+        /**
+         * The inherited floor alone is at or past the hard limit, so a cut
+         * would hand the next node a context it cannot work in either. The
+         * thresholds need widening or the frozen prefix shrinking; cutting
+         * would only thrash.
+         */
+        | "inherited_floor_exceeds_limit";
+      /**
+       * True when the count is already past the hard limit and a cut is not yet
+       * possible -- i.e. a single turn consumed more than the headroom. The caller
+       * should surface this: the thresholds need retuning, or one tool returned an
+       * output large enough to need its own handling.
+       */
+      overrun: boolean;
+    };
+
+export function shouldCut(input: BoundaryInput): BoundaryDecision {
+  const cfg = { ...DEFAULT_BOUNDARY, ...input.config };
+  if (cfg.hardTokens <= cfg.triggerTokens) {
+    throw new RangeError(
+      `boundary: hardTokens (${cfg.hardTokens}) must exceed triggerTokens (${cfg.triggerTokens}); ` +
+        "the difference is the headroom needed to reach a turn boundary",
+    );
+  }
+  // The mirror of thrashing, and just as silent: a work floor at or above the
+  // trigger means the trigger can never be acted on, so the session grows
+  // without bound and nothing says why.
+  if (cfg.minNodeWorkTokens >= cfg.triggerTokens) {
+    throw new RangeError(
+      `boundary: minNodeWorkTokens (${cfg.minNodeWorkTokens}) must be below triggerTokens ` +
+        `(${cfg.triggerTokens}); otherwise no node can ever reach a boundary`,
+    );
+  }
+
+  const { tokens, atTurnBoundary, checkpointRequested = false, inheritedTokens = 0 } = input;
+  const ownWork = Math.max(0, tokens - inheritedTokens);
+
+  if (!atTurnBoundary) {
+    return {
+      cut: false,
+      reason: "awaiting_turn_boundary",
+      overrun: tokens >= cfg.hardTokens,
+    };
+  }
+
+  // Is there any reason to consider a boundary at all?
+  const wouldCut =
+    tokens >= cfg.hardTokens || checkpointRequested || tokens >= cfg.triggerTokens;
+  if (!wouldCut) return { cut: false, reason: "below_trigger", overrun: false };
+
+  // There is -- but a node that has produced almost nothing cannot be helped
+  // by one: the next node inherits the same floor and lands in the same place.
+  if (ownWork < cfg.minNodeWorkTokens) {
+    if (inheritedTokens >= cfg.hardTokens) {
+      return { cut: false, reason: "inherited_floor_exceeds_limit", overrun: true };
+    }
+    return { cut: false, reason: "below_min_node_work", overrun: tokens >= cfg.hardTokens };
+  }
+
+  // Worth cutting. The hard limit is checked first so the model cannot defer
+  // it by asking for a checkpoint.
+  if (tokens >= cfg.hardTokens) return { cut: true, reason: "hard_limit" };
+  if (checkpointRequested) return { cut: true, reason: "model_checkpoint" };
+  return { cut: true, reason: "trigger" };
+}
+
+/**
+ * Stop-and-ask rule (D9 / M.4). New read observations or fresh successful checks
+ * reset the counter. Exact repetitions, annotations alone and gate regressions
+ * do not. This detects inactivity; it cannot judge relevance to the user's goal.
+ */
+export const DEFAULT_MAX_SEGMENTS_WITHOUT_PROGRESS = 3;
+
+export function shouldStopAndAsk(
+  segmentsWithoutProgress: number,
+  max = DEFAULT_MAX_SEGMENTS_WITHOUT_PROGRESS,
+): boolean {
+  return segmentsWithoutProgress >= max;
+}

package/src/core/churn.ts

@@ -0,0 +1,59 @@
+/**
+ * Two loops the repetition check cannot see.
+ *
+ * `continuationGuidance` flags an action/observation cycle that repeats
+ * exactly. A real rut rarely does: a rerun test prints a new timestamp, a
+ * build a new temp path, and every observation digest differs -- so neither
+ * that check nor D9 stall counting fires while the model retries one idea.
+ * These two keys come from facts the harness recorded itself, not from
+ * comparing output: the exact command with its exit code, and the path of
+ * each successful edit (LangChain's harness write-up uses the same edit
+ * count; opencode's doom_loop misses exactly these near-repeats).
+ *
+ * Advice only, once per request: nothing is blocked and the stop rules are
+ * unchanged.
+ */
+import type { GuidanceEvent, LogEvent } from "./events.ts";
+
+/**
+ * Assumed, not measured. Three failures leaves room for "change, retry,
+ * still failing" -- normal debugging -- before calling it a loop; eight edits
+ * of one file sits above a typical refactor. Too low costs one extra notice;
+ * too high falls back to today's behaviour.
+ */
+export const CHURN_FAILURES = 3;
+export const CHURN_EDITS = 8;
+
+export function churnReview(events: readonly LogEvent[]): Pick<GuidanceEvent, "reason" | "text" | "sources"> | null {
+  const start = events.findLastIndex((event) => event.t === "user");
+  const current = events.slice(Math.max(0, start));
+  if (current.some((event) => event.t === "guidance" && event.reason === "churn")) return null;
+  const failures = new Map<string, { count: number; last: string }>();
+  const edits = new Map<string, { count: number; last: string }>();
+  for (const event of current) {
+    if (event.t !== "tool_result" || event.effect === undefined) continue;
+    const effect = event.effect;
+    if (effect.kind === "command") {
+      const key = effect.cmd.trim();
+      if (effect.exit === 0) { failures.delete(key); continue; }
+      const seen = { count: (failures.get(key)?.count ?? 0) + 1, last: event.id };
+      failures.set(key, seen);
+      if (seen.count >= CHURN_FAILURES) return {
+        reason: "churn", sources: [event.id],
+        text: `Harness: \`${key}\` failed ${seen.count} times in this request without succeeding. ` +
+          "Retrying the same approach is unlikely to change the result. Read the end of the last failure, " +
+          "state the cause you believe it has, and test that belief with a different step before running it again.",
+      };
+    } else if (effect.kind === "edit") {
+      const seen = { count: (edits.get(effect.path)?.count ?? 0) + 1, last: event.id };
+      edits.set(effect.path, seen);
+      if (seen.count >= CHURN_EDITS) return {
+        reason: "churn", sources: [event.id],
+        text: `Harness: ${effect.path} was edited ${seen.count} times in this request. ` +
+          "Repeated small edits usually mean the underlying cause is not yet understood. Re-read the file and the " +
+          "failing evidence, then make one change that addresses the cause.",
+      };
+    }
+  }
+  return null;
+}

package/src/core/completion-review.ts

@@ -0,0 +1,66 @@
+/**
+ * A one-time reconciliation when the model ends a request.
+ *
+ * The model deciding it is done is a claim like any other (D11), and the
+ * failure modes that end a Terminal-Bench run early all look like a normal
+ * final reply: an edit nobody ran, a question handed back to a user who is
+ * not there, or nothing at all. ForgeCode found a programmatic check at this
+ * point was its largest single gain and that a prompt instruction alone did
+ * not reproduce it. The check here only appends a notice; the model still
+ * decides, and a second finish is respected -- an honest blocker must not
+ * turn into a loop.
+ */
+import type { GuidanceEvent, LogEvent } from "./events.ts";
+
+/**
+ * Wording that hands the task back instead of finishing it. Ported from
+ * waner `crates/waner_core/src/turn/premature_stop.rs`, including its window:
+ * the first 400 and last 300 characters, where an opening refusal or a
+ * closing offer sits. The same words in the middle of a long report are
+ * usually a quotation or a description, not a stop.
+ */
+const HAND_BACK = [
+  "i can't proceed", "i cannot proceed", "i can't continue", "i cannot continue",
+  "giving up", "stopping here", "unable to complete", "i'm unable to", "i am unable to",
+  "let me know if you", "would you like me to", "do you want me to", "shall i ",
+  "我无法继续", "无法完成", "需要你确认", "请确认是否", "是否需要我", "要不要我",
+];
+
+export function looksLikeHandBack(text: string): boolean {
+  const chars = [...text.trim()];
+  const window = `${chars.slice(0, 400).join("")}\n${chars.slice(Math.max(0, chars.length - 300)).join("")}`.toLowerCase();
+  return HAND_BACK.some((pattern) => window.includes(pattern));
+}
+
+export function completionReview(
+  events: readonly LogEvent[],
+  remainingRequests: number,
+): Pick<GuidanceEvent, "reason" | "text" | "sources"> | null {
+  if (remainingRequests < 1) return null;
+  const start = events.findLastIndex((event) => event.t === "user");
+  if (start < 0) return null;
+  const current = events.slice(start);
+  if (current.some((event) => event.t === "guidance" && event.reason === "completion_review")) return null;
+  const final = current.findLast((event) => event.t === "assistant");
+  if (final?.t !== "assistant" || final.blocks.some((block) => block.type === "tool_use")) return null;
+
+  const text = final.blocks.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n").trim();
+  const usedTools = current.some((event) => event.t === "tool_result");
+  const lastEdit = current.findLastIndex((event) => event.t === "tool_result" && event.effect?.kind === "edit");
+  const verifiedAfter = lastEdit >= 0 && current.slice(lastEdit + 1)
+    .some((event) => event.t === "tool_result" && event.effect?.kind === "command" && event.effect.exit === 0);
+
+  const gaps: string[] = [];
+  if (usedTools && text.length === 0) gaps.push("the final reply is empty");
+  if (lastEdit >= 0 && !verifiedAfter) gaps.push("files were changed but no command has succeeded since the last edit");
+  if (text.length > 0 && looksLikeHandBack(text)) gaps.push("the reply handed the task back instead of finishing it; no one will answer");
+  if (gaps.length === 0) return null;
+  return {
+    reason: "completion_review",
+    sources: [current[0]!.id, final.id],
+    text: `Harness completion check: ${gaps.join("; ")}. ` +
+      `Re-read the original request (event ${current[0]!.id}) and check each requirement against evidence in this session. ` +
+      "Run the command that verifies the result, or finish with the specific blocker that prevents verification. " +
+      "This check runs once per request.",
+  };
+}

package/src/core/context-policy.ts

@@ -0,0 +1,60 @@
+/** N.6: log ownership is independent of the policy that replaces its context view. */
+import { shouldCut, type BoundaryDecision, type BoundaryInput } from "./boundary.ts";
+import { windowBudget } from "./context-window.ts";
+
+export const CONTEXT_POLICIES = ["segmented", "continuous", "adaptive", "windowed"] as const;
+export type ContextPolicy = typeof CONTEXT_POLICIES[number];
+export const DEFAULT_CONTEXT_POLICY: ContextPolicy = "windowed";
+export function isContextPolicy(value: unknown): value is ContextPolicy {
+  return typeof value === "string" && (CONTEXT_POLICIES as readonly string[]).includes(value);
+}
+
+export interface BoundaryCost { keepUsd: number; rebuildUsd: number }
+/**
+ * A one-request input-cost estimate, NOT a forecast of task cost or quality.
+ * Reuse only the last observed cached token count; price all new input and the
+ * entire replacement cold. This deliberately does not assume a cache hit on the
+ * unchanged system prefix, future cache persistence, or free evidence recovery.
+ */
+export function estimateBoundaryCost(input: {
+  retainedTokens: number; rebuiltTokens: number; observedCachedTokens: number;
+  inputPrice: number; cacheReadPrice: number; cacheWritePrice: number;
+}): BoundaryCost | null {
+  if (Object.values(input).some((value) => !Number.isFinite(value) || value < 0)) return null;
+  const cold = Math.max(input.inputPrice, input.cacheWritePrice);
+  const cached = Math.min(input.retainedTokens, input.observedCachedTokens);
+  const cost = { keepUsd: (cached * input.cacheReadPrice + (input.retainedTokens - cached) * cold) / 1_000_000,
+    rebuildUsd: input.rebuiltTokens * cold / 1_000_000 };
+  return Object.values(cost).every(Number.isFinite) ? cost : null;
+}
+
+export type ContextDecision = BoundaryDecision | { cut: false; overrun: boolean;
+  reason: "continuous" | "awaiting_continuation" | "unknown_cost" | "preserving_cache" };
+
+export function decideContext(input: BoundaryInput & {
+  policy: ContextPolicy; continuationReady: boolean; cost: BoundaryCost | null;
+  contextWindow?: number; outputReserve?: number;
+}): ContextDecision {
+  if (!isContextPolicy(input.policy)) throw new Error("unknown context policy");
+  if (input.policy === "continuous") return { cut: false, reason: "continuous", overrun: false };
+  if (input.policy === "windowed") {
+    const budget = windowBudget(input.contextWindow, input.outputReserve ?? 0);
+    if (budget !== null) {
+      if (!input.atTurnBoundary) return { cut: false, reason: "awaiting_turn_boundary", overrun: input.tokens > budget.usable };
+      if (input.tokens < budget.trigger) return { cut: false, reason: "below_trigger", overrun: false };
+      if ((input.inheritedTokens ?? 0) >= budget.trigger) return { cut: false, reason: "inherited_floor_exceeds_limit", overrun: true };
+      return { cut: true, reason: input.tokens > budget.usable ? "hard_limit" : "trigger" };
+    }
+    // Unknown capacity is not an infinite window. Keep the explicit legacy bounds.
+    return shouldCut(input);
+  }
+  const baseline = shouldCut(input);
+  if (input.policy === "segmented" || !baseline.cut || baseline.reason !== "trigger") return baseline;
+  // Readiness and price may defer a soft trigger; neither can veto the hard limit.
+  if (!input.continuationReady) return { cut: false, reason: "awaiting_continuation", overrun: false };
+  if (input.cost === null || Object.values(input.cost).some((value) => !Number.isFinite(value) || value < 0)) {
+    return { cut: false, reason: "unknown_cost", overrun: false };
+  }
+  if (input.cost.rebuildUsd >= input.cost.keepUsd) return { cut: false, reason: "preserving_cache", overrun: false };
+  return baseline;
+}

package/src/core/context-window.ts

@@ -0,0 +1,54 @@
+/** N.8: window pressure changes the projection, never the durable transcript. */
+import type { LogEvent } from "./events.ts";
+import type { Handoff } from "./handoff.ts";
+import { projectContext, type FrozenPrefix } from "./project.ts";
+import type { TokenCounter } from "./tokens.ts";
+
+export interface WindowBudget { usable: number; prepare: number; trigger: number; target: number }
+export function windowBudget(window: number | undefined, outputReserve: number): WindowBudget | null {
+  if (window === undefined) return null;
+  if (!Number.isSafeInteger(window) || window <= 0 || !Number.isSafeInteger(outputReserve) || outputReserve < 0) {
+    throw new RangeError("context window and output reserve must be finite token counts");
+  }
+  const usable = Math.max(0, window - outputReserve);
+  // Assumptions, not measured optima: 20% headroom absorbs estimator/tool growth;
+  // half a window after a cut prevents repeated cold rebuilds. See N.8.
+  return { usable, prepare: Math.floor(usable * 0.7), trigger: Math.floor(usable * 0.8), target: Math.floor(usable * 0.5) };
+}
+
+/** Resolve a suffix on the effective ancestry; a bad reference never means empty history. */
+export function retainedContext(events: readonly LogEvent[], from: string): LogEvent[] {
+  const index = events.findIndex((event) => event.id === from);
+  if (index < 0) throw new Error(`MISSING_RETAINED_EVENT: ${from}`);
+  const first = events[index]!;
+  if (first.t !== "assistant" && first.t !== "user") throw new Error(`INVALID_RETAINED_BOUNDARY: ${from}`);
+  const retained = events.slice(index).filter((event) => event.t !== "cut");
+  const projection = projectContext({ frozen: { system: "", tools: [] }, handoff: null, events: retained });
+  if (projection.violations.length > 0) throw new Error(`UNPAIRED_RETAINED_CONTEXT: ${from}`);
+  return retained;
+}
+
+/** Pi keeps recent exchanges; here they stay references into the original log (D8). */
+export function selectRecentContext(input: {
+  events: readonly LogEvent[]; frozen: FrozenPrefix; handoff: Handoff; counter: TokenCounter;
+  targetTokens: number; requiredUserId?: string;
+}): { from: string; tokens: number } | null {
+  const { events, frozen, handoff, counter, targetTokens, requiredUserId } = input;
+  const required = requiredUserId === undefined ? events.length : events.findIndex((event) => event.id === requiredUserId);
+  if (required < 0) throw new Error("missing required user request");
+  let result: { from: string; tokens: number } | null = null;
+  // The 20k recent-history cap is a conservative starting point borrowed from
+  // Pi, not a semantic guarantee. The full replacement must also fit target.
+  const floor = projectContext({ frozen, handoff, events: [] });
+  const limit = Math.min(targetTokens, counter.count(floor.messages, floor.system, frozen.tools) + 20_000);
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i]!;
+    if (event.t !== "assistant" && event.t !== "user") continue;
+    const projection = projectContext({ frozen, handoff, events: events.slice(i) });
+    if (projection.violations.length > 0) continue;
+    const tokens = counter.count(projection.messages, projection.system, frozen.tools);
+    if (tokens > limit) break;
+    if (i <= required) result = { from: event.id, tokens };
+  }
+  return result;
+}