@bridge_gpt/mcp-server 0.2.21 → 0.2.24

package/build/docs.generated.js

@@ -0,0 +1,5 @@
+// AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
+// This file is produced by scripts/bundle-docs.js
+export const DOCS = {
+    "docs/mcp-tool-integrations.md": "# MCP tool integrations — the human \"why\" behind the capability report\n\nThis catalog is **explanatory prose only**. It exists so the `/install-bridge`\ncapability report can cite a human-readable \"why\" for each gate. It is **not** a\nsource of truth for gating: the server computes every `locked_tools` /\n`unlocked_tools` membership decision itself and the agent must never recompute a\ntool's dependencies from this document.\n\n**Authoritative source of gating.** The enforced rules — which tools are blocked,\nwhich are degraded, and what each requires — live in\n`api/library/vcs/vcs_route_operations.py`:\n\n- `VCS_ROUTE_REQUIREMENTS` — routes that **BLOCK** (are unavailable) without a\n  VCS connection.\n- `VCS_ROUTE_WARNINGS` — routes that **DEGRADE** (stay usable, but without\n  codebase context) without a VCS connection.\n- `NEVER_GATED_ROUTE_KEYS` — routes that are never gated on any integration.\n- `INDEX_REQUIRED_ROUTE_KEYS`, `INDEX_REQUIRED_BRAINSTORM_MODES`,\n  `CREATE_DOC_CODEBASE_CONTEXT_DOC_TYPES`, `CREATE_DOC_WARN_DOC_TYPES` — the\n  conditional \"requires a successful code index\" dimension.\n- The resolver helpers `get_required_vcs_operation()`, `get_warn_vcs_operation()`,\n  and `requires_successful_index()` are the authoritative functions that decide a\n  case. The capability report is derived from these; this catalog explains them.\n\n## Reading the capability report\n\nEach tool entry the server returns has the exact shape\n`{tool, effect, missing, semantics}`:\n\n- **`effect`**\n  - **`BLOCK`** — the tool is **unavailable** until every listed dependency is\n    met. It will refuse to run without them.\n  - **`DEGRADE`** — the tool is **usable right now**, but **without codebase\n    context** (it cannot ground its output in your repository). Connecting the\n    listed dependency upgrades it from \"works blind\" to \"works with full context\".\n    A `DEGRADE` tool is never \"failed\".\n- **`missing`** — the server-computed dependency identifiers still needed:\n  integration ids such as `github_app` / `vcs_access_token`, and the synthetic\n  `code_index` (a successful repository index).\n- **`semantics`**\n  - **`all_of`** — every id in `missing` is required.\n  - **`any_of`** — the VCS-provider candidates in `missing` are alternatives:\n    **either** `github_app` **or** `vcs_access_token` satisfies the VCS\n    requirement (this is the \"provider unknown\" case). When `code_index` also\n    appears, it remains separately required — `semantics` describes only the VCS\n    provider candidates, and a code index is always mandatory in addition.\n\nThe three readiness dimensions `configured` / `learned` / `indexed` are reported\nindependently. `indexed` may be `true`, `false`, or `null` — a `null` means the\nindex status could not be confirmed and must **not** be read as \"indexed\".\n\n## The integrations\n\n| Integration id | What it is | What it unlocks |\n| --- | --- | --- |\n| `jira` | Jira API access | Ticket reads/writes, estimation and review automations, status transitions. |\n| `github_app` | GitHub App installation | Pull requests, code review, and private-repo parsing on GitHub projects. |\n| `vcs_access_token` | VCS access token | Pull requests, code review, and private-repo parsing on Bitbucket projects. |\n| `vcs_webhook` | VCS webhook secret | Merge webhooks and CI follow-up triggers. |\n| `code_index` | A successful repository index | Codebase-grounded planning, architecture, reimplementation, and technical/discovery brainstorms. Produced by `/parse-repository`. |\n\nA project's `github_app` **or** `vcs_access_token` provides the VCS connection;\nwhich one applies depends on the project's version-control system. When the\nproject's provider is unknown, either credential satisfies the requirement — the\nreport expresses that as `semantics: any_of`.\n\n## The gates, by capability\n\n### Pull requests and CI (BLOCK on VCS)\n\nTools like `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, and\n`materialize_fresh_base` are **unavailable** (`BLOCK`) until a VCS connection is\nconfigured. They act directly on the version-control host, so without a\nconnection there is nothing for them to talk to.\n\n### Repository indexing and maps (BLOCK on VCS)\n\n`parse_repository` and `regenerate_directory_map` need a VCS connection to read\nthe repository. They **BLOCK** until VCS is connected.\n\n### Codebase-grounded generation (BLOCK on VCS **and** a code index)\n\nPlanning and architecture tools — `generate_plan_direct`,\n`generate_architecture_direct`, `request_reimplement_context`,\n`code_writer_generate_plan`, `code_writer_generate_architecture`, and\n`create_doc` for **TDD** / **architecture** documents — ground their output in\nyour indexed codebase. They **BLOCK** until BOTH a VCS connection AND a\nsuccessful code index exist (`all_of`, with `code_index` in `missing`).\n\n### Brainstorms (BLOCK on a code index, mode-dependent)\n\n`request_brainstorm` in **technical** or **discovery** mode searches your indexed\ncodebase, so it **BLOCK**s on `code_index`. **Design**-mode brainstorming never\nqueries the index and is never gated.\n\n### Document generation that DEGRADEs (usable without codebase context)\n\nTools like `generate_prd_direct`, `generate_fsd_direct`,\n`code_writer_generate_fsd`, `generate_clarifying_questions_direct`,\n`generate_ticket_critique_direct`, `generate_ticket_review_direct`, and\n`create_doc` for **PRD** / **FSD** documents **DEGRADE** rather than block: they\nrun today from the ticket alone, and connecting VCS simply lets them ground their\noutput in your codebase. They always appear under \"Tools you can use now\", with a\nreduced-context caveat when the VCS connection is missing.\n\n### Never gated\n\nSetup and bootstrap tools (`ping`, `config_field`, `get_install_manifest`,\n`apply_install_manifest`, `get_my_role`, `persist_routing_credential`,\n`get_docs_dir`, and the bootstrap-invite exchange) are always available — they\nare how you configure everything else.\n"
+};

