@north-light/crouter 0.3.154

package/dist/core/io.d.ts

@@ -0,0 +1,73 @@
+import { CrtrError } from './errors.js';
+import { type ExitCodeValue } from '../types.js';
+import { ApiError } from '../api/index.js';
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export declare function setJsonOutput(v: boolean): void;
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export declare function isJsonOutput(): boolean;
+/** Structured error payload. `error` is a stable code the agent branches on;
+ *  `next` is the recovery road sign. */
+export interface ErrorPayload {
+    error: string;
+    message: string;
+    received?: unknown;
+    field?: string;
+    /** Transport status of a failed backend call (configured CLIs). It is kept out
+     *  of `received` on purpose: `received` names the caller's offending VALUE, and
+     *  reporting an HTTP status there is a false claim about what was sent. */
+    http_status?: number;
+    next: string;
+}
+/** A command-level failure: surfaces as the JSON response on stdout. */
+export declare class InputError extends CrtrError {
+    payload: ErrorPayload;
+    constructor(payload: ErrorPayload, exitCode?: ExitCodeValue);
+}
+/** Read raw stdin to EOF. Returns empty string when stdin is a TTY (no pipe).
+ *  Called by the argv parser for leaves declaring a `stdin` parameter. */
+export declare function readStdinRaw(): Promise<string>;
+/** Best-effort, non-hanging peek at whatever stdin bytes are already
+ *  buffered — used ONLY to detect a positional/stdin conflict, never to
+ *  consume the leaf's actual required stdin body. Genuine piped/redirected
+ *  content (a heredoc, `< file`, `cat x |`) is fully written into the pipe
+ *  before this process starts reading, so it resolves within one tick; a
+ *  non-TTY stdin that's simply inherited and held open with nothing written
+ *  to it (e.g. a caller subprocess that never closes its own stdin) would
+ *  otherwise hang `readStdinRaw()` forever — this bounds that wait instead
+ *  of blocking the whole invocation on an ambiguous pipe. Returns '' on a
+ *  TTY (nothing can be piped) or once the bound elapses with no bytes. */
+export declare function peekStdinRaw(timeoutMs?: number): Promise<string>;
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
+export declare function emit(obj: Record<string, unknown>): void;
+/** One JSONL record. Call per event in a stream; partial reads stay parseable. */
+export declare function emitLine(obj: Record<string, unknown>): void;
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export declare function writeStdout(s: string): Promise<boolean>;
+export declare function diag(message: string): void;
+/** Translate an `ApiError` into the clean CLI error a leaf should surface.
+ *  Three tiers, in priority order:
+ *   1. Daemon-down (503 / `daemon_unavailable`) → a `network`-class `CrtrError`
+ *      so the exit code and next-hint match the operational failure it is.
+ *   2. A server-thrown `InputError` round-trips its FULL structured payload
+ *      through `toErrorBody` into `ApiError.details` (`{error,message,next,…}`) —
+ *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
+ *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
+ *      it before the re-plumb, preserving its SPECIFIC code + next.
+ *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *      and a caller-supplied-or-default `next`. */
+export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrError;
+/** Terminal error handler. Command-level failures (bad input, not-found,
+ *  ambiguous) surface as the JSON response on stdout so the caller parses one
+ *  contract. A daemon `ApiError` is translated to that same clean contract
+ *  (`apiErrorToCliError`) as a safety net for any leaf that lets it propagate.
+ *  Runtime/internal failures go to stderr as `{error:"internal"}` — raw traces
+ *  never reach the agent. Exits non-zero either way. */
+export declare function handle(e: unknown): void;

package/dist/core/io.js

