feat(pi): add persistent Mosaic goal controller

docs/PRD.md

@@ -102,6 +102,128 @@ Context compaction, session replacement, and same-PID runtime reloads can leave
 
 ---
 
+## Pi Persistent Goal Loop (#1150)
+
+### Problem and objective
+
+A Pi agent can stop after a plausible-looking answer even when the operator's broader objective is
+not complete, and ordinary compaction can weaken or omit the original objective. Mosaic needs an
+optional, operator-controlled goal loop that keeps a Pi session oriented, checks progress at native
+lifecycle boundaries, and resumes work until completion is verified or a bounded safety state is
+reached.
+
+The objective is a Mosaic-owned Pi extension deployed from the framework into
+`~/.config/mosaic/runtime/pi/`. It must not install into or depend on `~/.pi/agent/extensions/`.
+
+### Scope
+
+#### In scope
+
+1. `PGL-REQ-01`: The framework SHALL ship a dedicated Pi goal extension under
+   `packages/mosaic/framework/runtime/pi/`, seed it under `$MOSAIC_HOME/runtime/pi/`, and make
+   `mosaic pi` load it alongside the core Mosaic extension when present.
+2. `PGL-REQ-02`: `/goal` SHALL support setting a goal plus status, pause, resume, cancel, and help
+   operations without silently replacing an active goal.
+3. `PGL-REQ-03`: Active branch-specific goal state SHALL be persisted in Pi custom session entries,
+   restored on session start and tree navigation, and never rely on a compaction summary as its
+   source of truth.
+4. `PGL-REQ-04`: A hidden goal contract SHALL be injected through Pi's `context` event before every
+   model request so it remains effective across tool turns, retries, and post-compaction requests.
+5. `PGL-REQ-05`: The harness SHALL inspect every `turn_end` and successful `session_compact` event.
+   A structured terminating goal-report tool SHALL capture `continue`, evidence-bearing `achieved`,
+   or `blocked` status without requiring a redundant model turn.
+6. `PGL-REQ-06`: An achievement claim SHALL remain provisional until a second consecutive
+   evidence-bearing verification report. Any continuation report or successful compaction during
+   verification SHALL reset the verification sequence.
+7. `PGL-REQ-07`: Continuation SHALL be initiated at safe lifecycle boundaries, primarily
+   `agent_settled`; manual compaction and restored active sessions may schedule a deferred idle
+   continuation without re-entering compaction handlers.
+8. `PGL-REQ-08`: The loop SHALL have operator cancellation plus bounded turn and repeated-no-progress
+   limits. Exhausted or blocked goals pause rather than continuing indefinitely.
+9. `PGL-REQ-09`: Framework installation and update SHALL preserve normal manifest ownership: the
+   goal extension is framework-owned under `runtime/**`, while no goal extension or configuration
+   asset is created or modified under the operator's main Pi configuration. Pi remains the owner of
+   its native session files used by `appendEntry()`.
+
+#### Out of scope
+
+1. A mathematical guarantee that an arbitrary natural-language goal is semantically complete.
+2. Automatically executing user-supplied shell predicates or accepting executable validation code in
+   `/goal` arguments.
+3. Restarting Pi after process, host, or supervisor failure; the existing Mosaic fleet/runtime
+   supervisor owns process durability.
+4. Gateway, database, web UI, Discord, or cross-harness goal orchestration in this slice.
+
+### User and stakeholder requirements
+
+- An operator can start a goal from Pi and see its current phase, evidence, limits, and latest report.
+- The agent remains oriented after each turn and compaction until verified, paused, blocked,
+  exhausted, or cancelled.
+- Local testing uses a file under `~/.config/mosaic/runtime/pi/`; the feature never writes an
+  extension asset to `~/.pi/agent/extensions/`.
+- Framework updates deploy the same reviewed extension source through Mosaic's existing manifest
+  sync path.
+
+### Non-functional requirements
+
+1. **Safety:** bounded continuation, explicit cancellation, no arbitrary command execution, and no
+   completion without non-empty reported evidence.
+2. **Reliability:** serialized continuation scheduling, branch-aware restoration, compaction-safe
+   context injection, and stale-timer cancellation on session shutdown.
+3. **Performance:** no extra nested judge-model request on every turn; structured reporting uses the
+   active agent's final terminating tool call.
+4. **Observability:** Pi status/notifications expose phase and bounded counters without recording
+   credentials or hidden model reasoning.
+5. **Maintainability:** the state machine is deterministic and behavior-tested independently from Pi
+   provider/network access.
+
+### Acceptance criteria
+
+1. `AC-PGL-01`: A framework-sync fixture installs the extension at
+   `$MOSAIC_HOME/runtime/pi/goal-extension.ts`, and launcher tests prove both Mosaic Pi extensions are
+   emitted in deterministic order while absent optional files remain backward-compatible.
+2. `AC-PGL-02`: Command tests prove set/status/pause/resume/cancel behavior, active-goal replacement
+   refusal, and bounded input handling.
+3. `AC-PGL-03`: Lifecycle tests prove every turn is recorded, active context is injected on every
+   request, two evidence-bearing achievement reports are required, and `agent_settled` continues an
+   unmet goal without duplicate scheduling.
+4. `AC-PGL-04`: Compaction and restoration tests prove goal state survives, verification is reset and
+   rechecked after compaction, manual compaction continuation is deferred until idle, and tree/session
+   branch state is reconstructed correctly.
+5. `AC-PGL-05`: Limit tests prove max-turn and repeated-no-progress exhaustion stop autonomous
+   continuation, while pause/cancel/blocked states do not restart.
+6. `AC-PGL-06`: Focused tests, package typecheck/lint/test, repository quality gates, a local Pi load
+   smoke test from `~/.config/mosaic/runtime/pi/`, independent review, and terminal-green CI pass before
+   issue #1150 closes.
+
+### Constraints, risks, and assumptions
+
+- Dependency: Pi's extension API must continue to provide `registerCommand`, `registerTool`,
+  `context`, `turn_end`, `agent_settled`, `session_compact`, session custom entries, and terminating
+  tool results.
+- Risk: the working agent can overstate completion. Mitigation: structured evidence, a mandatory
+  second verification pass, explicit semantic limitations, and operator-visible reports.
+- Risk: an impossible goal can consume unbounded resources. Mitigation: hard turn/no-progress bounds
+  and paused terminal states.
+- Risk: automatic continuation can race compaction or session replacement. Mitigation: drive from
+  `agent_settled`, defer idle restarts, generation-check timers, and clear timers on shutdown.
+- `ASSUMPTION:` Two consecutive evidence-bearing reports are the initial local verification policy;
+  rationale: it provides a real recheck without doubling every turn's model cost. Future policy may
+  add independent or deterministic validators.
+- `ASSUMPTION:` Default limits are 40 turns and 6 repeated no-progress reports, configurable only by
+  bounded Mosaic environment settings; rationale: useful persistence with a finite autonomous budget.
+- `ASSUMPTION:` Documentation remains canonical in-repo for this slice; no external docs publication
+  is requested.
+
+### Testing and delivery intent
+
+Use TDD for the deterministic controller and lifecycle invariants. Test with fake Pi lifecycle
+objects first, then run a local load/smoke test from the deployed Mosaic path. Deliver source, tests,
+launcher wiring, framework/runtime documentation, user/developer guides, and sitemap updates in one
+reviewed squash PR to `main` with terminal-green CI.
+
+---
+
 ## Fleet Declarative Configuration Management Workstream (FCM, #758)
 
 ### Problem and objective