@bigknoxy/hashpilot 4.6.6 → 4.8.0

package/README.md

@@ -175,8 +175,9 @@ silent one.
 ### Upgrade
 
 ```bash
-hashpilot upgrade          # upgrade to latest from main
+hashpilot upgrade          # upgrade to the latest npm release (falls back to GitHub if npm is unreachable)
 hashpilot upgrade --dry-run  # preview what would happen
+hashpilot upgrade --channel some-branch  # bleeding-edge: install that exact git branch instead, skipping npm
 ```
 
 ### Uninstall
@@ -357,7 +358,7 @@ diffable, and CI fails on any case that regresses from green.
 
 | Command | What It Does |
 |---------|-------------|
-| `upgrade [--dry-run] [--channel <branch>] [--target <dir>] [--keep-telemetry] [--force]` | Upgrade HashPilot from GitHub to latest version |
+| `upgrade [--dry-run] [--channel <branch>] [--target <dir>] [--keep-telemetry] [--force]` | Upgrade HashPilot to the latest version — npm by default, falling back to GitHub; `--channel <branch>` installs that exact git branch instead |
 
 ### Edit — Hash Route
 

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
 
@@ -765,7 +765,7 @@ hashpilot doctor [options]
 
 #### `upgrade`
 
-Upgrade HashPilot to the latest version from GitHub
+Upgrade HashPilot to the latest version (npm, falling back to GitHub)
 
 ```
 hashpilot upgrade [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.6.6",
+  "version": "4.8.0",
   "description": "HashPilot — Global Tool-Agnostic Structured Editing Core for Coding Agents",
   "type": "module",
   "engines": {

package/scripts/install.sh

@@ -14,37 +14,233 @@ warn() { printf "${YELLOW}[hashpilot]${NC} %s\n" "$1"; }
 err()  { printf "${RED}[hashpilot]${NC} %s\n" "$1"; }
 detail() { printf "${DIM}  →${NC} %s\n" "$1"; }
 
+# Single source of truth for the "use npm, not an explicit git ref" sentinel
+# — referenced in this file and (as a literal, since it's a separate process)
+# in src/commands/maintenance.ts's `--channel` default; keep both in sync.
+DEFAULT_CHANNEL="main"
+
+# None of this script's network calls bounded how long they'd wait — a host
+# that accepts the TCP connection but never responds (common for corporate
+# proxies blocking a specific destination, which is the exact scenario the
+# npm-registry fallback below exists for) hung the installer indefinitely
+# instead of ever reaching that fallback.
+CURL_META_OPTS=(--connect-timeout 10 --max-time 20)
+CURL_DOWNLOAD_OPTS=(--connect-timeout 10 --max-time 300)
+
+# Extract one string field's value from a small JSON blob (grep+sed, no jq
+# dependency, matching this script's existing style) — centralized so every
+# call site gets the same handling instead of each reinventing it slightly
+# differently. Pass "url" as $3 to additionally require the value look like
+# a real http(s) URL: the naive sed substitution only fires on a genuine
+# match, so a non-URL value (empty, relative, a mirror that rewrites the
+# field to something else) would otherwise silently pass the whole
+# grep-matched line through unchanged — still non-empty, so it would pass a
+# bare `-n` check as if it were real.
+json_field() {
+  local json="$1" field="$2" require="${3:-}" value
+  value=$(echo "$json" | grep -o "\"${field}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -1 \
+    | sed "s/.*\"${field}\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\"/\\1/" || true)
+  if [ "$require" = "url" ]; then
+    case "$value" in
+      https://*|http://*) ;;
+      *) value="" ;;
+    esac
+  fi
+  echo "$value"
+}
+
+# Download a tarball to a temp file (verifying its sha1 against $3 first, if
+# given — npm's registry metadata includes one for free), then extract it.
+# Shared by the npm and GitHub source fetches below so hardening (timeouts,
+# checksum verification) only has to be added once. Leaves nothing behind
+# and returns non-zero on any failure: download, checksum mismatch, or
+# extraction — every failure mode here is handled identically by the caller
+# (fall back to the next source), so there is no reason for them to differ.
+fetch_and_extract_tarball() {
+  local url="$1" dest_dir="$2" expected_sha1="${3:-}" tmp_tarball
+  tmp_tarball="$(mktemp)"
+  if ! curl -fsSL "${CURL_DOWNLOAD_OPTS[@]}" "$url" -o "$tmp_tarball" 2>/dev/null; then
+    rm -f "$tmp_tarball"
+    return 1
+  fi
+  if [ -n "$expected_sha1" ]; then
+    local actual_sha1
+    # `sha1sum` is GNU coreutils only — stock macOS (BSD userland) has
+    # `shasum -a 1` instead, and neither exists on some minimal containers,
+    # where `openssl sha1` is the last resort. Checking only for `sha1sum`
+    # made every npm-path checksum check fail on macOS, silently forcing
+    # every install/upgrade there onto the GitHub fallback — defeating this
+    # PR's actual point on a major platform.
+    if command -v sha1sum >/dev/null 2>&1; then
+      actual_sha1="$(sha1sum "$tmp_tarball" 2>/dev/null | awk '{print $1}')"
+    elif command -v shasum >/dev/null 2>&1; then
+      actual_sha1="$(shasum -a 1 "$tmp_tarball" 2>/dev/null | awk '{print $1}')"
+    elif command -v openssl >/dev/null 2>&1; then
+      actual_sha1="$(openssl sha1 "$tmp_tarball" 2>/dev/null | awk '{print $NF}')"
+    else
+      # Fail closed, not open: forging a match here would silently disable
+      # the integrity guarantee this whole check exists for. Returning
+      # failure instead routes through this function's normal
+      # failure-handling — the caller already treats that identically to a
+      # checksum mismatch or a failed download, falling back to the GitHub
+      # source rather than installing something unverified.
+      warn "no sha1sum/shasum/openssl found; cannot verify tarball checksum"
+      rm -f "$tmp_tarball"
+      return 1
+    fi
+    if [ "$actual_sha1" != "$expected_sha1" ]; then
+      warn "tarball checksum mismatch (expected ${expected_sha1}, got ${actual_sha1:-<none>})"
+      rm -f "$tmp_tarball"
+      return 1
+    fi
+  fi
+  if ! tar -xz -C "$dest_dir" --strip-components=1 -f "$tmp_tarball" 2>&1 | while IFS= read -r line; do detail "$line"; done; then
+    rm -f "$tmp_tarball"
+    return 1
+  fi
+  rm -f "$tmp_tarball"
+}
+
 # ── Detect source directory ──────────────────────────────────────────────
 REMOTE_MODE=false
 SOURCE_DIR=""
+# Declared here (not just inside the remote-mode block below) so the
+# dependency-install step can use it as the authoritative "did this come
+# from npm" signal — local-clone mode and the GitHub-fallback path both
+# leave it false, which is correct for both.
+NPM_INSTALLED=false
+
+# An explicit --source wins over everything else, checked here (before the
+# real argument-parsing loop below, which runs too late for this) so that
+# passing --source skips local-clone detection AND the auto-download below
+# entirely — downloading anything when the caller already told us exactly
+# where the source is would be pure waste, and previously caused a real bug:
+# HASHPILOT_VERSION got read from the auto-fetched npm/GitHub tarball, not
+# from the --source directory that was actually installed, silently
+# mislabeling the manifest/version banner whenever the two versions differed.
+# No `break`: --source given twice must resolve to the SAME occurrence the
+# real argument-parsing loop below honors (it keeps the last one), or the
+# version/manifest would be read from one directory while the actual
+# install copies from another — reintroducing the exact class of mismatch
+# this pre-scan exists to prevent.
+EXPLICIT_SOURCE=""
+_ARGV=("$@")
+for ((_i = 0; _i < ${#_ARGV[@]}; _i++)); do
+  if [ "${_ARGV[$_i]}" = "--source" ] && [ $((_i + 1)) -lt ${#_ARGV[@]} ]; then
+    EXPLICIT_SOURCE="${_ARGV[$((_i + 1))]}"
+  fi
+done
 
+if [ -n "$EXPLICIT_SOURCE" ]; then
+  SOURCE_DIR="$EXPLICIT_SOURCE"
 # Try to resolve from script location (local clone mode)
-if SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd 2>/dev/null)"; then
+elif SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd 2>/dev/null)"; then
   REPO_ROOT="$(cd "$SCRIPT_DIR/.." 2>/dev/null && pwd 2>/dev/null || echo "")"
   if [ -n "$REPO_ROOT" ] && [ -f "$REPO_ROOT/package.json" ]; then
     SOURCE_DIR="$REPO_ROOT"
   fi
 fi
 
-# No local source — download release tarball from GitHub (curl-pipe / remote mode)
+# No local source — fetch a tarball (curl-pipe / remote mode).
+#
+# Primary source is the published npm package: it's the tested, minimal
+# artifact (no devDependencies, no tests/docs bloat — see
+# tests/packaging.test.ts for what it guarantees ships) instead of the full
+# git source tree, and it stops this installer silently drifting from the
+# npm distribution channel now that publishing actually works (#193). Only
+# curl is used — no `npm`/`node` binary required, since bun is this script's
+# only external prerequisite.
+#
+# Falls back to the GitHub source tarball (release tag, or a branch) when:
+#   - the npm registry is unreachable or the package/version can't be found
+#     (offline-but-git-reachable environments, corporate proxies that allow
+#     github.com but not registry.npmjs.org), or
+#   - HASHPILOT_SOURCE_CHANNEL is set to something other than "main" — an
+#     explicit non-default channel (e.g. `hashpilot upgrade --channel
+#     some-branch`) means the user wants that exact git ref, which npm's
+#     published releases can't provide.
+#
+# HASHPILOT_NPM_REGISTRY overrides the registry base URL — used by tests to
+# deterministically force the npm path to fail without relying on a real
+# outage, and by anyone behind an npm registry mirror/proxy.
 if [ -z "$SOURCE_DIR" ]; then
   REMOTE_MODE=true
   CLONE_DIR=$(mktemp -d)
