agent-coord-mcp 0.26.4 → 0.26.6

package/src/tools/worktrees.ts

@@ -0,0 +1,283 @@
+/*
+ * `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"]);
+    return {
+      ok: true as const,
+      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 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,
+    ...(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 };
+}