fapony 0.3.4 → 0.3.6

package/README.md

@@ -434,9 +434,10 @@ years:
 - **There is no `MASTER.md`.** Every line above is derived from the plan files themselves, so it
   cannot drift; a hand-kept master file always does.
 
-`status` / `blocked_by` / `blocks` / `superseded_by` are read by people, not by a tool — the one
-that read them, `plan_list`, was removed in 2026-09 once `mem kickoff` answered the same
-question from the CLI, where a schema costs nothing until it runs.
+`status` / `blocked_by` / `blocks` / `superseded_by` are read by `fapony mem plan-check`
+(dangling refs, blocker shipped but dependent still blocked, waiter cycles, blocked with all
+chunks ticked) and by `fapony mem plan-sweep` (blocked view + a `🔓` unblock hint on `--apply`).
+Sentence values ("waiting on support email") carry no `PLAN-*.md` token and are never flagged.
 
 The layout, and why archiving is a plain `git mv`:
 
@@ -464,18 +465,25 @@ fapony price-scan                        # fetch model price table → prices.js
 fapony usage-web [port]                   # live usage comparison dashboard from cache
 fapony stats [--mode verdict [--regime code|fix|review|plan|inquiry|test]]  # KPIs: pass/stall rate, by-model, by-grade — --mode verdict ranks by quality/tokens instead
 fapony digest [--since 7d|YYYY-MM-DD] [--format text|html] [--json] [--out FILE]  # single-page summary: decisions, open bugs, in-flight plans, cost, pass/fail — from what's already on disk
-fapony plan-seed <name> [--spec] [--scope <path>]...  # write PLAN (+SPEC): frontmatter, 8 empty sections, prior-art list, ledger context; SPEC chunks carry signatures, every section capped — the agent fills the judgment
+fapony plan-seed <name> [--spec] [--scope <path>]...  # write PLAN (+SPEC): frontmatter, 8 empty sections, prior-art list, mem-decision context + existing-in-scope; existing plans listed on stdout; SPEC chunks carry signatures, every section capped — the agent fills the judgment
 fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]  # read-only scope facts for a review (changed files, importers, untested, signatures, plan cross-check)
 
 # Memory & convention debt
 fapony mem add <kind> "<text>" --files f1,f2 [spec.md]   # append a mem row (decision/bug/note/next/hold)
 fapony mem close <id> "<msg>"              # close a bug
-fapony mem find "<text>"                   # substring-search every row
+fapony mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--open]  # search mem log
 fapony mem kickoff [<plan.md>]             # open a session + a next-up list
 fapony mem where                           # show the resolved mem dir and which step won
 fapony mem done | stale              # views
 fapony debt [--id <convention>] [--where <path>]   # ไฟล์ไหนยังไม่ย้ายไป convention ที่ประกาศไว้ (live, read-only)
 fapony lint-baseline [--cmd ...] [--diff]  # separate "already red" from "I made it red"
+
+# Hooks (wired by `fapony install`, not run by hand)
+fapony hook-stop                        # Stop hook: block turns with commits but no mem row
+fapony hook-read-hint                   # read/re-read annotations
+fapony hook-edit-hint                   # importer count before editing shape
+fapony hook-mv-guard                    # deny raw git mv of plan files into done/
+fapony hook-session-start               # SessionStart: kickoff into context
 ```
 
 *When* to call `mem add` is your project's call, not fapony's — write it in your own
@@ -501,7 +509,6 @@ fapony install --dry-run                  # show what would happen without writi
 fapony setup                             # interactive wizard: config + scaffold in one step
 fapony update                            # self-update via git pull
 fapony telemetry show|send               # opt-in only, default off — see https://github.com/kire21b/fapony/blob/main/TELEMETRY.md
-fapony test                              # self-check
 ```
 
 ## Config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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)",
