Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

21.0 KB
Raw Blame
/**
 * The tier-1 deadline and the two switches.
 *
 * THE DEADLINE IS THE SHARPEST REQUIREMENT IN THIS PHASE, and it is a
 * DERIVATION rather than a constant. Phase 0 measured Claude Code's client
 * abort against a custom base URL at 359.607 s and then PROVED that the number
 * is `API_TIMEOUT_MS`'s 360 000 ms default rather than a fixed watchdog, by
 * setting the variable to 20 000 and observing six aborts at exactly 20.000 s.
 *
 * So a user who has set `API_TIMEOUT_MS=60000` has a client that gives up at
 * 60 s. Hold their request for a deadline derived from the DEFAULT and every
 * episode ends in `client_gone`: recovery never engages, on that machine,
 * silently, forever, with nothing printed anywhere. That is the failure this
 * file exists to make impossible, and it is why the first test asserts the
 * value MOVES with the environment rather than asserting any single number.
 */

import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { magmuxPaneCapability } from "../launcher/magmux-wrapper.js";
import { readRecoveryEnabled, readRecoveryUi } from "../profile-config.js";
import {
  CLIENT_CEILING_CLAMP_MS,
  DEADLINE_MARGIN_MS,
  DEFAULT_API_TIMEOUT_MS,
  DEFAULT_TIER1_DEADLINE_MS,
  TIER1_DEADLINE_FLOOR_MS,
  applyRetryWatchdog,
  logDeadlineIfShortened,
  recoverySurfaceAllowed,
  resetDeadlineNotice,
  resetRecoveryFlagOverrides,
  resolveRecoveryEnabled,
  resolveRecoveryUi,
  resolveTier1DeadlineMs,
  retryWatchdogEnv,
  setRecoveryFlagOverrides,
} from "./settings.js";
import {
  capturedRecoveryLines,
  startLogCapture,
  stopLogCapture,
} from "./test-helpers/capture-log.js";

const ENV_KEYS = ["API_TIMEOUT_MS", "CLAUDISH_RECOVERY", "CLAUDISH_RECOVERY_UI"] as const;
const saved: Record<string, string | undefined> = {};

beforeEach(() => {
  for (const k of ENV_KEYS) {
    saved[k] = process.env[k];
    delete process.env[k];
  }
  resetRecoveryFlagOverrides();
  resetDeadlineNotice();
});

afterEach(() => {
  for (const k of ENV_KEYS) {
    if (saved[k] === undefined) delete process.env[k];
    else process.env[k] = saved[k] as string;
  }
  resetRecoveryFlagOverrides();
  resetDeadlineNotice();
});

// ───────────────────────────────────────────────────────────────────────────
// The deadline
// ───────────────────────────────────────────────────────────────────────────

