@quantmind-br/pi-goal-x 0.0.0-stage → 0.35.1

package/docs/prompt-caching.md

@@ -0,0 +1,31 @@
+# Prompt caching
+
+pi-goal-x preserves the provider's reusable prompt prefix during normal user turns, autonomous checkpoints, and tool loops. No extra extension setting is required. Pi's provider configuration still determines whether caching is enabled, its retention period, and model support.
+
+The request layout is:
+
+1. Host system prompt and tool schemas.
+2. Conversation history, with each goal checkpoint normalized to a tiny, stable trigger in its original position.
+3. Request-only goal policy, then a task snapshot, then compact counter/context snapshots, replayed at verified history anchors when safe. Current policy includes the objective, lifecycle rules, the task gate, limits, scheduling state and applicable recovery/auditor reminders. The task snapshot carries task progress: the `[TASK LIST]` header with completed/total counts, the current task with its contract, pending tasks, and the count of omitted pending tasks.
+
+Changing goal state never rewrites the system prompt or historical messages. The full goal-state message is not persisted into the session. Old checkpoints remain until Pi compacts history; retaining small markers avoids shifting the prefix on every continuation. Display-only auditor messages are consistently excluded, and tool calls stay adjacent to their results.
+
+Goal context filtering and live-state tails use Pi's `context_with_system` event, preserving system and tool deltas in their original positions. Parent and delegated sessions use this hook from their first request.
+
+For Anthropic-style explicit caching, the extension moves Pi's existing cache_control breakpoint from the transient state message onto the preceding cacheable history block. The Bedrock equivalent moves the cachePoint. Both preserve the configured TTL and do not add breakpoints. Payloads without an existing explicit marker—including caching disabled and implicit-cache providers—receive no marker changes. The extension does not set cache keys, enable paid extended retention, or replace provider defaults.
+
+Goal and drafting tools share a fixed, idempotent profile: goal progress, focus, lifecycle changes, and draft start/confirm/cancel do not change tool declarations or their prompt rules. Drafting tools reject calls without an active user-started draft. While a draft is active, an execution guard blocks the five ordinary goal tools until confirmation or cancellation. Only changes to disableTasks alter this extension's tool selection and legitimately rebuild the cache. Host tools remain untouched. Drafting messages are appended to conversation history. Isolated auditor and Oracle sessions already use fixed instructions/tool profiles and place goal-specific evidence in their user messages; their tool loops retain history. They have separate sessions and use Pi's cache defaults. Opting these sessions into project resources also opts into any behavior from those resources.
+
+Cache reuse can still be interrupted by Pi compaction, branch/session changes, model/provider switches, other extensions changing earlier content, changed tool schemas, provider expiry, minimum-length or breakpoint-lookback limits, or routing. The extension cannot guarantee a hit rate or a particular cost reduction. The supported host range is Pi 1.4+ within 1.x, with Node 22.19 or newer. Development dependencies pin Pi 1.4.0.
+
+Pi 1.4 prepares custom-triggered turns through the same public startup protocol as user prompts. The extension leaves structured prompt and tool deltas intact, including additional sections supplied by other extensions. Direct creation, drafting, resume and reload use the host's native prompt preparation from the first request. Explicit tool-profile changes can still rebuild the prefix.
+
+Validation includes consecutive request-prefix regressions; actual Anthropic, Anthropic-compatible Chat Completions, OpenAI Chat Completions and Responses serialization with short/long/disabled retention; Bedrock payload-shape checks; lifecycle/tool-pair safety tests; and full SDK parent/auditor/Oracle payload captures. These tests stop before HTTP dispatch. They verify request construction, not live provider hit rates.
+
+Provider references: [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) describes exact-prefix matching and explicit breakpoints; [DeepSeek context caching](https://api-docs.deepseek.com/guides/kv_cache/) describes its automatic prefix cache and usage counters.
+
+Active requests split policy, task snapshots and compact counter/context snapshots into separate tails, always in that order. Already-sent tails are replayed at verified history anchors so implicit-cache requests extend their previous prefix. Each kind is appended only when it differs from its previous copy, so starting, completing or skipping a task, or changing the current task, appends one task snapshot instead of resetting retention (#108 measured four prefix breaks across one three-task run; now only the task setup that enables the completion gate resets). With `blockCompletion` enabled, the policy carries a fixed TASK GATE line that defers to the latest task snapshot, so the pending count never changes policy. Policy changes (including budget/run-limit removal and enabling or disabling the task gate), dropping the task list, rewritten history and unsafe tool-result boundaries reset retention. At most 32 tails, 16 KiB of task snapshots and 4 KiB of counter text are retained per session, across at most 16 session/model identities; exceeding a bound performs one full reset. No full-state tails are persisted. Unchanged requests add no tail. Older task and counter snapshots are historical: the latest snapshot supersedes earlier ones, and current policy takes precedence over cache reuse.
+
+Explicit-marker relocation skips all retained live text and tolerates Pi's trailing effort-only messages. Another extension's content-bearing suffix is left alone. Changing models/providers starts a separate retention identity. Unknown session identities do not retain history between requests.
+
+Validation now includes advancing SDK request chains, combined effort-marker/retention regressions, 1,000-turn growth bounds and a 64 KiB–4 MiB history-cost gate. These are request-construction and CPU measurements, not live provider hit-rate claims.

package/docs/unified-dashboard.md

@@ -0,0 +1,286 @@
+# Unified Dashboard
+
+`pi-goal-x` renders one dashboard component in two presentation modes. The
+above-editor widget, `/goal-status`, and the completion flow all derive from
+the same presentation model (`extensions/widgets/goal-dashboard-model.ts`),
+so they can never drift apart on data or terminology.
+
+- **Compact mode** — a persistent summary above the editor while a goal is
+  focused.
+- **Expanded mode** — the full dashboard: task tree, current-task details,
+  verification, and recent activity. This replaces the former task-list
+  overlay; `Ctrl+Shift+T` now toggles between compact and expanded instead of
+  opening a separate overlay.
+
+Everything shown is derived from persisted goal state and the durable ledger:
+progress, the current task, verification status, the audit result, and recent
+activity are never fabricated for display.
+
+## Compact mode
+
+Always visible above the editor while a goal is focused:
+
+```text
+╭─ pi-goal-x ─ Add CSV export to reports ────────────────────────────────────────────────╮
+│ goal: running [12m47s 18.2K] (+2 open)                                                 │
+├─ Tasks · ✓3 done · 2 open ─────────────────────────────────── [████░░] · Sub 2/3 [██░] ┤
+│ ✓ t1  Review reports page and data source                                              │
+│ ✓ t2  Implement filtered CSV export                                                    │
+│ ▸ t3  Add the download button ☑ ▸ 2/3                                                  │
+│ · t4  Add documentation                                                                │
+│ … +1 more task                                                                         │
+│ Current  t3 · Add the download button                                                  │
+│ Verify   Run npm test with zero failures.                                              │
+│ File     .pi/goals/active_goal_g1.md                                                   │
+╰─ Ctrl+Shift+T: expand tasks─────────────────────────── Ctrl+Shift+A: toggle auditor ● ─╯
+```
+
+Compact rows, in order:
+
+1. Header (rounded corners): title. (Usage lives in the status line below,
+   not in the header.)
+2. Status: `goal: <status> [<elapsed> <tokens>] (+N open)` — the same
+   terminology as the pi footer status line.
+3. Token budget (when configured): `⛽ Budget 18.2K / 50K · 36%`.
+4. Tasks header row: `Tasks · ✓N done · M open` with the compact task
+   progress bar, then the current task's subtask bar beside it
+   (` · Sub done/total ` + bar — the word `Sub` is dropped in narrow mode so
+   the full counts still fit at 50 columns, and the segment is omitted
+   entirely in minimal mode, where the counts and task bar alone use all
+   available space). `N` counts top-level tasks complete **or skipped** — a
+   skipped top-level task counts as done (§9.1) — and `M` counts pending
+   tasks. The subtask segment appears only when the current task has direct
+   children. The whole header row is neutral gray (label, counts, bar fill,
+   and empty cells) so nothing in the progress info is colourful.
+6. Task list section: the top-level tasks shown by default in **pastel
+   amber** (`mdHeading`) with colour-coded markers and ids (✓ complete muted
+   green, ▸ current teal, ~ skipped gray, · pending amber), an aligned id
+   column, truncated amber titles, and a `… +N more` overflow line when the
+   list is longer than the row budget (5 rows at wide, 4 medium, 3 narrow, 2
+   minimal). Tasks that have direct subtasks show a muted `▸ done/total`
+   marker at the end of their row (leaf tasks show none). The current task
+   is fully highlighted in the theme's accent color (marker, id, title). The
+   whole box chrome — top/bottom frame, left/right edges, corners and
+   interior rules — is drawn in one tone: the theme's neutral gray
+   (`muted`). No blue tinge.
+6. Current task: `Current  t3 · Add the download button` (id and title in the
+   accent color).
+7. Goal-level verification contract (first line, truncated).
+8. Blocked or paused detail (reason, suggested action).
+9. Active (or archived) goal file path.
+10. Footer with the expansion shortcut. The whole footer line — leading dash,
+    shortcut hint and trailing fill — is drawn in one frame tone (the
+    neutral-gray `muted`), so the color spans the full width with no two-tone
+    split; the header line is likewise one tone with only the `pi-goal-x`
+    brand in accent. The auditor status lives in the bottom-right of this
+    border: a single `●` — green when the focused goal's independent auditor
+    is on, gray when off — drawn right before the `╯` corner. In wide/medium
+    layouts the footer also right-aligns a `Ctrl+Shift+A: toggle auditor`
+    note beside the dot, making explicit that the shortcut turns the auditor
+    on and off; narrow and minimal keep just the dot. `Ctrl+Shift+A` toggles
+    the auditor per-goal (persisted, `auditor_toggled` ledger event,
+    dashboard refresh, notification; inert with no focused goal, a goal modal
+    open, or a complete goal). The expanded dashboard does not render the
+    auditor indicator.
+
+When every top-level task is done, the current line reads
+`Current  All tasks complete`. With `disableTasks` enabled the task rows are
+omitted entirely.
+
+## Expanded mode
+
+`Ctrl+Shift+T` expands the same component:
+
+```text
+╭─ pi-goal-x ─ Add CSV export to reports ─────────────── 12m47s · 18.2K tok ─╮
+│ Status: ● In progress · Focused: yes · Other goals: 2                      │
+│ File: .pi/goals/active_goal_...                                             │
+├─ Progress ──────────────────────────────────────────────────────────────────┤
+│ [██████░░░░] 3/5 tasks · 60%                                               │
+├─ Tasks ─────────────────────────────────────────────────────────────────────┤
+│ ✓ t1  Review reports page and data source                                  │
+│ ✓ t2  Implement filtered CSV export                                        │
+│ ▸ t3  Add the download button ☑                                            │
+│   ✓ t3.1  Add loading state                                                 │
+│   ✓ t3.2  Generate timestamped filename                                    │
+│   · t3.3  Add error handling                                                │
+│ · t4  Add documentation                                                    │
+│ ~ t5  Add and run tests                                                    │
+├─ Current task ──────────────────────────────────────────────────────────────┤
+│ t3 · Add the download button                                               │
+│ Subtasks [███████░░░] 2/3 · 67%                                            │
+│ Contract: The button downloads a CSV using the active filters.             │
+├─ Verification ──────────────────────────────────────────────────────────────┤
+│ Run npm test with zero failures.                                            │
+├─ Recent activity ───────────────────────────────────────────────────────────┤
+│ ✓ Completed “Implement filtered CSV export”. — Done                        │
+│ ▸ Started “Add error handling”.                                             │
+╰─ Esc/Ctrl+Shift+T: collapse ────────────────────────────────────────────────╯
+```
+
+Task markers (§9.2): `✓` complete, `~` skipped, `▸` current, `·` pending.
+A `☑` suffix marks a task that carries its own verification contract; the full
+contract is shown in the current-task block.
+
+When no persisted current task exists, the dashboard falls back to the first
+pending task for display and marks it as inferred — the fallback is never
+persisted.
+
+## Scrolling the task list
+
+Both views show the task list as a **window** over the plan-ordered list, and
+by default the window is **anchored to the most recently completed task** —
+the viewport is "scrolled down" so recent completions (by `completedAt`) are
+visible instead of always showing the earliest tasks. With nothing completed
+the window starts at the top; when a new task completes the window re-anchors
+to it. `↑ N more tasks` / `… +N more tasks` indicator rows mark rows hidden
+above and below the window.
+
+pi has no separate focus — the prompt editor owns the plain arrow keys — so
+the two views scroll differently:
+
+| View | Key | Action |
+| --- | --- | --- |
+| Expanded (modal) | `↑` / `↓` | Scroll one task row |
+| Expanded (modal) | `PgUp` / `PgDn` | Scroll one page of task rows |
+| Expanded (modal) | `Home` / `End` | Jump to the top / bottom of the list |
+| Compact (inline) | `Ctrl+Shift+↑` / `Ctrl+Shift+↓` | Scroll one task row |
+| Compact (inline) | `Ctrl+Shift+PgUp` / `Ctrl+Shift+PgDn` | Scroll one page |
+| Compact (inline) | `Ctrl+Shift+Home` / `Ctrl+Shift+End` | Jump to the top / bottom |
+
+While the expanded dashboard is open it is modal and owns the plain arrow
+keys (like the session tree or model selector); `Esc` collapses it. The
+compact widget never touches the editor's arrows — it scrolls with the
+`Ctrl+Shift` chords, which pi leaves unbound, so typing and navigation are
+never hijacked. The chords are consumed only when the compact list actually
+overflows its viewport; on a short list they pass through unused. When the
+list overflows, the compact footer advertises the chords
+(`Ctrl+Shift+↑↓: scroll`). `/goal-status` renders the same anchored window as
+a static snapshot (it is not interactive). The window and its indicators are
+width-safe at every layout width.
+
+## Status states
+
+| Symbol | Status | Shown for |
+| --- | --- | --- |
+| `●` | In progress | active goal with auto-continue on |
+| `○` | Idle | active goal with auto-continue off |
+| `◐` | Paused (user/agent) | paused goal, with reason |
+| `⊘` | Blocked | blocked goal, with blocker and suggested action |
+| `⛽` | Budget limited | goal at its token budget, with usage detail |
+| `✓` | Complete | completed goal, before/after archival |
+
+Status labels are always explicit words, so the dashboard stays readable
+without the symbols.
+
+## Unfocused state
+
+When open goals exist but none is focused:
+
+```text
+╭─ pi-goal-x ─ Goal focus required ───────────────────────────────────────────╮
+│ 3 open goals are available.                                                │
+│ Run /goal-focus to choose the goal for this session.                       │
+╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Audit view
+
+During an independent completion audit the widget switches to a structured
+audit dashboard with the same visual system:
+
+```text
+╭─ Independent completion audit ─ anthropic/claude-sonnet:high ─── 2m18s ─╮
+│ ✓ Objective and success criteria                                         │
+│ ✓ Verification contracts                                                 │
+│ ✓ Tasks and recorded evidence                                            │
+│ ◌ Workspace inspection                                                   │
+│ · Final decision                                                         │
+│ [███████░░░] 72%                                                         │
+╰─ Esc: stop audit ─────────────────────────────────────────────────────────╯
+```
+
+Raw auditor tools and output are hidden by default; they appear only in
+expanded/debug audit mode or when the audit failed and diagnostics are needed.
+
+After the audit, a result card shows the outcome:
+
+```text
+╭─ Audit result ─ APPROVED ─────────────────────────────────────────────────╮
+│ ✓ Objective satisfied.                                                    │
+│ ✓ Verification requirements satisfied.                                    │
+│ ✓ Required tasks and evidence accepted.                                   │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+A rejected audit keeps the goal open, shows `CHANGES REQUIRED` with the
+auditor's findings, and returns to the normal dashboard so work can continue.
+
+## Keybindings
+
+| Key | Action |
+| --- | --- |
+| `Ctrl+Shift+T` | Toggle the dashboard between compact and expanded |
+| `Ctrl+Shift+A` | Toggle the focused goal's independent auditor on/off (persisted per-goal; inert with no goal, a goal modal open, or a complete goal) |
+| `↑` / `↓`, `PgUp` / `PgDn`, `Home` / `End` | Scroll the expanded task tree (see [Scrolling the task list](#scrolling-the-task-list)) |
+| `Ctrl+Shift+↑` / `Ctrl+Shift+↓`, `Ctrl+Shift+PgUp` / `Ctrl+Shift+PgDn`, `Ctrl+Shift+Home` / `Ctrl+Shift+End` | Scroll the compact task list |
+| `Esc` | Collapse the expanded dashboard; otherwise pause the goal |
+| `Esc` (during audit) | Stop the audit and choose to continue working or complete without audit |
+
+Configure the three task shortcuts with `keybindings.dashboard.toggleExpand`,
+`keybindings.dashboard.scrollUp`, and `keybindings.dashboard.scrollDown` in
+`.pi/pi-goal-x-settings.json`. The defaults are `ctrl+shift+t`,
+`ctrl+shift+up`, and `ctrl+shift+down`.
+
+## Width behavior
+
+Layout modes (§5.5):
+
+- **Wide (≥100 columns):** full border, multiple fields per line, full task
+  titles, wider progress bars, current-task details.
+- **Medium (70–99):** mostly one field per line, shorter bars, truncated
+  paths and contracts.
+- **Narrow (50–69):** compact border, short labels, reduced metadata, one
+  task line at a time.
+- **Very narrow (<50):** the essential summary only — status, task progress,
+  the current task, and the verification contract.
+
+The renderer never emits a line wider than the terminal width: all alignment
+and truncation is visible-width aware (ANSI colors, Unicode, and double-width
+characters included). Golden tests assert `visibleWidth(line) <= width` for
+every rendered line at 40, 50, 60, 80, 100, and 140 columns.
+
+## `/goal-status`
+
+`/goal-status` renders the same model as the widget.
+
+- Standard mode: a static compact-dashboard rendering, current-task details,
+  recent activity, and the last audit result. No effective-settings noise.
+- `/goal-status verbose`: goal id, revision, full objective, the complete
+  task tree with full evidence and contracts, recent ledger history, token
+  budget detail, pause/blocker detail, active and archived paths, the last
+  audit report, and effective settings with provenance.
+
+## Migration behavior
+
+The current-task focus is a new **optional** persisted field
+(`currentTaskId`) on goal records.
+
+- Legacy goal files load without it and are **never rewritten** just because
+  the field is absent.
+- A persisted `currentTaskId` is accepted only when it references an existing
+  *pending* task; it is cleared when that task is completed, skipped, or
+  removed during normalization.
+- Task-list restructuring preserves the current task only while its id
+  remains pending; otherwise the focus clears and the dashboard recomputes.
+- For display only, the dashboard may infer the first pending task as the
+  current task and marks it as inferred.
+
+## Compatibility
+
+- Existing goal-file formats, archived goals, settings, slash commands, and
+  direct-goal behavior are preserved.
+- The task-overlay shortcut is retained but now expands the unified
+  dashboard; the separate overlay registration is removed.
+- Headless behavior remains functional without TUI rendering, and
+  audit-disabled completion remains explicit and distinct from approval.

package/extensions/auditor-selector.ts

@@ -0,0 +1,74 @@
+/**
+ * Auditor model/thinking selector helpers (ll01 cb6760b pattern).
+ *
+ * `/goal-settings` provider/model rows open a searchable selector: the
+ * current-session/default choice (which clears the explicit provider/model),
+ * authenticated models from the model registry (with a ✓ marker on the exact
+ * current selection), and an advanced manual `provider/model` entry. The
+ * thinking-level row offers Pi's seven levels or `(default)`.
+ */
+
+import { GOAL_THINKING_LEVELS } from "./goal-settings.ts";
+
+export type AuditorModelSummary = { provider: string; id: string; name?: string };
+
+export type AuditorChoice =
+	| { kind: "default"; label: string }
+	| { kind: "model"; provider: string; model: string; label: string }
+	| { kind: "manual"; label: string };
+
+export const AUDITOR_THINKING_LEVELS = GOAL_THINKING_LEVELS;
+
+export function auditorModelLabel(model: AuditorModelSummary): string {
+	return `${model.provider}/${model.id}${model.name && model.name !== model.id ? ` — ${model.name}` : ""}`;
+}
+
+/** `${provider}/${model}` key for the current configured model, if explicit. */
+export function configuredAuditorModelKey(config: { provider?: string; model?: string }): string | undefined {
+	return config.provider && config.model ? `${config.provider}/${config.model}` : undefined;
+}
+
+export function buildAuditorModelChoices(
+	available: AuditorModelSummary[],
+	configured: string | undefined,
+	session: string | undefined,
+): AuditorChoice[] {
+	const models = available.slice().sort((a, b) => auditorModelLabel(a).localeCompare(auditorModelLabel(b)));
+	return [
+		{
+			kind: "default",
+			label: `${configured ? "  " : session ? "✓ " : "  "}Current session / default${session ? ` (${session})` : " (system default)"}`,
+		},
+		...models.map((model) => {
+			const key = `${model.provider}/${model.id}`;
+			return {
+				kind: "model" as const,
+				provider: model.provider,
+				model: model.id,
+				label: `${configured === key ? "✓ " : "  "}${auditorModelLabel(model)}`,
+			};
+		}),
+		{ kind: "manual", label: "✎ Enter provider/model manually (advanced)" },
+	];
+}
+
+export function filterAuditorModelChoices(choices: AuditorChoice[], filter: string): AuditorChoice[] {
+	const normalized = filter.trim().toLowerCase();
+	if (!normalized) return choices;
+	return choices.filter(
+		(choice) => choice.kind === "default" || choice.kind === "manual" || choice.label.toLowerCase().includes(normalized),
+	);
+}
+
+export function parseManualAuditorModel(input: string): { provider: string; model: string } | { error: string } {
+	const value = input.trim();
+	const slash = value.indexOf("/");
+	if (slash <= 0 || slash === value.length - 1) {
+		return { error: "Auditor model must use provider/model format; unavailable models will fail clearly at audit time." };
+	}
+	return { provider: value.slice(0, slash), model: value.slice(slash + 1) };
+}
+
+export function thinkingLevelChoices(current: string | undefined): string[] {
+	return ["(default)", ...AUDITOR_THINKING_LEVELS].map((level) => (level === current ? `✓ ${level}` : `  ${level}`));
+}

package/extensions/goal-accounting.ts

@@ -0,0 +1,107 @@
+/**
+ * GoalAccounting — serialized, idempotent token/time accounting.
+ *
+ * One instance per extension. `begin(goalId)` starts a session for an active
+ * goal; `charge()` computes the elapsed seconds since the last charge and the
+ * completed-turn tokens, then advances the baseline so repeated calls never
+ * double-charge the same wall-clock interval. `liveSeconds()` is a read-only
+ * display helper that does not mutate state.
+ *
+ * Also exposes the token-budget helpers used by the runtime to detect the
+ * one-time `budget_limited` transition.
+ */
+
+export interface AccountingCharge {
+	tokens: number;
+	seconds: number;
+}
+
+export interface BudgetLike {
+	tokenBudget?: number;
+	usage: { tokensUsed: number };
+}
+
+export class GoalAccounting {
+	private activeGoalId: string | null = null;
+	private lastAccountedAt: number | null = null;
+
+	/** Start accounting for a goal id (or clear when null). */
+	begin(goalId: string | null): void {
+		this.activeGoalId = goalId;
+		this.lastAccountedAt = goalId ? Date.now() : null;
+	}
+
+	clear(): void {
+		this.activeGoalId = null;
+		this.lastAccountedAt = null;
+	}
+
+	get goalId(): string | null {
+		return this.activeGoalId;
+	}
+
+	/** True when accounting is active for exactly this goal. */
+	isActiveFor(goalId: string): boolean {
+		return this.activeGoalId === goalId && this.lastAccountedAt !== null;
+	}
+
+	/**
+	 * Serialized idempotent charge: returns the tokens + whole elapsed seconds
+	 * accumulated since the previous charge, then advances the baseline to
+	 * `now`. Calling again immediately afterwards yields 0 seconds (never
+	 * double-charges the same interval).
+	 */
+	charge(opts: { now?: number; completedTurnTokens?: number } = {}): AccountingCharge {
+		const now = opts.now ?? Date.now();
+		const elapsedSeconds = this.lastAccountedAt === null
+			? 0
+			: Math.max(0, Math.floor((now - this.lastAccountedAt) / 1000));
+		this.lastAccountedAt = now;
+		const tokens = Math.max(0, Math.trunc(opts.completedTurnTokens ?? 0));
+		return { tokens, seconds: elapsedSeconds };
+	}
+
+	/** Live elapsed whole seconds for display; does not advance the baseline. */
+	liveSeconds(now = Date.now()): number {
+		if (this.lastAccountedAt === null) return 0;
+		return Math.max(0, Math.floor((now - this.lastAccountedAt) / 1000));
+	}
+}
+
+/** Remaining token budget, or null when no budget is set. */
+export function budgetRemaining(goal: BudgetLike): number | null {
+	if (typeof goal.tokenBudget !== "number" || !Number.isFinite(goal.tokenBudget) || goal.tokenBudget <= 0) {
+		return null;
+	}
+	const used = Math.max(0, Math.floor(goal.usage.tokensUsed));
+	return Math.max(0, Math.floor(goal.tokenBudget - used));
+}
+
+/** True when a budget is set and accounted usage has reached it. */
+export function budgetReached(goal: BudgetLike): boolean {
+	const remaining = budgetRemaining(goal);
+	return remaining !== null && remaining === 0;
+}
+
+/** Token-budget description for display/steering text. */
+export function budgetLine(goal: BudgetLike): string | null {
+	const remaining = budgetRemaining(goal);
+	if (remaining === null) return null;
+	const used = Math.floor(goal.usage.tokensUsed);
+	return `token budget: ${used}/${Math.floor(goal.tokenBudget ?? 0)} used, ${remaining} remaining`;
+}
+
+/** Agent-facing accounting must never read as current context occupancy. */
+export function modelBudgetLine(goal: BudgetLike): string | null {
+	const line = budgetLine(goal);
+	return line ? `Lifetime ${line} (spending cap, not context capacity)` : null;
+}
+
+export interface GoalContextUsage { tokens: number | null; contextWindow: number }
+
+/** A point-in-time observation; older retained observations are historical. */
+export function contextUsageLine(usage?: GoalContextUsage): string {
+	if (!usage || usage.tokens === null || !Number.isFinite(usage.tokens) || usage.tokens < 0
+		|| !Number.isFinite(usage.contextWindow) || usage.contextWindow <= 0) return "Context snapshot: unavailable";
+	return `Context snapshot: ${Math.round(usage.tokens)}/${Math.round(usage.contextWindow)} tokens (${Math.round(100 * usage.tokens / usage.contextWindow)}%)`;
+}