agent-coord-mcp 0.26.5 → 0.26.6

package/src/prefix.ts

@@ -0,0 +1,72 @@
+/*
+ * WHERE WILL A NEW GLOBAL INSTALL LAND, AND IS IT WHERE THE FLEET LOADS FROM?
+ *
+ * These are two different questions and neither answers the other. The
+ * `server-build-drift` check names which copy is RUNNING; this names where the
+ * NEXT copy will be written. A run of `npm i -g agent-coord-mcp` that prints
+ * "added 1 package" is not evidence it landed anywhere that runs.
+ *
+ * MEASURED ON THIS BOX, 2026-08-28 — the divergence is not hypothetical:
+ *   npm prefix -g          -> .../node/v22.22.2
+ *   every live fleet server-> .../node/v22.21.1/lib/node_modules/agent-coord-mcp
+ * Three prefixes exist here (two nvm, one /opt/homebrew), `npm prefix -g` is
+ * PATH-dependent, and nvm switches it per shell. So the install target and the
+ * load target had silently diverged, and a successful install would have
+ * updated a copy nothing loads. That gap cost the fleet a day.
+ */
+import path from "node:path";
+
+/**
+ * The global root a module path sits under, or null if it is not in one.
+ * `/p/lib/node_modules/agent-coord-mcp/dist` -> `/p`
+ */
+export function prefixOf(modulePath: string | undefined): string | null {
+  if (!modulePath) return null;
+  // Split on the LAST occurrence: a global prefix can itself live under a path
+  // containing `node_modules`, and taking the first match would name an
+  // ancestor that installs nothing.
+  const marker = `${path.sep}lib${path.sep}node_modules${path.sep}`;
+  const i = modulePath.lastIndexOf(marker);
+  if (i === -1) return null;
+  return modulePath.slice(0, i);
+}
+
+export type PrefixVerdict =
+  | { level: "ok"; detail: string }
+  | { level: "warn"; detail: string }
+  | { level: "error"; detail: string };
+
+/**
+ * `loadPrefix` is where THIS server was loaded from; `installPrefix` is what
+ * `npm prefix -g` answered, and `npmPath` is which npm answered it — because a
+ * prefix without the binary that reported it cannot be reproduced by anyone.
+ */
+export function prefixVerdict(loadPrefix: string | null, installPrefix: string | null, npmPath?: string): PrefixVerdict {
+  const via = npmPath ? ` (asked: ${npmPath})` : "";
+
+  // NOT DETERMINED IS NOT MATCHING. Both unknown branches are warnings that say
+  // what could not be established, never an "ok" over an unasked question.
+  // NOT APPLICABLE IS NOT THE SAME AS UNCHECKED, and conflating them is how a
+  // check earns its way into being ignored. A dev checkout has no load prefix
+  // BY CONSTRUCTION: this process is not the copy the fleet loads, so there is
+  // no divergence for it to have. Warning on every dev run would fire on every
+  // test run and every local session — noise, which is what a denylist does.
+  //
+  // The question is still ASKED where it can be answered: a session running
+  // from a global install has a load prefix, and that is where the fleet lives.
+  if (!loadPrefix)
+    return { level: "ok", detail: `not applicable: this server runs from a dev checkout, not a global install${via}, so it is not the copy the fleet loads and has no prefix to diverge from. Run \`doctor\` in an installed session to compare install target against load target.` };
+  if (!installPrefix)
+    return { level: "warn", detail: `could not determine the global install prefix${via} — \`npm prefix -g\` gave no answer, so where a new copy would land is UNKNOWN. Running from ${loadPrefix}.` };
+
+  if (path.resolve(loadPrefix) === path.resolve(installPrefix))
+    return { level: "ok", detail: `a global install would land where this server loads from (${loadPrefix})${via}` };
+
+  return {
+    level: "error",
+    detail:
+      `INSTALL PREFIX AND LOAD PREFIX DIVERGE. A global install from this shell writes to ${installPrefix}${via}, but this server is running from ${loadPrefix}. ` +
+      `A successful "added 1 package" would update a copy nothing loads, and every check that reads a VERSION would keep reporting the old one truthfully. ` +
+      `Install with an explicit prefix (\`npm i -g --prefix ${loadPrefix} <pkg>\`) or switch node/nvm to the version owning ${loadPrefix} before installing.`,
+  };
+}