package/build/executor/base-branch.js

@@ -0,0 +1,50 @@
+/**
+ * Per-job base-branch resolution (BAPI-586).
+ *
+ * The executor has one global `--base-branch` (`ExecutorOptions.baseBranch`,
+ * default `main`), but Epic Conductor runs can be based on a custom branch
+ * (e.g. `develop`, `release/2026.07`) and multi-repository executors may serve
+ * repos with different bases. This helper makes the persisted RUN base
+ * (`job.payload.base_branch`) authoritative for each job while keeping the CLI
+ * value as a legacy fallback.
+ *
+ * A malformed present value fails CLOSED (contract error) rather than silently
+ * falling back — a wrong base is exactly the BAPI-586 defect. An OMITTED value
+ * (legacy / older-Conductor jobs) degrades gracefully to the CLI base.
+ */
+import { validateBranchName } from "../base-ref.js";
+/**
+ * Resolve the effective logical base branch for one executor job.
+ *
+ * - `payload.base_branch` ABSENT (`undefined`) → legacy job → `fallbackBaseBranch`.
+ * - present and a valid branch name → authoritative for this job, even when it
+ *   differs from the executor-wide `--base-branch`.
+ * - present but malformed (`null`, non-string, empty/whitespace, `..`, `.lock`,
+ *   control chars, leading `-`) → contract failure. The diagnostic names the
+ *   base-branch contract WITHOUT echoing arbitrary payload contents.
+ */
+export function resolveExecutorJobBaseBranch(job, fallbackBaseBranch) {
+    const payload = job.payload;
+    const raw = payload && typeof payload === "object"
+        ? payload.base_branch
+        : undefined;
+    // Omitted field: legacy / older-Conductor job → CLI fallback (backward compat).
+    if (raw === undefined) {
+        return { ok: true, baseBranch: fallbackBaseBranch };
+    }
+    // Present but not a string (null, number, object, …): fail closed, no echo.
+    if (typeof raw !== "string") {
+        return {
+            ok: false,
+            error: "job payload base_branch is present but is not a string branch name.",
+        };
+    }
+    const validationError = validateBranchName(raw);
+    if (validationError) {
+        return {
+            ok: false,
+            error: `job payload base_branch is not a valid branch name: ${validationError}`,
+        };
+    }
+    return { ok: true, baseBranch: raw };
+}