@@ -29,11 +29,10 @@
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
-    "test": "bun fapony.ts test",
-    "test:fast": "SKIP_SLOW=1 bun fapony.ts test",
-    "test:one": "bun scripts/test-one.ts",
+    "test": "bun test --timeout 20000 --parallel",
+    "test:changed": "bun test --timeout 20000 --changed",
     "knip": "bunx knip@6 --exclude types,nsTypes || true",
-    "check": "bun run lint && bun run typecheck && bun fapony.ts test",
+    "check": "bun run lint && bun run typecheck && bun test --timeout 20000 --parallel",
     "prepublishOnly": "bash scripts/smoke-publish.sh",
     "release": "git checkout main && git pull --ff-only && npm version patch -m 'release v%s' && git push origin main --follow-tags",
     "overview": "bun fapony.ts report-web /tmp/fapony-overview.html && open /tmp/fapony-overview.html"

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

@@ -21,7 +21,7 @@ You are about to move a PLAN that has been shipped to the archive.
    Say in the summary that you stamped it, so a wrong HEAD is visible and correctable.
    STOP only if there's no git repo / no commits to hash from.
 
-1b. **A plan can also leave `plan/` without shipping** — it got absorbed into another plan, or the
+ 1b. **A plan can also leave `plan/` without shipping** — it got absorbed into another plan, or the
    redesign deleted the thing it planned. That is normal during a UI/UX sweep and is the main
    reason `plan/` grows forever: there is no state for "dead" so it just sits there. Archive it
    the same way, with two differences — header `> ⛔ **superseded by [PLAN-bar.md](PLAN-bar.md)**
@@ -37,12 +37,22 @@ You are about to move a PLAN that has been shipped to the archive.
    A plan that is merely *waiting* (on a person, a customer, a decision) is **not** dead and does
    not move — mark it `status: blocked` + `blocked_by: <what you are waiting for>` and leave it in
    `plan/` — the frontmatter is for the next person reading the folder, and the plan stays out
-   of `done/`, which is what `plan-sweep` and `kickoff` go by.
+   of `done/`, which is what `plan-sweep` and `kickoff` go by. Never `--apply` a blocked file;
+   a blocked file with all chunks ticked is deferred doc debt — ask the user: ship it or keep
+   waiting.
+
+ 1c. **Check the dep graph before moving** — `fapony mem plan-check` reads `blocked_by`/`blocks`
+    and says what a human would miss: a `blocked_by` pointing at a file that is not in `plan/`
+    or `done/`, a blocker already in `done/` while the dependent is still `status: blocked`,
+    a waiter cycle, and a blocked plan with all chunks ticked. Fix its issues first — a move
+    on top of a broken graph just relocates the confusion.
 
 2. **Run `plan-sweep --apply`** — this does the `git mv`, rewrites markdown links inside the
    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:
+   name the file, prints a `🔓 <shipped> — <waiter> lists it as blocker` line when the ship
+   unblocks a waiting plan (copy that line into your summary — the waiter keeps
+   `status: blocked` until its owner clears it), and logs a decision row — all in one call:
    ```bash
    fapony mem plan-sweep <PLAN-foo.md> --apply
    ```

package/skill/plan-with-pony/SKILL.md

@@ -88,9 +88,13 @@ fapony plan-seed <feature> --spec --scope <path>
 One command, no MCP round trip. It writes `<planDir>/PLAN-<feature>.md` +
 `<specDir>/SPEC-<feature>.md` — the frontmatter, the 8 empty sections, a `## 8. References` list
 of shipped plans that already touched this scope, and a `## Context (fapony)` block under the
-TL;DR (recent mem decisions plus which model holds up per task shape here). SPEC chunks carry
+TL;DR (recent mem decisions plus what is already in scope — one line per scope file with its
+exports; needs `--scope` to list anything). No ledger-ranking line: the ledger is frozen and
+cross-model ranking claims are off the table, so the seed does not point at them. SPEC chunks carry
 verbatim signatures, hard-capped (PLAN ≤ ~60 / SPEC ≤ 200 lines), and capped lines say what was
