@crouton-kit/crouter 0.3.78 → 0.3.79

package/dist/clients/attach/auth-pickers.d.ts

@@ -1,17 +1,5 @@
 import type { TUI } from '@earendil-works/pi-tui';
 import type { Picker, PickerControls } from './pickers.js';
-/** A compact auth summary for a provider — used by non-picker surfaces (e.g.
- *  the `crtr sys setup` login tab) to show which providers are already
- *  configured without mounting the full selector. */
-export interface ProviderAuthSummary {
-    id: string;
-    name: string;
-    configured: boolean;
-}
-/** Summarize which providers have a stored credential in `agentDir`'s auth.json.
- *  Mirrors the OAuth selector's provider list; `configured` is true when the
- *  provider has an explicit stored credential (OAuth token or API key). */
-export declare function summarizeProviderAuth(agentDir: string): ProviderAuthSummary[];
 /** `/login` — show the provider selector, then run pi's native login flow in
  *  the viewer. On success, notifies the broker to reload auth via reload_auth.
  *  Returns a Picker (OAuthSelectorComponent as the overlay). */

package/dist/clients/attach/auth-pickers.js

@@ -10,6 +10,8 @@
 import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { AuthStorage, ModelRegistry, OAuthSelectorComponent, LoginDialogComponent, } from '@earendil-works/pi-coding-agent';
+import { loginAnthropic, loginOpenAICodex } from '@earendil-works/pi-ai/oauth';
+import { ANTHROPIC_PROVIDER_ID, commitManagedLogin, isManagedProvider, readSubscriptionPool, removeManagedProvider, } from '../../core/subscription-state.js';
 /** Build an AuthStorage + ModelRegistry from the broker's agentDir (or pi's
  *  default). Both point at the SAME auth.json the broker uses — the viewer and
  *  broker share the filesystem (tmux-local invariant). */
@@ -47,17 +49,6 @@ function buildProviderList(authStorage, registry) {
     }
     return providers;
 }
