@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/core/canvas/browse/render.js

@@ -26,9 +26,11 @@ export const PROMPT_LINES = 3;
 export const REPLY_LINES = 3;
 export const PREVIEW_BODY = PROMPT_LINES + REPLY_LINES;
 export const PREVIEW_HEIGHT = PREVIEW_BODY + 2;
-//   header = title + tab bar + status line + column header + separator (+ search input)
-export function headerHeight(search) {
-    return 5 + (search ? 1 : 0);
+//   header = title + tab bar + status line + column header + separator (+ input line)
+// `inputLine` is true whenever a text-input mode is open (search / rename / message)
+// — each adds one prompt row above the column header.
+export function headerHeight(inputLine) {
+    return 5 + (inputLine ? 1 : 0);
 }
 // ── Row table layout ──────────────────────────────────────────────────────────
 // A row is three zones: a fixed-width STATUS rail (glyph + word) on the left, the
@@ -57,6 +59,7 @@ const FG_CYAN = '36';
 const FG_GRAY = '90'; // bright-black
 const FG_BRIGHT_YELLOW = '93';
 const FG_BRIGHT_CYAN = '96'; // query-match highlight (ties to the cyan search accent)
+const FG_MAGENTA = '35'; // pin star (distinct from the yellow ⚑ asks flag)
 // STATUS_GLYPH + STATUS_COLOR are imported from ../status-glyph.js (the shared
 // canvas-graph map). STATUS_COLOR there is NUMERIC SGR (e.g. 32) — wrap with
 // `sgr()` where a string ANSI code is needed (Span fg / template literals accept
@@ -232,7 +235,7 @@ function assembleRow(left, right, width, color, lineBase, fill) {
 }
 /** One table row: `<status rail>  <indent><collapse> <name> <flags>` ........ `<meta>`.
  *  `showCwd` adds the project column (All-dirs view); `now` drives the age. */
-function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
+function rowLine(row, tree, width, isCursor, query, caps, showCwd, now, isPinned) {
     const node = tree.nodes.get(row.id);
     if (node === undefined)
         return '';
@@ -254,12 +257,15 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
     // label live in the rail). Dim yellow so it reads as secondary detail.
     if (r.hanging != null)
         flags.push({ text: ` · ${faultSummary(r.hanging, now)}`, style: { fg: FG_YELLOW, dim: true } });
+    // Pin marker travels just before the name so a starred node is scannable in any
+    // tab/sort. Magenta keeps it distinct from the yellow ⚑ asks flag.
+    const pinMark = isPinned ? [{ text: '★ ', style: { fg: FG_MAGENTA, bold: true } }] : [];
     const status = statusRail(r);
     const right = metaCluster(r, now, showCwd);
     const treeLead = `${indent}${collapse} `;
-    // Clip the NAME (only) so gutter + status + tree + name + flags + meta all fit;
-    // the cluster is dropped first (assembleRow) when even a 4-col name won't fit it.
-    const fixed = spansWidth([gutter]) + spansWidth(status) + [...treeLead].length + spansWidth(flags);
+    // Clip the NAME (only) so gutter + status + tree + pin + name + flags + meta all
+    // fit; the cluster is dropped first (assembleRow) when even a 4-col name won't fit.
+    const fixed = spansWidth([gutter]) + spansWidth(status) + [...treeLead].length + spansWidth(pinMark) + spansWidth(flags);
     const rightW = spansWidth(right);
     const nameMax = Math.max(4, width - fixed - rightW - 1);
     const nameStyle = { dim: !isCursor && terminal, bold: isCursor }; // dim terminal names; bold the cursor row
@@ -267,6 +273,7 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
         gutter,
         ...status,
         { text: treeLead, style: { dim: true } },
+        ...pinMark,
         ...nameSpans(clip(r.name, nameMax), query, nameStyle),
         ...flags,
     ];
@@ -403,16 +410,63 @@ function previewPanel(r, width, caps, now, query) {
     }
     return out;
 }
