agent-coord-mcp 0.26.4 → 0.26.6

package/dist/tools/worktrees.js

@@ -0,0 +1,264 @@
+/*
+ * `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, b) => {
+    const real = (x) => {
+        try {
+            return realpathSync(x);
+        }
+        catch {
+            return path.resolve(x);
+        }
+    };
+    return real(a) === real(b);
+};
+const git = (repo, args) => 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) {
+    const out = [];
+    let cur = 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) {
+    const all = listWorktrees(repo);
+    return all.length ? all[0].path : null;
+}
+const isDirty = (repo) => {
+    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) {
+    const { agentId, repo, base } = args;
+    if (!path.isAbsolute(repo))
+        return { ok: false, error: `repo must be an absolute path, got '${repo}'` };
+    if (!existsSync(repo))
+        return { ok: false, error: `no such repo: ${repo}` };
+    let primary;
+    try {
+        primary = primaryOf(repo);
+    }
+    catch (e) {
+        return { ok: false, error: `not a git repository (${String(e.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) {
+    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;
+    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,
+            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,
+            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"]);
+        return {
+            ok: true,
+            path: existing.path,
+            sha: head,
+            branch: existing.branch,
+            created: false,
+            base: ref,
+            ...(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, error: `git worktree add failed: ${String(e.message).split("\n")[0]}` };
+    }
+    return {
+        ok: true,
+        path: target,
+        sha,
+        branch,
+        created: true,
+        base: ref,
+        ...(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) {
+    const { repo, base } = args;
+    const ref = `origin/${base}`;
+    try {
+        git(repo, ["fetch", "--quiet", "origin", base]);
+    }
+    catch {
+        /* reported per tree below */
+    }
+    let tip;
+    try {
+        tip = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`]);
+    }
+    catch {
+        return { ok: false, 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;
+        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.message).split("\n")[0]}` });
+        }
+    }
+    return { ok: true, base: ref, tip: tip.slice(0, 8), applied: args.apply === true, trees: results };
+}
+//# sourceMappingURL=worktrees.js.map

package/dist/tools/worktrees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktrees.js","sourceRoot":"","sources":["../../src/tools/worktrees.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.4",
+  "version": "0.26.6",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.). Local stdio or networked over Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -46,7 +46,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "proper-lockfile": "^4.1.2",
     "zod": "^4.4.3",
-    "@davidbalzan/groundwork-seam": "0.1.6"
+    "@davidbalzan/groundwork-seam": "0.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/scripts/check-test-count.mjs

@@ -22,7 +22,7 @@
 
 import { spawn } from "node:child_process";
 
-const EXPECTED_TESTS = 347;
+const EXPECTED_TESTS = 452;
 
 const expected = Number(process.env.AGENT_COORD_EXPECTED_TESTS ?? EXPECTED_TESTS);
 // Same glob the suite always used — `--test test/` would recurse differently

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";