@orboto/mcp 0.225.0 → 0.226.2

package/dist/channel-start.test.js

@@ -67,7 +67,7 @@ describe('ORB-2584 - the channel needs a channel-enabled start', () => {
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
             const path = new URL(url.toString()).pathname;
             const map = {
-                '/v1/agent/heartbeat': { sessionToken: 'mcp-x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null, wake: 'on_call', scopeExpired: { scope: { role: 'coordinator' }, pid: 4100, startedAt: null, forPid: 5200, expiredAt: 'now' }, notes },
+                '/v1/agent/heartbeat': { sessionToken: 'mcp-x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null, wake: 'on_call', scopeExpired: { scope: { role: 'coordinator' }, pid: 4100, startedAt: null, forPid: 5200, expiredAt: 'now' }, scopeContinued: { scope: { role: 'lead' }, pid: 4100, startedAt: null, forPid: 5200, conversation: 'conv-1', continuedAt: 'now' }, notes },
                 '/users/me': { email: 'dev@example.invalid', fullName: 'Dev' },
                 '/agent-instructions': { instructions: 'rules', rulesHash: 'h' },
             };
@@ -78,6 +78,6 @@ describe('ORB-2584 - the channel needs a channel-enabled start', () => {
         const text = res.content[0].text;
         for (const note of notes)
             expect(text).toContain(note);
-        expect(res.structuredContent).toMatchObject({ session: { wake: 'on_call', scopeExpired: { scope: { role: 'coordinator' } } } });
+        expect(res.structuredContent).toMatchObject({ session: { wake: 'on_call', scopeExpired: { scope: { role: 'coordinator' } }, scopeContinued: { conversation: 'conv-1' } } });
     });
 });

package/dist/project-scope.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { rememberDeclaredScope } from './session-scope-memory.js';
 /** Must stay equal to ProjectKeyEnv in cli/internal/cmd/project_scope.go (drift test). */
 export const PROJECT_KEY_ENV = 'ORBOTO_PROJECT_KEY';
@@ -19,15 +21,29 @@ export function envProjectScope(raw = process.env.ORBOTO_PROJECT_KEY, role = pro
 export function scopeDeclared(scope) {
     return !!scope && (!!scope.role || (scope.projectKeys?.length ?? 0) > 0 || (scope.ticketKeys?.length ?? 0) > 0);
 }
-/** Declares the environment's project on the session row unless the row already carries a scope; answers the row. */
-export async function declareEnvProjectScope(client, instanceToken, raw = process.env.ORBOTO_PROJECT_KEY, role = process.env.ORBOTO_SESSION_ROLE) {
+/** ORB-2593 - true while the `orboto claude` supervisor of this session waits for the conversation a bare `--resume` picks: no default scope is declared before it. */
+export function supervisorScopePending(env = process.env) {
+    const dir = (env.ORBOTO_CLAUDE_SUPERVISOR_DIR ?? '').trim();
+    const launcher = Number((env.ORBOTO_LAUNCHER_PID ?? '').trim());
+    if (!dir || !Number.isInteger(launcher) || launcher <= 1)
+        return false;
+    try {
+        const state = JSON.parse(readFileSync(join(dir, 'state.json'), 'utf8'));
+        return state.pid === launcher && state.scopePending === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Declares the environment's project on the session row unless the row already carries a scope or the supervisor waits for a picked conversation; answers the row. */
+export async function declareEnvProjectScope(client, instanceToken, raw = process.env.ORBOTO_PROJECT_KEY, role = process.env.ORBOTO_SESSION_ROLE, pending = supervisorScopePending()) {
     const scope = envProjectScope(raw, role);
-    if (!scope)
+    if (!scope || pending)
         return null;
     const current = await client.get('/v1/agent/session', { instanceToken }).catch(() => null);
     if (current && scopeDeclared(current.scope))
         return current;
-    const row = await client.post('/v1/agent/heartbeat', { scope }, { instanceToken }).catch(() => null);
+    const row = await client.post('/v1/agent/heartbeat', { scope, scopeDefault: true }, { instanceToken }).catch(() => null);
     if (row && typeof row.sessionId === 'string')
         rememberDeclaredScope(instanceToken, row.scope ?? scope);
     return row;

package/dist/project-scope.test.js

@@ -41,7 +41,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         await declareEnvProjectScope(client, 'agent-abc', 'ACME');
         expect(client.calls).toEqual([
             { method: 'GET', path: '/v1/agent/session', instanceToken: 'agent-abc' },
-            { method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] } }, instanceToken: 'agent-abc' },
+            { method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }, instanceToken: 'agent-abc' },
         ]);
         expect(rememberedScope('agent-abc')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
     });
@@ -79,7 +79,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         });
         const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'k' });
         const res = await makeSessionStartHandler(client)({}, { sessionId: 'scope1' });
