pan start, watches the pull request to landing, and parks what it cannot decide for you. Its status is never stored: everything on this page and in pan flywheel status is derived fresh from the conversation, the tracker and the pull request.
What the loop does
Each tick is one pass through five phases:- Orient: read the policies, the backlog sequence, the bound order book if any, and the issues already in flight.
- Drain what is already in flight: walk every in-flight issue first and make the first move each one needs before picking anything new.
- Pick the next item: choose the next issue from an active order book, or the backlog sequence in rank order.
- Launch: start the issue with
pan start, the loop’s only launcher. Ifpan startfails with a disk-low error, the loop launches nothing else that tick and raises a Needs-you item instead. - Watch to landing: follow the issue’s pull request through review, tests and merge.
- It orchestrates and never writes code, specs or plans; the only files it writes are
.pan/flywheel/state.md,.pan/flywheel/report.mdand its.pan/parked.mdlist. - It keeps to
roles.flywheel.maxAgents(default 30) as its own instruction, not a checkpan startmakes. - It never merges or deep-wipes anything itself; merges follow the merge policy, see Auto-merge.
- It never adds or removes the operator-only labels
released,vetoed,auto-mergeorhold-for-uat; itsghaccess refuses those writes. vetoedis absolute: a vetoed issue is never picked up, planned or struck from vetoed by the loop.- It does not auto-start changes to pipeline machinery; it marks them
needs-handoffinstead. - There is one Flywheel conversation per Overdeck install, and starting a second one while the first is active is refused.
- After a merge to Overdeck’s own main with green CI, it runs
pan reload; it does not deploy other projects.
Start and control the loop
start refuses to run while a flywheel is already running, and refuses a paused one too unless you pass --fresh, which replaces the paused conversation (its old transcript stays on disk). stop pauses the loop either way, even when no report arrives within --timeout.
The Flywheel page’s toolbar shows different buttons depending on run state: idle shows Start (and Start fresh when a leftover session is detected); paused shows Resume and Start fresh; running shows Pause, Report, Stop and Abort. Pop out and a Conversation / Terminal toggle are always available.
A Run config footer shows the Harness, Model, Effort, Max agents and Scope the loop is running with, and opens Settings → Roles → Flywheel, where the Flywheel effort and Flywheel max agents fields live. The model defaults to claude-opus-5-5 and the effort to high; see Effort for what effort controls and how a resumed loop keeps the effort it started with.
pan orders start <book-id> opens the same flywheel conversation bound to that book; see Order books for how that compares to pan flywheel start --orders.
Open the page from the left column’s Flywheel entry, the command palette’s Open Flywheel action, or directly at /flywheel.
What the loop picks up
An issue is pickable when all of these hold:- It is ready (the
readylabel). - It is planned: it has an xBRIEF with tasks.
- It is released: the
releasedlabel is set, or Auto-pickup is on, or it is a member of the active order book. - It is not parked, not vetoed, not under an
objection, not already in pipeline, and not an epic.
pan start, which does not check it on its own. Overdeck’s automatic work dispatch, which can start work agents outside the loop, checks the same release conditions in code. The Forecast view on /backlog shows the same rule.
Order matters too: a bound or running order book’s items come first (see Order books); otherwise the loop walks .pan/backlog/sequence.md in rank order. A Promote gate jumps an issue ahead of its rank; a Vetoed issue is never picked up. Before picking anything new, the loop drains every issue already in flight, making the first move each one needs.
The three switches
The Flywheel page header shows three switches. They are global app settings, not per project, except that a project can opt out of the merge train withmerge_train: disabled in projects.yaml.
Require UAT holds a ready PR for your Merge click; it never requires a passed UAT verdict before merge. A failed UAT verdict at the head commit blocks merge only while the issue is held for UAT, so with this switch off and no
hold-for-uat label or project hold, it does not block; see Issue pipeline for that distinction.
Batch size and wait for the merge train live in Settings → Merge Train; see Auto-merge for the full merge policy and Merge batches for how the train itself works.
Read the Flywheel page
Header
The header shows a run chip:running · tick N, paused, idle, or unreachable when the status read itself fails. A failed read never shows idle: before any status has loaded the chip shows unreachable; after that the chip keeps the last status and the Status tab notes that it is showing the last status. Next to it sits a freshness badge, the conversation’s running duration, an in-flight count (N in flight · M shipped today), and the three switches.
Freshness has three states: live when the last tick was 60 seconds or less ago, breathing when it was 20 minutes or less ago, and stalled when it is older than that.
The rail
The left rail stacks, top to bottom: the Merge train card (every project’s train in one card, with project filter chips; see Merge batches), the running order book card when one is bound, and the Flywheel card itself, which has four tabs: Status, State, Report and Stats. The State tab renders.pan/flywheel/state.md, the Report tab renders .pan/flywheel/report.md, and the Stats tab shows the same substrate-bug stats as pan flywheel stats. The rail is resizable and stacks above the conversation on narrow screens.
The lane board
The Status tab opens with a headline strip and a health strip, then the last tick, any Needs-you cards, the lane board, and Shipped today (merges, deploys and release tags since local midnight). The lane board has seven lanes, in this order: Plan, Build, Checks, Review, Merge, Deploy, Done today. Each lane header shows its name and a count. A card in a lane shows the issue id, how long it has sat in that stage, cost, owner, title, an agent line, one plain sentence on why it is not moving, and its last activity. Clicking a card opens the issue; a Deploy or Done today card links to its pull request.The right column
The right column holds theconv-flywheel conversation itself, with its own composer so you can talk to the loop directly, or its terminal.
Needs-you items
Needs-you items come from the tick marker’sneeds-you= field, one item per ; -separated part. The loop keeps an item’s wording identical until it is resolved, because the page matches items by their exact text.
Each card shows the question, why it came up, and when (tick <n> · HH:MM · <age>). An issue id opens that issue; text written as owner/repo#<n> links to the GitHub pull request or issue; an item ending in a URL inside angle brackets (for example <https://...>) renders as a link. A real control appears only where one applies: the test-removal waiver, Start <ID> then Confirm start, or Open <ID>.
The show message link (labelled “Show where this was raised” for screen readers) opens the conv-flywheel conversation at the message that first raised the item, or reopens a pending question.
The top bar’s Needs you · N button counts the one shared Needs-you list, which includes Flywheel items, and is always shown. See Issue pipeline for Needs you in general.
Parked issues and pan parked
These are two different things, and the page keeps them apart. The loop parks an issue it cannot decide for itself, such as ambiguous scope or a destructive step outside the acceptance criteria, by listing it in.pan/parked.md with a one-line reason, then moves on to the next pick. It skips any issue that already carries the parked label or a .pan/parked.md listing. You can park an issue yourself with the Park toggle in the pickup controls, which sets the parked label; such an issue shows state parked in pan show. To unpark it, remove the label or delete its line from .pan/parked.md.
pan parked lists a different set: issues stalled in one of three orbits, oldest first, each with why and how to release it:
operator-gate: an agent you paused, one marked troubled, one you stopped, or an openpan askdecision waiting in Needs you. Release it withpan unpause <id>,pan untroubled <id>,pan start <id>, or by answering thepan askdecision.zombie-session: a live agent on an issue that is already closed.idle-running: a live agent idle for 6 hours or more with no pipeline stage owning the next move.
--json prints the raw rows. pan parked does not list issues parked by the parked label or by a .pan/parked.md listing; those show up on this page and as state parked in pan show.
The backlog sequencer
The Backlog Sequencer page, at/backlog (open it from More → Operations → Backlog), ranks the open backlog in pickup order with dependency context and the gates that control pickup and planning.
It has three views: List, DAG and Forecast. The List view’s columns are rank, importance, the issue with status markers, a one-line why, size, condition, gate and a 0 to 100 score. The DAG view draws the dependency graph, collapsing to the top issues plus their neighbors once the backlog gets large. The Forecast view shows a stat bar of counts (in flight, ready, planned, pickable, and more) and two sub-tabs: Waves, which groups pickable work into the order it would run, and Lanes, which shows the same work spread across a modeled number of parallel agents.
Filters narrow by importance, condition, pipeline membership, release status, having a PRD, free text, and a stale toggle.
Four buttons run a sequencing pass, one at a time:
- Run creation pass ranks the open backlog from scratch; it shows only when there is no sequence yet.
- Update changed re-reads only the issues that changed since the last pass and keeps every other rank.
- Re-rank all re-ranks the whole open backlog; slower and more expensive than an incremental pass.
- Clear deletes the sequence file and its cache so a creation pass can rebuild it.
sequencer-runner agent on roles.sequencer.model; see Model routing for what that role resolves to.
Hovering a row shows + Order book, which adds the issue to the active order book’s Lane A or Lane B; a row already in a book shows Open order book instead. Clicking a row opens its detail panel, with the same pickup controls also found in the issue cockpit and the issue drawer: Release moves a planned issue to released, Recall undoes it, Promote jumps an issue ahead of its rank, and Vetoed keeps it out of pickup, planning and the sequence’s own ranking entirely.
The sequence lives at .pan/backlog/sequence.md in the plan home, committed on main. pan backlog write-sequence <file> is how the sequencer agent writes it: it validates the file’s fields (issue, rank, size, importance, score, condition, dependsOn, why, gate, planning), commits and pushes; see Pipeline commands for the full command. Never hand-edit the file.
Files the loop and the sequencer keep
The loop and the sequencer each keep their state in a few plain files under the plan home, never in a database:.pan/flywheel/state.md: the loop’s memory across runs, substrate fixes and learnings it wants to carry forward. It is appended to, then committed and pushed..pan/flywheel/report.md: what shipped, what is in flight, what is parked, and substrate fixes found. It is written onpan flywheel stoporpan flywheel report, replacing the previous report, then committed and pushed. The Flywheel page’s State and Report tabs render these two files..pan/backlog/sequence.md: a human-readable table and rationale for the top of the backlog, followed by a machine-readable JSON block below a marker line. Do not hand-edit anything below that marker; it is committed onmainaschore(workspace): backlog sequence.
pan backlog write-sequence <file> is the only way the sequence file should be written: it validates the JSON (naming fields like issue, rank, size, importance, score, condition, dependsOn, why, gate and planning), skips the commit when only the timestamp would change, then commits and pushes. A validation error prints Validation error: ... and exits 1. See Pipeline commands for the full command reference.
Known limits
- The loop’s author gate names fixed GitHub logins: it acts only on issues whose author is
eltmon(the Overdeck maintainer) orpanopticon-agent[bot], or that are assigned toeltmon. On any other repo or account the loop skips your issues, and the current GitHub App bot (overdeck-agent[bot]) does not pass it either. See issue #5544. - The Backlog page and its automatic pass read the sequence from the dashboard server’s working directory, the Overdeck checkout or install it runs from. There is no project picker yet, and a pass ranks only issues whose id starts with
PAN-(Overdeck’s own tracker), so on any other project the sequencer has nothing to rank. - The agent cap (
roles.flywheel.maxAgents) and the pickup rule are applied by the loop’s own instructions;pan startchecks neither on its own. - There is one Flywheel conversation per Overdeck install,
conv-flywheel.
Related
- Flywheel vision: the roadmap and the readiness criteria for a user-facing v1.0.
- Issue pipeline: the stages an issue moves through after
pan start, and Needs you in general. - Order books: curated campaigns and the
pan orderscommands. - Auto-merge: the merge policy the loop never bypasses.
- Merge batches: the merge train.
- Pipeline commands: the full
pan flywheelandpan backlogflag tables.