@bridge_gpt/mcp-server 0.2.52 → 0.2.54

package/README.md

@@ -352,7 +352,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.52", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -374,7 +374,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.52", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -396,7 +396,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.52", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -421,7 +421,7 @@ you select `copilot-cli`; the shape below is what it produces.
     "bridge": {
       "type": "local",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.52", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
       "tools": ["*"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
@@ -445,7 +445,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.52", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -464,7 +464,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.52", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.54", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -570,7 +570,7 @@ The tools worth knowing for most tickets.
 **1. Review Ticket**
 - **What it does:** Runs a full quality review of a ticket: clarifying questions and a critique plus an alternate-model second opinion, then evaluates the findings and produces a decision page for accepting or rejecting them.
 - **When it's useful:** (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.
-- **How to use it:** `/review-ticket BAPI-123` (command only — "review" as free text is easily mistaken for a freehand agent review). For several tickets at once, `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket and reviews them in parallel with no worktrees; every `/review-ticket` flag applies, and `--review KEY=auto,rounds=N` sets per-ticket overrides.
+- **How to use it:** `/review-tickets BAPI-123` (command only — "review" as free text is easily mistaken for a freehand agent review). A single key reviews inline in the current session — no terminal tab, no worktree. For several tickets at once, `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket and reviews them in parallel with no worktrees; every review flag applies, and `--review KEY=auto,rounds=N` sets per-ticket overrides.
 - **Flags:** `--auto` auto-accept findings and skip the approval gates · `--rounds=1` a cheaper single-pass review that still evaluates findings and captures decisions · `--rounds=2` force the full second-opinion review · omit `--rounds` to let the difficulty-adaptive review policy decide.
 
 **2. Start Tickets**
@@ -581,7 +581,7 @@ The tools worth knowing for most tickets.
 
 **3. Review and Start**
 - **What it does:** Spawns one worktree per ticket; each session reviews the ticket inline and, after a per-ticket proceed/halt gate, hands off to a **fresh implementation session** that reuses the same worktree — review and implementation run in two separate agent contexts, not one shared session.
-- **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).
+- **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 `/idea-to-pr`, 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` 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`.
 
@@ -637,6 +637,12 @@ Good to know, but not needed every day.
 - **How to use it:** Ask your agent — "Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."
 - **Flags:** `provider` openai (`gpt-image-2`) / gemini (Imagen, which adds an invisible SynthID watermark) · `quality` low (default, cheapest) / medium / high · `size` 1024x1024 / 1024x1536 / 1536x1024. The image is saved to `BAPI_DOCS_DIR/images/` and also returned inline.
 
+**6. Create Decision Page**
+- **What it does:** Turns open decisions from the current conversation into an interactive HTML decision page, then folds the submitted answers back into the conversation.
+- **When it's useful:** (Refinement) Use it whenever a conversation has accumulated more open choices than are comfortable to settle in prose — not for a single simple question, which is faster to just ask directly.
+- **How to use it:** `/create-decision-page <topic or open questions>` — e.g. *"how we handle rate limiting"* — or leave it empty to frame the open choices already raised earlier in the conversation.
+- **Flags:** None.
+
 ### Now and then
 
 Useful once in a while.
@@ -688,11 +694,35 @@ Useful once in a while.
 - **When it's useful:** (Architecture | Refinement) When you need a sizing pass across an epic, or across a set of tickets you name explicitly.
 - **How to use it:** `/estimate-epic BAPI-123`
 - **Flags:** Pass an epic key, or an explicit list of ticket keys to estimate as one group.
+
+**9. Regression Check**
+- **What it does:** Runs the deterministic regression-reviewer (lightweight mode) against a proposed code change and reports its blast radius — which real call-sites, tests, mocks, or config the change does and doesn't account for.
+- **When it's useful:** (Correctness) Before merging a change, to see which real callers, tests, or config it leaves unaccounted for.
+- **How to use it:** `/regression-check` reviews the working tree against `HEAD` by default; `/regression-check --diff main...HEAD` reviews an explicit range.
+- **Flags:** `--diff <range>` review a specific diff/PR range instead of the working tree vs. `HEAD` · `--symbols a,b,c` review a not-yet-diffed planned change by naming its symbols directly.
+
+**10. Scan Test Coverage**
+- **What it does:** Scans recently shipped tickets from git history and reports which features have or could gain integration tests, and which can only be smoke tested.
+- **When it's useful:** (Testing) Periodically, to find recently shipped features still missing integration-test coverage and how each could be smoke tested instead.
+- **How to use it:** `/scan-test-coverage` runs incrementally from the last recorded marker in `docs/test-coverage/STATE.md`.
+- **Flags:** `--since=YYYY-MM-DD` override the window start date · `--full` ignore the marker and use a 6-month lookback · `--limit=N` cap the number of features investigated.
+
+**11. Estimate Ticket**
+- **What it does:** One-ticket shortcut over the existing epic estimation capability: estimates a single Jira ticket via the same `estimate_epic` tool.
+- **When it's useful:** (Estimation) When you want one ticket's estimate without typing out an epic key or an explicit ticket list.
+- **How to use it:** `/estimate-ticket BAPI-123`
+- **Flags:** `--allow-partial` the sole optional flag.
+
+**12. Draft Ticket**
+- **What it does:** Delegates to the Jira Ticket Writer to create only a local Markdown draft — it does not create or update a Jira issue.
+- **When it's useful:** (Refinement) When you want a reviewable local ticket draft before committing to an upload workflow.
+- **How to use it:** `/draft-ticket <description>`
+- **Flags:** None.
 <!-- END GENERATED: mcp-tool-documentation -->
 
 ### Workflow commands
 
-Slash commands that drive several tools at once. Start Tickets, Review and Start, and Explore Ticket are documented above under [Regularly useful](#regularly-useful) — the rest live here.
+Slash commands that drive several tools at once. Start Tickets, Review and Start, and Explore Ticket are documented above under [Regularly useful](#regularly-useful); Create Decision Page is documented above under [Occasionally useful](#occasionally-useful); Regression Check and Scan Test Coverage are documented above under [Now and then](#now-and-then) — the rest live here.
 
 **1. Implement Ticket**
 - **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.
@@ -1060,12 +1090,54 @@ all, because an unknown owner is not the same as a not-ready one. No branch,
 including every error path, ever offers you two paths.
 
 `drive-epic` owns no branch behavior of its own — it forwards `--feature-branch
-<name>` and `--into-base` verbatim to `setup-epic`, which decides the strategy (see
-below). With neither flag, a multi-ticket epic runs on `epic/<KEY>`.
+<name>`, `--into-base`, and `--attended` verbatim to `setup-epic`, which decides
+the strategy and the posture (see below). With none of them, a multi-ticket epic
+runs on `epic/<KEY>`, unattended.
+
+**The composed bring-up is two-phase (BAPI-1102).** With `--plan-file` on a
+repository whose readiness is missing only the runtime facts, one invocation runs,
+in order: the **control plane** (Bridge API server + reconciler, each gated on its
+own readiness), then `setup-epic` to create and approve the run, then **executor
+lanes scoped to that run** with `--epic-run-id <run>`, then the **dead-man
+observer** last, then the ready banner. The order is forced: an executor lane must
+carry an explicit claim scope, and the run it is scoped to does not exist until the
+server is up and `setup-epic` has run.
+
+A composed plane serves **exactly one** run; start a second plane for a second
+epic. If `setup-epic` fails, the control plane is left running and **no executor
+lane is spawned**. If the lanes fail to become ready, the control plane and the
+committed run are both left intact and the observer is not started — nothing is
+rolled back, because a local process that failed to start says nothing about
+whether the run is valid.
+
+"Plane ready" reports **processes**, not dispatchability: if the run cuts an epic
+branch, the reconciler holds ticket dispatch until that branch's index scope
+finishes preparing.
 
 Two conductors is a transitional state. When one is eliminated, `drive-epic` is
 the only thing that changes.
 
+### `plane up` — claim scope is required
+
+`plane up` starts the runtime on its own, and every executor lane it starts needs
+an explicit claim scope:
+
+```
+npx -y @bridge_gpt/mcp-server plane up --epic-run-id <run-id>   # repeatable
+npx -y @bridge_gpt/mcp-server plane up --repo-wide              # or repository-wide
+```
+
+The two are mutually exclusive. Asked to start lanes with neither, `plane up`
+**refuses before spawning anything**, in the executor's own words. That is not a
+new restriction — an executor started with no claim scope has refused to start
+since BAPI-1026 — it is that refusal moved to where it is actionable, instead of
+surfacing as a member crash and a full plane rollback.
+
+`plane status` reports the lifecycle phase (control plane starting/ready, lanes
+starting/ready, observer active, plane ready) and the epic run the plane is bound
+to. `plane down` handles every intermediate phase: it stops the bound run first,
+then signals the recorded process group.
+
 ### `setup-epic`
 
 Bootstraps an Epic Conductor v2 run in one command — creates the epic run, stores the plan DAG, and approves it:
@@ -1088,6 +1160,39 @@ branch, matching plain `start-tickets`.
 > name, or to force a branch for a single-node plan. Passing both is a parse error,
 > refused before any file read, credential resolution, or network call.
 
+**A run that selects an epic branch is created UNATTENDED (BAPI-1102).** Its
+`policy_json` carries `posture: "unattended"` and `v2_auto_merge_enabled: true`, so
+child PRs merge into the epic branch without parking for a human at every gate. The
+**integration PR into the repository base branch stays human-gated.** The run's CI
+gate is stamped **server-side at first approval** — from your repository's declared
+default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
+
+> **Behavior change (BAPI-1102).** Pass `--attended` to restore the previous
+> composition: `base_branch` plus an explicitly requested `--review-policy`, with no
+> posture and no auto-merge authorization. `--into-base`, single-node plans, and
+> branch-silent invocations are **unchanged** — they send no `policy_json` at all,
+> byte for byte as before. A `--policy-file` still supersedes composition entirely;
+> combining `--attended` with a file that declares `posture: "unattended"` is a named
+> refusal rather than a silent winner.
+
+An unattended run has two one-time **repository** prerequisites — consent
+(`unattended_conductor_allowed`) and a verified notify webhook default — plus
+confirmed default-branch review/CI workflows. Each is refused by name **before any
+run row is created** (`target_not_allowed`, `webhook_unverified`,
+`repository_readiness_unconfirmed`), and `drive-epic` readiness and `doctor` both
+list them with their current state. `notify.local_sink` does not satisfy the webhook
+prerequisite.
+
+> **Rollout note.** The client-side default and the server-side admission,
+> stamping, and readiness changes must be released as **one compatible unit**. The
+> new default's shape (`v2_auto_merge_enabled: true` with no `required_checks`) is
+> exactly what the create route refused before BAPI-1102, so shipping the client
+> half alone would 422 every unattended run at `POST /jira/epic-runs/runs`.
+> Deploying only the server half is safe and inert: it narrows two refusals and adds
+> a first-approval stamp, and **rewrites no existing run**. No database migration and
+> no new environment variable is introduced — `config_projects.unattended_conductor_allowed`
+> and `epic_supervisor_setup.done_gate_config` already exist and are read as-is.
+
 Once the plan is approved, the **server-side reconciler** picks the run up within ~30s. To execute claimed jobs on your machine, run `executor`:
 
 ```
@@ -1457,17 +1562,18 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The authoritative tool catalog covers **72 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The authoritative tool catalog covers **75 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping` (its JSON also carries `docs_dir`, `role`, and `customer_type`)
 - **Team & access** — `invite_member` (admin-only; mints a scoped access key for a teammate on an already-configured project — the plaintext key is shown exactly once)
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
 - **Attachments** — `attachment` (operations: `upload`, `download`, `list`)
 - **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/architecture/fsd/prd, where `architecture` is an alias of `tdd`), `request_ticket_review` (writes both `get_clarifying_questions` and `get_ticket_critique`), `request_reimplement_context`/`get_reimplement_context`, `request_council`/`get_council`, `request_deep_research`/`get_deep_research`
+- **Bounded waits** — `wait_for_ticket_review`, `wait_for_ci_checks`. Each call waits at most 240 s and returns `state: "ready" | "pending" | "error"`; `pending` is a normal, resumable result you call again on, never a failure. They exist so an agent can wait without a foreground `sleep` and without binding a long server-side operation to the 900 s MCP client deadline. `wait_for_ci_checks` reports only that checks are **terminal** — deciding pass or fail stays with the caller.
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
 - **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`, `get_ticket_state_tree` (live repo-wide lifecycle + dependency tree; read-only, no mutation parameter)
 - **Jira status** — `update_jira_status` (pass `status: "auto"` to resolve the configured post-PR status server-side)
-- **Repository & CI** — `parse_repository` (`action`: `start`, `status`), `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
+- **Repository & CI** — `parse_repository` (`action`: `start`, `status`), `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `wait_for_ci_checks` (the last two are hidden until `ci_check_config` resolves, and share one visibility gate)
 - **Pipelines & automation** — `get_pipeline_recipe` (returns a fully resolved recipe the agent executes step-by-step)
 - **Config** — `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)
 
@@ -1478,10 +1584,10 @@ Pipelines are declarative, multi-step workflows your AI agent executes step-by-s
 | Pipeline | Description | Invoke with |
 |---|---|---|
 | `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |
-| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. | `/review-ticket PROJ-123` |
+| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. Internal atomic pipeline invoked by `/review-tickets` (inline for one key, spawned per tab for several) and by `/review-and-implement`, `/review-and-start`, `/start-tickets`, and `/conduct-epic`. | `/review-tickets PROJ-123` |
 | `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |
 | `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |
-| `full-automation` | Client-side wrapper: runs the `idea-to-ticket` recipe, then hands the created keys to `/review-and-start --auto` | `/full-automation "<idea>"` |
+| `full-automation` | Client-side wrapper: runs the `idea-to-ticket` recipe, then hands the created keys to `/review-and-start --auto` | `/idea-to-pr "<idea>"` |
 | `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |
 
 ### Pipeline response envelope

package/build/agent-launchers/claude.js

@@ -3,7 +3,7 @@
  *
  * Resolves the `claude` binary against the *explicitly supplied PATH* (not the
  * ambient process default) and builds the launched-run invocation by delegating
- * to the shared `renderScheduledPrompt` renderer (no hard-coded `/full-automation`
+ * to the shared `renderScheduledPrompt` renderer (no hard-coded per-command
  * prompt). It emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
  * working-directory flag, so the cwd is always set by the launching unit — this
  * adapter must never add a working-directory argument to the invocation.
@@ -41,8 +41,8 @@ export async function resolveCommandOnPath(command, envPath, deps) {
     return pathApi.normalize(candidate);
 }
 /**
- * Backward-compatibility shim for callers that quoted an idea-file path for a
- * `/full-automation` prompt. Generalized prompt-token quoting now lives in
+ * Backward-compatibility shim for callers that quoted an idea-file path for the
+ * pre-rename 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.
  */

package/build/agent-launchers/prompt.js

@@ -32,15 +32,14 @@ function schemaSupportsAutoFlag(schema) {
  * the normalized `input.args`, plus (only where the command can parse them)
  * `--scheduled-at <ISO>` and `--auto`.
  *
- * `--scheduled-at` is appended for `full-automation` (legacy) and `epic-tick`
- * (BAPI-418), both of whose parsers accept it as a first-class argument. Every
- * other command rejects unrecognized flags and halts (e.g. `start-tickets` stops
- * on any unsupported flag), and the shared late-fire gate already embeds the
- * scheduled time — so injecting `--scheduled-at` into their argv would break an
- * otherwise launchable command for no benefit.
+ * `--scheduled-at` is appended for `epic-tick` (BAPI-418), whose parser accepts
+ * it as a first-class argument. Every other command rejects unrecognized flags
+ * and halts (e.g. `start-tickets` stops on any unsupported flag), and the shared
+ * late-fire gate already embeds the scheduled time — so injecting `--scheduled-at`
+ * into their argv would break an otherwise launchable command for no benefit.
  *
  * `--auto` is appended when auto-approve is set AND the command supports it (its
- * schema declares a boolean `--auto` flag, or it is `full-automation` / `epic-tick`).
+ * schema declares a boolean `--auto` flag, or it is `epic-tick`).
  * It is never duplicated if already present in `input.args`.
  *
  * This is the SINGLE source of the delegated argv: both the rendered target
@@ -54,12 +53,10 @@ function buildAugmentedArgs(input) {
     // epic-tick already accepts --scheduled-at (parseEpicTickArgs, cli.ts) so it
     // receives the scheduled time as a structured arg for the late-fire decision,
     // not just via the embedded gate text.
-    if (input.commandName === "full-automation" || input.commandName === "epic-tick") {
+    if (input.commandName === "epic-tick") {
         args.push("--scheduled-at", input.runAtIso);
     }
-    const supportsAuto = schemaSupportsAutoFlag(input.schema) ||
-        input.commandName === "full-automation" ||
-        input.commandName === "epic-tick";
+    const supportsAuto = schemaSupportsAutoFlag(input.schema) || input.commandName === "epic-tick";
     const alreadyHasAuto = input.args.includes("--auto");
     if (input.autoApprove && supportsAuto && !alreadyHasAuto) {
         args.push("--auto");

package/build/base-ref.js

@@ -28,16 +28,38 @@ 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.
+ * This is the project's BOUNDED SAFETY SUBSET, not an implementation of
+ * `git check-ref-format`. It rejects, without invoking Git: an empty or
+ * whitespace-only name, a name longer than 255 Unicode code points, a leading
+ * `-` (which git would parse as a flag, e.g. `--upload-pack=evil`), a `..`
+ * sequence, a `.lock` suffix, and ASCII control characters. Every failure is a
+ * short, secret-free reason string naming only the rule that failed — never the
+ * offending value.
+ *
+ * The rules Git also refuses but this subset does NOT — `~`, `^`, `:`, `?`,
+ * `*`, `[`, `@{`, a backslash, and a trailing dot — are deliberate follow-up
+ * work, recorded here so nobody reads this as comprehensive ref validation. The
+ * subset is chosen to stop flag injection and command-shaped input, which is the
+ * safety property the callers actually depend on.
+ *
+ * BAPI-1127: this validator has a hand-written Python mirror,
+ * `feature_branch_provisioning._validate_provisioned_branch`, and the two are
+ * pinned rule-for-rule by the shared vectors in
+ * `tests/pytest/fixtures/run_branch_vectors.json`. The length rule counts
+ * UNICODE CODE POINTS, matching Python's `len()`. It previously used
+ * `String.length`, which counts UTF-16 code units, so a name of non-BMP
+ * characters (each a surrogate PAIR) measured double and the two runtimes
+ * disagreed about the same name at the boundary.
+ *
+ * Rule ORDER is part of the contract: the first failing rule is the one
+ * reported, so the vectors can name exactly one `error_type` per invalid input.
  */
 export function validateBranchName(branch) {
     if (branch.trim().length === 0)
         return "branch name must not be empty.";
-    if (branch.length > 255)
+    // Spread to code points (never `.length`) so this measures the same units
+    // Python's `len()` does.
+    if ([...branch].length > 255)
         return "branch name must be 255 characters or fewer.";
     if (branch.startsWith("-"))
         return "branch name must not start with '-'.";
@@ -46,9 +68,11 @@ export function validateBranchName(branch) {
     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);
+    // raw control bytes in source. Iterated by code point for the same reason the
+    // length rule is: a surrogate pair is one character, and neither half of one
+    // can be an ASCII control character anyway.
+    for (const ch of branch) {
+        const code = ch.codePointAt(0);
         if (code <= 0x1f || code === 0x7f) {
             return "branch name must not contain control characters.";
         }

package/build/bounded-wait.js

@@ -0,0 +1,174 @@
+/**
+ * A bounded, resumable wait primitive (BAPI-1104, R77).
+ *
+ * WHY THIS EXISTS. Across the BAPI-1061 and BAPI-1085 unattended runs the single
+ * largest source of wasted attempts was workers that could not wait. The Claude
+ * Code harness refuses a foreground `sleep`, and the MCP client deadline is 900
+ * seconds — so a recipe that waited by sleeping could not run at all, and one
+ * that waited by blocking a single tool call for 900 s died mid-wait, exited
+ * without its verdict artifact, and was requeued. Both failures cost a full
+ * attempt from a two-attempt budget for work that had already been done.
+ *
+ * The fix is a wait the caller can RESUME. `boundedWait` occupies at most
+ * {@link MAX_BUDGET_MS} (240 s — comfortably inside the 900 s cap), and when that
+ * window elapses it returns `{state: "pending"}`, which is a NORMAL, expected
+ * result, not an error. The caller loops: each call is a fresh bounded window,
+ * and an arbitrarily long upstream operation is covered by however many windows
+ * the caller's own budget allows. Nothing about the job's lease, heartbeat, or
+ * dead-man timing changes, because the worker never stops making tool calls.
+ *
+ * WHAT THIS MODULE IS NOT. It performs no I/O of its own. It imports no HTTP
+ * helper, knows no endpoint path, and names no agent CLI — every upstream read
+ * happens inside the caller-supplied `probe`. That is what lets the planned
+ * `cursor-agent` and Codex adapters use the identical primitive, and it is what
+ * keeps the reason vocabulary below closed: the primitive can only report states
+ * it can itself observe.
+ *
+ * NO RAW UPSTREAM DATA ESCAPES. A result carries a closed-vocabulary reason and
+ * nothing else. Exception text, response bodies, headers, URLs, and credentials
+ * are never read into a result — a caller that needs upstream detail must obtain
+ * it inside its own probe and sanitize it there, the same bar
+ * `formatRecoverablePollGiveUp` sets for the existing poller.
+ *
+ * TIMER DISCIPLINE. Every timer this module creates is registered and cancelled
+ * in an outer `finally`, on every exit path including an unexpected throw. The
+ * timer seams are injectable because `VirtualClock.tickUntil` in
+ * `executor/test-clock.ts` flushes microtasks only and cannot advance a real
+ * `setTimeout` — a primitive that reached for the global timer would make its own
+ * deterministic tests hang rather than fail, which is the worse of the two.
+ */
+import { MAX_CONSECUTIVE_POLL_FAILURES, MAX_PROBE_TIMEOUT_MS, MAX_POLL_JITTER_MS, defaultPollDelayMs, } from "./polling-policy.js";
+/** Hard ceiling on one wait window. Well inside the 900 s MCP client deadline. */
+export const MAX_BUDGET_MS = 240_000;
+const monotonicNow = () => typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+/**
+ * Wait for `probe` to report ready, for at most `budgetMs` (≤ 240 s).
+ *
+ * Returns `ready` with the probe's value, `pending` when the window closed or
+ * transport kept failing, or `error` over the closed reason vocabulary. Never
+ * throws: an unexpected exception from a caller's `isReady` or timer seam still
+ * unwinds through the `finally` that cancels every outstanding timer.
+ */
+export async function boundedWait(options) {
+    const { budgetMs, probe, isReady, signal, deps } = options;
+    // Caller error, reported rather than clamped: a budget that is NaN, infinite,
+    // or sub-millisecond is a computed value that went wrong upstream, and
+    // silently substituting 240 s would hide the bug behind a working wait.
+    if (typeof budgetMs !== "number" || !Number.isFinite(budgetMs) || budgetMs < 1) {
+        return { state: "error", reason: "INVALID_ARGUMENT" };
+    }
+    const effectiveBudgetMs = Math.min(budgetMs, MAX_BUDGET_MS);
+    const now = deps?.now ?? monotonicNow;
+    const setTimer = deps?.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+    const clearTimer = deps?.clearTimer ?? ((handle) => clearTimeout(handle));
+    const jitterMs = deps?.jitterMs ?? (() => Math.random() * MAX_POLL_JITTER_MS);
+    // EVERY timer created below is registered here and cancelled in the outer
+    // `finally`. A leaked timer in an MCP server process keeps the event loop
+    // alive and, in a test, keeps a virtual clock advancing past the assertion.
+    const liveTimers = new Set();
+    const track = (handle) => {
+        liveTimers.add(handle);
+        return handle;
+    };
+    const release = (handle) => {
+        liveTimers.delete(handle);
+        clearTimer(handle);
+    };
+    const startedAt = now();
+    const deadlineAt = startedAt + effectiveBudgetMs;
+    const remaining = () => deadlineAt - now();
+    /** Sleep through an injected timer, resolving early if the caller aborts. */
+    const delay = (ms) => new Promise((resolve) => {
+        if (ms <= 0) {
+            resolve();
+            return;
+        }
+        let handle;
+        const finish = () => {
+            signal?.removeEventListener("abort", finish);
+            if (handle !== undefined)
+                release(handle);
+            resolve();
+        };
+        handle = track(setTimer(finish, ms));
+        signal?.addEventListener("abort", finish, { once: true });
+    });
+    let consecutiveFailures = 0;
+    try {
+        while (true) {
+            if (signal?.aborted)
+                return { state: "error", reason: "ABORTED" };
+            if (remaining() <= 0) {
+                return { state: "pending", reason: "WAIT_WINDOW_ELAPSED" };
+            }
+            // One controller per probe, aborted by EITHER the per-probe timeout or the
+            // caller's signal. The probe therefore never outlives its own budget, and a
+            // hung upstream costs one probe timeout rather than the whole window.
+            const probeController = new AbortController();
+            const abortProbe = () => probeController.abort();
+            signal?.addEventListener("abort", abortProbe, { once: true });
+            const probeTimeoutMs = Math.max(1, Math.min(MAX_PROBE_TIMEOUT_MS, remaining()));
+            let timedOut = false;
+            const timeoutHandle = track(setTimer(() => {
+                timedOut = true;
+                probeController.abort();
+            }, probeTimeoutMs));
+            let outcome = null;
+            let threw = false;
+            try {
+                outcome = await probe(probeController.signal);
+            }
+            catch {
+                // The probe's exception NEVER reaches a result. A transport throw and a
+                // probe timeout are the same observation — "no answer this time" — and
+                // both are transient until the shared ceiling says otherwise.
+                threw = true;
+            }
+            finally {
+                release(timeoutHandle);
+                signal?.removeEventListener("abort", abortProbe);
+            }
+            // Caller cancellation outranks whatever the in-flight probe reported: the
+            // caller stopped caring, and it is not an upstream observation.
+            if (signal?.aborted)
+                return { state: "error", reason: "ABORTED" };
+            if (threw || timedOut || outcome === null) {
+                consecutiveFailures += 1;
+                if (consecutiveFailures >= MAX_CONSECUTIVE_POLL_FAILURES) {
+                    return { state: "pending", reason: "UPSTREAM_TRANSIENT" };
+                }
+            }
+            else if (outcome.kind === "terminal") {
+                return { state: "error", reason: "UPSTREAM_TERMINAL" };
+            }
+            else if (outcome.kind === "malformed") {
+                return { state: "error", reason: "INVALID_RESPONSE" };
+            }
+            else {
+                // The server answered. Reset the streak BEFORE evaluating readiness — an
+                // answer of "not yet" is still proof the transport is healthy.
+                consecutiveFailures = 0;
+                if (outcome.ready === true) {
+                    const value = outcome.value;
+                    if (isReady === undefined || isReady(value)) {
+                        return { state: "ready", result: value };
+                    }
+                }
+            }
+            if (remaining() <= 0) {
+                return { state: "pending", reason: "WAIT_WINDOW_ELAPSED" };
+            }
+            // The existing poller's curve plus bounded jitter, clamped to whatever is
+            // actually left so a backoff can never overrun the deadline it is inside.
+            const backoff = defaultPollDelayMs(now() - startedAt) + jitterMs();
+            await delay(Math.min(backoff, remaining()));
+        }
+    }
+    finally {
+        for (const handle of liveTimers)
+            clearTimer(handle);
+        liveTimers.clear();
+    }
+}