@dougharness/cli 1.0.2 → 1.1.1

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

@@ -15,8 +15,10 @@ import { mkdirSync, existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, resolve, join } from "node:path";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
 import { classifyBlocks, adversaryBlocks } from "./board.mjs";
-import { transcriptUsage, priceUsage, projectSlug, CODEX_PRICES, CODEX_DEFAULT_MODEL } from "./cost.mjs";
+import { transcriptUsage, projectSlug, CODEX_PRICES, CODEX_DEFAULT_MODEL } from "./cost.mjs";
 import { MODELS_HEADING } from "./models.mjs";
 
 let DatabaseSync;
@@ -459,6 +461,44 @@ export function openMemory(dir) {
   };
 }
 
+// Read-only probe for `doug doctor`: can this Node build an FTS5 table in memory? Never throws.
+export function probeSqliteFts5() {
+  try {
+    const db = new DatabaseSync(":memory:");
+    try {
+      db.exec("CREATE VIRTUAL TABLE probe USING fts5(x)");
+    } finally {
+      db.close();
+    }
+    return { ok: true, reason: null };
+  } catch (err) {
+    return { ok: false, reason: err && err.message ? err.message : String(err) };
+  }
+}
+
+// Read-only look at the store for `doug doctor`: creates nothing, migrates nothing, never throws.
+export function inspectMemory(dir) {
+  const file = memoryPath(dir);
+  const out = { file, exists: false, userVersion: null, maxUserVersion: 8, quickCheck: null, error: null };
+  if (!existsSync(file)) return out;
+  out.exists = true;
+  let db;
+  try {
+    db = new DatabaseSync(file, { readOnly: true });
+    out.userVersion = db.prepare("PRAGMA user_version").get().user_version;
+    out.quickCheck = String(db.prepare("PRAGMA quick_check").get().quick_check);
+  } catch (err) {
+    out.error = err && err.message ? err.message : String(err);
+  } finally {
+    try {
+      if (db) db.close();
+    } catch {
+      // already unusable
+    }
+  }
+  return out;
+}
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -787,22 +827,32 @@ function toRecallLesson(lesson, extra) {
   return { ...rest, hasVector: !!embedding, ...extra };
 }
 
