fab-kit · src/kit/skills/fab-operator.md · v9 · 903 lines

Operator Tick Anatomy

What the operator checks each tick, why PR #913 slipped through, how to collapse five tracked-thing schemas into one, which cron kind fits, and where rk should grow.

loaded per reload
3,425 lines
skill 903 + _cli-fab 1,475 + _preamble 545 + _cli-agents 255 + _cli-external 247
git choreography
235 lines
dependency cherry-pick, 3 merge modes, ordered merge, auto-merge — the operator's main job; stays inline
tracked-thing schemas
5 + 1
monitored, watches, autopilot, notes, branch_map, plus the merge sequence hidden inside a note
things probed per tick
1 kind
tmux panes. Linear/Slack only via a watch; GitHub only for an armed merge; notes never

1 · What a tick does today

Every tick runs the seven steps in §4 Tick Behavior. Each step reads one section of the state file and talks to one external source. The picture is worth drawing because the gaps are structural, not accidental: whole classes of tracked things have no arrow to anything that observes the world.

state file (server-keyed yaml) tick · 7 steps · §4 external world monitored: {change → pane} keyed by tmux pane id · fab stages watches: source linear|slack Go rejects any other --source autopilot: {queue, current} fab change ids only notes: free prose dependency_wait · phase_plan · coordination · correction no probe, no last_checked, not in frame branch_map: {id → branch, repo} 1 Snapshot fab operator tick-start --diff binary diffs panes vs baseline → deltas, candidates 2 Auto-nudge fab pane questions answer waiting/idle agents via rk mux send 3 Watches for each watch: MCP query dedupe vs known/completed → spawn 4 Autopilot advance · merge-seq check gh only while a coordination note says “armed” 5 Removals fab operator remove ack of level-triggered deltas 6 observed fields — no-op, binary owns baseline 7 clock — no-op, verbs mute/unmute Frame quiet tick → one line 🛰️ Operator · 22:03 · tick #5121 · 3 tracked · no change tmux panes @rk_pane_agent_state · fab status Linear / Slack (MCP) list_issues · read_channel GitHub (gh) pr view · pr checks · pr merge rk cron “operator tick” backoff 60s→30m · wake on state change read at Init only · “operator judgment” branch_map → deps at spawn snapshot every tick send-keys only enabled watches only armed PRs operator tick (bare text) → runs steps 1–7 “tell me when #913 merges” no state section reaches this same for: a non-fab branch, a deploy, a cron job, a Linear ticket you don’t want to spawn from, a CI run…
Figure 1. The tick is a fixed sequence of kind-specific steps. Only the pane-keyed monitored set is diffed by the binary. Linear and Slack are reached only through a typed watch, GitHub only while a merge sequence is armed, and notes are prose the agent is trusted to re-verify with no mechanism that makes it do so.

2 · Where PR #913 fell through

The self-analysis in the screenshot is accurate about the symptom. The cause sits in the skill text, not in the session's discipline.

21:51 t9hb pipeline done → completion delta fab operator remove t9hb — correct #913 leaves the only probed set ticks #5119 – #5123 · 21:52 → 22:06 tick-start --diff --quiet → deltas: [] → compact frame “no change” — and the skill forbids any other per-tick output the n34/W1 wait lives in a note; nothing re-polls it 22:07:54 #913 merges on GitHub no delta, no wake, no arrow in Figure 1 22:09 user asks answer from memory
Figure 2. Once t9hb was removed, the PR it produced was outside every mechanical probe. The dependency wait had been routed to a note, exactly as §4 Notes instructs, and notes are re-verified only by “operator judgment per tick”, with quiet ticks explicitly told to emit nothing else.

Three lines in the skill together produce this outcome:

The Go side agrees with the prose: operator_watch.go rejects any --source other than linear or slack, and tick-start only enumerates tmux panes. So your read is right. The tracked-thing model is fab-change-shaped, and everything else is a special case bolted to its side.

3 · One tracked-item model

The fix is not a sixth section for GitHub. It is to make every tracked thing the same shape, so that the binary can poll all of them in one loop and the LLM only decides what to do about changes. The operator's job statement then becomes literally what you said: hand me something long-running, I will watch it and act when it moves.

