@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/model-script.ts

@@ -0,0 +1,351 @@
+/**
+ * A scripted model, for the Tier-1 evals.
+ *
+ * The replay seams (`submission-replay.ts`, `lessons/replay.ts`) feed recorded
+ * results into one hook each, which is enough when the thing under test is the
+ * hook. The evidence gate is different: what it judges is a model's edit to
+ * the notebook, and the deny that matters is the one pi's own `tool_call` path
+ * honours -- every other tool_call handler running first, the exec-guard
+ * floor, the write landing or not. A replay can't show that. This seam puts a
+ * model in the loop that says exactly what a script tells it to, using pi's
+ * faux provider, so pi's agent loop, its tools and every Orbit hook run as they
+ * do with a real model.
+ *
+ * `ORBIT_MODEL_SCRIPT` names a JSONL file, one model turn per line, in order:
+ *
+ * ```json
+ * {"tool": "galaxy_invocation_check_all", "input": {}, "text": "Checking the run first."}
+ * {"tool": "edit", "input": {"path": "notebook.md", "edits": [{"oldText": "...", "newText": "..."}]}}
+ * {"text": "Step 1 is verified."}
+ * ```
+ *
+ * A tool line ends its turn with `toolUse`, so pi runs the call and asks for
+ * the next turn; a text line ends it with `stop`, which ends the prompt -- so
+ * text meant to come before a call goes on the call's line. A script that runs out
+ * answers every later turn with an empty `stop`, which ends the prompt cleanly
+ * rather than with the faux provider's "no more responses" error.
+ *
+ * Same constraints as the replay seams: off unless the variable is set (and
+ * nothing registers otherwise), the file must resolve inside the session
+ * directory, and a `model.script` activity row is written before the first
+ * turn, so a log produced this way says so. Two more, because this one stands
+ * in for the model:
+ *
+ * - the file is read once per process, at the first session start, through
+ *   one descriptor on a regular file, so nothing the scripted session does --
+ *   a write to the script, a tool result, a notebook edit, `/new` -- can add
+ *   lines to it;
+ * - when the variable is set, the scripted model is selected whether or not
+ *   the file was usable, moved back to if anything selects another, and any
+ *   request that reaches a real provider anyway is aborted and logged.
+ *   `team_dispatch`, which calls a model directly, refuses to run.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  fauxAssistantMessage,
+  fauxProvider,
+  fauxText,
+  fauxToolCall,
+  type AssistantMessage,
+  type FauxContentBlock,
+  type FauxProviderHandle,
+  type ToolCall,
+} from "@earendil-works/pi-ai";
+import * as fs from "fs";
+import * as path from "path";
+import { readEnv } from "../../shared/orbit-env.js";
+import { appendActivityEvent } from "./activity";
+import { getNotebookPath } from "./state";
+
+export const MODEL_SCRIPT_PROVIDER = "loom-script";
+export const MODEL_SCRIPT_MODEL_ID = "scripted";
+
+export interface ScriptTurn {
+  text?: string;
+  tool?: string;
+  input?: Record<string, unknown>;
+}
+
+export interface ParsedScript {
+  turns: ScriptTurn[];
+  /** Lines that weren't a turn: bad JSON, or neither a tool nor text. */
+  skipped: number;
+}
+
+export function isModelScriptEnabled(): boolean {
+  return !!readEnv("MODEL_SCRIPT")?.trim();
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** One turn per non-blank line; anything that isn't one is counted, not guessed at. */
+export function parseModelScript(raw: string): ParsedScript {
+  const turns: ScriptTurn[] = [];
+  let skipped = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      skipped++;
+      continue;
+    }
+    if (!isPlainObject(parsed)) {
+      skipped++;
+      continue;
+    }
+    const text = typeof parsed.text === "string" ? parsed.text : undefined;
+    const tool = typeof parsed.tool === "string" && parsed.tool.trim() ? parsed.tool : undefined;
+    if (parsed.input !== undefined && !isPlainObject(parsed.input)) {
+      skipped++;
+      continue;
+    }
+    if (tool) {
+      turns.push({ tool, input: (parsed.input as Record<string, unknown>) ?? {}, text });
+    } else if (text !== undefined && parsed.tool === undefined) {
+      turns.push({ text });
+    } else {
+      skipped++;
+    }
+  }
+  return { turns, skipped };
+}
+
+/** The assistant message a turn becomes. Exported for the test that pins the shape. */
+export function turnToMessage(turn: ScriptTurn | undefined): AssistantMessage {
+  if (!turn) return fauxAssistantMessage([], { stopReason: "stop" });
+  const content: FauxContentBlock[] = [];
+  if (turn.text !== undefined) content.push(fauxText(turn.text));
+  if (turn.tool) {
+    // Parsed from JSON, so it is JSON.
+    const args = structuredClone(turn.input ?? {}) as ToolCall["arguments"];
+    content.push(fauxToolCall(turn.tool, args));
+    return fauxAssistantMessage(content, { stopReason: "toolUse" });
+  }
+  return fauxAssistantMessage(content, { stopReason: "stop" });
+}
+
+/**
+ * What the process has read of the script. Process-wide rather than held by
+ * one extension instance: pi rebuilds the runtime and reruns extension
+ * factories on `/new`, resume and fork, and a fresh instance that re-read the
+ * file would run whatever an earlier scripted turn wrote into it. On
+ * `globalThis` for the same reason -- a re-imported module would start over.
+ */
+interface ScriptState {
+  loaded: boolean;
+  turns: ScriptTurn[];
+}
+
+const STATE_KEY = Symbol.for("loom.modelScript.state");
+
+function processState(): ScriptState {
+  const g = globalThis as { [STATE_KEY]?: ScriptState };
+  return (g[STATE_KEY] ??= { loaded: false, turns: [] });
+}
+
+/** Test reset: forget what this process read. */
+export function resetModelScriptState(): void {
+  const state = processState();
+  state.loaded = false;
+  state.turns = [];
+}
+
+/**
+ * The faux provider plus the queue it reads from. Every model call takes the
+ * next turn and queues itself again, so the provider never runs dry.
+ */
+export function createScriptedModel(state: ScriptState = { loaded: false, turns: [] }): {
+  faux: FauxProviderHandle;
+  load: (turns: ScriptTurn[]) => void;
+} {
+  const faux = fauxProvider({
+    provider: MODEL_SCRIPT_PROVIDER,
+    api: MODEL_SCRIPT_PROVIDER,
+    models: [
+      {
+        id: MODEL_SCRIPT_MODEL_ID,
+        name: "Scripted model (ORBIT_MODEL_SCRIPT)",
+        reasoning: false,
+        input: ["text"],
+        contextWindow: 200_000,
+        maxTokens: 16_384,
+      },
+    ],
+  });
+  const step = (): AssistantMessage => {
+    faux.appendResponses([step]);
+    return turnToMessage(state.turns.shift());
+  };
+  faux.setResponses([step]);
+  return {
+    faux,
+    load: (turns) => {
+      state.turns = turns.map((t) => structuredClone(t));
+    },
+  };
+}
+
+/** Big enough for any scenario, small enough that a mistake can't stall startup. */
+const MAX_SCRIPT_BYTES = 1 << 20;
+
+export interface ScriptRead {
+  /** Relative to the real session directory; null when refused. */
+  file: string | null;
+  parsed: ParsedScript;
+  rejected?: "missing" | "outside-session-dir" | "not-a-file" | "too-large" | "unreadable";
+}
+
+/**
+ * Read the script once, through one file descriptor, from a regular file that
+ * really is inside the session directory.
+ *
+ * Resolved before it is opened, then opened with `O_NOFOLLOW`, so swapping the
+ * checked file for a symlink between the containment check and the read fails
+ * the open instead of reading elsewhere; the content comes from that same
+ * descriptor. `O_NONBLOCK` and the `isFile` check refuse a named pipe, which
+ * would otherwise let a writer supply lines after startup, or never close and
+ * hang it. (On Windows neither flag exists and both are 0; the check on the
+ * descriptor still refuses anything that isn't a file.)
+ */
+export function readModelScript(sessionDir: string, configured: string): ScriptRead {
+  const empty: ParsedScript = { turns: [], skipped: 0 };
+  const root = fs.realpathSync(sessionDir);
+  let real: string;
+  try {
+    real = fs.realpathSync(path.resolve(sessionDir, configured));
+  } catch {
+    return { file: null, parsed: empty, rejected: "missing" };
+  }
+  if (!real.startsWith(root + path.sep)) {
+    return { file: null, parsed: empty, rejected: "outside-session-dir" };
+  }
+  const flags =
+    fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+  let fd: number;
+  try {
+    fd = fs.openSync(real, flags);
+  } catch {
+    return { file: null, parsed: empty, rejected: "unreadable" };
+  }
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) return { file: null, parsed: empty, rejected: "not-a-file" };
+    // O_NOFOLLOW covers the last component only. A parent directory swapped
+    // for a symlink between the realpath and the open would still be
+    // followed, so the path has to resolve to the same place after the open,
+    // and to the file this descriptor has open.
+    let again: fs.Stats | null = null;
+    try {
+      if (fs.realpathSync(real) === real) again = fs.statSync(real);
+    } catch {
+      // gone or moved: refused below
+    }
+    if (!again || again.dev !== stat.dev || again.ino !== stat.ino) {
+      return { file: null, parsed: empty, rejected: "outside-session-dir" };
+    }
+    if (stat.size > MAX_SCRIPT_BYTES) {
+      return { file: null, parsed: empty, rejected: "too-large" };
+    }
+    return {
+      file: path.relative(root, real),
+      parsed: parseModelScript(fs.readFileSync(fd, "utf-8")),
+    };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+const SCRIPTED_REF = `${MODEL_SCRIPT_PROVIDER}/${MODEL_SCRIPT_MODEL_ID}`;
+
+function logRow(kind: string, payload: Record<string, unknown>): void {
+  const notebookPath = getNotebookPath();
+  if (!notebookPath) return;
+  appendActivityEvent(path.dirname(notebookPath), {
+    timestamp: new Date().toISOString(),
+    kind,
+    source: "model-script",
+    payload,
+  });
+}
+
+export function registerModelScript(pi: ExtensionAPI): void {
+  const state = processState();
+  const scripted = createScriptedModel(state);
+  pi.registerProvider(scripted.faux.provider);
+  const isScripted = (m: { provider?: string; id?: string } | undefined) =>
+    m?.provider === MODEL_SCRIPT_PROVIDER && m?.id === MODEL_SCRIPT_MODEL_ID;
+
+  const select = async (): Promise<boolean> => {
+    try {
+      if (await pi.setModel(scripted.faux.getModel())) return true;
+      // A native provider's auth state can lag its registration by a tick.
+      await new Promise((resolve) => setImmediate(resolve));
+      return await pi.setModel(scripted.faux.getModel());
+    } catch {
+      return false;
+    }
+  };
+
+  pi.on("session_start", async () => {
+    const configured = readEnv("MODEL_SCRIPT")?.trim();
+    if (!configured) return;
+    // Selected before anything can go wrong with the file, so a bad script
+    // never leaves the session on a real model.
+    const selected = await select();
+    if (state.loaded) {
+      if (!selected) logRow("model.script.unselected", { model: SCRIPTED_REF });
+      return;
+    }
+    state.loaded = true;
+
+    const notebookPath = getNotebookPath();
+    if (!notebookPath) return;
+    const read = readModelScript(path.dirname(notebookPath), configured);
+    scripted.load(read.parsed.turns);
+    logRow("model.script", {
+      // Never the configured spelling of a refused path: it can name
+      // somewhere outside the session.
+      file: read.file,
+      entries: read.parsed.turns.length,
+      skipped: read.parsed.skipped,
+      ...(read.rejected ? { rejected: read.rejected } : {}),
+      model: SCRIPTED_REF,
+      selected,
+    });
+  });
+
+  // Anything that moves the session off the scripted model -- the picker, an
+  // RPC, a restore -- is moved back.
+  pi.on("model_select", async (event) => {
+    if (isScripted(event.model)) return;
+    const selected = await select();
+    logRow("model.script.reselected", {
+      from: `${event.model?.provider}/${event.model?.id}`,
+      source: event.source,
+      selected,
+    });
+  });
+
+  // The backstop. The faux provider never calls `onPayload`, so while the
+  // seam is on, a provider request reaching this hook is a real one, however
+  // it got selected. Abort it before it is sent.
+  pi.on("before_provider_request", async (_event, ctx) => {
+    ctx.abort();
+    logRow("model.script.blocked", {
+      model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null,
+    });
+  });
+}
+
+/** For tools that call a provider directly, outside the session's model. */
+export function modelScriptRefusal(tool: string): string | null {
+  return readEnv("MODEL_SCRIPT")?.trim()
+    ? `${tool} is unavailable while ORBIT_MODEL_SCRIPT is set: it calls a model directly, ` +
+        `and the scripted session must never reach a real one.`
+    : null;
+}

