@gethmy/mcp 3.2.0 → 3.4.0

package/dist/cli.js

@@ -978,6 +978,565 @@ var init_oauth_refresh = __esm(() => {
   init_oauth_login();
 });
 
+// src/run-state.ts
+var exports_run_state = {};
+__export(exports_run_state, {
+  writeSpoolBatch: () => writeSpoolBatch,
+  writeRouteMemo: () => writeRouteMemo,
+  trimSpool: () => trimSpool,
+  spoolDir: () => spoolDir,
+  sessionsDir: () => sessionsDir,
+  runStateExists: () => runStateExists,
+  runStateDir: () => runStateDir,
+  removeSpoolBatches: () => removeSpoolBatches,
+  readSpoolBatches: () => readSpoolBatches,
+  readRouteMemo: () => readRouteMemo,
+  readPublishedSessions: () => readPublishedSessions,
+  publishRunSession: () => publishRunSession,
+  pidIsAlive: () => pidIsAlive,
+  clearRunSession: () => clearRunSession,
+  chooseRunSessionForHook: () => chooseRunSessionForHook,
+  ancestorPids: () => ancestorPids,
+  RUN_STATE_DIR_ENV: () => RUN_STATE_DIR_ENV,
+  MAX_POINTER_AGE_MS: () => MAX_POINTER_AGE_MS
+});
+import { execFileSync } from "node:child_process";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync3,
+  renameSync as renameSync2,
+  rmSync as rmSync3,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join4 } from "node:path";
+function runStateDir(env = process.env) {
+  const override = env[RUN_STATE_DIR_ENV]?.trim();
+  if (override)
+    return override;
+  return join4(homedir2(), ".harmony", "runs");
+}
+function sessionsDir(stateDir) {
+  return join4(stateDir, "sessions");
+}
+function spoolDir(stateDir, agentSessionId) {
+  return join4(stateDir, "spool", sanitizeIdForPath(agentSessionId));
+}
+function sanitizeIdForPath(id) {
+  return id.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 100);
+}
+function pointerFileName(publisherPid, cardId) {
+  return `${publisherPid}.${sanitizeIdForPath(cardId)}.json`;
+}
+function pidIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+function readProcParent(pid) {
+  try {
+    const stat = readFileSync3(`/proc/${pid}/stat`, "utf-8");
+    const tail = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+    const ppid = Number.parseInt(tail[1] ?? "", 10);
+    return Number.isInteger(ppid) && ppid > 0 ? ppid : null;
+  } catch {
+    return null;
+  }
+}
+function psParentTable() {
+  if (psTableCache)
+    return psTableCache;
+  const table = new Map;
+  try {
+    const out = execFileSync("ps", ["-Ao", "pid=,ppid="], {
+      encoding: "utf-8",
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    for (const line of out.split(`
+`)) {
+      const match = line.trim().match(/^(\d+)\s+(\d+)$/);
+      if (!match)
+        continue;
+      table.set(Number(match[1]), Number(match[2]));
+    }
+  } catch {}
+  psTableCache = table;
+  return table;
+}
+function ancestorPids(pid, readParent) {
+  const parentOf = readParent ?? ((child) => {
+    const viaProc = readProcParent(child);
+    if (viaProc !== null)
+      return viaProc;
+    return psParentTable().get(child) ?? null;
+  });
+  const chain2 = [];
+  const seen = new Set([pid]);
+  let current = pid;
+  if (!readParent && pid === process.pid) {
+    const ppid = process.ppid;
+    if (Number.isInteger(ppid) && ppid > 1) {
+      chain2.push(ppid);
+      seen.add(ppid);
+      current = ppid;
+    }
+  }
+  for (let depth = chain2.length;depth < MAX_ANCESTOR_DEPTH; depth++) {
+    const parent = parentOf(current);
+    if (parent === null || parent <= 1 || seen.has(parent))
+      break;
+    chain2.push(parent);
+    seen.add(parent);
+    current = parent;
+  }
+  return chain2;
+}
+function publishRunSession(session, options) {
+  const stateDir = options?.stateDir ?? runStateDir();
+  const pid = options?.pid ?? process.pid;
+  const record = {
+    cardId: session.cardId,
+    agentSessionId: session.agentSessionId,
+    publisherPid: pid,
+    ancestorPids: options?.ancestors ?? ancestorPids(pid),
+    cwd: options?.cwd ?? process.cwd(),
+    updatedAt: new Date().toISOString()
+  };
+  try {
+    const dir = sessionsDir(stateDir);
+    mkdirSync3(dir, { recursive: true, mode: 448 });
+    const target = join4(dir, pointerFileName(pid, session.cardId));
+    const temp = `${target}.${process.pid}.tmp`;
+    writeFileSync3(temp, JSON.stringify(record), { mode: 384 });
+    renameSync2(temp, target);
+    return record;
+  } catch {
+    return null;
+  }
+}
+function clearRunSession(cardId, options) {
+  const stateDir = options?.stateDir ?? runStateDir();
+  const pid = options?.pid ?? process.pid;
+  if (!options?.keepPointer) {
+    try {
+      unlinkSync(join4(sessionsDir(stateDir), pointerFileName(pid, cardId)));
+    } catch {}
+  }
+  if (options?.agentSessionId) {
+    try {
+      rmSync3(spoolDir(stateDir, options.agentSessionId), {
+        recursive: true,
+        force: true
+      });
+    } catch {}
+  }
+}
+function readPublishedSessions(options) {
+  const stateDir = options?.stateDir ?? runStateDir();
+  const now = options?.now ?? Date.now();
+  const dir = sessionsDir(stateDir);
+  let names;
+  try {
+    names = readdirSync2(dir);
+  } catch {
+    return [];
+  }
+  const live = [];
+  for (const name of names) {
+    if (!name.endsWith(".json"))
+      continue;
+    const path = join4(dir, name);
+    let record;
+    try {
+      record = JSON.parse(readFileSync3(path, "utf-8"));
+    } catch {
+      safeUnlink(path);
+      continue;
+    }
+    if (typeof record?.cardId !== "string" || typeof record?.agentSessionId !== "string" || !record.cardId || !record.agentSessionId) {
+      safeUnlink(path);
+      continue;
+    }
+    const age = now - Date.parse(record.updatedAt ?? "");
+    if (!Number.isFinite(age) || age > MAX_POINTER_AGE_MS) {
+      safeUnlink(path);
+      continue;
+    }
+    if (!pidIsAlive(record.publisherPid)) {
+      safeUnlink(path);
+      continue;
+    }
+    live.push({ ...record, ancestorPids: record.ancestorPids ?? [] });
+  }
+  return live;
+}
+function safeUnlink(path) {
+  try {
+    unlinkSync(path);
+  } catch {}
+}
+function chooseRunSessionForHook(args) {
+  const { candidates, hookAncestorPids } = args;
+  if (candidates.length === 0)
+    return null;
+  const hasCwd = typeof args.cwd === "string" && args.cwd.length > 0;
+  const pool = hasCwd ? candidates.filter((candidate) => candidate.cwd === args.cwd) : candidates;
+  if (pool.length === 0)
+    return null;
+  let best = null;
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of pool) {
+    const claimed = new Set([
+      candidate.publisherPid,
+      ...candidate.ancestorPids ?? []
+    ]);
+    let score = Number.POSITIVE_INFINITY;
+    for (let i = 0;i < hookAncestorPids.length; i++) {
+      if (claimed.has(hookAncestorPids[i])) {
+        score = i;
+        break;
+      }
+    }
+    if (score === Number.POSITIVE_INFINITY)
+      continue;
+    if (score < bestScore || score === bestScore && best !== null && Date.parse(candidate.updatedAt) > Date.parse(best.updatedAt)) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+  if (best)
+    return best;
+  if (hasCwd && pool.length === 1)
+    return pool[0];
+  return null;
+}
+function writeSpoolBatch(dir, events, options) {
+  if (events.length === 0)
+    return null;
+  const now = options?.now ?? Date.now();
+  const pid = options?.pid ?? process.pid;
+  const nonce = options?.nonce ?? Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+  try {
+    mkdirSync3(dir, { recursive: true, mode: 448 });
+    const name = `${String(now).padStart(14, "0")}-${pid}-${nonce}.json`;
+    const target = join4(dir, name);
+    const temp = `${target}.tmp`;
+    writeFileSync3(temp, JSON.stringify(events), { mode: 384 });
+    renameSync2(temp, target);
+    return target;
+  } catch {
+    return null;
+  }
+}
+function readSpoolBatches(dir, limit = 200) {
+  let names;
+  try {
+    names = readdirSync2(dir);
+  } catch {
+    return [];
+  }
+  const batches = [];
+  for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+    if (batches.length >= limit)
+      break;
+    const path = join4(dir, name);
+    try {
+      const parsed = JSON.parse(readFileSync3(path, "utf-8"));
+      if (!Array.isArray(parsed)) {
+        safeUnlink(path);
+        continue;
+      }
+      batches.push({ path, events: parsed });
+    } catch {
+      safeUnlink(path);
+    }
+  }
+  return batches;
+}
+function removeSpoolBatches(paths) {
+  for (const path of paths)
+    safeUnlink(path);
+}
+function trimSpool(dir, max) {
+  let names;
+  try {
+    names = readdirSync2(dir).filter((n) => n.endsWith(".json")).sort();
+  } catch {
+    return 0;
+  }
+  if (names.length <= max)
+    return 0;
+  const excess = names.slice(0, names.length - max);
+  for (const name of excess)
+    safeUnlink(join4(dir, name));
+  return excess.length;
+}
+function routeMemoPath(stateDir, harnessSessionId) {
+  return join4(stateDir, "routes", `${sanitizeIdForPath(harnessSessionId)}.json`);
+}
+function readRouteMemo(stateDir, harnessSessionId) {
+  try {
+    const raw = JSON.parse(readFileSync3(routeMemoPath(stateDir, harnessSessionId), "utf-8"));
+    const pid = raw?.publisherPid;
+    const cardId = raw?.cardId;
+    const agentSessionId = raw?.agentSessionId;
+    if (typeof pid !== "number" || !Number.isInteger(pid))
+      return null;
+    if (typeof cardId !== "string" || cardId.length === 0)
+      return null;
+    if (typeof agentSessionId !== "string" || agentSessionId.length === 0) {
+      return null;
+    }
+    return { publisherPid: pid, cardId, agentSessionId };
+  } catch {
+    return null;
+  }
+}
+function writeRouteMemo(stateDir, harnessSessionId, memo) {
+  try {
+    const path = routeMemoPath(stateDir, harnessSessionId);
+    mkdirSync3(join4(stateDir, "routes"), { recursive: true, mode: 448 });
+    writeFileSync3(path, JSON.stringify({
+      publisherPid: memo.publisherPid,
+      cardId: memo.cardId,
+      agentSessionId: memo.agentSessionId
+    }), { mode: 384 });
+  } catch {}
+}
+function runStateExists(stateDir = runStateDir()) {
+  try {
+    return existsSync3(sessionsDir(stateDir)) && statSync2(sessionsDir(stateDir)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+var RUN_STATE_DIR_ENV = "HARMONY_RUN_STATE_DIR", MAX_POINTER_AGE_MS, MAX_ANCESTOR_DEPTH = 12, psTableCache = null;
+var init_run_state = __esm(() => {
+  MAX_POINTER_AGE_MS = 10 * 60000;
+});
+
+// src/hook-install.ts
+var exports_hook_install = {};
+__export(exports_hook_install, {
+  userSettingsPath: () => userSettingsPath,
+  uninstallUserHook: () => uninstallUserHook,
+  removeHarmonyHook: () => removeHarmonyHook,
+  installUserHook: () => installUserHook,
+  hookInstallStatus: () => hookInstallStatus,
+  hookCommandBinary: () => hookCommandBinary,
+  hookCommand: () => hookCommand,
+  hookBinaryPath: () => hookBinaryPath,
+  hasHarmonyHook: () => hasHarmonyHook,
+  harmonyHookCommand: () => harmonyHookCommand,
+  addHarmonyHook: () => addHarmonyHook,
+  HOOK_MARKER: () => HOOK_MARKER
+});
+import { existsSync as existsSync10, mkdirSync as mkdirSync7, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
+import { dirname as dirname5, join as join10 } from "node:path";
+import { fileURLToPath } from "node:url";
+function userSettingsPath(home = homedir8()) {
+  return join10(home, ".claude", "settings.json");
+}
+function hookBinaryPath(moduleUrl = import.meta.url) {
+  const here = dirname5(fileURLToPath(moduleUrl));
+  const candidates = [
+    join10(here, "run-hook-cli.js"),
+    join10(here, "..", "dist", "run-hook-cli.js"),
+    join10(here, "run-hook-cli.ts")
+  ];
+  return candidates.find((path) => existsSync10(path)) ?? candidates[0];
+}
+function hookCommand(binary, execPath = process.execPath) {
+  return `[ -x "${execPath}" ] && [ -f "${binary}" ] && "${execPath}" "${binary}" ${HOOK_MARKER} || exit 0`;
+}
+function hookCommandBinary(command) {
+  const match = /\[ -f "([^"]+)" \]/.exec(command);
+  return match?.[1] ?? null;
+}
+function isHarmonyHook(entry) {
+  return typeof entry?.command === "string" && entry.command.includes(HOOK_MARKER);
+}
+function addHarmonyHook(settings, command) {
+  const next = { ...settings };
+  const hooks = {
+    ...next.hooks ?? {}
+  };
+  const postToolUse = Array.isArray(hooks.PostToolUse) ? [...hooks.PostToolUse] : [];
+  const ours = {
+    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];
+    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 };
+}
+function removeHarmonyHook(settings) {
+  const hooksValue = settings.hooks;
+  if (hooksValue === null || typeof hooksValue !== "object") {
+    return { settings, changed: false };
+  }
+  const hooks = {
+    ...hooksValue
+  };
+  if (!Array.isArray(hooks.PostToolUse)) {
+    return { settings, changed: false };
+  }
+  let changed = false;
+  const groups = [];
+  for (const group of hooks.PostToolUse) {
+    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 };
+  if (Object.keys(hooks).length > 0) {
+    next.hooks = hooks;
+  } else {
+    delete next.hooks;
+  }
+  return { settings: next, changed: true };
+}
+function hasHarmonyHook(settings) {
+  return harmonyHookCommand(settings) !== null;
+}
+function harmonyHookCommand(settings) {
+  const hooks = settings?.hooks;
+  const groups = hooks?.PostToolUse;
+  if (!Array.isArray(groups))
+    return null;
+  for (const group of groups) {
+    for (const entry of Array.isArray(group?.hooks) ? group.hooks : []) {
+      if (isHarmonyHook(entry))
+        return entry.command;
+    }
+  }
+  return null;
+}
+function hookInstallStatus(settings) {
+  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 && existsSync10(binary)
+  };
+}
+function readSettings(path) {
+  try {
+    const parsed = JSON.parse(readFileSync8(path, "utf-8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function writeSettings(path, settings) {
+  mkdirSync7(dirname5(path), { recursive: true });
+  writeFileSync6(path, `${JSON.stringify(settings, null, 2)}
+`, "utf-8");
+}
+function installUserHook(options) {
+  const path = options?.settingsPath ?? userSettingsPath();
+  const command = hookCommand(options?.binary ?? hookBinaryPath());
+  if (existsSync10(path)) {
+    try {
+      JSON.parse(readFileSync8(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)
+    };
+  }
+}
+function uninstallUserHook(options) {
+  const path = options?.settingsPath ?? userSettingsPath();
+  if (!existsSync10(path)) {
+    return { ok: true, path, changed: false, command: "" };
+  }
+  try {
+    JSON.parse(readFileSync8(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)
+    };
+  }
+}
+var HOOK_MARKER = "--harmony-post-tool-use", HOOK_TIMEOUT_SECONDS = 10, HOOK_MATCHER = "*";
+var init_hook_install = () => {};
+
 // src/cli.ts
 init_config();
 import { createRequire as createRequire2 } from "node:module";
@@ -1389,7 +1948,6 @@ var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
 var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
-var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
 var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
@@ -2617,6 +3175,9 @@ ${untrustedDataBlock(planContent.trim(), {
   async updatePlaybook(playbookId, updates) {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
+  async deletePlaybook(playbookId) {
+    return this.request("DELETE", `/playbooks/${encodeURIComponent(playbookId)}`);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -2644,6 +3205,222 @@ function resetClient() {
   client2 = null;
 }
 
+// src/comment-session.ts
+var RUN_SESSION_CARD_ENV = "HARMONY_AGENT_CARD_ID";
+var RUN_SESSION_ID_ENV = "HARMONY_AGENT_SESSION_ID";
+function readDeclaredRunSession(env = process.env) {
+  const cardId = env[RUN_SESSION_CARD_ENV]?.trim();
+  const agentSessionId = env[RUN_SESSION_ID_ENV]?.trim();
+  if (!cardId || !agentSessionId)
+    return null;
+  return { cardId, agentSessionId };
+}
+function chooseCommentSession(args) {
+  const tracked = args.tracked;
+  if (tracked?.agentSessionId && tracked.scopeId === args.callerScopeId) {
+    return {
+      kind: "session",
+      agentSessionId: tracked.agentSessionId,
+      source: "tracked"
+    };
+  }
+  const declared = args.declared;
+  if (declared && declared.cardId === args.cardId) {
+    return {
+      kind: "session",
+      agentSessionId: declared.agentSessionId,
+      source: "declared"
+    };
+  }
+  return { kind: "sessionless" };
+}
+
+// src/run-event-forwarder.ts
+init_run_state();
+var FLUSH_INTERVAL_MS = 2000;
+var MAX_INTERVAL_MS = 60000;
+var MAX_EVENTS_PER_REQUEST = 500;
+var MAX_BATCHES_PER_FLUSH = 200;
+var MAX_BATCH_ATTEMPTS = 20;
+var POINTER_REFRESH_MS = 60000;
+
+class RunEventForwarder {
+  cardId;
+  agentSessionId;
+  getClient;
+  stateDir;
+  baseIntervalMs;
+  timer = null;
+  flushing = false;
+  stopped = false;
+  consecutiveFailures = 0;
+  lastPointerRefresh = Date.now();
+  attempts = new Map;
+  constructor(options) {
+    this.cardId = options.cardId;
+    this.agentSessionId = options.agentSessionId;
+    this.getClient = options.getClient;
+    this.stateDir = options.stateDir ?? runStateDir();
+    this.baseIntervalMs = options.intervalMs ?? FLUSH_INTERVAL_MS;
+  }
+  get dir() {
+    return spoolDir(this.stateDir, this.agentSessionId);
+  }
+  nextDelay() {
+    if (this.consecutiveFailures === 0)
+      return this.baseIntervalMs;
+    const scaled = this.baseIntervalMs * 2 ** Math.min(this.consecutiveFailures, 6);
+    return Math.min(scaled, MAX_INTERVAL_MS);
+  }
+  start() {
+    if (this.timer || this.stopped)
+      return;
+    this.schedule();
+  }
+  schedule() {
+    if (this.stopped)
+      return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.flush().finally(() => this.schedule());
+    }, this.nextDelay());
+    this.timer.unref?.();
+  }
+  async flush() {
+    if (this.flushing)
+      return 0;
+    this.flushing = true;
+    try {
+      this.refreshPointer();
+      const batches = readSpoolBatches(this.dir, MAX_BATCHES_PER_FLUSH);
+      if (batches.length === 0) {
+        this.consecutiveFailures = 0;
+        return 0;
+      }
+      const paths = [];
+      const events = [];
+      for (const batch of batches) {
+        if (events.length > 0 && events.length + batch.events.length > MAX_EVENTS_PER_REQUEST) {
+          break;
+        }
+        paths.push(batch.path);
+        events.push(...batch.events);
+      }
+      if (events.length === 0)
+        return 0;
+      try {
+        await this.getClient().appendAgentRunEvents(this.cardId, {
+          sessionId: this.agentSessionId,
+          events
+        });
+        removeSpoolBatches(paths);
+        for (const path of paths)
+          this.attempts.delete(path);
+        this.consecutiveFailures = 0;
+        return events.length;
+      } catch {
+        this.consecutiveFailures++;
+        const poisoned = [];
+        for (const path of paths) {
+          const next = (this.attempts.get(path) ?? 0) + 1;
+          this.attempts.set(path, next);
+          if (next >= MAX_BATCH_ATTEMPTS)
+            poisoned.push(path);
+        }
+        if (poisoned.length > 0) {
+          removeSpoolBatches(poisoned);
+          for (const path of poisoned)
+            this.attempts.delete(path);
+        }
+        return 0;
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+  refreshPointer() {
+    const now = Date.now();
+    if (now - this.lastPointerRefresh < POINTER_REFRESH_MS)
+      return;
+    this.lastPointerRefresh = now;
+    publishRunSession({ cardId: this.cardId, agentSessionId: this.agentSessionId }, { stateDir: this.stateDir });
+  }
+  async stop(handover) {
+    if (this.stopped)
+      return;
+    this.stopped = true;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    try {
+      await this.flush();
+    } catch {}
+    const handoverTo = handover?.handoverTo;
+    const keepPointer = handoverTo !== undefined;
+    const keepSpool = handoverTo === this.agentSessionId;
+    clearRunSession(this.cardId, {
+      stateDir: this.stateDir,
+      ...keepSpool ? {} : { agentSessionId: this.agentSessionId },
+      ...keepPointer ? { keepPointer: true } : {}
+    });
+  }
+}
+var forwarders = new Map;
+var DISABLE_RUN_HOOK_ENV = "HARMONY_DISABLE_RUN_HOOK";
+function hookTimelineDisabled(env, explicitStateDir) {
+  const off = env[DISABLE_RUN_HOOK_ENV]?.trim().toLowerCase();
+  if (off && off !== "0" && off !== "false")
+    return true;
+  if (env.NODE_ENV === "test" && !explicitStateDir)
+    return true;
+  return false;
+}
+function startRunEventForwarder(options) {
+  const existing = forwarders.get(options.cardId);
+  if (existing)
+    existing.stop({ handoverTo: options.agentSessionId });
+  const forwarder = new RunEventForwarder(options);
+  forwarders.set(options.cardId, forwarder);
+  forwarder.start();
+  return forwarder;
+}
+async function stopRunEventForwarder(cardId) {
+  const forwarder = forwarders.get(cardId);
+  if (!forwarder)
+    return;
+  forwarders.delete(cardId);
+  await forwarder.stop();
+}
+async function stopAllRunEventForwarders() {
+  const all = [...forwarders.values()];
+  forwarders.clear();
+  await Promise.all(all.map((f) => f.stop().catch(() => {
+    return;
+  })));
+}
+function beginHookTimeline(args) {
+  if (!args.agentSessionId)
+    return null;
+  const env = args.env ?? process.env;
+  if (readDeclaredRunSession(env))
+    return null;
+  if (hookTimelineDisabled(env, args.stateDir))
+    return null;
+  const published = publishRunSession({ cardId: args.cardId, agentSessionId: args.agentSessionId }, args.stateDir ? { stateDir: args.stateDir } : undefined);
+  if (!published)
+    return null;
+  return startRunEventForwarder({
+    cardId: args.cardId,
+    agentSessionId: args.agentSessionId,
+    getClient: args.getClient,
+    ...args.stateDir ? { stateDir: args.stateDir } : {}
+  });
+}
+async function endHookTimeline(cardId) {
+  await stopRunEventForwarder(cardId);
+}
+
 // src/auto-session.ts
 var CLIENT_DISPLAY_NAMES = {
   "claude-code": "Claude Code",
@@ -2727,6 +3504,7 @@ async function trackActivity(cardId, options) {
   for (const otherCardId of toEnd) {
     await autoEndSession(scope, client3, otherCardId, "completed");
   }
+  let agentSessionId;
   try {
     const started = await client3.startAgentSession(cardId, {
       agentIdentifier,
@@ -2736,6 +3514,7 @@ async function trackActivity(cardId, options) {
     });
     if (started?.session === null)
       return;
+    agentSessionId = started?.session?.id;
   } catch {}
   scope.sessions.set(cardId, {
     cardId,
@@ -2744,8 +3523,14 @@ async function trackActivity(cardId, options) {
     isExplicit: false,
     agentIdentifier,
     agentName,
+    agentSessionId,
     status: "working"
   });
+  beginHookTimeline({
+    cardId,
+    agentSessionId,
+    getClient: () => client3
+  });
 }
 function markExplicit(cardId, options) {
   const scope = getOrCreateScope(options?.scopeId ?? DEFAULT_SCOPE);
@@ -2846,6 +3631,9 @@ function sweepTick() {
 async function autoEndSession(scope, client3, cardId, status) {
   if (!scope.sessions.delete(cardId))
     return;
+  try {
+    await endHookTimeline(cardId);
+  } catch {}
   try {
     await client3.endAgentSession(cardId, { status });
   } catch {}
@@ -3452,6 +4240,51 @@ async function onboardNewUser(params) {
   };
 }
 
+// src/plan-task-link.ts
+function findPlanTask(tasks, taskId) {
+  if (!taskId) {
+    return { ok: false, reason: "No plan task id was given." };
+  }
+  if (!Array.isArray(tasks)) {
+    return {
+      ok: false,
+      reason: "The plan returned no readable criteria list."
+    };
+  }
+  for (const row of tasks) {
+    if (!row || typeof row !== "object")
+      continue;
+    const candidate = row;
+    if (candidate.id === taskId) {
+      return { ok: true, task: candidate };
+    }
+  }
+  return {
+    ok: false,
+    reason: `Plan task ${taskId} is not one of this plan's criteria. ` + `Read the plan with harmony_get_plan and use an id from its \`tasks\`.`
+  };
+}
+function linkedReport(planId, task, newCardId) {
+  const previous = task.card_id ?? null;
+  return {
+    planId,
+    taskId: task.id,
+    linked: true,
+    criterion: task.content ?? null,
+    ...previous && previous !== newCardId ? { replacedCardId: previous } : {}
+  };
+}
+function unlinkedReport(planId, task, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    planId,
+    taskId: task.id,
+    linked: false,
+    criterion: task.content ?? null,
+    error: `The card was created, but the plan criterion still does not point at it: ${message}. ` + `Repair it with harmony_link_plan_task — do not create the card again.`
+  };
+}
+
 // src/playbook-metric-warnings.ts
 function playbookMetricWarnings(agents, steps) {
   if (!Array.isArray(steps))
@@ -3482,30 +4315,30 @@ async function collectPlaybookMetricWarnings(client3, workspaceId, steps) {
 
 // src/skills.ts
 import {
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync3,
-  readFileSync as readFileSync4,
-  renameSync as renameSync2,
-  writeFileSync as writeFileSync3
+  existsSync as existsSync5,
+  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync5,
+  renameSync as renameSync3,
+  writeFileSync as writeFileSync4
 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { dirname as dirname2, join as join5 } from "node:path";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname2, join as join6 } from "node:path";
 init_config();
 
 // src/hmy-config.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join4 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join5 } from "node:path";
 var DEFAULTS = { updateCheck: true, pin: null };
 function getHmyConfigPath() {
-  return join4(homedir2(), ".hmy", "config.yaml");
+  return join5(homedir3(), ".hmy", "config.yaml");
 }
 function loadHmyConfig() {
   const path = getHmyConfigPath();
-  if (!existsSync3(path))
+  if (!existsSync4(path))
     return { ...DEFAULTS };
   try {
-    return parseHmyConfig(readFileSync3(path, "utf-8"));
+    return parseHmyConfig(readFileSync4(path, "utf-8"));
   } catch {
     return { ...DEFAULTS };
   }
@@ -3637,11 +4470,11 @@ function stripSkillPreamble(content) {
 }
 function atomicWrite(filePath, content) {
   const dir = dirname2(filePath);
-  if (!existsSync4(dir))
-    mkdirSync3(dir, { recursive: true });
+  if (!existsSync5(dir))
+    mkdirSync4(dir, { recursive: true });
   const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-  writeFileSync3(tmp, content);
-  renameSync2(tmp, filePath);
+  writeFileSync4(tmp, content);
+  renameSync3(tmp, filePath);
 }
 function hasMetadataVersion(content) {
   return parseSkillVersion(content) !== null;
@@ -3670,7 +4503,7 @@ function parseSkillVersion(content) {
 function findSkillFiles(paths, knownNames) {
   const results = [];
   for (const filePath of paths) {
-    if (!existsSync4(filePath))
+    if (!existsSync5(filePath))
       continue;
     for (const name of knownNames) {
       if (filePath.includes(`/${name}/`) || filePath.includes(`/${name}.md`)) {
@@ -3681,15 +4514,15 @@ function findSkillFiles(paths, knownNames) {
   }
   return results;
 }
-var HMY_DIR = join5(homedir3(), ".hmy");
-var HMY_VERSION_FILE = join5(HMY_DIR, "VERSION");
-var LAST_CHECK_FILE = join5(HMY_DIR, "last-update-check");
+var HMY_DIR = join6(homedir4(), ".hmy");
+var HMY_VERSION_FILE = join6(HMY_DIR, "VERSION");
+var LAST_CHECK_FILE = join6(HMY_DIR, "last-update-check");
 var CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 function checkedRecently(now = Date.now()) {
   try {
-    if (!existsSync4(LAST_CHECK_FILE))
+    if (!existsSync5(LAST_CHECK_FILE))
       return false;
-    const ts = Number.parseInt(readFileSync4(LAST_CHECK_FILE, "utf-8").trim(), 10);
+    const ts = Number.parseInt(readFileSync5(LAST_CHECK_FILE, "utf-8").trim(), 10);
     if (!Number.isFinite(ts))
       return false;
     return now - ts < CHECK_TTL_MS;
@@ -3699,9 +4532,9 @@ function checkedRecently(now = Date.now()) {
 }
 function recordCheck(now = Date.now()) {
   try {
-    if (!existsSync4(HMY_DIR))
-      mkdirSync3(HMY_DIR, { recursive: true });
-    writeFileSync3(LAST_CHECK_FILE, String(now));
+    if (!existsSync5(HMY_DIR))
+      mkdirSync4(HMY_DIR, { recursive: true });
+    writeFileSync4(LAST_CHECK_FILE, String(now));
   } catch {}
 }
 async function refreshSkills(opts = {}) {
@@ -3733,7 +4566,7 @@ async function refreshSkills(opts = {}) {
           const parentDir = dirname2(samplePath);
           siblingPath = `${parentDir}/${name}.md`;
         }
-        if (existsSync4(siblingPath)) {
+        if (existsSync5(siblingPath)) {
           skillFiles.push({ name, filePath: siblingPath });
         }
       }
@@ -3743,7 +4576,7 @@ async function refreshSkills(opts = {}) {
     let updated = false;
     for (const { name, filePath } of skillFiles) {
       try {
-        const currentContent = readFileSync4(filePath, "utf-8");
+        const currentContent = readFileSync5(filePath, "utf-8");
         const localVersion = parseSkillVersion(currentContent);
         const fetched = await client3.fetchSkill(name);
         const remoteVersion = fetched.skillVersion;
@@ -3949,12 +4782,13 @@ function optionalNonNegativeNumberArg(raw, field) {
     throw new Error(`${field} must be a non-negative number.`);
   return n;
 }
-function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId) {
+function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, scopeId) {
   memorySessions.set(cardId, {
     cardId,
     agentIdentifier,
     agentName,
     agentSessionId,
+    scopeId,
     memoryReadCount: 0,
     pendingActions: [],
     allActions: [],
@@ -4066,6 +4900,10 @@ var TOOLS = {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
         },
+        planTaskId: {
+          type: "string",
+          description: "Id of the plan CRITERION this card is created to fulfil (optional; requires `planId`). " + "Sets both directions at once: the card's plan_id, and the criterion's card_id — the " + "return leg a card outcome needs to reach the plan. Read the ids from harmony_get_plan's " + "`tasks`. A criterion that is not in the named plan refuses the whole call, so no card is " + "created on a false premise; a failure to write the return leg AFTER the card exists " + "keeps the card and reports it in `planTask` instead."
+        },
         attachments: {
           type: "array",
           description: "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " + "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " + "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " + "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " + "harness has written it to a local file you can pass as filePath — a model cannot re-emit " + "pasted image bytes into base64Data. Per-file failures never block card creation; they are " + "reported back in the result's `attachments` array so you can retry via harmony_upload.",
@@ -5543,6 +6381,29 @@ var TOOLS = {
       required: ["planId"]
     }
   },
+  harmony_link_plan_task: {
+    description: "Point a plan CRITERION at the card that fulfils it, and/or set the criterion's status. " + "A plan task is a success criterion, not a work item: `cards.plan_id` says which plan a card " + "belongs to, and this sets the return leg the plan needs to show real progress instead of " + "guessing from board-column names. Use it to repair a link, to re-point a criterion at a " + "different card, or to mark a criterion `completed` once its card actually delivered it. " + "Leave a criterion the card did NOT deliver open — an open criterion is the signal. " + "Linking a card that belongs to no plan yet also adopts it into this one (reported as " + "`cardPlanAdopted`), and linking a card that already belongs to a DIFFERENT plan is " + "refused — move it with harmony_update_card first, so the two directions cannot drift.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "Plan ID owning the criterion" },
+        taskId: {
+          type: "string",
+          description: "Criterion id, from harmony_get_plan's `tasks`. Must belong to `planId`."
+        },
+        cardId: {
+          type: "string",
+          description: "Card that fulfils this criterion. Must live in the plan's own project, and " + "must belong to this plan or to no plan yet — a card already in another plan " + "is refused rather than silently re-pointed."
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "in_progress", "completed"],
+          description: "Criterion status. Set `completed` only when the card demonstrably delivered it."
+        }
+      },
+      required: ["planId", "taskId"]
+    }
+  },
   harmony_list_playbook: {
     description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, and state. Read-only.",
     inputSchema: {
@@ -5637,6 +6498,19 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
+  harmony_delete_playbook: {
+    description: "Permanently delete a playbook. IRREVERSIBLE and cascading: its version snapshots and run history are deleted with it, and every card currently running it is unbound — the card stays on the board and keeps its column, but loses its playbook, its pinned version and its stage pointer, so the agent daemon stops treating it as a stage card. Prefer harmony_update_playbook with state='deprecated' unless the playbook should never have existed: a deprecated playbook stays applicable to in-flight cards and is only hidden from new applies. Requires the playbook's creator or a workspace owner/admin — and an ARMED playbook (triggerType 'auto') takes an owner/admin even from its creator, because removing it stops the workspace's automation for everyone. Anyone else is refused and the playbook is left alone. Returns unboundCardCount (the exact number of cards it unbound) and unboundCards (up to 50 of them by id, short_id, title and the stage each one lost).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to delete (UUID)"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5931,28 +6805,58 @@ async function handleToolCall(name, args, deps) {
         fileName: z.string().optional(),
         contentType: z.string().optional()
       })).parse(args.attachments) : [];
+      const planId = args.planId ? z.string().uuid().parse(args.planId) : undefined;
+      const planTaskId = args.planTaskId ? z.string().uuid().parse(args.planTaskId) : undefined;
+      if (planTaskId && !planId) {
+        throw new Error("planTaskId requires planId: no route resolves a plan from a criterion id alone. " + "Pass the plan the criterion belongs to — harmony_get_plan returns both.");
+      }
+      let criterion;
+      if (planTaskId && planId) {
+        const { tasks } = await client3.getPlan(planId);
+        const found = findPlanTask(tasks, planTaskId);
+        if (!found.ok)
+          throw new Error(found.reason);
+        criterion = found.task;
+      }
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
         description: args.description,
         priority: args.priority,
         assigneeId: args.assigneeId,
-        planId: args.planId
+        planId
       });
+      const newCardId = result.card?.id;
+      let planTask;
+      if (criterion && planId) {
+        if (!newCardId) {
+          planTask = unlinkedReport(planId, criterion, new Error("no card id was returned to link against"));
+        } else {
+          try {
+            await client3.updatePlanTask(planId, criterion.id, {
+              cardId: newCardId
+            });
+            planTask = linkedReport(planId, criterion, newCardId);
+          } catch (err) {
+            planTask = unlinkedReport(planId, criterion, err);
+          }
+        }
+      }
+      const planTaskField = planTask ? { planTask } : {};
       if (attachments.length === 0) {
-        return { success: true, ...result };
+        return { success: true, ...result, ...planTaskField };
       }
-      const cardId = result.card?.id;
-      if (!cardId) {
+      if (!newCardId) {
         return {
           success: true,
           ...result,
+          ...planTaskField,
           attachmentWarning: "Card created, but attachments were skipped: no card id was returned to upload against."
         };
       }
       const attachmentResults = await Promise.all(attachments.map(async (file) => {
         try {
-          const uploaded = await attachFileToCard(client3, cardId, file);
+          const uploaded = await attachFileToCard(client3, newCardId, file);
           return { ok: true, attachment: uploaded.attachment };
         } catch (err) {
           return {
@@ -5962,7 +6866,12 @@ async function handleToolCall(name, args, deps) {
           };
         }
       }));
-      return { success: true, ...result, attachments: attachmentResults };
+      return {
+        success: true,
+        ...result,
+        ...planTaskField,
+        attachments: attachmentResults
+      };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6446,15 +7355,24 @@ ${list}
       const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
       const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
       const replyToId = args.replyToId !== undefined ? z.string().uuid().parse(args.replyToId) : undefined;
-      const agentSessionId = getMemorySession(cardId)?.agentSessionId;
+      const sessionChoice = chooseCommentSession({
+        cardId,
+        tracked: getMemorySession(cardId),
+        callerScopeId: deps.getScopeId?.(),
+        declared: readDeclaredRunSession()
+      });
       const result = await client3.addComment(cardId, body, {
         commentType,
         supersedesId,
         confirmsId,
         replyToId,
-        agentSessionId
+        agentSessionId: sessionChoice.kind === "session" ? sessionChoice.agentSessionId : undefined
       });
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        sessionAttribution: sessionChoice.kind === "session" ? sessionChoice.source : "none"
+      };
     }
     case "harmony_get_comments": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6678,7 +7596,12 @@ ${options}
         scopeId: deps.getScopeId?.()
       });
       const agentSessionId = result.session?.id;
-      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId);
+      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, deps.getScopeId?.());
+      beginHookTimeline({
+        cardId,
+        agentSessionId,
+        getClient: () => client3
+      });
       return {
         success: true,
         assignedTo,
@@ -6740,6 +7663,7 @@ ${options}
       const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
+      await endHookTimeline(cardId);
       let result = {
         session: null
       };
@@ -7349,7 +8273,7 @@ ${options}
       } else if (args.cardId) {
         const cardId = z.string().uuid().parse(args.cardId);
         result = await client3.getPlanByCardId(cardId);
-        if (!result) {
+        if (!result || result.plan == null && !result.foreign_criteria?.length) {
           return {
             success: true,
             plan: null,
@@ -7357,13 +8281,23 @@ ${options}
             message: "No plan linked to this card"
           };
         }
+        if (result.plan == null && result.foreign_criteria?.length) {
+          return {
+            success: true,
+            plan: null,
+            tasks: [],
+            divergentCriteria: result.foreign_criteria ?? [],
+            message: "This card belongs to no plan, but plan criteria point at it. " + "Repair it with harmony_update_card (planId) or harmony_link_plan_task."
+          };
+        }
       } else {
         throw new Error("Either planId or cardId must be provided");
       }
       return {
         success: true,
         plan: result.plan,
-        tasks: result.tasks
+        tasks: result.tasks,
+        ...result.foreign_criteria?.length ? { divergentCriteria: result.foreign_criteria } : {}
       };
     }
     case "harmony_update_plan": {
@@ -7379,6 +8313,34 @@ ${options}
       const result = await client3.updatePlan(planId, updates);
       return { success: true, plan: result.plan };
     }
+    case "harmony_link_plan_task": {
+      const planId = z.string().uuid().parse(args.planId);
+      const taskId = z.string().uuid().parse(args.taskId);
+      const cardId = args.cardId ? z.string().uuid().parse(args.cardId) : undefined;
+      const status = args.status ? z.enum(["pending", "in_progress", "completed"]).parse(args.status) : undefined;
+      if (!cardId && !status) {
+        throw new Error("Nothing to do: pass cardId, status, or both.");
+      }
+      const { tasks } = await client3.getPlan(planId);
+      const found = findPlanTask(tasks, taskId);
+      if (!found.ok)
+        throw new Error(found.reason);
+      const result = await client3.updatePlanTask(planId, taskId, {
+        cardId,
+        status
+      });
+      return {
+        success: true,
+        planTask: {
+          planId,
+          taskId,
+          criterion: found.task.content ?? null,
+          ...cardId ? linkedReport(planId, found.task, cardId) : { linked: found.task.card_id != null },
+          ...cardId && result.cardPlanAdopted ? { cardPlanAdopted: true } : {},
+          ...status ? { status } : {}
+        }
+      };
+    }
     case "harmony_advance_plan": {
       const planId = z.string().uuid().parse(args.planId);
       const summary = args.summary;
@@ -7466,6 +8428,16 @@ ${options}
         ...warnings.length > 0 ? { warnings } : {}
       };
     }
+    case "harmony_delete_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.deletePlaybook(playbookId);
+      return {
+        success: true,
+        playbook: result.playbook,
+        unboundCardCount: result.unboundCardCount,
+        unboundCards: result.unboundCards
+      };
+    }
     case "harmony_save_card_as_playbook":
       return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
     case "harmony_signup": {
@@ -7599,6 +8571,9 @@ class HarmonyMCPServer {
       try {
         await shutdownAllSessions();
       } catch {}
+      try {
+        await stopAllRunEventForwarders();
+      } catch {}
       destroyAutoSession();
       process.exit(exitCode);
     };
@@ -7636,29 +8611,29 @@ class HarmonyMCPServer {
 // src/tui/setup.ts
 import { createHash as createHash5 } from "node:crypto";
 import {
-  existsSync as existsSync8,
+  existsSync as existsSync9,
   lstatSync,
-  mkdirSync as mkdirSync5,
+  mkdirSync as mkdirSync6,
   symlinkSync,
-  unlinkSync
+  unlinkSync as unlinkSync2
 } from "node:fs";
-import { homedir as homedir6 } from "node:os";
-import { dirname as dirname4, join as join8 } from "node:path";
+import { homedir as homedir7 } from "node:os";
+import { dirname as dirname4, join as join9 } from "node:path";
 import * as p4 from "@clack/prompts";
 init_config();
 init_oauth_login();
 
 // src/tui/agents.ts
-import { existsSync as existsSync5 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { join as join6 } from "node:path";
+import { existsSync as existsSync6 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join7 } from "node:path";
 var AGENT_DEFINITIONS = [
   {
     id: "claude",
     name: "Claude Code",
     description: "Anthropic CLI agent",
     hint: "/hmy <card>",
-    globalPaths: [join6(homedir4(), ".claude")],
+    globalPaths: [join7(homedir5(), ".claude")],
     localPaths: [".claude"]
   },
   {
@@ -7666,7 +8641,7 @@ var AGENT_DEFINITIONS = [
     name: "Codex",
     description: "OpenAI coding agent",
     hint: "/prompts:hmy <card>",
-    globalPaths: [join6(homedir4(), ".codex")],
+    globalPaths: [join7(homedir5(), ".codex")],
     localPaths: ["AGENTS.md"]
   },
   {
@@ -7682,20 +8657,20 @@ var AGENT_DEFINITIONS = [
     name: "Windsurf",
     description: "Codeium AI IDE",
     hint: "MCP tools available automatically",
-    globalPaths: [join6(homedir4(), ".codeium", "windsurf")],
+    globalPaths: [join7(homedir5(), ".codeium", "windsurf")],
     localPaths: [".windsurf", ".windsurfrules"]
   }
 ];
 function detectAgents(cwd = process.cwd()) {
   return AGENT_DEFINITIONS.map((def) => {
-    const globalPath = def.globalPaths.find((p) => existsSync5(p)) || null;
-    const localPath = def.localPaths.find((p) => existsSync5(join6(cwd, p))) || null;
+    const globalPath = def.globalPaths.find((p) => existsSync6(p)) || null;
+    const localPath = def.localPaths.find((p) => existsSync6(join7(cwd, p))) || null;
     return {
       id: def.id,
       name: def.name,
       detected: !!(globalPath || localPath),
       globalPath,
-      localPath: localPath ? join6(cwd, localPath) : null,
+      localPath: localPath ? join7(cwd, localPath) : null,
       description: def.description,
       hint: def.hint
     };
@@ -7714,8 +8689,8 @@ async function confirmOrDefault(assumeYes, opts) {
 }
 
 // src/tui/docs.ts
-import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync5, statSync as statSync2 } from "node:fs";
-import { isAbsolute, join as join7, resolve as resolve2, sep as sep2 } from "node:path";
+import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync6, statSync as statSync3 } from "node:fs";
+import { isAbsolute, join as join8, resolve as resolve2, sep as sep2 } from "node:path";
 import * as p2 from "@clack/prompts";
 
 // src/tui/theme.ts
@@ -7802,25 +8777,25 @@ var IGNORED_DIRS = new Set([
 ]);
 function readJson(filePath) {
   try {
-    return JSON.parse(readFileSync5(filePath, "utf-8"));
+    return JSON.parse(readFileSync6(filePath, "utf-8"));
   } catch {
     return null;
   }
 }
 function readText(filePath) {
   try {
-    return readFileSync5(filePath, "utf-8");
+    return readFileSync6(filePath, "utf-8");
   } catch {
     return null;
   }
 }
 function listDirs(dirPath) {
   try {
-    return readdirSync2(dirPath).filter((entry) => {
+    return readdirSync3(dirPath).filter((entry) => {
       if (IGNORED_DIRS.has(entry) || entry.startsWith("."))
         return false;
       try {
-        return statSync2(join7(dirPath, entry)).isDirectory();
+        return statSync3(join8(dirPath, entry)).isDirectory();
       } catch {
         return false;
       }
@@ -7868,25 +8843,25 @@ function describeDir(name) {
 }
 function scanProject(cwd) {
   let packageManager = null;
-  if (existsSync6(join7(cwd, "bun.lock")) || existsSync6(join7(cwd, "bun.lockb"))) {
+  if (existsSync7(join8(cwd, "bun.lock")) || existsSync7(join8(cwd, "bun.lockb"))) {
     packageManager = "bun";
-  } else if (existsSync6(join7(cwd, "pnpm-lock.yaml"))) {
+  } else if (existsSync7(join8(cwd, "pnpm-lock.yaml"))) {
     packageManager = "pnpm";
-  } else if (existsSync6(join7(cwd, "yarn.lock"))) {
+  } else if (existsSync7(join8(cwd, "yarn.lock"))) {
     packageManager = "yarn";
-  } else if (existsSync6(join7(cwd, "package.json"))) {
+  } else if (existsSync7(join8(cwd, "package.json"))) {
     packageManager = "npm";
   }
-  const pkg = readJson(join7(cwd, "package.json"));
+  const pkg = readJson(join8(cwd, "package.json"));
   const scripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null ? pkg.scripts : {};
   let language = "unknown";
-  if (existsSync6(join7(cwd, "tsconfig.json"))) {
+  if (existsSync7(join8(cwd, "tsconfig.json"))) {
     language = "typescript";
-  } else if (existsSync6(join7(cwd, "go.mod"))) {
+  } else if (existsSync7(join8(cwd, "go.mod"))) {
     language = "go";
-  } else if (existsSync6(join7(cwd, "Cargo.toml"))) {
+  } else if (existsSync7(join8(cwd, "Cargo.toml"))) {
     language = "rust";
-  } else if (existsSync6(join7(cwd, "setup.py")) || existsSync6(join7(cwd, "pyproject.toml"))) {
+  } else if (existsSync7(join8(cwd, "setup.py")) || existsSync7(join8(cwd, "pyproject.toml"))) {
     language = "python";
   } else if (pkg) {
     language = "javascript";
@@ -7922,7 +8897,7 @@ function scanProject(cwd) {
     }
   }
   let linter = null;
-  if (existsSync6(join7(cwd, "biome.json")) || existsSync6(join7(cwd, "biome.jsonc"))) {
+  if (existsSync7(join8(cwd, "biome.json")) || existsSync7(join8(cwd, "biome.jsonc"))) {
     linter = "biome";
   } else {
     const eslintFiles = [
@@ -7937,7 +8912,7 @@ function scanProject(cwd) {
       "eslint.config.cjs",
       "eslint.config.ts"
     ];
-    if (eslintFiles.some((f) => existsSync6(join7(cwd, f)))) {
+    if (eslintFiles.some((f) => existsSync7(join8(cwd, f)))) {
       linter = "eslint";
     } else {
       const prettierFiles = [
@@ -7949,13 +8924,13 @@ function scanProject(cwd) {
         "prettier.config.js",
         "prettier.config.mjs"
       ];
-      if (prettierFiles.some((f) => existsSync6(join7(cwd, f)))) {
+      if (prettierFiles.some((f) => existsSync7(join8(cwd, f)))) {
         linter = "prettier";
       }
     }
   }
   let indentStyle = null;
-  const biome = readJson(join7(cwd, "biome.json")) ?? readJson(join7(cwd, "biome.jsonc"));
+  const biome = readJson(join8(cwd, "biome.json")) ?? readJson(join8(cwd, "biome.jsonc"));
   if (biome) {
     const formatter = biome.formatter;
     if (formatter) {
@@ -7965,7 +8940,7 @@ function scanProject(cwd) {
     }
   }
   if (!indentStyle) {
-    const editorConfig = readText(join7(cwd, ".editorconfig"));
+    const editorConfig = readText(join8(cwd, ".editorconfig"));
     if (editorConfig) {
       const styleMatch = editorConfig.match(/indent_style\s*=\s*(space|tab)/);
       const sizeMatch = editorConfig.match(/indent_size\s*=\s*(\d+)/);
@@ -7978,13 +8953,13 @@ function scanProject(cwd) {
     }
   }
   const dirs = listDirs(cwd);
-  const srcDirs = existsSync6(join7(cwd, "src")) ? listDirs(join7(cwd, "src")) : [];
-  const monorepo = existsSync6(join7(cwd, "packages")) || existsSync6(join7(cwd, "apps"));
+  const srcDirs = existsSync7(join8(cwd, "src")) ? listDirs(join8(cwd, "src")) : [];
+  const monorepo = existsSync7(join8(cwd, "packages")) || existsSync7(join8(cwd, "apps"));
   const existingDocs = {
-    agentsMd: existsSync6(join7(cwd, "AGENTS.md")),
-    claudeMd: existsSync6(join7(cwd, "CLAUDE.md")),
-    docsDir: existsSync6(join7(cwd, "docs")),
-    architectureMd: existsSync6(join7(cwd, "docs", "architecture.md"))
+    agentsMd: existsSync7(join8(cwd, "AGENTS.md")),
+    claudeMd: existsSync7(join8(cwd, "CLAUDE.md")),
+    docsDir: existsSync7(join8(cwd, "docs")),
+    architectureMd: existsSync7(join8(cwd, "docs", "architecture.md"))
   };
   return {
     packageManager,
@@ -8135,9 +9110,9 @@ var VAGUE_STANDARDS = [
 ];
 function verifyDocs(cwd) {
   const issues = [];
-  const claudeMd = readText(join7(cwd, "CLAUDE.md"));
-  const agentsMd = readText(join7(cwd, "AGENTS.md"));
-  const pkg = readJson(join7(cwd, "package.json"));
+  const claudeMd = readText(join8(cwd, "CLAUDE.md"));
+  const agentsMd = readText(join8(cwd, "AGENTS.md"));
+  const pkg = readJson(join8(cwd, "package.json"));
   const pkgScripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null ? pkg.scripts : {};
   const projectRoot = resolve2(cwd);
   if (claudeMd) {
@@ -8167,7 +9142,7 @@ function verifyDocs(cwd) {
           continue;
         }
         importedFiles.push({ ref: refPath, resolved: resolvedPath });
-        if (!existsSync6(resolvedPath)) {
+        if (!existsSync7(resolvedPath)) {
           issues.push({
             severity: "error",
             file: "CLAUDE.md",
@@ -8303,7 +9278,7 @@ function verifyDocs(cwd) {
     }
     checkBacktickPaths(agentsMd, "AGENTS.md", cwd, issues);
   }
-  const archMd = readText(join7(cwd, "docs", "architecture.md"));
+  const archMd = readText(join8(cwd, "docs", "architecture.md"));
   if (archMd) {
     checkBacktickPaths(archMd, "docs/architecture.md", cwd, issues);
   }
@@ -8350,7 +9325,7 @@ function checkBacktickPaths(content, file, cwd, issues) {
     const resolvedRef = resolve2(root, refPath);
     if (resolvedRef !== root && !resolvedRef.startsWith(root + sep2))
       continue;
-    if (!existsSync6(resolvedRef)) {
+    if (!existsSync7(resolvedRef)) {
       issues.push({
         severity: "warning",
         file,
@@ -8373,18 +9348,18 @@ async function runDocsStep(cwd) {
     }
     const files = [];
     files.push({
-      path: join7(cwd, "AGENTS.md"),
+      path: join8(cwd, "AGENTS.md"),
       content: generateAgentsMd(info, cwd),
       type: "text"
     });
     files.push({
-      path: join7(cwd, "CLAUDE.md"),
+      path: join8(cwd, "CLAUDE.md"),
       content: generateClaudeMd(info),
       type: "text"
     });
     if (info.dirs.includes("docs") || info.srcDirs.length > 0) {
       files.push({
-        path: join7(cwd, "docs", "architecture.md"),
+        path: join8(cwd, "docs", "architecture.md"),
         content: generateArchitectureMd(info, cwd),
         type: "text"
       });
@@ -8422,21 +9397,21 @@ async function runDocsStep(cwd) {
 // src/tui/writer.ts
 import {
   chmodSync,
-  existsSync as existsSync7,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync6,
-  writeFileSync as writeFileSync4
+  existsSync as existsSync8,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync7,
+  writeFileSync as writeFileSync5
 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
+import { homedir as homedir6 } from "node:os";
 import { dirname as dirname3 } from "node:path";
 import * as p3 from "@clack/prompts";
 function ensureDir(dirPath) {
-  if (!existsSync7(dirPath)) {
-    mkdirSync4(dirPath, { recursive: true, mode: 493 });
+  if (!existsSync8(dirPath)) {
+    mkdirSync5(dirPath, { recursive: true, mode: 493 });
   }
 }
 function writeFile(filePath, content, options = {}) {
-  const exists = existsSync7(filePath);
+  const exists = existsSync8(filePath);
   if (exists && !options.force) {
     return { path: filePath, action: "skip" };
   }
@@ -8444,7 +9419,7 @@ function writeFile(filePath, content, options = {}) {
     ensureDir(dirname3(filePath));
     const defaultMode = filePath.includes(".harmony-mcp") ? 384 : 420;
     const mode = options.mode ?? defaultMode;
-    writeFileSync4(filePath, content, { mode });
+    writeFileSync5(filePath, content, { mode });
     if (options.mode !== undefined) {
       chmodSync(filePath, options.mode);
     }
@@ -8458,11 +9433,11 @@ function writeFile(filePath, content, options = {}) {
   }
 }
 function mergeJsonFile(filePath, updates, options = {}) {
-  const exists = existsSync7(filePath);
+  const exists = existsSync8(filePath);
   if (!exists) {
     try {
       ensureDir(dirname3(filePath));
-      writeFileSync4(filePath, JSON.stringify(updates, null, 2), {
+      writeFileSync5(filePath, JSON.stringify(updates, null, 2), {
         mode: 420
       });
       return { path: filePath, action: "create" };
@@ -8475,7 +9450,7 @@ function mergeJsonFile(filePath, updates, options = {}) {
     }
   }
   try {
-    const existing = JSON.parse(readFileSync6(filePath, "utf-8"));
+    const existing = JSON.parse(readFileSync7(filePath, "utf-8"));
     if (updates.mcpServers && existing.mcpServers) {
       const existingServers = existing.mcpServers;
       const updateServers = updates.mcpServers;
@@ -8483,12 +9458,12 @@ function mergeJsonFile(filePath, updates, options = {}) {
     } else {
       Object.assign(existing, updates);
     }
-    writeFileSync4(filePath, JSON.stringify(existing, null, 2), { mode: 420 });
+    writeFileSync5(filePath, JSON.stringify(existing, null, 2), { mode: 420 });
     return { path: filePath, action: "merge" };
   } catch {
     if (options.force) {
       try {
-        writeFileSync4(filePath, JSON.stringify(updates, null, 2), {
+        writeFileSync5(filePath, JSON.stringify(updates, null, 2), {
           mode: 420
         });
         return { path: filePath, action: "update" };
@@ -8508,11 +9483,11 @@ function mergeJsonFile(filePath, updates, options = {}) {
   }
 }
 function appendToToml(filePath, section, content, options = {}) {
-  const exists = existsSync7(filePath);
+  const exists = existsSync8(filePath);
   if (!exists) {
     try {
       ensureDir(dirname3(filePath));
-      writeFileSync4(filePath, content, { mode: 420 });
+      writeFileSync5(filePath, content, { mode: 420 });
       return { path: filePath, action: "create" };
     } catch (error) {
       return {
@@ -8523,19 +9498,19 @@ function appendToToml(filePath, section, content, options = {}) {
     }
   }
   try {
-    const existing = readFileSync6(filePath, "utf-8");
+    const existing = readFileSync7(filePath, "utf-8");
     if (existing.includes(`[${section}]`)) {
       if (options.force) {
         const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
         const updated = existing.replace(new RegExp(`(?:#[^\\n]*\\n)*\\[${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`), content.trim() + `
 
 `);
-        writeFileSync4(filePath, updated, { mode: 420 });
+        writeFileSync5(filePath, updated, { mode: 420 });
         return { path: filePath, action: "update" };
       }
       return { path: filePath, action: "skip" };
     }
-    writeFileSync4(filePath, existing + `
+    writeFileSync5(filePath, existing + `
 ` + content, { mode: 420 });
     return { path: filePath, action: "merge" };
   } catch (error) {
@@ -8548,7 +9523,7 @@ function appendToToml(filePath, section, content, options = {}) {
 }
 async function writeFilesWithProgress(files, options = {}) {
   const results = [];
-  const home = homedir5();
+  const home = homedir6();
   const spinner2 = p3.spinner();
   spinner2.start("Writing configuration files...");
   for (const file of files) {
@@ -8585,10 +9560,10 @@ function getWriteSummary(files, options = {}) {
   const toCreate = [];
   const toUpdate = [];
   const toSkip = [];
-  const home = homedir5();
+  const home = homedir6();
   for (const file of files) {
     const displayPath = formatPath(file.path, home);
-    const exists = existsSync7(file.path);
+    const exists = existsSync8(file.path);
     if (exists && !options.force) {
       toSkip.push(displayPath);
     } else if (exists) {
@@ -8643,13 +9618,14 @@ var SAFE_HARMONY_TOOLS = [
   "harmony_create_plan",
   "harmony_update_plan",
   "harmony_advance_plan",
+  "harmony_link_plan_task",
   "harmony_remember",
   "harmony_relate",
   "harmony_update_memory",
   "harmony_process_command",
   "harmony_sync"
 ];
-var GLOBAL_SKILLS_DIR = join8(homedir6(), ".agents", "skills");
+var GLOBAL_SKILLS_DIR = join9(homedir7(), ".agents", "skills");
 var API_URL = "https://app.gethmy.com/api";
 async function registerMcpServer() {
   try {
@@ -8663,15 +9639,15 @@ async function registerMcpServer() {
   }
 }
 async function writeMcpConfigFallback(home) {
-  const { readFileSync: readFileSync7, writeFileSync: writeFileSync5, mkdirSync: mkdirSync6, existsSync: existsSync9 } = await import("node:fs");
-  const settingsPath = join8(home, ".claude", "settings.json");
+  const { readFileSync: readFileSync8, writeFileSync: writeFileSync6, mkdirSync: mkdirSync7, existsSync: existsSync10 } = await import("node:fs");
+  const settingsPath = join9(home, ".claude", "settings.json");
   const settingsDir = dirname4(settingsPath);
-  if (!existsSync9(settingsDir)) {
-    mkdirSync6(settingsDir, { recursive: true });
+  if (!existsSync10(settingsDir)) {
+    mkdirSync7(settingsDir, { recursive: true });
   }
   let settings = {};
-  if (existsSync9(settingsPath)) {
-    settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
+  if (existsSync10(settingsPath)) {
+    settings = JSON.parse(readFileSync8(settingsPath, "utf-8"));
   }
   const mcpServers = settings.mcpServers || {};
   mcpServers.harmony = {
@@ -8679,18 +9655,18 @@ async function writeMcpConfigFallback(home) {
     args: ["-y", "@gethmy/mcp@latest", "serve"]
   };
   settings.mcpServers = mcpServers;
-  writeFileSync5(settingsPath, JSON.stringify(settings, null, 2));
+  writeFileSync6(settingsPath, JSON.stringify(settings, null, 2));
 }
 async function allowlistHarmonyTools(home, allowAll) {
-  const { readFileSync: readFileSync7, writeFileSync: writeFileSync5, mkdirSync: mkdirSync6, existsSync: existsSync9 } = await import("node:fs");
-  const settingsPath = join8(home, ".claude", "settings.json");
+  const { readFileSync: readFileSync8, writeFileSync: writeFileSync6, mkdirSync: mkdirSync7, existsSync: existsSync10 } = await import("node:fs");
+  const settingsPath = join9(home, ".claude", "settings.json");
   const settingsDir = dirname4(settingsPath);
-  if (!existsSync9(settingsDir)) {
-    mkdirSync6(settingsDir, { recursive: true });
+  if (!existsSync10(settingsDir)) {
+    mkdirSync7(settingsDir, { recursive: true });
   }
   let settings = {};
-  if (existsSync9(settingsPath)) {
-    settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
+  if (existsSync10(settingsPath)) {
+    settings = JSON.parse(readFileSync8(settingsPath, "utf-8"));
   }
   const permissions = settings.permissions || {};
   const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
@@ -8703,7 +9679,7 @@ async function allowlistHarmonyTools(home, allowAll) {
   allow.push(...missing);
   permissions.allow = allow;
   settings.permissions = permissions;
-  writeFileSync5(settingsPath, JSON.stringify(settings, null, 2));
+  writeFileSync6(settingsPath, JSON.stringify(settings, null, 2));
   return "added";
 }
 async function validateApiKey(apiKey, apiUrl = API_URL) {
@@ -8797,7 +9773,7 @@ async function resolveProjectSlug(apiKey, slug) {
   };
 }
 async function getAgentFiles(agentId, cwd, installMode = "global") {
-  const home = homedir6();
+  const home = homedir7();
   const files = [];
   const symlinks = [];
   switch (agentId) {
@@ -8812,17 +9788,17 @@ async function getAgentFiles(agentId, cwd, installMode = "global") {
           const content = buildSkillFile(fetched);
           if (installMode === "global") {
             files.push({
-              path: join8(GLOBAL_SKILLS_DIR, name, "SKILL.md"),
+              path: join9(GLOBAL_SKILLS_DIR, name, "SKILL.md"),
               content,
               type: "text"
             });
             symlinks.push({
-              target: join8(GLOBAL_SKILLS_DIR, name),
-              link: join8(home, ".claude", "skills", name)
+              target: join9(GLOBAL_SKILLS_DIR, name),
+              link: join9(home, ".claude", "skills", name)
             });
           } else {
             files.push({
-              path: join8(cwd, ".claude", "skills", name, "SKILL.md"),
+              path: join9(cwd, ".claude", "skills", name, "SKILL.md"),
               content,
               type: "text"
             });
@@ -8845,13 +9821,13 @@ ${summary}`);
           throw new Error(`hmy-update-check integrity check failed: expected ${updateCheckFetched.sha256}, got ${actualHash}`);
         }
         files.push({
-          path: join8(home, ".hmy", "bin", "hmy-update-check"),
+          path: join9(home, ".hmy", "bin", "hmy-update-check"),
           content: updateCheckFetched.content,
           type: "text",
           mode: 493
         });
         files.push({
-          path: join8(home, ".hmy", "VERSION"),
+          path: join9(home, ".hmy", "VERSION"),
           content: versionInfo.version,
           type: "text"
         });
@@ -8913,7 +9889,7 @@ Skip if: work was already started with a card reference, or no matching card exi
 - \`harmony_generate_prompt\` - Get role-based guidance and focus areas for the card
 `;
       files.push({
-        path: join8(cwd, "AGENTS.md"),
+        path: join9(cwd, "AGENTS.md"),
         content: agentsContent,
         type: "text"
       });
@@ -8930,17 +9906,17 @@ ${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "{{card}}").replace("Your agent
 `;
       if (installMode === "global") {
         files.push({
-          path: join8(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
+          path: join9(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
           content: promptContent,
           type: "text"
         });
         symlinks.push({
-          target: join8(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
-          link: join8(home, ".codex", "prompts", "hmy.md")
+          target: join9(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
+          link: join9(home, ".codex", "prompts", "hmy.md")
         });
       } else {
         files.push({
-          path: join8(home, ".codex", "prompts", "hmy.md"),
+          path: join9(home, ".codex", "prompts", "hmy.md"),
           content: promptContent,
           type: "text"
         });
@@ -8952,7 +9928,7 @@ command = "npx"
 args = ["-y", "@gethmy/mcp@latest", "serve"]
 `;
       files.push({
-        path: join8(home, ".codex", "config.toml"),
+        path: join9(home, ".codex", "config.toml"),
         content: tomlContent,
         type: "toml",
         tomlSection: "mcp_servers.harmony"
@@ -8961,7 +9937,7 @@ args = ["-y", "@gethmy/mcp@latest", "serve"]
     }
     case "cursor": {
       files.push({
-        path: join8(cwd, ".cursor", "mcp.json"),
+        path: join9(cwd, ".cursor", "mcp.json"),
         content: JSON.stringify({
           mcpServers: {
             harmony: {
@@ -8987,17 +9963,17 @@ ${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Y
 `;
       if (installMode === "global") {
         files.push({
-          path: join8(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
+          path: join9(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
           content: ruleContent,
           type: "text"
         });
         symlinks.push({
-          target: join8(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
-          link: join8(home, ".cursor", "rules", "harmony.mdc")
+          target: join9(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
+          link: join9(home, ".cursor", "rules", "harmony.mdc")
         });
       } else {
         files.push({
-          path: join8(cwd, ".cursor", "rules", "harmony.mdc"),
+          path: join9(cwd, ".cursor", "rules", "harmony.mdc"),
           content: ruleContent,
           type: "text"
         });
@@ -9006,7 +9982,7 @@ ${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Y
     }
     case "windsurf": {
       files.push({
-        path: join8(home, ".codeium", "windsurf", "mcp_config.json"),
+        path: join9(home, ".codeium", "windsurf", "mcp_config.json"),
         content: JSON.stringify({
           mcpServers: {
             harmony: {
@@ -9032,17 +10008,17 @@ ${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Y
 `;
       if (installMode === "global") {
         files.push({
-          path: join8(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
+          path: join9(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
           content: ruleContent,
           type: "text"
         });
         symlinks.push({
-          target: join8(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
-          link: join8(home, ".codeium", "windsurf", "rules", "harmony.md")
+          target: join9(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
+          link: join9(home, ".codeium", "windsurf", "rules", "harmony.md")
         });
       } else {
         files.push({
-          path: join8(cwd, ".windsurf", "rules", "harmony.md"),
+          path: join9(cwd, ".windsurf", "rules", "harmony.md"),
           content: ruleContent,
           type: "text"
         });
@@ -9054,7 +10030,7 @@ ${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Y
 }
 async function runSetup(options = {}) {
   const cwd = process.cwd();
-  const home = homedir6();
+  const home = homedir7();
   console.clear();
   console.log(messages.header());
   const assumeYes = shouldAssumeYes(options.yes, process.stdin.isTTY);
@@ -9552,8 +10528,8 @@ Specify the workspace with --workspace <id>, or select one below.`);
     for (const symlink of allSymlinks) {
       try {
         const linkDir = dirname4(symlink.link);
-        if (!existsSync8(linkDir)) {
-          mkdirSync5(linkDir, { recursive: true });
+        if (!existsSync9(linkDir)) {
+          mkdirSync6(linkDir, { recursive: true });
         }
         let linkExists = false;
         try {
@@ -9562,7 +10538,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         } catch {}
         if (linkExists) {
           if (options.force) {
-            unlinkSync(symlink.link);
+            unlinkSync2(symlink.link);
           } else {
             continue;
           }
@@ -9581,7 +10557,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
     } else {
       try {
         await writeMcpConfigFallback(home);
-        console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join8(home, ".claude", "settings.json"), home))} ${colors.dim("(updated)")}`);
+        console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join9(home, ".claude", "settings.json"), home))} ${colors.dim("(updated)")}`);
       } catch {
         p4.log.warning("Could not register MCP server. Run manually: claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve");
       }
@@ -9602,7 +10578,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
       try {
         const result = await allowlistHarmonyTools(home, allowAll);
         const scope = allowAll ? "all tools" : "safe tools";
-        console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join8(home, ".claude", "settings.json"), home))} ${colors.dim(result === "added" ? `(${scope} allowlisted)` : `(${scope} already allowlisted)`)}`);
+        console.log(`  ${colors.success("✓")} ${colors.dim(formatPath(join9(home, ".claude", "settings.json"), home))} ${colors.dim(result === "added" ? `(${scope} allowlisted)` : `(${scope} already allowlisted)`)}`);
       } catch {
         p4.log.warning("Could not allowlist Harmony tools. Run /permissions in Claude Code and choose “always allow” for Harmony, or add mcp__harmony to permissions.allow in ~/.claude/settings.json.");
       }
@@ -9783,4 +10759,59 @@ program.command("setup").description("Setup wizard for Harmony MCP (recommended)
     yes: options.yes
   });
 });
+var 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 () => {
+  const { installUserHook: installUserHook2 } = await Promise.resolve().then(() => (init_hook_install(), exports_hook_install));
+  const result = installUserHook2();
+  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(`
+Tool 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: uninstallUserHook2 } = await Promise.resolve().then(() => (init_hook_install(), exports_hook_install));
+  const result = uninstallUserHook2();
+  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: hookInstallStatus2, userSettingsPath: userSettingsPath2 } = await Promise.resolve().then(() => (init_hook_install(), exports_hook_install));
+  const { readPublishedSessions: readPublishedSessions2, runStateDir: runStateDir2 } = await Promise.resolve().then(() => (init_run_state(), exports_run_state));
+  const { readFileSync: readFileSync9 } = await import("node:fs");
+  const path = userSettingsPath2();
+  let status = {
+    installed: false,
+    binary: null,
+    binaryExists: false
+  };
+  try {
+    status = hookInstallStatus2(JSON.parse(readFileSync9(path, "utf-8")));
+  } catch {}
+  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: ${runStateDir2()}`);
+  const sessions = readPublishedSessions2();
+  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();