@dougharness/cli 1.0.2 → 1.1.1

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

@@ -60,20 +60,33 @@
 //   memory.mjs lesson unstale <id> [dir] [--json]
 //                                                 clear a lesson's stale mark (set by recall's citation
 //                                                 re-check) so it is a candidate again; refuses on an unknown id
+//   memory.mjs brief-lessons <card-id> [dir] [--k <n>] [--json]
+//                                                 (card memory-every-session) recall for a hand-track card's
+//                                                 briefs: query = the card's title and goal, k 8. Prints the
+//                                                 workflow's lessons header, the rendered `- [id] ...` lines
+//                                                 (capped at 2000 chars like plan.mjs), then `memoryUsed: <ids>`;
+//                                                 writes .doug/.state/reports/<card-id>/lessons.json. No database
+//                                                 -> "No lessons recalled for <id>." (database not created);
+//                                                 a database or provider error -> one stderr line, exit 0;
+//                                                 unknown card -> exit 1
 //   memory.mjs recall <query> [dir] [--files <glob,glob>] [--k <n>] [--json]
-//                                                 hybrid recall (card memory-recall): BM25 over FTS5 fused by
-//                                                 reciprocal rank fusion with cosine over stored vectors when a
-//                                                 provider is configured and vectors exist for it, recency-
-//                                                 weighted, scope-boosted by --files, each returned lesson's
-//                                                 citation re-checked against [dir] only when [dir] is a real
-//                                                 project root (contains .doug); keyword-only, and says so, when
-//                                                 no provider is configured or no vectors match it
+//                                                 dense recall (card memory-recall): with a provider and
+//                                                 stored vectors, every live lesson is ranked by cosine x
+//                                                 recency weight x scope boost (--files), ties by lesson id,
+//                                                 then BM25 hits with no vector are appended in BM25 order;
+//                                                 without a provider or vectors the ranking is BM25 x recency
+//                                                 x scope, a keyword-only fallback that says so. Each returned
+//                                                 lesson's citation is re-checked against [dir] only when
+//                                                 [dir] is a real project root (contains .doug)
 //   memory.mjs reflect <report.json> [dir] [--run <wf-id>] [--card <id>] [--commit <sha>]
-//                       [--adversary "<id>=<class>[: <reason>]"]... [--claude-bin <path>] [--claude-dir <path>]
+//                       [--adversary "<id>=<class>[: <reason>]"]... [--harmful <id>]... [--claude-bin <path>] [--claude-dir <path>]
 //                       [--model <name>] [--max-usd <n>] [--dry-run] [--json]
 //                                                 runs after record: applies deterministic helpful/harmful
 //                                                 counters to lessons named in each task's memoryUsed (committed
-//                                                 even if the LLM pass below fails), then a cheap-row `claude -p
+//                                                 even if the LLM pass below fails; a real block alone bumps no
+//                                                 harmful: each --harmful <id>, a recalled lesson that misled the
+//                                                 work, gets harmful +1 and no helpful; an id outside every
+//                                                 task's memoryUsed exits 1 before any write), then a cheap-row `claude -p
 //                                                 --json-schema` pass proposes at most 3 lessons from the report,
 //                                                 filtered in code (a pitfall needs a block classed real, a
 //                                                 pattern needs a first-pass verified task, the citation must be
@@ -82,10 +95,17 @@
 //                                                 helpful instead of appending); idempotent on the report's
 //                                                 sha256 (a second reflect on the same report is a no-op, exit
 //                                                 0); --dry-run applies nothing but still runs the LLM pass and
-//                                                 prints what would happen; --hand is refused, since a hand
-//                                                 landing has no report. Cost is measured from the same local
+//                                                 prints what would happen. Cost is measured from the same local
 //                                                 transcripts cost.mjs reads, falling back to the CLI's own
 //                                                 cost estimate. Needs Node >=22.16 (node:sqlite).
