@mocito/pi-goal 0.1.11 → 0.3.0

package/CHANGELOG.md

@@ -1,8 +1,45 @@
 # Changelog
 
-## Unreleased
+All notable changes to this project will be documented in this file.
 
-## 0.1.11 - 2026-07-17
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-11
+
+### Changed
+
+- Compact the footer into a palette-neutral Nerd Font goal icon plus distinct active, paused, blocked, usage-limited, budget-limited, and complete icons. Retain used/budget token counts in every budgeted state; leave command output, notifications, and widget text unchanged. Require Nerd Font 3 or later for footer icons.
+
+## [0.2.0] - 2026-10-09
+
+### Added
+
+- Declare `{ goal }` structured summaries for `get_goal` and `create_goal`, including `goal: null` for empty state, plus `goal` namespace discovery and behavior annotations. Codemode receives objects without `JSON.parse`; terminal updates remain model-only without a new schema.
+- Mark usage-refreshing queries as stateful and serialize them with goal mutations.
+
+### Fixed
+
+- Restrict footer/widget updates to TUI mode; print, JSON and RPC retain goal lifecycle behavior without terminal writes.
+
+### Changed
+
+- Update the shared Pi development and contract-test baseline to 1.1.0; require Node.js >=22.19.0 to match the host runtime. Pi remains a host-supplied peer dependency.
+- Share install telemetry mechanics through `@mocito/install-telemetry` while preserving Pi-specific settings and state paths.
+- Require Pi 1.1.0 for usage-accounting lifecycle and cache-warming hooks. Stop idle cache warming for retained token-budgeted or usage-limited goals without changing no-goal sessions.
+
+### Fixed
+
+- Request automatic goal continuation through `agent_before_settle` after Pi's recovery and queued work, rather than an `agent_end` timer. Preserve other handlers' proposals and append-only history while sending at most one current goal context to the model.
+- Do not restart cancelled/failed runs or failed automatic compaction, including after successful queued work within the same run. Provider-limit notices, like budget notices, no longer request a wrap-up turn.
+- Preserve explicit start/resume/reload activation and wait for tree navigation to finish. Invalidate stale activations across goal/session/branch changes; reject oversized stored objectives without truncation.
+- Keep `update_goal` model-only on supported Pi runtimes (Pi 1.0.2 or newer), preventing codemode and other nested tool calls from completing or blocking a goal before the model inspects verification results. Preserve direct final-turn updates and script access to `get_goal` and `create_goal`.
+- Let `enableInstallTelemetry: false` override an enabled `PI_TELEMETRY` environment flag.
+- Count finalized tool, standalone, compaction, and branch-summary usage in goal budgets, including already-aggregated nested calls and context-omitted billed attempts. Preserve schema-v1 ledgers and backfill previously missed entries once within the branch-local goal lifetime.
+- Enforce saved usage before continuation and settlement, after compaction/navigation, on goal queries, and through a session-scoped idle usage check. Budget notices no longer request an extra model turn.
+
+## [0.1.11] - 2026-07-17
 
 ### Fixed
 
@@ -10,20 +47,20 @@
 - Derive persisted `piGoalVersion` metadata from the package version so release versions cannot drift.
 - Ignore malformed persisted mutations instead of allowing invalid status, budget, or accounting data to corrupt reconstructed goal state.
 
-## 0.1.10 - 2026-07-01
+## [0.1.10] - 2026-07-01
 
 ### Changed
 
 - Update Pi core development dependencies for Pi 0.80 compatibility.
 
-## 0.1.9 - 2026-06-16
+## [0.1.9] - 2026-06-16
 
 ### Fixed
 
 - Notify the model when a goal transitions to `budget_limited` or `usage_limited` so it can stop work and call `update_goal` instead of silently continuing to spend tokens after the budget is exhausted or the provider hits a rate limit. Previously the model was only ever informed via a UI notification that it could not see, leaving the current turn to keep running for additional assistant entries and allowing `update_goal` to mark the goal `complete` long after the budget had been blown.
 - Branch the continuation prompt on the `budget_limited` reason so any future continuation of a budget-limited goal instructs the model to wrap up and call `update_goal` rather than push forward.
 
-## 0.1.8 - 2026-06-08
+## [0.1.8] - 2026-06-08
 
 ### Fixed
 
@@ -31,7 +68,7 @@
 - Reject `update_goal` when it is batched with verification/tool calls in the same assistant turn, forcing completion/blocking decisions to happen after inspecting verification results.
 - Preserve the elapsed-time fix for old sessions by ignoring legacy account mutation `timeUsedSeconds` fields during reconstruction.
 
-## 0.1.7 - 2026-06-08
+## [0.1.7] - 2026-06-08
 
 ### Fixed
 
@@ -41,7 +78,7 @@
 
 - Pause goals on assistant-surfaced provider usage/quota/billing limit errors and repeated provider failures, not only HTTP 429 response hooks.
 
-## 0.1.6 - 2026-06-06
+## [0.1.6] - 2026-06-06
 
 ### Changed
 
@@ -49,14 +86,26 @@
 - Aligned package structure with monorepo guidelines (added root `index.ts` re-export, `.editorconfig`, `.gitignore`; fixed extension entry point; removed non-canonical tsconfig flags).
 - Update `author` field to full name for monorepo consistency.
 
-## 0.1.3
+## [0.1.3] - 2026-06-06
+
+### Changed
+
+- Temporarily rename the package to unscoped `pi-goal`; this version was not published because that npm name was unavailable.
+
+## [0.1.2] - 2026-05-28
+
+### Changed
 
 - Move the extension entry point to `extensions/index.ts` so Pi displays the package extension compactly.
 
-## 0.1.1
+## [0.1.1] - 2026-05-28
+
+### Added
 
 - Add best-effort install/update telemetry, gated by Pi telemetry/offline settings and disabled in CI.
 
-## 0.1.0
+## [0.1.0] - 2026-05-28
+
+### Added
 
 - Initial `@mocito/pi-goal` package with `/goal`, goal tools, branch-scoped session persistence, usage accounting, UI status, and automatic continuation.

package/README.md

@@ -1,6 +1,16 @@
 # @mocito/pi-goal
 
-Persistent long-running goals for Pi, modeled after Codex `/goal`.
+Give Pi a durable objective and let it keep working until the job is verified done.
+
+`pi-goal` adds branch-aware, long-running goals modeled after Codex `/goal`, with automatic continuation, token budgets, progress visibility, and explicit completion checks.
+
+## Features
+
+- **Work beyond one turn** — Pi continues an active goal after successful runs, without restarting cancelled or failed work.
+- **Persistent branch-aware state** — goals survive reloads and follow session trees, forks, and clones without leaking across divergent branches.
+- **Budget control** — cap token use, monitor remaining budget, and pause or resume work at any time.
+- **Visible progress** — track status, active time, token usage, and budget from Pi's UI.
+- **Verified endings** — model tools require explicit completion evidence and stop repeated retries when work is blocked or provider limits intervene.
 
 ## Install
 
@@ -8,6 +18,10 @@ Persistent long-running goals for Pi, modeled after Codex `/goal`.
 pi install npm:@mocito/pi-goal
 ```
 
+Requires Pi 1.1.0 or newer for complete usage accounting and the settlement
+and cache-warming hooks. Development and session-contract tests use Pi 1.1.0.
+There is no legacy fallback for nested terminal updates.
+
 For local development:
 
 ```bash
@@ -36,15 +50,177 @@ Replacing a non-complete goal asks for confirmation when UI is available.
 - `create_goal` creates a goal only when explicitly requested and fails if one already exists.
 - `update_goal` lets the model mark a goal `complete` or `blocked` only. It should mark complete only after requirement-by-requirement verification, and blocked only after the same blocker repeats for at least three goal turns.
 
