@loucompanion/forge-bridge 0.1.3-dev.b3bce6ba65a6 → 0.1.3-dev.ba7d36726eda

package/dist/session/session.service.js

@@ -1,12 +1,27 @@
-import { redactSecrets } from "../shared/redaction/redaction.js";
+import { redactRunnerDispatchEvent, redactRunOnceResultPacket } from "./session-redaction.js";
 import { RoutingProviderCliService } from "./provider-cli/provider-cli.service.js";
 import { GitWorktreeService } from "../worktree/worktree.service.js";
+import { SandboxWorkspaceService } from "../sandbox/workspace.service.js";
+import { HostRuntimeAdmissionExpiredError, hostRuntimeEventResources, } from "../runtime/host-runtime-lease.js";
 export class BridgeSessionService {
     worktrees;
     providerCli;
-    constructor(worktrees = new GitWorktreeService(), providerCli = new RoutingProviderCliService()) {
+    hostRuntime;
+    constructor(worktrees = process.env.FORGE_SANDBOX_ID
+        ? new SandboxWorkspaceService()
+        : new GitWorktreeService(), providerCli = new RoutingProviderCliService(), hostRuntime) {
         this.worktrees = worktrees;
         this.providerCli = providerCli;
+        this.hostRuntime = hostRuntime;
+    }
+    async updateLease(dispatchAttemptId, fencingToken, expiresAt) {
+        await this.hostRuntime?.updateLease(dispatchAttemptId, fencingToken, expiresAt);
+    }
+    async reapHostRuntime(options) {
+        return await this.hostRuntime?.reap?.(options) ?? null;
+    }
+    runtimeCapacity() {
+        return this.hostRuntime?.snapshot?.() ?? null;
     }
     async runOnce(dispatch, sink, signal) {
         validateApiKeySecretGrant(dispatch);
@@ -16,7 +31,12 @@ export class BridgeSessionService {
             if (signal?.aborted) {
                 return;
             }
-            const redacted = redactSecrets(event, redactionSecrets);
+            const redacted = redactRunnerDispatchEvent(event, redactionSecrets);
+            events.push(redacted);
+            await sink.emit(redacted);
+        };
+        const emitLifecycle = async (event) => {
+            const redacted = redactRunnerDispatchEvent(event, redactionSecrets);
             events.push(redacted);
             await sink.emit(redacted);
         };
@@ -27,44 +47,121 @@ export class BridgeSessionService {
             content: "forge-bridge accepted run-once dispatch.",
             eventType: "dispatch_accepted"
         });
-        const worktree = await this.worktrees.prepare({
-            repo: dispatch.repo,
-            workItem: dispatch.workItem,
-            baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
-            worktreeKey: dispatch.lease.worktreeKey,
-            ownerType: dispatch.cycleRun.ownerType ?? dispatch.lease.ownerType ?? null,
-            ownerId: dispatch.cycleRun.ownerId ?? dispatch.lease.ownerId ?? null,
-            lane: dispatch.execution.lane,
-            phase: dispatch.cycleRun.phase,
-            allowedRepoRoot: dispatch.serverLocal.repoRoot,
-            cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
-            artifacts: dispatch.artifacts,
-            qaRework: dispatch.qaRework,
-            warmPathOverrides: dispatch.warmPathOverrides
-        });
-        const providerDispatch = withPreparedQaReworkPacket(dispatch, worktree.qaReworkPacketPath);
-        throwIfAborted(signal);
-        await emit({
-            role: "runner",
-            kind: "checkpoint",
-            content: `Prepared worktree ${worktree.branchName}.`,
-            eventType: "worktree_prepared"
-        });
-        if (worktree.dependencyWarm) {
-            await emitDependencyWarmEvents(worktree.dependencyWarm, emit);
-        }
+        let worktree = null;
+        let hostSingletonKeys = null;
+        let hostLease = null;
         try {
+            if (dispatch.sandbox?.executionMode === "host" && this.hostRuntime) {
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: "Evaluating runner-local managed host admission before preparing the worktree.",
+                    eventType: "host_runtime_admission_waiting",
+                });
+                try {
+                    hostSingletonKeys = await this.hostRuntime.acquire(dispatch, signal);
+                }
+                catch (error) {
+                    if (error instanceof HostRuntimeAdmissionExpiredError) {
+                        await emitLifecycle({
+                            role: "runner",
+                            kind: "error",
+                            content: "Managed host admission expired while the project singleton remained busy; no worktree or runtime resources were created.",
+                            eventType: "host_runtime_admission_expired",
+                        }).catch(() => undefined);
+                    }
+                    throw error;
+                }
+                throwIfAborted(signal);
+                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.",
+                    eventType: "host_runtime_admission_acquired",
+                });
+            }
+            worktree = await this.worktrees.prepare({
+                repo: dispatch.repo,
+                workItem: dispatch.workItem,
+                baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
+                worktreeKey: dispatch.lease.worktreeKey,
+                ownerType: dispatch.cycleRun.ownerType ?? dispatch.lease.ownerType ?? null,
+                ownerId: dispatch.cycleRun.ownerId ?? dispatch.lease.ownerId ?? null,
+                lane: dispatch.execution.lane,
+                phase: dispatch.cycleRun.phase,
+                allowedRepoRoot: dispatch.serverLocal.repoRoot,
+                cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
+                artifacts: dispatch.artifacts,
+                priorPhaseArtifacts: dispatch.priorPhaseArtifacts,
+                qaRework: dispatch.qaRework,
+                warmPathOverrides: dispatch.warmPathOverrides
+            });
+            const providerDispatch = withPreparedQaReworkPacket(dispatch, worktree.qaReworkPacketPath);
+            throwIfAborted(signal);
+            await emit({
+                role: "runner",
+                kind: "checkpoint",
+                content: `Prepared worktree ${worktree.branchName}.`,
+                eventType: "worktree_prepared"
+            });
+            if ((worktree.hydratedPriorPhaseArtifactCount ?? 0) > 0) {
+                await emit({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: `Hydrated ${worktree.hydratedPriorPhaseArtifactCount} persisted prior-phase artifact(s) into the prepared worktree.`,
+                    eventType: "prior_phase_artifacts_hydrated"
+                });
+            }
+            if (worktree.dependencyWarm) {
+                await emitDependencyWarmEvents(worktree.dependencyWarm, emit);
+            }
+            if (dispatch.sandbox?.executionMode === "host" && this.hostRuntime) {
+                hostLease = await this.hostRuntime.start(dispatch, worktree.worktreePath, signal);
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: `Host runtime lease ${hostLease.lease.leaseId} is active for this worktree.`,
+                    eventType: "sandbox_started",
+                    occurredAt: hostLease.lease.stateChangedAt,
+                    data: JSON.stringify(hostRuntimeEventResources(hostLease.lease, hostLease.runtimeContract)),
+                });
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: "Managed host fallback isolates the worktree, attempt paths, assigned loopback ports, and supervised process trees, but not the host filesystem, network, credentials, or kernel. Serialized projects also hold a runner-local singleton. Enable Run in Docker in Project Settings when stronger isolation is required.",
+                    eventType: "host_runtime_isolation_notice",
+                    data: JSON.stringify({
+                        isolationStrength: "managed_host_process",
+                        remediation: "Enable Run in Docker in Project Settings.",
+                    }),
+                });
+                const unconfiguredPortCount = hostLease.lease.resources.ports.length;
+                hostLease = await this.hostRuntime.startConfiguredProject(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken, signal);
+                if (hostLease.lease.resources.ports.length > unconfiguredPortCount) {
+                    const assigned = hostLease.lease.resources.ports.at(-1);
+                    await emitLifecycle({
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Verified supervised project runtime ${assigned.name} on ${assigned.hostIp}:${assigned.hostPort}.`,
+                        eventType: "host_runtime_project_ready",
+                        data: JSON.stringify(hostRuntimeEventResources(hostLease.lease, hostLease.runtimeContract)),
+                    });
+                }
+            }
             if (dispatch.draft) {
                 throwIfAborted(signal);
                 const run = await this.providerCli.runDraft({
                     dispatch: providerDispatch,
                     worktree,
+                    runtimeEnvironment: hostLease?.environment,
                     emit,
                     signal
                 });
                 throwIfAborted(signal);
                 const draftArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
-                return redactSecrets({
+                return redactRunOnceResultPacket({
                     schemaVersion: 1,
                     exitCode: 0,
                     summary: run.summary,
@@ -75,14 +172,17 @@ export class BridgeSessionService {
                 }, redactionSecrets);
             }
             throwIfAborted(signal);
-            const lane = dispatch.execution.lane.toLowerCase();
-            const role = dispatch.execution.role.toLowerCase();
+            const lane = dispatch.execution.lane.trim().toLowerCase();
+            const role = dispatch.execution.role.trim().toLowerCase();
+            const cycleKind = dispatch.cycleRun.kind.trim().toLowerCase();
             const isQa = role === "qa" || lane === "qa";
-            const isArchitect = role === "architect" || lane === "architect" || dispatch.cycleRun.kind.toLowerCase() === "architect";
+            const isArchitect = role === "architect" || lane === "architect" || cycleKind === "architect";
+            const isCiRepair = role === "ci_repair" || lane === "ci_repair" || cycleKind === "pr_checks";
             const isConflictResolve = role === "conflict_resolve" || lane === "conflict_resolve";
             const context = {
                 dispatch: providerDispatch,
                 worktree,
+                runtimeEnvironment: hostLease?.environment,
                 emit,
                 signal
             };
@@ -90,12 +190,14 @@ export class BridgeSessionService {
                 ? await this.providerCli.runQa(context)
                 : isArchitect
                     ? await this.providerCli.runArchitect(context)
-                    : isConflictResolve
-                        ? await this.providerCli.runConflictResolve(context)
-                        : await this.providerCli.runImplementation(context);
+                    : isCiRepair
+                        ? await this.providerCli.runCiRepair(context)
+                        : isConflictResolve
+                            ? await this.providerCli.runConflictResolve(context)
+                            : await this.providerCli.runImplementation(context);
             throwIfAborted(signal);
             const phaseArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
-            return redactSecrets({
+            return redactRunOnceResultPacket({
                 schemaVersion: 1,
                 exitCode: 0,
                 summary: run.summary,
@@ -106,7 +208,51 @@ export class BridgeSessionService {
             }, redactionSecrets);
         }
         finally {
-            await this.worktrees.release(worktree);
+            if (hostLease && dispatch.sandbox) {
+                const teardownAt = new Date().toISOString();
+                await emitLifecycle({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: `Releasing host runtime lease ${hostLease.lease.leaseId}.`,
+                    eventType: "sandbox_teardown_started",
+                    occurredAt: teardownAt,
+                }).catch(() => undefined);
+                try {
+                    const released = await this.hostRuntime?.release(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken);
+                    if (!released) {
+                        await emitLifecycle({
+                            role: "runner",
+                            kind: "error",
+                            content: "Host runtime cleanup requires reconciliation: the runtime lease was not current during release.",
+                            eventType: "teardown_failed",
+                            occurredAt: new Date().toISOString(),
+                        }).catch(() => undefined);
+                    }
+                    else {
+                        await emitLifecycle({
+                            role: "runner",
+                            kind: "checkpoint",
+                            content: `Released host runtime lease ${released.leaseId}.`,
+                            eventType: "sandbox_teardown_completed",
+                            occurredAt: released.releasedAt,
+                        }).catch(() => undefined);
+                    }
+                }
+                catch (error) {
+                    await emitLifecycle({
+                        role: "runner",
+                        kind: "error",
+                        content: `Host runtime cleanup requires reconciliation: ${error instanceof Error ? error.message : String(error)}`,
+                        eventType: "teardown_failed",
+                        occurredAt: new Date().toISOString(),
+                    }).catch(() => undefined);
+                }
+            }
+            if (!hostLease && hostSingletonKeys && dispatch.sandbox) {
+                await this.hostRuntime?.release(dispatch.sandbox.dispatchAttemptId, dispatch.lease.fencingToken).catch(() => undefined);
+            }
+            if (worktree)
+                await this.worktrees.release(worktree);
         }
     }
 }

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

@@ -1,5 +1,5 @@
 export interface RunOnceDispatchPacket {
-    readonly schemaVersion: 1;
+    readonly schemaVersion: 1 | 2;
     readonly userId: string;
     readonly workItem: DispatchWorkItem;
     readonly repo: DispatchRepo;
@@ -8,9 +8,12 @@ export interface RunOnceDispatchPacket {
     readonly lease: DispatchLease;
     readonly execution: DispatchExecution;
     readonly serverLocal: DispatchServerLocalConfig;
+    readonly sandbox?: DispatchSandboxContext | null;
     readonly pullRequest?: DispatchPullRequestContext | null;
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
+    readonly apiKeySecretGrantHandle?: ApiKeySecretGrantHandle | null;
     readonly artifacts: readonly DispatchResolvedArtifact[];
+    readonly priorPhaseArtifacts?: readonly DispatchPriorPhaseArtifact[];
     readonly warmPathOverrides?: readonly string[];
     readonly qaBrowser?: DispatchQaBrowserContext | null;
     readonly qaScope?: DispatchQaScope | null;
@@ -22,6 +25,42 @@ export interface RunOnceDispatchPacket {
     readonly designerRefs?: DispatchDesignerRefHandoffContext | null;
     readonly draft?: DispatchDraftPrompt | null;
 }
+export interface DispatchSandboxContext {
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly runnerInstanceId: string;
+    readonly executionMode: "host" | "docker";
+    readonly executionPolicy: "host_allowed" | "sandbox_preferred" | "sandbox_required";
+    readonly networkPolicy: DispatchSandboxNetworkPolicy;
+    readonly requestedResources: DispatchSandboxResourceRequest;
+    readonly runtime?: string | null;
+    readonly sandboxConfigCommitSha?: string | null;
+    readonly inputCommitSha?: string | null;
+    readonly contractDigest?: string | null;
+    readonly imageDigest?: string | null;
+    readonly publicationMode: "bridge_push" | "shared_filesystem";
+    readonly publishGrantHandle?: DispatchPublishGrantHandle | null;
+}
+export interface DispatchPublishGrantHandle {
+    readonly grantId: string;
+    readonly branch: string;
+    readonly expiresAt: string;
+}
+export interface DispatchSandboxResourceRequest {
+    readonly sandboxSlots: number;
+    readonly cpuMillis: number;
+    readonly workerMemoryLimitBytes: number;
+    readonly serviceMemoryLimitBytes: number;
+    readonly runtimeOverheadBytes: number;
+    readonly memoryBytes: number;
+    readonly workspaceBytes: number;
+    readonly pids: number;
+    readonly buildSlots: number;
+}
+export interface DispatchSandboxNetworkPolicy {
+    readonly mode: "offline" | "public_allowlist" | "open_public";
+    readonly allowedHosts: readonly string[];
+}
 export interface DispatchDraftPrompt {
     readonly kind: string;
     readonly systemPrompt: string;
@@ -154,6 +193,19 @@ export interface DispatchStoryQaDependencyContext {
     readonly fromWorkItemId: string;
     readonly toWorkItemId: string;
 }
+export interface DispatchPriorPhaseArtifact {
+    readonly workItemId: string;
+    readonly artifactId: string;
+    readonly cycleRunId: string;
+    readonly phase: "implementation" | "self_review" | "validation";
+    readonly status: string;
+    readonly producedAt: string;
+    readonly sourcePath: string;
+    readonly verdictJson: string;
+    readonly report: string;
+    readonly verdictContentHash: string;
+    readonly reportContentHash: string;
+}
 export interface DispatchDesignerRefHandoffContext {
     readonly schemaVersion: number;
     readonly kind: string;
@@ -279,6 +331,11 @@ export interface ApiKeySecretGrant {
     readonly secret: string;
     readonly expiresAt: string;
 }
+export interface ApiKeySecretGrantHandle {
+    readonly grantId: string;
+    readonly provider: string;
+    readonly expiresAt: string;
+}
 export interface DispatchServerLocalConfig {
     readonly repoRoot: string;
     readonly cleanupWorktrees: boolean;

package/dist/session/session.types.js

@@ -2,11 +2,11 @@ import path from "node:path";
 export function parseRunOnceDispatchPacket(value) {
     const packet = asObject(value, "dispatch packet");
     const schemaVersion = requiredNumber(packet, "schemaVersion");
-    if (schemaVersion !== 1) {
+    if (schemaVersion !== 1 && schemaVersion !== 2) {
         throw new Error(`Unsupported dispatch schemaVersion: ${schemaVersion}`);
     }
     return {
-        schemaVersion: 1,
+        schemaVersion,
         userId: requiredString(packet, "userId"),
         workItem: parseWorkItem(packet.workItem),
         repo: parseRepo(packet.repo),
@@ -15,9 +15,12 @@ export function parseRunOnceDispatchPacket(value) {
         lease: parseLease(packet.lease),
         execution: parseExecution(packet.execution),
         serverLocal: parseServerLocal(packet.serverLocal),
+        sandbox: parseSandbox(packet.sandbox, schemaVersion),
         pullRequest: parsePullRequest(packet.pullRequest),
         apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
+        apiKeySecretGrantHandle: parseApiKeySecretGrantHandle(packet.apiKeySecretGrantHandle),
         artifacts: parseArtifacts(packet.artifacts),
+        priorPhaseArtifacts: parsePriorPhaseArtifacts(packet.priorPhaseArtifacts),
         warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
         qaBrowser: parseQaBrowser(packet.qaBrowser),
         qaScope: parseQaScope(packet.qaScope ?? packet.qa_scope),
@@ -30,6 +33,128 @@ export function parseRunOnceDispatchPacket(value) {
         draft: parseDraftPrompt(packet.draft)
     };
 }
+function parseSandbox(value, schemaVersion) {
+    if (value === undefined || value === null) {
+        if (schemaVersion === 2) {
+            throw new Error("sandbox is required for dispatch schemaVersion 2.");
+        }
+        return null;
+    }
+    const sandbox = asObject(value, "sandbox");
+    const executionMode = requiredString(sandbox, "executionMode");
+    if (executionMode !== "host" && executionMode !== "docker") {
+        throw new Error("sandbox.executionMode must be host or docker.");
+    }
+    const executionPolicy = requiredString(sandbox, "executionPolicy");
+    if (executionPolicy !== "host_allowed" && executionPolicy !== "sandbox_preferred" && executionPolicy !== "sandbox_required") {
+        throw new Error("sandbox.executionPolicy is invalid.");
+    }
+    return {
+        dispatchAttemptId: requiredString(sandbox, "dispatchAttemptId"),
+        executionLeaseId: requiredString(sandbox, "executionLeaseId"),
+        runnerInstanceId: requiredString(sandbox, "runnerInstanceId"),
+        executionMode,
+        executionPolicy,
+        networkPolicy: parseSandboxNetworkPolicy(sandbox.networkPolicy),
+        requestedResources: parseSandboxResourceRequest(sandbox.requestedResources),
+        runtime: optionalString(sandbox, "runtime"),
+        sandboxConfigCommitSha: optionalString(sandbox, "sandboxConfigCommitSha"),
+        inputCommitSha: optionalString(sandbox, "inputCommitSha"),
+        contractDigest: optionalString(sandbox, "contractDigest"),
+        imageDigest: optionalString(sandbox, "imageDigest"),
+        publicationMode: parsePublicationMode(sandbox.publicationMode),
+        publishGrantHandle: parsePublishGrantHandle(sandbox.publishGrantHandle)
+    };
+}
+function parsePublicationMode(value) {
+    if (value === undefined || value === null)
+        return "shared_filesystem";
+    if (value !== "bridge_push" && value !== "shared_filesystem")
+        throw new Error("sandbox.publicationMode is invalid.");
+    return value;
+}
+function parsePublishGrantHandle(value) {
+    if (value === undefined || value === null)
+        return null;
+    const handle = asObject(value, "sandbox.publishGrantHandle");
+    const grantId = requiredString(handle, "grantId");
+    const branch = requiredString(handle, "branch");
+    const expiresAt = requiredString(handle, "expiresAt");
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(grantId)) {
+        throw new Error("sandbox.publishGrantHandle.grantId is invalid.");
+    }
+    if (branch.length > 240)
+        throw new Error("sandbox.publishGrantHandle.branch is too long.");
+    if (!Number.isFinite(Date.parse(expiresAt)))
+        throw new Error("sandbox.publishGrantHandle.expiresAt is invalid.");
+    return { grantId, branch, expiresAt };
+}
+function parseSandboxResourceRequest(value) {
+    if (value === undefined || value === null) {
+        return {
+            sandboxSlots: 1,
+            cpuMillis: 2000,
+            workerMemoryLimitBytes: 2 * 1024 ** 3,
+            serviceMemoryLimitBytes: 0,
+            runtimeOverheadBytes: 128 * 1024 ** 2,
+            memoryBytes: 2 * 1024 ** 3 + 128 * 1024 ** 2,
+            workspaceBytes: 10 * 1024 ** 3,
+            pids: 512,
+            buildSlots: 1
+        };
+    }
+    const resources = asObject(value, "sandbox.requestedResources");
+    const memoryBytes = boundedInteger(resources, "memoryBytes", 128 * 1024 ** 2, 512 * 1024 ** 3);
+    const hasMemoryBreakdown = ["workerMemoryLimitBytes", "serviceMemoryLimitBytes", "runtimeOverheadBytes"]
+        .some(key => resources[key] !== undefined && resources[key] !== null);
+    const workerMemoryLimitBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "workerMemoryLimitBytes", 128 * 1024 ** 2, 512 * 1024 ** 3)
+        : memoryBytes;
+    const serviceMemoryLimitBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "serviceMemoryLimitBytes", 0, 512 * 1024 ** 3)
+        : 0;
+    const runtimeOverheadBytes = hasMemoryBreakdown
+        ? boundedInteger(resources, "runtimeOverheadBytes", 0, 64 * 1024 ** 3)
+        : 0;
+    if (workerMemoryLimitBytes + serviceMemoryLimitBytes + runtimeOverheadBytes !== memoryBytes) {
+        throw new Error("sandbox.requestedResources memory breakdown must equal memoryBytes.");
+    }
+    return {
+        sandboxSlots: boundedInteger(resources, "sandboxSlots", 1, 4),
+        cpuMillis: boundedInteger(resources, "cpuMillis", 100, 64_000),
+        workerMemoryLimitBytes,
+        serviceMemoryLimitBytes,
+        runtimeOverheadBytes,
+        memoryBytes,
+        workspaceBytes: boundedInteger(resources, "workspaceBytes", 1024 ** 3, 10 * 1024 ** 4),
+        pids: boundedInteger(resources, "pids", 32, 65_536),
+        buildSlots: boundedInteger(resources, "buildSlots", 0, 4)
+    };
+}
+function parseSandboxNetworkPolicy(value) {
+    if (value === undefined || value === null)
+        return { mode: "offline", allowedHosts: [] };
+    const policy = asObject(value, "sandbox.networkPolicy");
+    const mode = requiredString(policy, "mode");
+    if (mode !== "offline" && mode !== "public_allowlist" && mode !== "open_public") {
+        throw new Error("sandbox.networkPolicy.mode is invalid.");
+    }
+    const rawHosts = policy.allowedHosts ?? [];
+    if (!Array.isArray(rawHosts) || rawHosts.some((host) => typeof host !== "string")) {
+        throw new Error("sandbox.networkPolicy.allowedHosts must be a string array.");
+    }
+    const allowedHosts = [...new Set(rawHosts.map(host => host.trim().toLowerCase()).filter(Boolean))];
+    if (allowedHosts.length > 128 || allowedHosts.some(host => !/^(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(host))) {
+        throw new Error("sandbox.networkPolicy.allowedHosts contains an invalid hostname.");
+    }
+    if (mode !== "public_allowlist" && allowedHosts.length > 0) {
+        throw new Error("sandbox.networkPolicy.allowedHosts requires public_allowlist mode.");
+    }
+    if (mode === "public_allowlist" && allowedHosts.length === 0) {
+        return { mode: "offline", allowedHosts: [] };
+    }
+    return { mode, allowedHosts };
+}
 export function failureResult(summary, events = []) {
     return {
         schemaVersion: 1,
@@ -172,6 +297,16 @@ function parseApiKeySecretGrant(value) {
         expiresAt: requiredString(grant, "expiresAt")
     };
 }
+function parseApiKeySecretGrantHandle(value) {
+    if (value === undefined || value === null)
+        return null;
+    const grant = asObject(value, "apiKeySecretGrantHandle");
+    return {
+        grantId: requiredString(grant, "grantId"),
+        provider: requiredString(grant, "provider"),
+        expiresAt: requiredString(grant, "expiresAt")
+    };
+}
 function parseServerLocal(value) {
     const serverLocal = asObject(value, "serverLocal");
     return {
@@ -549,6 +684,34 @@ function parseArtifacts(value) {
         };
     });
 }
+function parsePriorPhaseArtifacts(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("priorPhaseArtifacts must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        const artifact = asObject(entry, `priorPhaseArtifacts[${index}]`);
+        const phase = requiredString(artifact, "phase").trim().toLowerCase().replace(/-/g, "_");
+        if (phase !== "implementation" && phase !== "self_review" && phase !== "validation") {
+            throw new Error(`priorPhaseArtifacts[${index}].phase must be implementation, self_review, or validation.`);
+        }
+        return {
+            workItemId: requiredString(artifact, "workItemId"),
+            artifactId: requiredString(artifact, "artifactId"),
+            cycleRunId: requiredString(artifact, "cycleRunId"),
+            phase,
+            status: requiredString(artifact, "status"),
+            producedAt: requiredString(artifact, "producedAt"),
+            sourcePath: requiredString(artifact, "sourcePath"),
+            verdictJson: requiredString(artifact, "verdictJson"),
+            report: optionalString(artifact, "report") ?? "",
+            verdictContentHash: requiredString(artifact, "verdictContentHash").toLowerCase(),
+            reportContentHash: requiredString(artifact, "reportContentHash").toLowerCase()
+        };
+    });
+}
 function asObject(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`${label} must be an object.`);
@@ -616,3 +779,10 @@ function requiredNumber(source, key) {
     }
     return value;
 }
+function boundedInteger(source, key, minimum, maximum) {
+    const value = requiredNumber(source, key);
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`${key} must be an integer from ${minimum} through ${maximum}.`);
+    }
+    return value;
+}

package/dist/shared/path/path.js

@@ -4,7 +4,9 @@ export function isSubPath(root, candidate) {
     const normalizedRoot = path.resolve(root);
     const normalizedCandidate = path.resolve(candidate);
     const relative = path.relative(normalizedRoot, normalizedCandidate);
-    return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+    return relative === "" || (relative !== ".."
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative));
 }
 export async function resolveExistingDirectoryPath(inputPath) {
     const stat = await fs.stat(inputPath);

package/dist/shared/process/host-process-recovery.d.ts

@@ -0,0 +1,12 @@
+import type { HostProcessSupervisorMetadata } from "./host-process-supervisor.js";
+export type HostProcessRecoveryOutcome = "absent" | "terminated" | "pid_reused" | "unverifiable";
+export interface HostProcessRecovery {
+    recover(metadata: HostProcessSupervisorMetadata): Promise<HostProcessRecoveryOutcome>;
+}
+/** Exact, birth-marker-fenced recovery for a process tree left by an old bridge. */
+export declare class ExactHostProcessRecovery implements HostProcessRecovery {
+    private readonly platform;
+    private readonly graceMs;
+    constructor(platform?: NodeJS.Platform, graceMs?: number);
+    recover(metadata: HostProcessSupervisorMetadata): Promise<HostProcessRecoveryOutcome>;
+}