@oracle-agent/oracle 0.4.2 → 0.5.0

package/scripts/check-doc-drift.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Release gate: shipped prose must not contradict shipped behavior.
+//
+// Why this exists. The 2026-08-01 four-model audit found the same stale claim
+// in 20 places across both packages: docs said the unattended signer was
+// limited to `hl` and `poly` long after six bounded surfaces had shipped. The
+// worst instances were not READMEs — they were `profiles/oracle/SOUL.md` and
+// `skills/oracle-action-semantics/SKILL.md`, which are read by the MODEL. An
+// agent told that EVM daemon execution is impossible reasons incorrectly about
+// its own authority, and no test suite can see a false sentence.
+//
+// This scans every doc surface that ships in the tarball, including model-facing
+// SOUL and skill text, which is exactly where drift hides longest.
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+const failures = [];
+
+// Claims that shipped in a real release and are now false.
+const STALE_CLAIMS = [
+  { re: /limited\s+to\s+`?hl`?\s+and\s+`?poly`?/i, why: "says the unattended signer is limited to hl+poly" },
+  { re: /only\s+`?hl`?\s+and\s+`?poly`?\s+are\s+enabled/i, why: "says only hl+poly are daemon-enabled" },
+  { re: /daemon\s+surfaces\s+remain\s+`?hl`?\s+and\s+`?poly`?/i, why: "freezes the surface list at hl+poly" },
+  { re: /policy-bounded\s+`?hl`?\s+and\s+`?poly`?\s+only/i, why: "restricts the daemon to hl+poly" },
+  { re: /agent-facing\s+daemon\s+supports\s+only\s+policy-bounded\s+Hyperliquid\s+and\s+Polymarket\s+execution/i, why: "says the agent-facing daemon supports only Hyperliquid+Polymarket" },
+  { re: /`?evm`?,?\s+`?btc`?,?\s+and\s+`?sol`?\s+fail\s+closed\s+at\s+the\s+daemon/i, why: "claims evm/btc/sol are refused at the daemon" },
+  { re: /EVM,\s*BTC,?\s*and\s+Solana\s+are\s+not\s+daemon\s+surfaces/i, why: "denies evm/btc/sol are daemon surfaces" },
+  { re: /companion\s+daemon\s+is\s+`?hl`?\s*\/\s*`?poly`?[- ]only/i, why: "describes the companion daemon as hl/poly-only" },
+  { re: /daemon\s+supports\s+only\s+policy-bounded\s+Hyperliquid\s+and\s+Polymarket/i, why: "describes the daemon as Hyperliquid/Polymarket-only" },
+  { re: /unattended\s+signer\s+remains\s+`?hl`?\s*\/\s*`?poly`?/i, why: "freezes the generic signer at hl/poly" },
+  { re: /supports\s+autonomous\s+Hyperliquid\s+and\s+Polymarket\s+execution/i, why: "describes the daemon as Hyperliquid/Polymarket-only" },
+  { re: /\(HL\s*\+\s*Poly,\s*capped\)/i, why: "documents autosign as hl/poly-only" },
+  { re: /policy-bounded\s+HL\s*\/\s*Polymarket\s+exec/i, why: "documents the signer daemon as hl/poly-only" },
+  { re: /policy-bounded\s+daemon\s+surfaces:\s*hl\s*\|\s*poly\s*$/i, why: "documents only two of six daemon surfaces" },
+  { re: /ORACLE_SIGNER_SURFACES=hl,poly\s*$/i, why: "quickstart freezes ORACLE_SIGNER_SURFACES at hl,poly" },
+  { re: /ORACLE_AUTONOMOUS_TRADING=1.*(?:or\s+run\s+the\s+signer\s+daemon|same(?:-tier)?).*oracle-signer/i, why: "frames direct exec and oracle-signer as equivalent agent paths" },
+  { re: /(?:or\s+run\s+the\s+signer\s+daemon|same(?:-tier)?).*oracle-signer.*ORACLE_AUTONOMOUS_TRADING=1/i, why: "frames direct exec and oracle-signer as equivalent agent paths" },
+];
+
+// Version pins that go stale the moment a release ships. The audit found the
+// quickstart advertising 0.3.6/0.6.1 inside a 0.4.0 tarball, so a copy-paste
+// install handed users an older wall set.
+function checkVersionPins(rel, text) {
+  const lines = text.split("\n");
+  lines.forEach((line, i) => {
+    const pin = line.match(/@oracle-agent\/oracle@(\d+\.\d+\.\d+)/);
+    if (pin && pin[1] !== pkg.version) {
+      failures.push(
+        `${rel}:${i + 1} pins @oracle-agent/oracle@${pin[1]} but this package is ${pkg.version}\n    ${line.trim().slice(0, 120)}`,
+      );
+    }
+    const latest = line.match(/Latest:.*oracle\s+`(\d+\.\d+\.\d+)`/i);
+    if (latest && latest[1] !== pkg.version) {
+      failures.push(
+        `${rel}:${i + 1} advertises oracle ${latest[1]} as latest but this package is ${pkg.version}\n    ${line.trim().slice(0, 120)}`,
+      );
+    }
+  });
+}
+
+// Every markdown surface that ships to a user or a model.
+function docFiles() {
+  const out = [];
+  for (const rel of ["README.md", "SETUP.md", "SECURITY.md"]) {
+    if (existsSync(path.join(root, rel))) out.push(rel);
+  }
+  for (const dir of ["docs", "profiles", "skills"]) {
+    const abs = path.join(root, dir);
+    if (!existsSync(abs)) continue;
+    const walk = (d) => {
+      for (const entry of readdirSync(d)) {
+        const full = path.join(d, entry);
+        if (statSync(full).isDirectory()) walk(full);
+        else if (entry.endsWith(".md")) out.push(path.relative(root, full));
+      }
+    };
+    walk(abs);
+  }
+  return out;
+}
+
+const files = docFiles();
+for (const rel of files) {
+  const text = readFileSync(path.join(root, rel), "utf8");
+  text.split("\n").forEach((line, i) => {
+    for (const claim of STALE_CLAIMS) {
+      if (claim.re.test(line)) {
+        failures.push(`${rel}:${i + 1} ${claim.why}\n    ${line.trim().slice(0, 140)}`);
+      }
+    }
+  });
+  checkVersionPins(rel, text);
+}
+
+console.log(`package version: ${pkg.version}`);
+console.log(`doc surfaces scanned: ${files.length} (README/SETUP/SECURITY + docs/ + profiles/ + skills/)`);
+console.log("");
+
+if (failures.length) {
+  console.error(`FAIL — ${failures.length} doc/code drift finding(s):\n`);
+  for (const f of failures) console.error(`  ${f}\n`);
+  console.error("Shipped prose contradicts shipped behavior. Model-facing SOUL/skill text counts:");
+  console.error("an agent that reads a false capability claim reasons wrongly about its own authority.");
+  process.exit(1);
+}
+
+console.log("PASS — no stale capability claims or version pins in shipped docs");

