elanous 0.2.42 → 0.2.44

package/graphs/overlays/README.md

@@ -1,5 +1,11 @@
 # 오버레이 — 「기본 템플릿을 «언제·어떻게» 변형하나」
 
+## ARG-PROMOTE rehearsal
+
+`graph promote evaluate --fixture <json> --json` evaluates an **injected fixture only**. It checks at least five same-trigger adaptation runs, a same-trigger baseline, a landing-rate gain of at least 20 percentage points, seven days of comparative evidence, and a subsequent seven-day shadow interval whose observations are accepted. The result is marked `mockOnly: true`; an eligible result is a proposal object with `promoted_from`, evidence, rollback guidance, and the ELA-53 human patent-review reminder. This command never writes an overlay, changes a profile, opens a PR, or lands anything. Production promotion still requires independently observed evidence and an L0 human-reviewed PR.
+
+The fixture event shape is `{ runId, timestamp, trigger, phase, landed?, shadowAccepted? }`, where `phase` is `adaptation`, `baseline`, or `shadow`. Fixture counts are rehearsal evidence only and must not be copied into production evidence as real runs.
+
 대표 지시(2026-09-08): *「최초 결정 시 템플릿을 변형하고, 실제 구현 간 다이나믹 대응으로 바꿀 수 있게」*
 
 ## ⛔ 층이 «셋»이고 각 층이 바꿀 수 있는 것이 «다르다»

package/graphs/overlays/examples/research-runtime-empty-terminal.yaml

@@ -0,0 +1,28 @@
+overlay_id: research-runtime-empty-terminal
+target: research-loop
+stage: runtime
+applies_when: attempts >= 1
+patch:
+  - op: add
+    path: /nodes/-
+    value:
+      node_id: source-audit
+      kind: judge
+      recipe: observe-only
+      max_visits: 1
+      contract:
+        inputs: [worktree]
+        tools: read-only
+        outputs: [findings]
+  - op: add
+    path: /edges/-
+    value:
+      from: judge
+      on: outcome
+      map:
+        source-missing: source-audit
+  - op: add
+    path: /edges/-
+    value:
+      from: source-audit
+      to: merge

package/graphs/profiles/local.yaml

@@ -0,0 +1,5 @@
+profile_id: local
+applies_when: substrate == local
+state:
+  substrate: local
+overlays: []

package/graphs/profiles/pod.yaml

@@ -0,0 +1,4 @@
+profile_id: pod
+applies_when: substrate == pod
+state: { substrate: pod }
+overlays: []

package/graphs/release/release-loop.yaml

@@ -21,6 +21,7 @@ nodes:
   # Public export is checked before expensive prefetch/gate work; a leak stops the release immediately.
   - { node_id: export-check, kind: gate, recipe: 'cmd:export-check', max_visits: 1 }
   - { node_id: prefetch, kind: agent, recipe: 'cmd:docs', max_visits: 1 }
+  - { node_id: pre-gate-join, kind: gate, recipe: none, max_visits: 1 }
   - { node_id: gate, kind: gate, recipe: 'cmd:gate', max_visits: 1, notify: { on: [fail] } }
   # Deterministic, best-effort traffic transition; it never changes the release verdict.
   - { node_id: traffic-gate-passed, kind: gate, recipe: 'cmd:traffic-gate-passed', max_visits: 1 }
@@ -28,6 +29,7 @@ nodes:
   - { node_id: gate-triage, kind: judge, recipe: 'cmd:gate-triage', max_visits: 1 }
   - { node_id: mac-smoke, kind: gate, recipe: 'cmd:mac-smoke', max_visits: 1 }
   - { node_id: pwa, kind: gate, recipe: 'cmd:pwa', max_visits: 1, notify: { on: [fail] } }
+  - { node_id: pre-prepare-join, kind: gate, recipe: none, max_visits: 1 }
   - { node_id: prepare, kind: agent, recipe: 'cmd:prepare', max_visits: 1, notify: { on: [fail] } }
   - { node_id: upgrade, kind: gate, recipe: 'cmd:upgrade', max_visits: 1 }
   - { node_id: tui, kind: gate, recipe: 'cmd:docs', max_visits: 1 }
@@ -44,13 +46,13 @@ nodes:
   - { node_id: npm-publish, kind: git, recipe: 'cmd:npm-publish', max_visits: 1 }
   - { node_id: traffic-npm-published, kind: gate, recipe: 'cmd:traffic-npm-published', max_visits: 1 }
   - { node_id: docs-land, kind: git, recipe: 'cmd:docs-land', max_visits: 1 }
