@joshuafolkken/kit 1.1178.0 → 1.1229.0

package/prompts/collaboration-workflow/turn-batching.md

@@ -36,7 +36,7 @@
 
 ## 実装中の独立編集に効く合成コマンド（joshuafolkken/kit#2202）
 
-レーン子ではガードが `off` なので、`Read` → `Edit` の交互の並びは誰にも止められない。**Step 0 が対象ファイルを列挙した時点で、`pnpm josh read:files <path> …` で読み取りを 1 回に畳み、続く別ファイルへの編集を 1 ターンに載せる**（`report-format.md` が導く）。書き込みは `pnpm josh edit:files` で畳む（joshuafolkken/kit#2366） — プランを 1 呼び出しで適用し、`old` が 1 箇所に一致しなければ拒否する。形式は `docs/josh-commands-automation.md` →「`josh read:files`」と「`josh edit:files`」、経緯は `docs/maintainers/turn-batching-rationale.md` → "The composite commands"。
+レーン子ではガードが `off` なので、`Read` → `Edit` の交互の並びは誰にも止められない。**Step 0 が対象ファイルを列挙した時点で、`pnpm josh read:files <path> …` で読み取りを 1 回に畳み、続く別ファイルへの編集を 1 ターンに載せる**（`report-format.md` が導く）。書き込みは `pnpm josh edit:files` で畳む（joshuafolkken/kit#2366） — プランを 1 呼び出しで適用し、`old` が 1 箇所に一致しなければ拒否する。形式は `docs/josh-commands-run.md` →「`josh read:files`」と「`josh edit:files`」、経緯は `docs/maintainers/turn-batching-rationale.md` → "The composite commands"。
 
 ## ガード発火時にも合成コマンドを手渡す（joshuafolkken/kit#2311）
 

package/prompts/collaboration-workflow/upstream-interrupt.md

@@ -9,13 +9,23 @@
 - **トリガーは「発見」であって「ブロックし始めたとき」ではない**
 - **起票は Tier A（確認なし）**。起票してよいか、どのリポジトリへ起票するか、いずれもユーザー確認を取らない。対象は first-party に限る（→「第三者リポジトリへの書き込みは Tier C（明示指示が必要）」）
 - **停止は無条件**。Issue が存在する状態にしてから停止する。上流の修正を待つか先送りするかは、Issue を目の前にしたユーザーが決める
-- **`backlogrun` の中では、停止の範囲がセッション全体ではなくその子 Issue に限定される**。起票と回避策の禁止は変わらない。該当の子に `needs-decision` を付けて park し、依存していない他の子へ進む（→ `.claude/skills/workflow-commands/backlogrun-park.md` → "park and continue"）
+- **`backlogrun` の中では、停止の範囲がセッション全体ではなくその子 Issue に限定される**。起票と回避策の禁止は変わらない。上流の修正を待つか先送りするかは人の判断なので、該当の子に `needs-decision` を付けて park し、依存していない他の子へ進む（→ `.claude/skills/workflow-commands/backlogrun-park.md` → "Only a person's judgement carries `needs-decision`"）
+
+### 実行中のリポジトリ自身のラン機構の不具合
+
+**この手順の対象は別パッケージであり、実行中のリポジトリ自身は含まない。** kit の中で kit のラン機構（`backlog:drive`、`run:wake`、`run:carry`、レーン、分類、カウンタ、ガードなど）の不具合を見つけた場合、それは上流の欠陥ではなく**このリポジトリの割り込み**である。上流 Issue を立てて停止する代わりに、次の手順を取る。この節がその単一ソースである。
+
+1. **起票する** — `pnpm josh issue:file "<title>" --body-file <path> --depth <n> --route interrupt --label priority:high`。上限は効かない（`wip-cap.md` →「割り込み起票 — 上限が効かない側」の条件 2）
+2. **止まらずに直す** — 壊れた機構を迂回しない（回避策の禁止と、検証ゲートを緩めない規則はここでも変わらない）。`backlogrun` の中では、その割り込みを次の子にし、修正が着地してから塞がれていた子へ戻る。プールから選ぶランでは `priority:high` が先頭に並べ、epic の下では `wip-cap.md` の手順 3 で挿入する。名前を指定したランのドライバーは指定された Issue しか出さないので、`pnpm josh lane:launch <N>` で自分で dispatch する。バッチの外では `wip-cap.md` の手順 4 が変わらず効く — 起票まで済ませ、打つべき `fullrun #<N>` を報告して止まる
+3. **再開できるなら自分で再開し、動くことを確かめる** — 修正のマージ後、再開の手段がある答えには人の打ち直しを求めない。手渡し済みの記録、所有者が死んだ記録、監督プロセスの停止（`warning` Telegram）には `pnpm josh run:wake --start`、`run:carry` の `standing` には `pnpm josh run:carry --resume "<invocation>" --owner "$PPID"` を自分で打つ。そのあと `pnpm josh run:wake --list` が監督プロセスを示し、そのログに次の子の dispatch が現れることを確かめて報告する
+4. **人に打ち直しを求めるのは再開の手段が無いときだけ** — `expired`（8 時間の上限を使い切った）、`mismatch`（別の起動の記録）、別の生きた所有者の `busy`。新しい承認を宣言するのは人だけ、という規則も変わらない
+5. **`needs-decision` を付けない** — ランが自分で直せる不具合は人の判断を要さない（`.claude/skills/workflow-commands/backlogrun-park.md` → "Only a person's judgement carries `needs-decision`"）
 
 手順:
 
 1. **現在の作業を退避する**: `git stash push -u -m "upstream-interrupt: paused #<N>"`（WIP コミットでも可）。退避したことを忘れないよう、この時点で stash を作る。メッセージ付きで積むのは、復元をメッセージで特定するため（下記ステップ 5）
 2. **進行中の Issue に状況を明記する**: `pnpm josh issue:comment <N> --body-file <path>` で、(a) 作業を stash したこと、(b) 中断理由（どの別パッケージの・どんな問題で中断したか）、(c) 対象パッケージに作成した新 Issue へのリンクを `## Upstream issues` 見出しの下に `owner/repo#N` 形式で、を記載する。これにより「なぜこの Issue が一時停止しているか」と「何を待っているのか」が後から監査できる（→「起票元へのバックリンク」）
