@mcpherson-ai/observa-local-node 0.1.3

package/README.md

@@ -0,0 +1,103 @@
+# Observa Local Node
+
+**Mode: SHADOW_ONLY. Authority: NONE. Enforcement: OFF.**
+
+Observa Local Node observes and verifies what your workflow runtime actually did
+and records tamper-evident evidence about it. It has no authority to allow,
+deny, approve, block, retry, or change anything in your systems, and this
+build contains no code path that could.
+
+Observa Local Node is an **invite-only beta**. This package delivers bytes; it
+activates nothing by itself. Installation requires the signed installation
+manifest issued with your invite, and the installer verifies that manifest
+against keys shipped in this package before composing anything.
+
+- Product: Observa Local Node 0.1.3
+- Composition: `observa-local-node-n8n-generic-shadow-beta` (beta channel)
+- Runtime components bundled: 5 (installed for you; never
+  used as separate packages)
+
+## Install
+
+```sh
+npm install -g @mcpherson-ai/observa-local-node@beta
+observa --version
+observa install --manifest <your-signed-manifest.json>
+```
+
+Install by the `beta` dist-tag: this is a beta channel and no
+`latest` release exists, so a bare package name would not resolve.
+
+The approved component artifacts ship inside this package and are found
+automatically; every artifact is verified by manifest-pinned SHA-256 before a
+byte of it is staged. Observa installs into `~/.observa/installation`
+(override: `OBSERVA_HOME`) and touches nothing else. Installation is fully
+offline: the installer has no registry or network surface at all.
+
+## Observe n8n automatically
+
+```sh
+observa config set n8n_loopback_credential '<choose any local secret, 24+ characters>'
+observa n8n-setup
+observa start
+```
+
+That credential is yours: it authenticates n8n's calls to Observa's own
+loopback endpoint on this machine. It is stored owner-only, never transmitted
+by the installer, and never appears in any Observa output.
+
+`n8n-setup` writes an owner-only environment file for n8n's supported global
+backend hook. Configure your n8n service/container to load that environment
+before n8n starts. The hook observes ordinary workflows automatically — do
+not add an Observa node to a workflow. It reads execution metadata only and
+never reads item data, node parameters, credentials, or workflow static data.
+
+## Hosted evidence delivery (if you received a pairing code)
+
+```sh
+observa pair --base-url <HOSTED_BASE_URL> --code-stdin
+```
+
+Paste the single-use pairing code, then send end-of-input (Ctrl-D). The
+resulting connector credential is stored owner-only and never displayed.
+Without a pairing code, everything above still works fully locally.
+
+## Commands
+
+```sh
+observa --help       # full usage
+observa status       # non-secret installation facts
+observa diagnose     # integrity/signature/config checks (exit 1 on FAIL)
+observa start        # start Observa's own local observer
+observa stop         # stop it (never your n8n)
+observa update --manifest <newer-signed-manifest.json>
+observa rollback     # return to the retained previous release
+observa uninstall --yes [--purge-config]
+```
+
+## What ships in this package
+
+| file | internal component | role |
+|---|---|---|
+| `artifacts/mcphersonai-observa-node-0.1.0.tgz` | `@mcphersonai/observa-node@0.1.0` | verification |
+| `artifacts/mcphersonai-observa-adapter-n8n-0.1.0.tgz` | `@mcphersonai/observa-adapter-n8n@0.1.0` | runtime-adapter |
+| `artifacts/mcphersonai-observa-n8n-h1-binding-0.1.0.tgz` | `@mcphersonai/observa-n8n-h1-binding@0.1.0` | integration-binding |
+| `artifacts/mcphersonai-observa-domain-generic-0.1.0.tgz` | `@mcphersonai/observa-domain-generic@0.1.0` | domain-contract |
+| `artifacts/mcphersonai-observa-hosted-transport-0.1.0.tgz` | `@mcphersonai/observa-hosted-transport@0.1.0` | transport-client |
+
+Plus the `observa` CLI, `SHA256SUMS`, and
+`npm-distribution-provenance.json` (exact source identity of every shipped byte).
+
+## What this package will not do
+
+- It cannot allow, deny, approve or enforce anything: SHADOW_ONLY is the only
+  mode in its vocabulary, and a manifest asking for any other word is refused.
+- It never modifies, restarts or reconfigures your n8n or any other system.
+- It asks for no system credentials, and has no field anywhere in which one
+  could be sent to us.
+- It runs no install scripts, has zero dependencies, and phones nothing home.
+
+## If something refuses
+
+Every refusal prints `REFUSED <CODE>`. Send your Observa contact the code
+and the output of `observa diagnose` — neither contains secrets.

