@clipboard-health/groundcrew 2.3.6 → 3.0.1

package/README.md

@@ -105,6 +105,25 @@ Installs the `crew` binary. `@clipboard-health/clearance` is pulled in transitiv
    crew run --watch               # poll forever
    ```
 
+## Secrets
+
+Groundcrew forwards a small allowlist of build-time secrets from your shell into the setup phase (so `npm install` can authenticate against private registries) and then strips them before the agent runs. The agent process never inherits these values in its environment.
+
+**Recognized names.** Defined in [`BUILD_SECRET_NAMES`](./src/lib/buildSecrets.ts):
+
+- `NPM_TOKEN`
+- `BUF_TOKEN`
+
+Set them in the shell you run `crew` from. Anything not in this list is ignored by the secret-shuttling path.
+
+**Flow.** For each ticket:
+
+1. If any recognized var is set and non-empty, groundcrew writes `secrets.env` (mode `0600`) into the ticket's temp prompt dir as `KEY='value'` lines — see `stageBuildSecrets` in [`src/commands/setupWorkspace.ts`](./src/commands/setupWorkspace.ts).
+2. The launch script sources `secrets.env` with `set -a` so the values are exported into the setup phase only (and under `sdx`, forwarded into the sandbox via `-e KEY` flags).
+3. After setup completes, the script `unset`s every name in `BUILD_SECRET_NAMES` and then `rm -rf`s the entire prompt dir (including `secrets.env`) before `exec`'ing the agent. See `sourceSecretsLine` / `unsetSecretsLine` and the `rm -rf` / `exec` lines in [`src/lib/launchCommand.ts`](./src/lib/launchCommand.ts). The rollback path on setup failure ([`src/commands/setupWorkspace.ts`](./src/commands/setupWorkspace.ts)) wipes the prompt dir too.
+
+Net effect: by the time the agent process exists, the values are gone from the environment and the file is gone from disk.
+
 ## Runners
 
 `local.runner` picks the local isolation backend. `auto` resolves per platform.
@@ -216,42 +235,129 @@ Rules:
 
 </details>
 
+## Per-repo setup hook
+
+When groundcrew launches a worktree, if `.groundcrew/setup.sh` exists in the repo root it's invoked as `bash .groundcrew/setup.sh --deps-only` before the agent starts; otherwise nothing runs. The same convention applies inside the sdx sandbox (overridable per-model via `models.definitions.<name>.sandbox.setupCommand`). No implicit `npm install`, `uv sync`, or anything else — groundcrew is language-agnostic, so opt in by adding the script.
+
+### The `--deps-only` contract
+
+The flag tells the script "you're being called by an automated system before an agent launches — skip anything interactive or one-time-only." The same script handles both modes; branch on `$1`. The name is historical and Node-flavored, but the semantic is language-neutral:
+
+- **With `--deps-only`**: do the cheap recurring work this worktree needs (lockfile install, generate types, etc.). No prompts, no global installs, no `nvm` / `pyenv` bootstrap that the host should already have.
+- **Without the flag**: full interactive bootstrap. Use this path when an engineer runs the script by hand for first-time onboarding, or when wiring it into another tool's SessionStart hook.
+
+Setup failures are advisory — groundcrew logs the non-zero exit and still launches the agent so a flaky network or stale lockfile doesn't block the session.
+
+### Examples
+
+**Python (uv):**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+if [ "${1:-}" = "--deps-only" ]; then
+  uv sync --dev
+else
+  uv sync --dev
+  # ... extra one-time bootstrap (e.g., pre-commit install, db seed) ...
+fi
+```
+
+**Node (npm):**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+if [ "${1:-}" = "--deps-only" ]; then
+  npm clean-install
+else
+  npm clean-install
+  # ... extra one-time bootstrap (e.g., husky install, codegen, link local packages) ...
+fi
+```
+
+**Docs-only or polyglot repo with no install step:**
+
+Omit the script. With nothing at `.groundcrew/setup.sh`, groundcrew skips the hook silently — fine for documentation repos, polyglot monorepos where setup happens per-package, or anywhere the per-worktree work is genuinely zero.
+
+For a more comprehensive real-world example (nvm bootstrap, hash-based skip-on-no-changes caching, portable SHA-256 detection), see [this repo's own `.groundcrew/setup.sh`](./.groundcrew/setup.sh). It's also symlinked at `.claude/setup.sh` so the same script doubles as a Claude Code SessionStart hook for this repo — that symlink is local convenience, not part of groundcrew's contract.
+
+### Generating it with an agent
+
+To have a coding agent (Claude Code, Cursor, etc.) scaffold `.groundcrew/setup.sh` for a repo you're onboarding, see [docs/setup-hook-agent-prompt.md](./docs/setup-hook-agent-prompt.md) — it encodes the contract above as a copy-pasteable prompt.
+
 ## Commands
 
 ```bash