tracked: [] — one shape - id: pr-913 kind: github-pr probe: shell · gh pr view 913 --json state done_when: .state == MERGED then: spawn n34 in ~/code/hexokit depends_on: [] last: {state: OPEN, at: 22:03} - id: t9hb kind: fab-change probe: pane - id: DEV-988 kind: linear probe: agent - id: deploy kind: shell probe: curl … - id: n1 kind: note probe: none monitored · watches · autopilot · notes → kinds tick · binary fab operator tick-start --diff runs every probe: shell|pane diffs vs last, evaluates done_when lists probe: agent items due for a check emits: changed · done · needs_check · stale operator · llm act on deltas only changed → evaluate then prose needs_check → run MCP probe, track observe waiting agent → auto-answer (unchanged §5) done → track rm (the ack) frame: one table, all kinds id · kind · state · checked 4m ago · next unverified items get ⚠ instead of silence world tmux panes GitHub · gh any shell probe (curl, kubectl, test) Linear / Slack · MCP (agent-side) rk cron “operator tick” mute when tracked is empty unmute on first track add read all deltas · needs_check track add · observe · rm (verbs, never hand-writes) every item renders, with age since last check
Figure 3. One list, one probe loop, one frame. A fab change is the item whose probe is the pane snapshot; a Linear watch is an item whose probe the agent runs over MCP because the binary cannot; a PR is a shell probe. Notes are items with no probe, and because they render with an age, a stale one is visible instead of forgotten.

What this buys you, in the terms of the #913 incident: fab operator track add pr-913 --probe 'gh pr view 913 --json state' --done '.state==\"MERGED\"' --then 'spawn n34…' would have produced a done delta on the first tick after 22:07:54, and the operator would have spawned n34 without being asked.

4 · The frame

The table the operator prints every tick is the only surface where a stale item can be seen. Today it has two tables (changes per repo, then watches), no column for when a thing was last verified, and no row for notes. Proposed: one table over every tracked item, a column for freshness, and a column for what the operator will do next. Rendered as the terminal shows it:

🛰️ Operator · 22:03 · tick #5121 · 6 tracked · idle-every 3m · skip-if-busy
IDKindStateCheckedNext
▶t9hbfab · ~/code/hexokit🟢 review · activelive—
n34fab · ~/code/hexokit⏸ held—waits on pr-913
▶pr-913gh pr · hexokit#913🟡 OPEN · checks pending2m agospawn n34 when MERGED
▶DEV-988linear · DEV🟢 In Progress11m ago ⚠notify when Done
deployshell · curl staging🔴 exit 1 · 3 fails1m agoescalated
n1notephase 2 of 4 — auto-merge armed behind s2gw3d—
pr-913: OPEN → checks pending · DEV-988: unverified 11m (cadence 5m) · deploy: probe failed ×3, auto-paused

And the quiet tick, still one line, now carrying the live cadence read from rk cron list --json:

🛰️ **Operator** · 22:06 · tick #5122 · **6 tracked** · idle-every 3m · no change · 1 waiting

The markdown source the operator emits for the full frame, shown fenced here only so the page can display it:

🛰️ **Operator** · 22:03 · tick #5121 · **6 tracked** · idle-every 3m · skip-if-busy

| | ID | Kind | State | Checked | Next |
|:--:|---|---|---|---|---|
| ▶ | `t9hb` | fab · ~/code/hexokit | 🟢 review · active | live | — |
| | `n34` | fab · ~/code/hexokit | ⏸ held | — | waits on `pr-913` |
| ▶ | `pr-913` | gh pr · hexokit#913 | 🟡 OPEN · checks pending | 2m ago | spawn `n34` when MERGED |
| ▶ | `DEV-988` | linear · DEV | 🟢 In Progress | 11m ago ⚠ | notify when Done |
| | `deploy` | shell · curl staging | 🔴 exit 1 · 3 fails | 1m ago | escalated |
| | `n1` | note | phase 2 of 4 — auto-merge armed behind s2gw | 3d | — |

*pr-913: OPEN → checks pending · DEV-988: unverified 11m (cadence 5m) · deploy: probe failed ×3, auto-paused*