describe("resolveTier1DeadlineMs — derived from API_TIMEOUT_MS, never hardcoded", () => {
  test("the measured default is what the derivation is anchored to", () => {
    // Recorded so a later edit that 'simplifies' the anchor has to argue with
    // the measurement rather than with a bare number.
    expect(DEFAULT_API_TIMEOUT_MS).toBe(360_000);
    expect(CLIENT_CEILING_CLAMP_MS).toBe(300_000);
    expect(DEADLINE_MARGIN_MS).toBe(30_000);
    expect(TIER1_DEADLINE_FLOOR_MS).toBe(15_000);
  });

  test("unset ⇒ 270 000 ms (min(default,300k) − 30k)", () => {
    expect(resolveTier1DeadlineMs({} as NodeJS.ProcessEnv)).toBe(270_000);
    expect(DEFAULT_TIER1_DEADLINE_MS).toBe(270_000);
  });

  test("API_TIMEOUT_MS=60000 ⇒ 30 000 ms, far BELOW the default hold", () => {
    // The whole point. A hardcoded 270 s here would outlive this user's client
    // by 210 s and end every episode in client_gone.
    const d = resolveTier1DeadlineMs({ API_TIMEOUT_MS: "60000" } as NodeJS.ProcessEnv);
    expect(d).toBe(30_000);
    expect(d).toBeLessThan(60_000);
    expect(d).toBeLessThan(DEFAULT_TIER1_DEADLINE_MS);
  });

  test("the value MOVES with the environment — it is not a constant", () => {
    // Mutation-relevant: an implementation that returned a constant passes the
    // default case and fails here, which is the only case that matters.
    const seen = new Set(
      ["45000", "60000", "120000", "240000", "360000"].map((v) =>
        resolveTier1DeadlineMs({ API_TIMEOUT_MS: v } as NodeJS.ProcessEnv)
      )
    );
    expect(seen.size).toBeGreaterThan(1);
    expect([...seen].sort((a, b) => a - b)).toEqual([15_000, 30_000, 90_000, 210_000, 270_000]);
  });

  test("an absurdly small API_TIMEOUT_MS clamps UP to the floor, not to zero or negative", () => {
    // 20 000 − 30 000 is negative. A raw subtraction would give a deadline in
    // the past, so shouldSkipTier1's no-budget gate would fire on every single
    // request and the feature would be off with no trace.
    expect(resolveTier1DeadlineMs({ API_TIMEOUT_MS: "20000" } as NodeJS.ProcessEnv)).toBe(15_000);
    expect(resolveTier1DeadlineMs({ API_TIMEOUT_MS: "1" } as NodeJS.ProcessEnv)).toBe(15_000);
    expect(resolveTier1DeadlineMs({ API_TIMEOUT_MS: "30000" } as NodeJS.ProcessEnv)).toBe(15_000);
  });

  test("a generous API_TIMEOUT_MS is clamped by the client ceiling", () => {
    expect(resolveTier1DeadlineMs({ API_TIMEOUT_MS: "900000" } as NodeJS.ProcessEnv)).toBe(270_000);
  });

  test("garbage, zero and negative all fall back to the default ceiling", () => {
    for (const raw of ["", "abc", "0", "-5000", "NaN"]) {
      expect(resolveTier1DeadlineMs({ API_TIMEOUT_MS: raw } as NodeJS.ProcessEnv)).toBe(270_000);
    }
  });

  test("reads process.env by default", () => {
    process.env.API_TIMEOUT_MS = "60000";
    expect(resolveTier1DeadlineMs()).toBe(30_000);
  });
});

describe("logDeadlineIfShortened", () => {
  // Through the REAL logger — see capture-log.ts for why not `mock.module()`.
  beforeAll(() => startLogCapture());
  afterAll(() => stopLogCapture());

  test("says nothing at the default — a healthy default must not be noisy", async () => {
    logDeadlineIfShortened(resolveTier1DeadlineMs({} as NodeJS.ProcessEnv));
    expect(await capturedRecoveryLines()).toEqual([]);
  });

  test("fires once when the environment shortens the hold, naming both numbers", async () => {
    process.env.API_TIMEOUT_MS = "60000";
    logDeadlineIfShortened(resolveTier1DeadlineMs());
    logDeadlineIfShortened(resolveTier1DeadlineMs());
    logDeadlineIfShortened(resolveTier1DeadlineMs());
    const lines = await capturedRecoveryLines();
    // Once per process: a shortened budget is not an error and must not be
    // repeated on every failing request.
    expect(lines.length).toBe(1);
    expect(lines[0]).toContain("tier-1 hold shortened to 30s");
    // Both halves matter: what you got, and what you would have got. A line
    // carrying only the first is not actionable.
    expect(lines[0]).toContain("API_TIMEOUT_MS=60000");
    expect(lines[0]).toContain("default would be 270s");
  });
});

// ───────────────────────────────────────────────────────────────────────────
// The switches
// ───────────────────────────────────────────────────────────────────────────