-## Behavior
+`update_goal` is model-only: it remains available directly to the model with
+codemode disabled, `on`, or `only`, but cannot be called from codemode scripts or
+other tools through `ctx.executeTool()`. Run verification first, inspect the
+results, then call `update_goal` as the only tool call in a separate final
+assistant turn. `get_goal` and `create_goal` remain callable from scripts.
 
-Goal state is stored as immutable `pi-goal` custom session entries and reconstructed from `ctx.sessionManager.getBranch()`, so state follows Pi session branches, tree navigation, forks, and reloads.
+The extension enforces this call boundary, not the truth of the model's
+verification evidence. Trusted extensions still run with the user's permissions.
+
+### Structured script contract
 
-When an active goal is idle, the extension injects a hidden `pi-goal-context` message and triggers another turn. A context filter keeps only the latest goal context message for the current goal to avoid linear context growth.
+On Pi 1.1.0 or newer, `get_goal` and `create_goal` declare output schemas:
 
-The footer and optional editor widget show status, elapsed active time, token usage, and budget.
+- `get_goal` returns `{ goal: summary | null }`, including a stable `null` when
+  no goal exists. Its direct no-goal text stays `No goal is set.`.
+- `create_goal` returns `{ goal: summary }`. It still requires an explicit
+  creation request; discovery metadata is not permission to create a goal.
+- `summary` contains `goalId`, `objective`, `status`, `tokensUsed`,
+  `timeUsedSeconds`, `createdAt`, `updatedAt`, and optional `tokenBudget`,
+  `remainingTokens`, `activeStartedAt`. Internal accounting ledgers,
+  verification metadata and branch entries are not included.
 
-Provider usage-limit handling pauses active goals when Pi exposes HTTP 429 responses or assistant error messages that indicate subscription, quota, billing, balance, or repeated provider failures. This prevents automatic continuation from retrying indefinitely after provider limits such as 5-hour subscription caps. When the budget is exhausted or a provider limit is detected, a visible `pi-goal-event` message is also delivered to the model so it can stop work and call `update_goal` to finalize the goal instead of continuing to spend tokens on a turn that has effectively been cut off.
+```js
+const { goal } = await tools.get_goal({});
+text(goal ? { status: goal.status, remainingTokens: goal.remainingTokens } : "No goal");
+```
+
+Remove old `JSON.parse(await tools.get_goal({}))` wrappers. Direct results remain
+readable JSON and the renderers retain their summaries. Invalid requests and
+creation conflicts throw; scripts must catch rejection. Neither tool uses a
+structured success object with `isError: true`. Legacy oversized objectives remain
+inspectable without silent truncation; new objectives retain the 4,000-character
+input limit.
+
+Await `describeNamespace("goal")`, `describeTool("get_goal")`, or
+`searchTools("goal budget", { namespace: "goal" })`, including with zero inline
+budget. No deferred/codemode-only option or default exposure change is added.
+`update_goal` remains absent from nested discovery and has no output schema.
+
+All goal tools run sequentially. `get_goal` is **not** annotated read-only because
+it refreshes and can persist usage accounting; its repeated bookkeeping is
+idempotent. Creation is non-idempotent. Terminal update is destructive and
+non-idempotent. All are local-only, and the annotations are advisory, not
+approval or evidence verification. Pi owns aggregation of nested usage; these
+snapshots do not add a second usage report.
+
+## Behavior
+
+Goal state is stored as immutable `pi-goal` custom session entries and reconstructed from `ctx.sessionManager.getBranch()`, so state follows Pi session branches, tree navigation, forks, and reloads.
+
+After a successful run, the extension accounts finalized usage and proposes a
+hidden `pi-goal-context` message at Pi's actionable `agent_before_settle` boundary.
+Pi finishes its retry, overflow recovery, compaction, and queued work before
+reaching that boundary. Pi then validates the proposed context and owns the next
+request; there is no post-run `agent_end` timer or new run from `agent_settled`.
+A context filter keeps only the latest message for the current active goal.
+Earlier messages remain in append-only session history.
+
+Cancellation, terminal assistant errors, and failed/cancelled automatic
+compaction suppress goal continuation for that run. Cancellation and ordinary
+errors leave the stored goal active; they do not silently pause or clear it.
+The compaction-failure stop survives queued steering/follow-up work and resets
+only when the whole run reaches the notification-only `agent_settled` event.
+Explicit new input can start work again. Use `/goal pause` to keep it paused.
+Pending steering, follow-up, and user messages take priority and are not consumed
+or duplicated by the goal extension.
+
+Initial `/goal` commands, `/goal resume`, active session startup/reload, and tree
+navigation retain a separate activation path because there may be no running
+boundary. Tree activation waits for navigation to finish. Each activation
+rechecks goal/session/branch identity, saved usage, idle state, and pending work.
+A real run or a goal/session/branch transition invalidates an obsolete activation.
+Resuming or reloading a session with an active goal can therefore restart it,
+including after an earlier cancellation.
+
+Boundary proposals preserve other extensions' entries and continuation requests.
+The incoming `context.canContinue` describes the preview before the goal message:
+it can be false after a normal assistant reply. The goal's custom-message draft
+makes that preview runnable; Pi checks the final preview after all handlers.
+Declining goal continuation does not veto another extension's continuation.
+
+The TUI footer shows a goal icon, a distinct state icon, and compact used/budget
+token counts when a budget exists. The editor widget and `/goal status` retain
+text details, including elapsed active time and token usage.
+Print, JSON and RPC retain the goal lifecycle without terminal footer/widget updates.
+
+### Footer icons
+
+The footer starts with **󰣉** (`nf-md-bullseye_arrow`, `U+F08C9`), followed by:
+
+| Icon | State | Nerd Font glyph |
+| --- | --- | --- |
+| 󰐊 | Active | `nf-md-play` (`U+F040A`) |
+| 󰏤 | Paused | `nf-md-pause` (`U+F03E4`) |
+| 󰌾 | Blocked | `nf-md-lock` (`U+F033E`) |
+| 󰔟 | Provider usage-limited | `nf-md-timer_sand` (`U+F051F`) |
+| 󰆙 | Token budget-limited | `nf-md-counter` (`U+F0199`) |
+| 󰄬 | Complete | `nf-md-check` (`U+F012C`) |
+
+For example, `󰣉 󰐊 12k/50k` is an active goal with about 12,000 tokens used
+against a 50,000-token budget. Budget counts remain visible in every retained
+state, including paused and limited states. Without a budget, only the icons
+appear. Clearing the goal clears the footer.
+
+The footer omits repeated labels and resume instructions; use `/goal status`
+for details and `/goal resume` to resume. Notifications and the active-goal
+widget remain in text. Icons use the terminal's default text color and carry
+state by shape, not stored ANSI colors.
+
+Configure the terminal to use **Nerd Font 3 or later**, preferably its **Mono**
+variant. There is no text footer option or missing-glyph detection; unsupported
+fonts may display boxes. Goal storage, accounting, and continuation are unchanged.
+
+Provider usage-limit handling pauses active goals when Pi exposes HTTP 429 responses or assistant error messages that indicate subscription, quota, billing, balance, or repeated provider failures. This prevents automatic continuation from retrying indefinitely after provider limits such as 5-hour subscription caps. When the budget is exhausted or a provider limit is detected, a visible `pi-goal-event` notice is saved to model context without requesting a wrap-up turn. The model can act on that notice during a request independently started by Pi, the user, or another extension; the notice itself does not spend more tokens.
+
+### Token accounting and attribution
+
+The goal counts reported tokens from finalized assistant messages, tool results,
+standalone usage entries (including cache warming), compactions, and branch
+summaries. Failed or cancelled calls count when Pi persists their usage.
+Nested tool usage is already aggregated by Pi onto the parent tool result and
+is counted once, not by walking nested calls. Cached input tokens count too.
+This is a token budget, not a currency or provider-quota budget.
+
+Virtual-model selections do not change that rule: Pi records the physical
+assistant's usage, and codemode classifier usage is aggregated onto its parent
+tool result. However, a raw `ctx.modelRegistry.classify()` call inside a router
+does **not** automatically create a session usage entry in Pi 1.1.0. The goal
+cannot charge an unrecorded result. Paid automatic routers need an explicit,
+single-count attribution contract before they can be treated as budget-safe;
+do not infer free classification from an unchanged goal total. Classifier
+judgments are not completion evidence or permission to bypass approvals.
+
+The accounting interval starts at the goal's creation/replacement entry and
+ends when it is replaced or cleared on that branch. Earlier work is excluded,
+including entries before creation with the same timestamp. Entries need valid
+timestamps within the interval and no later than the scan time.
+As in earlier v1 releases, **pause stops continuation, not accounting**:
+work while paused, limited, blocked, or complete is still charged to the
+retained goal. Clear or replace the goal before doing unrelated work.
+Completion reports are snapshots of finalized usage at completion.
+
+Accounting uses raw branch history, not the model-context projection. Compacted
+or context-omitted billed attempts still count. Reloads and forks retain the
+inherited entry-ID ledger; divergent branch work is not imported. A tree
+summary's own usage belongs to the destination branch. Navigating back before
+work was done restores that branch's earlier total, not a session-wide spend cap.
+
+Schema-v1 mutations remain compatible; no migration or session rewrite is needed.
+Previously accounted assistant tokens and IDs are retained. The next scan
+backfills newly supported usage entries once, so old goals may show higher
+totals or reach their budgets after upgrading.
+
+Budget enforcement scans saved usage at turn end, before settlement, after
+compaction/tree navigation, on reload, before scheduled continuation, and when
+goals are queried or changed. Pi 1.1 has no extension notification for newly
+saved idle usage, so a session-scoped one-second poll checks for branch changes
+while idle. It does not make provider requests. A budget notice updates visible
+state and model context **without requesting another model turn**.
+
+### Idle cache warming
+
+The extension requests `stop` at an idle warming decision when the retained
+goal has a token budget or is `budget_limited`/`usage_limited`. It never requests
+`warm`, changes Pi's settings, or overrides decisions for no-goal sessions or
+unbudgeted, non-limited goals. Pi uses the last handler that returns an action;
+a later extension can explicitly override this stop.
+
+This policy is idle-only. It does not intercept every provider request, cancel
+in-flight warming, or stop streaming-phase warming. Any persisted warming usage
+within the goal interval is still accounted.
 
 ## Examples
 
