harnery 0.7.0 → 0.8.0

package/src/commands/grep.ts

@@ -1,15 +1,29 @@
 import { spawn } from "node:child_process";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { resolveSearchEngine, type SearchEngine } from "../lib/tools/ripgrep.ts";
 
 /**
- * `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 = [
@@ -51,7 +65,9 @@ const LANG_GLOBS: Record<string, string[]> = {
   rs: ["*.rs"],
 };
 
-interface GrepOpts {
+export type GrepEngine = SearchEngine;
+
+export interface GrepOpts {
   repo?: string;
   allRepos?: boolean;
   lang?: string;
@@ -59,6 +75,7 @@ interface GrepOpts {
   wholeWord?: boolean;
   literal?: boolean;
   filesOnly?: boolean;
+  files?: boolean;
   count?: boolean;
   context?: string;
   maxCount?: string;
@@ -84,7 +101,8 @@ export function registerGrepCommand(
   program
     .command("grep <pattern> [paths...]")
     .description(
-      "Monorepo-aware code search. Skips dist/.next/node_modules/.git/... by default. " +
+      "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)")
@@ -94,6 +112,11 @@ export function registerGrepCommand(
     .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")
@@ -122,9 +145,10 @@ function collect(value: string, prev: string[]): string[] {
   return [...prev, value];
 }
 
-interface GrepResult {
+export interface GrepResult {
   pattern: string;
-  mode: "regex" | "literal";
+  mode: "regex" | "literal" | "files";
+  engine: GrepEngine;
   repos: { name: string; cwd: string; matches: Match[]; truncated: boolean }[];
   total_matches: number;
   total_files: number;
@@ -132,39 +156,89 @@ interface GrepResult {
   elapsed_ms: number;
 }
 
-async function runGrep(
+/** Exported for tests (not part of the package exports map). */
+export async function runGrep(
   pattern: string,
   paths: string[],
   opts: GrepOpts,
   context: HarneryProgramContext | undefined,
 ): Promise<GrepResult> {
   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: [unknown, string][] = [
+      [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: GrepResult["repos"] = [];
   let totalMatches = 0;
   const filesSeen = new Set<string>();
   let truncated = false;
+  let budget = limit;
 
-  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;
-    }
-    const matches = await runGrepInRepo(pattern, paths, opts, repo.cwd, repo.name, repoLimit);
-    let repoTruncated = false;
-    if (Number.isFinite(repoLimit) && matches.length >= repoLimit) {
-      repoTruncated = true;
-      truncated = true;
+  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 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}`);
     allRepoResults.push({ name: repo.name, cwd: repo.cwd, matches, truncated: repoTruncated });
@@ -172,7 +246,8 @@ async function runGrep(
 
   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,
@@ -223,8 +298,42 @@ async function runGrepInRepo(
   cwd: string,
   repoName: string,
   limit: number,
+  engine: GrepEngine,
+  rgBin: string,
+  extraExcludeDirs: readonly string[],
 ): Promise<Match[]> {
-  const args: string[] = ["-rn", "--color=never", "-I"]; // -I: skip binary files
+  // 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)] as const)
+      : (["find", buildFindArgs(pattern, paths, opts, extraExcludeDirs)] as const)
+    : engine === "rg"
+      ? ([rgBin, buildRgArgs(pattern, paths, opts, extraExcludeDirs)] as const)
+      : (["grep", buildGrepArgs(pattern, paths, opts, extraExcludeDirs)] as const);
+
+  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: GrepOpts): string[] | undefined {
+  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: string,
+  paths: string[],
+  opts: GrepOpts,
+  extraExcludeDirs: readonly string[],
+): string[] {
+  const args: string[] = ["-rn", "-H", "--color=never", "-I"]; // -I: skip binary files
   if (opts.ignoreCase) args.push("-i");
   if (opts.wholeWord) args.push("-w");
   if (opts.literal) args.push("-F");
@@ -242,26 +351,138 @@ async function runGrepInRepo(
     for (const d of DEFAULT_EXCLUDE_DIRS) args.push(`--exclude-dir=${d}`);
     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}`);
   for (const g of opts.include ?? []) args.push(`--include=${g}`);
 
   args.push("--", pattern);
   if (paths.length > 0) args.push(...paths);
   else args.push(".");
+  return args;
+}
 
