@bridge_gpt/mcp-server 0.1.13 → 0.1.16

package/build/start-tickets.js

@@ -0,0 +1,1210 @@
+/**
+ * start-tickets — packaged CLI subcommand of the bridge-api-mcp-server bin.
+ *
+ * Spawns one Worktrunk worktree + selected-agent session per Jira ticket key.
+ * The agent defaults to Claude Code (`claude`) and is configurable via `--agent`
+ * (see agent-registry.ts). This module ports the behaviour of the former repo-local
+ * `scripts/start-tickets.sh` into TypeScript that ships inside the
+ * `@bridge_gpt/mcp-server` npm package, fixing the distribution bug where
+ * external `--init` consumers received a `/start-tickets` slash command that
+ * shelled out to a script that does not exist in their checkout.
+ *
+ * ---------------------------------------------------------------------------
+ * Implemented worktree-creation model (BAPI-302)
+ * ---------------------------------------------------------------------------
+ * The CLI owns worktree creation; the terminal tabs only run the agent:
+ *
+ *   1. The CLI creates / switches Worktrunk worktrees up front via
+ *      `wt switch [--create] -y <branch> --format=json` (no `-x`; `-y`
+ *      auto-approves hooks since there is no TTY), parsing the JSON output to
+ *      capture each worktree path and per-ticket success. On Windows the
+ *      Worktrunk binary is `git-wt`, NOT `wt` (see platform routing below).
+ *   2. Worktree operations are throttled by `--max-parallel` (default 3) so the
+ *      expensive per-worktree `pre-start` hooks (uv venv / uv pip sync) do not
+ *      all run at once.
+ *   3. Only after a worktree is created does the CLI open one terminal tab per
+ *      successful worktree, running the per-platform agent shell command for the
+ *      selected agent (POSIX `cd '<path>' && <agent> '...'` or PowerShell
+ *      `Set-Location ...; <agent> '...'`; the agent defaults to `claude`).
+ *
+ * ---------------------------------------------------------------------------
+ * Cross-platform spawning (BAPI-303)
+ * ---------------------------------------------------------------------------
+ * Spawning is routed per platform behind the injected `spawnTerminalTab`
+ * boundary:
+ *
+ *   - macOS  (darwin): Terminal.app / iTerm via `osascript`.
+ *   - Windows (win32): Windows Terminal (`wt.exe new-tab`) with a
+ *     `Start-Process powershell.exe` fallback when Windows Terminal is absent.
+ *   - Linux  (linux): one detached `tmux` session per ticket (pane retained
+ *     via `; exec $SHELL`); attach with `tmux attach -t <session>`.
+ *
+ * Any other `process.platform` value fails fast with a clear "unsupported
+ * platform" message. `--dry-run` short-circuits before routing so it previews
+ * the platform-correct command form on any OS.
+ *
+ * The single highest-risk Windows detail is the `wt` name collision: Windows
+ * Terminal is `wt.exe` (tab launcher) while Worktrunk installs as `git-wt`
+ * (worktree creator). The two are resolved and referenced independently.
+ *
+ * Subprocess safety: every git / Worktrunk / AppleScript / Windows Terminal /
+ * PowerShell / tmux invocation goes through the injected `runCommand` boundary
+ * using list-based arguments (`execFile`, never `shell: true`), so all logic is
+ * unit-testable on Linux CI without spawning real commands or terminals.
+ */
+import { execFile } from "child_process";
+import path from "path";
+// Per-OS prerequisite knowledge + low-level command probes live in the shared
+// prereqs module so `runPreflight` (enforce) and the read-only `doctor` (render)
+// can never drift. `start-tickets.ts` imports VALUES from there; the prereqs
+// module imports only TYPES back, so the runtime graph stays acyclic.
+import { WORKTRUNK_BINARY_OVERRIDE_ENV, WINDOWS_TERMINAL_COMMAND, WINDOWS_POWERSHELL_CANDIDATES, DEFAULT_WINDOWS_WORKTRUNK_BINARY, DEFAULT_POSIX_WORKTRUNK_BINARY, TMUX_COMMAND, GIT_FOR_WINDOWS_BASH_HINT, isSupportedStartTicketsPlatform, unsupportedPlatformMessage, resolveWorktrunkBinary, commandSucceeded, getCommandProbe, isCommandOnPath, resolveFirstCommandOnPath, enforcePreflightPrerequisites, appendDoctorHint, } from "./start-tickets-prereqs.js";
+import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
+// Re-export the shared prereq surface (constants, platform helpers, command
+// probes) so existing import sites that read them from "./start-tickets.js"
+// keep working unchanged.
+export { WORKTRUNK_BINARY_OVERRIDE_ENV, WINDOWS_TERMINAL_COMMAND, WINDOWS_POWERSHELL_CANDIDATES, DEFAULT_WINDOWS_WORKTRUNK_BINARY, DEFAULT_POSIX_WORKTRUNK_BINARY, TMUX_COMMAND, GIT_FOR_WINDOWS_BASH_HINT, isSupportedStartTicketsPlatform, unsupportedPlatformMessage, resolveWorktrunkBinary, commandSucceeded, getCommandProbe, isCommandOnPath, resolveFirstCommandOnPath, };
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Jira-style ticket key, e.g. BAPI-248. */
+export const TICKET_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+/** Default cap on concurrently-created worktrees. */
+export const DEFAULT_MAX_PARALLEL = 3;
+/** Default tmux session-name prefix; one detached session is created per ticket. */
+export const DEFAULT_TMUX_SESSION_PREFIX = "bridge-start-tickets";
+/** Environment variable overriding the tmux session-name prefix. */
+export const TMUX_SESSION_OVERRIDE_ENV = "BAPI_TMUX_SESSION";
+// ---------------------------------------------------------------------------
+// Usage / argument parsing
+// ---------------------------------------------------------------------------
+/** User-facing usage text for the packaged `start-tickets` subcommand. */
+export function getStartTicketsUsage() {
+    return [
+        "Usage:",
+        "  npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]",
+        "",
+        "Flags:",
+        "  --agent claude|cursor-agent Agent command to launch in each worktree (default: claude)",
+        "  --terminal terminal|iterm   Override the macOS terminal app (default: auto-detect via $TERM_PROGRAM); honored on macOS only",
+        "  --dry-run                   Print intended actions; create no worktrees, open no tabs",
+        "  --branch KEY=BRANCH         Use BRANCH instead of feature/KEY for that ticket (repeatable)",
+        "  --no-refresh-main           Skip 'git fetch origin main' + fast-forward of local main",
+        "  --max-parallel N            Max worktrees to create concurrently (default: 3)",
+        "  -h, --help                  Show this help",
+        "",
+        "Environment:",
+        `  ${WORKTRUNK_BINARY_OVERRIDE_ENV}     Override the Worktrunk executable name/path for nonstandard installs`,
+        `  ${TMUX_SESSION_OVERRIDE_ENV}        Override the tmux session-name prefix on Linux (default: ${DEFAULT_TMUX_SESSION_PREFIX})`,
+        "",
+        "Prerequisites:",
+        "  macOS    wt, git, osascript",
+        "  Windows  git-wt, Git for Windows / Git Bash, Windows Terminal or PowerShell",
+        "  Linux    wt, git, tmux",
+        "",
+        "Each KEY must match [A-Z]+-[0-9]+ (e.g., BAPI-248).",
+    ].join("\n");
+}
+/**
+ * Parse argv strictly and without an arg-parser dependency. Returns a
+ * discriminated result: help, a validation error, or validated options.
+ */
+export function parseStartTicketsArgs(argv) {
+    // Help is honoured before any other validation.
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getStartTicketsUsage() };
+    }
+    let terminal;
+    let dryRun = false;
+    let refreshMain = true;
+    let maxParallelRaw;
+    let agentName = DEFAULT_AGENT_NAME;
+    const branchEntries = [];
+    const keys = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const takeValue = () => {
+            // The `--flag=value` form is handled inline by callers; this reads the
+            // separate next token for the `--flag value` form.
+            if (i + 1 >= argv.length)
+                return undefined;
+            i += 1;
+            return argv[i];
+        };
+        if (arg === "--agent" || arg.startsWith("--agent=")) {
+            let value;
+            if (arg.startsWith("--agent=")) {
+                value = arg.slice("--agent=".length);
+            }
+            else {
+                value = takeValue();
+                if (value === undefined) {
+                    return { status: "error", message: "--agent requires a value (an agent name)." };
+                }
+            }
+            if (!isAgentName(value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --agent value: '${value}' (allowed agents: ${formatValidAgentNames()}).`,
+                };
+            }
+            agentName = value;
+            continue;
+        }
+        if (arg === "--terminal" || arg.startsWith("--terminal=")) {
+            let value;
+            if (arg.startsWith("--terminal=")) {
+                value = arg.slice("--terminal=".length);
+            }
+            else {
+                value = takeValue();
+                if (value === undefined) {
+                    return { status: "error", message: "--terminal requires a value (terminal or iterm)." };
+                }
+            }
+            if (value !== "terminal" && value !== "iterm") {
+                return {
+                    status: "error",
+                    message: `Invalid --terminal value: '${value}' (allowed values: terminal, iterm).`,
+                };
+            }
+            terminal = value;
+            continue;
+        }
+        if (arg === "--max-parallel" || arg.startsWith("--max-parallel=")) {
+            if (arg.startsWith("--max-parallel=")) {
+                maxParallelRaw = arg.slice("--max-parallel=".length);
+            }
+            else {
+                const value = takeValue();
+                if (value === undefined) {
+                    return { status: "error", message: "--max-parallel requires a positive integer value." };
+                }
+                maxParallelRaw = value;
+            }
+            continue;
+        }
+        if (arg === "--branch" || arg.startsWith("--branch=")) {
+            let value;
+            if (arg.startsWith("--branch=")) {
+                value = arg.slice("--branch=".length);
+            }
+            else {
+                value = takeValue();
+                if (value === undefined) {
+                    return { status: "error", message: "--branch requires a KEY=BRANCH value." };
+                }
+            }
+            branchEntries.push(value);
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--no-refresh-main") {
+            refreshMain = false;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unknown flag: ${arg}` };
+        }
+        keys.push(arg);
+    }
+    // --- key validation ---
+    if (keys.length === 0) {
+        return {
+            status: "error",
+            message: "At least one ticket key is required (e.g., BAPI-248).",
+        };
+    }
+    const seen = new Set();
+    for (const key of keys) {
+        if (!TICKET_KEY_PATTERN.test(key)) {
+            return {
+                status: "error",
+                message: `Invalid ticket key: '${key}' (keys must match [A-Z]+-[0-9]+, e.g., BAPI-248).`,
+            };
+        }
+        if (seen.has(key)) {
+            return { status: "error", message: `Duplicate ticket key: '${key}'.` };
+        }
+        seen.add(key);
+    }
+    // --- max-parallel validation ---
+    let maxParallel = DEFAULT_MAX_PARALLEL;
+    if (maxParallelRaw !== undefined) {
+        if (!/^[0-9]+$/.test(maxParallelRaw) || Number(maxParallelRaw) < 1) {
+            return {
+                status: "error",
+                message: `Invalid --max-parallel value: '${maxParallelRaw}' (must be a positive integer).`,
+            };
+        }
+        maxParallel = Number(maxParallelRaw);
+    }
+    // --- branch override validation ---
+    const branchOverrides = {};
+    for (const entry of branchEntries) {
+        const sepIndex = entry.indexOf("=");
+        if (sepIndex <= 0) {
+            return {
+                status: "error",
+                message: `Invalid --branch override: '${entry}' (expected KEY=BRANCH).`,
+            };
+        }
+        const overrideKey = entry.slice(0, sepIndex);
+        const branchName = entry.slice(sepIndex + 1);
+        if (!TICKET_KEY_PATTERN.test(overrideKey)) {
+            return {
+                status: "error",
+                message: `Invalid --branch override key: '${overrideKey}' (keys must match [A-Z]+-[0-9]+).`,
+            };
+        }
+        if (!seen.has(overrideKey)) {
+            return {
+                status: "error",
+                message: `--branch override key '${overrideKey}' is not one of the requested tickets.`,
+            };
+        }
+        const branchError = validateBranchName(branchName);
+        if (branchError) {
+            return {
+                status: "error",
+                message: `Invalid branch name for ${overrideKey}: ${branchError}`,
+            };
+        }
+        branchOverrides[overrideKey] = branchName;
+    }
+    return {
+        status: "ok",
+        options: { keys, terminal, dryRun, refreshMain, maxParallel, branchOverrides, agentName },
+    };
+}
+/** Returns an error string for an unsafe branch name, or null when valid. */
+function validateBranchName(branch) {
+    if (branch.length === 0)
+        return "branch name must not be empty.";
+    if (branch.startsWith("-"))
+        return "branch name must not start with '-'.";
+    // Reject ASCII control characters (0x00-0x1F and 0x7F) without embedding
+    // raw control bytes in source.
+    for (let i = 0; i < branch.length; i++) {
+        const code = branch.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f) {
+            return "branch name must not contain control characters.";
+        }
+    }
+    return null;
+}
+/** Resolve the branch for a ticket: explicit override, else feature/<KEY>. */
+export function resolveBranchForTicket(key, overrides) {
+    if (Object.prototype.hasOwnProperty.call(overrides, key)) {
+        return overrides[key];
+    }
+    return `feature/${key}`;
+}
+/**
+ * Determine which macOS terminal to drive. An explicit choice wins; otherwise
+ * auto-detect iTerm from `$TERM_PROGRAM` (case-insensitive), defaulting to
+ * Terminal.app. Only consumed by the macOS spawner; ignored on Windows/Linux.
+ */
+export function detectTerminal(explicit, env) {
+    if (explicit)
+        return explicit;
+    const termProgram = (env.TERM_PROGRAM ?? "").toLowerCase();
+    if (termProgram.includes("iterm"))
+        return "iterm";
+    return "terminal";
+}
+// ---------------------------------------------------------------------------
+// Platform routing
+// ---------------------------------------------------------------------------
+//
+// `isSupportedStartTicketsPlatform`, `unsupportedPlatformMessage`, and
+// `resolveWorktrunkBinary` now live in ./start-tickets-prereqs.js (imported and
+// re-exported above) so preflight enforcement and the doctor share them.
+/** Map a platform to its default terminal spawner. */
+export function getDefaultSpawnTerminalTabForPlatform(platform) {
+    switch (platform) {
+        case "darwin":
+            return spawnMacOSTerminalTab;
+        case "win32":
+            return spawnWindowsTerminalTab;
+        case "linux":
+            return spawnLinuxTmuxTerminalTab;
+        default:
+            return spawnUnsupportedPlatformTerminalTab;
+    }
+}
+/**
+ * The single source of truth for platform selection. Resolves the Worktrunk
+ * binary, closes over the selected `agent` to build the per-platform shell
+ * command, and preserves the injected `deps.spawnTerminalTab` (so mocks/overrides
+ * are always honored). Returns a structured error for unsupported platforms;
+ * never throws.
+ */
+export function resolveStartTicketsPlatformConfig(deps, agent) {
+    if (!isSupportedStartTicketsPlatform(deps.platform)) {
+        return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
+    }
+    const platform = deps.platform;
+    return {
+        ok: true,
+        config: {
+            platform,
+            worktrunkBinary: resolveWorktrunkBinary(platform, deps.env),
+            buildAgentShellCommand: (key, worktreePath) => buildAgentShellCommand(agent, key, worktreePath, platform),
+            spawnTerminalTab: deps.spawnTerminalTab,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Pure escaping + slug helpers
+// ---------------------------------------------------------------------------
+/**
+ * Escape a string for inclusion inside a single-quoted shell context: each
+ * embedded single-quote becomes the sequence `'\''`. Returns only the inner
+ * escaped text (no surrounding quotes). Mirrors the bash `sh_squote_inner`.
+ */
+export function shSquoteInner(value) {
+    return value.replace(/'/g, "'\\''");
+}
+/**
+ * Escape a string for inclusion inside an AppleScript double-quoted literal:
+ * backslashes are doubled first, then double quotes are backslash-escaped.
+ * Returns only the inner escaped text (no surrounding quotes). Mirrors the
+ * bash `applescript_dquote_inner`.
+ */
+export function applescriptDquoteInner(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * Escape a string for inclusion inside a PowerShell single-quoted literal: each
+ * embedded single-quote is doubled (`'` -> `''`). Returns only the inner
+ * escaped text (no surrounding quotes). Mirrors the POSIX `shSquoteInner`
+ * pattern for the PowerShell quoting rules.
+ */
+export function powershellSquoteInner(value) {
+    return value.replace(/'/g, "''");
+}
+/** Wrap `value` in a PowerShell single-quoted literal, escaping inner quotes. */
+export function powershellSquote(value) {
+    return `'${powershellSquoteInner(value)}'`;
+}
+/**
+ * Slugify a ticket summary into a branch-name fragment. Mirrors the slash
+ * command's enrichment rules so behaviour stays consistent; the CLI itself
+ * does NOT call the Bridge API — enrichment happens in the slash command and
+ * is passed in via `--branch` overrides.
+ *
+ * Rules: lowercase, collapse runs of [^a-z0-9]+ to a single '-', trim leading
+ * and trailing '-', truncate to at most 40 chars preferring a dash boundary.
+ * Returns "" when no usable slug remains.
+ */
+export function slugifyTicketSummaryForBranch(summary) {
+    let slug = summary
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "");
+    if (slug.length <= 40)
+        return slug;
+    let truncated = slug.slice(0, 40);
+    const lastDash = truncated.lastIndexOf("-");
+    if (lastDash > 0) {
+        truncated = truncated.slice(0, lastDash);
+    }
+    return truncated.replace(/-+$/, "");
+}
+// ---------------------------------------------------------------------------
+// Subprocess boundary
+// ---------------------------------------------------------------------------
+/** Build the default dependency set backed by real subprocesses / process state. */
+export function createDefaultStartTicketsDeps() {
+    const runCommand = (file, args, options) => new Promise((resolve) => {
+        execFile(file, args, {
+            cwd: options?.cwd,
+            // Worktrunk JSON / git porcelain output can be large; give it room.
+            maxBuffer: 64 * 1024 * 1024,
+            encoding: "utf-8",
+        }, (error, stdout, stderr) => {
+            const exitCode = error && typeof error.code === "number"
+                ? (error.code)
+                : error
+                    ? 1
+                    : 0;
+            resolve({
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+                exitCode,
+            });
+        });
+    });
+    const deps = {
+        runCommand,
+        platform: process.platform,
+        env: process.env,
+        cwd: process.cwd(),
+        // The platform router is the single source of truth for spawner selection.
+        spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
+    };
+    return deps;
+}
+/** Combine a result's stderr + stdout into a single trimmed detail string. */
+function combineCommandOutput(result) {
+    return [result.stderr, result.stdout]
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .join(" ");
+}
+/**
+ * Verify a tool is on PATH via the platform-correct probe. An optional
+ * `installHint` is appended to the failure message. Thin wrapper around the
+ * shared `isCommandOnPath`; retained for callers/tests that prefer a structured
+ * `VoidResult` over a boolean.
+ */
+export async function requireCommandOnPath(deps, tool, installHint) {
+    if (await isCommandOnPath(deps, tool))
+        return { ok: true };
+    const hint = installHint ? ` ${installHint}` : "";
+    return { ok: false, error: `Required command not found on PATH: ${tool}.${hint}` };
+}
+/** Succeed when any candidate is on PATH; otherwise return `errorMessage`. */
+export async function requireAnyCommandOnPath(deps, candidates, errorMessage) {
+    const found = await resolveFirstCommandOnPath(deps, candidates);
+    if (found)
+        return { ok: true };
+    return { ok: false, error: errorMessage };
+}
+/**
+ * Minimal, fail-fast, per-platform pre-flight. Skipped entirely for dry runs.
+ * Delegates the per-OS prerequisite knowledge (worktrunk binary, git, the
+ * platform launchers, Git Bash, and the git work-tree check) to the shared
+ * `enforcePreflightPrerequisites`, so `runPreflight` and the read-only `doctor`
+ * never drift. A dependency-missing failure is annotated with a hint to run the
+ * read-only `doctor`; an unsupported-platform failure is returned as-is (doctor
+ * cannot fix it, and orchestration/CLI tests assert the bare message). `uv` and
+ * the selected agent are NOT enforced here — they are doctor-only. Never throws.
+ */
+export async function runPreflight(deps, options) {
+    if (options.dryRun)
+        return { ok: true };
+    const result = await enforcePreflightPrerequisites(deps);
+    if (result.ok)
+        return { ok: true };
+    if (result.reason === "unsupported-platform") {
+        return { ok: false, error: result.error };
+    }
+    return { ok: false, error: appendDoctorHint(result.error) };
+}
+// ---------------------------------------------------------------------------
+// main refresh + worktree parsing
+// ---------------------------------------------------------------------------
+/** Parse `git worktree list --porcelain` into entries with path + optional branch. */
+export function parseGitWorktreeList(output) {
+    const entries = [];
+    let current = null;
+    for (const rawLine of output.split("\n")) {
+        const line = rawLine.replace(/\r$/, "");
+        if (line.startsWith("worktree ")) {
+            if (current)
+                entries.push(current);
+            current = { path: line.slice("worktree ".length) };
+        }
+        else if (line.startsWith("branch ") && current) {
+            const ref = line.slice("branch ".length);
+            current.branch = ref.startsWith("refs/heads/")
+                ? ref.slice("refs/heads/".length)
+                : ref;
+        }
+    }
+    if (current)
+        entries.push(current);
+    return entries;
+}
+/** Return the worktree path owning branch `main`, or null. */
+export function findMainWorktreePath(entries) {
+    for (const entry of entries) {
+        if (entry.branch === "main")
+            return entry.path;
+    }
+    return null;
+}
+/**
+ * Fetch origin/main and fast-forward local `main`. No-op when `refreshMain` is
+ * false. Handles both checkout states:
+ *
+ *  - `main` IS checked out in a worktree → `git merge --ff-only` inside that
+ *    worktree, so its index/working tree stay consistent (git forbids
+ *    force-moving a checked-out branch ref).
+ *  - `main` is NOT checked out anywhere (e.g. the primary checkout is on a
+ *    feature/chore branch) → fast-forward the ref directly with
+ *    `git branch --force`, since no working tree depends on it. This is guarded
+ *    by an ancestry check so a diverged local `main` is never clobbered, and it
+ *    creates `main` from origin/main when no local ref exists yet.
+ *
+ * Returns a structured failure for any expected problem (fetch failure, diverged
+ * main, or a failed ref update).
+ */
+export async function refreshMainBranch(deps, options) {
+    if (!options.refreshMain)
+        return { ok: true };
+    const fetch = await deps.runCommand("git", ["fetch", "origin", "main"], {
+        cwd: deps.cwd,
+    });
+    if (!commandSucceeded(fetch)) {
+        return {
+            ok: false,
+            error: "git fetch origin main failed. Check your network and 'git remote get-url origin', or pass --no-refresh-main to skip.",
+        };
+    }
+    const list = await deps.runCommand("git", ["worktree", "list", "--porcelain"], { cwd: deps.cwd });
+    if (!commandSucceeded(list)) {
+        return {
+            ok: false,
+            error: "git worktree list --porcelain failed; cannot locate the main worktree.",
+        };
+    }
+    const mainPath = findMainWorktreePath(parseGitWorktreeList(list.stdout));
+    // `main` is checked out somewhere: fast-forward it in place. git refuses to
+    // force-move a checked-out branch ref, so we must go through merge.
+    if (mainPath) {
+        const merge = await deps.runCommand("git", ["merge", "--ff-only", "origin/main"], { cwd: mainPath });
+        if (!commandSucceeded(merge)) {
+            return {
+                ok: false,
+                error: `Local main has diverged from origin/main (checked out at ${mainPath}). Resolve the divergence manually, or rerun with --no-refresh-main.`,
+            };
+        }
+        return { ok: true };
+    }
+    // `main` is not checked out in any worktree. No working tree depends on the
+    // ref, so fast-forward it directly — but only when it is a true fast-forward,
+    // never clobbering local-only commits. When local `main` does not exist yet,
+    // create it from origin/main.
+    if (await branchExists(deps, "main")) {
+        const ancestor = await deps.runCommand("git", ["merge-base", "--is-ancestor", "main", "origin/main"], { cwd: deps.cwd });
+        if (!commandSucceeded(ancestor)) {
+            return {
+                ok: false,
+                error: "Local main has diverged from origin/main. Resolve the divergence manually, or rerun with --no-refresh-main.",
+            };
+        }
+    }
+    const update = await deps.runCommand("git", ["branch", "--force", "main", "origin/main"], { cwd: deps.cwd });
+    if (!commandSucceeded(update)) {
+        return {
+            ok: false,
+            error: "Failed to fast-forward local main to origin/main. Resolve manually, or rerun with --no-refresh-main.",
+        };
+    }
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Concurrency + worktree creation
+// ---------------------------------------------------------------------------
+/**
+ * Run `worker` over `items` with at most `limit` concurrent workers, preserving
+ * result order regardless of completion order.
+ */
+export async function runWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    const effectiveLimit = Math.max(1, Math.floor(limit));
+    let nextIndex = 0;
+    async function runner() {
+        while (true) {
+            const index = nextIndex;
+            if (index >= items.length)
+                return;
+            nextIndex += 1;
+            results[index] = await worker(items[index], index);
+        }
+    }
+    const runners = [];
+    const poolSize = Math.min(effectiveLimit, items.length);
+    for (let i = 0; i < poolSize; i++) {
+        runners.push(runner());
+    }
+    await Promise.all(runners);
+    return results;
+}
+/** True only when `git show-ref --verify --quiet refs/heads/<branch>` exits 0. */
+export async function branchExists(deps, branch) {
+    const result = await deps.runCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: deps.cwd });
+    return commandSucceeded(result);
+}
+/**
+ * Build `wt switch` args. Include `--create` only when the branch does not yet
+ * exist. Always include `-y` (auto-approve): the CLI runs the Worktrunk binary
+ * via `execFile` with no TTY, so without `-y` the `pre-start` / `post-start`
+ * hook-approval prompts would have no input source and the call would hang or
+ * fail — this mirrors the deleted `scripts/start-tickets.sh`, which ran
+ * `wt switch -c -y`. Never includes `-x` — the CLI owns worktree creation and
+ * tab spawning separately. The args are platform-agnostic; only the binary
+ * differs (`wt` vs `git-wt`).
+ */
+export function buildWtSwitchArgs(branch, exists) {
+    if (exists) {
+        return ["switch", "-y", branch, "--format=json"];
+    }
+    return ["switch", "--create", "-y", branch, "--format=json"];
+}
+/** Return the Node `path` API matching a platform (`win32` vs POSIX). */
+export function pathApiForPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/**
+ * Extract a worktree path from Worktrunk JSON stdout. Accepts several common
+ * shapes defensively and resolves relative paths against `cwd` using the
+ * platform-correct path semantics (so Windows-style paths resolve correctly
+ * even when the test/host OS differs). Throws when no usable path can be
+ * extracted.
+ */
+export function extractWorktreePath(stdout, cwd, platform = process.platform) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`Could not parse Worktrunk JSON output: ${stdout.slice(0, 200)}`);
+    }
+    const candidate = pickWorktreePathField(parsed);
+    if (!candidate) {
+        throw new Error(`Worktrunk JSON did not include a worktree path: ${stdout.slice(0, 200)}`);
+    }
+    const pathApi = pathApiForPlatform(platform);
+    return pathApi.isAbsolute(candidate) ? candidate : pathApi.resolve(cwd, candidate);
+}
+function pickWorktreePathField(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return undefined;
+    const obj = parsed;
+    if (typeof obj.path === "string")
+        return obj.path;
+    if (typeof obj.worktree_path === "string")
+        return obj.worktree_path;
+    if (typeof obj.directory === "string")
+        return obj.directory;
+    if (obj.worktree && typeof obj.worktree === "object") {
+        const nested = obj.worktree;
+        if (typeof nested.path === "string")
+            return nested.path;
+    }
+    return undefined;
+}
+/**
+ * Create / switch the worktree for a single ticket using the resolved Worktrunk
+ * binary (`wt` on macOS/Linux, `git-wt` on Windows). Returns a `created` row on
+ * success (with key, branch, path) or a `create-failed` row on any expected
+ * failure — never throws for per-ticket problems.
+ */
+export async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBinary) {
+    const branch = resolveBranchForTicket(key, branchOverrides);
+    try {
+        const exists = await branchExists(deps, branch);
+        const args = buildWtSwitchArgs(branch, exists);
+        const result = await deps.runCommand(worktrunkBinary, args, { cwd: deps.cwd });
+        if (!commandSucceeded(result)) {
+            const reason = (result.stderr || result.stdout || "").trim();
+            return {
+                key,
+                branch,
+                status: "create-failed",
+                error: `${worktrunkBinary} ${args.join(" ")} failed${reason ? `: ${reason}` : ""}`,
+            };
+        }
+        const worktreePath = extractWorktreePath(result.stdout, deps.cwd, deps.platform);
+        return { key, branch, status: "created", path: worktreePath };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { key, branch, status: "create-failed", error: message };
+    }
+}
+/**
+ * Create / switch worktrees for every ticket, throttled to `maxParallel`, using
+ * the resolved Worktrunk binary. Returns one row per ticket in original key
+ * order; per-ticket failures are recorded as `create-failed` rows rather than
+ * aborting the run.
+ */
+export async function createWorktrees(deps, options, worktrunkBinary) {
+    return runWithConcurrency(options.keys, options.maxParallel, (key) => createWorktreeForTicket(deps, key, options.branchOverrides, worktrunkBinary));
+}
+// ---------------------------------------------------------------------------
+// Per-platform shell-command construction
+// ---------------------------------------------------------------------------
+/** The starter prompt handed to the selected agent. Identical for every agent. */
+export function buildAgentPrompt(key) {
+    return `/implement-ticket ${key}`;
+}
+/**
+ * Build the agent invocation (`<command> <quotedPrompt>`) for the agent's prompt
+ * style. Only `positional` exists today; the `switch` keeps a future flag-style
+ * agent a typed extension rather than a silent fall-through. `quote` applies the
+ * platform-correct quoting to the prompt.
+ */
+export function buildAgentInvocation(agent, prompt, quote) {
+    switch (agent.promptArgStyle) {
+        case "positional":
+            return `${agent.command} ${quote(prompt)}`;
+        default: {
+            const exhaustive = agent.promptArgStyle;
+            throw new Error(`Unsupported agent promptArgStyle: ${String(exhaustive)}`);
+        }
+    }
+}
+/** POSIX agent shell command: `cd '<path>' && <agent> '<prompt>'`. */
+export function buildPosixAgentShellCommand(agent, key, worktreePath) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key), (p) => `'${shSquoteInner(p)}'`);
+    return `cd '${shSquoteInner(worktreePath)}' && ${invocation}`;
+}
+/** PowerShell agent shell command: `Set-Location -LiteralPath '<path>'; <agent> '<prompt>'`. */
+export function buildPowerShellAgentShellCommand(agent, key, worktreePath) {
+    const invocation = buildAgentInvocation(agent, buildAgentPrompt(key), powershellSquote);
+    return `Set-Location -LiteralPath ${powershellSquote(worktreePath)}; ${invocation}`;
+}
+/**
+ * Build the shell command run inside each spawned tab/session, dispatched by
+ * platform. PowerShell on Windows; POSIX everywhere else (incl. the unsupported
+ * dry-run fallback). The selected `agent` (never a module-level constant)
+ * determines the launched command.
+ */
+export function buildAgentShellCommand(agent, key, worktreePath, platform = "darwin") {
+    if (platform === "win32")
+        return buildPowerShellAgentShellCommand(agent, key, worktreePath);
+    return buildPosixAgentShellCommand(agent, key, worktreePath);
+}
+// ---------------------------------------------------------------------------
+// macOS terminal spawning (behind the injected boundary)
+// ---------------------------------------------------------------------------
+/** Generate AppleScript that runs `shellCommand` in a Terminal.app tab. */
+export function buildTerminalAppleScript(shellCommand) {
+    const esc = applescriptDquoteInner(shellCommand);
+    return [
+        'tell application "Terminal"',
+        "    activate",
+        "    if (count of windows) is 0 then",
+        `        do script "${esc}"`,
+        "    else",
+        '        tell application "System Events" to keystroke "t" using command down',
+        "        delay 0.2",
+        `        do script "${esc}" in selected tab of front window`,
+        "    end if",
+        "end tell",
+    ].join("\n");
+}
+/** Generate AppleScript that runs `shellCommand` in an iTerm2 tab. */
+export function buildITermAppleScript(shellCommand) {
+    const esc = applescriptDquoteInner(shellCommand);
+    return [
+        'tell application "iTerm"',
+        "    activate",
+        "    if (count of windows) = 0 then",
+        "        set newWindow to (create window with default profile)",
+        `        tell current session of newWindow to write text "${esc}"`,
+        "    else",
+        "        tell current window",
+        "            set newTab to (create tab with default profile)",
+        `            tell current session of newTab to write text "${esc}"`,
+        "        end tell",
+        "    end if",
+        "end tell",
+    ].join("\n");
+}
+/**
+ * Spawn a single macOS terminal tab running `shellCommand`. Selects the
+ * AppleScript builder by terminal choice and runs it via `osascript -e`. The
+ * optional `context` is accepted to satisfy the shared spawner signature but is
+ * unused on macOS. Returns a structured failure for expected spawn errors
+ * (never throws).
+ */
+export async function spawnMacOSTerminalTab(deps, terminal, shellCommand, _context) {
+    const script = terminal === "iterm"
+        ? buildITermAppleScript(shellCommand)
+        : buildTerminalAppleScript(shellCommand);
+    const result = await deps.runCommand("osascript", ["-e", script]);
+    if (commandSucceeded(result))
+        return { ok: true };
+    const reason = (result.stderr || result.stdout || "").trim();
+    return {
+        ok: false,
+        error: `osascript failed to open a ${terminal} tab${reason ? `: ${reason}` : ""}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Windows terminal spawning (behind the injected boundary)
+// ---------------------------------------------------------------------------
+/**
+ * List-based Windows Terminal args: open at `-d <path>` and run PowerShell.
+ *
+ * `wt.exe` parses `;` inside ANY argv item as a sub-command delimiter, so a raw
+ * `Set-Location ...; claude ...` PowerShell command would be split — the tab
+ * would only run `Set-Location` and the agent would never launch. Windows
+ * Terminal's documented escape for a literal semicolon is `\;`; wt.exe unescapes
+ * it back to `;` before handing the command to PowerShell. We therefore escape
+ * every `;` in the PowerShell command passed to wt.exe. (The PowerShell
+ * `Start-Process` fallback below does its own quoting via `-ArgumentList` and is
+ * unaffected.)
+ */
+export function buildWindowsTerminalArgs(worktreePath, shellCommand) {
+    const wtEscapedCommand = shellCommand.replace(/;/g, "\\;");
+    return ["new-tab", "-d", worktreePath, "powershell.exe", "-NoExit", "-Command", wtEscapedCommand];
+}
+/**
+ * Build the PowerShell `Start-Process` command used as the no-Windows-Terminal
+ * fallback. `Start-Process` opens a detached, visible window per ticket (a bare
+ * `powershell.exe -Command` invoked through `execFile` cannot). Nested quoting
+ * uses PowerShell single-quote escaping.
+ */
+export function buildPowerShellFallbackStartProcessCommand(worktreePath, shellCommand) {
+    const argumentList = `@('-NoExit', '-Command', ${powershellSquote(shellCommand)})`;
+    return (`Start-Process -FilePath 'powershell.exe' ` +
+        `-WorkingDirectory ${powershellSquote(worktreePath)} ` +
+        `-ArgumentList ${argumentList}`);
+}
+/**
+ * Spawn a Windows tab. Prefers Windows Terminal (`wt.exe new-tab`); falls back
+ * to `Start-Process powershell.exe` when Windows Terminal is absent. Never uses
+ * the Worktrunk `git-wt` binary for tab launching. Returns a structured failure
+ * (never throws).
+ */
+export async function spawnWindowsTerminalTab(deps, _terminal, shellCommand, context) {
+    const worktreePath = context?.worktreePath;
+    if (!worktreePath) {
+        return {
+            ok: false,
+            error: "Windows spawner requires a worktreePath context to open a tab.",
+        };
+    }
+    if (await isCommandOnPath(deps, WINDOWS_TERMINAL_COMMAND)) {
+        const args = buildWindowsTerminalArgs(worktreePath, shellCommand);
+        const result = await deps.runCommand(WINDOWS_TERMINAL_COMMAND, args);
+        if (commandSucceeded(result))
+            return { ok: true };
+        const reason = combineCommandOutput(result);
+        return {
+            ok: false,
+            error: `wt.exe failed to open a Windows Terminal tab${reason ? `: ${reason}` : ""}`,
+        };
+    }
+    const powershell = await resolveFirstCommandOnPath(deps, WINDOWS_POWERSHELL_CANDIDATES);
+    if (!powershell) {
+        return {
+            ok: false,
+            error: "Windows Terminal (wt.exe) or PowerShell is required to open a tab, but neither was found on PATH.",
+        };
+    }
+    const fallback = buildPowerShellFallbackStartProcessCommand(worktreePath, shellCommand);
+    const result = await deps.runCommand(powershell, [
+        "-NoProfile",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        fallback,
+    ]);
+    if (commandSucceeded(result))
+        return { ok: true };
+    const reason = combineCommandOutput(result);
+    return {
+        ok: false,
+        error: `PowerShell failed to open a window via Start-Process${reason ? `: ${reason}` : ""}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Linux tmux spawning (behind the injected boundary)
+// ---------------------------------------------------------------------------
+/** Sanitize a value into a tmux-safe identifier (no whitespace, '.', or ':'). */
+export function sanitizeTmuxName(value) {
+    const cleaned = value
+        .replace(/[^A-Za-z0-9_-]+/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "");
+    return cleaned.length > 0 ? cleaned : "ticket";
+}
+/** Safe tmux window name derived from the ticket key. */
+export function tmuxWindowNameForTicket(key) {
+    return sanitizeTmuxName(key);
+}
+/** Resolve the tmux session-name prefix (env override, else the default). */
+export function tmuxSessionPrefix(deps) {
+    const override = deps.env[TMUX_SESSION_OVERRIDE_ENV];
+    if (override !== undefined) {
+        const trimmed = override.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    return DEFAULT_TMUX_SESSION_PREFIX;
+}
+/** One detached tmux session per ticket: `<prefix>-<safe-key>`. */
+export function tmuxSessionNameForTicket(deps, key) {
+    return `${tmuxSessionPrefix(deps)}-${sanitizeTmuxName(key)}`;
+}
+/**
+ * Wrap the agent shell command so the tmux pane stays open after the agent
+ * exits or crashes (otherwise tmux closes the window and the user loses all
+ * output). `exec $SHELL` replaces the pane with an interactive login shell.
+ */
+export function buildTmuxPaneCommand(shellCommand) {
+    return `${shellCommand}; exec $SHELL`;
+}
+/** Args for `tmux new-session -d -s <session> -n <window> -c <path> <cmd>`. */
+export function buildTmuxNewSessionArgs(session, window, worktreePath, paneCommand) {
+    return ["new-session", "-d", "-s", session, "-n", window, "-c", worktreePath, paneCommand];
+}
+/** Args for `tmux new-window -t <session> -n <window> -c <path> <cmd>`. */
+export function buildTmuxNewWindowArgs(session, window, worktreePath, paneCommand) {
+    return ["new-window", "-t", session, "-n", window, "-c", worktreePath, paneCommand];
+}
+/**
+ * Spawn a Linux tmux session for one ticket. Creates one detached session per
+ * ticket (adding a window if that session already exists, e.g. on re-run),
+ * keeping the pane open after the agent exits. Emits a clear, actionable error
+ * when tmux is missing. No per-emulator detection. Returns a structured failure
+ * (never throws).
+ */
+export async function spawnLinuxTmuxTerminalTab(deps, _terminal, shellCommand, context) {
+    const worktreePath = context?.worktreePath;
+    const key = context?.key;
+    if (!worktreePath || !key) {
+        return {
+            ok: false,
+            error: "Linux tmux spawner requires a worktreePath context to open a session.",
+        };
+    }
+    if (!(await isCommandOnPath(deps, TMUX_COMMAND))) {
+        return {
+            ok: false,
+            error: "tmux is required to spawn Linux sessions but was not found on PATH. Install tmux and retry.",
+        };
+    }
+    const session = tmuxSessionNameForTicket(deps, key);
+    const window = tmuxWindowNameForTicket(key);
+    const paneCommand = buildTmuxPaneCommand(shellCommand);
+    const hasSession = await deps.runCommand(TMUX_COMMAND, ["has-session", "-t", session]);
+    const args = commandSucceeded(hasSession)
+        ? buildTmuxNewWindowArgs(session, window, worktreePath, paneCommand)
+        : buildTmuxNewSessionArgs(session, window, worktreePath, paneCommand);
+    const result = await deps.runCommand(TMUX_COMMAND, args);
+    if (commandSucceeded(result))
+        return { ok: true };
+    const reason = combineCommandOutput(result);
+    return {
+        ok: false,
+        error: `tmux failed to create a session/window${reason ? `: ${reason}` : ""}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Unsupported-platform spawner
+// ---------------------------------------------------------------------------
+/** Spawner for unsupported platforms: always a structured failure, never throws. */
+export async function spawnUnsupportedPlatformTerminalTab(deps, _terminal, _shellCommand, _context) {
+    return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
+}
+// ---------------------------------------------------------------------------
+// Tab spawning across created worktrees
+// ---------------------------------------------------------------------------
+/**
+ * Open one tab/session per successfully-created worktree, building each shell
+ * command with the platform-correct `buildShellCommand` and passing per-ticket
+ * context to the spawner. `created` rows become `spawned` (or `spawn-failed`);
+ * `create-failed` rows pass through untouched. The `terminal` choice is only
+ * consumed by the macOS spawner; Windows/Linux spawners intentionally ignore it.
+ */
+export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildShellCommand) {
+    const out = [];
+    for (const row of rows) {
+        if (row.status !== "created" || !row.path) {
+            out.push(row);
+            continue;
+        }
+        const shellCommand = buildShellCommand(row.key, row.path);
+        const result = await deps.spawnTerminalTab(deps, terminal, shellCommand, {
+            key: row.key,
+            worktreePath: row.path,
+        });
+        if (result.ok) {
+            out.push({ ...row, status: "spawned" });
+        }
+        else {
+            out.push({ ...row, status: "spawn-failed", error: result.error });
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Dry-run, summary, orchestration, CLI wrapper
+// ---------------------------------------------------------------------------
+/** Build one dry-run summary row per ticket with resolved branches. */
+export function buildDryRunResults(keys, overrides) {
+    return keys.map((key) => ({
+        key,
+        branch: resolveBranchForTicket(key, overrides),
+        status: "dry-run",
+    }));
+}
+/**
+ * Pure platform resolution for dry-run rendering only (no side effects). Closes
+ * over the selected `agent` to build the preview command. Uses `git-wt` +
+ * PowerShell on Windows, `wt` + POSIX on macOS/Linux, and a non-throwing `wt` +
+ * POSIX fallback for unsupported platforms.
+ */
+export function getDryRunPlatformDetails(agent, platform = process.platform, env = process.env) {
+    return {
+        worktrunkBinary: resolveWorktrunkBinary(platform, env),
+        buildAgentShellCommand: (key, worktreePath) => buildAgentShellCommand(agent, key, worktreePath, platform),
+    };
+}
+/**
+ * Build the user-facing dry-run detail lines for one ticket, rendering the
+ * platform-correct Worktrunk binary and the selected agent's shell command. Pure
+ * platform formatting only — no preflight, no routing failures.
+ */
+export function buildDryRunDetailLines(agent, key, branch, platform = process.platform, env = process.env) {
+    const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env);
+    const wtArgs = buildWtSwitchArgs(branch, false);
+    const agentInvocation = build(key, "<worktree-path>");
+    return [
+        `DRY-RUN: ${key} -> branch=${branch}`,
+        `DRY-RUN:   ${worktrunkBinary} ${wtArgs.join(" ")}`,
+        `DRY-RUN:   ${agentInvocation}`,
+    ];
+}
+/**
+ * Format the final summary report. Emits a delimited `Summary` section with one
+ * stable parseable line per ticket (`KEY  branch=BRANCH  status=STATUS`, plus
+ * `  path=PATH` when available) followed by warning lines for any create/spawn
+ * failures.
+ */
+export function formatSummaryReport(rows) {
+    const lines = ["Summary:"];
+    for (const row of rows) {
+        let line = `${row.key}  branch=${row.branch}  status=${row.status}`;
+        if (row.path)
+            line += `  path=${row.path}`;
+        lines.push(line);
+    }
+    const failures = rows.filter((r) => r.status === "create-failed" || r.status === "spawn-failed");
+    if (failures.length > 0) {
+        lines.push("");
+        lines.push("Warnings:");
+        for (const row of failures) {
+            lines.push(`  ${row.key}: ${row.error ?? row.status}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Top-level orchestration. Dry runs short-circuit to dry-run rows (before any
+ * preflight or routing). Otherwise run preflight, resolve the platform config,
+ * refresh main (unless disabled), create worktrees with throttling using the
+ * resolved Worktrunk binary, then spawn tabs/sessions for successful worktrees
+ * using the platform-correct shell builder. Global preflight/refresh failures
+ * are returned as `{ ok: false }`; per-ticket failures stay in the rows.
+ */
+export async function orchestrateStartTickets(deps, options) {
+    if (options.dryRun) {
+        return { ok: true, rows: buildDryRunResults(options.keys, options.branchOverrides) };
+    }
+    // Resolve the selected agent once, before any side effects, so an invalid
+    // agent fails fast with a clear error and no Worktrunk/terminal work occurs.
+    const agent = resolveAgentSpec(options.agentName);
+    if (!agent) {
+        return {
+            ok: false,
+            error: `Unknown agent: '${options.agentName}'. Valid agents: ${formatValidAgentNames()}.`,
+        };
+    }
+    const preflight = await runPreflight(deps, options);
+    if (!preflight.ok)
+        return { ok: false, error: preflight.error };
+    const platformConfig = resolveStartTicketsPlatformConfig(deps, agent);
+    if (!platformConfig.ok)
+        return { ok: false, error: platformConfig.error };
+    const refresh = await refreshMainBranch(deps, options);
+    if (!refresh.ok)
+        return { ok: false, error: refresh.error };
+    const created = await createWorktrees(deps, options, platformConfig.config.worktrunkBinary);
+    const terminal = detectTerminal(options.terminal, deps.env);
+    const rows = await spawnTabsForCreatedWorktrees(deps, created, terminal, platformConfig.config.buildAgentShellCommand);
+    return { ok: true, rows };
+}
+/** Platform-specific guidance printed when one or more tabs fail to spawn. */
+function spawnFailureHintForPlatform(platform) {
+    if (platform === "darwin") {
+        return ("One or more tabs failed to spawn. If osascript reported a permission error, grant the " +
+            "required macOS permissions under System Settings -> Privacy & Security, then re-run: " +
+            "Automation (to let the terminal app be controlled) and, for the Terminal.app path, " +
+            "Accessibility (the new-tab step sends Cmd-T via System Events keystrokes, which Automation " +
+            "alone does not cover).");
+    }
+    if (platform === "win32") {
+        return ("One or more tabs failed to spawn. Ensure Windows Terminal (wt.exe) or PowerShell is " +
+            "installed and on PATH; see the per-ticket warnings above for details.");
+    }
+    if (platform === "linux") {
+        return ("One or more tabs failed to spawn. Ensure tmux is installed and on PATH; see the " +
+            "per-ticket warnings above for details.");
+    }
+    return "One or more tabs failed to spawn; see the per-ticket warnings above for details.";
+}
+/**
+ * CLI entry for the `start-tickets` subcommand. Returns a process exit code.
+ * Help returns 0; validation / global failures return 1; a normal run returns
+ * 0 even when individual tickets have create-failed / spawn-failed statuses.
+ */
+export async function runStartTicketsCli(argv, overrides = {}) {
+    const log = overrides.log ?? ((m) => console.log(m));
+    const errorLog = overrides.errorLog ?? ((m) => console.error(m));
+    const parsed = parseStartTicketsArgs(argv);
+    if (parsed.status === "help") {
+        log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        errorLog(`Error: ${parsed.message}`);
+        errorLog("");
+        errorLog(getStartTicketsUsage());
+        return 1;
+    }
+    const options = parsed.options;
+    const deps = overrides.deps ?? createDefaultStartTicketsDeps();
+    const orchestrate = overrides.orchestrate ?? orchestrateStartTickets;
+    // The parser validates `--agent`, so this resolves to a real spec; the guard
+    // is defensive only.
+    const agent = resolveAgentSpec(options.agentName);
+    if (!agent) {
+        errorLog(`Error: Unknown agent: '${options.agentName}'. Valid agents: ${formatValidAgentNames()}.`);
+        return 1;
+    }
+    if (options.dryRun) {
+        for (const key of options.keys) {
+            const branch = resolveBranchForTicket(key, options.branchOverrides);
+            for (const line of buildDryRunDetailLines(agent, key, branch, deps.platform, deps.env)) {
+                log(line);
+            }
+        }
+        log("");
+    }
+    const result = await orchestrate(deps, options);
+    if (!result.ok) {
+        errorLog(`Error: ${result.error}`);
+        return 1;
+    }
+    log(formatSummaryReport(result.rows));
+    // Linux: each spawned ticket runs in a detached tmux session — tell the user
+    // how to attach.
+    const spawned = result.rows.filter((r) => r.status === "spawned");
+    if (deps.platform === "linux" && spawned.length > 0) {
+        log("");
+        log("Linux: each ticket runs in a detached tmux session. Attach with:");
+        for (const row of spawned) {
+            log(`  tmux attach -t ${tmuxSessionNameForTicket(deps, row.key)}`);
+        }
+    }
+    const spawnFailures = result.rows.filter((r) => r.status === "spawn-failed");
+    if (spawnFailures.length > 0) {
+        errorLog("");
+        errorLog(spawnFailureHintForPlatform(deps.platform));
+    }
+    return 0;
+}