agent-dag 3.20.0 → 3.21.1

package/dist/web/index.html

@@ -40,8 +40,8 @@
         document.documentElement.setAttribute("data-theme", stored === "light" ? "light" : "dark");
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-Dr-bVaHM.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DVj_M279.css">
+    <script type="module" crossorigin src="/assets/index-ByXJWM3T.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BYMVIG6f.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dag",
-  "version": "3.20.0",
+  "version": "3.21.1",
   "description": "Live deck of Claude Code and Codex agents — watch tool calls, token spend and every Claude Code subagent on one calm canvas. Run it with npx ccdeck.",
   "type": "module",
   "bin": {

package/release-notes.json

@@ -31,6 +31,12 @@
     "about a defect in the type, and the suite refuses both it and no space at",
     "all."
   ],
+  "3.21.0": [
+    {
+      "title": "🖼️ The deck explains itself in pictures",
+      "body": "🎬 First run opens an eight-picture tour instead of the changelog — who is waiting on you, the tree, a node's inside, cost and quota, this machine, accounts, local network, how to start. `Take the tour` on an empty canvas brings it back.\n\n📡 **Local network** has a guide: a card while it is off, `How it works` under an empty list, four pictures ending on `Turn it on`. A machine's row opens its own dialog — address, version and system, the logins it offers, and a name of your own for it. Setup ends on Done.\n\n🔄 The deck updates itself when nobody is looking: no tab focused, no agent mid-turn, thirty seconds quiet. The banner's `auto when idle` switch governs it.\n\n🔑 An account whose numbers were paused resumes on its own, and the panel is titled **Claude accounts** — a Codex login is not in it."
+    }
+  ],
   "3.20.0": [
     {
       "title": "🟢 The deck keeps running after you close the terminal",

package/src/server/activity.mjs

@@ -0,0 +1,52 @@
+// Whether any agent is mid-turn, from the hook stream alone.
+//
+// For the one decision the server takes on its own that must not land in the
+// middle of a turn: restarting into a new version while nobody is looking
+// (auto-update.mjs). A restart mid-turn drops the hook events fired during the
+// gap, and the canvas shows those tools in flight until the stale sweeper
+// reaps them — restart.ts states the rule for the page, which decides it from
+// its reducer's `active` state.
+//
+// With no page open there is no reducer, so this keeps the smallest version of
+// it: a session is open from the first event of a turn until the turn ends
+// (`Stop`, `SessionEnd`). SessionStart and Notification move nothing — a CLI
+// sitting at its prompt is not busy, and the idle reminder arrives after the
+// turn it is about. An open session whose last event is older than
+// OPEN_CAP_MS counts as gone rather than busy: a CLI that crashed never sends
+// its Stop, and waiting on one forever would mean never updating.
+export const OPEN_CAP_MS = 30 * 60_000;
+
+const OPENS = new Set([
+  "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "SubagentStart", "SubagentStop",
+]);
+const CLOSES = new Set(["Stop", "SessionEnd"]);
+
+export function createActivity({ openCapMs = OPEN_CAP_MS } = {}) {
+  /** session id → when its turn last produced an event */
+  const open = new Map();
+  let lastAt = 0;
+  return {
+    /** One hook payload, as pushEvent receives it. Anything else is ignored. */
+    note(raw, at) {
+      const name = raw?.hook_event_name;
+      if (!OPENS.has(name) && !CLOSES.has(name)) return;
+      if (at > lastAt) lastAt = at;
+      const id = raw?.session_id;
+      if (typeof id !== "string" || !id) return;
+      if (CLOSES.has(name)) open.delete(id);
+      else open.set(id, at);
+    },
+    /** Whether any turn is still running. */
+    busy(now) {
+      for (const [id, at] of open) {
+        if (Math.abs(now - at) > openCapMs) open.delete(id);
+        else return true;
+      }
+      return false;
+    },
+    /** How long since the last turn event of any session — Infinity before the first. */
+    quietMs(now) {
+      return lastAt ? Math.max(0, now - lastAt) : Infinity;
+    },
+  };
+}

package/src/server/auto-update.mjs

@@ -0,0 +1,79 @@
+// Updating the deck while nobody is looking at it.
+//
+// The update path had one automatic step, and it needed a page: the banner's
+// `auto when idle` restarted the deck once an install had landed, and only in a
+// tab somebody was looking at. An install itself never happened unless a person
+// pressed `Update now`, and a deck with no tab open stayed on its old code for
+// good. Since 3.20.0 the deck outlives its terminal and runs for days with no
+// tab at all, which made that the common case.
+//
+// So the server does it, at the one moment it cannot interrupt anybody: no tab
+// has focus (presence.mjs), no agent is mid-turn, and no turn has produced an
+// event for AWAY_QUIET_MS (activity.mjs). The same switch governs it — the
+// banner's `auto when idle`, kept in prefs.json as `autoUpdate` now so the
+// server can read it with no page open. A person looking at the deck still gets
+// the banner and its buttons; this is only for when they are not.
+//
+// Every effect goes through the code a press uses — startUpgrade, and the
+// launcher's restart — so an unattended update cannot do anything a person
+// could not have done from the banner. Pure rules here; index.mjs owns the
+// timer and the effects.
+
+/** Quiet before the deck may act: the page's IDLE_BEFORE_RESTART_MS, so the
+ *  two paths agree on what idle means. */
+export const AWAY_QUIET_MS = 30_000;
+
+/** How long a deck that has just started waits before acting at all. A
+ *  relaunch that came back on the version it left would otherwise try again a
+ *  minute later, and again after that; this caps any such loop at one attempt
+ *  per boot grace, under the launcher's own two-strike rule for npx
+ *  (supervisor.mjs, upgradeAttempt). */
+export const AWAY_BOOT_GRACE_MS = 5 * 60_000;
+
+/** How long the same attempt is left alone after it was made: an install that
+ *  failed, a fetch the launcher refused, a restart it could not run. A newer
+ *  version is a different attempt and is not held back by this. */
+export const AWAY_RETRY_MS = 30 * 60_000;
+
+/** How often the server asks. The gate below is answered from memory; only
+ *  when it passes does the tick read the version report, which touches disk. */
+export const AWAY_TICK_MS = 60_000;
+
+/** How long a report that found nothing newer is taken as the answer. The npm
+ *  lookup behind it is hourly anyway, and the report is not free: on Windows
+ *  upgradeBlock proves the npm prefix writable by creating a file in it, and a
+ *  deck left alone overnight would otherwise do that once a minute. */
+export const AWAY_RECHECK_MS = 5 * 60_000;
+
+/**
+ * Whether the deck may consider updating itself right now. Every input is
+ * already in memory, so this runs every tick at no cost.
+ */
+export function awayGate({
+  enabled, supervised, restarting, sinceBootMs, looking, busy, quietMs,
+  graceMs = AWAY_BOOT_GRACE_MS, quietNeedMs = AWAY_QUIET_MS,
+}) {
+  return enabled === true && supervised === true && !restarting
+    && sinceBootMs >= graceMs && !looking && !busy && quietMs >= quietNeedMs;
+}
+
+/**
+ * What to do about the version report, once the gate has passed.
+ *
+ *   restart  the newer code is already on disk (an install landed, or a
+ *            checkout was pulled) — the free half, as pickNotice says
+ *   install  `npm i -g` over a global install; the next tick restarts into it
+ *   npx      the launcher fetches the new version and hands it the port
+ *   null     nothing newer, an install already running, the same attempt
+ *            made too recently, or a copy that only a person can update
+ */
+export function awayUpdateStep({ notice, mode, installing, lastTry, now, retryMs = AWAY_RETRY_MS }) {
+  if (!notice || installing) return { act: null };
+  const target = `${notice.kind}:${notice.to}`;
+  // A clock that moved backwards counts as time elapsed, as everywhere else in
+  // the update path: a deck must not wait out a window it cannot measure.
+  if (lastTry?.target === target && now >= lastTry.at && now - lastTry.at < retryMs) return { act: null, target };
+  if (notice.kind === "restart") return { act: "restart", target };
+  if (notice.kind === "upgrade" && (mode === "install" || mode === "npx")) return { act: mode, target };
+  return { act: null, target };
+}

package/src/server/claude-accounts.mjs

@@ -504,6 +504,34 @@ export async function fetchClaudeAccounts({ force = false } = {}) {
   return mine;
 }
 
+// ── the repair nobody should have to press ───────────────────────────────────
+//
+// A `stale-copy` row — claude-swap's stored copy of the signed-in account's
+// login was rejected, while the login itself works — has exactly one repair,
+// and it asks the user nothing: re-capture the copy from the login they already
+// have (cswap-admin's recaptureActive). It was a button, `resume`, which asked a
+// person to confirm the only answer there is. So the read that finds the state
+// starts the repair, and the row carries how it is going instead of a button.
+//
+// HANDED IN, NOT IMPORTED. The repair writes a credential into claude-swap's
+// store, and this module is read by dozens of tests against fixture stores. The
+// server hands it in when it starts listening (index.mjs) and nothing else does,
+// so no test run can reach `cswap add` through a read.
+let _repairStaleCopy = null;
+
+/** Called with `{ num, email, now }` for a `stale-copy` row, and returns that
+ *  row's `repair`. Null unregisters. */
+export function repairStaleCopyWith(fn) {
+  _repairStaleCopy = typeof fn === "function" ? fn : null;
+}
+
+/** The registered repair's state for one row. A repair that throws costs the
+ *  row its state, never the read. */
+function repairFor(num, email, now) {
+  if (!_repairStaleCopy) return null;
+  try { return _repairStaleCopy({ num, email, now }) ?? null; } catch { return null; }
+}
+
 /**
  * The read itself, split out from the admission control above it so the guard is
  * readable as the four lines it is.
@@ -636,6 +664,10 @@ async function readRoster(now, gen) {
       // in as it anyway. The panel says so quietly instead of offering to log
       // them in again.
       staleCopy: trouble?.kind === "stale-copy",
+      // How the deck's own repair of that is going — `{ state: "running" }` or
+      // `{ state: "failed", reason, retryAt }` — and null on every other row.
+      // Asking is what starts it; see repairStaleCopyWith.
+      repair: trouble?.kind === "stale-copy" ? repairFor(Number(num), acct.email ?? null, now) : null,
       // Nothing has been collected for this account in half a day, and nothing
       // says why. Its own word because the two existing ones would both be
       // wrong: `error` claims a rejection that was never reported, and

package/src/server/cswap-admin.mjs

@@ -1216,26 +1216,39 @@ export function removePromptMatches(line, num) {
  * refresh token dies it quarantines the row: no further collection is
  * attempted, so the numbers freeze and every Refresh re-reads a store that
  * cannot change. #721 fixed the sentence the panel said about that state; this
- * is the button that ends it.
+ * is what ends it — started by the deck itself (autoRecapture, below) the
+ * moment a read finds the state, and still reachable from the admin route.
  *
  * `cswap add` on an account already in the store is an idempotent credential
  * refresh — registerSignedIn above says so in its own words: "No new slot means
  * the account was already managed and cswap refreshed its credentials in
- * place." It captures whatever is signed in RIGHT NOW, which for the active
- * slot is the account the row belongs to, with the working credentials the user
- * already has. Nobody is signed in or out, no browser opens, and the active
- * account does not change.
+ * place." It captures whatever is signed in RIGHT NOW, with the working
+ * credentials the user already has. Nobody is signed in or out, no browser
+ * opens, and the active account does not change.
  *
- * It only ever repairs the ACTIVE slot, because "what is signed in right now"
- * is the only thing `cswap add` can see. The panel offers it nowhere else.
+ * WHICH IS WHY IT ASKS WHO THAT IS FIRST. "Whatever is signed in" is the active
+ * slot's account only while the two agree. Somebody who signed in as another
+ * account in a terminal has made it a different one, and `cswap add` would then
+ * refresh — or add — that account instead. Behind a press that was a narrow
+ * race; with the deck starting it on its own it is the one thing that must be
+ * ruled out. So the capture runs only when the CLI's account is the active
+ * slot's, and, when the caller names an account, that one too.
  */
-export async function recaptureActive() {
+export async function recaptureActive({ expect = null } = {}) {
   return withStoreLock(async () => {
-    // Who is actually signed in, asked before and after, because `cswap add`
-    // captures the live credentials and this is the one check that the thing it
-    // captured is the thing the user meant.
+    // Who is signed in right now: `cswap add` captures THAT, whoever it is.
     const before = await currentIdentity();
     if (!before?.email) return { ok: false, reason: "not_signed_in" };
+    const who = before.email.toLowerCase();
+    const store = await readStore();
+    const activeNum = String(store.activeNum);
+    const activeEmail = String(store.emails[activeNum] ?? "").toLowerCase();
+    // One address under two organizations is two accounts to claude-swap, so a
+    // matching email in another org is still somebody else's slot.
+    const sameOrg = !before.orgId || !store.orgs[activeNum] || before.orgId === store.orgs[activeNum];
+    if (who !== activeEmail || !sameOrg || (expect != null && who !== String(expect).toLowerCase())) {
+      return { ok: false, reason: "not_active_account", email: before.email };
+    }
 
     const add = await run(await cswapBin(), ["add"], { timeout: CSWAP_TIMEOUT_MS });
     if (!add.ok) return { ok: false, reason: "add_failed", error: addFailureText(add) };
@@ -1259,6 +1272,69 @@ export async function recaptureActive() {
   });
 }
 
+// ── the same repair, without the press ──────────────────────────────────────
+
+/**
+ * How long one account is left alone after the deck re-captured it on its own.
+ *
+ * Ten minutes: past claude-swap's longest ordinary poll interval, so a capture
+ * that took has been collected before this could fire again, and one that did
+ * not — a collector that still cannot read the login — costs one `claude auth
+ * status` and one `cswap add` per ten minutes rather than one per panel poll.
+ */
+const AUTO_RECAPTURE_RETRY_MS = 10 * 60_000;
+
+/** Emails whose automatic attempt is under way. Per account rather than one
+ *  flag: after an auto-switch a second account can pause while the first's
+ *  attempt still waits on the store lock, and it must not borrow that attempt's
+ *  `running`. The lock serialises the attempts themselves. */
+const _autoRunning = new Set();
+/** Lower-cased email → the last automatic attempt: when, and why it failed. */
+const _autoTried = new Map();
+
+/**
+ * What the deck's own re-capture of a paused account should do now, given its
+ * last attempt. Pure; exported for tests.
+ *
+ *   running  an attempt is under way
+ *   start    none has been made, or the last is old enough to try again
+ *   failed   one was made inside the window and the row is still paused;
+ *            `reason` is why it failed, or null when the capture itself held
+ */
+export function autoRecaptureState(last, now, { inFlight = false, retryMs = AUTO_RECAPTURE_RETRY_MS } = {}) {
+  if (inFlight) return { state: "running" };
+  if (!last || now - last.at >= retryMs) return { state: "start" };
+  return { state: "failed", reason: last.reason ?? null, retryAt: last.at + retryMs };
+}
+
+/**
+ * Re-capture a paused account because a read found it paused — the repair the
+ * `resume` button used to wait for.
+ *
+ * Synchronous for its caller, which is building a roster row: it starts the
+ * attempt and returns the state to draw. At most one attempt per account under
+ * way and one per AUTO_RECAPTURE_RETRY_MS, always for the account the row names,
+ * which recaptureActive checks against who is signed in inside the store lock.
+ */
+export function autoRecapture({ email, now = Date.now() } = {}) {
+  const key = String(email ?? "").trim().toLowerCase();
+  if (!key) return null;
+  const next = autoRecaptureState(_autoTried.get(key), now, { inFlight: _autoRunning.has(key) });
+  if (next.state !== "start") return next;
+  _autoRunning.add(key);
+  _autoTried.set(key, { at: now, reason: null });
+  recaptureActive({ expect: key })
+    .then(
+      r => { if (!r?.ok) _autoTried.set(key, { at: now, reason: r?.reason ?? "failed" }); },
+      () => { _autoTried.set(key, { at: now, reason: "failed" }); },
+    )
+    // And the roster forgets the row it drew as `running`, so the next read —
+    // forced or not — says how the attempt went, instead of the cache or a
+    // forced read's one-minute floor holding `resuming…` over a failure.
+    .finally(() => { _autoRunning.delete(key); invalidateClaudeAccountsCache(); });
+  return { state: "running" };
+}
+
 export async function removeAccount(num) {
   const n = Number(num);
   if (!Number.isInteger(n) || n < 1 || n > 999) return { ok: false, reason: "bad_account" };

package/src/server/deck-prefs.mjs

@@ -58,6 +58,12 @@ export const prefsPath = (home = deckDataDir()) => join(prefsDir(home), "prefs.j
  */
 export const DEFAULTS = Object.freeze({
   notifications: true,
+  // Whether the deck may update itself: restart into code already on disk once
+  // it is idle, and — while nobody is looking — install a newer release and
+  // restart into that (auto-update.mjs). ON, because this is the banner's
+  // `auto when idle`, which defaulted on as a localStorage key; it moved here so
+  // the server can read it with no page open.
+  autoUpdate: true,
   // LAN sync, off until somebody turns it on. `passphrase` is the only secret
   // this file has ever held, which is why the write below now names a mode.
   lan: Object.freeze({
@@ -74,6 +80,9 @@ export const DEFAULTS = Object.freeze({
     // the dialog that turns the feature on prints them.
     autoAsk: true,
     autoAccept: true,
+    // What somebody HERE calls another deck, keyed by its fingerprint. The name
+    // a deck gives itself is its owner's to choose; this is the other half.
+    aliases: Object.freeze({}),
   }),
 });
 
@@ -90,6 +99,40 @@ export const DEFAULTS = Object.freeze({
  *  window between the two, which is exactly when a secret is in it. */
 export const PREFS_MODE = 0o600;
 
+/** The longest name somebody here may give another deck. The same order as a
+ *  deck's own name, and short enough to stay one line in the panel's column. */
+export const ALIAS_MAX = 48;
+
+/** A name somebody typed for another deck, cleaned — or "" for one with
+ *  nothing left in it, which is how an alias is taken away. Control characters
+ *  go the way cleanName sends them: this string reaches a terminal as well as a
+ *  page. */
+export function cleanAlias(raw) {
+  if (typeof raw !== "string") return "";
+  const flat = raw.replace(/\p{Cc}/gu, " ").replace(/\s+/g, " ").trim();
+  return [...flat].slice(0, ALIAS_MAX).join("").trim();
+}
+
+/** A fingerprint an alias may be kept under. Real ones are `abc-def-012-345`;
+ *  what matters here is only that a typed address's placeholder — which has a
+ *  colon in it and names no deck — can never be one, and that nothing exotic
+ *  becomes a key in an object this file writes back to disk. */
+export function isAliasKey(fp) {
+  return typeof fp === "string" && /^[A-Za-z0-9-]{1,64}$/.test(fp);
+}
+
+/** The alias map, coerced. A page writes it; a hand-edited file can hold
+ *  anything. Capped, because nothing legitimate is anywhere near it. */
+function aliasesFrom(raw) {
+  const out = {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  for (const [fp, name] of Object.entries(raw).slice(0, 256)) {
+    const clean = cleanAlias(name);
+    if (isAliasKey(fp) && clean) out[fp] = clean;
+  }
+  return out;
+}
+
 /** One LAN section, coerced. Unknown keys dropped like everything else here,
  *  and the two lists forced to arrays of strings — they arrive from a page and
  *  are then compared against account keys and dialled as addresses. */
@@ -113,7 +156,13 @@ function normaliseLan(raw) {
     // cannot be checked is worse than no entry at all.
     trusted: (Array.isArray(src.trusted) ? src.trusted : [])
       .filter(t => t && typeof t.fp === "string" && typeof t.pub === "string")
-      .map(t => ({ fp: t.fp, pub: t.pub, name: typeof t.name === "string" ? t.name : "" })),
+      .map(t => ({
+        fp: t.fp, pub: t.pub, name: typeof t.name === "string" ? t.name : "",
+        // When somebody here said yes. Absent on every pin made before this was
+        // kept, and absent is drawn as "before" rather than guessed.
+        ...(Number.isFinite(t.at) && t.at > 0 ? { at: t.at } : {}),
+      })),
+    aliases: aliasesFrom(src.aliases),
     // The port this deck listened on last time, so an address somebody typed on
     // the other machine still works after a restart. It asked the OS for a new
     // one every start, which is invisible while broadcast works and is exactly
@@ -145,6 +194,7 @@ export function normalise(raw) {
   const src = raw && typeof raw === "object" ? raw : {};
   return {
     notifications: typeof src.notifications === "boolean" ? src.notifications : DEFAULTS.notifications,
+    autoUpdate: typeof src.autoUpdate === "boolean" ? src.autoUpdate : DEFAULTS.autoUpdate,
     lan: normaliseLan(src.lan),
   };
 }