@clipboard-health/groundcrew 2.3.0 → 2.3.1

package/README.md

@@ -92,6 +92,7 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
 
    ```bash
    crew doctor
+   crew doctor --ticket TEAM-123
    crew run --dry-run
    crew run            # one-shot
    crew run --watch    # poll forever
@@ -162,15 +163,71 @@ Rules:
 ## Manual commands
 
 ```bash
+crew doctor --ticket <TICKET>
 crew run --ticket <TICKET>
 crew setup repos [--dry-run] [<repo>...]
 crew cleanup <TICKET>
 ```
 
+`crew doctor --ticket <TICKET>` diagnoses one Linear ticket without provisioning it. It checks the same resolution inputs that decide whether the orchestrator can see the ticket — Todo status, `agent-*` label, model resolution, repository mention, local clone — then checks blockers, model session usage, and available in-progress capacity.
+
 `crew run --ticket <TICKET>` provisions a single ticket the same way the orchestrator would: the repo is parsed from the ticket's Linear description and the model comes from the ticket's `agent-*` label (manual setup falls back to `models.default` for unlabeled tickets). If the description does not mention a repo from `workspace.knownRepositories`, setup fails before provisioning. `--watch` and `--ticket` are mutually exclusive — `--watch` drives the orchestrator loop; `--ticket` provisions one ticket and exits. `crew cleanup <TICKET>` resolves to every tracked worktree carrying that ticket id (across repos) and tears them all down. To inspect codexbar session windows directly, run `codexbar usage`; the orchestrator already gates on this internally via `orchestrator.sessionLimitPercentage`.
 
+### `crew doctor --ticket <ticket>`
+
+Diagnose why a ticket would or wouldn't be dispatched on the next orchestrator tick. Runs the same resolution and eligibility chain as the dispatcher, but for a single ticket, and prints a tree of pass/fail checks.
+
+```bash
+crew doctor --ticket HRD-446
+```
+
+Exits 0 if the ticket would dispatch, 1 otherwise. Useful when you've labelled a ticket with `agent-claude` and it doesn't show up on the board.
+
+Example output for a ticket that would dispatch:
+
+```text
+groundcrew doctor --ticket HRD-446 (Add retry logic to the sync job)
+────────────────────────────────────────────────────────────────────
+
+Resolution
+  [ok] Ticket exists in Linear ("Add retry logic to the sync job")
+  [ok] Status is Todo
+  [ok] Has agent-* label (agent-claude)
+  [ok] Model resolves from agent-* label (model "claude")
+  [ok] Description mentions known repo (owner/repo)
+  [ok] Resolved repo is cloned locally (/dev/workspaces/owner/repo)
+
+Eligibility
+  [ok] No active blockers
+  [ok] Model "claude" usage under sessionLimitPercentage (12% (limit 85%))
+  [ok] In-progress cap not hit (2/4 used)
+
+→ would be dispatched on next tick
+```
+
+Example output for a ticket that's not in the Todo status:
+
+```text
+groundcrew doctor --ticket HRD-447 (Refactor auth middleware)
+─────────────────────────────────────────────────────────────
+
+Resolution
+  [ok] Ticket exists in Linear ("Refactor auth middleware")
+  [--] Status is Todo (current: In Progress)
+  [ok] Has agent-* label (agent-claude)
+  [ok] Model resolves from agent-* label (model "claude")
+  [ok] Description mentions known repo (owner/repo)
+  [ok] Resolved repo is cloned locally (/dev/workspaces/owner/repo)
+
+Eligibility
+  (skipped — resolution checks failed)
+
+→ ineligible: status is In Progress (need Todo)
+```
+
 ## Gotchas
 
+- **Ticket labeled but not on the board?** Run `crew doctor --ticket <ticket>` — it lists every check the dispatcher runs and flags the failing one.
 - **Local execution picks one of safehouse/sdx/none.** `local.runner: "auto"` resolves to `safehouse` on macOS and `sdx` (Docker Sandboxes) on Linux/WSL. Override with `local.runner: "safehouse" | "sdx" | "none"`. There is no per-model `isolation` knob anymore — the runner is global. `sdx` requires a per-model `sandbox: { agent }` block so groundcrew can map the model to an sbx agent.
 - **Safehouse-already-wrapped commands are not re-wrapped.** If a `models.definitions.<name>.cmd` already starts with `safehouse`, groundcrew assumes that command owns its Safehouse flags and does not add the `safehouse-clearance` wrapper a second time. Changing the proxy's allowlist after it's running requires killing the PID in `${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.pid` so the next launch picks up the new env.
 - **Sandbox lifecycle is create-only.** Groundcrew auto-creates the sandbox for a `<repository, model>` pair when missing, but never deletes one — sandboxes persist across tickets and across `crew cleanup`. Auth state lives inside the sandbox, so deleting it forces a re-login. Inspect or remove them manually with `sbx ls` / `sbx rm`.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA0HA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAyIA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}

package/dist/cli.js

@@ -51,6 +51,24 @@ async function runCli(argv) {
     }
     await setupWorkspaceCli(ticket, { dryRun });
 }
+async function doctorCli(argv) {
+    let ticket;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--ticket") {
+            const value = argv[index + 1];
+            if (value === undefined || value.length === 0 || value.startsWith("-")) {
+                throw new Error("crew doctor --ticket: ticket id is required");
+            }
+            ticket = value;
+            index += 1;
+            continue;
+        }
+        throw new Error(`crew doctor: unknown argument: ${argument}`);
+    }
+    const ok = ticket === undefined ? await doctor() : await doctor({ ticket });
+    process.exitCode = ok ? process.exitCode : 1;
+}
 const SUBCOMMANDS = {
     run: {
         summary: "Run the orchestrator (one-shot by default), or provision one ticket with --ticket",
@@ -58,13 +76,9 @@ const SUBCOMMANDS = {
         invoke: runCli,
     },
     doctor: {
-        summary: "Verify prereqs against the resolved config",
-        invoke: async () => {
-            const ok = await doctor();
-            if (!ok) {
-                process.exitCode = 1;
-            }
-        },
+        summary: "Verify prereqs, or diagnose one ticket with --ticket",
+        usage: "[--ticket <ticket>]",
+        invoke: doctorCli,
     },
     cleanup: {
         summary: "Tear down a worktree",
@@ -87,9 +101,7 @@ function printHelp() {
     writeOutput("Commands:");
     for (const [name, command] of Object.entries(SUBCOMMANDS)) {
         writeOutput(`  ${name.padEnd(width)}  ${command.summary}`);
-        if (command.usage !== undefined) {
-            writeOutput(`  ${" ".repeat(width)}  → crew ${name} ${command.usage}`);
-        }
+        writeOutput(`  ${" ".repeat(width)}  → crew ${name} ${command.usage}`);
     }
     writeOutput("\nSee README.md for full configuration and behavior.");
 }

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

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/commands/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAczD,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,UAAU,EAAE;QAClB,KAAK,EAAE,UAAU,CAAC;QAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;QAC1C,+FAA+F;QAC/F,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;QACvD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAmNjE"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/commands/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,UAAU,EAAE;QAClB,KAAK,EAAE,UAAU,CAAC;QAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;QAC1C,+FAA+F;QAC/F,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;QACvD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAuLjE"}

package/dist/commands/dispatcher.js

@@ -10,42 +10,16 @@ import { isGroundcrewIssue } from "../lib/boardSource.js";
 import { createLinearIssueStatusUpdater } from "../lib/linearIssueStatus.js";
 import { errorMessage, log, logEvent } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
-import { classifyBlockers, classifyEligibility, } from "./eligibility.js";
+import { classifyBlockers, classifyEligibility, classifyUsageExhaustion, } from "./eligibility.js";
 import { setupWorkspace } from "./setupWorkspace.js";
-const PERCENT_FRACTION_DIVISOR = 100;
-const DAYS_PER_WEEK = 7;
-const MINUTES_PER_DAY = 24 * 60;
-const MINUTES_PER_WEEK = DAYS_PER_WEEK * MINUTES_PER_DAY;
 export function createDispatcher(deps) {
     const { config, client } = deps;
     const issueStatusUpdater = createLinearIssueStatusUpdater({ config, client });
     function buildExhaustedSet(usage) {
         const exhausted = new Set();
-        const sessionLimit = config.orchestrator.sessionLimitPercentage;
-        for (const [model, snapshot] of Object.entries(usage)) {
-            if (snapshot.session !== null && snapshot.session * PERCENT_FRACTION_DIVISOR > sessionLimit) {
-                exhausted.add(model);
-                const pct = (snapshot.session * PERCENT_FRACTION_DIVISOR).toFixed(0);
-                const mins = snapshot.sessionEndDuration ?? "?";
-                log(`${model} session at ${pct}% (> ${sessionLimit}%), resets in ${mins}m — skipping its tickets`);
-            }
-            // Weekly gate paces total weekly usage against day buckets from the
-            // weekly reset. Day 1's budget is available immediately after rollover,
-            // then each later day opens another 1/7 of the weekly budget. Skipped when:
-            //   - weekly is null (no codexbar secondary window this tick)
-            //   - weekly is non-finite (EXHAUSTED_USAGE — session gate above
-            //     already pins it to Infinity)
-            //   - weekEndDuration is null (can't compute where we are in week)
-            if (snapshot.weekly !== null &&
-                Number.isFinite(snapshot.weekly) &&
-                snapshot.weekEndDuration !== null) {
-                const usedPct = snapshot.weekly * PERCENT_FRACTION_DIVISOR;
-                const allowedPct = weeklyPacedBudgetPercentage(snapshot.weekEndDuration);
-                if (usedPct > allowedPct) {
-                    exhausted.add(model);
-                    log(`${model} weekly at ${usedPct.toFixed(1)}% (> ${allowedPct.toFixed(1)}% paced budget), resets in ${snapshot.weekEndDuration}m — skipping its tickets`);
-                }
-            }
+        for (const exhaustion of classifyUsageExhaustion(config, usage)) {
+            exhausted.add(exhaustion.model);
+            log(formatUsageExhaustion(exhaustion));
         }
         return exhausted;
     }
@@ -187,9 +161,10 @@ export function createDispatcher(deps) {
     }
     return { runOnce };
 }
-function weeklyPacedBudgetPercentage(weekEndDuration) {
-    const elapsedMinutes = Math.min(MINUTES_PER_WEEK, Math.max(0, MINUTES_PER_WEEK - weekEndDuration));
-    const elapsedDayCount = Math.ceil(elapsedMinutes / MINUTES_PER_DAY);
-    const budgetDayCount = Math.min(DAYS_PER_WEEK, Math.max(1, elapsedDayCount));
-    return (budgetDayCount / DAYS_PER_WEEK) * PERCENT_FRACTION_DIVISOR;
+function formatUsageExhaustion(exhaustion) {
+    if (exhaustion.kind === "session") {
+        const mins = exhaustion.resetMinutes ?? "?";
+        return `${exhaustion.model} session at ${exhaustion.usedPercentage.toFixed(0)}% (> ${exhaustion.limitPercentage}%), resets in ${mins}m — skipping its tickets`;
+    }
+    return `${exhaustion.model} weekly at ${exhaustion.usedPercentage.toFixed(1)}% (> ${exhaustion.allowedPercentage.toFixed(1)}% paced budget), resets in ${exhaustion.resetMinutes}m — skipping its tickets`;
 }

package/dist/commands/doctor.d.ts

@@ -2,5 +2,8 @@
  * doctor — verify groundcrew prerequisites against the resolved config.
  * Returns true if every required check passes; false otherwise.
  */
-export declare function doctor(): Promise<boolean>;
+export interface DoctorOptions {
+    ticket?: string;
+}
+export declare function doctor(options?: DoctorOptions): Promise<boolean>;
 //# sourceMappingURL=doctor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8IH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAkE/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2BH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsHD,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAK1E"}

package/dist/commands/doctor.js

@@ -8,6 +8,7 @@ import { detectHostCapabilities, which } from "../lib/host.js";
 import { resolveLocalRunner } from "../lib/localRunner.js";
 import { errorMessage, resolveLinearApiKey, writeOutput } from "../lib/util.js";
 import { resolveWorkspaceKind } from "../lib/workspaces.js";
+import { runTicketDoctor } from "./ticketDoctor.js";
 // Tokenization stops after this many non-flag tokens. Two is enough to
 // catch wrapper + wrapped CLI commands like `safehouse claude --foo`.
 const MAX_TOKENS_PER_CMD = 2;
@@ -121,7 +122,26 @@ function format(check) {
     const hint = check.hint !== undefined && check.hint.length > 0 ? `  — ${check.hint}` : "";
     return `${tag}${check.name}${hint}`;
 }
-export async function doctor() {
+export async function doctor(options = {}) {
+    if (options.ticket !== undefined) {
+        return await doctorTicket(options.ticket);
+    }
+    return await doctorHost();
+}
+async function doctorTicket(ticket) {
+    try {
+        return await runTicketDoctor(ticket);
+    }
+    catch (error) {
+        const displayTicket = ticket.toUpperCase();
+        const header = `groundcrew doctor --ticket ${displayTicket}`;
+        writeOutput(header);
+        writeOutput("=".repeat(header.length));
+        writeOutput(`[--] config: ${errorMessage(error)}`);
+        return false;
+    }
+}
+async function doctorHost() {
     writeOutput("groundcrew doctor");
     writeOutput("=================");
     let config;

package/dist/commands/eligibility.d.ts

@@ -37,6 +37,19 @@ export interface SkipVerdict {
     model?: string;
 }
 type Verdict = StartVerdict | SkipVerdict;
+export type ModelUsageExhaustion = {
+    kind: "session";
+    model: string;
+    usedPercentage: number;
+    limitPercentage: number;
+    resetMinutes: number | null;
+} | {
+    kind: "weekly";
+    model: string;
+    usedPercentage: number;
+    allowedPercentage: number;
+    resetMinutes: number;
+};
 export interface ClassifyArguments {
     config: ResolvedConfig;
     /**
@@ -68,6 +81,7 @@ interface BlockerClassification {
  * falls back to the default predictably.
  */
 export declare function pickBestModel(config: ResolvedConfig, usage: UsageByModel, exhausted: Set<string>): string | undefined;
+export declare function classifyUsageExhaustion(config: ResolvedConfig, usage: UsageByModel): ModelUsageExhaustion[];
 /**
  * Cheap pre-pass — partitions Todo into unblocked issues and blocker
  * skip verdicts. Runs before the dispatcher fetches usage or probes the

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

@@ -1 +1 @@
-{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../src/commands/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAgB,KAAK,eAAe,EAAoB,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,KAAK,UAAU,GACX,SAAS,GACT,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,4BAA4B,GAC5B,mBAAmB,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,eAAe,CAAC;IACvB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,EAAE,UAAU,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,cAAc,EAAE,cAAc,CAAC;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAqCD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,MAAM,GAAG,SAAS,CAepB;AA4CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,qBAAqB,CAYvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,EAAE,CAgE5E"}
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../src/commands/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAgB,KAAK,eAAe,EAAoB,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOzD,KAAK,UAAU,GACX,SAAS,GACT,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,4BAA4B,GAC5B,mBAAmB,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,eAAe,CAAC;IACvB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,EAAE,UAAU,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC;AAE1C,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,cAAc,EAAE,cAAc,CAAC;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,qBAAqB;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAqCD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,MAAM,GAAG,SAAS,CAepB;AAaD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,GAClB,oBAAoB,EAAE,CAmCxB;AA4CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,qBAAqB,CAYvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,EAAE,CAgE5E"}

package/dist/commands/eligibility.js

@@ -8,6 +8,10 @@
  */
 import { isTerminalStatus } from "../lib/boardSource.js";
 import { AGENT_ANY_MODEL } from "../lib/config.js";
+const PERCENT_FRACTION_DIVISOR = 100;
+const DAYS_PER_WEEK = 7;
+const MINUTES_PER_DAY = 24 * 60;
+const MINUTES_PER_WEEK = DAYS_PER_WEEK * MINUTES_PER_DAY;
 function blockerSummary(blocker) {
     return `${blocker.id}:${blocker.status ?? "missing"}`;
 }
@@ -59,6 +63,46 @@ export function pickBestModel(config, usage, exhausted) {
         return best;
     }).name;
 }
+function weeklyPacedBudgetPercentage(weekEndDuration) {
+    const elapsedMinutes = Math.min(MINUTES_PER_WEEK, Math.max(0, MINUTES_PER_WEEK - weekEndDuration));
+    const elapsedDayCount = Math.ceil(elapsedMinutes / MINUTES_PER_DAY);
+    const budgetDayCount = Math.min(DAYS_PER_WEEK, Math.max(1, elapsedDayCount));
+    return (budgetDayCount / DAYS_PER_WEEK) * PERCENT_FRACTION_DIVISOR;
+}
+export function classifyUsageExhaustion(config, usage) {
+    const exhausted = [];
+    const sessionLimit = config.orchestrator.sessionLimitPercentage;
+    for (const [model, snapshot] of Object.entries(usage)) {
+        if (snapshot.session !== null && snapshot.session * PERCENT_FRACTION_DIVISOR > sessionLimit) {
+            exhausted.push({
+                kind: "session",
+                model,
+                usedPercentage: snapshot.session * PERCENT_FRACTION_DIVISOR,
+                limitPercentage: sessionLimit,
+                resetMinutes: snapshot.sessionEndDuration,
+            });
+        }
+        // Weekly gate paces total weekly usage against day buckets from the
+        // weekly reset. Day 1's budget is available immediately after rollover,
+        // then each later day opens another 1/7 of the weekly budget.
+        if (snapshot.weekly !== null &&
+            Number.isFinite(snapshot.weekly) &&
+            snapshot.weekEndDuration !== null) {
+            const usedPercentage = snapshot.weekly * PERCENT_FRACTION_DIVISOR;
+            const allowedPercentage = weeklyPacedBudgetPercentage(snapshot.weekEndDuration);
+            if (usedPercentage > allowedPercentage) {
+                exhausted.push({
+                    kind: "weekly",
+                    model,
+                    usedPercentage,
+                    allowedPercentage,
+                    resetMinutes: snapshot.weekEndDuration,
+                });
+            }
+        }
+    }
+    return exhausted;
+}
 // Stale worktrees with no matching live workspace are filtered out here so
 // they don't permanently block later tickets in the Todo queue.
 function classifyRecovery(arguments_) {

package/dist/commands/ticketDoctor.d.ts

@@ -0,0 +1,48 @@
+import { type Blocker, type RawLinearIssue } from "../lib/boardSource.ts";
+import { type ResolvedConfig } from "../lib/config.ts";
+import { type UsageByModel } from "../lib/usage.ts";
+export type TicketDoctorVerdict = {
+    kind: "would-dispatch";
+} | {
+    kind: "ineligible";
+    reason: string;
+} | {
+    kind: "unresolvable";
+    reason: string;
+};
+export interface TicketCheck {
+    name: string;
+    status: "ok" | "fail" | "skipped";
+    detail?: string;
+    failureSummary?: string;
+}
+export interface TicketDoctorResult {
+    ticket: string;
+    title?: string;
+    resolution: TicketCheck[];
+    eligibility: TicketCheck[];
+    verdict: TicketDoctorVerdict;
+}
+export interface TicketDoctorDependencies {
+    config: ResolvedConfig;
+    ticket: string;
+    /**
+     * Injected to keep `ticketDoctor` pure and easy to unit-test. Production
+     * callers pass a closure that delegates to `fetchRawLinearIssue` with a
+     * real `LinearClient`; tests pass a `vi.fn()` returning a fixture.
+     */
+    fetchRawIssue: (input: {
+        ticket: string;
+    }) => Promise<RawLinearIssue>;
+    fetchBlockersFor: (input: {
+        ticket: string;
+        uuid: string;
+    }) => Promise<readonly Blocker[]>;
+    fetchUsage: () => Promise<UsageByModel>;
+    countInProgress: () => Promise<number>;
+}
+export declare function renderTicketDoctorResult(result: TicketDoctorResult): string[];
+export declare function ticketDoctor(dependencies: TicketDoctorDependencies): Promise<TicketDoctorResult>;
+export declare function ticketDoctorCli(argv: string[]): Promise<void>;
+export declare function runTicketDoctor(ticket: string): Promise<boolean>;
+//# sourceMappingURL=ticketDoctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ticketDoctor.d.ts","sourceRoot":"","sources":["../../src/commands/ticketDoctor.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,OAAO,EAEZ,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAA+B,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AASrE,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACtE,gBAAgB,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IAC3F,UAAU,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IACxC,eAAe,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AA+SD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAmB7E;AAED,wBAAsB,YAAY,CAChC,YAAY,EAAE,wBAAwB,GACrC,OAAO,CAAC,kBAAkB,CAAC,CA0F7B;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAenE;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBtE"}

package/dist/commands/ticketDoctor.js

@@ -0,0 +1,402 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fetchBlockersForTicket, fetchInProgressIssueCount, fetchRawLinearIssue, resolveModelFor, resolveRepositoryFor, } from "../lib/boardSource.js";
+import { AGENT_ANY_MODEL, loadConfig } from "../lib/config.js";
+import { getUsageByModel } from "../lib/usage.js";
+import { getLinearClient, writeOutput } from "../lib/util.js";
+import { classifyBlockers, classifyUsageExhaustion, pickBestModel, } from "./eligibility.js";
+function buildModelChecks(raw, config) {
+    const modelResolution = resolveModelFor({ labels: raw.labels, config });
+    const checks = [];
+    switch (modelResolution.kind) {
+        case "no-label": {
+            checks.push({
+                name: "Has agent-* label",
+                status: "fail",
+                detail: "no agent-* label on this ticket",
+                failureSummary: "ticket has no agent-* label",
+            });
+            checks.push({ name: "Model resolves from agent-* label", status: "skipped" });
+            break;
+        }
+        case "agent-any": {
+            checks.push({
+                name: "Has agent-* label",
+                status: "ok",
+                detail: "agent-any",
+            });
+            checks.push({
+                name: "Model resolves from agent-* label",
+                status: "ok",
+                detail: `model picked at dispatch time; defaults to "${config.models.default}" when usage ties`,
+            });
+            break;
+        }
+        case "matched": {
+            checks.push({
+                name: "Has agent-* label",
+                status: "ok",
+                detail: `agent-${modelResolution.model}`,
+            });
+            checks.push({
+                name: "Model resolves from agent-* label",
+                status: "ok",
+                detail: `model "${modelResolution.model}"`,
+            });
+            break;
+        }
+        case "disabled-fallback": {
+            checks.push({
+                name: "Has agent-* label",
+                status: "ok",
+                detail: `agent-${modelResolution.requestedModel}`,
+            });
+            checks.push({
+                name: "Model resolves from agent-* label",
+                status: "ok",
+                detail: `agent-${modelResolution.requestedModel} disabled; falling back to model "${modelResolution.fallbackModel}"`,
+            });
+            break;
+        }
+        /* v8 ignore next @preserve */
+        default: {
+            break;
+        }
+    }
+    let resolvedModel = config.models.default;
+    if (modelResolution.kind === "matched") {
+        resolvedModel = modelResolution.model;
+    }
+    else if (modelResolution.kind === "agent-any") {
+        resolvedModel = AGENT_ANY_MODEL;
+    }
+    else if (modelResolution.kind === "disabled-fallback") {
+        resolvedModel = modelResolution.fallbackModel;
+    }
+    return { resolvedModel, checks };
+}
+function buildRepoChecks(raw, config, ticket) {
+    const repositoryResolution = resolveRepositoryFor({
+        description: raw.description,
+        config,
+        ticket,
+    });
+    const checks = [];
+    if (repositoryResolution.kind === "ok") {
+        checks.push({
+            name: "Description mentions known repo",
+            status: "ok",
+            detail: repositoryResolution.repository,
+        });
+        const repoDir = join(config.workspace.projectDir, repositoryResolution.repository);
+        if (existsSync(repoDir)) {
+            checks.push({
+                name: "Resolved repo is cloned locally",
+                status: "ok",
+                detail: repoDir,
+            });
+        }
+        else {
+            checks.push({
+                name: "Resolved repo is cloned locally",
+                status: "fail",
+                detail: `${repositoryResolution.repository} not found at ${repoDir} — run \`crew setup repos ${repositoryResolution.repository}\``,
+                failureSummary: `resolved repo ${repositoryResolution.repository} is not cloned locally`,
+            });
+        }
+    }
+    else {
+        checks.push({
+            name: "Description mentions known repo",
+            status: "fail",
+            detail: `no entry from workspace.knownRepositories (${config.workspace.knownRepositories.join(", ")}) appears in description`,
+            failureSummary: "description does not mention a known repo",
+        });
+        checks.push({
+            name: "Resolved repo is cloned locally",
+            status: "skipped",
+        });
+    }
+    // repositoryResolution.kind is "ok" only when the first check passed.
+    /* v8 ignore else @preserve */
+    const resolvedRepository = repositoryResolution.kind === "ok" ? repositoryResolution.repository : "";
+    return { resolvedRepository, checks };
+}
+async function runEligibilityChecks(arguments_) {
+    const { ticket, raw, config, resolvedRepository, resolvedModel, dependencies, eligibility } = arguments_;
+    const blockers = await dependencies.fetchBlockersFor({ ticket, uuid: raw.uuid });
+    const groundcrewIssue = {
+        id: ticket,
+        uuid: raw.uuid,
+        title: raw.title,
+        status: raw.stateName,
+        statusId: "",
+        assignee: "",
+        updatedAt: "",
+        teamId: raw.teamId,
+        repository: resolvedRepository,
+        model: resolvedModel,
+        blockers: [...blockers],
+        hasMoreBlockers: raw.hasMoreBlockers,
+    };
+    const blockerClassification = classifyBlockers(config, [groundcrewIssue]);
+    const [firstSkip] = blockerClassification.skips;
+    if (firstSkip !== undefined) {
+        if (firstSkip.eventReason === "blockers_paginated") {
+            eligibility.push({
+                name: "No active blockers",
+                status: "fail",
+                detail: "blockers exceeded the v1 relation page size",
+                failureSummary: "blockers exceeded the v1 relation page size",
+            });
+            return false;
+        }
+        // firstSkip.blockers is always set for "blocked" and "blockers_paginated" skip reasons.
+        /* v8 ignore next @preserve */
+        const blockerIds = firstSkip.blockers ?? [];
+        eligibility.push({
+            name: "No active blockers",
+            status: "fail",
+            detail: blockerIds.join(", "),
+            failureSummary: `blocked by ${blockerIds.join(", ")}`,
+        });
+        return false;
+    }
+    eligibility.push({ name: "No active blockers", status: "ok" });
+    const usage = await dependencies.fetchUsage();
+    const usageExhaustion = classifyUsageExhaustion(config, usage);
+    const exhausted = new Set(usageExhaustion.map((exhaustion) => exhaustion.model));
+    let model = resolvedModel;
+    let resolvedFromAny = "";
+    if (model === AGENT_ANY_MODEL) {
+        const picked = pickBestModel(config, usage, exhausted);
+        if (picked === undefined) {
+            eligibility.push({
+                name: "Model usage under sessionLimitPercentage",
+                status: "fail",
+                detail: "agent-any but no model has available capacity",
+                failureSummary: "agent-any has no model with available capacity",
+            });
+            return false;
+        }
+        model = picked;
+        resolvedFromAny = `; agent-any resolved to model "${picked}"`;
+    }
+    const exhaustedUsage = usageExhaustion.find((exhaustion) => exhaustion.model === model);
+    eligibility.push(exhaustedUsage === undefined
+        ? modelUsageOkCheck({ config, model, usage, resolvedFromAny })
+        : usageExhaustionCheck(exhaustedUsage));
+    const inProgress = await dependencies.countInProgress();
+    const cap = config.orchestrator.maximumInProgress;
+    const capOk = inProgress < cap;
+    const capCheck = {
+        name: "In-progress cap not hit",
+        status: capOk ? "ok" : "fail",
+        detail: `${inProgress}/${cap} used`,
+    };
+    if (!capOk) {
+        capCheck.failureSummary = `in-progress cap is full (${inProgress}/${cap} used)`;
+    }
+    eligibility.push(capCheck);
+    return eligibility.every((check) => check.status === "ok");
+}
+function modelUsageOkCheck(arguments_) {
+    const { config, model, usage, resolvedFromAny } = arguments_;
+    const sessionPercent = ((usage[model]?.session ?? 0) * 100).toFixed(0);
+    return {
+        name: `Model "${model}" usage under sessionLimitPercentage`,
+        status: "ok",
+        detail: `${sessionPercent}% (limit ${config.orchestrator.sessionLimitPercentage}%)${resolvedFromAny}`,
+    };
+}
+function usageExhaustionCheck(exhaustion) {
+    if (exhaustion.kind === "session") {
+        return {
+            name: `Model "${exhaustion.model}" usage under sessionLimitPercentage`,
+            status: "fail",
+            detail: `${exhaustion.usedPercentage.toFixed(0)}% (limit ${exhaustion.limitPercentage}%)`,
+            failureSummary: `${exhaustion.model} session usage ${exhaustion.usedPercentage.toFixed(0)}% over ${exhaustion.limitPercentage}% limit`,
+        };
+    }
+    return {
+        name: `Model "${exhaustion.model}" weekly usage within paced budget`,
+        status: "fail",
+        detail: `${exhaustion.usedPercentage.toFixed(1)}% (paced budget ${exhaustion.allowedPercentage.toFixed(1)}%, resets in ${exhaustion.resetMinutes}m)`,
+        failureSummary: `${exhaustion.model} weekly usage ${exhaustion.usedPercentage.toFixed(1)}% over ${exhaustion.allowedPercentage.toFixed(1)}% paced budget`,
+    };
+}
+const STATUS_TAG = {
+    ok: "[ok]",
+    fail: "[--]",
+    skipped: "[? ]",
+};
+function formatCheck(check) {
+    const tag = STATUS_TAG[check.status];
+    const detail = check.detail === undefined ? "" : ` (${check.detail})`;
+    return `  ${tag} ${check.name}${detail}`;
+}
+function formatVerdict(verdict) {
+    switch (verdict.kind) {
+        case "would-dispatch": {
+            return "→ would be dispatched on next tick";
+        }
+        case "unresolvable": {
+            return `→ unresolvable: ${verdict.reason}`;
+        }
+        case "ineligible": {
+            return `→ ineligible: ${verdict.reason}`;
+        }
+        /* v8 ignore next 3 @preserve -- exhaustive over TicketDoctorVerdict.kind */
+        default: {
+            return `→ ${verdict.kind}`;
+        }
+    }
+}
+function eligibilityLines(result) {
+    if (result.eligibility.length === 0) {
+        const skipMessage = result.verdict.kind === "unresolvable"
+            ? "  (skipped — ticket unresolved)"
+            : "  (skipped — resolution checks failed)";
+        return [skipMessage];
+    }
+    return result.eligibility.map(formatCheck);
+}
+export function renderTicketDoctorResult(result) {
+    const titlePart = result.title === undefined ? "" : ` (${result.title})`;
+    const header = `groundcrew doctor --ticket ${result.ticket}${titlePart}`;
+    const bar = "─".repeat(header.length);
+    const verdictLine = formatVerdict(result.verdict);
+    return [
+        header,
+        bar,
+        "",
+        "Resolution",
+        ...result.resolution.map(formatCheck),
+        "",
+        "Eligibility",
+        ...eligibilityLines(result),
+        "",
+        verdictLine,
+    ];
+}
+export async function ticketDoctor(dependencies) {
+    const ticket = dependencies.ticket.toUpperCase();
+    const resolution = [];
+    const eligibility = [];
+    let raw;
+    try {
+        raw = await dependencies.fetchRawIssue({ ticket });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        resolution.push({ name: "Ticket exists in Linear", status: "fail", detail: message });
+        return {
+            ticket,
+            resolution,
+            eligibility,
+            verdict: { kind: "unresolvable", reason: message },
+        };
+    }
+    const { config } = dependencies;
+    resolution.push({ name: "Ticket exists in Linear", status: "ok", detail: `"${raw.title}"` });
+    // Status check
+    const todoState = config.linear.statuses.todo;
+    if (raw.stateName === todoState) {
+        resolution.push({ name: "Status is Todo", status: "ok" });
+    }
+    else {
+        resolution.push({
+            name: "Status is Todo",
+            status: "fail",
+            detail: `current: ${raw.stateName}`,
+            failureSummary: `status is ${raw.stateName} (need ${todoState})`,
+        });
+    }
+    // Label + model checks
+    const { resolvedModel, checks: modelChecks } = buildModelChecks(raw, config);
+    resolution.push(...modelChecks);
+    // Repo checks
+    const { resolvedRepository, checks: repoChecks } = buildRepoChecks(raw, config, ticket);
+    resolution.push(...repoChecks);
+    const firstResolutionFail = resolution.find((check) => check.status === "fail");
+    if (firstResolutionFail !== undefined) {
+        // failureSummary is always set for all resolution fail paths; .name fallback is defensive.
+        /* v8 ignore next @preserve */
+        const resolutionReason = firstResolutionFail.failureSummary ?? firstResolutionFail.name;
+        return {
+            ticket,
+            title: raw.title,
+            resolution,
+            eligibility,
+            verdict: { kind: "ineligible", reason: resolutionReason },
+        };
+    }
+    // All resolution checks passed (or were skipped). Run eligibility checks.
+    const allEligibilityOk = await runEligibilityChecks({
+        ticket,
+        raw,
+        config,
+        resolvedRepository,
+        resolvedModel,
+        dependencies,
+        eligibility,
+    });
+    if (!allEligibilityOk) {
+        const firstEligibilityFail = eligibility.find((check) => check.status === "fail");
+        // firstEligibilityFail is always defined when allEligibilityOk is false; fallback is defensive.
+        /* v8 ignore next @preserve */
+        const reason = firstEligibilityFail?.failureSummary ??
+            firstEligibilityFail?.name ??
+            "eligibility check failed";
+        return {
+            ticket,
+            title: raw.title,
+            resolution,
+            eligibility,
+            verdict: { kind: "ineligible", reason },
+        };
+    }
+    return {
+        ticket,
+        title: raw.title,
+        resolution,
+        eligibility,
+        verdict: { kind: "would-dispatch" },
+    };
+}
+export async function ticketDoctorCli(argv) {
+    const [ticket, ...extraArgs] = argv;
+    if (ticket === undefined || ticket.length === 0 || ticket.startsWith("-")) {
+        throw new Error("Usage: crew doctor --ticket <ticket>");
+    }
+    /* v8 ignore else @preserve */
+    if (extraArgs.length > 0) {
+        throw new Error(`crew doctor --ticket: unexpected arguments: ${extraArgs.join(" ")}`);
+    }
+    /* v8 ignore start @preserve */
+    const ok = await runTicketDoctor(ticket);
+    if (!ok) {
+        process.exitCode = 1;
+    }
+    /* v8 ignore stop @preserve */
+}
+export async function runTicketDoctor(ticket) {
+    const config = await loadConfig();
+    let client;
+    const linearClient = () => {
+        client ??= getLinearClient();
+        return client;
+    };
+    const result = await ticketDoctor({
+        config,
+        ticket,
+        fetchRawIssue: async ({ ticket: t }) => await fetchRawLinearIssue({ client: linearClient(), ticket: t }),
+        fetchBlockersFor: async ({ ticket: t, uuid }) => await fetchBlockersForTicket({ client: linearClient(), ticket: t, uuid }),
+        fetchUsage: async () => await getUsageByModel(config),
+        countInProgress: async () => await fetchInProgressIssueCount({ client: linearClient(), config }),
+    });
+    for (const line of renderTicketDoctorResult(result)) {
+        writeOutput(line);
+    }
+    return result.verdict.kind === "would-dispatch";
+}

