@north-light/crouter 0.3.221 → 0.3.223

package/dist/commands/sys/doctor.js

@@ -15,10 +15,12 @@ import { detectPackageManager } from './setup-core.js';
 import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
 import { discoverHookRegistry } from '../../core/command-hooks/discovery.js';
 import { resolveBinContributions } from '../../core/runtime/bin-contributions.js';
+import { inspectHumanActions } from '../../core/human-actions.js';
 import { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
 import { listAllPlugins } from '../../core/resolver.js';
 import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
 import { processGeneration, processLocatedGeneration, runtimeManifest, selectedGeneration } from './shared.js';
+import { CONFIG_FILE } from '../../types.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
 }
@@ -198,6 +200,55 @@ function runBinContributionChecks(scopes) {
     }
     return results;
 }
+/** Validate every scope-configured completion action without executing it. */
+function runHumanActionChecks(scopes) {
+    const inScope = new Set(scopes);
+    const userConfig = join(scopeRoot('user'), CONFIG_FILE);
+    const results = [];
+    const winningOrigins = new Map();
+    for (const action of inspectHumanActions(process.cwd())) {
+        if ('kind' in action) {
+            if (action.kind === 'unknown_action')
+                continue;
+            const scope = action.configOrigin === userConfig ? 'user' : 'project';
+            const block = action.block === true;
+            const winningOrigin = block ? undefined : winningOrigins.get(action.name);
+            if (!block && winningOrigin === undefined)
+                winningOrigins.set(action.name, action.configOrigin);
+            if (!inScope.has(scope))
+                continue;
+            const checkName = block ? `humanActions:block@${action.configOrigin}` : `humanActions:${action.name}@${action.configOrigin}`;
+            const remediation = {
+                kind: 'human_action',
+                description: block
+                    ? `Fix or remove the \`humanActions\` block in ${action.configOrigin}. Actions run argv directly without a shell.`
+                    : `Fix or remove the \`humanActions.${action.name}\` declaration in ${action.configOrigin}. Actions run argv directly without a shell.`,
+            };
+            if (winningOrigin !== undefined) {
+                results.push({
+                    scope,
+                    name: checkName,
+                    status: 'pass',
+                    message: `warning: shadowed by ${winningOrigin}; ${action.configOrigin}: ${action.reason}`,
+                    remediation,
+                });
+            }
+            else {
+                results.push(failCheck(scope, checkName, `${action.configOrigin}: ${action.reason}`, remediation));
+            }
+            continue;
+        }
+        const scope = action.configOrigin === userConfig ? 'user' : 'project';
+        const winningOrigin = winningOrigins.get(action.name);
+        if (winningOrigin === undefined)
+            winningOrigins.set(action.name, action.configOrigin);
+        if (!inScope.has(scope))
+            continue;
+        const shadowedPrefix = winningOrigin === undefined ? '' : `shadowed by ${winningOrigin}; `;
+        results.push(pass(scope, `humanActions:${action.name}@${action.configOrigin}`, `${shadowedPrefix}${action.configOrigin} → ${action.argv[0]} (cwd ${action.cwd})`));
+    }
+    return results;
+}
 /** Check each enabled plugin's advisory PATH requirements against the exact
  *  broker environment a node launched from this cwd/profile receives. */
 function runRequiresChecks(scopes) {
@@ -506,12 +557,12 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/collision problems and carry disable/update/remove/show remediation; healthy hooks list effective target, phase, and op. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. humanActions:<name>@<config-origin> checks validate each user/project scope completion-action declaration: action-name and argv shape, cwd directory, argv[0] regular-file existence, and execute permission; they never execute an action. A malformed effective declaration fails; a malformed shadowed declaration is a pass-level warning that names the winning and shadowed origins. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/collision problems and carry disable/update/remove/show remediation; healthy hooks list effective target, phase, and op. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
-            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command and hook manifests, bare-binary (`bin`) declarations, and advisory `requires` PATH checks never execute plugin or contributed binaries.',
+            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command and hook manifests, bare-binary (`bin`) declarations, humanActions declarations, and advisory `requires` PATH checks never execute plugin or contributed binaries.',
             'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and plugin command/hook findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
             'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with its command) so callers can apply it directly without --fix.',
         ],