package/SHA256SUMS

@@ -0,0 +1,33 @@
+757c317514d4082617a6d8be6a726e744561fc992ec7d57873c3a1029726f869  README.md
+daf644c3cc22f4b588af1f242dd02dd0946b6cfa869db1466da33dfb235871d0  artifacts/mcphersonai-observa-adapter-n8n-0.1.0.tgz
+7f326e4b744f8eeaef7d12d781d82a6f8cf8cea5327ed4c9b22c180bd0ab5e04  artifacts/mcphersonai-observa-domain-generic-0.1.0.tgz
+b6f2ccbbb0526aa08686c8725dd5d2e78aee58e607f15e380170c057a08881e8  artifacts/mcphersonai-observa-hosted-transport-0.1.0.tgz
+5f4bc40bf964255491a21c066d1578b9867b892689c609e4475c53210f7b6b72  artifacts/mcphersonai-observa-n8n-h1-binding-0.1.0.tgz
+00e96d00c9ed9d8d3ca98cde4b9e14c8eecc9adc360174afb7ca95f03db61e3c  artifacts/mcphersonai-observa-node-0.1.0.tgz
+70c520a6c4a2478a60b98bdc2018328c01d1c797c9048f664b507b4ee570632e  distribution/observa-cli/bin/observa-n8n-hosted.mjs
+b2f67dcbf449e858933b5a19775adc8107bd66b6fc3ba2134e36b16eb892287a  distribution/observa-cli/bin/observa.mjs
+0caa044f718d6305d60d53a8fb76255b84c7d08ae70ecb7d285a8d1f37c7d3fd  distribution/observa-cli/integrations/n8n/observa-external-hook.cjs
+e6f3353b323702df54e96210bd0f1363f89636d2c0b216057698b383ecf40c8c  distribution/observa-cli/keys/observa-beta-1.public.json
+31c5bf2495a237be149ab3b1bb72a0707d13f342bb438de1604dc06fe7faf71b  distribution/observa-cli/src/artifact.mjs
+6935ff8d65887154f6e4527cb99e49dae88252f3f423dcc8e38a7a96b261af85  distribution/observa-cli/src/config.mjs
+3ac787dccc3c6a09e7f800ba31e4e3f67fe21f160226a51ed36228d440503c7f  distribution/observa-cli/src/errors.mjs
+8deccb19fca28ea4ebb84d2da43c346a216bf958444376a64b06a59336ec6138  distribution/observa-cli/src/hosted-delivery.mjs
+a89aeeeaa04f099949a40ea3b3cf678aa4114824042df661e1faa71d5b8ce97e  distribution/observa-cli/src/index.mjs
+2bccc8ca0bfd37382f00d032fa6dedce7ca2b6819019ab5d4c97e8995e58d1bc  distribution/observa-cli/src/install.mjs
+0dffd6446a9428fc9f3e45e468988a9b13cfc99a5ad3179a1f1b01029bc5cfbc  distribution/observa-cli/src/lock.mjs
+eccce81a4bd746805d31ee3a270dfd34083a40746293b1307f58288d0d8d79d0  distribution/observa-cli/src/manifest-schema.mjs
+94dd7980032fe70636ef96e089cd96aba2ac1307a369ae7ed52aa3c04267f91b  distribution/observa-cli/src/manifest-verify.mjs
+6ae519f0e59dccd14a6bc6655c65846b1b9084bf28f720b9a5c24bba563d05a0  distribution/observa-cli/src/n8n-hook.mjs
+ce2acc3d335467e7af2531a5950a34c3ed3dacdddb41601df20ff278efe7da63  distribution/observa-cli/src/pair.mjs
+3ccc90a750ae941d9dffd7f8e19be9c0cc404016ee3f442fe5a8ee43abcf9664  distribution/observa-cli/src/re-pair.mjs
+01fc22e4fc893f58d5eef11d726b4044fe2f1ad7430d9acb322e964b60d246e1  distribution/observa-cli/src/service.mjs
+07258afc26ec033d471af3a4bca60c1f2c74d898d55d295baa52a5eceaaf2073  distribution/observa-cli/src/state.mjs
+09dfc6c6e8668c8be4089c0bb6f85c49afdd54479489860c56b03198f011d03e  distribution/observa-cli/src/status.mjs
+5077b323eef9aab9fcb71aae5dd3b5e8ca15ea9b71a489068c2df109da77c2f2  distribution/observa-cli/src/vocabulary.mjs
+5c7b7ae62dd01649983b6635b9b1f0549bbc2199502b384efbef19dd538f2cb6  npm-distribution-provenance.json
+2022669eda7348bcccbbfc69025cadf99df0f5a97c7b8a756499bbbf53d3cd26  package.json
+d3e88b83d1226878130e9fbfbd33fd29634d4cb0c49b4d6a2b6dbc9ebbdb63e1  runtime-adapters/n8n/src/strict-json.mjs
+b28e8f6a53fe945ff1e2610a1f9d333aa9fa62ffe375e253aeadaed74a5eb72d  sdk/contracts/canonical.mjs
+78aa76d66bf8606c2bcfe5e50004139fe8c2168fc3a9b653534fc41f2471a4e9  sdk/contracts/entry-boundary.mjs
+d5aa1bbe72f3fa4ba9edf47ad7dc2113df3877fa852251221c8c0abee60545d7  sdk/contracts/errors.mjs
+88da8b531a26fc8d1b7d68f622e1e135b0addbf75057fd161b773cb449044c87  sdk/contracts/stable-primitives.mjs

