witnora 0.12.1 → 0.13.1

package/README.md

@@ -13,21 +13,22 @@ outcome. It writes portable reports and accumulates a local failure corpus.
 
 ## 5-minute hosted path
 
-Create a Hosted project. The Setup Wizard pre-fills a metadata-only plan and
-asks for two decisions: **Confirm plan** and **Authorize install**. Then open a
-terminal in the agent repository and run the one command shown by Witnora:
+Create a Hosted project. The Setup Wizard pre-fills a metadata-only plan. Open
+a terminal in the Agent repository and run the one command shown by Witnora:
 
 ```bash
 npx witnora@latest onboard --project your-project-id
 ```
 
-The browser approval creates one restricted project credential, then the CLI
-saves it outside the repository, detects capability groups, and installs only
-missing Gateway, outcome-probe, CI, policy, review, configuration, and boundary
-files. It verifies each component and reports progress to Hosted. A failed
-attempt removes only files created by that attempt. The onboarding receipt is
-synthetic: it cannot create a run, evidence object, release decision, or
-`CURRENT` assurance.
+One browser **Approve setup** action authorizes the bounded plan and one
+reversible installation. The CLI saves a restricted credential outside the
+repository, detects capability groups, installs only missing Gateway,
+outcome-probe, CI, policy, review, configuration, and boundary files, and
+starts the customer-owned Gateway in the background. It health-checks each
+component and reports progress to Hosted. A failed attempt stops only the
+Gateway process it started and removes only files created by that attempt. The
+onboarding receipt is synthetic: it cannot create a run, evidence object,
+release decision, or `CURRENT` assurance.
 
 Onboarding also performs the default private capability discovery locally. It
 does not read source-file contents or upload source code, prompt text,
@@ -45,11 +46,15 @@ explicit GitHub authorization and is never enabled implicitly.
 
 ### Customer-owned Gateway
 
-The default Setup Wizard installs a durable customer-owned Gateway beside the
-Agent automatically. Start it, then run the Agent's normal sandbox workflow:
+The default Setup Wizard installs and starts a customer-owned Gateway beside
+the Agent automatically. Run the Agent's normal sandbox workflow. Routine
+Gateway operations are available without keeping another terminal open:
 
 ```bash
-npx witnora@latest gateway run
+npx witnora@latest gateway status
+npx witnora@latest gateway logs
+npx witnora@latest gateway restart
+npx witnora@latest gateway stop
 ```
 
 Initialization writes a reusable `.witnora/gateway/client.mjs`. Import its
@@ -69,8 +74,8 @@ read-only probe checks the target state.
 
 Enterprises that require self-hosted or manual component control can use the
 individual `gateway init`, `gateway doctor`, policy, probe, CI, and review
-commands under Hosted **Advanced**. They are not part of the default customer
-journey.
+commands under Hosted **Advanced**. `gateway run` remains available there for
+foreground debugging. They are not part of the default customer journey.
 
 After the connection self-test, Hosted shows one template-specific next step.
 Place the generated Gateway client at one meaningful sandbox boundary and run

package/dist/cli.js

@@ -37,8 +37,9 @@ import { importGenericEval, renderGenericEvalReport } from "./generic-eval.js";
 import { runDesignPartnerCommand } from "./design-partner-v02.js";
 import { runOnboard } from "./onboard.js";
 import { inspectRepository } from "./onboard.js";
+import { renderReleaseEvaluation, runReleaseEvaluation } from "./release-evaluation.js";
 import { runPrivateCapabilityDiscovery } from "./private-discovery.js";
-import { doctorCustomerGateway, initializeCustomerGateway, renderGatewayDoctor, runCustomerGateway } from "./gateway.js";
+import { doctorCustomerGateway, initializeCustomerGateway, readManagedCustomerGatewayLogs, renderGatewayDoctor, renderManagedGatewayStatus, restartManagedCustomerGateway, runCustomerGateway, startManagedCustomerGateway, statusManagedCustomerGateway, stopManagedCustomerGateway, } from "./gateway.js";
 import { verifyEvidencePacketV02 } from "./evidence-v02.js";
 process.on("uncaughtException", reportFatalError);
 process.on("unhandledRejection", reportFatalError);
@@ -158,6 +159,29 @@ else if (command === "onboard") {
         openBrowser: readBoolFlag("--no-browser") ? async () => { } : undefined,
     });
 }
