fapony 0.3.0 → 0.3.4

package/skill/review-pony/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-pony
-description: Review a plan, PR, diff, or design doc as a verification rather than an opinion — scope first, walk the real path, break it on paper, cite everything. Takes optional effort (low|medium|high|max, widens the walk only, never skips a pass) and --fix (apply CONFIRMED blocker/major findings after the report). Records the verdict to fapony after the report. Trigger on /review-pony and proactively whenever the user asks to review, audit, scrutinize, sanity-check, or get a second opinion on a plan, PR, diff, design doc, or proposed code change.
+description: Review a plan, PR, diff, or design doc as a verification rather than an opinion — scope first, walk the real path, break it on paper, cite everything. Takes optional effort (low|medium|high|max, widens the walk only, never skips a pass) and --fix (apply CONFIRMED blocker/major findings after the report). Records surviving findings to the project's mem log after the report. Trigger on /review-pony and proactively whenever the user asks to review, audit, scrutinize, sanity-check, or get a second opinion on a plan, PR, diff, design doc, or proposed code change.
 ---
 
 # Review Pony
@@ -83,10 +83,10 @@ Write down every place the walk surprises you. Surprises outrank style; chase th
 - `low` — direct callers only, one hop. No test reading unless the diff touches a test file.
 - `medium` (default) — as written above: full path, callers, tests on the path.
 - `high` — also second-degree callers, and read the tests that exercise them, not just the path.