package/distribution/observa-cli/bin/observa-n8n-hosted.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// The Local Node service WITH hosted evidence delivery — the v0.1.1 start
+// path when `observa pair` has configured Hosted delivery.
+//
+// This composes the SEALED pieces exactly as the closed binding's harness
+// does, without touching one of their bytes: the sealed adapter's own
+// config, observer and loopback server, with the existing hosted transport
+// client INJECTED at the seam the sealed observer published
+// (`new RuntimeObserver({ transport })`). The sealed binary's own `serve`
+// verb remains the local-receipts-only path and remains untouched.
+//
+// The sealed runtime modules load from the INSTALLED release root
+// (OBSERVA_RELEASE_LIB, set by `observa start`) — the bytes the signed
+// manifest verified — because this bin ships inside the CLI package, away
+// from the runtime artifacts. In the repository the two roots coincide.
+//
+// Environment contract (set by `observa start`, exactly like the sealed
+// serve verb's own env): the sealed OBSERVA_N8N_* variables, plus
+//   OBSERVA_RELEASE_LIB        the installed release lib root
+//   OBSERVA_HOSTED_BASE_URL    where Hosted Observa listens
+//   OBSERVA_HOSTED_CREDENTIAL  the mgd1 connector credential
+// The credential arrives in the environment from the supervisor, exactly as
+// the loopback credential already does, and is never written to a page, a
+// log line, or an error by this process.
+//
+// AUTHORITY: NONE. ENFORCEMENT: OFF. This process observes and delivers
+// evidence; the acknowledgements it receives are receipt acknowledgements
+// with no instruction field to obey.
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  capabilityReportFrom, loadHostedRuntime,
+} from "../src/hosted-delivery.mjs";
+import { HOSTED_BASE_URL_PATTERN } from "../src/pair.mjs";
+
+const MGD1_TOKEN_PATTERN = /^mgd1_[a-f0-9]{32}\.[A-Za-z0-9_-]{43}$/;
+
+const out = (line) => process.stdout.write(`${line}\n`);
+const err = (line) => process.stderr.write(`${line}\n`);
+
+function defaultLibRoot() {
+  // Repository/source convenience only: the CLI package sits two levels
+  // under the release root there. Installed services always receive
+  // OBSERVA_RELEASE_LIB from the supervisor.
+  return fileURLToPath(new URL("../../..", import.meta.url));
+}
+
+export async function serveHosted(env = process.env) {
+  const baseUrl = env.OBSERVA_HOSTED_BASE_URL;
+  const credential = env.OBSERVA_HOSTED_CREDENTIAL;
+  if (typeof baseUrl !== "string" || !HOSTED_BASE_URL_PATTERN.test(baseUrl)) {
+    err("REFUSED HOSTED_BASE_URL_SHAPE_REFUSED");
+    process.exitCode = 1;
+    return null;
+  }
+  if (typeof credential !== "string" || !MGD1_TOKEN_PATTERN.test(credential)) {
+    err("REFUSED HOSTED_CREDENTIAL_SHAPE_REFUSED");
+    process.exitCode = 1;
+    return null;
+  }
+  const libRoot = env.OBSERVA_RELEASE_LIB ?? defaultLibRoot();
+
+  const runtime = await loadHostedRuntime(libRoot);
+  const load = (relative) =>
+    import(pathToFileURL(join(libRoot, ...relative.split("/"))).href);
+  const [{ configFromEnv, describeConfig }, { RuntimeObserver }, serverModule] =
+    await Promise.all([
+      load("runtime-adapters/n8n/src/config.mjs"),
+      load("runtime-adapters/n8n/src/observer.mjs"),
+      load("runtime-adapters/n8n/src/server.mjs"),
+    ]);
+  const { createObservationServer, listen, ROUTES } = serverModule;
+
+  const config = configFromEnv(env);
+  const client = runtime.clientModule.createHostedTransportClient({
+    baseUrl,
+    credential,
+    installationId: config.installationId,
+  });
+  const transport = runtime.clientModule.createHostedObservationTransport({ client });
+  const observer = new RuntimeObserver({
+    receiptPath: config.receiptPath,
+    transport,
+  });
+  const server = createObservationServer({ observer, config });
+  const address = await listen(server, config);
+
+  out("observa n8n local node (hosted delivery) — authority NONE, enforcement OFF");
+  out(`listening on http://${config.host}:${address.port} (loopback only)`);
+  out(`routes: ${ROUTES.ATTEMPT} ${ROUTES.COMPLETION} ${ROUTES.STATUS}`);
+  // describe() and describeConfig() are secret-free by contract.
+  out(`config: ${JSON.stringify(describeConfig(config))}`);
+  out(`hosted transport: ${JSON.stringify(transport.describe())}`);
+
+  // One capability report at startup: which contracts this installation
+  // speaks. Delivery failure is a STATUS, logged as such — the local
+  // observer keeps running either way, exactly like every other delivery.
+  const capability = await client.sendCapabilityReport(capabilityReportFrom(runtime));
+  out(`capability report delivery: ${capability.status}${capability.code ? ` (${capability.code})` : ""}`);
+
+  return { server, observer, client, transport };
+}
+
+// Run only when executed directly; importing this file must stay
+// side-effect free so preflight-style clean-environment imports succeed.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const verb = process.argv[2] ?? "serve";
+  if (verb !== "serve") {
+    err(`REFUSED UNKNOWN_VERB: ${verb} (only: serve)`);
+    process.exitCode = 2;
+  } else {
+    await serveHosted(process.env);
+  }
+}

