ccdeck 3.36.8 → 3.37.0

package/src/server/codex-quota.mjs

@@ -14,7 +14,7 @@ import { readFile } from "node:fs/promises";
 import { cooldownFromHeader } from "./quota-oauth.mjs";
 import { join } from "node:path";
 import { CODEX_HOME } from "./codex-dir.mjs";
-import { getCodexAuth, forceCodexRefresh, isCredentialHost } from "./codex-auth.mjs";
+import { codexCredentialFingerprint, getCodexAuth, forceCodexRefresh, isCredentialHost } from "./codex-auth.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { resetLabel } from "./reset-label.mjs";
 
@@ -28,6 +28,11 @@ const DEFAULT_BASE = "https://chatgpt.com/backend-api";
 let _cache   = null;
 let _cacheAt = 0;
 const CACHE_MS = 60_000;
+// The last reading that had lanes in it, apart from `_cache`, which also holds
+// failures. A 429 is the backend asking for a pause, not a statement that the
+// lanes read a minute ago have stopped being true, so they are what is held
+// through it — as quota.mjs keeps its own `_lastGood` for the same case.
+let _lastGood = null;
 
 // The last base URL we refused, so the refusal is said once rather than once a
 // minute for as long as the config stays that way.
@@ -280,6 +285,12 @@ const FORCE_POLL_MS = 60_000;
 // _rateLimitedUntil, which is likewise never beaten by force.
 let _rateLimitedUntil = 0;
 const COOLDOWN_MS = 5 * 60_000;
+// Set when the cooldown above is for a refused login rather than a 429: the
+// fingerprint of the credential auth.json held when it was refused. That wait
+// is about the credential, and `codex login` — the very thing the panel tells
+// the user to run — replaces it; held to the clock alone, ↻ was answered with
+// the old refusal for five minutes after the login that fixed it.
+let _refusedWith = null;
 
 // Stamped when a fetch STARTS rather than when it lands: what the floor is
 // rationing is the round trip, and one that is still in flight has already been
@@ -323,10 +334,27 @@ export function fetchCodexQuota({ force = false } = {}) {
   // that has not landed yet is one.
   if (_inflight) return _inflight;
   if (!mayFetchQuota({ now, lastFetchAt: _lastFetchAt, rateLimitedUntil: _rateLimitedUntil })) {
+    // Past the floor and inside a refused login's cooldown, the one question
+    // worth asking is whether auth.json still holds what was refused — a local
+    // read, and the wire stays quiet unless the answer is no.
+    if (_refusedWith && mayFetchQuota({ now, lastFetchAt: _lastFetchAt, rateLimitedUntil: 0 })) {
+      return track((async () => {
+        if (await codexCredentialFingerprint() === _refusedWith) return heldReading(Date.now());
+        _rateLimitedUntil = 0;
+        _refusedWith = null;
+        _lastFetchAt = Date.now();
+        return doFetchCodexQuota();
+      })());
+    }
     return Promise.resolve(heldReading(now));
   }
   _lastFetchAt = now;
-  _inflight = doFetchCodexQuota().finally(() => { _inflight = null; });
+  return track(doFetchCodexQuota());
+}
+
+/** `run`, as the one outstanding fetch every caller joins until it settles. */
+function track(run) {
+  _inflight = run.finally(() => { _inflight = null; });
   return _inflight;
 }
 