-// --- Hybrid recall -----------------------------------------------------------------------------------------
-// BM25 (FTS5) and cosine-over-stored-vectors fused by reciprocal rank fusion, recency-weighted, scope-boosted,
-// then citation-rechecked against checkoutDir before anything is returned — only when checkoutDir is a real
-// project root (isProjectRoot); otherwise every candidate is returned unchecked (checked: false in the result)
-// rather than either throwing (no checkoutDir given) or marking every row stale forever (a wrong one given).
-// Never throws for a provider or checkout problem (a database problem may still throw, same as every other
-// export here). See design #2 in the memory-recall card for the step-by-step this implements.
+// --- Dense-ranked recall -----------------------------------------------------------------------------------
+// With a provider and vectors stored under its model/dims, every vectored live in-window lesson is ranked by
+// cosine similarity x recency weight x scope boost (memory-benchmark section 9: cosine x recency beat the old
+// 50+50 reciprocal rank fusion); BM25 hits that have no such vector are appended after all vectored lessons, in
+// BM25 order. Without a provider or vectors, BM25 x recency x scope is the ranking (mode keyword-only). Ties
+// break by lesson id ascending. Results are then citation-rechecked against checkoutDir before anything is
+// returned — only when checkoutDir is a real project root (isProjectRoot); otherwise every candidate is
+// returned unchecked (checked: false in the result) rather than either throwing (no checkoutDir given) or
+// marking every row stale forever (a wrong one given). Never throws for a provider or checkout problem (a
+// database problem may still throw, same as every other export here). See design #2 in the memory-recall card.
 export async function recallLessons(m, query, opts = {}) {
-  const { files = [], k = 8, now = new Date(), provider = null, checkoutDir = null, staleDays = 30 } = opts;
+  const { files = [], k = 8, now = new Date(), provider = null, checkoutDir = null, staleDays = 30, detectedProvider = null } = opts;
   const nowDate = now instanceof Date ? now : new Date(now);
   const nowIsoStr = nowDate.toISOString();
   const nowMs = nowDate.getTime();
   const checked = isProjectRoot(checkoutDir);
 
   // (a) candidates: not superseded, not stale, and confirmed-or-created within staleDays.
-  const allRows = m.prepare("SELECT * FROM lessons WHERE superseded_by IS NULL AND stale IS NULL").all().map(lessonRowToObject);
+  // Light columns only: the embedding blob is never loaded here (card recall-scale-row-load).
+  const allRows = m
+    .prepare(
+      "SELECT id, created, confirmed, scope, embedding_model, embedding_dims, embedding IS NOT NULL AS has_vec FROM lessons WHERE superseded_by IS NULL AND stale IS NULL"
+    )
+    .all()
+    .map(lessonRowToObject);
+  const hasVec = (l) => !!l.has_vec;
   const freshRows = allRows.filter((l) => ageDaysOf(l.confirmed || l.created, nowMs) <= staleDays);
   const byId = new Map(freshRows.map((l) => [l.id, l]));
 
@@ -820,16 +870,24 @@ export async function recallLessons(m, query, opts = {}) {
     bm25Ranked = rows.map((r) => r.id).filter((id) => byId.has(id));
   }
 
-  // (c) vector side, only with a provider and rows stored under the same model+dims, top 50.
+  // (c) dense side, only with a provider and rows stored under the same model+dims: cosine (dot of the stored
+  // vectors) for every such row, not only BM25 hits.
   let mode = "keyword-only";
   let reason = "no provider configured";
   let providerName = null;
-  let vectorRanked = [];
+  const cosine = new Map();
   if (provider) {
     providerName = provider.name;
-    const vectorRows = freshRows.filter(
-      (l) => l.embedding && l.embedding_model === provider.model && l.embedding_dims === provider.dims
-    );
+    // Blobs are read only when the light columns say a fresh row holds one under this model/dims.
+    const anyMatching = freshRows.some((l) => hasVec(l) && l.embedding_model === provider.model && l.embedding_dims === provider.dims);
+    const vectorRows = !anyMatching
+      ? []
+      : m
+      .prepare(
+        "SELECT id, embedding FROM lessons WHERE superseded_by IS NULL AND stale IS NULL AND embedding IS NOT NULL AND embedding_model = ? AND embedding_dims = ?"
+      )
+      .all(provider.model, provider.dims)
+      .filter((l) => byId.has(l.id));
     if (!vectorRows.length) {
       reason = `no vectors stored for ${provider.model}/${provider.dims}`;
     } else {
@@ -838,49 +896,83 @@ export async function recallLessons(m, query, opts = {}) {
         reason = embedResult.reason;
       } else {
         const qVec = embedResult.vectors[0];
-        const scored = vectorRows.map((l) => {
+        for (const l of vectorRows) {
           const vec = blobToFloats(l.embedding);
           let dot = 0;
           for (let i = 0; i < qVec.length && i < vec.length; i++) dot += qVec[i] * vec[i];
-          return { id: l.id, score: dot };
-        });
-        scored.sort((a, b) => b.score - a.score);
-        vectorRanked = scored.slice(0, 50).map((s) => s.id);
+          cosine.set(l.id, dot);
+        }
         mode = "hybrid";
         reason = null;
       }
     }
   }
 
-  // (d) reciprocal rank fusion, 1/(60+rank) per side, rank starting at 1.
-  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)));
+  // card recall-fallback-warning: keyword-only is degraded when a provider was given, vectors exist for any
+  // model, or the caller detected a usable provider; hybrid reports how many live in-window rows lack a vector.
+  // The existence check is bounded and only runs when no other term already decided it.
+  const hasAnyVector = (db) =>
+    !!db.prepare("SELECT 1 AS x FROM lessons WHERE superseded_by IS NULL AND stale IS NULL AND embedding IS NOT NULL LIMIT 1").get();
+  const degraded = mode === "keyword-only" && (!!provider || hasAnyVector(m) || !!detectedProvider);
+  const coverage = {};
+  if (mode === "hybrid") {
+    coverage.total = freshRows.length;
+    coverage.unvectored = freshRows.filter(
+      (l) => !(hasVec(l) && l.embedding_model === provider.model && l.embedding_dims === provider.dims)
+    ).length;
+  }
 