+  - { node_id: release-post-publish-join, kind: gate, recipe: none, max_visits: 1 }
   - { node_id: verify, kind: gate, recipe: 'cmd:verify', max_visits: 1, notify: { on: [ok, fail] } }
   - { node_id: traffic-verify-complete, kind: gate, recipe: 'cmd:traffic-verify-complete', max_visits: 1 }
   - { node_id: vault-note, kind: gate, recipe: 'cmd:vault-note', max_visits: 1 }
   - { node_id: release-story, kind: gate, recipe: 'cmd:release-story', max_visits: 1 }
   - { node_id: ops-upgrade, kind: agent, recipe: 'cmd:ops-upgrade', max_visits: 1 }
   - { node_id: version-dev-bump, kind: git, recipe: 'cmd:version-dev-bump', max_visits: 1 }
-  - { node_id: version-dev-bump-after-failure, kind: git, recipe: 'cmd:version-dev-bump', max_visits: 1 }
   - { node_id: traffic-failed-restore, kind: gate, recipe: 'cmd:traffic-failed-restore', max_visits: 1 }
   - { node_id: done, kind: gate, max_visits: 1 }
   - { node_id: failed, kind: gate, max_visits: 1 }
@@ -58,18 +60,29 @@ edges:
   - { from: version-release, on: outcome, map: { ok: traffic-cut-start, fail: failed, error: failed } }
   # Advisory traffic writes report failure to OP; release steps still proceed on fail/error.
   - { from: traffic-cut-start, on: outcome, map: { ok: cutoff, fail: cutoff, error: cutoff } }
-  - { from: cutoff, on: outcome, map: { ok: checklist-gate, fail: traffic-failed-restore, error: traffic-failed-restore } }
-  - { from: checklist-gate, on: outcome, map: { ok: export-check, fail: traffic-failed-restore, error: traffic-failed-restore } }
-  - { from: export-check, on: outcome, map: { ok: prefetch, fail: traffic-failed-restore, error: traffic-failed-restore } }
-  # Prefetch never gates: even a crashed prefetch node is a cache miss — the late nodes take their original paths.
-  - { from: prefetch, on: outcome, map: { ok: gate, fail: gate, error: gate } }
+  - { from: cutoff, on: outcome, map: { ok: export-check, fail: traffic-failed-restore, error: traffic-failed-restore } }
+  - from: export-check
+    on: outcome
+    map: { fail: traffic-failed-restore, error: traffic-failed-restore }
+    # This single edge launches checklist-gate and prefetch concurrently; the join routes checklist failures to restore.
+    branches: { ok: [checklist-gate, prefetch] }
+    warning_branches: [prefetch]
+    join: pre-gate-join
+  # Export is required before fanout; checklist and prefetch then run together, with prefetch warning-only.
+  - { from: pre-gate-join, on: outcome, map: { ok: gate, fail: traffic-failed-restore, error: traffic-failed-restore } }
   - { from: gate, on: outcome, map: { ok: traffic-gate-passed, fail: gate-triage, error: gate-triage } }
   # Warning-only: the transition result stays truthful; every outcome continues to the next release node.
-  - { from: traffic-gate-passed, on: outcome, map: { ok: mac-smoke, fail: mac-smoke, error: mac-smoke } }
+  - from: traffic-gate-passed
+    on: outcome
+    branches:
+      ok: [mac-smoke, pwa]
+      fail: [mac-smoke, pwa]
+      error: [mac-smoke, pwa]
+    warning_branches: [mac-smoke]
+    join: pre-prepare-join
   - { from: gate-triage, on: outcome, map: { ok: traffic-failed-restore, fail: traffic-failed-restore, error: traffic-failed-restore } }
   # Warning-only: a macOS failure or unmeasured run never blocks publishing — auto-approve shows it as a warning row.
-  - { from: mac-smoke, on: outcome, map: { ok: pwa, fail: pwa, error: pwa } }
-  - { from: pwa, on: outcome, map: { ok: prepare, fail: traffic-failed-restore, error: traffic-failed-restore } }
+  - { from: pre-prepare-join, on: outcome, map: { ok: prepare, fail: traffic-failed-restore, error: traffic-failed-restore } }
   - { from: prepare, on: outcome, map: { ok: upgrade, fail: traffic-failed-restore, error: traffic-failed-restore } }
   - { from: upgrade, on: outcome, map: { ok: tui, fail: traffic-failed-restore, error: traffic-failed-restore } }
   - { from: tui, on: outcome, map: { ok: docs, fail: traffic-failed-restore, error: traffic-failed-restore } }