-3. **対象パッケージのリポジトリに新しい Issue を作成する（確認なし）**: `pnpm josh issue:file "<root-cause title>" --body-file <body-file> --depth <n> --route tier-a --repo <owner>/<repo>`（`route:tier-a` は実装中の Tier A 起票を経路として集計するためのラベル — joshuafolkken/kit#1083）。本文の検査、本文が宣言する分類ラベルの付与、`## Origin` 節の確認、起票先での重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands-automation.md` → `josh issue:file`）。分類の単一ソースは `prompts/collaboration-workflow/issue-template.md`。根本原因・再現・期待結果を Step 1 のテンプレに沿って記載し、**本文に `## Origin` 節を置いて起票元 Issue を `owner/repo#N` 形式で書く**（→「起票元へのバックリンク」）。ここで「起票してよいか」を尋ねて停止してはならない
+3. **対象パッケージのリポジトリに新しい Issue を作成する（確認なし）**: `pnpm josh issue:file "<root-cause title>" --body-file <body-file> --depth <n> --route tier-a --repo <owner>/<repo>`（`route:tier-a` は実装中の Tier A 起票を経路として集計するためのラベル — joshuafolkken/kit#1083）。本文の検査、本文が宣言する分類ラベルの付与、`## Origin` 節の確認、起票先での重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands-backlog.md` → `josh issue:file`）。分類の単一ソースは `prompts/collaboration-workflow/issue-template.md`。根本原因・再現・期待結果を Step 1 のテンプレに沿って記載し、**本文に `## Origin` 節を置いて起票元 Issue を `owner/repo#N` 形式で書く**（→「起票元へのバックリンク」）。ここで「起票してよいか」を尋ねて停止してはならない
 4. **`confirmation` Telegram を送って停止する**: 上流 Issue の URL と、何が止まっているかを本文に書く（→ `CLAUDE.md` → "Mid-workflow stop notification (`confirmation`)"）。無人実行でも画面外でユーザーが気付ける。停止は Issue が既に存在する状態で行うので、ユーザーは「待つ / 先送りする」を Issue を見ながら 1 語で答えられる
 5. **元の作業を再開する**: 上流の修正がマージされた、または**ユーザーが先送りを明示判断した**後に `pnpm josh stash:pop "upstream-interrupt: paused #<N>"`（位置指定や引数なしの `git stash pop` は使わない — stash は全 work tree が共有する 1 本のスタックで、別のレーンの stash を取り込む恐れがある）して、退避していた元タスクを続行する。上流 Issue を割り込みで実装するかどうかもユーザーの判断（上流パッケージの実装・PR・マージはそれぞれのワークフロー規則に従う）
 

package/prompts/collaboration-workflow/wip-cap.md

@@ -2,7 +2,7 @@
 
 **単一ソースはこのファイルである。**
 
-**この規則は常駐していない — 引き金つき配送に移った**（joshuafolkken/kit#1524）。`pnpm josh rule:guard` が Issue を作成する `Bash` 呼び出し（`pnpm josh issue:file`。`gh issue create` や `…/issues` への `title` 付き POST による直接起票は `direct-filing` が毎回拒否する）を拒否し、そこで数え方・拒否・2 つの免除・免除を決める 3 条件を突きつける。起票が無いターンでは何も起きず、それは上限に触れる行為が無いということである。配送は**ラン 1 回につき 1 度**なので、数えたうえで同じ呼び出しをもう一度出せばよい。機構と列挙表は `rule-delivery.md`、配送文の実体は `scripts/rules/delivered-rules.ts` の `WIP_CAP_REASON` にある（固定するテストは `docs/maintainers/wip-cap-rationale.md` →「文言を固定しているテスト」）。
+**この規則は常駐していない — 引き金つき配送に移った**（joshuafolkken/kit#1524）。`pnpm josh rule:guard` が Issue を作成する `Bash` 呼び出し（`pnpm josh issue:file`。`gh issue create` や `…/issues` への `title` 付き POST による直接起票は `direct-filing` が毎回拒否する）を拒否し、そこで数え方・拒否・2 つの免除・免除を決める 3 条件を突きつける。起票が無いターンでは何も起きず、それは上限に触れる行為が無いということである。配送は**ラン 1 回につき 1 度**なので、数えたうえで同じ呼び出しをもう一度出せばよい。機構と列挙表は `rule-delivery.md`、配送文の実体は `scripts/rules/wip-cap.ts` の `WIP_CAP_REASON` にある（固定するテストは `docs/maintainers/wip-cap-rationale.md` → "Tests that pin the wording"）。
 
 背景・測定・経緯は保守者向けの `docs/maintainers/wip-cap-rationale.md` にあり、ラン中に読む必要はない。
 