Rules: kept and changed

RuleTodayProposed
Render channelbare markdown, no fence, no headings; tables, emoji, bold, italic, code spans, URLskept
Emoji is the only colour🟢 🟡 🔴 ✅ ⚪; geometric glyphs bannedkept, adds ⏸ held on a dependency
Header🛰️ **Operator** · HH:MM · tick #N · **N tracked**same, plus · <schedule> · <deliver> read from rk cron list --json, never composed
Two shapesfull on a delta, every 10th tick, or on request; one-line compact otherwisekept; a stale or probe_error delta also forces the full frame
Groupingone anchor + table per repo, then a Watches tableone table; scope moves into the Kind column (fab · ~/repo, gh pr · repo#N, linear · PROJECT)
▶ markerautopilot-queue memberthe item has a then: the operator will act on its next change
State columnStage, optional ⚠️ for >15m idlehealth emoji + last observed state verbatim from the probe's declared field; fab items keep stage · agent
Checked columnnone (watches had "Nm ago" in Status)age since last successful probe; live for pane items; ⚠ once past the item's check_every; 🔴 at twice it
Next columnPR URLthe armed action in five words or fewer; the URL moves to the footnote line when it changes
Notesabsent from the frame; only in fab operator staterows like any other item, Checked shows age since update
Footnoteitalic, ·-separated actionskept; changed-field deltas render here too (OPEN → MERGED)
Idle messageseparate "Waiting for next tick" line between ticksdeleted; the compact line already carries time and tick
Nothing else per tickno echo of the tick document, no per-candidate lineskept

Ordering: kind, then scope, then id, so fab items stay together and a Linear item never lands between two changes of the same repo. Items removed this tick render once with ✅ and their closing footnote, then vanish. A held item shows what it waits on, so a dependency chain reads top to bottom without opening the state file.

Where it lands. The cadence suffix on the header rides fab change A, since it only reads released rk output. Everything else is change B: the Kind, Checked and Next columns exist only once items carry kind, checked_at and then.

5 · Simplifications, in order

  1. Replace the five state sections with one tracked list.

    Each item: id, kind, probe (pane | shell <cmd> | agent <instruction> | none), done_when, then (prose), depends_on, last, checked_at. Monitored entries, watches, autopilot queue entries and coordination notes become kinds with defaults. The clock predicate becomes “tracked is non-empty”, which is simpler than today's four-clause disjunction. branch_map can stay as a side lookup, or ride as item metadata.

  2. Make tick-start --diff poll every item with a mechanical probe.

    Today it enumerates panes. Extend it to run shell probes (bounded timeout, argv-only, stderr swallowed) and evaluate done_when as a small predicate over the probe's JSON. Items whose probe is agent come back in a needs_check block with their age, so the LLM is told what to verify rather than trusted to remember. This single change closes the #913 class of bug.

  3. Keep the git choreography in the main skill; tighten it in place. decided 2026-09-11

    Dependency resolution, the three merge modes, ordered merge and auto-merge are 235 lines, but they are the operator's main job, and they must survive a compaction reload: an armed merge sequence whose procedure lives in a helper the operator has to remember to load is the #913 shape again. So they stay where the reload guarantees them. In the generic model they operate on items with depends_on rather than on a separate autopilot block, which removes the duplicated "satisfied" definitions and the note-based persistence of the merge sequence. Realistic trim in place: 235 to about 180 lines. The three mode diagrams stay; the mode question requires them.

  4. Demote fab-only rules from principles to the fab-change kind.

    “Route pipeline-first”, “spawn in a worktree”, the hard wt gate at startup, stage-validated flags and “completion = review-pr done” are all correct for a fab change and wrong for everything else you listed. Keep them as the defaults that kind carries. A task kind whose then is “open an agent tab with this prompt” covers a normal change; a linear kind with no then covers a ticket you merely want to watch.

  5. One frame, one table (§4).

    Replace the change table plus watches table plus the ten-row element-format table with a single table over items: id, kind, state, age since check, next. Keep the health emoji as the only colour channel and keep the compact quiet-tick line. An item not verified within its expected cadence shows ⚠ unverified 14m, which is the visual that would have caught #913 by tick #5121.

  6. Notes become items with probe: none, and they render.

    Drop the four note kinds and the routing-doctrine table. A note is a tracked item a human will resolve; it shows in the frame with its age, and the “stale after 14 days” flag already exists in note list. This also removes the paragraph that currently tells the agent merge-gate waits are its unaided responsibility.

  7. Prune the operational scaffolding once the model is uniform.

    Candidates: the two-rung version-skew fallback, the pre-cron /loop fallback (rk is a hard dependency of the operator in practice), the duplicate no-fence warnings, the Spawn-Session inference's four evidence tiers (default to “session of the target repo's other agents, else ask once”), and the “Idle Message” section. Each is defensible alone; together they are why the file is 903 lines.