-        expect(beats).toEqual([{}, { scope: { role: 'worker', projectKeys: ['ACME'] } }]);
+        expect(beats).toEqual([{}, { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }]);
         expect(res.content[0].text).toContain('projects ACME');
         expect(rememberedScope('mcp-scope1')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
     });
@@ -99,7 +99,7 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
         expect(envProjectScope(undefined, 'lead')).toBeNull();
         const client = fakeClient({ sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null });
         await declareEnvProjectScope(client, 'agent-control', undefined, 'coordinator');
-        expect(client.calls[1]).toEqual({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'coordinator' } }, instanceToken: 'agent-control' });
+        expect(client.calls[1]).toEqual({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'coordinator' }, scopeDefault: true }, instanceToken: 'agent-control' });
         expect(rememberedScope('agent-control')).toEqual({ role: 'coordinator' });
     });
     it('orboto_session_start without a scope declares the control session the environment names', async () => {
@@ -124,7 +124,27 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
         });
         const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'k' });
         await makeSessionStartHandler(client)({}, { sessionId: 'control1' });
-        expect(beats).toEqual([{}, { scope: { role: 'coordinator' } }]);
+        expect(beats).toEqual([{}, { scope: { role: 'coordinator' }, scopeDefault: true }]);
         expect(rememberedScope('mcp-control1')).toEqual({ role: 'coordinator' });
     });
 });
+describe('ORB-2593 - a picker-pending orboto claude start', () => {
+    it('declares no default scope while the supervisor waits for the picked conversation, and declares it once the pick resolved', async () => {
+        const { mkdtempSync, writeFileSync } = await import('node:fs');
+        const { tmpdir } = await import('node:os');
+        const { join } = await import('node:path');
+        const { supervisorScopePending } = await import('./project-scope.js');
+        const dir = mkdtempSync(join(tmpdir(), 'orboto-supervisor-'));
+        const env = { ORBOTO_CLAUDE_SUPERVISOR_DIR: dir, ORBOTO_LAUNCHER_PID: '4000' };
+        writeFileSync(join(dir, 'state.json'), JSON.stringify({ pid: 4000, scopePending: true }));
+        expect(supervisorScopePending(env)).toBe(true);
+        expect(supervisorScopePending({ ...env, ORBOTO_LAUNCHER_PID: '4001' })).toBe(false);
+        const pending = fakeClient({ sessionId: 'x', scope: null });
+        expect(await declareEnvProjectScope(pending, 'agent-abc', 'ACME', undefined, supervisorScopePending(env))).toBeNull();
+        expect(pending.calls).toEqual([]);
+        writeFileSync(join(dir, 'state.json'), JSON.stringify({ pid: 4000 }));
+        const resolved = fakeClient({ sessionId: 'x', scope: null });
+        await declareEnvProjectScope(resolved, 'agent-abc', 'ACME', undefined, supervisorScopePending(env));
+        expect(resolved.calls.filter((c) => c.method === 'POST')).toEqual([{ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }, instanceToken: 'agent-abc' }]);
+    });
+});

package/dist/session-origin.test.js

@@ -20,6 +20,10 @@ describe('ORB-2544 - the origin header', () => {
         expect(params.get('harness')).toBe('claude-code');
         expect(params.get('client')).toBe('orboto-mcp');
     });