+//   memory.mjs reflect --hand <card-id> [dir] --commit <sha> [--rounds <n>] [--review "R1=<class>[: <reason>]"]...
+//                       [--harmful <id>]... [--note <text>] [--claude-bin <path>] [--model <name>] [--max-usd <n>] [--dry-run] [--json]
+//                                                 (card memory-every-session) the same pass for a hand landing:
+//                                                 assembles .doug/.state/reports/<card-id>/hand-report.json from
+//                                                 the saved briefs/, reviews/ and lessons.json (memoryUsed = its
+//                                                 ids; verified true; passes = --rounds, default 1; one fixed
+//                                                 blocker ledger entry per --review id), then reflects on it
+//                                                 exactly as above. --commit is required (exit 2). No schema change.
 //   memory.mjs doctor [dir] [--json]
 //                                                 probe the configured embedding provider (memory.embeddings in
 //                                                 .doug/config.json), or a local Ollama at localhost:11434 when
@@ -165,7 +185,7 @@
 // lesson add and import embed only the row(s) they just wrote, best-effort, when a provider is configured: a
 // provider failure prints one stderr line and never turns into a nonzero exit for that add/import. A pending
 // row from an earlier add is left alone until `reembed` (or a later add/import) picks it up.
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
@@ -187,7 +207,7 @@ import {
 
 const argv = process.argv.slice(2);
 const FLAGS = new Set(["json", "all", "hand", "dry-run", "check", "no-check"]);
-const REPEATABLE = new Set(["adversary"]);
+const REPEATABLE = new Set(["adversary", "review", "harmful"]);
 const opts = {};
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
@@ -595,27 +615,89 @@ try {
     }
     case "reflect": {
       const usage =
-        'usage: memory.mjs reflect <report.json> [dir] [--run <wf-id>] [--card <id>] [--commit <sha>] [--adversary "<id>=<class>[: <reason>]"]... [--claude-bin <path>] [--claude-dir <path>] [--model <name>] [--max-usd <n>] [--dry-run] [--json]';
-      if (opts.hand) fail(`${usage}\n--hand is not accepted: a hand landing has no report.`, 2);
-      const [reportFile] = rest;
-      if (!reportFile) fail(usage, 2);
-      const dir = dirFrom(rest, 1);
-      const reportPath = resolve(reportFile);
-      if (!existsSync(reportPath)) fail(`no such report file: ${reportPath}`);
+        'usage: memory.mjs reflect <report.json> [dir] [--run <wf-id>] [--card <id>] [--commit <sha>] [--adversary "<id>=<class>[: <reason>]"]... [--harmful <id>]... [--claude-bin <path>] [--claude-dir <path>] [--model <name>] [--max-usd <n>] [--dry-run] [--json]';
+      let dir;
+      let reportPath;
       let reportText;
-      try {
-        reportText = readFileSync(reportPath, "utf8");
-      } catch (err) {
-        fail(`cannot read report file ${reportPath}: ${err.message}`);
-      }
       let report;
-      try {
-        report = unwrapReport(JSON.parse(reportText));
-      } catch (err) {
-        fail(`cannot parse report file ${reportPath} as JSON: ${err.message}`);
+      let classes;
+      let handCard = null;
+      if (opts.hand) {
+        const handUsage =
+          'usage: memory.mjs reflect --hand <card-id> [dir] --commit <sha> [--rounds <n>] [--review "R1=<real|marginal|false>[: <reason>]"]... [--harmful <id>]... [--note <text>] [--claude-bin <path>] [--model <name>] [--max-usd <n>] [--dry-run] [--json]';
+        const [id] = rest;
+        if (!id || !opts.commit) fail(handUsage, 2);
+        handCard = id;
+        dir = dirFrom(rest, 1);
+        let rounds = 1;
+        if (opts.rounds !== undefined) {
+          rounds = Number(opts.rounds);
+          if (!Number.isInteger(rounds) || rounds < 1) fail(`${handUsage}\n--rounds must be a positive integer, got ${JSON.stringify(opts.rounds)}.`, 2);
+        }
+        try {
+          classes = parseAdversaryClasses(opts.review || []);
+        } catch (err) {
+          fail(`${handUsage}\n${err.message}`, 2);
+        }
+        const base = join(dir, ".doug", ".state", "reports", id);
+        const readDirFiles = (sub) => {
+          const d = join(base, sub);
+          if (!existsSync(d)) return [];
+          return readdirSync(d)
+            .filter((n) => !n.startsWith("."))
+            .sort()
+            .map((name) => {
+              try {
+                return { name, text: readFileSync(join(d, name), "utf8") };
+              } catch {
+                return null;
+              }
+            })
+            .filter(Boolean);
+        };
+        let memoryUsed = [];
+        try {
+          const saved = JSON.parse(readFileSync(join(base, "lessons.json"), "utf8"));
+          if (saved && Array.isArray(saved.ids)) memoryUsed = saved.ids.filter((x) => typeof x === "string");
+        } catch {
+          memoryUsed = [];
+        }
+        const ledger = classes.map((c) => {
+          return { id: c.id, stage: "adversary", seat: "reviewer", severity: "blocker", status: "fixed", description: c.reason || `reviewer finding ${c.id}` };
+        });
+        const sortKeys = (v) =>
+          Array.isArray(v) ? v.map(sortKeys) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])])) : v;
+        const handReport = sortKeys({
+          track: "hand",
+          card: id,
+          commit: opts.commit,
+          levels: [{ index: 0, tasks: [{ id, card: id, commit: opts.commit, verified: true, passes: rounds, stopReason: null, memoryUsed, ledger }] }],
+          hand: { briefs: readDirFiles("briefs"), reviews: readDirFiles("reviews"), note: textOrNull(opts.note) },
+        });
+        reportText = JSON.stringify(handReport, null, 2) + "\n";
+        reportPath = join(base, "hand-report.json");
+        mkdirSync(base, { recursive: true });
+        writeFileSync(reportPath, reportText, "utf8");
+        report = handReport;
+      } else {
+        const [reportFile] = rest;
+        if (!reportFile) fail(usage, 2);
+        dir = dirFrom(rest, 1);
+        reportPath = resolve(reportFile);
+        if (!existsSync(reportPath)) fail(`no such report file: ${reportPath}`);
+        try {
+          reportText = readFileSync(reportPath, "utf8");
+        } catch (err) {
+          fail(`cannot read report file ${reportPath}: ${err.message}`);
+        }
+        try {
+          report = unwrapReport(JSON.parse(reportText));
+        } catch (err) {
+          fail(`cannot parse report file ${reportPath} as JSON: ${err.message}`);
+        }
+        classes = parseAdversaryClasses(opts.adversary || []);
       }
       const reportHash = createHash("sha256").update(reportText).digest("hex");
