@north-light/crouter 0.3.220 → 0.3.222

package/dist/commands/sys/migrate.js

@@ -1,24 +1,32 @@
-// `crtr sys migrate` — the convergent-lane state-migration runner: converge
-// every writable memory store's documents to the current document format.
-// (Journaled canvas-db migrations run in the db's own ordered chain when the
-// daemon opens it; this leaf owns only the on-disk document stores.)
+// `crtr sys migrate` — the on-disk state-migration runner: converge every
+// stored profile manifest to the current manifest format, then every writable
+// memory store's documents to the current document format. (Journaled
+// canvas-db migrations run in the db's own ordered chain when the daemon opens
+// it; this leaf owns only the on-disk state.)
+//
+// Manifests come FIRST and are read as raw bytes under the profile lock: the
+// current reader treats a pre-migration manifest exactly like corrupt JSON, so
+// `listProfiles()` sees nothing until this lane has run. Store discovery below
+// therefore works from the lane's post-migration snapshots — which are equally
+// coherent under `--dry-run`, where the same fold ran and nothing was written.
 import { dirname, join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { pathExists, realpathOrSelf } from '../../core/fs-utils.js';
 import { createMemoryDocSnapshot } from '../../core/memory-resolver.js';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
 import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
-import { listProfiles, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { profileMemoryDir, profilesRoot, withProfileManifestLock } from '../../core/profiles/manifest.js';
 import { descendantStoreRootsExhaustive } from '../../core/nested-stores.js';
 import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
 import { runConvergentMigrations } from '../../migrations/convergent.js';
+import { runProfileManifestMigrations } from '../../migrations/profile-manifests.js';
 function targetKey(target) {
     return `${realpathOrSelf(target.cwd)}\u0000${target.profileId ?? ''}\u0000${target.nodeId ?? ''}`;
 }
 /** Every writable memory store — the lint corpus minus builtin (package-owned,
  *  regenerated on every install, so migrating it would fight the package).
  *  Physical stores dedupe once while retaining every owning target corpus. */
-function migratableStores() {
+function migratableStores(profiles) {
     const stores = new Map();
     const add = (dir, target) => {
         if (dir === null || dir === '' || !pathExists(dir))
@@ -49,18 +57,18 @@ function migratableStores() {
     };
     const selectedProfileId = process.env['CRTR_PROFILE_ID'] || null;
     addProjectRoots(projectScopeRoots(process.cwd(), null), selectedProfileId);
-    const profiles = listProfiles();
     const profileTargets = [];
     for (const { profileId, manifest } of profiles) {
+        const home = manifest.home !== null && manifest.home !== '' ? manifest.home : null;
         const profileTarget = {
-            cwd: manifest.home ?? manifest.projects[0] ?? process.cwd(),
+            cwd: home ?? manifest.projects[0]?.path ?? process.cwd(),
             profileId,
             nodeId: null,
         };
         profileTargets.push(profileTarget);
         add(profileMemoryDir(profileId), profileTarget);
         const roots = [
-            ...new Set(manifest.projects.flatMap((project) => [join(project, '.crouter'), ...projectScopeRoots(project, null)])),
+            ...new Set(manifest.projects.flatMap((project) => [join(project.path, '.crouter'), ...projectScopeRoots(project.path, null)])),
         ];
         addProjectRoots(roots, profileId);
     }
@@ -82,23 +90,25 @@ function migratableStores() {
 }
 export const sysMigrateLeaf = defineLeaf({
     name: 'migrate',
-    description: 'converge every writable memory store to the current document format',
-    whenToUse: 'after a crtr update whose release notes name a document-format migration, or when old-format docs resurface (a restore, a sync, a hand-authored file). Convergent and idempotent: re-running over a current corpus changes nothing, so use --dry-run first only when you want to review the rewrite.',
+    description: 'converge every profile manifest and writable memory store to the current on-disk format',
+    whenToUse: 'after a crtr update whose release notes name a state migration, when profiles stop resolving on a home that predates the update, or when old-format docs resurface (a restore, a sync, a hand-authored file). Convergent and idempotent: re-running over current state changes nothing, so use --dry-run first only when you want to review the rewrite.',
     help: {
         name: 'sys migrate',
-        summary: 'run the registered document-format migrations over every writable memory store',
+        summary: 'run the registered state migrations over every profile manifest and writable memory store',
         params: [
             { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Plan and report every rewrite without writing any file.' },
         ],
         output: [
+            { name: 'profiles', type: 'number', required: true, constraint: 'Profile manifests scanned.' },
             { name: 'stores', type: 'number', required: true, constraint: 'Memory stores scanned.' },
-            { name: 'changed', type: 'number', required: true, constraint: 'Files rewritten (or, under --dry-run, that would be).' },
-            { name: 'applied', type: 'object[]', required: true, constraint: 'One row per migration that changed files in a store: {store, migration, files}. Empty when the corpus is already current.' },
-            { name: 'skipped', type: 'object[]', required: true, constraint: 'Docs left untouched because their frontmatter is not valid YAML: {store, relPath, error}. Fix the doc, then re-run.' },
+            { name: 'changed', type: 'number', required: true, constraint: 'Files rewritten (or, under --dry-run, that would be) — manifests and documents together.' },
+            { name: 'applied', type: 'object[]', required: true, constraint: 'One row per migration that changed files: {store, lane, migration, files}, lane one of profile-manifest, convergent. Empty when the state is already current.' },
+            { name: 'skipped', type: 'object[]', required: true, constraint: 'Files left untouched because they could not be parsed — a doc whose frontmatter is not valid YAML, or a manifest that is not valid JSON: {store, relPath, error}. Fix the file, then re-run.' },
             { name: 'dryRun', type: 'boolean', required: true, constraint: 'True when nothing was written (preview only).' },
         ],
         outputKind: 'object',
         effects: [
+            'Rewrites old-format `profile.json` manifests in place (atomic, under the same per-profile lock `profile project add/remove` take). A manifest whose structure cannot be converted fails the whole run — no project setting is ever guessed.',
             'Rewrites old-format memory documents in place (atomic per-file writes) across the writable stores: every profile and every profile-owned project (plus nested descendant stores and installed plugin stores), the current project, user, and this node\'s store. Builtin docs are package-owned and never touched.',
             'Under --dry-run: read-only, writes nothing.',
         ],
@@ -107,7 +117,15 @@ export const sysMigrateLeaf = defineLeaf({
         const dryRun = input.dryRun === true;
         const applied = [];
         const skipped = [];
-        const stores = migratableStores();
+        const profilesDir = profilesRoot();
+        const profileRun = runProfileManifestMigrations(profilesDir, { dryRun, withLock: withProfileManifestLock });
+        for (const row of profileRun.applied) {
+            applied.push({ store: profilesDir, lane: 'profile-manifest', migration: row.migration, files: [row.path] });
+        }
+        for (const row of profileRun.skipped) {
+            skipped.push({ store: profilesDir, relPath: `${row.profileId}/profile.json`, error: row.error });
+        }
+        const stores = migratableStores(profileRun.snapshots);
         const snapshots = new Map();
         for (const store of stores) {
             const resolvers = store.targets.map((target) => (name) => {
@@ -137,21 +155,22 @@ export const sysMigrateLeaf = defineLeaf({
                 },
             });
             for (const row of result.applied)
-                applied.push({ store: store.dir, migration: row.migration, files: row.files });
+                applied.push({ store: store.dir, lane: 'convergent', migration: row.migration, files: row.files });
             for (const s of result.skipped)
                 skipped.push({ store: store.dir, relPath: s.relPath, error: s.error });
         }
         const changed = applied.reduce((n, row) => n + row.files.length, 0);
         return {
+            profiles: profileRun.profiles,
             stores: stores.length,
             changed,
             applied,
             skipped,
             dryRun,
             follow_up: skipped.length > 0
-                ? 'Some docs have invalid YAML frontmatter and were left untouched — fix each named file, then re-run `crtr sys migrate`.'
+                ? 'Some files could not be parsed and were left untouched — fix each named file, then re-run `crtr sys migrate`.'
                 : changed === 0
-                    ? 'Corpus already current — nothing to rewrite.'
+                    ? 'State already current — nothing to rewrite.'
                     : dryRun
                         ? 'Preview only — re-run without --dry-run to write these changes.'
                         : undefined,

package/dist/commands/sys/setup-core.js

@@ -535,7 +535,7 @@ export async function executeSetupSubmission(submission) {
                 const registered = ensureMarketplaceRegistered(marketplace);
                 if (registered !== null)
                     installedPackages.push(registered);
-                installFromMarketplace({ marketplace: marketplace, plugin: plugin }, 'user');
+                await installFromMarketplace({ marketplace: marketplace, plugin: plugin }, 'user');
                 installedPackages.push(entry.name);
             }
             catch (e) {

package/dist/commands/sys/sync-project-guidance.js

@@ -36,7 +36,7 @@ function projectDocRoots(sourceArg) {
         try {
             const { manifest } = loadProfileManifest(profileId);
             for (const p of manifest.projects) {
-                const r = resolve(p);
+                const r = resolve(p.path);
                 if (!roots.includes(r))
                     roots.push(r);
             }

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__/canvas-inbox-watcher-hold.test.js

@@ -271,7 +271,7 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         homes.push(userHome);
         process.env.HOME = userHome;
         try {
-            const profile = createProfile('paused watcher', ['/tmp']);
+            const profile = createProfile('paused watcher', [{ path: '/tmp', memory: 'content' }]);
             pauseProfile(profile.profileId);
             process.env['CRTR_PROFILE_ID'] = profile.profileId;
             const pi = makeFakePi();

package/dist/core/__tests__/fixtures/c5-command-boundary-ext.js

@@ -5,4 +5,28 @@ export default function (pi) {
             /* never invoked — isLeadingEngineCommand only checks registration */
         },
     });
+    pi.registerCommand('gatewaycmd', {
+        description: 'Gateway-advertised custom-message fixture',
+        gateway: true,
+        handler: async () => {
+            pi.sendMessage({
+                customType: 'fixture-output',
+                content: 'expanded agent input',
+                display: true,
+                details: { fixture: true },
+            });
+        },
+    });
+    pi.registerCommand('gatewaynext', {
+        description: 'Queued Gateway custom-message fixture',
+        gateway: true,
+        handler: async () => {
+            pi.sendMessage({
+                customType: 'fixture-next-output',
+                content: null,
+                display: true,
+                details: 'extension-details',
+            }, { deliverAs: 'nextTurn' });
+        },
+    });
 }

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

@@ -107,6 +107,28 @@ interface SessionTreeNode {
     entry: TreeEntry;
     children: SessionTreeNode[];
 }
+/** The real SessionManager surface the broker reads and patches. A method
+ *  missing here is a broken fixture, not a degraded one — the broker throws
+ *  during session build and never boots. */
+interface FakeSessionManager {
+    buildSessionContext: () => {
+        messages: AgentMessage[];
+        thinkingLevel: string;
+        model: null;
+    };
+    getLeafId: () => string | null;
+    getEntry: (id: string) => TreeEntry | undefined;
+    getTree: () => SessionTreeNode[];
+    getUserMessagesForForking: () => Array<{
+        entryId: string;
+        text: string;
+        timestamp?: string;
+    }>;
+    getSessionId: () => string;
+    getSessionFile: () => string;
+    getSessionDir: () => string;
+    appendCustomMessageEntry: (customType: string, content: unknown, display: boolean, details?: unknown) => string;
+}
 declare class FakeSession {
     private readonly sm;
     private readonly loader;
@@ -142,24 +164,8 @@ declare class FakeSession {
     private readonly modelRt;
     constructor(sm: SessionManager, loader: ResourceLoader | undefined, model?: FakeModel, modelRuntime?: FakeModelRuntime);
     get messages(): AgentMessage[];
-    get sessionManager(): {
-        buildSessionContext: () => {
-            messages: AgentMessage[];
-            thinkingLevel: string;
-            model: null;
-        };
-        getLeafId: () => string | null;
-        getEntry: (id: string) => TreeEntry | undefined;
-        getTree: () => SessionTreeNode[];
-        getUserMessagesForForking: () => Array<{
-            entryId: string;
-            text: string;
-            timestamp?: string;
-        }>;
-        getSessionId: () => string;
-        getSessionFile: () => string;
-        getSessionDir: () => string;
-    };
+    private smFacade;
+    get sessionManager(): FakeSessionManager;
     get sessionId(): string;
     get sessionFile(): string | undefined;
     get model(): FakeModel | undefined;

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

@@ -341,8 +341,13 @@ class FakeSession {
     // truth, since `session.messages` can be sliced by pi's retry/overflow/
     // compaction recovery. Mirror that surface so the fake's snapshot still serves
     // the accrued history (G2/G3). The fake's persisted analog is the active branch.
+    // Built once and cached: the real SessionManager is a single object the
+    // broker's advertised-command contract monkey-patches
+    // (appendCustomMessageEntry), so a fresh literal per access would silently
+    // discard that patch.
+    smFacade;
     get sessionManager() {
-        return {
+        this.smFacade ??= {
             buildSessionContext: () => this.tree.buildSessionContext(),
             getLeafId: () => this.tree.getLeafId(),
             getEntry: (id) => this.tree.getEntry(id),
@@ -351,7 +356,9 @@ class FakeSession {
             getSessionId: () => this.sm.getSessionId(),
             getSessionFile: () => this.sm.getSessionFile(),
             getSessionDir: () => this.sm.getSessionDir(),
+            appendCustomMessageEntry: (customType, content, display, details) => this.tree.append({ role: 'custom', customType, content, display, details }).id,
         };
+        return this.smFacade;
     }
     get sessionId() {
         return this.sm.getSessionId();

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'),
+    });
+});