@clipboard-health/groundcrew 4.14.0 → 4.15.0

package/dist/commands/orchestrator.d.ts

@@ -1,8 +1,8 @@
 /**
  * groundcrew orchestrator — polls Linear projects and spins up workspace +
  * git-worktree pairs for ready tickets. Each tick fetches the board, runs
- * the cleaner, and runs the dispatcher; logging from those modules is the
- * orchestrator's user-facing output.
+ * the cleaner, the reviewer, and the dispatcher; logging from those modules is
+ * the orchestrator's user-facing output.
  */
 export interface OrchestratorOptions {
     watch: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyDH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAiBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0C7E"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2DH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAiBD,wBAAsB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgD7E"}

package/dist/commands/orchestrator.js

@@ -1,18 +1,20 @@
 /**
  * groundcrew orchestrator — polls Linear projects and spins up workspace +
  * git-worktree pairs for ready tickets. Each tick fetches the board, runs
- * the cleaner, and runs the dispatcher; logging from those modules is the
- * orchestrator's user-facing output.
+ * the cleaner, the reviewer, and the dispatcher; logging from those modules is
+ * the orchestrator's user-facing output.
  */
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
 import { loadConfig } from "../lib/config.js";
+import { findPullRequestsForBranch } from "../lib/pullRequests.js";
 import { RepositoryResolutionError } from "../lib/ticketSource.js";
 import { getUsageByModel } from "../lib/usage.js";
 import { errorMessage, log, sleep } from "../lib/util.js";
 import { worktrees } from "../lib/worktrees.js";
 import { createCleaner } from "./cleaner.js";
 import { createDispatcher } from "./dispatcher.js";
+import { createReviewer } from "./reviewer.js";
 const RATE_LIMIT_DELAY_MS = 60_000;
 const RETRY_BASE_DELAY_MS = 1000;
 const RETRY_MAX_ATTEMPTS = 3;
