@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.9445952e33ba

package/dist/session/session.types.js

@@ -1,4 +1,15 @@
 import path from "node:path";
+import { redactText } from "../shared/redaction/redaction.js";
+export class ForgeFailureError extends Error {
+    failureCode;
+    failureSource;
+    constructor(failureCode, message, failureSource = "bridge", options) {
+        super(message, options);
+        this.name = "ForgeFailureError";
+        this.failureCode = normalizeFailureCode(failureCode);
+        this.failureSource = failureSource;
+    }
+}
 export function parseRunOnceDispatchPacket(value) {
     const packet = asObject(value, "dispatch packet");
     const schemaVersion = requiredNumber(packet, "schemaVersion");
@@ -34,6 +45,134 @@ export function parseRunOnceDispatchPacket(value) {
         draft: parseDraftPrompt(packet.draft)
     };
 }
+export function parseRunOnceResultPacket(value) {
+    const packet = asObject(value, "run-once result packet");
+    const schemaVersion = requiredNumber(packet, "schemaVersion");
+    if (schemaVersion !== 1 && schemaVersion !== 2) {
+        throw new Error(`Unsupported run-once result schemaVersion: ${schemaVersion}`);
+    }
+    const exitCode = requiredNumber(packet, "exitCode");
+    if (!Number.isSafeInteger(exitCode))
+        throw new Error("exitCode must be an integer.");
+    requiredString(packet, "summary");
+    if (!Array.isArray(packet.events))
+        throw new Error("events must be an array.");
+    for (const item of packet.events) {
+        if (typeof item !== "object" || item === null || !("wait" in item))
+            continue;
+        const event = asObject(item, "run-once result event");
+        if (event.wait !== undefined && event.wait !== null) {
+            parseWaitEnvelope(event.wait, requiredString(event, "eventType"));
+        }
+    }
+    if (schemaVersion === 1) {
+        if (packet.failure !== undefined && packet.failure !== null) {
+            throw new Error("run-once result schemaVersion 1 cannot contain a v2 failure envelope.");
+        }
+        return packet;
+    }
+    if (exitCode === 0 && packet.failure !== undefined && packet.failure !== null) {
+        throw new Error("run-once result cannot report both success and a failure envelope.");
+    }
+    if (exitCode !== 0 && (packet.failure === undefined || packet.failure === null)) {
+        throw new Error("run-once result schemaVersion 2 requires a failure envelope for a nonzero exit.");
+    }
+    if (packet.failure !== undefined && packet.failure !== null)
+        parseFailureEnvelope(packet.failure);
+    return packet;
+}
+const waitKinds = new Map([
+    ["host_runtime_admission_waiting", "host_runtime_admission"],
+    ["host_runtime_admission_acquired", "host_runtime_admission"],
+    ["host_runtime_serial_admission_waiting", "host_runtime_serial_admission"],
+    ["host_runtime_prepared_probe_started", "host_runtime_prepared_probe"],
+    ["host_runtime_prepared_probe_progress", "host_runtime_prepared_probe"],
+    ["host_runtime_prepared_probe_completed", "host_runtime_prepared_probe"],
+    ["host_runtime_prepared_admission_waiting", "host_runtime_prepared_admission"],
+    ["host_runtime_prepared_admission_acquired", "host_runtime_prepared_admission"],
+]);
+export function waitKindForEvent(eventType) {
+    const kind = waitKinds.get(eventType);
+    if (!kind)
+        throw new Error(`Unsupported typed wait observation '${eventType}'.`);
+    return kind;
+}
+export function waitWakeCondition(kind) {
+    switch (kind) {
+        case "host_runtime_serial_admission":
+            return "project_singleton_released";
+        case "host_runtime_prepared_probe":
+            return "prepared_runtime_probe_completed";
+        default:
+            return "host_runtime_admission_available";
+    }
+}
+function parseWaitEnvelope(value, eventType) {
+    const wait = asObject(value, "wait envelope");
+    if (requiredNumber(wait, "schemaVersion") !== 2) {
+        throw new Error("Unsupported wait envelope schemaVersion.");
+    }
+    let expectedKind;
+    try {
+        expectedKind = waitKindForEvent(eventType);
+    }
+    catch {
+        throw new Error("wait envelope is only valid on a wait lifecycle observation.");
+    }
+    const kind = requiredString(wait, "kind");
+    const scope = requiredString(wait, "scope");
+    const wakeCondition = requiredString(wait, "wakeCondition");
+    if (kind !== expectedKind
+        || !isWaitCode(kind, 80)
+        || !isWaitCode(scope, 64)
+        || !isWaitCode(wakeCondition, 80)
+        || wakeCondition !== waitWakeCondition(kind)) {
+        throw new Error("wait envelope kind, scope, or wakeCondition is invalid.");
+    }
+    if (!Array.isArray(wait.resourceKeys)
+        || wait.resourceKeys.length > 16
+        || wait.resourceKeys.some(item => typeof item !== "string" || !isWaitCode(item, 256))
+        || new Set(wait.resourceKeys).size !== wait.resourceKeys.length) {
+        throw new Error("wait envelope resourceKeys are invalid, duplicated, or exceed their bound.");
+    }
+    const queuePosition = wait.queuePosition;
+    if (queuePosition !== undefined && queuePosition !== null
+        && (typeof queuePosition !== "number" || !Number.isSafeInteger(queuePosition) || queuePosition <= 0)) {
+        throw new Error("wait envelope queuePosition is invalid.");
+    }
+    const blockerSessionId = wait.blockerSessionId;
+    if (blockerSessionId !== undefined && blockerSessionId !== null
+        && (typeof blockerSessionId !== "string"
+            || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(blockerSessionId)
+            || /^0{8}-0{4}-0{4}-0{4}-0{12}$/u.test(blockerSessionId))) {
+        throw new Error("wait envelope blockerSessionId is invalid.");
+    }
+    const blockerTitle = wait.blockerTitle;
+    if (blockerTitle !== undefined && blockerTitle !== null
+        && (typeof blockerTitle !== "string" || blockerTitle.length > 500)) {
+        throw new Error("wait envelope blockerTitle is invalid.");
+    }
+    const retryAt = wait.retryAt;
+    if (retryAt !== undefined && retryAt !== null
+        && (typeof retryAt !== "string" || !Number.isFinite(Date.parse(retryAt)))) {
+        throw new Error("wait envelope retryAt is invalid.");
+    }
+    const firstObservedAt = requiredString(wait, "firstObservedAt");
+    if (!Number.isFinite(Date.parse(firstObservedAt))) {
+        throw new Error("wait envelope firstObservedAt is invalid.");
+    }
+    const observationVersion = requiredNumber(wait, "observationVersion");
+    if (!Number.isSafeInteger(observationVersion) || observationVersion <= 0) {
+        throw new Error("wait envelope observationVersion is invalid.");
+    }
+    if (requiredString(wait, "contractOrigin") !== "bridge_v2") {
+        throw new Error("wait envelope contractOrigin must identify the v2 Bridge writer.");
+    }
+    return value;
+}
+function isWaitCode(value, maximumLength) {
+    return value.length <= maximumLength && /^[a-z][a-z0-9_.:-]*$/u.test(value);
+}
 function parseRuntimeIntent(value) {
     if (value === undefined || value === null) {
         return { executionClass: "managed_runtime", applicationRuntimeRequired: true };
@@ -171,17 +310,391 @@ function parseSandboxNetworkPolicy(value) {
     }
     return { mode, allowedHosts };
 }
-export function failureResult(summary, events = []) {
+const failureCodePattern = /^[a-z][a-z0-9_.-]{0,79}$/u;
+const failureCategories = new Set(["domain", "provider", "transport", "cancellation", "ownership", "resource", "unknown"]);
+const failurePhases = new Set(["offer", "build", "prepare", "agent", "validation", "import", "teardown", "unknown"]);
+const failureSources = new Set(["bridge", "provider", "sandbox", "unknown"]);
+const failureRetryabilities = new Set(["retryable", "non_retryable", "policy_required", "unknown"]);
+const failureOperatorActions = new Set(["none", "retry_dispatch", "retry_with_policy", "inspect_failure", "fix_input", "fix_environment", "reauthenticate", "restore_ownership"]);
+const maximumFailureMessageLength = 2000;
+const maximumFailureCausalChainLength = 8;
+const waitConditionCodes = new Set([
+    "host_runtime_admission_waiting",
+    "host_runtime_serial_admission_waiting",
+    "host_runtime_prepared_probe_started",
+    "host_runtime_prepared_probe_progress",
+    "host_runtime_prepared_admission_waiting",
+    "waiting_for_capacity",
+]);
+const stableFailureFamilyCodes = new Set([
+    "generated_output_reset_invalid",
+    "generated_output_reset_unsafe",
+    "sandbox_build_failed",
+    "sandbox_build_policy_failed",
+    "sandbox_builder_release_failed",
+    "sandbox_config_commit_invalid",
+    "sandbox_config_commit_missing",
+    "sandbox_config_commit_unapproved",
+    "contract_invalid",
+    "sandbox_input_failed",
+    "docker_capacity_unavailable",
+    "docker_engine_invalid_response",
+    "docker_engine_recovery_failed",
+    "docker_engine_recovery_timeout",
+    "docker_linux_required",
+    "docker_preflight_required",
+    "docker_rootless_required",
+    "docker_unavailable",
+    "docker_unreachable",
+    "sandbox_output_conflict",
+    "sandbox_output_invalid",
+    "sandbox_output_missing",
+    "sandbox_output_publish_forbidden",
+    "sandbox_output_rejected",
+    "sandbox_output_publish_rejected",
+    "sandbox_output_publish_stale",
+    "sandbox_output_publish_unavailable",
+    "sandbox_output_stale",
+    "sandbox_import_cancelled",
+    "sandbox_import_unavailable",
+    "teardown_failed",
+    "reaper_cleanup_degraded",
+    "reaper_runner_replaced",
+    "sandbox_egress_policy_invalid",
+    "sandbox_egress_proxy_unavailable",
+    "sandbox_event_flood",
+    "sandbox_event_invalid",
+    "sandbox_identity_invalid",
+    "sandbox_image_signature_failed",
+    "sandbox_log_limit",
+    "sandbox_preflight_failed",
+    "sandbox_security_profile_invalid",
+    "sandbox_security_profile_unavailable",
+    "sandbox_service_health_policy_invalid",
+]);
+export function failureResult(summary, events = [], facts = failureFactsForCode("bridge.execution_failed")) {
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         exitCode: 1,
-        summary,
-        events
+        summary: boundedFailureText(summary),
+        events,
+        failure: createFailureEnvelope(summary, facts),
+    };
+}
+export function createFailureEnvelope(message, facts, occurredAt = new Date().toISOString()) {
+    const code = normalizeFailureCode(facts.code);
+    if (waitConditionCodes.has(code)) {
+        throw new Error(`Wait condition '${code}' must be emitted as lifecycle state, not a terminal failure.`);
+    }
+    assertFailureFactsMatchPolicy(code, facts);
+    return {
+        schemaVersion: 2,
+        code,
+        message: boundedFailureText(message),
+        category: facts.category,
+        phase: facts.phase,
+        source: facts.source,
+        retryability: facts.retryability,
+        operatorAction: facts.operatorAction,
+        causalChain: (facts.causalChain ?? []).slice(0, maximumFailureCausalChainLength).map(cause => ({
+            code: normalizeFailureCode(cause.code),
+            message: boundedFailureText(cause.message),
+            source: cause.source,
+        })),
+        occurredAt,
+        contractOrigin: "bridge_v2",
+    };
+}
+export function failureFactsFromError(error, options = {}) {
+    if (options.cancelled) {
+        const cancellationSource = options.source ?? "bridge";
+        return {
+            ...failureFactsForCode("bridge.dispatch_cancelled", cancellationSource),
+            causalChain: errorCauseChain(error, cancellationSource),
+        };
+    }
+    const source = error instanceof ForgeFailureError
+        ? error.failureSource
+        : options.source ?? "bridge";
+    const code = error instanceof ForgeFailureError
+        ? error.failureCode
+        : "bridge.execution_failed";
+    return {
+        ...failureFactsForCode(code, source),
+        causalChain: errorCauseChain(error, source),
+    };
+}
+export function failureFactsForCode(code, source = "bridge") {
+    const policy = failurePolicyForCode(code);
+    if (policy.known && !policy.allowedSources.includes(source)) {
+        throw new Error(`Failure code '${policy.code}' cannot be attributed to source '${source}'.`);
+    }
+    return {
+        code: policy.code,
+        category: policy.category,
+        phase: policy.phase,
+        source,
+        retryability: policy.retryability,
+        operatorAction: policy.operatorAction,
     };
 }
+export function failurePolicyForCode(code) {
+    code = normalizeFailureCode(code);
+    const classification = unvalidatedFailureFactsForCode(code, "bridge");
+    const known = classification.category !== "unknown" || code === "legacy_failure_unknown";
+    return {
+        code,
+        category: classification.category,
+        phase: classification.phase,
+        retryability: classification.retryability,
+        operatorAction: classification.operatorAction,
+        allowedSources: allowedSourcesForCode(code, known),
+        known,
+    };
+}
+function unvalidatedFailureFactsForCode(code, source) {
+    code = normalizeFailureCode(code);
+    if (["bridge.dispatch_cancelled", "dispatch_cancelled", "dispatch_session_terminal", "dispatch.capacity_retargeted"].includes(code)) {
+        return facts(code, "cancellation", "teardown", source, "non_retryable", "none");
+    }
+    if (["bridge.dispatch_fence_conflict", "bridge.reservation_stale", "bridge.capacity_wait_lost", "bridge.dispatch_attempt_missing"].includes(code)) {
+        return facts(code, "ownership", "offer", source, "non_retryable", "restore_ownership");
+    }
+    if (["reservation_expired", "bridge.lease_expired", "bridge.stale_runner_instance", "bridge.runner_replaced"].includes(code)) {
+        return facts(code, "ownership", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (["bridge.dispatch_failed", "bridge.execution_failed", "bridge.cli_execution_failed", "bridge_callback_timeout"].includes(code)) {
+        return facts(code, "transport", "unknown", source, "policy_required", "inspect_failure");
+    }
+    if (code === "bridge.unavailable") {
+        return facts(code, "transport", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (["capacity_unavailable", "bridge.runner_draining", "docker_engine_unavailable", "docker_memory_low", "docker_memory_sample_unavailable", "docker_cpu_low", "docker_disk_low", "server_local.resource_pressure", "server_local.capacity_unavailable", "dispatch.preparation_resource_pressure", "sandbox_capacity_profile_unavailable", "host_runtime_admission_expired"].includes(code)) {
+        return facts(code, "resource", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (["bridge.lease_retry_exhausted", "bridge.capacity_wait_exhausted"].includes(code)) {
+        return facts(code, "resource", "offer", source, "non_retryable", "inspect_failure");
+    }
+    if (["prepublication_infrastructure_failed", "prepublication_capability_unavailable"].includes(code)) {
+        return facts(code, "resource", "validation", source, "retryable", "retry_with_policy");
+    }
+    if (["prepublication_validation_failed", "prepublication_contract_invalid", "prepublication_execution_scope_invalid"].includes(code)) {
+        return facts(code, "domain", "validation", source, "non_retryable", "fix_input");
+    }
+    if (["generated_output_reset_failed", "generated_output_reset_unverified", "worktree_prepare_failed", "host_runtime_ledger_write_failed", "host_diagnostics_temporary_unavailable", "attempt_process_supervisor_start_failed", "attempt_process_supervisor_start_timeout"].includes(code)) {
+        return facts(code, "transport", "prepare", source, "retryable", "retry_dispatch");
+    }
+    if (stableFailureFamilyCodes.has(code) && code.startsWith("generated_output_reset_")) {
+        return facts(code, "domain", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (code === "provider_start_unavailable") {
+        return facts(code, "provider", "prepare", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_configuration_invalid") {
+        return facts(code, "provider", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (["host_port_collision", "host_runtime_process_exited", "host_runtime_listener_timeout", "host_runtime_http_readiness_timeout", "host_runtime_prepared_source_changed", "host_runtime_prepared_probe_incomplete", "host_runtime_prepared_probe_cleanup_unconfirmed"].includes(code)) {
+        return facts(code, "resource", "prepare", source, "retryable", "retry_dispatch");
+    }
+    if (code === "host_runtime_project_start_failed") {
+        return facts(code, "domain", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (stableFailureFamilyCodes.has(code) && (code.startsWith("sandbox_build") || code.startsWith("image_"))) {
+        const policyFailure = code === "sandbox_build_policy_failed";
+        return facts(code, "resource", "build", source, policyFailure ? "non_retryable" : "retryable", policyFailure ? "fix_environment" : "retry_dispatch");
+    }
+    if (code === "provider_network_policy_denied"
+        || stableFailureFamilyCodes.has(code) && (code.startsWith("sandbox_config") || code.startsWith("contract_") || code.startsWith("sandbox_input"))) {
+        return facts(code, "domain", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (stableFailureFamilyCodes.has(code) && code.startsWith("docker_")) {
+        return facts(code, "resource", "prepare", source, "non_retryable", "fix_environment");
+    }
+    if (code === "provider_network_unavailable") {
+        return facts(code, "transport", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_request_not_found") {
+        return facts(code, "provider", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_capacity_unavailable") {
+        return facts(code, "resource", "offer", source, "retryable", "retry_dispatch");
+    }
+    if (code === "provider_context_window_exhausted") {
+        return facts(code, "provider", "agent", source, "retryable", "retry_dispatch");
+    }
+    if (stableFailureFamilyCodes.has(code) && (code.startsWith("sandbox_output") || code.startsWith("sandbox_import"))) {
+        const retryable = code === "sandbox_import_unavailable" || code === "sandbox_output_publish_unavailable";
+        return facts(code, "transport", "import", source, retryable ? "retryable" : "non_retryable", retryable ? "retry_with_policy" : "inspect_failure");
+    }
+    if (stableFailureFamilyCodes.has(code) && (code.startsWith("teardown") || code.startsWith("reaper"))) {
+        return facts(code, "transport", "teardown", source, "retryable", "retry_with_policy");
+    }
+    if (["invalid_dispatch"].includes(code)) {
+        return facts(code, "domain", "offer", source, "non_retryable", "fix_input");
+    }
+    if ([
+        "bridge.api_key_auth_required",
+        "bridge.api_key_secret_grant_missing",
+        "bridge.api_key_secret_grant_denied",
+        "bridge.api_key_secret_grant_provider_mismatch",
+        "bridge.api_key_secret_missing",
+        "contract_plaintext_secret_rejected",
+    ].includes(code)) {
+        return facts(code, "domain", "prepare", source, "non_retryable", "reauthenticate");
+    }
+    if (code === "sandbox_idle_timeout") {
+        return facts(code, "provider", "agent", source, "retryable", "retry_with_policy");
+    }
+    if (code === "sandbox_wall_timeout") {
+        return facts(code, "provider", "agent", source, "retryable", "retry_with_policy");
+    }
+    if (["sandbox_oom_killed", "sandbox_pid_exhausted", "sandbox_file_descriptor_exhausted", "sandbox_storage_exhausted"].includes(code)) {
+        return facts(code, "resource", "agent", source, "non_retryable", "inspect_failure");
+    }
+    if (code === "sandbox_auth_unavailable") {
+        return facts(code, "domain", "prepare", source, "non_retryable", "reauthenticate");
+    }
+    if (code === "sandbox_lease_expired") {
+        return facts(code, "ownership", "agent", source, "non_retryable", "restore_ownership");
+    }
+    if (code === "sandbox_runtime_failed") {
+        return facts(code, "provider", "agent", source, "non_retryable", "inspect_failure");
+    }
+    if (code === "worktree_branch_integration_conflict") {
+        return facts(code, "domain", "agent", source, "non_retryable", "fix_input");
+    }
+    if (stableFailureFamilyCodes.has(code) && code.startsWith("sandbox_")) {
+        return facts(code, "provider", "agent", source, "non_retryable", "inspect_failure");
+    }
+    return facts(code, "unknown", "unknown", source, "unknown", "inspect_failure");
+}
+function parseFailureEnvelope(value) {
+    const failure = asObject(value, "failure");
+    if (requiredNumber(failure, "schemaVersion") !== 2)
+        throw new Error("failure.schemaVersion must be 2.");
+    const code = requiredString(failure, "code");
+    const message = requiredString(failure, "message");
+    const category = requiredString(failure, "category");
+    const phase = requiredString(failure, "phase");
+    const source = requiredString(failure, "source");
+    const retryability = requiredString(failure, "retryability");
+    const operatorAction = requiredString(failure, "operatorAction");
+    const occurredAt = requiredString(failure, "occurredAt");
+    const contractOrigin = requiredString(failure, "contractOrigin");
+    if (!failureCodePattern.test(code))
+        throw new Error("failure.code is invalid.");
+    if (message.length > maximumFailureMessageLength)
+        throw new Error("failure.message is too long.");
+    if (!failureCategories.has(category) || !failurePhases.has(phase) || !failureSources.has(source)
+        || !failureRetryabilities.has(retryability) || !failureOperatorActions.has(operatorAction)) {
+        throw new Error("failure contains an unsupported category, phase, source, retryability, or operator action.");
+    }
+    assertFailureFactsMatchPolicy(code, { code, category, phase, source, retryability, operatorAction });
+    if (!Number.isFinite(Date.parse(occurredAt)))
+        throw new Error("failure.occurredAt is invalid.");
+    if (contractOrigin !== "bridge_v2")
+        throw new Error("failure.contractOrigin must be bridge_v2.");
+    if (!Array.isArray(failure.causalChain) || failure.causalChain.length > maximumFailureCausalChainLength) {
+        throw new Error("failure.causalChain is invalid or too long.");
+    }
+    const causalChain = failure.causalChain.map((candidate, index) => {
+        const cause = asObject(candidate, `failure.causalChain[${index}]`);
+        const causeCode = requiredString(cause, "code");
+        const causeMessage = requiredString(cause, "message");
+        const causeSource = requiredString(cause, "source");
+        if (!failureCodePattern.test(causeCode) || causeMessage.length > maximumFailureMessageLength || !failureSources.has(causeSource)) {
+            throw new Error(`failure.causalChain[${index}] is invalid.`);
+        }
+        return { code: causeCode, message: causeMessage, source: causeSource };
+    });
+    return { schemaVersion: 2, code, message, category, phase, source, retryability, operatorAction, causalChain, occurredAt, contractOrigin };
+}
+function facts(code, category, phase, source, retryability, operatorAction) {
+    return { code, category, phase, source, retryability, operatorAction };
+}
+function allowedSourcesForCode(code, known) {
+    if (!known)
+        return ["bridge", "provider", "sandbox", "unknown"];
+    if (code.startsWith("provider_"))
+        return ["bridge", "provider", "sandbox"];
+    if (code.startsWith("sandbox_")
+        || code.startsWith("docker_")
+        || code.startsWith("image_")
+        || code.startsWith("contract_")
+        || code.startsWith("generated_output_reset_")
+        || code.startsWith("teardown")
+        || code.startsWith("reaper")) {
+        return ["bridge", "sandbox"];
+    }
+    return ["bridge"];
+}
+function assertFailureFactsMatchPolicy(code, factsToValidate) {
+    const policy = failurePolicyForCode(code);
+    if (!policy.known)
+        return;
+    if (factsToValidate.category !== policy.category
+        || factsToValidate.phase !== policy.phase
+        || factsToValidate.retryability !== policy.retryability
+        || factsToValidate.operatorAction !== policy.operatorAction
+        || !policy.allowedSources.includes(factsToValidate.source)) {
+        throw new Error(`Failure code '${policy.code}' contradicts the failure taxonomy or allowed-source registry.`);
+    }
+}
+function normalizeFailureCode(value) {
+    const normalized = value.trim().toLowerCase().slice(0, 80);
+    return failureCodePattern.test(normalized) ? normalized : "bridge.execution_failed";
+}
+function boundedFailureText(value) {
+    const bounded = value.trim().slice(0, maximumFailureMessageLength);
+    return bounded || "Dispatch failed without a diagnostic message.";
+}
+/**
+ * Rebuilds an error graph at a privileged execution boundary without
+ * retaining the raw error or any raw recursive cause. Forge failure metadata
+ * survives so the P7 taxonomy remains authoritative after sanitization.
+ */
+export function sanitizeFailureError(error, exactSecrets = []) {
+    return sanitizeFailureErrorAtDepth(error, exactSecrets, new Set(), 0);
+}
+function sanitizeFailureErrorAtDepth(error, exactSecrets, visited, depth) {
+    if (depth >= maximumFailureCausalChainLength) {
+        return new Error("Additional error causes were omitted.");
+    }
+    if (error !== null && typeof error === "object") {
+        if (visited.has(error))
+            return new Error("Circular error cause was omitted.");
+        visited.add(error);
+    }
+    const message = redactText(error instanceof Error ? error.message : String(error), exactSecrets);
+    const cause = error instanceof Error && error.cause !== undefined
+        ? sanitizeFailureErrorAtDepth(error.cause, exactSecrets, visited, depth + 1)
+        : undefined;
+    const options = cause === undefined ? undefined : { cause };
+    if (error instanceof ForgeFailureError) {
+        return new ForgeFailureError(error.failureCode, message, error.failureSource, options);
+    }
+    if (error instanceof AggregateError) {
+        const errors = [...error.errors].map(item => sanitizeFailureErrorAtDepth(item, exactSecrets, visited, depth + 1));
+        return new AggregateError(errors, message, options);
+    }
+    return new Error(message, options);
+}
+function errorCauseChain(error, source) {
+    const causes = [];
+    let current = error;
+    while (current !== undefined && current !== null && causes.length < maximumFailureCausalChainLength) {
+        const message = current instanceof Error ? current.message : String(current);
+        const code = current instanceof ForgeFailureError ? current.failureCode : "cause_unknown";
+        const causeSource = current instanceof ForgeFailureError ? current.failureSource : source;
+        causes.push({ code, message: boundedFailureText(message), source: causeSource });
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return causes;
+}
 function parseWorkItem(value) {
     const item = asObject(value, "workItem");
     return {
+        projectId: optionalString(item, "projectId"),
         id: requiredString(item, "id"),
         kind: requiredString(item, "kind"),
         title: requiredString(item, "title"),
@@ -205,6 +718,7 @@ function parseRepo(value) {
 function parseCycleRun(value) {
     const cycle = asObject(value, "cycleRun");
     return {
+        effectivePlanAmendmentHash: optionalString(cycle, "effectivePlanAmendmentHash"),
         id: requiredString(cycle, "id"),
         ownerType: optionalString(cycle, "ownerType"),
         ownerId: optionalString(cycle, "ownerId"),
@@ -214,6 +728,7 @@ function parseCycleRun(value) {
         requestedBase: optionalString(cycle, "requestedBase") ?? "develop",
         baseBranch: optionalString(cycle, "baseBranch") ?? "develop",
         expectedCurrentBranch: optionalString(cycle, "expectedCurrentBranch"),
+        repairHeadSha: optionalString(cycle, "repairHeadSha"),
         attempt: requiredNumber(cycle, "attempt"),
         model: requiredString(cycle, "model")
     };
@@ -223,7 +738,9 @@ function parseSession(value) {
     return {
         id: requiredString(session, "id"),
         model: requiredString(session, "model"),
-        lane: requiredString(session, "lane")
+        lane: requiredString(session, "lane"),
+        resumedFromSessionId: optionalString(session, "resumedFromSessionId"),
+        resumeProviderThreadId: optionalString(session, "resumeProviderThreadId")
     };
 }
 function parseLease(value) {
@@ -251,7 +768,8 @@ function parseExecution(value) {
         role: requiredString(execution, "role"),
         lane: requiredString(execution, "lane"),
         requiresApiKeySecretGrant: requiredBoolean(execution, "requiresApiKeySecretGrant"),
-        runnerRepoLocalPath: optionalString(execution, "runnerRepoLocalPath")
+        runnerRepoLocalPath: optionalString(execution, "runnerRepoLocalPath"),
+        effort: optionalString(execution, "effort")
     };
 }
 function parseDraftPrompt(value) {
@@ -349,9 +867,49 @@ function parsePullRequest(value) {
         requiredChecksTotal: requiredNumber(pullRequest, "requiredChecksTotal"),
         unresolvedThreads: requiredNumber(pullRequest, "unresolvedThreads"),
         humanApproved: requiredBoolean(pullRequest, "humanApproved"),
-        hasMergeConflicts: requiredBoolean(pullRequest, "hasMergeConflicts")
+        hasMergeConflicts: requiredBoolean(pullRequest, "hasMergeConflicts"),
+        headSha: optionalString(pullRequest, "headSha") ?? "",
+        reviewIssueKey: optionalString(pullRequest, "reviewIssueKey"),
+        reviewFindings: parsePullRequestReviewFindings(pullRequest.reviewFindings),
+        openWorkOrderStories: parseWorkOrderStories(pullRequest.openWorkOrderStories)
     };
 }
+function parseWorkOrderStories(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("pullRequest.openWorkOrderStories must be an array when provided.");
+    return value.map((entry, index) => {
+        const story = asObject(entry, `pullRequest.openWorkOrderStories[${index}]`);
+        return {
+            workItemId: requiredString(story, "workItemId"),
+            title: optionalString(story, "title") ?? "",
+            acceptanceCriteria: optionalString(story, "acceptanceCriteria") ?? ""
+        };
+    });
+}
+function parsePullRequestReviewFindings(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("pullRequest.reviewFindings must be an array when provided.");
+    return value.map((entry, index) => {
+        const finding = asObject(entry, `pullRequest.reviewFindings[${index}]`);
+        return {
+            claimId: requiredString(finding, "claimId"),
+            kind: requiredString(finding, "kind"),
+            bodySha256: requiredString(finding, "bodySha256"),
+            body: optionalString(finding, "body") ?? "",
+            contentAvailable: requiredBoolean(finding, "contentAvailable"),
+            actionable: requiredBoolean(finding, "actionable"),
+            actionabilityReason: requiredString(finding, "actionabilityReason"),
+            author: optionalString(finding, "author"),
+            url: optionalString(finding, "url"),
+            path: optionalString(finding, "path"),
+            line: optionalPositiveInteger(finding, "line")
+        };
+    });
+}
 function parseWarmPathOverrides(value) {
     if (value === undefined || value === null) {
         return [];
@@ -396,6 +954,7 @@ function parseQaScope(value) {
         schema_version: requiredNumber(qaScope, "schema_version"),
         surface: parseOptionalStringArray(qaScope.surface, "qaScope.surface"),
         required_evidence: parseOptionalStringArray(qaScope.required_evidence, "qaScope.required_evidence"),
+        required_capabilities: parseOptionalStringArray(qaScope.required_capabilities ?? qaScope.requiredCapabilities, "qaScope.required_capabilities"),
         not_applicable: parseOptionalStringArray(qaScope.not_applicable, "qaScope.not_applicable"),
         browser_required: optionalBoolean(qaScope, "browser_required") ?? optionalBoolean(qaScope, "browserRequired") ?? false,
         api_required: optionalBoolean(qaScope, "api_required") ?? optionalBoolean(qaScope, "apiRequired") ?? false,
@@ -529,6 +1088,7 @@ function parseStoryQa(value) {
     }
     const storyQa = asObject(value, "storyQa");
     return {
+        references: parseStoryQaReferences(storyQa.references),
         storyWorkItemId: requiredString(storyQa, "storyWorkItemId"),
         planId: requiredString(storyQa, "planId"),
         planContentHash: requiredString(storyQa, "planContentHash"),
@@ -541,6 +1101,26 @@ function parseStoryQa(value) {
         dependencies: parseStoryQaDependencies(storyQa.dependencies)
     };
 }
+function parseStoryQaReferences(value) {
+    if (value === undefined || value === null)
+        return null;
+    const bundle = asObject(value, "storyQa.references");
+    if (!Array.isArray(bundle.files))
+        throw new Error("storyQa.references.files must be an array.");
+    return {
+        schemaVersion: requiredNumber(bundle, "schemaVersion"),
+        cycleRunId: requiredString(bundle, "cycleRunId"),
+        storyWorkItemId: requiredString(bundle, "storyWorkItemId"),
+        projectId: requiredString(bundle, "projectId"), repoId: requiredString(bundle, "repoId"),
+        planId: requiredString(bundle, "planId"), planContentHash: requiredString(bundle, "planContentHash"),
+        effectiveAmendmentHash: requiredString(bundle, "effectiveAmendmentHash"), capturedAt: requiredString(bundle, "capturedAt"),
+        files: bundle.files.map((entry, index) => {
+            const file = asObject(entry, `storyQa.references.files[${index}]`);
+            return { path: requiredString(file, "path"), body: requiredString(file, "body"),
+                contentHash: requiredString(file, "contentHash"), provenance: requiredString(file, "provenance") };
+        })
+    };
+}
 function parseStoryQaChildTasks(value) {
     if (!Array.isArray(value)) {
         throw new Error("storyQa.childTasks must be an array.");