@gethmy/mcp 3.2.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";
@@ -1384,7 +1731,6 @@ var AGENT_MILESTONE_LIVENESS_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_DAEMON_MS = 30 * 60 * 1000;
 var AGENT_SWEEP_INTERACTIVE_MS = 2 * 60 * 60 * 1000;
 var AGENT_SWEEP_PAUSED_MS = 4 * 60 * 60 * 1000;
-var SWEPT_SESSION_WRITE_GRACE_MS = 60 * 60 * 1000;
 var ACTIVE_STATUSES = new Set(["working", "blocked", "waiting"]);
 // ../harmony-shared/dist/cardLinks.js
 var LINK_TYPE_INVERSES = {
@@ -2612,6 +2958,9 @@ ${untrustedDataBlock(planContent.trim(), {
   async updatePlaybook(playbookId, updates) {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);
   }
+  async deletePlaybook(playbookId) {
+    return this.request("DELETE", `/playbooks/${encodeURIComponent(playbookId)}`);
+  }
 }
 var _promptModules = null;
 async function loadPromptModules() {
@@ -2639,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",
@@ -2722,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,
@@ -2731,6 +3297,7 @@ async function trackActivity(cardId, options) {
     });
     if (started?.session === null)
       return;
+    agentSessionId = started?.session?.id;
   } catch {}
   scope.sessions.set(cardId, {
     cardId,
@@ -2739,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);
@@ -2841,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 {}
@@ -3447,6 +4023,51 @@ async function onboardNewUser(params) {
   };
 }
 
+// src/plan-task-link.ts
+function findPlanTask(tasks, taskId) {
+  if (!taskId) {
+    return { ok: false, reason: "No plan task id was given." };
+  }
+  if (!Array.isArray(tasks)) {
+    return {
+      ok: false,
+      reason: "The plan returned no readable criteria list."
+    };
+  }
+  for (const row of tasks) {
+    if (!row || typeof row !== "object")
+      continue;
+    const candidate = row;
+    if (candidate.id === taskId) {
+      return { ok: true, task: candidate };
+    }
+  }
+  return {
+    ok: false,
+    reason: `Plan task ${taskId} is not one of this plan's criteria. ` + `Read the plan with harmony_get_plan and use an id from its \`tasks\`.`
+  };
+}
+function linkedReport(planId, task, newCardId) {
+  const previous = task.card_id ?? null;
+  return {
+    planId,
+    taskId: task.id,
+    linked: true,
+    criterion: task.content ?? null,
+    ...previous && previous !== newCardId ? { replacedCardId: previous } : {}
+  };
+}
+function unlinkedReport(planId, task, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    planId,
+    taskId: task.id,
+    linked: false,
+    criterion: task.content ?? null,
+    error: `The card was created, but the plan criterion still does not point at it: ${message}. ` + `Repair it with harmony_link_plan_task — do not create the card again.`
+  };
+}
+
 // src/playbook-metric-warnings.ts
 function playbookMetricWarnings(agents, steps) {
   if (!Array.isArray(steps))
@@ -3477,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 };
   }