+    it('ORB-2593 - the handed origin keeps the launch, the channel server verdict, the conversation and the checkout', () => {
+        const params = new URLSearchParams(stdioOrigin({ ORBOTO_ORIGIN: 'pid=99&harness=claude-code&launch=orboto-claude&server=running&conv=conv-1111&checkout=0123456789abcdef' }));
+        expect([params.get('launch'), params.get('server'), params.get('conv'), params.get('checkout')]).toEqual(['orboto-claude', 'running', 'conv-1111', '0123456789abcdef']);
+    });
     it('ORB-2571 - a stdio proxy names the harness orboto <harness> started and its model, else the harness markers', () => {
         expect(stdioHarness({ ORBOTO_HARNESS: 'kimi', CLAUDECODE: '1' })).toBe('kimi');
         expect(stdioHarness({ ORBOTO_HARNESS: 'antigravity' })).toBe('agy');

package/dist/tools/agent-coordination.js

@@ -121,9 +121,13 @@ export function noRecipientText(err) {
         return null;
     const p = body.errorParams ?? {};
     const live = (p.liveSessions ?? []).map((s) => `${s.addresses[0] ?? s.email} (${s.email}, ${s.shortId})`);
+    const ways = 'a role address in `to` (integrator@KEY), `toSessionRef` with an instance short id, or `queue: true` with `project` to keep it until a session declares the project';
+    if (p.reason === 'ambiguous_account') {
+        return `not sent: ${p.address ?? 'that account'} has ${live.length} live sessions you may address and a request needs one of them. Sessions: ${live.join('; ')}. Send again with \`toSessionRef\` set to the instance short id of one, or address a role (${ways}).`;
+    }
     return `not sent: no live session can receive a request to ${p.address ?? '?'} (${p.reason ?? 'no_recipient'}). `
-        + (live.length ? `Live sessions: ${live.join('; ')}. ` : 'No live session declared the project. ')
-        + 'Address one of them, or send again with queue: true and project to keep it until a session declares the project.';
+        + (live.length ? `Live sessions: ${live.join('; ')}. ` : 'No live session answers there. ')
+        + `Ways on: ${ways}.`;
 }
 /** ORB-2542 - the 409 `owner_mismatch` as a tool error naming the owner and both ways on. */
 export function ownerMismatchText(err) {
@@ -159,14 +163,15 @@ export function reminderTooSoonText(err) {
 }
 export const agentNotifyToolConfig = {
     title: 'Notify an agent or user',
-    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + 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. A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session. An identical send (same recipient, project, kind, subject, payload; no threadId, no attachments) within the dedupe window (default 24 h) is not delivered again: the text says so and names the existing message. remind: true is a deliberate reminder of it (notifies again, at most one per 15 min, faster is refused with retryAfter); urgent: true is never suppressed and counts as a reminder. Loops and retries never set remind or urgent.',
+    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). outcome: one sentence, 10 to 1000 characters; body: the plain text of the message (any length, lands in payload.body; payload may carry other 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. A request to an account email without project or toSessionRef goes to its one live session, with several it is refused listing them (pick one with toSessionRef). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session. An identical send (same recipient, project, kind, subject, payload; no threadId, no attachments) within the dedupe window (default 24 h) is not delivered again: the text says so and names the existing message. remind: true is a deliberate reminder of it (notifies again, at most one per 15 min, faster is refused with retryAfter); urgent: true is never suppressed and counts as a reminder. Loops and retries never set remind or urgent.',
     inputSchema: z.object({
         targetEmail: z.string().email().optional(),
         to: z.string().min(3).max(200).optional(),
         queue: z.boolean().optional(),
         kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
         subject: z.string().min(1).max(200),
-        outcome: z.string().min(10).max(1000).optional(),
+        outcome: z.string().optional(),
+        body: z.string().optional(),
         payload: z.record(z.string(), z.unknown()).optional(),
         threadId: z.string().uuid().optional(),
         project: z.string().min(1).max(64).optional(),
@@ -213,17 +218,41 @@ export function makeAgentBroadcastHandler(client) {
         };
     };
 }
-/** ORB-2223 - the message-kind definition this versioned sender enforces; the API only warns. */
+export const NOTIFY_OUTCOME_MIN = 10;
+export const NOTIFY_OUTCOME_MAX = 1000;
+export const NOTIFY_BODY_MAX_BYTES = 900 * 1024;
+/** ORB-2555 - a complete example call for a kind, the answer to every refusal. */
+export function notifyExample(kind, to) {
+    const target = to ?? 'integrator@KEY';
+    switch (kind) {
+        case 'request': return `orboto_agent_notify { to: "${target}", kind: "request", subject: "<one line>", outcome: "<what must be true when it is done>", body: "<details, any length>" }`;
+        case 'complete': return `orboto_agent_notify { to: "${target}", kind: "complete", subject: "<one line>", outcome: "<what is now true>", threadId: "<message id answered>" }`;
+        case 'error': return `orboto_agent_notify { to: "${target}", kind: "error", subject: "<one line>", body: "<what failed and what you tried>" }`;
+        default: return `orboto_agent_notify { to: "${target}", kind: "info", subject: "<one line>", body: "<text>" }`;
+    }
+}
+/** ORB-2223 - the message-kind definition this versioned sender enforces; the API only warns. ORB-2555 - every refusal names the flag and carries a complete example. */
 export function notifyDefinitionError(args) {
     const kind = args.kind ?? 'info';
+    const example = (text) => `Invalid arguments: ${text} Example: ${notifyExample(kind, args.to)}`;
     if (!args.to && !args.targetEmail)
-        return 'Invalid arguments: name a recipient - `to` (integrator@KEY, an email or a session id) or `targetEmail`.';
-    if ((kind === 'request' || kind === 'complete') && !args.outcome?.trim()) {
-        return `Invalid arguments: \`outcome\` is required for a ${kind} - the outcome sentence (what must be true when it is done, or what was delivered).`;
+        return example('name a recipient - `to` (integrator@KEY, an email or a session id) or `targetEmail`.');
+    const outcome = args.outcome?.trim() ?? '';
+    if ((kind === 'request' || kind === 'complete') && !outcome) {
+        return example(`\`outcome\` is required for a ${kind} - the outcome sentence (what must be true when it is done, or what was delivered), ${NOTIFY_OUTCOME_MIN} to ${NOTIFY_OUTCOME_MAX} characters.`);
     }
-    if (kind === 'request' && !args.project && !args.toSessionRef && !(args.to && !args.to.includes('.'))) {
-        return 'Invalid arguments: a request needs a target - a role address in `to` (integrator@KEY), `project` (key or UUID) or `toSessionRef`.';
+    if (outcome && outcome.length < NOTIFY_OUTCOME_MIN)
+        return example(`\`outcome\` has ${outcome.length} characters, at least ${NOTIFY_OUTCOME_MIN} are needed.`);
+    if (outcome.length > NOTIFY_OUTCOME_MAX) {
+        return example(`\`outcome\` has ${outcome.length} characters, at most ${NOTIFY_OUTCOME_MAX} are allowed: keep the outcome to one sentence and put the long text into \`body\` (any length, it lands in payload.body).`);
     }
+    if (args.body !== undefined && !args.body.trim())
+        return example('`body` is empty - give the text or leave it out.');
+    if (args.body !== undefined && args.payload && 'body' in args.payload)
+        return example('`body` and `payload.body` are both set - use one of them.');
+    const bodyBytes = args.body === undefined ? 0 : Buffer.byteLength(args.body.replace(/[\r\n]+$/, ''));
+    if (bodyBytes > NOTIFY_BODY_MAX_BYTES)
+        return example(`\`body\` has ${bodyBytes} bytes, at most ${NOTIFY_BODY_MAX_BYTES} (900 KiB) are allowed: split it into several messages or attach a file with the CLI.`);
     return null;
 }
 export function makeAgentNotifyHandler(client) {
@@ -234,8 +263,9 @@ export function makeAgentNotifyHandler(client) {
         const senderRef = mcpInstanceToken(args.senderRef, extra);
         let res;
         try {
-            const { urgent, ...rest } = args;
-            res = await client.post('/v1/agent/notify', { ...rest, ...(urgent ? { priority: NOTIFY_PRIORITIES[1] } : {}), senderRef, ownerCheck: 'refuse' }, { instanceToken: mcpInstanceToken(undefined, extra) });
+            const { urgent, body, ...rest } = args;
+            const payload = body !== undefined ? { ...(rest.payload ?? {}), body: body.replace(/[\r\n]+$/, '') } : rest.payload;
+            res = await client.post('/v1/agent/notify', { ...rest, ...(payload ? { payload } : {}), ...(urgent ? { priority: NOTIFY_PRIORITIES[1] } : {}), senderRef, ownerCheck: 'refuse' }, { instanceToken: mcpInstanceToken(undefined, extra) });
         }
         catch (err) {
             const refused = err instanceof OrbotoApiError ? noRecipientText(err) ?? ownerMismatchText(err) ?? reminderTooSoonText(err) : null;

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

@@ -141,11 +141,13 @@ describe('orboto_agent_notify', () => {
         const refused = await handler({ targetEmail: 'bob@example.com', kind: 'request', subject: 'Please review ORB-42' });
         expect(refused.isError).toBe(true);
         expect(refused.content[0].text).toContain('`outcome` is required for a request');
-        const noTarget = await handler({ targetEmail: 'bob@example.com', kind: 'request', subject: 'Please review ORB-42', outcome: 'ORB-42 has a review verdict' });
-        expect(noTarget.content[0].text).toContain('`project` (key or UUID) or `toSessionRef`');
         const noOutcome = await handler({ targetEmail: 'bob@example.com', kind: 'complete', subject: 'Done' });
         expect(noOutcome.content[0].text).toContain('`outcome` is required for a complete');
         expect(capturedBody).toHaveLength(0);
+        const bareEmail = await handler({ targetEmail: 'bob@example.com', kind: 'request', subject: 'Please review ORB-42', outcome: 'ORB-42 has a review verdict' });
+        expect(bareEmail.isError).toBeUndefined();
+        expect(capturedBody).toHaveLength(1);
+        capturedBody.length = 0;
         const result = await handler({
             targetEmail: 'bob@example.com',
             kind: 'request',
@@ -348,6 +350,84 @@ describe('orboto_agent_notify role addresses (ORB-2264)', () => {
         expect(agentNotifyToolConfig.description).toContain('integrator@KEY');
     });
 });
+describe('orboto_agent_notify body and refusals (ORB-2555)', () => {
+    const sentBodies = () => {
+        const bodies = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            bodies.push(JSON.parse(String(init.body)));
+            return { ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ ok: true, messageId: '00000000-0000-4000-8000-000000000001', toSessionId: null, routedTo: 'account' }) };
+        });
+        return bodies;
+    };
+    it('maps body into payload.body next to other payload keys and carries text beyond the outcome cap', async () => {
+        const bodies = sentBodies();
+        const long = 'detail line\n'.repeat(400);
+        await makeAgentNotifyHandler(client)({ to: 'worker@ORB', kind: 'complete', subject: 'report', outcome: 'the report is delivered in full', body: long, payload: { ticketKey: 'ORB-1' } });
+        expect(bodies[0].payload).toEqual({ ticketKey: 'ORB-1', body: long.trimEnd() });
+        expect(bodies[0].body).toBeUndefined();
+        await makeAgentNotifyHandler(client)({ to: 'worker@ORB', subject: 'plain', body: 'text' });
+        expect(bodies[1].payload).toEqual({ body: 'text' });
+    });
+    it('trims trailing newlines of the body and counts its limit in bytes like the CLI', async () => {
+        const bodies = sentBodies();
+        const handler = makeAgentNotifyHandler(client);
+        await handler({ to: 'worker@ORB', subject: 's', body: 'text\r\n\n' });
+        expect(bodies[0].payload).toEqual({ body: 'text' });
+        const tooBig = await handler({ to: 'worker@ORB', subject: 's', body: 'ä'.repeat(500 * 1024) });
+        expect(tooBig.content[0].text).toContain('bytes, at most 921600 (900 KiB)');
+        expect(bodies).toHaveLength(1);
+    });
+    it('refuses an outcome over 1000 characters with the remedy and a complete example, sending nothing', async () => {
+        const bodies = sentBodies();
+        const result = await makeAgentNotifyHandler(client)({ to: 'integrator@ORB', kind: 'complete', subject: 'report', outcome: 'x'.repeat(1001) });
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        expect(text).toContain('`outcome` has 1001 characters, at most 1000');
+        expect(text).toContain('put the long text into `body`');
+        expect(text).toContain('Example: orboto_agent_notify { to: "integrator@ORB", kind: "complete"');
+        expect(bodies).toHaveLength(0);
+    });
+    it('names the missing field with an example per kind', async () => {
+        const bodies = sentBodies();
+        const handler = makeAgentNotifyHandler(client);
+        const text = async (args) => (await handler(args)).content[0].text;
+        expect(await text({ to: 'integrator@ORB', kind: 'request', subject: 's' })).toContain('outcome: "<what must be true when it is done>", body: "<details, any length>"');
+        expect(await text({ to: 'integrator@ORB', kind: 'error', subject: 's', outcome: 'short' })).toContain('`outcome` has 5 characters, at least 10');
+        expect(await text({ to: 'integrator@ORB', subject: 's', body: '  ' })).toContain('`body` is empty');
+        expect(await text({ to: 'integrator@ORB', subject: 's', body: 'x', payload: { body: 'y' } })).toContain('`body` and `payload.body` are both set');
+        expect(await text({ subject: 's' })).toContain('Example: orboto_agent_notify { to: "integrator@KEY", kind: "info"');
+        expect(bodies).toHaveLength(0);
+    });
+    it('turns the ambiguous account 409 into a tool error listing the sessions and asking for toSessionRef', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+            ok: false, status: 409, statusText: 'Conflict', json: async () => ({}),
+            text: async () => JSON.stringify({
+                errorKey: 'errors.agents.no_recipient',
+                errorParams: { address: 'claude@orboto.io', reason: 'ambiguous_account', liveSessions: [
+                        { shortId: 'f072e1c5', email: 'claude@orboto.io', addresses: ['worker@ORB'] }, { shortId: 'a072e1c5', email: 'claude@orboto.io', addresses: ['review@ORB'] },
+                    ] },
+            }),
+        }));
+        const result = await makeAgentNotifyHandler(client)({ targetEmail: 'claude@orboto.io', kind: 'request', subject: 's', outcome: 'ORB-1 is reviewed with findings' });
+        const text = result.content[0].text;
+        expect(result.isError).toBe(true);
+        expect(text).toContain('has 2 live sessions');
+        expect(text).toContain('worker@ORB (claude@orboto.io, f072e1c5)');
+        expect(text).toContain('`toSessionRef`');
+        expect(text).toContain('integrator@KEY');
+    });
+    it('names every way on when the account has no live session', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+            ok: false, status: 409, statusText: 'Conflict', json: async () => ({}),
+            text: async () => JSON.stringify({ errorKey: 'errors.agents.no_recipient', errorParams: { address: 'claude@orboto.io', reason: 'no_recipient', project: null, liveSessions: [] } }),
+        }));
+        const result = await makeAgentNotifyHandler(client)({ targetEmail: 'claude@orboto.io', kind: 'request', subject: 's', outcome: 'ORB-1 is reviewed with findings' });
+        const text = result.content[0].text;
+        expect(text).toContain('a role address in `to` (integrator@KEY)');
+        expect(text).toContain('`toSessionRef`');
+        expect(text).toContain('`queue: true` with `project`');
+    });
+});
 describe('orboto_agent_notify dedupe and reminders (ORB-2563)', () => {
     afterEach(() => { vi.restoreAllMocks(); });
     it('mirrors the priorities and sender lines of the shared schema', () => {

package/dist/tools/session-start.js

@@ -222,7 +222,7 @@ export function makeSessionStartHandler(client, opts = {}) {
         }
         const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? {
             sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt,
-            wake: r.wake, scopeExpired: r.scopeExpired ?? null, notes: Array.isArray(r.notes) ? r.notes.filter((n) => typeof n === 'string') : [],
+            wake: r.wake, scopeExpired: r.scopeExpired ?? null, scopeContinued: r.scopeContinued ?? null, notes: Array.isArray(r.notes) ? r.notes.filter((n) => typeof n === 'string') : [],
         } : null);
         const host = localSessionHost(extra);
         let registration = await client.post('/v1/agent/heartbeat', { ...(input.scope !== undefined ? { scope: input.scope } : {}), ...(host ? { clientInfo: { host } } : {}) }, { instanceToken })
@@ -383,6 +383,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                     ref: instanceToken, id: registration?.sessionId ?? null, scope: registration?.scope ?? null,
                     reconnects: registration?.reconnects ?? 0, reconnectedAt: registration?.lastReconnectAt ?? null,
                     ...(registration?.wake ? { wake: registration.wake } : {}), scopeExpired: registration?.scopeExpired ?? null,
+                    scopeContinued: registration?.scopeContinued ?? null,
                 },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections

package/package.json

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