-  const matches = await execGrep(args, cwd, limit);
-  return matches.map((m) => ({ ...m, repo: repoName }));
+function buildRgArgs(
+  pattern: string,
+  paths: string[],
+  opts: GrepOpts,
+  extraExcludeDirs: readonly string[],
+): string[] {
+  // --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: string[] = [
+    "-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: string,
+  paths: string[],
+  opts: GrepOpts,
+  extraExcludeDirs: readonly string[],
+): string[] {
+  const args: string[] = ["--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;
 }
 
-function execGrep(args: string[], cwd: string, limit: number): Promise<Omit<Match, "repo">[]> {
+/**
+ * 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: string,
+  paths: string[],
+  opts: GrepOpts,
+  extraExcludeDirs: readonly string[],
+): string[] {
+  const args: string[] = 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: string,
+  args: string[],
+  cwd: string,
+  limit: number,
+): Promise<Omit<Match, "repo">[]> {
   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: Omit<Match, "repo">[] = [];
     let buffer = "";
     let stderr = "";
@@ -297,9 +518,11 @@ function execGrep(args: string[], cwd: string, limit: number): Promise<Omit<Matc
         const parsed = parseGrepLine(buffer);
         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);
@@ -307,21 +530,23 @@ function execGrep(args: string[], cwd: string, limit: number): Promise<Omit<Matc
   });
 }
 
-/** 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: string): Omit<Match, "repo"> | null {
   // 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)) {
@@ -329,12 +554,17 @@ function parseGrepLine(line: string): Omit<Match, "repo"> | null {
     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: string): string {
+  return file.startsWith("./") ? file.slice(2) : file;
+}
+
 function renderResult(r: GrepResult, opts: GrepOpts): string {
   const lines: string[] = [];
   const showRepoHeader = r.repos.length > 1;
@@ -347,7 +577,7 @@ function renderResult(r: GrepResult, opts: GrepOpts): string {
       );
     }
     for (const m of repo.matches) {
-      if (opts.filesOnly) {
+      if (opts.filesOnly || opts.files) {
         lines.push(m.file);
       } else if (opts.count) {
         lines.push(`${m.file}:${m.line}`);
@@ -360,12 +590,13 @@ function renderResult(r: GrepResult, opts: GrepOpts): string {
     }
   }
   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/src/core/agents/cli.ts

@@ -164,6 +164,39 @@ async function handleProject(root: string, rest: string[]): Promise<number> {
   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: string,
+  owner: string,
+  hb: { session_id?: string; platform?: string },
+  path: string,
+  reason: "explicit" | "heal",
+): Promise<void> {
+  try {
+    const { emit } = await import("./events/emit.ts");
+    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: string, action: string, rest: string[]): Promise<number> {
   const writer = await import("./state/heartbeat-writer.ts");
   const [owner, ...args] = rest;
@@ -210,15 +243,37 @@ async function handleStateAction(root: string, action: string, rest: string[]):
         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/src/core/agents/state/heartbeat-projector.ts

@@ -88,7 +88,7 @@ export function projectHeartbeats(
       if (!existing && TERMINAL.has(ev.event_type)) continue;
       perOwner[ev.instance_id] = existing ?? seed(ev, coordRoot);
     }
-    apply(perOwner[ev.instance_id]!, ev);
+    apply(perOwner[ev.instance_id]!, ev, coordRoot);
   }
 
   const written: string[] = [];
@@ -153,7 +153,7 @@ function seed(ev: CanonicalEvent, coordRoot: string): V2Heartbeat {
   return hb;
 }
 
-function apply(hb: V2Heartbeat, ev: CanonicalEvent): void {
+function apply(hb: V2Heartbeat, ev: CanonicalEvent, coordRoot: string): void {
   hb.last_heartbeat = ev.ts;
   hb.last_event_id = ev.event_id;
   hb.events_applied += 1;
@@ -285,7 +285,15 @@ function apply(hb: V2Heartbeat, ev: CanonicalEvent): void {
     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: string): string =>
+          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/src/core/config.ts

@@ -33,6 +33,13 @@ interface HarneryConfig {
    * declares it here (e.g. "scripts/setup-hooks.sh"). Unset → a generic hint.
    */
   hooksSetupHint?: string;
+  /**
+   * Managed-tool provisioning consent. `{ ripgrep: { autoInstall: true } }`
+   * lets `grep` download the pinned, checksum-verified ripgrep into the
+   * harnery tools dir on first miss. Committed by a host repo once; absent →
+   * a missing rg only produces a rate-limited install hint.
+   */
+  tools?: { ripgrep?: { autoInstall?: boolean } };
   [k: string]: unknown;
 }
 
@@ -144,3 +151,20 @@ export function resolveHooksSetupHint(coordRoot?: string | null): string | null
   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?: string | null): boolean {
+  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;
+}