@@ -335,7 +363,12 @@ async function doFetchCodexQuota() {
   // Stamped at completion, not at entry: the two calls below can take up to
   // 17s between them, and a cache entry that is already stale on arrival
   // shortens the effective TTL for no reason.
-  const finish = (r) => { _cache = r; _cacheAt = Date.now(); return r; };
+  const finish = (r) => {
+    _cache = r;
+    _cacheAt = Date.now();
+    if (r.ok && !r.stale) _lastGood = r;
+    return r;
+  };
   const fail   = (reason) => finish({ ok: false, reason, fetchedAt: started });
   // A refusal we were told about, rather than one we inferred: back off further
   // than the ordinary floor before asking again. `retry-after` is honoured when
@@ -345,6 +378,13 @@ async function doFetchCodexQuota() {
     // defeats the cooldown a 429 exists to impose, and a day freezes this
     // poller for the life of the process.
     _rateLimitedUntil = Date.now() + cooldownFromHeader(res?.headers?.get?.("retry-after"), COOLDOWN_MS);
+    _refusedWith = null;
+  };
+  // The same wait for a login that was refused, stamped with the credential it
+  // was refused for, so a new one ends it (see fetchCodexQuota).
+  const refused = async (res) => {
+    cooldown(res);
+    _refusedWith = await codexCredentialFingerprint();
   };
 
   let auth, base, res;
@@ -388,7 +428,7 @@ async function doFetchCodexQuota() {
         // The credential is gone and only `codex login` brings it back, so
         // rotating another single-use token at the next request would burn the
         // one the CLI is still holding. Wait.
-        if (refreshed.reason === "refresh_rejected") cooldown(null);
+        if (refreshed.reason === "refresh_rejected") await refused(null);
         return fail(refreshed.reason);
       }
       auth = refreshed;
@@ -398,9 +438,19 @@ async function doFetchCodexQuota() {
     if (!res.ok) {
       // A second 401 means the token we just rotated to was rejected as well —
       // the case that turned into one rotation per request. 429 is the backend
-      // saying the same thing in the ordinary way.
-      if (res.status === 401 || res.status === 429) cooldown(res);
-      return fail(res.status === 401 ? "refresh_rejected" : `http_${res.status}`);
+      // saying the same thing in the ordinary way, and it says nothing against
+      // the lanes already read: they are held, stale, through the wait, and
+      // without any the panel is told the deck is waiting rather than to press
+      // a ↻ the cooldown refuses.
+      if (res.status === 401) {
+        await refused(res);
+        return fail("refresh_rejected");
+      }
+      if (res.status === 429) {
+        cooldown(res);
+        return _lastGood ? finish({ ..._lastGood, stale: true }) : fail("rate_limited");
+      }
+      return fail(`http_${res.status}`);
     }
   } catch (err) {
     console.error(`${PRODUCT} codex-quota: fetch failed:`, err?.message ?? err);

package/src/server/deck-home.mjs

@@ -220,6 +220,11 @@ export const TEMP_STALE_MS = 60 * 60 * 1000;
  * after the ones that are not — and it is deliberately blind to WHICH deck made
  * a file, because it cannot know: it goes by age instead, which is a fact about
  * the file rather than a guess about a pid.
+ *
+ * BUT ONLY THE DECK'S OWN NAMES. CCDECK_HOME is used as it is, so these can be
+ * somebody's own folder — a USB stick's root, a synced tools folder — and a
+ * `report.tmp` or a downloader's staging file in it is theirs. Every shape the
+ * deck's writers have ever used is in deckTemp, and nothing else is touched.
  */
 export async function sweepTempFiles({ dirs, fs, now = Date.now(), onError } = {}) {
   let removed = 0;
@@ -227,7 +232,7 @@ export async function sweepTempFiles({ dirs, fs, now = Date.now(), onError } = {
     let names;
     try { names = await fs.readdir(dir); } catch { continue; }
     for (const name of names) {
-      if (!name.endsWith(".tmp") && !name.endsWith(".migrating")) continue;
+      if (!deckTemp(name)) continue;
       const path = join(dir, name);
       try {
         const st = await fs.stat(path);
@@ -241,3 +246,20 @@ export async function sweepTempFiles({ dirs, fs, now = Date.now(), onError } = {
   }
   return removed;
 }
+
+const escaped = (name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const DECK_TEMP = [
+  // atomic-write.mjs: `<target>.agent-dag-<pid>-<n>.tmp`, and before the
+  // sequence number `<target>.agent-dag-<pid>.tmp`.
+  /\.agent-dag-\d+(?:-\d+)?\.tmp$/,
+  // The preferences' and the Browser Watch archive's own writers, from before
+  // atomic-write.mjs and since: `prefs.json.<pid>.tmp`, `state.json.<pid>.<n>.tmp`.
+  /^(?:prefs|state)\.json\.\d+(?:\.\d+)?\.tmp$/,
+  // migrateDeckFiles: `<moved file>.<pid>.migrating`.
+  new RegExp(`^(?:${MOVED.map(m => escaped(m.name)).join("|")})\\.\\d+\\.migrating$`),
+];
+
+/** Is `name` a temp file the deck itself makes? */
+export function deckTemp(name) {
+  return DECK_TEMP.some(re => re.test(name));
+}

package/src/server/deck-prefs.mjs

@@ -47,6 +47,8 @@ import { deckDataDir } from "./deck-home.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { normaliseOrigins } from "./account-origins.mjs";
 import { normaliseUsage } from "./usage-day.mjs";
+import { refSlug } from "./install-ref.mjs";
+import { normaliseRating } from "./rating.mjs";
 
 /** Set to "1" to keep the deck off the desktop whatever the stored preference
  *  says. Same sheet of switches as AGENTS_DECK_NO_DOWNLOAD and
@@ -93,13 +95,16 @@ export const DEFAULTS = Object.freeze({
   // not yet acknowledged, retried on the next start so switching off while
   // offline still ends in a deletion; `usage` is the day's tally of sessions,
   // subagents and projects, counts and days only, so a restart carries it on
-  // (usage-day.mjs); `installedAt` is when the id was made, and
+  // (usage-day.mjs); `installedAt` is when the id was made, on a first run
+  // only (an id made over an older deck's settings has none), and
   // `firstSessionAt`/`firstProvider`/`activationSent` the install's first
   // session and whether the "activated" event saying so got through — the times
-  // stay here, only a bucket leaves (activation.mjs).
+  // stay here, only a bucket leaves (activation.mjs); `rating` is the one
+  // question the deck asks about itself, answered or put off (rating.mjs).
   report: Object.freeze({
     installId: "", lastVersion: "", lastActiveDay: "", forget: "", usage: null,
     installedAt: "", firstSessionAt: "", firstProvider: "", activationSent: false,
+    rating: Object.freeze(normaliseRating(null)),
   }),
   // The accounts this deck signed in itself, and the re-sign-in prompts
   // somebody put off (#1893) — keyed by account identity, written by the deck
@@ -110,7 +115,7 @@ export const DEFAULTS = Object.freeze({
   // write below names a mode. AGENTS_DECK_NO_LAN=1 keeps a deck off the network
   // whatever this file says — see lanEnabled.
   lan: Object.freeze({
-    enabled: true, name: "", secret: "", shared: [], manual: [], trusted: [], unpaired: [], port: 0,
+    enabled: true, name: "", secret: "", shared: [], onward: [], manual: [], trusted: [], unpaired: [], port: 0,
     // WHO PAIRS WITH WHOM, WITHOUT ANYBODY PRESSING ANYTHING. Asking is on, so
     // two decks on one network find each other and send each other a request —
     // which is what a person with three of their own machines wants and had to
@@ -227,6 +232,11 @@ function normaliseLan(raw) {
     // anybody can act on and refusing to start would take the feature away.
     secret: typeof src.secret === "string" ? src.secret : "",
     shared: strings(src.shared),
+    // WHICH OF THOSE AN ARRIVAL TICKED rather than a person (#1188), so a deck
+    // the accept switch paired is not offered them — see sharedWith in
+    // lan-sync.mjs. Only ever a subset of `shared`: an untick takes the mark
+    // with it, so ticking the account again is a person's tick.
+    onward: strings(src.onward).filter(key => strings(src.shared).includes(key)),
     manual: strings(src.manual),
     // THE DECKS SOMEBODY PRESSED ACCEPT ON. The public key is the load-bearing
     // half: a fingerprint is a hash of it, so an entry without one cannot be
@@ -301,7 +311,7 @@ export function normalise(raw) {
 }
 
 /** The reporter's own state, coerced: strings empty when absent, the day's
- *  tally null until there is one, and one flag. */
+ *  tally null until there is one, one flag, and a ref only if it is one. */
 function normaliseReport(raw) {
   const src = raw && typeof raw === "object" ? raw : {};
   const text = v => (typeof v === "string" ? v : "");
@@ -315,9 +325,21 @@ function normaliseReport(raw) {
     firstSessionAt: text(src.firstSessionAt),
     firstProvider: text(src.firstProvider),
     activationSent: src.activationSent === true,
+    ref: refSlug(src.ref) ?? "",
+    selfUpdate: selfUpdateMarker(src.selfUpdate),
+    rating: normaliseRating(src.rating),
   };
 }
 
+/** The deck's note that it started an update itself (reports.mjs
+ *  noteSelfUpdate): the version it left and when, or null. */
+function selfUpdateMarker(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const from = typeof raw.from === "string" && /^[0-9A-Za-z.+_-]{1,32}$/.test(raw.from) ? raw.from : "";
+  const at = typeof raw.at === "string" && Number.isFinite(Date.parse(raw.at)) ? raw.at : "";
+  return from && at ? { from, at } : null;
+}
+
 // How a refusal to write is told — the error writePrefs throws, and the reason
 // and the detail the route hands the panel: prefs-refusal.mjs.
 export { prefsRefusalDetail, prefsWriteRefusal };
@@ -506,11 +528,15 @@ export function withManualEntry(entry) {
  * to the next machine as the deck that gave it. Only on arrival — an untick
  * afterwards is the person's answer and nothing re-ticks it, because an account
  * this deck already holds is never added again.
+ *
+ * AND MARKED AS THE ARRIVAL'S in `lan.onward`, in the same write, so a restart
+ * cannot turn it into a tick somebody made — see sharedWith in lan-sync.mjs.
  */
 export function withShared(key) {
   return prev => {
     const shared = Array.isArray(prev?.lan?.shared) ? prev.lan.shared : [];
-    return !key || shared.includes(key) ? null : { lan: { shared: [...shared, key] } };
+    const onward = Array.isArray(prev?.lan?.onward) ? prev.lan.onward : [];
+    return !key || shared.includes(key) ? null : { lan: { shared: [...shared, key], onward: [...onward, key] } };
   };
 }
 
@@ -633,14 +659,51 @@ export function publicPrefs(prefs) {
   const { report: _report, accounts: _accounts, ...p } = normalise(prefs);
   // unpaired is engine-authored state too. No page draws or edits it; keeping
   // it out also means a future whole-prefs form cannot replay a stale unpair
-  // list over a decision the engine made after the form loaded.
-  const { secret, trusted, unpaired: _unpaired, ...lan } = p.lan;
+  // list over a decision the engine made after the form loaded. `onward` is
+  // the deck's own bookkeeping of which ticks an arrival made, for the same
+  // reason.
+  const { secret, trusted, unpaired: _unpaired, onward: _onward, ...lan } = p.lan;
   return {
     ...p,
     lan: { ...lan, trusted: trusted.map(t => ({ fp: t.fp, name: t.name })) },
   };
 }
 
+/**
+ * The preferences a PAGE may write — publicPrefs's other half, and the fields
+ * `POST /api/prefs` takes. Exactly what the page and the desktop app send:
+ * the three switches, and the LAN dialog's fields.
+ *
+ * EVERYTHING ELSE IS THE DECK'S OWN, and kept as it is on disk whatever a body
+ * names. The LAN key, the decks somebody accepted or unpaired, which ticks an
+ * arrival made and the port are written by the engine and read back at the
+ * next start (see lanApplyFields in lan-deck.mjs); a name for another deck
+ * goes through its own route, which cleans it; the reports switch only through
+ * /api/reports, because turning it off asks for a deletion (#1853); the
+ * reporter's state and the accounts the deck signed in (#1893) are the deck's
+ * to record. A new preference is not writable from a page until it is named
+ * here — prefs-route-fields.test.ts lists them.
+ */
+export const PAGE_FIELDS = Object.freeze({
+  top: Object.freeze(["notifications", "tourSeen", "autoUpdate"]),
+  lan: Object.freeze([
+    "enabled", "name", "shared", "manual", "shareActive", "pairingMode",
+    "autoAsk", "autoAccept", "tailscale", "tailscaleAsk", "tailscaleAccept",
+  ]),
+});
+
+/** A page's body cut down to PAGE_FIELDS: the patch writePrefs is handed. A
+ *  field the body does not name is not in it, so it keeps its value. */
+export function pagePatch(body) {
+  const pick = (src, keys) => {
+    const from = src && typeof src === "object" && !Array.isArray(src) ? src : {};
+    return Object.fromEntries(keys.filter(k => Object.hasOwn(from, k)).map(k => [k, from[k]]));
+  };
+  const patch = pick(body, PAGE_FIELDS.top);
+  const lan = pick(body?.lan, PAGE_FIELDS.lan);
+  return Object.keys(lan).length ? { ...patch, lan } : patch;
+}
+
 /**
  * May the deck raise a desktop notification right now?
  *

package/src/server/depth-facts.mjs

@@ -0,0 +1,178 @@
+// How the deck holds up and who runs it, for the daily "active" report
+// (reports.mjs), and how an update arrived, for the "update" one.
+//
+// EVERY VALUE HERE IS A BUCKET, A CATEGORY OR A SMALL COUNT. How long this run
+// took to start, the usage day's peak memory and how many events the deck took
+// in that day leave as the bucket they fall in ("2s", "512m", "1k"); the Claude
+// and Codex plans as the plan's category ("max-20x", "plus") and nothing else
+// from the credentials they are read from; the Claude accounts and the paired
+// machines as counts, capped. The lists below are the only words that can
+// leave, and the API keeps the same ones (ccdeck-api AppEventRequest): a value
+// off a list is not sent.
+//
+// Each bucket is named by its upper edge: "2s" is over one second and up to
+// two, "512m" over 256 MB and up to 512 MB, "1k" a day of 100 to 999 events.
+
+export const LAUNCH_BUCKETS = Object.freeze(["1s", "2s", "5s", "10s", "30s", "later"]);
+const LAUNCH_EDGES_MS = [1000, 2000, 5000, 10_000, 30_000];
+
+export const MEMORY_BUCKETS = Object.freeze(["128m", "256m", "512m", "1g", "2g", "more"]);
+const MEMORY_EDGES_MB = [128, 256, 512, 1024, 2048];
+
+export const EVENT_BUCKETS = Object.freeze(["0", "100", "1k", "10k", "100k", "more"]);
+const EVENT_EDGES = [0, 99, 999, 9999, 99_999];
+
+export const CLAUDE_PLANS = Object.freeze(["free", "pro", "max", "max-5x", "max-20x", "team", "enterprise", "api"]);
+export const CODEX_PLANS = Object.freeze(["free", "go", "plus", "pro", "pro-lite", "team", "business", "enterprise", "edu", "api"]);
+
+/** How a new version arrived: the deck's own update (a press, or the update it
+ *  runs while nobody is looking), the desktop app's updater, npx fetching the
+ *  latest, npm run by hand, or a source checkout pulled. */
+export const UPDATE_VIAS = Object.freeze(["self-update", "desktop-updater", "npx", "npm", "checkout"]);
+
+/** The most accounts or paired machines a report says; past it, it says this. */
+export const COUNT_CAP = 50;
+
+/** How long the deck's own update stays the answer: a press that failed is not
+ *  credited with an update somebody made by hand days later. */
+export const SELF_UPDATE_FRESH_MS = 2 * 24 * 60 * 60 * 1000;
+
+function bucketOf(value, edges, names) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+  const i = edges.findIndex(edge => value <= edge);
+  return names[i < 0 ? names.length - 1 : i];
+}
+
+/** A run's start, in ms from its process starting to the deck listening. */
+export function launchBucket(ms) {
+  return bucketOf(ms, LAUNCH_EDGES_MS, LAUNCH_BUCKETS);
+}
+
+/** The deck's peak resident memory on a day, in MB. */
+export function memoryBucket(mb) {
+  return bucketOf(mb, MEMORY_EDGES_MB, MEMORY_BUCKETS);
+}
+
+/** The live events a day took in. */
+export function eventsBucket(n) {
+  return Number.isInteger(n) ? bucketOf(n, EVENT_EDGES, EVENT_BUCKETS) : undefined;
+}
+
+/** A whole count of zero or more, capped at COUNT_CAP; anything else, nothing. */
+export function cappedCount(n) {
+  return Number.isInteger(n) && n >= 0 ? Math.min(n, COUNT_CAP) : undefined;
+}
+
+/**
+ * The Claude plan as a category, from the two fields Claude Code keeps beside
+ * its OAuth token: `subscriptionType` ("pro", "max", "team"…) and, for Max, the
+ * `rateLimitTier` that says which of the two ("…max_5x", "…max_20x"). Nothing
+ * else in that file is looked at, and a type off the list says nothing.
+ */
+export function claudePlanToken({ subscriptionType, rateLimitTier } = {}) {
+  const type = typeof subscriptionType === "string" ? subscriptionType.trim().toLowerCase() : "";
+  if (type === "max") {
+    const tier = typeof rateLimitTier === "string" ? rateLimitTier.toLowerCase() : "";
+    return tier.includes("20x") ? "max-20x" : tier.includes("5x") ? "max-5x" : "max";
+  }
+  return ["free", "pro", "team", "enterprise"].includes(type) ? type : undefined;
+}
+
+/** The Codex plan as a category, from the `chatgpt_plan_type` claim codex-auth
+ *  reads; OpenAI writes Pro Lite three ways. */
+export function codexPlanToken(planType) {
+  const type = typeof planType === "string" ? planType.trim().toLowerCase().replace(/_/g, "-") : "";
+  const plan = type === "prolite" ? "pro-lite" : type;
+  return CODEX_PLANS.includes(plan) && plan !== "api" ? plan : undefined;
+}
+
+/**
+ * How the version this run is on arrived, for the "update" that says it.
+ *
+ * `marker` is what the deck wrote when it started an update itself
+ * (`{ from, at }`, reports.mjs noteSelfUpdate): it counts only for an update
+ * away from the version it was written on, and only while fresh. Otherwise the
+ * channel says it: the desktop app updates through its own updater, a source
+ * checkout through git, and an npm install either because npx fetched the
+ * latest or because somebody ran npm.
+ */
+export function updateVia({ marker, lastVersion, channel, npx = false, now = new Date() } = {}) {
+  const at = marker && typeof marker.at === "string" ? Date.parse(marker.at) : NaN;
+  if (marker?.from && marker.from === lastVersion && Number.isFinite(at)
+    && now.getTime() - at >= 0 && now.getTime() - at <= SELF_UPDATE_FRESH_MS) {
+    return "self-update";
+  }
+  if (channel === "desktop") return "desktop-updater";
+  if (channel === "checkout") return "checkout";
+  if (channel === "npm") return npx ? "npx" : "npm";
+  return undefined;
+}
+
+// ── the deck's own readings ──────────────────────────────────────────────────
+//
+// Read only when an "active" is about to go, never on a hot path, and each by
+// lazy import, so the reporter's module graph pulls in none of it. Each one is
+// on its own: a reading that fails or does not apply is left out, and none of
+// them can throw.
+
+/** The Claude plan, unless the boot left Claude out. Bedrock, Vertex and an
+ *  API key are "api"; a machine that keeps its login in the macOS Keychain has
+ *  no file to read, and says nothing. Bedrock, Vertex and the key are read
+ *  where the quota reader reads them — Claude Code's settings as well as this
+ *  deck's environment, "true", "yes" and "on" as well as "1" — so the plan
+ *  reported and the quota panel agree about one install. */
+async function claudePlan(env) {
+  const [{ readFile }, { claudeSignIn, credentialsPath }] = await Promise.all([import("node:fs/promises"), import("./quota-oauth.mjs")]);
+  const { cloud, apiKey } = await claudeSignIn(env);
+  if (cloud) return "api";
+  let oauth = null;
+  try {
+    oauth = JSON.parse(await readFile(credentialsPath(), "utf8"))?.claudeAiOauth ?? null;
+  } catch { /* no file, or not one we can read */ }
+  if (oauth) return claudePlanToken(oauth);
+  return apiKey ? "api" : undefined;
+}
+
+/** The Codex plan, never refreshing a token to learn it. */
+async function codexPlan() {
+  const { getCodexAuth } = await import("./codex-auth.mjs");
+  const auth = await getCodexAuth({ allowRefresh: false });
+  if (auth?.apiKeyMode) return "api";
+  return auth?.ok ? codexPlanToken(auth.planType) : undefined;
+}
+
+/** The accounts the last roster read held: no read is started for this. */
+async function accountCount() {
+  const { knownAccountCount } = await import("./claude-accounts.mjs");
+  return knownAccountCount();
+}
+
+async function quietly(read) {
+  try {
+    return await read();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What the deck says about itself on its "active": the plans, the accounts and
+ * the paired machines. `setup` is what the boot set up (activation.mjs) — the
+ * Claude plan is read unless the Claude hooks are off, the Codex plan only when
+ * the deck watches Codex — and `prefs` the held prefs, whose paired decks are
+ * the machines.
+ */
+export async function deckDepth({ setup = {}, prefs = null, env = process.env } = {}) {
+  const [claude, codex, accounts] = await Promise.all([
+    setup.claudeHooks === "off" ? undefined : quietly(() => claudePlan(env)),
+    setup.codexWatch === "on" ? quietly(codexPlan) : undefined,
+    quietly(accountCount),
+  ]);
+  const trusted = prefs?.lan?.trusted;
+  return {
+    claudePlan: claude,
+    codexPlan: codex,
+    accounts,
+    machines: Array.isArray(trusted) ? trusted.length : undefined,
+  };
+}

package/src/server/detach.mjs

@@ -20,11 +20,13 @@
 // the terminal is fed by TAILING that file rather than by holding a pipe open.
 // One sink, no handover, nothing to break when the launcher goes.
 //
-// That file is `deck.log`, and it is truncated only when no deck is registered
-// on this machine. A running deck holds an open descriptor into it, so
-// truncating underneath one would punch a hole in the log of a deck nobody
-// asked to disturb — and the case that reaches here with a deck already up is
-// the attach, which has six lines to say and no business erasing anything.
+// That file is `deck.log`, every writer appends to it, and it is started afresh
+// only when no deck is registered or booting on this machine — by moving the
+// old one aside, never by truncating it. A running deck holds an open
+// descriptor into it, so truncating underneath one would punch a hole in the
+// log of a deck nobody asked to disturb — and the case that reaches here with a
+// deck already up is the attach, which has six lines to say and no business
+// erasing anything.
 //
 // ONE PLATFORM WHERE THIS IS NOT ENOUGH, and it is worth knowing before someone
 // reports it as a bug. Windows OpenSSH puts a session's processes in a job
@@ -45,7 +47,7 @@
 // deck was started from, which is what makes `--logs` worth reading, and the
 // launcher passes nothing at all when it is not itself a terminal.
 import { spawn } from "node:child_process";
-import { closeSync, mkdirSync, openSync, readSync, statSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readSync, renameSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { isOneShot } from "./args.mjs";
 
@@ -60,16 +62,23 @@ export const DETACHED_ENV = "AGENTS_DECK_DETACHED";
 export const DECK_LOG = "deck.log";
 
 /**
- * Truncate this log, or append to it?
+ * Start this log afresh, or carry on in it?
  *
- * Truncated when nothing is registered, which is the ordinary start and the
- * only moment the previous contents are certainly nobody's. Appended otherwise,
- * because a registered deck is holding an open descriptor at some offset into
- * this very file: truncating under it does not make it start again at zero, it
- * makes its next write land past the end and leave a hole.
+ * Afresh when nothing is registered and no deck holds the boot lock, which is
+ * the ordinary start and the only moment the previous contents are certainly
+ * nobody's. A deck in its boot window is not registered yet — it registers up
+ * to eight seconds later (boot-lock.mjs) — so two starts inside one window both
+ * read an empty registry; the lock is what the second one can see.
+ *
+ * AFRESH IS NEVER A TRUNCATION. A deck holds an open descriptor into this file,
+ * and truncating under it does not make it start again at zero: its next write
+ * lands past the end and leaves a hole. So the old log is moved aside to
+ * `deck.log.1` — a deck still writing to it keeps writing there — and a new
+ * file is opened. And every writer appends (see detachAndWatch), so nobody's
+ * offset can fall behind anybody else's.
  */
-export function logMode(liveCount) {
-  return liveCount > 0 ? "a" : "w";
+export function startsFresh(liveCount, booting = false) {
+  return liveCount === 0 && !booting;
 }
 
 /**
@@ -152,31 +161,43 @@ export function noConsoleOptions({ detached = false, platform = process.platform
  * An npx run has no `ccdeck` on PATH — that is the whole point of npx — so
  * telling one to run `ccdeck --stop` is telling them to run something that does
  * not exist on their machine. `invokedAs` already answers which of the three
- * published names was typed; this only decides whether `npx ` goes in front.
+ * published names was typed; this only decides which runner goes in front.
+ * `runner` is install-layout's oneOffRunner — "npx", "pnpm dlx", "bunx" or
+ * "yarn dlx", none of which leaves the command on PATH either — and `npx` the
+ * older spelling of the first.
  */
-export function stopCommand({ npx = false, invokedAs = null, product = "ccdeck" } = {}) {
+export function stopCommand({ runner = null, npx = false, invokedAs = null, product = "ccdeck" } = {}) {
+  return command("--stop", { runner, npx, invokedAs, product });
+}
+
+/** `<runner> <name> <flag>`, or `<name> <flag>` for a copy that stays. */
+function command(flag, { runner = null, npx = false, invokedAs = null, product = "ccdeck" }) {
+  const via = runner || (npx ? "npx" : null);
   const name = invokedAs || product;
-  return npx ? `npx ${name} --stop` : `${name} --stop`;
+  return via ? `${via} ${name} ${flag}` : `${name} ${flag}`;
 }
 
 /**
  * What the terminal is left with once the deck has gone to the background: the
- * command that ends it, and — for an npx run — the one thing it cannot have.
+ * command that ends it, and — for a one-off run — the one thing it cannot have.
  *
- * THE ONE THING AN NPX RUN CANNOT HAVE, said where it is missing. A login item
- * must name a path that will still be there tomorrow, and npx runs out of a
- * cache npm deletes whenever it likes — so an npx deck runs in the background
- * and cannot come back after a reboot. One line, no disk written, offered
- * rather than done: `npx` means "run without installing", and a tool that
- * installs itself anyway is the one people uninstall.
+ * THE ONE THING A ONE-OFF RUN CANNOT HAVE, said where it is missing. A login
+ * item must name a path that will still be there tomorrow, and npx, pnpm dlx,
+ * bunx and yarn dlx all run out of a cache or a temp folder that is deleted
+ * whenever its owner likes — so such a deck runs in the background and cannot
+ * come back after a reboot. One line, no disk written, offered rather than
+ * done: `npx` means "run without installing", and a tool that installs itself
+ * anyway is the one people uninstall. Through the same runner, like the stop
+ * command: neither is on PATH after a one-off run.
  *
  * `tone` is a palette and `g` a glyph tier, both from term.mjs, so a pipe gets
  * no escapes and a console without the em dash gets its stand-in.
  */
-export function backgroundNote({ npx = false, invokedAs = null, product = "ccdeck", tone, g }) {
-  const stop = stopCommand({ npx, invokedAs, product });
-  const offer = npx
-    ? `     ${tone.muted}\`${invokedAs ?? product} --install\` also starts it at login${tone.reset}\n`
+export function backgroundNote({ runner = null, npx = false, invokedAs = null, product = "ccdeck", tone, g }) {
+  const how = { runner, npx, invokedAs, product };
+  const stop = stopCommand(how);
+  const offer = runner || npx
+    ? `     ${tone.muted}\`${command("--install", how)}\` also starts it at login${tone.reset}\n`
     : "";
   return `  ${tone.muted}${g.dash}  running in the background ${g.bullet} \`${stop}\` ends it${tone.reset}\n${offer}\n`;
 }
@@ -241,6 +262,7 @@ export async function detachAndWatch({
   argv = [],
   logDir,
   liveCount = 0,
+  booting = false,
   env = process.env,
   out = process.stdout,
   isTTY = false,
@@ -254,14 +276,20 @@ export async function detachAndWatch({
   const path = join(logDir, DECK_LOG);
   try { mkdirSync(logDir, { recursive: true }); } catch { /* reported by the open below */ }
 
-  const mode = logMode(liveCount);
-  // Where the terminal starts reading. An append leaves the previous deck's log
-  // alone and shows only what this child writes.
-  const from = mode === "a" ? (() => { try { return statSync(path).size; } catch { return 0; } })() : 0;
+  if (startsFresh(liveCount, booting)) {
+    try { renameSync(path, `${path}.1`); } catch { /* no log yet, or held where it cannot move: carry on in it */ }
+  }
+  // Where the terminal starts reading: the end of what is there. An attach
+  // leaves the running deck's log alone and shows only what this child writes.
+  const from = (() => { try { return statSync(path).size; } catch { return 0; } })();
 
   let fd;
   try {
-    fd = openSync(path, mode, 0o600);
+    // "a", O_APPEND, for every start. The supervisor and worker share this
+    // descriptor, an attach appends its own lines to the same file, and a login
+    // item's service manager appends to it too; opened at an offset of its own,
+    // the running deck's next write landed over whatever came after it.
+    fd = openSync(path, "a", 0o600);
   } catch (err) {
     // A log we cannot open is not a reason to refuse to start. Say so once and
     // run in the foreground, which is exactly what every version before this