sh3-core 0.14.0 → 0.14.3

package/dist/shell-shard/dispatch-custom.test.js

@@ -16,12 +16,14 @@ function makeStubDeps(mode, customMode) {
     return {
         deps: {
             mode: () => mode,
+            role: () => 'user',
             resolver,
             scrollback,
             session,
             shell,
             fs,
             cwd: () => '/',
+            busy: () => () => { },
             customMode,
         },
         pushed,
@@ -102,3 +104,49 @@ describe('dispatch — custom transport', () => {
         expect(err.text).toMatch(/no longer available/);
     });
 });
+describe('dispatch — auto-spinner', () => {
+    it('acquires a busy slot for the duration of a custom-mode dispatch', async () => {
+        let active = 0;
+        let peak = 0;
+        const busy = () => {
+            active++;
+            peak = Math.max(peak, active);
+            return () => { active--; };
+        };
+        let resolveDispatch;
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: () => new Promise((resolve) => {
+                resolveDispatch = resolve;
+            }),
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(Object.assign(Object.assign({}, deps), { busy }));
+        const promise = dispatch('hi');
+        // Yield once so the dispatch closure runs through to the await on desc.dispatch
+        await Promise.resolve();
+        expect(peak).toBe(1);
+        expect(active).toBe(1);
+        resolveDispatch();
+        await promise;
+        expect(active).toBe(0);
+    });
+    it('clears busy when the dispatch handler throws', async () => {
+        let active = 0;
+        const busy = () => { active++; return () => { active--; }; };
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: async () => { throw new Error('kaboom'); },
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(Object.assign(Object.assign({}, deps), { busy }));
+        await dispatch('hi');
+        expect(active).toBe(0);
+    });
+});

package/dist/shell-shard/dispatch-gating.test.d.ts

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

package/dist/shell-shard/dispatch-gating.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from 'vitest';
+import { makeDispatch } from './dispatch';
+const appsVerb = { name: 'apps', summary: '', async run() { } };
+const clearVerb = {
+    name: 'clear',
+    summary: '',
+    globalVerb: true,
+    async run(ctx) {
+        ctx.scrollback.push({ kind: 'status', text: 'cleared', level: 'info', ts: 0 });
+    },
+};
+function scaffold(mode) {
+    const sent = [];
+    const pushed = [];
+    const scrollback = { push: (e) => pushed.push(e), clear: () => { } };
+    const session = { history: { push: vi.fn() }, send: (m) => sent.push(m), cwd: '/', connected: true, connect: vi.fn() };
+    const fs = {};
+    const shell = {};
+    // Real-shape resolver to exercise the new globalOnly path.
+    const resolver = {
+        resolve: (line, opts = {}) => {
+            const head = line.trim().split(/\s+/)[0];
+            const verb = head === 'apps' ? appsVerb : head === 'clear' ? clearVerb : null;
+            if (!verb)
+                return { kind: 'forward', line };
+            if (opts.globalOnly && !verb.globalVerb)
+                return { kind: 'forward', line };
+            return { kind: 'local', verb, args: [], line };
+        },
+    };
+    const { dispatch } = makeDispatch({
+        mode: () => mode,
+        role: () => (mode.requiresRole === 'admin' ? 'admin' : 'user'),
+        resolver,
+        scrollback,
+        session,
+        shell,
+        fs,
+        cwd: () => '/',
+        busy: () => () => { },
+    });
+    return { dispatch, sent, pushed };
+}
+describe('dispatch — mode-gated verb resolution', () => {
+    const sh3Mode = { id: 'sh3', label: 'SH3', transport: 'none', autoRelocate: true };
+    const bashMode = { id: 'bash', label: 'Bash', transport: 'ws', autoRelocate: false, requiresRole: 'admin' };
+    it('sh3 mode resolves sh3-domain verbs locally', async () => {
+        const { dispatch, sent } = scaffold(sh3Mode);
+        await dispatch('apps');
+        expect(sent).toEqual([]);
+    });
+    it('bash mode forwards sh3-domain verbs to ws', async () => {
+        const { dispatch, sent } = scaffold(bashMode);
+        await dispatch('apps');
+        expect(sent.some((m) => m.t === 'submit' && m.line === 'apps')).toBe(true);
+    });
+    it('bash mode runs globalVerb (clear) locally', async () => {
+        const { dispatch, sent, pushed } = scaffold(bashMode);
+        await dispatch('clear');
+        expect(sent.every((m) => m.t !== 'submit')).toBe(true);
+        expect(pushed.some((e) => e.kind === 'status' && e.text === 'cleared')).toBe(true);
+    });
+});

