witnora 0.20.13 → 0.20.15

package/dist/cli.js

@@ -155,7 +155,7 @@ else if (command === "onboard") {
         throw new Error("--project <project-id> is required.");
     await runOnboard({
         projectId,
-        server: readFlag("--server") ?? brandedEnvironment("BASE_URL") ?? DEFAULT_WITNORA_SERVER,
+        server: readFlag("--server"),
         name: readFlag("--name"),
         repository: readFlag("--repo") ?? process.cwd(),
         template: readFlag("--template") ? parseAgentTemplate(readFlag("--template")) : undefined,
@@ -282,6 +282,8 @@ else if (command === "gateway") {
             configHome,
         }, () => stopManagedCustomerGateway({ repository, dir, configHome }));
         process.stdout.write(readBoolFlag("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderManagedGatewayStatus(result));
+        if (!readBoolFlag("--json"))
+            process.stdout.write("Automatic startup remains installed if previously configured. To remove it, run witnora gateway service uninstall with the same --repo and --dir options. Saved credentials and evidence are retained.\n");
     }
     else if (action === "exec") {
         const boundary = process.argv.indexOf("--", 4);
@@ -322,7 +324,9 @@ else if (command === "gateway") {
         process.stdout.write(`Configured the Managed Workflow Harness for ${result.config.workflowIds?.length ?? "all active"} Workflow Contract(s).\nConfig: ${result.path}\nRestart the managed Gateway to activate it.\n`);
     }
     else {
-        throw new Error("Use witnora gateway init|doctor|start|status|logs|restart|repair|service|stop|exec|run|workflow-harness.");
+        process.stdout.write(renderCommandHelp("gateway"));
+        if (action !== "help")
+            process.exitCode = 1;
     }
 }
 else if (command === "discover") {
@@ -901,11 +905,18 @@ else if (command === "conformance") {
 }
 else {
     process.stdout.write(`Usage:
+Connection and discovery:
   witnora onboard --project <project-id>
+  witnora discover [--connection <name>] [--repo <directory>]
+  witnora gateway --help
+  witnora gateway status|doctor|start|restart|stop
+  witnora gateway service install|uninstall
   witnora mcp
   witnora try --template workflow [--push]
   witnora init --subject my-browser-agent
   witnora connect --server https://witnora.com --project <project-id>
+
+Local setup and evaluation:
   witnora sandbox init
   witnora sandbox certify --adapter ./witnora.sandbox.mjs
   witnora sandbox push --adapter ./witnora.sandbox.mjs
@@ -913,6 +924,8 @@ else {
   witnora browser-adapter certify --adapter ./witnora.browser-adapter.mjs
   witnora init --out witnora.config.json --tripwire-config tripwire.yml --force
   witnora init --subject my-browser-agent --github-action
+
+Evidence, reports, and history:
   witnora report --mcpbench .mcpbench/latest/results.json --tripwire .tripwire/latest/tripwire-result.json --onegent .onegent/procurement/audit-packet.json --out .witnora/latest --subject my-agent
   witnora corpus ingest --tripwire .tripwire/latest/tripwire-result.json --out .witnora/corpus/corpus.jsonl --subject my-agent
   witnora corpus review --corpus .witnora/corpus/corpus.jsonl --reviews .witnora/corpus/failure-reviews.jsonl --pattern-key <failure-key> --type wrong_click --status corrected

package/dist/command-help.js

@@ -48,6 +48,8 @@ writes missing starter files, starts a customer-owned Gateway in the background,
 isolated synthetic self-test receipt. The self-test does not create assurance evidence or establish
 CURRENT status. When --action-transport is selected, Witnora validates that exact local transport
 without proposing or executing an Action and reports the bounded result to Hosted.
+Use witnora gateway stop to stop it now, or witnora gateway service uninstall to remove
+automatic startup. Both preserve saved credentials and historical evidence.
 
 Options:
   --server <url>          Hosted server (default: https://witnora.com)
@@ -86,6 +88,7 @@ Options:
   witnora gateway service install|uninstall
   witnora gateway stop
   witnora gateway run
+  witnora gateway exec -- <agent command>
   witnora gateway workflow-harness --workflow <id> --evaluator-origin http://127.0.0.1:<port>/ \\
     --evaluator-credential-handle file://... --evaluator-contract-sha256 <sha256>
 
@@ -96,6 +99,8 @@ under customer control. The service command installs an OS-native auto-start and
 boundary. Repair safely reinstalls that boundary, restarts the existing generated Gateway,
 and reruns digest, credential, Probe, and health checks. The run command is the foreground
 debugging path.
+Stopping the Gateway preserves its installed service. Use gateway service uninstall
+to remove automatic startup without deleting saved credentials or historical evidence.
 
 The reference Gateway establishes RECORDED evidence only. ENFORCED requires target
 write credentials behind a controlled execution adapter. OUTCOME VERIFIED requires a

package/dist/credentials.js

@@ -33,16 +33,27 @@ export async function loadConnection(name, options = {}) {
 }
 export async function resolveConnection(options = {}) {
     const env = options.env ?? process.env;
-    const stored = options.server && options.projectId && options.apiKey
+    const explicit = options.server && options.projectId && options.apiKey;
+    const stored = explicit
         ? undefined
         : await loadConnection(options.name, options);
-    if (options.name && stored && !options.server && !options.projectId && !options.apiKey) {
-        return stored;
+    if (options.name && !stored && !explicit) {
+        throw new Error(`Saved connection "${options.name}" was not found. Run \`witnora onboard --project <project-id> --name ${options.name}\` or provide all three connection flags.`);
+    }
+    // A browser-approved connection is one credential tuple. Ambient variables must
+    // not redirect it to another project or supply that project's key.
+    const witnoraEnvironment = env.WITNORA_BASE_URL !== undefined || env.WITNORA_PROJECT_ID !== undefined || env.WITNORA_API_KEY !== undefined;
+    const source = stored ?? (witnoraEnvironment
+        ? { server: env.WITNORA_BASE_URL, projectId: env.WITNORA_PROJECT_ID, apiKey: env.WITNORA_API_KEY }
+        : { server: env.AGENTCERT_BASE_URL, projectId: env.AGENTCERT_PROJECT_ID, apiKey: env.AGENTCERT_API_KEY });
+    if (!explicit && ((options.server && source.server && normalizeServer(options.server) !== normalizeServer(source.server))
+        || (options.projectId && source.projectId && options.projectId.trim() !== source.projectId.trim()))) {
+        throw new Error("Partial connection flags change the saved or environment server/project. Provide --server, --project, and --api-key together to select another credential tuple; no request was sent.");
     }
     const candidate = {
-        server: options.server ?? env.WITNORA_BASE_URL ?? env.AGENTCERT_BASE_URL ?? stored?.server,
-        projectId: options.projectId ?? env.WITNORA_PROJECT_ID ?? env.AGENTCERT_PROJECT_ID ?? stored?.projectId,
-        apiKey: options.apiKey ?? env.WITNORA_API_KEY ?? env.AGENTCERT_API_KEY ?? stored?.apiKey,
+        server: options.server ?? source.server,
+        projectId: options.projectId ?? source.projectId,
+        apiKey: options.apiKey ?? source.apiKey,
     };
     const missing = Object.entries(candidate).filter(([, value]) => !value).map(([key]) => key);
     if (missing.length > 0) {
@@ -50,6 +61,18 @@ export async function resolveConnection(options = {}) {
     }
     return validateConnection(candidate);
 }
+export function resolveOnboardServer(options) {
+    if (options.server)
+        return normalizeServer(options.server);
+    const env = options.env ?? process.env;
+    const server = env.WITNORA_BASE_URL ?? env.AGENTCERT_BASE_URL;
+    const projectId = env.WITNORA_BASE_URL !== undefined ? env.WITNORA_PROJECT_ID : env.AGENTCERT_PROJECT_ID;
+    if (server && projectId && projectId !== options.projectId) {
+        const projectVariable = env.WITNORA_BASE_URL !== undefined ? "WITNORA_PROJECT_ID" : "AGENTCERT_PROJECT_ID";
+        throw new Error(`Onboarding project "${options.projectId}" differs from environment project "${projectId}". Update or unset ${projectVariable}, or pass --server <url> explicitly to choose the intended server; no authorization request was sent.`);
+    }
+    return normalizeServer(server ?? DEFAULT_WITNORA_SERVER);
+}
 export function credentialsPath(options = {}) {
     const configHome = options.configHome
         ?? process.env.WITNORA_CONFIG_HOME

package/dist/gateway.js

@@ -919,6 +919,7 @@ export async function createContinuousAssuranceController(input) {
     const managed = input.managed ?? await configManagedWorkflowHarnessImport();
     let harness;
     let harnessFingerprint;
+    let harnessHasRealPathBindings = false;
     let timer;
     let reconciling = false;
     let closing = false;
@@ -942,29 +943,38 @@ export async function createContinuousAssuranceController(input) {
         const previous = harness;
         harness = next;
         harnessFingerprint = fingerprint;
+        harnessHasRealPathBindings = config.schemaVersion === MANAGED_WORKFLOW_HARNESS_SCHEMA && Boolean(config.realPathActivations?.length);
         await previous?.close();
     };
     const workflowHarnessPath = join(input.directory, "workflow-harness.json");
     if (await exists(workflowHarnessPath)) {
         try {
-            await replaceHarness(parseManagedWorkflowHarnessConfig(await readFile(workflowHarnessPath, "utf8")));
+            const current = parseManagedWorkflowHarnessConfig(await readFile(workflowHarnessPath, "utf8"));
+            // Reconcile generated provider bindings against this Agent before starting
+            // a cached Harness; older installations may contain another Agent's plan.
+            if (current.schemaVersion !== MANAGED_WORKFLOW_HARNESS_SCHEMA || !current.realPathActivations?.length)
+                await replaceHarness(current);
         }
         catch (error) {
             lastReportedError = message(error);
             process.stderr.write(`Existing Assurance Harness will be repaired in the background: ${lastReportedError}\n`);
         }
     }
-    const reconcile = async () => {
+    const reconcile = async (signal) => {
         if (closing || reconciling)
             return;
         reconciling = true;
+        const reconciliationFetch = signal
+            ? (resource, init) => request(resource, { ...init, signal: init?.signal ? AbortSignal.any([signal, init.signal]) : signal })
+            : request;
         try {
             const activation = await activateRealPathIntegrations({
                 repository: input.repository,
                 server: input.server,
                 projectId: input.projectId,
                 apiKey: input.apiKey,
-                fetch: request,
+                agentIdentity: input.config.agentIdentity ?? { externalId: input.config.connectionName, version: "" },
+                fetch: reconciliationFetch,
             });
             if (activation.state === "READY_TO_START") {
                 const configured = await activateManagedWorkflowHarness({
@@ -975,7 +985,13 @@ export async function createContinuousAssuranceController(input) {
                 });
                 await replaceHarness(configured.config);
             }
-            await publishCurrentChangeManifests({ ...input, fetch: request }, harness ? await harness.status() : undefined);
+            else if (harnessHasRealPathBindings) {
+                await harness?.close();
+                harness = undefined;
+                harnessFingerprint = undefined;
+                harnessHasRealPathBindings = false;
+            }
+            await publishCurrentChangeManifests({ ...input, fetch: reconciliationFetch }, harness ? await harness.status() : undefined);
             lastReportedError = undefined;
         }
         catch (error) {
@@ -988,6 +1004,10 @@ export async function createContinuousAssuranceController(input) {
             reconciling = false;
         }
     };
+    // The collector sends its first signed heartbeat as soon as its server starts.
+    // Resolve the exact Harness first so HTTP readiness cannot race that heartbeat.
+    // A failed or timed-out lookup leaves cached provider bindings unstarted.
+    await reconcile(AbortSignal.timeout(5_000));
     return {
         start() {
             if (timer || closing)

package/dist/onboard.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { access, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { credentialsPath, DEFAULT_WITNORA_SERVER, loadConnection, saveConnection } from "./credentials.js";
+import { credentialsPath, loadConnection, resolveOnboardServer, saveConnection } from "./credentials.js";
 import { authorizeProjectConnection } from "./device-authorization.js";
 import { verifyControlPlaneConnection } from "./control-plane.js";
 import { inferPrivateCapabilities, runPrivateCapabilityDiscovery } from "./private-discovery.js";
@@ -17,7 +17,7 @@ import { runCustomerGatewayCommand } from "./gateway-exec.js";
 export async function runOnboard(options) {
     const requestFetch = options.fetch ?? fetch;
     const output = options.output ?? ((message) => process.stdout.write(message));
-    const server = normalizeServer(options.server ?? DEFAULT_WITNORA_SERVER);
+    const server = resolveOnboardServer(options);
     const repositoryPath = resolve(options.repository ?? process.cwd());
     const repository = await inspectRepository(repositoryPath, options.template);
     const agentIdentity = {
@@ -249,7 +249,7 @@ export async function runOnboard(options) {
         }
         const runtimeConfigured = await gatewayHasRuntimeWorker(repositoryPath);
         generatedFiles.push(...await generateAutopilotFiles(repositoryPath, repository.name, runtimeConfigured));
-        realPathActivation = await activateRealPathIntegrations({ repository: repositoryPath, server, projectId: token.projectId, apiKey: token.apiKey, env: options.env, fetch: requestFetch });
+        realPathActivation = await activateRealPathIntegrations({ repository: repositoryPath, server, projectId: token.projectId, apiKey: token.apiKey, agentIdentity, env: options.env, fetch: requestFetch });
         generatedFiles.push(...realPathActivation.generatedFiles);
         try {
             const activation = await activateManagedWorkflowHarness({ repository: repositoryPath, realPathActivations: realPathActivation.activations, previousGeneratedModuleSha256: realPathActivation.previousGeneratedModuleSha256 });
@@ -352,6 +352,7 @@ export async function runOnboard(options) {
             output(`Keep this command open for up to ${Math.max(1, Math.ceil((options.waitForActionPathMs ?? 0) / 60_000))} minutes. It will finish automatically after you confirm the Business Task in the browser; no second onboard command is required. Press Ctrl+C to pause safely.\n`);
             const resolution = await waitForOnboardingResolution({
                 repository: repositoryPath, server, projectId: token.projectId, apiKey: token.apiKey,
+                agentIdentity,
                 env: options.env, fetch: requestFetch, sleep: options.sleep, timeoutMs: options.waitForActionPathMs ?? 0,
             });
             if (resolution?.kind === "LOCAL_OUTPUT") {
@@ -420,13 +421,14 @@ export async function runOnboard(options) {
             output(`Action transport: ${actionTransportTest.transport.toUpperCase()} is waiting for one exact sandbox Task/action path. ${actionTransportTest.limitation}\n`);
         }
         output(localOutputTaskConfirmed
-            ? "Connected. Nora is monitoring this Agent. The approved read-only local-output task is confirmed; no external Action transport is required.\n"
+            ? "Setup complete. Check this Agent's connection in the workspace; setup alone does not establish a live connection for this Agent, version, and environment. The approved read-only local-output task is confirmed; no external Action transport is required.\n"
             : actionTransportTest?.state === "WAITING_FOR_ACTION_PATH"
                 ? `Base Gateway connected, but ${actionTransportTest.transport.toUpperCase()} Action is not verified yet. Run the Agent once and confirm its Business Task in the browser. Recovery only: rerun this command if the original waiting process was closed.\n`
-                : "Connected. Nora is monitoring this Agent. Run it normally whenever it is ready; the first source-signed activity will appear automatically without blocking setup.\n");
+                : "Setup complete. Check this Agent's connection in the workspace; setup alone does not establish a live connection for this Agent, version, and environment. Run it normally to send source-signed activity.\n");
         output(localWorkflowCommand
             ? `Local sandbox command: ${agentRunCommand}\n`
             : `For a local sandbox workflow, use npx --yes witnora@${cliVersion} gateway exec -- <your normal sandbox command> so the Gateway token stays out of shell history.\n`);
+        output("To stop now: npx witnora@latest gateway stop. To remove automatic startup: npx witnora@latest gateway service uninstall. Run these in this Agent repository; saved credentials and evidence are retained.\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,

package/dist/real-path-activation.js

@@ -12,7 +12,28 @@ export async function activateRealPathIntegrations(options) {
         throw new Error(`Could not load approved real-path integrations (${response.status}).`);
     const body = await boundedJson(response);
     const approved = Array.isArray(body.integrations) ? body.integrations.map(parsePlan).filter((plan) => plan.status === "READY_TO_ACTIVATE" || plan.status === "HARNESS_ACTIVE") : [];
-    const plans = approved.filter((plan) => ["STRIPE_REFUND", "SHOPIFY_DISPUTE", "ZENDESK_TICKET", "SALESFORCE_RECORD", "HUBSPOT_CRM_RECORD", "POSTGRES_RECORD", "QUEUE_JOB"].includes(plan.generated.providerPackId) && plan.environment === "sandbox" && plan.customerSummary.evaluationMode === "SHADOW");
+    let plans = approved.filter((plan) => plan.projectId === options.projectId && ["STRIPE_REFUND", "SHOPIFY_DISPUTE", "ZENDESK_TICKET", "SALESFORCE_RECORD", "HUBSPOT_CRM_RECORD", "POSTGRES_RECORD", "QUEUE_JOB"].includes(plan.generated.providerPackId) && plan.environment === "sandbox" && plan.customerSummary.evaluationMode === "SHADOW");
+    if (plans.length && options.agentIdentity) {
+        const identity = options.agentIdentity;
+        if (!identity.externalId || !identity.version)
+            plans = [];
+        else {
+            const setupResponse = await request(`${base}/v1/projects/${encodeURIComponent(options.projectId)}/setup-plans`, { method: "GET", headers: { authorization: `Bearer ${options.apiKey}` } });
+            if (!setupResponse.ok)
+                throw new Error(`Could not resolve this Agent's exact setup binding (${setupResponse.status}). No provider preflight was attempted.`);
+            const setup = await boundedJson(setupResponse);
+            const plan = setup.plan;
+            const connectedAgentId = plan?.autopilot?.install?.connectedAgentId;
+            // Autopilot credentials can read their own setup, not the workspace-wide
+            // Agent directory. Installation events bind the canonical ID to the exact
+            // locally observed identity; before that event, activation stays pending.
+            const matches = Array.isArray(setup.events) ? setup.events.filter((event) => event?.type === "execution_completed"
+                && event.details?.connectedAgentExternalId === identity.externalId && event.details?.connectedAgentVersion === identity.version
+                && typeof event.details?.connectedAgentId === "string" && (!connectedAgentId || event.details.connectedAgentId === connectedAgentId)) : [];
+            const ids = [...new Set(matches.map((event) => event.details.connectedAgentId))];
+            plans = ids.length === 1 ? plans.filter((integration) => integration.subject.agentId === ids[0] && integration.subject.agentVersion === identity.version) : [];
+        }
+    }
     if (!plans.length)
         return { state: "NOT_CONFIGURED", created: false, activations: [], generatedFiles: [], rollback: async () => undefined };
     const environment = options.env ?? process.env;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.20.13",
+  "version": "0.20.15",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",