@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/epic-implementer-bundle-cli.js

@@ -27,7 +27,10 @@ const USAGE = [
     "  validate   Validate identities, the node->ticket mapping, manifest agreement,",
     "             and path containment. Writes nothing.",
     "  finalize   Validate, then finalize epic-plan.dag.json with real keys and",
-    "             per-node touched_files, and write the sibling-ticket manifest.",
+    "             per-node touched_files, write the sibling-ticket manifest, and",
+    "             write epic-plan.meta.json ({\"epic_key\": ...}) beside the DAG so",
+    "             drive-epic can find the plan from the epic key. Each file is a",
+    "             separate atomic write, not one transaction across all three.",
     "",
     "Options:",
     "  --input <file>     JSON document with epic_key, epic_slug, mappings,",
@@ -235,6 +238,15 @@ export async function runEpicImplementerBundleCli(argv, overrides = {}) {
     const manifestWrite = await writeJsonAtomically(validation.value.manifest_path, manifest, deps.fs);
     if (!manifestWrite.ok)
         return emitFailure(manifestWrite.error);
+    // BAPI-1285: the discovery metadata is written LAST, and separately from the
+    // DAG on purpose — the sidecar goes to the server, whose epic-run models
+    // forbid extra fields. A failure here must never read as success, but the
+    // earlier artifacts are already final, so the message says so.
+    const metaWrite = await writeJsonAtomically(validation.value.meta_path, { epic_key: validation.value.epic_key }, deps.fs);
+    if (!metaWrite.ok) {
+        return emitFailure(`Could not write meta_path ${validation.value.meta_path}. The sidecar and manifest may ` +
+            "already be finalized. Re-run finalize, or check write permissions on the docs directory.");
+    }
     const result = {
         ok: true,
         mode: "finalize",
@@ -242,6 +254,7 @@ export async function runEpicImplementerBundleCli(argv, overrides = {}) {
         plan_version: validation.value.plan_version,
         sidecar_path: validation.value.sidecar_path,
         manifest_path: validation.value.manifest_path,
+        meta_path: validation.value.meta_path,
         ticket_keys: validation.value.mappings.map((m) => m.ticket_key),
     };
     if (opts.json)

package/build/epic-launch-profile.js

@@ -317,8 +317,11 @@ export async function writeEpicLaunchProfile(profile, deps) {
  *    `BAPI_BASE_URL` that names a DIFFERENT endpoint is a conflict — an override
  *    alone never rebinds a profile; guided setup does that.
  *  - Without one, `--base-url` and `BAPI_BASE_URL` must agree when both are set.
- *  - Nothing set is `target-missing`. There is no production default here:
- *    production is supported, but only as a deliberate selection.
+ *  - Nothing set uses the caller's `defaultBaseUrl` (source `"default"`), which
+ *    is validated only on that branch, so it can never change an explicit
+ *    outcome or mask a conflict. `drive-epic` passes production. A caller that
+ *    passes no default — guided setup, which writes a binding and a profile and
+ *    so needs a deliberate target — gets `target-missing`.
  *
  * Messages name the source and the rule only — never a URL, which can carry
  * userinfo.
@@ -377,12 +380,18 @@ export function resolveEpicLaunchTarget(inputs) {
         return { ok: true, baseUrl: flag.value, source: "flag" };
     if (env.value !== null)
         return { ok: true, baseUrl: env.value, source: "env" };
+    if (inputs.defaultBaseUrl !== undefined) {
+        const fallback = normalize(inputs.defaultBaseUrl, "default Bridge API target");
+        if (!fallback.ok)
+            return { ok: false, kind: "target-invalid", message: fallback.message };
+        if (fallback.value !== null)
+            return { ok: true, baseUrl: fallback.value, source: "default" };
+    }
     return {
         ok: false,
         kind: "target-missing",
-        message: "No Bridge API target is selected for this epic launch. Pass --launch-profile <name> (created by " +
-            `\`npx -y ${MCP_PACKAGE_NAME} install conductor --launch-profile <name> --base-url <url>\`), or ` +
-            "--base-url <url>. Nothing defaults to production.",
+        message: "No Bridge API target is selected. Pass --base-url <url> or set BAPI_BASE_URL to the server " +
+            "this setup should approve.",
     };
 }
 // ---------------------------------------------------------------------------

package/build/epic-run-status.js

@@ -0,0 +1,5 @@
+export const TERMINAL_EPIC_RUN_STATUSES = ["abandoned", "done"];
+/** True when `status` names a finished run. Unknown strings are NOT terminal. */
+export function isTerminalEpicRunStatus(status) {
+    return TERMINAL_EPIC_RUN_STATUSES.includes(status);
+}

package/build/epic-shared/bridge-client.js

@@ -657,6 +657,36 @@ export async function reclaimIndexScope(access, request, fetchImpl = globalThis.
         },
     };
 }
+const AUTOMATION_QUEUE_VERDICTS = [
+    "ok",
+    "working_backlog",
+    "undrained",
+    "unknown",
+];
+/**
+ * Narrow the optional `automation_queue` block. Anything not shaped like the
+ * BAPI-1299 contract is `null`, so a consumer reports it as unavailable.
+ */
+export function parseAutomationQueueHealth(raw) {
+    if (!isRecord(raw))
+        return null;
+    const status = raw["status"];
+    const verdict = raw["verdict"];
+    if (status !== "readable" && status !== "unreadable")
+        return null;
+    if (typeof verdict !== "string" || !AUTOMATION_QUEUE_VERDICTS.includes(verdict))
+        return null;
+    const count = raw["queued_count"];
+    const age = raw["oldest_queued_age_seconds"];
+    const evidence = raw["has_fresh_drainer_evidence"];
+    return {
+        status,
+        verdict: verdict,
+        queuedCount: typeof count === "number" && Number.isFinite(count) ? count : null,
+        oldestQueuedAgeSeconds: typeof age === "number" && Number.isFinite(age) ? age : null,
+        hasFreshDrainerEvidence: typeof evidence === "boolean" ? evidence : null,
+    };
+}
 /**
  * Epic-run statuses that mean a v2 conductor may still be driving the run.
  *
@@ -681,9 +711,10 @@ const ACTIVE_EPIC_RUN_STATUSES = [
 /**
  * `GET /automation/health?repo_name=` — read-only parse-dispatcher liveness.
  *
- * Root-mounted, NOT under `/jira`. The response is narrowed to two safe fields;
- * signals, stale-ticket samples, queue contents, and every timestamp are
- * deliberately dropped — an advisory line needs a verdict, not a report.
+ * Root-mounted, NOT under `/jira`. The response is narrowed to two safe fields,
+ * plus (BAPI-1299) the automation-queue verdict and its three counts; signals,
+ * stale-ticket samples, queue contents, and every timestamp are deliberately
+ * dropped — an advisory line needs a verdict, not a report.
  *
  * `absent` is claimed ONLY on positive evidence: a `stale` or `never_seen`
  * heartbeat together with a responding process that is not itself sweeping.
@@ -704,6 +735,7 @@ export async function getParseDispatcherHealth(access, fetchImpl = globalThis.fe
             value: { observation: "unavailable", heartbeatState: null, respondingSchedulerRunning: false },
         };
     }
+    const automationQueue = parseAutomationQueueHealth(result.value["automation_queue"]);
     const reconciler = isRecord(result.value["reconciler"]) ? result.value["reconciler"] : null;
     const scheduler = isRecord(result.value["scheduler"]) ? result.value["scheduler"] : null;
     const rawState = reconciler === null ? undefined : reconciler["state"];
@@ -722,7 +754,17 @@ export async function getParseDispatcherHealth(access, fetchImpl = globalThis.fe
     else {
         observation = "unavailable";
     }
-    return { ok: true, value: { observation, heartbeatState, respondingSchedulerRunning } };
+    // BAPI-1299: the queue block is added only when the server sent a
+    // well-formed one, so an older server's result keeps its exact prior shape.
+    return {
+        ok: true,
+        value: {
+            observation,
+            heartbeatState,
+            respondingSchedulerRunning,
+            ...(automationQueue !== null ? { automationQueue } : {}),
+        },
+    };
 }
 /**
  * `GET /jira/epic-runs/runs?repo_name=` — live v2 conductor runs on THIS repo.

package/build/executor/cli.js

@@ -6,6 +6,7 @@
  * the MCP server; all user-facing diagnostics go to stderr; secrets are never
  * printed. Returns numeric exit codes rather than throwing at the top level.
  */
+import { unlink } from "node:fs/promises";
 import os from "node:os";
 import { VERSION } from "../version.generated.js";
 import { resolveWorktrunkBinary } from "../start-tickets-prereqs.js";
@@ -20,6 +21,7 @@ import { createIntegrationActionHttpClient, } from "./integration-job.js";
 import { startExecutorSleepAssertion } from "./platform.js";
 import { runExecutor } from "./runner.js";
 import { runExecutorWatchCli } from "./watch-cli.js";
+import { removeRunExecutorRecordIfOwned } from "../executor-launch.js";
 /** Fixed executor timing/behavior defaults. */
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
@@ -48,6 +50,9 @@ export function getExecutorUsage() {
         "                                Exactly one of --epic-run-id or --repo-wide is",
         "                                REQUIRED; omitting both is a startup error, not",
         "                                repository-wide claiming (BAPI-1026 / R54).",
+        "  --exit-when-run-terminal      Exit 0 once the ONE --epic-run-id run is done or",
+        "                                abandoned and no job is held (BAPI-1279). Valid",
+        "                                only with exactly one --epic-run-id.",
         "  --base-url <url>              Bridge API endpoint (overrides BAPI_BASE_URL).",
         "  --executor-id <id>            Stable executor id (default: <hostname>-<pid>).",
         "  --max-concurrent <n>          Max concurrent jobs (>= 1, default 1).",
@@ -80,6 +85,7 @@ export function parseExecutorArgs(argv, context) {
     const repos = [];
     const epicRunIds = [];
     let repoWide = false;
+    let exitWhenRunTerminal = false;
     let scrubInheritedGithubCredentials = false;
     let executorId;
     let maxConcurrent = DEFAULT_MAX_CONCURRENT;
@@ -126,6 +132,9 @@ export function parseExecutorArgs(argv, context) {
         else if (arg === "--repo-wide") {
             repoWide = true;
         }
+        else if (arg === "--exit-when-run-terminal") {
+            exitWhenRunTerminal = true;
+        }
         else if (arg === "--scrub-inherited-github-credentials") {
             scrubInheritedGithubCredentials = true;
         }
@@ -208,6 +217,15 @@ export function parseExecutorArgs(argv, context) {
     if (!scope.ok) {
         return { kind: "error", message: scope.message };
     }
+    // BAPI-1279 — "exit when THE run is finished" needs exactly one run to watch.
+    // With several, or with --repo-wide, there is no single run whose end means
+    // this process is done, so the combination is refused before startup.
+    if (exitWhenRunTerminal && epicRunIds.length !== 1) {
+        return {
+            kind: "error",
+            message: "--exit-when-run-terminal requires exactly one --epic-run-id (and no --repo-wide)",
+        };
+    }
     const options = {
         executorId: executorIdFinal,
         repos,
@@ -237,6 +255,8 @@ export function parseExecutorArgs(argv, context) {
         // BAPI-1026 (R54) — same "truly absent, never a falsy placeholder"
         // discipline: `repoWide` is either `true` or the key is missing.
         ...(repoWide ? { repoWide: true } : {}),
+        // BAPI-1279 — same discipline: `true` or absent.
+        ...(exitWhenRunTerminal ? { exitWhenRunTerminal: true } : {}),
         // BAPI-1137: absent unless explicitly requested, so an ordinary executor's
         // options object is byte-for-byte what it was before this slice.
         ...(scrubInheritedGithubCredentials ? { scrubInheritedGithubCredentials: true } : {}),
@@ -401,6 +421,25 @@ export async function runExecutorCli(argv, overrides = {}) {
     const createIntegrationClient = overrides.createIntegrationClient ?? createIntegrationActionHttpClient;
     const runnerSeams = {
         onSignal: overrides.onSignal ?? defaultSignalRegistrar,
+        // BAPI-1279 — on a terminal exit, delete the launcher record drive-epic
+        // wrote for this run, but only if it still names THIS instance (its id, and
+        // this process or the relay that started it). Advisory: a failure here
+        // never changes the exit code.
+        ...(options.exitWhenRunTerminal === true
+            ? {
+                onRunTerminal: async (epicRunId) => {
+                    await removeRunExecutorRecordIfOwned({
+                        repoRoot: deps.cwd,
+                        epicRunId,
+                        executorId: options.executorId,
+                        pids: [context.pid, process.ppid],
+                    }, {
+                        readFile: deps.readFile,
+                        unlink: (filePath) => unlink(filePath),
+                    });
+                },
+            }
+            : {}),
         integrationActions: createIntegrationClient({
             baseUrl,
             apiKey: apiKeyByRepo[options.repoName],

package/build/executor/completion-contract.js

@@ -0,0 +1,423 @@
+/**
+ * The required-work completion-evidence contract (BAPI-1301, D4a) — executor
+ * mirror of `src/python/llms/executor_completion_contract.py`.
+ *
+ * A covered child attempt (`implement`, `resume`, `remediate`, `ci_fix`) that
+ * was claimed under the `completion_evidence.v1` requirement reports its
+ * terminal outcome with one bounded, versioned envelope built from facts the
+ * EXECUTOR observed: the stream-json lifecycle it read to EOF, the processes it
+ * swept, and the finalization facts it verified. The server re-validates the
+ * envelope against the claimed row and refuses success unless the envelope
+ * proves the attempt finished its required work and cleaned up after itself.
+ *
+ * What the envelope proves, and what it does not:
+ *  - A task that ended `succeeded` proves its LIFECYCLE ended. It does not prove
+ *    the check it ran is correct or that an effect it attempted was authorized.
+ *    Declared checks are run by the executor itself (D4c) and reported through
+ *    `verification`.
+ *  - `cleanup.verdict: "confirmed"` covers processes that kept the inherited
+ *    environment. Every covered verdict names `residual_not_covered`: a daemon
+ *    that detaches AND clears its environment carries no tag and is invisible to
+ *    the sweep on macOS. The controlled workload excludes it.
+ *
+ * Nothing in the envelope is a prompt, a raw tool argument, a provider payload,
+ * a process argument, an environment value, a path, or a URL. Inputs and targets
+ * cross the wire only as SHA-256 digests.
+ */
+import { createHash } from "node:crypto";
+/** The capability string declared on `POST /claim` and required by covered jobs. */
+export const COMPLETION_EVIDENCE_CAPABILITY = "completion_evidence.v1";
+export const COMPLETION_CONTRACT_VERSION = 1;
+/**
+ * BAPI-1302 (D4c) — the envelope version that carries executor-run check facts
+ * in `verification_facts`. Sent for every job whose payload carries a
+ * required-verification declaration; version 1 otherwise.
+ */
+export const COMPLETION_CONTRACT_VERSION_V2 = 2;
+/**
+ * BAPI-1302 (D4c) — declared on `POST /claim` when this executor runs declared
+ * checks itself. A job carrying a declaration requires it, so an executor
+ * without the runner never claims one.
+ */
+export const REQUIRED_VERIFICATION_CAPABILITY = "required_verification.v1";
+export const COMPLETION_CONTRACT_MARKER_VALUES = ["completion_evidence.v1", "legacy"];
+export const COVERED_JOB_TYPES = ["implement", "resume", "remediate", "ci_fix"];
+/**
+ * The measured runtime identity (BAPI-1292 probe): Claude Code 2.1.282 on macOS
+ * arm64. A measured baseline, not a certification — any other CLI version or
+ * platform is unsupported until measured.
+ */
+export const SUPPORTED_COMPLETION_RUNTIME = {
+    adapter: "claude",
+    cli_version: "2.1.282",
+    platform: "darwin-arm64",
+    event_schema: "claude-stream-json.lifecycle.v1",
+};
+export const EVIDENCE_VALUES = ["sufficient", "insufficient"];
+export const INSUFFICIENT_REASON_VALUES = [
+    "no_init_event",
+    "no_result_turn",
+    "active_turn_at_close",
+    "live_required_work",
+    "stale_task_snapshot",
+    "late_activity_after_close",
+    "stdout_not_read_to_eof",
+    "stream_parse_error",
+    "stream_lost",
+    "stream_oversize",
+    "stream_truncated",
+    "event_conflict",
+    "event_unknown",
+    "ledger_capacity_exhausted",
+    "denial_capacity_exhausted",
+    "forced_kill_no_cli_teardown",
+    "no_process_exit",
+    "transport_failed_before_work",
+    "transport_failed_after_progress",
+    "allowance_exhausted",
+    "unsupported_runtime",
+    "binding_mismatch",
+    // Failed before any worker was launched: nothing to be incomplete, nothing to
+    // clean up. Alone, it is not a completion cause (see isNotLaunchedEnvelope).
+    "worker_not_launched",
+    // BAPI-1302: the job's required-verification declaration was unusable, so no
+    // worker was launched against a partial set of checks.
+    "declaration_refused",
+];
+export const EXECUTION_VALUES = ["complete", "incomplete", "unknown"];
+/**
+ * `not_declared` is "no declared local verification" — NOT a pass. `unavailable`
+ * means checks were declared but no runner is installed (D4c absent): a park.
+ */
+export const VERIFICATION_VALUES = [
+    "not_declared",
+    "passed",
+    "failed",
+    "unavailable",
+    "incomplete",
+];
+export const FINALIZATION_VALUES = ["ok", "unmet", "not_required", "unknown"];
+export const CLEANUP_VERDICT_VALUES = ["confirmed", "failed", "unconfirmed"];
+export const CLEANUP_RESIDUAL_ENV_SCRUBBING_DAEMON = "environment_scrubbing_daemon";
+/**
+ * The second accepted residual (BAPI-1301). macOS hides a platform (Apple-signed)
+ * binary's environment from `ps -E`, so `/bin/bash`, `/bin/zsh` or `/bin/sleep`
+ * shows no tag. Tracked descendants cover the common case; a platform-binary
+ * process that detaches from the tracked tree between samples (reparented to
+ * launchd) is not attributable. Named on every verdict; the server still
+ * requires only the scrubbing-daemon token.
+ */
+export const CLEANUP_RESIDUAL_PLATFORM_BINARY_ENV_HIDDEN = "platform_binary_environment_hidden";
+export const CLEANUP_REASON_VALUES = [
+    "survivors_detected",
+    "enumeration_failed",
+    "ownership_unverifiable",
+    "executor_interrupted",
+    "sweep_deadline_exhausted",
+    "not_run",
+];
+export const TASK_KIND_VALUES = [
+    "delegate",
+    "delegate_bg",
+    "bash_bg",
+    "monitor",
+    "bash_task",
+    "subagent_bash",
+    "task",
+];
+export const TASK_STATE_VALUES = [
+    "pending",
+    "succeeded",
+    "failed",
+    "stopped",
+    "withdrawn",
+    "replaced",
+    "unknown",
+    "conflict",
+];
+/** The only states that resolve a REQUIRED task. */
+export const TASK_RESOLVING_STATES = new Set([
+    "succeeded",
+    "replaced",
+]);
+export const DENIAL_OPERATION_VALUES = [
+    "push",
+    "pr_create",
+    "external_mutation",
+    "delegate",
+    "other",
+    "unknown",
+];
+export const DENIAL_STATE_VALUES = ["blocking", "historical", "unlinked", "ambiguous"];
+export const MISSING_CAPABILITY_VALUES = [
+    "declared_check_runner",
+    "permission_enforcement",
+    "focused_ci_repair",
+    "repaired_head_convergence",
+    "continuation",
+];
+/** BAPI-1302 — where a job's declaration came from. Neither `absent` nor `declared_empty` is a pass. */
+export const DECLARATION_PROVENANCE_VALUES = ["declared", "declared_empty", "absent", "refused"];
+/** BAPI-1302 — how one declared command ended, as the executor observed it. */
+export const CHECK_OUTCOME_VALUES = [
+    "exited_zero",
+    "exited_nonzero",
+    "timed_out",
+    "launch_error",
+    "cancelled",
+    "not_run",
+];
+/** BAPI-1302 — bounded reason for a non-zero outcome. Never exit text or output. */
+export const CHECK_REASON_VALUES = [
+    "declared_timeout",
+    "reservation_exhausted",
+    "stopped_after_interruption",
+    "ownership_lost",
+    "executor_cancelled",
+    "spawn_failed",
+];
+/**
+ * BAPI-1302 — what the executor saw of the final local artifact (full HEAD plus
+ * the TRACKED tree and index) around the checks. Only `stable` lets a result
+ * count. Untracked files are outside the guarantee.
+ */
+export const ARTIFACT_VALUES = [
+    "stable",
+    "not_observed",
+    "head_unreadable",
+    "dirty_before",
+    "head_moved",
+    "tracked_changed",
+    "unobservable_after",
+];
+export const MAX_CHECKS = 16;
+export const MAX_CHECK_DURATION_MS = 2 * 60 * 60 * 1000;
+export const COMPLETION_CAUSE_VALUES = [
+    "required_work_incomplete",
+    "required_check_failed",
+    "permission_stop",
+    "unsupported_completion_evidence",
+    "cleanup_unconfirmed",
+    "verification_runner_unavailable",
+];
+export const MAX_TASKS = 64;
+export const MAX_DENIALS = 32;
+export const MAX_IDENTIFIER_CHARS = 128;
+export const MAX_SERIALIZED_BYTES = 32 * 1024;
+/** One stream-json event larger than this is `stream_oversize`, never parsed. */
+export const MAX_EVENT_BYTES = 1024 * 1024;
+const IDENTIFIER_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+export function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+/** A stable digest of a structured value (sorted keys). Never the value itself. */
+export function digestStructured(value) {
+    return sha256Hex(stableStringify(value));
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value ?? null);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+/** An opaque identifier, or null when the value cannot be carried safely. */
+export function boundedIdentifier(value) {
+    if (typeof value !== "string")
+        return null;
+    if (value.length === 0 || value.length > MAX_IDENTIFIER_CHARS)
+        return null;
+    return IDENTIFIER_RE.test(value) ? value : null;
+}
+export function isCoveredJobType(jobType) {
+    return COVERED_JOB_TYPES.includes(jobType);
+}
+/** Whether a claimed job carries the covered completion contract. */
+export function claimRequiresCompletionEvidence(requiredCapabilities) {
+    return Array.isArray(requiredCapabilities) && requiredCapabilities.includes(COMPLETION_EVIDENCE_CAPABILITY);
+}
+export function runtimeMatchesSupported(runtime) {
+    if (!runtime)
+        return false;
+    return (runtime.adapter === SUPPORTED_COMPLETION_RUNTIME.adapter &&
+        runtime.cli_version === SUPPORTED_COMPLETION_RUNTIME.cli_version &&
+        runtime.platform === SUPPORTED_COMPLETION_RUNTIME.platform &&
+        runtime.event_schema === SUPPORTED_COMPLETION_RUNTIME.event_schema);
+}
+export function unresolvedRequiredTasks(envelope) {
+    return envelope.tasks.filter((t) => t.required && !TASK_RESOLVING_STATES.has(t.state));
+}
+const FULL_SHA_RE = /^[0-9a-f]{40}$/;
+/**
+ * The verification verdict version-2 facts support. Mirrors the server's
+ * `verification_verdict_from_facts` clause for clause; the envelope's
+ * `verification` token must equal it or the server refuses the envelope.
+ *
+ * `declaredCount` is the number of commands the job's declaration names; a
+ * declared command with no fact is not-run, so the verdict is `incomplete`.
+ */
+export function verificationVerdictFromFacts(facts, declaredCount) {
+    if (facts.provenance === "absent" || facts.provenance === "declared_empty")
+        return "not_declared";
+    if (facts.provenance !== "declared")
+        return "incomplete";
+    const expected = declaredCount ?? facts.commands.length;
+    if (expected === 0 || facts.commands.length !== expected)
+        return "incomplete";
+    if (facts.artifact !== "stable" || facts.tested_head_sha === null || !FULL_SHA_RE.test(facts.tested_head_sha)) {
+        return "incomplete";
+    }
+    if (facts.commands.some((c) => c.outcome !== "exited_zero" && c.outcome !== "exited_nonzero"))
+        return "incomplete";
+    if (facts.commands.some((c) => c.outcome === "exited_nonzero"))
+        return "failed";
+    return "passed";
+}
+/**
+ * Closed reason the envelope cannot support a covered success, or null.
+ * Mirrors the server's `success_refusal_reason` clause for clause, so the
+ * executor never sends `/complete` for an envelope the server would refuse.
+ */
+export function successRefusalReason(envelope) {
+    if (envelope.evidence !== "sufficient")
+        return "evidence_insufficient";
+    if (envelope.execution !== "complete")
+        return "execution_not_complete";
+    if (unresolvedRequiredTasks(envelope).length > 0)
+        return "required_task_unresolved";
+    if (envelope.verification !== "passed" && envelope.verification !== "not_declared") {
+        return "verification_not_acceptable";
+    }
+    if (envelope.finalization !== "ok" && envelope.finalization !== "not_required") {
+        return "finalization_not_met";
+    }
+    if (envelope.cleanup.verdict !== "confirmed" || envelope.cleanup.survivors !== 0) {
+        return "cleanup_not_confirmed";
+    }
+    if (envelope.denials.some((d) => d.state === "blocking"))
+        return "blocking_denial";
+    if (envelope.cause !== null)
+        return "cause_present";
+    return null;
+}
+/**
+ * The executor-proposed cause for an envelope that cannot be a success. Same
+ * order as the server's `derive_park_cause`; the server re-derives it and never
+ * lets this value widen what the rest of the envelope proves.
+ */
+export function deriveCompletionCause(envelope) {
+    const reasons = new Set(envelope.insufficient_reasons);
+    if (reasons.has("unsupported_runtime"))
+        return "unsupported_completion_evidence";
+    if (isNotLaunchedEnvelope(envelope))
+        return null;
+    const blocking = envelope.denials.filter((d) => d.state === "blocking");
+    if (blocking.length > 0 && envelope.evidence === "sufficient" && blocking.some((d) => d.result_after_denial)) {
+        return "permission_stop";
+    }
+    if (envelope.cleanup.verdict !== "confirmed" || envelope.cleanup.survivors !== 0)
+        return "cleanup_unconfirmed";
+    const unresolved = envelope.tasks.some((t) => t.required && !TASK_RESOLVING_STATES.has(t.state));
+    if (blocking.length > 0 ||
+        envelope.evidence !== "sufficient" ||
+        envelope.execution !== "complete" ||
+        unresolved ||
+        envelope.verification === "incomplete") {
+        return "required_work_incomplete";
+    }
+    if (envelope.verification === "unavailable")
+        return "verification_runner_unavailable";
+    if (envelope.verification === "failed")
+        return "required_check_failed";
+    // Nothing completion-specific is wrong: an unmet finalization (or success)
+    // keeps its existing executor/server classification.
+    return null;
+}
+/**
+ * Whether an envelope reports a failure before any worker was launched: exactly
+ * the `worker_not_launched` reason, no task/denial/result, confirmed cleanup with
+ * zero survivors. Mirrors the server's `is_not_launched_envelope`.
+ */
+export function isNotLaunchedEnvelope(envelope) {
+    return (envelope.insufficient_reasons.length === 1 &&
+        envelope.insufficient_reasons[0] === "worker_not_launched" &&
+        envelope.tasks.length === 0 &&
+        envelope.denials.length === 0 &&
+        envelope.results_seen === 0 &&
+        envelope.cleanup.verdict === "confirmed" &&
+        envelope.cleanup.survivors === 0);
+}
+/**
+ * The envelope for a covered attempt that failed before any worker existed.
+ *
+ * Every covered terminal report must carry an envelope; without one the server
+ * refuses the report and the row eventually dead-letters as cleanup
+ * unconfirmed — parking a transient pre-spawn problem for a human with a
+ * misleading cause. Nothing was spawned, so cleanup is truthfully confirmed with
+ * zero survivors, and the report's own error kind keeps deciding.
+ */
+export function buildNotLaunchedEnvelope(input) {
+    return {
+        evidence_version: input.verificationFacts ? COMPLETION_CONTRACT_VERSION_V2 : COMPLETION_CONTRACT_VERSION,
+        runtime: { ...input.runtime },
+        binding: { ...input.binding },
+        session_id: null,
+        evidence: "insufficient",
+        insufficient_reasons: ["worker_not_launched"],
+        execution: "unknown",
+        verification: input.verification,
+        finalization: "unknown",
+        cleanup: {
+            verdict: "confirmed",
+            method: "env_tag_sweep",
+            survivors: 0,
+            reasons: [],
+            residual_not_covered: [...input.residuals],
+        },
+        tasks: [],
+        denials: [],
+        missing_capabilities: [],
+        results_seen: 0,
+        cause: null,
+        ...(input.verificationFacts ? { verification_facts: input.verificationFacts } : {}),
+    };
+}
+/**
+ * Enforce the serialized bound. An envelope that would exceed it drops its
+ * lowest-value detail (resolved tasks, then historical/unlinked denials) and
+ * becomes `insufficient` — it never silently loses an unresolved obligation.
+ */
+export function boundEnvelope(envelope) {
+    const size = (e) => Buffer.byteLength(JSON.stringify(e), "utf8");
+    if (size(envelope) <= MAX_SERIALIZED_BYTES)
+        return envelope;
+    const markOversize = (e) => {
+        const reasons = new Set(e.insufficient_reasons);
+        reasons.add("ledger_capacity_exhausted");
+        const next = {
+            ...e,
+            evidence: "insufficient",
+            insufficient_reasons: [...reasons],
+            execution: e.execution === "complete" ? "unknown" : e.execution,
+            cause: null,
+        };
+        return { ...next, cause: deriveCompletionCause(next) };
+    };
+    let next = markOversize({
+        ...envelope,
+        tasks: envelope.tasks.filter((t) => t.required && !TASK_RESOLVING_STATES.has(t.state)),
+    });
+    if (size(next) <= MAX_SERIALIZED_BYTES)
+        return next;
+    next = markOversize({
+        ...next,
+        denials: next.denials.filter((d) => d.state === "blocking" || d.state === "ambiguous"),
+    });
+    if (size(next) <= MAX_SERIALIZED_BYTES)
+        return next;
+    // Last resort: identities cannot fit. Keep the count-free verdict only.
+    return markOversize({ ...next, tasks: next.tasks.slice(0, 8), denials: next.denials.slice(0, 8) });
+}