+else if (command === "release") {
+    const action = process.argv[3] ?? "help";
+    if (action !== "evaluate")
+        throw new Error("Use witnora release evaluate --case <assurance-case-id>.");
+    const assuranceCaseId = readFlag("--case");
+    if (!assuranceCaseId)
+        throw new Error("--case <assurance-case-id> is required.");
+    const connection = await resolveConnection({
+        name: readFlag("--connection"),
+        server: readFlag("--server"),
+        projectId: readFlag("--project"),
+        apiKey: readFlag("--api-key"),
+    });
+    const result = await runReleaseEvaluation({
+        connection,
+        assuranceCaseId,
+        repository: readFlag("--repo") ?? process.cwd(),
+        outDir: readFlag("--out"),
+    });
+    process.stdout.write(renderReleaseEvaluation(result));
+    if (!result.passed)
+        process.exitCode = 1;
+}
 else if (command === "gateway") {
     const action = process.argv[3] ?? "help";
     if (action === "init") {
@@ -180,11 +204,35 @@ else if (command === "gateway") {
         if (result.overall !== "READY_TO_RECORD")
             process.exitCode = 1;
     }
+    else if (action === "start") {
+        const result = await startManagedCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
+        process.stdout.write(readBoolFlag("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderManagedGatewayStatus(result));
+    }
+    else if (action === "status") {
+        const result = await statusManagedCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
+        process.stdout.write(readBoolFlag("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderManagedGatewayStatus(result));
+        if (!result.healthy)
+            process.exitCode = 1;
+    }
+    else if (action === "logs") {
+        const lines = Number(readFlag("--lines") ?? 100);
+        if (!Number.isSafeInteger(lines) || lines < 1 || lines > 10_000)
+            throw new Error("--lines must be an integer between 1 and 10000.");
+        process.stdout.write(`${await readManagedCustomerGatewayLogs({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir"), lines })}\n`);
+    }
+    else if (action === "restart") {
+        const result = await restartManagedCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
+        process.stdout.write(readBoolFlag("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderManagedGatewayStatus(result));
+    }
+    else if (action === "stop") {
+        const result = await stopManagedCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
+        process.stdout.write(readBoolFlag("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderManagedGatewayStatus(result));
+    }
     else if (action === "run") {
         await runCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
     }
     else {
-        throw new Error("Use witnora gateway init|doctor|run.");
+        throw new Error("Use witnora gateway init|doctor|start|status|logs|restart|stop|run.");
     }
 }
 else if (command === "discover") {

package/dist/command-help.js

@@ -1,6 +1,27 @@
 export function renderCommandHelp(command) {
     if (command === "sandbox" || command === "browser-adapter")
         return undefined;
+    if (command === "release")
+        return `Usage:
+  witnora release evaluate --case <assurance-case-id>
+
+Runs one allowlisted release-evaluation script already defined by this repository,
+writes a Witnora evidence bundle, and attaches it to the selected self-service
+release assurance case. Hosted configuration cannot supply executable commands.
+
+Script selection order:
+  witnora:release, evals:run, test:ci, test
+
+Options:
+  --case <id>             Self-service release assurance case (required)
+  --connection <name>    Saved Hosted connection
+  --repo <directory>     Agent repository (default: current directory)
+  --out <directory>      Evidence output directory
+  --server <url>         Hosted Witnora base URL
+  --project <id>         Hosted project ID
+  --api-key <key>        Project API key (prefer the saved connection or secret manager)
+  --help, -h             Show this help
+`;
     if (command === "discover")
         return `Usage:
   witnora discover [--connection <name>] [--repo <directory>]
@@ -22,8 +43,9 @@ Options:
   witnora onboard --project <project-id> --template <browser|coding|mcp|workflow|data>
 
 Opens one browser authorization, saves a restricted project credential, detects the repository,
-writes missing starter files, and records an isolated synthetic self-test receipt. The self-test
-does not create assurance evidence or establish CURRENT status.
+writes missing starter files, starts a customer-owned Gateway in the background, and records an
+isolated synthetic self-test receipt. The self-test does not create assurance evidence or establish
+CURRENT status.
 
 Options:
   --server <url>          Hosted server (default: https://witnora.com)
@@ -37,12 +59,18 @@ Options:
         return `Usage:
   witnora gateway init --project <project-id>
   witnora gateway doctor
+  witnora gateway start
+  witnora gateway status
+  witnora gateway logs [--lines 100]
+  witnora gateway restart
+  witnora gateway stop
   witnora gateway run
 
-Initializes and runs a customer-owned, metadata-only collector beside the Agent.
+Initializes and manages a customer-owned, metadata-only collector beside the Agent.
 The browser approval issues a collector-scoped credential; no API key is copied into
 the repository or exposed to the Agent. The local queue and source signing key remain
-under customer control.
+under customer control. Onboard uses background start by default. The run command is
+the foreground debugging path.
 
 The reference Gateway establishes RECORDED evidence only. ENFORCED requires target
 write credentials behind a controlled execution adapter. OUTCOME VERIFIED requires a
@@ -56,7 +84,8 @@ Options:
   --name <name>           Saved collector connection name
   --no-browser            Print the approval URL without opening it
   --force                 Replace an existing reviewed local setup
-  --json                  JSON doctor output
+  --json                  JSON status output
+  --lines <count>         Number of recent log lines (default: 100)
 `;
     if (command === "design-partner")
         return `Usage:

package/dist/control-plane.js

@@ -100,6 +100,8 @@ export async function pushEvidenceToControlPlane(options) {
         schemaVersion: bundle.schemaVersion,
         runId: run.id,
     });
+    if (options.releaseAssuranceCaseId)
+        query.set("assuranceCaseId", options.releaseAssuranceCaseId);
     const evidence = await requestJson(request, `${projectUrl}/evidence?${query}`, {
         method: "POST",
         headers: { ...headers, "content-type": "application/json" },

package/dist/gateway.js

@@ -1,10 +1,14 @@
 import { 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 { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadConnection } from "./credentials.js";
 import { authorizeProjectConnection } from "./device-authorization.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";
 export async function initializeCustomerGateway(options) {
     const repository = resolve(options.repository ?? process.cwd());
     const outDir = resolve(repository, options.outDir ?? ".witnora/gateway");
@@ -59,7 +63,7 @@ export async function initializeCustomerGateway(options) {
         for (const [path, content, mode] of [
             [configPath, `${JSON.stringify(config, null, 2)}\n`, 0o644],
             [secretsPath, `${JSON.stringify(secrets, null, 2)}\n`, 0o600],
-            [gitignorePath, "secrets.json\ndata/\n", 0o644],
+            [gitignorePath, "secrets.json\ndata/\nruntime/\n", 0o644],
             [clientPath, gatewayClient(config), 0o644],
             [readmePath, gatewayReadme(config), 0o644],
         ]) {
@@ -78,10 +82,9 @@ export async function initializeCustomerGateway(options) {
     output("\nCustomer-owned Gateway initialized.\n");
     output(`Configuration: ${configPath}\nLocal secret: ${secretsPath} (never commit or upload)\n`);
     output("Next:\n");
-    output("  1. Run: npx witnora@latest gateway doctor\n");
-    output("  2. Run: npx witnora@latest gateway run\n");
-    output("  3. Import .witnora/gateway/client.mjs at one sandbox workflow boundary.\n");
-    output("  4. Run that workflow normally; start, event, and complete are recorded locally.\n");
+    output("  1. Run: npx witnora@latest gateway start\n");
+    output("  2. Import .witnora/gateway/client.mjs at one sandbox workflow boundary.\n");
+    output("  3. Run that workflow normally; start, event, and complete are recorded locally.\n");
     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 };
 }
@@ -136,7 +139,7 @@ export async function doctorCustomerGateway(options) {
             checks.push({ id: "process", status: "PASS", message: `Gateway is listening at http://${config.host}:${config.port}.` });
         }
         catch {
-            checks.push({ id: "process", status: "WARN", message: "Gateway is not running yet. Start it with `witnora gateway run`." });
+            checks.push({ id: "process", status: "WARN", message: "Gateway is not running yet. Start managed mode with `witnora gateway start`." });
         }
     }
     if (config && secrets) {
@@ -149,7 +152,7 @@ export async function doctorCustomerGateway(options) {
         overall: failed ? "SETUP_INCOMPLETE" : "READY_TO_RECORD",
         checks,
         evidenceCeiling: "recorded",
-        nextAction: failed ? "Run `witnora gateway init --project <project-id>` again after resolving failed checks." : "Start the Gateway, then send one sandbox run through its local event API.",
+        nextAction: failed ? "Run `witnora gateway init --project <project-id>` again after resolving failed checks." : "Ensure the managed Gateway is healthy, then send one sandbox run through its local event API.",
     };
 }
 export async function runCustomerGateway(options) {
@@ -181,6 +184,187 @@ export async function runCustomerGateway(options) {
         process.once(signal, () => void gateway.close().finally(() => process.exit(0)));
     }
 }
+export async function startManagedCustomerGateway(options = {}) {
+    const repository = resolve(options.repository ?? process.cwd());
+    const directory = resolve(repository, options.dir ?? ".witnora/gateway");
+    const config = parseConfig(await readFile(join(directory, "gateway.json"), "utf8"));
+    const current = await statusManagedCustomerGateway(options);
+    if (current.state === "RUNNING_MANAGED" || current.state === "RUNNING_EXTERNAL") {
+        return { ...current, started: false };
+    }
+    if (current.state === "CONFLICT")
+        throw new Error(current.detail);
+    if (current.state === "STALE")
+        await rm(runtimePath(directory), { force: true });
+    const cliEntry = resolve(options.cliEntry ?? fileURLToPath(new URL("./cli.js", import.meta.url)));
+    if (!await exists(cliEntry))
+        throw new Error(`Managed Gateway CLI entry was not found at ${cliEntry}. Reinstall Witnora and run onboard again.`);
+    const runtimeDirectory = join(directory, "runtime");
+    const logPath = join(runtimeDirectory, "gateway.log");
+    await mkdir(runtimeDirectory, { recursive: true });
+    const log = openSync(logPath, "a");
+    let launchError;
+    let child;
+    try {
+        const args = [cliEntry, "gateway", "run", "--repo", repository];
+        if (options.dir)
+            args.push("--dir", options.dir);
+        child = spawn(process.execPath, args, {
+            cwd: repository,
+            detached: true,
+            windowsHide: true,
+            stdio: ["ignore", log, log],
+            env: {
+                ...process.env,
+                ...(options.configHome ? { WITNORA_CONFIG_HOME: options.configHome } : {}),
+                WITNORA_GATEWAY_MANAGED: "1",
+            },
+        });
+        child.once("error", (error) => { launchError = error; });
+        child.unref();
+    }
+    finally {
+        closeSync(log);
+    }
+    if (!child.pid)
+        throw new Error("Witnora could not obtain a process ID for the managed Gateway.");
+    const runtime = {
+        schemaVersion: RUNTIME_SCHEMA,
+        pid: child.pid,
+        projectId: config.projectId,
+        server: config.server,
+        collectorId: config.collectorId,
+        host: config.host,
+        port: config.port,
+        startedAt: new Date().toISOString(),
+        cliEntry,
+        logPath,
+    };
+    await writeFile(runtimePath(directory), `${JSON.stringify(runtime, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await chmod(runtimePath(directory), 0o600).catch(() => undefined);
+    const sleep = options.sleep ?? wait;
+    const deadline = Date.now() + (options.timeoutMs ?? 12_000);
+    while (Date.now() < deadline) {
+        if (launchError)
+            break;
+        const status = await statusManagedCustomerGateway(options);
+        if (status.state === "RUNNING_MANAGED") {
+            options.output?.(`Managed customer-owned Gateway started in the background at ${status.baseUrl}.\nLog: ${logPath}\n`);
+            return { ...status, started: true };
+        }
+        if (status.state === "CONFLICT") {
+            await stopManagedCustomerGateway({ ...options, timeoutMs: 2_000 }).catch(() => undefined);
+            throw new Error(status.detail);
+        }
+        await sleep(120);
+    }
+    await stopManagedCustomerGateway({ ...options, timeoutMs: 2_000 }).catch(() => undefined);
+    const tail = await readManagedCustomerGatewayLogs({ repository, dir: options.dir, lines: 20 }).catch(() => "");
+    throw new Error(`Managed Gateway did not become healthy${launchError ? `: ${launchError.message}` : " before the startup deadline"}.${tail ? `\nRecent Gateway log:\n${tail}` : ""}`);
+}
+export async function statusManagedCustomerGateway(options = {}) {
+    const repository = resolve(options.repository ?? process.cwd());
+    const directory = resolve(repository, options.dir ?? ".witnora/gateway");
+    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);
+    const base = {
+        schemaVersion: "witnora.managed_gateway_status.v0.1",
+        baseUrl,
+        projectId: config.projectId,
+        collectorId: config.collectorId,
+        pid: runtime?.pid,
+        logPath: runtime?.logPath,
+    };
+    if (health && health.collectorId !== config.collectorId) {
+        return { ...base, state: "CONFLICT", healthy: false, managed: false, detail: `Port ${config.port} is occupied by collector ${health.collectorId}, not ${config.collectorId}.` };
+    }
+    if (runtime && !runtimeMatches(runtime, config)) {
+        return { ...base, state: "CONFLICT", healthy: false, managed: false, detail: "Managed Gateway runtime metadata belongs to a different project or collector." };
+    }
+    if (health) {
+        const managed = Boolean(runtime && pidRunning(runtime.pid));
+        return {
+            ...base,
+            state: managed ? "RUNNING_MANAGED" : "RUNNING_EXTERNAL",
+            healthy: true,
+            managed,
+            detail: managed ? "The customer-owned Gateway is healthy and managed by Witnora." : "A compatible Gateway is healthy but was started outside Witnora process management.",
+        };
+    }
+    if (runtime) {
+        const running = pidRunning(runtime.pid);
+        return {
+            ...base,
+            state: running ? "STARTING" : "STALE",
+            healthy: false,
+            managed: running,
+            detail: running ? "The managed Gateway process is starting but has not passed its health check." : "Managed Gateway runtime metadata is stale; the recorded process is no longer running.",
+        };
+    }
+    return { ...base, state: "STOPPED", healthy: false, managed: false, detail: "The customer-owned Gateway is not running." };
+}
+export async function stopManagedCustomerGateway(options = {}) {
+    const repository = resolve(options.repository ?? process.cwd());
+    const directory = resolve(repository, options.dir ?? ".witnora/gateway");
+    const runtime = await readRuntime(directory);
+    const before = await statusManagedCustomerGateway(options);
+    if (!runtime)
+        return { ...before, stopped: false };
+    if (before.state === "CONFLICT")
+        throw new Error(before.detail);
+    if (pidRunning(runtime.pid)) {
+        try {
+            process.kill(runtime.pid, "SIGTERM");
+        }
+        catch (error) {
+            if (!isMissingProcess(error))
+                throw error;
+        }
+        const sleep = options.sleep ?? wait;
+        const deadline = Date.now() + (options.timeoutMs ?? 5_000);
+        while (Date.now() < deadline && pidRunning(runtime.pid))
+            await sleep(100);
+        if (pidRunning(runtime.pid)) {
+            try {
+                process.kill(runtime.pid, "SIGKILL");
+            }
+            catch (error) {
+                if (!isMissingProcess(error))
+                    throw error;
+            }
+        }
+    }
+    await rm(runtimePath(directory), { force: true });
+    const after = await statusManagedCustomerGateway(options);
+    return { ...after, stopped: !after.healthy };
+}
+export async function restartManagedCustomerGateway(options = {}) {
+    const status = await statusManagedCustomerGateway(options);
+    if (status.state === "RUNNING_EXTERNAL")
+        throw new Error("The Gateway is running outside Witnora process management. Stop that foreground process before requesting a managed restart.");
+    await stopManagedCustomerGateway(options);
+    return startManagedCustomerGateway(options);
+}
+export async function readManagedCustomerGatewayLogs(options = {}) {
+    const repository = resolve(options.repository ?? process.cwd());
+    const directory = resolve(repository, options.dir ?? ".witnora/gateway");
+    const path = join(directory, "runtime", "gateway.log");
+    const content = await readFile(path, "utf8");
+    return content.split(/\r?\n/).slice(-Math.max(1, options.lines ?? 100)).join("\n").trim();
+}
+export function renderManagedGatewayStatus(result) {
+    return [
+        `Customer-owned Gateway: ${result.state}`,
+        `Health: ${result.healthy ? "HEALTHY" : "UNAVAILABLE"}`,
+        `Endpoint: ${result.baseUrl}`,
+        ...(result.pid ? [`Process: ${result.pid}${result.managed ? " (managed)" : ""}`] : []),
+        ...(result.logPath ? [`Log: ${result.logPath}`] : []),
+        result.detail,
+        "",
+    ].join("\n");
+}
 export function renderGatewayDoctor(result) {
     return [
         `Customer-owned Gateway: ${result.overall}`,
@@ -218,7 +402,7 @@ 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}\`.\n\n## Start the Gateway\n\n\`\`\`bash\nnpx witnora@latest gateway doctor\nnpx witnora@latest gateway run\n\`\`\`\n\nKeep \`gateway run\` open. 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\` or \`data/\`.\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`;
+    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`;
 }
 function gatewayClient(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`;
@@ -248,6 +432,51 @@ function gatewayPaths(directory) {
         join(directory, "README.md"),
     ];
 }
+async function gatewayHealth(baseUrl, requestFetch) {
+    try {
+        const response = await requestFetch(`${baseUrl}/healthz`, { signal: AbortSignal.timeout(800) });
+        if (!response.ok)
+            return undefined;
+        const value = await response.json();
+        return typeof value.collectorId === "string" && value.collectorId ? { collectorId: value.collectorId } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readRuntime(directory) {
+    try {
+        const value = JSON.parse(await readFile(runtimePath(directory), "utf8"));
+        if (value.schemaVersion !== RUNTIME_SCHEMA || !Number.isSafeInteger(value.pid) || Number(value.pid) < 1 || !value.projectId || !value.collectorId || !value.host || !Number.isSafeInteger(value.port) || !value.cliEntry || !value.logPath)
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function runtimeMatches(runtime, config) {
+    return runtime.projectId === config.projectId && runtime.server === config.server && runtime.collectorId === config.collectorId
+        && runtime.host === config.host && runtime.port === config.port;
+}
+function runtimePath(directory) {
+    return join(directory, "runtime", "gateway-runtime.json");
+}
+function pidRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isMissingProcess(error);
+    }
+}
+function isMissingProcess(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ESRCH");
+}
+function wait(milliseconds) {
+    return new Promise((resolveWait) => setTimeout(resolveWait, milliseconds));
+}
 function safeSlug(value) {
     return (value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "agent-repository").slice(0, 48);
 }

package/dist/onboard.js

@@ -7,7 +7,7 @@ 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 } from "./gateway.js";
+import { doctorCustomerGateway, initializeCustomerGateway, inspectCustomerGatewayFiles, startManagedCustomerGateway, stopManagedCustomerGateway, } from "./gateway.js";
 export async function runOnboard(options) {
     const requestFetch = options.fetch ?? fetch;
     const output = options.output ?? ((message) => process.stdout.write(message));
@@ -38,7 +38,12 @@ export async function runOnboard(options) {
     }
     const attemptId = `install-${Date.now()}-${randomSuffix()}`;
     const generatedFiles = [];
+    const gatewayLifecycle = options.gatewayLifecycle ?? {
+        start: startManagedCustomerGateway,
+        stop: stopManagedCustomerGateway,
+    };
     let gatewayMigration;
+    let managedGateway;
     await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, { status: "installing", attemptId });
     try {
         generatedFiles.push(...await generateRepositoryConfig(repositoryPath, repository.template, repository.name));
@@ -103,6 +108,14 @@ export async function runOnboard(options) {
             }
         }
         generatedFiles.push(...await generateAutopilotFiles(repositoryPath, repository.name));
+        managedGateway = await gatewayLifecycle.start({
+            repository: repositoryPath,
+            configHome: options.configHome,
+            fetch: requestFetch,
+            output,
+        });
+        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")
             throw new Error(doctor.checks.filter((check) => check.status === "FAIL").map((check) => check.message).join(" "));
@@ -114,13 +127,18 @@ export async function runOnboard(options) {
         output(`Credentials: ${credentialsPath}\nSelf-test receipt: ${receiptPath}\n`);
         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("The self-test remains isolated. Start the generated Gateway and run the agent normally; the first source-signed, server-reconciled Gateway run completes onboarding.\n");
+        output(`Gateway: ${managedGateway.state} at ${managedGateway.baseUrl}${managedGateway.pid ? ` (process ${managedGateway.pid})` : ""}.\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 };
+            gatewayDirectory: join(repositoryPath, ".witnora", "gateway"), gatewayArchiveDirectory: gatewayMigration?.archiveDirectory,
+            gateway: managedGateway };
     }
     catch (error) {
         const diagnosis = error instanceof Error ? error.message : String(error);
+        if (managedGateway?.started) {
+            await gatewayLifecycle.stop({ repository: repositoryPath, configHome: options.configHome, fetch: requestFetch }).catch(() => undefined);
+        }
         await rollbackGeneratedFiles(generatedFiles);
         if (gatewayMigration)
             await restoreGateway(gatewayMigration);

package/dist/release-evaluation.js

@@ -0,0 +1,309 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { withArtifactManifest } from "./artifact-manifest.js";
+import { buildEvidenceBundle } from "./bundle.js";
+import { collectCompanionArtifacts } from "./companion-artifacts.js";
+import { pushEvidenceToControlPlane } from "./control-plane.js";
+const RELEASE_SCRIPT_CANDIDATES = ["witnora:release", "evals:run", "test:ci", "test"];
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+export async function runReleaseEvaluation(options) {
+    const repository = resolve(options.repository ?? process.cwd());
+    const assuranceCase = await loadReleaseAssuranceCase(options.connection, options.assuranceCaseId, options.fetch ?? fetch);
+    assertEvaluatingSelfServiceCase(assuranceCase);
+    const script = await detectReleaseScript(repository);
+    const timeoutMs = normalizeTimeout(options.timeoutMs);
+    const executedAt = (options.now ?? (() => new Date()))();
+    const execution = await (options.runner ?? runNpmScript)({ repository, script, timeoutMs });
+    const outputDirectory = resolve(options.outDir ?? join(repository, ".witnora", "release", assuranceCase.id));
+    await mkdir(outputDirectory, { recursive: true });
+    const logPath = join(outputDirectory, "evaluation.log");
+    const evaluationArtifactPath = join(outputDirectory, "evaluation-output.json");
+    const evidencePath = join(outputDirectory, "agentcert-evidence.json");
+    await writeFile(logPath, renderEvaluationLog(script, execution), "utf8");
+    await writeFile(evaluationArtifactPath, `${JSON.stringify(renderEvaluationArtifact(script, execution), null, 2)}\n`, "utf8");
+    const result = releaseEvaluationResult({
+        assuranceCase,
+        script,
+        execution,
+        timestamp: executedAt.toISOString(),
+        runId: (options.randomId ?? randomUUID)(),
+        artifactPath: relative(repository, evaluationArtifactPath).replaceAll("\\", "/"),
+    });
+    let bundle = buildEvidenceBundle([result], assuranceCase.subject.name, assuranceCase.subject.kind);
+    bundle.runId = `witnora_release_${result.runId}`;
+    bundle.generatedAt = executedAt.toISOString();
+    const companions = await collectCompanionArtifacts(bundle, repository);
+    bundle = withArtifactManifest(bundle, companions.artifacts);
+    const evidenceBytes = new TextEncoder().encode(`${JSON.stringify(bundle, null, 2)}\n`);
+    await writeFile(evidencePath, evidenceBytes);
+    const hosted = await (options.push ?? pushEvidenceToControlPlane)({
+        baseUrl: options.connection.server,
+        projectId: options.connection.projectId,
+        apiKey: options.connection.apiKey,
+        bundle,
+        evidenceBytes,
+        fileName: "agentcert-evidence.json",
+        companionArtifacts: companions.artifacts,
+        skippedCompanionArtifacts: companions.skipped,
+        releaseAssuranceCaseId: assuranceCase.id,
+    });
+    return {
+        assuranceCaseId: assuranceCase.id,
+        script,
+        passed: execution.exitCode === 0 && !execution.timedOut,
+        exitCode: execution.exitCode,
+        timedOut: execution.timedOut,
+        evidencePath,
+        logPath,
+        hostedRunId: hosted.runId,
+        hostedEvidenceId: hosted.evidenceId,
+    };
+}
+export function renderReleaseEvaluation(outcome) {
+    const status = outcome.passed ? "PASSED" : "FAILED";
+    return [
+        `Release evaluation: ${status}`,
+        `Local script: npm run ${outcome.script}`,
+        `Evidence: ${outcome.evidencePath}`,
+        `Log: ${outcome.logPath}`,
+        `Hosted run: ${outcome.hostedRunId}`,
+        `Attached to release assurance case: ${outcome.assuranceCaseId}`,
+        outcome.passed
+            ? "Next: return to Release Assurance. Witnora will enable customer review after the attached evidence is verified."
+            : "Next: inspect the log, fix the failing evaluation, and run the same command again. The failed evidence remains part of the audit trail.",
+        "",
+    ].join("\n");
+}
+async function loadReleaseAssuranceCase(connection, caseId, request) {
+    const response = await request(`${connection.server.replace(/\/$/, "")}/v1/projects/${encodeURIComponent(connection.projectId)}/assurance-cases/${encodeURIComponent(caseId)}`, { headers: { authorization: `Bearer ${connection.apiKey}` } });
+    if (!response.ok) {
+        const body = await response.text();
+        let message = body || `HTTP ${response.status}`;
+        try {
+            const parsed = JSON.parse(body);
+            message = parsed.error ?? parsed.message ?? message;
+        }
+        catch {
+            // Preserve the plain response body.
+        }
+        throw new Error(`Could not load release assurance case ${caseId}: ${message}`);
+    }
+    const payload = await response.json();
+    if (!payload.assuranceCase)
+        throw new Error(`Release assurance case ${caseId} was not returned by Hosted.`);
+    return payload.assuranceCase;
+}
+function assertEvaluatingSelfServiceCase(assuranceCase) {
+    if (assuranceCase.engagement) {
+        throw new Error("This case is managed by an independent review engagement. Use the reviewer evidence workflow instead.");
+    }
+    if (assuranceCase.status !== "evaluating") {
+        throw new Error(`Release assurance case ${assuranceCase.id} is ${assuranceCase.status}, not evaluating.`);
+    }
+}
+async function detectReleaseScript(repository) {
+    let raw;
+    try {
+        raw = await readFile(join(repository, "package.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error("No package.json was found. Add a local `witnora:release` npm script that runs the repository's existing release evaluation.");
+        }
+        throw error;
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("package.json is not valid JSON.");
+    }
+    const script = RELEASE_SCRIPT_CANDIDATES.find((candidate) => typeof packageJson.scripts?.[candidate] === "string");
+    if (!script) {
+        throw new Error("No supported release evaluation script was found. Add `witnora:release`, or expose an existing `evals:run`, `test:ci`, or `test` npm script.");
+    }
+    return script;
+}
+async function runNpmScript(input) {
+    return new Promise((resolveRun, rejectRun) => {
+        const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["run", input.script], {
+            cwd: input.repository,
+            detached: process.platform !== "win32",
+            shell: false,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        let forceTimer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (forceTimer)
+                clearTimeout(forceTimer);
+            resolveRun(result);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            terminateProcessTree(child.pid);
+            forceTimer = setTimeout(() => {
+                terminateProcessTree(child.pid, true);
+                finish({ exitCode: 1, stdout, stderr, timedOut: true });
+            }, 5_000);
+        }, input.timeoutMs);
+        child.stdout.on("data", (chunk) => { stdout = appendBounded(stdout, chunk); });
+        child.stderr.on("data", (chunk) => { stderr = appendBounded(stderr, chunk); });
+        child.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (forceTimer)
+                clearTimeout(forceTimer);
+            rejectRun(error);
+        });
+        child.once("close", (code) => {
+            finish({ exitCode: code ?? 1, stdout, stderr, timedOut });
+        });
+    });
+}
+function terminateProcessTree(pid, force = false) {
+    if (!pid)
+        return;
+    if (process.platform === "win32") {
+        const taskkill = spawn("taskkill", ["/pid", String(pid), "/t", "/f"], {
+            shell: false,
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        taskkill.on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(-pid, force ? "SIGKILL" : "SIGTERM");
+    }
+    catch {
+        // The process may have exited between the timeout and termination attempt.
+    }
+}
+function appendBounded(current, chunk) {
+    if (Buffer.byteLength(current) >= MAX_OUTPUT_BYTES)
+        return current;
+    const remaining = MAX_OUTPUT_BYTES - Buffer.byteLength(current);
+    return current + chunk.subarray(0, remaining).toString("utf8");
+}
+function normalizeTimeout(value) {
+    const timeout = value ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeout) || timeout < 1_000 || timeout > 30 * 60 * 1000) {
+        throw new Error("Release evaluation timeout must be between 1 second and 30 minutes.");
+    }
+    return timeout;
+}
+function renderEvaluationLog(script, result) {
+    return [
+        `command=npm run ${script}`,
+        `exitCode=${result.exitCode}`,
+        `timedOut=${result.timedOut}`,
+        "",
+        "[stdout]",
+        result.stdout,
+        "",
+        "[stderr]",
+        result.stderr,
+        "",
+    ].join("\n");
+}
+function renderEvaluationArtifact(script, result) {
+    const stdout = redactEvaluationOutput(result.stdout);
+    const stderr = redactEvaluationOutput(result.stderr);
+    return {
+        schemaVersion: "witnora.release_evaluation_output.v0.1",
+        command: { executable: "npm", arguments: ["run", script] },
+        exitCode: result.exitCode,
+        timedOut: result.timedOut,
+        stdout: outputDescriptor(result.stdout, stdout.value),
+        stderr: outputDescriptor(result.stderr, stderr.value),
+        redaction: {
+            policyVersion: "witnora.release_output_redaction.v0.1",
+            replacements: stdout.replacements + stderr.replacements,
+            rawOutputRetainedLocally: true,
+        },
+    };
+}
+function outputDescriptor(raw, redacted) {
+    return {
+        sha256: createHash("sha256").update(raw).digest("hex"),
+        byteLength: Buffer.byteLength(raw),
+        excerpt: redacted,
+    };
+}
+function redactEvaluationOutput(value) {
+    const patterns = [
+        /\bsk-(?:proj-|live_|test_)?[A-Za-z0-9_-]{16,}\b/g,
+        /\brk_(?:live|test)_[A-Za-z0-9]{12,}\b/g,
+        /\bnpm_[A-Za-z0-9]{16,}\b/g,
+        /\bac_(?:live|test)_[A-Za-z0-9_-]{12,}\b/g,
+        /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/gi,
+    ];
+    let redacted = value;
+    let replacements = 0;
+    for (const pattern of patterns) {
+        redacted = redacted.replace(pattern, () => {
+            replacements += 1;
+            return "[REDACTED_SECRET]";
+        });
+    }
+    return { value: redacted, replacements };
+}
+function releaseEvaluationResult(input) {
+    const passed = input.execution.exitCode === 0 && !input.execution.timedOut;
+    return {
+        schemaVersion: "1",
+        product: "agentcert-cli",
+        runId: input.runId,
+        timestamp: input.timestamp,
+        phase: "pre-release",
+        score: passed ? 100 : 0,
+        passed,
+        summary: passed
+            ? `The repository's existing ${input.script} evaluation completed successfully.`
+            : `The repository's existing ${input.script} evaluation failed${input.execution.timedOut ? " after timing out" : ""}.`,
+        evidenceStrength: {
+            schemaVersion: "agentcert.evidence_strength.v0.1",
+            level: "reported",
+            claims: ["A customer-owned repository evaluation produced a captured process result."],
+            limitations: ["This local command result is not independent outcome verification or an independent Witnora review."],
+            trustVector: {
+                schemaVersion: "witnora.evidence_trust_vector.v0.1",
+                capture: "self_reported",
+                mediation: "none",
+                outcome: "unverified",
+                completeness: "partial",
+                attestation: "unsigned",
+                review: "none",
+                limitations: ["The repository controls the evaluated script and its reported outcome."],
+            },
+        },
+        artifacts: { evaluationOutput: input.artifactPath },
+        evidence: [{
+                id: `release-evaluation-${input.runId}`,
+                kind: "release_evaluation",
+                severity: passed ? "info" : "high",
+                message: passed
+                    ? `npm run ${input.script} completed with exit code 0.`
+                    : `npm run ${input.script} completed with exit code ${input.execution.exitCode}${input.execution.timedOut ? " after timing out" : ""}.`,
+                source: "witnora-cli",
+                artifactPath: input.artifactPath,
+                suggestedFix: passed ? undefined : "Inspect the complete local evaluation log and the uploaded redacted summary, correct the failure, and rerun this release evaluation.",
+                metadata: { assuranceCaseId: input.assuranceCase.id, script: input.script, timedOut: input.execution.timedOut },
+            }],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "Apache-2.0",