killeros 2.0.20 → 2.0.21

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.0.21] - 2026-08-29
+
+### Changed
+
+- Bounded goal verification and Pi compatibility, reduced Git status polling, reserved handoff context, and separated goal state and question UI logic.
+- Blocked moderate dependency advisories in CI and updated TypeBox within the supported 1.x line.
+- Preserved seconds in footer and goal elapsed times after one minute.
+- Added a muted top border to the prompt editor.
+- Colored the footer workspace path `#F0F89A`.
+- Added a live changed-file count beside the Git branch when the worktree is dirty.
+- Synced `dev` back to successful `main` releases after publishing.
+
+### Fixed
+
+- Kept likely secrets out of `/init`, restricted personal-instruction imports to Pi's agent directory, and replaced injectable handoff framing with validated JSON.
+- Hardened releases against stale CI runs, mismatched existing npm artifacts, and tag conflicts discovered after publication.
+
 ## [2.0.20] - 2026-08-25
 
 ### Changed

package/README.md

@@ -19,7 +19,7 @@ A TypeScript extension for the [Pi coding agent](https://github.com/earendil-wor
 ## Requirements
 
 - Node.js 22.19.0+
-- Pi 0.84.3+
+- Pi 0.84.3 or later within the 0.x release line
 - An interactive TUI session for the custom header, editor, footer, `question`, and `/init`
 
 ## Install
@@ -34,7 +34,7 @@ Or from GitHub:
 pi install git:github.com/KyrosHendrix/pi-KillerOS
 ```
 
-Pin a release by appending its tag, for example `@v2.0.20`. Add `-l` to install only for the current project. Restart Pi after installing.
+Pin a release by appending its tag, for example `@v2.0.21`. Add `-l` to install only for the current project. Restart Pi after installing.
 
 ## Commands
 

package/killeros/display.ts

@@ -28,9 +28,14 @@ export function formatTime(milliseconds: number): string {
   if (!Number.isFinite(milliseconds)) return "0s";
   const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
   if (totalSeconds < 60) return `${totalSeconds}s`;
-  const minutes = Math.floor(totalSeconds / 60);
-  if (minutes < 60) return `${minutes}m`;
-  return `${Math.floor(minutes / 60)}h${minutes % 60}m`;
+
+  const seconds = totalSeconds % 60;
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  if (totalMinutes < 60) return `${totalMinutes}m ${seconds.toString().padStart(2, "0")}s`;
+
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return `${hours}h ${minutes.toString().padStart(2, "0")}m ${seconds.toString().padStart(2, "0")}s`;
 }
 
 export function formatTokens(value: number): string {

package/killeros/footer.ts

@@ -1,14 +1,98 @@
+import { execFile } from "node:child_process";
 import { type ExtensionAPI, type ExtensionContext, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth, type TUI } from "@earendil-works/pi-tui";
 import { isCodexFastEnabled, subscribeCodexFast } from "./codex-fast-state.ts";
 import { formatCwd, formatTime, formatTokens, padRight } from "./display.ts";
-import { goalElapsedMilliseconds } from "./goals.ts";
+import { goalElapsedMilliseconds } from "./goal-state.ts";
 import type { GoalRuntime, GoalState } from "./runtime.ts";
 import { safeTerminalText } from "./safe-terminal-text.ts";
 import { LEVEL_COLORS, type ThinkingLevel } from "./variants.ts";
 
-const FOOTER_REFRESH_INTERVAL_MS = 1_000;
+const GIT_STATUS_REFRESH_INTERVAL_MS = 30_000;
 const CODEX_PROVIDER = "openai-codex";
+const colorDirectory = (text: string): string => `\x1B[38;2;240;248;154m${text}\x1B[39m`;
+
+function resolveUncommittedFileCount(cwd: string): Promise<number | undefined> {
+  return new Promise((resolve) => {
+    execFile(
+      "git",
+      ["-C", cwd, "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+      {
+        encoding: "utf8",
+        maxBuffer: 4 * 1024 * 1024,
+        timeout: 1_000,
+        windowsHide: true,
+      },
+      (error, stdout) => {
+        if (error) {
+          resolve(undefined);
+          return;
+        }
+
+        const entries = stdout.split("\0");
+        let count = 0;
+        for (let index = 0; index < entries.length; index += 1) {
+          const entry = entries[index];
+          if (!entry) continue;
+          count += 1;
+          if (entry[0] === "R" || entry[0] === "C" || entry[1] === "R" || entry[1] === "C") index += 1;
+        }
+        resolve(count);
+      },
+    );
+  });
+}
+
+/** Coalesces Git status requests to one active scan and one queued follow-up. */
+export function createGitStatusRefresh(
+  cwd: string,
+  onCount: (count: number | undefined) => void,
+  resolveCount: (cwd: string) => Promise<number | undefined> = resolveUncommittedFileCount,
+): { request: () => void; dispose: () => void } {
+  let disposed = false;
+  let pending = false;
+  let queued = false;
+  const request = (): void => {
+    if (disposed) return;
+    if (pending) {
+      queued = true;
+      return;
+    }
+    pending = true;
+    void resolveCount(cwd).then((count) => {
+      if (!disposed) onCount(count);
+    }).finally(() => {
+      pending = false;
+      if (!disposed && queued) {
+        queued = false;
+        request();
+      }
+    });
+  };
+  return {
+    request,
+    dispose() {
+      disposed = true;
+      queued = false;
+    },
+  };
+}
+
+type ScheduleFallback = (refresh: () => void, intervalMs: number) => () => void;
+
+const scheduleFallback: ScheduleFallback = (refresh, intervalMs) => {
+  const timer = setInterval(refresh, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+};
+
+/** Schedules the fallback Git scan independently from footer rendering. */
+export function scheduleGitStatusFallback(
+  refresh: () => void,
+  schedule: ScheduleFallback = scheduleFallback,
+): () => void {
+  return schedule(refresh, GIT_STATUS_REFRESH_INTERVAL_MS);
+}
 
 export function formatCost(usd: number): string {
   if (!Number.isFinite(usd)) return "$—";
@@ -142,23 +226,10 @@ function renderFooter(rows: string[], width: number, theme: Theme): string[] {
   return [theme.fg("borderMuted", "─".repeat(width)), ...rows];
 }
 
-function formatGoalElapsed(milliseconds: number): string {
-  const totalSeconds = Number.isFinite(milliseconds) ? Math.max(0, Math.floor(milliseconds / 1_000)) : 0;
-  if (totalSeconds < 60) return `${totalSeconds}s`;
-
-  const seconds = totalSeconds % 60;
-  const totalMinutes = Math.floor(totalSeconds / 60);
-  if (totalMinutes < 60) return `${totalMinutes}m ${seconds.toString().padStart(2, "0")}s`;
-
-  const hours = Math.floor(totalMinutes / 60);
-  const minutes = totalMinutes % 60;
-  return `${hours}h ${minutes.toString().padStart(2, "0")}m ${seconds.toString().padStart(2, "0")}s`;
-}
-
 function formatGoalFooter(state: GoalState | undefined, theme: Theme): string {
   if (!state) return "";
   if (state.status === "active") {
-    return theme.fg("warning", `/goal is active (${formatGoalElapsed(goalElapsedMilliseconds(state))})`);
+    return theme.fg("warning", `/goal is active (${formatTime(goalElapsedMilliseconds(state, Date.now()))})`);
   }
   if (state.status === "paused") return theme.fg("warning", "/goal is paused");
   if (state.status === "blocked") return theme.fg("error", "/goal is blocked");
@@ -172,6 +243,7 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
   let cachedSessionCost = 0;
   let sessionCostDirty = true;
   let unsubscribeCodexFast: (() => void) | undefined;
+  let requestGitStatusRefresh: (() => void) | undefined;
   const resetSessionCost = (): void => {
     cachedSessionCost = 0;
     sessionCostDirty = true;
@@ -201,13 +273,25 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
 
     ctx.ui.setFooter((tui, theme, footerData) => {
       activeTui = tui;
-      const unsubscribe = footerData.onBranchChange(() => tui.requestRender());
-      const refreshTimer = setInterval(() => tui.requestRender(), FOOTER_REFRESH_INTERVAL_MS);
-      refreshTimer.unref?.();
+      let uncommittedFileCount: number | undefined;
+      const gitStatus = createGitStatusRefresh(ctx.cwd, (count) => {
+        if (count === uncommittedFileCount) return;
+        uncommittedFileCount = count;
+        tui.requestRender();
+      });
+      requestGitStatusRefresh = gitStatus.request;
+      const unsubscribe = footerData.onBranchChange(() => {
+        gitStatus.request();
+        tui.requestRender();
+      });
+      gitStatus.request();
+      const stopFallback = scheduleGitStatusFallback(gitStatus.request);
       return {
         dispose() {
           unsubscribe();
-          clearInterval(refreshTimer);
+          stopFallback();
+          gitStatus.dispose();
+          if (requestGitStatusRefresh === gitStatus.request) requestGitStatusRefresh = undefined;
           if (activeTui === tui) activeTui = undefined;
         },
         invalidate() {},
@@ -227,8 +311,8 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
           const context = formatContextProgress(usage?.tokens ?? null, contextWindow, theme);
           const branch = footerData.getGitBranch();
           const signature = formatModel(model, theme, true, isCodexFastEnabled());
-          const fullDirectory = theme.fg("dim", cwd);
-          const focusedDirectory = theme.fg("dim", compactDirectory(cwd));
+          const fullDirectory = colorDirectory(cwd);
+          const focusedDirectory = colorDirectory(compactDirectory(cwd));
           const goal = formatGoalFooter(goalRuntime.state, theme);
           const primary = joinFooterParts([
             signature,
@@ -248,7 +332,11 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
               : footerRowFits(primaryFocused, "", width)
                 ? renderFooterRow(primaryFocused, "", width)
                 : renderFooterRow(essentialModel, context, width);
-          const branchLabel = branch ? theme.fg("dim", branch) : "";
+          const branchLabel = branch
+            ? uncommittedFileCount
+              ? `${theme.fg("dim", `${branch} · `)}${theme.fg("warning", `${uncommittedFileCount} changed`)}`
+              : theme.fg("dim", branch)
+            : "";
           const workspaceRight = goal || fullDirectory;
           const secondaryRow = footerRowFits(branchLabel, workspaceRight, width)
             ? renderFooterRow(branchLabel, workspaceRight, width)
@@ -271,8 +359,12 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
     thinkingLevel = event.level;
     activeTui?.requestRender();
   });
-  pi.on("turn_end", invalidateSessionCost);
-  pi.on("session_compact", invalidateSessionCost);
+  const refreshAfterActivity = (): void => {
+    invalidateSessionCost();
+    requestGitStatusRefresh?.();
+  };
+  pi.on("turn_end", refreshAfterActivity);
+  pi.on("session_compact", refreshAfterActivity);
   pi.on("session_tree", () => {
     resetSessionCost();
     activeTui?.requestRender();
@@ -282,6 +374,7 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
     unsubscribeCodexFast = undefined;
     resetSessionCost();
     activeTui = undefined;
+    requestGitStatusRefresh = undefined;
     goalRuntime.requestRender = undefined;
   });
 }

package/killeros/goal-state.ts

@@ -0,0 +1,407 @@
+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, GoalFileBaseline, GoalFileVerification, GoalState, GoalStateCommon, GoalStatus } from "./runtime.ts";
+
+export const GOAL_OBJECTIVE_LIMIT = 4_000;
+export const GOAL_VERSION = 1;
+const FILE_HASH_CHUNK_SIZE = 64 * 1024;
+export const FILE_HASH_LIMIT = 64 * 1024 * 1024;
+type OpenGoalFile = (filePath: string) => Promise<FileHandle>;
+const openGoalFile: OpenGoalFile = (filePath) => open(filePath, "r");
+
+export interface GoalTransitionOptions {
+  resetBlockedAudit?: boolean;
+  resumeAfterManualCompaction?: true;
+  blockerAudit?: GoalBlockerAudit;
+}
+
+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 isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+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 isGoalFileVerification(value: unknown): value is GoalFileVerification {
+  return isUnknownRecord(value)
+    && value.kind === "file"
+    && typeof value.path === "string"
+    && value.path === value.path.trim()
+    && isAbsoluteFilePath(value.path)
+    && isGoalFileBaseline(value.baseline);
+}
+
+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) {
+    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,
+  } = value;
+  if (version !== GOAL_VERSION
+    || typeof revision !== "number" || !Number.isInteger(revision) || revision < 1
+    || typeof objective !== "string" || !objective.trim() || [...objective].length > GOAL_OBJECTIVE_LIMIT
+    || !isGoalStatus(status)
+    || !finiteNonNegative(createdAt)
+    || !finiteNonNegative(updatedAt)
+    || !finiteNonNegative(activeMilliseconds)
+    || typeof turns !== "number" || !Number.isInteger(turns) || turns < 0
+    || blockedAuditStartTurn !== undefined
+      && (typeof blockedAuditStartTurn !== "number" || !Number.isInteger(blockedAuditStartTurn)
+        || blockedAuditStartTurn < 0 || blockedAuditStartTurn > turns)
+    || !finiteNonNegative(baselineTokens)
+    || result !== undefined && typeof result !== "string"
+    || verification !== undefined && !isGoalFileVerification(verification)
+    || resumeAfterManualCompaction !== undefined && resumeAfterManualCompaction !== true
+    || blockerAudit !== undefined && !isGoalBlockerAudit(blockerAudit, turns, status)) {
+    return undefined;
+  }
+
+  const common: GoalStateCommon = {
+    version: GOAL_VERSION,
+    revision,
+    objective: objective.trim(),
+    createdAt,
+    updatedAt,
+    activeMilliseconds,
+    turns,
+    blockedAuditStartTurn: blockedAuditStartTurn ?? 0,
+    baselineTokens,
+    ...(verification === undefined ? {} : { verification }),
+  };
+  switch (status) {
+    case "active":
+      if (!finiteNonNegative(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();
+  }
+}
+
+/** Captures one explicit absolute output path so goal completion can verify its creation or modification. */
+export async function inferGoalVerification(objective: string): Promise<GoalFileVerification | undefined> {
+  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;
+  const paths = [...objective.matchAll(destination)]
+    .map((match) => (match[1] ?? match[2] ?? match[3] ?? match[4] ?? "").trim())
+    .filter(isAbsoluteFilePath);
+  const unique = [...new Set(paths)];
+  const filePath = unique.length === 1 ? unique[0] : undefined;
+  return filePath ? { kind: "file", path: filePath, baseline: await captureGoalFileBaseline(filePath) } : undefined;
+}
+
+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 validateGoalObjective(input: string): string | undefined {
+  const objective = input.trim();
+  if (!objective) return undefined;
+  return [...objective].length <= 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 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 }),
+  };
+}
+
+export function stopGoalClock(state: GoalState, now: number): GoalStateCommon {
+  const common = commonGoalState(state);
+  return state.status === "active"
+    ? { ...common, activeMilliseconds: common.activeMilliseconds + Math.max(0, now - state.activeStartedAt) }
+    : common;
+}
+
+export function createNewGoalState(
+  objective: string,
+  baselineTokens: number,
+  verification: GoalFileVerification | undefined,
+  now: number,
+): GoalState {
+  return {
+    version: GOAL_VERSION,
+    revision: 1,
+    objective,
+    status: "active",
+    createdAt: now,
+    updatedAt: now,
+    activeMilliseconds: 0,
+    activeStartedAt: now,
+    turns: 0,
+    blockedAuditStartTurn: 0,
+    baselineTokens,
+    ...(verification === undefined ? {} : { verification }),
+  };
+}
+
+export function editGoalState(
+  state: GoalState,
+  objective: string,
+  verification: GoalFileVerification | undefined,
+  now: number,
+): GoalState {
+  const current = stopGoalClock(state, now);
+  const { verification: _previousVerification, ...common } = current;
+  return {
+    ...common,
+    revision: current.revision + 1,
+    objective,
+    status: "active",
+    updatedAt: now,
+    activeStartedAt: now,
+    blockedAuditStartTurn: current.turns,
+    ...(verification === undefined ? {} : { verification }),
+  };
+}
+
+export function beginGoalTurnState(
+  current: Extract<GoalState, { status: "active" }>,
+  now: number,
+): GoalState {
+  return { ...current, revision: current.revision + 1, turns: current.turns + 1, updatedAt: now };
+}
+
+export function checkpointActiveGoalState(
+  current: Extract<GoalState, { status: "active" }>,
+  now: number,
+): GoalState {
+  return {
+    ...stopGoalClock(current, now),
+    revision: current.revision + 1,
+    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,
+): GoalState {
+  const common = stopGoalClock(current, now);
+  return {
+    ...common,
+    status: "paused",
+    ...(result === undefined ? {} : { 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: paused.revision + 1, updatedAt: now };
+}
+
+export function recordGoalBlockerAudit(
+  state: Extract<GoalState, { status: "active" }>,
+  blockerAudit: GoalBlockerAudit,
+  now: number,
+): GoalState {
+  return { ...state, revision: state.revision + 1, updatedAt: now, blockerAudit };
+}
+
+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: stopped.revision + 1,
+    updatedAt: now,
+    blockedAuditStartTurn: options.resetBlockedAudit ? stopped.turns : stopped.blockedAuditStartTurn,
+  };
+  const blockerAudit = options.resetBlockedAudit ? undefined : options.blockerAudit ?? current.blockerAudit;
+  switch (status) {
+    case "active":
+      return { ...common, status, activeStartedAt: now, ...(blockerAudit === undefined ? {} : { blockerAudit }) };
+    case "paused":
+      return {
+        ...common,
+        status,
+        ...(result === undefined ? {} : { result }),
+        ...(blockerAudit === undefined ? {} : { blockerAudit }),
+        ...(options.resumeAfterManualCompaction === undefined ? {} : { resumeAfterManualCompaction: true }),
+      };
+    case "blocked":
+      if (result === undefined) throw new Error("A blocked goal requires a result");
+      return { ...common, status, result, ...(blockerAudit === undefined ? {} : { blockerAudit }) };
+    case "complete":
+      if (result === undefined) throw new Error("A complete goal requires a result");
+      return { ...common, status, result };
+  }
+}