session-orchestrator 3.16.0

package/scripts/emit-event.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * emit-event.mjs — CLI wrapper around emitEvent() from scripts/lib/events.mjs.
+ *
+ * Lets non-Node callers (shell helpers, hooks) route through the single
+ * canonical emission path instead of hand-writing JSONL with `jq >> file`.
+ * Hand-rolled appenders drift from `emitEvent()` (the `stop` vs
+ * `orchestrator.session.stopped` divergence #609 fixed); this CLI closes the
+ * last such gap — compute-grounding-injection.sh (#611).
+ *
+ * Usage:
+ *   node scripts/emit-event.mjs --type <name> --payload '<json>' [--file <path>]
+ *
+ * Flags:
+ *   --type <name>      REQUIRED. Event type (e.g. orchestrator.grounding.injected).
+ *   --payload <json>   Optional. JSON object string, shallow-merged into the record.
+ *                      Defaults to {} when omitted. Must parse to a plain object.
+ *   --file <path>      Optional. Destination JSONL path override. Defaults to the
+ *                      project's .orchestrator/metrics/events.jsonl (via emitEvent).
+ *   --json             Optional. Emit a structured JSON result line to stdout.
+ *   --help, -h         Print usage and exit 0.
+ *
+ * Exit codes (per .claude/rules/cli-design.md):
+ *   0 — success (event emitted)
+ *   1 — user/input error (missing --type, malformed --payload JSON, non-object payload)
+ *   2 — system error (write failure, unexpected internal error)
+ *
+ * Data → stdout (only with --json). Diagnostics → stderr (always). Related: #611.
+ */
+
+import { parseArgs } from 'node:util';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const HELP = `Usage: emit-event.mjs --type <name> [--payload '<json>'] [--file <path>] [--json]
+
+Routes a single event through emitEvent() (scripts/lib/events.mjs) — the canonical
+emission path that also fires the optional Clank Event Bus webhook.
+
+Flags:
+  --type <name>      REQUIRED. Event type (e.g. orchestrator.grounding.injected).
+  --payload <json>   Optional. JSON object string, shallow-merged. Defaults to {}.
+  --file <path>      Optional. Destination JSONL path override. Defaults to the
+                     project's .orchestrator/metrics/events.jsonl.
+  --json             Optional. Print a JSON result object to stdout.
+  --help, -h         Print this help and exit 0.
+
+Exit codes:
+  0 — success
+  1 — user/input error (missing --type, malformed --payload, non-object payload)
+  2 — system error (write failure / internal error)
+`;
+
+/**
+ * Print an error diagnostic to stderr and exit with the given code. When
+ * `--json` is set, also writes a JSON result object to stdout so machine
+ * callers get a parseable signal on both streams (data→stdout, diag→stderr).
+ *
+ * @param {string} message — human-readable diagnostic (stderr)
+ * @param {number} exitCode — 1 (user/input) or 2 (system)
+ * @param {boolean} jsonMode — whether to also emit JSON to stdout
+ */
+function fail(message, exitCode, jsonMode) {
+  process.stderr.write(`emit-event: ${message}\n`);
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({ ok: false, error: message }) + '\n');
+  }
+  process.exit(exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// --help (before any parsing; never errors)
+// ---------------------------------------------------------------------------
+
+const rawArgv = process.argv.slice(2);
+if (rawArgv.includes('--help') || rawArgv.includes('-h')) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+// Detect --json early so error paths can honour it even if parseArgs throws.
+const jsonMode = rawArgv.includes('--json');
+
+// ---------------------------------------------------------------------------
+// Top-level guard — uncaught errors become a system error (exit 2), not a stack
+// ---------------------------------------------------------------------------
+
+process.on('uncaughtException', (err) => {
+  fail(`internal error: ${err?.message ?? String(err)}`, 2, jsonMode);
+});
+
+// ---------------------------------------------------------------------------
+// Parse argv
+// ---------------------------------------------------------------------------
+
+let parsed;
+try {
+  parsed = parseArgs({
+    args: rawArgv,
+    options: {
+      type:    { type: 'string' },
+      payload: { type: 'string' },
+      file:    { type: 'string' },
+      json:    { type: 'boolean' },
+    },
+    strict: false, // tolerate unknown flags as positionals rather than throwing
+  });
+} catch (err) {
+  fail(`failed to parse arguments: ${err.message}`, 1, jsonMode);
+}
+
+const type = parsed.values['type'];
+const payloadRaw = parsed.values['payload'];
+const filePath = parsed.values['file'];
+
+// --- Validate --type (user/input error → exit 1) ---
+if (typeof type !== 'string' || type.length === 0) {
+  fail('--type is required', 1, jsonMode);
+}
+
+// --- Parse --payload JSON (default {}); must be a plain object (exit 1) ---
+let payload = {};
+if (payloadRaw !== undefined) {
+  try {
+    payload = JSON.parse(payloadRaw);
+  } catch (err) {
+    fail(`--payload is not valid JSON: ${err.message}`, 1, jsonMode);
+  }
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    fail('--payload must be a JSON object', 1, jsonMode);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Emit via the canonical path
+// ---------------------------------------------------------------------------
+
+let emitEvent;
+try {
+  ({ emitEvent } = await import(join(__dirname, 'lib', 'events.mjs')));
+} catch (err) {
+  fail(`failed to load events.mjs: ${err.message}`, 2, jsonMode);
+}
+
+try {
+  await emitEvent(type, payload, filePath ? { filePath } : {});
+} catch (err) {
+  // Write/IO failures are system errors (exit 2).
+  fail(`failed to emit event: ${err.message}`, 2, jsonMode);
+}
+
+if (jsonMode) {
+  process.stdout.write(
+    JSON.stringify({ ok: true, event: type, ...(filePath ? { file: filePath } : {}) }) + '\n',
+  );
+}
+
+process.exit(0);

package/scripts/emit-session.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * emit-session.mjs — validating writer for session JSONL entries.
+ *
+ * Issue #249 follow-up. The gate that session-end Phase 3.7 invokes to append
+ * a single session record to `.orchestrator/metrics/sessions.jsonl` (or any
+ * target path). Replaces the raw shell `>>` append with a validated path:
+ *
+ *   node scripts/emit-session.mjs [--file PATH] [--entry JSON]
+ *
+ * Input modes:
+ *   --entry '<json>'   pass the entry JSON literally (for shell pipelines)
+ *   (stdin)            read the entry JSON from stdin (default when no --entry)
+ *
+ * Defaults:
+ *   --file .orchestrator/metrics/sessions.jsonl
+ *
+ * Exit codes:
+ *   0 — validated and appended
+ *   1 — validation failed (see stderr for reason); file not touched
+ *   2 — I/O / parse error (non-JSON input, unwritable path)
+ *
+ * On success the script echoes a single JSON line to stdout:
+ *   {"action":"appended","path":"<file>","session_id":"<id>","schema_version":2}
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { appendJsonl } from './lib/common.mjs';
+import {
+  validateSession,
+  ValidationError,
+  CURRENT_SESSION_SCHEMA_VERSION,
+  clampTimestampsMonotonic,
+  aliasLegacyEndedAt,
+} from './lib/session-schema.mjs';
+
+/**
+ * Serialize `validated` to a single JSONL line and prove it round-trips:
+ * the line MUST be JSON-parseable AND the parsed-back object MUST still pass
+ * `validateSession`. This is the pre-write self-validation seam (#662) that
+ * mirrors the `appendLearning` guard — it catches non-serializable values
+ * (`undefined`, `NaN`, `Infinity`, `BigInt`, circular refs) that
+ * `JSON.stringify` silently drops or that produce a line which won't parse
+ * back to the same schema-valid shape.
+ *
+ * Throws ValidationError (consumed by the caller as a validation failure,
+ * exit 1). Does not write — the caller appends only after this returns.
+ *
+ * @param {object} validated — already validated session entry
+ * @returns {string} the verified JSONL line (newline-terminated)
+ * @throws {ValidationError} when the serialized line does not round-trip
+ */
+export function serializeSessionLineChecked(validated) {
+  let line;
+  try {
+    line = JSON.stringify(validated);
+  } catch (err) {
+    throw new ValidationError(`session is not JSON-serializable: ${err.message}`);
+  }
+  if (typeof line !== 'string' || line.length === 0) {
+    throw new ValidationError('session serialized to an empty line');
+  }
+  let reparsed;
+  try {
+    reparsed = JSON.parse(line);
+  } catch (err) {
+    throw new ValidationError(
+      `serialized session line does not parse back as JSON: ${err.message}`
+    );
+  }
+  // Re-validate the round-tripped shape — catches required fields that were
+  // present as `undefined`/`NaN` before stringify but vanished after.
+  validateSession(reparsed);
+  return line + '\n';
+}
+
+function parseArgs(argv) {
+  const args = { file: '.orchestrator/metrics/sessions.jsonl', entry: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--file') args.file = argv[++i];
+    else if (a === '--entry') args.entry = argv[++i];
+    else if (a === '--help' || a === '-h') {
+      process.stdout.write(
+        'Usage: node scripts/emit-session.mjs [--file PATH] [--entry JSON]\n' +
+          '  --file   target JSONL file (default: .orchestrator/metrics/sessions.jsonl)\n' +
+          '  --entry  entry JSON (if omitted, read from stdin)\n' +
+          'Exit codes: 0 append ok, 1 validation error, 2 I/O error\n'
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`emit-session: unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch (err) {
+    process.stderr.write(`emit-session: failed to read stdin: ${err.message}\n`);
+    process.exit(2);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const raw = args.entry ?? readStdin();
+  if (!raw || raw.trim().length === 0) {
+    process.stderr.write('emit-session: no entry provided (stdin empty and --entry not set)\n');
+    process.exit(2);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    process.stderr.write(`emit-session: input is not valid JSON: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  // Pre-validation repairs (issue #321):
+  //   1. Alias legacy `ended_at` -> `completed_at` for pre-canonical writers.
+  //   2. Clamp completed_at < started_at inversions (clock-skew or manual
+  //      STATE.md frontmatter edits) before validate would reject them.
+  let repaired = aliasLegacyEndedAt(parsed);
+  if (repaired !== parsed && repaired._completed_at_conflict === true) {
+    process.stderr.write(
+      `emit-session: WARN session_id=${repaired.session_id ?? '<unknown>'}: ` +
+        `both completed_at and ended_at present and differ; preferring completed_at\n`
+    );
+  }
+  const beforeClamp = repaired;
+  repaired = clampTimestampsMonotonic(repaired);
+  if (repaired !== beforeClamp && repaired._clamped === true) {
+    const startedMs = Date.parse(repaired.started_at);
+    const origMs = Date.parse(repaired._original_completed_at);
+    const deltaSec = Number.isFinite(startedMs - origMs)
+      ? Math.round((startedMs - origMs) / 1000)
+      : null;
+    process.stderr.write(
+      `emit-session: WARN session_id=${repaired.session_id ?? '<unknown>'}: ` +
+        `completed_at < started_at (delta=${deltaSec}s); clamped completed_at to started_at ` +
+        `(original preserved as _original_completed_at=${repaired._original_completed_at})\n`
+    );
+  }
+
+  let validated;
+  try {
+    validated = validateSession(repaired);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      process.stderr.write(`emit-session: validation failed: ${err.message}\n`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Pre-write round-trip self-validation (#662): prove the line this writer is
+  // about to append parses back AND re-validates BEFORE it reaches disk. The
+  // append path (appendJsonl) does the same JSON.stringify, so a record that
+  // stringifies "fine" but round-trips to a schema-invalid shape (NaN/undefined
+  // required field silently dropped by JSON.stringify) would otherwise corrupt
+  // sessions.jsonl and only surface on the NEXT session's read. Treated as a
+  // validation failure (exit 1); file is left untouched.
+  try {
+    serializeSessionLineChecked(validated);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      process.stderr.write(
+        `emit-session: pre-write round-trip validation failed: ${err.message}\n`
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // validateSession returns `{ ...entry, schema_version }` — the spread preserves
+  // ALL additive fields, including `memory_cleanup_at` (#699) and `autopilot_run_id`
+  // (#300). No field stripping occurs here; additive v1-compatible fields pass through.
+  try {
+    await appendJsonl(args.file, validated);
+  } catch (err) {
+    process.stderr.write(`emit-session: write failed (${args.file}): ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const summary = {
+    action: 'appended',
+    path: args.file,
+    session_id: validated.session_id,
+    schema_version: validated.schema_version ?? CURRENT_SESSION_SCHEMA_VERSION,
+  };
+  process.stdout.write(JSON.stringify(summary) + '\n');
+}
+
+// Only run the CLI when invoked directly (`node scripts/emit-session.mjs ...`),
+// not when imported as a module (e.g. by tests that exercise the exported
+// serializeSessionLineChecked seam — #662). Without this guard, importing the
+// module would block on stdin / exit the test process.
+const _isDirectRun =
+  process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+
+if (_isDirectRun) {
+  main().catch((err) => {
+    process.stderr.write(`emit-session: unexpected error: ${err?.stack ?? err}\n`);
+    process.exit(2);
+  });
+}

package/scripts/eval-session.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * eval-session.mjs — CLI front-end for the aiat-llm-eval deterministic engine
+ * (Epic #803, S3). Evaluates ONE completed orchestrator session against the
+ * rubric-v1 dimensions from local metrics files, appends the record to the
+ * eval journal, and can re-verify a stored record for scoring drift.
+ *
+ * Follows .claude/rules/cli-design.md:
+ *   - `--json` for machine output; human-readable by default.
+ *   - Data → stdout, diagnostics → stderr.
+ *   - Exit codes: 0 success/match · 1 user-error/drift · 2 system error.
+ *
+ * Usage:
+ *   eval-session.mjs [--session <id>] [--json] [--no-write]
+ *                    [--metrics-dir <path>] [--rubric <path>]
+ *                    [--model-id <id>] [--model-source <self-report|env|config>]
+ *                    [--handle <s>]
+ *   eval-session.mjs --verify <run-id> [--json] [--metrics-dir <path>]
+ *   eval-session.mjs --help | --version
+ *
+ * The eval `timestamp` is captured HERE (the one sanctioned Date.now read); the
+ * engine receives it as a parameter so its scoring path stays clock-free.
+ */
+
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { evaluateSession, diffDimensions, DEFAULT_RUBRIC_PATH, RUBRIC_VERSION } from './lib/eval/engine.mjs';
+import { appendEvalRecord, readEvalRecords } from './lib/eval/sink.mjs';
+import { VALID_MODEL_SOURCES } from './lib/eval/schema.mjs';
+import { SessionResolutionError } from './lib/eval/session-resolve.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const EXIT_OK = 0;
+const EXIT_USER = 1;
+const EXIT_SYSTEM = 2;
+
+function readPkgVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'));
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+const HELP = `eval-session — deterministic session evaluator (aiat-llm-eval / ${RUBRIC_VERSION})
+
+USAGE
+  eval-session.mjs [options]                 evaluate + append a session-eval record
+  eval-session.mjs --verify <run-id>         re-evaluate a stored record, diff for drift
+  eval-session.mjs --help | --version
+
+OPTIONS
+  --session <id>          session_id to evaluate (default: last completed session)
+  --json                  emit the record (or verify result) as JSON on stdout
+  --no-write              evaluate without appending to the eval journal
+  --metrics-dir <path>    metrics directory (default: .orchestrator/metrics)
+  --rubric <path>         rubric file to hash for provenance (default: ${DEFAULT_RUBRIC_PATH})
+  --model-id <id>         evaluated model id (default: $ANTHROPIC_MODEL or "unknown")
+  --model-source <src>    ${VALID_MODEL_SOURCES.join(' | ')} (default: self-report)
+  --handle <s>            optional self-chosen pseudonym (omit ⇒ anonymized)
+  --verify <run-id>       re-run the stored record and diff per-dimension
+  --help                  show this help
+  --version               print version
+
+EXIT CODES
+  0  success / verify match
+  1  user error (session not found, unknown run-id) / verify drift
+  2  system error
+`;
+
+function fail(exitCode, message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(exitCode);
+}
+
+/** Render the human-readable per-dimension summary. */
+function renderHuman(record, summary, writeResult) {
+  const lines = [];
+  lines.push(`Session:  ${record.session_id}  (resolved via ${summary.resolvedVia})`);
+  lines.push(`Run:      ${record.run_id}`);
+  lines.push(`Rubric:   ${record.rubric_version}  (${record.standard_version})`);
+  lines.push(`Model:    ${record.model.id}  [${record.model.source}]`);
+  if (summary.contaminated) {
+    lines.push(`WARNING:  time-window contaminated by ${summary.peerCount} peer session(s) [${summary.peers.join(', ')}]`);
+  }
+  lines.push('');
+  lines.push('Dimensions (no global score — by construction):');
+  for (const d of record.dimensions) {
+    lines.push(`  ${d.id.padEnd(22)} [${d.method}]  ${d.status.toUpperCase()}`);
+    lines.push(`      ${d.evidence}`);
+  }
+  lines.push('');
+  const k = record.kpis;
+  const fmt = (v) => (v === null || v === undefined ? 'null' : String(v));
+  lines.push(
+    `KPIs (reported): duration=${fmt(k.duration_seconds)}s waves=${fmt(k.total_waves)} agents=${fmt(k.total_agents)} tok_in=${fmt(k.token_input)} tok_out=${fmt(k.token_output)} carryover=${fmt(k.carryover)}`,
+  );
+  if (writeResult === null) {
+    lines.push('(dry-run: --no-write, record NOT persisted)');
+  } else if (writeResult.ok) {
+    lines.push(`Written:  ${writeResult.path}`);
+  } else {
+    lines.push(`NOT written (${writeResult.reason}): ${writeResult.error}`);
+  }
+  return lines.join('\n');
+}
+
+function runEvaluate(values) {
+  const metricsDir = values['metrics-dir'] || '.orchestrator/metrics';
+  const rubricPath = values.rubric || DEFAULT_RUBRIC_PATH;
+  const modelSource = values['model-source'] || 'self-report';
+  if (!VALID_MODEL_SOURCES.includes(modelSource)) {
+    fail(EXIT_USER, `--model-source must be one of ${VALID_MODEL_SOURCES.join(' | ')} (got: ${modelSource})`);
+  }
+  const modelId = values['model-id'] || process.env.ANTHROPIC_MODEL || 'unknown';
+  const handle = values.handle ?? null;
+
+  // The one sanctioned clock read — the engine gets this as a parameter.
+  const timestamp = new Date().toISOString();
+
+  let result;
+  try {
+    result = evaluateSession({
+      sessionId: values.session,
+      metricsDir,
+      rubricPath,
+      timestamp,
+      model: { id: modelId, source: modelSource },
+      handle,
+    });
+  } catch (err) {
+    if (err instanceof SessionResolutionError) {
+      fail(EXIT_USER, `Cannot evaluate: ${err.message}`);
+    }
+    fail(EXIT_SYSTEM, `Evaluation error: ${err?.message ?? String(err)}`);
+    return;
+  }
+
+  const { record, summary } = result;
+
+  let writeResult = null;
+  if (!values['no-write']) {
+    writeResult = appendEvalRecord(record, { path: path.join(metricsDir, 'eval.jsonl') });
+    if (!writeResult.ok) {
+      // never-throw sink already emitted a stderr WARN; surface it as a soft note.
+      process.stderr.write(`[eval-session] append failed (${writeResult.reason}): ${writeResult.error}\n`);
+    }
+  }
+
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify(record)}\n`);
+  } else {
+    process.stdout.write(`${renderHuman(record, summary, writeResult)}\n`);
+  }
+  process.exit(EXIT_OK);
+}
+
+function runVerify(runId, values) {
+  const metricsDir = values['metrics-dir'] || '.orchestrator/metrics';
+  const rubricPath = values.rubric || DEFAULT_RUBRIC_PATH;
+
+  const records = readEvalRecords(path.join(metricsDir, 'eval.jsonl'));
+  const stored = records.find((r) => r && r.run_id === runId);
+  if (!stored) {
+    fail(EXIT_USER, `--verify: run-id not found in eval journal: ${runId}`);
+  }
+
+  let fresh;
+  try {
+    fresh = evaluateSession({
+      sessionId: stored.session_id,
+      metricsDir,
+      rubricPath,
+      timestamp: stored.timestamp,
+      model: stored.model && stored.model.id ? stored.model : { id: 'unknown', source: 'self-report' },
+      handle: stored.handle ?? null,
+      pluginVersion: stored.harness?.plugin_version,
+      platform: stored.harness?.platform,
+      resolveModelFromEnv: false, // reproduce the stored model verbatim — never env-override
+    }).record;
+  } catch (err) {
+    if (err instanceof SessionResolutionError) {
+      fail(EXIT_USER, `--verify: ${err.message}`);
+    }
+    fail(EXIT_SYSTEM, `--verify evaluation error: ${err?.message ?? String(err)}`);
+    return;
+  }
+
+  const diffs = diffDimensions(stored.dimensions, fresh.dimensions);
+
+  if (diffs.length === 0) {
+    if (values.json) {
+      process.stdout.write(`${JSON.stringify({ run_id: runId, match: true, dimensions: fresh.dimensions.length })}\n`);
+    } else {
+      process.stdout.write(`MATCH: ${runId} re-evaluates identically across ${fresh.dimensions.length} dimension(s).\n`);
+    }
+    process.exit(EXIT_OK);
+  }
+
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify({ run_id: runId, match: false, diffs })}\n`);
+  } else {
+    const out = [`DRIFT: ${runId} re-evaluation differs from the stored record:`];
+    for (const d of diffs) {
+      if (d.reason) {
+        out.push(`  ${d.id}: ${d.reason}`);
+      } else {
+        out.push(`  ${d.id}.${d.field}: stored=${JSON.stringify(d.stored)} fresh=${JSON.stringify(d.fresh)}`);
+      }
+    }
+    process.stdout.write(`${out.join('\n')}\n`);
+  }
+  process.exit(EXIT_USER);
+}
+
+function main() {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      options: {
+        session: { type: 'string' },
+        json: { type: 'boolean', default: false },
+        'no-write': { type: 'boolean', default: false },
+        'metrics-dir': { type: 'string' },
+        rubric: { type: 'string' },
+        'model-id': { type: 'string' },
+        'model-source': { type: 'string' },
+        handle: { type: 'string' },
+        verify: { type: 'string' },
+        help: { type: 'boolean', default: false },
+        version: { type: 'boolean', default: false },
+      },
+      allowPositionals: true,
+    }));
+  } catch (err) {
+    fail(EXIT_USER, `Argument error: ${err?.message ?? String(err)}`);
+    return;
+  }
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    process.exit(EXIT_OK);
+  }
+  if (values.version) {
+    process.stdout.write(`${readPkgVersion()}\n`);
+    process.exit(EXIT_OK);
+  }
+
+  if (values.verify) {
+    runVerify(values.verify, values);
+    return;
+  }
+
+  runEvaluate(values);
+}
+
+main();