-  
-  # Determine version to download (latest release)
-  log "Fetching latest release info from GitHub..."
-  RELEASE_INFO=$(curl -fsSL "https://api.github.com/repos/bigknoxy/HashPilot/releases/latest" 2>/dev/null || echo "")
-  TAG_NAME=$(echo "$RELEASE_INFO" | grep '"tag_name"' | head -1 | sed 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)
-  if [ -n "$TAG_NAME" ]; then
-    TARBALL_URL="https://github.com/bigknoxy/HashPilot/archive/refs/tags/${TAG_NAME}.tar.gz"
-    log "Downloading HashPilot ${TAG_NAME} from GitHub..."
-  else
-    # Fallback to main branch if no release
-    TARBALL_URL="https://github.com/bigknoxy/HashPilot/archive/refs/heads/main.tar.gz"
-    log "Downloading HashPilot from main branch..."
+  # A stale HASHPILOT_SOURCE_CHANNEL already exported in the caller's shell
+  # (or a CI job's environment) must not silently override the channel the
+  # user actually asked for on THIS invocation — src/commands/maintenance.ts
+  # always sets this explicitly (to "" on the default channel) precisely so
+  # `${HASHPILOT_SOURCE_CHANNEL:-$DEFAULT_CHANNEL}` can't see a leftover
+  # value from a previous run, but default it defensively here too for
+  # anyone invoking install.sh directly rather than through `hashpilot
+  # upgrade`.
+  SOURCE_CHANNEL="${HASHPILOT_SOURCE_CHANNEL:-$DEFAULT_CHANNEL}"
+  [ -z "$SOURCE_CHANNEL" ] && SOURCE_CHANNEL="$DEFAULT_CHANNEL"
+  NPM_REGISTRY="${HASHPILOT_NPM_REGISTRY:-https://registry.npmjs.org}"
+  NPM_INSTALLED=false
+
+  if [ "$SOURCE_CHANNEL" = "$DEFAULT_CHANNEL" ]; then
+    log "Fetching latest release info from npm..."
+    NPM_INFO=$(curl -fsSL "${CURL_META_OPTS[@]}" "${NPM_REGISTRY}/@bigknoxy/hashpilot/latest" 2>/dev/null || echo "")
+    NPM_TARBALL_URL="$(json_field "$NPM_INFO" "tarball" url)"
+    NPM_VERSION="$(json_field "$NPM_INFO" "version")"
+    NPM_SHASUM="$(json_field "$NPM_INFO" "shasum")"
+    if [ -n "$NPM_TARBALL_URL" ]; then
+      log "Downloading HashPilot v${NPM_VERSION} from npm..."
+      # A tarball can download, checksum-verify, and extract cleanly while
+      # still being useless — e.g. a registry response that resolved to
+      # some unrelated but validly-formed archive. Require a package.json
+      # to actually be there before trusting this source; otherwise every
+      # later step (the version read right after this block especially)
+      # fails with a bare, undiagnosed exit instead of falling back like
+      # every other failure mode here does.
+      if fetch_and_extract_tarball "$NPM_TARBALL_URL" "$CLONE_DIR" "$NPM_SHASUM"; then
+        if [ -f "$CLONE_DIR/package.json" ]; then
+          NPM_INSTALLED=true
+        else
+          warn "npm tarball extracted but had no package.json; falling back to GitHub source"
+        fi
+      else
+        warn "npm tarball download/extract failed; falling back to GitHub source"
+      fi
+      if [ "$NPM_INSTALLED" = "false" ]; then
+        rm -rf "$CLONE_DIR"
+        CLONE_DIR=$(mktemp -d)
+      fi
+    else
+      warn "npm registry unreachable or package not found; falling back to GitHub source"
+    fi
   fi
