fapony 0.3.3 → 0.3.4

package/fapony.ts

@@ -1,121 +1,8 @@
 #!/usr/bin/env bun
 
 // fapony — measure/verify MCP server for coding agents
-// CLI dispatch: all logic lives in src/
+// CLI dispatch lives in src/adapters/cli.ts
 
-import { existsSync } from "node:fs";
-import { cmdAnalyze } from "./src/analyze.js";
-import { cmdDebt } from "./src/debt/cli.js";
-import { cmdDigest } from "./src/digest/cli.js";
-import {
-  cmdHookEditHint,
-  cmdHookReadHint,
-  cmdHookSessionStart,
-  cmdHookStop,
-} from "./src/hook.js";
-import { cmdInit } from "./src/init.js";
-import { cmdInitMem } from "./src/init-mem.js";
-import { cmdInstall } from "./src/install.js";
-import { cmdLintBaseline } from "./src/lint-baseline.js";
-import { cmdMcp } from "./src/mcp/transport.js";
-import { cmdMem } from "./src/mem/index.js";
-import { initStore } from "./src/mem/store.js";
-import { cmdPriceScan } from "./src/price/index.js";
-import { cmdReport, cmdReportWeb } from "./src/report/index.js";
-import { cmdPlanSeed } from "./src/seed/plan-seed.js";
-import { cmdReviewSeed } from "./src/seed/review-seed.js";
-import { cmdSetup } from "./src/setup.js";
-import { cmdStats } from "./src/stats/index.js";
-import { cmdTelemetry } from "./src/telemetry.js";
-import { cmdUpdate } from "./src/update.js";
-import { cmdUsageScan, cmdUsageWeb } from "./src/usage/index.js";
+import { cliMain } from "./src/adapters/cli.js";
 
-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") {
-  // `--mem-dir <path>` is global to `mem` and must reach both the writer
-  // (initStore) and the resolver behind `mem where` — parse it once and thread
-  // it through, never strip it and forget.
-  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-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") {
-  // dynamic: src/test.js re-exports test/index.js, which the npm package
-  // doesn't ship (repo self-check only, not a published command) — a static
-  // import here would fail module load for every command, not just this one
-  const { cmdTest } = await import("./src/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-session-start|test> [args]",
-  );
-  process.exit(1);
-}
+cliMain();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus a project mem log and convention-debt tracker agents query via 3 MCP tools. No server, your data stays local",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
@@ -18,7 +18,7 @@
     "coding-agent"
   ],
   "bin": {
-    "fapony": "./fapony.ts"
+    "fapony": "fapony.ts"
   },
   "files": [
     "fapony.ts",

package/skill/move-to-done/SKILL.md

@@ -40,8 +40,9 @@ You are about to move a PLAN that has been shipped to the archive.
    of `done/`, which is what `plan-sweep` and `kickoff` go by.
 
 2. **Run `plan-sweep --apply`** — this does the `git mv`, rewrites markdown links inside the
-   file and inbound links from other plan files, warns about plain-text mentions, and logs
-   a decision row — all in one call:
+   file and inbound links from every `.md` under `.fapony/` (`plan/`, `done/`, `spec/`),
+   warns about plain-text mentions and about tracked files outside `.fapony/` that still
+   name the file (both detect-only), and logs a decision row — all in one call:
    ```bash
    fapony mem plan-sweep <PLAN-foo.md> --apply
    ```

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