agent-coord-mcp 0.26.17 → 0.26.19

package/src/tools/work.ts

@@ -13,6 +13,8 @@ import {
   projectV1ToLanes,
   queueItemsOf,
   renderWorkDoc,
+  renderWorkDocForWrite,
+  zeroIsUnparsed,
   workDocIssues,
   workDocLegacyWriteIssues,
   LANES_V0_WRITE_ISSUE,
@@ -55,6 +57,13 @@ export type StoredWorkDoc = {
   kind: "queue" | "done" | "board" | "legacy";
   path: string;
   doc: WorkDoc;
+  /**
+   * The bytes as read. Kept because a COUNT OF ZERO cannot be interpreted
+   * without them: `zeroIsUnparsed` needs to know whether the document had
+   * content the parser did not understand, and the parsed doc has already
+   * discarded that distinction (q-3e7c81a5).
+   */
+  source: string;
 };
 
 export type StoredFactsDoc = {
@@ -77,7 +86,7 @@ async function loadDoc(repo: string, f: { kind: WorkFileKind; path: string }): P
     const parsed = parseFactsDoc(source);
     return { kind: "facts", path: f.path, source, entries: parsed.entries, issues: parsed.issues };
   }
-  return { kind: f.kind, path: f.path, doc: parseWorkDoc(source) };
+  return { kind: f.kind, path: f.path, doc: parseWorkDoc(source), source };
 }
 
 function docIssues(d: StoredDoc): string[] {
@@ -97,12 +106,56 @@ function importedSummary(d: StoredDoc) {
     };
   }
   const issues = [...workDocIssues(d.doc), ...workDocLegacyWriteIssues(d.doc)];
-  return {
-    path: d.path,
-    kind: d.kind,
+  const counts = {
     queue: queueItemsOf(d.doc).length,
     done: doneEntriesOf(d.doc).length,
     board: listWorkBoardOf(d.doc).length,
+  };
+  // A ZERO THAT CANNOT BE TRUSTED IS NAMED, NOT RETURNED BARE.
+  //
+  // These three were plain `.length`, so a document the parser did not
+  // understand reported the same zero as an empty one. A consumer's dashboard
+  // read that and showed a fleet as IDLE on a night it merged 27 PRs; they
+  // declined to enable these verbs rather than ship a display they could not
+  // trust (q-3e7c81a5).
+  //
+  // The counts keep their shape and meaning — a reader that only wants numbers
+  // is unaffected — and `unparsed` says which of them are unanswered questions
+  // rather than answers. The predicate is the SEAM's, shared with `doctor`'s
+  // queue-done-loop rather than restated here.
+  // ONLY THE AXES THIS DOCUMENT CLAIMS TO CARRY.
+  //
+  // Caught by the test's own output rather than by review: qualifying all three
+  // for every file reported `docs/QUEUE.md` as having unparsed `done` and `board`
+  // axes, which is nonsense — a queue document is not expected to hold done
+  // entries, so its zero there is not an unanswered question, it is a category
+  // error on my part. Scoping the qualification to the document's KIND is the
+  // same population discipline the count itself needed: a claim about an axis a
+  // file never carried is noise, and noise is what teaches a reader to skip the
+  // real one. `legacy` is the single-file BACKLOG.md, which carries both regions.
+  const AXES_BY_KIND = {
+    queue: ["queue"],
+    done: ["done"],
+    board: ["board"],
+    legacy: ["queue", "done"],
+  } as const;
+  const unparsed = (AXES_BY_KIND[d.kind] as readonly (keyof typeof counts)[]).filter((axis) =>
+    zeroIsUnparsed(counts[axis], d.source),
+  );
+  return {
+    path: d.path,
+    kind: d.kind,
+    ...counts,
+    ...(unparsed.length
+      ? {
+          unparsed,
+          unparsedNote:
+            `${d.path} has content the parser did not understand: ${unparsed.join(", ")} parsed to ZERO. ` +
+            `That is an unanswered question, not an empty document — do not render it as idle, empty or done. ` +
+            `Either the file uses a shape this grammar does not accept, or it is malformed; both need a human, and ` +
+            `neither is "nothing there".`,
+        }
+      : {}),
     ...(issues.length ? { issues } : {}),
   };
 }
@@ -359,6 +412,19 @@ export async function exportWorkTool(args: {
       });
       continue;
     }
+    // DELIBERATELY THE PURE RENDER, NOT THE STAMPING ONE (q-c50e9b83).
+    //
+    // I routed this through `renderWorkDocForWrite` first and it broke three
+    // pre-existing tests that assert `import → export` writes the real documents
+    // back BYTE-IDENTICALLY. They were right and the change was wrong: this is a
+    // TRANSPORT, not an authoring path. Its contract is to reproduce a document,
+    // and a transport that silently edits content the caller never asked it to
+    // touch is a worse defect than the one being fixed — it would also mean
+    // exporting into ANOTHER project's documents mutates them.
+    //
+    // So the primary is scoped to the AUTHORING writer (`land`, via records.ts),
+    // and an unstamped item arriving through this path is the backstop's
+    // population: it cannot reach `main` without passing a push.
     const rendered = renderWorkDoc(d.doc);
     const current = existsSync(target) ? await fsp.readFile(target, "utf8") : null;
     const declared = scopes.documents.find((s) => s.path === d.path);

