@orboto/mcp 0.204.0 → 0.205.0

package/README.md

@@ -119,7 +119,7 @@ Omit `ORBOTO_API_KEY` to use OAuth login instead. `codex mcp add` writes the sam
 | `ORBOTO_MCP_TOKEN_CACHE` | no | Override the OAuth token cache path (default `~/.config/orboto/mcp-oauth.json`). |
 | `ORBOTO_MCP_NO_BROWSER` | no | Set to `1` to print the authorization URL instead of auto-opening a browser (headless hosts). |
 | `ORBOTO_MCP_TRANSPORT` | no | `stdio` (default) or `http`. Stdio is the right choice for `npx`-launched clients. |
-| `ORBOTO_MCP_TOOLSET` | no | `minimal`, `curated` (default) or `full`. Curated is the measured high-frequency set (31 tools, ~7.8k tokens of schemas at connect) - the whole REST API stays reachable via `orboto_api_search` + `orboto_api_call`. `full` registers every named tool (175, ~39.5k tokens). `minimal` is the daily loop only (12 tools, ~2.8k tokens including the instructions block) for local models with an 8k/16k context window. HTTP clients can pick per connection instead: `?toolset=minimal` on the `/mcp` URL or an `x-orboto-toolset: minimal` header. |
+| `ORBOTO_MCP_TOOLSET` | no | `channel`, `minimal`, `curated` (default) or `full`. `channel` registers no tool, prompt or resource: the agent works through the `orboto` CLI, the server carries the Claude Code wake channel and an instructions block under 400 tokens - it is what `orboto mcp install`, `orboto connect` and the Claude Code plugin write. Curated is the measured high-frequency set (31 tools, ~7.8k tokens of schemas at connect) - the whole REST API stays reachable via `orboto_api_search` + `orboto_api_call`. `full` registers every named tool (175, ~39.5k tokens). `minimal` is the daily loop only (12 tools, ~2.8k tokens including the instructions block) for local models with an 8k/16k context window. HTTP clients can pick per connection instead: `?toolset=minimal` on the `/mcp` URL or an `x-orboto-toolset: minimal` header. |
 | `ORBOTO_MCP_PORT` | no | Listen port when transport is `http`. Default `3100`. |
 | `ORBOTO_MCP_CLIENT` | no | User-agent suffix that lands in the API audit log. Useful for filtering audit rows by client. |
 | `ORBOTO_MCP_CHANNEL` | no | `1` (default) makes the stdio proxy a Claude Code channel: it follows the session's inbox stream and pushes each message as a `notifications/claude/channel` event that wakes the session (`claude --dangerously-load-development-channels server:orboto`, ORB-2140). `0` disables it. |

package/dist/channel-toolset.test.js