@@ -84,16 +97,19 @@ edges:
   - { from: publish, on: outcome, map: { ok: npm-publish, fail: traffic-failed-restore, error: traffic-failed-restore } }
   - { from: npm-publish, on: outcome, map: { ok: traffic-npm-published, fail: traffic-failed-restore, error: traffic-failed-restore } }
   # Publication already happened; a traffic write failure must not skip docs-land.
-  - { from: traffic-npm-published, on: outcome, map: { ok: docs-land, fail: docs-land, error: docs-land } }
-  # RELEASE-DEVBUMP-ALWAYS: after a successful publish every fail/error routes through version-dev-bump —
-  # a published release always hands main to its own next -dev, then still finishes failed.
-  - { from: docs-land, on: outcome, map: { ok: verify, fail: version-dev-bump-after-failure, error: version-dev-bump-after-failure } }
-  - { from: verify, on: outcome, map: { ok: traffic-verify-complete, fail: version-dev-bump-after-failure, error: version-dev-bump-after-failure } }
+  # After npm publish these writes have independent ledgers and run together; the join keeps either result and gates verify.
+  - from: traffic-npm-published
+    on: outcome
+    branches:
+      ok: [docs-land, version-dev-bump]
+      fail: [docs-land, version-dev-bump]
+      error: [docs-land, version-dev-bump]
+    join: release-post-publish-join
+  - { from: release-post-publish-join, on: outcome, map: { ok: verify, fail: traffic-failed-restore, error: traffic-failed-restore } }
+  - { from: verify, on: outcome, map: { ok: traffic-verify-complete, fail: traffic-failed-restore, error: traffic-failed-restore } }
   - { from: traffic-verify-complete, on: outcome, map: { ok: vault-note, fail: vault-note, error: vault-note } }
   # Warning-only: vault note and release story failures after publication never block operational upgrades.
   - { from: vault-note, on: outcome, map: { ok: release-story, fail: release-story, error: release-story } }
   - { from: release-story, on: outcome, map: { ok: ops-upgrade, fail: ops-upgrade, error: ops-upgrade } }
-  - { from: ops-upgrade, on: outcome, map: { ok: version-dev-bump, fail: version-dev-bump, error: version-dev-bump } }
-  - { from: version-dev-bump, on: outcome, map: { ok: done, fail: traffic-failed-restore, error: traffic-failed-restore } }
-  - { from: version-dev-bump-after-failure, on: outcome, map: { ok: traffic-failed-restore, fail: traffic-failed-restore, error: traffic-failed-restore } }
+  - { from: ops-upgrade, on: outcome, map: { ok: done, fail: done, error: done } }
   - { from: traffic-failed-restore, on: outcome, map: { ok: failed, fail: failed, error: failed } }

package/graphs/units/verbs/make-doc.yaml

@@ -32,3 +32,4 @@ edges:
   - from: document-draft
     on: outcome
     map: { done: done, rework: rework, needs-human: needs-human, failed: failed }
+    fallback: [{ node: failed, requires: [] }]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elanous",
   "mcpName": "io.github.ElanvitalAI/elanous",
-  "version": "0.2.42",
+  "version": "0.2.44",
   "description": "Self-healing coding harness where eyes, hands, and memory all turn on one sentence — it authors its own goals, implements them in isolated worktrees, and reviews its own work.",
   "license": "Apache-2.0",
   "author": "Elanvital AI",
@@ -60,6 +60,7 @@
     "prepack": "bun -e \"import { writePackagedRevision } from './src/version/code-revision.ts'; writePackagedRevision()\"",
     "postpack": "bun -e \"import { rmSync } from 'node:fs'; rmSync('src/version/packed-revision.json', { force: true })\"",
     "dev": "bun run src/index.ts",
+    "catalog:build": "bun run scripts/build-signed-catalog.ts",
     "build": "bun build src/index.ts --outdir dist --target bun",
     "sync": "bun run src/index.ts sync",
     "status": "bun run src/index.ts status",
@@ -104,6 +105,7 @@
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "diff": "^9.0.0",
+    "google-auth-library": "^10.6.2",
     "libsodium-wrappers": "^0.8.4",
     "mammoth": "^1.12.0",
     "mermaidtui": "^0.0.5",
@@ -125,9 +127,11 @@
     "yaml": "^2.8.3"
   },
   "optionalDependencies": {
-    "node-pty": "^1.1.0",
     "telegram": "^2.26.22"
   },