@@ -83,15 +259,16 @@ Environment flags:
 ## Troubleshooting
 
 - If continuation does not start, run `/goal status` and confirm the goal is `active`.
-- If a goal stops unexpectedly, check whether it reached its token budget or the provider returned a rate/usage limit. Usage-limit pauses may include a provider reset hint when one is available. A budget-exhausted or rate-limited goal is also surfaced to the model as a `pi-goal-event` in the conversation so it can call `update_goal`; if the model never receives that, the goal stays in `budget_limited` until you run `/goal resume` or `/goal clear`.
+- If a goal stops unexpectedly, check whether the run was cancelled, failed, or hit a token budget/provider limit. Usage-limit pauses may include a provider reset hint. Budget/provider notices do not start another request; the goal remains `budget_limited` or `usage_limited` until explicitly resumed, cleared, or finalized during later work.
 - If context appears stale after tree navigation or reload, run `/goal status`; branch state is reconstructed from the active branch.
 - In print/JSON modes, commands and tools work, but interactive confirmations/editors are unavailable.
 
 ## Limitations
 
-- Token budget is enforced after finalized assistant usage is visible; v1 cannot hard-stop mid-turn, but the model is notified as soon as the overrun is detected so it can stop further work in the same or next turn.
+- Token budget is enforced after finalized usage is saved. It stops goal-driven continuation, not an in-flight provider call, Pi's own recovery, user-requested work, or another extension's continuation. Usage that a provider/tool does not report cannot be counted.
 - Usage-limit handling is best-effort via HTTP responses and assistant error messages; provider transports vary in how much structured limit information they expose.
 - Automatic continuation is session-local, not a background daemon.
+- Oversized stored objectives (over 4,000 characters) are not automatically continued or silently truncated. Edit the objective before resuming.
 
 ## Development and validation
 
@@ -105,6 +282,40 @@ npm run pack:dry-run --workspace packages/pi-goal
 npm audit --omit=dev
 ```
 
+The session-contract suite uses real Pi loading, tool dispatch, provider
+serialization, and session trees with synthetic goals and mocked provider
+traffic. It checks direct and nested calls, codemode discovery, termination,
+reloads, model changes, and branch reconstruction without live credentials or
+provider requests.
+
+Accounting regressions also cover multi-level metered codemode calls, failed
+results, mocked cache warming and remote compaction, branch summaries, context
+omissions, inherited fork histories, and tool-only budget exhaustion. The warming
+tests load the compaction/reasoning hooks in both orders and verify that idle
+refreshes do not change saved reasoning state.
+
+The settlement suite exercises the production extension in real Pi sessions
+with bounded mocked responses. It covers cancellation (including retry and
+pre-settlement cancellation), successful/exhausted retries, compaction
+success/failure, canonical context edits, user queues, extension ordering,
+terminal tools, startup/resume/reload, replacement, forks, tree navigation, and
+TUI/print/JSON/RPC bindings. It also advances controlled timers after settlement
+to detect an obsolete timer that would restart the run. No live credentials are
+used; HTTP responses are mocked and WebSocket traffic is blocked.
+
+Run the focused lifecycle smoke test from the monorepo root:
+
+```bash
+node --import tsx --test packages/pi-goal/tests/settlement-contract.test.mjs
+```
+
+Footer smoke test with a Nerd Font Mono: create a budgeted goal, pause it, and
+resume it. Check the distinct play/pause icons and retained budget numbers.
+Check blocked, usage-limited, budget-limited, and complete icons in retained
+sessions, then clear the goal and check that its status disappears. Repeat at
+narrow/wide widths and after light/dark theme changes; `/goal status` must still
+show text details.
+
 Before publishing, also run the root validation loop:
 
 ```bash

package/SECURITY.md

@@ -25,6 +25,52 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 
 The package does not require API keys and does not read provider credentials. Its model tools can only inspect the current goal, create a new explicitly requested goal when none exists, or mark the current goal `complete`/`blocked`.
 
-On startup, the extension sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, goal objectives, file paths, session data, config values, or API keys. Telemetry writes a local deduplication marker under Pi's agent extensions directory.
+On supported Pi runtimes (Pi 1.1.0 or newer), `update_goal` uses Pi's
+`model-only` exposure. Codemode discovery and nested dispatch through
+`ctx.executeTool()` cannot reach it. A direct update must be the only tool call
+in its assistant turn, after the model has inspected verification results.
+Older runtimes are unsupported; there is no legacy nested-call fallback.
+`get_goal` and `create_goal` remain callable from scripts.
+
+Those two tools expose a declared `{ goal }` summary through `structuredContent`,
+not the full persisted entry or accounting ledger. The objective is user data,
+not automatically secret-scanned. Direct text and renderer details keep the
+same summary fields. `get_goal` can persist refreshed accounting, so its metadata
+does not claim a pure read; all goal tool calls are sequential. Namespace and
+annotation metadata are advisory and do not grant creation or completion authority.
+
+This is a tool-call boundary, not an independent verifier of completion or
+blocker evidence. The model remains responsible for that evidence. A trusted
+extension can execute arbitrary code with the user's permissions; model-only
+exposure is not a sandbox against installed extensions.
+
+On startup, `@mocito/install-telemetry` sends a best-effort install/update telemetry ping to the configured telemetry endpoint once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, goal objectives, file paths, session data, config values, or API keys. Telemetry writes a local deduplication marker under Pi's agent extensions directory.
 
 Goal objectives are treated as untrusted user-provided task data when continuation context is built. They are JSON-encoded before being embedded in the hidden context message to reduce prompt-injection risk from delimiter-breaking text.
