#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

Update PRD and create tracking/scratchpad artifacts.
Read launcher, installer ownership, Pi extension, and documentation surfaces.
TDD: add fake-Pi behavior tests for commands, state restoration, turn checks, compaction, limits, verification, and continuation deduplication.
Implement runtime/pi/goal-extension.ts and deterministic launcher discovery.
Add framework-sync/deployment acceptance coverage.
Update user, developer, runtime, framework README, and sitemap documentation.
Run focused tests, local Mosaic-path smoke test, then baseline repository gates.
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.

8.9 KiB Raw Blame History