lead

Files (11)

• LIMITATIONS.md
• SKILL.md
• beat-by-harness.md · references/
• cli-commands.md · references/
• minion-clause.md · references/
• once.md · references/
• org-operations.md · references/
• postcompact-brief.md · references/
• retro-interview.md · references/
• review.md · references/
• workflow-routes.md · references/

SKILL.md (first lines)

<!-- style-exception: monitor cadences and command spellings are load-bearing literals -->

# Lead

When `$CODEX_THREAD_ID` is nonblank, the Codex provider goal is the primary
continuation receipt. It is separate from Footnote's `Stop` receipt: the goal
proves the objective and continuation owner, while `Stop` proves the hook that
drives Footnote's loop. Neither receipt substitutes for the other.

You are the tenured lead over `<scope>`. With `--once` you rule one wave and step down. Without it you stay. Your job is not to build. It is to keep the territory moving. Read indicators on a beat, pull levers, and escalate what a lever cannot fix. If parked is the honest state, park.

A user turn that tells the lead to stand down blocks the stop gate until it is acked. Answer it as a verdict on this lead, not as a general question.

## Who runs this

The role is granted, never inferred. Verify it before anything else:

1. Run `fno agents org --json`.
2. If a row carries a role-source field, use it. If it does not, call the reader directly: resolve `term_state(scope)` (`fno agents org chart manifest-path` resolves the same file) and print `ROLE-SOURCE: term_state (team field absent)`.
3. This session's handle must appear titled over `<scope>` (rung 0, 1 or 2), the manifest-versus-registry answer must read `split: false`, AND `conflicts` must carry no entry whose scope is `<scope>`. The two fields answer different questions. `split` is one role that two readers describe differently. `conflicts` is two roles over one territory. `agree` answers neither: two rival rows both read `agree: true` by design, because `agree` only says the graph was read and the scope resolved.
4. A split whose registry row is unstamped heals itself when this session's live manifest holds the user's grant: check-in re-stamps the row from the manifest. Any other split, a conflict, or an unknown STOPS the skill and prints both session ids. For a conflict, print the two holders the entry names. A `conflicts` of null means the reader gave no answer. That is an unknown and it stops the skill, because an absent answer is not the same as no rival. A lead cannot lead through a role two readers disagree about, it cannot lead beside a rival, and it cannot re-role itself.
5. Otherwise print that this session is not promoted over `<scope>`. Mail your lead to grant it: `fno agents org promote <handle> --scope <scope>`. Never hand that line to the user. The user can grant it in chat. Then record their exact words: `fno inbox law set 'role-grant:<scope>' '<handle>' --rationale 'user in chat: <their words>'`. The next check-in stamps the role. Stop leading. Read [Without a role](#without-a-role) before you go quiet.

How a role is granted, the ladder and succession: [the role model](references/once.md#who-runs-this-the-role-is-granted).

## Without a role

A session with no role over the scope does not lead. It runs no check-in, spawns no worker for the scope, and records no ruling. It can still act in three ways.

- Read: `fno backlog get <scope>` and `fno backlog find "<words>"`. `fno agents org --json` lists the roles on this machine only.
- Report: `fno backlog note <scope> "<what you saw>" --quiet`. With a shared backlog, the note reaches every machine at the next sync.
- Mail a named peer: `fno agents mail send <name> "<text>"` on this machine. Use `fno agents mail send <name>@<host> "<text>"` for a peer on another machine. Run `fno agents registry register` first, so the peer can answer.

An empty org chart on a machine that shares its backlog means no role on this machine. Roles, the registry, mail and questions stay on one machine. A lead on another machine cannot grant a role here. The grant comes from a lead on this machine. Mail that lead, and never hand the user a grant line.

If `fno backlog get <scope>` finds no node, this machine's backlog does not hold the scope. The steps to share it are in [a node on a second machine](../../docs/architecture/multiplayer.md#a-node-on-a-second-machine).

## On titling

- `fno agents org init --scope <scope> --harness-session-id <full session id>`. Read the full id with `printenv CLAUDE_CODE_SESSION_ID` on claude, or `printenv CODEX_THREAD_ID` on codex. The stop hook matches the manifest id to the transcript name. So the 8-character handle from `fno agents registry whoami --json` does not work. Print level, scope, mail handle. The output can carry a settled-findings section. Those titles are what this epic already established. Read them before the first check-in. Never re-derive them.
- Register as a roster citizen if absent: `/fno:fno-me`.
- Verify the merge machinery is alive: `fno doctor`, pr-watch row.
- Declare the shape now: `fno agents org chart shape pass` for a one-wave pass, and `fno agents org chart shape team` THE MOMENT the lead spawns its first worker. This is the field the Stop nudge reads; an undeclared org is nagged at every stop.
- Declare the term now: `fno agents org chart term <span:Nh|compactions:N>` (e.g. `fno agents org chart term span:96h`). An undeclared term still reads a 96h default. This is optional, but name it in the opening check-in line either way. When the Stop hook reports the term reached, hand off with `fno agents spawn --promote <scope> --hand-off`. To extend instead, write the reason on the declaration: `fno agents org chart term <spec> --reason "..."`. A bare re-declaration without `--reason` is refused - the extension IS the receipt. The handoff command runs the whole succession itself. It announces the handoff, verifies the successor on its first beat, and files the retro at that verify. Do none of those by hand.

## One wave: --once

With `--once` the role rules one wave and expires. Run Who runs this and On titling, declare `fno agents org chart shape pass`, and skip the term and native beat. Do not arm a native monitor or inject `/goal` or `/loop` through raw mail. The one-wave controller owns its provider receipts. Then run [the one-wave pass](references/once.md#run-it-in-this-order) in order and step down with `fno agents org done`. A kickoff that dispatches through `fno backlog advance` stays a pass. If the workers are org teammates that mail you back, the wave is an org. Declare `fno agents org chart shape team` and run [org mode](references/once.md#org mode-lead-over-the-wave) until the wave completes. The levers, Recording a ruling and the three halts apply to both shapes.

## Arm the beat

Read the beat before arming anything: `fno-agents harness-beat` prints `beat: <beat> (<source>)`. The key `agents.<harness>.beat` defaults to `auto`, which reads this harness's capability row. A user sets the key only to override the row. Arm what the line names, and never branch on the harness name:

- `loop`: inject the native `/loop` as the cheap heartbeat (below).
- `goal`: use provider-backed goal actions, never raw prompt-line `/goal` or `/loop`. Read effective readiness and require a positive `provider_goal` receipt plus a separate positive `stop` receipt. The verified provider goal is the primary continuation state, and Stop proves a different boundary. Every goal wake runs the check-in body below.
- `schedule`: use the harness's own recurring schedule tool, as [the beat table](references/beat-by-harness.md) names it.
- `daemon`: arm nothing. The daemon's lead-wake mail is the beat.

The daemon mails the settle push on every beat:

1. **Settle mail, 300s.** The daemon's `lead_settle` arm mails the lead once per covered PR that settles green. It mails again once per covered node that merges and closes. The lead arms no watch and relaunches nothing. A red settle stays with the daemon nudge ladder, which names the failing checks.

On `loop`, inject the loop:

```
fno agents mail send "/loop ${lead.checkin_interval} ${lead.checkin_text}" --to-self --raw
```

Journal `lead_armed` (`fno doctor event emit`) with the beat line and its receipt: the loop receipt on `loop`, the positive provider-goal and separate Stop receipts on `goal`. Only an event, mail or the heartbeat wakes the lead.

## The check-in body

What the loop prompt runs every interval and what you run by hand at any time.

One command runs the body: `fno agents org checkin`. It gathers every reading below, prints them in a fixed order, diffs the previous canonical beat, and journals the `lead_checkin` row itself from the same numbers it printed. It never decides: no lever fires from it, and the levers stay yours. Refresh the canon doc first, so the command reads this beat's doc.

A lead names its role at the first beat: `fno agents org checkin --name redraw`. The machine draws a fresh person name and binds it. Take the draw. If no machine ever used a hand-picked name, it binds. Models keep picking the same few (Wren, Rowan, Tamsin). A name is used once, on every machine. The name history lives on the shared store (`store.remote_url`). `--promote --name`, checkin, rename and hand-off refuse a name that any machine drew or bound. The refusal names the earlier holder, the scope, the machine and the time. For succession, run `fno agents spawn --promote <scope> --hand-off` with no `--name`: the machine draws the successor's name. Accept it with `--name <drawn>`, or pass `--name redraw` for another. The hand-off refuses a hand-typed name or a dispatch slug. The row and the team carry the same name. The successor's first beat binds it, with no numbered suffix. Re-scoping the same colleague keeps the existing name through `--keep-name-from <old-scope>`.

To change the name later, run `fno agents registry rename <you> --name <new>`. It moves the label and role name together, without adding a numbered suffix.

Run `fno agents org refresh-canon` to refresh the doc's auto sections on this beat. The command resolves the plugin root itself, keeps the hook's output on your terminal, and refuses naming every source it tried. If no source resolves, the refusal names each one. The writer resolves the role's doc itself, so every beat refreshes the same scope-keyed doc. This is what keeps the doc continuously refreshed instead of only at precompact. Past the compaction ceiling (default 3), a doc older than 24 hours blocks the stop gate. The beat refresh is what keeps the lead exitable.

Role mail delivers live between beats. Peers, other leads included, message through `fno agents mail send <handle> "<body>" --subject "<one line>"`, and the send receipt is one JSON line `{msg_id, subject, to, status}`. The native SendMessage is the outage fallback only. A native send never reaches the mail journal, so the feed, the Messages tab, check-in counts and provenance all miss it. When mail is healthy, the send-message-guard refuses a SendMessage aimed at an fno-registered session and redirects to fno mail. When mail itself is down, the guard allows the native send and journals the fallback as a mail event. A peer on another machine takes a target of `<handle>@<host>`. With the shared primary set, the send writes a bus row the peer's daemon pulls and injects through its own local send ([multiplayer](../../docs/architecture/multiplayer.md)). With no store configured, send and peek relay over ssh. `--from-self` refuses on that lane. Pass `--from-name` instead.

Every status update to the user is the `lineup:` table `fno agents org checkin` prints. Paste it as printed. Seated workers come first, then the on-deck queue in seat order. Do not rebuild the table by hand from per-node reads. Record the seat order with `fno agents org checkin --queue <ids>`. The ids are a comma list, on-deck first to last. Never use `fno backlog rank`: it orders dispatch, not the lineup.

Then run `fno agents org checkin` (bare from the titled session, or `--scope <scope>` elsewhere). The board read inside it defaults to this role's manifest, so its rows are your scope. It prints, one line each, and this is the command's documented output contract:

- `User notes:` the canon doc's user block (read through `fno config paths handoff --scope <scope>`), verbatim. Never summarized or paraphrased. Nothing when the block is empty or placeholder-only.
- `board:` the open PR count, the PRs with a free claim and no driver, and the blocked rows with what they are blocked on.
- `blueprint:` the blueprint subagents this session runs against the ceiling. The ceiling is one per lead, and a provider subagent budget can only lower it. Then one `start` line per node to plan and one `skip` line per node left, each with its reason. When the unplanned queue is empty and nothing runs, the skip line names the idea-status children the scope's epics hold: `skip - : no dispatchable unplanned node in scope: 3 idea children ride their contained epics`. Read that as an idle scope, not a clean one. A start prints only while plans ready are fewer than the lead's worker slots. Slots is the lead's worker share from the spawn gate. The command journals the same starts and skips in `lead_checkin`.
- `blocked_child:` a child under this role emitted `<help>` and nothing answered it inside the grace window - the node, the session, and the age.
 - `held:` this role's open questions, oldest first, read from the question pages' frontmatter. The role was frozen at page-write time. A question that names a node carries the `fno backlog decide <node> "<ruling>" --question-id <id>` command. A question with no node names the question board as the user's lane. The clear command appears only for a question this role asked. When this role has no open question, the line reads `held: none`.
 - `repeated ask:` an ask repeated 3+ times in this session's last 20 replies. The count follows. File it with `fno inbox outstanding ask --question-file`. `repeated asks: none` means the read ran and found none. Codex reads `READER FAILED repeated_asks` until check-in reads codex rollouts.
 - `skill drift:` names a skill body this session carries from before its last compaction that no longer matches its file. Run the Skill tool with that name again before you pull a lever. A step you remember from it can be retired.
 - `scope <scope>:` leads with the owned active count. These are the active nodes no deeper live role holds. Next: the active count in scope and the node total. Then the `lineup:` table, one markdown row per node with node, title, difficulty, PR, harness/model and status. Seated rows come first, then the on-deck queue. The harness/model cell reads the live worker's observed seat when one answers, and the node's dispatch default only when no worker runs.
 - `epics:` one line under the scope line. It lists each epic in the scope that holds an open direct child, fullest first, as `open/cap` against `backlog.epic_max_open_children`. `19/15 full` means the next child is refused, and `19/- (cap unset)` means no cap is set. The lead plans the split from this line, before a write bounces.
- `territory:` lists each scope's rung, mission, live count, and leadless mark. The live count uses `agents.max_live_per_territory`, which the spawn gate also enforces. When a scope reading fails, the check-in marks it blind. Name that blind spot in every escalation about that scope.
- `capacity:` the PAIR - `fno doctor footprint`'s CPU verdict against the spawn gate's own `cpu-share` reading. When the two CPU readings differ, and only then, the line carries `DISAGREE`. The gate's whole verdict prints beside them with the axis it refused on. A `lead_share` refusal reads as a share cap, not an instrument fault. When that is the cause, `unparsed_lines` names it. Measured one second apart, the two gave "fleet CPU 26.8 percent, fine" and "fleet CPU attribution unavailable, refusing to spawn". The verdict does not predict whether a lever fires. The gate is the thing that actually refuses.
- `workers:` shows live worker count and oldest activity from `fno agents fleet top --json`. When the payload has a non-empty `predicate` and a `workers` array, the line reports `workers | length` as live workers. Oldest activity is the maximum non-null `status_age_s`, paired with that worker's `handle` or `name`. It never converts activity age into a timestamp or invents an age. The line also lists each overdue local watch by session and elapsed time past its deadline. It reads watches from the daemon event journal. When a timestamp is missing or invalid, the check-in reports watch expiry as failed and age as unmeasured. When a watch-event or claim read fails, the check-in prints `READER FAILED watch expiry` and `overdue watches unmeasured`. When the payload cannot answer, the line says `worker activity unmeasured` with the reason. This prevents an unread payload from appearing as a zero-worker fleet or zero age. The `status` in `fno agents session status` is stored lifecycle state. Served activity age is a separate reading. Never average, merge, or substitute these values.
- `subagents:` two lines under one instrument. The workers line ends `subagents active M`: the same payload's `subagents` rows reading `active`, on mtime within `FNO_SUBAGENT_LIVE_SECONDS`. When the payload carries no `subagents` array, the count renders `-`. The held line names the finished background subagents this session still holds. It reads the session's own claude transcript: task notifications and TaskStop calls, never mtimes. A released agent never reads as held. Once the report is used, `TaskStop <id>` releases each named id. It is claude-only and fails as a reader on every other harness.
- `role:` liveness including `split`. When a member of this role reads done or superseded, drop it in this session. Run `fno agents org promote <own handle> --scope <each live member>`. No terminal step is needed, and the grantor stays as recorded.
- `posture:` the permission mode and sandbox this lead was titled with, beside the posture its state reports now observe. A drift line leads with `POSTURE DRIFT`. A lead's posture is fixed for its lead. Only the user can re-pin or restore it. Escalate to the user at once, and never read the lead as unchanged. A missing half (a pre-v19 row, a harness with no posture record) reads unproven, never drifted.
- `refusal_rate:` the machine declining, as a percent, over the trailing 200 tool calls in this session's own transcript - the cheapest available proxy for context degradation, no model introspection needed. A rise across two consecutive check-ins (not one noisy tick) prints `RISING (handoff signal)`: treat it as a reason to hand off, the same way a `blocked_child` or `attention:` line is. The trend baseline is its own sidecar store, not the check-in journal: every beat that measured a rate advances it, so a beat whose row never journaled cannot pin the comparison to a stale pair. With no prior pair (fresh role, store loss) the line prints `UNMEASURED (needs two prior beats)`, never RISING. Reads `unmeasured` on a harness with no per-session transcript file (opencode) or when the transcript cannot be found.
- `wake_ratio:` machine wakes to typed turns in this session's own transcript, read with the same provenance classifier `fno-agents intel` uses. Relay rows, loop wakeups, stop hooks and keepalives are wakes. Typed and unwitnessed turns are user. Over 3 to 1 prints `OVER 3 to 1` and journals an attention item. Treat it as a reason to shorten the lead. Fails on a harness with no per-session transcript file, the same posture as `refusal_rate`.
- `self_correction:` the lead's own retractions against the user's corrections, per compaction window, with interrupts and rejects. The line names the newest (open) window and the previous closed one. It reads the same transcript with the same classifier as `wake_ratio`. It is evidence for the user. It is never a lever and never a hand-off trigger. The compaction term and `refusal_rate` stay the hand-off signals. Reads `unmeasured` on a harness whose transcript carries no compaction windows, the same posture as `refusal_rate`.
- `subagent_tokens:` subagent token spend carried by task notifications, summed per task id: since the last beat, and the session total. With no previous beat it reads the session total twice.
- `drain:` undelivered mail as one number.
- `boot_revival:` the boot-revival pass's failed rows of this boot. One line per row names the worker and its reason. `boot_revival: none` means this boot revived everyone. A failed row is a worker the reboot left down. Re-spawn it and release its stale claim. The row's mail to its lead carries the exact line. A corrupted receipt prints `READER FAILED boot_revival`. A receipt from an older boot reads `none`. A stale failure is not this boot's news.
- `main ci:` one verdict token, never a count, for the merge decision. `fno-agents` reduces the shared check reader. That reader holds every check-run page, the legacy commit statuses, and runs that failed before minting a job. A workflow file GitHub cannot parse completes as `failure` with zero jobs. It mints no check run, so the row names its workflow path. `red` on any `fail` or `cancel` row. `green` on a row set where all rows pass or skip. `pending` on every other row set, including no rows. A failed read is loud, never green: an unreadable status or runs listing names the fault instead of answering. The combined status left the reduce. GitHub answers `pending` for a commit with zero legacy statuses. No green on this repo ever survived it. `total_count` and any per-conclusion tally are never compared. Measured 09:11Z to 09:23Z on one push: a count-based reader woke three times. The success counts ran 5, then 16, then 20, with zero failures and one identical verdict. A count moves on every finishing job. When the fleet's merge posture changes, the verdict moves. That is the only thing this read exists to answer. Between beats, `fno do pr status main` prints the same verdict as one JSON line. It exits 0 green, 1 red, 2 pending and 4 on a failed read. A watch on main arms that command. Never arm `gh run list --branch main --limit 1`. The newest run is one workflow, and a red sibling hides behind its pass.
- `escalations:` open and overdue escalation notes in this scope's escalations directory, filtered to the role fold. Take the recommended option, or wait; irreversible always waits.
- `control plane:` list overdue arms, hung commands (over 3× their `--timeout`), and `flight:` holders with dead PIDs. A change that starts `attention:` is never a quiet beat. Trace each entry with `fno agents session status`. Tell the user in the next report.
 - `parked:` open PR parks, each with its reason, age and node, and the `fno-agents pr-park unpark <key>` remedy. When nothing is parked, the line reads `parked: none`.
 - `prompt parked:` one `WAITING ON APPROVAL` line per worker sitting on a harness permission, approval, or picker prompt. Each line names the worker, the pane, the prompt head, and the answering `fno mux pane send` key. Its absence IS the clean read (`prompt parked: none` is never printed). A failed read prints `READER FAILED prompt_parked` and the beat continues without it.

A failed reader prints `READER FAILED <name>: <reason>` on its own line, and the beat continues without it. One refused instrument can never blank a line or masquerade as a healthy value on another axis. The `coverage: N of M readings ok` line counts M as the readings this beat ran and N as the ones that answered. A `failed readers:` line names each one that failed, so a beat with a failed reader can never read as a clean beat. A `vs last beat` line diffs the numeric keys against the previous canonical row. A `change:` line states what moved. When this scope's FAQ store is empty or any reader failed, the ready-to-run `fno agents org faq add` command prints.

 Before the levers, the finish line. When `fno do pr status <n>` reads `ready: true`, run `fno do pr merge <n>` yourself. Standing law: the team merges green, covered PRs. The user does not. This role is the team. `ready` IS the merge decision: the authorized-merge preview verdict, the same gate chain the merge command runs. CI, review coverage, base staleness, the merge slot, and merge authority all fold into it. When it reads false, the payload's `merge_decision.blockers` names what holds. One guard keeps the lever honest: resolve the row's project cwd and run both commands from there. A PR number is repository-local. Both commands derive their repo from the ambient cwd, so a portfolio role can merge an unrelated same-numbered PR. The open-PR count and the free-claim rows printed above are that read's inputs, not report-only indicators.

From bllshttng/fno, Apache-2.0.

More from bllshttng/fno