@@ -0,0 +1,90 @@
+/**
+ * ORB-2210 - the `channel` toolset: no tools, CLI-first instructions, and
+ * the wake channel still delivers into the connected session.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { z } from 'zod';
+import { buildOrbotoMcpServer } from './server.js';
+import { CHANNEL_CAPABILITY, CHANNEL_METHOD, InboxChannel } from './inbox-channel.js';
+import { resolveToolset, toolInToolset } from './toolset.js';
+beforeEach(() => { delete process.env.ORBOTO_MCP_TOOLSET; });
+afterEach(() => { vi.restoreAllMocks(); delete process.env.ORBOTO_MCP_TOOLSET; });
+const ChannelNotification = z.object({
+    method: z.literal(CHANNEL_METHOD),
+    params: z.object({ content: z.string(), meta: z.record(z.string()) }),
+});
+function sse(frames) {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            for (const frame of frames)
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`));
+            controller.close();
+        },
+    });
+    return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream' } });
+}
+async function connectChannelServer() {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
+    const server = await buildOrbotoMcpServer({ baseUrl: 'https://x.test', apiKey: 'orb_k', channel: true, toolset: 'channel' });
+    const client = new Client({ name: 't', version: '0' });
+    const [a, b] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(a), client.connect(b)]);
+    return { server, client, fetchSpy };
+}
+describe('resolveToolset / toolInToolset - channel', () => {
+    it('channel resolves from either surface and admits no tool', () => {
+        expect(resolveToolset('channel', undefined)).toBe('channel');
+        expect(resolveToolset(undefined, 'channel')).toBe('channel');
+        expect(resolveToolset('channel', 'full')).toBe('channel');
+        for (const name of ['orboto_session_start', 'orboto_get_ticket', 'orboto_api_call', 'orboto_messages']) {
+            expect(toolInToolset(name, 'channel'), name).toBe(false);
+        }
+    });
+});
+describe('ORB-2210 - the channel toolset', () => {
+    it('starts, answers initialize, registers no tool, prompt or resource, and fetches no rules at connect', async () => {
+        const { server, client, fetchSpy } = await connectChannelServer();
+        expect(client.getServerVersion()?.name).toBe('orboto');
+        expect(client.getServerCapabilities()?.tools).toBeUndefined();
+        expect(client.getServerCapabilities()?.prompts).toBeUndefined();
+        expect(client.getServerCapabilities()?.resources).toBeUndefined();
+        expect(client.getServerCapabilities()?.experimental).toHaveProperty(CHANNEL_CAPABILITY);
+        expect(fetchSpy).not.toHaveBeenCalled();
+        await client.close();
+        await server.close();
+    });
+    it('instructions point at the CLI, the scope command and the way back to the tools', async () => {
+        const { server, client } = await connectChannelServer();
+        const text = client.getInstructions() ?? '';
+        expect(text).toContain('`orboto help`');
+        expect(text).toContain('orboto session-start');
+        expect(text).toContain('orboto agent-heartbeat --role');
+        expect(text).toContain('--scope-projects');
+        expect(text).toContain('ORBOTO_MCP_TOOLSET=curated|full');
+        expect(text).toContain('orboto messages --ack');
+        expect(text).not.toMatch(/orboto_[a-z_]+/);
+        await client.close();
+        await server.close();
+    });
+    it('a streamed inbox message reaches the connected client as a channel event', async () => {
+        const { server, client } = await connectChannelServer();
+        const received = [];
+        client.setNotificationHandler(ChannelNotification, (n) => { received.push(n.params); });
+        const fetchFn = vi.fn().mockResolvedValueOnce(sse([{
+                id: 'm1', fromUserId: 'u-spec', kind: 'request', subject: 'ticket-ready:ORB-1', payload: { message: 'please take it' },
+                threadId: null, projectKey: 'ORB', createdAt: new Date().toISOString(),
+            }])).mockImplementation(() => new Promise(() => { }));
+        const inbox = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp: server, fetchFn, log: () => { }, digestMinutes: 15 });
+        inbox.start();
+        await vi.waitFor(() => expect(received).toHaveLength(1));
+        expect(received[0].meta).toMatchObject({ id: 'm1', kind: 'request', project: 'ORB' });
+        expect(received[0].content).toContain('ticket-ready:ORB-1');
+        expect(inbox.stats.delivered).toBe(1);
+        inbox.close();
+        await client.close();
+        await server.close();
+    });
+});

package/dist/connect-script.js

@@ -1,7 +1,7 @@
 /**
  * ORB-2157 - the one source of the script an agent follows when a person
  * asks it to set orboto up. `orboto_help { topic: "connect" }` returns it,
- * docs/connect-your-agent.md, docs/claude-code.md and skills/orboto/SKILL.md
+ * docs/connect-your-agent.md, docs/claude-code.md and skills/orboto/reference/agents.md
  * carry the same sentences, and connect-script.test.ts holds them together.
  */
 export const CONNECT_SCRIPT_HEADING = 'If you are an AI agent helping a person set this up';

package/dist/connect-script.test.js

@@ -8,7 +8,7 @@ import { readFileSync } from 'node:fs';
 import { CONNECT_SCRIPT_HEADING, CONNECT_SCRIPT_STEPS, connectScriptText } from './connect-script.js';
 import { makeHelpHandler } from './tools/help.js';
 const read = (relative) => readFileSync(new URL(`../../../${relative}`, import.meta.url), 'utf8');
