ccdeck 3.42.0 → 3.43.0

package/src/server/codex-recovery.mjs

@@ -0,0 +1,83 @@
+import { codexThreadLink } from "./codex-lineage.mjs";
+import { turnContextEffort } from "./codex-translate.mjs";
+import { stat } from "node:fs/promises";
+import { readAppendedLines } from "./jsonl-chunks.mjs";
+
+export const RECOVERY_TAIL_BYTES = 8 * 1024 * 1024;
+export const RECOVERY_FILE_LIMIT = 128;
+export const RECOVERY_SCAN_BYTES = 32 * 1024 * 1024;
+export const RECOVERY_RECENT_MS = 24 * 60 * 60 * 1000;
+
+/** A fixed prefix of an existing file. The live watcher resumes at offset. */
+export async function readCodexRecovery(path, initial, sid, cwd, factsBefore = Infinity) {
+  const from = Math.max(0, initial.size - RECOVERY_TAIL_BYTES);
+  const cursor = { offset: from, midLine: from > 0 };
+  const result = { active: false, at: null, turnId: null, prompt: undefined,
+    model: undefined, usage: undefined, window: undefined, effort: undefined,
+    approval: undefined, contextTokens: undefined, offset: initial.size, certain: true, links: [] };
+  let pendingPrompt;
+  { // The entire bounded tail fits in one reader chunk; never reread a partial suffix.
+    const { text, advanced } = await readAppendedLines(path, cursor, initial.size);
+    if (!advanced && initial.size > from) result.certain = false;
+    let lineEnd = cursor.offset - Buffer.byteLength(text) - 1;
+    for (const line of text.split("\n")) {
+      lineEnd += Buffer.byteLength(line) + 1;
+      if (!line) continue;
+      let row;
+      try { row = JSON.parse(line); } catch { result.certain = false; continue; }
+      const link = codexThreadLink(row, sid, cwd);
+      if (link) result.links.push(link);
+      const p = row?.payload;
+      if (row?.type === "turn_context") {
+        if (typeof p?.model === "string") result.model = p.model;
+        result.effort = turnContextEffort(p);
+        if (typeof p?.approval_policy === "string") result.approval = p.approval_policy;
+      }
+      if (row?.type !== "event_msg" || !p) continue;
+      if (p.type === "task_started") {
+        if (!result.active || result.turnId !== p.turn_id) result.prompt = pendingPrompt;
+        pendingPrompt = undefined;
+        result.active = true;
+        result.turnId = typeof p.turn_id === "string" ? p.turn_id : null;
+        result.at = Date.parse(row.timestamp);
+        if (typeof p.model_context_window === "number") result.window = p.model_context_window;
+      } else if (p.type === "task_complete" || p.type === "turn_aborted") {
+        if (!p.turn_id || !result.turnId || p.turn_id === result.turnId) {
+          result.active = false;
+          result.prompt = pendingPrompt = undefined;
+          result.turnId = null;
+          result.at = Date.parse(row.timestamp);
+        }
+      } else if (p.type === "token_count") {
+        if (p.info?.total_token_usage) result.usage = p.info.total_token_usage;
+        if (typeof p.info?.last_token_usage?.total_tokens === "number") result.contextTokens = p.info.last_token_usage.total_tokens;
+        if (typeof p.info?.model_context_window === "number") result.window = p.info.model_context_window;
+      }
+      const prompt = p.type === "user_message" && typeof p.message === "string" ? p.message
+        : p.item?.type === "UserMessage" && Array.isArray(p.item.content)
+          ? p.item.content.map(part => typeof part?.text === "string" ? part.text : "").join("") : null;
+      if (prompt && lineEnd <= factsBefore) {
+        if (result.active) result.prompt = prompt;
+        else pendingPrompt = prompt;
+      }
+    }
+  }
+  result.offset = cursor.offset;
+  // An incomplete final line might be the completion. Keep it for the tail,
+  // but do not call this snapshot active until the evidence is complete.
+  if (cursor.offset !== initial.size) result.certain = false;
+  const current = await stat(path);
+  if (current.size !== initial.size || current.dev !== initial.dev || current.ino !== initial.ino) result.certain = false;
+  return result;
+}
+
+/** Repeated rollouts of a resumed thread must agree on the newest boundary. */
+export function latestCodexRecovery(candidates) {
+  if (!candidates.length || candidates.some(c => !c.snapshot.certain)) return null;
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.some(c => !Number.isFinite(c.snapshot.at))) return null;
+  const newest = Math.max(...candidates.map(c => c.snapshot.at));
+  const sameTime = candidates.filter(c => c.snapshot.at === newest);
+  if (sameTime.some(c => c.snapshot.active !== sameTime[0].snapshot.active)) return null;
+  return sameTime[sameTime.length - 1];
+}