Line budget

SectionLines todayFateEst. after
Header, §1 Principles, §2 Startup110Keep; principles lose fab-only rows70
§3 Safety45Keep as is45
§4 Clock, mute/lease, reload57Keep; predicate simplifies45
§4 State file, monitored, branch_map, notes108Collapse to one item schema40
§4 Tick + frame + idle message113Generic loop, one table55
§5 Auto-nudge74Keep, it is the best part70
§6 Spawn + Working a change65Keep; session inference trimmed45
§6 Dependencies, autopilot, merge modes, merges235Keep inline; re-point at items, dedupe the "satisfied" definitions180
§7 Watches54Become a kind; conversational map stays20
§8–9 Config, key properties42Keep35
Total903≈600

The estimate is a target, not a measurement. A third of the file describes kind-specific exceptions to a loop that can be written once; the choreography third stays.

6 · What to keep untouched

One caution on shell probes. A probe string in the state file is executed by the binary on every tick. That is fine for a user-owned XDG file, but the verb should refuse a probe that is not an argv list, run it with a short timeout, and never pass it through a shell. The rk cron respawn argv in §4 already follows that shape.

7 · The clock: which cron kind

Verified against run-kit's backoff.go, not only the doc page. The ladder's anchor is the operator pane's own last non-clock activity: an agent-state epoch within 120 seconds of the entry's latest delivery is attributed to the tick and the ladder keeps climbing; an epoch outside that window is genuine activity and resets to rung 0.

backoff 1m→30m · what moves the ladder +1m +2m +4m +8m → 16m → 30m… wake_on fire a delivery too → attributed, no reset PR merges invisible to rk · no reset tick turn > 120s reads as real work → reset you type to the operator non-attributed epoch → rung 0 +1m +2m +4m Rule: agent events are always fast via wake_on regardless of rung. The rung only sets the polling floor for things wake_on cannot see, and only the operator's own activity tightens it. For external items that means a 30-minute floor once the fleet is quiet, and no external event can shorten it.
Figure 4. What resets the backoff ladder and what does not. Both channels of the operator-tick entry write to the same delivery log, so a wake fire is attributed like a scheduled one.
KindAnchorSees external changePane-only operatorGeneric tracking
everylast deliveryby polling at a fixed floorfine, slightly wastefulgood: predictable floor
cronwall clocknowrong shapeper-item schedules only
backoffoperator pane's last genuine idleby polling, thinning to 30mbest with wake_onpoor: floor erodes
--idle-every 9aupsame, flat ladder (min = max)by polling at a fixed floor, re-phased on your activityfinebest with skip-if-busy
wake_onother panes' state edgesnoessentialessential for agent items only

What 9aup adds, and why it changes the answer

Recommended entry for the generic operator

schedule:  idle-every 3m            # every 3m when no epoch is available
wake_on:   { event: agent-state-change, scope: server, debounce: 60s }
deliver:   skip-if-busy             # no queued tick backlog, no tick after every exchange
if_absent: respawn · pinned

Two consequences to accept: a wake_on fire that lands mid-turn is dropped too, so the interval must stay short; and an operator parked on its own permission prompt skips every tick until answered, which is why it runs with bypass permissions.

Who turns the knob

