@joshuafolkken/kit 1.1435.0 → 1.1455.0

package/dist/hooks/pretool-guard.js

@@ -1,22 +1,22 @@
 #!/usr/bin/env tsx
 import {
   pretool_guard
-} from "./chunk-JXQBK323.js";
-import "./chunk-MSYSUSY6.js";
-import "./chunk-YZXYOAZ3.js";
+} from "./chunk-HHI6FO3R.js";
+import "./chunk-HFGWYGUV.js";
+import "./chunk-7WQBPLUN.js";
 import "./chunk-IX6TTTI6.js";
-import "./chunk-YW452ZAX.js";
+import "./chunk-Z4XI7CZS.js";
 import "./chunk-CDY4NFQG.js";
-import "./chunk-7KMN5QB5.js";
-import "./chunk-2G5F2YCD.js";
-import "./chunk-QL6QTPWN.js";
-import "./chunk-5SJSSCJG.js";
+import "./chunk-5H4SSDSD.js";
+import "./chunk-D5QBTOCZ.js";
+import "./chunk-WNLVGT7E.js";
+import "./chunk-UT7YC3N2.js";
 import {
   hook_decision
-} from "./chunk-MU4LJFIV.js";
-import "./chunk-XER6SSIB.js";
-import "./chunk-4BHUPFKF.js";
-import "./chunk-3LE6VLSR.js";
+} from "./chunk-GPLGZ6IC.js";
+import "./chunk-LIAFCXL7.js";
+import "./chunk-OLMO72ON.js";
+import "./chunk-3C4XRYG6.js";
 import "./chunk-DGT54IH5.js";
 
 // scripts/hooks/pretool-guard-cli.ts

package/dist/hooks/session-lang.js

@@ -8,19 +8,19 @@ import {
   run_event_stream_emit,
   run_headless,
   session_language
-} from "./chunk-YW452ZAX.js";
+} from "./chunk-Z4XI7CZS.js";
 import {
   error_text
 } from "./chunk-CDY4NFQG.js";
 import {
   josh_environment_file
-} from "./chunk-4BHUPFKF.js";
+} from "./chunk-OLMO72ON.js";
 import {
   agent_session_environment,
   json_value,
   process_identity,
   run_carry
-} from "./chunk-3LE6VLSR.js";
+} from "./chunk-3C4XRYG6.js";
 import {
   stamp_file
 } from "./chunk-DGT54IH5.js";

package/dist/hooks/stop-guard.js

@@ -13,7 +13,7 @@ import {
   repo_party,
   run_cut,
   run_hold
-} from "./chunk-YZXYOAZ3.js";
+} from "./chunk-7WQBPLUN.js";
 import {
   agent_headless,
   agent_role_profile,
@@ -23,22 +23,22 @@ import {
   run_event_stream_emit,
   run_headless,
   session_language
-} from "./chunk-YW452ZAX.js";
+} from "./chunk-Z4XI7CZS.js";
 import {
   timed_fetch
 } from "./chunk-723HKZO5.js";
 import "./chunk-CDY4NFQG.js";
 import {
   hook_decision
-} from "./chunk-MU4LJFIV.js";
+} from "./chunk-GPLGZ6IC.js";
 import {
   time_density_hook,
   time_hook_transcript,
   time_reported_failure
-} from "./chunk-XER6SSIB.js";
+} from "./chunk-LIAFCXL7.js";
 import {
   lane_child_marker
-} from "./chunk-4BHUPFKF.js";
+} from "./chunk-OLMO72ON.js";
 import {
   backlog_budget,
   issue_number_shape,
@@ -47,7 +47,7 @@ import {
   process_owner_schema,
   run_carry,
   run_invocation
-} from "./chunk-3LE6VLSR.js";
+} from "./chunk-3C4XRYG6.js";
 import {
   stamp_file
 } from "./chunk-DGT54IH5.js";
