@joshuafolkken/kit 1.1094.0 → 1.1136.0

package/.claude/agents/investigator.md

@@ -0,0 +1,17 @@
+---
+name: investigator
+description: Read-only investigation unit for the pre-implementation reading — finds out how an Issue's subject currently works and returns the conclusion with its `file:line` citations, never the file text. Dispatch it when `pnpm josh investigation:guard` asks for a delegated unit, or when `pnpm josh delegate investigation` answers `delegate`.
+tools: Read, Grep, Glob, Bash
+effort: low
+---
+
+You are an investigation unit dispatched by a run that is about to implement an Issue. Your job is
+to find out **how the subject currently works**, not what to change.
+
+- Start from what the brief says the main line already concluded; do not re-read what it lists as read.
+- Search and read freely — this context is yours, and keeping it out of the main line is why you exist.
+- Never edit, stage or commit anything. A throwaway probe script may be written to the session
+  scratchpad, run, and deleted; return its output alone.
+- Return the conclusion plus the `file:line` citations that support each claim. Never paste file
+  text beyond a short quoted line — the main line opens the cited lines to verify you.
+- Report what the code does, never a root cause or a fix: deciding that stays in the main line.

package/.claude/settings.json

@@ -42,6 +42,7 @@
 	"env": {
 		"BASH_MAX_OUTPUT_LENGTH": "8000"
 	},
