@scrylog/cli 0.2.0 → 0.3.0

package/src/usage/clients/claude-cli-probe.ts

@@ -1,187 +1,513 @@
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { UsageClient } from "../client";
+import { classifyUsageError, UsageError } from "../errors";
 import type { ClaudeUsageSnapshot, RateWindowLegacy } from "../types";
 
-export class TimeoutError extends Error {
+export type ClaudeProbeStrategy = "script-darwin" | "script-linux" | "expect" | "plain";
+
+export class TimeoutError extends UsageError {
   constructor(message: string) {
-    super(message);
+    super("transient", message);
     this.name = "TimeoutError";
   }
 }
 
+interface ProbeOptions {
+  initialTimeoutMs?: number;
+  retryTimeoutMs?: number;
+  killGraceMs?: number;
+  maxOutputBytes?: number;
+  cooldownMs?: number;
+  strategies?: readonly ClaudeProbeStrategy[];
+}
+
 function parseResetDate(text: string): Date | null {
-  // Patterns:
-  // "Resets at 8:00PM PDT"
-  // "Resets at 8:00 PM PDT"
-  // "Resets at Apr 28 at 8:00PM PDT"
-  // "Resets at Apr 28 at 8:00 PM PDT"
   const match = text.match(/Resets at (.+?)(?:\s*\(([^)]+)\))?$/i);
   if (!match) return null;
   const datePart = match[1]!.trim();
-  const tz = match[2] || undefined;
-  try {
-    const d = new Date(datePart);
-    if (!Number.isNaN(d.getTime())) return d;
-    // Fallback: try appending current year if no year present
-    const withYear = `${datePart} ${new Date().getFullYear()}`;
-    const d2 = new Date(withYear);
-    if (!Number.isNaN(d2.getTime())) return d2;
-  } catch {
-    // ignore
-  }
-  return null;
+  const direct = new Date(datePart);
+  if (!Number.isNaN(direct.getTime())) return direct;
+  const withYear = new Date(`${datePart} ${new Date().getFullYear()}`);
+  return Number.isNaN(withYear.getTime()) ? null : withYear;
 }
 
 function parsePercent(line: string): number | null {
   const match = line.match(/(\d{1,3}(?:\.\d+)?)\s*%/);
   if (!match) return null;
-  const val = Number.parseFloat(match[1]!);
-  return Number.isNaN(val) ? null : val;
+  const value = Number.parseFloat(match[1]!);
+  return Number.isNaN(value) ? null : value;
 }
 
 function toRateWindow(usedPercent: number, resetText: string | null, windowMinutes: number): RateWindowLegacy {
-  const resetsAt = resetText ? parseResetDate(resetText) : null;
   return {
     usedPercent: Math.max(0, Math.min(100, usedPercent)),
     windowMinutes,
-    resetsAt,
+    resetsAt: resetText ? parseResetDate(resetText) : null,
     resetDescription: resetText,
   };
 }
 
