Core Consolidation
Shared Core Refactor
A broad deduplication pass across the driver, front-end, attach, harness, worktree, CLI, and TUI layers.
4 milestones 18 tasks 42 agents
233k peak context
124k median execute
5h 38m total 10m 42s per task
23m 31s plan 2h 38m execute 37m 36s review
317 edits 795 commands
claude harness
122.3M tokens in 840.5k tokens out
$123.71 nominal cost
This run took a maintenance plan whose risk was not one feature, but repetition spread across Gantry's own core. The digest cut that problem by subsystem: first the driver and ledger primitives, then the front-end event folds, then the attach codec and harness plugins, and finally the worktree, CLI, and TUI hygiene tail.
That order matters because most sprints were behavior-preserving extractions. Each worker received a narrow duplicate pattern with explicit compatibility checks, so the run could replace copied logic with named shared homes while keeping the old public surfaces observable by tests, snapshots, or protocol goldens.
How this walkthrough is structured
Feature
What did the run build and ship?
The current tree still carries the shared model layer the run introduced, even though later reorganizations moved much of the driver work out of its original module paths.
Build
How did Gantry structure the work?
The work was cut as a stack of small refactors, with the only stress appearing where a completed slice changed the next plan rather than where the gate found broken behavior.
Milestone 1
Unified Driver Core
5 tasks 0 agents 1h 19m wall time 179k peak context $40.41 nominal cost
The original driver modules named in the facts have since been replaced by the newer run module layout, so the exact file-level contribution is no longer cleanly separable. The ideas are still present: ledger status is typed, sprint finishing is centralized, and agent calls and stage budgets travel through named structs. The current `src/engine/run` code shows this milestone as a foundation folded into later architecture rather than as a preserved old directory.
This milestone isolated the driver core before the wider front-end and protocol work began. Its sprints each named one repeated control-flow decision or event-emission ritual, which made the work suitable for clean-context agents: find the copies, extract one primitive, and keep every observable card and ledger row stable. The final parameter bundle triggered a replan for the remaining run, evidence that this first cut changed enough shared plumbing for the planner to refresh what came next.
Centralize Done Predicate
0 agents 4m 32s wall time 69k peak context 13.7k tokens out $2.04 nominal cost
The exact helper from this sprint is not visible under the old map-driver path today, because map execution has been reorganized into the run pattern modules. The standing behavior remains the same public contract: map work re-derives completion from artifacts and their skip checks instead of trusting a mutable flag. Current map and pattern code still treats disk state as the resume source of truth.
This sprint was asked to give the map driver's resume invariant one canonical predicate. The boundary was intentionally small: decide whether an artifact plus skip-test means done, then replace the copied counts that used the same rule. Its gate stayed green, which fits a cut whose risk was semantic drift between copied predicates rather than broad behavior.
Stage Card Helpers
0 agents 15m 11s wall time 139k peak context 50.7k tokens out $7.32 nominal cost
The old helper sites have moved, but the current run code still names the event-card construction boundary through helpers such as stage-start and stage-finished card paths. Card defaults are no longer an incidental struct literal at every call site. The surviving code reads as event intent, with tests elsewhere preserving the rendered stream.
This was the highest-surface refactor in the first milestone, because stage cards were hand-built across the flat driver, map driver, and agent runner. The brief kept it finite by preserving every emitted field and focusing only on shared constructors for starts, finishes, and note pairs. It passed without a repair loop, so the extraction did not expose a mismatch in the event stream.
Unified Status Primitives
0 agents 17m 19s wall time 156k peak context 55.6k tokens out $9.13 nominal cost
`LedgerStatus` now owns the on-disk status tokens and the conversion from sprint status, while `finish_sprint` records the ledger row and emits the terminal event together. That is still visible in `src/engine/ledger.rs` and `src/engine/run/finish.rs`. Later status variants have been added, but the central mapping remains the place callers go through.
This sprint joined two related concerns: the terminal event emitted for a sprint and the row recorded in the ledger. That was a good unit because the brief could state the exact mapping between semantic sprint state and on-disk status while leaving callers as simple users of the primitive. The gate stayed green across the migrated terminal paths.
Consolidate Agent Outcomes
0 agents 14m 49s wall time 125k peak context 52.3k tokens out $5.63 nominal cost
Outcome classification still sits behind shared methods and helper types rather than copied match arms in each driver path. The current run modules use those abstractions when deciding how worker results affect retry, stop, or map fault handling. The contribution is partly submerged by later run-module growth, but the classification boundary survived.
This sprint took the agent outcome type as the owner of repeated failure reasoning. The brief narrowed the work to accessors and classifiers, with the stage-dependent policy left at the caller where it belonged. That boundary let the worker reduce repeated matches without pretending all agent failures mean the same thing.
Bundle Stage Parameters
0 agents 18m 26s wall time 179k peak context 71.5k tokens out $11.75 nominal cost
The current run code contains `StageBudget`, `AgentCall`, and `SprintBaseline`, which are exactly the kind of bundles the brief called for. They make effort selection, agent dispatch, and sprint baselines explicit values instead of loose argument sequences. The clippy suppressions that motivated the sprint are no longer the way this path is expressed.
This final driver-core sprint replaced long positional argument lists with named bundles. It came after the earlier extractions because those had already shortened the surrounding functions, making the signature change easier to review. The run facts record a successful replan after this unit, so the next milestone proceeded from an updated view of the remaining work.
Milestone 2
Frontend Event Consolidation
5 tasks 0 agents 57m 42s wall time 133k peak context $26.94 nominal cost
The front-end consolidation is highly visible in today's tree. Window-title progress lives in `src/window_title.rs`, shared formatting lives in `src/format.rs`, and both headless and TUI paths call into those shared surfaces. The run left a front-end layer where display decisions have named homes instead of parallel folds.
This milestone moved from driver control flow to front-end derived state. The planner protected the refactor with a characterization test first, then extracted shared models and formatters before doing heavier dispatch cleanup. Each sprint stayed green, which is important here because most of the work claimed byte-preserving output across both terminal front-ends.
Title Characterization Test
0 agents 5m 18s wall time 90k peak context 15.2k tokens out $2.61 nominal cost
The test layer still carries title-fold coverage around milestone and flat progress, terminal status, and playhead clearing. Its feature value is indirect: it guards the shared `ProgressModel` by first documenting the behavior it replaced. Even where later title logic expanded, this sprint's safety-net role remains visible in the surrounding tests.
This sprint deliberately changed no production code. It gave one worker the job of proving that the headless and TUI title folds already agreed before any extraction began. That made the next sprint a refactor against pinned behavior instead of a rewrite based on confidence.
Shared Progress Model
0 agents 8m 39s wall time 124k peak context 31.8k tokens out $4.72 nominal cost
`ProgressModel` is now a standing shared type in `src/window_title.rs`. Both front-ends feed it rather than owning separate title-progress machines, and the model also adopts newer run-view progress when pattern-shaped runs provide it. The title path has continued to evolve, but this shared fold remains the central owner.
This sprint was the central extraction of the front-end milestone. Because the previous worker had pinned twin behavior, the fresh agent could focus on moving state into one fold and routing both front-ends through it. The boundary was the title projection only, not the whole render tree.
Shared Duration Formatters
0 agents 15m 33s wall time 121k peak context 51.9k tokens out $6.57 nominal cost
`src/format.rs` now owns shared duration, reset-wait, countdown, and related rendering helpers used by headless and TUI code. The TUI metrics formatter and headless log paths no longer carry their own independent duration routines. The standing module is broader now, but the consolidation target from this sprint is still there.
This sprint handled duplicate time rendering after the title state had a shared home. The brief made the risky part explicit: one formatting disagreement was allowed to change if the reconciled function was tested and narrowly contained. Its green boundary meant the worker could remove local copies without broad front-end churn.
Display Fallback Consolidation
0 agents 8m 39s wall time 101k peak context 26.6k tokens out $4.39 nominal cost
`SprintMeta` now exposes `display_title` and `display_title_or_id`, with comments documenting why those fallbacks differ. Current renderer, state, and headless code call through those methods instead of reimplementing title selection. The milestone-run predicate work was later absorbed into broader projection logic, but the display-title API remains.
This sprint was a small domain refactor with a sharp behavior boundary. It had to preserve two different fallback ladders rather than flatten them into one cleaner-looking rule. That made it a contained task for a fresh worker: put both accessors on the owner type and migrate each caller to the matching behavior.
Retry Note Consolidation
0 agents 10m 18s wall time 133k peak context 42.3k tokens out $4.83 nominal cost
The shared retry-note decision is now in `src/format.rs`, while headless and TUI wrappers keep their different presentation text. The current event folds are organized around helper methods rather than large inline bodies. The sprint also left the milestone-tag wart documented away from a bare literal at the call site.
This closing front-end sprint removed the last large inlined event-fold branches. Its useful boundary was not "rewrite rendering," but share the retry-note core and turn each fold arm into dispatch to named helpers. It stayed green, so the output-preservation promise held while the code became easier to scan.
Milestone 3
Codec and Harness Dedup
4 tasks 0 agents 47m 58s wall time 159k peak context $24.24 nominal cost
The attach codec and harness shared helpers are among the clearest surviving parts of the run. `src/engine/attach.rs` uses serde-aware mirrors while keeping protocol framing explicit, and `src/engine/harness` has common config, delivery, and text-classification utilities. The feature is not a new user command; it is a smaller compatibility surface for live attach and multi-harness execution.
This milestone split a protocol-risk refactor from harness-plugin cleanup. It first pinned the attach wire bytes, then swapped codec internals under those goldens, and only afterward moved to harness config, auth, MCP, and classifier duplication. The first attach sprint produced an unfinished replan marker, but the remaining unit ran from the refreshed plan and the milestone still closed green.
Attach Wire Golden Frames
0 agents 5m 13s wall time 81k peak context 17.6k tokens out $2.43 nominal cost
The attach tests still enumerate every event shape and command shape with fixed timestamp data and explicit frame expectations. That suite is the compatibility contract for a live attacher, not just a regression test for one serializer. Later protocol additions have grown the fixture, but the golden-frame style remains.
This sprint built tests before touching the codec. The task was well-contained because the attach module already knew every event and command variant, and the worker only had to harden the expected bytes. The recorded unfinished replan marker after this unit suggests the goldens revealed planning detail the remaining codec work had to respect.
Derive Wire Codec
0 agents 16m 56s wall time 159k peak context 71.1k tokens out $6.49 nominal cost
`src/engine/attach.rs` now uses serde derives and mirror types for awkward wire shapes such as prompt payloads and metrics. The framing remains explicit, but event and command bodies are no longer hand-mapped variant by variant. The protocol constant stayed stable, which is the practical signal that the wire contract did not change.
This sprint performed the actual codec replacement under the protection of the goldens. The brief's key constraint was that derived serialization still had to pass through value normalization to keep the old key ordering. That gave the worker an objective boundary: delete manual tables only when the wire output stayed byte-compatible.
Config and Auth Consolidation
0 agents 6m 50s wall time 131k peak context 20.9k tokens out $5.23 nominal cost
The shared harness module now owns the common config builder and readiness helpers, while individual plugin modules supply their harness-specific inputs. Claude's legacy alias path still wraps that shared builder instead of being flattened away. The result is visible as thinner plugin setup code with behavior pinned by the existing per-plugin tests.
This sprint moved from protocol code to harness plugin scaffolding. The task boundary was the common environment config and readiness probe shared by the harnesses, with each plugin retaining only its defaults, keys, and credential path. It stayed green, indicating the alias and auth precedence tests were strong enough to guard the extraction.
MCP and Text Consolidation
0 agents 11m 6s wall time 103k peak context 34.6k tokens out $5.52 nominal cost
`McpDelivery::from_registration` centralizes the empty-registration decision for file-based harness MCP setup. The shared transient module also owns `first_line` and the union `looks_oversized`, so plugins no longer carry separate keyword lists. Current Claude and OpenCode parsing both consult that shared ceiling classifier before transient handling.
This sprint completed the harness deduplication with MCP delivery and text classification. Unlike most of the run, it included a stated behavior improvement: oversized detection should use the union of existing phrases. The boundary was still narrow because it lived inside plugin helpers and their classifier tests.
Milestone 4
Worktree Contract Hygiene
4 tasks 0 agents 54m 58s wall time 233k peak context $31.05 nominal cost
Today's tree shows this milestone across distinct surfaces: strict worktree reads in `src/engine/worktree.rs`, CLI exit helpers in `src/main.rs`, shared TUI scroll state in `src/tui/state.rs`, and metric segment construction in `src/tui/render.rs`. Some later changes expanded those areas, but the named contracts and helper types remain active. The milestone left Gantry's internal UI and git boundaries easier to audit.
The final milestone gathered cleanup tasks that were safe only after the core and front-end refactors had landed. It opened with the one correctness-adjacent contract change, then handled CLI, scroll, and metrics deduplication as confined mechanical work. The whole milestone stayed green, so the hygiene tail did not destabilize the earlier shared foundations.
Git Read Contracts
0 agents 12m 22s wall time 144k peak context 41.9k tokens out $6.85 nominal cost
`commits_beyond_main`, `main_porcelain`, and `main_newly_dirty` now return errors for decision-critical failures instead of collapsing them into empty output. The worktree module also documents which reads stay lenient and why. Callers that protect merge and confinement paths can now stop or take the conservative branch when git itself cannot answer.
This sprint was the run's correctness-focused exception. The brief asked the worker to separate git reads that may be lenient from reads that drive merge, confinement, or no-op decisions. Its boundary was exact: success behavior should not move, but a git failure must no longer be read as the optimistic answer.
CLI Parsing Hygiene
0 agents 7m 42s wall time 90k peak context 22.4k tokens out $3.49 nominal cost
`src/main.rs` now has shared `die` and `or_die` helpers for the repeated error-exit idiom, plus consolidated flag parsing around the startup flow. Snapshot and harness dispatch are expressed through common machinery rather than scattered scans. Later CLI work has added more structure, but the cleanup's helper boundary is still present.
This was a low-risk entry-module cleanup with strict compatibility requirements. The worker's job was to parse repeated booleans once, centralize error exits, table-drive snapshot dispatch, and reuse harness selection work. Because all of that sat in one module, the sprint could be reviewed as structure without changing command semantics.
Scroll Consolidation
0 agents 21m 49s wall time 233k peak context 80.1k tokens out $14.45 nominal cost
`Scroll` now owns offset, follow mode, and draw-time maximums, with named operations for top, bottom, up, down, and clamp. `ChatState` groups the chat pane's fields around its own scroll value instead of leaving them scattered on the application state. Current mouse and key handlers drive those types rather than relying on a bottom sentinel.
This sprint took a repeated UI state machine and made it explicit. The scope was wide inside the TUI but narrow by subsystem: feed, sidebar, chat, and detail views all needed the same offset, follow-tail, and clamp behavior. It stayed green under snapshot-heavy expectations, which is the right proof for a visual behavior-preserving refactor.
Metrics & Cleanup
0 agents 6m 37s wall time 80k peak context 17.5k tokens out $2.68 nominal cost
`src/tui/render.rs` now has one `metrics_segments` builder used by stage-log and run-total formatting. Turn pluralization and token segment assembly live in that helper instead of being repeated through separate walkers. The dead throwaway constructions named in the brief are gone from the current TUI module.
The final sprint was intentionally small: unify repeated TUI metrics segment builders and remove dead discarded constructions. Its value was in closing the plan without reopening broader rendering choices. The green result indicates the worker kept the metrics lines stable while deleting the duplicated walk.