cohorte 1.4.0 → 1.5.0

package/dashboard/server/doctor.js

@@ -12,7 +12,10 @@ const { versions } = require('./versions');
 // Rendered surface agents live alongside these fixed (non-surface) agents; exclude them
 // from the orphan check so they're never mistaken for a stray surface agent.
 const FIXED_AGENTS = new Set([
-  'review', 'release', 'smoke', 'profile-reader',
+  'review', 'release', 'profile-reader',
+  // retired (1.5.0) — still excluded so a stale install's leftover file isn't
+  // reported as a stray surface agent.
+  'smoke',
   'implementer.template',
 ]);
 
@@ -126,7 +129,7 @@ function checkGate(profile, projectRoot) {
   const wantPf = gate.preflight || {};
   const havePf = (cfg.preflight && typeof cfg.preflight === 'object') ? cfg.preflight : {};
   if (!!wantPf.enabled !== !!havePf.enabled
-      || !sameSet(wantPf.agents || ['review', 'smoke'], havePf.agents || ['review', 'smoke'])
+      || !sameSet(wantPf.agents || ['review'], havePf.agents || ['review'])
       || Number(wantPf.max_age_minutes || 30) !== Number(havePf.max_age_minutes || 30)) {
     drifted.push('preflight');
   }

package/dashboard/server/index.js

@@ -11,6 +11,7 @@ const { versions } = require('./versions');
 const { state } = require('./doctor');
 const { kanban } = require('./kanban');
 const { metrics } = require('./metrics');
+const { usage } = require('./usage');
 const fleet = require('./fleet');
 
 const MIME = {
@@ -321,6 +322,12 @@ function start({ projectRoot, globalDir, port, host, openBrowser, pkgRoot, versi
         const root = q ? path.resolve(q) : projectRoot;
         return sendJson(res, 200, metrics({ projectRoot: root }));
       }
+      if (url === '/api/usage') {
+        const q = new URL(req.url, 'http://localhost');
+        const root = q.searchParams.get('project') ? path.resolve(q.searchParams.get('project')) : projectRoot;
+        const days = Number(q.searchParams.get('days')) || null;
+        return sendJson(res, 200, usage({ projectRoot: root, days }));
+      }
       if (url === '/api/projects') {
         const body = await readBody(req);
         if (req.method === 'POST') {

package/dashboard/server/metrics.js

@@ -1,6 +1,6 @@
 'use strict';
 // Read a project's `.claude/pipeline-metrics.jsonl` (one line per phase batch, appended by
-// /build, /review, /fix and /smoke) and aggregate it per feature: wall-clock per phase, fix
+// /build, /review and /fix) and aggregate it per feature: wall-clock per phase, fix
 // rounds, and per-surface results. Dependency-free; a missing file is simply "no data yet".
 //
 // Two line formats coexist in the file:
@@ -11,9 +11,9 @@
 const fs = require('fs');
 const path = require('path');
 
-// `cycle` is a RETIRED phase, kept so metrics files written before its removal still render.
-// Without it in this list its per-surface results parse fine but land in no column — the
-// surface table showed rows with every cell empty.
+// `smoke` and `cycle` are RETIRED phases, kept so metrics files written before their removal
+// still render. Without them in this list their per-surface results parse fine but land in no
+// column — the surface table showed rows with every cell empty.
 const PHASES = ['build', 'review', 'fix', 'smoke', 'cycle'];
 
 // Parse the raw JSONL into normalized batches ({ts, feature, phase, seconds, surfaces}),

package/dashboard/server/usage.js

@@ -0,0 +1,61 @@
+'use strict';
+// Serve the metrics collector's rollup (scripts/metrics/collect.mjs) to the dashboard:
+// real cost and runtime per command, read from Claude Code's own transcripts.
+//
+// This is the SECOND metrics source in the cockpit, and the two answer different questions.
+// `metrics.js` reads `.claude/pipeline-metrics.jsonl` — written by the model itself, so it
+// carries per-surface verdicts (ok / REVISE:2 / error) that only the model knows, but it
+// misses any run that ended early and can never report tokens. This one is derived from the
+// transcripts, so it is complete and exact on cost and time but knows nothing about verdicts.
+// Verdicts from one, money from the other; neither is a replacement for the other.
+//
+// The collector is ESM and this server is CommonJS, so it runs as a child process — the same
+// bridge `bin/cli.js` uses. A spawn is ~1-2s on a large history, which is why the result is
+// cached: the panel polls, and re-parsing tens of MB of transcripts on every poll would make
+// the whole cockpit feel broken.
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const COLLECT = path.join(__dirname, '..', '..', 'scripts', 'metrics', 'collect.mjs');
+
+// Transcripts only grow, and nobody needs sub-minute freshness on a spend figure.
+const CACHE_MS = 60_000;
+const cache = new Map(); // projectRoot → { at, value }
+
+function usage({ projectRoot, days = null, force = false }) {
+  const key = `${projectRoot}|${days || ''}`;
+  const hit = cache.get(key);
+  if (!force && hit && Date.now() - hit.at < CACHE_MS) return hit.value;
+
+  const args = [COLLECT, projectRoot, '--json'];
+  if (days) args.push(`--days=${days}`);
+
+  let value;
+  try {
+    const r = spawnSync(process.execPath, args, {
+      encoding: 'utf8',
+      // A pathological history must not wedge the cockpit's event loop forever.
+      timeout: 60_000,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.status !== 0 || !r.stdout) {
+      value = { present: false, error: (r.stderr || '').trim().split('\n').slice(-1)[0] || 'collector failed' };
+    } else {
+      const parsed = JSON.parse(r.stdout);
+      // No transcripts for this project is a normal state (a fresh checkout, or a project
+      // driven from another machine), not an error — say so rather than rendering zeros
+      // that look like "this pipeline is free".
+      value = parsed.totals && parsed.totals.sessions
+        ? { present: true, ...parsed }
+        : { present: false, error: 'no Claude Code transcripts found for this project' };
+    }
+  } catch (e) {
+    value = { present: false, error: String((e && e.message) || e) };
+  }
+
+  cache.set(key, { at: Date.now(), value });
+  return value;
+}
+
+module.exports = { usage };

package/install.ps1

@@ -151,6 +151,7 @@ try {
         Copy-Item (Join-Path $src 'scripts\kanban-move.sh')       (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'scripts\telemetry-send.sh')    (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'scripts\preflight.sh')         (Join-Path $dest 'pipeline\scripts') -Force
+        Copy-Item (Join-Path $src 'scripts\loop.sh')              (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'core\agents\implementer.template.md') (Join-Path $dest 'pipeline') -Force
         if (Test-Path (Join-Path $src 'CHANGELOG.md')) { Copy-Item (Join-Path $src 'CHANGELOG.md') (Join-Path $dest 'pipeline') -Force }
         [System.IO.File]::WriteAllText((Join-Path $dest 'pipeline\VERSION'), "$ver`n", [System.Text.UTF8Encoding]::new($false))
@@ -188,8 +189,10 @@ try {
         New-Item -ItemType Directory -Force -Path (Join-Path $dest 'agents') | Out-Null
         Copy-Item (Join-Path $src 'core\agents\review.md'),
                   (Join-Path $src 'core\agents\release.md'),
-                  (Join-Path $src 'core\agents\smoke.md'),
                   (Join-Path $src 'core\agents\profile-reader.md') (Join-Path $dest 'agents') -Force
+        # 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent.
+        Remove-Item -LiteralPath (Join-Path $dest 'agents\smoke.md') -Force -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath (Join-Path $dest 'commands\smoke.md') -Force -ErrorAction SilentlyContinue
         # 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
         # copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
         Remove-Item -LiteralPath (Join-Path $dest 'agents\questionnaire-researcher.md') -Force -ErrorAction SilentlyContinue

package/install.sh

@@ -107,8 +107,9 @@ copy_core() {
   cp "$src/scripts/kanban-move.sh"       "$dest/pipeline/scripts/"
   cp "$src/scripts/telemetry-send.sh"    "$dest/pipeline/scripts/"
   cp "$src/scripts/preflight.sh"         "$dest/pipeline/scripts/"
+  cp "$src/scripts/loop.sh"              "$dest/pipeline/scripts/"
   chmod +x "$dest/pipeline/scripts/kanban-move.sh" "$dest/pipeline/scripts/telemetry-send.sh" \
-           "$dest/pipeline/scripts/preflight.sh" 2>/dev/null || true
+           "$dest/pipeline/scripts/preflight.sh" "$dest/pipeline/scripts/loop.sh" 2>/dev/null || true
   cp "$src/core/agents/implementer.template.md" "$dest/pipeline/"
   [ -f "$src/CHANGELOG.md" ] && cp "$src/CHANGELOG.md" "$dest/pipeline/"
   printf '%s\n' "$ver" > "$dest/pipeline/VERSION"
@@ -149,8 +150,10 @@ PY
 copy_fixed_agents() {
   mkdir -p "$dest/agents"
   cp "$src/core/agents/review.md" "$src/core/agents/release.md" \
-     "$src/core/agents/smoke.md" "$src/core/agents/profile-reader.md" \
+     "$src/core/agents/profile-reader.md" \
      "$dest/agents/"
+  # 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent.
+  rm -f "$dest/agents/smoke.md" "$dest/commands/smoke.md"
   # 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
   # copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
   rm -f "$dest/agents/questionnaire-researcher.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/profile/PIPELINE.template.md

@@ -106,7 +106,7 @@ commands:
   format: pnpm format
   typecheck: pnpm check-types
   test: pnpm test
-  test_quiet: pnpm test --reporter=dot       # bridled variant — what /review·/smoke preflight runs
+  test_quiet: pnpm test --reporter=dot       # bridled variant — what the /review preflight runs
   # migration commands — omit / leave "" if the project has no DB migrations
   migrate: "cd apps/api && node ace migration:run"
   make_migration: "cd apps/api && node ace make:migration"
@@ -164,12 +164,12 @@ gate:
     - "git rebase"
     - "git reset"
     - "docker compose"
-  # Phase gate: review/smoke dispatches require a fresh `.claude/preflight.ok` stamp,
+  # Phase gate: review dispatches require a fresh `.claude/preflight.ok` stamp,
   # written by pipeline/scripts/preflight.sh when typecheck+lint+tests are green —
   # gate.py "ask"s the dispatch when the stamp is missing, stale, or HEAD moved.
   preflight:
     enabled: true
-    agents: [review, smoke]                   # subagent_types the stamp gates
+    agents: [review]                          # subagent_types the stamp gates
     max_age_minutes: 30
 
 ```

package/profile/SCHEMA.md

@@ -34,7 +34,7 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `contract.path` `.ext` `.index`      | string       | build                             | Where `<feature_id>` contract is authored + barrel.           |
 | `contract.authored_by`               | const `lead` | build                             | Implementers import it read-only, never edit.                 |
 | `commands.*`                         | string       | all                               | Repo-wide install/dev/lint/format/typecheck/test + migrate.   |
-| `commands.test_quiet` `.lint_quiet`  | string       | review, smoke, audit, workflows   | Repo-wide bridled variants — what the `/review`·`/smoke` pre-flight runs. Same fallback as the per-surface ones. |
+| `commands.test_quiet` `.lint_quiet`  | string       | review, audit, workflows          | Repo-wide bridled variants — what the `/review` pre-flight runs. Same fallback as the per-surface ones. |
 | `rbac.enabled`                       | bool         | brainstorm, review                | Toggle RBAC personas + authz audit.                           |
 | `rbac.hierarchy`                     | list         | review                            | Highest→lowest role list.                                     |
 | `design.enabled`                     | bool         | build, frontend, align-ds         | `false` ⇒ design steps are no-ops.                            |
@@ -52,8 +52,8 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `gate.ask[]`                         | list         | hooks/gate.py, settings           | Command substrings that require confirm, on any branch.       |
 | `gate.ask_on_default_branch[]`       | list         | hooks/gate.py                     | Confirm ONLY on `default_branch`; free on feature branches.   |
 | `gate.default_branch`                | string       | hooks/gate.py                     | Protected branch (default `main`); gate resolves via git.     |
-| `gate.preflight.enabled`             | bool         | hooks/gate.py, review, smoke      | Phase gate: review/smoke dispatches need a fresh preflight stamp. See §Preflight. |
-| `gate.preflight.agents[]`            | list         | hooks/gate.py                     | `subagent_type`s the stamp gates (default `[review, smoke]`). |
+| `gate.preflight.enabled`             | bool         | hooks/gate.py, review             | Phase gate: review dispatches need a fresh preflight stamp. See §Preflight. |
+| `gate.preflight.agents[]`            | list         | hooks/gate.py                     | `subagent_type`s the stamp gates (default `[review]`).        |
 | `gate.preflight.max_age_minutes`     | number       | hooks/gate.py                     | Stamp freshness window (default 30).                          |
 
 ## Prose sections
@@ -161,8 +161,8 @@ the frozen contract as the only cross-surface channel**. So specialization means
 Coarse first, specialize on evidence: start with one `frontend` / `backend` surface each; split only a
 surface that's proven slow and cleanly separable. The evidence lives in
 the **main checkout's** `.claude/pipeline-metrics.jsonl` (gitignored) — one JSONL line per phase batch
-(`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/build`, `/review`, `/fix`
-and `/smoke`.
+(`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/build`, `/review`
+and `/fix`.
 **`surfaces` keys are surface keys, nothing else** — run-level facts go in their own top-level
 fields. Anything put inside `surfaces` is read
 as a surface: the dashboard renders it as a row in the per-surface table and scores a non-`ok`
@@ -188,7 +188,7 @@ to log it. For what's EXPENSIVE, use Claude Code's own accounting:
   per-subagent attribution needs traces (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, beta).
 
 **Lead context discipline — the silent bill.** The lead session's conversation history is re-sent as
-input on EVERY turn; a session that spans spec→build→smoke→review→fix without clearing re-pays the
+input on EVERY turn; a session that spans spec→build→review→fix without clearing re-pays the
 accumulated spec walk-through, handoffs, and reports on each turn. The pipeline is built so this is
 never necessary: every phase handoff (spec, contract, diff, staged reports) lives on disk, so `/clear`
 at each phase boundary is always safe — each command's closing line recommends it. Corollaries the
@@ -219,7 +219,7 @@ storing a bare `pnpm test` as the thing agents execute; `/update-pipeline` tops
 
 ## Preflight — the deterministic phase gate
 
-`/review` and `/smoke` start by running `pipeline/scripts/preflight.sh` — a plain shell script (no
+`/review` starts by running `pipeline/scripts/preflight.sh` — a plain shell script (no
 agent) that executes the profile's mechanical checks in order (typecheck → lint → tests, quiet
 variants) with all output redirected to `specs/reports/<id>.preflight.txt`:
 
@@ -231,7 +231,7 @@ variants) with all output redirected to `specs/reports/<id>.preflight.txt`:
 
 `hooks/gate.py` enforces the stamp as a **phase gate** (the `preflight` block of `gate-config.json`,
 generated from `gate.preflight`): a Task dispatch of a listed `subagent_type` (default
-`review`/`smoke`) with a missing/stale stamp — older than `max_age_minutes`, or HEAD moved — gets an
+`review`) with a missing/stale stamp — older than `max_age_minutes`, or HEAD moved — gets an
 "ask", so a lead can't accidentally skip the gate but a human can consciously override it. The gate
 hook fires for **every** agent in the session, including subagents spawned by the Workflow runtime
 (they run in `acceptEdits` whatever the session mode — Write/Edit auto-approved — but Bash and Task
@@ -409,7 +409,7 @@ card created in the target column if missing.
 | `/spec` opens (draft)                   | `spec`          |
 | `/spec` freezes (`status: frozen`)      | `ready`         |
 | `/build`                                | `building`      |
-| `/review` (owns the move — `/smoke` never moves the card) | `review`        |
+| `/review`                               | `review`        |
 | `/fix`                                  | `fix`           |
 | `/ship` starts                          | `ship`          |
 | PR opened (`status: shipped`)           | `shipped` (+ `PR #<num>` on the card) |
@@ -437,7 +437,7 @@ pre-telemetry installs) ask ONE question, once per machine, default **No**, and
 `|| true`, so a **missing** script is equally silent: `/doctor` check 1 verifies `pipeline/scripts/`
 is fully populated.
 
-**Which commands ping** — the seven that make up the feature funnel, and only those. The point is to
+**Which commands ping** — the six that make up the feature funnel, and only those. The point is to
 see where features stall, so every stage of `idea → PR` reports and nothing else does:
 
 | phase | fired when | `seconds` | `results` |
@@ -445,7 +445,6 @@ see where features stall, so every stage of `idea → PR` reports and nothing el
 | `brainstorm` | the return is staged | `0` | — |
 | `spec` | a freeze lands (Mode A only) | `0` | `frozen` |
 | `build` | after the batch metrics line | wall-clock | `ok,ok` / `error` |
-| `smoke` | after the verdict | wall-clock | `PASS` / `FAIL:<n>` |
 | `review` | after the merged verdict | wall-clock | `<verdict>:<count>` |
 | `fix` | after the batch metrics line | wall-clock | `<fixed>/<found>` |
 | `ship` | the release agent succeeded | `0` | `pr` / `compare` |

package/scripts/loop.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+#
+# loop.sh — autonomous /build → /review → /fix → /review … loop for ONE feature.
+#
+#   loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+#
+# THE POINT: every phase runs as a SEPARATE `claude -p` child with its own fresh
+# context. The session that typed /loop never sees the diff, the N review reports
+# or the N contracts — it reads only this script's one-line-per-phase stdout and,
+# at the end, the verdict JSON. Running the loop inside the calling session would
+# accumulate all of it in a history that is re-sent at input price on every turn,
+# which is the exact cost the pipeline's /clear discipline exists to avoid.
+#
+# Contract with the pipeline: /review writes specs/reports/<id>.verdict.json on
+# every run. That file — `blocking` and `fingerprint` — is the ONLY channel
+# between cohorte and this driver. No prose is parsed.
+#
+# Exit codes (three distinct diagnostics, do not collapse them):
+#   0   clean — a review returned blocking == 0
+#   1   ceiling — --max passes used, still blocking (the fix was progressing;
+#       re-run with a higher --max)
+#   2   no usable verdict — /review produced nothing, or aborted on a red
+#       preflight (typecheck/lint/tests broken; the message says which)
+#   3   non-convergent — two consecutive reviews returned the SAME blocking
+#       fingerprint: the fix is treading water, a higher --max will not help
+#   64  usage — bad flag, bad id, missing spec, no `claude` on PATH
+#
+# No /fix runs on the last pass: fixing without a review behind it ships
+# unaudited code. Each fix pass is committed — that commit is the only way back
+# after N autonomous passes.
+
+set -uo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+usage: loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+
+  --max=N      stop after N review passes (default 5)
+  --no-build   never build — re-run the /review ⇄ /fix loop on a feature that
+               is already built (the common case; the build stamp is ignored)
+  --rebuild    force a /build even if the stamp says it was already built
+
+  env CLAUDE_FLAGS   flags for every child session
+                     (default: --permission-mode acceptEdits)
+EOF
+  exit 64
+}
+
+id=""
+max=5
+build_mode="auto"          # auto | never | force
+
+for arg in "$@"; do
+  case "$arg" in
+    --max=*)
+      max="${arg#--max=}"
+      case "$max" in
+        ''|*[!0-9]*) echo "loop: --max must be a positive integer (got '${arg#--max=}')" >&2; exit 64 ;;
+      esac
+      [ "$max" -ge 1 ] || { echo "loop: --max must be >= 1" >&2; exit 64; }
+      ;;
+    --no-build) build_mode="never" ;;
+    --rebuild)  build_mode="force" ;;
+    -h|--help)  usage ;;
+    -*)         echo "loop: unknown flag: $arg" >&2; usage ;;
+    *)
+      [ -z "$id" ] || { echo "loop: unexpected argument: $arg" >&2; usage; }
+      id="$arg"
+      ;;
+  esac
+done
+
+[ -n "$id" ] || usage
+# --no-build --rebuild together is a contradiction, not a precedence puzzle.
+case " $* " in
+  *" --no-build "*) case " $* " in *" --rebuild "*)
+    echo "loop: --no-build and --rebuild are mutually exclusive" >&2; exit 64 ;; esac ;;
+esac
+
+command -v claude >/dev/null 2>&1 || {
+  echo "loop: no 'claude' on PATH — the loop drives child claude -p sessions" >&2
+  exit 64
+}
+
+root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "loop: not inside a git checkout" >&2; exit 64; }
+cd "$root" || exit 64
+
+spec="specs/$id.md"
+[ -f "$spec" ] || {
+  echo "loop: no spec at $spec — run /spec $id first" >&2; exit 64; }
+
+reports="specs/reports"
+mkdir -p "$reports"
+verdict="$reports/$id.verdict.json"
+stamp="$reports/$id.built"
+log="$reports/$id.loop.log"
+
+: "${CLAUDE_FLAGS:=--permission-mode acceptEdits}"
+
+: >"$log"
+{
+  printf '# loop %s — max=%s build=%s\n' "$id" "$max" "$build_mode"
+  printf '# flags: %s\n' "$CLAUDE_FLAGS"
+} >>"$log"
+
+# --- one phase = one throwaway child session ---------------------------------
+# ALL child output is redirected into $log and never surfaces here: if the
+# parent re-imports the children's transcripts, the whole point is lost.
+# $CLAUDE_FLAGS is intentionally unquoted — it is a flag list, not one word.
+run_phase() {
+  cmd="$1"
+  printf '▶ /%-6s %-24s ' "$cmd" "$id"
+  printf '\n\n===== /%s %s =====\n' "$cmd" "$id" >>"$log"
+  # shellcheck disable=SC2086
+  if claude -p "/$cmd $id" $CLAUDE_FLAGS >>"$log" 2>&1; then
+    echo "ok"
+    return 0
+  fi
+  echo "fail"
+  return 1
+}
+
+# Scalar reads on a flat JSON object — no jq dependency (the pipeline ships no
+# runtime deps). Only `blocking` and `fingerprint` are ever read; both are
+# top-level scalars by construction of the verdict contract.
+json_num() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$1" | head -n1; }
+json_str() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" | head -n1; }
+
+finish() { echo "$2"; exit "$1"; }
+
+# --- build -------------------------------------------------------------------
+# The stamp is the driver's own bookkeeping — /build knows nothing about it.
+case "$build_mode" in
+  force) do_build=1 ;;
+  never) do_build=0 ;;
+  auto)  [ -f "$stamp" ] && do_build=0 || do_build=1 ;;
+esac
+
+if [ "$do_build" -eq 1 ]; then
+  run_phase build || finish 2 "✗ /build failed — see $log"
+  date -u +%Y-%m-%dT%H:%M:%SZ >"$stamp"
+fi
+
+# --- review ⇄ fix ------------------------------------------------------------
+prev_fp=""
+pass=1
+while [ "$pass" -le "$max" ]; do
+  # Delete first: a stale verdict from the previous pass read as this pass's
+  # answer would end the loop on someone else's numbers.
+  rm -f "$verdict"
+  run_phase review || true          # exit status of the child is not the verdict
+
+  [ -f "$verdict" ] || finish 2 \
+    "✗ /review wrote no verdict (pass $pass) — see $log"
+
+  if grep -q '"aborted"' "$verdict"; then
+    finish 2 "✗ /review aborted on a red preflight — typecheck/lint/tests are broken, see $reports/$id.preflight.txt"
+  fi
+
+  blocking="$(json_num "$verdict" blocking)"
+  [ -n "$blocking" ] || finish 2 \
+    "✗ verdict has no usable 'blocking' count (pass $pass) — see $verdict"
+
+  [ "$blocking" -eq 0 ] && finish 0 \
+    "✓ clean after $pass review pass(es) — no blocking findings"
+
+  fp="$(json_str "$verdict" fingerprint)"
+  if [ -n "$fp" ] && [ "$fp" = "$prev_fp" ]; then
+    finish 3 "✗ non-convergent — the same $blocking blocking finding(s) survived a fix pass; see $verdict"
+  fi
+  prev_fp="$fp"
+
+  # Last pass: report and stop. A /fix here would leave unreviewed code behind.
+  [ "$pass" -eq "$max" ] && finish 1 \
+    "✗ ceiling — $blocking blocking finding(s) after $max pass(es); re-run with a higher --max"
+
+  run_phase fix || true
+
+  # Non-fatal by design: nothing to commit is a legitimate outcome (an agent
+  # that decided a finding needed no code change). The commit itself is the
+  # rollback point for the pass that just ran.
+  git add -A >>"$log" 2>&1
+  git commit -m "loop($id): fix pass $pass" >>"$log" 2>&1 || true
+
+  pass=$((pass + 1))
+done
+
+finish 1 "✗ ceiling — $max pass(es) exhausted"