package/extensions/orbit/notebook-anchors.ts

@@ -0,0 +1,342 @@
+/**
+ * What a `notebook_anchor` is allowed to point at.
+ *
+ * `galaxy_invocation_record` / `galaxy_job_record` take a `notebookAnchor` and
+ * write it into the block verbatim. Nothing checked it, so a model that typed
+ * `plan-1-step-3` where the notebook says `plan-a-step-1` produced a block that
+ * binds to no step at all: the Activity panel still shows the run, the poller
+ * still advances it, and the evidence gate -- which looks a step's anchor up
+ * among the blocks (`findContradictions`) -- silently has nothing to compare.
+ * A binding that quietly points nowhere is worse than a rejected call, because
+ * every downstream check reads as "no opinion" rather than "broken".
+ *
+ * Three things count as an anchor, matching what the plan convention
+ * (`context.ts`) teaches and what `init-gate.ts` parses:
+ *
+ *   - an explicit `{#plan-a-step-1}` marker, which is what steps carry;
+ *   - a plan step's positional address, `plan-<letter>-step-<n>`, derived for
+ *     steps that carry no explicit marker. That is the shape the convention
+ *     would have given them, and it is the only address available on the
+ *     Llama-4 path, where `buildPlanConventionBlock({omitAnchors: true})`
+ *     deliberately tells the model *not* to write `{#...}` because the litellm
+ *     proxy in front of it reads a curly brace as a tool-call boundary, and
+ *     then tells it to say "Plan A step 2" instead;
+ *   - a markdown heading, via its GitHub-style slug, for a notebook whose
+ *     sections are the only structure it has.
+ *
+ * Fenced and indented code is excluded, for the reason `parsePlanSteps`
+ * excludes fences: a plan draft pasted inside a ```plan fence is quoted, not
+ * asserted, and the `loom-invocation` blocks are themselves fences. Without
+ * that, a block's own `notebook_anchor:` line would make every later record
+ * call for that anchor validate against a record we wrote ourselves.
+ */
+
+/** `{#some-id}` -- same shape `evidence-gate.ts` reads off a step line. */
+const ANCHOR = /\{#([^}]+)\}/g;
+/** Non-global twin, for the one place that only asks whether there is one. */
+const HAS_ANCHOR = /\{#[^}]+\}/;
+/** A markdown ATX heading, indentable by up to three spaces like any block. */
+const HEADING = /^ {0,3}(#{1,6})\s+(.*)$/;
+/** `## Plan A: Title [routing]` -- the same shape init-gate.ts parses. */
+const PLAN_HEADING = /^ {0,3}##\s+Plan\s+([^:]+):/i;
+const ANY_H2 = /^ {0,3}##\s+/;
+/** A plan step checkbox line, with its optional leading ordinal. */
+const STEP_LINE = /^\s*-\s+\[[ xX!]\]\s+(.*)$/;
+const STEP_ORDINAL = /^(\d+)\.\s*/;
+
+/**
+ * A fence opener: up to three spaces of indent, optionally behind a list
+ * marker, then three or more backticks or tildes.
+ *
+ * The list-marker branch is not pedantry. `- ```plan` opens a fence inside a
+ * list item, and a scanner that only looks for a fence at the start of a line
+ * walks straight past it and collects every anchor in the quoted plan that
+ * follows.
+ */
+const FENCE_OPEN = /^ {0,3}(?:(?:[-*+]|\d{1,9}[.)])\s+)?(`{3,}|~{3,})/;
+/** Four spaces (or a tab) of indent is an indented code block, not prose. */
+const INDENTED_CODE = /^(?: {4}|\t)/;
+
+/** How many anchors a rejection names before it starts summarizing. */
+const MAX_LISTED_ANCHORS = 20;
+
+export interface NotebookAnchors {
+  /** Explicit `{#id}` markers, in document order, spelled as written. */
+  explicit: string[];
+  /** Positional addresses for plan steps that carry no explicit marker. */
+  steps: string[];
+  /** Slugs derived from headings, in document order, GitHub-style. */
+  headings: string[];
+}
+
+export type AnchorResolution =
+  | { kind: "resolved"; anchor: string }
+  | { kind: "unknown" }
+  /** Two anchors differ only in case and the input matched neither exactly. */
+  | { kind: "ambiguous"; candidates: string[] };
+
+/**
+ * Slugify heading text the way GitHub does: drop the inline markup, lowercase,
+ * strip punctuation, spaces to hyphens. `## Plan A: chrM Variant Calling
+ * [remote]` becomes `plan-a-chrm-variant-calling-remote`.
+ */
+export function slugifyHeading(text: string): string {
+  return text
+    .replace(ANCHOR, "")
+    .replace(/[*_`~]/g, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, "")
+    .trim()
+    .replace(/\s+/g, "-");
+}
+
+/**
+ * Walk the notebook a line at a time, handing back only the lines a reader
+ * would see as prose -- no fenced blocks, no indented code.
+ *
+ * Fence tracking remembers the marker it opened with and closes only on the
+ * same character, at least as long, with nothing but whitespace after it. A
+ * symmetric "any three backticks or tildes toggles" rule gets this wrong in
+ * both directions: `~~~` inside a ``` block ends the quote early and exposes
+ * whatever follows, and a stray ``` inside an indented code sample swallows the
+ * rest of the file.
+ */
+function* proseLines(content: string): Generator<string> {
+  let fence: { marker: string; length: number } | null = null;
+  for (const line of content.split("\n")) {
+    if (fence) {
+      const close = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
+      if (close && close[1][0] === fence.marker && close[1].length >= fence.length) {
+        fence = null;
+      }
+      continue;
+    }
+    if (INDENTED_CODE.test(line)) continue;
+    const open = line.match(FENCE_OPEN);
+    if (open) {
+      fence = { marker: open[1][0], length: open[1].length };
+      continue;
+    }
+    yield line;
+  }
+}
+
+/** Every anchor the notebook offers, split by how it was written. */
+export function collectNotebookAnchors(content: string): NotebookAnchors {
+  const explicit: string[] = [];
+  const steps: string[] = [];
+  const headings: string[] = [];
+  // GitHub disambiguates repeated heading slugs with -1, -2, ... Mirroring it
+  // means the second `## Results` is addressable as `results-1` rather than
+  // being silently unreachable behind the first.
+  const headingCounts = new Map<string, number>();
+  let planKey: string | null = null;
+  let stepIndex = 0;
+
+  for (const line of proseLines(content)) {
+    for (const m of line.matchAll(ANCHOR)) {
+      const id = m[1].trim();
+      if (id) explicit.push(id);
+    }
+
+    const heading = line.match(HEADING);
+    if (heading) {
+      const plan = line.match(PLAN_HEADING);
+      if (plan) {
+        planKey = slugifyHeading(plan[1]);
+        stepIndex = 0;
+      } else if (ANY_H2.test(line)) {
+        // Any other h2 ends the plan section, same rule init-gate.ts uses.
+        planKey = null;
+      }
+      const slug = slugifyHeading(heading[2]);
+      if (slug) {
+        const seen = headingCounts.get(slug) ?? 0;
+        headingCounts.set(slug, seen + 1);
+        headings.push(seen === 0 ? slug : `${slug}-${seen}`);
+      }
+      continue;
+    }
+
+    const step = line.match(STEP_LINE);
+    if (!step || !planKey) continue;
+    const text = step[1];
+    stepIndex++;
+    // A step that names itself is addressed by that name; deriving a second
+    // address for it would let a block record an anchor the evidence gate can
+    // never match against the step it belongs to.
+    if (HAS_ANCHOR.test(text)) continue;
+    // Prefer the ordinal the step writes over its position, since that is the
+    // number the convention's anchor would carry.
+    const ordinal = text.match(STEP_ORDINAL)?.[1] ?? String(stepIndex);
+    steps.push(`plan-${planKey}-step-${ordinal}`);
+  }
+
+  return { explicit, steps, headings };
+}
+
+/** A checkbox line, under the anchor a registry attempt would be bound to. */
+export interface CheckboxStep {
+  anchor: string;
+  state: " " | "x" | "!";
+  text: string;
+  /** False for a positional address, which follows the line's position, not the line. */
+  explicit: boolean;
+}
+
+const CHECKBOX_LINE = /^\s*-\s+\[([ xX!])\]\s+(.*)$/;
+
+/**
+ * Every checkbox line a reader would see, keyed the way `collectNotebookAnchors`
+ * addresses steps: each explicit `{#id}` on the line wherever it sits in the
+ * file, else the plan step's positional address. Unlike `parsePlanSteps` in
+ * the evidence gate, an explicitly anchored checkbox counts outside a
+ * `## Plan` section too -- renaming the heading above a step must not make its
+ * checkbox stop being that step's.
+ */
+export function collectCheckboxSteps(content: string): CheckboxStep[] {
+  const out: CheckboxStep[] = [];
+  let planKey: string | null = null;
+  let stepIndex = 0;
+  for (const line of proseLines(content)) {
+    if (HEADING.test(line)) {
+      const plan = line.match(PLAN_HEADING);
+      if (plan) {
+        planKey = slugifyHeading(plan[1]);
+        stepIndex = 0;
+      } else if (ANY_H2.test(line)) {
+        planKey = null;
+      }
+      continue;
+    }
+    const box = line.match(CHECKBOX_LINE);
+    if (!box) continue;
+    const state = (box[1] === "X" ? "x" : box[1]) as CheckboxStep["state"];
+    const text = box[2];
+    if (planKey && STEP_LINE.test(line)) stepIndex++;
+    const ids = [...text.matchAll(ANCHOR)].map((m) => m[1].trim()).filter(Boolean);
+    if (ids.length > 0) {
+      for (const anchor of ids) out.push({ anchor, state, text: text.trim(), explicit: true });
+      continue;
+    }
+    if (!planKey) continue;
+    const ordinal = text.match(STEP_ORDINAL)?.[1] ?? String(stepIndex);
+    out.push({
+      anchor: `plan-${planKey}-step-${ordinal}`,
+      state,
+      text: text.trim(),
+      explicit: false,
+    });
+  }
+  return out;
+}
+
+/**
+ * The anchors a record call may name, de-duplicated, in the order a rejection
+ * should offer them: what the author wrote, then step addresses, then sections.
+ *
+ * De-duplication is case-sensitive on purpose. Two spellings of one anchor are
+ * a real collision the author should see, not noise to fold away.
+ */
+export function listNotebookAnchors(content: string): string[] {
+  const { explicit, steps, headings } = collectNotebookAnchors(content);
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const anchor of [...explicit, ...steps, ...headings]) {
+    if (seen.has(anchor)) continue;
+    seen.add(anchor);
+    out.push(anchor);
+  }
+  return out;
+}
+
+/**
+ * Strip the spellings a model copies out of the markdown -- `{#step-1}`,
+ * `#step-1` -- down to the bare id.
+ */
+function normalizeAnchorInput(raw: string): string {
+  let value = raw.trim();
+  const braced = value.match(/^\{(.+)\}$/);
+  if (braced) value = braced[1];
+  return value.replace(/^#+/, "").trim();
+}
+
+/**
+ * Resolve `input` against the notebook, returning the anchor **as the notebook
+ * spells it**.
+ *
+ * Canonicalizing rather than echoing the input back matters: the evidence gate
+ * matches a block's `notebook_anchor` against a step's anchor verbatim, so
+ * storing a case-drifted copy would record a block bound to nothing while
+ * looking fine in the file. For the same reason a case-insensitive match that
+ * two different anchors both answer to is refused rather than guessed -- the
+ * guess would gate the wrong step.
+ *
+ * `Plan A step 2` is accepted as well as `plan-a-step-2`, because that is the
+ * form `anchorGuidance` asks for when explicit anchors are suppressed.
+ */
+export function resolveNotebookAnchor(content: string, input: string): AnchorResolution {
+  const wanted = normalizeAnchorInput(input);
+  if (!wanted) return { kind: "unknown" };
+  const { explicit, steps, headings } = collectNotebookAnchors(content);
+  // The prose form the Llama-4 guidance teaches slugs to the address form.
+  const candidates = [wanted, slugifyHeading(wanted)].filter(Boolean);
+
+  for (const candidate of candidates) {
+    for (const anchor of explicit) {
+      if (anchor === candidate) return { kind: "resolved", anchor };
+    }
+  }
+  for (const candidate of candidates) {
+    const lowered = candidate.toLowerCase();
+    const hits = [...new Set(explicit.filter((a) => a.toLowerCase() === lowered))];
+    if (hits.length > 1) return { kind: "ambiguous", candidates: hits };
+    if (hits.length === 1) return { kind: "resolved", anchor: hits[0] };
+  }
+  for (const candidate of candidates) {
+    const lowered = candidate.toLowerCase();
+    for (const anchor of [...steps, ...headings]) {
+      if (anchor === lowered) return { kind: "resolved", anchor };
+    }
+  }
+  return { kind: "unknown" };
+}
+
+/** The refusal a record tool hands back, naming what the notebook does have. */
+export function unknownAnchorMessage(input: string, anchors: string[]): string {
+  const wanted = normalizeAnchorInput(input) || input.trim();
+  if (anchors.length === 0) {
+    return (
+      `Unknown notebook anchor "${wanted}": notebook.md has no headings, plan steps or ` +
+      `{#anchor} markers to bind to, so this block would point at nothing. Write the step ` +
+      `first -- \`- [ ] 1. **Step name** {#${wanted}} -- description\` -- then record against it.`
+    );
+  }
+  const shown = anchors.slice(0, MAX_LISTED_ANCHORS);
+  const extra = anchors.length - shown.length;
+  const tail = extra > 0 ? `, and ${extra} more` : "";
+  return (
+    `Unknown notebook anchor "${wanted}": nothing in notebook.md resolves to it, so this ` +
+    `block would point at nothing. Anchors that do exist: ${shown.join(", ")}${tail}. ` +
+    `Record against one of those, or add {#${wanted}} to the step you mean first.`
+  );
+}
+
+/** The refusal when the notebook spells one anchor two ways. */
+export function ambiguousAnchorMessage(input: string, candidates: string[]): string {
+  const wanted = normalizeAnchorInput(input) || input.trim();
+  return (
+    `Ambiguous notebook anchor "${wanted}": notebook.md carries ${candidates.join(" and ")}, ` +
+    `which differ only in case, and binding to the wrong one would attach this run to the ` +
+    `wrong step. Record against one of them exactly as it is written, or give the two steps ` +
+    `distinct anchors.`
+  );
+}
+
+/** Thrown by the record tools' write path when the anchor doesn't resolve. */
+export class UnknownAnchorError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnknownAnchorError";
+  }
+}