Simplification review, all 35 approved proposals, and the work queue drained

[brillout]

A clean-slate simplification review of the whole repo — and its implementation. Every proposal
the maintainer approved: 35 approved, 6 rejected, all 35 landed — then the six entries standing
in TODO_AGENTS.md, which is now empty, and then a review of the whole branch, whose findings are
fixed here too.

Net: +27,774 / −94,019 across ~2,260 files, and the product does the same thing.

The test applied throughout: can this be removed? Not "is this good code" — most of it was. The
question is whether the concept earns a place in a product whose stated goal is one sentence long.

What was removed

The stack's bottom two layers were ballast. the-framework and framework-dashboard imported
zero symbols from @gemstack/ai-sdk (30.8k LOC, 15+ providers, evals, computer-use, vector
stores, React bindings). Only ai-autopilot touched it — five symbols — and every file that did was
itself unreachable from the product. Both packages are gone (A1, A2); the used slice of
ai-autopilot was absorbed.

Two products were wired in parallel. --deploy cloudflare|dokploy, --serve*,
--sandbox docker and the Local/Docker/WebContainer/Fake runners described "idea to a running
app"; the root SPEC describes "idea, ticket, or queue entry → reviewed pull request" on existing
repos. The second product won (A4). With it went the Bootstrap spine, which had degenerated to
one function call (A3), and the domain-preset review loop (A5).

The CLI is one command with no arguments. 67 flags → four options and no verbs (D4): 27 were
the daemon's own process API serialized onto a command line, and are now a JSON spec on a temp file.
It runs in the foreground and only in the foreground (D4b), which deletes the liveness record,
the machine-global state file and the second-process problem.

One package, not four. The dashboard merged in (A7), which dissolved a 406-symbol export
surface with one consumer; turbo went with it (A8), then Vike for plain Vite (F1), Telefunc
for plain HTTP handlers (F3), and the vendored animate-ui (F4).

Concepts that were one thing written several ways. Four gate mechanisms → one (D6). Four
records of what happened → one (B3). Three claim mechanisms → two (E2). Three spending gates
→ one, on starting (E1) — nothing interrupts work already in flight. Four background sweeps on
four timers → one daemon tick (E4). Three retention rules → one: only remove what is on the
remote (E5). Two run paths that could drift → one (D2). Three prompt modes → two switches
(C1).

Three words for one thing → three concepts with three names (D5): the unit of work is an
agent, the CLI that drives it is a driver, and where it executes is its location. The
rename runs all the way through — every identifier, the module names, the on-disk layout
(agents/, agent.json), the branch prefix the-framework/agent-{id}, the spawn flag
--agent {path}, all 520 SPEC files, every doc comment, and every visible label in the dashboard,
the CLI and the daemon's log.

The work queue, drained

With the review's list finished, the six entries in TODO_AGENTS.md were worked front to back:

• Spike & plan can never fire while the AI queue has entries #1432 — Spike & plan was unreachable. The sweep stood down whenever the queue had work and
  the draining routine was switched off, so with a standing backlog every work-inventing routine
  was unreachable. That switch means "do not work the queue"; the rotation fills it. It now
  falls through. A drain-only click still stands down — it asked for the queue by name.
• readZip/ZipEntry leak onto the public API via the driver barrel #947 — readZip/ZipEntry left the published API surface, both steps at once: nothing has
  ever shipped to npm, so the barrel removal costs no consumer anything.
• Bug: cannot select Fable #1143 — the model picker lists only real models. Dropping the "Default" entry alone would have
  been worse than keeping it: the label fell back to the first model, so an unset preference would
  have started reading as Fable. That fallback went with it — and it turned out to be hiding a
  trigger with no accessible name at all.
• Empty settings dropdown #1172 — a settings row with nothing to pick renders nothing. The reported control did not
  survive the deletions above, so this makes the class impossible rather than hunting the instance.
• Agent escaped its run worktree: edits landed in the main checkout, its commit claims work it does not contain #1276 (fix 2 only, as scoped) — the system prompt now says where the workspace ends. Worktrees
  nest inside the repo, so the user's checkout is a path prefix of the agent's cwd and the same file
  exists twice; the reproduced failure had an agent editing the outer copy while committing the
  inner one, finishing done with a commit holding none of the work.
