@crouton-kit/crouter 0.3.82 → 0.3.84

package/dist/core/canvas/pid.js

@@ -9,6 +9,7 @@
 // placement.ts, and crtrd.ts into one (Phase 3 review reuse MINOR-1).
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { readKernelBootId } from './boot.js';
 /** Is `pid` a ZOMBIE (exited, awaiting reap by its parent)? `kill(pid, 0)`
  *  reports a zombie as a perfectly normal alive process — its PID is still
  *  occupied in the process table — so callers relying on that signal-0 probe
@@ -60,13 +61,29 @@ export function isPidAlive(pid) {
     }
     return !isZombie(pid);
 }
-/** Split a `composeIdentity` fingerprint (`lstart` or `lstart#ticks`) into its
- *  coarse (`lstart`, second-granular, portable) and fine (`ticks`, Linux-only
- *  jiffies, best-effort) parts. `#` never appears in `lstart` itself (a `ps`
- *  timestamp), so the first `#` unambiguously separates them. */
+/** Matches the kernel `boot_id` UUID shape (`/proc/sys/kernel/random/boot_id`),
+ *  used to tell a NEW-format identity base (a per-boot UUID) apart from a
+ *  LEGACY one (a `ps lstart` wall-clock timestamp). A boot_id is a lowercase
+ *  hex UUID; an `lstart` string is a human-readable date — the two never
+ *  collide, so this cleanly classifies which comparison rule an identity's
+ *  base obeys (see `identitiesMatch`). */
+const BOOT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Split a `composeIdentity` fingerprint (`<base>` or `<base>#<ticks>`, where
+ *  `base` is a per-boot `boot_id` UUID on Linux-with-procfs or the portable
+ *  `ps lstart` timestamp otherwise) into its coarse base and fine `ticks`
+ *  (Linux-only jiffies) parts. `#` never appears in a `boot_id` or an `lstart`
+ *  timestamp, so the first `#` unambiguously separates them. Only a NON-EMPTY,
+ *  purely-numeric suffix counts as ticks (the shape `procStartTicks` and
+ *  `composeIdentity` guarantee); a malformed or empty suffix (`A#`, `A#bad`,
+ *  `A#1#2`) is treated as ABSENT ticks, so the base compare then applies — a
+ *  garbage suffix must never be trusted as a fine discriminator (review
+ *  Minor). */
 function splitIdentity(identity) {
     const i = identity.indexOf('#');
-    return i === -1 ? { base: identity, ticks: undefined } : { base: identity.slice(0, i), ticks: identity.slice(i + 1) };
+    if (i === -1)
+        return { base: identity, ticks: undefined };
+    const suffix = identity.slice(i + 1);
+    return { base: identity.slice(0, i), ticks: /^\d+$/.test(suffix) ? suffix : undefined };
 }
 /** THE single precision-aware identity compare, used EVERYWHERE two
  *  `composeIdentity` fingerprints are compared (this module's own
@@ -75,32 +92,60 @@ function splitIdentity(identity) {
  *  drift from this rule (review Major #1, Round 2 of the pid-reuse-liveness
  *  fix).
  *
- *  The hazard this closes: `composeIdentity` appends the `#<ticks>` Linux
- *  discriminator only when `/proc/<pid>/stat` happens to be readable at
- *  capture time — so the SAME live process can be recorded plain `lstart` on
- *  one capture and `lstart#ticks` on another (a transient `/proc` read
- *  failure, or capturing on a platform/container without procfs). A naive
- *  `===` then reads that as a reuse (different string) and reports `dead` for
- *  a broker that never actually died — the false-DEAD direction, which can
- *  make `reviveNode`'s double-launch guard wrongly relaunch a SECOND broker
- *  onto a still-live session.
+ *  Two hazards this closes, both in the false-DEAD direction (the dangerous
+ *  one — a false DEAD lets `reviveNode`'s double-launch guard relaunch a
+ *  SECOND broker onto a still-live session):
  *
- *  Rule: split both on `#`. Bases (`lstart`) differ → definitely NOT a match
- *  (different process, or the same pid reused in a different second). Bases
- *  match and BOTH carry a `#ticks` suffix → match iff the suffixes are equal
- *  (this still catches genuine same-second reuse, the case `procStartTicks`
- *  exists for). Bases match and EITHER lacks the suffix → coarse-vs-fine,
- *  can't distinguish → MATCH (fail-open to same-process, matching this
- *  module's universal discipline: only a POSITIVE mismatch counts as reuse,
- *  never an absence of evidence). */
+ *  1. `composeIdentity` appends the `#<ticks>` Linux discriminator only when
+ *     `/proc/<pid>/stat` happens to be readable at capture time — so the SAME
+ *     live process can be recorded plain `lstart` on one capture and
+ *     `lstart#ticks` on another (a transient `/proc` read failure, or
+ *     capturing on a platform/container without procfs). A naive `===` reads
+ *     that as a reuse (different string) and reports `dead` for a broker that
+ *     never died.
+ *  2. `lstart` is NOT stable for a live process on every host. It is derived
+ *     from `/proc/stat` btime (wall-clock boot epoch) + starttime jiffies, so
+ *     a clock correction / suspend-resume shifts btime and re-anchors the
+ *     SAME live process's `lstart` by seconds between two captures. Observed
+ *     on Blaxel unikraft guests: pid+ticks identical across probes, `lstart`
+ *     drifting +81s — a base-first compare then reads the live home-node
+ *     broker as reused/dead every cycle, driving an uncapped revive loop.
+ *
+ *  A third hazard the base itself once carried: `ticks` (jiffies-since-boot)
+ *  RESET on every boot and can repeat across boots, so ticks-alone is only
+ *  safe WITHIN one boot. `composeIdentity` therefore boot-SCOPES the base on
+ *  Linux-with-procfs — the base IS the kernel `boot_id` UUID — so a
+ *  new-format identity is `<bootId>#<ticks>` and equality means same boot AND
+ *  same process. This closes the cross-boot false match at the root, without
+ *  plumbing boot reconciliation ahead of every caller.
+ *
+ *  Rule: split both on `#`.
+ *   - BOTH sides carry `#ticks` AND both bases are `boot_id` UUIDs
+ *     (new-format vs new-format): match iff base AND ticks are equal. A
+ *     different boot_id with equal ticks is NOT a match (the cross-boot
+ *     collision).
+ *   - BOTH sides carry `#ticks` but a base is NOT a boot_id UUID on EITHER
+ *     side — a LEGACY `lstart#ticks` row recorded before this repo boot-scoped
+ *     the base, or a Linux host that has procfs ticks but no readable boot_id:
+ *     ticks DECIDE it alone (the prior landed semantics). This is a NARROW
+ *     format-migration path so an in-place upgrade never false-kills a live
+ *     broker whose row still holds `lstart#ticks`; it is NOT a general
+ *     fallback — new-format vs new-format always demands base+ticks above.
+ *   - EITHER side lacks a valid `#ticks` suffix (macOS / no procfs / transient
+ *     `/proc` miss / malformed suffix): fall back to the coarse base —
+ *     matching iff the bases agree (fail-open to same-process, matching this
+ *     module's universal discipline: only a POSITIVE mismatch counts as reuse,
+ *     never an absence of evidence). */
 export function identitiesMatch(a, b) {
     const ia = splitIdentity(a);
     const ib = splitIdentity(b);
-    if (ia.base !== ib.base)
-        return false;
-    if (ia.ticks !== undefined && ib.ticks !== undefined)
-        return ia.ticks === ib.ticks;
-    return true;
+    if (ia.ticks !== undefined && ib.ticks !== undefined) {
+        if (BOOT_ID_RE.test(ia.base) && BOOT_ID_RE.test(ib.base)) {
+            return ia.base === ib.base && ia.ticks === ib.ticks;
+        }
+        return ia.ticks === ib.ticks; // legacy lstart#ticks (either side) → ticks-alone migration
+    }
+    return ia.base === ib.base;
 }
 export function recordedPidLiveness(pid, expectedIdentity) {
     const debug = Boolean(process.env.CRTR_DEBUG_PID_LIVENESS);
@@ -226,16 +271,86 @@ function procStartTicks(pid) {
         return null;
     }
 }
