@bigknoxy/hashpilot 4.7.0 → 4.8.0

package/docs/CLI-QUICKREF.md

@@ -167,7 +167,7 @@ looks unrelated to AST. Green baseline is `bun test` fully passing (515 pass / 0
 
 <!-- BEGIN GENERATED: command reference -->
 
-_36 commands, generated from `--help`. Do not edit by hand — run `bun run gen:cli-quickref`._
+_37 commands, generated from `--help`. Do not edit by hand — run `bun run gen:cli-quickref`._
 
 ### Global options
 
@@ -824,4 +824,23 @@ hashpilot config [options]
 |------|---------|
 | `--config <path>` | Config file path override |
 
+#### `search`
+
+Search a workspace: zg (zvec-grep) semantic/lexical when available, grep fallback. Usage: search "<query>" (zg) or search --engine grep "<pattern>" [paths...]
+
+```
+hashpilot search [options] <query> [paths...]
+```
+
+| Positional | Meaning |
+|------------|---------|
+| `query` | Query text (plain language for zg; a regex only makes sense on the grep engine) |
+| `paths` | Paths to search (grep engine only; zg searches its indexed workspace) |
+
+| Flag | Meaning |
+|------|---------|
+| `--engine <engine>` | Search engine: auto, zg, grep, off (default: config or auto) (default: "auto") |
+| `--glob <glob>` | Source glob filter, repeatable (default: code extensions) (default: []) |
+| `--zg-bin <path>` | Path to the zg binary (default: ZG_BIN env, then PATH) |
+
 <!-- END GENERATED: command reference -->

package/docs/PLAN-search-adapter.md

@@ -0,0 +1,130 @@
+# PLAN — Optional zg Search Adapter (`hashpilot search`)
+
+Status: **scoped, NOT built.** Decision artifact for `docs/zvec-grep-integration.md` Option 2.
+This is what it would take, enumerated as *falsifiers* (tests that invalidate the naive
+design) plus a TDD implementation plan. Follow `test-driven-development`.
+
+**Goal:** an optional `hashpilot search` subcommand that uses zg for semantic/lexical search
+when available and configured, degrading to the existing `grep-many` otherwise — with zero
+change to HashPilot's standalone behavior.
+
+**Boundary rules (from Option 1 rejection):** zg stays an external CLI. No `@zvec/zvec-grep`
+npm dependency. Node 22+ is a *documented* optional requirement, never an enforcement.
+`grep-many` and the entire editing core are untouched.
+
+---
+
+## Falsifier set (the design is wrong if any of these tests pass)
+
+Each row: the naive assumption → the falsifying test → the design it forces.
+
+- **F1 — "semantic output is strictly better, pass it through."**
+  Observed: default Model2Vec ranks `.md` docs over source. *Test:* pointer that the top zg
+  hit for a code query is a `.md` file → `search` MUST NOT return docs when
+  `sourceGlobs` is set. *Forces:* `sourceGlobs` filter (default `*.ts,*.js,*.py,*.go,*.rs`),
+  passed to zg as `-g`.
+
+- **F2 — "zg is always on PATH."**
+  *Test:* `ZG_BIN` unset / zg absent → `search` returns grep-many-equivalent results, exit 0,
+  telemetry records a `search_degraded` reason. *Forces:* a resolve step + clean degraded
+  path with a named exit code, never a crash.
+
+- **F3 — "semantic search works with no index."**
+  *Test:* fresh tree, no `.zvec-grep/` → `zg query` fails. `search` MUST surface an
+  actionable error ("run `zg index` first", a dedicated errorCode), not an opaque spawn
+  failure. *Forces:* index-state detection before querying.
+
+- **F4 — "one output shape across all zg routes."**
+  *Test:* parser fed captured hybrid / fts / vector / rg outputs (with header + freshness
+  lines) yields the same `{file,startLine,endLine}` regardless of route. *Forces:* a
+  route-aware parser, golden-tested on fixture artifacts.
+
+- **F5 — "grep fallback equals grep-many."**
+  *Test (parity):* `search "<regex>"` with engine=grep and zg absent produces the
+  *byte-identical* JSON body that `grep-many "<regex>"` produces for the same inputs.
+  *Forces:* a shared result mapper; no drift between the two search paths.
+
+- **F6 — "config toggle is cosmetic."**
+  *Test:* `engine: "off"` with a real zg present → a fake zg records **zero** invocations.
+  *Forces:* the policy check runs *before* any spawn; `off` never touches zg.
+
+- **F7 — "search may build convenience indexes."**
+  zg's own rule: *an agent must never silently create/rebuild a persistent index.*
+  *Test:* running `search` on an unindexed tree must NOT create `.zvec-grep/`.
+  *Forces:* query-only; missing index ⇒ error, never build.
+
+- **F8 — "spawn exit 0 ⇒ success."**
+  HashPilot's grep lesson (`core/grep.ts:156-180`): code 1 + empty stderr = zero matches,
+  nonzero + JSON stdout = real error. *Test:* zg exits 2 with stderr but emits parseable
+  markdown → reported as a search *error*, not silently dropped. *Forces:* replicate grep.ts
+  `runCommand` semantics.
+
+- **F9 — "results fit GrepResult, just add semantics."**
+  zg has no column and emits grouped line spans; forcing it into `{path,line,column,content}`
+  is lossy and lies. *Test:* a `SearchResult` must carry `{file,startLine,endLine,heading?,
+  scope?}` and NOT claim a `column`. *Forces:* a distinct type; no cross-field duplication
+  with `GrepResult`.
+
+---
+
+## Files touched
+
+- **Create** `src/core/search.ts` — the adapter + parser + resolve + fallback (models
+  `core/grep.ts:156` `runCommand` and `parseGrepLine`).
+- **Create** `src/commands/search.ts` — commander registration mirroring `commands/read.ts`
+  (single `search` command: `<query>` positional, `--line`/`--glob`/`--engine` flags).
+- **Modify** `src/cli.ts` — `register(searchCommands)`.
+- **Modify** `src/core/config.ts` — add to `HashPilotConfig` (`#56-63`):
+  ```ts
+  search?: {
+    engine?: "auto" | "zg" | "grep";   // auto: use zg if resolvable
+    sourceGlobs?: string[];            // default ["*.ts","*.js","*.py","*.go","*.rs"]
+  };
+  ```
+  Read from `.hashpilot.json` via `loadConfig` (`config.ts:111`).
+- **Modify** `src/core/doctor.ts` — report zg presence in the environment health check.
+- **Modify** `src/core/index.ts` — export `search`.
+- **Docs gate:** regenerate `docs/CLI-QUICKREF.md` (`bun run gen:cli-quickref`) and add a
+  ROADMAP row (`lint:roadmap`). Both are CI-enforced contracts.
+
+---
+
+## TDD implementation (vertical tracer bullets, RED→GREEN each)
+
+A **fake `zg` fixture** (env-injected via `ZG_BIN`) keeps tests hermetic — real subprocess
+(no mock), printed canned agent-markdown per query. Same style as `tests/grep.test.ts`
+(real subprocess, temp trees, no mocks).
+
+- **TB1 (F2/F4):** `search` resolves fake zg + parses one hybrid query → `SearchResult[]`.
+  RED: `tests/search.test.ts` — "search parses zg hybrid hits into file+span".
+- **TB2 (F5):** zg absent / `--engine grep` → result JSON byte-identical to `grep-many`.
+  RED: parity test against a call of the real `grepMany`.
+- **TB3 (F6):** `engine:"off"` never spawns zg (fake zg invocation counter stays 0).
+  RED: policy test; GREEN: check-policy-before-spawn.
+- **TB4 (F1):** sourceGlobs filters the doc hit out of results.
+  RED: seed fake zg with a `.md`-first fixture; expect it dropped under source mode.
+- **TB5 (F3/F7):** unindexed tree → actionable error and no `.zvec-grep/` created.
+  RED: assert errorCode + `!existsSync(".zvec-grep")`.
+- **TB6:** CLI contract — `hashpilot search "<q>"` wires end-to-end; quickref regenerated.
+  Uses `tests/cli-contract.test.ts` pattern.
+
+**Spike first (throwaway, delete after):** parse one real `zg query` hybrid/fts/vector/rg
+output into a fixture, choose the regex — proves the parser before TDD (allowed: exploration
+thrown away, then TDD).
+
+---
+
+## Effort
+
+~2 new files + 4 small edits (config, cli, index, doctor), ~400–550 LOC incl. tests.
+~6 TDD bullets, one focused session each. Biggest risk is **agend-markdown parser
+brittleness** — mitigated by golden fixtures; the durable fix is zg's MCP JSON endpoint
+(swap the parser for an MCP call in a follow-up, keep the same `SearchResult` type).
+
+## Risks / notes
+- zg's CLI has **no `--json`** — the whole adapter's stability rests on the agent-markdown
+  format. Acceptable for a prototype; MCP path is the production answer.
+- Default embedding ranks docs over source — hence `sourceGlobs` is a hard requirement, not
+  a nice-to-have (F1).
+- zero behavior change to grep-many/editing (boundary rule) is itself a falsifier: the full
+  existing suite must stay green.

package/docs/zvec-grep-integration.md

@@ -0,0 +1,92 @@
+# zg (zvec-grep) × HashPilot Integration
+
+Status: **proven prototype** (Option 3: docs-only integration). HashPilot does not
+depend on zg. zg is an optional, separately-installed search layer; HashPilot edits.
+
+## What zg is / is not
+
+- **zg answers "WHERE is the code?"** — semantic (plain-language), BM25, and ripgrep
+  behind one local-first index. Repo: `zvec-ai/zvec-grep`, Apache 2.0, npm `@zvec/zvec-grep`,
+  Node 22+. Default embedder `local/potion-code-16m-v2` is a static Model2Vec — no GPU.
+- **HashPilot answers "HOW do I change it safely once found?"** — hash-anchored, AST-aware,
+  provenance-tracked edits.
+- **They do not overlap except at one point:** HashPilot's `grep-many`/`symbol-lookup-many`
+  (exact/token lookup) ≈ zg's `--rg`/index path. zg's *semantic* route is the capability
+  HashPilot genuinely lacks. Neither replaces the other — zg does zero editing, HashPilot
+  does zero semantic search.
+
+## The recommended pipeline (search → edit)
+
+```
+zg query "<plain language>"      →  file + line span       (the NEIGHBORHOOD)
+hashpilot read-hash <file> <line> →  SHA-256 anchor         (the precision anchor)
+hashpilot replace-hash <file> <hash> <new> --range N:N      (the guaranteed edit)
+```
+
+zg locates *which file & which broader region*; HashPilot needs a *single precise line* to
+anchor an edit. Feed zg's span, pick the anchor line, let HashPilot guarantee the edit.
+
+## HashPilot anchor semantics (read before scripting edits)
+
+`replace-hash <file> <oldHash> <newContent> --range N:M` verifies against **the hash of
+exactly lines N..M joined by "\n"** (`content.split("\n").slice(N-1,M).join("\n")`,
+`src/core/hash-edit.ts`). Getting the anchor wrong ⇒ every edit is `HASH_MISMATCH`.
+
+- `read-hash <file> <line>` returns two anchors, keyed `lineHash` and `contextHash`:
+  - `lineHash` = hash of that one line → pair with `--range N:N`
+  - `contextHash` = hash of the 7-line window (3 before + line + 3 after) → pair with a
+    `--range` covering that same window. Widening/capping the range makes it no longer match.
+  - There is no generic `hash` key. Multi-line edits: compute the joined-lines hash yourself.
+- **Stale edits are refused, never guessed past:** mismatch → `STALE_ANCHOR` (zero window
+  matches) or `AMBIGUOUS_ANCHOR` (two matches). Default recovery `relocate` only re-anchors
+  when exactly one same-width window matches.
+- On success `newHash` is the hash of the just-written *range* (not the file) so it chains
+  directly into the next edit of the same region.
+- **Scripting gotcha:** on failure hashpilot exits **status 3 but still writes JSON to
+  stdout**. In `execSync` a throw ≠ the failure signal — check `e.status`, parse `e.stdout`.
+
+## zg CLI facts observed
+
+- **No `--json` output mode** (removed). Default is agent-markdown; parse
+  `matchedBy=… (\S+):(\d+)-(\d+)`. Production JSON lives on zg's MCP server
+  (`http://127.0.0.1:7999/mcp`, Streamable HTTP).
+- **Default embedding ranks docs over source on code queries.** `zg query "router chooses
+  edit strategy"` surfaced `*.md` before `src/core/router.ts`. Bias to source with
+  `-g '*.ts'` / a language glob (`zg query "…" -g '*.ts'`).
+- **Freshness is state-aware:** results report `fresh` or `possibly_stale`, and zg detects
+  a HashPilot write — the edit flips the index to `possibly_stale`. Good cross-tool sensing;
+  re-run same query to confirm current state.
+- Index of ~140 files / ~1300 entities builds in ~14s incl. model download.
+  Workspace index lives `<root>/.zvec-grep/`; runtime/model state lives in `ZVEC_GREP_HOME`.
+
+## Working pipeline (proven end-to-end, 2026-09-03)
+
+```
+zg query "where the router decides which edit strategy" -g '*.ts'
+  → src/core/router.ts:108-423
+hashpilot read-hash src/core/router.ts 58
+  → lineHash 940e4dd9ce34 "// 1. Check policy overrides first"
+hashpilot replace-hash src/core/router.ts 940e4dd9ce34 \
+    "  // 1. Check policy overrides first [zg→hashpilot pipeline live]" --range 58:58
+  → ok=true success=true stale=false  (Replaced 1 lines, range 58-58)
+re-run zg query → possibly_stale   (zg notices the edit)
+```
+
+Re-applying the now-stale hash was refused (`STALE_ANCHOR`, file untouched) — the anchor
+guarantees the edit lands where pointed, or not at all.
+
+## Adoption decision (kept deliberately out of HashPilot)
+
+Three coupling tiers were considered and documented:
+1. **Hard npm dependency** (`@zvec/zvec-grep` in package.json) — **rejected.** Drags the
+   embedding stack + Node 22+ into a stateless editing primitive; couples release cycles.
+2. **Optional adapter** (`hashpilot search <q>` shells to zg, greps fallback) — scoped but
+   **not built**. See `docs/PLAN-search-adapter.md` for the falsifier + TDD breakdown.
+3. **Docs-only (this file)** — adopted. The search→edit orchestration is *agent* behavior,
+   not editing-primitive behavior; it belongs outside the binary.
+
+## Environment for trying it
+
+- zg: Node 22+. `npm i -g @zvec/zvec-grep` or local install. Model downloads on first index.
+- HashPilot: Bun 1.2+.
+- For a full `/` disk, point `ZVEC_GREP_HOME` (and index the workspace) on a roomy path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigknoxy/hashpilot",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "HashPilot — Global Tool-Agnostic Structured Editing Core for Coding Agents",
   "type": "module",
   "engines": {

package/src/cli.ts

@@ -40,6 +40,7 @@ import { register as registerProvenance } from "./commands/provenance";
 import { register as registerMcp } from "./commands/mcp";
 import { register as registerMaintenance } from "./commands/maintenance";
 import { register as registerRoute } from "./commands/route";
+import { register as registerSearch } from "./commands/search";
 
 const VERSION: string = pkg.version;
 
@@ -108,6 +109,7 @@ registerProvenance(program);
 registerMcp(program);
 registerMaintenance(program);
 registerRoute(program);
+registerSearch(program);
 
 /** Node syscall codes that mean "the filesystem said no", not "HashPilot has a bug". */
 const IO_SYSCALL_CODES = new Set([

package/src/commands/search.ts

@@ -0,0 +1,70 @@
+import type { Command } from "commander";
+import {
+  search,
+  loadConfig,
+  recordEvent,
+  finish,
+  DEFAULT_SOURCE_GLOBS,
+} from "../core/index";
+import type { SearchResult } from "../core/index";
+
+/** Restrict `--engine` to the supported values; commander enforces via `.choices`. */
+const ENGINE_CHOICES = ["auto", "zg", "grep", "off"] as const;
+
+function collectGlob(value: string, previous: string[]): string[] {
+  return previous.concat([value]);
+}
+
+/** Register the `search` command group. */
+export function register(program: Command): void {
+  program
+    .command("search")
+    .description(
+      "Search a workspace: zg (zvec-grep) semantic/lexical when available, grep fallback. " +
+        "Usage: search \"<query>\" (zg) or search --engine grep \"<pattern>\" [paths...]",
+    )
+    .argument("<query>", "Query text (plain language for zg; a regex only makes sense on the grep engine)")
+    .argument("[paths...]", "Paths to search (grep engine only; zg searches its indexed workspace)")
+    .option(
+      "--engine <engine>",
+      `Search engine: ${ENGINE_CHOICES.join(", ")} (default: config or auto)`,
+      "auto",
+    )
+    .option(
+      "--glob <glob>",
+      "Source glob filter, repeatable (default: code extensions)",
+      collectGlob,
+      [] as string[],
+    )
+    .option("--zg-bin <path>", "Path to the zg binary (default: ZG_BIN env, then PATH)")
+
+    .action(async (query: string, paths: string[], opts) => {
+      const start = Date.now();
+      const config = loadConfig();
+      // Config defaults apply only when the CLI flag is left at its "auto" default.
+      const engine = (opts.engine === "auto" && config.search?.engine ? config.search.engine : opts.engine) as
+        | (typeof ENGINE_CHOICES)[number]
+        | undefined;
+      const sourceGlobs = opts.glob.length > 0 ? opts.glob : (config.search?.sourceGlobs ?? DEFAULT_SOURCE_GLOBS);
+      const zgBin = opts.zgBin ?? config.search?.zgBin;
+
+      const res: SearchResult = await search(query, paths ?? [], {
+        engine,
+        sourceGlobs,
+        zgBin,
+        root: process.cwd(),
+      });
+
+      const hitCount = res.engine === "zg" ? res.hits.length : res.results.length;
+      recordEvent({
+        operation: "search",
+        engine: res.engine,
+        hits: hitCount,
+        degraded: "degraded" in res ? Boolean(res.degraded) : false,
+        noIndex: res.engine === "zg" && Boolean(res.noIndex),
+        success: !("error" in res && res.error),
+        elapsed_ms: Date.now() - start,
+      });
+      finish(res);
+    });
+}

package/src/core/config.ts

@@ -53,11 +53,26 @@ export interface SnapshotConfig {
   maxAgeDays?: number;
 }
 
+/**
+ * Optional zg (zvec-grep) integration. zg is an external search layer — HashPilot
+ * never depends on it; these set the default behavior of `hashpilot search`.
+ * See docs/zvec-grep-integration.md.
+ */
+export interface SearchConfig {
+  /** `auto` uses zg when a binary resolves, else grep. `off` never spawns zg. */
+  engine?: "auto" | "zg" | "grep" | "off";
+  /** Only these globs are returned from zg's results. Defaults to code extensions. */
+  sourceGlobs?: string[];
+  /** Path to the zg binary. Defaults to ZG_BIN env, then PATH. */
+  zgBin?: string;
+}
+
 export interface HashPilotConfig {
   routePolicy?: RoutePolicy;
   telemetry?: TelemetryConfig;
   provenance?: ProvenanceConfig;
   snapshots?: SnapshotConfig;
+  search?: SearchConfig;
   /** Extra directories writes may target, beyond the project root. Relative entries resolve against cwd. */
   allowedRoots?: string[];
 }
@@ -183,6 +198,9 @@ function mergeConfig(base: HashPilotConfig, override: Partial<HashPilotConfig>):
   if (override.snapshots) {
     base.snapshots = { ...base.snapshots, ...override.snapshots };
   }
+  if (override.search) {
+    base.search = { ...base.search, ...override.search };
+  }
   if (override.allowedRoots) {
     base.allowedRoots = [...(base.allowedRoots || []), ...override.allowedRoots];
   }

package/src/core/index.ts

@@ -2,6 +2,8 @@ export { readMany, readHash, computeHash, computeLineHash } from "./read";
 export type { ReadResult, ReadHashResult } from "./read";
 export { grepMany, symbolLookupMany } from "./grep";
 export type { GrepResult, GrepManyResult, SymbolLookupResult } from "./grep";
+export { search, parseZgMarkdown, matchesSource, DEFAULT_SOURCE_GLOBS } from "./search";
+export type { SearchResult, SearchHit, ZgSearchResult, GrepSearchResult, SearchOptions } from "./search";
 export { replaceHash } from "./hash-edit";
 export type { ReplaceHashResult, ReplaceHashOptions } from "./hash-edit";
 export {
@@ -95,7 +97,7 @@ export type {
 export { executeIntent, executePlan } from "./plan-executor";
 export type { StepResult, PlanResult, IntentResult } from "./plan-executor";
 export { loadConfig, policyForce } from "./config";
-export type { HashPilotConfig, RoutePolicy, TelemetryConfig, ProvenanceConfig, SnapshotConfig } from "./config";
+export type { HashPilotConfig, RoutePolicy, TelemetryConfig, ProvenanceConfig, SnapshotConfig, SearchConfig } from "./config";
 export {
   recordSnapshot,
   listChangeSets,

package/src/core/search.ts

@@ -0,0 +1,228 @@
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { grepMany, type GrepResult } from "./grep";
+
+export const DEFAULT_SOURCE_GLOBS = ["*.ts", "*.js", "*.py", "*.go", "*.rs", "*.rb"];
+
+/** One semantic hit parsed from zg's agent-markdown output. */
+export interface SearchHit {
+  file: string;
+  startLine: number;
+  endLine: number;
+  symbol?: string;
+  status?: string;
+  heading?: string;
+}
+
+export interface ZgSearchResult {
+  engine: "zg";
+  query: string;
+  hits: SearchHit[];
+  elapsed_ms: number;
+  /** Set true when zg ran but the workspace index was missing. */
+  noIndex?: boolean;
+  error?: string;
+  errorCode?: "SEARCH_NO_INDEX" | "SEARCH_FAILED";
+}
+
+export interface GrepSearchResult {
+  engine: "grep";
+  query: string;
+  /** Passthrough of grep-many's own result object — result parity by construction. */
+  pattern: string;
+  results: GrepResult[];
+  error?: string;
+  /** True when zg was requested (auto/zg) but the binary was unavailable. */
+  degraded?: boolean;
+  elapsed_ms: number;
+}
+
+export type SearchResult = ZgSearchResult | GrepSearchResult;
+
+export interface SearchOptions {
+  engine?: "auto" | "zg" | "grep" | "off";
+  sourceGlobs?: string[];
+  /** Workspace root used to detect the `.zvec-grep` index (default: cwd). */
+  root?: string;
+  /** Explicit zg binary path (overrides ZG_BIN env and PATH lookup). */
+  zgBin?: string;
+}
+
+const HIT_HEADER = /^#\d+\s+(?:matchedBy=\S+?\s+)?([^:\s][^:]*?):(\d+)-(\d+)$/;
+
+/**
+ * Parse zg's agent-markdown query output into ordered `SearchHit`s.
+ *
+ * Each hit block opens with `#N matchedBy=<tags> <path>:<start>-<end>` (the
+ * matchedBy prefix is optional — some routes omit it), followed by zero or more
+ * `key: value` attribute lines (status, symbol, heading, scope) until the next
+ * `#N` header.
+ */
+export function parseZgMarkdown(text: string): SearchHit[] {
+  const hits: SearchHit[] = [];
+  let current: Partial<SearchHit> | null = null;
+
+  for (const raw of text.split("\n")) {
+    const line = raw.trimEnd();
+    const header = HIT_HEADER.exec(line);
+    if (header) {
+      if (current?.file) hits.push(current as SearchHit);
+      current = { file: header[1], startLine: Number(header[2]), endLine: Number(header[3]) };
+      continue;
+    }
+    if (!current?.file) continue;
+    const attr = /^([a-zA-Z]+):\s*(.+)$/.exec(line.trim());
+    if (attr) {
+      const key = attr[1] as "symbol" | "status" | "heading";
+      if (key === "symbol" || key === "status" || key === "heading") current[key] = attr[2];
+    }
+  }
+  if (current?.file) hits.push(current as SearchHit);
+  return hits;
+}
+
+export function matchesSource(file: string, globs: string[]): boolean {
+  if (!globs || globs.length === 0) return true;
+  return globs.some((g) => {
+    if (g.startsWith("*.")) {
+      const ext = g.slice(1); // e.g. ".ts"
+      // Check that the file's actual extension matches. We use the last "."
+      // in the final path segment as the extension boundary — same as path.extname.
+      const basename = file.split("/").pop()!;
+      const dotIdx = basename.lastIndexOf(".");
+      if (dotIdx === -1) return false;
+      return basename.slice(dotIdx) === ext;
+    }
+    return file.endsWith(g);
+  });
+}
+
+interface ZgProcessResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  timedOut?: boolean;
+  spawnError?: string;
+}
+
+function runZg(argv: string[], bin: string, timeoutMs = 60_000): Promise<ZgProcessResult> {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const done = (result: ZgProcessResult) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    try {
+      const proc = spawn(bin, argv, { stdio: ["ignore", "pipe", "pipe"] });
+      const timer = setTimeout(() => {
+        proc.kill("SIGKILL");
+        done({ stdout, stderr, code: null, timedOut: true });
+      }, timeoutMs);
+      proc.stdout.on("data", (d) => (stdout += d));
+      proc.stderr.on("data", (d) => (stderr += d));
+      proc.on("error", (err) => done({ stdout, stderr, code: null, spawnError: err.message }));
+      proc.on("close", (code) => {
+        clearTimeout(timer);
+        done({ stdout, stderr, code });
+      });
+    } catch (err: unknown) {
+      done({ stdout, stderr, code: null, spawnError: err instanceof Error ? err.message : String(err) });
+    }
+  });
+}
+
+function resolveZgBinary(zgBin?: string): string | undefined {
+  const explicit = zgBin || process.env.ZG_BIN;
+  if (explicit) return explicit;
+  const pathDirs = (process.env.PATH || "").split(":");
+  for (const dir of pathDirs) {
+    if (dir && existsSync(join(dir, "zg"))) return join(dir, "zg");
+  }
+  return undefined;
+}
+
+/** The search command surface for `hashpilot search`. */
+export async function search(query: string, paths: string[], opts: SearchOptions = {}): Promise<SearchResult> {
+  const start = Date.now();
+  const queryGlobs = opts.sourceGlobs ?? DEFAULT_SOURCE_GLOBS;
+  const engine: "auto" | "zg" | "grep" | "off" = opts.engine ?? "auto";
+  const searchRoots = paths.length ? paths : ["."];
+
+  const zgBin = resolveZgBinary(opts.zgBin);
+  const zgUsable = !!zgBin && existsSync(zgBin);
+
+  // Which engine do we run? "off" means search is disabled — return empty immediately.
+  // "grep" never touches zg. "auto" prefers zg when available. "zg" uses zg but
+  // degrades to grep rather than failing (F2): a misconfigured / missing binary
+  // must not hard-crash the search command.
+  if (engine === "off") {
+    return {
+      engine: "grep",
+      query,
+      pattern: "",
+      results: [],
+      degraded: false,
+      elapsed_ms: Date.now() - start,
+    };
+  }
+  const engineIsGrep = engine === "grep";
+  const degraded = engineIsGrep ? false : !zgUsable;
+  const useZg = !engineIsGrep && zgUsable;
+
+  if (!useZg) {
+    const grepRes = await grepMany(query, searchRoots);
+    return {
+      engine: "grep",
+      query,
+      pattern: grepRes.pattern,
+      results: grepRes.results,
+      error: grepRes.error,
+      degraded,
+      elapsed_ms: Date.now() - start,
+    };
+  }
+
+  const root = opts.root ?? process.cwd();
+  if (!existsSync(join(root, ".zvec-grep"))) {
+    return {
+      engine: "zg",
+      query,
+      hits: [],
+      noIndex: true,
+      errorCode: "SEARCH_NO_INDEX",
+      error: "No zg index found in this workspace. Run `zg index` first, then retry.",
+      elapsed_ms: Date.now() - start,
+    };
+  }
+
+  const args = ["query", query];
+  for (const g of queryGlobs) args.push("-g", g);
+  const { stdout, stderr, code, timedOut, spawnError } = await runZg(args, zgBin!);
+
+  if (code !== 0) {
+    if (code === 1 && !stderr) {
+      // zg mirrors ripgrep: exit 1 with no stderr = no matches.
+      return { engine: "zg", query, hits: [], elapsed_ms: Date.now() - start };
+    }
+    const diagnostic = timedOut
+      ? `zg timed out after 60s`
+      : spawnError
+        ? `zg spawn failed: ${spawnError}`
+        : (stderr || stdout || "zg exited unsuccessfully");
+    return {
+      engine: "zg",
+      query,
+      hits: [],
+      errorCode: "SEARCH_FAILED",
+      error: diagnostic.slice(0, 300),
+      elapsed_ms: Date.now() - start,
+    };
+  }
+
+  const parsed = parseZgMarkdown(stdout).filter((h) => matchesSource(h.file, queryGlobs));
+  return { engine: "zg", query, hits: parsed, elapsed_ms: Date.now() - start };
+}