fapony 0.3.3 → 0.3.4

package/src/adapters/hooks/git-autonomy.ts

@@ -0,0 +1,178 @@
+// src/adapters/hooks/git-autonomy.ts — git-autonomy rewrites as shared logic.
+//
+// A personal opencode plugin (~/.config/opencode/plugins/git-autonomy.ts)
+// rewrote opencode's built-in "never commit unless asked" policy on two
+// surfaces: the system prompt (experimental.chat.system.transform) and the
+// bash tool description (tool.definition). This module is that file's logic,
+// extracted so `fapony install --platform opencode --git-autonomy` can
+// generate a thin plugin that imports it — one copy, updated by `git pull`,
+// same shape as the read/commit/edit/session-start hints.
+//
+// Opt-in only: the installer never writes this unless the flag is passed.
+// The rewrite itself is an opinion (commit-as-you-go), not a utility, so it
+// must never ride the default install path.
+//
+// Stale-regex guard (the "rots silently" problem): upstream text lives in the
+// opencode binary, not in a file, so a reword upstream makes a pattern stop
+// matching with no error. Every rewrite carries `required`; `gitAutonomyStatus`
+// reports required ids that hit nothing — the analyze-like help for this
+// feature. The tone-example cut is required:false: versions without those
+// examples are fine, a missing commit policy is not.
+
+/** Commit-as-you-go policy replacing opencode's ask-first rule. */
+export const GIT_AUTONOMY_COMMIT_POLICY =
+  "Commit each finished unit of work as you go — do not wait to be asked. If the user wants to review before a commit they will say so.";
+
+/** Same policy, bash-tool-description surface. */
+export const GIT_AUTONOMY_TOOL_POLICY =
+  "Commit finished work as you go — do not wait to be asked; never amend published commits or force-push.";
+
+export const GIT_AUTONOMY_PLUGIN_FILE = "fapony-git-autonomy.ts";
+export const GIT_AUTONOMY_PLUGIN_NAME = "FaponyGitAutonomy";
+
+export interface GitAutonomyRewrite {
+  /** Stable id used by gitAutonomyStatus to name the stale pattern. */
+  id: string;
+  pattern: RegExp;
+  replacement: string;
+  /** False = a miss is fine (upstream dropped that text). True = a miss is rot. */
+  required: boolean;
+}
+
+export const GIT_AUTONOMY_SYSTEM_REWRITES: GitAutonomyRewrite[] = [
+  {
+    id: "system-commit-full",
+    pattern: /NEVER commit changes[\s\S]{0,500}?too proactive\./g,
+    replacement: GIT_AUTONOMY_COMMIT_POLICY,
+    required: true,
+  },
+  {
+    id: "system-commit-fallback",
+    pattern: /NEVER commit changes[^.]*\./g,
+    replacement: GIT_AUTONOMY_COMMIT_POLICY,
+    required: true,
+  },
+  {
+    id: "system-bash-desc",
+    pattern:
+      /- Only commit, amend, push, or create PRs when explicitly requested\./g,
+    replacement:
+      "- Commit and push finished work as you go, and open a PR when a branch is ready. Do not amend published commits or force-push.",
+    required: true,
+  },
+  {
+    // "# Tone and style" few-shot examples: from the intro down to the next
+    // heading. Anchored on the unique intro so no other <example> block is
+    // touched. Pure token rent — the surrounding sentences already state the
+    // terseness rules.
+    id: "system-tone-examples",
+    pattern:
+      /Here are some examples to demonstrate appropriate verbosity:[\s\S]*?(?=\n# )/g,
+    replacement: "",
+    required: false,
+  },
+];
+
+export interface GitAutonomyToolRewrite extends GitAutonomyRewrite {
+  toolID: string;
+}
+
+export const GIT_AUTONOMY_TOOL_REWRITES: GitAutonomyToolRewrite[] = [
+  {
+    id: "tool-bash-commit",
+    toolID: "bash",
+    pattern:
+      /- Only commit, amend, push, or create PRs when explicitly requested\./g,
+    replacement: `- ${GIT_AUTONOMY_TOOL_POLICY}`,
+    required: true,
+  },
+];
+
+function fresh(re: RegExp): RegExp {
+  // /g patterns are stateful via lastIndex — clone so repeated calls and
+  // .test-then-.replace sequences never skip a match.
+  return new RegExp(re.source, re.flags);
+}
+
+/**
+ * Apply the system-prompt rewrites. Returns the rewritten text plus the ids
+ * that fired, in order — the caller (plugin) ignores the second half, tests
+ * and gitAutonomyStatus use it to tell "rewrote" from "silently missed".
+ */
+export function rewriteGitAutonomySystem(text: string): {
+  text: string;
+  matched: string[];
+} {
+  const matched: string[] = [];
+  let out = text;
+  for (const r of GIT_AUTONOMY_SYSTEM_REWRITES) {
+    const re = fresh(r.pattern);
+    if (re.test(out)) {
+      matched.push(r.id);
+      out = out.replace(fresh(r.pattern), r.replacement);
+      // The loose fallback must never run once the full block was replaced.
+      if (r.id === "system-commit-full") break;
+    }
+  }
+  return { text: out, matched };
+}
+
+/** Apply the tool.description rewrites for one toolID. */
+export function rewriteGitAutonomyTool(
+  toolID: string,
+  description: string,
+): { description: string; matched: string[] } {
+  const matched: string[] = [];
+  let out = description;
+  for (const r of GIT_AUTONOMY_TOOL_REWRITES) {
+    if (r.toolID !== toolID) continue;
+    const re = fresh(r.pattern);
+    if (re.test(out)) {
+      matched.push(r.id);
+      out = out.replace(fresh(r.pattern), r.replacement);
+    }
+  }
+  return { description: out, matched };
+}
+
+export interface GitAutonomyStatus {
+  /** Required ids that fired at least once across the inputs. */
+  hits: string[];
+  /** Required ids that hit nothing — upstream reworded or moved the text. */
+  stale: string[];
+  /** True when no required pattern is stale. */
+  ok: boolean;
+}
+
+/**
+ * Analyze-like help for this feature: feed the current opencode system lines
+ * + tool descriptions, get back which required patterns are stale. Optional
+ * rewrites (tone examples) never appear in `stale` — their absence is fine.
+ */
+export function gitAutonomyStatus(
+  systemTexts: string[],
+  toolDescs: Record<string, string>,
+): GitAutonomyStatus {
+  const seen = new Set<string>();
+  for (const t of systemTexts) {
+    for (const id of rewriteGitAutonomySystem(t).matched) seen.add(id);
+  }
+  for (const [toolID, desc] of Object.entries(toolDescs)) {
+    for (const id of rewriteGitAutonomyTool(toolID, desc).matched) seen.add(id);
+  }
+  const requiredIds = new Set<string>();
+  for (const r of GIT_AUTONOMY_SYSTEM_REWRITES)
+    if (r.required) requiredIds.add(r.id);
+  for (const r of GIT_AUTONOMY_TOOL_REWRITES)
+    if (r.required) requiredIds.add(r.id);
+  // system-commit-full and system-commit-fallback are two spellings of one
+  // policy: either hit means the policy landed, only both missing is stale.
+  const commitHit =
+    seen.has("system-commit-full") || seen.has("system-commit-fallback");
+  const hits = [...seen].filter((id) => requiredIds.has(id));
+  const stale: string[] = [];
+  if (!commitHit) stale.push("system-commit");
+  if (!seen.has("system-bash-desc")) stale.push("system-bash-desc");
+  if (!seen.has("tool-bash-commit")) stale.push("tool-bash-commit");
+  return { hits, stale, ok: stale.length === 0 };
+}

package/src/adapters/hooks/index.ts

@@ -0,0 +1,79 @@
+// src/adapters/hooks/index.ts — re-export all hook adapters
+
+// Re-export hint-log for backwards compatibility.
+export {
+  type HintFireRow,
+  type HintImpact,
+  hintLogDir,
+  hintLogPath,
+  recordHintFire,
+  worktreeKey,
+} from "../../core/hint-log.js";
+// Re-export pure helpers from core for backwards compatibility.
+export {
+  hookTsMs,
+  sessionKey,
+  utcStamp,
+} from "../../core/hook-helpers.js";
+export { computeHintImpact } from "./compute-hint-impact.js";
+export {
+  type ContextLineData,
+  readContextData,
+  readContextLines,
+} from "./context-data.js";
+export {
+  cmdHookEditHint,
+  type EditHintInput,
+  type EditTrackRow,
+  editHintFor,
+  editTrackPath,
+} from "./edit-hint.js";
+export {
+  GIT_AUTONOMY_COMMIT_POLICY,
+  GIT_AUTONOMY_PLUGIN_FILE,
+  GIT_AUTONOMY_PLUGIN_NAME,
+  GIT_AUTONOMY_SYSTEM_REWRITES,
+  GIT_AUTONOMY_TOOL_POLICY,
+  GIT_AUTONOMY_TOOL_REWRITES,
+  type GitAutonomyRewrite,
+  type GitAutonomyStatus,
+  type GitAutonomyToolRewrite,
+  gitAutonomyStatus,
+  rewriteGitAutonomySystem,
+  rewriteGitAutonomyTool,
+} from "./git-autonomy.js";
+export { cmdHookMvGuard, mvGuardDecision } from "./mv-guard.js";
+export {
+  COMMIT_HINT_MIN_COMMITS,
+  type CommitHintInput,
+  cmdHookReadHint,
+  commitHintFor,
+  READ_HINT_MIN_BYTES,
+  READ_HINT_MIN_LIMIT,
+  type ReadHintInput,
+  type ReadTrackRow,
+  type RereadHintInput,
+  readHintFor,
+  readTrackPath,
+  rereadHintFor,
+} from "./read-hint.js";
+export {
+  capContext,
+  cmdHookSessionStart,
+  SESSION_START_MAX_CHARS,
+  sessionStartContext,
+} from "./session-start.js";
+export {
+  cmdHookStop,
+  cursorTranscriptPath,
+  decideStop,
+  isCodexPayload,
+  isCursorPayload,
+  type NormalizedStopInput,
+  normalizeStopInput,
+  type RawStopPayload,
+  type StopClient,
+  stopBlockedBefore,
+  stopBlockPath,
+  stopOutput,
+} from "./stop.js";

package/src/adapters/hooks/mv-guard.ts

@@ -0,0 +1,52 @@
+// src/adapters/hooks/mv-guard.ts — PreToolUse Bash guard: deny a raw `git mv`
+// of a plan file into a done/ directory, point at `fapony mem plan-sweep
+// --apply` instead.
+//
+// Manual `git mv` skips the link rewrite plan-sweep does — that produced two
+// rounds of dangling links (mem mtjn3ldk, mtl15q4y) and once, a plan moved to
+// a path that doesn't exist (.fapony/plan/done/ instead of .fapony/done/).
+// Every other fapony hook only annotates; this one denies, because asking
+// ("should use plan-sweep") measurably does not change agent behavior —
+// only required/reject and Stop-style blocks do (CLAUDE.md rule 9).
+//
+// Claude-only: OpenCode's tool.execute.after fires after the mv already ran,
+// so there is nothing left to deny by the time that hook sees it.
+
+const MV_PATTERN =
+  /git\s+mv\s+(?:-\S+\s+)*["']?([^"'\s]*\.fapony\/(?:[^/\s]+\/)*plan\/PLAN-[^"'\s]+\.md)["']?\s+["']?([^"'\s]*\bdone\/?)["']?/;
+
+/** Deny reason for a raw `git mv <plan>.md <...done/>` command, or null to allow. */
+export function mvGuardDecision(command: unknown): string | null {
+  if (typeof command !== "string" || command === "") return null;
+  const m = MV_PATTERN.exec(command);
+  if (!m) return null;
+  const [, src] = m;
+  return (
+    `fapony: raw \`git mv\` of a plan into done/ skips the link rewrite — ` +
+    `run \`fapony mem plan-sweep --apply ${src}\` instead, it moves the file ` +
+    `and fixes inbound/outbound links together.`
+  );
+}
+
+/** Claude Code PreToolUse (matcher Bash): stdin JSON in, deny decision out. */
+export async function cmdHookMvGuard(): Promise<void> {
+  try {
+    const raw = JSON.parse(await Bun.stdin.text()) as {
+      tool_input?: { command?: unknown };
+    };
+    const reason = mvGuardDecision(raw.tool_input?.command);
+    if (reason) {
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+          },
+        }),
+      );
+    }
+  } catch {
+    // a parse failure must never block a command — silence, not deny
+  }
+}

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