package/dist/shell-shard/dispatch-invoke.test.d.ts

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

package/dist/shell-shard/dispatch-invoke.test.js

@@ -0,0 +1,214 @@
+import { describe, it, expect, vi } from 'vitest';
+import { makeDispatch } from './dispatch';
+const openVerb = {
+    name: 'open',
+    summary: '',
+    async run(ctx, args) {
+        var _a;
+        ctx.scrollback.push({ kind: 'status', text: `opened:${(_a = args[0]) !== null && _a !== void 0 ? _a : ''}`, level: 'info', ts: 0 });
+    },
+};
+function scaffold(opts) {
+    const sent = [];
+    const pushed = [];
+    const connectSpy = vi.fn();
+    const scrollback = { push: (e) => pushed.push(e), clear: () => { } };
+    const session = {
+        history: { push: vi.fn() },
+        send: (m) => sent.push(m),
+        cwd: '/',
+        connect: connectSpy,
+    };
+    const fs = {};
+    const shell = {};
+    const resolver = {
+        resolve: (line, _opts = {}) => {
+            const head = line.trim().split(/\s+/)[0];
+            const rest = line.trim().split(/\s+/).slice(1);
+            if (head === 'open')
+                return { kind: 'local', verb: openVerb, args: rest, line };
+            return { kind: 'forward', line };
+        },
+    };
+    const { dispatch } = makeDispatch({
+        mode: () => opts.current,
+        role: () => opts.role,
+        resolver,
+        scrollback,
+        session,
+        shell,
+        fs,
+        cwd: () => '/',
+        busy: () => () => { },
+        customMode: (id) => { var _a, _b; return (_b = (_a = opts.customs) === null || _a === void 0 ? void 0 : _a.find((d) => d.id === id)) !== null && _b !== void 0 ? _b : null; },
+    });
+    return { dispatch, sent, pushed, connectSpy };
+}
+const customMode = (id) => ({ id, label: id, transport: 'custom', autoRelocate: false });
+describe('output.invoke — sh3 target', () => {
+    it('runs an sh3 verb when invoked from a custom mode', async () => {
+        const captured = [];
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('sh3', 'open foo.md');
+                    captured.push('after-invoke');
+                },
+            }];
+        const { dispatch, pushed } = scaffold({
+            current: customMode('gemini'),
+            role: 'user',
+            customs,
+        });
+        await dispatch('hello');
+        expect(pushed.some((e) => e.kind === 'status' && e.text === 'opened:foo.md')).toBe(true);
+        expect(captured).toEqual(['after-invoke']);
+    });
+    it('throws for unknown sh3 verb', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('sh3', 'nonexistent');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/unknown sh3 verb/);
+    });
+});
+describe('output.invoke — bash target', () => {
+    it('admin invocation lazy-connects and forwards', async () => {
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('bash', 'ls');
+                },
+            }];
+        const { dispatch, sent, connectSpy } = scaffold({
+            current: customMode('gemini'),
+            role: 'admin',
+            customs,
+        });
+        await dispatch('hello');
+        expect(connectSpy).toHaveBeenCalledTimes(1);
+        expect(sent.some((m) => m.t === 'submit' && m.line === 'ls')).toBe(true);
+    });
+    it('lazy-connect only fires once across multiple invokes', async () => {
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('bash', 'ls');
+                    await output.invoke('bash', 'pwd');
+                },
+            }];
+        const { dispatch, connectSpy } = scaffold({
+            current: customMode('gemini'),
+            role: 'admin',
+            customs,
+        });
+        await dispatch('hello');
+        expect(connectSpy).toHaveBeenCalledTimes(1);
+    });
+    it('non-admin invoking bash throws', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('bash', 'ls');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/admin role/);
+    });
+});
+describe('output.invoke — guards', () => {
+    it('self-invoke throws', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('gemini', 'foo');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/cannot invoke own mode/);
+    });
+    it('unknown custom mode throws', async () => {
+        let caught;
+        const customs = [{
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    try {
+                        await output.invoke('claude', 'foo');
+                    }
+                    catch (e) {
+                        caught = e;
+                    }
+                },
+            }];
+        const { dispatch } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/unknown mode/);
+    });
+});
+describe('output.invoke — custom target', () => {
+    it('routes through the target descriptor dispatch with the same scrollback', async () => {
+        const customs = [
+            {
+                id: 'gemini',
+                label: 'Gemini',
+                runsOn: 'client',
+                dispatch: async (_input, output) => {
+                    await output.invoke('claude', 'hi');
+                },
+            },
+            {
+                id: 'claude',
+                label: 'Claude',
+                runsOn: 'client',
+                dispatch: async (input, output) => {
+                    output.text('stdout', `claude:${input.line}\n`);
+                },
+            },
+        ];
+        const { dispatch, pushed } = scaffold({ current: customMode('gemini'), role: 'user', customs });
+        await dispatch('hello');
+        expect(pushed.some((e) => { var _a, _b; return e.kind === 'text' && ((_b = (_a = e.chunks) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.includes('claude:hi')); })).toBe(true);
+    });
+});

package/dist/shell-shard/dispatch.d.ts

@@ -2,16 +2,24 @@ import type { VerbRegistry, ShellApi } from './registry';
 import type { Scrollback } from './scrollback.svelte';
 import type { SessionClient } from './session-client.svelte';
 import type { TenantFsClient } from './tenant-fs-client';
-import type { ShellMode } from './modes/types';
+import type { ShellMode, ShellRole } from './modes/types';
 import type { ShellModeDescriptor } from './contract';
 export interface DispatchDeps {
     mode: () => ShellMode;
+    /** Current shell role — used by invoke() role-gating. */
+    role: () => ShellRole;
     resolver: VerbRegistry;
     scrollback: Scrollback;
     session: SessionClient;
     shell: ShellApi;
     fs: TenantFsClient;
     cwd: () => string;
+    /**
+     * Acquire a busy indicator. Returns a clear handle. Calling clear()
+     * multiple times is safe (idempotent). Used internally to auto-spawn
+     * a spinner around custom-mode dispatch and exposed via output.busy().
+     */
+    busy: (label?: string) => () => void;
     /**
      * Look up a contributed mode descriptor by id. Called only when the active
      * mode has `transport: 'custom'`. Returns null if the descriptor has been

package/dist/shell-shard/dispatch.js

@@ -11,6 +11,67 @@
 import { makeShellModeOutput } from './output';
 export function makeDispatch(deps) {
     let activeController = null;
+    /**
+     * Programmatic cross-mode dispatch. Validates target id, role gate, and
+     * self-invoke; routes to sh3 (full local resolution), bash (WS forward
+     * with lazy connect), or a custom descriptor (recursive desc.dispatch).
+     *
+     * sh3 path bypasses mode gating: a verb's globalVerb flag is irrelevant
+     * because the caller is a trusted mode shard, not user input from a
+     * different mode.
+     */
+    let bashConnected = false;
+    async function invoke(modeId, line) {
+        var _a, _b, _c, _d;
+        const current = deps.mode();
+        if (modeId === current.id) {
+            throw new Error(`invoke: cannot invoke own mode '${modeId}'`);
+        }
+        if (modeId === 'sh3') {
+            const resolution = deps.resolver.resolve(line, { globalOnly: false });
+            if (resolution.kind === 'forward') {
+                const head = (_a = line.trim().split(/\s+/)[0]) !== null && _a !== void 0 ? _a : '';
+                throw new Error(`invoke: unknown sh3 verb '${head}'`);
+            }
+            await resolution.verb.run({
+                shell: deps.shell,
+                scrollback: deps.scrollback,
+                session: deps.session,
+                cwd: deps.cwd(),
+                dispatch,
+                fs: deps.fs,
+            }, resolution.args);
+            return;
+        }
+        if (modeId === 'bash') {
+            if (deps.role() !== 'admin') {
+                throw new Error("invoke: 'bash' requires admin role");
+            }
+            if (!bashConnected) {
+                bashConnected = true;
+                deps.session.connect();
+            }
+            deps.session.send({ t: 'submit', line });
+            return;
+        }
+        // Custom mode
+        const desc = (_c = (_b = deps.customMode) === null || _b === void 0 ? void 0 : _b.call(deps, modeId)) !== null && _c !== void 0 ? _c : null;
+        if (!desc) {
+            throw new Error(`invoke: unknown mode '${modeId}'`);
+        }
+        if (desc.requiresRole && desc.requiresRole !== deps.role()) {
+            throw new Error(`invoke: mode '${modeId}' requires ${desc.requiresRole} role`);
+        }
+        if (desc.runsOn === 'server') {
+            throw new Error('invoke: server-side modes are not yet supported');
+        }
+        const subOutput = makeShellModeOutput({
+            scrollback: deps.scrollback,
+            busy: deps.busy,
+            invoke,
+        });
+        await desc.dispatch({ line, cwd: deps.cwd(), signal: (_d = activeController === null || activeController === void 0 ? void 0 : activeController.signal) !== null && _d !== void 0 ? _d : new AbortController().signal }, subOutput);
+    }
     async function dispatch(line) {
         var _a, _b, _c, _d;
         // Abort any in-flight custom dispatch when a new line is submitted.
@@ -25,7 +86,9 @@ export function makeDispatch(deps) {
             deps.scrollback.push({ kind: 'status', text: 'shell: server shell not available in user mode', level: 'error', ts: Date.now() });
             return;
         }
-        const resolution = deps.resolver.resolve(line);
+        const resolution = deps.resolver.resolve(line, {
+            globalOnly: mode.id !== 'sh3',
+        });
         if (resolution.kind === 'local') {
             // Log locally-dispatched verbs for shared history (ws only)
             if (mode.transport === 'ws') {
@@ -78,7 +141,12 @@ export function makeDispatch(deps) {
                 });
                 return;
             }
-            const output = makeShellModeOutput(deps.scrollback);
+            const output = makeShellModeOutput({
+                scrollback: deps.scrollback,
+                busy: deps.busy,
+                invoke,
+            });
+            const clearBusy = deps.busy();
             try {
                 await desc.dispatch({ line: resolution.line, cwd: deps.cwd(), signal: controller.signal }, output);
             }
@@ -95,6 +163,9 @@ export function makeDispatch(deps) {
                     });
                 }
             }