package/src/cli/commands/credential.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "credential",
+  summary: "OS credential store glue",
+  group: "sign",
+  usage: "oracle credential <get|set|delete> ...",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-credential", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/data-mcp.mjs

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { spawnChild } from "../spawn-child.mjs";
+
+export default {
+  name: "data-mcp",
+  summary: "start the read-only data MCP server",
+  group: "read",
+  usage: "oracle data-mcp",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-data-mcp.mjs");
+    return spawnChild(
+      process.execPath,
+      [bin, ...ctx.argv],
+      { stdio: "inherit", env: process.env },
+      "oracle-data-mcp",
+    );
+  },
+};

package/src/cli/commands/data.mjs

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { spawnChild } from "../spawn-child.mjs";
+
+const DEFAULT_DATA_URL = "http://127.0.0.1:8787";
+
+function usage() {
+  process.stderr.write(
+    "usage: oracle data <serve|call|catalog|health> [args]\n" +
+      "  oracle data serve [--port N]\n" +
+      "  oracle data call <provider> <op> [--args '<json>']\n" +
+      "  oracle data catalog\n" +
+      "  oracle data health\n",
+  );
+}
+
+async function dataFetch(pathname, { method = "GET", body } = {}) {
+  const base = (process.env.ORACLE_DATA_URL || DEFAULT_DATA_URL).replace(/\/$/, "");
+  const url = base + pathname;
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: body ? { "content-type": "application/json" } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+    return res.ok ? 0 : 1;
+  } catch (err) {
+    if (err && (err.code === "ECONNREFUSED" || /fetch failed|ECONNREFUSED/i.test(String(err)))) {
+      process.stderr.write("oracle: data server not running — start it with 'oracle data serve'\n");
+      return 4;
+    }
+    process.stderr.write(`oracle data: ${err.message || err}\n`);
+    return 1;
+  }
+}
+
+export default {
+  name: "data", summary: "desk data plane", group: "read",
+  usage: "oracle data serve|call|catalog|health",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (!verb || verb === "--help" || verb === "-h") { usage(); return verb ? 0 : 1; }
+    if (verb === "serve") {
+      let port = null;
+      try {
+        const { values } = parseArgs({ args: ctx.argv.slice(1), options: { port: { type: "string" } }, allowPositionals: true, strict: false });
+        port = values.port || null;
+      } catch {}
+      const env = { ...process.env };
+      if (port) env.ORACLE_DATA_PORT = String(port);
+      const bin = path.join(ctx.root, "bin", "desk-server.mjs");
+      return spawnChild(process.execPath, [bin], { stdio: "inherit", env }, "desk-server");
+    }
+    if (verb === "health") return dataFetch("/");
+    if (verb === "catalog") return dataFetch("/data/catalog");
+    if (verb === "call") {
+      const provider = ctx.argv[1];
+      const op = ctx.argv[2];
+      if (!provider || !op) { usage(); return 1; }
+      let argsObj = {};
+      const i = ctx.argv.indexOf("--args");
+      if (i >= 0) {
+        try { argsObj = JSON.parse(ctx.argv[i + 1] || "{}"); }
+        catch (err) { process.stderr.write(`oracle data call: invalid --args JSON: ${err.message}\n`); return 1; }
+      }
+      return dataFetch("/data/call", { method: "POST", body: { provider, op, args: argsObj } });
+    }
+    usage();
+    return 1;
+  },
+};

