@bridge_gpt/mcp-server 0.2.0 → 0.2.2

package/README.md

@@ -193,7 +193,7 @@ These features are useful for most tickets.
 **4. Deep Research**
 - **What it does:** Runs multi-source, fact-checked web research on a technical topic and returns a cited report.
 - **When it's useful:** (Architecture | Refinement) When a decision hinges on outside knowledge (libraries, best practices, standards) you don't already have.
-- **How to use it:** `/deep-research <question>`
+- **How to use it:** `/bridge-research <question>`
 
 **5. Jira Ticket Writer**
 - **What it does:** An agent that drafts a well-structured Jira ticket from a plain description, applying your project's standards.
@@ -211,57 +211,57 @@ These features are useful for most tickets.
 
 These features are good to know, but you probably won't use them every day.
 
-**1. Second Opinion**
-- **What it does:** Gets an immediate critique of any text from a different model family — no artifact saved, just the reply.
-- **When it's useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.
-- **How to use it:** ask your agent — *"Get a second opinion from Gemini on whether the BAPI-123 plan's migration step is safe to run against prod."*
-- **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).
-
-**2. Idea to Ticket**
-- **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.
-- **When it's useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.
-- **How to use it:** `/idea-to-ticket <idea>`
-
-**3. Explore Ticket**
-- **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.
-- **When it's useful:** (Architecture | Refinement) Before writing a ticket or plan, when you're unsure how a change would fit the existing code.
-- **How to use it:** `/explore-ticket <task>` — *"Explore the codebase for how we'd add a Mistral LLM provider and recommend 2–3 implementation options."*
-
-**4. Plan Ticket**
+**1. Plan Ticket**
 - **What it does:** Generates a step-by-step implementation plan for a ticket, with references to real code files, and saves it locally.
 - **When it's useful:** (Refinement | Implementation) Once a ticket is solid and you want a concrete build plan before (or instead of) auto-implementing.
 - **How to use it:** `/plan-ticket BAPI-123`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check the plan with a second provider.
 
-**5. Clarify Ticket**
+**2. Clarify Ticket**
 - **What it does:** Generates clarifying questions for a ticket (or debugging guidance for bugs) and saves them locally.
 - **When it's useful:** (Refinement) When a ticket feels under-specified and you want the open questions made explicit.
 - **How to use it:** `/clarify-ticket BAPI-123` — *"Generate clarifying questions for BAPI-123"*
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**6. Critique Ticket**
+**3. Critique Ticket**
 - **What it does:** Critiques a ticket's quality against your project standards and lists deviations + improvements.
 - **When it's useful:** (Refinement) When you want a quality gate on a ticket before it's worked.
 - **How to use it:** `/critique-ticket BAPI-123` — *"Critique BAPI-123 against our project standards and list what's missing or deviating."*
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**7. Full Automation**
-- **What it does:** Drives the whole chain end-to-end: idea → ticket(s) → review each → spawn worktrees to implement.
-- **When it's useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.
-- **How to use it:** `/full-automation <idea>` (command only — creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can't).
-- **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.
+**4. Explore Ticket**
+- **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.
+- **When it's useful:** (Architecture | Refinement) Before writing a ticket or plan, when you're unsure how a change would fit the existing code.
+- **How to use it:** `/explore-ticket <task>` — *"Explore the codebase for how we'd add a Mistral LLM provider and recommend 2–3 implementation options."*
+
+**5. Second Opinion**
+- **What it does:** Gets an immediate critique of any text from a different model family — no artifact saved, just the reply.
+- **When it's useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.
+- **How to use it:** ask your agent — *"Get a second opinion from Gemini on whether the BAPI-123 plan's migration step is safe to run against prod."*
+- **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).
+
+**6. Generate Image**
+- **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.
+- **When it's useful:** (Architecture | Refinement) When you want a quick visual — a UI mockup, diagram, or illustration — to anchor a design discussion or attach to a ticket.
+- **How to use it:** ask your agent — *"Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."*
+- **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen — adds an invisible SynthID watermark) · `quality` low (default, cheapest) / medium / high · `size` 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to `BAPI_DOCS_DIR/images/` and also returned inline.
 
