@north-light/crouter 0.3.259 → 0.3.261

package/dist/builtin-memory/internal/plugins.md

@@ -290,6 +290,16 @@ An exec manifest accepts only `schemaVersion` and `mounts`. Its leaves declare `
 
 Every branch child is a branch (without `rootEntry`) or leaf. A leaf declares `params`, `output` (array of `{ name, type, required, constraint }`), and a non-empty `effects` array. Params use crtr's public vocabulary — one positional max, long-form `flag`s (types `string|int|bool|path|enum`, `choices` for enum), `stdin`, `context-file`; kebab-case names, no aliases. Two client-side affordances ride on a `positional` or `flag`: `encoding: "text"|"base64"` on a `type: "path"` param sends the named local FILE's content instead of the path string, and `defaultFromEnv: "UPPER_SNAKE"` fills an omitted `string`/`path` param from that environment variable on the calling machine, counting as supplied (so it satisfies `required` and is sent) — unlike a static `default`, which is a parse convenience only and never ships. `defaultFromEnv` is rejected alongside `default` or `repeatable`. The declaration mirrors crtr's stable help descriptors, not its internal TypeScript defs — no closures, dynamic state, or renderers.
 
+### Extensible branches and repository fragments
+
+Use `"extensible": true` only on a plugin branch mounted at `parent: []` when repositories should add native children beneath that branch. It is mutually exclusive with `passthrough`: a passthrough branch owns all remaining tokens and cannot have contributed children. The marker does not change the plugin's transport or its own children; those children remain first, and a repository root that reuses one of their names rejects the entire fragment.
+
+A repository CLI framework generates one fragment per opted-in branch at `<project-root>/.crouter/commands/<effective-branch>.json`; the repository developer commits the generated file, never hand-writing it. The effective branch is the composed command name, so a cross-plugin collision uses its origin-qualified identity (for example, `first:demo.json` extends only `first:demo`). On every invocation crtr walks the caller's existing project-root chain nearest first and reads only the first matching fragment; a corrected file is live on the next invocation without installation, caching, or restart.
+
+A fragment accepts only `schemaVersion: 1`, its required `exec` `transport`, and non-empty `mounts`; it shares the `commands.json` node, parameter, output, and effects grammar documented above rather than defining another command language. Its executable is project-root-relative, contained in that root, a regular executable file, and is direct-spawned only for an explicit leaf invocation. Fragment roots attach beneath the extensible branch and may be branches or direct leaves, so `parent: []` never declares `rootEntry`; non-empty parents resolve only within the fragment's own forest, and `passthrough` is forbidden everywhere in a fragment. HTTP transport is not supported for fragments.
+
+A contributed exec leaf receives the same one-request/one-envelope protocol described in [Exec protocol](#exec-protocol), with the full walked command path and `context.extension { branch, root }` instead of `context.plugin`; it runs with the caller's cwd and full environment. It is trusted repository code running with the caller's authority, not sandboxed code. Native help renders contributed commands without provenance; when a present fragment is rejected, only that extensible branch's help shows an `<extension-issue>` pointing to the file, while `crtr sys doctor` reports the full `command_extension_invalid` remediation and also catches fragments for branches that are not extensible. Recovery is to fix or regenerate the committed fragment.
+
 ### Execution and trust boundaries
 
 An exec leaf direct-spawns its executable (no shell) only on explicit invocation — never on install, help, or discovery — with `--crtr-command-protocol 1`, the caller's cwd, and the full environment. It is **trusted local code running with the caller's authority**: crtr does not sandbox it, filter the environment, mint a credential, or interpret its backend authentication. This is an execution trust boundary, not a sandbox.

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

@@ -106,7 +106,7 @@ 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, mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, mounts: string[] (accepted top-level command names), extensibleBranches: string[] (mount names accepting repository fragments), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
             { name: 'hooks', type: 'object', required: false, constraint: 'Present for every hook declaration, including hook-only plugins. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[] ({code, path?, message, received, expected, next}), trust: string}. Static only: no hook executable runs.' },
         ],
         outputKind: 'object',
@@ -146,6 +146,7 @@ export const pluginShow = defineLeaf({
             commands = {
                 manifestPath: v.manifestPath,
                 mounts: v.contributions.map((c) => c.node.name),
+                extensibleBranches: v.contributions.filter((c) => c.node.extensible === true).map((c) => c.node.name),
                 issues: v.issues,
             };
         }

package/dist/commands/sys/doctor.d.ts

@@ -1 +1,36 @@
+import { type Scope } from '../../types.js';
+type CheckStatus = 'pass' | 'fail';
+type CheckScope = Scope | 'canvas';
+/**
+ * Structured fix action for a failing check. Surfaced on each
+ * non-pass result so an agent reading doctor output can apply it directly
+ * when `--fix` is not used (or when --fix did not auto-apply). Every
+ * remediation includes the exact action and payload — no inference required.
+ */
+interface Remediation {
+    kind: 'remove_config_key' | 'rm_path' | 'human_action';
+    description: string;
+    scope?: Scope;
+    configKey?: string;
+    path?: string;
+    command?: string;
+}
+interface CheckResult {
+    scope: CheckScope;
+    name: string;
+    status: CheckStatus;
+    message: string;
+    fixed?: boolean;
+    remediation?: Remediation;
+}
+/**
+ * Validate the command manifest + executable path of every effective command
+ * plugin (the deduped, enabled set that actually composes into the tree).
+ * Purely static — the plugin binary is NEVER executed, and no remediation ever
+ * chmods or rewrites third-party plugin content (every fix is a human_action:
+ * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
+ * are reported, so `--scope` narrows these checks too.
+ */
+export declare function runCommandPluginChecks(scopes: Scope[]): Promise<CheckResult[]>;
 export declare const sysDoctorLeaf: import("../../core/command.js").LeafDef;
+export {};

package/dist/commands/sys/doctor.js

@@ -14,6 +14,9 @@ import { readFault } from '../../core/runtime/fault.js';
 import { detectNerdFont, nerdFontInstallCommand, NERD_FONT_SELECT_HINT } from '../../core/runtime/nerd-font.js';
 import { detectPackageManager } from './setup-core.js';
 import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { adaptPluginContributions } from '../../core/command-plugins/compose.js';
+import { resolveCommandRegistry } from '../../core/command-manifests/registry.js';
+import { applyCommandExtensions, orphanCommandExtensionValidations } from '../../core/command-plugins/extensions.js';
 import { discoverHookRegistry } from '../../core/command-hooks/discovery.js';
 import { resolveBinContributions } from '../../core/runtime/bin-contributions.js';
 import { inspectHumanActions } from '../../core/human-actions.js';
@@ -116,7 +119,7 @@ function faultRemediation(fault, nodeId) {
  * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
  * are reported, so `--scope` narrows these checks too.
  */
-async function runCommandPluginChecks(scopes) {
+export async function runCommandPluginChecks(scopes) {
     const results = [];
     const inScope = new Set(scopes);
     const reserved = new Set(SUBTREE_NAMES);
@@ -124,7 +127,8 @@ async function runCommandPluginChecks(scopes) {
     // collisions surface here. A collision no longer costs anyone their command:
     // each claimant mounts under an origin-qualified name, so it is reported as a
     // healthy mount rather than a failure demanding the user remove a plugin.
-    for (const v of validateEffectiveCommandPlugins(reserved, undefined, undefined, await coreCommandPaths())) {
+    const validations = validateEffectiveCommandPlugins(reserved, undefined, undefined, await coreCommandPaths());
+    for (const v of validations) {
         const plugin = v.plugin;
         if (!inScope.has(plugin.scope))
             continue;
@@ -143,6 +147,22 @@ async function runCommandPluginChecks(scopes) {
             results.push(failCheck(plugin.scope, `plugin:${plugin.name}:commands[${i}]`, `${issue.code}${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, remediation));
         });
     }
