@bridge_gpt/mcp-server 0.2.50 → 0.2.52

package/build/conduct-epic/cut-protocol.js

@@ -277,6 +277,67 @@ export const SCOPE_LIFECYCLE_LABELS = Object.freeze({
     ready: "Ready",
     failed: "Failed",
 });
+/**
+ * The fixed lifecycle label a heartbeat uses when the status READ itself failed
+ * (BAPI-963).
+ *
+ * A read failure is not a lifecycle state, and the raw error is deliberately not
+ * interpolated into a heartbeat: a per-poll line repeated for twenty minutes is
+ * the worst possible place to smuggle unbounded server text.
+ */
+export const SCOPE_BOOTSTRAP_UNREADABLE_STATE = "unreadable";
+/**
+ * Format one bootstrap heartbeat line (BAPI-963).
+ *
+ * Shared with `setup-epic` at this seam so both conductors compute progress the
+ * same way; RENDERING stays with each caller, because the pilot writes to its own
+ * stderr advisory channel and v2 reports progress server-side.
+ *
+ * The shape is fixed and grep-friendly — elapsed first, state second — because a
+ * ~30-minute seed that printed nothing was externally indistinguishable from a
+ * hang (sleeping process, 0% CPU, a frozen `updated_at`). Elapsed seconds are
+ * clamped at zero so a clock adjustment cannot render a negative age.
+ */
+export function formatScopeBootstrapHeartbeat(elapsedMs, state) {
+    const seconds = Math.max(0, Math.floor(elapsedMs / 1000));
+    // `lifecycle_state` is a required non-empty string on the wire, not a closed
+    // set. Bounding it to the known labels (plus the fixed `unreadable` and a
+    // catch-all) keeps an unvalidated server string out of a line that repeats
+    // every interval for up to twenty minutes.
+    return `Seeding scope: elapsed=${seconds}s state=${boundScopeLifecycleLabel(state)}`;
+}
+/** The label an unrecognized lifecycle state collapses to. Never `null`, never raw. */
+export const SCOPE_BOOTSTRAP_UNKNOWN_STATE = "unknown";
+/**
+ * Collapse any lifecycle state to a bounded, safe label (BAPI-1054).
+ *
+ * `lifecycle_state` is a required non-empty string on the wire, not a closed set,
+ * so an unrecognized value is possible and an error-bearing one
+ * (`unreadable (<server error>)`) is routine. Extracted from
+ * {@link formatScopeBootstrapHeartbeat}, which has always applied this rule, so
+ * every surface that renders a state applies the SAME one — a second spelling of
+ * "bounded" is how raw server text eventually reaches a terminal.
+ */
+export function boundScopeLifecycleLabel(state) {
+    return state === SCOPE_BOOTSTRAP_UNREADABLE_STATE || state in SCOPE_LIFECYCLE_LABELS
+        ? state
+        : SCOPE_BOOTSTRAP_UNKNOWN_STATE;
+}
+/**
+ * Describe the nominal polling window up front (BAPI-963).
+ *
+ * Computed from the interval and cap rather than hard-coded, so a change to
+ * either constant cannot leave the operator-facing duration claim stale. The
+ * window is NOMINAL: the observed pilot seed outran even this bound, which is
+ * why the wording promises a poll cadence rather than a completion time.
+ */
+export function describeScopeBootstrapWindow(intervalMs = SCOPE_BOOTSTRAP_POLL_INTERVAL_MS, maxPolls = SCOPE_BOOTSTRAP_MAX_POLLS) {
+    const intervalSeconds = Math.max(1, Math.round(intervalMs / 1000));
+    const windowMinutes = Math.max(1, Math.round((intervalMs * maxPolls) / 60_000));
+    return (`Seeding the epic's index scope. This copies the repository's whole parse cache and ` +
+        `verifies it, and commonly takes many minutes. Progress is reported every ` +
+        `${intervalSeconds}s; the poll gives up after about ${windowMinutes} minutes.`);
+}
 /**
  * Poll a scope's lifecycle until it is `ready`, `failed`, or the bounded wait
  * elapses, reporting each NEWLY observed lifecycle transition exactly once, in
@@ -296,6 +357,8 @@ export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {
     const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const maxPolls = options.maxPolls ?? SCOPE_BOOTSTRAP_MAX_POLLS;
     const intervalMs = options.intervalMs ?? SCOPE_BOOTSTRAP_POLL_INTERVAL_MS;
+    const now = options.now ?? (() => new Date());
+    const startedAtMs = now().getTime();
     let lastState = "unknown";
     let lastStatus = null;
     let lastReportedState = null;
@@ -304,10 +367,12 @@ export async function pollIndexScopeLifecycle(deps, access, scopeId, options = {
         const status = await getIndexScopeStatus(access, scopeId, deps.fetchImpl);
         if (!status.ok) {
             lastState = `unreadable (${status.error})`;
+            options.onPoll?.(now().getTime() - startedAtMs, SCOPE_BOOTSTRAP_UNREADABLE_STATE);
             continue;
         }
         lastStatus = status.value;
         lastState = status.value.lifecycle_state;
+        options.onPoll?.(now().getTime() - startedAtMs, lastState);
         if (lastState !== lastReportedState) {
             lastReportedState = lastState;
             options.onTransition?.(lastState, status.value);

package/build/conductor/bridge-api-client.js

@@ -769,6 +769,79 @@ export async function fetchEpicRunState(access, epicKey, fetchImpl = globalThis.
     const parsed = await fetchConductorJsonWithTimeout(url, conductorGetHeaders(access), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parsed;
 }
+// ---------------------------------------------------------------------------
+// Executor wind-down: read-only completion-state projection (BAPI-1010)
+// ---------------------------------------------------------------------------
+/** Closed runtime vocabulary mirroring the Python `EpicRunStatus` Literal exactly. */
+export const EPIC_RUN_STATUS_VALUES = [
+    "planning",
+    "pending_approval",
+    "active",
+    "blocked",
+    "abandoned",
+    "done",
+];
+function isEpicRunStatus(value) {
+    return typeof value === "string" && EPIC_RUN_STATUS_VALUES.includes(value);
+}
+/**
+ * GET the epic run's completion state (`status` plus the derived feature
+ * branch) through the existing {@link fetchEpicRunState} transport, then
+ * validate the payload as untrusted boundary input. Never throws — every
+ * failure, transport or validation, resolves to the closed failure member of
+ * {@link EpicRunCompletionStateResult} rather than propagating a raw error,
+ * response body, header, or credential.
+ *
+ * `epicRunId` may be an epic run id or an epic key — the underlying endpoint
+ * accepts either, exactly like {@link fetchEpicRunState}'s existing callers.
+ */
+export async function readEpicRunCompletionState(access, epicRunId, fetchImpl = globalThis.fetch) {
+    if (typeof epicRunId !== "string" || epicRunId.trim().length === 0) {
+        return { ok: false, reason: "invalid-input" };
+    }
+    let parsed;
+    try {
+        parsed = await fetchEpicRunState(access, epicRunId, fetchImpl);
+    }
+    catch (err) {
+        if (err instanceof ConductorBridgeApiError) {
+            if (err.kind === "http" && err.status === 404)
+                return { ok: false, reason: "not-found" };
+            if (err.kind === "unauthorized")
+                return { ok: false, reason: "unauthorized" };
+            if (err.kind === "timeout")
+                return { ok: false, reason: "timeout" };
+            if (err.kind === "server")
+                return { ok: false, reason: "server" };
+            if (err.kind === "network")
+                return { ok: false, reason: "network" };
+            if (err.kind === "invalid-input")
+                return { ok: false, reason: "invalid-input" };
+            return { ok: false, reason: "malformed" };
+        }
+        return { ok: false, reason: "network" };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, reason: "malformed" };
+    }
+    const epicRun = parsed["epic_run"];
+    if (!epicRun || typeof epicRun !== "object" || Array.isArray(epicRun)) {
+        return { ok: false, reason: "malformed" };
+    }
+    const status = epicRun["status"];
+    if (!isEpicRunStatus(status)) {
+        return { ok: false, reason: "malformed" };
+    }
+    const policyJson = epicRun["policy_json"];
+    let featureBranch;
+    if (policyJson && typeof policyJson === "object" && !Array.isArray(policyJson)) {
+        const baseBranch = policyJson["base_branch"];
+        if (typeof baseBranch === "string" && baseBranch.trim().length > 0) {
+            featureBranch = baseBranch;
+        }
+    }
+    return { ok: true, state: featureBranch ? { status, featureBranch } : { status } };
+}
 /**
  * GET `/jira/epic-runs/runs?repo_name=<repo>&status=active` and return the
  * list of active epic runs. Caps at 20 results — enough for typical deployments
@@ -957,8 +1030,9 @@ function parseAdvanceEpicTicketStatusResult(parsed) {
  * PATCH the per-ticket CAS status endpoint
  * (`PATCH /runs/{epic_run_id}/tickets/{ticket_key}`). Surfaces structured CAS
  * conflicts as a distinct non-throwing outcome where the backend returns one;
- * the current backend instead raises a 400 VALIDATION on a stale row_version,
- * which surfaces as a thrown `ConductorBridgeApiError("http", 400)`.
+ * the current backend instead raises a 400 CONFLICT on a stale row_version
+ * (BAPI-1016 — the status stays 400; only the body error_code changed from the
+ * former VALIDATION), which surfaces as a thrown `ConductorBridgeApiError("http", 400)`.
  * Transport/auth/server failures still throw a sanitized {@link ConductorBridgeApiError}.
  */
 export async function advanceEpicTicketStatus(access, request, fetchImpl = globalThis.fetch) {
@@ -1283,6 +1357,8 @@ export async function validateEpicPlan(access, request, fetchImpl = globalThis.f
     };
     if (request.epicKey !== undefined)
         body.epic_key = request.epicKey;
+    if (request.trackedPaths !== undefined)
+        body.tracked_paths = request.trackedPaths;
     const parsed = await fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), JSON.stringify(body), CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
     return parseValidateEpicPlanResult(parsed);
 }