-**8. Implement Ticket**
+**7. Implement Ticket**
 - **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.
 - **When it's useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.
 - **How to use it:** `/implement-ticket BAPI-123` (command only — "implement X" as free text almost always triggers a freehand build instead of the Bridge plan→code→PR→CI pipeline).
 - **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).
 
-**9. Generate Image**
-- **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.
-- **When it's useful:** (Architecture | Refinement) When you want a quick visual — a UI mockup, diagram, or illustration — to anchor a design discussion or attach to a ticket.
-- **How to use it:** ask your agent — *"Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."*
-- **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen — adds an invisible SynthID watermark) · `quality` low (default, cheapest) / medium / high · `size` 1024x1024 / 1024x1536 / 1536x1024 · `save_locally` write the image to `docs/images`.
+**8. Full Automation**
+- **What it does:** Drives the whole chain end-to-end: idea → ticket(s) → review each → spawn worktrees to implement.
+- **When it's useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.
+- **How to use it:** `/full-automation <idea>` (command only — creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can't).
+- **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.
+
+**9. Idea to Ticket**
+- **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.
+- **When it's useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.
+- **How to use it:** `/idea-to-ticket <idea>`
 
 ### Tier 3 — Now and then
 
@@ -277,40 +277,40 @@ These features are useful once in a while, but you probably won't need them ever
 - **When it's useful:** (Implementation) After making changes, to confirm everything passes and auto-fix straightforward breakages.
 - **How to use it:** `/run-tests` (`--unit-only`, `--skip-e2e`)
 
-**3. Learn Repository**
-- **What it does:** Researches and documents the repo's architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.
-- **When it's useful:** (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge's agents follow your conventions.
-- **How to use it:** `/learn-repository`
-
-**4. Teach Bridge**
-- **What it does:** Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).
-- **When it's useful:** (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.
-- **How to use it:** `/teach-bridge <teaching>` — *"Teach Bridge: always use data-testid selectors in E2E tests."*
+**3. Plan Epic**
+- **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.
+- **When it's useful:** (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.
+- **How to use it:** `/plan-epic <epic>` — *"Decompose the epic 'migrate PayPal token storage off Custom Objects' into sub-tasks with an exploration doc for each."*
 
-**5. Update Ticket**
+**4. Update Ticket**
 - **What it does:** Synthesizes a ticket's clarifying answers and critique into a rewritten description and pushes it to Jira.
 - **When it's useful:** (Refinement) After review, to fold the resolved questions and fixes back into the ticket itself.
 - **How to use it:** `/update-ticket BAPI-123` (command only — does a full overwrite of the live Jira description; "update" as free text is both vague and hard to reverse).
 
-**6. Plan Epic**
-- **What it does:** Decomposes a large epic into sub-tasks with a structured exploration doc for each.
-- **When it's useful:** (Architecture | Refinement) When a feature is too big for one ticket and you need it broken down and scoped.
-- **How to use it:** `/plan-epic <epic>` — *"Decompose the epic 'migrate PayPal token storage off Custom Objects' into sub-tasks with an exploration doc for each."*
+**5. Get Ticket**
+- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).
+- **When it's useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.
+- **How to use it:** ask your agent — *"Pull up BAPI-123 and show me its description, status, and acceptance criteria."*
+
+**6. Write Comment**
+- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).
+- **When it's useful:** (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.
+- **How to use it:** ask your agent — *"Post a comment on BAPI-123: blocked on the expired Atlassian token — will retry after it's rotated."*
 
 **7. Download / Upload Attachment**
 - **What it does:** Pulls files off a Jira ticket to disk, or attaches a local file to a ticket.
 - **When it's useful:** (Refinement | Implementation) When a ticket has design files/logs you need locally, or you want to attach output back to it.
 - **How to use it:** ask your agent — *"Download the design mockups attached to BAPI-123 into my docs folder."* / *"Attach build-log.txt to BAPI-123."*
 