-  // (e) recency weight, (f) scope boost.
-  const candidates = [];
-  for (const [id, rrfScore] of fused.entries()) {
-    const lesson = byId.get(id);
-    if (!lesson) continue;
+  // (d) scores: recency weight, then scope boost. Dense mode scores cosine; the BM25 order scores 1/(60+rank).
+  const bm25Rank = new Map(bm25Ranked.map((id, idx) => [id, idx]));
+  const weigh = (lesson, base) => {
     const ageDays = ageDaysOf(lesson.confirmed || lesson.created, nowMs);
-    const recency = 0.5 + 0.5 * Math.exp(-ageDays / 90);
-    let score = rrfScore * recency;
+    let score = base * (0.5 + 0.5 * Math.exp(-ageDays / 90));
     if (files.length && (lesson.scope.length === 0 || scopeMatchesFiles(lesson.scope, files))) score *= 1.5;
+    return score;
+  };
+  const byScoreThenId = (a, b) => b.score - a.score || (a.lesson.id < b.lesson.id ? -1 : a.lesson.id > b.lesson.id ? 1 : 0);
+  const sidesOf = (id) => {
     const sides = [];
-    if (bm25Ranked.includes(id)) sides.push("bm25");
-    if (vectorRanked.includes(id)) sides.push("vector");
-    candidates.push({ lesson, score, sides });
+    if (bm25Rank.has(id)) sides.push("bm25");
+    if (cosine.has(id)) sides.push("vector");
+    return sides;
+  };
+  let candidates;
+  if (mode === "hybrid") {
+    // (e) vectored lessons by cosine x recency x scope, then BM25 hits with no vector, in BM25 order.
+    const dense = [...cosine.entries()].map(([id, dot]) => {
+      const lesson = byId.get(id);
+      return { lesson, score: weigh(lesson, dot), sides: sidesOf(id) };
+    });
+    dense.sort(byScoreThenId);
+    const appended = bm25Ranked
+      .filter((id) => !cosine.has(id))
+      .map((id) => ({ lesson: byId.get(id), score: weigh(byId.get(id), 1 / (60 + bm25Rank.get(id) + 1)), sides: sidesOf(id) }));
+    candidates = [...dense, ...appended];
+  } else {
+    candidates = bm25Ranked.map((id) => ({ lesson: byId.get(id), score: weigh(byId.get(id), 1 / (60 + bm25Rank.get(id) + 1)), sides: sidesOf(id) }));
+    candidates.sort(byScoreThenId);
   }
-  candidates.sort((a, b) => b.score - a.score);
 
   // (g) top k. With a real project root, each candidate's citation is re-checked: a failure marks the row
   // stale and drops it, backfilling from the next candidate so k are returned when enough candidates exist,
   // and a pass sets confirmed. Without one (checked: false), candidates are taken as-is — nothing is marked
   // stale or confirmed, since there is nothing trustworthy to check them against.
+  // Every lessons column except the blob, derived from the live schema so a later column cannot drop out.
+  const loadCols = m
+    .prepare("PRAGMA table_info(lessons)")
+    .all()
+    .map((c) => c.name)
+    .filter((n) => n !== "embedding")
+    .join(", ");
+  const loadById = m.prepare(`SELECT ${loadCols}, embedding IS NOT NULL AS has_vec FROM lessons WHERE id = ?`);
   const result = [];
   let idx = 0;
   while (result.length < k && idx < candidates.length) {
     const cand = candidates[idx++];
+    // Every column except the blob (and the model/dims toRecallLesson strips anyway); hasVector comes from has_vec.
+    const { has_vec, ...full } = loadById.get(cand.lesson.id);
+    cand.lesson = lessonRowToObject({ ...full, embedding: has_vec ? true : null });
     if (!checked) {
       result.push(toRecallLesson(cand.lesson, { score: cand.score, sides: cand.sides }));
       continue;
@@ -894,7 +986,176 @@ export async function recallLessons(m, query, opts = {}) {
     result.push(toRecallLesson({ ...cand.lesson, confirmed: nowIsoStr }, { score: cand.score, sides: cand.sides }));
   }
 
-  return { mode, reason: mode === "hybrid" ? null : reason, provider: providerName, checked, lessons: result };
+  return { mode, reason: mode === "hybrid" ? null : reason, provider: providerName, checked, degraded, ...coverage, lessons: result };
+}
+
+// Renders recalled lessons as one line per lesson, in rank order. Each lesson's own text gets a fixed budget
+// (LESSON_CHAR_BUDGET): text over budget is cut at the last sentence boundary (". ", "! ", "? ", or a newline)
+// within it, falling back to the last word boundary, then a hard cut, with an ellipsis ("…") appended; the
+// citation (or kind, when there is none) stays on the line either way. A sentence/newline boundary this close
+// to the start (MIN_CUT_KEPT) keeps too little to be worth it — a lesson opening with a heading-then-newline,
+// or a stray early period, would otherwise collapse to almost nothing — so that case falls through to the word
+// boundary (then the hard cut) instead, same as when no such boundary exists at all. That keeps any one lesson
+// — the memory store holds whole files up to ~12k characters, not just short summaries — from ever crowding
+// out the rest: the running total is kept under LESSONS_CHAR_CAP by skipping (not stopping at) a line that
+// would overflow it, so a later, shorter lesson still renders even after an earlier one didn't fit. lessonIds
+// carries exactly the ids of the lines rendered. { text: null, ids: [] } when nothing rendered, the caller's
+// cue to omit the fields entirely.
+const LESSONS_CHAR_CAP = 2000;
+const LESSON_CHAR_BUDGET = 400;
+const MIN_CUT_KEPT = 40;
+function cutLessonText(text, budget) {
+  if (text.length <= budget) return text;
+  const slice = text.slice(0, budget);
+  let cut = -1;
+  for (const sep of [". ", "! ", "? "]) {
+    const idx = slice.lastIndexOf(sep);
+    if (idx !== -1) cut = Math.max(cut, idx + sep.length - 1);
+  }
+  const nl = slice.lastIndexOf("\n");
+  if (nl !== -1) cut = Math.max(cut, nl);
+  if (cut < MIN_CUT_KEPT) cut = -1;
+  if (cut === -1) {
+    const sp = slice.lastIndexOf(" ");
+    cut = sp !== -1 ? sp : budget;
+  }
+  return text.slice(0, cut).trimEnd() + "…";
+}
+export function renderLessons(lessons) {
+  const text = [];
+  const ids = [];
+  let length = 0;
+  for (const lesson of Array.isArray(lessons) ? lessons : []) {
+    const line = `- [${lesson.id}] ${cutLessonText(lesson.text, LESSON_CHAR_BUDGET)} (${lesson.citation || lesson.kind})`;
+    const nextLength = length + (text.length ? 1 : 0) + line.length;
+    if (nextLength > LESSONS_CHAR_CAP) continue;
+    text.push(line);
+    ids.push(lesson.id);
+    length = nextLength;
+  }
+  return text.length ? { text: text.join("\n"), ids } : { text: null, ids: [] };
+}
+
+// The lessons a session starts with when no card query exists (card memory-every-session): live, non-stale
+// lessons confirmed-or-created within staleDays, ordered by helpful minus harmful desc, then confirmed-or-created
+// desc, then id ascending. No provider, no citation re-check, nothing written.
+export function topLessons(m, { k = 5, staleDays = 30, now = new Date() } = {}) {
+  const nowMs = (now instanceof Date ? now : new Date(now)).getTime();
+  const rows = m
+    .prepare(
+      `SELECT id, text, kind, scope, citation, source_agent, source_model, task, card, commit_sha, created, confirmed,
+              helpful, harmful, superseded_by, stale
+       FROM lessons WHERE superseded_by IS NULL AND stale IS NULL`
+    )
+    .all()
+    .map(lessonRowToObject)
+    .filter((l) => ageDaysOf(l.confirmed || l.created, nowMs) <= staleDays);
+  const stamp = (l) => new Date(l.confirmed || l.created).getTime() || 0;
+  rows.sort((a, b) => b.helpful - b.harmful - (a.helpful - a.harmful) || stamp(b) - stamp(a) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return rows.slice(0, k);
+}
+
+// --- Degraded-recall warnings (card recall-fallback-warning) ------------------------------------------------
+// The one place that words a degraded recall, for memory.mjs recall / index search and plan.mjs json alike.
+// `result` is a recallLessons or searchIndex result; `what` is "memory recall" or "code index search"; `code`
+// picks the chunk wording and the `index build` fix. Returns the stderr line (no newline) or null.
+export function degradedWarning(result, { what = "memory recall", code = false, detectedProvider = null } = {}) {
+  const noun = code ? "chunks" : "lessons";
+  const rebuild = code ? "run memory.mjs index build" : "run memory.mjs reembed";
+  if (result.mode === "hybrid") {
+    if (result.unvectored > 0) return `WARNING: ${result.unvectored} of ${result.total} ${noun} have no vector; ${rebuild}`;
+    return null;
+  }
+  if (!result.degraded) return null;
+  const reason = result.reason;
+  let fix;
+  let shown = reason;
+  if (reason === "no provider configured") {
+    if (detectedProvider) {
+      shown = `no provider configured, but ${detectedProvider} is available`;
+      fix = "run memory.mjs doctor to enable it";
+    } else {
+      fix = "configure memory.embeddings (memory.mjs doctor)";
+    }
+  } else if (typeof reason === "string" && reason.startsWith("no vectors stored for ")) {
+    fix = rebuild;
+  } else if (reason === "timeout") {
+    fix = "run memory.mjs doctor (a cold model can time out on first use; retry)";
+  } else {
+    fix = "run memory.mjs doctor";
+  }
+  return `WARNING: ${what} degraded to keyword-only: ${shown}; ${fix}`;
+}
+
+// The reason shown in a task prompt block when a recall was degraded: the same wording as the warning's reason
+// part, including the detected-provider form.
+export function degradedReason(result, detectedProvider = null) {
+  if (result.reason === "no provider configured" && detectedProvider) return `no provider configured, but ${detectedProvider} is available`;
+  return result.reason;
+}
+
+// One probe for a usable local embedding provider, for a caller whose config has none. DOUG_OLLAMA_BASE_URL
+// overrides the default base URL (http://localhost:11434). Returns a short description ("ollama embeddinggemma
+// at <url>") or null: a failed or negative probe is "not detected", never an error. Ollama only, GET only:
+// /api/version then /api/tags under ONE shared 1500 ms deadline (never an embed call, never a POST). The model
+// name matching mirrors embeddings.mjs's modelNameMatches (exact, or the part before ":" on either side); that
+// helper is not exported and this card may not edit embeddings.mjs, so the rule is repeated here.
+export async function detectLocalProvider(opts = {}) {
+  try {
+    const baseUrl = process.env.DOUG_OLLAMA_BASE_URL || "http://localhost:11434";
+    const root = baseUrl.replace(/\/$/, "");
+    const want = "embeddinggemma";
+    const base = (n) => String(n ?? "").split(":")[0];
+    const signal = AbortSignal.timeout(opts.timeoutMs ?? 1500);
+    const get = opts.fetch ? (url) => fetchGet(opts.fetch, url, signal) : (url) => httpGet(url, signal);
+    const version = await get(`${root}/api/version`);
+    if (!version.ok) return null;
+    const tags = await get(`${root}/api/tags`);
+    if (!tags.ok) return null;
+    const json = JSON.parse(tags.body);
+    const models = Array.isArray(json && json.models) ? json.models : [];
+    const present = models.some((mo) => mo && [mo.name, mo.model].some((n) => n !== undefined && n !== null && (n === want || base(n) === want)));
+    return present ? `ollama ${want} at ${baseUrl}` : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchGet(fetchImpl, url, signal) {
+  const res = await fetchImpl(url, { signal, headers: { Connection: "close" } });
+  if (!res.ok) {
+    await res.body?.cancel?.().catch(() => {});
+    return { ok: false, body: "" };
+  }
+  return { ok: true, body: await res.text() };
+}
+
+// node:http rather than fetch: aborting a fetch whose TCP connect is still pending leaves the connect attempt
+// (and so the process) alive for ~10 s against an unroutable host; destroying a node:http request tears the
+// socket down at once, so the CLI exits right after the deadline.
+function httpGet(url, signal) {
+  return new Promise((resolveP, rejectP) => {
+    const mod = url.startsWith("https:") ? httpsRequest : httpRequest;
+    const req = mod(url, { method: "GET", headers: { Connection: "close" } }, (res) => {
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        res.destroy();
+        resolveP({ ok: false, body: "" });
+        return;
+      }
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolveP({ ok: true, body: Buffer.concat(chunks).toString("utf8") }));
+      res.on("error", rejectP);
+    });
+    const onAbort = () => {
+      req.destroy();
+      rejectP(new Error("timeout"));
+    };
+    if (signal.aborted) return onAbort();
+    signal.addEventListener("abort", onAbort, { once: true });
+    req.on("error", rejectP);
+    req.end();
+  });
 }
 
 function taskAdversary(task, level) {
@@ -1243,14 +1504,25 @@ function reflectionRowToObject(row) {
   };
 }
 
-// Deterministic, no LLM: for each task whose memoryUsed is non-empty, a real block bumps harmful on every used
-// lesson that exists (real wins even when the task also verified), else a first-verified task bumps helpful;
-// neither verified nor real does nothing. An id naming no lesson is reported in `unknown`, never an error.
-// apply:false (a dry run's preview) computes the same result without writing anything.
-function computeReflectCounters(m, blocks, report, { apply }) {
+// Deterministic, no LLM. harmful is an explicit mark (card reflect-harmful-irrelevant-lessons): only an id in
+// `harmfulIds` (the lead's judgement that the lesson misled the work) gets harmful +1, once however often it is
+// named or used; a real block alone bumps nothing. For each task whose memoryUsed is non-empty, a real block earns
+// no helpful (real wins even when the task also verified), else a first-verified task bumps helpful on every used
+// lesson not named harmful; neither verified nor real does nothing. An id naming no lesson is reported in
+// `unknown`, never an error. apply:false (a dry run's preview) computes the same result without writing anything.
+function computeReflectCounters(m, blocks, report, { apply, harmfulIds = [] }) {
   const helpful = [];
   const harmful = [];
   const unknown = [];
+  const named = new Set(harmfulIds);
+  for (const id of named) {
+    if (getLesson(m, id)) {
+      if (apply) m.prepare("UPDATE lessons SET harmful = harmful + 1 WHERE id = ?").run(id);
+      harmful.push(id);
+    } else {
+      unknown.push(id);
+    }
+  }
   for (const level of report.levels || []) {
     for (const task of level.tasks || []) {
       const used = Array.isArray(task.memoryUsed) ? task.memoryUsed : [];
@@ -1258,15 +1530,11 @@ function computeReflectCounters(m, blocks, report, { apply }) {
       const real = blocks.some((b) => b.task === task.id && b.class === "real");
       if (real) {
         for (const id of used) {
-          if (getLesson(m, id)) {
-            if (apply) m.prepare("UPDATE lessons SET harmful = harmful + 1 WHERE id = ?").run(id);
-            harmful.push(id);
-          } else {
-            unknown.push(id);
-          }
+          if (!getLesson(m, id) && !named.has(id)) unknown.push(id);
         }
       } else if (task.verified === true) {
         for (const id of used) {
+          if (named.has(id)) continue;
           if (getLesson(m, id)) {
             if (apply) m.prepare("UPDATE lessons SET helpful = helpful + 1 WHERE id = ?").run(id);
             helpful.push(id);
@@ -1343,9 +1611,41 @@ export function buildReflectPrompt(report, { blocks = [], plan = null, existingL
   } else {
     lines.push("(none yet)");
   }
+  if (report.hand && typeof report.hand === "object") appendHandMaterial(lines, report.hand);
   return lines.join("\n") + "\n";
 }
 
+// A hand landing's saved material (card memory-every-session): each file capped at HAND_FILE_CHAR_CAP, all of it at
+// HAND_TOTAL_CHAR_CAP, the landing note last so a budget spent on files still leaves the note.
+const HAND_FILE_CHAR_CAP = 4000;
+const HAND_TOTAL_CHAR_CAP = 16000;
+const HAND_TRUNCATED = "\u2026[truncated]";
+
+function appendHandMaterial(lines, hand) {
+  lines.push("");
+  lines.push("Hand-track material (briefs, reviewer reports, landing note; the rules above still apply, cite report:<card> or report:<card>/R<n>):");
+  const note = typeof hand.note === "string" && hand.note.trim() ? hand.note : null;
+  const cutNote = note && note.length > HAND_FILE_CHAR_CAP ? note.slice(0, HAND_FILE_CHAR_CAP) + HAND_TRUNCATED : note;
+  let budget = HAND_TOTAL_CHAR_CAP - (cutNote ? cutNote.length : 0);
+  const add = (label, files) => {
+    for (const f of Array.isArray(files) ? files : []) {
+      if (!f || typeof f.text !== "string") continue;
+      if (budget <= 0) break;
+      let text = f.text.length > HAND_FILE_CHAR_CAP ? f.text.slice(0, HAND_FILE_CHAR_CAP) + HAND_TRUNCATED : f.text;
+      if (text.length > budget) text = text.slice(0, budget) + HAND_TRUNCATED;
+      budget -= text.length;
+      lines.push(`--- ${label} ${f.name || ""} ---`);
+      lines.push(text);
+    }
+  };
+  add("brief", hand.briefs);
+  add("reviewer report", hand.reviews);
+  if (cutNote) {
+    lines.push("--- landing note ---");
+    lines.push(cutNote);
+  }
+}
+
 // Citation filter (C.2): a "report:" citation is checked against `report` (never unchecked here, unlike
 // checkCitation's default), a path:line citation against `dir` via checkCitation; anything else — free text, an
 // empty string, a report: citation shaped wrong — is rejected outright.
@@ -1465,7 +1765,7 @@ function computeReflectCost({ dir, claudeDir, sessionId, totalCostUsd }) {
     if (existsSync(file)) {
       try {
         const t = transcriptUsage(file);
-        const usd = t.model ? priceUsage(t.usage, t.model) : null;
+        const usd = t.usd;
         if (usd !== null) return { usd, usdSource: "transcript" };
       } catch {
         // fall through to the envelope's own number
@@ -1494,6 +1794,7 @@ export async function runReflect(m, report, opts = {}) {
     model = null,
     claudeDir,
     dryRun = false,
+    harmful = [],
     propose,
     now = nowIso(),
   } = opts;
@@ -1507,13 +1808,30 @@ export async function runReflect(m, report, opts = {}) {
   // happen before any write, so it is the very first thing after the idempotency check.
   const blocks = classifyBlocks(report, classes);
 
+  // A harmful id must be one a task recalled; refused before any write, naming it and the recalled ids.
+  const harmfulIds = [...new Set(harmful)];
+  if (harmfulIds.length) {
+    const recalled = new Set();
+    for (const level of report.levels || []) {
+      for (const task of level.tasks || []) {
+        if (Array.isArray(task.memoryUsed)) for (const id of task.memoryUsed) recalled.add(id);
+      }
+    }
+    const outside = harmfulIds.filter((id) => !recalled.has(id));
+    if (outside.length) {
+      throw new Error(
+        `--harmful id(s) not in any task's memoryUsed: ${outside.join(", ")}. memoryUsed ids: ${recalled.size ? [...recalled].join(", ") : "(none)"}.`
+      );
+    }
+  }
+
   let counters;
   if (dryRun) {
-    counters = computeReflectCounters(m, blocks, report, { apply: false });
+    counters = computeReflectCounters(m, blocks, report, { apply: false, harmfulIds });
   } else {
     m.exec("BEGIN");
     try {
-      counters = computeReflectCounters(m, blocks, report, { apply: true });
+      counters = computeReflectCounters(m, blocks, report, { apply: true, harmfulIds });
       m.prepare(
         `INSERT INTO reflections (report_hash, recorded, run, card, commit_sha, model, counters, proposed, appended, bumped, rejected, usd, usd_source, session_id)
          VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL)`

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

@@ -42,7 +42,8 @@ export function crewOf(plan, task) {
 // feature, never more than eight. The validator warns; it does not refuse, since the planner may have a reason.
 export const FEATURE_TASKS = 5;
 export const TASK_CAP = 8;
-export const DEFAULT_BUDGET = { agents: 12, tokens: 400000, wallMinutes: 40 };
+// agents 26 is the minimum that lets the default fixAttempts 5 run with one adversary seat when Codex is down and the Claude fallback runs on every pass (card flow-budget-after-parallel-adversary); a supervisor seat or a fix retry is not covered.
+export const DEFAULT_BUDGET = { agents: 26, tokens: 400000, wallMinutes: 40 };
 
 export function loadPlan(dir, relpath = PLAN_RELPATH) {
   const file = join(dir, relpath);
@@ -559,6 +560,15 @@ export function planWarnings(plan) {
   else if (n > FEATURE_TASKS) out.push(`${n} tasks: a feature is three to five; merge tasks that share a file group or split the plan`);
   const files = new Set(plan.tasks.flatMap((t) => (Array.isArray(t.files) ? t.files : [])));
   if (n > 1 && files.size === 1) out.push(`${n} tasks own the same single file (${[...files][0]}): single-file work is one task`);
+  const verifyOwners = [];
+  for (const v of Array.isArray(plan.verify) ? plan.verify : []) if (typeof v === "string" && v.trim()) verifyOwners.push([v.trim(), "plan.verify"]);
+  for (const t of plan.tasks) if (t && typeof t.verify === "string" && t.verify.trim()) verifyOwners.push([t.verify.trim(), `task ${t.id} verify`]);
+  for (const a of Array.isArray(plan.acceptance) ? plan.acceptance : []) {
+    if (!a || typeof a !== "object" || typeof a.command !== "string" || !a.command.trim()) continue;
+    const cmd = a.command.trim();
+    const hit = verifyOwners.find(([c]) => c === cmd);
+    if (hit) out.push(`acceptance "${a.text}" command \`${cmd}\` repeats a verify command (${hit[1]}): every verifier, integrate, and land already run it; name a narrower check or make it prose`);
+  }
   return out;
 }
 

package/node_modules/@dougharness/flow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougharness/flow",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "private": true,
   "description": "Plan, approve, implement one task per worktree, verify, review: a Workflow-tool template and subagents for Claude Code.",
   "type": "module",
@@ -9,6 +9,7 @@
     "agents",
     "skills",
     "workflows",
+    "hooks",
     "scripts",
     "lib",
     ".claude-plugin"