@gethmy/mcp 3.3.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.",
   "publishConfig": {
     "access": "public"
@@ -24,7 +24,8 @@
   },
   "bin": {
     "harmony-mcp": "dist/cli.js",
-    "gethmy-mcp": "dist/cli.js"
+    "gethmy-mcp": "dist/cli.js",
+    "harmony-run-hook": "dist/run-hook-cli.js"
   },
   "files": [
     "dist",
@@ -59,7 +60,7 @@
     "bun": ">=1.0.0"
   },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --target node --external @clack/prompts --external @modelcontextprotocol/sdk --external commander --external hono --external picocolors --external zod && bun build src/api-client.ts src/config.ts src/oauth-refresh.ts --outdir dist/lib --root src --target node --external @clack/prompts --external @modelcontextprotocol/sdk --external commander --external hono --external picocolors --external zod",
+    "build": "rm -rf dist && bun build src/index.ts src/cli.ts src/run-hook-cli.ts --outdir dist --target node --external @clack/prompts --external @modelcontextprotocol/sdk --external commander --external hono --external picocolors --external zod && bun build src/api-client.ts src/config.ts src/oauth-refresh.ts --outdir dist/lib --root src --target node --external @clack/prompts --external @modelcontextprotocol/sdk --external commander --external hono --external picocolors --external zod",
     "build:bun": "bun build src/index.ts src/http.ts src/remote.ts src/cli.ts --outdir dist --target bun",
     "serve:remote": "bun src/remote.ts",
     "dev": "bun --watch src/index.ts",

package/src/api-client.ts

