agent-coord-mcp 0.26.18 → 0.26.20

package/src/tools/worktrees.ts

@@ -227,42 +227,18 @@ async function create(a: {
     atBase: true,
     behindBy: 0,
     ...(a.ephemeral
-      ? { ephemeral: true, removeWith: `git -C ${repo} worktree remove --force ${target} && git -C ${repo} branch -D ${branch}` }
+      ? {
+          ephemeral: true,
+          // A VERB NAME, NOT A COMMAND LINE. This used to hand back the shell to
+          // paste — the tool knew the repo, path and branch and spent the agent's
+          // tokens on work it could do itself.
+          releaseWith: { verb: "release_worktree", args: { repo, path: target, apply: true } },
+        }
       : {}),
   };
 }
 
-// ---------- 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` };
-  }
+// ---------- shared: is this tree's work already in the base? ----------
 
 /**
  * Are the commits HEAD has beyond `tip` ALREADY LANDED there?
@@ -303,6 +279,39 @@ function aheadIsLanded(at: string, tip: string): boolean {
     .every((l) => l.trim().startsWith("-"));
 }
 
+// ---------- 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;
@@ -415,3 +424,196 @@ function aheadIsLanded(at: string, tip: string): boolean {
   }
   return { ok: true as const, base: ref, tip: tip.slice(0, 8), applied: args.apply === true, trees: results };
 }
+
+// ---------- the counterpart to ensure_worktree: give the tree back ----------
+
+/*
+ * `ensure_worktree` CREATED trees and nothing RELEASED them, so teardown stayed a
+ * hand step in five role cards — `git worktree prune` in coord-audit, coord-ci,
+ * coord-qa and coord-worker, `git worktree remove` twice in coordinator, which
+ * says so itself: "it never removes, so `git worktree remove`/`prune` remain hand
+ * steps". Seven commands for one act the bus already had the inputs for.
+ *
+ * WORSE THAN ABSENT: `ensure_worktree` COMPUTED the teardown command and handed it
+ * back as a string for the agent to paste (`removeWith`). The tool knew the repo,
+ * the path and the branch, and spent the agent's tokens on shell it could have run.
+ * That is the shape David ruled against: "where possible we should hide the
+ * plumbing from the agents".
+ *
+ * THE REFUSALS ARE THE POINT, and they inherit `refresh_worktrees`' direction —
+ * report by default, refuse per tree with the reason named, never clobber:
+ *
+ *   - THE PRIMARY CHECKOUT IS NEVER RELEASED. It is the path everyone already has.
+ *   - A DIRTY TREE IS REFUSED. Uncommitted work is what a diff cannot show and git
+ *     cannot give back, so this is the one refusal with no override.
+ *   - A TREE HOLDING UNLANDED COMMITS IS REFUSED — and "unlanded" is decided by
+ *     `aheadIsLanded` (patch ids), NOT by ancestry. Under squash merge a landed
+ *     branch's shas never enter the base, so ancestry calls every finished tree
+ *     mid-slice forever (q-5c40db91). Using ancestry here would refuse to release
+ *     exactly the trees that are safe to release, which is how the hand step
+ *     survived: the guard would have been wrong and everyone would have forced it.
+ *
+ * A NEGATIVE FROM `aheadIsLanded` IS INCONCLUSIVE, NOT A NO. Several commits squashed
+ * into one carry a different combined patch id, so it cannot prove landedness for
+ * every shape. It therefore refuses and says the check was inconclusive rather than
+ * claiming the work is unlanded — the caller lands it, or passes `force:true`, which
+ * is recorded in the result so a forced release is findable afterwards.
+ */
+export const releaseWorktreeSchema = {
+  repo: z.string().min(1),
+  agentId: z.string().min(1).optional(),
+  path: z.string().min(1).optional(),
+  base: z.string().min(1).optional(),
+  apply: z.boolean().optional(),
+  force: z.boolean().optional(),
+};
+
+export async function releaseWorktreeTool(args: {
+  repo: string;
+  agentId?: string;
+  path?: string;
+  base?: string;
+  apply?: boolean;
+  force?: boolean;
+}) {
+  const { repo } = args;
+  if (!args.agentId && !args.path) {
+    return { ok: false as const, error: "name the tree to release: pass `agentId` or `path`" };
+  }
+
+  const trees = listWorktrees(repo);
+  const primary = primaryOf(repo) ?? "";
+  const target = args.path
+    ? trees.find((w) => samePath(w.path, args.path as string))
+    : trees.find((w) => (w.branch ?? "").includes(args.agentId as string) || w.path.includes(args.agentId as string));
+
+  if (!target) {
+    return {
+      ok: false as const,
+      error: args.path
+        ? `no worktree at '${args.path}' — nothing to release`
+        : `no worktree found for '${args.agentId}' — nothing to release`,
+      // An ABSENCE is reported with what WAS found, so a misaimed lookup is
+      // distinguishable from an empty world (the positive-control rule).
+      known: trees.map((w) => ({ path: w.path, branch: w.branch })),
+    };
+  }
+
+  const at = target.path;
+  const branch = target.branch;
+
+  if (samePath(at, primary)) {
+    return {
+      ok: false as const,
+      error: `refusing to release ${at}: that is the PRIMARY checkout, the path everyone already has`,
+      path: at,
+    };
+  }
+
+  if (isDirty(at)) {
+    return {
+      ok: false as const,
+      error:
+        `refusing to release ${at}: the tree is DIRTY. Uncommitted work is what a diff cannot show and ` +
+        `git cannot give back, so this refusal has no override — commit it, stash it, or delete it by hand.`,
+      path: at,
+      branch,
+      dirty: true,
+    };
+  }
+
+  const base = args.base ?? "main";
+  const ref = `origin/${base}`;
+  let tip: string | null = null;
+  try {
+    git(repo, ["fetch", "--quiet", "origin", base]);
+  } catch {
+    /* a stale tip is reported below rather than guessed at */
+  }
+  try {
+    tip = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`]);
+  } catch {
+    tip = null;
+  }
+
+  let ahead = "unknown";
+  if (tip) {
+    try {
+      ahead = git(at, ["rev-list", "--count", `${tip}..HEAD`]);
+    } catch {
+      /* left unknown — an unreadable count must not read as zero */
+    }
+  }
+
+  const holdsWork = ahead !== "0";
+  const landed = tip && holdsWork ? aheadIsLanded(at, tip) : true;
+
+  if (!tip) {
+    return {
+      ok: false as const,
+      error: `refusing to release ${at}: ${ref} does not resolve, so whether this tree's work landed cannot be measured`,
+      path: at,
+      branch,
+    };
+  }
+
+  if (holdsWork && !landed && !args.force) {
+    return {
+      ok: false as const,
+      error:
+        `refusing to release ${at}: it is ${ahead} commit(s) ahead of ${ref} and the patch-id check was ` +
+        `INCONCLUSIVE — not proof the work is unlanded, but not proof it landed either (several commits ` +
+        `squashed into one carry a different combined patch id). Land it, or pass force:true, which is recorded.`,
+      path: at,
+      branch,
+      ahead,
+      landedCheck: "inconclusive",
+    };
+  }
+
+  const plan = {
+    path: at,
+    branch,
+    ahead,
+    landedCheck: holdsWork ? (landed ? "landed" : "inconclusive") : "nothing-ahead",
+    ...(args.force && holdsWork && !landed ? { forced: true } : {}),
+  };
+
+  if (!args.apply) {
+    return {
+      ok: true as const,
+      applied: false,
+      would: "remove the worktree and delete its branch",
+      ...plan,
+      note: "reports by default; pass apply:true to remove",
+    };
+  }
+
+  try {
+    git(repo, ["worktree", "remove", "--force", at]);
+  } catch (e) {
+    return {
+      ok: false as const,
+      error: `worktree remove failed: ${String((e as Error).message).split("\n")[0]}`,
+      ...plan,
+    };
+  }
+  // PRUNE IS PART OF THE ACT, not a step the caller remembers. Every card that
+  // said `git worktree remove` also said `git worktree prune`, which is the
+  // clearest evidence they were one operation split across two lines of prose.
+  try {
+    git(repo, ["worktree", "prune"]);
+  } catch {
+    /* removal already succeeded; a failed prune is not worth failing the call */
+  }
+  let branchDeleted = false;
+  if (branch) {
+    try {
+      git(repo, ["branch", "-D", branch.replace(/^refs\/heads\//, "")]);
+      branchDeleted = true;
+    } catch {
+      /* a branch that will not delete is reported, not fatal */
+    }
+  }
+  return { ok: true as const, applied: true, removed: true, branchDeleted, ...plan };
+}

package/src/transports/config.ts

@@ -0,0 +1,110 @@
+/**
+ * WHICH TRANSPORT THIS FLEET IS CONFIGURED TO USE (Phase 5.4 Task 3.1–3.2).
+ *
+ * Whole-fleet, read ONCE at startup, per David 2026-09-11 — no per-seat
+ * branching in `send_command` or `attach`. Memoised for that reason and not for
+ * speed: a value that can be re-read mid-process is a value that can change
+ * mid-process, and then two calls in one session disagree about what the fleet
+ * is doing.
+ *
+ * ⛔ AN UNKNOWN VALUE REFUSES AT STARTUP. It does not fall back to `tmux-push`.
+ *
+ * The reason is not tidiness. A SILENT FALLBACK AND A CORRECT DEFAULT PRODUCE
+ * IDENTICAL EVIDENCE: both give you a fleet on tmux with nothing in any log, so
+ * a typo in the config reads exactly like a deliberate default, and the person
+ * who typed `heardr` spends the afternoon asking why their transport change did
+ * nothing. Refusing is louder than the bug it prevents.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { ROOT } from "../store.js";
+import { TMUX_PUSH, TRANSPORT_KINDS, type TransportKind } from "./types.js";
+
+/** `$AGENT_COORD_DIR/config.json`, the fleet-wide file. */
+export const TRANSPORT_CONFIG_FILE = path.join(ROOT, "config.json");
+export const TRANSPORT_ENV_VAR = "AGENT_COORD_TRANSPORT";
+
+/**
+ * PRECEDENCE, documented here because 3.2 asks for a decision and not a
+ * preference: **config file > env > default**.
+ *
+ * The file wins because it is the FLEET's statement and is reviewable — it sits
+ * on disk where every seat reads the same bytes, and a wrong value can be
+ * corrected in one place. An env var is per-process: it is the right tool for
+ * one seat to deviate deliberately (a test, a bisect), and the wrong tool for
+ * stating what the fleet does, because nothing can see it from outside that
+ * process. So the narrower, less visible source loses to the broader one, and
+ * `source` is reported so a surprising answer can be traced to its origin
+ * rather than guessed at.
+ */
+export type ConfiguredTransport = {
+  kind: TransportKind;
+  source: "config" | "env" | "default";
+  /** Where the value came from, for an error message a human can act on. */
+  origin: string;
+};
+
+function refuse(value: string, origin: string): never {
+  throw new Error(
+    `[agent-coord-mcp] unknown transport ${JSON.stringify(value)} from ${origin}. ` +
+      `Valid: ${TRANSPORT_KINDS.join(", ")}. ` +
+      `REFUSING AT STARTUP rather than falling back to "${TMUX_PUSH}" — a silent fallback and a correct ` +
+      `default leave identical evidence, so a typo here would look exactly like a working default and the ` +
+      `transport change would appear to do nothing. Fix the value or remove it to get the default.`,
+  );
+}
+
+function asKind(value: unknown, origin: string): TransportKind {
+  if (typeof value !== "string" || value.length === 0) refuse(String(value), origin);
+  const match = TRANSPORT_KINDS.find((k) => k === value);
+  if (!match) refuse(value, origin);
+  return match;
+}
+
+let cached: ConfiguredTransport | undefined;
+
+/**
+ * Resolve the fleet's transport. Throws on an unknown value — call it once at
+ * startup so the refusal lands before any agent attaches.
+ */
+export function configuredTransport(): ConfiguredTransport {
+  if (cached) return cached;
+
+  if (existsSync(TRANSPORT_CONFIG_FILE)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(TRANSPORT_CONFIG_FILE, "utf8"));
+    } catch (e) {
+      // A CONFIG FILE THAT CANNOT BE PARSED IS NOT AN ABSENT ONE. Treating it as
+      // absent would silently use the default while a file sits there stating
+      // otherwise — the same two-states-one-evidence defect as the fallback.
+      throw new Error(
+        `[agent-coord-mcp] ${TRANSPORT_CONFIG_FILE} is unreadable (${(e as Error).message}). ` +
+          `REFUSING rather than treating it as absent: a file that exists and cannot be read is not the ` +
+          `same as no file, and defaulting here would hide a stated intent behind a working fleet.`,
+      );
+    }
+    const raw = (parsed as { transport?: unknown } | null)?.transport;
+    if (raw !== undefined) {
+      cached = { kind: asKind(raw, `${TRANSPORT_CONFIG_FILE} ("transport")`), source: "config", origin: TRANSPORT_CONFIG_FILE };
+      return cached;
+    }
+  }
+
+  const env = process.env[TRANSPORT_ENV_VAR];
+  if (env !== undefined && env !== "") {
+    cached = { kind: asKind(env, `$${TRANSPORT_ENV_VAR}`), source: "env", origin: `$${TRANSPORT_ENV_VAR}` };
+    return cached;
+  }
+
+  cached = { kind: TMUX_PUSH, source: "default", origin: `built-in default (${TMUX_PUSH})` };
+  return cached;
+}
+
+/**
+ * Drop the memo. FOR TESTS ONLY — the whole point of reading once is that
+ * production code cannot do this.
+ */
+export function resetConfiguredTransportForTests(): void {
+  cached = undefined;
+}

