harnery 0.7.0 → 0.8.0

package/dist/commands/grep.js

@@ -1,12 +1,26 @@
 import { spawn } from "node:child_process";
+import { resolveSearchEngine } from "../lib/tools/ripgrep.js";
 /**
- * `grep`: monorepo-aware code search. Thin wrapper over grep -rn with
- * smart default excludes (skip dist/.next/node_modules/.git/...), repo
+ * `grep`: monorepo-aware code search. Prefers ripgrep (`rg`) when it is on
+ * PATH and falls back to GNU `grep -rn` transparently — both engines are
+ * driven with equivalent flags and their output is parsed into the same
+ * envelope, so results are identical (pinned by tests/unit/grep-engine.test.ts).
+ * Smart default excludes (skip dist/.next/node_modules/.git/...), repo
  * scoping (`--repo <name>` or `--all-repos`), and language presets.
  *
- * Default behavior matches grep's "regex" semantics (`-E` extended). Use
- * `-F` / `--literal` to pin to literal-string mode. Output is line-oriented
- * `file:line:content` in TTY mode, `{rows, total, truncated}` in --json mode.
+ * Engine selection: `HARNERY_GREP_ENGINE=rg|grep` forces one; otherwise `rg`
+ * is resolved (managed install, PATH, or opt-in auto-provision; see resolveEngine) and used when available. Repos are searched in
+ * parallel, and in `--all-repos` mode the parent scan prunes submodule
+ * directories so each match is attributed to exactly one repo (previously the
+ * parent scan descended into submodules, double-scanning and double-reporting
+ * every submodule match).
+ *
+ * Default behavior matches extended-regex semantics (`grep -E` / ripgrep's
+ * default). Use `-F` / `--literal` to pin to literal-string mode. Output is
+ * line-oriented `file:line:content` in TTY mode, `{rows, total, truncated}`
+ * in --json mode. Matches are sorted (file, then line) for stable output
+ * across runs and engines; with `-C <n>` context, engine order is kept so
+ * context groups stay adjacent.
  */
 const DEFAULT_EXCLUDE_DIRS = [
     ".git",
@@ -47,7 +61,8 @@ const LANG_GLOBS = {
 export function registerGrepCommand(program, emit, context) {
     program
         .command("grep <pattern> [paths...]")
-        .description("Monorepo-aware code search. Skips dist/.next/node_modules/.git/... by default. " +
+        .description("Monorepo-aware code search (ripgrep when available, GNU grep fallback). " +
+        "Skips dist/.next/node_modules/.git/... by default. " +
         "Use --repo, --all-repos, --lang for scoping. Regex by default; -F for literal.")
         .option("--repo <name>", "Scope to one submodule (`.` = parent repo root)")
         .option("--all-repos", "Search parent + every submodule")
@@ -56,6 +71,8 @@ export function registerGrepCommand(program, emit, context) {
         .option("-w, --whole-word", "Match whole words only")
         .option("-F, --literal", "Treat <pattern> as a literal string (no regex)")
         .option("-l, --files-only", "Only print file names containing a match")
+        .option("--files", "Filename search: treat <pattern> as a filename glob and list matching files " +
+        "(rg --files when available, POSIX find fallback)")
         .option("-c, --count", "Print match count per file (suppresses content)")
         .option("-C, --context <n>", "Print N lines of context around each match", "0")
         .option("--max-count <n>", "Stop after N matches per file")
@@ -83,33 +100,72 @@ export function registerGrepCommand(program, emit, context) {
 function collect(value, prev) {
     return [...prev, value];
 }
-async function runGrep(pattern, paths, opts, context) {
+/** Exported for tests (not part of the package exports map). */
+export async function runGrep(pattern, paths, opts, context) {
     if (!pattern)
         throw new Error("pattern required");
+    if (opts.files) {
+        // Filename mode lists files by name glob; content-search flags make no
+        // sense here — reject loudly rather than silently ignoring them.
+        const incompatible = [
+            [opts.lang, "--lang"],
+            [opts.count, "-c/--count"],
+            [opts.wholeWord, "-w/--whole-word"],
+            [opts.literal, "-F/--literal"],
+            [opts.maxCount, "--max-count"],
+            [opts.include?.length, "--include"],
+            [Number.parseInt(opts.context ?? "0", 10) > 0 ? true : undefined, "-C/--context"],
+        ];
+        for (const [set, flag] of incompatible) {
+            if (set)
+                throw new Error(`${flag} does not apply to --files (filename glob) mode`);
+        }
+    }
     const started = Date.now();
+    const { engine, rgBin } = await resolveSearchEngine("grep");
     const repos = resolveRepos(opts, context);
     const limit = opts.limit ? Number.parseInt(opts.limit, 10) : Number.POSITIVE_INFINITY;
+    const contextN = Number.parseInt(opts.context ?? "0", 10);
+    const sortable = !(Number.isFinite(contextN) && contextN > 0);
+    // Host-injected default excludes (generated mirrors, vendored trees, ...)
+    // ride the same --no-default-excludes gate as the built-in list.
+    const hostExcludeDirs = opts.noDefaultExcludes ? [] : (context?.grepExcludeDirs ?? []);
+    // All repos are searched concurrently; each is capped at the global limit
+    // (a single repo can never contribute more), then the global budget is
+    // applied in repo order below so `--limit` semantics stay deterministic.
+    const perRepo = await Promise.all(repos.map((repo) => {
+        // In --all-repos mode the parent scan prunes submodule dirs — each
+        // submodule gets its own scoped scan, so descending from the parent
+        // would double-scan and double-report every submodule match. This
+        // pruning is correctness (one repo owns each match), so it applies
+        // even when --no-default-excludes is set.
+        const dedupeDirs = opts.allRepos && repo.name === "parent" ? (context?.submodules ?? []) : [];
+        const extraDirs = [...hostExcludeDirs, ...dedupeDirs];
+        return runGrepInRepo(pattern, paths, opts, repo.cwd, repo.name, limit, engine, rgBin, extraDirs);
+    }));
     const allRepoResults = [];
     let totalMatches = 0;
     const filesSeen = new Set();
     let truncated = false;
-    for (const repo of repos) {
-        if (truncated)
-            break;
-        const repoLimit = Number.isFinite(limit)
-            ? Math.max(0, limit - totalMatches)
-            : Number.POSITIVE_INFINITY;
-        if (repoLimit === 0) {
-            truncated = true;
-            allRepoResults.push({ name: repo.name, cwd: repo.cwd, matches: [], truncated: true });
-            break;
+    let budget = limit;
+    for (let i = 0; i < repos.length; i++) {
+        const repo = repos[i];
+        if (!repo)
+            continue;
+        const collected = perRepo[i] ?? [];
+        if (sortable) {
+            collected.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
         }
-        const matches = await runGrepInRepo(pattern, paths, opts, repo.cwd, repo.name, repoLimit);
-        let repoTruncated = false;
-        if (Number.isFinite(repoLimit) && matches.length >= repoLimit) {
-            repoTruncated = true;
+        const engineCapped = Number.isFinite(limit) && collected.length >= limit;
+        const take = Number.isFinite(budget)
+            ? Math.min(collected.length, Math.max(0, budget))
+            : collected.length;
+        const matches = collected.slice(0, take);
+        const repoTruncated = engineCapped || collected.length > take;
+        if (repoTruncated)
             truncated = true;
-        }
+        if (Number.isFinite(budget))
+            budget -= take;
         totalMatches += matches.length;
         for (const m of matches)
             filesSeen.add(`${repo.name}/${m.file}`);
@@ -117,7 +173,8 @@ async function runGrep(pattern, paths, opts, context) {
     }
     return {
         pattern,
-        mode: opts.literal ? "literal" : "regex",
+        mode: opts.files ? "files" : opts.literal ? "literal" : "regex",
+        engine,
         repos: allRepoResults,
         total_matches: totalMatches,
         total_files: filesSeen.size,
@@ -155,8 +212,32 @@ function resolveRepos(opts, context) {
     }
     return [{ name: "cwd", cwd: process.cwd() }];
 }
-async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit) {
-    const args = ["-rn", "--color=never", "-I"]; // -I: skip binary files
+async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit, engine, rgBin, extraExcludeDirs) {
+    // Filename mode: `rg --files` when available; POSIX `find` otherwise (GNU
+    // grep has no list-by-name mode). Content mode: rg / grep as selected.
+    const [bin, args] = opts.files
+        ? engine === "rg"
+            ? [rgBin, buildRgFilesArgs(pattern, paths, opts, extraExcludeDirs)]
+            : ["find", buildFindArgs(pattern, paths, opts, extraExcludeDirs)]
+        : engine === "rg"
+            ? [rgBin, buildRgArgs(pattern, paths, opts, extraExcludeDirs)]
+            : ["grep", buildGrepArgs(pattern, paths, opts, extraExcludeDirs)];
+    let matches = await execSearch(bin, args, cwd, limit);
+    // -c mode: GNU grep prints a `path:0` row for every searched file; ripgrep
+    // omits zero-count rows. Filter zeros on both engines so output matches.
+    if (opts.count)
+        matches = matches.filter((m) => m.line > 0);
+    return matches.map((m) => ({ ...m, repo: repoName }));
+}
+function resolveLangGlobs(opts) {
+    const langGlobs = opts.lang ? LANG_GLOBS[opts.lang] : undefined;
+    if (opts.lang && !langGlobs) {
+        throw new Error(`unknown --lang "${opts.lang}". Valid: ${Object.keys(LANG_GLOBS).join(", ")}`);
+    }
+    return langGlobs;
+}
+function buildGrepArgs(pattern, paths, opts, extraExcludeDirs) {
+    const args = ["-rn", "-H", "--color=never", "-I"]; // -I: skip binary files
     if (opts.ignoreCase)
         args.push("-i");
     if (opts.wholeWord)
@@ -183,12 +264,11 @@ async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit) {
         for (const f of DEFAULT_EXCLUDE_FILES)
             args.push(`--exclude=${f}`);
     }
+    for (const d of extraExcludeDirs)
+        args.push(`--exclude-dir=${d}`);
     for (const e of opts.exclude ?? [])
         args.push(`--exclude=${e}`);
-    const langGlobs = opts.lang ? LANG_GLOBS[opts.lang] : undefined;
-    if (opts.lang && !langGlobs) {
-        throw new Error(`unknown --lang "${opts.lang}". Valid: ${Object.keys(LANG_GLOBS).join(", ")}`);
-    }
+    const langGlobs = resolveLangGlobs(opts);
     if (langGlobs)
         for (const g of langGlobs)
             args.push(`--include=${g}`);
@@ -199,12 +279,125 @@ async function runGrepInRepo(pattern, paths, opts, cwd, repoName, limit) {
         args.push(...paths);
     else
         args.push(".");
-    const matches = await execGrep(args, cwd, limit);
-    return matches.map((m) => ({ ...m, repo: repoName }));
+    return args;
 }
-function execGrep(args, cwd, limit) {
+function buildRgArgs(pattern, paths, opts, extraExcludeDirs) {
+    // --hidden --no-ignore: match GNU grep's semantics (search dotdirs, ignore
+    // .gitignore) so the only filters are the explicit exclude lists.
+    // --no-config: a user's ripgrep config file must not skew results.
+    // --with-filename: rg drops the file prefix for a single explicit file arg,
+    // which would break the shared parser.
+    const args = [
+        "-n",
+        "--no-heading",
+        "--with-filename",
+        "--color=never",
+        "--no-config",
+        "--hidden",
+        "--no-ignore",
+    ];
+    if (opts.ignoreCase)
+        args.push("-i");
+    if (opts.wholeWord)
+        args.push("-w");
+    if (opts.literal)
+        args.push("-F");
+    if (opts.filesOnly)
+        args.push("-l");
+    if (opts.count)
+        args.push("-c");
+    const contextN = Number.parseInt(opts.context ?? "0", 10);
+    if (Number.isFinite(contextN) && contextN > 0)
+        args.push(`-C${contextN}`);
+    if (opts.maxCount) {
+        const n = Number.parseInt(opts.maxCount, 10);
+        if (Number.isFinite(n) && n > 0)
+            args.push(`-m${n}`);
+    }
+    // Gitignore-style globs: a bare name matches (and prunes) at any depth,
+    // mirroring grep's --exclude-dir / --exclude basename semantics. ORDER
+    // MATTERS: rg globs are last-match-wins, so positives (includes/lang) go
+    // first and negatives (excludes) last — otherwise `--include '*.md'` would
+    // re-include a .md file inside an excluded node_modules/. grep's
+    // --exclude-dir always beats --include, so this keeps the engines aligned.
+    const langGlobs = resolveLangGlobs(opts);
+    if (langGlobs)
+        for (const g of langGlobs)
+            args.push(`--glob=${g}`);
+    for (const g of opts.include ?? [])
+        args.push(`--glob=${g}`);
+    if (!opts.noDefaultExcludes) {
+        for (const d of DEFAULT_EXCLUDE_DIRS)
+            args.push(`--glob=!${d}`);
+        for (const f of DEFAULT_EXCLUDE_FILES)
+            args.push(`--glob=!${f}`);
+    }
+    for (const d of extraExcludeDirs)
+        args.push(`--glob=!${d}`);
+    for (const e of opts.exclude ?? [])
+        args.push(`--glob=!${e}`);
+    args.push("--", pattern);
+    if (paths.length > 0)
+        args.push(...paths);
+    else
+        args.push(".");
+    return args;
+}
+/**
+ * Filename mode via ripgrep: `--files` lists files; a single positive glob
+ * acts as a whitelist, negative globs prune. `--iglob` gives -i semantics.
+ */
+function buildRgFilesArgs(pattern, paths, opts, extraExcludeDirs) {
+    const args = ["--files", "--hidden", "--no-ignore", "--no-config", "--color=never"];
+    // Positive pattern FIRST, negatives last (rg globs are last-match-wins;
+    // excludes must beat the pattern — see the ordering note in buildRgArgs).
+    args.push(`${opts.ignoreCase ? "--iglob" : "--glob"}=${pattern}`);
+    if (!opts.noDefaultExcludes) {
+        for (const d of DEFAULT_EXCLUDE_DIRS)
+            args.push(`--glob=!${d}`);
+        for (const f of DEFAULT_EXCLUDE_FILES)
+            args.push(`--glob=!${f}`);
+    }
+    for (const d of extraExcludeDirs)
+        args.push(`--glob=!${d}`);
+    for (const e of opts.exclude ?? [])
+        args.push(`--glob=!${e}`);
+    if (paths.length > 0)
+        args.push(...paths);
+    else
+        args.push(".");
+    return args;
+}
+/**
+ * Filename mode via POSIX find (the no-ripgrep fallback):
+ *   find <paths> ( -name d1 -o -name d2 ... ) -prune -o -type f -name <glob> [! -name <ex>]... -print
+ * Sticks to POSIX operators (`(`, `-o`, `!`) so BSD/macOS find behaves the same.
+ */
+function buildFindArgs(pattern, paths, opts, extraExcludeDirs) {
+    const args = paths.length > 0 ? [...paths] : ["."];
+    const pruneDirs = [...(opts.noDefaultExcludes ? [] : DEFAULT_EXCLUDE_DIRS), ...extraExcludeDirs];
+    if (pruneDirs.length > 0) {
+        args.push("(");
+        pruneDirs.forEach((d, i) => {
+            if (i > 0)
+                args.push("-o");
+            args.push("-name", d);
+        });
+        args.push(")", "-prune", "-o");
+    }
+    args.push("-type", "f", opts.ignoreCase ? "-iname" : "-name", pattern);
+    const fileExcludes = [
+        ...(opts.noDefaultExcludes ? [] : DEFAULT_EXCLUDE_FILES),
+        ...(opts.exclude ?? []),
+    ];
+    for (const e of fileExcludes)
+        args.push("!", "-name", e);
+    args.push("-print");
+    return args;
+}
+function execSearch(bin, args, cwd, limit) {
     return new Promise((resolveP, reject) => {
-        const proc = spawn("grep", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const proc = spawn(bin, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
         const matches = [];
         let buffer = "";
         let stderr = "";
@@ -242,31 +435,34 @@ function execGrep(args, cwd, limit) {
                 if (parsed)
                     matches.push(parsed);
             }
-            // grep exits 1 on "no matches": normal, not an error.
-            if (code !== null && code !== 0 && code !== 1 && !truncated) {
-                reject(new Error(`grep exited ${code}: ${stderr.trim() || "(no stderr)"}`));
+            // Exit 1 is "no matches" on both engines: normal, not an error. Exit 2
+            // with matches collected means a partial failure (an unreadable file
+            // mid-walk); surface the results rather than throwing them away.
+            if (code !== null && code !== 0 && code !== 1 && !truncated && matches.length === 0) {
+                reject(new Error(`${bin} exited ${code}: ${stderr.trim() || "(no stderr)"}`));
                 return;
             }
             resolveP(matches);
         });
     });
 }
-/** Parse `path:line:content` from grep -n output. Returns null for ambiguous (no line number) lines. */
+/** Parse `path:line:content` from grep/rg -n output. Returns null for ambiguous (no line number) lines. */
 function parseGrepLine(line) {
     // First colon ends path; second colon ends line number (if numeric).
     const firstColon = line.indexOf(":");
     if (firstColon < 0) {
         // -l mode: just a path. Encode as line=0, text="".
-        return { file: line, line: 0, text: "" };
+        return { file: normalizeFile(line), line: 0, text: "" };
     }
     const after = line.slice(firstColon + 1);
     const secondColon = after.indexOf(":");
     if (secondColon < 0) {
         // -c mode: `path:count`.
         const count = Number.parseInt(after, 10);
-        if (Number.isFinite(count))
-            return { file: line.slice(0, firstColon), line: count, text: "" };
-        return { file: line.slice(0, firstColon), line: 0, text: after };
+        if (Number.isFinite(count)) {
+            return { file: normalizeFile(line.slice(0, firstColon)), line: count, text: "" };
+        }
+        return { file: normalizeFile(line.slice(0, firstColon)), line: 0, text: after };
     }
     const lineNum = Number.parseInt(after.slice(0, secondColon), 10);
     if (!Number.isFinite(lineNum)) {
@@ -274,11 +470,15 @@ function parseGrepLine(line) {
         return null;
     }
     return {
-        file: line.slice(0, firstColon),
+        file: normalizeFile(line.slice(0, firstColon)),
         line: lineNum,
         text: after.slice(secondColon + 1),
     };
 }
+/** Both engines may emit a leading `./` for the default path; strip it so output is engine-identical. */
+function normalizeFile(file) {
+    return file.startsWith("./") ? file.slice(2) : file;
+}
 function renderResult(r, opts) {
     const lines = [];
     const showRepoHeader = r.repos.length > 1;
@@ -290,7 +490,7 @@ function renderResult(r, opts) {
             lines.push(`── ${repo.name} (${repo.matches.length} match${repo.matches.length === 1 ? "" : "es"}) ──`);
         }
         for (const m of repo.matches) {
-            if (opts.filesOnly) {
+            if (opts.filesOnly || opts.files) {
                 lines.push(m.file);
             }
             else if (opts.count) {
@@ -305,13 +505,14 @@ function renderResult(r, opts) {
         }
     }
     if (r.total_matches === 0) {
-        lines.push(`(no matches for /${r.pattern}/${r.mode === "literal" ? " (literal)" : ""})`);
+        const modeTag = r.mode === "literal" ? " (literal)" : r.mode === "files" ? " (files)" : "";
+        lines.push(`(no matches for /${r.pattern}/${modeTag})`);
     }
     else if (r.repos.length > 1 || r.truncated) {
         lines.push("");
         const summary = `${r.total_matches} match${r.total_matches === 1 ? "" : "es"} across ${r.total_files} file${r.total_files === 1 ? "" : "s"}`;
         const tail = r.truncated ? " (truncated; use --limit)" : "";
-        lines.push(`${summary}${tail}  (${r.elapsed_ms}ms)`);
+        lines.push(`${summary}${tail}  (${r.elapsed_ms}ms, ${r.engine})`);
     }
     return lines.join("\n");
 }

package/dist/core/agents/cli.js

@@ -150,6 +150,32 @@ async function handleProject(root, rest) {
     }
     return 0;
 }
+/**
+ * Append a canonical `claim.release` event for a path dropped from an owner's
+ * files_touched. The path is canonicalized to repo-relative (matching the
+ * projector's normalization) so the subtraction matches on replay regardless
+ * of the form the caller passed. Soft-fails: a failed emit must never break
+ * the release/kill flow — the file mutation already happened.
+ */
+async function emitClaimRelease(root, owner, hb, path, reason) {
+    try {
+        const { emit } = await import("./events/emit.js");
+        const canonical = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+        const platform = hb.platform;
+        const harness = platform === "cursor" ? "cursor" : platform === "codex" ? "codex" : "claude-code";
+        emit(root, {
+            event_type: "claim.release",
+            instance_id: owner,
+            session_id: hb.session_id ?? owner,
+            harness,
+            source: "agent-coord",
+            data: { path: canonical, reason },
+        });
+    }
+    catch {
+        /* soft-fail: never break the caller */
+    }
+}
 async function handleStateAction(root, action, rest) {
     const writer = await import("./state/heartbeat-writer.js");
     const [owner, ...args] = rest;
@@ -189,14 +215,36 @@ async function handleStateAction(root, action, rest) {
                 process.stderr.write("agent-coord release-claim: missing <path>\n");
                 return 2;
             }
+            const before = writer.readHeartbeat(root, owner);
             const hb = writer.releaseClaim(root, owner, path);
             if (!hb)
                 return 1;
+            // Durability: the projector rebuilds files_touched by replaying the
+            // permanent Edit/Write events, so a file-only release is silently
+            // reverted by the next full replay. Emitting claim.release puts the
+            // subtraction into the stream so every future replay honors it. Only
+            // emit when the release actually removed a held path (idempotent
+            // re-releases stay quiet).
+            const heldBefore = before?.files_touched?.length ?? 0;
+            const heldAfter = hb.files_touched?.length ?? 0;
+            if (heldBefore > heldAfter) {
+                await emitClaimRelease(root, owner, before ?? hb, path, "explicit");
+            }
             process.stdout.write(`${JSON.stringify({ instance_id: owner, files_touched: hb.files_touched })}\n`);
             return 0;
         }
         case "kill-heartbeat": {
+            // Read held claims BEFORE the unlink so they can be released durably —
+            // killing only the file leaves the claims resurrectable from the
+            // permanent Edit/Write events on the next full replay (observed: a
+            // 6-day-dead agent's claims returning after its heartbeat was killed).
+            const before = writer.readHeartbeat(root, owner);
             const ok = writer.killHeartbeat(root, owner);
+            if (ok && before) {
+                for (const held of before.files_touched ?? []) {
+                    await emitClaimRelease(root, owner, before, held, "heal");
+                }
+            }
             process.stdout.write(`${JSON.stringify({ instance_id: owner, removed: ok })}\n`);
             return ok ? 0 : 1;
         }

package/dist/core/agents/state/heartbeat-projector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat-projector.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,OAAO,EAAE;QACP,cAAc,EAAE,CAAC,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAE,CAoD9D;AA8VD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3E"}
+{"version":3,"file":"heartbeat-projector.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,OAAO,EAAE;QACP,cAAc,EAAE,CAAC,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAE,CAoD9D;AAsWD,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3E"}

package/dist/core/agents/state/heartbeat-projector.js

@@ -38,7 +38,7 @@ export function projectHeartbeats(coordRoot, events) {
                 continue;
             perOwner[ev.instance_id] = existing ?? seed(ev, coordRoot);
         }
-        apply(perOwner[ev.instance_id], ev);
+        apply(perOwner[ev.instance_id], ev, coordRoot);
     }
     const written = [];
     for (const [instance_id, hb] of Object.entries(perOwner)) {
@@ -101,7 +101,7 @@ function seed(ev, coordRoot) {
     }
     return hb;
 }
-function apply(hb, ev) {
+function apply(hb, ev, coordRoot) {
     hb.last_heartbeat = ev.ts;
     hb.last_event_id = ev.event_id;
     hb.events_applied += 1;
@@ -238,7 +238,14 @@ function apply(hb, ev) {
         case "claim.release": {
             const path = pickStr(d, "path");
             if (path && hb.files_touched) {
-                hb.files_touched = hb.files_touched.filter((p) => p !== path);
+                // files_touched holds a mix of absolute-under-coordRoot and canonical
+                // repo-relative entries (Edit events report absolute; release-claim
+                // canonicalizes to relative). Normalize both sides so a release
+                // subtracts regardless of form — an exact-string compare silently
+                // no-ops on the mismatch and the claim resurrects on the next replay.
+                const norm = (p) => p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
+                const target = norm(path);
+                hb.files_touched = hb.files_touched.filter((p) => norm(p) !== target);
             }
             break;
         }

package/dist/core/config.d.ts

@@ -43,4 +43,13 @@ export declare function pinnedBinName(projectRoot: string): string | null;
  * `coordRoot` is resolved via `findCoordRoot()` when not passed.
  */
 export declare function resolveHooksSetupHint(coordRoot?: string | null): string | null;
+/**
+ * Whether the host project consented to automatic ripgrep provisioning:
+ * `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall": true } } }`.
+ * A repo commits that once and every clone self-heals on first `grep`; without
+ * it, a missing rg only produces a rate-limited hint (`doctor --fix` installs
+ * explicitly). `HARNERY_TOOLS_AUTOINSTALL=1|0` overrides per process.
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export declare function ripgrepAutoInstall(coordRoot?: string | null): boolean;
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAgBvC,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAyBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAuBvC,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAyBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOrE"}

package/dist/core/config.js

@@ -132,3 +132,22 @@ export function resolveHooksSetupHint(coordRoot) {
     const hint = readConfig(root).hooksSetupHint;
     return typeof hint === "string" && hint.trim() ? hint.trim() : null;
 }
+/**
+ * Whether the host project consented to automatic ripgrep provisioning:
+ * `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall": true } } }`.
+ * A repo commits that once and every clone self-heals on first `grep`; without
+ * it, a missing rg only produces a rate-limited hint (`doctor --fix` installs
+ * explicitly). `HARNERY_TOOLS_AUTOINSTALL=1|0` overrides per process.
+ * `coordRoot` is resolved via `findCoordRoot()` when not passed.
+ */
+export function ripgrepAutoInstall(coordRoot) {
+    const env = coordEnv("TOOLS_AUTOINSTALL");
+    if (env === "1")
+        return true;
+    if (env === "0")
+        return false;
+    const root = coordRoot ?? findCoordRoot();
+    if (!root)
+        return false;
+    return readConfig(root).tools?.ripgrep?.autoInstall === true;
+}

package/dist/lib/tools/ripgrep.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Managed ripgrep provisioning for `grep --files` / content search.
+ *
+ * harnery can install a pinned, checksum-verified ripgrep into its own tools
+ * directory (`$XDG_DATA_HOME/harnery/tools`, default `~/.local/share/harnery/
+ * tools`) so `harn grep` gets the fast engine even on machines where nobody
+ * ever installed rg. The download is version-pinned and every artifact's
+ * sha256 is baked in below (cross-checked against the official release
+ * checksums), so the install is reproducible, never "whatever is latest."
+ *
+ * Consent model: the installer only runs automatically when the host project
+ * opts in via `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall":
+ * true } } }` — a repo commits that once and every clone self-heals. Without
+ * the opt-in, a missing rg produces a rate-limited stderr hint naming
+ * `harn doctor --fix` (explicit install). Environments that forbid downloads
+ * lose nothing: every failure path falls back to GNU grep.
+ */
+export declare const RG_VERSION = "14.1.1";
+/** True when a pinned artifact exists for this OS/arch (Windows: not yet). */
+export declare function rgInstallSupported(): boolean;
+/** Machine-level harnery tools dir (NOT the per-project .harnery/ state dir). */
+export declare function toolsDir(): string;
+/** Path the managed rg binary lives at once installed. */
+export declare function managedRgPath(): string;
+/**
+ * Locate a usable ripgrep. Precedence:
+ *   1. HARNERY_RG_PATH (explicit override)
+ *   2. the managed tools-dir install (works even when PATH doesn't carry it)
+ *   3. `rg` on PATH
+ * Returns the spawnable path/name, or null when none respond to --version.
+ */
+export declare function findRg(): string | null;
+/**
+ * Download + verify + install the pinned ripgrep into the tools dir.
+ * Atomic: extracts to a temp dir and renames the binary into place.
+ * Throws on unsupported platform, network failure, or checksum mismatch —
+ * callers are expected to fall back to grep and say why.
+ */
+export declare function installRg(log?: (line: string) => void): Promise<string>;
+export type SearchEngine = "rg" | "grep";
+/**
+ * Shared engine resolver for the ripgrep-backed search commands (`grep`,
+ * `callers`). Returns the engine plus the spawnable rg path.
+ *
+ * `HARNERY_GREP_ENGINE=rg|grep` forces one; otherwise findRg() probes
+ * HARNERY_RG_PATH → the managed tools-dir install → PATH. On a miss, the
+ * host's `.harnery/config.jsonc` `tools.ripgrep.autoInstall` consent triggers
+ * a pinned, checksum-verified install into the harnery tools dir (any failure
+ * falls back to grep with a stderr note); without consent, a rate-limited
+ * stderr hint (keyed per `hintKey`) names the explicit install command.
+ */
+export declare function resolveSearchEngine(hintKey?: string): Promise<{
+    engine: SearchEngine;
+    rgBin: string;
+}>;
+/**
+ * Emit `line` to stderr at most once per 24h (stamp file in the tools dir).
+ * Keeps the "rg missing" nudge from nagging on every single grep invocation.
+ */
+export declare function hintOncePerDay(line: string): void;
+//# sourceMappingURL=ripgrep.d.ts.map

package/dist/lib/tools/ripgrep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripgrep.d.ts","sourceRoot":"","sources":["../../../src/lib/tools/ripgrep.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,UAAU,WAAW,CAAC;AA0BnC,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,IAAI,MAAM,CAIjC;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAWD;;;;;;GAMG;AACH,wBAAgB,MAAM,IAAI,MAAM,GAAG,IAAI,CAStC;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAoD7E;AAkBD,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,SAAS,GACf,OAAO,CAAC;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BlD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAYjD"}