• Idea: also show daily % used #1367 — the usage panel says what was spent as quota time, and what share of the pro-rata
  allowance that is. It declines to read before any allowance has elapsed rather than dividing by
  zero.

The branch, reviewed

A pass over the whole diff. Six findings, each fixed on this branch:

• The RPC handler table inherited from Object. Its key is a path segment off an
  unauthenticated request, so POST /_rpc/constructor found Object and answered 200 with whatever
  it was handed, and __proto__ / toString / valueOf reached members that are not handlers.
  Null-prototype table; none of them is an RPC, so all of them are the 404 they are.
• B5 silently started publishing for anyone who had opted out. It replaced autoPushBranch /
  autoOpenPr / autoMerge with the handoff ordinal and read neither the stored preferences nor a
  committed the-framework.yml written in the old spelling. Ignoring those keys does not leave
  anyone where they were: absent means the default, and the default pushes the branch and opens a
  PR. Both readers migrate the old triple now, on the defaults those keys carried.
• D5's on-disk rename made every earlier archive invisible. The committed archive (Session history gets lost #1179) exists
  because git clean -fdx used to delete a project's whole history; renaming its directory without
  reading the old name reproduced exactly that, one upgrade later. Both names are read and both are
  un-ignored — rewriting the .gitignore with only the new one would have ignored a pre-rename
  archive. Same for the transient runs/, which is the one history with no second copy anywhere.
• ~93 comments still described Telefunc and Vike as the live mechanism, including three that
  justify code by a constraint Telefunc imposed and that no longer exists, and a dozen suites
  explaining their mocks by a failure mode that is gone.
• D5's prose rename had not happened. Identifiers, disk layout and SPECs said "agent"; ~1,700
  lines of doc comment still said "run". run as a verb and GitHub Actions runs stay.
• SessionOptions / SessionKind sat in the public barrel beside runAgent /
  RunAgentOptions, naming the same unit of work in the vocabulary D5 retired.

Two defects found by using the product were fixed alongside them: the usage panel's unplaceable-week
error contradicted the readout it was printing directly below (a week line with no reset time — what
an untouched account prints — fell through to the "no week at all" wording), and the handoff panel's
push ran outside the lock that teardown holds across the same branch's push, so the two collided
creating one ref and a lost teardown stranded the worktree. That race is what had been flaking
publish a finished session in CI.

What was kept, and why

Six proposals were rejected: B1 and B4 (data model), F5 (dashboard feature surface),
E3 (the routine rotation), G1 (SDD — the SPEC.md beside every source file stays, which is
why every deletion here takes its specs with it and every behaviour change rewrites them), and
C4 (the ${{ }} template language). Each one's live consequences are written into the SPEC.md
of the thing it is about, which is where SDD puts a decision — the permanent fork-point ambiguity in
the queue promoter, the template language's scan limit, the foreground daemon's trade.

Behaviour changes, called out

One from the review, and it is a restoration rather than a change: declining a plan stops the
agent — the behaviour D6 dropped when the gate kind that carried it was collapsed. It is back as
a property of the gate: an option the agent marks stop ends the session instead of resuming it.
That is strictly more general than what it replaces, which only worked for plan approvals.

Two breaks, both the same call the maintainer already made explicitly for the on-disk layout —
break rather than carry a compatibility branch: the spawn flag --session {path} is now
--agent {path}, and agents branch the-framework/agent-{id} rather than run-{id}.

Everything else preserves behaviour. Where it could not, the commit message says so in its own
words.

Verification

Every commit on this branch was verified the same way: both typechecks, a full build, 1,418 node
tests, 768 dashboard tests (80 files), and a non-root run that reproduces CI's environment.

Three more, raised by the review and then acted on

