@joshuafolkken/kit 1.1136.0 → 1.1178.0

package/.claude/skills/workflow-commands/backlogrun-park.md

@@ -15,7 +15,7 @@ authorization, whether it came from a named epic or from the opted-in pool:
 - **A stop that would end the run parks one issue and the run continues** — → "park
   and continue", which is that rule's single source, including what happens to the issue's lane.
 - **A prerequisite discovered mid-run is recorded as a dependency rather than parked** —
-  → "A prerequisite discovered mid-run", and `SKILL.md` → §2d for the three-way
+  → "A prerequisite discovered mid-run", and `prerequisite.md` for the three-way
   distinction between a prerequisite, a split and an upstream defect. **One thing is genuinely
   different**: with no epic, there is no `pnpm josh epic --add` to record the ordering into, so the
   prerequisite is filed with `route:tier-a` and the blocked issue is parked with `needs-decision`
@@ -58,8 +58,8 @@ untouched**, for the same reason. **Name the lane directory in the stop report a
 person told to look at a working tree and not told which one has been told nothing. The lanes already in
 flight finish; no new lane is opened.
 
-**Never apply or remove the label** — `auto-ok`'s rule, at `auto-ok`'s strength. Full definition and the
-`needs-decision` comparison: `SKILL.md` → §2z, which is the single source.
+**Never apply or remove the label** — a person's alone. Full definition and the
+`needs-decision` comparison: `needs-human-review.md`, which is the single source.
 
 ## park and continue
 
@@ -75,13 +75,11 @@ pnpm josh issue:comment <N> --body-file <path>   # what needs deciding, and the
 `needs-decision` precedence over `in-progress`, so the next child is offered normally. Then return to
 step 1; the other children are unaffected unless they depend on this one.
 