@@ -1295,7 +1371,8 @@ function parseValidateEpicPlanResult(parsed) {
     const planHash = p["plan_hash"];
     const serializationEnabled = p["serialization_enabled"];
     const insertedEdges = p["inserted_edges"];
-    if (p["valid"] !== true ||
+    const valid = p["valid"];
+    if (typeof valid !== "boolean" ||
         typeof planHash !== "string" ||
         planHash.trim() === "" ||
         typeof serializationEnabled !== "boolean" ||
@@ -1304,12 +1381,35 @@ function parseValidateEpicPlanResult(parsed) {
         insertedEdges < 0) {
         throw new ConductorBridgeApiError("server");
     }
+    // BAPI-1027: `valid: false` is now a FIRST-CLASS, fully-verified answer rather
+    // than a protocol error. The historical strictness (throw on anything but
+    // `valid === true`) existed because a body claiming a verdict without carrying
+    // one is false assurance — but a rejection body carries its reasons, so the
+    // caller can verify exactly what it is being told. That guard is preserved
+    // where it still applies: a `valid: false` with no parseable rejection asserts
+    // a failure it does not substantiate, and is still a protocol error.
+    const rejections = parsePlanLintRejections(p["rejections"]);
+    const notices = parsePlanLintNotices(p["notices"]);
+    if (!valid && rejections.length === 0) {
+        throw new ConductorBridgeApiError("server");
+    }
     // BAPI-848 — the coverage diagnostics are read TOLERANTLY, unlike the fields
     // above. A server that predates them is not a protocol error, and the CLI must
     // keep working against one; the defaults below are the honest reading of an
     // absent field (nothing reported), and the renderer states the scope it was
     // actually given rather than inventing coverage it cannot see.
     return {
+        valid,
+        rejections,
+        notices,
+        // BAPI-1027: read TOLERANTLY like the coverage fields, but defaulted to the
+        // SAFE reading. A server that predates this field reports nothing about
+        // completeness, and "we cannot tell whether every rule ran" must not render
+        // as a warning on every single validate against an older deployment — so an
+        // absent field means complete, while a present `false` is honored exactly.
+        evaluationComplete: typeof p["evaluation_complete"] === "boolean"
+            ? p["evaluation_complete"]
+            : true,
         planHash,
         serializationEnabled,
         insertedEdges,
@@ -1321,6 +1421,69 @@ function parseValidateEpicPlanResult(parsed) {
             : "unreported",
     };
 }
+/** Strict-but-tolerant parse of the `rejections` array; malformed entries are dropped. */
+function parsePlanLintRejections(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const entry = raw;
+        const reasonCode = entry["reason_code"];
+        const explanation = entry["explanation"];
+        // A finding without a code or an explanation cannot be rendered usefully and
+        // must not be counted as one: a phantom rejection would block a plan while
+        // telling the operator nothing about why.
+        if (typeof reasonCode !== "string" || reasonCode.trim() === "")
+            continue;
+        if (typeof explanation !== "string" || explanation.trim() === "")
+            continue;
+        const rejection = {
+            reasonCode,
+            explanation,
+            ticketKeys: safeStringArray(entry["ticket_keys"]),
+        };
+        if (typeof entry["path"] === "string" && entry["path"] !== "") {
+            rejection.path = entry["path"];
+        }
+        if (typeof entry["migration_id"] === "string" && entry["migration_id"] !== "") {
+            rejection.migrationId = entry["migration_id"];
+        }
+        out.push(rejection);
+    }
+    return out;
+}
+/** Strict-but-tolerant parse of the `notices` array; malformed entries are dropped. */
+function parsePlanLintNotices(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const entry = raw;
+        const noticeCode = entry["notice_code"];
+        const explanation = entry["explanation"];
+        if (typeof noticeCode !== "string" || noticeCode.trim() === "")
+            continue;
+        if (typeof explanation !== "string" || explanation.trim() === "")
+            continue;
+        out.push({
+            noticeCode,
+            explanation,
+            ticketKeys: safeStringArray(entry["ticket_keys"]),
+            paths: safeStringArray(entry["paths"]),
+        });
+    }
+    return out;
+}
+/** Non-empty strings from an array, or `[]` for anything else. */
+function safeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === "string" && v !== "");
+}
 /** Non-negative safe integer, or 0 for anything else (absent field included). */
 function safeCount(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
@@ -1341,12 +1504,15 @@ export async function storeEpicPlan(access, request, fetchImpl = globalThis.fetc
         throw new ConductorValidationError(`planVersion mismatch: request.planVersion=${request.planVersion} but planBlob.plan_version=${blobVersion}`);
     }
     const url = buildConductorJiraUrl(access.baseUrl, `${epicRunApiPath(request.epicKey)}/plan`);
-    const body = JSON.stringify({
+    const storeBody = {
         repo_name: access.repoName,
         plan_version: request.planVersion,
         plan_blob: request.planBlob,
         plan_hash: request.planHash,
-    });
+    };
+    if (request.trackedPaths !== undefined)
+        storeBody.tracked_paths = request.trackedPaths;
+    const body = JSON.stringify(storeBody);
     return fetchConductorJsonPostWithTimeout(url, conductorPostHeaders(access), body, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
 }
 /**

package/build/conductor/deny-enforcement-preflight.js

@@ -1,10 +1,15 @@
 /**
  * Executor deny-enforcement preflight (TDD §7 / §11, R8).
  *
- * v2's permission model is "skip-permissions + a deterministic deny-layer": workers
- * run `claude -p … --dangerously-skip-permissions` with a small stable deny set. But
- * whether `permissions.deny` is actually enforced under `--dangerously-skip-permissions`
- * is version-specific and must be PROBED, never assumed. This module exports the single
+ * v2's permission model since BAPI-1020 is "the `auto` posture + a deterministic
+ * deny layer + an always-on argument guard": workers run
+ * `claude -p … --permission-mode auto` with a small stable deny set, and
+ * `--dangerously-skip-permissions` is the explicit REVERT value rather than the
+ * default. Whether `permissions.deny` is actually enforced under a given posture is
+ * version-specific and must be PROBED, never assumed — and BOTH postures are probed,
+ * for different reasons: `auto` because it is what every worker runs under, and
+ * bypass because it stays selectable and must stay guarded. A posture that is not
+ * enforced is fatal regardless of which one it is. This module exports the single
  * reusable predicate the T3a executor's claim loop calls at startup/preflight before
  * claiming any job: on a failed deny probe with no working fallback it returns
  * `enforced: false`, and the executor must refuse to claim jobs (a fatal finding).
@@ -19,15 +24,28 @@ import { resolveAgentSpec } from "../agent-registry.js";
 import { createProbeContext } from "../agent-capabilities/probe-context.js";
 import { createDefaultAgentCapabilitiesDeps } from "../agent-capabilities/default-deps.js";
 import { runDenyEnforcementCheck } from "../agent-capabilities/probes.js";
+/**
+ * The postures probed when a caller names none (BAPI-1020).
+ *
+ * `auto` FIRST, deliberately: it is the posture every worker runs under, so when
+ * enforcement is broken the run that proves it is the one that matters, and the
+ * short-circuit below then skips the second probe entirely rather than spending
+ * minutes of real headless Claude runs re-confirming a fatal result.
+ */
+export const REQUIRED_DENY_ENFORCEMENT_POSTURES = [
+    "auto",
+    "skip_permissions",
+];
 /** Canonical refuse-to-claim directive included in every fatal/degraded-fatal result. */
 const REFUSE_TO_CLAIM_WARNING = "The executor claim loop MUST refuse to claim jobs until settings permissions.deny " +
     "or the PreToolUse fallback enforces the deny layer.";
 /**
- * Run the deny-enforcement preflight and map the shared deny-check outcome onto the
- * standard inspection shape. Never throws — unexpected exceptions become a fatal
- * `enforced: false` result. Always cleans up the probe context's temp dirs.
+ * Run the deny-enforcement preflight for ONE posture and map the shared
+ * deny-check outcome onto the standard inspection shape. Never throws —
+ * unexpected exceptions become a fatal `enforced: false` result. Always cleans up
+ * the probe context's temp dirs.
  */
-export async function runDenyEnforcementPreflight(opts = {}) {
+async function runDenyEnforcementPreflightForPosture(posture, opts) {
     try {
         const agent = resolveAgentSpec("claude");
         if (!agent) {
@@ -47,7 +65,7 @@ export async function runDenyEnforcementPreflight(opts = {}) {
             const { result, layer } = await runDenyEnforcementCheck(ctx, {
                 model: opts.model,
                 timeoutMs: opts.timeoutMs,
-                permissionPosture: opts.permissionPosture,
+                permissionPosture: posture,
             });
             if (result.status === "pass" && layer === "settings-deny") {
                 return {
@@ -65,7 +83,8 @@ export async function runDenyEnforcementPreflight(opts = {}) {
                     layer: "pretooluse-hook",
                     degraded: true,
                     warnings: [
-                        "settings permissions.deny was not enforced under --dangerously-skip-permissions; relying on PreToolUse fallback.",
+                        `settings permissions.deny was not enforced under the ${posture ?? "skip_permissions"} ` +
+                            "posture; relying on PreToolUse fallback.",
                     ],
                     status: result.status,
                     detail: result.detail,
@@ -95,3 +114,81 @@ export async function runDenyEnforcementPreflight(opts = {}) {
         };
     }
 }
+/**
+ * Run the deny-enforcement preflight and return the executor's claim gate.
+ *
+ * With an explicit `permissionPosture`, probes exactly that posture and returns
+ * its result unchanged — the single-posture behavior every existing caller and
+ * test seam relies on.
+ *
+ * With no posture named, probes {@link REQUIRED_DENY_ENFORCEMENT_POSTURES} in
+ * order and combines (BAPI-1020). Three properties of that combination matter:
+ *
+ *   - FATAL IF EITHER FAILS. `enforced` is the conjunction, so a posture that is
+ *     not enforced blocks claiming even when the other one is. There is no
+ *     "mostly enforced".
+ *   - SHORT-CIRCUITS ON THE FIRST FAILURE. Each posture costs several real
+ *     headless Claude runs and takes minutes; once the answer is fatal, the
+ *     remaining postures cannot change it, and burning the time to re-confirm it
+ *     would delay every claim on a machine that is already refusing to claim.
+ *   - REPORTS EACH POSTURE SEPARATELY. `postures` carries every probed posture's
+ *     own layer and detail. The top-level `layer` is the FIRST required posture's
+ *     (`auto`, the one workers run under) rather than a merged string, so the
+ *     existing consumers — which read `layer` as "what enforced for a worker" —
+ *     keep reading a true answer, and the per-posture facts stay available beside
+ *     it instead of being collapsed into it.
+ */
+export async function runDenyEnforcementPreflight(opts = {}) {
+    if (opts.permissionPosture !== undefined) {
+        return runDenyEnforcementPreflightForPosture(opts.permissionPosture, opts);
+    }
+    const postures = [];
+    const warnings = [];
+    let combined;
+    let degraded = false;
+    for (const posture of REQUIRED_DENY_ENFORCEMENT_POSTURES) {
+        const result = await runDenyEnforcementPreflightForPosture(posture, opts);
+        postures.push({
+            posture,
+            enforced: result.enforced,
+            layer: result.layer,
+            ...(result.status === undefined ? {} : { status: result.status }),
+            ...(result.detail === undefined ? {} : { detail: result.detail }),
+        });
+        for (const warning of result.warnings) {
+            if (!warnings.includes(warning))
+                warnings.push(warning);
+        }
+        if (result.degraded)
+            degraded = true;
+        if (combined === undefined)
+            combined = result;
+        if (!result.enforced) {
+            // Fatal already. Naming the posture is the diagnostic that matters: "deny is
+            // unenforced" is not actionable until an operator knows WHICH posture, since
+            // the fix for the worker default and the fix for the revert value differ.
+            return {
+                enforced: false,
+                layer: result.layer,
+                degraded: true,
+                warnings: [
+                    `Deny-layer enforcement is not verified for the '${posture}' permission posture.`,
+                    ...warnings,
+                ],
+                ...(result.status === undefined ? {} : { status: result.status }),
+                ...(result.detail === undefined ? {} : { detail: result.detail }),
+                postures,
+            };
+        }
+    }
+    const primary = combined;
+    return {
+        enforced: true,
+        layer: primary.layer,
+        degraded,
+        warnings,
+        ...(primary.status === undefined ? {} : { status: primary.status }),
+        ...(primary.detail === undefined ? {} : { detail: primary.detail }),
+        postures,
+    };
+}