---
kind: record
status: active
---

# #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

- [x] Issue #1150 created through Mosaic wrapper.
- [x] Isolated worktree created from `origin/main`.
- [x] PRD requirements and acceptance criteria added.
- [x] Task scratchpad created.
- [x] RED controller and security-regression tests written and observed failing before implementation.
- [x] Goal controller, launcher discovery, framework deployment coverage, and bounded state machine
      implemented.
- [x] User, admin, developer, runtime, adapter, README, and sitemap documentation updated.
- [x] Final source copied additively to `~/.config/mosaic/runtime/pi/goal-extension.ts`; source and
      deployed SHA-256 are identical.
- [x] Live Pi RPC smoke from the exact Mosaic path reached `achieved` with two verification passes and
      no extension errors.
- [x] Baseline and situational checks completed, except the explicitly documented unavailable
      PostgreSQL-only root integration case.
- [x] 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.
