@orquentra/codebuddy 2.9.0 → 2.15.0

package/ARCHITECTURE.md

@@ -113,6 +113,104 @@ Rationale:
 
 - better to return slightly stale ranking than block on Hugging Face cold starts or rate limits
 
+## Local LLM and Intent Cards (2.15)
+
+**Runtime: node-llama-cpp.** The local small model (Qwen3-0.6B Q4_K_M by
+default; Qwen3-1.7B as `better`; Qwen only) runs through
+node-llama-cpp 3.22 (llama.cpp bindings). It was compared with Cactus on the
+four criteria in the 2.15 brief:
+
+| | node-llama-cpp 3.22.3 | Cactus |
+|---|---|---|
+| Install size | 41 MB package + one prebuilt binary (19 MB mac-arm64-metal, 33–34 MB x64) | npm ships `cactus-react-native` (152 MB, mobile) and `cactus-needle` (tool-calling model only) |
+| Cold start (M-series, Qwen3-0.6B) | 441 ms load, measured | no Node server binding to measure |
+| Tokens/s (M-series, Metal) | 100–200 tok/s measured; ~2 s per card incl. JSON grammar | n/a |
+| Prebuilt targets | macOS arm64/x64, Linux x64/arm64, Windows x64 (+CUDA/Vulkan) | iOS/Android focus |
+
+Cactus has no maintained Node.js binding for a desktop/server process, and its
+Node package hosts only the Needle tool-calling model, which the brief excludes
+(the job is plain English → code vocabulary, not tool selection). So
+node-llama-cpp. It is not a package dependency: `codebuddy use` (or
+`codebuddy models add local-llm`) installs it with `npm -g` and downloads the pinned GGUF into
+`~/.cache/codebuddy/models/gguf/`, checking size and sha256 before moving it
+into place. Forcing `gpu: false` on macOS makes node-llama-cpp compile llama.cpp
+from source (34 s first load), so the backend uses `gpu: "auto"` (Metal on Apple
+Silicon, CPU elsewhere) with `threads` capped at cores − 1
+(`CODEBUDDY_LLM_THREADS` overrides).
+
+**Where it runs.** Generation happens on llama.cpp's native threads inside
+`codebuddy serve` (background project sync) or `codebuddy index --cards`, never
+on a request path except the bounded query expansion below. A single context
+sequence serialises calls. Hooks and MCP tool calls touch
+`.codebuddy/cache/foreground`; the card and fact passes wait (up to 15 s) while
+it is fresher than 2 s. Output is constrained by a JSON-schema grammar with
+`maxItems`/`maxLength` bounds (without them the 0.6B model writes paragraphs
+until the token cap cuts the JSON), then validated with zod; invalid output is
+retried once, then the file is skipped.
+
+**Lifetime.** The model is loaded on demand and unloaded `IDLE_UNLOAD_MS`
+(60 s) after its last generation; measured on Qwen3-0.6B, resident memory went
+from 1,274 MB to 452 MB (the rest is the llama.cpp/Metal runtime, freed when
+the process exits). `serve` frees it on shutdown, and the detached
+`index --cards` that setup starts exits when its pass ends. Setup skips the
+local model on machines under 4 GB RAM or with one core (`machineCanCard`) and
+uses cloud Qwen there when a key is set.
+
+**Model size.** The same four-file card test with the grammar bounds:
+SmolLM2-135M Q4_K_M (105 MB) wrote `...` summaries and raw code lines as
+symptoms; Gemma 3 270M Q4_K_M (253 MB) wrote one-word summaries and term lists
+as symptoms; Qwen3-0.6B Q4_K_M (397 MB) wrote usable summaries and symptoms.
+So CodeBuddy ships Qwen only. A machine below `machineCanCard` gets Qwen from
+the cloud instead (BYOK: `qwen/qwen3.8-27b` on Groq or OpenRouter, sent with
+`reasoning_effort: "none"`; `<think>` blocks are stripped), configured by
+setup only when a provider key is already in the environment.
+
+**Cards** extend the existing `llm-summaries.json` store (prompt version 2), so
+the BYOK and local backends fill the same cache. Each card is used three ways:
+a card vector per file in `file-vectors.json` (granite, next to the chunk
+vectors), one Markdown file per source file in `.codebuddy/cache/cards/`, which
+is its own zvec-grep workspace (English model `local/bge-small-en-v1.5`,
+`--no-ignore`, so the project's ignore rules never hide it), and card terms and
+symptoms in the content index at half weight.
+
+**Agreement rule** (`context/discovery.ts`). 2.14 dropped every vector hit
+outside the keyword set unless it shared task terms with the source and cleared
+`zvec.minScore`. That deleted exactly the hits a reworded task needs. In 2.15 a
+candidate is admitted when at least two signals put it in their top k (default
+5): zvec-grep (code and card workspaces fused), the source-chunk vector, the
+card vector, and the old term-overlap rule as one more vote. Every ranking has
+a top k even for an unrelated task, so a vector vote also needs its cosine at
+or above a floor (`chunkFloor` 0.80, `cardFloor` 0.75). zg prints no
+similarity, so its vote is rank-only, and two rank-only votes never agree.
+Abstention returns nothing only when no candidate passes the rule and keyword
+evidence is below the floor. Card text alone never admits a file; card
+evidence counts when another signal agrees. The floors are uncalibrated
+defaults. Tune them in `.codebuddy/config.json` under `discovery.agreement`
+against the unrelated-task files (the 6 in the Litestar harness plus
+`evals/unrelated-2.15.json`).
+
+**Confidence.** Discovery returns `high` (anchor, exact identifier, CLI
+command, or ≥ 3 votes counting a strong keyword match as two), `medium` (two),
+or `low` (dense signals present but no returned file has two). `low` returns no
+paths: the hook emits nothing, and `context_pack` adds a note telling the agent
+to search normally. Without any dense signal the result is 2.14's keyword path
+and is never suppressed.
+
+**Expansion.** When a task found nothing confident and names no identifier,
+discovery asks the warm local model for 5–8 code terms (≤ 800 ms in
+`context_pack`, ≤ 300 ms in the hook) and ranks once more. Answers are cached
+per normalised task in `.codebuddy/cache/expansions.json` (LRU, 200). The hook
+process never has a warm model, so it only benefits from cached expansions.
+
+**Index facts** (`llm/index-facts.ts`) are Markdown facts with
+`createdByAgent: codebuddy-index`, `paths: [source]`,
+`verification: ["source:Lline"]` and an `index:` idempotency key.
+Manifest and CI facts are read deterministically. Prose facts come from the
+model and must share words with the cited line and read as a statement.
+Sensitive candidates are dropped. Re-extraction replaces only index facts
+whose source hash changed. The cap is 40 per repository, and near-duplicates
+(Jaccard ≥ 0.8) of any existing fact are skipped.
+
 ## Sharing Model
 
 Shares are references by default.

package/CLAUDE_CODEX.md

@@ -343,6 +343,28 @@ CODEBUDDY_PROJECT_ROOT = "/absolute/path/to/your-project"
 
 Restart Codex after installing or changing an MCP entry.
 
+Native project hooks are available in Codex 0.169.0. To retain task checkpoints
+with minimal prompt injection:
+
+```bash
+codebuddy clients install codex --mode lean --capture
+```
+
+Review the commands in Codex `/hooks` and approve them through Codex's trust UI.
+CodeBuddy writes `.codex/hooks.json`, preserves unrelated hooks, and never marks
+its own commands trusted. Without that review, automatic recovery is not active.
+Visible prompts, edits, explicit command outcomes and final answers are journaled;
+private reasoning and unstable rollout formats are not required. Compaction and
+startup/resume can restore unfinished task state. Host-payload tests pass; a live
+agent A/B has not yet verified correctness, token savings or cost savings.
+`codebuddy clients verify codex` checks installation, not trust approval.
+
+OpenCode and Hermes capture-enabled plugins use the same checkpoint bridge.
+Reinstall existing plugins to obtain it; capability reporting distinguishes older
+plugins. Disable capture with `--no-capture`; this also disables checkpoint capture
+and recovery. Hermes rehydrates its ephemeral prompt context from visible events.
+
+
 ## Useful CLI Commands
 
 List namespaces:
@@ -433,3 +455,14 @@ codebuddy doctor --skip-model-check
 ```
 
 Database and MCP setup can still be valid even when live Hugging Face diagnostics are temporarily unavailable.
+
+## Read guard modes
+
+Large unranged Claude `Read` calls are initially bounded to 200 lines, with an
+explicit continuation hint. Any explicit offset or limit passes unchanged; request
+the full line count when the whole file is needed. No permission approval is
+emitted. `CODEBUDDY_TOOL_GUARD=strict` restores the legacy outline-and-deny mode;
+`CODEBUDDY_TOOL_GUARD=0` disables the guard. The default leaves Bash commands
+unchanged and caps content-mode `Grep` calls only. Shell `grep` output is not
+silently capped because pipelines and exit status can be part of correctness.
+Live-host turn and token effects remain unmeasured.

package/README.md

@@ -1,11 +1,18 @@
-# CodeBuddy
+# CodeBuddy by Orquentra
 
 Local-first project context and memory for AI coding agents.
 
+Published by Orquentra as
+[`@orquentra/codebuddy` on npm](https://www.npmjs.com/package/@orquentra/codebuddy).
+
 CodeBuddy helps agents find relevant code, understand project constraints, and
 remember decisions across sessions. It works through MCP with Claude Code,
 Codex, OpenCode, Hermes, and other compatible clients.
 
+[npm package](https://www.npmjs.com/package/@orquentra/codebuddy) ·
+[Documentation](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/guide.md) ·
+[Source and issues](https://github.com/Orquentra-Inc/CodeBuddy)
+
 ## Install
 
 Requires Node.js 20 or later.
@@ -16,9 +23,12 @@ cd your-project
 codebuddy
 ```
 
-The setup wizard configures the project and agent integration. Project context
-works without a database; semantic memory recall optionally uses PostgreSQL
-with pgvector and a local Hugging Face embedding model (no token needed).
+That one command sets everything up: PostgreSQL (the bundled Docker database
+if none is running), the local embedding model (~90 MB), zvec-grep (installed
+and indexed), the local Qwen model (~400 MB; cloud Qwen with a key you enter on
+machines under 4 GB RAM), agent wiring for Claude and Codex, and a background
+pass that builds file vectors, intent cards and project facts. Skip pieces with
+`--no-local-llm`, `--no-graphify` or `--no-docker`.
 
 Run setup inside the project you want CodeBuddy to read. Claude Desktop
 registration saves that folder's absolute path, so restarting the desktop app
@@ -28,17 +38,111 @@ Older desktop registrations without a project path can be repaired by running
 `codebuddy claude install` from the initialized project folder, then restarting
 Claude Desktop.
 
+### Verify the package
+
+The npm package name is **`@orquentra/codebuddy`**; the installed command is
+**`codebuddy`**. Open the [npm package page](https://www.npmjs.com/package/@orquentra/codebuddy)
+directly to find its published versions, or query the public registry:
+
+```bash
+npm view @orquentra/codebuddy version --registry=https://registry.npmjs.org/
+```
+
+Search engine results and AI summaries may lag behind npm releases. If an
+installation fails, include the exact npm error and requested version in a
+[GitHub issue](https://github.com/Orquentra-Inc/CodeBuddy/issues).
+
 ## What it does
 
 - **Task context:** relevant files, symbols, code excerpts, nearby dependencies,
   and covering tests within a token budget.
 - **Project memory:** decisions, rules, and handoffs stored as readable Markdown,
-  recalled on every prompt by hybrid lexical + vector search
-  ([how it works](docs/semantic-memory.md)).
+  recalled for relevant tasks by hybrid lexical + vector search
+  ([how it works](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/semantic-memory.md)).
+- **Continuity:** a local journal of each session's goal, edits, checks and
+  findings, re-injected after compaction and offered to the next session when
+  a task was left unfinished. Native bridges cover Claude Code, Codex, OpenCode
+  and Hermes; live-host recovery and agent savings are not yet measured.
+- **Capture controls:** Claude Code, Codex, OpenCode and Hermes can keep turn capture
+  enabled with lean prompt injection (`clients install <client> --mode lean --capture`).
+  Codex project hooks require review in `/hooks`; installation does not bypass trust.
 - **Change guidance:** plans, policies, incident history, and risk signals.
+- **Reuse hints:** exported helpers matched lexically, with a conservative local
+  semantic fallback after indexing. A five-query smoke test admitted 2/5 correct
+  suggestions and withheld three; neither of two unrelated queries was admitted.
+  This is small-sample evidence, not an agent savings result.
 - **Optional retrieval:** zvec semantic search, Graphify architecture maps, and
   a bring-your-own LLM layer.
 
+## Optional local LLM (2.15)
+
+A small local model can write a plain-English **intent card** for every source
+file, so a task worded nothing like the code (for example "the browser forgets
+how long to wait before reconnecting") still finds the right file. `codebuddy`
+/ `codebuddy use` installs it as part of setup (Qwen3-0.6B Q4_K_M, ~400 MB,
+checksum-verified; skip with `--no-local-llm` or `CODEBUDDY_LOCAL_LLM=0`), and it
+runs offline after that. To manage it by hand:
+
+```bash
+codebuddy models add local-llm            # Qwen3-0.6B Q4_K_M, ~400 MB, checksum-verified
+codebuddy models add local-llm --size better   # Qwen3-1.7B, ~1.1 GB
+codebuddy models remove local-llm         # back to keyword + vector discovery
+```
+
+Setup also installs the runtime (`node-llama-cpp`, prebuilt for macOS, Linux
+and Windows; `models add` asks first). CodeBuddy uses Qwen only. On a machine
+under 4 GB of RAM or with one CPU core, setup uses Qwen in the cloud instead
+(`qwen/qwen3.8-27b` on Groq, free-tier key; or OpenRouter). It uses
+`GROQ_API_KEY` / `OPENROUTER_API_KEY` from the environment, or asks for a Groq
+key (free at console.groq.com/keys) and saves it in `~/.codebuddy/global.json`
+(mode 0600, never in the project). Bounded, redacted file heads and
+signatures are then sent to that provider ([details](docs/llm-byok.md)). Skip
+the prompt and keyword + vector discovery keep working.
+The model runs inside `codebuddy serve` (not in Docker; Docker only hosts
+PostgreSQL). It is unloaded 60 s after its last card and freed when the agent
+closes `serve`, so it never keeps running in the background.
+
+Qwen3-0.6B is the smallest model that wrote usable cards in our checks:
+SmolLM2-135M (105 MB) returned placeholders and raw code lines, and Gemma 3
+270M returned keyword lists instead of descriptions, so neither ships.
+Nothing leaves your machine, and without the model every feature falls back to
+the 2.14 behaviour.
+
+- **Intent cards:** a summary, 3–6 "symptoms" in bug-report wording, the code
+  terms to search for, and a line per main symbol. Written in the background by
+  `codebuddy serve` (or `codebuddy index --cards`) for new and changed source
+  files only; tests, docs, generated, vendored and secret-bearing files are
+  skipped. Cards feed a second vector per file, a zvec-grep card workspace, and
+  (down-weighted) the keyword index. Progress: `codebuddy models`, `codebuddy
+  storage`.
+- **Agreement rule:** a file the keywords missed is admitted when two
+  independent signals agree (zvec-grep, source-chunk vectors, card vectors,
+  term overlap). When no returned file has two, CodeBuddy says so instead of
+  guessing: `context_pack` returns `confidence: "low"` with a note to search
+  normally, and the prompt hook stays silent.
+- **Index facts:** up to 40 project facts drawn from `package.json`,
+  `pyproject.toml`, CI workflows, README / CONTRIBUTING / AGENTS.md /
+  CLAUDE.md and deprecation or release policies, each with its source line.
+  They are ordinary Markdown facts; `codebuddy memory list --origin index`
+  shows them and `codebuddy memory prune --origin index` removes them. Facts a
+  person or agent wrote are never replaced.
+
+`codebuddy use` also builds the zvec-grep index and enables it when `zg` 0.2.x
+is installed, and `codebuddy serve` keeps a `zg server` running so the prompt
+hook gets vector candidates within its deadline.
+
+## What it costs
+
+Context is not free: tool schemas, the rules block and the injected context are
+re-read on every turn. A 2026-11 A/B on 23 real Litestar bug fixes (Claude Code,
+Sonnet) found CodeBuddy 2.9 cost a median 22% more per task than stock Claude
+Code with no change in pass rate or exploration. 2.10 cuts the fixed overhead
+from about 4,250 to about 400 tokens per session; that it now breaks even or
+saves is not yet measured. On small, well-specified tasks expect near-zero
+overhead, not savings; savings need vague tasks, large repositories or
+cross-session memory. Method and pre-registered criteria:
+[docs/benchmarks](docs/benchmarks/).
+
 ## See what it does
 
 ```bash
@@ -68,13 +172,14 @@ codebuddy init --non-interactive
 codebuddy context preview "fix the login flow"
 ```
 
-Agents use `context_pack` to request task evidence and `context_after_turn` to
-capture useful knowledge. Request `evidence: "source"` when a short excerpt
+By default the MCP server lists three tools: `context_pack` for task evidence,
+and `recall` / `remember` for project memory (`CODEBUDDY_TOOL_PROFILE=full`
+lists all of them). Request `evidence: "source"` when a short excerpt
 needs more detail. Inspect missing or truncated evidence before editing.
 
 ## Documentation
 
-- [Full guide and examples](https://github.com/Orquentra-Inc/CodeBuddy/blob/348bb7c/README.md)
+- [Full guide and examples](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/guide.md)
 - [Telemetry and the admin panel](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/telemetry.md)
 - [Token budgets](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/token-budgets.md)
 - [Optional LLM setup](https://github.com/Orquentra-Inc/CodeBuddy/blob/main/docs/llm-byok.md)

package/dist/{adapters-S4HHTWJW.js → adapters-OJRSVFV3.js}

@@ -8,7 +8,7 @@ import {
   parseMode,
   sharedRulesReaders,
   supportedModes
-} from "./chunk-W7GAXL6C.js";
+} from "./chunk-V7PT6ER5.js";
 import "./chunk-PZ5AY32C.js";
 export {
   AUTOMATION_MODES,
@@ -21,4 +21,4 @@ export {
   sharedRulesReaders,
   supportedModes
 };
-//# sourceMappingURL=adapters-S4HHTWJW.js.map
+//# sourceMappingURL=adapters-OJRSVFV3.js.map

package/dist/{chunk-GXOML4UZ.js → chunk-4BSO3HST.js}

@@ -1,9 +1,9 @@
 import {
   asksForChangelog
-} from "./chunk-TLWGZVPC.js";
+} from "./chunk-UR3DF74I.js";
 import {
   readConfigFile
-} from "./chunk-KNR2P2UY.js";
+} from "./chunk-M75SN4D4.js";
 import {
   writeAtomic
 } from "./chunk-CG5B3LYG.js";
@@ -52,10 +52,10 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
   const config = await zvecConfig(root);
   if (!config.enabled) return none("disabled", "zvec-grep not enabled");
   const { deadlineAt } = options;
-  const run = (args) => {
+  const run = (args, cwd = root) => {
     const ms = deadlineAt === void 0 ? config.timeoutMs : Math.min(config.timeoutMs, deadlineAt - Date.now());
-    if (ms <= 0) return Promise.resolve({ stdout: "", error: deadlineError() });
-    return runZg(config.binary, args, root, ms);
+    if (ms <= 0) return Promise.resolve({ stdout: "", stderr: "", error: deadlineError() });
+    return runZg(config.binary, args, cwd, ms);
   };
   const missedDeadline = (status) => deadlineAt !== void 0 && status === "timeout" && Date.now() >= deadlineAt - 5;
   const cached = await readCachedReadiness(root, config.binary);
@@ -73,7 +73,7 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
   const limit = Math.min(20, Math.max(1, Math.floor(options.limit ?? 10)));
   const chunkLimit = limit * 8;
   const globs = zvecExcludeGlobs(task);
-  const result = await run([
+  const query = [
     "query",
     "--vector",
     task,
@@ -84,13 +84,20 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
     "--limit",
     String(chunkLimit),
     ...globs.flatMap((glob) => ["-g", glob])
-  ]);
+  ];
+  const cardQuery = queryCards(root, task, limit, (args, cwd) => run(args, cwd));
+  let result = await run(query);
+  if (result.error && isBusy(result) && (deadlineAt === void 0 || deadlineAt - Date.now() > 400)) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, BUSY_RETRY_MS));
+    result = await run(query);
+  }
   if (result.error) {
-    const failure = fromError(result.error, "zvec-grep query");
-    if (!missedDeadline(failure.status)) await resetZvecCache(root);
+    const failure = fromError(result.error, "zvec-grep query", result.stderr);
+    if (!missedDeadline(failure.status) && failure.status !== "busy") await resetZvecCache(root);
     return failure;
   }
   const hits = parseHits(result.stdout).slice(0, chunkLimit);
+  const cardPaths = await cardQuery;
   if (hits.length === 0 && /\bzg index\b/.test(result.stdout)) {
     const notReady = none("index-not-ready", NOT_READY);
     await markReadiness(root, config.binary, notReady);
@@ -133,7 +140,8 @@ async function zvecCandidates(repositoryRoot, task, options = {}) {
     stale,
     changed,
     minScore: config.minScore,
-    reason: `zvec-grep vector search: ${paths.length} file(s)` + (globs.length > 0 ? "; non-source paths excluded" : "") + (stale > 0 ? `, ${stale} stale hit(s) dropped` : "") + (changed > 0 ? `, ${changed} hit(s) changed since the zg index dropped` : "") + (indexedAt === null ? "; index age unknown, hits unverified (run `codebuddy zvec index`)" : "")
+    ...cardPaths.length > 0 ? { cardPaths } : {},
+    reason: `zvec-grep vector search: ${paths.length} file(s)` + (globs.length > 0 ? "; non-source paths excluded" : "") + (stale > 0 ? `, ${stale} stale hit(s) dropped` : "") + (changed > 0 ? `, ${changed} hit(s) changed since the zg index dropped` : "") + (cardPaths.length > 0 ? `; ${cardPaths.length} intent card match(es)` : "") + (indexedAt === null ? "; index age unknown, hits unverified (run `codebuddy zvec index`)" : "")
   };
 }
 async function refreshZvecIndex(repositoryRoot, options = {}) {
@@ -229,6 +237,90 @@ async function buildZvecIndex(repositoryRoot, options = {}) {
   return code;
 }
 var NOT_READY = "zvec-grep index missing or not ready; run `codebuddy zvec index`";
+var CARDS_DIR = join(".codebuddy", "cache", "cards");
+var DEFAULT_CARD_MODEL = "local/bge-small-en-v1.5";
+async function queryCards(root, task, limit, run) {
+  const cards = join(root, CARDS_DIR);
+  if (!await stat(join(cards, ".zvec-grep")).catch(() => null)) return [];
+  const result = await run(
+    ["query", "--vector", task, "--mode", "auto", "--refresh", "off", "--limit", String(limit)],
+    cards
+  );
+  if (result.error) return [];
+  const paths = [];
+  for (const hit of parseHits(result.stdout)) {
+    const card = toRepoRelative(cards, hit.path);
+    if (!card?.endsWith(".md")) continue;
+    const path = card.slice(0, -3);
+    if (paths.includes(path)) continue;
+    if (!(await stat(resolve(root, path)).catch(() => null))?.isFile()) continue;
+    paths.push(path);
+  }
+  return paths.slice(0, limit);
+}
+async function refreshZvecCardIndex(repositoryRoot, options = {}) {
+  const root = resolve(repositoryRoot);
+  const config = await zvecConfig(root);
+  if (!config.enabled) return { status: "disabled", reason: "zvec-grep not enabled" };
+  const cards = join(root, CARDS_DIR);
+  if (!await stat(cards).catch(() => null))
+    return { status: "ok", reason: "no intent cards yet" };
+  const exists = await stat(join(cards, ".zvec-grep")).catch(() => null);
+  const result = await runZg(
+    config.binary,
+    [
+      "index",
+      cards,
+      ...exists ? [] : ["--embedding", config.cardModel],
+      "--no-ignore",
+      "--mode",
+      "auto"
+    ],
+    cards,
+    REFRESH_TIMEOUT_MS,
+    options.signal
+  );
+  if (result.error) {
+    const failure = fromError(result.error, "zvec-grep card index", result.stderr);
+    return { status: failure.status, reason: failure.reason };
+  }
+  await writeFile(join(cards, ".zvec-grep", ".gitignore"), "*\n", { flag: "wx" }).catch(() => {
+  });
+  return { status: "ok", reason: "zvec-grep card index refreshed" };
+}
+async function ensureZvecServer(repositoryRoot) {
+  const root = resolve(repositoryRoot);
+  const config = await zvecConfig(root);
+  const noop = async () => {
+  };
+  if (!config.enabled) return { started: false, reason: "zvec-grep not enabled", stop: noop };
+  const run = (args) => runZg(config.binary, args, root, Math.max(config.timeoutMs, 5e3));
+  const readiness = await checkReadiness(run);
+  if (readiness) return { started: false, reason: readiness.reason, stop: noop };
+  const status = await run(["server", "status"]);
+  if (!status.error && /^Server: ready\b/m.test(status.stdout)) {
+    return { started: false, reason: "zg server already running (reused)", stop: noop };
+  }
+  const on = await run(["server", "on"]);
+  await rm(serverPath(root), { force: true });
+  if (on.error) {
+    return {
+      started: false,
+      reason: fromError(on.error, "zg server on", on.stderr).reason,
+      stop: noop
+    };
+  }
+  return {
+    started: true,
+    reason: "zg server started",
+    // ponytail: the daemon is shared; a second `codebuddy serve` that reused it
+    // loses vectors when this one exits. Refcount via ZVEC_GREP_HOME if that matters.
+    stop: async () => {
+      await runZg(config.binary, ["server", "off"], root, 5e3);
+      await rm(serverPath(root), { force: true });
+    }
+  };
+}
 async function checkReadiness(run) {
   const version = await run(["version"]);
   if (version.error) return fromError(version.error, "zvec-grep version check");
@@ -306,7 +398,8 @@ async function zvecConfig(root) {
     enabled: env !== void 0 ? env === "1" || env === "true" : file.zvec?.enabled ?? false,
     binary: file.zvec?.binary ?? "zg",
     timeoutMs: file.zvec?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-    minScore: file.zvec?.minScore ?? DEFAULT_ZVEC_MIN_SCORE
+    minScore: file.zvec?.minScore ?? DEFAULT_ZVEC_MIN_SCORE,
+    cardModel: file.zvec?.cardModel ?? DEFAULT_CARD_MODEL
   };
 }
 function runZg(binary, args, cwd, timeoutMs, signal) {
@@ -321,12 +414,16 @@ function runZg(binary, args, cwd, timeoutMs, signal) {
         killSignal: "SIGKILL",
         ...signal ? { signal } : {}
       },
-      (error, stdout) => {
+      (error, stdout, stderr) => {
         if (error && error.killed) {
-          resolveRun({ stdout: "", error: Object.assign(error, { code: "ETIMEDOUT" }) });
+          resolveRun({
+            stdout: "",
+            stderr: String(stderr),
+            error: Object.assign(error, { code: "ETIMEDOUT" })
+          });
           return;
         }
-        resolveRun({ stdout: String(stdout), error });
+        resolveRun({ stdout: String(stdout), stderr: String(stderr), error });
       }
     );
   });
@@ -360,10 +457,17 @@ async function serverRunning(root, binary, run) {
   }
   return running;
 }
-function fromError(error, what) {
+function fromError(error, what, stderr = "") {
   if (error.code === "ENOENT") return none("not-installed", "zvec-grep (`zg`) not found on PATH");
   if (error.code === "ETIMEDOUT") return none("timeout", `${what} timed out`);
-  return none("failed", `${what} failed`);
+  if (BUSY.test(stderr)) return none("busy", `${what}: index busy (a zg index refresh is running)`);
+  const code = stderr.match(/\bCode:\s*(\S+)/)?.[1];
+  return none("failed", `${what} failed${code ? ` (${code})` : ""}`);
+}
+var BUSY = /ZVEC_GREP\.ENGINE\.LOCK\.BUSY/;
+var BUSY_RETRY_MS = 150;
+function isBusy(result) {
+  return BUSY.test(result.stderr);
 }
 function none(status, reason) {
   return { status, paths: [], hits: [], reason, stale: 0, changed: 0 };
@@ -384,6 +488,10 @@ export {
   parseHits,
   resetZvecCache,
   zvecStatus,
-  buildZvecIndex
+  buildZvecIndex,
+  CARDS_DIR,
+  DEFAULT_CARD_MODEL,
+  refreshZvecCardIndex,
+  ensureZvecServer
 };
-//# sourceMappingURL=chunk-GXOML4UZ.js.map
+//# sourceMappingURL=chunk-4BSO3HST.js.map