@bridge_gpt/mcp-server 0.2.21 → 0.2.24

package/README.md

@@ -18,7 +18,7 @@ The Bridge MCP is an end-to-end accelerator for shipping code within SFCC, power
 - [Worktree credentials and the `mcp-invoke` shim](#worktree-credentials-and-the-mcp-invoke-shim)
 - [Reference](#reference)
 
-For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./CONDUCTOR.md).
+For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./docs/CONDUCTOR.md).
 
 ## Getting Started
 
@@ -32,10 +32,25 @@ npx -y @bridge_gpt/mcp-server@latest install-bridge
 
 `install-bridge` scaffolds the project, writes your editor's MCP config with real
 values, verifies connectivity, persists your API key to the user-scoped credential
-store, and opens a fresh agent session to finish setup (`/install-bridge` then
-`/learn-repository`). The only inputs are an **API key** (generate one on the Bridge
-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.
+store, and opens a fresh agent session that runs `/install-bridge` to derive and
+apply the remaining config, presents a **capability report** (what you can use now
+and what you'll unlock), and closes by asking whether to index the repository. It
+does **not** automatically run `/learn-repository` or index without your consent —
+both remain available as separate steps. The only inputs are an **API key**
+(generate one on the Bridge 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:
 
@@ -67,8 +82,13 @@ works as a fallback.)
 4. **Persists your key** to the user-scoped credential store
    (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) so shell-spawned
    tooling (e.g. `start-tickets`) can resolve it.
-5. **Opens a fresh agent session** that runs `/install-bridge` (to derive the
-   remaining config fields from your codebase) and then `/learn-repository`.
+5. **Opens a fresh agent session** that runs `/install-bridge` to derive and apply
+   the remaining config fields from your codebase, presents the capability report
+   (Connected / Not yet connected / Tools you can use now / Tools you'll unlock /
+   Recommended next step), and closes with one optional `[Y/n] Index repository
+   now?` question. It does not chain `/learn-repository` and never indexes without
+   consent; run `/learn-repository` and `/parse-repository` yourself when you want
+   them.
 
 The only inputs are an **API key** and a **repo name** (everything else is
 derived). Resolution order:
@@ -76,19 +96,88 @@ 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**.
-- **Repo name:** `--repo <name>` → `BAPI_REPO_NAME` env → an inferred default you
-  confirm interactively. It MUST match the server-side repository registration.
+  never mints one — **`--invite` is the one exception** (below). The key is
+  **never printed or logged**.
+- **Repo name:** `--repo <name>` and `BAPI_REPO_NAME` remain the deterministic
+  short-circuits and compatibility fallbacks — when either is set it is used
+  directly, with no network round-trip. When **neither** is set, a compatible
+  server resolves the unique repository from your existing API key automatically
+  (a read-only lookup), so you don't have to supply it. If the server is older,
+  the key can't be uniquely resolved, or the lookup fails, `install-bridge` falls
+  back to an inferred default you confirm interactively (and requires `--repo`
+  when stdin is non-interactive). Whatever name is used MUST match the
+  server-side repository registration.
+
+#### Self-serve email onboarding (`--email`) — no account, no key, no invite
+
+The primary path for a **first-time user with nothing yet** — no Bridge account,
+no API key, and no pre-issued invite. Run:
+
+```bash
+npx -y @bridge_gpt/mcp-server@latest install-bridge --email you@example.com
+```
+
+`install-bridge` requests a brand-new Bridge workspace for that email, receives an
+invite token, and then feeds it into the **exact same** persist-before-exchange
+bootstrap protocol as `--invite` below — so the project is created and your first
+admin key is minted in one command. The minted token is used internally and **never
+shown**.
+
+The email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a
+**visible** interactive prompt (email is not a secret, so it is echoed as you type —
+unlike the API key and the invite token, which use a hidden prompt). It is still
+**never written to a log line**. No email verification is performed and no message
+is sent to the address — it only labels your new workspace. `--email` is mutually
+exclusive with `--api-key` and `--invite`.
+
+#### Bootstrap-invite onboarding (`--invite`)
+
+With a **bootstrap invite** you were already given, there is no pre-existing key and
+no web UI: like `--email` above, this mode **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`).
+- `--email <addr>` — self-serve signup: create a new workspace from just an email
+  (mutually exclusive with `--api-key` and `--invite`). Falls back to
+  `BAPI_SIGNUP_EMAIL`, then a visible prompt. Visible input, not a secret; still
+  never logged.
+- `--invite [token]` — redeem a bootstrap invite (mutually exclusive with
+  `--api-key` and `--email`). 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 +365,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"`.
@@ -448,10 +544,12 @@ Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-exp
 
 **v1 is read-only and developer-sandbox-only** — no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.
 
+For a step-by-step OCAPI client setup guide (including the Business Manager permissions grant), see [docs/install/sfcc-integration.md](./docs/install/sfcc-integration.md).
+
 <details>
 <summary><strong>Setup</strong></summary>
 
-The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The seven read tools must be enabled with a profile (step 3).
+The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The read tools, the write tools, and `sfcc_log_query` must be enabled with a profile (step 3). Changing `BRIDGE_MCP_PROFILE` requires an MCP client restart.
 
 **Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).
 
@@ -486,7 +584,7 @@ Without this, only the diagnostic tools are registered.
 All SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.
 
 **Diagnostics** (always available, no profile needed)
-- `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, and AM token acquisition.
+- `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.
 - `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).
 
 **System object model** (needs the `sfcc` profile)
@@ -505,13 +603,21 @@ All SFCC tools are read-only and target a developer sandbox. Oversized responses
 - `site_preference_search` — search/filter preferences within a group.
 - `site_preference_values_set` — **write** (sandbox only): set custom preference values via `PATCH /site_preferences/preference_groups/{group}/sandbox` with a flat map of `c_`-prefixed ids to string/number/boolean/string[] values. A bad group returns 404 `CustomPreferenceGroupNotFoundException`; echoes grant JSON on 403.
 
+**On-demand log query** (needs the `sfcc` profile)
+- `sfcc_log_query` — query redacted, filtered SFCC logs on demand. `environment` and `time_range` (`start`/`end`) are **required** — production, "all environments", and an open-ended period are never inferred. The tool calls a Bridge backend endpoint that runs the pull → redaction → filter pipeline server-side and returns scoped, redacted findings; **WebDAV credentials, retrieval, redaction, and filtering all stay server-side and single-sourced.** It holds no credentials of its own.
+  - **Guardrails.** Selection is bounded by log-file `prefixes` (max 5), the time range, a scanned-entry cap (`max_entries`, ≤ 2000), a finding cap, and a per-snippet length cap. High-volume prefix classes (`info`, `jobs`, `debug`, `customdebug`) impose a **stricter 6-hour** max range (vs. 24h for the error class) because `info-*` runs ~1 MB/day versus `error-*` at ~13 KB median — a wide window over a high-volume prefix is **rejected**, never silently narrowed.
+  - **Response order.** Resolved scope (`environment`, `time_range`, `applied_prefixes`) and cap `status` first, redacted `findings` second, retrieval/truncation `metadata` last.
+  - **Statuses & errors.** `ready`, `no_matching_findings`, `results_truncated`; plus `VALIDATION_ERROR` (bad/oversized scope, caught before any network call), `NOT_CONFIGURED` (503 — the log capability isn't set up; run `sfcc_setup_status`, whose step 6 reports it), and `BAD_GATEWAY`/`SERVICE_UNAVAILABLE` on a retrieval/backend failure.
+  - **Auth is separate from OCAPI.** Log retrieval uses **HTTP Basic auth** — a Business Manager username + a **40-character WebDAV access key** — *not* the OCAPI Account Manager OAuth token the other SFCC tools use. A valid AM bearer token 401s on `/Logs`. `sfcc_setup_status` step 5 (AM/OCAPI token) and step 6 (WebDAV log access) are independent: one can be green while the other is not.
+  - **Local / air-gapped fallback.** The primary path above is the only path this tool takes. For air-gapped development, the documented fallback is Salesforce's own **`@salesforce/b2c-dx-mcp`** (`logs_list_files`, configured from `dw.json`) — it is vendor-maintained and reads log files over WebDAV, so it is strictly less work than shelling the B2C CLI (`b2c logs get --since <window> --search <q> --json`). It is **not** the primary path because its credentials live client-side and its output has **not** passed Bridge's redaction/filter. If you use it, its output must be treated as raw: route it back through the same server-side Python `LogSource` composition and `RedactionPort`/T3 filter workflow — never paste or relay unredacted `b2c-dx-mcp` or CLI output to an LLM.
+
 ## CLI Subcommands
 
 Beyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) — so they travel with the package to every consumer. See [Usage Documentation → Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.
 
 ### `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 +626,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) |
@@ -537,7 +645,7 @@ 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`.
 
-**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
+**Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./docs/CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
 
 **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.
 
@@ -557,9 +665,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](./docs/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() };
+    });
+}