@h-rig/run-plugin 0.0.6-alpha.186

package/dist/src/read-model/runs-screen.js

@@ -0,0 +1,217 @@
+// @bun
+// packages/run-plugin/src/read-model/runs-screen.ts
+import {
+  DRONE_WIDTH,
+  RIG_SPINNER_FRAMES,
+  accent,
+  bold,
+  ink,
+  ink2,
+  ink3,
+  ink4,
+  phaseGlyph,
+  red,
+  renderDroneFrame,
+  statusRoleColor
+} from "@rig/std-shared/board-theme";
+var MAX_VISIBLE = 16;
+function createRunsBoardView(host, deps) {
+  const { truncateToWidth, matchesKey } = deps;
+  let runs = [];
+  let selected = 0;
+  let loading = true;
+  let error = null;
+  let tick = 0;
+  let filter = "";
+  let sortMode = "active";
+  function visibleRuns() {
+    const query = filter.trim().toLowerCase();
+    const filtered = query ? runs.filter((run) => run.runId.toLowerCase().includes(query) || run.status.toLowerCase().includes(query) || run.title.toLowerCase().includes(query)) : [...runs];
+    if (sortMode === "active") {
+      return filtered.map((run, index) => ({ run, index })).sort((a, b) => a.run.rank - b.run.rank || a.index - b.index).map((entry) => entry.run);
+    }
+    if (sortMode === "status") {
+      return filtered.map((run, index) => ({ run, index })).sort((a, b) => a.run.status.localeCompare(b.run.status) || a.index - b.index).map((entry) => entry.run);
+    }
+    return filtered;
+  }
+  function clampSelection() {
+    selected = Math.max(0, Math.min(selected, Math.max(0, visibleRuns().length - 1)));
+  }
+  function moveSelection(delta) {
+    const visible = visibleRuns();
+    if (visible.length === 0)
+      return;
+    selected = Math.max(0, Math.min(visible.length - 1, selected + delta));
+  }
+  function selectedRun() {
+    return visibleRuns()[selected] ?? null;
+  }
+  function setFilter(next) {
+    filter = next;
+    clampSelection();
+  }
+  function cycleSort() {
+    sortMode = sortMode === "active" ? "recent" : sortMode === "recent" ? "status" : "active";
+    clampSelection();
+    return sortMode;
+  }
+  function droneBoardLines(width, message, messageWidth) {
+    const spinner = RIG_SPINNER_FRAMES[tick % RIG_SPINNER_FRAMES.length];
+    if (width < DRONE_WIDTH + 4) {
+      return ["", ` ${accent(spinner)} ${ink3(message)}`, ""];
+    }
+    const pad = " ".repeat(Math.max(0, Math.floor((width - DRONE_WIDTH) / 2)));
+    const msgPad = " ".repeat(Math.max(0, Math.floor((width - messageWidth) / 2)));
+    return [
+      "",
+      ...renderDroneFrame(tick).map((line) => pad + line),
+      "",
+      `${msgPad}${accent(spinner)} ${ink3(message)}`,
+      ""
+    ];
+  }
+  function renderLines(width) {
+    if (loading) {
+      return droneBoardLines(width, "contacting the fleet\u2026", 24);
+    }
+    if (error) {
+      return ["", ` ${red("runs unavailable:")} ${ink2(error)}`, ""];
+    }
+    const visible = visibleRuns();
+    if (runs.length === 0) {
+      return droneBoardLines(width, "no runs yet \u2014 n picks a task and launches one", 44);
+    }
+    if (visible.length === 0) {
+      return ["", ` ${ink2("no runs match")} ${accent(`/${filter}`)} ${ink3("\u2014 esc clears the filter")}`, ""];
+    }
+    const start = Math.max(0, Math.min(selected - Math.floor(MAX_VISIBLE / 2), visible.length - MAX_VISIBLE));
+    const window = visible.slice(start, start + MAX_VISIBLE);
+    const lines = window.map((run, index) => {
+      const isSelected = start + index === selected;
+      const color = statusRoleColor(run.role);
+      const dot = color(phaseGlyph(run.phase));
+      const id = run.runId.slice(0, 8);
+      const status = color(run.status.padEnd(16));
+      const title = truncateToWidth(run.title, Math.max(8, width - 36));
+      const row = ` ${dot} ${isSelected ? bold(ink(id)) : ink3(id)}  ${status} ${isSelected ? ink(title) : ink2(title)}`;
+      return isSelected ? accent("\u258C") + row : " " + row;
+    });
+    const meta = [];
+    if (visible.length > MAX_VISIBLE)
+      meta.push(`${selected + 1}/${visible.length}`);
+    if (filter)
+      meta.push(`filter: ${filter}`);
+    meta.push(`sort: ${sortMode}`);
+    lines.push(ink4(`   ${meta.join("  \xB7  ")}`));
+    return ["", ...lines, ""];
+  }
+  function handleInput(data) {
+    const enc = (value) => encodeURIComponent(value);
+    if (matchesKey(data, "up") || data === "k") {
+      moveSelection(-1);
+      host.requestRender();
+      return true;
+    }
+    if (matchesKey(data, "down") || data === "j") {
+      moveSelection(1);
+      host.requestRender();
+      return true;
+    }
+    if (matchesKey(data, "enter") || matchesKey(data, "return")) {
+      const run = selectedRun();
+      if (run)
+        host.act(`run-detail:${enc(run.runId)}`);
+      return true;
+    }
+    if (data === "a") {
+      const run = selectedRun();
+      if (run)
+        host.attach(run.runId);
+      return true;
+    }
+    if (data === "s") {
+      const run = selectedRun();
+      if (run)
+        host.openSteer(run.runId);
+      return true;
+    }
+    if (data === "p") {
+      const run = selectedRun();
+      if (run) {
+        host.setNotice(`pause requested for ${run.runId.slice(0, 8)}\u2026`);
+        host.act(`run-pause:${enc(run.runId)}`);
+      }
+      return true;
+    }
+    if (data === "u") {
+      const run = selectedRun();
+      if (run) {
+        host.setNotice(`resume requested for ${run.runId.slice(0, 8)}\u2026`);
+        host.act(`run-resume:${enc(run.runId)}`);
+      }
+      return true;
+    }
+    if (data === "x") {
+      const run = selectedRun();
+      if (run) {
+        host.setNotice(`stop requested for ${run.runId.slice(0, 8)}\u2026`);
+        host.act(`run-stop:${enc(run.runId)}`);
+      }
+      return true;
+    }
+    if (data === "n") {
+      host.navigate("tasks");
+      return true;
+    }
+    if (data === "/") {
+      host.openSearch(filter, setFilter);
+      return true;
+    }
+    if (data === "o") {
+      const mode = cycleSort();
+      host.setNotice(`sorted: ${mode}`);
+      host.requestRender();
+      return true;
+    }
+    if (matchesKey(data, "escape")) {
+      if (filter) {
+        setFilter("");
+        host.requestRender();
+        return true;
+      }
+      return false;
+    }
+    return false;
+  }
+  return {
+    render(width) {
+      return renderLines(width).map((line) => truncateToWidth(line, Math.max(10, width - 1)));
+    },
+    handleInput,
+    setBoard(board) {
+      if (board.kind !== "runs")
+        return;
+      const previous = selectedRun()?.runId;
+      runs = [...board.runs];
+      if (previous) {
+        const index = visibleRuns().findIndex((run) => run.runId === previous);
+        if (index >= 0)
+          selected = index;
+      }
+      clampSelection();
+      loading = false;
+      error = null;
+    },
+    setError(next) {
+      error = next;
+    },
+    setTick(next) {
+      tick = next;
+    },
+    invalidate() {}
+  };
+}
+export {
+  createRunsBoardView
+};