• The dashboard imported the package's own build output. Not a decision — A7 merged the two
  packages by rewriting @gemstack/the-framework into the path that name resolved to, leaving the
  dashboard depending on dist/. pnpm typecheck failed on a fresh clone with 160 errors until
  something had run tsc, and editing src/ type-checked the browser against the last build.
  Of ~120 imports, all but the browser-safe barrel's are type-only and reach no bundle at all, so
  they now come from ../src: 160 errors to 0 with no dist present, and a byte-identical bundle,
  because the module graph never changed — only whether it was read pre-compiled. One import
  genuinely wants the build and says so: the dev:daemon plugin runs the real daemon in the Vite
  config's own Node process.
• Two components nothing rendered. ActivityChart and AgentOutcomes were drawn only by the
  design gallery, whose own rule is that a card renders the real shipped component. Deleting them
  was the smaller half: Improve dashboard #1139 cut the page that drew them and left DashboardData still carrying
  agentsByStatus, activity, totalAgents and most of ProjectStat — every one of which needed
  listAgents over every project's entire archive, on a payload two pollers ask for every 5 and 10
  seconds. The daemon was walking every project's whole history twice a cycle to compute a
  fourteen-day histogram nobody has seen since. A test pins the payload's shape.
• TODO_SIMPLIFY.md is gone, after the decisions still live in it moved into the SPECs where
  SDD puts them: the template language's scan limit (C4's rejection asked for exactly this, and
  reading the code to state it corrected the claim — it is "never two closing braces adjacent", not
  "no braces"), and the foreground daemon's trade from D4b. Git holds the document; this description
  holds what it decided.

[brillout]

CI build is failing on this PR, and I can't attribute it to the change

Flagging rather than fixing, because I've been unable to reproduce it and I don't want to push a speculative CI change on a docs-only PR.

This PR's entire diff is two markdown files — TODO_SIMPLIFY.md and MEMORY.md. No source, no config, no test files:

 MEMORY.md        |    7 +-
 TODO_SIMPLIFY.md | 1267 ++++++++++++++++++++++++++++++++++++++++++++++++++++++

Nothing under test reads either file (grep for TODO_SIMPLIFY|MEMORY.md across packages/ and e2e/ returns nothing), so there is no mechanism by which they affect a test run.

What I checked

	Result
main at 6b211c9 (the base this branch now contains)	green — as are all recent runs on main
Full CI pipeline locally on the failing commit 8c73f15	green — build, typecheck, test; 7/7 turbo tasks, 1,722 node tests + 803 dashboard tests
Clean-room repro: fresh clone at 8c73f15, fresh pnpm install --frozen-lockfile, CI=true	green, exit 0
Without a global git identity (runners have none)	green, 1,722 pass
Node version	CI pins 22; local is 22.22.2
Turbo cache masking a failure on main	Ruled out — no remote cache, no globalDependencies; both start cold

It has now failed twice in a row (f49a9e6 and 8c73f15), so it isn't a one-off. I merged main in between, which did not change the outcome.

What the log suggests, and what I can't see

Turbo reports Failed: @gemstack/the-framework#test, but there is no not ok line, assertion error, or stack trace anywhere in the retrievable portion. The dashboard suite also ends without its Test Files … passed summary — it stops right after components/PreviewBar.test.tsx and goes straight to [ELIFECYCLE]. That pattern reads as a process aborting (crash, OOM, or the 60s per-test timeout in run-tests.mjs) rather than a test asserting false.

I could not confirm this: the failing task's output is at the head of the job log, and the tooling available to me only returns the tail (~21 KB), with direct Actions-API log download disabled for this session.

What would settle it

Anyone with Actions access can open the full log and search for not ok or ##[error] above the turbo summary — that single line is what I'm missing. Alternatively, a re-run with --concurrency=1 would show whether it's contention between the two test suites running in parallel.

Happy to fix it once the actual failure is visible. I've deliberately not pushed CI config changes to chase it blind.

---

Generated by Claude Code

[brillout]

Post-merge review of the refactor

