witnora 0.12.0 → 0.13.0

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

@@ -38,7 +38,7 @@ import { runDesignPartnerCommand } from "./design-partner-v02.js";
 import { runOnboard } from "./onboard.js";
 import { inspectRepository } from "./onboard.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);
@@ -180,11 +180,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

@@ -22,8 +22,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 +38,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 +63,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/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

@@ -1,13 +1,13 @@
 import { createHash } from "node:crypto";
-import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { DEFAULT_WITNORA_SERVER } from "./credentials.js";
+import { DEFAULT_WITNORA_SERVER, saveConnection } from "./credentials.js";
 import { authorizeProjectConnection } from "./device-authorization.js";
 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,6 +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));
@@ -85,9 +91,31 @@ export async function runOnboard(options) {
             generatedFiles.push(...gateway.generatedFiles);
         }
         else {
-            output("\nExisting complete customer-owned Gateway found; verifying and reusing it.\n");
+            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");
+            }
+            else {
+                await assertGatewayStopped(requestFetch, binding.host, binding.port, binding.projectId, token.projectId);
+                gatewayMigration = await archiveGateway(gatewayState.directory, repositoryPath, binding.projectId);
+                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,
+                    fetch: requestFetch, configHome: options.configHome, output,
+                });
+                generatedFiles.push(...gateway.generatedFiles);
+            }
         }
         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(" "));
@@ -99,20 +127,78 @@ 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") };
+            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);
         await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
             status: "failed", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles), diagnosis, rolledBack: true,
         }).catch(() => undefined);
         throw new Error(`Witnora Setup Autopilot rolled back this install attempt: ${diagnosis}`);
     }
 }
+async function inspectGatewayBinding(directory, projectId, server) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(join(directory, "gateway.json"), "utf8"));
+    }
+    catch {
+        throw new Error("Existing Gateway configuration is not valid JSON. Preserve it and repair the setup in Advanced mode.");
+    }
+    const existingProjectId = typeof value.projectId === "string" ? value.projectId.trim() : "";
+    const existingServer = typeof value.server === "string" ? normalizeServer(value.server) : "";
+    const connectionName = typeof value.connectionName === "string" ? value.connectionName.trim() : "";
+    const host = typeof value.host === "string" && value.host.trim() ? value.host.trim() : "127.0.0.1";
+    const port = Number(value.port);
+    if (!existingProjectId || !existingServer || !connectionName || !Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error("Existing Gateway configuration is missing a valid project, server, host, or port. Preserve it and repair the setup in Advanced mode.");
+    }
+    return { matches: existingProjectId === projectId && existingServer === server, projectId: existingProjectId, server: existingServer, connectionName, host, port };
+}
+async function assertGatewayStopped(requestFetch, host, port, oldProjectId, newProjectId) {
+    try {
+        const response = await requestFetch(`http://${host}:${port}/healthz`, { signal: AbortSignal.timeout(800) });
+        if (!response.ok)
+            return;
+    }
+    catch {
+        return;
+    }
+    throw new Error(`The running Gateway belongs to project ${oldProjectId}, not ${newProjectId}. Stop it with Ctrl+C, then run onboard again so Witnora can preserve the old evidence and bind this repository to the new project.`);
+}
+async function archiveGateway(gatewayDirectory, repositoryPath, projectId) {
+    const archiveRoot = join(repositoryPath, ".witnora", "gateway-archive");
+    const archiveDirectory = join(archiveRoot, `${Date.now()}-${safePathSegment(projectId)}-${randomSuffix()}`);
+    await mkdir(archiveRoot, { recursive: true });
+    const archiveIgnore = join(archiveRoot, ".gitignore");
+    if (!await exists(archiveIgnore))
+        await writeFile(archiveIgnore, "*\n!.gitignore\n");
+    try {
+        await rename(gatewayDirectory, archiveDirectory);
+    }
+    catch (error) {
+        throw new Error(`Could not archive the Gateway for project ${projectId}. Stop any running Gateway with Ctrl+C and retry. ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { gatewayDirectory, archiveDirectory };
+}
+async function restoreGateway(migration) {
+    await rm(migration.gatewayDirectory, { recursive: true, force: true });
+    await rename(migration.archiveDirectory, migration.gatewayDirectory);
+}
+function safePathSegment(value) {
+    return (value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-|-$/g, "") || "unknown-project").slice(0, 80);
+}
 async function generateAutopilotFiles(repositoryPath, subject) {
     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`],

package/package.json

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