@@ -317,6 +317,52 @@ var backlog_ready = {
 
 // scripts/notify/telegram-notify.ts
 import { z } from "zod";
+
+// scripts/notify/confirmation-options.ts
+var JAPANESE_LANG_PREFIX = "ja";
+var JAPANESE_HEADINGS = {
+  recommended: "\u63A8\u5968:",
+  alternatives: "\u4ED6\u306E\u9078\u629E\u80A2:",
+  none: "\u306A\u3057"
+};
+var ENGLISH_HEADINGS = {
+  recommended: "Recommended:",
+  alternatives: "Alternatives:",
+  none: "none"
+};
+function headings() {
+  const { lang } = session_language.resolve_session_lang();
+  return lang.toLowerCase().startsWith(JAPANESE_LANG_PREFIX) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS;
+}
+function alternatives_block(options, labels) {
+  if (options.alternatives.length === 0) return `${labels.alternatives} ${labels.none}`;
+  const lines = options.alternatives.map((alternative) => `- ${alternative}`);
+  return [labels.alternatives, ...lines].join("\n");
+}
+function block(options) {
+  const labels = headings();
+  return `${labels.recommended} ${options.recommended}
+${alternatives_block(options, labels)}`;
+}
+var confirmation_options = { block };
+
+// scripts/notify/notify-opt-in.ts
+var OPT_IN_KEY = "JOSH_NOTIFY_OPT_IN";
+var OPTIONAL_TASK_TYPES = /* @__PURE__ */ new Set(["planning", "completion"]);
+var LIST_SEPARATOR = ",";
+function opted_in_types() {
+  return (process.env[OPT_IN_KEY] ?? "").split(LIST_SEPARATOR).map((entry) => entry.trim().toLowerCase()).filter((entry) => entry.length > 0);
+}
+function is_skipped(task_type) {
+  if (!OPTIONAL_TASK_TYPES.has(task_type)) return false;
+  return !opted_in_types().includes(task_type);
+}
+function skip_line(task_type) {
+  return `\u{1F515} ${task_type} notifications are not opted in (${OPT_IN_KEY}).`;
+}
+var notify_opt_in = { is_skipped, skip_line };
+
+// scripts/notify/telegram-notify.ts
 var TELEGRAM_API_BASE = "https://api.telegram.org";
 var TELEGRAM_TEXT_LIMIT = 4096;
 var BODY_TRUNCATION_MARK = "\n...";
@@ -377,6 +423,12 @@ function load_config() {
 function is_notify_disabled() {
   return parse_environment_string(process.env[NOTIFY_SWITCH_KEY]).toLowerCase() === NOTIFY_OFF_VALUE;
 }
+function skip_line2(task_type) {
+  if (is_notify_disabled()) {
+    return `\u{1F515} Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`;
+  }
+  return notify_opt_in.is_skipped(task_type) ? notify_opt_in.skip_line(task_type) : void 0;
+}
 function build_header(task_type, repo_name) {
   const { icon, label } = TASK_DEFINITIONS[task_type];
   if (repo_name === void 0 || repo_name.length === 0) return `${icon} ${label}`;
@@ -402,6 +454,7 @@ function build_url_parts(input) {
 function build_blocks(input) {
   const blocks = [build_title_block(input)];
   push_if_present(blocks, input.body);
+  push_if_present(blocks, input.choices);
   blocks.push(...build_url_parts(input));
   return blocks;
 }
@@ -435,10 +488,9 @@ function build_send_failure(error, config) {
   return new Error(`${SEND_FAILED_PREFIX}: ${reason}`, { cause: new Error(reason) });
 }
 async function send(input) {
-  if (is_notify_disabled()) {
-    console.info(
-      `\u{1F515} Telegram notifications are disabled (${NOTIFY_SWITCH_KEY}=${NOTIFY_OFF_VALUE}).`
-    );
+  const skipped = skip_line2(input.task_type);
+  if (skipped !== void 0) {
+    console.info(skipped);
     return;
   }
   const config = load_config();
@@ -487,6 +539,7 @@ async function confirm(input) {
       repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
       issue_title: input.issue_title,
       body: input.body,
+      choices: confirmation_options.block(input),
       issue_url: void 0,
       pr_url: void 0
     },
@@ -762,7 +815,7 @@ var stop_payload_schema = z3.object({
   last_assistant_message: z3.string().nullish()
 });
 var NO_OUTCOME = { reason: void 0 };
-var STOP_NOTIFY_REASON = '\u26D4 mid-workflow stop notification: this working tree is still held by a run and no `confirmation` Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run paused. `CLAUDE.md` \u2192 "Mid-workflow stop notification" requires `pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\'` before any mid-workflow pause. Send it, then end with a one-line confirmation that it was sent \u2014 do not repeat your previous reply. This fires only while the hold is held and no notify is on the transcript, and `stop_hook_active` lets a second stop through so a run is never wedged.';
+var STOP_NOTIFY_REASON = '\u26D4 mid-workflow stop notification: this working tree is still held by a run and no `confirmation` Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run paused. `CLAUDE.md` \u2192 "Mid-workflow stop notification" requires `pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\' --recommended "<choice>" --alternative "<choice>"` before any mid-workflow pause. Send it, then end with a one-line confirmation that it was sent \u2014 do not repeat your previous reply. This fires only while the hold is held and no notify is on the transcript, and `stop_hook_active` lets a second stop through so a run is never wedged.';
 var HOLD_RELEASE_REASON = "\u26D4 working-tree hold not released: this working tree is clean but its `run:hold` record is still in place, so the next run here runs `pnpm josh ms` believing the tree is free while you hold it. The workflow-commands skill \u2192 `working-tree-hold.md`: a stop that leaves the tree clean releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty, and a `prrun` stop keeps it by its stop mark \u2014 this row is silent there. Release it, then end with a one-line confirmation that it was released \u2014 do not repeat your previous reply.";
 var ISSUE_CITATION_REASON = "Session-facing output cites an Issue as a number-link so the reader can click through and see which repository it is (`CLAUDE.md`, `prompts/collaboration-workflow/issue-citation.md`).";
 function build_citation_reason(references) {

package/dist/josh.js

@@ -395,6 +395,7 @@ var START_TIME_FORMAT = "lstart=";
 var PID_FLAG = "-p";
 var PROBE_ENVIRONMENT = { TZ: "UTC", LC_ALL: "C" };
 var LIVENESS_SIGNAL = 0;
+var NO_SUCH_PROCESS = "ESRCH";
 var LOWEST_REAL_PID = 1;
 var PROC_START_FIELD_INDEX = 19;
 var BEACON_SCHEME = "socket:";
@@ -409,15 +410,20 @@ var BEACON_GONE_STATUS = 2;
 var SOCKET_PROBE_SOURCE = `const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(${String(BEACON_LIVE_STATUS)}));socket.once('error',(error)=>process.exit(['ECONNREFUSED','ENOENT'].includes(error.code)?${String(BEACON_GONE_STATUS)}:${String(BEACON_UNKNOWN_STATUS)}));socket.setTimeout(1000,()=>process.exit(${String(BEACON_UNKNOWN_STATUS)}));`;
 var beacons = /* @__PURE__ */ new Map();
 var exit_cleanup = { is_registered: false };
-function is_live_pid(pid) {
-  if (pid < LOWEST_REAL_PID) return false;
+function signal_refusal(pid) {
   try {
     process.kill(pid, LIVENESS_SIGNAL);
-    return true;
-  } catch {
-    return false;
+    return void 0;
+  } catch (error) {
+    return error.code ?? NO_SUCH_PROCESS;
   }
 }
+function is_live_pid(pid) {
+  return pid >= LOWEST_REAL_PID && signal_refusal(pid) === void 0;
+}
+function is_present_pid(pid) {
+  return pid >= LOWEST_REAL_PID && signal_refusal(pid) !== NO_SUCH_PROCESS;
+}
 function read_proc_start(pid) {
   try {
     const stat = readFileSync3(`/proc/${String(pid)}/stat`, "utf8");
@@ -543,6 +549,11 @@ function is_same_process(pid, recorded_start, read2 = read_start) {
   if (recorded_start === void 0) return void 0;
   return matches_recorded_start(pid, recorded_start, read2);
 }
+function is_present_process(pid, recorded_start, read2 = read_start) {
+  if (!is_present_pid(pid)) return false;
+  if (recorded_start === void 0) return void 0;
+  return matches_recorded_start(pid, recorded_start, read2);
+}
 function is_own_process(pid, recorded_start) {
   return pid === process.pid && recorded_start === own_start();
 }
@@ -551,6 +562,8 @@ var process_identity = {
   is_live_beacon,
   is_live_pid,
   is_own_process,
+  is_present_pid,
+  is_present_process,
   is_same_process,
   open_beacon,
   own_fields,
@@ -1447,16 +1460,16 @@ var ISSUE_COMMANDS = {
     description: "File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle",
     category: "AI tools",
     reference: [
-      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>] [--over-cap] [--no-auto-ok] [--requested] [--release]",
+      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>] [--over-cap] [--no-auto-ok] [--release]",
       "automation",
       ["network"]
     ]
   },
   "issue:release": {
     script: "scripts/issue/issue-release-cli.ts",
-    description: "Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+    description: "Link an Issue to the repository's open release Issue as its blocker (or, with --wait, as waiting on it), filing one when none is open",
     category: "AI tools",
-    reference: ["<issue>", "automation", ["network"]]
+    reference: ["<issue> [--wait]", "automation", ["network"]]
   }
 };
 
@@ -1741,6 +1754,16 @@ var AI_COMMANDS = {
     category: "AI tools",
     reference: ["[--exclude <n>[,<n>...]] [--label <name>]", "automation", ["network"]]
   },
+  "auto-ok:judge": {
+    script: "scripts/auto-ok/auto-ok-judge-cli.ts",
+    description: "List the open issues backlogrun owes an auto-ok judgement, or record one (--apply / --decline)",
+    category: "AI tools",
+    reference: [
+      "[--apply <n> (--lane | --solo) | --decline <n> --reason <text>]",
+      "automation",
+      ["network"]
+    ]
+  },
   ...BACKLOG_COMMANDS,
   cost: {
     script: "scripts/cost-runtime/cost-cli.ts",
@@ -2528,7 +2551,7 @@ var PROJECT_COMMANDS = {
     description: "Set a project up for the GitHub Issue workflow, from git init to the setup PR",
     category: "Project",
     reference: [
-      `${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]`,
+      `${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--dry-run] [--init-command <command>] [--push-preflight-command <command>]`,
       "developer",
       ["files", "git", "network", "processes"]
     ]
@@ -2561,7 +2584,7 @@ var PROJECT_COMMANDS = {
     description: "Initialize config in a new project",
     category: "Project",
     reference: [
-      `${PROFILE_ARGUMENTS} [--no-install]`,
+      `${PROFILE_ARGUMENTS} [--no-install] [--dry-run]`,
       "developer",
       ["files", "network", "processes"]
     ]
@@ -2724,7 +2747,7 @@ var WORKFLOW_COMMANDS = {
     description: "Send Telegram notification",
     category: "Workflow",
     reference: [
-      "[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]",
+      "[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>] [--recommended <text>] [--alternative <text>]...",
       "automation",
       ["notifications"]
     ],

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1435.0",
+  "version": "1.1455.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [

package/prompts/collaboration-workflow/issue-template.md

@@ -6,6 +6,7 @@
 ## 背景
 
 <不具合なら `- 種別: 不具合`、そうでなければ `- 種別: 非不具合` を宣言する>
+<人の判断が要らなければ `- 人の判断: 不要`、要るなら `- 人の判断: 要（<方針の判断 / 外部アカウント / 目視確認>）` を宣言する>
 
 <なぜ必要か>
 
@@ -49,15 +50,16 @@
 
 ### `## 背景` 直下の宣言と分類ラベル
 
-起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行う。本文の検査（`pnpm josh issue:lint <path>` と同じ）と、下表の宣言から決まる分類ラベルの付与は、このコマンドが 1 回の作成リクエストで行う。**宣言を選ぶのは起票者の判断であり、コマンドは単語から推測しない。** 人が依頼した起票（会話での依頼も含む）には `--requested` を付ける（`kickoff.md` → "Words typed after `new`"）。
+起票は `pnpm josh issue:file "<title>" --body-file <本文ファイル> --depth <n>` で行う。本文の検査（`pnpm josh issue:lint <path>` と同じ）と、下表の宣言から決まる分類ラベルの付与は、このコマンドが 1 回の作成リクエストで行う。**宣言を選ぶのは起票者の判断であり、コマンドは単語から推測しない。** `- 人の判断:` の行は必須で、`issue:file` だけが検査し（`issue:lint` は見ない）、`auto-ok` の判定に使う。判定は人が依頼した起票も含めてすべて同じ（`scripts/issue/issue-auto-ok.ts`、`docs/how-to/run-backlog.md`）。**`不要` を宣言する起票には `--label run:lane`（kit 自身の検証の不具合なら `run:solo`）も付ける** — 付いていなければ `issue:file` が拒否する。
 
-| 宣言                   | 付くラベル        | 選ぶ基準                                                                                   |
-| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
-| `- 種別: 不具合`       | `bug`             | 報告された症状を直す。`- 種別: 非不具合` とどちらか一方を必ず置く                          |
-| `- 目的: 機能追加`     | `enhancement`     | 新しい機能。不具合修正・文書のみ・依存更新・保守作業には書かない                           |
-| `- 目的: 機能改善`     | `enhancement`     | 既存機能の改善。目的が曖昧なら期待結果と受け入れ条件を具体化してから選ぶ                   |
-| `- 互換性: 破壊的変更` | `breaking-change` | 既存の利用者・API・設定の契約を変える。移行措置があっても書き、廃止対象と影響を説明する    |
-| `- 種別: 振る舞い変更` | なし              | AI の振る舞いを変える。`## 発火点` / `## ベースライン` / `## 再現` の 3 見出しが必須になる |
+| 宣言                   | 付くラベル                        | 選ぶ基準                                                                                                        |
+| ---------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `- 種別: 不具合`       | `bug`                             | 報告された症状を直す。`- 種別: 非不具合` とどちらか一方を必ず置く                                               |
+| `- 目的: 機能追加`     | `enhancement`                     | 新しい機能。不具合修正・文書のみ・依存更新・保守作業には書かない                                                |
+| `- 目的: 機能改善`     | `enhancement`                     | 既存機能の改善。目的が曖昧なら期待結果と受け入れ条件を具体化してから選ぶ                                        |
+| `- 互換性: 破壊的変更` | `breaking-change`                 | 既存の利用者・API・設定の契約を変える。移行措置があっても書き、廃止対象と影響を説明する                         |
+| `- 種別: 振る舞い変更` | なし                              | AI の振る舞いを変える。`## 発火点` / `## ベースライン` / `## 再現` の 3 見出しが必須になる                      |
+| `- 人の判断: 不要`     | `auto-ok`（除外ラベルがなければ） | 方針の判断・外部アカウント・人の目視確認のどれも要らない。`- 人の判断: 要（<どれか>）` とどちらか一方を必ず置く |
 
 - **持ち主の意図と違う動きは、コード・コメント・テストに書かれた設計どおりでも `- 種別: 不具合` とする。** コードは意図を写したもので、意図そのものではない。変更の形（コードか文書か）でも決めない。例: コメントとテストに固定されたまま意図より広く働く自動付与、文書だけでも意図と違う分類を生む基準
 - **`- 種別: 不具合` の Issue の回帰テストは、利用者が症状を見たのと同じ粒度で書く。** 修正前のツリーでも緑になるテストは `pnpm josh git -y` がコミットを拒否する（joshuafolkken/kit#2448）

package/prompts/collaboration-workflow/shell-body.md

@@ -25,7 +25,7 @@ zsh は `pnpm josh ms` を実行し、その標準出力を本文に埋め込む
 pnpm josh issue:comment <N> --body-file <path>
 gh api -X PATCH repos/{owner}/{repo}/issues/<N> --field body=@<path>
 pnpm josh followup "<title> #<N>" --notify-message-file <path>
-pnpm josh notify --task-type confirmation --issue-url "<url>" --body-file <path>
+pnpm josh notify --task-type confirmation --issue-url "<url>" --body-file <path> --recommended "<choice>"
 ```
 
 **PR コメントも同じ経路である** — REST では pull request のコメントは issue のコメントであり、`pnpm josh issue:comment <N> --body-file <path>` がそのまま使える。`gh issue comment` / `gh pr comment` は使わない（GraphQL 経由。理由は `docs/maintainers/shell-body-rationale.md` → "Why no `gh` subcommand is written in an executable block"）。

package/prompts/review.md

@@ -100,10 +100,14 @@ round-1 High/Medium finding actually closed — by a fix in this working tree, o
 positive — and none was filed or deferred. **Without the flag the answer is `required`**, which is also
 what the command answers to every uncertainty it meets, a missing round-1 snapshot included.
 
-**`skip` has exactly two arms** — **A** (no fix code: the fix delta is empty) and **B** (inert fix
-code: every path in the fix delta is inert by the review-level classification above); the reason line
-names which fired. Why neither weakens the standard: `docs/maintainers/review-history.md` → "The two
-skip arms".
+**`skip` has exactly two arms** — **A** (no fix code: the fix delta is empty) and **B** (a fix that
+leaves what executes unchanged: every path in the fix delta is inert by the review-level classification
+above, `docs/**/*.md`, the root `README.md`, under `prompts/`, or a `.ts` / `.js` / `.svelte` file
+outside `.claude/` whose only change is in comments, a directive comment — lint, type-check, coverage
+or bundler — counting as code); the reason line names which fired. **One path
+outside that set makes the round `required`** — `.claude/**`, `CLAUDE.md`, a test, configuration, a
+code line, or a source file whose comment-free text cannot be read. Why neither arm weakens the
+standard: `docs/maintainers/review-history.md` → "The two skip arms".
 
 **A skipped round is recorded on the Issue**, so the condition stays auditable and can be withdrawn if
 a defect is later traced to a skipped delta:

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

@@ -0,0 +1,125 @@
+import { fileURLToPath } from 'node:url'
+import { RUN_LANE_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { auto_ok_judge_read } from './auto-ok-judge-read'
+import { auto_ok_judge_write } from './auto-ok-judge-write'
+
+// `josh auto-ok:judge` — the open issues `backlogrun` judges for `auto-ok` when a lane is free and
+// nothing is opted in (joshuafolkken/kit#3854), and the record of each judgement.
+//
+// Bare, it lists the issues that still owe a judgement: one number per line on stdout, or `none`, with
+// each title on stderr. The agent reads each one's body and comments (`josh issue:read`) and answers
+// with `--apply <N> --lane|--solo` or `--decline <N> --reason <text>`; which of the two is a reading of
+// the issue, never this command's.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const NONE_TOKEN = 'none'
+const USAGE =
+	'Usage: josh auto-ok:judge [--apply <N> (--lane | --solo) | --decline <N> --reason <text>]'
+
+const OPTIONS = {
+	apply: { type: 'string' },
+	decline: { type: 'string' },
+	lane: { type: 'boolean' },
+	solo: { type: 'boolean' },
+	reason: { type: 'string' },
+} as const
+
+type Values = NonNullable<ReturnType<typeof cli_flags.values_of<typeof OPTIONS>>>
+
+type JudgeRequest =
+	| { kind: 'list' }
+	| { kind: 'apply'; issue: string; run_label: string }
+	| { kind: 'decline'; issue: string; reason: string }
+
+function run_label_of(values: Values): string | undefined {
+	if (values.lane === values.solo) return undefined
+
+	return values.lane === true ? RUN_LANE_LABEL : RUN_SOLO_LABEL
+}
+
+function apply_request(issue: string, values: Values): JudgeRequest | undefined {
+	const run_label = run_label_of(values)
+
+	return run_label === undefined ? undefined : { kind: 'apply', issue, run_label }
+}
+
+function decline_request(issue: string, values: Values): JudgeRequest | undefined {
+	const reason = values.reason?.trim() ?? ''
+
+	return reason === '' ? undefined : { kind: 'decline', issue, reason }
+}
+
+function request_of(values: Values): JudgeRequest | undefined {
+	const issue = values.apply ?? values.decline
+
+	if (issue === undefined) return { kind: 'list' }
+	if (!issue_number_shape.is_issue_number(issue)) return undefined
+
+	return values.apply === undefined ? decline_request(issue, values) : apply_request(issue, values)
+}
+
+function parse_request(argv: ReadonlyArray<string>): JudgeRequest | undefined {
+	const values = cli_flags.values_of(argv, OPTIONS)
+
+	if (values === undefined || (values.apply !== undefined && values.decline !== undefined)) {
+		return undefined
+	}
+
+	return request_of(values)
+}
+
+async function list(): Promise<number> {
+	const owed = await auto_ok_judge_read.owed()
+
+	if (owed === undefined) {
+		console.error('the open issues could not be read')
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (owed.length === 0) console.info(NONE_TOKEN)
+
+	for (const row of owed) {
+		console.error(session_cite.issue(row.number, row.title))
+		console.info(String(row.number))
+	}
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function dispatch(request: JudgeRequest): Promise<number> {
+	const { apply, decline } = auto_ok_judge_write
+
+	if (request.kind === 'list') return await list()
+	if (request.kind === 'decline') return await decline(request.issue, request.reason)
+
+	return await apply(request.issue, request.run_label)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await dispatch(request)
+}
+
+// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const auto_ok_judge_cli = { NONE_TOKEN, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { auto_ok_judge_cli }

package/scripts/auto-ok/auto-ok-judge-read.ts

@@ -0,0 +1,95 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { issue_watch_diff } from '#scripts/issue/issue-watch-diff'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { z } from 'zod'
+import { auto_ok_judge, type JudgeIssue } from './auto-ok-judge'
+
+// The reading half of `josh auto-ok:judge`: the open issues that still owe a judgement, shared by the
+// command's listing and the backlog driver's check for a free lane with nothing opted in.
+//
+// **The driver asks once a minute while it watches**, so it hands in a cache it keeps for its process:
+// an issue seen judged is remembered with its `updatedAt`, and its comments are read again only once
+// that moves — a body edit, a comment or a label change. Without it every watch minute would read the
+// comments of every candidate in the repository.
+
+// The listing cap `auto-ok:next` reads the opted-in pool under; the open backlog is read under the same.
+const LISTING_LIMIT = 200
+// How many comment listings run at once — a handful of `gh` processes, never one per candidate.
+const COMMENT_READ_WIDTH = 4
+
+const row_schema = z.looseObject({
+	number: z.number(),
+	title: z.string(),
+	body: z.string().nullish(),
+	labels: z.array(issue_label_schema),
+	updatedAt: z.string(),
+})
+
+interface JudgeRow extends JudgeIssue {
+	title: string
+	updated_at: string
+}
+
+// An issue's number to the `updatedAt` it was last seen judged at.
+type JudgedCache = Map<number, string>
+
+function to_row(raw: z.infer<typeof row_schema>): JudgeRow {
+	return {
+		number: raw.number,
+		title: raw.title,
+		body: raw.body ?? '',
+		labels: raw.labels.map((label) => label.name),
+		updated_at: raw.updatedAt,
+	}
+}
+
+// `undefined` when the listing could not be read, which is never "nothing to judge".
+async function read_candidates(): Promise<ReadonlyArray<JudgeRow> | undefined> {
+	const { json } = await git_gh_command.issue_list_open_for_judgement(LISTING_LIMIT)
+
+	if (json === undefined) return undefined
+
+	const listing = read_json_listing(json, row_schema)
+
+	if (listing.kind !== 'read') return undefined
+
+	return listing.rows.map((raw) => to_row(raw)).filter((row) => auto_ok_judge.is_candidate(row))
+}
+
+// `true` only for an issue known to owe a judgement: a failed comment read learns nothing, so it is
+// neither counted nor remembered.
+async function owes_judgement(row: JudgeRow, cache: JudgedCache): Promise<boolean> {
+	if (cache.get(row.number) === row.updated_at) return false
+
+	const comments = issue_watch_diff.parse_comments(
+		await git_gh_command.issue_list_comments(String(row.number)),
+	)
+
+	if (comments === undefined) return false
+	if (!auto_ok_judge.is_judged(row.body, comments)) return true
+
+	cache.set(row.number, row.updated_at)
+
+	return false
+}
+
+async function owed(cache: JudgedCache = new Map()): Promise<ReadonlyArray<JudgeRow> | undefined> {
+	const candidates = await read_candidates()
+
+	if (candidates === undefined) return undefined
+
+	const owing = await bounded_pool.bounded_map(
+		candidates,
+		COMMENT_READ_WIDTH,
+		async (row) => await owes_judgement(row, cache),
+	)
+
+	return candidates.filter((_row, index) => owing[index] === true)
+}
+
+const auto_ok_judge_read = { owed }
+
+export type { JudgedCache, JudgeRow }
+export { auto_ok_judge_read }