Reviewed the refactor as it stands on main (6ec7850), tracing each candidate end-to-end against current code, with the pre-refactor tree (acb7f30) as the comparison. Excluded up front: everything a follow-up already fixed (#1543's back-read removal, #1545's notice deletion, #1580/#1581's branch names), and everything the zero-migration policy settles — e.g. retired autoPushBranch/autoOpenPr/autoMerge keys in a committed yml going silently inert is pinned as deliberate (config.test.ts:44-45, config.SPEC.md:20, MEMORY.md) and ruled on twice, so it is not a finding. Nine findings, ranked by how much they can hurt. File references are packages/the-framework/src/ unless noted.

1. Teardown pushes a handoff: 'local' session's branch to origin — every session end, automatically

removeProjectWorktree pushes any branch not already on the remote before removing the checkout (worktrees.ts:133-143 → pushAgentBranch, dashboard/agent-handoff.ts:418), and neither it nor any caller reads the handoff level. It runs on every daemon-spawned session end — settle → tearDownWorktree → removeProjectWorktree unconditionally, whatever state the agent ended in (daemon-runtime.ts:743-760, :564) — plus the startup/10-minute sweep and the dashboard's Remove button. So on any remoted repo, a session explicitly configured handoff: 'local' — the rung that exists to mean "publish nothing", the deliverable of B5/#1379 (handoff-level.ts:8-9) — gets its tf-agent-… branch pushed to origin under the user's credentials seconds after it finishes. The agent-side handoff honors the rung (agent-handoff.ts:620 skips as not-armed); the daemon then publishes at teardown anyway.

The same push overrides two of the code's own intents: a stopped agent ("publishing what it happened to reach is the opposite of what stopping meant", cli.ts:975-977 — then Stop → exit → teardown → push), and the daemon's own CI-fix agents, started handoff: 'local' precisely because "this agent's handoff must not push or open anything of its own" (daemon-services.ts:277-279).

Push-as-removal is documented policy (worktrees.SPEC.md:5, MEMORY's removal rule), but no SPEC, MEMORY entry or this PR's "behaviour changes, called out" section addresses the collision with handoff: 'local' — and this PR's own R2 section states the standard it breaks: someone "who had declined to publish would have come back … to branches on the remote … under their name, from a tool they had told not to." Pre-refactor teardown committed and removed without ever pushing. The retention rule doesn't force the push: keeping the checkout is the rule's own documented fallback, already what happens for a remote-less repo (worktrees.ts:137-141). Treating an unpushed handoff-local worktree the same way (keep it, don't publish it) satisfies both.

2. E2 re-fans-out ticketless queue entries mid-handoff — the deleted claim's own doc named this exact case

E2 deleted RunMeta.queueEntry + claimedQueueEntries + the cross-machine PR-diff reader, whose seam doc said verbatim: "a hands-off web run's local process ends at the hand-off while the cloud session still works the entry — both would otherwise put the same entry back on the market and fan it out to a second agent." That is now what happens for entries with no ticket link. Trace on main: preferences target: 'web' rides into unattended drains (agent-options.ts:67,86, daemon-services.ts:156-159); a web agent's local meta settles done at the hand-off while the cloud session still works (agent-location.ts:39-41, agent.ts:272-275); the next tick promotes, gets already up to date (the local branch never touched the queue file, queue-promote.ts:76), settles, and drops the in-memory pin (auto-pm.ts:650-668); the entry is still open — its check-off lands only when the cloud PR merges (auto-pm.ts:758-763) — so after the 30-minute cooldown the sweep starts a second agent, and a second cloud session, on the same entry, repeating until the first PR's merge reaches the checkout. A daemon restart drops the pin the same way.

Ticket-linked entries are protected by #1573's pushed .lock.md (verified: ticket-locks.ts:130-143, failed locks dropped at auto-pm.ts:791-802); a plain-text entry gets pinnedDrainJob unconditionally (auto-pm.ts:794). Neither queue-promote.SPEC.md nor auto-pm.SPEC.md owns the in-flight window as an accepted cost — auto-pm.SPEC.md:8 says a ticketless entry "keeps the queue itself as the coordination point", but during a hand-off the queue file demonstrably doesn't coordinate. And the comment at daemon-services.ts:223-224 still claims the pinned entry "rides along (#1253) … and outlives … the agent's local process" — a protection E2 removed. Either the SPEC owns the window, or ticketless entries need the same lock shape #1573 gave tickets; the stale comment goes either way.

3. A Start landing during shutdown spawns an agent nothing ever stops

Shutdown order (daemon.ts:268-287): quiesce → stopAgents → flushAgents → … → dashboard.close() last. The HTTP surface keeps accepting until that final step, and neither sendStart (dashboard-rpc/control.ts:177-193) nor /_relay/start (dashboard/relay-endpoints.ts:83) checks any closing flag. The spawn is detached: true + unref() (daemon-runtime.ts:105-123) — its own process group, so the terminal's Ctrl-C never reaches it. stopAgents snapshots activeAgents once (daemon-runtime.ts:836-845); an agent in the starting window (registered only at :761, after an awaited spec write) is in neither the snapshot nor the wait. Result: a Start clicked (or relayed) during the multi-second stop span produces an orphan on ppid 1 holding a worktree, burning quota after "everything closed" — and next boot's reconcileOrphanedAgents only flips agents whose pid is dead (store/agent-store.ts:917-946), so it stays running.

The window itself pre-dates this PR (same ordering at acb7f30), but the PR recorded the invariant it violates — MEMORY's "Ctrl-C closes everything", daemon.SPEC.md:6 "nothing burns quota after you have closed it", and stopAgents' own doc describing exactly this orphan. auto-pm.ts:841-851 already fixes the identical shape for its own spawns (#983); onStart has no equivalent. Cheap fix: a closing flag checked in onStart, or close the server before the stop pass.

4. The startup footer advertises a command that exits 2

Every daemon start prints "Type a prompt on the dashboard to start an agent, or use: framework "<what to build>"" (cli.ts:1311-1314), but D4 removed the positional path — framework "build me X" now answers unknown command: build me X, exit 2 (cli.ts:286, :646-650). The line was accurate pre-D4 (positionals became opts.intent); the refactor deleted the path and left the advertisement. Nothing pins the text (the footer test asserts other lines). One-line fix.

5. Agent specs leak their temp directory — and the whole prompt on spawn failure

writeAgentSpec mkdtemps framework-session-*/session.json per spawn (agent-spec.ts:46-47); readAgentSpec removes only the file, never the directory (agent-spec.ts:57-59), and no sweeper exists — one empty dir per session, forever, under a long-lived auto-PM daemon. On the spawn-error path neither writer cleans up at all (cli.ts:1358-1362; daemon-runtime.ts:728-740,759 — settle tears down the worktree but never touches the spec), leaving the full prompt on disk. Both contradict the module's own claim that "a spec never outlives the session it started" (agent-spec.ts:43, agent-spec.SPEC.md:7 — the rationale being a device token in the options). Fix: rm the spec's dirname recursively in readAgentSpec, plus cleanup on the error paths.

6. preset: / event: are a zombie config surface

The keys are still parsed, type-validated, resolved and confirmed to the user — the ◆ config: preset=… echo (config.ts:47, config-layers.ts:83-89,112-115, cli.ts:704-705) and launcher chips (dashboard/components/ResolvedOptions.tsx:27-28) — but A5 deleted every functional consumer (resolveDomainPreset, the review loop, domainLoopChecklist: zero hits on main). Two regressions ride along: an unknown preset used to error and now any string is accepted and narrated as if in force, and config.ts:14 still documents event by "the preset's review loop" A5 deleted, with config.SPEC.md:1 still presenting preset as live surface. This violates the CLI's own stated standard four hundred lines away: "A setting that silently does nothing is worse than one that errors" (cli.ts:361-363). Either the keys go, or something consumes them.

7. Dead option plumbing left behind by D4

Six fields survived the collapse with no transport: StartAgentOptions.autopilot/.technical (dashboard/types.ts:56,58) are written and read by nothing, under a header still claiming "each maps to a run flag" that no longer exists; AgentOptions.sessionLink has a live reader (cli.ts:87-90) that no writer can reach — while cli.ts:72-73 and session-link.ts:9 both instruct embedders to "set sessionLink on the spec", an instruction that is silently discarded; AgentOptions.preset/.buildEvent feed flagConfigLayer (cli.ts:384-385) but nothing can set them; todoMaxItems is read live (cli.ts:1233 → agent.ts:248) and settable nowhere — the suite itself asserts the void (cli.test.ts:116). Same-vein residue: an orphaned doc comment for the removed eco field (dashboard/types.ts:63) and a modes event kind + OPEN_LOOP_MODES = ['autopilot','technical'] (events.ts:316,336) that nothing outside tests emits.

8. The "not enabled on this server" guards are unreachable, and control.SPEC.md still describes them as live

contextStartAgent()/contextAddProject() throw on an unwired field by documented design ("Unwired is a bug rather than a degraded host", dashboard-rpc/context.ts:27-37; every context field required since D3), so the crafted { ok:false, error: 'starting a session is not enabled on this server' } branches (dashboard-rpc/control.ts:183-184, projects.ts:27-28,42-43) can never run — a hypothetically unwired host answers 500. Pre-F3 these guards were live (hosts wired subsets; the relay really got the friendly error). The right cleanup is deleting the guards — and fixing control.SPEC.md:6, which still says "exist only where the daemon wired them; other hosts refuse", directly contradicting context.SPEC.md:5 and the code.

9. The sweep grinds forever on checkouts that can never push

Mostly documented policy (remote-less repos keep every checkout; each failed reclaim is announced — worktrees.SPEC.md:6,10, merged-worktrees.SPEC.md:7), but the undocumented residue: the sweep is stateless (merged-worktrees.ts:65-79), never consults hasRemote (which the handoff path does check — agent-handoff.ts:277,637), and so re-runs ~5 git spawns and prints the identical "kept the worktree" line per retained checkout every 10 minutes, forever, for a condition that cannot change. New consequence worth stating somewhere: post-E5 a remote-less repo accumulates one permanent checkout per session (pre-refactor, clean finishes were removed locally), and the dashboard's Remove can never succeed there — only the history-destroying Delete reclaims disk. Distinguishing "no remote configured" from retryable failures (or deduplicating the repeat line) is the whole fix.

---

Held up under attack (verified, no finding): the retired-yml silence (settled policy, pinned), E5's push-as-removal mechanism itself (SPEC-owned — finding 1 is only its collision with handoff: 'local'), #1573's drain locks for ticket-linked entries, and the throw-on-unwired context design.

Happy to fix any subset of these — say which. 1, 4, 5 and the stale comments are small and self-contained; 2 and 3 each want a design call (own the window in the SPEC vs. close it) before code.

---

Generated by Claude Code

[suleimansh]

Take 1, 4, 5 and the stale comments first. 1 is confirmed live on our side too — teardown pushed a declined session's branch to origin during the 2026-08-17 dogfood — and the keep-the-worktree fallback (the remote-less behavior) is the right fix, no new mechanism.

2: fix the stale daemon-services.ts comment now, but own the window in the SPEC rather than building a ticketless lock — #1582 moves the queue to the eagerly-pushed data branch with the check-off landing daemon-side, which closes this window structurally, so any new claim shape here would be deleted weeks later.

3: close it with the closing-flag check in onStart (the #983 shape) rather than reordering shutdown.

6, 7, 8: delete it all per the zero-users rule — unless you want preset: live soon, in which case say so and it needs a consumer, not a guard.

9: check hasRemote once and log the kept-checkout line once per checkout, not per sweep.

[brillout]

Done — #1594, one commit per instruction, in your order.

The two calls you left open, resolved as directed: 1 is the keep-the-worktree fallback with the armed handoff read off the agent's meta (so the daemon's own handoff: local CI-fix agents are covered too, and an already-pushed branch still lets the checkout go); 2 is the comment fix plus auto-pm.SPEC.md owning the window as accepted-until-#1582, no new claim shape. 6–8 deleted throughout — nothing wants preset: live. One consequence stated out loud: the lifecycle e2e story now pins the new contract (a local-handoff session ends with its checkout kept and nothing on origin), and the publish story runs push-armed so the click-vs-teardown ref collision it exists to pin still happens.

Verified on the head: both typechecks, a full build, 1466 node / 771 dashboard (81 files).

---

Generated by Claude Code