-crew doctor                        # full setup check
-crew doctor --ticket <TICKET>      # diagnose one ticket
-crew run                           # one-shot dispatch
-crew run --watch                   # poll forever
-crew run --ticket <TICKET>         # provision one ticket and exit
+crew doctor                                              # full setup check
+crew doctor --ticket <TICKET> [--no-linear] [--no-fetch] # full ticket lifecycle (dispatch + recovery)
+crew run                                                 # one-shot dispatch
+crew run --watch                                         # poll forever
+crew run --ticket <TICKET>                               # provision one ticket and exit
 crew setup repos [--dry-run] [<repo>...]
-crew cleanup <TICKET>              # tear down every worktree carrying this ticket
+crew cleanup <TICKET>                                    # tear down every worktree carrying this ticket
 ```
 
-`--watch` and `--ticket` are mutually exclusive. To inspect codexbar session windows directly, run `codexbar usage`.
+`crew doctor --ticket <TICKET>` covers the full per-ticket lifecycle: pre-dispatch eligibility (Todo status, `agent-*` label, model resolution, repository mention, local clone, blockers, model session usage, in-progress capacity) **and** post-dispatch local-state recovery (host worktree, workspace pane, local branch, remote branch, open PR). Verdict precedence runs from post-dispatch outcomes down: `pr-open` > `pr-merged` > `in-flight` > `recoverable` > `unresolvable` > `ineligible` > `would-dispatch` > `lost`. Exits 0 on `would-dispatch`, `pr-open`, or `pr-merged`; any other verdict exits 1. `--watch` and `--ticket` are mutually exclusive. To inspect codexbar session windows directly, run `codexbar usage`.
 
 ### `crew doctor --ticket <ticket>`
 
-Diagnose why a ticket would or wouldn't be dispatched on the next tick. Runs the same resolution and eligibility chain as the dispatcher. Exits 0 if the ticket would dispatch, 1 otherwise. The hero above shows a passing run; here's a failing one:
+Diagnose where a ticket is in its lifecycle and what to do next. Runs the same resolution and eligibility chain as the dispatcher, plus probes the host worktree, workspace pane, local branch, remote branch, and PR; prints a single verdict with a copy-pasteable recovery step when one applies.
+
+Flags:
+
+- `--no-linear` — skip the Linear GraphQL call. Resolution and Eligibility sections are skipped; verdicts that need only local state (`in-flight`, `recoverable`, `pr-open`, `pr-merged`, `lost`) still fire.
+- `--no-fetch` — skip the upfront `git fetch origin <branch>` before checking remote presence.
+
+The Workspace section appends an attach hint to the pane name when the workspace backend exposes one (e.g. `tmux attach -t <session>:<pane>` or `cmux attach <name>`), so the verdict line is immediately actionable. The hero above shows a passing pre-dispatch run; here's the same command on a ticket that's already past dispatch:
 
 ```text
-groundcrew doctor --ticket HRD-447 (Refactor auth middleware)
-─────────────────────────────────────────────────────────────
+groundcrew doctor --ticket HRD-442 (Multi-event extractor: year inference can produce date_start > date_end)
+────────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 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)
+  [ok] Ticket exists in Linear ("Multi-event extractor: year inference can produce date_start > date_end")
+  [ok] Status is Todo
+  (skipped — post-dispatch — pre-dispatch checks are irrelevant)
 
 Eligibility
-  (skipped — resolution checks failed)
+  (skipped — post-dispatch — pre-dispatch checks are irrelevant)
+
+Worktree
+  [ok] Host worktree exists (/Users/paul/dev/groundcrew-workspaces/herds-social/herds-hrd-442)
+  [--] Working tree clean (0 modified, 1 untracked)
+  [ok] Branch checked out (paul-hrd-442)
+
+Workspace
+  [ok] Workspace pane open (hrd-442 — attach: `tmux attach -t groundcrew:hrd-442`)
+
+Local branch
+  [ok] Local branch exists (paul-hrd-442, 2 ahead / 0 behind origin/main)
 