@@ -1213,6 +1213,12 @@ export class HarmonyApiClient {
     data: {
       decision: "continue" | "stop";
       extraTurns: number;
+      /**
+       * Consumption granted with a Continue, in USD (#1058). Optional — an
+       * omitted value makes the daemon fall back to its own configured grant
+       * (`budget.pause.extraBudgetUsd`, else the per-spawn `sdk.maxBudgetUsd`).
+       */
+      extraBudgetUsd?: number;
       message?: string;
     },
   ): Promise<{ id: string; seq: number; createdAt: string }> {
@@ -1232,6 +1238,8 @@ export class HarmonyApiClient {
     decisions: Array<{
       decision: "continue" | "stop";
       extraTurns: number;
+      /** Consumption granted with the Continue, in USD (#1058) — absent on a pre-#1058 row. */
+      extraBudgetUsd?: number;
       message?: string;
       createdAt: string;
     }>;
@@ -1930,9 +1938,19 @@ export class HarmonyApiClient {
     return this.request("GET", `/plans/${planId}`);
   }
 
+  /**
+   * The plan a card belongs to, and the criteria that point back at it from elsewhere.
+   *
+   * `plan`/`tasks` are MEMBERSHIP (`cards.plan_id`). `foreign_criteria` is DELIVERY
+   * (`plan_tasks.card_id`) for the rows where the two disagree — a card in no plan, or a
+   * card in a different one (#1054). It is optional because a harmony-api older than
+   * #1054 does not send it, so a reader must treat its absence as "unknown", never as
+   * "there are none".
+   */
   async getPlanByCardId(cardId: string): Promise<{
     plan: unknown;
     tasks: unknown[];
+    foreign_criteria?: unknown[];
   } | null> {
     return this.request("GET", `/cards/${cardId}/plan`);
   }
@@ -1948,6 +1966,13 @@ export class HarmonyApiClient {
     return this.request("PATCH", `/plans/${planId}`, updates);
   }
 
+  /**
+   * Point a criterion at a card and/or set its status.
+   *
+   * `cardPlanAdopted` reports the second write this route makes (#1054): linking a card
+   * that belongs to no plan also writes `cards.plan_id`, so the two columns cannot drift.
+   * Absent from a harmony-api older than #1054 — read it as "unknown", never as "no".
+   */
   async updatePlanTask(
     planId: string,
     taskId: string,
@@ -1955,7 +1980,7 @@ export class HarmonyApiClient {
       cardId?: string;
       status?: "pending" | "in_progress" | "completed";
     },
-  ): Promise<{ task: unknown }> {
+  ): Promise<{ task: unknown; cardPlanAdopted?: boolean }> {
     return this.request("PATCH", `/plans/${planId}/tasks/${taskId}`, updates);
   }
 

package/src/auto-session.ts

@@ -24,6 +24,7 @@
  */
 
 import type { HarmonyApiClient } from "./api-client.js";
+import { beginHookTimeline, endHookTimeline } from "./run-event-forwarder.js";
 
 /**
  * Status reported for a tracked session. Drives the heartbeat decision: only
@@ -43,6 +44,17 @@ export interface TrackedSession {
   isExplicit: boolean;
   agentIdentifier: string;
   agentName: string;
+  /**
+   * `card_agent_context.id` for this session, when the start endpoint returned
+   * one. Recorded so the session can be PUBLISHED on disk for the `PostToolUse`
+   * hook to find (#874) — a hook is a separate process and cannot read this
+   * map, so the id has to travel through the filesystem.
+   *
+   * Optional because an older API build may return no id, and because a start
+   * that threw is still tracked locally. Absent means "no tool-call rows for
+   * this session", never an error.
+   */
+  agentSessionId?: string;
   /**
    * Last status reported for the session (default `working`). Only `working`
    * sessions are heartbeated by the sweep; see `heartbeatActiveSessions`.
@@ -290,6 +302,7 @@ export async function trackActivity(
   // rather than letting a surviving client walk the run back to life one cooldown
   // later (card #770). An explicit `/hmy` re-run is unaffected — it starts the
   // session by name and only faces the 10-minute #663 window.
+  let agentSessionId: string | undefined;
   try {
     const started = await client.startAgentSession(cardId, {
       agentIdentifier,
@@ -300,6 +313,7 @@ export async function trackActivity(
     // Refused: don't track it locally either, or the sweep would heartbeat a
     // session that does not exist and `checkInactivity` would later "end" it.
     if (started?.session === null) return;
+    agentSessionId = (started?.session as { id?: string } | undefined)?.id;
   } catch {
     // Session start failed (might already have one), still track locally
   }
@@ -311,8 +325,20 @@ export async function trackActivity(
     isExplicit: false,
     agentIdentifier,
     agentName,
+    agentSessionId,
     status: "working",
   });
+
+  // Publish for the `PostToolUse` hook. An auto-session is a real session with
+  // a real timeline, so it gets tool rows for the same reason an explicit one
+  // does. Best-effort by construction — `beginHookTimeline` returns null rather
+  // than throwing, so a failure here cannot break the tool call that triggered
+  // the auto-start.
+  beginHookTimeline({
+    cardId,
+    agentSessionId,
+    getClient: () => client,
+  });
 }
 
 /**
@@ -551,6 +577,13 @@ async function autoEndSession(
   // cardId concurrently; whichever claims it first runs the end + pipeline,
   // the loser bails so endAgentSession / runEndSessionPipeline fire exactly once.
   if (!scope.sessions.delete(cardId)) return;
+  // Drain and unpublish BEFORE the session row is ended — an append to an ended
+  // session is refused, so the tail of the tool log would be lost otherwise.
+  try {
+    await endHookTimeline(cardId);
+  } catch {
+    // Best-effort telemetry; never blocks the end.
+  }
   try {
     await client.endAgentSession(cardId, { status });
   } catch {

package/src/cli.ts

@@ -211,4 +211,108 @@ program
     });
   });
 
+const hook = program
+  .command("hook")
+  .description(
+    "Manage the PostToolUse hook that streams tool calls to a card's run timeline",
+  );
+
+hook
+  .command("install")
+  .description(
+    "Install the hook into ~/.claude/settings.json (the user layer, never a project)",
+  )
+  .action(async () => {
+    // Imported lazily so `serve` — the hot path — does not parse this module.
+    const { installUserHook } = await import("./hook-install.js");
+    const result = installUserHook();
+    if (!result.ok) {
+      console.error(`Could not install the hook: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(
+      result.changed
+        ? `Installed the Harmony PostToolUse hook in ${result.path}`
+        : `The Harmony PostToolUse hook is already installed in ${result.path}`,
+    );
+    console.log(`  command: ${result.command}`);
+    console.log(
+      "\nTool calls from an MCP session will now appear on the card's run timeline.",
+    );
+    console.log(
+      "The user settings layer is deliberate: a daemon run never loads it, so it",
+    );
+    console.log("cannot double-report the stream it already sends itself.");
+  });
+
+hook
+  .command("uninstall")
+  .description("Remove the hook from ~/.claude/settings.json")
+  .action(async () => {
+    const { uninstallUserHook } = await import("./hook-install.js");
+    const result = uninstallUserHook();
+    if (!result.ok) {
+      console.error(`Could not remove the hook: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(
+      result.changed
+        ? `Removed the Harmony PostToolUse hook from ${result.path}`
+        : "The Harmony PostToolUse hook was not installed.",
+    );
+  });
+
+hook
+  .command("status")
+  .description("Report whether the hook is installed, and any live sessions")
+  .action(async () => {
+    const { hookInstallStatus, userSettingsPath } = await import(
+      "./hook-install.js"
+    );
+    const { readPublishedSessions, runStateDir } = await import(
+      "./run-state.js"
+    );
+    const { readFileSync } = await import("node:fs");
+    const path = userSettingsPath();
+    let status = {
+      installed: false,
+      binary: null as string | null,
+      binaryExists: false,
+    };
+    try {
+      status = hookInstallStatus(JSON.parse(readFileSync(path, "utf-8")));
+    } catch {
+      // A missing or corrupt settings file reads as "not installed".
+    }
+    console.log(
+      `Hook: ${status.installed ? "installed" : "not installed"} (${path})`,
+    );
+    if (status.installed && !status.binaryExists) {
+      console.log(
+        `  ! its hook binary is gone: ${status.binary ?? "unparseable command"}`,
+      );
+      console.log(
+        "  The hook is INERT until you re-run `npx @gethmy/mcp hook install`.",
+      );
+      console.log(
+        "  An upgrade or a cleared npx/bunx cache moves the binary; the installed",
+      );
+      console.log(
+        "  command guards its own paths, so nothing errors in the meantime.",
+      );
+    }
+    console.log(`State: ${runStateDir()}`);
+    const sessions = readPublishedSessions();
+    if (sessions.length === 0) {
+      console.log("Live sessions: none");
+      return;
+    }
+    console.log(`Live sessions: ${sessions.length}`);
+    for (const session of sessions) {
+      console.log(
+        `  card ${session.cardId} · session ${session.agentSessionId} · pid ${session.publisherPid} · ${session.cwd}`,
+      );
+    }
+  });
+
 program.parse();

package/src/hook-install.ts

@@ -0,0 +1,388 @@
+/**
+ * Installing the `PostToolUse` hook — and why only into the USER layer (#874).
+ *
+ * ## The project layer is not a preference, it is refused
+ *
+ * `assertNoProjectSandboxOverride` (`packages/harmony-harness/src/run-containment.ts`)
+ * reads a worktree's `.claude/settings.json` and `.claude/settings.local.json`
+ * before every contained spawn and refuses ANY key outside an eight-key inert
+ * allow-list (`$schema`, `cleanupPeriodDays`, `includeCoAuthoredBy`,
+ * `language`, `outputStyle`, `spinnerTipsEnabled`, `theme`, `verbose`).
+ *
+ * `hooks` is not merely missing from that list — it is the key that BROKE the
+ * previous denylist and forced the inversion. A hook block in a run's own
+ * worktree executed as the daemon user, outside the sandbox, and read
+ * `~/.ssh/config` and `~/.harmony-mcp/config.json`. So writing this hook into a
+ * project settings file would throw `ProjectSandboxOverrideError` on every
+ * contained implement run in that repo — it would not degrade, it would stop
+ * the daemon.
+ *
+ * ## The user layer is also what makes it CORRECT
+ *
+ * `implementRunContainment` sets `settingSources: readOnly ? [] : ["project"]`.
+ * `"user"` appears in neither branch. A daemon run therefore never loads
+ * `~/.claude/settings.json` and never fires this hook, while an operator's own
+ * `/hmy` terminal session — which runs under their own settings — does.
+ *
+ * That is the whole of the card's "a daemon run is untouched: still exactly one
+ * stream, no doubled events" criterion, satisfied by construction rather than
+ * by a runtime toggle that could be set wrong. There is no flag to get right,
+ * because the two layers are already disjoint.
+ *
+ * ## Merging, not overwriting
+ *
+ * `~/.claude/settings.json` is the operator's file and usually already has
+ * hooks in it. Every function here merges into a parsed object and leaves
+ * unrelated entries untouched, and the install is idempotent — running it twice
+ * yields one entry, not two. The pure functions are separated from the file I/O
+ * so the merge is table-tested rather than verified by writing to a real home
+ * directory.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * A marker argument the hook binary ignores.
+ *
+ * Identifying our entry by its PATH would be fragile — it differs between a
+ * global npm install, a bunx cache and a dev checkout — so the command carries
+ * a stable sentinel instead. It doubles as a note to whoever reads the settings
+ * file and wonders what the entry is.
+ */
+export const HOOK_MARKER = "--harmony-post-tool-use";
+
+/** Seconds. Generous: the hook does no network I/O, so it should never hit it. */
+const HOOK_TIMEOUT_SECONDS = 10;
+
+/** Matches every tool. The redaction rules, not the matcher, decide what is sent. */
+const HOOK_MATCHER = "*";
+
+interface HookCommandEntry {
+  type?: string;
+  command?: string;
+  timeout?: number;
+}
+
+interface HookMatcherEntry {
+  matcher?: string;
+  hooks?: HookCommandEntry[];
+}
+
+/** `~/.claude/settings.json` — the user layer, never the project layer. */
+export function userSettingsPath(home: string = homedir()): string {
+  return join(home, ".claude", "settings.json");
+}
+
+/**
+ * Absolute path to the hook binary.
+ *
+ * Resolved from this module's own location rather than looked up on `PATH`, for
+ * the reason `harmonyMcpServer` resolves the MCP CLI the same way: a `PATH`
+ * lookup or an `npx` resolution step can find a different install than the one
+ * that wrote the settings entry. The `.ts` fallback is for a dev checkout run
+ * straight from source.
+ */
+export function hookBinaryPath(moduleUrl: string = import.meta.url): string {
+  const here = dirname(fileURLToPath(moduleUrl));
+  const candidates = [
+    // Built package: `bun build src/run-hook-cli.ts --outdir dist`.
+    join(here, "run-hook-cli.js"),
+    join(here, "..", "dist", "run-hook-cli.js"),
+    // Dev checkout running straight from source.
+    join(here, "run-hook-cli.ts"),
+  ];
+  return (
+    candidates.find((path) => existsSync(path)) ?? (candidates[0] as string)
+  );
+}
+
+/**
+ * The exact command string written into the settings file.
+ *
+ * Both absolute paths are pinned deliberately (see `hookBinaryPath`), and both
+ * can go away under the user's feet: an `npx`/`bunx` cache is hash- or
+ * version-scoped, so upgrading `@gethmy/mcp` or clearing the cache moves the
+ * binary, and a Node upgrade through a version manager moves `execPath`. The
+ * entry lives in the USER layer with a `*` matcher, so a bare command would
+ * then fail on every tool call of every session on the machine — `exit 1` with
+ * `Cannot find module`, or `exit 127` with no such file. That is the exact
+ * inverse of this card's "the hook is a no-op — never an error" criterion, and
+ * `hook status` reported `installed` throughout, because it only looked for the
+ * marker.
+ *
+ * So the command guards its own preconditions and exits 0 when either path is
+ * gone. The trailing `|| exit 0` also swallows a non-zero exit from the hook
+ * itself, which is the same promise stated once more at the shell level: this
+ * hook never breaks the tool call it observes. `hook status` reports the stale
+ * path so the user knows to re-run `hook install`.
+ *
+ * This is POSIX shell (`sh -c`), which is what the harness runs a hook command
+ * with on macOS and Linux — the only platforms `~/.claude/settings.json`
+ * installs are supported on.
+ */
+export function hookCommand(
+  binary: string,
+  execPath = process.execPath,
+): string {
+  return `[ -x "${execPath}" ] && [ -f "${binary}" ] && "${execPath}" "${binary}" ${HOOK_MARKER} || exit 0`;
+}
+
+/**
+ * The hook binary an installed command points at, or null.
+ *
+ * Parsed back out of the `[ -f "…" ]` guard `hookCommand` writes. Reading it
+ * from the command string keeps the settings entry to the three keys the
+ * harness's hook schema defines, rather than smuggling a path into a fourth.
+ */
+export function hookCommandBinary(command: string): string | null {
+  const match = /\[ -f "([^"]+)" \]/.exec(command);
+  return match?.[1] ?? null;
+}
+
+/** Is this settings entry ours? */
+function isHarmonyHook(entry: HookCommandEntry | undefined): boolean {
+  return (
+    typeof entry?.command === "string" && entry.command.includes(HOOK_MARKER)
+  );
+}
+
+type Settings = Record<string, unknown>;
+
+/**
+ * Add (or update) the Harmony `PostToolUse` entry in a parsed settings object.
+ *
+ * Idempotent: an existing Harmony entry has its command REPLACED, so upgrading
+ * to a new install path fixes the entry rather than adding a second one that
+ * would double every tool row. Other people's hooks are never touched.
+ */
+export function addHarmonyHook(
+  settings: Settings,
+  command: string,
+): { settings: Settings; changed: boolean } {
+  const next: Settings = { ...settings };
+  const hooks: Record<string, unknown> = {
+    ...((next.hooks as Record<string, unknown>) ?? {}),
+  };
+  const postToolUse: HookMatcherEntry[] = Array.isArray(hooks.PostToolUse)
+    ? [...(hooks.PostToolUse as HookMatcherEntry[])]
+    : [];
+
+  const ours: HookCommandEntry = {
+    type: "command",
+    command,
+    timeout: HOOK_TIMEOUT_SECONDS,
+  };
+
+  let changed = false;
+  let placed = false;
+
+  for (let i = 0; i < postToolUse.length; i++) {
+    const group = postToolUse[i] as HookMatcherEntry;
+    const inner = Array.isArray(group?.hooks) ? group.hooks : [];
+    const index = inner.findIndex(isHarmonyHook);
+    if (index === -1) continue;
+    placed = true;
+    if (inner[index]?.command !== command) {
+      const updated = [...inner];
+      updated[index] = ours;
+      postToolUse[i] = { ...group, hooks: updated };
+      changed = true;
+    }
+  }
+
+  if (!placed) {
+    postToolUse.push({ matcher: HOOK_MATCHER, hooks: [ours] });
+    changed = true;
+  }
+
+  hooks.PostToolUse = postToolUse;
+  next.hooks = hooks;
+  return { settings: next, changed };
+}
+
+/**
+ * Remove the Harmony entry, leaving every other hook alone.
+ *
+ * A matcher group left with no hooks is dropped, and a `PostToolUse` array left
+ * empty is dropped with it, so uninstalling returns the file to the shape it
+ * had before — an empty `"PostToolUse": []` is litter that outlives the reason
+ * for it.
+ */
+export function removeHarmonyHook(settings: Settings): {
+  settings: Settings;
+  changed: boolean;
+} {
+  const hooksValue = settings.hooks;
+  if (hooksValue === null || typeof hooksValue !== "object") {
+    return { settings, changed: false };
+  }
+  const hooks: Record<string, unknown> = {
+    ...(hooksValue as Record<string, unknown>),
+  };
+  if (!Array.isArray(hooks.PostToolUse)) {
+    return { settings, changed: false };
+  }
+
+  let changed = false;
+  const groups: HookMatcherEntry[] = [];
+  for (const group of hooks.PostToolUse as HookMatcherEntry[]) {
+    const inner = Array.isArray(group?.hooks) ? group.hooks : [];
+    const kept = inner.filter((entry) => !isHarmonyHook(entry));
+    if (kept.length !== inner.length) changed = true;
+    if (kept.length === 0 && inner.length > 0) continue;
+    groups.push(
+      kept.length === inner.length ? group : { ...group, hooks: kept },
+    );
+  }
+
+  if (!changed) return { settings, changed: false };
+
+  if (groups.length > 0) {
+    hooks.PostToolUse = groups;
+  } else {
+    delete hooks.PostToolUse;
+  }
+
+  const next: Settings = { ...settings };
+  if (Object.keys(hooks).length > 0) {
+    next.hooks = hooks;
+  } else {
+    delete next.hooks;
+  }
+  return { settings: next, changed: true };
+}
+
+/** Is the Harmony hook present in a parsed settings object? */
+export function hasHarmonyHook(settings: Settings): boolean {
+  return harmonyHookCommand(settings) !== null;
+}
+
+/** The Harmony hook's command string as installed, or null when absent. */
+export function harmonyHookCommand(settings: Settings): string | null {
+  const hooks = settings?.hooks as Record<string, unknown> | undefined;
+  const groups = hooks?.PostToolUse;
+  if (!Array.isArray(groups)) return null;
+  for (const group of groups as HookMatcherEntry[]) {
+    for (const entry of Array.isArray(group?.hooks) ? group.hooks : []) {
+      if (isHarmonyHook(entry)) return entry.command as string;
+    }
+  }
+  return null;
+}
+
+/**
+ * What `hook status` needs to say something true.
+ *
+ * `installed` on its own was misleading: the entry can name a binary that an
+ * upgrade or a cache purge has moved, in which case the hook is inert and only
+ * re-running `hook install` fixes it. The guard in `hookCommand` keeps that
+ * inert rather than broken; this is how the user finds out.
+ */
+export function hookInstallStatus(settings: Settings): {
+  installed: boolean;
+  binary: string | null;
+  binaryExists: boolean;
+} {
+  const command = harmonyHookCommand(settings);
+  if (command === null) {
+    return { installed: false, binary: null, binaryExists: false };
+  }
+  const binary = hookCommandBinary(command);
+  return {
+    installed: true,
+    binary,
+    binaryExists: binary !== null && existsSync(binary),
+  };
+}
+
+function readSettings(path: string): Settings {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed)
+      ? (parsed as Settings)
+      : {};
+  } catch {
+    // A missing file is the common case. A CORRUPT one is not ours to silently
+    // replace, so the callers below check `existsSync` and refuse instead.
+    return {};
+  }
+}
+
+function writeSettings(path: string, settings: Settings): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+}
+
+export type HookInstallResult =
+  | { ok: true; path: string; changed: boolean; command: string }
+  | { ok: false; path: string; error: string };
+
+/** Write the hook into the user settings layer. */
+export function installUserHook(options?: {
+  settingsPath?: string;
+  binary?: string;
+}): HookInstallResult {
+  const path = options?.settingsPath ?? userSettingsPath();
+  const command = hookCommand(options?.binary ?? hookBinaryPath());
+  if (existsSync(path)) {
+    try {
+      JSON.parse(readFileSync(path, "utf-8"));
+    } catch (err) {
+      return {
+        ok: false,
+        path,
+        error: `${path} is not valid JSON, so it was left untouched: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      };
+    }
+  }
+  try {
+    const { settings, changed } = addHarmonyHook(readSettings(path), command);
+    if (changed) writeSettings(path, settings);
+    return { ok: true, path, changed, command };
+  } catch (err) {
+    return {
+      ok: false,
+      path,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/** Remove the hook from the user settings layer. */
+export function uninstallUserHook(options?: {
+  settingsPath?: string;
+}): HookInstallResult {
+  const path = options?.settingsPath ?? userSettingsPath();
+  if (!existsSync(path)) {
+    return { ok: true, path, changed: false, command: "" };
+  }
+  try {
+    JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    return {
+      ok: false,
+      path,
+      error: `${path} is not valid JSON, so it was left untouched: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+  try {
+    const { settings, changed } = removeHarmonyHook(readSettings(path));
+    if (changed) writeSettings(path, settings);
+    return { ok: true, path, changed, command: "" };
+  } catch (err) {
+    return {
+      ok: false,
+      path,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/plan-task-link.ts

@@ -5,7 +5,9 @@
  * has always carried the plan → card direction; `plan_tasks.card_id` is the return leg
  * ("Linked card ID if task has been converted to a card", 20260127100000). It shipped
  * with the table and no client ever wrote it, so a card outcome had nowhere to land and
- * plan progress fell back to matching board-column NAMES (`src/lib/planProgress.ts`).
+ * plan progress fell back to matching board-column NAMES. The number now counts these
+ * criteria instead (`computePlanProgress`, `src/lib/planProgress.ts`, card #1042), so a
+ * criterion left unlinked here is a criterion the plan reports as unmet.
  *
  * Everything here is pure and total, because the interesting cases are the ones a live
  * call cannot cheaply produce: a criterion that belongs to a different plan, a malformed