@clipboard-health/groundcrew 4.18.1 → 4.18.2

package/dist/commands/reviewer.d.ts

@@ -1,21 +1,24 @@
 /**
- * Per-iteration scanner that advances in-progress tickets to in-review once
- * their worktree has an open (or merged) pull request. Sits between the cleaner
- * and the dispatcher in each `orchestrate()` tick. A successfully-applied
- * transition frees a dispatch slot (the slot math counts only in-progress)
- * while leaving the worktree intact for review, since the cleaner only tears
- * down `done` tickets.
+ * Per-iteration scanner that advances a ticket based on its worktree's pull
+ * request state. Sits between the cleaner and the dispatcher in each
+ * `orchestrate()` tick.
  *
- * The write-back lands in the ticket source, not the in-memory `BoardState`, so
- * the dispatcher in the SAME tick still sees the ticket as in-progress; the slot
- * frees on the NEXT tick's `board.fetch()`. That one-tick latency is deliberate
- * — it keeps the reviewer from mutating shared `BoardState` mid-tick. One per
- * `orchestrate()`; stateless across iterations. Mirrors `Cleaner`.
+ * - An **open** PR on an **in-progress** ticket → `markInReview`: frees a
+ *   dispatch slot (slot math counts only in-progress) while leaving the
+ *   worktree intact for review, since the cleaner only tears down `done`.
+ * - A **merged** PR (on an in-progress or in-review ticket) → `markDone`:
+ *   the work has landed, so the ticket is terminal and the cleaner tears the
+ *   worktree down on a later tick. `merged` never routes to `in-review`.
  *
- * "Worktree has an open PR" is a v1 proxy for "the implementation is finished
- * and up for review". The detection + the open/merged condition live here in
- * the core reviewer (a push model) rather than inside any adapter, so a future
- * per-adapter `shouldAdvanceToReview` predicate is a clean additive change.
+ * Sources that don't implement `markDone` (e.g. Linear) return `unsupported`;
+ * the reviewer logs the skip and does nothing — there is no in-review
+ * fallback. (Linear's own GitHub integration moves merged issues to Done,
+ * which groundcrew observes via `fetch()`.)
+ *
+ * The write-back lands in the ticket source, not the in-memory `BoardState`,
+ * so the dispatcher in the SAME tick still sees prior state; the slot frees on
+ * the NEXT tick's `board.fetch()`. That one-tick latency is deliberate. One
+ * per `orchestrate()`; stateless across iterations. Mirrors `Cleaner`.
  */
 import type { Board } from "../lib/board.ts";
 import type { PullRequestSummary } from "../lib/pullRequests.ts";

