stack/docs/scratchpads/1150-pi-goal-extension.md

#1150 — Pi persistent goal extension

• Task ID: ISSUE-1150 (no docs/TASKS.md row; that file is orchestrator-only)
• Issue: #1150 — pi: add persistent /goal controller extension to Mosaic framework
• Branch: feat/1150-pi-goal-extension
• Mode: Delivery
• Status: in progress

Objective

Build and locally validate a Mosaic-owned Pi /goal extension. Source must ship from packages/mosaic/framework/runtime/pi/, framework sync must deploy it under ~/.config/mosaic/runtime/pi/, and no extension/configuration asset may be written into ~/.pi. Pi's native session manager remains the owner of session entries.

Scope and acceptance source

• Canonical requirements: docs/PRD.md, section Pi Persistent Goal Loop (#1150).
• User intent: continuous goal orientation and status checking after each Pi turn and compaction, tested locally before framework delivery.
• Documentation target: canonical in-repo user/developer/runtime docs; no external publication.

Assumptions

• ASSUMPTION: Initial semantic verification uses two consecutive structured, evidence-bearing reports from the working agent rather than a second model request after every turn. This keeps the loop testable and avoids doubling model cost while making the limitation explicit.
• ASSUMPTION: Default autonomous bounds are 40 turns and 6 repeated no-progress reports, with only bounded numeric environment overrides.
• ASSUMPTION: A local smoke copy to ~/.config/mosaic/runtime/pi/goal-extension.ts is authorized by the user's explicit request. Full framework reseed into the live home is not required for the smoke test and would touch unrelated framework-owned files.

Budget

• Working estimate: 30K implementation/review tokens.
• Hard user cap: none stated.
• Cost control: deterministic fake-Pi tests; no nested evaluator calls; only bounded arithmetic/load smoke workflows against the installed runtime.

Plan

1. Update PRD and create tracking/scratchpad artifacts.
2. Read launcher, installer ownership, Pi extension, and documentation surfaces.
3. TDD: add fake-Pi behavior tests for commands, state restoration, turn checks, compaction, limits, verification, and continuation deduplication.
4. Implement runtime/pi/goal-extension.ts and deterministic launcher discovery.
5. Add framework-sync/deployment acceptance coverage.
6. Update user, developer, runtime, framework README, and sitemap documentation.
7. Run focused tests, local Mosaic-path smoke test, then baseline repository gates.
8. Run independent review, remediate, commit, push/PR/CI/merge/issue closure per delivery gates.

TDD decision

Applied. The continuation state machine and lifecycle scheduling are control-path logic where a race or false terminal state can cause unbounded work or premature completion.

Progress checkpoints

• Issue #1150 created through Mosaic wrapper.
• Isolated worktree created from origin/main.
• PRD requirements and acceptance criteria added.
• Task scratchpad created.
• RED controller and security-regression tests written and observed failing before implementation.
• Goal controller, launcher discovery, framework deployment coverage, and bounded state machine implemented.
• User, admin, developer, runtime, adapter, README, and sitemap documentation updated.
• Final source copied additively to ~/.config/mosaic/runtime/pi/goal-extension.ts; source and deployed SHA-256 are identical.
• Live Pi RPC smoke from the exact Mosaic path reached achieved with two verification passes and no extension errors.
• Baseline and situational checks completed, except the explicitly documented unavailable PostgreSQL-only root integration case.
• Independent code and OWASP/security reviews completed; all findings remediated and re-reviewed.
• Commit, push, PR, terminal-green CI, squash merge, and issue closure complete.

Tests and evidence

Situational

• pnpm --filter @mosaicstack/mosaic exec vitest run src/runtime/pi-goal-extension.spec.ts
  • final: 25 passed.
  • Covers commands, per-turn checks, context injection, two-pass verification, mixed-report rejection, bounded limits, compaction, branch restore, stale timers, credential redaction, typed-field false-positive protection, and append-only legacy-state fail-closed behavior.
• Final focused launcher/controller/file-adapter run: 3 files / 67 tests passed.
• Final V8 coverage for framework/runtime/pi/goal-extension.ts:
  • 99.17% statements/lines, 93.78% branches, 100% functions.
• Installer migration fixture: 24 passed and byte-compared the deployed framework asset.
• Standalone extension TypeScript check against installed Pi 0.84.1 types passed: pnpm --filter @mosaicstack/mosaic exec tsc --noEmit --pretty false --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck framework/runtime/pi/goal-extension.ts.
• Live deployment/load evidence:
  • source/deployed SHA-256: 1f0a3806e0948ad5f49684273a7e535e9880c148f7fd16d13ee487fcd601f637.
  • get_commands identified /goal as an extension command sourced from ~/.config/mosaic/runtime/pi/goal-extension.ts; /goal help succeeded; zero extension errors.
  • live arithmetic goal ended achieved, verification 2/2, with 3 goal reports / 3 agent starts and zero extension errors.
  • no goal extension exists under ~/.pi extension paths.

Baseline

• pnpm build: passed before the final framework-only redaction remediation; the extension is not a package build input and its final source passed the standalone Pi type check.
• pnpm typecheck: 45/45 tasks passed.
• pnpm lint: 25/25 tasks passed.
• pnpm format:check: passed.
• Final Mosaic package components:
  • Vitest: 82 files / 1,539 tests passed.
  • full test:framework-shell harness passed.
  • the discovered pre-existing tmux loader-marker race was reproduced with constructor PID evidence, fixed with a pane readiness/FIFO barrier, passed 3 consecutive focused runs, and passed in the full shell harness.
  • one combined rerun encountered the separate existing real-lease probe TOCTOU in install-ordering-guard.spec.ts; an earlier final Vitest run was fully green and the changed focused suites remained green.
• Gateway safe baseline excluding the prohibited PostgreSQL-only fixture: 55 files / 600 tests passed (6 files / 12 tests skipped by their existing environment gates).
• Root pnpm test reached 43 successful workspace tasks and all changed-package Vitest tests, but the unchanged apps/gateway/src/__tests__/cross-user-isolation.test.ts afterAll hook retried a PostgreSQL connection and failed authentication (28P01). This checkout explicitly forbids local PostgreSQL startup/access; the failure is unrelated to #1150 and cannot be remediated by starting the database. The gateway suite excluding that PostgreSQL-only file and required CI are used as the safe verification paths.

Independent review

• Codex code review: approved, 0 findings across 15 files.
• Initial Codex security review: one medium CWE-532/A09 finding for raw report persistence.
• Remediation added central credential-pattern redaction, prompt/docs guidance, canary tests, typed field false-positive guards, and sticky fail-closed restore for credential-bearing append-only history.
• Codex security re-review: risk none, 0 findings, confidence 0.87.
• Focused remediation review findings were fixed; final focused re-review verdict: APPROVE.
• Focused independent review of the tmux readiness barrier: APPROVE, no actionable findings.

Risks and blockers

• Live ~/.config/mosaic is shared by active Pi/fleet processes. Local deployment remained a single additive framework file and did not reload or restart unrelated sessions.
• Completion verification is semantic, not mathematical: the active agent supplies structured evidence twice. Operators must still inspect consequential outcomes.
• Credential redaction is pattern-based defense-in-depth, not a secret store. It covers controller-owned state/status/tool details, not Pi's separate model-message/tool-call history. Goals and reports must never contain real secrets or raw sensitive output. Because Pi session entries are append-only, a detected credential-bearing legacy branch fails closed and the affected session must be removed.
• Current installed Pi is newer than the repository's historical gateway Pi dependency. The extension was checked and smoke-tested against installed Pi 0.84.1 using stable documented APIs.
• Local root testing cannot safely execute the unchanged PostgreSQL-only integration fixture under the checkout's explicit database safety constraints. Terminal-green PR CI remains mandatory before merge.
• The unchanged real-lease default-probe test can observe different broker availability across its two sequential probes; one combined package rerun hit that existing TOCTOU. The same final Vitest suite passed in a separate run, and CI remains the merge authority.