+/** The keybinding help overlay — a full-screen cheatsheet that replaces the body
+ *  while `?` is held open. Grouped by intent so the whole key surface is legible in
+ *  one glance (the footer only ever advertises the common few). */
+const HELP_ROWS = [
+    ['Move', '↑/↓  j/k', 'up / down'],
+    ['', 'g / G', 'top / bottom'],
+    ['', '.', 'jump to this node (recenter)'],
+    ['Tree', '→/←  h/l', 'expand / collapse'],
+    ['', 'space', 'toggle fold'],
+    ['Tabs', 'Tab / 1-5', 'All · Live · Dormant · Attention · Pinned'],
+    ['Find', '/', 'fuzzy search (name · kind · id · prompts)'],
+    ['Pin', 'f', 'star / unstar — floats to top, Pinned tab'],
+    ['Open', '⏎', 'resume the node'],
+    ['Act', 'm', 'message the node (no resume)'],
+    ['', 'R', 'rename the node'],
+    ['', 'x', 'close-out node + subtree'],
+    ['', 'K', 'revive now (a hanging node)'],
+    ['View', 's', 'cycle sort (attention/tree/relevance/recency)'],
+    ['', 'c', 'toggle cwd scope'],
+    ['', 'r', 'toggle residents-only'],
+    ['', 'p', 'toggle preview panel'],
+    ['Quit', 'q / Esc', ''],
+];
+function renderHelp(size, caps) {
+    const cols = Math.max(20, size.cols);
+    const rows = Math.max(8, size.rows);
+    const width = cols - 1;
+    const lines = [];
+    lines.push(`${BOLD}Canvas navigator — keys${RESET}`);
+    lines.push('');
+    const dim = (s) => `${DIM}${s}${RESET}`;
+    for (const [group, keys, desc] of HELP_ROWS) {
+        const g = group.padEnd(6);
+        const k = keys.padEnd(12);
+        const line = `  ${dim(g)}${BOLD}${k}${RESET}${desc === '' ? '' : `  ${dim(desc)}`}`;
+        lines.push(clip(line, width));
+    }
+    lines.push('');
+    lines.push(dim('  ? or any key to close'));
+    while (lines.length < rows - 1)
+        lines.push('');
+    const body = lines.map((l) => `${l}${ESC}K`).join('\r\n');
+    return `${ESC}H${body}${ESC}J`;
+}
 /**
  * Render the whole frame. Returns a single string that, written as-is, repaints
  * the screen in place. `caps` gates all hue (defaults to a no-color frame so
  * existing callers / non-TTY paths stay color-free).
  */
 export function renderFrame(state, size, caps = { color: false, color256: false }) {
+    if (state.help === true)
+        return renderHelp(size, caps);
     const cols = Math.max(20, size.cols);
     const rows = Math.max(8, size.rows);
     const width = cols - 1; // leave the last column for \x1b[K
     const now = Date.now();
+    const inputMode = state.search || state.rename === true || state.message === true;
     const lines = [];
     // line 1 — title + right-aligned status summary (each glyph in its status hue).
     const title = `${BOLD}Canvas${RESET} — ${state.totalNodes} nodes`;
@@ -428,10 +482,12 @@ export function renderFrame(state, size, caps = { color: false, color256: false
     lines.push(tabBar(state.tab, caps.color));
     // line 3 — status line (scope · sort · filter).
     lines.push(statusLine(state));
-    // line 4 — search input, only while actively typing a search.
-    if (state.search) {
-        const slash = caps.color ? `${ESC}${FG_CYAN}m/${RESET}` : '/';
-        lines.push(`${slash} ${state.query}▎`);
+    // line 4 — the text-input prompt, only while a search / rename / message is open.
+    if (inputMode) {
+        const prefix = state.rename === true ? 'rename ▸' : state.message === true ? 'msg ▸' : '/';
+        const buf = state.rename === true ? (state.renameBuf ?? '') : state.message === true ? (state.messageBuf ?? '') : state.query;
+        const p = caps.color ? `${ESC}${FG_CYAN}m${prefix}${RESET}` : prefix;
+        lines.push(`${p} ${buf}▎`);
     }
     // column header (table labels) + separator.
     const showCwd = state.cwdScope === null; // project column only matters across dirs
@@ -451,7 +507,8 @@ export function renderFrame(state, size, caps = { color: false, color256: false
     }
     else {
         for (let i = start; i < end; i++) {
-            lines.push(rowLine(state.visible[i], state.tree, width, i === state.cursor, state.query, caps, showCwd, now));
+            const vr = state.visible[i];
+            lines.push(rowLine(vr, state.tree, width, i === state.cursor, state.query, caps, showCwd, now, state.pinned.has(vr.id)));
         }
         for (let i = end - start; i < viewport; i++)
             lines.push('');
@@ -477,11 +534,11 @@ export function renderFrame(state, size, caps = { color: false, color256: false
         const selRow = state.visible[state.cursor];
         const cursorRow = selRow !== undefined ? state.tree.nodes.get(selRow.id)?.row : undefined;
         const hangingHint = cursorRow?.hanging != null ? 'K revive now  ' : '';
-        const footer = state.search
+        const footer = inputMode
             ? '⏎ commit  Esc cancel  ⌫ delete'
             : state.readOnly === true
-                ? '↑↓ move  →/← tree  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit  — read-only remote canvas'
-                : `${hangingHint}↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit`;
+                ? '↑↓ move  →/← tree  / search  f pin  Tab tabs  ? more  q quit  — read-only remote canvas'
+                : `${hangingHint}↑↓ move  ⏎ resume  / search  f pin  m msg  x close  R rename  ? more  q quit`;
         lines.push(`${DIM}${clip(footer, width)}${RESET}`);
     }
     // Assemble: home, each line cleared to EOL, then clear below.

package/dist/core/canvas/nav-model.js

@@ -1,16 +1,10 @@
-// nav-model.ts — the pure model/render layer of the canvas graph-nav chrome.
+// nav-model.ts — the pure model/render layer for attach's canvas chrome.
 //
-// Extracted from src/pi-extensions/canvas-nav.ts so a SINGLE source feeds both
-// the legacy pi extension (canvas-nav) and the headless `crtr surface attach` viewer.
 // Everything here is pi-API-free: it reads the canvas (sqlite + meta.json + node
-// telemetry) and produces ANSI-styled strings + a flattened graph model. The
-// extension-host wiring (widgets, key taps, the ask-poll timer, run/focus
-// shelling) stays in canvas-nav.ts and drives these functions.
-//
-// Mutable interaction state that the legacy extension held at module scope —
-// the per-node ask counts and the manual fold overrides — is threaded through
-// parameters here (see `asks` and `FoldState`) so this layer owns no singletons
-// and each consumer keeps its own state.
+// telemetry) and produces ANSI-styled strings plus a flattened graph model.
+// Per-view interaction state, including ask counts and manual fold overrides, is
+// threaded through parameters (see `asks` and `FoldState`) so this layer owns no
+// singletons and each consumer keeps its own state.
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';

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

@@ -23,6 +23,11 @@ export declare function canvasDbPath(): string;
  *  local-disk hosts. Parent dir is created on use so both paths just work. */
 export declare function viewSocketPath(nodeId: string): string;
 export declare function nodesRoot(): string;
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export declare function sessionListCachePath(): string;
 export declare function nodeDir(nodeId: string): string;
 export declare function contextDir(nodeId: string): string;
 /** Replace the literal env-var tokens `$CRTR_CONTEXT_DIR` / `$CRTR_NODE_ID` in

package/dist/core/canvas/paths.js

@@ -63,6 +63,13 @@ export function viewSocketPath(nodeId) {
 export function nodesRoot() {
     return join(crtrHome(), 'nodes');
 }
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export function sessionListCachePath() {
+    return join(crtrHome(), 'session-list-cache.json');
+}
 export function nodeDir(nodeId) {
     return join(nodesRoot(), nodeId);
 }

package/dist/core/command-plugins/adapter.d.ts

@@ -0,0 +1,15 @@
+import type { InstalledPlugin } from '../../types.js';
+import type { Field } from '../help.js';
+export interface ExternalLeafSpec {
+    plugin: InstalledPlugin;
+    /** Absolute, resolved executable path. */
+    executable: string;
+    /** Full canonical command path, e.g. ['app', 'show']. */
+    commandPath: string[];
+    /** Declared leaf output fields — validated against the result before render. */
+    output: Field[];
+}
+/** Execute one external leaf and return its result object (crtr renders it via
+ *  the generic renderer; `--json` mirrors it). Throws a CrtrError for any
+ *  protocol violation or the plugin's own recoverable error. */
+export declare function executeExternalLeaf(spec: ExternalLeafSpec, input: Record<string, unknown>): Record<string, unknown>;

package/dist/core/command-plugins/adapter.js

@@ -0,0 +1,145 @@
+// External leaf adapter — the execution seam for a command plugin's leaf.
+//
+// On explicit leaf invocation only (never on discovery/help), direct-spawn the
+// plugin's canonical executable with `--crtr-command-protocol 1`, write one
+// JSON request to stdin, and parse exactly one JSON response envelope from
+// stdout. The envelope's `ok` is the source of truth; crtr owns rendering and
+// error normalization. The executable inherits the caller's cwd + full
+// environment and owns its own time budget (no crtr timeout) — this is a trust
+// boundary, not a sandbox (installed code can already read the caller's files).
+import { spawnSync } from 'node:child_process';
+import { CrtrError } from '../errors.js';
+import { diag } from '../io.js';
+import { ExitCode } from '../../types.js';
+const MAX_STDOUT = 10 * 1024 * 1024; // 10 MiB hard cap on plugin stdout.
+const RESERVED_CODES = new Set(['internal', 'unknown_path', 'command_collision', 'plugin_protocol_error']);
+// Strict snake_case: no leading/trailing underscore, no consecutive underscores.
+const SNAKE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+const NEXT = 'Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.';
+/** Execute one external leaf and return its result object (crtr renders it via
+ *  the generic renderer; `--json` mirrors it). Throws a CrtrError for any
+ *  protocol violation or the plugin's own recoverable error. */
+export function executeExternalLeaf(spec, input) {
+    const request = {
+        protocolVersion: 1,
+        command: spec.commandPath,
+        input,
+        context: {
+            cwd: process.cwd(),
+            plugin: {
+                name: spec.plugin.name,
+                version: spec.plugin.version ?? spec.plugin.manifest.version ?? null,
+                scope: spec.plugin.scope,
+                root: spec.plugin.root,
+            },
+        },
+    };
+    const res = spawnSync(spec.executable, ['--crtr-command-protocol', '1'], {
+        input: JSON.stringify(request),
+        cwd: process.cwd(),
+        env: process.env,
+        maxBuffer: MAX_STDOUT,
+        stdio: ['pipe', 'pipe', 'inherit'],
+        encoding: 'utf8',
+    });
+    if (res.error !== undefined) {
+        const err = res.error;
+        // spawnSync signals a maxBuffer overrun as ENOBUFS (and kills the child);
+        // the exec-family code is accepted too for robustness across Node versions.
+        if (err.code === 'ENOBUFS' || err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            throw protocolError(spec, `stdout exceeded the 10 MiB cap`, 'one JSON envelope under 10 MiB on stdout');
+        }
+        throw protocolError(spec, `executable could not be run (${err.code ?? err.message})`, 'a runnable command executable');
+    }
+    if (res.signal !== null) {
+        throw protocolError(spec, `executable was killed by signal ${res.signal}`, 'a clean exit with one JSON envelope on stdout');
+    }
+    const stdout = res.stdout ?? '';
+    let envelope;
+    try {
+        envelope = JSON.parse(stdout.trim());
+    }
+    catch {
+        throw protocolError(spec, `stdout was not a single JSON envelope`, 'exactly one JSON envelope on stdout');
+    }
+    if (!isObject(envelope)) {
+        throw protocolError(spec, `stdout was not a JSON object`, 'a { protocolVersion: 1, ok: boolean, ... } envelope');
+    }
+    if (envelope['protocolVersion'] !== 1) {
+        throw protocolError(spec, `unsupported protocolVersion ${String(envelope['protocolVersion'])}`, 'protocolVersion exactly 1');
+    }
+    if (typeof envelope['ok'] !== 'boolean') {
+        throw protocolError(spec, `envelope is missing a boolean "ok"`, 'a boolean ok field');
+    }
+    const ok = envelope['ok'];
+    // `ok` is the source of truth; an exit-code mismatch is a soft diagnostic.
+    if (ok && res.status !== 0) {
+        diag(`crtr: ${label(spec)} returned ok:true but exited ${res.status} (honoring the envelope)`);
+    }
+    else if (!ok && res.status === 0) {
+        diag(`crtr: ${label(spec)} returned ok:false but exited 0 (honoring the envelope)`);
+    }
+    if (ok) {
+        const result = envelope['result'];
+        if (!isObject(result)) {
+            throw protocolError(spec, `success envelope has no result object`, 'result: an object matching the declared output');
+        }
+        validateResult(spec, result);
+        return result;
+    }
+    // Recoverable command failure → structured CrtrError with the plugin's code.
+    const error = envelope['error'];
+    if (!isObject(error) || typeof error['code'] !== 'string' || typeof error['message'] !== 'string') {
+        throw protocolError(spec, `error envelope is missing a { code, message }`, 'error: { code, message, ... }');
+    }
+    const code = error['code'];
+    if (!SNAKE.test(code) || RESERVED_CODES.has(code)) {
+        throw protocolError(spec, `error code "${code}" is invalid or reserved`, `a lowercase snake_case code not in {${[...RESERVED_CODES].join(', ')}}`);
+    }
+    throw new CrtrError(code, error['message'], ExitCode.GENERAL, {
+        received: error['received'],
+        field: typeof error['field'] === 'string' ? error['field'] : undefined,
+        next: typeof error['next'] === 'string' ? error['next'] : NEXT,
+    });
+}
+/** Enforce declared top-level output field presence + primitive/container
+ *  type. A missing required field or a type mismatch is a protocol error. */
+function validateResult(spec, result) {
+    for (const f of spec.output) {
+        const present = Object.prototype.hasOwnProperty.call(result, f.name) && result[f.name] !== undefined && result[f.name] !== null;
+        if (f.required && !present) {
+            throw protocolError(spec, `result is missing required output field "${f.name}"`, `a "${f.name}" field of type ${f.type}`);
+        }
+        if (present && !typeMatches(f.type, result[f.name])) {
+            throw protocolError(spec, `output field "${f.name}" has the wrong type`, `${f.name}: ${f.type}`);
+        }
+    }
+}
+/** Loose type check over the declared type vocabulary. Only the recognized
+ *  primitive/container categories are enforced; an unrecognized declared type
+ *  falls back to presence-only. */
+function typeMatches(type, v) {
+    const t = type.toLowerCase();
+    if (t === 'string' || t === 'path')
+        return typeof v === 'string';
+    if (t === 'int' || t === 'integer')
+        return typeof v === 'number' && Number.isInteger(v);
+    if (t === 'number' || t === 'float')
+        return typeof v === 'number';
+    if (t === 'bool' || t === 'boolean')
+        return typeof v === 'boolean';
+    if (t === 'array' || t.endsWith('[]'))
+        return Array.isArray(v);
+    if (t === 'object')
+        return isObject(v);
+    return true;
+}
+function protocolError(spec, received, expected) {
+    return new CrtrError('plugin_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, { received, next: NEXT });
+}
+function label(spec) {
+    return `plugin "${spec.plugin.name}" command \`${spec.commandPath.join(' ')}\``;
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/core/command-plugins/compose.d.ts

@@ -0,0 +1,5 @@
+import type { BranchDef } from '../command.js';
+import type { CommandRegistrySnapshot } from './discovery.js';
+/** Map an accepted registry snapshot to real top-level BranchDefs, ready to
+ *  concatenate beside core subtrees in `buildRoot()`. */
+export declare function composeExternalSubtrees(snapshot: CommandRegistrySnapshot): BranchDef[];

package/dist/core/command-plugins/compose.js

@@ -0,0 +1,56 @@
+// Tree composer — adapt validated declarative nodes into ordinary crtr
+// BranchDef/LeafDef values via the SAME defineBranch/defineRoot path core uses,
+// so external contributions get child-owned parent representations and the
+// existing help renderer with no second help engine. External nodes are
+// static-only (no dynamicState, no custom renderer); each leaf's run closure is
+// the external adapter. Composition is deterministic: contributions arrive
+// already sorted by name from discovery.
+import { defineBranch, defineLeaf } from '../command.js';
+import { executeExternalLeaf } from './adapter.js';
+/** Map an accepted registry snapshot to real top-level BranchDefs, ready to
+ *  concatenate beside core subtrees in `buildRoot()`. */
+export function composeExternalSubtrees(snapshot) {
+    return snapshot.contributions.map((c) => buildBranch(c, c.node, [c.node.name]));
+}
+function buildBranch(contribution, node, path) {
+    const rootEntry = node.rootEntry !== undefined
+        ? {
+            concept: node.rootEntry.concept,
+            // Explicit field mapping: declarative description→desc, whenToUse→useWhen.
+            desc: node.rootEntry.description,
+            useWhen: node.rootEntry.whenToUse,
+        }
+        : undefined;
+    return defineBranch({
+        name: node.name,
+        description: node.description,
+        whenToUse: node.whenToUse,
+        ...(node.tier !== undefined ? { tier: node.tier } : {}),
+        ...(rootEntry !== undefined ? { rootEntry } : {}),
+        help: {
+            name: path.join(' '),
+            summary: node.summary,
+            ...(node.model !== undefined ? { model: node.model } : {}),
+        },
+        children: node.children.map((child) => child.kind === 'branch'
+            ? buildBranch(contribution, child, [...path, child.name])
+            : buildLeaf(contribution, child, [...path, child.name])),
+    });
+}
+function buildLeaf(contribution, node, path) {
+    return defineLeaf({
+        name: node.name,
+        description: node.description,
+        whenToUse: node.whenToUse,
+        ...(node.tier !== undefined ? { tier: node.tier } : {}),
+        help: {
+            name: path.join(' '),
+            summary: node.summary,
+            params: node.params,
+            output: node.output,
+            outputKind: 'object',
+            effects: node.effects,
+        },
+        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable: contribution.executable, commandPath: path, output: node.output }, input),
+    });
+}

package/dist/core/command-plugins/discovery.d.ts

@@ -0,0 +1,104 @@
+import type { InstalledPlugin } from '../../types.js';
+import type { InputParam, Field } from '../help.js';
+/** A stable, doctor-renderable validation issue. Never thrown — accumulated
+ *  and surfaced through `pkg plugin show` / `sys doctor`. */
+export interface CommandDiscoveryIssue {
+    /** Stable code the surfaces branch on. */
+    code: CommandIssueCode;
+    /** The offending plugin's name. */
+    plugin: string;
+    /** Dotted path to the offending field/node within the manifest, when known. */
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision';
+/** The validated declarative node schema (static-only — no closures, no
+ *  dynamicState, no renderers). Params/output reuse the existing public help
+ *  vocabulary so composition maps them straight through. */
+export interface DeclRootEntry {
+    concept: string;
+    description: string;
+    whenToUse: string;
+}
+export interface DeclBranch {
+    kind: 'branch';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: 'normal' | 'common' | 'important';
+    /** Required on a top-level branch, forbidden on a nested one. */
+    rootEntry?: DeclRootEntry;
+    summary: string;
+    model?: string;
+    children: DeclNode[];
+}
+export interface DeclLeaf {
+    kind: 'leaf';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: 'normal' | 'common' | 'important';
+    summary: string;
+    params: InputParam[];
+    output: Field[];
+    outputKind: 'object';
+    effects: string[];
+}
+export type DeclNode = DeclBranch | DeclLeaf;
+/** One accepted top-level contribution: a validated branch node plus the
+ *  plugin identity and canonical executable the adapter needs at run time. */
+export interface ValidatedContribution {
+    plugin: InstalledPlugin;
+    /** Absolute, realpath-resolved executable path. */
+    executable: string;
+    /** The validated top-level branch node (always kind 'branch'). */
+    node: DeclBranch;
+}
+/** Per-plugin validation result — the Phase 2 lifecycle entry point. Reports
+ *  accepted contributions and every issue without executing the binary. */
+export interface PluginCommandValidation {
+    plugin: InstalledPlugin;
+    /** Absolute path to the plugin's commands.json (whether or not it loaded). */
+    manifestPath: string;
+    /** Absolute, resolved executable path when it passed path/exec-bit safety. */
+    executable?: string;
+    contributions: ValidatedContribution[];
+    issues: CommandDiscoveryIssue[];
+}
+/** The invocation-local registry snapshot the tree composer consumes. */
+export interface CommandRegistrySnapshot {
+    /** Accepted top-level contributions, deterministically ordered by name. */
+    contributions: ValidatedContribution[];
+    /** Every discovery issue across all effective command plugins. */
+    issues: CommandDiscoveryIssue[];
+}
+/** The effective, deduped set of enabled plugins that declare a command
+ *  manifest, in scope-precedence order. Enumerated with existing machinery
+ *  only: `projectScopeRoots()` (profile-widened, nearest-first) via
+ *  `listInstalledPluginsInRoot('project', root)`, then user scope. Dedup is by
+ *  plugin NAME across ALL copies (highest precedence wins) BEFORE the enabled
+ *  filter — so a disabled higher-precedence copy suppresses lower-precedence
+ *  copies of the same name. */
+export declare function effectiveCommandPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
+/** Validate every effective command plugin and compose an invocation-local
+ *  registry snapshot. `reservedNames` are the core top-level subtree names —
+ *  a contribution claiming one is silently skipped from the tree and recorded
+ *  as a `command_collision` issue (core always wins). A plugin-vs-plugin
+ *  top-level name collision drops all claimants with an issue. Accepted
+ *  contributions are sorted by name for deterministic help/order. */
+export declare function discoverCommandContributions(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): CommandRegistrySnapshot;
+/** Validate every effective command plugin, including the cross-plugin
+ *  top-level name collision pass: a name claimed by more than one plugin is
+ *  dropped from EVERY claimant's contributions and a `command_collision`
+ *  issue is recorded on EACH claimant's validation, so per-plugin surfaces
+ *  (`sys doctor`, `pkg plugin show`) see it too. This is the entry point for
+ *  any surface that reports on mounted commands — the per-plugin
+ *  `validatePluginCommands` cannot see other plugins' claims. */
+export declare function validateEffectiveCommandPlugins(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): PluginCommandValidation[];
+/** Validate one plugin's command manifest without executing its binary.
+ *  `reservedNames` are the core top-level names used for the core-collision
+ *  check; pass an empty set to skip it. Never throws. */
+export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>): PluginCommandValidation;