package/dist/commands/reviewer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reviewer.d.ts","sourceRoot":"","sources":["../../src/commands/reviewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,KAAK,UAAU,EAAsC,MAAM,wBAAwB,CAAC;AAE7F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAAC;AAE7C,UAAU,YAAY;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AAED,sEAAsE;AACtE,UAAU,eAAe;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAsBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAqG3D"}
+{"version":3,"file":"reviewer.d.ts","sourceRoot":"","sources":["../../src/commands/reviewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EACL,KAAK,UAAU,EAIhB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAAC;AAE7C,UAAU,YAAY;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AAED,sEAAsE;AACtE,UAAU,eAAe;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,UAAU,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AA+CD,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAwH3D"}

package/dist/commands/reviewer.js

@@ -1,28 +1,47 @@
 /**
- * Per-iteration scanner that advances in-progress tickets to in-review once
- * their worktree has an open (or merged) pull request. Sits between the cleaner
- * and the dispatcher in each `orchestrate()` tick. A successfully-applied
- * transition frees a dispatch slot (the slot math counts only in-progress)
- * while leaving the worktree intact for review, since the cleaner only tears
- * down `done` tickets.
+ * Per-iteration scanner that advances a ticket based on its worktree's pull
+ * request state. Sits between the cleaner and the dispatcher in each
+ * `orchestrate()` tick.
  *
- * The write-back lands in the ticket source, not the in-memory `BoardState`, so
- * the dispatcher in the SAME tick still sees the ticket as in-progress; the slot
- * frees on the NEXT tick's `board.fetch()`. That one-tick latency is deliberate
- * — it keeps the reviewer from mutating shared `BoardState` mid-tick. One per
- * `orchestrate()`; stateless across iterations. Mirrors `Cleaner`.
+ * - An **open** PR on an **in-progress** ticket → `markInReview`: frees a
+ *   dispatch slot (slot math counts only in-progress) while leaving the
+ *   worktree intact for review, since the cleaner only tears down `done`.
+ * - A **merged** PR (on an in-progress or in-review ticket) → `markDone`:
+ *   the work has landed, so the ticket is terminal and the cleaner tears the
+ *   worktree down on a later tick. `merged` never routes to `in-review`.
  *
- * "Worktree has an open PR" is a v1 proxy for "the implementation is finished
- * and up for review". The detection + the open/merged condition live here in
- * the core reviewer (a push model) rather than inside any adapter, so a future
- * per-adapter `shouldAdvanceToReview` predicate is a clean additive change.
+ * Sources that don't implement `markDone` (e.g. Linear) return `unsupported`;
+ * the reviewer logs the skip and does nothing — there is no in-review
+ * fallback. (Linear's own GitHub integration moves merged issues to Done,
+ * which groundcrew observes via `fetch()`.)
+ *
+ * The write-back lands in the ticket source, not the in-memory `BoardState`,
+ * so the dispatcher in the SAME tick still sees prior state; the slot frees on
+ * the NEXT tick's `board.fetch()`. That one-tick latency is deliberate. One
+ * per `orchestrate()`; stateless across iterations. Mirrors `Cleaner`.
  */
-import { naturalIdFromCanonical } from "../lib/ticketSource.js";
+import { naturalIdFromCanonical, } from "../lib/ticketSource.js";
 import { debug, errorMessage, log, logEvent } from "../lib/util.js";
-// A PR whose lifecycle means the work is up for (or past) review. `merged`
-// catches a PR that merged between ticks, so we still free the slot.
-function isReviewablePullRequest(pr) {
-    return pr.state === "open" || pr.state === "merged";
+// Maps a worktree's PRs to the transition its ticket should make. A merged PR
+// means the work landed → done; an open PR on an in-progress ticket means it's
+// up for review. `merged` wins over `open`. An open PR on an already in-review
+// ticket is a no-op (returns undefined). Closed-only PRs are ignored.
+function intendedTransition(pullRequests, status) {
+    if (pullRequests.some((pr) => pr.state === "merged")) {
+        return "done";
+    }
+    if (status === "in-progress" && pullRequests.some((pr) => pr.state === "open")) {
+        return "in-review";
+    }
+    return undefined;
+}
+// The PR to name in logs for a transition: the merged one for `done`, the open
+// one for `in-review`. Guaranteed to exist because intendedTransition only
+// returns a transition when a PR of the matching state is present.
+function pullRequestForTransition(pullRequests, transition) {
+    const state = transition === "done" ? "merged" : "open";
+    // oxlint-disable-next-line typescript/no-non-null-assertion -- intendedTransition guarantees a PR of this state exists
+    return pullRequests.find((pr) => pr.state === state);
 }
 function matchingWorktreeEntries(arguments_) {
     const { issue, worktreeEntries, ticket } = arguments_;
@@ -35,12 +54,12 @@ export function createReviewer(deps) {
     const { board, findPullRequests } = deps;
     async function runOnce(arguments_) {
         const { state, worktreeEntries, dryRun, signal } = arguments_;
-        const inProgress = state.issues.filter((issue) => issue.status === "in-progress");
-        if (inProgress.length === 0) {
+        const candidates = state.issues.filter((issue) => issue.status === "in-progress" || issue.status === "in-review");
+        if (candidates.length === 0) {
             return;
         }
-        for (const issue of inProgress) {
-            // oxlint-disable-next-line no-await-in-loop -- at most maximumInProgress (1-5) issues per tick; sequential keeps gh load low.
+        for (const issue of candidates) {
+            // oxlint-disable-next-line no-await-in-loop -- few candidates per tick; sequential keeps gh load low.
             await advanceIfReviewable({
                 issue,
                 worktreeEntries,
@@ -49,9 +68,10 @@ export function createReviewer(deps) {
             });
         }
     }
-    // Idempotent after an applied transition: once advanced, the issue leaves
-    // `in-progress`, so it never reaches this scan again. Unsupported writebacks
-    // are skipped without claiming success and may retry on later ticks.
+    // Idempotent after an applied transition: once advanced, the issue leaves the
+    // in-progress/in-review candidate set, so it never reaches this scan again.
+    // Unsupported writebacks are skipped without claiming success and may retry
+    // on later ticks.
     async function advanceIfReviewable(arguments_) {
         const { issue, worktreeEntries, dryRun, signal } = arguments_;
         const ticket = naturalIdFromCanonical(issue.id);
@@ -59,8 +79,8 @@ export function createReviewer(deps) {
         for (const entry of entries) {
             // The injected lookup is contracted never to reject (failures resolve to
             // []), but we still guard it so one bad lookup can never abort the tick
-            // and starve the other in-progress issues. A failure means "can't tell
-            // yet" → skip this worktree and retry next tick.
+            // and starve the other candidates. A failure means "can't tell yet" →
+            // skip this worktree and retry next tick.
             let pullRequests;
             try {
                 // oxlint-disable-next-line no-await-in-loop -- a ticket almost always has one worktree; sequential lookups are fine.
@@ -74,47 +94,61 @@ export function createReviewer(deps) {
                 debug(`PR lookup failed for ${ticket} (${entry.branchName}): ${errorMessage(error)}`);
                 continue;
             }
-            const reviewable = pullRequests.find(isReviewablePullRequest);
-            if (reviewable === undefined) {
+            const transition = intendedTransition(pullRequests, issue.status);
+            if (transition === undefined) {
                 continue;
             }
+            const pullRequest = pullRequestForTransition(pullRequests, transition);
             if (dryRun) {
-                log(`[dry-run] Would advance ${ticket} to in-review (PR ${reviewable.url})`);
-                logEvent("review", { outcome: "skipped", reason: "dry_run", ticket, pr: reviewable.url });
+                log(`[dry-run] Would advance ${ticket} to ${transition} (PR ${pullRequest.url})`);
+                logEvent("review", {
+                    outcome: "skipped",
+                    reason: "dry_run",
+                    ticket,
+                    pr: pullRequest.url,
+                    to: transition,
+                });
                 return;
             }
-            // oxlint-disable-next-line no-await-in-loop -- single write-back then return; never iterates past the first reviewable worktree.
-            await advance({ issue, ticket, pullRequest: reviewable });
+            // oxlint-disable-next-line no-await-in-loop -- single write-back then return; never iterates past the first actionable worktree.
+            await advance({ issue, ticket, pullRequest, transition });
             return;
         }
     }
     // A writeback failure (shell/Linear error) is logged and swallowed: the
-    // ticket stays in-progress and is retried next tick, exactly like a failed
+    // ticket keeps its status and is retried next tick, exactly like a failed
     // lookup. We never let one ticket's writeback abort the others' reviews.
     async function advance(arguments_) {
-        const { issue, ticket, pullRequest } = arguments_;
+        const { issue, ticket, pullRequest, transition } = arguments_;
         try {
-            const result = await board.markInReview(issue);
+            const result = transition === "done" ? await board.markDone(issue) : await board.markInReview(issue);
             if (result.outcome === "unsupported") {
-                log(`Skipped advancing ${ticket} to in-review: ${result.reason}`);
+                log(`Skipped advancing ${ticket} to ${transition}: ${result.reason}`);
                 logEvent("review", {
                     outcome: "skipped",
                     reason: "unsupported",
                     ticket,
+                    to: transition,
                 });
                 return;
             }
-            log(`Advanced ${ticket} to in-review (PR ${pullRequest.url})`);
+            log(`Advanced ${ticket} to ${transition} (PR ${pullRequest.url})`);
             logEvent("review", {
                 outcome: "advanced",
                 ticket,
                 pr: pullRequest.url,
                 state: pullRequest.state,
+                to: transition,
             });
         }
         catch (error) {
-            log(`Failed to advance ${ticket} to in-review: ${errorMessage(error)}`);
-            logEvent("review", { outcome: "failed", reason: "writeback_failed", ticket });
+            log(`Failed to advance ${ticket} to ${transition}: ${errorMessage(error)}`);
+            logEvent("review", {
+                outcome: "failed",
+                reason: "writeback_failed",
+                ticket,
+                to: transition,
+            });
         }
     }
     return { runOnce };

package/dist/lib/adapters/shell/factory.d.ts

@@ -12,6 +12,7 @@
  *    in MVP-2.
  *  - `markInProgress` absent → silent no-op.
  *  - `markInReview` absent → reports unsupported.
+ *  - `markDone` absent → reports unsupported.
  *  - `fetch` is required by the Zod schema.
  */
 import type { AdapterContext } from "../../adapterDefinition.ts";

package/dist/lib/adapters/shell/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAGL,KAAK,KAAK,IAAI,cAAc,EAE5B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AA4BrB,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB3F;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,cAAc,GACvB,YAAY,CAoGd"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAGL,KAAK,KAAK,IAAI,cAAc,EAG5B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AA+BrB,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB3F;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,cAAc,GACvB,YAAY,CA8Gd"}

package/dist/lib/adapters/shell/factory.js

@@ -12,6 +12,7 @@
  *    in MVP-2.
  *  - `markInProgress` absent → silent no-op.
  *  - `markInReview` absent → reports unsupported.
+ *  - `markDone` absent → reports unsupported.
  *  - `fetch` is required by the Zod schema.
  */
 import { toCanonicalId, } from "../../ticketSource.js";
@@ -23,6 +24,7 @@ const DEFAULT_TIMEOUTS = {
     resolveOne: 10_000,
     markInProgress: 10_000,
     markInReview: 10_000,
+    markDone: 10_000,
 };
 function mergeTimeouts(overrides) {
     return {
@@ -31,6 +33,7 @@ function mergeTimeouts(overrides) {
         resolveOne: overrides?.resolveOne ?? DEFAULT_TIMEOUTS.resolveOne,
         markInProgress: overrides?.markInProgress ?? DEFAULT_TIMEOUTS.markInProgress,
         markInReview: overrides?.markInReview ?? DEFAULT_TIMEOUTS.markInReview,
+        markDone: overrides?.markDone ?? DEFAULT_TIMEOUTS.markDone,
     };
 }
 export function toCanonicalIssue(shellIssue, sourceName) {
@@ -149,5 +152,15 @@ export function createShellTicketSource(config, _context) {
             await invokeWriteback(config.commands.markInReview, timeouts.markInReview, issue);
             return { outcome: "applied" };
         },
+        async markDone(issue) {
+            if (config.commands.markDone === undefined) {
+                return {
+                    outcome: "unsupported",
+                    reason: `shell source "${sourceName}" has no commands.markDone configured`,
+                };
+            }
+            await invokeWriteback(config.commands.markDone, timeouts.markDone, issue);
+            return { outcome: "applied" };
+        },
     };
 }

package/dist/lib/adapters/shell/schema.d.ts

@@ -89,6 +89,7 @@ export declare const shellAdapterConfigSchema: z.ZodObject<{
         resolveOne: z.ZodOptional<z.ZodString>;
         markInProgress: z.ZodOptional<z.ZodString>;
         markInReview: z.ZodOptional<z.ZodString>;
+        markDone: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     cwd: z.ZodOptional<z.ZodString>;
     timeouts: z.ZodOptional<z.ZodObject<{
@@ -97,6 +98,7 @@ export declare const shellAdapterConfigSchema: z.ZodObject<{
         resolveOne: z.ZodOptional<z.ZodNumber>;
         markInProgress: z.ZodOptional<z.ZodNumber>;
         markInReview: z.ZodOptional<z.ZodNumber>;
+        markDone: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;

package/dist/lib/adapters/shell/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA4B,CAAC;AAEhE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;iBA0BnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA4B,CAAC;AAEhE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;iBA4BnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/lib/adapters/shell/schema.js

@@ -47,6 +47,7 @@ export const shellAdapterConfigSchema = z.object({
         resolveOne: z.string().optional(),
         markInProgress: z.string().optional(),
         markInReview: z.string().optional(),
+        markDone: z.string().optional(),
     }),
     cwd: z.string().optional(),
     timeouts: z
@@ -59,6 +60,7 @@ export const shellAdapterConfigSchema = z.object({
         resolveOne: z.number().int().positive().optional(),
         markInProgress: z.number().int().positive().optional(),
         markInReview: z.number().int().positive().optional(),
+        markDone: z.number().int().positive().optional(),
     })
         .optional(),
     env: z.record(z.string(), z.string()).optional(),

package/dist/lib/board.d.ts

@@ -4,7 +4,7 @@
  * goes through this; the moment we skip the wrapper we grow Linear assumptions
  * back into consumers.
  */
-import { type BoardState, type Issue, type MarkInReviewResult, type TicketSource } from "./ticketSource.ts";
+import { type BoardState, type Issue, type MarkDoneResult, type MarkInReviewResult, type TicketSource } from "./ticketSource.ts";
 export interface Board {
     verify(): Promise<void>;
     fetch(): Promise<BoardState>;
@@ -21,6 +21,12 @@ export interface Board {
      * return `unsupported` (see `TicketSource.markInReview`).
      */
     markInReview(issue: Issue): Promise<MarkInReviewResult>;
+    /**
+     * Advances a ticket to done on the adapter whose `name` matches
+     * `issue.source`. Unknown source throws. Sources that don't implement the
+     * optional `markDone` return `unsupported` (see `TicketSource.markDone`).
+     */
+    markDone(issue: Issue): Promise<MarkDoneResult>;
 }
 export declare function createBoard(sources: readonly TicketSource[]): Board;
 //# sourceMappingURL=board.d.ts.map

package/dist/lib/board.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"board.d.ts","sourceRoot":"","sources":["../../src/lib/board.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,kBAAkB,EAEvB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,KAAK;IACpB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IACrE,wFAAwF;IACxF,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAqBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,KAAK,CAwGnE"}
+{"version":3,"file":"board.d.ts","sourceRoot":"","sources":["../../src/lib/board.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,kBAAkB,EAEvB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,KAAK;IACpB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IACrE,wFAAwF;IACxF,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACjD;AAqBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,KAAK,CAmHnE"}

package/dist/lib/board.js

@@ -111,6 +111,16 @@ export function createBoard(sources) {
         async markInReview(issue) {
             return await routeWriteback(byName, issue).markInReview(issue);
         },
+        async markDone(issue) {
+            const source = routeWriteback(byName, issue);
+            if (source.markDone === undefined) {
+                return {
+                    outcome: "unsupported",
+                    reason: `source "${source.name}" does not support markDone`,
+                };
+            }
+            return await source.markDone(issue);
+        },
     };
 }
 /**

package/dist/lib/pullRequests.d.ts

@@ -15,6 +15,8 @@ export interface PullRequestSummary {
     /** Lowercased lifecycle: "open" | "merged" | "closed". */
     state: string;
     title: string;
+    /** PR head commit SHA used to ignore historical PRs from reused branch names. */
+    headRefOid: string;
 }
 interface LookupArgs {
     /** Worktree directory; `gh` resolves the GitHub repo from its git remote. */

package/dist/lib/pullRequests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pullRequests.d.ts","sourceRoot":"","sources":["../../src/lib/pullRequests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AASD,UAAU,UAAU;IAClB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAgDD,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAyBxC"}
+{"version":3,"file":"pullRequests.d.ts","sourceRoot":"","sources":["../../src/lib/pullRequests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AASD,UAAU,UAAU;IAClB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmDD,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CA6BxC"}

package/dist/lib/pullRequests.js

@@ -37,6 +37,7 @@ function parsePullRequests(output) {
             number: entry.number,
             state: STATE_MAP[entry.state] ?? entry.state.toLowerCase(),
             title: entry.title,
+            headRefOid: entry.headRefOid,
         });
     }
     return summaries;
@@ -50,27 +51,32 @@ function isRawPullRequest(value) {
     return (typeof record["url"] === "string" &&
         typeof record["number"] === "number" &&
         typeof record["state"] === "string" &&
-        typeof record["title"] === "string");
+        typeof record["title"] === "string" &&
+        typeof record["headRefOid"] === "string");
 }
 export async function findPullRequestsForBranch(arguments_) {
     const { cwd, branchName, signal } = arguments_;
+    const options = signal === undefined ? { cwd } : { cwd, signal };
     try {
-        const output = await runCommandAsync("gh", [
-            "pr",
-            "list",
-            "--head",
-            branchName,
-            "--state",
-            "all",
-            "--limit",
-            String(GH_PR_LIST_LIMIT),
-            "--json",
-            "url,number,state,title",
-        ], signal === undefined ? { cwd } : { cwd, signal });
-        return parsePullRequests(output);
+        const [output, currentHeadOid] = await Promise.all([
+            runCommandAsync("gh", [
+                "pr",
+                "list",
+                "--head",
+                branchName,
+                "--state",
+                "all",
+                "--limit",
+                String(GH_PR_LIST_LIMIT),
+                "--json",
+                "url,number,state,title,headRefOid",
+            ], options),
+            runCommandAsync("git", ["rev-parse", "HEAD"], options),
+        ]);
+        return parsePullRequests(output).filter((pr) => pr.headRefOid === currentHeadOid);
     }
     catch {
-        // gh not installed / not authenticated / non-GitHub remote / network
+        // gh/git not installed / not authenticated / non-GitHub remote / network
         // error / etc. All resolve to "no PR info available" for display.
         return [];
     }

package/dist/lib/ticketSource.d.ts

@@ -116,6 +116,12 @@ export type MarkInReviewResult = {
     outcome: "unsupported";
     reason: string;
 };
+export type MarkDoneResult = {
+    outcome: "applied";
+} | {
+    outcome: "unsupported";
+    reason: string;
+};
 export interface TicketSource {
     /** Stable identifier used as the id prefix and in log lines. Equal to the source's config `name`. */
     readonly name: string;
@@ -136,6 +142,16 @@ export interface TicketSource {
      * rather than pretending the transition happened.
      */
     markInReview(issue: Issue): Promise<MarkInReviewResult>;
+    /**
+     * Optional writeback: advance a ticket to done once its PR has merged.
+     * Sources without a native/configured done transition omit this method; the
+     * Board treats an absent method as `{ outcome: "unsupported" }` so the
+     * reviewer can log the skip without claiming a transition that never
+     * happened. Linear omits it on purpose: on merge, Linear's own GitHub
+     * integration moves the issue to Done, which groundcrew then observes via
+     * `fetch()` and the cleaner tears down.
+     */
+    markDone?(issue: Issue): Promise<MarkDoneResult>;
     /**
      * Optional: return parent tickets that were excluded from `fetch()` because
      * they have sub-issues. Board surfaces these so the dispatcher can log WHY

package/dist/lib/ticketSource.d.ts.map

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

package/docs/ticket-sources.md

@@ -16,8 +16,9 @@ export default {
         resolveOne: "~/.config/groundcrew/jira-resolve.sh ${id}",
         markInProgress: "jira issue move ${id} 'In Progress'",
         markInReview: "jira issue move ${id} 'In Review'",
+        markDone: "jira issue move ${id} 'Done'",
       },
-      timeouts: { fetch: 60_000, markInReview: 15_000 },
+      timeouts: { fetch: 60_000, markInReview: 15_000, markDone: 15_000 },
     },
   ],
 };
@@ -26,12 +27,15 @@ export default {
 `commands.fetch` must print a JSON array of issues. `commands.resolveOne`, when
 set, must print one issue, print nothing for "not found", or exit `3` for "not
 found". `commands.markInProgress`, when set, receives the issue's `sourceRef` as
-JSON on stdin. `commands.markInReview`, when set, receives the same `sourceRef`
-and is run after groundcrew sees an open or merged PR on the ticket's worktree
-branch. If `commands.markInReview` is omitted, groundcrew treats in-review
-advancement as unsupported for that source and does not claim the transition
-succeeded. `${id}`, `${canonicalId}`, and `${name}` placeholders are shell-quoted
-before substitution.
+JSON on stdin. `commands.markInReview`, when set, receives the same `sourceRef` and is run
+after groundcrew sees an **open** PR on the ticket's worktree branch (in-progress
+tickets only). If omitted, groundcrew treats in-review advancement as unsupported
+for that source and does not claim the transition succeeded. `commands.markDone`,
+when set, receives the same `sourceRef` and is run after groundcrew sees a
+**merged** PR on the ticket's worktree branch (a merged PR never advances to
+in-review). If omitted, groundcrew treats done advancement as unsupported and
+leaves the ticket for the source's own integration to close out. `${id}`,
+`${canonicalId}`, and `${name}` placeholders are shell-quoted before substitution.
 
 ```json
 [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.18.1",
+  "version": "4.18.2",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",