The operator changing its own schedule "as the work changes" is right in aim and wrong if it is a per-tick LLM judgment, which is the #913 failure class again. The split that works:

  1. LLM decides cadence per item, once, at track add.

    "CI here takes about 8 minutes", "poll the deploy every 2 minutes until green". It becomes the item's check_every.

  2. Binary derives the entry's schedule from the tracked set.

    No external items: backoff 1m→30m, keeping the fade. Any external item: idle-every min(check_every) with skip-if-busy. Applied through rk cron edit on the same hook that mutes and unmutes, only when the derived value changes.

  3. User overrides conversationally, bounded.

    "Hold the ticks for 30 minutes" stays a lease. "Check every 15 minutes for the rest of the day" is an edit with an expiry the reconcile respects.

  4. The frame shows the live cadence.

    Ready line and compact tick line carry every 3m · skip-if-busy or backoff 1m→30m, read from rk cron list --json, never from memory.

Mechanical note for run-kit: switching kinds re-anchors. A switch to every 3m fires on the next poll if the gap already exceeds 3 minutes. Harmless, but the edit spec should say so.

8 · Substrate: fab pane vs rk mux

Both, layered. The operator still calls fab pane map --all-sessions and tick-start --diff, but since the cli-layering work those source their pane list from rk mux panes --json whenever rk is present, with a silent tmux fallback. rk is the substrate; fab adds change, stage and PR enrichment from the worktree's status files.

JobOperator usesUnderneath
Enumerate panesfab pane map, tick-start --diffrk mux panes --json, tmux fallback
Read a screen, process tree, killrk mux capture / process / killfab's twins demoted to dispatch-internal
Send text, answers, keysrk mux send, --answer, --key, --forceraw send-keys fallback
Readiness after spawnfab pane readydelegates to rk mux await --ready
Spawn a workerraw tmux new-window -t -P -F -n -c "cmd; exec $SHELL"no rk verb
Mark tracked windowsfab pane window-name prefix » / ›raw window rename
Detect prompts on uninstrumented panesfab pane questionscapture-scan
Agent-exited livenesstick-start walks the process tree itselfduplicates rk mux process
Clockrk cron entry, mute/unmute from fab verbs

rk gaps, by payoff status 2026-09-11

  1. A probe-fingerprint wake source. rejected

    Decision: probes stay in fab. A raw output fingerprint has too many unrelated ways to change, so it would wake the operator on noise. The mitigation belongs where the item is defined: at track add the LLM names the field to compare (.state, .mergedAt), and tick-start diffs only that. Original proposal kept for the record: wake_on: { event: probe-change, argv: [gh, pr, view, "913", --json, state], every: 2m }. rk polls external state inside its own 30-second ticker and fires the operator only on change. Polling leaves LLM turns entirely, the operator stays on backoff, and the #913 class is closed at the substrate. It has a target and a delivery, so it fits rk's own scope rule. A repo-boundary decision: settle it before the fab tracked-item work.

  2. A spawn verb. released · wzve

    rk tab new takes no session target, cwd or command. A verb taking -t session, -c cwd, the command, a name, optional --ready, printing {session, window_id, pane_id} deletes §6 step 7 and its escaping paragraph.

  3. Window marking through options, with setters. released · hzih

    rk renders @rk_win_marker, @rk_win_color, @rk_win_note but they are set only by raw tmux set-option. A rk tab mark verb plus a "tracked by operator" treatment retires the »/› rename hack.

  4. Liveness in the enumeration row. released · 7pek

    Add has_agent to rk mux panes --json so tick-start can drop its own process-tree walk, the most intricate code in the operator binary.

  5. Structured schedule in rk cron list --json. released · r5ao

    Today schedule is the display string backoff 1m→30m. Deriving and editing needs {kind, min, max, interval}, deliver and wake_on as fields.

  6. Prompt classification. released · a7g2

    fab pane questions is substrate work living in fab. An rk mux capture --classify is its natural home. Small and last.

Not a gap: fleet waiting. rk mux await --any blocks the caller and needs re-arming; the cron wake_on edge already does that job without a foreground process.

9 · With rk released: what else leaves the prose

