flywheel protocol v1

This is the protocol flywheel enforces today, in code — not the fuller factory model it is building toward. The authority for everything below is the code itself: internal/flywheel/events.go (the kinds map and Validate), internal/flywheel/state.go (Derive’s status transitions), internal/flywheel/verify.go (flywheel verify: rules T1, T3, T4, T5, T8, R1, W1, P1, L1 and V1), internal/flywheel/land.go (flywheel land enforces T7 and T9 live) and internal/flywheel/chain.go (the hash-chained log, checked by flywheel verify --log, with a chain per shard in the sharded layout). docs/design/autonomous-shipping.md describes a larger design — audits, nonconformances, andon signals, a hash-chained log — and much of it is built now (audited and signal events, first-article audits, the chain); §3 below says exactly which parts of that design are still aspiration (T2, T6 and parts of T9 and T10), so a reader never has to guess.

Every record is one JSON line appended to .flywheel/events.jsonl by AppendEvent, and the log is never rewritten — flywheel log (or a command that calls AppendEvent internally) is the only way to add a line. flywheel state derives .flywheel/state.json and the status block in flywheel.md from the log alone (Derive): the log is the one source of truth, everything else is a read-only projection of it. A command whose --dir is inside a unit’s worktree (<root>/.flywheel/worktrees/<task>, made by flywheel run --worktree) uses the main checkout’s ledger at <root>, never the worktree’s stale copy (issue #395).

Every skill in skills/ that drives this loop cites protocol v1 and links back here; cmd/flywheel/docs_test.go fails the build the moment a skill stops citing it, or this file’s first line stops matching ^# flywheel protocol v.

1. Required entries per task
2. Transitions the code enforces
3. Designed, not enforced
4. Who may write which event
Log layout
5. flywheel verify and exit codes

1. Required entries per task

Forty-nine event kinds exist; events.go’s kinds map is the authority for the list, and Validate rejects anything else. A stamped event’s ts is strictly after the previous event in its log (issue #650), so replay never sorts a re-plan before the finish it follows. Nine of the kinds carry a task’s status (state.go’s kindRank orders them, together with some status-neutral kinds, for replay); the rest — worker_plan, no-plan, off-course, report, validated, owns_checked, amended, sharded and the others — change other fields but never the status itself. staffed, goal, session_start, session_command and session_end carry no task at all, and Validate also refuses a task on health, release_audited, reanchored and recovered (events.go).

`planned`

Written by: the planner or lead, via flywheel log --task <id> --kind planned --brief <path> [--session S --model M] [--goal G] [--note TEXT].
Carries: task, brief (the brief file’s path), header (the parsed brief header — owns, needs, needs-state, needs-env, preflight, skills, gates, live-gates, exclusive, review, kind and sha256 — as recorded when the event was appended; Kind is the optional kind: line, issue #475, trimmed and lowercased, the last one winning, which routing and flywheel stats --by model --kind read and flywheel lint checks against lint.kinds in config, default feature, fix, refactor, test, docs, chore, perf; an empty kind: line or another value is a lint problem, and no kind is ever inferred; flywheel lint also warns on a gate running a JavaScript test runner outside lint.test_runners, else the runners package.json’s test scripts and dependencies name, issue #646), and reports a problem for a gate whose command word is not a command (placeholder text; words listed in lint.gate_commands are always accepted, issue #662) or that is a placeholder phrase wrapped in (...) or <...> such as (as the brief), on any host, persona (planner), session and model (the planner’s identity, from --session/--model), goal_id (from --goal; an unknown goal is refused with exit 1 and nothing is appended), note, and issue (the tracker issue the plan links to, set by flywheel brief --from-issue, issue #457; Validate accepts it only on a planned event and only >= 1), and base (the flywheel root’s HEAD commit when the event was appended, omitted outside a git repository or before the first commit, issue #722: the base a lead-built unit’s changed lines are counted from; UnitBase and every dispatch-base reader still ignore it). owns/needs are copied from the brief header when the event is appended. When header is present it is authoritative over the brief file, and owns/needs are its summary.
flywheel brief <task> --from-issue N [--repo OWNER/REPO] --owns a,b [--needs t1,t2] [--gate CMD]... [--kind K] [--force] [--no-plan] [--dir DIR] (issue #457) reads issue N with gh issue view N --json number,title,body,url, writes .flywheel/briefs/<task>.txt atomically (the header from the flags — needs default none, gates default go build ./... && go vet ./... && go test ./... when --dir has go.mod, otherwise --gate is required — then # TASK: <title> (issue #N), Issue: <url>, ## Why (from the issue) with the issue body, and ## Checks), refuses an existing brief without --force, lints it (a lint problem removes the file), prints the path and, unless --no-plan, appends this planned event with issue N, printing the warnings flywheel log --kind planned prints. Exit 0 ok, 1 error (gh, write, lint), 2 usage (missing --from-issue, a bad N, missing --owns).
Effect: Derive sets status planned. Verify’s T1 (plannedBriefOnly) uses the task’s latest planned event’s brief path, deliberately ignoring any amended events, as the hash a fresh dispatch must match. Acceptance criteria belong to the goal (flywheel goal add --accept CMD), not to a unit: a planned event links to its goal with goal_id. Re-planning an id that already has dispatched attempts starts a new plan: flywheel log warns on stderr (exit 0; --replan silences it, and is a usage error with any other kind), and Derive resets the row’s session, attempt, rc, reason, verdict, model and stale list so the floor shows a clean planned row. The attempt count and every earlier event stay, so the next flywheel run numbers after the old attempts. Branches are shared by every worktree of a repository, so when branch fw/<task> already exists flywheel log also warns that another flywheel root may own the id (issue #479): warning: branch fw/<id> already exists (checked out in <path>); another root may own this id (--replan silences this), the parenthesised path only when a worktree other than this root’s own task worktree has it checked out. It runs read-only git only, and none outside a repository. Take a duplicate plan back with a withdrawn event. flywheel run --worktree on such an id fails naming that worktree.

`dispatched`

Written by: the CLI only, via flywheel run <task> — never by hand.
Not written when a variable the prompt’s needs-env: names (a correction’s unioned with the base brief’s) is unset or empty in flywheel’s environment: run refuses with rule needs-env (exit 6) naming the variables, never their values, before dispatch (only a dispatch_refused event is recorded, issue #534); flywheel validate refuses the same way (exit 6) before any gate runs.
Not written when the worker’s models_allowed list is non-empty and the final model (after --model, routing, a resume’s last model and the breaker’s fallback) is not on it: run refuses with rule models-allowed (exit 6) naming the model, the worker and the list, before any process starts (only a dispatch_refused event is recorded). The breaker never falls back onto a model outside the list, and flywheel config validate refuses a model, fallback or routing candidate outside it (#746).
Not written when a preflight: command exits non-zero: each preflight: CMD line the prompt names (a correction’s unioned with the base brief’s) runs in order in the repository root, as a gate runs, after the needs-env check; the first that exits non-zero or cannot start refuses with rule preflight (exit 6) naming the command, its exit code and its first output line, before any file is written (only a dispatch_refused event is recorded, issue #635). Needs-env and preflight run before the dispatch lock is taken, so a slow preflight never holds up another dispatch; under the lock the prompt must still be the bytes they checked, else the run errors and must be started again (issue #651). Each passing command prints <task> preflight ok: <cmd>. Only flywheel run runs preflight; flywheel validate does not (it measures the deliverable, not capacity).
Not written when a gate the attempt will be measured with (a correction’s gate: lines when it declares any, else the base brief’s) has a command word that is not a command, or is placeholder text like gate: (as the brief) by lint’s placeholder-phrase rule: run refuses with rule gate-command (exit 6) naming the gate and word, before the dispatch lock (only a dispatch_refused event is recorded, issue #662). No gate is run; words in config lint.gate_commands are always accepted.
Not written when config lint.full_suite_required is true and none of those gates matches the full-suite pattern (lint.full_suite, else the toolchain default; or, when an owned path is under a lint.full_suite_paths prefix, every such prefix’s pattern): run refuses with rule full-suite (exit 6) naming each missed pattern, before the dispatch lock (only a dispatch_refused event is recorded, issue #652). An invalid pattern is not refused here; flywheel lint reports it. flywheel validate refuses the effective brief with the same rule (exit 6) before any gate runs, recording nothing, as it does for needs-env.
Not written when config lint.required_gates has a key that applies ("" always; any other key when it prefixes an owned path) with a pattern none of those gates matches: run refuses with rule required-gates (exit 6) naming each missed pattern, before the dispatch lock (only a dispatch_refused event is recorded, issue #751). flywheel validate refuses the effective brief with the same rule (exit 6) before any gate runs, recording nothing.
Not written when config lint.required_live_gates has a key that applies (the same way) with a pattern none of the merged live-gate: lines matches (a gate: line never counts): run refuses with rule required-live-gates (exit 6) naming each missed pattern, before the dispatch lock (only a dispatch_refused event is recorded, issue #845). flywheel validate refuses the effective brief with the same rule (exit 6), with or without --live, before any gate runs, recording nothing.
Not written when config lint.required_observes has a key that applies (the same way) with a pattern none of the brief’s observe: lines matches (a gate: or live-gate: line never counts): run refuses with rule required-observes (exit 6) naming each missed pattern, before the dispatch lock (only a dispatch_refused event is recorded, issue #848). flywheel validate refuses the effective brief with the same rule (exit 6) before any gate runs, recording nothing.
Not written when config lint.owns_companions has a key that applies ("" always; any other key when it prefixes an owned path) with a companion path the merged owns do not contain (an exact entry, a dir/ prefix or a glob counts; a ! entry excluding it does not): run refuses with rule owns-companions (exit 6) naming each missed companion, before the dispatch lock (only a dispatch_refused event is recorded, issue #785). flywheel validate refuses the effective brief with the same rule (exit 6) before any gate runs, recording nothing.
Not written when a skill the brief’s skills: header names (a correction’s unioned with the base brief’s) is not installed as <dir>/<name>/SKILL.md in a directory the dispatching worker’s adapter loads skills from (claude: .claude/skills in the worker’s tree — the --workdir, an existing task worktree, a correction’s recorded workdir, else the flywheel root — then ~/.claude/skills; opencode: .opencode/skill(s), ~/.config/opencode/skill(s), then the claude ones): run refuses with rule skills (exit 6) naming each missing skill and every directory looked in, before the dispatch lock (only a dispatch_refused event is recorded). A plugin skill (a name with :) and an adapter with no known skill directory are not checked (issue #695).
Not written when the brief’s agent: header (issue #755; a correction keeps the base brief’s, and one naming a different agent is refused) names an agent the dispatching worker cannot run: the worker’s adapter is not claude, no .claude/agents/<name>.md exists in the worker’s tree (as for skills:) or under ~/.claude/agents/, or the file has no --- frontmatter or an empty body. run refuses with rule agent (exit 6) before the dispatch lock (only a dispatch_refused event is recorded). The claude dispatch passes the file inline as --agents '{"<name>":{"description":...,"prompt":...,"tools":[...]}}' --agent <name>.
Not written on a kind: fix task’s first dispatch (no --resume, no --delta, no earlier dispatched event) with lint.red_first on when no gate_probed event recorded before it failed on a gate still in the brief: run refuses with rule red-first (exit 6) before preflight and the dispatch lock (only a dispatch_refused event is recorded), so a missed probe costs no paid attempt (#812). A correction (--delta or --resume) of a dispatched kind: fix task whose merged gates drop every red-probed gate the replaced attempt kept is refused the same way, its fix naming the gate to keep verbatim (#825). Red-first (issue #648) is also a flywheel lint --probe problem for a kind: fix brief whose gates all pass on the base tree (config lint.red_first false turns it off), and flywheel inspect --verdict pass enforces it with rule red-first from the gate_probed events recorded before this event, plus those recorded after it on this event’s tree before any attempt finished (issue #833). Rule ci-escape (issue #776) is the same kind of inspect refusal: a correction after a ci_failed event needs a brief with a gate that event’s gates lack.
Carries: task, attempt (r1, r2, … for a fresh run; c1, c2, … for a correction), adapter (one of the four the code accepts: opencode, claude, codex or the offline sim; AdapterFor in adapter.go rejects any other name), worker (the resolved worker’s name, issue #469; omitted on events recorded before it), lead (the lead session that dispatched it: flywheel run --session ID, default $FLYWHEEL_SESSION, issue #472; omitted when unset and on older events, never required), variant (the worker’s reasoning variant, issue #473; omitted when unset and on older events), route (the routing choice, issue #474: {model, pick, objective, draw, kind, basis, scores[{model, attempts, score}]}, pick exploit or explore; kind the task’s brief kind: (issue #475, omitted when it has none) and basis the scoreboard the choice used: kind when at least one candidate has enough attempts and a score on that kind’s own rows, else model (the model-wide rows, as for a task without a kind); scores are the rows used; omitted when the worker has no routing block, when --model was given, on a resume, and on older events), model (flywheel cost charges each finished event to the model on its own attempt’s dispatched event, falling back to the task’s latest preceding one when the attempt has none; flywheel stats --by model scores every adapter, model and variant from these events, and a rate whose denominator is under 3 is null in JSON and n/a in text; --by model --kind adds the same scoreboard per task kind, by_model_kind in --json, each row’s kind the kind of its task’s latest planned or amended header), path (the run file), sha256 (of the exact prompt sent), brief (for a correction attempt: .flywheel/briefs/<task>.<attempt>.delta.txt, the per-attempt snapshot of the delta taken atomically at dispatch; the operator’s --delta file is left untouched and may be edited or reused for the next correction without breaking this one’s T1, issue #452; a failed snapshot fails the dispatch), header (the parsed brief header of the exact prompt dispatched — the planned brief on a fresh attempt, the delta on a correction — authoritative over the file it names), baseline (paths already dirty at dispatch, so a later owns check can excuse pre-existing dirt it didn’t cause), tree (the worker’s tree’s content tree hash just before the worker starts, as validated records it; omitted when it cannot be computed, never failing the dispatch; red-first counts a gate_probed event recorded after the first dispatch only when its tree equals this one, issue #833), base (the commit HEAD pointed at in the worker’s tree when the attempt was dispatched, so the owns check can count changes the unit’s own commits since then, issue #332; flywheel run <task> --worktree --base REF branches a new fw/<task> from REF’s commit instead of the main checkout’s HEAD, without checking REF out, so base records REF’s commit — an existing fw/<task> that does not contain REF is refused with a flywheel rebase <task> --onto REF hint, and --base without --worktree is refused (exit 6, rule base) before dispatch (only a dispatch_refused event is recorded), issue #456; without --base a new fw/<task> starts from origin/<integration.branch>, else the local integration.branch, when that is configured (neither resolving refuses the dispatch), else from HEAD with a progress warning when HEAD carries commits origin/main (else origin/master, else the local main or master) lacks, issue #550), workdir (the worker’s tree, canonical absolute form, recorded only when it is not the flywheel root: the task worktree for run --worktree, or PATH for flywheel run <task> --workdir PATH, an existing tree the lead prepared, a merge in progress say, used as it is with no setup, checkpoints or attempt commit; --workdir with --worktree, a PATH that is not a directory, or one that is not a git working tree of the same repository (a different git rev-parse --git-common-dir) is refused (exit 6, rule workdir; with --base, rule base) before dispatch (only a dispatch_refused event is recorded); validate and inspect default to it, and a --resume or --delta with neither flag runs there again, issue #545; when that tree is the task worktree the resume or delta counts as --worktree, setup, checkpoints and attempt commit included, issue #894), increment (N when flywheel run --increment N sent only increment N of the brief as a fresh session; the attempt is an ordinary r<n>; 0 or omitted means the whole brief; Validate accepts it only on a dispatched event and only >= 1, and flywheel run refuses (exit 6, rule increment) a brief that defines no increment N — an “Increments” section with item N, or an “Increment N” heading), slot (the unit slot leased for the worker’s tree and given to the worker, worktree.setup and every validate gate as FLYWHEEL_SLOT: a lease per working tree in <git common dir>/flywheel-slots/<n>, the lowest free n from 1, reused for the tree’s life and reclaimed once its directory is gone; omitted outside a git repository; Validate accepts it only on a dispatched event and only >= 1, issue #697), skills (the brief’s skills: list as merged for the attempt, which the fresh dispatch prompt told the worker to load with Load these skills before any other work: a, b.; omitted when none; Validate accepts it only on a dispatched event, issue #695), agent and agent_sha256 (the brief’s agent: name as kept for the attempt and the sha256 hex of the agent file passed to claude --agents; omitted when none; Validate accepts them only on a dispatched event, issue #755), seeded (issue #898: the staging files run seeded before the baseline, one entry per file sorted by to, as on staged but reversed: from the existing protected destination, to the staging path, sha256 the content’s, copied true. For each owned plain file path (no trailing /, ! or glob) under a stage: line’s <from> (the base brief’s lines unioned with the prompt’s) whose staging copy is missing and whose destination is a regular file, the destination’s bytes are copied to the staging path atomically and run prints <task> seeded <to> from <from>; a seed failure fails the run; omitted when nothing was seeded), note.
Effect: Derive sets status dispatched, increments Attempts, and fixes this as the task’s current attempt — every later started, worker_plan, report, finished, validated, owns_checked or lost event whose own attempt differs is stale and ignored (listed under Stale instead of changing anything). Verify’s T1 (ruleT1) checks this event’s sha256 against the current brief (fresh attempts) or the delta file it names (c* attempts); an amended event between the dispatch and now excuses a fresh attempt’s mismatch, but never a correction’s.
Locks (issue #893): .flywheel/dispatch.lock is held in two short phases, never across worktree creation, the slot lease, the needs-state links, copies and install, worktree.setup, the baseline or the worktree snapshot. Phase A reads the log and runs every check that reads it (in-flight, owns, exclusive, quiet, limits, budget, unit-cost, routing, breaker, models-allowed, rate-limit, rate, brief drift, the attempt number), then releases the lock. Phase B takes it again just before this event is appended, re-reads the log and re-runs the same checks: a unit that dispatched in between is refused exactly as in phase A (same rule, same dispatch_refused record), and the prepared worktree is left in place for the next dispatch (setup is idempotent). What this event records — the overlap and exclusive notes, the shared gates, the model and route, skills — comes from phase B’s read; the attempt id, which already named the delta snapshot, the run file and the worktree_setup event, is kept, and the run errors instead when another dispatched event of the task landed between the phases. A per-task lock, .flywheel/dispatch-<task>.lock (bytes outside [A-Za-z0-9._-] become _), is held from before phase A until this event is appended, so two dispatches of one task never prepare its worktree at once (it waits up to 30m). Lock order: the per-task lock, then dispatch.lock, then events.lock.

`dispatch_refused`

Written by: the CLI only, via flywheel run <task> (issue #651), when the run returns before dispatched because of a rule refusal (every “refused (exit 6, rule …)” above: needs-env, preflight, gate-command, full-suite, required-gates, required-live-gates, required-observes, owns-companions, retro-missing (issue #854), claude-dir, skills, agent, base, in-flight, owns, exclusive, limits, budget, breaker, models-allowed, …) or because the dispatch lock could not be taken (.flywheel/dispatch.lock held past its wait in either phase, or the task’s own .flywheel/dispatch-<task>.lock, issue #893). Appended through AppendEvent (events.lock), never under the dispatch lock. Not written for a resume with no worker session, for a refusal because the factory is suspended (rule suspended: the owner froze the ledger, and a retry loop would write to it while stopped), for a plain error (bad arguments, an unreadable file), for a task with no planned event, or when the task’s newest event is already a dispatch_refused with the same rule and note (a retry loop records the refusal once).
Carries: task, rule (the refusal’s rule, or dispatch-lock for the lock timeout) and note (the refusal text; for the lock, lock ... is held by run <task> (pid <n>) (waited ..., <n> handovers); ... — the holder named from the lock file’s cmd label, or another command for an older lock file). Validate requires the task and the rule; no other kind may carry rule.
Effect: no status change: the unit stays planned (or whatever it was). Derive sets the task’s refused in .flywheel/state.json to <rule>: <note> of the newest dispatch_refused newer than its newest dispatched; a later dispatched clears it. flywheel status lists each such unit under Refused: <n> as <task> <status> refused: <rule>.

`worktree_setup`

Written by: the CLI only, via flywheel run <task> --worktree (issue #430), after the task’s worktree (.flywheel/worktrees/<task>) exists and before dispatched, on every dispatch that has something to prepare ((link), (copy) or (install) entries, worktree.carry, or a setup command): the effective brief’s needs-state: <path> (link) entries, each linked from the repo into the worktree (a directory junction on Windows, a symlink elsewhere; a path already present is left alone), then the worktree.setup command, run with bash (the gates’ shell) in the worktree with FLYWHEEL_TASK, FLYWHEEL_WORKTREE, FLYWHEEL_ROOT and FLYWHEEL_SLOT (the worktree’s unit slot, issue #697) set and killed at worktree.setup_timeout (default 10m). Setup runs on every dispatch, so it must be idempotent. flywheel rebase <task> also writes one, with no attempt, when it re-runs worktree.setup after a rebase (issue #672; see rebased). A relative script path (the first word, or the second after node/python/bash/sh/pwsh) missing from the worktree but present in the root resolves against the root; prefer "$FLYWHEEL_ROOT/<script>". On Windows gates and setup run in Git for Windows’ bash, never the WSL launcher. flywheel removes a worktree it made (land’s cleanup, the vs-base and group-review temp trees, calibrate) only after removing every link or junction inside it as a link, because git worktree remove follows junctions on Windows and would delete the linked main-checkout files (issue #822).
Carries: task, attempt (the attempt being dispatched), linked (the linked paths), command, rc, duration_ms, note (the last 20 lines of output, or the link error), escaped (issue #460: the entries of a linked path, one level deep plus one level inside each @ scope, that are links or junctions resolving into the main checkout outside the linked path itself and outside the worktree, e.g. a workspace’s node_modules/@acme/web -> packages/web; the .pnpm store and broken links are not), copied (issue #471: the needs-state: <path> (copy) entries plus worktree.carry, copied from the repo into the worktree after the links and before setup, overwriting on every dispatch; the paths only, never their contents), installed (issue #460: the needs-state: <path> (install) entries) and install (the package manager’s offline install run once in the worktree for them, after the copies and before setup, with setup’s runner and worktree.setup_timeout, picked by the lockfile at the worktree root: pnpm-lock.yaml → pnpm install --offline --frozen-lockfile, bun.lock/bun.lockb → bun install --frozen-lockfile, yarn.lock → yarn install --immutable with .yarnrc.yml else yarn install --frozen-lockfile --offline, package-lock.json/npm-shrinkwrap.json → npm ci --prefer-offline --no-audit; or up to date (<lockfile>) when .flywheel/install.sha256 in the worktree, written after an install exits 0, holds the lockfile’s name and SHA-256 and every installed path is a directory). rc, duration_ms stay the setup command’s; an install failure’s exit and tail go in note. flywheel validate in an isolated workdir appends this event too (issue #769) when it re-runs the install because the lockfile changed since the last one, with installed, install and note “validate: lockfile changed since the last install” (followed by the failure’s tail when it fails; a failed re-install refuses with rule setup, exit 6, before any gate).
Effect: no status change. An (install) path that is also a (link) entry (a linked tree is shared and must never be installed into), no lockfile at the worktree root, or an install that does not exit 0 refuses the dispatch with rule setup and an event whose note says why; setup does not run. A copy whose source is missing in the repo, or whose path git tracks in the worktree (a copy would overwrite committed content; use (link) or commit it), refuses the dispatch with rule setup and an event whose note names it; a copied path git does not ignore in the worktree prints warning: needs-state copy <path> is not git-ignored in the worktree .... A link error (a (link) path missing in the repo) or a setup that does not exit 0 refuses the dispatch (exit 6, rule setup, the fix naming the path or command and the output tail): no dispatched event is recorded and no worker starts. A non-empty escaped prints warning: needs-state link <path> holds links into the main checkout (<n>: ...) on the dispatch’s stderr, since the unit’s gates would import the main checkout’s copies (use needs-state: <path> (install) instead); with worktree.strict_links true (default false) it also refuses the dispatch (rule setup, the event still recorded with escaped and a note saying it was refused, and setup does not run). After the install and a successful setup (and even when nothing is configured), a worktree with a package.json but no node_modules or .pnp.cjs of its own is checked for an ancestor node_modules up to the main checkout root (never above it) that Node’s parent lookup would resolve packages from, the main checkout’s (issue #802): it is recorded as inherited (an absolute path) and prints warning: worktree <wt> has a package.json but no node_modules of its own, so Node resolves packages from <path> ...; with worktree.strict_links true it also refuses the dispatch (rule setup, the event still recorded with inherited and a note saying it was refused). Then a worktree whose own real node_modules (a copied one, say) holds links into the main checkout has those entries recorded in escaped (the event is recorded even when nothing is configured) and prints warning: worktree node_modules holds links into the main checkout ...; with worktree.strict_links true it also refuses the dispatch (rule setup) (issue #819). Besides the worktree’s own node_modules, every real (never linked) node_modules one or two levels down (<wt>/<a>/node_modules, <wt>/<a>//node_modules, a workspace package’s own, where npm and pnpm also put workspace links) is scanned the same way and reported as <rel>/node_modules/<entry>; the walk never follows a link and skips .git, .flywheel and node_modules (issue #829). flywheel validate with a workdir (a run --worktree unit’s recorded worktree included) re-checks inherited and escaping modules after the (install) re-run and before any gate: a finding prints the same warnings and records a worktree_setup event (inherited, escaped, a note starting validate: ); with worktree.strict_links true the note starts validate: refused: and validate refuses with rule setup (exit 6) before any gate runs. Nothing found records nothing (issue #829).

`staged`

Written by: the CLI only, via flywheel validate <task> (issue #781), before the gates and before the tree is hashed, when the effective brief’s stage: <from> -> <to> lines (e.g. stage: staging/claude/ -> .claude/) staged at least one file. Each regular file under <from> in the workdir (symlinks skipped; a missing <from> stages nothing) is copied to the same relative path under <to>, atomically, unless the destination already holds the same bytes. A correction’s stage lines union with the base brief’s. A stage line with no ->, an empty side, an absolute path or a .. segment, the same path twice, one side inside the other, or a <from> Claude Code protects is refused before any gate (exit 6, rule stage) and is a flywheel lint problem; a valid line whose <from> the unit owns nothing under is a lint warning. At dispatch flywheel run seeds each owned staging FILE whose staging copy is missing from its existing destination (issue #898), recorded as seeded on the dispatched event.
Carries: task, attempt, workdir (as on validated), staged (one entry per staged file, sorted by from: from and to repo-relative paths, sha256 the content’s hex SHA-256, and copied, false when the destination already held the bytes). Validate requires a non-empty staged.
Effect: no status change. The pass’s tree includes the destinations, and the owns check treats each destination as owned when its from is owned (a destination whose source is not owned stays outside owns:); the pass’s owns_checked carries the same staged. Ownership persists: every later pass also treats each destination recorded on the task’s earlier staged and unstaged events (latest record per to wins) as owned through its owned from, so it stays owned after flywheel unstage removed the source. validate prints <task> note: staging copies remain (<n> files under <dirs>): run flywheel unstage <task> before landing when the pass staged a file (a reading, never a failure). validate --group does not apply stage lines.

`unstaged`

Written by: the CLI only, via flywheel unstage <task> [--workdir DIR] (issue #781), after removing the source files of the task’s latest staged event (and the now-empty directories under each stage line’s <from>, <from> included); each destination is kept. Every source must still hold its recorded sha256 and every destination the same bytes, or it refuses before removing anything (exit 6, rule stage: “staged content changed since validate measured it: re-run flywheel validate”). No staged event is an error (exit 1). A second call with every source already gone and an unstaged event newer than the latest staged records nothing.
Carries: task, workdir (as on validated), staged (the files whose sources it removed, as on staged). Validate requires a non-empty staged.
Effect: no status change. The tree changed, so the lead validates again before inspect and land (validate -> unstage -> validate -> inspect -> land); that pass keeps the destinations owned.

`started`

Written by: the CLI, from the run’s first parsed start observation.
Carries: task, session (the emitted OpenCode session id). No model — that rides only on dispatched and finished.
Effect: Derive sets status running. Verify’s T4 (ruleT4) treats any session that ever wrote a task’s started, finished, dispatched, report or worker_plan event as a worker session — one an inspected event must never reuse.

`worker_plan`

Written by: the CLI, the first time the run’s text output has a line that, after stripping leading whitespace, list/quote markers (-, , +, >, #) and markdown emphasis (, _, ), starts with PLAN ` (issue #284).
Carries: task, attempt (set on every worker_plan since issue #592; older events have none and are matched by their path), path (.flywheel/runs/<id>.<attempt>.plan.md), sha256 of that file. The recorded plan is the text from that matched line onward, with leading whitespace and list markers stripped but emphasis markers preserved.
Carried over on --resume (issue #592): a resumed session is the same conversation and never repeats its first message, so when an attempt of the session being resumed already checked in, the CLI appends, before the stream starts, a worker_plan for the new attempt with the latest such plan’s path and sha256 (the plan file is not copied), attempt the new attempt and note “carried over from (resumed session <first 8 chars of the session>)".
Effect: no status change. Its presence before step 20 is what a missing no-plan event certifies.

`no-plan`

Written by: the CLI, at most once per attempt, at the 20th completed step, or at finish (a normal or stalled end after at least one completed step, before that finished event), only if neither a PLAN -prefixed line (as detected above) nor an earlier no-plan has appeared (issue #65, #284, #533). Not written on a --resume whose session already checked in: that attempt carries the session’s worker_plan over (issue #592). Ends with no worker output (silent, start failed) write none. Each one is followed by a no-plan signal.
Carries: task, attempt; the finish-time one also carries note (“finished after N steps with no PLAN check-in”).
Effect: Derive ignores it for status exactly like worker_plan; it never changes rc or reason — it is a flag, not a verdict.

`off-course`

Written by: the CLI, at most once per attempt, the moment a read, grep or glob tool call (offCourseTools) names the 5th distinct path outside the worktree — library source a worker reached for instead of go doc (issue #72, #154). The finish-time one also fires when the attempt wrote outside the worktree, and the finished note then says “wrote outside the worktree: …” (issue #359); a write under the worker session’s own scratchpad (claude/<project>/<session>/scratchpad/) is exempt and counts toward neither (#906).
Carries: task, attempt, note (the offending paths, in the order first seen, comma-joined and capped at 200 characters by clipNote).
Effect: Derive has no case for it, so — like worker_plan and no-plan — it never touches Status; it is a record for a human (or a future gauge) to notice, not a verdict.

`finished`

Written by: the CLI, exactly once per attempt, on every code path out of a run (clean stop, silent, stalled, provider error, output cap, start failure).
Carries: task, session, attempt, model (every finished event carries the model, issue #134), rc, reason (stop clean; length output-capped; error — a provider error, signal provider-error; flywheel run waits a fixed 2 minutes and resumes the same session with the continue delta .flywheel/briefs/<task>.error-<n>.txt, at most limits.provider_error_retries times (default 1; 0 disables), never when the task recorded no worker session (the resume would be refused); the retry’s dispatched event is its record (its brief the per-attempt snapshot of that delta), no other event kind, issue #830; rate-limited — the provider’s rate or usage limit cut the run off (a claude 429 or limit message); the note names limit resets <time>, no signal is recorded, the breaker does not count it, and flywheel run resumes the same session after the reset (limits.rate_limit_retries, limits.rate_limit_max_wait), issue #380. A rate-limited finish whose reset parses also carries reset_at (RFC 3339): the limit belongs to the subscription, so until then the model is paused — flywheel run refuses a fresh attempt on it (exit 6, rule rate-limit), while a --resume waits for the reset plus a minute before dispatching (bounded by limits.rate_limit_max_wait; a wait beyond it is refused, exit 6, rule rate-limit, naming the reset), and a --resume with no delta file after a rate-limited or abandoned-job finish uses the automatic continue delta (the next unused <task>.limit-<n>.txt), issue #472, flywheel next HOLDs with rate-limit: <model> paused until <time>, and the floor shows the unit rate-limited until HH:MM and an andon entry model/<model> paused until HH:MM; a later clean stop finish on the model ends the pause early, issue #383. A claude stream’s rate_limit_event lines carry the exact reset epoch and the share of the window used: a rate-limited finish takes reset_at from the latest one (else the parsed message), and EVERY finish that saw one carries limit_utilization (0..1), limit_reset_at (RFC 3339) and limit_window (e.g. five_hour). Pause before the wall: when a model’s LATEST finish has limit_utilization at or above limits.rate_limit_pause_at (default 0.95; negative disables) and limit_reset_at is ahead, the model is paused until then exactly as for a hit limit, the refusal naming (<n>% of the <window> window used) and the andon paused until HH:MM (<n>% used); a later finish below the threshold, or the reset passing, releases it, issue #417. A pause whose window is account-wide (five_hour, seven_day) holds every model dispatched through the same adapter, named (<reporter> reported <n>% of the <window> window, account-wide), until the reset or a later clean stop of any model on that adapter; a model-scoped window (seven_day_opus, …) holds only its model, issue #658; abandoned-job — a clean stop that left a background shell it started (claude Bash run_in_background, whose tool_result reports running in background with ID: <id> or agentId: <id>) never collected — no later tool call’s input names that id (BashOutput, KillShell, a Read of its output file, …) — so the job died with the session; the note names background job never collected: <cmd>, no signal is recorded, the floor shows the unit abandoned-job on the andon, and flywheel run resumes the same session once, immediately, with .flywheel/briefs/<task>.job-1.txt telling the worker to run the job in the foreground; a second abandoned-job is returned as is, issue #390; suspended — a flywheel suspend --stop stopped the worker at a lease tick; the note is stopped by suspend at <ts>, the session is kept and flywheel resume continues it (see suspended), issue #572; start-failed; silent; stalled — the run-file gap watchdog killed a run that had started but stopped producing lines for the worker’s stall timeout, issue #158, or whose stream’s tool_progress heartbeat showed one tool call open for the worker’s tool_stall_timeout (whole seconds, default 1800; the heartbeats keep the run file growing, so the gap watchdog never fires), with the note tool call <tool> open <elapsed>s (tool_stall_timeout <N>s) first, issue #917), note, steps, tokens, cost, peak_reasoning (the largest single-step reasoning figure seen in the run, omitted from the line when 0, issue #156), sha256 (of the whole run file), wrote (the attempt’s distinct edit/write paths, sorted, at most 50, omitted when the attempt made no edits, issue #163; it also holds the worktree-relative paths the worker changed in the tree since dispatch — changed at finish and not dirty at dispatch, or with a sha that differs from the dispatch baseline, .flywheel/ excluded — so MultiEdit, NotebookEdit and shell writes count, issue #463), wrote_from_tree (the subset of wrote that came only from the tree, not from a tool observation; omitted when empty, issue #463), denied_writes (the worktree-relative, slash-separated, sorted, distinct paths whose Write, Edit, MultiEdit or NotebookEdit the harness denied during the attempt, from the claude result line’s permission_denials, whatever the finish reason; omitted when none, issue #757), commands (the shell commands the worker ran, in order, at most 100, each clipped to 300 characters; omitted when it ran none, issue #365), gates_unrun (on a stop finish only: the ids 1, 2, .. of the attempt’s effective gate: lines that no recorded command contains, whitespace collapsed, or contains the gate’s first 40 characters; matched against each command’s full text, not the clipped commands entry, so a gate chained after character 300 still ran, issue #865; live gates are not checked; omitted when empty, issue #365), gates_stale (on a stop finish only: the ids of the gates a recorded command ran before the worker’s last Write, Edit or delete and none ran after it, so disjoint from gates_unrun; a write made through the shell is not seen, and a write only under .flywheel/ does not count; omitted when empty, issue #948), skills_loaded (on every finish of a claude attempt: the skills its stream loaded through the Skill tool, the call’s input.skill, in order, each once; omitted when none; Validate accepts it only on a finished event, issue #695), commit (on a stop finish of a --worktree unit only, issue #391, a --resume or --delta that continues in the task worktree counting as --worktree, issue #894: workers never run git write commands, so flywheel commits the attempt itself on fw/<task> — built in a temporary index from HEAD plus every changed path inside the attempt’s owns — the resolved brief’s owns plus this dispatch’s own prompt’s owns: lines, so a correction delta that widens owns is committed (issue #477), the same set validate measures; checkpoints use it too — flywheel’s own bookkeeping excluded, message <task> <attempt> with a Flywheel-Task: <task> trailer, author and committer flywheel <flywheel@localhost>, the branch moved by compare-and-swap, and the worktree’s index refreshed for the committed paths; omitted when nothing owned changed. Changed paths outside owns stay uncommitted, are named on the note as left uncommitted (outside owns): <paths>, printed as `warning: : attempt commit left changed path(s) uncommitted (outside owns): ` and recorded as `uncommitted`; a commit failure never fails the run and is noted as `attempt commit failed: `).
uncommitted (issue #477): the changed paths the attempt commit left out. Only a finished or a recommitted event may carry it. The task’s latest finished or recommitted event, in log order, supplies the list (a recommit with none clears it; a later finished of a new attempt supersedes a recommit). While any of its paths is still changed (dirty or untracked) in the tree validate measures, the owns check fails with the single outside entry left uncommitted by the attempt commit: <paths> (replacing those bare paths, and even when a baseline or claim would excuse them): a PR cut from fw/<task> would lack them. To clear it, amend owns to cover the paths (flywheel log --kind amended), then run flywheel worktree commit <task> --session S (issue #897), never a hand-made git commit.
reason is the provider’s own finish reason, passed through verbatim by the adapter rather than normalized by flywheel; stop is the only clean value. Other values seen in practice: length, error, start-failed, silent, stalled (above) and unknown — unknown meaning the provider reported no reason the adapter recognised, which is information, not a bug (issue #176).
Effect: Derive sets status finished. stageOf (factory.go) then reads reason: stop (or empty) is stage finished; length is stage cut-off; anything else, stalled included, is stage failed — both cut-off and failed units reach the andon and flywheel status’s Attention list (issue #131). peak_reasoning changes no stage: the factory floor (render.go) prints it next to a capped unit’s state, and a length finish’s own progress line names it in the hint suggesting smaller steps (run.go).
classifyRun (factory.go) reads wrote alongside reason: a done attempt with a non-stop reason and a non-empty wrote classifies run state failed-dirty instead of plain failed (or capped, when reason is length) — a failed attempt that left files behind, needing a human decision (revert, resume, or re-dispatch) that a clean failure or a cut-off run that wrote nothing does not (issue #163). failed-dirty reaches the andon and is dead, exactly as failed is.
A stop finish is not automatically done (issue #364): when the claude result line carried permission_denials, note adds permission denied: <tool [path], ...> and a permission-denied signal follows the finished event (run state blocked). The andon is raised live when the stream reports the denial as it happens (issue #526): claude’s user line whose tool_result has is_error true and text containing `requested permissions to use ` appends the attempt's one `permission-denied` signal at once, with `note` `permission denied (live): `, and prints `andon: permission-denied (live)`; the worker is not stopped, and no second signal is appended at finish. A Bash denial names the deny pattern and the command segment it matched, `Bash: ()`, or `Bash: unattributed ()` when no pattern matches (issue #497). Otherwise, when `wrote` is empty, no signal is recorded (an untriaged signal blocks landing, and some units legitimately write nothing): the factory view derives the floor state **no-writes** from the `finished` event alone. An attempt that resumed the same agent session as an earlier attempt that wrote files is not no-writes: it wraps up that work (issue #592). Both states apply only while the unit is awaiting judgement (status `finished`); once passed, rejected or landed it shows done. Both reach the andon; no-writes blocks nothing.
A non-empty gates_unrun adds gates never run by the worker: <ids> to note and prints a <task> <attempt> never ran gate(s) <ids> progress line; no signal is recorded (the lead re-measures every gate). flywheel validate prints ` note: the worker never ran gate(s) itself; its report's claims about them are unmeasured` after the gate lines (issue #365). A non-empty `gates_stale` likewise adds `gates not rerun after the worker's last write: `, prints ` did not rerun gate(s) after its last write`, records no signal, and `flywheel validate` prints ` note: the worker did not rerun gate(s) after its last write; its report's claims about them are unmeasured` (issue #948).
Workers never write git (issue #423). The guarantee is two layers that do not depend on PATH: denied at dispatch — the claude adapter’s default --disallowedTools denies git commit, push, stash, reset, checkout, rebase, merge, add, rm, mv, restore, update-index, apply, tag, branch (so git branch --show-current too; use git rev-parse --abbrev-ref HEAD), switch, cherry-pick, revert, am, worktree, clean, notes, replace, update-ref and gc (stash and worktree for their write forms only: git stash list/show and git worktree list stay allowed, matching the git guard) — and detected after each attempt — on every exit path, before flywheel’s own attempt commit (so its index refresh is never charged to the worker), flywheel compares the worktree’s HEAD, branch, stash, index (git diff --cached --name-only) and tags with the state captured at dispatch, and note names what changed: HEAD: <old> -> <new>, branch: <old> -> <new>, stash, index: staged <paths>, index: unstaged <paths>, tags: +<name>/tags: -<name>, each followed by who it is charged to and why: (the worker's: <why>) or (changed by another process: <why>) (issue #621). git-write blames a worker only for git writes the worker could have made. A staged path, an unstaged path while HEAD stayed put, a tag added or moved onto a local-only commit, or a deleted tag is a git-write signal whatever the guard logged (issue #423). A HEAD or stash move, or a branch change that moved HEAD, is one only when the git guard logged a write the worker tried (issue #361; otherwise another process moved it and the note says so). What only another process makes never signals, even beside a logged write: a tag on a commit a remote-tracking ref contains (a fetch, shared by every worktree; the note says fetched, issues #442, #621), the worktree’s branch renamed with HEAD unchanged, and an unstaged path when HEAD moved. Other branches and refs/remotes/* are not compared. The guard logs refused writes only: the read forms of git config (--get*, --list/-l, get, list, a single key with no value) pass it (issue #621). Paths the worker staged are unstaged by flywheel (git reset -q -- <paths>, content kept in the working tree) and the note adds `index restored: `. The PATH git guard is defence in depth, not the guarantee: a shell that puts the real `git` first on PATH never reaches it.
checkpoint (issue #422): on an unclean finish (error, rate-limited, stalled, silent, abandoned-job, length, suspended) of an attempt that wrote files, the sha of the snapshot of its changed owned paths at refs/flywheel/checkpoints/<task>/<attempt> (see recovered below). Only a finished event may carry it.
Workers load no MCP servers unless the worker config lists them (issue #425). Every claude dispatch passes --strict-mcp-config with --mcp-config set to the worker’s mcp value (the Claude CLI’s {"mcpServers": {...}} shape, compacted), or to the empty set {"mcpServers":{}} when mcp is unset — so the user-level MCP servers (mail, calendar, drive, trackers, chat, plugins) that --setting-sources user would still load never reach a worker. The review agent sets no mcp and gets the empty set. flywheel rejects a config whose mcp is not a JSON object with an mcpServers object.
A claude worker’s permission_mode (issue #526) is its --permission-mode: acceptEdits (the default when unset), bypassPermissions, default, plan or dontAsk; any other value, or the key on a non-claude worker, is a config error; set it with flywheel config set workers.<name>.permission_mode bypassPermissions. --disallowedTools is passed under every mode, bypassPermissions included (Claude Code enforces deny rules even when bypassing), so the git-write deny list still holds. flywheel lint warns when a brief asks for web research (WebSearch, WebFetch, “web search”, “search the web”, “web fetch”) and the default worker is a claude worker whose allowed_tools lack WebSearch/WebFetch and whose mode is not bypassPermissions.
A claude worker’s --max-turns (issue #459) is its max_turns, else limits.max_turns, else 200; a negative value, or a worker max_turns on a non-claude worker, is a config error; set it with flywheel config set workers.<name>.max_turns N (0 clears it).

`report`

Written by: the CLI, only when the attempt’s reason is stop and its last text was non-empty.
Carries: task, path (.flywheel/runs/<id>.<attempt>.report.md), sha256.
Effect: no status change. Any other finish reason keeps the last reply as .flywheel/runs/<id>.<attempt>.partial.md on disk instead, and appends no report event — so a cut-off or failed run can never be mistaken for a done one.

`reviewed`

Written by: flywheel review <task> --verdict pass|correct|reject --session S [--model M], from an isolated copy of the tree; by the review agent, flywheel review <task> --agent --session S [--base REF] [--worker NAME] [--round N] (issue #389); flywheel log --kind reviewed remains valid input. The agent’s diff and changed paths start from one base (issue #789): --base REF (a ref that does not resolve to a commit is inconclusive, exit 8, nothing recorded), else the unit’s dispatch base, else a lead-built unit’s planned base (the HEAD its planned event recorded), else the working tree’s HEAD. --base without --agent (a hand verdict) is a usage error, exit 2.
Enforced: rule review-empty (exit 6, issue #789): when that base gives no changed paths, the review agent and the panel (--panel, one refusal before any member) refuse before writing a prompt, running a reviewer or appending any event; the fix names the base used and the remedy, flywheel review <task> --agent --base <the commit before the unit> or --workdir <the unit's worktree>. The --fix loop exits 6 on it too. flywheel’s own files (.flywheel/, flywheel.md) are not the unit’s change, so they never make a diff non-empty (issue #793).
Carries: task, verdict (pass, correct, reject, or crashed — a panel member whose run failed twice, only with a category, issue #469 — enforced by Validate), session, model (the reviewer’s identity), tree, note, persona (reviewer). The review agent’s event also carries adapter (the agent that reviewed; a verdict passed in by hand names none, and the next agent round is one more than the task’s reviewed events that do), verdict correct when any finding is a blocker or major and pass otherwise, the note <n> finding(s): blocker, <m> major, <k> minor, and tokens and cost: what every reviewer run of the round spent (the first run and a retry after a refused answer), summed from the stream the way a worker’s are (issue #459), and base, the full commit the reviewed diff started from (omitted when it was the working tree’s HEAD, issue #789). Its review_finding events carry none, so the spend counts once; a hand verdict carries neither. flywheel cost, limits.unit_cost_usd, limits.budget and the floor count a reviewed event with cost or tokens as spend.
Effect: Derive maps pass→passed, correct→needs-correction, reject→rejected, except that a reviewed event written by the review agent (persona reviewer with an adapter) never sets passed — its pass leaves the status unchanged, because the agent reads and the gauges measure: only validate+inspect (or a hand-recorded review, which re-runs the gates) pass a unit (issue #389). Unlike inspected, verify’s T8 does not restrict who may write a reviewed event — inspected (§4) is the path every current command actually takes.

`review_finding`

Written by: the review agent only, flywheel review <task> --agent --session S (issue #389). The agent (the staffing reviewer role’s adapter and model, else the default worker, or --worker) runs in the unit’s worktree under the git guard with a read-only tool policy (claude: Read, Grep, Glob, git diff/log/show, go vet/test, read-only gh issue view/gh pr view, the unit’s own gate commands as Bash(<program> <first argument>:*) patterns (a bare program such as node never), and any review.allowed_tools patterns (issue #469); Edit, Write and NotebookEdit refused), on a prompt holding its instructions, the unit’s brief followed by every correction delta dispatched since the unit’s latest fresh attempt (or its latest planned/amended brief, when later), in order (issue #458; the deltas share 48 KB, the latest always whole and earlier ones replaced oldest first by a line naming their path), the attempt’s gate readings and the diff from the dispatch base (capped at 200 KB), kept at .flywheel/reviews/<task>.<round>.prompt.md beside its stream .flywheel/reviews/<task>.<round>.jsonl. The findings contract is checked, not trusted: an answer whose file does not exist (and is not a changed path), whose line is not 0 or a real line, with an empty claim or scenario, or with more than 3 nits is refused, and the agent runs once more, fresh, into <task>.<round>b.jsonl; a second refusal records nothing and flywheel review --agent exits 1 naming both transcripts (their spend is in the transcripts only; a panel member records it on its crashed event). flywheel review calibrate --cases FILE --session S runs the same agent over a sample of past PR states in temporary worktrees and synthetic ledgers (never this ledger) and reports its recall against the case file (docs/calibration/README.md).
Carries: task, attempt (the unit’s latest), session (the reviewer, never a worker session of the task: refused T4), model, tree, severity (blocker, major, minor or nit), category, title (the claim), observed (the failure scenario), ask (the fix hint), path (the file), line_no (the file line; line is already the product line), and finding, a stable id <task>-r<round>-<n>. Validate requires the task, session, a severity in the set, the title and the path.
Effect: no status change. Every finding and the round’s closing reviewed event go out in one AppendEvents write; an answer without a parsable {"findings": [...]} block records nothing.
Open and closed (OpenFindings, issue #389): a finding opens when it is raised. It closes only on the framework’s evidence, never on an agent’s word: a LATER agent review round (a reviewed event with persona reviewer and an adapter) completes without re-reporting it — same path and the same claim, case- and space-insensitive; a re-report is still open under its new id — or the lead dismisses it (a finding_response below). A worker’s fixed never closes a finding by itself. blocker and major findings block the unit.

`finding_response`

Written by: flywheel review <task> --agent --fix (ReviewLoop, issue #389) after each correction, one per open blocking finding it sent — the worker’s answer parsed from the attempt’s report (.flywheel/runs/<task>.<attempt>.report.md), under the worker’s session; or, for an id the report does not answer, disputed with note missing: the worker gave no answer, so the next round re-reviews it anyway. Responses are recorded only for the findings sent: a finding outside the unit’s effective owns is never sent and never gets one (issue #458). And by the lead, flywheel review <task> --dismiss <id> --session S --note WHY: disputed with note dismissed: WHY; a worker session of the task is refused (T4, exit 6), and the id must be a finding the task’s reviewer raised.
Carries: task, attempt (the correction), session, finding (the id it answers), verdict fixed or disputed, and note (the worker’s evidence or reason). Validate requires the task, the finding and a verdict in the set.
Effect: no status change. Only a lead dismissal — disputed, note starting dismissed:, from a non-worker session — closes a finding, and with it any later re-report of the same file and claim.
The loop: review; no open blocking finding → verdict pass (exit 0). Else flywheel writes the findings delta .flywheel/briefs/<task>.review-<round>.txt — the effective brief’s owns:, needs: and every gate: line, # TASK: fix the review findings, one block per open blocking finding (FINDING <id> [<severity>] <file>:<line> — <claim>, scenario: …, fix hint: …), then the contract: fix each finding, change nothing unrelated, re-run every gate, and end the report with one line per finding, FINDING <id>: fixed <evidence> or FINDING <id>: disputed <reason> — resumes the worker’s session on it, records the answers and reviews again. After --rounds reviews (default 3) the open blocking findings are printed and the command exits 1. Without --fix-worker the corrections go to the worker that built the unit: the last dispatched attempt’s worker while it is still configured, else the first configured worker with its adapter and model, else the default worker with one stderr line saying so (issue #469). A session never crosses adapters: flywheel run --resume onto a worker whose adapter differs from the last attempt’s is refused (exit 6, rule resume) before dispatch (only a dispatch_refused event is appended), and the fix loop instead dispatches such a correction as a fresh session that reads the delta.
The thread (issue #389): .flywheel/reviews/<task>.md is GENERATED from the event log (RenderReviewThread) after every agent review round, every recorded finding_response and every dismissal — never on GitHub. It holds one `## Round — , , , tree ` section per round listing its findings, each with its current status (`open`, `closed in round `, `re-reported in round as `, or `dismissed by : `) and the answers under it (` : fixed|disputed — `), then `## Open blocking findings`. It carries a `` marker; a file there without it is never overwritten, and a failed write is only a progress warning.
Enforced: flywheel inspect --verdict pass is refused (rule review, exit 6) while the task has an open blocking finding, and flywheel verify fails rule R1 for an inspected pass recorded while one was open (§2). flywheel floor shows such a unit as review-open (<count>) on the andon, and flywheel stats reports a review block. Open blocking findings outside the effective brief’s owns show as needs-owner (<count>) instead, and review-open counts only those inside (issue #458).
The review panel (issue #420): flywheel review <task> --agent --panel --session S [--round N] [--fix [--rounds N] [--fix-worker NAME] [--worktree]] runs the review agent once per member of review.panel, sequentially, each a persona owning one dimension. A member’s reviewer is its adapter/model in review.panel, else its worker, else staffing.reviewer, else the default worker; --worker is refused, and before the panel runs one stderr line per member names it, panel <dimension>: <adapter>/<model> (from <source>) (issue #469). The personas are embedded (internal/flywheel/review_personas/<dimension>.md): correctness, security, tests, errors (error handling and resources), cross-os, contract (flags, event kinds, exit codes, config keys, backwards compatibility) and docs. A member’s prompt is review_prompt.md plus its persona file, kept at .flywheel/reviews/<task>.<round>.<dimension>.prompt.md. Every finding in its answer must carry its dimension as category; one outside it refuses the answer (the same refuse-and-retry-once path). All members of one run share a round; their findings are <task>-r<round>-<dimension>-<n>. A member’s reviewed event keeps persona reviewer (so status derivation and every agent-review check are unchanged) and records its dimension in category; Validate refuses a reviewed category that is not a persona, and accepts a persona reviewer:<dimension> only for a known one. A member’s round closes only its own dimension’s findings; a general round closes all. Rounds are counted with a panel run as one round until a dimension repeats. With --fix each loop round is a whole panel. The command prints the findings (or, with --fix, the open blocking ones), then the verdict matrix, and exits 0 when every dimension is pass, else 1 (6 on a refusal, 2 on usage).
A crashed member (issue #469): a member whose run fails (the reviewer exits non-zero, its stream breaks, or its answer is refused twice) runs once more; failing again, the panel appends one reviewed event with verdict crashed, persona reviewer, the dimension in category, the reviewed tree, the cause (the stream’s error result, else the stderr tail; about 300 bytes) in note, and the tokens and cost its two failed runs spent (issue #459), and goes on with the next member. Validate accepts crashed only with a category. It names no adapter, so it closes no finding, counts as no round and changes no status. Any other error (persona, config, ledger, rule) still stops the panel. With --fix, a round with a crash still corrects the open blocking findings inside owns; with none open it never passes: it reviews again while rounds remain, then ends with verdict incomplete naming the crashed dimensions.
The verdict matrix (VerdictMatrix): per panel dimension, the verdict of the latest agent or crashed reviewed event of that dimension on the tree — pass, correct or crashed (never pass) — else missing; a correct whose blocking findings are all dismissed counts as pass. The thread groups a panel round as one ## Round <n> — review panel section with one line per member and its findings under a ### <dimension> heading, then ## Panel verdict matrix — tree <sha7>. When review.panel is configured, the floor shows each unit’s matrix after its run state as panel <cells>, one cell per dimension in panel order on the unit’s measured tree (its latest owns_checked or validated reading): ✓ pass, ✗ correct (an open blocking finding), · not reviewed on that tree. The cells’ room comes out of MODEL, then SESSION; when they cannot give it, the cells are dropped and the task id is never cut. --json carries them as a unit’s panel.
Numbers: flywheel stats breaks the review down per persona (review.by_persona: persona, level unit or group, reviews, findings, by_severity, and how the findings were answered — fixed or disputed by the worker’s latest finding_response, dismissed by a lead) and per level (review.by_level: unit, group, and release when a release audit ran — rounds, rounds not pass, findings, blocking; a release audit’s findings are its failed checks). A finding counts for a panel persona only when its id is <task>-r<n>-<dimension>-; others are general. flywheel review calibrate --panel [dims] (bare: the configured review.panel) calibrates each persona over the same sampled PR states (same seed) and reports, per persona, the PR states it reviewed, hits, misses, extra findings and recall, then the panel, which hits a case when any persona hit it; the report’s **Total: ...** line is the panel’s. A persona whose review fails is skipped for that PR state alone.
Config: review.panel — the members, [{"persona": ..., "worker"|"adapter"+"model": ...}]; config get/set review.panel reads and writes a comma-separated persona list (a member keeps its reviewer). Unset, the panel is correctness, tests, errors, contract, docs; security and cross-os are opt-in. review.required (default false) makes a complete panel a condition of every pass. review.panel_min_lines (default 0, off; config set refuses a negative or non-integer value) scopes a small unit’s configured panel to one reviewer (issue #459): see panel_scoped.
Enforced: when the task has been reviewed by the panel, or review.required is set, flywheel inspect --verdict pass is refused (rule panel, exit 6) unless every configured dimension is pass on the tree being inspected, naming each <dimension>=missing|correct and the command; and flywheel verify fails rule P1 for such a pass (§2). “Configured” means panelFor below.

`panel_scoped`

Written by: the CLI only, via flywheel review <task> --agent --panel with the configured panel (no explicit member list) and review.panel_min_lines N > 0 (issue #459). Before any member runs, it counts the unit’s changed lines on the tree it is about to review: added plus deleted lines of git diff --numstat <base> -- <paths> (the unit’s dispatch base and changed paths, as the review diff uses; a binary file counts 0) plus the lines of each new untracked file among those paths; flywheel’s own files (flywheel.md, .flywheel/) are not counted (issue #729). Below N, only one member runs, the configured correctness member (else the first), and this event is appended first; the command prints <task> review panel: <n> changed lines < review.panel_min_lines <N>; one reviewer: <persona> and a one-line verdict matrix. At or above N, or with N = 0, the full panel runs and nothing is recorded.
Carries: task, tree (the tree the member reviews), panel (the one persona), session, and note (<n> changed lines < review.panel_min_lines <N>). Refused without task, tree or a non-empty panel.
panelFor(events, task, tree, configured): the panel of the latest panel_scoped event of the task on exactly tree, else the configured dimensions. Inspect’s rule panel, verify’s P1 (over the events before each pass, on its tree), flywheel recover and the floor’s panel cells all use it, so they agree from the ledger alone and never re-measure. A tree that changed after a scoped review (a fix round) has no record and needs the full panel, unless the next panel run measures it small and scopes it again.

`group_reviewed`

Written by: the CLI only, via flywheel review --group <goal|tasks:a,b> --agent --session S [--base REF] [--worker NAME] (issue #420): a group of units validated together. A group is a goal id (every task planned with that goal_id) or an explicit tasks:<a>,,...; its own records carry task group:<id> (the goal id, or the list with : and , turned into -: tasks:a,b is group:tasks-a-b), which Validate accepts wherever a task id is required.
The integration tree: a detached git worktree add of the base (default main) in a temp dir, then each member’s work merged in member order with git merge --no-ff --no-edit as flywheel’s identity — its task branch fw/<task> when it exists, else the commit of its latest finished event. A member with neither is reported as missing and skipped; a merge that conflicts is aborted, its paths recorded, and the next member continues. The tree is removed afterwards.
Group gates: each review.group_gates command runs in the integration tree like a gate (bash -c, captured output) and is recorded as a validated event with task group:<id> and gate g<n>.
The integration reviewer: the embedded integration persona (never a panel dimension) reviews the combined diff base..tree, with a prompt section listing each member and its effective owns, the missing members, the conflicts and the gate readings; its prompt and stream are .flywheel/reviews/group-<id>.<round>.prompt.md and .jsonl. It reports only defects that involve more than one unit’s change or the merge itself (merge seams, duplicated logic, conflicting assumptions, contract drift between units); every finding must carry category integration (the same refuse-and-retry-once path as the review agent).
Routing: each finding becomes a review_finding (persona reviewer:integration, category integration, reason the group task, id group:<id>-r<round>-<n>) on the first member whose effective owns contain its file, else on group:<id>. Each conflicting path becomes a blocker on the member whose merge conflicted.
Carries: task (group:<id>), verdict (correct when any blocker or major finding or any failed group gate, else pass), tree (the integration tree), commit (its HEAD), session, model, adapter, persona reviewer:integration, note (members ...; missing ...; conflicts ...; gates g1=<rc> ...; <n> finding(s)). The gate readings, the findings and this event are one append. A session that is a worker session of a member is refused (T4).
Effect: no status change. An integration finding is closed only by a later review of the same group (which re-reports a defect still present under a new id) or by a lead’s dismissal (flywheel review <task> --dismiss <id>); a unit’s own review never closes one. The thread is .flywheel/reviews/group-<id>.md (same marker rule as a task’s thread), and each member a finding was routed to has its own thread refreshed.
Config: review.group_gates (default none); config get/set review.group_gates reads and writes the commands separated by ;; (set also splits on newlines; an empty value clears them). The integration reviewer may run the members’ gate commands and the group gates, as a unit’s reviewer runs its unit’s. review.allowed_tools (default none) adds claude --allowedTools patterns to every reviewer’s read-only policy; config get/set review.allowed_tools uses the same separators, and an empty entry is refused.
Enforced: flywheel land refuses (rule group, below).
State: a group task is not a unit. Derive leaves group:<id> out of tasks (and counts) and lists it under groups in .flywheel/state.json: id, task, members (from the latest group_reviewed note), verdict (the latest), rounds, open (its open blocking integration findings, on its members or on the group task) and updated_at; groups is omitted when there is none. The floor (flywheel factory, text and --json) shows a groups (<n>) section, one row per group — id, verdict, open <n>, members — and an andon entry group:<id> group-open (<n>) while one is open.
Exit: 0 on pass, 1 on correct or an error, 6 on a refusal, 2 on usage.

`blocked`

Written by: the controller (flywheel controller), when a task’s needs: target is scrapped.
Carries: task, reason (names the needs target).
Effect: Derive sets status blocked.

`lost`

Written by: flywheel controller, flywheel run (before its owns and exclusive collision checks) and flywheel next (before it recommends), for the current attempt of a dispatched or running task that is abandoned (issue #402): its lease has expired, or no lease exists and its run file .flywheel/runs/<task>.<attempt>.jsonl (with no run file, its dispatched event) is older than limits.lost_after (a Go duration, default 24h). A live lease is never lost, and a lost attempt is not in flight, so it never blocks a dispatch. Until then flywheel run refuses any dispatch of a task whose attempt is still dispatched or running, fresh, --delta, --increment or --resume alike (exit 6, rule in-flight, issue #522), before recording anything.
Carries: task, attempt, reason (lease-expired or idle), note (the evidence: lease expired at <time>, no live lease; run file idle since <time>, or no live lease; no run file; dispatched at <time>).
Effect: a stale-kind event, ignored unless its attempt matches the task’s current one; otherwise Derive sets status lost.

`withdrawn`

Written by: the lead, via flywheel log --task <id> --kind withdrawn --note "<why>" (issue #479), to take a plan back — typically one planned under an id another flywheel root already claimed. --note is required (exit 2 without it). flywheel log refuses it (exit 6, rule W1) while the task’s current attempt is dispatched or running; the same check holds for a --json line.
Carries: task, note (why), optionally session.
Effect: Derive sets status withdrawn (same-instant rank after blocked, before lost). It is terminal like landed and lost: station scrap, floor stage withdrawn, never offered by flywheel next, and it holds no owns or exclusive claims. A later planned event revives the id.
Verify: rule W1 (section 2).

`rebased`

Written by: the CLI only: flywheel rebase <task> [--onto REF] (issue #414), or flywheel log --kind rebased for a hand rebase (below). The rebase command writes it after git rebase --onto <onto> <base> fw/<task> succeeded in the unit’s task worktree (.flywheel/worktrees/<task>; anywhere else the command refuses). onto defaults to the integration branch (below); a configured one that does not resolve is an error naming integration.branch. On a conflict the rebase is aborted, the branch is left as it was, the conflicting paths are listed (exit 1) and nothing is recorded. A rebase done by hand is recorded with flywheel log --task <t> --kind rebased --base <ref> --note "<old base> onto <ref>" (issue #498): --base is resolved to a full commit in --dir, and a missing --task, --base or --note is a usage error (exit 2). When the branch was rebased by hand onto a newer integration commit and that went unrecorded (issue #672), <base> is the branch’s real fork point (`git merge-base HEAD `, used when the recorded base is its ancestor), not the stale recorded base, so the integration branch's own commits are never replayed; `flywheel validate` reports the same drift as `base drift: recorded , branch forks from ; record it: flywheel log --task --kind rebased --base ` (JSON `base_drift`), a reading that never changes the owns check. After the `rebased` event the command re-runs `worktree.setup` when configured, in the task worktree, and appends a `worktree_setup` event (no attempt); a setup that fails exits 1 naming the command, its rc and its output tail, with the rebase kept.
Carries: task, optionally attempt, base (the new base: git rev-parse <onto>), note (was <old base>, onto <onto>, plus , branch forked from <fork> (rebased outside flywheel) when the fork point was used). Validate requires the base and the note.
Effect: no status change. The unit’s base (dispatchBase) becomes the latest rebased event’s base instead of the first dispatched event’s, so the owns check and the review ranges measure from there.
A unit is stacked when its base is not an ancestor of the integration branch and a commit on it after their merge-base carries a Flywheel-Task: <T> trailer for another unit T whose branch fw/<T> contains the base (or, with fw/<T> gone, T is landed): T landed as a squash and the unit still carries T’s pre-squash commits. flywheel validate then records the warning base <sha7> (unit <T>) was squash-merged as <sha7>; run: flywheel rebase <task> as the owns_checked note (the reading still runs), flywheel land refuses (rule stacked, below), and the floor shows the done unit’s run state as stacked on the andon.
The integration branch (issue #456) is .flywheel/config.json "integration": {"branch": "<name>"} when set (validated: non-empty, no whitespace, not starting with -; set with flywheel config set integration.branch <name>, an empty value clears it, issue #529), else main when refs/heads/main exists, else master. flywheel rebase (default --onto), stacked detection (validate, land’s stacked refusal, recover, the floor), flywheel review --group (default --base, main when none), flywheel review calibrate (default --main origin/<branch>, origin/main when none) and flywheel init --ci (the audit workflow’s push branches) read it; flywheel doctor prints integration branch: (integration.branch) or (detected) on stderr and warns when a configured branch does not resolve, then host rules: : pull request <on|off>, required checks <on|off>, up to date <on|off> (or inconclusive) with a warning for each missing pull-request rule, required checks, strict “require branches to be up to date”, or required ship.required_checks name (#686). flywheel ship’s preflight reads the same host rules once its checks pass (not with --no-merge): its shipped note is status passed; <host rules line> and each warning prints ship <task>: warning: <warning>; host rules warnings never refuse a ship (#686).
The ship signature is .flywheel/config.json "ship": {"signature": false} to turn it off (absent or true means on; flywheel ship --no-signature turns it off for one run). When on, flywheel ship adds Shipped-by: flywheel <version> (unit <task>, attempt <attempt>, <passed>/<total> gates) to its ship commit (beside Flywheel-Task:) and to the squash-merge message’s final trailer paragraph, and a Shipped by [flywheel](...) <version> · unit ... · <passed>/<total> gates · <n> correction(s) footer to the PR body; each once, all built from the ledger and the binary’s version.
The ship draft is .flywheel/config.json "ship": {"draft": false} to open the PR ready (absent or true means on, issue #765). When on, flywheel ship’s pr step opens the PR as a draft (opened draft #<n> <url>) and its ci step marks it ready for review (gh pr ready) when CI passes, its note ending ` (marked ready for review); merge` marks it ready again before merging, so a resumed ship never merges a draft. A failed mark-ready fails the step. A reused PR is left as it is.
The ship required checks are .flywheel/config.json "ship": {"required_checks": ["test", "lint"]} (issue #640): the check names flywheel ship’s ci step waits for on the PR’s head commit before it merges; it may name a commit status. Absent or empty means the names of the check runs (never commit statuses) reported on the head commits of every one of the last 3 pull requests merged into the integration branch (none merged: no expected checks); --ignore-check NAME removes a name from either set. A check named in required_checks must conclude SUCCESS: SKIPPED or NEUTRAL on it fails ci at once with required-check-skipped (issue #653), while an inferred expected check that skipped still counts as present.
The worker policy (issue #692) is .flywheel/config.json "worker_policy": {"deny": ["pio run -t upload", "node scripts/flash.mjs"]}: command prefixes, as a worker would type them, that no worker may run (a device upload, a deploy, a publish). Each entry is added to the adapter’s built-in deny list, never replacing it. LoadConfig rejects an empty or whitespace-only entry and one containing *, (, ) or a trailing : (pattern syntax flywheel adds itself), naming worker_policy.deny[]. Enforcement per adapter: claude appends Bash(<prefix>:*) to the worker’s resolved --disallowedTools (the git-write defaults, or its own disallowed_tools), deduplicated, and a denial is attributed to that pattern like a git one (the stop signal’s Bash: <pattern> (<segment>), issue #497); opencode leaves .flywheel/opencode-worker.json as the user wrote it and flywheel run checks its permission.bash holds "<prefix>*": "deny" for every entry (the embedded default when the file is missing), refusing the dispatch with the missing patterns, the file and “add them after the "*": "allow" line”; codex and pi cannot enforce a command deny list, so flywheel run refuses with worker_policy.deny is set but the <adapter> adapter cannot enforce a command deny list; use a claude or opencode worker; sim ignores it. Both refusals come before any event (no dispatched, no dispatch_refused). Separately, flywheel config validate exits 1, while loading still succeeds, when a worker’s disallowed_tools (which replaces the defaults) omits any of Bash(git commit:*), Bash(git push:*) or Bash(git reset:*).

`recovered`

Written by: the CLI only, via flywheel recover --apply (issue #422), when it applied at least one safe action, and via flywheel supervise --resume-limited (issue #472) or the controller’s auto-resume (issue #528) for each auto-resume.
Carries: no task; note (the actions applied, ; -separated, e.g. mark-lost T r1 (lease-expired) checkpoint 1a2b3c4, re-validate T, rebase T onto 5d6e7f8; or one auto-resume <task> <attempt> after rate limit (<n>/<cap>)), paths (the tasks they touched, sorted), session on an auto-resume (--session, default $FLYWHEEL_SESSION, else supervise; the controller’s, $FLYWHEEL_SESSION else controller). Validate requires the note and refuses a task.
Effect: no status change; the applied actions record their own events (lost, validated, owns_checked, rebased; a resumed run its dispatched and finished).
flywheel supervise --resume-limited acts on the recover next action resume-session (below) for a unit that is not dormant and whose latest finished is its current attempt’s rate-limited one (never abandoned-job, never any other reason; a wait-reset unit, its model still paused, waits until the pause passes). Still under supervise.lock, it appends the auto-resume event FIRST, then starts flywheel run <task> --resume --session <session> in the background, its output appended to .flywheel/runs/<task>.autoresume.log; a crash between the two never starts the unit twice. An auto-resume event later in the log than the task’s latest finished means a resume was already started for that finish: a second pass starts nothing. The cap is limits.rate_limit_retries auto-resumes since the task’s latest planned event: past it the pass reports not resumed: auto-resume cap N reached and starts nothing. A failed start keeps its event (it counts toward the cap). Exit codes are unchanged.
Out-of-process resume path (issue #830): the recover resume-session reason for a rate-limited or abandoned-job unit names flywheel supervise --resume-limited (or flywheel controller with controller.auto_resume) after the reset, its command still flywheel run <task> --resume; flywheel status attention lines carry next (flywheel run <t> --resume (or flywheel supervise --resume-limited) for rate-limited, flywheel run <t> --resume for error), printed as -> <next>. flywheel wait --notify CMD runs CMD through the gates’ shell once per named task whose finish is not a clean stop, as soon as wait prints that finish, with FLYWHEEL_FINISHED="<task> <attempt> reason=<r> exit=<code>" (<code> the exit flywheel run returns for that reason); a failing command only warns (flywheel wait: warning: ...) and appends no event.
flywheel controller runs the same pass (issue #528) after each tick’s reconcile actions while controller.auto_resume is on (the default; false turns it off): same selection, cap and event-before-start ordering, under supervise.lock (a tick waits at most 1s for it; a busy lock skips the pass that tick with a warning on stderr, the next tick retries), its session $FLYWHEEL_SESSION, else controller. Each unit it acted on prints one line after the tick summary: resumed <task> <attempt> (log .flywheel/runs/<task>.autoresume.log) or not resumed <task>: <reason>. For every unit actually started it runs controller.notify, when set, through the gates’ shell with FLYWHEEL_RESUMED="<task> <attempt> model=<model>"; a notify failure only warns. flywheel supervise --resume-limited is the one-shot form.
flywheel controller --health-every D (default 5m; 0 disables) makes each tick end by appending one health event when none is recorded or the latest is at least D old: at most one per interval, idempotent within it. flywheel status --health [--stale-after D] [--json] prints the latest as health <age> ago: running N, stalled N, rate-limited N (paused: <model> until HH:MM), andon N, oldest <task> <age>, controller gen G, flywheel <version>, or health: none recorded; --json prints {ts, age, stale, health} (null when none). A record older than --stale-after (default 10m) prints health STALE (<age>): the controller is not recording; run flywheel controller and exits 1 (exit 0 otherwise). The recorder also writes the record’s stale_after: controller.health_stale (a Go duration, positive) when set, else twice --health-every (issue #552). When the latest record is older than its stale_after, the factory floor (factory, watch, the TUI) shows one andon entry health STALE: the controller is not recording <age>; a record without stale_after (an older writer) never does. status --health still judges by --stale-after.
limits.checkpoint_every (a Go duration, default 10m; "0" off): an attempt running in its task worktree is checkpointed to refs/flywheel/checkpoints/<task>/<attempt> on that interval, only when its owned files changed.
limits.shell_timeout (a Go duration, default 60m, positive): the longest foreground command a claude worker’s Bash tool may run. flywheel run sets the worker’s BASH_MAX_TIMEOUT_MS to it (overriding an inherited value) and BASH_DEFAULT_TIMEOUT_MS when the environment has none, and the abandoned-job resume delta names it, issue #678.
flywheel recover [--json] [--apply] [--all] [--dormant-after DUR] [--session ID] (read-only without --apply) is where every lead session starts. It checks integrity: the log’s hash chain and every §2 rule over every task. A rule failure on a task that is not landed fails integrity. A failure on a landed task is history: it can no longer be acted on, so it is reported and counted (integrity.history; the text shows the count and the first five, --all every one) and never fails integrity or the exit status. Then per task (as Derive sees it) it checks:
- the task worktree (.flywheel/worktrees/<task>, else the attempt’s recorded workdir). Its HEAD must contain the attempt’s finished.commit (git merge-base --is-ancestor). A lead commit or merge on top is consistent; a later rebased event explains a move; a git failure is unknown, never a mismatch. Its uncommitted paths are compared with the attempt’s wrote list. The dispatch baseline with unchanged content and the paths worktree_setup linked are excused; the rest are unexplained.
- the lease (live, dead, none).
- the run file (complete when its last byte is a newline, torn, missing).
- a stacked base, a paused model, and the task’s checkpoints.
- the lead-built mark (issue #722, JSON lead_built, omitted when empty): when the latest inspected event after the task’s latest planned one has lead_built, built by lead, <n> changed lines plus , exception: <text> when it carries one; with no such inspected event, a lead-built task (no dispatched after its latest planned) with a validated event is built by lead; otherwise empty. The text prints it under the task as built by lead: <n> changed lines. The floor (flywheel factory, text and --json unit lead_built) shows the same mark in the unit row’s SESSION and MODEL cells, truncated to their combined width.
- the review owed (issue #789, JSON review_owed, omitted when empty; landed tasks included): when the task’s latest inspected event with verdict pass has lead_built and an exception, and no agent reviewed event (persona reviewer or reviewer:<dim> with an adapter) follows it, whatever its verdict, the command that pays it: flywheel review <task> --agent --base <leadBuiltBase> --session <reviewer> (--base <the commit before the unit> when no base is recorded). The text prints review owed: <command> after the built-by-lead line. The task’s next action is unchanged. flywheel next appends one REVIEW_OWED action per owing task (reason: the command), in ledger order after the reconciler’s actions (MARK_LOST, REQUEST_INSPECTION, BLOCK, WAIT, DISPATCH, HOLD); nothing applies it.
A landed task is reported from the ledger alone (no worktree, lease, run-file or tree reads), and the tree hash is computed once per workdir, so recover stays fast on a large ledger (#628).

A task not landed whose latest event is older than --dormant-after (default 168h; 0 disables) is dormant (JSON dormant: true). Its next action is still computed, but the text shows dormant tasks as one summary line (count and ids) unless --all, and --apply never acts on one: it is listed as dormant. Landed tasks are likewise one summary line (N landed units) unless --all. Exit 0 when integrity passes and no task’s next action is investigate, else 1.

Several lead sessions may share one ledger (issue #472). --session ID (default $FLYWHEEL_SESSION) names yours. Each task carries lead, the lead of its latest dispatched event that records one (a dispatch without a session, a review --fix round say, keeps it). integrity.failed stays flat. integrity.by_lead groups it by that lead: your session’s group first (current: true), then the other recorded leads sorted, then "" (unrecorded, or an item with no task). When at least one failed item’s lead is recorded, the text prints the failures under lead <id> (this session): <n>, lead <id>: <n> and lead unrecorded: <n> headers; otherwise it keeps the flat lines. With a session given, a task another lead dispatched ends its line with ` [lead ]`. Export `FLYWHEEL_SESSION` once per lead session so `flywheel run` records it and `flywheel recover` groups by it.

The next action per task, first match wins:

Condition	Action	Command
`landed`	`none`
not in flight, worktree HEAD is not the attempt’s commit	`investigate`
not in flight, uncommitted paths no attempt wrote	`investigate`
dispatched/running, lease live	`none`
dispatched/running, lost by the `lost` rules above	`mark-lost`	`flywheel recover --apply`
dispatched/running, otherwise	`none`
unclean finish or `lost`, model paused	`wait-reset`	`flywheel run <task> --resume` (waits for the reset)
finished `suspended`, the factory still suspended	`resume-session`	`flywheel resume --session <s>`
finished `suspended`, the factory thawed	`resume-session`	`flywheel run <task> --resume`
finished `rate-limited` or `abandoned-job`	`resume-session`	`flywheel run <task> --resume`
`lost`, or any other unclean finish	`none` (dispatch or correct)
finished `stop` or `passed`, stacked	`rebase`	`flywheel rebase <task>`
`passed`	`land`	`flywheel land <task>`
open blocking findings outside the effective brief’s owns (issue #458)	`assign-owner` (assign them to another unit, amend owns, or dismiss them; the reason names the ids and the thread)	`flywheel review <task> --dismiss <id> ...`
any other status than `finished`	`none`
no `owns_checked` reading since the finish	`re-validate`	`flywheel validate <task>`
the tree changed since that reading	`re-validate`	`flywheel validate <task>`
readings complete and passing, review panel applies and is incomplete	`review`	`flywheel review <task> --agent --panel ...`
readings complete and passing	`inspect`	`flywheel inspect <task> --verdict pass ...`
otherwise (readings failed on the current tree)	`none` (correct)

--apply runs only mark-lost (as the controller does, and it checkpoints the lost attempt’s changed owned files, since a killed process never reached its finished event), re-validate (a measurement) and rebase when the base is certainly squashed and git rebase reports no conflict (a conflict is aborted and listed). resume-session, wait-reset, review, inspect, land, assign-owner and investigate are never run; they are listed for the lead.
Checkpoints. An attempt that ends uncleanly (error, rate-limited, stalled, silent, abandoned-job, length, suspended) after writing files has its changed owned paths snapshotted: a temporary index reads HEAD, adds those paths, writes a tree, and commit-tree makes checkpoint <task> <attempt> on top of HEAD, kept at refs/flywheel/checkpoints/<task>/<attempt> — never the branch, never the real index. The finished event carries the sha as checkpoint; a checkpoint failure goes on its note and never fails the run. flywheel checkpoint list|diff|restore|drop manages them; restore refuses over uncommitted changes to the checkpoint’s paths unless --force.

`landed`

Written by: the CLI only, via flywheel land <task> --commit <sha> or flywheel land --group.
Carries: task, commit, note, and group (group:<id>) when landed by land --group.
Group landing (#775): flywheel land --group <goal|tasks:a,b> --commit <sha> [--note N] [--allow-untriaged R] lands every member of a group (GroupMembers) on the one merge commit. It takes no task id and refuses --merge, --by-lead, --exception and --correct (exit 2). First every member not already landed on that commit must be passed, else it refuses (exit 6, rule T5, naming the member) and nothing lands; then each member lands through the same checks as land --commit (the commit must touch that member’s files, T9, stacked, group), its landed event carrying group. A member already landed on the commit is skipped, so a rerun resumes after a failure. --allow-untriaged applies to the members with untriaged signals. It prints <task> landed <sha> (group <id>) per member landed. flywheel stats counts such units as group_landed and never as first pass.
Effect: Derive sets status landed. Verify’s T5 (ruleT5) requires an earlier inspected pass or a recorded excepted event for the task; LandTask itself refuses live (exit 6, rule T5) unless the task’s derived status is already passed or an exception is provided, refuses (exit 6, rule T5, issue #673) a --commit that is on neither any remote’s <integration.branch> nor the local one, or touches none of the unit’s files (exits 8 when the commit does not resolve or no integration branch does; see T5 below), and refuses (exit 6, rule T9) while the task has untriaged signals unless --allow-untriaged <reason> records why, refuses (exit 6, rule stacked, issue #414) a unit whose base landed as a squash (see rebased above; the fix is flywheel rebase <task>, and an exception landing overrides it), refuses (exit 6, rule group, issue #420) while an open blocking finding with category integration is on the task or, when it was planned under a goal, on group:<goal> (see group_reviewed above; close it by a new group review or a lead’s dismissal), and refuses to re-land the same task under a different commit than it already recorded. The read, the checks and the append(s) run under .flywheel/dispatch.lock (the lock run and amended take) and then .flywheel/feedback.lock (the lock learning writers take; always in that order), so two concurrent landings of one task can never both pass the already-landed check, and no learning can change the task’s signals mid-decision.

`land_corrected`

Written by: the CLI only, via flywheel land <task> --correct <sha> --reason TEXT --session S (issue #673): a landing recorded with the wrong commit is corrected by a new event, never by rewriting the landed one (the log is append-only) and never by a note.
Carries: task, commit (the corrected commit), tree (its landed tree, as landed records), note (the reason), session (the lead). Validate requires the task, the note, the session and a valid commit on every write path.
Effect: no status change (the status stays landed). The task’s effective landed commit is the last landed or land_corrected commit in log order (landedCommit); the earlier ones are superseded, and flywheel explain lists them. Re-landing the effective commit is a no-op; any other commit is still refused (T5). CorrectLanding takes .flywheel/dispatch.lock and refuses (exit 6, rule T5) when the task has no landed event (nothing to correct; land it first), when the commit is malformed or already the effective one, or when the --commit checks of landed refuse it (off the integration branch, touching none of the unit’s files; exit 8 when it does not resolve), and (exit 6, rule T4) when the session is a worker session for the task. --correct cannot be combined with --commit, --merge, --by-lead, --exception, --allow-untriaged, --onto or --note, and needs --reason and --session (exit 2). Verify’s T5 fails a land_corrected event without an earlier landed event, reason or session; T4 fails one from a worker session.

`excepted`

Written by: the CLI only, via flywheel land <task> --commit <sha> --exception TEXT --session S.
Carries: task, commit (the commit the evidence covers), session (the lead), note (the evidence), reason (the status it overrode). Validate requires the note, the session and a valid commit on every write path.
Effect: no status change by itself. It is appended in the same single write as the landed event it permits (AppendEvents), so a failure never leaves an exception without its landing. Verify’s T5 accepts a landing on an exception only when the exception names the same commit and reports it as “landed on a recorded exception” (a deliberate, visible exception to T5, never a silent bypass). T4 fails an excepted event from a worker session (one that wrote the task’s started, finished, dispatched, report or worker_plan event).

`allow_untriaged`

Written by: the CLI only, via flywheel land <task> --commit <sha> --allow-untriaged REASON.
Carries: task, commit (the commit the landing covers), note (the reason), signals (the condition names the landing allows — the untriaged signal names at the time the landing was recorded). Validate requires the task, the note and a valid commit on every write path.
Effect: no status change by itself. It is appended in the same single write as the landed event it permits (AppendEvents), so a failure never leaves an allow_untriaged without its landing. T9 enforces that a landing refusing to triage signals must be recorded with this event; the signals are not triaged by this event (they stay listed by flywheel feedback until a learning names them), and the event is purely for auditability and transparency.

`audited`

Written by: flywheel audit <task> --session S, from a session that did not plan, build or inspect the unit.
Carries: task, verdict (conforms / nonconformance), session, tree, note (the findings), persona (auditor).
Effect: no status change, and its verdict never replaces the unit’s QC verdict in derived state. The tree is the one the gates were re-run on: captured before the clean copy is made and re-checked before recording (a tree that changed mid-audit records nothing). A record check that cannot be established (INCONCLUSIVE) is a finding: an audit that cannot confirm does not pass. The auditor’s independence is checked again right before the event is appended. T7 gating is opt-in: see T7 below. In config, Validate refuses a staffing.auditor on the same agent and model as another role unless its RoleConfig independence is "session" (issue #463): a single-model factory then relies on this fresh-session check; a shared session is refused either way, and independence on any other role, or any other value, is a config problem.

`release_audited`

Written by: flywheel audit --release <version> --session S (issue #420), after a release is published.
Floor level: carries no task.
Carries: session, version (the tag, v0.21.1), verdict (pass, fail or inconclusive), checks (one name=status string per check, in order: tag, changelog, binary, commands, docs, calibration; status pass, fail, skipped or inconclusive) and note (the same list joined by , ). Validate requires the session, the version, the verdict and at least one check; no other kind may carry version or checks.
Effect: no status change. Every repository file is read at the tag, never the working tree. The verdict is fail when any check failed, else inconclusive when any could not be established (a download or a run of the binary failed, or the tag is missing only from this clone or origin could not be asked; a tag missing on origin too fails tag), else pass. It is recorded whatever the verdict; a missing session or a usage error records nothing.

`health`

Written by: flywheel controller with --health-every above 0 (issue #528), at most once per interval.
Floor level: carries no task.
Carries: health, the snapshot: running (tasks dispatched or running), stalled and rate_limited (units in that run state on the floor), finished (finished tasks less the rate-limited units, so none is counted twice; issue #552), andon (the floor’s andon count), stale_after (the age past which the record is stale, a Go duration such as 10m0s: controller.health_stale, else twice --health-every; omitted by older writers; past it the floor shows a health STALE andon entry), paused_models ([{model, reset_at}], each model a rate limit pauses and its RFC 3339 reset), oldest_in_flight (the longest-dispatched in-flight task and its age, T3 42m; omitted when none), controller_generation (the controller lock’s generation) and version (the flywheel version). Validate requires the snapshot and no task; no other kind may carry health.
Effect: no status change. Read by flywheel status --health.

`suspended`

Written by: flywheel suspend --session S [--reason TEXT] [--until TIME] (issue #572).
Floor level: carries no task.
Carries: session (who froze the factory), note (the reason) and until (the thaw time, RFC 3339; omitted when the freeze lasts until flywheel resume). Validate requires the session and no task; no other kind may carry until, and it must parse as RFC 3339.
Effect: the factory is suspended while its latest suspended event comes after its latest unsuspended event and its until, when set, is still ahead; past until it thaws with no event. While suspended every dispatch path refuses and appends nothing: flywheel run exits 6 with rule suspended (the factory is suspended since <ts> by <session>: <reason>; flywheel resume --session <s> to thaw), flywheel next turns each DISPATCH into a WAIT naming the suspension, and the controller’s and supervise --resume-limited’s auto-resume starts nothing, reporting each unit not resumed with reason suspended. flywheel status prints a first SUSPENDED since … line (suspended in --json) and the floor lists a factory suspended andon entry first. A second flywheel suspend while suspended is refused (exit 6, rule suspended).
stop (flywheel suspend --stop; only suspended may carry it): the suspension also stops every live worker. The command writes the sentinel .flywheel/suspend.stop (content: the event’s ts). A running flywheel run stats it on every lease tick (lease.renew_interval) and, only when it exists, reads the ledger and confirms the suspension carries stop; it then kills the worker the way the stall watchdog does and finishes the attempt with reason suspended, note stopped by suspend at <ts>: the finished event keeps the session, the written owned files are checkpointed, a worktree’s changes stay in the worktree (no attempt commit), and the run exits 6. flywheel recover offers such a unit resume-session (reason stopped by a factory suspension) with the command flywheel resume --session <s> while suspended and `flywheel run --resume` once thawed; the floor shows it `suspended`, not failed.
Automatic freeze (reason tokens-exhausted; issue #572): the automatic mark is the event’s reason field, empty on every manual suspension. With controller.auto_freeze on (the default; false turns it off), a controller tick appends a suspended event with session controller (the tick’s session), stop, until the earliest reset and note tokens exhausted: <models> paused until <HH:MM> UTC when at least one worker is configured, every configured worker’s model and fallback models is paused by a rate limit (the reset_at / limit_reset_at pause at limits.rate_limit_pause_at) and the factory is not already suspended. The first tick past that until (with a starter configured) thaws it: it appends unsuspended (note tokens returned), removes .flywheel/suspend.stop and, for every task whose latest finished event is suspended or rate-limited with no later dispatched or auto-resume recovered event, appends a recovered event (auto-resume <task> <attempt> after tokens returned, paths the task) and then starts flywheel run <task> --resume through the auto-resume starter (a suspended unit with the continue delta above). The recorded auto-resume keeps the tick’s auto-resume pass from starting the unit again. A tick that thaws does not freeze. A manual suspension is never thawed by the controller: only by flywheel resume or its own until, and then with no re-dispatch.

`unsuspended`

Written by: flywheel resume --session S [--note TEXT] [--no-redispatch] (issue #572).
Floor level: carries no task.
Carries: session (who thawed the factory) and note. Validate requires the session and no task.
Effect: thaws a suspended factory; refused (exit 6, rule suspended) when it is not suspended. The command removes .flywheel/suspend.stop and re-dispatches every task whose latest finished event has reason suspended and no later dispatched event: it writes the continue delta .flywheel/briefs/<task>.delta.txt (the brief’s owns, needs and gates, then “You were stopped by a factory suspension; …”) and starts flywheel run <task> --resume --dir <dir> --session <s> detached, as supervise --resume-limited does (log .flywheel/runs/<task>.autoresume.log), printing resumed <task> <attempt> (log <path>). --no-redispatch only thaws.

`probed`

Written by: flywheel doctor --record.
Carries: model, reason (the doctor class: ok, credits, key limit, consent required, auth missing, error, local endpoint down, model not pulled), note (flywheel doctor, or flywheel doctor: <detail> when the probe is not ok: the start error, the error message, or exit N: <first stderr line> / no stop (...), cut to 200 characters; issue #637).
Effect: an ok probe newer than the model’s latest provider error closes its breaker at once instead of waiting for the cooldown to expire (issue #46).

`gate_probed`

Written by: flywheel lint <brief> --probe --task <id> (issue #544), one event per gate in a single append, before dispatch; --probe without --task records nothing, and --task without --probe is a usage error (exit 2).
Carries: task, gate (the gate’s 1-based index as a string), command (the gate command text), rc, duration_ms, reason (the probe’s first output line, or the spawn error text) and commit (the probed HEAD when the dir is a git repo) and tree (the probed dir’s content tree hash, as validated records it; omitted when it cannot be computed, e.g. not a git repo, issue #833). Validate requires task, gate, command and rc.
Effect: informational; no status change. It may precede the task’s planned event: Derive skips it, so it never creates a task. When a gate fails, flywheel validate looks up the task’s newest gate_probed event with the same command (the text, not the index) and, if its rc is non-zero, prints <task> gate <N>: note: this gate already failed on the base tree before dispatch (exit <rc>): <reason>; flywheel explain adds (also failed on the base tree before dispatch, exit <rc>) to the failed gate’s line. Validate’s exit code is unchanged. Probes before the task’s first dispatched event feed inspect’s red-first rule (issue #648): for a kind: fix task with lint.red_first on (the default), flywheel inspect --verdict pass keeps the newest pre-dispatch probe per command and refuses (rule red-first, exit 6) unless one has an rc other than 0, 126 and 127 on a command still among the effective brief’s gates. flywheel run refuses the task’s first dispatch the same way (rule red-first, exit 6, issue #812), so the missing probe is caught before a paid attempt, and refuses a correction (--delta/--resume) whose merged gates drop every red-probed gate the replaced attempt kept (issue #825). A probe recorded after the first dispatched event counts too, but only before the task’s first finished event and only when its tree is set and equals that dispatched event’s tree: it ran on the dispatched base tree, not the worker’s (HEAD proves nothing, as workers never commit; issue #833). Any other probe after dispatch never counts; probing before dispatch stays the normal path. Right after it, inspect applies rule ci-escape (issue #776, see ci_failed). The probe itself (recorded or not) also feeds lint’s rule host-dependent-gate (issue #809): a full-suite gate that fails on the base tree while CI’s check runs are green on that commit is a lint problem (lint.probe_ci false turns it off); recording is unchanged. Config gates.env_allow (issue #809, unset by default) runs every gate with a clean environment: a gate inherits only the variables whose name is an entry or starts with an entry’s prefix (an entry ending in a single *), plus the OS essentials (PATH, PATHEXT, HOME, USERPROFILE, HOMEDRIVE, HOMEPATH, TEMP, TMP, TMPDIR, SystemRoot, SystemDrive, windir, ComSpec, LOCALAPPDATA, APPDATA, ProgramData, ProgramFiles, ProgramFiles(x86), USER, USERNAME, LOGNAME, SHELL, LANG, LC_ALL, TERM) and Windows’ =C: entries; FLYWHEEL_BASE, FLYWHEEL_SLOT and FLYWHEEL_PIPESTATUS_FILE are added after the filter. A worker (not a gate) also gets FLYWHEEL_TMP, its scratch directory .flywheel/runs/<task>.<attempt>.tmp in the worker’s tree (issue #872), and TMPDIR, TEMP and TMP set to a second per-attempt directory under the system temp, flywheel-<task>-<attempt>-*, outside any git repository so the temp dirs its tools create are too (issue #880); both are removed when the attempt ends. Names match case-insensitively on Windows only. A brief’s needs-env: names (exact) pass through too, wherever its gates run. It applies to validate (and its vs-base run, whose cache is keyed on the list), this probe, review --group gates and the review and audit re-runs. An empty entry, one with =, or a * anywhere but last is a config error naming gates.env_allow[i].

`amended`

Written by: the planner or lead, via flywheel log --task <id> --kind amended --brief <path> [--session S --model M] --note <why>; a --json-ingested amended event lands through the same check.
Carries: task, brief, header (the parsed brief header as recorded when the amendment was appended, as for planned), session and model (the planner’s identity, recorded as for planned), note, persona (planner), and owns/needs copied from the brief header, as for planned. The --goal flag is a usage error (exit 2) with --kind amended.
Effect: Derive updates only brief/needs/owns on the task, never its status. Verify’s T1 treats a dispatched hash mismatch as explained when an amended event for the task falls between that dispatch and now.
Limit: an amendment cannot change the gate set an attempt has already been dispatched with — a pass is measured against the attempt’s effective header, so the command refuses (exit 6) an amendment that would change the effective gate set instead of recording one that changes nothing. The comparison is against the effective set AttemptBrief merges, not the dispatched header alone: a correction whose delta declares no gate: lines inherits the base gates, so amending them does change what validation runs and is allowed; a correction’s delta never replaces live-gate: lines, so an amendment touching only live-gate: takes effect on a correction attempt but is inert — and refused — on a fresh dispatched one. Change the gates of a dispatched attempt with a correction delta: flywheel run <task> --delta <file>. An amendment that widens owns: after a fresh dispatch takes effect: the attempt’s effective owns are the dispatched header’s plus every later amendment’s (issue #281). One that would narrow owns: or exclusive: cannot take effect — both are unioned — so it is refused (exit 6) like an inert gate change. Narrowing is judged by coverage, with the matching the owns check uses: replacing src/ with src/main.go stops covering src/other.go, so it is a narrowing. A JSON-ingested amendment without a header is stored with the header parsed from its brief, so it takes effect the same way. A legacy dispatch that recorded no header is measured against the latest amendment, where a narrowing does take effect, and is not refused. Fixing prose is allowed. The refusal and the append run under .flywheel/dispatch.lock, the same lock file flywheel run holds across its own read-check-append, so an amendment and a dispatch serialise.
Acknowledging a lost delta: flywheel log --task <id> --kind amended --attempt c<n> --note <why> (no --brief) records that correction c<n>’s delta is not retained — for ledgers written before the per-attempt snapshot, where a later correction overwrote a shared delta file (issue #452). Validate requires a correction attempt (c*) and a non-empty note; flywheel log (the flag path and --json alike) also requires a dispatched event for that attempt and refuses a brief or header. It amends no brief: it never excuses a fresh attempt’s mismatch. T1 passes that one correction’s mismatched or unreadable delta only when the acknowledgement was recorded after its dispatch, with reason acknowledged: delta for c<n> not retained (<note>); it never waives a correction silently, and never one with no acknowledgement.

Because planned, amended and dispatched events carry the parsed header, the log is self-contained: a pass is measured against the header recorded in it, so a brief edited on disk after the fact — even one re-recorded through flywheel log --kind amended with the same path — no longer changes what any recorded pass is measured against. On a dispatched attempt, owns widen with --kind amended; gates change only with flywheel run <task> --delta <file>, which is what flywheel run’s brief-drift message names (issue #387). An amended event whose brief matches the file on disk records the change, as a later planned one does, so later dispatches neither warn brief-drift nor refuse under --strict-brief (issue #617). An event without a header falls back to reading the file at its brief path, so ledgers written before this field existed keep working exactly as before.

`validated`

Written by: the CLI only, via flywheel validate <task>, once per declared gate: line, or flywheel attest (an external reading, below), or flywheel validate --group (below).
Group readings (#775): flywheel validate --group <goal|tasks:a,b> --workdir <combined tree> [--dir DIR] validates the members of a group (GroupMembers: a goal id or an explicit task list) together on one combined tree, for units split with disjoint owns: but shared gates, whose own trees fail those gates by design. It takes no task id, needs --workdir, and refuses --live and --carry (exit 2). Before any gate runs it refuses (exit 6, rule group-owns, naming the path and both tasks) when two members’ owns: lists share an entry or a changed path (the union of each member’s changed paths since its dispatch base) matches two members’ owns:. Walking the members in order and each member’s gates in order, every distinct gate command runs once on the combined tree: its validated event is recorded for the first member that declares it, and every other member declaring the same command gets a copy under its own task, attempt and gate index. Then one owns_checked per member is recorded on the same tree and commit: outside the group’s outside list (a changed path no member’s owns: or needs-state: covers), files the changed paths in that member’s own owns:, markers as usual. Every one of these events carries group (group:<id>, GroupTask); Validate accepts group only on validated, owns_checked, inspected and landed, and only in group:<id> form. The readings match on task and tree, so each member’s inspect --verdict pass accepts them as its own. It prints one group <id> gate <command>: pass|fail line per distinct gate, owns: ok or the outside paths, and <task>: readings recorded on tree <short> per member; exit 0, 5 on a failing gate, an outside path or a conflict marker, 6 a refusal.
Carries: task, attempt, gate (1-based index, as a string), command, tree (git tree hash), commit (the repository HEAD at the moment this reading was taken, not at the start of the pass — each gate resolves it independently, so two readings in one pass may carry different commits and that is correct, not a bug; empty when the workdir is not a git repository or HEAD cannot be read, so a consumer must treat commit as optional and never assume a non-empty value, issue #240), workdir (the git working tree the reading was taken in, recorded in canonical absolute form — symlinks resolved, DOS 8.3 short names expanded — and only when it differs from the flywheel root: an external --workdir clone, so a verifier can resolve the tree object in the right repository, issue #244; omitted on same-dir readings, including aliases of the root), rc, duration_ms, sha256 (of the gate’s combined output), path (.flywheel/evidence/<task>/<attempt>/gate-<n>.log), persona (always "supervisor", hardcoded — see §4), reason/note (host-blocked when Windows Smart App Control blocked the freshly built binary twice in a row; vs-base when a vs-base gate passed against its unit’s base, see below), vs_base (a vs-base gate’s comparison against the unit’s base, issue #788).
Effect: no status change. Validate requires gate and tree to be non-empty. A host-blocked reading never counts as passing for T3, matching ValidateTask’s own GatesOK=false for it.
A gate that fails for a reason attributable entirely to a changed path outside the unit’s own owns: — another unit’s half-written file in the same tree, not this unit’s own work — is recorded with reason inconclusive and a note of blocked by <paths> (issue #162). T3 still requires a passing reading for every declared gate: an inconclusive reading is not a pass, and flywheel validate still exits 5 for it, exactly like an ordinary failure.
A quiet gate (issue #411) is a gate[quiet]: or live-gate[quiet]: header line: a gate that host contention distorts (device timing, hardware in the loop). The parsed header keeps its command among the gates or live gates as usual and lists its 1-based index in QuietGates / QuietLiveGates. Before it runs, flywheel validate takes the exclusive .flywheel/locks/quiet.lock (recording task, gate, pid, host and started_at) and polls until no other task has a live lease on this host and no other process holds a gate marker; the validating task’s own lease is ignored. Every ordinary gate holds a shared marker (.flywheel/locks/gates/<pid>-<n>) while it runs, and first waits while another process holds quiet.lock; after the budget it runs anyway with the note ran during a quiet gate (<task> gate <n>). Both waits are bounded by limits.quiet_wait (a Go duration, default 30m). A lock or marker whose pid is dead on this host is stale and ignored. When the host never goes idle, the quiet gate does not run: it is recorded with reason inconclusive, no rc and the note host busy: <tasks> — unmeasured, never a failure, and not a pass for T3. While quiet.lock is held by a live process, flywheel run refuses every dispatch (exit 6, rule quiet: a quiet gate (<task> gate <n>) is running on this host; dispatch after it ends).
A vs-base gate (#788) is a gate[vs-base]: or live-gate[vs-base]: header line (combinable: gate[quiet,vs-base]:); the parsed header lists its 1-based index in VsBaseGates / VsBaseLiveGates. A fail-match: <Go regexp> header line (FailMatch, the last line wins) names the failing-test lines of every vs-base gate; flywheel lint reports a regexp that does not compile as a problem, and warns when fail-match is set with no vs-base gate or a vs-base gate has no fail-match. Only a vs-base gate whose own reading is a plain failure (non-zero, not host-blocked, masked or inconclusive) is compared: the same command runs at the unit’s base (its dispatched or rebased base, UnitBase; for a lead-built unit, which has neither, the latest planned event’s base, #798) in a temporary detached worktree with the brief’s needs-state carried in, its output in .flywheel/evidence/<task>/<attempt>/gate-<n>.base.log, and the base reading is cached in .flywheel/cache/vs-base/<base>-<sha256(command NUL fail-match)[:16]>.json (base, command, fail_match, rc, failing). The failing lines are the output’s lines (CR stripped, trailing space trimmed) that fail-match matches, deduplicated and sorted. With fail-match the gate passes when the base fails, the unit’s failing set is non-empty and every unit line fails on base too; without it, when the base fails. The validated event then carries rc 0, reason vs-base, the note passed vs base <base12>: <n> failing on base too (or base fails too (rc <n>)) and a vs_base object: base, rc (the unit’s own exit code), base_rc, failing and base_failing (counts), new (unit lines not on base, at most 20), cached, base_log. A failure keeps the unit’s rc and vs_base, its note naming <n> new failing vs base <base12>: <lines>, base passes or no fail-match line in the output. No recorded base (neither a dispatched/rebased base nor a planned base) fails with vs-base: no unit base recorded; a base that cannot be measured (a setup error, a host-blocked run) is never cached and the gate stays failed with a note why. The pass’s debt stays visible: for each gate the latest validated event on the unit’s measured tree that is a vs-base pass counts, and flywheel factory appends ` vs-base ` to the unit's row (`vs_base_failing` in `--json`; n is the sum of their `failing`, shown only when above 0); `flywheel inspect --verdict pass` prints, after `inspected pass`, one line per such pass on the inspected tree: `gate passed vs base : failing on base too ( on base)`. `flywheel verify` checks every vs-base pass with rule V1 (§2).
Exclusive resources (#697): a resources: e2e, dev-db header line names the shared host resources (ports, one local database) a unit’s heavy gates use. Names are lower case, [a-z0-9][a-z0-9._-]*; lines accumulate and each name is kept once, in order, in the parsed header’s Resources. Gate markers are a comma list: gate[resources]: (or gate[quiet,resources]:, live-gate[resources]:) records the gate’s 1-based index in ResourceGates / ResourceLiveGates. A gate marked [resources] holds the locks; when no gate of a list (gates or live gates) is marked, every gate of that list holds them. While such a gate runs, flywheel validate holds an exclusive lock per resource at <git common dir>/flywheel-locks/resource-<name>.lock (outside a repository, <tree>/.flywheel/locks/resource-<name>.lock), so the lock is per repository: every worktree of it on this host shares it. Locks are taken in sorted name order (no deadlock between two units naming one pair in different orders) and released in reverse once the reading is recorded. A wait is bounded by limits.quiet_wait (default 30m); a stale lock (no heartbeat for 15s) is taken over. A gate that waited at least 1s records the validated note `waited for resource ()`, joined with `; ` to any other note. When a lock stays held past the budget the gate does not run: it is recorded with `reason` `inconclusive`, no `rc` and the note `resource busy: held by `, not a pass for T3, and `flywheel validate` exits as for any inconclusive gate. The lock serialises validate's gates only, never the worker's own runs. With no `resources:` line nothing is locked. `flywheel lint` reports an invalid name, an empty `resources:` line and a `[resources]` marker without a `resources:` line as problems.
An external reading (source "external", issue #367) is one flywheel did not measure: flywheel attest <task> --commit <sha> --evidence <url> --session <lead> records that a named run elsewhere (CI on the unit’s PR) passed every gate on a commit. It writes one validated per gate: and live-gate: (rc 0) and one clean owns_checked, in one AppendEvents call, on the commit’s tree, each carrying source, evidence (the run’s URL or reference), commit and session; Validate refuses an external reading missing any of the three. Only the lead writes them, never a worker: attest refuses a worker session of the task (T4, and verify’s T4 fails one), a task with no dispatched attempt (T5), and a commit that changed a path outside the unit’s owns: against its first parent (T3). The T3 path check skips flywheel.md, .flywheel/ and any path matching a .flywheel/config.json attest.lead_paths entry (issue #895): lead-maintained tracking files such as TASKS.md, matched like owns: entries (exact path, prefix ending in /, or shell pattern). A load refuses an entry that is empty, absolute, has a .. segment, starts with ! or is a bad pattern; a T3 refusal’s fix names the key. lead_paths widens nothing else (validate’s owns check is unchanged). With --scope tasks:a,b (issue #908) the command reaches the same scoped check land --pr uses (AttestScoped, #831): for a squash holding several units’ files, a path another listed unit owns is accepted, a path no listed unit owns is still T3, and a listed task not in the ledger is a usage error (exit 2). An external reading counts for T3 exactly like a measured one; verify fails one missing its evidence, session or commit, and names the evidence of a pass it relied on (attested: <evidence> on the T3 line).
An observed reading (source "observed", issue #842) is a check only a person can make: the brief’s observe: <what a person must see and how to decide it> header line, one per check, kept in order and inherited by a correction delta as live-gate: lines are. Nothing runs it: validate skips it and the worker’s report says what to look at. After looking, the lead runs flywheel observe <task> --check <n> --result pass|fail --evidence <photo or reference> --session <lead>, which writes one validated with gate obs<n>, command the observe line, the unit’s current tree (the tree validate hashes), rc 0 for pass and 1 for fail, source, evidence, session and persona supervisor. Validate refuses an observed reading without evidence or a session; observe refuses a missing session or a worker session of the task (T4), a task with no dispatched attempt (T5), and a check outside the brief’s observe lines; verify’s T4 fails an observed reading from a worker session. flywheel lint reports an empty observe: line.

`resource_wait`

Written by: the CLI only, via flywheel validate <task> (#697): when a gate that holds the brief’s resource locks finds a resource’s lock file already present as it starts to take that resource, validate appends one resource_wait for that resource before it starts waiting. A free lock records nothing.
Carries: task, attempt, gate (the gate id exactly as the gate’s validated event carries it, e.g. 1 or live2), command, persona ("supervisor"), workdir (as on validated) and note waiting for resource <name> (<holder>), the holder the lock file names, or another command when it names none.
Effect: no status change. Validate requires a task, a gate and a note. The gate’s later validated event (the waited ... note, or the resource busy: ... inconclusive reading) ends the wait.
Live wait: flywheel factory shows a unit’s RUN cell as waiting for resource <name> (<holder>) <age> while its latest resource_wait of the unit’s current attempt has no later validated event of the same task, attempt and gate, and is younger than limits.quiet_wait (default 30m) plus one minute, so a validate that died before its reading never shows a wait forever.

`worktree_discarded`

Written by: the CLI only, via flywheel worktree remove <path> --discard --session S [--note TEXT] [--dir DIR] (#851), the lead’s safe removal of its own linked worktrees (never raw git worktree remove --force). The command resolves <path> against the cwd and finds it in git worktree list --porcelain of --dir (default .; cleaned absolute paths, case-insensitive on Windows). It exits 1 naming the path for the main checkout or a path that is not a linked worktree, and removes nothing. A clean tree (git status --porcelain=v1 -z --untracked-files=all in the worktree is empty; ignored files do not count) is removed with its links unlinked first (#822), prints removed <path>, exits 0 and records nothing. A dirty tree without --discard exits 6 (rule worktree-dirty), listing every dirty path with its status code, and removes nothing. --discard without --session is usage (exit 2). With --discard, this event is appended first; an append failure exits 1 and removes nothing; only then is the tree force-removed, printing discarded N path(s); removed <path>.
Carries: no task (floor level), workdir (the absolute worktree path), commit (its HEAD), paths (every discarded path, as git status names it), session and note (branch <name>, or branch (detached), then ; <--note> when given).
Effect: no status change. Validate requires workdir, paths and session.

`retro`

Written by: the CLI only, via flywheel retro <task> --session S (--changed P1,P2 | --none) --note TEXT [--dir DIR] (#854), the lead’s retrospective after a landed unit: the agents, briefs and skills it used, refined, validated and evaluated. The task id may come before or after the flags. A task with no landed event is refused with exit 6 (rule retro-not-landed) and nothing is recorded. Exactly one of --changed and --none, --session and --note are required, else usage (exit 2). Each --changed path must be a relative path inside --dir that exists, else exit 1 naming it. A second retro on the same task is appended like the first. Exit 0 recorded.
Carries: task, session, note and paths (the --changed paths, slash form). --none is recorded as empty paths; there is no other marker for it.
Effect: no status change. Validate requires a task, a session and a note.

`recommitted`

Written by: the CLI only, via flywheel worktree commit <task> --session S [--note TEXT] [--dir DIR] (#897), the lead’s recorded re-run of the attempt commit after amending owns to cover paths a clean stop left uncommitted. The task id may come before or after the flags; a missing task or --session is usage (exit 2). The command resolves the task worktree <dir>/.flywheel/worktrees/<task> with fw/<task> checked out; a task with no events in the log, or no such task worktree, exits 1 naming it and records nothing. Owns are the owns validate measures for the task’s current attempt: the attempt’s brief header with recorded amendments and staged destinations applied (one shared helper, so the two cannot drift). The commit is built exactly as a finished event’s attempt commit (temporary index, flywheel identity, message <task> <attempt>, compare-and-swap on fw/<task>; never the shared index), for the task’s latest attempt id. It prints recommitted <task> <attempt>: <sha> (or : nothing to commit), then still uncommitted (outside owns): <paths> when changed paths remain outside owns, all on stdout, and exits 0. A commit made but whose index refresh failed is still recorded, then exits 1.
Carries: task, attempt, session, commit (omitted when nothing was committed), uncommitted (the changed paths still outside owns) and note.
Effect: no status change. Validate requires a task and a session. Validate’s owns check reads this event’s uncommitted as it reads a finished event’s: the latest of the two wins.
Enforcement: config lint.retro_required_since (RFC 3339; "", the default, is off; any other value that does not parse fails config load naming the key). When set, a unit is due when its latest landed event (a land_corrected changes the commit, not the landing, so it does not count) has a ts at or after it and no retro event follows that landing in log order; a re-landing after a retro is due again. While any unit is due, flywheel run refuses before the brief’s checks and preflight with rule retro-missing (exit 6, a dispatch_refused event), its fix naming every due unit and flywheel retro <task> --session S (--changed P,... | --none) --note TEXT. A correction (--delta/--resume) of a unit that is itself due is not refused for that unit. flywheel status prints retro due: <t1>, <t2>, and retro_due in --json.

`owns_checked`

Written by: the CLI only, via flywheel validate <task>, once per pass, or flywheel attest (an external reading, see validated above), or flywheel validate --group, once per member on the combined tree, carrying group (group:<id>, issue #775; see validated above).
Carries: task, attempt, tree, commit (the repository HEAD at the moment the owns check ran, resolved independently of the gates — each reading carries the HEAD at the time it was taken, so it may differ from the gates’ commits and that is correct, not a bug; empty when the workdir is not a git repository or HEAD cannot be read, so a consumer must treat commit as optional and never assume a non-empty value, issue #240), workdir (as on validated — where the reading was taken, canonical absolute form, recorded only when it differs from the flywheel root, issue #244), outside (changed paths not covered by owns:), churn (optional map from a bare outside path to "line endings only" or "whitespace only" when its bytes differ from the dispatch base only that way — a label for the lead to restore it byte-for-byte, never an excuse: the path stays in outside, issue #647), baselined (changed paths excused because they were already dirty at dispatch and are byte-identical now), attributed (changed paths blamed on another in-flight task instead — see below), markers (optional, sorted "<path>:<line>" entries for every git conflict marker line in a changed path, owned or not: after one trailing \r is stripped, a line starting <<<<<<< or >>>>>>> , or exactly <<<<<<<, >>>>>>> or =======; binary and deleted files are skipped; capped at 20 entries plus "... and N more"; any fails the pass, exit 5, issue #698), dropped (optional, sorted "<path>: <line>" entries for every non-blank line the integration commits the branch merged — the unit’s base up to its merge-base with the integration branch — added to a changed owned file that the tree no longer holds, compared without trailing space and \r; a deleted file drops all of them; lines trimmed and clipped to 80 characters; capped like markers; any fails the pass, exit 5, issue #770), fix_lines (optional, sorted "<path>: <n> line(s) from fix <sha12> <subject>" entries for non-blank lines the unit removed from a changed owned file that an earlier fix commit added, measured from the branch’s merge-base with the integration branch so lines integration removed do not count, a subject counting as a fix when it starts with fix, fixes, fixed, hotfix or bugfix; a line-ending change or a pure rename removes nothing and a deleted file counts; subjects clipped to 80 characters; capped like markers; a unit with no dispatch base has none; a reading, it never affects whether a reading is clean, the exit code or inspect, issue #940), staged (optional, the files the brief’s stage: lines staged before the gates, as on staged, issue #781), persona ("supervisor").
Effect: no status change. T3 requires an owns_checked with an empty outside, empty markers and empty dropped on the same tree, and refuses a pass, naming the first entries, while the latest owns_checked on that tree carries markers or dropped. land --merge and ship re-validate the tree they merged, so a marker or a dropped line there is refused with exit 6 before the branch moves or is pushed. A dropped line is restored (`git diff
.. -- ` shows what the integration branch added), or, when the removal is intended, the merged base is recorded (`flywheel log --task --kind rebased --base `) so the check starts there, and the tree re-validated. `flywheel validate` also warns, never fails, when integration commits the branch has not merged touch owned files: ` base: warning: integration commit(s) since the unit's base touch owned files (, ...): merge before landing` (JSON `pending`, issue #770).
The changed paths are the unit’s changes since the attempt was dispatched — uncommitted and untracked files plus files touched by the branch’s own commits since the base commit of the unit’s first dispatched event, or of its latest rebased event (issue #414) (a correction attempt’s check still counts what an earlier attempt committed) (files merged in from another branch are not the unit’s) — so committing a stray edit does not hide it (issue #332). Commits reachable from the integration branch (origin/<integration.branch>, else origin/main or origin/master, else the local branch) are never the unit’s, so a branch that fast-forwarded to main is not charged with main’s files (issue #581).
A changed path outside owns: and not baselined is attributed rather than outside when some other task’s brief owns: it (ownsContains, the matching flywheel validate already uses) and that task is currently in flight (Derive status dispatched, running, or finished — never landed, passed, or rejected): a neighbour’s own work in progress on a shared checkout, not this task’s stray file (issue #117). Attribution never excuses a path this task’s own owns: already covers — such a path was never outside to begin with — and never hides a path no in-flight task owns: that path is still outside, and T3 still fails it. flywheel validate prints attributed paths as <task> owns: attributed <path> -> <task>[, ...] before the outside line.
In a sibling worktree (another git worktree of the same repository, compared against the dispatch-time snapshot), a changed path is attributed to a task of THAT worktree’s own ledger whose brief owns it, which was dispatched, and which has not landed (any status except landed) — its own ledger is the authority for its own worktree, and a unit that passed inspection still owns the uncommitted edits made in its worktree afterwards (issue #278). A task that was only planned never ran and attributes nothing; a path no such task owns is still outside.

`inspected`

Written by: the CLI only, via flywheel inspect <task> --verdict ... --session ....
Carries: task, verdict (pass, rework, scrap, or escalate), tree, session, note, commit (with --commit <sha>: the tree inspected is that commit’s, not the working tree’s — how an attested, already-merged commit is inspected, issue #367), workdir (the git working tree inspected, canonical absolute form, recorded only when it differs from the flywheel root, issue #244), persona (always "inspector", hardcoded by InspectTask — see §4 for the only way a "lead" ever appears there), and on a lead-built unit (no dispatched event after the task’s latest planned one, issue #722) lead_built (true), changed_lines (added plus deleted lines from the unit’s base — UnitBase, else the latest planned event’s base, else HEAD — including new untracked files; with --commit, git diff --numstat <base> <commit>, base defaulting to <commit>^; flywheel’s own files, flywheel.md and .flywheel/, are not counted, issue #729) and exception (--exception’s text). Validate accepts the three only on an inspected event, and exception only with lead_built. group (group:<id>) when recorded by inspect --group.
Group inspection (#775): flywheel inspect --group <goal|tasks:a,b> --verdict V --session S [--commit SHA] [--note N] [--workdir PATH] inspects every member of a group (GroupMembers), typically after flywheel validate --group on the combined tree. It takes no task id (exit 2). It first checks every member against every rule below exactly as flywheel inspect <task> would, recording nothing; the first refusal exits 6 naming the member, and no member’s inspection is recorded. Only when every member passes the check is each member’s inspected event recorded, in member order, each carrying group. It prints <task> inspected <verdict> (group <id>) per member.
Lead-built cap (issue #722): a pass on a lead-built unit whose changed_lines exceed lead_built.max_changed_lines (default 10; config set refuses a negative or non-integer value, and Validate a negative one) is refused (rule lead-built, exit 6, after panel): `task has no dispatched attempt and changes lines, over lead_built.max_changed_lines ; dispatch a worker (flywheel run ) or record why with --exception ""`. `--exception` passes it and is recorded; `--exception` on a unit that is not lead-built is an error (exit 1). `flywheel verify` checks the same as rule L1 (§2).
Skills not loaded (issue #695): with skills.require_loaded on (the default; flywheel config set skills.require_loaded false|true, a non-boolean refused), a pass is refused (rule skills-not-loaded, exit 6, after red-first, before panel) when the latest dispatched event after the task’s latest planned one has adapter claude, names skills, and some named skill appears in no skills_loaded of any finished event after that planned one (a plain name also matches <plugin>:<name>, a <plugin>:<name> its plain name; case-sensitive): `<a, b>: the worker never loaded these skills; dispatch a correction with flywheel run --delta asking it to load them`. Another adapter, no finished event yet, or a lead-built unit is never refused by it. `flywheel validate` prints the same as ` skills-not-loaded: ...` and exits 5; `flywheel explain` shows `skills loaded:` and `skills-not-loaded:` (JSON `skills_loaded`, `skills_not_loaded`).
Denied write (issue #757): a pass is refused (rule denied-write, exit 6, after skills-not-loaded, before panel) when a path in the denied_writes of any of the task’s finished events is among the unit’s changed paths since its dispatch base and no lead lead_edit claim covers it: the worker routed a denied write another way (Bash, an interpreter, a copy). The fix names the paths: revert them, or apply the content yourself and claim it with flywheel claim-edit --paths --session <you>.
CI escape (issue #776): a pass is refused (rule ci-escape, exit 6, after red-first, before skills-not-loaded; not configurable) while the task’s newest ci_failed event’s gates still hold every gate command of the attempt’s brief: CI failed on <note> after every gate in the brief passed; add a gate that reproduces it to the brief (flywheel run <task> --delta ...), then validate again. A brief with a gate command that event lacks passes.
Effect: Derive maps pass→passed, rework→needs-correction, scrap→rejected, escalate→blocked. InspectTask enforces T4, and for a pass verdict T3 too, before the event is even appended — a refused inspection never reaches the log at all.

`ci_failed`

Written by: flywheel ship’s ci step when a check failed with none pending (a CI timeout or a skipped required check is not an escape and writes none), appended before its failing shipped event; and by flywheel log --task <id> --kind ci_failed --note "<check(s)>" for a PR merged outside ship (--task and a non-empty --note are required, exit 2 otherwise).
Carries: task (required), attempt, note (#<n>: <failing checks> from ship; the --note text from flywheel log) and gates: the gate commands of the attempt’s brief (AttemptBrief) when it was recorded, the gates the failing tree passed (issue #776). Validate refuses gates on any other kind, and a ci_failed event without a task or a note.
Effect: none on the task’s status. flywheel inspect --verdict pass refuses (rule ci-escape) until the brief gains a gate, and quality.ci_escapes counts the unit once it lands.

`staffed`

Written by: flywheel staff --role <role> --session <session> [--model M].
Carries: session (required — floor-level kinds are the ones allowed an empty task), persona (defaults to "lead" when not given).
Effect: task-less; Derive skips it outright (if e.Task == "" { continue }). It only feeds flywheel factory’s floor view.

`session_start`

Written by: flywheel log --kind session_start --session <id>, invoked by the Claude Code hook or the OpenCode plugin (flywheel-session.mjs) that flywheel init --hooks installs, on a session’s first turn (issue #157). The same --hooks also installs a Claude Code Stop hook that runs flywheel gate and blocks ending the session while units are finished but not inspected or signals are untriaged (issue #56).
Carries: session (required, like staffed) and no task.
Effect: floor-level; Derive skips it outright, the same way it skips staffed. `flywheel trace ` is its only reader.

flywheel init --git-hooks adds the git layer (issue #56): a commit-msg hook refuses a commit without a Flywheel-Task: <id> trailer (merges, reverts and fixup/squash commits are exempt), and a pre-push hook refuses a push while a unit named in the pushed commits fails flywheel verify --shipped (every verify rule plus S1, which also refuses a unit with no inspected pass: one that was only planned was built outside flywheel, issue #861), or flywheel verify --log finds the event log’s hash chain broken. An existing hook is never overwritten: to get the --shipped check on a repository whose pre-push hook predates it, delete pre-push from the hooks directory and rerun flywheel init --git-hooks.

flywheel init --ci adds the CI layer: a flywheel-audit job running flywheel verify --all --log on every pull request. Made a required status check in the branch ruleset, it cannot be bypassed locally; it needs the event log committed, and an inconclusive check (exit 8) only warns.

`session_command`

Written by: the same hook or plugin, once for every flywheel-prefixed command the session runs.
Carries: session and note (the command line) — both required; Validate rejects the event if either is empty.
Effect: floor-level like session_start. flywheel trace <session> prints its note in the trace line’s detail column.

`session_end`

Written by: the same hook or plugin, when the session ends.
Carries: session (required) and no task.
Effect: floor-level like session_start.

`learning`

Written by: flywheel feedback add --task <id> --severity P0|P1|P2 --title T --observed O --evidence E --ask A [--signals a,b] [--scope flywheel|project], or a flywheel log --json batch.
Carries: task, severity, title, observed, evidence, ask (all required), signals, and scope (issue #409): flywheel — the default, and what an event without scope means — is feedback about flywheel; project is the project’s own learning (its product bugs, say). Validate refuses any other scope, and a scope on any other kind.
Effect: numbered L-01, L-02, … in log order whatever the scope; the generated .flywheel/learnings.md renders a ## Feedback for flywheel and a ## Project learnings section. flywheel feedback export and submit carry only undismissed flywheel-scoped learnings and say how many project ones stayed local.

`note`

Written by: anyone keeping a journal, via flywheel log --kind note [--task T] --note "<text>" [--session S] (issue #409). --note is required.
Carries: note (required), and optionally task and session.
Effect: none — a journal line (action: dispatched…, result: … merged) is never a learning, so it never reaches learnings.md or an upstream report. flywheel explain shows it as note: <text>.

`lead_edit`

Written by: the lead, via flywheel claim-edit --paths <p1,p2> --session <session> [--note ...], to declare an edit it made itself after a unit’s dispatch (issue #228); validate’s owns output and inspect’s T3 refusal name this command for an own-tree outside path (#750).
Carries: session (the declaring session, required), owns (the claimed repo-relative paths, reusing the field that means “these paths belong to this declaration”), baseline (path -> sha256 of the content the claim declared, the same map field a dispatched event uses; "deleted" marks a path that was absent at claim time), note, and no task: the claim is repository-wide, not per task. Only literal paths may be claimed: claim-edit refuses a pattern (*, ?, [) or a trailing / directory prefix with exit 2, because a pattern cannot be bound to one content hash and would exempt a whole tree.
Effect: no status change — Derive skips it like every other floor-level event. The owns check (attributeOutside in gauges.go) attributes a changed path a claim covers as `“ -> lead "` instead of `outside`, so the reading stays clean; a path the claim does not cover is still `outside`. It is a **declaration, not an exemption**: the path still appears in the ledger, attributed to a named session, and the claim expires the moment the path's content no longer hashes to the recorded value (or the path reappears, for a deletion marker) — the lead declared that edit, not the file forever (issue #258).
Three guards a consumer can rely on. A lead_edit never covers a path when (1) the declaring session is a worker session of the task being validated — one that wrote that task’s started, finished, dispatched, report, or worker_plan event, the same worker-event set T4 uses — (2) the claim’s ts is not strictly before the reading being computed: a claim never retroactively blesses a stray an earlier validation already reported, or (3) the path’s current content does not hash to the recorded baseline value: an unbound claim (no entry for the path) never excuses anything. The owns check re-reads the event log immediately before attributing, so a claim appended while the gates ran still qualifies for that reading.
With --worktree <dir> the claim names another session’s edit in a sibling worktree: the paths are hashed relative to that worktree and the event carries it as workdir, so it excuses "<worktree>: <path>" (attributed "<worktree>: <path> -> lead <session>") under the same guards, and never the same relative path in the unit’s own tree (issue #362).
Sibling worktrees (issue #339): a path changed in another worktree recorded at the unit’s dispatch, owned by no in-flight unit’s brief there, is attributed `“: -> lead "` when that worktree's own ledger has a `lead_edit` claim covering it under the same three guards (the worker-session guard against each of that worktree's in-flight units), and only while that worktree still has a dispatched, unlanded unit. A sibling that is another unit's `run --worktree` worktree, `/.flywheel/worktrees/`, is read against the MAIN ledger instead: while `` is dispatched and unlanded there, every changed path in it is attributed `": -> "` (issue #386). A task worktree `/.flywheel/worktrees/` of another ledger L is read against L's ledger and attributed `": -> (another ledger )"` while `` is dispatched and unlanded there (issue #918). Once `` has landed, a changed path in its task worktree whose content (git blob) equals the path in the `tree` of the task's latest `landed` event is attributed `": -> (landed)"`, or `"... -> (landed, another ledger )"`; a landed event without a tree, a deleted file or an edit after landing stays outside ([#937](https://github.com/suzworx/flywheel/issues/937)).

`goal`

Written by: flywheel goal add/flywheel goal set.
Carries: goal (a GoalSpec: id, title, acceptance, required tasks, status — one of active, met, failed, abandoned, checked by Validate).
Effect: task-less, like staffed.

2. Transitions the code enforces

flywheel verify runs ten rules against every task it is asked about — VerifyTasks calls ruleT1, ruleT3, ruleT4, ruleT5, ruleT8, ruleR1, ruleW1, ruleP1, ruleL1, ruleV1 in that order — and the same rules are enforced live, before the record is written, inside InspectTask (T3, T4, T8, R1 as the refusal rule review, and P1 as the refusal rule panel) and LandTask (T5). ValidateTask produces the readings T3 needs but enforces nothing itself; it can fail its own gates (exit 5) without touching the log’s legality.

T1 — dispatch matches its brief. A fresh (r*) dispatched event’s sha256 must match the brief named by the task’s latest planned event, unless an amended event for the task landed in between — then the mismatch is explained, not flagged. A correction (c*) dispatched event hashes its own delta file instead (the path in its own brief field, the per-attempt snapshot); no brief amendment ever excuses a tampered or missing delta. The one exception is explicit: an amended event naming that c* attempt with a note, recorded after its dispatch, acknowledges a delta lost before the snapshot existed, and T1 passes it with the reason acknowledged: delta for c<n> not retained (<note>). verify reports this per-task as rule T1.
T3 — a pass needs current readings, not old ones. inspected pass (or a live --verdict pass inspection) needs, for the same git tree hash the unit actually built: a passing validated event from the supervisor for every gate the current attempt’s prompt declares, and a clean (outside-, markers- and dropped-empty) owns_checked — both recorded after the latest finished event that precedes the check. Every observe: line needs a passing obs<n> observation on that tree after the same finished event too (issue #842): a failing one, or a later failure, is not a pass, and the refusal names flywheel observe <task> --check <n>. On a shared working tree the hash can move between validate and inspect because other units keep writing, so the rule is relaxed (issue #218): when no reading exists on the current tree, the reading may be taken on another tree T whose difference from the current tree lies entirely outside the unit’s owns: — every one of the task’s readings must come from that same T, and the recorded inspected event’s note then names T (; reading from tree <T> (diff outside owns)). This is sound because every file the unit owns is byte-identical between the measured tree and the inspected one, so the unit’s own work was measured; it costs a little because a gate broader than the owned files could be broken by a neighbour’s later change, and T3 accepts that risk deliberately — the alternative is that correct work cannot land at all. That is not a licence to put whole-workspace gates on narrow units. “The current attempt’s prompt” is AttemptBrief’s result (issue #133): the base brief plus, when the current attempt dispatched a different file (a correction delta), that file’s gate: lines replacing the base’s and its owns: unioned with the base’s; the union covers every correction delta dispatched since the task’s latest fresh r<N> attempt, so a later, narrower delta keeps what an earlier one widened (its gate: lines do not carry over, issue #912) — an amended event replaces which brief counts as the base outright. owns: entries are matched as a literal path, a dir/ prefix, or a path.Match shell pattern, all three checked the same way (issue #135, ownsContains). An entry starting with ! is negated (issue #388) and takes the same three forms: a path is owned when some positive entry matches it and no negated entry does, so apps/inc/**, !apps/inc/wake.h owns apps/inc/a.h but not apps/inc/wake.h, and a negation with no positive entry owns nothing. flywheel’s own bookkeeping stays owned. The dispatch owns collision check applies the same rule, so that header does not collide with an in-flight task owning apps/inc/wake.h; an amendment adding a negation that removes a covered path is a narrowing; and flywheel lint never checks a negated entry for existence, but warns when no positive entry covers it. owns: none (or owns: -, any case) declares a unit that owns no paths (issue #693), such as a read-only investigation: the entry is dropped rather than kept as a path named none, so the unit never collides at dispatch, and any changed file outside flywheel’s own bookkeeping fails its owns check. flywheel lint counts it as a present owns line and reports none combined with real paths as a problem. Each inspection uses its own window, so a later correction attempt never invalidates an earlier legitimate pass. A pass measured in an external --workdir — a separate clone, not a worktree of the verifying repository — is verifiable from its own repo: flywheel verify --workdir <path> resolves tree objects there, and without the flag a workdir recorded on the task’s reading events is used when that path still exists (issue #244). When the pass’s tree cannot be resolved in any repository the verifier can see, the strict reading check still runs on the ledger’s own evidence (it needs no git): a complete reading passes T3, and an incomplete one is inconclusive (exit 8) rather than a violation — a verifier that cannot see the tree must not claim a violation it has not established.
T4 — no self-inspection. An inspected, excepted or land_corrected event’s session must never be a session that wrote that task’s started, finished, dispatched, report, or worker_plan event. InspectTask checks this before T3, so a worker-session inspection is refused as T4 even when its readings are also missing.
T5 — no landing without a pass. A landed event needs an earlier inspected pass or a recorded excepted event for the same task. LandTask additionally refuses to land a task whose derived status is not passed (unless an exception is provided), and refuses a second landed event for the same task under a different commit than the effective one (the last landed or land_corrected commit; the same commit is a silent no-op, exit 0). A wrong landing is corrected by flywheel land <task> --correct <sha> --reason TEXT --session S (see land_corrected); a land_corrected event needs an earlier landed event, a reason and a session. Land also verifies the --commit it records (issue #673): the commit must resolve, be an ancestor of an integration ref (any remote’s <integration.branch>, e.g. origin/main or upstream/main, or the local branch; unconfigured, any remote’s or the local main or master), and change at least one of the unit’s paths (the diff from the last dispatch’s base to the last passing inspection’s tree, else the planned owns; .flywheel/ and flywheel.md do not count). A commit off the integration branch or touching none of the unit’s paths is refused (exit 6, rule T5, naming the commit’s subject); a commit that does not resolve, or no integration ref that resolves, exits 8 (inconclusive: run git fetch). Outside a git repository, and when the ledger names no paths, the check that cannot run is skipped. flywheel land --merge is exempt: it makes the commit from the unit’s own branch. flywheel ship fetches the integration branch before landing.
T8 — personas write only their own kinds. validated and owns_checked must carry persona "supervisor"; inspected must carry "inspector" or "lead". No other kind is persona-checked by this rule (§4 has the full picture, including what is and is not mechanically enforced).
R1 — no inspected pass while a blocking review finding was open (issue #389). An inspected pass fails when OpenFindings over the events BEFORE it held a blocker or major finding for the task; a finding raised after the pass never fails it retroactively, and a task never reviewed passes. Live, InspectTask refuses such a pass as rule review, before T3: `open blocking review findings: ; fix them (flywheel review --agent --fix) or dismiss one (flywheel review --dismiss --session --note "")`. A non-pass verdict is never refused by it.
P1 — no inspected pass without a complete review panel (issue #420). Where the panel applied — review.required is set, or an agent reviewed event carrying a dimension preceded the pass — an inspected pass fails when VerdictMatrix over the events BEFORE it, on the pass’s tree, has a configured dimension that is not pass; the reason names each <dimension>=missing|correct. The panel and review.required are read from today’s configuration; a panel_scoped event on the pass’s tree narrows the panel to its own (panelFor, issue #459). Live, InspectTask refuses such a pass as rule panel, after T3 (the tree it checks is the one T3 measured): the review panel is not complete on tree <tree>: <dimension>=<verdict>, ...; run flywheel review <task> --agent --panel --session <reviewer> (add --fix to correct and re-review).
W1 — no withdrawal of a live attempt (issue #479). A withdrawn event is legal after a planned or amended event or after a finished attempt (any status but dispatched or running); one the task’s events derive to dispatched or running just before it (derivation order) fails with withdrawn event at <ts> while attempt <attempt> was <status>; stop the run (or wait for it to finish) before withdrawing. Live, flywheel log refuses such a withdrawal as rule W1 (exit 6) before anything is written.
L1 — no lead-built pass over the cap (issue #722). Every inspected pass with lead_built fails when its changed_lines exceed today’s lead_built.max_changed_lines and it carries no exception (the reason names the session, the lines and the cap); otherwise it passes as lead-built by <session>: <n> changed lines (; exception: <text> when set). With no lead-built pass, one passing item: no lead-built pass over the cap. Live, InspectTask refuses such a pass as rule lead-built (see inspected).
V1 — a vs-base pass is consistent (issue #788). Every validated event with reason vs-base fails (the reason names the gate and its ts) unless its rc is 0 and it carries a vs_base with a non-empty base, a non-zero rc and base_rc and an empty new. A validated event with rc 0 that carries vs_base under another reason fails too. Otherwise one passing item: no vs-base pass or <k> vs-base passes, <n> failing on base too.
S1 — the unit was judged (issue #861; only with flywheel verify --shipped, which the pre-push hook runs). One item per task, after the ten rules above: it passes when the task’s latest inspected event has verdict pass, or the task has a landed event (T5 already requires an inspected pass or an exception before one). Otherwise it fails: task "<id>" was never judged (no inspected pass); build it with flywheel run <id>, then flywheel validate <id> and flywheel inspect <id> --verdict pass, or record a lead edit with flywheel claim-edit, or task "<id>"'s latest inspected verdict is <verdict>, not pass. A unit that was only planned passes the ten rules, so without S1 edits made by hand or by an outside agent could be pushed under its trailer. Without --shipped there is no S1 item and the output is unchanged.

3. Designed, not enforced

docs/design/autonomous-shipping.md describes ten transition rules, T1-T10, and a fuller event vocabulary (audited, signal, dismissed, learning, “by” attribution blocks). Of the T rules, T1, T3, T4, T5 and T8 exist in verify.go (alongside R1, W1, P1, L1 and V1, §2), and T7 and T9 are enforced live by flywheel land (land.go, below). Only the kinds in events.go’s known-kinds map exist at all — Validate rejects any other kind by name — and audited, signal, dismissed and learning are all in that map, so each is a recognized record (audited is written by flywheel audit, §1). Concretely, still design-only or only partly built:

T2 (a step-20 worker_plan or a signal) — the no-plan half landed (§1); flywheel run now records a signal event for no-plan and the other conditions, but nothing treats one as a rule violation.
T6 (sensitive domains need the lead’s sign-off and an audit before landing) — nothing detects a “sensitive domain,” and no command asks for a sign-off.
T7 (a wave’s first article needs audited conforms before the rest lands; an open nonconformance stops its kind of task) — flywheel audit now records audited (issue #61), and flywheel audit --first-article / --sample RATE select first articles and a seeded sample (issue #61), and T7 is enforced by flywheel land when .flywheel/config.json sets audit.first_article: a unit is refused (exit 6) until its worker line has a conforming audit, and while the line’s latest audit is a nonconformance.
T9 (checkpoint/land/handoff refuse while signals are untriaged, unless allow_untriaged) — now enforced live by flywheel land for a task’s own untriaged signals (refused with exit 6 unless --allow-untriaged <reason> records an allow_untriaged event). flywheel handoff does not refuse yet, and flywheel verify does not re-check T9, because ledgers written before the rule existed have landings with untriaged signals and would all fail. The signals are not triaged by allow_untriaged — they stay listed by flywheel feedback until a learning names them with --signals, and they recur untriaged again if the condition reappears after the learning.
T10 (the log is append-only with a hash chain per shard) — the log is append-only in practice (AppendEvent only ever opens with O_APPEND, and ParseEvents treats an unresolved git conflict marker as a hard error). Every event carries prev, the SHA-256 of the log’s last complete line when it was appended (issue #57); flywheel verify --log checks that every prev matches the hash of some earlier line, failing (exit 6) at the first line whose prev matches none. Appends are serialised by .flywheel/events.lock (held only for the read of the last line and the write), so within one ledger the chain is linear: every record but the last is the predecessor of the next, and removing or editing any of them is detected. “Some earlier line” is accepted so a git merge, which interleaves two branches’ lines, stays valid. The per-shard half is built too: in the sharded layout each shard file has its own chain from the shard genesis hash, and @floor.jsonl’s seal pins the legacy file (verifyShardedChain in chain.go; see Sharded layout). Still not built: removing the LAST line of a file, or editing a line written before the chain existed, is not detected.

Until these land, the factory-role table, the andon cord, sampling, and nonconformance handling in docs/design/autonomous-shipping.md and skills/flywheel/references/factory.md describe intent and skill-level convention, not something flywheel verify can fail on.

4. Who may write which event

Verify’s T8 is the only persona check in the code, and it covers exactly three kinds:

validated / owns_checked → persona must be "supervisor". flywheel validate hardcodes this on every event it writes (gauges.go), regardless of which session or identity ran the command — ValidateTask takes no session argument and the event carries none, so nothing ties a reading to who typed it. “A worker never runs the gauges” is a skill-level convention here, not a mechanical block: the OpenCode worker permission policy (skills/flywheel/references/worker-permissions.json) denies only tree-rewriting git commands, not flywheel validate. flywheel attest also signs its external readings "supervisor", and they are the one kind of reading that does carry a session: the lead’s, never a worker’s (T4).
inspected → persona must be "inspector" or "lead". flywheel inspect (InspectTask) always writes "inspector"; the only way an inspected event ever carries "lead" is a hand-crafted flywheel log --json line with an explicit "persona":"lead" field — the ordinary flag form of flywheel log has no --persona flag at all.
Every other kind (planned, dispatched, started, worker_plan, no-plan, finished, report, reviewed, blocked, lost, withdrawn, landed, amended, staffed, goal) carries no persona restriction in ruleT8; withdrawn is the lead’s, through flywheel log; ci_failed is written by flywheel ship’s ci step or the lead’s flywheel log --kind ci_failed (issue #776). In practice most of them are written only by a specific CLI command (dispatched/started/worker_plan/no-plan/finished/report/worktree_setup only by flywheel run; landed only by flywheel land; blocked/lost only by flywheel controller; review_finding only by flywheel review --agent; finding_response only by flywheel review --agent --fix and a lead’s --dismiss), which is what keeps them honest — not a persona field. The staffing reviewer role (staffing.reviewer.adapter|model|session) names who run; landed only by flywheel land; blocked only by flywheel controller; lostonly byflywheel controller, flywheel run and flywheel next; review_findingonly byflywheel review –agent), which is what keeps them honest — not a persona field. The staffing reviewer role (staffing.reviewer.adapter|model|session) names who runs the review agent;Validate` refuses a reviewer session that also holds the lead or inspector role, and the agent itself refuses (T4) a session that is a worker session of the task.

The one place “a worker never inspects its own work” is a real, live check rather than a skill convention is T4: InspectTask and ruleT4 both refuse an inspected event whose --session was ever a worker session (one that wrote that task’s started, finished, dispatched, report, or worker_plan event). Put plainly, in this codebase: a worker never writes a validated, owns_checked, inspected, or landed event because no worker-facing tool writes them and the worker’s own permission policy does not need to block commands it is never given; the supervisor (the gauges) never writes an inspected event because flywheel validate has no verdict to record; and the inspector never writes a validated event because flywheel inspect never touches gate output — only flywheel validate does, and it always signs its own readings "supervisor", never "inspector".

Log layout

The event log has two layouts, both append-only: the legacy single-file layout (.flywheel/events.jsonl) and the sharded layout (files under .flywheel/events/). Both are opt-in; flywheel log --shard is the only way to switch, and the switch is one-way: once a repository uses the sharded layout, older binaries cannot read it safely (they reject the unknown log.shards config field). The config key log.shards is written by --shard and fences out older binaries.

Legacy layout

The legacy layout is a single .flywheel/events.jsonl file, one JSON event object per line, appended by AppendEvent.

Ledger directory (`ledger.dir`)

Both layouts live in .flywheel/ by default, so a project that commits the log sees it rewritten by every branch switch and conflicted by every merge. The opt-in configuration key "ledger": {"dir": "<value>"} in .flywheel/config.json moves the log (events.jsonl or events/) outside the checkout (issue #464). Values:

"home": <user home>/.flywheel/ledgers/<id>, where <id> is the first 16 hex characters of the sha256 of the absolute, forward-slashed path git rev-parse --path-format=absolute --git-common-dir prints, so every worktree of one clone shares it;
an absolute path;
~/<path>, under the user’s home.

The environment variable FLYWHEEL_LEDGER_DIR, when non-empty, overrides the config value (same value forms). Unset, every path is exactly the in-tree one. The log’s location is read from the ledger key alone, never through the full config validation, so a broken unrelated key never hides the log. Refusals, each an error naming the path and ledger.dir:

flywheel refuses to load a config whose ledger.dir is empty or a relative path;
a resolved directory inside the checkout’s work tree or its git directory;
a set ledger.dir while the in-tree log (.flywheel/events.jsonl or .flywheel/events/) still exists — two live logs; the error says to run flywheel ledger move.

flywheel ledger move [--dir DIR] [--json] is the one supported migration of the in-tree log into the ledger directory. It holds the in-tree .flywheel/events.lock for the whole move, copies events.jsonl and every file under events/ (the relative layout kept, @floor.jsonl included, *.tmp skipped; a symlink is refused) into a temp directory beside the destination, fsyncs each copy and compares it byte for byte with its source, then renames the temp directory onto the destination (a missing or empty one; a destination holding only locks/ keeps it and takes the copy’s entries). It then sets the in-tree files aside under .flywheel/ledger-move.old/, runs the chain verification against the destination and only then removes them from the working tree; a verification error puts them back and exits 1. A destination already holding byte-identical copies (a crash between the rename and the removal) resumes straight to the removal, and a crash after the set-aside is put back and resumed on the next run. A destination holding any other log or file (except locks/) is refused with exit 6, rule two-live-logs, and both are left untouched; the temp directory never survives a failure. With ledger.dir unset, or refused, it exits 2; with no in-tree log it prints nothing to move and exits 0. Git is never run for writing: when git tracked the in-tree log, the command says to commit its removal (git rm --cached is not run).

Readers never create the directory; writers create it. The locks that guard the log move with it: <ledger dir>/locks/@events.lock (in-tree: .flywheel/events.lock) and the per-shard <ledger dir>/locks/<shard>.lock (in-tree: .flywheel/locks/<shard>.lock), so two checkouts that share one ledger directory serialise their appends. The other .flywheel/ locks stay in the checkout. The pre-push hook verifies the log when ledger.dir or FLYWHEEL_LEDGER_DIR is set.

flywheel doctor follows ledger.dir: a refused value or two live logs is a warning carrying the error; with it set the git-tracking and merge=union checks are skipped (the log is meant to be outside git) and it warns only when the resolved directory exists and is not a directory or not writable (probed with a temp file it removes; a missing directory is fine, the first append creates it). In both modes a leftover .flywheel/ledger-move.old/ warns that a flywheel ledger move was interrupted after setting the in-tree log aside: run flywheel ledger move again before any other flywheel command. flywheel fleet counts a directory whose ledger directory holds events.jsonl or events/, and one whose ledger.dir is set but refused (its row carries the error); it de-duplicates by the event log’s location, so the worktrees of one clone sharing a ledger directory are listed once, under the first path reaching it. flywheel init with ledger.dir set (config or env) creates no .flywheel/events.jsonl and omits that piece, and fails on a refused value. A new .flywheel/.gitignore from init lists runs/, worktrees/, locks/, claims/ and leases/ (per-host runtime state); an existing one is never rewritten.

flywheel verify with ledger.dir set and a resolved directory that holds neither events.jsonl nor events/ (a CI runner, or any host but the one the log lives on) is inconclusive, never a vacuous pass: before any task or chain check it prints flywheel verify: inconclusive: ledger.dir places the event log at <dir>, which holds no log on this host (it is outside the checkout, so this checkout cannot be audited) to stderr (with --json, the result JSON with one LOG item, pass false, inconclusive true and that reason) and exits 8; a refused ledger.dir exits 1. Unset, or an external directory that holds a log, verifies as before. The flywheel init --ci workflow skips its “the event log is not committed” pre-check when .flywheel/config.json has a "ledger" key or FLYWHEEL_LEDGER_DIR is set, so that exit 8 reaches its ::warning:: inconclusive branch (which names both causes: a tree this checkout cannot resolve, or ledger.dir keeping the log outside the repository) and the job passes without establishing anything. An existing workflow is never rewritten: rerun flywheel init --ci after deleting it to get the guard.

flywheel ledger backup with ledger.dir set also copies the external events.jsonl and every file under events/ (complete lines only, *.tmp and symlinks skipped as in .flywheel/, the directory’s locks/ and anything else left out) into the copy’s .flywheel/, so manifest paths stay .flywheel/events.jsonl and .flywheel/events/..., and records the resolved directory as the manifest’s (and --json result’s) ledger_dir. A ledger directory that does not exist yet is fine: no events are copied. A destination inside the ledger directory is refused like one inside .flywheel/. The copy’s chain is checked by its own files, never by the live directory its copied config.json names. To restore, copy <path>/.flywheel back, except that with ledger_dir in the manifest the event-log files go back into that directory (or flywheel ledger move them there).

Sharded layout

The sharded layout puts events under .flywheel/events/:

Per-task shards: one file per task, named <task>.jsonl, holds all events for that task (every event with that task id in the task field).
Global events: @floor.jsonl holds events that have no task (session_start, session_end, session_command, staffed, goal, lead_edit, and amended events whose brief is in the global briefs directory).
Session boundary events: @session-<id>.jsonl holds every session_start, session_command, and session_end event for that session, so a reader can reconstruct a session’s view efficiently.

Readers merge events in this order: legacy file first, then stable by each shard’s running-max timestamp (the timestamp of the last appended event in that shard), which preserves the global linearized order while allowing shards to operate concurrently. Each shard has its own hash chain with a genesis block (the first event appended to that shard) and a sharded event at the moment the layout is switched (kind sharded, with fields identical to other seal events). flywheel verify --log checks each shard’s chain separately and also the merged order across shards.

Transient locks under .flywheel/locks/ guard concurrent writes (one per shard, named <task>.lock); they are git-ignored. The locks enforce per-shard write order and are consulted by readers to detect in-flight appends, but readers never wait — a slow reader may observe partial state, and consistency is per-file, not cross-shard. Deletions and trimmed tails in a shard are not detected by the chain (the seal block lives at insertion time, not at mutation time); only appends are tracked.

Backups

flywheel ledger backup <path> (#464) is the supported way to keep an extra, point-in-time copy of the ledger; it is not an alternative to committing it (the ledger is committed with merge=union, and flywheel doctor warns when it is untracked or lacks that attribute). It copies .flywheel/ to <path>/.flywheel/ but leaves out the top-level worktrees/ and locks/ (live process state, not records), every *.tmp file, and symlinks or junctions (it lists them instead of following them). events.jsonl and every shard under events/ are copied by complete lines only: a trailing partial line still being appended is left out and counted. The copy is built in a temp directory next to <path>, then renamed onto it. <path>/flywheel-backup.json records the creation time, the source, each file’s path, size and sha256, the skipped paths, the partial-tail bytes, and the result of VerifyLogChain on the copy. A broken chain is recorded, not fatal. To restore, copy <path>/.flywheel back.

5. `flywheel verify` and exit codes

flywheel verify [<task>...|--all] [--json] [--log] [--shipped] [--workdir PATH] runs T1/T3/T4/T5/T8/R1/W1/P1/L1/V1 for the requested tasks (--all derives the task list from every task seen in the log), plus S1 with --shipped (every task needs an inspected pass or a landing, issue #861; §2), and prints one PASS/FAIL/INCONCLUSIVE line per rule per task, or the same result as JSON ({"passed": bool, "items": [{"task","rule","pass","inconclusive","reason"}]}; inconclusive is omitted when false, so --json consumers of the existing fields keep working). --workdir names the repository to resolve tree objects in when the readings were taken in an external clone (issue #244); without it, a workdir recorded on the task’s reading events is used when that path still exists. --log checks the event log’s hash chain (T10, issue #57): every event’s prev must match the SHA-256 of some earlier complete line; --log fails (exit 6) at the first line whose prev matches none, indicating a line was edited or removed. When that dangling prev is the hash of a LATER line in the same file, the break reason is reordered: line N chains to line M, which comes after it (a git merge or an edit reordered the log; no record is missing). A git merge or conflict resolution of a committed ledger does this. It is still a break, but no record is missing (issue #422); otherwise the reason is prev matches no earlier line. Either layout prints <file> line N: <reason> (prev <12 hex>).

Acknowledged breaks (issue #436). The ledger is append-only, so an explained break is never repaired by an edit: flywheel log --reanchor --note "<why>" [--force] [--session S] [--dir DIR] appends a reanchored event (floor level, no task) through the normal append path, so the acknowledgement is itself chained. It carries file (the log file as the chain check names it: events.jsonl or events/<task>.jsonl), line_no (the 1-based break line, display only), break_prev (the dangling prev, full hex), sha256 (the break line’s hash — the identity of the acknowledged line), reason (reordered when the break reason starts reordered:, else removed) and note (why, required). The command refuses (exit 6) when the chain is intact, when the break is not a dangling prev (a missing seal, a line with no prev, a wrong shard genesis), and when the break classifies as removed without --force: a removed break may be a real edit or deletion, and --force records the decision that it is explained. --reanchor does not combine with --kind, --task or --json, and --note is required (exit 2). The chain check (all layouts) first reads the log’s reanchored events; a break is acknowledged when one has the same file, the same break_prev, a sha256 equal to the break line’s hash, and a reason equal to the classification computed now — a reordered acknowledgement never covers a line that now classifies as removed. An acknowledged break does not stop the scan; each later break needs its own acknowledgement. --json lists them under acknowledged (file, line, reason, session, note), and a passing --log and flywheel recover’s integrity line append ; acknowledged break at <file> line N (<reason>), by <session>: <note> for each.

Preventing reorders. A repository that commits .flywheel/ should merge the event log with git’s union driver, which keeps each side’s appended lines in order, so every prev still resolves to an earlier line. flywheel init writes .flywheel/.gitattributes with events.jsonl merge=union and events/*.jsonl merge=union; it never rewrites an existing file, so an older repository adds those two lines to .flywheel/.gitattributes by hand and commits it. An INCONCLUSIVE item is pass:false with inconclusive:true: the pass’s tree could not be resolved in any repository this verifier can see, so T3 can neither confirm the readings nor assert a breach. Naming a task explicitly still runs every rule for it even if the log has never heard of it — a missing planned brief, for instance, fails T3 by name rather than being skipped. An empty log verified with --all passes vacuously; verifying with no tasks and no --all is a usage error — except --log alone, which checks only the chain.

Exit codes follow the repo-wide convention from AGENTS.md: 0 ok, 1 error, 2 usage, 5 gauges failed, 6 rule refusal, 8 inconclusive. The enforcing commands:

Command	Success (0)	Refusal	Other
`flywheel validate <task>` (or `--group`)	every gate passed, nothing outside `owns:`	5 — a gate failed, stayed host-blocked after one rerun, a changed path is outside `owns:`, or a claude worker never loaded a skill its brief named (`skills-not-loaded`, issue #695; `skills.require_loaded` false turns it off); 6 — `RuleRefusal` naming `needs-env`, `stage` (an invalid `stage:` line, issue #781), `full-suite`, `required-gates`, `required-live-gates` (issue #845), `required-observes` (issue #848), `owns-companions` (issue #785), or `group-owns` (`validate --group`: two members own one `owns:` entry or one changed path, issue #775)	2 usage, 1 other error
`flywheel inspect <task> --verdict ... --session ...`	inspection recorded	6 — `RuleRefusal` naming T3, T4, T8, `review` (an open blocking review finding), `red-first` (a `kind: fix` pass with no gate red on the base tree before dispatch, issue #648; `lint.red_first` false turns it off), `ci-escape` (CI failed after every gate in the brief passed and the brief has gained no gate since the newest `ci_failed` event, issue #776), `skills-not-loaded` (a claude worker never loaded a skill its brief named, issue #695; `skills.require_loaded` false turns it off), `denied-write` (a path whose write the harness denied changed anyway with no lead claim, issue #757), `panel` or `lead-built` (a pass on a unit with no dispatched attempt over `lead_built.max_changed_lines`, issue #722; `--exception` records why) and its fix	2 usage, 1 other error
`flywheel attest <task> --commit <sha> --evidence URL --session S`	external readings recorded	6 — `RuleRefusal` naming T3, T4 or T5	2 usage, 1 other error (e.g., the commit is not in the repository; a commit that resolves but whose tree cannot be computed reports git’s own error naming the step, such as read-tree, #907)
`flywheel observe <task> --check N --result pass\\|fail --evidence REF --session S`	observed reading recorded (#842)	6 — `RuleRefusal` naming T4 or T5	2 usage, 1 other error (e.g., a check outside the brief’s observe lines)
`flywheel verify [...] [--json]`	every requested check passes	6 — any check fails (`FAIL <task> <rule>: <reason>`)	8 — every failing check is `INCONCLUSIVE` (no violation established, the tree could not be resolved); 2 usage, 1 other error
`flywheel land <task> --commit <sha> [--exception TEXT --session S]`	landing recorded, or repeats an already-landed commit	6 — `RuleRefusal` naming T5 or T4 (T5 includes a commit off the integration branch or touching none of the unit’s files)	8 inconclusive (the commit or every integration ref does not resolve: run `git fetch`), 2 usage (e.g., –exception without –session), 1 other error
`flywheel inspect --group <group> --verdict ... --session ...`	every member’s inspection recorded	6 — the first member’s `RuleRefusal` (any rule `inspect <task>` refuses), naming the member; nothing recorded	2 usage (a task id with `--group`), 1 other error
`flywheel land --group <group> --commit <sha>`	every member landed, or already landed on the commit	6 — `RuleRefusal` naming T5 (a member not passed: nothing lands) or a member’s `land --commit` refusal	8 inconclusive, 2 usage (a task id, or `--merge`, `--by-lead`, `--exception`, `--correct`), 1 other error
`flywheel land <task> --correct <sha> --reason TEXT --session S`	`land_corrected` recorded	6 — `RuleRefusal` naming T5 (no landed event, the commit is already the effective one, or it fails land’s commit checks) or T4 (a worker session)	8 inconclusive (the commit does not resolve: run `git fetch`), 2 usage (a conflicting flag, or no –reason or –session), 1 other error
`flywheel run <task>`	`rc == 0` and finish `reason` was `stop`	—	3 silent (no output within the start timeout); 7 stalled (the run-file gap watchdog fired mid-stream, issue #158); 6 suspended (a `flywheel suspend --stop` stopped the worker, issue #572); 4 any other outcome (nonzero `rc`, or `reason` `length`/`error`/`start-failed`); 2 usage or no worker configured; 1 other error

flywheel run’s own codes (3, 4, 7, and 6 for suspended) are not part of the repo-wide list: they are ExitCode’s reading of one Result, keyed by exit number instead of by command, and AGENTS.md records them as run-specific. Exit 7 means stalled — a mid-stream gap — and nothing else, so a consumer scripts exit codes per command, never globally:

Exit	`flywheel run` reason
3	`silent` — no stdout line arrived within the start timeout
4	any other non-clean outcome — nonzero `rc`, or finish `reason` `length`, `error`, `rate-limited` (after any resumes), `abandoned-job` (after its one resume), or `start-failed`
6	`suspended` — a `flywheel suspend --stop` stopped the worker at a lease tick (issue #572); `flywheel resume` continues it
7	`stalled` — the run had started but the run file stopped growing for the stall timeout (issue #158)

Everything upstream of these five commands — writing a brief, deciding what belongs in owns:, choosing which task to dispatch next — is judgment the protocol does not check; the CLI enforces only what is above.

flywheel protocol v1

Contents

1. Required entries per task

planned

dispatched

dispatch_refused

worktree_setup

staged

unstaged

started

worker_plan

no-plan

off-course

finished

report

reviewed

review_finding

finding_response

panel_scoped

group_reviewed

blocked

lost

withdrawn

rebased

recovered

landed

land_corrected

excepted

allow_untriaged

audited

release_audited

health

suspended

unsuspended

probed

gate_probed

amended

validated

resource_wait

worktree_discarded

retro

recommitted

owns_checked

inspected

ci_failed

staffed

session_start

session_command

session_end

learning

note

lead_edit

goal