+	"enableArtifact": false,
 	"hooks": {
 		"SessionStart": [
 			{

package/.claude/skills/workflow-commands/SKILL.md

@@ -122,7 +122,7 @@ procedure.
 | Under `backlogrun`, a stop that would end a batch, or a named non-epic item | Park one child and continue; run a named non-epic item as a `fullrun` | `backlogrun-park.md` → "park and continue"; `backlogrun-child.md` → "When `#N` is not an epic" |
 | `backlogrun`'s authorization | The whole `auto-ok` opted-in pool as well as its named items; `pnpm josh backlog:next` offers them | `backlogrun.md` |
 | First call of any entry | `#N`: `pnpm josh run:entry <N> --to <command>` (claims the tree, except `kickoff`); `new` (not `kickoff`): `pnpm josh run:hold` | §2k; §2f → `working-tree-hold.md` |
-| Same turn as the hold (not a dispatched child, not `kickoff`) | `pnpm josh cost --cut`; `under` continues, `over` stops with a `confirmation` Telegram and the resume command, then `pnpm josh run:release` | `backlogrun-progress.md` → "The hand-off" (shared 135,000 threshold) |
+| Same turn as the hold (not a dispatched child, not `kickoff`) | `pnpm josh cost --cut`; `under` continues, `over` stops — `run:entry` notifies and runs `run:release` (by hand for `new`) | `backlogrun-progress.md` → "The hand-off" (shared 135,000 threshold) |
 | Before any work starts (every entry) | The split assessment; the default is not to split — separability **and** a scope clearly over one gate must hold together; a `fullrun` / `halfrun` that finds a split files the epic and **stops** | `split-assessment.md` → "The question" |
 | Another Issue here must land first | A prerequisite is a dependency, not a park (the third of four mid-run discoveries) | §2d → `prerequisite.md` |
 | Something worth filing, none of the three | File it without asking (Tier A, first-party) and carry on; a delegated child returns it to the parent instead | §2i → `observation-filing.md` |

package/.claude/skills/workflow-commands/background-commands.md

@@ -28,83 +28,39 @@ command finished.
 
 **Never hand-write a `while`/`until` … `sleep` loop over the output file.** The loop does not know
 when the command finished: a regex that never matches waits to the block limit, and one that matches
-a mid-run line exits too early — either way a full-context round trip is spent for nothing. Six lanes
-lost about 45 minutes, 13% of their wall clock, to exactly this (joshuafolkken/kit#2371), and in the
-worst case a lane grepped a merged PR's output file for 30 minutes after the merge had already
-landed. `pnpm josh rule:guard` refuses the poll loop and hands back this route, so the guarantee is a
-mechanism rather than prose to remember (`prompts/collaboration-workflow/rule-delivery.md`).
+a mid-run line exits too early. `pnpm josh rule:guard` refuses the poll loop and hands back this route
+(`prompts/collaboration-workflow/rule-delivery.md`). Rationale:
+`docs/maintainers/background-commands-rationale.md` → "Why a poll loop is refused".
 
 **To glance at interim output, `Read` the output file once** — the notification names its path — and
 never in a sleep loop. If what you are waiting on is CI, `pnpm josh followup` waits on it for you in
 the foreground; a bare `sleep` that arms a progress heartbeat is `run:progress --wait`'s job, refused
-in front of a hand-armed timer by `early-heartbeat` (joshuafolkken/kit#1570). This loop is the case
-that rule leaves alone by design, because a loop ends on a condition rather than a clock — and here
-the condition it ends on is the wrong one.
-
-## Decision record
-
-This document is read at its point of use, not at the entry: it binds only after the first edit —
-at the gate, the push, the CI wait and `pnpm josh followup` — so it is fetched in full, in the turn
-that reaches the first backgroundable command (`pnpm josh gate`), by the run that has to obey it
-(`SKILL.md` → §1, "Five documents are read at the point of use"). `SKILL.md` → §2h is the resident
-pointer to it, and carries the one thing it does not: the same rule at a batch's scale.
-
-**A run's idle time collects in its tail, and the two ways it collects there are one mistake**
-(joshuafolkken/kit#1510). `fullrun #1501` ran 45m03s on about 17 minutes of work. Of the 25 minutes
-nothing was running, **6m28s** was a `pnpm josh git -y` issued in the **foreground** with a
-900-second tool timeout — above the harness's own 600-second cap, so the harness detached it at the
-cap and nothing read the output file for six and a half minutes afterwards — and **6m06s** was bare
-CI: the push landed, the turn ended, and the merge started only once the person asked whether it was
-merging. Both halves handed the deciding of *when to look back* to something that was never going to
-decide it.
-
-**Issue it in the background, and never give a foreground call a timeout above the harness cap.**
-The cap decides how long a foreground call waits, not the number passed to it, so a number above the
-cap chooses the detached path without choosing the completion notification that should come with it.
-A call issued detached from the start re-invokes the run when it exits — which is what makes the
-completion *delivered* rather than something to remember to poll for.
-
-The measured outliers were a 6m28s foreground `git -y`, 6m06s of unattended CI and a 19m26s push
-transport fault. The operational section above maps those waits to background gate/push and a
-foreground `followup`; `followup.md` remains its command procedure.
-
-**A tail does follow the merge, and it is not small** (joshuafolkken/kit#1462). This section first
-gave a different reason for that last bullet — that the merge ends the run, leaving no tail to
-overlap — and the measurement says otherwise. The run-timing report charges to **`post-run`** exactly what runs
-after the last `followup` span ends: **3.0 min, 5.9% of a 50.5-minute run**, in the lane child
-`--issue 1599` (PR #1602); **2 min 31 s, 14% of 20m15s**, in the plain `fullrun #1597` (PR #1603);
-**3.1 min** hand-measured in run #1441's delegated child, which is where this Issue started. **What
-was wrong is the premise, not the conclusion** — `followup` stays foreground, and what changes is
-*where the tail's work is done*.
-
-**So the tail is emptied before `followup` is issued, rather than worked through after it returns.**
+in front of a hand-armed timer by `early-heartbeat`.
+
+## The tail and what overlaps each wait
+
+**Never give a foreground call a timeout above the harness cap** — the cap decides how long a
+foreground call waits, so a larger number detaches the call without the completion notification.
+Rationale: `docs/maintainers/background-commands-rationale.md` → "Why the tail collects idle time".
+
+**The tail is emptied before `followup` is issued, rather than worked through after it returns.**
 One question decides each step, and it is asked of the step rather than judged: **does it read the
 merge result?**
 
 - **It does — the step stays after `followup`.** `pnpm josh ms`, `pnpm josh issue:state <N>`,
   `pnpm josh epic:next`, `pnpm josh backlog:next --exclude <N>`, and `pnpm josh lane:close` /
-  `pnpm josh lane:list`. Each is a verifier or is keyed to a merge that has to have happened, and
-  bringing one forward would have it read a state nobody has reached yet. **De-duplicating a step is
-  not removing it**: the parent reads the child's state from GitHub *because* a summary is not a
-  verifier ("Each child runs in a delegated unit"), so none of these may be dropped or answered from
-  memory.
+  `pnpm josh lane:list`. **De-duplicating a step is not removing it**: none of these may be dropped or
+  answered from memory.
 - **It does not — the step is composed in the turn that issues `followup`.** The epic progress
-  comment's counter *values* (children run, Issues filed, consecutive failures, the run's start time)
-  are all counted inside the run, and the completion report body is already
-  placed beside `pnpm josh git -y` in the table below. **Only the write follows the merge.** The
-  comment exists because a compaction takes the counters at a moment nobody chooses (`backlogrun-progress.md` →
-  "The counters live in the record"), so composing the values earlier moves no write and loses
-  no counter.
-- **`pnpm josh cost --cut` stays after the merge, and reads nothing from it.** It measures
-  this session's own transcript, so the question above would bring it forward — but its answer grows
-  with the session, and asking it a call early under-reads the very number the hand-off is decided
-  on. It is seconds of tail against a guard on session size, so it keeps its documented seam
-  (`backlogrun-progress.md` → "The check is asked at every merge").
-
-**What runs beside a backgrounded command is the work that writes nothing to the working tree.** That
-is the whole test, and it is the same one that lets the gate and the review overlap (`SKILL.md` →
-§2): a step that edits makes the background command's result stale, so it is not something to overlap
-with. Applied to the three waits a run actually has:
+  comment's counter *values* and the completion report body (placed beside `pnpm josh git -y` in the
+  table below). **Only the write follows the merge.**
+- **`pnpm josh cost --cut` stays after the merge, and reads nothing from it** — its answer grows with
+  the session, so it keeps its documented seam (`backlogrun-progress.md` → "The check is asked at
+  every merge").
+
+**What runs beside a backgrounded command is the work that writes nothing to the working tree** — a
+step that edits makes the background command's result stale. Applied to the three waits a run
+actually has:
 
 | While this runs | Do this beside it |
 | --------------- | ----------------- |
@@ -115,26 +71,21 @@ with. Applied to the three waits a run actually has:
 
 **The turn never ends at the push.** The completion notification for `pnpm josh git -y` is what
 resumes the run, and the turn that reads it goes straight through any branch-2 filing and
-`pnpm josh epic:bundle` to `pnpm josh followup`. joshuafolkken/kit#1333 had already settled that end
-state for a clean second round, and symptom 2 above is its regression — **so the guarantee is a
-mechanism and not only the procedure**: `pnpm josh rule:guard` refuses the foreground push step and
-states both halves at that call (`prompts/collaboration-workflow/rule-delivery.md`). A turn *ending*
-is the absence of a call and no `PreToolUse` hook can see one, so the last call before the seam is
-where the rule can be put; the push reissued detached is not refused again, so a run that obeys pays
-nothing.
-
-**One turn does end before the push, and only one: a dispatched lane child's pre-gate cut**
-(joshuafolkken/kit#1839). It ends the turn before the gate and relaunches a fresh process in the same
-act, so the run continues rather than stalling — the sanctioned boundary distinct from the push
-turn-end this section forbids. The boundary, its two commands and the resume verification are the
-`pre-gate-cut.md` skill document, its single source.
+`pnpm josh epic:bundle` to `pnpm josh followup`. `pnpm josh rule:guard` refuses the foreground push
+step and states both halves at that call (`prompts/collaboration-workflow/rule-delivery.md`); the push
+reissued detached is not refused again. Rationale: `docs/maintainers/background-commands-rationale.md`
+→ "Why the push is guarded".
+
+**One turn does end before the push, and only one: a dispatched lane child's pre-gate cut.** It ends
+the turn before the gate and relaunches a fresh process in the same act — `pre-gate-cut.md` → "Taking
+the cut" is its single source.
 
 **A headless lane child (`claude -p`) is where "a background command re-invokes the run" does not
-hold: its background Bash tasks are killed when its turn ends** (joshuafolkken/kit#2704). It hands the
-gate-to-merge region to a foreground `pnpm josh ship --detach` instead (`chain-rule.md` step 0) —
-its preflight runs before the supervisor exists, so a backgrounded `ship` dies with the turn
-(joshuafolkken/kit#3027); `pnpm josh rule:guard` refuses a backgrounded `josh gate` / `git` /
-`followup` / `ship` there, and the `Stop` hook sends a child with a task still running back to wait.
+hold: its background Bash tasks are killed when its turn ends.** It hands the gate-to-merge region to
+a foreground `pnpm josh ship --detach` instead (`chain-rule.md` step 0) — its preflight runs before the
+supervisor exists, so a backgrounded `ship` dies with the turn; `pnpm josh rule:guard` refuses a
+backgrounded `josh gate` / `git` / `followup` / `ship` there, and the `Stop` hook sends a child with a
+task still running back to wait.
 
 The operational section above is the single source of the rule. `followup.md`, `chain-rule.md` and
 `backlogrun-progress.md` → "Progress while the run is quiet" route here for it rather than restating it.

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

@@ -18,14 +18,16 @@ by that supervisor; an AI parent is started only for a driver branch that requir
 pnpm josh run:progress --wait --output <the transcript path of each delegated unit>   # in the background
 ```
 
-**`--wait` waits one silence interval out, prints one line and exits** — the long-running form (no
-`--wait`) is right only where output is streamed. The parent changes no value on the line. **Every
-interval is three moves and no fourth:**
+**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:**
 
-1. Start `pnpm josh run:progress --wait --output <transcript paths>` **in the background**.
-2. When it exits, **present what it printed as-is** — the command prints the five labelled lines and the
-   next report time itself.
-3. **In that same turn, start the next one.** The interval is measured from the last report.
+| 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
@@ -33,18 +35,18 @@ lane children are in-flight but the watcher's life record has gone stale. **It i
 until the watcher is restarted — once per run, so the `pnpm josh run:progress --wait` that fixes it is
 not blocked.
 
-**`run:progress` prints the five labelled lines itself (joshuafolkken/kit#2026); present them as-is.** It emits the observation instant (`at`, local first and UTC beside it), the elapsed figures
+**`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 relay the output verbatim and
-round, rephrase or re-label nothing. How each field reads when it has nothing to report (`record
+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`.
 
-**It exits only when it has a line to hand over**, or when `--hours` runs out having never gone quiet
-for a whole interval (that exit says so on standard error). **Nothing in flight keeps it waiting.**
+**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
@@ -130,21 +132,13 @@ in the same turn as each: **the Step 0 work summary, the pull request opening, e
 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.
 
-**On a quiet tick the turn is the relayed line plus at most two lines of the run's own prose**, saying
-only what changed stage and what is being waited on. **A tick is quiet when none of the real reports
-happened since the last one**; a gate that went green, a review round, a file edited, a poll answering
-`wait` are the run working, not a report. **No table, no re-listing of children, no restating of the
-plan** — `epic:next`, the epic body and the progress comment hold all three. **A real report is not
-bounded by that**: `--mark` restarts the clock, so a merge, a park or a stop is where the run may be
-long.
-
 **`--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 any long-running watcher still in the background is stopped in the same turn. That
+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.
 
@@ -183,10 +177,10 @@ run in lanes".
    that lane's `lane:open`.
 
    **Start the unit without blocking on it — `pnpm josh lane:dispatch <N>` when the child runs in a
-   lane — and in the same turn start `pnpm josh lane:await <N...>` in the background** (joshuafolkken/kit#2113).
+   lane — and in the same turn start `pnpm josh lane:await <N...> --owner "$PPID"` in the background** (joshuafolkken/kit#2113).
    `lane:await` watches local process presence and exits when any named child confirms-complete. **The
    re-confirm delay and poll interval are the command's, not the agent's** — pass only the issue
-   numbers. Without that wake (Codex), hand off instead — "A parent without a completion callback".
+   numbers and `--owner` (why: `docs/josh-commands-automation.md` → `josh lane:await`). Without that wake (Codex), hand off instead — "A parent without a completion callback".
 
    **A `lane:await` wake is a confirmed-gone process, so classify the ending at once — do not wait out
    the silent-unit window** (joshuafolkken/kit#2277). On a `lane:await` wake go straight to `pnpm josh run:merge <N> --output <path>` — the composite reads the child's **exit
@@ -275,11 +269,12 @@ run in lanes".
    a session that cannot measure is read as `over`. **Never read the condition off `pnpm josh delegate
    epic-child`** ("The check is asked at every merge" below).
 3. **`wait`** — go back to step 1. **With something of this run's own in flight, that happens on the
-   wake the progress watcher's exit delivers** and the parent starts no sleep of its own; the 60 s
-   figure bounds how soon the ask may be repeated. **With nothing in flight the watcher declines and
-   never exits, so the parent keeps the interval** — the case for "another repository has work but this
-   one does not", and for a cross-repository publish wait. The table in "The wake exists only while
-   something is in flight" below decides which.
+   wake `lane:await` or the progress watcher's arrival exit delivers** and the parent starts no sleep
+   of its own; the 60 s figure bounds how soon the ask may be repeated. **A scheduled report is not one
+   of those wakes** (joshuafolkken/kit#3102). **With nothing in flight neither wake comes, so the parent
+   keeps the interval** — the case for "another repository has work but this one does not", and for a
+   cross-repository publish wait. "The wake exists only while something is in flight" below decides
+   which.
 4. **`stop`** — report the parked children and finish.
 5. **`complete`** — post the epic summary and finish.
 6. **Exit code 1** — `epic:next` refused a cyclic or contradictory graph, or could not read a child.
@@ -421,8 +416,8 @@ in the background, in the same turn as that first `lane:list`. The wired `run:wa
 
 **A carried-over child finishes in its own detached unit, and the resumed parent does not stand in front
 of its merge.** A lane handed over at the cut is still running its own `fullrun` — the foreground
-`pnpm josh followup` and the CI wait included — in a process of its own (background-commands.md →
-"`pnpm josh followup` — foreground": foreground is *within the unit*, the background from the parent).
+`pnpm josh followup` and the CI wait included — in a process of its own (`background-commands.md` →
+"Background the gate and push": foreground is *within the unit*, the background from the parent).
 **So the parent never runs a carried-over child's `followup` itself**: it polls the handed-over lane and
 opens new work beside it. **The reads and the dispatches go out together, in one turn** — `pnpm josh lane:list`,
 `pnpm josh run:liveness`, `epic:next --lanes`, and opening a lane for a child it offers take none of each
@@ -472,7 +467,7 @@ clock". A stale child's label is
 removed first, so the next poll can offer it. **A graph that has deadlocked on a cycle is not this loop's
 to untangle**: `epic:next` detects it and exits with an error.
 
-### The parent keeps no clock of its own — the watcher's exit is the wake
+### The parent keeps no clock of its own — a child's completion or an arrival is the wake
 
 **After hand-off, the supervisor's driver owns the mechanical clock.** `backlog:drive` polls lane
 completion and the backlog inside the detached process, without waking an AI parent; the parent-turn
@@ -483,12 +478,14 @@ source and `run:report` the final report.
 `docs/maintainers/backlogrun-progress-rationale.md` → "Why the parent waits on classification, not a
 clock".
 
-The watcher reports on its own interval, and a judgment session may take its exit as a prompt to act.
+The watcher reports on its own interval to the event stream and exits only on an arrival, so a judgment
+session takes that exit — or a `lane:await` completion — as its prompt to act, never a report.
 
 #### The wake exists only while something is in flight
 
-`run:progress --wait` prints only when it has a human-facing line. With no child in flight it may
-decline; the driver still polls for new work and enforces the idle and whole-run bounds. A GitHub
+`lane:await` wakes on a child's completion and `run:progress --wait` on an arrival; its reports wake
+nobody. With no child in flight it may decline; the driver still polls for new work and enforces the
+idle and whole-run bounds. A GitHub
 listing failure stays a retry or unreadable answer from the offer command, never an empty backlog.
 
 `epic:next` does not report when a label was applied, so read that from the issue's timeline:

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

@@ -365,7 +365,7 @@ subsection.
 | Answer | What to do | Budget answer |
 | --- | --- | --- |
 | One or more issue numbers | Start each one as a child, up to the free lanes — `backlogrun-lanes.md` → "Lanes" and "Each child runs in a delegated unit", unchanged. Then **ask the command again**, with the merged numbers added to `--exclude` | `candidates` |
-| `wait`, with something of this run's own still in flight | Everything opted in is blocked or already running, so waiting can still change the answer. **Ask the command again on the wake the progress watcher's exit delivers** — the parent starts no sleep of its own, and the interval is a floor on the re-ask rather than a clock (`backlogrun-progress.md` → "Waiting, and never waiting forever" and "The parent keeps no clock of its own") | `blocked` |
+| `wait`, with something of this run's own still in flight | Everything opted in is blocked or already running, so waiting can still change the answer. **Ask the command again on the in-flight wake — `pnpm josh lane:await` or the progress watcher's arrival exit, never a report** — the parent starts no sleep of its own, and the interval is a floor on the re-ask rather than a clock (`backlogrun-progress.md` → "Waiting, and never waiting forever" and "The parent keeps no clock of its own") | `blocked` |
 | `wait` this checkout can never resolve — the only candidates the command reported on standard error are in other repositories, and this run has nothing of its own in flight | Report those candidates with their checkouts. **Waiting cannot resolve them, but a person opting a new issue in here still can**, so the ending is the idle watch's rather than this row's | `exhausted` |
 | `stop` | Nothing can proceed without a person. Report the parked issues and finish | `parked` |
 | `triage` | A candidate lacks `run:solo` / `run:lane` (joshuafolkken/kit#2779). Judge each one stderr names as the pre-start pass does, then **ask again**; running children continue | `untriaged` |
@@ -451,7 +451,7 @@ tracks.
 | Verdict | What the loop does |
 | --- | --- |
 | `run` | Start what `backlog:next` offered, up to the free lanes. The reason names how many more the maximum still allows; start no more than that |
-| `watch` | Ask both commands again — at the 5-minute idle poll while the backlog is empty **and** nothing of this run's is in flight, and at the 60-second polling interval in every other case (a blocked backlog, a drain, or a watch that opened while children were still merging). *Whether the parent keeps that interval as a clock of its own* is the in-flight test: with nothing in flight the watcher declines for the whole watch and never exits, so the parent sleeps the interval itself; with something in flight the wake is the watcher's exit and the interval is only a floor on the re-ask (`backlogrun-progress.md` → "The wake exists only while something is in flight"). **Nothing is held while watching** — the working tree's hold and each drained lane were released at the last child's merge, so a watching run blocks no other run |
+| `watch` | Ask both commands again — at the 5-minute idle poll while the backlog is empty **and** nothing of this run's is in flight, and at the 60-second polling interval in every other case (a blocked backlog, a drain, or a watch that opened while children were still merging). *Whether the parent keeps that interval as a clock of its own* is the in-flight test: with nothing in flight the watcher declines for the whole watch and never exits, so the parent sleeps the interval itself; with something in flight the wake is `pnpm josh lane:await` or the watcher's arrival exit — never a report — and the interval is only a floor on the re-ask (`backlogrun-progress.md` → "The wake exists only while something is in flight"). **Nothing is held while watching** — the working tree's hold and each drained lane were released at the last child's merge, so a watching run blocks no other run |
 | `stop` | Report and finish. The reason it printed **is** the termination reason the completion report carries |
 
 **At the drain the retrospective fires before this watch, not after it** (joshuafolkken/kit#2335):

package/.claude/skills/workflow-commands/delegation.md

@@ -40,7 +40,11 @@ a temporary probe script and return its output.
 **The threshold is 3 files, and it is a count, not a forecast.** When the next read reaches it,
 delegate the unread investigation. Brief the unit on what was already read; do not re-read it there.
 **A delegation resets the counter rather than spending it**; `pnpm josh investigation:guard` counts
-unedited files and refuses the threshold read. `pnpm josh delegate --list` prints the threshold.
+unedited files and search turns and refuses the threshold call. `pnpm josh delegate --list` prints
+the threshold.
+
+**Dispatch the unit as the `investigator` agent** (`kit:investigator` in a consumer) — the parent's
+model at a lowered effort, read-only.
 `docs/josh-commands-automation.md` → "`josh investigation:guard`" carries the command's counting details.
 
 **The main line does not idle while the unit reads:** read files this run will edit, then verify the

package/.claude/skills/workflow-commands/fullrun.md

@@ -32,8 +32,8 @@ call reports `hold`.
    `pnpm josh run:release`: `gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress
    2>/dev/null || true`. A `needs-human-review` stop keeps both hold and label.
 3. **Ask the session boundary in the same turn as the hold** — `pnpm josh cost --cut`. `under`
-   continues; `over` (or unanswerable) stops before the title with a `confirmation` Telegram carrying
-   the figure and the resume command (`fullrun #<N>` / `fullrun new`), then `pnpm josh run:release`.
+   continues; `over` (or unanswerable) stops before the title — `run:entry` sends this and step 1's
+   `confirmation` Telegram and runs `run:release` (`stop notified: …`); by hand only for `new`.
    **Skip it when dispatched by `backlogrun`** (that batch owns the question). `backlogrun-progress.md`
    → "The hand-off" is the single source of the check and the shared 135,000 threshold.
 4. **Gather the mechanical reads — `pnpm josh run:prep <N>`**: `issue:read`'s body/comments
@@ -51,7 +51,7 @@ call reports `hold`.
 ## The progress step and the lane-child seam
 
 - **Start the progress watcher once the hold is claimed** — `pnpm josh run:progress --wait` in the
-  background, presented as-is when it exits, and `pnpm josh run:progress --mark` in the same turn as
+  background, started once and relayed never, and `pnpm josh run:progress --mark` in the same turn as
   every real report (`backlogrun-progress.md` → "Progress while the run is quiet"). A `fullrun`
   dispatched as a lane child starts none and never reads that document (`pnpm josh read:set
   lane-child`). **The watcher is a per-session heartbeat; the run's report surface is not it** — the
@@ -62,7 +62,8 @@ call reports `hold`.
   before the hold, joshuafolkken/kit#2760); on `resume` it skips the title, plan, hold and implementation and goes to the gate. At the pre-gate
   boundary — immediately after `pnpm josh main:merge`, before the gate — it takes the cut with
   `pnpm josh run:cut <N>` (the ordered step in `chain-rule.md`), and it records any park on the Issue before the stop notify.
-  `pre-gate-cut.md` is the single source of both.
+  `pre-gate-cut.md` → "Resuming — the fresh process's entry check" and `pre-gate-cut.md` → "Taking
+  the cut" are the single sources of the two.
 - **`resume: halfrun`** adopted a stopped `halfrun` (#2796): gate in full; `resume: prrun-*` a stopped
   `prrun` (#3023); `working-tree-hold.md`.
 

package/.claude/skills/workflow-commands/halfrun.md

@@ -13,18 +13,19 @@ that holds its detail.
 
 1. **Claim the working tree first** — `pnpm josh run:entry <N> --to halfrun` (bare `pnpm josh
    run:hold` for `new`), ahead of the title and a `new` filing; it folds steps 3 and 5 and starts
-   at its stage line's `start:` (`SKILL.md` → §2k). `busy` / `unknown` stop with a `confirmation` Telegram. **The stop
+   at its stage line's `start:` (`SKILL.md` → §2k). `busy` / `unknown` stop with a `confirmation` Telegram (`run:entry` sends it). **The stop
    before commit keeps the hold** (a second run would trample the uncommitted work); a stop on a
    split, prerequisite or third-party target releases it. `working-tree-hold.md` is the single source; a
    cross-repository target resolves its checkout from `pnpm josh doctor` first (`target-repository.md`).
 2. **Apply `in-progress` the moment `run:hold` answered `hold`** — the stop before commit keeps it on;
    a stop that leaves the tree clean removes it in the same turn as `pnpm josh run:release` (`gh api -X
    DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress 2>/dev/null || true`).
-3. **Ask the session boundary** — `pnpm josh cost --cut` (folded into `run:entry`); `over` stops with a `confirmation` Telegram and the resume command (`halfrun #<N>` /
-   `halfrun new`). **Skip it when dispatched by a batch.** `backlogrun-progress.md` → "The hand-off" is
+3. **Ask the session boundary** — `pnpm josh cost --cut` (folded into `run:entry`); `over` stops — `run:entry` notifies and releases
+   (`halfrun new`: by hand). **Skip it when dispatched by a batch.** `backlogrun-progress.md` → "The hand-off" is
    the single source of the check and the shared 135,000 threshold.
 4. **Start the progress watcher once the hold is claimed** — `pnpm josh run:progress --wait` in the
-   background, `--mark` in the same turn as every real report; the stop before commit ends the watcher
+   background, started once — it reports to the event stream itself and nothing is relayed — and
+   `--mark` in the same turn as every real report; the stop before commit ends the watcher
    itself (`backlogrun-progress.md` → "Progress while the run is quiet").
 5. **The mechanical reads** — `run:entry` folds `run:prep` (body/comments — `SKILL.md` → §2g;
    `human_review`; `latest:scope`); a `new` entry runs `pnpm josh run:prep <N>` once filed.

package/.claude/skills/workflow-commands/latest-gate.md

@@ -64,21 +64,13 @@ merge is CI**: the `Security Audit` job runs on every pull request and is one of
 whatever this gate answered locally. The local reading is a head start on a failure CI would catch
 anyway; it was never the only net.
 
-## Why an elapsed-time window rather than "once per batch"
-
-The batch entry points had already hoisted the update to the head of a batch, and that hoist is
-correct — but it says nothing about a standalone `fullrun`, which **is** the head of its own
-one-issue batch and therefore updated on every invocation. A session that runs six issues one at a
-time paid the full cost six times while a batch of the same six paid it once, for no difference
-anybody chose. An elapsed-time window is the one condition that reads the same at every entry point,
-so no entry needs a rule of its own — and the batch hoists survive it unchanged, because a batch's
-second child asks the same command and is told `skip`.
-
-**The lock file the update rewrites still lands with whichever issue ran it.** `josh latest` leaves
-`pnpm-lock.yaml` modified and that issue's `pnpm josh git -y` commits it, exactly as before. What the
-window removes is the other runs carrying the same bumps; it does not make that one diff clean.
-Should the issue then fail CI on a bump rather than on its own change, that is a dependency problem
-found once — fix it forward before parking the issue for it.
+## The lock file lands with the issue that ran the update
+
+**The lock file the update rewrites lands with whichever issue ran it.** `josh latest` leaves
+`pnpm-lock.yaml` modified and that issue's `pnpm josh git -y` commits it. Should the issue then fail
+CI on a bump rather than on its own change, fix it forward before parking the issue for it. Rationale
+for the elapsed-time window: `docs/maintainers/latest-gate-rationale.md` → "Why an elapsed-time
+window rather than once per batch".
 
 This file is the single source of the rule. `fullrun.md`, `halfrun.md`, `backlogrun.md` and `backlogrun.md`
 each name `pnpm josh latest:scope` at the point their procedure reaches it and route here for

package/.claude/skills/workflow-commands/pre-gate-cut.md

@@ -69,9 +69,8 @@ pnpm josh run:cut <N>
 **`cut` is the only verdict that ends the turn.** Every other one — `under-threshold` included — leaves
 the current process to carry the run on itself.
 
-### The gate refuses until the cut has been taken (joshuafolkken/kit#1864)
+### The gate refuses until the cut has been taken
 
-**This step was carried as prose and fired exactly never.** In measured lane children the cut was taken **0 times**, so
 `pnpm josh rule:guard` **refuses `pnpm josh gate`** while this checkout is a lane and no cut record is
 carried, handing back the command above. Rationale:
 `docs/maintainers/pre-gate-cut-rationale.md` → "Why the rules are guards, not prose".
@@ -165,13 +164,10 @@ hand-off". The parent's seam and the child's `run_cut.IMPLEMENTATION_CONTEXT_THR
 **135_000** `CONTEXT_CUT_THRESHOLD` (aliased so the tests cannot drift). No separate measurement is
 built for the lane child.
 
-### It is a guard, fired at the edit that crosses the threshold (joshuafolkken/kit#2310)
+### It is a guard, fired at the edit that crosses the threshold
 
-**This step was carried as prose and fired exactly never** — the cut fired **0 times** while 33.9% of
-lane requests ran past 200,000 tokens. Rationale:
-`docs/maintainers/pre-gate-cut-rationale.md` → "Why the rules are guards, not prose".
-
-So `pnpm josh rule:guard` **refuses an `Edit` / `Write`** while this checkout is a dispatched lane child
+Rationale: `docs/maintainers/pre-gate-cut-rationale.md` → "Why the rules are guards, not prose".
+`pnpm josh rule:guard` **refuses an `Edit` / `Write`** while this checkout is a dispatched lane child
 whose recent-context cost is over threshold, handing back `pnpm josh run:cut --impl <N> --handoff <path>` — the
 refusal lands _before_ the edit. `cut` ends the turn, the rest leave this process implementing; a fresh
 process's `pnpm josh run:cut --resume <N>` then answers **`resume-impl`**, so it **skips the title, plan,

package/.claude/skills/workflow-commands/split-assessment.md

@@ -33,27 +33,13 @@ does. **There is no second criterion.** §2i's observation, the review round cap
 prerequisite each route a second filing through it, delivered by `pnpm josh rule:guard` at the run's
 second `pnpm josh issue:file` call, never the first.
 
-## Why the default is not to split
-
-**The rules were manufacturing Issues faster than runs could close them.** Execution was never the
-bottleneck; arrival was, and this assessment was one of the routes producing it: `route:split`
-accounted for **28 of the 119 open Issues (24%)**.
-
-**Separability is not scarce, which is why a test made only of it splits nearly everything.** Almost
-any request can be described as several deliverables that could each ship alone, so the old test bit on
-requests worth a handful of lines. The second question is what makes the test bite only where one Issue
-would genuinely be unverifiable in one pass. The review round cap's default and the WIP cap changed
-alongside it, in one commit.
-
 ## Diff size is not a reason to split, and that is measured
 
 **Size is a bar a split has to clear; it is never a reason to split.** Question 2 is a *minimum* — below
-it the work stays whole — and nothing makes a large diff a reason to divide one. Splitting an Issue in
-two to shorten review round 1 lengthens it, because each Issue pays round 1's fixed cost again while
-the size-dependent part is merely divided between the halves (measured in joshuafolkken/kit#1436:
-round 1's cost is dominated by a fixed part that two Issues pay twice, so there is no diff size at
-which splitting to cut it pays). **A proposal to add a size threshold that splits more is required to
-say why that data does not reach it.**
+it the work stays whole — and nothing makes a large diff a reason to divide one. **A proposal to add a
+size threshold that splits more is required to say why the round-1 measurement does not reach it.**
+Rationale: `docs/maintainers/split-assessment-rationale.md` → "Why the default is not to split" and
+`docs/maintainers/split-assessment-rationale.md` → "Why diff size is not a reason to split".
 
 **The size half is measured, not eyeballed — `pnpm josh split:assess`.** It counts the branch's
 changed files and changed lines with test files excluded and answers `split` / `single` on size

package/.github/actions/setup-node/action.yml

@@ -0,0 +1,33 @@
+name: Setup Node.js
+description: >
+  Set Node.js up at the version every kit workflow runs on, optionally pointed at a package
+  registry.
+
+# The one place the Node.js version of kit's workflows is written (joshuafolkken/kit#3084). Every
+# job used to call actions/setup-node with its own `node-version` literal, so a version move had to
+# find all of them. A job that needs a different runtime says so explicitly — `node-26-pnpm` in
+# `ci.yml` passes its own runtime to `.github/actions/setup-pnpm` instead of calling this.
+#
+# Distributed: `josh sync` writes this file into a consumer beside the workflows that call it, the
+# same way as `.github/actions/setup-pnpm`. `workflow_pin_logic` reads this file as a source of
+# canonical action pins.
+
+inputs:
+  registry-url:
+    description: Passed to actions/setup-node's `registry-url`; empty writes no `.npmrc`.
+    required: false
+    default: ''
+  scope:
+    description: Passed to actions/setup-node's `scope`, for a scoped registry.
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      with:
+        node-version: '24'
+        registry-url: ${{ inputs.registry-url }}
+        scope: ${{ inputs.scope }}

package/.github/actions/setup-pnpm/action.yml

@@ -10,10 +10,10 @@ description: >
 # job that calls this action cannot install without the scan.
 #
 # Distributed: `josh sync` writes this file into a consumer beside the workflows that call it
-# (`pr-classification.yml`), stamped as managed like they are (joshuafolkken/kit#3013).
-# `templates/workflows/ci.yml` still carries the same steps inline — it was written before this file
-# was distributed, and moving it onto the action is a change of its own. `workflow_pin_logic` reads
-# this file as a source of canonical action pins, so the template's refs still resolve from here.
+# (`ci.yml` and `pr-classification.yml`), stamped as managed like they are (joshuafolkken/kit#3013).
+# The distributed `ci.yml` calls it exactly as kit's own does, so a consumer's CI prepares pnpm on
+# the path kit's CI runs (joshuafolkken/kit#3095). `workflow_pin_logic` reads this file as a source
+# of canonical action pins.
 
 inputs:
   install:

package/.github/workflows/auto-tag.yml

@@ -8,6 +8,7 @@ jobs:
   create-tag:
     name: Create Git Tag if Version Changed
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       actions: write
       contents: write
@@ -19,9 +20,7 @@ jobs:
           fetch-depth: 2
 
       - name: Setup Node.js
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: '24'
+        uses: ./.github/actions/setup-node
 
       - name: Check if package.json changed
         id: pkg_changed