-→ ineligible: status is In Progress (need Todo)
+Remote branch
+  [ok] Branch present on origin
+
+Pull request
+  [ok] Open PR for this branch (#224 https://github.com/herds-social/herds/pull/224)
+
+→ pr-open: https://github.com/herds-social/herds/pull/224 (#224)
 ```
 
+#### Recovering a stranded ticket
+
+The verdict on the last line maps to a recovery action:
+
+| Verdict          | What to do                                                                                    |
+| ---------------- | --------------------------------------------------------------------------------------------- |
+| `pr-open`        | Nothing — the PR is the source of truth.                                                      |
+| `pr-merged`      | Done.                                                                                         |
+| `in-flight`      | The ticket is still being worked on; the verdict line names the workspace pane to attach to.  |
+| `recoverable`    | Run the printed `nextStep` exactly.                                                           |
+| `would-dispatch` | Pre-dispatch checks pass; the orchestrator will pick the ticket up on its next tick.          |
+| `ineligible`     | A resolution or eligibility check failed; the reason after the colon names the failing check. |
+| `unresolvable`   | The Linear ticket couldn't be fetched; the reason after the colon names the error.            |
+| `lost`           | No trace exists. Re-dispatch via `crew run --ticket <ticket>`.                                |
+
 ## Troubleshooting
 
 First stop for "labeled but not on the board": `crew doctor --ticket <ticket>` lists every check the dispatcher runs and flags the failing one.

package/clearance-allow-hosts

@@ -55,6 +55,7 @@ productionresultssa17.blob.core.windows.net
 productionresultssa18.blob.core.windows.net
 productionresultssa19.blob.core.windows.net
 raw.githubusercontent.com
+release-assets.githubusercontent.com
 results-receiver.actions.githubusercontent.com
 
 # npm registry

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiJA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}

package/dist/cli.js

@@ -4,7 +4,7 @@ import { doctor } from "./commands/doctor.js";
 import { orchestrate } from "./commands/orchestrator.js";
 import { setupReposCli } from "./commands/setupRepos.js";
 import { setupWorkspaceCli } from "./commands/setupWorkspace.js";
-import { errorMessage, writeError, writeOutput } from "./lib/util.js";
+import { errorMessage, readTicketArgument, writeError, writeOutput } from "./lib/util.js";
 const requireFromCli = createRequire(import.meta.url);
 function setupUsage() {
     return "Usage: crew setup repos [--dry-run] [<repo>...]";
@@ -32,11 +32,7 @@ async function runCli(argv) {
             continue;
         }
         if (argument === "--ticket") {
-            const value = argv[index + 1];
-            if (value === undefined || value.length === 0 || value.startsWith("-")) {
-                throw new Error("crew run --ticket: ticket id is required");
-            }
-            ticket = value;
+            ticket = readTicketArgument(argv, index, "run");
             index += 1;
             continue;
         }
@@ -53,20 +49,29 @@ async function runCli(argv) {
 }
 async function doctorCli(argv) {
     let ticket;
+    const remainingArgs = [];
     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;
+            ticket = readTicketArgument(argv, index, "doctor");
             index += 1;
             continue;
         }
+        if (argument === "--no-linear" || argument === "--no-fetch") {
+            remainingArgs.push(argument);
+            continue;
+        }
         throw new Error(`crew doctor: unknown argument: ${argument}`);
     }
-    const ok = ticket === undefined ? await doctor() : await doctor({ ticket });
+    if (ticket === undefined) {
+        if (remainingArgs.length > 0) {
+            throw new Error(`crew doctor: ${remainingArgs[0]} requires --ticket (host doctor mode has no flags)`);
+        }
+        const ok = await doctor();
+        process.exitCode = ok ? process.exitCode : 1;
+        return;
+    }
+    const ok = await doctor({ ticket, ticketArgv: remainingArgs });
     process.exitCode = ok ? process.exitCode : 1;
 }
 const SUBCOMMANDS = {
@@ -76,8 +81,8 @@ const SUBCOMMANDS = {
         invoke: runCli,
     },
     doctor: {
-        summary: "Verify prereqs, or diagnose one ticket with --ticket",
-        usage: "[--ticket <ticket>]",
+        summary: "Verify prereqs, or diagnose one ticket with --ticket (full lifecycle: dispatch eligibility + local-state recovery)",
+        usage: "[--ticket <ticket> [--no-linear] [--no-fetch]]",
         invoke: doctorCli,
     },
     cleanup: {

package/dist/commands/doctor.d.ts

@@ -4,6 +4,8 @@
  */
 export interface DoctorOptions {
     ticket?: string;
+    /** Extra flags after `--ticket <id>`; currently `--no-linear` and `--no-fetch`. */
+    ticketArgv?: 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;AA2BH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsHD,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAK1E"}
+{"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;IAChB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAsHD,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAK1E"}

package/dist/commands/doctor.js

@@ -8,7 +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";
+import { parseTicketDoctorFlags, 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;
@@ -124,13 +124,18 @@ function format(check) {
 }
 export async function doctor(options = {}) {
     if (options.ticket !== undefined) {
-        return await doctorTicket(options.ticket);
+        return await doctorTicket(options.ticket, options.ticketArgv ?? []);
     }
     return await doctorHost();
 }
-async function doctorTicket(ticket) {
+async function doctorTicket(ticket, ticketArgv) {
     try {
-        return await runTicketDoctor(ticket);
+        const flags = parseTicketDoctorFlags(ticketArgv);
+        return await runTicketDoctor({
+            ticket,
+            doLinear: flags.doLinear,
+            doFetch: flags.doFetch,
+        });
     }
     catch (error) {
         const displayTicket = ticket.toUpperCase();

package/dist/commands/ticketCheck.d.ts

@@ -0,0 +1,22 @@
+export interface TicketCheck {
+    name: string;
+    status: "ok" | "fail" | "skipped";
+    detail?: string;
+    failureSummary?: string;
+}
+export interface Section {
+    name: string;
+    checks: TicketCheck[];
+    /** When present and `checks` is empty, the section renders as `(skipped — <skipReason>)`. */
+    skipReason?: string;
+}
+interface RenderInput {
+    command: string;
+    argument: string;
+    title?: string;
+    sections: Section[];
+    verdict: string;
+}
+export declare function renderTicketCheckResult(input: RenderInput): string[];
+export {};
+//# sourceMappingURL=ticketCheck.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ticketCheck.d.ts","sourceRoot":"","sources":["../../src/commands/ticketCheck.ts"],"names":[],"mappings":"AAAA,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,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAqBD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CAMpE"}

package/dist/commands/ticketCheck.js

@@ -0,0 +1,23 @@
+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 sectionLines(section) {
+    if (section.checks.length === 0 && section.skipReason !== undefined) {
+        return [section.name, `  (skipped — ${section.skipReason})`];
+    }
+    return [section.name, ...section.checks.map(formatCheck)];
+}
+export function renderTicketCheckResult(input) {
+    const titlePart = input.title === undefined ? "" : ` (${input.title})`;
+    const header = `groundcrew ${input.command} ${input.argument}${titlePart}`;
+    const bar = "─".repeat(header.length);
+    const body = input.sections.flatMap((section) => ["", ...sectionLines(section)]);
+    return [header, bar, ...body, "", input.verdict];
+}

package/dist/commands/ticketDoctor.d.ts

@@ -1,7 +1,25 @@
 import { type Blocker, type RawLinearIssue } from "../lib/boardSource.ts";
 import { type ResolvedConfig } from "../lib/config.ts";
 import { type UsageByModel } from "../lib/usage.ts";
+import { type WorkspaceAccessHint, type WorkspaceProbe } from "../lib/workspaces.ts";
+import { type WorktreeDirtiness, type WorktreeEntry } from "../lib/worktrees.ts";
+import { type TicketCheck } from "./ticketCheck.ts";
 export type TicketDoctorVerdict = {
+    kind: "pr-open";
+    number: number;
+    url: string;
+} | {
+    kind: "pr-merged";
+    number: number;
+    url: string;
+} | {
+    kind: "in-flight";
+    reason: string;
+} | {
+    kind: "recoverable";
+    reason: string;
+    nextStep: string;
+} | {
     kind: "would-dispatch";
 } | {
     kind: "ineligible";
@@ -9,40 +27,170 @@ export type TicketDoctorVerdict = {
 } | {
     kind: "unresolvable";
     reason: string;
+} | {
+    kind: "lost";
+    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 type LinearStatusProbe = {
+    kind: "terminal";
+    stateName: string;
+} | {
+    kind: "non-terminal";
+    stateName: string;
+} | {
+    kind: "skipped";
+} | {
+    kind: "unresolvable";
+    reason: string;
+};
+export type WorktreeProbe = {
+    kind: "present-clean";
+} | {
+    kind: "present-dirty";
+    modified: number;
+    untracked: number;
+} | {
+    kind: "present-unknown-dirtiness";
+    reason: string;
+} | {
+    kind: "absent";
+};
+export type LocalBranchProbe = {
+    kind: "present";
+    ahead: number;
+    behind: number;
+    defaultBranch?: string;
+} | {
+    kind: "absent";
+} | {
+    kind: "unknown";
+    reason: string;
+};
+export type RemoteBranchProbe = {
+    kind: "present";
+} | {
+    kind: "absent";
+} | {
+    kind: "unknown";
+    reason: string;
+};
+export type PullRequestProbe = {
+    kind: "open";
+    number: number;
+    url: string;
+} | {
+    kind: "merged";
+    number: number;
+    url: string;
+} | {
+    kind: "absent";
+} | {
+    kind: "gh-missing";
+} | {
+    kind: "unknown";
+    reason: string;
+};
+export interface DecideVerdictInput {
+    linear: LinearStatusProbe;
+    worktree: WorktreeProbe;
+    localBranch: LocalBranchProbe;
+    remoteBranch: RemoteBranchProbe;
+    pullRequest: PullRequestProbe;
+    branch: string;
+    worktreeDir: string | undefined;
+    workspaceName: string | undefined;
 }
+/**
+ * Returns a post-dispatch verdict if the probe bundle matches one of the
+ * "ticket has moved past dispatch" cases. Returns `undefined` otherwise,
+ * signalling that the caller should fall through to the pre-dispatch path.
+ *
+ * Precedence: PR > in-flight > recoverable. Inside `recoverable`, dirty
+ * worktree beats clean-with-un-pushed-local beats remote-only beats stranded
+ * local.
+ */
+export declare function decidePostDispatchVerdict(input: DecideVerdictInput): TicketDoctorVerdict | undefined;
 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.
+     * Injected to keep `ticketDoctor` pure and easy to unit-test. `undefined`
+     * means the caller passed `--no-linear` — the Linear-backed pre-dispatch
+     * checks (status, label, repo, eligibility) are all skipped.
      */
-    fetchRawIssue: (input: {
+    fetchRawIssue: ((input: {
         ticket: string;
-    }) => Promise<RawLinearIssue>;
+    }) => Promise<RawLinearIssue>) | undefined;
     fetchBlockersFor: (input: {
         ticket: string;
         uuid: string;
     }) => Promise<readonly Blocker[]>;
     fetchUsage: () => Promise<UsageByModel>;
     countInProgress: () => Promise<number>;
+    findWorktree: (ticket: string) => WorktreeEntry | undefined;
+    probeWorkspaces: () => Promise<WorkspaceProbe>;
+    workspaceAccessHint: (name: string) => Promise<WorkspaceAccessHint | undefined>;
+    probeWorkingTree: (input: {
+        worktreeDir: string;
+    }) => Promise<WorktreeDirtiness>;
+    probeLocalBranch: (input: {
+        repoDir: string;
+        branch: string;
+        defaultBranch: string;
+    }) => Promise<LocalBranchProbe>;
+    probeRemoteBranch: (input: {
+        repoDir: string;
+        branch: string;
+        doFetch: boolean;
+    }) => Promise<RemoteBranchProbe>;
+    probePullRequest: (input: {
+        repoDir: string;
+        branch: string;
+    }) => Promise<PullRequestProbe>;
+    doFetch: boolean;
 }
-export declare function renderTicketDoctorResult(result: TicketDoctorResult): string[];
+export interface TicketDoctorResult {
+    ticket: string;
+    title?: string;
+    resolution: TicketCheck[];
+    eligibility: TicketCheck[];
+    worktree: TicketCheck[];
+    workspace: TicketCheck[];
+    localBranch: TicketCheck[];
+    remoteBranch: TicketCheck[];
+    pullRequest: TicketCheck[];
+    skipReasons: {
+        resolution: string;
+        eligibility: string;
+        worktree: string;
+        workspace: string;
+        localBranch: string;
+        remoteBranch: string;
+        pullRequest: string;
+    };
+    verdict: TicketDoctorVerdict;
+}
+/**
+ * Pure-with-async orchestrator that gathers all sections plus the verdict.
+ * All I/O happens via injected probes — the function itself does no
+ * filesystem, network, or stdout work.
+ */
 export declare function ticketDoctor(dependencies: TicketDoctorDependencies): Promise<TicketDoctorResult>;
-export declare function ticketDoctorCli(argv: string[]): Promise<void>;
-export declare function runTicketDoctor(ticket: string): Promise<boolean>;
+interface TicketDoctorArguments {
+    ticket: string;
+    doLinear: boolean;
+    doFetch: boolean;
+}
+/**
+ * Parses optional `--no-linear` and `--no-fetch` flags that follow
+ * `crew doctor --ticket <id>`. The ticket id is consumed by `cli.ts` before
+ * this point.
+ */
+export declare function parseTicketDoctorFlags(argv: string[]): {
+    doLinear: boolean;
+    doFetch: boolean;
+};
+export declare function renderTicketDoctorResult(result: TicketDoctorResult): string[];
+export declare function runTicketDoctor(parsed: TicketDoctorArguments): Promise<boolean>;
+export {};
 //# sourceMappingURL=ticketDoctor.d.ts.map

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

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