@@ -0,0 +1,383 @@
+// src/adapters/hooks/read-hint.ts — Read hint + re-read hint + commit hint
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Attaches size/read context
+// to file reads. Also includes commitHintFor (OpenCode commit hint).
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { SCAN_EXTS } from "../../analyze.js";
+import { recordHintFire } from "../../core/hint-log.js";
+import { sessionKey } from "../../core/hook-helpers.js";
+import { readMemLog } from "../../memory.js";
+import { renderSeed } from "../../seed/review-seed.js";
+import { readContextData } from "./context-data.js";
+
+// --- Read hint (size) ---
+
+/** Below this size a full read is already cheap — stay silent. */
+export const READ_HINT_MIN_BYTES = 24_000;
+/** A caller-chosen limit below this is a bounded read — already cheap. */
+export const READ_HINT_MIN_LIMIT = 300;
+/** One-time measurement (2026-09-17, this repo): 5 files / 2,146 lines ≈ 3.7KB out. */
+const READ_HINT_MEASURED = "measured ~3.7KB output on a 2,146-line file";
+/** Cap on the outline attached to the read hint — keeps the hint compact. */
+const READ_HINT_OUTLINE_CAP = 2_000;
+
+export interface ReadHintInput {
+  filePath: unknown;
+  offset?: unknown;
+  limit?: unknown;
+  cwd: string;
+}
+
+/**
+ * Factual one-liner for a full-file read of a large source file, or null.
+ * Every unknown resolves to null — a hint must never fire on a guess.
+ */
+export function readHintFor(opts: ReadHintInput): 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 limit = typeof opts.limit === "number" ? opts.limit : null;
+    if (limit !== null && limit < READ_HINT_MIN_LIMIT) return null;
+    const st = statSync(opts.filePath);
+    if (!st.isFile() || st.size < READ_HINT_MIN_BYTES) 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 lines = readFileSync(opts.filePath, "utf-8").split("\n").length;
+    const rel = relative(opts.cwd, opts.filePath);
+    const shown = rel.startsWith("..") ? opts.filePath : rel;
+
+    let outline = "";
+    try {
+      const seed = renderSeed(["--files", shown], opts.cwd);
+      const sigMatch = seed.match(
+        /signatures \(current\):\n([\s\S]*?)(?:\n\w|\nstatic graph)/,
+      );
+      if (sigMatch) {
+        outline = sigMatch[1].trim();
+      } else {
+        const afterFiles = seed.indexOf("\nimporters");
+        if (afterFiles > 0) {
+          outline = seed
+            .slice(0, Math.min(afterFiles, READ_HINT_OUTLINE_CAP))
+            .trim();
+        } else {
+          outline = seed.slice(0, READ_HINT_OUTLINE_CAP).trim();
+        }
+      }
+      if (outline.length > READ_HINT_OUTLINE_CAP) {
+        outline = `${outline.slice(0, READ_HINT_OUTLINE_CAP).trimEnd()}\n… truncated`;
+      }
+    } catch {
+      // review-seed failed — fall back to the command suggestion
+    }
+
+    if (outline) {
+      return (
+        `fapony: ${shown} is ${lines} lines\n${outline}\n` +
+        `(review-seed --files ${shown} for importers + callers; skill /lookup-before-edit)`
+      );
+    }
+    return (
+      `fapony: ${shown} is ${lines} lines — review-seed --files ${shown} ` +
+      `returns exports with line numbers, importers, and signatures first ` +
+      `(${READ_HINT_MEASURED}; skill /lookup-before-edit has the routine)`
+    );
+  } catch {
+    return null;
+  }
+}
+
+// --- Re-read tracking (mtime heuristic) ---
+
+const READ_TRACK_DIR = "read-track";
+
+export interface ReadTrackRow {
+  ts: string;
+  path: string;
+  mtime: number;
+}
+
+/** Directory holding one read log per session. */
+function readTrackDir(): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, READ_TRACK_DIR);
+}
+
+/** Absolute path of a session's read log — may not exist. */
+export function readTrackPath(session: string): string {
+  return join(readTrackDir(), `${sessionKey(session)}.jsonl`);
+}
+
+function readTrackRows(session: string): ReadTrackRow[] {
+  const p = readTrackPath(session);
+  if (!existsSync(p)) return [];
+  const rows: ReadTrackRow[] = [];
+  for (const line of readFileSync(p, "utf-8").split("\n")) {
+    if (!line) continue;
+    try {
+      const r = JSON.parse(line) as ReadTrackRow;
+      if (typeof r.path === "string" && typeof r.mtime === "number") {
+        rows.push(r);
+      }
+    } catch {
+      // a torn line must not lose the rest of the log
+    }
+  }
+  return rows;
+}
+
+function appendReadTrackRow(session: string, row: ReadTrackRow): void {
+  const dir = readTrackDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(readTrackPath(session), `${JSON.stringify(row)}\n`, "utf-8");
+}
+
+export interface RereadHintInput {
+  filePath: unknown;
+  offset?: unknown;
+  limit?: unknown;
+  cwd: string;
+  session?: unknown;
+}
+
+/**
+ * Annotate a full-file read of a path already read this session whose mtime
+ * has not moved, or null. Records every full read.
+ */
+export function rereadHintFor(opts: RereadHintInput): string | null {
+  try {
+    if (process.env.FAPONY_NO_REREAD_HINT === "1") return null;
+    if (typeof opts.session !== "string" || opts.session === "") return null;
+    if (typeof opts.filePath !== "string" || opts.filePath === "") return null;
+    const offset = typeof opts.offset === "number" ? opts.offset : null;
+    if (offset !== null && offset !== 0) return null;
+    const limit = typeof opts.limit === "number" ? opts.limit : null;
+    if (limit !== null && limit < READ_HINT_MIN_LIMIT) return null;
+
+    const abs = (() => {
+      const p = opts.filePath.startsWith("/")
+        ? opts.filePath
+        : join(opts.cwd, opts.filePath);
+      try {
+        return realpathSync(p);
+      } catch {
+        return resolve(p);
+      }
+    })();
+    const st = statSync(abs);
+    if (!st.isFile()) return null;
+    const mtime = Math.round(st.mtimeMs);
+
+    const prior = readTrackRows(opts.session).filter((r) => r.path === abs);
+    const last = prior.at(-1);
+    appendReadTrackRow(opts.session, {
+      ts: new Date().toISOString(),
+      path: abs,
+      mtime,
+    });
+    if (!last || last.mtime !== mtime) return null;
+
+    const rel = relative(opts.cwd, opts.filePath);
+    const shown = rel.startsWith("..") ? opts.filePath : rel;
+    return (
+      `fapony: already read ${shown} ${prior.length}\u00d7 this session — ` +
+      `content unchanged since the last read (mtime), grep the line range ` +
+      `you need instead of re-reading it`
+    );
+  } catch {
+    return null;
+  }
+}
+
+// --- Commit hint (OpenCode tool.execute.after) ---
+
+/** Below this number of commits, the hint is unnecessary noise. */
+export const COMMIT_HINT_MIN_COMMITS = 1;
+
+export interface CommitHintInput {
+  command: unknown;
+  cwd: string;
+}
+
+function git(args: string[], cwd: string): string | null {
+  try {
+    const p = Bun.spawnSync(["git", ...args], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    return p.exitCode === 0 ? p.stdout.toString().trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+import { hookTsMs, utcStamp } from "../../core/hook-helpers.js";
+
+/**
+ * Nudge for bash commands containing `git commit` that produced commits with
+ * no mem row recorded for them.
+ */
+export function commitHintFor(opts: CommitHintInput): string | null {
+  try {
+    if (typeof opts.command !== "string" || opts.command === "") return null;
+    if (!/\bgit\s+commit\b/.test(opts.command)) return null;
+
+    const worktree = git(["rev-parse", "--show-toplevel"], opts.cwd);
+    if (!worktree) return null;
+
+    let memLastTs: string | null = null;
+    try {
+      memLastTs = readMemLog(worktree).rows[0]?.ts ?? null;
+    } catch {
+      memLastTs = null;
+    }
+    if (!memLastTs) return null;
+    const since = utcStamp(new Date(hookTsMs(memLastTs) + 1000));
+
+    const log = git(
+      ["log", "--since", `${since} +0000`, "--format=%h %s"],
+      worktree,
+    );
+    const commitList = log ? log.split("\n").filter(Boolean) : [];
+    if (commitList.length < COMMIT_HINT_MIN_COMMITS) return null;
+
+    const lines: string[] = [
+      `${commitList.length} commit(s) since last mem row (${memLastTs.slice(0, 10)}) — record a mem row for this work.`,
+    ];
+    for (const c of commitList.slice(0, 5)) lines.push(`  ${c}`);
+    if (commitList.length > 5) lines.push(`  … +${commitList.length - 5} more`);
+    lines.push(
+      `fapony mem add <decision|bug|note> "what happened" --files <files> ${worktree}/.fapony/plan/PLAN.md`,
+    );
+
+    const prefixed = lines.map((l) => `fapony: ${l}`).join("\n");
+    return prefixed;
+  } catch {
+    return null;
+  }
+}
+
+// --- Read hint CLI command ---
+
+/** Claude Code PreToolUse (matcher Read): stdin JSON in, additionalContext out. */
+export async function cmdHookReadHint(): 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;
+        offset?: unknown;
+        limit?: 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 = readHintFor({
+      filePath,
+      offset: raw.tool_input?.offset,
+      limit: raw.tool_input?.limit,
+      cwd,
+    });
+    if (hint) parts.push(hint);
+    const reread = rereadHintFor({
+      filePath,
+      offset: raw.tool_input?.offset,
+      limit: raw.tool_input?.limit,
+      cwd,
+      session,
+    });
+    if (reread) parts.push(reread);
+    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 ---
+    const rel =
+      typeof filePath === "string"
+        ? (() => {
+            try {
+              const git = Bun.spawnSync(
+                ["git", "rev-parse", "--show-toplevel"],
+                { cwd, stdout: "pipe", stderr: "pipe" },
+              );
+              if (git.exitCode !== 0) return null;
+              const wt = realpathSync(git.stdout.toString().trim());
+              const abs = realpathSync(
+                filePath.startsWith("/") ? filePath : join(wt, filePath),
+              );
+              const r = relative(wt, abs).split("\\").join("/");
+              return r.startsWith("..") ? null : r;
+            } catch {
+              return null;
+            }
+          })()
+        : null;
+    const worktree = ctx?.worktree ?? null;
+    if (worktree) {
+      if (hint) {
+        recordHintFire({
+          ts: new Date().toISOString(),
+          worktree,
+          surface: "read",
+          file: rel,
+          count: 1,
+        });
+      }
+      if (ctx && ctx.debtIds.length > 0) {
+        recordHintFire({
+          ts: new Date().toISOString(),
+          worktree,
+          surface: "debt",
+          file: rel,
+          count: ctx.debtIds.length,
+          ids: ctx.debtIds,
+        });
+      }
+      if (ctx && ctx.memLines.length > 0) {
+        recordHintFire({
+          ts: new Date().toISOString(),
+          worktree,
+          surface: "mem",
+          file: rel,
+          count: ctx.memLines.length,
+        });
+      }
+    }
+  } catch {
+    // any failure = no hint; a hook must never block a read over a hint
+  }
+}