-cut. The CLI resolves plan-dir/spec-dir and refuses to overwrite (pick `-v2` — see Phase 2).
+cut. Stdout ends with the existing plan list (active first, then shipped) — the seed that lands
+next to a shipped decision without knowing it is the expensive mistake, and the file guard in §8
+is not where the glance lands. The CLI resolves plan-dir/spec-dir and refuses to overwrite (pick `-v2` — see Phase 2).
 
 **§2/§5 arrive empty on purpose (2026-09-18).** They used to hold a repetition scan and analyze
 findings; measured over every plan that ever used them, §5 printed "no findings" 3 times out of 3

package/src/adapters/cli.ts

@@ -6,13 +6,14 @@
 
 import { existsSync } from "node:fs";
 import { cmdAnalyze } from "../analyze.js";
+import { renderUsage, suggestCommand } from "../commands.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 { cmdMem, MEM_SUBCOMMANDS } from "../mem/index.js";
 import { initStore } from "../mem/store.js";
 import { cmdPriceScan } from "../price/index.js";
 import { cmdReport, cmdReportWeb } from "../report/index.js";
@@ -35,6 +36,11 @@ import { cmdMcp } from "./mcp/transport.js";
 export async function cliMain(): Promise<void> {
   const [cmd, ...a] = process.argv.slice(2);
 
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(renderUsage());
+    return;
+  }
+
   if (cmd === "analyze") {
     cmdAnalyze(a);
   } else if (cmd === "debt") {
@@ -110,14 +116,13 @@ export async function cliMain(): Promise<void> {
     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]",
-    );
+    const hints = suggestCommand(cmd ?? "", MEM_SUBCOMMANDS);
+    if (hints.length > 0) {
+      console.error(`did you mean ${hints.map((h) => `"${h}"`).join(" or ")}?`);
+    }
+    console.error(`usage: fapony <command> [args] — see "fapony --help"`);
     process.exit(1);
   }
 }

package/src/adapters/hooks/bug-markers.ts

@@ -0,0 +1,50 @@
+// src/adapters/hooks/bug-markers.ts — how fapony recognises "a bug was found".
+//
+// Split from stop.ts so the Stop hook (blocking, claude/cursor/codex) and the
+// OpenCode commit hint (advisory) share one definition. A bug that lives only
+// in a `note` row is not surfaced by anything, so the two signals are:
+//
+//   1. a structured commit-message token — `fix:` / `bugfix:` / `hotfix:`.
+//      Universal by construction: only the type token is English, so a Thai
+//      description on a conventional commit still reads as a bug
+//      (`fix(debt): ...`). This is the language-independent signal, and it is
+//      already how this repo commits (120/581 commits are fix-family).
+//   2. free-text announcement phrases — inherently per-language. A substring
+//      list cannot be universal; keep it small and open instead. Add your
+//      language here — do NOT invent a new row kind for it (open/closed is
+//      derived from close rows already; a kind would just drift).
+//
+// Deliberately NOT matched: symptom words ("broken", "dies silently"). They
+// appear in every bug report and would fire on any turn that reads one — the
+// Stop hook blocks once per session on a match, so a false positive is costly.
+
+/** Free-text announcement phrases ("I found a bug"), never symptom words. */
+export const BUG_MARKERS: RegExp[] = [
+  /เจอบั๊ก/,
+  /พบบั๊ก/,
+  /\bfound (?:a |the )?bug\b/i,
+  /\b(?:this|that|it)(?:'s| is) a bug\b/i,
+  /\bbug\b\s*:/i,
+];
+
+/**
+ * The matched marker phrase, or null. Returns the matched text so the caller
+ * can quote it back to the agent (stop.ts does, in its block reason).
+ */
+export function hasBugMarker(text: string): string | null {
+  for (const re of BUG_MARKERS) {
+    const m = text.match(re);
+    if (m) return m[0];
+  }
+  return null;
+}
+
+// Conventional-commit bug types, anchored to the subject prefix — arbitrary
+// prose containing "fix" ("pre-fix the cache") must not match. Language-free:
+// the type token stays English even when the description is not.
+const BUGFIX_COMMIT = /^(?:fix|bugfix|hotfix)(?:\([^)]*\))?!?:/;
+
+/** True when a commit subject declares a fix (the universal bug token). */
+export function isBugfixCommit(subject: string): boolean {
+  return BUGFIX_COMMIT.test(subject.trim());
+}

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

