@bridge_gpt/mcp-server 0.2.20 → 0.2.23

package/CONDUCTOR.md

@@ -3,14 +3,62 @@
 Conductor is the **opt-in, off-by-default** coordination layer for running many
 agent sessions together (epic supervision, inter-agent messaging, done-gate
 evaluation, and conditional auto-merge). A normal `start-tickets` run does **not**
-involve Conductor — you opt in per run with `--conductor`, and epic-tick dispatch
-enables it internally.
+involve Conductor — you opt in per run with `--conductor`.
 
-This document is the reference for Conductor's observability stream, local git
-hooks, and the per-repo done-gate / auto-merge config. For the everyday
-`start-tickets` flags and cross-platform behavior, see
+This document is the reference for Conductor's architecture, epic setup,
+observability stream, local git hooks, and the per-repo done-gate / auto-merge
+config. For the everyday `start-tickets` flags and cross-platform behavior, see
 [README → CLI Subcommands](./README.md#cli-subcommands).
 
+## Epic Conductor v2 — how an epic is actually driven
+
+**The v1 `conductor epic-tick` command is frozen.** It throws
+`EPIC_TICK_V1_FROZEN` on every invocation and advances nothing. There is nothing
+to schedule locally. If you have an epic-tick schedule registered from an earlier
+release, cancel it (`schedule-run cancel --id <id>`) — it is a dead timer.
+`conductor doctor` flags one if it finds it.
+
+v2 splits the old local tick into two halves:
+
+| Half | Where it runs | What it does |
+| --- | --- | --- |
+| **Reconciler** | **Server-side**, on the Bridge API worker dyno, every 30s | Selects every epic run whose status is `active`, evaluates gates, and enqueues executor jobs. Nothing to install or schedule. |
+| **Executor** | **Locally**, on your machine | Polls for jobs, claims them, spawns worker agents, heartbeats. This is the only piece you run. |
+
+```
+npx -y @bridge_gpt/mcp-server executor --repo <name>
+```
+
+The reconciler drives a run purely off `epic_runs.status = 'active'` — there is no
+local schedule, and no per-repo "enable the tick" flag. (An `epic_tick_enabled`
+config field existed briefly and was inert; it has been removed.)
+
+## Setting up an epic
+
+One command creates the run, stores the plan, and approves it:
+
+```
+npx -y @bridge_gpt/mcp-server setup-epic --epic-key BAPI-405 \
+  --plan-file docs/tmp/epic-plans/<slug>/epic-plan.dag.json
+```
+
+The plan sidecar (`epic-plan.dag.json`) is produced by the `decompose-epic`
+pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable
+`depends_on`/edge references, acyclicity) before sending anything, so a malformed
+plan fails legibly instead of as a bare HTTP 400.
+
+It is **idempotent**: re-running it on an epic that already has a live run reuses
+that run rather than minting a second one. Use `--dry-run` to validate a plan and
+preview the calls without mutating anything.
+
+Once the plan is approved the run becomes `active`, the server-side reconciler
+picks it up within ~30s, and your local `executor` starts claiming jobs.
+
+> **A caveat worth knowing before you plan an epic.** Conductor has no
+> merge-conflict handling, and plan-time file-overlap serialization is currently
+> dark (the planner does not yet emit the `touched_files` metadata it needs). If
+> two sibling tickets touch the same files, do not let them dispatch in parallel.
+
 ## Conductor observability (opt-in via `--conductor`, BAPI-394)
 
 Conductor is **off by default** — without `--conductor` no `BAPI_CONDUCTOR_*` env,
@@ -28,7 +76,7 @@ in the env, hook command, or run metadata. Override the gate/supervisor labels w
 `BAPI_CONDUCTOR_GATE_NAME` / `BAPI_CONDUCTOR_SUPERVISOR_MODE`. Inspect the stream
 with `conductor doctor`. Observability is best-effort: a conductor failure never
 blocks or aborts a spawn, and `--dry-run` performs no conductor side effects.