+
+Budget accounting reads finalized usage from the raw current branch, including
+context-omitted entries. Its metadata contains only token totals, entry IDs,
+timestamps, and aggregate scan diagnostics—not prompts, tool arguments, raw
+responses, credentials, or encrypted compaction checkpoints. A session-scoped
+idle poll reads the branch leaf ID and scans changed history without making
+network requests.
+
+Budgets are best-effort token accounting, not a hard spending or authorization
+boundary. Unreported usage cannot be counted, active requests can overrun, and
+other extensions can override idle warming decisions. Pause and terminal goal
+states stop goal continuation but do not exclude later branch usage; clear or
+replace a retained goal before unrelated work.
+
+Automatic goal continuation is proposed at Pi's `agent_before_settle` boundary,
+after recovery and queued work, rather than starting a new run from a timer.
+Cancelled/error outcomes and failed automatic compaction do not request more
+goal work. Budget and provider-limit notices are context-only and do not request
+a wrap-up turn. These checks control the goal extension's requests, not Pi's own
+recovery, user input, or another trusted extension's continuation.
+
+Explicit activation on creation, resume, startup/reload, and tree navigation
+rechecks the current goal, session, branch, pending work, and finalized budget.
+Old activations are invalidated on lifecycle changes. An active stored goal can
+resume on reload; use `/goal pause` to persist a stop across reloads.
+Continuation retains JSON framing for untrusted objectives and refuses stored
+objectives beyond the public 4,000-character limit instead of truncating them.

package/extensions/index.ts

