157 lines
8.9 KiB
Markdown
157 lines
8.9 KiB
Markdown
# #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.
|