@visual-z/xeno 0.8.3 → 0.9.0

package/src/core/file-precondition.ts

@@ -1,78 +0,0 @@
-/** R4 / D8: a read descriptor names immutable version premises; it grants no authority. */
-import type { ObservationReceipt } from "./read-observation.ts";
-import { isObservationArtifact } from "./observation-view.ts";
-import type { LogEvent } from "./events.ts";
-
-export interface FileIdentity { host: string; workspace: string; resource: string }
-export interface FileReadDescriptor {
-  kind: "file_read";
-  version: 1;
-  source: ObservationReceipt["source"];
-  selection: ObservationReceipt["selection"];
-}
-export interface FilePrecondition {
-  source: "read_handle" | "expected_sha256" | "session" | "create_only" | "unobserved";
-  expected: string | null;
-  read_handle?: string;
-}
-export type FilePreconditionDecision = { ok: true; precondition: FilePrecondition } |
-  { ok: false; code: "invalid_input" | "version_mismatch"; message: string; precondition?: FilePrecondition };
-
-const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
-const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-export const isFileDigest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
-
-/** Preserve chronology across path aliases; handoff anchors intentionally keep their legacy spelling. */
-export function latestObservedFileVersion(events: readonly LogEvent[], resource: string, identify: (path: string) => string): string | undefined {
-  for (let index = events.length - 1; index >= 0; index--) {
-    const event = events[index]!;
-    // P.3: multi-file Patch and captured commands observe each actual resulting version.
-    if (event.t === "checkpoint" && event.phase === "applied") {
-      for (const [path, change] of Object.entries(event.changes))
-        if (identify(path) === resource) return change.after?.sha256;
-      continue;
-    }
-    if (event.t !== "tool_result") continue;
-    const effect = event.effect;
-    if ((effect?.kind === "read" || effect?.kind === "edit") && identify(effect.path) === resource)
-      return effect.kind === "read" ? effect.sha256 : effect.sha256_after;
-  }
-  return undefined;
-}
-
-export function isFileReadDescriptor(value: unknown): value is FileReadDescriptor {
-  if (!record(value) || value["kind"] !== "file_read" || value["version"] !== 1) return false;
-  const source = value["source"], selection = value["selection"];
-  return record(source) && ["host", "workspace", "resource"].every(key => typeof source[key] === "string" && source[key] !== "") &&
-    isFileDigest(source["sha256"]) && isObservationArtifact(source["raw"]) && source["raw"].sha256 === source["sha256"] &&
-    record(selection) && natural(selection["start"]) && selection["start"] >= 1 && natural(selection["end"]) &&
-    natural(selection["total_lines"]) && selection["start"] <= selection["end"] && selection["end"] <= selection["total_lines"];
-}
-
-/** Explicit premises take precedence; an omitted premise may use the complete log projection. */
-export function checkFilePrecondition(identity: FileIdentity, current: string | null, input: {
-  descriptor?: FileReadDescriptor; read_handle?: string; expected_sha256?: string; observed?: string; create_only?: boolean;
-}): FilePreconditionDecision {
-  const invalid = (message: string): FilePreconditionDecision => ({ ok: false, code: "invalid_input", message });
-  if (input.expected_sha256 !== undefined && !isFileDigest(input.expected_sha256)) return invalid("expected_sha256 must be a lowercase SHA-256 digest");
-  if (input.observed !== undefined && !isFileDigest(input.observed)) return invalid("the observed file version is invalid; inspect the original log");
-  if (input.create_only && (input.read_handle !== undefined || input.expected_sha256 !== undefined))
-    return invalid("create_only cannot be combined with read_handle or expected_sha256");
-  if ((input.read_handle === undefined) !== (input.descriptor === undefined)) return invalid("read_handle requires its verified descriptor");
-  if (input.descriptor) {
-    if (!isFileReadDescriptor(input.descriptor) || !isFileDigest(input.read_handle)) return invalid("invalid read_handle descriptor");
-    for (const field of ["host", "workspace", "resource"] as const)
-      if (input.descriptor.source[field] !== identity[field]) return invalid(`read_handle names another ${field}; read the intended file here`);
-    if (input.expected_sha256 !== undefined && input.expected_sha256 !== input.descriptor.source.sha256)
-      return invalid("read_handle and expected_sha256 name different versions");
-  }
-  const precondition: FilePrecondition = input.create_only ? { source: "create_only", expected: null }
-    : input.descriptor ? { source: "read_handle", expected: input.descriptor.source.sha256, read_handle: input.read_handle! }
-    : input.expected_sha256 !== undefined ? { source: "expected_sha256", expected: input.expected_sha256 }
-    : input.observed !== undefined ? { source: "session", expected: input.observed }
-    : { source: "unobserved", expected: null };
-  if (precondition.source !== "unobserved" && precondition.expected !== current)
-    return { ok: false, code: "version_mismatch", precondition,
-      message: `file version changed; expected ${precondition.expected ?? "absent"}, current sha256: ${current ?? "absent"}. Read the current file before retrying.` };
-  return { ok: true, precondition };
-}