-      const classes = parseAdversaryClasses(opts.adversary || []);
       const plan = loadPlan(dir);
       const models = loadModels(dir);
       const model = textOrNull(opts.model) || (models.tiers.cheap && models.tiers.cheap.model) || "haiku";
@@ -640,11 +722,12 @@ try {
           classes,
           plan,
           run: opts.run ?? null,
-          card: opts.card ?? null,
+          card: handCard ?? opts.card ?? null,
           commit: opts.commit ?? null,
           model,
           claudeDir,
           dryRun,
+          harmful: opts.harmful || [],
           propose,
         });
         if (!dryRun && result.ok && result.appended && result.appended.length) {
@@ -843,14 +926,18 @@ try {
       }
       const provider = createProvider(readMemoryConfig(dir));
       const staleDays = readMemoryStaleDays(dir);
-      const { openMemory, recallLessons } = await import("../lib/memory.mjs");
+      const { openMemory, recallLessons, degradedWarning, detectLocalProvider } = await import("../lib/memory.mjs");
+      // Probed once, and only when no provider is configured; a failed probe is just "not detected".
+      const detectedProvider = provider ? null : await detectLocalProvider();
       const m = openMemory(dir);
       let result;
       try {
-        result = await recallLessons(m, query, { files, k, provider, checkoutDir: dir, staleDays });
+        result = await recallLessons(m, query, { files, k, provider, checkoutDir: dir, staleDays, detectedProvider });
       } finally {
         m.close();
       }
+      const recallWarning = degradedWarning(result, { what: "memory recall", detectedProvider });
+      if (recallWarning) process.stderr.write(recallWarning + "\n");
       if (opts.json) {
         process.stdout.write(JSON.stringify(result, null, 2) + "\n");
       } else {
@@ -863,6 +950,67 @@ try {
       }
       break;
     }
+    case "brief-lessons": {
+      const usage = "usage: memory.mjs brief-lessons <card-id> [dir] [--k <n>] [--json]";
+      const [id, ...extra] = rest;
+      if (!id) fail(usage, 2);
+      const dir = dirFrom(extra, 0);
+      let k = 8;
+      if (opts.k !== undefined) {
+        k = Number(opts.k);
+        if (!Number.isInteger(k) || k < 1) fail(`${usage}\n--k must be an integer >= 1, got ${JSON.stringify(opts.k)}.`, 2);
+      }
+      let card;
+      try {
+        card = findCard(loadBoard(dir), id);
+      } catch (err) {
+        fail(`no card ${id}: ${err.message}`);
+      }
+      const query = `${card.title}\n${card.goal ?? ""}`;
+      const header = "Lessons from earlier runs on this repository (memory; each cites where it was learned):";
+      const saved = { card: id, query, mode: null, reason: null, ids: [], text: null, recalledAt: new Date().toISOString() };
+      let error = null;
+      if (existsSync(join(dir, ".doug", ".state", "memory", "memory.db"))) {
+        try {
+          const provider = createProvider(readMemoryConfig(dir));
+          const staleDays = readMemoryStaleDays(dir);
+          const { openMemory, recallLessons, degradedWarning, degradedReason, detectLocalProvider, renderLessons } = await import("../lib/memory.mjs");
+          const detectedProvider = provider ? null : await detectLocalProvider();
+          const m = openMemory(dir);
+          try {
+            const result = await recallLessons(m, query, { k, checkoutDir: dir, provider, staleDays, detectedProvider });
+            const warning = degradedWarning(result, { what: "memory recall", detectedProvider });
+            if (warning) process.stderr.write(warning + "\n");
+            const rendered = renderLessons(result.lessons);
+            saved.mode = result.mode;
+            saved.reason = result.degraded ? degradedReason(result, detectedProvider) : null;
+            saved.ids = rendered.ids;
+            saved.text = rendered.text === null ? null : result.degraded ? `(recall was keyword-only: ${saved.reason})\n${rendered.text}` : rendered.text;
+          } finally {
+            m.close();
+          }
+        } catch (err) {
+          error = err.message;
+          saved.mode = null;
+          saved.reason = null;
+          saved.ids = [];
+          saved.text = null;
+          saved.error = error;
+          process.stderr.write(`[doug] memory recall skipped: ${error}\n`);
+        }
+      }
+      const reportDir = join(dir, ".doug", ".state", "reports", id);
+      mkdirSync(reportDir, { recursive: true });
+      writeFileSync(join(reportDir, "lessons.json"), JSON.stringify(saved, null, 2) + "\n", "utf8");
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(saved, null, 2) + "\n");
+      } else if (saved.ids.length) {
+        process.stdout.write([header, saved.text, `memoryUsed: ${saved.ids.join(", ")}`].join("\n") + "\n");
+      } else {
+        process.stdout.write(`No lessons recalled for ${id}.\n`);
+      }
+      break;
+    }
     case "doctor": {
       const dir = dirFrom(rest, 0);
       const cfg = readMemoryConfig(dir);
@@ -919,10 +1067,12 @@ try {
       if (opts.check && opts["no-check"]) {
         fail(`${usage}\n--check and --no-check are mutually exclusive.`, 2);
       }
-      const { openMemory, embedLessons } = await import("../lib/memory.mjs");
+      const { openMemory, embedLessons, lessonsNeedingEmbedding } = await import("../lib/memory.mjs");
       const m = openMemory(dir);
       let result;
       let checkStatus;
+      let stillMissing = 0;
+      let liveTotal = 0;
       try {
         if (opts["no-check"]) {
           process.stderr.write("embed-check: skipped (--no-check)\n");
@@ -944,6 +1094,8 @@ try {
           batch,
           onProgress: ({ embedded, total }) => process.stderr.write(`embedded ${embedded}/${total}\n`),
         });
+        stillMissing = lessonsNeedingEmbedding(m, { model: provider.model, dims: provider.dims }).length;
+        liveTotal = m.prepare("SELECT COUNT(*) AS n FROM lessons WHERE superseded_by IS NULL AND stale IS NULL").get().n;
       } finally {
         m.close();
       }
@@ -954,6 +1106,11 @@ try {
           `Embedded ${result.embedded}/${result.total} lesson(s) with ${provider.model}/${provider.dims} (${result.failed} failed).\n`
         );
       }
+      if (stillMissing > 0) {
+        process.stderr.write(
+          `WARNING: ${stillMissing} of ${liveTotal} lessons still have no vector for ${provider.model}/${provider.dims}; retry with memory.mjs reembed --batch 4\n`
+        );
+      }
       break;
     }
     case "index": {
@@ -1076,15 +1233,18 @@ try {
           }
         }
         const provider = createProvider(readMemoryConfig(dir));
