@north-light/crouter 0.3.173 → 0.3.175

package/dist/clients/attach/__tests__/ref-autocomplete.test.js

@@ -4,27 +4,15 @@ import { findRefCompletionContext, RefAwareAutocompleteProvider } from '../input
 function ref(name, shortForm = `${name} docs`) {
     return { name, kind: 'knowledge', scope: 'user', shortForm };
 }
-/** Records every call so delegation (vs. ref handling) is directly assertable. */
-class FakeDelegate {
-    getSuggestionsCalls = [];
-    applyCompletionCalls = [];
-    shouldTriggerFileCompletionCalls = [];
-    suggestions = { items: [{ value: 'reload', label: '/reload' }], prefix: '/' };
-    shouldTrigger = false;
-    async getSuggestions(lines, cursorLine, cursorCol, options) {
-        this.getSuggestionsCalls.push([lines, cursorLine, cursorCol, options]);
-        return this.suggestions;
-    }
-    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
-        this.applyCompletionCalls.push([lines, cursorLine, cursorCol, item, prefix]);
-        return { lines, cursorLine, cursorCol };
-    }
-    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
-        this.shouldTriggerFileCompletionCalls.push([lines, cursorLine, cursorCol]);
-        return this.shouldTrigger;
-    }
-}
-const opts = { signal: new AbortController().signal, force: false };
+/** The wrapped provider; ref handling must never reach it in a ref context. */
+const inertDelegate = {
+    async getSuggestions() { return null; },
+    applyCompletion(lines, cursorLine, cursorCol) { return { lines, cursorLine, cursorCol }; },
+    shouldTriggerFileCompletion() { return false; },
+};
+// The grammar boundary decides whether a typed '/' is a slash COMMAND or a
+// memory REF. Getting it wrong either hides the command palette or turns
+// ordinary prose ('http://', 'and/or') into a completion popup.
 test('findRefCompletionContext classifies leading, non-leading, and non-token caret positions', () => {
     // Leading: '/' is the very first character of the whole message.
     assert.deepEqual(findRefCompletionContext(['/de'], 0, 3), {
@@ -62,63 +50,8 @@ test('findRefCompletionContext classifies leading, non-leading, and non-token ca
     // Caret has moved past the token into trailing whitespace — not touching it.
     assert.equal(findRefCompletionContext(['/dev  x'], 0, 5), null);
 });
-test('leading /de delegates verbatim and never surfaces refs, even when a matching ref exists', async () => {
-    const delegate = new FakeDelegate();
-    const provider = new RefAwareAutocompleteProvider([ref('dev')], delegate);
-    const result = await provider.getSuggestions(['/de'], 0, 3, opts);
-    assert.equal(result, delegate.suggestions);
-    assert.equal(delegate.getSuggestionsCalls.length, 1);
-    assert.deepEqual(delegate.getSuggestionsCalls[0], [['/de'], 0, 3, opts]);
-});
-test('non-leading /de mid-prose and at the start of a later line surfaces prefix-filtered refs', async () => {
-    const delegate = new FakeDelegate();
-    const refs = [ref('dev', 'dev stack docs'), ref('taste/foo', 'foo taste doc'), ref('other')];
-    const provider = new RefAwareAutocompleteProvider(refs, delegate);
-    const midProse = await provider.getSuggestions(['fix /de'], 0, 7, opts);
-    assert.deepEqual(midProse, {
-        items: [{ value: 'dev', label: '/dev', description: 'dev stack docs' }],
-        prefix: 'de',
-    });
-    assert.equal(delegate.getSuggestionsCalls.length, 0);
-    const laterLine = await provider.getSuggestions(['fix this', '/de'], 1, 3, opts);
-    assert.deepEqual(laterLine, {
-        items: [{ value: 'dev', label: '/dev', description: 'dev stack docs' }],
-        prefix: 'de',
-    });
-    // Bare non-leading '/' offers the whole inventory. The returned `prefix`
-    // strips the leading '/' (review Major 3 — see input/ref-autocomplete.ts) so
-    // pi-tui's `tui.select.confirm` fallthrough never misclassifies a ref
-    // completion as a leading-command completion and submits on Enter.
-    const bare = await provider.getSuggestions(['fix /'], 0, 5, opts);
-    assert.deepEqual(bare, {
-        items: [
-            { value: 'dev', label: '/dev', description: 'dev stack docs' },
-            { value: 'taste/foo', label: '/taste:foo', description: 'foo taste doc' },
-            { value: 'other', label: '/other', description: 'other docs' },
-        ],
-        prefix: '',
-    });
-    // Nested names are offered in colon surface form and filtered by it.
-    const nested = await provider.getSuggestions(['see /tas'], 0, 8, opts);
-    assert.deepEqual(nested, {
-        items: [{ value: 'taste/foo', label: '/taste:foo', description: 'foo taste doc' }],
-        prefix: 'tas',
-    });
-    assert.equal(delegate.getSuggestionsCalls.length, 0, 'no ref-context call ever reaches the wrapped provider');
-});
-test('boundary-invalid strings and no-match prefixes never enter ref mode', async () => {
-    const delegate = new FakeDelegate();
-    const provider = new RefAwareAutocompleteProvider([ref('dev')], delegate);
-    await provider.getSuggestions(['see http://example.com'], 0, 12, opts);
-    await provider.getSuggestions(['read and/or write'], 0, 10, opts);
-    assert.equal(delegate.getSuggestionsCalls.length, 2, 'both boundary cases fell through to the delegate');
-    const noMatch = await provider.getSuggestions(['fix /zz'], 0, 7, opts);
-    assert.equal(noMatch, null, 'a non-leading ref context with no prefix match returns null, not delegate output');
-    assert.equal(delegate.getSuggestionsCalls.length, 2, 'a real (non-matching) ref context still never delegates');
-});
-test('applying a ref completion replaces only the token, adds no separator, and never calls the delegate', () => {
-    const delegate = new FakeDelegate();
-    const provider = new RefAwareAutocompleteProvider([ref('dev')], delegate);
+test('applying a ref completion replaces only the token and adds no separator', () => {
+    const provider = new RefAwareAutocompleteProvider([ref('dev')], inertDelegate);
     const line = 'before /de after';
     const cursorCol = line.indexOf('/de') + '/de'.length;
     const item = { value: 'dev', label: '/dev' };
@@ -126,51 +59,4 @@ test('applying a ref completion replaces only the token, adds no separator, and
     assert.deepEqual(result.lines, ['before /dev after']);
     assert.equal(result.cursorLine, 0);
     assert.equal(result.cursorCol, 'before /dev'.length);
-    assert.equal(delegate.applyCompletionCalls.length, 0);
-});
-test('applying an item absent from the ref inventory in a real non-leading ref context delegates unchanged', () => {
-    const delegate = new FakeDelegate();
-    const provider = new RefAwareAutocompleteProvider([ref('dev')], delegate);
-    // 'reload' is a command, not a ref — it can never legitimately arrive here,
-    // but the provider must still refuse to treat it as a ref rather than
-    // trusting every slash-valued item blindly.
-    const item = { value: 'reload', label: '/reload' };
-    const result = provider.applyCompletion(['fix /re'], 0, 7, item, '/re');
-    assert.deepEqual(result, { lines: ['fix /re'], cursorLine: 0, cursorCol: 7 });
-    assert.equal(delegate.applyCompletionCalls.length, 1);
-    assert.deepEqual(delegate.applyCompletionCalls[0], [['fix /re'], 0, 7, item, '/re']);
-});
-test('applying at a leading-command position always delegates, regardless of item.value', () => {
-    const delegate = new FakeDelegate();
-    const provider = new RefAwareAutocompleteProvider([ref('re')], delegate);
-    const item = { value: 're', label: '/re' };
-    const result = provider.applyCompletion(['/re'], 0, 3, item, '/re');
-    assert.deepEqual(result, { lines: ['/re'], cursorLine: 0, cursorCol: 3 });
-    assert.equal(delegate.applyCompletionCalls.length, 1);
-    assert.deepEqual(delegate.applyCompletionCalls[0], [['/re'], 0, 3, item, '/re']);
-});
-test('shouldTriggerFileCompletion is forced true only in a non-leading ref context', () => {
-    const delegate = new FakeDelegate();
-    const provider = new RefAwareAutocompleteProvider([ref('dev')], delegate);
-    assert.equal(provider.shouldTriggerFileCompletion(['before /de after'], 0, 'before /de'.length), true);
-    assert.equal(delegate.shouldTriggerFileCompletionCalls.length, 0);
-    // Leading context delegates.
-    delegate.shouldTrigger = true;
-    assert.equal(provider.shouldTriggerFileCompletion(['/de'], 0, 3), true);
-    assert.equal(delegate.shouldTriggerFileCompletionCalls.length, 1);
-    // Non-token context (e.g. an '@' file-mention position) delegates too.
-    delegate.shouldTrigger = false;
-    const line = 'see @file.txt';
-    assert.equal(provider.shouldTriggerFileCompletion([line], 0, line.length), false);
-    assert.equal(delegate.shouldTriggerFileCompletionCalls.length, 2);
-});
-test('triggerCharacters passes through the wrapped provider unchanged', () => {
-    class DelegateWithTrigger extends FakeDelegate {
-        triggerCharacters = ['@'];
-    }
-    const delegate = new DelegateWithTrigger();
-    const provider = new RefAwareAutocompleteProvider([ref('dev')], delegate);
-    assert.deepEqual(provider.triggerCharacters, ['@']);
-    const bare = new RefAwareAutocompleteProvider([ref('dev')], new FakeDelegate());
-    assert.equal(bare.triggerCharacters, undefined);
 });

package/dist/clients/attach/__tests__/titled-editor-preview.test.js

@@ -1,95 +1,18 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { CURSOR_MARKER, visibleWidth } from '@earendil-works/pi-tui';
+import { visibleWidth } from '@earendil-works/pi-tui';
 import { RefAwareAutocompleteProvider } from '../input/ref-autocomplete.js';
 import { compactLoadedCommandPreview, TitledEditor } from '../input/titled-editor.js';
-const REF_STYLE_ON = '\x1b[4m\x1b[2m';
-const REF_STYLE_OFF = '\x1b[24m\x1b[22m';
-function stripAnsi(s) {
-    return s
-        .split(CURSOR_MARKER)
-        .join('')
-        .replace(/\x1b\[[0-9;]*m/g, '')
-        .replace(/\x1b\][^\x07]*\x07/g, '');
-}
 function makeEditor(rows = 24) {
     const tui = { requestRender: () => { }, terminal: { rows } };
     const theme = { borderColor: (s) => s, selectList: {} };
     const keybindings = { matches: () => false };
     return new TitledEditor(tui, theme, keybindings);
 }
-test('loaded command disclosure stays bounded and points to the full inspector', () => {
-    const lines = compactLoadedCommandPreview(Array.from({ length: 20 }, (_, i) => `instruction ${i}`).join('\n'), 32);
-    assert.equal(lines.length, 8);
-    assert.match(lines.at(-1), /truncated · inspect/);
-    assert.ok(lines.every((line) => visibleWidth(line) <= 32));
-});
-test('short loaded command disclosure is not decorated as truncated', () => {
-    assert.deepEqual(compactLoadedCommandPreview('one\ntwo', 32), ['one', 'two']);
-});
-test('inline disclosure strips hostile terminal controls while inspector text stays raw', () => {
-    const lines = compactLoadedCommandPreview('safe\x1b[2J\x1b]8;;https://evil.example\x07link\x1b]8;;\x07\u0000', 32);
-    const visible = lines.join('\n');
-    assert.match(visible, /safelink/);
-    assert.doesNotMatch(visible, /\x1b|\u0000|evil\.example/);
-});
-test('inline disclosure bounds huge work before wrapping and suppresses below usable inspect width', () => {
-    const lines = compactLoadedCommandPreview('x'.repeat(1_000_000), 32);
-    assert.equal(lines.length, 8);
-    assert.match(lines.at(-1), /inspect/);
-    assert.deepEqual(compactLoadedCommandPreview('ordinary prompt', 20), []);
-});
-test('down exhausts native editor movement and prompt history before yielding to the roster', { timeout: 1_000 }, () => {
-    const tui = { requestRender: () => { }, terminal: { rows: 24 } };
-    const theme = { borderColor: (s) => s, selectList: {} };
-    const keybindings = {
-        matches: (data, binding) => binding === 'tui.editor.cursorDown' && data === '\x1b[B',
-    };
-    const editor = new TitledEditor(tui, theme, keybindings);
-    const internals = editor;
-    let boundaryHits = 0;
-    editor.onCursorDownAtBottom = () => { boundaryHits++; };
-    editor.setText('this editor line is deliberately long enough to wrap several times');
-    editor.render(20);
-    internals.state.cursorLine = 0;
-    internals.state.cursorCol = 0;
-    editor.handleInput('\x1b[B');
-    assert.ok(editor.getCursor().col > 0, 'a wrapped visual line consumes ↓');
-    assert.equal(boundaryHits, 0);
-    editor.setText('short line');
-    editor.render(20);
-    internals.state.cursorCol = 2;
-    editor.handleInput('\x1b[B');
-    assert.equal(editor.getCursor().col, editor.getText().length, 'the last visual line first moves to its end');
-    assert.equal(boundaryHits, 0);
-    editor.handleInput('\x1b[B');
-    assert.equal(boundaryHits, 1, 'only the true editor bottom yields to the roster');
-    editor.addToHistory('previous prompt');
-    editor.setText('');
-    editor.render(20);
-    editor.handleInput('\x1b[A');
-    assert.equal(editor.getText(), 'previous prompt', '↑ opens the prior submitted prompt');
-    editor.handleInput('\x1b[B');
-    assert.equal(editor.getText(), '', '↓ returns from history to the draft');
-    assert.equal(boundaryHits, 1, 'history navigation consumes ↓ before the roster');
-});
-test('resolved-ref candidates are underlined; unknown or boundary-invalid strings are untouched', () => {
-    const editor = makeEditor();
-    editor.setResolvedRefNames(['dev', 'taste/foo']);
-    const text = 'check /dev. and /taste:foo and /nope and http://x and and/or';
-    editor.setText(`placeholder\n${text}`);
-    const internals = editor;
-    internals.state.cursorLine = 0;
-    internals.state.cursorCol = 0;
-    const lines = editor.render(80);
-    const body = lines[2]; // border(0) + placeholder(1) + the ref line(2)
-    assert.equal(stripAnsi(body).trimEnd(), text, 'decoration never alters the visible text');
-    assert.ok(body.includes(`${REF_STYLE_ON}/dev${REF_STYLE_OFF}`), 'trailing punctuation is trimmed from the highlighted span');
-    assert.ok(body.includes(`${REF_STYLE_ON}/taste:foo${REF_STYLE_OFF}`), 'nested taste/foo highlights as its colon surface form');
-    const onCount = body.split(REF_STYLE_ON).length - 1;
-    assert.equal(onCount, 2, 'unknown (/nope) and boundary-invalid (http://x, and/or) strings get no decoration at all');
-});
-test("decoration never changes a rendered line's visible width", () => {
+// The frame-width invariant: the viewer renders exactly `terminal.rows` lines
+// with no overflow, so a decoration that changes a rendered line's visible
+// width crashes the pane.
+test("ref decoration never changes a rendered line's visible width", () => {
     const width = 40;
     const texts = [
         'ünïcödé prefix /dev then more text that wraps across the available width for sure',
@@ -109,78 +32,15 @@ test("decoration never changes a rendered line's visible width", () => {
         }
     }
 });
-test('cursor sweep across a resolved ref decorates outside the cursor cell and safely degrades inside it', () => {
-    const text = 'go /dev now';
-    // span for /dev is [3,7); decorated everywhere the cursor's own reverse-video
-    // cell doesn't touch or straddle it (see decorateRow's before/after-cursor math).
-    const decoratedCols = new Set([0, 1, 2, 7, 8, 9, 10, 11]);
-    for (const paneFocused of [true, false]) {
-        const editor = makeEditor();
-        editor.setResolvedRefNames(['dev']);
-        editor.focused = true; // component (TUI) focus controls CURSOR_MARKER emission
-        editor.paneFocused = paneFocused; // terminal-pane focus controls solid vs muted cursor styling
-        editor.setText(text);
-        const internals = editor;
-        for (let col = 0; col <= text.length; col++) {
-            internals.state.cursorLine = 0;
-            internals.state.cursorCol = col;
-            const lines = editor.render(60);
-            const body = lines[1];
-            assert.equal(stripAnsi(body).trimEnd(), text, `text intact at col ${col} paneFocused=${paneFocused}`);
-            const hasCursorMarkup = body.includes('\x1b[7m') || body.includes('\x1b[48;5;240m');
-            assert.ok(hasCursorMarkup, `cursor cell present at col ${col} paneFocused=${paneFocused}`);
-            const decorated = body.includes(REF_STYLE_ON);
-            assert.equal(decorated, decoratedCols.has(col), `decoration at col ${col} paneFocused=${paneFocused}`);
-        }
-    }
-});
-test('chrome (loaded-command disclosure, title/info border, context badge) never carries ref decoration', () => {
-    const editorA = makeEditor();
-    const editorB = makeEditor();
-    for (const editor of [editorA, editorB]) {
-        editor.title = 'session';
-        editor.info = 'cwd-info';
-        editor.contextBadge = 'node-1';
-        editor.loadedCommand = { name: 'dev', content: 'do the thing', inspectHint: 'ctrl+i' };
-        editor.setText('please use /dev to continue');
-    }
-    editorB.setResolvedRefNames(['dev']);
-    const linesA = editorA.render(60);
-    const linesB = editorB.render(60);
-    assert.equal(linesA.length, linesB.length, 'decoration never adds or removes lines');
-    let diffCount = 0;
-    let diffIndex = -1;
-    for (let i = 0; i < linesA.length; i++) {
-        if (linesA[i] !== linesB[i]) {
-            diffCount++;
-            diffIndex = i;
-        }
-    }
-    assert.equal(diffCount, 1, 'decoration touches exactly the one content row carrying the ref, nothing else');
-    assert.ok(linesB[diffIndex].includes(REF_STYLE_ON), 'the differing row is in fact the decorated one');
-});
-test('terminal suppression combines a trimmed local-command rule and a separate untrimmed engine-command rule (Minor 10)', () => {
-    const editor = makeEditor();
-    editor.setResolvedRefNames(['dev']);
-    // The LOCAL viewer rule is checked against TRIMMED text (mirrors
-    // slash/dispatch.ts's own `text.trim()`-based dispatch parse) — leading
-    // whitespace is tolerated.
-    editor.setLocalCommandNames(['dev']);
-    editor.setText('  /dev something /dev');
-    assert.ok(!editor.render(60)[1].includes(REF_STYLE_ON), 'local-command rule suppresses even with leading whitespace (trimmed rule)');
-    // The SAME leading-whitespace text is NOT suppressed by the ENGINE rule —
-    // it mirrors the broker's own `isLeadingEngineCommand`, which requires the
-    // RAW text itself (no trim) to start with '/'.
-    editor.setLocalCommandNames([]);
-    editor.setEngineCommandNames(['dev']);
-    assert.ok(editor.render(60)[1].includes(REF_STYLE_ON), 'engine rule does not tolerate leading whitespace — decoration is not suppressed');
-    // Without leading whitespace the engine (untrimmed) rule suppresses too.
-    editor.setText('/dev something /dev');
-    assert.ok(!editor.render(60)[1].includes(REF_STYLE_ON), 'engine rule suppresses once the raw text itself starts with /');
-    editor.setEngineCommandNames([]);
-    assert.ok(editor.render(60)[1].includes(REF_STYLE_ON), 'decoration resumes once neither the local nor the engine rule matches');
+// An untrusted command body reaches the inline disclosure verbatim; a live
+// escape sequence there would repaint or hyperlink the user's terminal.
+test('inline disclosure strips hostile terminal controls', () => {
+    const lines = compactLoadedCommandPreview('safe\x1b[2J\x1b]8;;https://evil.example\x07link\x1b]8;;\x07\u0000', 32);
+    const visible = lines.join('\n');
+    assert.match(visible, /safelink/);
+    assert.doesNotMatch(visible, /\x1b|\u0000|evil\.example/);
 });
-test('Enter-confirming a non-leading ref completion accepts the token and returns to editing, never submits (Major 3)', async () => {
+test('Enter-confirming a non-leading ref completion accepts the token and returns to editing, never submits', async () => {
     const editor = makeEditor();
     editor.focused = true;
     let submitted;
@@ -206,7 +66,7 @@ test('Enter-confirming a non-leading ref completion accepts the token and return
     assert.equal(editor.getText(), 'hey check /dev', 'the token was replaced in place, not submitted as typed');
     assert.equal(submitted, undefined, 'Enter-confirming a ref completion must never submit the message');
 });
-test('a real Enter submission preserves raw leading/trailing whitespace end-to-end (Major 4)', () => {
+test('a real Enter submission preserves raw leading/trailing whitespace end-to-end', () => {
     const editor = makeEditor();
     let submitted;
     editor.onSubmit = (text) => {
@@ -217,54 +77,3 @@ test('a real Enter submission preserves raw leading/trailing whitespace end-to-e
     assert.equal(submitted, '  hello world  ', 'onSubmit receives the exact untrimmed text, not the base editor\'s trimmed copy');
     assert.equal(editor.getText(), '', 'submitValue still resets editor state as usual');
 });
-test('a resolved ref wider than the editor renders plain, without corrupting width', () => {
-    const name = 'x'.repeat(40);
-    const width = 20;
-    const plain = makeEditor();
-    const decorated = makeEditor();
-    decorated.setResolvedRefNames([name]);
-    plain.setText(`/${name}`);
-    decorated.setText(`/${name}`);
-    const linesPlain = plain.render(width);
-    const linesDecorated = decorated.render(width);
-    assert.deepEqual(linesDecorated, linesPlain, 'a span that never fits inside one wrapped chunk is left entirely undecorated');
-});
-test('a non-leading ref-grammar character triggers autocomplete without an explicit Tab', async () => {
-    const editor = makeEditor();
-    editor.focused = true;
-    const calls = [];
-    const provider = {
-        async getSuggestions(_lines, cursorLine, cursorCol) {
-            calls.push({ cursorLine, cursorCol });
-            const item = { value: 'dev', label: '/dev' };
-            return { items: [item], prefix: '/' };
-        },
-        applyCompletion(lines, cursorLine, cursorCol) {
-            return { lines, cursorLine, cursorCol };
-        },
-    };
-    editor.setAutocompleteProvider(provider);
-    editor.setText('hey check ');
-    editor.handleInput('/');
-    await new Promise((resolve) => setTimeout(resolve, 20));
-    assert.equal(calls.length, 1, 'the bridge triggers exactly one suggestion request');
-    assert.equal(calls[0].cursorCol, 'hey check /'.length);
-});
-test('a leading slash is unaffected by the trigger bridge (native path only, not doubled)', async () => {
-    const editor = makeEditor();
-    editor.focused = true;
-    const calls = [];
-    const provider = {
-        async getSuggestions() {
-            calls.push(1);
-            return null;
-        },
-        applyCompletion(lines, cursorLine, cursorCol) {
-            return { lines, cursorLine, cursorCol };
-        },
-    };
-    editor.setAutocompleteProvider(provider);
-    editor.handleInput('/');
-    await new Promise((resolve) => setTimeout(resolve, 20));
-    assert.equal(calls.length, 1, 'exactly one trigger from the native leading path, not doubled by the bridge');
-});

package/dist/clients/attach/command.d.ts

@@ -1,2 +1,3 @@
 import type { BranchDef } from '../../core/command.js';
-export declare function registerAttach(): BranchDef;
+import type { SubTier } from '../../core/help.js';
+export declare function registerAttach(namespace: string, tier: SubTier): BranchDef;

package/dist/clients/attach/command.js

@@ -9,92 +9,97 @@
 // actually opens.
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { mark } from '../../core/timing.js';
-const attachToLeaf = defineLeaf({
-    name: 'to',
-    description: 'attach an interactive terminal viewer to a node (reviving it if dormant)',
-    whenToUse: 'you want to WATCH or DRIVE a headless node live in this pane — it connects over the node\'s unix socket to the broker hosting the engine and renders the same chat stream. Normal local attaches are writable; use --observer for read-only, or --canvas for a remote read-only view. A DORMANT node is revived first: crtrd runs reviveNode server-side, then the viewer streams over the broker\'s socket. The configured detach shortcuts leave the engine running',
-    help: {
-        name: 'attach to',
-        summary: 'attach a terminal viewer to a headless node\'s running broker (writable by default, --observer for read-only); configured detach shortcuts leave the engine running',
-        params: [
-            {
-                kind: 'positional',
-                name: 'node',
-                required: true,
-                constraint: 'Node id to attach to. A dormant node is revived (server-side) before the viewer connects.',
-            },
-            {
-                kind: 'flag',
-                name: 'observer',
-                type: 'bool',
-                required: false,
-                default: false,
-                constraint: 'Attach READ-ONLY: request the observer role. Default local attaches request the writable controller role.',
-            },
-            {
-                kind: 'flag',
-                name: 'canvas',
-                type: 'string',
-                required: false,
-                constraint: 'Attach against a remote canvas target configured via `crtr canvas config add` instead of the local canvas — connects over a relayed WebSocket to the target\'s preview endpoint using the relay token from the 0600 secrets store. Omit for local (default): connects to the node\'s local unix socket, which must already exist in THIS machine\'s canvas.db. Does NOT honor `crtr canvas use` — this flag is the only way to attach remotely.',
-            },
-        ],
-        output: [
-            {
-                name: 'note',
-                type: 'string',
-                required: false,
-                constraint: 'Only set on the non-TTY/piped path (a static notice); the interactive path returns nothing.',
-            },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Takes over the current pane in raw mode and renders the node\'s live engine stream until you use a configured detach shortcut or the broker exits.',
-            'As a writable controller: sends prompts/steers/dialog answers to the engine over the socket. As observer: read-only. Multiple writable local viewers may drive the same broker.',
-            'A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects; this LOCAL process NEVER spawns pi and NEVER writes the session — it holds only a socket to the broker.',
-            'Outside a TTY (piped): prints a short notice and exits 0 — attach is an interactive program, not a pipe stage.',
-        ],
-    },
-    run: async (input) => {
-        const nodeId = input['node'];
-        const observer = input['observer'] ?? false;
-        const canvasName = input['canvas'];
-        // attach IS the in-pane interactive program — it only needs a TTY (crtr is
-        // tmux-only, but the pane itself is the surface). Non-TTY (piped) → static
-        // notice + exit, never a non-tmux interactive fallback. Guarded BEFORE the
-        // heavy import so a piped invocation never pays the viewer's load cost.
-        if (!process.stdout.isTTY) {
-            return {
-                note: `crtr surface attach is an interactive terminal viewer — run it in a tmux pane (a TTY), not a pipe. Node: ${nodeId}`,
-            };
-        }
-        // The viewer runtime (the pi-coding-agent-heavy bundle) loads only here.
-        mark('viewer.bundle_import_start');
-        const { runAttach } = await import('./viewer.js');
-        mark('viewer.bundle_loaded');
-        await runAttach(nodeId, observer, canvasName);
-        // The session has sent its final broker frame and restored the terminal.
-        // Force this one-shot viewer process out now: pi's bundled UI dependencies
-        // can retain libuv handles after their visible work is finished. The exit
-        // handler registered by teardown still runs, so terminal restoration remains
-        // safe if the normal path raced a signal.
-        process.exit(0);
-    },
-    render: (result) => (result['note'] !== undefined ? String(result['note']) : ''),
-});
-export function registerAttach() {
+function attachToLeaf(namespace) {
+    return defineLeaf({
+        name: 'to',
+        description: 'attach an interactive terminal viewer to a node (reviving it if dormant)',
+        whenToUse: 'you want to WATCH or DRIVE a headless node live in this pane — it connects over the node\'s unix socket to the broker hosting the engine and renders the same chat stream. Normal local attaches are writable; use --observer for read-only, or --canvas for a remote read-only view. A DORMANT node is revived first: crtrd runs reviveNode server-side, then the viewer streams over the broker\'s socket. The configured detach shortcuts leave the engine running',
+        help: {
+            name: `${namespace} attach to`,
+            summary: 'attach a terminal viewer to a headless node\'s running broker (writable by default, --observer for read-only); configured detach shortcuts leave the engine running',
+            params: [
+                {
+                    kind: 'positional',
+                    name: 'node',
+                    required: true,
+                    constraint: 'Node id to attach to. A dormant node is revived (server-side) before the viewer connects.',
+                },
+                {
+                    kind: 'flag',
+                    name: 'observer',
+                    type: 'bool',
+                    required: false,
+                    default: false,
+                    constraint: 'Attach READ-ONLY: request the observer role. Default local attaches request the writable controller role.',
+                },
+                {
+                    kind: 'flag',
+                    name: 'canvas',
+                    type: 'string',
+                    required: false,
+                    constraint: 'Attach against a remote canvas target configured via `crtr canvas config add` instead of the local canvas — connects over a relayed WebSocket to the target\'s preview endpoint using the relay token from the 0600 secrets store. Omit for local (default): connects to the node\'s local unix socket, which must already exist in THIS machine\'s canvas.db. Does NOT honor `crtr canvas use` — this flag is the only way to attach remotely.',
+                },
+            ],
+            output: [
+                {
+                    name: 'note',
+                    type: 'string',
+                    required: false,
+                    constraint: 'Only set on the non-TTY/piped path (a static notice); the interactive path returns nothing.',
+                },
+            ],
+            outputKind: 'object',
+            effects: [
+                'Takes over the current pane in raw mode and renders the node\'s live engine stream until you use a configured detach shortcut or the broker exits.',
+                'As a writable controller: sends prompts/steers/dialog answers to the engine over the socket. As observer: read-only. Multiple writable local viewers may drive the same broker.',
+                'A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects; this LOCAL process NEVER spawns pi and NEVER writes the session — it holds only a socket to the broker.',
+                'Outside a TTY (piped): prints a short notice and exits 0 — attach is an interactive program, not a pipe stage.',
+            ],
+        },
+        run: async (input) => {
+            const nodeId = input['node'];
+            const observer = input['observer'] ?? false;
+            const canvasName = input['canvas'];
+            // attach IS the in-pane interactive program — it only needs a TTY (crtr is
+            // tmux-only, but the pane itself is the surface). Non-TTY (piped) → static
+            // notice + exit, never a non-tmux interactive fallback. Guarded BEFORE the
+            // heavy import so a piped invocation never pays the viewer's load cost.
+            if (!process.stdout.isTTY) {
+                return {
+                    note: `crtr surface attach is an interactive terminal viewer — run it in a tmux pane (a TTY), not a pipe. Node: ${nodeId}`,
+                };
+            }
+            // The viewer runtime (the pi-coding-agent-heavy bundle) loads only here.
+            mark('viewer.bundle_import_start');
+            const { runAttach } = await import('./viewer.js');
+            mark('viewer.bundle_loaded');
+            await runAttach(nodeId, observer, canvasName);
+            // The session has sent its final broker frame and restored the terminal.
+            // Force this one-shot viewer process out now: pi's bundled UI dependencies
+            // can retain libuv handles after their visible work is finished. The exit
+            // handler registered by teardown still runs, so terminal restoration remains
+            // safe if the normal path raced a signal.
+            process.exit(0);
+        },
+        render: (result) => (result['note'] !== undefined ? String(result['note']) : ''),
+    });
+}
+export function registerAttach(namespace, tier) {
     return defineBranch({
         name: 'attach',
+        description: 'a terminal viewer for a headless node — connect over its socket and drive (or watch) the live engine',
+        whenToUse: 'you want to open a headless node live in this pane — watch its engine stream and drive it by typing, without the node ever running pi in your window. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects over a unix socket; this local process never starts the engine itself. Configured detach shortcuts leave the engine running.',
+        tier,
         rootEntry: {
             concept: 'a terminal viewer for a headless node — connect over its socket and drive (or watch) the live engine',
             desc: 'attach a terminal viewer to a headless node',
             useWhen: 'you want to open a headless node live in this pane — watch its engine stream and drive it by typing, without the node ever running pi in your window. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects over a unix socket; this local process never starts the engine itself. Configured detach shortcuts leave the engine running.',
         },
         help: {
-            name: 'attach',
+            name: `${namespace} attach`,
             summary: 'attach a terminal viewer to a headless node\'s running broker',
             model: 'The branch opens a viewer in the current pane. A TTY is required; piped invocation prints a notice and exits. Normal local attaches request the writable controller role; --observer and --canvas are read-only. Multiple local writable viewers may watch and drive one broker. Configured detach shortcuts detach cleanly and the engine runs on. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects. If the broker exits, the viewer holds the pane and auto-reconnects — through a yield/refresh relaunch, and across dormancy until the node wakes again — reporting "broker gone" and exiting only when the node is terminal (done/dead/canceled) or deleted. This local process NEVER spawns pi or writes the session — it holds only a socket to the broker. --canvas <name> is the escape hatch for a node hosted on a different machine\'s canvas — see the leaf\'s own -h.',
         },
-        children: [attachToLeaf],
+        children: [attachToLeaf(namespace)],
     });
 }

package/dist/clients/attach/input/capabilities.d.ts

@@ -0,0 +1,27 @@
+import type { ClientRole, ClientToBroker } from '../../../core/runtime/broker-protocol.js';
+/** Actions the attach input surface may perform. Frame-level broker enforcement
+ * remains authoritative; this is the viewer-side refusal contract. */
+export type ViewerOperation = 'engine-drive' | 'dequeue' | 'wake-dormant' | 'auth' | 'canvas-resume' | 'local-canvas-inspect' | 'canvas-inbox';
+export interface ViewerCapabilities {
+    readonly role: ClientRole;
+    readonly remote: boolean;
+    readonly nodeId: string;
+    readonly profileId: string | undefined;
+    readonly permittedOperations: ReadonlySet<ViewerOperation>;
+    permits(operation: ViewerOperation): boolean;
+    refusal(operation: ViewerOperation, command?: string): string | undefined;
+}
+export interface ViewerCapabilityInput {
+    role: ClientRole;
+    remote: boolean;
+    nodeId: string;
+    profileId: string | undefined;
+}
+/** Build the one authority for a viewer session. Remote viewers are observers
+ * even when a caller supplied a controller role; keep that invariant local to
+ * this construction boundary. */
+export declare function createViewerCapabilities(input: ViewerCapabilityInput): ViewerCapabilities;
+/** The slash dispatcher asks the capability model for a command's operation;
+ * commands with no returned operation are viewer-local/read-only. */
+export declare function viewerOperationForFrame(frame: ClientToBroker): ViewerOperation | undefined;
+export declare function viewerOperationForSlash(name: string, builtin: boolean, canvas: boolean): ViewerOperation | undefined;