package/dist/src/read-model/session-journal.d.ts

@@ -0,0 +1,26 @@
+import { type RigRunTimelineEntry, type RunInboxResolutionSentinel, type RunJournalProjection, type RunSessionCustomEntry, type RunSessionJournalCodec, type RunStatus } from "@rig/contracts";
+export declare function isTerminalRunStatus(status: RunStatus): boolean;
+export declare function sessionIdFromSessionFile(sessionPath: string | null | undefined): string | null;
+export declare function foldRunSessionEntries(entries: ReadonlyArray<RunSessionCustomEntry>, runId: string): RunJournalProjection;
+export declare function projectRunFromSession(source: {
+    getEntries(): ReadonlyArray<RunSessionCustomEntry>;
+} | ReadonlyArray<RunSessionCustomEntry>, runId: string): RunJournalProjection;
+export declare function timelineEntriesFromCustomEntries(entries: readonly RunSessionCustomEntry[]): readonly RigRunTimelineEntry[];
+export declare function latestTimelineEntriesFromCustomEntries(entries: readonly RunSessionCustomEntry[], limit: number): readonly RigRunTimelineEntry[];
+export declare function parseStopSentinel(text: string, expectedRunId: string): {
+    reason: string | null;
+} | null;
+export declare function parsePauseSentinel(text: string, expectedRunId: string): {
+    requestedBy: string | null;
+} | null;
+export declare function parseResumeSentinel(text: string, expectedRunId: string): {
+    requestedBy: string | null;
+} | null;
+export declare function parseInboxResolutionSentinel(text: string, expectedRunId: string): RunInboxResolutionSentinel | null;
+/**
+ * The read-only run-session journal codec, packaged as the `RUN_SESSION_JOURNAL`
+ * capability value. Workflow fact APPENDS (rig.workflow.*) are NOT here: a
+ * read-only projection plugin must not write a status journal (arch Law 1), so
+ * the workflow journal WRITER capability is owned by the run-worker writer owner.
+ */
+export declare const runSessionJournalCodec: RunSessionJournalCodec;

