1. modularize /goal logic

[kevinjosethomas]

• goal state and accounting now have a dedicated owner, with separate command parsing and persistence modules.
• first refactor in the cleanup stack; design and rollout are tracked in eng-5938.
• preserves goal behavior and persistence; all 68 focused tests and npm run check pass.

---

Note

Medium Risk
Large refactor of goal lifecycle wiring in AgentSession; behavior depends on preserved ordering for accounting, completion cleanup, and continuation rollback clocks.

Overview
Pulls goal state, accounting, persistence, and /goal parsing out of AgentSession into a dedicated goals/ feature: GoalController owns transitions, token/time accounting, continuation checkpoints, and assistant usage dedup; persistence.ts wraps branch load/save and CLI seed eligibility; commands.ts holds slash-command parsing.

AgentSession now wires a GoalController with session persistence and goal_update emissions, delegating start/pause/resume/clear/complete/fail, budget limiting, continuation increment/rollback, and branch reload. Host completion passes a callback so stale budget-limit contexts are cleared before completion is persisted. Continuation races restore state via checkpoint/restore (with optional clock preservation after deferred RLM work).

Adds src/README.md documenting the extraction pattern and ordering invariants. Adds test/goals/controller.test.ts and updates continuation quiescence tests to use a controller-backed harness. core/goals.ts types and thread_goal_state format are unchanged.

^{Reviewed by Cursor Bugbot for commit 120516e. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Extract /goal logic from AgentSession into GoalController and supporting modules

• Moves goal state ownership, accounting, persistence, and command parsing out of AgentSession into a new goals/ package containing controller.ts, persistence.ts, and commands.ts.
• GoalController owns all goal lifecycle operations (start, pause, resume, fail, complete, rollback, assistant-usage accounting) using an injected persistence adapter and clock for deterministic time accounting.
• AgentSession constructs the controller and delegates to it; the public goalState getter now returns the controller's clock-accounted snapshot.
• Adds README.md guidance for src/ organization and goal ownership boundaries.
• Behavioral Change: goal seeding now accepts only model, thinking-level, and service-tier bootstrap entries via createGoalPersistence; out-of-tree consumers relying on broader seed eligibility may need updating.

^{Macroscope summarized 120516e.}

[github-actions]

Prime Agent performance — completed

PR 120516ed compared with main 1eee2938.

Overall: 0 regressed · 0 improved · 17 no clear change.

Metric	Main	This PR	Change
Cold startup	2,978.7 ms	3,096.5 ms	≈ +117.8 ms (+3.96%)
Warm startup	1,721.0 ms	1,731.8 ms	≈ +10.8 ms (+0.63%)
Installation	29.38 s	28.27 s	≈ -1.11 s (-3.77%)
Compressed release artifacts	11.12 MB	11.12 MB	≈ +0.00074 MB (+0.01%)
Installed footprint	597.49 MB	597.50 MB	≈ +0.0047 MB (+0.00%)
Idle memory, summed RSS	1,084.26 MB	1,142.94 MB	≈ +58.69 MB (+5.41%)

Python runtime

Metric	Main	This PR	Change
Python kernel startup	124.8 ms	127.1 ms	≈ +2.2 ms (+1.79%)
Python cell round trip	0.566 ms	0.560 ms	≈ -0.007 ms (-1.16%)
Empty bash command	11.6 ms	11.6 ms	≈ +0.0061 ms (+0.05%)
Bash git status	18.2 ms	17.8 ms	≈ -0.4 ms (-2.09%)
Bash 32 KiB output	12.5 ms	12.1 ms	≈ -0.4 ms (-3.32%)
35 cells / 9 shell calls	173.8 ms	168.5 ms	≈ -5.3 ms (-3.06%)
Python interrupt to done	1.582 ms	1.621 ms	≈ +0.039 ms (+2.46%)
Python state snapshot	25.9 ms	26.2 ms	≈ +0.2 ms (+0.88%)
Python state restore	349.7 ms	352.1 ms	≈ +2.3 ms (+0.67%)
Python idle RSS	35.15 MB	34.88 MB	≈ -0.27 MB (-0.76%)
Python RSS after pandas workload	98.70 MB	97.67 MB	≈ -1.03 MB (-1.04%)

Sandbox cost: ~$0.0907 — no inference calls.
Run, logs, and downloadable raw results

Methodology and samples

Main resolved at 2026-09-10T23:42:48.640022+00:00. Harness 1eee2938.
Linux x64, 4 vCPU, 8 GB RAM, 20 GB disk; region us.
Image: node:24-bookworm@sha256:be23f54a88d34e8824c741b19b91064094f92c1c97b194144bfc8b50d67258e2.
Stock tools, skills, daemon, and Python bootstrap enabled; fresh homes and a fixed Git fixture.
Onboarding is dismissed; the editor starts without a selected model or submitted prompt.
Medians shown. Arrows require a 20% timing/memory change plus absolute floors and IQR.
These practical noise floors are not a statistical significance test.
Cold means stopped Prime processes; OS filesystem caches are not flushed.
No model requests or credentials. Installation excludes build/setup time.
Installer tarballs use loopback; npm/Python downloads use the network with fresh caches.
Artifact size counts release tarballs; footprint after first use includes registry packages.
MB is decimal. Summed RSS can double-count shared pages; PSS is recorded when available.
Provisioning, setup, and build durations are recorded separately in the raw results.
Kernel probes use the installed JSONL runtime, outside the TUI/TypeScript host.
Per trial: 50 Python cells, 5 calls per shell case, and one 35-cell mix (9 git status calls).
Cell/shell values are batch means; other runtime timings are single operations.
State fixture: a 10,000-row × 8-column integer DataFrame and a 10,000-integer list.
Restore runs in a fresh kernel, including pandas imports; kernel startup is excluded.
Kernel RSS covers the isolated Python process; loaded RSS follows the pandas workload.
Costs estimate full sandbox lifetimes at configured rates, including setup and build.
Budget target: $1; not a billing cap. Checks are informational.

Metric	Main successful/attempted	PR successful/attempted	Main spread	PR spread
Cold startup	10/10	10/10	IQR 75.9 ms	IQR 115.8 ms
Warm startup	10/10	10/10	IQR 96.1 ms	IQR 91.3 ms
Installation	3/3	3/3	range 4.41 s	range 0.20 s
Compressed release artifacts	1/1	1/1	—	—
Installed footprint	1/1	1/1	—	—
Idle memory, summed RSS	10/10	10/10	IQR 112.88 MB	IQR 79.47 MB
Python kernel startup	10/10	10/10	IQR 8.2 ms	IQR 9.7 ms
Python cell round trip	10/10	10/10	IQR 0.043 ms	IQR 0.047 ms
Empty bash command	10/10	10/10	IQR 0.6 ms	IQR 0.7 ms
Bash git status	10/10	10/10	IQR 1.0 ms	IQR 1.4 ms
Bash 32 KiB output	10/10	10/10	IQR 0.4 ms	IQR 0.6 ms
35 cells / 9 shell calls	10/10	10/10	IQR 13.1 ms	IQR 5.5 ms
Python interrupt to done	10/10	10/10	IQR 0.129 ms	IQR 0.099 ms
Python state snapshot	10/10	10/10	IQR 2.5 ms	IQR 1.3 ms
Python state restore	10/10	10/10	IQR 14.4 ms	IQR 15.0 ms
Python idle RSS	10/10	10/10	IQR 4.12 MB	IQR 2.91 MB
Python RSS after pandas workload	10/10	10/10	IQR 3.53 MB	IQR 2.80 MB