-**8. Write Comment**
-- **What it does:** Posts a comment on a Jira ticket (markdown; long ones can attach as a file).
-- **When it's useful:** (Refinement | Implementation) To leave context, status, or a decision trail on the ticket.
-- **How to use it:** ask your agent — *"Post a comment on BAPI-123: blocked on the expired Atlassian token — will retry after it's rotated."*
+**8. Learn Repository**
+- **What it does:** Researches and documents the repo's architecture, testing, review, and correctness standards, then saves them to Bridge for future agents.
+- **When it's useful:** (Setup/Learning) When onboarding a new repo, or after big changes, so Bridge's agents follow your conventions.
+- **How to use it:** `/learn-repository`
 
-**9. Get Ticket**
-- **What it does:** Retrieves the full details of a Jira ticket (summary, status, description, etc.).
-- **When it's useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.
-- **How to use it:** ask your agent — *"Pull up BAPI-123 and show me its description, status, and acceptance criteria."*
+**9. Teach Bridge**
+- **What it does:** Takes a plain-English instruction, figures out which standards field it belongs to, and merges it in (admin only).
+- **When it's useful:** (Setup/Learning) When you notice the agents missing a convention and want to correct it in one sentence.
+- **How to use it:** `/teach-bridge <teaching>` — *"Teach Bridge: always use data-testid selectors in E2E tests."*
 
 ### Operational commands
 
@@ -372,6 +372,8 @@ Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switch
 npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 ```
 
+**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-5 → basic, 6+ → premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier → alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all omit `--model` (the agent uses its default) and surface a per-ticket warning rather than failing the spawn. `--dry-run` does **not** fetch tiers or inject `--model`.
+
 **Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.
 
 - **macOS** — opens a Terminal.app or iTerm tab via `osascript`.
@@ -540,7 +542,7 @@ The server registers **55 tools**. Async AI tools follow a request/get pattern:
 - **Jira status** — `get_jira_transitions`, `update_jira_status`, `resolve_target_status`
 - **Repository & CI** — `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
 - **Pipelines & automation** — `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`
-- **Config & telemetry** — `get_project_standards`, `list_config_fields`, `get_config_field`, `update_config_field`, `record_tiered_section_metric`
+- **Config** — `get_project_standards`, `list_config_fields`, `get_config_field`, `update_config_field`
 
 ### Bundled pipelines
 

package/build/agent-launchers/claude.js

@@ -1,15 +1,17 @@
 /**
- * The v1 `claude` agent launcher (BAPI-327).
+ * The `claude` agent launcher (BAPI-327, generalized in BAPI-351).
  *
  * Resolves the `claude` binary against the *baked schedule-time PATH* (not the
- * ambient process default), builds the locked
- * `/full-automation --scheduled-at <T> --idea-file <abs> [--auto]`
- * prompt, and emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
+ * ambient process default) and builds the scheduled-run invocation by delegating
+ * to the shared `renderScheduledPrompt` renderer (no hard-coded `/full-automation`
+ * prompt). It emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
  * working-directory flag, so the cwd is always set by the scheduler unit — this
- * adapter must never add a cwd argument to the invocation.
+ * adapter must never add a working-directory argument to the invocation.
  */
 import { pathApiForPlatform } from "../scheduler-backends/types.js";
 import { posixShellQuote, windowsCmdQuote } from "../scheduler-backends/escaping.js";