@@ -10,15 +10,15 @@
 
 **オープン Issue が上限を超えている状態で新しく起票するときは、先に 1 件閉じる。**
 
-**件数は `pnpm josh issue:file` が起票の前に数える**（joshuafolkken/kit#3181）。手で数えることも、見積もりや記憶で済ませることもない。数え方・印字・保留の詳細は `docs/josh-commands-automation.md` → "`josh issue:file`" にある。
+**件数は `pnpm josh issue:file` が起票の前に数える**（joshuafolkken/kit#3181）。手で数えることも、見積もりや記憶で済ませることもない。数え方・印字・保留の詳細は `docs/josh-commands-backlog.md` → "`josh issue:file`" にある。
 
-- **上限は 30。** これを超える 1 件を作る前に 1 件閉じる。エージェントが読む文書（`CLAUDE.md`・`prompts/`・配布 skill）がこの数字を書くのはこの行だけで、一次情報は `scripts/rules/delivered-rules.ts` の `WIP_CAP` である（一致はテストが固定する）。
+- **上限は 30。** これを超える 1 件を作る前に 1 件閉じる。エージェントが読む文書（`CLAUDE.md`・`prompts/`・配布 skill）がこの数字を書くのはこの行だけで、一次情報は `scripts/rules/wip-cap.ts` の `WIP_CAP` である（一致はテストが固定する）。
 - コマンドは起票先（`--repo` を付ければそのリポジトリ）のオープン Issue を epic も含めて数え、`wip:` 行に件数・上限・判定を印字する。上限を超えて免除が宣言されていなければ**何も送らずに保留し、免除の問いを印字する**。
 - **免除を宣言するのはこのファイルの判断である** — `--route interrupt`（下の 3 条件）、`--route split` / `--route tier-a`（実行が詰まる起票）はルートそのものが宣言になる。ルートの無い実行が詰まる起票（利用者が `new` と打った入口など）は `--over-cap` を付けて出し直す。裁量起票（`--route review-cap` を含む）に `--over-cap` を付けてはならない。
 
 ## なぜ上限が要るのか
 
-測定は `docs/maintainers/wip-cap-rationale.md` →「なぜ上限が要るのか — 測定」。
+測定は `docs/maintainers/wip-cap-rationale.md` → "Why a cap is needed — the measurement"。
 
 **上限は、増加を見えるようにするための強制装置である。** 数を減らすこと自体が目的ではない。上限を超えた状態で起票しようとしたときに「本当にこれは 1 件増やす価値があるか」を必ず 1 回考えさせる、そこだけが役割である。
 
@@ -40,13 +40,13 @@
 
 前提 Issue（`prerequisite.md`）、別パッケージ起因の割り込み Issue、ユーザーが `new` と打った入口、`issue:scout` が重複無しと答えた新規作業、**そして分割判定が作る子 Issue と epic**。**これらは起票しないと実行が進まない。**
 
-- **上限を理由に止めない。** 理由は `docs/maintainers/wip-cap-rationale.md` →「実行が詰まる起票を止めない理由」。
+- **上限を理由に止めない。** 理由は `docs/maintainers/wip-cap-rationale.md` → "Why a filing a run is blocked by is not stopped"。
 - **分割の子がここに入る理由**: 分割を検出した `fullrun` / `halfrun` は「子と epic を起票して **STOP**」と定められている（`fullrun.md` / `halfrun.md`）。**分割するかどうかを決めるのは分割判定の側**で、既定はもう「分割しない」に上がっている — 上限が二重に効く必要はない。
 - **超過した事実は完了報告に 1 行書く**（例: 「オープン 34 件で起票した」）。上限は可視化のための装置なので、超えたことが見えていれば役割は果たしている。
 
 ### 割り込み起票 — 上限が効かない側（3 条件で機械的に決める）
 
-**重大な欠陥の発見は、それが現在のランを止めていなくても捨ててはならない。** 上限の目的は増加を見えるようにすることであって、**発見を捨てることではない**（上の「なぜ上限が要るのか」）。由来は `docs/maintainers/wip-cap-rationale.md` →「割り込み区分の由来 — joshuafolkken/kit#1517」。
+**重大な欠陥の発見は、それが現在のランを止めていなくても捨ててはならない。** 上限の目的は増加を見えるようにすることであって、**発見を捨てることではない**（上の「なぜ上限が要るのか」）。由来は `docs/maintainers/wip-cap-rationale.md` → "Where the interrupt category comes from"。
 
 **別パッケージ起因の割り込みとは別の区分である。** あちらは上流リポジトリへ起票して停止する手順（`upstream-interrupt.md`、`route:tier-a`）で、実行が詰まる側に属する。ここで言う割り込みは、**このリポジトリの欠陥で、発見したランをブロックしていないもの**を指す。
 
@@ -60,20 +60,20 @@
 
 **3 つのいずれにも当たらない発見は、従来どおり裁量側の出口を取る。** 改善案、設計上の好み、未検証の疑い、「あとで直したい」はここに入らない — レビュー指摘なら branch 3（PR 本文に 1 行残して落とす）であり、それは既定の出口であって上限に阻まれたときの代替ではない。
 
