@clipboard-health/groundcrew 4.52.7 → 4.52.8

package/README.md

@@ -123,6 +123,9 @@ crew cleanup [--force] <TASK>                          # tear down every worktre
 crew cleanup [--force] --all                           # tear down every idle worktree (no live workspace)
 crew upgrade [<version>]                                 # reinstall crew globally through npm
 crew completions <bash|zsh|fish>                        # print a shell completion script
+crew stage label-add <pr-url> <label>                   # add a configured pr-stage-sync gating label
+crew stage label-remove <pr-url> <label>                # remove a configured pr-stage-sync gating label
+crew stage refresh                                      # run one pr-stage-sync pass now
 ```
 
 See [command details](./docs/commands.md) for status output, doctor behavior, and the stop/resume workflow.

package/crew.config.example.ts

@@ -224,4 +224,18 @@ export default {
   //   // evidence with it. Default: `${XDG_STATE_HOME:-~/.local/state}/groundcrew/groundcrew.log`.
   //   file: "~/Library/Logs/groundcrew/groundcrew.log",
   // },
+  //
+  // // Paints each task's cmux sidebar with its pull request's review stage
+  // // (crew_stage), gating labels (crew_labels), and ticket id (crew_ticket)
+  // // once per watch tick. Opt-in and cmux-only; other workspaceKind backends
+  // // no-op. The two gating labels below are created on the PR's repo on
+  // // first use via `crew stage label-add`/`label-remove`; a PR sits at
+  // // `my_review` until `selfReviewed` is applied and `needs_testing` until
+  // // `tested` is applied, ahead of CI and review-decision state.
+  // cmux: {
+  //   prStages: {
+  //     enabled: true,
+  //     labels: { selfReviewed: "self-reviewed", tested: "tested" },
+  //   },
+  // },
 } satisfies Config;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuPA;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAIvD;AAiDD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA6PA;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAIvD;AAiDD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCvD"}

package/dist/cli.js

@@ -9,6 +9,7 @@ import { orchestrate } from "./commands/orchestrator.js";
 import { resumeWorkspaceCli } from "./commands/resumeWorkspace.js";
 import { setupWorkspaceCli } from "./commands/setupWorkspace.js";
 import { sourceCli } from "./commands/source.js";
+import { stageCli } from "./commands/stage.js";
 import { statusCli } from "./commands/status.js";
 import { taskCli } from "./commands/task.js";
 import { createDefaultUpgradeCliOptions, upgradeCli } from "./commands/upgrade.js";
@@ -192,6 +193,11 @@ const SUBCOMMANDS = {
         usage: "<bash|zsh|fish>",
         invoke: completionsCli,
     },
+    stage: {
+        summary: "Manage pr-stage-sync's gating labels, or run a sync pass now",
+        usage: "<label-add|label-remove|refresh> [...]",
+        invoke: stageCli,
+    },
 };
 function isVisibleCommand(command) {
     return command.hidden !== true && command.deprecated !== true;

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

@@ -1 +1 @@
-{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/commands/completions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,+EAA+E;AAC/E,KAAK,aAAa,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,eAAO,MAAM,gBAAgB,YAAI,MAAM,EAAE,KAAK,EAAE,MAAM,CAAU,CAAC;AAEjE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AA2B/D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,iBAAiB,EAqJvD,CAAC;AAqXF,2DAA2D;AAC3D,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEtE;AAQD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlE"}
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/commands/completions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,+EAA+E;AAC/E,KAAK,aAAa,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,eAAO,MAAM,gBAAgB,YAAI,MAAM,EAAE,KAAK,EAAE,MAAM,CAAU,CAAC;AAEjE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AA2B/D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,iBAAiB,EAsKvD,CAAC;AAqXF,2DAA2D;AAC3D,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEtE;AAQD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlE"}

package/dist/commands/completions.js

@@ -186,6 +186,23 @@ export const COMPLETION_SPEC = [
         summary: "Print a shell completion script",
         argValues: SUPPORTED_SHELLS,
     },
+    {
+        name: "stage",
+        summary: "Manage pr-stage-sync's gating labels, or run a sync pass now",
+        subcommands: [
+            {
+                name: "label-add",
+                summary: "Add a configured gating label to a pull request",
+                options: [],
+            },
+            {
+                name: "label-remove",
+                summary: "Remove a configured gating label from a pull request",
+                options: [],
+            },
+            { name: "refresh", summary: "Run one pr-stage-sync pass now" },
+        ],
+    },
 ];
 /** Global flags valid only as the first token. */
 const TOP_LEVEL_GLOBALS = [

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;AAoEH,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,CAiE7E"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqEH,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,CAoE7E"}

package/dist/commands/orchestrator.js

@@ -14,6 +14,7 @@ import { errorMessage, log, sleep, writeOutput } from "../lib/util.js";
 import { worktrees } from "../lib/worktrees.js";
 import { createCleaner } from "./cleaner.js";
 import { createDispatcher } from "./dispatcher.js";
+import { createPrStageSync, createPrStageSyncDeps } from "./prStageSync.js";
 import { createReviewer } from "./reviewer.js";
 const RATE_LIMIT_DELAY_MS = 60_000;
 const RETRY_BASE_DELAY_MS = 1000;
@@ -98,6 +99,7 @@ export async function orchestrate(options) {
         findPullRequests: findPullRequestsForBranch,
     });
     const dispatcher = createDispatcher({ config, board });
+    const prStageSync = createPrStageSync(createPrStageSyncDeps(config));
     // 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".
     const idleSuffix = options.watch
@@ -121,6 +123,7 @@ export async function orchestrate(options) {
         });
         await reviewer.runOnce(tickArguments);
         await cleaner.runOnce(tickArguments);
+        await prStageSync.runOnce(tickArguments);
     };
     await (options.watch ? runWatchLoop(tick, config) : tick());
 }

package/dist/commands/prStageSync.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-tick sync that paints each tracked task's cmux sidebar with its ticket
+ * id, and — when `cmux.prStages.enabled` — its pull request's review stage
+ * and gating labels too. Replaces the standalone `crew-pr-stages` bash
+ * poller: same stage/ticket derivation rules (`../lib/prStageRules.ts`),
+ * same status-key contract the installed sidebar reads, but PRs are
+ * resolved from the task's own worktree branch
+ * (`findPullRequestsForBranchOrThrow`) instead of cmux's own git-branch PR
+ * detection.
+ *
+ * `crew_ticket` is written for every matched cmux task workspace regardless
+ * of the `cmux.prStages.enabled` opt-in, since a custom sidebar may read it
+ * independent of PR-stage sync; the opt-in only gates the `gh`-backed stage
+ * and label writes (and the `crew_poller_heartbeat` that signals they're
+ * running). `cmuxAdapter.ts` also writes it once at workspace-creation time,
+ * using the same `deriveTicket` rule, so a brand-new workspace shows a
+ * ticket pill before the first tick without disagreeing with it — this
+ * module keeps the value current afterward.
+ *
+ * Runs after the other tick steps in `orchestrator.ts`. Every failure is
+ * caught and logged here — a flaky `gh` call or a single misbehaving
+ * workspace must never break the watch loop or starve the other steps.
+ */
+import { type CmuxWorkspaceSummary } from "../lib/cmuxAdapter.ts";
+import { type CmuxStatusWrite } from "../lib/cmuxStatusFields.ts";
+import type { ResolvedConfig } from "../lib/config.ts";
+import { type PullRequestDetail } from "../lib/pullRequestDetails.ts";
+import { type PullRequestSummary } from "../lib/pullRequests.ts";
+import type { WorktreeEntry } from "../lib/worktrees.ts";
+export type FindPullRequests = (arguments_: {
+    cwd: string;
+    branchName: string;
+    signal?: AbortSignal;
+}) => Promise<readonly PullRequestSummary[]>;
+export type FetchPullRequestDetails = (arguments_: {
+    urls: readonly string[];
+    signal?: AbortSignal;
+}) => Promise<Map<string, PullRequestDetail | undefined>>;
+export type ListCmuxWorkspaces = (signal?: AbortSignal) => Promise<CmuxWorkspaceSummary[] | undefined>;
+export type ReadCmuxStatus = (workspaceId: string, signal?: AbortSignal) => Promise<Map<string, string>>;
+export type WriteCmuxStatus = (workspaceId: string, write: CmuxStatusWrite, signal?: AbortSignal) => Promise<void>;
+export type IsCmuxAdapterActive = (signal?: AbortSignal) => Promise<boolean>;
+export interface PrStageSyncDeps {
+    config: ResolvedConfig;
+    findPullRequests: FindPullRequests;
+    fetchPullRequestDetails: FetchPullRequestDetails;
+    listCmuxWorkspaces: ListCmuxWorkspaces;
+    readCmuxStatus: ReadCmuxStatus;
+    writeCmuxStatus: WriteCmuxStatus;
+    isCmuxAdapterActive: IsCmuxAdapterActive;
+}
+export interface PrStageSyncTickArgs {
+    worktreeEntries: readonly WorktreeEntry[];
+    /** Orchestrator `--dry-run`; only `runOnce` honors it — `syncOnce` (`crew stage refresh`) always writes. */
+    dryRun?: boolean;
+    signal?: AbortSignal;
+}
+export interface PrStageSync {
+    /**
+     * The orchestrator tick step. A dry run skips everything. Otherwise
+     * `crew_ticket` is always written for matched cmux task workspaces; stage,
+     * labels, and the heartbeat are additionally synced only when
+     * `config.cmux.prStages.enabled` is true.
+     */
+    runOnce: (arguments_: PrStageSyncTickArgs) => Promise<void>;
+    /** Ungated (still requires the cmux adapter): `crew stage refresh` and the label CLI's trailing sync. */
+    syncOnce: (arguments_: PrStageSyncTickArgs) => Promise<void>;
+}
+/** Whether the resolved workspace backend for this config is cmux — every other adapter no-ops. */
+export declare function isCmuxAdapterActive(config: ResolvedConfig, signal?: AbortSignal): Promise<boolean>;
+export declare function createPrStageSync(deps: PrStageSyncDeps): PrStageSync;
+/** Wires the real cmux/gh-backed implementations behind `PrStageSyncDeps`. */
+export declare function createPrStageSyncDeps(config: ResolvedConfig): PrStageSyncDeps;
+//# sourceMappingURL=prStageSync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prStageSync.d.ts","sourceRoot":"","sources":["../../src/commands/prStageSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,oBAAoB,EAA8B,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EACL,KAAK,eAAe,EAKrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AASnG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAczD,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,MAAM,MAAM,uBAAuB,GAAG,CAAC,UAAU,EAAE;IACjD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,oBAAoB,EAAE,GAAG,SAAS,CAAC,CAAC;AACjD,MAAM,MAAM,cAAc,GAAG,CAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAClC,MAAM,MAAM,eAAe,GAAG,CAC5B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,eAAe,EACtB,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,IAAI,CAAC,CAAC;AACnB,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,uBAAuB,EAAE,uBAAuB,CAAC;IACjD,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,EAAE,eAAe,CAAC;IACjC,mBAAmB,EAAE,mBAAmB,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,4GAA4G;IAC5G,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,OAAO,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,yGAAyG;IACzG,QAAQ,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED,mGAAmG;AACnG,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAUlB;AA2QD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CA0KpE;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAU7E"}

package/dist/commands/prStageSync.js

@@ -0,0 +1,397 @@
+/**
+ * Per-tick sync that paints each tracked task's cmux sidebar with its ticket
+ * id, and — when `cmux.prStages.enabled` — its pull request's review stage
+ * and gating labels too. Replaces the standalone `crew-pr-stages` bash
+ * poller: same stage/ticket derivation rules (`../lib/prStageRules.ts`),
+ * same status-key contract the installed sidebar reads, but PRs are
+ * resolved from the task's own worktree branch
+ * (`findPullRequestsForBranchOrThrow`) instead of cmux's own git-branch PR
+ * detection.
+ *
+ * `crew_ticket` is written for every matched cmux task workspace regardless
+ * of the `cmux.prStages.enabled` opt-in, since a custom sidebar may read it
+ * independent of PR-stage sync; the opt-in only gates the `gh`-backed stage
+ * and label writes (and the `crew_poller_heartbeat` that signals they're
+ * running). `cmuxAdapter.ts` also writes it once at workspace-creation time,
+ * using the same `deriveTicket` rule, so a brand-new workspace shows a
+ * ticket pill before the first tick without disagreeing with it — this
+ * module keeps the value current afterward.
+ *
+ * Runs after the other tick steps in `orchestrator.ts`. Every failure is
+ * caught and logged here — a flaky `gh` call or a single misbehaving
+ * workspace must never break the watch loop or starve the other steps.
+ */
+import { listCmuxWorkspaceSummaries } from "../lib/cmuxAdapter.js";
+import { readCmuxStatus, TICKET_KEY, TICKET_PRIORITY, writeCmuxStatus, } from "../lib/cmuxStatusFields.js";
+import { detectHostCapabilities } from "../lib/host.js";
+import { fetchPullRequestDetails } from "../lib/pullRequestDetails.js";
+import { findPullRequestsForBranchOrThrow } from "../lib/pullRequests.js";
+import { deriveTicket, derivePrStage, managedLabelsField, } from "../lib/prStageRules.js";
+import { debug, errorMessage, logEvent, readEnvironmentVariable } from "../lib/util.js";
+import { resolveWorkspaceKind } from "../lib/workspaces.js";
+import { effectiveBranchName } from "../lib/worktreeRunState.js";
+const FLOW = "pr-stage-sync";
+const STAGE_KEY = "crew_stage";
+const STAGE_PRIORITY = -10;
+const HEARTBEAT_KEY = "crew_poller_heartbeat";
+const HEARTBEAT_PRIORITY = -12;
+const LABELS_KEY = "crew_labels";
+const LABELS_PRIORITY = -13;
+const CMUX_WORKSPACE_ID_ENV = "CMUX_WORKSPACE_ID";
+/** Whether the resolved workspace backend for this config is cmux — every other adapter no-ops. */
+export async function isCmuxAdapterActive(config, signal) {
+    try {
+        const { resolved } = resolveWorkspaceKind({
+            config,
+            host: await detectHostCapabilities(signal),
+        });
+        return resolved === "cmux";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Only cmux workspaces groundcrew created for a task are in scope: resolving
+ * a PR "from the task's worktree branch" presupposes a task. A cmux pane the
+ * user opened by hand has neither — it is left exactly as untouched as
+ * before this feature existed, rather than guessed at. The workspace's
+ * reported cwd is the precise match (handles multi-repo tasks); the task-id
+ * marker is the fallback for a workspace cmux hasn't reported a cwd for yet.
+ */
+function matchWorkspacesToTasks(workspaces, worktreeEntries) {
+    const matches = [];
+    for (const workspace of workspaces) {
+        const entry = worktreeEntries.find((candidate) => candidate.dir === workspace.currentDirectory) ??
+            worktreeEntries.find((candidate) => candidate.task === workspace.taskId);
+        if (entry !== undefined) {
+            matches.push({ workspace, entry });
+        }
+    }
+    return matches;
+}
+/** One PR to track per workspace: prefer a live one, then whichever terminal state, else whatever gh returned first. */
+function selectTrackedPullRequest(pullRequests) {
+    return (pullRequests.find((pr) => pr.state === "open") ??
+        pullRequests.find((pr) => pr.state === "merged") ??
+        pullRequests.find((pr) => pr.state === "closed") ??
+        pullRequests[0]);
+}
+function newCounters() {
+    return { written: 0, cleared: 0, skipped: 0 };
+}
+async function applyField(arguments_) {
+    const { workspaceId, key, priority, current, desired, signal, writeStatus, counters } = arguments_;
+    if (desired === current) {
+        counters.skipped += 1;
+        return;
+    }
+    await writeStatus(workspaceId, { key, priority, value: desired }, signal);
+    if (desired.length === 0) {
+        counters.cleared += 1;
+    }
+    else {
+        counters.written += 1;
+    }
+}
+/**
+ * The ticket field is derived from the workspace's own title/cwd, so it
+ * needs no PR lookup and is written for every matched cmux task workspace —
+ * including when `cmux.prStages.enabled` is false, so the sidebar's
+ * `crew_ticket` read works for everyone regardless of the PR-stage opt-in.
+ */
+async function writeTicketField(arguments_) {
+    const { workspace, current, deps, signal, counters } = arguments_;
+    await applyField({
+        workspaceId: workspace.id,
+        key: TICKET_KEY,
+        priority: TICKET_PRIORITY,
+        current: current.get(TICKET_KEY) ?? "",
+        desired: deriveTicket({
+            title: workspace.title,
+            ...(workspace.currentDirectory === undefined
+                ? {}
+                : { currentDirectory: workspace.currentDirectory }),
+        }) ?? "",
+        signal,
+        writeStatus: deps.writeCmuxStatus,
+        counters,
+    });
+}
+/**
+ * Stage and labels are cleared only when the branch is confirmed to have no
+ * PR; when discovery itself failed (network/auth error) or a PR exists but
+ * its detail couldn't be (re)confirmed this tick (a failed or partial
+ * GraphQL batch), they are left exactly as they were — never guessed, never
+ * cleared.
+ */
+async function syncWorkspace(arguments_) {
+    const { match, labelNames, pullRequest, pullRequestLookupFailed, detail, deps, signal, counters, } = arguments_;
+    const { workspace } = match;
+    const current = await deps.readCmuxStatus(workspace.id, signal);
+    await writeTicketField({ workspace, current, deps, signal, counters });
+    if (pullRequestLookupFailed) {
+        counters.skipped += 2;
+        return;
+    }
+    if (pullRequest === undefined) {
+        await applyField({
+            workspaceId: workspace.id,
+            key: STAGE_KEY,
+            priority: STAGE_PRIORITY,
+            current: current.get(STAGE_KEY) ?? "",
+            desired: "",
+            signal,
+            writeStatus: deps.writeCmuxStatus,
+            counters,
+        });
+        await applyField({
+            workspaceId: workspace.id,
+            key: LABELS_KEY,
+            priority: LABELS_PRIORITY,
+            current: current.get(LABELS_KEY) ?? "",
+            desired: "",
+            signal,
+            writeStatus: deps.writeCmuxStatus,
+            counters,
+        });
+        return;
+    }
+    if (detail === undefined) {
+        counters.skipped += 2;
+        return;
+    }
+    await applyField({
+        workspaceId: workspace.id,
+        key: STAGE_KEY,
+        priority: STAGE_PRIORITY,
+        current: current.get(STAGE_KEY) ?? "",
+        desired: derivePrStage(detail, labelNames),
+        signal,
+        writeStatus: deps.writeCmuxStatus,
+        counters,
+    });
+    await applyField({
+        workspaceId: workspace.id,
+        key: LABELS_KEY,
+        priority: LABELS_PRIORITY,
+        current: current.get(LABELS_KEY) ?? "",
+        desired: managedLabelsField(detail.labels, labelNames),
+        signal,
+        writeStatus: deps.writeCmuxStatus,
+        counters,
+    });
+}
+async function resolvePullRequestsByWorkspace(arguments_) {
+    const { matches, config, findPullRequests, signal } = arguments_;
+    const byWorkspace = new Map();
+    const failedWorkspaceIds = new Set();
+    for (const match of matches) {
+        // oxlint-disable-next-line no-await-in-loop -- one gh lookup per matched workspace; mirrors reviewer.ts's sequential PR lookups
+        const branchName = await effectiveBranchName({ config, entry: match.entry });
+        try {
+            // oxlint-disable-next-line no-await-in-loop -- see above
+            const pullRequests = await findPullRequests({
+                cwd: match.entry.dir,
+                branchName,
+                ...(signal === undefined ? {} : { signal }),
+            });
+            byWorkspace.set(match.workspace.id, selectTrackedPullRequest(pullRequests));
+        }
+        catch (error) {
+            debug(`pr-stage-sync: PR lookup failed for ${match.entry.task}: ${errorMessage(error)}`);
+            failedWorkspaceIds.add(match.workspace.id);
+        }
+    }
+    return { byWorkspace, failedWorkspaceIds };
+}
+/**
+ * Prefers the first matched task workspace, since the sidebar's staleness
+ * check (`heartbeatFresh`) scans every workspace for any recent heartbeat —
+ * it doesn't matter which task workspace carries it from pass to pass. This
+ * matters because `crew stage refresh`/`label-add`/`label-remove` run this
+ * same pass from a cmux Action's own ephemeral workspace, which cmux closes
+ * right after the command exits; a heartbeat written there would vanish with
+ * it, making a successful on-demand refresh look stale on the very next
+ * render. Falls back to the watch loop's own cmux workspace
+ * (`$CMUX_WORKSPACE_ID`) only when no task is currently tracked, so a
+ * fully-working sync with zero matched tasks still reports a heartbeat
+ * somewhere instead of silently writing none at all.
+ */
+async function writeHeartbeat(arguments_) {
+    const targetWorkspaceId = arguments_.matches[0]?.workspace.id ?? readEnvironmentVariable(CMUX_WORKSPACE_ID_ENV);
+    if (targetWorkspaceId === undefined) {
+        return;
+    }
+    const epochSeconds = String(Math.floor(Date.now() / 1000));
+    await arguments_.writeStatus(targetWorkspaceId, { key: HEARTBEAT_KEY, priority: HEARTBEAT_PRIORITY, value: epochSeconds }, arguments_.signal);
+}
+const TICKETS_ONLY_FLOW = "pr-stage-sync.tickets-only";
+export function createPrStageSync(deps) {
+    /**
+     * Runs when `cmux.prStages.enabled` is false: writes only `crew_ticket` for
+     * each matched task workspace, with no `gh` lookups, no stage/label
+     * writes, and no `crew_poller_heartbeat` — the absence of any heartbeat is
+     * exactly what tells the sidebar the PR-stage feature is off, so it must
+     * never be written from this path.
+     */
+    async function syncTicketsOnly(arguments_) {
+        const { worktreeEntries, signal } = arguments_;
+        if (!(await deps.isCmuxAdapterActive(signal))) {
+            return;
+        }
+        debug("pr-stage-sync: starting (tickets-only, cmux.prStages disabled)");
+        const counters = newCounters();
+        let outcome = "updated";
+        let reason;
+        try {
+            const workspaces = await deps.listCmuxWorkspaces(signal);
+            if (workspaces === undefined) {
+                logEvent(TICKETS_ONLY_FLOW, { outcome: "error", reason: "workspace_list_failed" });
+                return;
+            }
+            const matches = matchWorkspacesToTasks(workspaces, worktreeEntries);
+            for (const match of matches) {
+                try {
+                    // oxlint-disable-next-line no-await-in-loop -- sequential per workspace, mirrors syncOnce
+                    const current = await deps.readCmuxStatus(match.workspace.id, signal);
+                    // oxlint-disable-next-line no-await-in-loop -- sequential per workspace, mirrors syncOnce
+                    await writeTicketField({ workspace: match.workspace, current, deps, signal, counters });
+                }
+                catch (error) {
+                    outcome = "error";
+                    reason = "status_write_failed";
+                    debug(`pr-stage-sync: ticket write failed for ${match.entry.task}: ${errorMessage(error)}`);
+                }
+            }
+        }
+        catch (error) {
+            outcome = "error";
+            reason = errorMessage(error);
+        }
+        logEvent(TICKETS_ONLY_FLOW, {
+            outcome,
+            written: counters.written,
+            cleared: counters.cleared,
+            skipped: counters.skipped,
+            ...(reason === undefined ? {} : { reason }),
+        });
+    }
+    async function syncOnce(arguments_) {
+        const { worktreeEntries, signal } = arguments_;
+        const { config } = deps;
+        if (!(await deps.isCmuxAdapterActive(signal))) {
+            return;
+        }
+        debug("pr-stage-sync: starting");
+        const counters = newCounters();
+        let outcome = "updated";
+        let reason;
+        try {
+            const workspaces = await deps.listCmuxWorkspaces(signal);
+            if (workspaces === undefined) {
+                logEvent(FLOW, { outcome: "error", reason: "workspace_list_failed" });
+                return;
+            }
+            const matches = matchWorkspacesToTasks(workspaces, worktreeEntries);
+            const { byWorkspace: pullRequestByWorkspace, failedWorkspaceIds } = await resolvePullRequestsByWorkspace({
+                matches,
+                config,
+                findPullRequests: deps.findPullRequests,
+                signal,
+            });
+            if (failedWorkspaceIds.size > 0) {
+                outcome = "error";
+                reason = "pull_request_lookup_failed";
+            }
+            const urls = [
+                ...new Set([...pullRequestByWorkspace.values()].flatMap((pr) => (pr === undefined ? [] : [pr.url]))),
+            ];
+            let details = new Map();
+            if (urls.length > 0) {
+                try {
+                    details = await deps.fetchPullRequestDetails({
+                        urls,
+                        ...(signal === undefined ? {} : { signal }),
+                    });
+                }
+                catch (error) {
+                    outcome = "error";
+                    reason = "pull_request_detail_lookup_failed";
+                    debug(`pr-stage-sync: PR detail lookup failed: ${errorMessage(error)}`);
+                }
+            }
+            for (const match of matches) {
+                const pullRequest = pullRequestByWorkspace.get(match.workspace.id);
+                const detail = pullRequest === undefined ? undefined : details.get(pullRequest.url);
+                try {
+                    // oxlint-disable-next-line no-await-in-loop -- sequential per workspace so one workspace's status calls never interleave with another's
+                    await syncWorkspace({
+                        match,
+                        labelNames: config.cmux.prStages.labels,
+                        pullRequest,
+                        pullRequestLookupFailed: failedWorkspaceIds.has(match.workspace.id),
+                        detail,
+                        deps,
+                        signal,
+                        counters,
+                    });
+                }
+                catch (error) {
+                    outcome = "error";
+                    reason = "status_write_failed";
+                    debug(`pr-stage-sync: sync failed for ${match.entry.task}: ${errorMessage(error)}`);
+                }
+            }
+            try {
+                await writeHeartbeat({ matches, writeStatus: deps.writeCmuxStatus, signal });
+            }
+            catch (error) {
+                // A heartbeat failure is reported only when nothing else already
+                // flagged this pass as an error, so it never masks a more specific
+                // reason (like a per-workspace status_write_failed) from an earlier
+                // step in the same pass.
+                if (outcome !== "error") {
+                    outcome = "error";
+                    reason = "heartbeat_write_failed";
+                }
+                debug(`pr-stage-sync: heartbeat write failed: ${errorMessage(error)}`);
+            }
+        }
+        catch (error) {
+            outcome = "error";
+            reason = errorMessage(error);
+        }
+        logEvent(FLOW, {
+            outcome,
+            written: counters.written,
+            cleared: counters.cleared,
+            skipped: counters.skipped,
+            ...(reason === undefined ? {} : { reason }),
+        });
+    }
+    async function runOnce(arguments_) {
+        if (arguments_.dryRun === true) {
+            logEvent(FLOW, { outcome: "skipped", reason: "dry_run" });
+            return;
+        }
+        if (!deps.config.cmux.prStages.enabled) {
+            await syncTicketsOnly(arguments_);
+            return;
+        }
+        await syncOnce(arguments_);
+    }
+    return { runOnce, syncOnce };
+}
+/** Wires the real cmux/gh-backed implementations behind `PrStageSyncDeps`. */
+export function createPrStageSyncDeps(config) {
+    return {
+        config,
+        findPullRequests: findPullRequestsForBranchOrThrow,
+        fetchPullRequestDetails,
+        listCmuxWorkspaces: listCmuxWorkspaceSummaries,
+        readCmuxStatus,
+        writeCmuxStatus,
+        isCmuxAdapterActive: async (signal) => await isCmuxAdapterActive(config, signal),
+    };
+}

package/dist/commands/stage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `crew stage` — operator commands for `pr-stage-sync`'s two gating labels
+ * (`label-add` / `label-remove`) and an on-demand sync pass (`refresh`).
+ * Labels are restricted to the two names configured under
+ * `cmux.prStages.labels`; each is created in the PR's repo on first use with
+ * a fixed color so the two gates stay visually distinct in GitHub's label UI.
+ */
+export declare function stageCli(argv: string[]): Promise<void>;
+//# sourceMappingURL=stage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../../src/commands/stage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuJH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAe5D"}