package/src/core/file-references.ts

@@ -1,35 +0,0 @@
-/** Explicit whitespace-delimited @ references; code literals and emails remain text. */
-export interface FileReference { readonly start: number; readonly end: number; readonly path: string }
-
-export function fileReferences(text: string): FileReference[] {
-  const refs: FileReference[] = [];
-  let codeTicks = 0;
-  for (let i = 0; i < text.length; i++) {
-    if (text[i] === "\\") { i++; continue; }
-    if (text[i] === "`") {
-      let end = i;
-      while (text[end] === "`") end++;
-      const count = end - i;
-      if (codeTicks === 0) codeTicks = count;
-      else if (count === codeTicks) codeTicks = 0;
-      i = end - 1;
-      continue;
-    }
-    if (codeTicks > 0 || text[i] !== "@" || (i > 0 && !/\s/.test(text[i - 1]!))) continue;
-    const start = i;
-    let end = i + 1;
-    let path: string;
-    if (text[end] === '"') {
-      const close = text.indexOf('"', end + 1);
-      if (close < 0 || text.slice(end, close).includes("\n")) continue;
-      path = text.slice(end + 1, close);
-      end = close + 1;
-    } else {
-      while (end < text.length && !/\s/.test(text[end]!)) end++;
-      path = text.slice(start + 1, end);
-    }
-    if (path.length > 0) refs.push({ start, end, path });
-    i = end - 1;
-  }
-  return refs;
-}

package/src/core/frontmatter.ts

