@shawnowen/comet-mcp 2.3.1 → 2.4.1

package/vendor/readiness-report.mjs

@@ -0,0 +1,742 @@
+#!/usr/bin/env node
+/**
+ * Readiness Reporter — machine-readable + human-readable readiness reports (Spec 070, S070-T007).
+ * Operational Telemetry — route/fallback/ownership/completion aggregation (Spec 070, S070-T019).
+ *
+ * Runs bootstrap checks via comet-bootstrap.mjs and annotates results with
+ * two-tier readiness labels (Pilot / Broad) per clarification C3.
+ *
+ * Can be used as:
+ *   1. CLI:  node scripts/readiness-report.mjs [--json] [--save <path>] [--port <n>]
+ *   2. API:  import { generateReadinessReport, recordTelemetryEvent } from './readiness-report.mjs';
+ *
+ * Readiness tiers (C3):
+ *   - Pilot:  core + CDP + config + output dirs pass; MCP and extension may warn.
+ *   - Broad:  all checks pass including MCP build and extension bridge.
+ *
+ * Telemetry (S070-T019):
+ *   Events are appended to {COMET_OUTPUT_BASE}/audit/telemetry-events.jsonl via
+ *   recordTelemetryEvent(). The report aggregates recent events into route usage,
+ *   fallback frequency, ownership check results, and completion outcome stats.
+ *
+ * Exit codes mirror bootstrap: 0 = Broad-ready, 1 = critical failure, 2 = Pilot-only (warnings).
+ */
+
+import { spawnSync } from "child_process";
+import { writeFileSync, mkdirSync, existsSync, readFileSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const COMET_BRIDGE_ROOT = process.env.COMET_BRIDGE_ROOT || join(__dirname, "..");
+
+const PILOT_REQUIRED_CHECKS = ["comet-app", "cdp", "config", "output-dirs"];
+const BROAD_REQUIRED_CHECKS = [
+  "comet-app",
+  "cdp",
+  "mcp",
+  "extension-bridge",
+  "config",
+  "output-dirs",
+];
+
+// --- Telemetry (S070-T019) ---
+
+const TELEMETRY_OUTPUT_BASE =
+  process.env.COMET_OUTPUT_BASE || join(homedir(), ".claude/comet-browser/output");
+const TELEMETRY_LOG_PATH = join(TELEMETRY_OUTPUT_BASE, "audit", "telemetry-events.jsonl");
+const AUDIT_SESSION_BASE =
+  process.env.BROWSER_AUDIT_PATH || join(homedir(), "equabot", "audit", "browser-sessions");
+
+const VALID_ROUTES = ["mcp", "cli", "http", "ide-browser"];
+const VALID_OUTCOMES = ["completed", "failed", "aborted"];
+const VALID_OWNERSHIP_RESULTS = ["passed", "failed", "skipped"];
+
+// --- Telemetry Event Recording (S070-T019) ---
+
+/**
+ * Append a telemetry event to the JSONL log.
+ * Other modules (cursor-comet.mjs, auto.mjs, tab-safety.mjs) call this to record
+ * route usage, fallback triggers, ownership check results, and run completions.
+ *
+ * @param {{
+ *   type: 'route' | 'fallback' | 'ownership' | 'completion',
+ *   route?: string,
+ *   channel?: string,
+ *   fallbackUsed?: boolean,
+ *   fallbackReason?: string,
+ *   ownershipResult?: 'passed' | 'failed' | 'skipped',
+ *   ownershipAction?: string,
+ *   agentId?: string,
+ *   taskThreadId?: string,
+ *   outcome?: 'completed' | 'failed' | 'aborted',
+ *   runId?: string,
+ *   durationMs?: number,
+ *   metadata?: object,
+ * }} event
+ */
+export function recordTelemetryEvent(event) {
+  if (!event || !event.type) return;
+  const entry = {
+    ts: new Date().toISOString(),
+    ...event,
+  };
+  try {
+    const dir = dirname(TELEMETRY_LOG_PATH);
+    mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify(entry) + "\n";
+    writeFileSync(TELEMETRY_LOG_PATH, line, { flag: "a" });
+  } catch {
+    // telemetry is best-effort; never block the caller
+  }
+}
+
+/**
+ * Read and parse telemetry events from the JSONL log.
+ * @param {{ maxAgeDays?: number, limit?: number }} [opts]
+ * @returns {object[]}
+ */
+function readTelemetryEvents(opts = {}) {
+  const maxAgeDays = opts.maxAgeDays ?? 7;
+  const limit = opts.limit ?? 5000;
+  if (!existsSync(TELEMETRY_LOG_PATH)) return [];
+
+  let raw;
+  try {
+    raw = readFileSync(TELEMETRY_LOG_PATH, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const cutoff = new Date(Date.now() - maxAgeDays * 86_400_000).toISOString();
+  const events = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const evt = JSON.parse(line);
+      if (evt.ts && evt.ts >= cutoff) events.push(evt);
+    } catch {
+      // skip malformed lines
+    }
+    if (events.length >= limit) break;
+  }
+  return events;
+}
+
+/**
+ * Read recent audit session metadata for completion stats enrichment.
+ * @param {{ limit?: number }} [opts]
+ * @returns {object[]}
+ */
+function readRecentAuditSessions(opts = {}) {
+  const limit = opts.limit ?? 50;
+  if (!existsSync(AUDIT_SESSION_BASE)) return [];
+
+  let dirs;
+  try {
+    dirs = readdirSync(AUDIT_SESSION_BASE, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort()
+      .reverse()
+      .slice(0, limit);
+  } catch {
+    return [];
+  }
+
+  const sessions = [];
+  for (const dir of dirs) {
+    const metaPath = join(AUDIT_SESSION_BASE, dir, "metadata.json");
+    if (!existsSync(metaPath)) continue;
+    try {
+      sessions.push(JSON.parse(readFileSync(metaPath, "utf-8")));
+    } catch {
+      // skip corrupt metadata
+    }
+  }
+  return sessions;
+}
+
+/**
+ * Aggregate telemetry events and audit sessions into an operational summary.
+ * Per Spec 070 S070-T019: route used, fallback status, ownership checks,
+ * and completion stats.
+ *
+ * @param {{ maxAgeDays?: number }} [opts]
+ * @returns {object} Telemetry summary
+ */
+export function collectTelemetrySummary(opts = {}) {
+  const events = readTelemetryEvents(opts);
+  const sessions = readRecentAuditSessions();
+
+  const routeCounts = {};
+  for (const r of VALID_ROUTES) routeCounts[r] = 0;
+  let routeTotal = 0;
+
+  let fallbackTriggered = 0;
+  let fallbackTotal = 0;
+  const fallbackReasons = {};
+
+  const ownershipCounts = {};
+  for (const r of VALID_OWNERSHIP_RESULTS) ownershipCounts[r] = 0;
+  let ownershipTotal = 0;
+
+  const completionCounts = {};
+  for (const o of VALID_OUTCOMES) completionCounts[o] = 0;
+  let completionTotal = 0;
+  const durations = [];
+
+  for (const evt of events) {
+    switch (evt.type) {
+      case "route":
+        if (evt.route && VALID_ROUTES.includes(evt.route)) {
+          routeCounts[evt.route]++;
+          routeTotal++;
+        }
+        break;
+      case "fallback":
+        fallbackTotal++;
+        if (evt.fallbackUsed) {
+          fallbackTriggered++;
+          const reason = evt.fallbackReason || "unknown";
+          fallbackReasons[reason] = (fallbackReasons[reason] || 0) + 1;
+        }
+        break;
+      case "ownership":
+        if (evt.ownershipResult && VALID_OWNERSHIP_RESULTS.includes(evt.ownershipResult)) {
+          ownershipCounts[evt.ownershipResult]++;
+          ownershipTotal++;
+        }
+        break;
+      case "completion":
+        if (evt.outcome && VALID_OUTCOMES.includes(evt.outcome)) {
+          completionCounts[evt.outcome]++;
+          completionTotal++;
+          if (typeof evt.durationMs === "number") durations.push(evt.durationMs);
+        }
+        break;
+    }
+  }
+
+  let auditSessionStats = { total: 0, completed: 0, failed: 0, active: 0, other: 0 };
+  for (const s of sessions) {
+    auditSessionStats.total++;
+    if (s.status === "completed" && s.outcome === "success") auditSessionStats.completed++;
+    else if (s.status === "completed" && s.outcome === "failed") auditSessionStats.failed++;
+    else if (s.status === "failed") auditSessionStats.failed++;
+    else if (s.status === "active") auditSessionStats.active++;
+    else auditSessionStats.other++;
+  }
+
+  const avgDurationMs =
+    durations.length > 0
+      ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
+      : null;
+
+  return {
+    period: {
+      maxAgeDays: opts.maxAgeDays ?? 7,
+      eventsAnalyzed: events.length,
+      auditSessionsAnalyzed: sessions.length,
+    },
+    routes: {
+      total: routeTotal,
+      counts: routeCounts,
+      primary:
+        routeTotal > 0 ? Object.entries(routeCounts).sort((a, b) => b[1] - a[1])[0][0] : null,
+    },
+    fallbacks: {
+      total: fallbackTotal,
+      triggered: fallbackTriggered,
+      rate: fallbackTotal > 0 ? +(fallbackTriggered / fallbackTotal).toFixed(3) : 0,
+      reasons: fallbackReasons,
+    },
+    ownership: {
+      total: ownershipTotal,
+      counts: ownershipCounts,
+      violationRate: ownershipTotal > 0 ? +(ownershipCounts.failed / ownershipTotal).toFixed(3) : 0,
+    },
+    completions: {
+      total: completionTotal,
+      counts: completionCounts,
+      successRate:
+        completionTotal > 0 ? +(completionCounts.completed / completionTotal).toFixed(3) : 0,
+      avgDurationMs,
+    },
+    auditSessions: auditSessionStats,
+  };
+}
+
+/**
+ * Run bootstrap checks by invoking comet-bootstrap.mjs --json and parsing results.
+ * @param {{ port?: number, autoStart?: boolean, cometBridgeRoot?: string }} [opts]
+ * @returns {{ bootstrapReport: object, raw: string, checks: Array }}
+ */
+export function runBootstrapChecks(opts = {}) {
+  const root = opts.cometBridgeRoot || COMET_BRIDGE_ROOT;
+  const scriptsDir = join(root, "scripts");
+  const args = [join(scriptsDir, "comet-bootstrap.mjs"), "--json"];
+  if (opts.port) args.push("--port", String(opts.port));
+  if (opts.autoStart) args.push("--auto-start");
+
+  const result = spawnSync(process.execPath, args, {
+    cwd: root,
+    encoding: "utf-8",
+    timeout: 30_000,
+    env: { ...process.env, COMET_BRIDGE_ROOT: root },
+  });
+
+  const raw = (result.stdout || "").trim();
+  let bootstrapReport;
+  try {
+    bootstrapReport = JSON.parse(raw);
+  } catch {
+    bootstrapReport = {
+      timestamp: new Date().toISOString(),
+      overall: "FAIL",
+      checks: [
+        {
+          id: "bootstrap-parse",
+          status: "FAIL",
+          critical: true,
+          message: `Could not parse bootstrap output: ${raw.slice(0, 200)}`,
+        },
+      ],
+      summary: { total: 1, passed: 0, failed: 1, warnings: 0, skipped: 0 },
+    };
+  }
+
+  return { bootstrapReport, raw, checks: bootstrapReport.checks || [] };
+}
+
+/**
+ * Assess two-tier readiness from bootstrap check results.
+ * @param {Array<{id: string, status: string}>} checks
+ * @returns {{ pilotReady: boolean, broadReady: boolean, pilotGaps: string[], broadGaps: string[] }}
+ */
+export function assessReadinessTier(checks) {
+  const checkMap = new Map(checks.map((c) => [c.id, c.status]));
+
+  const pilotGaps = [];
+  for (const id of PILOT_REQUIRED_CHECKS) {
+    const status = checkMap.get(id);
+    if (!status || status === "FAIL") {
+      pilotGaps.push(id);
+    }
+  }
+
+  const broadGaps = [];
+  for (const id of BROAD_REQUIRED_CHECKS) {
+    const status = checkMap.get(id);
+    if (!status || status === "FAIL" || status === "WARN") {
+      broadGaps.push(id);
+    }
+  }
+
+  return {
+    pilotReady: pilotGaps.length === 0,
+    broadReady: broadGaps.length === 0,
+    pilotGaps,
+    broadGaps,
+  };
+}
+
+/**
+ * Determine which commands are safe to run given current readiness.
+ * Maps to fallback-policy.md §3 degradation matrix.
+ * @param {Array<{id: string, status: string}>} checks
+ * @returns {{ allowed: string[], blocked: string[], warnings: string[] }}
+ */
+export function assessCapabilities(checks) {
+  const checkMap = new Map(checks.map((c) => [c.id, c.status]));
+  const allowed = [];
+  const blocked = [];
+  const warnings = [];
+
+  const cdpOk = checkMap.get("cdp") === "PASS";
+  const mcpOk = checkMap.get("mcp") === "PASS";
+  const extOk = checkMap.get("extension-bridge") === "PASS";
+  const configOk = checkMap.get("config") === "PASS";
+  const appOk = checkMap.get("comet-app") === "PASS";
+
+  if (cdpOk && appOk && configOk) {
+    allowed.push(
+      "session",
+      "browse",
+      "search",
+      "scrape",
+      "interact",
+      "screenshot",
+      "pdf",
+      "network",
+      "monitor",
+      "keepalive",
+      "auto"
+    );
+  } else if (!cdpOk) {
+    blocked.push(
+      "session",
+      "browse",
+      "search",
+      "scrape",
+      "interact",
+      "screenshot",
+      "pdf",
+      "network",
+      "monitor",
+      "keepalive",
+      "auto"
+    );
+  } else {
+    blocked.push("Core browser commands (missing app binary or config)");
+  }
+
+  if (cdpOk && extOk) {
+    allowed.push("tab-groups (create/list/update/delete)");
+    allowed.push("multi-agent isolation (isolateGroups)");
+  } else if (cdpOk && !extOk) {
+    blocked.push("tab-groups (create/list/update/delete)");
+    blocked.push("multi-agent isolation (isolateGroups)");
+    warnings.push("Extension bridge not loaded — tab group and multi-agent isolation unavailable");
+  }
+
+  if (cdpOk && !extOk) {
+    // Title-prefix ownership still works without extension (fallback-policy §2.2)
+    allowed.push("multi-agent title-prefix ownership (degraded)");
+  }
+
+  if (!mcpOk) {
+    warnings.push("comet-mcp not built — MCP tools unavailable, CLI fallback required");
+  } else {
+    allowed.push("mcp-tools (comet_connect, comet_ask, comet_poll, etc.)");
+  }
+
+  // Lifecycle sync is best-effort; never blocks execution (fallback-policy §2.5)
+  allowed.push("lifecycle-sync (best-effort)");
+
+  return { allowed, blocked, warnings };
+}
+
+/**
+ * Derive boolean capability flags from a readiness checks array.
+ * Accepts either { checks: [...] } or a full report with { bootstrap: { checks: [...] } }.
+ * Used by tests and other modules for quick gating decisions.
+ *
+ * @param {{ checks?: Array, bootstrap?: { checks: Array } }} report
+ * @returns {{ isCoreReady: boolean, isTabGroupReady: boolean, isMCPReady: boolean, isMultiAgentReady: boolean }}
+ */
+export function getCapabilityMatrix(report) {
+  const checks = report?.checks || report?.bootstrap?.checks || [];
+  const checkMap = new Map(checks.map((c) => [c.id, c.status]));
+
+  const cometAppOk = checkMap.get("comet-app") === "PASS";
+  const configOk = checkMap.get("config") === "PASS";
+  const outputOk = checkMap.get("output-dirs") === "PASS" || checkMap.get("output-dirs") === "WARN";
+  const cdpOk = checkMap.get("cdp") === "PASS";
+  const mcpOk = checkMap.get("mcp") === "PASS";
+  const extOk = checkMap.get("extension-bridge") === "PASS";
+
+  const isCoreReady = cometAppOk && configOk && outputOk;
+  const isTabGroupReady = cdpOk && extOk;
+  const isMCPReady = mcpOk;
+  const isMultiAgentReady = isCoreReady && cdpOk && isTabGroupReady;
+
+  return { isCoreReady, isTabGroupReady, isMCPReady, isMultiAgentReady };
+}
+
+/**
+ * Alias: run bootstrap checks and return structured report.
+ * @param {{ cometBridgeRoot?: string, port?: number }} [opts]
+ * @returns {object} Readiness report from generateReadinessReport
+ */
+export function runReadinessChecks(opts = {}) {
+  return generateReadinessReport({ ...opts, persist: false, includeTelemetry: false });
+}
+
+/**
+ * Resolve the audit output directory for persisting reports.
+ * Falls back to <COMET_BRIDGE_ROOT>/output/audit if config is unavailable.
+ */
+function resolveAuditDir() {
+  try {
+    // Attempt synchronous read of comet-config for the audit path.
+    // Config is ESM-only so we rely on env-based override or default path.
+    const envBase = process.env.COMET_OUTPUT_BASE;
+    if (envBase) return join(envBase, "audit");
+  } catch {
+    /* ignore */
+  }
+  return join(COMET_BRIDGE_ROOT, "output", "audit");
+}
+
+/**
+ * Generate the full readiness report.
+ *
+ * By default the report JSON is persisted to the audit directory for
+ * downstream consumption (S070-T019 telemetry, verification evidence).
+ * Pass `persist: false` to skip file writes.
+ *
+ * @param {{ port?: number, autoStart?: boolean, persist?: boolean, outPath?: string, includeTelemetry?: boolean, telemetryMaxAgeDays?: number }} [opts]
+ * @returns {object} Readiness report
+ */
+export function generateReadinessReport(opts = {}) {
+  const { bootstrapReport } = runBootstrapChecks(opts);
+  const checks = bootstrapReport.checks || [];
+  const tier = assessReadinessTier(checks);
+  const capabilities = assessCapabilities(checks);
+
+  const readinessTier = tier.broadReady ? "Broad" : tier.pilotReady ? "Pilot" : "Not Ready";
+
+  const telemetry =
+    opts.includeTelemetry !== false
+      ? collectTelemetrySummary({ maxAgeDays: opts.telemetryMaxAgeDays })
+      : null;
+
+  const report = {
+    reportVersion: "2.0.0",
+    spec: "S070-T007+T019",
+    timestamp: new Date().toISOString(),
+    cometBridgeRoot: COMET_BRIDGE_ROOT,
+    bootstrap: bootstrapReport,
+    readiness: {
+      tier: readinessTier,
+      pilotReady: tier.pilotReady,
+      broadReady: tier.broadReady,
+      pilotGaps: tier.pilotGaps,
+      broadGaps: tier.broadGaps,
+    },
+    capabilities,
+    telemetry,
+    reportPath: null,
+  };
+
+  // Persist by default unless explicitly disabled
+  if (opts.persist !== false) {
+    try {
+      const outPath =
+        opts.outPath ||
+        (() => {
+          const auditDir = resolveAuditDir();
+          mkdirSync(auditDir, { recursive: true });
+          const ts = new Date().toISOString().replace(/[:.]/g, "-");
+          return join(auditDir, `readiness-report-${ts}.json`);
+        })();
+      mkdirSync(dirname(outPath), { recursive: true });
+      writeFileSync(outPath, JSON.stringify(report, null, 2));
+      report.reportPath = outPath;
+    } catch {
+      // Non-fatal: report generation succeeds even if file write fails
+    }
+  }
+
+  return report;
+}
+
+function printHumanReport(report) {
+  const tierIcon = { Broad: "\u2705", Pilot: "\u26A0\uFE0F", "Not Ready": "\u274C" };
+
+  console.log("");
+  console.log("=== Comet Toolkit Readiness Report ===");
+  console.log(`Spec: S070-T007 | Generated: ${report.timestamp}`);
+  console.log(`Root: ${report.cometBridgeRoot}`);
+  console.log("");
+
+  console.log("--- Bootstrap Checks ---");
+  const statusIcon = { PASS: "\u2705", FAIL: "\u274C", WARN: "\u26A0\uFE0F", SKIP: "\u23ED\uFE0F" };
+  for (const check of report.bootstrap.checks) {
+    console.log(`  ${statusIcon[check.status] || "?"}  [${check.id}] ${check.message}`);
+  }
+  console.log("");
+
+  console.log("--- Readiness Tier ---");
+  console.log(`  ${tierIcon[report.readiness.tier] || "?"}  ${report.readiness.tier}`);
+  if (report.readiness.tier === "Pilot") {
+    console.log(`     Pilot: READY (core checks pass)`);
+    console.log(`     Broad: NOT READY — gaps: ${report.readiness.broadGaps.join(", ")}`);
+  } else if (report.readiness.tier === "Not Ready") {
+    console.log(`     Pilot: NOT READY — gaps: ${report.readiness.pilotGaps.join(", ")}`);
+    console.log(`     Broad: NOT READY — gaps: ${report.readiness.broadGaps.join(", ")}`);
+  } else {
+    console.log(`     Pilot: READY`);
+    console.log(`     Broad: READY`);
+  }
+  console.log("");
+
+  console.log("--- Capability Matrix ---");
+  if (report.capabilities.allowed.length > 0) {
+    console.log("  Allowed:");
+    for (const cap of report.capabilities.allowed) console.log(`    \u2705  ${cap}`);
+  }
+  if (report.capabilities.blocked.length > 0) {
+    console.log("  Blocked:");
+    for (const cap of report.capabilities.blocked) console.log(`    \u274C  ${cap}`);
+  }
+  if (report.capabilities.warnings.length > 0) {
+    console.log("  Warnings:");
+    for (const w of report.capabilities.warnings) console.log(`    \u26A0\uFE0F  ${w}`);
+  }
+  console.log("");
+
+  // --- Telemetry Summary (S070-T019) ---
+  if (report.telemetry) {
+    printTelemetrySummary(report.telemetry);
+  }
+
+  if (report.reportPath) {
+    console.log(`Report saved: ${report.reportPath}`);
+    console.log("");
+  }
+}
+
+function printTelemetrySummary(t) {
+  console.log("--- Operational Telemetry (S070-T019) ---");
+  console.log(
+    `  Period: last ${t.period.maxAgeDays} days | ${t.period.eventsAnalyzed} events | ${t.period.auditSessionsAnalyzed} audit sessions`
+  );
+  console.log("");
+
+  if (t.routes.total > 0) {
+    console.log("  Route Usage:");
+    for (const [route, count] of Object.entries(t.routes.counts)) {
+      if (count > 0) {
+        const pct = ((count / t.routes.total) * 100).toFixed(1);
+        const bar = "\u2588".repeat(Math.max(1, Math.round((count / t.routes.total) * 20)));
+        console.log(`    ${route.padEnd(12)} ${String(count).padStart(4)}  (${pct}%)  ${bar}`);
+      }
+    }
+    console.log(`    Primary route: ${t.routes.primary}`);
+  } else {
+    console.log("  Route Usage: no events recorded");
+  }
+  console.log("");
+
+  console.log("  Fallback Status:");
+  if (t.fallbacks.total > 0) {
+    const rateStr = (t.fallbacks.rate * 100).toFixed(1);
+    console.log(
+      `    Evaluated: ${t.fallbacks.total} | Triggered: ${t.fallbacks.triggered} (${rateStr}%)`
+    );
+    if (Object.keys(t.fallbacks.reasons).length > 0) {
+      console.log("    Reasons:");
+      for (const [reason, count] of Object.entries(t.fallbacks.reasons)) {
+        console.log(`      - ${reason}: ${count}`);
+      }
+    }
+  } else {
+    console.log("    No fallback events recorded");
+  }
+  console.log("");
+
+  console.log("  Ownership Checks:");
+  if (t.ownership.total > 0) {
+    const vRateStr = (t.ownership.violationRate * 100).toFixed(1);
+    console.log(
+      `    Total: ${t.ownership.total} | Passed: ${t.ownership.counts.passed} | Failed: ${t.ownership.counts.failed} | Skipped: ${t.ownership.counts.skipped}`
+    );
+    console.log(`    Violation rate: ${vRateStr}%`);
+  } else {
+    console.log("    No ownership check events recorded");
+  }
+  console.log("");
+
+  console.log("  Completion Stats:");
+  if (t.completions.total > 0) {
+    const sRateStr = (t.completions.successRate * 100).toFixed(1);
+    console.log(
+      `    Total: ${t.completions.total} | Completed: ${t.completions.counts.completed} | Failed: ${t.completions.counts.failed} | Aborted: ${t.completions.counts.aborted}`
+    );
+    console.log(`    Success rate: ${sRateStr}%`);
+    if (t.completions.avgDurationMs !== null) {
+      const sec = (t.completions.avgDurationMs / 1000).toFixed(1);
+      console.log(`    Avg duration: ${sec}s`);
+    }
+  } else {
+    console.log("    No completion events recorded");
+  }
+
+  if (t.auditSessions.total > 0) {
+    console.log("");
+    console.log("  Audit Sessions:");
+    console.log(
+      `    Total: ${t.auditSessions.total} | Completed: ${t.auditSessions.completed} | Failed: ${t.auditSessions.failed} | Active: ${t.auditSessions.active}`
+    );
+  }
+
+  console.log("");
+}
+
+// ---------- CLI entrypoint ----------
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const jsonFlag = argv.includes("--json");
+  const helpFlag = argv.includes("--help") || argv.includes("-h");
+  const noPersist = argv.includes("--no-persist");
+  const noTelemetry = argv.includes("--no-telemetry");
+  const saveIdx = argv.indexOf("--save");
+  const savePath = saveIdx !== -1 && saveIdx + 1 < argv.length ? argv[saveIdx + 1] : undefined;
+  const portIdx = argv.indexOf("--port");
+  const port =
+    portIdx !== -1 && portIdx + 1 < argv.length ? parseInt(argv[portIdx + 1], 10) : undefined;
+  const daysIdx = argv.indexOf("--telemetry-days");
+  const telemetryDays =
+    daysIdx !== -1 && daysIdx + 1 < argv.length ? parseInt(argv[daysIdx + 1], 10) : undefined;
+
+  if (helpFlag) {
+    console.error(`Comet Toolkit Readiness Report (Spec 070, S070-T007)
+
+Usage:
+  node scripts/readiness-report.mjs [options]
+
+Options:
+  --json              Machine-readable JSON output
+  --save <path>       Save report to a specific file (JSON)
+  --no-persist        Skip automatic persistence to audit directory
+  --no-telemetry      Omit operational telemetry section
+  --telemetry-days N  Telemetry lookback window (default: 7)
+  --port <n>          CDP port override
+  --auto-start        Attempt Comet auto-start if CDP unreachable
+  --help              Show this help
+
+Readiness tiers (per clarification C3):
+  Pilot  — core checks pass (app, CDP, config, output dirs)
+  Broad  — all checks pass (including MCP build and extension bridge)
+
+Exit codes:
+  0  Broad-ready (all checks pass)
+  1  Not ready (critical failures)
+  2  Pilot-only (warnings for non-critical checks)`);
+    process.exit(0);
+  }
+
+  const autoStart = argv.includes("--auto-start");
+  const report = generateReadinessReport({
+    port,
+    autoStart,
+    persist: !noPersist,
+    outPath: savePath,
+    includeTelemetry: !noTelemetry,
+    telemetryMaxAgeDays: telemetryDays,
+  });
+
+  if (jsonFlag) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printHumanReport(report);
+  }
+
+  if (report.readiness.tier === "Not Ready") process.exit(1);
+  if (report.readiness.tier === "Pilot") process.exit(2);
+  process.exit(0);
+}
+
+const isMainModule =
+  process.argv[1] &&
+  (process.argv[1].endsWith("readiness-report.mjs") ||
+    process.argv[1] === fileURLToPath(import.meta.url));
+
+if (isMainModule) {
+  main();
+}