package/dist/index.d.ts

@@ -5,5 +5,7 @@ export { orchestrate, type OrchestratorOptions } from "./commands/orchestrator.t
 export { setupWorkspace, type SetupWorkspaceOptions } from "./commands/setupWorkspace.ts";
 export type { Config, ModelDefinition, ResolvedConfig } from "./lib/config.ts";
 export { loadConfig } from "./lib/config.ts";
+export { fetchBlockersForTicket, fetchInProgressIssueCount, fetchRawLinearIssue, fetchResolvedIssue, resolveModelFor, resolveRepositoryFor, type ModelResolution, type RawLinearIssue, type RepositoryResolution, } from "./lib/boardSource.ts";
 export { getUsageByModel, type UsageByModel } from "./lib/usage.ts";
+export { ticketDoctor, type TicketCheck, type TicketDoctorDependencies, type TicketDoctorResult, type TicketDoctorVerdict, } from "./commands/ticketDoctor.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -4,4 +4,6 @@ export { doctor } from "./commands/doctor.js";
 export { orchestrate } from "./commands/orchestrator.js";
 export { setupWorkspace } from "./commands/setupWorkspace.js";
 export { loadConfig } from "./lib/config.js";
+export { fetchBlockersForTicket, fetchInProgressIssueCount, fetchRawLinearIssue, fetchResolvedIssue, resolveModelFor, resolveRepositoryFor, } from "./lib/boardSource.js";
 export { getUsageByModel } from "./lib/usage.js";
