agent-coord-mcp 0.26.18 → 0.26.19

package/dist/typed-records.js

@@ -0,0 +1,174 @@
+// Typed records become obligatory on agent→agent traffic (Phase 5.1 Task 12).
+//
+// THE MECHANISM ALREADY SHIPPED AND ADOPTION WAS THE WHOLE GAP.
+// `hooks/tier.mjs:injectLine` slims a multi-line message to *first line +
+// `[+N lines · record:<type> · retrieve_message id=<uuid>]`* — but ONLY when
+// `record.type` is a string. Measured on the groundwork room 2026-08-30: 206
+// messages, 175 multi-line, 33 typed, 33 slimmed; the coordinator had sent 101
+// and typed 0. The renderer was never the problem.
+//
+// SO THE RULE IS ENFORCED AT THE SEND, NOT THE RENDER. An untyped agent→agent
+// message must not be able to EXIST, or the next reader re-derives the type
+// from prose and we are back to parsing English. Prose is a second source of
+// truth about what a message meant.
+//
+// Three things this module is careful about, each one a stated acceptance
+// property rather than an implementation taste:
+//
+//  1. STAGED, WITH A NAMED DATE. Five fleets share this bus and 7 of 13 server
+//     processes predate 0.26.7. A refusal shipped before a verified restart
+//     rejects messages from agents that CANNOT comply — the sender gets an
+//     error it has no code path to satisfy. So: WARN until the cutover, REFUSE
+//     after it, and the warning names the date in every single message so the
+//     deadline arrives having been announced ~every send rather than once.
+//
+//  2. THE REFUSAL NAMES A TYPE THE SENDER MAY ACTUALLY USE. `go` and `scope`
+//     are coordinator-restricted and `verdict` is gate-runner-restricted
+//     (RECORD_AUTHORITY): the aide hit exactly this, being told to use `scope`
+//     by one check and refused it by another. Naming a forbidden type is
+//     unusable guidance, so every suggestion is filtered through what this
+//     sender's role may emit before it is offered.
+//
+//  3. `fyi` IS AN HONEST CATCH-ALL. If the nine types do not cover a legitimate
+//     send, agents mistype into whatever passes and the type becomes noise —
+//     which costs more than the untyped message did. Anything unrecognised
+//     suggests `fyi` and says so plainly, never a forced `decision`/`risk`.
+// The named cutover. Until this instant an untyped agent→agent send WARNS and
+// is stored; from it, the same send is refused.
+//
+// A DATE, NOT A VERSION, because the constraint being waited on is a fleet-wide
+// RESTART, and no version string on the wire can answer "has every server
+// restarted" — 0.26.7 is published while servers predating it still run. Time
+// is the only clock every one of those processes shares.
+export const TYPED_RECORD_CUTOVER_ISO = "2026-09-15T00:00:00.000Z";
+export const TYPED_RECORD_CUTOVER_MS = Date.parse(TYPED_RECORD_CUTOVER_ISO);
+// `AGENT_COORD_TYPED_RECORDS=warn|refuse` overrides the date. It exists for two
+// callers and no others: tests (which must exercise both sides of a date that
+// has not arrived) and an operator who needs to pull the refusal back for a
+// fleet mid-incident. It is NOT the exemption — an exemption is per-agent and
+// visible (see `proseOnly`); this switch is fleet-wide and invisible, which is
+// exactly why it is not how a less capable model gets on the bus.
+export function typedRecordMode(now = Date.now()) {
+    const env = process.env.AGENT_COORD_TYPED_RECORDS;
+    if (env === "warn" || env === "refuse")
+        return env;
+    return now >= TYPED_RECORD_CUTOVER_MS ? "refuse" : "warn";
+}
+// ---------- suggesting the type the sender should have used ----------
+// A rejection that says only "record required" costs a round trip; one that
+// says "looks like a `done` — it cites a PR" costs none. A FAILURE PATH MUST BE
+// MORE INFORMATIVE THAN THE SUCCESS PATH HERE, because it fires during a
+// migration, at agents that are mid-slice and did nothing wrong yesterday.
+//
+// Read from the text the fleet already writes: the six canonical prefixes are
+// in every card and on ~every message, so the type is usually already declared
+// in English one token in.
+const PREFIX_TYPES = [
+    [/^\s*DONE\b/i, "done", "the message opens with the DONE: prefix"],
+    [/^\s*BLOCKER\b/i, "blocker", "the message opens with the BLOCKER: prefix"],
+    [/^\s*RISK\b/i, "risk", "the message opens with the RISK: prefix"],
+    [/^\s*FYI\b/i, "fyi", "the message opens with the FYI: prefix"],
+    [/^\s*AGENT_ACTION\b/i, "action", "the message opens with the AGENT_ACTION: prefix"],
+    [/^\s*DAVID_DECISION\b/i, "decision", "the message opens with the DAVID_DECISION: prefix"],
+    [/^\s*GO\b/i, "go", "the message opens with the GO: prefix"],
+    [/^\s*SCOPE(?:\s+CHANGE)?\b/i, "scope", "the message opens with the SCOPE: prefix"],
+];
+// Weaker than a prefix and only consulted when there is no prefix at all.
+const SHAPE_TYPES = [
+    [/\b(PASS|FAIL)\b.*\b[0-9a-f]{7,40}\b/, "verdict", "it reads as a gate verdict over a commit sha"],
+    [/^\s*(PASS|FAIL)\b/, "verdict", "it opens with a PASS/FAIL gate result"],
+    [/(^|\s)(#\d+|[\w.-]+\/[\w.-]+#\d+|https:\/\/github\.com\/\S+\/pull\/\d+)/, "done", "it cites a PR"],
+];
+/**
+ * The record type this message most likely should have carried, CONSTRAINED to
+ * what this sender is allowed to emit.
+ *
+ * `mayNotEmit` is the restricted set this role is refused (recordAuthorityFor).
+ * A suggestion landing in it is downgraded to `fyi` and the downgrade is
+ * reported rather than hidden — being quietly steered off `go` reads as the
+ * heuristic being bad, when in fact the role simply does not own that type.
+ */
+export function suggestRecordType(text, mayNotEmit = []) {
+    const forbidden = new Set(mayNotEmit);
+    const firstLine = (text ?? "").split("\n", 1)[0] ?? "";
+    const hit = PREFIX_TYPES.find(([re]) => re.test(firstLine)) ??
+        SHAPE_TYPES.find(([re]) => re.test(firstLine) || re.test(text ?? ""));
+    if (!hit) {
+        return {
+            type: "fyi",
+            why: "nothing in the text names a kind — 'fyi' is the honest catch-all and is never wrong on purpose",
+        };
+    }
+    const [, type, why] = hit;
+    if (forbidden.has(type)) {
+        return {
+            type: "fyi",
+            downgradedFrom: type,
+            why: `${why}, but '${type}' is restricted to roles this sender does not hold — 'fyi' carries the same slimming`,
+        };
+    }
+    return { type, why };
+}
+/**
+ * The one line of guidance appended to both the warning and the refusal. Same
+ * words either side of the cutover ON PURPOSE: an agent that reads it during
+ * the warn window has already been told the exact call that will keep working.
+ */
+export function typedRecordGuidance(s) {
+    const cite = s.type === "done"
+        ? `, cites: [{kind:'pr', ref:'<owner/repo#N>'}]` // a `done` is refused without one anyway
+        : "";
+    return (`looks like a '${s.type}' — ${s.why}. ` +
+        `Add record: {type:'${s.type}', payload:{summary:'<one line>'}${cite}} to this same call; ` +
+        `'text' is untouched by the record and your wording always wins.`);
+}
+// ---------- measuring adoption, and the inverse failure ----------
+// SUCCESS IS THE TRAFFIC TABLE RE-MEASURED, NOT THIS TASK MERGED. The baseline
+// captured the day the rule was made: 212 room messages, 37 typed (17%),
+// 425,903 bytes sitting below line 1 — bytes every reader pays for and no
+// reader asked for.
+//
+// AND THE INVERSE FAILURE LOOKS EXACTLY LIKE SUCCESS ON A COVERAGE NUMBER. If
+// `fyi` becomes nearly everything, coverage reads ~100% while agents are
+// mistyping to get past the gate and the type has stopped carrying
+// information — that is the catch-all rule (12.5) failing, not holding. So the
+// distribution is reported alongside the percentage and is what the verdict
+// keys on. A coverage-only check would certify the failure it exists to catch.
+//
+// The threshold is deliberately generous: `fyi` IS the honest answer for a
+// large share of real traffic, so this fires on domination, not on presence.
+export const FYI_DOMINANCE_THRESHOLD = 0.75;
+/** `messages` is any array of stored messages ({text, record?}). */
+export function typedRecordStats(messages) {
+    const distribution = {};
+    let typed = 0;
+    let unslimmedBytes = 0;
+    for (const m of messages) {
+        const type = typeof m.record?.type === "string" ? m.record.type : undefined;
+        distribution[type ?? "untyped"] = (distribution[type ?? "untyped"] ?? 0) + 1;
+        if (type) {
+            typed++;
+            continue;
+        }
+        const text = m.text ?? "";
+        const nl = text.indexOf("\n");
+        if (nl !== -1)
+            unslimmedBytes += Buffer.byteLength(text.slice(nl + 1), "utf8");
+    }
+    const total = messages.length;
+    const coverage = total ? typed / total : 0;
+    const fyiShareOfTyped = typed ? (distribution.fyi ?? 0) / typed : 0;
+    // Order matters: degeneracy is checked BEFORE coverage, or a room that is
+    // 100% `fyi` reports "healthy" — the exact misreading this guards.
+    const degenerate = typed >= 10 && fyiShareOfTyped > FYI_DOMINANCE_THRESHOLD;
+    const verdict = degenerate ? "degenerate" : coverage >= 0.95 ? "healthy" : "adopting";
+    const note = degenerate
+        ? `'fyi' is ${(fyiShareOfTyped * 100).toFixed(0)}% of typed messages — coverage looks solved while the type has ` +
+            `stopped carrying information. Agents are typing to pass the gate, which is 12.5 FAILING, not holding.`
+        : verdict === "healthy"
+            ? `${(coverage * 100).toFixed(0)}% typed with a spread distribution — the reader-side cost is paid down and the type still discriminates.`
+            : `${(coverage * 100).toFixed(0)}% typed; ${unslimmedBytes.toLocaleString("en-US")} bytes still sit below line 1 in untyped messages, ` +
+                `carried by every reader.`;
+    return { total, typed, coverage: Number(coverage.toFixed(3)), unslimmedBytes, distribution, fyiShareOfTyped: Number(fyiShareOfTyped.toFixed(3)), verdict, note };
+}
+//# sourceMappingURL=typed-records.js.map

package/dist/typed-records.js.map

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

package/dist/work.js

@@ -0,0 +1,2 @@
+export { BOARD_ARITY, isMalformedRow, EM_DASH_SEP, MIDDOT_SEP, parseQueueLine, parseDoneLine, renderQueueLine, renderDoneLine, renderBoardRow, parseWorkDoc, renderWorkDoc, renderWorkDocForWrite, stampQueueIds, zeroIsUnparsed, substantiveLines, queueItemsOf, doneEntriesOf, boardRowsOf, workstreamsV1RowsOf, listWorkBoardOf, projectV1ToLanes, workDocIssues, workDocLegacyWriteIssues, LANES_V0_WRITE_ISSUE, } from "@davidbalzan/groundwork-seam/docs";
+//# sourceMappingURL=work.js.map

package/dist/work.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work.js","sourceRoot":"","sources":["../src/work.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,WAAW,EAEX,cAAc,EAGd,WAAW,EACX,UAAU,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,cAAc,EACd,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,wBAAwB,EACxB,oBAAoB,GAGrB,MAAM,mCAAmC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.18",
+  "version": "0.26.19",
   "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": {
@@ -8,18 +8,6 @@
     "coord-chat": "scripts/coord-chat.mjs",
     "coord-pusher": "scripts/coord-pusher.mjs"
   },
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "pnpm run clean && tsc",
-    "prepare": "node scripts/check-self-dependency.mjs && pnpm run clean && tsc",
-    "prepack": "node scripts/check-self-dependency.mjs && pnpm run build",
-    "prepublishOnly": "node scripts/check-publish-tool.mjs",
-    "start": "node dist/server.js",
-    "dev": "tsx src/server.ts",
-    "pretest": "node scripts/check-self-dependency.mjs && node scripts/check-optional-call.mjs && tsc",
-    "test": "node scripts/check-test-count.mjs",
-    "test:raw": "node --test \"test/*.test.mjs\""
-  },
   "files": [
     "dist",
     "src",
@@ -65,5 +53,14 @@
     "@types/proper-lockfile": "^4.1.4",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsc",
+    "start": "node dist/server.js",
+    "dev": "tsx src/server.ts",
+    "pretest": "node scripts/check-self-dependency.mjs && node scripts/check-optional-call.mjs && tsc",
+    "test": "node scripts/check-test-count.mjs",
+    "test:raw": "node --test \"test/*.test.mjs\""
   }
-}
+}