+    if (inScope.has('project')) {
+        const registry = resolveCommandRegistry(adaptPluginContributions(validations.flatMap((validation) => validation.contributions)).contributions, reserved);
+        const extensions = applyCommandExtensions(registry.contributions);
+        const allExtensionChecks = [...extensions.validations, ...orphanCommandExtensionValidations(registry.contributions)];
+        for (const extension of allExtensionChecks) {
+            if (extension.issue === undefined) {
+                results.push(pass('project', `extension:${extension.branch}`, `repository fragment valid: ${extension.fragmentPath}`));
+                continue;
+            }
+            const issue = extension.issue;
+            results.push(failCheck('project', `extension:${extension.branch}`, `${issue.code} at ${issue.path ?? extension.fragmentPath}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, {
+                kind: 'human_action',
+                description: issue.next,
+            }));
+        }
+    }
     return results;
 }
 /** Statically inspect the complete effective hook registry. This shares the

package/dist/core/__tests__/integration/command-plugins.test.js

@@ -29,7 +29,7 @@ import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverCommandContributions, effectiveCommandPlugins, validatePluginCommands, } from '../../command-plugins/discovery.js';
+import { discoverCommandContributions, effectiveCommandPlugins, validatePluginCommands, buildExternalCommandSnapshot, } from '../../command-plugins/discovery.js';
 import { composeExternalSubtrees, adaptPluginContributions } from '../../command-plugins/compose.js';
 import { collectHelpAddenda } from '../../command-plugins/help-addenda.js';
 import { resolveCommandRegistry } from '../../command-manifests/registry.js';
@@ -38,9 +38,11 @@ import { renderRoot, renderBranch, renderLeafArgv } from '../../help.js';
 import { renderResult } from '../../render.js';
 import { CrtrError } from '../../errors.js';
 import { resetScopeCache } from '../../scope.js';
+import { createProfile } from '../../profiles/manifest.js';
 import { listInstalledPluginsInRoot } from '../../resolver.js';
 import { pluginShow } from '../../../commands/pkg/plugin-inspect.js';
-import { pluginDisable, pluginEnable, pluginInstall } from '../../../commands/pkg/plugin-manage.js';
+import { pluginDisable, pluginEnable, pluginInstall, pluginUpdate } from '../../../commands/pkg/plugin-manage.js';
+import { runCommandPluginChecks } from '../../../commands/sys/doctor.js';
 // The set of reserved core names discovery must fail closed against. We don't
 // import the real SUBTREE_NAMES (build-root.ts pulls the whole tree); a small
 // explicit set is enough for the collision contract and keeps the test cheap.
@@ -112,6 +114,45 @@ function commandsJson(topName = 'app') {
         ],
     };
 }
+function extensibleDemoCommandsJson(extensible = true) {
+    return {
+        schemaVersion: 1,
+        mounts: [{
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: 'demo',
+                    description: 'fixture extensible branch',
+                    whenToUse: 'testing repository command contributions',
+                    ...(extensible ? { extensible: true } : {}),
+                    rootEntry: { concept: 'fixture command contributions', description: 'fixture extensible branch', whenToUse: 'testing repository command contributions' },
+                    summary: 'fixture extensible branch',
+                    children: [{ kind: 'branch', name: 'built-in', description: 'plugin-owned branch', whenToUse: 'using the plugin-owned command', summary: 'plugin-owned branch', children: [] }],
+                },
+            }],
+    };
+}
+function extensionFragment(rootName = 'repo-branch') {
+    return {
+        schemaVersion: 1,
+        transport: { kind: 'exec', executable: 'scripts/extension.js' },
+        mounts: [
+            { parent: [], node: { kind: 'branch', name: rootName, description: 'repository branch', whenToUse: 'using repository-defined commands', summary: 'repository branch', children: [] } },
+            { parent: [rootName], node: { kind: 'leaf', name: 'run', description: 'run repository operation', whenToUse: 'testing extension execution', summary: 'run repository operation', params: [{ kind: 'flag', name: 'thing', type: 'string', required: true, constraint: 'fixture input' }], output: [{ name: 'value', type: 'string', required: true, constraint: 'echoed fixture input' }], outputKind: 'object', effects: ['None. Read-only.'] } },
+        ],
+    };
+}
+const EXTENSION_EXEC = `#!/usr/bin/env node
+const fs = require('fs');
+let data = '';
+process.stdin.on('data', (chunk) => data += chunk);
+process.stdin.on('end', () => {
+  const request = JSON.parse(data);
+  if (process.env.EXTENSION_REQUEST_LOG) fs.writeFileSync(process.env.EXTENSION_REQUEST_LOG, JSON.stringify(request));
+  if (process.env.EXTENSION_SENTINEL) fs.writeFileSync(process.env.EXTENSION_SENTINEL, 'executed');
+  process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { value: request.input.thing } }));
+});
+`;
 function passthroughCommandsJson() {
     return {
         schemaVersion: 1,
@@ -210,6 +251,26 @@ after(() => {
     }
     resetScopeCache();
 });
+function installExtensionFixture(manifest = extensionFragment()) {
+    installPlugin(userRoot, 'extension-fixture', { manifest: extensibleDemoCommandsJson() });
+    const commandsDir = join(projectRoot, 'commands');
+    const scriptsDir = join(projectDir, 'scripts');
+    mkdirSync(commandsDir, { recursive: true });
+    mkdirSync(scriptsDir, { recursive: true });
+    const fragmentPath = join(commandsDir, 'demo.json');
+    const executable = join(scriptsDir, 'extension.js');
+    writeFileSync(fragmentPath, JSON.stringify(manifest));
+    writeFileSync(executable, EXTENSION_EXEC);
+    chmodSync(executable, 0o755);
+    return { fragmentPath, executable };
+}
+function extensionBranch(startDir = projectDir, name = 'demo') {
+    resetScopeCache();
+    const snapshot = buildExternalCommandSnapshot(RESERVED, startDir);
+    const branch = composeExternalSubtrees(snapshot).find((node) => node.name === name);
+    assert.ok(branch, `expected the extensible ${name} branch`);
+    return branch;
+}
 function leafOf(branch, name) {
     const c = branch.children.find((x) => x.name === name);
     assert.ok(c !== undefined && c.kind === 'leaf', `expected leaf ${name}`);
@@ -384,6 +445,260 @@ describe('end-to-end CLI invocation', () => {
         assert.equal(obj.status, 'running');
     });
 });
+// Extensible plugin command branches — repository fragments attach to a marked
+// top-level branch as one native forest and stay entirely inside the existing
+// parser/help/exec contract.
+describe('extensible plugin command branches', () => {
+    test('merges native help, executes with extension context, and mirrors JSON', async () => {
+        const { fragmentPath } = installExtensionFixture();
+        const branch = extensionBranch();
+        const help = renderBranch(branch.help);
+        assert.match(help, /<command name="demo"/);
+        assert.match(help, /<subcommand name="built-in"/);
+        assert.match(help, /<subcommand name="repo-branch"[^>]*subcommands="1"/);
+        assert.ok(help.indexOf('name="built-in"') < help.indexOf('name="repo-branch"'));
+        assert.equal((help.match(/<command name=/g) ?? []).length, 1);
+        const repoBranch = branch.children.find((child) => child.name === 'repo-branch');
+        assert.ok(repoBranch !== undefined && repoBranch.kind === 'branch');
+        const leaf = leafOf(repoBranch, 'run');
+        const leafHelp = renderLeafArgv(leaf.help);
+        assert.match(leafHelp, /^demo repo-branch run: run repository operation\./);
+        assert.match(leafHelp, /Input/);
+        assert.match(leafHelp, /Output \(fields carried in the rendered result\)/);
+        assert.match(leafHelp, /Effects/);
+        const requestLog = join(projectDir, 'extension-request.json');
+        process.env['EXTENSION_REQUEST_LOG'] = requestLog;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            assert.deepEqual(await leaf.run({ thing: 'x' }), { value: 'x' });
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_REQUEST_LOG'];
+        }
+        const request = JSON.parse(readFileSync(requestLog, 'utf8'));
+        assert.deepEqual(request.command, ['demo', 'repo-branch', 'run']);
+        assert.deepEqual(request.input, { thing: 'x' });
+        assert.deepEqual(request.context.extension, { branch: 'demo', root: projectDir });
+        assert.equal(request.context.plugin, undefined);
+        const root = defineRoot({ tagline: 'test', globals: [], subtrees: [branch] });
+        assert.match(renderRoot(root.help), /\[\+2 subcommands — `crtr demo -h`\]/);
+        assert.equal(existsSync(join(projectDir, 'EXECUTED')), false);
+        assert.ok(existsSync(fragmentPath));
+    });
+    test('uses a collision-qualified branch name for fragment discovery, doctor, and exec context', async () => {
+        installPlugin(userRoot, 'first', { manifest: extensibleDemoCommandsJson() });
+        installPlugin(userRoot, 'second', { manifest: extensibleDemoCommandsJson() });
+        const commandsDir = join(projectRoot, 'commands');
+        const scriptsDir = join(projectDir, 'scripts');
+        mkdirSync(commandsDir, { recursive: true });
+        mkdirSync(scriptsDir, { recursive: true });
+        writeFileSync(join(commandsDir, 'first:demo.json'), JSON.stringify(extensionFragment()));
+        writeFileSync(join(scriptsDir, 'extension.js'), EXTENSION_EXEC);
+        chmodSync(join(scriptsDir, 'extension.js'), 0o755);
+        const first = extensionBranch(projectDir, 'first:demo');
+        const second = extensionBranch(projectDir, 'second:demo');
+        assert.ok(first.children.some((child) => child.name === 'repo-branch'));
+        assert.ok(!second.children.some((child) => child.name === 'repo-branch'));
+        const repoBranch = first.children.find((child) => child.name === 'repo-branch');
+        assert.ok(repoBranch !== undefined && repoBranch.kind === 'branch');
+        const requestLog = join(projectDir, 'collision-extension-request.json');
+        process.env['EXTENSION_REQUEST_LOG'] = requestLog;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            assert.deepEqual(await leafOf(repoBranch, 'run').run({ thing: 'x' }), { value: 'x' });
+            const checks = await runCommandPluginChecks(['project']);
+            const extension = checks.find((check) => check.name === 'extension:first:demo');
+            assert.ok(extension, JSON.stringify(checks));
+            assert.equal(extension.status, 'pass');
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_REQUEST_LOG'];
+        }
+        const request = JSON.parse(readFileSync(requestLog, 'utf8'));
+        assert.deepEqual(request.command, ['first:demo', 'repo-branch', 'run']);
+        assert.deepEqual(request.context.extension, { branch: 'first:demo', root: projectDir });
+        assert.equal(request.context.plugin, undefined);
+    });
+    test('runs through the real CLI with native help and --json output', { timeout: 40000 }, () => {
+        installExtensionFixture();
+        const cli = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'dist', 'cli.js');
+        const run = (args) => execFileSync(process.execPath, [cli, ...args], {
+            cwd: projectDir,
+            env: { ...process.env, HOME: home, CRTR_FRONT_DOOR: '' },
+            encoding: 'utf8',
+        });
+        const branchHelp = run(['demo', '-h']);
+        assert.match(branchHelp, /<command name="demo"/);
+        assert.match(branchHelp, /<subcommand name="built-in"/);
+        assert.match(branchHelp, /<subcommand name="repo-branch"/);
+        assert.deepEqual(JSON.parse(run(['demo', 'repo-branch', 'run', '--thing', 'x', '--json'])), { value: 'x' });
+    });
+    test('discovers per invocation, scopes by cwd, and nearest root wins', () => {
+        const { fragmentPath } = installExtensionFixture();
+        assert.ok(renderBranch(extensionBranch().help).includes('repo-branch'));
+        writeFileSync(fragmentPath, JSON.stringify(extensionFragment('changed')));
+        assert.ok(renderBranch(extensionBranch().help).includes('name="changed"'));
+        rmSync(fragmentPath);
+        assert.ok(!renderBranch(extensionBranch().help).includes('repo-branch'));
+        writeFileSync(fragmentPath, JSON.stringify(extensionFragment('outer')));
+        const inner = join(projectDir, 'nested');
+        const innerScope = join(inner, '.crouter', 'commands');
+        mkdirSync(innerScope, { recursive: true });
+        mkdirSync(join(inner, 'scripts'), { recursive: true });
+        writeFileSync(join(inner, 'scripts', 'extension.js'), EXTENSION_EXEC);
+        chmodSync(join(inner, 'scripts', 'extension.js'), 0o755);
+        writeFileSync(join(innerScope, 'demo.json'), JSON.stringify(extensionFragment('inner')));
+        assert.ok(renderBranch(extensionBranch(inner).help).includes('name="inner"'));
+        assert.ok(!renderBranch(extensionBranch(inner).help).includes('name="outer"'));
+        assert.ok(!renderBranch(extensionBranch(emptyStart).help).includes('name="outer"'));
+    });
+    test('does not discover fragments from selected-profile projects outside the cwd chain', () => {
+        installPlugin(userRoot, 'extension-fixture', { manifest: extensibleDemoCommandsJson() });
+        const profileProject = mintDir('crtr-cmdplugin-profile-project-');
+        const fragmentDir = join(profileProject, '.crouter', 'commands');
+        const scriptDir = join(profileProject, 'scripts');
+        mkdirSync(fragmentDir, { recursive: true });
+        mkdirSync(scriptDir, { recursive: true });
+        writeFileSync(join(fragmentDir, 'demo.json'), JSON.stringify(extensionFragment()));
+        writeFileSync(join(scriptDir, 'extension.js'), EXTENSION_EXEC);
+        chmodSync(join(scriptDir, 'extension.js'), 0o755);
+        process.env['CRTR_PROFILE_ID'] = createProfile('extension-fragment-scope', [{ path: profileProject, memory: 'content' }]).profileId;
+        resetScopeCache();
+        assert.ok(!renderBranch(extensionBranch(emptyStart).help).includes('repo-branch'));
+    });
+    test('rejects absolute executable paths and identifies the offending fragment node', async () => {
+        const { fragmentPath, executable } = installExtensionFixture();
+        const fragment = extensionFragment();
+        fragment.transport.executable = executable;
+        writeFileSync(fragmentPath, JSON.stringify(fragment));
+        const help = renderBranch(extensionBranch().help);
+        assert.match(help, /<extension-issue/);
+        assert.ok(!help.includes('repo-branch'));
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const checks = await runCommandPluginChecks(['project']);
+            const check = checks.find((candidate) => candidate.name === 'extension:demo');
+            assert.ok(check, JSON.stringify(checks));
+            assert.equal(check.status, 'fail');
+            assert.match(check.message, new RegExp(`${fragmentPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:transport\\.executable`));
+        }
+        finally {
+            process.chdir(priorCwd);
+        }
+    });
+    test('rejects the complete fragment with scoped help notice and doctor remediation', async () => {
+        const { fragmentPath } = installExtensionFixture();
+        const bad = extensionFragment();
+        bad['unknown'] = true;
+        writeFileSync(fragmentPath, JSON.stringify(bad));
+        const help = renderBranch(extensionBranch().help);
+        assert.match(help, /name="built-in"/);
+        assert.ok(!help.includes('repo-branch'));
+        assert.match(help, new RegExp(`<extension-issue fragment="${fragmentPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"`));
+        assert.match(help, /unknown top-level keys/);
+        const sentinel = join(projectDir, 'extension-executed');
+        process.env['EXTENSION_SENTINEL'] = sentinel;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const checks = await runCommandPluginChecks(['project']);
+            const check = checks.find((candidate) => candidate.name === 'extension:demo');
+            assert.ok(check, JSON.stringify(checks));
+            assert.equal(check.status, 'fail');
+            assert.match(check.message, /command_extension_invalid/);
+            assert.match(check.message, new RegExp(fragmentPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+            assert.match(check.remediation.description, /regenerate/i);
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_SENTINEL'];
+        }
+        assert.equal(existsSync(sentinel), false);
+    });
+    test('requires the marker, rejects passthrough/rootEntry/conflicts, and leaves unmarked passthrough inert', async () => {
+        const { fragmentPath } = installExtensionFixture();
+        writeFileSync(join(userRoot, 'plugins', 'extension-fixture', 'commands.json'), JSON.stringify(extensibleDemoCommandsJson(false)));
+        assert.ok(!renderBranch(extensionBranch().help).includes('repo-branch'));
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const checks = await runCommandPluginChecks(['project']);
+            const orphan = checks.find((candidate) => candidate.name === 'extension:demo');
+            assert.ok(orphan, JSON.stringify(checks));
+            assert.equal(orphan.status, 'fail');
+            assert.match(orphan.message, /no effective plugin branch is extensible/);
+        }
+        finally {
+            process.chdir(priorCwd);
+        }
+        writeFileSync(join(userRoot, 'plugins', 'extension-fixture', 'commands.json'), JSON.stringify(extensibleDemoCommandsJson()));
+        const variants = [
+            ['passthrough', (fragment) => { fragment['mounts'][0]['node']['passthrough'] = { bin: 'x', installHint: 'x' }; }],
+            ['rootEntry', (fragment) => { fragment['mounts'][0]['node']['rootEntry'] = { concept: 'x', description: 'x', whenToUse: 'x' }; }],
+        ];
+        for (const [name, mutate] of variants) {
+            const fragment = extensionFragment();
+            mutate(fragment);
+            writeFileSync(fragmentPath, JSON.stringify(fragment));
+            const help = renderBranch(extensionBranch().help);
+            assert.match(help, /<extension-issue/);
+            assert.ok(!help.includes('repo-branch'), name);
+        }
+        writeFileSync(fragmentPath, JSON.stringify(extensionFragment('built-in')));
+        const conflictHelp = renderBranch(extensionBranch().help);
+        assert.match(conflictHelp, /<extension-issue/);
+        assert.match(conflictHelp, /conflicts with a child/);
+        installPlugin(userRoot, 'passthrough-fixture', { manifest: passthroughCommandsJson() });
+        writeFileSync(join(projectRoot, 'commands', 'capture.json'), JSON.stringify(extensionFragment()));
+        resetScopeCache();
+        const snapshot = buildExternalCommandSnapshot(RESERVED, projectDir);
+        const capture = composeExternalSubtrees(snapshot).find((branch) => branch.name === 'capture');
+        assert.ok(capture?.passthrough);
+        assert.equal(capture.children.length, 0);
+    });
+    test('install and update validate the marker but never inspect repository fragments', async () => {
+        const source = join(mintDir('crtr-extensible-source-'), 'fixture');
+        mkdirSync(join(source, '.crouter-plugin'), { recursive: true });
+        mkdirSync(join(source, 'bin'), { recursive: true });
+        const manifest = extensibleDemoCommandsJson();
+        manifest.mounts[0].node['name'] = 'install-demo';
+        const rootEntry = manifest.mounts[0].node['rootEntry'];
+        rootEntry['concept'] = 'install fixture';
+        writeFileSync(join(source, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: 'install-extension-fixture', version: '0.1.0', description: 'fixture', commands: 'commands.json', transport: { kind: 'exec', executable: 'bin/cmd.js' } }));
+        writeFileSync(join(source, 'commands.json'), JSON.stringify(manifest));
+        writeFileSync(join(source, 'bin', 'cmd.js'), EXTENSION_EXEC);
+        chmodSync(join(source, 'bin', 'cmd.js'), 0o755);
+        mkdirSync(join(projectRoot, 'commands'), { recursive: true });
+        writeFileSync(join(projectRoot, 'commands', 'install-demo.json'), JSON.stringify({ unknown: true }));
+        await pluginInstall.run({ installRef: source, scope: 'user' });
+        (manifest.mounts[0].node['children'][0]['extensible'] = true);
+        writeFileSync(join(source, 'commands.json'), JSON.stringify(manifest));
+        await assert.rejects(pluginUpdate.run({ name: 'install-extension-fixture' }), /extensible is valid only on a top-level branch mount/);
+    });
+    test('plugin inspection identifies extensible branches without executing the fragment executable', async () => {
+        const { executable } = installExtensionFixture();
+        const sentinel = join(projectDir, 'inspect-executed');
+        process.env['EXTENSION_SENTINEL'] = sentinel;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const shown = await pluginShow.run({ name: 'extension-fixture' });
+            const commands = shown['commands'];
+            assert.deepEqual(commands.extensibleBranches, ['demo']);
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_SENTINEL'];
+        }
+        assert.equal(existsSync(sentinel), false);
+        assert.ok(existsSync(executable));
+    });
+});
 // 5. Lifecycle without restart (per-invocation discovery)
 describe('lifecycle without restart', () => {
     test('install → appears; disable → gone; edit → visible; remove → gone', () => {

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(' ')}\``;
 }

package/dist/core/help.d.ts

@@ -198,6 +198,11 @@ export interface BranchHelp {
     /** Parent-level listing assembled by defineBranch from the actual child defs.
      *  renderBranch reads this; never author it by hand. */
     listing?: ListingChild[];
+    /** A rejected repository fragment is visible only on its owning extensible branch. */
+    extensionIssue?: {
+        fragment: string;
+        message: string;
+    };
 }
 /** Viewer-only hint about how a leaf's result should preview in the attach
  *  viewer's chat — never part of `-h` output and never reaches agent-facing

package/dist/core/help.js

@@ -161,6 +161,9 @@ export function renderBranch(h) {
             lines.push('');
         lines.push(`<subcommand name="${c.name}" description="${attr(c.description)}" whenToUse="${attr(c.whenToUse)}"${subs}/>`);
     }
+    if (h.extensionIssue !== undefined) {
+        lines.push(`<extension-issue fragment="${attr(h.extensionIssue.fragment)}">This repository's contributed commands were rejected: ${h.extensionIssue.message}. Run \`crtr sys doctor\` for the full report.</extension-issue>`);
+    }
     lines.push('</command>');
     return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.259",
+  "version": "0.3.261",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.259",
+  "version": "0.3.261",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.259",
+      "version": "0.3.261",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {