witnora 0.13.3 → 0.13.5

package/dist/internal/control-client/durable-action-worker.js

@@ -0,0 +1,359 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { canonicalJson } from "./canonical.js";
+export class FileActionCheckpointStore {
+    directory;
+    constructor(directory) { this.directory = resolve(directory); }
+    async load(actionId) {
+        try {
+            return parseCheckpoint(await readFile(this.path(actionId), "utf8"));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return undefined;
+            throw error;
+        }
+    }
+    async save(checkpoint) {
+        const path = this.path(checkpoint.actionId);
+        await mkdir(dirname(path), { recursive: true });
+        const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        const handle = await open(temporary, "w", 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(checkpoint, null, 2)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+    }
+    async list() {
+        let names;
+        try {
+            names = await readdir(this.directory);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return [];
+            throw error;
+        }
+        const values = await Promise.all(names.filter((name) => name.endsWith(".json")).map(async (name) => parseCheckpoint(await readFile(join(this.directory, name), "utf8"))));
+        return values.sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+    }
+    async claimExecution(actionId, ownerId, claimedAt) {
+        const path = this.claimPath(actionId);
+        await mkdir(dirname(path), { recursive: true });
+        const claimId = randomUUID();
+        try {
+            const handle = await open(path, "wx", 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify({ schemaVersion: "witnora.execution_claim.v0.1", actionId, claimId, ownerId, claimedAt })}\n`, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            return { acquired: true, claimId };
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+            const existing = JSON.parse(await readFile(path, "utf8"));
+            if (typeof existing.claimId !== "string" || !existing.claimId)
+                throw new Error("Existing execution claim is invalid; refusing to dispatch.");
+            return { acquired: false, claimId: existing.claimId };
+        }
+    }
+    path(actionId) {
+        if (!/^[A-Za-z0-9._:-]+$/.test(actionId))
+            throw new Error("actionId contains unsupported characters.");
+        return join(this.directory, `${actionId}.json`);
+    }
+    claimPath(actionId) {
+        if (!/^[A-Za-z0-9._:-]+$/.test(actionId))
+            throw new Error("actionId contains unsupported characters.");
+        return join(this.directory, `${actionId}.execution-claim`);
+    }
+}
+export class DurableApprovedActionWorker {
+    options;
+    now;
+    chains = new Map();
+    timer;
+    lastHeartbeatAt;
+    lastError;
+    workerId = randomUUID();
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+        if (!options.config.adapterId || !validVersion(options.config.adapterVersion))
+            throw new Error("An exact adapter id and semantic version are required.");
+        if (!options.config.probeId || !options.config.probeCredentialHandle || options.probe.id !== options.config.probeId
+            || options.probe.credentialHandle !== options.config.probeCredentialHandle || options.probe.readOnly !== true)
+            throw new Error("An exact separate read-only probe credential is required.");
+        if (options.config.adapterId === options.config.probeId)
+            throw new Error("The adapter and outcome probe must be separate.");
+        if (options.runtime.reconcileReadOnly !== true)
+            throw new Error("Unknown writes require an explicitly read-only reconciliation path.");
+        this.lastHeartbeatAt = this.now().toISOString();
+    }
+    async track(input) {
+        assertProposal(input.proposal);
+        const existing = await this.options.store.load(input.actionId);
+        const digest = sha256(input.proposal);
+        if (existing) {
+            if (existing.proposalSha256 !== digest)
+                throw new Error("Action id was already tracked with a different proposal.");
+            return existing;
+        }
+        const checkpoint = {
+            schemaVersion: "witnora.durable_action_checkpoint.v0.1", actionId: input.actionId, phase: "TRACKED",
+            proposal: structuredClone(input.proposal), proposalSha256: digest, updatedAt: this.now().toISOString(),
+        };
+        await this.options.store.save(checkpoint);
+        return checkpoint;
+    }
+    tick(actionId) {
+        const previous = this.chains.get(actionId) ?? Promise.resolve(undefined);
+        const next = previous.catch(() => undefined).then(() => this.tickOnce(actionId));
+        this.chains.set(actionId, next);
+        return next.finally(() => { if (this.chains.get(actionId) === next)
+            this.chains.delete(actionId); });
+    }
+    start() {
+        if (this.timer)
+            return;
+        const poll = async () => {
+            this.lastHeartbeatAt = this.now().toISOString();
+            const checkpoints = await this.options.store.list();
+            let cycleError;
+            await Promise.all(checkpoints.filter((item) => !terminal(item.phase)).map((item) => this.tick(item.actionId).catch((error) => { cycleError = message(error); })));
+            this.lastError = cycleError;
+        };
+        void poll().catch((error) => { this.lastError = message(error); });
+        this.timer = setInterval(() => void poll().catch((error) => { this.lastError = message(error); }), this.options.config.pollIntervalMs ?? 2_000);
+        this.timer.unref();
+    }
+    stop() { if (this.timer)
+        clearInterval(this.timer); this.timer = undefined; }
+    async status() {
+        const checkpoints = await this.options.store.list();
+        return {
+            schemaVersion: "witnora.durable_action_worker_status.v0.1",
+            ready: Boolean(this.timer) && !this.lastError,
+            trackedActionCount: checkpoints.length,
+            pendingActionCount: checkpoints.filter((item) => !terminal(item.phase)).length,
+            unknownResultCount: checkpoints.filter((item) => item.phase === "UNKNOWN_RESULT").length,
+            lastHeartbeatAt: this.lastHeartbeatAt,
+            ...(this.lastError ? { lastError: this.lastError } : {}),
+        };
+    }
+    async tickOnce(actionId) {
+        let checkpoint = await this.options.store.load(actionId);
+        if (!checkpoint)
+            throw new Error(`Action ${actionId} is not tracked.`);
+        if (terminal(checkpoint.phase))
+            return checkpoint;
+        const action = await this.options.hosted.getAction(actionId);
+        if (!exactActionMatches(action, actionId, checkpoint.proposal, this.options.config.adapterId, this.options.config.adapterVersion)) {
+            return this.persist(checkpoint, "BLOCKED", { limitation: "Hosted action no longer matches the exact locally configured action, adapter, or build binding." });
+        }
+        if ((checkpoint.phase === "EXECUTION_STARTED" || checkpoint.phase === "UNKNOWN_RESULT") && checkpoint.grant) {
+            if (!exactGrantMatches(checkpoint.grant, actionId, checkpoint.proposal, this.options.config.runtimeIdentityId)) {
+                return this.persist(checkpoint, "BLOCKED", { limitation: "Hosted grant does not match the exact approved local action binding." });
+            }
+            const reconciled = await this.options.runtime.reconcile({ action, proposal: checkpoint.proposal, grant: checkpoint.grant });
+            if (!reconciled)
+                return this.persist(checkpoint, "UNKNOWN_RESULT", { limitation: "Write result is unknown. The worker will only use read-only reconciliation and will never redispatch this grant." });
+            checkpoint = await this.persist(checkpoint, "EXECUTED", { execution: reconciled, limitation: undefined });
+        }
+        if (!checkpoint.execution) {
+            if (action.status === "REJECTED" || action.status === "DENIED")
+                return this.persist(checkpoint, "DENIED");
+            if (action.status === "APPROVAL_EXPIRED" || action.status === "GRANT_EXPIRED" || (action.status === "APPROVED" && expired(action.approvalExpiresAt, this.now())))
+                return this.persist(checkpoint, "EXPIRED");
+            if (action.status === "PENDING_APPROVAL")
+                return this.persist(checkpoint, "WAITING_APPROVAL");
+            if (action.status !== "APPROVED" && action.status !== "ALLOWED") {
+                return this.persist(checkpoint, "BLOCKED", { limitation: `Action status ${action.status} is not executable.` });
+            }
+        }
+        if (!checkpoint.grant && !checkpoint.execution) {
+            const intent = checkpoint.proposal.executionIntent;
+            const grant = await this.options.hosted.issueExecutionGrant(actionId, {
+                runtimeIdentityId: this.options.config.runtimeIdentityId,
+                adapterId: intent.adapterId,
+                adapterVersionConstraint: intent.adapterVersionConstraint,
+                allowedOrigins: intent.allowedOrigins,
+                allowedOperation: intent.allowedOperation,
+                allowedResource: intent.allowedResource,
+                approvedParameters: intent.approvedParameters,
+                outcomePredicate: intent.outcomePredicate,
+                agentBuildId: intent.agentBuildId,
+                agentBuildDigest: intent.agentBuildDigest,
+                ttlSeconds: this.options.config.grantTtlSeconds ?? 120,
+            }, `durable-worker:grant:${actionId}`);
+            checkpoint = await this.persist(checkpoint, "GRANT_ISSUED", { grant });
+        }
+        const grant = checkpoint.grant;
+        if (!grant)
+            return this.persist(checkpoint, "BLOCKED", { limitation: "A durable execution result exists without its bound Hosted grant." });
+        const grantPayload = grant.grant.payload ?? {};
+        if (!exactGrantMatches(grant, actionId, checkpoint.proposal, this.options.config.runtimeIdentityId)) {
+            return this.persist(checkpoint, "BLOCKED", { limitation: "Hosted grant does not match the exact approved local action binding." });
+        }
+        if (!checkpoint.execution) {
+            if (grant.status !== "ISSUED" || expired(stringValue(grantPayload.expiresAt), this.now()))
+                return this.persist(checkpoint, "EXPIRED");
+            const claim = await this.options.store.claimExecution(actionId, this.workerId, this.now().toISOString());
+            if (!claim.acquired) {
+                checkpoint = await this.persist(checkpoint, "UNKNOWN_RESULT", {
+                    executionClaimId: claim.claimId,
+                    limitation: "Another Gateway process owns the durable execution claim. This worker will only reconcile and will never dispatch.",
+                });
+                const reconciled = await this.options.runtime.reconcile({ action, proposal: checkpoint.proposal, grant });
+                if (!reconciled)
+                    return checkpoint;
+                checkpoint = await this.persist(checkpoint, "EXECUTED", { execution: reconciled, limitation: undefined });
+            }
+            else {
+                checkpoint = await this.persist(checkpoint, "EXECUTION_STARTED", { executionClaimId: claim.claimId });
+            }
+        }
+        if (!checkpoint.execution && checkpoint.phase === "EXECUTION_STARTED") {
+            if (!checkpoint.hostedReservation) {
+                const reservation = await this.options.runtime.prepareClaim({ action, proposal: checkpoint.proposal, grant });
+                if (!exactHostedReservation(reservation, actionId, grant.id))
+                    return this.persist(checkpoint, "BLOCKED", { limitation: "Runtime claim is not bound to the exact action, grant, and execution session." });
+                const claimed = await this.options.hosted.claimExecutionGrant(grant.id, reservation.claim, `durable-worker:claim:${grant.id}`);
+                if (!claimed.acquired) {
+                    checkpoint = await this.persist(checkpoint, "UNKNOWN_RESULT", {
+                        limitation: "Hosted already has an execution reservation for this grant. This worker will only reconcile and will never dispatch.",
+                    });
+                    const reconciled = await this.options.runtime.reconcile({ action, proposal: checkpoint.proposal, grant });
+                    if (!reconciled)
+                        return checkpoint;
+                    checkpoint = await this.persist(checkpoint, "EXECUTED", { execution: reconciled, limitation: undefined });
+                }
+                else {
+                    checkpoint = await this.persist(checkpoint, "EXECUTION_STARTED", { hostedReservation: reservation });
+                }
+            }
+        }
+        if (!checkpoint.execution && checkpoint.phase === "EXECUTION_STARTED" && checkpoint.hostedReservation) {
+            try {
+                const execution = await this.options.runtime.execute({ action, proposal: checkpoint.proposal, grant, hostedReservation: checkpoint.hostedReservation });
+                checkpoint = await this.persist(checkpoint, "EXECUTED", { execution });
+            }
+            catch {
+                checkpoint = await this.persist(checkpoint, "UNKNOWN_RESULT", { limitation: "Write result is unknown. The worker will only use read-only reconciliation and will never redispatch this grant." });
+                const reconciled = await this.options.runtime.reconcile({ action, proposal: checkpoint.proposal, grant });
+                if (!reconciled)
+                    return checkpoint;
+                checkpoint = await this.persist(checkpoint, "EXECUTED", { execution: reconciled, limitation: undefined });
+            }
+        }
+        if (!checkpoint.observation) {
+            const observation = await this.options.probe.observe({ action, proposal: checkpoint.proposal, grant, execution: checkpoint.execution });
+            if (!observation.observationSource || observation.observationSource !== this.options.config.probeId)
+                throw new Error("Outcome observation did not come from the exact configured probe.");
+            checkpoint = await this.persist(checkpoint, "PROBED", { observation });
+        }
+        const verified = await this.options.hosted.verifyAction(actionId, {
+            ...checkpoint.observation,
+            executionGrantId: grant.id,
+            executionSessionId: checkpoint.execution.executionSessionId,
+        }, `durable-worker:verify:${actionId}:${checkpoint.execution.executionSessionId}`);
+        if (verified.status !== "VERIFIED" || verified.verificationSuccess !== true)
+            throw new Error("Hosted outcome verification did not establish the expected result.");
+        const receipts = await this.options.hosted.listActionReceipts(actionId);
+        const signed = receipts.find((item) => Array.isArray(item.receipt?.signatureSet) && item.receipt.signatureSet.length > 0);
+        if (!signed)
+            throw new Error("Hosted did not automatically issue a signed action receipt.");
+        return this.persist(checkpoint, "COMPLETED", { receiptId: signed.id });
+    }
+    async persist(checkpoint, phase, patch = {}) {
+        const next = { ...checkpoint, ...patch, phase, updatedAt: this.now().toISOString() };
+        if (patch.limitation === undefined && "limitation" in patch)
+            delete next.limitation;
+        await this.options.store.save(next);
+        return next;
+    }
+}
+function exactActionMatches(action, actionId, proposal, adapterId, adapterVersion) {
+    const approved = action.assuranceContext?.executionIntent;
+    const proposed = proposal.executionIntent;
+    return action.id === actionId && action.externalId === proposal.externalId && action.actionType === proposal.actionType
+        && action.targetSystem === proposal.targetSystem && sha256(action.expectedState ?? {}) === sha256(proposal.expectedState ?? {})
+        && proposed.adapterId === adapterId && runtimeAdapterVersionSatisfies(adapterVersion, proposed.adapterVersionConstraint)
+        && approved?.adapterId === proposed.adapterId && approved.adapterVersionConstraint === proposed.adapterVersionConstraint
+        && canonicalJson(approved.allowedOrigins) === canonicalJson(proposed.allowedOrigins)
+        && approved.allowedOperation === proposed.allowedOperation && approved.allowedResource === proposed.allowedResource
+        && approved.approvedParametersDigest === sha256(proposed.approvedParameters)
+        && approved.outcomePredicateDigest === sha256(proposed.outcomePredicate)
+        && approved.agentBuildId === proposed.agentBuildId && approved.agentBuildDigest === proposed.agentBuildDigest;
+}
+function exactGrantMatches(grant, actionId, proposal, runtimeIdentityId) {
+    const payload = grant.grant.payload ?? {};
+    const intent = proposal.executionIntent;
+    return payload.executionGrantId === grant.id && payload.actionId === actionId && payload.adapterId === intent.adapterId
+        && payload.adapterVersionConstraint === intent.adapterVersionConstraint && payload.expectedRuntimeIdentityId === runtimeIdentityId
+        && canonicalJson(payload.allowedOrigins) === canonicalJson(intent.allowedOrigins)
+        && payload.allowedOperation === intent.allowedOperation && payload.allowedResource === intent.allowedResource
+        && payload.agentBuildId === intent.agentBuildId && payload.agentBuildDigest === intent.agentBuildDigest
+        && payload.parametersDigest === sha256(intent.approvedParameters) && payload.outcomePredicateDigest === sha256(intent.outcomePredicate);
+}
+function exactHostedReservation(reservation, actionId, executionGrantId) {
+    if (!reservation || typeof reservation !== "object" || typeof reservation.executionSessionId !== "string"
+        || !reservation.executionSessionId || !reservation.claim || typeof reservation.claim !== "object" || Array.isArray(reservation.claim))
+        return false;
+    const payload = reservation.claim.payload;
+    return Boolean(payload && typeof payload === "object" && !Array.isArray(payload)
+        && payload.actionId === actionId
+        && payload.executionGrantId === executionGrantId
+        && payload.executionSessionId === reservation.executionSessionId);
+}
+function parseCheckpoint(raw) {
+    const value = JSON.parse(raw);
+    if (value.schemaVersion !== "witnora.durable_action_checkpoint.v0.1" || !value.actionId || !value.phase || !value.proposal || !value.proposalSha256 || !value.updatedAt) {
+        throw new Error("Durable action checkpoint is invalid.");
+    }
+    return value;
+}
+function assertProposal(value) {
+    const intent = value?.executionIntent;
+    if (!value?.externalId || !value.actionType || !value.targetSystem || !intent?.adapterId || !intent.adapterVersionConstraint
+        || !Array.isArray(intent.allowedOrigins) || !intent.allowedOrigins.length || !intent.allowedOperation || !intent.allowedResource
+        || !intent.approvedParameters || typeof intent.approvedParameters !== "object" || !intent.outcomePredicate || typeof intent.outcomePredicate !== "object"
+        || !intent.agentBuildId || !/^[a-f0-9]{64}$/.test(intent.agentBuildDigest)) {
+        throw new Error("Tracked action is missing an exact execution intent.");
+    }
+}
+function sha256(value) { return createHash("sha256").update(canonicalJson(value)).digest("hex"); }
+function expired(value, now) { return !value || !Number.isFinite(Date.parse(value)) || Date.parse(value) <= now.getTime(); }
+function stringValue(value) { return typeof value === "string" ? value : undefined; }
+function validVersion(value) { return /^v?\d+\.\d+\.\d+$/.test(value); }
+export function runtimeAdapterVersionSatisfies(version, constraint) {
+    const parsed = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    const exact = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(constraint);
+    if (!parsed)
+        return false;
+    if (exact)
+        return parsed.slice(1).join(".") === exact.slice(1).join(".");
+    const compatible = /^\^v?(\d+)\.(\d+)\.(\d+)$/.exec(constraint);
+    if (!compatible)
+        return false;
+    const [major, minor, patch] = parsed.slice(1).map(Number);
+    const [requiredMajor, requiredMinor, requiredPatch] = compatible.slice(1).map(Number);
+    if (requiredMajor > 0)
+        return major === requiredMajor && (minor > requiredMinor || (minor === requiredMinor && patch >= requiredPatch));
+    if (requiredMinor > 0)
+        return major === 0 && minor === requiredMinor && patch >= requiredPatch;
+    return major === 0 && minor === 0 && patch === requiredPatch;
+}
+function terminal(phase) { return phase === "DENIED" || phase === "EXPIRED" || phase === "BLOCKED" || phase === "COMPLETED"; }
+function isMissing(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }
+function isAlreadyExists(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "EEXIST"); }
+function message(error) { return error instanceof Error ? error.message : String(error); }

package/dist/internal/control-client/remote-collector.d.ts

@@ -38,6 +38,25 @@ export interface RemoteCollectorAck {
     alerts: Array<Record<string, unknown>>;
     run: Record<string, unknown>;
 }
+export interface RuntimeReadinessBinding {
+    collectorId: string;
+    sourceKeyId: string;
+    configDigestSha256: string;
+    runtimeIdentity: {
+        id: string;
+    };
+    mandateDigestSha256: string;
+    adapterDigestSha256: string;
+    probeDigestSha256: string;
+    fixtureContractDigestSha256: string;
+}
+export interface CollectorRuntimeHeartbeat {
+    classification: "LOCAL_SANDBOX_ONLY";
+    binding: RuntimeReadinessBinding;
+    workerReady: boolean;
+    fixtureReady: boolean;
+    lastError?: string;
+}
 export interface RemoteCollectorClientOptions {
     baseUrl: string;
     projectId: string;
@@ -85,6 +104,7 @@ export declare class RemoteCollectorClient {
         pendingRecordCount: number;
         lastAckSequence?: number;
         occurredAt?: string;
+        runtime?: CollectorRuntimeHeartbeat;
     }): Promise<Record<string, unknown>>;
     reconcile(runId: string, receipt: Record<string, unknown>): Promise<Record<string, unknown>>;
     proposeAction(proposal: Record<string, unknown>, idempotencyKey: string): Promise<Record<string, unknown>>;

package/dist/internal/control-client/remote-collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-collector.d.ts","sourceRoot":"","sources":["../../../../agentcert-sdk/src/remote-collector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remote-collector.d.ts","sourceRoot":"","sources":["../../../../agentcert-sdk/src/remote-collector.ts"],"names":[],"mappings":"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"}

package/dist/internal/control-client/remote-collector.js

@@ -104,6 +104,7 @@ export class RemoteCollectorClient {
             occurredAt: input.occurredAt ?? new Date().toISOString(),
             pendingRecordCount: input.pendingRecordCount,
             lastAckSequence: input.lastAckSequence,
+            runtime: input.runtime,
         };
         const payloadSha256 = sha256(canonicalJson(payload));
         return this.json("collector-heartbeats", {

package/dist/onboard.js

@@ -7,7 +7,9 @@ import { verifyControlPlaneConnection } from "./control-plane.js";
 import { inferPrivateCapabilities, runPrivateCapabilityDiscovery } from "./private-discovery.js";
 import { parseAgentTemplate, starterAdapter, starterProfile, starterTripwireConfig } from "./onboarding-templates.js";
 import { writeTryEvidence } from "./try.js";
-import { doctorCustomerGateway, initializeCustomerGateway, inspectCustomerGatewayFiles, startManagedCustomerGateway, stopManagedCustomerGateway, } from "./gateway.js";
+import { doctorCustomerGateway, initializeCustomerGateway, inspectLocalRuntimeBinding, inspectCustomerGatewayFiles, startManagedCustomerGateway, stopManagedCustomerGateway, upgradeCustomerGatewayRuntime, RuntimeSetupNotReadyError, } from "./gateway.js";
+import { discoverRuntimeReferences, planRuntimeSandboxModules } from "./runtime-sandbox-kit.js";
+import { automaticRuntimeReferencesUsable, bootstrapLocalRuntime, verifyAutomaticRuntimeProbe } from "./runtime-bootstrap.js";
 export async function runOnboard(options) {
     const requestFetch = options.fetch ?? fetch;
     const output = options.output ?? ((message) => process.stdout.write(message));
@@ -36,6 +38,44 @@ export async function runOnboard(options) {
     if (!setupPlan || !setupPlan.authorizedOperations.some((item) => item.kind === "authorize_install")) {
         throw new Error("Confirm the Setup Plan and authorize installation in the Witnora Workspace before running onboard.");
     }
+    let localRuntime = await discoverRuntimeReferences({
+        repository: repositoryPath, configHome: options.configHome, projectId: token.projectId, server, env: options.env ?? process.env,
+    });
+    let runtimeLimitation = localRuntime.limitation;
+    let runtimeBootstrapRequired = !localRuntime.references;
+    if (localRuntime.references?.probeApiKeyId) {
+        try {
+            if (!await automaticRuntimeReferencesUsable(localRuntime.references))
+                throw new Error("local bootstrap material invalid");
+            await verifyAutomaticRuntimeProbe({ references: localRuntime.references, projectId: token.projectId, server, fetch: requestFetch });
+        }
+        catch {
+            runtimeBootstrapRequired = true;
+        }
+    }
+    if (runtimeBootstrapRequired) {
+        try {
+            const references = localRuntime.references;
+            const modules = references?.sandboxOrigin && references.adapterDigestSha256 && references.probeDigestSha256 && references.fixtureContractDigestSha256
+                ? { sandboxOrigin: references.sandboxOrigin, adapterDigestSha256: references.adapterDigestSha256, probeDigestSha256: references.probeDigestSha256, fixtureContractDigestSha256: references.fixtureContractDigestSha256 }
+                : await planRuntimeSandboxModules();
+            const bootstrap = await bootstrapLocalRuntime({
+                projectId: token.projectId,
+                planId: setupPlan.id,
+                server,
+                apiKey: token.apiKey,
+                configHome: options.configHome,
+                fetch: requestFetch,
+                modules,
+            });
+            localRuntime = { references: bootstrap.references };
+            runtimeLimitation = undefined;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : "Unknown Runtime bootstrap error.";
+            runtimeLimitation = `Hosted Runtime bootstrap did not complete: ${detail.slice(0, 500)} The existing Gateway was preserved and setup remains RECORDED_ONLY.`;
+        }
+    }
     const attemptId = `install-${Date.now()}-${randomSuffix()}`;
     const generatedFiles = [];
     const gatewayLifecycle = options.gatewayLifecycle ?? {
@@ -44,6 +84,7 @@ export async function runOnboard(options) {
     };
     let gatewayMigration;
     let managedGateway;
+    let runtimeUpgrade;
     await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, { status: "installing", attemptId });
     try {
         generatedFiles.push(...await generateRepositoryConfig(repositoryPath, repository.template, repository.name));
@@ -84,17 +125,49 @@ export async function runOnboard(options) {
             throw new Error(`Existing Gateway setup is incomplete. Preserve the existing files and repair or remove the partial setup in Advanced mode. Missing: ${gatewayState.missing.map((path) => basename(path)).join(", ")}.`);
         }
         if (gatewayState.status === "absent") {
-            const gateway = await initializeCustomerGateway({
-                projectId: token.projectId, server, repository: repositoryPath, authorization: token,
-                fetch: requestFetch, configHome: options.configHome, output,
-            });
+            let gateway;
+            try {
+                gateway = await initializeCustomerGateway({
+                    projectId: token.projectId, server, repository: repositoryPath, authorization: token,
+                    runtimeReferences: localRuntime.references,
+                    fetch: requestFetch, configHome: options.configHome, output,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof RuntimeSetupNotReadyError) || !localRuntime.references)
+                    throw error;
+                runtimeLimitation = `Local sandbox Runtime references were found but did not establish readiness: ${error.message}`;
+                gateway = await initializeCustomerGateway({ projectId: token.projectId, server, repository: repositoryPath, authorization: token, fetch: requestFetch, configHome: options.configHome, output });
+            }
             generatedFiles.push(...gateway.generatedFiles);
         }
         else {
             const binding = await inspectGatewayBinding(gatewayState.directory, token.projectId, server);
             if (binding.matches) {
                 await saveConnection(binding.connectionName, { server, projectId: token.projectId, apiKey: token.apiKey }, { configHome: options.configHome });
-                output("\nExisting customer-owned Gateway matches this project; verifying and reusing it.\n");
+                if (localRuntime.references) {
+                    try {
+                        runtimeUpgrade = await upgradeCustomerGatewayRuntime({ repository: repositoryPath, authorization: token, runtimeReferences: localRuntime.references, configHome: options.configHome, fetch: requestFetch });
+                        if (runtimeUpgrade.changed) {
+                            const stopped = await gatewayLifecycle.stop({ repository: repositoryPath, configHome: options.configHome, fetch: requestFetch });
+                            if (stopped.state !== "STOPPED" || stopped.healthy)
+                                throw new Error("The prior managed Gateway process did not stop before Runtime generation replacement.");
+                        }
+                        runtimeLimitation = undefined;
+                        output(runtimeUpgrade.changed
+                            ? "\nExisting customer-owned Gateway matches this project; safely replaced its generated Runtime generation, stopped the prior process, and preserved a local backup.\n"
+                            : "\nExisting customer-owned Gateway already has the exact current Runtime generation; verifying and reusing it.\n");
+                    }
+                    catch (error) {
+                        if (!(error instanceof RuntimeSetupNotReadyError))
+                            throw error;
+                        runtimeLimitation = `Local sandbox Runtime references were found but did not establish readiness: ${error.message}`;
+                        output("\nExisting customer-owned Gateway remains RECORDED_ONLY because its Runtime references did not pass readiness checks.\n");
+                    }
+                }
+                else {
+                    output("\nExisting customer-owned Gateway matches this project; verifying and reusing it.\n");
+                }
             }
             else {
                 await assertGatewayStopped(requestFetch, binding.host, binding.port, binding.projectId, token.projectId);
@@ -102,12 +175,14 @@ export async function runOnboard(options) {
                 output(`\nExisting Gateway belongs to project ${binding.projectId}; archived it at ${gatewayMigration.archiveDirectory}.\n`);
                 const gateway = await initializeCustomerGateway({
                     projectId: token.projectId, server, repository: repositoryPath, authorization: token,
+                    runtimeReferences: localRuntime.references,
                     fetch: requestFetch, configHome: options.configHome, output,
                 });
                 generatedFiles.push(...gateway.generatedFiles);
             }
         }
-        generatedFiles.push(...await generateAutopilotFiles(repositoryPath, repository.name));
+        const runtimeConfigured = await gatewayHasRuntimeWorker(repositoryPath);
+        generatedFiles.push(...await generateAutopilotFiles(repositoryPath, repository.name, runtimeConfigured));
         managedGateway = await gatewayLifecycle.start({
             repository: repositoryPath,
             configHome: options.configHome,
@@ -117,10 +192,14 @@ export async function runOnboard(options) {
         if (!managedGateway.healthy)
             throw new Error(managedGateway.detail);
         const doctor = await doctorCustomerGateway({ repository: repositoryPath, configHome: options.configHome, fetch: requestFetch });
-        if (doctor.overall !== "READY_TO_RECORD")
+        if (doctor.overall !== "READY_TO_RECORD" && doctor.overall !== "READY_FOR_RUNTIME")
             throw new Error(doctor.checks.filter((check) => check.status === "FAIL").map((check) => check.message).join(" "));
+        const runtimeBinding = doctor.overall === "READY_FOR_RUNTIME" ? await inspectLocalRuntimeBinding({ repository: repositoryPath }).catch(() => undefined) : undefined;
+        const runtimeReadiness = doctor.overall === "READY_FOR_RUNTIME" && runtimeBinding
+            ? { state: "LOCAL_SANDBOX_READY", checkedAt: new Date().toISOString(), limitations: [] }
+            : { state: "RECORDED_ONLY", checkedAt: new Date().toISOString(), limitations: [runtimeLimitation ?? "The local sandbox Runtime worker has not established exact adapter, probe, source-key, identity, mandate, and readiness bindings."] };
         await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
-            status: "verified", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles),
+            status: "verified", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles), runtimeReadiness, ...(runtimeBinding ? { runtimeBinding } : {}),
         });
         output(`\nWitnora Setup Autopilot completed for ${repository.name}.\n`);
         output(`Project: ${token.projectId}\nTemplate: ${repository.template} (${repository.kind})\n`);
@@ -128,11 +207,14 @@ export async function runOnboard(options) {
         output(`Private discovery: ${discovery.capabilityCount} capability group(s); ${discovery.unknownCapabilityCount} pending confirmation.\n`);
         output("Installed: customer-owned Gateway, default-deny policy, independent-probe contract, review contract, and PR/release/nightly CI.\n");
         output(`Gateway: ${managedGateway.state} at ${managedGateway.baseUrl}${managedGateway.pid ? ` (process ${managedGateway.pid})` : ""}.\n`);
+        output(runtimeReadiness.state === "LOCAL_SANDBOX_READY"
+            ? "Runtime: LOCAL_SANDBOX_READY. This proves only the generated localhost sandbox loop is ready; it does not establish coverage, CURRENT, or a verified customer outcome.\n"
+            : `Runtime: RECORDED_ONLY. ${runtimeReadiness.limitations[0]}\n`);
         output("The self-test remains isolated. The Gateway is ready in the background; run the agent normally. The first source-signed, server-reconciled Gateway run completes onboarding.\n");
         return { projectId: token.projectId, connectionName: token.connectionName, credentialsPath, template: repository.template,
             repositoryKind: repository.kind, generatedFiles, receiptPath, discovery, setupPlanId: setupPlan.id,
             gatewayDirectory: join(repositoryPath, ".witnora", "gateway"), gatewayArchiveDirectory: gatewayMigration?.archiveDirectory,
-            gateway: managedGateway };
+            gateway: managedGateway, runtimeReadiness };
     }
     catch (error) {
         const diagnosis = error instanceof Error ? error.message : String(error);
@@ -140,6 +222,7 @@ export async function runOnboard(options) {
             await gatewayLifecycle.stop({ repository: repositoryPath, configHome: options.configHome, fetch: requestFetch }).catch(() => undefined);
         }
         await rollbackGeneratedFiles(generatedFiles);
+        await runtimeUpgrade?.rollback().catch(() => undefined);
         if (gatewayMigration)
             await restoreGateway(gatewayMigration);
         await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
@@ -199,10 +282,10 @@ async function restoreGateway(migration) {
 function safePathSegment(value) {
     return (value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-|-$/g, "") || "unknown-project").slice(0, 80);
 }
-async function generateAutopilotFiles(repositoryPath, subject) {
+async function generateAutopilotFiles(repositoryPath, subject, runtimeConfigured) {
     const files = new Map([
         [".witnora/setup/policy.json", `${JSON.stringify({ schemaVersion: "witnora.setup_policy.v0.1", subject, unknownCapabilities: "pending_confirmation", defaultDecision: "deny", environment: "sandbox" }, null, 2)}\n`],
-        [".witnora/setup/outcome-probe.json", `${JSON.stringify({ schemaVersion: "witnora.outcome_probe_contract.v0.1", mode: "independent_read_only", credentialEnv: "WITNORA_OUTCOME_PROBE_CREDENTIAL", status: "awaiting_customer_secret", uploadsCredential: false }, null, 2)}\n`],
+        [".witnora/setup/outcome-probe.json", `${JSON.stringify({ schemaVersion: "witnora.outcome_probe_contract.v0.1", mode: "independent_read_only", status: runtimeConfigured ? "configured" : "awaiting_runtime_bootstrap", uploadsCredential: false }, null, 2)}\n`],
         [".witnora/setup/review.json", `${JSON.stringify({ schemaVersion: "witnora.review_contract.v0.1", independentReviewRequired: true, syntheticEvidenceEligible: false }, null, 2)}\n`],
         [".github/workflows/witnora-assurance.yml", continuousAssuranceWorkflow()],
     ]);
@@ -217,6 +300,10 @@ async function generateAutopilotFiles(repositoryPath, subject) {
     }
     return written;
 }
+async function gatewayHasRuntimeWorker(repositoryPath) {
+    const config = await optionalJson(join(repositoryPath, ".witnora", "gateway", "gateway.json"));
+    return Boolean(config?.runtimeWorker && typeof config.runtimeWorker === "object" && !Array.isArray(config.runtimeWorker));
+}
 function continuousAssuranceWorkflow() {
     return `name: Witnora assurance\non:\n  pull_request:\n  push:\n    tags: [\"v*\"]\n  schedule:\n    - cron: \"17 3 * * *\"\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  assurance:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 22\n      - run: npx witnora@latest release-gate --config witnora.config.json --strict\n`;
 }