@@ -19,7 +19,35 @@ export default function piGoal(pi: ExtensionAPI) {
 
   let goal: GoalState | null = null;
   let consecutiveAssistantErrors = 0;
-  const scheduler = new GoalContinuationScheduler(pi, { getGoal: () => goal });
+  let automaticCompactionFailed = false;
+  const scheduler = new GoalContinuationScheduler(pi, { getGoal: () => goal, beforeContinue: accountAndEnforceBudget });
+  let idleAccountingTimer: ReturnType<typeof setInterval> | undefined;
+
+  function stopIdleAccounting(): void {
+    if (idleAccountingTimer) clearInterval(idleAccountingTimer);
+    idleAccountingTimer = undefined;
+  }
+
+  function startIdleAccounting(ctx: ExtensionContext): void {
+    stopIdleAccounting();
+    let lastLeaf = ctx.sessionManager.getLeafId?.();
+    // Pi 1.1 emits warming entry_appended only to SDK listeners, not extensions.
+    // Poll the cheap public leaf ID; scan billing history only when it changes.
+    idleAccountingTimer = setInterval(() => {
+      try {
+        if (!ctx.isIdle() || !goal) return;
+        const leaf = ctx.sessionManager.getLeafId?.();
+        if (leaf === lastLeaf) return;
+        accountAndEnforceBudget(ctx);
+        lastLeaf = ctx.sessionManager.getLeafId?.();
+      } catch {
+        // SDK disposal can invalidate contexts without dispatching shutdown.
+        // Never keep using a stale context; normal lifecycle checks still apply.
+        stopIdleAccounting();
+      }
+    }, 1000);
+    idleAccountingTimer.unref();
+  }
 
   const setGoal = (next: GoalState | null) => { goal = next; };
 
@@ -36,11 +64,8 @@ export default function piGoal(pi: ExtensionAPI) {
   // Send a visible message to the model so it can react to a terminal
   // status transition (budget exhausted, provider limit hit) instead of
   // silently continuing to spend tokens on work that is about to be cut
-  // off. The scheduler has already been cleared at this point, so this
-  // is the model's only chance to learn about the transition before the
-  // user notices.
+  // off. Terminal notices are context-only: they must not buy another request.
   function notifyAgentOfTerminalTransition(
-    ctx: ExtensionContext,
     content: string,
     details: Record<string, unknown>,
   ): void {
@@ -51,7 +76,7 @@ export default function piGoal(pi: ExtensionAPI) {
         display: true,
         details: { ...details, piGoalVersion: PI_GOAL_VERSION },
       },
-      { triggerTurn: true, deliverAs: ctx.isIdle() ? "steer" : "followUp" },
+      { triggerTurn: false },
     );
   }
 
@@ -74,7 +99,6 @@ export default function piGoal(pi: ExtensionAPI) {
     updateGoalUi(ctx, goal);
     scheduler.clear();
     notifyAgentOfTerminalTransition(
-      ctx,
       `<provider_limit>\nYour persistent Pi goal has been paused because the provider hit a usage/rate limit${suffix}. The goal is in the "usage_limited" state. Do not do any more work that would use additional tokens. Use /goal resume to continue after the limit resets, or call update_goal with status "complete" or "blocked" to finalize the goal now.\n</provider_limit>`,
       {
         kind: "provider_limit",
@@ -103,7 +127,6 @@ export default function piGoal(pi: ExtensionAPI) {
       ctx.ui.notify("Goal token budget reached.", "warning");
       scheduler.clear();
       notifyAgentOfTerminalTransition(
-        ctx,
         `<budget_exceeded>\nYour persistent Pi goal's token budget of ${snapshot.tokenBudget} has been reached (used ${snapshot.tokensUsed} tokens). Stop work immediately to avoid burning more tokens. If all requirements are satisfied, call update_goal with status "complete". If the goal cannot be completed, call update_goal with status "blocked". Do not do any more work that would use additional tokens.\n</budget_exceeded>`,
         {
           kind: "budget_exceeded",
@@ -119,6 +142,7 @@ export default function piGoal(pi: ExtensionAPI) {
   registerGoalRenderers(pi);
   registerGoalTools(pi, {
     getGoal: () => goal,
+    refreshUsage: accountAndEnforceBudget,
     setGoal,
     afterGoalChanged,
     clearContinuation: () => scheduler.clear(),
@@ -128,6 +152,7 @@ export default function piGoal(pi: ExtensionAPI) {
     description: "set or view the goal for a long-running task",
     getArgumentCompletions: goalCompletions,
     handler: async (args, ctx) => {
+      accountAndEnforceBudget(ctx);
       await handleGoalCommand(pi, args, ctx, {
         getGoal: () => goal,
         setGoal,
@@ -138,6 +163,9 @@ export default function piGoal(pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    scheduler.clear();
+    automaticCompactionFailed = false;
+    consecutiveAssistantErrors = 0;
     const diagnostics: string[] = [];
     goal = reconstructGoalState(ctx.sessionManager.getBranch() as any[], diagnostics);
     if (goal?.status === "active" && !goal.activeStartedAt) {
@@ -147,22 +175,48 @@ export default function piGoal(pi: ExtensionAPI) {
       goal = applyGoalMutation(goal, resumed);
     }
     if (diagnostics.length) ctx.ui.notify(`pi-goal: ${diagnostics[0]}`, "warning");
+    accountAndEnforceBudget(ctx);
     updateGoalUi(ctx, goal);
+    startIdleAccounting(ctx);
     if (goal?.status === "active" && ctx.isIdle() && !ctx.hasPendingMessages()) scheduler.schedule(ctx, "continue");
   });
 
   pi.on("session_tree", async (_event, ctx) => {
     scheduler.clear();
+    automaticCompactionFailed = false;
+    consecutiveAssistantErrors = 0;
     goal = reconstructGoalState(ctx.sessionManager.getBranch() as any[]);
+    accountAndEnforceBudget(ctx);
     updateGoalUi(ctx, goal);
-    if (goal?.status === "active" && ctx.isIdle() && !ctx.hasPendingMessages()) scheduler.schedule(ctx, "continue");
+    startIdleAccounting(ctx);
+    if (goal?.status === "active" && !ctx.hasPendingMessages()) scheduler.schedule(ctx, "continue", { afterTree: true });
   });
 
   pi.on("session_compact", async (_event, ctx) => {
     goal = reconstructGoalState(ctx.sessionManager.getBranch() as any[]);
+    accountAndEnforceBudget(ctx);
     updateGoalUi(ctx, goal);
   });
 
+  pi.on("session_compact_failed", (event) => {
+    if (event.reason !== "manual") {
+      automaticCompactionFailed = true;
+      scheduler.clear();
+    }
+  });
+
+  pi.on("agent_start", () => {
+    // A real run supersedes any idle activation. Never leave a timer behind
+    // that could restart the session after cancellation or recovery.
+    scheduler.clear();
+  });
+
+  pi.on("agent_settled", () => {
+    // agent_start also fires for queued work inside the same high-level run.
+    // Keep a compaction failure latched until that entire run has settled.
+    automaticCompactionFailed = false;
+  });
+
   pi.on("message_end", async (event: any, ctx) => {
     if (event.message?.role !== "assistant") return;
     const classification = classifyAssistantError(event.message);
@@ -183,12 +237,26 @@ export default function piGoal(pi: ExtensionAPI) {
   });
 
   pi.on("turn_end", async (_event, ctx) => {
+    // Unlike message_end, this boundary sees persisted assistant/tool entries.
     accountAndEnforceBudget(ctx);
   });
 
   pi.on("agent_end", async (_event, ctx) => {
     accountAndEnforceBudget(ctx);
-    if (goal?.status === "active") scheduler.schedule(ctx, "continue");
+  });
+
+  pi.on("agent_before_settle", (event, ctx) => {
+    accountAndEnforceBudget(ctx);
+    if (!automaticCompactionFailed) return scheduler.beforeSettle(event, ctx);
+  });
+
+  pi.on("cache_warming_decision", async (_event, ctx) => {
+    accountAndEnforceBudget(ctx);
+    // Never enable warming or change no-goal sessions. Pi chains actions in
+    // registration order, so a later handler can explicitly override this stop.
+    if (ctx.isIdle() && goal && (goal.tokenBudget != null || goal.status === "budget_limited" || goal.status === "usage_limited")) {
+      return { action: "stop" };
+    }
   });
 
   pi.on("after_provider_response", async (event, ctx) => {
@@ -208,7 +276,13 @@ export default function piGoal(pi: ExtensionAPI) {
     accountAndEnforceBudget(ctx);
     scheduler.clear();
   });
+  pi.on("session_before_tree", (_event, ctx) => {
+    accountAndEnforceBudget(ctx);
+    scheduler.clear();
+  });
   pi.on("session_shutdown", async (_event, ctx) => {
+    stopIdleAccounting();
+    accountAndEnforceBudget(ctx);
     if (goal?.status === "active") {
       const time = realizedTimeUsed(goal);
       const stopped = statusMutation(goal, "active", time, undefined, transitionMeta("session_shutdown", goal, time, nowIso()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocito/pi-goal",
-  "version": "0.1.11",
+  "version": "0.3.0",
   "description": "Persistent long-running goals for Pi.",
   "type": "module",
   "license": "MIT",
@@ -53,18 +53,21 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.0",
-    "@earendil-works/pi-coding-agent": "^0.80.0",
-    "@earendil-works/pi-tui": "^0.80.0",
-    "@types/node": "^26.1.0",
-    "typebox": "^1.3.4",
-    "tsx": "^4.23.0",
-    "typescript": "^6.0.3"
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@types/node": "^26.6.3",
+    "tsx": "^4.23.15",
+    "typebox": "^1.3.34",
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@mocito/install-telemetry": "0.1.1"
   }
 }

package/src/accounting.ts

@@ -1,7 +1,8 @@
 import type { BranchEntry, GoalMutation, GoalState } from "./types.js";
-import { GOAL_SCHEMA_VERSION } from "./types.js";
+import { GOAL_ENTRY_TYPE, GOAL_SCHEMA_VERSION } from "./types.js";
 import { withPiGoalVersion } from "./metadata.js";
 import { nowIso } from "./utils.js";
+import { isKnownMutation } from "./state.js";
 
 export interface UsageAccountingResult {
   mutation?: GoalMutation;
@@ -12,7 +13,10 @@ export interface UsageAccountingResult {
 
 export function assistantUsageTokens(message: any): number {
   if (!message || message.role !== "assistant") return 0;
-  const usage = message.usage;
+  return usageTokens(message.usage);
+}
+
+function usageTokens(usage: any): number {
   if (!usage || typeof usage !== "object") return 0;
   if (Number.isFinite(usage.totalTokens)) return Math.max(0, Math.floor(usage.totalTokens));
   return [usage.input, usage.output, usage.cacheRead, usage.cacheWrite]
@@ -20,28 +24,47 @@ export function assistantUsageTokens(message: any): number {
     .reduce((sum, n) => sum + Math.max(0, Math.floor(n)), 0);
 }
 
+function entryUsage(entry: BranchEntry): any {
+  if (entry.type === "message" && (entry.message?.role === "assistant" || entry.message?.role === "toolResult")) {
+    // Pi already aggregates every nesting level onto the transcript tool result.
+    return entry.message.usage;
+  }
+  if (entry.type === "usage" || entry.type === "compaction" || entry.type === "branch_summary") return entry.usage;
+}
+
 export function accountUsageFromBranch(goal: GoalState, branchEntries: BranchEntry[], endMs = Date.now()): UsageAccountingResult {
   const accounted = new Set(goal.accountedUsage.entryIds);
   const createdMs = Date.parse(goal.createdAt);
+  // Entry order disambiguates work finalized in the same millisecond as creation.
+  // Timestamp-only fallback supports existing callers with an unpersisted goal.
+  const startIndex = branchEntries.findIndex((entry) => entry?.type === "custom" && entry.customType === GOAL_ENTRY_TYPE
+    && isKnownMutation(entry.data) && entry.data.goalId === goal.goalId && (entry.data.kind === "create" || entry.data.kind === "replace"));
   let addedTokens = 0;
   let scannedAssistantEntries = 0;
+  let scannedUsageEntries = 0;
   let cacheTokensIncluded = false;
   const addedEntryIds: string[] = [];
-  for (const entry of branchEntries) {
-    if (entry?.type !== "message" || !entry.id || entry.message?.role !== "assistant") continue;
-    scannedAssistantEntries++;
+  for (const entry of branchEntries.slice(startIndex + 1)) {
+    if (!entry || typeof entry.id !== "string" || !entry.id) continue;
+    // A retained goal ends at replacement/clear, not pause or terminal status.
+    if (entry.type === "custom" && entry.customType === GOAL_ENTRY_TYPE
+      && isKnownMutation(entry.data)
+      && (entry.data.kind === "create" || entry.data.kind === "replace" || entry.data.kind === "clear")) break;
     if (accounted.has(entry.id)) continue;
     const entryMs = Date.parse(entry.timestamp ?? "");
-    if (Number.isFinite(createdMs) && Number.isFinite(entryMs) && entryMs < createdMs) continue;
-    const usage = entry.message?.usage;
+    if (!Number.isFinite(createdMs) || !Number.isFinite(entryMs) || entryMs < createdMs || entryMs > endMs) continue;
+    const usage = entryUsage(entry);
+    if (!usage) continue;
+    scannedUsageEntries++;
+    if (entry.message?.role === "assistant") scannedAssistantEntries++;
     if (usage && (Number.isFinite(usage.cacheRead) || Number.isFinite(usage.cacheWrite))) cacheTokensIncluded = true;
-    const tokens = assistantUsageTokens(entry.message);
+    const tokens = usageTokens(usage);
     if (tokens <= 0) continue;
     addedTokens += tokens;
+    accounted.add(entry.id);
     addedEntryIds.push(entry.id);
   }
   if (addedTokens === 0) return { goal, addedTokens: 0, addedEntryIds };
-  void endMs;
   const mutation: GoalMutation = {
     schemaVersion: GOAL_SCHEMA_VERSION,
     kind: "account",
@@ -51,7 +74,7 @@ export function accountUsageFromBranch(goal: GoalState, branchEntries: BranchEnt
     at: nowIso(),
     meta: withPiGoalVersion({
       source: "accounting",
-      accounting: { scannedAssistantEntries, addedEntryCount: addedEntryIds.length, cacheTokensIncluded },
+      accounting: { scannedAssistantEntries, scannedUsageEntries, addedEntryCount: addedEntryIds.length, cacheTokensIncluded },
     }),
   };
   return {

package/src/commands.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { GoalMutation, GoalState, ParsedGoalCommand } from "./types.js";
+import type { GoalMutation, GoalState, GoalStatus, ParsedGoalCommand } from "./types.js";
 import { GOAL_EVENT_TYPE, GOAL_SCHEMA_VERSION, GOAL_SUMMARY_TYPE } from "./types.js";
 import { accountUsageFromBranch } from "./accounting.js";
 import { appendGoalMutation, applyGoalMutation, createGoalMutation, replaceGoalMutation, statusMutation } from "./state.js";
@@ -138,18 +138,21 @@ function accountCurrent(pi: ExtensionAPI, ctx: ExtensionCommandContext, goal: Go
   return result.goal;
 }
 
+const GOAL_ICON = "\u{f08c9}"; // Nerd Fonts 3 nf-md-bullseye_arrow
+const GOAL_STATUS_ICONS: Record<GoalStatus, string> = {
+  active: "\u{f040a}", // nf-md-play
+  paused: "\u{f03e4}", // nf-md-pause
+  blocked: "\u{f033e}", // nf-md-lock
+  usage_limited: "\u{f051f}", // nf-md-timer_sand
+  budget_limited: "\u{f0199}", // nf-md-counter
+  complete: "\u{f012c}", // nf-md-check
+};
+
 export function formatGoalFooter(goal: GoalState | null): string | undefined {
   if (!goal) return undefined;
   const summary = goalToSummary(goal);
-  const budget = summary.tokenBudget ? ` (${summary.tokensUsed >= 1000 ? Math.round(summary.tokensUsed / 1000) + "k" : summary.tokensUsed}/${summary.tokenBudget >= 1000 ? Math.round(summary.tokenBudget / 1000) + "k" : summary.tokenBudget})` : "";
-  switch (summary.status) {
-    case "active": return summary.tokenBudget ? `Goal: active${budget}` : "Pursuing goal";
-    case "paused": return "Goal paused (/goal resume)";
-    case "blocked": return "Goal blocked (/goal resume)";
-    case "usage_limited": return "Goal hit usage limits (/goal resume)";
-    case "budget_limited": return `Goal unmet${budget}`;
-    case "complete": return `Goal achieved${budget}`;
-  }
+  const budget = summary.tokenBudget ? ` ${summary.tokensUsed >= 1000 ? Math.round(summary.tokensUsed / 1000) + "k" : summary.tokensUsed}/${summary.tokenBudget >= 1000 ? Math.round(summary.tokenBudget / 1000) + "k" : summary.tokenBudget}` : "";
+  return `${GOAL_ICON} ${GOAL_STATUS_ICONS[summary.status]}${budget}`;
 }
 
 export function formatWidget(goal: GoalState | null): string[] | undefined {

package/src/continuation.ts

@@ -1,63 +1,99 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentBeforeSettleEvent, BoundaryResult, CustomMessageEntryDraft, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildGoalContextMessage } from "./prompts.js";
 import { PI_GOAL_VERSION } from "./metadata.js";
-import { GOAL_CONTEXT_TYPE } from "./types.js";
+import { GOAL_CONTEXT_TYPE, MAX_OBJECTIVE_CHARS } from "./types.js";
 import type { GoalContextReason, GoalState } from "./types.js";
 
 export interface ContinuationRuntime {
   getGoal(): GoalState | null;
+  beforeContinue?(ctx: ExtensionContext): void;
 }
 
 export class GoalContinuationScheduler {
-  private scheduled = false;
-  private inFlight = false;
   private timer: NodeJS.Timeout | undefined;
   private turnCount = 0;
-  private lastGoalId: string | undefined;
+  private generation = 0;
 
   constructor(private readonly pi: ExtensionAPI, private readonly runtime: ContinuationRuntime) {}
 
-  schedule(ctx: ExtensionContext, reason: GoalContextReason | string = "continue"): void {
+  /** Only for explicit activation when there is no running settlement boundary. */
+  schedule(ctx: ExtensionContext, reason: GoalContextReason | string = "continue", options: { afterTree?: boolean } = {}): void {
     const goal = this.runtime.getGoal();
-    if (!goal || goal.status !== "active") return;
-    if (ctx.hasPendingMessages()) return;
-    if (this.scheduled || this.inFlight) return;
-    this.scheduled = true;
-    this.lastGoalId = goal.goalId;
-    this.timer = setTimeout(() => {
+    if (!goal || goal.status !== "active" || (!options.afterTree && !ctx.isIdle()) || ctx.hasPendingMessages()) return;
+    // A replacement or a second explicit activation supersedes the old timer.
+    this.clear();
+    const generation = this.generation;
+    const sessionId = ctx.sessionManager.getSessionId();
+    const leafId = ctx.sessionManager.getLeafId();
+    const fire = () => {
       this.timer = undefined;
-      void this.fire(ctx, reason as GoalContextReason);
-    }, 0);
+      try {
+        if (generation !== this.generation || ctx.signal?.aborted || ctx.hasPendingMessages()) return;
+        if (ctx.sessionManager.getSessionId() !== sessionId) return;
+        if (!ctx.isIdle()) {
+          // Pi releases the navigation operation only after ALL session_tree
+          // handlers return. A later async handler may still be finishing.
+          // agent_start or any invalidation clears this activation meanwhile.
+          if (options.afterTree) this.timer = setTimeout(fire, 50);
+          return;
+        }
+        if (leafId && !ctx.sessionManager.getBranch().some((entry) => entry.id === leafId)) return;
+        this.runtime.beforeContinue?.(ctx);
+        const current = this.runtime.getGoal();
+        if (generation !== this.generation || !current || current.status !== "active" || current.goalId !== goal.goalId) return;
+        const draft = this.buildDraft(current, reason as GoalContextReason);
+        if (!draft) return;
+        const { type: _type, ...message } = draft;
+        this.pi.sendMessage(message, { triggerTurn: true });
+      } catch {
+        // A disposed/replaced SDK runtime invalidates captured contexts, even
+        // without session_shutdown. Fail closed rather than restart stale work.
+      }
+    };
+    this.timer = setTimeout(fire, 0);
   }
 
-  private async fire(ctx: ExtensionContext, reason: GoalContextReason): Promise<void> {
-    this.scheduled = false;
+  /** The caller accounts finalized usage before making this synchronous proposal. */
+  beforeSettle(event: AgentBeforeSettleEvent, ctx: ExtensionContext): BoundaryResult | undefined {
+    this.clear();
     const goal = this.runtime.getGoal();
-    if (!goal || goal.status !== "active" || goal.goalId !== this.lastGoalId) return;
-    if (ctx.hasPendingMessages()) return;
-    this.inFlight = true;
-    this.turnCount++;
-    try {
-      this.pi.sendMessage({
-        customType: GOAL_CONTEXT_TYPE,
-        content: buildGoalContextMessage(goal, reason === "created" || reason === "resumed" || reason === "objective_updated" ? reason : "continue"),
-        display: false,
-        details: { goalId: goal.goalId, reason, turnCount: this.turnCount, piGoalVersion: PI_GOAL_VERSION, status: goal.status, usage: { tokensUsed: goal.tokensUsed, timeUsedSeconds: goal.timeUsedSeconds } },
-      }, { triggerTurn: true, deliverAs: ctx.isIdle() ? "steer" : "followUp" });
-    } finally {
-      this.inFlight = false;
+    if (!goal || goal.status !== "active" || event.outcome !== "completed" || ctx.signal?.aborted) return;
+    if (goal.objective.length > MAX_OBJECTIVE_CHARS) return;
+    if (ctx.hasPendingMessages() || event.context.pendingMessages.length > 0) return;
+
+    const proposed = event.entries.some((entry) => entry.type === "custom_message"
+      && entry.customType === GOAL_CONTEXT_TYPE && (entry.details as { goalId?: string } | undefined)?.goalId === goal.goalId);
+    if (proposed && event.context.canContinue) {
+      return { continue: true };
     }
+    // canContinue describes the preview BEFORE our draft. It is normally false
+    // after an assistant reply. This user-role custom message makes it runnable;
+    // Pi rebuilds and validates the final preview after all handlers have run.
+    const draft = this.buildDraft(goal, "continue");
+    if (draft) return { entries: [...event.entries, draft], continue: true };
+  }
+
+  private buildDraft(goal: GoalState, reason: GoalContextReason): CustomMessageEntryDraft | undefined {
+    // Public inputs are validated already; do not turn oversized legacy/raw
+    // session data into an unbounded prompt or silently truncate the objective.
+    if (goal.objective.length > MAX_OBJECTIVE_CHARS) return;
+    return {
+      type: "custom_message",
+      customType: GOAL_CONTEXT_TYPE,
+      content: buildGoalContextMessage(goal, reason === "created" || reason === "resumed" || reason === "objective_updated" ? reason : "continue"),
+      display: false,
+      details: { goalId: goal.goalId, reason, turnCount: ++this.turnCount, piGoalVersion: PI_GOAL_VERSION, status: goal.status, usage: { tokensUsed: goal.tokensUsed, timeUsedSeconds: goal.timeUsedSeconds } },
+    };
   }
 
   clear(): void {
-    this.scheduled = false;
-    this.inFlight = false;
+    this.generation++;
     if (this.timer) clearTimeout(this.timer);
     this.timer = undefined;
   }
 
   isScheduled(): boolean {
-    return this.scheduled;
+    return this.timer !== undefined;
   }
 }
 

package/src/install-telemetry.ts

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { reportInstallTelemetry as report } from "@mocito/install-telemetry";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const PACKAGE_NAME = "pi-goal";
-const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
-const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const INSTALL_TELEMETRY_ENDPOINT = "https://mocito.dev/api/report-install";
 const CI_ENVIRONMENT_VARIABLES = [
   "APPVEYOR",
   "BITBUCKET_BUILD_NUMBER",
@@ -24,10 +23,6 @@ const CI_ENVIRONMENT_VARIABLES = [
   "VERCEL",
 ];
 
-interface InstallTelemetryState {
-  lastReportedVersion?: string;
-}
-
 interface PiSettingsDocument {
   enableInstallTelemetry?: unknown;
 }
@@ -51,18 +46,15 @@ function isPresentEnvFlag(value: string | undefined): boolean {
   return normalized !== "0" && normalized !== "false" && normalized !== "no";
 }
 
-function isCiEnvironment(): boolean {
-  if (isTruthyEnvFlag(process.env.CI)) return true;
-  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
-}
-
-function isInstallTelemetryEnabled(): boolean {
-  if (isCiEnvironment()) return false;
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+export function isInstallTelemetryEnabled(env: NodeJS.ProcessEnv = process.env, settingsPath = join(getAgentDir(), "settings.json")): boolean {
+  if (isTruthyEnvFlag(env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(env[name]))) return false;
+  if (isTruthyEnvFlag(env.PI_OFFLINE)) return false;
 
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
-  return settings.enableInstallTelemetry !== false;
+  const settings = readJsonFile(settingsPath) as PiSettingsDocument;
+  if (settings.enableInstallTelemetry === false) return false;
+  if (env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(env.PI_TELEMETRY);
+  return true;
 }
 
 function getPackageVersion(): string {
@@ -70,35 +62,16 @@ function getPackageVersion(): string {
   return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
 }
 
-function getInstallTelemetryUserAgent(version: string): string {
-  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
-  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
-  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
-}
-
-async function reportInstallTelemetryAsync(): Promise<void> {
+export function reportInstallTelemetry(): void {
   try {
-    if (!isInstallTelemetryEnabled()) return;
-
-    const version = getPackageVersion();
-    const extensionsDir = join(getAgentDir(), "extensions");
-    const statePath = join(extensionsDir, "pi-goal-install.json");
-    const state = readJsonFile(statePath) as InstallTelemetryState;
-    if (state.lastReportedVersion === version) return;
-
-    await mkdir(extensionsDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
-
-    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
-    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
-      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
-      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
-    });
+    void report({
+      endpoint: INSTALL_TELEMETRY_ENDPOINT,
+      tool: PACKAGE_NAME,
+      version: getPackageVersion(),
+      statePath: join(getAgentDir(), "extensions", "pi-goal-install.json"),
+      enabled: isInstallTelemetryEnabled(),
+    }).catch(() => undefined);
   } catch {
-    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+    // Best-effort telemetry: ignore local policy and filesystem failures.
   }
 }
-
-export function reportInstallTelemetry(): void {
-  void reportInstallTelemetryAsync();
-}

package/src/state.ts

@@ -69,7 +69,7 @@ export function applyGoalMutation(current: GoalState | null, mutation: GoalMutat
   }
 }
 
-function isKnownMutation(value: Partial<GoalMutation> | undefined): value is GoalMutation {
+export function isKnownMutation(value: Partial<GoalMutation> | undefined): value is GoalMutation {
   if (!value || value.schemaVersion !== GOAL_SCHEMA_VERSION || typeof value.kind !== "string" || !validTimestamp(value.at)) return false;
   const mutation = value as Record<string, unknown>;
   if (value.kind === "clear") return optionalNonNegativeInteger(mutation.timeUsedSeconds);

package/src/tool-contracts.ts

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+import type { GoalSummary } from "./types.js";
+
+export const GOAL_NAMESPACE = {
+  name: "goal",
+  description: "Inspect or explicitly create the current branch's persistent goal.",
+  instructions: "get_goal and create_goal return { goal }, with goal:null only when no goal is set. Await dependent calls: create_goal mutates branch state and fails if a goal exists. get_goal refreshes usage bookkeeping before returning a snapshot. Errors reject rather than returning a success object. Creation requires an explicit user/system/developer request. update_goal remains model-only: call it directly, alone in a final assistant turn after verification, never from a script.",
+};
+
+const summary = Type.Object({
+  goalId: Type.String(),
+  // Creation is limited to 4,000 chars; legacy stored objectives remain readable.
+  objective: Type.String(),
+  status: Type.Union(["active", "paused", "blocked", "usage_limited", "budget_limited", "complete"].map(value => Type.Literal(value))),
+  tokenBudget: Type.Optional(Type.Integer({ minimum: 1 })),
+  tokensUsed: Type.Number({ minimum: 0 }),
+  remainingTokens: Type.Optional(Type.Number()),
+  timeUsedSeconds: Type.Number({ minimum: 0 }),
+  createdAt: Type.String(), updatedAt: Type.String(), activeStartedAt: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+
+export const GET_GOAL_OUTPUT = Type.Object({ goal: Type.Union([summary, Type.Null()]) }, { additionalProperties: false });
+export const CREATE_GOAL_OUTPUT = Type.Object({ goal: summary }, { additionalProperties: false });
+
+export function goalResult(goal: GoalSummary | null) {
+  const text = JSON.stringify({ goal }, null, 2);
+  const payload = JSON.parse(text);
+  return {
+    content: [{ type: "text" as const, text: goal ? text : "No goal is set." }],
+    structuredContent: payload,
+    details: payload,
+  };
+}

package/src/tools.ts

@@ -8,9 +8,11 @@ import { findToolCallContext, transitionMeta } from "./metadata.js";
 import type { BranchEntry, GoalState, GoalStatus } from "./types.js";
 import { goalToSummary, goalUsageSummary, nowIso, realizedTimeUsed, truncateOneLine } from "./utils.js";
 import { validateObjective, validateTokenBudget } from "./validation.js";
+import { CREATE_GOAL_OUTPUT, GET_GOAL_OUTPUT, GOAL_NAMESPACE, goalResult } from "./tool-contracts.js";
 
 export interface ToolRuntime {
   getGoal(): GoalState | null;
+  refreshUsage?(ctx: ExtensionContext): void;
   setGoal(goal: GoalState | null): void;
   afterGoalChanged(ctx: ExtensionContext, event?: string): void;
   clearContinuation(): void;
@@ -34,15 +36,21 @@ const UpdateGoalParams = Type.Object({
 export function registerGoalTools(pi: ExtensionAPI, runtime: ToolRuntime): void {
   pi.registerTool({
     name: "get_goal",
+    namespace: GOAL_NAMESPACE,
+    outputSchema: GET_GOAL_OUTPUT,
+    executionMode: "sequential",
+    // Querying refreshes/persists usage accounting; it is not a pure read.
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     label: "Get Goal",
     description: "Return the current persistent Pi goal and usage for this session branch.",
     promptSnippet: "Inspect the active persistent goal and token/time budget.",
     promptGuidelines: ["Use get_goal when you need current pi-goal objective, status, usage, or remaining budget."],
     parameters: Type.Object({}, { additionalProperties: false }),
-    async execute() {
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      runtime.refreshUsage?.(ctx);
       const goal = runtime.getGoal();
       const payload = goal ? goalToSummary(goal) : null;
-      return { content: [{ type: "text", text: payload ? JSON.stringify({ goal: payload }, null, 2) : "No goal is set." }], details: { goal: payload } };
+      return goalResult(payload);
     },
     renderCall(_args, theme) {
       return new Text(theme.fg("toolTitle", theme.bold("get_goal")), 0, 0);
@@ -55,6 +63,9 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: ToolRuntime): void
 
   pi.registerTool({
     name: "create_goal",
+    namespace: GOAL_NAMESPACE,
+    outputSchema: CREATE_GOAL_OUTPUT,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     label: "Create Goal",
     description: "Create a persistent Pi goal only when explicitly requested by user/system/developer instructions. Fails if a goal already exists.",
     promptSnippet: "Create a new persistent goal when explicitly requested.",
@@ -76,7 +87,7 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: ToolRuntime): void
       runtime.setGoal(goal);
       runtime.afterGoalChanged(ctx, "Goal created.");
       const summary = goalToSummary(goal);
-      return { content: [{ type: "text", text: JSON.stringify({ goal: summary }, null, 2) }], details: { goal: summary } };
+      return goalResult(summary);
     },
     renderCall(args, theme) {
       return new Text(`${theme.fg("toolTitle", theme.bold("create_goal"))} ${theme.fg("accent", truncateOneLine(String((args as any).objective ?? "")))}`, 0, 0);
@@ -89,15 +100,19 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: ToolRuntime): void
 
   pi.registerTool({
     name: "update_goal",
+    namespace: GOAL_NAMESPACE,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     label: "Update Goal",
-    description: "Mark the current Pi goal complete or blocked. Only model-controlled terminal goal updates are accepted.",
+    description: "Mark the current Pi goal complete or blocked. Call directly as the only tool call in a separate final assistant turn, after inspecting verification results. Not callable from codemode or other tools.",
     promptSnippet: "Mark the persistent goal complete or blocked after strict verification.",
     promptGuidelines: [
+      "Call update_goal directly as the only tool call in a separate final assistant turn, never from codemode or another tool.",
       "Use update_goal with status complete only after explicit requirement-by-requirement verification proves the full goal is satisfied.",
       "Use update_goal with status blocked only after the same blocker repeats for at least three consecutive goal turns.",
       "Never use update_goal for pause, resume, budget_limited, usage_limited, or edits; those are user/system-controlled.",
     ],
     parameters: UpdateGoalParams,
+    exposure: "model-only",
     executionMode: "sequential",
     async execute(toolCallId, params, _signal, _onUpdate, ctx) {
       if (params.status !== "complete" && params.status !== "blocked") throw new Error("update_goal only accepts status complete or blocked.");
@@ -142,6 +157,8 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: ToolRuntime): void
 
 export function assertStandaloneUpdateGoalCall(branchEntries: BranchEntry[], toolCallId: string) {
   const toolContext = findToolCallContext(branchEntries, toolCallId);
+  // A direct executor may have no transcript context. This guard checks sibling
+  // calls, not caller authority: Pi enforces nested-call denial via model-only exposure.
   if (!toolContext) return undefined;
   if (toolContext.siblingToolCalls.length > 1) {
     throw new Error("update_goal must be the only tool call in its assistant turn. Run verification commands first, inspect their results, then call update_goal in a separate final turn.");

package/src/types.ts

@@ -48,6 +48,7 @@ export interface GoalMutationMeta {
   };
   accounting?: {
     scannedAssistantEntries?: number;
+    scannedUsageEntries?: number;
     addedEntryCount?: number;
     cacheTokensIncluded?: boolean;
   };

package/src/ui.ts

@@ -3,11 +3,13 @@ import type { GoalState } from "./types.js";
 import { formatGoalFooter, formatWidget } from "./commands.js";
 
 export function updateGoalUi(ctx: ExtensionContext, goal: GoalState | null): void {
+  if (ctx.mode !== "tui") return;
   ctx.ui.setStatus("pi-goal", formatGoalFooter(goal));
   ctx.ui.setWidget("pi-goal", formatWidget(goal), { placement: "belowEditor" });
 }
 
 export function clearGoalUi(ctx: ExtensionContext): void {
+  if (ctx.mode !== "tui") return;
   ctx.ui.setStatus("pi-goal", undefined);
   ctx.ui.setWidget("pi-goal", undefined);
 }