+            finally {
+                clearBusy();
+            }
             return;
         }
         // 'none' transport, unknown verb: print error

package/dist/shell-shard/output.d.ts

@@ -1,3 +1,10 @@
 import type { Scrollback } from './scrollback.svelte';
 import type { ShellModeOutput } from './contract';
-export declare function makeShellModeOutput(sb: Scrollback): ShellModeOutput;
+export interface ShellModeOutputDeps {
+    scrollback: Scrollback;
+    /** Acquire a busy indicator; returns a clear handle. */
+    busy: (label?: string) => () => void;
+    /** Programmatically dispatch a line through another mode's resolution path. */
+    invoke: (modeId: string, line: string) => Promise<void>;
+}
+export declare function makeShellModeOutput(deps: ShellModeOutputDeps): ShellModeOutput;

package/dist/shell-shard/output.js

@@ -24,7 +24,8 @@ function lastRichId(sb) {
     const last = sb.entries[sb.entries.length - 1];
     return last.id;
 }
-export function makeShellModeOutput(sb) {
+export function makeShellModeOutput(deps) {
+    const sb = deps.scrollback;
     return {
         text(stream, chunk) {
             sb.push({ kind: 'text', stream, chunks: [chunk], ts: Date.now() });
@@ -71,5 +72,20 @@ export function makeShellModeOutput(sb) {
                 },
             };
         },
+        busy(label) {
+            const clearController = deps.busy(label);
+            let cleared = false;
+            return {
+                clear() {
+                    if (cleared)
+                        return;
+                    cleared = true;
+                    clearController();
+                },
+            };
+        },
+        invoke(modeId, line) {
+            return deps.invoke(modeId, line);
+        },
     };
 }