-**深刻さの自己申告は条件ではない。** 理由は `docs/maintainers/wip-cap-rationale.md` →「深刻さの自己申告を条件にしない理由」。
+**深刻さの自己申告は条件ではない。** 理由は `docs/maintainers/wip-cap-rationale.md` → "Why self-reported severity is not a condition"。
 
 #### 該当したときの手順
 
-1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。起票は `pnpm josh issue:file` で行う。本文の検査、本文が宣言する分類ラベルの付与、重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands-automation.md` → `josh issue:file`）。
+1. **上限に関係なく起票する。** 1 件閉じることを条件にしない。起票は `pnpm josh issue:file` で行う。本文の検査、本文が宣言する分類ラベルの付与、重複探し、`epic:bundle` はこのコマンドが実行する（`docs/josh-commands-backlog.md` → `josh issue:file`）。
 
    ```bash
    pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route interrupt
    ```
 
 2. **超過している事実と、当たった条件の番号を本文に 1 行書く**（例:「オープン 37 件で起票。3 条件のうち 2（文書化された手順が完了できない）に該当」）。**どちらか一方では足りない** — 件数だけでは判定が再現できず、条件だけでは上限の可視化が効かない。
-3. **次に実行されるものとして挿入する。** epic の下にあるなら `pnpm josh epic --add <E> <N>` で、**位置を指定せずに**追加する（`<E>` が epic、`<N>` が起票した割り込み）。**`--before` / `--after` を使ってはならない。** それらは `blocked-by` を書き込み、「発見したランをブロックしていない欠陥」という割り込みの定義と矛盾する**偽の依存関係**になる。**順序は実行側が持つ** — 先に提示させたいときは、行だけを動かす `--order-before <M>` を使う。仕組みと経緯は `docs/maintainers/wip-cap-rationale.md` →「位置を指定しない追加の経緯」。**epic の下に無いなら挿入先そのものが無い**ので、この手順は飛ばして 4 だけを行う。
+3. **次に実行されるものとして挿入する。** epic の下にあるなら `pnpm josh epic --add <E> <N>` で、**位置を指定せずに**追加する（`<E>` が epic、`<N>` が起票した割り込み）。**`--before` / `--after` を使ってはならない。** それらは `blocked-by` を書き込み、「発見したランをブロックしていない欠陥」という割り込みの定義と矛盾する**偽の依存関係**になる。**順序は実行側が持つ** — 先に提示させたいときは、行だけを動かす `--order-before <M>` を使う。仕組みと経緯は `docs/maintainers/wip-cap-rationale.md` → "Why an addition names no position"。**epic の下に無いなら挿入先そのものが無い**ので、この手順は飛ばして 4 だけを行う。
 4. **着手は、既にある承認の内側でのみ、指示を待たずに行う。** `backlogrun` の中なら、打たれたキーワードがバッチを承認しているので、割り込みは次の子として着手してよい。**バッチの外では `CLAUDE.md` →「Explicit invocation required」が変わらず効く** — 起票と挿入まで済ませたうえで、利用者に打つべきコマンド（`fullrun #<N>`）を報告して止まる。**割り込みは上限の例外であって、明示起動規則の例外ではない。**
 
 **起票と、実行されるようにするところまでが 1 つのまとまりである。** epic の下にある割り込みを起票だけして追加しなければ、`epic:next` はそれを候補にすら出さない — Issue は残るが実行されないという、コメントに埋もれるのと大差ない状態になる。**epic の外にある割り込みでは、まとまりの後半は 4 の報告そのもの**であり、打つべきコマンドを利用者に渡すまでが 1 回の行為である。上の「ひとまとまりで判定する」がここにも効く。
 
-**割り込みをバッチの中で単独で走らせるか、並列のレーンで走らせるか**は `.claude/skills/workflow-commands/backlogrun-lanes.md` → "Lanes — running more than one child at a time" が単一ソースである（理由は `docs/maintainers/wip-cap-rationale.md` →「単独実行の理由と由来」）。上限の数字の変え方は `docs/maintainers/wip-cap-rationale.md` →「上限そのものを変えるとき」、上限が分割判定・レビュー上限と一緒に動く理由は `docs/maintainers/wip-cap-rationale.md` →「3 つは一緒に動く」と `docs/maintainers/wip-cap-rationale.md` →「3 つを 1 コミットで着地させた経緯」にある。
+**割り込みをバッチの中で単独で走らせるか、並列のレーンで走らせるか**は `.claude/skills/workflow-commands/backlogrun-lanes.md` → "Lanes — running more than one child at a time" が単一ソースである（理由は `docs/maintainers/wip-cap-rationale.md` → "Why a solo run"）。上限の数字の変え方は `docs/maintainers/wip-cap-rationale.md` → "Changing the cap itself"、上限が分割判定・レビュー上限と一緒に動く理由は `docs/maintainers/wip-cap-rationale.md` → "The three move together"と `docs/maintainers/wip-cap-rationale.md` → "Why the three landed in one commit"にある。

package/prompts/review-rubric.md

@@ -212,8 +212,7 @@ allowed.
 
 ### 4. Project conventions (`CLAUDE.md`)
 
-**Do not re-check what lint enforces — the gate has already run; lint does not catch `function`
-syntax over an arrow const (outside named route handlers), the early-return one-liner, duplication
+**Do not re-check what lint enforces — the gate has already run; lint does not catch duplication
 that is not identical, a name whose shape passes but whose meaning misleads, grouping and file layout,
 Svelte semantics, or test placement beyond the `*.spec.*` / top-level `tests/` bans, so check those.**
 A lint gap the change opens — a disabled rule, an ignored path, an added `eslint-disable`, a block

