@bridge_gpt/mcp-server 0.2.18 → 0.2.19

package/build/worktree-core.js

@@ -0,0 +1,202 @@
+/**
+ * Shared Worktrunk worktree primitives (BAPI-534).
+ *
+ * Extracted verbatim from `start-tickets.ts` so both the interactive
+ * `start-tickets` flow and the Epic Conductor v2 executor (`executor/worktree.ts`)
+ * call ONE implementation of the `wt switch` argument construction, branch
+ * inspection, and Worktrunk JSON path parsing — no duplicated switch logic.
+ *
+ * `start-tickets.ts` re-exports every symbol here so its pinned test imports
+ * (and the strict-equality assertions in `worktree-core.test.ts`) keep working.
+ *
+ * Import direction: this module imports the shared `StartTicketsDeps` /
+ * `BranchOverrides` / `SummaryRow` types from `start-tickets.js` as TYPE-ONLY
+ * imports (erased at runtime) plus the `commandSucceeded` value from
+ * `start-tickets-prereqs.js`. `start-tickets.ts` imports the VALUES here — a
+ * type-only back-edge keeps the runtime graph acyclic (mirrors the existing
+ * prereqs <-> start-tickets pattern).
+ */
+import path from "path";
+import { commandSucceeded } from "./start-tickets-prereqs.js";
+/** Resolve the branch for a ticket: explicit override, else feature/<KEY>. */
+export function resolveBranchForTicket(key, overrides) {
+    if (Object.prototype.hasOwnProperty.call(overrides, key)) {
+        return overrides[key];
+    }
+    return `feature/${key}`;
+}
+/** True only when `git show-ref --verify --quiet refs/heads/<branch>` exits 0. */
+export async function branchExists(deps, branch) {
+    const result = await deps.runCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: deps.cwd });
+    return commandSucceeded(result);
+}
+/**
+ * Build `wt switch` args. Include `--create` only when the branch does not yet
+ * exist. Always include `-y` (auto-approve): the CLI runs the Worktrunk binary
+ * via `execFile` with no TTY, so without `-y` the `pre-start` / `post-start`
+ * hook-approval prompts would have no input source and the call would hang or
+ * fail — this mirrors the deleted `scripts/start-tickets.sh`, which ran
+ * `wt switch -c -y`. Never includes `-x` — the CLI owns worktree creation and
+ * tab spawning separately. The args are platform-agnostic; only the binary
+ * differs (`wt` vs `git-wt`).
+ *
+ * `baseStartPoint` (BAPI-527) is the ref/commit new branches are cut from via
+ * Worktrunk's `-b <start-point>`. It may be a branch name (the interactive
+ * default, e.g. `"main"`) OR an immutable commit SHA resolved by the non-mutating
+ * conductor dispatch path ({@link fetchAndResolveBaseSha}) — Worktrunk's `-b`
+ * accepts either. Only used when `exists === false`; existing branches are reused
+ * as-is and never recreated from a start point.
+ */
+export function buildWtSwitchArgs(branch, exists, baseStartPoint = "main") {
+    if (exists) {
+        return ["switch", "-y", branch, "--format=json"];
+    }
+    return ["switch", "--create", "-y", branch, "-b", baseStartPoint, "--format=json"];
+}
+/** Return the Node `path` API matching a platform (`win32` vs POSIX). */
+export function pathApiForPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/**
+ * Extract a worktree path from Worktrunk JSON stdout. Accepts several common
+ * shapes defensively and resolves relative paths against `cwd` using the
+ * platform-correct path semantics (so Windows-style paths resolve correctly
+ * even when the test/host OS differs). Throws when no usable path can be
+ * extracted.
+ */
+export function extractWorktreePath(stdout, cwd, platform = process.platform) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`Could not parse Worktrunk JSON output: ${stdout.slice(0, 200)}`);
+    }
+    const candidate = pickWorktreePathField(parsed);
+    if (!candidate) {
+        throw new Error(`Worktrunk JSON did not include a worktree path: ${stdout.slice(0, 200)}`);
+    }
+    const pathApi = pathApiForPlatform(platform);
+    return pathApi.isAbsolute(candidate) ? candidate : pathApi.resolve(cwd, candidate);
+}
+function pickWorktreePathField(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return undefined;
+    const obj = parsed;
+    if (typeof obj.path === "string")
+        return obj.path;
+    if (typeof obj.worktree_path === "string")
+        return obj.worktree_path;
+    if (typeof obj.directory === "string")
+        return obj.directory;
+    if (obj.worktree && typeof obj.worktree === "object") {
+        const nested = obj.worktree;
+        if (typeof nested.path === "string")
+            return nested.path;
+    }
+    return undefined;
+}
+/**
+ * F7: decide whether a PRE-EXISTING branch is safe to reuse as a conductor
+ * worktree base. A branch whose tip is an ancestor of the resolved base carries
+ * no commits beyond base (nothing stale to build on) and is safe. A branch with
+ * commits not on base is a leftover from a prior run — refuse it. Prefers the
+ * authoritative `origin/<base>` ref when present. Conservative: any inability to
+ * prove ancestry refuses (when in doubt, refuse).
+ *
+ * `baseStartPoint` (BAPI-527) is the SAME effective base new worktrees are cut
+ * from: a branch name for interactive dispatch, or the fetched immutable commit
+ * SHA for non-mutating conductor dispatch. When it is a SHA the `origin/<sha>`
+ * probe below naturally fails to resolve, so the ancestry check falls back to
+ * comparing the existing branch directly against that fetched SHA — never
+ * against the local `main` branch name.
+ */
+export async function isExistingBranchSafeToReuse(deps, branch, baseStartPoint) {
+    let baseRef = baseStartPoint;
+    const originRef = `origin/${baseStartPoint}`;
+    const originExists = await deps.runCommand("git", ["rev-parse", "--verify", "--quiet", originRef], { cwd: deps.cwd });
+    if (commandSucceeded(originExists))
+        baseRef = originRef;
+    // `merge-base --is-ancestor <branch> <baseRef>` exits 0 iff <branch> is an
+    // ancestor of <baseRef> (a fresh branch at base counts as an ancestor).
+    const ancestor = await deps.runCommand("git", ["merge-base", "--is-ancestor", branch, baseRef], { cwd: deps.cwd });
+    if (commandSucceeded(ancestor))
+        return { safe: true };
+    return {
+        safe: false,
+        reason: `existing branch '${branch}' is not an ancestor of ${baseRef}; it carries commits not on the ` +
+            `resolved base (likely a leftover from a prior run). Refusing to reuse a stale worktree — delete it ` +
+            `(git worktree remove + git branch -D ${branch}) or rebase it onto ${baseRef}, then re-dispatch.`,
+    };
+}
+/**
+ * Create / switch the worktree for a single ticket using the resolved Worktrunk
+ * binary (`wt` on macOS/Linux, `git-wt` on Windows). Returns a `created` row on
+ * success (with key, branch, path) or a `create-failed` row on any expected
+ * failure — never throws for per-ticket problems.
+ *
+ * `baseStartPoint` is routed into `buildWtSwitchArgs` as Worktrunk's `-b` and is
+ * used ONLY when the branch does not yet exist locally. Executor RECOVERY callers
+ * (BAPI-542/BAPI-528, `executor/worktree.ts`) may pass `origin/<branch>` here so a
+ * missing local branch is recreated from the pushed PR branch rather than cut
+ * fresh off the base branch, and additionally pass `behavior.freshenFromOrigin`
+ * so an ALREADY-EXISTING local branch is hard-reset onto that same pushed ref
+ * instead of being silently reused as-is. This stays executor-agnostic: no
+ * job-type logic lives here — the caller decides the start point, the stale
+ * guard, and the freshen behavior.
+ */
+export async function createWorktreeForTicket(deps, key, branchOverrides, worktrunkBinary, baseStartPoint = "main", guardStaleWorktree = false, behavior = {}) {
+    const branch = resolveBranchForTicket(key, branchOverrides);
+    try {
+        const exists = await branchExists(deps, branch);
+        // F7 (conductor dispatch): refuse a stale pre-existing branch rather than
+        // silently building the worker on leftover code. BAPI-527: the ancestry
+        // check compares against the SAME effective base start point (branch name or
+        // fetched SHA) that a NEW branch would be cut from below.
+        if (exists && guardStaleWorktree) {
+            const safety = await isExistingBranchSafeToReuse(deps, branch, baseStartPoint);
+            if (!safety.safe) {
+                return {
+                    key,
+                    branch,
+                    status: "create-failed",
+                    error: `stale worktree guard: ${safety.reason}`,
+                };
+            }
+        }
+        const args = buildWtSwitchArgs(branch, exists, baseStartPoint);
+        const result = await deps.runCommand(worktrunkBinary, args, { cwd: deps.cwd });
+        if (!commandSucceeded(result)) {
+            const reason = (result.stderr || result.stdout || "").trim();
+            return {
+                key,
+                branch,
+                status: "create-failed",
+                error: `${worktrunkBinary} ${args.join(" ")} failed${reason ? `: ${reason}` : ""}`,
+            };
+        }
+        const worktreePath = extractWorktreePath(result.stdout, deps.cwd, deps.platform);
+        // BAPI-528: freshen a REUSED existing branch onto the pushed ref. A new
+        // branch was already cut from `baseStartPoint` (recovery sets that to
+        // `origin/<branch>`), so this only applies when the local branch pre-existed.
+        // Run inside the switched worktree (the branch is checked out there).
+        if (exists && behavior.freshenFromOrigin) {
+            const resetArgs = ["reset", "--hard", behavior.freshenFromOrigin];
+            const reset = await deps.runCommand("git", resetArgs, { cwd: worktreePath });
+            if (!commandSucceeded(reset)) {
+                const reason = (reset.stderr || reset.stdout || "").trim();
+                return {
+                    key,
+                    branch,
+                    status: "create-failed",
+                    error: `git ${resetArgs.join(" ")} failed${reason ? `: ${reason}` : ""}`,
+                };
+            }
+        }
+        return { key, branch, status: "created", path: worktreePath };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { key, branch, status: "create-failed", error: message };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",
@@ -27,21 +27,25 @@
     "check:version-generated": "node scripts/bundle-version.js && node scripts/check-version-generated.js",
     "postbuild": "node scripts/prepend-shebang.cjs",
     "start": "node build/index.js",
-    "test": "node --test --test-force-exit build/pipeline-utils.test.js build/update-check.test.js build/cli-upgrade.test.js build/decision-page-schema.test.js build/decision-page-template.test.js build/bundle-pipelines.test.js build/instructions-contract.test.js build/pipeline-orchestrator-persistence.test.js build/pipeline-orchestrator-execution.test.js build/pipeline-orchestrator-integration.test.js build/index-static.test.js build/config-fields.static.test.js build/index-resolvers.test.js build/index-project-root.test.js build/index-pipelines.test.js build/index.test.js build/bridge-config.test.js build/credential-store.test.js build/agent-config-credential-migration.test.js build/mcp-invoke.test.js build/mcp-provisioning.test.js build/third-party-mcp-targets.test.js build/git-ignore-utils.test.js build/credential-materialization.test.js build/mcp-registration-doctor.test.js build/secret-safety.test.js build/start-tickets.test.js build/review-tickets.test.js build/start-tickets-base-branch.test.js build/agent-registry.test.js build/agent-registry.model-routing.test.js build/start-tickets.shell-model-routing.test.js build/start-tickets.bridge-api-model-routing.test.js build/start-tickets.tier-fetch-model-routing.test.js build/start-tickets.resolve-model-routing.test.js build/start-tickets.orchestrate-model-routing.test.js build/start-tickets.routing-diagnostics.test.js build/start-tickets-repo.test.js build/start-tickets-credential-invariants.static.test.js build/credentials-cli.test.js build/start-tickets-prereqs.test.js build/regression-check.test.js build/doctor.test.js build/install-doctor.test.js build/install-bridge.test.js build/init.test.js build/resolveUploadAttachment.test.js build/package-static.test.js build/chain-utils.test.js build/chain-orchestrator.test.js build/scheduler-backends/types.test.js build/scheduler-backends/escaping.test.js build/scheduler-backends/launchd.test.js build/scheduler-backends/task-scheduler.test.js build/scheduler-backends/systemd-user.test.js build/scheduler-backends/at-fallback.test.js build/scheduler-backends/index.test.js build/command-catalog.test.js build/scheduled-prompt.test.js build/agent-launchers/claude.test.js build/agent-launchers/cursor.test.js build/agent-launchers/index.test.js build/schedule-store.test.js build/schedule-run.test.js build/agent-capabilities/cli.test.js build/agent-capabilities/runner.test.js build/agent-capabilities/probes.test.js build/agent-capabilities/reporter.test.js build/conductor/taxonomy-and-errors.test.js build/conductor/github-mergeability.test.js build/conductor/merge-conflict-routing.test.js build/conductor/redaction-normalization.test.js build/conductor/claude-hook.test.js build/conductor/git-ci-types.test.js build/conductor/done-gate.test.js build/conductor/git-ci-taxonomy-payload.test.js build/conductor/bridge-api-client.test.js build/conductor/plan.test.js build/conductor/producer-ledger.test.js build/conductor/spec-review-producer.test.js build/conductor/git-producer.test.js build/conductor/git-hooks.test.js build/conductor/store-migration.test.js build/conductor/pr-discovery.test.js build/conductor/pr-ci-producer.test.js build/conductor/pr-review-producer.test.js build/conductor/doctor.test.js build/conductor/index-poll-ci-producer.test.js build/start-tickets-conductor.test.js build/start-tickets-conductor.spawn.test.js build/conductor/supervisor-config.test.js build/conductor/supervisor-ledger.test.js build/conductor/supervisor-state-reducer.test.js build/conductor/supervisor-housekeeping-projection.test.js build/conductor/supervisor-escalation.test.js build/conductor/supervisor-retired-judgment.static.test.js build/conductor/supervisor-runtime.test.js build/conductor/supervisor-store-projection.test.js build/conductor/supervisor-cli.test.js build/conductor/supervisor-start-tickets.test.js build/conductor/supervisor-message-relay.test.js build/conductor/supervisor-state-message-events.test.js build/conductor/store-message-relay.test.js build/start-tickets-message-relay.test.js build/conductor/event-accessors.test.js build/conductor/merge-ledger.test.js build/conductor/local-merge.test.js build/conductor/supervisor-merge.test.js build/conductor/bridge-api-merge-client.test.js build/conductor/bridge-api-epic-client.test.js build/conductor/supervisor-merge-runtime-state.test.js build/conductor/epic-state.test.js build/conductor/epic-reconcile.test.js build/conductor/epic-runtime.test.js build/conductor/epic-tick-sequence.test.js build/conductor/epic-runtime-post-action.test.js build/conductor/file-scope-guard.test.js build/conductor/file-scope-guard.integration.test.js build/mcp-profile.test.js build/mcp-profile-registration.test.js build/tools-budget.test.js build/integration/measure-tools.test.js build/sfcc/config.test.js build/sfcc/ocapi-shape.test.js build/sfcc/output.test.js build/sfcc/credentials.test.js && node --experimental-test-module-mocks --test --test-force-exit build/index-heavy-read-truncation.test.js build/index-artifacts.test.js build/index-brainstorm-filenames.test.js build/index-output-path.test.js build/index-generate-decision-page.test.js build/index-generate-decision-page.integration.test.js build/conductor/paths.test.js build/conductor/store-lifecycle.test.js build/conductor/store-queries.test.js build/conductor/tools.test.js build/conductor/cli.test.js build/conductor/security-regressions.test.js build/conductor/git-inspection.test.js build/conductor/tools-done-gate.test.js build/conductor/cli-git-hooks.test.js build/sfcc/client.test.js build/sfcc/tool-wrapper.test.js build/sfcc/setup-status.test.js build/sfcc/permissions.test.js build/sfcc/register.test.js build/sfcc/reads-system-object.test.js build/sfcc/reads-custom-object-def.test.js build/sfcc/reads-site-preference.test.js",
-    "test:integration": "node --test build/integration/refresh-main.integration.test.js build/integration/start-tickets.integration.test.js build/integration/doctor.integration.test.js build/integration/agent-capabilities.integration.test.js build/integration/conductor-producer.integration.test.js build/integration/conductor-message-relay.integration.test.js",
+    "test": "node --test --test-force-exit build/pipeline-utils.test.js build/backend-warnings.test.js build/update-check.test.js build/cli-upgrade.test.js build/decision-page-schema.test.js build/decision-page-template.test.js build/bundle-pipelines.test.js build/instructions-contract.test.js build/pipeline-orchestrator-persistence.test.js build/pipeline-orchestrator-execution.test.js build/pipeline-orchestrator-integration.test.js build/index-static.test.js build/config-fields.static.test.js build/index-resolvers.test.js build/index-project-root.test.js build/index-pipelines.test.js build/index.test.js build/bridge-config.test.js build/credential-store.test.js build/agent-config-credential-migration.test.js build/mcp-invoke.test.js build/mcp-provisioning.test.js build/mcp-server-invocation.test.js build/third-party-mcp-targets.test.js build/git-ignore-utils.test.js build/credential-materialization.test.js build/mcp-registration-doctor.test.js build/secret-safety.test.js build/start-tickets.test.js build/review-tickets.test.js build/start-tickets-base-branch.test.js build/agent-registry.test.js build/agent-registry.model-routing.test.js build/start-tickets.shell-model-routing.test.js build/start-tickets.bridge-api-model-routing.test.js build/start-tickets.tier-fetch-model-routing.test.js build/start-tickets.resolve-model-routing.test.js build/start-tickets.orchestrate-model-routing.test.js build/start-tickets.routing-diagnostics.test.js build/start-tickets-repo.test.js build/start-tickets-credential-invariants.static.test.js build/credentials-cli.test.js build/start-tickets-prereqs.test.js build/regression-check.test.js build/doctor.test.js build/install-doctor.test.js build/install-bridge.test.js build/init.test.js build/resolveUploadAttachment.test.js build/package-static.test.js build/chain-utils.test.js build/chain-orchestrator.test.js build/scheduler-backends/types.test.js build/scheduler-backends/escaping.test.js build/scheduler-backends/launchd.test.js build/scheduler-backends/task-scheduler.test.js build/scheduler-backends/systemd-user.test.js build/scheduler-backends/at-fallback.test.js build/scheduler-backends/index.test.js build/command-catalog.test.js build/scheduled-prompt.test.js build/agent-launchers/claude.test.js build/agent-launchers/cursor.test.js build/agent-launchers/index.test.js build/schedule-store.test.js build/schedule-run.test.js build/agent-capabilities/cli.test.js build/agent-capabilities/runner.test.js build/agent-capabilities/probes.test.js build/agent-capabilities/probe-context.test.js build/agent-capabilities/reporter.test.js build/conductor/taxonomy-and-errors.test.js build/conductor/github-mergeability.test.js build/conductor/merge-conflict-routing.test.js build/conductor/redaction-normalization.test.js build/conductor/claude-hook.test.js build/conductor/git-ci-types.test.js build/conductor/done-gate.test.js build/conductor/git-ci-taxonomy-payload.test.js build/conductor/bridge-api-client.test.js build/conductor/plan.test.js build/conductor/producer-ledger.test.js build/conductor/spec-review-producer.test.js build/conductor/git-producer.test.js build/conductor/git-hooks.test.js build/conductor/store-migration.test.js build/conductor/pr-discovery.test.js build/conductor/pr-ci-producer.test.js build/conductor/pr-review-producer.test.js build/conductor/doctor.test.js build/conductor/deny-enforcement-preflight.test.js build/conductor/errors.test.js build/conductor/store.test.js build/conductor/index-poll-ci-producer.test.js build/start-tickets-conductor.test.js build/start-tickets-conductor.spawn.test.js build/start-tickets-conductor-node-propagation.test.js build/start-tickets.non-mutating-base.test.js build/start-tickets-live-source-guard.test.js build/conductor/worker-ledger-cli.test.js build/conductor/supervisor-config.test.js build/conductor/supervisor-ledger.test.js build/conductor/supervisor-state-reducer.test.js build/conductor/supervisor-housekeeping-projection.test.js build/conductor/supervisor-escalation.test.js build/conductor/supervisor-retired-judgment.static.test.js build/conductor/supervisor-runtime.test.js build/conductor/supervisor-store-projection.test.js build/conductor/supervisor-cli.test.js build/conductor/supervisor-start-tickets.test.js build/conductor/supervisor-message-relay.test.js build/conductor/supervisor-state-message-events.test.js build/conductor/store-message-relay.test.js build/start-tickets-message-relay.test.js build/conductor/event-accessors.test.js build/conductor/merge-ledger.test.js build/conductor/deterministic-completion.static.test.js build/conductor/deterministic-completion.integration.test.js build/conductor/local-merge.test.js build/conductor/supervisor-merge.test.js build/conductor/bridge-api-merge-client.test.js build/conductor/bridge-api-epic-client.test.js build/conductor/supervisor-merge-runtime-state.test.js build/conductor/epic-state.test.js build/executor/claude-settings.test.js build/executor/cli.test.js build/executor/credentials.test.js build/executor/echo-acceptance.test.js build/executor/env.test.js build/executor/heartbeat.test.js build/executor/http-client.test.js build/executor/job-runner.test.js build/executor/job-runner.payload-timeout.test.js build/executor/worker-finalization.test.js build/executor/job-runner.static.test.js build/executor/prompt-spec.test.js build/executor/job-types.test.js build/executor/recovery-job.static.test.js build/executor/observation.test.js build/executor/permissions.test.js build/executor/preflight.test.js build/executor/process.test.js build/executor/results.test.js build/executor/runner.test.js build/executor/terminal-mutation.test.js build/executor/worker-command.test.js build/executor/worktree-core.test.js build/executor/worktree.test.js build/executor/job-errors.test.js build/executor/worktree-inspection.test.js build/executor/resume-pre-spawn.test.js build/executor/verdict-artifact.test.js build/executor/worker-log.test.js build/executor/job-log-registry.test.js build/executor/viewer-tabs.test.js build/executor/watch-cli.test.js build/executor/merge-job.test.js build/executor/worktree-gc.test.js build/executor/runner.job-behaviors.test.js build/conductor/cli-freeze.test.js build/conductor/epic-reconcile.test.js build/conductor/epic-runtime.test.js build/conductor/epic-tick-sequence.test.js build/conductor/epic-runtime-post-action.test.js build/conductor/file-scope-guard.test.js build/conductor/file-scope-guard.integration.test.js build/mcp-profile.test.js build/mcp-profile-registration.test.js build/tools-budget.test.js build/visual-diff-worker.test.js build/visual-diff.test.js build/integration/measure-tools.test.js build/sfcc/config.test.js build/sfcc/ocapi-shape.test.js build/sfcc/output.test.js build/sfcc/credentials.test.js && node --experimental-test-module-mocks --test --test-force-exit build/index-heavy-read-truncation.test.js build/index-artifacts.test.js build/index-brainstorm-filenames.test.js build/index-output-path.test.js build/index-generate-decision-page.test.js build/index-generate-decision-page.integration.test.js build/visual-diff.registration.test.js build/visual-diff.attachment-adapter.test.js build/attachment-download.test.js build/conductor/paths.test.js build/conductor/store-lifecycle.test.js build/conductor/store-queries.test.js build/conductor/tools.test.js build/conductor/cli.test.js build/conductor/security-regressions.test.js build/conductor/git-inspection.test.js build/conductor/tools-done-gate.test.js build/conductor/pr-ci-producer-emit-seam.test.js build/conductor/cli-git-hooks.test.js build/sfcc/client.test.js build/sfcc/tool-wrapper.test.js build/sfcc/setup-status.test.js build/sfcc/permissions.test.js build/sfcc/register.test.js build/sfcc/reads-system-object.test.js build/sfcc/reads-custom-object-def.test.js build/sfcc/reads-site-preference.test.js",
+    "test:integration": "node --test build/integration/refresh-main.integration.test.js build/integration/start-tickets.integration.test.js build/integration/doctor.integration.test.js build/integration/agent-capabilities.integration.test.js build/integration/conductor-producer.integration.test.js build/integration/conductor-message-relay.integration.test.js build/integration/executor-http-runner.integration.test.js build/integration/executor-job-behaviors.integration.test.js build/integration/executor-recovery-jobs.integration.test.js build/integration/executor-spec-review-prompt.integration.test.js build/integration/resume-pre-spawn.git.integration.test.js",
     "test:smoke": "node --test build/integration/packaged-cli-smoke.test.js",
     "prepublishOnly": "node scripts/bundle-assets.js && npm run build && node scripts/verify-shebang.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0",
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "better-sqlite3": "^12.11.1"
+    "better-sqlite3": "^12.11.1",
+    "playwright": "^1.51.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^26.0.1",
+    "@types/pngjs": "^6.0.5",
     "esbuild": "^0.28.1",
     "typescript": "^6.0.3"
   },

package/public/css/main.min.css

@@ -494,6 +494,45 @@ textarea {
     line-height: 1.4;
 }
 
+/* Structured server-sourced setup instructions (BAPI-515), rendered inside
+   .explanation-content by renderExplanationContent(). Scoped to this wrapper
+   only — the container above is left untouched. */
+.explanation-content .setup-instructions {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.explanation-content .setup-instructions-link {
+    color: var(--primary-color);
+    font-weight: 500;
+    text-decoration: underline;
+    overflow-wrap: anywhere;
+}
+
+.explanation-content .setup-instructions-link:hover {
+    color: var(--primary-dark);
+}
+
+.explanation-content .setup-instructions-link:focus-visible {
+    outline: 2px solid var(--primary-color);
+    outline-offset: 2px;
+}
+
+.explanation-content .setup-instructions-steps {
+    margin: 0;
+    padding-left: 20px;
+}
+
+.explanation-content .setup-instructions-steps li + li {
+    margin-top: 4px;
+}
+
+.explanation-content .setup-instructions-note {
+    margin: 0;
+    color: var(--secondary-color);
+}
+
 /* Form error styling */
 .form-error {
     color: var(--error-color);