-- `max` — also run `get_impact_radius_tool` (or grep if the graph isn't wired) on every changed
-  file and re-open every `deferred` line from the last review of this scope, if fapony has one.
+- `max` — also grep every changed file for second-degree callers, and re-open
+  every `deferred` line from the last review of this scope, if fapony has one.
 
-Whatever level stopped you, say so in the one-line coverage note (rule below) — "walked to 1 hop"
+Whatever level stopped you, say so in the one-line coverage note (see Report) — "walked to 1 hop"
 is honest, "walked" alone at `low` is not.
 
 ## Pass 3 — A finding needs a failing input
@@ -161,56 +161,25 @@ fixed: 1, 2 · skipped: 3 (PLAUSIBLE — could not reach the failing state)
 ```
 
 Fixing changes what actually shipped, not what the review found — re-run pass 4's citation
-check on the new state before calling it done, but don't re-run the whole review. Submit the
-verdict on what you found, not on the post-fix state (`verdict_submit`'s `note` can say the fix
-was applied).
-
-## After: record the verdict (fapony)
-
-Call `verdict_submit` once, after the report is shown. Don't block the report on it, and don't
-let it change the report's content. Pass `regime="review"` — required, and a review is what this
-was; it is what puts this run in the `regime × model` table.
-
-| Report verdict | `verdict` |
-|---|---|
-| ship, 0 findings | `pass-excellent` |
-| ship, nit-only findings | `pass-good` |
-| fix-then-ship | `pass-adequate` |
-| rework / reject | `fail` |
-| could not walk enough to have a verdict | `uncertain` |
-
-`uncertain` is not a softer `fail`. It is the honest answer when the walk never
-reached the thing under review — the branch wouldn't build, the path is behind a
-service you cannot run, every finding came out `PLAUSIBLE`. Say so in the report
-too. Guessing `pass` there is the one outcome that makes the ledger lie.
-
-`reason_code` — the *lead* (most severe) finding, not a generic bucket:
-
-- **0 findings, or a clean pass → `none`** — never `other`. `other` means "a real
-  finding that none of these buckets name", so filing clean passes there puts them
-  in the recurring-fail-reasons list, where they crowd out the reasons that mean
-  something. It is the one value in this table that costs other people accuracy.
-- missing or weak test coverage on the path you walked → `missing_test`
-- change is narrower or wider than the plan / PR description claims → `scope_mismatch`
-- a shell/eval/deploy command runs without the guard it needs → `unsafe_command`
-- the plan or spec didn't cover a case the walk exposed → `spec_gap`
-- the change stops short of what it set out to do → `incomplete`
-- a real finding none of the above names → `other`, and then `note` is **required**
-
-Always attach a one-line `note` — the only field a later review can act on. Say what broke or
-was walked, not that a review happened.
-
-Args: `verdict`, `reason_code`, `note`, `regime`, `worktree` — **absolute path** via
-`git rev-parse --show-toplevel`, never a bare name (`runs.worktree` is free text; a bare name
-writes where no query reads it and every fapony tool misses the run), `plan` (the PLAN file
-path under review, omitted for a bare PR/diff), and `files` — the repo-relative paths you
-actually walked. **Always send `files`.** It is the only input to per-file risk history; a
-verdict without it tells the next session that something failed but not where. No `run_id` —
-fapony reuses the latest still-open run for the same worktree+plan (so round 2+ counts toward
-the round cap), creating a row only when none is open. `session_id` (optional) — the client
-session id, only if the client exposes it; attribute the model, never block the submit on it.
-If `verdict_submit` errors, say so in one line and move on — never re-run a review because
-storage failed.
+check on the new state before calling it done, but don't re-run the whole review. Record
+what you found, not the post-fix state (the row's text can say the fix was applied).
+
+## After: record what the next session needs (fapony)
+
+If a blocker/major CONFIRMED finding survived, or the verdict is rework/reject,
+call `mem_add` once, after the report is shown. Don't block the report on it,
+and don't let it change the report's content. Clean reviews (ship, nit-only
+findings) record nothing — there is nothing the next session needs to find.
+
+kind is `bug` when a finding survived (something is broken), `decision` when
+the verdict turns on scope alone (rework/reject from pass 1 — the review locks
+a direction). text is the report's verdict line, standalone — what broke or was
+decided, not that a review happened. files are the repo-relative paths actually
+walked — required, a row without them is unfindable. worktree is the absolute
+path (`git rev-parse --show-toplevel`), never a bare name. Only record into a
+project that already has a mem log — never create one uninvited.
+If `mem_add` errors, say so in one line and move on — never re-run a review
+because storage failed.
 
 ---
 
@@ -232,10 +201,10 @@ The four passes are the rules. These three are what they fail on in practice:
 ```
 1-4.  scope holds; walked the new gate branch; ran the evidence command — it exits 0
       without running the suite (CONFIRMED: `bun test` with no test dir exits 0)
-post. verdict_submit(verdict="pass-adequate", reason_code="other", regime="review",
-        note="evidence entry `bun test` exits 0 while running zero tests — real entry is `bun run test`",
-        worktree="/Users/you/Project/fapony/wt-fapony",
-        plan=".fapony/plan/PLAN-verdict-notes.md")
+post. mem_add(kind="bug",
+        text="incremental scan replaces cached history with a delta — cache holds 500, truth 1500",
+        files=["cache.ts", "claude-code.ts"],
+        worktree="/Users/you/Project/fapony/wt-fapony")
 ```
 
 A report in budget — same review that, narrated, ran five paragraphs:

package/src/adapters/cli.ts

@@ -0,0 +1,123 @@
+// src/adapters/cli.ts — CLI dispatch: parse argv and route to feature modules
+//
+// Extracted from fapony.ts (PLAN-lib-layer chunk 3). The entry point
+// (fapony.ts) calls cliMain(); this file owns all feature imports and the
+// argv routing.
+
+import { existsSync } from "node:fs";
+import { cmdAnalyze } from "../analyze.js";
+import { cmdDebt } from "../debt/cli.js";
+import { cmdDigest } from "../digest/cli.js";
+import { cmdInit } from "../init.js";
+import { cmdInitMem } from "../init-mem.js";
+import { cmdInstall } from "../install.js";
+import { cmdLintBaseline } from "../lint-baseline.js";
+import { cmdMem } from "../mem/index.js";
+import { initStore } from "../mem/store.js";
+import { cmdPriceScan } from "../price/index.js";
+import { cmdReport, cmdReportWeb } from "../report/index.js";
+import { cmdPlanSeed } from "../seed/plan-seed.js";
+import { cmdReviewSeed } from "../seed/review-seed.js";
+import { cmdSetup } from "../setup.js";
+import { cmdStats } from "../stats/index.js";
+import { cmdTelemetry } from "../telemetry.js";
+import { cmdUpdate } from "../update.js";
+import { cmdUsageScan, cmdUsageWeb } from "../usage/index.js";
+import {
+  cmdHookEditHint,
+  cmdHookMvGuard,
+  cmdHookReadHint,
+  cmdHookSessionStart,
+  cmdHookStop,
+} from "./hooks/index.js";
+import { cmdMcp } from "./mcp/transport.js";
+
+export async function cliMain(): Promise<void> {
+  const [cmd, ...a] = process.argv.slice(2);
+
+  if (cmd === "analyze") {
+    cmdAnalyze(a);
+  } else if (cmd === "debt") {
+    cmdDebt(a);
+  } else if (cmd === "lint-baseline") {
+    cmdLintBaseline(a);
+  } else if (cmd === "plan-seed") {
+    cmdPlanSeed(a);
+  } else if (cmd === "review-seed") {
+    cmdReviewSeed(a);
+  } else if (cmd === "digest") {
+    await cmdDigest(a);
+  } else if (cmd === "stats") {
+    cmdStats(a);
+  } else if (cmd === "telemetry") {
+    await cmdTelemetry(a);
+  } else if (cmd === "init-mem") {
+    cmdInitMem(a);
+  } else if (cmd === "mem") {
+    const memDirIdx = a.indexOf("--mem-dir");
+    let overrideMemDir: string | undefined;
+    let rest = a;
+    if (memDirIdx !== -1) {
+      overrideMemDir = a[memDirIdx + 1];
+      if (!overrideMemDir || overrideMemDir.startsWith("--")) {
+        console.error("fapony mem: --mem-dir needs a value");
+        process.exit(1);
+      }
+      if (!existsSync(overrideMemDir)) {
+        console.error(
+          `fapony mem: --mem-dir path does not exist: ${overrideMemDir}`,
+        );
+        process.exit(1);
+      }
+      rest = a.filter((_, i) => i !== memDirIdx && i !== memDirIdx + 1);
+    }
+    initStore(process.cwd(), overrideMemDir);
+    try {
+      await cmdMem(rest, overrideMemDir);
+    } catch (e) {
+      console.error(
+        `fapony mem: ${e instanceof Error ? e.message : String(e)}`,
+      );
+      process.exit(1);
+    }
+  } else if (cmd === "init") {
+    await cmdInit(a);
+  } else if (cmd === "install") {
+    await cmdInstall(a);
+  } else if (cmd === "setup") {
+    await cmdSetup();
+  } else if (cmd === "update") {
+    await cmdUpdate();
+  } else if (cmd === "hook-stop") {
+    await cmdHookStop();
+  } else if (cmd === "hook-read-hint") {
+    await cmdHookReadHint();
+  } else if (cmd === "hook-edit-hint") {
+    await cmdHookEditHint();
+  } else if (cmd === "hook-mv-guard") {
+    await cmdHookMvGuard();
+  } else if (cmd === "hook-session-start") {
+    await cmdHookSessionStart();
+  } else if (cmd === "mcp") {
+    cmdMcp();
+  } else if (cmd === "report") {
+    cmdReport(a);
+  } else if (cmd === "report-web") {
+    cmdReportWeb(a);
+  } else if (cmd === "usage-scan") {
+    cmdUsageScan(a);
+  } else if (cmd === "price-scan") {
+    await cmdPriceScan(a);
+  } else if (cmd === "usage-web") {
+    cmdUsageWeb(a);
+  } else if (cmd === "test") {
+    const { cmdTest } = await import("../test.js");
+    await cmdTest();
+  } else {
+    console.error(`fapony: unknown command "${cmd ?? ""}"`);
+    console.error(
+      "usage: fapony <setup|update|stats|telemetry|init|init-mem|mem|install|report|report-web|usage-scan|usage-web|price-scan|analyze|debt|lint-baseline|plan-seed|review-seed|digest|mcp|hook-stop|hook-read-hint|hook-edit-hint|hook-mv-guard|hook-session-start|test> [args]",
+    );
+    process.exit(1);
+  }
+}

package/src/adapters/hooks/compute-hint-impact.ts

@@ -0,0 +1,107 @@
+// src/adapters/hooks/compute-hint-impact.ts — hint-fire impact computation
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Reads hint log + re-runs
+// debt detection to count resolved vs unresolved hints.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import {
+  type HintFireRow,
+  type HintImpact,
+  hintLogDir,
+  worktreeKey,
+} from "../../core/hint-log.js";
+import { debtForFile, loadConventions } from "../../debt/index.js";
+
+/**
+ * Compute hint-fire impact from the log. `since` is an ISO date string;
+ * omit to scan all rows. `worktree` scopes to one project's log file.
+ */
+export function computeHintImpact(
+  since?: string,
+  worktree?: string,
+): HintImpact {
+  const dir = hintLogDir();
+  const impact: HintImpact = {
+    fired: 0,
+    by_surface: { read: 0, debt: 0, mem: 0, commit: 0, edit: 0 },
+    debt: { shown: 0, resolved: 0, unknown: 0 },
+    window: since ?? null,
+  };
+
+  if (!existsSync(dir)) return impact;
+
+  let files: string[];
+  try {
+    const all = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    files = worktree
+      ? all.filter((f) => f === `${worktreeKey(worktree)}.jsonl`)
+      : all;
+  } catch {
+    return impact;
+  }
+
+  const debtShown = new Map<string, true>();
+  const debtByFile = new Map<string, string[]>();
+
+  for (const file of files) {
+    let content: string;
+    try {
+      content = readFileSync(join(dir, file), "utf-8");
+    } catch {
+      continue;
+    }
+    for (const line of content.split("\n")) {
+      if (!line) continue;
+      let row: HintFireRow;
+      try {
+        row = JSON.parse(line) as HintFireRow;
+      } catch {
+        continue;
+      }
+      if (since && row.ts < since) continue;
+      impact.fired++;
+      impact.by_surface[row.surface]++;
+
+      if (row.surface === "debt" && row.ids && row.file) {
+        const key = `${row.worktree}\t${row.file}`;
+        const existing = debtByFile.get(key) ?? [];
+        for (const id of row.ids) {
+          const dk = `${row.worktree}\t${row.file}\t${id}`;
+          if (!debtShown.has(dk)) {
+            debtShown.set(dk, true);
+            existing.push(id);
+          }
+        }
+        debtByFile.set(key, existing);
+      }
+    }
+  }
+
+  for (const [key, ids] of debtByFile) {
+    const [worktree, file] = key.split("\t");
+    const absFile = join(worktree, file);
+    let currentIds: Set<string>;
+    try {
+      if (!statSync(absFile).isFile()) {
+        impact.debt.unknown += ids.length;
+        continue;
+      }
+      const convs = debtForFile(worktree, absFile, loadConventions(worktree));
+      currentIds = new Set(convs.map((c) => c.id));
+    } catch {
+      impact.debt.unknown += ids.length;
+      continue;
+    }
+    for (const id of ids) {
+      impact.debt.shown++;
+      if (currentIds.has(id)) {
+        // still present — not resolved
+      } else {
+        impact.debt.resolved++;
+      }
+    }
+  }
+
+  return impact;
+}

package/src/adapters/hooks/context-data.ts

@@ -0,0 +1,102 @@
+// src/adapters/hooks/context-data.ts — shared debt + mem context reader
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Used by both read-hint and
+// edit-hint adapters to attach debt/mem lines when a file is open.
+
+import { realpathSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { collectSourceFiles, SCAN_EXTS } from "../../analyze.js";
+import { debtForFile, loadConventions } from "../../debt/index.js";
+import { readMemLog } from "../../memory.js";
+
+const DEBT_HINT_MAX = 3;
+const MEM_HINT_MAX = 2;
+const MEM_TEXT_MAX = 120;
+
+export interface ContextLineData {
+  worktree: string;
+  debtIds: string[];
+  debtLines: string[];
+  memLines: string[];
+}
+
+/** Structured data behind readContextLines — used by cmdHookReadHint for logging. */
+export function readContextData(
+  filePath: unknown,
+  cwd: string,
+): ContextLineData | null {
+  try {
+    if (typeof filePath !== "string" || filePath === "") return null;
+    const git = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (git.exitCode !== 0) return null;
+    const worktree = realpathSync(git.stdout.toString().trim());
+    const abs = realpathSync(
+      filePath.startsWith("/") ? filePath : join(worktree, filePath),
+    );
+    const rel = relative(worktree, abs).split("\\").join("/");
+    if (rel.startsWith("..") || rel === "") return null;
+
+    const debtIds: string[] = [];
+    const debtLines: string[] = [];
+    const memLines: string[] = [];
+
+    // convention debt — source files only, fresh from the repo
+    const dot = rel.lastIndexOf(".");
+    if (dot >= 0 && SCAN_EXTS.has(rel.slice(dot))) {
+      for (const c of debtForFile(
+        worktree,
+        abs,
+        loadConventions(worktree),
+      ).slice(0, DEBT_HINT_MAX)) {
+        debtIds.push(c.id);
+        debtLines.push(`fapony debt: [${c.id}] ${c.rule}`);
+      }
+    }
+
+    // mem rows that are about this file
+    const mem = readMemLog(worktree);
+    if (mem.rows.length > 0) {
+      const base = basename(rel);
+      const direct: typeof mem.rows = [];
+      const baseOnly: typeof mem.rows = [];
+      for (const r of mem.rows) {
+        if (r.kind === "claim" || r.kind === "release") continue;
+        const hay = `${r.text}\n${r.spec ?? ""}\n${(r.files ?? []).join(",")}`;
+        if ((r.files ?? []).includes(rel) || hay.includes(rel)) {
+          direct.push(r);
+          continue;
+        }
+        if (base && hay.includes(base)) baseOnly.push(r);
+      }
+      let usableBase = baseOnly;
+      if (baseOnly.length > 0) {
+        const sameName = collectSourceFiles(worktree).filter(
+          (f) => basename(f) === base,
+        ).length;
+        if (sameName !== 1) usableBase = [];
+      }
+      const memHits = [...direct, ...usableBase].slice(0, MEM_HINT_MAX);
+      for (const r of memHits) {
+        memLines.push(
+          `fapony mem: ${r.ts.slice(0, 10)} ${r.kind} — ${r.text.slice(0, MEM_TEXT_MAX)}`,
+        );
+      }
+    }
+    return { worktree, debtIds, debtLines, memLines };
+  } catch {
+    return null;
+  }
+}
+
+export function readContextLines(filePath: unknown, cwd: string): string[] {
+  const data = readContextData(filePath, cwd);
+  if (!data) return [];
+  return [...data.debtLines, ...data.memLines].slice(
+    0,
+    DEBT_HINT_MAX + MEM_HINT_MAX,
+  );
+}

package/src/adapters/hooks/edit-hint.ts

@@ -0,0 +1,195 @@
+// src/adapters/hooks/edit-hint.ts — Edit hint: importer count + once-per-session dedupe
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Attaches importer count
+// when editing a source file.
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, relative, sep } from "node:path";
+import { buildGraphCached, SCAN_EXTS } from "../../analyze.js";
+import { recordHintFire } from "../../core/hint-log.js";
+import { sessionKey } from "../../core/hook-helpers.js";
+import { readContextData } from "./context-data.js";
+
+const EDIT_TRACK_DIR = "edit-track";
+
+export interface EditTrackRow {
+  ts: string;
+  path: string;
+}
+
+/** Directory holding one edit log per session. */
+function editTrackDir(): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, EDIT_TRACK_DIR);
+}
+
+/** Absolute path of a session's edit log — may not exist. */
+export function editTrackPath(session: string): string {
+  return join(editTrackDir(), `${sessionKey(session)}.jsonl`);
+}
+
+function editTrackPaths(session: string): Set<string> {
+  const p = editTrackPath(session);
+  if (!existsSync(p)) return new Set();
+  const out = new Set<string>();
+  for (const line of readFileSync(p, "utf-8").split("\n")) {
+    if (!line) continue;
+    try {
+      const r = JSON.parse(line) as EditTrackRow;
+      if (typeof r.path === "string") out.add(r.path);
+    } catch {
+      // a torn line must not lose the rest of the log
+    }
+  }
+  return out;
+}
+
+function appendEditTrackRow(session: string, row: EditTrackRow): void {
+  const dir = editTrackDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(editTrackPath(session), `${JSON.stringify(row)}\n`, "utf-8");
+}
+
+export interface EditHintInput {
+  filePath: unknown;
+  cwd: string;
+  session?: unknown;
+}
+
+/**
+ * Factual one-liner for editing a source file that has importers, or null.
+ * Every unknown resolves to null — a hint must never fire on a guess.
+ */
+export function editHintFor(opts: EditHintInput): string | null {
+  try {
+    if (typeof opts.filePath !== "string" || opts.filePath === "") return null;
+    const dot = opts.filePath.lastIndexOf(".");
+    if (dot < 0 || !SCAN_EXTS.has(opts.filePath.slice(dot))) return null;
+    const git = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+      cwd: opts.cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (git.exitCode !== 0) return null;
+    const worktree = realpathSync(git.stdout.toString().trim());
+    const abs = (() => {
+      const p = opts.filePath.startsWith("/")
+        ? opts.filePath
+        : join(opts.cwd, opts.filePath);
+      try {
+        return realpathSync(p);
+      } catch {
+        return null;
+      }
+    })();
+    if (!abs) return null;
+    const rel = relative(worktree, abs).split(sep).join("/");
+    if (rel.startsWith("..") || rel === "") return null;
+
+    const importers = buildGraphCached(worktree).dependents.get(rel);
+    if (!importers || importers.size === 0) return null;
+
+    if (typeof opts.session === "string" && opts.session !== "") {
+      if (editTrackPaths(opts.session).has(abs)) return null;
+      appendEditTrackRow(opts.session, {
+        ts: new Date().toISOString(),
+        path: abs,
+      });
+    }
+
+    const n = importers.size;
+    return (
+      `fapony: ${rel} has ${n} importer${n === 1 ? "" : "s"} — ` +
+      `review-seed --files ${rel} lists them (add --callers <export> for one ` +
+      `export's callers); check before changing its shape (skill /lookup-before-edit)`
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Claude Code PreToolUse (matcher Edit): stdin JSON in, additionalContext out. */
+export async function cmdHookEditHint(): Promise<void> {
+  try {
+    const raw = JSON.parse(await Bun.stdin.text()) as {
+      cwd?: string;
+      transcript_path?: string;
+      session_id?: string;
+      tool_input?: {
+        file_path?: unknown;
+      };
+    };
+    const cwd = raw.cwd ?? process.cwd();
+    const filePath = raw.tool_input?.file_path;
+    const session = raw.transcript_path ?? raw.session_id;
+    const parts: string[] = [];
+    const hint = editHintFor({ filePath, cwd, session });
+    if (hint) parts.push(hint);
+    const ctx = readContextData(filePath, cwd);
+    if (ctx) {
+      for (const line of [...ctx.debtLines, ...ctx.memLines]) {
+        parts.push(line);
+      }
+    }
+    if (parts.length > 0) {
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: parts.join("\n"),
+          },
+        }),
+      );
+    }
+
+    // --- hint-fire log ---
+    if (hint) {
+      try {
+        const g = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+          cwd,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        if (g.exitCode === 0) {
+          const worktree = realpathSync(g.stdout.toString().trim());
+          const abs =
+            typeof filePath === "string"
+              ? (() => {
+                  try {
+                    return realpathSync(
+                      filePath.startsWith("/")
+                        ? filePath
+                        : join(worktree, filePath),
+                    );
+                  } catch {
+                    return null;
+                  }
+                })()
+              : null;
+          const rel = abs
+            ? relative(worktree, abs).split("\\").join("/")
+            : null;
+          recordHintFire({
+            ts: new Date().toISOString(),
+            worktree,
+            surface: "edit",
+            file: rel && !rel.startsWith("..") ? rel : null,
+            count: 1,
+          });
+        }
+      } catch {
+        // best-effort — swallow
+      }
+    }
+  } catch {
+    // any failure = no hint; a hook must never block an edit over a hint
+  }
+}