+  "elanousOptionalIntegrations": {
+    "node-pty": "^1.1.0"
+  },
   "devDependencies": {
     "@copilotkit/aimock": "1.45.1",
     "@types/bun": "^1.2.0",

package/plugins/demo-absorption-briefing/plugin.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "demo-absorption-briefing",
+  "version": "0.1.0",
+  "description": "Absorption briefing scene package: topic subscriptions, scheduled runs, issue briefs, and reopen follow-up.",
+  "extensions": {
+    "ai.elanous": {
+      "connectors": [
+        { "id": "exa", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "EXA_API_KEY" }] },
+        { "id": "firecrawl", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "FIRECRAWL_API_KEY" }] },
+        { "id": "xai", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "XAI_API_KEY" }] },
+        { "id": "telegram", "required": false, "fields": [{ "name": "botToken", "secret": true, "env": "ELANOUS_TELEGRAM_BOT_TOKEN" }] },
+        { "id": "telegram-chat", "required": false, "fields": [{ "name": "chatId", "secret": false, "env": "ELANOUS_TELEGRAM_CHAT_ID" }] },
+        { "id": "linear", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "LINEAR_API_KEY" }] }
+      ]
+    }
+  }
+}

package/plugins/demo-absorption-briefing/skills/demo-absorption-briefing/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: demo-absorption-briefing
+description: Subscribe an issue to the existing scheduled topic-briefing flow and report its status.
+---
+
+# Absorption briefing
+
+Use the existing `eln intake source` commands to inspect, add, and run topic sources. Keep scheduled execution and issue delivery on the existing intake pipeline. Report the source id and delivery result; do not invent findings when search providers are unavailable.

package/plugins/demo-browser-hand/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "demo-browser-hand",
+  "version": "0.1.0",
+  "description": "Browser hand scene package: navigation, capture, bypass guidance, and human interaction handoff.",
+  "extensions": {
+    "ai.elanous": {
+      "connectors": [
+        { "id": "linear", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "LINEAR_API_KEY" }] }
+      ]
+    }
+  }
+}

package/plugins/demo-browser-hand/skills/demo-browser-hand/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: demo-browser-hand
+description: Navigate and inspect web pages with the existing browser tools, handing off when a person must act.
+---
+
+# Browser hand
+
+Use the existing `BrowserOpen`, `BrowserNavigate`, `BrowserRead`, `BrowserScreenshot`, and `BrowserClose` tools. Ask the user to complete authentication, consent, or other human-only steps in the browser when required. Do not claim a page changed unless a fresh read confirms it.

package/plugins/demo-linear-secretary/plugin.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "demo-linear-secretary",
+  "version": "0.1.0",
+  "description": "Linear secretary scene package: issue creation, sub-issues, comments, checklists, and progress sync.",
+  "extensions": {
+    "ai.elanous": {
+      "connectors": [
+        { "id": "linear", "required": true, "fields": [{ "name": "apiKey", "secret": true, "env": "LINEAR_API_KEY" }] },
+        { "id": "telegram", "required": false, "fields": [{ "name": "botToken", "secret": true, "env": "ELANOUS_TELEGRAM_BOT_TOKEN" }] },
+        { "id": "telegram-chat", "required": false, "fields": [{ "name": "chatId", "secret": false, "env": "ELANOUS_TELEGRAM_CHAT_ID" }] }
+      ]
+    }
+  }
+}

package/plugins/demo-linear-secretary/skills/demo-linear-secretary/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: demo-linear-secretary
+description: Create and maintain Linear issues through the existing Elanous Linear secretary tool.
+---
+
+# Linear secretary
+
+Use the existing `elanous_linear_secretary` tool for issue creation, child issues, comments, checklists, and progress synchronization. Confirm the selected Linear project before creating issues. Never put API keys in issue text, comments, or tool arguments other than the configured connector.

package/plugins/demo-plugin-wizard/plugin.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "demo-plugin-wizard",
+  "version": "0.1.0",
+  "description": "Plugin wizard scene package: search a marketplace, install packages, develop with Claude or Codex, and use the result.",
+  "extensions": {
+    "ai.elanous": {
+      "connectors": []
+    }
+  }
+}

package/plugins/demo-plugin-wizard/skills/demo-plugin-wizard/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: demo-plugin-wizard
+description: Search, install, and use plugins with existing Elanous plugin commands.
+---
+
+# Plugin wizard
+
+Use `eln plugin market` to inspect configured marketplaces, `eln plugin add` to install a package, and `eln plugin make` to create a local graph plugin. Keep marketplace trust and capability consent visible; report the exact plugin id and version after installation. Claude Code and GitHub CLI authentication use their existing login flows, not API-key prompts.

package/plugins/demo-research/plugin.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "demo-research",
+  "version": "0.1.0",
+  "description": "Research scene package: Exa and Firecrawl search, Grok coverage, research turn guidance, and Bloom defaults.",
+  "extensions": {
+    "ai.elanous": {
+      "connectors": [
+        { "id": "exa", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "EXA_API_KEY" }] },
+        { "id": "firecrawl", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "FIRECRAWL_API_KEY" }] },
+        { "id": "xai", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "XAI_API_KEY" }] },
+        { "id": "tavily", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "TAVILY_API_KEY" }] }
+      ]
+    }
+  }
+}

