@north-light/crouter 0.3.154

package/dist/core/__tests__/test-runner-cheap-sharding.test.js

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import { readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+// Regression coverage for the PR #386 cheap-lane correction: the default (no
+// file argument) `cheap` selection can no longer fit its aggregate ordinary
+// duration inside one 90s Actions wall (see notes/pr386 diagnosis), so it
+// splits into ORDINARY_SHARDS deterministic, path-hash-stable shards. These
+// tests prove the split is duration-blind, disjoint, and complete; that each
+// shard's timeout is capped correctly; that default cheap sharding activates
+// only for the true default selection; that the forbidden cross-invocation
+// flags are rejected while it is active; and that a targeted single-file
+// cheap selection still runs as one unsharded invocation.
+import { cheapShardTimeoutMs, findTestFiles, hasForbiddenCrossInvocationFlag, isDefaultCheapSelection, laneOf, ORDINARY_SHARDS, pathShard, runTier, } from '../../../scripts/test-runner.mjs';
+test('the default ordinary partition is duration-blind, disjoint, and complete', async () => {
+    const ordinaryFiles = (await findTestFiles()).filter((file) => laneOf(file) === 'ordinary');
+    assert.ok(ordinaryFiles.length > 0, 'expected at least one ordinary-lane file to partition');
+    const shards = Array.from({ length: ORDINARY_SHARDS }, (_, shardIndex) => ordinaryFiles.filter((file) => pathShard(file, ORDINARY_SHARDS) === shardIndex));
+    // Complete: every ordinary file lands in exactly one shard.
+    const union = new Set(shards.flat());
+    assert.equal(union.size, ordinaryFiles.length, 'every ordinary file must appear in the union of shards');
+    // Disjoint: no file appears in more than one shard.
+    for (const file of ordinaryFiles) {
+        const memberships = shards.filter((shard) => shard.includes(file)).length;
+        assert.equal(memberships, 1, `${file} must belong to exactly one shard, got ${memberships}`);
+    }
+    // Stable: membership depends only on the path string, never on measured
+    // duration or file order. Pin fixed path→shard vectors rather than
+    // comparing a call against an immediately repeated call to itself, which
+    // cannot catch an unstable algorithm or membership drift.
+    assert.equal(pathShard('src/core/__tests__/test-runner-cheap-sharding.test.ts', ORDINARY_SHARDS), 1);
+    assert.equal(pathShard('src/core/keybindings/__tests__/bespoke-consumers.test.ts', ORDINARY_SHARDS), 0);
+    assert.equal(pathShard('src/core/__tests__/fixtures/spawn-proof-target.test.ts', ORDINARY_SHARDS), 0);
+});
+test('cheapShardTimeoutMs caps a shard at the 90s tier wall and never past the remaining full-suite budget', () => {
+    const now = Date.now();
+    // No full-suite deadline (a bare `test:cheap`): every shard gets the full 90s.
+    assert.equal(cheapShardTimeoutMs(Infinity, now), 90_000);
+    // Full-suite budget has plenty of room left: still capped at 90s.
+    assert.equal(cheapShardTimeoutMs(now + 600_000, now), 90_000);
+    // Full-suite budget is tighter than 90s: the shard is capped to what remains.
+    assert.equal(cheapShardTimeoutMs(now + 50_000, now), 50_000);
+    // Full-suite budget is already exhausted: the shard gets a non-positive
+    // timeout so the caller can fail fast instead of starting a doomed shard.
+    assert.ok(cheapShardTimeoutMs(now - 1, now) <= 0);
+});
+test('default cheap sharding activates only for the true default (no file argument) cheap selection', () => {
+    assert.equal(isDefaultCheapSelection('cheap', false), true);
+    assert.equal(isDefaultCheapSelection('cheap', true), false);
+    assert.equal(isDefaultCheapSelection('fast', false), false);
+    assert.equal(isDefaultCheapSelection('process', false), false);
+    assert.equal(isDefaultCheapSelection('live', false), false);
+    assert.equal(isDefaultCheapSelection('heavy', false), false);
+});
+test('hasForbiddenCrossInvocationFlag recognizes --test-shard and --test-global-setup in both bare and = forms', () => {
+    assert.equal(hasForbiddenCrossInvocationFlag(['--test-shard', '1/2']), true);
+    assert.equal(hasForbiddenCrossInvocationFlag(['--test-shard=1/2']), true);
+    assert.equal(hasForbiddenCrossInvocationFlag(['--test-global-setup=./setup.mjs']), true);
+    assert.equal(hasForbiddenCrossInvocationFlag(['--test-global-setup', './setup.mjs']), true);
+    assert.equal(hasForbiddenCrossInvocationFlag(['--test-name-pattern=foo']), false);
+    assert.equal(hasForbiddenCrossInvocationFlag([]), false);
+});
+test('runTier rejects --test-shard and --test-global-setup while default cheap partitioning is active', async () => {
+    await assert.rejects(() => runTier('cheap', ['--test-shard=1/2']), /default cheap selection.*path-hash-stable shards/);
+    await assert.rejects(() => runTier('cheap', ['--test-global-setup=./setup.mjs']), /default cheap selection.*path-hash-stable shards/);
+    await assert.rejects(() => runTier('cheap', ['--test-global-setup', './setup.mjs']), /default cheap selection.*path-hash-stable shards/);
+});
+test('a targeted single-file cheap selection stays a single unsharded invocation and its target really executes', async () => {
+    // This is a real explicit-file cheap invocation (the same path a caller
+    // takes with `npm run test:full:cheap -- <file>`), proving the targeted
+    // path still runs the file directly rather than through the shard loop.
+    // The target is a dedicated fixture (fixtures/spawn-proof-target.test.ts)
+    // that writes an observable marker file when asked, so this regression can
+    // tell "the spawned file's own test body actually ran" apart from "the
+    // child process merely exited 0" — the two were indistinguishable under
+    // the bug this guards: `run()`'s spawn inherited NODE_TEST_CONTEXT /
+    // NODE_TEST_WORKER_ID from this already-running node:test process, which
+    // made the spawned child's own recursion guard silently skip the target
+    // file while the process still exited 0. Asserting only `code === 0` (as
+    // this test previously did) would also pass with that fix reverted.
+    const proofFile = join(tmpdir(), `crtr-test-runner-spawn-proof-${process.pid}-${Date.now()}.txt`);
+    const priorProofEnv = process.env.CRTR_SPAWN_PROOF_FILE;
+    process.env.CRTR_SPAWN_PROOF_FILE = proofFile;
+    try {
+        const code = await runTier('cheap', ['src/core/__tests__/fixtures/spawn-proof-target.test.ts']);
+        assert.equal(code, 0);
+        assert.equal(await readFile(proofFile, 'utf8'), 'ran', 'spawned target must actually execute and write its proof marker');
+    }
+    finally {
+        if (priorProofEnv === undefined)
+            delete process.env.CRTR_SPAWN_PROOF_FILE;
+        else
+            process.env.CRTR_SPAWN_PROOF_FILE = priorProofEnv;
+        await rm(proofFile, { force: true });
+    }
+});

package/dist/core/__tests__/tmux-surface.test.d.ts

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

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

@@ -0,0 +1,470 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/tmux-surface.test.ts
+//
+// STEP 2 of the placement/focus migration: guards on the tmux Surface (driver).
+//
+//   1. The §2.2 HARD DRIVER INVARIANT (GREEN now): every create/placement verb
+//      in the driver — after the broker-host cut gutted the engine-in-pane
+//      relocate verbs (U9 deleted swap-pane/break-pane/join-pane/move-pane),
+//      the survivors are new-window / split-window / respawn-pane — MUST pass an
+//      explicit `-t` target.
+//      Omitting `-t` lets tmux resolve against its GLOBAL current session, which
+//      can leak a pane into a user session — the exact unbidden-window bug this
+//      redesign kills. This guards the bug's blast radius and should pass today.
+//
+//   2. The §5.1 "only placement.ts / tmux-chrome.ts import tmux.ts" lint guard
+//      (ENFORCED as of Step 8): every other module reaches the driver through
+//      placement's re-exports or the tmux-chrome seam, so the only direct
+//      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, 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 { ensureSession } from '../runtime/placement.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
+const TMUX_TS = join(SRC_ROOT, 'core', 'runtime', 'tmux.ts');
+/** The placement verbs the §2.2 invariant governs. (swap-pane/break-pane/
+ *  join-pane/move-pane were deleted with the engine-in-pane host in the broker
+ *  cut; kept in the match set so a regression that re-introduces an untargeted
+ *  one is still caught.) */
+const PLACEMENT_VERBS = [
+    'new-window',
+    'split-window',
+    'swap-pane',
+    'break-pane',
+    'join-pane',
+    'move-pane',
+    'respawn-pane',
+];
+/** The smallest `[ … ]` array literal that encloses `matchIdx`: scan back to the
+ *  nearest `[` (the array open — the verb is always its first element), then
+ *  forward with bracket-depth counting to the matching `]` (handles nested
+ *  arrays like splitWindow's `? [] : ['-h']`). Returns the array source slice. */
+function enclosingArray(src, matchIdx) {
+    let open = matchIdx;
+    while (open >= 0 && src[open] !== '[')
+        open--;
+    assert.ok(open >= 0, `no enclosing [ for the verb at index ${matchIdx}`);
+    let depth = 0;
+    for (let i = open; i < src.length; i++) {
+        if (src[i] === '[')
+            depth++;
+        else if (src[i] === ']') {
+            depth--;
+            if (depth === 0)
+                return src.slice(open, i + 1);
+        }
+    }
+    throw new Error('unbalanced [ ] while bracket-matching the verb array');
+}
+test('§2.2 driver invariant: every placement verb in tmux.ts passes an explicit -t target', () => {
+    const src = readFileSync(TMUX_TS, 'utf8');
+    // Match only the QUOTED JS string forms (`'new-window'`, …) — these are real
+    // args-array elements; the jsdoc prose mentions the verbs unquoted / in
+    // backticks, so this never trips on a comment.
+    const re = new RegExp(`'(${PLACEMENT_VERBS.join('|')})'`, 'g');
+    let found = 0;
+    for (let m = re.exec(src); m !== null; m = re.exec(src)) {
+        found++;
+        const verb = m[1];
+        const arr = enclosingArray(src, m.index);
+        // The invariant is "name a specific tmux object, never fall back to the
+        // GLOBAL current one". `-t` targets a destination; `break-pane` (and the
+        // deleted swap/join/move-pane) instead name their SOURCE with `-s` — which
+        // satisfies the invariant identically. Accept either explicit target flag.
+        assert.ok(arr.includes(`'-t'`) || arr.includes(`'-s'`), `tmux verb '${verb}' is invoked WITHOUT an explicit -t/-s target — a latent ` +
+            `instance of the unbidden-window bug (§2.2). Offending args array:\n${arr}`);
+    }
+    // Sanity: the driver really does contain placement verbs (so a refactor that
+    // renames them can't make this assertion vacuously pass). The broker cut left
+    // three (new-window / split-window / respawn-pane).
+    assert.ok(found >= 3, `expected to scan ≥3 placement verbs, saw ${found}`);
+});
+// ---------------------------------------------------------------------------
+// Lint guard — §5.1, ENFORCED. The driver (tmux.ts) is imported ONLY by
+// placement.ts (the sanctioned model-over-driver, which re-exports the verbs
+// other modules need) and the tmux-chrome.ts chrome seam. Every other module —
+// runtime, daemon, commands, stophook, AND tests — must route through those.
+// ---------------------------------------------------------------------------
+/** Every `.ts` file under `src` (recursively), excluding nothing. */
+function allTsFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        if (statSync(p).isDirectory())
+            out.push(...allTsFiles(p));
+        else if (entry.endsWith('.ts'))
+            out.push(p);
+    }
+    return out;
+}
+/** Files (basename) sanctioned to import the driver, per §2.1. */
+const ALLOWED_IMPORTERS = new Set(['tmux.ts', 'placement.ts', 'placement-tmux.ts', 'tmux-chrome.ts']);
+function importsDriver(file) {
+    const src = readFileSync(file, 'utf8');
+    // A specifier whose basename is exactly `tmux.js` (so `tmux-chrome.js` is NOT
+    // matched). Covers `from '...'` and `import('...')`.
+    return [...src.matchAll(/(?:from|import\s*\()\s*'([^']+)'/g)].some((m) => basename(m[1]) === 'tmux.js');
+}
+test('§5.1 lint: only placement.ts / tmux-chrome.ts import the tmux driver', () => {
+    const offenders = allTsFiles(SRC_ROOT)
+        .filter((f) => !ALLOWED_IMPORTERS.has(basename(f)))
+        .filter(importsDriver)
+        .map((f) => f.slice(SRC_ROOT.length + 1));
+    assert.deepEqual(offenders, [], `modules importing tmux.ts directly: ${offenders.join(', ')}`);
+});
+function isolatedTmux(socket, args) {
+    const result = spawnSync('tmux', ['-S', socket, ...args], { encoding: 'utf8' });
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+function tmuxBinding(socket, table, key) {
+    const result = isolatedTmux(socket, ['list-keys', '-T', table]);
+    if (result.status !== 0)
+        return null;
+    return result.stdout.split('\n').find((line) => {
+        const match = line.match(/^bind-key\s+(?:-r\s+)?-T\s+\S+\s+(\S+)\s+/);
+        return match?.[1] === key;
+    }) ?? null;
+}
+test('tmux repairs corrupt bracketed-paste caps without replacing user overrides', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-bracketed-paste-${process.pid}-${Date.now()}`;
+    // `-f /dev/null`: boot a config-less isolated server so these binding tests are
+    // hermetic. Without it the server sources the developer's ~/.tmux.conf, whose
+    // own root-table bindings (e.g. M-j) pre-occupy keys these tests rebind onto —
+    // the installer then correctly refuses to clobber the foreign binding and the
+    // assertion fails on the dev's machine but not on a config-less CI runner.
+    const boot = spawnSync('tmux', ['-L', name, '-f', '/dev/null', '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'];
+    process.env['TMUX'] = `${socket},1,0`;
+    try {
+        assert.equal(isolatedTmux(socket, ['set-option', '-s', 'terminal-overrides', 'xterm*:Tc']).status, 0);
+        assert.equal(isolatedTmux(socket, ['set-option', '-sga', 'terminal-overrides', '*:Enbp=E[?2004h:Dsbp=E[?2004l']).status, 0);
+        ensureSession('test', process.cwd());
+        const repaired = isolatedTmux(socket, ['show-options', '-s', 'terminal-overrides']);
+        assert.equal(repaired.status, 0, repaired.stderr);
+        assert.match(repaired.stdout, /xterm\*:Tc/, 'unrelated user override must remain');
+        assert.match(repaired.stdout, /Enbp=\\+E\[\?2004h/, 'a valid Enbp override must be appended');
+        ensureSession('test', process.cwd());
+        assert.equal(isolatedTmux(socket, ['show-options', '-s', 'terminal-overrides']).stdout, repaired.stdout, 'valid Enbp must make the repair idempotent');
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});
+test('tmux installer remaps owned pairs and preserves occupied user bindings', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-keybindings-${process.pid}-${Date.now()}`;
+    const boot = spawnSync('tmux', ['-L', name, '-f', '/dev/null', 'new-session', '-d', '-s', 'test'], { encoding: 'utf8' });
+    assert.equal(boot.status, 0, boot.stderr);
+    const socketResult = spawnSync('tmux', ['-L', name, 'display-message', '-p', '#{socket_path}'], { encoding: 'utf8' });
+    const socket = socketResult.stdout.trim();
+    assert.notEqual(socket, '');
+    const priorTmux = process.env['TMUX'];
+    process.env['TMUX'] = `${socket},1,0`;
+    try {
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-]', 'run-shell', `crtr surface node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`]);
+        const first = installTmuxBindings(resolveKeybindings());
+        assert.equal(first.ok, true, JSON.stringify(first.diagnostics));
+        assert.ok(first.installed.some((pair) => pair.table === 'root' && pair.key === 'M-]'));
+        const defaultMenu = tmuxBinding(socket, 'root', 'M-c') ?? '';
+        assert.match(defaultMenu, /display-menu/);
+        assert.match(defaultMenu, /copy node id/);
+        assert.match(defaultMenu, /surface node id --pane \{pane\}/);
+        assert.match(defaultMenu, /fork into idle root/);
+        assert.match(defaultMenu, /node fork --pane #\{pane_id\}/);
+        const headings = ['-#[bold]Explore', '-#[bold]Current node', '-#[bold]Lifecycle', '-#[bold]System'];
+        for (const heading of headings)
+            assert.ok(defaultMenu.includes(heading), `missing heading ${heading}`);
+        assert.deepEqual(headings.map((heading) => defaultMenu.indexOf(heading)), [...headings.map((heading) => defaultMenu.indexOf(heading))].sort((a, b) => a - b), 'prefix-menu groups should stay in their intended order');
+        // Each later group is preceded by a horizontal-rule separator (a lone empty
+        // item name between the previous group and the header).
+        assert.ok((defaultMenu.match(/'' "-#\[bold\]/g) ?? []).length >= 3, defaultMenu);
+        assert.ok(defaultMenu.indexOf('promote to orchestrator') > defaultMenu.indexOf('-#[bold]Lifecycle'));
+        assert.match(defaultMenu, /"create ›" i .*display-menu.*idea.*bug/);
+        assert.match(defaultMenu, /"Alt\+C to close" M-c refresh-client/);
+        const explore = defaultMenu.indexOf('-#[bold]Explore');
+        const currentNode = defaultMenu.indexOf('-#[bold]Current node');
+        const lifecycle = defaultMenu.indexOf('-#[bold]Lifecycle');
+        const system = defaultMenu.indexOf('-#[bold]System');
+        for (const item of ['resume node', 'graph view', 'focus manager', 'show ›']) {
+            assert.ok(defaultMenu.indexOf(item) > explore && defaultMenu.indexOf(item) < currentNode, `${item} belongs in Explore`);
+        }
+        assert.match(defaultMenu, /"show ›" s .*display-menu.*metadata.*context \+ reports/);
+        for (const item of ['background bash command', 'copy node id']) {
+            assert.ok(defaultMenu.indexOf(item) > currentNode && defaultMenu.indexOf(item) < lifecycle, `${item} belongs to the current node`);
+        }
+        assert.ok(defaultMenu.indexOf('fork into idle root') > lifecycle && defaultMenu.indexOf('fork into idle root') < system, 'fork belongs in Lifecycle');
+        assert.ok(defaultMenu.indexOf('settings') > system, 'settings belongs in System');
+        assert.ok(defaultMenu.indexOf('create ›') > system, 'create belongs in System');
+        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'],
+            'crtr.tmux.node.next': [],
+            'crtr.tmux.view.next': ['alt+z > n'],
+            'crtr.tmux.view.previous': ['alt+z > p'],
+        }));
+        assert.equal(remapped.ok, true, JSON.stringify(remapped.diagnostics));
+        assert.equal(tmuxBinding(socket, 'root', 'M-c'), null);
+        assert.equal(tmuxBinding(socket, 'root', 'M-]'), null);
+        const menu = tmuxBinding(socket, 'root', 'M-Z') ?? '';
+        assert.match(menu, /graph view/);
+        assert.match(menu, /Z/);
+        assert.match(menu, /"Alt\+Shift\+Z to close" M-Z refresh-client/);
+        const prefix = tmuxBinding(socket, 'root', 'M-z') ?? '';
+        assert.match(prefix, /switch-client/);
+        const again = installTmuxBindings(resolveKeybindings({
+            'crtr.tmux.menu.open': ['alt+shift+y'],
+            'crtr.tmux.node.next': [],
+            'crtr.tmux.view.next': ['alt+z > n'],
+            'crtr.tmux.view.previous': ['alt+z > p'],
+        }));
+        assert.equal(again.ok, true, JSON.stringify(again.diagnostics));
+        isolatedTmux(socket, ['bind-key', '-T', 'root', 'M-Z', 'display-message', 'user-owned']);
+        const occupied = installTmuxBindings(resolveKeybindings({ 'crtr.tmux.menu.open': ['alt+shift+z'] }));
+        assert.equal(occupied.ok, true);
+        assert.ok(occupied.diagnostics.some((diagnostic) => diagnostic.code === 'occupied' && diagnostic.bindingId === 'crtr.tmux.menu.open'));
+        assert.match(tmuxBinding(socket, 'root', 'M-Z') ?? '', /user-owned/);
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        isolatedTmux(socket, ['kill-server']);
+    }
+});
+test('tmux installer replaces an untracked stale crouter menu even when a partial manifest exists', (t) => {
+    if (spawnSync('tmux', ['-V']).status !== 0) {
+        t.skip('tmux is unavailable');
+        return;
+    }
+    const name = `crtr-stale-menu-${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'];
+    process.env['TMUX'] = `${socket},1,0`;
+    try {
+        // Upgrade fixture: a later installer started a manifest with only M-i while
+        // the older crouter M-c menu remained live but untracked. Its crouter-only
+        // markers prove ownership; it deliberately lacks the new background item.
+        isolatedTmux(socket, ['set-option', '-s', '@crtr_keybindings_manifest', JSON.stringify([{ table: 'root', key: 'M-i' }])]);
+        isolatedTmux(socket, [
+            'bind-key', '-T', 'root', 'M-c', 'display-menu',
+            'promote to orchestrator', 'o', "run-shell 'crtr canvas chord'",
+            'new issue / todo', 'i', 'display-message stale',
+        ]);
+        const stale = tmuxBinding(socket, 'root', 'M-c') ?? '';
+        assert.match(stale, /crtr canvas chord/);
+        assert.doesNotMatch(stale, /background bash command/);
+        const result = installTmuxBindings(resolveKeybindings());
+        assert.equal(result.ok, true, JSON.stringify(result.diagnostics));
+        assert.ok(!result.diagnostics.some((d) => d.bindingId === 'crtr.tmux.menu.open'), JSON.stringify(result.diagnostics));
+        assert.match(tmuxBinding(socket, 'root', 'M-c') ?? '', /background bash command/);
+    }
+    finally {
+        if (priorTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = priorTmux;
+        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, '-f', '/dev/null', '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, '-f', '/dev/null', '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, '-f', '/dev/null', '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/__tests__/wake-bearings.test.d.ts

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