@north-light/crouter 0.3.258 → 0.3.260

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/surface/node/cycle.js

@@ -55,7 +55,7 @@ export const surfaceNodeCycleLeaf = defineLeaf({
             { name: 'from', type: 'string', required: false, constraint: 'The node you cycled away from.' },
         ],
         outputKind: 'object',
-        effects: ['Brings the neighbor\'s viewer forefront beside the caller (like `surface node focus`); the viewer you were watching drops to the background.', 'Relaunches the neighbor\'s broker first if it was dormant.'],
+        effects: ['Brings the neighbor\'s viewer forefront beside the caller (like `surface node focus`); the viewer you were watching drops to the background.', 'Opens a parked resident from its saved snapshot without waking it; submitted input wakes it through the normal message path.'],
     },
     run: async (input) => {
         const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane ?? undefined;
@@ -73,7 +73,7 @@ export const surfaceNodeCycleLeaf = defineLeaf({
         if (target === null)
             return { focused: false, from: fromId };
         // Placement brings the neighbor's viewer forefront beside the caller; the
-        // server (ensureAttach, inside focusViewer) relaunches its broker if dormant.
+        // server keeps an exact parked resident offline until submitted input.
         const res = await focusViewer(targetId, { cwd: target.cwd, name: target.name, pane });
         return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
     },

package/dist/commands/surface/node/focus.js

@@ -6,11 +6,11 @@ import { cliClient, rethrowAsCliError } from '../../api-client.js';
 import { currentTmux, displayPopup, focusViewer, shellQuote } from './placement.js';
 export const surfaceNodeFocusLeaf = defineLeaf({
     name: 'focus',
-    description: 'bring a node into view without accidentally reviving finished work',
-    whenToUse: 'you want to bring a specific node into view — a live node, or a resident agent that merely stopped, opens (resuming its saved conversation in place) beside your current pane; FINISHED work — a terminal worker, or any node that pushed a final report — opens its saved transcript instead of being put back to work. Use `node lifecycle revive` to deliberately relaunch finished work anyway. Use `surface node cycle` to walk neighbors, and `node message send` to steer without leaving where you are',
+    description: 'bring a node into view without waking parked or finished work',
+    whenToUse: 'you want to bring a specific node into view — a live node opens beside your pane, while a parked resident opens its saved conversation without waking until input is submitted. FINISHED work — a terminal worker, or any node that pushed a final report — opens its saved transcript instead of being put back to work. Use `node lifecycle revive` to deliberately relaunch finished work anyway. Use `surface node cycle` to walk neighbors, and `node message send` to steer without leaving where you are',
     help: {
         name: 'surface node focus',
-        summary: 'bring a node into view — attach to a live broker, resume a resident agent that stopped, or open a saved transcript for finished work without reviving it',
+        summary: 'bring a node into view — attach live, open a parked resident without waking it, or inspect finished work as a saved transcript',
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
             { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Always open a NEW viewer SIDE-BY-SIDE with your current pane instead of moving/reusing the node\'s existing viewer. Two agents on screen at once (F4).' },
@@ -20,11 +20,11 @@ export const surfaceNodeFocusLeaf = defineLeaf({
         output: [
             { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node\'s viewer was brought into view.' },
             { name: 'session', type: 'string', required: false, constraint: 'The tmux session the viewer lives in.' },
-            { name: 'revived', type: 'boolean', required: true, constraint: 'True when focusing had to relaunch the node\'s broker (a live node whose engine was gone, or a stopped resident agent resumed in place); false when its viewer was already attached, and false for a saved-transcript inspection.' },
+            { name: 'revived', type: 'boolean', required: true, constraint: 'True when focusing had to recover a non-parked node\'s broker; false for an already attached viewer, an offline parked resident, or saved-transcript inspection.' },
             { name: 'in_place', type: 'boolean', required: true, constraint: 'True when an existing viewer was navigated to (no new pane); false when a fresh viewer pane was opened or moved beside you.' },
         ],
         outputKind: 'object',
-        effects: ['For active/idle nodes: opens/moves the one surface-attach viewer beside the caller, or navigates to its existing viewer.', 'For a resident node that stopped without finalizing: resumes its saved conversation in place (status returns to active) and opens its viewer — the same path as a live node.', 'For finished work (a terminal node, or any node with a final report): opens a read-only saved transcript popup. It does not launch a broker or change node status.', 'With --new-pane/--in-place on a live node: controls whether the viewer splits beside or replaces the caller pane.'],
+        effects: ['For active/idle nodes: opens/moves the one surface-attach viewer beside the caller, or navigates to its existing viewer.', 'For an unfinalized parked resident: opens the normal conversation viewer from its saved snapshot without launching a broker or changing lifecycle; submitting input sends the durable human message that wakes it.', 'For finished work (a terminal node, or any node with a final report): opens a read-only saved transcript popup. It does not launch a broker or change node status.', 'With --new-pane/--in-place on a conversation viewer: controls whether the viewer splits beside or replaces the caller pane.'],
     },
     run: async (input) => {
         const id = input['node'];
@@ -59,16 +59,16 @@ export const surfaceNodeFocusLeaf = defineLeaf({
         // any node that pushed a final report) is archive: show its persisted
         // transcript, because reviving it would set completed work back in motion, and
         // `node lifecycle revive` remains the explicit way to do that on purpose.
-        // A RESIDENT node with no final report never finished — its `done` is just a
-        // clean broker exit — so it falls through to the live path below, where
-        // ensureAttach's true resume replays the conversation exactly as it stood.
+        // A RESIDENT node with no final report never finished — its parked `done`
+        // falls through to the conversation path, where focus can seat its saved
+        // snapshot without launching an engine.
         if (!isLiveStatus(node.status) && isFinishedWork({ lifecycle: node.lifecycle, finalized: node.final_report != null })) {
             const focused = displayPopup(pane, node.cwd, `crtr node inspect transcript ${shellQuote(id)}`);
             return { focused, session: null, revived: false, in_place: false };
         }
-        // Local viewer tail: open/move the broker-backed viewer beside the caller.
-        // The server (ensureAttach) owns the revive + view.sock wait; pure tmux ops
-        // own the pane placement.
+        // Local viewer tail: open/move the normal conversation viewer beside the
+        // caller. The server owns the serialized live-vs-parked decision; pure tmux
+        // operations own pane placement.
         const res = await focusViewer(id, {
             cwd: node.cwd,
             name: node.name,

package/dist/commands/surface/node/placement.js

@@ -7,6 +7,11 @@ export function viewerEnv() {
     const crtrHome = envHomeOverride();
     return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
 }
+/** Internal startup policy for viewers opened by focus/navigation. Direct
+ * `surface attach` has no marker and keeps its activating default. */
+function focusViewerEnv() {
+    return { ...viewerEnv(), CRTR_ATTACH_WAKE_PARKED: '0' };
+}
 /** The live viewer pane for `nodeId` (the pane a surface-attach viewer tagged
  *  `@crtr_node`), or undefined. Pure tag scan over live panes. */
 export function viewerPaneOf(nodeId) {
@@ -22,7 +27,7 @@ export function viewerPaneOf(nodeId) {
 /** Open a fresh surface-attach viewer SPLIT beside `callerPane` and rebalance
  *  its window to even side-by-side widths. Pure tmux. */
 function openBesideCaller(callerPane, nodeId, cwd, callerSession, revived) {
-    const opened = splitWindow(callerPane, { cwd, env: viewerEnv(), command: `crtr surface attach to ${nodeId}` });
+    const opened = splitWindow(callerPane, { cwd, env: focusViewerEnv(), command: `crtr surface attach to ${nodeId}` });
     if (opened === null)
         return { focused: false, session: null, inPlace: false, revived };
     const loc = paneLocation(opened);
@@ -40,8 +45,12 @@ export async function focusViewer(nodeId, opts) {
     if (callerPane === undefined || callerPane === '') {
         return { focused: false, session: null, inPlace: false, revived: false };
     }
-    // (a) Server ensures the broker engine is alive + its view.sock accepts.
-    const attach = await cliClient().ensureAttach(nodeId).catch(rethrowAsCliError);
+    // (a) Server ensures a live broker is attachable, but leaves an exact parked
+    // resident untouched. This policy is unconditional so an active→parked race
+    // is decided at the daemon's synchronous fleet/launch boundary.
+    const attach = await cliClient()
+        .ensureAttach(nodeId, { resume: true, revive: true, wakeParked: false })
+        .catch(rethrowAsCliError);
     const revived = attach.revived;
     const callerSession = paneLocation(callerPane)?.session ?? null;
     // (b0) --in-place → the caller pane BECOMES this node's viewer, replacing what
@@ -57,8 +66,8 @@ export async function focusViewer(nodeId, opts) {
         catch { /* best-effort */ }
         const window = windowOfPane(callerPane);
         const env = priorNodeId !== undefined && priorNodeId !== ''
-            ? { ...viewerEnv(), CRTR_ATTACH_ROSTER: priorNodeId }
-            : viewerEnv();
+            ? { ...focusViewerEnv(), CRTR_ATTACH_ROSTER: priorNodeId }
+            : focusViewerEnv();
         const ok = respawnPaneSync({ pane: callerPane, cwd: opts.cwd, env, command: `crtr surface attach to ${nodeId}` });
         if (ok && window !== null)
             renameWindow(window, opts.name);

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/broker-client/client.d.ts

@@ -22,11 +22,10 @@ export interface BrokerClientOptions {
  *  re-dialing the same target while the node is still alive — a yield
  *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
  *  broker on the same path. It gives up only when the node is genuinely gone:
- *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
- *  terminal — an idle-release node revives on its next inbox wake, so keep
- *  trying (the supervisor waits at a relaxed cadence for as long as the row
- *  stays live). Local canvas rows only — a remote target has no local row, so
- *  callers driving a remote attach must not consult this (see viewer.ts). */
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` and an
+ *  exact unfinalized parked resident are NOT terminal — either can wake while
+ *  the viewer remains seated. Local canvas rows only — a remote target has no
+ *  local row, so callers driving a remote attach must not consult this. */
 export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
 /** The plan-fixed interface (Wave 3): `connect()`, `on('frame', …)`,
  *  `send(frame)`, `on('close', …)`, plus `connect`/`error` events. */

package/dist/core/broker-client/client.js

@@ -41,14 +41,18 @@ const REQUEST_TIMEOUT_MS = 10_000;
  *  re-dialing the same target while the node is still alive — a yield
  *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
  *  broker on the same path. It gives up only when the node is genuinely gone:
- *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
- *  terminal — an idle-release node revives on its next inbox wake, so keep
- *  trying (the supervisor waits at a relaxed cadence for as long as the row
- *  stays live). Local canvas rows only — a remote target has no local row, so
- *  callers driving a remote attach must not consult this (see viewer.ts). */
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` and an
+ *  exact unfinalized parked resident are NOT terminal — either can wake while
+ *  the viewer remains seated. Local canvas rows only — a remote target has no
+ *  local row, so callers driving a remote attach must not consult this. */
 export function reconnectShouldGiveUp(row) {
     if (row === null)
         return true;
+    if (row.lifecycle === 'resident'
+        && row.status === 'done'
+        && row.intent === 'parked'
+        && row.final_report == null)
+        return false;
     return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
 }
 export class BrokerClient extends EventEmitter {