@@ -3,15 +3,21 @@
 // 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 {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
 import {
   type HintFireRow,
   type HintImpact,
   hintLogDir,
   worktreeKey,
 } from "../../core/hint-log.js";
-import { debtForFile, loadConventions } from "../../debt/index.js";
+import { debtForFile, resolveDebtScope } from "../../debt/index.js";
 
 /**
  * Compute hint-fire impact from the log. `since` is an ISO date string;
@@ -80,14 +86,25 @@ export function computeHintImpact(
 
   for (const [key, ids] of debtByFile) {
     const [worktree, file] = key.split("\t");
-    const absFile = join(worktree, file);
+    let 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));
+      // The log stores the worktree lexically; scanRoot is physical —
+      // resolve so debtForFile compares like with like.
+      try {
+        absFile = realpathSync(absFile);
+      } catch {
+        // keep the lexical form
+      }
+      // Same scope as the hint itself — resolving at the git root would
+      // load zero conventions in a monorepo and count every shown id as
+      // resolved (precision stuck at 100%).
+      const scope = resolveDebtScope(dirname(absFile));
+      const convs = debtForFile(scope.scanRoot, absFile, scope.loaded);
       currentIds = new Set(convs.map((c) => c.id));
     } catch {
       impact.debt.unknown += ids.length;

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

@@ -4,9 +4,9 @@
 // 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 { basename, dirname, join, relative } from "node:path";
 import { collectSourceFiles, SCAN_EXTS } from "../../analyze.js";
-import { debtForFile, loadConventions } from "../../debt/index.js";
+import { debtForFile, resolveDebtScope } from "../../debt/index.js";
 import { readMemLog } from "../../memory.js";
 
 const DEBT_HINT_MAX = 3;
@@ -44,21 +44,27 @@ export function readContextData(
     const debtLines: string[] = [];
     const memLines: string[] = [];
 
-    // convention debt — source files only, fresh from the repo
+    // convention debt — source files only, fresh from the repo. The scope
+    // pairs the git root (repo-relative `where`) with the nearest
+    // conventions file — anchoring the load at the root goes silent in a
+    // monorepo with app-scoped conventions (bug mucvfaxk).
     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)) {
+      const scope = resolveDebtScope(dirname(abs));
+      for (const c of debtForFile(scope.scanRoot, abs, scope.loaded).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);
+    // mem rows that are about this file — resolve the log from the file's own
+    // directory, not the repo root. In a monorepo the log is app-scoped, so
+    // anchoring at the root sees only an out-of-scope candidate and goes silent
+    // even though the file being touched sits right under its log (bug muc9q47r).
+    const mem = readMemLog(dirname(abs));
     if (mem.rows.length > 0) {
       const base = basename(rel);
       const direct: typeof mem.rows = [];

package/src/adapters/hooks/index.ts

@@ -15,6 +15,11 @@ export {
   sessionKey,
   utcStamp,
 } from "../../core/hook-helpers.js";
+export {
+  BUG_MARKERS,
+  hasBugMarker,
+  isBugfixCommit,
+} from "./bug-markers.js";
 export { computeHintImpact } from "./compute-hint-impact.js";
 export {
   type ContextLineData,
@@ -64,6 +69,7 @@ export {
   sessionStartContext,
 } from "./session-start.js";
 export {
+  bugSignalFromTranscript,
   cmdHookStop,
   cursorTranscriptPath,
   decideStop,

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

@@ -18,6 +18,7 @@ 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 { hasBugMarker, isBugfixCommit } from "./bug-markers.js";
 import { readContextData } from "./context-data.js";
 
 // --- Read hint (size) ---
@@ -244,7 +245,9 @@ export function commitHintFor(opts: CommitHintInput): string | null {
 
     let memLastTs: string | null = null;
     try {
-      memLastTs = readMemLog(worktree).rows[0]?.ts ?? null;
+      // Anchor at the dir the commit ran in, not the repo root: the log is
+      // app-scoped in a monorepo, and root resolution misses it (bug muc9q47r).
+      memLastTs = readMemLog(opts.cwd).rows[0]?.ts ?? null;
     } catch {
       memLastTs = null;
     }
@@ -258,6 +261,13 @@ export function commitHintFor(opts: CommitHintInput): string | null {
     const commitList = log ? log.split("\n").filter(Boolean) : [];
     if (commitList.length < COMMIT_HINT_MIN_COMMITS) return null;
 
+    // %h %s — strip the short hash to test the subject alone.
+    const subjectOf = (c: string) => c.replace(/^\S+\s+/, "");
+    const bugCommits = commitList.filter(
+      (c) =>
+        isBugfixCommit(subjectOf(c)) || hasBugMarker(subjectOf(c)) !== null,
+    );
+
     const lines: string[] = [
       `${commitList.length} commit(s) since last mem row (${memLastTs.slice(0, 10)}) — record a mem row for this work.`,
     ];
@@ -266,6 +276,12 @@ export function commitHintFor(opts: CommitHintInput): string | null {
     lines.push(
       `fapony mem add <decision|bug|note> "what happened" --files <files> ${worktree}/.fapony/plan/PLAN.md`,
     );
+    if (bugCommits.length > 0) {
+      lines.push(
+        `${bugCommits.length} of these read as a bug (fix-type commit or found-a-bug wording) — use kind:bug so it surfaces later, not note:`,
+      );
+      lines.push(`  fapony mem add bug "what broke" --files <files>`);
+    }
 
     const prefixed = lines.map((l) => `fapony: ${l}`).join("\n");
     return prefixed;

package/src/adapters/hooks/session-start.ts

@@ -69,12 +69,23 @@ export function sessionStartContext(
   cwd: string,
   faponyTs: string = Bun.main,
 ): string | null {
-  if (!whereMemDir(cwd).dir) return null;
-  const p = Bun.spawnSync([process.execPath, faponyTs, "mem", "kickoff"], {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
+  // Resolution shares one function with every reader. A bare monorepo root has
+  // no log at/above cwd, so the resolver reports the app-scoped log only as an
+  // out-of-scope candidate (SPEC §1). For a *read* at session start that is
+  // still recoverable: if the whole repo holds exactly one log, it is the
+  // project's memory — point kickoff at it with --mem-dir. Two or more is
+  // genuinely ambiguous (which app?), so refuse exactly as the resolver does.
+  const resolved = whereMemDir(cwd);
+  const memArgs: string[] = [];
+  if (!resolved.dir) {
+    const candidates = resolved.candidates ?? [];
+    if (candidates.length !== 1) return null;
+    memArgs.push("--mem-dir", candidates[0]);
+  }
+  const p = Bun.spawnSync(
+    [process.execPath, faponyTs, "mem", ...memArgs, "kickoff"],
+    { cwd, stdout: "pipe", stderr: "pipe" },
+  );
   const out = p.stdout.toString().trim();
   if (p.exitCode !== 0 || !out) return null;
   return capContext(out);

package/src/adapters/hooks/stop.ts

@@ -15,6 +15,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { hookTsMs, sessionKey, utcStamp } from "../../core/hook-helpers.js";
 import { readMemLog, whereMemDir } from "../../memory.js";
+import { hasBugMarker } from "./bug-markers.js";
 
 // --- Types ---
 
@@ -120,7 +121,8 @@ export function normalizeStopInput(
 
 /**
  * Pure decision: block when this session produced commits but no mem row
- * newer than session start exists.
+ * newer than session start exists, or when the agent announced a bug but
+ * filed no kind:bug row.
  */
 export function decideStop(opts: {
   stopHookActive: boolean;
@@ -130,9 +132,23 @@ export function decideStop(opts: {
   commitList?: string[];
   memLastTs?: string | null;
   memCandidates?: string[];
+  bugSignal?: string | null;
+  bugRowSinceStart?: boolean;
 }): string | null {
   if (opts.stopHookActive) return null;
   if (!opts.worktree) return null;
+
+  // --- Bug-signal block (independent of commits) ---
+  if (opts.bugSignal && !opts.bugRowSinceStart) {
+    return [
+      `This turn reported a bug ("${opts.bugSignal}") but no mem row with kind:bug exists for this session.`,
+      `A bug described in chat is lost when the room closes — a decision row does not surface it.`,
+      `  fapony mem add bug "<what is broken>" --files <files>`,
+      `Already filed elsewhere, or not a bug? End the turn again — this fires once per session.`,
+    ].join("\n");
+  }
+
+  // --- Commit block (original) ---
   if (opts.commits < 1) return null;
   if (!opts.memLastTs && !opts.memCandidates?.length) return null;
   if (opts.since && opts.memLastTs) {
@@ -164,6 +180,11 @@ export function decideStop(opts: {
       `${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.`,
   );
+  if (opts.bugSignal) {
+    lines.push(
+      `This turn announced a bug ("${opts.bugSignal}") — use kind:bug, not decision.`,
+    );
+  }
   return lines.join("\n");
 }
 
@@ -182,6 +203,7 @@ const STOP_BLOCK_DIR = "stop-block";
 interface StopBlockRow {
   ts: string;
   worktree: string;
+  kind?: string;
 }
 
 /** Absolute path of a session's block log — may not exist. */
@@ -192,12 +214,16 @@ export function stopBlockPath(session: string): string {
 }
 
 /**
- * True when this session already blocked for this worktree — the caller then
- * lets the turn end. Records the block when it has not.
+ * True when this session already blocked for this worktree + kind — the caller
+ * then lets the turn end. Records the block when it has not.
+ *
+ * `kind` defaults to `"commit"` for backwards compatibility. Bug blocks use
+ * `"bug"` so they don't consume the commit block's quota.
  */
 export function stopBlockedBefore(
   session: string | null,
   worktree: string,
+  kind: string = "commit",
 ): boolean {
   if (!session) return false;
   const path = stopBlockPath(session);
@@ -206,7 +232,8 @@ export function stopBlockedBefore(
       for (const line of readFileSync(path, "utf-8").split("\n")) {
         if (!line) continue;
         try {
-          if ((JSON.parse(line) as StopBlockRow).worktree === worktree) {
+          const row = JSON.parse(line) as StopBlockRow;
+          if (row.worktree === worktree && (row.kind ?? "commit") === kind) {
             return true;
           }
         } catch {
@@ -216,7 +243,7 @@ export function stopBlockedBefore(
     }
     const dir = join(path, "..");
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const row: StopBlockRow = { ts: new Date().toISOString(), worktree };
+    const row: StopBlockRow = { ts: new Date().toISOString(), worktree, kind };
     appendFileSync(path, `${JSON.stringify(row)}\n`, "utf-8");
   } catch {
     return false;
@@ -224,6 +251,89 @@ export function stopBlockedBefore(
   return false;
 }
 
+// --- Bug-signal detection ---
+
+/**
+ * Scan assistant text from a Claude transcript for bug markers. Reads only
+ * the tail of the file (last 200KB) to avoid parsing the full transcript.
+ * Returns the first matched marker word, or null.
+ */
+export function bugSignalFromTranscript(
+  transcriptPath: string,
+  sinceMs: number,
+): string | null {
+  try {
+    const stat = statSync(transcriptPath);
+    // Cap at 10MB — hook must not stall turn-end
+    if (stat.size > 10 * 1024 * 1024) return null;
+
+    // Read tail to avoid parsing the full transcript
+    const tailBytes = Math.min(stat.size, 200 * 1024);
+    const fd = require("node:fs").openSync(transcriptPath, "r");
+    const buf = Buffer.alloc(tailBytes);
+    require("node:fs").readSync(
+      fd,
+      buf,
+      0,
+      tailBytes,
+      Math.max(0, stat.size - tailBytes),
+    );
+    require("node:fs").closeSync(fd);
+
+    const tail = buf.toString("utf-8");
+    // When reading from the middle of a large file, the first line is partial
+    const readingMidFile = tailBytes < stat.size;
+    const startIdx = readingMidFile ? tail.indexOf("\n") : -1;
+    const lines =
+      startIdx >= 0 ? tail.slice(startIdx + 1).split("\n") : tail.split("\n");
+
+    for (const line of lines) {
+      if (!line) continue;
+      // Transcript tail: untyped JSONL — the structural type below names only
+      // the fields this scan reads (biome noExplicitAny: no `any` annotation).
+      let o: {
+        message?: {
+          role?: string;
+          content?: Array<{ type?: string; text?: string }>;
+          created_at?: string;
+        };
+      };
+      try {
+        o = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const m = o.message;
+      if (m?.role !== "assistant" || !Array.isArray(m.content)) continue;
+      // Skip messages older than session start
+      if (m.created_at) {
+        const msgMs = new Date(m.created_at).getTime();
+        if (!Number.isNaN(msgMs) && msgMs < sinceMs) continue;
+      }
+      for (const b of m.content) {
+        if (b.type !== "text" || typeof b.text !== "string") continue;
+        const hit = hasBugMarker(b.text);
+        if (hit) return hit;
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * True when the mem log has at least one kind:bug row with ts >= since.
+ */
+function hasBugRowSince(worktree: string, since: string): boolean {
+  try {
+    const { rows } = readMemLog(worktree, since);
+    return rows.some((r) => r.kind === "bug");
+  } catch {
+    return false;
+  }
+}
+
 function git(args: string[], cwd: string): string | null {
   try {
     const p = Bun.spawnSync(["git", ...args], {
@@ -262,6 +372,8 @@ export async function cmdHookStop(): Promise<void> {
     let commitList: string[] = [];
     let memLastTs: string | null = null;
     let memCandidates: string[] = [];
+    let bugSignal: string | null = null;
+    let bugRowSinceStart = false;
     if (worktree && since) {
       const log = git(
         ["log", "--since", `${since} +0000`, "--format=%h %s"],
@@ -276,6 +388,14 @@ export async function cmdHookStop(): Promise<void> {
       } catch {
         memLastTs = null;
       }
+      // Bug-signal detection (independent of commits)
+      if (norm.transcriptPath && process.env.FAPONY_NO_BUG_BLOCK !== "1") {
+        const sinceMs = hookTsMs(since);
+        if (!Number.isNaN(sinceMs)) {
+          bugSignal = bugSignalFromTranscript(norm.transcriptPath, sinceMs);
+          if (bugSignal) bugRowSinceStart = hasBugRowSince(worktree, since);
+        }
+      }
     }
 
     reason = decideStop({
@@ -286,11 +406,17 @@ export async function cmdHookStop(): Promise<void> {
       commitList,
       memLastTs,
       memCandidates,
+      bugSignal,
+      bugRowSinceStart,
     });
     if (
       reason &&
       worktree &&
-      stopBlockedBefore(norm.transcriptPath, worktree)
+      stopBlockedBefore(
+        norm.transcriptPath,
+        worktree,
+        bugSignal ? "bug" : "commit",
+      )
     ) {
       reason = null;
     }