package/scripts/metrics/collect.mjs

@@ -60,21 +60,30 @@ function knownCommands() {
   }
   // Fallback for a collector run outside the package (e.g. copied into a repo on its own).
   if (!names.size) {
-    for (const n of ['brainstorm', 'spec', 'build', 'smoke', 'review', 'fix', 'ship',
+    for (const n of ['brainstorm', 'spec', 'build', 'review', 'fix', 'ship',
                      'audit', 'refactor', 'align-ds', 'doctor', 'init-pipeline', 'update-pipeline']) names.add(n);
   }
   // Retired commands. The list above is read from the shipped core, so a command that is
   // removed stops being recognised — and every run of it already in the transcripts silently
   // reclassifies as (chat), rewriting history and inflating the catch-all bucket. Keep the
   // names here so past runs stay attributed to what actually ran.
-  for (const n of ['cycle']) names.add(n);
+  for (const n of ['cycle', 'smoke']) names.add(n);
   return names;
 }
 const COMMANDS = knownCommands();
 
+// An invocation is a short instruction that is mostly the command ("move on branding-ramp
+// and /review"). A long prompt that happens to name one is someone TALKING ABOUT the
+// command — a bug report, a design discussion, a pasted transcript. Counting those as runs
+// inflates a command's run count and cost with conversation that never invoked it, which is
+// exactly what happened in cohorte's own repo while this pipeline was being discussed.
+// Only inline mentions are length-gated; an explicit <command-name> is always an invocation.
+const MENTION_MAX_CHARS = 120;
+
 function commandIn(text) {
   const explicit = /<command-name>\s*(\/?[\w:-]+)\s*<\/command-name>/.exec(text);
   if (explicit) return explicit[1].replace(/^\//, '');
+  if (text.trim().length > MENTION_MAX_CHARS) return null;
   // Last mention wins: "finish /build then /review" ends on the one being asked for.
   let found = null;
   for (const m of text.matchAll(/(?:^|\s)\/([a-z][a-z0-9-]{2,})\b/g)) {

package/scripts/preflight.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# preflight.sh — deterministic phase gate for /review and /smoke.
+# preflight.sh — deterministic phase gate for /review.
 #
 # Runs the profile's mechanical checks (typecheck, lint, tests — whatever the caller
 # passes) BEFORE any agent is spawned. A red gate means the caller aborts and relays
@@ -15,7 +15,7 @@
 #   The caller must stop there — no agents.
 # - All green: writes `<project>/.claude/preflight.ok` ("<epoch> <HEAD sha>") — the
 #   stamp `hooks/gate.py` checks (gate-config.json `preflight` block) before letting
-#   review/smoke agents dispatch.
+#   review agents dispatch.
 
 set -u
 

package/scripts/telemetry-send.sh

@@ -2,7 +2,7 @@
 # telemetry-send.sh — fire-and-forget anonymous usage ping (SCHEMA.md §Telemetry).
 #
 #   telemetry-send.sh <phase> <feature_id> <seconds> [results]
-#     phase    brainstorm|spec|build|smoke|review|fix|ship — the feature funnel, and only it.
+#     phase    brainstorm|spec|build|review|fix|ship — the feature funnel, and only it.
 #              Setup/maintenance commands never ping (SCHEMA.md §Telemetry).
 #     feature  the feature id — NEVER sent raw; SHA-256-hashed to 12 hex chars
 #     seconds  batch wall-clock
@@ -39,7 +39,10 @@ phase="${1:-}"; feature="${2:-}"; seconds="${3:-0}"; results="${4:-}"
 # Allowlist the phase here — the collector accepts any string, so a typo in a command
 # file would silently pollute the dataset with a phantom phase nobody notices.
 case "$phase" in
-  brainstorm|spec|build|smoke|review|fix|ship) ;;
+  brainstorm|spec|build|review|fix|ship) ;;
+  # `smoke` is a RETIRED phase (removed in 1.5.0) — still accepted so a stale install
+  # pinging it lands in its own bucket instead of being silently dropped.
+  smoke) ;;
   *) exit 0 ;;
 esac
 

