@afokapu/atdd-flow 0.3.81 → 0.3.83

package/extensions/pi/index.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import { mkdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { parse, stringify } from "yaml";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, recordMailActivation, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
@@ -413,6 +414,23 @@ function unmatchedWakeRequest(branch: TranscriptEntry[], identity: WakeIdentity)
 /** The recovery bundle is advisory; any failure falls back to the plain prompt. */
 const recovery = (root: string, seat: string, mode: RecoveryMode, session?: string) => recoveryFor(root, seat, mode, session).catch(() => undefined);
 
+type ReceiptWithLaunchRequest = { handover_replacement?: { request?: unknown } };
+
+/** The request recorded in this seat's own launcher receipt, or undefined when the seat, receipt or embed is absent or unreadable. */
+async function embeddedLaunchRequest(root: string, seat: string) {
+  try {
+    const receiptPath = (await readYaml<Seat>(paths(root).seatFile(seat))).runtime?.launch_receipt;
+    if (!receiptPath) return undefined;
+    return (parse(await readFile(receiptPath, "utf8")) as ReceiptWithLaunchRequest | null)?.handover_replacement?.request;
+  } catch { return undefined; }
+}
+
+/** True when this Pi was launched by the active request: its own receipt embeds exactly that request, so it is the consumed successor, not a source to shut down. */
+async function launchedByRequest(root: string, seat: string, request: unknown) {
+  const embedded = await embeddedLaunchRequest(root, seat);
+  return embedded !== undefined && isDeepStrictEqual(embedded, request);
+}
+
 /** Desk mail is authoritative; the queue is a bounded delivery index and fs.watch only shortens latency. */
 export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = process.env) {
   const root = environment.ATDD_WORKFLOW_ROOT;
@@ -456,7 +474,7 @@ export default function (pi: ExtensionAPI, environment: NodeJS.ProcessEnv = proc
     if (!sourceSession) return;
     try {
       const request = await readHandoverReplacement(root, seat);
-      if (request.source.pi_session !== sourceSession) return;
+      if (request.source.pi_session !== sourceSession || await launchedByRequest(root, seat, request)) return;
       pi.sendMessage({
         customType: "atdd-flow-context-handover-replacement",
         content: `SYSTEM: Validated Path-A request for ${seat} observed. The successor must not start until this Pi has shut down and Herdr reports the exact source pane released.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.81",
+  "version": "0.3.83",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/retire-merge-proof.ts

@@ -0,0 +1,54 @@
+// URN: component:flow:terminal-seat-retirement:retire-merge-proof:backend:integration
+// Tested-By:
+// - test:atdd-flow:terminal-seat-retire-merge-proof
+// Runtime: bun
+// Purpose: Independent merge proof for retiring a driver that worktree finish refuses.
+
+import { type Seat, runOutput } from "./core";
+import { isAncestor } from "./vcs";
+
+type PullRequest = { state?: string; headRefOid?: string; mergeCommit?: { oid?: string } | null };
+
+/** A clean worktree is required; only generated hook files may be untracked, as `worktree finish` allows. */
+async function worktreeIsClean(worktree: string) {
+  const status = await runOutput(["git", "-C", worktree, "status", "--porcelain"]);
+  return status.split("\n").filter(Boolean).every((line) => line.endsWith(" .githooks/") || line.endsWith(" .githooks"));
+}
+
+/** No uncommitted work, and the worktree is on the exact branch tip being proven merged. */
+async function worktreeIsAtTip(worktree: string, tip: string) {
+  return await worktreeIsClean(worktree) && await runOutput(["git", "-C", worktree, "rev-parse", "HEAD"]) === tip;
+}
+
+/** Merged PRs for the branch, from GitHub; an unavailable or malformed answer is no evidence. */
+async function mergedPullRequests(repository: string, branch: string): Promise<PullRequest[]> {
+  try {
+    const listed = JSON.parse(await runOutput(["gh", "pr", "list", "--head", branch, "--state", "merged", "--limit", "20", "--json", "state,headRefOid,mergeCommit"], repository));
+    return Array.isArray(listed) ? listed : [];
+  } catch { return []; }
+}
+
+/** A merged PR whose head is exactly the branch tip and whose merge (or squash) commit is on the primary branch. */
+async function squashMergeProof(repository: string, branch: string, tip: string, primary: string) {
+  for (const pull of await mergedPullRequests(repository, branch)) {
+    const merge = pull.mergeCommit?.oid;
+    if (pull.state === "MERGED" && pull.headRefOid === tip && merge && await isAncestor(repository, merge, primary)) return merge;
+  }
+  return undefined;
+}
+
+/**
+ * Proves a retiring driver has no unmerged work without `worktree finish`: the worktree is clean and at the branch tip, and that tip
+ * is reachable from the primary branch or is the head of a merged PR whose merge commit is on it. Returns the evidence, or undefined.
+ * Nothing is removed or deleted: the caller retains the worktree and branch.
+ */
+export async function terminalMergeProof(repository: string, owner: Seat): Promise<string | undefined> {
+  try {
+    const primary = await runOutput(["git", "-C", repository, "branch", "--show-current"]);
+    const tip = await runOutput(["git", "-C", repository, "rev-parse", "--verify", `refs/heads/${owner.branch}`]);
+    if (!primary || !await worktreeIsAtTip(owner.worktree, tip)) return undefined;
+    if (await isAncestor(repository, tip, primary)) return `branch tip ${tip} is reachable from ${primary}`;
+    const merge = await squashMergeProof(repository, owner.branch, tip, primary);
+    return merge ? `branch tip ${tip} is the head of a merged PR whose merge commit ${merge} is on ${primary}` : undefined;
+  } catch { return undefined; }
+}

package/src/retire-merge-proof.ts.bak

@@ -0,0 +1,49 @@
+// URN: component:flow:terminal-seat-retirement:retire-merge-proof:backend:integration
+// Tested-By:
+// - test:atdd-flow:terminal-seat-retire-merge-proof
+// Runtime: bun
+// Purpose: Independent merge proof for retiring a terminal driver that worktree finish refuses.
+
+import { type Seat, runOutput } from "./core";
+import { isAncestor } from "./vcs";
+
+type PullRequest = { state?: string; headRefOid?: string; mergeCommit?: { oid?: string } | null };
+
+/** A clean worktree is required; only generated hook files may be untracked, as `worktree finish` allows. */
+async function worktreeIsClean(worktree: string) {
+  const status = await runOutput(["git", "-C", worktree, "status", "--porcelain"]);
+  return status.split("\n").filter(Boolean).every((line) => line.endsWith(" .githooks/") || line.endsWith(" .githooks"));
+}
+
+/** Merged PRs for the branch, from GitHub; an unavailable or malformed answer is no evidence. */
+async function mergedPullRequests(repository: string, branch: string): Promise<PullRequest[]> {
+  try {
+    const listed = JSON.parse(await runOutput(["gh", "pr", "list", "--head", branch, "--state", "merged", "--limit", "20", "--json", "state,headRefOid,mergeCommit"], repository));
+    return Array.isArray(listed) ? listed : [];
+  } catch { return []; }
+}
+
+/** A merged PR whose head is exactly the branch tip and whose merge (or squash) commit is on the primary branch. */
+async function squashMergeProof(repository: string, branch: string, tip: string, primary: string) {
+  for (const pull of await mergedPullRequests(repository, branch)) {
+    const merge = pull.mergeCommit?.oid;
+    if (pull.state === "MERGED" && pull.headRefOid === tip && merge && await isAncestor(repository, merge, primary)) return merge;
+  }
+  return undefined;
+}
+
+/**
+ * Proves a retiring driver has no unmerged work without `worktree finish`: the worktree is clean and at the branch tip, and that tip
+ * is reachable from the primary branch or is the head of a merged PR whose merge commit is on it. Returns the evidence, or undefined.
+ * Nothing is removed or deleted: the caller retains the worktree and branch.
+ */
+export async function terminalMergeProof(repository: string, owner: Seat): Promise<string | undefined> {
+  try {
+    const primary = await runOutput(["git", "-C", repository, "branch", "--show-current"]);
+    const tip = await runOutput(["git", "-C", repository, "rev-parse", "--verify", `refs/heads/${owner.branch}`]);
+    if (!primary || !await worktreeIsClean(owner.worktree) || await runOutput(["git", "-C", owner.worktree, "rev-parse", "HEAD"]) !== tip) return undefined;
+    if (await isAncestor(repository, tip, primary)) return `branch tip ${tip} is reachable from ${primary}`;
+    const merge = await squashMergeProof(repository, owner.branch, tip, primary);
+    return merge ? `branch tip ${tip} is the head of a merged PR whose merge commit ${merge} is on ${primary}` : undefined;
+  } catch { return undefined; }
+}

package/src/tasks.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import {
   type Checkpoint, type Seat, atomicYaml, canonicalAddress, exists, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
+import { terminalMergeProof } from "./retire-merge-proof";
 import { operatorAuthorizationPayload } from "./task-supersede-authorization";
 import { branchCommit, currentCommit, isAncestor, vcsMode, type VcsMode } from "./vcs";
 
@@ -258,6 +259,21 @@ async function retirementBun(root: string, projectName: string) {
   return [required(Bun.which("atdd-bun") ?? undefined, "atdd-bun in the primary checkout node_modules/.bin or on PATH")];
 }
 
+/**
+ * ATDD Bun removes a clean merged worktree and its branch. When it refuses (a squash-merged or post-JJ branch it cannot prove
+ * merged), retirement proceeds only on independent merge proof; the worktree and branch are then retained and the refusal stands otherwise.
+ */
+async function finishOrProveMerged(root: string, projectName: string, owner: Seat) {
+  const config = await project(root, projectName);
+  try {
+    return await runOutput([...await retirementBun(root, projectName), "worktree", "finish", "--delete-branch", "--vcs", vcsMode(config)], owner.worktree);
+  } catch (error) {
+    const proof = config.repository && await exists(owner.worktree) ? await terminalMergeProof(config.repository, owner) : undefined;
+    if (!proof) throw error;
+    return `Worktree finish refused (${(error as Error).message}); merge proof: ${proof}; worktree ${owner.worktree} and branch ${owner.branch} retained.`;
+  }
+}
+
 async function retireDriver(root: string, projectName: string, assignee: string, id: string, allowAbsentWorktree = false, allowPrimaryCheckout = false) {
   const unfinished = (await allTasks(root, projectName))
     .filter((entry) => entry.id !== id && (entry.task.assignee === assignee || entry.task.coordinator === assignee) && !terminal(entry.task))
@@ -271,7 +287,7 @@ async function retireDriver(root: string, projectName: string, assignee: string,
     const primaryCheckout = allowPrimaryCheckout && primary && await canonicalPath(owner.worktree) === await canonicalPath(primary);
     const summary = (primaryCheckout ? `Primary checkout ${owner.worktree} retained; retired without worktree finish.` : undefined)
       ?? (allowAbsentWorktree ? await absentUnregisteredWorktree(root, projectName, owner) : undefined)
-      ?? await runOutput([...await retirementBun(root, projectName), "worktree", "finish", "--delete-branch", "--vcs", vcsMode(await project(root, projectName))], owner.worktree);
+      ?? await finishOrProveMerged(root, projectName, owner);
     owner.retired = { task: `${projectName}/${id}`, completed_at: now(), summary };
     await atomicYaml(paths(root).seatFile(assignee), owner);
     const checkpoint: Checkpoint = {