@@ -1,213 +0,0 @@
-/**
- * Restricted YAML frontmatter reader.
- *
- * Why hand-written instead of a YAML package: the emitter in yaml.ts already
- * made that call for writes (AGENTS.md cites it as the example). This is the
- * read side of the same choice. A full parser would pull in aliases, anchors
- * and tags on a path that reads user and project files.
- *
- * Supported: `key: value`, quoted strings, booleans, and `[a, b]` arrays.
- * Nested mappings and multiline blocks are named and skipped; siblings stay.
- * The function does not throw — a broken header must not take down startup.
- */
-
-export type FrontmatterValue = string | boolean | readonly string[];
-
-export interface FrontmatterParse {
-  readonly fields: { readonly [key: string]: FrontmatterValue };
-  readonly body: string;
-  readonly diagnostics: readonly string[];
-}
-
-const KEY = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/;
-const BOOL = /^(?:true|false)$/i;
-
-export function parseFrontmatter(text: string): FrontmatterParse {
-  try {
-    return parseInner(text);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { fields: {}, body: text, diagnostics: [`frontmatter: ${message}`] };
-  }
-}
-
-function parseInner(text: string): FrontmatterParse {
-  const normalized = stripBom(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-  const extracted = extract(normalized);
-  if (extracted.yaml === null) {
-    return { fields: {}, body: extracted.body, diagnostics: [] };
-  }
-
-  const fields: { [key: string]: FrontmatterValue } = {};
-  const diagnostics: string[] = [];
-  const lines = extracted.yaml.split("\n");
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]!;
-    if (line.trim().length === 0 || line.trimStart().startsWith("#")) continue;
-
-    if (/^\s/.test(line)) {
-      diagnostics.push(`frontmatter: indented line is not a supported field`);
-      continue;
-    }
-
-    const match = KEY.exec(line);
-    if (!match) {
-      diagnostics.push(`frontmatter: unparseable line ${JSON.stringify(line)}`);
-      continue;
-    }
-
-    const key = match[1]!;
-    const raw = match[2] ?? "";
-
-    if (isNestedMarker(raw)) {
-      diagnostics.push(`frontmatter: nested mapping "${key}" is not supported`);
-      i = skipIndented(lines, i);
-      continue;
-    }
-
-    const parsed = parseValue(raw);
-    if (parsed === undefined) {
-      diagnostics.push(`frontmatter: nested mapping "${key}" is not supported`);
-      i = skipIndented(lines, i);
-      continue;
-    }
-    fields[key] = parsed;
-  }
-
-  return { fields, body: extracted.body, diagnostics };
-}
-
-function extract(text: string): { yaml: string | null; body: string } {
-  if (!text.startsWith("---")) return { yaml: null, body: text };
-  const lines = text.split("\n");
-  if (lines[0] !== "---") return { yaml: null, body: text };
-  let end = -1;
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i] === "---") {
-      end = i;
-      break;
-    }
-  }
-  if (end < 0) return { yaml: null, body: text };
-  return {
-    yaml: lines.slice(1, end).join("\n"),
-    body: lines.slice(end + 1).join("\n").replace(/^\n+/, "").replace(/\s+$/, ""),
-  };
-}
-
-function isNestedMarker(raw: string): boolean {
-  const value = raw.trim();
-  return value.length === 0 || value === "|" || value === "|-" || value === "|+" ||
-    value === ">" || value === ">-" || value === ">+";
-}
-
-function parseValue(raw: string): FrontmatterValue | undefined {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith("{")) return undefined;
-  if (trimmed.startsWith("[")) return parseFlowArray(trimmed);
-  if (trimmed.startsWith('"') || trimmed.startsWith("'")) {
-    const quoted = parseQuoted(trimmed);
-    return quoted ?? trimmed;
-  }
-  const unquoted = stripInlineComment(trimmed);
-  if (BOOL.test(unquoted)) return unquoted.toLowerCase() === "true";
-  return unquoted;
-}
-
-/**
- * Flow arrays of scalars only. A mapping inside the brackets is a nested
- * structure we refuse, so the caller can name the field and keep going.
- */
-function parseFlowArray(raw: string): readonly string[] | undefined {
-  if (!raw.startsWith("[") || !raw.endsWith("]")) return undefined;
-  const inner = raw.slice(1, -1).trim();
-  if (inner.length === 0) return [];
-  if (inner.includes("{") || inner.includes("[") || /(?:^|,)\s*[A-Za-z_][A-Za-z0-9_-]*\s*:/.test(inner)) {
-    return undefined;
-  }
-  const items: string[] = [];
-  let buf = "";
-  let quote: string | null = null;
-  for (let i = 0; i < inner.length; i++) {
-    const ch = inner[i]!;
-    if (quote) {
-      if (quote === "'" && ch === "'" && inner[i + 1] === "'") {
-        buf += "'";
-        i++;
-        continue;
-      }
-      if (ch === quote && (quote === "'" || inner[i - 1] !== "\\")) {
-        quote = null;
-        continue;
-      }
-      buf += ch;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      quote = ch;
-      continue;
-    }
-    if (ch === ",") {
-      items.push(buf.trim());
-      buf = "";
-      continue;
-    }
-    buf += ch;
-  }
-  items.push(buf.trim());
-  return items;
-}
-
-function parseQuoted(raw: string): string | undefined {
-  const q = raw[0];
-  if (q !== '"' && q !== "'") return undefined;
-  let out = "";
-  for (let i = 1; i < raw.length; i++) {
-    const ch = raw[i]!;
-    if (q === "'" && ch === "'" && raw[i + 1] === "'") {
-      out += "'";
-      i++;
-      continue;
-    }
-    if (ch === q) {
-      const rest = raw.slice(i + 1).trim();
-      if (rest.length > 0 && !rest.startsWith("#")) return undefined;
-      return out;
-    }
-    if (q === '"' && ch === "\\" && i + 1 < raw.length) {
-      const next = raw[i + 1]!;
-      out += next === "n" ? "\n" : next === "t" ? "\t" : next;
-      i++;
-      continue;
-    }
-    out += ch;
-  }
-  return undefined;
-}
-
-function stripInlineComment(value: string): string {
-  const idx = value.indexOf(" #");
-  return (idx >= 0 ? value.slice(0, idx) : value).trim();
-}
-
-function skipIndented(lines: readonly string[], i: number): number {
-  let j = i + 1;
-  while (j < lines.length) {
-    const next = lines[j]!;
-    if (next.trim().length === 0) {
-      j++;
-      continue;
-    }
-    if (/^\s/.test(next)) {
-      j++;
-      continue;
-    }
-    break;
-  }
-  return j - 1;
-}
-
-function stripBom(text: string): string {
-  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}

