@clipboard-health/groundcrew 2.3.0 → 2.3.4

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/setupWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUvF,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAgBD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmED,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CAoGf;AA0FD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}
+{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUvF,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAgBD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmED,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CAuGf;AA0FD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/commands/setupWorkspace.js

@@ -122,7 +122,9 @@ export async function setupWorkspace(config, options, runOptions = {}) {
         const stagedPrompt = stagePrompt({ config, ticket, ticketDetails, worktreeName });
         promptDir = stagedPrompt.directory;
         const secretsFile = stageBuildSecrets(promptDir);
-        const sandboxName = runner === "sdx" ? sandboxNameFor({ repository, model }) : undefined;
+        const sandboxName = runner === "sdx" && definition.sandbox !== undefined
+            ? sandboxNameFor({ agent: definition.sandbox.agent })
+            : undefined;
         if (runner === "sdx" && sandboxName !== undefined && definition.sandbox !== undefined) {
             await ensureSandbox({
                 sandboxName,

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";