package/build/executor/env.js

@@ -8,6 +8,7 @@
  * keys — it never copies arbitrary `process.env`, so credentials/tokens/headers
  * cannot leak into the spawned `claude` process.
  */
+import { PR_BASE_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 /** Non-secret operational keys forwarded to the worker when present. */
 const ALLOWED_ENV_KEYS = [
     "PATH",
@@ -63,8 +64,15 @@ export function isExecutorEnvKeyAllowed(key) {
  * anyway, and the delay was observed causing a worker to background the push and
  * exit before it landed. `BAPI_CONDUCTOR_*` identity keys remain intentionally
  * absent from the worker env (TDD §7) — this literal does not change that.
+ *
+ * BAPI-586: when `effectiveBaseBranch` is provided (the validated run base for
+ * this job), it is injected as `BAPI_BASE_BRANCH` so the worker can run
+ * `gh pr create --base "$BAPI_BASE_BRANCH"` deterministically. It is set from the
+ * EXPLICIT job value, NOT copied from `parentEnv` (`BAPI_BASE_BRANCH` is not in
+ * the allowlist), so any inherited value cannot override the run base and no
+ * unrelated `BAPI_*` / secret value can leak in via this key.
  */
-export function buildExecutorWorkerEnv(parentEnv) {
+export function buildExecutorWorkerEnv(parentEnv, effectiveBaseBranch) {
     const env = {};
     for (const key of ALLOWED_ENV_KEYS) {
         if (!isExecutorEnvKeyAllowed(key))
@@ -75,5 +83,8 @@ export function buildExecutorWorkerEnv(parentEnv) {
         }
     }
     env.BRIDGE_SKIP_PREPUSH = "1";
+    if (typeof effectiveBaseBranch === "string" && effectiveBaseBranch.length > 0) {
+        env[PR_BASE_BRANCH_ENV_VAR] = effectiveBaseBranch;
+    }
     return env;
 }

package/build/executor/job-errors.js

@@ -3,6 +3,7 @@ export const MissingVerdictArtifact = "MissingVerdictArtifact";
 export const WorktreeLostBeforePush = "WorktreeLostBeforePush";
 export const BranchMismatch = "BranchMismatch";
 export const WorkerFinalizationMissingRemoteBranchAndPr = "WorkerFinalizationMissingRemoteBranchAndPr";
+export const WorkerFinalizationPrBaseMismatch = "WorkerFinalizationPrBaseMismatch";
 /** Bound a failure message so no unbounded/secret-bearing text is posted. */
 const ERROR_MESSAGE_MAX_CHARS = 300;
 /**

package/build/executor/job-runner.js

@@ -30,9 +30,11 @@ import { isVerdictJobType, readVerdictArtifact } from "./verdict-artifact.js";
 import { createWorkerLogTee, closeWorkerLogTee, teeAsyncIterable, } from "./worker-log.js";
 import { registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
 import { executorViewerTabsEnabled, openExecutorViewerTab } from "./viewer-tabs.js";
-import { isRecoveryJobType, isSpawnJobType } from "./job-types.js";
+import { isImplementationStyleJobType, isRecoveryJobType, isSpawnJobType } from "./job-types.js";
+import { resolveExecutorJobBaseBranch } from "./base-branch.js";
 import { validateWorkerFinalization } from "./worker-finalization.js";
 import { ensureExecutorWorktree } from "./worktree.js";
+import { buildPrBaseContractLaunchInstruction } from "../pr-base-contract.js";
 import { buildClaudeExecutorArgv, CLAUDE_EXECUTABLE, resolveExecutorModelAlias, resolveExecutorPrompt, } from "./worker-command.js";
 import { collectGitTelemetry } from "./observation.js";
 /** Default runtime for the no-op smoke process (ms). */
@@ -553,11 +555,37 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
     }
 }
 async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams) {
+    // --- Per-job base branch (BAPI-586) ----------------------------------
+    // Resolve the effective logical base BEFORE any side effect: the persisted
+    // run base (`payload.base_branch`) is authoritative, falling back to the
+    // executor CLI base for legacy jobs. A present-but-malformed value fails
+    // CLOSED with `ContractError.BaseBranch` and never spawns. The resulting
+    // job-scoped options carry that base through worktree seeding, prompt
+    // rendering, deny layer, telemetry, env, and finalization so they cannot
+    // disagree about the base.
+    const baseResolution = resolveExecutorJobBaseBranch(job, options.baseBranch);
+    if (!baseResolution.ok) {
+        await httpClient.fail(job, {
+            error_kind: "ContractError.BaseBranch",
+            error_message: baseResolution.error,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "base_branch_contract" };
+    }
+    const effectiveBaseBranch = baseResolution.baseBranch;
+    const jobOptions = { ...options, baseBranch: effectiveBaseBranch };
     // --- Worktree + prompt (resume pre-spawn protocol or standard) -------
-    const prep = await prepareSpawn(job, httpClient, options, deps, seams);
+    const prep = await prepareSpawn(job, httpClient, jobOptions, deps, seams);
     if (!prep.ok)
         return prep.result;
-    const { worktreePath, branch, prompt } = prep;
+    const { worktreePath, branch } = prep;
+    // BAPI-586: PR-producing spawn jobs (implement/resume/remediate/ci_fix/rebase)
+    // are told to open the PR against the injected run base. Verdict-only
+    // `spec_review` produces no PR, so it is excluded from the instruction while
+    // still using the pinned base for its fresh worktree.
+    const prompt = isImplementationStyleJobType(job.job_type)
+        ? `${prep.prompt} ${buildPrBaseContractLaunchInstruction()}`
+        : prep.prompt;
     // --- Timeout contract ------------------------------------------------
     const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
     if (!timeout.ok) {
@@ -569,7 +597,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
         return { status: "failed", reason: "timeout_contract" };
     }
     // --- Deny layer (fail-open) ------------------------------------------
-    const deny = await provisionExecutorDenyLayer(worktreePath, { baseBranch: options.baseBranch }, {
+    const deny = await provisionExecutorDenyLayer(worktreePath, { baseBranch: effectiveBaseBranch }, {
         readFile: deps.readFile,
         writeFile: deps.writeFile,
         mkdir: deps.mkdir,
@@ -643,7 +671,9 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
     // --- Spawn -----------------------------------------------------------
     const alias = resolveExecutorModelAlias(job.payload);
     const argv = buildClaudeExecutorArgv(prompt, alias);
-    const env = buildExecutorWorkerEnv(deps.env);
+    // BAPI-586: inject the validated run base as BAPI_BASE_BRANCH so the worker
+    // can target it via `gh pr create --base "$BAPI_BASE_BRANCH"`.
+    const env = buildExecutorWorkerEnv(deps.env, effectiveBaseBranch);
     let proc;
     try {
         proc = deps.spawnProcess(CLAUDE_EXECUTABLE, argv, { cwd: worktreePath, env });
@@ -666,11 +696,11 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
             stderr: proc.stderr ? teeAsyncIterable(proc.stderr, tee, "stderr") : null,
         }
         : proc;
-    const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, options.baseBranch);
+    const collectTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
     const procResult = await superviseProcess({
         job,
         httpClient,
-        options,
+        options: jobOptions,
         deps,
         ownership,
         observation,
@@ -765,6 +795,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
             result,
             runCommand: deps.runCommand,
             headSha: git.last_commit_sha,
+            expectedBaseBranch: effectiveBaseBranch,
         });
         if (!finalization.ok) {
             await finalizeRegistry();

package/build/executor/test-clock.js

@@ -28,7 +28,12 @@ export class VirtualClock {
     }
 }
 async function flushMicrotasks() {
-    for (let i = 0; i < 12; i++)
+    // BAPI-586: the fresh executor worktree path now awaits a `git fetch` +
+    // `git rev-parse` (base pin) and a post-create head verification BEFORE the
+    // worker spawn, adding several microtask turns. Drain generously so a
+    // `tickUntil` flush still reaches the spawn/exit in one pass (draining an
+    // already-empty queue is a harmless no-op).
+    for (let i = 0; i < 64; i++)
         await Promise.resolve();
 }
 /** A controllable fake owned process for `implement` spawn tests. */

package/build/executor/worker-finalization.js

@@ -23,7 +23,7 @@
  * branch tip SHA against the worker's own HEAD commit (`headSha`, from git
  * telemetry) whenever that comparison is available.
  */
-import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr } from "./job-errors.js";
+import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr, WorkerFinalizationPrBaseMismatch, } from "./job-errors.js";
 import { isImplementationStyleJobType } from "./job-types.js";
 /** Bounded settling re-check defaults for the authoritative origin-tip lookup. */
 const DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS = 3;
@@ -111,6 +111,66 @@ async function resolveOriginBranchShaForFinalization(runCommand, worktreePath, b
     }
     return remoteSha;
 }
+/**
+ * BAPI-586: resolve the base branch of the PR for `branch` via `gh pr view`.
+ * Fail-open on any unavailability (gh missing, non-zero exit, unparseable JSON)
+ * → `{ found: false }`, so a wrong-base guard never blocks a job on transport
+ * failure; the reconciliation observation (epic-runtime) is the second layer.
+ * When a PR IS visible, `baseRef` is the trimmed `baseRefName`, or null if that
+ * field is absent/non-string (which the caller treats as a fail-closed mismatch —
+ * missing base evidence is never a match). Never copies raw stderr.
+ */
+async function resolvePrBaseRef(runCommand, worktreePath, branch) {
+    const args = ["pr", "view"];
+    if (branch)
+        args.push(branch);
+    args.push("--json", "number,baseRefName");
+    let result;
+    try {
+        result = await runCommand("gh", args, { cwd: worktreePath });
+    }
+    catch {
+        return { found: false, baseRef: null };
+    }
+    if (result.exitCode !== 0)
+        return { found: false, baseRef: null };
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return { found: false, baseRef: null };
+    }
+    if (!parsed || typeof parsed !== "object")
+        return { found: false, baseRef: null };
+    const obj = parsed;
+    const prNumber = typeof obj.number === "number" ? obj.number : undefined;
+    const rawBase = obj.baseRefName;
+    const baseRef = typeof rawBase === "string" && rawBase.trim().length > 0 ? rawBase.trim() : null;
+    return { found: true, prNumber, baseRef };
+}
+/**
+ * BAPI-586: bounded, secret-free failure for a PR that targets a branch other
+ * than the run base. Details are limited to ticket key, PR number, expected base,
+ * and actual base (all public identifiers). The operator guidance names cherry-pick
+ * rebuild as the remedy and explicitly warns against a GitHub-UI retarget (a branch
+ * built on a squash-merged dependency goes CONFLICTING when retargeted). This guard
+ * is OBSERVATIONAL: it performs no `gh pr edit`, reset, force-push, or branch
+ * reconstruction.
+ */
+function prBaseMismatchFailure(job, prNumber, expectedBase, actualBase) {
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    const prLabel = typeof prNumber === "number" ? `PR #${prNumber}` : "its PR";
+    return {
+        error_kind: WorkerFinalizationPrBaseMismatch,
+        error_message: `${label} opened ${prLabel} against base '${actualBase}', but the run base is '${expectedBase}'. ` +
+            `A PR that does not target '${expectedBase}' never triggers code review and would strand the ticket. ` +
+            `Recovery: rebuild the feature branch from a fresh origin/${expectedBase} and cherry-pick only this ` +
+            `ticket's own commits, then force-push. Do NOT merely retarget the PR base in the GitHub UI — a branch ` +
+            `built on a squash-merged dependency goes CONFLICTING when retargeted.`,
+        classification: "crashed",
+    };
+}
 function missingBranchAndPrFailure(job, detail) {
     const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
     return {
@@ -129,6 +189,33 @@ export async function validateWorkerFinalization(input) {
     if (!isImplementationStyleJobType(job.job_type)) {
         return { ok: true };
     }
+    // BAPI-586: a wrong-base PR (opened against a dependency's feature branch or the
+    // repo default instead of the run base) never fires `claude-review.yml` and
+    // strands the ticket at `code_review`. When the run base is known, query the
+    // PR's `baseRefName` and fail loud on any mismatch BEFORE accepting the clean
+    // exit — even when a `pr_url` is present (a PR existing is not proof of a
+    // correct base). Fail-open when no PR is visible (gh unavailable / no PR):
+    // reconciliation is the backstop. A PR with absent/malformed base data is a
+    // fail-CLOSED mismatch — missing base evidence is never treated as a match.
+    const expectedBase = typeof input.expectedBaseBranch === "string" ? input.expectedBaseBranch.trim() : "";
+    if (expectedBase) {
+        const branchForPr = typeof branch === "string" ? branch.trim() : "";
+        const prBase = await resolvePrBaseRef(runCommand, worktreePath, branchForPr);
+        if (prBase.found) {
+            if (prBase.baseRef === null) {
+                return {
+                    ok: false,
+                    failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, "(unresolved)"),
+                };
+            }
+            if (prBase.baseRef !== expectedBase) {
+                return {
+                    ok: false,
+                    failure: prBaseMismatchFailure(job, prBase.prNumber, expectedBase, prBase.baseRef),
+                };
+            }
+        }
+    }
     if (extractPrUrl(result)) {
         return { ok: true };
     }

package/build/executor/worktree.js

@@ -6,6 +6,7 @@
  * construction or Worktrunk JSON path parsing here. Per-job create failures are
  * returned as structured job failures (→ `/fail`), never thrown.
  */
+import { fetchAndResolveBaseSha } from "../base-ref.js";
 import { commandSucceeded } from "../start-tickets-prereqs.js";
 import { createWorktreeForTicket } from "../worktree-core.js";
 /**
@@ -95,7 +96,26 @@ export async function ensureExecutorWorktree(job, options, deps, policy = {}) {
         }
         return { ok: false, error: row.error ?? `worktree creation failed for branch '${branch}'` };
     }
-    const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseStartPoint, guardStaleWorktree);
+    // BAPI-586 (fresh dispatch): a fresh implementation-style job must start from
+    // the CURRENT remote base — never a stale local `main`, another local base
+    // branch, or a sibling/dependency feature branch. Fetch `origin/<base>` and
+    // pin its immutable SHA (serialized per repo by the shared helper so
+    // concurrent fresh jobs don't collide on git lock files), then:
+    //   - cut an absent branch directly from that SHA (Worktrunk `-b <sha>`),
+    //   - align a guard-approved pre-existing branch exactly to that SHA, and
+    //   - verify the created worktree head equals that SHA before spawning.
+    // If the refresh fails, fail CLOSED with a structured, secret-free error —
+    // continuing from a cached local base would silently omit a merged dependency
+    // and reproduce the BAPI-586 wrong-base strand.
+    const resolvedBase = await fetchAndResolveBaseSha(deps, options.baseBranch);
+    if (!resolvedBase.ok) {
+        return {
+            ok: false,
+            error: `failed to resolve remote base '${options.baseBranch}' for a fresh worktree: ${resolvedBase.error}`,
+        };
+    }
+    const baseSha = resolvedBase.base_sha;
+    const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseSha, guardStaleWorktree, { alignExistingBranchTo: baseSha, verifyHeadMatches: baseSha });
     if (row.status === "created" && typeof row.path === "string") {
         return { ok: true, worktreePath: row.path, branch };
     }