package/src/cli/commands/doctor.mjs

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DOCTOR_SIGNING_OPTIONAL } from "../first-run.mjs";
+
+function nodeVersionOk() {
+  const [maj, min] = process.versions.node.split(".").map(Number);
+  return maj > 20 || (maj === 20 && min >= 19);
+}
+
+function loadExecEnv(p) {
+  if (!fs.existsSync(p)) return {};
+  const out = {};
+  for (const line of fs.readFileSync(p, "utf8").split(/\r?\n/)) {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (m) out[m[1]] = m[2];
+  }
+  return out;
+}
+
+function which(bin) {
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    const c = path.join(dir, bin);
+    try { if (fs.existsSync(c)) return c; } catch {}
+  }
+  return null;
+}
+
+async function probeDataServer(url) {
+  try {
+    const res = await fetch(url.replace(/\/$/, "") + "/");
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export default {
+  name: "doctor",
+  summary: "check read plane; checks signer too when installed",
+  group: "read",
+  usage: "oracle doctor [--json]",
+  async run(ctx) {
+    const json = ctx.argv.includes("--json");
+    const checks = [];
+    let failed = false;
+    const push = (id, status, detail, fix = null) => {
+      checks.push({ id, status, detail, fix });
+      if (status === "fail") failed = true;
+    };
+
+    push("node", nodeVersionOk() ? "ok" : "fail", `node ${process.versions.node}`,
+      nodeVersionOk() ? null : "install node >= 20.19");
+
+    const execEnvPath = ctx.paths.oracleExecEnvPath();
+    const envFile = loadExecEnv(execEnvPath);
+    const att =
+      process.env.ORACLE_ATTESTATION_SECRET ||
+      process.env.ORACLE_STAMP_HMAC_SECRET ||
+      envFile.ORACLE_ATTESTATION_SECRET ||
+      envFile.ORACLE_STAMP_HMAC_SECRET;
+    push("attestation_secret", att ? "ok" : "warn", att ? "present" : "missing",
+      att ? null : "run oracle init --apply (writes ~/.config/oracle/exec.env)");
+
+    const dataUrl = process.env.ORACLE_DATA_URL || "http://127.0.0.1:8787";
+    const dataUp = await probeDataServer(dataUrl);
+    push("data_server", dataUp ? "ok" : "warn", dataUp ? `reachable ${dataUrl}` : `down ${dataUrl}`,
+      dataUp ? null : "oracle data serve");
+
+    const hermes = which("hermes");
+    push("hermes_cli", hermes ? "ok" : "warn", hermes ? `present ${hermes}` : "not on PATH",
+      hermes ? null : "install Hermes if you want agent lanes");
+
+    const profilesDir = path.join(ctx.paths.hermesRoot(), "profiles");
+    let laneCount = 0;
+    if (fs.existsSync(profilesDir)) {
+      laneCount = fs.readdirSync(profilesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
+    }
+    push("hermes_lanes", laneCount > 0 ? "ok" : "warn",
+      laneCount > 0 ? `${laneCount} profile dir(s)` : "no lane profiles found",
+      laneCount > 0 ? null : "oracle init --apply");
+
+    const operator = ctx.resolveOperator();
+    let operatorBlock = { installed: false };
+    if (operator.ok) {
+      const r = ctx.dispatchOperator("oracle-agentic-doctor", ["--json"], { stdio: "pipe" });
+      let detail = { installed: true, version: operator.version, source: operator.source };
+      if (r && typeof r === "object" && r.stdout) {
+        try {
+          const parsed = JSON.parse(r.stdout);
+          detail = {
+            installed: true,
+            version: operator.version,
+            source: operator.source,
+            signingReady: parsed.signingReady,
+            broadcastReady: parsed.broadcastReady,
+            executionReady: parsed.executionReady,
+            masterKillSwitch: parsed.masterKillSwitch,
+            raw: parsed,
+          };
+        } catch {
+          detail.doctorParseError = true;
+          detail.doctorExit = r.code;
+        }
+      } else if (typeof r === "number") {
+        detail.doctorExit = r;
+      }
+      operatorBlock = detail;
+      const signingReady = detail.signingReady === true;
+      push(
+        "signing",
+        signingReady ? "ok" : "warn",
+        signingReady
+          ? `operator ${operator.version} ready via ${operator.source}`
+          : `operator ${operator.version} installed but signing is not ready`,
+        signingReady ? null : "oracle sign doctor --json",
+      );
+    }
+
+    const report = { ok: !failed, checks, operator: operatorBlock };
+    if (json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    } else {
+      for (const c of checks) {
+        process.stdout.write(`${c.status.toUpperCase().padEnd(4)} ${c.id}: ${c.detail}\n`);
+        if (c.fix) process.stdout.write(`     fix: ${c.fix}\n`);
+      }
+      if (!operator.ok) process.stdout.write(`INFO ${DOCTOR_SIGNING_OPTIONAL}\n`);
+    }
+    return failed ? 1 : 0;
+  },
+};

package/src/cli/commands/help.mjs

@@ -0,0 +1,7 @@
+export default {
+  name: "help",
+  summary: "show command help",
+  group: "meta",
+  usage: "oracle help [noun]",
+  async run() { return 0; },
+};

package/src/cli/commands/init.mjs

@@ -0,0 +1,27 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { renderNextSteps } from "../first-run.mjs";
+
+export default {
+  name: "init",
+  summary: "install agent lanes + read plane (dry-run by default)",
+  group: "read",
+  usage: "oracle init [--apply --force --only <lane> --json --yes]",
+  async run(ctx) {
+    const argv = [...ctx.argv];
+    if (argv.includes("--yes") && !argv.includes("--apply")) argv.push("--apply");
+    const bin = path.join(ctx.root, "bin", "oracle-init.mjs");
+    const r = spawnSync(process.execPath, [bin, ...argv], { encoding: "utf8", env: process.env });
+    if (r.error) {
+      process.stderr.write(`oracle: failed to spawn oracle-init: ${r.error.message}\n`);
+      return 1;
+    }
+    if (r.stdout) process.stdout.write(r.stdout);
+    if (r.stderr) process.stderr.write(r.stderr);
+    const code = typeof r.status === "number" ? r.status : 1;
+    if (code === 0 && argv.includes("--apply") && !argv.includes("--json")) {
+      process.stdout.write(renderNextSteps());
+    }
+    return code;
+  },
+};

package/src/cli/commands/mcp.mjs

@@ -0,0 +1,142 @@
+import { parseArgs } from "node:util";
+import { printOperatorNotInstalled } from "../operator-dispatch.mjs";
+import { installClaudeCode } from "../mcp-targets/claude-code.mjs";
+import { installClaudeDesktop } from "../mcp-targets/claude-desktop.mjs";
+import { installCodex } from "../mcp-targets/codex.mjs";
+import { installChatgpt } from "../mcp-targets/chatgpt.mjs";
+import { buildServerSpecs } from "../mcp-targets/shared.mjs";
+
+function usage() {
+  process.stderr.write(
+    "usage: oracle mcp <install|print> [target] [flags]\n" +
+      "  targets: claude-code | claude-desktop | codex | chatgpt | generic\n" +
+      "  flags:   --with-control --project --print --json\n",
+  );
+}
+
+function emitResult(result, { json = false } = {}) {
+  if (result.print && !result.instructions) {
+    process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+  } else if (result.printText) {
+    process.stdout.write(result.printText);
+  }
+  if (result.instructions) {
+    process.stdout.write(result.instructions + "\n");
+    if (result.print && json) process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+  }
+  if (!result.print && !result.printText && !result.instructions) {
+    const line = {
+      status: result.status,
+      path: result.path || null,
+      backup: result.backup || null,
+      method: result.method || null,
+    };
+    process.stdout.write(
+      (json ? JSON.stringify(line, null, 2) : `${line.status}${line.path ? " " + line.path : ""}`) + "\n",
+    );
+  }
+}
+
+export default {
+  name: "mcp",
+  summary: "wire Oracle into AI clients",
+  group: "read",
+  usage: "oracle mcp install <target> | oracle mcp print [--target <t>]",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (!verb || verb === "--help" || verb === "-h") {
+      usage();
+      return verb ? 0 : 1;
+    }
+
+    let values, positionals;
+    try {
+      ({ values, positionals } = parseArgs({
+        args: ctx.argv.slice(1),
+        options: {
+          "with-control": { type: "boolean", default: false },
+          project: { type: "boolean", default: false },
+          print: { type: "boolean", default: false },
+          json: { type: "boolean", default: false },
+          target: { type: "string" },
+        },
+        allowPositionals: true,
+        strict: false,
+      }));
+    } catch (err) {
+      process.stderr.write(`oracle mcp: ${err.message}\n`);
+      usage();
+      return 1;
+    }
+
+    const withControl = !!values["with-control"];
+    const project = !!values.project;
+    const json = !!values.json;
+    const operator = ctx.resolveOperator ? ctx.resolveOperator() : { ok: false };
+
+    if (withControl && (!operator || !operator.ok)) {
+      printOperatorNotInstalled(process.stderr);
+      return 3;
+    }
+
+    const opts = { oracleRoot: ctx.root, operator, withControl, project, cwd: process.cwd() };
+
+    if (verb === "print") {
+      const target = values.target || positionals[0] || "claude-code";
+      if (target === "generic" || target === "claude-code") {
+        const built = buildServerSpecs(opts);
+        if (!built.ok) { printOperatorNotInstalled(process.stderr); return 3; }
+        process.stdout.write(JSON.stringify({ mcpServers: built.specs }, null, 2) + "\n");
+        return 0;
+      }
+      if (target === "chatgpt") {
+        const r = await installChatgpt({ printOnly: true });
+        emitResult(r, { json });
+        return 0;
+      }
+      if (target === "codex") {
+        emitResult(await installCodex({ ...opts, printOnly: true }), { json });
+        return 0;
+      }
+      if (target === "claude-desktop") {
+        emitResult(await installClaudeDesktop({ ...opts, printOnly: true }), { json });
+        return 0;
+      }
+      process.stderr.write(`oracle mcp: unknown target '${target}'\n`);
+      return 1;
+    }
+
+    if (verb === "install") {
+      const target = positionals[0] || values.target;
+      if (!target) { usage(); return 1; }
+      const printOnly = !!values.print;
+      let result;
+      if (target === "claude-code") result = await installClaudeCode({ ...opts, printOnly });
+      else if (target === "claude-desktop") result = await installClaudeDesktop({ ...opts, printOnly });
+      else if (target === "codex") result = await installCodex({ ...opts, printOnly });
+      else if (target === "chatgpt") result = await installChatgpt({ printOnly });
+      else if (target === "generic") {
+        const built = buildServerSpecs(opts);
+        if (!built.ok) { printOperatorNotInstalled(process.stderr); return 3; }
+        process.stdout.write(JSON.stringify({ mcpServers: built.specs }, null, 2) + "\n");
+        return 0;
+      } else {
+        process.stderr.write(`oracle mcp: unknown target '${target}'\n`);
+        return 1;
+      }
+      if (!result.ok) {
+        if (result.code === 3) printOperatorNotInstalled(process.stderr);
+        else process.stderr.write(`oracle mcp: ${result.reason || "failed"}\n`);
+        return result.code || 1;
+      }
+      emitResult(result, { json });
+      if (result.status && String(result.status).startsWith("printed") && result.print) {
+        process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+      }
+      return 0;
+    }
+
+    usage();
+    return 1;
+  },
+};

package/src/cli/commands/prepare.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "prepare", summary: "build an unsigned swap (alias of route prepare)", group: "read",
+  usage: "oracle prepare <chain> <tokenIn> <tokenOut> <taker> [amt]",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-route.mjs");
+    const r = spawnSync(process.execPath, [bin, "prepare", ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-route: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/public.mjs

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { spawnChild } from "../spawn-child.mjs";
+export default {
+  name: "public", summary: "secret-free public HTTP surface", group: "read",
+  usage: "oracle public serve [--port N]",
+  async run(ctx) {
+    const verb = ctx.argv[0] || "serve";
+    if (verb !== "serve") { process.stderr.write("usage: oracle public serve [--port N]\n"); return 1; }
+    let port = null;
+    try {
+      const { values } = parseArgs({ args: ctx.argv.slice(1), options: { port: { type: "string" } }, allowPositionals: true, strict: false });
+      port = values.port || null;
+    } catch {}
+    const env = { ...process.env };
+    if (port) env.ORACLE_PUBLIC_PORT = String(port);
+    const bin = path.join(ctx.root, "bin", "oracle-public-server.mjs");
+    return spawnChild(process.execPath, [bin], { stdio: "inherit", env }, "oracle-public-server");
+  },
+};

package/src/cli/commands/route.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "route", summary: "swap/bridge prepare helpers", group: "read",
+  usage: "oracle route <swap|bridge|prepare|prepare-bridge> ...",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-route.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-route: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/runner.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "runner",
+  summary: "action runner daemon",
+  group: "sign",
+  usage: "oracle runner [--interval-ms N ...]",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-runner", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/scan.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "scan", summary: "chain scanner", group: "read",
+  usage: "oracle scan <chains|head|token|pools|risk|quote|sell> ...",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-scan.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-scan: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/sign.mjs

@@ -0,0 +1,21 @@
+export default {
+  name: "sign",
+  summary: "provision / check the local signer (opt-in)",
+  group: "sign",
+  usage: "oracle sign <init|doctor> ...",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (verb === "init") {
+      return ctx.dispatchOperator("oracle-agentic-init", ctx.argv.slice(1), { appendHintOnError: true });
+    }
+    if (verb === "doctor") {
+      return ctx.dispatchOperator("oracle-agentic-doctor", ctx.argv.slice(1), { appendHintOnError: true });
+    }
+    process.stderr.write(
+      "usage: oracle sign <init|doctor> ...\n" +
+        "  oracle sign init      provision keys + policy (interactive)\n" +
+        "  oracle sign doctor    check local signer readiness\n",
+    );
+    return 1;
+  },
+};

package/src/cli/commands/signer.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "signer",
+  summary: "loopback signer daemon",
+  group: "sign",
+  usage: "oracle signer [--port N ...]",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-signer", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/upgrade.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "upgrade", summary: "upgrade installed Hermes lanes", group: "read",
+  usage: "oracle upgrade [--apply ...]",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-upgrade.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-upgrade: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/vault.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "vault",
+  summary: "encrypt local key files at rest",
+  group: "sign",
+  usage: "oracle vault <encrypt|rekey|inspect|decrypt> ...",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-vault", ctx.argv, { appendHintOnError: true });
+  },
+};