agent-coord-mcp 0.26.5 → 0.26.7

package/src/tools/transport.ts

@@ -1,5 +1,7 @@
 import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
 import { newestMtimeUnder, onDiskBuildMtime, onDiskSourceMtime, SERVER_BUILD_MTIME, SERVER_BUILD_SHA, BUILD_DIR } from "../build.js";
+import { prefixOf, prefixVerdict } from "../prefix.js";
+import { execFileSync } from "node:child_process";
 import { registerTool } from "./registry.js";
 import { roleInputSchema, type RoleArg } from "../roles.js";
 import { attributeWriter, isGitRepo, lastWriterOf, loadScopes, ownsDocument } from "./scopes.js";
@@ -307,13 +309,69 @@ function defaultReminderText(agentId: string): string {
   );
 }
 
+/*
+ * REMINDERS ARE OBSERVABLE, because "scheduled" is not "delivered".
+ *
+ * `send_command` returns `reminderScheduled` the instant the timer is set, and
+ * the delivery is an async lockfile-protected append whose only failure path
+ * was a line on stderr. So a reminder could be LATE or LOST and the caller had
+ * already been told it was handled — the same claim-without-a-completion-signal
+ * shape as an empty check rollup reading green.
+ *
+ * MEASURED: `withLock` is configured `retries: 10, minTimeout: 20,
+ * maxTimeout: 200`, so the append is PERMITTED well over a second of backoff.
+ * Under sustained inbox contention the reminder lands at ~420ms. Any assertion
+ * with a wall-clock budget below the lock's own policy is asserting something
+ * the system never promised — which is what made tools.test.mjs:156 fail under
+ * full-suite load and pass everywhere else.
+ *
+ * A longer sleep would convert that race into a slower race. This gives the
+ * work a real completion signal instead, so callers and tests can await the
+ * thing itself rather than guess at a duration.
+ */
+type PendingReminder = { done: Promise<void>; timer: NodeJS.Timeout };
+const pendingReminders = new Set<PendingReminder>();
+
+/** Reminders whose delivery FAILED, kept so a drop is observable, not stderr-only. */
+export const reminderFailures: { to: string; error: string; at: number }[] = [];
+
+/**
+ * Resolves once every scheduled reminder has been delivered or has failed.
+ *
+ * Re-`ref`s the pending timers for the duration of the wait. The reminder timer
+ * is deliberately `unref`d so it never holds the MCP server open on its own —
+ * but that also means the event loop will not wait for it, and awaiting an
+ * unref'd timer's promise hangs until the loop drains. A caller that has
+ * explicitly asked to wait is stating the opposite intent, so the ref is
+ * restored for exactly that window and dropped again afterwards.
+ *
+ * (The unref has a production consequence worth naming: if the server's
+ * transport closes before the timer fires, the reminder is dropped. That is a
+ * separate defect from the one this function fixes — reported, not silently
+ * papered over.)
+ */
+export function remindersSettled(): Promise<void> {
+  const pending = [...pendingReminders];
+  for (const p of pending) p.timer.ref();
+  return Promise.all(pending.map((p) => p.done)).then(() => {
+    for (const p of pending) p.timer.unref();
+  });
+}
+
 function scheduleReminders(
   from: string,
   recipients: string[],
   delayMs: number,
   override: string | undefined,
 ): void {
+  // Registered BEFORE the timer fires, so awaiting settlement covers the delay
+  // as well as the write — otherwise a caller could observe "nothing pending"
+  // during the window between scheduling and firing.
+  let markDone: () => void = () => {};
+  const done = new Promise<void>((resolve) => { markDone = resolve; });
+  let entry: PendingReminder;
   const t = setTimeout(async () => {
+   try {
     for (const r of recipients) {
       try {
         const reminder: Message = {
@@ -328,12 +386,20 @@ function scheduleReminders(
         };
         await appendJsonl(inboxFile(r), reminder);
       } catch (e) {
-        process.stderr.write(
-          `[send_command] post-/clear reminder to '${r}' failed: ${(e as Error)?.message ?? e}\n`,
-        );
+        const error = (e as Error)?.message ?? String(e);
+        // Recorded, not just printed: a dropped reminder leaves a just-cleared
+        // agent contextless, and stderr is not somewhere anyone looks for that.
+        reminderFailures.push({ to: r, error, at: Date.now() });
+        process.stderr.write(`[send_command] post-/clear reminder to '${r}' failed: ${error}\n`);
       }
     }
+   } finally {
+    pendingReminders.delete(entry);
+    markDone();
+   }
   }, delayMs);
+  entry = { done, timer: t };
+  pendingReminders.add(entry);
   // Don't keep the event loop alive solely for the reminder — the MCP server's
   // transport already holds it open as long as it's connected.
   if (typeof t.unref === "function") t.unref();
@@ -639,6 +705,11 @@ export async function attachAgentTool(args: {
     // code, and after an in-place rebuild the two differ (that difference is
     // exactly what doctor's provenance check exists to surface).
     serverBuildMtime: SERVER_BUILD_MTIME,
+    // WHAT this transport carries, recorded by the code that decides it.
+    // `includeRoom` is what the pusher is actually spawned with a few lines
+    // above, so the marker cannot claim a capability the process was not
+    // given — the marker and the spawn come from one value, not two.
+    rooms: includeRoom,
   };
   // Use updateJson so it lockfile-protects and creates the file atomically.
   await updateJson<TransportMarker>(transportFile(args.agentId), marker, () => marker);
@@ -941,6 +1012,10 @@ export const reportTransportSchema = {
   // counterpart has been upgraded since. The remote pusher passes
   // `(await fsp.stat(__filename)).mtimeMs`; absent → doctor skips the check.
   scriptMtime: z.number().optional(),
+  // Whether this pusher carries room traffic as well as DMs. Absent → the
+  // marker cannot say, and every reader reports UNKNOWN rather than assuming
+  // a full transport (the worker-2 shape).
+  rooms: z.boolean().optional(),
 };
 
 // Called by an external push daemon (typically scripts/coord-pusher.mjs on a
@@ -954,6 +1029,7 @@ export async function reportTransportTool(args: {
   host?: string;
   since?: number;
   scriptMtime?: number;
+  rooms?: boolean;
 }) {
   const marker: TransportMarker = {
     agentId: args.agentId,
@@ -963,6 +1039,7 @@ export async function reportTransportTool(args: {
     host: args.host,
     since: args.since ?? Date.now(),
     scriptMtime: args.scriptMtime,
+    rooms: args.rooms,
   };
   await updateJson<TransportMarker>(transportFile(args.agentId), marker, () => marker);
   return { ok: true, marker };
@@ -1212,6 +1289,25 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     });
   }
 
+  // 1b³. WHERE A NEW GLOBAL INSTALL WOULD LAND, which is a different question
+  //      from which copy is running (1b² above) and neither substitutes. On
+  //      this box `npm prefix -g` and the fleet's actual load path pointed at
+  //      two different nvm versions, so an install that printed success would
+  //      have updated a copy nothing loads.
+  {
+    const loadPrefix = prefixOf(BUILD_DIR);
+    let installPrefix: string | null = null;
+    let npmPath: string | undefined;
+    try {
+      installPrefix = execFileSync("npm", ["prefix", "-g"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+      npmPath = execFileSync("which", ["npm"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    } catch {
+      installPrefix = null;
+    }
+    const v = prefixVerdict(loadPrefix, installPrefix, npmPath);
+    findings.push({ check: "install-prefix", level: v.level, detail: v.detail, fixable: false });
+  }
+
   // 1b²ᵇ. The affirmative catch for merged-but-never-rebuilt: src/ newer than
   //       the compiled build means no restart can help — the artifact every
   //       future session will load is already behind the code. Distinct from

package/src/tools/worktrees.ts

@@ -0,0 +1,311 @@
+/*
+ * `ensure_worktree` — the worktree invariant as a verb.
+ *
+ * `git worktree add` lives on five cards as a RECIPE, which means it is followed
+ * from memory and skipped under pressure. The failure it prevents is not
+ * theoretical: a shared checkout is how two agents' edits land in one tree, and
+ * the primary checkout is the one everybody reaches for because it is the path
+ * they already have.
+ *
+ * CUT FROM `origin/<base>`, NEVER A LOCAL BRANCH. A local `main` is whatever the
+ * last person left there; `origin/<base>` is what everyone else will merge into.
+ * This is the same rule as `land`'s target-tip check, one step earlier: the
+ * question is always "what does the thing I am merging into have?".
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+
+/**
+ * Compare paths by their REAL path, never by string.
+ *
+ * git reports `/private/var/...` where a caller passes `/var/...` — macOS's
+ * symlink — so `path.resolve` comparison silently MISSES the primary and the
+ * guard that refuses it never fires. The same symlink cost a carrier check its
+ * main-module guard earlier today: it exited 0 having done nothing.
+ */
+const samePath = (a: string, b: string): boolean => {
+  const real = (x: string) => {
+    try {
+      return realpathSync(x);
+    } catch {
+      return path.resolve(x);
+    }
+  };
+  return real(a) === real(b);
+};
+
+const git = (repo: string, args: string[]): string =>
+  execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+/** Every worktree git knows about: `{path, branch, bare}` in list order. The
+ *  FIRST entry is the primary checkout — that is what `--porcelain` guarantees. */
+export function listWorktrees(repo: string): { path: string; branch: string | null }[] {
+  const out: { path: string; branch: string | null }[] = [];
+  let cur: { path: string; branch: string | null } | null = null;
+  for (const line of git(repo, ["worktree", "list", "--porcelain"]).split("\n")) {
+    if (line.startsWith("worktree ")) {
+      if (cur) out.push(cur);
+      cur = { path: line.slice(9), branch: null };
+    } else if (line.startsWith("branch ") && cur) {
+      cur.branch = line.slice(7).replace(/^refs\/heads\//, "");
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/** The primary checkout — the tree nobody may be given for a slice. */
+export function primaryOf(repo: string): string | null {
+  const all = listWorktrees(repo);
+  return all.length ? (all[0] as { path: string }).path : null;
+}
+
+const isDirty = (repo: string): boolean => {
+  try {
+    return git(repo, ["status", "--porcelain"]).length > 0;
+  } catch {
+    return true; // unreadable is not clean
+  }
+};
+
+export const ensureWorktreeSchema = {
+  agentId: z.string().min(1),
+  repo: z.string().min(1),
+  base: z.string().min(1),
+  task: z.string().optional(),
+  ephemeral: z.boolean().optional(),
+  parent: z.string().optional(),
+};
+
+export async function ensureWorktreeTool(args: {
+  agentId: string;
+  repo: string;
+  base: string;
+  task?: string;
+  ephemeral?: boolean;
+  parent?: string;
+}) {
+  const { agentId, repo, base } = args;
+  if (!path.isAbsolute(repo)) return { ok: false as const, error: `repo must be an absolute path, got '${repo}'` };
+  if (!existsSync(repo)) return { ok: false as const, error: `no such repo: ${repo}` };
+
+  let primary: string | null;
+  try {
+    primary = primaryOf(repo);
+  } catch (e) {
+    return { ok: false as const, error: `not a git repository (${String((e as Error).message).split("\n")[0]})` };
+  }
+
+  // `repo` IS the primary checkout in normal use — that is how you address the
+  // repository. What must never happen is HANDING AN AGENT THE PRIMARY as its
+  // slice tree, so the refusal is on the computed TARGET, not on the input.
+  //
+  // Reading spec 1.4 literally ("calling with the primary path exits non-zero")
+  // would refuse every call and make the verb unusable, since `repo` is always
+  // the primary. The invariant it protects is the one implemented here: two
+  // agents editing one tree. Flagged in the PR rather than silently chosen.
+  return await create({ ...args, primary: primary ?? repo });
+}
+
+async function create(a: {
+  agentId: string;
+  repo: string;
+  base: string;
+  task?: string;
+  ephemeral?: boolean;
+  parent?: string;
+  primary: string;
+}) {
+  const { repo, base, agentId, primary } = a;
+
+  // The BASE must exist as a REMOTE ref. A missing `origin/<base>` is refused
+  // rather than silently falling back to a local branch of the same name — the
+  // local one is whatever the last person left there.
+  const ref = `origin/${base}`;
+  let sha: string;
+  try {
+    git(repo, ["fetch", "--quiet", "origin", base]);
+  } catch {
+    /* offline or no remote: fall through to the rev-parse, which is the real test */
+  }
+  try {
+    sha = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`]);
+  } catch {
+    return {
+      ok: false as const,
+      error: `${ref} does not resolve — refusing to cut a tree from a local '${base}', which is whatever the last person left there. Fetch the remote, or name a base that exists on origin.`,
+    };
+  }
+
+  // ONE PROJECT PARENT: trees live beside the primary, named for the agent, so a
+  // stray tree is identifiable without opening it.
+  const parent = a.parent ?? path.dirname(primary);
+  const leaf = `${path.basename(primary)}-${agentId}${a.ephemeral ? "-ephemeral" : ""}`;
+  const target = path.join(parent, leaf);
+  const branch = a.task ? `${agentId}/${a.task}` : `${agentId}/work`;
+
+  // DEFENCE IN DEPTH, AND IT IS CURRENTLY UNREACHABLE — stated because a guard
+  // that cannot fire is worth nothing until someone knows it cannot.
+  //
+  // The leaf is always `<primary-basename>-<agentId>`, so the target can never
+  // equal the primary while that naming holds. I tried to write a test that
+  // reaches this branch and could not without symlink contrivance; the honest
+  // conclusion is that the NAMING is the real invariant and this is a backstop
+  // for the day someone changes it. It is kept rather than deleted for exactly
+  // that day, and labelled rather than left looking load-bearing.
+  //
+  // What actually protects the invariant is tested instead: the target always
+  // differs from the primary, for any agent id.
+  if (samePath(target, primary)) {
+    return {
+      ok: false as const,
+      error:
+        `refusing to hand back the PRIMARY checkout (${primary}) as a slice tree — that is the path everyone already has, ` +
+        `so it is the one two agents end up editing at once. Pass a different parent or agentId.`,
+    };
+  }
+
+  const existing = listWorktrees(repo).find((w) => samePath(w.path, target));
+  if (existing) {
+    // IDEMPOTENT, and it reports what it FOUND rather than what it would have
+    // made: a verb that silently returns a tree on a different branch than asked
+    // for is the adjacent-answer shape.
+    const head = git(existing.path, ["rev-parse", "HEAD"]);
+    // IS THE REUSED TREE ACTUALLY AT THE BASE IT CLAIMS?
+    //
+    // The verb warned when an existing tree was on a different BRANCH and said
+    // nothing about it being behind the BASE — so a tree left on last week's
+    // main was handed back as ready. Starting a new task there produces the
+    // "stale main -> confidently-wrong inventories" failure the worker card
+    // already warns about, and nothing about the result looks stale.
+    //
+    // Reported here, not refused: an existing tree legitimately holds
+    // in-progress work mid-slice (1.3). The refusal belongs to `claim`, which
+    // is the verb that means "start something new".
+    let atBase = false;
+    let behindBy: number | null = null;
+    try {
+      const baseSha = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`]);
+      atBase = head === baseSha;
+      if (!atBase) behindBy = Number(git(existing.path, ["rev-list", "--count", `HEAD..${ref}`])) || 0;
+    } catch {
+      // NOT MEASURED IS NOT AT-BASE. Leaving `atBase` false is the safe
+      // direction: it makes `claim` ask rather than assume.
+      atBase = false;
+    }
+    return {
+      ok: true as const,
+      path: existing.path,
+      sha: head,
+      branch: existing.branch,
+      created: false,
+      base: ref,
+      atBase,
+      behindBy: behindBy ?? 0,
+      ...(existing.branch !== branch
+        ? { warning: `existing tree is on '${existing.branch}', not the '${branch}' this call would have created — reusing it, NOT re-pointing it` }
+        : {}),
+    };
+  }
+
+  try {
+    git(repo, ["worktree", "add", "-q", "-b", branch, target, sha]);
+  } catch (e) {
+    return { ok: false as const, error: `git worktree add failed: ${String((e as Error).message).split("\n")[0]}` };
+  }
+  return {
+    ok: true as const,
+    path: target,
+    sha,
+    branch,
+    created: true,
+    base: ref,
+    // Cut from `sha`, which IS origin/<base> — true by construction here, and
+    // stated so callers need not special-case "created" to know it.
+    atBase: true,
+    behindBy: 0,
+    ...(a.ephemeral
+      ? { ephemeral: true, removeWith: `git -C ${repo} worktree remove --force ${target} && git -C ${repo} branch -D ${branch}` }
+      : {}),
+  };
+}
+
+// ---------- 1.2 / 1.3: refresh idle trees, never mid-slice ----------
+
+export const refreshWorktreesSchema = {
+  repo: z.string().min(1),
+  base: z.string().min(1),
+  apply: z.boolean().optional(),
+};
+
+/**
+ * Fast-forward IDLE trees onto `origin/<base>`. Never `--force`, never a
+ * mid-slice tree.
+ *
+ * A tree is MID-SLICE when it is dirty or holds commits the base does not.
+ * Pulling under someone's feet is worse than staleness: staleness is visible in
+ * a diff, a clobbered work-in-progress is not. So dirty or diverged is REFUSED
+ * per tree and named, and the run continues for the others.
+ */
+export async function refreshWorktreesTool(args: { repo: string; base: string; apply?: boolean }) {
+  const { repo, base } = args;
+  const ref = `origin/${base}`;
+  try {
+    git(repo, ["fetch", "--quiet", "origin", base]);
+  } catch {
+    /* reported per tree below */
+  }
+  let tip: string;
+  try {
+    tip = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`]);
+  } catch {
+    return { ok: false as const, error: `${ref} does not resolve — nothing to fast-forward onto` };
+  }
+
+  const results = [];
+  for (const w of listWorktrees(repo)) {
+    const at = w.path;
+    if (samePath(at, primaryOf(repo) ?? "")) {
+      results.push({ path: w.path, action: "skipped", why: "primary checkout — not a slice tree" });
+      continue;
+    }
+    if (isDirty(at)) {
+      results.push({ path: w.path, action: "refused", why: "MID-SLICE: uncommitted changes. Pulling here would clobber work a diff cannot show." });
+      continue;
+    }
+    let head: string;
+    try {
+      head = git(at, ["rev-parse", "HEAD"]);
+    } catch {
+      results.push({ path: w.path, action: "refused", why: "unreadable HEAD" });
+      continue;
+    }
+    if (head === tip) {
+      results.push({ path: w.path, action: "current", why: `already at ${ref}` });
+      continue;
+    }
+    let ahead = "0";
+    try {
+      ahead = git(at, ["rev-list", "--count", `${tip}..HEAD`]);
+    } catch {
+      /* treated as diverged below */
+    }
+    if (ahead !== "0") {
+      results.push({ path: w.path, action: "refused", why: `MID-SLICE: ${ahead} commit(s) not on ${ref}. Refusing rather than --force.` });
+      continue;
+    }
+    if (!args.apply) {
+      results.push({ path: w.path, action: "would-fast-forward", why: `behind ${ref}` });
+      continue;
+    }
+    try {
+      git(at, ["merge", "--ff-only", tip]);
+      results.push({ path: w.path, action: "fast-forwarded", why: `to ${tip.slice(0, 8)}` });
+    } catch (e) {
+      results.push({ path: w.path, action: "refused", why: `ff-only failed: ${String((e as Error).message).split("\n")[0]}` });
+    }
+  }
+  return { ok: true as const, base: ref, tip: tip.slice(0, 8), applied: args.apply === true, trees: results };
+}