+export { ticketDoctor, } from "./commands/ticketDoctor.js";

package/dist/lib/boardSource.d.ts

@@ -69,6 +69,61 @@ interface ResolvedIssue {
     model: string;
     teamId: string;
 }
+export interface RawLinearIssue {
+    uuid: string;
+    title: string;
+    description: string;
+    teamId: string;
+    labels: {
+        name: string;
+    }[];
+    /** Linear workflow state name, e.g. "Todo", "In Review". May be "" if state was null. */
+    stateName: string;
+    blockers: Blocker[];
+    hasMoreBlockers: boolean;
+}
+export declare function fetchBlockersForTicket(arguments_: {
+    client: LinearClient;
+    ticket: string;
+    uuid: string;
+}): Promise<readonly Blocker[]>;
+export declare function fetchRawLinearIssue(arguments_: {
+    client: LinearClient;
+    ticket: string;
+}): Promise<RawLinearIssue>;
+export declare function fetchInProgressIssueCount(arguments_: {
+    client: LinearClient;
+    config: ResolvedConfig;
+}): Promise<number>;
+export type RepositoryResolution = {
+    kind: "ok";
+    repository: string;
+} | {
+    kind: "missing";
+};
+export declare function resolveRepositoryFor(arguments_: {
+    description: string | undefined;
+    config: ResolvedConfig;
+    ticket: string;
+}): RepositoryResolution;
+export type ModelResolution = {
+    kind: "matched";
+    model: string;
+} | {
+    kind: "no-label";
+} | {
+    kind: "agent-any";
+} | {
+    kind: "disabled-fallback";
+    requestedModel: string;
+    fallbackModel: string;
+};
+export declare function resolveModelFor(arguments_: {
+    labels: {
+        name: string;
+    }[];
+    config: ResolvedConfig;
+}): ModelResolution;
 /**
  * `agent-any` collapses to `models.default` here — manual setup doesn't run
  * the usage-gated `any` resolver, so the caller gets a concrete model name

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

@@ -1 +1 @@
-{"version":3,"file":"boardSource.d.ts","sourceRoot":"","sources":["../../src/lib/boardSource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAM7F,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,0FAA0F;IAC1F,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,IAAI,eAAe,CAExE;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,YAAmB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAMjF;CACF;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8DAA8D;IAC9D,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9B;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAUpE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAEhF;AAmMD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE;IACnD,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmDzB"}
+{"version":3,"file":"boardSource.d.ts","sourceRoot":"","sources":["../../src/lib/boardSource.ts"],"names":[],"mappings":"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"}

package/dist/lib/boardSource.js

@@ -129,9 +129,9 @@ async function fetchBoard(client, config) {
     const issues = nodes
         .filter((node) => node.children.nodes.length === 0)
         .map((node) => {
-        const parsedAgentLabels = parseAgentLabels(node.labels.nodes, config);
-        warnIfDisabledFallback(node.identifier, parsedAgentLabels, config);
-        const repository = parsedAgentLabels === undefined
+        const modelResolution = resolveModelFor({ labels: node.labels.nodes, config });
+        warnIfDisabledFallback(node.identifier, modelResolution, config);
+        const repository = modelResolution.kind === "no-label"
             ? undefined
             : parseRepository({
                 description: node.description ?? undefined,
@@ -139,6 +139,16 @@ async function fetchBoard(client, config) {
                 repositoryRegex,
                 ticket: node.identifier,
             });
+        let model;
+        if (modelResolution.kind === "matched") {
+            ({ model } = modelResolution);
+        }
+        else if (modelResolution.kind === "disabled-fallback") {
+            model = modelResolution.fallbackModel;
+        }
+        else if (modelResolution.kind === "agent-any") {
+            model = AGENT_ANY_MODEL;
+        }
         return {
             id: node.identifier.toLowerCase(),
             uuid: node.id,
@@ -148,7 +158,7 @@ async function fetchBoard(client, config) {
             assignee: node.assignee?.name ?? "Unassigned",
             updatedAt: node.updatedAt,
             repository,
-            model: parsedAgentLabels?.model,
+            model,
             teamId: node.team?.id ?? "",
             blockers: blockersFromRelations(node.inverseRelations?.nodes ?? []),
             hasMoreBlockers: node.inverseRelations?.pageInfo.hasNextPage ?? false,
@@ -174,22 +184,64 @@ function buildRepositoryRegex(config) {
     return new RegExp(String.raw `\b(${alternation})\b`);
 }
 const ISSUE_LABEL_PAGE_SIZE = 50;
-/**
- * `agent-any` collapses to `models.default` here — manual setup doesn't run
- * the usage-gated `any` resolver, so the caller gets a concrete model name
- * instead of a sentinel that downstream code can't interpret.
- */
-export async function fetchResolvedIssue(arguments_) {
-    const { client, config, ticket } = arguments_;
+const ISSUE_RELATION_PAGE_SIZE = 50;
+export async function fetchBlockersForTicket(arguments_) {
+    const { client, uuid } = arguments_;
+    const relations = [];
+    let after = null;
+    for (;;) {
+        // oxlint-disable-next-line no-await-in-loop -- pagination cursor depends on the previous response
+        const response = await client.client.rawRequest(`query IssueBlockers($id: String!, $after: String) {
+        issue(id: $id) {
+          inverseRelations(first: ${ISSUE_RELATION_PAGE_SIZE}, after: $after, includeArchived: false) {
+            nodes {
+              type
+              issue {
+                identifier
+                title
+                state { name }
+              }
+            }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      }`, { id: uuid, after });
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- shape is fixed by our GraphQL query above
+        const { issue } = response.data;
+        if (issue === null) {
+            return [];
+        }
+        relations.push(...issue.inverseRelations.nodes);
+        if (!issue.inverseRelations.pageInfo.hasNextPage) {
+            break;
+        }
+        after = issue.inverseRelations.pageInfo.endCursor;
+    }
+    return blockersFromRelations(relations);
+}
+export async function fetchRawLinearIssue(arguments_) {
+    const { client, ticket } = arguments_;
     const response = await client.client.rawRequest(`query ResolveIssue($id: String!) {
       issue(id: $id) {
         id
         title
         description
         team { id }
+        state { name }
         labels(first: ${ISSUE_LABEL_PAGE_SIZE}) {
           nodes { name }
         }
+        inverseRelations(first: 50, includeArchived: false) {
+          nodes {
+            type
+            issue {
+              identifier
+              title
+              state { name }
+            }
+          }
+          pageInfo { hasNextPage }
+        }
       }
     }`, { id: ticket.toUpperCase() });
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- shape is fixed by our GraphQL query above
@@ -197,26 +249,119 @@ export async function fetchResolvedIssue(arguments_) {
     if (issue === null) {
         throw new Error(`Ticket ${ticket.toUpperCase()} not found in Linear`);
     }
-    const description = issue.description ?? "";
-    const repository = parseRepository({
-        description,
+    return {
+        uuid: issue.id,
+        title: issue.title,
+        description: issue.description ?? "",
+        teamId: issue.team?.id ?? "",
+        labels: issue.labels.nodes,
+        stateName: issue.state?.name ?? "",
+        blockers: blockersFromRelations(issue.inverseRelations?.nodes ?? []),
+        hasMoreBlockers: issue.inverseRelations?.pageInfo.hasNextPage ?? false,
+    };
+}
+export async function fetchInProgressIssueCount(arguments_) {
+    const { client, config } = arguments_;
+    let after = null;
+    let count = 0;
+    for (;;) {
+        // oxlint-disable-next-line no-await-in-loop -- pagination cursor depends on the previous response
+        const response = await client.client.rawRequest(`query InProgressIssues($slugId: String!, $stateName: String!, $agentLabelPrefix: String!, $after: String) {
+        issues(
+          filter: {
+            project: { slugId: { eq: $slugId } }
+            state: { name: { eq: $stateName } }
+            labels: { some: { name: { startsWith: $agentLabelPrefix } } }
+          }
+          first: ${ISSUES_PAGE_SIZE}
+          after: $after
+          includeArchived: false
+        ) {
+          nodes { id }
+          pageInfo { hasNextPage endCursor }
+        }
+      }`, {
+            slugId: config.linear.slugId,
+            stateName: config.linear.statuses.inProgress,
+            agentLabelPrefix: AGENT_LABEL_PREFIX,
+            after,
+        });
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- shape is fixed by our GraphQL query above
+        const { issues: page } = response.data;
+        count += page.nodes.length;
+        if (!page.pageInfo.hasNextPage) {
+            return count;
+        }
+        after = page.pageInfo.endCursor;
+    }
+}
+export function resolveRepositoryFor(arguments_) {
+    const { description, config } = arguments_;
+    if (description === undefined || description.length === 0) {
+        return { kind: "missing" };
+    }
+    const repository = buildRepositoryRegex(config).exec(description)?.[1];
+    if (repository === undefined) {
+        return { kind: "missing" };
+    }
+    return { kind: "ok", repository };
+}
+export function resolveModelFor(arguments_) {
+    const { labels, config } = arguments_;
+    const parsed = parseAgentLabels(labels, config);
+    if (parsed === undefined) {
+        return { kind: "no-label" };
+    }
+    if (parsed.model === AGENT_ANY_MODEL) {
+        return { kind: "agent-any" };
+    }
+    if (parsed.disabledFallback !== undefined) {
+        return {
+            kind: "disabled-fallback",
+            requestedModel: parsed.disabledFallback,
+            fallbackModel: parsed.model,
+        };
+    }
+    return { kind: "matched", model: parsed.model };
+}
+/**
+ * `agent-any` collapses to `models.default` here — manual setup doesn't run
+ * the usage-gated `any` resolver, so the caller gets a concrete model name
+ * instead of a sentinel that downstream code can't interpret.
+ */
+export async function fetchResolvedIssue(arguments_) {
+    const { client, config, ticket } = arguments_;
+    const raw = await fetchRawLinearIssue({ client, ticket });
+    const repositoryResolution = resolveRepositoryFor({
+        description: raw.description,
         config,
-        repositoryRegex: buildRepositoryRegex(config),
         ticket: ticket.toUpperCase(),
     });
+    if (repositoryResolution.kind === "missing") {
+        throw new RepositoryResolutionError({
+            ticket: ticket.toUpperCase(),
+            repositories: config.workspace.knownRepositories,
+        });
+    }
     // Manual setup is an explicit per-ticket opt-in by the user, so an
     // unlabeled ticket still resolves to `models.default` — different from
     // the auto-pickup path, where unlabeled tickets are ignored.
-    const parsed = parseAgentLabels(issue.labels.nodes, config);
-    warnIfDisabledFallback(ticket, parsed, config);
-    const model = parsed === undefined || parsed.model === AGENT_ANY_MODEL ? config.models.default : parsed.model;
+    const modelResolution = resolveModelFor({ labels: raw.labels, config });
+    warnIfDisabledFallback(ticket, modelResolution, config);
+    let model = config.models.default;
+    if (modelResolution.kind === "matched") {
+        ({ model } = modelResolution);
+    }
+    else if (modelResolution.kind === "disabled-fallback") {
+        model = modelResolution.fallbackModel;
+    }
     return {
-        uuid: issue.id,
-        title: issue.title,
-        description,
-        repository,
+        uuid: raw.uuid,
+        title: raw.title,
+        description: raw.description,
+        repository: repositoryResolution.repository,
         model,
-        teamId: issue.team?.id ?? "",
+        teamId: raw.teamId,
     };
 }
 function parseRepository(arguments_) {
@@ -278,11 +423,11 @@ function parseAgentLabels(labels, config) {
     }
     return fallback;
 }
-function warnIfDisabledFallback(ticket, parsed, config) {
-    if (parsed?.disabledFallback === undefined) {
+function warnIfDisabledFallback(ticket, modelResolution, config) {
+    if (modelResolution.kind !== "disabled-fallback") {
         return;
     }
-    log(`${ticket.toLowerCase()}: agent-${parsed.disabledFallback} label refers to a disabled model; falling back to models.default (${config.models.default})`);
+    log(`${ticket.toLowerCase()}: agent-${modelResolution.requestedModel} label refers to a disabled model; falling back to models.default (${config.models.default})`);
 }
 function blockersFromRelations(relations) {
     return relations

package/package.json

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