package/prompts/review.md

@@ -167,7 +167,7 @@ Only branch 2 files an Issue. What follows applies to that branch.
   1. File the follow-up Issue referencing the current one, tagged `route:review-cap` — **before the current Issue closes.**
      `pnpm josh issue:file "<title>" --body-file <body-file> --depth <n> --route review-cap`.
      The command lints the body, applies the classification labels it declares, runs the duplicate scan
-     and then `epic:bundle` on the new Issue (`docs/josh-commands-automation.md` → `josh issue:file`). The
+     and then `epic:bundle` on the new Issue (`docs/josh-commands-backlog.md` → `josh issue:file`). The
      `epic:bundle` candidate search reads open issues only, so once the parent has closed it answers
      `none` permanently.
   2. Act on the `epic:bundle` answer it prints. **`epic:bundle` recommends and writes nothing**, so acting means running the

package/scripts/agent/agent-headless.ts

@@ -0,0 +1,29 @@
+// The mark every agent session kit launches itself carries — a lane child, a ship reviewer, a woken
+// `run:wake` session (joshuafolkken/kit#3245).
+//
+// **Those sessions run under `claude -p`, and nobody reads their replies.** Their output goes to a
+// stream-json log, and the only reader of the final text is the exit record's failure reason. So the
+// stop rules that correct how a reply is written — the issue citation, the session language — refused
+// replies no person would ever see, and each refusal cost a model turn: across one baseline run, 107
+// of them in children and wake sessions.
+//
+// **It is set at the one place agent sessions are launched, never read from the prompt.** Every launch
+// that passes an agent profile composes its environment in `agent_launch_environment.build`, so the
+// mark is exactly "kit started this agent". A person's own session is never spawned there, so it never
+// carries the mark; a process the headless session starts inherits it, and is headless too.
+const KEY = 'JOSH_AGENT_HEADLESS'
+const VALUE = '1'
+
+type EnvironmentSource = Readonly<Record<string, string | undefined>>
+
+function environment(): Record<string, string> {
+	return { [KEY]: VALUE }
+}
+
+function is_headless(source: EnvironmentSource = process.env): boolean {
+	return source[KEY] === VALUE
+}
+
+const agent_headless = { KEY, environment, is_headless }
+
+export { agent_headless }

package/scripts/agent/agent-launch-environment.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync
 import path from 'node:path'
 import { gh_cli_token } from '#scripts/gh/gh-cli-token'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+import { agent_headless } from './agent-headless'
 import { agent_role_profile, type AgentProfile } from './agent-role-profile'
 import { codex_home_source } from './codex-home-source'
 