package/src/tools/worktrees.ts

@@ -227,11 +227,58 @@ 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 } },
+        }
       : {}),
   };
 }
 
+// ---------- shared: is this tree's work already in the base? ----------
+
+/**
+ * Are the commits HEAD has beyond `tip` ALREADY LANDED there?
+ *
+ * `rev-list --count <tip>..HEAD` is pure ANCESTRY, and under squash merge a landed
+ * branch's own shas never enter the base's history — so `ahead` stays > 0 FOREVER
+ * for work that shipped (q-5c40db91; 20 of the last 20 merges on this repo's main
+ * are single-parent). Reading `ahead > 0` as "this tree holds unlanded work" makes
+ * the verb whose job is fast-forwarding idle trees classify a FINISHED tree as
+ * mid-slice, permanently.
+ *
+ * MEASURED, and it cost a lane cycle: a `claim` was refused because a worker's tree
+ * "reads as 1 commit not on origin/main" while that branch had been squash-merged an
+ * hour earlier. Same inverted alarm as the item's headline — landed work reported as
+ * unmerged, inviting preservation of work already shipped — inside our own tooling.
+ *
+ * `git cherry` compares PATCH IDS, so every line marked `-` means every commit's patch
+ * is already upstream. It is NOT complete: several commits squashed into one carry a
+ * different combined patch id, so a negative is INCONCLUSIVE and is reported as
+ * mid-slice exactly as before. Only a positive changes the verdict, which keeps the
+ * failure direction the same as today's for everything this cannot prove.
+ */
+function aheadIsLanded(at: string, tip: string): boolean {
+  // `git` here THROWS rather than returning null, so the catch is what keeps an
+  // UNREADABLE answer out of the landed bucket: not measured is not landed, and
+  // the tree stays mid-slice, which is the direction that refuses rather than
+  // the direction that tells someone their work is safe to discard.
+  let cherry: string;
+  try {
+    cherry = git(at, ["cherry", tip, "HEAD"]);
+  } catch {
+    return false;
+  }
+  if (cherry.trim().length === 0) return false;
+  return cherry
+    .trim()
+    .split("\n")
+    .every((l) => l.trim().startsWith("-"));
+}
+
 // ---------- 1.2 / 1.3: refresh idle trees, never mid-slice ----------
 
 export const refreshWorktreesSchema = {
@@ -264,6 +311,7 @@ export async function refreshWorktreesTool(args: { repo: string; base: string; a
     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;
@@ -308,7 +356,9 @@ export async function refreshWorktreesTool(args: { repo: string; base: string; a
               (dirty
                 ? " and DIRTY — not fast-forwarded; uncommitted work is what a diff cannot show"
                 : ahead !== "0"
-                  ? ` and ${ahead} ahead — not fast-forwarded; it has commits ${ref} does not`
+                  ? aheadIsLanded(at, tip)
+                    ? ` and ${ahead} ahead whose patches are ALREADY UPSTREAM — squash-merged, so ancestry will never agree; not fast-forwarded, but nothing here needs preserving`
+                    : ` and ${ahead} ahead — not fast-forwarded; it has commits ${ref} does not`
                   : args.apply
                     ? ""
                     : " — pass apply:true to fast-forward it"),
@@ -337,7 +387,28 @@ export async function refreshWorktreesTool(args: { repo: string; base: string; a
       /* 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.` });
+      // LANDED, NOT MID-SLICE — the ancestry count cannot tell these apart.
+      if (aheadIsLanded(at, tip)) {
+        results.push({
+          path: w.path,
+          action: "landed",
+          why:
+            `${ahead} commit(s) are not ancestors of ${ref}, but every one of their PATCHES is already upstream — ` +
+            `this branch was SQUASH-MERGED and its work has shipped. Ancestry can never say so: a squash writes a new ` +
+            `commit, so these shas will read as "not on ${ref}" forever. Nothing here needs preserving; detach to ${ref} ` +
+            `(or delete the branch) and this tree is reusable. NOT fast-forwarded automatically — moving a tree off ` +
+            `committed work is a decision, not a refresh.`,
+        });
+        continue;
+      }
+      results.push({
+        path: w.path,
+        action: "refused",
+        why:
+          `MID-SLICE: ${ahead} commit(s) not on ${ref}, and their patches are NOT upstream. Refusing rather than --force. ` +
+          `(A squash of SEVERAL commits into one changes the combined patch id, so this cannot prove the negative — ` +
+          `it reports mid-slice, which is the same direction it always failed in.)`,
+      });
       continue;
     }
     if (!args.apply) {
@@ -353,3 +424,196 @@ export async function refreshWorktreesTool(args: { repo: string; base: string; a
   }
   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/work.ts

@@ -17,6 +17,10 @@ export {
   renderBoardRow,
   parseWorkDoc,
   renderWorkDoc,
+  renderWorkDocForWrite,
+  stampQueueIds,
+  zeroIsUnparsed,
+  substantiveLines,
   queueItemsOf,
   doneEntriesOf,
   boardRowsOf,