muonroi-cli 1.2.3 → 1.3.1

package/src/ui/types.ts

@@ -0,0 +1,83 @@
+import type { Agent } from "../orchestrator/orchestrator.js";
+import type { PaymentSettings, SandboxMode, SandboxSettings } from "../utils/settings.js";
+
+export type ContextStats = {
+  contextWindow: number;
+  usedTokens: number;
+  remainingTokens: number;
+  ratioUsed: number;
+  ratioRemaining: number;
+};
+
+export type PasteBlock = {
+  id: number;
+  content: string;
+  lines: number;
+  isImage?: boolean;
+  clipboardBase64?: string;
+  clipboardMediaType?: string;
+};
+
+export type FileMentionBlock = { id: number; path: string };
+
+export type QueuedMessage = { text: string; displayText: string };
+
+export interface SandboxRow {
+  key: string;
+  label: string;
+  type: "toggle" | "text";
+  placeholder?: string;
+  getDisplay: (mode: SandboxMode, s: SandboxSettings) => string;
+  getOptions?: () => string[];
+  apply: (mode: SandboxMode, s: SandboxSettings, value: string) => { mode?: SandboxMode; settings?: SandboxSettings };
+}
+
+export interface WalletDisplayInfo {
+  address: string | null;
+  ethBalance: string | null;
+  usdcBalance: string | null;
+}
+
+export interface WalletRow {
+  key: string;
+  label: string;
+  type: "toggle" | "readonly";
+  getDisplay: (settings: Required<PaymentSettings>, info: WalletDisplayInfo) => string;
+  getOptions?: () => string[];
+  apply?: (settings: Required<PaymentSettings>, value: string) => Partial<PaymentSettings>;
+}
+
+export interface AppStartupConfig {
+  apiKey: string | undefined;
+  baseURL: string;
+  model: string;
+  sandboxMode: SandboxMode;
+  sandboxSettings: SandboxSettings;
+  maxToolRounds: number;
+  version: string;
+  /**
+   * TEST SEAM (Task 5.2): when true, dispatch a synthetic halt chunk after the
+   * TUI reaches its first idle state. Lets harness E2E specs verify the recovery
+   * card without triggering a real CB-3 sprint run.
+   * Never set this in production — only passed via --inject-halt CLI flag.
+   */
+  injectHalt?: boolean;
+}
+
+export interface AppProps {
+  agent: Agent;
+  startupConfig: AppStartupConfig;
+  initialMessage?: string;
+  onExit?: () => void;
+}
+
+export interface ActiveTurnState {
+  kind: "local" | "telegram";
+  agent: Agent;
+  modeColor?: string;
+  remoteKey?: string;
+  sourceLabel?: string;
+  userId?: number;
+  latestAssistantText: string;
+  flushedAssistantChars: number;
+}

package/src/ui/utils/color.ts

@@ -0,0 +1,19 @@
+export function withAlpha(color: string, alpha: number): string {
+  const normalized = color.trim();
+  const hex = normalized.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!hex) return color;
+
+  const body = hex[1];
+  const expanded =
+    body.length === 3
+      ? body
+          .split("")
+          .map((ch) => ch + ch)
+          .join("")
+      : body;
+
+  const alphaHex = Math.round(Math.max(0, Math.min(1, alpha)) * 255)
+    .toString(16)
+    .padStart(2, "0");
+  return `#${expanded}${alphaHex}`;
+}

package/src/ui/utils/format.ts

