@crouton-kit/crouter 0.3.70 → 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__/fault-classifier.test.js

@@ -28,3 +28,18 @@ test('HTTP 401/403 objects still classify as auth (unchanged path)', () => {
     assert.equal(classify('pi→provider', { status: 401, statusText: 'Unauthorized' }).kind, 'auth');
     assert.equal(classify('pi→provider', { status: 403 }).kind, 'auth');
 });
+// Stale ⚠ triangles — undici mid-stream disconnect text (e.g. a laptop sleep/
+// wake episode) must classify as a transient connection blip (disposition
+// 'auto'), not fall through to 'other' (disposition 'fatal', "needs you").
+test('undici stream-drop texts classify as connection/auto, not other/fatal', () => {
+    for (const msg of ['terminated', 'other side closed', 'premature close']) {
+        const c = classify('pi→provider', msg);
+        assert.equal(c.kind, 'connection', `"${msg}" must classify as connection`);
+        assert.equal(c.disposition, 'auto', `"${msg}" must be auto-retried, not fatal`);
+    }
+});
+test('"terminated" matches as a whole word only (no false positive on substrings)', () => {
+    // \bterminated\b must not match e.g. "unterminated" as a stray substring hit —
+    // guard the word-boundary choice explicitly.
+    assert.notEqual(classify('pi→provider', 'preterminated').kind, 'connection');
+});

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__/full/broker-dialogs.test.js

@@ -142,10 +142,15 @@ test('G6 — zero-viewer dialog resolves immediately; an unanswered attended dia
     assert.equal(r1[base].resolved, false, 'G6a: zero-viewer dialog resolves to the default (deny)');
     assert.ok(r1[base].ms < 2000, `G6a: resolved immediately (noOp), not after the 5000ms timeout — got ${r1[base].ms}ms`);
     // (b) controller attached but silent → the broker resolves on the SHORT explicit
-    // per-dialog timeout (800ms), never the 120s default.
+    // per-dialog timeout (800ms), never the 120s default. On timeout the broker also
+    // broadcasts a correlated `extension_ui_dismiss` keyed to the dialog's id, so the
+    // controller's overlay (which has no independent timer) is torn down by id.
     const c = await ctrl('g6-ctrl');
     h.fakeCmd(id, { cmd: 'dialog', timeout: 800 });
-    await c.waitFrame((f) => f.type === 'extension_ui_request', 'G6b dialog forwarded to controller'); // received, deliberately NOT answered
+    const req = await c.waitFrame((f) => f.type === 'extension_ui_request', 'G6b dialog forwarded to controller'); // received, deliberately NOT answered
+    const reqId = req.id;
+    const dismiss = await c.waitFrame((f) => f.type === 'extension_ui_dismiss' && f.id === reqId, 'G6b broker emits a correlated extension_ui_dismiss on timeout');
+    assert.equal(dismiss.id, reqId, 'G6b: the dismiss frame carries the timed-out dialog id, not another');
     const r2 = await awaitDialogs(base + 2, 'G6b attended dialog resolved on timeout');
     assert.equal(r2[base + 1].resolved, false, 'G6b: an unanswered attended dialog resolves to the default (deny)');
     assert.ok(r2[base + 1].ms >= 600 && r2[base + 1].ms < 5000, `G6b: resolved on the ~800ms per-dialog timeout, not instantly and not the 120s default — got ${r2[base + 1].ms}ms`);

package/dist/core/__tests__/host-teardown-process-group.test.js

@@ -62,7 +62,7 @@
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createHarness } from './helpers/harness.js';
@@ -180,9 +180,20 @@ async function spawnBrokerWithSharedGroupDescendant(tag, descendantScript = 'sle
     if (leader.pid == null)
         throw new Error('failed to spawn fake broker leader');
     trackPid(leader.pid);
-    await h.waitFor(() => existsSync(pidFile), { label: `${tag}: descendant pid file written` });
-    const descendantPid = Number.parseInt(readFileSync(pidFile, 'utf8').trim(), 10);
-    assert.ok(Number.isInteger(descendantPid) && descendantPid > 0, `${tag}: parsed a real descendant pid`);
+    const descendantPid = await h.waitFor(() => {
+        try {
+            const record = readFileSync(pidFile, 'utf8');
+            if (!/^\d+\n$/.test(record))
+                return false;
+            const pid = Number(record.slice(0, -1));
+            return Number.isSafeInteger(pid) && pid > 0 ? pid : false;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }, { label: `${tag}: valid descendant pid written` });
     trackPid(descendantPid);
     await h.waitFor(() => isPidAlive(descendantPid), { label: `${tag}: descendant alive before teardown` });
     return { leaderPid: leader.pid, descendantPid };

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 {};