+import { renderScheduledPrompt } from "../scheduled-prompt.js";
+import { quotePromptToken } from "../scheduled-prompt.js";
 /**
  * Resolve a bare command to an absolute path using the platform PATH-probe,
  * forcing the baked PATH so the schedule resolves the same binary the user had
@@ -40,24 +42,30 @@ export async function resolveCommandOnPath(command, envPath, deps) {
     return pathApi.normalize(candidate);
 }
 /**
- * Quote the idea-file path so it survives as a single `/full-automation`
- * argument even when it contains spaces or markup-significant characters
- * (`&`, `<`, `>`, …) that would otherwise be split or mangled when the slash
- * command is parsed. Only an embedded double quote needs escaping; the same
- * absolute path is additionally baked into `BRIDGE_GPT_IDEA_FILE` by every
- * backend as a robust environment fallback.
+ * Backward-compatibility shim for callers that quoted an idea-file path for a
+ * `/full-automation` prompt. Generalized prompt-token quoting now lives in
+ * `quotePromptToken`; this preserves the original quote semantics (always wrap in
+ * double quotes, escape embedded quotes) for any remaining path callers.
  */
 export function quoteIdeaFileForPrompt(ideaFile) {
     return `"${ideaFile.replace(/"/g, '\\"')}"`;
 }