describe("resolveRecoveryEnabled / resolveRecoveryUi — flag > env > scoped > true", () => {
  test("nothing set ⇒ true for both (the default is ON)", () => {
    expect(resolveRecoveryEnabled()).toBe(true);
    expect(resolveRecoveryUi()).toBe(true);
  });

  test("env alone decides when no flag is given", () => {
    process.env.CLAUDISH_RECOVERY = "0";
    process.env.CLAUDISH_RECOVERY_UI = "false";
    expect(resolveRecoveryEnabled()).toBe(false);
    expect(resolveRecoveryUi()).toBe(false);
    process.env.CLAUDISH_RECOVERY = "1";
    process.env.CLAUDISH_RECOVERY_UI = "true";
    expect(resolveRecoveryEnabled()).toBe(true);
    expect(resolveRecoveryUi()).toBe(true);
  });

  test("the flag BEATS the environment, in both directions", () => {
    process.env.CLAUDISH_RECOVERY = "0";
    process.env.CLAUDISH_RECOVERY_UI = "0";
    setRecoveryFlagOverrides({ recovery: true, recoveryUi: true });
    expect(resolveRecoveryEnabled()).toBe(true);
    expect(resolveRecoveryUi()).toBe(true);

    process.env.CLAUDISH_RECOVERY = "1";
    process.env.CLAUDISH_RECOVERY_UI = "1";
    setRecoveryFlagOverrides({ recovery: false, recoveryUi: false });
    expect(resolveRecoveryEnabled()).toBe(false);
    expect(resolveRecoveryUi()).toBe(false);
  });

  test("the two switches are independent — the UI switch never gates the ladder", () => {
    // DEC-1: the loopback carve-out is deleted. `recoveryUi` decides one thing
    // only, and it is not whether a retry happens.
    setRecoveryFlagOverrides({ recoveryUi: false });
    expect(resolveRecoveryUi()).toBe(false);
    expect(resolveRecoveryEnabled()).toBe(true);
  });

  test("an unparseable env value is NO opinion, not false", () => {
    // "yes"/"on"/"" must not silently disable recovery: a typo'd off-switch
    // that half-works is worse than one that does not work at all.
    for (const raw of ["yes", "on", "", "  ", "2", "off"]) {
      process.env.CLAUDISH_RECOVERY = raw;
      expect(resolveRecoveryEnabled()).toBe(true);
    }
  });

  test("whitespace and case are tolerated on the values that DO parse", () => {
    process.env.CLAUDISH_RECOVERY = " FALSE ";
    expect(resolveRecoveryEnabled()).toBe(false);
    process.env.CLAUDISH_RECOVERY = " True ";
    expect(resolveRecoveryEnabled()).toBe(true);
  });

  test("resetRecoveryFlagOverrides clears the flag layer", () => {
    setRecoveryFlagOverrides({ recovery: false });
    expect(resolveRecoveryEnabled()).toBe(false);
    resetRecoveryFlagOverrides();
    expect(resolveRecoveryEnabled()).toBe(true);
  });
});

describe("the scoped layers: project .claudish.json > global config.json", () => {
  let dir: string;
  beforeEach(() => {
    dir = mkdtempSync(join(tmpdir(), "claudish-recovery-scope-"));
  });
  afterEach(() => rmSync(dir, { recursive: true, force: true }));

  const paths = () => ({
    global: () => join(dir, "config.json"),
    project: () => join(dir, ".claudish.json"),
  });

  test("project beats global", () => {
    writeFileSync(join(dir, "config.json"), JSON.stringify({ recoveryUi: { enabled: true } }));
    writeFileSync(join(dir, ".claudish.json"), JSON.stringify({ recoveryUi: { enabled: false } }));
    expect(readRecoveryUi(paths())).toBe(false);
  });

  test("global answers when the project file says nothing", () => {
    writeFileSync(join(dir, "config.json"), JSON.stringify({ recovery: { enabled: false } }));
    expect(readRecoveryEnabled(paths())).toBe(false);
  });

  test("`{}` is NO OPINION and falls through to the next scope", () => {
    // The reason both fields are objects rather than bare booleans. A bare
    // boolean cannot express 'present but undecided', so a project file that
    // merely mentions the key would override the global one with `false`.
    writeFileSync(join(dir, "config.json"), JSON.stringify({ recoveryUi: { enabled: false } }));
    writeFileSync(join(dir, ".claudish.json"), JSON.stringify({ recoveryUi: {} }));
    expect(readRecoveryUi(paths())).toBe(false);
  });

  test("neither scope stating a boolean ⇒ undefined, so the caller's default applies", () => {
    writeFileSync(join(dir, "config.json"), JSON.stringify({ recoveryUi: { enabled: "yes" } }));
    expect(readRecoveryUi(paths())).toBeUndefined();
    expect(readRecoveryEnabled(paths())).toBeUndefined();
  });

  test("a garbled file is skipped rather than fatal", () => {
    writeFileSync(join(dir, ".claudish.json"), "{ not json");
    writeFileSync(join(dir, "config.json"), JSON.stringify({ recovery: { enabled: false } }));
    expect(readRecoveryEnabled(paths())).toBe(false);
  });

  test("a missing file is skipped rather than fatal", () => {
    expect(readRecoveryUi(paths())).toBeUndefined();
  });
});

// ───────────────────────────────────────────────────────────────────────────
// `recoverySurfaceAllowed` — the gate that decides whether a launch PAYS for
// the recovery surface. It shipped as `resolveRecoveryUi()` alone at both
// `claude-runner.ts` call sites, so `--no-recovery` still wrapped the session
// in magmux. Observed on a real launch at HEAD 60cdb37, from the OS's own
// process table: `magmux --id claudish-84222` running under `--no-recovery`.
// ───────────────────────────────────────────────────────────────────────────