package/distribution/observa-cli/bin/observa.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// observa — the customer installer/orchestrator.
+//
+//   install    verify a signed manifest and install exact approved artifacts
+//   status     non-secret installation facts
+//   diagnose   integrity/signature/config-presence checks
+//   start      start the Observa-owned local service
+//   stop       stop it (never the customer's n8n or Odoo)
+//   update     install a NEWER signed manifest (retains rollback set)
+//   rollback   return to the retained previous signed manifest
+//   uninstall  remove Observa-managed state (config survives by default)
+//   config     set a LOCAL config value (never printed back)
+//   pair       redeem one pairing code; store hosted delivery config locally
+//   unpair     stop delivery and clear only the hosted pairing config
+//
+// There is no verb that approves, allows, denies, enforces, or decides.
+// The signed manifest authorizes WHICH approved components install; it makes
+// no runtime governance decision, and neither does this tool.
+
+import { homedir } from "node:os";
+import { readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliRefusal } from "../src/errors.mjs";
+import { loadTrustedKeys } from "../src/manifest-verify.mjs";
+import { installFromManifestFile, rollbackToPrevious, uninstall } from "../src/install.mjs";
+import { serviceIsRunning, startService, stopService } from "../src/service.mjs";
+import { collectStatus, runDiagnose } from "../src/status.mjs";
+import { isPairingOwnedConfigKey, isSecretConfigKey, writeLocalConfigValue } from "../src/config.mjs";
+import { pairHosted } from "../src/pair.mjs";
+import {
+  pairingRecoveryAvailable, rePairHosted, unpairHosted,
+} from "../src/re-pair.mjs";
+import { readState } from "../src/state.mjs";
+import { prepareN8nHook } from "../src/n8n-hook.mjs";
+import { CLI_ARTIFACT_ID, CLI_AUTHORITY, CLI_VERSION } from "../src/vocabulary.mjs";
+
+const out = (line) => process.stdout.write(`${line}\n`);
+const err = (line) => process.stderr.write(`${line}\n`);
+
+function defaultHome(env) {
+  return env.OBSERVA_HOME ? resolve(env.OBSERVA_HOME) : join(homedir(), ".observa", "installation");
+}
+
+function defaultTrustDir(env) {
+  if (env.OBSERVA_TRUST_DIR) return resolve(env.OBSERVA_TRUST_DIR);
+  return fileURLToPath(new URL("../keys/", import.meta.url));
+}
+
+// When this CLI is delivered as the Observa Local Node npm distribution, the
+// approved component artifacts ship beside it under <package>/artifacts. That
+// directory is a CONVENIENCE default for `install`'s artifact drop dir — every
+// artifact is still resolved by manifest-pinned sha256, so a wrong or
+// tampered directory changes nothing about what can install.
+function packagedArtifactsDir() {
+  const candidate = fileURLToPath(new URL("../../../artifacts/", import.meta.url));
+  try {
+    return statSync(candidate).isDirectory() ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (["yes", "purge-config", "code-stdin"].includes(key)) {
+        flags[key] = true;
+      } else {
+        i += 1;
+        if (i >= argv.length) throw new CliRefusal("FLAG_VALUE_MISSING", key);
+        flags[key] = argv[i];
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+function banner() {
+  out(`${CLI_ARTIFACT_ID} ${CLI_VERSION}`);
+  out(`authority ${CLI_AUTHORITY} · installer/orchestrator only · SHADOW_ONLY vocabulary`);
+}
+
+function usage() {
+  banner();
+  out("");
+  out("usage: observa <install|status|diagnose|start|stop|update|rollback|uninstall|config|pair|unpair|n8n-setup|version>");
+  out("");
+  out("  install   --manifest <signed.json> [--artifacts <dir>] [--expect-installation <id>]");
+  out("  update    --manifest <signed.json> [--artifacts <dir>]");
+  out("  rollback");
+  out("  status | diagnose | start | stop | version");
+  out("  uninstall --yes [--purge-config]");
+  out("  config set <key> <value>");
+  out("  pair      initial: --base-url <https://host> (--code-stdin | --code-file <owner-only-file>) [--deployment <id>] [--name <label>]");
+  out("            after unpair: no flags; reuses the installed identity");
+  out("  unpair    revoke Hosted delivery; retain the installed identity for re-pair");
+  out("  n8n-setup write an owner-only environment for n8n's global observation hook");
+  out("");
+  out("  --help    print this usage; --version print the version banner");
+  out("");
+  out("environment: OBSERVA_HOME (installation home), OBSERVA_TRUST_DIR (verification keys)");
+}
+
+async function pairingCodeFromInput(flags) {
+  if (flags.code !== undefined) {
+    throw new CliRefusal("PAIR_CODE_ARGV_REFUSED", "use --code-stdin or --code-file");
+  }
+  const stdinSelected = flags["code-stdin"] === true;
+  const fileSelected = typeof flags["code-file"] === "string";
+  if (stdinSelected === fileSelected) {
+    throw new CliRefusal("PAIR_CODE_INPUT_REQUIRED", "choose exactly one of --code-stdin or --code-file");
+  }
+  if (fileSelected) {
+    const path = resolve(flags["code-file"]);
+    let stat;
+    try {
+      stat = statSync(path);
+    } catch {
+      throw new CliRefusal("PAIR_CODE_FILE_UNAVAILABLE");
+    }
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0) {
+      throw new CliRefusal("PAIR_CODE_FILE_PERMISSIONS_REFUSED", "pairing-code file must be owner-only");
+    }
+    const text = readFileSync(path, "utf8");
+    if (Buffer.byteLength(text) > 1024) throw new CliRefusal("PAIR_CODE_INPUT_REFUSED");
+    const code = text.trim();
+    if (code.length === 0) throw new CliRefusal("PAIR_CODE_INPUT_REFUSED");
+    return code;
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > 1024) throw new CliRefusal("PAIR_CODE_INPUT_REFUSED");
+    chunks.push(chunk);
+  }
+  const code = Buffer.concat(chunks).toString("utf8").trim();
+  if (code.length === 0) throw new CliRefusal("PAIR_CODE_INPUT_REFUSED");
+  return code;
+}
+
+function printStatus(status) {
+  banner();
+  out("");
+  if (!status.installed && !status.state_problem) {
+    out("installed        no");
+    return;
+  }
+  if (status.state_problem) out(`state problem    ${status.state_problem}`);
+  out(`installed        ${status.installed ? "yes" : "no"}`);
+  if (status.installation_id) {
+    out(`installation     ${status.installation_id} (org ${status.organization_id}, ws ${status.workspace_id})`);
+    out(`manifest         ${status.manifest_id}`);
+    out(`previous         ${status.previous_manifest_id ?? "none"}`);
+    out(`mode             ${status.mode}`);
+    out(`service          ${status.service}`);
+    out(`hosted           ${status.hosted_configured ? "configured" : "not configured"}`);
+    if (status.manifest_problem) out(`manifest problem ${status.manifest_problem}`);
+    if (status.components) {
+      out("components:");
+      for (const c of status.components) {
+        out(`  ${c.package_name}@${c.package_version} (${c.role})`);
+      }
+    }
+  }
+}
+
+async function main() {
+  const [, , command, ...rest] = process.argv;
+  const env = process.env;
+  const home = defaultHome(env);
+  const { flags, positional } = parseFlags(rest);
+  const trustedKeys = () => loadTrustedKeys(defaultTrustDir(env));
+
+  switch (command) {
+    case "install":
+    case "update": {
+      if (typeof flags.manifest !== "string") throw new CliRefusal("MANIFEST_FLAG_REQUIRED");
+      if (command === "update" && readState(home) === null) {
+        throw new CliRefusal("NOT_INSTALLED", "update requires an existing installation");
+      }
+      const result = installFromManifestFile({
+        home,
+        manifestFile: resolve(flags.manifest),
+        artifactDir: flags.artifacts ? resolve(flags.artifacts) : packagedArtifactsDir(),
+        trustedKeys: trustedKeys(),
+        expectedInstallationId: flags["expect-installation"] ?? null,
+      });
+      banner();
+      out("");
+      out(`${result.transition} ok`);
+      out(`manifest   ${result.manifest.manifest_id}`);
+      out(`mode       ${result.manifest.mode}`);
+      out(`components ${result.manifest.components.length}`);
+      out("status     installed");
+      return;
+    }
+    case "rollback": {
+      const result = rollbackToPrevious({ home, trustedKeys: trustedKeys() });
+      banner();
+      out("");
+      out(`rollback ok → ${result.manifest.manifest_id}`);
+      return;
+    }
+    case "status": {
+      printStatus(collectStatus(home, { trustedKeys: trustedKeys() }));
+      return;
+    }
+    case "diagnose": {
+      const report = runDiagnose(home, { trustedKeys: trustedKeys() });
+      banner();
+      out("");
+      for (const check of report.checks) {
+        out(`${check.status.padEnd(4)}  ${check.check}${check.detail ? `  — ${check.detail}` : ""}`);
+      }
+      out("");
+      out(report.ok ? "DIAGNOSE PASS" : "DIAGNOSE FAIL");
+      if (!report.ok) process.exitCode = 1;
+      return;
+    }
+    case "start": {
+      const result = startService(home, { port: flags.port ? Number(flags.port) : null });
+      out(result.alreadyRunning ? "already running" : `started (pid ${result.pid})`);
+      return;
+    }
+    case "stop": {
+      const result = stopService(home);
+      out(result.wasRunning ? "stopped" : "was not running");
+      return;
+    }
+    case "uninstall": {
+      if (flags.yes !== true) throw new CliRefusal("UNINSTALL_REQUIRES_CONFIRMATION", "pass --yes");
+      const result = uninstall({ home, purgeConfig: flags["purge-config"] === true });
+      out(`uninstalled (customer config ${result.configRetained ? "retained" : "purged"})`);
+      return;
+    }
+    case "config": {
+      if (positional[0] !== "set" || positional.length !== 3) {
+        throw new CliRefusal("CONFIG_USAGE", "observa config set <key> <value>");
+      }
+      if (isPairingOwnedConfigKey(positional[1])) {
+        throw new CliRefusal("HOSTED_CONFIG_PAIRING_OWNED", "use `observa pair`");
+      }
+      writeLocalConfigValue(home, positional[1], positional[2]);
+      // Never echo the value; secret keys are not even named back verbatim.
+      out(`config ${isSecretConfigKey(positional[1]) ? "secret " : ""}key set: ${positional[1]}`);
+      return;
+    }
+    case "pair": {
+      let result;
+      if (pairingRecoveryAvailable(home)) {
+        if (Object.keys(flags).length !== 0 || positional.length !== 0) {
+          throw new CliRefusal("PAIR_RECOVERY_FLAGS_REFUSED", "run `observa pair` with no flags");
+        }
+        result = await rePairHosted({ home });
+      } else {
+        if (typeof flags["base-url"] !== "string") throw new CliRefusal("PAIR_BASE_URL_FLAG_REQUIRED");
+        const pairingCode = await pairingCodeFromInput(flags);
+        result = await pairHosted({
+          home,
+          baseUrl: flags["base-url"],
+          pairingCode,
+          ...(typeof flags.deployment === "string" ? { deploymentId: flags.deployment } : {}),
+          ...(typeof flags.name === "string" ? { installationName: flags.name } : {}),
+        });
+      }
+      banner();
+      out("");
+      out(result.repaired ? "re-paired ok (installed identity preserved)" : "paired ok");
+      out(`installation  ${result.installation_id}`);
+      if (result.credential_id) out(`credential id ${result.credential_id}`);
+      if (result.fingerprint) out(`fingerprint   ${result.fingerprint}`);
+      out(`deployment    ${result.deployment_id}`);
+      out(`hosted url    ${result.hosted_base_url}`);
+      // The credential itself was stored owner-only and is never displayed.
+      out("credential    stored locally (never displayed)");
+      return;
+    }
+    case "unpair": {
+      const wasRunning = serviceIsRunning(home);
+      if (wasRunning) stopService(home);
+      const result = await unpairHosted({ home });
+      out(`unpaired (hosted service ${wasRunning ? "stopped" : "was not running"}; ${result.revoked_credentials} Hosted credential(s) revoked; installed identity retained)`);
+      return;
+    }
+    case "n8n-setup": {
+      if (Object.keys(flags).length !== 0 || positional.length !== 0) {
+        throw new CliRefusal("N8N_SETUP_FLAGS_REFUSED");
+      }
+      const result = prepareN8nHook(home);
+      out("n8n automatic observation configured");
+      out(`environment ${result.env_path}`);
+      out("workflow edits none");
+      return;
+    }
+    case "version":
+    case "--version": {
+      banner();
+      return;
+    }
+    case "help":
+    case "--help":
+    case "-h": {
+      // Asking for help is a successful invocation (exit 0); only an
+      // unrecognized command is an error. Reconciles the founder clean-install
+      // rehearsal finding of 2026-08-16 (`observa --help` once exited 2).
+      usage();
+      return;
+    }
+    default:
+      usage();
+      process.exitCode = command === undefined ? 0 : 2;
+  }
+}
+
+main().catch((error) => {
+  if (error instanceof CliRefusal) {
+    err(`REFUSED ${error.code}${error.detail ? `: ${error.detail}` : ""}`);
+    process.exitCode = 1;
+    return;
+  }
+  err(`ERROR ${error.code ?? error.message}`);
+  process.exitCode = 1;
+});