package/dist/shell-shard/output.test.js

@@ -2,10 +2,12 @@ import { describe, it, expect } from 'vitest';
 import { Scrollback } from './scrollback.svelte';
 import { makeShellModeOutput } from './output';
 const FakeComponent = (() => { });
+const stubBusy = () => () => { };
+const stubInvoke = async () => { };
 describe('makeShellModeOutput', () => {
     it('text() pushes coalescing text entries', () => {
         const sb = new Scrollback();
-        const out = makeShellModeOutput(sb);
+        const out = makeShellModeOutput({ scrollback: sb, busy: stubBusy, invoke: stubInvoke });
         out.text('stdout', 'hello ');
         out.text('stdout', 'world');
         const text = sb.entries.filter((e) => e.kind === 'text');
@@ -14,7 +16,7 @@ describe('makeShellModeOutput', () => {
     });
     it('status() pushes a status entry with the right level', () => {
         const sb = new Scrollback();
-        const out = makeShellModeOutput(sb);
+        const out = makeShellModeOutput({ scrollback: sb, busy: stubBusy, invoke: stubInvoke });
         out.status('warn', 'careful');
         const s = sb.entries.find((e) => e.kind === 'status');
         expect(s).toBeDefined();
@@ -23,7 +25,7 @@ describe('makeShellModeOutput', () => {
     });
     it('rich().update() mutates the live entry props', () => {
         const sb = new Scrollback();
-        const out = makeShellModeOutput(sb);
+        const out = makeShellModeOutput({ scrollback: sb, busy: stubBusy, invoke: stubInvoke });
         const handle = out.rich(FakeComponent, { tokens: 'a' });
         handle.update({ tokens: 'ab' });
         const entry = sb.entries.find((e) => e.kind === 'rich');
@@ -31,7 +33,7 @@ describe('makeShellModeOutput', () => {
     });
     it('stream() marks the entry mid-stream until complete()', () => {
         const sb = new Scrollback();
-        const out = makeShellModeOutput(sb);
+        const out = makeShellModeOutput({ scrollback: sb, busy: stubBusy, invoke: stubInvoke });
         const h = out.stream(FakeComponent, { tokens: '' });
         let entry = sb.entries.find((e) => e.kind === 'rich');
         expect(entry.props.__streamState).toBe('streaming');
@@ -42,7 +44,7 @@ describe('makeShellModeOutput', () => {
     });
     it('stream().error() marks the entry errored and pushes a status', () => {
         const sb = new Scrollback();
-        const out = makeShellModeOutput(sb);
+        const out = makeShellModeOutput({ scrollback: sb, busy: stubBusy, invoke: stubInvoke });
         const h = out.stream(FakeComponent, { tokens: '' });
         h.error(new Error('boom'));
         const entry = sb.entries.find((e) => e.kind === 'rich');
@@ -52,3 +54,20 @@ describe('makeShellModeOutput', () => {
         expect(s.text).toMatch(/boom/);
     });
 });
+describe('makeShellModeOutput — busy', () => {
+    it('forwards busy() to the controller and clear() is idempotent', () => {
+        const calls = [];
+        let cleared = 0;
+        const sb = new Scrollback();
+        const busy = (label) => {
+            calls.push(`acquire:${label !== null && label !== void 0 ? label : ''}`);
+            return () => { cleared++; };
+        };
+        const out = makeShellModeOutput({ scrollback: sb, busy, invoke: stubInvoke });
+        const h = out.busy('thinking');
+        expect(calls).toEqual(['acquire:thinking']);
+        h.clear();
+        h.clear();
+        expect(cleared).toBe(1);
+    });
+});

package/dist/shell-shard/registry-resolve.test.d.ts

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

package/dist/shell-shard/registry-resolve.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { VerbRegistry } from './registry';
+import { registerVerb, __resetViewRegistryForTest } from '../shards/registry';
+const sh3Verb = { name: 'apps', summary: '', async run() { } };
+const globalVerb = { name: 'clear', summary: '', globalVerb: true, async run() { } };
+describe('VerbRegistry.resolve — globalOnly option', () => {
+    beforeEach(() => {
+        __resetViewRegistryForTest();
+        registerVerb('apps', sh3Verb);
+        registerVerb('clear', globalVerb);
+    });
+    it('without globalOnly resolves any registered verb', () => {
+        const r = new VerbRegistry();
+        expect(r.resolve('apps').kind).toBe('local');
+        expect(r.resolve('clear').kind).toBe('local');
+    });
+    it('with globalOnly only resolves globalVerb=true entries', () => {
+        const r = new VerbRegistry();
+        expect(r.resolve('apps', { globalOnly: true }).kind).toBe('forward');
+        expect(r.resolve('clear', { globalOnly: true }).kind).toBe('local');
+    });
+    it('the $ escape always forwards regardless of globalOnly', () => {
+        const r = new VerbRegistry();
+        expect(r.resolve('$ ls', { globalOnly: true }).kind).toBe('forward');
+    });
+});

package/dist/shell-shard/registry.d.ts

@@ -3,5 +3,16 @@ export type { Verb, VerbContext, Resolution, ShellApi };
 export declare class VerbRegistry {
     list(): Verb[];
     get(name: string): Verb | undefined;
-    resolve(line: string): Resolution;
+    /**
+     * Resolve a submitted line to a local verb or a forward instruction.
+     *
+     * @param line The user-submitted line.
+     * @param opts.globalOnly When true, only verbs declared with `globalVerb:
+     *   true` resolve locally; everything else forwards. Used by the dispatch
+     *   path to gate sh3-domain verbs to sh3 mode while keeping framework
+     *   controls (clear, mode) reachable from every mode.
+     */
+    resolve(line: string, opts?: {
+        globalOnly?: boolean;
+    }): Resolution;
 }

package/dist/shell-shard/registry.js

@@ -14,7 +14,16 @@ export class VerbRegistry {
     get(name) {
         return getVerb(name);
     }
-    resolve(line) {
+    /**
+     * Resolve a submitted line to a local verb or a forward instruction.
+     *
+     * @param line The user-submitted line.
+     * @param opts.globalOnly When true, only verbs declared with `globalVerb:
+     *   true` resolve locally; everything else forwards. Used by the dispatch
+     *   path to gate sh3-domain verbs to sh3 mode while keeping framework
+     *   controls (clear, mode) reachable from every mode.
+     */
+    resolve(line, opts = {}) {
         const trimmed = line.trim();
         if (!trimmed)
             return { kind: 'forward', line };
@@ -32,6 +41,8 @@ export class VerbRegistry {
         const verb = getVerb(head);
         if (!verb)
             return { kind: 'forward', line };
+        if (opts.globalOnly && !verb.globalVerb)
+            return { kind: 'forward', line };
         // Simple space-split for args — verbs can re-tokenize if they need quoting
         const args = rest.length ? rest.split(/\s+/) : [];
         return { kind: 'local', verb, args, line };