@north-light/crouter 0.3.234 → 0.3.236

package/dist/commands/node/subscription.js

@@ -69,6 +69,10 @@ export const nodeSubscription = defineBranch({
     name: 'subscription',
     description: 'manage push-delivery edges between nodes',
     whenToUse: 'you need an ongoing active or passive subscriber-to-publisher delivery edge that spawn did not create, or need to remove one',
-    help: { name: 'node subscription', summary: 'add or remove subscriber-to-publisher push-delivery edges' },
+    help: {
+        name: 'node subscription',
+        summary: 'add or remove subscriber-to-publisher push-delivery edges',
+        model: 'Subscriptions point from a subscriber to a publisher and control future push delivery. Active edges wake on each push; passive edges accumulate pushes for the subscriber’s next turn. Removing either edge stops subsequent delivery without changing messages already received.',
+    },
     children: [nodeSubscribe, nodeUnsubscribe],
 });

package/dist/commands/node/wait.js

@@ -154,6 +154,10 @@ export const nodeWaitBranch = defineBranch({
     name: 'wait',
     description: 'declare a durable controller or deadline wait',
     whenToUse: 'a terminal node must dorm for one named controller, or race its inbox against a self-scheduled deadline',
-    help: { name: 'node wait', summary: 'declare durable wait state; choose the event that settles it' },
+    help: {
+        name: 'node wait',
+        summary: 'declare durable wait state; choose the event that settles it',
+        model: 'Both waits belong to the calling terminal node and settle on one future event. A controller wait records an existing node as the wake source; a deadline wait arms an urgent one-shot cron that races any earlier inbox delivery and is canceled when that delivery wins.',
+    },
     children: [nodeWait, nodeWaitDeadline],
 });

package/dist/commands/pkg/plugin-manage.js