-**What happens to a parked child's lane depends on whether it had committed, and the two answers are
-opposite.** **Parked before its commit**, the lane is stashed and closed:
-`git -C <dir> stash push -u -m "backlogrun: parked #<N>"`, the stash recorded on the Issue, then
-`pnpm josh lane:close <N>` (`epic:next` counts a parked child's lane as released, and `lane:close`
-removes the work tree by force). **Parked after its commit and push**, the lane is *kept*: nothing to
-stash, and closing would delete the local branch the resume needs. **A lost merge race is not one of
-these rows** — it resolves in its lane ("Conflicts are not predicted" above), and parks only under that
+**A parked child's lane is kept, whether or not it had committed.** **Parked before its commit**, the
+uncommitted work stays in the lane's tree — never in the stash, which every work tree shares — and
+`lane:close` would remove it by force. **Parked after its commit and push**, closing would delete the
+local branch the resume needs. **A lost merge race is not one of
+these rows** — it resolves in its lane (`backlogrun-recovery.md` → "Conflicts are not predicted"), and parks only under that
 section's four conditions, which take the after-commit row. Both rows and the `pnpm josh run:release
 <N>` every parked ending owes are "What happens to a lane" above, the single source.
 
@@ -101,7 +99,8 @@ gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/needs-decision 2>/dev/nu
 
 **The released child goes back to a lane, never into the parent's own context.** A parent that is
 *already* running, and clears a label mid-run because a person just answered, dispatches it the same way
-rather than picking up its diff itself — `pnpm josh lane:open <N>` then `pnpm josh lane:dispatch <N>`. A
+rather than picking up its diff itself — `pnpm josh lane:launch <N>`, which dispatches into the lane the
+park kept, or opens one where none is. A
 parent that implements the released child inline is the failure the orchestrator rule is written against:
 "The parent orchestrates and never implements a child in its own context" above.
 
@@ -110,8 +109,10 @@ human-in-the-loop cycle, not an optional tidy-up.
 
 ## `in-progress` is removed by whoever finds it stale
 
-Nothing in the codebase removes `in-progress`; a normal finish closes the issue. An interrupted run
-leaves it behind, and a child that carries it is excluded from every future `epic:next` — permanently.
+A run's own ending removes `in-progress` — `pnpm josh followup` on a merge, `pnpm josh run:release <N>`
+on a stop. An interrupted run reaches neither and leaves it behind, and a child that carries it is
+excluded from every future `epic:next` — permanently. The removal below is the one hand-written call
+left, for a label no live run owns: another tree's record is not this tree's to release.
 **A session that detects a stale child removes the label itself** (Tier A) and reports it, before
 continuing the loop.
 
@@ -140,7 +141,7 @@ gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null
 
 Finding that something else in **this** repository has to land first is not a split, and not an upstream
 defect. The child in hand is still one deliverable; it just needs another one before it. The three-way
-distinction, the `route:tier-a` filing command and the filing ceiling are `SKILL.md` → §2d, the single
+distinction, the `route:tier-a` filing command and the filing ceiling are `prerequisite.md`, the single
 source; what follows is this entry's branch.
 
 `<M>` below is the child being implemented when the prerequisite turned up; `<N>` is the new Issue.
@@ -166,7 +167,7 @@ source; what follows is this entry's branch.
 3. `pnpm josh epic --add <E> <N> --before <M>` — one command writes the task-list row, the declaration
    and the `blocked-by` relation together. Never edit the body by hand: the declaration and the relations
    then disagree, `epic:next` returns `error`, and the unattended run stops.
-4. **Remove `in-progress` from `<M>`** — `gh api -X DELETE repos/{owner}/{repo}/issues/<M>/labels/in-progress 2>/dev/null || true`.
+4. **Remove `in-progress` from `<M>`** — `pnpm josh run:release <M>`, which removes the label with the hold.
    This is what lets `<M>` run again: `epic:next` classifies a child carrying `in-progress` as waiting on
    time **before** it looks at any blocker, so a child left labelled is never offered again.
 5. **Do not park.** Go back to step 1 of the loop. `epic:next` classifies the original child as resolving

package/.claude/skills/workflow-commands/backlogrun-progress.md

@@ -1,148 +1,18 @@
 # `backlogrun` — progress, the hand-off, resume and waiting
 
-**Read this file in full before the progress watcher starts** (`pnpm josh run:progress --wait`) and
-before the hand-off check at a child's merge (`pnpm josh cost --cut`). It is a point-of-use
-document, never an entry read: the entry procedure is `backlogrun.md`, which points here at those
-steps (joshuafolkken/kit#2010). This file is the single source of the heartbeat, the session hand-off
-and cut/resume, waiting without waiting forever, and the end-of-run summary and propagate.
+**Read this file in full before the first child is dispatched** and before the hand-off check at a
+child's merge (`pnpm josh cost --cut`). It is a point-of-use document, never an entry read: the entry
+procedure is `backlogrun.md`, which points here at those steps (joshuafolkken/kit#2010). This file is
+the single source of the session hand-off and cut/resume, waiting without waiting forever, and the
+end-of-run summary and propagate. **The heartbeat is not here** — it binds every implementing run, so
+its single source is `progress-watcher.md` → "Progress while the run is quiet" (joshuafolkken/kit#3172),
+read before the watcher starts.
 
 After a carry hand-off, the detached `run:wake` supervisor runs the deterministic `backlog:drive`
 loop. References below to a parent's mechanical polling and lane collection describe work now done
 by that supervisor; an AI parent is started only for a driver branch that requires judgment.
 
-## Progress while the run is quiet
-
-**Start the progress step before step 1 of the loop, and do it without being asked.**
-
-```bash
-pnpm josh run:progress --wait --output <the transcript path of each delegated unit>   # in the background
-```
-
-**Start it once; it reports by itself** (joshuafolkken/kit#3102). Each silence interval appends the
-five labelled lines to the run's event stream as a heartbeat and to the ambient log, prints nothing to
-standard output and keeps running — so a scheduled report never wakes the parent, and the parent
-relays none. **It exits only on one of three, and the command computes which:**
-
-| Exit                                                    | What the parent does                                                   |
-| ------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Newly runnable backlog work (the `ready #N` line)       | Read the ready line, act on it, and restart the watcher in that turn  |
-| `pnpm josh followup` removed the run's life record      | Nothing — the run has ended                                            |
-| `--hours` elapsed (8 by default for `--wait`)           | Restart the watcher in that turn                                       |
-
-**`pnpm josh run:watcher:guard` detects a missed restart** (joshuafolkken/kit#2113): it refuses when
-lane children are in-flight but the watcher's life record has gone stale. **It is wired into
-`pretool-guard`, the one `PreToolUse` hook** (joshuafolkken/kit#2353), so the next tool call is refused
-until the watcher is restarted — once per run, so the `pnpm josh run:progress --wait` that fixes it is
-not blocked.
-
-**`run:progress` writes the five labelled lines itself (joshuafolkken/kit#2026).** It emits the observation instant (`at`, local first and UTC beside it), the elapsed figures
-(`quiet` and `unchanged`), the children in flight, the run state (`lanes`, `load`, `record`), and the
-scheduled `next`, each behind its own label and on its own line — so where a session does present them
-(`--once`), it relays the output verbatim and rounds, rephrases or re-labels nothing. How each field reads when it has nothing to report (`record
-unread`, `no in-progress child yet`, `lanes none`, an absent `next`) is fixed by the command's own unit
-tests. **A value said that way is still an observation, never a state**: `record unread` means no
-`--output` path was given, not *not stalled*; `lanes none` is *no lane is open*, not *nothing is
-running*; and the `next` line is a schedule — the time *if the silence continues*, superseded when a
-real report resets the clock through `--mark`.
-
-**A report is not an exit, and neither is a decline** — with no run recorded it keeps waiting, and the
-`--hours` exit says so on standard error.
-
-**`--mark` at every real report.** Whenever this loop reports something of its own — a child merged,
-parked, a stop — run `pnpm josh run:progress --mark` in the same turn to restart the silence clock. The clock is silence, never a timer
-(`docs/josh-commands-automation.md` → "`josh run:progress`").
-
-**Do not keep a progress clock of your own** — the hook refuses the arm rather than asking
-(`scripts/rules/early-heartbeat.ts` → `decide`), though **a single correctly-spaced arm is allowed**. It
-is still not the way to report; the step above prints without arming anything, and `--wait` is not a
-wait timer. Rationale: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the heartbeat reads
-as it does".
-
-**The default interval is twenty minutes, overridable — by the person, not the run.**
-`JOSH_PROGRESS_INTERVAL_MINUTES` moves both sides (the guard reads it through the watcher's reader);
-`josh` → `progress_interval_minutes` in `package.json` sits one step below the variable. **`--interval`
-moves the watcher alone** — it makes the watcher quieter than the floor, never the guard stricter.
-
-**An explicit ask is not a heartbeat, and it is exempt by construction.**
-**Every unscheduled progress statement is answered by `pnpm josh run:progress --once`** — presented in
-the same five field lines, the reply to an explicit ask and the note just after a run starts alike.
-**Never write a clock time the command did not print** (not an approximation, not a placeholder — where
-a field is missing, say so). **`--once` records the report**, so no `--mark` beside it.
-
-**Every report opens with the time the observation was taken** — not only how long it has been quiet: an
-absolute instant, `at YYYY-MM-DD HH:MM±HH:MM / YYYY-MM-DDTHH:MMZ`. **It is added, never substituted for
-the elapsed figure**, and **the presented line needs no stamp computed for it** — the command prints the
-`at` stamp and the `next` field.
-
-**The line carries observations, never "still running", and nothing in it is a verification result** —
-no gate, CI or check rollup, because the command reads none of them. Rationale:
-`docs/maintainers/backlogrun-progress-rationale.md` → "Why the heartbeat reads as it does".
-
-**The invariant is a tier, not a mechanism** (joshuafolkken/kit#2156, joshuafolkken/kit#2207). Three
-tiers say how much of a person's attention a signal takes: **interrupt** reaches for it now (a Telegram),
-**ambient** is seen without being asked for, and **requested** is read only when a person types for it.
-**The heartbeat sits at the ambient tier, and stays there across a `backlogrun` session cut — never
-promoted to interrupt, never demoted to requested.**
-
-**The report surface belongs to the run, not to the session** (joshuafolkken/kit#2207). The run's
-session-facing events — a plan posted, a child launched, a PR opened, a review round, a park, a cut, a
-stop, a merge — are appended to one ordered stream keyed to the run's identity (`pnpm josh run:event`).
-**Every session is a writer;
-the reader is a script in a pane of the person's own, never a conversation** (#2492):
-`pnpm josh run:event --watch` prints each event the moment it lands, in the session language, and the
-`heartbeat` events say the run is alive when quiet. **No session relays the stream** — name the watch command once, at the first cut or when
-asked. **It is the same reader before and after the cut**: a cut moves who executes, never where the
-stream lives.
-
-**Interrupt is withheld on purpose**: no Telegram for the heartbeat. **`pnpm josh run:wake --list` is the requested tier** — the last-event read of the stream the
-watch pane reads, for a person who types for one line rather than watching. **`tail -F` on the
-raw stream file is a recovery path, not the ambient surface** — the watch pane is how progress is seen
-without asking, and the raw `tail` is the fallback when the pane has stopped, named for that role in
-`--list`'s own output.
-
-**A stop is an interrupt, and only a stop** (joshuafolkken/kit#2136). A run that has _stopped_ — every
-remaining child blocked behind a parked one, the backlog drained of anything runnable, the failure
-streak tripped — is pushed to the interrupt tier: `pnpm josh run:carry --end --stopped "<reason>"` sends one ⏸️ confirmation
-as it ends the record, and because the record is gone by the second `--end` the same stop never notifies
-twice. A parked child is pushed by the child itself, which records the park and sends its own
-`confirmation` before it stops (`backlogrun-park.md`). Rationale for the tiers:
-`docs/maintainers/backlogrun-progress-rationale.md` → "Why the signal tiers are split this way".
-
-**A heartbeat is emitted from the moment a run has started, even before any child carries
-`in-progress`** — "a run has started" is read from a mechanical record (a registered lane, a held work
-tree, or a carried budget), and the line names that stage as an observed fact (`no in-progress child
-yet`). **Only a checkout with no run recorded at all stays silent.**
-
-**The scope is every implementing run, not this command alone.** `fullrun`, `halfrun` and `backlogrun`
-start the same watcher under the same rules, and this section is the single source for all four; `kickoff`
-starts none. **`halfrun` is included.**
-
-**One watcher per run, and the outermost invocation is the one that starts it.** A `fullrun` running as
-a `backlogrun` named issue or an `backlogrun` child starts none: the brief names the invocation it descends
-from. `backlogrun` starts one for the whole batch. **A dispatched lane child is refused a watcher by its
-`JOSH_LANE_CHILD` mark** — it still runs `--mark` for the parent's clock, but every reporting form
-(`--wait`, `--once`, the default watch) exits at once with a notice.
-
-**In a single-issue run it starts immediately after `pnpm josh run:hold` succeeds.** **It is started in the target repository's checkout, and
-`--mark` is run there too.**
-
-**What counts as a real report when the run has one issue.** A `fullrun` has exactly one child, so the
-unit is **any turn that puts a progress statement in front of the person** — four of them, `--mark` run
-in the same turn as each: **the Step 0 work summary, the pull request opening, each review round's
-verdict, and any `confirmation` / `failure` / `completion` notification or stop.** **A tool result only
-you read is not one** — a gate run, a `gh` read, an edit.
-
-**`--output` is omitted in a single-issue run, and `record` reads `unread`.** Rationale for the
-watcher's scope and placement: `docs/maintainers/backlogrun-progress-rationale.md` → "Why the watcher
-runs where it does".
-
-**A run that merges needs no teardown; a run that stops has to end the reporting itself.** **A stop
-keeps the `in-progress` label on purpose** — so **no further `--wait` is started** after the stop
-notification, and the running `--wait` is stopped in the same turn, since no report ends it. That
-covers `halfrun`'s stop before commit, a `needs-human-review` stop, a split or prerequisite stop, and
-a `backlogrun` named issue's failure stop.
-
-### Running a named epic's children
+## Running a named epic's children
 
 `josh epic:next <E> --repo <this repository> --lanes` prints **one issue number per line** on standard
 output — as many as that repository has free lanes — or, when there is no child to run, the verdict as a
@@ -196,39 +66,11 @@ run in lanes".
    through the same `run:merge --output` classification. **The flag is what you saw, never what kind of
    child it is.**
 
-   When the unit reports back, **confirm the child from GitHub before believing it**:
-
-   ```bash
-   pnpm josh issue:state <N>                          # a child in this repository
-   pnpm josh issue:state <N> --repo <owner/repo>      # a child in another one
-   # state: CLOSED
-   # labels: (none)
-   # human_review: no
-   ```
-
-   **`--repo` is not optional for a cross-repository child.** Without it the read resolves `<N>` against
-   the repository this session runs in.
-
-   `state: CLOSED` is the only answer that means the child finished. **Read the `human_review:` and
-   `labels:` lines before calling anything else a failure.** **A non-zero exit is not `OPEN`**: the command exits non-zero
-   without a state when the number resolves to nothing (`does not resolve`) or the read failed (`could
-   not read`, a rate limit or expired auth). Re-read before deciding.
-
-   - **Open, carrying `needs-decision`** — the unit **parked** it. Not a failure: leave the label on, do
-     **not** count it against the consecutive-failure guard, and go back to step 1.
-   - **Open, and `human_review: yes`** — the child **stopped before its commit**, the run's own ending
-     (§2z). **`Open` is part of the test** — a CLOSED child carrying the label finished and merged.
-     **Read that line, not the `labels:` one.** Leave
-     `in-progress` **on**, do not park it, do not count it, and do **not** go back to step 1. Finish the
-     session and report. **Do not send a second `confirmation` Telegram** — the unit already sent one.
-     Where the child ran in this session's own context, that first notification is yours to send.
-   - **Open, without `needs-decision`** — it failed. Remove the stale `in-progress` here (Tier A), count
-     it against the consecutive-failure guard, and **park it**.
-
-   **Never ask `epic:next` in place of this read.**
-
-   **A merge is one event, and one call of the parent's — `pnpm josh run:merge <N>`**
-   (joshuafolkken/kit#2024). The composite command confirms the child from GitHub, does the post-merge steps, folds in the hand-off check, and prints
+   **When the unit reports back, a merge is one event, and one call of the parent's — `pnpm josh
+   run:merge <N>`** (joshuafolkken/kit#2024). It is the only reading of how the child ended: never
+   classify `pnpm josh issue:state` by hand, and never ask `epic:next` in its place. Rationale:
+   `docs/maintainers/backlogrun-progress-rationale.md` → "Why a child's ending is read by `run:merge` alone".
+   The composite command confirms the child from GitHub, does the post-merge steps, folds in the hand-off check, and prints
    the next child number — or a control verdict — for the parent to read. Pass the merged child's
    number and the offer's source — `--epic <E> --repo <owner/repo>` for a named epic,
    nothing for the opted-in backlog — with `--owner "$PPID"` so it counts into the carry record under
@@ -257,7 +99,9 @@ run in lanes".
    **Beyond the offer `epic:next` prints** (`run` becomes numbers; `wait` / `stop` / `complete` /
    `error` pass through), the composite adds six verdict tokens: `over` — the merge crossed the budget,
    so hand the lanes over and take the cut ("The hand-off" below); `human-review` — the child stopped
-   before its commit, the run's own ending (SKILL.md → §2z), so stop; `stop` — the consecutive-failure
+   before its commit, the run's own ending (needs-human-review.md), so stop — leave `in-progress` on, and send
+   no second `confirmation` Telegram, since the unit already sent one (where the child ran in this
+   session's own context, that first notification is yours to send); `stop` — the consecutive-failure
    guard tripped; `environment` — the consecutive-**outage** guard tripped, so the API is down and the
    run stops as an environment failure rather than the children's (joshuafolkken/kit#2240); `resumed` —
    an unadopted cut was relaunched; `lane:await <N>` it again (joshuafolkken/kit#2484); and `retry` — the child's state could not be read, so re-read it.
@@ -522,7 +366,7 @@ closing with the release tail below. Its output is the Telegram body too — pas
 `pnpm josh notify --body-file`.
 
 **That same session asks `pnpm josh release:scope` once, after the last child has merged** — in the
-primary checkout, after the last lane is closed, and never once per child. `followup-reference.md` →
+primary checkout, after the last lane is closed, and never once per child. `followup.md` →
 "When `pnpm josh release` runs" is the single source for the position and the three answers. `run:report`
 appends that answer as the summary's closing line: on `required` the request and the exact command, on
 `unknown` the word `unknown`, never rounded to `skip`.

package/.claude/skills/workflow-commands/backlogrun-recovery.md

@@ -0,0 +1,155 @@
+# `backlogrun` — recovering a child that went wrong
+
+**Read the section you need at the moment it is needed, never at the entry or before the first child**
+(joshuafolkken/kit#3175). Both sections below are reached only on failure — a unit that went silent, a
+lane whose pull request conflicts with `main` — so a run in which nothing fails never pays for them.
+`backlogrun-child.md`, `backlogrun-lanes.md` and `chain-rule.md` point here at those triggers.
+
+## A delegated unit that stopped without reporting
+
+**A unit can be stopped from outside, and a stop leaves no notification behind** — and a stopped unit
+trips none of `backlogrun-child.md`'s guards, which all assume it is running. **So the parent checks
+rather than waiting — which means it must not be waiting.** **Hand the child to the unit without
+blocking on its return, and poll** at the loop's polling interval; ask once the unit's output has been
+unchanged for the silent-unit window (`| Silent delegated unit | 30 min |` in `backlogrun-progress.md`).
+
+**Note where the unit writes at hand-off; the modification time is read from the file, not carried.**
+**Where the child runs in a lane, that note goes into the lane rather than the conversation** —
+`pnpm josh lane:output <N> <path>`, in the same turn as the dispatch, so it comes back from
+`pnpm josh lane:output <N>` in any session.
+
+**Ask the command rather than combining the traces yourself.** Traces are read **in the checkout the
+unit was given** — this session's own unless the unit was handed a separate work tree, and the stash in
+the recovery below is taken there too.
+
+```bash
+pnpm josh run:liveness <N> --output <path> --process none
+pnpm josh run:liveness <N> --output <path> --process alive
+pnpm josh run:liveness <N> --output <path> --process none --window 45 --repo <owner/repo>
+```
+
+| Answer | What it found | What the parent does |
+| --- | --- | --- |
+| `alive` | The output moved, or a process of the child is running | Keep polling; touch nothing |
+| `stopped` | The output has been frozen past the window and no process of the child is alive | The recovery below |
+| `settled` | The child closed, or the unit parked it with `needs-decision` | Re-read it with `pnpm josh run:status <N>` — one read-only call whose state section says which branch and whose carry counters beside it feed the failure-streak decision — and take the branch its state section says |
+| `undetermined` | A trace could not be read | Read the trace that failed and ask again — and see the two-in-a-row rule below |
+
+**Two `undetermined` answers in a row is a fault in the check, not a slow unit.** The second
+consecutive `undetermined` on the same child ends the polling: send a `confirmation` Telegram naming
+the trace that failed, and stop. **It is never escalated to a `stopped`** — nothing was read.
+
+**Silence and no process together — never either one alone.** **A trace that could not be read answers
+`undetermined`, never `stopped`**, and a process trace nobody gave is an unasked question rather than
+"no process". **Output that moved answers `alive` on its own; a live process is weighed only once every
+trace has answered.** Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why liveness needs
+silence and no process together".
+
+**The path passed to `--output` is absolute** — the command refuses a relative one. **The process
+trace is the one the command does not read for itself**: run it in the unit's checkout and read the
+command lines rather than the names — `pgrep -laf 'josh gate'` etc. — looking for one naming **that
+checkout's path**, since several kit projects may run at once. **Read the file the path points at, not
+the link**: a transcript path is a symlink whose own modification time never changes, so a `stat` typed
+by hand needs `-L` (`run:liveness` follows the link itself).
+
+**A clean checkout is not evidence that the unit is alive** — a stop can come while the unit is still
+reading the skill and the issue. The checkout is read only for whether there is work to stash before
+the child is parked; **"nothing was ever opened for the child" is `pnpm josh run:hold`'s preflight check
+at the start of the next child, not this one's.**
+
+**What follows is what a failed child already gets.** Re-read the child first with
+`pnpm josh run:status <N>` — its state section carries the same `state:` / `labels:` /
+`human_review:` lines `issue:state` prints, and folds in the carry counters this recovery reads
+anyway; then, while it is still `state: OPEN` and not carrying `needs-decision`.
+**A re-read carrying `needs-decision`** means the unit parked the child and then stopped, so fall
+through to the loop's park branch: leave the label on, count nothing against the consecutive-failure
+guard, and go back to step 1.
+
+1. **Stash the half-finished work** — `git stash push -u -m "backlogrun: stopped unit for #<N>"` — and
+   record it on the Issue. `-u` is not optional, and the comment is what gets the stash popped — by
+   message, `pnpm josh stash:pop "backlogrun: stopped unit for #<N>"`, never a positional
+   `git stash pop` that a shared stack lets another lane divert.
+2. **Classify how the child ended and act, in one call** — `pnpm josh run:merge <N> --output <path>`
+   (add `--epic <E> --repo <owner/repo> --owner "$PPID"` for a named epic). **It is the same composite a
+   returned child takes** (`backlogrun-progress.md` → "Running a named epic's children"), reached here
+   from the poll rather than from a return — **one** decision, never a second copy of it. It **reads the
+   child's exit record without waiting for the unit to return**, telling an `outage` — a child that
+   could not reach the API — apart from an `abandoned` one that stopped mid-implementation, and it drops
+   the stale `in-progress` itself, so there is no separate label-removal step:
+   - **outage** — the child never reached the API, so it is counted into its own outage streak and
+     **re-dispatched in the same run** by being offered again, **not** parked with `needs-decision` and
+     **not** counted against the consecutive-failure guard. **The re-dispatch resumes the child's
+     session**: `lane:dispatch` reads the `session_id` off the exit record and relaunches with
+     `--resume`; with no session id it falls back to a fresh `fullrun`, and the report says which path
+     it took. **Outages inside a two-minute window count once** toward the streak. The re-dispatch is
+     bounded by `CONSECUTIVE_OUTAGE_LIMIT` in `scripts/run/run-merge.ts`: *distinct* outages trip the
+     separate outage guard, at which point the command prints `environment` and the run stops. It never
+     re-dispatches into a dead API forever.
+   - **abandoned** — counted against the consecutive-failure guard and parked with `needs-decision`,
+     exactly as a failed child. Never retried silently.
+3. **Read the token it printed and take that branch** — a next child number to run (the re-dispatched
+   outage child among them), `environment` / `stop` to end the run, or `busy` / `retry` to re-read —
+   the same tokens the merge event reads (`backlogrun-progress.md` → "Running a named epic's children").
+   Then go back to step 1 of the loop.
+
+Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why the poll routes through `run:merge`".
+
+## Conflicts are not predicted
+
+**The child merges `origin/main` into its lane before its gate now, so this path is the fallback rather
+than the first line.** Every `fullrun` runs `pnpm josh main:merge` ahead of the gate
+(`chain-rule.md` → "origin/main is merged in before the gate", the single source), so an overlap
+already on `main` is resolved before the gate reads the tree. What this section covers is an overlap
+that lands on `main` *after* it, which `followup` still reports as a conflict.
+
+**Nothing here forecasts which children will overlap.** The overlap surfaces where GitHub already
+reports it: a pull request that conflicts with its base comes back `mergeStateStatus: DIRTY`, which
+`git-pr-checks-eval.ts` reads as a **failure** rather than polling through it — so `pnpm josh followup`
+ends that child with a named conflict in about ten seconds.
+
+**That child does not stop: it resolves the conflict in its own lane.** It is **not** counted against
+the consecutive-failure guard either way.
+
+**The merge direction is `origin/main` into the lane's branch, never a rebase**, and no step below
+rewrites a pushed commit. Rationale: `docs/maintainers/backlogrun-recovery-rationale.md` → "Why a conflict
+is resolved in the lane rather than handed to a person".
+
+1. **Resolve in the lane.** `git fetch origin main`, merge `origin/main` into the lane's branch, resolve
+   in place. Do not close the lane, open another, or switch its branch.
+2. **Re-run the whole gate.** The tree changed, so the green recorded before the conflict is void:
+   `pnpm josh lint:related` and `pnpm josh test:related`, then `pnpm josh gate`.
+3. **Review the resolution, one round.** Brief it with `pnpm josh review:brief` and run `/code-review`
+   over the resolution diff, then require `pnpm josh review:attest --check` to answer `ok`. That round
+   is a different subject and does not spend one of the two the cap allows — `prompts/review.md` →
+   "Review round cap" carries the exception.
+4. **Conclude the merge and push it, with `pnpm josh git -y`** — the only sanctioned way; without it
+   nothing changes on `origin` and condition 3 parks the child for good. **Record the resolution on the
+   Issue in this same step** — a comment naming the conflicting paths — because condition 3 counts
+   resolutions off the Issue comments, not off memory.
+5. **Merge**, by re-running `pnpm josh followup` exactly as before.
+
+**The safeguard is the re-run verification, not who holds the pen** — a conflict the run can resolve is
+not routed to a person.
+
+**The run steps back under these four conditions, and under no others. The list is exhaustive and
+carries no judgement.**
+
+1. **The resolution requires deleting the other side's change.** That decides intended behavior, not
+   text. It goes to the user as a **specification** question — "behavior A or behavior B" — never as a
+   diff.
+2. **Both sides rewrote the same lines** — overlapping, not adjacent. Read off the structure of the
+   conflict hunks, so it needs no interpretation.
+3. **A second conflict on the same child.** One resolution per child; the count is read off the Issue
+   comments step 4 writes, so it survives an interrupt.
+4. **The re-run gate did not come back green, or the resolution review returned a High.** Not only a
+   High: a lint error, a failing test or a spell-check hit that merging a moved `main` introduced is
+   this condition too.
+
+Meeting any of the four, the child is parked — `needs-decision` plus a comment naming which of the four
+it was — and its lane is **kept**, because the pushed branch is the resume path
+(`backlogrun-lanes.md` → "What happens to a lane").
+
+**Leave the tree clean before parking: `git merge --abort` precedes a park under conditions 1, 2 or 4.**
+Conditions 1 and 2 are read mid-merge with conflict markers still in the tree, condition 4 after a merge
+that is resolved but not committed; condition 3 fires before any merge is started, so there is nothing
+to abort.