@@ -531,6 +582,7 @@ export const sysDoctorLeaf = defineLeaf({
         allResults.push(...await runCommandPluginChecks(scopes));
         allResults.push(...await runHookPluginChecks(scopes));
         allResults.push(...runBinContributionChecks(scopes));
+        allResults.push(...runHumanActionChecks(scopes));
         allResults.push(...runRequiresChecks(scopes));
         allResults.push(...await runFaultChecks());
         const processLocation = processGeneration();

package/dist/core/__tests__/broker-extension-canvas-db-boundary.test.js

@@ -41,10 +41,13 @@ function dbReach(root) {
     }
     return null;
 }
-test('every shipped broker extension is transitively canvas.db-free', () => {
-    for (const name of CANVAS_EXTENSION_NAMES) {
-        const root = join(SOURCE_ROOT, 'pi-extensions', `${name}.ts`);
+test('every shipped broker extension and the prospective preflight are transitively canvas.db-free', () => {
+    const roots = [
+        ...CANVAS_EXTENSION_NAMES.map((name) => join(SOURCE_ROOT, 'pi-extensions', `${name}.ts`)),
+        join(SOURCE_ROOT, 'core/runtime/prospective-inventory-cli.ts'),
+    ];
+    for (const root of roots) {
         const reach = dbReach(root);
-        assert.equal(reach, null, `${name} reaches canvas.db through:\n${reach?.join('\n')}`);
+        assert.equal(reach, null, `${root} reaches canvas.db through:\n${reach?.join('\n')}`);
     }
 });

package/dist/core/__tests__/fixtures/memory-slash-live-probe.d.ts

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

package/dist/core/__tests__/fixtures/memory-slash-live-probe.js

@@ -0,0 +1,71 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DefaultResourceLoader, ExtensionRunner, } from '@earendil-works/pi-coding-agent';
+import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
+import { gatewayCommandRows, gatewayMemoryRows } from '../../runtime/chat-inventory-rows.js';
+import { captureChatCapabilities, registrationChatSurface } from '../../runtime/command-surface.js';
+import { runProspectiveInventory } from '../../runtime/prospective-inventory.js';
+async function main() {
+    const extensionPath = process.argv[2];
+    const invocations = JSON.parse(process.argv[3] ?? '[]');
+    if (extensionPath === undefined)
+        throw new Error('extension path is required');
+    const cwd = process.cwd();
+    const home = process.env['CRTR_HOME'];
+    if (home === undefined || home === '')
+        throw new Error('CRTR_HOME is required');
+    const stateBeforeProspective = existsSync(home);
+    const prospective = await runProspectiveInventory({ cwd, profileId: null, extensions: [extensionPath] });
+    const stateAfterProspective = existsSync(home);
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir: join(cwd, '.pi'),
+        additionalExtensionPaths: [extensionPath],
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const loaded = loader.getExtensions();
+    if (loaded.errors.length > 0)
+        throw new Error(JSON.stringify(loaded.errors));
+    const sent = [];
+    let activeName = '';
+    loaded.runtime.sendMessage = (message, options) => sent.push({ name: activeName, message, options });
+    const runner = new ExtensionRunner(loaded.extensions, loaded.runtime, cwd, undefined, undefined);
+    const registered = runner.getRegisteredCommands();
+    captureChatCapabilities({ commands: registered, templates: [] });
+    const commands = gatewayCommandRows(registered.map((command) => {
+        const expansion = command.expansion;
+        return {
+            name: command.invocationName,
+            description: command.description ?? '',
+            source: 'command',
+            ...(expansion === undefined ? {} : { expansion }),
+            ...registrationChatSurface(command),
+        };
+    }));
+    const memoryRefs = gatewayMemoryRows(buildRefInventory().refs);
+    const notifications = [];
+    for (const invocation of invocations) {
+        const command = runner.getCommand(invocation.name);
+        if (command === undefined)
+            throw new Error(`command not registered: ${invocation.name}`);
+        activeName = invocation.name;
+        await command.handler(invocation.args, {
+            cwd,
+            ui: { notify: (...args) => notifications.push(args) },
+        });
+    }
+    writeFileSync(3, JSON.stringify({
+        prospective,
+        stateBeforeProspective,
+        stateAfterProspective,
+        commands,
+        memoryRefs,
+        sent,
+        notifications,
+    }));
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/core/__tests__/human-action-delivery.test.d.ts

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

package/dist/core/__tests__/human-action-delivery.test.js

@@ -0,0 +1,140 @@
+import { after, afterEach, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { claimActionDelivery, enqueueActionDelivery, readActionDelivery, } from '../canvas/human-deliveries.js';
+import { actionDeliveryBackoffMs, actionDeliverySettlementForOutcome, deliverAction, } from '../../daemon/human/deliver-action.js';
+let home;
+const priorHome = process.env['CRTR_HOME'];
+beforeEach(() => {
+    closeDb();
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-action-delivery-'));
+    process.env['CRTR_HOME'] = home;
+});
+afterEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    if (priorHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = priorHome;
+});
+test('action delivery retries follow the durable backoff and exit boundary', () => {
+    assert.equal(actionDeliveryBackoffMs(1), 5_000);
+    assert.equal(actionDeliveryBackoffMs(2), 10_000);
+    assert.equal(actionDeliveryBackoffMs(3), 20_000);
+    assert.equal(actionDeliveryBackoffMs(11), 3_600_000);
+    assert.equal(actionDeliveryBackoffMs(100), 3_600_000);
+    const now = 1_000_000;
+    const outcome = (exitCode, signal = null) => actionDeliverySettlementForOutcome({
+        exitCode,
+        signal,
+        timedOut: false,
+        stderr: 'diagnostic',
+    }, 2, now);
+    assert.deepEqual(outcome(0), { state: 'accepted' });
+    assert.deepEqual(outcome(77), {
+        state: 'pending',
+        nextAttemptAt: now + 10_000,
+        failure: { kind: 'exit', exitCode: 77, stderr: 'diagnostic' },
+    });
+    assert.deepEqual(outcome(78), {
+        state: 'permanent_failed',
+        failure: { kind: 'exit', exitCode: 78, stderr: 'diagnostic' },
+    });
+    assert.equal(outcome(79).state, 'pending');
+    assert.equal(outcome(null, 'SIGTERM').state, 'pending');
+    assert.equal(actionDeliverySettlementForOutcome({
+        exitCode: null,
+        signal: null,
+        timedOut: true,
+        stderr: '',
+    }, 1, now).state, 'pending');
+    // The kill escalation's signal is the only way to tell the graceful term from the SIGKILL.
+    assert.deepEqual(actionDeliverySettlementForOutcome({
+        exitCode: null,
+        signal: 'SIGKILL',
+        timedOut: true,
+        stderr: 'stalled',
+    }, 1, now), {
+        state: 'pending',
+        nextAttemptAt: now + 5_000,
+        failure: { kind: 'timeout', signal: 'SIGKILL', stderr: 'stalled' },
+    });
+    assert.equal(actionDeliverySettlementForOutcome({
+        exitCode: null,
+        signal: null,
+        timedOut: false,
+        spawnError: new Error('missing executable'),
+        stderr: '',
+    }, 1, now).state, 'pending');
+});
+test('the delivery child gets the consent boundary env, never crtrd\'s own', async () => {
+    const priorUserHome = process.env['HOME'];
+    const project = join(home, 'project');
+    mkdirSync(join(project, '.crouter'), { recursive: true });
+    writeFileSync(join(project, '.crouter', 'config.json'), JSON.stringify({ spawnEnv: { allow: ['NL_*'] } }));
+    const envDump = join(home, 'child-env.txt');
+    const stdinDump = join(home, 'child-stdin.json');
+    const script = join(home, 'action.sh');
+    writeFileSync(script, `#!/bin/sh\nenv > ${envDump}\ncat > ${stdinDump}\n`);
+    chmodSync(script, 0o755);
+    process.env['HOME'] = home; // no real user-scope config contributes to the boundary
+    process.env['NL_CORE_URL'] = 'http://core.test';
+    process.env['CRTRD_ONLY_SECRET'] = 'must-not-cross';
+    const requestId = 'b'.repeat(64);
+    try {
+        enqueueActionDelivery({
+            requestId,
+            argv: [script],
+            cwd: project,
+            completion: { schema: 'crtr.human-completion/v1', requestId, delivery: { attempt: 0 } },
+        });
+        const claimed = claimActionDelivery(requestId, Date.now(), 'claimant');
+        assert.ok(claimed !== null);
+        await deliverAction(claimed, 'claimant');
+    }
+    finally {
+        delete process.env['NL_CORE_URL'];
+        delete process.env['CRTRD_ONLY_SECRET'];
+        if (priorUserHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = priorUserHome;
+    }
+    assert.equal(readActionDelivery(requestId)?.state, 'accepted');
+    const childEnv = new Map(readFileSync(envDump, 'utf8').split('\n').flatMap((line) => {
+        const split = line.indexOf('=');
+        return split === -1 ? [] : [[line.slice(0, split), line.slice(split + 1)]];
+    }));
+    assert.equal(childEnv.get('CRTRD_ONLY_SECRET'), undefined, 'crtrd host state must not cross without consent');
+    assert.equal(childEnv.get('NL_CORE_URL'), 'http://core.test', 'the target cwd\'s spawnEnv.allow carries its own config across');
+    assert.equal(childEnv.get('CRTR_HOME'), home, 'an action that calls crtr must reach the daemon that delivered to it');
+    assert.equal(JSON.parse(readFileSync(stdinDump, 'utf8')).delivery.attempt, 1);
+});
+test('the guarded claim admits only one contender', () => {
+    const requestId = 'a'.repeat(64);
+    enqueueActionDelivery({
+        requestId,
+        argv: ['/bin/true'],
+        cwd: home,
+        completion: { schema: 'crtr.human-completion/v1', delivery: { attempt: 0 } },
+    });
+    const now = Date.now();
+    const first = claimActionDelivery(requestId, now, 'claimant-a');
+    const second = claimActionDelivery(requestId, now, 'claimant-b');
+    assert.equal(first?.state, 'running');
+    assert.equal(first?.attempt, 1);
+    assert.equal(second, null);
+    assert.deepEqual(readActionDelivery(requestId) && {
+        state: readActionDelivery(requestId).state,
+        attempt: readActionDelivery(requestId).attempt,
+        claimOwner: readActionDelivery(requestId).claimOwner,
+    }, { state: 'running', attempt: 1, claimOwner: 'claimant-a' });
+});

package/dist/core/__tests__/human-actions.test.d.ts

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

package/dist/core/__tests__/human-actions.test.js

@@ -0,0 +1,116 @@
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/human-actions.test.ts
+//
+// This pins the silent execution boundary: a request must select the nearest
+// project declaration before farther projects or user scope, and its relative
+// executable/cwd must resolve from that declaration's authoring root.
+import { after, afterEach, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveHumanAction } from '../human-actions.js';
+import { createProfile } from '../profiles/manifest.js';
+import { resetScopeCache } from '../scope.js';
+let home;
+let cwd;
+let previousHome;
+let previousProfile;
+let previousCwd;
+before(() => {
+    previousHome = process.env['HOME'];
+    previousProfile = process.env['CRTR_PROFILE_ID'];
+    previousCwd = process.cwd();
+});
+beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-actions-home-'));
+    cwd = join(home, 'work', 'outer', 'nested', 'src');
+    mkdirSync(cwd, { recursive: true });
+    process.env['HOME'] = home;
+    delete process.env['CRTR_PROFILE_ID'];
+    process.chdir(cwd);
+    resetScopeCache();
+});
+afterEach(() => {
+    process.chdir(previousCwd);
+    rmSync(home, { recursive: true, force: true });
+    resetScopeCache();
+});
+after(() => {
+    process.chdir(previousCwd);
+    if (previousHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = previousHome;
+    if (previousProfile === undefined)
+        delete process.env['CRTR_PROFILE_ID'];
+    else
+        process.env['CRTR_PROFILE_ID'] = previousProfile;
+    resetScopeCache();
+});
+function writeAction(root, relativeExecutable, relativeCwd) {
+    const executable = join(root, relativeExecutable);
+    mkdirSync(join(executable, '..'), { recursive: true });
+    writeFileSync(executable, '');
+    chmodSync(executable, 0o755);
+    mkdirSync(join(root, relativeCwd), { recursive: true });
+}
+test('nearest project declaration wins and resolves paths from its authoring root', () => {
+    const userRoot = join(home, '.crouter');
+    writeAction(userRoot, 'user-bin', 'user-cwd');
+    mkdirSync(userRoot, { recursive: true });
+    writeFileSync(join(userRoot, 'config.json'), JSON.stringify({
+        humanActions: { release: { argv: ['user-bin'], cwd: 'user-cwd' }, 'user-only': { argv: ['user-bin'], cwd: 'user-cwd' } },
+    }));
+    const outer = join(home, 'work', 'outer');
+    writeAction(outer, 'outer-bin', 'outer-cwd');
+    mkdirSync(join(outer, '.crouter'), { recursive: true });
+    writeFileSync(join(outer, '.crouter', 'config.json'), JSON.stringify({
+        humanActions: { release: { argv: ['outer-bin'], cwd: 'outer-cwd' } },
+    }));
+    const nearest = join(outer, 'nested');
+    writeAction(nearest, 'scripts/finish-release', 'work');
+    mkdirSync(join(nearest, '.crouter'), { recursive: true });
+    writeFileSync(join(nearest, '.crouter', 'config.json'), JSON.stringify({
+        humanActions: { release: { argv: ['scripts/finish-release', '--nearest'], cwd: 'work' } },
+    }));
+    resetScopeCache();
+    assert.deepEqual(resolveHumanAction('release', cwd), {
+        name: 'release',
+        configOrigin: join(nearest, '.crouter', 'config.json'),
+        argv: [join(nearest, 'scripts/finish-release'), '--nearest'],
+        cwd: join(nearest, 'work'),
+    });
+    assert.deepEqual(resolveHumanAction('user-only', cwd), {
+        name: 'user-only',
+        configOrigin: join(userRoot, 'config.json'),
+        argv: [join(userRoot, 'user-bin')],
+        cwd: join(userRoot, 'user-cwd'),
+    });
+    const profileProject = join(home, 'profile-project');
+    writeAction(profileProject, 'profile-bin', 'profile-cwd');
+    mkdirSync(join(profileProject, '.crouter'), { recursive: true });
+    writeFileSync(join(profileProject, '.crouter', 'config.json'), JSON.stringify({
+        humanActions: { 'profile-only': { argv: ['profile-bin'], cwd: 'profile-cwd' } },
+    }));
+    process.env['CRTR_PROFILE_ID'] = createProfile('human-actions-test', [{ path: profileProject, memory: 'content' }]).profileId;
+    resetScopeCache();
+    assert.deepEqual(resolveHumanAction('profile-only', cwd), { kind: 'unknown_action', name: 'profile-only' });
+});
+test('a malformed nearer humanActions block does not shadow a farther declaration', () => {
+    const outer = join(home, 'work', 'outer');
+    writeAction(outer, 'outer-bin', 'outer-cwd');
+    mkdirSync(join(outer, '.crouter'), { recursive: true });
+    writeFileSync(join(outer, '.crouter', 'config.json'), JSON.stringify({
+        humanActions: { release: { argv: ['outer-bin'], cwd: 'outer-cwd' } },
+    }));
+    const nearest = join(outer, 'nested');
+    mkdirSync(join(nearest, '.crouter'), { recursive: true });
+    writeFileSync(join(nearest, '.crouter', 'config.json'), JSON.stringify({ humanActions: [] }));
+    resetScopeCache();
+    assert.deepEqual(resolveHumanAction('release', cwd), {
+        name: 'release',
+        configOrigin: join(outer, '.crouter', 'config.json'),
+        argv: [join(outer, 'outer-bin')],
+        cwd: join(outer, 'outer-cwd'),
+    });
+});

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -14,7 +14,7 @@ import { resetScopeCache } from '../scope.js';
 import { clearSessionCache } from '../substrate/session-cache.js';
 import { memoryDir as nodeMemoryDir } from '../runtime/memory.js';
 import { buildRefInventory } from '../memory/inline-ref-inventory.js';
-import { gatewayMemoryRows } from '../runtime/broker-inventory.js';
+import { gatewayMemoryRows } from '../runtime/chat-inventory-rows.js';
 // ---------------------------------------------------------------------------
 // Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
 // backed (node/project/user scope docs on disk), since precedence dedup,

package/dist/core/__tests__/profile-project-memory-delivery.test.js

@@ -21,6 +21,7 @@ import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
 import { createProfile } from '../profiles/manifest.js';
 import { spawnNode } from '../runtime/nodes.js';
+import { memoryDir } from '../runtime/memory.js';
 import { clearSessionCache } from '../substrate/session-cache.js';
 import { renderKnowledgeBlock } from '../substrate/render-node.js';
 import { renderWorkspaceOpenDocs } from '../substrate/on-read-node.js';
@@ -37,6 +38,8 @@ const B = {
     nameFromPcontent: 'BODY-T9-NAMEDUP-FROM-PCONTENT',
     userDupFromPnone: 'BODY-T9-USERDUP-FROM-PNONE',
     userDupFromUser: 'BODY-T9-USERDUP-FROM-USER',
+    kindSplit: 'BODY-T9-KIND-SPLIT',
+    documentGateWins: 'BODY-T9-DOCUMENT-GATE-WINS',
 };
 let home;
 let canvasHome;
@@ -115,6 +118,30 @@ before(() => {
     // would otherwise beat.
     writeDoc(pnone, 't9-userdup-doc', autoDoc('When the user duplicate resolves', B.userDupFromPnone));
     writeDoc(user, 't9-userdup-doc', autoDoc('When the user duplicate resolves', B.userDupFromUser));
+    writeDoc(user, 't9-kind-split', [
+        '---',
+        'kind: knowledge',
+        'when-and-why-to-read: "When the node needs this kind-specific guide"',
+        'surfaces:',
+        '  - {on: boot, gate: {kind: {in: [design, spec, plan, developer]}}, at: content}',
+        '  - {on: boot, gate: {kind: {in: [general, review, advisor]}}, at: preview}',
+        '---',
+        '',
+        B.kindSplit,
+        '',
+    ].join('\n'));
+    writeDoc(user, 't9-document-gate-wins', [
+        '---',
+        'kind: knowledge',
+        'when-and-why-to-read: "When document eligibility is tested"',
+        'gate: {kind: {ne: developer}}',
+        'surfaces:',
+        '  - {on: boot, gate: {kind: developer}, at: content}',
+        '---',
+        '',
+        B.documentGateWins,
+        '',
+    ].join('\n'));
     // Hidden-count pair: a top-level dir always renders, so a dir holding only a
     // bootless doc shows as `<dir>/` + `[+1 more]` — unless its project is `none`.
     writeDoc(pnone, join('t9-none-hidden', 'probe'), bootlessDoc('When counted', 'HIDDEN-NONE'));
@@ -152,8 +179,8 @@ after(() => {
     restore('CRTR_PROFILE_ID', prevProfile);
     restore('CRTR_NODE_ID', prevNode);
 });
-function newNode() {
-    return spawnNode({ kind: 'general', cwd: cwdProject, parent: null, profile_id: profileId }).node_id;
+function newNode(kind = 'general') {
+    return spawnNode({ kind, cwd: cwdProject, parent: null, profile_id: profileId }).node_id;
 }
 test('boot delivery caps every profile project at its relationship, including the one used as cwd', () => {
     const boot = renderKnowledgeBlock(newNode(), new Map());
@@ -168,6 +195,46 @@ test('boot delivery caps every profile project at its relationship, including th
     assert.match(boot, /[├└]─ t9-pname-doc$/m, `the name-capped doc discloses as a bare name; got:\n${boot}`);
     assert.ok(!boot.includes('When the name project delivers'), 'a name-capped doc discloses no preview line');
 });
+test('surface-entry gates select the rung by node kind while the document gate remains absolute', () => {
+    for (const kind of ['design', 'spec', 'plan', 'developer']) {
+        const boot = renderKnowledgeBlock(newNode(kind), new Map());
+        assert.ok(boot.includes(B.kindSplit), `${kind} receives the content rung; got:\n${boot}`);
+    }
+    for (const kind of ['general', 'review', 'advisor']) {
+        const boot = renderKnowledgeBlock(newNode(kind), new Map());
+        assert.match(boot, /t9-kind-split {2}# read when: When the node needs this kind-specific guide\./, `${kind} receives the preview rung; got:\n${boot}`);
+        assert.ok(!boot.includes(B.kindSplit), `${kind} does not receive the body`);
+    }
+    for (const kind of ['explore', 'personal-assistant']) {
+        const boot = renderKnowledgeBlock(newNode(kind), new Map());
+        assert.ok(!boot.includes('t9-kind-split'), `${kind} receives no kind-split entry; got:\n${boot}`);
+        assert.ok(!boot.includes(B.kindSplit), `${kind} receives no kind-split body`);
+    }
+    const developer = renderKnowledgeBlock(newNode('developer'), new Map());
+    assert.ok(!developer.includes('t9-document-gate-wins'), `a failing document gate excludes every entry; got:\n${developer}`);
+    assert.ok(!developer.includes(B.documentGateWins), 'a failing document gate excludes its content');
+});
+test('a node-local doc floors to name only without boot entries', () => {
+    const node = newNode('explore');
+    writeDoc(memoryDir(node), 't9-node-local-bootless', bootlessDoc('When the node-local fallback applies', 'BODY-T9-NODE-LOCAL-BOOTLESS'));
+    writeDoc(memoryDir(node), 't9-node-local-entry-gated', [
+        '---',
+        'kind: knowledge',
+        'when-and-why-to-read: "When the node-local entry gates are tested"',
+        'surfaces:',
+        '  - {on: boot, gate: {kind: developer}, at: content}',
+        '  - {on: boot, gate: {kind: review}, at: preview}',
+        '---',
+        '',
+        'BODY-T9-NODE-LOCAL-ENTRY-GATED',
+        '',
+    ].join('\n'));
+    const boot = renderKnowledgeBlock(node, new Map());
+    assert.match(boot, /[├└]─ t9-node-local-bootless$/m, `a bootless node-local doc falls to name; got:\n${boot}`);
+    assert.ok(!boot.includes('BODY-T9-NODE-LOCAL-BOOTLESS'), 'the fallback discloses no body');
+    assert.ok(!boot.includes('t9-node-local-entry-gated'), `ineligible boot entries keep a node-local doc absent; got:\n${boot}`);
+    assert.ok(!boot.includes('BODY-T9-NODE-LOCAL-ENTRY-GATED'), 'ineligible boot entries disclose no body');
+});
 test('a `none` project contributes nothing to boot — no body, no name, no hidden count, no shadow', () => {
     const boot = renderKnowledgeBlock(newNode(), new Map());
     assert.ok(!boot.includes(B.pnone), 'a none-capped body must not render');
@@ -191,7 +258,7 @@ test('workspace-open clamps each project store the same way boot does', () => {
     const opened = renderWorkspaceOpenDocs(newNode(), new Map());
     assert.ok(opened.includes(B.pcontent), `the content-capped project delivers its body; got:\n${opened}`);
     assert.ok(!opened.includes(B.ppreview), `the cwd project must not deliver its body; got:\n${opened}`);
-    assert.match(opened, /name="t9-ppreview-doc"[^>]*>\nWhen the cwd project delivers\./, `the cwd project delivers its preview line; got:\n${opened}`);
+    assert.match(opened, /name="t9-ppreview-doc" readWhen="When the cwd project delivers\./, `the cwd project delivers its preview line; got:\n${opened}`);
     assert.match(opened, /name="t9-pname-doc"[^>]*\/>/, `the name-capped doc delivers name-only; got:\n${opened}`);
     assert.ok(!opened.includes('t9-pnone-doc'), 'the none-capped project delivers nothing at workspace-open');
     assert.ok(!opened.includes(B.sharedFromPnone), 'nor its side of a name collision');

package/dist/core/__tests__/prospective-inventory-capability-parity.test.d.ts

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