-/** Compose the stable process-identity fingerprint used everywhere in this
- *  module: `ps lstart` (portable, BSD + Linux) plus the Linux-only jiffies
- *  discriminator when available (best-effort — see `procStartTicks`). ALWAYS
- *  used to build an identity string, never `lstart` alone directly, so every
- *  identity captured anywhere (launch-time `recordPid`, the teardown
- *  snapshot, and the escalation-window re-check) is comparable apples-to-
- *  apples. */
-function composeIdentity(pid, lstart) {
-    const ticks = procStartTicks(pid);
-    return ticks !== null ? `${lstart}#${ticks}` : lstart;
+/** How long a FAILED (`null`) boot_id read is remembered as negative before the
+ *  next call is allowed to re-read. Bounds the cost on a genuinely no-boot_id
+ *  host (macOS / no procfs) to one throwing `/proc` read per window rather than
+ *  one per identity composition — identity is composed per supervised row per
+ *  daemon tick and per process in a full ps-table capture, so an uncapped
+ *  retry-on-null is a synchronous read storm there. Kept short so a transient
+ *  miss on a real boot_id host still recovers promptly. */
+const BOOT_ID_NEGATIVE_TTL_MS = 60_000;
+/** The kernel `boot_id` (`/proc/sys/kernel/random/boot_id`) is stable for the
+ *  whole lifetime of this process — it only changes on a kernel boot, which
+ *  necessarily kills this process — so once a real value is read it is cached
+ *  for good, rather than re-read for every row of a whole-process-table `ps`
+ *  scan. Only SUCCESSFUL reads are cached forever: a `null` read is negative
+ *  for `BOOT_ID_NEGATIVE_TTL_MS`, after which the next call retries — so a
+ *  transient `/proc` miss on a boot_id-capable host still recovers (never
+ *  permanently downgraded to legacy `lstart#ticks`), while a genuinely
+ *  no-boot_id host is not hammered with a synchronous throwing read on every
+ *  identity composition. `now` is injectable for tests. */
+export function makeBootIdCache(read, now = Date.now, negativeTtlMs = BOOT_ID_NEGATIVE_TTL_MS) {
+    let cached = null;
+    let retryAfter = 0;
+    return () => {
+        if (cached !== null)
+            return cached;
+        const t = now();
+        if (t < retryAfter)
+            return null; // within the negative-cache window — don't re-read
+        const v = read();
+        if (v !== null)
+            return (cached = v);
+        retryAfter = t + negativeTtlMs;
+        return null;
+    };
+}
+const bootIdBase = makeBootIdCache(readKernelBootId);
+/** Is `identity` a LEGACY (pre-boot-scoped) baseline — a `<lstart>#<ticks>` row
+ *  whose base is NOT a boot_id UUID but which DOES carry ticks? These are the
+ *  rows the one-time startup migration re-records once this platform can
+ *  compose boot-scoped identities (see `migrateLegacyPidIdentities`). */
+export function isLegacyTicksIdentity(identity) {
+    const { base, ticks } = splitIdentity(identity);
+    return ticks !== undefined && !BOOT_ID_RE.test(base);
+}
+/** Is `identity` a NEW-format boot-scoped baseline — `<bootId>#<ticks>` with a
+ *  real boot_id UUID base AND ticks? The startup migration only re-records a
+ *  legacy row when the pid's CURRENT identity comes out in this shape (i.e. the
+ *  platform now composes new-format), never otherwise. */
+export function isBootScopedIdentity(identity) {
+    const { base, ticks } = splitIdentity(identity);
+    return ticks !== undefined && BOOT_ID_RE.test(base);
+}
+/** Compose the stable, BOOT-SCOPED process-identity fingerprint used
+ *  everywhere in this module. ALWAYS used to build an identity string, never a
+ *  raw field directly, so every identity captured anywhere (launch-time
+ *  `recordPid`, the teardown snapshot, and the escalation-window re-check) is
+ *  comparable apples-to-apples.
+ *
+ *  Platform capability, not layered fallbacks — the base is the finest STABLE
+ *  per-boot anchor available:
+ *   - Linux-with-procfs (the production guest shape): `<bootId>#<ticks>` — the
+ *     per-boot `boot_id` UUID plus the per-process jiffies-since-boot. Ticks
+ *     reset per boot and can repeat, so scoping the base to the boot is what
+ *     makes an equal-ticks compare safe ACROSS boots (see `identitiesMatch`).
+ *   - Linux-with-procfs but no readable `boot_id` (if that combination
+ *     exists): `<lstart>#<ticks>` — the prior landed behavior.
+ *   - No procfs ticks (macOS / containers without procfs): `<lstart>` alone —
+ *     unchanged coarse behavior. The base is only ever a `boot_id` when a
+ *     `ticks` discriminator is ALSO present; a bare `boot_id` (shared by every
+ *     process on the boot) would be a useless per-process identity. */
+export function composeIdentity(pid, lstart, deps = {}) {
+    // `deps` is a TEST-ONLY seam: it lets a unit test drive the composition with
+    // an injected ticks/boot_id pair (so `<bootId>#<ticks>` composition is
+    // provable off-Linux, where real `/proc` reads return null), without adding
+    // any runtime branch — production callers pass no `deps` and read the real
+    // `/proc` values exactly as before.
+    const ticks = deps.ticks !== undefined ? deps.ticks : procStartTicks(pid);
+    if (ticks === null)
+        return lstart;
+    const bootId = deps.bootId !== undefined ? deps.bootId : bootIdBase();
+    return `${bootId ?? lstart}#${ticks}`;
 }
 /** One combined `ps` probe over the WHOLE process table — `pid`, `ppid`, AND
  *  `lstart` per row — parsed into BOTH a ppid → children-pid[] map (for

package/dist/core/canvas/remote-canvas-source.d.ts

@@ -57,6 +57,6 @@ export declare class RemoteCanvasSource implements CanvasSource {
     subscriptionsOf(id: string): Promise<SubscriptionRef[]>;
     subscribersOf(id: string): Promise<SubscriptionRef[]>;
     view(root: string): Promise<string[]>;
-    askCountsForView(root: string): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
     hasActiveLiveSubscription(id: string): Promise<boolean>;
 }

package/dist/core/canvas/remote-canvas-source.js

@@ -12,7 +12,7 @@ const CACHE_TTL_MS = 1000;
 // `execJson<T>` parses stdout and casts it to T with NO structural check — a
 // remote subprocess that exits 0 with a wrong shape (e.g. `{}`, `{node:null}`)
 // would otherwise pass through as a "valid" T. `fetchShow`/`listNodes`/
-// `askCountsForView` validate before caching/returning; on a shape mismatch
+// `ticketCountsForView` validate before caching/returning; on a shape mismatch
 // they degrade exactly like the existing network-failure path (null/[]/{}),
 // never a malformed object a caller might dereference.
 // ---------------------------------------------------------------------------
@@ -206,7 +206,9 @@ export class RemoteCanvasSource {
         this.viewCache.set(root, { value: out, at: Date.now() });
         return out;
     }
-    async askCountsForView(root) {
+    async ticketCountsForView(root) {
+        // The `canvas attention map` transport is unchanged; its `counts` values now
+        // mean all pending human tickets (deck/review/notify), not just asks.
         const res = await this.execJson(['canvas', 'attention', 'map', '--view', root]);
         return isPlainObject(res) && isPlainObject(res['counts']) ? res['counts'] : {};
     }

package/dist/core/canvas/render.d.ts

@@ -126,16 +126,16 @@ export declare function dashboardRowsAll(): DashboardRow[];
 export declare function dashboardRowsAllFromSource(source: CanvasSource): Promise<DashboardRow[]>;
 /** Fold the cheap-boot row's deferred fields in for ONE row: the full label
  *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
- *  meta read + one telemetry read + one ask scan. Idempotent (no-op once enriched).
- *  For a batch, prefer {@link enrichRows} — it scans each cwd's ask inbox once. */
+ *  meta read + one telemetry read + one ticket scan. Idempotent (no-op once enriched).
+ *  For a batch, prefer {@link enrichRows} — it scans each cwd's ticket inbox once. */
 export declare function enrichRow(row: DashboardRow): DashboardRow;
 /** Batch {@link enrichRow}: enrich every not-yet-enriched row, scanning each
- *  distinct cwd's ask inbox exactly ONCE (via `asksForNodes`) instead of per row.
- *  Use this for a whole viewport / the full forest; mutates each row in place. */
+ *  distinct cwd's ticket inbox exactly ONCE (via `ticketCountsForNodes`) instead
+ *  of per row. Use this for a whole viewport / the full forest; mutates each row in place. */
 export declare function enrichRows(rows: DashboardRow[]): void;
 /** Telemetry (ctx tokens) is a local disk read, so it is suppressed to 0 for a
  *  remote source. Ask counts are suppressed to 0 UNLESS the caller supplies
- *  `remoteAsks` — a pre-fetched `askCountsForView` map (one call per forest
+ *  `remoteAsks` — a pre-fetched `ticketCountsForView` map (one call per forest
  *  root; the caller's job, since the right root set is a browse/snapshot
  *  concern, not this per-row enrichment loop's). See `runBrowse`'s
  *  `remoteAskCounts`, fetched once per snapshot rebuild, not per flush. */

package/dist/core/canvas/render.js

@@ -18,7 +18,7 @@ import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
 import { RemoteCanvasSource } from './remote-canvas-source.js';
 import { fullName } from './labels.js';
 import { jobDir, contextDir } from './paths.js';
-import { countAsks, asksForNodes } from './attention.js';
+import { countTickets, ticketCountsForNodes } from './attention.js';
 import { isPidAlive } from './pid.js';
 import { listFocuses } from './focuses.js';
 import { resolveNodeVisual, faultSummary } from './status-glyph.js';
@@ -68,7 +68,7 @@ function nodeLine(nodeId, indent, connector) {
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
     const tel = readNodeTelemetry(nodeId);
     const ctx = fmtCtx(tel.tokens_in);
-    const asks = countAsks(nodeId);
+    const asks = countTickets(nodeId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
@@ -119,7 +119,7 @@ export function renderTree(rootId) {
         return `? <missing node: ${rootId}>`;
     const tel = readNodeTelemetry(rootId);
     const ctx = fmtCtx(tel.tokens_in);
-    const asks = countAsks(rootId);
+    const asks = countTickets(rootId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     const hanging = hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
@@ -182,7 +182,7 @@ async function nodeLineFromSource(source, nodeId, indent, connector, remote) {
     const hanging = remote ? null : hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
     const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(nodeId).tokens_in);
-    const asks = remote ? 0 : countAsks(nodeId);
+    const asks = remote ? 0 : countTickets(nodeId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
@@ -212,7 +212,7 @@ export async function renderTreeFromSource(source, rootId) {
     if (node === null)
         return `? <missing node: ${rootId}>`;
     const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(rootId).tokens_in);
-    const asks = remote ? 0 : countAsks(rootId);
+    const asks = remote ? 0 : countTickets(rootId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     const hanging = remote ? null : hangingFor(node);
     const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
@@ -457,7 +457,7 @@ export function dashboardRows(rootId) {
                 kind: node.kind,
                 mode: node.mode,
                 ctx_tokens: tel.tokens_in ?? 0,
-                asks: countAsks(id),
+                asks: countTickets(id),
                 cwd: node.cwd,
                 created: node.created,
             }];
@@ -542,8 +542,8 @@ export async function dashboardRowsAllFromSource(source) {
 // ---------------------------------------------------------------------------
 /** Fold the cheap-boot row's deferred fields in for ONE row: the full label
  *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
- *  meta read + one telemetry read + one ask scan. Idempotent (no-op once enriched).
- *  For a batch, prefer {@link enrichRows} — it scans each cwd's ask inbox once. */
+ *  meta read + one telemetry read + one ticket scan. Idempotent (no-op once enriched).
+ *  For a batch, prefer {@link enrichRows} — it scans each cwd's ticket inbox once. */
 export function enrichRow(row) {
     if (row.enriched === true)
         return row;
@@ -551,18 +551,18 @@ export function enrichRow(row) {
     if (meta !== null)
         row.name = fullName(meta);
     row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
-    row.asks = countAsks(row.node_id);
+    row.asks = countTickets(row.node_id);
     row.enriched = true;
     return row;
 }
 /** Batch {@link enrichRow}: enrich every not-yet-enriched row, scanning each
- *  distinct cwd's ask inbox exactly ONCE (via `asksForNodes`) instead of per row.
- *  Use this for a whole viewport / the full forest; mutates each row in place. */
+ *  distinct cwd's ticket inbox exactly ONCE (via `ticketCountsForNodes`) instead
+ *  of per row. Use this for a whole viewport / the full forest; mutates each row in place. */
 export function enrichRows(rows) {
     const todo = rows.filter((r) => r.enriched !== true);
     if (todo.length === 0)
         return;
-    const asks = asksForNodes(todo.map((r) => r.node_id));
+    const asks = ticketCountsForNodes(todo.map((r) => r.node_id));
     for (const row of todo) {
         const meta = getNode(row.node_id);
         if (meta !== null)
@@ -574,7 +574,7 @@ export function enrichRows(rows) {
 }
 /** Telemetry (ctx tokens) is a local disk read, so it is suppressed to 0 for a
  *  remote source. Ask counts are suppressed to 0 UNLESS the caller supplies
- *  `remoteAsks` — a pre-fetched `askCountsForView` map (one call per forest
+ *  `remoteAsks` — a pre-fetched `ticketCountsForView` map (one call per forest
  *  root; the caller's job, since the right root set is a browse/snapshot
  *  concern, not this per-row enrichment loop's). See `runBrowse`'s
  *  `remoteAskCounts`, fetched once per snapshot rebuild, not per flush. */
@@ -583,7 +583,7 @@ export async function enrichRowsFromSource(source, rows, remoteAsks) {
     if (todo.length === 0)
         return;
     const remote = source instanceof RemoteCanvasSource;
-    const asks = remote ? (remoteAsks ?? {}) : asksForNodes(todo.map((r) => r.node_id));
+    const asks = remote ? (remoteAsks ?? {}) : ticketCountsForNodes(todo.map((r) => r.node_id));
     await Promise.all(todo.map(async (row) => {
         const meta = await source.getNode(row.node_id);
         if (meta !== null)

package/dist/core/canvas/source.d.ts

@@ -9,7 +9,7 @@ export interface CanvasSource {
     subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
     subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
     view(root: string): Promise<string[]>;
-    askCountsForView(root: string): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
     hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
 }
 export declare class LocalCanvasSource implements CanvasSource {
@@ -21,7 +21,7 @@ export declare class LocalCanvasSource implements CanvasSource {
     subscriptionsOf(subscriber: string): Promise<SubscriptionRef[]>;
     subscribersOf(publisher: string): Promise<SubscriptionRef[]>;
     view(root: string): Promise<string[]>;
-    askCountsForView(root: string): Promise<Record<string, number>>;
+    ticketCountsForView(root: string): Promise<Record<string, number>>;
     hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
 }
 export declare const localCanvasSource: CanvasSource;

package/dist/core/canvas/source.js

@@ -1,5 +1,5 @@
 import { getNode, getRow, listNodes, subscriptionsOf, subscribersOf, view, hasActiveLiveSubscription, } from './canvas.js';
-import { asksForNodes } from './attention.js';
+import { ticketCountsForNodes } from './attention.js';
 import { readState } from '../config.js';
 import { resolveRemoteCanvasTarget } from '../view/remote-canvas-target.js';
 import { RemoteCanvasSource } from './remote-canvas-source.js';
@@ -22,8 +22,8 @@ export class LocalCanvasSource {
     async view(root) {
         return view(root);
     }
-    async askCountsForView(root) {
-        return asksForNodes([root, ...view(root)]);
+    async ticketCountsForView(root) {
+        return ticketCountsForNodes([root, ...view(root)]);
     }
     async hasActiveLiveSubscription(nodeId) {
         return hasActiveLiveSubscription(nodeId);

package/dist/core/keybindings/__tests__/inbox-affordance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/keybindings/__tests__/inbox-affordance.test.js

@@ -0,0 +1,38 @@
+// Run with: node --import tsx/esm --test src/core/keybindings/__tests__/inbox-affordance.test.ts
+//
+// The shared inbox-affordance formatter is the single source of truth for how
+// every pending-interaction surface (attach footer, `human ask`/`review`
+// follow-up + help effects, `node focus` error) names the inbox shortcut. These
+// guard that it resolves the live binding — default, custom, multi-gesture, and
+// disabled — instead of hardcoding a symbol that can drift from the real key.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveKeybindings } from '../index.js';
+import { inboxOpenHint, inboxOpenInstruction, inboxPopupHint, inboxShortcut, } from '../inbox.js';
+const custom = () => resolveKeybindings({ 'crtr.tmux.inbox.toggle': ['alt+j'] });
+const multi = () => resolveKeybindings({ 'crtr.tmux.inbox.toggle': ['alt+i', 'alt+j'] });
+const disabled = () => resolveKeybindings({ 'crtr.tmux.inbox.toggle': [] });
+test('inboxShortcut resolves default, custom, multi-gesture, and disabled', () => {
+    assert.equal(inboxShortcut(resolveKeybindings()), 'Alt+I');
+    assert.equal(inboxShortcut(custom()), 'Alt+J');
+    assert.equal(inboxShortcut(multi()), 'Alt+I / Alt+J');
+    assert.equal(inboxShortcut(disabled()), null);
+});
+test('inboxOpenHint mirrors the attach footer contract', () => {
+    assert.equal(inboxOpenHint(resolveKeybindings()), 'Alt+I inbox');
+    assert.equal(inboxOpenHint(custom()), 'Alt+J inbox');
+    assert.equal(inboxOpenHint(multi()), 'Alt+I / Alt+J inbox');
+    assert.equal(inboxOpenHint(disabled()), 'hl inbox open');
+});
+test('inboxPopupHint is a bare parenthetical token, CLI form when disabled', () => {
+    assert.equal(inboxPopupHint(resolveKeybindings()), 'Alt+I');
+    assert.equal(inboxPopupHint(custom()), 'Alt+J');
+    assert.equal(inboxPopupHint(multi()), 'Alt+I / Alt+J');
+    assert.equal(inboxPopupHint(disabled()), '`hl inbox open`');
+});
+test('inboxOpenInstruction is an imperative clause, CLI-only when disabled', () => {
+    assert.equal(inboxOpenInstruction(resolveKeybindings()), 'press Alt+I (or run `hl inbox open` at a terminal)');
+    assert.equal(inboxOpenInstruction(custom()), 'press Alt+J (or run `hl inbox open` at a terminal)');
+    assert.equal(inboxOpenInstruction(multi()), 'press Alt+I / Alt+J (or run `hl inbox open` at a terminal)');
+    assert.equal(inboxOpenInstruction(disabled()), 'run `hl inbox open` at a terminal');
+});

package/dist/core/keybindings/__tests__/resolve.test.js

@@ -17,8 +17,9 @@ const REQUIRED_IDS = [
     ...ids('crtr.tmux.menu', ['open', 'promote', 'resume', 'demote', 'detach', 'close-subtree', 'context', 'providers', 'graph', 'focus-manager', 'issues']),
     ...ids('crtr.tmux.menu.issue', ['idea', 'bug']),
     ...ids('crtr.tmux.node', ['next', 'previous']),
+    'crtr.tmux.inbox.toggle',
     ...ids('crtr.tmux.view', ['next', 'previous']),
-    ...ids('crtr.attach', ['detach', 'clear-or-detach', 'graph.toggle', 'model-ladder.next']),
+    ...ids('crtr.attach', ['detach', 'clear-or-detach', 'graph.toggle', 'model-ladder.next', 'model-ladder.previous']),
     'crtr.mode.cycle',
     ...ids('crtr.graph', ['down', 'up', 'first', 'last', 'collapse-or-manager', 'expand-or-child', 'focus', 'focus-manager', 'close-subtree', 'dismiss']),
     ...ids('crtr.graph.confirm', ['accept', 'cancel']),

package/dist/core/keybindings/catalog.d.ts

@@ -7,8 +7,8 @@ type BrowseAction = 'quit' | 'down' | 'up' | 'first' | 'last' | 'expand-or-child
 type ProfileMenuAction = 'up' | 'down' | 'select' | 'accept-default' | 'abort' | `slot.${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9}` | 'create' | 'search-existing' | 'use-root' | 'set-default' | 'add-directory' | 'unpin';
 type SetupAction = 'cancel' | 'tab-next' | 'tab-previous' | 'open' | 'list-down' | 'list-up' | 'toggle' | 'details' | 'advance';
 type SetupKeybindingAction = 'edit' | 'commit-edit' | 'cancel-edit' | 'unbind' | 'reset-row' | 'reset-all' | 'save' | 'discard' | 'page-up' | 'page-down' | 'filter' | 'filter-delete' | 'filter-clear';
-export type BindingId = `crtr.tmux.menu.${TmuxMenuAction}` | `crtr.tmux.menu.issue.${'idea' | 'bug'}` | `crtr.tmux.node.${'next' | 'previous'}` | `crtr.tmux.view.${'next' | 'previous'}` | `crtr.attach.${'detach' | 'clear-or-detach' | 'graph.toggle' | 'model-ladder.next'}` | 'crtr.mode.cycle' | `crtr.graph.${GraphAction}` | `crtr.graph.confirm.${'accept' | 'cancel'}` | `crtr.view.host.${'force-quit' | 'editor.backspace'}` | `crtr.view.canvas.${'down' | 'up' | 'refresh' | 'quit'}` | `crtr.view.chat.${'submit' | 'contextual-cancel' | 'reconnect' | 'request-control' | 'release-control' | 'quit'}` | `crtr.view.git-pr.${'down' | 'up' | 'refresh' | 'quit'}` | `crtr.view.inbox.${InboxAction}` | `crtr.view.linkedin.${LinkedinAction}` | `crtr.view.prompt-review.${'down' | 'up' | 'compare-previous' | 'compare-next' | 'toggle-mode' | 'expand' | 'export' | 'refresh' | 'quit'}` | `crtr.view.settings.${'down' | 'up' | 'cell-previous' | 'cell-next' | 'refresh' | 'quit' | 'edit-or-submit' | 'cancel-edit'}` | `crtr.view.workspace-sidebar.${'down' | 'up' | 'open' | 'refresh' | 'quit'}` | `crtr.view-picker.${'down' | 'up' | 'run' | 'quit'}` | `crtr.browse.${BrowseAction}` | `crtr.browse.search.${'cancel' | 'commit' | 'delete' | 'quit'}` | `crtr.profile.menu.${ProfileMenuAction}` | `crtr.profile.search.${'up' | 'down' | 'pick' | 'back' | 'delete' | 'abort'}` | `crtr.setup.${SetupAction}` | `crtr.setup.confirm.${'accept' | 'back'}` | `crtr.setup.keybindings.${SetupKeybindingAction}`;
-export declare const BINDING_CATALOG: readonly [BindingDefinition<"crtr.tmux.menu.open">, BindingDefinition<"crtr.tmux.menu.promote">, BindingDefinition<"crtr.tmux.menu.resume">, BindingDefinition<"crtr.tmux.menu.demote">, BindingDefinition<"crtr.tmux.menu.detach">, BindingDefinition<"crtr.tmux.menu.close-subtree">, BindingDefinition<"crtr.tmux.menu.context">, BindingDefinition<"crtr.tmux.menu.providers">, BindingDefinition<"crtr.tmux.menu.graph">, BindingDefinition<"crtr.tmux.menu.focus-manager">, BindingDefinition<"crtr.tmux.menu.issues">, BindingDefinition<"crtr.tmux.menu.issue.idea">, BindingDefinition<"crtr.tmux.menu.issue.bug">, BindingDefinition<"crtr.tmux.node.next">, BindingDefinition<"crtr.tmux.node.previous">, BindingDefinition<"crtr.tmux.view.next">, BindingDefinition<"crtr.tmux.view.previous">, BindingDefinition<"crtr.attach.detach">, BindingDefinition<"crtr.attach.clear-or-detach">, BindingDefinition<"crtr.attach.graph.toggle">, BindingDefinition<"crtr.attach.model-ladder.next">, BindingDefinition<"crtr.mode.cycle">, BindingDefinition<"crtr.graph.down">, BindingDefinition<"crtr.graph.up">, BindingDefinition<"crtr.graph.first">, BindingDefinition<"crtr.graph.last">, BindingDefinition<"crtr.graph.collapse-or-manager">, BindingDefinition<"crtr.graph.expand-or-child">, BindingDefinition<"crtr.graph.focus">, BindingDefinition<"crtr.graph.focus-manager">, BindingDefinition<"crtr.graph.close-subtree">, BindingDefinition<"crtr.graph.dismiss">, BindingDefinition<"crtr.graph.confirm.accept">, BindingDefinition<"crtr.graph.confirm.cancel">, BindingDefinition<"crtr.view.host.force-quit">, BindingDefinition<"crtr.view.host.editor.backspace">, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<"crtr.view.chat.submit">, BindingDefinition<"crtr.view.chat.contextual-cancel">, BindingDefinition<"crtr.view.chat.reconnect">, BindingDefinition<"crtr.view.chat.request-control">, BindingDefinition<"crtr.view.chat.release-control">, BindingDefinition<"crtr.view.chat.quit">, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, ...(BindingDefinition<BindingId> | BindingDefinition<"crtr.view.prompt-review.down"> | BindingDefinition<"crtr.view.prompt-review.up"> | BindingDefinition<"crtr.view.prompt-review.compare-previous"> | BindingDefinition<"crtr.view.prompt-review.compare-next"> | BindingDefinition<"crtr.view.prompt-review.toggle-mode"> | BindingDefinition<"crtr.view.prompt-review.expand"> | BindingDefinition<"crtr.view.prompt-review.export"> | BindingDefinition<"crtr.view.prompt-review.refresh"> | BindingDefinition<"crtr.view.prompt-review.quit"> | BindingDefinition<"crtr.view.settings.down"> | BindingDefinition<"crtr.view.settings.up"> | BindingDefinition<"crtr.view.settings.cell-previous"> | BindingDefinition<"crtr.view.settings.cell-next"> | BindingDefinition<"crtr.view.settings.refresh"> | BindingDefinition<"crtr.view.settings.quit"> | BindingDefinition<"crtr.view.settings.edit-or-submit"> | BindingDefinition<"crtr.view.settings.cancel-edit"> | BindingDefinition<"crtr.view.workspace-sidebar.down"> | BindingDefinition<"crtr.view.workspace-sidebar.up"> | BindingDefinition<"crtr.view.workspace-sidebar.open"> | BindingDefinition<"crtr.view.workspace-sidebar.refresh"> | BindingDefinition<"crtr.view.workspace-sidebar.quit"> | BindingDefinition<"crtr.view-picker.down"> | BindingDefinition<"crtr.view-picker.up"> | BindingDefinition<"crtr.view-picker.run"> | BindingDefinition<"crtr.view-picker.quit"> | BindingDefinition<"crtr.browse.quit"> | BindingDefinition<"crtr.browse.down"> | BindingDefinition<"crtr.browse.up"> | BindingDefinition<"crtr.browse.first"> | BindingDefinition<"crtr.browse.last"> | BindingDefinition<"crtr.browse.expand-or-child"> | BindingDefinition<"crtr.browse.collapse-or-parent"> | BindingDefinition<"crtr.browse.toggle-fold"> | BindingDefinition<"crtr.browse.tab-next"> | BindingDefinition<"crtr.browse.tab-previous"> | BindingDefinition<"crtr.browse.tab.2" | "crtr.browse.tab.1" | "crtr.browse.tab.3" | "crtr.browse.tab.4" | "crtr.browse.tab.5"> | BindingDefinition<"crtr.browse.close-subtree"> | BindingDefinition<"crtr.browse.confirm-close"> | BindingDefinition<"crtr.browse.sort"> | BindingDefinition<"crtr.browse.scope"> | BindingDefinition<"crtr.browse.residents"> | BindingDefinition<"crtr.browse.preview"> | BindingDefinition<"crtr.browse.search"> | BindingDefinition<"crtr.browse.revive-now"> | BindingDefinition<"crtr.browse.focus"> | BindingDefinition<"crtr.browse.search.cancel"> | BindingDefinition<"crtr.browse.search.commit"> | BindingDefinition<"crtr.browse.search.delete"> | BindingDefinition<"crtr.browse.search.quit"> | BindingDefinition<"crtr.profile.menu.up"> | BindingDefinition<"crtr.profile.menu.down"> | BindingDefinition<"crtr.profile.menu.select"> | BindingDefinition<"crtr.profile.menu.accept-default"> | BindingDefinition<"crtr.profile.menu.abort"> | BindingDefinition<"crtr.profile.menu.slot.2" | "crtr.profile.menu.slot.1" | "crtr.profile.menu.slot.3" | "crtr.profile.menu.slot.4" | "crtr.profile.menu.slot.5" | "crtr.profile.menu.slot.8" | "crtr.profile.menu.slot.6" | "crtr.profile.menu.slot.7" | "crtr.profile.menu.slot.9">)[], BindingDefinition<"crtr.profile.menu.create">, BindingDefinition<"crtr.profile.menu.search-existing">, BindingDefinition<"crtr.profile.menu.use-root">, BindingDefinition<"crtr.profile.menu.set-default">, BindingDefinition<"crtr.profile.menu.add-directory">, BindingDefinition<"crtr.profile.menu.unpin">, BindingDefinition<"crtr.profile.search.up">, BindingDefinition<"crtr.profile.search.down">, BindingDefinition<"crtr.profile.search.pick">, BindingDefinition<"crtr.profile.search.back">, BindingDefinition<"crtr.profile.search.delete">, BindingDefinition<"crtr.profile.search.abort">, BindingDefinition<"crtr.setup.cancel">, BindingDefinition<"crtr.setup.tab-next">, BindingDefinition<"crtr.setup.tab-previous">, BindingDefinition<"crtr.setup.open">, BindingDefinition<"crtr.setup.list-down">, BindingDefinition<"crtr.setup.list-up">, BindingDefinition<"crtr.setup.toggle">, BindingDefinition<"crtr.setup.details">, BindingDefinition<"crtr.setup.advance">, BindingDefinition<"crtr.setup.confirm.accept">, BindingDefinition<"crtr.setup.confirm.back">, BindingDefinition<"crtr.setup.keybindings.edit">, BindingDefinition<"crtr.setup.keybindings.commit-edit">, BindingDefinition<"crtr.setup.keybindings.cancel-edit">, BindingDefinition<"crtr.setup.keybindings.unbind">, BindingDefinition<"crtr.setup.keybindings.reset-row">, BindingDefinition<"crtr.setup.keybindings.reset-all">, BindingDefinition<"crtr.setup.keybindings.save">, BindingDefinition<"crtr.setup.keybindings.discard">, BindingDefinition<"crtr.setup.keybindings.page-up">, BindingDefinition<"crtr.setup.keybindings.page-down">, BindingDefinition<"crtr.setup.keybindings.filter">, BindingDefinition<"crtr.setup.keybindings.filter-delete">, BindingDefinition<"crtr.setup.keybindings.filter-clear">];
+export type BindingId = `crtr.tmux.menu.${TmuxMenuAction}` | `crtr.tmux.menu.issue.${'idea' | 'bug'}` | `crtr.tmux.node.${'next' | 'previous'}` | `crtr.tmux.view.${'next' | 'previous'}` | 'crtr.tmux.inbox.toggle' | `crtr.attach.${'detach' | 'clear-or-detach' | 'graph.toggle' | 'model-ladder.next' | 'model-ladder.previous'}` | 'crtr.mode.cycle' | `crtr.graph.${GraphAction}` | `crtr.graph.confirm.${'accept' | 'cancel'}` | `crtr.view.host.${'force-quit' | 'editor.backspace'}` | `crtr.view.canvas.${'down' | 'up' | 'refresh' | 'quit'}` | `crtr.view.chat.${'submit' | 'contextual-cancel' | 'reconnect' | 'request-control' | 'release-control' | 'quit'}` | `crtr.view.git-pr.${'down' | 'up' | 'refresh' | 'quit'}` | `crtr.view.inbox.${InboxAction}` | `crtr.view.linkedin.${LinkedinAction}` | `crtr.view.prompt-review.${'down' | 'up' | 'compare-previous' | 'compare-next' | 'toggle-mode' | 'expand' | 'export' | 'refresh' | 'quit'}` | `crtr.view.settings.${'down' | 'up' | 'cell-previous' | 'cell-next' | 'refresh' | 'quit' | 'edit-or-submit' | 'cancel-edit'}` | `crtr.view.workspace-sidebar.${'down' | 'up' | 'open' | 'refresh' | 'quit'}` | `crtr.view-picker.${'down' | 'up' | 'run' | 'quit'}` | `crtr.browse.${BrowseAction}` | `crtr.browse.search.${'cancel' | 'commit' | 'delete' | 'quit'}` | `crtr.profile.menu.${ProfileMenuAction}` | `crtr.profile.search.${'up' | 'down' | 'pick' | 'back' | 'delete' | 'abort'}` | `crtr.setup.${SetupAction}` | `crtr.setup.confirm.${'accept' | 'back'}` | `crtr.setup.keybindings.${SetupKeybindingAction}`;
+export declare const BINDING_CATALOG: readonly [BindingDefinition<"crtr.tmux.menu.open">, BindingDefinition<"crtr.tmux.menu.promote">, BindingDefinition<"crtr.tmux.menu.resume">, BindingDefinition<"crtr.tmux.menu.demote">, BindingDefinition<"crtr.tmux.menu.detach">, BindingDefinition<"crtr.tmux.menu.close-subtree">, BindingDefinition<"crtr.tmux.menu.context">, BindingDefinition<"crtr.tmux.menu.providers">, BindingDefinition<"crtr.tmux.menu.graph">, BindingDefinition<"crtr.tmux.menu.focus-manager">, BindingDefinition<"crtr.tmux.menu.issues">, BindingDefinition<"crtr.tmux.menu.issue.idea">, BindingDefinition<"crtr.tmux.menu.issue.bug">, BindingDefinition<"crtr.tmux.node.next">, BindingDefinition<"crtr.tmux.node.previous">, BindingDefinition<"crtr.tmux.inbox.toggle">, BindingDefinition<"crtr.tmux.view.next">, BindingDefinition<"crtr.tmux.view.previous">, BindingDefinition<"crtr.attach.detach">, BindingDefinition<"crtr.attach.clear-or-detach">, BindingDefinition<"crtr.attach.graph.toggle">, BindingDefinition<"crtr.attach.model-ladder.next">, BindingDefinition<"crtr.attach.model-ladder.previous">, BindingDefinition<"crtr.mode.cycle">, BindingDefinition<"crtr.graph.down">, BindingDefinition<"crtr.graph.up">, BindingDefinition<"crtr.graph.first">, BindingDefinition<"crtr.graph.last">, BindingDefinition<"crtr.graph.collapse-or-manager">, BindingDefinition<"crtr.graph.expand-or-child">, BindingDefinition<"crtr.graph.focus">, BindingDefinition<"crtr.graph.focus-manager">, BindingDefinition<"crtr.graph.close-subtree">, BindingDefinition<"crtr.graph.dismiss">, BindingDefinition<"crtr.graph.confirm.accept">, BindingDefinition<"crtr.graph.confirm.cancel">, BindingDefinition<"crtr.view.host.force-quit">, BindingDefinition<"crtr.view.host.editor.backspace">, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<"crtr.view.chat.submit">, BindingDefinition<"crtr.view.chat.contextual-cancel">, BindingDefinition<"crtr.view.chat.reconnect">, BindingDefinition<"crtr.view.chat.request-control">, BindingDefinition<"crtr.view.chat.release-control">, BindingDefinition<"crtr.view.chat.quit">, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, BindingDefinition<BindingId>, ...(BindingDefinition<BindingId> | BindingDefinition<"crtr.view.prompt-review.down"> | BindingDefinition<"crtr.view.prompt-review.up"> | BindingDefinition<"crtr.view.prompt-review.compare-previous"> | BindingDefinition<"crtr.view.prompt-review.compare-next"> | BindingDefinition<"crtr.view.prompt-review.toggle-mode"> | BindingDefinition<"crtr.view.prompt-review.expand"> | BindingDefinition<"crtr.view.prompt-review.export"> | BindingDefinition<"crtr.view.prompt-review.refresh"> | BindingDefinition<"crtr.view.prompt-review.quit"> | BindingDefinition<"crtr.view.settings.down"> | BindingDefinition<"crtr.view.settings.up"> | BindingDefinition<"crtr.view.settings.cell-previous"> | BindingDefinition<"crtr.view.settings.cell-next"> | BindingDefinition<"crtr.view.settings.refresh"> | BindingDefinition<"crtr.view.settings.quit"> | BindingDefinition<"crtr.view.settings.edit-or-submit"> | BindingDefinition<"crtr.view.settings.cancel-edit"> | BindingDefinition<"crtr.view.workspace-sidebar.down"> | BindingDefinition<"crtr.view.workspace-sidebar.up"> | BindingDefinition<"crtr.view.workspace-sidebar.open"> | BindingDefinition<"crtr.view.workspace-sidebar.refresh"> | BindingDefinition<"crtr.view.workspace-sidebar.quit"> | BindingDefinition<"crtr.view-picker.down"> | BindingDefinition<"crtr.view-picker.up"> | BindingDefinition<"crtr.view-picker.run"> | BindingDefinition<"crtr.view-picker.quit"> | BindingDefinition<"crtr.browse.quit"> | BindingDefinition<"crtr.browse.down"> | BindingDefinition<"crtr.browse.up"> | BindingDefinition<"crtr.browse.first"> | BindingDefinition<"crtr.browse.last"> | BindingDefinition<"crtr.browse.expand-or-child"> | BindingDefinition<"crtr.browse.collapse-or-parent"> | BindingDefinition<"crtr.browse.toggle-fold"> | BindingDefinition<"crtr.browse.tab-next"> | BindingDefinition<"crtr.browse.tab-previous"> | BindingDefinition<"crtr.browse.tab.2" | "crtr.browse.tab.1" | "crtr.browse.tab.3" | "crtr.browse.tab.4" | "crtr.browse.tab.5"> | BindingDefinition<"crtr.browse.close-subtree"> | BindingDefinition<"crtr.browse.confirm-close"> | BindingDefinition<"crtr.browse.sort"> | BindingDefinition<"crtr.browse.scope"> | BindingDefinition<"crtr.browse.residents"> | BindingDefinition<"crtr.browse.preview"> | BindingDefinition<"crtr.browse.search"> | BindingDefinition<"crtr.browse.revive-now"> | BindingDefinition<"crtr.browse.focus"> | BindingDefinition<"crtr.browse.search.cancel"> | BindingDefinition<"crtr.browse.search.commit"> | BindingDefinition<"crtr.browse.search.delete"> | BindingDefinition<"crtr.browse.search.quit"> | BindingDefinition<"crtr.profile.menu.up"> | BindingDefinition<"crtr.profile.menu.down"> | BindingDefinition<"crtr.profile.menu.select"> | BindingDefinition<"crtr.profile.menu.accept-default"> | BindingDefinition<"crtr.profile.menu.abort"> | BindingDefinition<"crtr.profile.menu.slot.2" | "crtr.profile.menu.slot.1" | "crtr.profile.menu.slot.3" | "crtr.profile.menu.slot.4" | "crtr.profile.menu.slot.5" | "crtr.profile.menu.slot.8" | "crtr.profile.menu.slot.6" | "crtr.profile.menu.slot.7" | "crtr.profile.menu.slot.9">)[], BindingDefinition<"crtr.profile.menu.create">, BindingDefinition<"crtr.profile.menu.search-existing">, BindingDefinition<"crtr.profile.menu.use-root">, BindingDefinition<"crtr.profile.menu.set-default">, BindingDefinition<"crtr.profile.menu.add-directory">, BindingDefinition<"crtr.profile.menu.unpin">, BindingDefinition<"crtr.profile.search.up">, BindingDefinition<"crtr.profile.search.down">, BindingDefinition<"crtr.profile.search.pick">, BindingDefinition<"crtr.profile.search.back">, BindingDefinition<"crtr.profile.search.delete">, BindingDefinition<"crtr.profile.search.abort">, BindingDefinition<"crtr.setup.cancel">, BindingDefinition<"crtr.setup.tab-next">, BindingDefinition<"crtr.setup.tab-previous">, BindingDefinition<"crtr.setup.open">, BindingDefinition<"crtr.setup.list-down">, BindingDefinition<"crtr.setup.list-up">, BindingDefinition<"crtr.setup.toggle">, BindingDefinition<"crtr.setup.details">, BindingDefinition<"crtr.setup.advance">, BindingDefinition<"crtr.setup.confirm.accept">, BindingDefinition<"crtr.setup.confirm.back">, BindingDefinition<"crtr.setup.keybindings.edit">, BindingDefinition<"crtr.setup.keybindings.commit-edit">, BindingDefinition<"crtr.setup.keybindings.cancel-edit">, BindingDefinition<"crtr.setup.keybindings.unbind">, BindingDefinition<"crtr.setup.keybindings.reset-row">, BindingDefinition<"crtr.setup.keybindings.reset-all">, BindingDefinition<"crtr.setup.keybindings.save">, BindingDefinition<"crtr.setup.keybindings.discard">, BindingDefinition<"crtr.setup.keybindings.page-up">, BindingDefinition<"crtr.setup.keybindings.page-down">, BindingDefinition<"crtr.setup.keybindings.filter">, BindingDefinition<"crtr.setup.keybindings.filter-delete">, BindingDefinition<"crtr.setup.keybindings.filter-clear">];
 export declare const BINDING_IDS: ReadonlySet<string>;
 export declare const SAFETY_REQUIREMENTS: readonly SafetyRequirement[];
 export {};

package/dist/core/keybindings/catalog.js

@@ -40,13 +40,15 @@ export const BINDING_CATALOG = Object.freeze([
     b('crtr.tmux.menu.issue.bug', 'Global tmux', 'Create bug', 'Create a bug issue.', ['b'], 'tmux-menu-selector', ['tmux.menu.issue']),
     b('crtr.tmux.node.next', 'Global tmux', 'Next node', 'Focus the next canvas node.', ['alt+]'], 'host-global', ['tmux.root']),
     b('crtr.tmux.node.previous', 'Global tmux', 'Previous node', 'Focus the previous canvas node.', ['alt+['], 'host-global', ['tmux.root']),
+    b('crtr.tmux.inbox.toggle', 'Global tmux', 'Toggle inbox', 'Open or close the human inbox popup.', ['alt+i'], 'host-global', ['tmux.root']),
     b('crtr.tmux.view.next', 'Global tmux', 'Next view', 'Focus the next view.', ['alt+v > ]'], 'tmux-sequence', ['tmux.root']),
     b('crtr.tmux.view.previous', 'Global tmux', 'Previous view', 'Focus the previous view.', ['alt+v > ['], 'tmux-sequence', ['tmux.root']),
     b('crtr.attach.detach', 'Attach', 'Detach', 'Detach from the node.', ['ctrl+d'], 'host-global', ATTACH_CONTEXTS),
     b('crtr.attach.clear-or-detach', 'Attach', 'Clear or detach', 'Clear input or detach when input is empty.', ['ctrl+c'], 'host-global', ATTACH_CONTEXTS),
     b('crtr.attach.graph.toggle', 'Attach', 'Toggle graph', 'Open or close the graph overlay.', ['alt+g'], 'host-global', ATTACH_CONTEXTS),
-    b('crtr.attach.model-ladder.next', 'Attach', 'Next model ladder', 'Move to the next model ladder rung.', ['alt+shift+m'], 'host-global', ATTACH_CONTEXTS),
-    b('crtr.mode.cycle', 'Attach', 'Cycle mode', 'Cycle the active agent mode.', ['alt+m'], 'host-global', ATTACH_CONTEXTS),
+    b('crtr.attach.model-ladder.next', 'Attach', 'Next model ladder', 'Move to the next model ladder rung.', ['alt+m'], 'host-global', ATTACH_CONTEXTS),
+    b('crtr.attach.model-ladder.previous', 'Attach', 'Previous model ladder', 'Move to the previous model ladder rung.', ['alt+shift+m'], 'host-global', ATTACH_CONTEXTS),
+    b('crtr.mode.cycle', 'Attach', 'Cycle mode', 'Cycle the active agent mode.', ['alt+shift+p'], 'host-global', ATTACH_CONTEXTS),
     b('crtr.graph.down', 'GRAPH', 'Move down', 'Move to the next graph row.', ['j'], 'terminal', ['graph']),
     b('crtr.graph.up', 'GRAPH', 'Move up', 'Move to the previous graph row.', ['k'], 'terminal', ['graph']),
     b('crtr.graph.first', 'GRAPH', 'First row', 'Move to the first graph row.', ['g'], 'terminal', ['graph']),

package/dist/core/keybindings/inbox.d.ts

@@ -0,0 +1,21 @@
+import type { BindingId } from './catalog.js';
+import type { BindingResolution } from './types.js';
+/** The single source of truth for how every pending-interaction surface names
+ *  the inbox shortcut. Resolves the live `crtr.tmux.inbox.toggle` gestures and
+ *  returns the formatted label(s) — joined with ' / ' when multiple, matching
+ *  crouter's `formatBinding` convention — or null when the binding is disabled.
+ *  Bindings default to the user's resolved config so a bare call reflects
+ *  current state; callers holding a live snapshot (e.g. the attach viewer) pass
+ *  it so a `/reload` rebind is honored. */
+export declare function inboxShortcut(bindings?: BindingResolution<BindingId>): string | null;
+/** Closed-inbox footer affordance: "<shortcut> inbox", or the CLI fallback
+ *  `hl inbox open` when the binding is disabled. */
+export declare function inboxOpenHint(bindings?: BindingResolution<BindingId>): string;
+/** Bare token naming the inbox affordance for a parenthetical — the resolved
+ *  shortcut (e.g. `Alt+I`), or the backtick-quoted CLI form when disabled. Use
+ *  where prose reads "the inbox popup (<hint>)". */
+export declare function inboxPopupHint(bindings?: BindingResolution<BindingId>): string;
+/** Imperative clause telling the human how to open the inbox — "press
+ *  <shortcut> (or run `hl inbox open` at a terminal)", or just the CLI form
+ *  when the binding is disabled. */
+export declare function inboxOpenInstruction(bindings?: BindingResolution<BindingId>): string;

package/dist/core/keybindings/inbox.js

@@ -0,0 +1,35 @@
+import { formatGesture } from './match.js';
+import { resolveUserKeybindings } from './resolve.js';
+const INBOX_TOGGLE = 'crtr.tmux.inbox.toggle';
+/** The single source of truth for how every pending-interaction surface names
+ *  the inbox shortcut. Resolves the live `crtr.tmux.inbox.toggle` gestures and
+ *  returns the formatted label(s) — joined with ' / ' when multiple, matching
+ *  crouter's `formatBinding` convention — or null when the binding is disabled.
+ *  Bindings default to the user's resolved config so a bare call reflects
+ *  current state; callers holding a live snapshot (e.g. the attach viewer) pass
+ *  it so a `/reload` rebind is honored. */
+export function inboxShortcut(bindings = resolveUserKeybindings()) {
+    const gestures = bindings.gestures(INBOX_TOGGLE);
+    return gestures.length > 0 ? gestures.map(formatGesture).join(' / ') : null;
+}
+/** Closed-inbox footer affordance: "<shortcut> inbox", or the CLI fallback
+ *  `hl inbox open` when the binding is disabled. */
+export function inboxOpenHint(bindings) {
+    const shortcut = inboxShortcut(bindings);
+    return shortcut !== null ? `${shortcut} inbox` : 'hl inbox open';
+}
+/** Bare token naming the inbox affordance for a parenthetical — the resolved
+ *  shortcut (e.g. `Alt+I`), or the backtick-quoted CLI form when disabled. Use
+ *  where prose reads "the inbox popup (<hint>)". */
+export function inboxPopupHint(bindings) {
+    return inboxShortcut(bindings) ?? '`hl inbox open`';
+}
+/** Imperative clause telling the human how to open the inbox — "press
+ *  <shortcut> (or run `hl inbox open` at a terminal)", or just the CLI form
+ *  when the binding is disabled. */
+export function inboxOpenInstruction(bindings) {
+    const shortcut = inboxShortcut(bindings);
+    return shortcut !== null
+        ? `press ${shortcut} (or run \`hl inbox open\` at a terminal)`
+        : 'run `hl inbox open` at a terminal';
+}