@orboto/mcp 0.224.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/required-rules-wrapper.test.js

@@ -5,6 +5,7 @@ import { spawn } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { hermeticHome, hermeticSpawnEnv } from './test/hermetic-cli-env.js';
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 const cleanup = [];
 afterEach(async () => { for (const fn of cleanup.splice(0).reverse())
@@ -43,7 +44,7 @@ async function fixture() {
     await writeFile(guard, `const original = globalThis.fetch; globalThis.fetch = (input, init) => { if (new URL(input).origin !== ${JSON.stringify(origin)}) throw new Error('Fixture refused a nonlocal request'); return original(input, init); };`);
     const run = (args = ['session-start', '--force-rules']) => new Promise((ok, no) => {
         const child = spawn(process.execPath, ['--import', guard, join(dir, 'skills/orboto/scripts/orboto.mjs'), ...args], {
-            cwd: dir, env: { ...process.env, ORBOTO_PROFILE: '', ORBOTO_BASE_URL: `http://127.0.0.1:${address.port}`, ORBOTO_TOKEN: 'orb_fixture', ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' },
+            cwd: dir, env: hermeticSpawnEnv({ home: hermeticHome('mcp-wrapper'), baseUrl: `http://127.0.0.1:${address.port}`, token: 'orb_fixture', env: { ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' } }),
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         let out = '', err = '';

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/test/child-window-test-timeout.test.js

@@ -0,0 +1,20 @@
+import { expect, it } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const src = join(process.cwd(), 'src');
+function* testFiles(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* testFiles(full);
+        else if (entry.name.endsWith('.test.ts') && entry.name !== 'child-window-test-timeout.test.ts')
+            yield full;
+    }
+}
+it('every mcp test using childWindow() sets its own ciWindow test timeout above it', () => {
+    const offenders = [...testFiles(src)].filter((file) => {
+        const text = readFileSync(file, 'utf8');
+        return text.includes('childWindow()') && !/\}, ciWindow\(\d[\d_]*\)\);/.test(text);
+    });
+    expect(offenders).toEqual([]);
+});

package/dist/test/ci-window.js

@@ -0,0 +1,8 @@
+/** ORB-2231 - a wait window that grows fivefold on the loaded shared CI runner; mirrors apps/api/src/test/ci-window.ts and imports no vitest on purpose. */
+export function ciWindow(ms) {
+    return process.env.CI ? ms * 5 : ms;
+}
+/** ORB-2587 - the hang guard of one child process: 30 s, 5x on CI; the mcp runner timeout is 30 s unscaled, so a test using it sets its own ciWindow(...) test timeout. */
+export function childWindow() {
+    return ciWindow(30_000);
+}

package/dist/test/hermetic-cli-env.js

@@ -0,0 +1,42 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** ORB-2590 - the environment of every test that spawns the Go CLI or the skill wrapper: an allowlist, never process.env, so a developer's ~/.orboto bindings, ORBOTO_* and the parent harness's CLAUDE* markers cannot reach the child. */
+/** Runtime essentials and settings that do not identify the developer: the CLI reads CI (browser timeouts), a child may need the proxy, certificate and locale variables to reach the network. */
+export const INHERITED_NAMES = [
+    'PATH', 'SystemRoot', 'SYSTEMROOT', 'WINDIR', 'ComSpec', 'PATHEXT', 'CI',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
+    'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'LANG', 'LC_ALL', 'TZ',
+];
+const homes = new Set();
+/** A fresh empty HOME for one test; removed when the test process exits. */
+export function hermeticHome(label = 'spawn') {
+    const dir = mkdtempSync(join(tmpdir(), `orboto-hermetic-${label}-`));
+    homes.add(dir);
+    return dir;
+}
+process.once('exit', () => { for (const dir of homes) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch { /* best effort */ }
+} });
+/** HOME, USERPROFILE, XDG and temp dirs all inside `home`, the runtime essentials, an explicit instance, and only the `env` entries the test names. */
+export function hermeticSpawnEnv({ home, baseUrl, token, profile, env = {} }, inherited = process.env) {
+    const out = {
+        HOME: home, USERPROFILE: home, TMPDIR: home, TMP: home, TEMP: home,
+        XDG_CONFIG_HOME: join(home, '.config'), XDG_STATE_HOME: join(home, '.local', 'state'), XDG_CACHE_HOME: join(home, '.cache'),
+    };
+    for (const name of INHERITED_NAMES) {
+        const value = inherited[name];
+        if (value)
+            out[name] = value;
+    }
+    if (baseUrl !== undefined)
+        out.ORBOTO_BASE_URL = baseUrl;
+    if (token !== undefined)
+        out.ORBOTO_TOKEN = token;
+    if (profile !== undefined)
+        out.ORBOTO_PROFILE = profile;
+    return { ...out, ...env };
+}

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/doc-replace-wrapper.test.js

@@ -9,6 +9,8 @@ import { createServer } from 'node:http';
 import { spawn } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { childWindow, ciWindow } from '../test/ci-window.js';
+import { hermeticHome, hermeticSpawnEnv } from '../test/hermetic-cli-env.js';
 const DOC = 'd0c00000-2222-4222-8222-222222222222';
 const REV = 'bbbbbbbb-0000-4000-8000-000000000000';
 it('doc edit appends by default, --replace names the replaced revision, doc restore posts the restore', async () => {
@@ -45,8 +47,8 @@ it('doc edit appends by default, --replace names the replaced revision, doc rest
         await writeFile(guard, `const original = globalThis.fetch; globalThis.fetch = (input, init) => { if (new URL(input).origin !== ${JSON.stringify(origin)}) throw new Error('Fixture refused nonlocal request'); return original(input, init); };`);
         const run = (args) => new Promise((ok, no) => {
             const child = spawn(process.execPath, ['--import', guard, join(dir, 'skills/orboto/scripts/orboto.mjs'), ...args], {
-                cwd: dir, env: { ...process.env, ORBOTO_PROFILE: '', ORBOTO_BASE_URL: origin, ORBOTO_TOKEN: 'orb_fixture', ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' },
-                timeout: 20_000,
+                cwd: dir, env: hermeticSpawnEnv({ home: hermeticHome('mcp-wrapper'), baseUrl: origin, token: 'orb_fixture', env: { ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' } }),
+                timeout: childWindow(),
             });
             let out = '', err = '';
             child.stdout.on('data', (chunk) => { out += chunk.toString(); });
@@ -78,4 +80,4 @@ it('doc edit appends by default, --replace names the replaced revision, doc rest
             await new Promise((ok, no) => server.close((err) => err ? no(err) : ok()));
         await rm(dir, { recursive: true, force: true });
     }
-}, 60_000);
+}, ciWindow(60_000));

package/dist/tools/review-policy-wrapper.test.js

@@ -4,6 +4,8 @@ import { createServer } from 'node:http';
 import { spawn } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { childWindow, ciWindow } from '../test/ci-window.js';
+import { hermeticHome, hermeticSpawnEnv } from '../test/hermetic-cli-env.js';
 it('real wrapper preserves piped diff text and version-prefixed check/record values', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'orboto-1964-verify-temp-'));
     const fingerprint = 'sha256-diff-v2:' + 'a'.repeat(64);
@@ -35,8 +37,8 @@ it('real wrapper preserves piped diff text and version-prefixed check/record val
         await writeFile(guard, `const original = globalThis.fetch; globalThis.fetch = (input, init) => { if (new URL(input).origin !== ${JSON.stringify(origin)}) throw new Error('Fixture refused nonlocal request'); return original(input, init); };`);
         const run = (args, stdin = '') => new Promise((ok, no) => {
             const child = spawn(process.execPath, ['--import', guard, join(dir, 'skills/orboto/scripts/orboto.mjs'), ...args], {
-                cwd: dir, env: { ...process.env, ORBOTO_PROFILE: '', ORBOTO_BASE_URL: origin, ORBOTO_TOKEN: 'orb_fixture', ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' },
-                timeout: 20_000,
+                cwd: dir, env: hermeticSpawnEnv({ home: hermeticHome('mcp-wrapper'), baseUrl: origin, token: 'orb_fixture', env: { ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' } }),
+                timeout: childWindow(),
             });
             let out = '', err = '';
             child.stdout.on('data', (chunk) => { out += chunk.toString(); });
@@ -59,4 +61,4 @@ it('real wrapper preserves piped diff text and version-prefixed check/record val
             await new Promise((ok, no) => server.close((err) => err ? no(err) : ok()));
         await rm(dir, { recursive: true, force: true });
     }
-}, 60_000);
+}, ciWindow(60_000));

package/dist/tools/semantic-degraded-wrapper.test.js

@@ -8,6 +8,8 @@ import { createServer } from 'node:http';
 import { spawn } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { childWindow, ciWindow } from '../test/ci-window.js';
+import { hermeticHome, hermeticSpawnEnv } from '../test/hermetic-cli-env.js';
 const LINE = 'semantic search unavailable, showing full-text results';
 it('search, search-docs, ask-docs and check-similar print the degraded line on stderr', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'orboto-2543-wrapper-'));
@@ -45,8 +47,8 @@ it('search, search-docs, ask-docs and check-similar print the degraded line on s
         await writeFile(guard, `const original = globalThis.fetch; globalThis.fetch = (input, init) => { if (new URL(input).origin !== ${JSON.stringify(origin)}) throw new Error('Fixture refused nonlocal request'); return original(input, init); };`);
         const run = (args) => new Promise((ok, no) => {
             const child = spawn(process.execPath, ['--import', guard, join(dir, 'skills/orboto/scripts/orboto.mjs'), ...args], {
-                cwd: dir, env: { ...process.env, ORBOTO_PROFILE: '', ORBOTO_BASE_URL: origin, ORBOTO_TOKEN: 'orb_fixture', ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' },
-                timeout: 20_000,
+                cwd: dir, env: hermeticSpawnEnv({ home: hermeticHome('mcp-wrapper'), baseUrl: origin, token: 'orb_fixture', env: { ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' } }),
+                timeout: childWindow(),
             });
             let out = '', err = '';
             child.stdout.on('data', (chunk) => { out += chunk.toString(); });
@@ -67,4 +69,4 @@ it('search, search-docs, ask-docs and check-similar print the degraded line on s
             await new Promise((ok, no) => server.close((err) => err ? no(err) : ok()));
         await rm(dir, { recursive: true, force: true });
     }
-}, 60_000);
+}, ciWindow(60_000));

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.224.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",