@@ -72,6 +74,10 @@ export async function orchestrate(options) {
     const board = createBoard(allSources);
     await board.verify();
     const cleaner = createCleaner({ config });
+    const reviewer = createReviewer({
+        board,
+        findPullRequests: findPullRequestsForBranch,
+    });
     const dispatcher = createDispatcher({ config, board });
     // Folded into the dispatcher's idle log lines in watch mode so each idle
     // tick prints one combined line instead of "<reason>" + "Next poll in Xs".
@@ -88,6 +94,7 @@ export async function orchestrate(options) {
             ...(signal === undefined ? {} : { signal }),
         };
         await cleaner.runOnce(tickArguments);
+        await reviewer.runOnce(tickArguments);
         await dispatcher.runOnce({
             ...tickArguments,
             // Lazy: dispatcher only invokes this after its own early-returns, so

package/dist/commands/reviewer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ *
+ * 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`.
+ *
+ * "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.
+ */
+import type { Board } from "../lib/board.ts";
+import type { PullRequestSummary } from "../lib/pullRequests.ts";
+import { type BoardState } from "../lib/ticketSource.ts";
+import type { WorktreeEntry } from "../lib/worktrees.ts";
+/**
+ * Injected PR lookup. Matches `findPullRequestsForBranch`'s shape: best-effort,
+ * never rejects — a failed lookup (gh missing, unauthenticated, non-GitHub
+ * remote, network error) resolves to an empty list, indistinguishable from
+ * "no PR yet". Both outcomes mean "skip this issue, retry next tick".
+ */
+export type FindPullRequests = (arguments_: {
+    cwd: string;
+    branchName: string;
+    signal?: AbortSignal;
+}) => Promise<readonly PullRequestSummary[]>;
+interface ReviewerDeps {
+    board: Board;
+    findPullRequests: FindPullRequests;
+}
+/** Per-tick inputs, mirroring the other orchestrator steps' shape. */
+interface ReviewArguments {
+    state: BoardState;
+    worktreeEntries: readonly WorktreeEntry[];
+    dryRun: boolean;
+    signal?: AbortSignal;
+}
+export interface Reviewer {
+    runOnce(arguments_: ReviewArguments): Promise<void>;
+}
+export declare function createReviewer(deps: ReviewerDeps): Reviewer;
+export {};
+//# sourceMappingURL=reviewer.d.ts.map

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

@@ -0,0 +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"}

package/dist/commands/reviewer.js

@@ -0,0 +1,121 @@
+/**
+ * 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.
+ *
+ * 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`.
+ *
+ * "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.
+ */
+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";
+}
+function matchingWorktreeEntries(arguments_) {
+    const { issue, worktreeEntries, ticket } = arguments_;
+    if (issue.repository === undefined) {
+        return [];
+    }
+    return worktreeEntries.filter((entry) => entry.ticket === ticket && entry.repository === issue.repository);
+}
+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) {
+            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.
+            await advanceIfReviewable({
+                issue,
+                worktreeEntries,
+                dryRun,
+                ...(signal === undefined ? {} : { signal }),
+            });
+        }
+    }
+    // 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.
+    async function advanceIfReviewable(arguments_) {
+        const { issue, worktreeEntries, dryRun, signal } = arguments_;
+        const ticket = naturalIdFromCanonical(issue.id);
+        const entries = matchingWorktreeEntries({ issue, worktreeEntries, ticket });
+        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.
+            let pullRequests;
+            try {
+                // oxlint-disable-next-line no-await-in-loop -- a ticket almost always has one worktree; sequential lookups are fine.
+                pullRequests = await findPullRequests({
+                    cwd: entry.dir,
+                    branchName: entry.branchName,
+                    ...(signal === undefined ? {} : { signal }),
+                });
+            }
+            catch (error) {
+                debug(`PR lookup failed for ${ticket} (${entry.branchName}): ${errorMessage(error)}`);
+                continue;
+            }
+            const reviewable = pullRequests.find(isReviewablePullRequest);
+            if (reviewable === undefined) {
+                continue;
+            }
+            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 });
+                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 });
+            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
+    // lookup. We never let one ticket's writeback abort the others' reviews.
+    async function advance(arguments_) {
+        const { issue, ticket, pullRequest } = arguments_;
+        try {
+            const result = await board.markInReview(issue);
+            if (result.outcome === "unsupported") {
+                log(`Skipped advancing ${ticket} to in-review: ${result.reason}`);
+                logEvent("review", {
+                    outcome: "skipped",
+                    reason: "unsupported",
+                    ticket,
+                });
+                return;
+            }
+            log(`Advanced ${ticket} to in-review (PR ${pullRequest.url})`);
+            logEvent("review", {
+                outcome: "advanced",
+                ticket,
+                pr: pullRequest.url,
+                state: pullRequest.state,
+            });
+        }
+        catch (error) {
+            log(`Failed to advance ${ticket} to in-review: ${errorMessage(error)}`);
+            logEvent("review", { outcome: "failed", reason: "writeback_failed", ticket });
+        }
+    }
+    return { runOnce };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/linear/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAIL,KAAK,KAAK,IAAI,cAAc,EAE5B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAKL,KAAK,KAAK,IAAI,WAAW,EAE1B,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,YAAY,EAAE,MAAM,CAAC;CACtB;AAkFD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB7F;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,cAAc,GACtB,YAAY,CAgFd"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/linear/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAIL,KAAK,KAAK,IAAI,cAAc,EAG5B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAKL,KAAK,KAAK,IAAI,WAAW,EAE1B,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,YAAY,EAAE,MAAM,CAAC;CACtB;AAkFD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB7F;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,cAAc,GACtB,YAAY,CAyFd"}

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

@@ -186,5 +186,14 @@ export function createLinearTicketSource(config, context) {
                 teamId: ref.teamId,
             });
         },
+        async markInReview(issue) {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- by the Linear adapter's contract, every Issue it produces carries a LinearSourceRef in sourceRef
+            const ref = issue.sourceRef;
+            return await getIssueStatusUpdater().markInReview({
+                id: issue.id,
+                uuid: ref.uuid,
+                teamId: ref.teamId,
+            });
+        },
     };
 }

package/dist/lib/adapters/linear/writeback.d.ts

@@ -1,4 +1,5 @@
 import type { LinearClient } from "@linear/sdk";