Two facts change the arithmetic. First, the operator already cannot run without run-kit in any useful way: the clock, the role mark, the send gate and the spawn readiness probe are all rk. Second, the skill loads four helpers, and the biggest of them is a reference for every fab command when the operator uses four. The cuts below assume 9aup and the five backlog items are shipped.

  1. Make run-kit a hard dependency and delete every fallback.

    27 rk-absent or raw-tmux fallback passages in the skill and 12 in _cli-agents: raw send-keys, the /loop degraded clock, the ntfy / Discord / PushNotification / Slack notify ladder, rk-less pane-map notes, the two-rung version-skew procedure, and every scattered command -v rk gate. One startup check replaces them: rk present and at or above the version carrying the six verbs, else stop with the install line.

  2. Load the operator's slice of _cli-fab.md, not the file.

    1,475 lines loaded, about 400 used: fab operator, fab pane, fab agent, fab resolve. Split those into _cli-operator.md, or make helpers section-addressable in the frontmatter. This is the single largest context saving available and needs no run-kit change.

  3. Pre-send validation becomes "send via rk mux send; a refusal is the answer".

    §3 items 1 and 2 and _cli-agents § Pre-Send Validation paraphrase rk's own gate table. Keep the policy line: --answer for waiting, --force only on explicit user confirmation. The Delivery Probe section goes too; the paste probe and bounded recovery are rk's.

  4. Spawn is one call.

    rk tab new --session =S --cwd <wt> --name <n> --ready --json -- <cmd> returns {session, window_id, pane_id}; track add reads them. §6 step 7, the escaping paragraph, and the -P -F explanation go. Session inference keeps the three-line majority rule over rk mux sessions; the four-tier prose goes.

  5. Markers replace renames.

    rk tab mark and rk tab note replace the »/› choreography, its exit-code handling and the "window rename skipped" log line. fab pane window-name leaves the operator entirely.

  6. The clock section shrinks to the rule and the knob.

    Structured rk cron list --json renders the ready line from fields, so the four literal variants collapse to one template. Delete the seeded-entry YAML copy and the "how the union predicate covers the retired loop" history. Add the derived-schedule rule and rk cron edit in three lines.

  7. Question detection is rk mux capture --classify.

    The §5 detection paragraph and the fab pane questions contract pointer become one line over the tick's waiting-first candidates. The answer model and the strategic table stay; they are the skill's judgment, not substrate.

  8. agent_exited reads has_agent.

    The longest bullet in _cli-fab § tick-start, the shell-basename list and the process-tree walk semantics, becomes: command is a shell and has_agent is false.

  9. Probe contract, given the boundary decision.

    Every mechanical probe declares the fields it compares; tick-start never diffs raw output. That is the false-positive guard the rejected rk wake could not offer, and it is why the field choice sits with the LLM at track add.

Revised budget, all files the operator loads

FileTodayWhat changesTarget
fab-operator.md903§4 items 1–7 plus the cuts above; rk mandatory; choreography kept inline (≈180)≈480
_cli-fab.md1,475operator loads only its slice≈350
_preamble.md545unchanged, shared by every skill545
_cli-agents.md255pre-send, peek and probe sections point at rk skill mux≈120
_cli-external.md247/loop section deleted; wt moves to the fab-change helper≈80
Loaded per reload3,425≈1,575

Targets are estimates. The operator's reload cost is dominated by files it does not own, so the largest cut is a loading change, not a rewrite. The choreography is the one large block that stays, by design.

10 · Sequencing

Decided: probes live in fab, not rk. Assumed done: 9aup (edit, skip-if-busy, --idle-every) and backlog items wzve, hzih, 7pek, r5ao, a7g2.

  1. fab change A: loading and dependency.

    rk becomes mandatory; the operator loads _cli-operator.md instead of _cli-fab.md; every fallback passage is deleted; the compact line and ready line gain the live cadence from rk cron list --json. Otherwise no behaviour change, largest context win, safe to ship alone.

  2. fab change B: generic tracked list, probe loop, derived schedule.

    Go verbs and tick-start extension with field-scoped probes, one-table frame, §4 and §7 rewritten as kinds. Ready line from structured cron JSON, spawn via rk tab new, markers via rk tab mark. Autopilot becomes a chain of items with depends_on; the choreography sections are re-pointed at items and tightened in place, never moved out. The one-table frame (§4) lands here.