fapony 0.3.3 → 0.3.5

package/src/hook.ts

@@ -1,1424 +1,70 @@
-// src/hook.ts — Claude Code / Cursor Stop hook: refuse to end a turn that produced
-// commits but no mem row.
-//
-// Why a hook and not a message: SERVER_INSTRUCTIONS is a *request* that the
-// agent remember, and it measured as not enough · the hook does not grade in
-// the agent's place (it cannot — it does not see whether the work passed or
-// broke) it merely won't let the turn end until the agent grades itself,
-// separating "who judges" from "who forces judgment"
-//
-// The signal is a commit, not a dirty tree — dirty = still working, commit =
-// the unit of work is done, matching the definition "1 run = 1 measurable
-// unit of work" (rule 7)
-//
-// Two payloads, one decision — field-mapping only:
-//   claude  {cwd, transcript_path, stop_hook_active} → {"decision":"block"}
-//   cursor  {workspace_roots, conversation_id, loop_count, status} → {"followup_message"}
-//   (cursor: loop_count ≥ 1 = the hook already fired, status ≠ completed = allow)
-
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  realpathSync,
-  statSync,
-} from "node:fs";
-import { homedir } from "node:os";
-import { basename, join, relative, resolve, sep } from "node:path";
-import { buildGraphCached, collectSourceFiles, SCAN_EXTS } from "./analyze.js";
-import { debtForFile, loadConventions } from "./debt/index.js";
-import { readMemLog, whereMemDir } from "./memory.js";
-import { renderSeed } from "./seed/review-seed.js";
-
-// --- Hint-fire log (PLAN-feedback-surface chunk 1) ---
-//
-// Append-only JSONL under state dir (<faponyDir>/hint-log/<key>.jsonl),
-// one file per worktree. Best-effort: every error swallowed — a hook that
-// cannot log must still annotate. Called at caller only (cmdHookReadHint +
-// opencode plugins), never inside readHintFor/readContextLines/commitHintFor
-// (test pollution: those functions are called ~20x in test/hook.test.ts
-// without setting FAPONY_STATE_DIR).
-
-const HINT_LOG_DIR = "hint-log";
-
-/** Stable filename key from an absolute worktree path. */
-export function worktreeKey(worktree: string): string {
-  return worktree.replace(/^\/+/, "").replace(/\//g, "--");
-}
-
-/** Directory holding one hint-fire log file per worktree. */
-function hintLogDir(): string {
-  const base =
-    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
-  return join(base, HINT_LOG_DIR);
-}
-
-/** Absolute path of a worktree's hint-fire log — may not exist. */
-export function hintLogPath(worktree: string): string {
-  return join(hintLogDir(), `${worktreeKey(worktree)}.jsonl`);
-}
-
-export interface HintFireRow {
-  ts: string;
-  worktree: string;
-  surface: "read" | "debt" | "mem" | "commit" | "edit";
-  file: string | null;
-  count: number;
-  ids?: string[];
-}
-
-/**
- * Append a hint-fire log row. Best-effort: never throws, never blocks.
- * Uses $FAPONY_STATE_DIR when set (tests, CI), otherwise ~/.config/fapony.
- */
-export function recordHintFire(row: HintFireRow): void {
-  try {
-    const dir = hintLogDir();
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    appendFileSync(
-      hintLogPath(row.worktree),
-      `${JSON.stringify(row)}\n`,
-      "utf-8",
-    );
-  } catch {
-    // best-effort — swallow
-  }
-}
-
-// --- Debt precision (PLAN-feedback-surface chunk 2) ---
-//
-// Reads the hint-fire log, re-runs debtForFile at HEAD for each file that
-// received debt hints, and counts which ids are no longer flagged. This is
-// deterministic (no proxy, no join with events) and answers: of the debt
-// lines fapony showed, how many is the repo now clean of?
-
-export interface HintImpact {
-  fired: number;
-  by_surface: {
-    read: number;
-    debt: number;
-    mem: number;
-    commit: number;
-    edit: number;
-  };
-  debt: { shown: number; resolved: number; unknown: number };
-  window: string | null;
-}
-
-/**
- * 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 (the
- * `<key>.jsonl` naming makes this a filename comparison) — omit to merge
- * every worktree. Returns zeroed counts (not null) when there are no rows —
- * the caller decides how to present "no data" vs "zero".
- */
-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;
-
-  // Read the worktree's .jsonl when scoped, else every file in the dir.
-  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;
-  }
-
-  // debtShown: Map<"worktree\tfile\tid", true> — unique debt ids per file.
-  const debtShown = new Map<string, true>();
-  // debtByFile: Map<"worktree\tfile", string[]> — all ids shown per file.
-  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);
-      }
-    }
-  }
-
-  // Re-run debtForFile at HEAD for each file that had debt hints.
-  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()) {
-        // File deleted — all its debt ids are unknown.
-        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;
-}
-
-export interface RawStopPayload {
-  // Claude Code
-  cwd?: string;
-  transcript_path?: string | null;
-  stop_hook_active?: boolean;
-  // Cursor — common schema (https://cursor.com/docs/agent/hooks)
-  workspace_roots?: string[];
-  conversation_id?: string;
-  loop_count?: number;
-  status?: string;
-  // Codex — hooks contract (https://learn.chatgpt.com/docs/hooks)
-  session_id?: string;
-  model?: string;
-  permission_mode?: string;
-}
-
-export type StopClient = "claude" | "cursor" | "codex";
-
-export interface NormalizedStopInput {
-  client: StopClient;
-  cwd: string;
-  transcriptPath: string | null;
-  stopHookActive: boolean;
-}
-
-/** UTC 'YYYY-MM-DD HH:MM:SS' — the format events.ts is written in. */
-export function utcStamp(d: Date): string {
-  return d.toISOString().slice(0, 19).replace("T", " ");
-}
-
-/**
- * Parse either timestamp shape this repo produces: mem rows are ISO
- * (`new Date().toISOString()`), session start is utcStamp
- * ('YYYY-MM-DD HH:MM:SS', UTC). Never compare them as strings — 'T' > ' '
- * makes any same-date mem row read as "newer than session start".
- */
-export function hookTsMs(ts: string): number {
-  const iso = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(ts)
-    ? `${ts.replace(" ", "T")}Z`
-    : ts;
-  return new Date(iso).getTime();
-}
-
-/**
- * Pure decision: block when this session produced commits but no mem row
- * newer than session start exists. Every unknown (no git, no transcript,
- * hook already fired, no mem log) resolves to "allow" — a hook that guesses
- * wrong must never trap the agent.
- *
- * PLAN-verdict-to-mem: block condition changed from verdicts to mem rows.
- * The stop hook is the most expensive enforcement tool we have (rule 9);
- * using it for verdicts that are 94% pass-family was wasteful. Now it
- * enforces mem_add — rows that session N can actually read.
- */
-export function decideStop(opts: {
-  stopHookActive: boolean;
-  worktree: string | null;
-  commits: number;
-  since?: string | null;
-  commitList?: string[];
-  memLastTs?: string | null;
-  /** Logs that exist in the repo but are out of scope from this worktree. */
-  memCandidates?: string[];
-}): string | null {
-  if (opts.stopHookActive) return null; // already blocked once — let it end
-  if (!opts.worktree) return null;
-  if (opts.commits < 1) return null;
-  // No mem log at all = allow (same as sessionStartContext — silent when missing).
-  if (!opts.memLastTs && !opts.memCandidates?.length) return null;
-  // Has mem rows — block only if nothing newer than session start. Parsed
-  // as dates, not strings: the two sides arrive in different shapes (ISO mem
-  // rows vs utcStamp session start). Unparseable = allow, per the contract
-  // above — an unknown timestamp is not proof either way.
-  if (opts.since && opts.memLastTs) {
-    const sinceMs = hookTsMs(opts.since);
-    const memMs = hookTsMs(opts.memLastTs);
-    if (Number.isNaN(sinceMs) || Number.isNaN(memMs)) return null;
-    if (memMs >= sinceMs) return null;
-  }
-
-  const lines: string[] = [
-    `${opts.commits} commit(s) landed in ${opts.worktree} this session — no mem row recorded for this work.`,
-  ];
-  // ≤ 5 commits listed, rest folded into "… +N more" (spec §6: ≤ 12 lines).
-  const list = opts.commitList ?? [];
-  for (const c of list.slice(0, 5)) lines.push(`  ${c}`);
-  if (list.length > 5) lines.push(`  … +${list.length - 5} more`);
-  if (opts.memLastTs) {
-    lines.push(
-      `mem: last row ${opts.memLastTs.slice(0, 10)} — nothing newer this session`,
-    );
-  } else if (opts.memCandidates?.length) {
-    lines.push(
-      `mem: no log in scope from ${opts.worktree} — found ` +
-        `${opts.memCandidates.join(", ")} (run mem commands from there, or --mem-dir)`,
-    );
-  }
-
-  lines.push(
-    `Record a mem row before ending: fapony mem add <decision|bug|note> "what happened" --files <files> ` +
-      `${opts.worktree}/.fapony/plan/PLAN.md (or the relevant plan). ` +
-      `files[] is required — a row without it is unfindable when you touch that file next session.`,
-  );
-  return lines.join("\n");
-}
-
-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;
-  }
-}
-
-/**
- * Cursor transcript location derived from the conversation id —
- * ~/.cursor/projects/<slug>/agent-transcripts/<id>/<id>.jsonl where slug is
- * the workspace path minus its leading "/", "/" → "-" (Claude Code's slug
- * convention). Fallback only: a real transcript_path in the payload wins.
- */
-export function cursorTranscriptPath(
-  home: string,
-  cwd: string,
-  conversationId: string,
-): string {
-  const slug = cwd.replace(/^\//, "").replace(/\//g, "-");
-  return join(
-    home,
-    ".cursor",
-    "projects",
-    slug,
-    "agent-transcripts",
-    conversationId,
-    `${conversationId}.jsonl`,
-  );
-}
-
-export function isCursorPayload(raw: RawStopPayload): boolean {
-  return (
-    Array.isArray(raw.workspace_roots) ||
-    typeof raw.conversation_id === "string"
-  );
-}
-
-/** Codex sends permission_mode and/or model — fields neither Claude nor Cursor include in Stop. */
-export function isCodexPayload(raw: RawStopPayload): boolean {
-  return (
-    typeof raw.permission_mode === "string" ||
-    (typeof raw.model === "string" && !isCursorPayload(raw))
-  );
-}
-
-/** Field-mapping only — all three clients feed the same decideStop below. */
-export function normalizeStopInput(
-  raw: RawStopPayload,
-  home: string,
-): NormalizedStopInput {
-  if (isCodexPayload(raw)) {
-    // Codex: cwd is the session working directory; stop_hook_active means
-    // the hook already fired once (same semantics as Claude).
-    return {
-      client: "codex",
-      cwd: raw.cwd ?? process.cwd(),
-      transcriptPath:
-        typeof raw.transcript_path === "string" && raw.transcript_path
-          ? raw.transcript_path
-          : null,
-      stopHookActive: raw.stop_hook_active === true,
-    };
-  }
-  if (isCursorPayload(raw)) {
-    const cwd = raw.workspace_roots?.[0] ?? raw.cwd ?? process.cwd();
-    let transcriptPath =
-      typeof raw.transcript_path === "string" && raw.transcript_path
-        ? raw.transcript_path
-        : null;
-    if (!transcriptPath && raw.conversation_id) {
-      transcriptPath = cursorTranscriptPath(home, cwd, raw.conversation_id);
-    }
-    return {
-      client: "cursor",
-      cwd,
-      transcriptPath,
-      // loop_count counts follow-ups this hook already triggered — ≥ 1 means
-      // we already blocked once (Cursor's stop_hook_active).
-      stopHookActive: (raw.loop_count ?? 0) > 0,
-    };
-  }
-  return {
-    client: "claude",
-    cwd: raw.cwd ?? process.cwd(),
-    transcriptPath: raw.transcript_path ?? null,
-    stopHookActive: raw.stop_hook_active === true,
-  };
-}
-
-/** Claude blocks with decision:block; Cursor auto-submits as followup_message;
- *  Codex continues with decision:block + reason (continue:false would take
- *  precedence and end the turn instead — Codex Hooks, Stop section). */
-export function stopOutput(client: StopClient, reason: string): string {
-  if (client === "cursor") return JSON.stringify({ followup_message: reason });
-  if (client === "codex") return JSON.stringify({ decision: "block", reason });
-  return JSON.stringify({ decision: "block", reason });
-}
-
-// --- Block dedupe (one block per session + worktree) ---
-//
-// stop_hook_active only suppresses the block that fires *immediately* after
-// one. Every later turn that still carries ungraded commits blocks again, so
-// a session that keeps committing gets the same paragraph 4-5 times. The
-// first block already delivered it; the repeats add noise, not force (rule 9
-// — the forcing happens once, and the agent that ignored it once is not
-// persuaded by the fifth copy).
-//
-// Keyed by the transcript path, which is already the session identity the
-// commit window is measured from — no session field to thread through.
-
-const STOP_BLOCK_DIR = "stop-block";
-
-interface StopBlockRow {
-  ts: string;
-  worktree: string;
-}
-
-/** Absolute path of a session's block log — may not exist. */
-export function stopBlockPath(session: string): string {
-  const base =
-    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
-  return join(base, STOP_BLOCK_DIR, `${sessionKey(session)}.jsonl`);
-}
-
-/**
- * True when this session already blocked for this worktree — the caller then
- * lets the turn end. Records the block when it has not. Every unknown (no
- * session identity, unwritable state dir) resolves to false: a dedupe that
- * guesses must fail towards blocking, never towards silence.
- */
-export function stopBlockedBefore(
-  session: string | null,
-  worktree: string,
-): boolean {
-  if (!session) return false;
-  const path = stopBlockPath(session);
-  try {
-    if (existsSync(path)) {
-      for (const line of readFileSync(path, "utf-8").split("\n")) {
-        if (!line) continue;
-        try {
-          if ((JSON.parse(line) as StopBlockRow).worktree === worktree) {
-            return true;
-          }
-        } catch {
-          // a torn line must not lose the rest of the log
-        }
-      }
-    }
-    const dir = join(path, "..");
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const row: StopBlockRow = { ts: new Date().toISOString(), worktree };
-    appendFileSync(path, `${JSON.stringify(row)}\n`, "utf-8");
-  } catch {
-    return false;
-  }
-  return false;
-}
-
-/** Reads the Stop-hook JSON on stdin, prints a block decision or nothing. */
-export async function cmdHookStop(): Promise<void> {
-  let reason: string | null = null;
-  let client: StopClient = "claude";
-  try {
-    const raw = JSON.parse(await Bun.stdin.text()) as RawStopPayload;
-    const norm = normalizeStopInput(raw, homedir());
-    client = norm.client;
-    // Cursor aborted/errored turns pass: the user said stop, or the loop
-    // died — commits from those turns are still caught at the next completed
-    // stop (the window is the conversation transcript's birthtime).
-    if (client === "cursor" && raw.status !== "completed") return;
-    // Codex: no status guard needed — Stop fires at turn end unconditionally.
-
-    const worktree = git(["rev-parse", "--show-toplevel"], norm.cwd);
-
-    // Session start = when the transcript file was created. No transcript,
-    // no window to measure — allow.
-    let since: string | null = null;
-    if (norm.transcriptPath) {
-      try {
-        since = utcStamp(statSync(norm.transcriptPath).birthtime);
-      } catch {
-        since = null;
-      }
-    }
-
-    let commits = 0;
-    let commitList: string[] = [];
-    let memLastTs: string | null = null;
-    let memCandidates: string[] = [];
-    if (worktree && since) {
-      const log = git(
-        ["log", "--since", `${since} +0000`, "--format=%h %s"],
-        norm.cwd,
-      );
-      commitList = log ? log.split("\n").filter(Boolean) : [];
-      commits = commitList.length;
-      // Read mem log regardless of commits — the block condition is mem rows,
-      // not verdicts (PLAN-verdict-to-mem).
-      try {
-        const mem = readMemLog(worktree);
-        memLastTs = mem.rows[0]?.ts ?? null;
-        if (!memLastTs) memCandidates = whereMemDir(worktree).candidates ?? [];
-      } catch {
-        memLastTs = null;
-      }
-    }
-
-    reason = decideStop({
-      stopHookActive: norm.stopHookActive,
-      worktree: since ? worktree : null,
-      commits,
-      since,
-      commitList,
-      memLastTs,
-      memCandidates,
-    });
-    // Already blocked for this worktree in this session — say it once.
-    if (
-      reason &&
-      worktree &&
-      stopBlockedBefore(norm.transcriptPath, worktree)
-    ) {
-      reason = null;
-    }
-  } catch {
-    reason = null; // any failure = allow the turn to end
-  }
-
-  if (reason) console.log(stopOutput(client, reason));
-}
-
-// --- Session start (kickoff as context, not as a thing to remember) ---
-//
-// `fapony mem kickoff` is the one command that pays for itself at session
-// open — what is open, what is stale, what the last rows touched. Asking the
-// agent to run it measured as not enough (rule 9), and an MCP tool would pay
-// schema rent in every session of every client to save one bash round
-// (rule 13). A SessionStart hook is neither: zero rent, and it fires whether
-// or not anyone remembers.
-//
-// sessionStartContext is the one copy of that: guard (no mem log = null), the
-// kickoff spawn, and the cap. cmdHookSessionStart wraps it in the Claude/Codex
-// JSON, and the generated OpenCode plugin imports it directly — so the logic
-// lives here and `git pull` updates all three clients, instead of being baked
-// into the plugin file where a pull could not reach it (mub2ezhi).
-//
-// Runs the CLI in a subprocess rather than calling cmdKickoff: kickoff prints
-// to stdout and exits on bad input, both of which would be this hook's stdout.
-
-/** Cap on injected context — kickoff is short, a broken repo's output is not. */
-export const SESSION_START_MAX_CHARS = 4_000;
-
-const TRUNCATED = "… truncated — run `fapony mem find <word>` for the rest";
-
-/** Trim to whole lines, keeping the marker's line boundary intact. */
-function headLines(text: string, max: number): string {
-  const cut = text.slice(0, max);
-  const lastNl = cut.lastIndexOf("\n");
-  return (lastNl > 0 ? cut.slice(0, lastNl) : cut).trimEnd();
-}
-
-/**
- * Trim to whole lines within the cap, with an honest truncation marker.
- *
- * Kickoff's ordering is now: ranked rows → "## next up" → "## recent". The
- * most actionable content is at the top (bugs, diff-matched) and in "## next
- * up". A plain head-cut drops the suggestions — so we try to keep "## next up"
- * visible. When "## recent" exists, we cut it first; otherwise fall back to
- * keeping "## next up" at the tail.
- */
-export function capContext(
-  text: string,
-  max = SESSION_START_MAX_CHARS,
-): string {
-  if (text.length <= max) return text;
-  // New ordering: ranked → ## next up → ## recent → sweep/rotate
-  // Cut ## recent first to keep ranked content + suggestions visible.
-  const recentIdx = text.indexOf("\n## recent");
-  if (recentIdx > 0) {
-    const head = text.slice(0, recentIdx).trimEnd();
-    if (head.length <= max) return head;
-    // Head still too long — try to keep ## next up at the end
-    const nextIdx = head.lastIndexOf("\n## next up");
-    if (nextIdx > 0) {
-      const beforeNext = head.slice(0, nextIdx).trimEnd();
-      const nextTail = head.slice(nextIdx).trimEnd();
-      if (nextTail.length < max / 2) {
-        return `${headLines(beforeNext, max - nextTail.length)}\n${TRUNCATED}\n${nextTail}`;
-      }
-    }
-    return `${headLines(head, max)}\n${TRUNCATED}`;
-  }
-  // Fallback: no ## recent found (short output or other path)
-  const at = text.lastIndexOf("\n## next up");
-  const tail = at > 0 ? text.slice(at).trimEnd() : "";
-  if (tail && tail.length < max / 2) {
-    return `${headLines(text, max - tail.length)}\n${TRUNCATED}\n${tail}`;
-  }
-  return `${headLines(text, max)}\n${TRUNCATED}`;
-}
-
-/**
- * Kickoff output for `cwd`'s mem log, capped — or null when there is no log in
- * scope, the command fails, or it prints nothing. The single implementation
- * behind both cmdHookSessionStart (Claude/Codex) and the generated OpenCode
- * plugin, so a pull of INSTALL_ROOT updates all three.
- *
- * `faponyTs` is where the CLI lives. The hook defaults to `Bun.main` (itself,
- * when run as `bun <root>/fapony.ts hook-session-start`); the OpenCode plugin
- * must pass its baked path because `Bun.main` inside OpenCode is OpenCode's own
- * entry, not fapony's.
- */
-export function sessionStartContext(
-  cwd: string,
-  faponyTs: string = Bun.main,
-): string | null {
-  // No mem log in scope = nothing to say. Silence beats "no rows yet".
-  if (!whereMemDir(cwd).dir) return null;
-  const p = Bun.spawnSync([process.execPath, faponyTs, "mem", "kickoff"], {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const out = p.stdout.toString().trim();
-  if (p.exitCode !== 0 || !out) return null;
-  return capContext(out);
-}
-
-/** SessionStart hook: emit sessionStartContext as Claude/Codex JSON. */
-export async function cmdHookSessionStart(): Promise<void> {
-  try {
-    const raw = JSON.parse(await Bun.stdin.text()) as { cwd?: string };
-    const cwd = raw.cwd ?? process.cwd();
-    const ctx = sessionStartContext(cwd);
-    if (!ctx) return;
-    console.log(
-      JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "SessionStart",
-          additionalContext: ctx,
-        },
-      }),
-    );
-  } catch {
-    // any failure = no context, never a broken session start
-  }
-}
-
-// --- Read hint (PreToolUse annotate — never block, never dedupe) ---
-//
-// Reading a large file in full is where an agent spends tokens without
-// noticing — warnings in a skill were never enough (same principle as the
-// Stop hook: speak while it is spending). But this hook **annotates only**:
-// no permissionDecision, no "already read" dedupe — context compaction makes
-// "already read" false, and a hook that guesses wrong and traps the agent is
-// worse than no hook (the rule from the original hook.ts) — annotate cannot
-// trap by construction, the worst cost of a miss is one unnecessary line
-//
-// The text is facts only (line count + command + a one-time measurement), not
-// a per-file estimate — guessing tokens is dressing up as data, against
-// "facts only"
-
-/** 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 (no path, non-source ext, small file, bounded read, no git
- * repo, stat/read failure) resolves to null — a hint must never fire on a
- * guess. Fast path is statSync only; the file is read just to count lines,
- * and only after the size threshold passed.
- *
- * When review-seed succeeds, the hint attaches the actual outline (exports
- * with line numbers) instead of telling the agent to run a command (rules
- * 9/13: ask does not work, attach the data directly).
- */
-export function readHintFor(opts: ReadHintInput): string | null {
-  try {
-    if (typeof opts.filePath !== "string" || opts.filePath === "") return null;
-    const dot = opts.filePath.lastIndexOf(".");
-    // SCAN_EXTS keys carry the dot (".ts") — slice from the dot itself.
-    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;
-    // review-seed is a git command — outside a repo the hint would lie.
-    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;
-    // The hint feeds a command line — inside the worktree show the clean
-    // relative path, outside it relative() climbs dots, show absolute.
-    const rel = relative(opts.cwd, opts.filePath);
-    const shown = rel.startsWith("..") ? opts.filePath : rel;
-
-    // Try to attach the actual outline from review-seed (cap ~2KB)
-    let outline = "";
-    try {
-      const seed = renderSeed(["--files", shown], opts.cwd);
-      // Extract signatures section — the most useful part for reading
-      const sigMatch = seed.match(
-        /signatures \(current\):\n([\s\S]*?)(?:\n\w|\nstatic graph)/,
-      );
-      if (sigMatch) {
-        outline = sigMatch[1].trim();
-      } else {
-        // Fallback: take the first section after the file list
-        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 — annotate only) ---
-//
-// The size hint above fires on almost nothing real: measured 2026-09-20 over
-// 28,151 read parts across every project, only 2.3% had fileSize>=24KB with a
-// full bound, while 55.5% of read context came from files under 24KB and 19.5%
-// from re-reading a path already read this session (39.2% of context sits in
-// (session,path) pairs read >=2x). The cost is repetition, not one big file —
-// so the gate here is not size, it is "same file, unchanged, again".
-//
-// mtime is the whole mechanism: unchanged mtime since the previous read in
-// this session = the same bytes = annotate; mtime moved = someone edited it =
-// new content = silent. No Edit/Grep tracking — mtime already answers "did it
-// change", so no tool-sequence tagging is needed.
-//
-// Log lives beside hint-log but is separate — hint-log counts fires, this
-// records reads keyed by session (one file per session, so a hint never leaks
-// into the next session / rule 11). Same contract as the size hint: annotate
-// only, never block, every unknown → silent, best-effort. Called at the caller
-// only, never inside a pure function (test pollution — same reason
-// recordHintFire is caller-side).
-
-const READ_TRACK_DIR = "read-track";
-
-export interface ReadTrackRow {
-  ts: string;
-  path: string;
-  mtime: number;
-}
-
-/** Filename key for a session — basename of a transcript path or a raw id. */
-export function sessionKey(session: string): string {
-  const base = basename(session).replace(/\.[^.]+$/, "");
-  return base.replace(/[^A-Za-z0-9_-]/g, "-") || "unknown";
-}
-
-/** 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 identity — transcript path (Claude) or session id (OpenCode). */
-  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, so the returned count is
- * the number of prior reads. Every unknown (kill switch on, no session, no
- * path, bounded read, partial offset, missing file, read/write failure)
- * resolves to null — a hint must never fire on a guess.
- */
-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;
-    // A bounded/partial read is already cheap — same line the size hint draws.
-    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;
-
-    // The hint feeds the agent's context — show the path *it* passed, relative
-    // to its own cwd, so a symlinked cwd (macOS /var → /private/var) does not
-    // turn a clean relative path into a resolved absolute one.
-    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;
-  }
-}
-
-// --- Edit hint (PreToolUse annotate — importer count + once-per-session dedupe) ---
-//
-// Editing a file that has importers can silently break its consumers (measured:
-// 17.9% of changed nodes over 30 commits had a 1-hop blast radius; ~12-16% of
-// all-time fail rows were producer/consumer mismatches). The hint is a fact —
-// the importer count plus the review-seed command that lists them — never a
-// judgment about whether the edit is safe, and never a block.
-//
-// Dedupe is per (session, file): the first edit to a file fires, repeats stay
-// silent. The track log reuses the read-track session mechanism (sessionKey,
-// one jsonl per session) but lives in its own dir — sharing read-track's file
-// would make an Edit look like a Read and falsely trip the re-read hint. Like
-// rereadHintFor the track write happens inside this function (the caller-side
-// rule covers recordHintFire, not dedupe state); unlike it there is no mtime
-// comparison — an edit that moves mtime is still the same file in the same
-// session, and repeating the count buys nothing.
-
-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 identity — transcript path (Claude) or session id. Without it the
-   * hint still fires (the importer fact holds) but cannot dedupe.
-   */
-  session?: unknown;
-}
-
-/**
- * Factual one-liner for editing a source file that has importers, or null.
- * Every unknown (no path, non-source ext, new/unsaved file, outside the
- * worktree, no git repo, graph failure) resolves to null — a hint must never
- * fire on a guess. Files with importers are checked before the dedupe log is
- * touched, so a file nobody imports never writes a track row.
- */
-export function editHintFor(opts: EditHintInput): string | null {
-  try {
-    if (typeof opts.filePath !== "string" || opts.filePath === "") return null;
-    const dot = opts.filePath.lastIndexOf(".");
-    // SCAN_EXTS keys carry the dot (".ts") — slice from the dot itself.
-    if (dot < 0 || !SCAN_EXTS.has(opts.filePath.slice(dot))) return null;
-    // review-seed is a git command — outside a repo the hint would lie.
-    const git = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
-      cwd: opts.cwd,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    if (git.exitCode !== 0) return null;
-    // macOS /var → /private/var: normalize both sides before comparing.
-    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; // new file — nothing imports it yet
-      }
-    })();
-    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;
-  }
-}
-
-// --- Commit hint (tool.execute.after — annotate only, never block) ---
-//
-// OpenCode has no Stop hook (Cursor does — see cursor.ts hook-stop wiring)
-// so it cannot block a turn; instead it appends an annotate to the bash tool
-// output whenever there is a git commit with no mem row recorded for it. It is
-// the same kind of nudge as the read hint: no block, no dedupe, every unknown →
-// silent · called from the opencode plugin by direct import (like
-// readHintFor), no CLI subcommand because no client needs it as a subprocess
-// (Cursor uses its own hook-stop instead)
-//
-// The text is facts only (commit list + mem status), not an estimate
-
-/** Below this number of commits, the hint is unnecessary noise. */
-export const COMMIT_HINT_MIN_COMMITS = 1;
-
-export interface CommitHintInput {
-  command: unknown;
-  cwd: string;
-}
-
-/**
- * Nudge for bash commands containing `git commit` that produced commits with
- * no mem row recorded for them. Returns a one-to-two line hint string, or
- * null when there is nothing to nudge about (no new commits, not a git
- * commit command, not a git repo, no mem log to window on, any failure).
- *
- * Every unknown resolves to null — a hint must never fire on a guess. The
- * work is cheap: one git rev-parse + one mem-log read + one git log.
- * The window is the mem log, never the verdict ledger: gate events have no
- * writer left (PLAN-verdict-to-mem), so the last verdict is frozen — fresh
- * machines listed their entire repo history as unrecorded.
- */
-export function commitHintFor(opts: CommitHintInput): string | null {
-  try {
-    if (typeof opts.command !== "string" || opts.command === "") return null;
-    // Only fire on git commit commands — not `git push`, `git pull`, etc.
-    if (!/\bgit\s+commit\b/.test(opts.command)) return null;
-
-    const worktree = git(["rev-parse", "--show-toplevel"], opts.cwd);
-    if (!worktree) return null;
-
-    // Window = commits newer than the last mem row. No mem log in scope =
-    // no window to measure — stay silent (same as the stop hook: a hint must
-    // never fire on a guess, and the whole-history fire on fresh machines is
-    // what this replaced).
-    let memLastTs: string | null = null;
-    try {
-      memLastTs = readMemLog(worktree).rows[0]?.ts ?? null;
-    } catch {
-      memLastTs = null;
-    }
-    if (!memLastTs) return null;
-    // git's --since is inclusive to the second, and a commit can land in the
-    // same UTC second as the row recorded for it — bump by 1s so recorded
-    // work isn't re-flagged.
-    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;
-
-    // Build the nudge directly — commitHintFor is annotate-only (informational),
-    // while decideStop is blocking enforcement. They serve different purposes.
-    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; // any failure = no hint
-  }
-}
-
-/** Claude Code PreToolUse (matcher Read): stdin JSON in, additionalContext out.
- *  No permissionDecision ever — the tool call always proceeds. */
-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;
-    // One read log per session — transcript_path is the Claude session file,
-    // session_id the fallback when a client omits it.
-    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 (PLAN-feedback-surface chunk 1) ---
-    // After output — best-effort, never block the hint.
-    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
-  }
-}
-
-/** Claude Code PreToolUse (matcher Edit): stdin JSON in, additionalContext out.
- *  No permissionDecision ever — the edit always proceeds. Fires once per
- *  (session, file); the dedupe lives inside editHintFor.
- *
- *  Also attaches mem/debt context lines (same as read hint) — the moment
- *  paying down debt is worth tokens is when the file is already open. */
-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;
-    // One edit log per session — same identity as the read hint.
-    const session = raw.transcript_path ?? raw.session_id;
-    const parts: string[] = [];
-    const hint = editHintFor({ filePath, cwd, session });
-    if (hint) parts.push(hint);
-    // Attach mem/debt context (same as read hint — annotate only, cap 5 lines)
-    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 (PLAN-edit-importer-hint chunk 3) ---
-    // After output — best-effort, never block the hint.
-    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
-  }
-}
-
-// --- Debt + mem context (PLAN-convention-debt chunk 4) ---
-//
-// The one moment paying down debt is worth tokens is when the file is already
-// open — so hook-read-hint appends two things after the size hint: conventions
-// the file still violates (debt detector, computed live) and mem rows that
-// mention the file (across sessions) · **annotate only**, as before — no
-// block, no dedupe, every unknown → silent · combined cap 5 lines (debt 3 · mem 2)
-
-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;
-    // macOS /var → /private/var: git reports the resolved root while callers
-    // pass unresolved tmp paths — normalize both sides before comparing.
-    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);
-      }
-      // A bare-basename hit is only usable when that name is unique in the
-      // repo (24% of files share a basename — guessing would attach a row
-      // about a DIFFERENT index.ts). The walk is paid only when a hit exists.
-      let usableBase = baseOnly;
-      if (baseOnly.length > 0) {
-        const sameName = collectSourceFiles(worktree).filter(
-          (f) => basename(f) === base,
-        ).length;
-        if (sameName !== 1) usableBase = [];
-      }
-      // direct hits (files[] / full path) outrank bare-basename hits
-      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,
-  );
-}
+// src/hook.ts — re-export shim (PLAN-lib-layer chunk 3)
+//
+// All hook logic now lives in src/adapters/hooks/. This file re-exports
+// everything for backwards compatibility: test/hook.test.ts,
+// src/digest/collect.ts, and the generated OpenCode plugin all import
+// from this path.
+
+export {
+  bugSignalFromTranscript,
+  COMMIT_HINT_MIN_COMMITS,
+  type CommitHintInput,
+  type ContextLineData,
+  capContext,
+  cmdHookEditHint,
+  cmdHookMvGuard,
+  cmdHookReadHint,
+  cmdHookSessionStart,
+  cmdHookStop,
+  commitHintFor,
+  computeHintImpact,
+  cursorTranscriptPath,
+  decideStop,
+  type EditHintInput,
+  type EditTrackRow,
+  editHintFor,
+  editTrackPath,
+  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,
+  type HintFireRow,
+  type HintImpact,
+  hintLogDir,
+  hintLogPath,
+  hookTsMs,
+  isCodexPayload,
+  isCursorPayload,
+  mvGuardDecision,
+  type NormalizedStopInput,
+  normalizeStopInput,
+  type RawStopPayload,
+  READ_HINT_MIN_BYTES,
+  READ_HINT_MIN_LIMIT,
+  type ReadHintInput,
+  type ReadTrackRow,
+  type RereadHintInput,
+  readContextData,
+  readContextLines,
+  readHintFor,
+  readTrackPath,
+  recordHintFire,
+  rereadHintFor,
+  rewriteGitAutonomySystem,
+  rewriteGitAutonomyTool,
+  SESSION_START_MAX_CHARS,
+  type StopClient,
+  sessionKey,
+  sessionStartContext,
+  stopBlockedBefore,
+  stopBlockPath,
+  stopOutput,
+  utcStamp,
+  worktreeKey,
+} from "./adapters/hooks/index.js";