@@ -3632,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;
@@ -3665,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`)) {
@@ -3676,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;
@@ -3694,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 = {}) {
@@ -3728,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 });
         }
       }
@@ -3738,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;
@@ -3944,12 +4565,13 @@ function optionalNonNegativeNumberArg(raw, field) {
     throw new Error(`${field} must be a non-negative number.`);
   return n;
 }
-function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId) {
+function initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, scopeId) {
   memorySessions.set(cardId, {
     cardId,
     agentIdentifier,
     agentName,
     agentSessionId,
+    scopeId,
     memoryReadCount: 0,
     pendingActions: [],
     allActions: [],
@@ -4061,6 +4683,10 @@ var TOOLS = {
           type: "string",
           description: "Plan ID to link this card to (optional). Links the card to that plan via its plan_id."
         },
+        planTaskId: {
+          type: "string",
+          description: "Id of the plan CRITERION this card is created to fulfil (optional; requires `planId`). " + "Sets both directions at once: the card's plan_id, and the criterion's card_id — the " + "return leg a card outcome needs to reach the plan. Read the ids from harmony_get_plan's " + "`tasks`. A criterion that is not in the named plan refuses the whole call, so no card is " + "created on a false premise; a failure to write the return leg AFTER the card exists " + "keeps the card and reports it in `planTask` instead."
+        },
         attachments: {
           type: "array",
           description: "Optional reference files to attach to the new card (e.g. a screenshot from the prompt). " + "Max 5MB each; PNG/JPEG/GIF/WebP/HEIC/HEIF/PDF/DOC(X)/XLS(X)/TXT/CSV. Each file's bytes " + "come from `filePath` (absolute local path the server reads, preferred) or `base64Data` " + "(small-file fallback; requires fileName). NOTE: a pasted image only attaches if your " + "harness has written it to a local file you can pass as filePath — a model cannot re-emit " + "pasted image bytes into base64Data. Per-file failures never block card creation; they are " + "reported back in the result's `attachments` array so you can retry via harmony_upload.",
@@ -5538,6 +6164,29 @@ var TOOLS = {
       required: ["planId"]
     }
   },
+  harmony_link_plan_task: {
+    description: "Point a plan CRITERION at the card that fulfils it, and/or set the criterion's status. " + "A plan task is a success criterion, not a work item: `cards.plan_id` says which plan a card " + "belongs to, and this sets the return leg the plan needs to show real progress instead of " + "guessing from board-column names. Use it to repair a link, to re-point a criterion at a " + "different card, or to mark a criterion `completed` once its card actually delivered it. " + "Leave a criterion the card did NOT deliver open — an open criterion is the signal. " + "Linking a card that belongs to no plan yet also adopts it into this one (reported as " + "`cardPlanAdopted`), and linking a card that already belongs to a DIFFERENT plan is " + "refused — move it with harmony_update_card first, so the two directions cannot drift.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "Plan ID owning the criterion" },
+        taskId: {
+          type: "string",
+          description: "Criterion id, from harmony_get_plan's `tasks`. Must belong to `planId`."
+        },
+        cardId: {
+          type: "string",
+          description: "Card that fulfils this criterion. Must live in the plan's own project, and " + "must belong to this plan or to no plan yet — a card already in another plan " + "is refused rather than silently re-pointed."
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "in_progress", "completed"],
+          description: "Criterion status. Set `completed` only when the card demonstrably delivered it."
+        }
+      },
+      required: ["planId", "taskId"]
+    }
+  },
   harmony_list_playbook: {
     description: "List a workspace's playbooks (reusable process definitions). Returns each playbook's name, version, and state. Read-only.",
     inputSchema: {
@@ -5632,6 +6281,19 @@ var TOOLS = {
       required: ["playbookId"]
     }
   },
+  harmony_delete_playbook: {
+    description: "Permanently delete a playbook. IRREVERSIBLE and cascading: its version snapshots and run history are deleted with it, and every card currently running it is unbound — the card stays on the board and keeps its column, but loses its playbook, its pinned version and its stage pointer, so the agent daemon stops treating it as a stage card. Prefer harmony_update_playbook with state='deprecated' unless the playbook should never have existed: a deprecated playbook stays applicable to in-flight cards and is only hidden from new applies. Requires the playbook's creator or a workspace owner/admin — and an ARMED playbook (triggerType 'auto') takes an owner/admin even from its creator, because removing it stops the workspace's automation for everyone. Anyone else is refused and the playbook is left alone. Returns unboundCardCount (the exact number of cards it unbound) and unboundCards (up to 50 of them by id, short_id, title and the stage each one lost).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to delete (UUID)"
+        }
+      },
+      required: ["playbookId"]
+    }
+  },
   harmony_signup: {
     description: "Create a new user account. Returns a JWT session for subsequent authenticated calls. No API key required.",
     inputSchema: {
@@ -5926,28 +6588,58 @@ async function handleToolCall(name, args, deps) {
         fileName: z.string().optional(),
         contentType: z.string().optional()
       })).parse(args.attachments) : [];
+      const planId = args.planId ? z.string().uuid().parse(args.planId) : undefined;
+      const planTaskId = args.planTaskId ? z.string().uuid().parse(args.planTaskId) : undefined;
+      if (planTaskId && !planId) {
+        throw new Error("planTaskId requires planId: no route resolves a plan from a criterion id alone. " + "Pass the plan the criterion belongs to — harmony_get_plan returns both.");
+      }
+      let criterion;
+      if (planTaskId && planId) {
+        const { tasks } = await client3.getPlan(planId);
+        const found = findPlanTask(tasks, planTaskId);
+        if (!found.ok)
+          throw new Error(found.reason);
+        criterion = found.task;
+      }
       const result = await client3.createCard(projectId, {
         title,
         columnId: args.columnId,
         description: args.description,
         priority: args.priority,
         assigneeId: args.assigneeId,
-        planId: args.planId
+        planId
       });
+      const newCardId = result.card?.id;
+      let planTask;
+      if (criterion && planId) {
+        if (!newCardId) {
+          planTask = unlinkedReport(planId, criterion, new Error("no card id was returned to link against"));
+        } else {
+          try {
+            await client3.updatePlanTask(planId, criterion.id, {
+              cardId: newCardId
+            });
+            planTask = linkedReport(planId, criterion, newCardId);
+          } catch (err) {
+            planTask = unlinkedReport(planId, criterion, err);
+          }
+        }
+      }
+      const planTaskField = planTask ? { planTask } : {};
       if (attachments.length === 0) {
-        return { success: true, ...result };
+        return { success: true, ...result, ...planTaskField };
       }
-      const cardId = result.card?.id;
-      if (!cardId) {
+      if (!newCardId) {
         return {
           success: true,
           ...result,
+          ...planTaskField,
           attachmentWarning: "Card created, but attachments were skipped: no card id was returned to upload against."
         };
       }
       const attachmentResults = await Promise.all(attachments.map(async (file) => {
         try {
-          const uploaded = await attachFileToCard(client3, cardId, file);
+          const uploaded = await attachFileToCard(client3, newCardId, file);
           return { ok: true, attachment: uploaded.attachment };
         } catch (err) {
           return {
@@ -5957,7 +6649,12 @@ async function handleToolCall(name, args, deps) {
           };
         }
       }));
-      return { success: true, ...result, attachments: attachmentResults };
+      return {
+        success: true,
+        ...result,
+        ...planTaskField,
+        attachments: attachmentResults
+      };
     }
     case "harmony_update_card": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6441,15 +7138,24 @@ ${list}
       const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
       const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
       const replyToId = args.replyToId !== undefined ? z.string().uuid().parse(args.replyToId) : undefined;
-      const agentSessionId = getMemorySession(cardId)?.agentSessionId;
+      const sessionChoice = chooseCommentSession({
+        cardId,
+        tracked: getMemorySession(cardId),
+        callerScopeId: deps.getScopeId?.(),
+        declared: readDeclaredRunSession()
+      });
       const result = await client3.addComment(cardId, body, {
         commentType,
         supersedesId,
         confirmsId,
         replyToId,
-        agentSessionId
+        agentSessionId: sessionChoice.kind === "session" ? sessionChoice.agentSessionId : undefined
       });
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        sessionAttribution: sessionChoice.kind === "session" ? sessionChoice.source : "none"
+      };
     }
     case "harmony_get_comments": {
       const cardId = z.string().uuid().parse(args.cardId);
@@ -6673,7 +7379,12 @@ ${options}
         scopeId: deps.getScopeId?.()
       });
       const agentSessionId = result.session?.id;
-      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId);
+      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId, deps.getScopeId?.());
+      beginHookTimeline({
+        cardId,
+        agentSessionId,
+        getClient: () => client3
+      });
       return {
         success: true,
         assignedTo,
@@ -6735,6 +7446,7 @@ ${options}
       const endProgressPercent = optionalPercentArg(args.progressPercent, "progressPercent");
       await flushMemoryActions(client3, cardId);
       cleanupMemorySession(cardId);
+      await endHookTimeline(cardId);
       let result = {
         session: null
       };
@@ -7344,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,
@@ -7352,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": {
@@ -7374,6 +8096,34 @@ ${options}
       const result = await client3.updatePlan(planId, updates);
       return { success: true, plan: result.plan };
     }
+    case "harmony_link_plan_task": {
+      const planId = z.string().uuid().parse(args.planId);
+      const taskId = z.string().uuid().parse(args.taskId);
+      const cardId = args.cardId ? z.string().uuid().parse(args.cardId) : undefined;
+      const status = args.status ? z.enum(["pending", "in_progress", "completed"]).parse(args.status) : undefined;
+      if (!cardId && !status) {
+        throw new Error("Nothing to do: pass cardId, status, or both.");
+      }
+      const { tasks } = await client3.getPlan(planId);
+      const found = findPlanTask(tasks, taskId);
+      if (!found.ok)
+        throw new Error(found.reason);
+      const result = await client3.updatePlanTask(planId, taskId, {
+        cardId,
+        status
+      });
+      return {
+        success: true,
+        planTask: {
+          planId,
+          taskId,
+          criterion: found.task.content ?? null,
+          ...cardId ? linkedReport(planId, found.task, cardId) : { linked: found.task.card_id != null },
+          ...cardId && result.cardPlanAdopted ? { cardPlanAdopted: true } : {},
+          ...status ? { status } : {}
+        }
+      };
+    }
     case "harmony_advance_plan": {
       const planId = z.string().uuid().parse(args.planId);
       const summary = args.summary;
@@ -7461,6 +8211,16 @@ ${options}
         ...warnings.length > 0 ? { warnings } : {}
       };
     }
+    case "harmony_delete_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      const result = await client3.deletePlaybook(playbookId);
+      return {
+        success: true,
+        playbook: result.playbook,
+        unboundCardCount: result.unboundCardCount,
+        unboundCards: result.unboundCards
+      };
+    }
     case "harmony_save_card_as_playbook":
       return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
     case "harmony_signup": {
@@ -7594,6 +8354,9 @@ class HarmonyMCPServer {
       try {
         await shutdownAllSessions();
       } catch {}
+      try {
+        await stopAllRunEventForwarders();
+      } catch {}
       destroyAutoSession();
       process.exit(exitCode);
     };