-(Epic-tick dispatch always enables conductor internally, independent of this flag.)
+(Epic dispatch always enables conductor internally, independent of this flag.)
 
 When `--conductor` is set, the spawn boundary also injects
 `BRIDGE_MCP_PROFILE=conductor` so each worker registers the 8 conductor/event/
@@ -61,10 +109,28 @@ hook presence and managed-snippet status **read-only** (a new `git hooks` sectio
 MCP tool drives CI polling and gate evaluation regardless of whether hooks are
 installed.
 
-## `conductor_done_gate` config
+## Supervisor config — where the done gate and auto-merge live
+
+> **These are not config fields.** They used to be `conductor_done_gate` and
+> `conductor_auto_merge_enabled` on the generic config-field route; BAPI-438 moved
+> them onto dedicated supervisor endpoints. Setting them via
+> `PUT /jira/config-field/...` returns **HTTP 400 "Invalid config field"** — that
+> rejection is correct, not a bug. Use the endpoints below.
+
+Two scopes exist for each: a per-repo **project default**, and a per-epic override.
 
-The per-repo `conductor_done_gate` config field (read through the existing
-config-field route) defines the v1 done gate. It supports exactly one condition,
+| Setting | Endpoint (project default) |
+| --- | --- |
+| `done_gate_config` | `PUT /jira/epic-runs/supervisor-setup/defaults/?repo_name=<repo>` |
+| `auto_merge_enabled`, `merge_approval_required` | `PUT /jira/epic-runs/supervisor-config/defaults/?repo_name=<repo>` |
+
+Swap `…/defaults/` for `…/runs/{epic_key}/…` to scope a setting to one epic. The
+matching `GET` on each returns the effective value, with a `source` of `epic`,
+`project_default`, or `none` (nothing configured — fails closed).
+
+### `done_gate_config`
+
+Defines the done gate. It supports exactly one condition,
 `required_ci_checks_green`:
 
 ```json
@@ -81,30 +147,23 @@ config`) only when every listed required check is present, complete, and green f
 the bound PR head SHA. The gate **fails closed**: an unset, disabled (`enabled` not
 strictly `true`), malformed, empty, or unsupported config emits no `gate.met`.
 
-## `conductor_auto_merge_enabled` config (C6 conditional auto-merge)
+### `auto_merge_enabled` (C6 conditional auto-merge)
 
 When a worker's PR meets the done gate (`gate.met`), the supervisor can autonomously
-merge it — but **only** when the repo has explicitly opted in. The per-repo
-`conductor_auto_merge_enabled` config field (read through the same config-field route
-as `conductor_done_gate`) is the opt-in switch:
-
-```json
-{ "enabled": true }
-```
+merge it — but **only** when the repo has explicitly opted in.
+`auto_merge_enabled` on the supervisor-config endpoint is the opt-in switch.
 
-A bare JSON boolean (`true`) is also accepted. **Auto-merge is disabled by default.**
-Behavior:
+**Auto-merge is disabled by default.** Behavior:
 
-- **Disabled / unset / malformed → dry-run.** Anything other than `true` or
-  `{"enabled": true}` — including unset, `false`, `{"enabled": false}`, or any
-  malformed value — fails **closed**: the supervisor records a `merge.dry_run` event
-  and **no PR is ever merged**.
+- **Disabled / unset / unconfigured → dry-run.** Anything other than an explicit
+  `true` — including a repo with no supervisor config at all (`source: "none"`) —
+  fails **closed**: the supervisor records a `merge.dry_run` event and **no PR is
+  ever merged**.
 - **Enabled → autonomous merge** when the gate is met and the deterministic guards
   pass.
-- **Kill-switch.** Set `conductor_auto_merge_enabled` to `false` or remove the field
-  to immediately stop autonomous merges. The protected merge endpoint
-  **independently re-enforces** the flag, so even a conductor that calls it cannot
-  merge while the flag is off.
+- **Kill-switch.** Set `auto_merge_enabled` to `false` to immediately stop
+  autonomous merges. The protected merge endpoint **independently re-enforces** the
+  flag, so even a conductor that calls it cannot merge while the flag is off.
 
 Merge authority is **deterministic code, never an LLM**. The deterministic guards,
 all bound to **PR number + expected head SHA (never a branch name)**:

package/README.md

@@ -37,6 +37,17 @@ store, and opens a fresh agent session to finish setup (`/install-bridge` then
 API web UI **Security** page) and a **repo name** — everything else is derived. Add
 `--dry-run` to preview every step without writing, pinging, or spawning anything.
 
+**Were you sent a bootstrap invite?** Then you don't need an API key or the web UI
+at all — run the command your operator gave you:
+
+```bash
+npx -y @bridge_gpt/mcp-server@latest install-bridge --invite
+```
+
+That one-liner is deliberately **secret-free**: the CLI prompts for the bootstrap
+invite token with **echo suppressed**, and sends it only in the request body. It
+creates your project and mints your own admin API key in a single command.
+
 To upgrade later, run:
 
 ```bash
@@ -76,19 +87,55 @@ derived). Resolution order:
 - **API key:** `--api-key <key>` → `BAPI_API_KEY` env → an interactive (no-echo)
   prompt. Generate one first on the Bridge API web UI **Security** page (see
   [Generate an API Key](#2-generate-an-api-key)); the command consumes a key, it
-  never mints one. The key is **never printed or logged**.
+  never mints one — **`--invite` is the one exception** (below). The key is
+  **never printed or logged**.
 - **Repo name:** `--repo <name>` → `BAPI_REPO_NAME` env → an inferred default you
   confirm interactively. It MUST match the server-side repository registration.
 
+#### Bootstrap-invite onboarding (`--invite`)
+
+With a **bootstrap invite** there is no pre-existing key and no web UI: this is the
+one mode where `install-bridge` **creates** the project and its first admin key
+instead of consuming one. Run `install-bridge --invite` and it:
+
+1. **Prompts for the bootstrap invite token** with echo suppressed (the default —
+   see below).
+2. **Generates your `key_secret`** (32 CSPRNG bytes) and **fsyncs it locally**
+   *before* contacting the server. If that write fails the run aborts and the
+   invite is **not** spent.
+3. **Redeems the invite** — `POST /setup/bootstrap` with the token, repo name, and
+   `key_secret` in the **body** — which creates the project and mints your admin
+   key. (This replaces the connectivity ping: there is no key to ping with yet.)
+4. **Verifies the newly-minted key**, then writes the per-host MCP config.
+5. **Promotes the credential** to `bapi:<repo>` and **opens the agent session** —
+   the same Steps 3–5 as the normal flow.
+
+Because the locally-saved `key_secret` is the only proof that can replay a
+redemption, a re-run after a network failure is safe: it re-sends the *same* secret
+and gets back the *same* project and key. If the repo name you chose is already
+taken (names are globally unique) the server rolls back — your invite is untouched —
+and the CLI asks for a different name and retries with the same token.
+
+**The delivered one-liner is secret-free, by design.** "A copy/paste one-liner" and
+"the token never touches shell history" are contradictory, so the token is *not* in
+the command: the CLI asks for it, and it travels only in the request body.
+`--invite <token>`, `--invite=<token>`, and `BAPI_INVITE` still work for
+**scripting only** — and both forms **expose the token to your shell history and to
+the process list**. Prefer the prompt.
+
 Useful flags:
 
 - `--dry-run` — preview every step (scaffold targets, config files and keys with
   the key value **redacted**, the ping target, the credential store target, and
   the exact agent spawn command) without writing, pinging, or spawning anything.
-- `--force` — overwrite an existing real `BAPI_API_KEY` in a host config without
-  prompting (re-running is otherwise non-destructive).
+  With `--invite` it also never calls the exchange endpoint and never generates or
+  stores a secret.
+- `--force` — overwrite an existing real `BAPI_API_KEY` in a host config, or in the
+  credential store, without prompting (re-running is otherwise non-destructive).
 - `--agent claude|cursor-agent` — which agent to launch for the agentic remainder
   (default `claude`).
+- `--invite [token]` — redeem a bootstrap invite (mutually exclusive with
+  `--api-key`). Omit the value to get the hidden prompt.
 
 That's it — once `install-bridge` finishes you're connected. If you prefer to do
 it by hand (or just want to understand each step), the manual flow below does the
@@ -276,7 +323,14 @@ These features are useful for most tickets.
 - **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
 - **When it's useful:** (Implementation | Automation) When you're ready to start building one or more refined tickets concurrently.
 - **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).
-- **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default.
+- **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default · `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs (default `implement`, byte-identical to today; `review-and-implement` runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session) · `--rounds=1|2` review-only, forwarded to the review phase, valid only with `--workflow review-and-implement`.
+
+**2b. Review and Start**
+- **What it does:** Spawns one worktree per ticket, each running review then (after a per-ticket human proceed/halt gate) implementation — the chained `review → gate → implement` composition.
+- **When it's useful:** (Refinement | Implementation | Automation) The **recommended front door** for "review these tickets, then implement the ones that pass," starting from existing ticket keys (unlike `/full-automation`, which only accepts an idea).
+- **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).
+- **Flags:** `--auto` a single chain-level flag that auto-approves both the review and the implementation phase of every spawned session · `--rounds=1|2` forwarded to the review phase · `--agent`, `--base-branch`, `--max-parallel`, `--dry-run` mirror `/start-tickets`.
+- Under the hood, this is a thin shim over `start-tickets --workflow review-and-implement <KEYS>` — the lower-level launcher seam documented above; the halt-gate decision logic lives in the spawned `/review-and-implement` session, never in this command or the CLI.
 
 **3. Brainstorm**
 - **What it does:** Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of three modes, selected via `mode`: **`technical`** (default — implementation/architecture approaches), **`design`** (UI/UX and visual direction), or **`discovery`** (stakeholder discovery questions for early/vague tasks, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`). Discovery needs no extra configuration. The legacy boolean `design=true` still works and maps to `mode: "design"`.
@@ -511,7 +565,7 @@ Beyond `--init` / `--upgrade`, the package ships operational subcommands of the
 
 ### `start-tickets`
 
-Spawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`.
+Spawns one Worktrunk worktree + selected-agent session per Jira ticket and backs the `/start-tickets` slash command. The agent defaults to **Claude Code** (`claude`) and is configurable via `--agent`. For existing ticket keys, `/review-and-start` (see [Usage Documentation → Review and Start](#tier-1--regularly-useful)) is the recommended enriched front door over this CLI's `--workflow review-and-implement` seam; using the CLI directly (below) remains the advanced/lower-level path.
 
 ```
 npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
@@ -520,6 +574,8 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | Flag | Default | Meaning |
 |---|---|---|
 | `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
+| `--workflow implement\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `implement` is byte-identical to today's `/implement-ticket <KEY> [--auto]`. `review-and-implement` spawns `/review-and-implement <KEY> [--auto] [--rounds=<n>]`, which runs `/review-ticket` then, after a per-ticket halt gate, `/implement-ticket` in the same session. `--auto` applies to the selected workflow as a whole. |
+| `--rounds 1\|2` | unset | Review round count forwarded to the review phase. Review-only — valid only with `--workflow review-and-implement`. |
 | `--terminal terminal\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |
 | `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |
 | `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |
@@ -557,9 +613,27 @@ npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
 
 It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
 
+### `setup-epic`
+
+Bootstraps an Epic Conductor v2 run in one command — creates the epic run, stores the plan DAG, and approves it:
+
+```
+npx -y @bridge_gpt/mcp-server setup-epic --epic-key <KEY> --plan-file <path-to-epic-plan.dag.json>
+```
+
+The plan sidecar is produced by the `decompose-epic` pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable dependency references, acyclicity) before sending anything, so a malformed plan fails legibly instead of as a bare HTTP 400. It is **idempotent**: re-running it on an epic that already has a live run reuses that run rather than minting a second one. `--dry-run` validates and previews the calls without mutating anything; `--json` emits a single machine-readable result object.
+
+Once the plan is approved, the **server-side reconciler** picks the run up within ~30s. To execute claimed jobs on your machine, run `executor`:
+
+```
+npx -y @bridge_gpt/mcp-server executor --repo <name>
+```
+
 ### Conductor (epic & multi-agent orchestration)
 
-Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — `conductor install-git-hooks`, the `conductor_done_gate` and `conductor_auto_merge_enabled` config fields, and the observability stream — lives in **[CONDUCTOR.md](./CONDUCTOR.md)**.
+Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `conductor install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./CONDUCTOR.md)**.
+
+> The v1 `conductor epic-tick` command is **frozen** — it throws on every invocation. There is nothing to schedule locally, and `conductor doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.
 
 ## Custom Pipelines
 

package/build/base-ref.js

@@ -0,0 +1,151 @@
+/**
+ * Shared remote-base resolution (BAPI-586).
+ *
+ * A focused, executor-agnostic helper that BOTH Conductor dispatch paths use to
+ * validate, fetch, and pin the configured remote base commit before creating a
+ * fresh worktree:
+ *
+ *   - the interactive `start-tickets` non-mutating dispatch path
+ *     (`orchestrateStartTickets`), and
+ *   - the Epic Conductor v2 executor fresh worktree path
+ *     (`executor/worktree.ts#ensureExecutorWorktree`).
+ *
+ * Extracted out of the large `start-tickets.ts` CLI module so executor code can
+ * depend on a small, focused module instead of pulling in the whole CLI. The
+ * operation is FETCH-ONLY: it never fast-forwards, resets, or force-moves any
+ * local branch ref — it fetches `origin/<base>` and resolves the fetched tip to
+ * an immutable commit SHA, which becomes Worktrunk's `-b <start-point>`.
+ *
+ * Import direction: this module imports the shared `RunCommand` type from
+ * `start-tickets.js` as a TYPE-ONLY import (erased at runtime) plus the
+ * `commandSucceeded` value from `start-tickets-prereqs.js`. `start-tickets.ts`
+ * imports the VALUES here and re-exports them, so the runtime graph stays
+ * acyclic (mirrors the existing `worktree-core.ts` / prereqs pattern).
+ */
+import path from "path";
+import { commandSucceeded } from "./start-tickets-prereqs.js";
+/**
+ * Returns an error string for an unsafe branch name, or null when valid.
+ *
+ * Rejects names that Git itself refuses (`git check-ref-format`) as well as
+ * injection-shaped inputs, WITHOUT invoking Git: an empty/whitespace-only name,
+ * a leading `-` (which git would parse as a flag, e.g. `--upload-pack=evil`),
+ * ASCII control characters, a `..` sequence, and a `.lock` suffix. Every failure
+ * is a short, secret-free reason string that names only the rule that failed.
+ */
+export function validateBranchName(branch) {
+    if (branch.trim().length === 0)
+        return "branch name must not be empty.";
+    if (branch.length > 255)
+        return "branch name must be 255 characters or fewer.";
+    if (branch.startsWith("-"))
+        return "branch name must not start with '-'.";
+    if (branch.includes(".."))
+        return "branch name must not contain '..'.";
+    if (branch.endsWith(".lock"))
+        return "branch name must not end with '.lock'.";
+    // 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;
+}
+// ---------------------------------------------------------------------------
+// Per-repository fetch serialization
+// ---------------------------------------------------------------------------
+/**
+ * A per-repository async mutex chain. The executor runner fills up to
+ * `maxConcurrent` slots against ONE shared clone, so once a `git fetch` is
+ * introduced on the fresh path, simultaneous fresh jobs would race on
+ * `FETCH_HEAD.lock` / `index.lock`. Serializing fetch-and-resolve per repository
+ * removes that collision while still letting independent repositories proceed
+ * concurrently (the map is keyed per normalized repo path, not one global lock).
+ */
+const repoFetchLocks = new Map();
+/** Normalize a repo working directory into a stable, spelling-independent key. */
+function normalizeRepoKey(cwd) {
+    // `path.resolve` collapses `.`/`..` segments and trailing separators so
+    // different spellings of the same directory share one lock entry.
+    return path.resolve(cwd);
+}
+/**
+ * Run `fn` while holding the per-repository lock. Concurrent calls for the same
+ * normalized repo run strictly one at a time; calls for different repos overlap.
+ * The lock is released and its map entry removed in `finally` — including on a
+ * thrown/failed operation — so a failed fetch never deadlocks later dispatches
+ * or leaks repository keys.
+ */
+async function withRepoFetchLock(repoKey, fn) {
+    const previous = repoFetchLocks.get(repoKey) ?? Promise.resolve();
+    let releaseCurrent;
+    const current = new Promise((resolve) => {
+        releaseCurrent = resolve;
+    });
+    // Later waiters chain on `previous` THEN on our gate, so they cannot start
+    // until we release. `current` only ever resolves, so this chain never rejects.
+    const chained = previous.then(() => current);
+    repoFetchLocks.set(repoKey, chained);
+    await previous.catch(() => { });
+    try {
+        return await fn();
+    }
+    finally {
+        releaseCurrent();
+        // Drop the entry only if no later waiter chained on after us (we are still
+        // the tail). Otherwise the newest waiter owns the key.
+        if (repoFetchLocks.get(repoKey) === chained) {
+            repoFetchLocks.delete(repoKey);
+        }
+    }
+}
+/** Test-only: clear all per-repository fetch locks between tests. */
+export function __resetBaseRefFetchLocksForTests() {
+    repoFetchLocks.clear();
+}
+/**
+ * Validate `baseBranch`, then (serialized per repository) fetch
+ * `origin/<baseBranch>` and resolve the fetched tip to an immutable commit SHA,
+ * WITHOUT ever fast-forwarding or force-moving any local branch ref (no
+ * `git merge --ff-only`, no `git branch --force`, no `git reset`). Pinning the
+ * SHA removes ambiguity and prevents Worktrunk or stale local branch state from
+ * selecting a sibling feature branch when the resulting SHA is passed as
+ * Worktrunk's `-b` start point.
+ *
+ * Validation runs BEFORE the lock is acquired so an injection-shaped ref name is
+ * rejected without any git invocation and without touching the mutex. Both the
+ * `git fetch` and the `git rev-parse` run inside the same per-repository lock so
+ * concurrent fresh jobs cannot collide on git lock files or resolve an unrelated
+ * fetch result. Failures name only the configured branch and the failed
+ * operation — never remote URLs, credentials, raw command arguments, or
+ * unbounded command output.
+ */
+export async function fetchAndResolveBaseSha(deps, baseBranch) {
+    const validationError = validateBranchName(baseBranch);
+    if (validationError) {
+        return { ok: false, error: `Invalid base branch '${baseBranch}': ${validationError}` };
+    }
+    const repoKey = normalizeRepoKey(deps.cwd);
+    return withRepoFetchLock(repoKey, async () => {
+        const fetch = await deps.runCommand("git", ["fetch", "origin", baseBranch], {
+            cwd: deps.cwd,
+        });
+        if (!commandSucceeded(fetch)) {
+            return {
+                ok: false,
+                error: `git fetch origin ${baseBranch} failed. Check your network and 'git remote get-url origin', or pass --no-refresh-base to skip.`,
+            };
+        }
+        const resolve = await deps.runCommand("git", ["rev-parse", "--verify", `origin/${baseBranch}^{commit}`], { cwd: deps.cwd });
+        if (!commandSucceeded(resolve)) {
+            return {
+                ok: false,
+                error: `Failed to resolve origin/${baseBranch} to a commit SHA after fetch (git rev-parse --verify failed).`,
+            };
+        }
+        return { ok: true, base_sha: resolve.stdout.trim() };
+    });
+}