@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.41da3780c451

package/dist/session/session.service.js

@@ -1,5 +1,7 @@
 import { redactRunnerDispatchEvent, redactRunOnceResultPacket } from "./session-redaction.js";
+import { randomUUID } from "node:crypto";
 import { RoutingProviderCliService } from "./provider-cli/provider-cli.service.js";
+import { ForgeFailureError, waitKindForEvent, waitWakeCondition } from "./session.types.js";
 import { GitWorktreeService } from "../worktree/worktree.service.js";
 import { SandboxWorkspaceService } from "../sandbox/workspace.service.js";
 import { HostRuntimeAdmissionExpiredError, hostRuntimeEventResources, } from "../runtime/host-runtime-lease.js";
@@ -37,9 +39,12 @@ export class BridgeSessionService {
         let cleanupFailure = null;
         try {
             throwIfAborted(signal);
-            await this.hostRuntime.invalidatePromotion?.(request.repoId);
             await this.hostRuntime.acquire(dispatch, signal);
             admissionAcquired = true;
+            // Readiness probes acquire background-exclusive project admission. Only
+            // invalidate the prior proof after that fence is held so a user lane can
+            // never observe the proof disappear underneath shared admission.
+            await this.hostRuntime.invalidatePromotion?.(request.repoId, "discovery");
             assertReadinessProbeStartupBudget(request.expiresAt);
             worktree = await this.worktrees.prepare({
                 repo: dispatch.repo,
@@ -51,7 +56,10 @@ export class BridgeSessionService {
                 lane: "runtime_readiness",
                 phase: "readiness_probe",
                 allowedRepoRoot: request.repoRoot,
-                cleanupWorktrees: request.cleanupWorktrees,
+                // Readiness probes are disposable infrastructure checks, not agent lanes.
+                // Always remove their worktree even when the bridge is configured to retain
+                // failed agent worktrees for inspection.
+                cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
                 artifacts: [],
             });
             assertReadinessProbeStartupBudget(request.expiresAt);
@@ -120,18 +128,39 @@ export class BridgeSessionService {
         validateApiKeySecretGrant(dispatch);
         const redactionSecrets = exactSecrets(dispatch);
         const events = [];
+        let waitObservationVersion = 0;
+        const waitFirstObservedAt = new Map();
+        const waitObservation = (eventType, queuePosition) => {
+            const occurredAt = new Date().toISOString();
+            const kind = waitKindForEvent(eventType);
+            const firstObservedAt = waitFirstObservedAt.get(kind) ?? occurredAt;
+            waitFirstObservedAt.set(kind, firstObservedAt);
+            waitObservationVersion += 1;
+            const wait = {
+                schemaVersion: 2,
+                kind,
+                scope: "project",
+                resourceKeys: [`project-runtime:${dispatch.repo.id}`],
+                ...(queuePosition === undefined ? {} : { queuePosition }),
+                wakeCondition: waitWakeCondition(kind),
+                firstObservedAt,
+                observationVersion: waitObservationVersion,
+                contractOrigin: "bridge_v2",
+            };
+            return { occurredAt, wait };
+        };
         const emit = async (event) => {
             if (signal?.aborted) {
                 return;
             }
-            const redacted = redactRunnerDispatchEvent(event, redactionSecrets);
+            const redacted = redactRunnerDispatchEvent({ ...event, eventId: event.eventId ?? randomUUID() }, redactionSecrets);
             if (redacted.eventType !== "provider_tool_heartbeat") {
                 events.push(redacted);
             }
             await sink.emit(redacted);
         };
         const emitLifecycle = async (event) => {
-            const redacted = redactRunnerDispatchEvent(event, redactionSecrets);
+            const redacted = redactRunnerDispatchEvent({ ...event, eventId: event.eventId ?? randomUUID() }, redactionSecrets);
             events.push(redacted);
             await sink.emit(redacted);
         };
@@ -147,14 +176,31 @@ export class BridgeSessionService {
         let hostLease = null;
         try {
             if (dispatch.sandbox?.executionMode === "host" && this.hostRuntime) {
+                const capacity = this.hostRuntime.snapshot?.() ?? null;
+                const projectCapacity = capacity?.projects.find(project => project.repoId === dispatch.repo.id) ?? null;
+                const admissionWait = waitObservation("host_runtime_admission_waiting", capacity ? capacity.waitingAttempts + 1 : undefined);
                 await emitLifecycle({
                     role: "runner",
                     kind: "checkpoint",
-                    content: "Evaluating runner-local managed host admission before preparing the worktree.",
+                    content: capacity
+                        ? `Waiting for host-runtime admission before preparing the worktree (queue position ${capacity.waitingAttempts + 1}; runner ${capacity.activeAttempts} active, ${capacity.reservedAttempts} reserved; project ${projectCapacity?.activeAttempts ?? 0} active, ${projectCapacity?.waitingAttempts ?? 0} already waiting). This wait can be caused by the project serialization policy, readiness proof, or resource headroom; Forge will continue automatically when admission is available.`
+                        : "Waiting for host-runtime admission before preparing the worktree. Forge will continue automatically when admission is available.",
                     eventType: "host_runtime_admission_waiting",
+                    ...admissionWait,
+                    data: capacity ? JSON.stringify({
+                        queue_position: capacity.waitingAttempts + 1,
+                        runner_active_attempts: capacity.activeAttempts,
+                        runner_reserved_attempts: capacity.reservedAttempts,
+                        runner_waiting_attempts: capacity.waitingAttempts,
+                        project_active_attempts: projectCapacity?.activeAttempts ?? 0,
+                        project_reserved_attempts: projectCapacity?.reservedAttempts ?? 0,
+                        project_waiting_attempts: projectCapacity?.waitingAttempts ?? 0,
+                        project_safety_class: projectCapacity?.safetyClass ?? "unknown",
+                    }) : undefined,
                 });
                 try {
-                    hostSingletonKeys = await this.hostRuntime.acquire(dispatch, signal);
+                    hostSingletonKeys = await (this.hostRuntime.acquirePreparation?.(dispatch, signal)
+                        ?? this.hostRuntime.acquire(dispatch, signal));
                 }
                 catch (error) {
                     if (error instanceof HostRuntimeAdmissionExpiredError) {
@@ -168,13 +214,17 @@ export class BridgeSessionService {
                     throw error;
                 }
                 throwIfAborted(signal);
+                const admissionAcquired = waitObservation("host_runtime_admission_acquired");
                 await emitLifecycle({
                     role: "runner",
                     kind: "checkpoint",
-                    content: hostSingletonKeys.length > 0
-                        ? `Acquired managed host singleton ${hostSingletonKeys.join(", ")}.`
-                        : "Observed assigned-port evidence permits provisional parallel host admission; the prepared runtime contract must still match before launch.",
+                    content: this.hostRuntime.acquirePreparation
+                        ? "Acquired worktree-preparation capacity. Prepared runtime verification must finish before agent admission."
+                        : hostSingletonKeys.length > 0
+                            ? `Acquired managed host singleton ${hostSingletonKeys.join(", ")}.`
+                            : "Observed assigned-port evidence permits provisional parallel host admission; the prepared runtime contract must still match before launch.",
                     eventType: "host_runtime_admission_acquired",
+                    ...admissionAcquired,
                 });
             }
             try {
@@ -191,20 +241,28 @@ export class BridgeSessionService {
                     cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
                     artifacts: dispatch.artifacts,
                     priorPhaseArtifacts: dispatch.priorPhaseArtifacts,
+                    storyQa: dispatch.storyQa,
+                    referenceRunId: dispatch.sandbox?.dispatchAttemptId ?? dispatch.cycleRun.id,
+                    referenceCycleRunId: dispatch.cycleRun.id,
+                    effectivePlanAmendmentHash: dispatch.cycleRun.effectivePlanAmendmentHash,
                     qaRework: dispatch.qaRework,
-                    warmPathOverrides: dispatch.warmPathOverrides
+                    warmPathOverrides: dispatch.warmPathOverrides,
+                    applicationRuntimeRequired: dispatch.runtimeIntent.applicationRuntimeRequired,
+                    preserveExistingState: Boolean(dispatch.session.resumedFromSessionId)
                 });
             }
             catch (error) {
-                throw new Error(`worktree_prepare_failed: ${failureMessage(error)}`, { cause: error });
+                throw new ForgeFailureError("worktree_prepare_failed", `worktree_prepare_failed: ${failureMessage(error)}`, "bridge", { cause: error });
             }
             let providerDispatch = withPreparedQaReworkPacket(dispatch, worktree.qaReworkPacketPath);
             throwIfAborted(signal);
             await emit({
                 role: "runner",
                 kind: "checkpoint",
-                content: `Prepared worktree ${worktree.branchName}.`,
-                eventType: "worktree_prepared"
+                content: dispatch.session.resumedFromSessionId
+                    ? `Reattached to worktree ${worktree.branchName} without resetting source or clearing attempt artifacts.`
+                    : `Prepared worktree ${worktree.branchName}.`,
+                eventType: dispatch.session.resumedFromSessionId ? "worktree_reattached" : "worktree_prepared"
             });
             if ((worktree.hydratedPriorPhaseArtifactCount ?? 0) > 0) {
                 await emit({
@@ -218,7 +276,17 @@ export class BridgeSessionService {
                 await emitDependencyWarmEvents(worktree.dependencyWarm, emit);
             }
             if (dispatch.sandbox?.executionMode === "host" && this.hostRuntime) {
-                hostLease = await this.hostRuntime.start(dispatch, worktree.worktreePath, signal);
+                hostLease = await this.hostRuntime.start(dispatch, worktree.worktreePath, signal, async (checkpoint) => {
+                    const observation = waitObservation(checkpoint.code);
+                    await emitLifecycle({
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: checkpoint.message,
+                        eventType: checkpoint.code,
+                        ...observation,
+                        data: JSON.stringify({ expires_at: checkpoint.expiresAt }),
+                    });
+                });
                 await emitLifecycle({
                     role: "runner",
                     kind: "checkpoint",
@@ -238,7 +306,15 @@ export class BridgeSessionService {
                     }),
                 });
                 const unconfiguredPortCount = hostLease.lease.resources.ports.length;
-                hostLease = await this.hostRuntime.startConfiguredProject(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken, signal);
+                hostLease = await this.hostRuntime.startConfiguredProject(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken, signal, async (checkpoint) => {
+                    await emitLifecycle({
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: checkpoint.message,
+                        eventType: checkpoint.code,
+                        data: checkpoint.data ? JSON.stringify(checkpoint.data) : undefined,
+                    });
+                });
                 if (hostLease.lease.resources.ports.length > unconfiguredPortCount) {
                     const assigned = hostLease.lease.resources.ports.at(-1);
                     await emitLifecycle({
@@ -267,7 +343,7 @@ export class BridgeSessionService {
                 throwIfAborted(signal);
                 const draftArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
                 return redactRunOnceResultPacket({
-                    schemaVersion: 1,
+                    schemaVersion: 2,
                     exitCode: 0,
                     summary: run.summary,
                     events,
@@ -308,18 +384,21 @@ export class BridgeSessionService {
             }
             catch (error) {
                 const message = failureMessage(error);
-                if (message.includes("attempt_process_supervisor_start_")
-                    || message.includes("host_process_supervisor_start_")) {
-                    throw new Error(`provider_start_unavailable: ${message}`, { cause: error });
+                if (error instanceof ForgeFailureError
+                    && (error.failureCode === "attempt_process_supervisor_start_failed"
+                        || error.failureCode === "attempt_process_supervisor_start_timeout")) {
+                    throw new ForgeFailureError("provider_start_unavailable", `provider_start_unavailable: ${message}`, "bridge", { cause: error });
                 }
                 throw error;
             }
             throwIfAborted(signal);
             const phaseArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
             return redactRunOnceResultPacket({
-                schemaVersion: 1,
+                schemaVersion: 2,
                 exitCode: 0,
                 summary: run.summary,
+                resultCommitSha: run.resultCommitSha ?? null,
+                publishedCommitSha: run.publishedCommitSha ?? null,
                 events,
                 spec: run.spec ?? null,
                 artifact: run.artifact ?? null,
@@ -328,6 +407,25 @@ export class BridgeSessionService {
         }
         finally {
             if (hostLease && dispatch.sandbox) {
+                const providerMemory = this.hostRuntime?.providerMemoryTelemetry?.(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken);
+                if (providerMemory) {
+                    await emitLifecycle({
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Observed managed-host provider process-tree peak memory ${formatMemoryBytes(providerMemory.peakMemoryBytes)} from ${providerMemory.sampleCount} sample${providerMemory.sampleCount === 1 ? "" : "s"}.`,
+                        eventType: "sandbox_peak_memory_observed",
+                        occurredAt: providerMemory.observedAt,
+                        data: JSON.stringify({
+                            peakMemoryBytes: providerMemory.peakMemoryBytes,
+                            sampleCount: providerMemory.sampleCount,
+                            source: providerMemory.source,
+                            containers: [{
+                                    role: "agent",
+                                    peakMemoryBytes: providerMemory.peakMemoryBytes,
+                                }],
+                        }),
+                    }).catch(() => undefined);
+                }
                 const teardownAt = new Date().toISOString();
                 await emitLifecycle({
                     role: "runner",
@@ -351,7 +449,7 @@ export class BridgeSessionService {
                         await emitLifecycle({
                             role: "runner",
                             kind: "checkpoint",
-                            content: `Released host runtime lease ${released.leaseId}.`,
+                            content: `Released host runtime lease ${released.leaseId}. Diagnostics remain runner-local.`,
                             eventType: "sandbox_teardown_completed",
                             occurredAt: released.releasedAt,
                         }).catch(() => undefined);
@@ -370,7 +468,7 @@ export class BridgeSessionService {
             if (!hostLease && hostSingletonKeys && dispatch.sandbox) {
                 await this.hostRuntime?.release(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken).catch(() => undefined);
             }
-            if (worktree)
+            if (worktree && !isPauseCancellation(signal))
                 await this.worktrees.release(worktree);
         }
     }
@@ -378,6 +476,13 @@ export class BridgeSessionService {
 function failureMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function formatMemoryBytes(bytes) {
+    return `${(bytes / (1024 ** 2)).toFixed(bytes >= 1024 ** 3 ? 0 : 1)} MiB`;
+}
+function isPauseCancellation(signal) {
+    return signal?.aborted === true
+        && String(signal.reason ?? "").trim().toLowerCase() === "session pause requested";
+}
 function readinessProbeDispatch(request) {
     return {
         schemaVersion: 2,
@@ -433,7 +538,7 @@ function readinessProbeDispatch(request) {
             runnerRepoLocalPath: request.runnerRepoLocalPath,
         },
         runtimeIntent: { executionClass: "managed_runtime", applicationRuntimeRequired: true },
-        serverLocal: { repoRoot: request.repoRoot, cleanupWorktrees: request.cleanupWorktrees },
+        serverLocal: { repoRoot: request.repoRoot, cleanupWorktrees: true },
         sandbox: {
             dispatchAttemptId: request.requestId,
             executionLeaseId: request.requestId,
@@ -552,6 +657,23 @@ function withPreparedQaReworkPacket(dispatch, packetPath) {
     };
 }
 async function emitDependencyWarmEvents(warm, emit) {
+    for (const receipt of warm.receipts) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: receipt.cacheHit
+                ? `Reused verified ${receipt.ecosystem} dependency preparation receipt ${receipt.fingerprint} in ${receipt.packageRoot}.`
+                : `Published ${receipt.ecosystem} dependency preparation receipt ${receipt.fingerprint} in ${receipt.packageRoot}.`,
+            eventType: receipt.cacheHit ? "dependencies_preparation_cached" : "dependencies_preparation_receipt_published",
+            data: JSON.stringify({
+                ecosystem: receipt.ecosystem,
+                package_root: receipt.packageRoot,
+                cache_hit: receipt.cacheHit,
+                fingerprint: receipt.fingerprint,
+                receipt_path: receipt.receiptPath,
+            }),
+        });
+    }
     if (warm.linked.length > 0) {
         await emit({
             role: "runner",

package/dist/session/session.types.d.ts

@@ -94,6 +94,7 @@ export interface DispatchQaScope {
     readonly schema_version: number;
     readonly surface: readonly string[];
     readonly required_evidence: readonly string[];
+    readonly required_capabilities?: readonly string[];
     readonly not_applicable: readonly string[];
     readonly browser_required: boolean;
     readonly api_required: boolean;
@@ -152,6 +153,7 @@ export interface DispatchStoryDevelopContext {
     readonly dependencyWorkItemIds: readonly string[];
 }
 export interface DispatchStoryQaContext {
+    readonly references?: DispatchStoryQaReferenceBundle | null;
     readonly storyWorkItemId: string;
     readonly planId: string;
     readonly planContentHash: string;
@@ -163,6 +165,24 @@ export interface DispatchStoryQaContext {
     readonly childTasks: readonly DispatchStoryQaChildTaskContext[];
     readonly dependencies: readonly DispatchStoryQaDependencyContext[];
 }
+export interface DispatchStoryQaReferenceBundle {
+    readonly schemaVersion: number;
+    readonly cycleRunId: string;
+    readonly storyWorkItemId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly planId: string;
+    readonly planContentHash: string;
+    readonly effectiveAmendmentHash: string;
+    readonly capturedAt: string;
+    readonly files: readonly DispatchStoryQaReferenceFile[];
+}
+export interface DispatchStoryQaReferenceFile {
+    readonly path: string;
+    readonly body: string;
+    readonly contentHash: string;
+    readonly provenance: string;
+}
 export interface DispatchStoryQaChildTaskContext {
     readonly workItemId: string;
     readonly title: string;
@@ -263,6 +283,28 @@ export interface DispatchPullRequestContext {
     readonly unresolvedThreads: number;
     readonly humanApproved: boolean;
     readonly hasMergeConflicts: boolean;
+    readonly headSha: string;
+    readonly reviewIssueKey?: string | null;
+    readonly reviewFindings: readonly DispatchPullRequestReviewFinding[];
+    readonly openWorkOrderStories: readonly DispatchWorkOrderStory[];
+}
+export interface DispatchWorkOrderStory {
+    readonly workItemId: string;
+    readonly title: string;
+    readonly acceptanceCriteria: string;
+}
+export interface DispatchPullRequestReviewFinding {
+    readonly claimId: string;
+    readonly kind: string;
+    readonly bodySha256: string;
+    readonly body: string;
+    readonly contentAvailable: boolean;
+    readonly actionable: boolean;
+    readonly actionabilityReason: string;
+    readonly author?: string | null;
+    readonly url?: string | null;
+    readonly path?: string | null;
+    readonly line?: number | null;
 }
 export interface DispatchResolvedArtifact {
     readonly kind: string;
@@ -275,6 +317,7 @@ export interface DispatchResolvedArtifact {
     readonly event?: string | null;
 }
 export interface DispatchWorkItem {
+    readonly projectId?: string | null;
     readonly id: string;
     readonly kind: string;
     readonly title: string;
@@ -292,6 +335,7 @@ export interface DispatchRepo {
     readonly serverLocalPath?: string | null;
 }
 export interface DispatchCycleRun {
+    readonly effectivePlanAmendmentHash?: string | null;
     readonly id: string;
     readonly ownerType?: string | null;
     readonly ownerId?: string | null;
@@ -301,6 +345,7 @@ export interface DispatchCycleRun {
     readonly requestedBase: string;
     readonly baseBranch: string;
     readonly expectedCurrentBranch?: string | null;
+    readonly repairHeadSha?: string | null;
     readonly attempt: number;
     readonly model: string;
 }
@@ -308,6 +353,8 @@ export interface DispatchSession {
     readonly id: string;
     readonly model: string;
     readonly lane: string;
+    readonly resumedFromSessionId?: string | null;
+    readonly resumeProviderThreadId?: string | null;
 }
 export interface DispatchLease {
     readonly id: string;
@@ -330,6 +377,8 @@ export interface DispatchExecution {
     readonly lane: string;
     readonly requiresApiKeySecretGrant: boolean;
     readonly runnerRepoLocalPath?: string | null;
+    /** Reasoning effort from the Agents tab; null means the provider CLI's default. */
+    readonly effort?: string | null;
 }
 export interface ApiKeySecretGrant {
     readonly grantId: string;
@@ -347,6 +396,8 @@ export interface DispatchServerLocalConfig {
     readonly cleanupWorktrees: boolean;
 }
 export interface RunnerDispatchEvent {
+    /** Stable across callback retries; persisted atomically with the session event. */
+    readonly eventId?: string | null;
     readonly role: string;
     readonly kind: string;
     readonly content: string;
@@ -355,6 +406,22 @@ export interface RunnerDispatchEvent {
     readonly occurredAt?: string | null;
     /** Optional structured telemetry payload (JSON string), e.g. token usage for provider_usage events. */
     readonly data?: string | null;
+    /** Versioned nonterminal wait evidence. Legacy writers omit this field. */
+    readonly wait?: WaitEnvelope | null;
+}
+export interface WaitEnvelope {
+    readonly schemaVersion: 2;
+    readonly kind: string;
+    readonly scope: string;
+    readonly resourceKeys: readonly string[];
+    readonly queuePosition?: number | null;
+    readonly blockerSessionId?: string | null;
+    readonly blockerTitle?: string | null;
+    readonly wakeCondition: string;
+    readonly retryAt?: string | null;
+    readonly firstObservedAt: string;
+    readonly observationVersion: number;
+    readonly contractOrigin: "bridge_v2";
 }
 export interface RunnerDispatchSpec {
     readonly repoPath: string;
@@ -376,12 +443,74 @@ export interface RunnerDispatchArtifact {
     readonly producedBy: string;
     readonly status: string;
     readonly phase?: string | null;
+    /**
+     * QA sidecars are transported with the terminal result because managed
+     * worktrees may be released before the API mirrors the result. The API
+     * validates these bytes against the canonical evidence metadata and stores
+     * only that metadata.
+     */
+    readonly sidecars?: readonly RunnerDispatchSidecar[] | null;
+}
+export interface RunnerDispatchSidecar {
+    readonly path: string;
+    readonly contentBase64: string;
+    readonly contentHash: string;
+    readonly bytes: number;
+}
+export type FailureCategory = "domain" | "provider" | "transport" | "cancellation" | "ownership" | "resource" | "unknown";
+export type FailurePhase = "offer" | "build" | "prepare" | "agent" | "validation" | "import" | "teardown" | "unknown";
+export type FailureSource = "bridge" | "provider" | "sandbox" | "unknown";
+export type FailureRetryability = "retryable" | "non_retryable" | "policy_required" | "unknown";
+export type FailureOperatorAction = "none" | "retry_dispatch" | "retry_with_policy" | "inspect_failure" | "fix_input" | "fix_environment" | "reauthenticate" | "restore_ownership";
+export interface FailureCause {
+    readonly code: string;
+    readonly message: string;
+    readonly source: FailureSource;
+}
+export interface FailureEnvelope {
+    readonly schemaVersion: 2;
+    readonly code: string;
+    readonly message: string;
+    readonly category: FailureCategory;
+    readonly phase: FailurePhase;
+    readonly source: FailureSource;
+    readonly retryability: FailureRetryability;
+    readonly operatorAction: FailureOperatorAction;
+    readonly causalChain: readonly FailureCause[];
+    readonly occurredAt: string;
+    readonly contractOrigin: "bridge_v2";
+}
+export interface FailureFacts {
+    readonly code: string;
+    readonly category: FailureCategory;
+    readonly phase: FailurePhase;
+    readonly source: FailureSource;
+    readonly retryability: FailureRetryability;
+    readonly operatorAction: FailureOperatorAction;
+    readonly causalChain?: readonly FailureCause[];
+}
+export interface FailurePolicy {
+    readonly code: string;
+    readonly category: FailureCategory;
+    readonly phase: FailurePhase;
+    readonly retryability: FailureRetryability;
+    readonly operatorAction: FailureOperatorAction;
+    readonly allowedSources: readonly FailureSource[];
+    readonly known: boolean;
+}
+export declare class ForgeFailureError extends Error {
+    readonly failureCode: string;
+    readonly failureSource: FailureSource;
+    constructor(failureCode: string, message: string, failureSource?: FailureSource, options?: ErrorOptions);
 }
 export interface RunOnceResultPacket {
-    readonly schemaVersion: 1;
+    readonly schemaVersion: 1 | 2;
     readonly exitCode: number;
     readonly summary: string;
+    readonly resultCommitSha?: string | null;
+    readonly publishedCommitSha?: string | null;
     readonly events: readonly RunnerDispatchEvent[];
+    readonly failure?: FailureEnvelope | null;
     readonly spec?: RunnerDispatchSpec | null;
     readonly artifact?: RunnerDispatchArtifact | null;
     readonly artifacts?: readonly RunnerDispatchArtifact[] | null;
@@ -391,6 +520,9 @@ export interface RunnerEventLine {
     readonly event: RunnerDispatchEvent;
 }
 export declare function parseRunOnceDispatchPacket(value: unknown): RunOnceDispatchPacket;
+export declare function parseRunOnceResultPacket(value: unknown): RunOnceResultPacket;
+export declare function waitKindForEvent(eventType: string): string;
+export declare function waitWakeCondition(kind: string): string;
 export interface HostRuntimeReadinessProbeRequest {
     readonly requestId: string;
     readonly fencingToken: string;
@@ -423,4 +555,17 @@ export interface HostRuntimeReadinessQaLaunchTarget {
     readonly managedRuntimePort: string;
     readonly routes: readonly string[];
 }
-export declare function failureResult(summary: string, events?: readonly RunnerDispatchEvent[]): RunOnceResultPacket;
+export declare function failureResult(summary: string, events?: readonly RunnerDispatchEvent[], facts?: FailureFacts): RunOnceResultPacket;
+export declare function createFailureEnvelope(message: string, facts: FailureFacts, occurredAt?: string): FailureEnvelope;
+export declare function failureFactsFromError(error: unknown, options?: {
+    readonly cancelled?: boolean;
+    readonly source?: FailureSource;
+}): FailureFacts;
+export declare function failureFactsForCode(code: string, source?: FailureSource): FailureFacts;
+export declare function failurePolicyForCode(code: string): FailurePolicy;
+/**
+ * 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 declare function sanitizeFailureError(error: unknown, exactSecrets?: readonly string[]): Error;