+/** Re-export the generalized token quoter so launcher consumers have one import. */
+export { quotePromptToken };
 /**
- * Build the exact full-automation prompt. `--auto` is appended by
- * default; it is omitted only when the caller selected `--no-auto`.
+ * Build the scheduled-run prompt for the Claude launcher by delegating to the
+ * shared renderer. Exposed for focused unit testing of the launcher wiring.
  */
 export function buildClaudePrompt(input) {
-    const base = `/full-automation --scheduled-at ${input.runAtIso} ` +
-        `--idea-file ${quoteIdeaFileForPrompt(input.ideaFile)}`;
-    return input.autoApprove ? `${base} --auto` : base;
+    return renderScheduledPrompt({
+        scheduleId: input.scheduleId,
+        scheduledAt: input.runAtIso,
+        autoApprove: input.autoApprove,
+        commandName: input.commandName,
+        args: input.args,
+        commandBody: input.commandBody,
+        schema: input.schema,
+    });
 }
 const CLAUDE_CAPABILITY = {
     name: "claude",
@@ -65,7 +73,7 @@ const CLAUDE_CAPABILITY = {
     supportsCwdFlag: false,
     promptFlag: "-p",
 };
-/** Create the v1 Claude agent launcher. */
+/** Create the Claude agent launcher. */
 export function createClaudeLauncher() {
     return {
         capability: CLAUDE_CAPABILITY,

package/build/agent-launchers/cursor.js

@@ -0,0 +1,65 @@
+/**
+ * The `cursor-agent` agent launcher (BAPI-351).
+ *
+ * A near-mirror of the Claude launcher: it resolves the `cursor-agent` binary
+ * against the baked schedule-time PATH and builds the scheduled-run prompt via
+ * the shared `renderScheduledPrompt` renderer (so the drift gate and command body
+ * are identical across agents). A local spike confirmed cursor-agent resolves the
+ * same `.claude/commands` catalog and exits cleanly in headless mode.
+ *
+ * Cursor differences vs. Claude:
+ *  - headless invocation needs `--output-format text`, `--trust`, and a
+ *    `--workspace <repoPath>` flag (Cursor's working-directory flag), with the
+ *    prompt as the final positional token;
+ *  - headless auth is via the `CURSOR_API_KEY` environment variable. This adapter
+ *    never reads or prints that value — auth readiness is a prerequisite check.
+ */
+import { posixShellQuote, windowsCmdQuote } from "../scheduler-backends/escaping.js";
+import { renderScheduledPrompt } from "../scheduled-prompt.js";
+import { resolveCommandOnPath } from "./claude.js";
+/** Build the scheduled-run prompt for the Cursor launcher via the shared renderer. */
+export function buildCursorPrompt(input) {
+    return renderScheduledPrompt({
+        scheduleId: input.scheduleId,
+        scheduledAt: input.runAtIso,
+        autoApprove: input.autoApprove,
+        commandName: input.commandName,
+        args: input.args,
+        commandBody: input.commandBody,
+        schema: input.schema,
+    });
+}
+const CURSOR_CAPABILITY = {
+    name: "cursor-agent",
+    command: "cursor-agent",
+    supportsCwdFlag: true,
+    promptFlag: "-p",
+};
+/** Create the cursor-agent launcher. */
+export function createCursorLauncher() {
+    return {
+        capability: CURSOR_CAPABILITY,
+        resolveBinary(envPath, deps) {
+            return resolveCommandOnPath("cursor-agent", envPath, deps);
+        },
+        buildInvocation(exe, input) {
+            const prompt = buildCursorPrompt(input);
+            // Cursor takes the working directory via --workspace and the prompt as the
+            // final positional token; CURSOR_API_KEY (auth) is never placed in argv.
+            const args = [
+                CURSOR_CAPABILITY.promptFlag,
+                "--output-format",
+                "text",
+                "--trust",
+                "--workspace",
+                input.repoPath,
+                prompt,
+            ];
+            return { exe, args, prompt };
+        },
+        formatInvocationLine(invocation, platform) {
+            const quote = platform === "win32" ? windowsCmdQuote : posixShellQuote;
+            return [invocation.exe, ...invocation.args].map((part) => quote(part)).join(" ");
+        },
+    };
+}

package/build/agent-launchers/index.js

@@ -1,17 +1,32 @@
 /**
- * Agent-launcher registry (BAPI-327). v1 ships only `claude`; the lookup returns
- * `null` for every other name so the CLI can reject unsupported agents with a
- * clear message rather than silently falling back.
+ * Agent-launcher registry (BAPI-327, extended in BAPI-351).
+ *
+ * Maps a launcher name to its adapter. BAPI-351 added `cursor-agent` beside the
+ * default `claude`; the lookup returns `null` for every other name so the CLI can
+ * reject unsupported agents with a clear message rather than silently falling
+ * back. The supported names are kept aligned with `AgentName` from
+ * `agent-registry.ts` to avoid registry drift.
  */
 import { createClaudeLauncher } from "./claude.js";
+import { createCursorLauncher } from "./cursor.js";
 export { createClaudeLauncher } from "./claude.js";
+export { createCursorLauncher } from "./cursor.js";
 const CLAUDE_LAUNCHER = createClaudeLauncher();
-/** Return the launcher for a name, or `null` when unsupported in v1. */
+const CURSOR_LAUNCHER = createCursorLauncher();
+/** All supported launcher names, in deterministic order (claude first/default). */
+const LAUNCHER_NAMES = ["claude", "cursor-agent"];
+/** Return the launcher for a name, or `null` when unsupported. */
 export function getAgentLauncher(name) {
-    return name === "claude" ? CLAUDE_LAUNCHER : null;
+    switch (name) {
+        case "claude":
+            return CLAUDE_LAUNCHER;
+        case "cursor-agent":
+            return CURSOR_LAUNCHER;
+        default:
+            return null;
+    }
 }
-/** Comma-separated list of valid agent-launcher names (just `claude` in v1). */
+/** Comma-separated list of valid agent-launcher names (`claude, cursor-agent`). */
 export function formatValidAgentLauncherNames() {
-    const names = ["claude"];
-    return names.join(", ");
+    return LAUNCHER_NAMES.join(", ");
 }

package/build/agent-registry.js

@@ -11,6 +11,19 @@
  * `start-tickets.ts` / `start-tickets-prereqs.ts` / `doctor.ts`) so every other
  * module can import it without risking a circular dependency.
  */
+/**
+ * Conservative allowlist pattern for any model alias before it can reach shell
+ * construction. Mirrors the backend `_MODEL_ALIAS_PATTERN` in jira_api.py.
+ */
+export const MODEL_ALIAS_PATTERN = /^[A-Za-z0-9._:-]+$/;
+/** True only when `value` is a non-empty string matching the alias pattern. */
+export function isValidModelAlias(value) {
+    return typeof value === "string" && value.length > 0 && MODEL_ALIAS_PATTERN.test(value);
+}
+/** Type guard: true only for the three known tier names. */
+export function isModelTier(value) {
+    return value === "cheap" || value === "basic" || value === "premium";
+}
 /**
  * The registry: the ONLY place mapping an agent name to its command/spec. Seeded
  * with exactly `claude` (default) and `cursor-agent`. `as const satisfies` keeps
@@ -28,6 +41,12 @@ export const AGENT_REGISTRY = {
             win32: "npm install -g @anthropic-ai/claude-code",
         },
         authNote: "Claude Code authenticates interactively on first run — follow its login/auth prompt if asked.",
+        supportsModelOverride: true,
+        modelFlag: "--model",
+        // Claude family aliases float to the latest release and never drift, so they
+        // can be validated against a static allowlist.
+        tierModels: { cheap: "haiku", basic: "sonnet", premium: "opus" },
+        staticModelAliasAllowlist: ["haiku", "sonnet", "opus"],
     },
     "cursor-agent": {
         name: "cursor-agent",
@@ -39,6 +58,24 @@ export const AGENT_REGISTRY = {
             win32: "irm 'https://cursor.com/install?win32=true' | iex",
         },
         authNote: "Run cursor-agent login to authenticate; doctor checks PATH presence only, not login state.",
+        supportsModelOverride: true,
+        modelFlag: "--model",
+        // NOTE: Cursor model strings are version-sensitive and DRIFT between
+        // releases — unlike claude's stable family aliases. The ids are not even
+        // internally consistent across versions (Cursor advertises Sonnet/Opus 4.6
+        // as `claude-4.6-sonnet-…`/`claude-4.6-opus-…` but Opus 4.7/4.8 as
+        // `claude-opus-4-7-…`/`claude-opus-4-8-…`), so these defaults WILL go stale.
+        // There is therefore NO staticModelAliasAllowlist here; any resolved cursor
+        // alias is validated non-interactively at runtime (against
+        // `cursor-agent --list-models`) before injection, and an unadvertised id
+        // fail-opens to the cursor default. To pin a current id without a release,
+        // use the per-repo `difficulty_model_tier_overrides` config.
+        // Last verified against `cursor-agent --list-models` on 2026-06-15.
+        tierModels: {
+            cheap: "auto",
+            basic: "claude-4.6-sonnet-medium",
+            premium: "claude-opus-4-8-thinking-high",
+        },
     },
 };
 /** The default agent used when `--agent` is omitted. */
@@ -66,3 +103,34 @@ export function resolveAgentSpec(name) {
 export function formatValidAgentNames() {
     return listAgentNames().join(", ");
 }
+/**
+ * Resolve the concrete model alias to inject for a given agent + tier, applying
+ * an optional per-repo override. Pure and dependency-free: it never spawns a
+ * subprocess and never imports from `start-tickets.ts`.
+ *
+ * Returns `null` (meaning "omit `--model`, use the agent default") when:
+ *  - the agent does not support a model override,
+ *  - no tier is provided,
+ *  - the resolved candidate fails the alias-pattern validation, or
+ *  - the agent has a `staticModelAliasAllowlist` and the candidate is not in it.
+ *
+ * A non-empty override for the selected tier takes precedence over the registry
+ * default. For agents without a static allowlist (e.g. cursor-agent), the caller
+ * is still responsible for live-validating the returned alias before injection.
+ */
+export function resolveModelAlias(agent, tier, overrides) {
+    if (!agent.supportsModelOverride)
+        return null;
+    if (!tier)
+        return null;
+    const override = overrides?.[tier];
+    const candidate = typeof override === "string" && override.trim().length > 0
+        ? override.trim()
+        : agent.tierModels[tier];
+    if (typeof candidate !== "string" || !isValidModelAlias(candidate))
+        return null;
+    if (agent.staticModelAliasAllowlist && !agent.staticModelAliasAllowlist.includes(candidate)) {
+        return null;
+    }
+    return candidate;
+}