autonomous-flow-daemon 1.0.0 → 1.1.0

package/src/commands/score.ts

@@ -1,4 +1,8 @@
 import { daemonRequest } from "../daemon/client";
+import { fmtNum, visualWidth, localizedBoast } from "../core/boast";
+import type { ShiftSummary } from "../core/boast";
+import { getSystemLanguage } from "../core/locale";
+import { getMessages, t } from "../core/i18n/messages";
 
 interface HologramScore {
   requests: number;
@@ -28,6 +32,12 @@ interface EcosystemScore {
   primary: string;
 }
 
+interface SuppressionScore {
+  massEventsSkipped: number;
+  dormantTransitions: number;
+  activeTaps: number;
+}
+
 interface ScoreData {
   uptime: number;
   filesDetected: number;
@@ -39,6 +49,7 @@ interface ScoreData {
   hologram: HologramScore;
   immune: ImmuneScore;
   ecosystem: EcosystemScore;
+  suppression: SuppressionScore;
 }
 
 function formatUptime(seconds: number): string {
@@ -60,66 +71,95 @@ function formatChars(n: number): string {
   return `${(n / 1_000_000).toFixed(1)}M`;
 }
 
-const W = 46; // inner box width
+const W = 46;
 const line = "\u2500".repeat(W);
-const row = (content: string) => `\u2502${content.padEnd(W)}\u2502`;
+const sep = "\u2500".repeat(30);
+
+function row(content: string): string {
+  const vw = visualWidth(content);
+  const padSize = Math.max(0, W - vw);
+  return `\u2502${content}${" ".repeat(padSize)}\u2502`;
+}
+
+function vwPad(s: string, target: number): string {
+  const vw = visualWidth(s);
+  return s + " ".repeat(Math.max(0, target - vw));
+}
+
+/** Render a labeled key-value row with visual-width-aware padding. */
+function kv(label: string, value: string): string {
+  return row(`  ${vwPad(label, 13)}: ${value}`);
+}
 
 export async function scoreCommand() {
+  const lang = getSystemLanguage();
+  const i18n = getMessages(lang);
+
   try {
     const data = await daemonRequest<ScoreData>("/score");
     const h = data.hologram;
 
+    // Title
     console.log(`\u250C${line}\u2510`);
-    console.log(row("  afd score \u2014 Daemon Diagnostics"));
+    console.log(row(`  ${i18n.SCORE_TITLE}`));
     console.log(`\u251C${line}\u2524`);
-    console.log(row(`  Ecosystem    : ${data.ecosystem.primary}`));
+
+    // Ecosystem
+    console.log(kv(i18n.SCORE_ECOSYSTEM, data.ecosystem.primary));
     if (data.ecosystem.detected.length > 1) {
       const others = data.ecosystem.detected.slice(1).map(e => e.name).join(", ");
-      console.log(row(`  Also found   : ${others}`));
+      console.log(kv(i18n.SCORE_ALSO_FOUND, others));
     }
+
+    // Uptime / Events / Files
     console.log(`\u251C${line}\u2524`);
-    console.log(row(`  Uptime       : ${formatUptime(data.uptime)}`));
-    console.log(row(`  Events       : ${data.totalEvents}`));
-    console.log(row(`  Files Found  : ${data.watchedFiles.length}`));
+    console.log(kv(i18n.SCORE_UPTIME, formatUptime(data.uptime)));
+    console.log(kv(i18n.SCORE_EVENTS, String(data.totalEvents)));
+    console.log(kv(i18n.SCORE_FILES_FOUND, String(data.watchedFiles.length)));
     console.log(`\u251C${line}\u2524`);
-    console.log(row(`  Activity  ${heatBar(data.totalEvents, 100)}`));
+    console.log(row(`  ${vwPad(i18n.SCORE_ACTIVITY, 10)}${heatBar(data.totalEvents, 100)}`));
 
-    // Context Efficiency section
+    // Hologram section
     console.log(`\u251C${line}\u2524`);
-    console.log(row("  Context Efficiency (Hologram)"));
-    console.log(row(`  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+    console.log(row(`  ${i18n.SCORE_HOLOGRAM_TITLE}`));
+    console.log(row(`  ${sep}`));
     if (h.requests > 0) {
       const saved = h.originalChars - h.hologramChars;
-      console.log(row(`  Requests     : ${h.requests}`));
-      console.log(row(`  Original     : ${formatChars(h.originalChars)} chars`));
-      console.log(row(`  Hologram     : ${formatChars(h.hologramChars)} chars`));
-      console.log(row(`  Saved        : ${formatChars(saved)} chars (${h.savings}%)`));
-      console.log(row(`  Efficiency   ${heatBar(h.savings, 100)}`));
+      console.log(kv(i18n.SCORE_HOLOGRAM_REQUESTS, String(h.requests)));
+      console.log(kv(i18n.SCORE_HOLOGRAM_ORIGINAL, `${formatChars(h.originalChars)} chars`));
+      console.log(kv(i18n.SCORE_HOLOGRAM_COMPRESSED, `${formatChars(h.hologramChars)} chars`));
+      console.log(kv(i18n.SCORE_HOLOGRAM_SAVED, `${formatChars(saved)} chars (${h.savings}%)`));
+      console.log(row(`  ${vwPad(i18n.SCORE_HOLOGRAM_EFFICIENCY, 10)}${heatBar(h.savings, 100)}`));
     } else {
-      console.log(row("  No hologram requests yet."));
-      console.log(row("  Use: GET /hologram?file=<path>"));
+      console.log(row(`  ${i18n.SCORE_HOLOGRAM_EMPTY}`));
+      console.log(row(`  ${i18n.SCORE_HOLOGRAM_HINT}`));
     }
 
     // Immune System section
     console.log(`\u251C${line}\u2524`);
-    console.log(row("  Immune System"));
-    console.log(row(`  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+    console.log(row(`  ${i18n.SCORE_IMMUNE_TITLE}`));
+    console.log(row(`  ${sep}`));
     const ab = data.immune.antibodies;
     const ah = data.immune.autoHealed;
-    const immuneLevel = ab === 0 ? "Vulnerable" : ab < 3 ? "Learning" : ab < 6 ? "Guarded" : "Fortified";
-    console.log(row(`  Antibodies   : ${ab}`));
-    console.log(row(`  Level        : ${immuneLevel}`));
-    console.log(row(`  Immunity     ${heatBar(ab, 10)}`));
-    console.log(row(`  Auto-healed  : ${ah} background event${ah !== 1 ? "s" : ""}`));
+    const immuneLevel = ab === 0 ? i18n.SCORE_IMMUNE_VULNERABLE
+      : ab < 3 ? i18n.SCORE_IMMUNE_LEARNING
+      : ab < 6 ? i18n.SCORE_IMMUNE_GUARDED
+      : i18n.SCORE_IMMUNE_FORTIFIED;
+    console.log(kv(i18n.SCORE_ANTIBODIES, String(ab)));
+    console.log(kv(i18n.SCORE_LEVEL, immuneLevel));
+    console.log(row(`  ${vwPad(i18n.SCORE_IMMUNITY, 10)}${heatBar(ab, 10)}`));
+    const healedStr = t(i18n.SCORE_AUTO_HEALED, { count: ah, s: ah !== 1 ? "s" : "" });
+    console.log(kv(i18n.SCORE_AUTO_HEALED_LABEL, healedStr));
     if (data.immune.lastAutoHeal) {
       const ago = formatUptime(Math.floor((Date.now() - data.immune.lastAutoHeal.at) / 1000));
-      console.log(row(`  Last heal    : ${data.immune.lastAutoHeal.id} (${ago} ago)`));
+      const healStr = t(i18n.SCORE_LAST_HEAL, { id: data.immune.lastAutoHeal.id, ago });
+      console.log(kv(i18n.SCORE_LAST_EVENT, healStr));
     }
 
     // Watched files
     console.log(`\u251C${line}\u2524`);
     if (data.watchedFiles.length > 0) {
-      console.log(row("  Watched Files:"));
+      console.log(row(`  ${i18n.SCORE_WATCHED_FILES}`));
       for (const f of data.watchedFiles.slice(0, 8)) {
         console.log(row(`    ${f.substring(0, W - 6)}`));
       }
@@ -127,18 +167,38 @@ export async function scoreCommand() {
         console.log(row(`    ... +${data.watchedFiles.length - 8} more`));
       }
     } else {
-      console.log(row("  No files detected yet."));
+      console.log(row(`  ${i18n.SCORE_NO_FILES}`));
     }
 
+    // Last event
     if (data.lastEvent) {
       const ago = data.lastEventAt
-        ? formatUptime(Math.floor((Date.now() - data.lastEventAt) / 1000)) + " ago"
+        ? t(i18n.SCORE_AGO, { time: formatUptime(Math.floor((Date.now() - data.lastEventAt) / 1000)) })
         : "unknown";
       console.log(`\u251C${line}\u2524`);
-      console.log(row(`  Last: ${data.lastEvent.substring(0, 36)}`));
+      console.log(row(`  ${vwPad(i18n.SCORE_LAST_EVENT, 6)}: ${data.lastEvent.substring(0, 34)}`));
       console.log(row(`        ${ago}`));
     }
 
+    // Value Metrics section
+    try {
+      const summary = await daemonRequest<ShiftSummary>("/shift-summary");
+      console.log(`\u251C${line}\u2524`);
+      console.log(row(`  ${i18n.SCORE_VALUE_TITLE}`));
+      console.log(row(`  ${sep}`));
+      console.log(kv(i18n.SHIFT_TOKENS, `~${fmtNum(summary.totalTokensSaved)}`));
+      console.log(kv(i18n.SHIFT_TIME, `~${summary.totalMinutesSaved} min`));
+      console.log(kv(i18n.SHIFT_COST, `~$${summary.totalCostSaved.toFixed(2)}`));
+      if (summary.suppressionsSkipped > 0) {
+        console.log(kv(i18n.SHIFT_SUPPRESSED, `${summary.suppressionsSkipped}`));
+      }
+      console.log(`\u251C${line}\u2524`);
+      const boast = localizedBoast(lang);
+      console.log(row(`  \uD83D\uDDE3\uFE0F ${boast.substring(0, W - 6)}`));
+    } catch {
+      // Non-fatal
+    }
+
     console.log(`\u2514${line}\u2518`);
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);

package/src/commands/start.ts

@@ -1,42 +1,65 @@
-import { spawn } from "child_process";
 import { resolve } from "path";
+import { spawn } from "child_process";
+import { openSync, mkdirSync } from "fs";
 import { getDaemonInfo, isDaemonAlive } from "../daemon/client";
-import { AFD_DIR } from "../constants";
-import { mkdirSync } from "fs";
+import { AFD_DIR, LOG_FILE, WATCH_TARGETS } from "../constants";
 import { detectEcosystem } from "../adapters/index";
+import { detachedSpawnOptions, IS_WINDOWS } from "../platform";
+import { getSystemLanguage } from "../core/locale";
+import { getMessages, t } from "../core/i18n/messages";
+import { discoverWatchTargets } from "../core/discovery";
+
+const STARTUP_POLL_INTERVAL_MS = 100;
+const STARTUP_POLL_MAX_MS = 3000;
+
+export async function startCommand(options?: { mcp?: boolean }) {
+  // MCP stdio mode: run daemon in foreground with stdio transport
+  if (options?.mcp) {
+    const { main: runDaemon } = await import("../daemon/server");
+    runDaemon({ mcp: true });
+    return; // never reaches here — stdio loop blocks
+  }
+
+  const lang = getSystemLanguage();
+  const msg = getMessages(lang);
 
-export async function startCommand() {
   mkdirSync(AFD_DIR, { recursive: true });
 
-  // Check if already running
+  // ── Idempotency: check if already running ──
   const existing = getDaemonInfo();
-  if (existing && await isDaemonAlive(existing)) {
-    console.log(`[afd] Daemon already running (pid=${existing.pid}, port=${existing.port})`);
+  if (existing && (await isDaemonAlive(existing))) {
+    console.log(msg.DAEMON_ALREADY_RUNNING);
     return;
   }
 
-  // Spawn detached daemon
+  // ── Spawn detached daemon with log redirection ──
   const daemonScript = resolve(import.meta.dirname, "../daemon/server.ts");
-  const bunPath = process.execPath;
+  const logPath = resolve(LOG_FILE);
+  const logFd = openSync(logPath, "a"); // append mode
+
+  // On Windows, wrap in shell for proper detach; quote path for spaces
+  const args = IS_WINDOWS
+    ? ["run", `"${daemonScript}"`]
+    : ["run", daemonScript];
 
-  const child = spawn(bunPath, ["run", daemonScript], {
-    detached: true,
-    stdio: ["ignore", "ignore", "ignore"],
-    cwd: process.cwd(),
-    env: { ...process.env },
-  });
+  const child = spawn("bun", args, detachedSpawnOptions(logFd));
 
+  // Detach: allow parent to exit without killing child
   child.unref();
 
-  // Wait for daemon to write its port file (Windows needs more time)
-  await new Promise((r) => setTimeout(r, 1500));
+  // ── Poll for daemon readiness instead of fixed sleep ──
+  const info = await pollForDaemon(STARTUP_POLL_MAX_MS, STARTUP_POLL_INTERVAL_MS);
 
-  const info = getDaemonInfo();
-  if (info && await isDaemonAlive(info)) {
-    console.log(`[afd] Daemon started (pid=${info.pid}, port=${info.port})`);
-    console.log(`[afd] Watching: .claude/, CLAUDE.md, .cursorrules`);
+  if (info) {
+    console.log(t(msg.DAEMON_STARTED, { pid: info.pid, port: info.port }));
 
-    // Silently inject auto-heal hook and status line into detected ecosystem
+    // Smart Discovery: show what we're actually watching
+    const discovery = discoverWatchTargets(WATCH_TARGETS);
+    console.log(t(msg.DAEMON_WATCHING, { count: discovery.targets.length }));
+    console.log(`[afd] Targets: ${discovery.targets.join(", ")}`);
+    console.log(t(msg.DAEMON_LOGS, { path: logPath }));
+
+    // Inject hooks into detected ecosystems
     const ecosystems = detectEcosystem(process.cwd());
     for (const { adapter } of ecosystems) {
       if (adapter.injectHooks) {
@@ -49,7 +72,25 @@ export async function startCommand() {
       }
     }
   } else {
-    console.error("[afd] Failed to start daemon. Check logs.");
+    console.error(t(msg.DAEMON_START_FAILED, { path: logPath }));
     process.exit(1);
   }
 }
+
+/** Poll until daemon PID/port files appear and health check passes */
+async function pollForDaemon(
+  maxMs: number,
+  intervalMs: number,
+): Promise<{ pid: number; port: number } | null> {
+  const deadline = Date.now() + maxMs;
+
+  while (Date.now() < deadline) {
+    const info = getDaemonInfo();
+    if (info && (await isDaemonAlive(info))) {
+      return info;
+    }
+    await Bun.sleep(intervalMs);
+  }
+
+  return null;
+}

package/src/commands/stop.ts

@@ -1,6 +1,10 @@
 import { getDaemonInfo, isDaemonAlive, daemonRequest } from "../daemon/client";
 import { unlinkSync } from "fs";
 import { PID_FILE, PORT_FILE } from "../constants";
+import { formatShiftSummary } from "../core/boast";
+import type { ShiftSummary } from "../core/boast";
+import { getSystemLanguage } from "../core/locale";
+import { getMessages, t } from "../core/i18n/messages";
 
 function cleanupFiles() {
   try { unlinkSync(PID_FILE); } catch {}
@@ -8,27 +12,37 @@ function cleanupFiles() {
 }
 
 export async function stopCommand() {
+  const lang = getSystemLanguage();
+  const msg = getMessages(lang);
   const info = getDaemonInfo();
+
   if (!info) {
-    console.log("[afd] No daemon running.");
+    console.log(msg.DAEMON_NOT_RUNNING);
     return;
   }
 
   if (await isDaemonAlive(info)) {
+    // Fetch shift summary before stopping
+    try {
+      const summary = await daemonRequest<ShiftSummary>("/shift-summary");
+      console.log(formatShiftSummary(summary, lang));
+    } catch {
+      // Non-fatal: summary is a nicety, not a requirement
+    }
+
     try {
       await daemonRequest("/stop");
-      console.log(`[afd] Daemon stopped (pid=${info.pid})`);
+      console.log(t(msg.DAEMON_STOPPED, { pid: info.pid }));
     } catch {
-      // Force kill if graceful stop fails
       try {
         process.kill(info.pid, "SIGTERM");
-        console.log(`[afd] Daemon killed (pid=${info.pid})`);
+        console.log(t(msg.DAEMON_KILLED, { pid: info.pid }));
       } catch {
         console.log("[afd] Daemon process already gone.");
       }
     }
   } else {
-    console.log("[afd] Daemon not responding. Cleaning up stale PID files.");
+    console.log(msg.DAEMON_NOT_RESPONDING);
   }
 
   cleanupFiles();

package/src/constants.ts

@@ -4,4 +4,5 @@ export const AFD_DIR = ".afd";
 export const PID_FILE = join(AFD_DIR, "daemon.pid");
 export const PORT_FILE = join(AFD_DIR, "daemon.port");
 export const DB_FILE = join(AFD_DIR, "antibodies.sqlite");
-export const WATCH_TARGETS = [".claude/", "CLAUDE.md", ".cursorrules"];
+export const LOG_FILE = join(AFD_DIR, "daemon.log");
+export const WATCH_TARGETS = [".claude/", "CLAUDE.md", ".cursorrules", ".claudeignore", ".gitignore"];

package/src/core/boast.ts

@@ -0,0 +1,265 @@
+/**
+ * Boastful Doctor — Gamification & Delightful Logging
+ *
+ * Lightweight value calculations that stay well under the 270ms budget.
+ * All math is O(1) — no I/O, no async.
+ * All strings are localized via the i18n dictionary.
+ */
+
+import { getSystemLanguage } from "./locale";
+import type { SupportedLang } from "./locale";
+import { getMessages, t } from "./i18n/messages";
+import type { MessageDict } from "./i18n/messages";
+
+// ── Token & Cost Estimation ──
+
+/** Rough chars-per-token ratio for code (conservative estimate) */
+const CHARS_PER_TOKEN = 3.5;
+
+/** Average cost per 1K input tokens (Claude Sonnet ballpark) */
+const COST_PER_1K_TOKENS = 0.003;
+
+/** Estimated minutes a developer spends debugging a missing config */
+const DEBUG_MINUTES_BASE = 8;
+const DEBUG_MINUTES_PER_KB = 2;
+
+export interface HealMetrics {
+  fileSize: number;
+  healTimeMs: number;
+  tokensSaved: number;
+  minutesSaved: number;
+  costSaved: number;
+}
+
+/** Calculate mock "value saved" from a heal event. O(1), no I/O. */
+export function calcHealMetrics(fileSize: number, healTimeMs: number): HealMetrics {
+  const tokensSaved = Math.round(fileSize / CHARS_PER_TOKEN);
+  const fileSizeKB = fileSize / 1024;
+  const minutesSaved = Math.round(DEBUG_MINUTES_BASE + fileSizeKB * DEBUG_MINUTES_PER_KB);
+  const costSaved = Math.round(tokensSaved / 1000 * COST_PER_1K_TOKENS * 100) / 100;
+  return { fileSize, healTimeMs, tokensSaved, minutesSaved, costSaved };
+}
+
+export interface ShiftSummary {
+  uptimeFormatted: string;
+  totalEvents: number;
+  healsPerformed: number;
+  totalTokensSaved: number;
+  totalMinutesSaved: number;
+  totalCostSaved: number;
+  suppressionsSkipped: number;
+  dormantTransitions: number;
+  boast: string;
+}
+
+/** Build a shift summary from aggregated daemon stats. */
+export function buildShiftSummary(stats: {
+  uptimeSeconds: number;
+  totalEvents: number;
+  healsPerformed: number;
+  totalFileBytesSaved: number;
+  suppressionsSkipped: number;
+  dormantTransitions: number;
+}, lang?: SupportedLang): ShiftSummary {
+  const l = lang ?? getSystemLanguage();
+  const msg = getMessages(l);
+  const totalTokensSaved = Math.round(stats.totalFileBytesSaved / CHARS_PER_TOKEN);
+  const totalMinutesSaved = stats.healsPerformed * DEBUG_MINUTES_BASE;
+  const totalCostSaved = Math.round(totalTokensSaved / 1000 * COST_PER_1K_TOKENS * 100) / 100;
+
+  return {
+    uptimeFormatted: formatUptime(stats.uptimeSeconds),
+    totalEvents: stats.totalEvents,
+    healsPerformed: stats.healsPerformed,
+    totalTokensSaved,
+    totalMinutesSaved,
+    totalCostSaved,
+    suppressionsSkipped: stats.suppressionsSkipped,
+    dormantTransitions: stats.dormantTransitions,
+    boast: pick(msg.BOAST_SHIFT_END),
+  };
+}
+
+// ── Boast Selection ──
+
+function msg(lang?: SupportedLang): MessageDict {
+  return getMessages(lang ?? getSystemLanguage());
+}
+
+/** Pick a random heal boast. 1-in-N chance (anti-annoyance). */
+export function maybeHealBoast(triggerChance = 5, lang?: SupportedLang): string | null {
+  if (Math.floor(Math.random() * triggerChance) !== 0) return null;
+  const m = msg(lang);
+  return pick(m.BOAST_HEAL);
+}
+
+/** Always returns a dormant boast (rare event, always worth noting). */
+export function dormantBoast(lang?: SupportedLang): string {
+  return pick(msg(lang).BOAST_DORMANT);
+}
+
+/** Pick a random shift-end boast in the given locale. */
+export function localizedBoast(lang?: SupportedLang): string {
+  return pick(msg(lang).BOAST_SHIFT_END);
+}
+
+/** Format a single heal log line with metrics. */
+export function formatHealLog(
+  fileName: string,
+  metrics: HealMetrics,
+  boast: string | null,
+  lang?: SupportedLang,
+): string {
+  const m = msg(lang);
+  const vars = {
+    fileName,
+    ms: metrics.healTimeMs,
+    tokens: metrics.tokensSaved,
+    mins: metrics.minutesSaved,
+  };
+  const base = t(m.HEAL_LOG, vars);
+  if (!boast) return base;
+  const boastLine = t(boast, vars);
+  return `${base}\n${m.BOAST_HEAL_PREFIX} ${boastLine}`;
+}
+
+/** Format dormant log line. */
+export function formatDormantLog(
+  antibodyId: string,
+  lang?: SupportedLang,
+): string {
+  const m = msg(lang);
+  const boast = pick(m.BOAST_DORMANT);
+  return t(m.DORMANT_LOG, { id: antibodyId, boast });
+}
+
+/** Format the full shift summary for terminal output. */
+export function formatShiftSummary(s: ShiftSummary, lang?: SupportedLang): string {
+  const m = msg(lang);
+  const lines = [
+    "",
+    "┌──────────────────────────────────────────────┐",
+    pad(`  ${m.SHIFT_TITLE}`),
+    "├──────────────────────────────────────────────┤",
+    padKV(m.SHIFT_ON_DUTY, s.uptimeFormatted),
+    padKV(m.SHIFT_EVENTS, String(s.totalEvents)),
+    padKV(m.SHIFT_HEALS, String(s.healsPerformed)),
+    padKV(m.SHIFT_TOKENS, `~${fmtNum(s.totalTokensSaved)}`),
+    padKV(m.SHIFT_TIME, `~${s.totalMinutesSaved} min`),
+    padKV(m.SHIFT_COST, `~$${s.totalCostSaved.toFixed(2)}`),
+  ];
+
+  if (s.suppressionsSkipped > 0) {
+    padKVPush(lines, m.SHIFT_SUPPRESSED, `${s.suppressionsSkipped} mass events`);
+  }
+  if (s.dormantTransitions > 0) {
+    padKVPush(lines, m.SHIFT_RETIRED, `${s.dormantTransitions} antibodies`);
+  }
+
+  lines.push("├──────────────────────────────────────────────┤");
+  // Override server-side boast with locale-appropriate one
+  const localBoast = pick(m.BOAST_SHIFT_END);
+  lines.push(pad(`  ${localBoast}`));
+  lines.push("└──────────────────────────────────────────────┘");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/** Format value section for score command. */
+export function formatValueSection(s: ShiftSummary, lang?: SupportedLang): string[] {
+  const m = msg(lang);
+  const lines: string[] = [];
+  lines.push(m.SCORE_VALUE_TITLE);
+  lines.push(`${m.SHIFT_TOKENS}: ~${fmtNum(s.totalTokensSaved)}`);
+  lines.push(`${m.SHIFT_TIME}: ~${s.totalMinutesSaved} min`);
+  lines.push(`${m.SHIFT_COST}: ~$${s.totalCostSaved.toFixed(2)}`);
+  return lines;
+}
+
+// ── Helpers ──
+
+function pick<T>(arr: T[]): T {
+  return arr[Math.floor(Math.random() * arr.length)];
+}
+
+function formatUptime(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  return `${h}h ${m}m`;
+}
+
+const W = 46;
+
+function pad(content: string): string {
+  const visual = visualWidth(content);
+  if (visual > W) {
+    let len = 0;
+    let cut = 0;
+    for (const ch of content) {
+      const cw = isWideChar(ch) ? 2 : 1;
+      if (len + cw > W - 1) break;
+      len += cw;
+      cut += ch.length;
+    }
+    const trimmed = content.slice(0, cut) + "…";
+    const trimVw = visualWidth(trimmed);
+    return `│${trimmed}${" ".repeat(Math.max(0, W - trimVw))}│`;
+  }
+  return `│${content}${" ".repeat(Math.max(0, W - visual))}│`;
+}
+
+/** Pad a key-value row with aligned colon, visual-width-aware. */
+function padKV(key: string, value: string): string {
+  const keyVw = visualWidth(key);
+  const padSize = Math.max(0, 13 - keyVw);
+  return pad(`  ${key}${" ".repeat(padSize)}: ${value}`);
+}
+
+function padKVPush(lines: string[], key: string, value: string): void {
+  lines.push(padKV(key, value));
+}
+
+export function visualWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) {
+    w += isWideChar(ch) ? 2 : 1;
+  }
+  return w;
+}
+
+function isWideChar(ch: string): boolean {
+  const code = ch.codePointAt(0) ?? 0;
+  return (
+    // CJK Unified Ideographs
+    (code >= 0x4E00 && code <= 0x9FFF) ||
+    // CJK Extension A
+    (code >= 0x3400 && code <= 0x4DBF) ||
+    // Hangul Syllables
+    (code >= 0xAC00 && code <= 0xD7AF) ||
+    // Hangul Jamo
+    (code >= 0x1100 && code <= 0x11FF) ||
+    // Hangul Compatibility Jamo
+    (code >= 0x3130 && code <= 0x318F) ||
+    // CJK Compatibility
+    (code >= 0x3300 && code <= 0x33FF) ||
+    // Fullwidth Forms
+    (code >= 0xFF01 && code <= 0xFF60) ||
+    // Common emoji ranges
+    (code >= 0x1F300 && code <= 0x1FBFF) ||
+    (code >= 0x2600 && code <= 0x27BF) ||
+    (code >= 0xFE00 && code <= 0xFE0F) ||
+    (code >= 0x200D && code <= 0x200D) ||
+    (code >= 0x231A && code <= 0x23FA) ||
+    code === 0x2764 ||
+    code === 0x2139
+  );
+}
+
+export function fmtNum(n: number): string {
+  if (n < 1000) return `${n}`;
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}K`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}