tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/tui/chrome/updater.js

@@ -0,0 +1,651 @@
+/**
+ * The chrome status-bar updater — ONE background loop that keeps every adopted
+ * session's status var fresh.
+ *
+ * WHY a single updater (vs. the old per-session `#()`): the first chrome
+ * pointed each adopted session's `status-format[1]` at
+ * `#(tmux-ide statusline …)`, which tmux re-ran every `status-interval` — a
+ * full node boot + fleet scan PER adopted session PER tick (~0.35s each). And
+ * because each `#()` invocation was stateless it could never produce the
+ * cross-tick `done` status (working→idle needs history).
+ *
+ * This module computes the fleet ONCE per tick behind a PERSISTENT
+ * {@link createStatusTracker} (so working→idle surfaces as `done`), then writes
+ * a per-session `@tmux_ide_status` user option for each adopted session
+ * (per-session so each keeps its own active-highlight). `adoptSession` points
+ * `status-format[1]` at a bare `#{@tmux_ide_status}` read — near-free, no spawn.
+ *
+ * The loop is HOSTED IN TMUX: `adoptSession` spins up a hidden `_tmux-ide-chrome`
+ * session running `tmux-ide chrome-updater`, and unadopting the last session
+ * kills it. `runUpdaterTick` is factored to take injected io so it's unit-tested
+ * without a live tmux; `adoptedSessionsFrom` is a pure parser.
+ */
+import { hasSession, isProcessAlive, runTmux } from "@tmux-ide/tmux-bridge";
+import { ADOPTED_OPTION, CHIP_OPTION, PANE_CHROME_BORDER_FORMAT, UPDATER_SESSION, updaterSpawnArgv, } from "./front-door.js";
+import { DEFAULT_THEME, getAppConfig } from "../../lib/app-config.js";
+import { maybeCheckForUpdate, markUpdateNotified, } from "../../lib/update-check.js";
+import { createStatusTracker } from "../detect/classify.js";
+import { createSessionIdCapturer } from "../detect/session-id.js";
+import { listTeamProjects } from "../team/projects.js";
+import { paneChip } from "./chip.js";
+import { appendEvents, diffFleet } from "./events.js";
+import { decideNotifications, decideTtyWrites, enabledStates, inQuietHours, listAttachedClients, playPingSound, readAppFocus, readNotificationPrefs, sendSystemNotification, sendToasts, soundEligible, writeTtys, } from "./notify.js";
+import { loadLastNotified, saveLastNotified } from "./notify-state.js";
+import { collectFleetSnapshot, createSnapshotter, readSnapshot, writeSnapshot, } from "./snapshot.js";
+import { buildStatusline } from "./statusline.js";
+/** Per-session user option holding the pre-rendered status-bar string. */
+export const STATUS_OPTION = "@tmux_ide_status";
+// The adopted marker, the updater session name, and their argv builders live
+// in the LEAF module front-door.ts (the unified app imports them without
+// pulling this module's fleet-scan graph); re-exported here for the chrome.
+export { ADOPTED_OPTION, CHIP_OPTION, UPDATER_SESSION, updaterProbeArgv, updaterSpawnArgv, } from "./front-door.js";
+/** Server option holding the running updater's pid (a lightweight single-owner guard). */
+export const UPDATER_PID_OPTION = "@tmux_ide_updater_pid";
+/** Default tick cadence — overridable via `updater.tickMs` in the app config. */
+export const TICK_MS = 2000;
+/**
+ * PURE — parse `list-sessions -F '#{session_name}\t#{@tmux_ide_adopted}'` output
+ * into the list of adopted session names. A session is adopted when its marker
+ * field is exactly `"1"` (sessions without the option render an empty field —
+ * verified on tmux 3.6, where user options ARE readable in list-sessions
+ * formats).
+ */
+export function adoptedSessionsFrom(lines) {
+    const out = [];
+    for (const line of lines) {
+        const [name = "", flag = ""] = line.split("\t");
+        if (name && flag === "1")
+            out.push(name);
+    }
+    return out;
+}
+/** Enumerate adopted sessions from the live tmux server. Never throws. */
+export function listAdoptedSessions() {
+    try {
+        const raw = runTmux(["list-sessions", "-F", `#{session_name}\t#{${ADOPTED_OPTION}}`])
+            .toString()
+            .trim();
+        return raw ? adoptedSessionsFrom(raw.split("\n")) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parse the single fleet-wide window probe into windows whose panel-chrome row
+ * is missing. Kept pure so the per-tick enforcement has no hidden grammar.
+ */
+export function paneChromeWindowTargetsFrom(lines, adoptedSessions) {
+    const adopted = new Set(adoptedSessions);
+    const targets = [];
+    for (const line of lines) {
+        const [session = "", windowId = "", status = ""] = line.split("\t");
+        if (adopted.has(session) && /^@\d+$/u.test(windowId) && status !== "top") {
+            targets.push(windowId);
+        }
+    }
+    return targets;
+}
+/**
+ * Parse every valid window identity belonging to the selected sessions. Used
+ * when removing chrome, where already-top windows must be restored too.
+ */
+export function paneChromeWindowIdsFrom(lines, sessions) {
+    const selected = new Set(sessions);
+    const targets = [];
+    for (const line of lines) {
+        const [session = "", windowId = ""] = line.split("\t");
+        if (selected.has(session) && /^@\d+$/u.test(windowId))
+            targets.push(windowId);
+    }
+    return targets;
+}
+function listPaneChromeWindows() {
+    const raw = runTmux([
+        "list-windows",
+        "-a",
+        "-F",
+        "#{session_name}\t#{window_id}\t#{pane-border-status}",
+    ])
+        .toString()
+        .trim();
+    return raw ? raw.split("\n") : [];
+}
+/**
+ * Keep every window of every adopted session on the shared top-border chrome
+ * contract. New tmux windows start with their own window options, so setting
+ * only the session's current window during adoption is insufficient.
+ */
+export function enforcePaneChromeWindows(adoptedSessions) {
+    if (adoptedSessions.length === 0)
+        return;
+    const targets = paneChromeWindowTargetsFrom(listPaneChromeWindows(), adoptedSessions);
+    for (const windowId of targets) {
+        try {
+            runTmux(["set-option", "-w", "-t", windowId, "pane-border-status", "top"]);
+            runTmux([
+                "set-option",
+                "-w",
+                "-t",
+                windowId,
+                "pane-border-format",
+                PANE_CHROME_BORDER_FORMAT,
+            ]);
+        }
+        catch {
+            // A window can disappear between the fleet probe and these writes. The
+            // next tick repairs survivors; a closing window needs no repair.
+        }
+    }
+}
+/** Restore inherited pane-border options on every window being unadopted. */
+export function clearPaneChromeWindows(sessions) {
+    if (sessions.length === 0)
+        return;
+    const targets = paneChromeWindowIdsFrom(listPaneChromeWindows(), sessions);
+    for (const windowId of targets) {
+        try {
+            runTmux(["set-option", "-uw", "-t", windowId, "pane-border-status"]);
+            runTmux(["set-option", "-uw", "-t", windowId, "pane-border-format"]);
+        }
+        catch {
+            // Same close-race as enforcement; disappearing windows are already clean.
+        }
+    }
+}
+/** Write a session's pre-rendered status var. */
+function writeSessionStatus(session, value) {
+    runTmux(["set-option", "-t", session, STATUS_OPTION, value]);
+}
+/** Write a pane's pre-rendered chip var (empty string clears it → title fallback). */
+function writePaneChip(paneId, value) {
+    runTmux(["set-option", "-p", "-t", paneId, CHIP_OPTION, value]);
+}
+/**
+ * PURE — the reserved dock segment for an available update: the clickable
+ * `⬆ v<latest>` chip (accent-colored, wrapped in a `user|update` mouse range so a
+ * click floats the update popup — see {@link ./statusline.ts statusClickBindCommand}).
+ * Empty string when there's nothing to offer, so it takes no space on the bar.
+ */
+export function updateSegment(status, theme) {
+    if (!status.updateAvailable || !status.latest)
+        return "";
+    return `#[range=user|update]#[fg=${theme.accent}]⬆ v${status.latest}#[default]#[norange]`;
+}
+/** Flatten the project view to a flat per-session status list for {@link diffFleet}.
+ *  Exported: the control server's event tick diffs the same projection. */
+export function fleetStatuses(projects) {
+    return projects.flatMap((p) => p.sessions.map((s) => ({ name: s.name, status: s.status })));
+}
+/**
+ * One tick: if any session is adopted, compute the fleet ONCE and write each
+ * adopted session its own {@link buildStatusline} (its name flagged active so
+ * the per-session highlight is correct). PURE given its deps — no tmux, no
+ * fleet scan when nothing is adopted.
+ *
+ * When `prevState`/`appendEvents` are wired, it also detects state TRANSITIONS
+ * across the whole fleet (not just adopted sessions) and appends them to the
+ * event log — the updater is the one process that sees every tick, so it's the
+ * natural place to emit history.
+ */
+export function runUpdaterTick(deps) {
+    const adopted = deps.listAdopted();
+    if (adopted.length === 0)
+        return;
+    deps.enforcePaneChrome?.(adopted);
+    const theme = deps.theme ?? DEFAULT_THEME;
+    // Collect per-pane detail during the fleet scan so chips need no second pass.
+    const panes = [];
+    const projects = deps.computeProjects((pane) => panes.push(pane));
+    // The dock-first update surface: a cheap cache read that also kicks off the
+    // throttled background registry refresh. Threads the "⬆ v<latest>" chip into
+    // every bar this tick when an update is pending.
+    const update = deps.maybeCheckForUpdate?.();
+    const extra = update ? updateSegment(update, theme) : "";
+    for (const session of adopted) {
+        deps.writeStatus(session, buildStatusline(projects, session, 12, theme, extra));
+    }
+    writeChips(deps, adopted, panes, theme);
+    deps.captureSessionIds?.(panes);
+    if (update?.updateAvailable && update.latest)
+        dispatchUpdateToast(deps, update.latest);
+    if (deps.prevState && deps.appendEvents) {
+        const { events, state } = diffFleet(deps.prevState, fleetStatuses(projects));
+        deps.prevState.clear();
+        for (const [name, status] of state)
+            deps.prevState.set(name, status);
+        if (events.length > 0)
+            deps.appendEvents(events);
+    }
+    // Notifications ride PANE transitions (M25.1), not the session rollup — a
+    // second agent blocking in an already-blocked session is invisible at the
+    // session level but is exactly who the user needs to hear about. Due delayed
+    // pings re-verify against THIS tick's pane states before the diff mutates
+    // anything (M25.2).
+    if (deps.prevPaneState) {
+        firePendingOsPings(deps, panes);
+        const events = diffPaneTransitions(deps.prevPaneState, panes, deps.locatePane);
+        if (events.length > 0)
+            dispatchNotifications(deps, events);
+    }
+}
+/**
+ * Write each adopted session's panes their agent chip — but only when the chip
+ * CHANGED since last tick (per-pane cache), so a steady fleet issues zero
+ * set-options. No-op unless both `writeChip` and `chipCache` are wired. Panes of
+ * non-adopted (user, un-adopted) sessions are skipped: we only paint borders on
+ * sessions we've adopted.
+ */
+function writeChips(deps, adopted, panes, theme) {
+    const { writeChip, chipCache } = deps;
+    if (!writeChip || !chipCache)
+        return;
+    const adoptedSet = new Set(adopted);
+    for (const pane of panes) {
+        if (!adoptedSet.has(pane.sessionName))
+            continue;
+        const chip = paneChip(pane.agent, pane.status, theme);
+        if (chipCache.get(pane.paneId) === chip)
+            continue;
+        chipCache.set(pane.paneId, chip);
+        writeChip(pane.paneId, chip);
+    }
+}
+/**
+ * PURE (given `locate`) — diff the previous per-pane states against this
+ * tick's panes into ready-to-ping {@link NotifyEvent}s: each carries its
+ * `paneId` (the debounce/visibility key), `windowIndex` (window-granular toast
+ * suppression), the pane's resolved `agent`, and — only for a notifiable
+ * blocked/done transition that isn't first-sight — the human `location`
+ * (`locate` is a live tmux call, so it only fires for a potential ping).
+ * `prev` is mutated in place to the fresh state, like the session-level
+ * `prevState`; a pane that vanished simply drops out. First sight of a pane
+ * emits `from: null`, which {@link decideNotifications} ignores — that's the
+ * restart/first-tick grace.
+ */
+export function diffPaneTransitions(prev, panes, locate) {
+    const events = [];
+    const next = new Map();
+    for (const pane of panes) {
+        const before = prev.has(pane.paneId) ? prev.get(pane.paneId) : null;
+        next.set(pane.paneId, pane.status);
+        if (before === pane.status)
+            continue;
+        const notifiable = before !== null && (pane.status === "blocked" || pane.status === "done");
+        events.push({
+            session: pane.sessionName,
+            from: before,
+            to: pane.status,
+            paneId: pane.paneId,
+            windowIndex: pane.windowIndex,
+            agent: pane.agent,
+            location: notifiable && locate ? locate(pane.paneId) : pane.sessionName,
+        });
+    }
+    prev.clear();
+    for (const [paneId, status] of next)
+        prev.set(paneId, status);
+    return events;
+}
+/** PURE — whether ANY channel beyond the master switch is on; an all-off
+ *  config costs the tick nothing. */
+function anyChannelOn(prefs) {
+    return prefs.toast || prefs.macos || prefs.terminal || prefs.sound !== "none";
+}
+/**
+ * Ping the user about who needs them from this tick's transitions. Only runs
+ * when the notification deps are wired, notifications are `enabled`, AND at
+ * least one channel is on. `lastNotified` is mutated in place so the debounce
+ * (the flap guard) persists across ticks. The in-app toast fires IMMEDIATELY
+ * (cheap, low-annoyance); the OS-LEVEL channels (banner / terminal escape /
+ * sound / BEL) either fire now (`delaySeconds` 0 or no queue wired) or queue
+ * onto `pendingPings` for the delayed re-verify (M25.2). The debounce stamp
+ * lands at DECIDE time either way — a flap that later cancels its OS ping
+ * already toasted, so it spent its debounce slot honestly.
+ */
+function dispatchNotifications(deps, events) {
+    const { listClients, lastNotified, now, prefs, sendToasts: toast } = deps;
+    if (!listClients || !lastNotified || !now || !prefs)
+        return;
+    if (!prefs.enabled)
+        return;
+    if (!anyChannelOn(prefs))
+        return;
+    const nowMs = now();
+    const decision = decideNotifications(events, listClients(), lastNotified, nowMs, enabledStates(prefs), deps.appFocus?.() ?? null);
+    lastNotified.clear();
+    for (const [key, ts] of decision.nextLastNotified)
+        lastNotified.set(key, ts);
+    // A system entry exists for every event that actually fired (stamped the
+    // debounce map), so this is exactly "the map changed — persist it".
+    if (decision.system.length > 0)
+        deps.persistNotified?.(lastNotified);
+    if (prefs.toast && toast)
+        toast(decision.toasts);
+    if (decision.system.length === 0)
+        return;
+    const delayMs = prefs.delaySeconds * 1000;
+    if (delayMs > 0 && deps.pendingPings) {
+        for (const n of decision.system)
+            deps.pendingPings.push({ ...n, dueAtMs: nowMs + delayMs });
+    }
+    else {
+        fireOsChannels(deps, prefs, decision.system, nowMs);
+    }
+}
+/**
+ * Fire the DUE queued OS pings whose transition still holds (M25.2). The
+ * re-verify is tick-native: this tick's fresh pane scan is the source of truth
+ * — a pane that flapped out of the notified state, vanished, or is now on the
+ * unified app's screen ({@link AppFocus} — the user got there on their own)
+ * fires nothing and is dropped. Prefs are the CURRENT tick's fresh read, so a
+ * config change during the delay is honored. Runs before this tick's diff so
+ * "the next tick's pane states" is literally what confirms each ping.
+ */
+function firePendingOsPings(deps, panes) {
+    const { pendingPings: pending, now, prefs } = deps;
+    if (!pending || pending.length === 0 || !now || !prefs)
+        return;
+    const nowMs = now();
+    const due = [];
+    const keep = [];
+    for (const p of pending)
+        (p.dueAtMs <= nowMs ? due : keep).push(p);
+    if (due.length === 0)
+        return;
+    pending.length = 0;
+    for (const p of keep)
+        pending.push(p);
+    if (!prefs.enabled)
+        return;
+    const statusByPane = new Map(panes.map((p) => [p.paneId, p.status]));
+    const focus = deps.appFocus?.() ?? null;
+    const confirmed = due.filter((p) => {
+        // A pane-less ping (session-granular caller) can't be re-verified — fire it.
+        if (p.paneId !== null && statusByPane.get(p.paneId) !== p.state)
+            return false;
+        if (focus?.attached && p.paneId !== null && focus.panes.includes(p.paneId))
+            return false;
+        return true;
+    });
+    fireOsChannels(deps, prefs, confirmed, nowMs);
+}
+/**
+ * The OS-LEVEL fan-out (M25.2): system banner, terminal escapes + BEL to
+ * eligible client ttys, and the ping sound (at most ONE sound per batch — a
+ * fleet-wide flap must not ring a carillon). ALL of it is gated on quiet hours
+ * — inside the window nothing OS-level fires (the in-app toast and the event
+ * log have already surfaced the transition, so history stays honest).
+ */
+function fireOsChannels(deps, prefs, entries, nowMs) {
+    if (entries.length === 0)
+        return;
+    if (inQuietHours(new Date(nowMs), prefs.quietHours))
+        return;
+    if (prefs.macos && deps.sendSystem) {
+        for (const n of entries)
+            deps.sendSystem(n);
+    }
+    if ((prefs.terminal || prefs.sound !== "none") && deps.sendTerminal && deps.listClients) {
+        const clients = deps.listClients();
+        const writes = entries.flatMap((n) => decideTtyWrites(n, clients, prefs));
+        if (writes.length > 0)
+            deps.sendTerminal(writes);
+    }
+    if (deps.playSound && entries.some((n) => soundEligible(n.state, prefs.sound))) {
+        deps.playSound();
+    }
+}
+/**
+ * io — resolve a pane id to `session:window.pane` (e.g. `myproj:1.2`) for the
+ * ping text. Best-effort: a gone pane / failed call degrades to the raw pane id.
+ */
+export function paneLocation(paneId) {
+    try {
+        const raw = runTmux([
+            "display-message",
+            "-p",
+            "-t",
+            paneId,
+            "#{session_name}:#{window_index}.#{pane_index}",
+        ])
+            .toString()
+            .trim();
+        return raw || paneId;
+    }
+    catch {
+        return paneId;
+    }
+}
+/**
+ * Toast every attached client ONCE that an update is out — "run: tmux-ide
+ * update". The one-time guarantee lives in {@link markUpdateNotified} (persisted
+ * in the update cache, so it survives updater restarts, unlike the fleet
+ * notification's in-memory debounce). Honors the `toast` prefs kill-switch and
+ * no-ops unless the toast deps are wired.
+ */
+function dispatchUpdateToast(deps, version) {
+    const { markUpdateNotified: mark, listClients, sendToasts: toast, prefs } = deps;
+    if (!mark || !listClients || !toast)
+        return;
+    if (prefs && !prefs.toast)
+        return;
+    if (!mark(version))
+        return; // already toasted this version
+    const message = `⬆ tmux-ide v${version} available — run: tmux-ide update`;
+    toast(listClients().map((c) => ({ client: c.client, message })));
+}
+/**
+ * Seed a single session's status var NOW (a one-off fleet scan). Called by
+ * `adoptSession` so a freshly-adopted bar is never blank while it waits for the
+ * background loop's next tick. Best-effort — a failure just defers to the loop.
+ */
+export function seedSessionStatus(session) {
+    try {
+        const projects = listTeamProjects(createStatusTracker());
+        writeSessionStatus(session, buildStatusline(projects, session, 12, getAppConfig().theme));
+    }
+    catch {
+        // leave it to the updater's next tick
+    }
+}
+/** Whether the updater session is already up. */
+export function updaterRunning() {
+    try {
+        return hasSession(UPDATER_SESSION);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure the background updater is running: if the `_tmux-ide-chrome` session
+ * isn't up, start it detached running `tmux-ide chrome-updater`. `_`-internal
+ * so it's hidden from the bar/switcher. Best-effort — a chrome failure must
+ * never break adopt/launch.
+ */
+export function startUpdaterIfNeeded() {
+    try {
+        if (updaterRunning())
+            return;
+        runTmux(updaterSpawnArgv());
+    }
+    catch {
+        // best-effort — the bar still works via the last-written var
+    }
+}
+/** Kill the updater session (called when the last adopted session is unadopted). */
+export function stopUpdater() {
+    try {
+        if (updaterRunning())
+            runTmux(["kill-session", "-t", UPDATER_SESSION]);
+    }
+    catch {
+        // already gone — nothing to stop
+    }
+}
+/** Read the pid the current updater owner recorded, or null when unset/garbage. */
+function readUpdaterPid() {
+    try {
+        const raw = runTmux(["show-option", "-s", "-v", UPDATER_PID_OPTION]).toString().trim();
+        const pid = Number(raw);
+        return raw && Number.isInteger(pid) ? pid : null;
+    }
+    catch {
+        // option never set (unset server user-options error out) — no owner
+        return null;
+    }
+}
+/**
+ * Claim single-ownership of the loop. Returns false when another LIVE updater
+ * already holds the pid option (so a stray manual `chrome-updater` exits
+ * cleanly instead of double-writing). A dead/stale pid is reclaimed.
+ */
+function claimUpdater() {
+    const existing = readUpdaterPid();
+    if (existing !== null && existing !== process.pid && isProcessAlive(existing))
+        return false;
+    try {
+        runTmux(["set-option", "-s", UPDATER_PID_OPTION, String(process.pid)]);
+    }
+    catch {
+        // if we can't record the pid, still run — the session-level guard suffices
+    }
+    return true;
+}
+/** Release ownership on shutdown (only if we still hold it). */
+function releaseUpdater() {
+    try {
+        if (readUpdaterPid() === process.pid)
+            runTmux(["set-option", "-s", "-u", UPDATER_PID_OPTION]);
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Exit the loop after this many CONSECUTIVE ticks with the tmux server gone —
+ *  a dead server means nothing to watch and nobody to ping, and an immortal
+ *  interval would zombie (two were found live before M25.1). */
+export const UPDATER_UNREACHABLE_EXIT_TICKS = 5;
+/** PURE — a consecutive-failure counter: feed it each tick's reachability;
+ *  it answers "give up now?" after `threshold` misses in a row (any success
+ *  resets the run). */
+export function createUnreachableCounter(threshold = UPDATER_UNREACHABLE_EXIT_TICKS) {
+    let consecutive = 0;
+    return (reachable) => {
+        consecutive = reachable ? 0 : consecutive + 1;
+        return consecutive >= threshold;
+    };
+}
+/** io — can we still talk to the tmux server? (A server with zero sessions
+ *  exits, so `list-sessions` failing means the server itself is gone.) */
+function isServerReachable() {
+    try {
+        runTmux(["list-sessions", "-F", "#{session_name}"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run the updater loop forever (the body of `tmux-ide chrome-updater`). Claims
+ * single-ownership, then rewrites every adopted session's bar immediately and
+ * every {@link TICK_MS} thereafter behind ONE persistent tracker (so `done`
+ * transitions surface). Blocks — the interval keeps the event loop alive —
+ * until the tmux server has been unreachable for
+ * {@link UPDATER_UNREACHABLE_EXIT_TICKS} consecutive ticks, at which point the
+ * loop logs once and exits instead of running headless forever.
+ */
+export function runUpdaterLoop() {
+    if (!claimUpdater())
+        return;
+    // Resolve the config once for the loop's lifetime — cadence + palette. A
+    // config change (theme/keys/cadence) takes effect on the next updater start
+    // (which a re-adopt triggers).
+    const config = getAppConfig();
+    const tracker = createStatusTracker();
+    // Persistent across ticks so `diffFleet` can spot working→done etc.
+    const prevState = new Map();
+    // Per-PANE states for the notification path (M25.1 — pane-granular pings).
+    const prevPaneState = new Map();
+    // The notification debounce map — restored from disk so a restart can't
+    // re-ping inside the window, persisted back on every ping.
+    const lastNotified = loadLastNotified();
+    // Queued OS-level pings awaiting their delayed re-verify (M25.2). In-memory
+    // only: the window is seconds, so a restart just drops the queue.
+    const pendingPings = [];
+    // Persistent per-pane chip cache so we only rewrite a chip when it changed.
+    const chipCache = new Map();
+    // Session-id capture for kinds without a hook integration (codex/cursor):
+    // stamps @agent_session_id so restore --resume-agents has its key. Throttled
+    // internally; probes only unstamped panes of capturable kinds.
+    const capturer = createSessionIdCapturer({
+        // Throwing is fine here — the capturer treats a failed stamp as "retry on
+        // the next capture window".
+        stamp: (paneId, id) => runTmux(["set-option", "-p", "-t", paneId, "@agent_session_id", id]),
+    });
+    // The fleet snapshotter — pulsed each tick, self-throttled, writes only on a
+    // structural change so the fleet can be rebuilt after a tmux-server death.
+    const snapshotter = createSnapshotter({
+        collect: () => collectFleetSnapshot(),
+        read: readSnapshot,
+        write: writeSnapshot,
+        every: config.updater.snapshotEvery,
+    });
+    const shouldGiveUp = createUnreachableCounter();
+    const tick = () => {
+        try {
+            runUpdaterTick({
+                listAdopted: listAdoptedSessions,
+                computeProjects: (onPane) => listTeamProjects(tracker, { onPane }),
+                writeStatus: writeSessionStatus,
+                enforcePaneChrome: enforcePaneChromeWindows,
+                theme: config.theme,
+                writeChip: writePaneChip,
+                chipCache,
+                prevState,
+                appendEvents,
+                prevPaneState,
+                listClients: listAttachedClients,
+                lastNotified,
+                now: () => Date.now(),
+                prefs: readNotificationPrefs(),
+                sendToasts,
+                sendSystem: sendSystemNotification,
+                sendTerminal: writeTtys,
+                playSound: playPingSound,
+                pendingPings,
+                locatePane: paneLocation,
+                appFocus: () => readAppFocus(),
+                persistNotified: (map) => saveLastNotified(map),
+                maybeCheckForUpdate: () => maybeCheckForUpdate({ enabled: config.updates.check }),
+                markUpdateNotified,
+                captureSessionIds: (panes) => capturer.onTick(panes),
+            });
+        }
+        catch {
+            // never let one bad tick kill the loop
+        }
+        try {
+            snapshotter.onTick();
+        }
+        catch {
+            // a failed snapshot just means staler disaster-recovery state
+        }
+        // Self-exit when the server we exist to watch is gone (logged ONCE).
+        if (shouldGiveUp(isServerReachable())) {
+            console.error(`tmux-ide chrome-updater: tmux server unreachable for ${UPDATER_UNREACHABLE_EXIT_TICKS} consecutive ticks — exiting`);
+            shutdown();
+        }
+    };
+    const timer = setInterval(tick, config.updater.tickMs);
+    const shutdown = () => {
+        clearInterval(timer);
+        releaseUpdater();
+        process.exit(0);
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+    tick();
+}

package/packages/daemon/dist/tui/chrome/welcome.d.ts

@@ -0,0 +1,41 @@
+import { type AppKeys } from "../../lib/app-config.ts";
+/**
+ * Absolute path to the "already welcomed" marker: `<home>/welcomed`, where
+ * `<home>` is `TMUX_IDE_HOME` when set (tests / per-run overrides), else
+ * `~/.tmux-ide`. The env override lets a live test point the marker at a scratch
+ * dir so it never touches — or is confused by — the real user's marker.
+ */
+export declare function welcomeMarkerPath(): string;
+/**
+ * Whether the first-run welcome should show: the marker file is ABSENT and the
+ * config hasn't disabled it (`welcome.show !== false`). A missing/garbage config
+ * defaults `welcome.show` to true (see app-config), so a fresh install shows it.
+ */
+export declare function shouldShowWelcome(): boolean;
+/**
+ * Create the marker file so the welcome shows only once. Best-effort — a marker
+ * we can't write means the card may show again, but it must never crash adopt.
+ */
+export declare function markWelcomed(): void;
+/**
+ * PURE — the welcome card text (ANSI-styled), sized for a small ~60×12 popup. A
+ * tiny hero naming the FOUR keys that unlock the whole TUI, sourced from the live
+ * key config so a rebind relabels the card. Ends with the "shows once" note so
+ * the user knows it won't nag.
+ */
+export declare function buildWelcomeText(keys?: AppKeys): string;
+/**
+ * io — float the one-time welcome card on the CURRENT tmux client, best-effort.
+ *
+ * Called at the end of {@link ../chrome/statusline.ts adoptSession}. Gated by
+ * {@link shouldShowWelcome} (marker + config) AND by being inside a tmux client
+ * — outside tmux there's nowhere to float the popup, so we neither show it nor
+ * burn the one-shot (the marker stays, so the next in-tmux adopt still shows it).
+ *
+ * The popup is spawned DETACHED and unref'd so it never blocks the adopt: a
+ * `display-popup -E` would otherwise keep the tmux CLI alive until the user
+ * pressed a key. `spawn` inherits `$TMUX`, so the popup lands on the invoking
+ * client. The marker is written immediately after the spawn attempt so a rapid
+ * `adopt --all` shows the card exactly once, not once per session.
+ */
+export declare function maybeShowWelcomePopup(): void;