@orboto/mcp 0.210.0 → 0.211.1

package/README.md

@@ -123,7 +123,7 @@ Omit `ORBOTO_API_KEY` to use OAuth login instead. `codex mcp add` writes the sam
 | `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. |
-| `ORBOTO_MCP_CHANNEL_DIGEST_MINUTES` | no | Digest window for `info` / `complete` inbox mail on the channel. Default `15`; `0` delivers every message at once. Requests, errors, questions and mail older than five minutes always go out immediately. |
+| `ORBOTO_MCP_CHANNEL_DIGEST_MINUTES` | no | Digest window for account-addressed or broadcast `info` / `complete` inbox mail on the channel. Default `15`; `0` delivers every message at once. Requests, errors, questions, mail addressed to this session, replies in a thread this session sent into within 24 hours and mail older than five minutes always go out immediately. |
 
 ## Version compatibility
 

package/dist/connect-script.js

@@ -7,10 +7,10 @@
 export const CONNECT_SCRIPT_HEADING = 'If you are an AI agent helping a person set this up';
 export const CONNECT_SCRIPT_STEPS = [
     'Work one step per message: say in one sentence what the step does and why, run it, show the result, and only then move on.',
-    'Run every step you can run yourself - `orboto connect --yes` checks Node and Claude Code, writes the `orboto` server entry for this directory and prints the exact start command with the standing arguments.',
+    'Run every step you can run yourself - `orboto connect --yes --project <KEY>` wires this directory (profile pointer, project, the `orboto` server entry, one identity, the completion hook), probes the wake channel and ends with the checklist; exit code 0 means every line passed, and a failing line names its fix.',
     'Hand the person only the steps that need a human: the browser login, the two `/plugin` commands that install the orboto plugin (a CLI cannot type into a running session), quitting and restarting the session with that command, confirming the servers from `.mcp.json` and, in the development form, the local-development prompt, and, on a Team or Enterprise plan, the one Owner switch that allows channels and lists the plugin.',
     'Give every command the person runs verbatim in its own code block, never paraphrased and never merged into prose.',
-    'Verify before you continue: `orboto whoami` for the identity, `orboto mcp status` for the entry of this directory, `orboto connect --verify` for the channel.',
+    'Verify before you continue: every line of the `orboto connect` checklist passes, `orboto doctor` prints the same checklist later, `orboto connect --verify` probes the running session; declare or change the scope with `orboto session-start` in the shell, never through the claude.ai connector.',
     'Never paste a reference page into the chat - link it and keep the message to the step you are on.',
     'Never ask for an API key, a password or a token in the chat; `orboto login` writes the credential itself.',
     'When a check fails, name the cause from the troubleshooting table, fix it, and repeat the check before the next step.',

package/dist/inbox-channel.js

@@ -2,6 +2,8 @@ import { RESTART_REQUESTED_NOTICE, writeRestartRequest } from './session-restart
 import { confirmScope, rememberedScope } from './session-scope-memory.js';
 export { RESTART_REQUESTED_NOTICE };
 export const CHANNEL_METHOD = 'notifications/claude/channel';
+/** ORB-2263 - the server notice an unscoped channel session gets; the session sees it once, with the exact CLI call. */
+export const DECLARE_SCOPE_NOTICE = 'declare_scope';
 export const CHANNEL_CAPABILITY = 'claude/channel';
 export const DEFAULT_DIGEST_MINUTES = 15;
 const IMMEDIATE_AFTER_MS = 5 * 60_000;
@@ -19,7 +21,7 @@ export const CHANNEL_INSTRUCTIONS = 'Inbox channel: messages for THIS session ar
     + 'Never answer the channel itself and never ack what you did not handle - dismiss it instead with orboto_messages { dismiss: { ids, reason } }: '
     + '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 - '
+    + 'declare the scope through the CLI in the shell, `orboto session-start --role worker --scope-projects <KEY>`, to be woken by the account\'s project mail again - never through the claude.ai connector, which is another session - '
     + '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';
@@ -65,12 +67,18 @@ function waitedMinutes(createdAt, now) {
         return 0;
     return Math.max(0, Math.floor((now - t) / 60_000));
 }
-/** A message goes out at once when it asks for something or already waited; the rest is digest material. */
+/** ORB-2265 - a message the stream flags as addressed to this session or answering a thread it sent into is never digest material. */
+export function isForThisSession(m) {
+    return m.addressed === true || m.inSentThread === true;
+}
+/** A message goes out at once when it asks for something, is addressed to this session, answers its thread or already waited; account and broadcast info is digest material. */
 export function isImmediate(m, now, digestMinutes) {
     if (digestMinutes <= 0)
         return true;
     if (m.kind === 'request' || m.kind === 'error')
         return true;
+    if (isForThisSession(m))
+        return true;
     if (waitedMinutes(m.createdAt, now) * 60_000 >= IMMEDIATE_AFTER_MS)
         return true;
     return ASK.test(`${m.subject} ${firstLine(m.payload)}`);
@@ -96,6 +104,11 @@ export function renderEvent(m, now) {
         },
     };
 }
+/** ORB-2263 - the scope hint names the project of this checkout in its CLI call when the environment carries one. */
+export function scopeHintWithKey(content, rawKey) {
+    const key = rawKey?.trim().toUpperCase();
+    return key && /^[A-Z][A-Z0-9_]{0,63}$/.test(key) ? content.replaceAll('<KEY>', key) : content;
+}
 export function renderDigest(batch, now) {
     const lines = [`Inbox digest: ${batch.length} info/complete message(s) since the last event. Ack the ones you handled with orboto_messages { ackIds }.`];
     for (const m of batch) {
@@ -119,6 +132,7 @@ export class InboxChannel {
     seen = new Set();
     seenOrder = [];
     batch = [];
+    scopeHintShown = false;
     /** 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. */
@@ -172,10 +186,18 @@ export class InboxChannel {
             this.digestTimer = setTimeout(() => { this.digestTimer = null; void this.flushDigest(); }, this.digestMinutes * 60_000);
         }
     }
-    /** ORB-2151 - a server notice (the scope hint) is emitted as-is and never becomes the replay anchor. */
+    /** ORB-2151 - a server notice is emitted and never becomes the replay anchor; the scope hint only once per process (ORB-2263). */
     async deliverNotice(notice, content) {
         if (!content)
             return;
+        if (notice === DECLARE_SCOPE_NOTICE) {
+            if (this.scopeHintShown)
+                return;
+            this.scopeHintShown = true;
+            this.stats.notices += 1;
+            await this.emit({ content: scopeHintWithKey(content, this.opts.projectKey ?? process.env.ORBOTO_PROJECT_KEY), meta: { kind: 'notice', notice } });
+            return;
+        }
         this.stats.notices += 1;
         if (notice === RESTART_REQUESTED_NOTICE) {
             await this.emit({ content: this.takeRestartRequest(content), meta: { kind: 'notice', notice } });

package/dist/inbox-channel.test.js

@@ -5,7 +5,7 @@
 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 { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, CLI_OUTDATED_NOTICE, InboxChannel, RESTART_REQUESTED_NOTICE, cliOutdatedNotice, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, CLI_OUTDATED_NOTICE, InboxChannel, RESTART_REQUESTED_NOTICE, cliOutdatedNotice, digestMinutesFromEnv, isImmediate, renderEvent, scopeHintWithKey } from './inbox-channel.js';
 import { buildOrbotoMcpServer } from './server.js';
 import { _forgetDeclaredScopes, rememberDeclaredScope, rememberedScope } from './session-scope-memory.js';
 function mockMcp() {
@@ -49,6 +49,14 @@ describe('renderEvent / isImmediate', () => {
         expect(isImmediate(msg({ kind: 'info', payload: { message: 'old' }, createdAt: '2026-09-18 09:50:00+00' }), NOW, 15)).toBe(true);
         expect(isImmediate(msg({ kind: 'info', payload: { message: 'pushed abc' } }), NOW, 0)).toBe(true);
     });
+    it('ORB-2265 - info flagged addressed or in a sent thread wakes at once; account and broadcast info stays digest material', () => {
+        const info = (over = {}) => msg({ kind: 'info', payload: { message: 'z440-2 is off' }, ...over });
+        expect(isImmediate(info({ addressed: true }), NOW, 15)).toBe(true);
+        expect(isImmediate(info({ kind: 'complete', payload: null, addressed: true }), NOW, 15)).toBe(true);
+        expect(isImmediate(info({ threadId: 't1', inSentThread: true }), NOW, 15)).toBe(true);
+        expect(isImmediate(info(), NOW, 15)).toBe(false);
+        expect(isImmediate(info({ threadId: 't1' }), NOW, 15)).toBe(false);
+    });
     it('reads the digest window from the environment with a safe default', () => {
         expect(digestMinutesFromEnv(undefined)).toBe(15);
         expect(digestMinutesFromEnv('0')).toBe(0);
@@ -58,6 +66,25 @@ describe('renderEvent / isImmediate', () => {
     });
 });
 describe('InboxChannel', () => {
+    it('ORB-2265 - a connected channel wakes at once for info addressed to its session and for a reply flagged as in its sent thread, and digests the account info', async () => {
+        const { mcp, notification } = mockMcp();
+        const mine = 'bbbbbbbb-0000-4000-8000-000000000000';
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, log: () => { }, digestMinutes: 15 });
+        channel.applySession({ id: mine, scope: null, resumed: false, scopeRestored: false, reconnects: 0, lastReconnectAt: null });
+        const noSession = { email: 'claude@orboto.io', sessionId: null, label: 'claude@orboto.io' };
+        const base = { kind: 'info', payload: { message: 'z440-2 is off' }, createdAt: '2026-09-18 09:59:50+00' };
+        await channel.deliver(msg({ ...base, id: 'addr', addressed: true }));
+        await channel.deliver(msg({ ...base, id: 'thread', threadId: 't1', inSentThread: true, to: noSession }));
+        await channel.deliver(msg({ ...base, id: 'account', to: noSession }));
+        await channel.deliver(msg({ ...base, id: 'stale-thread', threadId: 't0', to: noSession }));
+        expect(notification).toHaveBeenCalledTimes(2);
+        expect(notification.mock.calls.map((c) => c[0].params.meta.id)).toEqual(['addr', 'thread']);
+        expect(channel.stats).toMatchObject({ delivered: 2, digested: 2 });
+        await vi.advanceTimersByTimeAsync(15 * 60_000);
+        expect(notification).toHaveBeenCalledTimes(3);
+        expect(notification.mock.calls[2][0].params.meta).toMatchObject({ kind: 'digest', count: '2' });
+        channel.close();
+    });
     it('turns each streamed message into one channel notification and batches info into a digest', async () => {
         const { mcp, notification } = mockMcp();
         const fetchFn = vi.fn().mockResolvedValueOnce(sse([
@@ -162,6 +189,27 @@ describe('InboxChannel', () => {
         expect(String(fetchFn.mock.calls[1][0])).toContain('since=m1');
         channel.close();
     });
+    it('ORB-2263 - the scope hint reaches the session once per process, with the checkout project in the CLI call', async () => {
+        const { mcp, notification } = mockMcp();
+        const hint = { notice: 'declare_scope', sessionId: 'cccccccc-0000-4000-8000-000000000000', content: 'declare your scope through the CLI in the shell: orboto session-start --role worker --scope-projects <KEY> - never through the claude.ai connector' };
+        const fetchFn = vi.fn()
+            .mockResolvedValueOnce(sse([hint]))
+            .mockResolvedValueOnce(sse([hint]))
+            .mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-once', mcp, fetchFn, log: () => { }, digestMinutes: 0, projectKey: 'acme' });
+        channel.start();
+        await vi.waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(1));
+        await vi.advanceTimersByTimeAsync(5_000);
+        await vi.waitFor(() => expect(fetchFn.mock.calls.length).toBeGreaterThanOrEqual(3));
+        expect(notification).toHaveBeenCalledTimes(1);
+        const sent = notification.mock.calls[0][0];
+        expect(sent.params.content).toContain('orboto session-start --role worker --scope-projects ACME');
+        expect(sent.params.content).not.toContain('<KEY>');
+        expect(channel.stats.notices).toBe(1);
+        expect(scopeHintWithKey('x <KEY>', undefined)).toBe('x <KEY>');
+        expect(scopeHintWithKey('x <KEY>', 'bad key!')).toBe('x <KEY>');
+        channel.close();
+    });
     it('ORB-2181 - a restart_requested notice becomes the supervisor request file and says so', async () => {
         const { mcp, notification } = mockMcp();
         const writeRestart = vi.fn().mockReturnValue({ written: true, sessionId: 'sess-1', path: '/home/a/.orboto/claude/sess-1/restart.json', detail: 'ok' });

package/dist/index.js

@@ -78,7 +78,10 @@ async function main() {
             beat();
             const beats = setInterval(beat, 60_000);
             beats.unref?.();
-            stdio.onclose = () => { clearInterval(beats); inbox.close(); };
+            const cleanup = () => { clearInterval(beats); inbox.close(); };
+            stdio.onclose = cleanup;
+            const { endProbeSessionOnStdinEnd } = await import('./probe-session.js');
+            endProbeSessionOnStdinEnd({ env: process.env, stdin: process.stdin, client: preflightClient, instanceToken, cleanup, exit: (code) => process.exit(code) });
         }
         return;
     }

package/dist/probe-session.js

@@ -0,0 +1,20 @@
+/** Must stay equal to ProbeSessionEnv in cli/internal/cmd/connect_probe.go (drift test). */
+export const PROBE_SESSION_ENV = 'ORBOTO_PROBE_SESSION';
+/** Answers false outside a probe; inside one, ends the session for good and exits once stdin ends. */
+export function endProbeSessionOnStdinEnd(opts) {
+    if (opts.env[PROBE_SESSION_ENV] !== '1')
+        return false;
+    let ended = false;
+    const end = () => {
+        if (ended)
+            return;
+        ended = true;
+        opts.cleanup();
+        void opts.client.post('/v1/agent/end-session', {}, { instanceToken: opts.instanceToken })
+            .catch(() => undefined)
+            .finally(() => opts.exit(0));
+    };
+    opts.stdin.once('end', end);
+    opts.stdin.once('close', end);
+    return true;
+}

package/dist/probe-session.test.js

@@ -0,0 +1,36 @@
+/** ORB-2263 - the probe proxy ends its own session on stdin end, a real session never does. */
+import { EventEmitter } from 'node:events';
+import { readFileSync } from 'node:fs';
+import { describe, expect, it, vi } from 'vitest';
+import { endProbeSessionOnStdinEnd, PROBE_SESSION_ENV } from './probe-session.js';
+function harness(env) {
+    const stdin = new EventEmitter();
+    const calls = [];
+    const client = { post: async (path, body, opts) => { calls.push({ path, body, instanceToken: opts?.instanceToken }); return undefined; } };
+    const cleanup = vi.fn();
+    const exit = vi.fn();
+    const armed = endProbeSessionOnStdinEnd({ env, stdin, client, instanceToken: 'agent-0123456789ab', cleanup, exit });
+    return { stdin, calls, cleanup, exit, armed };
+}
+describe('ORB-2263 - probe session end', () => {
+    it('names the variable the CLI sets for the probe child', () => {
+        const go = readFileSync(new URL('../../../cli/internal/cmd/connect_probe.go', import.meta.url), 'utf8');
+        expect(go).toContain(`const ProbeSessionEnv = "${PROBE_SESSION_ENV}"`);
+    });
+    it('ends the session for good and exits when the probe stdin ends', async () => {
+        const h = harness({ [PROBE_SESSION_ENV]: '1' });
+        expect(h.armed).toBe(true);
+        h.stdin.emit('end');
+        h.stdin.emit('close');
+        await vi.waitFor(() => expect(h.exit).toHaveBeenCalledWith(0));
+        expect(h.cleanup).toHaveBeenCalledTimes(1);
+        expect(h.calls).toEqual([{ path: '/v1/agent/end-session', body: {}, instanceToken: 'agent-0123456789ab' }]);
+    });
+    it('leaves a real session alone so a resume keeps its row', () => {
+        const h = harness({});
+        expect(h.armed).toBe(false);
+        h.stdin.emit('end');
+        expect(h.calls).toEqual([]);
+        expect(h.exit).not.toHaveBeenCalled();
+    });
+});

package/dist/tools/agent-coordination.js

@@ -82,9 +82,11 @@ export function makeAgentPresenceHandler(client) {
         };
     };
 }
+/** ORB-2263 - mirror of AgentNotifyRoutedToSchema in @orboto/shared-schema (drift test in agent-coordination.test.ts). */
+export const NOTIFY_ROUTED_TO = ['session', 'scope', 'account'];
 export const agentNotifyToolConfig = {
     title: 'Notify another agent / user',
-    description: 'Message a user (bot or human) by email; lands in their inbox (orboto_messages), for humans in-app. kind: request|error = work inside the scope the recipient holds (request needs project or toSessionRef + outcome); info = information; complete = result (needs outcome). payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it (ORB-2136).',
+    description: 'Message a user (bot or human) by email; lands in their inbox (orboto_messages), for humans in-app. kind: request|error = work inside the scope the recipient holds (request needs project or toSessionRef + outcome); info = information; complete = result (needs outcome). payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it (ORB-2136). The answer names routedTo (session, scope or account); routingNote "no session declared KEY" means nothing wakes - escalate instead of assuming delivery (ORB-2263).',
     inputSchema: z.object({
         targetEmail: z.string().email(),
         kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
@@ -92,14 +94,16 @@ export const agentNotifyToolConfig = {
         outcome: z.string().min(10).max(1000).optional(),
         payload: z.record(z.string(), z.unknown()).optional(),
         threadId: z.string().uuid().optional(),
-        project: z.string().min(1).max(64).optional().describe('Project key or UUID: scope the message to the recipient session working that project.'),
-        senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref for self-echo exclusion; defaults to this MCP session.'),
+        project: z.string().min(1).max(64).optional().describe('Project key or UUID.'),
+        senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref; default: this MCP session.'),
         toSessionRef: z.string().min(1).max(200).optional(),
     }).shape,
     outputSchema: z.object({
         ok: z.literal(true),
         messageId: z.string().uuid(),
         toSessionId: z.string().uuid().nullable(),
+        routedTo: z.enum(NOTIFY_ROUTED_TO),
+        routingNote: z.string().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -146,9 +150,11 @@ export function makeAgentNotifyHandler(client) {
         const senderRef = mcpInstanceToken(args.senderRef, extra);
         const res = await client.post('/v1/agent/notify', { ...args, senderRef }, { instanceToken: mcpInstanceToken(undefined, extra) });
         const target = res.toSessionId ? `${args.targetEmail} session ${res.toSessionId.slice(0, 8)}` : args.targetEmail;
+        const routedTo = res.routedTo ?? (res.toSessionId ? 'session' : 'account');
+        const note = res.routingNote ? ` - ${res.routingNote}` : '';
         return {
-            content: [{ type: 'text', text: `notified ${target} (message ${res.messageId} - delivered live if connected, waits in their inbox otherwise)` }],
-            structuredContent: { ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null },
+            content: [{ type: 'text', text: `notified ${target} (message ${res.messageId}, routed to ${routedTo}${note})` }],
+            structuredContent: { ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null, routedTo, ...(res.routingNote ? { routingNote: res.routingNote } : {}) },
         };
     };
 }

package/dist/tools/agent-coordination.test.js

@@ -7,8 +7,9 @@
  * agent-sessions.test.ts.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
 import { OrbotoClient } from '../orboto-client.js';
-import { makeAgentHeartbeatHandler, makeAgentPresenceHandler, makeAgentNotifyHandler, } from './agent-coordination.js';
+import { NOTIFY_ROUTED_TO, agentNotifyToolConfig, makeAgentHeartbeatHandler, makeAgentPresenceHandler, makeAgentNotifyHandler, } from './agent-coordination.js';
 import { makeAgentMessagesHandler } from './agent-messages.js';
 afterEach(() => { vi.restoreAllMocks(); });
 function stub(responses) {
@@ -180,6 +181,27 @@ describe('orboto_agent_notify', () => {
         expect(capturedBody[1].senderRef).toBe('runner:custom');
     });
 });
+describe('orboto_agent_notify routing (ORB-2263)', () => {
+    it('mirrors the routedTo values of the shared schema', () => {
+        const shared = readFileSync(new URL('../../../../packages/shared-schema/src/agent-message-kinds.ts', import.meta.url), 'utf8');
+        const match = shared.match(/AgentNotifyRoutedToSchema = z\.enum\(\[([^\]]+)\]\)/);
+        expect(match).not.toBeNull();
+        const values = match[1].split(',').map((v) => v.trim().replace(/'/g, ''));
+        expect(values).toEqual([...NOTIFY_ROUTED_TO]);
+        expect(agentNotifyToolConfig.description).toContain('routedTo');
+        expect(agentNotifyToolConfig.description).toContain('no session declared KEY');
+    });
+    it('answers routedTo account with the routing note so the sender escalates', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+            ok: true, status: 200, statusText: 'OK',
+            json: async () => ({ ok: true, messageId: '00000000-0000-4000-8000-000000000000', toSessionId: null, routedTo: 'account', routingNote: 'no session declared HIVE - the message waits in the account inbox and wakes no session; escalate or address a session instead of assuming delivery' }),
+            text: async () => '',
+        }));
+        const result = await makeAgentNotifyHandler(client)({ targetEmail: 'bot@example.org', kind: 'request', subject: 'build HIVE-720', outcome: 'HIVE-720 is built and in review', project: 'HIVE' });
+        expect(result.structuredContent).toMatchObject({ routedTo: 'account', routingNote: expect.stringContaining('no session declared HIVE') });
+        expect(result.content[0].text).toContain('routed to account - no session declared HIVE');
+    });
+});
 describe('orboto_messages (ORB-1742 self-echo exclusion)', () => {
     it('fetches with excludeRef = the session ref by default; includeOwnSends drops the filter', async () => {
         const urls = [];

package/dist/tools/knowledge.js

@@ -1,6 +1,7 @@
 /** ORB-2225 - the wiki as the agents' knowledge base: ask it first, file durable facts in it. */
 import { z } from 'zod';
 import { mcpInstanceToken } from './shared.js';
+import { droppedLines } from './wiki.js';
 export const knowledgeAskToolConfig = {
     title: 'Ask the wiki',
     description: 'Ask your session\'s project wikis and the Operations wiki before asking a person; cite docs by key.',
@@ -30,6 +31,6 @@ export const knowledgeAddToolConfig = {
 export function makeKnowledgeAddHandler(client) {
     return async (input, extra) => {
         const res = await client.post('/knowledge/add', input, { instanceToken: mcpInstanceToken(undefined, extra) });
-        return { content: [{ type: 'text', text: res.text }], structuredContent: res };
+        return { content: [{ type: 'text', text: `${res.text}${droppedLines(res.droppedOps ?? [])}` }], structuredContent: res };
     };
 }

package/dist/tools/knowledge.test.js

@@ -26,6 +26,14 @@ describe('ORB-2225 orboto_knowledge_ask and orboto_knowledge_add', () => {
         expect(textOf(result)).toContain('ACME-D7');
         expect(result.structuredContent).toMatchObject({ action: 'recorded' });
     });
+    it('files a fact and lists the ops the wiki agent dropped, as wiki record does', async () => {
+        const droppedOps = [{ title: 'Runner', target: 'ACME-D99', reason: 'unknown_target' }];
+        const post = vi.fn().mockResolvedValue({ action: 'recorded', text: 'Recorded in the ACME-S1 wiki: ACME-D7 "Build host". Cite it by key.', pages: [], source: null, droppedOps });
+        const result = await makeKnowledgeAddHandler({ post })({ title: 'Build host', content: 'build.example.org', projectKey: 'ACME' });
+        expect(textOf(result)).toContain('Ops dropped: 1');
+        expect(textOf(result)).toContain('- Runner (target ACME-D99): unknown_target');
+        expect(result.structuredContent).toMatchObject({ droppedOps });
+    });
     it('both tools carry a title and annotations; ask is read-only, add is not', () => {
         expect(knowledgeAskToolConfig.title).toBeTruthy();
         expect(knowledgeAskToolConfig.annotations.readOnlyHint).toBe(true);
@@ -71,4 +79,9 @@ describe('ORB-2225 orboto_wiki_runs', () => {
         expect(textOf(await handler({ spaceId: 'ACME-S1', action: 'retry', runId: '11111111-0000-4000-8000-000000000000' }))).toContain('ran again: applied');
         expect(post).toHaveBeenCalledWith('/spaces/ACME-S1/llm-wiki/ingest-runs/11111111-0000-4000-8000-000000000000/retry', {});
     });
+    it('ORB-2226 - a run that left planner ops out says how many', async () => {
+        const get = vi.fn().mockResolvedValue({ runs: [{ id: 'r2', sourceKey: 'ACME-D10', sourceTitle: 'Deploy notes', status: 'applied', error: null, droppedOps: [{ title: 'Deploy', target: 'ACME-D99', reason: 'unknown_target' }], createdAt: '2026-09-27T09:00:00Z' }] });
+        const handler = makeWikiRunsHandler({ get, post: vi.fn() });
+        expect(textOf(await handler({ spaceId: 'ACME-S1' }))).toContain('r2 applied ACME-D10 "Deploy notes" 2026-09-27T09:00:00Z (ops dropped: 1)');
+    });
 });

package/dist/tools/secret-scan.js

@@ -4,7 +4,7 @@
 import { z } from 'zod';
 export const secretScanToolConfig = {
     title: 'Secret scan',
-    description: 'Admin sweep for stored secret-shaped values (ORB-2229); see skill reference admin.md "Secret scan".',
+    description: 'Admin sweep for stored secret-shaped values (ORB-2229); see skill reference admin.md "Secret scan". Each offer prints a findingId (the credential kind it would become); the move into the vault is not a tool: send that id to POST /admin/content/secret-scan/move through orboto_api_call, or run `orboto admin secret-scan move <findingId>` in the CLI.',
     inputSchema: z.object({
         redact: z.boolean().optional().describe('Replace found values, purge history (default false).'),
         limit: z.number().int().min(1).max(1000).optional().describe('Max hits (default 200).'),
@@ -31,6 +31,9 @@ export function makeSecretScanHandler(client) {
                 for (const f of hit.findings) {
                     lines.push(`    ${f.class} in ${hit.field} at line ${f.line}, column ${f.column} (${f.preview}, ${f.length} chars)`);
                 }
+                for (const m of hit.moves ?? []) {
+                    lines.push(`    move as ${m.kind}: findingId ${m.findingId} (post /admin/content/secret-scan/move with a key)`);
+                }
             }
             lines.push(report.redacted > 0
                 ? `Redacted ${report.redacted} rows; rotate every credential listed above.`
@@ -46,7 +49,7 @@ export function makeSecretScanHandler(client) {
                 hits: report.hits.map((h) => ({
                     entity: h.entity, id: h.id, label: h.label, field: h.field,
                     projectKey: h.projectKey, spaceVisibility: h.spaceVisibility, webUrl: h.webUrl,
-                    classes: h.findings.map((f) => f.class), redacted: h.redacted,
+                    classes: h.findings.map((f) => f.class), redacted: h.redacted, moves: h.moves ?? [],
                 })),
             },
         };

package/dist/tools/secret-scan.test.js

@@ -0,0 +1,30 @@
+/** ORB-2229, ORB-2261 - orboto_secret_scan prints each hit masked and the finding id of every move offer. */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeSecretScanHandler } from './secret-scan.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.org', apiKey: 'orb_x' });
+describe('orboto_secret_scan', () => {
+    it('lists the move offers with their finding ids and never a value', async () => {
+        const calls = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            calls.push({ url: url.toString(), body: init?.body ? JSON.parse(init.body) : undefined });
+            return {
+                ok: true, status: 200, statusText: 'OK', text: async () => '',
+                json: async () => ({
+                    scannedAt: '2026-09-29T10:00:00.000Z', scanned: { doc: 1 }, redacted: 0, nextCursor: null, truncated: false,
+                    hits: [{
+                            entity: 'doc', id: 'd1', label: 'ACME-D38', field: 'content', projectKey: 'ACME', spaceVisibility: 'workspace', webUrl: null,
+                            findings: [{ class: 'labelled_value', line: 3, column: 11, preview: 'Hk***', length: 12 }], redacted: false,
+                            moves: [{ findingId: 'WyJkb2MiXQ', kind: 'login', findingIndexes: [0] }],
+                        }],
+                }),
+            };
+        });
+        const res = await makeSecretScanHandler(client)({});
+        expect(calls[0].url).toContain('/admin/content/secret-scan');
+        const text = res.content[0].text;
+        expect(text).toContain('move as login: findingId WyJkb2MiXQ');
+        expect(res.structuredContent).toMatchObject({ hits: [{ moves: [{ findingId: 'WyJkb2MiXQ', kind: 'login' }] }] });
+    });
+});

package/dist/tools/wiki.js

@@ -69,9 +69,15 @@ export function makeWikiLintHandler(client) {
         return text(`Lint complete: ${res.issues.length} open issue(s), ${res.resolved} auto-resolved.\n${lines.join('\n')}`, { issues: res.issues, detected: res.detected, resolved: res.resolved });
     };
 }
+/** ORB-2226 - planner ops whose target page matched no docId, doc key or title. */
+export function droppedLines(dropped) {
+    if (dropped.length === 0)
+        return '';
+    return `\nOps dropped: ${dropped.length}\n${dropped.map((d) => `- ${d.title}${d.target ? ` (target ${d.target})` : ''}: ${d.reason}`).join('\n')}`;
+}
 export const wikiPlanUpdateToolConfig = {
     title: 'Plan a wiki edit (dry-run, no writes)',
-    description: 'Turn a natural-language instruction into page operations (create/patch/append) WITHOUT writing anything. Returns a planId valid for 15 minutes plus the proposed ops. Review the ops, then call orboto_wiki_apply_plan to commit. Wraps POST /spaces/:id/docs/plan-update.',
+    description: 'Turn a natural-language instruction into page operations (create/patch/append) WITHOUT writing anything. Returns a planId valid for 15 minutes plus the proposed ops, and droppedOps: ops whose target page matched no docId, doc key or title. Review the ops, then call orboto_wiki_apply_plan to commit. Wraps POST /spaces/:id/docs/plan-update.',
     inputSchema: z.object({
         spaceId: z.string().uuid().describe('The wiki space to edit.'),
         instruction: z.string().min(1).max(4000).describe('What to change, in plain language.'),
@@ -86,7 +92,8 @@ export function makeWikiPlanUpdateHandler(client) {
             body.sourceDocId = input.sourceDocId;
         const res = await client.post(`/spaces/${input.spaceId}/docs/plan-update`, body);
         const ops = res.ops.map((o, i) => `${i + 1}. ${o.op} ${o.title ?? ''} - ${o.summary}`).join('\n');
-        return text(`Plan ${res.planId} (expires ${res.expiresAt}):\n${ops}\n\nApply with orboto_wiki_apply_plan(planId).`, { planId: res.planId, ops: res.ops, expiresAt: res.expiresAt });
+        const droppedOps = res.droppedOps ?? [];
+        return text(`Plan ${res.planId} (expires ${res.expiresAt}):\n${ops}${droppedLines(droppedOps)}\n\nApply with orboto_wiki_apply_plan(planId).`, { planId: res.planId, ops: res.ops, droppedOps, expiresAt: res.expiresAt });
     };
 }
 export const wikiApplyPlanToolConfig = {
@@ -121,7 +128,8 @@ export function makeWikiRecordHandler(client) {
             planBody.sourceDocId = input.sourceDocId;
         const plan = await client.post(`/spaces/${input.spaceId}/docs/plan-update`, planBody);
         const applied = await client.post(`/spaces/${input.spaceId}/docs/apply-plan`, { planId: plan.planId });
-        return text(`Recorded: ${applied.touchedDocs.length} page(s) updated.`, { planId: plan.planId, touchedDocs: applied.touchedDocs });
+        const droppedOps = plan.droppedOps ?? [];
+        return text(`Recorded: ${applied.touchedDocs.length} page(s) updated.${droppedLines(droppedOps)}`, { planId: plan.planId, touchedDocs: applied.touchedDocs, droppedOps });
     };
 }
 export const wikiAppendSectionToolConfig = {
@@ -196,7 +204,7 @@ export function makeWikiRunsHandler(client) {
         }
         const qs = input.status ? `?status=${input.status}` : '';
         const res = await client.get(`/spaces/${encodeURIComponent(input.spaceId)}/llm-wiki/ingest-runs${qs}`);
-        const lines = res.runs.map((r) => `- ${r.id} ${r.status} ${r.sourceKey ?? ''} "${r.sourceTitle}" ${r.createdAt}${r.error ? ` - ${r.error}` : ''}`);
+        const lines = res.runs.map((r) => `- ${r.id} ${r.status} ${r.sourceKey ?? ''} "${r.sourceTitle}" ${r.createdAt}${r.droppedOps?.length ? ` (ops dropped: ${r.droppedOps.length})` : ''}${r.error ? ` - ${r.error}` : ''}`);
         return text(lines.length ? lines.join('\n') : 'No ingest runs.', res);
     };
 }

package/dist/tools/wiki.test.js

@@ -57,6 +57,13 @@ describe('orboto_wiki_plan_update + apply_plan', () => {
         expect(calls[0].url).toBe(`https://orboto.example.com/spaces/${SPACE}/docs/plan-update`);
         expect(res.content[0].text).toContain('Plan p1');
     });
+    it('ORB-2226 - plan-update names the ops the planner target could not be resolved for', async () => {
+        stubJSON([{ json: { planId: 'p1', ops: [], droppedOps: [{ title: 'Runbook', target: 'ghost page', reason: 'unknown_target' }], expiresAt: '2026-01-01T00:15:00Z' } }]);
+        const res = await makeWikiPlanUpdateHandler(client)({ spaceId: SPACE, instruction: 'update the runbook' });
+        const out = res.content[0].text;
+        expect(out).toContain('Ops dropped: 1');
+        expect(out).toContain('- Runbook (target ghost page): unknown_target');
+    });
     it('apply-plan reports touched docs', async () => {
         stubJSON([{ json: { touchedDocs: [DOC] } }]);
         const res = await makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.210.0",
+  "version": "0.211.1",
   "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",