-  
-  curl -fsSL "$TARBALL_URL" | tar -xz -C "$CLONE_DIR" --strip-components=1 2>&1 | while IFS= read -r line; do detail "$line"; done
+
+  if [ "$NPM_INSTALLED" = "false" ]; then
+    if [ "$SOURCE_CHANNEL" = "$DEFAULT_CHANNEL" ]; then
+      log "Fetching latest release info from GitHub..."
+      RELEASE_INFO=$(curl -fsSL "${CURL_META_OPTS[@]}" "https://api.github.com/repos/bigknoxy/HashPilot/releases/latest" 2>/dev/null || echo "")
+      TAG_NAME="$(json_field "$RELEASE_INFO" "tag_name")"
+      if [ -n "$TAG_NAME" ]; then
+        TARBALL_URL="https://github.com/bigknoxy/HashPilot/archive/refs/tags/${TAG_NAME}.tar.gz"
+        log "Downloading HashPilot ${TAG_NAME} from GitHub..."
+      else
+        # Fallback to main branch if no release
+        TARBALL_URL="https://github.com/bigknoxy/HashPilot/archive/refs/heads/main.tar.gz"
+        log "Downloading HashPilot from main branch..."
+      fi
+    else
+      TARBALL_URL="https://github.com/bigknoxy/HashPilot/archive/refs/heads/${SOURCE_CHANNEL}.tar.gz"
+      log "Downloading HashPilot from branch ${SOURCE_CHANNEL}..."
+    fi
+
+    # This is the last fallback — nothing after this if it fails — so an
+    # unguarded call here would let `set -e` kill the script with a bare,
+    # undiagnosed exit instead of the clear, actionable message every other
+    # failure mode in this block already gets.
+    if ! fetch_and_extract_tarball "$TARBALL_URL" "$CLONE_DIR"; then
+      err "Failed to download or extract HashPilot from ${TARBALL_URL}"
+      err "Check your network connection, or that '${SOURCE_CHANNEL}' is a real branch/tag."
+      exit 1
+    fi
+  fi
+
   SOURCE_DIR="$CLONE_DIR"
   detail "Extracted to $CLONE_DIR"
 fi
