@gethmy/mcp 3.3.0 → 3.4.0

package/dist/index.js

@@ -978,6 +978,353 @@ 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/server.ts
 import { createHash as createHash4 } from "node:crypto";
 import { readFile } from "node:fs/promises";
@@ -2641,6 +2988,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",
@@ -2724,6 +3287,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,
@@ -2733,6 +3297,7 @@ async function trackActivity(cardId, options) {
     });
     if (started?.session === null)
       return;
+    agentSessionId = started?.session?.id;
   } catch {}
   scope.sessions.set(cardId, {
     cardId,
@@ -2741,8 +3306,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);
@@ -2843,6 +3414,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 {}
@@ -2851,36 +3425,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();
 
@@ -3554,30 +4098,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 };
   }
@@ -3709,11 +4253,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;
@@ -3742,7 +4286,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`)) {
@@ -3753,15 +4297,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;
@@ -3771,9 +4315,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 = {}) {
@@ -3805,7 +4349,7 @@ async function refreshSkills(opts = {}) {
           const parentDir = dirname2(samplePath);
           siblingPath = `${parentDir}/${name}.md`;
         }
-        if (existsSync4(siblingPath)) {
+        if (existsSync5(siblingPath)) {
           skillFiles.push({ name, filePath: siblingPath });
         }
       }
@@ -3815,7 +4359,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;
@@ -5621,7 +6165,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: {
@@ -5632,7 +6176,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",
@@ -6836,6 +7380,11 @@ ${options}
       });
       const agentSessionId = result.session?.id;
       initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, deps.getScopeId?.());
+      beginHookTimeline({
+        cardId,
+        agentSessionId,
+        getClient: () => client3
+      });
       return {
         success: true,
         assignedTo,
@@ -6897,6 +7446,7 @@ ${options}
       const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
+      await endHookTimeline(cardId);
       let result = {
         session: null
       };
@@ -7506,7 +8056,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,
@@ -7514,13 +8064,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": {
@@ -7548,7 +8108,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: {
@@ -7556,6 +8119,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 } : {}
         }
       };
@@ -7790,6 +8354,9 @@ class HarmonyMCPServer {
       try {
         await shutdownAllSessions();
       } catch {}
+      try {
+        await stopAllRunEventForwarders();
+      } catch {}
       destroyAutoSession();
       process.exit(exitCode);
     };