-function probeCli(binaryPath: string, timeoutMs: number): Promise<string> {
+const SCRIPT_FAILURE_PATTERNS: RegExp[] = [
+  /tcgetattr/i,
+  /Operation not supported on socket/i,
+];
+
+function stripAnsi(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\u001B\[[0-9;?]*[a-zA-Z]/g, "").replace(/\u001B\][^\u0007]*\u0007/g, "");
+}
+
+function looksLikeLauncherFailure(output: string, maxOutputBytes: number): boolean {
+  if (!output.trim()) return false;
+  if (output.length > Math.min(maxOutputBytes, 512)) return false;
+  const plain = stripAnsi(output);
+  return SCRIPT_FAILURE_PATTERNS.some((pattern) => pattern.test(plain));
+}
+
+function defaultWaitingStrategies(): ClaudeProbeStrategy[] {
+  if (process.platform === "darwin") return ["script-darwin", "expect", "plain"];
+  if (process.platform === "linux") {
+    const strategies: ClaudeProbeStrategy[] = [];
+    if (existsSync("/usr/bin/script")) strategies.push("script-linux");
+    if (existsSync("/usr/bin/expect")) strategies.push("expect");
+    strategies.push("plain");
+    return strategies;
+  }
+  return ["plain"];
+}
+
+function buildExpectScript(binaryPath: string, timeoutMs: number): string {
+  const seconds = Math.max(5, Math.ceil(timeoutMs / 1000));
+  const usageAt = Math.min(4000, Math.max(2500, seconds * 250));
+  const statusAt = usageAt + 2000;
+  const exitAt = Math.max(statusAt + 1000, timeoutMs - 1000);
+  const escaped = binaryPath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return `set timeout ${seconds}
+spawn "${escaped}"
+after ${usageAt} { send "/usage\\r" }
+after ${statusAt} { send "/status\\r" }
+after ${exitAt} { exit 0 }
+expect eof
+`;
+}
+
+/**
+ * Runs one launcher strategy to capture stdout/stderr, killing the process on
+ * timeout. Resolves with captured text and nothing else: a launcher that
+ * produces no bytes or only failure signatures is retried by the caller.
+ */
+function spawnStrategy(  strategy: ClaudeProbeStrategy,
+  binaryPath: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+  maxOutputBytes = 1024 * 1024,
+  killGraceMs = 500,
+): Promise<string> {
+  const useScript = process.platform === "darwin";
+  let command = binaryPath;
+  let args: string[] = [];
+  let stdin: string | null = null;
+  let expectDir: string | null = null;
+
+  if (strategy === "script-darwin") {
+    command = "script";
+    args = ["-q", "/dev/null", binaryPath];
+  } else if (strategy === "script-linux") {
+    command = "script";
+    args = ["-q", "-c", binaryPath, "/dev/null"];
+  } else if (strategy === "expect") {
+    expectDir = mkdtempSync(join(tmpdir(), "scrylog-expect-"));
+    const scriptPath = join(expectDir, "probe.exp");
+    writeFileSync(scriptPath, buildExpectScript(binaryPath, timeoutMs), { mode: 0o600 });
+    command = "expect";
+    args = [scriptPath];
+  }
+
+  const cleanupDir = (path: string | null): void => {
+    if (!path) return;
+    try {
+      rmSync(path, { recursive: true, force: true });
+    } catch {
+      // Bun can throw EFAULT when rmSync races with closeNotify teardown of
+      // the expect child; the temp dir is per-run and below tmpdir(), so a
+      // missed unlink is harmless and must not kill the daemon.
+    }
+  };
+
   return new Promise((resolve, reject) => {
-    let output = "";
-    let killed = false;
-
-    // Use `script` for PTY on macOS; fallback to direct spawn
-    const useScript = process.platform === "darwin";
-    const child = useScript
-      ? spawn("script", ["-q", "/dev/null", binaryPath], {
-          env: process.env,
-          stdio: ["pipe", "pipe", "pipe"],
-        })
-      : spawn(binaryPath, [], {
-          env: process.env,
-          stdio: ["pipe", "pipe", "pipe"],
-        });
-
-    const timer = setTimeout(() => {
-      killed = true;
-      child.kill("SIGTERM");
-      reject(new TimeoutError(`CLI probe timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
+    if (signal?.aborted) {
+      cleanupDir(expectDir);
+      reject(new UsageError("cancelled", "Claude CLI probe cancelled"));
+      return;
+    }
 
-    child.stdout.on("data", (data: Buffer) => {
-      output += data.toString("utf8");
-    });
+    let child: ChildProcessWithoutNullStreams;
+    try {
+      child = spawn(command, args, { env: process.env, stdio: ["pipe", "pipe", "pipe"] });
+    } catch (error) {
+      cleanupDir(expectDir);
+      reject(new UsageError("transient", `Could not launch Claude CLI: ${error instanceof Error ? error.message : String(error)}`));
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let outputBytes = 0;
+    let terminalError: Error | null = null;
+    let terminating = false;
+    let settled = false;
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
 
-    child.stderr.on("data", (data: Buffer) => {
-      output += data.toString("utf8");
-    });
+    const commandTimers: Array<ReturnType<typeof setTimeout>> = [];
+    const clearTimers = () => {
+      clearTimeout(timeoutTimer);
+      for (const timer of commandTimers) clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+    };
+    const terminate = (error: Error) => {
+      if (terminating || settled) return;
+      terminating = true;
+      terminalError = error;
+      child.stdin.end();
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => child.kill("SIGKILL"), killGraceMs);
+    };
+    const onAbort = () => terminate(new UsageError("cancelled", "Claude CLI probe cancelled"));
+    const timeoutTimer = setTimeout(
+      () => terminate(new TimeoutError(`Claude CLI probe (${strategy}) timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
 
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      if (!killed) reject(err);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const capture = (data: Buffer) => {
+      if (terminating) return;
+      outputBytes += data.byteLength;
+      if (outputBytes > maxOutputBytes) {
+        terminate(new UsageError("invalid-response", `Claude CLI output exceeded ${maxOutputBytes} bytes`));
+        return;
+      }
+      chunks.push(Buffer.from(data));
+    };
+    child.stdout.on("data", capture);
+    child.stderr.on("data", capture);
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      cleanupDir(expectDir);
+      signal?.removeEventListener("abort", onAbort);
+      reject(new UsageError("transient", `Could not launch Claude CLI (${strategy}): ${error.message}`));
     });
-
-    child.on("close", () => {
-      clearTimeout(timer);
-      if (!killed) resolve(output);
+    child.once("close", () => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      cleanupDir(expectDir);
+      signal?.removeEventListener("abort", onAbort);
+      if (terminalError) reject(terminalError);
+      else resolve(Buffer.concat(chunks).toString("utf8"));
     });
 
-    // Send commands
+    if (stdin) {
+      child.stdin.write(stdin);
+      child.stdin.end();
+      commandTimers.push(setTimeout(() => child.stdin.end(), 500));
+      return;
+    }
     child.stdin.write("/usage\n");
-    setTimeout(() => {
+    commandTimers.push(setTimeout(() => {
+      if (terminating || child.stdin.destroyed) return;
       child.stdin.write("/status\n");
-      setTimeout(() => {
-        child.stdin.end();
-      }, 500);
-    }, 500);
+      commandTimers.push(setTimeout(() => child.stdin.end(), 500));
+    }, 500));
   });
 }
 
+export function probeClaudeCli(
+  binaryPath: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+  maxOutputBytes = 1024 * 1024,
+  killGraceMs = 500,
+  strategies: readonly ClaudeProbeStrategy[] = defaultWaitingStrategies(),
+  spawnOne: typeof spawnStrategy = spawnStrategy,
+): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  return (async () => {
+    let lastFailure: Error | null = null;
+    for (const strategy of strategies) {
+      const remaining = deadline - Date.now();
+      if (remaining < 2_500) break;
+      try {
+        const output = await spawnOne(
+          strategy,
+          binaryPath,
+          remaining,
+          signal,
+          maxOutputBytes,
+          killGraceMs,
+        );
+        if (output.trim() && !looksLikeLauncherFailure(output, maxOutputBytes)) return output;
+        // The launcher itself failed (for example `script` without a TTY on
+        // socket stdin) — fall through to the next strategy.
+      } catch (catchError) {
+        if (classifyUsageError(catchError).kind === "cancelled") throw catchError;
+        lastFailure = catchError instanceof Error ? catchError : new Error(String(catchError));
+      }
+    }
+    throw new UsageError(
+      "transient",
+      `Could not launch Claude CLI in a usable terminal (tried: ${strategies.join(" → ")}; last: ${lastFailure?.message ?? "no output"})`,
+    );
+  })();
+}
+
 export class ClaudeCliProbeClient implements UsageClient<string, ClaudeUsageSnapshot> {
-  async fetch(binaryPath: string): Promise<ClaudeUsageSnapshot> {
+  private readonly inFlight = new Map<string, Promise<ClaudeUsageSnapshot>>();
+  private readonly cooldownUntil = new Map<string, number>();
+
+  constructor(
+    private readonly options: ProbeOptions = {},
+    private readonly probe: (
+      binaryPath: string,
+      timeoutMs: number,
+      signal?: AbortSignal,
+      maxOutputBytes?: number,
+      killGraceMs?: number,
+      strategies?: readonly ClaudeProbeStrategy[],
+    ) => Promise<string> = probeClaudeCli,
+  ) {}
+
+  fetch(binaryPath: string, options?: { signal?: AbortSignal }): Promise<ClaudeUsageSnapshot> {
+    const existing = this.inFlight.get(binaryPath);
+    if (existing) return this.waitForShared(existing, options?.signal);
+    if ((this.cooldownUntil.get(binaryPath) ?? 0) > Date.now()) {
+      return Promise.reject(new UsageError("transient", "Claude CLI recovery is cooling down after a failed attempt"));
+    }
+
+    const attempt = this.fetchOnce(binaryPath, options?.signal)
+      .catch((error) => {
+        // A cancelled poll is not a failed attempt: the next poll should retry
+        // immediately instead of being penalized by the failure cooldown.
+        if (classifyUsageError(error).kind !== "cancelled") {
+          this.cooldownUntil.set(binaryPath, Date.now() + (this.options.cooldownMs ?? 30_000));
+        }
+        throw error;
+      })
+      .finally(() => this.inFlight.delete(binaryPath));
+    this.inFlight.set(binaryPath, attempt);
+    return attempt;
+  }
+
+  private async fetchOnce(binaryPath: string, signal?: AbortSignal): Promise<ClaudeUsageSnapshot> {
     let output: string;
     try {
-      output = await probeCli(binaryPath, 10_000);
-    } catch (err) {
-      if (err instanceof TimeoutError) {
-        // Retry with longer timeout
-        output = await probeCli(binaryPath, 24_000);
-      } else {
-        throw err;
-      }
+      output = await this.probe(
+        binaryPath,
+        this.options.initialTimeoutMs ?? 10_000,
+        signal,
+        this.options.maxOutputBytes,
+        this.options.killGraceMs,
+        this.options.strategies,
+      );
+    } catch (error) {
+      if (!(error instanceof TimeoutError) || signal?.aborted) throw error;
+      output = await this.probe(
+        binaryPath,
+        this.options.retryTimeoutMs ?? 24_000,
+        signal,
+        this.options.maxOutputBytes,
+        this.options.killGraceMs,
+        this.options.strategies,
+      );
     }
+    return parseClaudeCliOutput(output);
+  }
 
-    const lines = output.split(/\r?\n/);
+  private waitForShared(promise: Promise<ClaudeUsageSnapshot>, signal?: AbortSignal): Promise<ClaudeUsageSnapshot> {
+    if (!signal) return promise;
+    if (signal.aborted) return Promise.reject(new UsageError("cancelled", "Claude CLI probe cancelled"));
+    return new Promise((resolve, reject) => {
+      const abort = () => reject(new UsageError("cancelled", "Claude CLI probe cancelled"));
+      signal.addEventListener("abort", abort, { once: true });
+      promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+  }
+}
 
-    let primary: RateWindowLegacy | null = null;
-    let secondary: RateWindowLegacy | null = null;
-    let opus: RateWindowLegacy | null = null;
-    let accountEmail: string | null = null;
-    let accountOrganization: string | null = null;
-    let loginMethod: string | null = null;
+export function parseClaudeCliOutput(output: string): ClaudeUsageSnapshot {
+  const lines = output.split(/\r?\n/);
+  if (claudeCliOutputIndicatesExpiredSession(output)) {
+    throw new UsageError("invalid-credentials", "Claude CLI session expired — run \"claude\" to re-login");
+  }
+  let primary: RateWindowLegacy | null = null;
+  let secondary: RateWindowLegacy | null = null;
+  let opus: RateWindowLegacy | null = null;
+  let accountEmail: string | null = null;
+  let accountOrganization: string | null = null;
+  const accountOrganizationId: string | null = null;
+  let loginMethod: string | null = null;
 
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i]!;
-      const lower = line.toLowerCase();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const lower = line.toLowerCase();
+    const identity = line.match(/(account_email|account_org|login_method)[:=]\s*(.+)/i);
+    if (identity?.[1].toLowerCase() === "account_email") accountEmail = identity[2]!.trim();
+    if (identity?.[1].toLowerCase() === "account_org") accountOrganization = identity[2]!.trim();
+    if (identity?.[1].toLowerCase() === "login_method") loginMethod = identity[2]!.trim();
 
-      if (lower.includes("account_email")) {
-        const m = line.match(/account_email[:=]\s*(.+)/i);
-        if (m) accountEmail = m[1]!.trim();
-      }
-      if (lower.includes("account_org")) {
-        const m = line.match(/account_org[:=]\s*(.+)/i);
-        if (m) accountOrganization = m[1]!.trim();
-      }
-      if (lower.includes("login_method")) {
-        const m = line.match(/login_method[:=]\s*(.+)/i);
-        if (m) loginMethod = m[1]!.trim();
-      }
+    const percent = parsePercent(line);
+    const resetLine = lines[i + 1] || "";
+    const resetText = resetLine.includes("Resets") ? resetLine.trim() : null;
+    if (lower.includes("current session") && percent !== null) {
+      primary = toRateWindow(100 - percent, resetText, 300);
+    }
+    if (lower.includes("current week") && percent !== null) {
+      const window = toRateWindow(100 - percent, resetText, 10080);
+      if (lower.includes("opus") || lower.includes("sonnet only")) opus = window;
+      else secondary = window;
+    }
+  }
 
-      if (lower.includes("current session")) {
-        const percent = parsePercent(line);
-        if (percent !== null) {
-          const used = Math.max(0, Math.min(100, 100 - percent));
-          const resetLine = lines[i + 1] || "";
-          primary = toRateWindow(used, resetLine.includes("Resets") ? resetLine.trim() : null, 300);
-        }
-      }
+  if (!primary) {
+    const modern = parseModernClaudeUsageOutput(lines, output);
+    if (modern) return modern;
+    if (outputIndicatesNoPlanUsage(output)) {
+      throw new UsageError(
+        "invalid-response",
+        "Claude CLI output contains no plan usage windows (plan may not expose usage — e.g. API Usage Billing)",
+      );
+    }
+    throw new UsageError(
+      "invalid-response",
+      `Could not parse primary usage window from Claude CLI output (${describeUnparseableOutput(output)})`,
+    );
+  }
+  return {
+    source: "cli",
+    primary,
+    secondary,
+    opus,
+    extraRateWindows: [],
+    providerCost: null,
+    updatedAt: new Date(),
+    accountEmail,
+    accountOrganization,
+    accountOrganizationId,
+    loginMethod,
+    subscriptionType: null,
+    rateLimitTier: null,
+  };
+}
 
-      if (lower.includes("current week")) {
-        const percent = parsePercent(line);
-        if (percent !== null) {
-          const used = Math.max(0, Math.min(100, 100 - percent));
-          const resetLine = lines[i + 1] || "";
-          const resetText = resetLine.includes("Resets") ? resetLine.trim() : null;
-          if (lower.includes("(all models)") || lower.includes("all models")) {
-            secondary = toRateWindow(used, resetText, 10080);
-          } else if (lower.includes("opus") || lower.includes("sonnet only")) {
-            opus = toRateWindow(used, resetText, 10080);
-          }
-        }
+/**
+ * Scanner for current Claude Code `/usage` renderings (v2.6.x "Usage" tabs and
+ * later). The legacy "Current session: NN%" block is gone; the panel renders
+ * `NN%`-bearing rows whose labels mention session/week tokens elsewhere on the
+ * same line or its immediate neighbors. Percentage values are remaining
+ * (legacy conversion applies when the row reads as "remaining").
+ */
+export function parseModernClaudeUsageOutput(lines: string[], output: string): ClaudeUsageSnapshot | null {
+  const plain = lines.map((line) => stripAnsi(line));
+  const collapsed = plain.join("\n").replace(/[ ]+/g, " ").toLowerCase();
+  if (!/\b\d{1,3}(?:\.\d+)?\s*%/.test(collapsed)) return null;
+
+  interface WindowHit {
+    percent: number;
+    resetText: string | null;
+    windowMinutes: number;
+    kind: "primary" | "secondary" | "opus";
+  }
+  const hits: WindowHit[] = [];
+  for (let i = 0; i < plain.length; i++) {
+    const raw = plain[i]!;
+    const lower = raw.toLowerCase();
+    const percent = parsePercent(raw);
+    if (percent === null) continue;    // Consider a bounded text window around the percent occurrence: the same
+    // line and the immediately previous line carry the window label (the
+    // terminal renders the panel in a grid; legacy puts both on one line,
+    // modern renderings may separate them by one row).
+    const label = lower;
+    const labelContext = `${plain[i - 1] ?? ""} ${raw}`.toLowerCase();
+
+    const reset = findResetNearby(plain, i);
+
+    if (
+      /(?:5[- ]?hour|session|rolling)/.test(labelContext) ||
+      /(?:5[- ]?hour|session|rolling)/.test(label)
+    ) {
+      if (!hits.some((hit) => hit.kind === "primary")) {
+        hits.push({ kind: "primary", percent, resetText: reset, windowMinutes: 300 });
       }
+      continue;
     }
-
-    if (!primary) {
-      throw new Error("Could not parse primary usage window from CLI output");
+    if (/(?:week|7[- ]?day)/.test(labelContext)) {
+      const isOpus = /opus|sonnet only/.test(labelContext);
+      const kind: WindowHit["kind"] = isOpus ? "opus" : "secondary";
+      if (!hits.some((hit) => hit.kind === kind)) {
+        hits.push({ kind, percent, resetText: reset, windowMinutes: 10080 });
+      }
     }
+  }
 
-    return {
-      source: "cli",
-      primary,
-      secondary,
-      opus,
-      extraRateWindows: [],
-      providerCost: null,
-      updatedAt: new Date(),
-      accountEmail,
-      accountOrganization,
-      loginMethod,
-      subscriptionType: null,
-      rateLimitTier: null,
-    };
+  const primary = hits.find((hit) => hit.kind === "primary");
+  const secondary = hits.find((hit) => hit.kind === "secondary");
+  const opus = hits.find((hit) => hit.kind === "opus");
+  if (!primary) return null;
+
+  // Claude renders remaining percentages in both legacy and modern panels;
+  // normalize to usedPercent like the legacy path.
+  const remainingToUsed = (percent: number): number => Math.max(0, Math.min(100, 100 - percent));
+
+  const identity = output.match(/(account_email|account_org|login_method)[:=]\s*(.+)/i);
+  return {
+    source: "cli",
+    primary: toRateWindow(remainingToUsed(primary.percent), primary.resetText, primary.windowMinutes),
+    secondary: secondary ? toRateWindow(remainingToUsed(secondary.percent), secondary.resetText, secondary.windowMinutes) : null,
+    opus: opus ? toRateWindow(remainingToUsed(opus.percent), opus.resetText, opus.windowMinutes) : null,
+    extraRateWindows: [],
+    providerCost: null,
+    updatedAt: new Date(),
+    accountEmail: identity?.[1]?.toLowerCase() === "account_email" ? identity[2]!.trim() : null,
+    accountOrganization: identity?.[1]?.toLowerCase() === "account_org" ? identity[2]!.trim() : null,
+    accountOrganizationId: null,
+    loginMethod: identity?.[1]?.toLowerCase() === "login_method" ? identity[2]!.trim() : null,
+    subscriptionType: null,
+    rateLimitTier: null,
+  };
+}
+
+function findResetNearby(lines: string[], percentIndex: number): string | null {
+  for (let offset = 1; offset <= 2; offset++) {
+    const line = lines[percentIndex + offset];
+    if (!line) break;
+    const trimmed = line.trim();
+    if (/resets?\b/i.test(trimmed)) return trimmed;
   }
+  return null;
+}
+
+const PLAN_USAGE_ABSENT_SIGNATURES: RegExp[] = [/total cost/i, /usage:\s*\d+ (?:input|tokens)/i, /total duration/i];
+
+function outputIndicatesNoPlanUsage(output: string): boolean {
+  const plain = stripAnsi(output);
+  if (/\d{1,3}(?:\.\d+)?\s*%/.test(plain)) return false;
+  return PLAN_USAGE_ABSENT_SIGNATURES.every((signature) => signature.test(plain));
+}
+
+function describeUnparseableOutput(output: string): string {
+  const plain = stripAnsi(output);
+  if (!plain.trim()) return "empty output";
+  const firstLine = plain.split(/\r?\n/).find((line) => line.trim())?.trim() ?? "";
+  return firstLine.length > 120 ? `${firstLine.slice(0, 120)}…` : firstLine;
+}
+
+function claudeCliOutputIndicatesExpiredSession(output: string): boolean {
+  const lower = output.toLowerCase();
+  return (
+    lower.includes("failed to authenticate") ||
+    lower.includes("oauth session expired") ||
+    lower.includes("could not be refreshed")
+  );
 }