@dougharness/cli 1.1.1 → 1.2.0

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

@@ -0,0 +1,368 @@
+// The parallel-card coordinator (card parallel-card-queens, ADR 0015): the pure decisions main makes while
+// several card queens run in one session. Which cards may run together (D1 disjointness), how many slots are
+// free, what a queen's finished run means, which done card lands next, which autopilot caps are reached.
+// Pure and import-free: the decisions are testable with fakes, and a host that is not Claude Code can reuse them.
+
+export const WORKERS_MAX_DEFAULT = 3;
+export const WORKERS_MAX_LIMIT = 16;
+
+// The configured workers.max when it is an integer from 1 to 16; the default silently when the key (or
+// workers) is absent; the default plus one warn() call otherwise.
+export function workersMax(config, warn = () => {}) {
+  const v = config && config.workers ? config.workers.max : undefined;
+  if (v === undefined) return WORKERS_MAX_DEFAULT;
+  if (Number.isInteger(v) && v >= 1 && v <= WORKERS_MAX_LIMIT) return v;
+  warn(`workers.max must be an integer from 1 to ${WORKERS_MAX_LIMIT}; using ${WORKERS_MAX_DEFAULT}`);
+  return WORKERS_MAX_DEFAULT;
+}
+
+// Paths every card records into; they never make two cards conflict.
+const IGNORED_PATHS = [".doug/board.json", "docs/live-runs.md", "board.json", "live-runs.md"];
+// A goal naming one of these runs alone: parallel cards would collide on the file (by basename), or on the
+// config (by full path).
+const SOLO_BASENAMES = ["package.json", "pnpm-lock.yaml", "package-lock.json", "yarn.lock", "CLAUDE.md"];
+const SOLO_PATHS = [".doug/config.json"];
+
+function norm(p) {
+  return String(p)
+    .replace(/\\/g, "/")
+    .replace(/\/{2,}/g, "/")
+    .replace(/^(\.\/)+/, "")
+    .replace(/\/+$/, "");
+}
+
+function baseName(p) {
+  const parts = norm(p).split("/");
+  return parts[parts.length - 1];
+}
+
+// Extensions seen in this repository; a token whose last segment has another one (Date.now, claude.ai, v1.2)
+// is prose, not a path.
+const FILE_EXTS = ["mjs", "js", "ts", "tsx", "json", "md", "yaml", "yml", "sh", "toml", "lock", "txt", "jsonl", "py", "db", "html", "css"];
+const PATH_CHARS = /^[A-Za-z0-9_.\-/*?@]+$/;
+// Prose pairs that look like a/b when no roots list is given.
+const PROSE_PAIRS = ["and/or", "either/or", "yes/no", "input/output", "read/write", "true/false", "he/she"];
+
+// A name that is only a dot and a word (.state, .git): a dot-directory, not a file with an extension.
+function isDotName(p) {
+  return /^\.[^.]+$/.test(baseName(p));
+}
+
+function hasFileExt(t) {
+  if (isDotName(t)) return false;
+  const m = /\.([A-Za-z0-9]+)$/.exec(baseName(t));
+  return !!m && FILE_EXTS.includes(m[1].toLowerCase());
+}
+
+// a/{b,c} -> a/b, a/c (first group, recursively). An unclosed brace is left as it is.
+function expandBraces(t) {
+  const open = t.indexOf("{");
+  const close = open < 0 ? -1 : t.indexOf("}", open);
+  if (open < 0 || close < 0) return [t];
+  const out = [];
+  for (const alt of t.slice(open + 1, close).split(",")) out.push(...expandBraces(t.slice(0, open) + alt + t.slice(close + 1)));
+  return out;
+}
+
+function cleanToken(raw) {
+  let t = raw;
+  for (let i = 0; i < 4; i++) {
+    const before = t;
+    t = t.replace(/^[([<"'`]+/, "").replace(/['\u2019]s$/, "").replace(/:\d+(-\d+)?$/, "");
+    t = t.replace(/[)\]>"'`,;:!?.]+$/, "");
+    if (t.endsWith("}") && !t.includes("{")) t = t.slice(0, -1);
+    if (t === before) break;
+  }
+  return t;
+}
+
+// The file and directory paths a goal names. Sentence punctuation, a trailing :line or :line-line and a
+// possessive 's are dropped; a/{b,c} expands to a/b and a/c; a trailing slash (a directory) is kept. Slash
+// commands, @scopes and prose (and/or, Date.now) are not paths. A slash token with no extension and no
+// trailing slash counts only when its first segment is in opts.roots; with no roots given it is kept.
+export function goalPaths(goal, opts) {
+  if (typeof goal !== "string") return [];
+  const roots = opts && Array.isArray(opts.roots) ? opts.roots : null;
+  const out = [];
+  for (const raw of goal.split(/\s+/)) {
+    const cleaned = cleanToken(raw);
+    if (!cleaned || cleaned.startsWith("/") || cleaned.startsWith("@") || cleaned.includes("://")) continue;
+    for (const t of expandBraces(cleaned)) {
+      if (!t || !PATH_CHARS.test(t) || !/[A-Za-z]/.test(t)) continue;
+      let ok;
+      if (!t.includes("/")) ok = hasFileExt(t);
+      else if (t.endsWith("/") || hasFileExt(t)) ok = true;
+      else if (roots) ok = roots.includes(t.split("/")[0]);
+      else ok = !PROSE_PAIRS.includes(t.toLowerCase()) && (isDotName(t) || !baseName(t).includes("."));
+      if (ok && !out.includes(t)) out.push(t);
+    }
+  }
+  return out;
+}
+
+function handPaths(card, opts) {
+  return goalPaths(card.goal, opts).filter((p) => !IGNORED_PATHS.includes(norm(p)));
+}
+
+function soloFile(card, opts) {
+  for (const p of goalPaths(card.goal, opts)) {
+    const n = norm(p);
+    if (SOLO_PATHS.includes(n) || SOLO_BASENAMES.includes(baseName(n))) return n;
+  }
+  return null;
+}
+
+function isDirEntry(p) {
+  return /\/$/.test(String(p)) || isDotName(p) || !baseName(p).includes(".");
+}
+
+function covers(dir, file) {
+  const d = norm(dir);
+  const f = norm(file);
+  return d !== "" && (f === d || f.startsWith(d + "/"));
+}
+
+// Two goal paths overlap: the same path, one inside the other, or the same file name.
+function pathsOverlap(p, q) {
+  if (covers(p, q) || covers(q, p)) return true;
+  return !isDirEntry(p) && !isDirEntry(q) && baseName(p) === baseName(q);
+}
+
+const GLOB_CHARS = /[*?{]/;
+
+function globToRegExp(glob) {
+  let re = "";
+  const g = norm(glob);
+  let inBrace = false;
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === "*") {
+      if (g[i + 1] === "*") {
+        i++;
+        if (g[i + 1] === "/") {
+          i++;
+          re += "(?:.*/)?";
+        } else re += ".*";
+      } else re += "[^/]*";
+    } else if (c === "?") re += "[^/]";
+    else if (c === "{" && g.indexOf("}", i) >= 0) {
+      inBrace = true;
+      re += "(?:";
+    } else if (c === "}" && inBrace) {
+      inBrace = false;
+      re += ")";
+    } else if (c === "," && inBrace) re += "|";
+    else re += c.replace(/[.+^$()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp("^" + re + "$");
+}
+
+// The directory a glob is rooted in: its literal prefix up to the last slash before the first glob character.
+function globRoot(glob) {
+  const g = norm(glob);
+  const at = g.search(GLOB_CHARS);
+  const lead = at < 0 ? g : g.slice(0, at);
+  const cut = lead.lastIndexOf("/");
+  return cut < 0 ? "" : lead.slice(0, cut);
+}
+
+// Do two plan ownership entries (exact file, directory or glob) overlap? Same semantics as scope.mjs's
+// ownsPath, tried both ways; a glob against anything also counts when their directories nest.
+function entriesOverlap(a, b) {
+  const x = norm(a);
+  const y = norm(b);
+  if (!x || !y) return false;
+  const gx = GLOB_CHARS.test(x);
+  const gy = GLOB_CHARS.test(y);
+  if (!gx && !gy) return covers(x, y) || covers(y, x);
+  if (gx && !gy && globToRegExp(x).test(y)) return true;
+  if (gy && !gx && globToRegExp(y).test(x)) return true;
+  const rx = gx ? globRoot(x) : x;
+  const ry = gy ? globRoot(y) : y;
+  if (rx === "" || ry === "") return true;
+  return covers(rx, ry) || covers(ry, rx);
+}
+
+function ownedFiles(card) {
+  const out = [];
+  const tasks = card.plan && Array.isArray(card.plan.tasks) ? card.plan.tasks : [];
+  for (const t of tasks) for (const f of (t && t.files) || []) if (typeof f === "string") out.push(f);
+  return out;
+}
+
+function taskIds(card) {
+  const tasks = card.plan && Array.isArray(card.plan.tasks) ? card.plan.tasks : [];
+  return tasks.map((t) => t && t.id).filter((id) => typeof id === "string");
+}
+
+function conflict(b, why) {
+  return { with: b.id, why };
+}
+
+function flowWithFlow(a, b) {
+  if (!a.plan || !b.plan) return conflict(b, `the plan of ${a.plan ? b.id : a.id} is not known yet`);
+  const ids = taskIds(b);
+  const shared = taskIds(a).find((id) => ids.includes(id));
+  if (shared) return conflict(b, `both plans have a task id "${shared}"`);
+  const mine = ownedFiles(a);
+  const theirs = ownedFiles(b);
+  for (const f of mine) for (const g of theirs) if (entriesOverlap(f, g)) return conflict(b, `both plans own ${norm(f) === norm(g) ? norm(f) : `${norm(f)} and ${norm(g)}`}`);
+  return null;
+}
+
+function flowWithHand(f, h, opts) {
+  if (!f.plan) return conflict(h, `the plan of ${f.id} is not known yet`);
+  if (soloFile(h, opts)) return conflict(h, `${h.id} names ${soloFile(h, opts)}, so it runs alone`);
+  for (const p of handPaths(h, opts)) {
+    for (const o of ownedFiles(f)) {
+      const bare = !norm(p).includes("/");
+      if (entriesOverlap(o, p) || (bare && !GLOB_CHARS.test(o) && baseName(o) === norm(p))) {
+        return conflict(h, `the plan owns ${norm(o)}, which the goal names (${norm(p)})`);
+      }
+    }
+  }
+  if (!f.component || !h.component) return conflict(h, "a card with no component conflicts with everything");
+  if (f.component === h.component) return conflict(h, `same component ${f.component}`);
+  return null;
+}
+
+function handWithHand(a, b, opts) {
+  const sa = soloFile(a, opts);
+  if (sa) return conflict(b, `${a.id} names ${sa}, so it runs alone`);
+  const sb = soloFile(b, opts);
+  if (sb) return conflict(b, `${b.id} names ${sb}, so it runs alone`);
+  const pa = handPaths(a, opts);
+  const pb = handPaths(b, opts);
+  for (const p of pa) for (const q of pb) if (pathsOverlap(p, q)) return conflict(b, `both goals name ${norm(p) === norm(q) ? norm(p) : `${norm(p)} and ${norm(q)}`}`);
+  if (!a.component || !b.component) return conflict(b, "a card with no component conflicts with everything");
+  if (a.component === b.component) return conflict(b, `same component ${a.component}`);
+  return null;
+}
+
+// null when the two cards may run together, else { with: b.id, why }. A flow card carries its plan as `.plan`.
+export function cardConflict(a, b, opts) {
+  if (!a || !b || typeof a !== "object" || typeof b !== "object") return { with: b && b.id !== undefined ? b.id : null, why: "a card is missing" };
+  if (a.track === "flow" && b.track === "flow") return flowWithFlow(a, b);
+  if (a.track === "flow") return flowWithHand(a, b, opts);
+  if (b.track === "flow") {
+    const c = flowWithHand(b, a, opts);
+    return c && conflict(b, c.why);
+  }
+  return handWithHand(a, b, opts);
+}
+
+// "hand" or "flow" for a card a queen can run; "alone" for a swarm or a decision card, which runs by itself.
+export function queenKind(card) {
+  if (!card) return "alone";
+  if (card.swarm || card.class === "decision") return "alone";
+  return card.track === "flow" ? "flow" : "hand";
+}
+
+// Which ready cards to start now. A flow card without a plan comes back as needsPlan (its owned files are
+// unknown until a planner runs); with a plan it is checked like any card. A card is launched when it conflicts
+// with nothing in flight and nothing launched before it; otherwise it is held against what it met first.
+// needsPlan and launch together never exceed `slots`; a held card takes no slot.
+export function pickCards(arg) {
+  const { ready = [], inFlight = [], slots = 0, plans = {}, roots } = arg && typeof arg === "object" ? arg : {};
+  const out = { launch: [], needsPlan: [], held: [], alone: [] };
+  const opts = { roots };
+  const planOf = (c) => (plans && typeof plans === "object" && Object.hasOwn(plans, c.id) ? plans[c.id] : null);
+  const withPlan = (c) => (c.track === "flow" && planOf(c) ? { ...c, plan: planOf(c) } : c);
+  const running = (inFlight || []).filter((c) => c && typeof c === "object").map(withPlan);
+  const launched = [];
+  let blocked = false;
+  for (const raw of ready || []) {
+    if (!raw || typeof raw !== "object") continue;
+    if (queenKind(raw) === "alone") {
+      // An alone card does not starve: the first one runnable in board order stops later launches. It is returned
+      // only when nothing is in flight, launched in this pick, or waiting for a plan.
+      if (running.length === 0 && out.launch.length === 0 && out.needsPlan.length === 0) out.alone.push(raw.id);
+      blocked = true;
+      continue;
+    }
+    if (blocked) continue;
+    if (out.launch.length + out.needsPlan.length >= slots) continue;
+    if (raw.track === "flow" && !planOf(raw)) {
+      out.needsPlan.push(raw.id);
+      continue;
+    }
+    const card = withPlan(raw);
+    let met = null;
+    for (const other of [...running, ...launched]) {
+      met = cardConflict(card, other, opts);
+      if (met) break;
+    }
+    if (met) out.held.push({ id: raw.id, with: met.with, why: met.why });
+    else {
+      out.launch.push(raw.id);
+      launched.push(card);
+    }
+  }
+  return out;
+}
+
+function parseResult(result) {
+  if (typeof result === "string") {
+    try {
+      return JSON.parse(result);
+    } catch {
+      return null;
+    }
+  }
+  return result && typeof result === "object" ? result : null;
+}
+
+// What a queen's finished run means for main: land it, resume it (the run died, or its result is unreadable, or
+// a seat's agent returned null), or ask the user (the other queens keep running meanwhile).
+export function classifyNotification(kind, arg) {
+  const { status, result } = arg || {};
+  if (status !== "completed") return { action: "resume", reason: `run status ${status}` };
+  const r = parseResult(result);
+  if (!r) return { action: "resume", reason: "result unreadable" };
+  if (kind === "flow") {
+    if (r.ok === true) return { action: "land" };
+    if (r.paused) {
+      const p = r.paused;
+      return { action: "ask", reason: `paused at a ${p.gate || "human"} gate (level ${p.level})` };
+    }
+    if (r.ok === false) return { action: "ask", reason: "the run stopped" + (r.stoppedAtLevel !== undefined ? ` at level ${r.stoppedAtLevel}` : "") };
+    return { action: "ask", reason: "unrecognised result" };
+  }
+  // The queen's real result (card-queen.js) carries outcome; the wrapper shape carries kind. Both are read.
+  const verdict = r.kind ?? r.outcome;
+  if (verdict === "done") return { action: "land" };
+  if (verdict === "stopped") {
+    if (r.reason === "agent-null") return { action: "resume", reason: "agent-null" };
+    return { action: "ask", reason: r.reason };
+  }
+  return { action: "ask", reason: "unrecognised result" };
+}
+
+// The done cards waiting to land, first in first out by doneAt. One lands at a time: while a card is landing
+// nothing else is next.
+export function landQueue(state) {
+  const cards = state && Array.isArray(state.cards) ? state.cards : [];
+  const done = cards
+    .filter((c) => c && typeof c === "object")
+    .map((c, i) => ({ c, i }))
+    .filter(({ c }) => c.state === "done")
+    .sort((x, y) => {
+      const a = x.c.doneAt || "￿";
+      const b = y.c.doneAt || "￿";
+      return a < b ? -1 : a > b ? 1 : x.i - y.i;
+    })
+    .map(({ c }) => c.id);
+  const busy = cards.some((c) => c && c.state === "landing");
+  return { next: busy || done.length === 0 ? null : done[0], queue: done };
+}
+
+// The names of the caps whose used value is at or over the cap. An unset cap is ignored.
+export function capsReached(caps, used) {
+  const out = [];
+  for (const name of ["usd", "wallMin", "contextPct"]) {
+    const cap = caps ? caps[name] : undefined;
+    const v = used ? used[name] : undefined;
+    if (typeof cap === "number" && Number.isFinite(cap) && typeof v === "number" && v >= cap) out.push(name);
+  }
+  return out;
+}

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

@@ -77,7 +77,7 @@ export function priceUsage(usage, model) {
 
 // The transcript writes one line per content block of an API response, each carrying that response's usage (and
 // the early blocks a partial output count), so usage is taken once per message id, the largest value seen per field.
-export function transcriptUsage(file) {
+export function transcriptUsage(file, { since = null, until = null } = {}) {
   const perMessage = new Map();
   const models = new Map();
   for (const line of readFileSync(file, "utf8").split("\n")) {
@@ -90,6 +90,13 @@ export function transcriptUsage(file) {
     }
     const m = o && o.message;
     if (o.type !== "assistant" || !m || !m.usage) continue;
+    if (since !== null || until !== null) {
+      // A window (card usd-budget-size-class) keeps only the lines whose timestamp falls in it, inclusive at both
+      // ends. A line with no readable timestamp cannot be placed and is kept: counting it is the conservative
+      // choice for a budget.
+      const at = Date.parse(o.timestamp);
+      if (!Number.isNaN(at) && ((since !== null && at < since) || (until !== null && at > until))) continue;
+    }
     const id = m.id || o.requestId || o.uuid;
     const u = m.usage;
     const cur = perMessage.get(id) || { ...emptyUsage(), model: m.model || null };
@@ -468,7 +475,7 @@ export function sessionTranscriptPath({ session, claudeDir = join(homedir(), ".c
 // <slug>/<session>/subagents/, recursively (plain agents and workflows/wf_*/ agents). `session` is an id or "latest",
 // the most recently modified top-level transcript in the project's slug directory. Throws when none is found.
 // Workflow journal.jsonl files carry no usage lines and add nothing.
-export function costSession({ session, claudeDir = join(homedir(), ".claude"), projectDir = process.cwd() } = {}) {
+export function costSession({ session, claudeDir = join(homedir(), ".claude"), projectDir = process.cwd(), since = null, until = null } = {}) {
   const top = sessionTranscriptPath({ session, claudeDir, projectDir });
   const slugDir = join(claudeDir, "projects", projectSlug(projectDir));
   const id = basename(top, ".jsonl");
@@ -485,23 +492,26 @@ export function costSession({ session, claudeDir = join(homedir(), ".claude"), p
   const usage = emptyUsage();
   let usd = 0;
   let unpriced = 0;
+  let counted = 0;
+  const windowed = since !== null || until !== null;
   const notes = [];
   for (const f of files) {
-    const t = transcriptUsage(f);
+    const t = transcriptUsage(f, { since, until });
     addUsage(usage, t.usage);
     if (!t.messages) continue;
+    counted++;
     const price = t.usd;
     if (price === null) {
       unpriced++;
       notes.push(`${f}: model ${t.model || "unknown"} is not in the price table; not priced`);
     } else usd += price;
   }
-  return { session: id, files: files.length, total: { usage, usd, unpriced, agents: files.length }, pricesDated: PRICES_DATED, notes };
+  return { session: id, files: windowed ? counted : files.length, windowed, total: { usage, usd, unpriced, agents: windowed ? counted : files.length }, pricesDated: PRICES_DATED, notes };
 }
 
 export function renderSession(result) {
   const t = result.total;
-  const lines = [`Session ${result.session}: ${result.files} transcript${result.files === 1 ? "" : "s"}.`];
+  const lines = [`Session ${result.session}: ${result.files} transcript${result.files === 1 ? "" : "s"}${result.windowed ? " in window" : ""}.`];
   lines.push(`Session total: ${fmtInt(t.usage.input)} input, ${fmtInt(t.usage.output)} output, ${fmtInt(t.usage.cacheRead)} cache read, ${fmtInt(t.usage.cacheWrite)} cache write tokens; ${fmtUsd(t.usd)}${t.unpriced ? ` (${t.unpriced} transcript(s) unpriced)` : ""} at list prices dated ${result.pricesDated}.`);
   for (const n of result.notes) lines.push(`Note: ${n}.`);
   return lines.join("\n") + "\n";

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 &&
@@ -452,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 };
@@ -569,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") {
@@ -675,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"}.`);