@crouton-kit/crouter 0.3.78 → 0.3.79

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

@@ -0,0 +1,444 @@
+// Contract-seam tests for the external command-plugin seam (Phase 1).
+// Run with: node --import tsx/esm --test src/core/__tests__/command-plugins.test.ts
+//
+// All tests run against an ISOLATED home (HOME → a fresh temp dir, no ambient
+// user plugins) and pass an explicit no-`.crouter` startDir, so discovery is
+// deterministic and cannot pick up the developer's real machine state.
+//
+// Covers the spec's Tests items:
+//  1. Registry composition — a fixture top-level branch + leaf composes into
+//     real BranchDef/LeafDef whose root/branch/leaf help carries the plugin's
+//     representations, schema, effects, and stable order.
+//  2. Core collision — a fixture claiming a SUBTREE_NAMES name is skipped +
+//     recorded as a command_collision issue.
+//  3. Scope/shadowing — a project copy shadows a user copy of the same plugin
+//     name; a disabled project copy suppresses the user copy.
+//  4. Protocol integration (table-driven, one fixture executable) — request
+//     envelope contents, rendered success, --json mirror, stderr separation,
+//     recoverable error propagation, and every malformed case.
+//  5. Lifecycle without restart — install/disable/edit/remove all take effect
+//     on the next discovery call (per-invocation, no cache).
+//  6/7. Typed issues for path/exec-bit/schema/unknown-key/parent violations
+//     without executing the fixture binary.
+import { test, describe, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, chmodSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+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 { composeExternalSubtrees } from '../command-plugins/compose.js';
+import { defineRoot } from '../command.js';
+import { renderRoot, renderBranch, renderLeafArgv } from '../help.js';
+import { renderResult } from '../render.js';
+import { CrtrError } from '../errors.js';
+import { resetScopeCache } from '../scope.js';
+import { listInstalledPluginsInRoot } from '../resolver.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.
+const RESERVED = new Set(['push', 'node', 'canvas', 'sys', 'memory']);
+// ---------------------------------------------------------------------------
+// Fixture executable: reads one JSON request on stdin, writes one envelope.
+// Behavior is selected by req.input.mode so one binary drives the whole table.
+// ---------------------------------------------------------------------------
+const FIXTURE_EXEC = `#!/usr/bin/env node
+const fs = require('fs');
+let data = '';
+process.stdin.on('data', (c) => (data += c));
+process.stdin.on('end', () => {
+  const req = JSON.parse(data);
+  const log = process.env.FIXTURE_REQUEST_LOG;
+  if (log) fs.writeFileSync(log, JSON.stringify(req));
+  const mode = (req.input && req.input.mode) || 'ok';
+  const env = (o, code) => { process.stdout.write(JSON.stringify(o)); process.exit(code); };
+  if (mode === 'invalid-json') { process.stdout.write('this is not json'); process.exit(0); }
+  if (mode === 'extra-stdout') { process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { app_id: 'x' } }) + '\\nEXTRA JUNK'); process.exit(0); }
+  if (mode === 'oversize') { process.stdout.write('x'.repeat(11 * 1024 * 1024)); process.exit(0); }
+  if (mode === 'signal') { process.kill(process.pid, 'SIGKILL'); return; }
+  if (mode === 'error') return env({ protocolVersion: 1, ok: false, error: { code: 'authentication_required', message: 'No home session is available.', field: 'session', next: 'Log in, then retry.' } }, 1);
+  if (mode === 'reserved-code') return env({ protocolVersion: 1, ok: false, error: { code: 'internal', message: 'boom' } }, 1);
+  if (mode === 'missing-field') return env({ protocolVersion: 1, ok: true, result: { status: 'running' } }, 0);
+  if (mode === 'exit-mismatch') return env({ protocolVersion: 1, ok: true, result: { app_id: req.input.appId, status: 'running' } }, 3);
+  if (mode === 'diag') { process.stderr.write('a diagnostic line on stderr\\n'); return env({ protocolVersion: 1, ok: true, result: { app_id: req.input.appId, status: 'running' } }, 0); }
+  return env({ protocolVersion: 1, ok: true, result: { app_id: req.input.appId, status: 'running' } }, 0);
+});
+`;
+function commandsJson(topName = 'app') {
+    return {
+        schemaVersion: 1,
+        executable: 'bin/cmd.js',
+        mounts: [
+            {
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: topName,
+                    description: 'application lifecycle and inspection',
+                    whenToUse: 'you need to create, deploy, inspect, or remove an application',
+                    rootEntry: {
+                        concept: 'applications hosted by a crouter home',
+                        description: 'application lifecycle and inspection',
+                        whenToUse: 'you need to create, deploy, inspect, or remove an application',
+                    },
+                    summary: 'application lifecycle and inspection',
+                    model: 'Applications are product resources owned by the selected home.',
+                    children: [
+                        {
+                            kind: 'leaf',
+                            name: 'show',
+                            description: 'show one application',
+                            whenToUse: 'inspect a single application by id',
+                            tier: 'important',
+                            summary: 'show one application details',
+                            params: [
+                                { kind: 'positional', name: 'app-id', required: true, constraint: 'the application id' },
+                                { kind: 'flag', name: 'mode', type: 'string', required: false, constraint: 'fixture behavior selector' },
+                            ],
+                            output: [
+                                { name: 'app_id', type: 'string', required: true, constraint: 'the echoed application id' },
+                                { name: 'status', type: 'string', required: false, constraint: 'current application status' },
+                            ],
+                            outputKind: 'object',
+                            effects: ['None. Read-only.'],
+                        },
+                    ],
+                },
+            },
+        ],
+    };
+}
+/** Write a plugin into `scopeRoot/plugins/<name>/` with a command manifest +
+ *  executable. `manifest` is the commands.json object (default fixture). */
+function installPlugin(scopeRoot, name, opts = {}) {
+    const root = join(scopeRoot, 'plugins', name);
+    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+    mkdirSync(join(root, 'bin'), { recursive: true });
+    const pointer = opts.commandsPointer ?? 'commands.json';
+    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name, version: '0.1.0', description: 'fixture', commands: pointer }));
+    writeFileSync(join(root, 'commands.json'), JSON.stringify(opts.manifest ?? commandsJson()));
+    const execPath = join(root, 'bin', 'cmd.js');
+    writeFileSync(execPath, opts.exec ?? FIXTURE_EXEC);
+    chmodSync(execPath, opts.execBit === false ? 0o644 : 0o755);
+    if (opts.enabled === false) {
+        writeFileSync(join(scopeRoot, 'config.json'), JSON.stringify({ plugins: { [name]: { enabled: false } } }));
+    }
+    return root;
+}
+// ---------------------------------------------------------------------------
+// Isolated home + workspace
+// ---------------------------------------------------------------------------
+let home; // becomes HOME → user scope root = $HOME/.crouter
+let userRoot;
+let projectDir; // a workspace with its own .crouter (project scope)
+let projectRoot;
+let emptyStart; // a startDir with NO .crouter anywhere above it
+let realHome;
+let realProfile;
+before(() => {
+    realHome = process.env['HOME'];
+    realProfile = process.env['CRTR_PROFILE_ID'];
+    delete process.env['CRTR_PROFILE_ID'];
+});
+after(() => {
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+    if (realProfile !== undefined)
+        process.env['CRTR_PROFILE_ID'] = realProfile;
+});
+// Every temp dir any test mints, so cleanup removes them ALL (an
+// after(...[home, ...]) would only see the LAST test's set and leak the rest).
+const tempDirs = [];
+function mintDir(prefix) {
+    const d = mkdtempSync(join(tmpdir(), prefix));
+    tempDirs.push(d);
+    return d;
+}
+beforeEach(() => {
+    home = mintDir('crtr-cmdplugin-home-');
+    process.env['HOME'] = home;
+    userRoot = join(home, '.crouter');
+    mkdirSync(join(userRoot, 'plugins'), { recursive: true });
+    projectDir = mintDir('crtr-cmdplugin-proj-');
+    projectRoot = join(projectDir, '.crouter');
+    mkdirSync(join(projectRoot, 'plugins'), { recursive: true });
+    emptyStart = mintDir('crtr-cmdplugin-empty-');
+    resetScopeCache();
+});
+after(() => {
+    for (const d of tempDirs) {
+        try {
+            rmSync(d, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    resetScopeCache();
+});
+function leafOf(branch, name) {
+    const c = branch.children.find((x) => x.name === name);
+    assert.ok(c !== undefined && c.kind === 'leaf', `expected leaf ${name}`);
+    return c;
+}
+// ---------------------------------------------------------------------------
+// 1. Registry composition
+// ---------------------------------------------------------------------------
+describe('registry composition', () => {
+    test('a fixture top-level branch composes with plugin-owned help, schema, effects, stable order', () => {
+        installPlugin(userRoot, 'crouter-infra');
+        resetScopeCache();
+        const snapshot = discoverCommandContributions(RESERVED, emptyStart);
+        // user scope is discovered from any startDir (it's not a project ancestor).
+        assert.equal(snapshot.issues.length, 0, JSON.stringify(snapshot.issues));
+        const external = composeExternalSubtrees(snapshot);
+        assert.equal(external.length, 1);
+        const app = external[0];
+        assert.equal(app.kind, 'branch');
+        assert.equal(app.name, 'app');
+        // Root help carries the plugin-owned rootEntry (mapped description→desc,
+        // whenToUse→useWhen), no core file knows what an app is.
+        const root = defineRoot({ tagline: 'test', globals: [], subtrees: external });
+        const rootOut = renderRoot(root.help);
+        assert.match(rootOut, /<command name="app">/);
+        assert.match(rootOut, /applications hosted by a crouter home/);
+        assert.match(rootOut, /use when you need to create, deploy, inspect, or remove an application/);
+        // important child promoted into root with its shortform desc.
+        assert.match(rootOut, /app show {2,}show one application/);
+        // Branch help lists the leaf via its own description/whenToUse.
+        const branchOut = renderBranch(app.help);
+        assert.match(branchOut, /<command name="app" description="application lifecycle and inspection">/);
+        assert.match(branchOut, /Applications are product resources owned by the selected home\./);
+        assert.match(branchOut, /name="show"[^>]*whenToUse="inspect a single application by id"/);
+        // Leaf help carries the full input/output schema + effects.
+        const leaf = leafOf(app, 'show');
+        const leafOut = renderLeafArgv(leaf.help);
+        assert.match(leafOut, /APP-ID/);
+        assert.match(leafOut, /--mode MODE/);
+        assert.match(leafOut, /app_id {2,}string\. the echoed application id/);
+        assert.match(leafOut, /None\. Read-only\./);
+    });
+});
+// ---------------------------------------------------------------------------
+// 2. Core collision
+// ---------------------------------------------------------------------------
+describe('core collision', () => {
+    test('a fixture claiming a core top-level name is skipped + recorded', () => {
+        installPlugin(userRoot, 'rogue', { manifest: commandsJson('push') });
+        resetScopeCache();
+        const snapshot = discoverCommandContributions(RESERVED, emptyStart);
+        assert.equal(composeExternalSubtrees(snapshot).length, 0, 'the colliding branch must not enter the tree');
+        const collision = snapshot.issues.find((i) => i.code === 'command_collision');
+        assert.ok(collision, 'a command_collision issue must be recorded for doctor/show');
+        assert.equal(collision.received, 'push');
+    });
+});
+// ---------------------------------------------------------------------------
+// 3. Scope / shadowing
+// ---------------------------------------------------------------------------
+describe('scope shadowing', () => {
+    test('a project copy shadows a user copy of the same plugin name', () => {
+        installPlugin(userRoot, 'crouter-infra');
+        installPlugin(projectRoot, 'crouter-infra');
+        resetScopeCache();
+        const effective = effectiveCommandPlugins(projectDir);
+        assert.equal(effective.length, 1);
+        assert.equal(effective[0].scope, 'project');
+        assert.equal(effective[0].root, join(projectRoot, 'plugins', 'crouter-infra'));
+    });
+    test('a disabled project copy suppresses the user copy (no resurfacing)', () => {
+        installPlugin(userRoot, 'crouter-infra');
+        installPlugin(projectRoot, 'crouter-infra', { enabled: false });
+        resetScopeCache();
+        // sanity: the project copy really is disabled at that root.
+        const projPlugins = listInstalledPluginsInRoot('project', projectRoot);
+        assert.equal(projPlugins.find((p) => p.name === 'crouter-infra').enabled, false);
+        const effective = effectiveCommandPlugins(projectDir);
+        assert.equal(effective.length, 0, 'the disabled higher-precedence copy must suppress the user copy');
+    });
+});
+// ---------------------------------------------------------------------------
+// 4. Protocol integration (table-driven)
+// ---------------------------------------------------------------------------
+describe('protocol integration', () => {
+    function showLeaf() {
+        installPlugin(userRoot, 'crouter-infra');
+        resetScopeCache();
+        const snapshot = discoverCommandContributions(RESERVED, emptyStart);
+        const app = composeExternalSubtrees(snapshot)[0];
+        return leafOf(app, 'show');
+    }
+    test('request envelope carries command path, camelCase input, cwd, plugin context', async () => {
+        const leaf = showLeaf();
+        const log = join(emptyStart, 'req.json');
+        process.env['FIXTURE_REQUEST_LOG'] = log;
+        try {
+            await leaf.run({ appId: 'app_123', mode: 'ok' });
+            const req = JSON.parse(readFileSync(log, 'utf8'));
+            assert.equal(req.protocolVersion, 1);
+            assert.deepEqual(req.command, ['app', 'show']);
+            assert.equal(req.input.appId, 'app_123');
+            assert.equal(req.context.cwd, process.cwd());
+            assert.equal(req.context.plugin.name, 'crouter-infra');
+            assert.equal(req.context.plugin.scope, 'user');
+            assert.equal(req.context.plugin.version, '0.1.0');
+            assert.equal(req.context.plugin.root, join(userRoot, 'plugins', 'crouter-infra'));
+        }
+        finally {
+            delete process.env['FIXTURE_REQUEST_LOG'];
+        }
+    });
+    test('ok:true → result validated + rendered; --json mirrors the same object', async () => {
+        const leaf = showLeaf();
+        const result = await leaf.run({ appId: 'app_123', mode: 'ok' });
+        assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
+        // Rendered through the existing generic renderer (no custom renderer).
+        const rendered = renderResult(result, leaf.help);
+        assert.match(rendered, /app_id/);
+        assert.match(rendered, /app_123/);
+    });
+    test('valid envelope + wrong exit code is honored (soft diagnostic, not a discard)', async () => {
+        const leaf = showLeaf();
+        const result = await leaf.run({ appId: 'app_123', mode: 'exit-mismatch' });
+        assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
+    });
+    test('stderr diagnostics do not pollute the stdout envelope', async () => {
+        const leaf = showLeaf();
+        const result = await leaf.run({ appId: 'app_123', mode: 'diag' });
+        assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
+    });
+    test('ok:false → structured CrtrError with the plugin code', async () => {
+        const leaf = showLeaf();
+        await assert.rejects(() => leaf.run({ appId: 'app_123', mode: 'error' }), (e) => e instanceof CrtrError && e.code === 'authentication_required' && (e.details?.['next'] === 'Log in, then retry.'));
+    });
+    const malformed = [
+        ['invalid JSON', 'invalid-json'],
+        ['extra stdout after the envelope', 'extra-stdout'],
+        ['oversize stdout (>10 MiB)', 'oversize'],
+        ['signal termination', 'signal'],
+        ['missing declared output field', 'missing-field'],
+        ['reserved error code', 'reserved-code'],
+    ];
+    for (const [desc, mode] of malformed) {
+        test(`malformed: ${desc} → plugin_protocol_error`, async () => {
+            const leaf = showLeaf();
+            await assert.rejects(() => leaf.run({ appId: 'app_123', mode }), (e) => e instanceof CrtrError && e.code === 'plugin_protocol_error');
+        });
+    }
+});
+// ---------------------------------------------------------------------------
+// 4b. True end-to-end CLI invocation (argv → parseArgv → adapter → renderer)
+// ---------------------------------------------------------------------------
+describe('end-to-end CLI invocation', () => {
+    // dist/cli.js is up 4 from src/core/__tests__/. Requires a prior `npm run
+    // build` (the harness/CI builds before tests). Drives the WHOLE seam: the
+    // declared positional `app-id` must arrive as `appId` in the request, and
+    // the rendered + --json outputs come through the real dispatcher.
+    const cli = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'dist', 'cli.js');
+    const runCrtr = (args) => {
+        installPlugin(userRoot, 'crouter-infra');
+        resetScopeCache();
+        return execFileSync(process.execPath, [cli, ...args], {
+            cwd: emptyStart,
+            env: { ...process.env, HOME: home, CRTR_NO_BOOTSTRAP: '1', CRTR_FRONT_DOOR: '' },
+            encoding: 'utf8',
+        });
+    };
+    test('crtr app show <id> renders the plugin result end to end', { timeout: 40000 }, () => {
+        const out = runCrtr(['app', 'show', 'app_123']);
+        assert.match(out, /app_123/);
+        assert.match(out, /running/);
+    });
+    test('--json mirrors the same result object', { timeout: 40000 }, () => {
+        const out = runCrtr(['app', 'show', 'app_123', '--json']);
+        const obj = JSON.parse(out);
+        assert.equal(obj.app_id, 'app_123');
+        assert.equal(obj.status, 'running');
+    });
+});
+// ---------------------------------------------------------------------------
+// 5. Lifecycle without restart (per-invocation discovery)
+// ---------------------------------------------------------------------------
+describe('lifecycle without restart', () => {
+    test('install → appears; disable → gone; edit → visible; remove → gone', () => {
+        const discover = () => {
+            resetScopeCache();
+            return composeExternalSubtrees(discoverCommandContributions(RESERVED, emptyStart));
+        };
+        // install
+        installPlugin(userRoot, 'crouter-infra');
+        assert.equal(discover().length, 1);
+        // disable (config edit only — no restart)
+        writeFileSync(join(userRoot, 'config.json'), JSON.stringify({ plugins: { 'crouter-infra': { enabled: false } } }));
+        assert.equal(discover().length, 0);
+        // re-enable + edit the declaration (rename the top-level command)
+        writeFileSync(join(userRoot, 'config.json'), JSON.stringify({ plugins: { 'crouter-infra': { enabled: true } } }));
+        writeFileSync(join(userRoot, 'plugins', 'crouter-infra', 'commands.json'), JSON.stringify(commandsJson('deploy')));
+        const afterEdit = discover();
+        assert.equal(afterEdit.length, 1);
+        assert.equal(afterEdit[0].name, 'deploy');
+        // remove
+        rmSync(join(userRoot, 'plugins', 'crouter-infra'), { recursive: true, force: true });
+        assert.equal(discover().length, 0);
+    });
+});
+// ---------------------------------------------------------------------------
+// 6/7. Typed issues without executing the binary
+// ---------------------------------------------------------------------------
+describe('typed validation issues', () => {
+    function validate(manifest, extra = {}) {
+        installPlugin(userRoot, 'p', { manifest, ...extra });
+        resetScopeCache();
+        const plugins = listInstalledPluginsInRoot('user', userRoot);
+        const p = plugins.find((x) => x.name === 'p');
+        return validatePluginCommands(p, RESERVED);
+    }
+    test('unknown schemaVersion → command_schema_version, no contribution', () => {
+        const m = commandsJson();
+        m['schemaVersion'] = 2;
+        const v = validate(m);
+        assert.equal(v.contributions.length, 0);
+        assert.ok(v.issues.some((i) => i.code === 'command_schema_version'));
+    });
+    test('unknown top-level key → command_manifest_invalid', () => {
+        const m = commandsJson();
+        m['requires'] = { crtr: '>=1' };
+        const v = validate(m);
+        assert.ok(v.issues.some((i) => i.code === 'command_manifest_invalid'));
+    });
+    test('non-empty parent → command_parent_invalid', () => {
+        const m = commandsJson();
+        m.mounts[0].parent = ['sys'];
+        const v = validate(m);
+        assert.ok(v.issues.some((i) => i.code === 'command_parent_invalid'));
+        assert.equal(v.contributions.length, 0);
+    });
+    test('non-executable file → command_not_executable', () => {
+        const v = validate(commandsJson(), { execBit: false });
+        assert.ok(v.issues.some((i) => i.code === 'command_not_executable'));
+    });
+    test('executable escaping the plugin root → command_path_unsafe', () => {
+        const m = commandsJson();
+        m['executable'] = '../../../../bin/sh';
+        const v = validate(m);
+        assert.ok(v.issues.some((i) => i.code === 'command_path_unsafe'));
+    });
+    test('a top-level leaf (no rootEntry) → command_node_invalid', () => {
+        const m = {
+            schemaVersion: 1,
+            executable: 'bin/cmd.js',
+            mounts: [{ parent: [], node: { kind: 'leaf', name: 'x', description: 'd', whenToUse: 'w', summary: 's', params: [], output: [], outputKind: 'object', effects: ['None. Read-only.'] } }],
+        };
+        const v = validate(m);
+        assert.ok(v.issues.some((i) => i.code === 'command_node_invalid'));
+        assert.equal(v.contributions.length, 0);
+    });
+    test('a valid manifest yields a contribution and zero issues', () => {
+        const v = validate(commandsJson());
+        assert.equal(v.issues.length, 0);
+        assert.equal(v.contributions.length, 1);
+        assert.equal(v.contributions[0].node.name, 'app');
+    });
+});

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -17,6 +17,11 @@ export declare class SessionManager {
     static open(path: string): SessionManager;
     getSessionId(): string;
     getSessionFile(): string;
+    /** The directory containing the session file — the real SessionManager's
+     *  getSessionDir(). The broker prewarms the session-list cache with it at boot
+     *  (broker.ts runBroker), so the fixture must expose it or every broker boot
+     *  crashes before it binds view.sock. */
+    getSessionDir(): string;
     private leafId;
     /** Cycling support (crtr-cycle marker) — mirrors the real SDK's getLeafId/
      *  resetLeaf/appendCustomEntry just enough that `buildBrokerSession`'s cycling
@@ -124,6 +129,7 @@ declare class FakeSession {
         }>;
         getSessionId: () => string;
         getSessionFile: () => string;
+        getSessionDir: () => string;
     };
     get sessionId(): string;
     get sessionFile(): string | undefined;

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -30,7 +30,7 @@
 //   <nodeDir>/fake-pi.cmd            — harness writes ONE JSON command (turn|stop|dialog)
 //   <nodeDir>/fake-pi.dialog.jsonl   — one line per resolved unattended dialog (§5.4)
 import { writeFileSync, readFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync, } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { DefaultResourceLoader, getAgentDir } from '@earendil-works/pi-coding-agent';
 /** Test seam (M-1 regression): a FRESH-start kickoff prompt carrying this token
@@ -100,6 +100,13 @@ export class SessionManager {
     getSessionFile() {
         return this.sessionFile;
     }
+    /** The directory containing the session file — the real SessionManager's
+     *  getSessionDir(). The broker prewarms the session-list cache with it at boot
+     *  (broker.ts runBroker), so the fixture must expose it or every broker boot
+     *  crashes before it binds view.sock. */
+    getSessionDir() {
+        return dirname(this.sessionFile);
+    }
     leafId = null;
     /** Cycling support (crtr-cycle marker) — mirrors the real SDK's getLeafId/
      *  resetLeaf/appendCustomEntry just enough that `buildBrokerSession`'s cycling
@@ -285,6 +292,7 @@ class FakeSession {
             getUserMessagesForForking: () => this.tree.getUserMessagesForForking(),
             getSessionId: () => this.sm.getSessionId(),
             getSessionFile: () => this.sm.getSessionFile(),
+            getSessionDir: () => this.sm.getSessionDir(),
         };
     }
     get sessionId() {

package/dist/core/__tests__/preview-registry-sync.test.js

@@ -10,10 +10,39 @@
 // buildRoot()-assembled tree (safe here — this is a test, not the attach
 // bundle) and asserts the set of leaves declaring `suppressOutput: true`
 // matches the registry exactly.
-import { test } from 'node:test';
+import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { buildRoot } from '../../build-root.js';
 import { SUPPRESS_OUTPUT_LEAVES } from '../preview-registry.js';
+import { resetScopeCache } from '../scope.js';
+// buildRoot() composes external command-plugin branches from the effective
+// enabled plugins (user scope + project ancestors). Pin HOME + profile to an
+// isolated no-plugin home so ambient machine state can't inject an external
+// leaf and make this drift guard nondeterministic.
+let home;
+let realHome;
+let realProfile;
+before(() => {
+    realHome = process.env['HOME'];
+    realProfile = process.env['CRTR_PROFILE_ID'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-preview-registry-'));
+    process.env['HOME'] = home;
+    delete process.env['CRTR_PROFILE_ID'];
+    resetScopeCache();
+});
+after(() => {
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+    if (realProfile !== undefined)
+        process.env['CRTR_PROFILE_ID'] = realProfile;
+    rmSync(home, { recursive: true, force: true });
+    resetScopeCache();
+});
 test('preview-registry.ts matches every leaf declaring help.preview.suppressOutput', async () => {
     const root = await buildRoot();
     const declared = new Set();

package/dist/core/__tests__/scope-crouter-home-fence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/scope-crouter-home-fence.test.js

@@ -0,0 +1,55 @@
+// The scope ancestor walk (`collectAncestorScopeRoots` → `findProjectScopeRoots`)
+// must never climb at or above `homedir()`. When HOME is relocated and nested
+// under a directory tree that itself contains a `.crouter/` (a mock-VM home
+// under the real host home, or any relocated-HOME sandbox), the unfenced walk
+// climbs ABOVE homedir() and sweeps in the above-HOME `.crouter` as a bogus
+// "project ancestor" — leaking that host's entire user-global memory store into
+// every nested-HOME node's assembled knowledge/preference catalog. This test
+// pins the fence: an ancestor `.crouter/` sitting ABOVE the relocated HOME must
+// NOT be collected as a project scope root, while a legitimate project
+// `.crouter/` BETWEEN the cwd and HOME still is.
+//
+// Mirrors src/core/__tests__/on-read-crouter-home-fence.test.ts.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/scope-crouter-home-fence.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findProjectScopeRoots, resetScopeCache } from '../scope.js';
+let sandbox;
+let prevHomeEnv;
+before(() => {
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    resetScopeCache();
+    // A sandbox that CONTAINS the relocated HOME, so the ancestor walk from a cwd
+    // under HOME can (without the fence) climb above HOME into the sandbox.
+    sandbox = mkdtempSync(join(tmpdir(), 'crtr-scope-fence-'));
+});
+after(() => {
+    resetScopeCache();
+    rmSync(sandbox, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+test('an ancestor .crouter ABOVE a relocated HOME is not collected as a project scope root', () => {
+    // Simulated host user-global store, sitting ABOVE the relocated home.
+    const hostUserRoot = join(sandbox, '.crouter');
+    mkdirSync(join(hostUserRoot, 'memory'), { recursive: true });
+    // The relocated HOME, nested one level under the sandbox.
+    const home = join(sandbox, 'vm-home');
+    process.env['HOME'] = home;
+    // A legitimate project `.crouter/` between the node cwd and HOME.
+    const projectDir = join(home, 'work', 'proj');
+    const projectRoot = join(projectDir, '.crouter');
+    mkdirSync(join(projectRoot, 'memory'), { recursive: true });
+    resetScopeCache();
+    const roots = findProjectScopeRoots(projectDir, null);
+    assert.ok(!roots.includes(hostUserRoot), `above-HOME .crouter must NOT be collected as a project ancestor; got: ${JSON.stringify(roots)}`);
+    assert.ok(roots.includes(projectRoot), `legitimate project .crouter between cwd and HOME must still be collected; got: ${JSON.stringify(roots)}`);
+});

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

@@ -1,6 +1,11 @@
 import { type CanvasSource } from '../source.js';
 import type { RemoteEventStream } from '../remote-event-stream.js';
 import { type CoalescedRebuilder } from './rebuild-coalescer.js';
+import { type BindingId, type BindingResolution, type RawTerminalInput } from '../../keybindings/index.js';
+declare const BROWSE_NAV_ACTIONS: readonly ["crtr.browse.quit", "crtr.browse.down", "crtr.browse.up", "crtr.browse.first", "crtr.browse.last", "crtr.browse.expand-or-child", "crtr.browse.collapse-or-parent", "crtr.browse.toggle-fold", "crtr.browse.tab-next", "crtr.browse.tab-previous", "crtr.browse.tab.1", "crtr.browse.tab.2", "crtr.browse.tab.3", "crtr.browse.tab.4", "crtr.browse.tab.5", "crtr.browse.close-subtree", "crtr.browse.sort", "crtr.browse.scope", "crtr.browse.residents", "crtr.browse.preview", "crtr.browse.search", "crtr.browse.revive-now", "crtr.browse.focus"];
+declare const BROWSE_SEARCH_ACTIONS: readonly ["crtr.browse.search.cancel", "crtr.browse.search.commit", "crtr.browse.search.delete", "crtr.browse.search.quit"];
+export declare function resolveBrowseNavAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_NAV_ACTIONS)[number] | null;
+export declare function resolveBrowseSearchAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_SEARCH_ACTIONS)[number] | null;
 /** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
  *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
  *  round, never one N+1 remote-subprocess rebuild per event. Exported (rather
@@ -18,3 +23,4 @@ export declare function runBrowse(opts?: {
     source?: CanvasSource;
     eventStream?: RemoteEventStream;
 }): Promise<void>;
+export {};