@dougharness/cli 1.0.1 → 1.1.0

package/node_modules/@dougharness/flow/lib/board.mjs

@@ -18,6 +18,29 @@ export const DONE = "done";
 export const SIZES = ["S", "M", "L"];
 export const TRACKS = ["flow", "hand"];
 export const CLASSES = ["tests-only", "prose", "gate-script", "code", "docs", "eval", "decision"];
+// Why a task stopped, as a closed set: every halt site in the doug-implement workflow sets one beside its prose
+// stopReason. The workflow carries its own literal copy (it may not import); a template test keeps them equal.
+export const STOP_CLASSES = [
+  "implementer-blocked",
+  "partial",
+  "stage-missing",
+  "spec-contradiction",
+  "environment",
+  "adversary-not-run",
+  "outside-owned",
+  "new-blockers-twice",
+  "fix-attempts-exhausted",
+  "stalled",
+  "budget",
+  "no-new-commit",
+  "dependency-skipped",
+  "stage-threw",
+  "level-adversary",
+];
+// "<id> [<class>]: "<reason>"" for a stopped task; an old report has no class and prints "<id>: "<reason>"".
+function stopText(t) {
+  return `${t.id}${t.stopClass ? ` [${t.stopClass}]` : ""}: "${t.stopReason}"`;
+}
 export const DEFAULT_TAGS = ["bug", "feature", "chore", "docs", "refactor", "spike"];
 
 export const DEFAULT_COLUMNS = [
@@ -28,6 +51,81 @@ export const DEFAULT_COLUMNS = [
   { id: "done", title: "Done", hint: "merged, gate green, documented" },
 ];
 
+// Ready is capped at 7; only the user promotes cards to Ready. A line for stderr when it holds more, else null.
+export const READY_CAP = 7;
+export function readyCapWarning(board) {
+  const n = board.cards.filter((c) => c.column === "ready").length;
+  return n <= READY_CAP ? null : `warning: Ready holds ${n} cards, above the cap of ${READY_CAP}; only the user promotes cards to Ready\n`;
+}
+
+// Wall-clock budget per card in minutes, a size x class table at p80 of measured landings (cards
+// autopilot-wall-cap-by-size, wall-budget-size-class). Each size has `all`; a class key is present only when its
+// cell had WALL_BUDGET_MIN_N or more landings. `board.mjs budgets --from docs/live-runs.md` recomputes it.
+export const WALL_BUDGET_MIN_N = 5;
+export const WALL_BUDGET_MIN = {"S":{"all":57,"code":53,"docs":29,"gate-script":116,"prose":50,"tests-only":66},"M":{"all":102,"code":112,"gate-script":289},"L":{"all":274}};
+
+// A card's budget: its size's class cell when it has one, else the size's `all`. No or an unknown size counts as M.
+export function cardBudgetMinutes(card, table = WALL_BUDGET_MIN) {
+  const size = card && (card.size === "S" || card.size === "M" || card.size === "L") ? card.size : "M";
+  const row = table[size];
+  const cls = card && card.class;
+  return typeof cls === "string" && Object.prototype.hasOwnProperty.call(row, cls) && cls !== "all" ? row[cls] : row.all;
+}
+
+export function wallCapMinutes(cards, table = WALL_BUDGET_MIN) {
+  return cards.reduce((sum, c) => sum + cardBudgetMinutes(c, table), 0);
+}
+
+// The landings in a docs/live-runs.md text: one { id, minutes } per `## <date>, <id>: <title>` section that has a
+// `| Wall clock | <n> min |` row (text after min is allowed; a decimal n is skipped) (the first such row). Older multi-column tables have no such row and are skipped.
+export function parseLiveRunWalls(text) {
+  const out = [];
+  let id = null;
+  let seen = false;
+  for (const line of String(text).split("\n")) {
+    if (line.startsWith("## ")) {
+      const m = /^## \d{4}-\d{2}-\d{2}, ([^:\s]+): /.exec(line);
+      id = m ? m[1] : null;
+      seen = false;
+      continue;
+    }
+    if (id === null || seen) continue;
+    const w = /^\| Wall clock \| (\d+) min(?:\s[^|]*)? \|\s*$/.exec(line);
+    if (w) {
+      out.push({ id, minutes: Number(w[1]) });
+      seen = true;
+    }
+  }
+  return out;
+}
+
+// The table recomputed from samples joined to their cards: p80 (sorted ascending, index min(floor(0.8 n), n - 1)) per size and per size/class cell. A
+// class cell under minN samples is left out (it falls back to its size's `all`); a size with no samples keeps the
+// fallback's `all`. `cells` lists every cell with its n and p80 (cls "all" is the size row; p80 null when n is 0).
+export function wallBudgetTable(samples, board, { minN = WALL_BUDGET_MIN_N, fallback = WALL_BUDGET_MIN } = {}) {
+  const byId = new Map(board.cards.map((c) => [c.id, c]));
+  const groups = { S: { all: [] }, M: { all: [] }, L: { all: [] } };
+  for (const s of samples) {
+    const card = byId.get(s.id);
+    if (!card || !(card.size === "S" || card.size === "M" || card.size === "L")) continue;
+    groups[card.size].all.push(s.minutes);
+    if (typeof card.class === "string" && card.class && card.class !== "all") (groups[card.size][card.class] ||= []).push(s.minutes);
+  }
+  const p80 = (xs) => [...xs].sort((a, b) => a - b)[Math.min(Math.floor(0.8 * xs.length), xs.length - 1)];
+  const table = {};
+  const cells = [];
+  for (const size of ["S", "M", "L"]) {
+    const g = groups[size];
+    table[size] = { all: g.all.length ? p80(g.all) : fallback[size].all };
+    cells.push({ size, cls: "all", n: g.all.length, p80: g.all.length ? p80(g.all) : null });
+    for (const cls of Object.keys(g).filter((k) => k !== "all").sort()) {
+      cells.push({ size, cls, n: g[cls].length, p80: p80(g[cls]) });
+      if (g[cls].length >= minN) table[size][cls] = p80(g[cls]);
+    }
+  }
+  return { table, cells };
+}
+
 function today() {
   return new Date().toISOString().slice(0, 10);
 }
@@ -197,8 +295,9 @@ export function findCard(board, id) {
 // The first Ready card, in board order, whose dependencies are all Done. Ready cards that are waiting
 // on something are reported so the user can see why they were skipped.
 // The first Ready card on the given track whose deps are Done. A card on the hand track is built directly in the
-// checkout (tests, gate, commit) by /core-next, never by /doug-next; a flow card the other way round. A Ready card on
-// the other track is skipped with hand: true or flow: true so the skill can say so. Decision 0005.
+// checkout (tests, gate, commit) through doug-hand, which /doug-next hands it to by id; a flow card the other way round. A Ready card on
+// the other track is skipped with hand: true or flow: true so the skill can say so. Decision 0005. `track: "any"`
+// takes a Ready card of either track (card autopilot): no track skip entries, the deps rule unchanged.
 // `tag`, when given, filters to Ready cards carrying it: a card without it is skipped SILENTLY (not pushed onto
 // `skipped`, since a caller-requested filter should not print a "skipping" line per card it filters out); a `tag`
 // outside boardTags(board) throws.
@@ -210,7 +309,7 @@ export function nextReadyCard(board, { track = "flow", tag } = {}) {
     if (c.column !== READY) continue;
     if (tag !== undefined && !(c.tags || []).includes(tag)) continue;
     const cardTrack = c.track === "hand" ? "hand" : "flow";
-    if (cardTrack !== track) {
+    if (track !== "any" && cardTrack !== track) {
       skipped.push(cardTrack === "hand" ? { id: c.id, hand: true } : { id: c.id, flow: true });
       continue;
     }
@@ -237,7 +336,7 @@ export function nextReadyCards(board, { track = "flow", batch, tag } = {}) {
     if (c.column !== READY || cards.length >= batch) continue;
     if (tag !== undefined && !(c.tags || []).includes(tag)) continue;
     const cardTrack = c.track === "hand" ? "hand" : "flow";
-    if (cardTrack !== track) {
+    if (track !== "any" && cardTrack !== track) {
       skipped.push(cardTrack === "hand" ? { id: c.id, hand: true } : { id: c.id, flow: true });
       continue;
     }
@@ -579,7 +678,36 @@ function outcomeOf(report) {
   return "not green";
 }
 
-export function runEntry({ card, report, cost = null, codexCost = null, wallClock = null, mergeCommit = null, record = null, adversary = [], date = new Date().toISOString().slice(0, 10), batch = null, sharedCost = null, taskIds = [], note = null, rehearsal = null }) {
+// Card flow-wall-budget: the Stage wall row and the summary note from cost.mjs's runWall result (passed in; this
+// library does not import cost.mjs). `keep` narrows the flags to one card's entry of a batch run.
+const wallMin = (ms) => {
+  const m = ms / 60000;
+  return Number.isInteger(m) ? String(m) : m.toFixed(1);
+};
+function wallFlagText(f) {
+  const what = f.kind === "pass" ? `${f.label} pass ${f.pass ?? "?"}` : `${f.kind} ${f.label}`;
+  return `${what} ${wallMin(f.ms)} min > ${wallMin(f.limitMs)}`;
+}
+function wallFlagsFor(wall, report, batch, cardId) {
+  const flags = Array.isArray(wall.flags) ? wall.flags : [];
+  if (!Array.isArray(batch) || batch.length < 2) return flags;
+  const ids = (report.levels || []).flatMap((l) => (l.tasks || []).map((t) => t.id));
+  return flags.filter((f) => {
+    const label = String(f.label).replace(/:retry$/, "");
+    if (/(^|:)level-\d+$/.test(label)) return batch[0] === cardId;
+    return ids.some((id) => label === id || label.startsWith(`${id}:`) || label.includes(`:${id}:`) || label.endsWith(`:${id}`));
+  });
+}
+function wallRow(wall, flags) {
+  if (!wall) return "not measured";
+  if (!wall.measured) return `unverified: ${wall.reason || "no agent times"}`;
+  const unverified = Array.isArray(wall.unverified) && wall.unverified.length ? `; unverified tasks: ${wall.unverified.join(", ")}` : "";
+  if (flags.length) return `over: ${flags.map(wallFlagText).join("; ")}${unverified}`;
+  const longest = Math.max(0, ...(wall.tasks || []).map((t) => t.ms));
+  return `within budget (${wall.wallMinutes ?? wallMin(longest)} min a task)${unverified}`;
+}
+
+export function runEntry({ card, report, cost = null, codexCost = null, wallClock = null, wall = null, mergeCommit = null, record = null, adversary = [], date = new Date().toISOString().slice(0, 10), batch = null, sharedCost = null, taskIds = [], note = null, rehearsal = null }) {
   const inBatch = Array.isArray(batch) && batch.length > 1;
   if (inBatch) report = filterReportForCard(report, card.id, taskIds);
   const lines = [];
@@ -588,7 +716,7 @@ export function runEntry({ card, report, cost = null, codexCost = null, wallCloc
   const batchNote = inBatch ? `, in one plan with ${listOthers(batch, card.id)} (one approval, one run, one landing)` : "";
   lines.push(
     rehearsal
-      ? `Rehearsal ${rehearsal} for card \`${card.id}\` on the ts-basic fixture (plugins/doug-flow/scripts/rehearse.mjs); the commit and gate below are the fixture's, not this repository's.`
+      ? `Rehearsal ${rehearsal} for card \`${card.id}\` on the ts-basic fixture (scripts/rehearse.mjs); the commit and gate below are the fixture's, not this repository's.`
       : `Ran through /doug-next on this repo from card \`${card.id}\`${record ? ` in \`${record}\`` : ""}${batchNote}. Plan "${report.plan}", integration branch \`${report.integrationBranch}\`${report.modelsSource ? `, models from ${report.modelsSource}` : ""}.`,
   );
   lines.push("");
@@ -609,6 +737,7 @@ export function runEntry({ card, report, cost = null, codexCost = null, wallCloc
   }
   if (inBatch) lines.push(`| Shared integration agents | ${sharedCost === null ? "not measured" : `$${Number(sharedCost).toFixed(2)}, counted once for the batch ${batch[0] === card.id ? "here" : `under ${batch[0]}`}`} |`);
   lines.push(`| Wall clock | ${wallClock === null ? "not measured" : wallClock} |`);
+  lines.push(`| Stage wall | ${wallRow(wall, wall ? wallFlagsFor(wall, report, inBatch ? batch : null, card.id) : [])} |`);
   const blocks = classifyBlocks(report, adversary);
   const shownCommit = rehearsal && mergeCommit ? String(mergeCommit).slice(0, 7) : mergeCommit;
   lines.push(`| Landed as | ${shownCommit ? `\`${shownCommit}\`` : "not landed"} |`);
@@ -634,6 +763,11 @@ export function runEntry({ card, report, cost = null, codexCost = null, wallCloc
     }
     lines.push(`| ${level.index} | integration | ${level.integration ? (level.integration.ok ? "ok" : "failed") : "not run"} | | | | ${describeTierCell({ implement: level.integrationModel })} | ${levelAdversaryCell(level.levelAdversary)} |`);
   }
+  const stopped = (report.levels || []).flatMap((l) => (l.tasks || []).filter((t) => t.stopReason));
+  if (stopped.length) {
+    lines.push("");
+    lines.push(`Stopped: ${stopped.map(stopText).join("; ")}`);
+  }
   if (blocks.length) {
     lines.push("");
     lines.push("Adversary blocks, classified (real: a defect a user would hit; marginal: true to the spec, no user impact; false: wrong):");
@@ -644,15 +778,15 @@ export function runEntry({ card, report, cost = null, codexCost = null, wallCloc
 }
 
 // The live-runs entry for a hand-track card (decision 0005): no workflow report and no levels, so it records what
-// /core-next can measure: the landing commit, the wall clock, and the gate result, plus an optional note.
+// doug-hand can measure: the landing commit, the wall clock, and the gate result, plus an optional note.
 export function handEntry({ card, commit = null, wallClock = null, gate = null, note = null, record = null, date = new Date().toISOString().slice(0, 10), rehearsal = null }) {
   const lines = [];
   lines.push(`## ${date}, ${card.id}: ${card.title}`);
   lines.push("");
   lines.push(
     rehearsal
-      ? `Rehearsal ${rehearsal} for card \`${card.id}\` on the ts-basic fixture (plugins/doug-flow/scripts/rehearse.mjs); the commit and gate below are the fixture's, not this repository's.`
-      : `Built by hand through /core-next from card \`${card.id}\`${record ? ` in \`${record}\`` : ""} (hand track, decision 0005); no workflow run.`,
+      ? `Rehearsal ${rehearsal} for card \`${card.id}\` on the ts-basic fixture (scripts/rehearse.mjs); the commit and gate below are the fixture's, not this repository's.`
+      : `Built by hand through doug-hand from card \`${card.id}\`${record ? ` in \`${record}\`` : ""} (hand track: a gated by-hand change); no workflow run.`,
   );
   lines.push("");
   lines.push("| Measure | Value |");
@@ -764,13 +898,21 @@ function acceptanceUnmet(report, tasks) {
   return { unmet, source: ` (acceptance read per task by [card] tag${asideNote})`, dirty: asideFailing > 0 };
 }
 
+function wallNote(wall, flags) {
+  if (!wall) return "";
+  if (!wall.measured) return " (stage times unverified)";
+  const n = Array.isArray(wall.unverified) ? wall.unverified.length : 0;
+  const unv = n ? ` (stage times unverified for ${n} task${n === 1 ? "" : "s"})` : "";
+  return (flags.length ? ` (over budget: ${flags.map(wallFlagText).join("; ")})` : "") + unv;
+}
+
 // Three lines for the chat after a run: the outcome, the tasks, and what stopped or was not met. Everything in it
 // is read from the report; nothing is estimated.
-export function runSummary({ report, cost = null, codexCost = null, wallClock = null, mergeCommit = null }) {
+export function runSummary({ report, cost = null, codexCost = null, wallClock = null, wall = null, mergeCommit = null, batch = null, card = null }) {
   const tasks = (report.levels || []).flatMap((l) => (l.tasks || []).map((t) => ({ level: l, task: t })));
   const integrated = tasks.filter(({ level }) => level.integration && level.integration.ok).length;
   const outcome = outcomeOf(report);
-  const first = `${report.plan}: ${outcome}; ${tasks.length} task${tasks.length === 1 ? "" : "s"}, ${integrated} integrated; wall ${wallClock === null ? "not measured" : wallClock}; cost ${cost === null ? "not measured" : `$${Number(cost).toFixed(2)}`}${codexCost === null ? "" : `; Codex $${Number(codexCost).toFixed(2)}`}${mergeCommit ? `; landed as ${mergeCommit}` : ""}.`;
+  const first = `${report.plan}: ${outcome}; ${tasks.length} task${tasks.length === 1 ? "" : "s"}, ${integrated} integrated; wall ${wallClock === null ? "not measured" : wallClock}; cost ${cost === null ? "not measured" : `$${Number(cost).toFixed(2)}`}${codexCost === null ? "" : `; Codex $${Number(codexCost).toFixed(2)}`}${mergeCommit ? `; landed as ${mergeCommit}` : ""}${wallNote(wall, wall ? wallFlagsFor(wall, report, batch, card) : [])}.`;
   const second = tasks.length
     ? tasks.map(({ task: t }) => {
         const passes = Array.isArray(t.attempts) && t.attempts.length ? t.attempts.length : 1;
@@ -780,7 +922,7 @@ export function runSummary({ report, cost = null, codexCost = null, wallClock =
         return `${t.id}: ${impl}, ${passes} pass${passes === 1 ? "" : "es"}, verify ${yesNo(t.verified)}, review ${yesNo(t.reviewed)}, adversary ${adv}`;
       }).join("; ")
     : "no tasks";
-  const stops = tasks.filter(({ task: t }) => t.stopReason).map(({ task: t }) => `${t.id}: "${t.stopReason}"`);
+  const stops = tasks.filter(({ task: t }) => t.stopReason).map(({ task: t }) => stopText(t));
   const { unmet, source, dirty } = acceptanceUnmet(report, tasks);
   const pause = pausedAt(report) ? `Paused at the human gate after level ${pausedAt(report).level}; next: ${listNext(report)}. Open it with plan.mjs gate open ${pausedAt(report).level} and resume the run.` : "";
   const third = pause || stops.length || unmet.length

package/node_modules/@dougharness/flow/lib/code-index.mjs

@@ -545,7 +545,7 @@ function rowsByIdMap(m, ids) {
 // the BM25 side (a precomputed allow-list of matching paths, so the ranking itself runs restricted), in memory
 // for the vector side. Never throws for a provider problem; a query with no FTS tokens simply has no BM25 side.
 export async function searchIndex(m, query, opts = {}) {
-  const { k = 8, files = [], provider = null } = opts;
+  const { k = 8, files = [], provider = null, detectedProvider = null } = opts;
 
   const allowedPaths = files.length
     ? new Set(
@@ -576,14 +576,16 @@ export async function searchIndex(m, query, opts = {}) {
   let reason = "no provider configured";
   let providerName = null;
   let vectorRanked = [];
+  let vectorsForProvider = 0;
   if (provider) {
     providerName = provider.name;
     let vectorRows = m
       .prepare("SELECT id, path, embedding FROM code_chunks WHERE embedding_model = ? AND embedding_dims = ?")
       .all(provider.model, provider.dims);
+    vectorsForProvider = vectorRows.length;
     if (allowedPaths) vectorRows = vectorRows.filter((r) => allowedPaths.has(r.path));
     if (!vectorRows.length) {
-      reason = `no vectors stored for ${provider.model}/${provider.dims}`;
+      reason = vectorsForProvider > 0 ? "no vectors in the filtered paths" : `no vectors stored for ${provider.model}/${provider.dims}`;
     } else {
       const embedResult = await provider.embed([String(query || "")], { inputType: "query" });
       if (!embedResult.ok) {
@@ -604,6 +606,19 @@ export async function searchIndex(m, query, opts = {}) {
     }
   }
 
+  // card recall-fallback-warning: a filter that excludes every vector while vectors exist for the provider is
+  // not degraded; hybrid counts chunks without a vector for the provider over the whole index.
+  const anyVectors = () => m.prepare("SELECT 1 FROM code_chunks WHERE embedding IS NOT NULL LIMIT 1").get() !== undefined;
+  const filteredOut = mode === "keyword-only" && !!provider && vectorsForProvider > 0 && reason === "no vectors in the filtered paths";
+  const degraded = mode === "keyword-only" && !filteredOut && (!!provider || anyVectors() || !!detectedProvider);
+  const coverage = {};
+  if (mode === "hybrid") {
+    coverage.total = m.prepare("SELECT COUNT(*) AS n FROM code_chunks").get().n;
+    coverage.unvectored = coverage.total - m
+      .prepare("SELECT COUNT(*) AS n FROM code_chunks WHERE embedding_model = ? AND embedding_dims = ?")
+      .get(provider.model, provider.dims).n;
+  }
+
   const fused = new Map();
   bm25Ranked.forEach((id, idx) => fused.set(id, (fused.get(id) || 0) + 1 / (60 + idx + 1)));
   vectorRanked.forEach((id, idx) => fused.set(id, (fused.get(id) || 0) + 1 / (60 + idx + 1)));
@@ -625,5 +640,5 @@ export async function searchIndex(m, query, opts = {}) {
     })
     .filter(Boolean);
 
-  return { mode, reason: mode === "hybrid" ? null : reason, provider: providerName, chunks };
+  return { mode, reason: mode === "hybrid" ? null : reason, provider: providerName, degraded, ...coverage, chunks };
 }

package/node_modules/@dougharness/flow/lib/context.mjs

@@ -0,0 +1,57 @@
+// The lead's own context reading (card autopilot-unlimited): scripts/context.mjs prints the last assistant line's
+// usage in the session transcript against its model's window, and whether it is at autopilot.contextThreshold.
+// windowFor and contextReading are copied from plugins/doug-gates/lib/agent-context.mjs: the plugins install
+// separately, so doug-flow cannot import across the boundary (as learn.mjs keeps its own local glob copy).
+
+import { readFileSync, existsSync } from "node:fs";
+
+// 1M for a Fable/Opus/Sonnet 5 model, 200k otherwise (an unknown or missing model errs early, on the smaller window).
+export function windowFor(model) {
+  if (typeof model !== "string") return 200000;
+  return /fable-5|opus-5|sonnet-5/.test(model) ? 1000000 : 200000;
+}
+
+// The last assistant line with usage in a transcript file, against its model's window. null when the file is
+// missing, unreadable, or has no assistant line carrying usage.
+export function contextReading(file, { windows = windowFor } = {}) {
+  if (!file || !existsSync(file)) return null;
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  let lastMessage = null;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let o;
+    try {
+      o = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (o && o.type === "assistant" && o.message && o.message.usage) lastMessage = o.message;
+  }
+  if (!lastMessage) return null;
+  const u = lastMessage.usage;
+  const tokens = (u.input_tokens || 0) + (u.cache_creation_input_tokens || 0) + (u.cache_read_input_tokens || 0);
+  const model = lastMessage.model || null;
+  const window = windows(model);
+  return { tokens, model, window, pct: Math.round((100 * tokens) / window) };
+}
+
+export const CONTEXT_THRESHOLD_DEFAULT = 60;
+
+// The configured autopilot.contextThreshold when it is a finite number in 1..100; the default silently when the key
+// (or autopilot) is absent or null; the default plus one warn() call otherwise.
+export function contextThreshold(config, warn = () => {}) {
+  const v = config && config.autopilot ? config.autopilot.contextThreshold : undefined;
+  if (v === undefined || v === null) return CONTEXT_THRESHOLD_DEFAULT;
+  if (typeof v === "number" && Number.isFinite(v) && v >= 1 && v <= 100) return v;
+  warn(`autopilot.contextThreshold must be a number from 1 to 100; using ${CONTEXT_THRESHOLD_DEFAULT}`);
+  return CONTEXT_THRESHOLD_DEFAULT;
+}
+
+export function atThreshold(pct, threshold) {
+  return pct >= threshold;
+}

package/node_modules/@dougharness/flow/lib/cost.mjs

@@ -1,15 +1,15 @@
 // Real cost of one doug-implement run, from the local Claude Code transcripts (decision 0005, card cost-per-run).
 // No network: the run's agent ids come from its journal under ~/.claude/projects/<slug>/<session>/subagents/workflows/<run>/,
 // each agent's tokens are summed from its transcript there, and the price comes from the table below.
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 // USD per million tokens, first-party Claude API list prices. Cache reads are 0.1x input (0.025x on Fable 5.1,
 // 0.05x on Opus 5.5); cache writes are 1.25x input for the 5-minute TTL and 2x for the 1-hour TTL. Opus 5.5:
 // input 4, output 20, cacheRead 0.2, cacheWrite5m 5, cacheWrite1h 8; source
-// https://platform.claude.com/docs/en/about-claude/pricing, fetched 2026-09-23. Update the date with the table.
-export const PRICES_DATED = "2026-09-23";
+// https://platform.claude.com/docs/en/about-claude/pricing, fetched 2026-10-04. Update the date with the table.
+export const PRICES_DATED = "2026-10-04";
 export const PRICES = {
   "claude-fable-5-1": { input: 10, output: 50, cacheRead: 0.25, cacheWrite5m: 12.5, cacheWrite1h: 20 },
   "claude-fable-5": { input: 10, output: 50, cacheRead: 1, cacheWrite5m: 12.5, cacheWrite1h: 20 },
@@ -18,6 +18,7 @@ export const PRICES = {
   "claude-opus-4-8": { input: 5, output: 25, cacheRead: 0.5, cacheWrite5m: 6.25, cacheWrite1h: 10 },
   "claude-opus-4-7": { input: 5, output: 25, cacheRead: 0.5, cacheWrite5m: 6.25, cacheWrite1h: 10 },
   "claude-opus-4-6": { input: 5, output: 25, cacheRead: 0.5, cacheWrite5m: 6.25, cacheWrite1h: 10 },
+  "claude-sonnet-5-5": { input: 2, output: 10, cacheRead: 0.2, cacheWrite5m: 2.5, cacheWrite1h: 4 },
   "claude-sonnet-5": { input: 2, output: 10, cacheRead: 0.2, cacheWrite5m: 2.5, cacheWrite1h: 4 },
   "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3, cacheWrite5m: 3.75, cacheWrite1h: 6 },
   "claude-haiku-4-5": { input: 1, output: 5, cacheRead: 0.1, cacheWrite5m: 1.25, cacheWrite1h: 2 },
@@ -318,6 +319,64 @@ export function costRun({ runId, claudeDir, projectDir, report, reportPath } = {
   };
 }
 
+// Card flow-wall-budget: slow tasks flagged after the run, from the runtime's run file (workflowProgress[] agents
+// carry startedAt and durationMs). Detection only; the budget is the report's wallMinutes. A task's wall and a
+// pass's wall are spans (latest end minus earliest start), never sums, since agents of a pass run alongside.
+export const PASS_WALL_SHARE = 0.75;
+export const STAGE_WALL_SHARE = 0.25;
+
+export function runWall(run, { wallMinutes } = {}) {
+  const MIN = 60000;
+  const result = (extra) => ({ measured: false, reason: null, wallMinutes, unverified: [], tasks: [], flags: [], ...extra });
+  const agents = run && Array.isArray(run.workflowProgress) ? run.workflowProgress.filter((p) => p && p.type === "workflow_agent") : [];
+  if (!agents.length) return result({ reason: "no run file" });
+  const timed = (a) => typeof a.startedAt === "number" && typeof a.durationMs === "number";
+  if (!agents.some(timed)) return result({ reason: "no agent times" });
+  const taskLimit = wallMinutes * MIN;
+  const passLimit = PASS_WALL_SHARE * taskLimit;
+  const stageLimit = STAGE_WALL_SHARE * taskLimit;
+  const byTask = new Map();
+  const stageFlags = [];
+  for (const a of agents) {
+    const label = String(a.label || "");
+    const parsed = parseLabel(label.replace(/:retry$/, ""));
+    if (timed(a) && a.durationMs > stageLimit) stageFlags.push({ kind: "stage", label, ms: a.durationMs, limitMs: stageLimit });
+    if (!parsed.task || /^level-\d+$/.test(parsed.task)) continue;
+    const t = byTask.get(parsed.task) || { task: parsed.task, agents: [], missing: false };
+    if (timed(a)) t.agents.push({ pass: parsed.pass ?? 1, from: a.startedAt, to: a.startedAt + a.durationMs });
+    else t.missing = true;
+    byTask.set(parsed.task, t);
+  }
+  const span = (list) => Math.max(...list.map((x) => x.to)) - Math.min(...list.map((x) => x.from));
+  const unverified = [];
+  const tasks = [];
+  const flags = [];
+  for (const t of byTask.values()) {
+    if (t.missing || !t.agents.length) {
+      unverified.push(t.task);
+      continue;
+    }
+    const passNums = [...new Set(t.agents.map((x) => x.pass))].sort((x, y) => x - y);
+    const passes = passNums.map((n) => ({ pass: n, ms: span(t.agents.filter((x) => x.pass === n)) }));
+    const ms = span(t.agents);
+    tasks.push({ task: t.task, ms, passes, stages: [] });
+    if (ms > taskLimit) flags.push({ kind: "task", label: t.task, ms, limitMs: taskLimit });
+    for (const p of passes) if (p.ms > passLimit) flags.push({ kind: "pass", label: t.task, pass: p.pass, ms: p.ms, limitMs: passLimit });
+  }
+  return result({ measured: true, unverified, tasks, flags: [...flags, ...stageFlags] });
+}
+
+// runWall for a run id: finds the run file next to the journal; never throws, an unreadable run is not measured.
+export function wallForRun({ runId, claudeDir, projectDir, wallMinutes } = {}) {
+  try {
+    const found = findRunDir({ runId, claudeDir, projectDir });
+    if (!found) return runWall(null, { wallMinutes });
+    return runWall(readJson(found.runFile), { wallMinutes });
+  } catch {
+    return runWall(null, { wallMinutes });
+  }
+}
+
 // A batch run's cost split per card (card parallel-cards): every agent whose task is one of a card's plan tasks
 // counts for that card; the shared stages (integrate, the level adversary: task `level-<n>`) are listed once as
 // `shared`; agents on no card's task are `other`. Nothing estimated: unpriced agents are counted, not summed.
@@ -359,6 +418,72 @@ export function renderCostByCard(byCard) {
 const fmtInt = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 const fmtUsd = (n) => (n === null ? "unpriced" : `$${n.toFixed(2)}`);
 
+// The top-level transcript path for a session id or "latest" (the most recently modified one in the project's slug
+// directory). Throws when none is found. Used by costSession and scripts/context.mjs.
+export function sessionTranscriptPath({ session, claudeDir = join(homedir(), ".claude"), projectDir = process.cwd() } = {}) {
+  if (!session) throw new Error("a session id or latest is required");
+  const slugDir = join(claudeDir, "projects", projectSlug(projectDir));
+  let id = session;
+  if (session === "latest") {
+    let best = null;
+    if (existsSync(slugDir)) {
+      for (const e of readdirSync(slugDir, { withFileTypes: true })) {
+        if (!e.isFile() || !e.name.endsWith(".jsonl")) continue;
+        const mtime = statSync(join(slugDir, e.name)).mtimeMs;
+        if (!best || mtime > best.mtime) best = { id: e.name.slice(0, -".jsonl".length), mtime };
+      }
+    }
+    if (!best) throw new Error(`no session transcript under ${slugDir}`);
+    id = best.id;
+  }
+  const top = join(slugDir, `${id}.jsonl`);
+  if (!existsSync(top)) throw new Error(`no transcript for session ${id} under ${slugDir}`);
+  return top;
+}
+
+// The cost of one Claude Code session (card autopilot): its top-level transcript plus every *.jsonl under
+// <slug>/<session>/subagents/, recursively (plain agents and workflows/wf_*/ agents). `session` is an id or "latest",
+// the most recently modified top-level transcript in the project's slug directory. Throws when none is found.
+// Workflow journal.jsonl files carry no usage lines and add nothing.
+export function costSession({ session, claudeDir = join(homedir(), ".claude"), projectDir = process.cwd() } = {}) {
+  const top = sessionTranscriptPath({ session, claudeDir, projectDir });
+  const slugDir = join(claudeDir, "projects", projectSlug(projectDir));
+  const id = basename(top, ".jsonl");
+  const files = [top];
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile() && e.name.endsWith(".jsonl")) files.push(p);
+    }
+  };
+  const subDir = join(slugDir, id, "subagents");
+  if (existsSync(subDir)) walk(subDir);
+  const usage = emptyUsage();
+  let usd = 0;
+  let unpriced = 0;
+  const notes = [];
+  for (const f of files) {
+    const t = transcriptUsage(f);
+    addUsage(usage, t.usage);
+    if (!t.messages) continue;
+    const price = t.model ? priceUsage(t.usage, t.model) : null;
+    if (price === null) {
+      unpriced++;
+      notes.push(`${f}: model ${t.model || "unknown"} is not in the price table; not priced`);
+    } else usd += price;
+  }
+  return { session: id, files: files.length, total: { usage, usd, unpriced, agents: files.length }, pricesDated: PRICES_DATED, notes };
+}
+
+export function renderSession(result) {
+  const t = result.total;
+  const lines = [`Session ${result.session}: ${result.files} transcript${result.files === 1 ? "" : "s"}.`];
+  lines.push(`Session total: ${fmtInt(t.usage.input)} input, ${fmtInt(t.usage.output)} output, ${fmtInt(t.usage.cacheRead)} cache read, ${fmtInt(t.usage.cacheWrite)} cache write tokens; ${fmtUsd(t.usd)}${t.unpriced ? ` (${t.unpriced} transcript(s) unpriced)` : ""} at list prices dated ${result.pricesDated}.`);
+  for (const n of result.notes) lines.push(`Note: ${n}.`);
+  return lines.join("\n") + "\n";
+}
+
 export function renderCost(result) {
   const lines = [];
   const when = result.startedAt ? `, ${result.startedAt}` : "";

package/node_modules/@dougharness/flow/lib/data/pairs.json

@@ -0,0 +1,103 @@
+{
+  "margin": 0.15,
+  "paraphrase": [
+    [
+      "The pre-commit hook re-runs the whole gate, so committing without waiting for tests wastes the developer's time.",
+      "Skipping ahead of the test run before a commit is pointless because the hook repeats every check anyway."
+    ],
+    [
+      "Worktrees under .claude/worktrees are gitignored and safe to delete once a task lands.",
+      "Once a task merges, the per-task checkout folder can be removed since it was never tracked by git."
+    ],
+    [
+      "Plan verify commands should call pnpm test:unit, never the full suite, because pnpm test spawns a live Codex call.",
+      "Use the unit-only test script for a plan's verify step; running the full suite triggers an actual Codex invocation."
+    ],
+    [
+      "A worker nearing its context limit should stop at a clean boundary and report a partial result instead of guessing.",
+      "When an agent's context window is almost full, it ought to pause at a good stopping point and flag the work as unfinished."
+    ],
+    [
+      "node:sqlite requires Node 22.16 or newer, so an older runtime must fail with one clear message rather than a stack trace.",
+      "Running on a Node version below 22.16 needs to produce a single readable error, not a crash dump, since the built-in SQLite module needs that version."
+    ],
+    [
+      "Force-deleting a git branch is blocked by the bash guard; merge it first and use the plain delete flag.",
+      "The shell guard refuses a hard branch removal, so branches must be merged before a normal delete works."
+    ],
+    [
+      "Lessons are append-only: a later insight can supersede an older one but the original text is never rewritten.",
+      "The store never edits a lesson's wording after the fact; a newer entry can mark an old one as replaced instead."
+    ],
+    [
+      "Reviewers should flag a pull request that widens scope beyond what the plan's tasks actually own.",
+      "When a change touches files outside what a task was granted, that overreach is exactly what review should catch."
+    ],
+    [
+      "The adversary review runs on Codex by default, falling back to an Opus pass when Codex can't be reached.",
+      "Codex normally does the adversarial check, but the workflow switches to Opus whenever Codex is unavailable."
+    ],
+    [
+      "Auto memory import should be idempotent, never rewriting files it did not itself create in the memory directory.",
+      "Re-running the import of automatic memory must not touch files outside its own directory and must produce the same result each time."
+    ],
+    [
+      "A swarm's lead splits one task into worker briefs and merges their results before verification starts.",
+      "In a swarm, the lead agent breaks a task into pieces for workers and combines their output ahead of the verify stage."
+    ],
+    [
+      "Keep CLAUDE.md under sixty lines since hooks already enforce most of the guardrails it would otherwise restate.",
+      "The instructions file should stay short, under sixty lines, because the hook layer already covers most of what it would repeat."
+    ]
+  ],
+  "unrelated": [
+    [
+      "The pre-commit hook re-runs the whole test gate before allowing a commit to land.",
+      "Ollama serves an OpenAI-compatible /v1/embeddings endpoint on port 11434 by default."
+    ],
+    [
+      "Worktrees under .claude/worktrees are gitignored and removed once a task merges.",
+      "A pull request title should stay under seventy characters so it reads well in a list view."
+    ],
+    [
+      "pnpm test:unit skips the live Codex test so a plan's verify step never spends real usage.",
+      "Vectors returned by the embedding provider are L2-normalized before they are stored in the database."
+    ],
+    [
+      "A worker close to its context limit should stop at a clean boundary and report a partial result.",
+      "The board's Ready column lists the next three small cards ahead of the larger context-window card."
+    ],
+    [
+      "node:sqlite needs Node 22.16 or newer for the built-in FTS5 support the lessons table relies on.",
+      "The reflect command proposes at most three new lessons per report, filtered by a cheap-row model pass."
+    ],
+    [
+      "Force-deleting a git branch is blocked by the bash guard; use a normal merge and delete instead.",
+      "Voyage AI's embeddings endpoint accepts an output_dimension parameter to control vector width."
+    ],
+    [
+      "Lessons are append-only; an older entry can be superseded but its text is never rewritten.",
+      "The doctor subcommand probes a configured provider or a local Ollama installation and prints what it found."
+    ],
+    [
+      "Review should catch a change that touches files outside what its task was granted to own.",
+      "A hand-track landing records the card id, commit, wall-clock time, and gate line, but has no report file."
+    ],
+    [
+      "The adversary review defaults to Codex and falls back to an Opus pass when Codex cannot run.",
+      "Recall fuses BM25 keyword scores with cosine similarity using reciprocal rank fusion when a provider is configured."
+    ],
+    [
+      "Importing auto memory is idempotent and never rewrites files outside its own memory directory.",
+      "The bash guard also blocks deleting a remote branch directly; ask first or merge it locally."
+    ],
+    [
+      "A swarm's lead agent splits a task into worker briefs and merges their output before verification.",
+      "CLAUDE.md documents only what hooks cannot already enforce, and stays under sixty lines."
+    ],
+    [
+      "Keep CLAUDE.md under sixty lines because the hook layer already enforces most of the guardrails.",
+      "A citation of the form path:line is re-checked against the checkout only when the directory contains a .doug folder."
+    ]
+  ]
+}