@north-light/crouter 0.3.258 → 0.3.260

package/dist/core/canvas/browse/model.d.ts

@@ -12,11 +12,11 @@ export declare const SORTS: readonly SortMode[];
 /** Does a node belong to this tab's slice?
  *    All       — every node.
  *    Live      — what you can pick up right now: active | idle, PLUS a resident
- *                agent that stopped without finishing (its broker exited, but
- *                Enter resumes the conversation in place — see `isFinishedWork`).
+ *                agent that stopped without finishing (Enter opens its saved
+ *                conversation; submitted input wakes it — see `isFinishedWork`).
  *                Finished work never appears here.
  *    Dormant   — done | dead | canceled: literally "no engine running". A stopped
- *                resident agent is deliberately on BOTH tabs — it is resumable
+ *                resident agent is deliberately on BOTH tabs — it is openable
  *                (Live) and it is not running (Dormant); both are true and each
  *                tab is the one a different search starts from.
  *    Attention — needs a human: has pending asks OR is parked on a fault.

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

@@ -11,11 +11,11 @@ export const SORTS = ['tree', 'attention', 'relevance', 'recency'];
 /** Does a node belong to this tab's slice?
  *    All       — every node.
  *    Live      — what you can pick up right now: active | idle, PLUS a resident
- *                agent that stopped without finishing (its broker exited, but
- *                Enter resumes the conversation in place — see `isFinishedWork`).
+ *                agent that stopped without finishing (Enter opens its saved
+ *                conversation; submitted input wakes it — see `isFinishedWork`).
  *                Finished work never appears here.
  *    Dormant   — done | dead | canceled: literally "no engine running". A stopped
- *                resident agent is deliberately on BOTH tabs — it is resumable
+ *                resident agent is deliberately on BOTH tabs — it is openable
  *                (Live) and it is not running (Dormant); both are true and each
  *                tab is the one a different search starts from.
  *    Attention — needs a human: has pending asks OR is parked on a fault.

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

@@ -435,8 +435,8 @@ const HELP_ROWS = [
     ['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', '⏎  o', 'resume the node (closes navigator)'],
-    ['', 'O', 'resume, keep browsing (open in background)'],
+    ['Open', '⏎  o', 'open conversation (closes navigator)'],
+    ['', 'O', 'open, keep browsing (background)'],
     ['Act', 'y', 'copy the node id to the clipboard'],
     ['', 'm', 'message the node (no resume)'],
     ['', 'R', 'rename the node'],
@@ -557,7 +557,7 @@ export function renderFrame(state, size, caps = { color: false, color256: false
             ? '⏎ commit  Esc cancel  ⌫ delete'
             : state.readOnly === true
                 ? '↑↓ move  →/← tree  / search  f pin  Tab tabs  ? more  q quit  — read-only remote canvas'
-                : `${hangingHint}↑↓ move  ⏎ resume  O bg  / search  f pin  m msg  x close  R rename  ? more  q quit`;
+                : `${hangingHint}↑↓ move  ⏎ open  O bg  / 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/command-manifests/manifest.d.ts

@@ -1,10 +1,10 @@
-import type { DeclLeaf, TransportKind, DeclBranch, ManifestTimeouts, CommandManifestIssue } from './schema.js';
+import type { DeclLeaf, DeclNode, TransportKind, ManifestTimeouts, CommandManifestIssue } from './schema.js';
 export interface ValidatedCommandManifest {
     schemaVersion: 1;
     baseUrl?: string;
     timeouts?: ManifestTimeouts;
-    /** Top-level branches, each ready to mount at parent []. */
-    roots: DeclBranch<DeclLeaf>[];
+    /** Top-level plugin branches or repository-fragment nodes, ready to mount. */
+    roots: DeclNode<DeclLeaf>[];
     /** Core command path (space-joined, e.g. "cron add") → attributed addendum
      *  text appended beneath that core command's help. Append-only product
      *  guidance — a plugin can never alter core contract text. */
@@ -32,4 +32,6 @@ export declare function validateCommandManifest(raw: unknown, options: {
      *  and ingress report can never disagree. Omitted only on the tolerant
      *  compose path, where mounting ignores addenda entirely. */
     coreCommandPaths?: ReadonlySet<string>;
+    /** A repository fragment attaches roots below an existing extensible branch. */
+    extensionFragment?: boolean;
 }): CommandManifestValidation;