package/scripts/test-dashboard.mjs

@@ -20,6 +20,7 @@ const require = createRequire(import.meta.url);
 const root = fileURLToPath(new URL("..", import.meta.url));
 const { parse, parseProfileBlock } = require(join(root, "dashboard/server/yaml.js"));
 const { metrics } = require(join(root, "dashboard/server/metrics.js"));
+const { usage } = require(join(root, "dashboard/server/usage.js"));
 const { state, scanSpecs } = require(join(root, "dashboard/server/doctor.js"));
 const { kanban } = require(join(root, "dashboard/server/kanban.js"));
 const fleet = require(join(root, "dashboard/server/fleet.js"));
@@ -106,6 +107,25 @@ console.log("metrics.js — the funnel aggregate");
   check("no metrics file ⇒ present:false", metrics({ projectRoot: scratch() }).present === false);
 }
 
+// ── usage.js ─────────────────────────────────────────────────────────────────
+// Wraps the ESM metrics collector for the CJS server. The failure that matters is
+// not a crash: a project with no transcripts must say so, because rendering zeros
+// reads as "this pipeline costs nothing" rather than "nothing was measured".
+console.log("usage.js — the collector bridge");
+{
+  const empty = usage({ projectRoot: scratch() });
+  check("a project with no transcripts reports present:false", empty.present === false);
+  check("…and says why rather than returning silent zeros",
+    typeof empty.error === "string" && empty.error.length > 0, JSON.stringify(empty));
+
+  // Same project twice: the second call must come from cache, or the panel's polling
+  // would re-parse tens of MB of transcripts on every refresh.
+  const d = scratch();
+  const t0 = Date.now(); usage({ projectRoot: d });
+  const t1 = Date.now(); usage({ projectRoot: d }); const cached = Date.now() - t1;
+  check("a repeated read is served from cache", cached <= Math.max(50, (t1 - t0)), `${cached}ms`);
+}
+
 // ── doctor.js ────────────────────────────────────────────────────────────────
 console.log("doctor.js — the /doctor port");
 {
@@ -135,7 +155,7 @@ console.log("doctor.js — the /doctor port");
   const d = scratch();
   const gate = {
     deny: ["x"], ask: ["y"], ask_on_default_branch: ["git push"], default_branch: "main",
-    preflight: { enabled: true, agents: ["review", "smoke"], max_age_minutes: 30 },
+    preflight: { enabled: true, agents: ["review"], max_age_minutes: 30 },
   };
   writeFileSync(join(d, "PIPELINE.md"), [
     "```yaml pipeline-profile",
@@ -153,7 +173,7 @@ console.log("doctor.js — the /doctor port");
     '  ask_on_default_branch: ["git push"]',
     "  preflight:",
     "    enabled: true",
-    "    agents: [review, smoke]",
+    "    agents: [review]",
     "    max_age_minutes: 30",
     "```",
   ].join("\n"));

package/scripts/test-gate.mjs

@@ -181,7 +181,7 @@ console.log("gate.py — config robustness");
 // ── the preflight phase gate (Task dispatches) ───────────────────────────────
 console.log("gate.py — preflight phase gate");
 {
-  const pf = { enabled: true, agents: ["review", "smoke"], max_age_minutes: 30 };
+  const pf = { enabled: true, agents: ["review"], max_age_minutes: 30 };
   const d = scratch(); writeConfig(d, { ...GATE_CFG, preflight: pf });
   const head = gitRepo(d, "main");
   const stamp = (epoch, sha) =>
@@ -195,7 +195,6 @@ console.log("gate.py — preflight phase gate");
 
   stamp(now(), head);
   check("fresh stamp at the current HEAD ⇒ passes", run(task("review"), at).decision === null);
-  check("smoke is gated too", run(task("smoke"), at).decision === null);
 
   stamp(now() - 60 * 60, head);
   check("stamp older than max_age_minutes ⇒ ask", run(task("review"), at).decision === "ask");