witnora 0.13.4 → 0.13.6

package/dist/gateway.js

@@ -1,12 +1,15 @@
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, createPrivateKey, createPublicKey, randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
 import { closeSync, openSync } from "node:fs";
-import { access, chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { loadConnection } from "./credentials.js";
 import { authorizeProjectConnection } from "./device-authorization.js";
+import { verifyHostedProbeCredential } from "./runtime-bootstrap.js";
 import { inspectIsolatedOutcomeProbe, observeInIsolatedOutcomeProbe } from "./probe-process.js";
+import { findAvailableRuntimeSandboxOrigin, LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256, startRuntimeSandboxFixture, } from "./runtime-sandbox-fixture.js";
+import { generateRuntimeSandboxKit, LOCAL_SANDBOX_ADAPTER_ID, LOCAL_SANDBOX_ADAPTER_VERSION, LOCAL_SANDBOX_PROBE_ID, } from "./runtime-sandbox-kit.js";
 const CONFIG_SCHEMA = "witnora.customer_gateway_setup.v0.1";
 const SECRETS_SCHEMA = "witnora.customer_gateway_local_secrets.v0.1";
 const RUNTIME_SCHEMA = "witnora.managed_gateway_runtime.v0.1";
@@ -41,6 +44,9 @@ export async function initializeCustomerGateway(options) {
     const missingScopes = expectedScopes.filter((scope) => !authorization.scopes.includes(scope));
     if (missingScopes.length > 0)
         throw new Error(`Gateway authorization is missing required scope(s): ${missingScopes.join(", ")}.`);
+    const runtimeKit = options.runtimeReferences
+        ? await prepareRuntimeSandboxKit(options.runtimeReferences, authorization, options.configHome, options.fetch ?? fetch, outDir)
+        : undefined;
     const config = {
         schemaVersion: CONFIG_SCHEMA,
         projectId: authorization.projectId,
@@ -51,8 +57,13 @@ export async function initializeCustomerGateway(options) {
         port: gatewayPort(process.env.WITNORA_GATEWAY_PORT, 8787),
         storageDirectory: "data",
         privacyMode: "metadata_only",
-        coverage: { recorded: "configured", enforced: "not_configured", outcomeVerified: "not_configured" },
+        coverage: runtimeKit
+            ? { recorded: "configured", enforced: "configured", outcomeVerified: "configured" }
+            : { recorded: "configured", enforced: "not_configured", outcomeVerified: "not_configured" },
+        ...(runtimeKit ? { runtimeWorker: runtimeKit.config } : {}),
     };
+    if (config.runtimeWorker)
+        config.runtimeWorker.configDigestSha256 = gatewayConfigDigest(config);
     const secrets = {
         schemaVersion: SECRETS_SCHEMA,
         gatewayToken: randomBytes(32).toString("base64url"),
@@ -67,6 +78,11 @@ export async function initializeCustomerGateway(options) {
             [gitignorePath, "secrets.json\ndata/\nruntime/\n", 0o644],
             [clientPath, gatewayClient(config), 0o644],
             [readmePath, gatewayReadme(config), 0o644],
+            ...(runtimeKit ? [
+                ...runtimeKit.secretFiles,
+                [join(outDir, runtimeKit.config.adapterModulePath), runtimeKit.adapterSource, 0o600],
+                [join(outDir, runtimeKit.config.probeModulePath), runtimeKit.probeSource, 0o600],
+            ] : []),
         ]) {
             await writeExclusive(path, content, force, mode);
             if (!force)
@@ -89,6 +105,238 @@ export async function initializeCustomerGateway(options) {
     output("This reference path establishes RECORDED evidence only. ENFORCED requires target write credentials behind a controlled execution adapter; OUTCOME VERIFIED requires a separate read-only probe.\n");
     return { configPath, secretsPath, config, generatedFiles };
 }
+export async function inspectLocalRuntimeBinding(options) {
+    const directory = resolve(options.repository ?? process.cwd(), options.dir ?? ".witnora/gateway");
+    const config = parseConfig(await readFile(join(directory, "gateway.json"), "utf8"));
+    const worker = config.runtimeWorker;
+    if (worker?.adapterId !== LOCAL_SANDBOX_ADAPTER_ID)
+        return undefined;
+    const ring = JSON.parse(await readFile(resolve(directory, config.storageDirectory, "source-keys.json"), "utf8"));
+    const sourceKeyId = typeof ring.activeKeyId === "string" && ring.keys?.some((key) => key.keyId === ring.activeKeyId && key.status === "active") ? ring.activeKeyId : undefined;
+    if (ring.collectorId !== config.collectorId || !sourceKeyId)
+        return undefined;
+    return { classification: "LOCAL_SANDBOX_ONLY", binding: {
+            collectorId: config.collectorId, sourceKeyId, configDigestSha256: worker.configDigestSha256, runtimeIdentity: { id: worker.runtimeIdentityId },
+            mandateDigestSha256: worker.mandateDigestSha256, adapterDigestSha256: worker.adapterModuleSha256,
+            probeDigestSha256: worker.probeModuleSha256, fixtureContractDigestSha256: worker.fixtureContractSha256,
+            ...(worker.probeApiKeyId ? { probeApiKeyId: worker.probeApiKeyId } : {}),
+        }, workerReady: true, fixtureReady: true };
+}
+export async function upgradeCustomerGatewayRuntime(options) {
+    const directory = resolve(options.repository, ".witnora/gateway");
+    const configPath = join(directory, "gateway.json");
+    const clientPath = join(directory, "client.mjs");
+    const readmePath = join(directory, "README.md");
+    const [configRaw, clientRaw, readmeRaw] = await Promise.all([readFile(configPath, "utf8"), readFile(clientPath, "utf8"), readFile(readmePath, "utf8")]);
+    const current = parseConfig(configRaw);
+    if (current.projectId !== options.authorization.projectId || current.server !== options.authorization.server)
+        throw new Error("Existing Gateway project/server binding does not match this authorized Runtime upgrade.");
+    const generatedClient = clientRaw === gatewayClient(current)
+        || (!current.runtimeWorker && clientRaw === recordedGatewayClient(current));
+    if (!generatedClient || readmeRaw !== gatewayReadme(current))
+        throw new Error("Existing Gateway files differ from the Witnora-generated version; refusing to overwrite them.");
+    if (current.runtimeWorker && current.runtimeWorker.adapterId !== LOCAL_SANDBOX_ADAPTER_ID) {
+        throw new Error("Existing Gateway already has a different Runtime worker; preserve it and reconfigure in Advanced mode.");
+    }
+    const runtimeKit = await prepareRuntimeSandboxKit(options.runtimeReferences, options.authorization, options.configHome, options.fetch ?? fetch, directory);
+    const next = { ...current, coverage: { recorded: "configured", enforced: "configured", outcomeVerified: "configured" }, runtimeWorker: runtimeKit.config };
+    next.runtimeWorker.configDigestSha256 = gatewayConfigDigest(next);
+    const replacingGeneratedRuntime = current.runtimeWorker?.adapterId === LOCAL_SANDBOX_ADAPTER_ID;
+    if (replacingGeneratedRuntime) {
+        const [adapterBytes, probeBytes] = await Promise.all([
+            readFile(resolve(directory, current.runtimeWorker.adapterModulePath)),
+            readFile(resolve(directory, current.runtimeWorker.probeModulePath)),
+        ]);
+        if (createHash("sha256").update(adapterBytes).digest("hex") !== current.runtimeWorker.adapterModuleSha256
+            || createHash("sha256").update(probeBytes).digest("hex") !== current.runtimeWorker.probeModuleSha256) {
+            throw new Error("Existing generated Runtime modules were modified; refusing to overwrite them.");
+        }
+        if (sameRuntimeGeneration(current.runtimeWorker, next.runtimeWorker)) {
+            return { config: current, generatedFiles: [], changed: false, rollback: async () => undefined };
+        }
+    }
+    const backupDirectory = join(directory, "data", "runtime-upgrade-backups", `${Date.now()}-${randomBytes(4).toString("hex")}`);
+    await mkdir(backupDirectory, { recursive: true });
+    const previousFiles = new Map([[configPath, configRaw], [clientPath, clientRaw], [readmePath, readmeRaw]]);
+    if (replacingGeneratedRuntime) {
+        previousFiles.set(resolve(directory, current.runtimeWorker.adapterModulePath), await readFile(resolve(directory, current.runtimeWorker.adapterModulePath)));
+        previousFiles.set(resolve(directory, current.runtimeWorker.probeModulePath), await readFile(resolve(directory, current.runtimeWorker.probeModulePath)));
+    }
+    await Promise.all([...previousFiles.entries()].map(([path, content]) => writeFile(join(backupDirectory, basename(path)), content, { mode: 0o600 })));
+    const created = [];
+    const restore = async () => {
+        await Promise.all([...previousFiles.entries()].map(([path, content]) => writeFile(path, content)));
+        for (const path of [...created].reverse())
+            await rm(path, { force: true }).catch(() => undefined);
+    };
+    try {
+        if (replacingGeneratedRuntime) {
+            await atomicWrite(join(directory, runtimeKit.config.adapterModulePath), runtimeKit.adapterSource, 0o600);
+            await atomicWrite(join(directory, runtimeKit.config.probeModulePath), runtimeKit.probeSource, 0o600);
+        }
+        else {
+            for (const [path, content, mode] of [
+                ...runtimeKit.secretFiles,
+                [join(directory, runtimeKit.config.adapterModulePath), runtimeKit.adapterSource, 0o600],
+                [join(directory, runtimeKit.config.probeModulePath), runtimeKit.probeSource, 0o600],
+            ]) {
+                await writeExclusive(path, content, false, mode);
+                created.push(path);
+            }
+        }
+        await atomicWrite(configPath, `${JSON.stringify(next, null, 2)}\n`, 0o644);
+        await atomicWrite(clientPath, gatewayClient(next), 0o644);
+        await atomicWrite(readmePath, gatewayReadme(next), 0o644);
+    }
+    catch (error) {
+        await restore();
+        throw error;
+    }
+    return { config: next, generatedFiles: [configPath, clientPath, readmePath, ...created, ...(replacingGeneratedRuntime ? [join(directory, runtimeKit.config.adapterModulePath), join(directory, runtimeKit.config.probeModulePath)] : [])], changed: true, rollback: restore };
+}
+function sameRuntimeGeneration(left, right) {
+    return JSON.stringify({ ...left, configDigestSha256: undefined }) === JSON.stringify({ ...right, configDigestSha256: undefined });
+}
+export class RuntimeSetupNotReadyError extends Error {
+    constructor(message) { super(message); this.name = "RuntimeSetupNotReadyError"; }
+}
+async function prepareRuntimeSandboxKit(references, authorization, configHome, requestFetch, outDir) {
+    try {
+        return await prepareRuntimeSandboxKitUnchecked(references, authorization, configHome, requestFetch, outDir);
+    }
+    catch (error) {
+        throw new RuntimeSetupNotReadyError(error instanceof Error ? error.message : String(error));
+    }
+}
+async function prepareRuntimeSandboxKitUnchecked(references, authorization, configHome, requestFetch, outDir) {
+    validateRuntimeReferences(references);
+    const localRuntimePublicKeyPem = await ed25519PublicKeyPem(references.runtimeSigningKeyHandle);
+    const probe = references.probeConnectionName
+        ? await loadConnection(references.probeConnectionName, { configHome })
+        : references.probeHostedCredentialHandle
+            ? { projectId: authorization.projectId, server: authorization.server, apiKey: await readSecretProviderHandle(references.probeHostedCredentialHandle) }
+            : undefined;
+    if (!probe || probe.projectId !== authorization.projectId || probe.server !== authorization.server || probe.apiKey === authorization.apiKey) {
+        throw new Error("The existing outcome-probe connection must be separate and bound to this project and server.");
+    }
+    const response = await requestFetch(`${authorization.server}/v1/projects/${encodeURIComponent(authorization.projectId)}/runtime-identities`, {
+        headers: { authorization: `Bearer ${authorization.apiKey}` },
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(String(body.error ?? `Runtime identity lookup failed with HTTP ${response.status}.`));
+    const identity = body.runtimeIdentities?.find((item) => item.runtimeIdentityId === references.runtimeIdentityId && item.keyId === references.runtimeKeyId);
+    const now = Date.now();
+    if (!identity || identity.status !== "ACTIVE" || !Number.isFinite(Date.parse(String(identity.validFrom))) || !Number.isFinite(Date.parse(String(identity.validUntil)))
+        || Date.parse(String(identity.validFrom)) > now || Date.parse(String(identity.validUntil)) <= now) {
+        throw new Error("The referenced runtime identity and key are not active for this project.");
+    }
+    if (!new Set(["SETUP_AUTOPILOT_SANDBOX", "DEVELOPMENT_FIXTURE"]).has(String(identity.registrationMethod)) || !Array.isArray(identity.adapterCapabilities)
+        || identity.adapterCapabilities.length !== 1 || identity.adapterCapabilities[0] !== LOCAL_SANDBOX_ADAPTER_ID) {
+        throw new Error("The Hosted runtime identity is not exclusively bound to the local sandbox adapter fixture.");
+    }
+    let hostedRuntimePublicKeyPem;
+    try {
+        hostedRuntimePublicKeyPem = createPublicKey(String(identity.publicKeyPem)).export({ type: "spki", format: "pem" }).toString();
+    }
+    catch {
+        throw new Error("The Hosted runtime identity has no valid public key binding.");
+    }
+    if (hostedRuntimePublicKeyPem !== localRuntimePublicKeyPem)
+        throw new Error("The local Runtime signing key does not match the Hosted runtime identity.");
+    const mandateResponse = await requestFetch(`${authorization.server}/v1/projects/${encodeURIComponent(authorization.projectId)}/mandates/${encodeURIComponent(references.mandateId)}`, {
+        headers: { authorization: `Bearer ${authorization.apiKey}` },
+    });
+    const mandate = await mandateResponse.json().catch(() => ({}));
+    if (!mandateResponse.ok)
+        throw new Error(String(mandate.error ?? `Mandate lookup failed with HTTP ${mandateResponse.status}.`));
+    const mandatePayload = mandate.payload && typeof mandate.payload === "object" && !Array.isArray(mandate.payload) ? mandate.payload : {};
+    const mandateConstraints = mandatePayload.constraints && typeof mandatePayload.constraints === "object" && !Array.isArray(mandatePayload.constraints)
+        ? mandatePayload.constraints : {};
+    if (mandate.id !== references.mandateId || mandate.status !== "ACTIVE"
+        || !validDigest(String(mandate.digestSha256 ?? ""))
+        || !activeWindow(mandatePayload.validFrom, mandatePayload.expiresAt, now)
+        || !Number.isInteger(mandatePayload.maxUses) || Number(mandatePayload.maxUses) < 1 || Number(mandatePayload.maxUses) > 1_000
+        || mandatePayload.maxDelegationDepth !== 0 || mandatePayload.parentMandateId !== undefined
+        || JSON.stringify(mandatePayload.audience) !== JSON.stringify(["WitnoraLocalSandbox"])
+        || JSON.stringify(mandatePayload.permittedActionClasses) !== JSON.stringify(["UPDATE"])
+        || !Array.isArray(mandatePayload.permittedOperations) || mandatePayload.permittedOperations.length !== 1 || !["UPDATE", "WitnoraLocalSandbox:UPDATE"].includes(String(mandatePayload.permittedOperations[0]))
+        || !Array.isArray(mandatePayload.permittedResources) || mandatePayload.permittedResources.length !== 1 || !["mock-state/*", "WitnoraLocalSandbox:mock-state/*"].includes(String(mandatePayload.permittedResources[0]))
+        || mandateConstraints.approvalRequirement !== "HUMAN" || mandateConstraints.rollbackRequired !== true
+        || mandateConstraints.outcomePredicateRequirement !== "state_subset"
+        || !Array.isArray(mandateConstraints.allowedEnvironment) || mandateConstraints.allowedEnvironment.length !== 1 || !["sandbox", "local"].includes(String(mandateConstraints.allowedEnvironment[0]))
+        || mandateConstraints.payment !== undefined || mandateConstraints.monetaryLimit !== undefined) {
+        throw new Error("The referenced mandate is not an active localhost sandbox UPDATE mandate.");
+    }
+    if (typeof mandatePayload.granteeIdentityId !== "string" || !mandatePayload.granteeIdentityId)
+        throw new Error("The referenced sandbox mandate has no grantee identity binding.");
+    const sandboxOrigin = references.sandboxOrigin ?? await findAvailableRuntimeSandboxOrigin();
+    const generated = generateRuntimeSandboxKit(sandboxOrigin);
+    if (references.adapterDigestSha256 && references.adapterDigestSha256 !== generated.adapterSha256
+        || references.probeDigestSha256 && references.probeDigestSha256 !== generated.probeSha256
+        || references.fixtureContractDigestSha256 && references.fixtureContractDigestSha256 !== LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256) {
+        throw new Error("Generated Runtime modules do not match the Hosted bootstrap contract.");
+    }
+    if (references.probeApiKeyId) {
+        if (!references.bootstrapId || !references.setupPlanId)
+            throw new Error("Hosted Runtime bootstrap references are incomplete.");
+        await verifyHostedProbeCredential({
+            projectId: authorization.projectId, server: authorization.server,
+            setupPlanId: references.setupPlanId, bootstrapId: references.bootstrapId,
+            probeApiKeyId: references.probeApiKeyId, apiKey: probe.apiKey, fetch: requestFetch,
+        });
+    }
+    const sandboxSecretsDirectory = join(outDir, "data", "runtime-sandbox");
+    const readCredentialPath = join(sandboxSecretsDirectory, "read-credential.txt");
+    const writeCredentialPath = join(sandboxSecretsDirectory, "write-credential.txt");
+    const auditCredentialPath = join(sandboxSecretsDirectory, "audit-reconcile-credential.txt");
+    const readCredential = randomBytes(32).toString("base64url");
+    const writeCredential = randomBytes(32).toString("base64url");
+    const auditCredential = randomBytes(32).toString("base64url");
+    return {
+        adapterSource: generated.adapterSource,
+        probeSource: generated.probeSource,
+        config: {
+            enabled: true,
+            adapterModulePath: "runtime/local-sandbox-adapter.mjs",
+            adapterModuleSha256: generated.adapterSha256,
+            probeModulePath: "runtime/local-sandbox-probe.mjs",
+            probeModuleSha256: generated.probeSha256,
+            adapterId: LOCAL_SANDBOX_ADAPTER_ID,
+            adapterVersion: LOCAL_SANDBOX_ADAPTER_VERSION,
+            probeId: LOCAL_SANDBOX_PROBE_ID,
+            ...(references.probeConnectionName ? { probeConnectionName: references.probeConnectionName } : { probeHostedCredentialHandle: references.probeHostedCredentialHandle }),
+            ...(references.probeApiKeyId ? { probeApiKeyId: references.probeApiKeyId, runtimeBootstrapId: references.bootstrapId, runtimeSetupPlanId: references.setupPlanId } : {}),
+            probeTargetCredentialHandle: pathToFileURL(readCredentialPath).href,
+            targetWriteCredentialHandle: pathToFileURL(writeCredentialPath).href,
+            reconcileAuditCredentialHandle: pathToFileURL(auditCredentialPath).href,
+            sandboxOrigin,
+            fixtureContractSha256: LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256,
+            mandateDigestSha256: String(mandate.digestSha256),
+            runtimeIdentityId: references.runtimeIdentityId,
+            mandateId: references.mandateId,
+            sandboxPrincipalId: mandatePayload.granteeIdentityId,
+            runtimeKeyId: references.runtimeKeyId,
+            runtimeSigningKeyHandle: references.runtimeSigningKeyHandle,
+            grantTtlSeconds: 120,
+            pollIntervalMs: 2_000,
+        },
+        secretFiles: [[readCredentialPath, `${readCredential}\n`, 0o600], [writeCredentialPath, `${writeCredential}\n`, 0o600], [auditCredentialPath, `${auditCredential}\n`, 0o600]],
+    };
+}
+function validateRuntimeReferences(value) {
+    if ((!value.probeConnectionName || !/^[A-Za-z0-9._-]{1,64}$/.test(value.probeConnectionName)) && !credentialHandle(value.probeHostedCredentialHandle ?? "")
+        || !value.mandateId || !value.runtimeIdentityId || !value.runtimeKeyId || !credentialHandle(value.runtimeSigningKeyHandle)) {
+        throw new Error("Runtime setup references must contain a named probe connection, active runtime identity/key, and opaque credential handles.");
+    }
+    for (const handle of [value.runtimeSigningKeyHandle, ...(value.probeHostedCredentialHandle ? [value.probeHostedCredentialHandle] : [])]) {
+        const url = new URL(handle);
+        if (url.protocol !== "file:")
+            throw new Error("The v0.1 localhost sandbox runtime supports file:// secret-provider handles only.");
+    }
+    if (value.probeHostedCredentialHandle === value.runtimeSigningKeyHandle)
+        throw new Error("Probe and runtime signing credentials must use separate handles.");
+}
 export async function inspectCustomerGatewayFiles(options) {
     const repository = resolve(options.repository ?? process.cwd());
     const directory = resolve(repository, options.outDir ?? ".witnora/gateway");
@@ -147,11 +395,29 @@ export async function doctorCustomerGateway(options) {
                     throw new Error("Runtime adapter or probe module digest does not match gateway.json.");
                 const [primary, probe] = await Promise.all([
                     loadConnection(config.connectionName, { configHome: options.configHome }),
-                    loadConnection(config.runtimeWorker.probeConnectionName, { configHome: options.configHome }),
+                    loadProbeHostedConnection(config.runtimeWorker, config.projectId, config.server, options.configHome),
                 ]);
                 if (!primary || !probe || probe.projectId !== config.projectId || probe.server !== config.server || probe.apiKey === primary.apiKey) {
                     throw new Error("A separate outcome-probe credential bound to this project is required.");
                 }
+                if (config.runtimeWorker.probeApiKeyId)
+                    await verifyConfiguredProbeCredential(config, probe.apiKey, options.fetch ?? fetch);
+                if (config.runtimeWorker.adapterId === LOCAL_SANDBOX_ADAPTER_ID) {
+                    if (!config.runtimeWorker.runtimeKeyId || !config.runtimeWorker.runtimeSigningKeyHandle || !config.runtimeWorker.targetWriteCredentialHandle
+                        || !config.runtimeWorker.mandateId || !config.runtimeWorker.sandboxPrincipalId) {
+                        throw new Error("The generated localhost Runtime identity, mandate, and credential bindings are incomplete.");
+                    }
+                    await ed25519PublicKeyPem(config.runtimeWorker.runtimeSigningKeyHandle);
+                }
+                if (config.runtimeWorker.targetWriteCredentialHandle) {
+                    const [readTargetCredential, writeTargetCredential, auditCredential] = await Promise.all([
+                        readSecretProviderHandle(config.runtimeWorker.probeTargetCredentialHandle),
+                        readSecretProviderHandle(config.runtimeWorker.targetWriteCredentialHandle),
+                        readSecretProviderHandle(config.runtimeWorker.reconcileAuditCredentialHandle),
+                    ]);
+                    if (new Set([readTargetCredential, writeTargetCredential, auditCredential]).size !== 3)
+                        throw new Error("Sandbox read, write, and reconciliation credentials must contain separate values.");
+                }
                 checks.push({ id: "runtime_configuration", status: "PASS", message: "The digest-pinned adapter module and separate outcome-probe credential are present." });
             }
             catch (error) {
@@ -159,7 +425,7 @@ export async function doctorCustomerGateway(options) {
             }
         }
         try {
-            const health = await gatewayHealth(`http://${config.host}:${config.port}`, options.fetch ?? fetch, Boolean(config.runtimeWorker));
+            const health = await gatewayHealth(`http://${config.host}:${config.port}`, options.fetch ?? fetch, config.runtimeWorker);
             if (!health)
                 throw new Error("Gateway health or runtime-worker readiness was not established.");
             checks.push({ id: "process", status: "PASS", message: `Gateway is listening at http://${config.host}:${config.port}.` });
@@ -206,35 +472,122 @@ export async function runCustomerGateway(options) {
     const keyRing = await (await exists(keyRingPath)
         ? CustomerSourceKeyRing.open(keyRingPath)
         : CustomerSourceKeyRing.create(keyRingPath, config.collectorId));
-    const actionWorker = config.runtimeWorker
-        ? await createConfiguredRuntimeActionWorker({
-            directory, config, connection, configHome: options.configHome,
-            DurableApprovedActionWorker: (await durableWorker).DurableApprovedActionWorker,
-            FileActionCheckpointStore: (await durableWorker).FileActionCheckpointStore,
+    const sandboxFixture = config.runtimeWorker?.adapterId === LOCAL_SANDBOX_ADAPTER_ID
+        ? await startRuntimeSandboxFixture({
+            origin: config.runtimeWorker.sandboxOrigin, directory: join(dataDirectory, "runtime-sandbox", "fixture"),
+            readCredentialHandle: config.runtimeWorker.probeTargetCredentialHandle,
+            writeCredentialHandle: config.runtimeWorker.targetWriteCredentialHandle,
+            auditCredentialHandle: config.runtimeWorker.reconcileAuditCredentialHandle,
+            contractSha256: config.runtimeWorker.fixtureContractSha256,
         })
         : undefined;
-    actionWorker?.start();
-    const gateway = await startCustomerOwnedCollectorGateway({
-        client: new RemoteCollectorClient({ baseUrl: connection.server, projectId: connection.projectId, apiKey: connection.apiKey }),
-        keyRing,
-        gatewayToken: secrets.gatewayToken,
-        storageDirectory: dataDirectory,
-        host: process.env.WITNORA_GATEWAY_HOST?.trim() || config.host,
-        port: gatewayPort(process.env.WITNORA_GATEWAY_PORT, config.port),
-        environment: "customer-owned",
-        ...(actionWorker && config.runtimeWorker ? { actionWorker: {
-                track: (input) => isConfiguredRuntimeProposal(input.proposal, config.runtimeWorker) ? actionWorker.track(input) : Promise.resolve(undefined),
-                status: () => actionWorker.status(), close: () => actionWorker.stop(),
-            } } : {}),
-    });
-    process.stdout.write(`Witnora customer-owned Gateway listening on ${gateway.baseUrl}\n`);
-    process.stdout.write(config.runtimeWorker
-        ? "Runtime worker: READY. Approved exact configured actions execute automatically, then use the separate read-only probe and Hosted signed receipt.\n"
-        : "Evidence ceiling: RECORDED. No exact target adapter and separate outcome probe are configured, so runtime writes remain fail-closed.\n");
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-        process.once(signal, () => void gateway.close().finally(() => process.exit(0)));
+    try {
+        const actionWorker = config.runtimeWorker
+            ? await createConfiguredRuntimeActionWorker({
+                directory, config, connection, configHome: options.configHome,
+                DurableApprovedActionWorker: (await durableWorker).DurableApprovedActionWorker,
+                FileActionCheckpointStore: (await durableWorker).FileActionCheckpointStore,
+            })
+            : undefined;
+        actionWorker?.start();
+        const gateway = await startCustomerOwnedCollectorGateway({
+            client: new RemoteCollectorClient({ baseUrl: connection.server, projectId: connection.projectId, apiKey: connection.apiKey }),
+            keyRing,
+            gatewayToken: secrets.gatewayToken,
+            storageDirectory: dataDirectory,
+            host: process.env.WITNORA_GATEWAY_HOST?.trim() || config.host,
+            port: gatewayPort(process.env.WITNORA_GATEWAY_PORT, config.port),
+            environment: "customer-owned",
+            ...(actionWorker && config.runtimeWorker ? { actionWorker: {
+                    track: (input) => isConfiguredRuntimeProposal(input.proposal, config.runtimeWorker) ? actionWorker.track(input) : Promise.resolve(undefined),
+                    status: async () => {
+                        const status = await actionWorker.status();
+                        const probeReady = await runtimeProbeCredentialReady(config, options.configHome);
+                        return {
+                            ...status,
+                            ready: status.ready === true && probeReady,
+                            runtimeBinding: {
+                                configDigestSha256: config.runtimeWorker.configDigestSha256,
+                                ...(config.runtimeWorker.probeApiKeyId ? { probeApiKeyId: config.runtimeWorker.probeApiKeyId } : {}),
+                            },
+                            ...(!probeReady ? { lastError: "Hosted outcome-probe credential is not active for this Runtime generation." } : {}),
+                            ...(config.runtimeWorker?.adapterId === LOCAL_SANDBOX_ADAPTER_ID
+                                ? { fixtureReady: await runtimeSandboxFixtureReady(config.runtimeWorker) }
+                                : {}),
+                        };
+                    },
+                    close: () => actionWorker.stop(),
+                    ...(config.runtimeWorker.adapterId === LOCAL_SANDBOX_ADAPTER_ID ? { runtimeBinding: {
+                            classification: "LOCAL_SANDBOX_ONLY",
+                            binding: {
+                                collectorId: config.collectorId, sourceKeyId: keyRing.activeSigner().keyId,
+                                configDigestSha256: config.runtimeWorker.configDigestSha256,
+                                runtimeIdentity: { id: config.runtimeWorker.runtimeIdentityId },
+                                mandateDigestSha256: config.runtimeWorker.mandateDigestSha256,
+                                adapterDigestSha256: config.runtimeWorker.adapterModuleSha256,
+                                probeDigestSha256: config.runtimeWorker.probeModuleSha256,
+                                fixtureContractDigestSha256: config.runtimeWorker.fixtureContractSha256,
+                                ...(config.runtimeWorker.probeApiKeyId ? { probeApiKeyId: config.runtimeWorker.probeApiKeyId } : {}),
+                            },
+                            fixtureReady: false,
+                        } } : {}),
+                } } : {}),
+        });
+        process.stdout.write(`Witnora customer-owned Gateway listening on ${gateway.baseUrl}\n`);
+        process.stdout.write(config.runtimeWorker
+            ? "Runtime worker: READY. Approved exact configured actions execute automatically, then use the separate read-only probe and Hosted signed receipt.\n"
+            : "Evidence ceiling: RECORDED. No exact target adapter and separate outcome probe are configured, so runtime writes remain fail-closed.\n");
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            process.once(signal, () => void Promise.allSettled([gateway.close(), ...(sandboxFixture ? [sandboxFixture.close()] : [])]).finally(() => process.exit(0)));
+        }
+    }
+    catch (error) {
+        await sandboxFixture?.close().catch(() => undefined);
+        throw error;
+    }
+}
+async function runtimeSandboxFixtureReady(config) {
+    try {
+        if (config.adapterId !== LOCAL_SANDBOX_ADAPTER_ID || !config.sandboxOrigin || !config.probeTargetCredentialHandle || !config.fixtureContractSha256)
+            return false;
+        const credential = await readSecretProviderHandle(config.probeTargetCredentialHandle);
+        const response = await fetch(`${config.sandboxOrigin}/healthz`, {
+            redirect: "error",
+            headers: { "x-sandbox-read-credential": credential },
+            signal: AbortSignal.timeout(2_000),
+        });
+        const body = await response.json().catch(() => ({}));
+        return response.ok && body.origin === config.sandboxOrigin && body.contractSha256 === config.fixtureContractSha256;
+    }
+    catch {
+        return false;
     }
 }
+async function runtimeProbeCredentialReady(config, configHome) {
+    try {
+        const worker = config.runtimeWorker;
+        if (!worker?.probeApiKeyId)
+            return true;
+        const probe = await loadProbeHostedConnection(worker, config.projectId, config.server, configHome);
+        if (!probe)
+            return false;
+        await verifyConfiguredProbeCredential(config, probe.apiKey, fetch);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function verifyConfiguredProbeCredential(config, apiKey, requestFetch) {
+    const worker = config.runtimeWorker;
+    if (!worker?.probeApiKeyId || !worker.runtimeBootstrapId || !worker.runtimeSetupPlanId)
+        throw new Error("Hosted Runtime probe generation binding is incomplete.");
+    await verifyHostedProbeCredential({
+        projectId: config.projectId, server: config.server,
+        setupPlanId: worker.runtimeSetupPlanId, bootstrapId: worker.runtimeBootstrapId,
+        probeApiKeyId: worker.probeApiKeyId, apiKey, fetch: requestFetch,
+    });
+}
 export async function createConfiguredRuntimeActionWorker(input) {
     const workerConfig = input.config.runtimeWorker;
     if (!workerConfig?.enabled)
@@ -251,17 +604,25 @@ export async function createConfiguredRuntimeActionWorker(input) {
     const adapterModule = await import(`${pathToFileURL(adapterModulePath).href}?sha256=${adapterModuleDigest}`);
     if (typeof adapterModule.createWitnoraRuntimeAdapter !== "function")
         throw new Error("Runtime adapter module must export its factory.");
-    const probeConnection = await loadConnection(workerConfig.probeConnectionName, { configHome: input.configHome });
+    const probeConnection = await loadProbeHostedConnection(workerConfig, input.config.projectId, input.config.server, input.configHome);
     if (!probeConnection || probeConnection.projectId !== input.config.projectId || probeConnection.server !== input.config.server) {
         throw new Error("The separate outcome-probe credential does not match this Gateway project and server.");
     }
     if (probeConnection.apiKey === input.connection.apiKey)
         throw new Error("The execution Gateway and outcome probe must use separate Hosted credentials.");
+    if (workerConfig.probeApiKeyId)
+        await verifyConfiguredProbeCredential(input.config, probeConnection.apiKey, input.fetch ?? fetch);
     const adapterContext = Object.freeze({
         adapterId: workerConfig.adapterId, adapterVersion: workerConfig.adapterVersion,
         projectId: input.config.projectId,
         hosted: runtimeHostedTransport(input.connection, input.fetch ?? fetch),
         storageDirectory: resolve(input.directory, "data", "runtime-actions"),
+        ...(workerConfig.runtimeKeyId && workerConfig.runtimeSigningKeyHandle && workerConfig.targetWriteCredentialHandle ? {
+            runtimeIdentity: Object.freeze({ id: workerConfig.runtimeIdentityId, keyId: workerConfig.runtimeKeyId }),
+            runtimeSigningKey: Object.freeze({ handle: workerConfig.runtimeSigningKeyHandle, access: "READ_ONLY" }),
+            targetWriteCredential: Object.freeze({ handle: workerConfig.targetWriteCredentialHandle, access: "WRITE_ONLY" }),
+            reconcileAuditCredential: Object.freeze({ handle: workerConfig.reconcileAuditCredentialHandle, access: "READ_ONLY" }),
+        } : {}),
     });
     const isolatedProbeConfig = {
         modulePath: probeModulePath,
@@ -276,6 +637,10 @@ export async function createConfiguredRuntimeActionWorker(input) {
         || typeof runtime.prepareClaim !== "function" || typeof runtime.execute !== "function" || typeof runtime.reconcile !== "function") {
         throw new Error("Runtime adapter does not match the exact configured id/version or read-only reconciliation contract.");
     }
+    if (workerConfig.adapterId === LOCAL_SANDBOX_ADAPTER_ID && JSON.stringify(runtime.capabilities) !== JSON.stringify({
+        targetSystem: "WitnoraLocalSandbox", operations: ["UPDATE"], origins: [workerConfig.sandboxOrigin], resources: ["mock-state/*"],
+    }))
+        throw new Error("Generated Runtime adapter capabilities do not match the exact localhost fixture contract.");
     const requestFetch = input.fetch ?? fetch;
     const primary = projectTransport(input.connection, requestFetch);
     const verifier = projectTransport(probeConnection, requestFetch);
@@ -357,7 +722,9 @@ function isConfiguredRuntimeProposal(proposal, config) {
     const intent = proposal.executionIntent;
     return Boolean(intent && typeof intent === "object" && !Array.isArray(intent)
         && intent.adapterId === config.adapterId
-        && typeof intent.adapterVersionConstraint === "string");
+        && typeof intent.adapterVersionConstraint === "string"
+        && (config.adapterId !== LOCAL_SANDBOX_ADAPTER_ID || proposal.targetSystem === "WitnoraLocalSandbox")
+        && (!config.mandateId || proposal.mandateId === config.mandateId));
 }
 export async function startManagedCustomerGateway(options = {}) {
     const repository = resolve(options.repository ?? process.cwd());
@@ -443,7 +810,7 @@ export async function statusManagedCustomerGateway(options = {}) {
     const config = parseConfig(await readFile(join(directory, "gateway.json"), "utf8"));
     const baseUrl = `http://${config.host}:${config.port}`;
     const runtime = await readRuntime(directory);
-    const health = await gatewayHealth(baseUrl, options.fetch ?? fetch, Boolean(config.runtimeWorker));
+    const health = await gatewayHealth(baseUrl, options.fetch ?? fetch, config.runtimeWorker);
     const base = {
         schemaVersion: "witnora.managed_gateway_status.v0.1",
         baseUrl,
@@ -549,6 +916,9 @@ export function renderGatewayDoctor(result) {
         "",
     ].join("\n");
 }
+export function isGatewayDoctorReady(result) {
+    return result.overall === "READY_TO_RECORD" || result.overall === "READY_FOR_RUNTIME";
+}
 function parseConfig(raw) {
     const value = JSON.parse(raw);
     if (value.schemaVersion !== CONFIG_SCHEMA || !value.projectId || !value.server || !value.connectionName || !value.collectorId) {
@@ -560,19 +930,34 @@ function parseConfig(raw) {
         throw new Error("Gateway host and port are invalid.");
     if (value.runtimeWorker)
         validateRuntimeWorkerConfig(value.runtimeWorker);
-    return value;
+    const config = value;
+    if (config.runtimeWorker?.adapterId === LOCAL_SANDBOX_ADAPTER_ID && gatewayConfigDigest(config) !== config.runtimeWorker.configDigestSha256) {
+        throw new Error("Generated localhost Runtime config digest does not match gateway.json.");
+    }
+    return config;
 }
 function validateRuntimeWorkerConfig(value) {
     if (value.enabled !== true || !value.adapterModulePath || !/^[a-f0-9]{64}$/.test(value.adapterModuleSha256)
         || !value.probeModulePath || !/^[a-f0-9]{64}$/.test(value.probeModuleSha256)
         || !value.adapterId || !/^v?\d+\.\d+\.\d+$/.test(value.adapterVersion) || !value.probeId
-        || !value.probeConnectionName || !credentialHandle(value.probeTargetCredentialHandle) || !value.runtimeIdentityId) {
+        || (!value.probeConnectionName && !credentialHandle(value.probeHostedCredentialHandle ?? ""))
+        || !credentialHandle(value.probeTargetCredentialHandle) || !value.runtimeIdentityId) {
         throw new Error("gateway.json runtimeWorker requires separate exact adapter/probe module digests, adapter id/version, probe credentials, and runtime identity.");
     }
     if (value.adapterModulePath === value.probeModulePath || value.adapterModuleSha256 === value.probeModuleSha256)
         throw new Error("runtimeWorker adapter and outcome probe modules must be independently pinned.");
     if (value.adapterId === value.probeId)
         throw new Error("runtimeWorker adapter and outcome probe must be separate.");
+    const bootstrapFields = [value.probeApiKeyId, value.runtimeBootstrapId, value.runtimeSetupPlanId].filter(Boolean);
+    if (bootstrapFields.length !== 0 && (bootstrapFields.length !== 3 || bootstrapFields.some((field) => !/^[A-Za-z0-9._:-]{1,200}$/.test(field)))) {
+        throw new Error("runtimeWorker Hosted bootstrap probe generation binding is incomplete.");
+    }
+    if (value.adapterId === LOCAL_SANDBOX_ADAPTER_ID && (!value.mandateId || !value.sandboxPrincipalId || !value.runtimeKeyId
+        || !credentialHandle(value.runtimeSigningKeyHandle ?? "") || !credentialHandle(value.targetWriteCredentialHandle ?? "") || !credentialHandle(value.reconcileAuditCredentialHandle ?? "")
+        || !localSandboxOrigin(value.sandboxOrigin) || value.fixtureContractSha256 !== LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256
+        || !validDigest(value.mandateDigestSha256 ?? "") || !validDigest(value.configDigestSha256 ?? ""))) {
+        throw new Error("The generated localhost sandbox adapter requires exact mandate, runtime signing-key, and target write-credential references.");
+    }
     if (value.grantTtlSeconds !== undefined && (!Number.isInteger(value.grantTtlSeconds) || value.grantTtlSeconds < 15 || value.grantTtlSeconds > 300))
         throw new Error("runtimeWorker grantTtlSeconds must be between 15 and 300.");
     if (value.pollIntervalMs !== undefined && (!Number.isInteger(value.pollIntervalMs) || value.pollIntervalMs < 250 || value.pollIntervalMs > 30_000))
@@ -599,14 +984,75 @@ function gatewayPort(value, fallback) {
     return parsed;
 }
 function gatewayReadme(config) {
-    return `# Witnora customer-owned Gateway\n\nThis directory configures a metadata-only Gateway for project \`${config.projectId}\`. The Setup Autopilot starts it in the background after browser authorization.\n\n## Operations\n\n\`\`\`bash\nnpx witnora@latest gateway status\nnpx witnora@latest gateway logs\nnpx witnora@latest gateway restart\nnpx witnora@latest gateway stop\n\`\`\`\n\n\`gateway run\` remains available as a foreground debugging command. In the Agent repository, import the generated client at one meaningful sandbox workflow boundary:\n\n\`\`\`js\nimport { randomUUID } from "node:crypto";\nimport { witnoraGateway } from "./.witnora/gateway/client.mjs";\n\nconst runId = randomUUID();\nawait witnoraGateway.start(runId, { workflow: "sandbox-workflow" });\ntry {\n  // Run the existing customer workflow here. Do not add raw inputs or outputs.\n  await witnoraGateway.event(runId, "workflow.step.completed", { step: "meaningful-boundary" });\n  await witnoraGateway.complete(runId, { status: "completed" });\n} catch (error) {\n  await witnoraGateway.event(runId, "workflow.failed", { errorType: error?.name ?? "Error" });\n  await witnoraGateway.complete(runId, { status: "failed" });\n  throw error;\n}\n\`\`\`\n\nThe generated client reads only the local ignored Gateway token and sends metadata to \`http://${config.host}:${config.port}\`. The Hosted API key and source-signing key stay in the Gateway process. Do not commit \`secrets.json\`, \`data/\`, or \`runtime/\`.\n\nThis reference process creates source-signed, durable **RECORDED** evidence. It does not claim complete mediation. **ENFORCED** requires the target write credential to be removed from the Agent and placed behind a controlled execution adapter. **OUTCOME VERIFIED** requires a separate read-only credential and independent probe.\n`;
+    const assuranceBoundary = config.runtimeWorker
+        ? "The generated localhost sandbox Runtime has a digest-pinned adapter, separate child read-only probe, and local credential boundary. Confirm `gateway doctor` reports **READY_FOR_RUNTIME**. This readiness does not establish coverage of real customer paths, CURRENT status, or a verified outcome."
+        : "This reference process creates source-signed, durable **RECORDED** evidence. It does not claim complete mediation. **ENFORCED** requires the target write credential to be removed from the Agent and placed behind a controlled execution adapter. **OUTCOME VERIFIED** requires a separate read-only credential and independent probe.";
+    return `# Witnora customer-owned Gateway\n\nThis directory configures a metadata-only Gateway for project \`${config.projectId}\`. The Setup Autopilot starts it in the background after browser authorization.\n\n## Operations\n\n\`\`\`bash\nnpx witnora@latest gateway status\nnpx witnora@latest gateway logs\nnpx witnora@latest gateway restart\nnpx witnora@latest gateway stop\n\`\`\`\n\n\`gateway run\` remains available as a foreground debugging command. In the Agent repository, import the generated client at one meaningful sandbox workflow boundary:\n\n\`\`\`js\nimport { randomUUID } from "node:crypto";\nimport { witnoraGateway } from "./.witnora/gateway/client.mjs";\n\nconst runId = randomUUID();\nawait witnoraGateway.start(runId, { workflow: "sandbox-workflow" });\ntry {\n  // Run the existing customer workflow here. Do not add raw inputs or outputs.\n  await witnoraGateway.event(runId, "workflow.step.completed", { step: "meaningful-boundary" });\n  await witnoraGateway.complete(runId, { status: "completed" });\n} catch (error) {\n  await witnoraGateway.event(runId, "workflow.failed", { errorType: error?.name ?? "Error" });\n  await witnoraGateway.complete(runId, { status: "failed" });\n  throw error;\n}\n\`\`\`\n\nThe generated client reads only the local ignored Gateway token and sends metadata to \`http://${config.host}:${config.port}\`. The Hosted API key and source-signing key stay in the Gateway process. Do not commit \`secrets.json\`, \`data/\`, or \`runtime/\`.\n\n${assuranceBoundary}\n`;
+}
+function gatewayConfigDigest(config) {
+    const runtimeWorker = config.runtimeWorker ? { ...config.runtimeWorker, configDigestSha256: undefined } : undefined;
+    return createHash("sha256").update(JSON.stringify(canonical({ ...config, runtimeWorker }))).digest("hex");
+}
+function canonical(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, canonical(item)]));
+    return undefined;
+}
+function activeWindow(validFrom, expiresAt, now) {
+    const starts = Date.parse(String(validFrom));
+    const expires = Date.parse(String(expiresAt));
+    return Number.isFinite(starts) && Number.isFinite(expires) && starts <= now && expires > now;
+}
+function validDigest(value) { return /^[a-f0-9]{64}$/.test(value); }
+function localSandboxOrigin(value) {
+    try {
+        if (!value)
+            return false;
+        const url = new URL(value);
+        return url.protocol === "http:" && url.hostname === "127.0.0.1" && Boolean(url.port) && url.pathname === "/" && !url.search && !url.hash && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
 }
 function gatewayClient(config) {
     const requestHelper = `async function actionRequest(path, init = {}) {\n  const headers = new Headers(init.headers);\n  headers.set("authorization", \`Bearer \${await token()}\`);\n  if (init.body) headers.set("content-type", "application/json");\n  const response = await fetch(\`\${baseUrl}\${path}\`, { ...init, headers });\n  const result = await response.json().catch(() => ({}));\n  if (!response.ok) throw new Error(result.error ?? \`Witnora Gateway returned HTTP \${response.status}.\`);\n  return result;\n}\n`;
     const actionMethods = `  proposeAction(proposal, idempotencyKey = proposal?.externalId) {\n    if (typeof idempotencyKey !== "string" || !idempotencyKey) throw new Error("Witnora action proposal requires an idempotency key or externalId.");\n    return actionRequest("/v1/actions", { method: "POST", body: JSON.stringify({ proposal, idempotencyKey }) });\n  },\n  getAction(actionId) {\n    if (!/^[A-Za-z0-9._:-]+$/.test(actionId)) throw new Error("Witnora actionId contains unsupported characters.");\n    return actionRequest(\`/v1/actions/\${encodeURIComponent(actionId)}\`);\n  },\n  issueExecutionGrant(actionId, grant, idempotencyKey = \`grant:\${actionId}\`) {\n    if (!/^[A-Za-z0-9._:-]+$/.test(actionId)) throw new Error("Witnora actionId contains unsupported characters.");\n    return actionRequest(\`/v1/actions/\${encodeURIComponent(actionId)}/execution-grant\`, { method: "POST", body: JSON.stringify({ grant, idempotencyKey }) });\n  },\n`;
+    const localSandboxMethod = config.runtimeWorker?.adapterId === LOCAL_SANDBOX_ADAPTER_ID && config.runtimeWorker.mandateId && config.runtimeWorker.sandboxPrincipalId
+        ? `  async proposeLocalSandboxUpdate({ resourceId, status = "UPDATED", externalId = \`runtime-sandbox-\${crypto.randomUUID()}\`, agentBuildId = "witnora-local-sandbox-task@1.0.0" }) {\n    if (!/^[A-Za-z0-9._:-]+$/.test(resourceId)) throw new Error("Local sandbox resourceId contains unsupported characters.");\n    const approvedParameters = { resourceId, status };\n    const digest = Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(agentBuildId))).toString("hex");\n    const proposal = {\n      externalId, principal: { id: "${config.runtimeWorker.sandboxPrincipalId}", version: "sandbox-v1" },\n      actionType: "UPDATE", targetSystem: "WitnoraLocalSandbox", requestedPermissions: [], sensitive: true, expectedState: approvedParameters,\n      mandateId: "${config.runtimeWorker.mandateId}", requireMandate: true,\n      executionIntent: { adapterId: "${LOCAL_SANDBOX_ADAPTER_ID}", adapterVersionConstraint: "^${LOCAL_SANDBOX_ADAPTER_VERSION}", allowedOrigins: ["${config.runtimeWorker.sandboxOrigin}"], approvedParameters, outcomePredicate: { type: "state_subset", expected: approvedParameters }, agentBuildId, agentBuildDigest: digest, allowedOperation: "UPDATE", allowedResource: \`mock-state/\${resourceId}\` },\n    };\n    return this.proposeAction(proposal, externalId);\n  },\n`
+        : "";
     return recordedGatewayClient(config)
         .replace("export const witnoraGateway = {", `${requestHelper}\nexport const witnoraGateway = {`)
-        .replace(/\n};\n$/, `\n${actionMethods}};\n`);
+        .replace(/\n};\n$/, `\n${actionMethods}${localSandboxMethod}};\n`);
+}
+async function loadProbeHostedConnection(config, projectId, server, configHome) {
+    if (config.probeConnectionName)
+        return loadConnection(config.probeConnectionName, { configHome });
+    if (!config.probeHostedCredentialHandle)
+        return undefined;
+    return { projectId, server, apiKey: await readSecretProviderHandle(config.probeHostedCredentialHandle) };
+}
+async function readSecretProviderHandle(handle) {
+    if (!credentialHandle(handle))
+        throw new Error("A valid opaque file:// credential handle is required.");
+    const url = new URL(handle);
+    if (url.protocol !== "file:")
+        throw new Error("Only file:// credential handles are supported by the localhost sandbox Runtime.");
+    const value = (await readFile(fileURLToPath(url), "utf8")).trim();
+    if (!value)
+        throw new Error("The referenced local credential is empty.");
+    return value;
+}
+async function ed25519PublicKeyPem(handle) {
+    const key = createPrivateKey(await readSecretProviderHandle(handle));
+    if (key.asymmetricKeyType !== "ed25519")
+        throw new Error("The Runtime signing-key reference must resolve to an Ed25519 private key.");
+    return createPublicKey(key).export({ type: "spki", format: "pem" }).toString();
 }
 function recordedGatewayClient(config) {
     return `import { readFile } from "node:fs/promises";\n\nconst baseUrl = "http://${config.host}:${config.port}";\nlet gatewayToken;\n\nasync function token() {\n  if (gatewayToken) return gatewayToken;\n  const secrets = JSON.parse(await readFile(new URL("./secrets.json", import.meta.url), "utf8"));\n  if (typeof secrets.gatewayToken !== "string" || secrets.gatewayToken.length < 32) {\n    throw new Error("Witnora local Gateway token is missing or invalid.");\n  }\n  gatewayToken = secrets.gatewayToken;\n  return gatewayToken;\n}\n\nasync function post(runId, operation, body) {\n  if (!/^[A-Za-z0-9._:-]+$/.test(runId)) throw new Error("Witnora runId contains unsupported characters.");\n  const response = await fetch(\`\${baseUrl}/v1/runs/\${encodeURIComponent(runId)}/\${operation}\`, {\n    method: "POST",\n    headers: { authorization: \`Bearer \${await token()}\`, "content-type": "application/json" },\n    body: JSON.stringify(body),\n  });\n  const result = await response.json().catch(() => ({}));\n  if (!response.ok) throw new Error(result.error ?? \`Witnora Gateway returned HTTP \${response.status}.\`);\n  return result;\n}\n\nexport const witnoraGateway = {\n  start(runId, metadata = {}) {\n    return post(runId, "start", { payload: metadata, idempotencyKey: "run-start" });\n  },\n  event(runId, type, metadata = {}, idempotencyKey = \`\${type}-\${crypto.randomUUID()}\`) {\n    return post(runId, "events", { type, payload: metadata, idempotencyKey });\n  },\n  complete(runId, metadata = {}) {\n    return post(runId, "complete", {\n      payload: metadata,\n      evidenceStrength: {\n        schemaVersion: "agentcert.evidence_strength.v0.1",\n        level: "recorded",\n        claims: [],\n        limitations: ["No write-credential mediation or independent outcome probe is configured."],\n      },\n      idempotencyKey: "run-complete",\n    });\n  },\n};\n`;
@@ -618,6 +1064,12 @@ async function writeExclusive(path, content, force, mode) {
     await writeFile(path, content, { encoding: "utf8", mode });
     await chmod(path, mode).catch(() => undefined);
 }
+async function atomicWrite(path, content, mode) {
+    const temporary = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    await writeFile(temporary, content, { encoding: "utf8", mode });
+    await rename(temporary, path);
+    await chmod(path, mode).catch(() => undefined);
+}
 async function exists(path) {
     try {
         await access(path);
@@ -636,14 +1088,29 @@ function gatewayPaths(directory) {
         join(directory, "README.md"),
     ];
 }
-async function gatewayHealth(baseUrl, requestFetch, requireRuntimeWorker = false) {
+async function gatewayHealth(baseUrl, requestFetch, runtimeWorker) {
     try {
         const response = await requestFetch(`${baseUrl}/healthz`, { signal: AbortSignal.timeout(800) });
         if (!response.ok)
             return undefined;
         const value = await response.json();
-        if (requireRuntimeWorker && value.actionWorker?.ready !== true)
+        if (runtimeWorker && value.actionWorker?.ready !== true)
             return undefined;
+        const processBinding = value.actionWorker?.runtimeBinding;
+        if (runtimeWorker?.probeApiKeyId && (processBinding?.configDigestSha256 !== runtimeWorker.configDigestSha256
+            || processBinding?.probeApiKeyId !== runtimeWorker.probeApiKeyId))
+            return undefined;
+        if (runtimeWorker?.adapterId === LOCAL_SANDBOX_ADAPTER_ID) {
+            const readCredential = await readSecretProviderHandle(runtimeWorker.probeTargetCredentialHandle);
+            const fixtureResponse = await requestFetch(`${runtimeWorker.sandboxOrigin}/healthz`, {
+                headers: { "x-sandbox-read-credential": readCredential }, signal: AbortSignal.timeout(800), redirect: "error",
+            });
+            if (!fixtureResponse.ok)
+                return undefined;
+            const fixture = await fixtureResponse.json();
+            if (fixture.contractSha256 !== runtimeWorker.fixtureContractSha256 || fixture.origin !== runtimeWorker.sandboxOrigin)
+                return undefined;
+        }
         return typeof value.collectorId === "string" && value.collectorId ? { collectorId: value.collectorId } : undefined;
     }
     catch {