@@ -0,0 +1,86 @@
+import type { KeyEvent } from "@opentui/core";
+import type { ScheduleDaemonStatus, StoredSchedule } from "../../tools/schedule.js";
+import type { ChatEntry, CouncilQuestionData, ToolCall, ToolResult } from "../../types/index.js";
+import type { CouncilCardKey } from "../components/council-question-card.js";
+
+export function formatScheduleDetails(schedule: StoredSchedule, daemonStatus: ScheduleDaemonStatus): string {
+  const daemonText = daemonStatus.running
+    ? `running${daemonStatus.pid ? ` (pid ${daemonStatus.pid})` : ""}`
+    : "not running";
+  return [
+    `Schedule: ${schedule.name}`,
+    `ID: ${schedule.id}`,
+    `Type: ${schedule.cron ? "recurring" : "one-time"}`,
+    `Cron: ${schedule.cron ?? "runs once immediately"}`,
+    `Enabled: ${schedule.enabled ? "yes" : "no"}`,
+    `Model: ${schedule.model}`,
+    `Directory: ${schedule.directory}`,
+    `Last run: ${schedule.lastRunAt ?? "never"}`,
+    `Daemon: ${daemonText}`,
+    "",
+    "Instruction:",
+    schedule.instruction,
+  ].join("\n");
+}
+
+export function formatAnswerForLog(ans: { kind: string; text: string }): string {
+  if (ans.kind === "freetext") return ans.text || "(empty)";
+  if (ans.kind === "chat") return "[Chat about this]";
+  return ans.text;
+}
+
+export function buildAssistantEntry(content: string, extra?: Partial<ChatEntry>): ChatEntry {
+  return { type: "assistant", content, timestamp: new Date(), ...extra };
+}
+
+export function buildToolResultEntry(
+  toolCall: ToolCall,
+  toolResult: ToolResult,
+  extra?: Partial<ChatEntry>,
+): ChatEntry {
+  const output = toolResult.output ?? (toolResult.error ? `Error: ${toolResult.error}` : "");
+  return {
+    type: "tool_result",
+    content: typeof output === "string" ? output : String(output),
+    timestamp: new Date(),
+    toolCall,
+    toolResult,
+    ...extra,
+  };
+}
+
+export function buildUserEntry(content: string, extra?: Partial<ChatEntry>): ChatEntry {
+  return { type: "user", content, timestamp: new Date(), ...extra };
+}
+
+export function buildPreflightQuestion(pf: {
+  preflightId: string;
+  problemStatement: string;
+  participants: Array<{ role: string; model: string }>;
+}): CouncilQuestionData {
+  return {
+    questionId: pf.preflightId,
+    phase: "preflight",
+    question: `Approve discussion plan for: ${pf.problemStatement}`,
+    context: pf.participants.length > 0 ? `Participants: ${pf.participants.map((p) => p.role).join(", ")}` : undefined,
+    options: [
+      { label: "Approve", value: "approve", kind: "choice", description: "Start the debate now" },
+      { label: "Reject", value: "reject", kind: "choice", description: "Cancel and rewrite the topic" },
+    ],
+    isRequired: true,
+    defaultIndex: 0,
+  };
+}
+
+export function mapCouncilCardKey(key: KeyEvent): CouncilCardKey | null {
+  if (key.name === "up") return { kind: "up" };
+  if (key.name === "down") return { kind: "down" };
+  if (key.name === "return") return { kind: "enter" };
+  if (key.name === "escape") return { kind: "escape" };
+  if (key.name === "backspace" || key.name === "delete") return { kind: "backspace" };
+  // Printable single character (letters, digits, space, etc.).
+  if (typeof key.sequence === "string" && key.sequence.length === 1 && key.sequence >= " " && key.sequence !== "\x7f") {
+    return { kind: "char", ch: key.sequence };
+  }
+  return null;
+}

package/src/ui/utils/modal.ts

@@ -0,0 +1,9 @@
+import type { KeyEvent } from "@opentui/core";
+
+export function bottomAlignedModalTop(height: number, panelHeight: number): number {
+  return Math.max(2, Math.floor((height - panelHeight) / 2));
+}
+
+export function isEscapeKey(key: KeyEvent): boolean {
+  return key.name === "escape" || key.code === "Escape" || key.baseCode === 27 || key.sequence === "" || key.raw === "";
+}

package/src/ui/utils/text.ts

