Skip to content

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

79.2 KB
Raw Blame
// ─── SessionManager ──────────────────────────────────────────────────────────
//
// Lifecycle owner for MCP sessions. Each session is one INTERACTIVE Claude Code,
// launched through claudish (`claudish -i --model X -y --quiet --session-id <uuid>
// --add-dir <turnDir> [caller flags]`) inside its own headless magmux pane and driven
// over the pane's socket (packages/cli/src/pane/, architecture §2). There is no `-p`,
// no `--stdin` and no stream-json: the child's own transcript is the turn oracle, and
// the pane session's phase table is the clock of every state record this file writes.
//
// The policy stays here (D8): a one-shot session's verdict is `classifyRunOutput` with
// no byte floor and no pattern; an interactive session continues after each turn and
// fails only on an API-error turn (D20); a question or a permission dialog waits for
// `send_input` (D19 is team's rule, not ours). `send_input` is accepted in every
// non-terminal state and queued (D17). `timeout_seconds` is the caller's own deadline
// and the only post-acceptance timer (D10).
//
// Session hooks (hook-system §2.3, §7.3, §7.4): every child gets an owner-created
// inbox (`hook-inbox.jsonl` in its session dir) and `CLAUDISH_HOOK_INBOX` /
// `CLAUDISH_HOOK_SESSION`. When this process's hook engine has a session hook, the pane
// gets a binding and each settled turn's answer is RECORDED into the output at once
// (`recordAnswer`), before its verdict, so no terminal path can lose it.
//
// The 10.4.0 session records are kept, byte for byte where the magus monitor reads
// them (§20.1): `spawn.json` before any pane, `waits.jsonl` from the pane's transition
// hook, `meta.json` through `toMetaRecord` with every 10.4.0 key, `events.jsonl` with
// one `assistant` line per main-chain message id.

