nightralph 0.0.53 → 0.0.56

package/README.md

@@ -22,22 +22,28 @@ so they can't drift as long as you install the skills with this package.
 <!-- toc -->
 
 - [Install](#install)
+  * [Requirements](#requirements)
   * [Install Dependency Skills](#install-dependency-skills)
 - [Workflow](#workflow)
   * [Create Issues](#create-issues)
-  * [Examples](#examples)
-  * [Interface](#interface)
-    + [`--spec ` option](#--spec--option)
+- [Examples](#examples)
+- [Command Line Arguments](#command-line-arguments)
+  * [Notes](#notes)
+  * [`--spec ` option](#--spec--option)
+  * [`--prefer-subagent` option](#--prefer-subagent-option)
 - [How It Works](#how-it-works)
   * [Select a ticket](#select-a-ticket)
   * [Worktrees](#worktrees)
   * [Progress](#progress)
+  * [Integration branch](#integration-branch)
+  * [Review](#review)
   * [Status display](#status-display)
 - [Keep Your Machine Awake](#keep-your-machine-awake)
   * [Mac OS](#mac-os)
     + [Claude Opus 4.6](#claude-opus-46)
     + [Claude Opus 5.5](#claude-opus-55)
-    + [Claude Sonnet 5](#claude-sonnet-5)
+    + [Claude Sonnet 5.5](#claude-sonnet-55)
+    + [Claude Haiku 5.5](#claude-haiku-55)
     + [Claude Fable 5.1](#claude-fable-51)
     + [`pi` + OpenRouter model](#pi--openrouter-model)
     + [`codex` + Luna](#codex--luna)
@@ -52,6 +58,19 @@ so they can't drift as long as you install the skills with this package.
 npm i -S nightralph
 ```
 
+### Requirements
+
+- Node 24 or newer (see `engines` in `package.json`) and git.
+- The agent CLI you name on the command line (`claude`, `codex` or
+  `pi`) installed and on your `PATH`. After it finds tickets,
+  nightralph checks for this command before it touches git, and
+  exits with code 2 if the command is not found. A run with no
+  tickets stops before the check. With `--dry-run` it prints the
+  problem and keeps going.
+- macOS or Linux. nightralph runs agents in their own process group
+  and uses `sh -c` for test and install commands, so it does not
+  run on Windows.
+
 ### Install Dependency Skills
 
 ```sh
@@ -100,8 +119,8 @@ a prose text description.
 The `nightralph` CLI does the `tdd` part of the workflow: the agent
 prompt tells the agent to write a failing test per acceptance
 criterion at the seams named in the spec's Testing Decisions, and
-the orchestrator runs the project's test command in the worktree
-before a ticket can be marked `done`.
+the orchestrator runs the project's test command, when there is
+one, in the worktree before a ticket can be marked `done`.
 
 >
 > [!NOTE]  
@@ -118,7 +137,7 @@ before a ticket can be marked `done`.
 > then follow with `to-tickets`.
 >
 
-### Examples
+## Examples
 
 After you have the tickets, use the `nightralph` loop to execute.
 The `to-tickets` skill produces markdown files at
@@ -150,29 +169,31 @@ npx nightralph claude -m claude-opus-4-6 30
 npx nightralph pi -m openrouter/z-ai/glm-5.3-flash --effort medium --retries 1
 ```
 
-### Interface
+## Command Line Arguments
 
 Flags:
 
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `<provider>` | yes | -- | Agent harness to spawn (e.g. `claude`, `codex`, `pi`) |
-| `[turns]` | no | -- | Max agentic turns per ticket (positional shorthand for `--max-turns`) |
+| `[turns]` | no | -- | Max agentic turns per agent run (positional shorthand for `--max-turns`) |
 | `-m`, `--model` | no | -- | Model flag passed to the agent |
 | `--spec <name>` | no | auto | Feature name (resolves `.scratch/<name>/`) |
 | `--dry-run` | no | -- | Show wave order and prompt without running |
+| `--no-review` | no | review on | Skip the review and fix pass at the end of a run |
 | `-X` | no | -- | Stop on merge conflict instead of re-spawning |
 | `--timeout` | no | `3600` | Kill the agent after N seconds. A killed agent is not a failure: its work is kept (see Notes) |
-| `--test-cmd <cmd>` | no | auto | Run in each worktree after the agent exits; non-zero exit rejects the ticket. Auto-detects `npm test`. Pass `""` to disable. Shares the agent's `--timeout`. Dependencies are already installed by `--install-cmd` |
+| `--test-cmd <cmd>` | no | auto | Run in each worktree after the agent exits; non-zero exit rejects the ticket. Defaults to `npm test` when `package.json` has a `test` script. When nothing is detected the run has no test gate and says so at startup. Pass `""` to run without a gate. Shares the agent's `--timeout`. Dependencies are already installed by `--install-cmd` |
 | `--install-cmd <cmd>` | no | auto | Run in each fresh worktree before the agent starts, and again after a merge-conflict rebase; non-zero exit fails the attempt (it is retried like any other failure). Auto-detects from the lockfile: `pnpm-lock.yaml` -> `pnpm install --prefer-offline --frozen-lockfile`, `package-lock.json` -> `npm ci --prefer-offline --no-audit --no-fund`, a `package.json` with no lockfile -> `npm install --prefer-offline --no-audit --no-fund --no-package-lock`, no `package.json` -> no install. Pass `""` to disable. Shares the agent's `--timeout`. Output goes to `<ticket>.install.log` |
-| `--max-turns <n>` | no | -- | Max agentic turns per ticket. Forwarded verbatim as `--max-turns <n>` to the provider CLI. Only `claude` accepts it; `codex` and `pi` reject it as an unknown option and the agent exits immediately. Applies to every agent spawn, including a re-spawn after a merge conflict. When omitted, `claude` applies no turn limit, so `--timeout` is the only cap. Reaching the limit is an error exit, so the ticket is recorded as failed |
+| `--max-turns <n>` | no | -- | Max agentic turns per agent run. Forwarded as `--max-turns <n>` to `claude` only; for `codex` and `pi` the flag is skipped with a warning and the agent runs with no turn limit. The limit is per spawn, not a total for the ticket: every retry and every re-spawn after a merge conflict starts with a fresh budget of `n` turns, so with `--retries 3` one ticket can use up to 4 x `n`. When omitted (or `0`), no limit is passed, so `--timeout` is the only cap. Takes precedence over the `[turns]` positional when both are given. Reaching the limit is an error exit, so the attempt fails and is retried like any other failure |
 | `--effort <level>` | no | -- | Starting effort/reasoning level. Each provider has its own ladder: `claude` supports `low`, `medium`, `high`, `xhigh`, `max` (forwarded as `--effort`); `codex` supports `low`, `medium`, `high` (forwarded as `-c model_reasoning_effort=<level>`); `pi` supports `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (forwarded as `--thinking`). Omitted = provider default. Each retry steps up from here (see `--retries`) |
+| `--prefer-subagent <model>` | no | -- | `claude` only. Sets `CLAUDE_CODE_SUBAGENT_MODEL=<model>` for every claude agent nightralph spawns (tickets, merge-conflict re-spawns, the reviewer and the fixer) and adds a prompt rule: hand read-only work (exploring the codebase, searching code, test runs with long output) to subagents, and make every edit and commit yourself. The reviewer gets the rule without the edit and commit line, since it never edits. `""` is the same as omitting the flag. For `codex` and `pi` it is skipped with one warning at startup (`--prefer-subagent not supported by <provider>, skipping`). `--dry-run` prints `Prefer subagent: <model>`, or `(none)`. See [`--prefer-subagent` option](#--prefer-subagent-option) |
 | `--retries <n>` | no | `3` | Extra attempts per ticket after a failed run. Each retry starts from a fresh worktree and raises the effort level one rung (see Notes). `0` disables retries |
 | `--retry-delay <n>` | no | `30` | Seconds to wait before the first retry; doubles each further retry (30s, 60s, 120s, ...). `0` disables the wait |
 | `--concurrency <n>` | no | `5` | Max agents running at once within a wave. A wave with more ready tickets than this runs them through a pool: as one agent exits, the next ticket starts. The wave still finishes fully before its branches are merged |
 
 
-**Notes**:
+### Notes
 
 * When `--spec <name>` is omitted, the CLI looks for
   `.scratch/<feature>/issues/` directories. If multiple features exist,
@@ -184,7 +205,8 @@ Flags:
   tickets start in the next wave.
 * An agent run only counts as a success when the agent exits 0,
   its worktree branch has new commits relative to the base branch,
-  and the test command (see `--test-cmd`) exits 0 in that worktree.
+  and the test command (see `--test-cmd`), when there is one, exits
+  0 in that worktree.
   Uncommitted changes left by the agent are auto-committed before
   the check. On success, the ticket's status is updated to `done`
   in-place. If the agent exits 0 but made no commits, or the test
@@ -209,6 +231,20 @@ Flags:
   logs are written to `<dir>/../logs/<ticket>.attempt<n>.log`
   (and `.attempt<n>.test.log` for the test command) so the first
   attempt's log is kept.
+* Each attempt at a ticket appends an entry to
+  `.scratch/<feature>/learnings.md`, next to `progress.md`. The
+  entry records what the orchestrator saw (the outcome, the agent's
+  exit code, the checklist items it reported, and the last lines of
+  the test or install log when one of those failed) and, when an
+  agent ran, the agent's own notes. The file is committed along with
+  `progress.md` and persists across runs. Each agent's prompt
+  includes the most
+  recent entries for its own ticket and the last successful entry of
+  each ticket that directly blocks it, so a retry can see why the
+  previous attempt failed. Agents keep their notes in
+  `.nightralph/notes.md` inside the worktree. nightralph collects
+  that file when the agent exits, and a self-ignoring
+  `.nightralph/.gitignore` keeps it out of the agent's commits.
 * A ticket that exhausts all its retry attempts is excluded from
   later waves in the same run. It stays `ready-for-agent` on disk
   so a future run can pick it up, but it will not be re-started
@@ -249,13 +285,95 @@ Flags:
     tool-use proposals so the agent runs non-interactively)
 
 
-#### `--spec <name>` option
+### `--spec <name>` option
 
 A feature name that resolves to `.scratch/<name>/`.
 The spec file is `.scratch/<name>/spec.md` and the issues directory
 is `.scratch/<name>/issues/`.
 
 
+### `--prefer-subagent` option
+
+Use this to use a strong model on the ticket while a cheaper, faster
+model handles the reading. The main agent writes the code and makes
+every commit. Subagents explore the codebase, search for code, and run
+tests whose output would flood the main agent's context, then report
+back a short answer.
+
+The flag does two things for every claude agent nightralph spawns
+(tickets, merge-conflict re-spawns, the reviewer and the fixer):
+
+1. It sets `CLAUDE_CODE_SUBAGENT_MODEL=<model>` in the agent's
+   environment.
+2. It adds a rule to the prompt: hand read-only work to subagents,
+   brief each one fully, do not delegate a lookup that takes a single
+   tool call, and never let a subagent edit files or commit. The
+   reviewer gets the same rule without the edit and commit line.
+
+`<model>` is anything Claude Code accepts as a model: an alias such as
+`sonnet` or `haiku`, or a full model ID. Sonnet is the safer choice
+when subagents need judgment, such as tracing a call path across
+modules. Haiku is cheaper and faster, and suits mechanical lookups and
+summarizing long test output, but it is more likely to miss something.
+
+```sh
+# Opus writes the code, Sonnet subagents explore and run tests
+npx nightralph claude -m claude-opus-4-6 --prefer-subagent sonnet
+
+# Cheaper subagents for searches and noisy test runs
+npx nightralph claude -m claude-opus-4-6 --prefer-subagent haiku
+
+# A Sonnet main agent with Haiku subagents
+npx nightralph claude -m claude-sonnet-4-6 --prefer-subagent haiku
+
+# Pin an exact model ID instead of an alias
+npx nightralph claude -m claude-opus-4-6 --prefer-subagent claude-sonnet-5-5
+
+# Check the setting and the prompt rule without running anything
+npx nightralph claude --prefer-subagent claude-haiku-5-5 --dry-run
+```
+
+Only the `claude` provider supports this flag. With `codex` or `pi` it
+is skipped with one warning at startup.
+
+`--prefer-subagent <model>` sets the model that a claude agent's
+subagents default to. It's a fallback, not a mandate. A model passed on
+an individual subagent call wins, and so does the `model` in a subagent
+definition. The built-in Explore subagent picks its own model.
+nightralph never sets `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, so without
+the flag a value you exported in your shell still applies.
+
+Subagent turns do not count toward `--max-turns`. That was observed on
+Claude Code 2.1.296 and is not documented by Anthropic, so it may
+change. Subagent time does count against `--timeout`, because the
+timeout covers the whole agent process.
+
+Spawned agents load your global `~/.claude` plugins and hooks. Those
+can spend turns and steer delegation their own way, and nightralph does
+not isolate agents from them.
+
+Subagent stats are recorded for every claude run, whether or not
+`--prefer-subagent` is set. When a claude agent ran, the attempt's
+entry in `learnings.md` includes `Subagents: <n>.` and `Cost: $<x>.`,
+each left out when the agent did not report it. The
+ticket's row in the status display shows the running total across its
+attempts, as in `a/03 - 2 subagents, $0.42`. After the finish summary,
+one line totals the subagents, agent runs and cost over every ticket
+attempt, merge-conflict re-spawn, the reviewer and the fixer:
+
+```
+Subagents: 5 started across 7 agent runs, cost $3.18 (cost from 6 of 7 runs)
+```
+
+The part in parentheses appears only when some runs reported no cost.
+A claude agent reports cost only when it finishes, so one killed at
+`--timeout` usually reports none. Codex and pi runs report nothing, so
+a run that used only them gets no stats line. Stats are advisory: they
+never change a ticket's outcome or the exit code.
+
+
+
+
 ## How It Works
 
 Tickets run in waves. A wave is a batch of tickets whose blockers are
@@ -287,6 +405,13 @@ completes, successful branches are merged back into the base branch.
 The first branch merges directly, and subsequent branches rebase
 onto the updated base before merging.
 
+Worktrees are created next to the repository, not inside it: a
+ticket's worktree is the sibling directory
+`<repo>.<feature>-<num>-<slug>` on the branch
+`<repo>--<feature>-<num>-<slug>`. A run that is interrupted leaves
+them in place; the next run removes a stale worktree and branch of
+the same name before creating a new one.
+
 A fresh worktree has only tracked files, so there is no
 `node_modules`. Before the agent starts, the orchestrator installs
 dependencies with the command that matches the project's lockfile
@@ -304,6 +429,33 @@ A file `progress.md` is written to the `.scratch/<feature>/` directory
 and committed after each ticket completes, so you can monitor the run from
 another terminal by reading the file.
 
+### Integration branch
+
+Launched from your default branch (`main`), nightralph does not merge
+into it. It creates `nightralph--<feature>` (or `nightralph--all` for
+several features), merges every ticket there, and leaves you on that
+branch. Running again from `main` resumes the same branch, so finished
+tickets stay finished. Launched from any other branch, it merges into
+that branch.
+
+After you merge the integration branch into `main`, the next run
+fast-forwards it to `main` and resumes. If the branch has commits `main`
+lacks, nightralph reports how far behind it is; merge `main` into it or
+delete it with `git branch -D`.
+
+If `.scratch/` is gitignored, the bookkeeping files (tickets, progress,
+learnings, review) are force-added and live on the integration branch, so
+they disappear from disk when you check out `main`.
+
+### Review
+
+After the last wave, an agent reviews everything merged since the last
+review and writes its findings to `.scratch/<feature>/review.md` (`.scratch/review.md`
+for a multi-feature run). A
+second agent fixes them test-first; its work merges only if the test
+command passes. Findings it could not fix stay unchecked in
+`review.md`. Skip this with `--no-review`.
+
 ### Status display
 
 In a terminal, nightralph shows a header line, one row per ticket, and
@@ -327,6 +479,9 @@ Each row starts with a dot that shows the ticket's state:
   run in this session. The row names the blocking tickets, as in
   `auth/03 (blocked by auth/01)`.
 
+A claude ticket's row can end with its subagent count and cost, as in
+`auth/02 - 2 subagents, $0.42` (see [`--prefer-subagent` option](#--prefer-subagent-option)).
+
 The header looks like this:
 
 ```
@@ -360,24 +515,31 @@ keep the machine awake, but the display can still go dark.
 #### Claude Opus 4.6
 
 ```sh
-caffeinate -i npx nightralph claude -m claude-opus-4-6 --effort low
+caffeinate -i npx nightralph claude -m claude-opus-4-6 --effort medium
 ```
 
 #### Claude Opus 5.5
 
 ```sh
-caffeinate -i npx nightralph claude -m claude-opus-5-5 --effort low
+caffeinate -i npx nightralph claude -m claude-opus-5-5 --effort medium
+```
+
+#### Claude Sonnet 5.5
+
+```sh
+caffeinate -i npx nightralph claude -m claude-sonnet-5-5 --effort medium
 ```
-#### Claude Sonnet 5
+
+#### Claude Haiku 5.5
 
 ```sh
-caffeinate -i npx nightralph claude -m claude-sonnet-5 --effort high
+caffeinate -i npx nightralph claude -m claude-haiku-5-5 --effort high
 ```
 
 #### Claude Fable 5.1
 
 ```sh
-caffeinate -i npx nightralph claude -m claude-fable-5-1 --effort low
+caffeinate -i npx nightralph claude -m claude-fable-5-1 --effort medium
 ```
 
 #### `pi` + OpenRouter model

package/dist/blockers.js

@@ -0,0 +1,149 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const FIELD_RE = /\*\*Blocked by:\*\*/i;
+const NEXT_FIELD_RE = /^\s*(?:[-*]\s+)?\*\*[^*\n]+:\*\*/;
+const HEADING_RE = /^\s*#{1,6}\s/;
+const CHECKLIST_RE = /^\s*[-*+]\s+\[[ xX]\]/;
+const TOKEN_RE = /[A-Za-z0-9_-]+/g;
+function endsField(line) {
+  return line.trim() === "" || NEXT_FIELD_RE.test(line) || HEADING_RE.test(line) || CHECKLIST_RE.test(line);
+}
+__name(endsField, "endsField");
+function fieldText(body) {
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((l) => FIELD_RE.test(l));
+  if (start === -1) return null;
+  const first = lines[start];
+  const m = FIELD_RE.exec(first);
+  const parts = [first.slice(m.index + m[0].length)];
+  for (const line of lines.slice(start + 1)) {
+    if (endsField(line)) break;
+    parts.push(line);
+  }
+  return parts.join("\n");
+}
+__name(fieldText, "fieldText");
+function stripNotes(text) {
+  const chars = [...text];
+  const drop = new Array(chars.length).fill(false);
+  const ticks = [];
+  chars.forEach((ch, i) => {
+    if (ch === "`") ticks.push(i);
+  });
+  for (let i = 0; i + 1 < ticks.length; i += 2) {
+    for (let j = ticks[i]; j <= ticks[i + 1]; j++) {
+      drop[j] = true;
+    }
+  }
+  const open = [];
+  chars.forEach((ch, i) => {
+    if (drop[i]) return;
+    if (ch === "(") {
+      open.push(i);
+    } else if (ch === ")" && open.length > 0) {
+      const from = open.pop();
+      for (let j = from; j <= i; j++) drop[j] = true;
+    }
+  });
+  return chars.map((ch, i) => drop[i] ? " " : ch).join("");
+}
+__name(stripNotes, "stripNotes");
+function looksLikeFeature(word) {
+  const segments = word.split("/");
+  return (segments.length > 1 || word.includes("-")) && /[a-z]/.test(word) && segments.every((s) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s));
+}
+__name(looksLikeFeature, "looksLikeFeature");
+function wordBefore(text, start) {
+  let i = start;
+  while (i > 0 && /\s/.test(text[i - 1])) i--;
+  if (i === start) return null;
+  const end = i;
+  while (i > 0 && /[A-Za-z0-9_/-]/.test(text[i - 1])) i--;
+  return i === end ? null : text.slice(i, end);
+}
+__name(wordBefore, "wordBefore");
+function parseBlockerField(body, knownFeatures) {
+  const text = fieldText(body);
+  if (text === null) return { refs: [], typos: [] };
+  const clean = stripNotes(text);
+  if (/^\s*none\b/i.test(clean)) return { refs: [], typos: [] };
+  const refs = [];
+  const typos = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = /* @__PURE__ */ __name((num, feature) => {
+    const id = `${feature ?? ""}:${num}`;
+    if (seen.has(id)) return;
+    seen.add(id);
+    refs.push(feature === void 0 ? { num } : { feature, num });
+  }, "add");
+  for (const m of clean.matchAll(TOKEN_RE)) {
+    const word = m[0];
+    if (/^\d+(?:-\d+)*$/.test(word)) {
+      const before = wordBefore(clean, m.index ?? 0);
+      let feature;
+      if (before !== null && knownFeatures.has(before)) {
+        feature = before;
+      } else if (before !== null && looksLikeFeature(before) && !typos.includes(before)) {
+        typos.push(before);
+      }
+      for (const n of word.split("-").map(Number)) add(n, feature);
+    }
+  }
+  return { refs, typos };
+}
+__name(parseBlockerField, "parseBlockerField");
+function refId(feature, num) {
+  return `${feature}:${num}`;
+}
+__name(refId, "refId");
+function resolveBlockers(raw, ownFeature, selected, lookup) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of raw) {
+    const feature = r.feature ?? ownFeature;
+    const id = refId(feature, r.num);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const nums = selected.get(feature);
+    if (nums) {
+      out.push({
+        feature,
+        num: r.num,
+        where: nums.has(r.num) ? "run" : "missing"
+      });
+      continue;
+    }
+    const status = lookup(feature, r.num);
+    if (status === void 0) {
+      out.push({ feature, num: r.num, where: "missing" });
+    } else {
+      out.push({
+        feature,
+        num: r.num,
+        where: status === "done" ? "done" : "pending",
+        status
+      });
+    }
+  }
+  return out;
+}
+__name(resolveBlockers, "resolveBlockers");
+function provisionalRefs(raw, ownFeature) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of raw) {
+    const feature = r.feature ?? ownFeature;
+    const id = refId(feature, r.num);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ feature, num: r.num, where: "run" });
+  }
+  return out;
+}
+__name(provisionalRefs, "provisionalRefs");
+export {
+  parseBlockerField,
+  provisionalRefs,
+  resolveBlockers
+};
+//# sourceMappingURL=blockers.js.map

package/dist/blockers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/blockers.ts"],
+  "sourcesContent": ["// Blocker references in a ticket's **Blocked by:** field. Pure:\n// no file or process access and no imports, so orchestrator.ts\n// and resolve.ts can both depend on it.\n\nexport type RawRef = {\n    feature?:string;  // absent -> the ticket's own feature\n    num:number;\n}\n\nexport type BlockerParse = {\n    refs:RawRef[];\n    typos:string[];   // feature-shaped words that name no feature\n}\n\nconst FIELD_RE = /\\*\\*Blocked by:\\*\\*/i\nconst NEXT_FIELD_RE = /^\\s*(?:[-*]\\s+)?\\*\\*[^*\\n]+:\\*\\*/\nconst HEADING_RE = /^\\s*#{1,6}\\s/\nconst CHECKLIST_RE = /^\\s*[-*+]\\s+\\[[ xX]\\]/\nconst TOKEN_RE = /[A-Za-z0-9_-]+/g\n\nfunction endsField (line:string):boolean {\n    return line.trim() === '' ||\n        NEXT_FIELD_RE.test(line) ||\n        HEADING_RE.test(line) ||\n        CHECKLIST_RE.test(line)\n}\n\n/**\n * The text of the **Blocked by:** field: the rest of its line\n * plus continuation lines, up to a blank line, the next\n * `**Field:**` line, a heading or a checklist item. `null` when\n * the body has no such field.\n */\nfunction fieldText (body:string):string|null {\n    const lines = body.split(/\\r?\\n/)\n    const start = lines.findIndex(l => FIELD_RE.test(l))\n    if (start === -1) return null\n    const first = lines[start]\n    const m = FIELD_RE.exec(first)!\n    const parts = [first.slice(m.index + m[0].length)]\n    for (const line of lines.slice(start + 1)) {\n        if (endsField(line)) break\n        parts.push(line)\n    }\n    return parts.join('\\n')\n}\n\n/**\n * Blanks out backtick spans and `(...)` spans (nested, across\n * lines). Only paired delimiters count; an unpaired `(` or\n * backtick stays as text. Each blanked character becomes a space,\n * so the words on either side never merge.\n */\nfunction stripNotes (text:string):string {\n    const chars = [...text]\n    const drop = new Array<boolean>(chars.length).fill(false)\n    const ticks:number[] = []\n    chars.forEach((ch, i) => {\n        if (ch === '`') ticks.push(i)\n    })\n    for (let i = 0; i + 1 < ticks.length; i += 2) {\n        for (let j = ticks[i]; j <= ticks[i + 1]; j++) {\n            drop[j] = true\n        }\n    }\n    const open:number[] = []\n    chars.forEach((ch, i) => {\n        if (drop[i]) return\n        if (ch === '(') {\n            open.push(i)\n        } else if (ch === ')' && open.length > 0) {\n            const from = open.pop()!\n            for (let j = from; j <= i; j++) drop[j] = true\n        }\n    })\n    return chars.map((ch, i) => (drop[i] ? ' ' : ch)).join('')\n}\n\n/**\n * A word shaped like a feature dir name: lowercase letters and\n * digits joined by hyphens, or a nested path of such segments\n * joined by `/`, with at least one letter. Doc IDs such as\n * `FDR-018` are not.\n */\nfunction looksLikeFeature (word:string):boolean {\n    const segments = word.split('/')\n    return (segments.length > 1 || word.includes('-')) &&\n        /[a-z]/.test(word) &&\n        segments.every(s => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s))\n}\n\n/**\n * The word that ends right before `start`, separated from it by\n * whitespace only. A word may contain `/`, so a nested feature such\n * as `rollout/billing` is one word. `null` when the gap is empty or\n * holds anything but whitespace.\n */\nfunction wordBefore (text:string, start:number):string|null {\n    let i = start\n    while (i > 0 && /\\s/.test(text[i - 1])) i--\n    if (i === start) return null\n    const end = i\n    while (i > 0 && /[A-Za-z0-9_/-]/.test(text[i - 1])) i--\n    return i === end ? null : text.slice(i, end)\n}\n\n/**\n * Reads the **Blocked by:** field of a ticket body. A number\n * belongs to the feature named by the word directly before it\n * when that word is in `knownFeatures` (the names of\n * `.scratch/<name>/issues` dirs, `<name>` possibly nested, as in\n * `rollout/billing`); otherwise to the ticket's own feature.\n * Feature-shaped words that name no feature are returned as\n * `typos`.\n */\nexport function parseBlockerField (\n    body:string,\n    knownFeatures:ReadonlySet<string>\n):BlockerParse {\n    const text = fieldText(body)\n    if (text === null) return { refs:[], typos:[] }\n    const clean = stripNotes(text)\n    if (/^\\s*none\\b/i.test(clean)) return { refs:[], typos:[] }\n\n    const refs:RawRef[] = []\n    const typos:string[] = []\n    const seen = new Set<string>()\n    const add = (num:number, feature?:string) => {\n        const id = `${feature ?? ''}:${num}`\n        if (seen.has(id)) return\n        seen.add(id)\n        refs.push(feature === undefined ? { num } : { feature, num })\n    }\n    for (const m of clean.matchAll(TOKEN_RE)) {\n        const word = m[0]\n        if (/^\\d+(?:-\\d+)*$/.test(word)) {\n            const before = wordBefore(clean, m.index ?? 0)\n            let feature:string|undefined\n            if (before !== null && knownFeatures.has(before)) {\n                feature = before\n            } else if (\n                before !== null &&\n                looksLikeFeature(before) &&\n                !typos.includes(before)\n            ) {\n                typos.push(before)\n            }\n            // both ends of a range belong to the same feature\n            for (const n of word.split('-').map(Number)) add(n, feature)\n        }\n    }\n    return { refs, typos }\n}\n\nexport type BlockerWhere = 'run'|'done'|'pending'|'missing'\n\nexport type BlockerRef = {\n    feature:string;\n    num:number;\n    // 'run'     -> a ticket in this run; its live status decides\n    // 'done'    -> outside the run, done when loaded\n    // 'pending' -> outside the run, not done (dead this session)\n    // 'missing' -> no ticket matches (dead, reported)\n    where:BlockerWhere;\n    status?:string;   // the outside ticket's status, for messages\n}\n\n// Same text as ticketKey in orchestrator.ts, which this module\n// must not import.\nfunction refId (feature:string, num:number):string {\n    return `${feature}:${num}`\n}\n\n/**\n * Classifies raw refs. `selected` maps each feature in the run to\n * its ticket numbers; `lookup` returns the status of a ticket in a\n * feature outside the run, or undefined when there is none.\n * De-duplicates by (feature, num) after the own feature is filled\n * in.\n */\nexport function resolveBlockers (\n    raw:ReadonlyArray<RawRef>,\n    ownFeature:string,\n    selected:ReadonlyMap<string, ReadonlySet<number>>,\n    lookup:(feature:string, num:number) => string|undefined\n):BlockerRef[] {\n    const out:BlockerRef[] = []\n    const seen = new Set<string>()\n    for (const r of raw) {\n        const feature = r.feature ?? ownFeature\n        const id = refId(feature, r.num)\n        if (seen.has(id)) continue\n        seen.add(id)\n        const nums = selected.get(feature)\n        if (nums) {\n            out.push({\n                feature,\n                num:r.num,\n                where:nums.has(r.num) ? 'run' : 'missing',\n            })\n            continue\n        }\n        const status = lookup(feature, r.num)\n        if (status === undefined) {\n            out.push({ feature, num:r.num, where:'missing' })\n        } else {\n            out.push({\n                feature,\n                num:r.num,\n                where:status === 'done' ? 'done' : 'pending',\n                status,\n            })\n        }\n    }\n    return out\n}\n\n/**\n * Refs for a bare scan, before the run is known: every ref is\n * `run`, so one that matches no ticket in the list is never\n * satisfied.\n */\nexport function provisionalRefs (\n    raw:ReadonlyArray<RawRef>,\n    ownFeature:string\n):BlockerRef[] {\n    const out:BlockerRef[] = []\n    const seen = new Set<string>()\n    for (const r of raw) {\n        const feature = r.feature ?? ownFeature\n        const id = refId(feature, r.num)\n        if (seen.has(id)) continue\n        seen.add(id)\n        out.push({ feature, num:r.num, where:'run' })\n    }\n    return out\n}\n\nexport type BlockerWarning = {\n    ticket:string;    // ticketLabel of the ticket with the problem\n    kind:'missing'|'typo';\n    text:string;      // the ref label or the unknown word\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/display.js

@@ -1,5 +1,6 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+import { formatStats } from "./stats.js";
 const ESC = "\x1B[";
 const ansi = {
   cursorUp(n) {
@@ -60,10 +61,9 @@ const MAX_MESSAGE_BUFFER = 200;
 const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g;
 function rowText(ticket) {
   const label = ticketLabel(ticket);
-  if (ticket.status !== "blocked" || !ticket.blockedBy?.length) {
-    return label;
-  }
-  return `${label} (blocked by ${ticket.blockedBy.join(", ")})`;
+  const base = ticket.status === "blocked" && ticket.blockedBy?.length ? `${label} (blocked by ${ticket.blockedBy.join(", ")})` : label;
+  const suffix = formatStats(ticket.stats);
+  return suffix === null ? base : `${base} - ${suffix}`;
 }
 __name(rowText, "rowText");
 function fitLine(line, width) {
@@ -192,6 +192,12 @@ class StatusDisplay {
     ticket.blockedBy = [...blockedBy];
     this.render();
   }
+  setTicketStats(num, feature, stats) {
+    const ticket = this.findTicket(num, feature);
+    if (!ticket) return;
+    ticket.stats = { ...stats };
+    this.render();
+  }
   log(message) {
     if (!this.wave) {
       this.config.stream.write(message + "\n");
@@ -330,6 +336,8 @@ Wave ${waveNum}${pct}: ` + tickets.map((t) => ticketLabel(t)).join(", ")
   }
   setBlocked(_num, _feature, _blockedBy) {
   }
+  setTicketStats(_num, _feature, _stats) {
+  }
   log(message) {
     console.log(message);
   }