@@ -0,0 +1,31 @@
+export function formatTokenCount(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}K`;
+  return String(tokens);
+}
+
+export function trunc(s: string, n: number): string {
+  return s.length <= n ? s : `${s.slice(0, n)}…`;
+}
+
+export function truncateLine(s: string, n: number): string {
+  return trunc(s.replace(/\s+/g, " ").trim(), n);
+}
+
+export function truncateBlock(text: string, maxLines: number): string {
+  const lines = text.split("\n");
+  if (lines.length <= maxLines) return text;
+  return [...lines.slice(0, maxLines), `… ${lines.length - maxLines} more lines`].join("\n");
+}
+
+export function compactTaskLabel(label: string): string {
+  const words = label.trim().split(/\s+/).filter(Boolean);
+  if (words.length <= 3) return label.trim() || "Working";
+  return `${words.slice(0, 3).join(" ")}...`;
+}
+
+export function sanitizeContent(raw: string): string {
+  let s = raw.replace(/^[\s\n]*assistant:\s*/gi, "");
+  s = s.replace(/\{"success"\s*:\s*(true|false)\s*,\s*"output"\s*:\s*"[\s\S]*$/m, "");
+  return s.trim();
+}

package/src/ui/utils/tools.ts

@@ -0,0 +1,95 @@
+import type { ToolCall } from "../../types/index.js";
+import { trunc } from "./text.js";
+
+export function describeMcpFsTool(name: string): { verb: string; ns: string } | null {
+  if (!name.startsWith("mcp_filesystem__") && !name.startsWith("mcp__filesystem__")) return null;
+  const op = name.replace(/^mcp_+filesystem__/, "");
+  const verbMap: Record<string, string> = {
+    read_text_file: "read",
+    read_file: "read",
+    read_media_file: "read media",
+    read_multiple_files: "read multi",
+    write_file: "write",
+    edit_file: "edit",
+    create_directory: "mkdir",
+    list_directory: "ls",
+    list_directory_with_sizes: "ls -s",
+    directory_tree: "tree",
+    move_file: "mv",
+    search_files: "search",
+    get_file_info: "stat",
+    list_allowed_directories: "list-allowed",
+  };
+  return { verb: verbMap[op] ?? op.replace(/_/g, " "), ns: "fs" };
+}
+
+export function toolArgs(tc?: ToolCall): string {
+  if (!tc) return "";
+  try {
+    const a = JSON.parse(tc.function.arguments);
+    if (tc.function.name === "bash") return (a.command || "").replace(/\n/g, " ").trim();
+    if (tc.function.name === "read_file" || tc.function.name === "write_file" || tc.function.name === "edit_file")
+      return a.file_path || a.path || "";
+    if (describeMcpFsTool(tc.function.name)) {
+      // Most MCP fs tools take `path`; some take `paths` (read_multiple_files) or `source`/`destination` (move_file).
+      if (Array.isArray(a.paths)) return a.paths.join(", ");
+      if (a.source && a.destination) return `${a.source} → ${a.destination}`;
+      return a.path || a.pattern || "";
+    }
+    if (tc.function.name === "grep") {
+      const path = a.path ? ` in ${a.path}` : "";
+      return `"${a.pattern || ""}"${path}`;
+    }
+    if (tc.function.name === "generate_image" || tc.function.name === "generate_video") return a.prompt || "";
+    if (tc.function.name === "task") return a.description || "";
+    if (tc.function.name === "lsp") return `${a.operation || "query"} ${a.filePath || ""}`.trim();
+    if (tc.function.name === "delegate") return a.description || "";
+    if (tc.function.name === "delegation_read") return a.id || "";
+    if (tc.function.name === "process_logs" || tc.function.name === "process_stop")
+      return a.id != null ? String(a.id) : "";
+    return a.query || "";
+  } catch {
+    return "";
+  }
+}
+
+export function tryParseArg(tc: ToolCall | undefined, key: string): string {
+  if (!tc) return "";
+  try {
+    return JSON.parse(tc.function.arguments)[key] || "";
+  } catch {
+    return "";
+  }
+}
+
+export function toolLabel(tc: ToolCall): string {
+  const args = toolArgs(tc);
+  if (tc.function.name === "bash") {
+    try {
+      const parsed = JSON.parse(tc.function.arguments);
+      if (parsed.background) return `Background: ${trunc(args || "Starting process...", 70)}`;
+    } catch {
+      /* */
+    }
+    return trunc(args || "Running command...", 80);
+  }
+  if (tc.function.name === "read_file") return `Read ${trunc(args, 60)}`;
+  if (tc.function.name === "write_file") return `Write ${trunc(args, 60)}`;
+  if (tc.function.name === "edit_file") return `Edit ${trunc(args, 60)}`;
+  if (tc.function.name === "grep") return `Grep ${trunc(args, 60)}`;
+  if (tc.function.name === "search_web") return `Web Search "${trunc(args, 60)}"`;
+  if (tc.function.name === "search_x") return `X Search "${trunc(args, 60)}"`;
+  if (tc.function.name === "generate_image") return `Generate image "${trunc(args, 60)}"`;
+  if (tc.function.name === "generate_video") return `Generate video "${trunc(args, 60)}"`;
+  if (tc.function.name === "task") return `Task ${trunc(args, 60)}`;
+  if (tc.function.name === "delegate") return `Background ${trunc(args, 60)}`;
+  if (tc.function.name === "delegation_read") return `Read delegation ${trunc(args, 60)}`;
+  if (tc.function.name === "delegation_list") return "List delegations";
+  if (tc.function.name === "process_logs") return `Logs for process ${args}`;
+  if (tc.function.name === "process_stop") return `Stop process ${args}`;
+  if (tc.function.name === "process_list") return "List processes";
+  if (tc.function.name === "generate_plan") return "Generating plan...";
+  const mcp = describeMcpFsTool(tc.function.name);
+  if (mcp) return `MCP ${mcp.ns} ${mcp.verb}${args ? ` ${trunc(args, 60)}` : ""}`;
+  return trunc(`${tc.function.name} ${args}`, 80);
+}

package/src/usage/__tests__/product-ledger.test.ts

@@ -0,0 +1,85 @@
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { appendProductLedger, getProductSpentUsd, readProductLedger } from "../product-ledger.js";
+
+const TEST_HOME = path.join(os.tmpdir(), `muonroi-test-${Math.random().toString(36).slice(2)}`);
+
+describe("product-ledger", () => {
+  beforeEach(async () => {
+    await fs.mkdir(TEST_HOME, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(TEST_HOME, { recursive: true, force: true });
+  });
+
+  it("appends and reads entries", async () => {
+    const runId = "test-run";
+    const entry1 = { ts: 1000, productRunId: runId, reservationId: "r1", actualUsd: 0.1, model: "m1", provider: "p1" };
+    const entry2 = { ts: 1001, productRunId: runId, reservationId: "r2", actualUsd: 0.2, model: "m1", provider: "p1" };
+
+    await appendProductLedger(runId, entry1, TEST_HOME);
+    await appendProductLedger(runId, entry2, TEST_HOME);
+
+    const entries = await readProductLedger(runId, TEST_HOME);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toEqual(entry1);
+    expect(entries[1]).toEqual(entry2);
+  });
+
+  it("calculates spent USD correctly", async () => {
+    const runId = "test-run-spent";
+    await appendProductLedger(
+      runId,
+      { ts: 1, productRunId: runId, reservationId: "r1", actualUsd: 0.1, model: "m", provider: "p" },
+      TEST_HOME,
+    );
+    await appendProductLedger(
+      runId,
+      { ts: 2, productRunId: runId, reservationId: "r2", actualUsd: 0.2, model: "m", provider: "p" },
+      TEST_HOME,
+    );
+
+    const spent = await getProductSpentUsd(runId, TEST_HOME);
+    expect(spent).toBeCloseTo(0.3);
+  });
+
+  it("handles missing files gracefully", async () => {
+    const entries = await readProductLedger("non-existent", TEST_HOME);
+    expect(entries).toEqual([]);
+
+    const spent = await getProductSpentUsd("non-existent", TEST_HOME);
+    expect(spent).toBe(0);
+  });
+
+  it("handles concurrent appends", async () => {
+    const runId = "concurrent-run";
+    const count = 10;
+    const promises = [];
+    for (let i = 0; i < count; i++) {
+      promises.push(
+        appendProductLedger(
+          runId,
+          {
+            ts: Date.now(),
+            productRunId: runId,
+            reservationId: `r${i}`,
+            actualUsd: 0.01,
+            model: "m",
+            provider: "p",
+          },
+          TEST_HOME,
+        ),
+      );
+    }
+
+    await Promise.all(promises);
+
+    const entries = await readProductLedger(runId, TEST_HOME);
+    expect(entries).toHaveLength(count);
+    const spent = await getProductSpentUsd(runId, TEST_HOME);
+    expect(spent).toBeCloseTo(count * 0.01);
+  });
+});

package/src/usage/cost-log.ts

@@ -0,0 +1,158 @@
+/**
+ * src/usage/cost-log.ts
+ *
+ * Lightweight, append-only JSONL log of every LLM call across the CLI.
+ * Complements the monthly ledger and per-product ledger by capturing calls
+ * that don't have a productRunId (orchestrator, compaction, council, PIL, ...).
+ *
+ * Goal: answer "where did the cost grow?" by callsite / role / phase, even
+ * for traffic that bypasses reserve/commit. Writes are best-effort — failures
+ * never block the model call.
+ *
+ * Path: ~/.muonroi-cli/usage/cost-log.jsonl  (rotates daily by date suffix)
+ */
+
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { projectCostUSD } from "./estimator.js";
+import type { CostMeta } from "./product-ledger.js";
+
+export interface CostLogEntry extends CostMeta {
+  ts: number;
+  provider: string;
+  model: string;
+  estimatedUsd: number;
+  productRunId?: string;
+  /**
+   * Free-form chars/tokens breakdown per logical prompt component.
+   * Keys: staticPrefix, dynamicSuffix, playwrightGuidance, pilSuffix,
+   *       messages, tools, toolNames, etc. Used by orchestrator to
+   *       attribute the 17K-token system prompt to specific parts.
+   */
+  breakdown?: Record<string, number>;
+}
+
+function muonroiHome(homeOverride?: string): string {
+  return homeOverride ?? process.env.MUONROI_CLI_HOME ?? path.join(os.homedir(), ".muonroi-cli");
+}
+
+function todayUtc(): string {
+  const d = new Date();
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+}
+
+function logPath(homeOverride?: string): string {
+  return path.join(muonroiHome(homeOverride), "usage", `cost-log-${todayUtc()}.jsonl`);
+}
+
+/**
+ * Append one entry. Best-effort: errors are swallowed so a logging fault
+ * cannot break the calling LLM request.
+ */
+export async function appendCostLog(entry: CostLogEntry, homeOverride?: string): Promise<void> {
+  try {
+    const fp = logPath(homeOverride);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.appendFile(fp, `${JSON.stringify(entry)}\n`);
+  } catch {
+    // intentionally swallow — diagnostics must not break the hot path
+  }
+}
+
+/**
+ * Metered wrapper for any LLM call.
+ *
+ * Use this at every `generateText` / `streamText` / `llm.generate` site that
+ * does NOT already go through the per-product ledger. It records:
+ *   - estimated cost (cheap, from chars/4)
+ *   - actual tokens IF the caller can supply them from `result.usage`
+ *   - callsite/role/phase/iteration tags for groupable reports
+ *
+ * The wrapper does not enforce the cap — orchestrator/compaction paths run
+ * outside reserve/commit by design (Phase G). It exists to MEASURE.
+ */
+export async function meteredGenerate<T>(
+  args: {
+    provider: string;
+    model: string;
+    systemChars: number;
+    promptChars: number;
+    estOutputTokens?: number;
+    meta?: CostMeta;
+    homeOverride?: string;
+  },
+  fn: () => Promise<{
+    result: T;
+    actualInputTokens?: number;
+    actualOutputTokens?: number;
+    cachedInputTokens?: number;
+    stepCount?: number;
+  }>,
+): Promise<T> {
+  const estIn = Math.ceil((args.systemChars + args.promptChars) / 4);
+  const estOut = args.estOutputTokens ?? 2048;
+  const startedAt = Date.now();
+  try {
+    const { result, actualInputTokens, actualOutputTokens, cachedInputTokens, stepCount } = await fn();
+    const inTok = actualInputTokens ?? estIn;
+    const outTok = actualOutputTokens ?? Math.max(1, Math.ceil(estOut / 4));
+    const usd = projectCostUSD(args.provider, args.model, inTok, outTok);
+    await appendCostLog(
+      {
+        ts: startedAt,
+        provider: args.provider,
+        model: args.model,
+        estimatedUsd: usd,
+        systemChars: args.systemChars,
+        promptChars: args.promptChars,
+        estInputTokens: estIn,
+        actualInputTokens,
+        actualOutputTokens,
+        cachedInputTokens,
+        stepCount,
+        durationMs: Date.now() - startedAt,
+        ...args.meta,
+      },
+      args.homeOverride,
+    );
+    return result;
+  } catch (err) {
+    // Still record the attempt so retries/failures show up in the bloat report.
+    await appendCostLog(
+      {
+        ts: startedAt,
+        provider: args.provider,
+        model: args.model,
+        estimatedUsd: 0,
+        systemChars: args.systemChars,
+        promptChars: args.promptChars,
+        estInputTokens: estIn,
+        durationMs: Date.now() - startedAt,
+        ...args.meta,
+        callsite: `${args.meta?.callsite ?? "unknown"}:error`,
+      },
+      args.homeOverride,
+    );
+    throw err;
+  }
+}
+
+/**
+ * Read all cost-log entries for the given UTC date (default = today).
+ * Returns empty array if the file does not exist.
+ */
+export async function readCostLog(date?: string, homeOverride?: string): Promise<CostLogEntry[]> {
+  const day = date ?? todayUtc();
+  const fp = path.join(muonroiHome(homeOverride), "usage", `cost-log-${day}.jsonl`);
+  try {
+    const content = await fs.readFile(fp, "utf-8");
+    return content
+      .split("\n")
+      .filter((l) => l.trim() !== "")
+      .map((l) => JSON.parse(l) as CostLogEntry);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+}

package/src/usage/decision-log.ts

@@ -0,0 +1,86 @@
+/**
+ * src/usage/decision-log.ts
+ *
+ * Per-turn orchestrator decision log. Captures the binary YES/NO decisions
+ * that gate expensive paths (auto-council, post-turn compaction, mode switch)
+ * along with the reason so reports can answer "why did we burn $0.30 on a
+ * council just now?" or "we paid for compaction every 4 turns — is the
+ * threshold tuned wrong?".
+ *
+ * Companion to:
+ *   - cost-log.ts (every LLM call: model, tokens, cost)
+ *   - pil/budget-log.ts (every pipeline run: per-layer prompt growth)
+ *
+ * Best-effort append; failures never break the orchestrator.
+ *
+ * Path: ~/.muonroi-cli/usage/decision-log-<UTC-date>.jsonl
+ */
+
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type DecisionKind = "auto-council" | "post-turn-compact" | "router-tier";
+
+export interface DecisionLogEntry {
+  ts: number;
+  sessionId?: string | null;
+  kind: DecisionKind;
+  /** true if the expensive path was taken; false if skipped. */
+  taken: boolean;
+  /** Short human-readable explanation suitable for a report column. */
+  reason: string;
+  /** Optional free-form data — taskType, confidence, model chosen, etc. */
+  meta?: Record<string, unknown>;
+}
+
+function muonroiHome(homeOverride?: string): string {
+  return homeOverride ?? process.env.MUONROI_CLI_HOME ?? path.join(os.homedir(), ".muonroi-cli");
+}
+
+function todayUtc(): string {
+  const d = new Date();
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+}
+
+function logPath(homeOverride?: string): string {
+  return path.join(muonroiHome(homeOverride), "usage", `decision-log-${todayUtc()}.jsonl`);
+}
+
+export async function appendDecisionLog(entry: DecisionLogEntry, homeOverride?: string): Promise<void> {
+  try {
+    const fp = logPath(homeOverride);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.appendFile(fp, `${JSON.stringify(entry)}\n`);
+  } catch {
+    // intentionally swallow — diagnostics must not break the turn
+  }
+}
+
+export async function readDecisionLog(date?: string, homeOverride?: string): Promise<DecisionLogEntry[]> {
+  const day = date ?? todayUtc();
+  const fp = path.join(muonroiHome(homeOverride), "usage", `decision-log-${day}.jsonl`);
+  try {
+    const content = await fs.readFile(fp, "utf-8");
+    return content
+      .split("\n")
+      .filter((l) => l.trim() !== "")
+      .map((l) => JSON.parse(l) as DecisionLogEntry);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+export async function listDecisionLogDates(homeOverride?: string): Promise<string[]> {
+  const dir = path.join(muonroiHome(homeOverride), "usage");
+  try {
+    const files = await fs.readdir(dir);
+    return files
+      .filter((f) => f.startsWith("decision-log-") && f.endsWith(".jsonl"))
+      .map((f) => f.replace(/^decision-log-/, "").replace(/\.jsonl$/, ""))
+      .sort();
+  } catch {
+    return [];
+  }
+}

package/src/usage/estimator.ts

@@ -32,3 +32,27 @@ export function projectCostUSD(
   const outUSD = (estOutputTokens / 1_000_000) * p.output_per_million_usd;
   return inUSD + outUSD;
 }
+
+/**
+ * Cache-aware cost projection. Splits input tokens into hit (charged at the
+ * cached_input rate when the model surfaces one) and miss (full input rate).
+ * Falls back to {@link projectCostUSD} when the model has no cached price.
+ *
+ * Use this for cost previews and post-hoc reconciliation of /ideal runs where
+ * DeepSeek prompt caching can change projected spend by an order of magnitude.
+ */
+export function projectCostUSDWithCache(
+  provider: string,
+  model: string,
+  estInputMissTokens: number,
+  estInputHitTokens: number,
+  estOutputTokens: number,
+): number {
+  const p = lookupPricing(provider, model);
+  if (!p) return 0;
+  const missUSD = (estInputMissTokens / 1_000_000) * p.input_per_million_usd;
+  const hitRate = p.cached_input_per_million_usd ?? p.input_per_million_usd;
+  const hitUSD = (estInputHitTokens / 1_000_000) * hitRate;
+  const outUSD = (estOutputTokens / 1_000_000) * p.output_per_million_usd;
+  return missUSD + hitUSD + outUSD;
+}