package/src/server.ts

@@ -96,6 +96,8 @@ import {
   ensureWorktreeTool,
   refreshWorktreesSchema,
   refreshWorktreesTool,
+  releaseWorktreeSchema,
+  releaseWorktreeTool,
   claimSchema,
   claimTool,
   landSchema,
@@ -659,6 +661,12 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     refreshWorktreesSchema,
     gate(null, refreshWorktreesTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
+  addTool(
+    "release_worktree",
+    "GIVE A WORKTREE BACK — the counterpart to ensure_worktree, which created trees while nothing released them, leaving `git worktree remove`/`prune` as a hand step in five role cards. Identify the tree by `agentId` or `path`. REFUSES the primary checkout (the path everyone already has); REFUSES a DIRTY tree with no override, because uncommitted work is what a diff cannot show and git cannot give back; and REFUSES a tree whose commits cannot be shown to have landed. Landedness is decided by PATCH ID, never ancestry — under squash merge a landed branch's shas never enter the base, so ancestry calls every finished tree mid-slice forever and would refuse exactly the trees that are safe to release. A patch-id negative is INCONCLUSIVE rather than a no, so it refuses and says so; `force:true` releases anyway and is recorded in the result. Removing and pruning are ONE act here, not two lines of prose the caller remembers. Reports by default; pass apply:true to remove.",
+    releaseWorktreeSchema,
+    gate(null, releaseWorktreeTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
 
   addTool(
     "next_unblocked",
@@ -669,7 +677,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   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.",
+    "Bind a queue item to an agent, ENSURE THE AGENT HAS AN ISOLATED WORKTREE, and produce the \ud83d\udea7 board row. With no itemId it takes next_unblocked. `claim` CALLS `ensure_worktree` rather than telling you to — a worktree that cannot be ensured is a REFUSAL, not a warning, because binding an item to an agent with nowhere isolated to work is the shared-checkout failure this pair exists to prevent. A REUSED tree that is not at origin/<base> is also refused, naming how far behind it is and pointing at `refresh_worktrees`: `claim` means START SOMETHING NEW, and a tree left on last week's base produces confidently-wrong work with nothing about the result looking stale. A freshly created tree is cut from origin/<base> and needs no such check. Returns `worktreeEnsured` with the tree's path and branch, and writes the board cell as the REMOTE-TRACKING ref so the same row reads identically from every checkout.",
     claimSchema,
     gate(null, claimTool as (a: Record<string, unknown>) => Promise<unknown>),
   );

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 };
+}