package/src/core/git-status.ts

@@ -1,29 +0,0 @@
-/** Counts from Git porcelain v2, distinct from agent tool effects. No path decoding needed. */
-export interface GitStatus {
-  readonly branch: string | null;
-  readonly staged: number;
-  readonly changed: number;
-  readonly untracked: number;
-  readonly conflicted: number;
-  readonly ahead: number;
-  readonly behind: number;
-}
-export function parseGitStatus(output: string): GitStatus {
-  let branch: string | null = null, staged = 0, changed = 0, untracked = 0, conflicted = 0, ahead = 0, behind = 0;
-  const records = output.split("\0");
-  for (let index = 0; index < records.length; index++) {
-    const line = records[index]!;
-    if (line.startsWith("# branch.head ")) branch = line.slice(14).trim();
-    else if (line.startsWith("# branch.ab ")) {
-      const match = /^# branch.ab \+(\d+) -(\d+)$/.exec(line.trim());
-      if (match) { ahead = Number(match[1]); behind = Number(match[2]); }
-    } else if (line.startsWith("? ")) untracked++;
-    else if (/^[12u] [A-Z?.]{2} /.test(line)) {
-      if (line[2] !== ".") staged++;
-      if (line[3] !== ".") changed++;
-      if (line[0] === "u") conflicted++;
-      if (line[0] === "2") index++; // Rename's next NUL field is a path, never a status record.
-    }
-  }
-  return { branch, staged, changed, untracked, conflicted, ahead, behind };
-}

package/src/core/goal-view.ts

