fapony 0.1.1 → 0.1.3

package/src/hook.ts

@@ -1,17 +1,20 @@
 // src/hook.ts — Claude Code / Cursor Stop hook: refuse to end a turn that produced
 // commits but no verdict.
 //
-// ทำไมต้องเป็น hook ไม่ใช่ข้อความ: SERVER_INSTRUCTIONS เป็นการ *ขอ* ให้ agent จำ
-// วัดแล้วว่าไม่พอ · hook ไม่ได้ตัดสินเกรดแทน (ตัดสินไม่ได้ — มันไม่เห็นว่างานผ่านหรือพัง)
-// มันแค่ไม่ให้จบเทิร์นจนกว่า agent จะตัดสินเอง แยก "ใครตัดสิน" ออกจาก "ใครบังคับให้ตัดสิน"
+// 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"
 //
-// สัญญาณคือ commit ไม่ใช่ dirty tree — dirty = กำลังทำอยู่, commit = หน่วยงานจบแล้ว
-// ตรงกับนิยาม "1 run = 1 หน่วยงานที่วัดได้" (กฎ 7)
+// 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)
 //
-// สอง payload หนึ่งการตัดสิน — field-mapping เท่านั้น:
+// 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 = hook เคยยิงแล้ว, status ≠ completed = ปล่อยผ่าน)
+//   (cursor: loop_count ≥ 1 = the hook already fired, status ≠ completed = allow)
 
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
@@ -54,7 +57,7 @@ export function utcStamp(d: Date): string {
  *
  * PLAN-mem-mcp chunk 3: the block message now carries the commit list and the
  * mem-log status (last row date). Both are *information*, never conditions —
- * the block condition stays verdict-only (กฎ 7: the hook does not judge, it
+ * the block condition stays verdict-only (rule 7: the hook does not judge, it
  * reports what is pending so the agent decides what deserves recording).
  */
 export function decideStop(opts: {
@@ -224,7 +227,7 @@ export async function cmdHookStop(): Promise<void> {
           .get(worktree, since) as { n: number } | null;
         verdicts = row?.n ?? 0;
         // Informational only — read-only, degrade silently (mem status never
-        // becomes a block condition, กฎ 7).
+        // becomes a block condition, rule 7).
         try {
           const mem = readMemLog(worktree);
           memLastTs = mem.rows[0]?.ts ?? null;
@@ -251,15 +254,17 @@ export async function cmdHookStop(): Promise<void> {
 
 // --- Read hint (PreToolUse annotate — never block, never dedupe) ---
 //
-// การอ่านไฟล์ใหญ่ทั้งไฟล์เป็นจุดที่ agent จ่าย token โดยไม่รู้ตัว — เสียงเตือน
-// ใน skill ไม่เคยพอ (หลักเดียวกับ Stop hook: พูดตอนมันกำลังจ่าย) แต่ hook นี้
-// **annotate เท่านั้น**: ไม่มี permissionDecision, ไม่มี "อ่านไปแล้ว" dedupe —
-// context compaction ทำให้ "อ่านไปแล้ว" กลายเป็นเท็จ และ hook ที่เดาผิดแล้วขัง
-// agent แย่กว่าไม่มี hook (กฎของ hook.ts เดิม) — annotate ขังไม่ได้ด้วย
-// construction, ต้นทุนพลาดสูงสุดคือบรรทัดเดียวที่ไม่จำเป็น
+// 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
 //
-// ข้อความเป็น fact ล้วน (จำนวนบรรทัด + คำสั่ง + ค่าที่วัดครั้งเดียว) ไม่ใช่
-// estimate ต่อไฟล์ — เดา token เป็นการแต่งตัวเป็นข้อมูล ขัด "facts only"
+// 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;
@@ -314,6 +319,98 @@ export function readHintFor(opts: ReadHintInput): string | 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 verdict pending. 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 + verdict status), not an estimate
+
+/** Below this number of commits, the hint is unnecessary noise. */
+export const COMMIT_HINT_MIN_COMMITS = 1;
+/** Cap commits shown in the hint message. */
+const COMMIT_HINT_MAX_LIST = 5;
+
+export interface CommitHintInput {
+  command: unknown;
+  cwd: string;
+}
+
+/**
+ * Nudge for bash commands containing `git commit` that produced
+ * ungraded commits. Returns a one-to-two line hint string, or null
+ * when there is nothing to nudge about (already graded, no commits,
+ * not a git commit command, not a git repo, any failure).
+ *
+ * Every unknown resolves to null — a hint must never fire on a
+ * guess. The work is cheap: one git rev-parse + one git log + one
+ * SQLite count.
+ */
+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 since the worktree's last verdict, not "does a
+    // verdict exist anywhere in its history" — a worktree that earned one
+    // verdict months ago must still nudge on every commit made since, the
+    // same way cmdHookStop windows on `e.ts >= since` (session start) rather
+    // than "any verdict this worktree has ever had".
+    const db = openDb();
+    const lastVerdict = db
+      .query(
+        `SELECT MAX(e.ts) AS ts FROM events e JOIN runs r ON r.id = e.run_id
+         WHERE e.kind = 'gate' AND r.worktree = ?`,
+      )
+      .get(worktree) as { ts: string | null } | null;
+    // git's --since is inclusive to the second, and the commit a verdict
+    // just graded often lands in the same UTC second as the verdict itself
+    // (verdict_submit runs right after the commit) — bump by 1s so that
+    // commit isn't re-flagged as ungraded because of its own grade.
+    const since = lastVerdict?.ts
+      ? utcStamp(
+          new Date(
+            new Date(`${lastVerdict.ts.replace(" ", "T")}Z`).getTime() + 1000,
+          ),
+        )
+      : null;
+
+    const log = since
+      ? git(["log", "--since", `${since} +0000`, "--format=%h %s"], worktree)
+      : git(["log", "--format=%h %s"], worktree);
+    const commitList = log ? log.split("\n").filter(Boolean) : [];
+    if (commitList.length < COMMIT_HINT_MIN_COMMITS) return null;
+
+    const reason = decideStop({
+      stopHookActive: false, // annotate-only: never "already blocked"
+      worktree,
+      commits: commitList.length,
+      verdicts: 0, // every commit left in the window is, by construction, ungraded
+      commitList: commitList.slice(0, COMMIT_HINT_MAX_LIST),
+    });
+    if (!reason) return null;
+
+    // Prefix each line with "fapony:" so it's visually distinct
+    // from normal bash output in the agent's context.
+    const prefixed = reason
+      .split("\n")
+      .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> {
@@ -355,10 +452,11 @@ export async function cmdHookReadHint(): Promise<void> {
 
 // --- Debt + mem context (PLAN-convention-debt chunk 4) ---
 //
-// จังหวะเดียวที่การแก้หนี้คุ้ม token คือตอนที่เปิดไฟล์นั้นอยู่แล้ว — hook-read-hint
-// จึงแนบสองอย่างต่อท้าย size hint: convention ที่ไฟล์ยังค้าง (debt detector, คำนวณสด)
-// และแถว mem ที่เอ่ยถึงไฟล์นั้น (ข้าม session) · **annotate เท่านั้น** เหมือนเดิม —
-// ไม่ block, ไม่ dedupe, ทุก unknown → เงียบ · cap รวม 5 บรรทัด (หนี้ 3 · mem 2)
+// 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;

package/src/init-mem.ts

@@ -31,9 +31,9 @@ export function cmdInitMem(args: string[]): void {
   const worktreeKey = args.find((x) => !x.startsWith("-"));
   const config = loadConfig();
 
-  // ไม่ระบุ key = repo ที่ยืนอยู่ตอนนี้ — ทำให้ `fapony init-mem --update` รันในโปรเจกต์ของใครก็ได้
-  // โดยไม่ต้องลงทะเบียน worktree ก่อน (loadConfig อ่าน fapony.config.json ของ cwd อยู่แล้ว
-  // จึงได้ paths.memoryEntry ของโปรเจกต์นั้นมาเอง)
+  // no key given = the repo you are standing in — so `fapony init-mem --update` runs in anyone's project
+  // without registering the worktree first (loadConfig already reads the cwd's fapony.config.json,
+  // so it picks up that project's paths.memoryEntry by itself)
   const worktree = worktreeKey ? config.worktrees[worktreeKey] : process.cwd();
   if (!worktree) {
     console.error(`unknown worktree key: ${worktreeKey}`);

package/src/install/opencode.ts

@@ -112,6 +112,7 @@ export function cmdInstallOpencode(
     const skillsDir = claudeSkillsDir(getHome);
     reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
     installReadHintPlugin(dryRun, getHome);
+    installCommitHintPlugin(dryRun, getHome);
     return;
   }
 
@@ -134,6 +135,7 @@ export function cmdInstallOpencode(
     }
     console.log(computeDiff(before, after));
     installReadHintPlugin(dryRun, getHome);
+    installCommitHintPlugin(dryRun, getHome);
     return;
   }
 
@@ -154,6 +156,7 @@ export function cmdInstallOpencode(
   const skillsDir = claudeSkillsDir(getHome);
   reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
   installReadHintPlugin(dryRun, getHome);
+  installCommitHintPlugin(dryRun, getHome);
 }
 
 /**
@@ -164,35 +167,86 @@ export function cmdInstallOpencode(
  * throws, never dedupes ("you already read this" goes false after context
  * compaction — a hook that guesses wrong must never trap the agent).
  *
- * Logic lives in src/hook.ts (readHintFor) — the plugin imports it from the
- * install root (path baked at install time), same one-copy-per-client shape
- * as the skills symlinks: a git pull in INSTALL_ROOT updates every client.
- * Best-effort, same policy as the claude hooks: an existing file that isn't
- * fapony's is never overwritten, and a failure never fails the install.
+ * Logic lives in src/hook.ts (readHintFor + readContextLines) — the plugin
+ * imports it from the install root (path baked at install time), same
+ * one-copy-per-client shape as the skills symlinks: a git pull in
+ * INSTALL_ROOT updates every client. Mirrors Claude's cmdHookReadHint
+ * (PreToolUse), which appends both the size hint and the debt/mem context —
+ * OpenCode was missing the second half until now (only the size hint was
+ * wired), so a convention debt on the file you just opened, or a mem-log
+ * row about it, never reached OpenCode even though the detector already
+ * runs on every read. Best-effort, same policy as the claude hooks: an
+ * existing file that isn't fapony's is never overwritten, and a failure
+ * never fails the install.
  */
 export function readHintPluginSource(root: string): string {
   const hookModule = JSON.stringify(join(root, "src", "hook.ts"));
   return `// fapony read hint — annotates full-file reads of large source files with a
-// factual review-seed pointer. Annotate only: never blocks, never dedupes.
+// factual review-seed pointer, plus any convention debt or mem-log row about
+// the file. Annotate only: never blocks, never dedupes.
 // Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
-import { readHintFor } from ${hookModule};
+import { readHintFor, readContextLines } from ${hookModule};
 
 export const FaponyReadHint = async ({ directory }) => {
   return {
     "tool.execute.after": async (input, output) => {
       try {
         if (input.tool !== "read") return;
+        const parts = [];
         const hint = readHintFor({
           filePath: input.args?.filePath,
           offset: input.args?.offset,
           limit: input.args?.limit,
           cwd: directory,
         });
+        if (hint) parts.push(hint);
+        for (const line of readContextLines(input.args?.filePath, directory)) {
+          parts.push(line);
+        }
+        if (parts.length > 0 && typeof output.output === "string") {
+          output.output = output.output + "\\n" + parts.join("\\n");
+        }
+      } catch {
+        // a hint must never break a read
+      }
+    },
+  };
+};
+`;
+}
+
+/**
+ * OpenCode plugin — the commit hint's in-process shape. `tool.execute.after`
+ * on the bash tool: when the command contains `git commit` and the worktree
+ * has ungraded commits, appends a nudge to the command output. Annotate only
+ * (no decision:block — OpenCode has no stop-hook equivalent).
+ *
+ * Logic lives in src/hook.ts (commitHintFor) — same one-copy-per-client shape
+ * as the read hint: a git pull in INSTALL_ROOT updates every client.
+ */
+export function commitHintPluginSource(root: string): string {
+  const hookModule = JSON.stringify(join(root, "src", "hook.ts"));
+  return `// fapony commit hint — annotates git commit bash commands with a
+// verdict reminder when commits have no verdict filed yet.
+// Annotate only: never blocks, never dedupes.
+// Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
+import { commitHintFor } from ${hookModule};
+
+export const FaponyCommitHint = async ({ directory }) => {
+  return {
+    "tool.execute.after": async (input, output) => {
+      try {
+        if (input.tool !== "bash") return;
+        const command = input.args?.command;
+        const hint = commitHintFor({
+          command,
+          cwd: directory,
+        });
         if (hint && typeof output.output === "string") {
           output.output = output.output + "\\n" + hint;
         }
       } catch {
-        // a hint must never break a read
+        // a hint must never break a bash command
       }
     },
   };
@@ -232,3 +286,36 @@ function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
     `  read hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
   );
 }
+
+function installCommitHintPlugin(dryRun: boolean, getHome: () => string): void {
+  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
+  const pluginPath = join(pluginsDir, "fapony-commit-hint.ts");
+  if (existsSync(pluginPath)) {
+    let current = "";
+    try {
+      current = readFileSync(pluginPath, "utf-8");
+    } catch {
+      current = "";
+    }
+    if (current.includes("commitHintFor")) {
+      console.error(`  commit hint: already installed — no change`);
+      return;
+    }
+    console.error(
+      `  commit hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+    );
+    return;
+  }
+  if (!dryRun) {
+    try {
+      mkdirSync(pluginsDir, { recursive: true });
+      writeFileSync(pluginPath, commitHintPluginSource(INSTALL_ROOT), "utf-8");
+    } catch (e) {
+      console.error(`  commit hint: failed to write — ${(e as Error).message}`);
+      return;
+    }
+  }
+  console.error(
+    `  commit hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  );
+}

package/src/install/types.ts

@@ -11,7 +11,7 @@ export const MCP_KEY = "fapony";
 
 export const MCP_CONFIG = {
   type: "local",
-  command: ["bun", "run", "fapony.ts", "mcp"],
+  command: ["bun", "run", join(INSTALL_ROOT, "fapony.ts"), "mcp"],
 };
 
 /** ZCode uses the stdio MCP shape: command is a string, args is an array.

package/src/install.ts

@@ -31,7 +31,11 @@ export {
 export { cmdInstallCodex } from "./install/codex.js";
 export { cmdInstallCursor } from "./install/cursor.js";
 export { detectClients } from "./install/detect.js";
-export { cmdInstallOpencode } from "./install/opencode.js";
+export {
+  cmdInstallOpencode,
+  commitHintPluginSource,
+  readHintPluginSource,
+} from "./install/opencode.js";
 export {
   agentsSkillsDir,
   claudeSkillsDir,

package/src/lint-baseline.ts

@@ -1,15 +1,15 @@
 // src/lint-baseline.ts — `fapony lint-baseline`: separate "was red before" from "I made it red".
 //
-// warning กับ error ที่แดงอยู่ก่อนหน้า agent เข้ามา ทำให้ agent ต้อง `fix all` ก่อน
-// แล้วงานจริงถูกกลบใน diff ก้อนเดียว (SPEC-convention-debt §4 — จากปากเจ้าของ:
-// "138 จุดใน ~40 ไฟล์ที่ไม่เกี่ยวกับงาน") ตัวเลขของรีโปที่แดงอยู่แล้ว 212 จุด —
-// agent ที่ไม่ได้ทำอะไรผิดต้องเห็น **0**
+// warnings and errors already red before the agent arrived force the agent to `fix all` first
+// and then the real work is buried in one large diff (SPEC-convention-debt §4 — from the owner:
+// "138 spots across ~40 files unrelated to the work") the repo's own red count is 212 —
+// an agent that did nothing wrong must see **0**
 //
-// กลไก — ไม่รู้จัก eslint: รันคำสั่งที่รีโปบอก (--cmd หรือ evidence.json ชื่อ "lint"),
-// parse เป็นชุด `path:rule-id` (**ไม่ใช่เลขบรรทัด** — บรรทัดขยับทุกครั้งที่แก้ไฟล์),
-// เก็บ baseline ไว้ที่ base_sha · ผลลัพธ์ไม่เข้า state.db (2 ตารางห้ามเพิ่ม) —
-// เป็นไฟล์ชั่วคราวใต้ state dir และถูกทิ้งเมื่อ --diff รายงานแล้ว · รายงานอย่างเดียว
-// ไม่ block — agent ตัดสินเองว่าจะแก้ของเก่าด้วยไหม
+// Mechanism — does not know eslint: runs the command the repo declares (--cmd or evidence.json named "lint"),
+// parses into a set of `path:rule-id` (**not line numbers** — lines shift every time a file is edited),
+// stores the baseline at base_sha · results never enter state.db (2 tables, no additions) —
+// it is a temporary file under the state dir and is discarded once --diff reports · report only
+// never blocks — the agent decides whether to fix the old issues too
 
 import { execSync } from "node:child_process";
 import {

package/src/mcp/tools/mem.ts

@@ -1,6 +1,6 @@
 // src/mcp/tools/mem.ts — mem_find: read-only search over the project's mem log
 //
-// "เขียนได้ ≠ อ่านกลับได้" — the write side works from the CLI with no MCP
+// "writable ≠ readable back" — the write side works from the CLI with no MCP
 // (vela: 2,920 rows / 49 days); what was missing is "which rows are about the
 // files I am about to touch". Read-only over readMemLog (PLAN-mem-mcp chunk 2).
 //

package/src/mcp/tools/stats.ts

@@ -86,11 +86,11 @@ export function toolFaponyStats(args: Record<string, unknown>): ToolResult {
     };
   }
 
-  // json:true → StatsData ล้วน (SPEC-verdict-stats) — ห้ามแทรก text อื่น
+  // json:true → pure StatsData (SPEC-verdict-stats) — no other text may be inserted
   if (args.json === true) {
     return jsonResult(data);
   }
 
-  // json:false → text เดียวกับ `fapony stats` — same formatter, raw (not JSON-wrapped)
+  // json:false → the same text as `fapony stats` — same formatter, raw (not JSON-wrapped)
   return { content: [{ type: "text", text: formatStatsText(data) }] };
 }

package/src/mcp/tools/usage.ts

@@ -13,7 +13,7 @@ import {
 } from "../../session/index.js";
 import { jsonResult, type ToolResult } from "../types.js";
 
-/** สรุป list-price ต่อ client — additive ไม่แตะบรรทัดเดิม */
+/** list-price summary per client — additive, leaves existing lines untouched */
 function imputationOf(
   result: PassiveUsageResult,
   prices: PriceTable | null,
@@ -45,7 +45,7 @@ function imputedTextLines(
   return [`  ${label}list-price equivalent: ${parts.join(" · ")}`];
 }
 
-/** ราคา list ราย model ต่อท้ายชื่อรุ่น — เฉพาะแถวที่ client ไม่บันทึก cost */
+/** list price per model appended to the model name — only rows where the client records no cost */
 function imputedSuffix(
   provider: string,
   model: string,
@@ -78,7 +78,7 @@ export function toolPassiveUsage(args: Record<string, unknown>): ToolResult {
     result: client.read(worktree, since, until, detail),
   }));
 
-  // ราคา list จาก cache อย่างเดียว — อ่านครั้งเดียวต่อ call ไม่ใช่ต่อ section
+  // list prices from the cache only — read once per call, not per section
   const prices = loadPrices();
 
   if (args.json === true) {

package/src/mcp/tools/verdict.ts

@@ -79,22 +79,35 @@ export function toolVerdictSubmit(args: Record<string, unknown>): ToolResult {
         : "mcp-external";
     const resolvedPlan =
       typeof plan === "string" && plan ? plan.trim().toLowerCase() : null;
-    let open = resolvedPlan
-      ? findOpenRun(db, resolvedWorktree, resolvedPlan)
-      : null;
-    // Fallback: if no exact match and plan is non-null, try any open run with
-    // plan=null.  This lets a verdict with free-text intent bind to a run that
-    // was created without a plan (the common "no PLAN file" flow).
-    if (!open && resolvedPlan) {
-      open = findOpenRunWithNullPlan(db, resolvedWorktree);
-    }
-    if (open) {
-      resolvedRunId = open.id;
-    } else {
-      // worktree/plan let callers (e.g. move-to-done) attribute the verdict
-      // so byReasonCode/bestPassing aggregate correctly instead of collapsing
-      // into "mcp-external".
-      resolvedRunId = newRun(db, resolvedWorktree, resolvedPlan, null, "mcp");
+    // BEGIN IMMEDIATE makes the find-then-create below atomic across
+    // concurrent MCP processes: without it, two agents closing the same
+    // worktree+plan at once can both see "no open run" and each insert a
+    // row. The write lock taken here blocks (busy_timeout, not throws) the
+    // second caller until the first commits, so it re-reads and finds the
+    // row already there instead of duplicating it.
+    db.run("BEGIN IMMEDIATE");
+    try {
+      let open = resolvedPlan
+        ? findOpenRun(db, resolvedWorktree, resolvedPlan)
+        : null;
+      // Fallback: if no exact match and plan is non-null, try any open run with
+      // plan=null.  This lets a verdict with free-text intent bind to a run that
+      // was created without a plan (the common "no PLAN file" flow).
+      if (!open && resolvedPlan) {
+        open = findOpenRunWithNullPlan(db, resolvedWorktree);
+      }
+      if (open) {
+        resolvedRunId = open.id;
+      } else {
+        // worktree/plan let callers (e.g. move-to-done) attribute the verdict
+        // so byReasonCode/bestPassing aggregate correctly instead of collapsing
+        // into "mcp-external".
+        resolvedRunId = newRun(db, resolvedWorktree, resolvedPlan, null, "mcp");
+      }
+      db.run("COMMIT");
+    } catch (e) {
+      db.run("ROLLBACK");
+      throw e;
     }
   }
 

package/src/mcp/transport.ts

@@ -112,7 +112,7 @@ function writeStatuslineCache(toolResult: ToolResult): void {
 
 const MCP_PROTOCOL_VERSION = "2025-03-26";
 const SERVER_NAME = "fapony-handcheck";
-const SERVER_VERSION = "0.1.0";
+const SERVER_VERSION = "0.1.3";
 
 // --- JSON-RPC dispatch ---