+import type { MarkInReviewResult } from "../../ticketSource.ts";
 interface LinearIssueReference {
     id: string;
     uuid: string;
@@ -6,6 +7,7 @@ interface LinearIssueReference {
 }
 interface LinearIssueStatusUpdater {
     markInProgress(issue: LinearIssueReference): Promise<void>;
+    markInReview(issue: LinearIssueReference): Promise<MarkInReviewResult>;
 }
 export declare function createLinearIssueStatusUpdater(arguments_: {
     client: LinearClient;

package/dist/lib/adapters/linear/writeback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writeback.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/linear/writeback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,wBAAwB;IAChC,cAAc,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,wBAAgB,8BAA8B,CAAC,UAAU,EAAE;IACzD,MAAM,EAAE,YAAY,CAAC;CACtB,GAAG,wBAAwB,CAuD3B"}
+{"version":3,"file":"writeback.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/linear/writeback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,wBAAwB;IAChC,cAAc,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,YAAY,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACxE;AAaD,wBAAgB,8BAA8B,CAAC,UAAU,EAAE;IACzD,MAAM,EAAE,YAAY,CAAC;CACtB,GAAG,wBAAwB,CAuD3B"}

package/dist/lib/adapters/linear/writeback.js

@@ -1,4 +1,14 @@
 import { debug } from "../../util.js";
+// Linear maps every `started` workflow state to canonical in-progress today,
+// so it cannot prove a successful in-review transition. Report unsupported
+// until read/write sides can distinguish "In Review" from generic started.
+async function markInReviewUnsupported(issue) {
+    debug(`markInReview is unsupported for ${issue.id} (Linear in-review not yet implemented)`);
+    return {
+        outcome: "unsupported",
+        reason: "Linear in-review writeback is not implemented",
+    };
+}
 export function createLinearIssueStatusUpdater(arguments_) {
     const { client } = arguments_;
     // Positive cache only. Keyed by teamId because the in-progress-state
@@ -47,5 +57,5 @@ export function createLinearIssueStatusUpdater(arguments_) {
         await client.updateIssue(issue.uuid, { stateId });
         debug(`Marked ${issue.id} as in progress`);
     }
-    return { markInProgress };
+    return { markInProgress, markInReview: markInReviewUnsupported };
 }

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

@@ -11,6 +11,7 @@
  *    commands should configure `resolveOne` explicitly. No cross-call cache
  *    in MVP-2.
  *  - `markInProgress` absent → silent no-op.
+ *  - `markInReview` 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;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAGL,KAAK,KAAK,IAAI,cAAc,EAC5B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAyBrB,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,CAgFd"}
+{"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"}

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

@@ -11,6 +11,7 @@
  *    commands should configure `resolveOne` explicitly. No cross-call cache
  *    in MVP-2.
  *  - `markInProgress` absent → silent no-op.
+ *  - `markInReview` absent → reports unsupported.
  *  - `fetch` is required by the Zod schema.
  */
 import { toCanonicalId, } from "../../ticketSource.js";
@@ -21,6 +22,7 @@ const DEFAULT_TIMEOUTS = {
     fetch: 30_000,
     resolveOne: 10_000,
     markInProgress: 10_000,
+    markInReview: 10_000,
 };
 function mergeTimeouts(overrides) {
     return {
@@ -28,6 +30,7 @@ function mergeTimeouts(overrides) {
         fetch: overrides?.fetch ?? DEFAULT_TIMEOUTS.fetch,
         resolveOne: overrides?.resolveOne ?? DEFAULT_TIMEOUTS.resolveOne,
         markInProgress: overrides?.markInProgress ?? DEFAULT_TIMEOUTS.markInProgress,
+        markInReview: overrides?.markInReview ?? DEFAULT_TIMEOUTS.markInReview,
     };
 }
 export function toCanonicalIssue(shellIssue, sourceName) {
@@ -68,6 +71,30 @@ export function createShellTicketSource(config, _context) {
         const parsed = shellFetchOutputSchema.parse(JSON.parse(stdout));
         return parsed.map((si) => toCanonicalIssue(si, sourceName));
     }
+    // Shared by markInProgress / markInReview: both pipe the canonical issue's
+    // opaque sourceRef to a status-transition script on stdin, with the natural
+    // and canonical ids substituted into the command.
+    async function invokeWriteback(command, timeoutMs, issue) {
+        if (command === undefined) {
+            return;
+        }
+        const naturalId = issue.id.startsWith(`${sourceName}:`)
+            ? issue.id.slice(sourceName.length + 1)
+            : issue.id;
+        await invokeShellCommand({
+            command,
+            timeoutMs,
+            cwd: config.cwd,
+            env: config.env,
+            substitutions: {
+                id: naturalId,
+                canonicalId: issue.id,
+                name: sourceName,
+            },
+            stdin: JSON.stringify(issue.sourceRef),
+            sourceName,
+        });
+    }
     return {
         name: sourceName,
         async verify() {
@@ -110,26 +137,17 @@ export function createShellTicketSource(config, _context) {
             return toCanonicalIssue(parsed, sourceName);
         },
         async markInProgress(issue) {
-            const markCommand = config.commands.markInProgress;
-            if (markCommand === undefined) {
-                return;
+            await invokeWriteback(config.commands.markInProgress, timeouts.markInProgress, issue);
+        },
+        async markInReview(issue) {
+            if (config.commands.markInReview === undefined) {
+                return {
+                    outcome: "unsupported",
+                    reason: `shell source "${sourceName}" has no commands.markInReview configured`,
+                };
             }
-            const naturalId = issue.id.startsWith(`${sourceName}:`)
-                ? issue.id.slice(sourceName.length + 1)
-                : issue.id;
-            await invokeShellCommand({
-                command: markCommand,
-                timeoutMs: timeouts.markInProgress,
-                cwd: config.cwd,
-                env: config.env,
-                substitutions: {
-                    id: naturalId,
-                    canonicalId: issue.id,
-                    name: sourceName,
-                },
-                stdin: JSON.stringify(issue.sourceRef),
-                sourceName,
-            });
+            await invokeWriteback(config.commands.markInReview, timeouts.markInReview, issue);
+            return { outcome: "applied" };
         },
     };
 }

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

@@ -88,6 +88,7 @@ export declare const shellAdapterConfigSchema: z.ZodObject<{
         fetch: z.ZodString;
         resolveOne: z.ZodOptional<z.ZodString>;
         markInProgress: z.ZodOptional<z.ZodString>;
+        markInReview: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     cwd: z.ZodOptional<z.ZodString>;
     timeouts: z.ZodOptional<z.ZodObject<{
@@ -95,6 +96,7 @@ export declare const shellAdapterConfigSchema: z.ZodObject<{
         fetch: z.ZodOptional<z.ZodNumber>;
         resolveOne: z.ZodOptional<z.ZodNumber>;
         markInProgress: z.ZodOptional<z.ZodNumber>;
+        markInReview: 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;;;;;;;;;;;;;;;;;iBAwBnC,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;;;;;;;;;;;;;;;;;;;iBA0BnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

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

@@ -46,6 +46,7 @@ export const shellAdapterConfigSchema = z.object({
         fetch: z.string(),
         resolveOne: z.string().optional(),
         markInProgress: z.string().optional(),
+        markInReview: z.string().optional(),
     }),
     cwd: z.string().optional(),
     timeouts: z
@@ -57,6 +58,7 @@ export const shellAdapterConfigSchema = z.object({
         fetch: z.number().int().positive().optional(),
         resolveOne: z.number().int().positive().optional(),
         markInProgress: z.number().int().positive().optional(),
+        markInReview: z.number().int().positive().optional(),
     })
         .optional(),
     env: z.record(z.string(), z.string()).optional(),

package/dist/lib/board.d.ts

@@ -1,10 +1,10 @@
 /**
- * Board composer — fans `verify` / `fetch` / `resolveOne` / `markInProgress`
- * across N `TicketSource` adapters. Even a single-source config goes through
- * this; the moment we skip the wrapper we grow Linear assumptions back into
- * consumers.
+ * Board composer — fans `verify` / `fetch` / `resolveOne` / `markInProgress` /
+ * `markInReview` across N `TicketSource` adapters. Even a single-source config
+ * goes through this; the moment we skip the wrapper we grow Linear assumptions
+ * back into consumers.
  */
-import { type BoardState, type Issue, type TicketSource } from "./ticketSource.ts";
+import { type BoardState, type Issue, type MarkInReviewResult, type TicketSource } from "./ticketSource.ts";
 export interface Board {
     verify(): Promise<void>;
     fetch(): Promise<BoardState>;
@@ -15,6 +15,12 @@ export interface Board {
     resolveOne(canonicalOrNaturalId: string): Promise<Issue | undefined>;
     /** Routes to the adapter whose `name` matches `issue.source`. Unknown source throws. */
     markInProgress(issue: Issue): Promise<void>;
+    /**
+     * Advances a ticket to in-review on the adapter whose `name` matches
+     * `issue.source`. Unknown source throws. Adapters with no in-review concept
+     * return `unsupported` (see `TicketSource.markInReview`).
+     */
+    markInReview(issue: Issue): Promise<MarkInReviewResult>;
 }
 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,EAEV,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;CAC7C;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,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"}

package/dist/lib/board.js

@@ -1,8 +1,8 @@
 /**
- * Board composer — fans `verify` / `fetch` / `resolveOne` / `markInProgress`
- * across N `TicketSource` adapters. Even a single-source config goes through
- * this; the moment we skip the wrapper we grow Linear assumptions back into
- * consumers.
+ * Board composer — fans `verify` / `fetch` / `resolveOne` / `markInProgress` /
+ * `markInReview` across N `TicketSource` adapters. Even a single-source config
+ * goes through this; the moment we skip the wrapper we grow Linear assumptions
+ * back into consumers.
  */
 import { AmbiguousTicketError, } from "./ticketSource.js";
 async function callVerify(source) {
@@ -106,11 +106,22 @@ export function createBoard(sources) {
             });
         },
         async markInProgress(issue) {
-            const source = byName.get(issue.source);
-            if (!source) {
-                throw new Error(`unknown source "${issue.source}" for issue ${issue.id}`);
-            }
-            await source.markInProgress(issue);
+            await routeWriteback(byName, issue).markInProgress(issue);
+        },
+        async markInReview(issue) {
+            return await routeWriteback(byName, issue).markInReview(issue);
         },
     };
 }
+/**
+ * Resolve the adapter that owns `issue` for a writeback, by its `source` name.
+ * Shared by `markInProgress` / `markInReview` so both route — and fail —
+ * identically. Throws when no adapter claims the source.
+ */
+function routeWriteback(byName, issue) {
+    const source = byName.get(issue.source);
+    if (!source) {
+        throw new Error(`unknown source "${issue.source}" for issue ${issue.id}`);
+    }
+    return source;
+}

package/dist/lib/ticketSource.d.ts

@@ -104,6 +104,12 @@ export interface BoardState {
     /** Parent tickets skipped because they have sub-issues. */
     parentSkips: readonly ParentSkip[];
 }
+export type MarkInReviewResult = {
+    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;
@@ -115,6 +121,15 @@ export interface TicketSource {
     resolveOne(naturalId: string): Promise<Issue | undefined>;
     /** Writeback. The adapter downcasts `issue.sourceRef` internally. */
     markInProgress(issue: Issue): Promise<void>;
+    /**
+     * Writeback: advance a ticket from in-progress to in-review once its
+     * worktree has an open PR. Frees a dispatch slot without tripping the
+     * cleaner's done-only teardown, so the worktree survives for review. The
+     * adapter downcasts `issue.sourceRef` internally. Adapters with no native
+     * in-review concept (or no configured command) MUST report `unsupported`
+     * rather than pretending the transition happened.
+     */
+    markInReview(issue: Issue): Promise<MarkInReviewResult>;
     /**
      * 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

@@ -15,14 +15,23 @@ export default {
         fetch: "~/.config/groundcrew/jira-fetch.sh",
         resolveOne: "~/.config/groundcrew/jira-resolve.sh ${id}",
         markInProgress: "jira issue move ${id} 'In Progress'",
+        markInReview: "jira issue move ${id} 'In Review'",
       },
-      timeouts: { fetch: 60_000 },
+      timeouts: { fetch: 60_000, markInReview: 15_000 },
     },
   ],
 };
 ```
 
-`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. `${id}`, `${canonicalId}`, and `${name}` placeholders are shell-quoted before substitution.
+`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
 [

package/package.json

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