@gethmy/mcp 3.3.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";
@@ -2646,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",
@@ -2729,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,
@@ -2738,6 +3514,7 @@ async function trackActivity(cardId, options) {
     });
     if (started?.session === null)
       return;
+    agentSessionId = started?.session?.id;
   } catch {}
   scope.sessions.set(cardId, {
     cardId,
@@ -2746,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);
@@ -2848,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 {}
@@ -2856,36 +3642,6 @@ async function autoEndSession(scope, client3, cardId, status) {
   } catch {}
 }
 
-// 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/server.ts
 init_config();
 
@@ -3559,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 };
   }
@@ -3714,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;
@@ -3747,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`)) {
@@ -3758,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;
@@ -3776,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 = {}) {
@@ -3810,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 });
         }
       }
@@ -3820,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;
@@ -5626,7 +6382,7 @@ var TOOLS = {
     }
   },
   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.",
+    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: {
@@ -5637,7 +6393,7 @@ var TOOLS = {
         },
         cardId: {
           type: "string",
-          description: "Card that fulfils this criterion. Must live in the plan's own project."
+          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",
@@ -6841,6 +7597,11 @@ ${options}
       });
       const agentSessionId = result.session?.id;
       initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, deps.getScopeId?.());
+      beginHookTimeline({
+        cardId,
+        agentSessionId,
+        getClient: () => client3
+      });
       return {
         success: true,
         assignedTo,
@@ -6902,6 +7663,7 @@ ${options}
       const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
+      await endHookTimeline(cardId);
       let result = {
         session: null
       };
@@ -7511,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,
@@ -7519,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": {
@@ -7553,7 +8325,10 @@ ${options}
       const found = findPlanTask(tasks, taskId);
       if (!found.ok)
         throw new Error(found.reason);
-      await client3.updatePlanTask(planId, taskId, { cardId, status });
+      const result = await client3.updatePlanTask(planId, taskId, {
+        cardId,
+        status
+      });
       return {
         success: true,
         planTask: {
@@ -7561,6 +8336,7 @@ ${options}
           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 } : {}
         }
       };
@@ -7795,6 +8571,9 @@ class HarmonyMCPServer {
       try {
         await shutdownAllSessions();
       } catch {}
+      try {
+        await stopAllRunEventForwarders();
+      } catch {}
       destroyAutoSession();
       process.exit(exitCode);
     };
@@ -7832,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"]
   },
   {
@@ -7862,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"]
   },
   {
@@ -7878,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
     };
@@ -7910,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
@@ -7998,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;
       }
@@ -8064,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";
@@ -8118,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 = [
@@ -8133,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 = [
@@ -8145,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) {
@@ -8161,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+)/);
@@ -8174,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,
@@ -8331,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) {
@@ -8363,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",
@@ -8499,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);
   }
@@ -8546,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,
@@ -8569,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"
       });
@@ -8618,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" };
   }
@@ -8640,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);
     }
@@ -8654,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" };
@@ -8671,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;
@@ -8679,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" };
@@ -8704,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 {
@@ -8719,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) {
@@ -8744,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) {
@@ -8781,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) {
@@ -8846,7 +9625,7 @@ var SAFE_HARMONY_TOOLS = [
   "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 {
@@ -8860,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 = {
@@ -8876,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 : [];
@@ -8900,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) {
@@ -8994,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) {
@@ -9009,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"
             });
@@ -9042,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"
         });
@@ -9110,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"
       });
@@ -9127,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"
         });
@@ -9149,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"
@@ -9158,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: {
@@ -9184,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"
         });
@@ -9203,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: {
@@ -9229,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"
         });
@@ -9251,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);
@@ -9749,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 {
@@ -9759,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;
           }
@@ -9778,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");
       }
@@ -9799,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.");
       }
@@ -9980,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();