package/plugins/demo-research/skills/demo-research/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: demo-research
+description: Research a question using the existing Elanous research command and available search providers.
+---
+
+# Research
+
+Use the existing `eln research` command or built-in research tools. Let the command select the configured providers, cite source URLs, and keep unverified claims marked as unknown. Exa, Firecrawl, Grok, and Tavily are optional connectors; a missing provider must not be described as a broken install.

package/plugins/demo-video-briefing/plugin.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "demo-video-briefing",
+  "version": "0.1.0",
+  "description": "Video briefing scene package: turn a decision memo into a short video and deliver it.",
+  "extensions": {
+    "ai.elanous": {
+      "connectors": [
+        { "id": "elevenlabs", "required": false, "fields": [{ "name": "apiKey", "secret": true, "env": "ELEVENLABS_API_KEY" }] },
+        { "id": "telegram", "required": false, "fields": [{ "name": "botToken", "secret": true, "env": "ELANOUS_TELEGRAM_BOT_TOKEN" }] },
+        { "id": "telegram-chat", "required": false, "fields": [{ "name": "chatId", "secret": false, "env": "ELANOUS_TELEGRAM_CHAT_ID" }] }
+      ]
+    }
+  }
+}

package/plugins/demo-video-briefing/skills/demo-video-briefing/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: demo-video-briefing
+description: Turn a decision memo into a short video with the existing Elanous explainer-video engine.
+---
+
+# Video briefing
+
+Use the existing explainer-video skill and engine to draft, render, and inspect the short briefing. The local renderer works without an external video key. ElevenLabs and Telegram are optional connectors; do not report delivery unless the existing sender confirms it.

package/scripts/bench-metering-plan.ts