@@ -0,0 +1,254 @@
+// The agent-facing I/O contract. Flags and positional args on input; stdout is
+// agent-ready markdown/XML the caller acts on directly (the result rendered FOR
+// the model, not data it parses); structured errors; stderr is diagnostics only
+// and never carries the result. The raw JSON object is available behind the
+// `--json` global for tooling. See the cli-design reference.
+import { CrtrError } from './errors.js';
+import { ExitCode } from '../types.js';
+import { renderError } from './render.js';
+import { ApiError } from '../api/index.js';
+// ---------------------------------------------------------------------------
+// output mode — prose (default) vs raw JSON (--json global, for tooling)
+// ---------------------------------------------------------------------------
+let jsonOutput = false;
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export function setJsonOutput(v) {
+    jsonOutput = v;
+}
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export function isJsonOutput() {
+    return jsonOutput;
+}
+/** A command-level failure: surfaces as the JSON response on stdout. */
+export class InputError extends CrtrError {
+    payload;
+    constructor(payload, exitCode = ExitCode.USAGE) {
+        super(payload.error, payload.message, exitCode, { ...payload });
+        this.name = 'InputError';
+        this.payload = payload;
+    }
+}
+// ---------------------------------------------------------------------------
+// stdin
+// ---------------------------------------------------------------------------
+/** Read raw stdin to EOF. Returns empty string when stdin is a TTY (no pipe).
+ *  Called by the argv parser for leaves declaring a `stdin` parameter. */
+export async function readStdinRaw() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** Best-effort, non-hanging peek at whatever stdin bytes are already
+ *  buffered — used ONLY to detect a positional/stdin conflict, never to
+ *  consume the leaf's actual required stdin body. Genuine piped/redirected
+ *  content (a heredoc, `< file`, `cat x |`) is fully written into the pipe
+ *  before this process starts reading, so it resolves within one tick; a
+ *  non-TTY stdin that's simply inherited and held open with nothing written
+ *  to it (e.g. a caller subprocess that never closes its own stdin) would
+ *  otherwise hang `readStdinRaw()` forever — this bounds that wait instead
+ *  of blocking the whole invocation on an ambiguous pipe. Returns '' on a
+ *  TTY (nothing can be piped) or once the bound elapses with no bytes. */
+export async function peekStdinRaw(timeoutMs = 200) {
+    if (process.stdin.isTTY)
+        return '';
+    return await new Promise((resolve) => {
+        const chunks = [];
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeListener('data', onData);
+            process.stdin.removeListener('end', onEnd);
+            process.stdin.removeListener('error', onError);
+            process.stdin.pause();
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        };
+        const onData = (chunk) => chunks.push(chunk);
+        const onEnd = () => finish();
+        const onError = () => finish();
+        const timer = setTimeout(finish, timeoutMs);
+        process.stdin.on('data', onData);
+        process.stdin.on('end', onEnd);
+        process.stdin.on('error', onError);
+        process.stdin.resume();
+    });
+}
+// ---------------------------------------------------------------------------
+// stdout — the result, nothing else
+// ---------------------------------------------------------------------------
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
+export function emit(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+/** One JSONL record. Call per event in a stream; partial reads stay parseable. */
+export function emitLine(obj) {
+    process.stdout.write(JSON.stringify(obj) + '\n');
+}
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export function writeStdout(s) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const onErr = (e) => {
+            if (e.code === 'EPIPE')
+                finish(false);
+        };
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            process.stdout.off('error', onErr);
+            resolve(ok);
+        };
+        process.stdout.on('error', onErr);
+        try {
+            process.stdout.write(s, (err) => finish(err === null || err === undefined));
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// stderr — diagnostics the agent MAY capture, never the result
+// ---------------------------------------------------------------------------
+export function diag(message) {
+    process.stderr.write(message + '\n');
+}
+// ---------------------------------------------------------------------------
+// errors
+// ---------------------------------------------------------------------------
+function payloadOf(e) {
+    if (e instanceof InputError)
+        return e.payload;
+    const d = (e.details !== undefined ? e.details : {});
+    const next = d.next !== undefined
+        ? d.next
+        : 'Inspect the error and adjust the call. See -h for the schema.';
+    return {
+        error: e.code,
+        message: e.message,
+        received: d.received,
+        field: d.field,
+        ...(typeof d.http_status === 'number' ? { http_status: d.http_status } : {}),
+        next,
+    };
+}
+// ---------------------------------------------------------------------------
+// ApiError → clean CLI error — the ONE shared translation (plan C-5)
+//
+// A daemon `ApiError` is NOT a `CrtrError`, so left unhandled it falls through
+// `handle()` as an "internal crtr bug" — the wrong UX for an operational
+// failure. This is the single place that maps it back to the clean, structured
+// error the pre-API leaves surfaced, so every re-plumbed verb shares one
+// contract instead of re-implementing the mapping per command. io.ts importing
+// `ApiError` from `src/api` is canvas-clean (src/api is Node-built-ins only).
+// ---------------------------------------------------------------------------
+/** Map a daemon HTTP status to the stable CLI error code the pre-API leaves
+ *  used, so agent-facing error contracts survive the re-plumb. Used only as the
+ *  fallback when the server did NOT round-trip a full structured payload. */
+const STATUS_TO_CLI_CODE = {
+    400: 'invalid_request',
+    404: 'not_found',
+    409: 'conflict',
+    422: 'unprocessable',
+    503: 'daemon_unavailable',
+};
+/** Translate an `ApiError` into the clean CLI error a leaf should surface.
+ *  Three tiers, in priority order:
+ *   1. Daemon-down (503 / `daemon_unavailable`) → a `network`-class `CrtrError`
+ *      so the exit code and next-hint match the operational failure it is.
+ *   2. A server-thrown `InputError` round-trips its FULL structured payload
+ *      through `toErrorBody` into `ApiError.details` (`{error,message,next,…}`) —
+ *      reconstruct it verbatim so a gate/guard error (revive reopen-gate, push
+ *      worktree/finalization guard, …) surfaces byte-for-byte as the leaf raised
+ *      it before the re-plumb, preserving its SPECIFIC code + next.
+ *   3. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *      and a caller-supplied-or-default `next`. */
+export function apiErrorToCliError(err, next) {
+    // A handover is NOT a down daemon: the successor is already up (the client
+    // waited for its /healthz), so telling anyone to start one is wrong — the
+    // only thing left is to re-issue the call.
+    if (err.code === 'daemon_restarting') {
+        return new CrtrError('daemon_restarting', err.message, ExitCode.NETWORK, {
+            next: 'crtrd is now on the new generation — retry the command.',
+        });
+    }
+    if (err.status === 503 || err.code === 'daemon_unavailable') {
+        return new CrtrError('daemon_unavailable', err.message, ExitCode.NETWORK, {
+            next: 'Start it with `crtr sys daemon start`, then retry.',
+        });
+    }
+    const d = err.details;
+    const payload = d && typeof d.error === 'string' && typeof d.message === 'string' && typeof d.next === 'string'
+        ? d
+        : {
+            error: STATUS_TO_CLI_CODE[err.status] ?? err.code,
+            message: err.message,
+            next: next ??
+                (err.status >= 500
+                    ? 'This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).'
+                    : err.status === 404
+                        ? 'List nodes with `crtr node inspect list`.'
+                        : 'Inspect the error and adjust the call. See -h for the schema.'),
+        };
+    // Preserve the exit-code class the server leaf carried instead of collapsing
+    // every non-503 to USAGE(2): a not-found (404 / `not_found`) surfaces exit 3
+    // and an ambiguous match exit 4, matching the codes the local-only leaves
+    // (memory/pkg/sys) still emit so the taxonomy stays uniform across the CLI.
+    return new InputError(payload, exitForCliCode(payload.error, err.status));
+}
+/** The `ExitCode` class a reconstructed API error should carry, keyed off the
+ *  round-tripped CLI code (and the 404 status as the not-found signal — the
+ *  server maps NOT_FOUND's exit class to status 404, but folds AMBIGUOUS and
+ *  USAGE both onto 400, so `ambiguous` is recoverable only from the code). */
+function exitForCliCode(code, status) {
+    if (code === 'not_found' || status === 404)
+        return ExitCode.NOT_FOUND;
+    if (code === 'ambiguous')
+        return ExitCode.AMBIGUOUS;
+    return ExitCode.USAGE;
+}
+/** Terminal error handler. Command-level failures (bad input, not-found,
+ *  ambiguous) surface as the JSON response on stdout so the caller parses one
+ *  contract. A daemon `ApiError` is translated to that same clean contract
+ *  (`apiErrorToCliError`) as a safety net for any leaf that lets it propagate.
+ *  Runtime/internal failures go to stderr as `{error:"internal"}` — raw traces
+ *  never reach the agent. Exits non-zero either way. */
+export function handle(e) {
+    if (e instanceof ApiError) {
+        handle(apiErrorToCliError(e));
+        return;
+    }
+    if (e instanceof CrtrError) {
+        const payload = payloadOf(e);
+        const out = jsonOutput
+            ? JSON.stringify(payload, null, 2)
+            : renderError(payload);
+        process.stdout.write(out + '\n');
+        process.exitCode = e.exitCode;
+        return;
+    }
+    const err = e;
+    const message = err !== null && err !== undefined && typeof err.message === 'string'
+        ? err.message
+        : String(e);
+    process.stderr.write(JSON.stringify({
+        error: 'internal',
+        message,
+        next: 'This is a crtr bug, not a bad call. Retry; if it persists, report it.',
+    }, null, 2) + '\n');
+    process.exitCode = ExitCode.GENERAL;
+}

package/dist/core/keybindings/__tests__/bespoke-consumers.test.d.ts

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

package/dist/core/keybindings/__tests__/bespoke-consumers.test.js

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveViewPickAction } from '../../../commands/view-pick.js';
+import { resolveBrowseNavAction, resolveBrowseSearchAction } from '../../canvas/browse/app.js';
+import { resolveProfileMenuAction, resolveProfileSearchAction } from '../../profiles/select.js';
+import { resolveKeybindings } from '../index.js';
+test('bespoke consumers resolve defaults and replacements without retaining old gestures', () => {
+    const defaults = resolveKeybindings();
+    assert.equal(resolveViewPickAction(defaults, { input: 'j' }), 'crtr.view-picker.down');
+    assert.equal(resolveBrowseNavAction(defaults, { input: 'G' }), 'crtr.browse.last');
+    // Unit 1's terminal-space canonicalization lets a literal space key resolve the
+    // catalog `space` gesture — the browse fold toggle now flows through the catalog.
+    assert.equal(resolveBrowseNavAction(defaults, { input: ' ' }), 'crtr.browse.toggle-fold');
+    assert.equal(resolveBrowseSearchAction(defaults, { return: true }), 'crtr.browse.search.commit');
+    assert.equal(resolveProfileMenuAction(defaults, { input: '3' }), 'crtr.profile.menu.slot.3');
+    assert.equal(resolveProfileSearchAction(defaults, { input: 'p', ctrl: true }), 'crtr.profile.search.up');
+    const remapped = resolveKeybindings({
+        'crtr.view-picker.down': ['z'],
+        'crtr.browse.last': ['z'],
+        'crtr.browse.search.commit': ['z'],
+        'crtr.profile.menu.slot.3': ['z'],
+        'crtr.profile.search.up': ['z'],
+    });
+    assert.equal(remapped.diagnostics.length, 0);
+    assert.equal(resolveViewPickAction(remapped, { input: 'j' }), null);
+    assert.equal(resolveViewPickAction(remapped, { input: 'z' }), 'crtr.view-picker.down');
+    assert.equal(resolveBrowseNavAction(remapped, { input: 'G' }), null);
+    assert.equal(resolveBrowseNavAction(remapped, { input: 'z' }), 'crtr.browse.last');
+    assert.equal(resolveBrowseSearchAction(remapped, { return: true }), null);
+    assert.equal(resolveBrowseSearchAction(remapped, { input: 'z' }), 'crtr.browse.search.commit');
+    assert.equal(resolveProfileMenuAction(remapped, { input: '3' }), null);
+    assert.equal(resolveProfileMenuAction(remapped, { input: 'z' }), 'crtr.profile.menu.slot.3');
+    assert.equal(resolveProfileSearchAction(remapped, { input: 'p', ctrl: true }), null);
+    assert.equal(resolveProfileSearchAction(remapped, { input: 'z' }), 'crtr.profile.search.up');
+});
+test('profile search leaves printable filter payloads outside catalog actions', () => {
+    const bindings = resolveKeybindings();
+    assert.equal(resolveProfileSearchAction(bindings, { input: 'w' }), null);
+    assert.equal(resolveProfileSearchAction(bindings, { input: '文' }), null);
+});

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, `surface 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.d.ts

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

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

@@ -0,0 +1,233 @@
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { BINDING_CATALOG, KeybindingConcurrentEditError, KeybindingValidationError, SAFETY_REQUIREMENTS, canonicalTerminalStroke, formatStroke, matchesTerminalInput, normalizeGesture, normalizeSparseOverrides, persistUserKeybindings, resolveKeybindings, resolveUserKeybindings, } from '../index.js';
+import { readConfig } from '../../config.js';
+const typeCheckedBindingId = 'crtr.graph.down';
+// @ts-expect-error The catalog type rejects IDs that are not built in.
+const rejectedBindingId = 'crtr.graph.not-real';
+void typeCheckedBindingId;
+void rejectedBindingId;
+function ids(prefix, actions) {
+    return actions.map((action) => `${prefix}.${action}`);
+}
+const REQUIRED_IDS = [
+    ...ids('crtr.tmux.menu', ['open', 'promote', 'resume', 'fork', 'demote', 'detach', 'close-subtree', 'background-bash', 'file-review', 'pin', 'show', 'metadata', 'context', 'providers', 'graph', 'focus-manager', 'copy-id', 'reload-viewer', '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', 'command.inspect', 'file-review']),
+    'crtr.mode.cycle',
+    ...ids('crtr.graph', ['down', 'up', 'first', 'last', 'collapse-or-manager', 'expand-or-child', 'focus', 'revive', 'focus-manager', 'close-subtree', 'dismiss']),
+    ...ids('crtr.graph.confirm', ['accept', 'cancel']),
+    ...ids('crtr.view.host', ['force-quit', 'editor.backspace']),
+    ...ids('crtr.view.canvas', ['down', 'up', 'refresh', 'quit']),
+    ...ids('crtr.view.chat', ['submit', 'contextual-cancel', 'reconnect', 'quit']),
+    ...ids('crtr.view.git-pr', ['down', 'up', 'refresh', 'quit']),
+    ...ids('crtr.view.inbox', ['down', 'up', 'open', 'reply', 'react', 'filter', 'refresh', 'connect-linkedin', 'connect-gmail', 'quit', 'submit-reply', 'cancel', 'reaction-previous', 'reaction-next', 'submit-reaction']),
+    ...ids('crtr.view.linkedin', ['down', 'up', 'open', 'reply', 'react', 'refresh', 'quit', 'submit-reply', 'cancel', 'reaction-previous', 'reaction-next', 'submit-reaction']),
+    ...ids('crtr.view.prompt-review', ['down', 'up', 'compare-previous', 'compare-next', 'toggle-mode', 'expand', 'export', 'refresh', 'quit']),
+    ...ids('crtr.view.workspace-sidebar', ['down', 'up', 'open', 'refresh', 'quit']),
+    ...ids('crtr.view.inspector', ['down', 'up', 'section-next', 'section-prev', 'page-down', 'page-up', 'toggle-detail', 'cancel-item', 'confirm', 'dismiss', 'retarget', 'refresh', 'quit']),
+    ...ids('crtr.view-picker', ['down', 'up', 'run', 'quit']),
+    ...ids('crtr.browse', ['quit', 'down', 'up', 'first', 'last', 'expand-or-child', 'collapse-or-parent', 'toggle-fold', 'tab-next', 'tab-previous', 'tab.1', 'tab.2', 'tab.3', 'tab.4', 'tab.5', 'close-subtree', 'confirm-close', 'sort', 'scope', 'profile', 'residents', 'preview', 'search', 'revive-now', 'focus', 'focus-background']),
+    ...ids('crtr.browse.search', ['cancel', 'commit', 'delete', 'quit']),
+    ...ids('crtr.profile.menu', ['up', 'down', 'select', 'accept-default', 'abort', 'slot.1', 'slot.2', 'slot.3', 'slot.4', 'slot.5', 'slot.6', 'slot.7', 'slot.8', 'slot.9', 'create', 'search-existing', 'use-root', 'set-default', 'add-directory', 'unpin']),
+    ...ids('crtr.profile.search', ['up', 'down', 'pick', 'back', 'delete', 'abort']),
+    ...ids('crtr.setup', ['cancel', 'tab-next', 'tab-previous', 'open', 'list-down', 'list-up', 'toggle', 'details', 'advance']),
+    ...ids('crtr.setup.confirm', ['accept', 'back']),
+    ...ids('crtr.setup.keybindings', ['edit', 'commit-edit', 'cancel-edit', 'unbind', 'reset-row', 'reset-all', 'save', 'discard', 'page-up', 'page-down', 'filter', 'filter-delete', 'filter-clear']),
+    ...ids('crtr.setup', ['cell-previous', 'cell-next']),
+    ...ids('crtr.setup.models', ['open', 'scope-next', 'commit', 'cancel']),
+];
+let home;
+let realHome;
+let realCwd;
+before(() => {
+    realHome = process.env['HOME'];
+    realCwd = process.cwd();
+});
+beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-keybindings-'));
+    process.env['HOME'] = home;
+    process.chdir(realCwd);
+});
+after(() => {
+    process.chdir(realCwd);
+    if (realHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = realHome;
+});
+test.afterEach(() => rmSync(home, { recursive: true, force: true }));
+test('catalog is closed, complete, ordered, and has valid collision-free defaults', () => {
+    const actualIds = BINDING_CATALOG.map((definition) => definition.id);
+    assert.deepEqual(actualIds, REQUIRED_IDS);
+    assert.equal(actualIds.length, REQUIRED_IDS.length);
+    assert.equal(new Set(actualIds).size, actualIds.length);
+    for (const definition of BINDING_CATALOG) {
+        assert.match(definition.id, /^crtr\.[a-z0-9.-]+$/);
+        assert.ok(definition.name.length > 0);
+        assert.ok(definition.description.length > 0);
+        assert.ok(definition.contexts.length > 0);
+        for (const gesture of definition.defaults)
+            assert.equal(normalizeGesture(gesture, definition), gesture);
+    }
+    const resolved = resolveKeybindings();
+    assert.equal(resolved.bindings.size, BINDING_CATALOG.length);
+    assert.deepEqual(resolved.diagnostics, []);
+    assert.ok(SAFETY_REQUIREMENTS.length > 0);
+});
+test('normalizes aliases, modifier order, uppercase printables, sequences, and duplicate gestures', () => {
+    assert.equal(normalizeGesture('M-C-X'), 'ctrl+alt+shift+x');
+    assert.equal(normalizeGesture('alt+ctrl+x'), 'ctrl+alt+x');
+    assert.equal(normalizeGesture('return'), 'enter');
+    assert.equal(normalizeGesture('esc'), 'escape');
+    assert.equal(normalizeGesture('meta+j'), 'alt+j');
+    assert.equal(normalizeGesture('+'), '+');
+    assert.equal(normalizeGesture('ctrl++'), 'ctrl++');
+    assert.equal(normalizeGesture('alt+>'), 'alt+>');
+    assert.equal(formatStroke('ctrl++'), 'Ctrl++');
+    assert.equal(canonicalTerminalStroke({ input: '+', ctrl: true }), 'ctrl++');
+    const resolved = resolveKeybindings({
+        'crtr.attach.graph.toggle': ['M-X', 'alt+x'],
+        'crtr.tmux.view.next': ['M-V > ]', 'alt+v > ]'],
+        'crtr.tmux.menu.promote': ['space'],
+    });
+    assert.deepEqual(resolved.gestures('crtr.attach.graph.toggle'), ['alt+shift+x', 'alt+x']);
+    assert.deepEqual(resolved.gestures('crtr.tmux.view.next'), ['alt+shift+v > ]', 'alt+v > ]']);
+    assert.deepEqual(resolved.gestures('crtr.tmux.menu.promote'), ['space']);
+});
+test('terminal literal space matches named space bindings', () => {
+    const raw = { input: ' ' };
+    assert.equal(canonicalTerminalStroke(raw), 'space');
+    assert.equal(matchesTerminalInput(resolveKeybindings(), 'crtr.browse.toggle-fold', raw), true);
+});
+test('invalid values and unknown IDs diagnose precisely while valid overrides still apply', () => {
+    const resolved = resolveKeybindings({
+        'crtr.unknown': ['x'],
+        'crtr.graph.down': 'down',
+        'crtr.attach.graph.toggle': ['alt+x'],
+        'crtr.tmux.view.next': ['alt+v'],
+    });
+    assert.equal(resolved.gestures('crtr.graph.down')[0], 'j');
+    assert.deepEqual(resolved.gestures('crtr.attach.graph.toggle'), ['alt+x']);
+    assert.equal(resolved.gestures('crtr.tmux.view.next')[0], 'alt+v > ]');
+    assert.deepEqual(new Set(resolved.diagnostics.map((item) => item.code)), new Set(['unknown-binding', 'invalid-override']));
+});
+test('colliding overrides fall back without affecting unrelated contexts', () => {
+    const resolved = resolveKeybindings({
+        'crtr.graph.down': ['k'],
+        'crtr.view.canvas.quit': ['x'],
+        'crtr.attach.graph.toggle': ['alt+c'],
+        'crtr.attach.detach': ['j'],
+        'crtr.setup.list-down': ['space'],
+    });
+    assert.equal(resolved.gestures('crtr.graph.down')[0], 'j');
+    assert.deepEqual(resolved.gestures('crtr.view.canvas.quit'), ['x']);
+    assert.deepEqual(resolved.gestures('crtr.attach.graph.toggle'), ['alt+g']);
+    assert.deepEqual(resolved.gestures('crtr.attach.detach'), ['ctrl+d']);
+    assert.deepEqual(resolved.gestures('crtr.setup.list-down'), ['j', 'down']);
+    assert.equal(resolved.diagnostics.filter((item) => item.code === 'collision').length, 4);
+});
+test('tmux menu selectors collide only inside their own menu', () => {
+    // The tmux.root opener may take a menu selector's key (detach = shift+d) — a
+    // globally-active root binding never collides with a menu-scoped selector.
+    const opener = resolveKeybindings({ 'crtr.tmux.menu.open': ['shift+d'] });
+    assert.deepEqual(opener.gestures('crtr.tmux.menu.open'), ['shift+d']);
+    assert.deepEqual(opener.diagnostics, []);
+    // Symmetrically, a menu selector may reuse an in-pane key (promote onto the
+    // browse-down `j`) — selectors are checked only within their own tmux.menu, so
+    // they never collide with in-pane terminal bindings (e.g. browse's own `o`).
+    const selector = resolveKeybindings({ 'crtr.tmux.menu.promote': ['j'] });
+    assert.deepEqual(selector.gestures('crtr.tmux.menu.promote'), ['j']);
+    assert.deepEqual(selector.diagnostics, []);
+});
+test('reachability rejects deliberate unbinding that would trap a context', () => {
+    const graph = resolveKeybindings({
+        'crtr.graph.dismiss': [],
+        'crtr.graph.down': ['escape'],
+    });
+    assert.deepEqual(graph.gestures('crtr.graph.dismiss'), ['escape']);
+    assert.deepEqual(graph.gestures('crtr.graph.down'), ['j']);
+    assert.ok(graph.diagnostics.some((item) => item.code === 'unreachable'));
+    assert.ok(graph.diagnostics.some((item) => item.code === 'collision'));
+    const setup = resolveKeybindings({
+        'crtr.setup.keybindings.discard': [],
+        'crtr.setup.keybindings.save': [],
+    });
+    assert.equal(setup.diagnostics.filter((item) => item.code === 'unreachable').length, 1);
+});
+test('sparsification omits defaults, preserves explicit unbinds, and reset removes the override', () => {
+    assert.deepEqual(normalizeSparseOverrides({ 'crtr.attach.graph.toggle': ['alt+g'] }), {});
+    assert.deepEqual(normalizeSparseOverrides({ 'crtr.graph.close-subtree': [] }), {
+        'crtr.graph.close-subtree': [],
+    });
+    assert.deepEqual(normalizeSparseOverrides({}), {});
+    assert.throws(() => normalizeSparseOverrides({ 'crtr.graph.down': ['k'] }), KeybindingValidationError);
+});
+test('user resolution ignores project keybindings', () => {
+    mkdirSync(join(home, '.crouter'), { recursive: true });
+    writeFileSync(join(home, '.crouter', 'config.json'), JSON.stringify({ keybindings: { 'crtr.graph.down': ['down'] } }));
+    const project = mkdtempSync(join(tmpdir(), 'crtr-keybindings-project-'));
+    mkdirSync(join(project, '.crouter'), { recursive: true });
+    writeFileSync(join(project, '.crouter', 'config.json'), JSON.stringify({ keybindings: { 'crtr.graph.down': ['up'] } }));
+    try {
+        process.chdir(project);
+        assert.deepEqual(resolveUserKeybindings().gestures('crtr.graph.down'), ['down']);
+    }
+    finally {
+        process.chdir(realCwd);
+        rmSync(project, { recursive: true, force: true });
+    }
+});
+test('config hard cut exposes only sparse keybindings and ignores unsupported raw fields', () => {
+    mkdirSync(join(home, '.crouter'), { recursive: true });
+    writeFileSync(join(home, '.crouter', 'config.json'), JSON.stringify({
+        canvasNav: { prefixKey: 'alt+x' },
+        keybindings: { 'crtr.graph.down': ['down'], bad: 3 },
+    }));
+    const config = readConfig('user');
+    assert.deepEqual(config.keybindings, { 'crtr.graph.down': ['down'] });
+    assert.equal(Object.hasOwn(config, 'canvasNav'), false);
+});
+test('atomic persistence preserves latest unrelated fields and writes only sparse normalized overrides', () => {
+    mkdirSync(join(home, '.crouter'), { recursive: true });
+    const path = join(home, '.crouter', 'config.json');
+    writeFileSync(path, JSON.stringify({
+        customFutureField: { retained: true },
+        max_panes_per_window: 4,
+        canvasNav: { prefixKey: 'alt+z' },
+    }));
+    persistUserKeybindings({
+        'crtr.attach.graph.toggle': ['M-X'],
+        'crtr.graph.close-subtree': [],
+        'crtr.graph.down': ['j'],
+    });
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    assert.deepEqual(raw.customFutureField, { retained: true });
+    assert.equal(raw.max_panes_per_window, 4);
+    assert.deepEqual(raw.keybindings, {
+        'crtr.attach.graph.toggle': ['alt+shift+x'],
+        'crtr.graph.close-subtree': [],
+    });
+    assert.equal(raw.canvasNav, undefined);
+});
+test('reset-all removes the top-level member and concurrent keybinding edits are refused', () => {
+    mkdirSync(join(home, '.crouter'), { recursive: true });
+    const path = join(home, '.crouter', 'config.json');
+    const original = { 'crtr.graph.down': ['down'] };
+    writeFileSync(path, JSON.stringify({ keybindings: original, retained: 1 }));
+    persistUserKeybindings({}, { expectedKeybindings: original });
+    let raw = JSON.parse(readFileSync(path, 'utf8'));
+    assert.equal(raw.keybindings, undefined);
+    assert.equal(raw.retained, 1);
+    writeFileSync(path, JSON.stringify({ keybindings: { 'crtr.graph.up': ['up'] }, retained: 2 }));
+    assert.throws(() => persistUserKeybindings({}, { expectedKeybindings: original }), KeybindingConcurrentEditError);
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+    assert.deepEqual(raw.keybindings, { 'crtr.graph.up': ['up'] });
+    assert.equal(raw.retained, 2);
+});