harnery 0.0.1 → 0.2.1

package/src/core/agents/render/session-context.ts

@@ -0,0 +1,341 @@
+/**
+ * SessionStart UX renderer: combines the peer table, the wiring check, and
+ * the pending-council formatter so agent-hook session.start can emit the
+ * combined `systemMessage` JSON directly.
+ *
+ * Outputs a Claude Code SessionStart hookSpecificOutput.additionalContext
+ * string.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveBinName } from "../../config.ts";
+
+interface HeartbeatRow {
+  instance_id?: string;
+  name?: string;
+  kind?: string;
+  session_id?: string;
+  started_at?: string;
+  last_heartbeat?: string;
+  last_tool?: string;
+  last_tool_target?: string;
+  files_touched?: string[];
+  platform?: string;
+  task?: string;
+  turn_summary?: string;
+}
+
+export interface RenderOpts {
+  coordRoot: string;
+  instanceId: string;
+  sessionId: string;
+  agentName?: string;
+  /** Harness label rendered in parens after the self-name (e.g. "Cursor", "Codex").
+   * Claude Code omits it. */
+  platformLabel?: string;
+}
+
+/**
+ * Build the combined SessionStart systemMessage. Returns the additionalContext
+ * string (or "" if there's nothing to say).
+ */
+export function renderSessionContext(opts: RenderOpts): string {
+  const { coordRoot, instanceId, sessionId, agentName, platformLabel } = opts;
+  const messages: string[] = [];
+
+  // 1. Self-name line + peer table (folded if peers present)
+  const peers = readActivePeers(coordRoot, instanceId);
+  const peerTable = formatPeerTable(peers, sessionId);
+  if (agentName) {
+    const suffix = platformLabel ? ` (${platformLabel})` : "";
+    const selfLine = `You are agent-${agentName}${suffix}.`;
+    messages.push(peerTable ? `${selfLine}\n\n${peerTable}` : selfLine);
+  } else if (peerTable) {
+    messages.push(peerTable);
+  }
+
+  // 2. Linked-worktree detection
+  if (isLinkedWorktree(coordRoot)) {
+    messages.push(
+      `Running inside worktree ${process.cwd()}. The coord layer is scoped to this worktree only; use \`${resolveBinName(coordRoot)} worktree diff\` to check for conflicts against sibling worktrees.`,
+    );
+  }
+
+  // 3. Council invites
+  if (agentName) {
+    const councilMsg = formatPendingCouncils(coordRoot, agentName);
+    if (councilMsg) messages.push(councilMsg);
+  }
+
+  // 4. Wiring check
+  const wiringIssues = checkWiring(coordRoot);
+  if (wiringIssues.length > 0) {
+    const wiringSummary = `Coordination hooks are NOT wired: the E-guard will not block conflicting commits, and post-commit claim pruning will not run. Run \`scripts/setup-hooks.sh\` to fix. Detected:\n${wiringIssues.map((i) => `  - ${i}`).join("\n")}`;
+    messages.push(wiringSummary);
+  }
+
+  return messages.join("\n\n");
+}
+
+/** Read all peer heartbeats from .harnery/active/, excluding self. */
+function readActivePeers(coordRoot: string, selfInstanceId: string): HeartbeatRow[] {
+  const out: HeartbeatRow[] = [];
+  const dir = join(coordRoot, ".harnery", "active");
+  if (!existsSync(dir)) return out;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const hb = JSON.parse(readFileSync(join(dir, f), "utf8")) as HeartbeatRow;
+      if (!hb.instance_id || hb.instance_id === selfInstanceId) continue;
+      out.push(hb);
+    } catch {
+      /* skip */
+    }
+  }
+  return out;
+}
+
+/**
+ * Renders the peer table as
+ * two subsections: "Other agent groups active" (blocking) and "Your group"
+ * (subagents/siblings, no mutual block). Folds transient subagents' files
+ * into their parent session.
+ */
+function formatPeerTable(peers: HeartbeatRow[], mySessionId: string): string {
+  if (peers.length === 0) return "";
+  const nowSec = Math.floor(Date.now() / 1000);
+
+  // Fold transient peers' files into their session_id parent.
+  const fold: Record<string, string[]> = {};
+  for (const p of peers) {
+    const kind = p.kind ?? "unknown";
+    if (kind === "transient" && p.session_id) {
+      fold[p.session_id] = (fold[p.session_id] ?? []).concat(p.files_touched ?? []);
+    }
+  }
+
+  // Build rows with display_files (own files + folded transient files).
+  type RowExt = HeartbeatRow & { display_files: string[] };
+  const rows: RowExt[] = peers
+    .filter((p) => (p.kind ?? "unknown") !== "transient")
+    .map((p) => {
+      const folded = fold[p.instance_id ?? ""] ?? [];
+      const display = Array.from(new Set([...(p.files_touched ?? []), ...folded])).sort();
+      return { ...p, display_files: display };
+    });
+
+  const blocking = rows.filter((p) => p.session_id !== mySessionId).sort(byStartedAt);
+  const group = rows.filter((p) => p.session_id === mySessionId).sort(byStartedAt);
+
+  const sections: string[] = [];
+  const blockingSection = renderSubtable(
+    blocking,
+    "Other agent groups active (their files block you):",
+    nowSec,
+  );
+  if (blockingSection) sections.push(blockingSection);
+  const groupSection = renderSubtable(
+    group,
+    "Your group (subagents / parent / siblings; no mutual block):",
+    nowSec,
+  );
+  if (groupSection) sections.push(groupSection);
+
+  return sections.join("\n\n");
+}
+
+function byStartedAt(a: HeartbeatRow, b: HeartbeatRow): number {
+  return (a.started_at ?? "").localeCompare(b.started_at ?? "");
+}
+
+function renderSubtable(
+  rows: Array<HeartbeatRow & { display_files: string[] }>,
+  header: string,
+  nowSec: number,
+): string {
+  if (rows.length === 0) return "";
+  const first = rows.slice(0, 10).map((r) => formatRow(r, nowSec));
+  const overflow = rows.length > 10 ? `\n  +${rows.length - 10} more` : "";
+  return `${header}\n${first.join("\n")}${overflow}`;
+}
+
+function formatRow(r: HeartbeatRow & { display_files: string[] }, nowSec: number): string {
+  const taskPart = r.task ? ` "${r.task.slice(0, 60)}"` : "";
+  const ageFrom = fmtAge(nowSec - parseIsoSec(r.started_at));
+  const filesPart = fmtFiles(r.display_files);
+  const lastActivity = fmtLastActivity(r, nowSec);
+  const turnSummary = r.turn_summary ? `\n    last turn: ${r.turn_summary.slice(0, 80)}` : "";
+  return `  - agent-${r.name ?? "unknown"}${taskPart}   (${ageFrom}, ${filesPart}${lastActivity})${turnSummary}`;
+}
+
+function fmtFiles(files: string[]): string {
+  if (files.length === 0) return "nothing yet";
+  if (files.length <= 3) return `holds: ${files.join(", ")}`;
+  return `holds: ${files.slice(0, 3).join(", ")}, +${files.length - 3} more`;
+}
+
+function fmtLastActivity(r: HeartbeatRow, nowSec: number): string {
+  if (!r.last_tool) return "";
+  const lastTs = parseIsoSec(r.last_heartbeat ?? r.started_at);
+  const ageSec = nowSec - lastTs;
+  const tail = r.last_tool_target ? ` ${r.last_tool_target.slice(0, 60)}` : "";
+  return `, last: ${r.last_tool}${tail} ${fmtAge(ageSec)}`;
+}
+
+function parseIsoSec(iso: string | undefined): number {
+  if (!iso) return 0;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
+
+function fmtAge(secs: number): string {
+  if (secs < 60) return `${Math.floor(secs)}s ago`;
+  if (secs < 3600) return `${Math.floor(secs / 60)}m ago`;
+  if (secs < 86400) return `${Math.floor(secs / 3600)}h ago`;
+  return `${Math.floor(secs / 86400)}d ago`;
+}
+
+/**
+ * Returns a list of wiring issues (empty when everything's wired). Checks
+ * parent core.hooksPath + one representative submodule.
+ */
+export function checkWiring(coordRoot: string): string[] {
+  const expected = join(coordRoot, "scripts", "hooks");
+  const issues: string[] = [];
+
+  // Parent repo
+  const parentHp = gitConfig(coordRoot, "core.hooksPath");
+  const parentResolved = resolveHooksPath(coordRoot, parentHp);
+  if (parentResolved !== expected) {
+    issues.push(
+      `parent core.hooksPath=${parentHp || "<unset>"} (resolves to ${parentResolved}, expected ${expected})`,
+    );
+  }
+
+  // One representative submodule
+  const gitmodules = join(coordRoot, ".gitmodules");
+  if (existsSync(gitmodules)) {
+    const sampleSub = extractFirstSubmodule(gitmodules);
+    if (sampleSub) {
+      const subPath = join(coordRoot, sampleSub);
+      const subGitDir = join(subPath, ".git");
+      if (existsSync(subGitDir)) {
+        const subHp = gitConfig(subPath, "core.hooksPath");
+        const subResolved = resolveSubmoduleHooksPath(coordRoot, sampleSub, subHp);
+        if (subResolved !== expected) {
+          issues.push(
+            `submodule ${sampleSub} core.hooksPath=${subHp || "<unset>"} (resolves to ${subResolved}; other submodules likely affected too)`,
+          );
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+function gitConfig(cwd: string, key: string): string {
+  const result = spawnSync("git", ["-C", cwd, "config", "--get", key], { encoding: "utf8" });
+  if (result.status !== 0) return "";
+  return result.stdout.trim();
+}
+
+function resolveHooksPath(root: string, hp: string): string {
+  if (!hp) return join(root, ".git", "hooks");
+  if (hp.startsWith("/")) return hp.replace(/\/$/, "");
+  return join(root, hp).replace(/\/$/, "");
+}
+
+function resolveSubmoduleHooksPath(root: string, sub: string, hp: string): string {
+  if (!hp) return join(root, sub, ".git", "hooks");
+  if (hp.startsWith("/")) return hp.replace(/\/$/, "");
+  return join(root, sub, hp).replace(/\/$/, "");
+}
+
+function extractFirstSubmodule(gitmodulesPath: string): string | null {
+  try {
+    const content = readFileSync(gitmodulesPath, "utf8");
+    const match = content.match(/^\s*path\s*=\s*(.+)$/m);
+    return match ? match[1]!.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect linked-worktree environment (`git worktree` created from the
+ * superproject) via a `git rev-parse --git-dir` vs `--git-common-dir` check.
+ */
+function isLinkedWorktree(coordRoot: string): boolean {
+  const dir = spawnSync("git", ["-C", coordRoot, "rev-parse", "--git-dir"], { encoding: "utf8" });
+  const common = spawnSync("git", ["-C", coordRoot, "rev-parse", "--git-common-dir"], {
+    encoding: "utf8",
+  });
+  if (dir.status !== 0 || common.status !== 0) return false;
+  const d = dir.stdout.trim();
+  const c = common.stdout.trim();
+  return d !== "" && c !== "" && d !== c;
+}
+
+/**
+ * Returns the formatted council invite reminder
+ * (or "" when no councils await input).
+ */
+export function formatPendingCouncils(coordRoot: string, agentName: string): string {
+  const councilsDir = join(coordRoot, ".harnery", "councils");
+  if (!existsSync(councilsDir)) return "";
+  const canonicalName = agentName.startsWith("agent-") ? agentName : `agent-${agentName}`;
+  const pending: string[] = [];
+  try {
+    for (const f of readdirSync(councilsDir)) {
+      if (!f.endsWith(".json")) continue;
+      const manifestPath = join(councilsDir, f);
+      try {
+        const m = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+          council_id?: string;
+          status?: string;
+          round_status?: string;
+          current_round?: number;
+          members?: string[];
+        };
+        if (m.status !== "active" || m.round_status !== "open") continue;
+        if (!m.members?.includes(canonicalName)) continue;
+        const round = m.current_round ?? 1;
+        const contributionPath = join(
+          councilsDir,
+          m.council_id ?? "",
+          `round-${round}`,
+          `${canonicalName}.md`,
+        );
+        if (existsSync(contributionPath)) continue; // already contributed
+        if (m.council_id) pending.push(m.council_id);
+      } catch {
+        /* skip */
+      }
+    }
+  } catch {
+    /* skip */
+  }
+
+  if (pending.length === 0) return "";
+  const bin = resolveBinName(coordRoot);
+  const firstThree = pending.slice(0, 3);
+  const tail = pending.length > 3 ? `, +${pending.length - 3} more` : "";
+  const list = firstThree.join(", ") + tail;
+  if (pending.length === 1) {
+    return (
+      `Council waiting on your input: \`${pending[0]}\`. ` +
+      `Run \`${bin} agents council show ${pending[0]}\` for the brief and ` +
+      `\`${bin} agents council contribute ${pending[0]} --message "<your take>"\` to weigh in.`
+    );
+  }
+  return `Councils waiting on your input (${pending.length} open): ${list}. Run \`${bin} agents council list --mine\` to see all of them, then \`${bin} agents council show <id>\` for any brief.`;
+}
+
+/**
+ * Suppress unused import warning when statSync isn't used in this file
+ * (kept exported for future renderers, e.g. heartbeat-freshness coloring).
+ */
+export const _ensureStatSyncImported = statSync;

package/src/core/agents/rules/claim-conflict.ts

@@ -0,0 +1,282 @@
+/**
+ * File-claim verdict.
+ *
+ * Phase 5 cutover: PreToolUse routes Edit/Write/NotebookEdit through here.
+ *
+ * Two checks:
+ *   1. Conflict: is the path already claimed by a fresh peer? Block with
+ *      the peer's name in the reason.
+ *   2. Ordering: if we already hold a claim on path A and want path
+ *      B, B must sort > A lexicographically. Otherwise emit
+ *      claim.conflict (ordering_violation) and block.
+ *
+ * Reads from `.harnery/active/<id>.json`, the single canonical heartbeat
+ * location after Phase 8 collapsed the v1/v2 dual-write.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const FRESHNESS_SECS = 600;
+
+export type VerdictResult = {
+  allow: boolean;
+  exit_code: 0 | 2;
+  rule: string;
+  reason?: string;
+};
+
+interface PeerView {
+  instance_id: string;
+  name?: string;
+  files_touched: string[];
+  last_heartbeat: string;
+  session_id: string;
+  /** parent_instance_id from heartbeat, present for subagent rows. Used by
+   *  the group-ownership check (sibling subagents + parent share a group
+   *  and don't block each other's claims).
+   */
+  parent_instance_id?: string;
+}
+
+export interface ClaimRequest {
+  rule: "claim";
+  instance_id: string;
+  session_id?: string;
+  path: string; // canonical monorepo-relative path
+  mode?: "read" | "write"; // default "write"
+}
+
+/**
+ * Evaluate a file-claim. Returns deny when another fresh peer claims the
+ * path, OR when this owner already holds a lower-sorted claim and the new
+ * one would create a circular wait.
+ */
+export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResult {
+  const peers = readPeers(coordRoot);
+  const myPeer = peers.find((p) => p.instance_id === req.instance_id);
+
+  // Group-ownership exclusion ("Option B" semantics): the parent
+  // session and all subagents under it share a group; claims within the
+  // group don't block each other. Compute the group root for the calling
+  // instance_id, then exclude any peer in the same group from the conflict
+  // scan. session_id from the payload is the parent_owner for subagents.
+  const groupRoot = computeGroupRoot(peers, req.instance_id, req.session_id);
+  const inMyGroup = (p: PeerView): boolean =>
+    p.instance_id === req.instance_id ||
+    p.instance_id === groupRoot ||
+    p.parent_instance_id === groupRoot ||
+    (p.parent_instance_id !== undefined && p.parent_instance_id === req.instance_id);
+
+  const otherPeers = peers.filter((p) => !inMyGroup(p));
+
+  // Conflict scan: any other fresh peer claiming this exact path?
+  const conflict = otherPeers.find(
+    (p) => isFresh(p.last_heartbeat) && p.files_touched.includes(req.path),
+  );
+  if (conflict) {
+    // Self-heal probe: if the file is committed-clean (exists in the repo AND has no uncommitted
+    // changes), the peer's claim is stale (worker crashed without releasing) →
+    // prune the claim from their heartbeat and allow the edit. Skips when the
+    // file doesn't exist (intent-to-create claim); that surface IS load-bearing.
+    if (isFileCommittedClean(coordRoot, req.path)) {
+      pruneClaimFromPeer(coordRoot, conflict.instance_id, req.path);
+      // Fall through to ordering check + allow.
+    } else {
+      return {
+        allow: false,
+        exit_code: 2,
+        rule: "claim.conflict",
+        reason: `File ${req.path} is currently being edited by agent-${conflict.name ?? conflict.instance_id.slice(0, 8)}. Wait for them to finish or pick a different file. Set HARNERY_AGENT_COORD_OFF=1 to bypass (not recommended).`,
+      };
+    }
+  }
+
+  // Ordering check: if we hold any claim with path < req.path, fine.
+  // Otherwise the new claim would create a backward-edge in the dependency
+  // graph and risk deadlock. Only applies when there are OTHER fresh peers:
+  // single-agent flow can't deadlock with itself, and the rule otherwise
+  // forces release-and-reacquire cycles on every reverse-order edit pair.
+  const hasFreshPeers = otherPeers.some(
+    (p) => isFresh(p.last_heartbeat) && p.files_touched.length > 0,
+  );
+  if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0) {
+    const highest = [...myPeer.files_touched].sort().at(-1)!;
+    if (req.path < highest) {
+      return {
+        allow: false,
+        exit_code: 2,
+        rule: "claim.ordering_violation",
+        reason: `Cannot acquire ${req.path} while holding ${highest} (claim ordering rule: paths must be acquired in sorted order). Release the higher claim first.`,
+      };
+    }
+  }
+
+  // Acquire the claim: atomic check-and-set. Adds req.path to my
+  // files_touched if not already present.
+  if (req.mode !== "read") {
+    addClaimToOwner(coordRoot, req.instance_id, req.path);
+  }
+
+  return { allow: true, exit_code: 0, rule: "claim.pass" };
+}
+
+/**
+ * Add `relPath` to the owner's heartbeat `files_touched` array (idempotent;
+ * no-op if already present). Atomic temp + rename. If the owner has no
+ * heartbeat yet (subagent that hasn't been initialized), creates a minimal one.
+ */
+function addClaimToOwner(coordRoot: string, instanceId: string, relPath: string): void {
+  const activeDir = join(coordRoot, ".harnery", "active");
+  if (!existsSync(activeDir)) return;
+  const path = join(activeDir, `${instanceId}.json`);
+  if (!existsSync(path)) {
+    const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const minimal = {
+      schema_version: 1,
+      instance_id: instanceId,
+      session_id: instanceId,
+      files_touched: [relPath],
+      started_at: now,
+      last_heartbeat: now,
+    };
+    try {
+      const tmp = `${path}.tmp.${process.pid}`;
+      writeFileSync(tmp, JSON.stringify(minimal, null, 2), "utf8");
+      renameSync(tmp, path);
+    } catch {
+      /* silent */
+    }
+    return;
+  }
+  try {
+    const body = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const files = (body.files_touched as string[] | undefined) ?? [];
+    if (files.includes(relPath)) return;
+    body.files_touched = [...files, relPath];
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
+    renameSync(tmp, path);
+  } catch {
+    /* silent */
+  }
+}
+
+function readPeers(coordRoot: string): PeerView[] {
+  const out: PeerView[] = [];
+  const path = join(coordRoot, ".harnery", "active");
+  if (!existsSync(path)) return out;
+  for (const f of readdirSync(path)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const hb = JSON.parse(readFileSync(join(path, f), "utf8")) as {
+        instance_id?: string;
+        name?: string;
+        session_id?: string;
+        files_touched?: string[];
+        last_heartbeat?: string;
+        parent_instance_id?: string;
+        parent_session_id?: string;
+      };
+      if (!hb.instance_id) continue;
+      // Derive parent_instance_id: explicit field first, then infer from
+      // session_id-differs-from-instance_id (the subagent shape:
+      // instance_id is the agent_id, session_id is the parent session).
+      const inferredParent =
+        hb.parent_instance_id ??
+        hb.parent_session_id ??
+        (hb.session_id && hb.session_id !== hb.instance_id ? hb.session_id : undefined);
+      out.push({
+        instance_id: hb.instance_id,
+        name: hb.name,
+        session_id: hb.session_id ?? hb.instance_id,
+        files_touched: hb.files_touched ?? [],
+        last_heartbeat: hb.last_heartbeat ?? "",
+        parent_instance_id: inferredParent,
+      });
+    } catch {
+      /* skip */
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the group root for `instanceId`. For a parent session it's instanceId
+ * itself. For a subagent it's the parent_instance_id from the heartbeat
+ * (stamped on subagent heartbeats). When session_id is
+ * supplied and differs from instanceId (Claude Code's `session_id != agent_id`
+ * shape for subagents), that's the group root too.
+ */
+function computeGroupRoot(peers: PeerView[], instanceId: string, sessionId?: string): string {
+  // If we have a peer entry, its parent_instance_id is authoritative.
+  const myPeer = peers.find((p) => p.instance_id === instanceId);
+  if (myPeer?.parent_instance_id) return myPeer.parent_instance_id;
+  // Fallback to session_id (parent's instance_id for subagents).
+  if (sessionId && sessionId !== instanceId) return sessionId;
+  // I am the group root.
+  return instanceId;
+}
+
+function isFresh(lastHeartbeat: string): boolean {
+  if (!lastHeartbeat) return false;
+  const ts = Date.parse(lastHeartbeat);
+  if (!Number.isFinite(ts)) return false;
+  return (Date.now() - ts) / 1000 <= FRESHNESS_SECS;
+}
+
+/**
+ * Check if a monorepo-relative path is committed-clean: file exists in the
+ * repo, is tracked, AND `git diff HEAD -- path` shows no uncommitted
+ * modifications. Untracked files are NOT committed-clean: `git diff HEAD`
+ * exits 0 on an untracked path (because git ignores it), so we have to
+ * positively confirm tracking via `git ls-files` before trusting the diff.
+ *
+ * Returns false when:
+ *  - file doesn't exist (intent-to-create, preserve the claim)
+ *  - file is untracked (peer wrote it, hasn't staged yet, preserve the claim)
+ *  - any git op fails (treat as dirty, fail-safe)
+ *  - diff shows non-empty output (genuinely dirty)
+ */
+function isFileCommittedClean(coordRoot: string, relPath: string): boolean {
+  const abs = join(coordRoot, relPath);
+  if (!existsSync(abs)) return false;
+  try {
+    const tracked = spawnSync("git", ["ls-files", "--error-unmatch", "--", relPath], {
+      cwd: coordRoot,
+      encoding: "utf8",
+      timeout: 2000,
+    });
+    if (tracked.status !== 0) return false;
+    const result = spawnSync("git", ["diff", "--quiet", "HEAD", "--", relPath], {
+      cwd: coordRoot,
+      encoding: "utf8",
+      timeout: 2000,
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove a stale claim from a peer's heartbeat. Atomic temp + rename. Silent
+ * on failure.
+ */
+function pruneClaimFromPeer(coordRoot: string, instanceId: string, relPath: string): void {
+  const path = join(coordRoot, ".harnery", "active", `${instanceId}.json`);
+  if (!existsSync(path)) return;
+  try {
+    const body = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const files = (body.files_touched as string[] | undefined) ?? [];
+    const next = files.filter((p) => p !== relPath);
+    if (next.length === files.length) return;
+    body.files_touched = next;
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
+    renameSync(tmp, path);
+  } catch {
+    /* silent */
+  }
+}