@@ -1,64 +0,0 @@
-/**
- * What the sidebar shows about an explicit goal (feat-sidebar-goal-and-speed),
- * derived from the log alone so it reads the same after a restart.
- *
- * The block exists only while a /goal is set, and for one message after it is
- * met. Its verdicts are the request ledger's (D11); this only chooses words:
- * the phase answers "do I need to act, and is it still running", and each
- * accepted check says what it needs from the user.
- */
-import type { LogEvent } from "./events.ts";
-import type { RequestCriterion, RequestState } from "./request-state.ts";
-
-export type GoalPhase = "drafting" | "working" | "needs_you" | "met" | "stopped";
-export type GoalCheck = { id: string; kind: RequestCriterion["kind"]; status: RequestCriterion["status"]; guard?: true; exit?: number };
-/**
- * `startedAt` is when the goal was set; `endedAt` when it was met, absent while
- * it runs. Times, not a duration, so a caller can cache this per log length and
- * read the clock only when it paints.
- */
-export type GoalStatus = { phase: GoalPhase; objective: string; checks: GoalCheck[]; startedAt: number; endedAt?: number; requests: number };
-
-/**
- * The goal block for the end of an ancestry, or null when no goal applies.
- * `running` is whether a request is in flight now; `drafting` is the objective
- * of a /goal whose criteria are still being drafted.
- */
-export function goalStatus(events: readonly LogEvent[], state: RequestState | undefined,
-  live: { running: boolean; drafting?: string }): GoalStatus | null {
-  if (live.drafting !== undefined) return { phase: "drafting", objective: live.drafting, checks: [], startedAt: 0, requests: 0 };
-  const lastSet = events.findLastIndex(event => event.t === "goal" && event.action === "set");
-  if (lastSet < 0) return null;
-  const set = events[lastSet]!;
-  if (set.t !== "goal" || set.action !== "set") return null;
-  const after = events.slice(lastSet + 1);
-  // The last clear decides: a met goal the user then cleared is gone like any other cleared goal.
-  const clear = after.findLastIndex(event => event.t === "goal" && event.action === "clear");
-  const cleared = clear < 0 ? undefined : after[clear];
-  // A goal the user cleared is gone; a met goal stays for one summary, until the next message opens a new request.
-  if (cleared?.t === "goal" && cleared.action === "clear" && cleared.reason !== "met") return null;
-  const recorded = cleared !== undefined;
-  if (recorded && after.slice(clear + 1).some(event => event.t === "user" && event.request === undefined)) return null;
-  // Only the goal's own request carries its contract; the ledger of any other request says nothing about it.
-  const own = state?.acceptance?.contract_id === set.contract.id && state.acceptance.contract_event !== undefined
-    && events.some((event, index) => index > lastSet && event.id === state.acceptance!.contract_event) ? state : undefined;
-  // The ledger is the verdict (D11): verified is met even before the clear is recorded -- an /accept outside a
-  // request, a log written before /accept recorded it -- and its clock stops at the last recorded fact.
-  const met = recorded || own?.status === "verified";
-  const end = recorded ? Date.parse(cleared.at) : met ? Date.parse(after.at(-1)?.at ?? set.at) : undefined;
-  const checks: GoalCheck[] = set.contract.criteria.map(item => {
-    const entry = own?.criteria.find(criterion => criterion.id === item.id);
-    const run = item.kind === "command" ? own?.commands.findLast(command => command.command === item.command) : undefined;
-    return { id: item.id, kind: item.kind, status: entry?.status ?? (item.kind === "human" ? "awaiting_human" : "not_run"),
-      ...(item.kind === "command" && item.guard ? { guard: true as const } : {}),
-      ...(entry?.status === "fail" && run ? { exit: run.exit } : {}) };
-  });
-  return { phase: met ? "met" : live.running ? "working" : own?.status === "awaiting_human" ? "needs_you" : "stopped",
-    objective: set.objective, checks, startedAt: Date.parse(set.at), ...(end === undefined ? {} : { endedAt: end }),
-    requests: (recorded ? after.slice(0, clear) : after).filter(event => event.t === "assistant").length };
-}
-
-/** The words the sidebar and the input edge use for a phase. */
-export function goalPhaseLabel(phase: GoalPhase): string {
-  return phase === "needs_you" ? "needs you" : phase;
-}

package/src/core/goal.ts

