@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/cli/commands/doctor.mjs

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DOCTOR_SIGNING_OPTIONAL } from "../first-run.mjs";
+import { resolveHermes } from "../runtime.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;
+}
+
+
+async function probeDataServer(url) {
+  try {
+    // The server serves /health; / intentionally 404s with a route list, so
+    // probing / reported a healthy server as down.
+    const res = await fetch(url.replace(/\/$/, "") + "/health");
+    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);
+    // `oracle init --apply` writes ORACLE_ROUTE_ATTESTATION_SECRET (see
+    // bin/oracle-init.mjs), but doctor checked only ORACLE_ATTESTATION_SECRET
+    // and ORACLE_STAMP_HMAC_SECRET — so it told the user to rerun an init step
+    // that could never satisfy the check.
+    const att =
+      process.env.ORACLE_ROUTE_ATTESTATION_SECRET ||
+      process.env.MAD_ROUTE_ATTESTATION_SECRET ||
+      process.env.ORACLE_ATTESTATION_SECRET ||
+      process.env.ORACLE_STAMP_HMAC_SECRET ||
+      envFile.ORACLE_ROUTE_ATTESTATION_SECRET ||
+      envFile.MAD_ROUTE_ATTESTATION_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 runtime = resolveHermes();
+    push("agent_runtime", runtime.ok ? "ok" : "warn",
+      runtime.ok ? `present ${runtime.bin} (${runtime.source})` : "not installed",
+      runtime.ok ? null : "oracle bootstrap");
+
+    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/equities.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * Crossbook product surface.
+ *
+ * Separate protocol product (tokenized / on-chain equities best execution across
+ * HIP-3, Arcus, RH Uniswap, Solana xStocks, TON), shipped inside the Oracle CLI
+ * so one install reaches it. Prepare-only; never signs.
+ */
+export default {
+  name: "equities",
+  summary: "Crossbook — HIP-3 / Arcus / RH / Solana / TON best execution",
+  group: "read",
+  usage: "oracle equities <venues|quote|prepare> [ticker] [flags]",
+  async run(ctx) {
+    if (ctx.argv.includes("-h") || ctx.argv.includes("--help") || ctx.argv.length === 0) {
+      process.stdout.write(`Crossbook — separate Oracle product for on-chain equities best execution
+
+Venues: HIP-3 builder DEXes · Arcus spot/perp · RH Uniswap (4663) · Solana xStocks · TON ston.fi
+Custody: prepare-only. Quote-only winners are never sold as signable here.
+Only rh_uniswap can emit an unsigned tx (your wallet signs).
+
+Usage:
+  oracle equities venues
+  oracle equities quote NVDA --size 1000
+  oracle equities quote SPY --size 500 --json
+  oracle equities prepare NVDA --recipient 0xYourWallet --size 1000
+
+Alias bin: oracle-equities
+`);
+      return 0;
+    }
+    const bin = ctx.bin("oracle-equities.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) {
+      process.stderr.write(`oracle: failed to spawn oracle-equities: ${r.error.message}\n`);
+      return 1;
+    }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/farm.mjs

@@ -0,0 +1,129 @@
+import { FARMING_METHODS, discoverFarms, airdropEV } from "../../data/providers/farming.mjs";
+
+const USAGE = `oracle farm <methods|discover|airdrop> [options]
+
+  oracle farm methods                       list the delta-aware farming playbooks
+  oracle farm methods --id stable-loop      full setup/exposure/hedge/monitor/exit for one method
+  oracle farm discover [--chain base]       rank live pools by net APR after costs and risk haircut
+                       [--limit 12] [--min-tvl 2000000] [--json]
+  oracle farm airdrop  [--wallets 5] [--tasks-weekly 6] [--hours-weekly 4]
+                       [--hourly-cost 25] [--gas-per-task 0.4] [--bridge-monthly 12]
+                       [--expected-reward 900] [--probability 22]
+                       [--sybil-haircut 25] [--lockup-months 6] [--json]
+
+Read-only. Ranks opportunities and designs prepare plans; never signs or broadcasts.`;
+
+function parseFlags(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--json") { out.json = true; continue; }
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) { out[key] = true; continue; }
+      out[key] = next;
+      i += 1;
+      continue;
+    }
+    out._.push(arg);
+  }
+  return out;
+}
+
+const usd = (n) => `$${Math.round(Number(n) || 0).toLocaleString("en-US")}`;
+const pct = (n) => `${(Number(n) || 0).toFixed(1)}%`;
+
+function printMethods(flags) {
+  const id = typeof flags.id === "string" ? flags.id : null;
+  if (id) {
+    const method = FARMING_METHODS.find((m) => m.id === id);
+    if (!method) {
+      process.stderr.write(`oracle farm: unknown method '${id}'. Known: ${FARMING_METHODS.map((m) => m.id).join(", ")}\n`);
+      return 1;
+    }
+    if (flags.json) { process.stdout.write(JSON.stringify(method, null, 2) + "\n"); return 0; }
+    process.stdout.write(`\n  ${method.label}  [${method.risk}]  target delta ${method.targetDelta}\n\n`);
+    for (const [label, key] of [["setup", "setup"], ["exposure", "exposure"], ["hedge", "hedge"], ["monitor", "monitor"], ["exit", "exit"]]) {
+      process.stdout.write(`  ${label.padEnd(9)} ${method[key]}\n`);
+    }
+    process.stdout.write("\n");
+    return 0;
+  }
+  if (flags.json) { process.stdout.write(JSON.stringify(FARMING_METHODS, null, 2) + "\n"); return 0; }
+  process.stdout.write("\n  farming methods\n\n");
+  for (const m of FARMING_METHODS) {
+    process.stdout.write(`  ${m.id.padEnd(18)} ${m.label.padEnd(30)} ${m.risk}\n`);
+  }
+  process.stdout.write("\n  oracle farm methods --id <id> for setup, exposure, hedge, monitor, and exit rules.\n\n");
+  return 0;
+}
+
+async function printDiscover(flags) {
+  const result = await discoverFarms({
+    chain: typeof flags.chain === "string" ? flags.chain : null,
+    limit: flags.limit,
+    minTvl: flags["min-tvl"],
+  });
+  if (flags.json) { process.stdout.write(JSON.stringify(result, null, 2) + "\n"); return 0; }
+  if (!result.live) {
+    process.stderr.write(`oracle farm: discovery unavailable — ${result.error}\n`);
+    return 1;
+  }
+  process.stdout.write(`\n  live farm discovery — ${result.source}, ${result.considered.toLocaleString("en-US")} pools considered (${result.consideredNote}), chain=${result.chain}\n\n`);
+  process.stdout.write(`  ${"verdict".padEnd(10)}${"net apr".padStart(9)}  ${"tvl".padStart(12)}  ${"chain".padEnd(12)}${"recipe".padEnd(18)}pool\n`);
+  for (const c of result.candidates) {
+    process.stdout.write(
+      `  ${c.verdict.padEnd(10)}${pct(c.netApr).padStart(9)}  ${usd(c.tvlUsd).padStart(12)}  ${c.chain.slice(0, 11).padEnd(12)}${c.recipe.padEnd(18)}${c.label}\n`,
+    );
+  }
+  process.stdout.write(`\n  net apr = apy − borrow − funding − gas − risk haircut.\n  ${result.posture}.\n\n`);
+  return 0;
+}
+
+function printAirdrop(flags) {
+  const ev = airdropEV({
+    wallets: flags.wallets,
+    tasksWeekly: flags["tasks-weekly"],
+    hoursWeekly: flags["hours-weekly"],
+    hourlyCost: flags["hourly-cost"],
+    gasPerTask: flags["gas-per-task"],
+    bridgeMonthly: flags["bridge-monthly"],
+    expectedReward: flags["expected-reward"],
+    probability: flags.probability,
+    sybilHaircut: flags["sybil-haircut"],
+    lockupMonths: flags["lockup-months"],
+  });
+  if (flags.json) { process.stdout.write(JSON.stringify(ev, null, 2) + "\n"); return 0; }
+  const i = ev.inputs;
+  process.stdout.write(`\n  airdrop expected value\n\n`);
+  process.stdout.write(`  ${i.wallets} wallets · ${i.tasksWeekly} tasks/wk · ${i.hoursWeekly} hrs/wk @ ${usd(i.hourlyCost)}/hr\n`);
+  process.stdout.write(`  ${pct(i.probabilityPct)} eligibility · ${pct(i.sybilHaircutPct)} sybil haircut · ${i.lockupMonths}mo lockup\n\n`);
+  process.stdout.write(`  monthly cost      ${usd(ev.monthlyCost).padStart(12)}   (gas ${usd(ev.monthlyGas)} + labor ${usd(ev.laborMonthly)} + bridges ${usd(i.bridgeMonthly)})\n`);
+  process.stdout.write(`  gross EV          ${usd(ev.grossExpectedValue).padStart(12)}\n`);
+  process.stdout.write(`  after haircuts    ${usd(ev.adjustedExpectedValue).padStart(12)}   (lockup discount ${(ev.lockupDiscount * 100).toFixed(0)}%)\n`);
+  process.stdout.write(`  net EV            ${usd(ev.netExpectedValue).padStart(12)}   ${ev.verdict}\n`);
+  if (ev.roiPct != null) process.stdout.write(`  ROI               ${pct(ev.roiPct).padStart(12)}\n`);
+  if (ev.breakevenProbabilityPct != null) {
+    process.stdout.write(`  breakeven odds    ${pct(ev.breakevenProbabilityPct).padStart(12)}   campaign must clear this to profit\n`);
+  }
+  process.stdout.write(`\n  ${ev.posture}.\n\n`);
+  return 0;
+}
+
+export default {
+  name: "farm",
+  summary: "farming methods, live farm discovery, airdrop EV",
+  group: "read",
+  usage: USAGE,
+  async run(ctx) {
+    const flags = parseFlags(ctx.argv);
+    const sub = flags._[0];
+    if (!sub || sub === "help") { process.stdout.write(USAGE + "\n"); return 0; }
+    if (sub === "methods") return printMethods(flags);
+    if (sub === "discover") return printDiscover(flags);
+    if (sub === "airdrop") return printAirdrop(flags);
+    process.stderr.write(`oracle farm: unknown subcommand '${sub}'\n\n${USAGE}\n`);
+    return 1;
+  },
+};