package/dist/core/command-manifests/manifest.js

@@ -33,17 +33,19 @@ export function validateCommandManifest(raw, options) {
     };
     // Top-level structure check
     if (!isRecord(raw)) {
-        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts, helpAddenda? }' : '{ schemaVersion, mounts, helpAddenda? }', 'Provide a valid JSON manifest object.');
+        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.extensionFragment === true ? '{ schemaVersion, transport, mounts }' : options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts, helpAddenda? }' : '{ schemaVersion, mounts, helpAddenda? }', 'Provide a valid JSON manifest object.');
         return { issues };
     }
     // Check for unknown top-level keys
     const topKeys = Object.keys(raw);
-    const allowedTopKeys = options.transport === 'http'
-        ? new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts', 'helpAddenda'])
-        : new Set(['schemaVersion', 'mounts', 'helpAddenda']);
+    const allowedTopKeys = options.extensionFragment === true
+        ? new Set(['schemaVersion', 'transport', 'mounts'])
+        : options.transport === 'http'
+            ? new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts', 'helpAddenda'])
+            : new Set(['schemaVersion', 'mounts', 'helpAddenda']);
     const unknownKeys = topKeys.filter((k) => !allowedTopKeys.has(k));
     if (unknownKeys.length > 0) {
-        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.transport === 'http' ? 'only: schemaVersion, baseUrl, timeouts, mounts, helpAddenda' : 'only: schemaVersion, mounts, helpAddenda', 'Remove the unknown keys.');
+        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.extensionFragment === true ? 'only: schemaVersion, transport, mounts' : options.transport === 'http' ? 'only: schemaVersion, baseUrl, timeouts, mounts, helpAddenda' : 'only: schemaVersion, mounts, helpAddenda', 'Remove the unknown keys.');
         return { issues };
     }
     // Validate schemaVersion
