fapony 0.3.6 → 0.4.0

package/README.md

@@ -38,26 +38,9 @@ quietly counted as free.
 
 That is day one. Past that, fapony keeps what coding agents actually did — the frozen
 ledger of graded runs (rounds, pass/fail, cost per grade, readable via CLI, no new grades)
-plus the live mem log — through 3 MCP tools any agent can call. If you juggle more than
-one agent, this is the point: the numbers come from the same yardstick everywhere, so
-"which model earns its keep on which kind of task" becomes a data question instead of a
-vibe. On top of history it checks claims against git facts: handoff conformance and
-allowlisted evidence — with everything the agent claimed but couldn't prove marked as such.
-
-**What that question looks like answered, from one project's own (frozen — reads history,
-no new grades) ledger — the top of the `n≥5` frontier (`fapony stats --mode verdict --regime code`):**
-
-| model | tokens/pass | quality | n |
-|---|---|---|---|
-| `claude-opus-5` | 22.5M | 3.8 | 10 |
-| `claude-sonnet-5` | 5.6M | 3.5 | 11 |
-| `muse-spark-1.3-contributor-free` | 4.3M | 4.0 | 5 |
-
-Same quality band, an 8× token spread — the kind of answer a session log can't give (it has tokens,
-no grades) and a benchmark can't give either (it has grades, not your codebase). One caveat that's
-on you to hold: work isn't randomly assigned to models, so a gap this size is a strong prior, not a
-controlled trial — you likely route easy tasks to the cheap model already. `n≥5` is fapony's own
-floor before a model counts toward the frontier at all; below that it's a data point, not a pick.
+plus the live mem log — through 3 MCP tools any agent can call. It checks claims against
+git facts: handoff conformance and allowlisted evidence — with everything the agent claimed
+but couldn't prove marked as such.
 
 **The reason to keep it running is the third layer: knowledge accumulation — and the thing it
 accumulates is pain.** An agent has no memory of pain across sessions: it writes the 37th
@@ -72,7 +55,7 @@ already decided on, that is the loop: notice the repeated cost, name the shared
 migration finish. Finding dead code and duplication is *not* part of it — knip and friends already
 do that better, and a convention with a `checker` is deliberately left to the checker.
 
-**The measurement layer underneath it:** Any single client already logs its own session — timing, tokens, tool calls. What none of them see is *across* runs, clients and task shapes: which model earns its keep on which kind of work **in this project**, at what token cost. The frozen ledger still answers that from history — every old verdict carries a `regime` (`code` / `fix` / `review` / `plan` / `inquiry` / `test`), and runs split by whether there was a plan at all — so "does planning beat diving in, and for which model" stays a table, not an argument. New accumulation goes to the mem log instead: decisions, bugs and notes with `files[]`, written by the agents doing the work.
+**The measurement layer underneath it:** Any single client already logs its own session — timing, tokens, tool calls. What none of them see is *across* runs, clients and task shapes: what each model costs you, across clients, on one yardstick, in this project (`fapony usage-web`, above) — tokens and cost, nothing self-graded. The frozen ledger still has old verdict rows (`fapony stats`), but the tool that wrote them (`verdict_submit`) is gone from the MCP surface: no new rows, for anyone, ever again, so a count of old rows (`n`) means nothing without the grading that stopped. New accumulation goes to the mem log instead: decisions, bugs and notes with `files[]`, written by the agents doing the work.
 
 Three tiers, deliberately: **measurement ships today** and needs no per-project setup — raw facts nobody can call unfair. **Verification is the sharper edge** but stays beta until its evidence layer is hardened; fapony doesn't control your agent's flow, so it never promises "verified" as a headline. **Knowledge accumulation is the compounding one** — it's worthless on run 1 and gets more useful every run after, which is exactly why it's the layer competitors can't clone by copying a feature list.
 
@@ -381,6 +364,12 @@ at once. ZCode and Codex get the same skills linked into `~/.agents/skills`. A d
 that already exists and isn't a fapony link is reported and left alone — replace it by hand
 if you want fapony's version.
 
+OpenCode is the one client whose hooks are generated files rather than `fapony hook-*`
+commands, so `fapony update` also re-runs the installer in a fresh process to refresh them —
+with `--plugins-only`, so a refresh touches fapony's plugin files and never your
+`opencode.json`. A fapony-owned plugin is rewritten in place; a file that isn't fapony's is
+reported and left alone, same as the skill links.
+
 `plan-with-pony` is vendor-neutral — the SKILL.md *is* the prompt, so pipe it to any agent:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "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)",
