@dougharness/cli 1.1.0 → 1.2.0

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

@@ -3,12 +3,39 @@
 // /v1/embeddings endpoint (Ollama, llama-server, vLLM, LM Studio, a hosted OpenAI-shaped key) and Voyage AI's
 // own endpoint. Product first: memory.embeddings in .doug/config.json is null by default, and every function
 // here treats "no provider" or "provider unreachable" as a normal outcome, never a thrown error.
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { homedir } from "node:os";
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
 
 const CONFIG_RELPATH = ".doug/config.json";
 const VALID_PROVIDERS = new Set(["openai-compatible", "voyage"]);
+
+// The bundled local model (card memory-bundled-embedding, ADR 0006 amendment 2026-10-08): the runtime is
+// installed into a user-level cache and loaded by dynamic import, never a dependency of any Doug package.
+export const LOCAL_MODEL_ID = "onnx-community/embeddinggemma-300m-ONNX";
+export const LOCAL_DTYPE = "q8";
+export const LOCAL_RUNTIME_PACKAGE = "@huggingface/transformers@4.3.1";
+export const LOCAL_QUERY_PREFIX = "task: search result | query: ";
+export const LOCAL_DOCUMENT_PREFIX = "title: none | text: ";
+const LOCAL_DIMS = 512;
+
+export function localCacheDir(env = process.env, home = homedir()) {
+  if (env.DOUG_CACHE_DIR) return env.DOUG_CACHE_DIR;
+  return join(env.XDG_CACHE_HOME || join(home, ".cache"), "doug");
+}
+
+export function localPaths(cacheDir) {
+  const modelsDir = join(cacheDir, "models");
+  return {
+    cacheDir,
+    runtimeDir: join(cacheDir, "runtime"),
+    modelsDir,
+    modelFile: join(modelsDir, "onnx-community", "embeddinggemma-300m-ONNX", "onnx", "model_quantized.onnx"),
+  };
+}
 const DEFAULT_TIMEOUT_MS = 2000;
 const OLLAMA_BASE_URL = "http://localhost:11434";
 const DEFAULT_MODEL = "embeddinggemma";
@@ -21,6 +48,7 @@ const PRESETS = {
   unsloth: { provider: "openai-compatible", baseUrl: "http://127.0.0.1:8888", apiKeyEnv: "UNSLOTH_API_KEY", sendsDims: false, requiresKey: true, modelsList: "v1" },
   openai: { provider: "openai-compatible", baseUrl: "https://api.openai.com", apiKeyEnv: "OPENAI_API_KEY", sendsDims: true, requiresKey: true, modelsList: "v1" },
   voyage: { provider: "voyage", baseUrl: "https://api.voyageai.com", apiKeyEnv: "VOYAGE_API_KEY", sendsDims: true, requiresKey: true, modelsList: null },
+  local: { provider: "local", baseUrl: undefined, apiKeyEnv: undefined, sendsDims: false, requiresKey: false, modelsList: null },
   custom: { provider: undefined, baseUrl: undefined, apiKeyEnv: undefined, sendsDims: true, requiresKey: false, modelsList: null },
 };
 