describe("recoverySurfaceAllowed — BOTH switches, because a wrap nothing can use is pure cost", () => {
  test("both on (the default) ⇒ the launch may own a surface", () => {
    expect(recoverySurfaceAllowed()).toBe(true);
  });

  test("--no-recovery withdraws the surface even with the UI switch left ON", () => {
    // THE REGRESSION. With the ladder disabled `shouldSkipTier1` answers
    // `recovery-disabled` on the first classified failure, so no episode is
    // ever opened and `ensureRecoveryUi` is never called: the pane CANNOT
    // appear. Wrapping anyway charges the emulator's native scrollback
    // (RISK-4), +89 ms of launch and a generated launcher script for a surface
    // that is structurally unreachable — and makes RISK-7's "restores today's
    // behaviour everywhere, byte for byte" false about the launch.
    setRecoveryFlagOverrides({ recovery: false });
    expect(resolveRecoveryUi()).toBe(true); // the UI switch is untouched…
    expect(recoverySurfaceAllowed()).toBe(false); // …and the surface is still withdrawn
  });

  test("every layer of the master switch withdraws it, not just the flag", () => {
    process.env.CLAUDISH_RECOVERY = "0";
    expect(recoverySurfaceAllowed()).toBe(false);
    // …and the flag can put it back, since the flag beats the environment.
    setRecoveryFlagOverrides({ recovery: true });
    expect(recoverySurfaceAllowed()).toBe(true);
  });

  test("--no-recovery-ui withdraws it with the ladder left ON", () => {
    // The half that already worked: retries still run, they simply answer
    // inline at exhaustion because no lease can exist.
    setRecoveryFlagOverrides({ recoveryUi: false });
    expect(resolveRecoveryEnabled()).toBe(true);
    expect(recoverySurfaceAllowed()).toBe(false);
  });

  test("the watchdog moves with it — surface and reach are one decision", () => {
    setRecoveryFlagOverrides({ recovery: false });
    expect(retryWatchdogEnv({ paneEligible: true })).toEqual({});
    resetRecoveryFlagOverrides();
    expect(retryWatchdogEnv({ paneEligible: true })).toEqual({ CLAUDE_CODE_RETRY_WATCHDOG: "1" });
  });
});

describe("an MCP pane child is never eligible for a recovery surface (D22)", () => {
  // The pane is a headless magmux: it exports MAGMUX_SOCK, so without the
  // pane-child case the child would read as `ambient`, export the ~300-attempt
  // watchdog and install a banner nobody can see, over the screen the MCP
  // server classifies.
  const paneChildEnv = {
    CLAUDISH_PANE_CHILD: "1",
    MAGMUX_SOCK: "/tmp/claudish-mux-501/magmux-c1-t1.sock",
  };

  test("magmuxPaneCapability answers none/pane-child before the ambient branch", () => {
    expect(
      magmuxPaneCapability({
        interactive: true,
        stdoutIsTty: true,
        parentEnv: paneChildEnv,
        magmuxBinary: "/opt/magmux",
      })
    ).toEqual({ kind: "none", reason: "pane-child" });
  });

  test("T-U-9: flag and pane cwd disable recovery before the ambient branch", () => {
    expect(
      magmuxPaneCapability({
        interactive: true,
        stdoutIsTty: true,
        parentEnv: {
          CLAUDISH_PANE_CHILD: "1",
          CLAUDISH_PANE_CWD: "/w",
          MAGMUX_SOCK: "/tmp/x.sock",
        },
        magmuxBinary: "/opt/magmux",
      })
    ).toEqual({ kind: "none", reason: "pane-child" });
  });

  test("the same environment without the marker is still ambient", () => {
    expect(
      magmuxPaneCapability({
        interactive: true,
        stdoutIsTty: false,
        parentEnv: { MAGMUX_SOCK: paneChildEnv.MAGMUX_SOCK },
        magmuxBinary: null,
      })
    ).toEqual({ kind: "ambient", sock: paneChildEnv.MAGMUX_SOCK });
  });

  test("a pane child exports no watchdog and drops a claudish-marked inherited one", () => {
    const capability = magmuxPaneCapability({
      interactive: true,
      stdoutIsTty: false,
      parentEnv: paneChildEnv,
    });
    // What an MCP server started by a wrapped claudish session passes down.
    const env: Record<string, string | undefined> = {
      CLAUDE_CODE_RETRY_WATCHDOG: "1",
      CLAUDISH_SET_RETRY_WATCHDOG: "1",
    };
    applyRetryWatchdog(env, { paneEligible: capability.kind !== "none" });
    expect(env.CLAUDE_CODE_RETRY_WATCHDOG).toBeUndefined();
    expect(env.CLAUDISH_SET_RETRY_WATCHDOG).toBeUndefined();
  });

  test("a user's own unmarked watchdog survives in a pane child", () => {
    const env: Record<string, string | undefined> = { CLAUDE_CODE_RETRY_WATCHDOG: "1" };
    applyRetryWatchdog(env, { paneEligible: false });
    expect(env.CLAUDE_CODE_RETRY_WATCHDOG).toBe("1");
  });
});