@@ -35,6 +35,7 @@
     "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",
+    "release:minor": "git checkout main && git pull --ff-only && npm version minor -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"
   },
   "devDependencies": {

package/src/install/opencode.ts

@@ -2,7 +2,13 @@
 //
 // Adds mcp.fapony config to ~/.config/opencode/opencode.json or opencode.jsonc.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { claudeSkillsDir, linkSkills, reportSkills } from "./skills.js";
@@ -84,6 +90,11 @@ function isConfigured(mcp: Record<string, unknown> | undefined): boolean {
 export interface OpencodeInstallOpts {
   /** Opt-in only: write the git-autonomy rewrite plugin. Never default. */
   gitAutonomy?: boolean;
+  /** Refresh only the generated plugin bodies — skip the opencode.json write
+   *  and the skills symlink entirely. This is `fapony update`'s post-pull
+   *  refresh: it must touch only fapony-owned plugin files, never the user's
+   *  config (rule 6c — overwriting what exists = ask first, or refuse). */
+  pluginsOnly?: boolean;
 }
 
 export function cmdInstallOpencode(
@@ -94,6 +105,21 @@ export function cmdInstallOpencode(
   const exitFn = deps.exit ?? defaultExit;
   const getHome = deps.homedir ?? homedir;
 
+  const installPlugins = (): void => {
+    installReadHintPlugin(dryRun, getHome);
+    installCommitHintPlugin(dryRun, getHome);
+    installEditHintPlugin(dryRun, getHome);
+    installSessionStartPlugin(dryRun, getHome);
+    if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+  };
+
+  // Refresh path: plugin bodies only — returns before findOpencodeConfig, so
+  // neither opencode.json nor the skills symlink is read or written.
+  if (opts.pluginsOnly) {
+    installPlugins();
+    return;
+  }
+
   const configPath = findOpencodeConfig(getHome);
   let before: Record<string, unknown>;
   let isNew = false;
@@ -117,11 +143,7 @@ export function cmdInstallOpencode(
     if (configPath) console.error(`  (${configPath})`);
     const skillsDir = claudeSkillsDir(getHome);
     reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
-    installReadHintPlugin(dryRun, getHome);
-    installCommitHintPlugin(dryRun, getHome);
-    installEditHintPlugin(dryRun, getHome);
-    installSessionStartPlugin(dryRun, getHome);
-    if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+    installPlugins();
     return;
   }
 
@@ -143,11 +165,7 @@ export function cmdInstallOpencode(
       console.error(`  (${configPath})`);
     }
     console.log(computeDiff(before, after));
-    installReadHintPlugin(dryRun, getHome);
-    installCommitHintPlugin(dryRun, getHome);
-    installEditHintPlugin(dryRun, getHome);
-    installSessionStartPlugin(dryRun, getHome);
-    if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+    installPlugins();
     return;
   }
 
@@ -167,11 +185,7 @@ export function cmdInstallOpencode(
   console.error(`  restart opencode to load the MCP server`);
   const skillsDir = claudeSkillsDir(getHome);
   reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
-  installReadHintPlugin(dryRun, getHome);
-  installCommitHintPlugin(dryRun, getHome);
-  installEditHintPlugin(dryRun, getHome);
-  installSessionStartPlugin(dryRun, getHome);
-  if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+  installPlugins();
 }
 
 /**
@@ -412,102 +426,102 @@ export const FaponyEditHint = async ({ directory }) => {
 `;
 }
 
-function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
+/**
+ * Write one generated OpenCode plugin file, refreshing our own older copy.
+ *
+ * Ownership is the exported plugin name (`FaponyReadHint`, …) — the one token
+ * every generated body carries. A file without it is someone's own plugin and
+ * is never touched, same rule as the skill symlinks. A file *with* it but
+ * different content is ours and stale: the plugin body is baked at install
+ * time, so a `git pull` updates the imported logic (src/hook.ts) but never this
+ * file. Refusing to overwrite it is how an old hook stays reachable forever —
+ * the Thai-only bug marker survived exactly that way — so ours gets rewritten
+ * in place, and only a foreign file is reported and left alone.
+ */
+function installPluginFile(
+  dryRun: boolean,
+  getHome: () => string,
+  fileName: string,
+  label: string,
+  ownedName: string,
+  desired: string,
+): void {
   const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-read-hint.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
+  const pluginPath = join(pluginsDir, fileName);
+  const write = (): boolean => {
+    if (dryRun) return true;
     try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
+      mkdirSync(pluginsDir, { recursive: true });
+      writeFileSync(pluginPath, desired, "utf-8");
+      return true;
+    } catch (e) {
+      console.error(`  ${label}: failed to write — ${(e as Error).message}`);
+      return false;
     }
-    if (current.includes("readHintFor")) {
-      console.error(`  read hint: already installed — no change`);
-      return;
+  };
+
+  if (!existsSync(pluginPath)) {
+    if (write()) {
+      console.error(
+        `  ${label}: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+      );
     }
+    return;
+  }
+
+  let current = "";
+  try {
+    current = readFileSync(pluginPath, "utf-8");
+  } catch {
+    current = "";
+  }
+  if (current === desired) {
+    console.error(`  ${label}: already installed — no change`);
+    return;
+  }
+  if (!current.includes(ownedName)) {
     console.error(
-      `  read hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+      `  ${label}: ${pluginPath} exists but isn't fapony's — not overwriting.`,
     );
     return;
   }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(pluginPath, readHintPluginSource(INSTALL_ROOT), "utf-8");
-    } catch (e) {
-      console.error(`  read hint: failed to write — ${(e as Error).message}`);
-      return;
-    }
+  if (write()) {
+    console.error(
+      `  ${label}: ${dryRun ? "would update" : "updated"} ${pluginPath}`,
+    );
   }
-  console.error(
-    `  read hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+}
+
+function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-read-hint.ts",
+    "read hint",
+    "FaponyReadHint",
+    readHintPluginSource(INSTALL_ROOT),
   );
 }
 
 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}`,
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-commit-hint.ts",
+    "commit hint",
+    "FaponyCommitHint",
+    commitHintPluginSource(INSTALL_ROOT),
   );
 }
 
 function installEditHintPlugin(dryRun: boolean, getHome: () => string): void {
-  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-edit-hint.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
-    try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
-    }
-    if (current.includes("editHintFor")) {
-      console.error(`  edit hint: already installed — no change`);
-      return;
-    }
-    console.error(
-      `  edit hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
-    );
-    return;
-  }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(pluginPath, editHintPluginSource(INSTALL_ROOT), "utf-8");
-    } catch (e) {
-      console.error(`  edit hint: failed to write — ${(e as Error).message}`);
-      return;
-    }
-  }
-  console.error(
-    `  edit hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-edit-hint.ts",
+    "edit hint",
+    "FaponyEditHint",
+    editHintPluginSource(INSTALL_ROOT),
   );
 }
 
@@ -571,50 +585,13 @@ function installSessionStartPlugin(
   dryRun: boolean,
   getHome: () => string,
 ): void {
-  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-session-start.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
-    try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
-    }
-    if (current.includes("FaponySessionStart")) {
-      // Ours — and generated, so never overwritten. A file baked by an older
-      // fapony differs from what we generate now: say so instead of "no change",
-      // which is how the pre-hook plugin (mub2ezhi) would have been kept.
-      if (current !== sessionStartPluginSource(INSTALL_ROOT)) {
-        console.error(
-          `  session start: stale fapony plugin — delete ${pluginPath} and re-run install`,
-        );
-        return;
-      }
-      console.error(`  session start: already installed — no change`);
-      return;
-    }
-    console.error(
-      `  session start: ${pluginPath} exists but isn't fapony's — not overwriting.`,
-    );
-    return;
-  }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(
-        pluginPath,
-        sessionStartPluginSource(INSTALL_ROOT),
-        "utf-8",
-      );
-    } catch (e) {
-      console.error(
-        `  session start: failed to write — ${(e as Error).message}`,
-      );
-      return;
-    }
-  }
-  console.error(
-    `  session start: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-session-start.ts",
+    "session start",
+    "FaponySessionStart",
+    sessionStartPluginSource(INSTALL_ROOT),
   );
 }
 
@@ -680,45 +657,27 @@ function installGitAutonomyPlugin(
   dryRun: boolean,
   getHome: () => string,
 ): void {
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-git-autonomy.ts",
+    "git-autonomy",
+    "FaponyGitAutonomy",
+    gitAutonomyPluginSource(INSTALL_ROOT),
+  );
+}
+
+/** The fapony-generated plugin files present in an OpenCode install. Empty =
+ *  OpenCode has none, so `fapony update` must not install into a client the user
+ *  never opted into. Callers also use it to tell whether the opt-in git-autonomy
+ *  plugin is installed, so an update can refresh it without ever creating it. */
+export function opencodePluginFiles(getHome: () => string = homedir): string[] {
   const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-git-autonomy.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
-    try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
-    }
-    if (current.includes("FaponyGitAutonomy")) {
-      // Ours — and generated, so never overwritten. Same stale-check shape
-      // as the session-start plugin: an older generation must say so instead
-      // of "no change", or a fixed rewrite never reaches the client.
-      if (current !== gitAutonomyPluginSource(INSTALL_ROOT)) {
-        console.error(
-          `  git-autonomy: stale fapony plugin — delete ${pluginPath} and re-run install --git-autonomy`,
-        );
-        return;
-      }
-      console.error(`  git-autonomy: already installed — no change`);
-      return;
-    }
-    console.error(
-      `  git-autonomy: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+  try {
+    return readdirSync(pluginsDir).filter(
+      (f) => f.startsWith("fapony-") && f.endsWith(".ts"),
     );
-    return;
+  } catch {
+    return [];
   }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(pluginPath, gitAutonomyPluginSource(INSTALL_ROOT), "utf-8");
-    } catch (e) {
-      console.error(
-        `  git-autonomy: failed to write — ${(e as Error).message}`,
-      );
-      return;
-    }
-  }
-  console.error(
-    `  git-autonomy: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
-  );
 }

package/src/install.ts

@@ -39,7 +39,9 @@ export {
   editHintPluginSource,
   gitAutonomyPluginSource,
   type OpencodeInstallOpts,
+  opencodePluginFiles,
   readHintPluginSource,
+  sessionStartPluginSource,
 } from "./install/opencode.js";
 export {
   agentsSkillsDir,
@@ -64,6 +66,8 @@ export async function cmdInstall(
   // not a utility — never installed unless this flag rides along, including
   // via --all. Opencode-only; other platforms ignore it.
   const gitAutonomy = args.includes("--git-autonomy");
+  // Refresh-only seam for `fapony update`: plugin bodies, never opencode.json.
+  const pluginsOnly = args.includes("--plugins-only");
 
   // --- explicit platform: original behavior, unchanged ---
   if (platform === "antigravity") {
@@ -87,12 +91,12 @@ export async function cmdInstall(
     return;
   }
   if (platform === "opencode") {
-    cmdInstallOpencode(dryRun, deps, { gitAutonomy });
+    cmdInstallOpencode(dryRun, deps, { gitAutonomy, pluginsOnly });
     return;
   }
   if (platform !== undefined) {
     console.error(
-      `usage: fapony install --platform antigravity|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy]`,
+      `usage: fapony install --platform antigravity|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy] [--plugins-only]`,
     );
     console.error(
       `  supported platforms: antigravity, opencode, claude, cursor, zcode, codex`,
@@ -131,7 +135,10 @@ export async function cmdInstall(
   if (installAll) {
     console.error();
     for (const client of found) {
-      installPlatform(client.platform, dryRun, deps, { gitAutonomy });
+      installPlatform(client.platform, dryRun, deps, {
+        gitAutonomy,
+        pluginsOnly,
+      });
     }
     return;
   }
@@ -160,7 +167,10 @@ export async function cmdInstall(
     for (const client of found) {
       const answer = await askFn(`install into ${client.platform}?`, "Y");
       if (isAffirmative(answer)) {
-        installPlatform(client.platform, dryRun, deps, { gitAutonomy });
+        installPlatform(client.platform, dryRun, deps, {
+          gitAutonomy,
+          pluginsOnly,
+        });
       }
     }
   } finally {
@@ -172,7 +182,7 @@ function installPlatform(
   platform: string,
   dryRun: boolean,
   deps: InstallDeps,
-  opts: { gitAutonomy?: boolean } = {},
+  opts: { gitAutonomy?: boolean; pluginsOnly?: boolean } = {},
 ): void {
   switch (platform) {
     case "antigravity":

package/src/update.ts

@@ -2,10 +2,12 @@
 // ROOT must be the repo root: import.meta.dir is src/, one level below it.
 // Shows old → new version, recent commits, and warns if uncommitted changes.
 
-import { execSync } from "node:child_process";
+import { execSync, spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
+import { opencodePluginFiles } from "./install/opencode.js";
 import { isAffirmative } from "./util.js";
 
 /** Repo root (parent of src/) — where package.json and bun.lock live.
@@ -27,12 +29,59 @@ function defaultInstall(): void {
   execSync("bun install", { cwd: ROOT, stdio: "pipe", timeout: 300_000 });
 }
 
+/** argv for the spawned plugin refresh — exported so tests can pin the flags:
+ *  a wrong flag fails silently (the child would just do a full install and
+ *  rewrite opencode.json, the exact bug `--plugins-only` exists to prevent). */
+export function refreshArgv(files: string[]): string[] {
+  const argv = [
+    join(ROOT, "fapony.ts"),
+    "install",
+    "--platform",
+    "opencode",
+    // Plugins only: a refresh touches fapony-owned plugin files, never the
+    // user's opencode.json (rule 6c).
+    "--plugins-only",
+  ];
+  // Opt-in plugin: refresh it when the user installed it, never create it.
+  if (files.includes("fapony-git-autonomy.ts")) argv.push("--git-autonomy");
+  return argv;
+}
+
+/**
+ * Refresh OpenCode's generated plugin bodies after the pull.
+ *
+ * OpenCode is the only client whose hooks are baked files — every other client
+ * writes a `fapony hook-*` command resolved at run time, so a pull alone keeps
+ * them current. Spawning a *fresh* process is the whole point: this one already
+ * loaded the pre-pull templates, so calling the installer in-process would
+ * rewrite the old body — the exact bug this exists to fix. `process.execPath`
+ * is the bun running fapony, so no PATH dependency. Runs `--plugins-only`, so
+ * the refresh never reads or writes opencode.json or the skills symlink.
+ * Best-effort: a refresh must never fail an update.
+ */
+function defaultRefreshPlugins(): void {
+  const getHome = (): string => homedir();
+  const files = opencodePluginFiles(getHome);
+  if (files.length === 0) return;
+  console.log("\n  Refreshing OpenCode plugins...");
+  const r = spawnSync(process.execPath, refreshArgv(files), {
+    stdio: "pipe",
+    timeout: 30_000,
+  });
+  if (r.error || r.status !== 0) {
+    console.log(
+      "  ⚠  plugin refresh failed — run manually: fapony install --platform opencode --plugins-only",
+    );
+  }
+}
+
 /** Minimal seam for cmdUpdate — git runner (map args→result, throws on failure),
- *  prompt, exit, and bun-install. Every field is used by both the default
- *  (production) path and the test path. */
+ *  prompt, exit, bun-install, and the post-pull OpenCode plugin refresh. Every
+ *  field is used by both the default (production) path and the test path. */
 export interface UpdateDeps {
   git?: (args: string) => string;
   install?: () => void;
+  refresh?: () => void;
   prompt?: (question: string, defaultVal?: string) => Promise<string>;
   exit?: (code: number) => never;
 }
@@ -88,6 +137,7 @@ function defaultPrompt(question: string, defaultVal?: string): Promise<string> {
 export async function cmdUpdate(deps: UpdateDeps = {}): Promise<void> {
   const git = deps.git ?? defaultGit;
   const installFn = deps.install ?? defaultInstall;
+  const refreshFn = deps.refresh ?? defaultRefreshPlugins;
   const promptFn = deps.prompt ?? defaultPrompt;
   const exitFn = deps.exit ?? ((code: number): never => process.exit(code));
   const gitQuiet = (args: string): string | null => {
@@ -173,6 +223,10 @@ export async function cmdUpdate(deps: UpdateDeps = {}): Promise<void> {
   // --- show what changed ---
   if (isUpToDate(oldSha, newSha)) {
     console.log(`\n  ✓  Already up to date (${oldVersion} @ ${oldSha}).`);
+    // The repo being current says nothing about the generated plugin bodies —
+    // a user who pulled by hand, or installed before the template changed, is
+    // exactly who needs this. Refresh is a no-op when nothing is stale.
+    refreshFn();
     return;
   }
 
@@ -201,6 +255,9 @@ export async function cmdUpdate(deps: UpdateDeps = {}): Promise<void> {
     }
   }
 
+  // --- refresh generated plugin bodies (after deps — the fresh process needs them) ---
+  refreshFn();
+
   console.log(`
   ┌──────────────────────────────────────────┐
   │  Update complete!                        │