@@ -60,7 +88,8 @@ export function readMemoryConfig(dir) {
   const e = memory && typeof memory === "object" ? memory.embeddings : undefined;
   if (e === null || e === undefined) return { embeddings: null };
   const resolved = applyPreset(e);
-  if (!isValidEmbeddingsConfig(resolved)) {
+  const isLocal = e.preset === "local";
+  if (isLocal ? !isValidLocalConfig(resolved) : !isValidEmbeddingsConfig(resolved)) {
     process.stderr.write(`[doug] ${CONFIG_RELPATH} memory.embeddings is not a valid shape; treating as unset (keyword-only)\n`);
     return { embeddings: null };
   }
@@ -80,9 +109,18 @@ function applyPreset(e) {
   for (const k of ["provider", "baseUrl", "apiKeyEnv"]) {
     if (out[k] === undefined && p[k] !== undefined) out[k] = p[k];
   }
+  if (e.preset === "local") {
+    if (out.model === undefined) out.model = LOCAL_MODEL_ID;
+    if (out.dims === undefined) out.dims = LOCAL_DIMS;
+  }
   return out;
 }
 
+// The local runtime runs one model at one width: a config that names anything else is invalid.
+function isValidLocalConfig(r) {
+  return !!(r && r.provider === "local" && r.model === LOCAL_MODEL_ID && r.dims === LOCAL_DIMS);
+}
+
 function isValidIndexConfig(idx) {
   return !!(
     idx &&
@@ -264,7 +302,9 @@ export async function checkEmbeddingSanity(provider, pairs) {
 
 // Task prefixes the provider layer must add; the server never adds them. Only the models below carry a
 // prefix; every other model gets none. mxbai and qwen3 prefix queries only, documents get "".
-function prefixFor(model, inputType) {
+export const PREFIXED_MODELS = ["embeddinggemma", "nomic-embed-text", "mxbai-embed-large", "qwen3-embedding"];
+
+export function prefixFor(model, inputType) {
   // Match on the lowercased basename after the last "/", so HF-style names (org/name) and Ollama names agree.
   let m = String(model || "").split(/[/\\]/).pop().toLowerCase();
   // LM Studio-style "text-embedding-<name>" ids: match on <name> when it is a prefixed family (not OpenAI's text-embedding-3-*).
@@ -450,11 +490,96 @@ async function embedBatched(texts, inputType, sendBatch) {
   return { ok: true, vectors };
 }
 
+async function defaultLoadTransformers(runtimeDir) {
+  const req = createRequire(join(runtimeDir, "noop.js"));
+  return import(pathToFileURL(req.resolve("@huggingface/transformers")).href);
+}
+
+// The in-process provider: the transformers module comes from opts.loadTransformers (the test seam) or the
+// runtime dir under the cache. Loads lazily on the first embed and keeps the model for the provider's life.
+// Recall never reaches the network (allowRemoteModels false); only setup's download passes allowRemote.
+function createLocalProvider(e, opts) {
+  const paths = localPaths(opts.cacheDir ?? localCacheDir());
+  const loadTransformers = opts.loadTransformers ?? (() => defaultLoadTransformers(paths.runtimeDir));
+  let loaded = null;
+  const load = async () => {
+    if (loaded) return loaded;
+    let mod;
+    try {
+      mod = await loadTransformers();
+    } catch {
+      return { failure: { ok: false, reason: `local embedding runtime not installed at ${paths.runtimeDir}: run doug memory setup` } };
+    }
+    mod.env.cacheDir = paths.modelsDir;
+    mod.env.allowRemoteModels = opts.allowRemote === true;
+    const tokenizer = await mod.AutoTokenizer.from_pretrained(LOCAL_MODEL_ID);
+    const model = await mod.AutoModel.from_pretrained(LOCAL_MODEL_ID, { dtype: LOCAL_DTYPE });
+    loaded = { tokenizer, model };
+    return loaded;
+  };
+  const sendBatch = async (texts, inputType) => {
+    const l = await load();
+    if (l.failure) return l.failure;
+    const prefix = inputType === "query" ? LOCAL_QUERY_PREFIX : LOCAL_DOCUMENT_PREFIX;
+    const inputs = l.tokenizer(texts.map((t) => prefix + t), { padding: true, truncation: true });
+    const { sentence_embedding } = await l.model(inputs);
+    const vectors = [];
+    for (const row of sentence_embedding.tolist()) {
+      if (row.length < LOCAL_DIMS) return { ok: false, reason: `wrong dims: got ${row.length}, expected ${LOCAL_DIMS}` };
+      vectors.push(l2normalize(Float32Array.from(row.slice(0, LOCAL_DIMS))));
+    }
+    return { ok: true, vectors };
+  };
+  return {
+    name: "local",
+    model: LOCAL_MODEL_ID,
+    dims: LOCAL_DIMS,
+    async embed(texts, { inputType = "document" } = {}) {
+      try {
+        return await embedBatched(texts, inputType, sendBatch);
+      } catch (err) {
+        return { ok: false, reason: `local embedding failed: ${err.message}` };
+      }
+    },
+  };
+}
+
+const LOCAL_CONFIG = { embeddings: { preset: "local", provider: "local", model: LOCAL_MODEL_ID, dims: LOCAL_DIMS } };
+
+// Installs the pinned runtime into <cacheDir>/runtime with the npm CLI, CPU only (the CUDA download is skipped on
+// every platform). Never throws.
+export function installLocalRuntime({ cacheDir, spawnImpl = spawn, platform = process.platform } = {}) {
+  return new Promise((resolve) => {
+    try {
+      const { runtimeDir } = localPaths(cacheDir ?? localCacheDir());
+      mkdirSync(runtimeDir, { recursive: true });
+      const child = spawnImpl(
+        platform === "win32" ? "npm.cmd" : "npm",
+        ["install", "--prefix", runtimeDir, "--no-audit", "--no-fund", LOCAL_RUNTIME_PACKAGE],
+        { stdio: "inherit", env: { ...process.env, ONNXRUNTIME_NODE_INSTALL: "skip" } },
+      );
+      child.on("error", (err) => resolve({ ok: false, reason: `npm install failed to start: ${err.message}` }));
+      child.on("close", (code) => resolve(code === 0 ? { ok: true } : { ok: false, reason: `npm install exited with code ${code}` }));
+    } catch (err) {
+      resolve({ ok: false, reason: `npm install failed: ${err.message}` });
+    }
+  });
+}
+
+// One document embed with remote models allowed: from_pretrained downloads the tokenizer and q8 model into the
+// models dir. Never throws.
+export async function downloadLocalModel({ cacheDir, loadTransformers } = {}) {
+  const provider = createProvider(LOCAL_CONFIG, { cacheDir, loadTransformers, allowRemote: true });
+  const r = await provider.embed(["probe"], { inputType: "document" });
+  return r.ok ? { ok: true } : { ok: false, reason: r.reason };
+}
+
 // cfg is the { embeddings } shape readMemoryConfig returns. Returns null when nothing is configured (the
 // caller's cue to run keyword-only); otherwise { name, model, dims, embed(texts, { inputType }) }.
 export function createProvider(cfg, opts = {}) {
   const e = cfg && cfg.embeddings;
   if (!e) return null;
+  if (e.provider === "local") return createLocalProvider(e, opts);
   const fetchImpl = opts.fetch || globalThis.fetch;
   const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const state = { omitDims: false };
@@ -567,6 +692,14 @@ export async function probeProvider(cfg, opts = {}) {
   const baseUrl = e && e.baseUrl ? e.baseUrl : process.env.DOUG_OLLAMA_BASE_URL || OLLAMA_BASE_URL;
   const wantModel = e && e.model ? e.model : DEFAULT_MODEL;
   const root = baseUrl.replace(/\/$/, "");
+  if (e && e.provider === "local") {
+    const { cacheDir, modelFile } = localPaths(opts.cacheDir ?? localCacheDir());
+    const modelPresent = existsSync(modelFile);
+    const base = { kind: "local", cacheDir, modelFile, modelPresent };
+    if (!modelPresent) return { ...base, reachable: false, embedOk: false, reason: "model file missing" };
+    const result = await createProvider(cfg, { cacheDir, loadTransformers: opts.loadTransformers }).embed(["probe"]);
+    return { ...base, reachable: result.ok, embedOk: result.ok, reason: result.ok ? null : result.reason };
+  }
   const preset = presetOf(e);
   if (preset && preset.modelsList === "v1") return probeV1Models(e, root, wantModel, { fetchImpl, timeoutMs });
   if (preset && e.provider === "voyage") {
@@ -673,6 +806,16 @@ export function doctorReport(cfg, probe, platform = process.platform) {
     return lines.join("\n");
   }
 
+  if (embeddings.provider === "local") {
+    lines.push(`memory.embeddings is configured: local ${embeddings.model}/${embeddings.dims} (bundled, in-process).`);
+    lines.push(`Cache: ${probe.cacheDir}`);
+    lines.push(`Model file: ${probe.modelFile} (${probe.modelPresent ? "present" : "missing"})`);
+    lines.push(`Dims: ${embeddings.dims}`);
+    if (!probe.modelPresent) lines.push("Run doug memory setup to install it.");
+    else if (probe.embedOk) lines.push("Test embed: ok");
+    else lines.push(`Test embed failed: ${probe.reason || "unknown error"}`);
+    return lines.join("\n");
+  }
   lines.push(`memory.embeddings is configured: ${embeddings.provider} ${embeddings.model}/${embeddings.dims} at ${embeddings.baseUrl}.`);
   if (presetOf(embeddings) && PRESETS[embeddings.preset].modelsList === "v1") {
     if (!probe.reachable) lines.push(`Not reachable: ${probe.reason || "unknown error"}.`);

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

@@ -22,7 +22,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { acceptanceEntries, integrationBranchFor, savePlan } from "./plan.mjs";
+import { acceptanceEntries, integrationBranchFor, integrationWorktreeFor, savePlan, PLAN_RELPATH } from "./plan.mjs";
 import { removeFinishedWorktrees } from "./worktrees.mjs";
 
 export const INTEGRATION_WORKTREE = ".claude/worktrees/doug-integration";
@@ -90,10 +90,15 @@ function run(command, cwd, timeoutMs) {
 // the MAIN checkout (--record-dir). Returns the entries land records under `verify` (command, ok, status, timedOut,
 // durationMs, outputTail, plus credited: "verified-tree" when credited), stopping at the first failure like
 // today's loop, or null when the output cannot be read (the caller then runs the loop unchanged).
+// verify.mjs may wait timeoutMs x n on a held gate.lock and then run n commands of timeoutMs each.
+export function vendoredVerifySpawnTimeoutMs(timeoutMs, n) {
+  return 2 * timeoutMs * n + 60000;
+}
+
 function verifyViaVendored(script, dir, work, commands, timeoutMs) {
   try {
     const args = [script, "--json", "--by", "land", "--cwd", work, "--record-dir", dir, "--timeout-ms", String(timeoutMs), ...commands.flatMap((c) => ["--command", c])];
-    const r = spawnSync(process.execPath, args, { cwd: work, encoding: "utf8", timeout: timeoutMs * commands.length + 60000, maxBuffer: 64 * 1024 * 1024, env: commandEnv() });
+    const r = spawnSync(process.execPath, args, { cwd: work, encoding: "utf8", timeout: vendoredVerifySpawnTimeoutMs(timeoutMs, commands.length), maxBuffer: 64 * 1024 * 1024, env: commandEnv() });
     let out = null;
     try {
       out = JSON.parse(String(r.stdout || "").trim().split("\n").pop());
@@ -104,7 +109,7 @@ function verifyViaVendored(script, dir, work, commands, timeoutMs) {
       const why = r.error && r.error.code === "ETIMEDOUT" ? "timed out" : "gave no readable result";
       return { error: `the vendored verify.mjs ${why}; land does not re-run the commands` };
     }
-    return out.results.map((x) => ({
+    const rows = out.results.map((x) => ({
       command: x.command,
       ok: x.ok === true,
       status: x.status,
@@ -113,13 +118,20 @@ function verifyViaVendored(script, dir, work, commands, timeoutMs) {
       outputTail: x.outputTail || "",
       ...(out.credited ? { credited: out.credited } : {}),
     }));
+    if (typeof out.lockWaitMs === "number") rows.lockWaitMs = out.lockWaitMs;
+    return rows;
   } catch (err) {
     return { error: `the vendored verify.mjs could not run: ${err && err.message}` };
   }
 }
 
 // Returns { ok: true, base, branch, mergeCommit, verify } or { ok: false, reason, verify? }. Never throws on a refusal.
-export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date(), deleteBranches = false } = {}) {
+// Card parallel-card-queens B5: rebase (set by plan.mjs land --card) rebases the integration branch onto the base
+// when the base has moved, in the worktree that has the branch checked out, and verifies the rebased tree; a
+// conflict is aborted and refused as "rebase-conflict: <files>". ownOnly removes only this plan's own task
+// branches' worktrees and its own integration worktree (no sweep of worktrees merged into base). planRelpath is
+// where plan.landed is saved (the per-card plan under --card). The result carries lockWaitMs from verify.mjs.
+export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date(), deleteBranches = false, rebase = false, ownOnly = false, planRelpath = PLAN_RELPATH } = {}) {
   if (!plan) return { ok: false, reason: "no plan" };
   if (plan.status !== "done") return { ok: false, reason: `plan status is "${plan.status}", not "done"; run plan.mjs done after a green doug-implement run` };
   if (plan.landed) return { ok: false, reason: `plan was already landed as ${plan.landed.mergeCommit} on ${plan.landed.at}` };
@@ -147,15 +159,17 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
   if (dirty.length) return { ok: false, reason: `tracked files are modified: ${dirty.join(", ")}; commit or stash them first` };
 
   // Verify on the branch itself, in the integration worktree if the workflow left it, else a temporary one.
-  const existing = join(dir, INTEGRATION_WORKTREE);
+  const existing = join(dir, integrationWorktreeFor(plan));
   const reuse = existsSync(existing) && tryGit(existing, ["symbolic-ref", "--short", "-q", "HEAD"]) === branch;
   let work = reuse ? existing : null;
   let temp = null;
+  const needsRebase = rebase && tryGit(dir, ["merge-base", "--is-ancestor", base, branch]) === null;
   if (!work) {
     temp = mkdtempSync(join(tmpdir(), "doug-land-"));
     work = join(temp, "wt");
     try {
-      git(dir, ["worktree", "add", "--detach", work, branch]);
+      // A rebase moves the branch ref, so the temporary worktree then has the branch itself checked out.
+      git(dir, needsRebase ? ["worktree", "add", work, branch] : ["worktree", "add", "--detach", work, branch]);
     } catch (err) {
       rmSync(temp, { recursive: true, force: true });
       return { ok: false, reason: `could not create a worktree for ${branch}: ${tail(err.stderr || err.message, 3)}` };
@@ -163,7 +177,16 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
   }
   const verify = [];
   const acceptance = [];
+  let lockWaitMs;
   try {
+    if (needsRebase) {
+      const rb = tryGitCapture(work, ["rebase", base]);
+      if (!rb.ok) {
+        const files = (tryGit(work, ["diff", "--name-only", "--diff-filter=U"]) || "").split("\n").filter(Boolean);
+        tryGit(work, ["rebase", "--abort"]);
+        return { ok: false, reason: `rebase-conflict: ${files.length ? files.join(", ") : tail(rb.error.stderr || rb.error.message, 3)}` };
+      }
+    }
     // card verified-tree-record: install always runs through run(). plan.verify goes through the vendored
     // verify.mjs when the project has one (it credits a verified-tree record of the branch's tree and writes one
     // for the main checkout after a green run); otherwise, or when it cannot be read, today's loop runs.
@@ -184,6 +207,7 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
       return { ok: false, reason: `verify failed on ${branch}: ${viaVerify.error}`, verify, acceptance: [] };
     }
     if (viaVerify) {
+      if (typeof viaVerify.lockWaitMs === "number") lockWaitMs = viaVerify.lockWaitMs;
       for (const r of viaVerify) {
         verify.push(r);
         if (!r.ok) return failVerify(r);
@@ -244,7 +268,7 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
     removedWorktrees.push(existingReal);
   }
   const taskBranches = (plan.tasks || []).flatMap((t) => [`doug/task-${t.id}`, ...(typeof t.reuse === "string" ? [t.reuse] : [])]);
-  const wtResult = removeFinishedWorktrees(dir, { branches: taskBranches, mergedInto: base });
+  const wtResult = removeFinishedWorktrees(dir, { branches: taskBranches, mergedInto: ownOnly ? null : base });
   const worktrees = { removed: [...removedWorktrees, ...wtResult.removed], kept: wtResult.kept };
 
   const branchesResult = { deleted: [], kept: [] };
@@ -273,6 +297,6 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
     verify: verify.map((v) => ({ command: v.command, ok: v.ok, durationMs: v.durationMs, ...(v.credited ? { credited: v.credited } : {}) })),
     acceptance: acceptance.map((a) => ({ text: a.text, command: a.command, ok: a.ok, durationMs: a.durationMs, ...(a.reused ? { reused: a.reused } : {}) })),
   };
-  savePlan(dir, { ...plan, landed });
-  return { ok: true, base, branch, mergeCommit, verify, acceptance, worktrees, branches: branchesResult };
+  savePlan(dir, { ...plan, landed }, planRelpath);
+  return { ok: true, base, branch, mergeCommit, verify, acceptance, worktrees, branches: branchesResult, ...(lockWaitMs !== undefined ? { lockWaitMs } : {}) };
 }

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

@@ -18,7 +18,7 @@ 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;
@@ -55,7 +55,8 @@ const LESSON_KINDS = ["feedback", "project", "pitfall", "pattern"];
 // row. On a hand row the following columns are NULL because they do not exist on that track — never because
 // they measured zero: run_id, spec_hash, files, size, shape, models, implemented, verified, reviewed,
 // review_issues, review_issue_count, adversary_verdict, adversary_blocked, adversary_source, blocks, passes,
-// fix_passes, stop_reason, in_scope, budget_spent, tokens, usd, codex_usd, report_hash, report_path, partial. In particular
+// fix_passes, stop_reason, stop_class, in_scope, budget_spent, tokens, codex_usd, report_hash, report_path, partial (usd too,
+// except that a hand landing recorded with --cost carries its measured session cost there; card usd-budget-size-class). In particular
 // verified is null on a hand row even though the gate passed: no independent verifier ran on that track, and
 // the gate's own text lives in the `gate` column instead. A consumer that averages fix_passes or counts
 // blocks across both tracks must filter on track. wall_clock, gate, and note only exist on a hand row; they
@@ -108,6 +109,7 @@ const OUTCOMES_COLUMNS_SQL = `
   tokens TEXT,
   usd REAL,
   codex_usd REAL,
+  stop_class TEXT,
   commit_sha TEXT,
   track TEXT NOT NULL DEFAULT 'flow',
   wall_clock TEXT,
@@ -399,6 +401,27 @@ function migrateV7ToV8(db) {
   }
 }
 
+// v8 had no stop_class column on outcomes (card memory-stop-class): the typed cause of a stop, from
+// task.stopClass, so stops can be counted by cause across runs. Additive like v7->v8: one guarded ALTER, then
+// the version bump; old rows stay null. OUTCOMES_COLUMNS_SQL carries stop_class for a v1 store's rebuild, so
+// this step is a no-op there instead of a duplicate-column error.
+const V9_STOP_COLUMNS = [["stop_class", "TEXT"]];
+
+function migrateV8ToV9(db) {
+  db.exec("BEGIN");
+  try {
+    const cols = db.prepare("PRAGMA table_info(outcomes)").all().map((c) => c.name);
+    for (const [name, type] of V9_STOP_COLUMNS) {
+      if (!cols.includes(name)) db.exec(`ALTER TABLE outcomes ADD COLUMN ${name} ${type};`);
+    }
+    db.exec("PRAGMA user_version = 9");
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
 export function openMemory(dir) {
   const file = memoryPath(dir);
   mkdirSync(dirname(file), { recursive: true });
@@ -407,7 +430,7 @@ export function openMemory(dir) {
   const version = db.prepare("PRAGMA user_version").get().user_version;
   if (version === 0) {
     db.exec(SCHEMA_SQL);
-    db.exec("PRAGMA user_version = 8");
+    db.exec("PRAGMA user_version = 9");
   } else if (version === 1) {
     migrateV1ToV2(db);
     migrateV2ToV3(db);
@@ -416,6 +439,7 @@ export function openMemory(dir) {
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 2) {
     migrateV2ToV3(db);
     migrateV3ToV4(db);
@@ -423,29 +447,37 @@ export function openMemory(dir) {
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 3) {
     migrateV3ToV4(db);
     migrateV4ToV5(db);
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 4) {
     migrateV4ToV5(db);
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 5) {
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 6) {
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 7) {
     migrateV7ToV8(db);
-  } else if (version !== 8) {
+    migrateV8ToV9(db);
+  } else if (version === 8) {
+    migrateV8ToV9(db);
+  } else if (version !== 9) {
     db.close();
-    throw new Error(`memory store ${file} is user_version ${version}; this code understands up to version 8`);
+    throw new Error(`memory store ${file} is user_version ${version}; this code understands up to version 9`);
   }
   return {
     file,
@@ -479,7 +511,7 @@ export function probeSqliteFts5() {
 // 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 };
+  const out = { file, exists: false, userVersion: null, maxUserVersion: 9, quickCheck: null, error: null };
   if (!existsSync(file)) return out;
   out.exists = true;
   let db;
@@ -719,7 +751,7 @@ export function checkCitation(lesson, checkoutDir, { report } = {}) {
     }
     const taskId = rest.slice(0, slash);
     const blockId = rest.slice(slash + 1);
-    const found = adversaryBlocks(report).some((b) => b.task === taskId && b.id === blockId);
+    const found = adversaryBlocks(report).some((b) => b.task === taskId && (b.id === blockId || b.id === `${taskId}/${blockId}`));
     return found ? { ok: true, reason: "block holds" } : { ok: false, reason: `no block "${blockId}" of task "${taskId}" in this report` };
   }
   const match = citation.match(CITATION_RE);
@@ -958,18 +990,20 @@ export async function recallLessons(m, query, opts = {}) {
   // 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 } = m
-      .prepare(
-        `SELECT id, text, kind, scope, citation, source_agent, source_model, task, card, commit_sha, created, confirmed,
-                helpful, harmful, superseded_by, embedding_model, embedding_dims, stale, embedding IS NOT NULL AS has_vec
-         FROM lessons WHERE id = ?`
-      )
-      .get(cand.lesson.id);
+    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 }));
@@ -1257,6 +1291,7 @@ export function outcomeRows(report, opts) {
         passes,
         fix_passes: fixPasses,
         stop_reason: task.stopReason ?? null,
+        stop_class: task.stopClass ?? null,
         in_scope: toIntOrNull(task.inScope),
         budget_spent: (task.budget && task.budget.spent) || null,
         tokens,
@@ -1327,7 +1362,7 @@ export function conditionConfigHash(dir) {
 // null when none was found: null fills every one of the seven condition columns with null, exactly like a row
 // that has never been stamped. `backfilled` is always 0 here — only `memory.mjs condition backfill`, which never
 // goes through this function, ever sets it to 1.
-export function handOutcomeRow({ card, commit, wallClock = null, gate = null, note = null, now = nowIso(), condition = null } = {}) {
+export function handOutcomeRow({ card, commit, wallClock = null, gate = null, note = null, now = nowIso(), condition = null, cost = null } = {}) {
   if (!card) throw new Error("handOutcomeRow requires card");
   if (!commit) throw new Error("handOutcomeRow requires commit");
   return {
@@ -1355,10 +1390,11 @@ export function handOutcomeRow({ card, commit, wallClock = null, gate = null, no
     passes: null,
     fix_passes: null,
     stop_reason: null,
+    stop_class: null,
     in_scope: null,
     budget_spent: null,
     tokens: null,
-    usd: null,
+    usd: typeof cost === "number" && Number.isFinite(cost) ? cost : null,
     codex_usd: null,
     commit_sha: commit,
     track: "hand",
@@ -1379,7 +1415,7 @@ export function handOutcomeRow({ card, commit, wallClock = null, gate = null, no
 const OUTCOME_COLUMNS = [
   "recorded", "run", "run_id", "report_hash", "report_path", "card", "task", "spec_hash", "files", "size", "shape",
   "models", "implemented", "verified", "reviewed", "review_issues", "review_issue_count", "adversary_verdict",
-  "adversary_blocked", "adversary_source", "blocks", "passes", "fix_passes", "stop_reason", "in_scope",
+  "adversary_blocked", "adversary_source", "blocks", "passes", "fix_passes", "stop_reason", "stop_class", "in_scope",
   "budget_spent", "tokens", "usd", "codex_usd", "commit_sha", "track", "wall_clock", "gate", "note", "partial",
   "harness_commit", "config_hash", "class", "arm", "assigned_by", "explore_probability", "backfilled",
 ];
@@ -1502,30 +1538,39 @@ 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; except on the hand track, whose reviewer blocks never withhold it), 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 : [];
       if (!used.length) continue;
-      const real = blocks.some((b) => b.task === task.id && b.class === "real");
+      // A hand report's blocks are reviewer blockers a later round fixed (card reflect-review-key-text): they are no
+      // evidence the lesson misled, so they never withhold helpful; only --harmful marks that.
+      const real = report.track !== "hand" && 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);
@@ -1586,7 +1631,7 @@ export function buildReflectPrompt(report, { blocks = [], plan = null, existingL
       if (Array.isArray(task.verifierFindings) && task.verifierFindings.length) lines.push(`  verifier findings: ${JSON.stringify(task.verifierFindings)}`);
       if (taskBlocks.length) {
         lines.push("  blocks:");
-        for (const b of taskBlocks) lines.push(`    - report:${task.id}/${b.id} class=${b.class || "unclassified"} reason=${b.reason || "none"}`);
+        for (const b of taskBlocks) lines.push(`    - report:${b.id.startsWith(`${task.id}/`) ? b.id : `${task.id}/${b.id}`} class=${b.class || "unclassified"} reason=${b.reason || "none"}`);
       }
       lines.push(`  memoryUsed: ${used.length ? used.join(", ") : "none"}`);
     }
@@ -1756,7 +1801,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
@@ -1785,6 +1830,7 @@ export async function runReflect(m, report, opts = {}) {
     model = null,
     claudeDir,
     dryRun = false,
+    harmful = [],
     propose,
     now = nowIso(),
   } = opts;
@@ -1798,13 +1844,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)`