You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your sessi
8000
on.Dismiss alert
{{ message }}
Repository navigation
Decompose useRuns and useDocumentLifecycle further #52
src/useDocument.ts was decomposed from 1,777 lines into six hooks (594-line composer). Two of the
extracted hooks are still large and are the natural next step:
src/runs/useRuns.ts — 794 lines.
src/document/useDocumentLifecycle.ts — 564 lines.
Why they were left whole
Both have a real reason, so this is a considered deferral rather than an oversight:
useRuns holds all five Run kinds because they share runInFlightRef, abortRef, priceTable
and sessionCost. Splitting per kind would add churn across four call sites without removing any
shared state.
useDocumentLifecycle bundles persistence + Library + metadata + durability, which are cohesive
around one DocumentRecord and one persistence controller.
What a follow-up should do
Find the seam that actually deletes shared state rather than just moving lines. Candidate: a single
run-state value (a discriminated union over the five Run kinds) replacing the five independent {running, startedAt, error} triples — which would also remove the class of bug fixed in anyRunInFlight (src/editor/announcements.ts), where one call site enumerated the flags
incorrectly.
Constraints
DocumentHandle is 98 members and is consumed by App.tsx, WorkingOrderRail, BandPanel, JudgePanel and WorkbenchView. Keep it stable, or change all consumers in the same commit.
send(ModelRequest) -> Promise<string> stays the only test seam. There is no DOM test layer, so a
change here is verified by tsc, the existing suite and the build only — read the dependency
arrays by hand.
Decision (Writer, 2026-09-26): hand to an agent, last. Relabelled ready-for-agent and blocked by every terminal v1.3 ticket so it does not conflict with the Rail and settings work. The constraints above stand: keep DocumentHandle stable or change every consumer in the same commit, preserve hook closure semantics exactly, verify by tsc, the suite and the build, and read the dependency arrays by hand. The run-state union is the seam to aim for; if it does not delete shared state, stop and report rather than moving lines.
Stopped before changing any code, per the Writer's decision: the run-state union does not delete shared state on v1.3 (55b0ad8).
A single discriminated value over the five Run kinds only removes state if at most one Run can be in flight at a time. On v1.3, several can run at once, and the per-kind errors are shown independently of each other:
Reader, Audit and Judge runs can start while other Runs are going.anyRunInFlight only gates the Findings Run buttons and the structural set (WorkingOrderRail.tsx, busy={runBusy}). The Reader and Audit Run buttons are disabled only by their own flag (BandPanel.tsx, disabled={!pass.enabled || running}), and so is the Judge (JudgePanel.tsx, canJudge … !running). The hook has no shared guard either: runReaderPass checks only readerInFlightRef, runAuditPass checks only auditInFlightRef, and runJudge has no ref guard at all. So a Findings Run, a Reader run, an Audit run and a Judge can all be in flight together, each showing its own RunningBadge or timer.
The structural set and a model Pass are in flight together by design.runStructuralSet calls runModelPass, so structuralRunning and runningPassId are both set at once. announcementForTransition depends on that pair ("intermediate passes inside it do not announce finished").
Errors outlive their Runs, one per kind.runError, readerError, auditError and judgeError each stay visible in their own panel until that kind runs again or resetReadouts fires. If a failed Findings Run is followed by a successful Reader run, the Findings error is still shown. A single value would lose it.
So a union has two ways to go, and neither satisfies the ticket:
One value that really is a union. Starting any Run would replace the others' state. That forces Runs to be serialised (Reader, Audit and Judge buttons disabled during any Run, or the hook refusing them) and drops persisted errors. Both are behaviour changes, which the constraints rule out.
A per-kind record ({ model?: {passId, startedAt, structural}, reader?: {startedAt, error}, … }). This holds the same fields as today's triples, grouped differently. It moves lines and deletes nothing.
The shared state the issue names doesn't shrink under either option. runInFlightRef and the three abort controllers from #46 stay, because each guards or cancels its own kind, and Cancel run already aborts all three. priceTable and sessionCost have nothing to do with run state. The per-kind *InFlightRefs have to stay too, since they are what stops a second click before React renders the running state.
Other ways forward, for the Writer to choose from (none started):
Decide that one Run at a time is the rule. The doc comment on anyRunInFlight already says so ("a second Run must not start while any of them is going"), but only the Findings and structural buttons enforce it. If that is the intended behaviour, a separate behaviour ticket could gate Reader, Audit and Judge on anyRunInFlight and add one shared in-flight guard in useRuns. After that ships, the union really would delete state: one in-flight value plus one ref would replace four refs and the running/startedAt pairs, with errors kept per kind. Decompose useRuns and useDocumentLifecycle further #52 could then be done as the refactor on top of it.
Take a smaller, honest cut now.readerRunning is always set together with readerStartedAt, and auditRunning with auditStartedAt, so each flag could be derived from its timestamp. That removes two useStates and nothing else. I don't think it meets "delete shared state" and haven't made the change.
Close as won't fix. The five-kinds-in-one-hook design reflects a real product fact: independent Runs that can run concurrently.
useDocumentLifecycle was not attempted: the Writer's decision points #52 at the run-state union.
Labelled needs-info pending the Writer's call on whether one Run at a time is the intended rule.
Handed back to a human (supervisor). The agent stopped as the 2026-09-26 decision instructs: on v1.3 the run-state union would not delete shared state, because Runs of different kinds can be in flight together and each kind's error stays on screen after its Run ends (details in the comment above). No code was changed.
I verified the core finding: anyRunInFlight's doc comment (src/editor/announcements.ts:75) says "a second Run must not start while any of them is going", but only the Findings Run buttons and the structural set honour it; the Reader and Audit Run buttons check only their own flag (src/editor/BandPanel.tsx:537, :600), and the Judge the same. So either the comment or the gating is wrong.
Decision needed: (a) make one-Run-at-a-time the enforced rule as a behaviour ticket first, after which the union genuinely deletes state and #52 can proceed; (b) the small cut (derive readerRunning/auditRunning from start times), which does not meet the "delete shared state" bar; or (c) close as won't fix.
Activity
kiran-brahma commentedon Sep 26, 2026
Decision (Writer, 2026-09-26): hand to an agent, last. Relabelled
ready-for-agentand blocked by every terminal v1.3 ticket so it does not conflict with the Rail and settings work. The constraints above stand: keepDocumentHandlestable or change every consumer in the same commit, preserve hook closure semantics exactly, verify bytsc, the suite and the build, and read the dependency arrays by hand. The run-state union is the seam to aim for; if it does not delete shared state, stop and report rather than moving lines.kiran-brahma commentedon Sep 26, 2026
Stopped before changing any code, per the Writer's decision: the run-state union does not delete shared state on
v1.3(55b0ad8).A single discriminated value over the five Run kinds only removes state if at most one Run can be in flight at a time. On
v1.3, several can run at once, and the per-kind errors are shown independently of each other:anyRunInFlightonly gates the Findings Run buttons and the structural set (WorkingOrderRail.tsx,busy={runBusy}). The Reader and Audit Run buttons are disabled only by their own flag (BandPanel.tsx,disabled={!pass.enabled || running}), and so is the Judge (JudgePanel.tsx,canJudge … !running). The hook has no shared guard either:runReaderPasschecks onlyreaderInFlightRef,runAuditPasschecks onlyauditInFlightRef, andrunJudgehas no ref guard at all. So a Findings Run, a Reader run, an Audit run and a Judge can all be in flight together, each showing its ownRunningBadgeor timer.runStructuralSetcallsrunModelPass, sostructuralRunningandrunningPassIdare both set at once.announcementForTransitiondepends on that pair ("intermediate passes inside it do not announce finished").runError,readerError,auditErrorandjudgeErroreach stay visible in their own panel until that kind runs again orresetReadoutsfires. If a failed Findings Run is followed by a successful Reader run, the Findings error is still shown. A single value would lose it.So a union has two ways to go, and neither satisfies the ticket:
{ model?: {passId, startedAt, structural}, reader?: {startedAt, error}, … }). This holds the same fields as today's triples, grouped differently. It moves lines and deletes nothing.The shared state the issue names doesn't shrink under either option.
runInFlightRefand the three abort controllers from #46 stay, because each guards or cancels its own kind, and Cancel run already aborts all three.priceTableandsessionCosthave nothing to do with run state. The per-kind*InFlightRefs have to stay too, since they are what stops a second click before React renders the running state.Other ways forward, for the Writer to choose from (none started):
anyRunInFlightalready says so ("a second Run must not start while any of them is going"), but only the Findings and structural buttons enforce it. If that is the intended behaviour, a separate behaviour ticket could gate Reader, Audit and Judge onanyRunInFlightand add one shared in-flight guard inuseRuns. After that ships, the union really would delete state: one in-flight value plus one ref would replace four refs and the running/startedAt pairs, with errors kept per kind. Decompose useRuns and useDocumentLifecycle further #52 could then be done as the refactor on top of it.readerRunningis always set together withreaderStartedAt, andauditRunningwithauditStartedAt, so each flag could be derived from its timestamp. That removes twouseStates and nothing else. I don't think it meets "delete shared state" and haven't made the change.useDocumentLifecyclewas not attempted: the Writer's decision points #52 at the run-state union.Labelled
needs-infopending the Writer's call on whether one Run at a time is the intended rule.Generated by Claude Code
kiran-brahma commentedon Sep 26, 2026
Handed back to a human (supervisor). The agent stopped as the 2026-09-26 decision instructs: on
v1.3the run-state union would not delete shared state, because Runs of different kinds can be in flight together and each kind's error stays on screen after its Run ends (details in the comment above). No code was changed.I verified the core finding:
anyRunInFlight's doc comment (src/editor/announcements.ts:75) says "a second Run must not start while any of them is going", but only the Findings Run buttons and the structural set honour it; the Reader and Audit Run buttons check only their own flag (src/editor/BandPanel.tsx:537,:600), and the Judge the same. So either the comment or the gating is wrong.Decision needed: (a) make one-Run-at-a-time the enforced rule as a behaviour ticket first, after which the union genuinely deletes state and #52 can proceed; (b) the small cut (derive
readerRunning/auditRunningfrom start times), which does not meet the "delete shared state" bar; or (c) close as won't fix.Generated by Claude Code
docs: mark the v1.3 and backlog tickets completed in the build order