killeros 3.0.6 → 3.0.8

package/killeros/goal-state.ts

@@ -1,724 +1,753 @@
-import { createHash } from "node:crypto";
-import type { Stats } from "node:fs";
-import { lstat, open, type FileHandle } from "node:fs/promises";
-import path from "node:path";
-import type { GoalBlockerAudit, GoalContinueReport, GoalFileBaseline, GoalFileVerification, GoalPendingDecision, GoalState, GoalStateCommon, GoalStatus, GoalTurnDecision, GoalTurnPhase } from "./runtime.ts";
-import { safeTerminalText } from "./safe-terminal-text.ts";
-
-export const DEFAULT_GOAL_MAX_TURNS = 20;
-export const GOAL_OBJECTIVE_LIMIT = 4_000;
-export const GOAL_EVIDENCE_LIMIT = 2_000;
-export const GOAL_MAX_TURNS = 10_000;
-export const GOAL_VERSION = 1;
-const FILE_HASH_CHUNK_SIZE = 64 * 1024;
-export const FILE_HASH_LIMIT = 64 * 1024 * 1024;
-const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-type OpenGoalFile = (filePath: string) => Promise<FileHandle>;
-const openGoalFile: OpenGoalFile = (filePath) => open(filePath, "r");
-
-export interface GoalTransitionOptions {
-  resetBlockedAudit?: boolean;
-  resumeAfterManualCompaction?: true;
-  blockerAudit?: GoalBlockerAudit;
-  keepTurnForRecovery?: true;
-  resumeInterruptedTurn?: true;
-  preserveTurnAuthorization?: true;
-  decision?: GoalTurnDecision;
-}
-
-function isGoalStatus(value: unknown): value is GoalStatus {
-  return value === "active" || value === "paused" || value === "blocked" || value === "complete";
-}
-
-function finiteNonNegative(value: unknown): value is number {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0;
-}
-
-function safeNonNegativeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
-function incrementableNonNegativeInteger(value: unknown): value is number {
-  return safeNonNegativeInteger(value) && value < Number.MAX_SAFE_INTEGER;
-}
-
-function addGoalMilliseconds(accumulated: number, interval: number): number {
-  const total = accumulated + interval;
-  if (!safeNonNegativeInteger(total)) throw new Error("Goal active duration exceeds the safe integer range");
-  return total;
-}
-
-function isUnknownRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function graphemeCount(value: string): number {
-  let length = 0;
-  for (const _ of graphemeSegmenter.segment(value)) length += 1;
-  return length;
-}
-
-function isSafePersistedText(value: unknown, limit: number, required = true): value is string {
-  return typeof value === "string"
-    && (required ? Boolean(value.trim()) : true)
-    && value === value.trim()
-    && safeTerminalText(value) === value
-    && graphemeCount(value) <= limit;
-}
-
-/** Normalizes model or user text before it crosses the persisted goal boundary. */
-export function normalizeGoalText(value: string, limit: number, label: string): string {
-  if (graphemeCount(value) > limit) throw new Error(`${label} must not exceed ${limit} characters`);
-  const normalized = safeTerminalText(value).trim();
-  if (!normalized) throw new Error(`${label} must not be empty`);
-  if (graphemeCount(normalized) > limit) throw new Error(`${label} must not exceed ${limit} characters`);
-  return normalized;
-}
-
-function isGoalTurnPhase(value: unknown): value is GoalTurnPhase {
-  return value === "ready" || value === "in-flight" || value === "authorized";
-}
-
-function isGoalContinueReport(value: unknown, turns: number): value is GoalContinueReport {
-  return isUnknownRecord(value)
-    && safeNonNegativeInteger(value.turn)
-    && value.turn >= 1
-    && value.turn <= turns
-    && isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)
-    && isSafePersistedText(value.nextAction, GOAL_EVIDENCE_LIMIT);
-}
-
-function isGoalPendingDecision(value: unknown, turns: number): value is GoalPendingDecision {
-  if (!isUnknownRecord(value)
-    || !safeNonNegativeInteger(value.turn)
-    || value.turn < 1
-    || value.turn > turns
-    || !isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)) return false;
-  if (value.kind === "continue") return isSafePersistedText(value.nextAction, GOAL_EVIDENCE_LIMIT);
-  return value.kind === "blocker-audit"
-    && typeof value.blockerKey === "string"
-    && /^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.blockerKey)
-    && typeof value.streak === "number"
-    && Number.isInteger(value.streak)
-    && value.streak >= 1
-    && value.streak < 3;
-}
-
-function isGoalTurnDecision(value: unknown, turns: number): value is GoalTurnDecision {
-  if (!isUnknownRecord(value)
-    || !safeNonNegativeInteger(value.turn)
-    || value.turn < 1
-    || value.turn > turns
-    || !isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)) return false;
-  if (value.kind === "continue") return isSafePersistedText(value.nextAction, GOAL_EVIDENCE_LIMIT);
-  if (value.kind === "complete") return value.verification === "file" || value.verification === "model-reported";
-  return (value.kind === "blocker-audit"
-    && typeof value.blockerKey === "string"
-    && /^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.blockerKey)
-    && typeof value.streak === "number"
-    && Number.isInteger(value.streak)
-    && value.streak >= 1
-    && value.streak < 3)
-    || (value.kind === "blocked"
-      && typeof value.blockerKey === "string"
-      && /^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.blockerKey)
-      && value.streak === 3);
-}
-
-function isGoalFileBaseline(value: unknown): value is GoalFileBaseline {
-  if (!isUnknownRecord(value)) return false;
-  if (value.exists === false) {
-    return value.size === undefined && value.mtimeMs === undefined && value.contentHash === undefined;
-  }
-  return value.exists === true
-    && finiteNonNegative(value.size)
-    && finiteNonNegative(value.mtimeMs)
-    && (value.contentHash === undefined
-      || value.contentHash === null
-      || typeof value.contentHash === "string" && /^[a-f0-9]{64}$/u.test(value.contentHash));
-}
-
-function isAbsoluteFilePath(value: string): boolean {
-  if (!value || /^(?:https?|file):\/\//iu.test(value) || /[\\\/]$/u.test(value)) return false;
-  return path.isAbsolute(value) || path.win32.isAbsolute(value);
-}
-
-function stripUnquotedPathPunctuation(value: string): string {
-  let stripped = value;
-  while (true) {
-    const withoutMarks = stripped.replace(/[.,;:!?]+$/u, "");
-    if (withoutMarks !== stripped) {
-      stripped = withoutMarks;
-      continue;
-    }
-    const closer = stripped.at(-1);
-    const opener = closer === ")" ? "(" : closer === "]" ? "[" : closer === "}" ? "{" : undefined;
-    if (closer === undefined || opener === undefined
-      || stripped.split(closer).length <= stripped.split(opener).length) return stripped;
-    stripped = stripped.slice(0, -1);
-  }
-}
-
-function isGoalFileVerification(value: unknown): value is GoalFileVerification {
-  return isUnknownRecord(value)
-    && value.kind === "file"
-    && isSafePersistedText(value.path, GOAL_OBJECTIVE_LIMIT)
-    && isAbsoluteFilePath(value.path)
-    && isGoalFileBaseline(value.baseline);
-}
-
-function isMaxTurns(value: unknown): value is number {
-  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= GOAL_MAX_TURNS;
-}
-
-function isGoalBlockerAudit(value: unknown, turns: number, status: GoalStatus): value is GoalBlockerAudit {
-  if (!isUnknownRecord(value)
-    || typeof value.key !== "string"
-    || !/^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.key)
-    || typeof value.streak !== "number" || !Number.isInteger(value.streak) || value.streak < 1 || value.streak > 3
-    || typeof value.lastTurn !== "number" || !Number.isInteger(value.lastTurn) || value.lastTurn < 1 || value.lastTurn > turns
-    || value.evidence !== undefined && !isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)) {
-    return false;
-  }
-  if (status === "complete") return false;
-  return status === "blocked" ? value.streak === 3 : value.streak < 3;
-}
-
-export function parseGoalState(value: unknown): GoalState | undefined {
-  if (!isUnknownRecord(value)) return undefined;
-  const {
-    version,
-    revision,
-    objective,
-    status,
-    createdAt,
-    updatedAt,
-    activeMilliseconds,
-    activeStartedAt,
-    turns,
-    blockedAuditStartTurn,
-    baselineTokens,
-    result,
-    resumeAfterManualCompaction,
-    blockerAudit,
-    verification,
-    maxTurns,
-    turnPhase,
-    turnDecision,
-    lastDecision,
-    lastContinueReport,
-    stopReason,
-  } = value;
-  if (version !== GOAL_VERSION
-    || !incrementableNonNegativeInteger(revision) || revision < 1
-    || typeof objective !== "string" || !objective.trim() || safeTerminalText(objective) !== objective
-      || graphemeCount(objective.trim()) > GOAL_OBJECTIVE_LIMIT
-    || !isGoalStatus(status)
-    || !safeNonNegativeInteger(createdAt)
-    || !safeNonNegativeInteger(updatedAt)
-    || !incrementableNonNegativeInteger(activeMilliseconds)
-    || !incrementableNonNegativeInteger(turns)
-    || blockedAuditStartTurn !== undefined
-      && (!safeNonNegativeInteger(blockedAuditStartTurn) || blockedAuditStartTurn > turns)
-    || !safeNonNegativeInteger(baselineTokens)
-    || result !== undefined && !isSafePersistedText(result, GOAL_EVIDENCE_LIMIT, false)
-    || verification !== undefined && !isGoalFileVerification(verification)
-    || maxTurns !== undefined && !isMaxTurns(maxTurns)
-    || resumeAfterManualCompaction !== undefined && resumeAfterManualCompaction !== true
-    || blockerAudit !== undefined && !isGoalBlockerAudit(blockerAudit, turns, status)
-    || turnPhase !== undefined && !isGoalTurnPhase(turnPhase)
-    || turnDecision !== undefined && !isGoalPendingDecision(turnDecision, turns)
-    || lastDecision !== undefined && !isGoalTurnDecision(lastDecision, turns)
-    || lastContinueReport !== undefined && !isGoalContinueReport(lastContinueReport, turns)
-    || stopReason !== undefined && !isSafePersistedText(stopReason, GOAL_EVIDENCE_LIMIT)) {
-    return undefined;
-  }
-
-  const pending = turnDecision;
-  if (pending !== undefined && pending.turn !== turns) return undefined;
-  if (isGoalTurnDecision(lastDecision, turns)) {
-    if (lastDecision.kind === "complete") {
-      if (status !== "complete") return undefined;
-      if ((lastDecision.verification === "file") !== (verification !== undefined)) return undefined;
-    }
-    if (lastDecision.kind === "blocked" && status !== "blocked") return undefined;
-  }
-  if (pending !== undefined && turnPhase !== "authorized") return undefined;
-  if (turnPhase === "authorized" && pending === undefined) return undefined;
-  if (turnPhase === "ready" && pending !== undefined) return undefined;
-  if (status === "complete" && (turnPhase !== undefined || pending !== undefined)) return undefined;
-  if (status === "blocked" && (turnPhase !== undefined || pending !== undefined)) return undefined;
-  if (status === "paused" && turnPhase === "ready" && pending !== undefined) return undefined;
-  // A pause reason is only current while paused; on any other status it contradicts the state.
-  if (stopReason !== undefined && status !== "paused") return undefined;
-
-  const common: GoalStateCommon = {
-    version: GOAL_VERSION,
-    revision,
-    objective: objective.trim(),
-    createdAt,
-    updatedAt,
-    activeMilliseconds,
-    turns,
-    blockedAuditStartTurn: blockedAuditStartTurn ?? 0,
-    baselineTokens,
-    ...(verification === undefined ? {} : { verification }),
-    ...(maxTurns === undefined ? {} : { maxTurns }),
-    ...(turnPhase === undefined ? {} : { turnPhase }),
-    ...(pending === undefined ? {} : { turnDecision: pending }),
-    ...(lastDecision === undefined ? {} : { lastDecision }),
-    ...(lastContinueReport === undefined ? {} : { lastContinueReport }),
-    ...(stopReason === undefined ? {} : { stopReason }),
-  };
-  switch (status) {
-    case "active":
-      if (!safeNonNegativeInteger(activeStartedAt) || resumeAfterManualCompaction !== undefined) return undefined;
-      return {
-        ...common,
-        status,
-        activeStartedAt,
-        ...(result === undefined ? {} : { result }),
-        ...(blockerAudit === undefined ? {} : { blockerAudit }),
-      };
-    case "paused":
-      if (activeStartedAt !== undefined) return undefined;
-      return {
-        ...common,
-        status,
-        ...(result === undefined ? {} : { result }),
-        ...(blockerAudit === undefined ? {} : { blockerAudit }),
-        ...(resumeAfterManualCompaction === undefined ? {} : { resumeAfterManualCompaction }),
-      };
-    case "blocked":
-      if (activeStartedAt !== undefined || resumeAfterManualCompaction !== undefined || typeof result !== "string") return undefined;
-      return { ...common, status, result, ...(blockerAudit === undefined ? {} : { blockerAudit }) };
-    case "complete":
-      if (activeStartedAt !== undefined || resumeAfterManualCompaction !== undefined
-        || typeof result !== "string" || blockerAudit !== undefined) return undefined;
-      return { ...common, status, result };
-  }
-}
-
-function sameFile(left: Stats, right: Stats): boolean {
-  return left.dev === right.dev
-    && left.ino === right.ino
-    && left.size === right.size
-    && left.mtimeMs === right.mtimeMs;
-}
-
-async function hashFile(handle: FileHandle, inspected: Stats): Promise<string> {
-  const hash = createHash("sha256");
-  const buffer = Buffer.allocUnsafe(FILE_HASH_CHUNK_SIZE);
-  let position = 0;
-  while (position < inspected.size) {
-    const length = Math.min(buffer.length, inspected.size - position);
-    const { bytesRead } = await handle.read(buffer, 0, length, position);
-    if (bytesRead === 0) throw new Error("Goal deliverable changed while it was being inspected");
-    hash.update(buffer.subarray(0, bytesRead));
-    position += bytesRead;
-  }
-  if (!sameFile(inspected, await handle.stat())) {
-    throw new Error("Goal deliverable changed while it was being inspected");
-  }
-  return hash.digest("hex");
-}
-
-/** Captures a file baseline with bounded asynchronous I/O and descriptor identity checks. */
-export async function captureGoalFileBaseline(
-  filePath: string,
-  openFile: OpenGoalFile = openGoalFile,
-): Promise<GoalFileBaseline> {
-  let inspected: Stats;
-  try {
-    inspected = await lstat(filePath);
-  } catch (error) {
-    if (isUnknownRecord(error) && error.code === "ENOENT") return { exists: false };
-    throw error;
-  }
-  const baseline = { exists: true as const, size: inspected.size, mtimeMs: inspected.mtimeMs };
-  if (!inspected.isFile() || inspected.size > FILE_HASH_LIMIT) return baseline;
-
-  let handle: FileHandle | undefined;
-  try {
-    handle = await openFile(filePath);
-    if (!sameFile(inspected, await handle.stat())) {
-      throw new Error("Goal deliverable changed while it was being inspected");
-    }
-    return { ...baseline, contentHash: await hashFile(handle, inspected) };
-  } catch (error) {
-    if (error instanceof Error && error.message === "Goal deliverable changed while it was being inspected") throw error;
-    return { ...baseline, contentHash: null };
-  } finally {
-    await handle?.close();
-  }
-}
-
-const GOAL_URL_PATTERN = /(?:https?|file):\/\/[^\s"'`]+/giu;
-const GOAL_QUOTED_PATTERN = /`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)'/gu;
-const GOAL_ABSOLUTE_PATTERN = /(?:^|[\s"'`(\[{,;])([A-Za-z]:[\\/][^\s,;'"`]+|\/[^\s,;'"`]+)/gu;
-const GOAL_LIST_FILE_PATTERN = /(?:\band\b|\bor\b|\bplus\b|\balong\s+with\b|[,;&+])\s*(?:`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)'|((?:\.{1,2}[\\/])*[A-Za-z0-9_][A-Za-z0-9_.-]*(?:[\\/][A-Za-z0-9_.-]+)*\.[A-Za-z0-9]{1,12})\b|(Makefile|Dockerfile|\.gitignore)\b)/giu;
-const GOAL_RELATIVE_FILE_PATTERN = /(?:^|[\s"'`(\[{,;])((?:\.{1,2}[\\/])*[A-Za-z0-9_][A-Za-z0-9_.-]*(?:[\\/][A-Za-z0-9_.-]+)*\.[A-Za-z0-9]{1,12})\b/gu;
-
-function isQuotedGoalFileMention(raw: string): boolean {
-  const value = raw.trim();
-  if (!value || /\p{Cc}/u.test(value) || /^(?:https?|file):\/\//iu.test(value) || /[\\/]$/u.test(value)) return false;
-  return /[\/\\.:]/u.test(value);
-}
-
-function isPathShapedGoalCandidate(raw: string): boolean {
-  if (/\p{Cc}/u.test(raw)) return false;
-  const value = raw.trim();
-  if (!value || /[\\\/]$/u.test(value)) return false;
-  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return true;
-  if (URL.canParse(value)) return false;
-  return /[\\\/]/u.test(value)
-    || value.startsWith(".") && value !== "." && value !== ".."
-    || /\.[A-Za-z0-9]{1,12}$/u.test(value);
-}
-
-function goalPathIdentity(filePath: string): string {
-  const nativePath = process.platform === "win32" ? filePath.replaceAll("/", "\\") : filePath;
-  // Parent segments may traverse symlinks; keep them distinct without filesystem proof.
-  const normalized = nativePath.split(path.sep).includes("..") ? nativePath : path.normalize(nativePath);
-  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
-}
-
-function absoluteGoalFilePath(value: string, cwd: string): string {
-  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return value;
-  const nativePath = process.platform === "win32" ? value.replaceAll("/", "\\") : value;
-  // Resolving parent segments lexically can select a different file across a directory symlink.
-  return nativePath.split(path.sep).includes("..")
-    ? `${path.resolve(cwd)}${path.sep}${nativePath}`
-    : path.resolve(cwd, value);
-}
-
-function normalizeGoalFileMention(raw: string, cwd: string, quoted = false): string | undefined {
-  const trimmed = raw.trim();
-  const value = quoted ? trimmed : stripUnquotedPathPunctuation(trimmed);
-  if (!value || /\p{Cc}/u.test(value) || !quoted && /\s/u.test(value)) return undefined;
-  const absolute = absoluteGoalFilePath(value, cwd);
-  if (!isAbsoluteFilePath(absolute)) return undefined;
-  return goalPathIdentity(absolute);
-}
-
-/** Counts distinct path-shaped mentions so several files cannot bind proof to one. */
-function countGoalTargetFiles(objective: string, cwd: string, target: string, targetQuoted: boolean): number {
-  const source = objective.replace(GOAL_URL_PATTERN, " ");
-  // ponytail: Only these exact prose forms are excluded; quote ambiguous bare filenames for exact proof.
-  const prose = source.replace(GOAL_QUOTED_PATTERN, " ")
-    .replace(/(?<![A-Za-z0-9_.\\/-])version\s+\d+(?:\.\d+)+(?=$|[\s,;:!?)\]}]|\.(?=$|[\s,;:!?)\]}]))/giu, " ")
-    .replace(/(?<![A-Za-z0-9_.\\/-])for\s+Node\.js(?!\s+compatibility\.[A-Za-z0-9])(?=$|[\s,;:!?)\]}]|\.(?=$|[\s,;:!?)\]}]))|(?<![A-Za-z0-9_.\\/-])Node\.js\s+compatibility(?=$|[\s,;:!?)\]}]|\.(?=$|[\s,;:!?)\]}]))/giu, " ");
-  const mentions = new Set<string>();
-  const add = (raw: string, quoted = false): void => {
-    const normalized = normalizeGoalFileMention(raw, cwd, quoted);
-    if (normalized) mentions.add(normalized);
-  };
-  add(target, targetQuoted);
-  for (const match of source.matchAll(GOAL_QUOTED_PATTERN)) {
-    const raw = match[1] ?? match[2] ?? match[3] ?? "";
-    if (isQuotedGoalFileMention(raw)) add(raw, true);
-  }
-  for (const match of source.matchAll(GOAL_LIST_FILE_PATTERN)) {
-    const quoted = match[1] ?? match[2] ?? match[3];
-    if (quoted !== undefined) add(quoted, true);
-  }
-  for (const match of prose.matchAll(GOAL_ABSOLUTE_PATTERN)) {
-    if (match[1]) add(stripUnquotedPathPunctuation(match[1].trim()));
-  }
-  for (const match of prose.matchAll(GOAL_LIST_FILE_PATTERN)) {
-    if (match[4]) add(match[4]);
-    if (match[5]) add(match[5]);
-  }
-  for (const match of prose.matchAll(GOAL_RELATIVE_FILE_PATTERN)) {
-    if (match[1]) add(match[1]);
-  }
-  return mentions.size;
-}
-
-/** Captures one explicit output path so goal completion can verify its creation or modification. */
-export async function inferGoalVerification(objective: string, cwd: string): Promise<GoalFileVerification | undefined> {
-  const candidates: Array<{ raw: string; quoted: boolean }> = [];
-  const destination = /\b(?:create|write|save|generate)\b[^\r\n]{0,160}?\b(?:file|document|markdown|report|spreadsheet|presentation|image)\b\s+(?:to|at|as|destination(?:\s+is)?|output(?:\s+(?:to|at))?)\b\s*(?:`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)'|([A-Za-z]:\\[^\s,;]+|\/[^\s,;]+))/giu;
-  for (const match of objective.matchAll(destination)) {
-    const quoted = match[1] ?? match[2] ?? match[3];
-    candidates.push({
-      raw: quoted !== undefined ? quoted : stripUnquotedPathPunctuation((match[4] ?? "").trim()),
-      quoted: quoted !== undefined,
-    });
-  }
-  const direct = /\b(?:update|edit|fix|refactor|migrate)\s+(`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)')/giu;
-  for (const match of objective.matchAll(direct)) {
-    const quoted = match[2] ?? match[3] ?? match[4];
-    if (quoted !== undefined) candidates.push({ raw: quoted, quoted: true });
-  }
-  const operands = new Set<string>();
-  const resolved = new Map<string, { filePath: string; quoted: boolean }>();
-  for (const candidate of candidates) {
-    const value = candidate.raw.trim();
-    if (!value || /\p{Cc}/u.test(value)) continue;
-    const alreadyAbsolute = path.isAbsolute(value) || path.win32.isAbsolute(value);
-    if (!alreadyAbsolute && URL.canParse(value)) continue;
-    const absolute = absoluteGoalFilePath(value, cwd);
-    const identity = goalPathIdentity(absolute);
-    operands.add(identity);
-    if (!isPathShapedGoalCandidate(candidate.raw) || !isAbsoluteFilePath(absolute)) continue;
-    const existing = resolved.get(identity);
-    resolved.set(identity, {
-      filePath: existing?.filePath ?? absolute,
-      quoted: candidate.quoted || existing?.quoted === true,
-    });
-  }
-  if (operands.size !== 1 || resolved.size !== 1) return undefined;
-  // A goal that names several files must not verify from one file alone.
-  // Repeated references to the same file count as one target.
-  const target = resolved.values().next().value;
-  if (target === undefined || countGoalTargetFiles(objective, cwd, target.filePath, target.quoted) > 1) return undefined;
-  return { kind: "file", path: target.filePath, baseline: await captureGoalFileBaseline(target.filePath) };
-}
-
-export async function verifyGoalDeliverable(verification: GoalFileVerification): Promise<void> {
-  let artifact: Stats;
-  try {
-    artifact = await lstat(verification.path);
-  } catch {
-    throw new Error(`Goal deliverable is not a regular file at the required path: ${verification.path}`);
-  }
-  if (!artifact.isFile()) {
-    throw new Error(`Goal deliverable is not a regular file at the required path: ${verification.path}`);
-  }
-  if (!verification.baseline.exists) return;
-  if (verification.baseline.contentHash === null) {
-    throw new Error(`Goal deliverable content cannot be verified: ${verification.path}`);
-  }
-  if (verification.baseline.contentHash !== undefined) {
-    const current = await captureGoalFileBaseline(verification.path);
-    if (!current.exists || current.contentHash === null) {
-      throw new Error(`Goal deliverable content cannot be verified: ${verification.path}`);
-    }
-    if (current.contentHash === verification.baseline.contentHash) {
-      throw new Error(`Goal deliverable has not changed since the goal started: ${verification.path}`);
-    }
-  }
-  if (verification.baseline.contentHash === undefined
-    && artifact.size === verification.baseline.size
-    && artifact.mtimeMs === verification.baseline.mtimeMs) {
-    throw new Error(`Goal deliverable has not changed since the goal started: ${verification.path}`);
-  }
-}
-
-export function boundGoalText(value: string, limit = GOAL_EVIDENCE_LIMIT): string {
-  const safe = safeTerminalText(value).trim();
-  return [...graphemeSegmenter.segment(safe)]
-    .slice(0, limit)
-    .map(({ segment }) => segment)
-    .join("")
-    .trimEnd();
-}
-
-export function validateGoalObjective(input: string): string | undefined {
-  const objective = input.trim();
-  if (!objective || safeTerminalText(objective) !== objective) return undefined;
-  return graphemeCount(objective) <= GOAL_OBJECTIVE_LIMIT ? objective : undefined;
-}
-
-export function goalElapsedMilliseconds(state: GoalState, now: number): number {
-  const activeInterval = state.status === "active" ? Math.max(0, now - state.activeStartedAt) : 0;
-  return addGoalMilliseconds(state.activeMilliseconds, activeInterval);
-}
-
-export function commonGoalState(state: GoalState): GoalStateCommon {
-  return {
-    version: state.version,
-    revision: state.revision,
-    objective: state.objective,
-    createdAt: state.createdAt,
-    updatedAt: state.updatedAt,
-    activeMilliseconds: state.activeMilliseconds,
-    turns: state.turns,
-    blockedAuditStartTurn: state.blockedAuditStartTurn,
-    baselineTokens: state.baselineTokens,
-    ...(state.verification === undefined ? {} : { verification: state.verification }),
-    ...(state.maxTurns === undefined ? {} : { maxTurns: state.maxTurns }),
-    ...(state.turnPhase === undefined ? {} : { turnPhase: state.turnPhase }),
-    ...(state.turnDecision === undefined ? {} : { turnDecision: state.turnDecision }),
-    ...(state.lastDecision === undefined ? {} : { lastDecision: state.lastDecision }),
-    ...(state.lastContinueReport === undefined ? {} : { lastContinueReport: state.lastContinueReport }),
-    ...(state.status === "paused" && state.stopReason !== undefined ? { stopReason: state.stopReason } : {}),
-  };
-}
-
-export function stopGoalClock(state: GoalState, now: number): GoalStateCommon {
-  const common = commonGoalState(state);
-  return state.status === "active"
-    ? { ...common, activeMilliseconds: addGoalMilliseconds(common.activeMilliseconds, Math.max(0, now - state.activeStartedAt)) }
-    : common;
-}
-
-export function createNewGoalState(
-  objective: string,
-  baselineTokens: number,
-  verification: GoalFileVerification | undefined,
-  now: number,
-  controls: { maxTurns?: number } = {},
-): GoalState {
-  return {
-    version: GOAL_VERSION,
-    revision: 1,
-    objective,
-    status: "active",
-    createdAt: now,
-    updatedAt: now,
-    activeMilliseconds: 0,
-    activeStartedAt: now,
-    turns: 0,
-    blockedAuditStartTurn: 0,
-    baselineTokens,
-    turnPhase: "ready",
-    ...(verification === undefined ? {} : { verification }),
-    ...(controls.maxTurns === undefined ? {} : { maxTurns: controls.maxTurns }),
-  };
-}
-
-function nextRevision(current: { revision: number }): number {
-  if (!incrementableNonNegativeInteger(current.revision)) {
-    throw new Error("Goal revision cannot advance safely");
-  }
-  return current.revision + 1;
-}
-
-export function beginGoalTurnState(
-  current: Extract<GoalState, { status: "active" }>,
-  now: number,
-): GoalState {
-  if (!incrementableNonNegativeInteger(current.turns)) throw new Error("Goal turn counter cannot advance safely");
-  const { turnDecision: _decision, turnPhase: _phase, ...withoutPending } = current;
-  return {
-    ...withoutPending,
-    revision: nextRevision(current),
-    turns: current.turns + 1,
-    updatedAt: now,
-    turnPhase: "in-flight",
-    ...(current.turnDecision === undefined ? {} : { lastDecision: current.turnDecision }),
-  };
-}
-
-export function checkpointActiveGoalState(
-  current: Extract<GoalState, { status: "active" }>,
-  now: number,
-): GoalState {
-  return {
-    ...stopGoalClock(current, now),
-    revision: nextRevision(current),
-    status: "active",
-    updatedAt: now,
-    activeStartedAt: now,
-    ...(current.result === undefined ? {} : { result: current.result }),
-    ...(current.blockerAudit === undefined ? {} : { blockerAudit: current.blockerAudit }),
-  };
-}
-
-export function pauseGoalState(
-  current: GoalState,
-  result: string | undefined,
-  now: number,
-  resumeAfterManualCompaction = false,
-  preserveTurnAuthorization = false,
-): GoalState {
-  const common = stopGoalClock(current, now);
-  const { turnDecision: _decision, turnPhase: _phase, ...withoutPending } = common;
-  return {
-    ...withoutPending,
-    status: "paused",
-    turnPhase: preserveTurnAuthorization ? current.turnPhase : "ready",
-    ...(preserveTurnAuthorization && current.turnDecision !== undefined ? { turnDecision: current.turnDecision } : {}),
-    ...(result === undefined ? {} : { result }),
-    ...(result === undefined ? {} : { stopReason: boundGoalText(result) }),
-    ...(current.blockerAudit === undefined ? {} : { blockerAudit: current.blockerAudit }),
-    ...(resumeAfterManualCompaction ? { resumeAfterManualCompaction: true as const } : {}),
-  };
-}
-
-export function checkpointPausedGoalState(
-  current: Extract<GoalState, { status: "paused" }>,
-  now: number,
-): GoalState {
-  const { resumeAfterManualCompaction: _resume, ...paused } = current;
-  return { ...paused, revision: nextRevision(current), updatedAt: now };
-}
-
-export function recordGoalDecision(
-  state: Extract<GoalState, { status: "active" }>,
-  decision: GoalPendingDecision,
-  now: number,
-): Extract<GoalState, { status: "active" }> {
-  if (decision.turn !== state.turns) throw new Error("Goal decision does not match the active turn");
-  return {
-    ...state,
-    revision: nextRevision(state),
-    updatedAt: now,
-    turnPhase: "authorized",
-    turnDecision: decision,
-    lastDecision: decision,
-    ...(decision.kind === "continue"
-      ? { lastContinueReport: { turn: decision.turn, evidence: decision.evidence, nextAction: decision.nextAction } }
-      : {}),
-  };
-}
-
-export function transitionGoalState(
-  current: GoalState,
-  status: GoalStatus,
-  result: string | undefined,
-  options: GoalTransitionOptions,
-  now: number,
-): GoalState {
-  const stopped = stopGoalClock(current, now);
-  const common: GoalStateCommon = {
-    ...stopped,
-    revision: nextRevision(stopped),
-    updatedAt: now,
-    blockedAuditStartTurn: options.resetBlockedAudit ? stopped.turns : stopped.blockedAuditStartTurn,
-  };
-  const blockerAudit = options.resetBlockedAudit ? undefined : options.blockerAudit ?? current.blockerAudit;
-  const pending = options.preserveTurnAuthorization ? current.turnDecision : undefined;
-  const { turnDecision: _decision, turnPhase: _phase, stopReason: _stopReason, ...withoutPending } = common;
-  switch (status) {
-    case "active":
-      return {
-        ...withoutPending,
-        ...(current.status === "blocked" ? { lastDecision: undefined } : {}),
-        status,
-        activeStartedAt: now,
-        turnPhase: pending !== undefined ? "authorized" : options.resumeInterruptedTurn ? "in-flight" : "ready",
-        ...(pending === undefined ? {} : { turnDecision: pending }),
-        ...(blockerAudit === undefined ? {} : { blockerAudit }),
-      };
-    case "paused":
-      return {
-        ...withoutPending,
-        status,
-        turnPhase: options.keepTurnForRecovery ? current.turnPhase : "ready",
-        ...(options.keepTurnForRecovery && current.turnDecision !== undefined ? { turnDecision: current.turnDecision } : {}),
-        ...(result === undefined ? {} : { result, stopReason: boundGoalText(result) }),
-        ...(blockerAudit === undefined ? {} : { blockerAudit }),
-        ...(options.resumeAfterManualCompaction === undefined ? {} : { resumeAfterManualCompaction: true }),
-      };
-    case "blocked":
-      if (result === undefined) throw new Error("A blocked goal requires a result");
-      return {
-        ...withoutPending,
-        status,
-        result,
-        ...(options.decision === undefined ? {} : { lastDecision: options.decision }),
-        ...(blockerAudit === undefined ? {} : { blockerAudit }),
-      };
-    case "complete":
-      if (result === undefined) throw new Error("A complete goal requires a result");
-      return {
-        ...withoutPending,
-        status,
-        result,
-        ...(options.decision === undefined ? {} : { lastDecision: options.decision }),
-      };
-  }
-}
+import { createHash } from "node:crypto";
+import type { Stats } from "node:fs";
+import { lstat, open, type FileHandle } from "node:fs/promises";
+import path from "node:path";
+import type { GoalBlockerAudit, GoalContinueReport, GoalFileBaseline, GoalFileVerification, GoalPendingDecision, GoalState, GoalStateCommon, GoalStatus, GoalTurnDecision, GoalTurnPhase } from "./runtime.ts";
+import { safeTerminalText } from "./safe-terminal-text.ts";
+
+export const DEFAULT_GOAL_MAX_TURNS = 20;
+export const GOAL_OBJECTIVE_LIMIT = 4_000;
+export const GOAL_EVIDENCE_LIMIT = 2_000;
+export const GOAL_MAX_TURNS = 10_000;
+export const GOAL_VERSION = 1;
+const FILE_HASH_CHUNK_SIZE = 64 * 1024;
+export const FILE_HASH_LIMIT = 64 * 1024 * 1024;
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+type OpenGoalFile = (filePath: string) => Promise<FileHandle>;
+const openGoalFile: OpenGoalFile = (filePath) => open(filePath, "r");
+
+export interface GoalTransitionOptions {
+  resetBlockedAudit?: boolean;
+  resumeAfterManualCompaction?: true;
+  blockerAudit?: GoalBlockerAudit;
+  keepTurnForRecovery?: true;
+  resumeInterruptedTurn?: true;
+  preserveTurnAuthorization?: true;
+  decision?: GoalTurnDecision;
+}
+
+function isGoalStatus(value: unknown): value is GoalStatus {
+  return value === "active" || value === "paused" || value === "blocked" || value === "complete";
+}
+
+function finiteNonNegative(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function safeNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function incrementableNonNegativeInteger(value: unknown): value is number {
+  return safeNonNegativeInteger(value) && value < Number.MAX_SAFE_INTEGER;
+}
+
+function addGoalMilliseconds(accumulated: number, interval: number): number {
+  const total = accumulated + interval;
+  if (!safeNonNegativeInteger(total)) throw new Error("Goal active duration exceeds the safe integer range");
+  return total;
+}
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function graphemeCount(value: string): number {
+  let length = 0;
+  for (const _ of graphemeSegmenter.segment(value)) length += 1;
+  return length;
+}
+
+function isSafePersistedText(value: unknown, limit: number, required = true): value is string {
+  return typeof value === "string"
+    && (required ? Boolean(value.trim()) : true)
+    && value === value.trim()
+    && safeTerminalText(value) === value
+    && graphemeCount(value) <= limit;
+}
+
+/** Normalizes model or user text before it crosses the persisted goal boundary. */
+export function normalizeGoalText(value: string, limit: number, label: string): string {
+  if (graphemeCount(value) > limit) throw new Error(`${label} must not exceed ${limit} characters`);
+  const normalized = safeTerminalText(value).trim();
+  if (!normalized) throw new Error(`${label} must not be empty`);
+  if (graphemeCount(normalized) > limit) throw new Error(`${label} must not exceed ${limit} characters`);
+  return normalized;
+}
+
+function isGoalTurnPhase(value: unknown): value is GoalTurnPhase {
+  return value === "ready" || value === "in-flight" || value === "authorized";
+}
+
+function isGoalContinueReport(value: unknown, turns: number): value is GoalContinueReport {
+  return isUnknownRecord(value)
+    && safeNonNegativeInteger(value.turn)
+    && value.turn >= 1
+    && value.turn <= turns
+    && isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)
+    && isSafePersistedText(value.nextAction, GOAL_EVIDENCE_LIMIT);
+}
+
+function isGoalPendingDecision(value: unknown, turns: number): value is GoalPendingDecision {
+  if (!isUnknownRecord(value)
+    || !safeNonNegativeInteger(value.turn)
+    || value.turn < 1
+    || value.turn > turns
+    || !isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)) return false;
+  if (value.kind === "continue") return isSafePersistedText(value.nextAction, GOAL_EVIDENCE_LIMIT);
+  return value.kind === "blocker-audit"
+    && typeof value.blockerKey === "string"
+    && /^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.blockerKey)
+    && typeof value.streak === "number"
+    && Number.isInteger(value.streak)
+    && value.streak >= 1
+    && value.streak < 3;
+}
+
+function isGoalTurnDecision(value: unknown, turns: number): value is GoalTurnDecision {
+  if (!isUnknownRecord(value)
+    || !safeNonNegativeInteger(value.turn)
+    || value.turn < 1
+    || value.turn > turns
+    || !isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)) return false;
+  if (value.kind === "continue") return isSafePersistedText(value.nextAction, GOAL_EVIDENCE_LIMIT);
+  if (value.kind === "complete") return value.verification === "file" || value.verification === "model-reported";
+  return (value.kind === "blocker-audit"
+    && typeof value.blockerKey === "string"
+    && /^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.blockerKey)
+    && typeof value.streak === "number"
+    && Number.isInteger(value.streak)
+    && value.streak >= 1
+    && value.streak < 3)
+    || (value.kind === "blocked"
+      && typeof value.blockerKey === "string"
+      && /^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.blockerKey)
+      && value.streak === 3);
+}
+
+function isGoalFileBaseline(value: unknown): value is GoalFileBaseline {
+  if (!isUnknownRecord(value)) return false;
+  if (value.exists === false) {
+    return value.size === undefined && value.mtimeMs === undefined && value.contentHash === undefined;
+  }
+  return value.exists === true
+    && finiteNonNegative(value.size)
+    && finiteNonNegative(value.mtimeMs)
+    && (value.contentHash === undefined
+      || value.contentHash === null
+      || typeof value.contentHash === "string" && /^[a-f0-9]{64}$/u.test(value.contentHash));
+}
+
+function isAbsoluteFilePath(value: string): boolean {
+  if (!value || /^(?:https?|file):\/\//iu.test(value) || /[\\\/]$/u.test(value)) return false;
+  return path.isAbsolute(value) || path.win32.isAbsolute(value);
+}
+
+function stripUnquotedPathPunctuation(value: string): string {
+  let stripped = value;
+  while (true) {
+    const withoutMarks = stripped.replace(/[.,;:!?]+$/u, "");
+    if (withoutMarks !== stripped) {
+      stripped = withoutMarks;
+      continue;
+    }
+    const closer = stripped.at(-1);
+    const opener = closer === ")" ? "(" : closer === "]" ? "[" : closer === "}" ? "{" : undefined;
+    if (closer === undefined || opener === undefined
+      || stripped.split(closer).length <= stripped.split(opener).length) return stripped;
+    stripped = stripped.slice(0, -1);
+  }
+}
+
+function isGoalFileVerification(value: unknown): value is GoalFileVerification {
+  return isUnknownRecord(value)
+    && value.kind === "file"
+    && isSafePersistedText(value.path, GOAL_OBJECTIVE_LIMIT)
+    && isAbsoluteFilePath(value.path)
+    && isGoalFileBaseline(value.baseline);
+}
+
+function isMaxTurns(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= GOAL_MAX_TURNS;
+}
+
+function isGoalBlockerAudit(value: unknown, turns: number, status: GoalStatus): value is GoalBlockerAudit {
+  if (!isUnknownRecord(value)
+    || typeof value.key !== "string"
+    || !/^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.key)
+    || typeof value.streak !== "number" || !Number.isInteger(value.streak) || value.streak < 1 || value.streak > 3
+    || typeof value.lastTurn !== "number" || !Number.isInteger(value.lastTurn) || value.lastTurn < 1 || value.lastTurn > turns
+    || value.evidence !== undefined && !isSafePersistedText(value.evidence, GOAL_EVIDENCE_LIMIT)) {
+    return false;
+  }
+  if (status === "complete") return false;
+  return status === "blocked" ? value.streak === 3 : value.streak < 3;
+}
+
+export function parseGoalState(value: unknown): GoalState | undefined {
+  if (!isUnknownRecord(value)) return undefined;
+  const {
+    version,
+    revision,
+    objective,
+    status,
+    createdAt,
+    updatedAt,
+    activeMilliseconds,
+    activeStartedAt,
+    turns,
+    blockedAuditStartTurn,
+    baselineTokens,
+    result,
+    resumeAfterManualCompaction,
+    blockerAudit,
+    verification,
+    maxTurns,
+    turnPhase,
+    turnDecision,
+    lastDecision,
+    lastContinueReport,
+    stopReason,
+  } = value;
+  if (version !== GOAL_VERSION
+    || !incrementableNonNegativeInteger(revision) || revision < 1
+    || typeof objective !== "string" || !objective.trim() || safeTerminalText(objective) !== objective
+      || graphemeCount(objective.trim()) > GOAL_OBJECTIVE_LIMIT
+    || !isGoalStatus(status)
+    || !safeNonNegativeInteger(createdAt)
+    || !safeNonNegativeInteger(updatedAt)
+    || !incrementableNonNegativeInteger(activeMilliseconds)
+    || !incrementableNonNegativeInteger(turns)
+    || blockedAuditStartTurn !== undefined
+      && (!safeNonNegativeInteger(blockedAuditStartTurn) || blockedAuditStartTurn > turns)
+    || !safeNonNegativeInteger(baselineTokens)
+    || result !== undefined && !isSafePersistedText(result, GOAL_EVIDENCE_LIMIT, false)
+    || verification !== undefined && !isGoalFileVerification(verification)
+    || maxTurns !== undefined && !isMaxTurns(maxTurns)
+    || resumeAfterManualCompaction !== undefined && resumeAfterManualCompaction !== true
+    || blockerAudit !== undefined && !isGoalBlockerAudit(blockerAudit, turns, status)
+    || turnPhase !== undefined && !isGoalTurnPhase(turnPhase)
+    || turnDecision !== undefined && !isGoalPendingDecision(turnDecision, turns)
+    || lastDecision !== undefined && !isGoalTurnDecision(lastDecision, turns)
+    || lastContinueReport !== undefined && !isGoalContinueReport(lastContinueReport, turns)
+    || stopReason !== undefined && !isSafePersistedText(stopReason, GOAL_EVIDENCE_LIMIT)) {
+    return undefined;
+  }
+
+  const pending = turnDecision;
+  if (pending !== undefined && pending.turn !== turns) return undefined;
+  if (isGoalTurnDecision(lastDecision, turns)) {
+    if (lastDecision.kind === "complete") {
+      if (status !== "complete") return undefined;
+      if ((lastDecision.verification === "file") !== (verification !== undefined)) return undefined;
+    }
+    if (lastDecision.kind === "blocked" && status !== "blocked") return undefined;
+  }
+  if (pending !== undefined && turnPhase !== "authorized") return undefined;
+  if (turnPhase === "authorized" && pending === undefined) return undefined;
+  if (turnPhase === "ready" && pending !== undefined) return undefined;
+  if (status === "complete" && (turnPhase !== undefined || pending !== undefined)) return undefined;
+  if (status === "blocked" && (turnPhase !== undefined || pending !== undefined)) return undefined;
+  if (status === "paused" && turnPhase === "ready" && pending !== undefined) return undefined;
+  // A pause reason is only current while paused; on any other status it contradicts the state.
+  if (stopReason !== undefined && status !== "paused") return undefined;
+
+  const common: GoalStateCommon = {
+    version: GOAL_VERSION,
+    revision,
+    objective: objective.trim(),
+    createdAt,
+    updatedAt,
+    activeMilliseconds,
+    turns,
+    blockedAuditStartTurn: blockedAuditStartTurn ?? 0,
+    baselineTokens,
+    ...(verification === undefined ? {} : { verification }),
+    ...(maxTurns === undefined ? {} : { maxTurns }),
+    ...(turnPhase === undefined ? {} : { turnPhase }),
+    ...(pending === undefined ? {} : { turnDecision: pending }),
+    ...(lastDecision === undefined ? {} : { lastDecision }),
+    ...(lastContinueReport === undefined ? {} : { lastContinueReport }),
+    ...(stopReason === undefined ? {} : { stopReason }),
+  };
+  switch (status) {
+    case "active":
+      if (!safeNonNegativeInteger(activeStartedAt) || resumeAfterManualCompaction !== undefined) return undefined;
+      return {
+        ...common,
+        status,
+        activeStartedAt,
+        ...(result === undefined ? {} : { result }),
+        ...(blockerAudit === undefined ? {} : { blockerAudit }),
+      };
+    case "paused":
+      if (activeStartedAt !== undefined) return undefined;
+      return {
+        ...common,
+        status,
+        ...(result === undefined ? {} : { result }),
+        ...(blockerAudit === undefined ? {} : { blockerAudit }),
+        ...(resumeAfterManualCompaction === undefined ? {} : { resumeAfterManualCompaction }),
+      };
+    case "blocked":
+      if (activeStartedAt !== undefined || resumeAfterManualCompaction !== undefined || typeof result !== "string") return undefined;
+      return { ...common, status, result, ...(blockerAudit === undefined ? {} : { blockerAudit }) };
+    case "complete":
+      if (activeStartedAt !== undefined || resumeAfterManualCompaction !== undefined
+        || typeof result !== "string" || blockerAudit !== undefined) return undefined;
+      return { ...common, status, result };
+  }
+}
+
+function sameFile(left: Stats, right: Stats): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.size === right.size
+    && left.mtimeMs === right.mtimeMs;
+}
+
+async function hashFile(handle: FileHandle, inspected: Stats): Promise<string> {
+  const hash = createHash("sha256");
+  const buffer = Buffer.allocUnsafe(FILE_HASH_CHUNK_SIZE);
+  let position = 0;
+  while (position < inspected.size) {
+    const length = Math.min(buffer.length, inspected.size - position);
+    const { bytesRead } = await handle.read(buffer, 0, length, position);
+    if (bytesRead === 0) throw new Error("Goal deliverable changed while it was being inspected");
+    hash.update(buffer.subarray(0, bytesRead));
+    position += bytesRead;
+  }
+  if (!sameFile(inspected, await handle.stat())) {
+    throw new Error("Goal deliverable changed while it was being inspected");
+  }
+  return hash.digest("hex");
+}
+
+/** Captures a file baseline with bounded asynchronous I/O and descriptor identity checks. */
+export async function captureGoalFileBaseline(
+  filePath: string,
+  openFile: OpenGoalFile = openGoalFile,
+): Promise<GoalFileBaseline> {
+  let inspected: Stats;
+  try {
+    inspected = await lstat(filePath);
+  } catch (error) {
+    if (isUnknownRecord(error) && error.code === "ENOENT") return { exists: false };
+    throw error;
+  }
+  const baseline = { exists: true as const, size: inspected.size, mtimeMs: inspected.mtimeMs };
+  if (!inspected.isFile() || inspected.size > FILE_HASH_LIMIT) return baseline;
+
+  let handle: FileHandle | undefined;
+  try {
+    handle = await openFile(filePath);
+    if (!sameFile(inspected, await handle.stat())) {
+      throw new Error("Goal deliverable changed while it was being inspected");
+    }
+    return { ...baseline, contentHash: await hashFile(handle, inspected) };
+  } catch (error) {
+    if (error instanceof Error && error.message === "Goal deliverable changed while it was being inspected") throw error;
+    return { ...baseline, contentHash: null };
+  } finally {
+    await handle?.close();
+  }
+}
+
+const GOAL_URL_PATTERN = /(?:https?|file):\/\/[^\s"'`]+/giu;
+const GOAL_QUOTED_PATTERN = /`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)'/gu;
+const GOAL_ABSOLUTE_PATTERN = /(?:^|[\s"'`(\[{,;])([A-Za-z]:[\\/][^\s,;'"`]+|\/[^\s,;'"`]+)/gu;
+const GOAL_LIST_FILE_PATTERN = /(?:\band\b|\bor\b|\bplus\b|\balong\s+with\b|[,;&+])\s*(?:`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)'|((?:\.{1,2}[\\/])*[A-Za-z0-9_][A-Za-z0-9_.-]*(?:[\\/][A-Za-z0-9_.-]+)*\.[A-Za-z0-9]{1,12})\b|(Makefile|Dockerfile|\.gitignore)\b)/giu;
+const GOAL_RELATIVE_FILE_PATTERN = /(?:^|[\s"'`(\[{,;])((?:\.{1,2}[\\/])*[A-Za-z0-9_][A-Za-z0-9_.-]*(?:[\\/][A-Za-z0-9_.-]+)*\.[A-Za-z0-9]{1,12})\b/gu;
+
+function isQuotedGoalFileMention(raw: string): boolean {
+  const value = raw.trim();
+  if (!value || /\p{Cc}/u.test(value) || /^(?:https?|file):\/\//iu.test(value) || /[\\/]$/u.test(value)) return false;
+  return /[\/\\.:]/u.test(value);
+}
+
+function isPathShapedGoalCandidate(raw: string): boolean {
+  if (/\p{Cc}/u.test(raw)) return false;
+  const value = raw.trim();
+  if (!value || /[\\\/]$/u.test(value)) return false;
+  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return true;
+  if (URL.canParse(value)) return false;
+  return /[\\\/]/u.test(value)
+    || value.startsWith(".") && value !== "." && value !== ".."
+    || /\.[A-Za-z0-9]{1,12}$/u.test(value);
+}
+
+function goalPathIdentity(filePath: string): string {
+  const nativePath = filePath.replaceAll("/", "\\");
+  // Parent segments may traverse symlinks; keep them distinct without filesystem proof.
+  const normalized = nativePath.split(path.sep).includes("..") ? nativePath : path.normalize(nativePath);
+  return normalized.toLowerCase();
+}
+
+function absoluteGoalFilePath(value: string, cwd: string): string {
+  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return value;
+  const nativePath = value.replaceAll("/", "\\");
+  // Resolving parent segments lexically can select a different file across a directory symlink.
+  return nativePath.split(path.sep).includes("..")
+    ? `${path.resolve(cwd)}${path.sep}${nativePath}`
+    : path.resolve(cwd, value);
+}
+
+function normalizeGoalFileMention(raw: string, cwd: string, quoted = false): string | undefined {
+  const trimmed = raw.trim();
+  const value = quoted ? trimmed : stripUnquotedPathPunctuation(trimmed);
+  if (!value || /\p{Cc}/u.test(value) || !quoted && /\s/u.test(value)) return undefined;
+  const absolute = absoluteGoalFilePath(value, cwd);
+  if (!isAbsoluteFilePath(absolute)) return undefined;
+  return goalPathIdentity(absolute);
+}
+
+/** Counts distinct path-shaped mentions so several files cannot bind proof to one. */
+function countGoalTargetFiles(objective: string, cwd: string, target: string, targetQuoted: boolean): number {
+  const source = objective.replace(GOAL_URL_PATTERN, " ");
+  // ponytail: Only these exact prose forms are excluded; quote ambiguous bare filenames for exact proof.
+  const prose = source.replace(GOAL_QUOTED_PATTERN, " ")
+    .replace(/(?<![A-Za-z0-9_.\\/-])version\s+\d+(?:\.\d+)+(?=$|[\s,;:!?)\]}]|\.(?=$|[\s,;:!?)\]}]))/giu, " ")
+    .replace(/(?<![A-Za-z0-9_.\\/-])for\s+Node\.js(?!\s+compatibility\.[A-Za-z0-9])(?=$|[\s,;:!?)\]}]|\.(?=$|[\s,;:!?)\]}]))|(?<![A-Za-z0-9_.\\/-])Node\.js\s+compatibility(?=$|[\s,;:!?)\]}]|\.(?=$|[\s,;:!?)\]}]))/giu, " ");
+  const mentions = new Set<string>();
+  const add = (raw: string, quoted = false): void => {
+    const normalized = normalizeGoalFileMention(raw, cwd, quoted);
+    if (normalized) mentions.add(normalized);
+  };
+  add(target, targetQuoted);
+  for (const match of source.matchAll(GOAL_QUOTED_PATTERN)) {
+    const raw = match[1] ?? match[2] ?? match[3] ?? "";
+    if (isQuotedGoalFileMention(raw)) add(raw, true);
+  }
+  for (const match of source.matchAll(GOAL_LIST_FILE_PATTERN)) {
+    const quoted = match[1] ?? match[2] ?? match[3];
+    if (quoted !== undefined) add(quoted, true);
+  }
+  for (const match of prose.matchAll(GOAL_ABSOLUTE_PATTERN)) {
+    if (match[1]) add(stripUnquotedPathPunctuation(match[1].trim()));
+  }
+  for (const match of prose.matchAll(GOAL_LIST_FILE_PATTERN)) {
+    if (match[4]) add(match[4]);
+    if (match[5]) add(match[5]);
+  }
+  for (const match of prose.matchAll(GOAL_RELATIVE_FILE_PATTERN)) {
+    if (match[1]) add(match[1]);
+  }
+  return mentions.size;
+}
+
+/** Captures one explicit output path so goal completion can verify its creation or modification. */
+export async function inferGoalVerification(objective: string, cwd: string): Promise<GoalFileVerification | undefined> {
+  const candidates: Array<{ raw: string; quoted: boolean }> = [];
+  const destination = /\b(?:create|write|save|generate)\b[^\r\n]{0,160}?\b(?:file|document|markdown|report|spreadsheet|presentation|image)\b\s+(?:to|at|as|destination(?:\s+is)?|output(?:\s+(?:to|at))?)\b\s*(?:`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)'|([A-Za-z]:\\[^\s,;]+|\/[^\s,;]+))/giu;
+  for (const match of objective.matchAll(destination)) {
+    const quoted = match[1] ?? match[2] ?? match[3];
+    candidates.push({
+      raw: quoted !== undefined ? quoted : stripUnquotedPathPunctuation((match[4] ?? "").trim()),
+      quoted: quoted !== undefined,
+    });
+  }
+  const direct = /\b(?:update|edit|fix|refactor|migrate)\s+(`([^`\r\n]+)`|"([^"\r\n]+)"|'([^'\r\n]+)')/giu;
+  for (const match of objective.matchAll(direct)) {
+    const quoted = match[2] ?? match[3] ?? match[4];
+    if (quoted !== undefined) candidates.push({ raw: quoted, quoted: true });
+  }
+  const operands = new Set<string>();
+  const resolved = new Map<string, { filePath: string; quoted: boolean }>();
+  for (const candidate of candidates) {
+    const value = candidate.raw.trim();
+    if (!value || /\p{Cc}/u.test(value)) continue;
+    const alreadyAbsolute = path.isAbsolute(value) || path.win32.isAbsolute(value);
+    if (!alreadyAbsolute && URL.canParse(value)) continue;
+    const absolute = absoluteGoalFilePath(value, cwd);
+    const identity = goalPathIdentity(absolute);
+    operands.add(identity);
+    if (!isPathShapedGoalCandidate(candidate.raw) || !isAbsoluteFilePath(absolute)) continue;
+    const existing = resolved.get(identity);
+    resolved.set(identity, {
+      filePath: existing?.filePath ?? absolute,
+      quoted: candidate.quoted || existing?.quoted === true,
+    });
+  }
+  if (operands.size !== 1 || resolved.size !== 1) return undefined;
+  // A goal that names several files must not verify from one file alone.
+  // Repeated references to the same file count as one target.
+  const target = resolved.values().next().value;
+  if (target === undefined || countGoalTargetFiles(objective, cwd, target.filePath, target.quoted) > 1) return undefined;
+  return { kind: "file", path: target.filePath, baseline: await captureGoalFileBaseline(target.filePath) };
+}
+
+export async function verifyGoalDeliverable(verification: GoalFileVerification): Promise<void> {
+  let artifact: Stats;
+  try {
+    artifact = await lstat(verification.path);
+  } catch {
+    throw new Error(`Goal deliverable is not a regular file at the required path: ${verification.path}`);
+  }
+  if (!artifact.isFile()) {
+    throw new Error(`Goal deliverable is not a regular file at the required path: ${verification.path}`);
+  }
+  if (!verification.baseline.exists) return;
+  if (verification.baseline.contentHash === null) {
+    throw new Error(`Goal deliverable content cannot be verified: ${verification.path}`);
+  }
+  if (verification.baseline.contentHash !== undefined) {
+    const current = await captureGoalFileBaseline(verification.path);
+    if (!current.exists || current.contentHash === null) {
+      throw new Error(`Goal deliverable content cannot be verified: ${verification.path}`);
+    }
+    if (current.contentHash === verification.baseline.contentHash) {
+      throw new Error(`Goal deliverable has not changed since the goal started: ${verification.path}`);
+    }
+  }
+  if (verification.baseline.contentHash === undefined
+    && artifact.size === verification.baseline.size
+    && artifact.mtimeMs === verification.baseline.mtimeMs) {
+    throw new Error(`Goal deliverable has not changed since the goal started: ${verification.path}`);
+  }
+}
+
+export function boundGoalText(value: string, limit = GOAL_EVIDENCE_LIMIT): string {
+  const safe = safeTerminalText(value).trim();
+  return [...graphemeSegmenter.segment(safe)]
+    .slice(0, limit)
+    .map(({ segment }) => segment)
+    .join("")
+    .trimEnd();
+}
+
+export function validateGoalObjective(input: string): string | undefined {
+  const objective = input.trim();
+  if (!objective || safeTerminalText(objective) !== objective) return undefined;
+  return graphemeCount(objective) <= GOAL_OBJECTIVE_LIMIT ? objective : undefined;
+}
+
+export function goalElapsedMilliseconds(state: GoalState, now: number): number {
+  const activeInterval = state.status === "active" ? Math.max(0, now - state.activeStartedAt) : 0;
+  return addGoalMilliseconds(state.activeMilliseconds, activeInterval);
+}
+
+export function commonGoalState(state: GoalState): GoalStateCommon {
+  return {
+    version: state.version,
+    revision: state.revision,
+    objective: state.objective,
+    createdAt: state.createdAt,
+    updatedAt: state.updatedAt,
+    activeMilliseconds: state.activeMilliseconds,
+    turns: state.turns,
+    blockedAuditStartTurn: state.blockedAuditStartTurn,
+    baselineTokens: state.baselineTokens,
+    ...(state.verification === undefined ? {} : { verification: state.verification }),
+    ...(state.maxTurns === undefined ? {} : { maxTurns: state.maxTurns }),
+    ...(state.turnPhase === undefined ? {} : { turnPhase: state.turnPhase }),
+    ...(state.turnDecision === undefined ? {} : { turnDecision: state.turnDecision }),
+    ...(state.lastDecision === undefined ? {} : { lastDecision: state.lastDecision }),
+    ...(state.lastContinueReport === undefined ? {} : { lastContinueReport: state.lastContinueReport }),
+    ...(state.status === "paused" && state.stopReason !== undefined ? { stopReason: state.stopReason } : {}),
+  };
+}
+
+export function stopGoalClock(state: GoalState, now: number): GoalStateCommon {
+  const common = commonGoalState(state);
+  return state.status === "active"
+    ? { ...common, activeMilliseconds: addGoalMilliseconds(common.activeMilliseconds, Math.max(0, now - state.activeStartedAt)) }
+    : common;
+}
+
+export function createNewGoalState(
+  objective: string,
+  baselineTokens: number,
+  verification: GoalFileVerification | undefined,
+  now: number,
+  controls: { maxTurns?: number } = {},
+): GoalState {
+  return {
+    version: GOAL_VERSION,
+    revision: 1,
+    objective,
+    status: "active",
+    createdAt: now,
+    updatedAt: now,
+    activeMilliseconds: 0,
+    activeStartedAt: now,
+    turns: 0,
+    blockedAuditStartTurn: 0,
+    baselineTokens,
+    turnPhase: "ready",
+    ...(verification === undefined ? {} : { verification }),
+    ...(controls.maxTurns === undefined ? {} : { maxTurns: controls.maxTurns }),
+  };
+}
+
+function nextRevision(current: { revision: number }): number {
+  if (!incrementableNonNegativeInteger(current.revision)) {
+    throw new Error("Goal revision cannot advance safely");
+  }
+  return current.revision + 1;
+}
+
+export function beginGoalTurnState(
+  current: Extract<GoalState, { status: "active" }>,
+  now: number,
+): GoalState {
+  if (!incrementableNonNegativeInteger(current.turns)) throw new Error("Goal turn counter cannot advance safely");
+  const { turnDecision: _decision, turnPhase: _phase, ...withoutPending } = current;
+  return {
+    ...withoutPending,
+    revision: nextRevision(current),
+    turns: current.turns + 1,
+    updatedAt: now,
+    turnPhase: "in-flight",
+    ...(current.turnDecision === undefined ? {} : { lastDecision: current.turnDecision }),
+  };
+}
+
+export function checkpointActiveGoalState(
+  current: Extract<GoalState, { status: "active" }>,
+  now: number,
+): GoalState {
+  return {
+    ...stopGoalClock(current, now),
+    revision: nextRevision(current),
+    status: "active",
+    updatedAt: now,
+    activeStartedAt: now,
+    ...(current.result === undefined ? {} : { result: current.result }),
+    ...(current.blockerAudit === undefined ? {} : { blockerAudit: current.blockerAudit }),
+  };
+}
+
+export function pauseGoalState(
+  current: GoalState,
+  result: string | undefined,
+  now: number,
+  resumeAfterManualCompaction = false,
+  preserveTurnAuthorization = false,
+): GoalState {
+  const common = stopGoalClock(current, now);
+  const { turnDecision: _decision, turnPhase: _phase, ...withoutPending } = common;
+  return {
+    ...withoutPending,
+    status: "paused",
+    turnPhase: preserveTurnAuthorization ? current.turnPhase : "ready",
+    ...(preserveTurnAuthorization && current.turnDecision !== undefined ? { turnDecision: current.turnDecision } : {}),
+    ...(result === undefined ? {} : { result }),
+    ...(result === undefined ? {} : { stopReason: boundGoalText(result) }),
+    ...(current.blockerAudit === undefined ? {} : { blockerAudit: current.blockerAudit }),
+    ...(resumeAfterManualCompaction ? { resumeAfterManualCompaction: true as const } : {}),
+  };
+}
+
+export function checkpointPausedGoalState(
+  current: Extract<GoalState, { status: "paused" }>,
+  now: number,
+): GoalState {
+  const { resumeAfterManualCompaction: _resume, ...paused } = current;
+  return { ...paused, revision: nextRevision(current), updatedAt: now };
+}
+
+export function recordGoalDecision(
+  state: Extract<GoalState, { status: "active" }>,
+  decision: GoalPendingDecision,
+  now: number,
+): Extract<GoalState, { status: "active" }> {
+  if (decision.turn !== state.turns) throw new Error("Goal decision does not match the active turn");
+  return {
+    ...state,
+    revision: nextRevision(state),
+    updatedAt: now,
+    turnPhase: "authorized",
+    turnDecision: decision,
+    lastDecision: decision,
+    ...(decision.kind === "continue"
+      ? { lastContinueReport: { turn: decision.turn, evidence: decision.evidence, nextAction: decision.nextAction } }
+      : {}),
+  };
+}
+
+/** Replaces the objective in place for an editable goal; pending decisions and audits belong to the previous objective. */
+export function editGoalState(
+  current: GoalState,
+  objective: string,
+  verification: GoalFileVerification | undefined,
+  now: number,
+): GoalState {
+  if (current.status !== "active" && current.status !== "paused") {
+    throw new Error("Only an active or paused goal can be edited");
+  }
+  const common: GoalStateCommon = {
+    version: current.version,
+    revision: nextRevision(current),
+    objective,
+    createdAt: current.createdAt,
+    updatedAt: now,
+    activeMilliseconds: current.activeMilliseconds,
+    turns: current.turns,
+    blockedAuditStartTurn: current.turns,
+    baselineTokens: current.baselineTokens,
+    turnPhase: "ready",
+    ...(current.maxTurns === undefined ? {} : { maxTurns: current.maxTurns }),
+    ...(verification === undefined ? {} : { verification }),
+  };
+  return current.status === "active"
+    ? { ...common, status: "active", activeStartedAt: current.activeStartedAt, ...(current.result === undefined ? {} : { result: current.result }) }
+    : { ...common, status: "paused", ...(current.result === undefined ? {} : { result: current.result }) };
+}
+
+export function transitionGoalState(
+  current: GoalState,
+  status: GoalStatus,
+  result: string | undefined,
+  options: GoalTransitionOptions,
+  now: number,
+): GoalState {
+  const stopped = stopGoalClock(current, now);
+  const common: GoalStateCommon = {
+    ...stopped,
+    revision: nextRevision(stopped),
+    updatedAt: now,
+    blockedAuditStartTurn: options.resetBlockedAudit ? stopped.turns : stopped.blockedAuditStartTurn,
+  };
+  const blockerAudit = options.resetBlockedAudit ? undefined : options.blockerAudit ?? current.blockerAudit;
+  const pending = options.preserveTurnAuthorization ? current.turnDecision : undefined;
+  const { turnDecision: _decision, turnPhase: _phase, stopReason: _stopReason, ...withoutPending } = common;
+  switch (status) {
+    case "active":
+      return {
+        ...withoutPending,
+        ...(current.status === "blocked" ? { lastDecision: undefined } : {}),
+        status,
+        activeStartedAt: now,
+        turnPhase: pending !== undefined ? "authorized" : options.resumeInterruptedTurn ? "in-flight" : "ready",
+        ...(pending === undefined ? {} : { turnDecision: pending }),
+        ...(blockerAudit === undefined ? {} : { blockerAudit }),
+      };
+    case "paused":
+      return {
+        ...withoutPending,
+        status,
+        turnPhase: options.keepTurnForRecovery ? current.turnPhase : "ready",
+        ...(options.keepTurnForRecovery && current.turnDecision !== undefined ? { turnDecision: current.turnDecision } : {}),
+        ...(result === undefined ? {} : { result, stopReason: boundGoalText(result) }),
+        ...(blockerAudit === undefined ? {} : { blockerAudit }),
+        ...(options.resumeAfterManualCompaction === undefined ? {} : { resumeAfterManualCompaction: true }),
+      };
+    case "blocked":
+      if (result === undefined) throw new Error("A blocked goal requires a result");
+      return {
+        ...withoutPending,
+        status,
+        result,
+        ...(options.decision === undefined ? {} : { lastDecision: options.decision }),
+        ...(blockerAudit === undefined ? {} : { blockerAudit }),
+      };
+    case "complete":
+      if (result === undefined) throw new Error("A complete goal requires a result");
+      return {
+        ...withoutPending,
+        status,
+        result,
+        ...(options.decision === undefined ? {} : { lastDecision: options.decision }),
+      };
+  }
+}