-        const { openMemory } = await import("../lib/memory.mjs");
+        const { openMemory, degradedWarning, detectLocalProvider } = await import("../lib/memory.mjs");
         const { searchIndex } = await import("../lib/code-index.mjs");
+        const detectedProvider = provider ? null : await detectLocalProvider();
         const m = openMemory(dir);
         let result;
         try {
-          result = await searchIndex(m, query, { k, files, provider });
+          result = await searchIndex(m, query, { k, files, provider, detectedProvider });
         } finally {
           m.close();
         }
+        const searchWarning = degradedWarning(result, { what: "code index search", code: true, detectedProvider });
+        if (searchWarning) process.stderr.write(searchWarning + "\n");
         if (opts.json) {
           process.stdout.write(JSON.stringify(result, null, 2) + "\n");
         } else {
@@ -1268,7 +1428,7 @@ try {
       break;
     }
     default:
-      fail("usage: memory.mjs <record|reflect|outcomes|lessons|lesson|import|recall|doctor|reembed|embed-check|index|condition|decision|rule|claude-md> ...", 2);
+      fail("usage: memory.mjs <record|reflect|outcomes|lessons|lesson|import|recall|brief-lessons|doctor|reembed|embed-check|index|condition|decision|rule|claude-md> ...", 2);
   }
 } catch (err) {
   fail(err.message);

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

@@ -51,6 +51,7 @@ import { landPlan, INTEGRATION_WORKTREE } from "../lib/land.mjs";
 import { removeFinishedWorktrees, retireTaskWorktrees, retireIntegrationWorktree, branchHead, isGitRepo } from "../lib/worktrees.mjs";
 import { readMemoryConfig, readMemoryStaleDays, readIndexConfig, createProvider } from "../lib/embeddings.mjs";
 import { existsSync, readFileSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 
 // The project's install command from .doug/config.json, used when the plan does not name one.
 function configInstall(d) {
@@ -88,60 +89,34 @@ function configDeleteBranches(d) {
     return false;
   }
 }
+// card plan-base-branch-default: the branch checked out in d, or on a detached HEAD its full sha (noted on
+// stderr); null when d is not a git repository or git fails.
+function currentBase(d) {
+  const git = (...args) => execFileSync("git", args, { cwd: d, encoding: "utf8", stdio: "pipe" }).trim();
+  try {
+    const b = git("symbolic-ref", "--short", "-q", "HEAD");
+    if (b) return b;
+  } catch {}
+  try {
+    const sha = git("rev-parse", "--verify", "-q", "HEAD");
+    if (!sha) return null;
+    process.stderr.write(`[doug] plan.mjs: detached HEAD; baseBranch set to ${sha}\n`);
+    return sha;
+  } catch {
+    return null;
+  }
+}
 function withDefaults(p, d) {
   let out = p;
+  if (typeof out.baseBranch !== "string" || !out.baseBranch.trim()) {
+    const base = currentBase(d);
+    if (base) out = { ...out, baseBranch: base };
+  }
   if (!out.install && configInstall(d)) out = { ...out, install: configInstall(d) };
   const hasCommand = out.adversary && typeof out.adversary === "object" && typeof out.adversary.command === "string" && out.adversary.command.trim();
   if (out.adversary !== false && !hasCommand && configAdversary(d)) out = { ...out, adversary: { ...(out.adversary && typeof out.adversary === "object" ? out.adversary : {}), command: configAdversary(d) } };
   return out;
 }
-// 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() + "…";
-}
-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: [] };
-}
-
 // Mirrors lib/memory.mjs's exported MEMORY_DB_RELPATH by value, not by import: importing that module loads
 // node:sqlite at its top level (review MAJOR/MINOR 4), so the mere existence check below must not pull it in
 // on a Node that lacks node:sqlite, or every plan.mjs json without a database would eat that module's load