package/src/transports/index.ts

@@ -0,0 +1,126 @@
+/**
+ * THE REGISTRY — the one place a transport kind is turned into an implementation.
+ *
+ * `resolveTransport` is deliberately total over `TransportKind`: adding a kind to
+ * the union without registering it is a compile error here rather than a silent
+ * fall-through at a call site. Until Task 3, tmux is the only registered
+ * implementation and that is the rollback plan — the seam lands behind no config.
+ */
+import { HERDR, TMUX_PUSH, TMUX_PUSH_REMOTE, type Transport, type TransportKind } from "./types.js";
+import { TmuxTransport, type TmuxHost } from "./tmux.js";
+import { configuredTransport } from "./config.js";
+
+export * from "./types.js";
+export * from "./config.js";
+export { TmuxTransport, tmuxAvailable, paneExists, probePane, tmuxVersion, type TmuxHost } from "./tmux.js";
+
+let host: TmuxHost | undefined;
+
+/** Wire the process-layer implementation in once, at module init. */
+export function registerTmuxHost(h: TmuxHost): void {
+  host = h;
+}
+
+export function resolveTransport(kind: TransportKind): Transport {
+  if (!host) {
+    throw new Error(
+      "transport host not registered — call registerTmuxHost() before resolveTransport(); " +
+        "this is a wiring error, not a runtime condition",
+    );
+  }
+  switch (kind) {
+    case TMUX_PUSH:
+    case TMUX_PUSH_REMOTE:
+      return new TmuxTransport(host, kind);
+    case HERDR:
+      // Task 4. Named so the union stays total and the gap is a stated absence
+      // rather than a default that silently behaves like tmux.
+      throw new Error('transport "herdr" is not implemented yet (Phase 5.4 Task 4)');
+  }
+}
+
+/* ── the ACTIVE transport, and why `running` is not read from config ────────── */
+
+/**
+ * The instance this process would actually use to deliver.
+ *
+ * Kept as an OBJECT rather than re-derived from the config value on each call,
+ * and that is the whole design. If `running` were computed by reading the config
+ * and resolving it, then `configured` and `running` would be two names for one
+ * fact and `agrees` could never be false — a check that cannot fail. The active
+ * instance is what startup actually installed, so the two can genuinely differ:
+ * a startup that refused, a process that never wired one, a test that installed
+ * another, a future path that falls back.
+ */
+let active: Transport | undefined;
+
+export function setActiveTransport(t: Transport): void {
+  active = t;
+}
+
+/** FOR TESTS ONLY — production wires the active transport once, at startup. */
+export function clearActiveTransportForTests(): void {
+  active = undefined;
+}
+
+export function activeTransport(): Transport | undefined {
+  return active;
+}
+
+/**
+ * Wire the transport this fleet is configured for. Called once at startup, and
+ * it is where an unknown config value turns into a refusal.
+ */
+export function initTransportFromConfig(): { kind: TransportKind; source: string } {
+  const conf = configuredTransport();
+  setActiveTransport(resolveTransport(conf.kind));
+  return { kind: conf.kind, source: conf.source };
+}
+
+/**
+ * WHAT THIS PROCESS IS ACTUALLY RUNNING, answered by CALLING the transport.
+ *
+ * *A config value is a label someone typed.* This asks the live object instead:
+ * it calls `available()` and puts a synthetic marker through `probe()`, and
+ * reports what came back as the evidence beside the answer. The probe is chosen
+ * to be discriminating rather than decorative — a tmux transport answers a
+ * bogus pane id with a reason that names the pane, and an implementation that
+ * does not talk to panes cannot produce that.
+ *
+ * Returns `undefined` for `kind` when nothing is wired, which is NOT the same as
+ * "tmux by default": a process with no transport delivers nothing, and reporting
+ * a default here would be the exact substitution this function exists to refuse.
+ */
+export async function runningTransport(): Promise<{
+  kind: TransportKind | undefined;
+  evidence: string;
+}> {
+  const t = active;
+  if (!t) {
+    return {
+      kind: undefined,
+      evidence: "no transport is wired in this process — nothing was called, and no default is assumed",
+    };
+  }
+  const availability = (() => {
+    try {
+      return `available()=${t.available()}`;
+    } catch (e) {
+      return `available() threw: ${(e as Error).message}`;
+    }
+  })();
+  let probeEvidence: string;
+  try {
+    const live = await t.probe({
+      agentId: "__capability_probe__",
+      transport: t.kind,
+      pid: process.pid,
+      target: "__no_such_target__",
+      since: Date.now(),
+    });
+    probeEvidence = `probe(bogus target)=${live.state}${live.state === "live" ? "" : `: ${live.reason}`}`;
+  } catch (e) {
+    probeEvidence = `probe threw: ${(e as Error).message}`;
+  }
+  return { kind: t.kind, evidence: `${availability}, ${probeEvidence}` };
+}