import { randomUUID } from "node:crypto";
import {
  type WriteStream,
  appendFileSync,
  closeSync,
  createWriteStream,
  existsSync,
  mkdirSync,
  openSync,
  readFileSync,
  readSync,
  renameSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { join, resolve, sep } from "node:path";

import { ENV } from "../config.js";
import { UPSTREAM_ERROR_LOG_ENV } from "../handlers/shared/upstream-error-capture.js";
import type { HookEngine } from "../hooks/engine.js";
import { loadHooksOnce } from "../hooks/index.js";
import { createHookInbox } from "../hooks/injection/inbox.js";
import { HOOK_INBOX_ENV } from "../hooks/injection/sinks.js";
import { HOOK_SESSION_ENV } from "../hooks/request-stage.js";
import {
  type SessionHookBinding,
  createSessionHookBinding,
  reportOwnerWithoutHooks,
  sessionHooksNeedBinding,
} from "../hooks/session/binding.js";
import {
  type Accounting,
  type CaptureResult,
  type CaptureUnchanged,
  ContractErrorException,
  DEFAULT_PANE_COLS,
  DEFAULT_PANE_ROWS,
  FAILURE_REASONS,
  type FailureReason,
  type FinalVerdict,
  type PaneBlock,
  type PaneDiagnostics,
  type PaneSession,
  type PaneSessionOptions,
  type PaneSize,
  type PaneSnapshot,
  type ResizeResult,
  SLOT_STATES,
  type SessionCancelResult,
  type SessionRow,
  type SettledTurn,
  type SlotState,
  assertMagmuxAvailable,
  chainAnswerOf,
  checkChildFlags,
  clampPaneSize,
  deliveryRefusal,
  flagsRemoveRead,
  isTerminalState,
  mergeAccounting,
  readTokenFileCached,
  reasonDetail,
  releasePaneReservations,
  reservePanes,
  resolveProvider,
  sockRootFor,
  startPaneSession,
  upstreamRecordsFor,
} from "../pane/index.js";
import { redactSecrets } from "../redact.js";
import { projectsDir, transcriptPathFor } from "../session/session-discovery.js";
import { TRUNCATION_NOTE, type TeamRunOutcome, classifyRunOutput } from "../team-orchestrator.js";
import { readTokenStatsAt } from "../team-stats.js";
import { sessionsDirFrom } from "./home-dir.js";
import { buildInheritedSettingsLayer } from "./inherited-settings.js";
import { hostPidFrom } from "./parent-session.js";
import { ScrollbackBuffer } from "./scrollback-buffer.js";
import type {
  SessionCreateOptions,
  SessionEventType,
  SessionInfo,
  SessionManagerOptions,
} from "./types.js";

/** One record of the session's own event log, as `get_diagnostics` returns it. */
export interface DiagnosticEvent {
  /**
   * When the record was written, ISO-8601 — or `""` for a record recovered from
   * `events.jsonl` after the session left memory whose line carries no `at`.
   * Empty rather than back-filled from the file's mtime: a fabricated timestamp is
   * indistinguishable from a measured one.
   */
  at: string;
  /** The record's `type` (`state`, `tool`, `anomaly`, `assistant`), or null. */
  label: string | null;
  /** The record, redacted and truncated to `EVENT_PREVIEW_CHARS`. */
  preview: string;
  /** True when `preview` is a prefix rather than the whole record. */
  truncated: boolean;
}

/** What `get_diagnostics` returns. Every field is reachable without a filesystem read. */
export interface SessionDiagnostics {
  sessionId: string;
  state: SlotState;
  /** The current session event (10.4.0's `status` key, RB7). */
  event: SessionEventType;
  reason: FailureReason | null;
  detail: string | null;
  /** The model as the caller asked for it. */
  model: string;
  /** The pinned `provider@model` the child was spawned with, or null. */
  spawnModel: string | null;
  provider: string | null;
  shape: "one-shot" | "interactive";
  /** The pane's internal phase; null when the session is not live. */
  phase: string | null;
  exitCode: number | null;
  /** Seconds since the last screen change or transcript append; null when not live. */
  idleSeconds: number | null;
  elapsedSeconds: number;
  /** The session's own timeout, for reading `elapsedSeconds` against (0 when unknown). */
  timeoutSeconds: number;
  /** Bytes of answer prose in `get_output`. Zero on a session that produced no answer. */
  outputBytes: number;
  turnsCompleted: number;
  tokensIn: number | null;
  tokensOut: number | null;
  costUsd: number | null;
  toolCalls: number;
  pendingInputs: number;
  /** Queued hook injections (hook-system §4.7 rule 11); 0 when not live. */
  pendingHookInputs: number;
  /** Whether claudish holds a live socket to the pane's magmux right now. */
  connected: boolean;
  /** The last non-empty rows of the child's screen, redacted (a PTY has no separate stderr). */
  screenTail: string;
  pane: string | null;
  sockPath: string | null;
  /** The head of magmux's own stderr, redacted. */
  magmuxStderr: string;
  /** The child's Claude Code session-registry record as last read (telemetry); null when none. */
  registry: { status: string | null; waitingFor: string | null; version: string | null } | null;
  captureSource: SessionInfo["captureSource"];
  turnSource: SessionInfo["turnSource"];
  /** Bytes of assistant text before a file-delivered turn's task file was read. */
  preambleBytes: number;
  readCoverage: {
    linesTotal: number;
    linesReturned: number;
    complete: boolean;
    reads: number;
  } | null;
  /**
   * magmux's input gate for the pane as last read (`ready`, `reason`, `detail`, `ageMs`
   * since the reading); null when not live or not connected.
   */
  gate: PaneDiagnostics["gate"];
  /**
   * The last gated send's outcome in the gate's words (`kind`, `reason`, `accept`,
   * `evidence`, `retypeCause`, `attempts`); null before the first send or when not live.
   */
  lastSend: PaneDiagnostics["lastSend"];
  claudeCodeVersion: string | null;
  /** Deduplicated anomaly keys with counts (`illegal_transition:…`, `socket_reconnected ×2`, …). */
  anomalies: readonly string[];
  /** The tail of the session's own event records, oldest → newest. */
  recentEvents: readonly DiagnosticEvent[];
  /** How many records the ring holds (it caps at `EVENT_RING_SIZE`). */
  eventsTotal: number;
  /** Raw JSONL records from the child proxy's upstream-error capture, newest last. */
  upstreamErrors: readonly string[];
  claudeSessionId: string | null;
  transcriptPath: string | null;
  sessionDir: string;
  eventLogPath: string;
  upstreamErrorLogPath: string;
}

/** What `get_output` returns. */
export interface SessionOutput {
  sessionId: string;
  state: SlotState;
  output: string;
  totalLines: number;
  turnsCompleted: number;
  tokensIn: number | null;
  tokensOut: number | null;
  elapsedSeconds: number;
  /** Seconds since the last activity. Null when not live. */
  idleSeconds: number | null;
}

/** What `send_input` returns (§4.2). */
export type SendInputResult =
  | { success: true; queued: number }
  | {
      success: false;
      reason: "terminal" | "unknown_session" | "delivery_unavailable" | "unsupported_command";
      state: SlotState | null;
    };

interface SessionEntry {
  info: SessionInfo;
  /** null before the pane started, and for a session whose pane never started */
  session: PaneSession | null;
  /** Answer prose, one line per entry. What `get_output` returns. */
  scrollback: ScrollbackBuffer;
  outputLogStream: WriteStream | null;
  sessionDir: string;
  cwd: string;
  tokenFile: string;
  eventLogPath: string;
  /** Bytes already written to `events.jsonl`; the log stops at EVENT_LOG_LIMIT. */
  eventLogBytes: number;
  upstreamErrorLogPath: string;
  /** The last `EVENT_RING_SIZE` event records, redacted and truncated. */
  eventRing: DiagnosticEvent[];
  /** Bytes of answer prose appended (the `outputBytes` metric). */
  proseBytes: number;
  /**
   * The answer text each turn index has put in the scrollback. A background notification
   * after the settle re-settles the SAME turn (D23) with a longer answer; only its new tail
   * is appended.
   */
  answeredTurns: Map<number, string>;
  /** The owner-created hook inbox; null when it could not be created. */
  inboxPath: string | null;
  waitLogPath: string;
  waitLogBytes: number;
  /** The `since` of the wait that is open now, or null. */
  waitSince: string | null;
  /** The terminal transition was handled (records written). */
  ended: boolean;
  evictHandle: ReturnType<typeof setTimeout> | null;
  lastLoggedTool: string | null;
  assistantIdsLogged: number;
  anomaliesLogged: Set<string>;
  /** A size asked for while the pane was still starting (L2): its launch size, else applied once it started. */
  requestedSize: PaneSize | null;
}

const DEFAULT_MAX_SESSIONS = 20;
const DEFAULT_SCROLLBACK = 2000;
const DEFAULT_TIMEOUT = 600;
const MAX_TIMEOUT = 3600;

/**
 * The caller's `timeout_seconds` as a whole number of seconds in
 * 1..MAX_TIMEOUT: rounded, then clamped. Anything that is not a finite number
 * (absent, null, NaN, Infinity, garbage from a client that ignored the schema)
 * is DEFAULT_TIMEOUT; a numeric string is read as its number.
 *
 * `spawn.json` is a contract with the magus plugin monitor, which drops any
 * record whose `timeoutSeconds` is not an integer in 1..3600 — so a raw 90.5,
 * 0 or -5 made the whole run invisible, and 0 or less also timed the session
 * out at once.
 */
export function normaliseTimeoutSeconds(raw: unknown): number {
  const n = typeof raw === "string" && raw.trim() !== "" ? Number(raw) : raw;
  if (typeof n !== "number" || !Number.isFinite(n)) return DEFAULT_TIMEOUT;
  return Math.min(MAX_TIMEOUT, Math.max(1, Math.round(n)));
}

/**
 * How long a terminal session stays readable before it is dropped from the map.
 * Long enough that an agent which polls, sees `completed`, and then calls
 * `get_output`/`get_diagnostics`/`capture_session` always finds the session; the
 * artifacts on disk outlive it either way.
 */
const TERMINAL_RETENTION_MS = 30 * 60_000;

/** Hard ceiling on retained terminal sessions, whatever the retention window says. */
const MAX_TERMINAL_SESSIONS = 50;

/** Cap on `events.jsonl`. */
const EVENT_LOG_LIMIT = 4 * 1024 * 1024;

/**
 * Cap on `waits.jsonl`. One line is under 200 bytes, so this is about 6 000
 * waits — far beyond any real interactive session. Past it, later waits are
 * not recorded.
 */
const WAIT_LOG_LIMIT = 1024 * 1024;

/** How many event records `get_diagnostics` can hand back, and how much of each. */
const EVENT_RING_SIZE = 200;
const EVENT_PREVIEW_CHARS = 800;

/** Default number of ring events returned when the caller names no limit. */
const DEFAULT_EVENT_LIMIT = 40;

/** Bytes of `upstream-errors.jsonl` read back for diagnostics. */
const UPSTREAM_ERROR_TAIL_BYTES = 64 * 1024;

/**
 * `spawn.json`'s `schema`. Bumped only on a breaking change to `spawn.json`; it
 * versions that file alone, not `waits.jsonl` or a team record's `meta.json`.
 */
const SPAWN_RECORD_SCHEMA = 1;

/** The caller's settings layer, in the session dir (never in work_dir or setupFrom). */
const INHERITED_SETTINGS = "inherited-settings.json";

/** RUNNING activities that are not a tool name (§8 B). */
// "hook": a settled turn held while session hooks run (§7.3); not a tool
const NON_TOOL_ACTIVITY = new Set(["thinking", "background", "finishing", "hook"]);

/** `meta.json` `status` for each terminal state (§20.1): EMPTY is a failure to the monitor. */
const META_STATUS: Record<SlotState, string> = {
  STARTING: "starting",
  RUNNING: "running",
  AWAITING_INPUT: "waiting_for_input",
  AWAITING_PERMISSION: "awaiting_permission",
  COMPLETED: "completed",
  FAILED: "failed",
  EMPTY: "failed",
  CANCELLED: "cancelled",
  TIMEOUT: "timeout",
};

/** A 10.4.0 `meta.json` `status` read back as a `SlotState` (the first-generation reader). */
const STATE_OF_10_4_STATUS: Record<string, SlotState> = {
  completed: "COMPLETED",
  failed: "FAILED",
  cancelled: "CANCELLED",
  timeout: "TIMEOUT",
};

/**
 * The event for a session state (architecture §3.4). Pure; the wire, the
 * wait log's `to` and `get_diagnostics.event` all read it.
 */
export function sessionEventFor(snap: { state: SlotState; activity: string | null }): {
  event: SessionEventType;
  tool: string | null;
} {
  switch (snap.state) {
    case "STARTING":
      return { event: "starting", tool: null };
    case "RUNNING": {
      const a = snap.activity;
      return a && !NON_TOOL_ACTIVITY.has(a)
        ? { event: "tool_executing", tool: a }
        : { event: "running", tool: null };
    }
    case "AWAITING_INPUT":
      return { event: "waiting_for_input", tool: null };
    case "AWAITING_PERMISSION":
      return { event: "awaiting_permission", tool: null };
    case "COMPLETED":
      return { event: "completed", tool: null };
    case "CANCELLED":
      return { event: "cancelled", tool: null };
    case "TIMEOUT":
      return { event: "timeout", tool: null };
    default:
      return { event: "failed", tool: null };
  }
}

/** One `list_sessions` row (§8 B): exactly the SlotRow keys plus the four session keys. */
export function sessionRowOf(
  info: SessionInfo,
  /** the session's upstream-error records (`upstreamRecordsFor`); [] = none read */
  upstreamRecords: readonly string[] = []
): SessionRow {
  const terminal = isTerminalState(info.state);
  return {
    slot: info.sessionId,
    model: info.model,
    provider: info.provider,
    state: info.state,
    reason: info.state === "COMPLETED" || !terminal ? null : info.reason,
    reason_detail: reasonDetail(info, upstreamRecords),
    tokens_in: info.tokensIn,
    tokens_out: info.tokensOut,
    cost_usd: info.costUsd,
    tool_calls: info.toolCalls,
    turns_completed: info.turnsCompleted,
    last_activity_at: info.lastActivityAt,
    idle_seconds: terminal ? null : info.idleSeconds,
    activity: terminal ? null : info.activity,
    pane: info.pane,
    recent: info.recent,
    session_id: info.sessionId,
    started_at: info.startedAt,
    completed_at: info.completedAt,
    elapsed_seconds: info.elapsedSeconds,
  };
}

/**
 * The `meta.json` record (§20.1). Every 10.4.0 key under its 10.4.0 name and meaning —
 * the magus monitor reads `status` (an unknown value reads as `failed`),
 * `terminalReason`, `elapsedSeconds`, `turnsCompleted`, `toolCallCount`, `costUsd` and
 * `exitCode` — plus additive keys. A `SessionInfo` key that would repeat a pinned key
 * (`toolCalls`, `reason`, `panePid`) is written only under the pinned name.
 */
export function toMetaRecord(info: SessionInfo, cwd: string): Record<string, unknown> {
  return {
    sessionId: info.sessionId,
    model: info.model,
    spawnModel: info.spawnModel,
    status: META_STATUS[info.state],
    pid: info.panePid,
    startedAt: info.startedAt,
    completedAt: info.completedAt,
    exitCode: info.exitCode,
    turnsCompleted: info.turnsCompleted,
    tokensUsed: (info.tokensIn ?? 0) + (info.tokensOut ?? 0),
    elapsedSeconds: info.elapsedSeconds,
    idleSeconds: info.idleSeconds,
    costUsd: info.costUsd,
    toolCallCount: info.toolCalls,
    terminalReason: info.reason,
    claudeSessionId: info.claudeSessionId,
    ...(info.parentClaudeSessionId ? { parentClaudeSessionId: info.parentClaudeSessionId } : {}),
    transcriptPath: info.transcriptPath,
    // additive (pane generation)
    state: info.state,
    detail: info.detail,
    tokensIn: info.tokensIn,
    tokensOut: info.tokensOut,
    lastActivityAt: info.lastActivityAt,
    shape: info.shape,
    pane: info.pane,
    provider: info.provider,
    captureSource: info.captureSource,
    turnSource: info.turnSource,
    timeoutSeconds: info.timeoutSeconds,
    cwd,
  };
}

/**
 * Write JSON so a reader never sees half of it: `<path>.tmp`, then rename over
 * `<path>`. Throws on failure; callers that must not throw catch it themselves.
 */
function writeJsonAtomic(path: string, value: unknown): void {
  const tmp = `${path}.tmp`;
  writeFileSync(tmp, JSON.stringify(value, null, 2), "utf-8");
  renameSync(tmp, path);
}

/** An anomaly entry without its `×n` count suffix. */
function anomalyKey(a: string): string {
  const at = a.lastIndexOf(" ×");
  return at > 0 ? a.slice(0, at) : a;
}

// ─── Disk fallback ───────────────────────────────────────────────────────────
//
// Sessions live in a Map, and two things legitimately remove them from it: the
// 30-minute / 50-session retention policy, and the MCP server restarting. The three
// READERS (`getSession`, `getOutput`, `getDiagnostics`) fall back to the session's
// directory; the MUTATORS never do (`liveEntry`). The reader reads both generations of
// `meta.json`: 10.4.0's (`status`, no `state`) and the pane one (`state` beside it).

/**
 * What a session id may contain, given that it is about to become a path segment.
 * No `/`, no `\`, no NUL and no leading dot, which makes `..`, `../../etc/passwd` and an
 * absolute path unrepresentable rather than merely unlikely.
 */
const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;

/** Refuse to parse a `meta.json` larger than this; it is not the file we wrote. */
const META_READ_LIMIT = 1024 * 1024;

/** Bytes of `output.log` read back, before the same scrollback bound the live path applies. */
const OUTPUT_TAIL_BYTES = 256 * 1024;

/** Bytes of `events.jsonl` read back: a bounded TAIL, never the whole file. */
const EVENT_TAIL_BYTES = 512 * 1024;

/** Bytes of `screen.txt` read back. */
const SCREEN_READ_BYTES = 64 * 1024;

/**
 * The detail of a session whose directory exists but whose `meta.json` does not, or
 * will not parse: the process died before reaching a verdict (SIGKILL, a panic, a full
 * disk). Distinctive enough to grep.
 */
const NO_TERMINAL_RECORD = "claudish_no_terminal_record";

/** How every annotation of OUR OWN in `output.log` begins (kept out of `outputBytes`). */
const CLAUDISH_NOTE_PREFIX = "[claudish] ";

/** A session reconstructed from `<sessionsDir>/<id>/`. There is no process behind it. */
interface DiskRecord {
  info: SessionInfo;
  sessionDir: string;
  /** True when `meta.json` was missing or unusable and `info` was reconstructed. */
  partial: boolean;
}

/**
 * The last `maxBytes` of a file, as text, plus whether the read began mid-file. A
 * positioned tail read, never a whole-file read. Null for an absent file. Never throws.
 */
function readTailText(path: string, maxBytes: number): { text: string; truncated: boolean } | null {
  let fd: number | null = null;
  try {
    const size = statSync(path).size;
    if (size === 0) return { text: "", truncated: false };
    const start = Math.max(0, size - maxBytes);
    const length = size - start;
    const buf = Buffer.alloc(length);
    fd = openSync(path, "r");
    readSync(fd, buf, 0, length, start);
    return { text: buf.toString("utf-8"), truncated: start > 0 };
  } catch {
    return null;
  } finally {
    if (fd !== null) {
      try {
        closeSync(fd);
      } catch {
        /* already gone */
      }
    }
  }
}

/** The last `maxBytes` of a JSONL file, split into whole lines; a first partial line is dropped. */
function readTailLines(path: string, maxBytes: number): string[] {
  const tail = readTailText(path, maxBytes);
  if (!tail) return [];
  const lines = tail.text.split("\n");
  if (tail.truncated) lines.shift();
  return lines.filter((line) => line.trim().length > 0);
}

/** Byte size of a file, or 0 when it is absent or unreadable. */
function fileSize(path: string): number {
  try {
    return statSync(path).size;
  } catch {
    return 0;
  }
}

/** Parse a small JSON object off disk, or null for every failure mode of the file. */
function readJsonObject(path: string, maxBytes: number): Record<string, unknown> | null {
  try {
    if (fileSize(path) > maxBytes) return null;
    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
    return parsed as Record<string, unknown>;
  } catch {
    return null;
  }
}

/** A field of a `meta.json` that must be a string, or null. Never a coercion. */
const metaString = (v: unknown): string | null =>
  typeof v === "string" && v.length > 0 ? v : null;

/** `{ parentClaudeSessionId }` when there is one, else nothing — never the key with no value. */
const optionalParent = (id: string | null | undefined): { parentClaudeSessionId?: string } =>
  id ? { parentClaudeSessionId: id } : {};

/** A field of a `meta.json` that must be a finite number, or null. */
const metaNumber = (v: unknown): number | null =>
  typeof v === "number" && Number.isFinite(v) ? v : null;

const metaReason = (v: unknown): FailureReason | null =>
  typeof v === "string" && (FAILURE_REASONS as readonly string[]).includes(v)
    ? (v as FailureReason)
    : null;

/** The record's `type`, or null — the label of one `events.jsonl` line. */
function labelForLine(line: string): string | null {
  try {
    const v = JSON.parse(line) as { type?: unknown; subtype?: unknown };
    if (typeof v?.type !== "string") return null;
    return typeof v.subtype === "string" ? `${v.type}:${v.subtype}` : v.type;
  } catch {
    return null;
  }
}

/** A tail window with its first, partial line removed (unless it is one enormous line). */
function dropLeadingFragment(tail: { text: string; truncated: boolean }): string {
  if (!tail.truncated) return tail.text;
  const firstBreak = tail.text.indexOf("\n");
  return firstBreak === -1 ? tail.text : tail.text.slice(firstBreak + 1);
}

/** Tokens, cost and tool calls from a recovered session's `tokens.json` (the proxy's own file). */
function diskAccounting(sessionDir: string): {
  tokensIn: number | null;
  tokensOut: number | null;
  costUsd: number | null;
  toolCalls: number;
} {
  const stats = readTokenStatsAt(join(sessionDir, "tokens.json"));
  return {
    tokensIn: stats?.billed_input_tokens ?? null,
    tokensOut: stats?.output_tokens ?? null,
    costUsd: typeof stats?.total_cost === "number" ? stats.total_cost : null,
    toolCalls: Array.isArray(stats?.tool_calls)
      ? stats.tool_calls.reduce((sum, t) => sum + (typeof t.count === "number" ? t.count : 0), 0)
      : 0,
  };
}

/** Whole seconds between an ISO start and an epoch-ms end, never negative and never NaN. */
function elapsedSecondsBetween(startedAt: string, endedAtMs: number): number {
  const seconds = Math.round((endedAtMs - Date.parse(startedAt)) / 1000);
  return Number.isFinite(seconds) ? Math.max(0, seconds) : 0;
}

/** `outputBytes` for a recovered session: prose only, without our own `[claudish] …` notes. */
function diskProseBytes(
  tail: { text: string; truncated: boolean } | null,
  fileBytes: number
): number {
  if (!tail || tail.truncated) return fileBytes;
  const prose = tail.text
    .split("\n")
    .filter((line) => !line.startsWith(CLAUDISH_NOTE_PREFIX))
    .join("\n");
  return Buffer.byteLength(prose, "utf-8");
}

/** The screen of a session whose pane never spawned (§8 D, amended r2). */
function blankFinalCapture(): CaptureResult {
  return {
    seq: 0,
    cols: DEFAULT_PANE_COLS,
    rows: DEFAULT_PANE_ROWS,
    cursor: { x: 0, y: 0 },
    lines: Array.from({ length: DEFAULT_PANE_ROWS }, () => ""),
    final: true,
  };
}

function unknownSession(sessionId: string): ContractErrorException {
  return new ContractErrorException(
    "unknown_session",
    `no session ${JSON.stringify(sessionId)} is held by this server`
  );
}

export class SessionManager {
  private sessions = new Map<string, SessionEntry>();
  private maxSessions: number;
  private scrollbackCapacity: number;
  private sessionsDir: string;
  private terminalRetentionMs: number;
  private readonly parentEnv: Record<string, string | undefined>;
  private readonly paneTimings: SessionManagerOptions["paneTimings"];
  /** createSession calls past their checks whose entry is not in the map yet. */
  private starting = 0;
  /** Pane starts in flight; `shutdownAll` waits for them so no pane starts unsettled. */
  private readonly pendingStarts = new Set<Promise<void>>();
  private readonly _hostPid: number;
  private readonly _launcherPid: number | undefined;
  /** Team run record id → its `startedAt`, until `finishTeamRun` writes its end. */
  private readonly teamRunStarts = new Map<string, string>();
  /** Team run records whose end is on disk. The first `finishTeamRun` write to succeed wins. */
  private readonly settledTeamRuns = new Set<string>();
  /** The hook engine pane bindings are built from; loaded before the first pane spawn. */
  private hookEnginePromise: Promise<HookEngine | null> | null = null;
  private readonly hookEngineSource: () => Promise<HookEngine | null>;
  private readonly bindingOverride: SessionManagerOptions["hookBinding"];
  private readonly magmuxBinary: string | undefined;

  constructor(options?: SessionManagerOptions) {
    // Computed once: the Claude Code process that launched this MCP server
    // does not change for the life of the process. See parent-session.ts.
    const host =
      options?.hostPid !== undefined
        ? { hostPid: options.hostPid }
        : hostPidFrom(process.env, process.ppid);
    this._hostPid = host.hostPid;
    this._launcherPid = host.launcherPid;
    this.maxSessions = options?.maxSessions ?? DEFAULT_MAX_SESSIONS;
    this.scrollbackCapacity = options?.scrollbackCapacity ?? DEFAULT_SCROLLBACK;
    this.terminalRetentionMs = options?.terminalRetentionMs ?? TERMINAL_RETENTION_MS;
    // `$HOME` before `os.homedir()`, by the rule the plugin monitor shares —
    // see home-dir.ts. Diverging here makes every run invisible to it.
    this.sessionsDir = options?.sessionsDir ?? sessionsDirFrom(process.env);
    this.parentEnv = options?.parentEnv ?? process.env;
    this.paneTimings = options?.paneTimings;
    this.hookEngineSource = options?.hookEngine ?? (() => loadHooksOnce());
    this.bindingOverride = options?.hookBinding;
    this.magmuxBinary = options?.magmuxBinary;
  }

  /** The process's hook engine (§2.2), awaited before the first pane spawn. Never rejects. */
  private hookEngine(): Promise<HookEngine | null> {
    if (!this.hookEnginePromise) this.hookEnginePromise = this.hookEngineSource().catch(() => null);
    return this.hookEnginePromise;
  }

  /** The Claude Code process that launched this MCP server (`spawn.json` `hostPid`). */
  get hostPid(): number {
    return this._hostPid;
  }

  /** The npm `node` launcher between Claude Code and this process, when there is one. */
  get launcherPid(): number | undefined {
    return this._launcherPid;
  }

  /**
   * Start the record of one `team(mode:"run")`: create
   * `<sessionsDir>/team-<8 hex>/` and write its `spawn.json` (`kind: "team"`).
   * Returns the record id.
   *
   * Called BEFORE `startModels`, so a run never starts unrecorded, and it
   * throws — failing the tool call before any child exists — when the record
   * cannot be written. The directory holds only `spawn.json` and, once the run
   * ends, `meta.json` (`finishTeamRun`). It is invisible to `list_sessions`
   * (in-memory only), and `loadDiskRecord` refuses its id, so no session tool
   * mistakes it for a session.
   */
  recordTeamRun(opts: { teamPath: string; slots: number; parentClaudeSessionId?: string }): string {
    mkdirSync(this.sessionsDir, { recursive: true });
    let id = "";
    let dir = "";
    // Non-recursive mkdir fails on an existing directory, so a collision of
    // two random 8-hex ids can never adopt someone else's record.
    for (let attempt = 0; ; attempt++) {
      id = `team-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
      dir = join(this.sessionsDir, id);
      try {
        mkdirSync(dir);
        break;
      } catch (err) {
        if ((err as NodeJS.ErrnoException)?.code !== "EEXIST" || attempt >= 4) throw err;
      }
    }
    const startedAt = new Date().toISOString();
    this.writeSpawnRecord(dir, {
      kind: "team",
      sessionId: id,
      parentClaudeSessionId: opts.parentClaudeSessionId,
      startedAt,
      teamPath: resolve(opts.teamPath),
      slots: opts.slots,
    });
    this.teamRunStarts.set(id, startedAt);
    return id;
  }

  /**
   * End a team run's record: write `<record dir>/meta.json` atomically, at most
   * once.
   *
   * The first call whose write SUCCEEDS wins; a later call writes nothing and
   * reports one stderr line. A failed write does not count, so a retry can
   * still end the record. It NEVER throws: a write failure is reported on
   * stderr, so a caller's `catch` always rethrows its ORIGINAL error rather
   * than a disk error that masked it. A lost write leaves a record with no
   * end, which an observer reports from the writer's liveness — never a false
   * verdict.
   */
  finishTeamRun(record: string, outcome: TeamRunOutcome): void {
    if (this.settledTeamRuns.has(record)) {
      process.stderr.write(`[claudish] team run record ${record} already ended; ignoring\n`);
      return;
    }
    try {
      const dir = this.diskSessionDir(record);
      if (dir === null) throw new Error("not a record id");
      const completedAt = new Date().toISOString();
      const startedAt =
        this.teamRunStarts.get(record) ??
        metaString(readJsonObject(join(dir, "spawn.json"), META_READ_LIMIT)?.startedAt) ??
        completedAt;
      const elapsedMs = Date.parse(completedAt) - Date.parse(startedAt);
      writeJsonAtomic(join(dir, "meta.json"), {
        kind: "team",
        status: outcome.status,
        startedAt,
        completedAt,
        elapsedSeconds: Number.isFinite(elapsedMs) ? Math.max(0, Math.round(elapsedMs / 1000)) : 0,
        slots: outcome.slots,
        ok: outcome.ok,
        failed: outcome.failed,
        cancelled: outcome.cancelled,
        ...(outcome.reason ? { reason: outcome.reason } : {}),
      });
      // Only now: the end is on disk. `startedAt` stays for a retry until then.
      this.settledTeamRuns.add(record);
      this.teamRunStarts.delete(record);
    } catch (err) {
      process.stderr.write(
        `[claudish] could not write the end of team run record ${record}: ` +
          `${err instanceof Error ? err.message : String(err)}\n`
      );
    }
  }

  /**
   * Write `<dir>/spawn.json`, the start-time record, atomically (tmp + rename),
   * one key per line.
   *
   * Deliberately NOT wrapped in a `try`: a run that cannot be recorded must not
   * run unrecorded, so a failure here fails the tool call before any pane
   * exists. `hostPid`, `launcherPid` (only when the launcher branch produced
   * `hostPid`) and `mcpPid` — this process, the one that writes `meta.json` —
   * are filled in here; the caller supplies the rest.
   */
  private writeSpawnRecord(
    dir: string,
    record: {
      kind: "session" | "team";
      sessionId: string;
      parentClaudeSessionId?: string;
      startedAt: string;
      model?: string;
      timeoutSeconds?: number;
      claudeSessionId?: string;
      teamPath?: string;
      slots?: number;
      setupFrom?: string;
    }
  ): void {
    const { kind, sessionId, parentClaudeSessionId, startedAt, ...rest } = record;
    const body = {
      schema: SPAWN_RECORD_SCHEMA,
      kind,
      sessionId,
      ...(parentClaudeSessionId ? { parentClaudeSessionId } : {}),
      hostPid: this._hostPid,
      ...(this._launcherPid !== undefined ? { launcherPid: this._launcherPid } : {}),
      mcpPid: process.pid,
      startedAt,
      ...rest,
    };
    writeJsonAtomic(join(dir, "spawn.json"), body);
  }

  /**
   * Create a session and start its pane. Resolves with the session id once the pane
   * exists (no boot wait): the session is STARTING then.
   *
   * Order (§4.2, §20.1): the checks; the magmux check; the pane reservation (a refused
   * session leaves no record); `prompt.md`; `spawn.json` (a failure releases the
   * reservation and fails the call); then the pane. A pane that fails to start leaves a
   * FAILED `pane_lost` session with a `meta.json`, and the call throws.
   */
  async createSession(opts: SessionCreateOptions): Promise<string> {
    if (this.activeSessions + this.starting >= this.maxSessions) {
      throw new Error(`Max sessions (${this.maxSessions}) reached`);
    }
    // A caller-supplied id must not be able to adopt or overwrite a live session.
    if (opts.sessionId !== undefined && this.sessions.has(opts.sessionId)) {
      throw new Error(`Session id already in use: ${opts.sessionId}`);
    }
    const callerFlags = opts.claudishFlags ?? [];
    const flagCheck = checkChildFlags(callerFlags);
    if (!flagCheck.ok) throw new Error(`invalid_args: ${flagCheck.message}`);
    // Built before any pane, so a malformed settings file fails the call as invalid_args.
    const inherited = opts.setupFrom
      ? buildInheritedSettingsLayer(opts.setupFrom, callerFlags)
      : { layer: null, restFlags: callerFlags };
    let flags = callerFlags;
    const readAvailable = !flagsRemoveRead(flags);
    if (opts.prompt) {
      const refusal = deliveryRefusal(opts.prompt, readAvailable);
      if (refusal) throw new Error(`invalid_args: ${refusal}`);
    }
    const parentEnv = opts.parentEnv ?? this.parentEnv;

    // Counted from here, so concurrent creates cannot overshoot maxSessions while they
    // await the magmux check; from `sessions.set` on, the entry itself counts.
    this.starting++;
    let counted = true;
    const uncount = () => {
      if (counted) this.starting--;
      counted = false;
    };
    try {
      await assertMagmuxAvailable(this.magmuxBinary);
      reservePanes(1, sockRootFor(parentEnv));
      let entry: SessionEntry;
      try {
        entry = this.recordSession(opts, inherited.layer);
      } catch (err) {
        releasePaneReservations(1);
        throw err;
      }
      // The caller's `--settings` are inside the file: exactly one `--settings` reaches
      // the child, since Claude Code keeps only the last one.
      if (inherited.layer) {
        flags = [...inherited.restFlags, "--settings", join(entry.sessionDir, INHERITED_SETTINGS)];
      }
      this.sessions.set(entry.info.sessionId, entry);
      uncount();
      const started = this.startPane(entry, opts, { flags, readAvailable, parentEnv });
      const tracked = started.catch(() => undefined);
      this.pendingStarts.add(tracked);
      try {
        await started;
      } finally {
        this.pendingStarts.delete(tracked);
      }
      return entry.info.sessionId;
    } finally {
      uncount();
    }
  }

  /**
   * `prompt.md`, `spawn.json`, `inherited-settings.json` (when there is a layer) and the
   * in-memory entry (STARTING). Throws before any pane.
   */
  private recordSession(
    opts: SessionCreateOptions,
    inheritedLayer: Record<string, unknown> | null
  ): SessionEntry {
    const sessionId = opts.sessionId ?? randomUUID().slice(0, 8);
    // Minted here: it is the child's transcript basename, known BEFORE the pane starts.
    const claudeSessionId = randomUUID();
    // Normalised once, here, so `spawn.json`, `SessionInfo` and the pane's timer agree
    // on one value the plugin monitor accepts (an integer in 1..MAX_TIMEOUT).
    const timeout = normaliseTimeoutSeconds(opts.timeoutSeconds);
    const startedAt = new Date().toISOString();
    const sessionDir = opts.sessionDir ?? join(this.sessionsDir, sessionId);
    mkdirSync(sessionDir, { recursive: true });
    if (opts.prompt) writeFileSync(join(sessionDir, "prompt.md"), opts.prompt, "utf-8");

    // The start-time record, BEFORE the pane and before every runtime file, so a
    // session never runs unrecorded. Throws rather than continue.
    this.writeSpawnRecord(sessionDir, {
      kind: "session",
      sessionId,
      parentClaudeSessionId: opts.parentClaudeSessionId,
      startedAt,
      model: opts.model,
      timeoutSeconds: timeout,
      claudeSessionId,
      ...(opts.setupFrom ? { setupFrom: opts.setupFrom } : {}),
    });
    // 0600: the caller's settings.local.json can carry `env` secrets.
    if (inheritedLayer) {
      writeFileSync(
        join(sessionDir, INHERITED_SETTINGS),
        `${JSON.stringify(inheritedLayer, null, 2)}\n`,
        { encoding: "utf-8", mode: 0o600 }
      );
    }

    const cwd = opts.cwd ?? process.cwd();
    const parentEnv = opts.parentEnv ?? this.parentEnv;
    const spawnModel = opts.spawnModel ?? null;
    const tokenFile = opts.tokenFile ?? join(sessionDir, "tokens.json");
    return {
      info: {
        sessionId,
        model: opts.model,
        spawnModel,
        provider: resolveProvider({ model: opts.model, spawnModel, tokenFile: null }),
        state: "STARTING",
        shape: opts.prompt ? "one-shot" : "interactive",
        pane: null,
        panePid: null,
        startedAt,
        completedAt: null,
        exitCode: null,
        turnsCompleted: 0,
        tokensIn: null,
        tokensOut: null,
        costUsd: null,
        toolCalls: 0,
        lastActivityAt: null,
        elapsedSeconds: 0,
        idleSeconds: null,
        activity: null,
        recent: null,
        reason: null,
        detail: null,
        pendingInputs: opts.prompt ? 1 : 0,
        claudeSessionId,
        transcriptPath: transcriptPathFor(cwd, claudeSessionId, projectsDir(parentEnv)),
        // Present only when there is one, so `meta.json` carries the key exactly when
        // `spawn.json` does, with the same value.
        ...optionalParent(opts.parentClaudeSessionId),
        captureSource: null,
        turnSource: "transcript",
        timeoutSeconds: timeout,
      },
      session: null,
      scrollback: new ScrollbackBuffer(this.scrollbackCapacity),
      outputLogStream: createWriteStream(join(sessionDir, "output.log")),
      sessionDir,
      cwd,
      tokenFile,
      eventLogPath: join(sessionDir, "events.jsonl"),
      eventLogBytes: 0,
      upstreamErrorLogPath: join(sessionDir, "upstream-errors.jsonl"),
      eventRing: [],
      proseBytes: 0,
      answeredTurns: new Map(),
      inboxPath: null,
      waitLogPath: join(sessionDir, "waits.jsonl"),
      waitLogBytes: 0,
      waitSince: null,
      ended: false,
      evictHandle: null,
      lastLoggedTool: null,
      assistantIdsLogged: 0,
      anomaliesLogged: new Set(),
      requestedSize: null,
    };
  }

  /** Start the entry's pane. A throw ends the record FAILED `pane_lost` and is rethrown. */
  private async startPane(
    entry: SessionEntry,
    opts: SessionCreateOptions,
    p: { flags: string[]; readAvailable: boolean; parentEnv: Record<string, string | undefined> }
  ): Promise<void> {
    const info = entry.info;
    const engine = await this.hookEngine();
    entry.inboxPath = createHookInbox(entry.sessionDir);
    const binding = this.bindingFor(entry, engine);
    // L2: a size asked for before this point is the pane's launch size
    const launch = entry.requestedSize;
    const paneOpts: PaneSessionOptions = {
      kind: "s",
      label: info.sessionId,
      callerFlags: p.flags,
      spawnModel: info.spawnModel ?? info.model,
      cwd: entry.cwd,
      sessionUuid: info.claudeSessionId,
      transcriptPath: info.transcriptPath,
      slotEnv: {
        // The child's token tracker writes to a path WE own: tokens, cost and tool
        // counts come from the proxy, never from anything the child prints.
        [ENV.CLAUDISH_TOKEN_FILE]: entry.tokenFile,
        // Per session, unconditionally: the records carry no session id, so a shared
        // path would interleave concurrent sessions into one unattributable file.
        [UPSTREAM_ERROR_LOG_ENV]: entry.upstreamErrorLogPath,
        // Every child, unconditionally (§2.3 step 1): a child may load hooks this
        // process did not, so it must never lack a sink, and ctx.session must be set.
        ...(entry.inboxPath ? { [HOOK_INBOX_ENV]: entry.inboxPath } : {}),
        [HOOK_SESSION_ENV]: JSON.stringify({ kind: "channel", id: info.sessionId, role: null }),
      },
      shape: info.shape,
      ...(opts.prompt ? { initialPrompt: opts.prompt } : {}),
      ...(launch ? { initialSize: launch } : {}),
      readAvailable: p.readAvailable,
      decide: (turn) => this.decide(entry, turn),
      onBlocked: (b) => this.onBlocked(entry, b),
      timeoutMs: info.timeoutSeconds * 1000,
      onChange: (snap) => this.onPaneChange(entry, snap),
      onTransition: (t) => this.onPaneTransition(entry, t),
      parentEnv: p.parentEnv,
      ...(this.paneTimings ? { timings: this.paneTimings } : {}),
      ...(this.magmuxBinary ? { magmuxBinary: this.magmuxBinary } : {}),
      ...(binding
        ? {
            hooks: binding,
            onTurnRecorded: (turn: SettledTurn) =>
              this.recordAnswer(entry, turn.index, turn.answer),
          }
        : {}),
    };
    try {
      entry.session = await startPaneSession(paneOpts);
    } catch (err) {
      this.removeInbox(entry);
      this.failNeverSpawned(entry, err);
      throw err;
    }
    const session = entry.session;
    // a size asked for while the pane started (after its environment was built): apply it
    // now; the pane's own worker answers any later resize
    const asked = entry.requestedSize;
    entry.requestedSize = null;
    if (asked && (asked.cols !== launch?.cols || asked.rows !== launch?.rows))
      session.resize(asked.cols, asked.rows).catch(() => undefined);
    // At reap: an owner without a binding checks the inbox once, then the file goes.
    void session.reaped().then(() => {
      if (!binding && entry.inboxPath)
        reportOwnerWithoutHooks(entry.inboxPath, engine, {
          model: info.model,
          sessionId: info.claudeSessionId,
        });
      // with a binding, what no settle took is journaled before the file goes
      binding?.sweepInbox?.();
      this.removeInbox(entry);
    });
    if (!entry.ended) this.applySnapshot(entry, session.snapshot());
  }

  /** The pane's hook binding: a test's, or the real one when this engine has session hooks. */
  private bindingFor(entry: SessionEntry, engine: HookEngine | null): SessionHookBinding | null {
    const info = entry.info;
    const session = {
      kind: "channel" as const,
      role: null,
      id: info.sessionId,
      claudeSessionId: info.claudeSessionId,
      model: info.model,
      cwd: entry.cwd,
      shape: info.shape,
      injection: "available" as const,
    };
    if (this.bindingOverride)
      return this.bindingOverride({ session, inboxPath: entry.inboxPath, engine });
    if (!engine || !sessionHooksNeedBinding(engine)) return null;
    return createSessionHookBinding(engine, session, entry.inboxPath);
  }

  private removeInbox(entry: SessionEntry): void {
    if (!entry.inboxPath) return;
    try {
      rmSync(entry.inboxPath, { force: true });
    } catch {
      // the session dir keeps it; nothing reads it after the reap
    }
  }

  /** A session whose pane never started: FAILED `pane_lost`, its records ended. */
  private failNeverSpawned(entry: SessionEntry, err: unknown): void {
    const msg = err instanceof Error ? err.message : String(err);
    const at = new Date().toISOString();
    const info = entry.info;
    info.state = "FAILED";
    info.reason = "pane_lost";
    info.detail = `the pane never started: ${msg}`;
    info.completedAt = at;
    info.pendingInputs = 0;
    info.elapsedSeconds = elapsedSecondsBetween(info.startedAt, Date.parse(at));
    this.appendEvent(entry, { type: "state", from: "STARTING", to: "FAILED", at });
    this.endRecords(entry, null);
  }

  // ─── Pane policy (D8) ──────────────────────────────────────────────────

  /** The verdict of a settled turn: one-shot → classified; interactive → continue (D20). */
  private decide(entry: SessionEntry, turn: SettledTurn): FinalVerdict | "continue" {
    this.appendAnswer(entry, turn.index, turn.answer);
    // The pane's shape at the settle, not entry.info's copy: a send_input whose own step
    // settles the turn has converted the session before sendInput could update the copy.
    if (turn.shape === "one-shot") {
      // A hook-extended turn chain is classified as one answer, with the CHAIN HEAD's
      // prompt-read result (§4.7 rule 9). Without hooks both equal the turn's own.
      const v = classifyRunOutput({
        answer: chainAnswerOf(turn),
        apiError: turn.apiError,
        stopReason: turn.stopReason,
        promptRead: turn.chainDelivery,
        minOutputBytes: 0,
      });
      if (v) return { state: v.state, reason: v.reason, detail: v.detail };
      return turn.stopReason === "max_tokens"
        ? { state: "COMPLETED", detail: TRUNCATION_NOTE }
        : { state: "COMPLETED" };
    }
    if (turn.apiError) {
      const v = classifyRunOutput({ answer: turn.answer, apiError: turn.apiError });
      return { state: "FAILED", reason: "api_error", detail: v?.detail ?? "API error" };
    }
    // An interactive turn whose task file was not fully read continues; the anomaly is
    // in the session's event log (r2, X-M4). An unread HOOK turn is the pane's
    // hook_injection_not_read, never the caller-facing prompt_not_read (L-2).
    if (!turn.hookCaused && turn.delivery.complete === false) {
      this.appendEvent(entry, {
        type: "anomaly",
        key: "prompt_not_read",
        turn: turn.index,
        linesRead: turn.delivery.linesRead,
        linesTotal: turn.delivery.linesTotal,
        at: new Date().toISOString(),
      });
    }
    return "continue";
  }

  /** A question or a permission dialog waits for `send_input` (the caller can answer). */
  private onBlocked(_entry: SessionEntry, _b: PaneBlock): "wait" {
    return "wait";
  }

  // ─── Pane callbacks ────────────────────────────────────────────────────

  /** `onTransition`: every wire-state change, synchronously. */
  private onPaneTransition(
    entry: SessionEntry,
    t: { from: SlotState; to: SlotState; at: string; snap: PaneSnapshot }
  ): void {
    if (entry.ended) return;
    const { snap } = t;
    this.applySnapshot(entry, snap);
    this.recordWaitTransition(entry, t.from, t.to, t.at, snap);
    this.appendEvent(entry, { type: "state", from: t.from, to: t.to, at: t.at });
    this.logPaneFacts(entry, snap);
    if (isTerminalState(t.to)) this.onTerminal(entry, snap);
  }

  /** `onChange` (coalesced): activity and accounting changes within a state. */
  private onPaneChange(entry: SessionEntry, snap: PaneSnapshot): void {
    if (entry.ended) return;
    this.applySnapshot(entry, snap);
    this.logPaneFacts(entry, snap);
  }

  /** The terminal transition: answer, records and eviction, before the reap starts. */
  private onTerminal(entry: SessionEntry, snap: PaneSnapshot): void {
    const session = entry.session;
    // A turn that ended without a settle (cancel, timeout, child exit) still shows the
    // answer it had produced.
    const index = snap.turnsCompleted + 1;
    if (session && !entry.answeredTurns.has(index)) {
      const partial = session.turnAnswer(index);
      if (partial) this.appendAnswer(entry, index, partial);
    }
    if (snap.state !== "COMPLETED") {
      const why = snap.reason ?? snap.state.toLowerCase();
      this.recordNote(
        entry,
        `\n[claudish] ${snap.state} ${why}${snap.detail ? `: ${snap.detail}` : ""}\n`
      );
    }
    const screen = session ? (session.capture() as CaptureResult).lines : null;
    this.endRecords(entry, screen);
  }

  /** Close `output.log`, write `screen.txt` and `meta.json`, schedule eviction. Once. */
  private endRecords(entry: SessionEntry, screenLines: string[] | null): void {
    if (entry.ended) return;
    entry.ended = true;
    entry.outputLogStream?.end();
    entry.outputLogStream = null;
    if (screenLines) {
      try {
        const text = screenLines.join("\n").replace(/\s+$/, "");
        writeFileSync(join(entry.sessionDir, "screen.txt"), `${redactSecrets(text)}\n`, "utf-8");
      } catch {
        /* diagnostics are never load-bearing */
      }
    }
    // A wait can only be open here when the session ended in a step that also left the
    // waiting state; recordWaitTransition closed it. Belt and braces for the never-
    // spawned path, which has no transition.
    if (entry.waitSince !== null) {
      this.appendWait(entry, {
        wait: "closed",
        since: entry.waitSince,
        at: entry.info.completedAt ?? new Date().toISOString(),
        to: sessionEventFor(entry.info).event,
      });
      entry.waitSince = null;
    }
    try {
      // atomic: the external monitor polls this file while we are live
      writeJsonAtomic(join(entry.sessionDir, "meta.json"), toMetaRecord(entry.info, entry.cwd));
    } catch (err) {
      process.stderr.write(
        `[claudish] session ${entry.info.sessionId}: could not write meta.json: ` +
          `${err instanceof Error ? err.message : String(err)}\n`
      );
    }
    this.scheduleEviction(entry);
  }

  /** Copy a pane snapshot (and the proxy's token file) into the session's info. */
  private applySnapshot(entry: SessionEntry, snap: PaneSnapshot): void {
    const info = entry.info;
    const acct: Accounting = mergeAccounting(snap, readTokenFileCached(entry.tokenFile), {
      model: info.model,
      spawnModel: info.spawnModel,
    });
    info.state = snap.state;
    info.shape = snap.shape;
    info.pane = snap.paneId || null;
    info.panePid = snap.panePid;
    info.completedAt = snap.endedAt;
    info.exitCode = snap.exitCode;
    info.turnsCompleted = snap.turnsCompleted;
    info.tokensIn = acct.tokensIn;
    info.tokensOut = acct.tokensOut;
    info.costUsd = acct.costUsd;
    info.toolCalls = acct.toolCalls;
    info.provider = acct.provider ?? info.provider;
    info.lastActivityAt = snap.lastActivityAt;
    info.idleSeconds = snap.idleSeconds;
    info.activity = snap.activity;
    info.recent = snap.recent;
    info.reason = snap.reason;
    info.detail = snap.detail;
    info.pendingInputs = snap.pendingInputs;
    info.captureSource = snap.captureSource;
    info.turnSource = snap.turnSource;
    info.elapsedSeconds = elapsedSecondsBetween(
      info.startedAt,
      snap.endedAt ? Date.parse(snap.endedAt) : Date.now()
    );
  }

  /** `events.jsonl`: new assistant message ids, tool changes, new anomalies. */
  private logPaneFacts(entry: SessionEntry, snap: PaneSnapshot): void {
    const at = new Date().toISOString();
    const ids = entry.session?.assistantMessageIds() ?? [];
    for (; entry.assistantIdsLogged < ids.length; entry.assistantIdsLogged++) {
      this.appendEvent(entry, {
        type: "assistant",
        message: { id: ids[entry.assistantIdsLogged] },
        at,
      });
    }
    const { tool } = sessionEventFor(snap);
    if (tool && tool !== entry.lastLoggedTool)
      this.appendEvent(entry, { type: "tool", name: tool, at });
    entry.lastLoggedTool = tool;
    for (const a of snap.anomalies) {
      const key = anomalyKey(a);
      if (entry.anomaliesLogged.has(key)) continue;
      entry.anomaliesLogged.add(key);
      this.appendEvent(entry, { type: "anomaly", key, at });
    }
  }

  // ─── Public verbs ──────────────────────────────────────────────────────

  /**
   * Send a turn (D17): accepted in every non-terminal state and queued until the session
   * is idle; during a question or a permission dialog the dialog is declined with Esc and
   * the text becomes the next prompt. Any accepted send converts a one-shot session to
   * interactive. A disk-recovered or unknown session answers `unknown_session`.
   */
  sendInput(sessionId: string, text: string): SendInputResult {
    const entry = this.liveEntry(sessionId);
    if (!entry) return { success: false, reason: "unknown_session", state: null };
    if (!entry.session) return { success: false, reason: "terminal", state: entry.info.state };
    const r = entry.session.send(text);
    if (!r.ok) return { success: false, reason: r.reason, state: entry.session.snapshot().state };
    entry.info.shape = "interactive";
    this.applySnapshot(entry, entry.session.snapshot());
    return { success: true, queued: r.queued };
  }

  /** Answer prose. Falls back to `<sessionsDir>/<id>/output.log` for a session not in memory. */
  getOutput(sessionId: string, tailLines?: number): SessionOutput {
    const entry = this.sessions.get(sessionId);
    if (!entry) return this.diskOutput(this.requireDiskRecord(sessionId), tailLines);
    this.refresh(entry);
    const info = entry.info;
    return {
      sessionId,
      state: info.state,
      output: entry.scrollback.getLines(tailLines).join("\n"),
      totalLines: entry.scrollback.totalLines,
      turnsCompleted: info.turnsCompleted,
      tokensIn: info.tokensIn,
      tokensOut: info.tokensOut,
      elapsedSeconds: info.elapsedSeconds,
      idleSeconds: isTerminalState(info.state) ? null : info.idleSeconds,
    };
  }

  /**
   * Everything a post-mortem needs, from the API rather than the filesystem. Falls back
   * to the session directory for a session not in memory — the restart case is the one
   * this exists for.
   */
  getDiagnostics(sessionId: string, eventLimit = DEFAULT_EVENT_LIMIT): SessionDiagnostics {
    const limit = Math.max(0, Math.min(Math.trunc(eventLimit) || 0, EVENT_RING_SIZE));
    const entry = this.sessions.get(sessionId);
    if (!entry) return this.diskDiagnostics(this.requireDiskRecord(sessionId), limit);
    this.refresh(entry);
    const info = entry.info;
    return {
      sessionId,
      state: info.state,
      event: sessionEventFor(info).event,
      reason: isTerminalState(info.state) && info.state !== "COMPLETED" ? info.reason : null,
      detail: info.detail,
      // The resolved chain, both halves: what the caller asked for, and the pinned
      // `provider@model` the child was actually spawned with.
      model: info.model,
      spawnModel: info.spawnModel,
      provider: info.provider,
      shape: info.shape,
      exitCode: info.exitCode,
      // Silence, reported not judged.
      idleSeconds: isTerminalState(info.state) ? null : info.idleSeconds,
      elapsedSeconds: info.elapsedSeconds,
      timeoutSeconds: info.timeoutSeconds,
      outputBytes: entry.proseBytes,
      turnsCompleted: info.turnsCompleted,
      tokensIn: info.tokensIn,
      tokensOut: info.tokensOut,
      costUsd: info.costUsd,
      toolCalls: info.toolCalls,
      pendingInputs: info.pendingInputs,
      pendingHookInputs:
        entry.session && !entry.ended ? entry.session.snapshot().pendingHookInputs : 0,
      pane: info.pane,
      captureSource: info.captureSource,
      turnSource: info.turnSource,
      ...this.paneFacts(entry),
      recentEvents: limit === 0 ? [] : entry.eventRing.slice(-limit),
      eventsTotal: entry.eventRing.length,
      upstreamErrors: readTailLines(entry.upstreamErrorLogPath, UPSTREAM_ERROR_TAIL_BYTES),
      claudeSessionId: info.claudeSessionId,
      transcriptPath: info.transcriptPath,
      sessionDir: entry.sessionDir,
      eventLogPath: entry.eventLogPath,
      upstreamErrorLogPath: entry.upstreamErrorLogPath,
    };
  }

  /** The `get_diagnostics` fields only a pane can answer; their "no pane" values otherwise. */
  private paneFacts(
    entry: SessionEntry
  ): Pick<
    SessionDiagnostics,
    | "phase"
    | "connected"
    | "screenTail"
    | "sockPath"
    | "magmuxStderr"
    | "registry"
    | "preambleBytes"
    | "readCoverage"
    | "gate"
    | "lastSend"
    | "claudeCodeVersion"
    | "anomalies"
  > {
    const session = entry.session;
    if (!session)
      return {
        phase: null,
        connected: false,
        screenTail: "",
        sockPath: null,
        magmuxStderr: "",
        registry: null,
        preambleBytes: 0,
        readCoverage: null,
        gate: null,
        lastSend: null,
        claudeCodeVersion: null,
        anomalies: entry.info.detail ? [entry.info.detail] : [],
      };
    const snap = session.snapshot();
    const pane = session.diagnostics();
    return {
      phase: snap.phase,
      connected: snap.connected,
      screenTail: redactSecrets(snap.screenTail),
      sockPath: session.sockPath,
      magmuxStderr: redactSecrets(pane.magmuxStderr),
      registry: pane.registry,
      preambleBytes: pane.preambleBytes,
      readCoverage: pane.readCoverage,
      gate: pane.gate,
      lastSend: pane.lastSend,
      claudeCodeVersion: snap.claudeCodeVersion,
      anomalies: snap.anomalies,
    };
  }

  /**
   * Stop a session (§8 C): synchronous transition, asynchronous reap. Idempotent: a
   * second call returns the same state with `changed:false`. Throws
   * `ContractErrorException("unknown_session")` for a session this server does not hold.
   */
  cancelSession(sessionId: string): SessionCancelResult {
    const entry = this.liveEntry(sessionId);
    if (!entry) throw unknownSession(sessionId);
    if (!entry.session) return { session_id: sessionId, state: entry.info.state, changed: false };
    const r = entry.session.cancel();
    return { session_id: sessionId, state: r.state, changed: r.changed };
  }

  /**
   * Set a session's terminal size (§8 F), clamped. Allowed in every live state, mid-turn
   * included; last caller wins. A session whose pane is still starting stores the size and
   * starts at it (L2), answering `changed:true, pending:true`; one whose pane never
   * started answers the default size with `changed:false`. Throws
   * `ContractErrorException`: `unknown_session`, `resize_unsupported`,
   * `delivery_unavailable`.
   */
  async resizeSession(sessionId: string, cols: number, rows: number): Promise<ResizeResult> {
    const entry = this.liveEntry(sessionId);
    if (!entry) throw unknownSession(sessionId);
    if (!entry.session) {
      if (isTerminalState(entry.info.state))
        return {
          session_id: sessionId,
          cols: DEFAULT_PANE_COLS,
          rows: DEFAULT_PANE_ROWS,
          changed: false,
          seq: 0,
        };
      const size = clampPaneSize(cols, rows);
      entry.requestedSize = size;
      return { session_id: sessionId, ...size, changed: true, seq: 0, pending: true };
    }
    const r = await entry.session.resize(cols, rows);
    return { session_id: sessionId, ...r };
  }

  /**
   * The session's screen (§8 D): a memory read. `CaptureUnchanged` when `sinceSeq`
   * equals the current seq. A session whose pane never started answers a blank final
   * screen. Throws `ContractErrorException("unknown_session")` once it is not retained.
   */
  captureSession(
    sessionId: string,
    sinceSeq?: number,
    spans?: boolean
  ): CaptureResult | CaptureUnchanged {
    const entry = this.liveEntry(sessionId);
    if (!entry) throw unknownSession(sessionId);
    if (!entry.session)
      return sinceSeq === 0 ? { unchanged: true, seq: 0, final: true } : blankFinalCapture();
    return entry.session.capture(sinceSeq, { spans: spans === true });
  }

  /**
   * Sessions this process holds. IN-MEMORY ONLY, deliberately: session ids carry no
   * ordering, and the sessions directory only grows (≈ 10 000 entries measured), so a
   * directory scan is either slow or a sample. Recovery is id-addressed and O(1).
   */
  listSessions(includeCompleted = false): SessionInfo[] {
    const sessions: SessionInfo[] = [];
    for (const entry of this.sessions.values()) {
      this.refresh(entry);
      if (!includeCompleted && isTerminalState(entry.info.state)) continue;
      sessions.push({ ...entry.info });
    }
    return sessions;
  }

  /** `list_sessions` rows (§8 B). */
  listSessionRows(includeCompleted = false): SessionRow[] {
    const rows: SessionRow[] = [];
    for (const entry of this.sessions.values()) {
      this.refresh(entry);
      if (!includeCompleted && isTerminalState(entry.info.state)) continue;
      const info = { ...entry.info };
      rows.push(sessionRowOf(info, upstreamRecordsFor(info, entry.upstreamErrorLogPath)));
    }
    return rows;
  }

  /** A single session's info; falls back to `<sessionsDir>/<id>/meta.json`. */
  getSession(sessionId: string): SessionInfo {
    const entry = this.sessions.get(sessionId);
    if (!entry) return this.requireDiskRecord(sessionId).info;
    this.refresh(entry);
    return { ...entry.info };
  }

  /**
   * Settle every live session CANCELLED (process shutdown): each closes its open wait
   * (`to:"cancelled"`) and writes its `meta.json` on that transition, before this
   * resolves. The pane registry's `reapAllPanes` does the killing; a test that wants the
   * panes gone awaits its own no-orphan check.
   */
  async shutdownAll(): Promise<void> {
    // A pane still starting would otherwise be skipped here and run on unsettled.
    await Promise.all([...this.pendingStarts]);
    const pending: Promise<unknown>[] = [];
    for (const entry of this.sessions.values()) {
      const session = entry.session;
      if (!session) continue;
      if (!isTerminalState(session.snapshot().state)) session.cancel();
      pending.push(session.terminal.catch(() => undefined));
    }
    await Promise.all(pending);
  }

  // ─── Internal: the read-only disk fallback ───────────────────────────────

  /**
   * The LIVE entry for a session, or undefined. Never consults the disk: a recovered
   * record describes a process that is GONE, so `sendInput`, `cancelSession` and
   * `captureSession` go through here and the three readers do not.
   */
  private liveEntry(sessionId: string): SessionEntry | undefined {
    return this.sessions.get(sessionId);
  }

  /** A disk record for `sessionId`, or the same `not found` an unknown id always got. */
  private requireDiskRecord(sessionId: string): DiskRecord {
    const record = this.loadDiskRecord(sessionId);
    if (!record) throw new Error(`Session ${sessionId} not found`);
    return record;
  }

  /**
   * `<sessionsDir>/<id>`, or null when the id is not something we will join onto a
   * path: the allowlist, then a containment check.
   */
  private diskSessionDir(sessionId: string): string | null {
    if (!SESSION_ID_RE.test(sessionId)) return null;
    const root = resolve(this.sessionsDir);
    const dir = resolve(root, sessionId);
    if (dir !== join(root, sessionId)) return null;
    if (!dir.startsWith(root + sep)) return null;
    return dir;
  }

  /**
   * Rebuild a `SessionInfo` from `<sessionsDir>/<id>/`, reading both `meta.json`
   * generations. Every field is validated, never coerced; nothing here throws.
   */
  private loadDiskRecord(sessionId: string): DiskRecord | null {
    const sessionDir = this.diskSessionDir(sessionId);
    if (sessionDir === null) return null;

    let dirMtimeMs: number;
    try {
      const stat = statSync(sessionDir);
      if (!stat.isDirectory()) return null;
      dirMtimeMs = stat.mtimeMs;
    } catch {
      return null;
    }

    // A team run's record lives in the same directory (`team-<8 hex>/`) and its id
    // passes SESSION_ID_RE, but it is not a session; an id-addressed tool answers a
    // team id exactly like an unknown id.
    const spawnRecord = readJsonObject(join(sessionDir, "spawn.json"), META_READ_LIMIT);
    if (spawnRecord?.kind === "team") return null;
    const meta = readJsonObject(join(sessionDir, "meta.json"), META_READ_LIMIT);
    if (meta?.kind === "team") return null;
    const partial = meta === null;
    const measured = diskAccounting(sessionDir);

    const transcriptPath = this.diskTranscriptPath(
      meta,
      metaString(meta?.claudeSessionId) ?? metaString(spawnRecord?.claudeSessionId) ?? ""
    );
    return {
      sessionDir,
      partial,
      info: diskInfo({ sessionId, meta, spawnRecord, measured, dirMtimeMs, transcriptPath }),
    };
  }

  /**
   * The recorded transcript path, re-derived from `claudeSessionId` + the recorded cwd
   * when the stored one does not exist (F1 window, §3.3). A 10.4.0 record carries no
   * cwd, so its stored path is returned as is.
   */
  private diskTranscriptPath(meta: Record<string, unknown> | null, uuid: string): string {
    const stored = metaString(meta?.transcriptPath) ?? "";
    const cwd = metaString(meta?.cwd);
    if (stored && existsSync(stored)) return stored;
    if (cwd && uuid) return transcriptPathFor(cwd, uuid, projectsDir(this.parentEnv));
    return stored;
  }

  /** `getOutput` for a recovered session, replayed through a real `ScrollbackBuffer`. */
  private diskOutput(record: DiskRecord, tailLines?: number): SessionOutput {
    const tail = readTailText(join(record.sessionDir, "output.log"), OUTPUT_TAIL_BYTES);
    const buffer = new ScrollbackBuffer(this.scrollbackCapacity);
    if (tail?.text) buffer.append(dropLeadingFragment(tail));
    const info = record.info;
    return {
      sessionId: info.sessionId,
      state: info.state,
      output: buffer.getLines(tailLines).join("\n"),
      totalLines: buffer.totalLines,
      turnsCompleted: info.turnsCompleted,
      tokensIn: info.tokensIn,
      tokensOut: info.tokensOut,
      elapsedSeconds: info.elapsedSeconds,
      idleSeconds: null,
    };
  }

  /**
   * `getDiagnostics` for a recovered session. What died with the process says so rather
   * than guessing: no phase, no live connection, `at:""` on an event line without one,
   * and the one anomaly that CAN be observed from disk — a record with no `meta.json`.
   */
  private diskDiagnostics(record: DiskRecord, limit: number): SessionDiagnostics {
    const { sessionDir, info } = record;
    const eventLogPath = join(sessionDir, "events.jsonl");
    const upstreamErrorLogPath = join(sessionDir, "upstream-errors.jsonl");
    const outputLogPath = join(sessionDir, "output.log");
    const events = readTailLines(eventLogPath, EVENT_TAIL_BYTES);
    const outputTail = readTailText(outputLogPath, OUTPUT_TAIL_BYTES);
    const screen = readTailText(join(sessionDir, "screen.txt"), SCREEN_READ_BYTES);
    return {
      sessionId: info.sessionId,
      state: info.state,
      event: sessionEventFor(info).event,
      reason: info.reason,
      detail: info.detail,
      model: info.model,
      spawnModel: info.spawnModel,
      provider: info.provider,
      shape: info.shape,
      phase: null,
      exitCode: info.exitCode,
      idleSeconds: null,
      elapsedSeconds: info.elapsedSeconds,
      timeoutSeconds: info.timeoutSeconds,
      outputBytes: diskProseBytes(outputTail, fileSize(outputLogPath)),
      turnsCompleted: info.turnsCompleted,
      tokensIn: info.tokensIn,
      tokensOut: info.tokensOut,
      costUsd: info.costUsd,
      toolCalls: info.toolCalls,
      pendingInputs: 0,
      pendingHookInputs: 0,
      connected: false,
      screenTail: redactSecrets(screen?.text ?? "").trimEnd(),
      pane: info.pane,
      sockPath: null,
      magmuxStderr: "",
      registry: null,
      captureSource: info.captureSource,
      turnSource: info.turnSource,
      preambleBytes: 0,
      readCoverage: null,
      gate: null,
      lastSend: null,
      claudeCodeVersion: null,
      anomalies: record.partial
        ? [
            `no readable meta.json in ${sessionDir} — this record was reconstructed from ` +
              "the remaining artifacts, so state, exit code and timings are unknown. The " +
              "session's process died before it could write a verdict.",
          ]
        : [],
      recentEvents:
        limit === 0
          ? []
          : events.slice(-limit).map((line) => {
              // Redacted on the READ path too: a log from an older build was not.
              const redacted = redactSecrets(line);
              const truncated = redacted.length > EVENT_PREVIEW_CHARS;
              let at = "";
              try {
                const parsed = JSON.parse(line) as { at?: unknown };
                if (typeof parsed?.at === "string") at = parsed.at;
              } catch {
                /* not ours */
              }
              return {
                at,
                label: labelForLine(line),
                preview: truncated ? redacted.slice(0, EVENT_PREVIEW_CHARS) : redacted,
                truncated,
              };
            }),
      eventsTotal: events.length,
      upstreamErrors: readTailLines(upstreamErrorLogPath, UPSTREAM_ERROR_TAIL_BYTES),
      claudeSessionId: info.claudeSessionId || null,
      transcriptPath: info.transcriptPath || null,
      sessionDir,
      eventLogPath,
      upstreamErrorLogPath,
    };
  }

  // ─── Internal ────────────────────────────────────────────────────────

  /** Refresh a live entry's info from its pane (a memory read plus a cached token file). */
  private refresh(entry: SessionEntry): void {
    if (entry.session && !entry.ended) this.applySnapshot(entry, entry.session.snapshot());
    else if (!isTerminalState(entry.info.state))
      entry.info.elapsedSeconds = elapsedSecondsBetween(entry.info.startedAt, Date.now());
  }

  /**
   * `onTurnRecorded` (binding present): the answer reaches the output when the turn is
   * RECORDED, before its verdict and before any hold. A second record of the same index
   * (a re-wake) appends only the text past what was already written, once, as its own
   * paragraph (§7.4) — the same extension rule `appendAnswer` applies to a re-settle (D23).
   */
  private recordAnswer(entry: SessionEntry, index: number, answer: string): void {
    this.appendAnswer(entry, index, answer);
  }

  /** A settled turn's answer → scrollback, `output.log` and `outputBytes`. Once per turn. */
  private appendAnswer(entry: SessionEntry, index: number, answer: string): void {
    const prior = entry.answeredTurns.get(index);
    // a re-settle that adds nothing, or rewrites rather than extends, appends nothing
    if (prior !== undefined && (answer.length <= prior.length || !answer.startsWith(prior))) return;
    entry.answeredTurns.set(index, answer);
    const added = prior === undefined ? answer : answer.slice(prior.length).replace(/^\n+/, "");
    if (!added) return;
    const text = added.endsWith("\n") ? added : `${added}\n`;
    entry.proseBytes += Buffer.byteLength(added, "utf-8");
    this.appendToOutput(entry, text);
  }

  /**
   * Append a `[claudish] …` annotation of OUR OWN to the output. Not counted in
   * `outputBytes`: that metric is what the CHILD produced.
   */
  private recordNote(entry: SessionEntry, note: string): void {
    this.appendToOutput(entry, note);
  }

  private appendToOutput(entry: SessionEntry, text: string): void {
    entry.scrollback.append(text);
    entry.outputLogStream?.write(text);
  }

  /** One event record: into the in-memory ring AND onto `events.jsonl`, redacted once. */
  private appendEvent(entry: SessionEntry, record: Record<string, unknown>): void {
    const line = JSON.stringify(record);
    const redacted = redactSecrets(line);
    const truncated = redacted.length > EVENT_PREVIEW_CHARS;
    entry.eventRing.push({
      at: typeof record.at === "string" ? record.at : new Date().toISOString(),
      label: typeof record.type === "string" ? record.type : null,
      preview: truncated ? redacted.slice(0, EVENT_PREVIEW_CHARS) : redacted,
      truncated,
    });
    if (entry.eventRing.length > EVENT_RING_SIZE) entry.eventRing.shift();
    if (entry.eventLogBytes >= EVENT_LOG_LIMIT) return;
    const payload = `${redacted}\n`;
    entry.eventLogBytes += Buffer.byteLength(payload, "utf-8");
    const capped = entry.eventLogBytes >= EVENT_LOG_LIMIT;
    try {
      appendFileSync(
        entry.eventLogPath,
        capped
          ? `${payload}{"type":"claudish_truncated","limit_bytes":${EVENT_LOG_LIMIT}}\n`
          : payload
      );
    } catch {
      /* diagnostics are never load-bearing */
    }
  }

  /**
   * The wait log's two hooks (§20.1): one `open` line when the wire state enters
   * AWAITING_INPUT or AWAITING_PERMISSION, one `closed` line when it leaves both. Driven
   * by the pane's `onTransition`, which reports the NET change of one step, so a turn
   * that settles with a send queued (RUNNING → IDLE → ADMITTING) opens no wait. The
   * phase table has no wait-to-wait edge, so `to` is never `waiting_for_input`.
   */
  private recordWaitTransition(
    entry: SessionEntry,
    from: SlotState,
    to: SlotState,
    at: string,
    snap: PaneSnapshot
  ): void {
    const was = isWaiting(from);
    const is = isWaiting(to);
    if (!was && is) {
      entry.waitSince = at;
      this.appendWait(entry, { wait: "open", since: at, turns: snap.turnsCompleted });
      return;
    }
    if (was && !is) {
      this.appendWait(entry, {
        wait: "closed",
        since: entry.waitSince ?? at,
        at,
        to: sessionEventFor(snap).event,
      });
      entry.waitSince = null;
    }
  }

  /**
   * Append one line to `waits.jsonl`. Durable on purpose: a wait can open and close
   * between two reads of any observer. One `appendFileSync` of under 200 bytes per line;
   * a write failure loses only that line. The log stops at WAIT_LOG_LIMIT.
   */
  private appendWait(
    entry: SessionEntry,
    line:
      | { wait: "open"; since: string; turns: number }
      | { wait: "closed"; since: string; at: string; to: SessionEventType }
  ): void {
    if (entry.waitLogBytes >= WAIT_LOG_LIMIT) return;
    const payload = `${JSON.stringify(line)}\n`;
    entry.waitLogBytes += Buffer.byteLength(payload, "utf-8");
    try {
      appendFileSync(entry.waitLogPath, payload);
    } catch (err) {
      process.stderr.write(
        `[claudish] session ${entry.info.sessionId}: could not append to waits.jsonl: ` +
          `${err instanceof Error ? err.message : String(err)}\n`
      );
    }
  }

  /** Drop a terminal session from the map after its retention window (memory only). */
  private scheduleEviction(entry: SessionEntry): void {
    if (entry.evictHandle) return;
    entry.evictHandle = setTimeout(() => {
      this.sessions.delete(entry.info.sessionId);
    }, this.terminalRetentionMs);
    // Never a reason for the MCP server to stay alive.
    entry.evictHandle.unref?.();
    this.evictOldestTerminal();
  }

  /** Enforce the hard ceiling, oldest terminal session first. */
  private evictOldestTerminal(): void {
    const terminal = [...this.sessions.values()].filter((c) => c.ended);
    if (terminal.length <= MAX_TERMINAL_SESSIONS) return;
    terminal.sort((a, b) => (a.info.completedAt ?? "").localeCompare(b.info.completedAt ?? ""));
    for (const victim of terminal.slice(0, terminal.length - MAX_TERMINAL_SESSIONS)) {
      if (victim.evictHandle) clearTimeout(victim.evictHandle);
      this.sessions.delete(victim.info.sessionId);
    }
  }

  private get activeSessions(): number {
    let count = 0;
    for (const entry of this.sessions.values()) if (!entry.ended) count++;
    return count;
  }
}

function isWaiting(s: SlotState): boolean {
  return s === "AWAITING_INPUT" || s === "AWAITING_PERMISSION";
}

/**
 * The state and reason of a disk record, from either `meta.json` generation: the pane
 * generation's `state` (a closed-set value) and `terminalReason` (a `FailureReason`), or
 * 10.4.0's `status`. A non-terminal or unknown value — and a missing record — reads
 * FAILED with reason null (§8 B).
 */
function diskState(meta: Record<string, unknown> | null): {
  state: SlotState;
  reason: FailureReason | null;
} {
  const raw = meta?.state;
  if (typeof raw === "string" && (SLOT_STATES as readonly string[]).includes(raw)) {
    const state = raw as SlotState;
    if (!isTerminalState(state)) return { state: "FAILED", reason: null };
    return { state, reason: state === "COMPLETED" ? null : metaReason(meta?.terminalReason) };
  }
  // 10.4.0: its terminalReason was Claude Code's text, not a FailureReason, so only the
  // two reasons a state implies are known.
  const status = typeof meta?.status === "string" ? STATE_OF_10_4_STATUS[meta.status] : undefined;
  const state = status ?? "FAILED";
  if (state === "CANCELLED") return { state, reason: "cancelled" };
  if (state === "TIMEOUT") return { state, reason: "timeout" };
  return { state, reason: null };
}

/**
 * A `SessionInfo` from a session directory's files. Every field is validated, never
 * coerced: a `meta.json` truncated mid-write by a SIGKILL is the case this is FOR.
 */
function diskInfo(d: {
  sessionId: string;
  meta: Record<string, unknown> | null;
  spawnRecord: Record<string, unknown> | null;
  measured: ReturnType<typeof diskAccounting>;
  dirMtimeMs: number;
  transcriptPath: string;
}): SessionInfo {
  const { meta, spawnRecord, measured } = d;
  const startedAt =
    metaString(meta?.startedAt) ??
    metaString(spawnRecord?.startedAt) ??
    new Date(d.dirMtimeMs).toISOString();
  const completedAt = metaString(meta?.completedAt);
  const { state, reason } = diskState(meta);
  return {
    // The id we were ASKED for, never the one in the file.
    sessionId: d.sessionId,
    model: metaString(meta?.model) ?? metaString(spawnRecord?.model) ?? "unknown",
    spawnModel: metaString(meta?.spawnModel),
    provider: metaString(meta?.provider),
    state,
    shape: meta?.shape === "interactive" ? "interactive" : "one-shot",
    pane: metaString(meta?.pane),
    // NEVER the pid from the file: it belonged to a process that is gone, and pids are
    // reused.
    panePid: null,
    startedAt,
    completedAt,
    exitCode: metaNumber(meta?.exitCode),
    turnsCompleted: metaNumber(meta?.turnsCompleted) ?? 0,
    tokensIn: metaNumber(meta?.tokensIn) ?? measured.tokensIn,
    tokensOut: metaNumber(meta?.tokensOut) ?? measured.tokensOut,
    costUsd: metaNumber(meta?.costUsd) ?? measured.costUsd,
    toolCalls: metaNumber(meta?.toolCallCount) ?? measured.toolCalls,
    lastActivityAt: metaString(meta?.lastActivityAt),
    // Wall time as it ENDED, not as it looks now.
    elapsedSeconds: elapsedSecondsBetween(
      startedAt,
      completedAt ? Date.parse(completedAt) : d.dirMtimeMs
    ),
    // Read from disk: no live process to be idle. Null, never 0.
    idleSeconds: null,
    activity: null,
    recent: null,
    reason,
    detail: meta === null ? NO_TERMINAL_RECORD : metaString(meta.detail),
    pendingInputs: 0,
    claudeSessionId:
      metaString(meta?.claudeSessionId) ?? metaString(spawnRecord?.claudeSessionId) ?? "",
    ...optionalParent(metaString(meta?.parentClaudeSessionId)),
    transcriptPath: d.transcriptPath,
    captureSource: diskCaptureSource(meta?.captureSource),
    turnSource: meta?.turnSource === "screen" ? "screen" : "transcript",
    timeoutSeconds:
      metaNumber(meta?.timeoutSeconds) ?? metaNumber(spawnRecord?.timeoutSeconds) ?? 0,
  };
}

function diskCaptureSource(v: unknown): SessionInfo["captureSource"] {
  return v === "transcript" || v === "screen" || v === "none" ? v : null;
}