package/src/cli/commands/fees.mjs

@@ -0,0 +1,109 @@
+import { readFileSync, existsSync } from "node:fs";
+import {
+  holderBalance,
+  isAddress,
+  LOCALS_ONLY_CONTRACT,
+  LOCALS_ONLY_CHAIN_ID,
+} from "../../licensing/locals-only.mjs";
+import { oracleExecEnvPath } from "../paths.mjs";
+
+const HELP = `oracle fees — Oracle fee-waiver status
+
+  oracle fees status            check the configured agent wallet
+  oracle fees check <address>   check any address
+  oracle fees info              show the Locals Only collection
+
+Oracle is public to everyone. A Locals Only NFT only waives Oracle's integrator
+fee. This command reads balanceOf on HyperEVM; it does not sign or request keys.`;
+
+export function agentAddress(envPath = oracleExecEnvPath()) {
+  if (!existsSync(envPath)) return null;
+  try {
+    const body = readFileSync(envPath, "utf8");
+    for (const line of body.split("\n")) {
+      const match = line.match(/^\s*(?:export\s+)?ORACLE_EVM_ADDRESS\s*=\s*(.+)\s*$/);
+      if (!match) continue;
+      const value = match[1].trim().replace(/^["']|["']$/g, "");
+      if (isAddress(value)) return value;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function line(out, text) {
+  out.write(text + "\n");
+}
+
+export async function run(argv = [], io = {}) {
+  const out = io.out ?? process.stdout;
+  const err = io.err ?? process.stderr;
+  const balanceOf = io.balanceOf ?? holderBalance;
+  const sub = argv[0];
+
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    line(out, HELP);
+    return 0;
+  }
+
+  if (sub === "info") {
+    line(out, `contract: ${LOCALS_ONLY_CONTRACT}`);
+    line(out, `chain:    HyperEVM (${LOCALS_ONLY_CHAIN_ID})`);
+    line(out, "benefit:  0% Oracle integrator fee");
+    line(out, "access:   public to everyone");
+    return 0;
+  }
+
+  let address;
+  if (sub === "status") {
+    address = io.agentAddress ? io.agentAddress() : agentAddress();
+    if (!address) {
+      line(out, "wallet: not configured");
+      line(out, "Locals Only fee-waiver status: unavailable");
+      line(out, "standard Oracle fee applies when configured");
+      line(out, "Oracle access remains public to everyone.");
+      return 0;
+    }
+  } else if (sub === "check") {
+    address = argv[1];
+    if (!isAddress(address)) {
+      line(err, "usage: oracle fees check <0x address>");
+      return 2;
+    }
+  } else {
+    line(err, `oracle fees: unknown subcommand '${sub}'`);
+    return 2;
+  }
+
+  try {
+    const balance = await balanceOf(address);
+    line(out, `wallet: ${address}`);
+    if (BigInt(balance) > 0n) {
+      line(out, `Locals Only balance: ${balance}`);
+      line(out, "Oracle integrator fee: 0%");
+    } else {
+      line(out, "Locals Only balance: 0");
+      line(out, "standard Oracle fee applies when configured");
+    }
+    line(out, "Oracle access remains public to everyone.");
+    return 0;
+  } catch {
+    line(out, "Locals Only fee-waiver status: unavailable");
+    line(out, "standard Oracle fee applies when configured");
+    line(out, "Oracle access remains public to everyone.");
+    return 0;
+  }
+}
+
+export const help = "check Locals Only zero-fee eligibility";
+
+export default {
+  name: "fees",
+  summary: "check Locals Only zero-fee eligibility",
+  group: "read",
+  usage: HELP,
+  async run(ctx) {
+    return run(ctx.argv ?? []);
+  },
+};

package/src/cli/commands/follow.mjs

@@ -0,0 +1,130 @@
+import { followWallet, DEFAULT_ENDPOINTS } from "../../data/providers/wallet-watch.mjs";
+import { resolveName, ADDRESS_RE } from "../../data/names.mjs";
+
+const CHAIN_NAMES = { 1: "ethereum", 8453: "base", 42161: "arbitrum" };
+const NAME_TO_ID = Object.fromEntries(Object.entries(CHAIN_NAMES).map(([id, n]) => [n, Number(id)]));
+
+const USAGE = `oracle follow <name-or-address> [--chain <name>] [--blocks <n>] [--json]
+
+  oracle follow vitalik.eth
+  oracle follow demi.hl --chain base
+  oracle follow 0x4d47b6757afd42c3dbd9691b71b43d74afa4b6b2 --blocks 20000 --json
+
+Reads ERC20 transfer activity for a wallet. Read-only: this calls
+eth_getLogs and eth_blockNumber and nothing else, so it can never move funds.
+
+Chains: ${Object.values(CHAIN_NAMES).join(", ")}. Default: ethereum.
+Lookback defaults to 40000 blocks. Endpoints are keyless.
+
+Note publicnode-class RPCs are deliberately excluded: they retain only ~128
+blocks, so they return an empty result instead of an error.`;
+
+function flagValue(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function fmtValue(v) {
+  const s = String(v ?? "");
+  return s.length > 22 ? `${s.slice(0, 19)}...` : s;
+}
+
+async function runFollow(argv = []) {
+  const asJson = argv.includes("--json");
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--json") continue;
+    if (a === "--chain" || a === "--blocks") { i += 1; continue; }
+    positional.push(a);
+  }
+  const query = (positional[0] || "").trim();
+
+  if (!query || query === "--help" || query === "-h") {
+    process.stdout.write(`${USAGE}\n`);
+    return query ? 0 : 1;
+  }
+
+  const chainArg = (flagValue(argv, "--chain") || "ethereum").toLowerCase();
+  const chainId = NAME_TO_ID[chainArg] ?? Number(chainArg);
+  if (!DEFAULT_ENDPOINTS[chainId]) {
+    process.stderr.write(`follow: unsupported chain "${chainArg}". Supported: ${Object.values(CHAIN_NAMES).join(", ")}\n`);
+    return 1;
+  }
+
+  const blocksArg = flagValue(argv, "--blocks");
+  const lookbackBlocks = blocksArg ? Number(blocksArg) : 40000;
+  if (!Number.isFinite(lookbackBlocks) || lookbackBlocks <= 0) {
+    process.stderr.write(`follow: --blocks must be a positive number, got "${blocksArg}"\n`);
+    return 1;
+  }
+
+  try {
+    // A name is a fine way to name a wallet, so resolve it the same way
+    // `oracle resolve` does rather than making the user paste hex.
+    let address = query;
+    let resolvedFrom = null;
+    if (!ADDRESS_RE.test(query)) {
+      const hit = await resolveName(query);
+      if (!hit?.address) {
+        process.stderr.write(`follow: could not resolve "${query}" to an address\n`);
+        return 1;
+      }
+      address = hit.address;
+      resolvedFrom = query;
+    }
+
+    const result = await followWallet(address, {
+      chains: [chainId],
+      lookback: lookbackBlocks,
+      onWarn: asJson ? undefined : (m) => process.stderr.write(`  warn: ${m}\n`),
+    });
+
+    const events = result.events || [];
+    if (asJson) {
+      process.stdout.write(`${JSON.stringify({
+        address,
+        resolvedFrom,
+        chain: CHAIN_NAMES[chainId] || String(chainId),
+        lookbackBlocks,
+        count: events.length,
+        errors: result.errors || [],
+        events,
+      })}\n`);
+      return 0;
+    }
+
+    const label = resolvedFrom ? `${resolvedFrom}  ${address}` : address;
+    process.stdout.write(`${label}\n`);
+    process.stdout.write(`  ${CHAIN_NAMES[chainId] || chainId} · last ${lookbackBlocks} blocks · ${events.length} transfer${events.length === 1 ? "" : "s"}\n`);
+
+    if (!events.length) {
+      // Empty is a scoped result, not proof the wallet is idle.
+      process.stdout.write(`  no ERC20 transfers in this window\n`);
+    }
+    for (const e of events.slice(0, 25)) {
+      const dir = e.to?.toLowerCase() === address.toLowerCase() ? "in " : "out";
+      process.stdout.write(`  ${dir} blk ${e.blockNumber}  token ${e.token}  ${fmtValue(e.value)}\n`);
+    }
+    if (events.length > 25) {
+      process.stdout.write(`  ... ${events.length - 25} more (use --json for all)\n`);
+    }
+    for (const err of result.errors || []) {
+      process.stderr.write(`  error: ${err.stage || "rpc"}: ${err.error}\n`);
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`follow failed: ${err?.message || err}\n`);
+    return 1;
+  }
+}
+
+export default {
+  name: "follow",
+  summary: "read a wallet's recent ERC20 transfer activity",
+  group: "read",
+  usage: USAGE,
+  async run(ctx) {
+    return runFollow(ctx.argv || []);
+  },
+};

package/src/cli/commands/harness.mjs

@@ -0,0 +1,63 @@
+// oracle harness — detect installed agent harnesses on this machine.
+//
+// Scans PATH for Agent Plugins-compatible clients, shows which ones
+// Oracle can delegate to. Native standalone is always the default.
+//
+// Commands:
+//   oracle harness detect             scan PATH, print installed harnesses
+//   oracle harness list               same as detect (alias)
+
+import { detectInstalledHarnesses } from "../../tui/backend.mjs";
+
+function usage() {
+  return [
+    "oracle harness — detect installed agent harnesses",
+    "",
+    "  oracle harness detect    scan PATH for Agent Plugins-compatible clients",
+    "",
+    "Oracle runs natively. If you prefer a different harness,",
+    "set ORACLE_CHAT_BACKEND=<name>.",
+    "",
+    "Detected: opencode, claude, codex, cursor, windsurf, aider, continue, hermes",
+  ].join("\n");
+}
+
+export default {
+  name: "harness",
+  summary: "detect installed agent harnesses",
+  usage,
+  async run(args, _ctx) {
+    const sub = args[0];
+    if (sub === "help" || sub === "--help" || sub === "-h") {
+      process.stdout.write(usage() + "\n");
+      return 0;
+    }
+    if (sub && sub !== "detect" && sub !== "list") {
+      process.stderr.write(`oracle harness: unknown subcommand '${sub}'\n`);
+      process.stderr.write(usage() + "\n");
+      return 1;
+    }
+
+    const harnesses = detectInstalledHarnesses();
+
+    if (harnesses.length === 0) {
+      process.stderr.write("No agent harnesses detected on PATH.\n");
+      process.stderr.write("Oracle runs natively — no external agent required.\n");
+      return 0;
+    }
+
+    const native = harnesses.find(h => h.kind === "oracle");
+    const others = harnesses.filter(h => h.kind !== "oracle");
+
+    process.stdout.write("\nOracle native chat: default\n\n");
+    process.stdout.write("Installed harnesses:\n");
+    for (const h of others) {
+      process.stdout.write(`  ${h.label.padEnd(22)} ${h.path}\n`);
+    }
+    if (others.length === 0) {
+      process.stdout.write("  (none — Oracle runs standalone)\n");
+    }
+    process.stdout.write(`\nSet ORACLE_CHAT_BACKEND=<name> to use a different harness.\n`);
+    return 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 = ctx.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;
+  },
+};