@@ -71,13 +267,18 @@ while [ $# -gt 0 ]; do
       echo "HashPilot Installer v${HASHPILOT_VERSION}"
       echo "Usage: $0 [options]"
       echo "  --source <dir>     Source directory (default: repo root)."
-      echo "                     If omitted and no local source found,"
-      echo "                     auto-downloads release tarball from GitHub."
+      echo "                     If omitted and no local source found, auto-downloads"
+      echo "                     from npm (falls back to the GitHub release/main tarball"
+      echo "                     if npm is unreachable)."
       echo "  --target <dir>     Install target (default: ~/.agentic-tools)"
       echo "  --keep-telemetry   Preserve existing telemetry on reinstall"
       echo '  --force, -f        Overwrite existing install without any prompt (including the non-interactive existing-install notice)'
       echo "  --help, -h         Show this help"
       echo ""
+      echo "Env vars: HASHPILOT_SOURCE_CHANNEL=<branch> skips npm and installs that exact"
+      echo "          git branch instead (e.g. for bleeding-edge testing)."
+      echo "          HASHPILOT_NPM_REGISTRY=<url> overrides the npm registry base URL."
+      echo ""
       echo "One-liner: curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/install.sh | bash"
       exit 0
       ;;
@@ -186,9 +387,50 @@ detail "Core source copied to $TARGET_DIR/structured-editing"
 
 # ── Install dependencies ────────────────────────────────────────────────
 log "Installing dependencies..."
-cd "$TARGET_DIR/structured-editing"
-bun install --frozen-lockfile 2>&1 | while IFS= read -r line; do detail "$line"; done
-cd "$OLDPWD"
+# Decide frozen-vs-production from $SOURCE_DIR (what we just copied FROM),
+# not from whatever bun.lock might already be sitting in the target
+# directory. The rsync fallback for hosts without rsync (`cp -r`, a few
+# lines up) does not delete files absent from the source — an upgrade from
+# a prior git-sourced install (which does ship bun.lock) to a new npm-
+# sourced one (which doesn't) would otherwise leave the old lockfile
+# behind, be found by a target-relative `[ -f bun.lock ]` check, and run
+# --frozen-lockfile against the npm package's own package.json — which
+# never matches, and hard-aborts the upgrade after node_modules has
+# already been removed, leaving no working install at all.
+#
+# $NPM_INSTALLED (set above, always defined regardless of which branch was
+# taken) is the authoritative signal for "this came from npm and has no
+# lockfile" — cross-checked against bun.lock's presence rather than relied
+# on alone, so a future source shape that disagrees with what we expect
+# (e.g. an npm extraction that somehow shipped a lockfile, or a git/local
+# source that's missing one) fails loudly here instead of silently
+# guessing.
+if [ "$NPM_INSTALLED" = "true" ] && [ -f "$SOURCE_DIR/bun.lock" ]; then
+  err "npm-sourced install unexpectedly has a bun.lock — refusing to guess which dependency mode is correct"
+  exit 1
+fi
+if [ "$NPM_INSTALLED" = "false" ] && [ ! -f "$SOURCE_DIR/bun.lock" ]; then
+  err "Source is missing bun.lock and wasn't installed from npm — refusing to guess which dependency mode is correct"
+  err "(local-clone and --source installs are expected to have bun.lock, same as the git repo does)"
+  exit 1
+fi
+
+if [ -f "$SOURCE_DIR/bun.lock" ]; then
+  cd "$TARGET_DIR/structured-editing"
+  bun install --frozen-lockfile 2>&1 | while IFS= read -r line; do detail "$line"; done
+  cd "$OLDPWD"
+else
+  # The npm-published package.json still lists devDependencies (npm's
+  # `files` field controls which FILES ship, not which package.json fields
+  # do) — a plain `bun install` would resolve and install semantic-release,
+  # fast-check, and the rest of the dev toolchain for no reason on an end
+  # user's machine. --production skips them; the CLI never needs them.
+  detail "No bun.lock shipped (npm package install) — resolving production dependencies fresh"
+  rm -f "$TARGET_DIR/structured-editing/bun.lock"
+  cd "$TARGET_DIR/structured-editing"
+  bun install --production 2>&1 | while IFS= read -r line; do detail "$line"; done
+  cd "$OLDPWD"
+fi
 detail "Dependencies installed"
 
 # ── Create CLI launcher ──────────────────────────────────────────────────

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/maintenance.ts

@@ -25,7 +25,7 @@ export function register(program: Command): void {
 
   program
     .command("upgrade")
-    .description("Upgrade HashPilot to the latest version from GitHub")
+    .description("Upgrade HashPilot to the latest version (npm, falling back to GitHub)")
     .option("--channel <channel>", "Release channel (default: main)", "main")
     .option("--target <dir>", "Install target directory (default: ~/.agentic-tools)")
     .option("--keep-telemetry", "Preserve existing telemetry on upgrade")
@@ -55,8 +55,12 @@ export function register(program: Command): void {
         }
         const script = await response.text();
 
-        // Write script to temp file and execute
+        // Write script to temp file and execute. targetDir may not exist yet
+        // on a genuinely first-time install (the `uninstall` command below
+        // already does this — `upgrade` didn't, and failed with a plain
+        // ENOENT on a brand-new target).
         const tmpScript = join(targetDir, `.hashpilot-upgrade-${Date.now()}.sh`);
+        mkdirSync(targetDir, { recursive: true });
         writeFileSync(tmpScript, script, { mode: 0o755 });
 
         const args = ["--target", targetDir];
@@ -66,7 +70,20 @@ export function register(program: Command): void {
         const proc = Bun.spawn(["bash", tmpScript, ...args], {
           stdout: "pipe",
           stderr: "pipe",
-          env: { ...process.env, PATH: `${join(targetDir, "bin")}:${process.env.PATH || ""}` },
+          env: {
+            ...process.env,
+            PATH: `${join(targetDir, "bin")}:${process.env.PATH || ""}`,
+            // Always set explicitly (never omitted) so a stale
+            // HASHPILOT_SOURCE_CHANNEL already exported in the caller's
+            // shell or a CI job's environment can't silently override the
+            // channel actually requested on *this* invocation — install.sh
+            // skips its npm-primary source fetch entirely when this is set
+            // to anything other than "main", since npm's published releases
+            // can't provide an arbitrary git ref, so an inherited stale
+            // value would silently install from git instead of npm with no
+            // warning at all.
+            HASHPILOT_SOURCE_CHANNEL: channel === "main" ? "" : channel,
+          },
         });
 
         const stdout = await new Response(proc.stdout).text();

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 };
+}