@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/lib/README.md

@@ -16,22 +16,24 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | Module | Responsibility |
 |---|---|
 | [`browser.ts`](./browser.ts) | Cross-platform default-browser opener shared by `file-browse` and `plan`: pure `browserCommand(url, platform)` plus best-effort `openInBrowser(url, { platform, spawn })` with an injectable spawn. |
-| [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection`. Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
+| [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` (the last two edit one leaf, flat or nested, preserving siblings and metadata). Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
 | [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters. |
-| [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` and `JobFinishedEvent`, published by `job` and consumed by bytefly's notify capability. |
+| [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` / `JobFinishedEvent` (published by `job`, consumed by bytefly's notify capability), `SUBAGENT_FINISHED_CHANNEL` / `SubagentFinishedEvent` (published by `subagent`, consumed by bytefly's footer roll-up), and `WEB_SEARCH_PROVIDER_CHANNEL` / `WebSearchProviderEvent` (published by `web-access` at session start, consumed by bytefly's doctor so it can report the resolved provider without importing the extension — the key itself is never in the payload). |
 | [`notice.ts`](./notice.ts) | The shared transcript notice: `NOTICE_TYPE`, the `NoticeDetails` / `NoticeItem` shape, `noticeMessage` (the `display: true` message both send paths accept), `isNotice`, and `pruneStaleNotices` — posted by `job` and `watch`, rendered by bytefly. |
 | [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — and `shortenPath`. |
 | [`interaction.ts`](./interaction.ts) | Turn-affinity prompt contract: the channel a remote transport marks on the UI context it owns (`INTERACTION_TURN_KEY`), the `InteractionChannel` interface (`request` / `post` / `postFile`), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file, fallback text, and digest preface) plus the shared “Other” label. |
 | [`git/`](./git/) | Shared git plumbing. [`git/runner.ts`](./git/runner.ts) is the `RunGit` seam (`createExecRunner` with timeout/env handling, `runGitOrThrow`, `GitError`); [`git/read.ts`](./git/read.ts) holds the read helpers (`repoRoot`, `repoRootFor`, `gitDir`, `revParse`, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
 | [`highlight.ts`](./highlight.ts) | First-party, escape-first syntax tokenizer (`detectLanguage`, `fenceLanguage`, `highlightLines`, `HighlightLanguage`, `TokenClass`) for js/ts, json, css, html, shell, python, java, yaml, and sql; shared by `file-browse` and plan's code blocks. |
-| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job` and `watch` share), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, sanitized `errorLine` / `rejectionLine`, `moreHint`, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
+| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface, whose conventions are its own doc, [`tui/README.md`](./tui/README.md). Modules: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job` and `watch` share), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, sanitized `errorLine` / `rejectionLine`, `moreHint`, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, and doc guards share. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
 | [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
-| [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. |
+| [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports, the published search provider, env, and a refresh-only reachability probe): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. A check kind is either a prerequisite (`binary`, `module`, `state`, `invocation`, `notify`, `provider`) or a `safety` switch whose off value trades a protection away, read from `bytefly.json` global-then-project. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
+| [`goal-state.ts`](./goal-state.ts) | The published `goal` state replayed from the session branch: `PublishedGoal`, `GOAL_ENTRY_TYPE`, `MAX_GOAL_OBJECTIVE`, and `lastGoal(entries)` (the last valid goal, skipping a rejected call and honouring an explicit clear), so `plan` can restate an active goal while planning and offer to record one on approval — with no extension importing another's modules. |
+| [`todo-state.ts`](./todo-state.ts) | The published `todo` state replayed from the session branch: `ExistingTodo` and `lastTodos(entries)` (the last valid list, skipping a rejected call), so `plan` can merge an approved plan's steps into it and `goal` can name the items still open when a goal is marked achieved — with no extension importing another's modules. |
 | [`tool-names.ts`](./tool-names.ts) | Tool names and one parameter name that more than one extension must agree on, so an orchestrating `ctx.executeTool()` call or schema probe breaks the build on a rename. |
 | [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, and the `tok-*` map), [`web/base.ts`](./web/base.ts), [`web/components.ts`](./web/components.ts), [`web/layout.ts`](./web/layout.ts), [`web/runtime.ts`](./web/runtime.ts) (`WEB_THEME_STORAGE_KEY`, `THEME_JS`, `THEME_TOGGLE_JS`), [`web/markup.ts`](./web/markup.ts), and the [`web/index.ts`](./web/index.ts) barrel. |
 
@@ -46,8 +48,9 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
   glyph and the `setStatus` key are one contract, not two literals. Tool names
   shared by an orchestrating tool and the tool it calls — and parameter names
   one extension probes on another — live in `tool-names.ts`.
-- **A color is a role, not a token.** Draw through [`tui/tokens.ts`](./tui/tokens.ts)
-  (`paint(theme, role, text)`) so a theme swap re-skins every surface; the
-  primitives in `tui/` already do, and a new one should too. The one exception is
-  Pi's tool-rendering vocabulary (`toolOutput`, `toolTitle`), which stays direct:
-  those tokens style a tool block, and no role maps to them.
+- **A color is a role, not a token.** The rules and the primitives are in
+  [`tui/README.md`](./tui/README.md#color-is-a-role): draw through
+  [`tui/tokens.ts`](./tui/tokens.ts) (`paint(theme, role, text)`) so a theme swap
+  re-skins every surface. The one exception is Pi's tool-rendering vocabulary
+  (`toolOutput`, `toolTitle`), which stays direct: those tokens style a tool
+  block, and no role maps to them.

package/lib/config.ts

@@ -139,6 +139,22 @@ export function configSection(
 	return asRecord(raw?.[key]);
 }
 
+/**
+ * The value at `path` in a document or section, or `undefined` when a step is
+ * absent or not an object. A one-element path reads a top-level key, so this
+ * also answers "is this setting stated here" for the flat case. `raw` may be an
+ * untrusted JSON value or an already-normalized config object.
+ */
+export function configValueAt(raw: unknown, path: readonly string[]): unknown {
+	let current: unknown = raw;
+	for (const key of path) {
+		const record = asRecord(current);
+		if (!record) return undefined;
+		current = record[key];
+	}
+	return current;
+}
+
 /** Options for {@link loadConfigSection}. */
 export interface SectionOptions {
 	/** Agent directory override; `worktree` resolves it explicitly. */
@@ -197,12 +213,38 @@ function readEditableDocument(path: string): Record<string, unknown> {
  * malformed document.
  */
 export function writeConfigValue(path: string, section: string, key: string, value: unknown): void {
+	writeConfigValueAt(path, section, [key], value);
+}
+
+/**
+ * Set the leaf at `keyPath` in one top-level section, with the same guarantees
+ * as {@link writeConfigValue}: siblings, other sections, and metadata survive,
+ * and the file and the section are created when absent. Intermediate objects
+ * are created as needed; a non-object in the way is replaced, because a refused
+ * edit would leave a hand-written typo unfixable from the screen. Refuses a
+ * malformed document and an empty path.
+ */
+export function writeConfigValueAt(path: string, section: string, keyPath: readonly string[], value: unknown): void {
+	if (keyPath.length === 0) throw new Error(`Cannot update ${path}: empty key path`);
 	const document = readEditableDocument(path);
 	const current = configSection(document, section) ?? {};
-	document[section] = { ...current, [key]: value };
+	document[section] = setPath(current, keyPath, value);
 	writeConfigFile(path, document);
 }
 
+/** Copy `source` with the leaf at `path` replaced; every sibling key is kept. */
+function setPath(source: Record<string, unknown>, path: readonly string[], value: unknown): Record<string, unknown> {
+	const [head] = path;
+	const next = { ...source };
+	if (head === undefined) return next;
+	if (path.length === 1) {
+		next[head] = value;
+		return next;
+	}
+	next[head] = setPath(asRecord(source[head]) ?? {}, path.slice(1), value);
+	return next;
+}
+
 /**
  * Delete one key from one top-level section, preserving its siblings and the
  * rest of the document. An emptied section is removed rather than left as `{}`.

package/lib/env.ts

@@ -16,6 +16,9 @@ export const ENV_ROOT = "PI_WORKTREE_ROOT";
  */
 export const ENV_DISABLED_EXTENSIONS = "PI_DISABLED_EXTENSIONS";
 
+/** Env var that turns off Pi's automatic network activity, including our own. */
+export const ENV_OFFLINE = "PI_OFFLINE";
+
 /** False when `name` appears in `PI_DISABLED_EXTENSIONS`, true otherwise. */
 export function isExtensionEnabled(name: string): boolean {
 	const raw = process.env[ENV_DISABLED_EXTENSIONS];
@@ -29,6 +32,15 @@ export function isExtensionEnabled(name: string): boolean {
 	return !disabled.has(name.toLowerCase());
 }
 
+/**
+ * Whether `PI_OFFLINE` is on, read the way Pi reads it: `1`, `true`, or `yes`
+ * (case-insensitive). Any other value, including empty, is off.
+ */
+export function isOffline(): boolean {
+	const raw = process.env[ENV_OFFLINE]?.trim().toLowerCase();
+	return raw === "1" || raw === "true" || raw === "yes";
+}
+
 /** The active worktree root from the environment, when set and still on disk. */
 export function worktreeRoot(): string | undefined {
 	const root = process.env[ENV_ROOT];

package/lib/events.ts

@@ -10,7 +10,9 @@
  *
  * The bus carries no state. `rails.ts` and `worktree` publish their own channels
  * from the modules that own them; a channel crosses an extension boundary only
- * when the payload is the whole contract, which is the case here.
+ * when the payload is the whole contract, which is the case here: `job` publishes
+ * a finished job for bytefly's notify capability, and `subagent` publishes a
+ * finished child run for bytefly's footer roll-up.
  */
 
 /** EventBus channel: a background job reached a terminal state. */
@@ -25,6 +27,89 @@ export const JOB_FINISHED_CHANNEL = "my-pi-agent/job-finished";
  */
 export type FinishedJobStatus = "exited" | "failed" | "killed" | "unknown";
 
+/** EventBus channel: a `watch` wake match fired while the agent was idle. */
+export const WATCH_MATCH_CHANNEL = "my-pi-agent/watch-match";
+
+/**
+ * Payload on {@link WATCH_MATCH_CHANNEL}: what a wake match saw.
+ *
+ * Emitted by `watch` and consumed by bytefly's notify capability, so the two can
+ * agree on an alert without `watch` learning about delivery methods. The line is
+ * **raw** — the matched text is arbitrary file or process output — and the
+ * consumer sanitizes it before it reaches a notification, exactly as it does for a
+ * job label. `count` covers the whole wake cycle, so one notification can say how
+ * many lines matched while the body describes the newest one.
+ */
+export interface WatchMatchEvent {
+	/** How many matches were pending when the wake fired. */
+	count: number;
+	/** The watcher that matched, e.g. `w3`. */
+	watcherId: string;
+	/** Its label, e.g. `build`. */
+	label: string;
+	/** The newest matched line, unsanitized. */
+	line: string;
+}
+
+/** EventBus channel: one subagent run finished (a child `pi` process exited). */
+export const SUBAGENT_FINISHED_CHANNEL = "my-pi-agent/subagent-finished";
+
+/**
+ * Payload on {@link SUBAGENT_FINISHED_CHANNEL}: what one finished child run spent.
+ *
+ * It carries the *pricing inputs* rather than a total, because the consumer prices
+ * them with the same rate table and currency as the session's own cost, and a
+ * currency change must re-price them rather than leave a figure in the old unit.
+ * `recordedCost` is Pi's own dollar figure for the child's assistant calls.
+ *
+ * A run that produced no assistant message (an unknown agent, a spawn failure)
+ * publishes nothing: there is no spend to account for.
+ */
+export interface SubagentFinishedEvent {
+	/** Agent that ran, e.g. `explorer`. */
+	agent: string;
+	/** Provider and model the child reported, when it reported one. */
+	provider: string | null;
+	model: string | null;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	/** Pi's recorded cost for the child's calls, in USD. */
+	recordedCost: number;
+	/** Epoch ms when the run finished, or `null` when unknown. */
+	at: number | null;
+	/** Child process exit code; a model-level failure still exits 0. */
+	exitCode: number;
+}
+
+/** EventBus channel: `web-access` resolved its search provider for this session. */
+export const WEB_SEARCH_PROVIDER_CHANNEL = "my-pi-agent/web-search-provider";
+
+/**
+ * Payload on {@link WEB_SEARCH_PROVIDER_CHANNEL}: what `web_search` will use.
+ *
+ * `web-access` owns the provider registry, each provider's `isConfigured`, and the
+ * `auto` resolution rule, so it is the only place those facts can come from: this
+ * event is how `doctor` learns them without importing an extension. The key
+ * itself is never published — only the variable name and whether a literal key is
+ * configured — so a diagnostic can never leak a secret into a log or a notice.
+ */
+export interface WebSearchProviderEvent {
+	/** Resolved backend id, e.g. `searxng`. */
+	provider: string;
+	/** Why this provider won: an explicit choice, one that is configured, or the keyless default. */
+	reason: "explicit" | "configured" | "default";
+	/** Whether the resolved provider's configuration is enough to call it. */
+	configured: boolean;
+	/** URL a refresh may probe, when the provider has a configurable endpoint. */
+	endpoint: string | null;
+	/** Environment variable a key would come from, when the provider takes one. */
+	apiKeyEnv: string | null;
+	/** Whether a literal key is configured, so a missing variable is not the whole story. */
+	keyConfigured: boolean;
+}
+
 /** Payload on {@link JOB_FINISHED_CHANNEL}: one job that just stopped. */
 export interface JobFinishedEvent {
 	/** Job id, e.g. `j3`. */

package/lib/goal-state.ts

@@ -0,0 +1,95 @@
+/**
+ * The published goal state, read back from the session branch (pure).
+ *
+ * `goal` publishes its objective two ways: every `goal` tool result carries the
+ * goal in `details` — a rejected call carries the unchanged goal *and* an
+ * `error`, which is not a write — and the `/goal` command appends a `goal` custom
+ * entry whose `data.goal` is `null` when the goal is cleared. Replaying the branch
+ * in order is how another extension reads the goal without importing goal's
+ * modules: `plan` restates an active goal in its planning context and offers to
+ * record one when a plan is approved with none.
+ *
+ * Stored values are re-validated and re-sanitized here. Branch data can be
+ * tampered with, migrated, or written by an older version, and a reader must not
+ * pass escapes or unbounded text onward; anything that fails validation is
+ * ignored rather than clearing a goal that is still valid.
+ *
+ * The entry type and the objective limit live here and are imported by `goal`, so
+ * the publisher and the reader cannot drift. `goal` keeps its own reconstruction
+ * (`extensions/goal/state.ts`) because it also drives the widget; this module is
+ * the minimal contract other extensions may depend on.
+ */
+
+import { sanitizeLine } from "./format.ts";
+import { GOAL_TOOL } from "./tool-names.ts";
+
+/** Custom-entry type `goal` uses to persist a goal set outside the tool. */
+export const GOAL_ENTRY_TYPE = "goal";
+
+/** Longest objective the goal tool accepts, and the most a reader will replay. */
+export const MAX_GOAL_OBJECTIVE = 2000;
+
+/** Whether the goal is still being pursued, or already done. */
+export type PublishedGoalStatus = "active" | "achieved";
+
+/** The goal as another extension may read it. */
+export interface PublishedGoal {
+	/** The objective, sanitized to a single line. */
+	objective: string;
+	status: PublishedGoalStatus;
+}
+
+/** Minimal shape of a session entry, used for runtime narrowing. */
+interface BranchEntryLike {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+	};
+}
+
+/**
+ * A stored goal value: `undefined` when it cannot be read, `null` for an explicit
+ * clear, otherwise the validated goal.
+ */
+function readGoal(value: unknown): PublishedGoal | null | undefined {
+	if (value === null) return null;
+	if (!value || typeof value !== "object") return undefined;
+	const goal = value as { objective?: unknown; status?: unknown };
+	if (typeof goal.objective !== "string") return undefined;
+	if (goal.status !== "active" && goal.status !== "achieved") return undefined;
+	const objective = sanitizeLine(goal.objective);
+	if (!objective || objective.length > MAX_GOAL_OBJECTIVE) return undefined;
+	return { objective, status: goal.status };
+}
+
+/** The last goal written on the branch, or `null` when the session has none. */
+export function lastGoal(entries: Iterable<unknown>): PublishedGoal | null {
+	let goal: PublishedGoal | null = null;
+	for (const raw of entries) {
+		const entry = raw as BranchEntryLike;
+
+		// The `/goal` command records a custom entry; the tool records a result below.
+		// Both replay in branch order, so the last write wins.
+		if (entry?.type === "custom" && entry.customType === GOAL_ENTRY_TYPE) {
+			const data = entry.data as { goal?: unknown } | null | undefined;
+			if (!data || typeof data !== "object" || !("goal" in data)) continue;
+			const next = readGoal(data.goal);
+			if (next !== undefined) goal = next;
+			continue;
+		}
+
+		if (entry?.type !== "message") continue;
+		const message = entry.message;
+		if (message?.role !== "toolResult" || message.toolName !== GOAL_TOOL) continue;
+		const details = message.details as { goal?: unknown; error?: unknown } | undefined;
+		if (!details || details.error) continue;
+		if (!("goal" in details)) continue;
+		const next = readGoal(details.goal);
+		if (next !== undefined) goal = next;
+	}
+	return goal;
+}