package/src/server/codex-translate.mjs

@@ -19,6 +19,10 @@ export const codexSessionModel = new Map();   // sid -> last model string
 // session. See codexObjToPayload for why this is read and what it is NOT used
 // for; #398 for why the deck holds it at all.
 export const codexSessionApproval = new Map(); // sid -> last approval_policy string
+// sid -> the reasoning effort of the newest `turn_context`, or null when that
+// record named none (#2155). Spread onto every payload as `reasoning_effort`,
+// as approval_policy is, so the card says the effort the current turn runs at.
+export const codexSessionEffort = new Map();
 
 // ─── What a rollout record states ─────────────────────────────────────────
 // The record shapes more than one reader takes a fact off: the translation
@@ -55,6 +59,19 @@ export function taskStartedWindow(obj) {
     : null;
 }
 
+/**
+ * The reasoning effort a `turn_context` record says the turn runs at, or null
+ * when it names none (#2155). Codex writes it twice on every turn — `effort`,
+ * and again as `collaboration_mode.settings.reasoning_effort` — and the first
+ * is read first, the second only in its absence. Not a fixed set of words: the
+ * config reference lists `low` … `xhigh` and more, and says the levels depend
+ * on the model, so any short word is taken as written.
+ */
+export function turnContextEffort(pl) {
+  const effort = pl?.effort ?? pl?.collaboration_mode?.settings?.reasoning_effort;
+  return typeof effort === "string" && /^[a-z][a-z0-9_-]{0,23}$/i.test(effort) ? effort : null;
+}
+
 /** The model a `response_item` names, or null. */
 export function responseItemModel(obj) {
   const pl = obj && obj.payload;
@@ -93,6 +110,12 @@ export function codexObjToPayload(obj, sid, cwd) {
   // watcher reads. The reducer stamps it on the root beside `contextWindow`.
   const approval_policy = codexSessionApproval.get(sid);
   const base = { session_id: sid, cwd, provider: "codex", approval_policy };
+  // The effort, on the same terms — but sent as null once a turn_context named
+  // none, where approval_policy is left out: a policy that goes missing is a
+  // record that dropped a field, while a turn with no effort is a model that
+  // has none, and the chip must stop showing the last one. Before the first
+  // turn_context it is absent, which the page reads as "not known yet".
+  if (codexSessionEffort.has(sid)) base.reasoning_effort = codexSessionEffort.get(sid);
 
   // Track model from turn_context / response_item before mapping events.
   if (type === "turn_context") {
@@ -128,6 +151,7 @@ export function codexObjToPayload(obj, sid, cwd) {
     } else {
       codexSessionApproval.delete(sid);
     }
+    codexSessionEffort.set(sid, turnContextEffort(pl));
     return null;
   }
   const itemModel = responseItemModel(obj);

package/src/server/codex-watch.mjs

@@ -9,9 +9,9 @@
 // reads the ring or the SSE clients. index.mjs starts the watcher. The bodies
 // are unchanged.
 import { stat } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { PRODUCT } from "./brand.mjs";
-import { STOP, sidFromRolloutName, walkRolloutDays } from "./codex-dir.mjs";
+import { STOP, rolloutNameId, sidFromRolloutName, walkRolloutDays } from "./codex-dir.mjs";
 // What one rollout line means as a hook payload, and the shape of the header
 // record that says whose rollout it is — see codex-translate.mjs. The watcher
 // below still decides which lines are read and where each one goes.
@@ -29,6 +29,9 @@ import { maybeResolveCodexMemory } from "./session-enrichment.mjs";
 // event-pipeline.mjs's pushEvent, reached without importing it — see
 // event-sink.mjs.
 import { pushEvent } from "./event-sink.mjs";
+import { codexThreadLink } from "./codex-lineage.mjs";
+import { readCodexRecovery, latestCodexRecovery, RECOVERY_FILE_LIMIT, RECOVERY_RECENT_MS, RECOVERY_SCAN_BYTES, RECOVERY_TAIL_BYTES } from "./codex-recovery.mjs";
+import { heldPrefs, prefsRead } from "./prefs-state.mjs";
 
 // ─── Codex rollout watcher ────────────────────────────────────────────────
 // Codex CLI hooks never fire on Windows — the elevated/unelevated sandbox
@@ -219,7 +222,7 @@ async function readCodexHeader(path) {
           // workspace test below, the log election, the cwd on every event this
           // rollout produces — reads state.cwd, and this is the one place it is
           // read off disk. See canonicalCwd.
-          return { sid, cwd: await canonicalCwd(meta.cwd) };
+          return { sid, cwd: await canonicalCwd(meta.cwd), link: codexThreadLink(obj, sid, meta.cwd) };
         }
         // The other rename the scan would otherwise retry in silence: a first
         // line that is whole but is not a session_meta will never become one.
@@ -313,6 +316,7 @@ function emitCodexEvent(payload, persist, toolAuditAt) {
 function ensureCodexRoot(state, persist) {
   if (state.rootOpened) return;
   state.rootOpened = true;
+  if (state.link) emitCodexEvent({ ...state.link, cwd: state.cwd }, persist);
   if (!state.sawBeginning) return;
   emitCodexEvent({ session_id: state.sid, cwd: state.cwd, provider: "codex", hook_event_name: "SessionStart" }, persist);
 }
@@ -325,7 +329,7 @@ function ensureCodexRoot(state, persist) {
  * skipping cursor is parked at its end; or this is the first scan, and the
  * file's history is skipped.
  */
-async function openCodexCursor(path, st, now, firstRun) {
+async function openCodexCursor(path, st, now, firstRun, recover = false) {
   // New file — read the header for sid + cwd, then decide whether to
   // capture it. Skip files outside our workspace.
   const header = await readCodexHeader(path);
@@ -347,7 +351,7 @@ async function openCodexCursor(path, st, now, firstRun) {
   // UsageObserved in the file to every tab, and re-appending the lot to
   // the shared events.jsonl if this deck is the elected writer (#981).
   const fresh = !codexSeenEver.has(path);
-  const state = { offset: fresh ? 0 : st.size, sid: header.sid, cwd: header.cwd, skip: false, sawBeginning: fresh, rootOpened: false, seenAt: now };
+  const state = { offset: fresh ? 0 : st.size, sid: header.sid, cwd: header.cwd, link: header.link, skip: false, sawBeginning: fresh, rootOpened: false, seenAt: now };
   codexFileState.set(path, state);
   rememberCodexPath(path);
   if (firstRun) {
@@ -379,6 +383,16 @@ async function openCodexCursor(path, st, now, firstRun) {
     // brace (#981).
     state.offset = st.size;
     state.sawBeginning = false;
+    if (recover) {
+      try {
+        state.recovery = await readCodexRecovery(path, st, state.sid, state.cwd);
+        state.recoveryObservedAt ??= now;
+        state.recoverySize = st.size;
+        state.recoveryBootSize = st.size;
+        state.offset = state.recovery.offset;
+      } catch { state.recovery = { certain: false }; }
+      return state;
+    }
     return null;
   }
   return state;
@@ -397,6 +411,11 @@ function emitCodexLines(state, consume, persist) {
     try { obj = JSON.parse(line); } catch { continue; }
     const prevModel = codexSessionModel.get(state.sid);
     const payload = codexObjToPayload(obj, state.sid, state.cwd);
+    const link = codexThreadLink(obj, state.sid, state.cwd);
+    if (link) {
+      ensureCodexRoot(state, persist);
+      emitCodexEvent(link, persist);
+    }
     // If the model changed (turn_context/response_item), surface it.
     const nowModel = codexSessionModel.get(state.sid);
     if (nowModel && nowModel !== prevModel) {
@@ -467,7 +486,7 @@ async function openGrownOlderRollouts(now) {
     // Never `sawBeginning`, whatever this process read of the file before: the
     // lines before `was` are ones this deck has either drawn already or joined
     // too late for, and either way a SessionStart now would be a false one.
-    const state = { offset: skip ? st.size : was, sid: header.sid, cwd: header.cwd, skip, sawBeginning: false, rootOpened: false, seenAt: now, mtimeMs: st.mtimeMs };
+    const state = { offset: skip ? st.size : was, sid: header.sid, cwd: header.cwd, link: header.link, skip, sawBeginning: false, rootOpened: false, seenAt: now, mtimeMs: st.mtimeMs };
     codexFileState.set(path, state);
     rememberCodexPath(path);
     opened.push({ path, st, state });
@@ -497,7 +516,12 @@ export async function scanCodexNow() {
 
 async function scanRollouts(firstRun) {
   try {
+    if (firstRun) await prefsRead;
     const now = Date.now();
+    const recoverAtBoot = firstRun && heldPrefs.current().recoverCodexSessions !== false;
+    let recoveryBudget = RECOVERY_FILE_LIMIT;
+    let olderStatBudget = RECOVERY_FILE_LIMIT;
+    let recoveryBytes = RECOVERY_SCAN_BYTES;
     // Read at most once per scan, and only from the first rollout that actually
     // has new bytes: most ticks read nothing and must not pay a directory
     // listing for the answer to a question nothing is asking.
@@ -508,7 +532,9 @@ async function scanRollouts(firstRun) {
     // `null` rather than 0 for "never", so a clock that starts near the epoch,
     // or a faked one, cannot make boot look recent.
     const walkAll = codexOlderWalkedAt == null || Math.abs(now - codexOlderWalkedAt) >= CODEX_STATE_TTL_MS;
-    const { files, older } = await listRecentCodexRollouts(walkAll);
+    const { files: recentFiles, older } = await listRecentCodexRollouts(walkAll);
+    const recent = new Set(recentFiles);
+    const files = recoverAtBoot ? [...recentFiles, ...older] : recentFiles;
     if (walkAll) { codexOlderWalkedAt = now; catalogOlderRollouts(older); }
     const listed = new Set(files);
     // Every rollout this tick has a reason to read, with its stat and cursor:
@@ -516,14 +542,20 @@ async function scanRollouts(firstRun) {
     // rollouts found grown. One pass reads them all below.
     const due = [];
     for (const path of files) {
-      codexOlderRollouts.delete(path); // listed, so the listing's
+      if (!recent.has(path) && olderStatBudget-- <= 0) continue;
       let st;
       try { st = await stat(path); } catch { continue; }
+      const eligible = recoverAtBoot && now - st.mtimeMs <= RECOVERY_RECENT_MS;
+      if (!recent.has(path) && (!eligible || recoveryBudget <= 0)) continue;
+      codexOlderRollouts.delete(path);
       let state = codexFileState.get(path);
       if (state) state.seenAt = now;
 
       if (!state) {
-        state = await openCodexCursor(path, st, now, firstRun);
+        const cost = Math.min(st.size, RECOVERY_TAIL_BYTES);
+        const recover = eligible && recoveryBudget > 0 && cost <= recoveryBytes;
+        if (recover) { recoveryBudget--; recoveryBytes -= cost; }
+        state = await openCodexCursor(path, st, now, firstRun, recover);
         if (!state) continue;
       }
       state.mtimeMs = st.mtimeMs;
@@ -542,6 +574,78 @@ async function scanRollouts(firstRun) {
     }
     due.push(...await openGrownOlderRollouts(now));
 
+    // Retry an unstable prefix only after its file changes. The live cursor
+    // stays behind an incomplete line and never replays skipped tool history.
+    let retryBudget = 16;
+    for (const entry of due) {
+      const { state, path, st } = entry;
+      const cost = Math.min(st.size, RECOVERY_TAIL_BYTES);
+      if (!firstRun && state.recovery && !state.recovery.certain && retryBudget > 0 && cost <= recoveryBytes && st.size !== state.recoverySize) {
+        recoveryBytes -= cost;
+        retryBudget--;
+        try {
+          state.recovery = await readCodexRecovery(path, st, state.sid, state.cwd, state.recoveryBootSize);
+          state.recoveryObservedAt ??= now;
+          // Keep the live cursor: bytes appended since boot are emitted below.
+        } catch { state.recovery = { certain: false }; }
+        state.recoverySize = st.size;
+      }
+    }
+    const bySession = new Map();
+    for (const entry of due) {
+      if (!entry.state.recovery) continue;
+      const candidates = bySession.get(entry.state.sid) ?? [];
+      candidates.push({ ...entry, snapshot: entry.state.recovery });
+      bySession.set(entry.state.sid, candidates);
+    }
+    const knownPathsBySession = new Map();
+    const unknownPaths = [];
+    if (bySession.size) for (const path of new Set([...files, ...codexOlderRollouts.keys(), ...codexFileState.keys()])) {
+      const sid = rolloutNameId(basename(path));
+      if (!sid) { unknownPaths.push(path); continue; }
+      const paths = knownPathsBySession.get(sid) ?? [];
+      paths.push(path); knownPathsBySession.set(sid, paths);
+    }
+    const selected = new Map();
+    for (const [sid, candidates] of bySession) {
+      // A resumed thread's unexamined rollout may contain a newer ending.
+      // Compare exact filename ids, including historical directories, before
+      // accepting a bounded selection. Unknown names make recovery uncertain.
+      const inspected = new Set(candidates.map(c => c.path));
+      const unseen = [...(knownPathsBySession.get(sid) ?? []), ...unknownPaths].some(path => !inspected.has(path));
+      const best = unseen ? null : latestCodexRecovery(candidates);
+      if (!best || !Number.isFinite(best.snapshot.at)) continue;
+      selected.set(sid, { candidates, best });
+    }
+    const recoveredLinks = [];
+    for (const { candidates, best } of selected.values()) {
+      const { state, snapshot } = best;
+      const signature = candidates.map(c => `${c.path}:${c.snapshot.offset}`).join("|");
+      if (candidates.every(c => c.state.recoveryEmitted === signature)) continue;
+      for (const c of candidates) c.state.recoveryEmitted = signature;
+      state.rootOpened = true;
+      pushEvent({
+        hook_event_name: "CodexSessionRecovered", provider: "codex",
+        session_id: state.sid, cwd: state.cwd, snapshot_observed_at: Math.min(...candidates.map(c => c.state.recoveryObservedAt ?? now)),
+        recovery_active: snapshot.active,
+        turn_started_at: snapshot.at, prompt: snapshot.prompt, model: snapshot.model,
+        usage: snapshot.usage, context_tokens: snapshot.contextTokens,
+        model_context_window: snapshot.window, approval_policy: snapshot.approval,
+        reasoning_effort: snapshot.effort,
+      }, "codex", { replay: true, persist: false });
+      if (snapshot.active) {
+        if (state.link) recoveredLinks.push({ ...state.link, cwd: state.cwd });
+        for (const link of snapshot.links ?? []) {
+          // Historical ancestry alone cannot establish that a child is active.
+          if (selected.get(link.session_id)?.best.snapshot.active) recoveredLinks.push(link);
+        }
+      }
+      // Keep terminal candidates too: a sibling rollout still being written
+      // must be reconciled against this ending on its next stable snapshot.
+      for (const c of candidates) c.state.recoverySize = c.st.size;
+    }
+    // Snapshots precede relationships so a child placeholder cannot overtake its facts.
+    for (const link of recoveredLinks) pushEvent(link, "codex", { replay: true, persist: false });
     for (const { path, st, state } of due) {
       if (state.skip) { state.offset = st.size; continue; }
       // A cursor sitting PAST the end of the file is a different thing from

package/src/server/cswap-auto-choice.mjs

@@ -0,0 +1,296 @@
+// The deck's own step in an auto-switch tick, taken before claude-swap's
+// engine: the home account and "soonest weekly reset" rules
+// (account-choice.mjs), carried out, and what they need remembered between
+// ticks.
+//
+// NOTHING SET, NOTHING DONE. With the next account left on "most room" and no
+// home, a tick never reads anything here beyond this file and goes straight to
+// the engine — the behaviour every deck had before these rules existed.
+//
+// WHAT IS REMEMBERED, per machine, in auto-choice.json beside prefs.json:
+//
+//   next        "room" | "weekly"
+//   home        { key, email, orgUuid } or null — an identity, never a slot:
+//               slots are reused and differ between machines (lan-copies.mjs)
+//   manual      the account in use was picked by hand: the panel's Switch, the
+//               terminal, anything that was not a tick. The moves nobody needs
+//               leave it alone until it fills.
+//   goHome      a home was just set, so the next tick may take the user there
+//   lastActive  the account the last tick left the user on, which is how a
+//               switch made by hand is told from one a tick made
+//   lastMoveAt  when a tick last moved the account, for the cooldowns
+//
+// The ticks run one at a time under the store mutex; the panel's two writes
+// do not, so every write here goes through one chain.
+import { readFile, readdir, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { deckDataDir } from "./deck-home.mjs";
+import { writeFileAtomic } from "./atomic-write.mjs";
+import { backupRoot, fetchClaudeAccounts, slotNumber, switchClaudeAccount } from "./claude-accounts.mjs";
+import { readCswapConfig } from "./cswap-auto-readers.mjs";
+import { accountKey } from "./lan-copies.mjs";
+import { isProcessAlive } from "./deck-probe.mjs";
+import { chooseAccount, countedModels, NEXT_CHOICES } from "./account-choice.mjs";
+
+/** Where the choice is kept: beside prefs.json, in the deck's own data. */
+export function choicePath(home = deckDataDir()) {
+  return join(home, "auto-choice.json");
+}
+
+const text = v => (typeof v === "string" && v ? v : null);
+
+/** Whatever is on disk, as a whole and known-shaped choice. */
+export function normaliseChoice(raw) {
+  const src = raw && typeof raw === "object" ? raw : {};
+  const home = src.home && typeof src.home === "object" && text(src.home.email)
+    ? { key: accountKey(src.home.email, src.home.orgUuid), email: src.home.email, orgUuid: text(src.home.orgUuid) }
+    : null;
+  return {
+    next: NEXT_CHOICES.includes(src.next) ? src.next : "room",
+    home,
+    manual: src.manual === true,
+    goHome: home != null && src.goHome === true,
+    lastActive: text(src.lastActive),
+    lastMoveAt: Number.isFinite(src.lastMoveAt) ? src.lastMoveAt : 0,
+  };
+}
+
+// The choice as last read or written. This process is the file's only writer,
+// so after the first read a tick asks memory, not the disk — which is what
+// keeps a deck with nothing set paying nothing per tick.
+let _held = null;
+
+async function readChoice() {
+  if (_held) return _held;
+  try { _held = normaliseChoice(JSON.parse(await readFile(choicePath(), "utf8"))); } catch { _held = normaliseChoice(null); }
+  return _held;
+}
+
+let _writes = Promise.resolve();
+/** Read, change and write the choice, one change at a time. A change that
+ *  changes nothing writes nothing: most ticks only confirm where they are. */
+function updateChoice(change) {
+  const done = _writes.then(async () => {
+    const before = await readChoice();
+    const next = normaliseChoice(change(before));
+    if (JSON.stringify(next) === JSON.stringify(before)) return before;
+    const path = choicePath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFileAtomic(path, `${JSON.stringify(next)}\n`);
+    _held = next;
+    return next;
+  });
+  _writes = done.catch(() => {});
+  return done;
+}
+
+/** What the panel draws: the strategy, and whose row carries the home mark. */
+export async function choiceStatus() {
+  const c = await readChoice();
+  return { next: c.next, home: c.home ? { email: c.home.email, orgUuid: c.home.orgUuid } : null };
+}
+
+/** "room" or "weekly". Choosing is a decision about the account in use too,
+ *  so a pick made by hand no longer holds the new rule back. */
+export async function setNextChoice(value) {
+  if (!NEXT_CHOICES.includes(value)) return { ok: false, reason: "bad_value" };
+  await updateChoice(c => ({ ...c, next: value, manual: false, lastActive: null }));
+  return { ok: true };
+}
+
+/**
+ * Make the account in slot `accountNum` the home, or clear it with null.
+ * Setting one is asking to be taken there: the next tick does, once the
+ * account is usable, even from an account picked by hand.
+ */
+export async function setHomeAccount(accountNum) {
+  if (accountNum === null) {
+    await updateChoice(c => ({ ...c, home: null, goHome: false }));
+    return { ok: true };
+  }
+  const num = slotNumber(accountNum);
+  if (num == null) return { ok: false, reason: "bad_account" };
+  const roster = await fetchClaudeAccounts();
+  const row = roster?.ok ? roster.accounts?.find(a => a.num === num) : null;
+  if (!row?.email) return { ok: false, reason: "bad_account" };
+  await updateChoice(c => ({ ...c, home: { email: row.email, orgUuid: row.orgUuid ?? null }, goHome: true, manual: false }));
+  return { ok: true };
+}
+
+/** Auto-switch was just turned on: whatever happened while it was off is not
+ *  a pick to protect, so the next tick starts from the account in use. */
+export function forgetPicksByHand() {
+  return updateChoice(c => ({ ...c, manual: false, lastActive: null })).catch(() => {});
+}
+
+/**
+ * What claude-swap's engine keeps in autoswitch_state.json that a move here
+ * has to respect: when it last switched, in ms or 0 — a move the deck makes
+ * does not start the engine's cooldown, so this one keeps both — and the
+ * accounts it has quarantined, by key.
+ *
+ * A quarantine is the slot's, with the email it held: the engine drops one
+ * whose slot now holds somebody else, so it is only this account's while the
+ * emails agree. One the engine would drop for a fresh login it drops on its
+ * next run, which every tick that does not move here is.
+ */
+async function engineState(accounts) {
+  let state = null;
+  try { state = JSON.parse(await readFile(join(backupRoot(), "autoswitch_state.json"), "utf8")); } catch {}
+  const at = Number(state?.lastSwitchAt);
+  const held = state?.quarantine && typeof state.quarantine === "object" ? state.quarantine : {};
+  const sameEmail = (x, y) => typeof x === "string" && typeof y === "string" && x.trim().toLowerCase() === y.trim().toLowerCase();
+  return {
+    lastSwitchAt: Number.isFinite(at) && at > 0 ? at * 1000 : 0,
+    quarantined: new Set(accounts.filter(a => sameEmail(held[String(a.num)]?.email, a.email)).map(a => a.key)),
+  };
+}
+
+/** The accounts the decks this one is paired with say they are working on.
+ *  One login live on two machines races for every renewal (README, "One login
+ *  live in one place"), so a tick never moves onto one of them. */
+async function accountsOnOtherDecks() {
+  try {
+    const { lanEngine } = await import("./lan-deck.mjs");
+    const peers = lanEngine.status()?.peers ?? [];
+    return new Set(peers.map(p => p?.offers?.current?.key).filter(k => typeof k === "string"));
+  } catch {
+    return new Set();
+  }
+}
+
+/** The name claude-swap gives an account's `cswap run` profile after its
+ *  slot number: the email, NFC, with anything but ASCII letters, digits and
+ *  `._-` turned into `_` (claude_swap/session.py, slugify_email). */
+export function sessionSlug(email) {
+  return [...String(email ?? "").normalize("NFC")].map(ch => (/^[A-Za-z0-9._-]$/.test(ch) ? ch : "_")).join("");
+}
+
+/**
+ * The accounts a `cswap run` session is working on, by key. Such a session
+ * runs Claude Code on the account's own copy of the login; the engine never
+ * activates one of them, because two copies of one login race for every
+ * renewal. `cswap switch`, which is what a move here runs, only warns — so
+ * the deck asks the same question first.
+ *
+ * Claude Code leaves one record per running instance in the profile's
+ * `sessions/<pid>.json`; one counts while its process is running. A pid used
+ * again by something else reads as live too, which only leaves that move to
+ * the engine.
+ */
+async function accountsInCswapRun(accounts) {
+  const live = new Set();
+  for (const a of accounts) {
+    if (a.num == null || !a.email) continue;
+    const dir = join(backupRoot(), "sessions", `${a.num}-${sessionSlug(a.email)}`, "sessions");
+    let names = [];
+    try { names = (await readdir(dir)).filter(n => /^\d+\.json$/.test(n)); } catch { continue; }
+    for (const name of names) {
+      let pid = null;
+      try { pid = Number(JSON.parse(await readFile(join(dir, name), "utf8"))?.pid); } catch {}
+      if (Number.isSafeInteger(pid) && pid > 0 && isProcessAlive(pid)) { live.add(a.key); break; }
+    }
+  }
+  return live;
+}
+
+const numberOr = (v, fallback) => {
+  const n = Number(v);
+  return v != null && v !== "" && Number.isFinite(n) ? n : fallback;
+};
+
+/** One side of a move, in the shape claude-swap's own `switch` event has. */
+const refOf = a => (a ? { number: a.num, email: a.email ?? null } : null);
+
+/**
+ * Ask the two rules, and move when they say so. Under the store mutex, from
+ * the tick (cswap-auto-loop.mjs).
+ *
+ * Returns `{ result, accounts }`: `result` is a tick in the shape summarise
+ * gives the engine's — so the caches, the swap log and the notification treat
+ * the move as any other — or null for "run the engine"; `accounts` is the
+ * roster it decided on, which noteEngineTick needs to name where the engine
+ * went, and null when nothing is set.
+ */
+export async function chooseBeforeEngine({ now = Date.now() } = {}) {
+  const choice = await readChoice();
+  if (choice.next === "room" && !choice.home) return { result: null, accounts: null };
+  const roster = await fetchClaudeAccounts();
+  if (!roster?.ok || !Array.isArray(roster.accounts)) return { result: null, accounts: null };
+  const accounts = roster.accounts.map(a => ({ ...a, key: accountKey(a.email, a.orgUuid) }));
+  const active = accounts.find(a => a.active) ?? null;
+
+  const byHand = active != null && choice.lastActive != null && choice.lastActive !== active.key;
+  const manual = choice.manual || byHand;
+  const goHome = choice.goHome && active?.key !== choice.home?.key;
+  // WHAT THIS TICK LEARNED, WRITTEN OVER WHAT IS THERE NOW. The panel's writes
+  // do not wait for the store lock, so "Set as home" or a new rule can land
+  // while the awaits below run. `manual` and `goHome` were worked out from the
+  // choice as it was read, so they are only written back over that same
+  // choice — over a newer one they would undo what the person just set.
+  // Every write replaces the held object, which is what tells the two apart.
+  const keep = c => (c === choice
+    ? { ...c, manual, goHome, lastActive: active?.key ?? c.lastActive }
+    : { ...c, lastActive: active?.key ?? c.lastActive });
+
+  const cfg = (await readCswapConfig()) ?? {};
+  const threshold = numberOr(cfg["autoswitch.threshold"]?.value, 90);
+  const models = countedModels(cfg["autoswitch.model"]?.value);
+  const engine = await engineState(accounts);
+  const pick = chooseAccount({
+    accounts,
+    choice: { next: choice.next, home: choice.home?.key ?? null, manual, goHome },
+    threshold,
+    models,
+    busy: new Set([...await accountsOnOtherDecks(), ...await accountsInCswapRun(accounts)]),
+    quarantined: engine.quarantined,
+    sinceMove: now - Math.max(choice.lastMoveAt, engine.lastSwitchAt),
+    cooldownMs: numberOr(cfg["autoswitch.cooldownSeconds"]?.value, 300) * 1000,
+    optional: (cfg["autoswitch.strategy"]?.value ?? "best") === "best",
+    now,
+  });
+  if (!pick) {
+    await updateChoice(keep);
+    return { result: null, accounts };
+  }
+  const moved = await switchClaudeAccount(pick.to.num);
+  if (!moved.ok) {
+    await updateChoice(keep);
+    return { result: null, accounts };
+  }
+  // The move happened, so where it left the user and when are true whatever
+  // was set meanwhile; a home still to be gone to is the current choice's.
+  await updateChoice(c => ({
+    ...c, manual: false, goHome: (c === choice ? goHome : c.goHome) && pick.to.key !== c.home?.key,
+    lastActive: pick.to.key, lastMoveAt: now,
+  }));
+  return {
+    result: {
+      ok: true,
+      event: "switch",
+      switched: true,
+      trigger: pick.trigger,
+      reason: null,
+      detail: null,
+      from: refOf(active),
+      to: refOf(pick.to),
+      active: refOf(active),
+      threshold,
+      // What the notification reads, in the shape claude-swap's poll gives:
+      // room per account, and the windows of each by label.
+      headroom: Object.fromEntries(accounts.map(a => [String(a.num), a.headroom ?? null])),
+      windows: Object.fromEntries(accounts.map(a => [String(a.num),
+        Object.fromEntries((a.lanes ?? []).map(l => [l.label, l.pct]))])),
+      resetAt: pick.resetAt ?? null,
+    },
+    accounts,
+  };
+}
+
+/** The engine switched in a tick this step had looked at: the account it left
+ *  the user on is the tick's pick, not one made by hand. */
+export async function noteEngineTick(result, accounts) {
+  if (!accounts || !result?.switched) return;
+  const to = accounts.find(a => String(a.num) === String(result.to?.number));
+  await updateChoice(c => ({ ...c, manual: false, lastActive: to?.key ?? null, lastMoveAt: Date.now() }));
+}