@@ -791,7 +791,7 @@ export const pluginRemove = defineLeaf({
         summary: 'remove a plugin and its directory from the given scope',
         params: [
             { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Plugin name to remove.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: searches all scopes.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: searches every scope.' },
         ],
         output: [
             { name: 'scopes', type: 'string[]', required: true, constraint: 'Scopes the plugin was removed from.' },

package/dist/commands/pkg.js

@@ -14,6 +14,7 @@ export function registerPkg() {
         help: {
             name: 'pkg',
             summary: 'manage plugins and marketplace sources',
+            model: 'Marketplaces are configured source catalogs; plugins are installed extensions resolved from those catalogs or direct HTTP endpoints. Browsing searches the configured catalogs without changing source or install state.',
         },
         children: [pkgBrowseLeaf, pluginBranch, marketBranch],
     });

package/dist/commands/profile/rename.js

@@ -3,7 +3,7 @@ import { resolveProfileOperand, renameProfile } from '../../core/profiles/manife
 export const renameLeaf = defineLeaf({
     name: 'rename',
     description: "change a profile's display name",
-    whenToUse: "you want to change a profile's display name — the gateable `profile` subject value and the name shown in bearings/listings. The profile id (its directory) never changes.",
+    whenToUse: "you want the profile to appear under a new name in bearings, listings, and `profile` subject gates. The profile id (its directory) never changes.",
     help: {
         name: 'profile rename',
         summary: "change a profile's manifest `name` only — the profile_id is stable and never changes",

package/dist/commands/sys/config.js

@@ -257,6 +257,7 @@ export const configBranch = defineBranch({
     help: {
         name: 'sys config',
         summary: 'read and write crtr configuration, including model ladders; edit humanActions maps directly in ~/.crouter/config.json or <repo>/.crouter/config.json',
+        model: 'Configuration resolves through ordered scopes. Reads can resolve the effective value, writes target one writable scope, and path inspection reveals the backing files without reading values.',
     },
     children: [configGet, configSet, configPath],
 });

package/dist/commands/sys.js

@@ -24,6 +24,7 @@ export function registerSys() {
         help: {
             name: 'sys',
             summary: 'crtr system configuration, settings, diagnostics, and self-management',
+            model: 'Configuration and settings own durable behavior; diagnostics and support observe it. Setup, migration, sync, and update change installed or generated state, while daemon control owns the supervisor lifecycle.',
         },
         children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysMigrateLeaf, sysSyncBranch, daemonBranch],
     });

package/dist/core/__tests__/canvas-inbox-watcher-naming.test.d.ts

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

package/dist/core/__tests__/canvas-inbox-watcher-naming.test.js

@@ -0,0 +1,258 @@
+// Tests for the naming/goal-capture gap on the durable-inbox delivery path.
+//
+// Run with: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/canvas-inbox-watcher-naming.test.ts
+//
+// A cold-booting child's first message falls to the durable inbox and pi's
+// `input` event never fires for it, so canvas-goal-capture's first-message
+// hooks (naming, goal capture) never run for it. The inbox watcher now mirrors
+// both on its own `kind: 'human'` visible delivery. This pins that mirror:
+// a human delivery reaches the naming pipeline and captures the goal, a
+// card/envelope delivery touches neither, and an already-described node's
+// naming call still fetches state (the daemon owns the compare-and-set) but
+// never issues a commit.
+//
+// The naming attempt is observed at the daemon socket exactly as in
+// canvas-goal-capture-envelope.test.ts: generateAndCommitInitialName starts by
+// asking crtrd for the node's projection (GET .../broker/extension-state), so
+// a request for a node id is proof the pipeline ran for it. An unnamed node's
+// GET is answered with an error — same as that file — so the test never
+// reaches the real headless model call; a "described" node's GET succeeds with
+// a non-empty description, which is enough to prove the guard short-circuits
+// before any commit (POST .../broker/generated-name) is sent.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
+import { createNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { apiSocketPath } from '../canvas/paths.js';
+import { appendInbox } from '../feed/inbox.js';
+const TICK_MS = 20;
+const DEBOUNCE_MS = 25;
+let home;
+let socket;
+const getRequests = [];
+const postRequests = [];
+/** node_id -> description the stub answers `extension-state` with. Absent =
+ *  the GET errors (mirrors canvas-goal-capture-envelope.test.ts: proof of
+ *  attempt without a real model call). Present (even '') = the GET succeeds. */
+const descriptions = new Map();
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+function initialPromptPath(id) {
+    return join(home, 'nodes', id, 'context', 'initial-prompt.md');
+}
+function respond(connection, status, body) {
+    const json = JSON.stringify(body);
+    connection.end(`HTTP/1.1 ${status}\r\n`
+        + 'Content-Type: application/json\r\n'
+        + `Content-Length: ${Buffer.byteLength(json)}\r\n`
+        + 'Connection: close\r\n\r\n'
+        + json);
+}
+function nodeIdFromPath(path) {
+    return path.split('/nodes/')[1]?.split('/')[0] ?? '';
+}
+/** Every node's watcher fetches `extension-state` ONCE at session_start (to
+ *  seed report-node names for card rendering) regardless of what it later
+ *  delivers, so a bare presence check can't tell a startup fetch from a
+ *  naming-triggered one. Naming issues a SECOND, independent fetch for the
+ *  same node id — count occurrences instead of checking presence. */
+function getRequestCount(nodeId) {
+    return getRequests.filter((line) => line.includes(`/nodes/${nodeId}/`)).length;
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        sentMessages: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        sendMessage(message) { this.sentMessages.push(message); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitFor(predicate, timeoutMs = 3000, stepMs = 10) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (predicate())
+            return;
+        await wait(stepMs);
+    }
+}
+const disposers = [];
+function registerWatcher(pi) {
+    const dispose = registerCanvasInboxWatcher(pi);
+    pi.fire('session_start', { type: 'session_start' }, undefined);
+    return dispose;
+}
+/** Point CRTR_HOME/CRTR_NODE_ID at this node and make sure it exists in canvas.db. */
+function freshNode(id) {
+    process.env['CRTR_NODE_ID'] = id;
+    createNode(node(id));
+}
+let origHome;
+let origNode;
+let origTick;
+let origDebounce;
+before(async () => {
+    origHome = process.env['CRTR_HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+    origTick = process.env['CRTR_WATCHER_TICK_MS'];
+    origDebounce = process.env['CRTR_WATCHER_DEBOUNCE_MS'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-inbox-naming-'));
+    mkdirSync(join(home, 'nodes'), { recursive: true });
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_WATCHER_TICK_MS'] = String(TICK_MS);
+    process.env['CRTR_WATCHER_DEBOUNCE_MS'] = String(DEBOUNCE_MS);
+    socket = createServer((connection) => {
+        connection.on('data', (chunk) => {
+            const raw = chunk.toString('utf8');
+            const requestLine = raw.split('\r\n')[0] ?? '';
+            const [method, path] = requestLine.split(' ');
+            if (method === 'GET' && path?.includes('/broker/extension-state')) {
+                getRequests.push(raw);
+                const nodeId = nodeIdFromPath(path);
+                if (!descriptions.has(nodeId)) {
+                    respond(connection, '500 Internal Server Error', { error: { code: 'internal', message: 'stub daemon' } });
+                    return;
+                }
+                respond(connection, '200 OK', {
+                    node: {
+                        node_id: nodeId, name: nodeId, description: descriptions.get(nodeId), kind: 'general',
+                        mode: 'base', lifecycle: 'terminal', status: 'active', cwd: '/tmp/work',
+                        parent: null, fork_from: null, profile_id: null, intent: null, created: new Date().toISOString(),
+                    },
+                    warm_spare: false, ancestors: [], children: [], fork_source: null,
+                    subject: { kind: 'general', mode: 'base', lifecycle: 'terminal', hasManager: false, cwd: '/tmp/work', scope: 'project', orchestration: { depth: 0 }, profile: null },
+                    report_nodes: [],
+                });
+                return;
+            }
+            if (method === 'POST' && path?.includes('/broker/generated-name')) {
+                postRequests.push(raw);
+                respond(connection, '200 OK', { applied: false });
+                return;
+            }
+            // Everything else (e.g. advanceBrokerInboxCursor) — a harmless error is
+            // fine: the watcher retries cursor commits later and never blocks
+            // visible delivery on them.
+            respond(connection, '500 Internal Server Error', { error: { code: 'internal', message: 'stub daemon' } });
+        });
+    });
+    await new Promise((resolve) => socket.listen(apiSocketPath(), resolve));
+});
+afterEach(() => {
+    while (disposers.length > 0)
+        disposers.pop()();
+});
+after(async () => {
+    closeDb();
+    await new Promise((resolve) => socket.close(() => resolve()));
+    rmSync(home, { recursive: true, force: true });
+    if (origHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = origHome;
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    if (origTick === undefined)
+        delete process.env['CRTR_WATCHER_TICK_MS'];
+    else
+        process.env['CRTR_WATCHER_TICK_MS'] = origTick;
+    if (origDebounce === undefined)
+        delete process.env['CRTR_WATCHER_DEBOUNCE_MS'];
+    else
+        process.env['CRTR_WATCHER_DEBOUNCE_MS'] = origDebounce;
+});
+test('an inbox-delivered human first message reaches the naming pipeline and captures the goal', async () => {
+    freshNode('inbox-human-unnamed');
+    const pi = makeFakePi();
+    disposers.push(registerWatcher(pi));
+    await wait(TICK_MS + 100);
+    appendInbox('inbox-human-unnamed', {
+        from: 'human',
+        tier: 'normal',
+        kind: 'message',
+        label: 'build me a receipt tracker',
+        data: { body: 'build me a receipt tracker' },
+    });
+    await waitFor(() => pi.injected.length >= 1);
+    assert.equal(pi.injected[0].content, 'build me a receipt tracker', 'the human body still rides the visible digest verbatim');
+    // One GET at session_start (report-node seed) plus one from the naming
+    // pipeline (generateAndCommitInitialName's own state fetch) = 2.
+    await waitFor(() => getRequestCount('inbox-human-unnamed') >= 2);
+    assert.equal(getRequestCount('inbox-human-unnamed'), 2, 'an inbox-delivered human message reaches the same naming pipeline a live message does');
+    assert.equal(readFileSync(initialPromptPath('inbox-human-unnamed'), 'utf8').trim(), 'build me a receipt tracker', 'an inbox-delivered first message is also captured as the goal, for fresh-revive recovery');
+});
+test('a card/envelope delivery never reaches naming or goal capture', async () => {
+    freshNode('inbox-card-only');
+    const pi = makeFakePi();
+    const dispose = registerWatcher(pi);
+    await wait(TICK_MS + 100);
+    appendInbox('inbox-card-only', { from: 'child-9', tier: 'normal', kind: 'update', label: 'phase one done' });
+    await waitFor(() => pi.injected.length >= 1, 3000);
+    assert.equal(pi.injected.length, 1, 'the card still reaches the digest as a visible send');
+    dispose(); // release ownership of this node id before a second watcher binds a new one
+    // Clock: a human message to a DIFFERENT node whose naming pipeline we know
+    // fires (proven above). Once its GET lands, the card node's window to fire
+    // its own GET has already passed — the watcher fires naming synchronously
+    // off the same delivery cycle, not on a later timer.
+    freshNode('inbox-card-clock');
+    const clockPi = makeFakePi();
+    disposers.push(registerWatcher(clockPi));
+    await wait(TICK_MS + 100);
+    appendInbox('inbox-card-clock', { from: 'human', tier: 'normal', kind: 'message', label: 'clock', data: { body: 'clock' } });
+    await waitFor(() => getRequests.some((line) => line.includes('inbox-card-clock')));
+    // Exactly the one startup GET (report-node seed) — no second, naming-triggered fetch.
+    assert.equal(getRequestCount('inbox-card-only'), 1, 'a card/envelope delivery never asks the naming pipeline to name the node');
+    assert.equal(existsSync(initialPromptPath('inbox-card-only')), false, 'a card/envelope delivery never seeds a goal file either');
+});
+test('an already-described node fetches state but never commits a new name', async () => {
+    descriptions.set('inbox-already-named', 'existing-description');
+    freshNode('inbox-already-named');
+    const pi = makeFakePi();
+    const dispose = registerWatcher(pi);
+    await wait(TICK_MS + 100);
+    appendInbox('inbox-already-named', {
+        from: 'human',
+        tier: 'normal',
+        kind: 'message',
+        label: 'second thing to do',
+        data: { body: 'second thing to do' },
+    });
+    await waitFor(() => pi.injected.length >= 1);
+    // One GET at session_start plus one from the naming pipeline's own state
+    // fetch: the guard is checked AFTER this fetch resolves, not before it.
+    await waitFor(() => getRequestCount('inbox-already-named') >= 2);
+    assert.equal(getRequestCount('inbox-already-named'), 2, 'the naming pipeline still asks the daemon for the current projection');
+    dispose(); // release ownership of this node id before a second watcher binds a new one
+    // Clock: a second node's naming pipeline fires synchronously off the same
+    // delivery cycle (proven in the first test above). Once its GET has landed,
+    // this node's guard — checked in the very same .then() before any commit
+    // call — has already resolved one way or the other.
+    freshNode('inbox-commit-clock');
+    const clockPi = makeFakePi();
+    disposers.push(registerWatcher(clockPi));
+    await wait(TICK_MS + 100);
+    appendInbox('inbox-commit-clock', { from: 'human', tier: 'normal', kind: 'message', label: 'clock', data: { body: 'clock' } });
+    await waitFor(() => getRequests.some((line) => line.includes('inbox-commit-clock')));
+    await wait(DEBOUNCE_MS + 100);
+    assert.equal(postRequests.some((line) => line.includes('inbox-already-named')), false, 'an already-described node is untouched: the guard short-circuits before any generated-name commit');
+});

package/dist/core/__tests__/cli-help-contract.test.d.ts

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

package/dist/core/__tests__/cli-help-contract.test.js

@@ -0,0 +1,150 @@
+// Help-contract gate for the whole command tree.
+// Run with: node --import tsx/esm --test src/core/__tests__/cli-help-contract.test.ts
+//
+// The cli-design rules that hold for every node are enforced here rather than
+// per command, because help text is written one command at a time and drifts
+// the same way every time: a branch ships its selection prose in the
+// description attribute, a rubric restates the description it sits beside, or
+// a constraint copied from a sibling leaf keeps naming a value this leaf's
+// enum rejects. Each rule below is mechanical — a judgment call about whether
+// a rubric actually helps an agent choose belongs to review, not to this file.
+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 { resetScopeCache } from '../scope.js';
+// buildRoot() composes external command-plugin branches from the effective
+// enabled plugins. Pin HOME to an isolated no-plugin home: a third party's
+// help text is not this repo's contract to enforce.
+let home;
+let realHome;
+let realProfile;
+before(() => {
+    realHome = process.env['HOME'];
+    realProfile = process.env['CRTR_PROFILE_ID'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-help-contract-'));
+    delete process.env['CRTR_PROFILE_ID'];
+    process.env['HOME'] = home;
+    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();
+});
+async function everyNode() {
+    const root = await buildRoot();
+    const out = [];
+    const visit = (node, path) => {
+        out.push({ node, path });
+        if (node.kind === 'branch')
+            for (const child of node.children)
+                visit(child, `${path} ${child.name}`);
+    };
+    for (const subtree of root.subtrees)
+        visit(subtree, subtree.name);
+    return out;
+}
+function normalize(text) {
+    if (text === undefined)
+        return '';
+    return text.toLowerCase().replace(/\s+/g, ' ').replace(/[.\s]+$/, '').trim();
+}
+function enumFlags(leaf) {
+    return (leaf.help.params ?? []).filter((param) => param.kind === 'flag' && param.type === 'enum' && param.choices !== undefined);
+}
+test('every branch offering a choice carries the model prose that frames it', async () => {
+    const offenders = [];
+    for (const { node, path } of await everyNode()) {
+        if (node.kind !== 'branch')
+            continue;
+        const choices = node.children.filter((child) => child.tier !== 'hidden');
+        if (choices.length < 2)
+            continue;
+        const model = node.help.model;
+        if (model === undefined || model.trim() === '')
+            offenders.push(`${path} (${choices.length} children)`);
+    }
+    assert.deepEqual(offenders, [], `branches with 2+ visible children and no help.model:\n  ${offenders.join('\n  ')}`);
+});
+test('no rubric restates the description it is read beside', async () => {
+    const offenders = [];
+    for (const { node, path } of await everyNode()) {
+        const description = normalize(node.description ?? '');
+        const rubric = normalize(node.whenToUse ?? '');
+        if (description === '' || rubric === '')
+            continue;
+        if (rubric === description || rubric.includes(description))
+            offenders.push(`${path}: whenToUse repeats "${node.description}"`);
+    }
+    assert.deepEqual(offenders, [], `rubrics restating their own description:\n  ${offenders.join('\n  ')}`);
+});
+// A constraint may name a value its own enum rejects only while saying so —
+// the copy-paste failure this catches states the foreign value as if it were
+// selectable. Vocabulary is per flag NAME, so it only fires where one flag
+// genuinely carries different choices on different leaves.
+const NEGATION = /\b(?:reject\w*|refus\w*|invalid|unsupported|forbid\w*|not\s+accepted)\b/i;
+test('no enum constraint names a value that enum does not accept', async () => {
+    const offenders = [];
+    for (const { node, path } of await everyNode()) {
+        if (node.kind !== 'branch')
+            continue;
+        const leaves = node.children.filter((child) => child.kind === 'leaf');
+        // Vocabulary is pooled across ONE branch's leaves, because that is where a
+        // constraint gets copied: two sibling verbs carrying the same flag with
+        // different choices. Pooling tree-wide would compare unrelated commands
+        // that merely share a flag name and flag ordinary English words that
+        // happen to be some distant enum's value.
+        const vocabulary = new Map();
+        for (const leaf of leaves) {
+            for (const flag of enumFlags(leaf)) {
+                const known = vocabulary.get(flag.name) ?? new Set();
+                for (const choice of flag.choices)
+                    known.add(choice.toLowerCase());
+                vocabulary.set(flag.name, known);
+            }
+        }
+        for (const leaf of leaves) {
+            for (const flag of enumFlags(leaf)) {
+                const own = new Set(flag.choices.map((choice) => choice.toLowerCase()));
+                const foreign = [...(vocabulary.get(flag.name) ?? [])].filter((value) => !own.has(value));
+                if (foreign.length === 0)
+                    continue;
+                for (const sentence of flag.constraint.split(/(?<=[.;:])\s+/)) {
+                    if (NEGATION.test(sentence))
+                        continue;
+                    const named = foreign.filter((value) => new RegExp(`\\b${value}\\b`, 'i').test(sentence));
+                    if (named.length > 0)
+                        offenders.push(`${path} ${leaf.name} --${flag.name}: names ${named.join(', ')} — accepts only ${flag.choices.join(', ')}`);
+                }
+            }
+        }
+    }
+    assert.deepEqual(offenders, [], `enum constraints naming values they reject:\n  ${offenders.join('\n  ')}`);
+});
+test('every leaf declares its effects, and none contradicts a claim of none', async () => {
+    const offenders = [];
+    for (const { node, path } of await everyNode()) {
+        if (node.kind !== 'leaf')
+            continue;
+        const effects = node.help.effects;
+        if (effects.length === 0 || effects.some((effect) => effect.trim() === '')) {
+            offenders.push(`${path}: declares no effects`);
+            continue;
+        }
+        // A leaf may describe what read-only means for it — several usefully do.
+        // What it may not do is open with "None" and then list effects underneath:
+        // an agent reading the first entry stops there.
+        if (effects.length > 1 && /^none\b/i.test(effects[0].trim())) {
+            offenders.push(`${path}: claims "${effects[0]}" and then lists ${effects.length - 1} more effect(s)`);
+        }
+    }
+    assert.deepEqual(offenders, [], `leaves with a broken effects declaration:\n  ${offenders.join('\n  ')}`);
+});

package/dist/core/__tests__/helpers/harness.js

@@ -505,6 +505,7 @@ export async function createHarness(opts = {}) {
                 prompt: task,
                 parent: parentId,
                 ...(o.mode !== undefined ? { mode: o.mode } : {}),
+                ...(o.lifecycle !== undefined ? { rootLifecycle: o.lifecycle } : {}),
                 ...(o.model !== undefined ? { model: o.model } : {}),
             });
             await harness.awaitBoot(result.node.node_id);

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

@@ -641,6 +641,27 @@ process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { ap
         }
         assertNotExecuted();
     });
+    test('a colliding exec plugin keeps its manifest path for help and execution', async () => {
+        installPlugin(userRoot, 'p-one', { exec: FIXTURE_EXEC });
+        installPlugin(userRoot, 'p-two', { exec: FIXTURE_EXEC, sourceMarketplace: 'fixture-market' });
+        resetScopeCache();
+        const snapshot = discoverCommandContributions(new Set(['sys']), emptyStart);
+        const external = composeExternalSubtrees(adaptPluginContributions(snapshot.contributions));
+        const mounted = external.find((branch) => branch.name === 'fixture-market:app');
+        assert.ok(mounted, 'the marketplace-qualified plugin branch is mounted');
+        assert.match(renderBranch(mounted.help), /<command name="fixture-market:app"/);
+        const leaf = leafOf(mounted, 'show');
+        const log = join(emptyStart, 'collision-request.json');
+        process.env['FIXTURE_REQUEST_LOG'] = log;
+        try {
+            const result = await leaf.run({ appId: 'app_123', mode: 'ok' });
+            assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
+            assert.deepEqual(JSON.parse(readFileSync(log, 'utf8')).command, ['app', 'show']);
+        }
+        finally {
+            delete process.env['FIXTURE_REQUEST_LOG'];
+        }
+    });
 });
 // Memory-corpus gate across the plugin lifecycle — install, and enable of a
 // package installed while disabled, both converge the candidate's memory store

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -22,7 +22,7 @@ import assert from 'node:assert/strict';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { appendInbox, readCursor, readInboxSince } from '../../feed/inbox.js';
-import { registerWarmSpare, subscribe, updateNode } from '../../canvas/index.js';
+import { registerWarmSpare, subscribe, subscriptionsOf, updateNode } from '../../canvas/index.js';
 import { isPidAlive } from '../../canvas/pid.js';
 import { reviveNode } from '../../runtime/revive.js';
 import { createHarness } from '../helpers/harness.js';
@@ -349,6 +349,75 @@ test('the unattended park clock cancels an obligation-free terminal node and spa
             process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
     }
 });
+test('a resident managed child parks without finalizing while a terminal child is settled by the same grace sweep', { timeout: 40_000 }, async () => {
+    const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+    const priorGraceMs = process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
+    process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';
+    process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = '1000';
+    try {
+        const resident = h.fabricateBrokerNode({
+            id: 'resident-managed-child',
+            parent: root,
+            lifecycle: 'resident',
+            status: 'idle',
+            intent: 'idle-release',
+            pi_session_id: 'resident-managed-session',
+        });
+        subscribe(root, resident, true);
+        // Keep a managed terminal child in the same sweep, but make its parent
+        // historical so no live subscriber remains to hold an unfinished report.
+        const terminalManager = h.fabricateBrokerNode({ id: 'terminal-manager', status: 'done' });
+        const terminal = h.fabricateBrokerNode({
+            id: 'terminal-managed-child',
+            parent: terminalManager,
+            lifecycle: 'terminal',
+            status: 'idle',
+            intent: 'idle-release',
+            pi_session_id: 'terminal-managed-session',
+        });
+        subscribe(terminalManager, terminal, true);
+        const boot = async (id) => {
+            updateNode(id, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
+            reviveNode(id, { resume: true });
+            return (await h.awaitBoot(id)).pid;
+        };
+        const residentPid = await boot(resident);
+        const terminalPid = await boot(terminal);
+        const seenAt = 50_000;
+        await h.tick(seenAt);
+        // Clock expiry arms the resident's pending park and requests its summary
+        // turn; the terminal child is cancelled outright by the same pass.
+        await h.tick(seenAt + 1500);
+        // Summary grace expiry: the degraded enactment parks without a report.
+        await h.tick(seenAt + 1500 + 1000);
+        await h.waitFor(() => h.node(resident)?.status === 'done' && h.node(resident)?.intent === 'parked' && !isPidAlive(residentPid), {
+            timeoutMs: 10_000,
+            intervalMs: 20,
+            label: 'resident managed child parks and releases its broker',
+        });
+        await h.waitFor(() => h.node(terminal)?.status === 'canceled' && !isPidAlive(terminalPid), {
+            timeoutMs: 10_000,
+            intervalMs: 20,
+            label: 'terminal managed child settles and releases its broker',
+        });
+        await h.awaitFleetExit(resident);
+        await h.awaitFleetExit(terminal);
+        assert.equal(h.node(resident)?.intent, 'parked', 'resident child carries the durable park marker, not a final');
+        assert.equal(h.node(resident)?.final_report ?? null, null, 'resident child has no forced final report');
+        assert.ok(subscriptionsOf(root).some((edge) => edge.node_id === resident && edge.active), 'resident child keeps its active parent subscription');
+        assert.equal(h.node(terminal)?.status, 'canceled', 'terminal child is settled by unattended grace without a final');
+    }
+    finally {
+        if (priorParkMs === undefined)
+            delete process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+        else
+            process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
+        if (priorGraceMs === undefined)
+            delete process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
+        else
+            process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = priorGraceMs;
+    }
+});
 test('an unattended resident awaiting a live child remains wakeable', { timeout: 30_000 }, async () => {
     const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
     process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';