package/dist/src/read-model/session-journal.js

@@ -0,0 +1,355 @@
+// @bun
+// packages/run-plugin/src/read-model/session-journal.ts
+import { Schema } from "effect";
+import {
+  CUSTOM_TYPE_FOR,
+  RIG_CONTROL_SENTINEL_END,
+  RIG_INBOX_RESOLUTION_SENTINEL,
+  RIG_PAUSE_SENTINEL,
+  RIG_RESUME_SENTINEL,
+  RIG_STOP_SENTINEL,
+  RIG_STOP_SENTINEL_END,
+  RunJournalEvent,
+  TYPE_FOR_CUSTOM
+} from "@rig/contracts";
+var decodeRunJournalEvent = (value) => Schema.decodeUnknownSync(RunJournalEvent)(value);
+var RUN_STATUS_TRANSITIONS = {
+  created: ["queued", "preparing", "running", "failed", "stopped"],
+  queued: ["preparing", "running", "failed", "stopped"],
+  preparing: ["queued", "running", "needs-attention", "failed", "stopped"],
+  running: [
+    "queued",
+    "waiting-approval",
+    "waiting-user-input",
+    "paused",
+    "validating",
+    "reviewing",
+    "closing-out",
+    "needs-attention",
+    "completed",
+    "failed",
+    "stopped"
+  ],
+  "waiting-approval": ["running", "needs-attention", "failed", "stopped"],
+  "waiting-user-input": ["running", "needs-attention", "failed", "stopped"],
+  paused: ["running", "failed", "stopped"],
+  validating: ["running", "reviewing", "closing-out", "needs-attention", "completed", "failed", "stopped"],
+  reviewing: ["running", "validating", "closing-out", "needs-attention", "completed", "failed", "stopped"],
+  "closing-out": ["running", "needs-attention", "completed", "failed", "stopped"],
+  "needs-attention": ["queued", "preparing", "running", "closing-out", "completed", "failed", "stopped"],
+  completed: [],
+  failed: ["queued", "preparing", "running", "closing-out"],
+  stopped: ["queued", "preparing", "running", "closing-out"]
+};
+var TERMINAL_RUN_STATUSES = ["completed", "failed", "stopped"];
+function isTerminalRunStatus(status) {
+  return TERMINAL_RUN_STATUSES.includes(status);
+}
+function canTransitionRunStatus(from, to) {
+  if (from === null)
+    return true;
+  if (from === to)
+    return true;
+  return RUN_STATUS_TRANSITIONS[from].includes(to);
+}
+function assertRunStatusTransition(from, to) {
+  if (!canTransitionRunStatus(from, to)) {
+    throw new Error(`Illegal run status transition: ${from ?? "(none)"} -> ${to}. ` + `Allowed from ${from ?? "(none)"}: ${from ? RUN_STATUS_TRANSITIONS[from].join(", ") : "(any)"}.`);
+  }
+}
+function reduceRunJournal(events, runId = null) {
+  let record = {};
+  let status = null;
+  const statusHistory = [];
+  const pendingApprovals = new Map;
+  const resolvedApprovals = [];
+  const pendingUserInputs = new Map;
+  const resolvedUserInputs = [];
+  const closeoutPhases = [];
+  let resolvedPipeline = null;
+  const stageOutcomes = [];
+  const anomalies = [];
+  let steeringCount = 0;
+  let stallCount = 0;
+  let lastSeq = 0;
+  let lastEventAt = null;
+  const projectedRunId = runId ?? events[0]?.runId ?? null;
+  for (const event of events) {
+    lastSeq = event.seq;
+    lastEventAt = event.at;
+    switch (event.type) {
+      case "status-changed": {
+        if (!canTransitionRunStatus(status, event.to)) {
+          anomalies.push({ seq: event.seq, kind: "illegal-transition", detail: `${status ?? "(none)"} -> ${event.to}` });
+        }
+        statusHistory.push({ seq: event.seq, at: event.at, from: status, to: event.to, reason: event.reason ?? null });
+        const wasTerminal = status !== null && isTerminalRunStatus(status);
+        status = event.to;
+        record = { ...record, updatedAt: event.at };
+        if (isTerminalRunStatus(event.to) && !record.completedAt)
+          record = { ...record, completedAt: event.at };
+        if (!isTerminalRunStatus(event.to) && wasTerminal)
+          record = { ...record, completedAt: null };
+        if (event.to === "running" && !record.startedAt)
+          record = { ...record, startedAt: event.at };
+        break;
+      }
+      case "record-patch": {
+        const next = { ...record };
+        for (const [key, value] of Object.entries(event.patch)) {
+          if (value !== undefined)
+            next[key] = value;
+        }
+        next.updatedAt = event.patch.updatedAt ?? event.at;
+        record = next;
+        break;
+      }
+      case "approval-requested": {
+        pendingApprovals.set(event.requestId, {
+          requestId: event.requestId,
+          requestKind: event.requestKind,
+          actionId: event.actionId ?? null,
+          payload: event.payload,
+          requestedAt: event.at
+        });
+        break;
+      }
+      case "approval-resolved": {
+        const pending = pendingApprovals.get(event.requestId);
+        if (!pending) {
+          const alreadyResolved = resolvedApprovals.some((entry) => entry.requestId === event.requestId);
+          anomalies.push({ seq: event.seq, kind: alreadyResolved ? "duplicate-resolution" : "unknown-request", detail: `approval ${event.requestId}` });
+          break;
+        }
+        pendingApprovals.delete(event.requestId);
+        resolvedApprovals.push({ ...pending, decision: event.decision, note: event.note ?? null, actor: event.actor, resolvedAt: event.at });
+        break;
+      }
+      case "input-requested": {
+        pendingUserInputs.set(event.requestId, {
+          requestId: event.requestId,
+          requestKind: "user-input",
+          actionId: null,
+          payload: event.payload,
+          requestedAt: event.at
+        });
+        break;
+      }
+      case "input-resolved": {
+        const pending = pendingUserInputs.get(event.requestId);
+        if (!pending) {
+          const alreadyResolved = resolvedUserInputs.some((entry) => entry.requestId === event.requestId);
+          anomalies.push({ seq: event.seq, kind: alreadyResolved ? "duplicate-resolution" : "unknown-request", detail: `user-input ${event.requestId}` });
+          break;
+        }
+        pendingUserInputs.delete(event.requestId);
+        resolvedUserInputs.push({ ...pending, answers: event.answers, actor: event.actor, resolvedAt: event.at });
+        break;
+      }
+      case "steering":
+        steeringCount += 1;
+        break;
+      case "adopted":
+        record = { ...record, pid: event.pid, updatedAt: event.at };
+        break;
+      case "stall-detected":
+        stallCount += 1;
+        break;
+      case "closeout-phase":
+        closeoutPhases.push({ seq: event.seq, at: event.at, phase: event.phase, outcome: event.outcome, detail: event.detail ?? null });
+        break;
+      case "pipeline-resolved":
+        resolvedPipeline = event.pipeline;
+        break;
+      case "stage-outcome":
+        stageOutcomes.push({ seq: event.seq, at: event.at, outcome: event.outcome });
+        break;
+      case "timeline-entry":
+      case "log-entry":
+        break;
+    }
+  }
+  return {
+    runId: projectedRunId,
+    record,
+    status,
+    statusHistory,
+    pendingApprovals: [...pendingApprovals.values()],
+    resolvedApprovals,
+    pendingUserInputs: [...pendingUserInputs.values()],
+    resolvedUserInputs,
+    steeringCount,
+    stallCount,
+    closeoutPhases,
+    resolvedPipeline,
+    stageOutcomes,
+    lastSeq,
+    lastEventAt,
+    anomalies
+  };
+}
+function sessionIdFromSessionFile(sessionPath) {
+  if (!sessionPath)
+    return null;
+  const file = sessionPath.split(/[\\/]/).pop() ?? "";
+  const match = file.match(/_([0-9a-fA-F][0-9a-fA-F-]{7,})\.jsonl$/);
+  return match?.[1] ?? null;
+}
+function isRunSessionCustomType(customType) {
+  return customType !== undefined && Object.hasOwn(TYPE_FOR_CUSTOM, customType);
+}
+function foldRunSessionEntries(entries, runId) {
+  const events = [];
+  entries.forEach((entry, index) => {
+    if (entry.type !== "custom" || !isRunSessionCustomType(entry.customType))
+      return;
+    const data = entry.data !== null && typeof entry.data === "object" ? entry.data : {};
+    const stamped = {
+      v: 1,
+      seq: index + 1,
+      at: typeof data.at === "string" ? data.at : new Date(0).toISOString(),
+      runId,
+      ...data,
+      type: TYPE_FOR_CUSTOM[entry.customType]
+    };
+    try {
+      events.push(decodeRunJournalEvent(stamped));
+    } catch {}
+  });
+  return reduceRunJournal(events, runId);
+}
+function projectRunFromSession(source, runId) {
+  const entries = "getEntries" in source ? source.getEntries() : source;
+  return foldRunSessionEntries(entries, runId);
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function timelineEntryFromCustomEntry(entry) {
+  if (entry.customType !== CUSTOM_TYPE_FOR["timeline-entry"] || !isRecord(entry.data))
+    return null;
+  const payload = isRecord(entry.data.payload) ? entry.data.payload : entry.data;
+  const type = typeof payload.type === "string" ? payload.type : "timeline";
+  const stage = typeof payload.stage === "string" ? payload.stage : typeof payload.name === "string" ? payload.name : null;
+  const status = typeof payload.status === "string" ? payload.status : typeof payload.outcome === "string" ? payload.outcome : null;
+  const detail = typeof payload.detail === "string" ? payload.detail : typeof payload.message === "string" ? payload.message : null;
+  const at = typeof entry.data.at === "string" ? entry.data.at : typeof payload.at === "string" ? payload.at : null;
+  return { at, type, stage, status, detail };
+}
+function timelineEntriesFromCustomEntries(entries) {
+  return entries.flatMap((entry) => {
+    const timelineEntry = timelineEntryFromCustomEntry(entry);
+    return timelineEntry ? [timelineEntry] : [];
+  });
+}
+function latestTimelineEntriesFromCustomEntries(entries, limit) {
+  if (limit <= 0)
+    return [];
+  const timeline = [];
+  for (let index = entries.length - 1;index >= 0 && timeline.length < limit; index -= 1) {
+    const timelineEntry = timelineEntryFromCustomEntry(entries[index]);
+    if (timelineEntry)
+      timeline.push(timelineEntry);
+  }
+  timeline.reverse();
+  return timeline;
+}
+function parseStopSentinel(text, expectedRunId) {
+  const start = text.indexOf(RIG_STOP_SENTINEL);
+  if (start < 0)
+    return null;
+  const end = text.indexOf(RIG_STOP_SENTINEL_END, start);
+  const body = text.slice(start + RIG_STOP_SENTINEL.length, end >= 0 ? end : undefined).trim();
+  const runId = body.match(/(?:^|\s)runId=([^\s>]+)/)?.[1] ?? "";
+  if (runId && runId !== expectedRunId)
+    return null;
+  const reason = body.match(/(?:^|\s)reason=(.+)$/)?.[1]?.trim() ?? null;
+  return { reason };
+}
+function parseControlSentinel(marker, text, expectedRunId) {
+  const start = text.indexOf(marker);
+  if (start < 0)
+    return null;
+  const end = text.indexOf(RIG_CONTROL_SENTINEL_END, start);
+  const body = text.slice(start + marker.length, end >= 0 ? end : undefined).trim();
+  const runId = body.match(/(?:^|\s)runId=([^\s>]+)/)?.[1] ?? "";
+  if (runId && runId !== expectedRunId)
+    return null;
+  const requestedBy = body.match(/(?:^|\s)requestedBy=([^\s>]+)/)?.[1] ?? null;
+  return { requestedBy };
+}
+function parsePauseSentinel(text, expectedRunId) {
+  return parseControlSentinel(RIG_PAUSE_SENTINEL, text, expectedRunId);
+}
+function parseResumeSentinel(text, expectedRunId) {
+  return parseControlSentinel(RIG_RESUME_SENTINEL, text, expectedRunId);
+}
+function decodeInboxResolutionPayload(payload) {
+  try {
+    const parsed = JSON.parse(decodeURIComponent(payload));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return null;
+    const record = parsed;
+    if (record.kind === "approval") {
+      const requestId = typeof record.requestId === "string" ? record.requestId.trim() : "";
+      const decision = record.decision === "approve" || record.decision === "reject" ? record.decision : null;
+      const note = typeof record.note === "string" ? record.note : record.note === null ? null : undefined;
+      if (!requestId || !decision)
+        return null;
+      return { kind: "approval", requestId, decision, ...note !== undefined ? { note } : {} };
+    }
+    if (record.kind === "input") {
+      const requestId = typeof record.requestId === "string" ? record.requestId.trim() : "";
+      const answers = record.answers && typeof record.answers === "object" && !Array.isArray(record.answers) ? Object.fromEntries(Object.entries(record.answers).filter((entry) => typeof entry[1] === "string")) : null;
+      if (!requestId || !answers)
+        return null;
+      return { kind: "input", requestId, answers };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function parseInboxResolutionSentinel(text, expectedRunId) {
+  const start = text.indexOf(RIG_INBOX_RESOLUTION_SENTINEL);
+  if (start < 0)
+    return null;
+  const end = text.indexOf(RIG_CONTROL_SENTINEL_END, start);
+  const body = text.slice(start + RIG_INBOX_RESOLUTION_SENTINEL.length, end >= 0 ? end : undefined).trim();
+  const runId = body.match(/(?:^|\s)runId=([^\s>]+)/)?.[1] ?? "";
+  if (runId && runId !== expectedRunId)
+    return null;
+  const requestedBy = body.match(/(?:^|\s)requestedBy=([^\s>]+)/)?.[1] ?? null;
+  const payload = body.match(/(?:^|\s)data=([^\s>]+)/)?.[1] ?? "";
+  const decoded = decodeInboxResolutionPayload(payload);
+  if (!decoded)
+    return null;
+  return { ...decoded, requestedBy };
+}
+var runSessionJournalCodec = {
+  foldRunSessionEntries,
+  projectRunFromSession,
+  isTerminalRunStatus,
+  canTransitionRunStatus,
+  assertRunStatusTransition,
+  sessionIdFromSessionFile,
+  timelineEntriesFromCustomEntries,
+  latestTimelineEntriesFromCustomEntries,
+  parseStopSentinel,
+  parsePauseSentinel,
+  parseResumeSentinel,
+  parseInboxResolutionSentinel
+};
+export {
+  timelineEntriesFromCustomEntries,
+  sessionIdFromSessionFile,
+  runSessionJournalCodec,
+  projectRunFromSession,
+  parseStopSentinel,
+  parseResumeSentinel,
+  parsePauseSentinel,
+  parseInboxResolutionSentinel,
+  latestTimelineEntriesFromCustomEntries,
+  isTerminalRunStatus,
+  foldRunSessionEntries
+};

package/dist/src/read-model/stats-command.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `rig stats` CLI command — owned by run-plugin (it owns the
+ * RUN_STATS / RUN_READ_MODEL domain). Lazy-imported by plugin.ts so config-time
+ * stays light. Mechanical arg-parsing helpers live on the floor
+ * (@rig/std-shared/cli-args); table formatting is this plugin's own
+ * (./cli-format); the metric aggregation is the read-model capability's.
+ */
+import type { CommandOutcome, RigStatsData, RunRecord } from "@rig/contracts";
+import type { RuntimeCliContext } from "@rig/core/config";
+type StatsCommandDeps = {
+    listRuns?: (projectRoot: string) => Promise<readonly RunRecord[]>;
+};
+export declare function parseSinceOption(value: string | undefined, now?: Date): Date | null;
+export declare function formatStatsRows(stats: RigStatsData): Array<[string, unknown]>;
+export declare function executeStats(context: RuntimeCliContext, args: readonly string[], deps?: StatsCommandDeps): Promise<CommandOutcome>;
+export {};