@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/__tests__/argv-parser.test.js

@@ -101,6 +101,24 @@ describe('parseArgv: positional', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// parseArgv — stdin satisfied by a positional argument
+// ---------------------------------------------------------------------------
+describe('parseArgv: stdin-as-positional', () => {
+    const params = [
+        { kind: 'stdin', name: 'prompt', required: true, constraint: 'Task.' },
+        { kind: 'flag', name: 'agent', type: 'string', required: false, default: 'general', constraint: '' },
+    ];
+    test('a positional token satisfies a stdin param', async () => {
+        const result = await parseArgv(params, ['--agent', 'general', 'Say hi']);
+        assert.equal(result['prompt'], 'Say hi');
+        assert.equal(result['agent'], 'general');
+    });
+    test('positional-as-stdin works with the positional before flags', async () => {
+        const result = await parseArgv(params, ['Say hi', '--agent', 'general']);
+        assert.equal(result['prompt'], 'Say hi');
+    });
+});
+// ---------------------------------------------------------------------------
 // parseArgv — context-file
 // ---------------------------------------------------------------------------
 describe('parseArgv: context-file', () => {
@@ -167,7 +185,7 @@ describe('renderLeafArgv: help format', () => {
     });
     test('contains Output section', () => {
         const out = renderLeafArgv(help);
-        assert.ok(out.includes('Output (stdout, JSON)'));
+        assert.ok(out.includes('Output (fields carried in the rendered result)'));
     });
     test('contains Effects section', () => {
         const out = renderLeafArgv(help);

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

@@ -0,0 +1,100 @@
+// Tests for the canvas-node inbox watcher pi extension.
+//
+// Run with: node --import tsx/esm --test src/core/__tests__/canvas-inbox-watcher.test.ts
+//
+// Focus: a finished node (push final → InboxEntry kind 'final') must STEER a
+// mid-stream subscriber, not queue behind its current turn as a follow-up.
+import { test, describe, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
+import { appendInbox } from '../feed/inbox.js';
+// Mirror the watcher's internal cadence (TICK_MS=800, DEBOUNCE_MS=1000): allow a
+// resolve+seed tick, a read tick, and the debounce window before asserting.
+const TICK_MS = 800;
+const DEBOUNCE_MS = 1000;
+const SETTLE_MS = TICK_MS * 2 + DEBOUNCE_MS + 500;
+let origHome;
+let origNode;
+const homes = [];
+const disposers = [];
+/** Point CRTR_HOME at a fresh temp canvas root and bind CRTR_NODE_ID. */
+function freshNode(nodeId) {
+    const home = join(tmpdir(), `crtr-canvas-watcher-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(home, { recursive: true });
+    homes.push(home);
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_NODE_ID'] = nodeId;
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+before(() => {
+    origHome = process.env['CRTR_HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+});
+afterEach(() => {
+    while (disposers.length > 0)
+        disposers.pop()();
+});
+after(() => {
+    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;
+    for (const h of homes) {
+        try {
+            rmSync(h, { recursive: true, force: true });
+        }
+        catch { /* noop */ }
+    }
+});
+describe('canvas inbox watcher — finished-node delivery', () => {
+    test('mid-stream: a finished node (kind final) steers the subscriber', async () => {
+        freshNode('node-final');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // Subscriber is actively streaming when the worker finishes.
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-final', { from: 'child-1', tier: 'normal', kind: 'final', label: 'all done' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1, 'one coalesced injection');
+        assert.equal(pi.injected[0].deliverAs, 'steer', 'a finished node steers, not follows up');
+    });
+    test('mid-stream: a routine update still follows up', async () => {
+        freshNode('node-update');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-update', { from: 'child-2', tier: 'normal', kind: 'update', label: 'still working' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1);
+        assert.equal(pi.injected[0].deliverAs, 'followUp', 'a normal update is not urgent → followUp');
+    });
+    test('idle: a finished node triggers a fresh turn (no deliverAs)', async () => {
+        freshNode('node-idle');
+        const pi = makeFakePi();
+        disposers.push(registerCanvasInboxWatcher(pi));
+        // No agent_start fired → watcher treats the node as idle.
+        await wait(TICK_MS + 100);
+        appendInbox('node-idle', { from: 'child-3', tier: 'normal', kind: 'final', label: 'done while idle' });
+        await wait(SETTLE_MS);
+        assert.equal(pi.injected.length, 1);
+        assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
+    });
+});

package/dist/core/__tests__/canvas.test.js

@@ -0,0 +1,154 @@
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, getRow, updateNode, setStatus, listNodes, subscribe, unsubscribe, setSubscriptionActive, recordSpawn, subscribersOf, subscriptionsOf, view, hasActiveLiveSubscription, rebuildIndex, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { contextDir, reportsDir, jobDir, nodeMetaPath, } from '../canvas/paths.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-canvas-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    // Fresh db + dirs per test for isolation.
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('createNode scaffolds dirs, writes meta, indexes the row', () => {
+    createNode(node('a'));
+    assert.ok(existsSync(contextDir('a')));
+    assert.ok(existsSync(reportsDir('a')));
+    assert.ok(existsSync(jobDir('a')));
+    assert.ok(existsSync(nodeMetaPath('a')));
+    const meta = getNode('a');
+    assert.equal(meta?.node_id, 'a');
+    assert.equal(meta?.kind, 'general');
+    const row = getRow('a');
+    assert.equal(row?.node_id, 'a');
+    assert.equal(row?.status, 'active');
+});
+test('meta.json is the source of truth on disk', () => {
+    createNode(node('a', { kind: 'developer' }));
+    const raw = JSON.parse(readFileSync(nodeMetaPath('a'), 'utf8'));
+    assert.equal(raw.kind, 'developer');
+});
+test('updateNode merges meta and re-indexes the row', () => {
+    createNode(node('a'));
+    updateNode('a', { mode: 'orchestrator', lifecycle: 'resident' });
+    assert.equal(getNode('a')?.mode, 'orchestrator');
+    assert.equal(getRow('a')?.lifecycle, 'resident');
+    // unspecified fields preserved
+    assert.equal(getNode('a')?.kind, 'general');
+});
+test('setStatus updates both meta and row', () => {
+    createNode(node('a'));
+    setStatus('a', 'done');
+    assert.equal(getNode('a')?.status, 'done');
+    assert.equal(getRow('a')?.status, 'done');
+});
+test('listNodes filters by status', () => {
+    createNode(node('a', { status: 'active' }));
+    createNode(node('b', { status: 'idle' }));
+    createNode(node('c', { status: 'done' }));
+    assert.equal(listNodes().length, 3);
+    assert.deepEqual(listNodes({ status: ['active', 'idle'] }).map((n) => n.node_id).sort(), ['a', 'b']);
+});
+test('subscription spine: subscribersOf / subscriptionsOf', () => {
+    createNode(node('mgr'));
+    createNode(node('w1'));
+    createNode(node('w2'));
+    // mgr subscribes to both workers (parent watches children)
+    subscribe('mgr', 'w1');
+    subscribe('mgr', 'w2', false);
+    // w1's subscribers = who a w1 push fans out to = mgr
+    assert.deepEqual(subscribersOf('w1').map((s) => s.node_id), ['mgr']);
+    // mgr's subscriptions = its reports = both workers
+    const subs = subscriptionsOf('mgr');
+    assert.deepEqual(subs.map((s) => s.node_id).sort(), ['w1', 'w2']);
+    assert.equal(subs.find((s) => s.node_id === 'w1')?.active, true);
+    assert.equal(subs.find((s) => s.node_id === 'w2')?.active, false);
+});
+test('subscribe is idempotent and flips active', () => {
+    createNode(node('a'));
+    createNode(node('b'));
+    subscribe('a', 'b', true);
+    subscribe('a', 'b', false); // re-subscribe updates the flag, no dup
+    const subs = subscriptionsOf('a');
+    assert.equal(subs.length, 1);
+    assert.equal(subs[0].active, false);
+    setSubscriptionActive('a', 'b', true);
+    assert.equal(subscriptionsOf('a')[0].active, true);
+    unsubscribe('a', 'b');
+    assert.equal(subscriptionsOf('a').length, 0);
+});
+test('view = transitive closure down the subscription spine', () => {
+    // root → mid → leaf, plus root → sib
+    for (const id of ['root', 'mid', 'leaf', 'sib'])
+        createNode(node(id));
+    subscribe('root', 'mid');
+    subscribe('root', 'sib');
+    subscribe('mid', 'leaf');
+    assert.deepEqual(view('root').sort(), ['leaf', 'mid', 'sib']);
+    assert.deepEqual(view('mid'), ['leaf']);
+});
+test('view is cycle-safe', () => {
+    createNode(node('a'));
+    createNode(node('b'));
+    subscribe('a', 'b');
+    subscribe('b', 'a');
+    assert.deepEqual(view('a'), ['b']);
+});
+test('hasActiveLiveSubscription: the stop-guard primitive', () => {
+    createNode(node('mgr'));
+    createNode(node('child', { status: 'active' }));
+    // no subscription yet
+    assert.equal(hasActiveLiveSubscription('mgr'), false);
+    subscribe('mgr', 'child', true);
+    assert.equal(hasActiveLiveSubscription('mgr'), true); // active sub to a live node
+    setStatus('child', 'done');
+    assert.equal(hasActiveLiveSubscription('mgr'), false); // child no longer live
+    setStatus('child', 'active');
+    setSubscriptionActive('mgr', 'child', false);
+    assert.equal(hasActiveLiveSubscription('mgr'), false); // passive sub doesn't count
+});
+test('recordSpawn writes the audit-only spawned_by edge', () => {
+    createNode(node('parent'));
+    createNode(node('child', { parent: 'parent' }));
+    recordSpawn('child', 'parent');
+    // spawned_by does not appear in the subscription spine
+    assert.equal(subscriptionsOf('child').length, 0);
+    assert.equal(subscribersOf('parent').length, 0);
+});
+test('rebuildIndex reconstructs node rows from on-disk metas', () => {
+    createNode(node('a', { parent: null }));
+    createNode(node('b', { parent: 'a' }));
+    // wipe just the db, keep the node dirs
+    closeDb();
+    rmSync(join(home, 'canvas.db'), { force: true });
+    rmSync(join(home, 'canvas.db-wal'), { force: true });
+    rmSync(join(home, 'canvas.db-shm'), { force: true });
+    assert.equal(getRow('a'), null); // gone from index
+    rebuildIndex();
+    assert.equal(getRow('a')?.node_id, 'a');
+    assert.equal(getRow('b')?.parent, 'a');
+});

package/dist/core/__tests__/reset.test.js

@@ -0,0 +1,105 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/reset.test.ts
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, subscribe, setStatus, subscriptionsOf, view, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { reportsDir, inboxPath } from '../canvas/paths.js';
+import { roadmapPath } from '../runtime/roadmap.js';
+import { resetRoot } from '../runtime/reset.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-reset-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('resetRoot empties the root view, reaps descendants, and wipes working state', () => {
+    // root → child → grandchild (mirrors a parent that subscribes to its workers)
+    createNode(node('root', { parent: null, lifecycle: 'resident', mode: 'orchestrator', pi_session_id: 'old-sess' }));
+    createNode(node('child', { parent: 'root' }));
+    createNode(node('grand', { parent: 'child' }));
+    subscribe('root', 'child', true);
+    subscribe('child', 'grand', true);
+    // Root accumulated working state.
+    writeFileSync(roadmapPath('root'), '# Roadmap\nold goal\n');
+    writeFileSync(inboxPath('root'), '{"ts":"x","from":"child","tier":"normal","kind":"update","label":"hi"}\n');
+    writeFileSync(join(reportsDir('root'), '20260101T000000-update.md'), 'stale report');
+    assert.equal(view('root').length, 2, 'precondition: root sees 2 descendants');
+    const res = resetRoot('root', 'new-sess');
+    assert.equal(res.reset, true);
+    assert.deepEqual(res.detached, ['child'], 'root detaches its direct subscription');
+    assert.deepEqual(res.reaped.sort(), ['child', 'grand'], 'whole sub-DAG reaped');
+    // Graph is empty from the root's view.
+    assert.equal(view('root').length, 0, 'root view is empty after reset');
+    assert.equal(subscriptionsOf('root').length, 0, 'no outgoing edges remain');
+    // Descendants are dead (daemon will skip them).
+    assert.equal(getNode('child')?.status, 'dead');
+    assert.equal(getNode('grand')?.status, 'dead');
+    // Working state wiped.
+    assert.equal(existsSync(roadmapPath('root')), false, 'roadmap wiped');
+    assert.equal(existsSync(inboxPath('root')), false, 'inbox wiped');
+    // Root reset to a pristine base resident, rebound to the new session id.
+    const root = getNode('root');
+    assert.equal(root?.mode, 'base');
+    assert.equal(root?.lifecycle, 'resident');
+    assert.equal(root?.status, 'active');
+    assert.equal(root?.intent, null);
+    assert.equal(root?.pi_session_id, 'new-sess');
+    assert.ok(root?.launch, 'a fresh base launch spec was written');
+});
+test('resetRoot on a non-root only refreshes the session id (no reap)', () => {
+    createNode(node('root', { parent: null }));
+    createNode(node('child', { parent: 'root', pi_session_id: 'old' }));
+    subscribe('root', 'child', true);
+    subscribe('child', 'root', false); // contrived: ensure child has an outgoing edge
+    const res = resetRoot('child', 'fresh');
+    assert.equal(res.reset, false, 'a non-root is not a graph reset');
+    assert.deepEqual(res.reaped, []);
+    assert.deepEqual(res.detached, []);
+    assert.equal(getNode('child')?.pi_session_id, 'fresh', 'session id still refreshed');
+    assert.equal(getNode('child')?.status, 'active', 'child not reaped');
+    // The root that subscribes to the child is untouched.
+    assert.equal(getNode('root')?.status, 'active');
+});
+test('resetRoot is a no-op for an unknown node', () => {
+    const res = resetRoot('ghost', 'x');
+    assert.equal(res.reset, false);
+    assert.deepEqual(res.reaped, []);
+    assert.deepEqual(res.detached, []);
+});
+test('reaped descendants keep their meta on disk (orphaned, not deleted)', () => {
+    createNode(node('root', { parent: null }));
+    createNode(node('child', { parent: 'root' }));
+    subscribe('root', 'child', true);
+    setStatus('child', 'idle');
+    resetRoot('root', 'new');
+    // The node record persists (we detach + mark dead, we don't delete the node).
+    const child = getNode('child');
+    assert.ok(child, 'child meta still on disk');
+    assert.equal(child?.status, 'dead');
+    // It is just unreachable from the root.
+    assert.equal(view('root').length, 0);
+});

package/dist/core/__tests__/resolver.test.js

@@ -6,7 +6,9 @@ import assert from 'node:assert/strict';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { parseSkillQualifier } from '../resolver.js';
+import { parseSkillQualifier, resolveSkill } from '../resolver.js';
+import { resetScopeCache } from '../scope.js';
+import { CrtrError } from '../errors.js';
 import { InputError } from '../io.js';
 import { readConfig } from '../config.js';
 import { SCHEMA_VERSION } from '../../types.js';
@@ -111,3 +113,69 @@ describe('config migration: skill keys colon → slash', () => {
         assert.equal(cfg.schema_version, SCHEMA_VERSION, 'schema_version bumped to current');
     });
 });
+// ---------------------------------------------------------------------------
+// resolveSkill — leaf-name fallback
+// ---------------------------------------------------------------------------
+describe('resolveSkill leaf-name fallback', () => {
+    let testHomeDir;
+    let origHome;
+    function writePluginSkill(plugin, skillPath) {
+        const root = join(testHomeDir, '.crouter', 'plugins', plugin);
+        mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+        writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: plugin, version: '0.0.1' }), 'utf8');
+        const skillDir = join(root, 'skills', ...skillPath.split('/'));
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, 'SKILL.md'), `---\nname: ${skillPath.split('/').pop()}\n---\nbody`, 'utf8');
+    }
+    before(() => {
+        testHomeDir = join(tmpdir(), `crtr-leaf-test-${Date.now()}`);
+        mkdirSync(testHomeDir, { recursive: true });
+        origHome = process.env['HOME'];
+        process.env['HOME'] = testHomeDir;
+        resetScopeCache();
+        // Unique leaf: only one plugin has it, reached via nested path.
+        writePluginSkill('ai', 'interface/cli-design');
+        // Colliding leaf: two plugins both expose `dup` at different paths.
+        writePluginSkill('pa', 'x/dup');
+        writePluginSkill('pb', 'y/dup');
+    });
+    after(() => {
+        if (origHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = origHome;
+        resetScopeCache();
+        rmSync(testHomeDir, { recursive: true, force: true });
+    });
+    test('bare leaf name resolves to the nested skill', () => {
+        const s = resolveSkill('cli-design');
+        assert.equal(s.name, 'interface/cli-design');
+        assert.equal(s.plugin, 'ai');
+    });
+    test('full path still resolves directly', () => {
+        const s = resolveSkill('ai/interface/cli-design');
+        assert.equal(s.name, 'interface/cli-design');
+        assert.equal(s.plugin, 'ai');
+    });
+    test('colliding leaf name throws ambiguous listing full paths', () => {
+        assert.throws(() => resolveSkill('dup'), (e) => {
+            assert.ok(e instanceof CrtrError, 'should be CrtrError');
+            assert.equal(e.code, 'ambiguous');
+            assert.match(e.message, /pa\/x\/dup/);
+            assert.match(e.message, /pb\/y\/dup/);
+            return true;
+        });
+    });
+    test('colliding leaf is resolvable via full path', () => {
+        const s = resolveSkill('pb/y/dup');
+        assert.equal(s.plugin, 'pb');
+        assert.equal(s.name, 'y/dup');
+    });
+    test('unknown leaf still throws not_found', () => {
+        assert.throws(() => resolveSkill('no-such-leaf-xyz'), (e) => {
+            assert.ok(e instanceof CrtrError);
+            assert.equal(e.code, 'not_found');
+            return true;
+        });
+    });
+});

package/dist/core/__tests__/unknown-path.test.d.ts

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

package/dist/core/__tests__/unknown-path.test.js

@@ -0,0 +1,52 @@
+// Regression tests for unknown-subcommand error recovery hints.
+// Run with: node --import tsx/esm --test src/core/__tests__/unknown-path.test.ts
+//
+// The `next` road sign must name a command that actually exists: the FULL path
+// to the deepest matched node, not just its local name. A prior bug emitted
+// `crtr find -h` (dropping the `skill` parent) when `crtr skill find bogus` was
+// invoked, sending the caller to a nonexistent top-level command.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { defineRoot, defineBranch, defineLeaf, walk, unknownPathError } from '../command.js';
+const leaf = defineLeaf({
+    name: 'search',
+    help: { name: 'search', summary: 'search', output: [], outputKind: 'object', effects: ['None. Read-only.'] },
+    run: async () => ({}),
+});
+const findBranch = defineBranch({
+    name: 'find',
+    help: { name: 'find', summary: 'find', children: [{ name: 'search', desc: 'search', useWhen: 'x' }] },
+    children: [leaf],
+});
+const skillBranch = defineBranch({
+    name: 'skill',
+    help: { name: 'skill', summary: 'skill', children: [{ name: 'find', desc: 'find', useWhen: 'x' }] },
+    rootEntry: { concept: 'skill', desc: 'skill', useWhen: 'x' },
+    children: [findBranch],
+});
+const root = defineRoot({
+    tagline: 'test runtime',
+    globals: [],
+    subtrees: [skillBranch],
+});
+function nextHint(...tokens) {
+    const { node, path, remaining } = walk(root, tokens);
+    const err = unknownPathError(node, path, remaining[0]);
+    return err.details.next;
+}
+describe('unknown-path error: recovery hint names the full valid path', () => {
+    test('root-level unknown points at `crtr -h`', () => {
+        assert.match(nextHint('bogus'), /Run `crtr -h`/);
+    });
+    test('one-level unknown points at `crtr skill -h`', () => {
+        assert.match(nextHint('skill', 'bogus'), /Run `crtr skill -h`/);
+    });
+    test('two-level unknown points at `crtr skill find -h`, not `crtr find -h`', () => {
+        const hint = nextHint('skill', 'find', 'bogus');
+        assert.match(hint, /Run `crtr skill find -h`/);
+        assert.doesNotMatch(hint, /Run `crtr find -h`/);
+    });
+    test('valid children of the matched node are listed', () => {
+        assert.match(nextHint('skill', 'find', 'bogus'), /Valid children: search\./);
+    });
+});

package/dist/core/bootstrap.d.ts

@@ -1,6 +1,8 @@
+import type { RootDef } from './command.js';
 export declare const OFFICIAL_MARKETPLACE_NAME = "crouter-official-marketplace";
 export declare const OFFICIAL_MARKETPLACE_URL = "https://github.com/crouton-labs/crouter-official-marketplace.git";
 export declare const OFFICIAL_MARKETPLACE_REF = "main";
 export declare function ensureBootSkill(argv: string[]): void;
+export declare function ensureSlashCommands(root: RootDef, argv: string[]): void;
 export declare function ensureOfficialMarketplace(argv: string[]): void;
 export declare function ensureProjectScope(argv: string[]): void;

package/dist/core/bootstrap.js

@@ -6,6 +6,7 @@ import { ensureDir, pathExists, readText, removePath, nowIso } from './fs-utils.
 import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
 import { clone } from './git.js';
 import { readMarketplaceManifest } from './manifest.js';
+import { collectSlashSpecs } from './command.js';
 import { CRTR_DIR_NAME } from '../types.js';
 export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
 export const OFFICIAL_MARKETPLACE_URL = 'https://github.com/crouton-labs/crouter-official-marketplace.git';
@@ -94,6 +95,71 @@ export function ensureBootSkill(argv) {
         }
     }
 }
+// ---------------------------------------------------------------------------
+// Slash commands (editor prompt templates) auto-installed for opted-in nodes.
+//
+// Any command that declares a `slash` SlashSpec is rendered to a markdown
+// template and dropped into the host's command dirs on each crtr run — pi reads
+// `~/.pi/agent/prompts/<name>.md`, Claude Code reads `~/.claude/commands/<name>.md`,
+// so `/name` becomes available. Marker-guarded (never clobbers a user-edited
+// file) and version-rolled like the boot skill. Kill switch: CRTR_NO_MODE_CMDS=1.
+// ---------------------------------------------------------------------------
+const SLASH_CMD_MARKER = '<!-- crtr-mode-cmd v1 -->';
+const SLASH_CMD_MARKER_PREFIX = '<!-- crtr-mode-cmd v';
+/** Render a SlashSpec to a full template file (frontmatter + marker + body). */
+function renderSlashTemplate(spec) {
+    const hint = spec.argumentHint !== undefined
+        ? `argument-hint: ${JSON.stringify(spec.argumentHint)}\n`
+        : '';
+    return `---\ndescription: ${spec.description}\n${hint}---\n\n${SLASH_CMD_MARKER}\n\n${spec.body}\n`;
+}
+/** Write `content` to `file` unless a user-customized file is already there.
+ *  Rolls forward our own (marker-bearing) versions; skips if identical. */
+function writeSlashFileIfOurs(dir, name, content) {
+    const file = join(dir, `${name}.md`);
+    if (pathExists(file)) {
+        const existing = readText(file);
+        if (!existing.includes(SLASH_CMD_MARKER_PREFIX))
+            return; // user's own file
+        if (existing === content)
+            return; // already current
+    }
+    ensureDir(dir);
+    writeFileSync(file, content, 'utf8');
+}
+export function ensureSlashCommands(root, argv) {
+    try {
+        if (process.env.CRTR_NO_MODE_CMDS === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        const specs = collectSlashSpecs(root);
+        if (specs.length === 0)
+            return;
+        // Target each host's command dir, but only when that host is actually in use
+        // (its root dir exists). We never create ~/.pi or ~/.claude ourselves.
+        const targets = [];
+        if (pathExists(join(homedir(), '.pi', 'agent'))) {
+            targets.push(join(homedir(), '.pi', 'agent', 'prompts'));
+        }
+        if (pathExists(join(homedir(), '.claude'))) {
+            targets.push(join(homedir(), '.claude', 'commands'));
+        }
+        if (targets.length === 0)
+            return;
+        for (const spec of specs) {
+            const content = renderSlashTemplate(spec);
+            for (const dir of targets)
+                writeSlashFileIfOurs(dir, spec.name, content);
+        }
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: slash-command error: ${msg}\n`);
+        }
+    }
+}
 export function ensureOfficialMarketplace(argv) {
     try {
         if (process.env.CRTR_NO_BOOTSTRAP === '1')

package/dist/core/canvas/attention.d.ts

@@ -0,0 +1,24 @@
+export interface AskEntry {
+    node_id: string;
+    name: string;
+    cwd: string;
+    count: number;
+}
+/**
+ * Count pending asks for the cwd of a single node.
+ * Returns 0 when the node is unknown or humanloop is unavailable.
+ */
+export declare function countAsks(nodeId: string): number;
+/**
+ * Pending asks for all nodes reachable in the subscription sub-DAG from
+ * `rootId` (including root itself). De-duped by cwd: when multiple nodes
+ * share a cwd the first one encountered claims the entry.
+ *
+ * Returns only entries with count > 0.
+ */
+export declare function pendingAsksForView(rootId: string): AskEntry[];
+/**
+ * Pending asks across the entire canvas — every distinct cwd among all known
+ * nodes. Returns only entries with count > 0.
+ */
+export declare function asksAcrossCanvas(): AskEntry[];