ccdeck 3.43.3 → 3.44.0

package/src/server/session-summary.mjs

@@ -0,0 +1,281 @@
+// The sessions a deck is watching, as one row each, for `ccdeck sessions`
+// (#2183) — the question somebody on SSH asks first: which of my agents is
+// waiting on me?
+//
+// The canvas answers it from src/web/reducer.ts, which folds every event into a
+// graph of agents, tool calls and subagents. None of that is needed to say
+// which sessions exist and which one is blocked, and none of it can be imported
+// here: it is TypeScript bundled for the browser. So this is a small fold over
+// the same ring, and THE WAITING RULE IS A MIRROR of src/web/waiting-block.ts —
+// the same three `notification_type` kinds, the same events that leave a block
+// standing, the same rule for whose traffic clears one — written twice because
+// it has to be, the way block-notify.mjs mirrors sound.ts.
+// session-summary-mirror.test.ts runs both over the same events and fails the
+// day they disagree.
+//
+// Pure: envelopes in, rows out. The route that serves it is in index.mjs.
+
+/** How long a session may be silent before it is taken to be gone — the
+ *  canvas's own STALE_SESSION_MS (src/web/board-sweeps.ts), for its reasons:
+ *  long enough for a permission prompt left standing through a meeting, short
+ *  enough that this morning's closed terminals stop being listed as running. */
+export const STALE_SESSION_MS = 90 * 60_000;
+
+/** The `notification_type` values that raise a block, as the chore each one is
+ *  — waitingKind in waiting-block.ts. */
+export function waitingKind(notificationType) {
+  if (notificationType === "permission_prompt") return "permission";
+  if (notificationType === "agent_needs_input") return "asked";
+  if (notificationType === "idle_prompt") return "idle";
+  return null;
+}
+
+/** Events that are not evidence the session moved, and leave a block standing
+ *  — WAITING_KEEPERS in waiting-block.ts, which says why each one is here. */
+export const WAITING_KEEPERS = new Set([
+  "Notification", "ModelObserved", "ContextObserved", "UsageObserved",
+  "SessionNamed", "SessionRecapped", "OutputObserved", "ActivityObserved", "JobObserved",
+]);
+
+/** The transcript scans: enrichment the server reads off a session's files,
+ *  never the session's own traffic — the reducer's early returns, which stamp
+ *  no provider and prove nothing about whether the session is alive. */
+const SCANS = new Set([...WAITING_KEEPERS].filter(n => n !== "Notification"));
+
+/** Two copies of one event inside this are the wire talking twice —
+ *  HOOK_REDELIVERY_WINDOW_MS and PROMPT_REDELIVERY_WINDOW_MS in
+ *  src/web/redelivery.ts, which are the same number on purpose. */
+const REDELIVERY_MS = 2_000;
+
+/** Whose traffic an event is: the subagent it names, or null for the root's —
+ *  explicitSubagentKey in agent-attribution.ts. */
+function subagentKeyOf(p) {
+  if (p.agent_id) return p.agent_id;
+  if (p.parent_tool_use_id) return p.parent_tool_use_id;
+  return null;
+}
+
+/** Is this event evidence the human dealt with `w`? clearsWaiting in
+ *  waiting-block.ts: any traffic falsifies an idle block; a permission prompt
+ *  or a question is answered only by the root's own traffic or by the very
+ *  subagent that asked. */
+function clearsWaiting(w, p) {
+  if (w.kind === "idle") return true;
+  const key = subagentKeyOf(p);
+  if (key == null) return true;
+  return w.subagent != null && w.subagent === key;
+}
+
+/** The newest call still in flight on a session, whose payload names who is
+ *  asking — blockedCall in waiting-block.ts, minus the canvas's owner lookup:
+ *  the payload's own key is what that function reads in the end. */
+function newestInFlight(s) {
+  let newest = null;
+  for (const c of s.inFlight.values()) if (!newest || c.at > newest.at) newest = c;
+  return newest;
+}
+
+function blankSession(id, at) {
+  return {
+    id, provider: null, cwd: null, name: null, model: null,
+    startedAt: at, lastEventAt: at, recoveryLiveAt: null,
+    turn: "idle", turnSince: at, closed: false, waiting: null,
+    prompts: [], lastTurnEndAt: null,
+    inFlight: new Map(),
+  };
+}
+
+/** A prompt, filed in time order unless it is a copy of one already filed —
+ *  recordPrompt in redelivery.ts. Only the newest is ever read, as evidence. */
+function recordPrompt(s, at, text) {
+  for (let i = s.prompts.length - 1; i >= 0; i--) {
+    const prev = s.prompts[i];
+    if (prev.at < at - REDELIVERY_MS) break;
+    if (prev.text === text && prev.at <= at + REDELIVERY_MS) return;
+  }
+  let i = s.prompts.length;
+  while (i > 0 && s.prompts[i - 1].at > at) i--;
+  s.prompts.splice(i, 0, { at, text });
+}
+
+/**
+ * `Stop` or `SessionEnd`: the root's turn is over — applyTurnEnd in
+ * session-lifecycle.ts, the parts of it a row can show.
+ *
+ * Refused whole when it is out of order (a boundary older than the prompt that
+ * opened the turn now running) or a copy of the ending already recorded, for
+ * the reducer's reason (#1022): a replayed `Stop` landing in the next turn
+ * would call a working session "your turn". And the calls it settles are the
+ * ROOT's only, and none on Codex: a background subagent outlives the turn that
+ * dispatched it, and its call — and a permission prompt that call raises — is
+ * still running after the root's `Stop`.
+ */
+function endTurn(s, name, at) {
+  const newest = s.prompts[s.prompts.length - 1];
+  const evidenceAt = newest && newest.at > s.startedAt ? newest.at : s.startedAt;
+  if (at < evidenceAt) return;
+  if (s.lastTurnEndAt != null && evidenceAt > s.lastTurnEndAt && at <= s.lastTurnEndAt + REDELIVERY_MS) return;
+  s.turn = "idle"; s.turnSince = at;
+  s.lastTurnEndAt = at;
+  if (s.provider !== "codex") {
+    for (const [id, call] of s.inFlight) if (call.key == null) s.inFlight.delete(id);
+  }
+  if (name === "SessionEnd") s.closed = true;
+}
+
+/**
+ * The deck's recovery scan, which finds a session already running when it
+ * starts — recoverSession in session-recovery.ts. Not the session's traffic:
+ * it leaves a standing block standing (after a restart the replay has put the
+ * session's prompt back up, and the scan arrives every second and a half),
+ * and a snapshot older than the session's own newest event says nothing.
+ */
+function recover(sessions, p, at) {
+  const id = p.session_id;
+  if ((p.provider !== "codex" && p.provider !== "claude") || typeof id !== "string" || !id) return;
+  const s = sessions.get(id);
+  if (s?.provider && s.provider !== p.provider) return;
+  if (s && Number.isFinite(p.snapshot_observed_at) && (s.recoveryLiveAt ?? s.lastEventAt ?? 0) >= p.snapshot_observed_at) return;
+  if (p.recovery_active === false) {
+    if (s) endTurn(s, p.recovery_session_closed === true ? "SessionEnd" : "Stop", at);
+    return;
+  }
+  const r = s ?? blankSession(id, at);
+  sessions.set(id, r);
+  r.recoveryLiveAt ??= s?.lastEventAt ?? 0;
+  r.provider = p.provider;
+  r.closed = false;
+  if (r.turn !== "working") { r.turn = "working"; r.turnSince = at; }
+  r.lastEventAt = at;
+  if (!r.cwd && typeof p.cwd === "string" && p.cwd) r.cwd = p.cwd;
+  if (typeof p.model === "string" && p.model) r.model = p.model;
+  if (!s && Number.isFinite(p.turn_started_at) && p.turn_started_at <= at) r.startedAt = p.turn_started_at;
+  if (typeof p.prompt === "string" && p.prompt && r.prompts.at(-1)?.text !== p.prompt) r.prompts.push({ at, text: p.prompt });
+}
+
+/**
+ * Every session in the ring, folded.
+ *
+ * `envelopes` are the ring's own `{ seq, receivedAt, payload }`, oldest first.
+ * Each row says what the session is doing in one word:
+ *
+ *   waiting   a permission prompt or a question is standing — the alarm the
+ *             topbar chip counts (isAlarming in ambient-counts.ts)
+ *   working   a turn is running
+ *   idle      the turn ended and the input box is waiting, which is not an
+ *             alarm (#348) but is "your turn"
+ *   ended     SessionEnd, or nothing heard for STALE_SESSION_MS
+ */
+export function summarizeSessions(envelopes, { now = Date.now(), staleMs = STALE_SESSION_MS } = {}) {
+  let sessions = new Map();
+  for (const env of Array.isArray(envelopes) ? envelopes : []) {
+    const p = env?.payload;
+    if (!p || typeof p !== "object") continue;
+    const name = p.hook_event_name ?? "Unknown";
+    // POST /api/clear wipes the canvas with this; it wipes the list too.
+    if (name === "__clear") { sessions = new Map(); continue; }
+    const at = Number(env.receivedAt) || now;
+    if (name === "ClaudeSessionRecovered" || name === "CodexSessionRecovered") { recover(sessions, p, at); continue; }
+    const id = typeof p.session_id === "string" && p.session_id ? p.session_id : null;
+    if (!id) continue;
+    let s = sessions.get(id);
+    if (!s) { s = blankSession(id, at); sessions.set(id, s); }
+    // A Codex child thread named by its parent: a session of its own, and
+    // nothing the human did — linkCodexThread, which returns before any block
+    // is read.
+    if (name === "CodexThreadLinked") { if (p.provider === "codex") s.provider ??= "codex"; continue; }
+
+    if (!WAITING_KEEPERS.has(name) && s.waiting && clearsWaiting(s.waiting, p)) s.waiting = null;
+    // A background job's file is not always the session talking — see the
+    // reducer's note at noteSessionHeard.
+    if (name !== "JobObserved" && at > s.lastEventAt) s.lastEventAt = at;
+    if (!SCANS.has(name)) {
+      // The provider, from the session's first own event; a scan stamps none.
+      s.provider ??= p.provider === "codex" ? "codex" : "claude";
+      if (at >= (s.recoveryLiveAt ?? 0)) s.recoveryLiveAt = at;
+    }
+    if (!s.cwd && typeof p.cwd === "string" && p.cwd) s.cwd = p.cwd;
+    if (typeof p.model === "string" && p.model && !subagentKeyOf(p)) s.model = p.model;
+    if (name === "SessionNamed") s.name = p.sessionTitle ?? p.sessionName ?? s.name;
+
+    switch (name) {
+      case "SessionStart":
+        s.closed = false;
+        // The earliest beginning heard of, as applySessionStart keeps it.
+        s.startedAt = Math.min(s.startedAt, at);
+        if (s.turn !== "working") { s.turn = "idle"; s.turnSince = at; }
+        break;
+      case "UserPromptSubmit": {
+        s.closed = false;
+        s.turn = "working"; s.turnSince = at;
+        const text = typeof p.prompt === "string" ? p.prompt : typeof p.message === "string" ? p.message : "";
+        if (text) recordPrompt(s, at, text);
+        break;
+      }
+      case "Stop":
+      case "SessionEnd":
+        endTurn(s, name, at);
+        break;
+      case "PreToolUse":
+        if (p.tool_use_id) s.inFlight.set(p.tool_use_id, { at, key: subagentKeyOf(p), tool: p.tool_name ?? null });
+        if (s.turn !== "working") { s.turn = "working"; s.turnSince = at; }
+        break;
+      case "PostToolUse":
+      case "PostToolUseFailure":
+        if (p.tool_use_id) s.inFlight.delete(p.tool_use_id);
+        break;
+      case "Notification": {
+        const kind = waitingKind(p.notification_type);
+        if (!kind) break;
+        const message = typeof p.message === "string" ? p.message : "";
+        const prev = s.waiting;
+        if (prev && prev.kind === kind && prev.message === message) {
+          prev.since = Math.min(prev.since, at);
+          break;
+        }
+        const block = { kind, message, since: at, subagent: null, tool: null };
+        if (kind === "permission") {
+          const call = newestInFlight(s);
+          if (call?.key) block.subagent = call.key;
+          // BLOCK_GUESS_WINDOW_MS: only a call that started moments before the
+          // prompt is printed as the thing being asked about.
+          if (call?.tool && at - call.at <= 30_000 && call.at <= at) block.tool = call.tool;
+        }
+        s.waiting = block;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const rows = [];
+  for (const s of sessions.values()) {
+    const gone = s.closed || now - s.lastEventAt > staleMs;
+    const alarm = !gone && s.waiting && s.waiting.kind !== "idle";
+    const state = gone ? "ended" : alarm ? "waiting" : s.turn === "working" && !s.waiting ? "working" : "idle";
+    const since = state === "waiting" ? s.waiting.since
+      : state === "idle" && s.waiting ? Math.min(s.waiting.since, s.turnSince)
+      : state === "ended" ? s.lastEventAt
+      : s.turnSince;
+    rows.push({
+      id: s.id,
+      provider: s.provider ?? "claude",
+      cwd: s.cwd,
+      project: s.cwd ? s.cwd.split(/[\\/]/).filter(Boolean).pop() ?? s.cwd : null,
+      name: s.name,
+      model: s.model,
+      state,
+      since,
+      startedAt: s.startedAt,
+      lastEventAt: s.lastEventAt,
+      waiting: gone || !s.waiting ? null : { kind: s.waiting.kind, message: s.waiting.message, since: s.waiting.since, tool: s.waiting.tool },
+    });
+  }
+  // The ones waiting on a human first, longest-blocked first — the order the
+  // topbar's own click visits them (blockedSessions) — then running, then the
+  // idle and the ended, most recently heard first.
+  const rank = { waiting: 0, working: 1, idle: 2, ended: 3 };
+  return rows.sort((a, b) => rank[a.state] - rank[b.state]
+    || (a.state === "waiting" ? a.since - b.since : b.lastEventAt - a.lastEventAt));
+}

package/src/server/skill-hook.mjs

@@ -0,0 +1,162 @@
+// Whether the deck may add the UserPromptExpansion hook that Skill activity
+// counts typed slash commands with (#2181) — and, until somebody asks for it,
+// the answer is no.
+//
+// WHY THIS ENTRY IS GATED HARDER THAN STOPFAILURE. A hook event name Claude
+// Code does not know is not skipped by every version. Up to 2.1.100 it made
+// Claude Code ignore the WHOLE settings.json — the user's permissions, env,
+// model and every hook in it, ours included — without a word on screen. 2.1.101
+// changed that ("an unrecognized hook event name in settings.json no longer
+// causes the entire file to be ignored", Claude Code's CHANGELOG.md, 2.1.101).
+// UserPromptExpansion itself arrived later still: the first npm release whose
+// CLI carries the name, and whose Agent SDK lists it in HOOK_EVENTS, is 2.1.116
+// (2.1.114 has neither, and there is no 2.1.115). Checked offline against the
+// published packages, with a scratch config holding the deck's own entry shape:
+//
+//   2.1.100  the whole file ignored — no hook fired, no env applied
+//   2.1.101  the file read, the entry ignored
+//   2.1.114  the file read, the entry ignored
+//   2.1.116  the file read, the entry fired on a typed custom command
+//
+// So the gate is the later of the two: 2.1.116, which is where the entry is
+// both harmless and useful. Below it the entry buys nothing, and below 2.1.101
+// it costs the user every setting they have.
+//
+// WHAT HAS TO BE TRUE before the entry is written:
+//   - the deck was started with AGENTS_DECK_SKILL_HOOK=1 — never by default;
+//   - at least one Claude Code was found, the way the deck finds `claude`: the
+//     candidate list (claude-dir.mjs) and AGENTS_DECK_CLAUDE;
+//   - EVERY one found says which version it is, and every one is 2.1.116 or
+//     newer. An old CLI anywhere on the machine still reads the same file, and
+//     one that will not say its version is treated as an old one.
+// A version is read off disk first (claude-dir.mjs, no child process). Only
+// for an install whose layout does not name one — a wrapper script, an unusual
+// prefix — and only once the user has opted in, is that binary asked
+// `--version`, by its full path and as argv, and believed only when it answers
+// the way Claude Code does: `<x.y.z> (Claude Code)`.
+//
+// Every boot re-decides. A machine that stops passing — the opt-in removed, a
+// Claude Code rolled back, a second, older one installed — has the entry taken
+// back out by the next start (installer.mjs), and the user's own
+// UserPromptExpansion hooks are left where they are.
+import { claudeCodeInstalls, claudeVersionAtLeast } from "./claude-dir.mjs";
+import { run } from "./exec.mjs";
+
+export const USER_PROMPT_EXPANSION = "UserPromptExpansion";
+
+/** The first Claude Code that knows the event: 2.1.116 (npm). */
+export const USER_PROMPT_EXPANSION_SINCE = "2.1.116";
+
+/** The first Claude Code that skips an unknown hook event instead of ignoring
+ *  the whole settings.json: 2.1.101 (CHANGELOG.md). */
+export const UNKNOWN_EVENT_TOLERATED_SINCE = "2.1.101";
+
+/** The gate: a version that is past both of the above. */
+export const SKILL_HOOK_SINCE = claudeVersionAtLeast(USER_PROMPT_EXPANSION_SINCE, UNKNOWN_EVENT_TOLERATED_SINCE)
+  ? USER_PROMPT_EXPANSION_SINCE
+  : UNKNOWN_EVENT_TOLERATED_SINCE;
+
+/** Set to "1" to ask for the entry. Anything else, or nothing, is no. */
+export const SKILL_HOOK_ENV = "AGENTS_DECK_SKILL_HOOK";
+
+/** Whether the person starting the deck asked for the entry. Only the exact
+ *  string "1": a typo or a "true" does not turn it on. */
+export function skillHookOptedIn(env = process.env) {
+  return env?.[SKILL_HOOK_ENV] === "1";
+}
+
+/** A `--version` that is not quick is not Claude Code's fast path. */
+const PROBE_TIMEOUT_MS = 5_000;
+
+/** What Claude Code prints for `--version`, e.g. `2.1.116 (Claude Code)`. A
+ *  first line in any other shape — a wrapper's own version, an error, an
+ *  update notice — is no answer. */
+const VERSION_LINE_RE = /^(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?) \(Claude Code\)$/;
+
+/** The version in Claude Code's own `--version` output, or undefined. */
+export function parseClaudeVersionOutput(text) {
+  const first = String(text ?? "").split(/\r?\n/).map(l => l.trim()).find(l => l !== "");
+  const m = first === undefined ? null : VERSION_LINE_RE.exec(first);
+  return m ? m[1] : undefined;
+}
+
+async function askVersion(runImpl, bin, timeout) {
+  try {
+    const r = await runImpl(bin, ["--version"], { timeout });
+    return r?.ok ? parseClaudeVersionOutput(r.stdout) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The decision, and why:
+ *
+ *   { install: false, state: "off",     reason: "not-enabled" }
+ *   { install: false, state: "skipped", reason: "no-claude" | "version-unknown" | "too-old", versions }
+ *   { install: true,  state: "on",      versions }
+ *
+ * `versions` is what was found, in the order found, with `null` for an install
+ * that did not say. `since` is the gate. Never throws: a probe that fails is a
+ * version that is unknown, which is a refusal.
+ *
+ * Every dependency is injected so the suite can lay out any machine: `installs`
+ * is claudeCodeInstalls()'s answer, `runImpl` is exec.mjs's run.
+ */
+export async function skillHookDecision({
+  env = process.env,
+  optedIn = skillHookOptedIn(env),
+  installs,
+  runImpl = run,
+  timeout = PROBE_TIMEOUT_MS,
+} = {}) {
+  const since = SKILL_HOOK_SINCE;
+  // Off is decided before anything is looked at: a deck that was not asked
+  // spends nothing on the question, and spawns nothing.
+  if (!optedIn) return { install: false, state: "off", reason: "not-enabled", since, versions: [] };
+  let found;
+  try {
+    found = Array.isArray(installs) ? [...installs] : claudeCodeInstalls();
+  } catch {
+    found = [];
+  }
+  // AGENTS_DECK_CLAUDE is the other way the deck finds `claude` — the sign-in
+  // and the account panel run it ahead of the candidate list
+  // (claude-identity.mjs) — so it is one more Claude Code that reads this
+  // settings.json. Its layout is not read: it is asked.
+  const configured = typeof env?.AGENTS_DECK_CLAUDE === "string" ? env.AGENTS_DECK_CLAUDE.trim() : "";
+  if (configured && !found.some(i => i.bin === configured)) found.push({ bin: configured, version: undefined });
+  if (found.length === 0) return { install: false, state: "skipped", reason: "no-claude", since, versions: [] };
+  const versions = [];
+  for (const { bin, version } of found) {
+    const v = version ?? (typeof bin === "string" && bin ? await askVersion(runImpl, bin, timeout) : undefined);
+    versions.push(v ?? null);
+  }
+  if (versions.some(v => v === null)) return { install: false, state: "skipped", reason: "version-unknown", since, versions };
+  if (!versions.every(v => claudeVersionAtLeast(v, since))) {
+    return { install: false, state: "skipped", reason: "too-old", since, versions };
+  }
+  return { install: true, state: "on", since, versions };
+}
+
+/**
+ * The boot report's row for the entry — `{ ok, detail }` — or null when there
+ * is nothing to say, which is the default: nobody asked for it, and a deck
+ * that was not asked prints exactly what it printed before. `dash` is the
+ * screen's own (bin/cli/screen.js), so the line carries no punctuation a
+ * legacy console cannot draw.
+ */
+export function skillHookStatus(decision, dash = "-") {
+  if (!decision || decision.state === "off") return null;
+  const found = (decision.versions ?? []).map(v => v ?? "unknown").join(", ");
+  if (decision.state === "on") return { ok: true, detail: `on ${dash} counts typed slash commands (Claude Code ${found})` };
+  const why = {
+    "no-claude": "no Claude Code found",
+    "version-unknown": `a Claude Code here does not say its version (found: ${found})`,
+    "too-old": `needs Claude Code ${decision.since} or newer everywhere (found: ${found})`,
+    "settings-shape": "the hooks in settings.json are not in a shape the deck can add to",
+    "backup-failed": "settings.json could not be backed up first",
+    raced: "settings.json changed while installing; the next start tries again",
+  }[decision.reason] ?? "not allowed";
+  return { ok: false, detail: `not installed ${dash} ${why}` };
+}

package/src/server/stop-continue-gate.d.mts

@@ -0,0 +1,8 @@
+import type { StopFacts } from "./stop-failure.mjs";
+export interface LoginEvidence { ok: boolean; at: number; room: boolean | null }
+export type GateReason = "no-login" | "before-stop" | "no-room";
+export interface Gate { ready: boolean; reason: GateReason | null }
+export const CONTINUE_PROMPT: string;
+export const REPEAT_HOLD_MS: number;
+export function loginEvidence(reading: unknown): LoginEvidence | null;
+export function continueGate(stop: Pick<StopFacts, "kind" | "at"> | null | undefined, login: LoginEvidence | null | undefined): Gate;

package/src/server/stop-continue-gate.mjs

@@ -0,0 +1,77 @@
+// When a turn that stopped on an expired login or a usage limit may be run
+// again (#2193), read once for both halves of the deck: the page draws the
+// Continue button from it, and the server refuses a press — and holds back the
+// automatic continue — on the same answer. The page imports this file the way
+// it imports stop-failure.mjs, so the two cannot come to disagree about one
+// stop.
+//
+// WHAT COUNTS AS "A WORKING LOGIN IS ACTIVE AGAIN". The deck's newest reading
+// of the active account's usage (quota.mjs), taken AFTER the stop and without
+// an error. That reading is made with the very credentials a session uses —
+// Claude Code's own token, `claude --print /usage`, or claude-swap's copy of
+// the active account — so a login that is still dead cannot produce one, and
+// one from before the stop says nothing about the login now. A switch of
+// account invalidates the reading, so the next one is about the new account.
+//
+// And the account has to have room: a working login on an account at 100% of
+// its 5-hour or 7-day window would stop the turn again on a usage limit at its
+// first request.
+//
+// Pure. Nothing here reads a clock, a file or a process.
+
+/** What the deck sends a background session to continue the turn that
+ *  failed: Claude Code's own words for it, the default of
+ *  CLAUDE_CODE_RESUME_PROMPT (code.claude.com/docs/en/env-vars), which is what
+ *  Claude Code sends when it continues an interrupted turn by itself. */
+export const CONTINUE_PROMPT = "Continue from where you left off.";
+
+/**
+ * A session the deck continued automatically, which then stops again on a
+ * login or a limit inside this window, is not continued automatically again
+ * until somebody acts on it — a prompt typed into it, or a press of Continue.
+ * That is the loop the setting must never become: a login that works for one
+ * request and dies on the next would otherwise be continued, stop, and be
+ * continued again for as long as the deck runs.
+ */
+export const REPEAT_HOLD_MS = 60 * 60_000;
+
+/**
+ * The quota reading as the gate reads it: `{ ok, at, room }`, or null when
+ * there is no reading at all.
+ *
+ *   ok    the reading is a real one, not a failure to read
+ *   at    when its numbers were collected — the reading's own clock, which is
+ *         the one that can be compared with a stop's (a reading the deck is
+ *         only holding over is still as old as it says)
+ *   room  both of the account's windows are under 100%, or null when the
+ *         reading names neither
+ */
+export function loginEvidence(reading) {
+  if (!reading || typeof reading !== "object") return null;
+  const at = Number(reading.fetchedAt);
+  const when = Number.isFinite(at) && at > 0 ? at : 0;
+  if (reading.ok !== true || !when) return { ok: false, at: when, room: null };
+  const pcts = [reading.session5hPct, reading.week7dPct].filter(v => typeof v === "number" && Number.isFinite(v));
+  return { ok: true, at: when, room: pcts.length ? pcts.every(p => p < 100) : null };
+}
+
+/**
+ * Whether the turn `stop` ended may be continued now, and when not, why:
+ *
+ *   "no-login"     there is no working reading of the active account at all
+ *   "before-stop"  the newest one was taken before the stop, so it cannot say
+ *                  the login works now
+ *   "no-room"      it works, and its 5-hour or 7-day window is full
+ *
+ * An API error that is neither — an overloaded server, a refused request — is
+ * not about the login, so nothing here holds it back. The automatic continue
+ * never acts on one (stop-continue.mjs); a press may.
+ */
+export function continueGate(stop, login) {
+  if (!stop || typeof stop !== "object") return { ready: false, reason: "no-login" };
+  if (stop.kind !== "login" && stop.kind !== "usage-limit") return { ready: true, reason: null };
+  if (!login || !login.ok) return { ready: false, reason: "no-login" };
+  if (!(login.at > stop.at)) return { ready: false, reason: "before-stop" };
+  if (login.room === false) return { ready: false, reason: "no-room" };
+  return { ready: true, reason: null };
+}