@crouton-kit/crouter 0.3.83 → 0.3.84

package/dist/core/__tests__/tmux-surface.test.js

@@ -17,11 +17,12 @@
 //      importers are placement.ts + tmux-chrome.ts (tmux.ts itself excluded).
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, mkdtempSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, basename } from 'node:path';
-import { installTmuxBindings } from '../runtime/tmux-chrome.js';
+import { installTmuxBindings, legacyInboxKeyFile } from '../runtime/tmux-chrome.js';
 import { resolveKeybindings } from '../keybindings/index.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SRC_ROOT = join(__dirname, '..', '..'); // .../src
@@ -149,6 +150,8 @@ test('tmux installer remaps owned pairs and preserves occupied user bindings', (
         assert.ok(first.installed.some((pair) => pair.table === 'root' && pair.key === 'M-]'));
         assert.match(tmuxBinding(socket, 'root', 'M-c') ?? '', /display-menu/);
         assert.match(tmuxBinding(socket, 'root', 'M-v') ?? '', /switch-client/);
+        // The inbox toggle installs at its default key (alt+i → M-i) in the same sweep.
+        assert.match(tmuxBinding(socket, 'root', 'M-i') ?? '', /hl inbox toggle/);
         const remapped = installTmuxBindings(resolveKeybindings({
             'crtr.tmux.menu.open': ['alt+shift+z'],
             'crtr.tmux.menu.graph': ['shift+z'],
@@ -185,3 +188,178 @@ test('tmux installer remaps owned pairs and preserves occupied user bindings', (
         isolatedTmux(socket, ['kill-server']);
     }
 });
+test('tmux installer rebinds/disables the inbox toggle and adopts the legacy hl-owned M-i', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-inbox-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socket = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' }).stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    const priorState = process.env['XDG_STATE_HOME'];
+    const stateHome = mkdtempSync(join(tmpdir(), 'crtr-inbox-state-'));
+    process.env['TMUX'] = `${socket},1,0`;
+    process.env['XDG_STATE_HOME'] = stateHome;
+    try {
+        // Fixture: a surviving hl-owned M-i binding plus its flat inbox-key file —
+        // the arrangement crouter's key ownership replaces — with no crouter
+        // manifest yet. First reconciliation must take over M-i (crouter's inbox
+        // toggle, tracked in the manifest) rather than report it foreign.
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-i', 'run-shell', '-b', 'hl inbox toggle --quiet --tmux-socket "#{socket_path}"']);
+        const legacyKeyDir = join(stateHome, 'humanloop');
+        mkdirSync(legacyKeyDir, { recursive: true });
+        const legacyKeyFile = join(legacyKeyDir, 'inbox-key');
+        writeFileSync(legacyKeyFile, 'M-i\n');
+        const first = installTmuxBindings(resolveKeybindings());
+        assert.equal(first.ok, true, JSON.stringify(first.diagnostics));
+        // Adopted, not foreign: M-i is now crouter's inbox toggle, no occupied diag.
+        assert.ok(!first.diagnostics.some((d) => d.bindingId === 'crtr.tmux.inbox.toggle'), JSON.stringify(first.diagnostics));
+        assert.match(tmuxBinding(socket, 'root', 'M-i') ?? '', /hl inbox toggle/);
+        assert.ok(first.installed.some((pair) => pair.table === 'root' && pair.key === 'M-i'));
+        // The obsolete flat key file is deleted by the cleanup.
+        assert.equal(existsSync(legacyKeyFile), false, 'legacy inbox-key file should be removed');
+        // Rebind to a custom key: the old M-i (crouter-owned via the manifest) is
+        // dropped and the new key carries the same inbox command.
+        const rebound = installTmuxBindings(resolveKeybindings({ 'crtr.tmux.inbox.toggle': ['alt+j'] }));
+        assert.equal(rebound.ok, true, JSON.stringify(rebound.diagnostics));
+        assert.equal(tmuxBinding(socket, 'root', 'M-i'), null);
+        assert.match(tmuxBinding(socket, 'root', 'M-j') ?? '', /hl inbox toggle/);
+        // Disable via empty gesture list: no inbox key installed at all, no error.
+        const disabled = installTmuxBindings(resolveKeybindings({ 'crtr.tmux.inbox.toggle': [] }));
+        assert.equal(disabled.ok, true, JSON.stringify(disabled.diagnostics));
+        assert.equal(tmuxBinding(socket, 'root', 'M-i'), null);
+        assert.equal(tmuxBinding(socket, 'root', 'M-j'), null);
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        if (priorState === undefined)
+            delete process.env['XDG_STATE_HOME'];
+        else
+            process.env['XDG_STATE_HOME'] = priorState;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});
+test('tmux installer adopts the legacy hl-owned inbox key when a crouter manifest already exists', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-inbox-upgrade-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socket = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' }).stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    const priorState = process.env['XDG_STATE_HOME'];
+    const stateHome = mkdtempSync(join(tmpdir(), 'crtr-inbox-state-'));
+    process.env['TMUX'] = `${socket},1,0`;
+    process.env['XDG_STATE_HOME'] = stateHome;
+    try {
+        // Contract: an hl-owned inbox binding not tracked in the manifest must be
+        // adopted even when a crouter manifest already exists. Force
+        // `manifest.existed = true` with a non-empty option, then seed an untracked
+        // hl-owned M-i binding + its key file.
+        isolatedTmux(socket, ['set-option', '-s', '@crtr_keybindings_manifest', '[]']);
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-i', 'run-shell', '-b', 'hl inbox toggle --quiet --tmux-socket "#{socket_path}"']);
+        const legacyKeyDir = join(stateHome, 'humanloop');
+        mkdirSync(legacyKeyDir, { recursive: true });
+        const legacyKeyFile = join(legacyKeyDir, 'inbox-key');
+        writeFileSync(legacyKeyFile, 'M-i\n');
+        const result = installTmuxBindings(resolveKeybindings());
+        assert.equal(result.ok, true, JSON.stringify(result.diagnostics));
+        // Cleanup ran despite the existing manifest: M-i is crouter's tracked inbox
+        // toggle, no occupied/foreign diagnostic, and the key file is gone.
+        assert.ok(!result.diagnostics.some((d) => d.bindingId === 'crtr.tmux.inbox.toggle'), JSON.stringify(result.diagnostics));
+        assert.match(tmuxBinding(socket, 'root', 'M-i') ?? '', /hl inbox toggle/);
+        assert.ok(result.installed.some((pair) => pair.table === 'root' && pair.key === 'M-i'));
+        assert.equal(existsSync(legacyKeyFile), false, 'legacy inbox-key file should be removed');
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        if (priorState === undefined)
+            delete process.env['XDG_STATE_HOME'];
+        else
+            process.env['XDG_STATE_HOME'] = priorState;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});
+test('tmux installer removes a legacy custom inbox key recorded in the state file', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-inbox-custom-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socket = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' }).stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    const priorState = process.env['XDG_STATE_HOME'];
+    const stateHome = mkdtempSync(join(tmpdir(), 'crtr-inbox-state-'));
+    process.env['TMUX'] = `${socket},1,0`;
+    process.env['XDG_STATE_HOME'] = stateHome;
+    try {
+        // Contract: an hl-owned binding at a non-default key named by the state
+        // file must be located via that file and unbound (its value is never
+        // imported as a crouter gesture), leaving crouter's configured M-i the only
+        // installed inbox key even when a crouter manifest already exists.
+        isolatedTmux(socket, ['set-option', '-s', '@crtr_keybindings_manifest', '[]']);
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-z', 'run-shell', '-b', 'hl inbox toggle --quiet --tmux-socket "#{socket_path}"']);
+        const legacyKeyDir = join(stateHome, 'humanloop');
+        mkdirSync(legacyKeyDir, { recursive: true });
+        const legacyKeyFile = join(legacyKeyDir, 'inbox-key');
+        writeFileSync(legacyKeyFile, 'M-z\n');
+        const result = installTmuxBindings(resolveKeybindings());
+        assert.equal(result.ok, true, JSON.stringify(result.diagnostics));
+        // The orphaned custom-key binding is gone — not left as an untracked live
+        // shortcut — and was not imported into crouter's config (M-z stays unbound).
+        assert.equal(tmuxBinding(socket, 'root', 'M-z'), null, 'legacy custom key must be unbound');
+        assert.match(tmuxBinding(socket, 'root', 'M-i') ?? '', /hl inbox toggle/);
+        assert.equal(existsSync(legacyKeyFile), false, 'legacy inbox-key file should be removed');
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        if (priorState === undefined)
+            delete process.env['XDG_STATE_HOME'];
+        else
+            process.env['XDG_STATE_HOME'] = priorState;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});
+test('legacyInboxKeyFile resolves under the OS home when HOME and XDG_STATE_HOME are unset', () => {
+    const priorHome = process.env['HOME'];
+    const priorState = process.env['XDG_STATE_HOME'];
+    delete process.env['HOME'];
+    delete process.env['XDG_STATE_HOME'];
+    try {
+        const resolved = legacyInboxKeyFile();
+        // Must be an absolute OS-home path (via os.homedir()), never cwd-relative —
+        // otherwise cleanup would miss the real file and could delete an unrelated
+        // file under the current directory.
+        assert.ok(resolved.startsWith('/'), `expected an absolute path, got ${resolved}`);
+        assert.ok(resolved.endsWith(join('.local', 'state', 'humanloop', 'inbox-key')), resolved);
+        assert.ok(!resolved.startsWith(join(process.cwd(), '.local')), `must not resolve relative to cwd: ${resolved}`);
+    }
+    finally {
+        if (priorHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = priorHome;
+        if (priorState === undefined)
+            delete process.env['XDG_STATE_HOME'];
+        else
+            process.env['XDG_STATE_HOME'] = priorState;
+    }
+});

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

@@ -22,11 +22,29 @@ export declare function currentBootIdentity(now?: number): BootIdentity;
  *  on either side (non-Linux dev) does it fall back to the epoch-drift window.
  *  Unit-testable without real uptime/fs. */
 export declare function bootChanged(current: BootIdentity, known: BootIdentity | null): boolean;
+/** POSITIVE proof that `current` is the SAME boot the persisted `known` marker
+ *  recorded — as distinct from `!bootChanged(...)`, which is merely "no change
+ *  detected" and is also true when there is no history, a malformed marker, or
+ *  only the coarse wall-clock fallback to go on. Proof requires an exact kernel
+ *  `boot_id` present and equal on BOTH sides. This gates the one-time legacy
+ *  identity migration: that sweep rewrites a legacy row's baseline as
+ *  `<currentBootId>#<ticks>`, permanently blessing the recorded pid as a
+ *  current-boot process, so it must run ONLY when we can prove the recorded pid
+ *  really is from this boot — never on a mere ticks match under an unproven
+ *  boot (the epoch fallback or an absent/malformed marker could otherwise bless
+ *  an unrelated stranger process that happens to collide on pid+ticks). */
+export declare function bootProvenSame(current: BootIdentity, known: BootIdentity | null): boolean;
 export interface BootReconcileResult {
     /** True when a boot change was detected (and, therefore, pids were cleared). */
     changed: boolean;
     /** node_ids whose stale `pi_pid` was cleared. */
     cleared: string[];
+    /** True ONLY when this run positively proved same-boot provenance against the
+     *  persisted marker (exact `boot_id` present and equal on both sides). Gates
+     *  the legacy identity migration — see `bootProvenSame`. False on a boot
+     *  change, a first-ever/absent/malformed marker, or a wall-clock-fallback
+     *  match. */
+    sameBootProven: boolean;
 }
 /** Idempotent and safe to call from every revive entry point (daemon startup,
  *  reviveNode): compares the current boot's identity against the last one
@@ -47,3 +65,29 @@ export interface BootReconcileResult {
  *  `current` defaults to the real identity; tests inject a synthetic one against
  *  an isolated CRTR_HOME to simulate a boot change without a real reboot. */
 export declare function reconcileBootLiveness(current?: BootIdentity): BootReconcileResult;
+/** The one-time legacy pid-identity migration, injected into the startup
+ *  composition. In production this is `migrateLegacyPidIdentities` from
+ *  canvas.ts; it is a parameter (not a direct import) because canvas.ts already
+ *  depends on pid.ts which depends on this module — injecting it keeps the
+ *  dependency one-directional and lets tests exercise this exact composition. */
+export type MigrateLegacyPidIdentities = (captureIdentity?: (pid: number) => string | undefined) => {
+    migrated: string[];
+};
+export interface BootStartupResult {
+    /** The pid-liveness reconciliation result (boot-change sweep + provenance). */
+    reconcile: BootReconcileResult;
+    /** node_ids whose legacy identity baseline was migrated — empty when the
+     *  provenance gate skipped the sweep. */
+    migrated: string[];
+}
+/** The daemon's one-time startup boot composition, the single source of truth
+ *  for its ORDERING and GATE: reconcile pid liveness FIRST (clearing any pids
+ *  recorded before this boot), then run the legacy identity migration ONLY when
+ *  reconciliation positively PROVED same-boot provenance (`sameBootProven`).
+ *  Both `runDaemon` and the migration-gate regression tests call this, so a
+ *  revert that inverts the gate, drops it, or reorders migration ahead of
+ *  reconciliation is caught here rather than only in a test-side duplicate.
+ *
+ *  `migrate` is injected (see `MigrateLegacyPidIdentities`); `current` and
+ *  `captureIdentity` pass through to the two steps for test injection. */
+export declare function reconcileAndMigrateBoot(migrate: MigrateLegacyPidIdentities, current?: BootIdentity, captureIdentity?: (pid: number) => string | undefined): BootStartupResult;

package/dist/core/canvas/boot.js

@@ -79,6 +79,23 @@ export function bootChanged(current, known) {
     }
     return Math.abs(current.bootEpochMs - known.bootEpochMs) > BOOT_EPOCH_TOLERANCE_MS;
 }
+/** POSITIVE proof that `current` is the SAME boot the persisted `known` marker
+ *  recorded — as distinct from `!bootChanged(...)`, which is merely "no change
+ *  detected" and is also true when there is no history, a malformed marker, or
+ *  only the coarse wall-clock fallback to go on. Proof requires an exact kernel
+ *  `boot_id` present and equal on BOTH sides. This gates the one-time legacy
+ *  identity migration: that sweep rewrites a legacy row's baseline as
+ *  `<currentBootId>#<ticks>`, permanently blessing the recorded pid as a
+ *  current-boot process, so it must run ONLY when we can prove the recorded pid
+ *  really is from this boot — never on a mere ticks match under an unproven
+ *  boot (the epoch fallback or an absent/malformed marker could otherwise bless
+ *  an unrelated stranger process that happens to collide on pid+ticks). */
+export function bootProvenSame(current, known) {
+    return (known !== null &&
+        current.bootId !== null &&
+        known.bootId !== null &&
+        current.bootId === known.bootId);
+}
 const BOOT_MARKER_KEY = 'boot_identity';
 function readBootMarker(db) {
     const row = db
@@ -129,8 +146,9 @@ export function reconcileBootLiveness(current = currentBootIdentity()) {
         if (!bootChanged(current, known)) {
             if (known === null)
                 writeBootMarker(db, current); // seed first-ever marker
+            const sameBootProven = bootProvenSame(current, known);
             db.exec('COMMIT');
-            return { changed: false, cleared: [] };
+            return { changed: false, cleared: [], sameBootProven };
         }
         const rows = db
             .prepare('SELECT node_id FROM nodes WHERE pi_pid IS NOT NULL')
@@ -148,7 +166,7 @@ export function reconcileBootLiveness(current = currentBootIdentity()) {
         }
         writeBootMarker(db, current);
         db.exec('COMMIT');
-        return { changed: true, cleared };
+        return { changed: true, cleared, sameBootProven: false };
     }
     catch (err) {
         try {
@@ -160,3 +178,18 @@ export function reconcileBootLiveness(current = currentBootIdentity()) {
         throw err;
     }
 }
+/** The daemon's one-time startup boot composition, the single source of truth
+ *  for its ORDERING and GATE: reconcile pid liveness FIRST (clearing any pids
+ *  recorded before this boot), then run the legacy identity migration ONLY when
+ *  reconciliation positively PROVED same-boot provenance (`sameBootProven`).
+ *  Both `runDaemon` and the migration-gate regression tests call this, so a
+ *  revert that inverts the gate, drops it, or reorders migration ahead of
+ *  reconciliation is caught here rather than only in a test-side duplicate.
+ *
+ *  `migrate` is injected (see `MigrateLegacyPidIdentities`); `current` and
+ *  `captureIdentity` pass through to the two steps for test injection. */
+export function reconcileAndMigrateBoot(migrate, current, captureIdentity) {
+    const reconcile = reconcileBootLiveness(current);
+    const migrated = reconcile.sameBootProven ? migrate(captureIdentity).migrated : [];
+    return { reconcile, migrated };
+}

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

@@ -50,6 +50,46 @@ export declare function recordPid(nodeId: string, pid: number): void;
  *  reuses the pid namespace could compare its own fresh pid against a STALE
  *  identity left over from the pid this row held before. */
 export declare function clearPid(nodeId: string): void;
+/** ONE-TIME completion of the boot-scoped-identity format migration, run once
+ *  at daemon startup (the natural boot-reconciliation chokepoint, right after
+ *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
+ *  lane only TOLERATES: a broker that survives an in-place crouter upgrade
+ *  keeps its old `lstart#ticks` row indefinitely (`recordPid` only fires on
+ *  launch/revive/session_start), so the cross-boot ticks-collision exposure the
+ *  boot-scoped base was added to close never provably shuts for those rows.
+ *
+ *  For every row whose RECORDED identity is legacy-format while this platform
+ *  now composes new-format (a readable kernel boot_id):
+ *   - if the recorded pid's CURRENT live identity matches the recorded one via
+ *     the migration lane (same live process, `identitiesMatch` true) AND that
+ *     current identity is itself boot-scoped — re-record it with the new
+ *     composer, completing the migration in place;
+ *   - otherwise (pid gone, probe failed, reused — no match, or no readable
+ *     boot_id for it) — leave the row untouched for the normal liveness
+ *     handling that already runs each tick.
+ *
+ *  After this runs once, the legacy compare lane only ever engages for
+ *  genuinely no-boot_id platforms. NOT a per-caller reconciliation layer — a
+ *  single startup sweep. `captureIdentity` is injectable for unit tests.
+ *
+ *  GATED on proven same-boot provenance by its caller (daemon startup runs it
+ *  only when `reconcileBootLiveness` returned `sameBootProven` — see
+ *  `bootProvenSame`). This is what makes a bare ticks match safe to bless as a
+ *  current-boot identity: without that proof an equal-ticks collision with an
+ *  unrelated process from a DIFFERENT boot could be rewritten as
+ *  `<currentBootId>#<ticks>`, permanently baptizing a stranger.
+ *
+ *  Not transactional by design: it never HOLDS the write lock across the (slow,
+ *  per-row) `ps` probe. Each re-record is a compare-and-swap single-row UPDATE
+ *  constrained by ALL three snapshotted values (`node_id`, `pi_pid`,
+ *  `pi_pid_identity`), counted only when a row actually changed. So if the old
+ *  broker exits and a concurrent revive atomically records a fresh
+ *  `(pi_pid, pi_pid_identity)` between this sweep's probe and its update, the
+ *  CAS matches zero rows and the migration is skipped rather than clobbering
+ *  the newer identity with the stale one. */
+export declare function migrateLegacyPidIdentities(captureIdentity?: (pid: number) => string | undefined): {
+    migrated: string[];
+};
 /** All rows, optionally filtered by status. */
 export declare function listNodes(filter?: {
     status?: NodeStatus | NodeStatus[];

package/dist/core/canvas/canvas.js

@@ -7,7 +7,7 @@
 import { existsSync, readFileSync, renameSync, readdirSync, rmSync, openSync, writeSync, fsyncSync, closeSync, statSync, } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { openDb } from './db.js';
-import { isPidAlive, capturePidIdentities } from './pid.js';
+import { isPidAlive, capturePidIdentities, identitiesMatch, isLegacyTicksIdentity, isBootScopedIdentity, } from './pid.js';
 import { cancelTriggersFor } from './triggers.js';
 import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, } from './paths.js';
 // ---------------------------------------------------------------------------
@@ -272,6 +272,70 @@ export function recordPid(nodeId, pid) {
 export function clearPid(nodeId) {
     openDb().prepare('UPDATE nodes SET pi_pid = NULL, pi_pid_identity = NULL WHERE node_id = ?').run(nodeId);
 }
+/** ONE-TIME completion of the boot-scoped-identity format migration, run once
+ *  at daemon startup (the natural boot-reconciliation chokepoint, right after
+ *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
+ *  lane only TOLERATES: a broker that survives an in-place crouter upgrade
+ *  keeps its old `lstart#ticks` row indefinitely (`recordPid` only fires on
+ *  launch/revive/session_start), so the cross-boot ticks-collision exposure the
+ *  boot-scoped base was added to close never provably shuts for those rows.
+ *
+ *  For every row whose RECORDED identity is legacy-format while this platform
+ *  now composes new-format (a readable kernel boot_id):
+ *   - if the recorded pid's CURRENT live identity matches the recorded one via
+ *     the migration lane (same live process, `identitiesMatch` true) AND that
+ *     current identity is itself boot-scoped — re-record it with the new
+ *     composer, completing the migration in place;
+ *   - otherwise (pid gone, probe failed, reused — no match, or no readable
+ *     boot_id for it) — leave the row untouched for the normal liveness
+ *     handling that already runs each tick.
+ *
+ *  After this runs once, the legacy compare lane only ever engages for
+ *  genuinely no-boot_id platforms. NOT a per-caller reconciliation layer — a
+ *  single startup sweep. `captureIdentity` is injectable for unit tests.
+ *
+ *  GATED on proven same-boot provenance by its caller (daemon startup runs it
+ *  only when `reconcileBootLiveness` returned `sameBootProven` — see
+ *  `bootProvenSame`). This is what makes a bare ticks match safe to bless as a
+ *  current-boot identity: without that proof an equal-ticks collision with an
+ *  unrelated process from a DIFFERENT boot could be rewritten as
+ *  `<currentBootId>#<ticks>`, permanently baptizing a stranger.
+ *
+ *  Not transactional by design: it never HOLDS the write lock across the (slow,
+ *  per-row) `ps` probe. Each re-record is a compare-and-swap single-row UPDATE
+ *  constrained by ALL three snapshotted values (`node_id`, `pi_pid`,
+ *  `pi_pid_identity`), counted only when a row actually changed. So if the old
+ *  broker exits and a concurrent revive atomically records a fresh
+ *  `(pi_pid, pi_pid_identity)` between this sweep's probe and its update, the
+ *  CAS matches zero rows and the migration is skipped rather than clobbering
+ *  the newer identity with the stale one. */
+export function migrateLegacyPidIdentities(captureIdentity = (pid) => capturePidIdentities([pid])?.get(pid)) {
+    const db = openDb();
+    const rows = db
+        .prepare('SELECT node_id, pi_pid, pi_pid_identity FROM nodes WHERE pi_pid IS NOT NULL AND pi_pid_identity IS NOT NULL')
+        .all();
+    // Compare-and-swap: rewrite only if the row STILL carries the exact pid +
+    // legacy identity we probed. A concurrent revive between probe and update
+    // records a new (pi_pid, pi_pid_identity) pair, so this WHERE fails to match
+    // and we skip rather than clobber the fresh baseline.
+    const upd = db.prepare('UPDATE nodes SET pi_pid_identity = ? WHERE node_id = ? AND pi_pid = ? AND pi_pid_identity = ?');
+    const migrated = [];
+    for (const row of rows) {
+        if (!isLegacyTicksIdentity(row.pi_pid_identity))
+            continue;
+        const current = captureIdentity(row.pi_pid);
+        if (current === undefined)
+            continue; // pid gone / probe failed → normal liveness handling
+        if (!isBootScopedIdentity(current))
+            continue; // no readable boot_id for it → nothing to upgrade
+        if (!identitiesMatch(current, row.pi_pid_identity))
+            continue; // reused → leave to liveness
+        const res = upd.run(current, row.node_id, row.pi_pid, row.pi_pid_identity);
+        if (res.changes > 0)
+            migrated.push(row.node_id); // skipped if a concurrent revive re-recorded
+    }
+    return { migrated };
+}
 /** All rows, optionally filtered by status. */
 export function listNodes(filter) {
     const db = openDb();

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

@@ -123,6 +123,49 @@ export declare function isRecordedPidAlive(pid: number | null | undefined, expec
  *  Guards `pid` before signaling (review nit, crouter#98): never hit pid 0
  *  (which means "my own group") or a negative/non-integer value. */
 export declare function killProcessGroup(pid: number, signal?: NodeJS.Signals): void;
+/** 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 declare function makeBootIdCache(read: () => string | null, now?: () => number, negativeTtlMs?: number): () => string | null;
+/** 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 declare function isLegacyTicksIdentity(identity: string): boolean;
+/** 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 declare function isBootScopedIdentity(identity: string): boolean;
+/** 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 declare function composeIdentity(pid: number, lstart: string, deps?: {
+    ticks?: string | null;
+    bootId?: string | null;
+}): string;
 /** Every transitive descendant of `rootPid`, discovered by walking `ps`'s
  *  pid/ppid table (BFS) — NOT process-GROUP membership. This is the fix for
  *  crouton-labs/crouter#98: the pi SDK's bash tool spawns its shell child with

package/dist/core/canvas/pid.js

@@ -271,16 +271,56 @@ function procStartTicks(pid) {
         return null;
     }
 }
+/** 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 it is read ONCE and cached, rather than
- *  re-read for every row of a whole-process-table `ps` scan. `undefined` = not
- *  yet read; `null` = read and absent (non-Linux / no procfs). */
-let cachedBootId;
-function bootIdBase() {
-    if (cachedBootId === undefined)
-        cachedBootId = readKernelBootId();
-    return cachedBootId;
+ *  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
@@ -300,11 +340,17 @@ function bootIdBase() {
  *     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. */
-function composeIdentity(pid, lstart) {
-    const ticks = procStartTicks(pid);
+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;
-    return `${bootIdBase() ?? lstart}#${ticks}`;
+    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/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,6 +17,7 @@ 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', 'model-ladder.previous']),
     'crtr.mode.cycle',