@oracle-agent/oracle 0.14.1 → 0.16.0

package/src/portfolio-risk.mjs

@@ -1,170 +0,0 @@
-// Pure portfolio exposure and coverage summary. This module performs no I/O.
-
-export const DEFAULT_RISK_THRESHOLDS = Object.freeze({
-  assetHighPct: 50,
-  assetMediumPct: 25,
-  chainHighPct: 75,
-  venueHighPct: 60,
-  stablecoinHighPct: 70,
-});
-
-const STABLECOINS = new Set(["USDC", "USDT", "USDT0", "DAI", "FRAX", "LUSD", "TUSD", "USDP", "GUSD", "PYUSD", "USDE"]);
-
-function finite(value) {
-  if (value === null || value === "" || value === undefined) return null;
-  const number = Number(value);
-  return Number.isFinite(number) && number >= 0 ? number : null;
-}
-
-function rounded(value) {
-  return Math.round((value + Number.EPSILON) * 1e8) / 1e8;
-}
-
-function pct(value, total) {
-  return total > 0 ? rounded((value / total) * 100) : null;
-}
-
-function addressOf(snapshot) {
-  return snapshot.address || snapshot.owner || snapshot.walletAddress || snapshot.wallet?.address || null;
-}
-
-function labelIndex(labels) {
-  const entries = Array.isArray(labels) ? labels : Array.isArray(labels?.entries) ? labels.entries : [];
-  const index = new Map();
-  for (const entry of entries) {
-    if (!entry?.address) continue;
-    const key = String(entry.address).toLowerCase();
-    if (!index.has(key)) index.set(key, entry);
-  }
-  return index;
-}
-
-function addAsset(output, raw, context = {}) {
-  if (!raw || typeof raw !== "object") return;
-  const symbol = String(raw.symbol ?? raw.coin ?? raw.name ?? raw.collection ?? raw.tokenId ?? "unknown");
-  const value = finite(raw.usdValue ?? raw.valueUsd ?? raw.knownUsd ?? raw.estimatedValueUsd ?? raw.floorValueUsd);
-  const kind = raw.kind === "nft" || raw.type === "nft" || raw.collection || raw.tokenId != null ? "nft" : "fungible";
-  output.push({
-    symbol,
-    usdValue: value,
-    chain: String(raw.chain ?? raw.chainName ?? context.chain ?? "unknown"),
-    venue: String(raw.venue ?? raw.protocol ?? raw.platform ?? context.venue ?? "wallet"),
-    address: raw.address ?? context.address ?? null,
-    kind,
-    stablecoin: raw.stablecoin === true || STABLECOINS.has(symbol.toUpperCase()),
-  });
-}
-
-function assetsFromSnapshot(snapshot) {
-  const output = [];
-  const rootAddress = addressOf(snapshot);
-  for (const asset of snapshot.assets || snapshot.holdings || []) addAsset(output, asset, { address: rootAddress, chain: snapshot.chain, venue: snapshot.venue });
-  for (const chain of snapshot.chains || []) {
-    const chainName = chain.chain ?? chain.name ?? chain.slug ?? (chain.chainId != null ? String(chain.chainId) : chain.family) ?? "unknown";
-    const context = { address: chain.address ?? rootAddress, chain: chainName, venue: chain.venue };
-    if (chain.native && (chain.native.amount == null || Number(chain.native.amount) !== 0)) {
-      addAsset(output, { ...chain.native, symbol: chain.native.symbol ?? chain.symbol ?? chainName }, context);
-    }
-    for (const asset of chain.assets || chain.fungibleTokens?.assets || []) addAsset(output, asset, context);
-    for (const asset of chain.collectibles?.assets || chain.nfts || []) addAsset(output, { ...asset, kind: "nft" }, context);
-    for (const asset of chain.spot?.balances || []) addAsset(output, asset, { ...context, venue: "Hyperliquid spot" });
-    const accountValue = finite(chain.perps?.accountValueUsd);
-    if (accountValue != null) addAsset(output, { symbol: "perps account", usdValue: accountValue }, { ...context, venue: "Hyperliquid perps" });
-  }
-  for (const item of snapshot.inventory?.items || snapshot.nfts?.items || []) addAsset(output, { ...item, kind: "nft" }, { address: rootAddress, chain: item.chain ?? snapshot.chain, venue: item.marketplace ?? snapshot.venue });
-  return output;
-}
-
-function snapshotKey(snapshot, index) {
-  const address = addressOf(snapshot);
-  const chain = snapshot.chain ?? snapshot.chainId ?? snapshot.family ?? "*";
-  return address ? `${String(address).toLowerCase()}|${String(chain).toLowerCase()}` : `snapshot:${index}`;
-}
-
-function buckets(assets, property, total) {
-  const map = new Map();
-  for (const asset of assets) {
-    if (asset.usdValue == null) continue;
-    const name = asset[property];
-    map.set(name, (map.get(name) || 0) + asset.usdValue);
-  }
-  return [...map].map(([name, knownUsd]) => ({ name, knownUsd: rounded(knownUsd), percentOfKnown: pct(knownUsd, total) }))
-    .sort((a, b) => b.knownUsd - a.knownUsd || a.name.localeCompare(b.name));
-}
-
-/**
- * Summarize already-fetched portfolio snapshots. Accepts either
- * `{ snapshots, labels, thresholds }` or an array plus an options object.
- */
-export function summarizePortfolioRisk(input = {}, options = {}) {
-  const snapshots = Array.isArray(input) ? input : Array.isArray(input.snapshots) ? input.snapshots : input.snapshot ? [input.snapshot] : [];
-  const labels = labelIndex(options.labels ?? options.addressBook ?? input.labels ?? input.addressBook);
-  const thresholds = { ...DEFAULT_RISK_THRESHOLDS, ...(input.thresholds || {}), ...(options.thresholds || {}) };
-  const unique = [];
-  const seen = new Set();
-  let duplicatesIgnored = 0;
-  snapshots.forEach((snapshot, index) => {
-    if (!snapshot || typeof snapshot !== "object") return;
-    const key = snapshotKey(snapshot, index);
-    if (seen.has(key)) duplicatesIgnored += 1;
-    else { seen.add(key); unique.push(snapshot); }
-  });
-
-  const assets = unique.flatMap(assetsFromSnapshot);
-  const priced = assets.filter((asset) => asset.usdValue != null);
-  const unknown = assets.filter((asset) => asset.usdValue == null);
-  const explicitUnknown = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.unpricedNonzeroItems || snapshot.unpricedNonzeroItems || 0), 0);
-  const totalKnownUsd = rounded(priced.reduce((sum, asset) => sum + asset.usdValue, 0));
-  const unknownItemCount = unknown.length + explicitUnknown;
-  const chainExposures = buckets(priced, "chain", totalKnownUsd);
-  const venueExposures = buckets(priced, "venue", totalKnownUsd);
-  const groupedAssets = buckets(priced, "symbol", totalKnownUsd);
-  for (const row of chainExposures) row.chain = row.name;
-  for (const row of venueExposures) row.venue = row.name;
-  for (const row of groupedAssets) {
-    row.asset = row.name;
-    row.symbol = row.name;
-  }
-  const stablecoinKnownUsd = rounded(priced.filter((asset) => asset.stablecoin).reduce((sum, asset) => sum + asset.usdValue, 0));
-  const nftAssets = assets.filter((asset) => asset.kind === "nft");
-  const snapshotNftUnvalued = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.nftUnvaluedItems || 0), 0);
-  const nftUnvaluedItems = nftAssets.filter((asset) => asset.usdValue == null).length + snapshotNftUnvalued;
-  const nftValuedItems = nftAssets.filter((asset) => asset.usdValue != null).length;
-  const top = groupedAssets[0] || null;
-  const concentrationLevel = !top ? "unknown" : top.percentOfKnown >= thresholds.assetHighPct ? "high" : top.percentOfKnown >= thresholds.assetMediumPct ? "medium" : "low";
-  const warnings = [];
-  if (unknownItemCount) warnings.push(`${unknownItemCount} nonzero holding(s) have unknown USD value; they are excluded from totals and percentages.`);
-  if (nftUnvaluedItems) warnings.push("NFT valuation coverage is partial; estimates are not executable bids and unvalued NFTs are not treated as zero.");
-  if (duplicatesIgnored) warnings.push(`${duplicatesIgnored} duplicate address/chain snapshot(s) were ignored.`);
-  if (top && concentrationLevel !== "low") warnings.push(`Asset concentration is ${concentrationLevel}: ${top.name} is ${top.percentOfKnown}% of known value.`);
-  if (chainExposures[0]?.percentOfKnown >= thresholds.chainHighPct) warnings.push(`Chain concentration is high: ${chainExposures[0].name} is ${chainExposures[0].percentOfKnown}% of known value.`);
-  if (venueExposures[0]?.percentOfKnown >= thresholds.venueHighPct) warnings.push(`Venue concentration is high: ${venueExposures[0].name} is ${venueExposures[0].percentOfKnown}% of known value.`);
-
-  const addresses = unique.map(addressOf).filter(Boolean).map((address) => {
-    const entry = labels.get(String(address).toLowerCase());
-    return { address, label: entry?.label ?? null, who: entry?.who ?? null, role: entry?.role ?? null };
-  });
-  return {
-    totalKnownUsd,
-    coverage: {
-      complete: unique.length > 0 && unknownItemCount === 0 && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false),
-      label: unknownItemCount === 0 && unique.length && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false)
-        ? "complete for the supplied snapshots" : "known priced value only; portfolio coverage is partial or unverified",
-      unknownUsd: unknownItemCount ? null : 0,
-      pricedItemCount: priced.length,
-      unknownItemCount,
-      snapshotCount: unique.length,
-      duplicatesIgnored,
-    },
-    chainExposures,
-    venueExposures,
-    topAssets: groupedAssets.slice(0, Math.max(1, Number(options.topAssets ?? input.topAssets ?? 10))),
-    concentrationRisk: { level: concentrationLevel, topAsset: top?.name ?? null, topAssetPercent: top?.percentOfKnown ?? null, thresholds: { mediumPct: thresholds.assetMediumPct, highPct: thresholds.assetHighPct } },
-    stablecoinExposure: { knownUsd: stablecoinKnownUsd, percentOfKnown: pct(stablecoinKnownUsd, totalKnownUsd), high: totalKnownUsd > 0 && pct(stablecoinKnownUsd, totalKnownUsd) >= thresholds.stablecoinHighPct },
-    nftCoverage: { status: nftAssets.length || snapshotNftUnvalued ? (nftUnvaluedItems ? "partial" : "valued") : "not-observed", valuedItems: nftValuedItems, unvaluedItems: nftUnvaluedItems, knownUsd: rounded(nftAssets.filter((asset) => asset.usdValue != null).reduce((sum, asset) => sum + asset.usdValue, 0)) },
-    addresses,
-    warnings: [...new Set(warnings)],
-  };
-}
-
-export const portfolioRiskSummary = summarizePortfolioRisk;