@@ -0,0 +1,229 @@
+#!/usr/bin/env bun
+/** Validate that a paired benchmark has measurement sources and private sinks planned.
+ * This checks the plan only: it never launches arms, reads credentials, or claims measurements. */
+import { readFile } from 'node:fs/promises';
+
+export type BenchProvider = 'openrouter' | 'bedrock' | 'elanous' | 'claude-code';
+
+export interface BenchMetricSource {
+  readonly collector: string;
+  readonly evidenceRef: string;
+  readonly region?: string;
+  readonly windowStartUtc?: string;
+  readonly windowEndUtc?: string;
+}
+
+export interface BenchArmMeteringPlan {
+  readonly armId: string;
+  readonly provider: BenchProvider;
+  /** Product/agent identity is separate from the provider that supplies billing. */
+  readonly agent?: 'elanous' | 'claude-code' | 'provider-arm';
+  readonly billingProvider: string;
+  readonly noAutoMerge: boolean;
+  readonly metrics: Readonly<Record<string, BenchMetricSource | BenchMetricDisposition>>;
+}
+
+export interface BenchMetricDisposition {
+  readonly status: 'not-applicable' | 'estimated' | 'unmeasured';
+  readonly reason: string;
+  readonly evidenceRef: string;
+}
+
+export interface BenchMeteringPlan {
+  readonly schemaVersion: 1;
+  readonly runId: string;
+  readonly promptSha256: string;
+  readonly baseSha: string;
+  readonly installedPin: string;
+  readonly arms: readonly BenchArmMeteringPlan[];
+  readonly sealed: {
+    readonly directory: string;
+    readonly directoryMode: string;
+    readonly unblindKey: string;
+    readonly meteringReceipt: string;
+    readonly fileMode: string;
+  };
+  readonly publicFields: readonly string[];
+}
+
+export interface BenchMeteringPlanCheck {
+  readonly readyToMeasure: boolean;
+  readonly metricsMeasured: false;
+  readonly armsLaunched: 0;
+  readonly issues: readonly string[];
+}
+
+const SHA256 = /^[0-9a-f]{64}$/i;
+const COMMIT = /^[0-9a-f]{40}$/i;
+const PROVIDER_PAIR_METRICS = [
+  'actualProvider',
+  'actualModel',
+  'rounds',
+  'inputTokens',
+  'outputTokens',
+  'elapsedMs',
+  'humanInterventions',
+  'actualChargeUsd',
+  'creditDelta',
+] as const;
+const COMPARISON_METRICS = [
+  'actualProvider', 'actualModel', 'rounds', 'inputTokens', 'outputTokens',
+  'toolCalls', 'elapsedMs', 'humanInterventions',
+] as const;
+const BEDROCK_METRICS = ['awsInvocationCount'] as const;
+const PRIVATE_PUBLIC_FIELDS = /^(armId|provider|billingProvider|model|actualProvider|actualModel|elapsedMs|durationMs|humanInterventions|toolCalls|actualChargeUsd|estimatedChargeUsd|creditDelta|awsInvocationCount|accountId|region)$/i;
+const SECRET_PROPERTY = /^(api[_-]?key|(?:secret|access)[_-]?(?:access)?key(?:id)?|authorization|password|credential|token)$/i;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function scanSecretPropertyNames(value: unknown, path = '$'): string[] {
+  if (Array.isArray(value)) return value.flatMap((entry, index) => scanSecretPropertyNames(entry, `${path}[${index}]`));
+  if (!record(value)) return [];
+  return Object.entries(value).flatMap(([key, nested]) => [
+    ...(SECRET_PROPERTY.test(key) ? [`${path}.${key}: credentials are not allowed in a measurement plan`] : []),
+    ...scanSecretPropertyNames(nested, `${path}.${key}`),
+  ]);
+}
+
+function validSource(value: unknown): value is BenchMetricSource {
+  const usableRef = (candidate: unknown): candidate is string => typeof candidate === 'string'
+    && candidate.trim().length > 0
+    && !/^(pending|tbd|unknown|n\/a)$/i.test(candidate.trim());
+  return record(value) && usableRef(value.collector) && usableRef(value.evidenceRef);
+}
+
+function isDisposition(value: unknown): value is BenchMetricDisposition {
+  return record(value) && ['not-applicable', 'estimated', 'unmeasured'].includes(String(value.status));
+}
+
+function validDisposition(value: unknown): value is BenchMetricDisposition {
+  return isDisposition(value) && typeof value.reason === 'string' && value.reason.trim().length > 0
+    && validSource({ collector: 'disposition', evidenceRef: value.evidenceRef });
+}
+
+function validAwsSource(value: unknown): value is BenchMetricSource {
+  if (!validSource(value) || typeof value.region !== 'string' || value.region.trim().length === 0) return false;
+  if (typeof value.windowStartUtc !== 'string' || typeof value.windowEndUtc !== 'string') return false;
+  const start = Date.parse(value.windowStartUtc);
+  const end = Date.parse(value.windowEndUtc);
+  return Number.isFinite(start) && Number.isFinite(end) && start < end
+    && value.windowStartUtc.endsWith('Z') && value.windowEndUtc.endsWith('Z');
+}
+
+/** The output is deliberately plan-ready, never measurement-ready. */
+export function checkBenchMeteringPlan(input: unknown): BenchMeteringPlanCheck {
+  const issues = scanSecretPropertyNames(input);
+  const issue = (message: string): void => { issues.push(message); };
+  if (!record(input)) {
+    issue('plan must be a JSON object');
+    return { readyToMeasure: false, metricsMeasured: false, armsLaunched: 0, issues };
+  }
+  if (input.schemaVersion !== 1) issue('schemaVersion must be 1');
+  if (typeof input.runId !== 'string' || input.runId.trim().length === 0) issue('runId is required');
+  if (typeof input.promptSha256 !== 'string' || !SHA256.test(input.promptSha256)) issue('promptSha256 must be a full SHA-256');
+  if (typeof input.baseSha !== 'string' || !COMMIT.test(input.baseSha)) issue('baseSha must be a full commit SHA');
+  if (typeof input.installedPin !== 'string' || !COMMIT.test(input.installedPin)) issue('installedPin must be a full commit SHA');
+
+  const arms = Array.isArray(input.arms) ? input.arms : [];
+  if (arms.length !== 2) issue('exactly two paired arms are required');
+  const claudePair = arms.some((arm) => record(arm) && arm.provider === 'elanous')
+    && arms.some((arm) => record(arm) && arm.provider === 'claude-code');
+  const providers = new Set<string>();
+  const armIds = new Set<string>();
+  for (const [index, arm] of arms.entries()) {
+    const prefix = `arms[${index}]`;
+    if (!record(arm)) { issue(`${prefix} must be an object`); continue; }
+    if (typeof arm.armId !== 'string' || arm.armId.trim().length === 0) issue(`${prefix}.armId is required`);
+    else if (armIds.has(arm.armId)) issue(`${prefix}.armId must be unique`);
+    else armIds.add(arm.armId);
+    if (!['openrouter', 'bedrock', 'elanous', 'claude-code'].includes(String(arm.provider))) issue(`${prefix}.provider must be openrouter, bedrock, elanous, or claude-code`);
+    else providers.add(arm.provider as string);
+    if (typeof arm.billingProvider !== 'string' || arm.billingProvider.trim().length === 0) issue(`${prefix}.billingProvider is required`);
+    if (arm.provider === 'bedrock' && arm.billingProvider !== 'bedrock') issue(`${prefix}.billingProvider must match bedrock`);
+    if (arm.provider === 'openrouter' && arm.billingProvider !== 'openrouter') issue(`${prefix}.billingProvider must match openrouter`);
+    if (arm.provider === 'claude-code' && (arm.agent !== 'claude-code' || arm.billingProvider !== 'subscription')) issue(`${prefix} Claude Code arm must identify agent claude-code and subscription billing`);
+    if (arm.provider === 'elanous') {
+      if (arm.agent !== 'elanous') issue(`${prefix} Elanous arm must identify agent elanous`);
+      if (!['openrouter', 'bedrock', 'codex'].includes(String(arm.billingProvider))) issue(`${prefix} Elanous billingProvider must be openrouter, bedrock, or codex`);
+    }
+    if (arm.noAutoMerge !== true) issue(`${prefix}.noAutoMerge must be true`);
+    const metrics = record(arm.metrics) ? arm.metrics : {};
+    const requiredMetrics = claudePair
+      ? COMPARISON_METRICS
+      : PROVIDER_PAIR_METRICS;
+    for (const metric of [...requiredMetrics, ...(arm.provider === 'bedrock' ? BEDROCK_METRICS : [])]) {
+      const value = metrics[metric];
+      if (isDisposition(value)) {
+        if (!validDisposition(value)) issue(`${prefix}.metrics.${metric} disposition needs a reason and evidenceRef`);
+        else if (value.status === 'unmeasured') issue(`${prefix}.metrics.${metric} is explicitly unmeasured; a collector and evidenceRef are required`);
+        else if (value.status === 'estimated') issue(`${prefix}.metrics.${metric} is estimated; a measured source is required`);
+        else if (metric !== 'actualChargeUsd' || arm.provider !== 'claude-code') issue(`${prefix}.metrics.${metric} is not applicable and cannot satisfy a required measurement`);
+      } else {
+        const sourceIsValid = metric === 'awsInvocationCount' ? validAwsSource(value) : validSource(value);
+        if (!sourceIsValid) issue(`${prefix}.metrics.${metric} needs a collector and evidenceRef${metric === 'awsInvocationCount' ? ', region, and an ordered UTC window' : ''}`);
+      }
+    }
+    const chargeMetric = metrics.actualChargeUsd;
+    const chargeSource = record(chargeMetric) ? chargeMetric.collector : undefined;
+    // This is deliberately a naming heuristic; it cannot prove the referenced billing artifact is genuine.
+    if (typeof chargeSource === 'string' && /estimate|rate.?card/i.test(chargeSource)) {
+      issue(`${prefix}.metrics.actualChargeUsd must identify an actual billing source, not an estimate`);
+    }
+    if (arm.provider === 'claude-code') {
+      if (!record(chargeMetric) || chargeMetric.status !== 'not-applicable'
+        || chargeMetric.reason !== 'subscription · no billing source'
+        || !validSource({ collector: 'subscription-disposition', evidenceRef: chargeMetric.evidenceRef })) {
+        issue(`${prefix}.metrics.actualChargeUsd must explicitly state subscription · no billing source`);
+      }
+      if ('creditDelta' in metrics) issue(`${prefix}.metrics.creditDelta must not imply subscription credit measurement`);
+    } else if (!validSource(chargeMetric)) {
+      issue(`${prefix}.metrics.actualChargeUsd needs an actual billing source`);
+    }
+    if ('estimatedChargeUsd' in metrics) {
+      const estimate = metrics.estimatedChargeUsd;
+      if (!record(estimate) || estimate.status !== 'estimated' || typeof estimate.reason !== 'string' || !estimate.reason.trim()
+        || !validSource({ collector: 'estimate', evidenceRef: estimate.evidenceRef })) {
+        issue(`${prefix}.metrics.estimatedChargeUsd must be explicitly marked estimated with reason and evidenceRef`);
+      }
+    }
+  }
+  const providerPair = providers.has('openrouter') && providers.has('bedrock');
+  const validClaudePair = providers.has('elanous') && providers.has('claude-code');
+  if (!providerPair && !validClaudePair) issue('pair must be openrouter + bedrock or elanous + claude-code');
+
+  const sealed = record(input.sealed) ? input.sealed : {};
+  if (sealed.directory !== 'sealed' || sealed.directoryMode !== '0700') issue('sealed output directory must be sealed/ with mode 0700');
+  if (sealed.unblindKey !== 'sealed/unblind-key.json') issue('unblind key must use the bench-blind-pack sealed path');
+  if (sealed.meteringReceipt !== 'sealed/metering-receipt.json') issue('metering receipt must stay beside the unblind key');
+  if (sealed.fileMode !== '0600') issue('sealed files must use mode 0600');
+
+  const publicFields = Array.isArray(input.publicFields) ? input.publicFields : [];
+  for (const field of publicFields) {
+    if (typeof field !== 'string' || PRIVATE_PUBLIC_FIELDS.test(field)) issue(`private metering/identity field cannot enter public output: ${String(field)}`);
+  }
+  return { readyToMeasure: issues.length === 0, metricsMeasured: false, armsLaunched: 0, issues };
+}
+
+async function main(argv: string[]): Promise<number> {
+  if (argv.length !== 1 || argv.includes('--help') || argv.includes('-h')) {
+    process.stderr.write('Usage: bun scripts/bench-metering-plan.ts <measurement-plan.json>\n');
+    return argv.includes('--help') || argv.includes('-h') ? 0 : 2;
+  }
+  try {
+    const plan = JSON.parse(await readFile(argv[0]!, 'utf8')) as unknown;
+    const result = checkBenchMeteringPlan(plan);
+    if (!result.readyToMeasure) {
+      process.stderr.write(`bench metering plan refused (${result.issues.length} issue(s)):\n${result.issues.map((entry) => `- ${entry}`).join('\n')}\n`);
+      return 2;
+    }
+    process.stdout.write('plan-ready; no metrics measured; no benchmark arms launched\n');
+    return 0;
+  } catch (error) {
+    process.stderr.write(`bench metering plan refused: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 2;
+  }
+}
+
+if (import.meta.main) process.exitCode = await main(process.argv.slice(2));

package/scripts/build-signed-catalog.ts

@@ -0,0 +1,48 @@
+import { mkdtempSync, readFileSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { signCatalogPayload, type SignedCatalogPayload } from '../src/registry/catalog-server.js';
+import { getElanousConfigDirOverride, resetElanousConfigDir, setElanousConfigDir } from '../src/elanous-config-dir.js';
+
+function option(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+const keyPath = option('--key-file') ?? process.env.ELANOUS_CATALOG_SIGNING_KEY_FILE;
+if (!keyPath) throw new Error('Pass --key-file or ELANOUS_CATALOG_SIGNING_KEY_FILE (private key is read only and never printed).');
+const root = mkdtempSync(join(tmpdir(), 'elanous-catalog-build-'));
+const envKeys = ['NODE_ENV', 'ELANOUS_STATE_DIR', 'ELANOUS_CATALOG_SERVER_CACHE', 'ELANOUS_CATALOG_PUBLIC_KEY_FILE', 'ELANOUS_CATALOG_DISCOVERY_SNAPSHOT'];
+const previousEnv = new Map(envKeys.map((key) => [key, process.env[key]]));
+const previousConfigDir = getElanousConfigDirOverride();
+for (const key of envKeys) delete process.env[key];
+process.env.NODE_ENV = 'test';
+process.env.ELANOUS_STATE_DIR = root;
+setElanousConfigDir(root);
+try {
+  const { getCatalog } = await import('../src/registry/loader.js');
+  const versionDoc = parseYaml(readFileSync(resolve('catalog/meta/catalogVersion.yaml'), 'utf8')) as { catalogVersion?: unknown };
+  if (!Number.isSafeInteger(versionDoc.catalogVersion) || (versionDoc.catalogVersion as number) < 1) {
+    throw new Error('catalog/meta/catalogVersion.yaml must contain a positive integer catalogVersion.');
+  }
+  const catalog = getCatalog();
+  const payload: SignedCatalogPayload = {
+    catalogVersion: versionDoc.catalogVersion as number,
+    generatedAt: new Date().toISOString(),
+    providers: [...catalog.providers.values()].sort((a, b) => a.id.localeCompare(b.id)),
+    models: [...catalog.models.values()].sort((a, b) => a.id.localeCompare(b.id)),
+  };
+  const signed = signCatalogPayload(payload, readFileSync(resolve(keyPath)));
+  const outPath = resolve(option('--out') ?? 'dist/catalog/catalog.json');
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, `${JSON.stringify(signed, null, 2)}\n`, { encoding: 'utf8', mode: 0o644 });
+  console.log(`Wrote signed catalog v${payload.catalogVersion}: ${outPath}`);
+} finally {
+  resetElanousConfigDir();
+  if (previousConfigDir) setElanousConfigDir(previousConfigDir);
+  for (const [key, value] of previousEnv) {
+    if (value === undefined) delete process.env[key]; else process.env[key] = value;
+  }
+  rmSync(root, { recursive: true, force: true });
+}