@@ -101,7 +103,7 @@ export function validateCommandManifest(raw, options) {
     // Validate and collect all mounts
     const validatedMounts = [];
     for (let i = 0; i < mounts.length; i++) {
-        const m = validateMount(mounts[i], i, options.transport, issue);
+        const m = validateMount(mounts[i], i, options.transport, issue, options.extensionFragment === true ? { topLevelRootEntry: 'forbidden', allowPassthrough: false, allowExtensible: false } : undefined);
         if (m === null)
             return { issues };
         validatedMounts.push(m);
@@ -179,7 +181,7 @@ function validateHelpAddenda(raw, coreCommandPaths, issue) {
     }
     return out;
 }
-function validateMount(raw, index, transport, issue) {
+function validateMount(raw, index, transport, issue, nodeOptions) {
     const path = `mounts[${index}]`;
     if (!isRecord(raw)) {
         issue('command_manifest_invalid', 'mount must be an object', typeName(raw), '{ parent, node }', 'Fix the mount.', path);
@@ -208,17 +210,10 @@ function validateMount(raw, index, transport, issue) {
     // Validate node
     const nodeRaw = raw['node'];
     const topLevel = parent.length === 0;
-    const node = validateCommandNode(nodeRaw, [`${path}.node`], topLevel, transport, issue);
+    const node = validateCommandNode(nodeRaw, [`${path}.node`], topLevel, transport, issue, nodeOptions);
     if (node === null)
         return null;
-    // Top-level mount must be a branch with rootEntry
-    if (topLevel && node.kind !== 'branch') {
-        issue('command_node_invalid', 'top-level mount node must be a branch', node.kind, 'a branch with a rootEntry', 'Wrap the command in a top-level branch.', `${path}.node.kind`);
-        return null;
-    }
-    // Ensure the node is properly typed (should only be DeclLeaf at this point)
-    const typedNode = node;
-    return { parent, node: typedNode };
+    return { parent, node };
 }
 // Forest materialization (order-independent)
 /**
@@ -236,19 +231,10 @@ function materializeForest(mounts, reservedCoreNames, issue) {
             return null;
         }
     }
-    // Build the forest: all top-level nodes with inline children, then attach nested mounts
-    const roots = topLevel.map((m) => ({
-        kind: 'branch',
-        name: m.node.name,
-        description: m.node.description,
-        whenToUse: m.node.whenToUse,
-        ...(m.node.tier !== undefined ? { tier: m.node.tier } : {}),
-        ...(m.node.rootEntry !== undefined ? { rootEntry: m.node.rootEntry } : {}),
-        summary: m.node.summary,
-        ...(m.node.model !== undefined ? { model: m.node.model } : {}),
-        ...(m.node.passthrough !== undefined ? { passthrough: m.node.passthrough } : {}),
-        children: [...m.node.children],
-    }));
+    // Build the forest: all top-level nodes with inline children, then attach nested mounts.
+    const roots = topLevel.map((m) => m.node.kind === 'branch'
+        ? { ...m.node, children: [...m.node.children] }
+        : { ...m.node });
     // Attach nested mounts
     for (const mount of nested) {
         const resolved = resolveAndAttachMount(roots, mount, issue);
@@ -270,8 +256,7 @@ function materializeForest(mounts, reservedCoreNames, issue) {
         return true;
     };
     for (const root of roots) {
-        const child = root;
-        if (!indexPaths(child, [root.name]))
+        if (!indexPaths(root, [root.name]))
             return null;
     }
     return roots;
@@ -287,6 +272,10 @@ function resolveAndAttachMount(roots, mount, issue) {
         issue('command_parent_invalid', `parent path starts with unknown branch`, first, 'a branch this manifest contributes', 'Fix the parent path or add the parent branch.', mount.parent.join('.'));
         return false;
     }
+    if (root.kind === 'leaf') {
+        issue('command_parent_invalid', 'parent path resolves to a leaf', first, 'a branch', 'Change the parent to point to a branch.', mount.parent.join('.'));
+        return false;
+    }
     let current = root;
     for (const token of rest) {
         const child = current.children.find((c) => c.name === token);

package/dist/core/command-manifests/registry.d.ts

@@ -1,5 +1,6 @@
 import type { LeafDef } from '../command.js';
 import type { DeclLeafBase, DeclBranch, CommandManifestIssue } from './schema.js';
+import type { ExtensionIssueNotice } from '../command-plugins/extensions.js';
 /** Reference to an external contributor (plugin or HTTP-transport plugin). */
 export type CommandContributorRef = {
     name: string;
@@ -27,6 +28,8 @@ export interface CommandContribution {
     /** Root name from the manifest, before collision qualification. */
     manifestName: string;
     adaptLeaf: LeafAdapter;
+    /** Present only on an extensible branch whose nearest repository fragment was rejected. */
+    extensionIssue?: ExtensionIssueNotice;
 }
 /** Per-contributor collision issue. */
 export interface ContributorIssue extends CommandManifestIssue {

package/dist/core/command-manifests/schema.d.ts

@@ -12,6 +12,8 @@ export interface DeclBranch<L = DeclLeafBase> {
     tier?: 'normal' | 'common' | 'important';
     /** Required on a top-level branch, forbidden on a nested one. */
     rootEntry?: DeclRootEntry;
+    /** Allows the nearest repository fragment to contribute children below this top-level branch. */
+    extensible?: true;
     summary: string;
     model?: string;
     /** Exec transport only: forward every argv token after this branch to an
@@ -78,8 +80,16 @@ export interface CommandManifestIssue {
     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' | 'command_help_addendum_invalid' | 'command_rest_invalid';
+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' | 'command_help_addendum_invalid' | 'command_rest_invalid' | 'command_extension_invalid';
 type IssueFn = (code: CommandIssueCode, message: string, received: string, expected: string, next: string, path?: string) => void;
 export type TransportKind = 'exec' | 'http';
-export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn): DeclBranch<DeclLeaf> | DeclLeaf | null;
+export interface CommandNodeValidationOptions {
+    /** Plugin roots need rootEntry; repository-fragment roots attach under an existing branch and forbid it. */
+    topLevelRootEntry?: 'required' | 'forbidden';
+    /** Repository fragments have no passthrough escape hatch. */
+    allowPassthrough?: boolean;
+    /** Only plugin manifests may mark their own top-level branch extensible. */
+    allowExtensible?: boolean;
+}
+export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn, options?: CommandNodeValidationOptions): DeclBranch<DeclLeaf> | DeclLeaf | null;
 export {};

package/dist/core/command-manifests/schema.js

@@ -5,7 +5,7 @@ const TIERS = new Set(['normal', 'common', 'important']);
 const FLAG_TYPES = new Set(['string', 'int', 'bool', 'path', 'enum']);
 const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const BRANCH_KEYS = new Set([
-    'kind', 'name', 'description', 'whenToUse', 'tier', 'rootEntry', 'summary', 'model', 'children',
+    'kind', 'name', 'description', 'whenToUse', 'tier', 'rootEntry', 'extensible', 'summary', 'model', 'children',
 ]);
 /** Only exec transport may declare `passthrough`; HTTP manifests keep
  *  BRANCH_KEYS, so a declared passthrough fails as an unknown key. */
@@ -331,7 +331,7 @@ function checkCommon(raw, path, issue) {
     }
     return true;
 }
-export function validateCommandNode(raw, path, topLevel, transport, issue) {
+export function validateCommandNode(raw, path, topLevel, transport, issue, options = {}) {
     const pathString = path.join('.');
     if (!isRecord(raw)) {
         issue('command_node_invalid', 'node must be an object', typeName(raw), 'a branch or leaf node object', 'Fix the node.', pathString);
@@ -339,9 +339,9 @@ export function validateCommandNode(raw, path, topLevel, transport, issue) {
     }
     const kind = raw['kind'];
     if (kind === 'branch')
-        return validateBranch(raw, pathString, topLevel, transport, issue);
+        return validateBranch(raw, pathString, topLevel, transport, issue, options);
     if (kind === 'leaf') {
-        if (topLevel) {
+        if (topLevel && options.topLevelRootEntry !== 'forbidden') {
             issue('command_node_invalid', 'top-level node must be a branch', 'leaf', 'a branch node with a rootEntry', 'Wrap the command in a top-level branch (noun) with a rootEntry.', `${pathString}.kind`);
             return null;
         }
@@ -350,18 +350,26 @@ export function validateCommandNode(raw, path, topLevel, transport, issue) {
     issue('command_node_invalid', 'node kind must be "branch" or "leaf"', String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${pathString}.kind`);
     return null;
 }
-function validateBranch(raw, path, topLevel, transport, issue) {
-    if (!checkKeys(raw, transport === 'exec' ? EXEC_BRANCH_KEYS : BRANCH_KEYS, path, issue))
+function validateBranch(raw, path, topLevel, transport, issue, options) {
+    const allowsPassthrough = options.allowPassthrough !== false;
+    const allowedKeys = transport === 'exec' && allowsPassthrough ? EXEC_BRANCH_KEYS : BRANCH_KEYS;
+    if (!checkKeys(raw, allowedKeys, path, issue))
         return null;
     if (!checkCommon(raw, path, issue))
         return null;
     const hasRoot = raw['rootEntry'] !== undefined;
-    if (topLevel && !hasRoot) {
+    const rootEntryPolicy = options.topLevelRootEntry ?? 'required';
+    if (topLevel && rootEntryPolicy === 'required' && !hasRoot) {
         issue('command_node_invalid', 'top-level branch requires a rootEntry', '(missing)', 'a rootEntry { concept, description, whenToUse }', 'Add a rootEntry to the top-level branch.', `${path}.rootEntry`);
         return null;
     }
-    if (!topLevel && hasRoot) {
-        issue('command_node_invalid', 'nested branch must not declare a rootEntry', 'rootEntry', 'no rootEntry (only top-level branches carry one)', 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
+    if ((!topLevel || rootEntryPolicy === 'forbidden') && hasRoot) {
+        issue('command_node_invalid', topLevel ? 'repository fragment root must not declare a rootEntry' : 'nested branch must not declare a rootEntry', 'rootEntry', topLevel ? 'no rootEntry (the owning plugin branch already has one)' : 'no rootEntry (only top-level branches carry one)', topLevel ? 'Remove rootEntry from the repository fragment root.' : 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
+        return null;
+    }
+    const hasExtensible = raw['extensible'] !== undefined;
+    if (hasExtensible && (!topLevel || options.allowExtensible === false || raw['extensible'] !== true)) {
+        issue('command_node_invalid', !topLevel ? 'extensible is valid only on a top-level branch mount' : 'extensible must be exactly true on a plugin top-level branch', String(raw['extensible']), !topLevel ? 'no extensible marker on nested branches' : 'extensible: true', !topLevel ? 'Move the marker to the plugin top-level branch or remove it.' : 'Set extensible to true or remove it.', `${path}.extensible`);
         return null;
     }
     let rootEntry;
@@ -386,6 +394,10 @@ function validateBranch(raw, path, topLevel, transport, issue) {
             return null;
         passthrough = validated;
     }
+    if (hasExtensible && passthrough !== undefined) {
+        issue('command_node_invalid', 'an extensible branch cannot declare passthrough', 'extensible and passthrough', 'one branch mode: extensible or passthrough', 'Remove passthrough or remove extensible.', path);
+        return null;
+    }
     const children = raw['children'];
     if (passthrough !== undefined) {
         if (!Array.isArray(children) || children.length !== 0) {
@@ -400,7 +412,7 @@ function validateBranch(raw, path, topLevel, transport, issue) {
     const validated = [];
     const childNames = new Set();
     for (let i = 0; i < children.length; i++) {
-        const child = validateCommandNode(children[i], [...path.split('.'), `children[${i}]`], false, transport, issue);
+        const child = validateCommandNode(children[i], [...path.split('.'), `children[${i}]`], false, transport, issue, options);
         if (child === null)
             return null;
         if (childNames.has(child.name)) {
@@ -413,7 +425,8 @@ function validateBranch(raw, path, topLevel, transport, issue) {
     return {
         kind: 'branch', name: raw['name'], description: raw['description'], whenToUse: raw['whenToUse'],
         ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
-        ...(rootEntry !== undefined ? { rootEntry } : {}), summary: raw['summary'],
+        ...(rootEntry !== undefined ? { rootEntry } : {}),
+        ...(hasExtensible ? { extensible: true } : {}), summary: raw['summary'],
         ...(raw['model'] !== undefined ? { model: raw['model'] } : {}),
         ...(passthrough !== undefined ? { passthrough } : {}), children: validated,
     };

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

@@ -39,7 +39,7 @@ export function composeExternalSubtrees(snapshot) {
 }
 function buildBranch(contribution, node, path) {
     const rootEntry = node.rootEntry === undefined ? undefined : { concept: node.rootEntry.concept, desc: node.rootEntry.description, useWhen: node.rootEntry.whenToUse };
-    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 } : {}) }, ...(node.passthrough !== undefined ? { passthrough: node.passthrough } : {}), children: node.children.map((child) => child.kind === 'branch' ? buildBranch(contribution, child, [...path, child.name]) : buildLeaf(contribution, child, [...path, child.name])) });
+    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 } : {}), ...(path.length === 1 && contribution.extensionIssue !== undefined ? { extensionIssue: contribution.extensionIssue } : {}) }, ...(node.passthrough !== undefined ? { passthrough: node.passthrough } : {}), 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) {
     const adapted = contribution.adaptLeaf(node, path);

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

@@ -34,4 +34,4 @@ export declare function discoverCommandContributions(reservedNames: ReadonlySet<
     contributions: ValidatedContribution[];
     issues: CommandDiscoveryIssue[];
 };
-export declare function buildExternalCommandSnapshot(reservedCoreNames: ReadonlySet<string>): CommandRegistrySnapshot;
+export declare function buildExternalCommandSnapshot(reservedCoreNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): CommandRegistrySnapshot;

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

@@ -6,6 +6,7 @@ import { validateCommandManifest } from '../command-manifests/manifest.js';
 import { qualifiedTopLevelCommandName, resolveCommandRegistry } from '../command-manifests/registry.js';
 import { adaptPluginContributions } from './compose.js';
 import { validateHttpPluginTransport } from './endpoint.js';
+import { applyCommandExtensions } from './extensions.js';
 export function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
     const seen = new Set();
     const result = [];
@@ -130,7 +131,11 @@ export function validatePluginCommands(plugin, reservedNames = new Set(), coreCo
         : transport;
     if (resolvedTransport === undefined)
         return { plugin, manifestPath, transport, contributions: [], issues };
-    return { plugin, manifestPath, transport: resolvedTransport, manifest: validation.manifest, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest, manifestName: node.name })), issues };
+    const roots = validation.manifest.roots;
+    if (!roots.every((node) => node.kind === 'branch')) {
+        throw new Error('plugin manifest validation returned a top-level leaf');
+    }
+    return { plugin, manifestPath, transport: resolvedTransport, manifest: validation.manifest, contributions: roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest, manifestName: node.name })), issues };
 }
 export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
     return effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin));
@@ -164,9 +169,10 @@ export function discoverCommandContributions(reservedNames, startDir = process.c
     const validations = validateEffectiveCommandPlugins(reservedNames, startDir, profileId);
     return { contributions: validations.flatMap((validation) => validation.contributions), issues: validations.flatMap((validation) => validation.issues) };
 }
-export function buildExternalCommandSnapshot(reservedCoreNames) {
-    const validations = discoverPluginCommandCandidates();
+export function buildExternalCommandSnapshot(reservedCoreNames, startDir = process.cwd(), profileId) {
+    const validations = discoverPluginCommandCandidates(startDir, profileId);
     const candidates = adaptPluginContributions(validations.flatMap((validation) => validation.contributions)).contributions;
     const resolved = resolveCommandRegistry(candidates, reservedCoreNames);
-    return { contributions: resolved.contributions, issues: [...validations.flatMap((validation) => validation.issues.map((issue) => contributorIssue(validation.plugin, issue))), ...resolved.issues] };
+    const extensions = applyCommandExtensions(resolved.contributions, startDir);
+    return { contributions: extensions.contributions, issues: [...validations.flatMap((validation) => validation.issues.map((issue) => contributorIssue(validation.plugin, issue))), ...resolved.issues] };
 }

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

@@ -0,0 +1,20 @@
+import type { CommandManifestIssue } from '../command-manifests/schema.js';
+import type { CommandContribution } from '../command-manifests/registry.js';
+export interface ExtensionIssueNotice {
+    fragment: string;
+    message: string;
+}
+export interface CommandExtensionValidation {
+    branch: string;
+    fragmentPath: string;
+    projectRoot: string;
+    issue?: CommandManifestIssue;
+}
+/** Attach the nearest repository-owned fragment to each marked plugin branch.
+ * Discovery reads only; execution remains in the leaf adapter. */
+export declare function applyCommandExtensions(contributions: readonly CommandContribution[], startDir?: string): {
+    contributions: CommandContribution[];
+    validations: CommandExtensionValidation[];
+};
+/** Doctor's only directory scan: fragments with no matching effective marked branch are otherwise inert by design. */
+export declare function orphanCommandExtensionValidations(contributions: readonly CommandContribution[], startDir?: string): CommandExtensionValidation[];

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

@@ -0,0 +1,166 @@
+import { existsSync, realpathSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { projectScopeRoots } from '../scope.js';
+import { validateCommandManifest } from '../command-manifests/manifest.js';
+import { executeExternalLeaf } from './transport/exec-invoke.js';
+import { isRecord } from '../../shared/predicates.js';
+function issue(fragmentPath, message, received, expected, next, nodePath) {
+    return {
+        code: 'command_extension_invalid',
+        message,
+        received,
+        expected,
+        next,
+        path: nodePath === undefined ? fragmentPath : `${fragmentPath}:${nodePath}`,
+    };
+}
+function regenerate(fragmentPath) {
+    return `Fix the repository CLI definition and regenerate ${fragmentPath}.`;
+}
+function safeExecutable(fragmentPath, root, executable) {
+    if (isAbsolute(executable)) {
+        return { issue: issue(fragmentPath, 'fragment transport executable must be project-relative', executable, 'a project-root-relative regular file', 'Fix transport.executable in the repository CLI definition and regenerate the fragment.', 'transport.executable') };
+    }
+    try {
+        const rootReal = realpathSync(root);
+        const resolved = realpathSync(resolve(root, executable));
+        if ((resolved !== rootReal && !resolved.startsWith(rootReal + sep)) || !statSync(resolved).isFile()) {
+            return { issue: issue(fragmentPath, 'fragment transport executable escapes the project root or is not a regular file', executable, 'a project-root-relative regular file', 'Fix transport.executable in the repository CLI definition and regenerate the fragment.', 'transport.executable') };
+        }
+        if ((statSync(resolved).mode & 0o111) === 0) {
+            return { issue: issue(fragmentPath, 'fragment transport executable lacks the POSIX exec bit', executable, 'a file with an executable permission bit', 'chmod +x the repository command executable, then regenerate the fragment.', 'transport.executable') };
+        }
+        return { executable: resolved };
+    }
+    catch {
+        return { issue: issue(fragmentPath, 'fragment transport executable escapes the project root or is not a regular file', executable, 'a project-root-relative regular file', 'Fix transport.executable in the repository CLI definition and regenerate the fragment.', 'transport.executable') };
+    }
+}
+function validateFragment(fragmentPath, projectRoot, branch, ownChildren) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(fragmentPath, 'utf8'));
+    }
+    catch {
+        return { issue: issue(fragmentPath, 'extension fragment is missing, unreadable, or not valid JSON', fragmentPath, 'a readable generated JSON fragment', `Regenerate ${fragmentPath}.`) };
+    }
+    if (!isRecord(raw)) {
+        return { issue: issue(fragmentPath, 'extension fragment must be an object', raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw, '{ schemaVersion, transport, mounts }', `Regenerate ${fragmentPath}.`) };
+    }
+    const unknown = Object.keys(raw).filter((key) => !['schemaVersion', 'transport', 'mounts'].includes(key));
+    if (unknown.length > 0) {
+        return { issue: issue(fragmentPath, 'extension fragment has unknown top-level keys', unknown.join(', '), 'only: schemaVersion, transport, mounts', `Regenerate ${fragmentPath}.`) };
+    }
+    const transport = raw['transport'];
+    if (!isRecord(transport) || Object.keys(transport).some((key) => !['kind', 'executable'].includes(key)) || transport['kind'] !== 'exec' || typeof transport['executable'] !== 'string' || transport['executable'].length === 0) {
+        return { issue: issue(fragmentPath, 'extension fragment transport must be { kind: "exec", executable: "project-relative path" }', JSON.stringify(transport), 'an exec transport with an executable', `Regenerate ${fragmentPath}.`, 'transport') };
+    }
+    const executableResult = safeExecutable(fragmentPath, projectRoot, transport['executable']);
+    if (executableResult.issue !== undefined)
+        return { issue: executableResult.issue };
+    const validation = validateCommandManifest(raw, {
+        transport: 'exec',
+        reservedCoreNames: new Set(),
+        extensionFragment: true,
+    });
+    if (validation.manifest === undefined) {
+        const source = validation.issues[0];
+        return {
+            issue: issue(fragmentPath, source.message, source.received, source.expected, regenerate(fragmentPath), source.path),
+        };
+    }
+    const conflict = validation.manifest.roots.find((root) => ownChildren.includes(root.name));
+    if (conflict !== undefined) {
+        return {
+            issue: issue(fragmentPath, `contributed command "${conflict.name}" conflicts with a child the extensible branch already owns`, conflict.name, 'a name not already owned by the plugin branch', `Rename "${conflict.name}" in the repository CLI tree, then regenerate ${fragmentPath}.`, conflict.name),
+        };
+    }
+    return { fragment: { roots: validation.manifest.roots, executable: executableResult.executable } };
+}
+function nearestFragment(branch, startDir) {
+    for (const scopeRoot of projectScopeRoots(startDir, null)) {
+        const projectRoot = dirname(scopeRoot);
+        const fragmentPath = join(scopeRoot, 'commands', `${branch}.json`);
+        if (existsSync(fragmentPath))
+            return { fragmentPath, projectRoot };
+    }
+    return undefined;
+}
+function markLeaves(node, leaves) {
+    if (node.kind === 'leaf') {
+        leaves.add(node);
+        return;
+    }
+    node.children.forEach((child) => markLeaves(child, leaves));
+}
+/** Attach the nearest repository-owned fragment to each marked plugin branch.
+ * Discovery reads only; execution remains in the leaf adapter. */
+export function applyCommandExtensions(contributions, startDir = process.cwd()) {
+    const validations = [];
+    const attached = contributions.map((contribution) => {
+        if (contribution.node.extensible !== true)
+            return contribution;
+        const branch = contribution.node.name;
+        const located = nearestFragment(branch, startDir);
+        if (located === undefined)
+            return contribution;
+        const result = validateFragment(located.fragmentPath, located.projectRoot, branch, contribution.node.children.map((child) => child.name));
+        if (result.issue !== undefined) {
+            validations.push({ branch, fragmentPath: located.fragmentPath, projectRoot: located.projectRoot, issue: result.issue });
+            return {
+                ...contribution,
+                extensionIssue: { fragment: located.fragmentPath, message: result.issue.message },
+            };
+        }
+        const fragment = result.fragment;
+        validations.push({ branch, fragmentPath: located.fragmentPath, projectRoot: located.projectRoot });
+        const leaves = new WeakSet();
+        fragment.roots.forEach((root) => markLeaves(root, leaves));
+        return {
+            ...contribution,
+            node: { ...contribution.node, children: [...contribution.node.children, ...fragment.roots] },
+            adaptLeaf: (leaf, path) => {
+                if (!leaves.has(leaf))
+                    return contribution.adaptLeaf(leaf, path);
+                const commandPath = [...path];
+                return {
+                    outputKind: 'object',
+                    run: async (input) => executeExternalLeaf({
+                        extension: { branch, root: located.projectRoot },
+                        executable: fragment.executable,
+                        commandPath,
+                        output: leaf.output,
+                    }, input),
+                };
+            },
+        };
+    });
+    return { contributions: attached, validations };
+}
+/** Doctor's only directory scan: fragments with no matching effective marked branch are otherwise inert by design. */
+export function orphanCommandExtensionValidations(contributions, startDir = process.cwd()) {
+    const scopeRoot = projectScopeRoots(startDir, null)[0];
+    if (scopeRoot === undefined)
+        return [];
+    const commandsDir = join(scopeRoot, 'commands');
+    let names;
+    try {
+        names = readdirSync(commandsDir);
+    }
+    catch {
+        return [];
+    }
+    const extensible = new Set(contributions.filter((contribution) => contribution.node.extensible === true).map((contribution) => contribution.node.name));
+    return names.filter((name) => name.endsWith('.json')).flatMap((name) => {
+        const branch = name.slice(0, -'.json'.length);
+        if (extensible.has(branch))
+            return [];
+        const fragmentPath = join(commandsDir, name);
+        return [{
+                branch,
+                fragmentPath,
+                projectRoot: dirname(scopeRoot),
+                issue: issue(fragmentPath, `fragment names branch "${branch}" but no effective plugin branch is extensible`, branch, 'the name of an effective extensible plugin branch', `Mark the plugin branch extensible or rename/remove ${fragmentPath}.`),
+            }];
+    });
+}

package/dist/core/command-plugins/transport/exec-invoke.d.ts

@@ -1,14 +1,27 @@
 import type { InstalledPlugin } from '../../../types.js';
 import type { Field } from '../../help.js';
-export interface ExternalLeafSpec {
+export type ExternalLeafSpec = {
     plugin: InstalledPlugin;
+    extension?: never;
     /** 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[];
-}
+} | {
+    plugin?: never;
+    extension: {
+        branch: string;
+        root: string;
+    };
+    /** 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[];
+};
 /** Validates a result object against declared output field descriptors.
  *  Returns null if valid; otherwise returns a { field, receivedType } error.
  *  Transport-neutral: used by exec and HTTP transport adapters. */

package/dist/core/command-plugins/transport/exec-invoke.js

@@ -52,12 +52,14 @@ export function executeExternalLeaf(spec, input) {
         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,
-            },
+            ...(spec.plugin !== undefined
+                ? { plugin: {
+                        name: spec.plugin.name,
+                        version: spec.plugin.version ?? spec.plugin.manifest.version ?? null,
+                        scope: spec.plugin.scope,
+                        root: spec.plugin.root,
+                    } }
+                : { extension: spec.extension }),
         },
     };
     const res = spawnSync(spec.executable, ['--crtr-command-protocol', '1'], {
@@ -207,5 +209,7 @@ 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(' ')}\``;
+    return spec.plugin !== undefined
+        ? `plugin "${spec.plugin.name}" command \`${spec.commandPath.join(' ')}\``
+        : `extension branch "${spec.extension.branch}" command \`${spec.commandPath.join(' ')}\``;
 }