package/src/server.ts

@@ -6,6 +6,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { unlinkSync, writeFileSync } from "node:fs";
 import { z, type ZodRawShape } from "zod";
+import { coordAwaySchema, coordAwayTool, readAway, awayRefusal, secondCoordinatorRefusal } from "./tools/away.js";
+import { rotateSchema, rotateTool, rotateReconcileSchema, rotateReconcileTool } from "./tools/rotate.js";
 import {
   ensureDirs,
   getTokenMap,
@@ -79,6 +81,24 @@ import {
   listScopesTool,
   importWorkSchema,
   importWorkTool,
+  stallCheckSchema,
+  stallCheckTool,
+  setHaltSchema,
+  setHaltTool,
+  lastRanSchema,
+  stallClockStatusTool,
+  ensureWorktreeSchema,
+  ensureWorktreeTool,
+  refreshWorktreesSchema,
+  refreshWorktreesTool,
+  claimSchema,
+  claimTool,
+  landSchema,
+  landTool,
+  mergeSchema,
+  mergeTool,
+  nextUnblockedSchema,
+  nextUnblockedTool,
   listWorkSchema,
   listWorkTool,
   exportWorkSchema,
@@ -250,9 +270,18 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     inputSchema: ZodRawShape,
     cb: (args: Record<string, unknown>) => Promise<ReturnType<typeof jsonResult>>,
   ) => {
-    server.registerTool(name, { description, inputSchema: z.object(inputSchema) }, async (args) =>
-      cb((args ?? {}) as Record<string, unknown>),
-    );
+    server.registerTool(name, { description, inputSchema: z.object(inputSchema) }, async (args) => {
+      const a = (args ?? {}) as Record<string, unknown>;
+      // DUTY-OFFICER ALLOWLIST, ENFORCED IN THE ONE PATH EVERY TOOL IS
+      // REGISTERED THROUGH. Placed here rather than in `gate` because `gate`
+      // does not know the tool's NAME, and because a guard applied per call
+      // site is a guard someone forgets at one call site — where the omission
+      // looks identical to the guarded ones from outside (kit#125).
+      const caller = bound ?? (typeof a["agentId"] === "string" ? (a["agentId"] as string) : typeof a["from"] === "string" ? (a["from"] as string) : undefined);
+      const refusal = awayRefusal(readAway(), caller, name);
+      if (refusal) throw new Error(refusal);
+      return cb(a);
+    });
   };
 
   addTool(
@@ -513,6 +542,90 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     gate(null, listWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  addTool(
+    "stall_check",
+    "The stall predicate over the board and the bus: a 🚧 row whose agent's heartbeat is older than the window, or whose claimed branch has no commits in it. HIT returns the hits for the caller to DM; MISS returns none and sends nothing — but EVERY run, hit or miss, leaves a mark, because a check that only speaks when it fires cannot be told from a broken one. Read the mark with stall_clock_status.",
+    stallCheckSchema,
+    gate(null, stallCheckTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "stall_clock_status",
+    "Is the stall clock alive? Reports when stall_check last ran, how many runs, and how many were misses — so 'no alerts' is distinguishable from 'nothing ran'. Never having run is an ERROR, not a quiet fleet.",
+    lastRanSchema,
+    gate(null, stallClockStatusTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "set_halt",
+    "Set or clear a NAMED halt. While set, `claim` and `next_unblocked` refuse. The reason is required because a halt blocks every lane in the fleet: it must name a board cutover, a cited BLOCKER: or a documented red pipeline — 'production feels down' is not a halt.",
+    setHaltSchema,
+    gate(null, setHaltTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "ensure_worktree",
+    "Create or reuse an isolated git worktree for an agent, cut from origin/<base> (never a local branch of the same name, which is whatever the last person left there). Refuses to hand back the PRIMARY checkout as a slice tree — that is the path everyone already has, so it is the one two agents end up editing at once. Idempotent: an existing tree is reported as found, and if it sits on a different branch that is said rather than re-pointed.",
+    ensureWorktreeSchema,
+    gate(null, ensureWorktreeTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "refresh_worktrees",
+    "Fast-forward IDLE worktrees onto origin/<base>. Never --force and never a mid-slice tree: dirty or holding commits the base does not is REFUSED per tree and named, because staleness is visible in a diff and a clobbered work-in-progress is not. Reports by default; pass apply:true to move them.",
+    refreshWorktreesSchema,
+    gate(null, refreshWorktreesTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "next_unblocked",
+    "The next queue item to work: re-reads docs/QUEUE.md via the seam, orders P1>P2>P3 with document order breaking ties, and SKIPS a blocked item rather than stalling the lane on a reorder (returning the board hunk to record the skip). Also reports items NOTHING WAITS ON as their own axis: an item that blocks nothing announces nothing when it stalls, so its absence is silent and needs an explicit check at a stage boundary.",
+    nextUnblockedSchema,
+    gate(null, nextUnblockedTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "claim",
+    "Bind a queue item to an agent and produce the 🚧 board row. With no itemId it takes next_unblocked. WARNS LOUDLY while `ensure_worktree` (Phase 5 Task 1) does not exist: the claim binds the item and the row only, and creating an isolated worktree at origin/<base> is still yours. The warning is conditional on that verb's absence, so it stops once Task 1 lands.",
+    claimSchema,
+    gate(null, claimTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "land",
+    "Record a merged PR: refuses without a cited PR number, and refuses unless the PR is on the TARGET TIP (origin/<base>) rather than a merge base — an item merged after your branch was cut is missing from the base too, so the base cannot answer 'what does the thing I am merging into have that I do not?'. Closes the queue item STATUS ONLY (priority and body bytes unchanged), proposes the DONE entry, and reports by default: pass write:true to apply.",
+    landSchema,
+    gate(null, landTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "merge",
+    "Merge a PR ONLY as the consequence of its check verdict: reads the status rollup and merges in the same call, so there is no ordering in which the check runs and the merge ignores it. Refuses on any failing check, on any check not yet terminal, on a CONFLICTING base, and on ZERO checks \u2014 no checks is not passing checks, an empty rollup has zero failures and evidences nothing. Every return carries the POPULATION it judged. Reports by default; pass write:true to merge.",
+    mergeSchema,
+    gate(null, mergeTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "coord_away",
+    "Declare the coordinator AWAY with a named duty officer, or RELEASE it. While ON, the duty officer is restricted to an ALLOWLIST (next_unblocked, claim, land, stall_check, and reporting) \u2014 an allowlist rather than a denylist, so a tool added tomorrow is refused by default instead of silently granted. Refuses ON without a dutyOfficerId (an unnamed stand-in reports the lane covered while leaving it uncovered), refuses a self-appointed officer, and refuses RELEASE by anyone but the coordinator who set it \u2014 a stand-in that can lift its own limits does not have any. While ON, a SECOND coordinator cannot join until released.",
+    coordAwaySchema,
+    gate("coordinatorId" as "agentId", coordAwayTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "rotate",
+    "Build a handover-to-self packet from LIVE state (git + gh), never chat memory \u2014 memory is the one source that cannot be re-derived after the reset it is meant to survive. REFUSES while the tree is dirty: uncommitted work is the one thing a packet cannot carry, and after /clear nothing can discover it existed. Jobs are an allowlist (reseed-only | phase-boundary); 'archive-done' is deliberately absent. Reports by default; write:true persists the packet.",
+    rotateSchema,
+    gate("agentId", rotateTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "rotate_reconcile",
+    "FIRST ACT AFTER A RESEED. Re-checks every packet claim against live state and REFUSES to report ready on any divergence \u2014 a PR that merged during the reset is the dangerous direction, because the agent resumes a branch already in main and every next step is coherent and wrong. 'missionHint' is reported as UNVERIFIABLE rather than counted as reconciled.",
+    rotateReconcileSchema,
+    gate("agentId", rotateReconcileTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   addTool(
     "export_work",
     "Render a project's work documents back out of the store, reproducing the pinned glyph contract exactly (ref after the last ' \u2014 ', date after a trailing ' \u00b7 '). Reports by default; pass write:true to rewrite the files. Refuses to export from an empty store rather than blanking a document. Refuses write:true when that write would emit a new 5-col lanes-v0 table (parse-only; write grammar is workstreams.v1). Any declared Task 4 write scope is REPORTED alongside the write, never enforced.",

package/src/tools/away.ts

@@ -0,0 +1,121 @@
+/*
+ * `coord_away` — Phase 5 Task 4.1/4.2.
+ *
+ * WHAT THIS IS NOT: a way to hand the coordinator's judgement to someone else.
+ * A duty officer keeps the lane MOVING while the coordinator is away; it does
+ * not inherit the authority to decide what the lane is for. The distinction is
+ * the whole point, so it is enforced as an ALLOWLIST rather than a denylist:
+ * a new tool added tomorrow is refused by default, and someone must decide, in
+ * writing, that a duty officer may call it.
+ *
+ * A denylist would have the opposite failure — every tool anyone forgets to
+ * list is silently granted — which is the same shape as an empty check rollup
+ * scoring green (kit#125): absence read as permission.
+ *
+ * ENFORCEMENT LIVES IN `addTool`, THE SINGLE PATH EVERY TOOL IS REGISTERED
+ * THROUGH, for the reason kit#125 folded the check into the merge call: a
+ * guard repeated at call sites is a guard someone forgets at one call site,
+ * and the forgotten one looks identical to the guarded ones from outside.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+
+const awayFile = () => path.join(ROOT, "coord-away.json");
+
+/**
+ * WHAT A DUTY OFFICER MAY DO: move claimed work along and report.
+ *
+ * Deliberately absent, each for its own reason rather than by omission:
+ *   `merge`          — merging is a judgement about whether work is DONE.
+ *   `register`/`join` w/ coordinator role — see `secondCoordinatorRefusal`.
+ *   grow-fleet verbs — a stand-in does not get to change the fleet's shape.
+ *   CANON writes     — canon outlives the absence that created the stand-in.
+ */
+export const DUTY_OFFICER_ALLOWLIST = ["next_unblocked", "claim", "land", "stall_check", "stall_clock_status", "post_status", "send_message", "read_messages", "status", "heartbeat", "list_work"] as const;
+
+export type AwayState = { on: boolean; project: string; coordinatorId: string; dutyOfficerId: string; until?: string; at: string };
+
+export function readAway(): Record<string, AwayState> {
+  const f = awayFile();
+  if (!existsSync(f)) return {};
+  try {
+    return JSON.parse(readFileSync(f, "utf8")) as Record<string, AwayState>;
+  } catch {
+    return {};
+  }
+}
+
+function writeAway(state: Record<string, AwayState>): void {
+  mkdirSync(ROOT, { recursive: true });
+  writeFileSync(awayFile(), `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/**
+ * The refusal a duty officer gets, or null if the call is allowed.
+ *
+ * Only the DUTY OFFICER is constrained. Everyone else's lane is unchanged:
+ * `coord-away` is not a freeze on the project, and a worker whose tools stop
+ * working because the coordinator stepped out would simply stop calling them.
+ */
+export function awayRefusal(state: Record<string, AwayState>, agentId: string | undefined, tool: string): string | null {
+  if (!agentId) return null;
+  const held = Object.values(state).find((s) => s.on && s.dutyOfficerId === agentId);
+  if (!held) return null;
+  if ((DUTY_OFFICER_ALLOWLIST as readonly string[]).includes(tool)) return null;
+  return `'${tool}' is not on the duty-officer allowlist. You are standing in for '${held.coordinatorId}' on '${held.project}' while coord-away is ON: a duty officer keeps the lane MOVING and does not inherit the authority to decide what it is for. Allowed: ${DUTY_OFFICER_ALLOWLIST.join(", ")}. If this genuinely needs doing, it needs ${held.coordinatorId} back or David — not a wider allowlist added in the moment.`;
+}
+
+/**
+ * 4.2 — a SECOND coordinator may not join while the first is away.
+ *
+ * Not a lock for its own sake: two coordinators is the condition under which
+ * two GOs can be issued for one lane, and the absent one cannot see the other
+ * arrive. The duty officer exists precisely so the seat is not empty, so a
+ * second claimant is a fleet-shape change, which is the category `coord_away`
+ * refuses by construction.
+ */
+export function secondCoordinatorRefusal(state: Record<string, AwayState>, agentId: string, roleId: string | undefined): string | null {
+  if (roleId !== "coordinator") return null;
+  const held = Object.values(state).find((s) => s.on && s.coordinatorId !== agentId);
+  if (!held) return null;
+  return `coord-away is HELD on '${held.project}' by '${held.coordinatorId}' (duty officer '${held.dutyOfficerId}'). A second coordinator cannot join until it is RELEASED — two coordinators is the condition under which one lane gets two GOs, and the absent one cannot see the second arrive.`;
+}
+
+export const coordAwaySchema = {
+  project: z.string().min(1),
+  on: z.boolean(),
+  coordinatorId: z.string().min(1),
+  dutyOfficerId: z.string().optional(),
+  until: z.string().optional(),
+};
+
+export async function coordAwayTool(args: { project: string; on: boolean; coordinatorId: string; dutyOfficerId?: string; until?: string }) {
+  const state = readAway();
+  const prior = state[args.project];
+
+  if (args.on) {
+    // A STAND-IN WITH NO NAME IS AN EMPTY SEAT DESCRIBED AS COVERED, which is
+    // strictly worse than a seat everyone can see is empty.
+    if (!args.dutyOfficerId) return { ok: false as const, error: `coord-away ON requires a dutyOfficerId. Turning it on without naming a stand-in reports the lane as covered while leaving it uncovered.` };
+    if (args.dutyOfficerId === args.coordinatorId) return { ok: false as const, error: `'${args.coordinatorId}' cannot be its own duty officer.` };
+    if (prior?.on && prior.coordinatorId !== args.coordinatorId) return { ok: false as const, error: `coord-away is already HELD on '${args.project}' by '${prior.coordinatorId}'. Release it first.` };
+    state[args.project] = { on: true, project: args.project, coordinatorId: args.coordinatorId, dutyOfficerId: args.dutyOfficerId, until: args.until, at: new Date().toISOString() };
+    writeAway(state);
+    return {
+      ok: true as const,
+      state: state[args.project],
+      allowlist: DUTY_OFFICER_ALLOWLIST,
+      announce: `AGENT_ACTION: coord-away ON — '${args.coordinatorId}' away${args.until ? ` until ${args.until}` : ""}; '${args.dutyOfficerId}' is duty officer, limited to: ${DUTY_OFFICER_ALLOWLIST.join(", ")}. A second coordinator cannot join until released.`,
+    };
+  }
+
+  // RELEASE IS THE COORDINATOR'S. A duty officer releasing its own limits is
+  // the limit not existing — the one call it must not be able to make.
+  if (!prior?.on) return { ok: false as const, error: `coord-away is not on for '${args.project}' — nothing to release.` };
+  if (prior.coordinatorId !== args.coordinatorId) return { ok: false as const, error: `coord-away on '${args.project}' is held by '${prior.coordinatorId}' and only they can release it. A stand-in that can lift its own limits does not have any.` };
+  state[args.project] = { ...prior, on: false, at: new Date().toISOString() };
+  writeAway(state);
+  return { ok: true as const, state: state[args.project], announce: `AGENT_ACTION: coord-away RELEASED on '${args.project}' — '${prior.coordinatorId}' is back; '${prior.dutyOfficerId}' stands down.` };
+}

package/src/tools/index.ts

@@ -6,3 +6,6 @@ export * from "./transport.js";
 export * from "./admin.js";
 export * from "./scopes.js";
 export * from "./work.js";
+export * from "./records.js";
+export * from "./worktrees.js";
+export * from "./stall.js";