-const CARRIERS = ['docs/connect-your-agent.md', 'docs/claude-code.md', 'skills/orboto/SKILL.md'];
+const CARRIERS = ['docs/connect-your-agent.md', 'docs/claude-code.md', 'skills/orboto/reference/agents.md'];
 describe('the connect script', () => {
     it('reads as a numbered script with the pages it links', () => {
         const text = connectScriptText();

package/dist/inbox-channel.js

@@ -1,4 +1,5 @@
 import { RESTART_REQUESTED_NOTICE, writeRestartRequest } from './session-restart.js';
+import { confirmScope, rememberedScope } from './session-scope-memory.js';
 export { RESTART_REQUESTED_NOTICE };
 export const CHANNEL_METHOD = 'notifications/claude/channel';
 export const CHANNEL_CAPABILITY = 'claude/channel';
@@ -19,7 +20,8 @@ export const CHANNEL_INSTRUCTIONS = 'Inbox channel: messages for THIS session ar
     + 'not_mine for another session\'s mail (the sender is told, and the message never reaches this session again), obsolete or duplicate with a note when the request is already done. '
     + 'A session that declared no scope is woken by mail addressed to it and by broadcasts only, and gets one notice event saying so on connect: '
     + 'declare the scope with orboto_session_start { scope: { role, projectKeys } } to be woken by the account\'s project mail again - '
-    + 'the rest of the account\'s inbox stays readable with orboto_messages the whole time.';
+    + 'the rest of the account\'s inbox stays readable with orboto_messages the whole time. '
+    + 'Declare it once: the session keeps its id and scope across reconnects and restarts of this terminal.';
 const START_FLAG = '--dangerously-load-development-channels server:orboto';
 /** ORB-2148 - the commands an agent hands its operator verbatim; docs/claude-code.md carries the same lines. */
 export const CHANNEL_START_COMMANDS = {
@@ -119,6 +121,8 @@ export class InboxChannel {
     batch = [];
     /** Counters an operator can read from the log; tests read them directly. */
     stats = { delivered: 0, digested: 0, duplicates: 0, reconnects: 0, notices: 0 };
+    /** ORB-2209 - what the server said on the last connect. */
+    session = null;
     constructor(opts) {
         this.opts = opts;
         this.log = opts.log ?? ((msg) => { try {
@@ -179,6 +183,12 @@ export class InboxChannel {
         }
         await this.emit({ content, meta: { kind: 'notice', notice } });
     }
+    /** ORB-2209 - the id and scope the server resumed; never a channel event. */
+    applySession(session) {
+        this.session = session;
+        confirmScope(this.opts.instanceToken, session.scope ?? null);
+        this.log(`inbox session ${session.id.slice(0, 8)}${session.resumed ? ` resumed (reconnect ${session.reconnects})` : ''}${session.scopeRestored ? ', scope re-declared' : ''}`);
+    }
     /** ORB-2181 - an admin restart notice becomes the supervisor's request file. */
     takeRestartRequest(reason) {
         try {
@@ -237,7 +247,9 @@ export class InboxChannel {
         const fetchFn = this.opts.fetchFn ?? fetch;
         this.abort = new AbortController();
         const since = this.lastId ?? this.since;
-        const url = `${this.opts.baseUrl.replace(/\/$/, '')}/v1/agent/messages/stream?since=${encodeURIComponent(since)}`;
+        const resent = rememberedScope(this.opts.instanceToken);
+        const url = `${this.opts.baseUrl.replace(/\/$/, '')}/v1/agent/messages/stream?since=${encodeURIComponent(since)}&sessionFrame=1`
+            + (resent ? `&declaredScope=${encodeURIComponent(JSON.stringify(resent))}` : '');
         const bearer = this.opts.tokenProvider ? await this.opts.tokenProvider.getAccessToken() : (this.opts.apiKey ?? '');
         const res = await fetchFn(url, {
             method: 'GET',
@@ -280,6 +292,10 @@ export class InboxChannel {
                     catch {
                         continue;
                     }
+                    if (parsed.session) {
+                        this.applySession(parsed.session);
+                        continue;
+                    }
                     if (parsed.notice) {
                         await this.deliverNotice(parsed.notice, parsed.content ?? '');
                         continue;

package/dist/inbox-channel.test.js

@@ -7,6 +7,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, CLI_OUTDATED_NOTICE, InboxChannel, RESTART_REQUESTED_NOTICE, cliOutdatedNotice, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
 import { buildOrbotoMcpServer } from './server.js';
+import { _forgetDeclaredScopes, rememberDeclaredScope, rememberedScope } from './session-scope-memory.js';
 function mockMcp() {
     const notification = vi.fn().mockResolvedValue(undefined);
     return { mcp: { server: { notification } }, notification };
@@ -97,6 +98,52 @@ describe('InboxChannel', () => {
         expect(channel.stats.reconnects).toBeGreaterThanOrEqual(1);
         channel.close();
     });
+    it('ORB-2209 - every reconnect sends the same instance token, re-sends the declared scope and applies the session frame without an event', async () => {
+        _forgetDeclaredScopes();
+        rememberDeclaredScope('mcp-proc', { role: 'worker', projectKeys: ['ORB'] });
+        const { mcp, notification } = mockMcp();
+        const frame = (count) => ({ session: { id: 'sess-1111', scope: { role: 'worker', projectKeys: ['ORB'] }, resumed: count > 0, scopeRestored: false, reconnects: count, lastReconnectAt: count ? '2026-09-18T10:00:02.000Z' : null } });
+        const fetchFn = vi.fn()
+            .mockResolvedValueOnce(sse([frame(0)]))
+            .mockResolvedValueOnce(sse([frame(1)]))
+            .mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        channel.start();
+        await vi.waitFor(() => expect(channel.session?.reconnects).toBe(0));
+        await vi.advanceTimersByTimeAsync(2_000);
+        await vi.waitFor(() => expect(channel.session?.reconnects).toBe(1));
+        expect(fetchFn.mock.calls.length).toBeGreaterThanOrEqual(2);
+        for (const [url, init] of fetchFn.mock.calls.slice(0, 2)) {
+            expect(init.headers['x-orboto-agent-session']).toBe('mcp-proc');
+            expect(String(url)).toContain('sessionFrame=1');
+            expect(decodeURIComponent(String(url))).toContain('declaredScope={"role":"worker","projectKeys":["ORB"]}');
+        }
+        expect(channel.session).toMatchObject({ id: 'sess-1111', resumed: true, scope: { projectKeys: ['ORB'] } });
+        expect(notification).not.toHaveBeenCalled();
+        channel.close();
+    });
+    it('ORB-2209 - a proxy that never declared a scope, or cleared it, re-sends nothing; a server-confirmed scope replaces the remembered one', async () => {
+        _forgetDeclaredScopes();
+        const { mcp } = mockMcp();
+        const fetchFn = vi.fn().mockImplementation(() => new Promise(() => { }));
+        const quiet = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-never', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        quiet.start();
+        await vi.waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(1));
+        expect(String(fetchFn.mock.calls[0][0])).not.toContain('declaredScope');
+        quiet.close();
+        rememberDeclaredScope('mcp-cleared', null);
+        expect(rememberedScope('mcp-cleared')).toBeNull();
+        rememberDeclaredScope('mcp-changed', { projectKeys: ['OLD'] });
+        const changed = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-changed', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        changed.applySession({ id: 's', scope: { projectKeys: ['NEW'] }, resumed: true, scopeRestored: false, reconnects: 3, lastReconnectAt: null });
+        expect(rememberedScope('mcp-changed')).toEqual({ projectKeys: ['NEW'] });
+        changed.applySession({ id: 's', scope: null, resumed: true, scopeRestored: false, reconnects: 4, lastReconnectAt: null });
+        expect(rememberedScope('mcp-changed')).toEqual({ projectKeys: ['NEW'] });
+        rememberDeclaredScope('mcp-never-2', null);
+        const other = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-untouched', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        other.applySession({ id: 's', scope: { projectKeys: ['SRV'] }, resumed: false, scopeRestored: false, reconnects: 0, lastReconnectAt: null });
+        expect(rememberedScope('mcp-untouched')).toBeNull();
+    });
     it('ORB-2151 - a server notice becomes its own event and never becomes the replay anchor', async () => {
         const { mcp, notification } = mockMcp();
         const hint = { notice: 'declare_scope', sessionId: 'cccccccc-0000-4000-8000-000000000000', content: 'declare your scope: orboto_session_start { scope: { role, projectKeys } }' };

package/dist/manifest-size.test.js

@@ -159,3 +159,33 @@ describe('ORB-1805 - minimal manifest fits a small context window', () => {
         expect(curated.instructionsChars).toBeGreaterThan(loaded.instructionsChars);
     });
 });
+/**
+ * ORB-2210 - the `channel` tier registers no tool, so its whole per-turn
+ * cost is the instructions block; 400 tokens is the ceiling the ticket set.
+ */
+const CHANNEL_MAX_TOKENS = 400;
+async function channelInstructions(channel) {
+    const server = await buildOrbotoMcpServer({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test', toolset: 'channel', channel });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'manifest-measure', version: '0.0.0' });
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    try {
+        const tools = client.getServerCapabilities()?.tools ? (await client.listTools()).tools.length : 0;
+        return { tools, instructionsChars: (client.getInstructions() ?? '').length };
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+describe('ORB-2210 - the channel manifest costs only its instructions', () => {
+    it('channel: zero tools, instructions with the wake paragraph stay under 400 estimated tokens', async () => {
+        const withWake = await channelInstructions(true);
+        const bare = await channelInstructions(false);
+        process.stdout.write(`[manifest-size] channel: ${withWake.tools} tools, instructions ${withWake.instructionsChars} chars (~${estTokens(withWake.instructionsChars)} tokens)\n`);
+        expect(withWake.tools).toBe(0);
+        expect(bare.tools).toBe(0);
+        expect(estTokens(withWake.instructionsChars)).toBeLessThanOrEqual(CHANNEL_MAX_TOKENS);
+        expect(bare.instructionsChars).toBeLessThan(withWake.instructionsChars);
+    });
+});

package/dist/server.js

@@ -8,7 +8,7 @@ import { OrbotoClient } from './orboto-client.js';
 import { registerOrbotoResources } from './resources.js';
 import { registerOrbotoPrompts } from './prompts.js';
 import { registerWithMetrics } from './with-metrics.js';
-import { resolveToolset, toolInToolset } from './toolset.js';
+import { CHANNEL_TOOLSET_INSTRUCTIONS, CHANNEL_TOOLSET_WAKE_INSTRUCTIONS, resolveToolset, toolInToolset } from './toolset.js';
 import { createNudgeState } from './session-nudge.js';
 import { aiStatusToolConfig, makeAiStatusHandler } from './tools/ai-status.js';
 import { draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler } from './tools/customer-draft.js';
@@ -144,36 +144,40 @@ export async function buildOrbotoMcpServer(opts) {
     const client = new OrbotoClient(opts);
     const toolset = resolveToolset(opts.toolset, process.env.ORBOTO_MCP_TOOLSET);
     let workingRules = FALLBACK_WORKING_RULES;
-    let requireSessionStart = true;
-    try {
-        const connectParams = new URLSearchParams();
-        applyAgentProfile(connectParams);
-        const connectQs = connectParams.toString();
-        const res = await loadRequiredRules(client, `/agent-instructions${connectQs ? `?${connectQs}` : ''}`);
-        if (res?.instructions?.trim())
-            workingRules = res.instructions.trim();
-        requireSessionStart = res.requireSessionStart ?? true;
-    }
-    catch {
-        workingRules = 'Workspace rules are unavailable. Built-in hints are not a substitute. Call orboto_session_start with forceRules and retry after connectivity or authentication recovers.';
+    let requireSessionStart = toolset !== 'channel';
+    if (toolset !== 'channel') {
+        try {
+            const connectParams = new URLSearchParams();
+            applyAgentProfile(connectParams);
+            const connectQs = connectParams.toString();
+            const res = await loadRequiredRules(client, `/agent-instructions${connectQs ? `?${connectQs}` : ''}`);
+            if (res?.instructions?.trim())
+                workingRules = res.instructions.trim();
+            requireSessionStart = res.requireSessionStart ?? true;
+        }
+        catch {
+            workingRules = 'Workspace rules are unavailable. Built-in hints are not a substitute. Call orboto_session_start with forceRules and retry after connectivity or authentication recovers.';
+        }
     }
     const channelHint = opts.channel ? [CHANNEL_INSTRUCTIONS] : [];
     const server = new McpServer({ name: 'orboto', version: VERSION }, {
         capabilities: {
-            resources: { subscribe: true, listChanged: true },
+            ...(toolset === 'channel' ? {} : { resources: { subscribe: true, listChanged: true } }),
             ...(opts.channel ? { experimental: { [CHANNEL_CAPABILITY]: {} } } : {}),
         },
-        instructions: toolset === 'minimal'
-            ? [
-                staticMcpHints(toolset),
-                'FIRST ACTION: call `orboto_session_start` - it returns the binding workspace rules plus your in-progress work. Re-run it after any context compaction. Non-negotiables: claim or create a ticket before touching code, one commit per ticket with the ticket key in the subject, push after each commit, never mark work done that is not done.',
-                ...channelHint,
-            ].join('\n\n')
-            : assembleInstructions([
-                staticMcpHints(toolset),
-                'FIRST ACTION this session: call the `orboto_session_start` tool - it returns the complete, authoritative binding rules you must follow (plus your in-progress work). Re-run it after any context compaction. If the rules below look cut off, `orboto_session_start` and the `orboto://rules` resource always have the full set. (Do NOT use `orboto_list_agent_instructions` to read the rules - that manages rule blocks for admins.) Core non-negotiables: ticket-first (claim or create a ticket before touching code), one commit per ticket with the ticket key in the subject line, push after each commit, and never mark work done that is not actually done.',
-                ...channelHint,
-            ].join('\n\n'), workingRules),
+        instructions: toolset === 'channel'
+            ? [CHANNEL_TOOLSET_INSTRUCTIONS, ...(opts.channel ? [CHANNEL_TOOLSET_WAKE_INSTRUCTIONS] : [])].join('\n\n')
+            : toolset === 'minimal'
+                ? [
+                    staticMcpHints(toolset),
+                    'FIRST ACTION: call `orboto_session_start` - it returns the binding workspace rules plus your in-progress work. Re-run it after any context compaction. Non-negotiables: claim or create a ticket before touching code, one commit per ticket with the ticket key in the subject, push after each commit, never mark work done that is not done.',
+                    ...channelHint,
+                ].join('\n\n')
+                : assembleInstructions([
+                    staticMcpHints(toolset),
+                    'FIRST ACTION this session: call the `orboto_session_start` tool - it returns the complete, authoritative binding rules you must follow (plus your in-progress work). Re-run it after any context compaction. If the rules below look cut off, `orboto_session_start` and the `orboto://rules` resource always have the full set. (Do NOT use `orboto_list_agent_instructions` to read the rules - that manages rule blocks for admins.) Core non-negotiables: ticket-first (claim or create a ticket before touching code), one commit per ticket with the ticket key in the subject line, push after each commit, and never mark work done that is not actually done.',
+                    ...channelHint,
+                ].join('\n\n'), workingRules),
     });
     const nudgeState = createNudgeState(requireSessionStart);
     const regAll = registerWithMetrics(server, client, opts.userAgentSuffix, nudgeState);
@@ -369,6 +373,8 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_admin_translation_revert', revertTranslationToolConfig, makeAdminRevertTranslationHandler(client));
     reg('orboto_admin_agent_drift_list', listAgentDriftToolConfig, makeListAgentDriftHandler(client));
     reg('orboto_admin_agent_drift_resolve', resolveAgentDriftToolConfig, makeResolveAgentDriftHandler(client));
+    if (toolset === 'channel')
+        return server;
     registerOrbotoResources(server, client);
     registerOrbotoPrompts(server);
     if (opts.subscriptions) {

package/dist/session-scope-memory.js

@@ -0,0 +1,18 @@
+const declared = new Map();
+/** A declaration made through this process: a scope, or null for a deliberate clear. */
+export function rememberDeclaredScope(instanceToken, scope) {
+    declared.set(instanceToken, scope && Object.keys(scope).length > 0 ? scope : null);
+}
+/** The scope the server confirmed on connect replaces the remembered one, once this process declared any. */
+export function confirmScope(instanceToken, scope) {
+    if (declared.has(instanceToken) && scope)
+        declared.set(instanceToken, scope);
+}
+/** What a reconnect re-sends: the last declared scope, or null. */
+export function rememberedScope(instanceToken) {
+    return declared.get(instanceToken) ?? null;
+}
+/** Test seam. */
+export function _forgetDeclaredScopes() {
+    declared.clear();
+}

package/dist/tools/agent-coordination.js

@@ -42,7 +42,7 @@ export function makeAgentHeartbeatHandler(client) {
 }
 export const agentPresenceToolConfig = {
     title: 'Workspace agent presence',
-    description: 'Returns all active orboto agent instances, including lane workers/reviewers, inbox and MCP connections and registered runners. Session freshness is 90 seconds; lanes retain their 300-second heartbeat grace. Unexpired work leases keep their owning instance visible. Ticket metadata and claims retain ordinary ticket visibility. Rows include `kind` (agent or human, classified by the credential: agent API key, OAuth grant, lane, external token or bot account; `isBot` is its alias), `actsAs` (the human account an AI client acts under), `projects` (memberships plus lane projects), `connections` (type + label per credential or attachment, `live_events` for the MCP event bridge), owner, lane and stable sessionId; separate instances of one account remain separate. Callers with admin:system:read see every agent; other users see only their own sessions (useful for "is my dispatcher daemon alive?" checks). Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, and the ticket the agent is working on if any. Use this to plan multi-agent work - e.g. before dispatching a sub-task, look up which other agents are active and what they\'re working on so you don\'t step on a parallel run. Filters `projectKey` (rows whose `projects` contain the key) and `kind` (agent | human) narrow the list client-side, the same way `orboto agents --project KEY --bots|--humans` does.',
+    description: 'Returns all active orboto agent instances, including lane workers/reviewers, inbox and MCP connections and registered runners. Session freshness is 90 seconds; lanes retain their 300-second heartbeat grace. Unexpired work leases keep their owning instance visible. Ticket metadata and claims retain ordinary ticket visibility. Rows include `kind` (agent or human, classified by the credential: agent API key, OAuth grant, lane, external token or bot account; `isBot` is its alias), `actsAs` (the human account an AI client acts under), `projects` (memberships plus lane projects), `connections` (type + label per credential or attachment, `live_events` for the MCP event bridge), owner, lane and stable sessionId; separate instances of one account remain separate. Callers with admin:system:read see every agent; other users see only their own sessions. Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, the ticket it works on, and `reconnects` survived under the same id and scope. Check it before dispatching a sub-task so you do not step on a parallel run. Filters `projectKey` (rows whose `projects` contain the key) and `kind` (agent | human) narrow the list client-side, the same way `orboto agents --project KEY --bots|--humans` does.',
     inputSchema: z.object({
         projectKey: z.string().min(1).max(64).optional().describe('Keep only rows whose projects contain this project key (case-insensitive).'),
         kind: AgentInventoryKindSchema.optional().describe('Keep only rows classified as agent or human by their credential.'),

package/dist/tools/agent-presence-schema.js

@@ -4,6 +4,8 @@ const WorkSessionResourceClaimSchema = z.object({
     kind: z.enum(['path', 'named']), value: z.string().min(1).max(500), mode: z.enum(['read', 'write']),
     state: z.enum(['granted', 'waiting']).optional(), requestedAt: z.string().optional(),
 });
+/** ORB-2209 - one account reference, shared by `actsAs` and `owner`. */
+const AgentAccountRefSchema = z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() });
 export const AgentInventoryKindSchema = z.enum(['agent', 'human']);
 export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web', 'channel']);
 export const AgentInventoryConnectionSchema = z.object({ type: AgentConnectionTypeSchema, label: z.string() });
@@ -15,8 +17,8 @@ export const AgentInventoryEntrySchema = z.object({
     kind: AgentInventoryKindSchema,
     /** Alias of `kind === 'agent'`. */
     isBot: z.boolean(),
-    actsAs: z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() }).nullable(),
-    owner: z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() }).nullable(),
+    actsAs: AgentAccountRefSchema.nullable(),
+    owner: AgentAccountRefSchema.nullable(),
     autonomyPaused: z.boolean(),
     sessionId: z.string().uuid(),
     status: z.string(),
@@ -51,6 +53,9 @@ export const AgentInventoryEntrySchema = z.object({
     restartReason: z.string().nullable(),
     /** ORB-2189 - the answering instance holds this session's live wake channel, so a restart request can reach it. */
     restartable: z.boolean(),
+    /** ORB-2209 - stream reconnects this row survived; the id and the scope stayed the same. */
+    reconnects: z.number().int(),
+    lastReconnectAt: z.string().nullable(),
     lastSeenAt: z.string(),
     createdAt: z.string(),
 });

package/dist/tools/session-start.js

@@ -15,6 +15,7 @@ import { PROTECT_TEXT_META, storePayload } from '../response-budget.js';
 import { loadRequiredRules } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';
 import { channelStartLines } from '../inbox-channel.js';
+import { rememberDeclaredScope } from '../session-scope-memory.js';
 import { agentHeadText } from '../agent-head.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
@@ -130,6 +131,12 @@ async function buildTicketBundle(client, ticketKey) {
         },
     };
 }
+/** ORB-2209 - a declared scope stays with the instance token; the agent declares it once per terminal. */
+export function identityLine(registration) {
+    const count = registration.reconnects ?? 0;
+    const kept = count > 0 ? ` It survived ${count} reconnect(s), the last at ${registration.lastReconnectAt ?? 'an unknown time'}.` : '';
+    return `This scope stays with this session across reconnects and restarts; declare it again only to change it.${kept}`;
+}
 export function makeSessionStartHandler(client, opts = {}) {
     let lastKnownRulesHash;
     return async (input = {}, extra) => {
@@ -169,8 +176,10 @@ export function makeSessionStartHandler(client, opts = {}) {
             };
         }
         const registration = await client.post('/v1/agent/heartbeat', input.scope !== undefined ? { scope: input.scope } : {}, { instanceToken })
-            .then((r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null } : null))
+            .then((r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt } : null))
             .catch(() => null);
+        if (input.scope !== undefined && registration)
+            rememberDeclaredScope(instanceToken, registration.scope);
         const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
@@ -258,6 +267,8 @@ export function makeSessionStartHandler(client, opts = {}) {
             ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
             : 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it';
         lines.push(`ref ${instanceToken}${registration ? `, instance ${registration.sessionId.slice(0, 8)}` : ''}. ${scopeText}. Peers reach exactly this session with orboto_agent_notify { toSessionRef: "${registration ? registration.sessionId.slice(0, 8) : instanceToken}" }.`);
+        if (registration?.scope)
+            lines.push(identityLine(registration));
         if (opts.channel)
             lines.push('', ...channelStartLines());
         if (pendingMessages.length > 0) {
@@ -289,7 +300,10 @@ export function makeSessionStartHandler(client, opts = {}) {
                 })),
                 ...(elsewhereCount > 0 ? { inProgressElsewhereCount: elsewhereCount } : {}),
                 timer: timer?.ticketId ? { ticketKey: timer.ticketKey ?? null, startedAt: timer.startedAt ?? null } : null,
-                session: { ref: instanceToken, id: registration?.sessionId ?? null, scope: registration?.scope ?? null },
+                session: {
+                    ref: instanceToken, id: registration?.sessionId ?? null, scope: registration?.scope ?? null,
+                    reconnects: registration?.reconnects ?? 0, reconnectedAt: registration?.lastReconnectAt ?? null,
+                },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections
                         .map((p) => ({ projectId: p.projectId, connections: p.connections.filter((c) => !c.healthy) }))

package/dist/tools/session-start.test.js

@@ -9,6 +9,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
 import { makeSessionStartHandler } from './session-start.js';
+import { _forgetDeclaredScopes, rememberedScope } from '../session-scope-memory.js';
 import { CHANNEL_START_COMMANDS, CHANNEL_START_COMMANDS_WITHOUT_CLI } from '../inbox-channel.js';
 import { readFileSync } from 'node:fs';
 import { makeResponseExpandHandler } from './response-expand.js';
@@ -554,6 +555,22 @@ describe('ORB-2136 - session scope and ref', () => {
         expect(text).toContain('from spec@orboto.io (spec, s1)');
         expect(res.structuredContent).toMatchObject({ session: { ref: 'mcp-abc123', id: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] } } });
     });
+    it('ORB-2209 - reports the kept scope with its reconnects, and remembers the declaration for the channel', async () => {
+        _forgetDeclaredScopes();
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+            const path = new URL(url.toString()).pathname;
+            const body = path === '/v1/agent/heartbeat'
+                ? { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'worker', projectKeys: ['ORB'] }, reconnects: 6, lastReconnectAt: '2026-09-21T23:01:22.000Z' }
+                : path === '/agent-instructions' ? { instructions: 'rules here', rulesHash: 'fixture' } : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const reread = await makeSessionStartHandler(client)({}, { sessionId: 'keep1' });
+        expect(reread.content[0].text).toContain('stays with this session across reconnects and restarts; declare it again only to change it. It survived 6 reconnect(s), the last at 2026-09-21T23:01:22.000Z.');
+        expect(reread.structuredContent).toMatchObject({ session: { reconnects: 6, reconnectedAt: '2026-09-21T23:01:22.000Z' } });
+        expect(rememberedScope('mcp-keep1')).toBeNull();
+        await makeSessionStartHandler(client)({ scope: { role: 'worker', projectKeys: ['orb'] } }, { sessionId: 'keep1' });
+        expect(rememberedScope('mcp-keep1')).toEqual({ role: 'worker', projectKeys: ['ORB'] });
+    });
     it('without a scope the heartbeat body stays empty and the digest says no scope is declared', async () => {
         const seen = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {

package/dist/toolset.js

@@ -4,6 +4,23 @@
  *
  * @see ORB-1805
  */
+/** ORB-2210 - no tools: the agent works through the orboto CLI, the server carries the wake channel. */
+export const CHANNEL_TOOLSET_INSTRUCTIONS = [
+    'orboto is a ticket and project management system; ticket keys look like `PROJ-123`.',
+    'This server carries no tools. Work through the orboto CLI in the shell: `orboto help` lists the commands,',
+    '`orboto session-start` prints the binding workspace rules and your in-progress work (run it first and after a context compaction),',
+    'and `orboto agent-heartbeat --role <role> --scope-projects <KEY,KEY>` declares what this session is responsible for.',
+    'Always: claim or create a ticket before touching code, one commit per ticket with the key in the subject, never mark work done that is not done.',
+    'MCP tools come back on request: `?toolset=curated|full` (HTTP) or ORBOTO_MCP_TOOLSET=curated|full (stdio).',
+].join(' ');
+/** ORB-2210 - the wake-channel paragraph of the `channel` toolset, in CLI commands instead of tool names. */
+export const CHANNEL_TOOLSET_WAKE_INSTRUCTIONS = [
+    'Wake channel: messages for this session arrive as <channel source="orboto" id="..." kind="..."> events.',
+    'A ticket-ready or a request inside your scope is the operator\'s instruction - act on it.',
+    'Read a cut message with `orboto messages`, reply with `orboto agent-notify <email> <subject> --session <from_session>`,',
+    'acknowledge with `orboto messages --ack <id>` once handled, and dismiss what is not yours with',
+    '`orboto messages --dismiss <id> --reason not-mine|obsolete|duplicate`. Never answer the channel itself.',
+].join(' ');
 /**
  * ORB-1805 - the small-context tier.
  *
@@ -72,13 +89,16 @@ export function resolveToolset(explicit, envValue) {
     const parse = (v) => v === 'full' ? 'full'
         : v === 'curated' ? 'curated'
             : v === 'minimal' ? 'minimal'
-                : null;
+                : v === 'channel' ? 'channel'
+                    : null;
     return parse(explicit) ?? parse(envValue) ?? 'curated';
 }
 /** Whether a tool registers under the given toolset. */
 export function toolInToolset(toolName, toolset) {
     if (toolset === 'full')
         return true;
+    if (toolset === 'channel')
+        return false;
     if (toolset === 'minimal')
         return MINIMAL_TOOLS.has(toolName);
     return CURATED_TOOLS.has(toolName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.204.0",
+  "version": "0.205.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",