describe("claude-runner asks that gate, and not the UI switch alone", () => {
  // A SOURCE GUARD, and it is the only thing that can fail on the defect that
  // actually shipped. The predicate above was always correct as an expression;
  // what was wrong was the CALL SITE — `resolveRecoveryUi() &&
  // paneCapability.kind === "wrap"` — and `launchClaudeCode` cannot be unit
  // tested for it: reaching that line means spawning Claude Code inside a real
  // magmux on a real TTY. That is C-8's live matrix, not a unit test. This is
  // the cheap half, and it fails the moment either call site is reverted.
  const source = readFileSync(resolve(import.meta.dir, "../claude-runner.ts"), "utf8");
  // The comments there name `resolveRecoveryUi()` while explaining why it is
  // not enough, so a guard that did not strip them would pass on reverted code.
  const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");

  // Since the hook system (architecture §3.2, §7.5) the gate is planned in ONE call,
  // `planInteractiveSurfaces({capability, recoveryAllowed, sessionHooksNeedDriver})`,
  // whose rules `hooks/session/interactive-launch.test.ts` pins. These guards check that
  // claude-runner feeds it the two-switch predicate and uses its answer at both sites.
  const plan = /planInteractiveSurfaces\(\{([\s\S]{0,400}?)\}\)/.exec(code)?.[1];

  test("the surface plan is asked with recoverySurfaceAllowed(), and the wrap ternary obeys it", () => {
    expect(
      plan,
      "could not find the planInteractiveSurfaces call in claude-runner.ts"
    ).toBeTruthy();
    expect(plan).toContain("recoveryAllowed: recoverySurfaceAllowed()");
    expect(plan).toContain("capability: paneCapability");
    // The reverted form, named explicitly so the failure says what went wrong
    // rather than which substring is missing.
    expect(
      /\bresolveRecoveryUi\(\)/.test(plan as string)
        ? "the surface plan asks resolveRecoveryUi() — --no-recovery will still wrap the session in magmux"
        : null
    ).toBeNull();
    const gate = /const wrap =\s*([\s\S]{0,160}?)\?\s*\n?\s*planMagmuxWrap/.exec(code)?.[1];
    expect(gate, "could not find the wrap ternary in claude-runner.ts").toBeTruthy();
    expect(gate).toContain("surfaces.wrap");
    expect(gate).toContain('paneCapability.kind === "wrap"');
    expect(/\bresolveRecoveryUi\(\)/.test(gate as string)).toBe(false);
  });

  test("the ambient-magmux branch installs the recovery UI from that plan", () => {
    const branch = code
      .split("\n")
      .find((l) => l.includes("else if") && /ambient|MAGMUX_SOCK/.test(l));
    expect(branch, "could not find the ambient branch in claude-runner.ts").toBeTruthy();
    expect(branch).toContain('surfaces.recoveryUi === "ambient"');
    expect(
      /\bresolveRecoveryUi\(\)/.test(branch as string)
        ? "the ambient branch asks resolveRecoveryUi() — --no-recovery still installs the recovery UI in a grid pane"
        : null
    ).toBeNull();
  });

  test("the ambient branch reads magmuxPaneCapability(), not its own MAGMUX_SOCK test (F8)", () => {
    // `network-recovery.md`: one predicate decides the surface. The ambient branch
    // used to restate it as `config.interactive && process.env.MAGMUX_SOCK`, so a
    // case added to `magmuxPaneCapability()` (the pane child, D22) would still
    // install the recovery UI here. The plan takes `paneCapability` whole.
    const branch = code
      .split("\n")
      .find((l) => l.includes("else if") && /ambient|MAGMUX_SOCK/.test(l));
    expect(branch, "could not find the ambient branch in claude-runner.ts").toBeTruthy();
    expect(branch).not.toContain("MAGMUX_SOCK");
    expect(plan).toContain("capability: paneCapability");
    expect(plan).not.toContain("MAGMUX_SOCK");
  });
});