package/src/prepare-envelope.mjs

@@ -1,204 +0,0 @@
-// Canonical prepare envelope shared by Oracle prepare helpers and the local operator.
-// The versioned checksum binds payload and freshness metadata. It detects mutation.
-// Optional HMAC (ORACLE_STAMP_HMAC_SECRET) adds keyed integrity when configured.
-// Signer-owned policy, not this public checksum alone, authorizes execution.
-
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-
-export const PREPARE_VERSION = 2;
-/** Default max age for a prepared envelope at sign time (ms). */
-export const PREPARE_MAX_AGE_MS = 5 * 60 * 1000;
-/**
- * Hard ceiling for maxAgeMs. Caller/agent cannot widen past this.
- * Override upward only via signer-process env ORACLE_PREPARE_HARD_MAX_AGE_MS.
- */
-export const PREPARE_HARD_MAX_AGE_MS = (() => {
-  const n = Number(process.env.ORACLE_PREPARE_HARD_MAX_AGE_MS);
-  return Number.isFinite(n) && n > 0 ? n : 30 * 60 * 1000; // 30 minutes
-})();
-
-/** Resolve max age: default 5m, never above hard max (even if caller passes MAX_SAFE_INTEGER). */
-export function resolvePrepareMaxAgeMs(requested) {
-  const base =
-    requested == null || requested === ""
-      ? PREPARE_MAX_AGE_MS
-      : Number(requested);
-  if (!Number.isFinite(base) || base < 0) return PREPARE_MAX_AGE_MS;
-  return Math.min(base, PREPARE_HARD_MAX_AGE_MS);
-}
-
-function stableStringify(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-  const keys = Object.keys(value).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
-}
-
-function secretFrom(env) {
-  const s = String(env?.ORACLE_STAMP_HMAC_SECRET || "").trim();
-  return s.length >= 16 ? s : "";
-}
-
-function stampSecret(env = process.env) {
-  // The signer process owns its policy. An options env is useful for isolated
-  // tests and unkeyed clients, but cannot shadow a real process secret.
-  return secretFrom(process.env) || secretFrom(env);
-}
-
-function requireMac(env = process.env) {
-  return String(process.env.ORACLE_STAMP_REQUIRE_MAC || "").trim() === "1" ||
-    String(env?.ORACLE_STAMP_REQUIRE_MAC || "").trim() === "1";
-}
-
-/** Fields that bind the envelope (must not include the stamp fields themselves). */
-export function prepareBodyForHash(prepared) {
-  const {
-    oraclePrepared,
-    prepareHash,
-    prepareMac,
-    note,
-    ...body
-  } = prepared || {};
-  return body;
-}
-
-export function computePrepareHash(prepared) {
-  const body = prepareBodyForHash(prepared);
-  return createHash("sha256").update(stableStringify(body)).digest("hex");
-}
-
-export function computePrepareMac(prepareHash, secret = stampSecret()) {
-  if (!secret) return "";
-  return createHmac("sha256", secret).update(String(prepareHash)).digest("hex");
-}
-
-function safeEqualHex(a, b) {
-  try {
-    const ba = Buffer.from(String(a), "hex");
-    const bb = Buffer.from(String(b), "hex");
-    if (ba.length === 0 || ba.length !== bb.length) return false;
-    return timingSafeEqual(ba, bb);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Stamp a prepare result. Call at the end of every prepare helper.
- * @param {object} payload  provider-specific prepare fields (action/tx/psbt/...)
- */
-export function stampPrepared(payload, { provider, kind, env = process.env } = {}) {
-  if (!payload || typeof payload !== "object") throw new Error("stampPrepared: payload object required");
-  const base = {
-    ...payload,
-    provider: payload.provider || provider,
-    kind: payload.kind || kind,
-    requiresUserSignature: payload.requiresUserSignature !== false,
-    signingReady: false,
-    broadcastReady: false,
-    executionReady: false,
-  };
-  if (!base.provider) throw new Error("stampPrepared: provider required");
-  if (!base.kind) throw new Error("stampPrepared: kind required");
-  const preparedAt = Date.now();
-  const expiresAt = preparedAt + PREPARE_MAX_AGE_MS;
-  const prepareVersion = PREPARE_VERSION;
-  const withMeta = { ...base, preparedAt, expiresAt, prepareVersion };
-  const prepareHash = computePrepareHash(withMeta);
-  const secret = stampSecret(env);
-  const prepareMac = secret ? computePrepareMac(prepareHash, secret) : undefined;
-  const out = {
-    ...withMeta,
-    oraclePrepared: true,
-    prepareHash,
-  };
-  if (prepareMac) out.prepareMac = prepareMac;
-  return out;
-}
-
-/**
- * Verify a prepared envelope before operator sign.
- * @throws on mismatch / expiry / missing stamp
- */
-export function assertPreparedEnvelope(prepared, {
-  maxAgeMs = PREPARE_MAX_AGE_MS,
-  nowMs = Date.now(),
-  providers = null,
-  kinds = null,
-  label = "operator",
-  env = process.env,
-} = {}) {
-  if (!prepared || typeof prepared !== "object") {
-    throw new Error(`${label}: prepared envelope object required`);
-  }
-  if (prepared.oraclePrepared !== true) {
-    throw new Error(
-      `${label}: prepared integrity envelope missing — use an @oracle-agent/oracle prepare result`,
-    );
-  }
-  if (Number(prepared.prepareVersion) !== PREPARE_VERSION) {
-    throw new Error(`${label}: unsupported prepareVersion ${prepared.prepareVersion}`);
-  }
-  const expected = computePrepareHash(prepared);
-  if (String(prepared.prepareHash || "") !== expected) {
-    throw new Error(`${label}: prepareHash mismatch — payload was altered after prepare`);
-  }
-
-  const secret = stampSecret(env);
-  const mac = String(prepared.prepareMac || "");
-  // The MAC used to be enforced only when it was PRESENT or when
-  // ORACLE_STAMP_REQUIRE_MAC=1. That is the classic optional-MAC downgrade:
-  // prepareHash is an unkeyed sha256 an attacker can recompute via the
-  // exported computePrepareHash, so stripping prepareMac and recomputing the
-  // hash let a mutated payload pass a default-posture verifier.
-  //
-  // A verifier that HOLDS the stamp secret is by definition in keyed mode, so
-  // it now requires the MAC rather than treating its absence as opt-out. An
-  // attacker can still strip the field, but they cannot forge it, and a
-  // verifier with no secret configured is unchanged (checksum-only, exactly as
-  // documented — the signer's own policy remains the authoritative wall).
-  if (requireMac(env) || mac || secret) {
-    if (!secret) {
-      throw new Error(
-        `${label}: prepareMac present or ORACLE_STAMP_REQUIRE_MAC=1 but ORACLE_STAMP_HMAC_SECRET missing in signer`,
-      );
-    }
-    const expectedMac = computePrepareMac(expected, secret);
-    if (!mac || !safeEqualHex(mac, expectedMac)) {
-      throw new Error(`${label}: prepareMac mismatch — stamp not from trusted preparer`);
-    }
-  }
-
-  const preparedAt = Number(prepared.preparedAt);
-  const expiresAt = Number(prepared.expiresAt);
-  const effectiveMax = resolvePrepareMaxAgeMs(maxAgeMs);
-  const age = nowMs - preparedAt;
-  const lifetime = expiresAt - preparedAt;
-  if (
-    !Number.isFinite(age) ||
-    !Number.isFinite(expiresAt) ||
-    !Number.isFinite(lifetime) ||
-    age < 0 ||
-    lifetime <= 0 ||
-    lifetime > PREPARE_HARD_MAX_AGE_MS ||
-    age > effectiveMax ||
-    nowMs > expiresAt
-  ) {
-    throw new Error(
-      `${label}: prepare envelope expired or clock-skewed (ageMs=${age}, max=${effectiveMax})`,
-    );
-  }
-  if (providers) {
-    const allow = new Set(providers);
-    if (!allow.has(prepared.provider)) {
-      throw new Error(`${label}: provider ${prepared.provider} not allowed here`);
-    }
-  }
-  if (kinds) {
-    const allow = new Set(kinds);
-    if (!allow.has(prepared.kind)) {
-      throw new Error(`${label}: kind ${prepared.kind} not allowed here`);
-    }
-  }
-  return true;
-}

package/src/profile-upgrade.mjs

@@ -1,277 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { randomBytes } from "node:crypto";
-import { createRequire } from "node:module";
-
-export const UPGRADE_VERSION = "oracle-profile-upgrade/v1";
-
-function exists(file) {
-  try { fs.accessSync(file); return true; } catch { return false; }
-}
-
-function snapshot(dir) {
-  if (!exists(dir)) return [];
-  return fs.readdirSync(dir, { recursive: true, withFileTypes: true })
-    .filter((entry) => entry.isFile())
-    .map((entry) => path.join(entry.parentPath || entry.path, entry.name))
-    .sort()
-    .map((file) => [path.relative(dir, file), fs.readFileSync(file)]);
-}
-
-function desiredTree(source) {
-  const files = snapshot(source);
-  files.push([".oracle-upgrade-version", Buffer.from(`${UPGRADE_VERSION}\n`)]);
-  return files.sort(([a], [b]) => a.localeCompare(b));
-}
-
-function treeMatches(dest, files) {
-  const actual = snapshot(dest);
-  return actual.length === files.length && actual.every(([name, body], i) =>
-    name === files[i][0] && body.equals(files[i][1]));
-}
-
-function tempSibling(target) {
-  return `${target}.tmp-oracle-upgrade-${process.pid}-${randomBytes(6).toString("hex")}`;
-}
-
-function backupName(target) {
-  let candidate = `${target}.bak-oracle-upgrade`;
-  for (let n = 1; exists(candidate); n += 1) candidate = `${target}.bak-oracle-upgrade-${n}`;
-  return candidate;
-}
-
-function installTree(source, dest, apply, report) {
-  if (!exists(source) || !fs.statSync(source).isDirectory()) return;
-  const files = desiredTree(source);
-  if (treeMatches(dest, files)) {
-    report.unchanged.push(dest);
-    return;
-  }
-  const wasPresent = exists(dest);
-  (wasPresent ? report.updated : report.created).push(dest);
-  if (!apply) return;
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  const tmp = tempSibling(dest);
-  let backup = null;
-  fs.mkdirSync(tmp);
-  try {
-    for (const [name, body] of files) {
-      const out = path.join(tmp, name);
-      fs.mkdirSync(path.dirname(out), { recursive: true });
-      fs.writeFileSync(out, body);
-    }
-    if (wasPresent) {
-      backup = backupName(dest);
-      fs.renameSync(dest, backup);
-      report.backups.push({ path: backup, original: dest });
-    }
-    fs.renameSync(tmp, dest);
-  } catch (error) {
-    if (exists(tmp)) fs.rmSync(tmp, { recursive: true, force: true });
-    if (backup && !exists(dest) && exists(backup)) fs.renameSync(backup, dest);
-    throw error;
-  }
-}
-
-// This deliberately accepts only the ordinary block-style YAML Hermes writes.
-// Unsupported constructs fail closed rather than risking a lossy rewrite.
-function validateYaml(text, file) {
-  if (/^mcp_servers:[ \t]*(?!\{\}[ \t]*(?:#.*)?$)\S+/m.test(text)) {
-    throw new Error(`${file}: mcp_servers must be a block mapping`);
-  }
-  const stack = [];
-  const keys = new Map();
-  const lines = text.split(/\r?\n/);
-  let flow = 0;
-  for (let index = 0; index < lines.length; index += 1) {
-    const raw = lines[index];
-    if (/^\s*#/.test(raw)) continue;
-    if (/^\s*\t|^ +\t/.test(raw)) throw new Error(`${file}:${index + 1}: tabs are not supported in YAML indentation`);
-    const line = raw.replace(/\s+#.*$/, "");
-    if (!line.trim() || /^\s*(?:---|\.\.\.)\s*$/.test(line)) continue;
-    const quoteFree = line.replace(/'(?:[^']|'')*'|"(?:[^"\\]|\\.)*"/g, "");
-    for (const char of quoteFree) {
-      if ("[{".includes(char)) flow += 1;
-      if ("]}".includes(char)) flow -= 1;
-      if (flow < 0) throw new Error(`${file}:${index + 1}: unbalanced flow collection`);
-    }
-    if (/^\s*[^#\-][^:]*:\s*(?:.*)?$/.test(line)) {
-      const indent = line.match(/^ */)[0].length;
-      const key = line.trimStart().match(/^([^:]+):/)[1].trim();
-      while (stack.length && stack.at(-1).indent >= indent) stack.pop();
-      const parent = stack.map((item) => item.key).join("/");
-      const id = `${parent}|${indent}|${key}`;
-      if (keys.has(id)) throw new Error(`${file}:${index + 1}: duplicate mapping key ${key}`);
-      keys.set(id, true);
-      if (/^[^:]+:\s*(?:#.*)?$/.test(line.trimStart())) stack.push({ indent, key });
-    } else if (!/^\s*-\s+/.test(line) && flow === 0) {
-      throw new Error(`${file}:${index + 1}: unsupported or malformed YAML`);
-    }
-  }
-  if (flow !== 0) throw new Error(`${file}: unbalanced flow collection`);
-  if (/^\s*[^#\n]*:\s*[>|][+-]?\s*$/m.test(text)) {
-    // Block scalars are safe to preserve outside mcp_servers, but editing inside
-    // one would require a complete YAML parser.
-    const mcp = topLevelBlock(text, "mcp_servers");
-    if (mcp && /:\s*[>|][+-]?\s*$/m.test(mcp.body)) throw new Error(`${file}: block scalars inside mcp_servers are unsupported`);
-  }
-}
-
-function topLevelBlock(text, name) {
-  const re = new RegExp(`^${name}:[^\\S\\r\\n]*(?:#.*)?$`, "m");
-  const match = re.exec(text);
-  if (!match) return null;
-  const start = match.index;
-  const bodyStart = text.indexOf("\n", start) + 1;
-  if (!bodyStart) return { start, end: text.length, bodyStart: text.length, body: "" };
-  const rest = text.slice(bodyStart);
-  const next = /^(?=\S[^\r\n]*:)/m.exec(rest);
-  const end = next ? bodyStart + next.index : text.length;
-  return { start, bodyStart, end, body: text.slice(bodyStart, end) };
-}
-
-function scalar(value) {
-  return JSON.stringify(value);
-}
-
-function serverBlock(name, command) {
-  const words = command.command === "node" ? [command.script] : command.args;
-  const lines = [`  ${name}:`, `    command: ${scalar(command.command)}`];
-  if (words?.length) lines.push("    args:", ...words.map((arg) => `      - ${scalar(arg)}`));
-  lines.push("    enabled: true", `    # ${UPGRADE_VERSION}`);
-  return `${lines.join("\n")}\n`;
-}
-
-function mergeMcp(text, desired) {
-  text = text.replace(
-    /^(mcp_servers:)\s*\{\}\s*(#.*)?$/m,
-    (_line, head, comment) => `${head}${comment ? ` ${comment}` : ""}`,
-  );
-  const block = topLevelBlock(text, "mcp_servers");
-  if (!block) {
-    const prefix = text.length && !text.endsWith("\n") ? "\n" : "";
-    return `${text}${prefix}mcp_servers:\n${[...desired].map(([n, c]) => serverBlock(n, c)).join("")}`;
-  }
-  let body = block.body;
-  for (const [name, command] of desired) {
-    const child = new RegExp(`^  ${name}:[^\\S\\r\\n]*(?:#.*)?\\r?\\n(?:^(?: {3,}|\\s*$).*\\r?\\n?)*`, "m");
-    const replacement = serverBlock(name, command);
-    body = child.test(body) ? body.replace(child, replacement) : `${body}${body && !body.endsWith("\n") ? "\n" : ""}${replacement}`;
-  }
-  return `${text.slice(0, block.bodyStart)}${body}${text.slice(block.end)}`;
-}
-
-function mergeEnabledPlugin(text, pluginId) {
-  text = text.replace(
-    /^(plugins:)\s*\{\}\s*(#.*)?$/m,
-    (_line, head, comment) => `${head}${comment ? ` ${comment}` : ""}`,
-  );
-  const item = `    - ${scalar(pluginId)}\n`;
-  const block = topLevelBlock(text, "plugins");
-  if (!block) {
-    const prefix = text.length && !text.endsWith("\n") ? "\n" : "";
-    return `${text}${prefix}plugins:\n  enabled:\n${item}`;
-  }
-  let body = block.body;
-  const flow = /^  enabled:\s*\[([^\]]*)\](.*)$/m.exec(body);
-  if (flow) {
-    const values = flow[1].split(",").map((value) => value.trim().replace(/^["']|["']$/g, ""));
-    if (!values.includes(pluginId)) {
-      const joined = flow[1].trim() ? `${flow[1].trimEnd()}, ${scalar(pluginId)}` : scalar(pluginId);
-      body = body.replace(flow[0], `  enabled: [${joined}]${flow[2]}`);
-    }
-  } else {
-    const sequence = /^  enabled:\s*(?:#.*)?\r?\n((?:^ {4}-.*\r?\n?)*)/m.exec(body);
-    if (sequence) {
-      const values = sequence[1].split(/\r?\n/).map((line) => line.replace(/^\s*-\s*/, "").trim().replace(/^["']|["']$/g, ""));
-      if (!values.includes(pluginId)) body = body.replace(sequence[0], `${sequence[0]}${item}`);
-    } else {
-      body = `${body}${body && !body.endsWith("\n") ? "\n" : ""}  enabled:\n${item}`;
-    }
-  }
-  return `${text.slice(0, block.bodyStart)}${body}${text.slice(block.end)}`;
-}
-
-function writeAtomic(file, body, report) {
-  const present = exists(file);
-  const old = present ? fs.readFileSync(file, "utf8") : null;
-  if (old === body) { report.unchanged.push(file); return; }
-  (present ? report.updated : report.created).push(file);
-  if (!report.applied) return;
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  if (present) {
-    const backup = backupName(file);
-    fs.copyFileSync(file, backup);
-    report.backups.push({ path: backup, original: file });
-  }
-  const tmp = tempSibling(file);
-  try {
-    fs.writeFileSync(tmp, body, { mode: present ? fs.statSync(file).mode : 0o600 });
-    fs.renameSync(tmp, file);
-  } catch (error) {
-    if (exists(tmp)) fs.rmSync(tmp, { force: true });
-    throw error;
-  }
-}
-
-function resolveControl(packageRoot, explicit) {
-  if (explicit) {
-    const [command, ...args] = explicit;
-    return { command, args };
-  }
-  const candidates = [
-    path.join(packageRoot, "bin", "oracle-control-mcp.mjs"),
-    path.join(packageRoot, "plugins", "oracle-owner-gate", "bin", "oracle-control-mcp.mjs"),
-    path.join(packageRoot, "plugins", "oracle-owner-gate", "oracle-control-mcp.mjs"),
-    // Control MCP ships with the local operator package, not the prepare-only public root.
-    path.join(packageRoot, "..", "@oracle-agent", "operator", "bin", "oracle-control-mcp.mjs"),
-    path.join(packageRoot, "..", "..", "@oracle-agent", "operator", "bin", "oracle-control-mcp.mjs"),
-  ];
-  for (const script of candidates) {
-    if (exists(script) && fs.statSync(script).isFile()) return { command: "node", script: path.resolve(script) };
-  }
-  try {
-    const require = createRequire(path.join(packageRoot, "package.json"));
-    const operatorPkg = path.dirname(require.resolve("@oracle-agent/operator/package.json"));
-    const script = path.join(operatorPkg, "bin", "oracle-control-mcp.mjs");
-    if (exists(script) && fs.statSync(script).isFile()) return { command: "node", script: path.resolve(script) };
-  } catch {}
-  return null;
-}
-
-export function upgradeProfiles({ hermesHome, packageRoot, only = null, apply = false, controlCommand = null }) {
-  const profilesRoot = path.join(hermesHome, "profiles");
-  const report = { ok: true, applied: apply, version: UPGRADE_VERSION, hermesHome, packageRoot, profiles: [], created: [], updated: [], unchanged: [], backups: [] };
-  let profiles = exists(profilesRoot) ? fs.readdirSync(profilesRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort() : [];
-  if (only) profiles = profiles.filter((name) => name === only);
-  if (only && profiles.length === 0) throw new Error(`profile not found: ${only}`);
-  report.profiles = profiles;
-
-  // Validate every selected config before planning or performing any write.
-  const configs = new Map();
-  for (const profile of profiles) {
-    const file = path.join(profilesRoot, profile, "config.yaml");
-    const text = exists(file) ? fs.readFileSync(file, "utf8") : "";
-    validateYaml(text, file);
-    configs.set(profile, text);
-  }
-
-  const skillSource = path.join(packageRoot, "skills", "oracle-action-semantics");
-  if (!exists(skillSource)) throw new Error(`required Oracle skill is missing: ${skillSource}`);
-  const pluginSource = path.join(packageRoot, "plugins", "oracle-owner-gate");
-  const control = resolveControl(packageRoot, controlCommand);
-  const dataScript = path.join(packageRoot, "bin", "oracle-data-mcp.mjs");
-  if (!exists(dataScript)) throw new Error(`oracle-data MCP command is missing: ${dataScript}`);
-
-  for (const profile of profiles) {
-    const root = path.join(profilesRoot, profile);
-    installTree(skillSource, path.join(root, "skills", "oracle-action-semantics"), apply, report);
-    if (exists(pluginSource)) installTree(pluginSource, path.join(root, "plugins", "oracle-owner-gate"), apply, report);
-    const desired = new Map([["oracle-data", { command: "node", script: dataScript }]]);
-    if (control) desired.set("oracle-control", control);
-    let config = mergeMcp(configs.get(profile), desired);
-    if (exists(pluginSource)) config = mergeEnabledPlugin(config, "oracle-owner-gate");
-    writeAtomic(path.join(root, "config.yaml"), config, report);
-  }
-  return report;
-}