@@ -57,9 +58,12 @@ function build(
 	profile: AgentProfile | undefined,
 	environment: LaunchEnvironment = {},
 ): LaunchEnvironment {
-	if (profile?.provider !== OPENAI_PROVIDER) return environment
+	if (profile === undefined) return environment
 
-	const base = { ...openai_environment(), ...environment }
+	const marked = { ...agent_headless.environment(), ...environment }
+	if (profile.provider !== OPENAI_PROVIDER) return marked
+
+	const base = { ...openai_environment(), ...marked }
 
 	return profile.role === agent_role_profile.REVIEWER
 		? { ...base, CODEX_HOME: reviewer_home(cwd, environment) }

package/scripts/agent/codex-agent-argv.ts

@@ -1,6 +1,7 @@
 import { lstatSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { git_common_directory } from '#scripts/git/git-common-directory'
+import { OBSERVATION_LEDGER_DIRECTORY } from '#scripts/observations/observation-ledger'
 import { agent_role_profile, type AgentProfile } from './agent-role-profile'
 
 const AGENT_COMMAND = 'codex'
@@ -13,7 +14,7 @@ const SQLITE_CACHE_PATH = ['node_modules', '.cache', 'josh', 'openai']
 const EPHEMERAL_FLAG = '--ephemeral'
 const ADD_DIRECTORY_FLAG = '--add-dir'
 const GIT_DIRECTORY = '.git'
-const LEDGER_DIRECTORY = 'docs'
+const LEDGER_DIRECTORY = path.dirname(OBSERVATION_LEDGER_DIRECTORY)
 
 interface CodexArgv {
 	command: string

package/scripts/auto-ok/auto-ok-cli.ts

@@ -5,9 +5,9 @@ import { epic_index, type FetchedEpics } from '#scripts/epic/epic-index'
 import { epic_issue } from '#scripts/epic/epic-issue'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { SUMMARY_FIELDS } from '#scripts/gh/git-gh-issue'
+import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { cutoff_cause, cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { read_json_listing } from '#scripts/git/parse-json-array'
-import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
 import { git_next_issues } from '#scripts/issue/git-next-issues'
 import { AUTO_OK_LABEL } from '#scripts/issue/issue-labels'
 

package/scripts/backlog/backlog-arrival.ts

@@ -1,5 +1,6 @@
 import { epic_triage } from '#scripts/epic/epic-triage'
 import type { JoshResult } from '#scripts/josh/josh-run'
+import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { run_headless } from '#scripts/run/run-headless'
 import { backlog_next } from './backlog-next'
 import { backlog_ready, type ReadyPorts, type ReadyReading } from './backlog-ready'
@@ -26,14 +27,13 @@ import { backlog_stalled } from './backlog-stalled'
 //
 // **Every read is bounded.** The probe is awaited inside the watcher's tick loop, so a `gh` call that
 // hangs would otherwise freeze the loop — its `--hours` bound, its liveness ping and the exit that is
-// the parent's wake. A read past `READ_TIMEOUT_MS` is killed and counts as a failed read.
+// the parent's wake. A read past `COMMAND_TIMEOUT_MS` is killed and counts as a failed read.
 //
 // **And strict.** `backlog:next` exits 0 on a `retry` (a transport failure) or an `error` verdict, which
 // the lenient pick-up read takes as an empty pool — here that empty baseline is the whole-pool wake the
 // paragraph above rules out, so either verdict, like a non-zero exit, is a read that did not answer.
 
 const PROBE_INTERVAL_MS = 60_000
-const READ_TIMEOUT_MS = 30_000
 const SUCCESS_EXIT_CODE = 0
 const NO_FREE = 0
 const NONE = 0
@@ -61,7 +61,7 @@ function answered_issues(result: JoshResult | undefined): ReadonlyArray<string>
 }
 
 async function bounded_ready_issues(): Promise<ReadonlyArray<string>> {
-	return answered_issues(await backlog_ready.read_backlog_next(READ_TIMEOUT_MS))
+	return answered_issues(await backlog_ready.read_backlog_next(COMMAND_TIMEOUT_MS))
 }
 
 const ARRIVAL_PORTS: ReadyPorts = {

package/scripts/backlog/backlog-budget.ts

@@ -59,7 +59,7 @@ type BudgetVerdict =
 	typeof RUN_VERDICT | typeof WATCH_VERDICT | typeof STOP_VERDICT | typeof TRIAGE_VERDICT
 
 // What `backlog:next` answered, in the words this decision needs. The mapping is mechanical and is
-// written once, in `docs/josh-commands-automation.md` → "`josh backlog:offer`": numbers are `candidates`, `wait` is `blocked` while
+// written once, in `docs/josh-commands-backlog.md` → "`josh backlog:offer`": numbers are `candidates`, `wait` is `blocked` while
 // this run has children in flight and `exhausted` when it does not, `none` is `exhausted`, `stop` is
 // `parked`, `triage` is `untriaged`, and `error` or a failed listing is `unreadable`.
 const ANSWERS = ['blocked', 'candidates', 'exhausted', 'parked', 'unreadable', 'untriaged'] as const

package/scripts/backlog/backlog-drive-args.ts

@@ -0,0 +1,135 @@
+import { cli_flags } from '#scripts/lib/cli-flags'
+import type { DriveState } from './backlog-drive'
+
+// The `josh backlog:drive` flags — read into a `DriveContext`, and written back as the `resume:` line —
+// split out of `backlog-drive-cli.ts` when it neared its line limit (joshuafolkken/kit#3264).
+// `backlog_drive_cli` re-exports `parse` and `resume_line` under the names they always had, so the move
+// changed no call site and no suite that reads them through `backlog_drive_cli`.
+
+const MS_PER_MINUTE = 60_000
+const LIST_SEPARATOR = ','
+const COUNT_PATTERN = /^\d+$/u
+const ISSUE_PATTERN = /^[1-9]\d*$/u
+const USAGE =
+	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>] [--stopped <n>]'
+
+const OPTIONS = {
+	active: { type: 'string' },
+	await: { type: 'string' },
+	exclude: { type: 'string' },
+	idle: { type: 'string' },
+	max: { type: 'string' },
+	only: { type: 'boolean' },
+	owner: { type: 'string' },
+	stopped: { type: 'string' },
+	window: { type: 'string' },
+} as const
+
+interface DriveContext {
+	owner: string
+	active: string | undefined
+	// Flags forwarded to `backlog:offer` unchanged — the declared budgets.
+	forwarded: ReadonlyArray<string>
+	exclude: ReadonlyArray<string>
+	awaited: ReadonlyArray<string>
+	window_ms: number | undefined
+	window: string | undefined
+	is_only: boolean
+	// The child whose merge answered `stop` before the hand-back: the resumed run starts already stopping.
+	stopped: string | undefined
+}
+
+type Values = Partial<Record<Exclude<keyof typeof OPTIONS, 'only'>, string>> & { only?: boolean }
+
+function read_values(argv: ReadonlyArray<string>): Values | undefined {
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
+}
+
+// A comma list of issue numbers; one entry that is not an issue number refuses the whole list.
+function to_issues(raw: string | undefined): ReadonlyArray<string> | undefined {
+	if (raw === undefined) return []
+
+	const issues = raw.split(LIST_SEPARATOR)
+
+	return issues.some((issue) => !ISSUE_PATTERN.test(issue)) ? undefined : issues
+}
+
+function forwarded_of(values: Values): ReadonlyArray<string> | undefined {
+	const pairs = (['max', 'idle'] as const).filter((name) => values[name] !== undefined)
+
+	if (pairs.some((name) => !COUNT_PATTERN.test(values[name] ?? ''))) return undefined
+
+	return pairs.flatMap((name) => [`--${name}`, values[name] ?? ''])
+}
+
+// An absent window is no bound; a present one must be a count, which `is_valid_window` checks first.
+function window_of(raw: string | undefined): number | undefined {
+	return raw === undefined ? undefined : Number(raw) * MS_PER_MINUTE
+}
+
+function is_valid_window(raw: string | undefined): boolean {
+	return raw === undefined || COUNT_PATTERN.test(raw)
+}
+
+function is_valid_single(values: Values): boolean {
+	const is_valid_stopped = values.stopped === undefined || ISSUE_PATTERN.test(values.stopped)
+
+	return is_valid_stopped && is_valid_window(values.window)
+}
+
+function owner_of(values: Values | undefined): string | undefined {
+	const owner = values?.owner
+
+	return owner !== undefined && COUNT_PATTERN.test(owner) ? owner : undefined
+}
+
+function to_context(values: Values, owner: string): DriveContext | undefined {
+	if (!is_valid_single(values)) return undefined
+
+	const forwarded = forwarded_of(values)
+	const exclude = to_issues(values.exclude)
+	const awaited = to_issues(values.await)
+
+	if (forwarded === undefined || exclude === undefined || awaited === undefined) return undefined
+
+	const window_ms = window_of(values.window)
+
+	return {
+		owner,
+		active: values.active,
+		forwarded,
+		exclude,
+		awaited,
+		window_ms,
+		window: values.window,
+		is_only: values.only === true,
+		stopped: values.stopped,
+	}
+}
+
+function parse(argv: ReadonlyArray<string>): DriveContext | undefined {
+	const values = read_values(argv)
+	const owner = owner_of(values)
+
+	return values === undefined || owner === undefined ? undefined : to_context(values, owner)
+}
+
+function resume_line(state: DriveState, context: DriveContext): string {
+	const exclude = [...new Set([...context.exclude, ...state.exclude])]
+	const flags = ['--owner', context.owner, '--active', state.active, ...context.forwarded]
+
+	if (exclude.length > 0) flags.push('--exclude', exclude.join(LIST_SEPARATOR))
+	if (context.window !== undefined) flags.push('--window', context.window)
+	if (state.stopped_by !== undefined) flags.push('--stopped', state.stopped_by)
+
+	return `resume: ${flags.join(' ')}`
+}
+
+const backlog_drive_args = {
+	USAGE,
+	parse,
+	resume_line,
+}
+
+export { backlog_drive_args }
+export type { DriveContext }

package/scripts/backlog/backlog-drive-cli.ts

@@ -4,13 +4,11 @@ import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
-import { lane_launch_cli, type LaunchOutcome } from '#scripts/lane/lane-launch-cli'
 import { lane_registry } from '#scripts/lane/lane-registry'
-import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
-import { run_carry, type RunCarry } from '#scripts/run/run-carry'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
-import { run_merge_cli, type MergeResult } from '#scripts/run/run-merge-cli'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_merge_cli, type MergeResult } from '#scripts/run/merge/run-merge-cli'
 import { z } from 'zod'
 import {
 	backlog_drive,
@@ -19,7 +17,9 @@ import {
 	type LoopPorts,
 	type OfferRead,
 } from './backlog-drive'
+import { backlog_drive_args, type DriveContext } from './backlog-drive-args'
 import { backlog_drive_finish } from './backlog-drive-finish'
+import { backlog_drive_launch } from './backlog-drive-launch'
 import { backlog_drive_named } from './backlog-drive-named'
 import { backlog_drive_named_offer } from './backlog-drive-named-offer'
 import { backlog_drive_offer_argv } from './backlog-drive-offer-argv'
@@ -44,114 +44,7 @@ const FAILURE_EXIT_CODE = 1
 const should_forward_stderr = true
 const POLL_MS = 5000
 const OFFER_MS = 60_000
-const MS_PER_MINUTE = 60_000
 const FIRST_LINE = 0
-const LIST_SEPARATOR = ','
-const COUNT_PATTERN = /^\d+$/u
-const ISSUE_PATTERN = /^[1-9]\d*$/u
-const USAGE =
-	'Usage: josh backlog:drive --owner <pid> [--active <ISO-8601>] [--max <n>] [--idle <minutes>] [--only] [--exclude <n>[,<n>...]] [--await <n>[,<n>...]] [--window <minutes>] [--stopped <n>]'
-
-const OPTIONS = {
-	active: { type: 'string' },
-	await: { type: 'string' },
-	exclude: { type: 'string' },
-	idle: { type: 'string' },
-	max: { type: 'string' },
-	only: { type: 'boolean' },
-	owner: { type: 'string' },
-	stopped: { type: 'string' },
-	window: { type: 'string' },
-} as const
-
-interface DriveContext {
-	owner: string
-	active: string | undefined
-	// Flags forwarded to `backlog:offer` unchanged — the declared budgets.
-	forwarded: ReadonlyArray<string>
-	exclude: ReadonlyArray<string>
-	awaited: ReadonlyArray<string>
-	window_ms: number | undefined
-	window: string | undefined
-	is_only: boolean
-	// The child whose merge answered `stop` before the hand-back: the resumed run starts already stopping.
-	stopped: string | undefined
-}
-
-type Values = Partial<Record<Exclude<keyof typeof OPTIONS, 'only'>, string>> & { only?: boolean }
-
-function read_values(argv: ReadonlyArray<string>): Values | undefined {
-	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
-}
-
-// A comma list of issue numbers; one entry that is not an issue number refuses the whole list.
-function to_issues(raw: string | undefined): ReadonlyArray<string> | undefined {
-	if (raw === undefined) return []
-
-	const issues = raw.split(LIST_SEPARATOR)
-
-	return issues.some((issue) => !ISSUE_PATTERN.test(issue)) ? undefined : issues
-}
-
-function forwarded_of(values: Values): ReadonlyArray<string> | undefined {
-	const pairs = (['max', 'idle'] as const).filter((name) => values[name] !== undefined)
-
-	if (pairs.some((name) => !COUNT_PATTERN.test(values[name] ?? ''))) return undefined
-
-	return pairs.flatMap((name) => [`--${name}`, values[name] ?? ''])
-}
-
-// An absent window is no bound; a present one must be a count, which `is_valid_window` checks first.
-function window_of(raw: string | undefined): number | undefined {
-	return raw === undefined ? undefined : Number(raw) * MS_PER_MINUTE
-}
-
-function is_valid_window(raw: string | undefined): boolean {
-	return raw === undefined || COUNT_PATTERN.test(raw)
-}
-
-function is_valid_single(values: Values): boolean {
-	const is_valid_stopped = values.stopped === undefined || ISSUE_PATTERN.test(values.stopped)
-
-	return is_valid_stopped && is_valid_window(values.window)
-}
-
-function owner_of(values: Values | undefined): string | undefined {
-	const owner = values?.owner
-
-	return owner !== undefined && COUNT_PATTERN.test(owner) ? owner : undefined
-}
-
-function to_context(values: Values, owner: string): DriveContext | undefined {
-	if (!is_valid_single(values)) return undefined
-
-	const forwarded = forwarded_of(values)
-	const exclude = to_issues(values.exclude)
-	const awaited = to_issues(values.await)
-
-	if (forwarded === undefined || exclude === undefined || awaited === undefined) return undefined
-
-	const window_ms = window_of(values.window)
-
-	return {
-		owner,
-		active: values.active,
-		forwarded,
-		exclude,
-		awaited,
-		window_ms,
-		window: values.window,
-		is_only: values.only === true,
-		stopped: values.stopped,
-	}
-}
-
-function parse(argv: ReadonlyArray<string>): DriveContext | undefined {
-	const values = read_values(argv)
-	const owner = owner_of(values)
-
-	return values === undefined || owner === undefined ? undefined : to_context(values, owner)
-}
 
 // The `--json` object `backlog:offer` prints, keyed under its `JSON_KEY`.
 const offer_read_schema = z.object({
@@ -235,14 +128,6 @@ async function merge(issue: string, owner: string): Promise<MergeResult> {
 	return result
 }
 
-async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind']> {
-	await backlog_drive_owner.assert_current(owner)
-
-	const outcome = await lane_launch_cli.launch_lane({ issue, stash: undefined })
-
-	return outcome.kind
-}
-
 // `lane:await`'s re-confirmed check, one state per child. A child already gone when the loop starts —
 // a restart after it ended — is read as having appeared, so it is collected after the re-confirm window
 // rather than waited on until the never-appeared timeout. One that never appeared is collected too:
@@ -278,17 +163,6 @@ async function open_lanes(): Promise<ReadonlyArray<string>> {
 	return lanes.filter((lane) => !lane.is_stranded).map((lane) => lane.issue)
 }
 
-function resume_line(state: DriveState, context: DriveContext): string {
-	const exclude = [...new Set([...context.exclude, ...state.exclude])]
-	const flags = ['--owner', context.owner, '--active', state.active, ...context.forwarded]
-
-	if (exclude.length > 0) flags.push('--exclude', exclude.join(LIST_SEPARATOR))
-	if (context.window !== undefined) flags.push('--window', context.window)
-	if (state.stopped_by !== undefined) flags.push('--stopped', state.stopped_by)
-
-	return `resume: ${flags.join(' ')}`
-}
-
 function end_line(end: DriveEnd): string {
 	const token = end.token === undefined || end.token === end.reason ? [] : [end.token]
 	const issue = end.issue === undefined ? [] : [`#${end.issue}`]
@@ -306,7 +180,7 @@ function ports_of(
 		is_finished: finished_checker(seeded),
 		merge: async (issue) => await merge(issue, context.owner),
 		offer: async (state) => await read_offer(state, context),
-		launch: async (issue) => await launch(issue, context.owner),
+		launch: async (issue) => await backlog_drive_launch.launch(issue, context.owner),
 		free_lanes: backlog_ready.drive_free_lane_count,
 		now: () => new Date(),
 		sleep: async (milliseconds) => {
@@ -345,7 +219,7 @@ async function drive(context: DriveContext): Promise<number> {
 	const end = await backlog_drive.run_loop(last.state, config, ports_of(context, seeded, last))
 
 	console.info(end_line(end))
-	console.info(resume_line(last.state, context))
+	console.info(backlog_drive_args.resume_line(last.state, context))
 
 	return SUCCESS_EXIT_CODE
 }
@@ -361,10 +235,10 @@ async function run_safe(context: DriveContext): Promise<number> {
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const context = parse(argv)
+	const context = backlog_drive_args.parse(argv)
 
 	if (context === undefined) {
-		console.error(USAGE)
+		console.error(backlog_drive_args.USAGE)
 
 		return FAILURE_EXIT_CODE
 	}
@@ -384,8 +258,8 @@ const backlog_drive_cli = {
 	merge,
 	merge_token,
 	offer_argv: backlog_drive_offer_argv.offer_argv,
-	parse,
-	resume_line,
+	parse: backlog_drive_args.parse,
+	resume_line: backlog_drive_args.resume_line,
 	to_offer,
 }