@@ -149,14 +124,27 @@ function renderLessons(lessons) {
 const MEMORY_DB_RELPATH = ".doug/.state/memory/memory.db";
 
 // Wraps a provider so a down or slow embeddings endpoint is ever hit once per `plan.mjs json` run: the first
-// embed() failure is cached and handed to every later caller with no further request, and the run prints
-// exactly one stderr line about it. Without this, a plan with many tasks rediscovers the same dead endpoint
+// embed() failure is cached and handed to every later caller with no further request (the degraded-recall
+// WARNING for it comes from warnOnce below, once per distinct line). Without this, a plan with many tasks rediscovers the same dead endpoint
 // once per task, each paying its own request or timeout (review MAJOR: measured 26.8s for 8 tasks against a
 // black-holed baseUrl). null in, null out: recallLessons already treats a null provider as keyword-only.
+// card recall-fallback-warning: each distinct degraded-recall warning is printed once per run, not once per task;
+// and the local-provider probe (only when no provider is configured) runs once per run too.
+const warnedLines = new Set();
+function warnOnce(line) {
+  if (!line || warnedLines.has(line)) return;
+  warnedLines.add(line);
+  process.stderr.write(line + "\n");
+}
+let detectedOnce = null;
+function detectOnce(provider) {
+  if (provider) return Promise.resolve(null);
+  if (!detectedOnce) detectedOnce = import("../lib/memory.mjs").then((mod) => mod.detectLocalProvider());
+  return detectedOnce;
+}
 function cachingProvider(provider) {
   if (!provider) return null;
   let failure = null;
-  let warned = false;
   return {
     name: provider.name,
     model: provider.model,
@@ -164,13 +152,7 @@ function cachingProvider(provider) {
     async embed(texts, opts) {
       if (failure) return failure;
       const result = await provider.embed(texts, opts);
-      if (!result.ok) {
-        failure = result;
-        if (!warned) {
-          warned = true;
-          process.stderr.write(`[doug] memory recall: embeddings provider unavailable (${result.reason}); keyword-only\n`);
-        }
-      }
+      if (!result.ok) failure = result;
       return result;
     },
   };
@@ -187,15 +169,20 @@ function cachingProvider(provider) {
 async function attachLessons(plan, dir, provider) {
   if (!existsSync(join(dir, MEMORY_DB_RELPATH))) return plan;
   try {
-    const { openMemory, recallLessons } = await import("../lib/memory.mjs");
+    const { openMemory, recallLessons, degradedWarning, degradedReason, renderLessons } = await import("../lib/memory.mjs");
     const staleDays = readMemoryStaleDays(dir);
     const m = openMemory(dir);
     try {
+      const detectedProvider = await detectOnce(provider);
+      // An empty lesson store has nothing to degrade (a code-index-only database, say): no warning for it.
+      const hasLessons = m.prepare("SELECT 1 FROM lessons WHERE superseded_by IS NULL AND stale IS NULL LIMIT 1").get() !== undefined;
       const tasks = [];
       for (const task of plan.tasks) {
-        const taskRecall = await recallLessons(m, `${task.title}\n${task.spec}`, { files: task.files, k: 8, checkoutDir: dir, provider, staleDays });
+        const taskRecall = await recallLessons(m, `${task.title}\n${task.spec}`, { files: task.files, k: 8, checkoutDir: dir, provider, staleDays, detectedProvider });
+        if (hasLessons) warnOnce(degradedWarning(taskRecall, { what: "memory recall", detectedProvider }));
         const taskLessons = renderLessons(taskRecall.lessons);
-        tasks.push(taskLessons.text === null ? task : { ...task, lessons: taskLessons.text, lessonIds: taskLessons.ids });
+        const lessonsText = taskLessons.text !== null && taskRecall.degraded ? `(recall was keyword-only: ${degradedReason(taskRecall, detectedProvider)})\n${taskLessons.text}` : taskLessons.text;
+        tasks.push(taskLessons.text === null ? task : { ...task, lessons: lessonsText, lessonIds: taskLessons.ids });
       }
       return { ...plan, tasks };
     } finally {
@@ -207,7 +194,7 @@ async function attachLessons(plan, dir, provider) {
   }
 }
 
-// Renders code chunks the same skip-not-stop way renderLessons renders lessons, one line per chunk:
+// Renders code chunks the same skip-not-stop way renderLessons (lib/memory.mjs) renders lessons, one line per chunk:
 // "- <path>:<start>-<end>  <first non-blank line of the chunk, trimmed to 120 chars>". codeContextIds carries
 // exactly the ids of the lines kept, in rank order. { text: null, ids: [] } when nothing rendered, the caller's
 // cue to omit the fields entirely.
@@ -243,17 +230,20 @@ async function attachCodeContext(plan, dir, provider) {
   if (!readIndexConfig(dir).enabled) return plan;
   if (!existsSync(join(dir, MEMORY_DB_RELPATH))) return plan;
   try {
-    const { openMemory } = await import("../lib/memory.mjs");
+    const { openMemory, degradedWarning, degradedReason } = await import("../lib/memory.mjs");
     const { searchIndex } = await import("../lib/code-index.mjs");
     const m = openMemory(dir);
     try {
       const chunkCount = m.prepare("SELECT COUNT(*) AS n FROM code_chunks").get().n;
       if (chunkCount === 0) return plan;
+      const detectedProvider = await detectOnce(provider);
       const tasks = [];
       for (const task of plan.tasks) {
-        const result = await searchIndex(m, `${task.title}\n${task.spec}`, { k: 6, provider });
+        const result = await searchIndex(m, `${task.title}\n${task.spec}`, { k: 6, provider, detectedProvider });
+        warnOnce(degradedWarning(result, { what: "code index search", code: true, detectedProvider }));
         const rendered = renderCodeContext(result.chunks);
-        tasks.push(rendered.text === null ? task : { ...task, codeContext: rendered.text, codeContextIds: rendered.ids });
+        const codeText = rendered.text !== null && result.degraded ? `(code search was keyword-only: ${degradedReason(result, detectedProvider)})\n${rendered.text}` : rendered.text;
+        tasks.push(rendered.text === null ? task : { ...task, codeContext: codeText, codeContextIds: rendered.ids });
       }
       return { ...plan, tasks };
     } finally {