@@ -1,200 +0,0 @@
-/**
- * Explicit goals (research doc S.2 / S.5).
- *
- * The model drafts acceptance criteria for a goal; the user accepts them one
- * by one; only the accepted ones become the goal's contract. Whether the goal
- * is met is never the model's call: it is the request ledger's status, which
- * only command receipts and the user's own acceptance decisions move (D11).
- * The draft is itself only a claim -- it parses into candidates, and a
- * candidate that does not validate is reported and sent back to the model to
- * correct, never repaired by guessing.
- */
-import { ACCEPTANCE_COMMAND_LIMIT, parseAcceptanceContract, type AcceptanceContract, type AcceptanceCriterion } from "./acceptance.ts";
-import type { GoalEvent, LogEvent } from "./events.ts";
-import type { RequestState } from "./request-state.ts";
-
-/**
- * Assumed, not measured: enough for a goal's distinct checks, few enough that
- * a person reads and decides on each one rather than accepting a wall.
- */
-export const GOAL_CRITERIA_LIMIT = 8;
-
-export function goalDraftRequest(objective: string): string {
-  return [
-    `Goal: ${objective}`,
-    "",
-    "Do not start the work yet. Draft the acceptance criteria that would show this goal is met, for the user to accept or reject one by one.",
-    "You may read the workspace first (read, find, grep) to learn its real files and commands. You cannot change anything or run commands in this step.",
-    `Then reply with only a JSON object: {"criteria":[{"id":"short-id","kind":"command","description":"what it shows","command":"exact shell command"}]}, at most ${GOAL_CRITERIA_LIMIT} items.`,
-    "- kind \"command\": a command that exits 0 only when the criterion holds, and fails on the workspace as it is now if the goal is not yet done. Prefer checks that exercise new inputs over checks that only replay an example.",
-    "- \"guard\": true on a command for what the goal must not break or change, such as files to leave untouched or behaviour that must keep working. A guard passes now and must still pass when the goal is done; every command without it must fail now.",
-    "- kind \"human\" (no command): only for what a person must judge, such as tone or visual quality.",
-    "- ids: letters, digits, dot, dash, underscore, colon; unique.",
-    "If you cannot tell how to check something, make it a human criterion rather than inventing a command.",
-    "If the goal cannot be checked or achieved in this workspace at all, reply {\"criteria\": [], \"blocked\": \"the specific reason\"}.",
-  ].join("\n");
-}
-
-export type GoalDraft = { criteria: AcceptanceCriterion[]; errors: string[]; blocked?: string };
-
-/**
- * Assumed, not measured: one correction. Instructor's reask and Pydantic AI's
- * output retries likewise send the validation errors back for a bounded number
- * of attempts. The slip this exists for -- a real GLM draft missing its
- * closing brackets -- needs one; a model that fails the same schema twice is
- * not helped by a third full request, and the user can still redraft.
- */
-export const GOAL_DRAFT_RETRIES = 1;
-
-/** The correction request: the parser's own reasons, and the form the reply must take. */
-export function goalDraftRetry(errors: readonly string[]): string {
-  return [
-    "Harness draft check: your draft could not be used as written.",
-    ...errors.map(error => `- ${error}`),
-    "Reply again with only the complete corrected JSON object in the same form, keeping the criteria that were valid. Do not start the work.",
-  ].join("\n");
-}
-
-/**
- * The draft among the events one draft run recorded: the last assistant reply
- * of the first request they open. A follow-up the user queued meanwhile opens
- * its own request and is never read as the draft; a run that recorded no
- * request has no draft.
- */
-export function draftReply(recorded: readonly LogEvent[]): { id: string; text: string } | null {
-  const opens = (event: LogEvent) => event.t === "user" && event.request === undefined;
-  const start = recorded.findIndex(opens);
-  if (start < 0) return null;
-  const next = recorded.findIndex((event, index) => index > start && opens(event));
-  const reply = recorded.slice(start, next < 0 ? undefined : next).findLast(event => event.t === "assistant");
-  return reply?.t === "assistant" ? { id: reply.id, text: reply.blocks.flatMap(block => block.type === "text" ? [block.text] : []).join("\n") } : null;
-}
-
-/** The first JSON object in a reply: a fenced block when present, else the outermost braces. */
-function jsonObject(text: string): unknown {
-  const fenced = /```(?:json)?\s*\n([\s\S]*?)\n```/.exec(text)?.[1];
-  const candidate = fenced ?? text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1);
-  if (!candidate.trim()) throw Error("the reply holds no JSON object");
-  return JSON.parse(candidate);
-}
-
-const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$/;
-
-/**
- * Why one drafted item is not a criterion, in words the user can act on; null
- * when it is one. A human item's empty or null `command`, and a `guard` of
- * false or null, are only a model's way of saying "none" and are dropped
- * before this runs.
- */
-function draftItemError(item: Record<string, unknown>, seen: ReadonlySet<string>): string | null {
-  const { id, kind, description, command, guard } = item;
-  if (typeof id !== "string" || !id.trim()) return "has no id";
-  if (!ID.test(id)) return `id ${JSON.stringify(id)} may use only letters, digits, dot, dash, underscore and colon (at most 80)`;
-  if (seen.has(id)) return `repeats id ${id}`;
-  if (typeof description !== "string" || !description.trim()) return "has no description";
-  if (description.length > 300) return "has a description longer than 300 characters";
-  if (kind === "human") return command !== undefined ? "is a human criterion with a command; make it a command criterion or drop the command"
-    : guard !== undefined ? "is a human criterion marked as a guard; a guard needs a command" : null;
-  if (kind !== "command") return `has kind ${JSON.stringify(kind)}; use "command" or "human"`;
-  if (guard !== undefined && guard !== true) return `has guard ${JSON.stringify(guard)}; use true or leave it out`;
-  if (typeof command !== "string" || !command.trim()) return "needs a command";
-  if (command.length > ACCEPTANCE_COMMAND_LIMIT) return `has a command longer than ${ACCEPTANCE_COMMAND_LIMIT} characters`;
-  return null;
-}
-
-export function parseGoalDraft(text: string): GoalDraft {
-  let value: unknown;
-  try { value = jsonObject(text); }
-  catch (error) { return { criteria: [], errors: [`the draft is not readable JSON: ${error instanceof Error ? error.message : String(error)}`] }; }
-  const object = value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
-  const items = object?.["criteria"];
-  if (!Array.isArray(items)) return { criteria: [], errors: ["the draft has no criteria array"] };
-  const blockedText = object?.["blocked"];
-  const blocked = typeof blockedText === "string" && blockedText.trim() ? blockedText.trim().slice(0, 500) : undefined;
-  const criteria: AcceptanceCriterion[] = [], errors: string[] = [], seen = new Set<string>();
-  items.forEach((raw, index) => {
-    if (criteria.length >= GOAL_CRITERIA_LIMIT) { errors.push(`criterion ${index + 1}: more than ${GOAL_CRITERIA_LIMIT} criteria`); return; }
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) { errors.push(`criterion ${index + 1} is not an object`); return; }
-    const item = { ...(raw as Record<string, unknown>) };
-    if (item["kind"] === "human" && (item["command"] === null || typeof item["command"] === "string" && !item["command"].trim())) delete item["command"];
-    if (item["guard"] === false || item["guard"] === null) delete item["guard"];
-    const problem = draftItemError(item, seen);
-    if (problem) { errors.push(`criterion ${index + 1} ${problem}`); return; }
-    // The one validator for criteria: a draft item is accepted exactly when a contract would accept it.
-    try {
-      const [criterion] = parseAcceptanceContract({ version: 1, id: "goal", criteria: [{ id: item["id"], kind: item["kind"], description: item["description"],
-        ...(item["kind"] === "command" ? { command: item["command"], ...(item["guard"] === true ? { guard: true } : {}) } : {}) }] }).criteria;
-      seen.add(criterion!.id); criteria.push(criterion!);
-    } catch (error) { errors.push(`criterion ${index + 1}: ${error instanceof Error ? error.message : String(error)}`); }
-  });
-  return { criteria, errors, ...(blocked ? { blocked } : {}) };
-}
-
-/** Only accepted criteria, in draft order. Accepting none is not a goal. */
-export function goalContract(criteria: readonly AcceptanceCriterion[], accepted: readonly string[]): AcceptanceContract {
-  const chosen = criteria.filter(item => accepted.includes(item.id));
-  if (chosen.length === 0) throw Error("a goal needs at least one accepted criterion");
-  return parseAcceptanceContract({ version: 1, id: "goal", scope: "request", criteria: chosen });
-}
-
-export type ActiveGoal = Extract<GoalEvent, { action: "set" }>;
-
-/** The goal in force at the end of an ancestry: the last set, unless a clear followed it. */
-export function activeGoal(events: readonly LogEvent[]): ActiveGoal | null {
-  const last = events.findLast(event => event.t === "goal");
-  return last?.t === "goal" && last.action === "set" ? last : null;
-}
-
-/**
- * Assumed, not measured: two goal checks answered without any tool use means
- * the model is talking past the goal, and more requests will not change that.
- * Claude Code's /goal stops on the same signal ("no tool use for several
- * turns in a row"). Too low would stop a model that needed one more reply to
- * plan; too high spends requests on replies that do nothing.
- */
-export const GOAL_IDLE_LIMIT = 2;
-
-/** Goal checks since the last tool result: each one the model answered without acting. */
-export function idleGoalChecks(events: readonly LogEvent[]): number {
-  let count = 0;
-  for (let i = events.length - 1; i >= 0; i--) {
-    const event = events[i]!;
-    if (event.t === "tool_result" || event.t === "user" && event.request === undefined) break;
-    if (event.t === "guidance" && event.reason === "goal") count++;
-  }
-  return count;
-}
-
-export type GoalDecision =
-  | { action: "met" }
-  | { action: "await_human" }
-  | { action: "stop"; reason: string }
-  | { action: "continue"; text: string };
-
-/**
- * What a goal does when the model ends a turn. Reads the request ledger, so
- * the loop and every goal view agree. A reported blocker stops the loop --
- * spending more requests against a stated blocker is the user's call -- but
- * leaves the goal active: the statement is not evidence it cannot be met.
- */
-export function goalDecision(state: RequestState, remainingRequests: number, idleChecks = 0): GoalDecision {
-  if (state.status === "verified") return { action: "met" };
-  if (state.status === "awaiting_human") return { action: "await_human" };
-  if (state.reported_blockers.length > 0) return { action: "stop", reason: `the model reported a blocker: ${state.reported_blockers.at(-1)!.reason}` };
-  if (remainingRequests < 1) return { action: "stop", reason: "the request budget is spent" };
-  if (idleChecks >= GOAL_IDLE_LIMIT) return { action: "stop", reason: `the model answered ${idleChecks} goal checks without acting` };
-  const missing = state.criteria.filter(item => item.kind === "command" && item.status !== "pass");
-  // An unchanged workspace failing the same way twice: rerunning is pointless,
-  // and the accepted check may be what is wrong. The model may not rewrite it;
-  // only the user can redraft a goal (S.2).
-  const stuck = missing.filter(item => (item.repeated_failures ?? 0) >= 2), rerun = missing.filter(item => !stuck.includes(item));
-  return { action: "continue", text: [
-    `Harness goal check: the goal is not met yet. Unmet: ${state.unmet.join("; ")}.`,
-    ...(rerun.length ? ["Run each missing check exactly, as a separate invocation:",
-      ...rerun.map(item => `- ${item.id}${item.guard ? " (a guard: it must keep passing)" : ""}: ${JSON.stringify(item.command)}`)] : []),
-    ...stuck.map(item => `- ${item.id} failed ${item.repeated_failures} times in a row against an unchanged workspace. Do not rerun it as is: change the work, ` +
-      "or, if the check itself may itself be broken (a syntax error, a missing tool, or a test of the wrong thing), record which check is broken and why " +
-      "with note(kind='blocked') and stop. Do not rewrite or replace an accepted check; the user can redraft the goal with /goal."),
-    "Keep working toward the goal. If something outside your control blocks it, record the specific blocker with note(kind='blocked') and stop.",
-  ].join("\n") };
-}