@crouton-kit/crouter 0.3.78 → 0.3.80

package/dist/clients/attach/titled-editor.js

@@ -5,6 +5,7 @@
 //   2. a border color that tracks the agent's thinking level (set by attach-cmd
 //      on each state update), mirroring pi's `getThinkingBorderColor`.
 // Both are pure render-layer chrome; nothing here touches the socket or session.
+import { statSync } from 'node:fs';
 import { CustomEditor } from '@earendil-works/pi-coding-agent';
 import { CURSOR_MARKER, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
 /** The standard thinking levels form a deliberate cool→warm ramp between blue
@@ -152,6 +153,39 @@ export function outlineCursorLine(line) {
     const replacement = `${MUTED_CURSOR_ON}${grapheme}\x1b[0m`;
     return line.slice(0, start) + replacement + line.slice(end + SOLID_CURSOR_RESET.length);
 }
+/** Image file extensions a dragged path is recognized by. */
+const IMAGE_PATH_RE = /\.(png|jpe?g|gif|webp|bmp)$/i;
+/** Recognize a single input chunk as a filesystem path to an image file — how a
+ *  terminal delivers a file DRAGGED into the pane (the escaped path pasted in
+ *  bulk, optionally wrapped in bracketed-paste markers). Returns the resolved
+ *  path, or null when the chunk isn't a lone image path (normal typing, multi-
+ *  line text, a non-image path, or a path that doesn't point at a real file).
+ *  Conservative on purpose: it must never transform ordinary typed input. */
+export function detectDroppedImagePath(data) {
+    // Unwrap bracketed paste (\x1b[200~ … \x1b[201~) when the terminal uses it.
+    const bracketed = data.match(/\x1b\[200~([\s\S]*?)\x1b\[201~/);
+    let payload = (bracketed ? bracketed[1] : data).trim();
+    if (payload.length < 2)
+        return null; // a lone keystroke is never a drop
+    if (/[\u0000-\u0008\u000e-\u001f]/.test(payload))
+        return null; // control chars → not a path
+    // Terminals wrap a dropped path in quotes or backslash-escape its spaces.
+    if ((payload.startsWith("'") && payload.endsWith("'")) ||
+        (payload.startsWith('"') && payload.endsWith('"'))) {
+        payload = payload.slice(1, -1);
+    }
+    const path = payload.replace(/\\(.)/g, '$1');
+    if (/\n/.test(path) || !IMAGE_PATH_RE.test(path))
+        return null;
+    try {
+        if (!statSync(path).isFile())
+            return null;
+    }
+    catch {
+        return null; // not a real file → treat as ordinary pasted text
+    }
+    return path;
+}
 export class TitledEditor extends CustomEditor {
     /** crtr's OWN keybindings manager — the same one CustomEditor matches `app.*`
      *  against. We keep a reference so `handleInput` can resolve the newline chord
@@ -175,11 +209,78 @@ export class TitledEditor extends CustomEditor {
      *  override, so matching the chord here makes the newline behavior independent
      *  of cross-instance keybinding mirroring. Skipped while the autocomplete popup
      *  is open so Enter-to-confirm keeps working. */
+    /** Set by the input controller: called when a bulk input chunk is recognized
+     *  as a filesystem path to an image file (a file DRAGGED into the pane, which
+     *  the terminal delivers as bracketed-paste TEXT, not an image event). Returns
+     *  true when it consumed the drop, so the raw path is never inserted as text. */
+    onPasteImagePath;
+    /** Width of an `[Image #N]` token sitting immediately before the cursor on the
+     *  current line, or 0 when the cursor isn't at the end of such a token — used to
+     *  delete/skip the token atomically. The token's separating space is a normal,
+     *  reachable character, deliberately NOT part of the atom. */
+    imageTokenWidthBeforeCursor() {
+        const { line, col } = this.getCursor();
+        const text = this.getLines()[line];
+        if (text === undefined)
+            return 0;
+        const match = text.slice(0, col).match(/\[Image #\d+\]$/);
+        return match ? match[0].length : 0;
+    }
+    /** Width of an `[Image #N]` token sitting immediately after the cursor on the
+     *  current line, or 0 when the cursor isn't at the start of such a token — used
+     *  to skip the token with the right arrow. */
+    imageTokenWidthAfterCursor() {
+        const { line, col } = this.getCursor();
+        const text = this.getLines()[line];
+        if (text === undefined)
+            return 0;
+        const match = text.slice(col).match(/^\[Image #\d+\]/);
+        return match ? match[0].length : 0;
+    }
     handleInput(data) {
         if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.input.newLine')) {
             this.insertTextAtCursor('\n');
             return;
         }
+        // Backspace over an `[Image #N]` token deletes the WHOLE token (and its
+        // trailing space) in one keypress, not one character at a time — the token is
+        // a single atom to the user. We replay the backspace across the token's full
+        // width so the base editor's cursor/undo bookkeeping stays correct.
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.editor.deleteCharBackward')) {
+            const width = this.imageTokenWidthBeforeCursor();
+            if (width > 1) {
+                for (let i = 0; i < width; i++)
+                    super.handleInput(data);
+                return;
+            }
+        }
+        // Left/right arrow steps OVER an `[Image #N]` token in one keypress — the
+        // token reads as a single character, so the caret never lands inside it. We
+        // replay the arrow across the token's full width so cursor bookkeeping stays
+        // correct.
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.editor.cursorLeft')) {
+            const width = this.imageTokenWidthBeforeCursor();
+            if (width > 1) {
+                for (let i = 0; i < width; i++)
+                    super.handleInput(data);
+                return;
+            }
+        }
+        if (!this.isShowingAutocomplete() && this.km.matches(data, 'tui.editor.cursorRight')) {
+            const width = this.imageTokenWidthAfterCursor();
+            if (width > 1) {
+                for (let i = 0; i < width; i++)
+                    super.handleInput(data);
+                return;
+            }
+        }
+        // A file dragged into the pane arrives as a bulk paste of its (shell-escaped)
+        // path, NOT as an image on the clipboard, so onPasteImage never fires. Detect
+        // an image-file path here and hand it to the controller so it becomes an
+        // `[Image #N]` token like a clipboard paste, instead of the raw temp path.
+        const droppedPath = detectDroppedImagePath(data);
+        if (droppedPath && this.onPasteImagePath?.(droppedPath))
+            return;
         super.handleInput(data);
     }
     /** Session-name chip painted into the LEFT of the top border. Empty → plain. */

package/dist/commands/human/queue.js

@@ -9,7 +9,7 @@ import { appendInbox } from '../../core/feed/inbox.js';
 import { closeSync, existsSync, linkSync, openSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { inbox, scanInbox, parseDeck, deckPath, responsePath, progressPath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
+import { openInbox, scanInbox, parseDeck, deckPath, responsePath, progressPath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
 import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
 // stranded-answer healing
@@ -158,8 +158,8 @@ export const humanInbox = defineLeaf({
         ],
     },
     run: async () => {
-        await inbox([interactionsRoot(process.cwd())]);
-        // humanloop's inbox() writes response.json but never calls pushFinal — so a
+        await openInbox({ roots: [interactionsRoot(process.cwd())] });
+        // humanloop's openInbox() writes response.json but never calls pushFinal — so a
         // deck drained here would strand (no answer-back, leaked bridge node). Heal
         // every resolved-but-live interaction: deliver its answer to the asker + reap.
         const delivered = await healStrandedInteractions(process.cwd());
@@ -766,7 +766,6 @@ export const humanRun = defineLeaf({
                 try {
                     const res = await launchReview(rc.file, {
                         output: rc.output,
-                        noTmux: true,
                     });
                     await pushFinal(rc.job_id, JSON.stringify(res));
                 }

package/dist/commands/pkg/plugin-inspect.js

@@ -3,6 +3,8 @@ import { notFound } from '../../core/errors.js';
 import { paginate } from '../../core/pagination.js';
 import { listInstalledPlugins, findPluginByName, } from '../../core/resolver.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
 export const pluginList = defineLeaf({
     name: 'list',
@@ -89,9 +91,10 @@ export const pluginShow = defineLeaf({
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Whether the plugin is active.' },
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
             { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, executable: string | null (null when path/exec-bit validation failed), mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically — the plugin binary is never executed.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only.'],
+        effects: ['None. Read-only. Command manifests are validated statically; the plugin executable is never run.'],
     },
     run: async (input) => {
         const name = input['name'];
@@ -114,6 +117,23 @@ export const pluginShow = defineLeaf({
         }
         const prefix = `${found.name}/`;
         const docs = listAllMemoryDocs().filter((d) => d.name.startsWith(prefix));
+        let commands;
+        if (typeof found.manifest.commands === 'string' && found.manifest.commands.length > 0) {
+            const reserved = new Set(SUBTREE_NAMES);
+            // Validate against the whole effective set so cross-plugin top-level
+            // name collisions show up in this plugin's issues (a collided command is
+            // NOT mounted). A copy outside the effective set (disabled, or shadowed
+            // by a higher-precedence copy) cannot collide, so the per-plugin
+            // validator is exact for it.
+            const v = validateEffectiveCommandPlugins(reserved).find((x) => x.plugin.root === found.root) ??
+                validatePluginCommands(found, reserved);
+            commands = {
+                manifestPath: v.manifestPath,
+                executable: v.executable ?? null,
+                mounts: v.contributions.map((c) => c.node.name),
+                issues: v.issues,
+            };
+        }
         return {
             name: found.name,
             scope: found.scope,
@@ -124,6 +144,7 @@ export const pluginShow = defineLeaf({
                 name: d.name,
                 path: d.path,
             })),
+            ...(commands !== undefined ? { commands } : {}),
         };
     },
 });

package/dist/commands/pkg/plugin-manage.js

@@ -8,7 +8,25 @@ import { updateConfig, updateState, ensureScopeInitialized } from '../../core/co
 import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink } from '../../core/fs-utils.js';
 import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
 import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
 import { isGitUrl, setPluginEnabled, resolveInstallScope } from './shared.js';
+/** Validate a just-installed/updated plugin's command manifest, if it declares
+ *  one. Returns undefined for plugins without a `commands` pointer. Never
+ *  executes the plugin binary — validation is fully static. */
+function commandReport(name, scope) {
+    const plugin = findPluginByName(name, scope);
+    if (plugin === null || typeof plugin.manifest.commands !== 'string' || plugin.manifest.commands.length === 0) {
+        return undefined;
+    }
+    const reserved = new Set(SUBTREE_NAMES);
+    // Report from the effective set so a cross-plugin top-level collision is
+    // visible at install time (a collided command is NOT mounted). A copy
+    // outside the effective set (disabled, or shadowed) cannot collide.
+    const v = validateEffectiveCommandPlugins(reserved).find((x) => x.plugin.root === plugin.root) ??
+        validatePluginCommands(plugin, reserved);
+    return { mounts: v.contributions.map((c) => c.node.name), issues: v.issues };
+}
 function classifyInstallRef(raw) {
     if (raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/')) {
         return { kind: 'local', value: raw };
@@ -203,10 +221,12 @@ function updateOnePlugin(plugin, marketplaceCache, opts) {
     }
     const manifest = readPluginManifest(plugin.root);
     updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? manifest?.version);
+    const commands = commandReport(plugin.name, plugin.scope);
     return {
         name: plugin.name,
         updated: contentUpdate.updated,
         sha: contentUpdate.sha,
+        ...(commands !== undefined ? { commands } : {}),
     };
 }
 export const pluginInstall = defineLeaf({
@@ -225,9 +245,13 @@ export const pluginInstall = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'Plugin name as installed.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the plugin was installed into.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the installed plugin directory.' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; the plugin binary is never executed.' },
         ],
         outputKind: 'object',
-        effects: ['Clones, links, or copies the plugin into the scope plugins directory. Registers the plugin in config.json with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.'],
+        effects: [
+            'Clones, links, or copies the plugin into the scope plugins directory. Registers the plugin in config.json with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
+            'If the plugin declares a command manifest, its commands go live on the next crtr invocation. A command leaf runs the plugin\'s own executable as trusted local code with your authority — only when you explicitly invoke that leaf, never on install, help, or discovery.',
+        ],
     },
     run: async (input) => {
         const rawRef = input['installRef'];
@@ -235,13 +259,11 @@ export const pluginInstall = defineLeaf({
         const gitRef = input['ref'];
         const scope = resolveInstallScope(scopeInput);
         const classified = classifyInstallRef(rawRef);
-        if (classified.kind === 'marketplace') {
-            return installFromMarketplace(classified.value, scope);
-        }
-        if (classified.kind === 'local') {
-            return installFromLocal(classified.value, scope);
-        }
-        return installFromGit(classified.value, gitRef, scope);
+        const installed = classified.kind === 'marketplace' ? installFromMarketplace(classified.value, scope)
+            : classified.kind === 'local' ? installFromLocal(classified.value, scope)
+                : installFromGit(classified.value, gitRef, scope);
+        const commands = commandReport(installed.name, installed.scope);
+        return commands !== undefined ? { ...installed, commands } : installed;
     },
 });
 export const pluginRemove = defineLeaf({
@@ -351,7 +373,7 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Plugin name to update. Omit to update all installed plugins.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, updated, sha}.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, updated, sha, commands?}. commands is present only for plugins declaring a command manifest: {mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})} — validated statically, never executing the plugin binary.' },
         ],
         outputKind: 'object',
         effects: ['Runs git pull in plugin or marketplace directories when they are git checkouts. Updates plugin version and last_updated state.'],

package/dist/commands/sys/__tests__/setup-core.test.js

@@ -1,7 +1,164 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { resolveBundledPiCliPath } from '../../../core/runtime/pi-cli.js';
+import { BINDING_CATALOG, resolveKeybindings } from '../../../core/keybindings/index.js';
+import { SetupKeybindingsDraft, buildSetupManifest } from '../setup-core.js';
+import { SetupWizard } from '../setup.js';
+import { applyTheme } from '../../../clients/attach/config-load.js';
+import { stripVTControlCharacters } from 'node:util';
+// The provider panel only touches the TUI on async OAuth transitions (never in
+// these keybindings-tab render/input tests) and reads auth from `agentDir`; a
+// no-op TUI stub and an empty temp agent dir keep the wizard headless.
+const stubTui = { requestRender() { } };
+const agentDir = mkdtempSync(join(tmpdir(), 'setup-wizard-test-'));
+test('setup keybinding draft edits, disables, resets, and discards transactionally', () => {
+    const draft = new SetupKeybindingsDraft({ 'crtr.attach.graph.toggle': ['alt+x'] });
+    assert.equal(draft.expression('crtr.attach.graph.toggle'), 'alt+x');
+    assert.equal(draft.dirty, false);
+    assert.equal(draft.edit('crtr.attach.graph.toggle', 'M-Y, ctrl+g').ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], ['alt+shift+y', 'ctrl+g']);
+    assert.equal(draft.dirty, true);
+    assert.equal(draft.unbind('crtr.attach.graph.toggle').ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], []);
+    draft.resetRow('crtr.attach.graph.toggle');
+    assert.equal(Object.hasOwn(draft.overrides(), 'crtr.attach.graph.toggle'), false);
+    draft.edit('crtr.attach.graph.toggle', 'alt+y');
+    draft.discard();
+    assert.deepEqual(draft.overrides(), { 'crtr.attach.graph.toggle': ['alt+x'] });
+    assert.equal(draft.dirty, false);
+});
+test('setup keybinding draft drops a member when the committed value equals the catalog default (N2 sparseness)', () => {
+    const draft = new SetupKeybindingsDraft(undefined);
+    const definition = BINDING_CATALOG.find((entry) => entry.id === 'crtr.attach.graph.toggle');
+    const defaultExpression = draft.expression(definition.id);
+    // Committing the seeded default verbatim must NOT record an override: the row
+    // stays sparse (no member) and the draft stays clean — no spurious unsaved/dot.
+    const result = draft.edit(definition.id, defaultExpression);
+    assert.equal(result.ok, true);
+    assert.equal(Object.hasOwn(draft.overrides(), definition.id), false);
+    assert.equal(draft.dirty, false);
+    // Editing to a real value records the member; re-committing the default drops it.
+    assert.equal(draft.edit(definition.id, 'ctrl+g').ok, true);
+    assert.deepEqual(draft.overrides()[definition.id], ['ctrl+g']);
+    assert.equal(draft.dirty, true);
+    assert.equal(draft.edit(definition.id, defaultExpression).ok, true);
+    assert.equal(Object.hasOwn(draft.overrides(), definition.id), false);
+    assert.equal(draft.dirty, false);
+});
+test('setup keybinding draft keeps the last valid cell value on syntax, collision, and safety errors', () => {
+    const draft = new SetupKeybindingsDraft(undefined);
+    const syntax = draft.edit('crtr.attach.graph.toggle', 'ctrl+not-a-key');
+    assert.equal(syntax.ok, false);
+    assert.deepEqual(draft.overrides(), {});
+    const collision = draft.edit('crtr.attach.graph.toggle', 'alt+m');
+    assert.equal(collision.ok, false);
+    assert.match(collision.diagnostics[0].message, /crtr\.mode\.cycle/);
+    assert.deepEqual(draft.overrides(), {});
+    const unsafe = draft.unbind('crtr.setup.keybindings.save');
+    assert.equal(unsafe.ok, false);
+    assert.match(unsafe.diagnostics[0].message, /save-keybindings/);
+    assert.deepEqual(draft.overrides(), {});
+});
+test('setup reset-all removes invalid and unknown raw members without cataloging pi bindings', () => {
+    const invalidRoot = new SetupKeybindingsDraft('alt+x');
+    assert.equal(invalidRoot.resolution().diagnostics[0]?.code, 'invalid-keybindings');
+    invalidRoot.resetAll();
+    assert.equal(invalidRoot.dirty, true);
+    assert.equal(invalidRoot.resolution().diagnostics.length, 0);
+    const draft = new SetupKeybindingsDraft({
+        'crtr.unknown': ['x'],
+        'crtr.attach.graph.toggle': 'alt+x',
+    });
+    assert.equal(draft.resolution().diagnostics.length, 2);
+    draft.resetAll();
+    assert.deepEqual(draft.overrides(), {});
+    assert.equal(draft.resolution().diagnostics.length, 0);
+    assert.equal(BINDING_CATALOG.some((entry) => entry.id.includes('app.') || entry.id.includes('tui.')), false);
+});
+test('setup keybinding draft refuses edits while the raw root is invalid until reset-all', () => {
+    const draft = new SetupKeybindingsDraft('alt+x');
+    assert.equal(draft.hasInvalidRoot(), true);
+    // An edit against an invalid root must NOT commit (the prior bug: it returned
+    // ok:true against an empty `current` while the row kept showing the default).
+    const rejected = draft.edit('crtr.attach.graph.toggle', 'ctrl+g');
+    assert.equal(rejected.ok, false);
+    assert.equal(rejected.diagnostics[0].code, 'invalid-keybindings');
+    assert.deepEqual(draft.overrides(), {});
+    // reset-all clears the invalid root; edits then succeed and display.
+    draft.resetAll();
+    assert.equal(draft.hasInvalidRoot(), false);
+    const accepted = draft.edit('crtr.attach.graph.toggle', 'ctrl+g');
+    assert.equal(accepted.ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], ['ctrl+g']);
+});
+test('setup keybindings editor stays visible while paging moves the selection (m3)', () => {
+    applyTheme({ cwd: process.cwd() });
+    const openingBindings = resolveKeybindings(undefined);
+    // A short terminal forces a small scroll window so paging past the edit row
+    // is the reproducible m3 scenario (editor was blind-typing off-screen before).
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, openingBindings, undefined, () => 14);
+    wizard.focused = true;
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    // Drive to the Keybindings tab (tab-next = Tab), open the editor on row 0 (Enter).
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    assert.match(render(), /Keybindings/);
+    wizard.handleInput('\r');
+    // Type a distinctive marker into the live editor buffer.
+    wizard.handleInput('zzz');
+    assert.match(render(), /zzz/, 'editor should echo typed input before paging');
+    // PageDown twice: selection moves off, but the editor row must remain on screen.
+    wizard.handleInput('\x1b[6~');
+    wizard.handleInput('\x1b[6~');
+    assert.match(render(), /zzz/, 'editor must stay visible (and keep capturing) after paging');
+});
+test('setup keybindings q-cancel with a dirty draft routes through discard-confirm, not a silent exit (N3)', () => {
+    applyTheme({ cwd: process.cwd() });
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 40);
+    wizard.focused = true;
+    let cancelled = false;
+    wizard.onCancel = () => { cancelled = true; };
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    // Make the draft dirty: unbind the selected row (delete key) so it has a real
+    // pending override.
+    wizard.handleInput('\x1b[3~');
+    assert.match(render(), /unsaved/, 'draft should be dirty after unbind');
+    // q (crtr.setup.cancel) in list mode must NOT drop the edits: it opens the same
+    // discard-confirm the Escape path uses.
+    wizard.handleInput('q');
+    assert.equal(cancelled, false, 'dirty draft must not silently exit on q');
+    assert.match(render(), /Discard every unsaved keybinding change\?/);
+    // A clean draft still exits on q (cancel elsewhere is unchanged).
+    const clean = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 40);
+    let cleanCancelled = false;
+    clean.onCancel = () => { cleanCancelled = true; };
+    clean.focused = true;
+    for (let i = 0; i < 5; i += 1)
+        clean.handleInput('\t');
+    clean.handleInput('q');
+    assert.equal(cleanCancelled, true, 'clean draft still exits on q');
+});
+test('setup keybindings selection always renders across group boundaries in a short window (m4 residual)', () => {
+    applyTheme({ cwd: process.cwd() });
+    // Small viewport so a window spans several group headings + a diagnostic line —
+    // the fixed-reserve page math used to let the selected row fail to render here.
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 13);
+    wizard.focused = true;
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    // Page/step down through the whole catalog; the selection marker must always render.
+    for (let step = 0; step < BINDING_CATALOG.length + 5; step += 1) {
+        assert.match(render(), /\u25b6/, `selection marker must render at step ${step}`);
+        wizard.handleInput('\x1b[6~'); // PageDown
+        wizard.handleInput('j'); // and a single-row step to hit every boundary alignment
+    }
+});
 test('resolveBundledPiCliPath uses crouter bundled pi instead of a standalone pi on PATH', () => {
     const prevPath = process.env.PATH;
     process.env.PATH = '';

package/dist/commands/sys/doctor.js

@@ -8,6 +8,8 @@ import { lsRemote } from '../../core/git.js';
 import { listNodes } from '../../core/canvas/index.js';
 import { activeFaultForDisplay } from '../../core/canvas/render.js';
 import { readFault } from '../../core/runtime/fault.js';
+import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
 }
@@ -89,6 +91,41 @@ function faultRemediation(fault) {
         logPath: fault.logPath,
     };
 }
+/**
+ * Validate the command manifest + executable path of every effective command
+ * plugin (the deduped, enabled set that actually composes into the tree).
+ * Purely static — the plugin binary is NEVER executed, and no remediation ever
+ * chmods or rewrites third-party plugin content (every fix is a human_action:
+ * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
+ * are reported, so `--scope` narrows these checks too.
+ */
+function runCommandPluginChecks(scopes) {
+    const results = [];
+    const inScope = new Set(scopes);
+    const reserved = new Set(SUBTREE_NAMES);
+    // Validate the whole effective set together so cross-plugin top-level name
+    // collisions surface here — a collided command is NOT mounted, and every
+    // claimant must fail, not pass.
+    for (const v of validateEffectiveCommandPlugins(reserved)) {
+        const plugin = v.plugin;
+        if (!inScope.has(plugin.scope))
+            continue;
+        if (v.issues.length === 0) {
+            const mounts = v.contributions.map((c) => c.node.name).join(', ');
+            results.push(pass(plugin.scope, `plugin:${plugin.name}:commands`, mounts.length > 0 ? `contributes top-level command(s): ${mounts}` : `command manifest valid`));
+            continue;
+        }
+        v.issues.forEach((issue, i) => {
+            const remediation = {
+                kind: 'human_action',
+                description: `${issue.next} If unfixable, disable (pkg plugin disable ${plugin.name}), update (pkg plugin update --name ${plugin.name}), or remove (pkg plugin remove ${plugin.name}) the plugin.`,
+            };
+            const detail = issue.path !== undefined ? ` at ${issue.path}` : '';
+            results.push(failCheck(plugin.scope, `plugin:${plugin.name}:commands[${i}]`, `${issue.code}${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, remediation));
+        });
+    }
+    return results;
+}
 function runFaultChecks() {
     const results = [];
     for (const node of listNodes()) {
@@ -240,7 +277,7 @@ function runChecksForScope(scope, opts) {
 export const sysDoctorLeaf = defineLeaf({
     name: 'doctor',
     description: 'diagnose installation health',
-    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, or a config entry points at a directory that no longer exists. Reports each problem with a structured remediation, and can apply the repairs for you.',
+    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or a command-plugin manifest/executable is malformed. Reports each problem with a structured remediation, and can apply the safe repairs for you.',
     help: {
         name: 'sys doctor',
         summary: 'diagnose missing manifests and broken config entries',
@@ -250,13 +287,13 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. Command-plugin manifest checks appear as plugin:<name>:commands (validated statically, never executed); their remediation is always a human_action (disable/update/remove the plugin). remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
-            'Read-only unless --fix is passed.',
-            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings stay read-only.',
+            'Read-only unless --fix is passed. Command-plugin manifests are validated statically — the plugin executable is never run, at any time.',
+            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and command-plugin findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
             'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with logPath) so callers can apply it directly without --fix.',
         ],
     },
@@ -270,6 +307,7 @@ export const sysDoctorLeaf = defineLeaf({
             const results = runChecksForScope(scope, { fix, remote });
             allResults.push(...results);
         }
+        allResults.push(...runCommandPluginChecks(scopes));
         allResults.push(...runFaultChecks());
         // Sort by scope then name (mirrors old printResults grouping)
         const scopeOrder = { user: 0, project: 1, builtin: 2, canvas: 3 };

package/dist/commands/sys/setup-core.d.ts

@@ -1,3 +1,4 @@
+import { type BindingId, type BindingResolution, type KeybindingDiagnostic, type SparseKeybindingOverrides } from '../../core/keybindings/index.js';
 export type SetupPackageId = 'crtr-extensions' | 'mode-switch' | 'oauth-adapter';
 export type SetupTool = 'tmux' | 'nvim';
 export type SetupPackageSourceKind = 'local-path' | 'npm';
@@ -58,6 +59,33 @@ export interface SetupInitialState {
     exaKeyPath: string;
     composioKeyPath: string;
 }
+export interface KeybindingEditResult {
+    readonly ok: boolean;
+    readonly diagnostics: readonly KeybindingDiagnostic[];
+}
+/** Transactional sparse keybinding draft used by the full-screen setup tab. */
+export declare class SetupKeybindingsDraft {
+    private expected;
+    private baseline;
+    private current;
+    private baselineInvalidRoot;
+    private invalidRoot;
+    constructor(rawKeybindings: unknown);
+    get dirty(): boolean;
+    overrides(): Record<string, unknown>;
+    expectedKeybindings(): unknown;
+    resolution(): BindingResolution<BindingId>;
+    /** True while the persisted `keybindings` root is a non-object (e.g. a string):
+     *  edits cannot be layered onto an invalid root, so the tab must reset-all first. */
+    hasInvalidRoot(): boolean;
+    expression(id: BindingId): string;
+    edit(id: BindingId, expression: string): KeybindingEditResult;
+    unbind(id: BindingId): KeybindingEditResult;
+    resetRow(id: BindingId): void;
+    resetAll(): void;
+    discard(): void;
+    markSaved(overrides: SparseKeybindingOverrides<BindingId>): void;
+}
 export declare function buildSetupManifest(resolveBuiltinPackageDir?: (name: string) => string): SetupPackageManifestEntry[];
 export declare function normalizePackageIdentity(source: string, settingsDir: string, homeDir: string): SetupPackageIdentity;
 export declare function detectInstalledSetupPackageIds(settingsJson: unknown, manifest?: SetupPackageManifestEntry[], settingsPath?: string, homeDir?: string): Set<SetupPackageId>;
@@ -68,6 +96,15 @@ export declare function buildSystemToolState(tool: SetupTool, packageManager: Pa
 export declare function resolveSettingsPath(homeDir?: string): string;
 export declare function resolveExaKeyPath(homeDir?: string): string;
 export declare function resolveComposioKeyPath(homeDir?: string): string;
+/** Where an already-present API key is resolved from — env var wins over the
+ *  key file, matching the runtime resolvers (search/exa.ts, connectors). */
+export type ApiKeySource = 'env' | 'file';
+export interface ApiKeyPresence {
+    present: boolean;
+    source?: ApiKeySource;
+}
+export declare function detectExaKey(homeDir?: string): ApiKeyPresence;
+export declare function detectComposioKey(homeDir?: string): ApiKeyPresence;
 export declare function buildSetupInitialState(opts?: {
     manifest?: SetupPackageManifestEntry[];
     settingsPath?: string;