-/** Summarize which providers have a stored credential in `agentDir`'s auth.json.
- *  Mirrors the OAuth selector's provider list; `configured` is true when the
- *  provider has an explicit stored credential (OAuth token or API key). */
-export function summarizeProviderAuth(agentDir) {
-    const { authStorage, registry } = buildLocalAuth(agentDir);
-    return buildProviderList(authStorage, registry).map((p) => ({
-        id: p.id,
-        name: p.name,
-        configured: authStorage.get(p.id) !== undefined,
-    }));
-}
 /** Open the browser with a URL (best-effort; platform-specific). */
 function openBrowser(url) {
     const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
@@ -112,6 +103,52 @@ export function buildLoginPicker(tui, agentDir, onAuthReloaded, notify, controls
         // inline under the editor (same slot as the model picker), not as a centered
         // overlay. `replace` focuses the dialog; `close()` (via finish) unmounts it.
         replace(dialog, dialog);
+        if (isManagedProvider(providerId)) {
+            // Managed provider (anthropic / openai-codex): drive pi's OAuth flow ourselves so we hold
+            // the credential, then persist it through the coordinated writer (commitManagedLogin ->
+            // commitDefaultIdentity for the default slot) rather than authStorage.login(). That keeps
+            // auth.json + the rotation pool identity in lockstep and runs the account-uniqueness gate
+            // the raw path skipped. /login here manages only the DEFAULT slot (label === providerId).
+            const runLogin = providerId === ANTHROPIC_PROVIDER_ID ? loginAnthropic : loginOpenAICodex;
+            // Snapshot the default slot's rate-limit timestamp BEFORE OAuth begins: a strictly newer
+            // concurrent 429 recorded during the login must survive a same-account re-login.
+            const defaultLastRateLimitedAt = readSubscriptionPool(providerId).find((entry) => entry.label === providerId)?.lastRateLimitedAt ?? 0;
+            runLogin({
+                onAuth: (info) => {
+                    dialog.showAuth(info.url, info.instructions);
+                    openBrowser(info.url);
+                },
+                onPrompt: (prompt) => dialog.showPrompt(prompt.message, prompt.placeholder),
+                onProgress: (message) => {
+                    dialog.showProgress(message);
+                },
+                onManualCodeInput: () => dialog.showManualInput('Paste the code or URL:'),
+            })
+                .then((credential) => {
+                if (settled)
+                    return;
+                const accountId = typeof credential.accountId === 'string' && credential.accountId.trim()
+                    ? credential.accountId.trim()
+                    : undefined;
+                commitManagedLogin(providerId, providerId, {
+                    refresh: credential.refresh,
+                    access: credential.access,
+                    expires: credential.expires,
+                    accountId,
+                    defaultLastRateLimitedAt,
+                });
+                notify(`Logged in to ${provider.name}`);
+                onAuthReloaded();
+                finish();
+            })
+                .catch((err) => {
+                if (err?.name !== 'AbortError') {
+                    notify(`Login error: ${String(err?.message ?? err)}`);
+                }
+                finish();
+            });
+            return;
+        }
         if (provider.authType === 'oauth') {
             const isKnownOAuth = authStorage.getOAuthProviders().some((p) => p.id === providerId);
             if (!isKnownOAuth) {
@@ -195,10 +232,22 @@ export function buildLogoutPicker(agentDir, onAuthReloaded, notify, close) {
     const getAuthStatus = (id) => authStorage.getAuthStatus(id);
     const onSelect = (providerId) => {
         const provider = providers.find((p) => p.id === providerId);
-        authStorage.logout(providerId);
-        close();
-        notify(`Logged out of ${provider?.name ?? providerId}`);
-        onAuthReloaded();
+        try {
+            // Managed providers tear down the WHOLE provider (every rotation account + the auth.json
+            // default record) through the coordinated service, never a raw authStorage.logout() that
+            // would strip only auth.json and orphan the pool.
+            if (isManagedProvider(providerId))
+                removeManagedProvider(providerId);
+            else
+                authStorage.logout(providerId);
+            close();
+            notify(`Logged out of ${provider?.name ?? providerId}`);
+            onAuthReloaded();
+        }
+        catch (error) {
+            close();
+            notify(`Logout error: ${error instanceof Error ? error.message : String(error)}`);
+        }
     };
     const component = new OAuthSelectorComponent('logout', authStorage, providers, onSelect, () => close(), getAuthStatus);
     return { component, focus: component };

package/dist/clients/attach/graph-overlay.d.ts

@@ -1,4 +1,5 @@
 import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type BindingResolution, type BindingId } from '../../core/keybindings/index.js';
 import { type CanvasSource } from '../../core/canvas/source.js';
 import type { AttachPalette } from './config-load.js';
 export declare class GraphOverlay implements Component {
@@ -6,6 +7,7 @@ export declare class GraphOverlay implements Component {
     private readonly self;
     private readonly getAsks;
     private readonly palette;
+    private bindings;
     private readonly source;
     private handle;
     /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
@@ -17,7 +19,7 @@ export declare class GraphOverlay implements Component {
     private cursorId;
     /** Viewport scroll offset (row index of the top visible tree row). */
     private scrollTop;
-    /** Transient y/n confirm gate (kill). */
+    /** Transient close confirmation gate. */
     private pendingConfirm;
     private snapshot;
     private snapshotSeq;
@@ -26,7 +28,15 @@ export declare class GraphOverlay implements Component {
      *  default and makes Enter/m/x no-op instead of shelling local focus/kill
      *  commands against a remote graph row. See the file header. */
     private readonly remote;
-    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>, palette: AttachPalette, source?: CanvasSource);
+    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>, palette: AttachPalette, bindings: BindingResolution<BindingId>, source?: CanvasSource);
+    setBindings(bindings: BindingResolution<BindingId>): void;
+    private matches;
+    private hint;
+    /** Compose footer hints in priority order, dropping WHOLE entries that would
+     *  overflow `budget` visible columns rather than letting the border mid-clip
+     *  the tail — so the prioritized head (dismiss + remapped local actions) stays
+     *  discoverable even in a narrow overlay. */
+    private fitHints;
     isOpen(): boolean;
     open(): void;
     close(): void;

package/dist/clients/attach/graph-overlay.js

@@ -1,4 +1,4 @@
-// graph-overlay.ts — the alt+g GRAPH navigator overlay for `crtr surface attach` (Unit Q).
+// graph-overlay.ts — the configurable GRAPH navigator overlay for `crtr surface attach`.
 //
 // Native reimplementation of canvas-nav.ts's GRAPH modal as a pi-tui OVERLAY
 // (the viewer has no pi extension host). `tui.showOverlay(this, …)` mounts this
@@ -6,12 +6,9 @@
 // CAPTURES keyboard focus (mirrors extension-dialogs.ts);
 // `OverlayHandle.hide()` tears it down and restores focus to the editor. While
 // shown, every key routes to handleInput() — a fold-aware NERDTree of the
-// active CanvasSource subscription graph with the canvas-nav keymap:
-//   j/k move · h/l fold/ascend-descend · g/G top/bottom · ↵ focus (swap into
-//   this pane) · m focus manager · x kill (y/n confirm) · esc close.
-// `e` is a tmux-menu prefixBind, not a GRAPH key, so it is swallowed (per
-// canvas-nav). Model/render uses the CanvasSource snapshot built for this
-// overlay; keys are decoded with pi-tui's canonical matchesKey (kitty/CSI-u aware).
+// active CanvasSource subscription graph. Actions and footer hints resolve from
+// the crouter binding catalog; input is decoded with pi-tui's canonical matcher
+// (kitty/CSI-u aware).
 //
 // Enter/m/x SHELL `crtr` out-of-process (node focus / node lifecycle close) — the viewer
 // itself never spawns pi or opens a session (the §0 one-writer invariant). It
@@ -30,6 +27,7 @@
 // graph structure + node metadata ONLY.
 import { execFile } from 'node:child_process';
 import { matchesKey, truncateToWidth } from '@earendil-works/pi-tui';
+import { formatBinding, matchesPiTuiInput, } from '../../core/keybindings/index.js';
 import { fullName } from '../../core/canvas/index.js';
 import { activeFaultForDisplay } from '../../core/canvas/render.js';
 import { readFault } from '../../core/runtime/fault.js';
@@ -43,18 +41,34 @@ import { beginFrame, navLabel, nodeGlyph, tokensCell, cycleBadge, askBadge, acti
 // clipped. margin keeps it off the screen edges.
 const HEIGHT_PCT = 0.72;
 const OVERLAY_OPTIONS = { anchor: 'center', width: '72%', minWidth: 48, maxHeight: '72%', margin: 1 };
-// Viewer-specific hint: nav-model's shared GRAPH_HINT advertises "e expand",
-// but that key is the tmux pane-expand prefix-bind canvas-nav installs in its
-// host pane — the attach overlay has no such bind and swallows `e`, so the key
-// would do nothing here. Drop it.
-const GRAPH_HINT = `${DIM}jk move · hl fold · ↵ focus · x kill · m mgr · esc${RESET}`;
-// REMOTE mode drops focus/kill/mgr — Enter/m/x no-op there (see the file header).
-const GRAPH_HINT_REMOTE = `${DIM}jk move · hl fold · esc${RESET}`;
+// The footer is width-budgeted (fitHints drops WHOLE trailing entries that
+// won't fit rather than mid-clipping the tail). List the keys a user most needs
+// to discover first — dismiss (the only way out) then the remapped local
+// actions — so they survive at the narrowest overlay width; routine navigation
+// trails and is the first to be dropped.
+const GRAPH_PRIMARY_LOCAL_HINTS = [
+    ['crtr.graph.dismiss', 'dismiss'],
+    ['crtr.graph.focus', 'focus'],
+    ['crtr.graph.close-subtree', 'close'],
+    ['crtr.graph.focus-manager', 'manager'],
+];
+const GRAPH_PRIMARY_REMOTE_HINTS = [
+    ['crtr.graph.dismiss', 'dismiss'],
+];
+const GRAPH_NAV_HINTS = [
+    ['crtr.graph.down', 'down'],
+    ['crtr.graph.up', 'up'],
+    ['crtr.graph.first', 'first'],
+    ['crtr.graph.last', 'last'],
+    ['crtr.graph.collapse-or-manager', 'fold/manager'],
+    ['crtr.graph.expand-or-child', 'expand/child'],
+];
 export class GraphOverlay {
     tui;
     self;
     getAsks;
     palette;
+    bindings;
     source;
     handle;
     /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
@@ -66,7 +80,7 @@ export class GraphOverlay {
     cursorId;
     /** Viewport scroll offset (row index of the top visible tree row). */
     scrollTop = 0;
-    /** Transient y/n confirm gate (kill). */
+    /** Transient close confirmation gate. */
     pendingConfirm;
     snapshot;
     snapshotSeq = 0;
@@ -75,14 +89,43 @@ export class GraphOverlay {
      *  default and makes Enter/m/x no-op instead of shelling local focus/kill
      *  commands against a remote graph row. See the file header. */
     remote;
-    constructor(tui, self, getAsks, palette, source = localCanvasSource) {
+    constructor(tui, self, getAsks, palette, bindings, source = localCanvasSource) {
         this.tui = tui;
         this.self = self;
         this.getAsks = getAsks;
         this.palette = palette;
+        this.bindings = bindings;
         this.source = source;
         this.remote = source instanceof RemoteCanvasSource;
     }
+    setBindings(bindings) {
+        this.bindings = bindings;
+        if (this.handle !== undefined)
+            this.tui.requestRender();
+    }
+    matches(id, data) {
+        return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    hint(entries) {
+        return entries.flatMap(([id, label]) => this.bindings.gestures(id).length === 0 ? [] : [`${formatBinding(this.bindings, id)} ${label}`]);
+    }
+    /** Compose footer hints in priority order, dropping WHOLE entries that would
+     *  overflow `budget` visible columns rather than letting the border mid-clip
+     *  the tail — so the prioritized head (dismiss + remapped local actions) stays
+     *  discoverable even in a narrow overlay. */
+    fitHints(entries, budget) {
+        const SEP = 3; // visible width of ' · '
+        const out = [];
+        let used = 0;
+        for (const piece of this.hint(entries)) {
+            const add = (out.length === 0 ? 0 : SEP) + visibleWidth(piece);
+            if (used + add > budget)
+                break;
+            out.push(piece);
+            used += add;
+        }
+        return out.join(' · ');
+    }
     isOpen() {
         return this.handle !== undefined;
     }
@@ -341,8 +384,14 @@ export class GraphOverlay {
             ? `${BOLD}⌗ canvas graph${RESET} ${DIM}(${cursorIdx + 1}/${rows.length})${RESET}`
             : `${BOLD}⌗ canvas graph${RESET} ${DIM}(loading)${RESET}`;
         const hint = this.pendingConfirm !== undefined
-            ? `${YELLOW}${this.pendingConfirm.label} ${BOLD}y/n${RESET}`
-            : this.remote ? GRAPH_HINT_REMOTE : GRAPH_HINT;
+            ? `${YELLOW}${this.pendingConfirm.label} ${BOLD}${this.hint([
+                ['crtr.graph.confirm.accept', 'accept'],
+                ['crtr.graph.confirm.cancel', 'cancel'],
+            ]).join(' · ')}${RESET}`
+            : `${DIM}${this.fitHints([
+                ...(this.remote ? GRAPH_PRIMARY_REMOTE_HINTS : GRAPH_PRIMARY_LOCAL_HINTS),
+                ...GRAPH_NAV_HINTS,
+            ], Math.max(1, width - 5))}${RESET}`; // budget matches borderRow's span
         // Frame the panel: title in the top border, hint in the bottom border, tree
         // rows boxed with themed side bars (truncate/pad to the inner width so the
         // right edge stays flush and opaque).
@@ -385,18 +434,19 @@ export class GraphOverlay {
     dispatch(data) {
         // y/n confirm gate takes precedence over everything.
         if (this.pendingConfirm !== undefined) {
-            if (matchesKey(data, 'y')) {
+            if (this.matches('crtr.graph.confirm.accept', data)) {
                 const act = this.pendingConfirm.action;
                 this.pendingConfirm = undefined;
                 act();
             }
             else {
-                this.pendingConfirm = undefined; // any other key cancels
+                // Preserve GRAPH's modal fallback: any non-accept key cancels close.
+                this.pendingConfirm = undefined;
             }
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'escape')) {
+        if (this.matches('crtr.graph.dismiss', data)) {
             this.close();
             return;
         }
@@ -427,29 +477,29 @@ export class GraphOverlay {
             }
             return idx;
         };
-        if (matchesKey(data, 'j')) {
+        if (this.matches('crtr.graph.down', data)) {
             idx = step(idx, 1);
             this.cursorId = rows[idx]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'k')) {
+        if (this.matches('crtr.graph.up', data)) {
             idx = step(idx, -1);
             this.cursorId = rows[idx]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'g')) {
+        if (this.matches('crtr.graph.first', data)) {
             this.cursorId = rows[edge(1)]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'shift+g')) {
+        if (this.matches('crtr.graph.last', data)) {
             this.cursorId = rows[edge(-1)]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'h')) {
+        if (this.matches('crtr.graph.collapse-or-manager', data)) {
             if (cur !== undefined && cur.hasKids && !cur.collapsed) {
                 this.userCollapsed.add(cur.id);
                 this.userExpanded.delete(cur.id);
@@ -463,7 +513,7 @@ export class GraphOverlay {
             }
             return;
         }
-        if (matchesKey(data, 'l')) {
+        if (this.matches('crtr.graph.expand-or-child', data)) {
             if (cur !== undefined && cur.collapsed && cur.hasKids) {
                 this.userExpanded.add(cur.id);
                 this.userCollapsed.delete(cur.id);
@@ -477,12 +527,12 @@ export class GraphOverlay {
             }
             return;
         }
-        // Enter/m/x drive local lifecycle/focus (`crtr node focus` / `crtr node
+        // Focus/manager/close actions drive local lifecycle/focus (`crtr node focus` / `crtr node
         // lifecycle close`) against `this.cursorId` — a REMOTE graph row's id has no
         // relationship to this machine's canvas.db (or, worse, collides with one
         // that does), so all three no-op in remote mode instead of shelling a local
-        // mutation command against a remote id. GRAPH_HINT_REMOTE drops their hints.
-        if (matchesKey(data, 'enter')) {
+        // mutation command against a remote id. Their hints are omitted remotely.
+        if (this.matches('crtr.graph.focus', data)) {
             if (this.remote)
                 return;
             if (this.cursorId !== undefined)
@@ -490,7 +540,7 @@ export class GraphOverlay {
             this.close();
             return;
         }
-        if (matchesKey(data, 'm')) {
+        if (this.matches('crtr.graph.focus-manager', data)) {
             if (this.remote)
                 return;
             const mgr = snapshot?.managerOf.get(this.self);
@@ -500,7 +550,7 @@ export class GraphOverlay {
             }
             return;
         }
-        if (matchesKey(data, 'x')) {
+        if (this.matches('crtr.graph.close-subtree', data)) {
             if (this.remote)
                 return;
             const target = this.cursorId ?? this.self;
@@ -510,7 +560,7 @@ export class GraphOverlay {
             this.tui.requestRender();
             return;
         }
-        // Modal: swallow everything else (incl. the `e` tmux-menu bind) so a stray
+        // Modal: swallow everything else so a stray
         // key never reaches the editor underneath.
     }
     // -------------------------------------------------------------------------

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.'],