@orboto/mcp 0.222.0 → 0.222.2

package/dist/inbox-channel.js

@@ -16,6 +16,10 @@ const MIN_BACKOFF_MS = 2_000;
 const MAX_BACKOFF_MS = 60_000;
 const HEARTBEAT_GRACE_MS = 90_000;
 const ASK = /\?|\bplease\b|\bbitte\b|\bneed\b|\bshare\b/i;
+/** ORB-2563 - what the channel dedupes on: the message and its reminder count. */
+export function wakeKey(m) {
+    return m.reminderCount ? `${m.id}#${m.reminderCount}` : m.id;
+}
 /** ORB-2467 - `attachments: 1 archive, 12.4 MB (orboto messages --download <id>)`, or nothing. */
 export function attachmentLine(m) {
     return m.attachments?.count ? `attachments: ${m.attachments.label} (orboto messages --download ${m.id})` : '';
@@ -79,6 +83,8 @@ export function isImmediate(m, now, digestMinutes) {
         return true;
     if (m.kind === 'request' || m.kind === 'error')
         return true;
+    if (m.priority === 'urgent' || (m.reminderCount ?? 0) > 0)
+        return true;
     if (isForThisSession(m))
         return true;
     if (waitedMinutes(m.createdAt, now) * 60_000 >= IMMEDIATE_AFTER_MS)
@@ -90,8 +96,9 @@ export function renderEvent(m, now) {
     const to = m.to?.label ?? 'you';
     const text = firstLine(m.payload);
     const body = text.length > CONTENT_CAP ? `${text.slice(0, CONTENT_CAP)} [... cut, read the rest with orboto_messages]` : text;
+    const marks = [m.priority === 'urgent' ? '[urgent]' : '', m.reminderCount ? `[reminder ${m.reminderCount}]` : ''].filter(Boolean).join(' ');
     const lines = [
-        `[${m.kind}] ${m.subject}`,
+        `${marks ? `${marks} ` : ''}[${m.kind}] ${m.subject}`,
         `from ${from} to ${to}${m.projectKey ? ` | project ${m.projectKey}` : ''} | id ${m.id}${m.threadId ? ` | thread ${m.threadId}` : ''}`,
     ];
     if (body)
@@ -106,6 +113,8 @@ export function renderEvent(m, now) {
             id: m.id, kind: m.kind, project: m.projectKey ?? '',
             from: from, from_session: (m.from?.sessionId ?? '').slice(0, 8), to_session: (m.to?.sessionId ?? '').slice(0, 8),
             waited_min: String(waited),
+            ...(m.priority === 'urgent' ? { priority: 'urgent' } : {}),
+            ...(m.reminderCount ? { reminder: String(m.reminderCount) } : {}),
         },
     };
 }
@@ -175,11 +184,11 @@ export class InboxChannel {
     async deliver(m) {
         if (!m?.id)
             return;
-        if (this.seen.has(m.id)) {
+        if (this.seen.has(wakeKey(m))) {
             this.stats.duplicates += 1;
             return;
         }
-        this.remember(m.id);
+        this.remember(wakeKey(m));
         this.lastId = m.id;
         if (isImmediate(m, this.now(), this.digestMinutes)) {
             await this.emit(renderEvent(m, this.now()));

package/dist/inbox-channel.test.js

@@ -66,6 +66,24 @@ describe('renderEvent / isImmediate', () => {
     });
 });
 describe('InboxChannel', () => {
+    it('ORB-2563 - a reminder of a seen message wakes again with its mark, a replay of the same reminder does not, urgent info skips the digest', async () => {
+        const { mcp, notification } = mockMcp();
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, log: () => { }, digestMinutes: 15 });
+        const noSession = { email: 'claude@orboto.io', sessionId: null, label: 'claude@orboto.io' };
+        const base = { kind: 'info', payload: { message: 'run done' }, createdAt: '2026-09-18 09:59:50+00', to: noSession };
+        await channel.deliver(msg({ ...base, id: 'urgent', priority: 'urgent' }));
+        await channel.deliver(msg({ ...base, id: 'plain' }));
+        await channel.deliver(msg({ ...base, id: 'plain', reminderCount: 1, repeatCount: 3 }));
+        await channel.deliver(msg({ ...base, id: 'plain', reminderCount: 1, repeatCount: 3 }));
+        expect(notification).toHaveBeenCalledTimes(2);
+        const events = notification.mock.calls.map((c) => c[0].params);
+        expect(events[0].meta).toMatchObject({ id: 'urgent', priority: 'urgent' });
+        expect(events[0].content.startsWith('[urgent] [info]')).toBe(true);
+        expect(events[1].meta).toMatchObject({ id: 'plain', reminder: '1' });
+        expect(events[1].content.startsWith('[reminder 1] [info]')).toBe(true);
+        expect(channel.stats).toMatchObject({ delivered: 2, digested: 1, duplicates: 1 });
+        channel.close();
+    });
     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';

package/dist/manifest-size.test.js

@@ -59,6 +59,9 @@ afterEach(() => { vi.restoreAllMocks(); });
  * ORB-2544 added no named tool: ending a session rides the escape hatch;
  * orboto_who `state` and the agent_presence redaction line fit after the
  * agent_presence summary shrank (full = 171,160).
+ * ORB-2563 gave `orboto_agent_notify` `remind` and `urgent` inside the
+ * ceiling: the docs `content` parameter description shrank to pay for it
+ * (full = 171,194).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/tools/admin-writes.js

@@ -3,6 +3,7 @@
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
+import { rethrowFullExportInProgress, runningFullExportId } from './backup.js';
 function rewrite403(action) {
     return (err) => {
         if (err instanceof OrbotoApiError && err.status === 403) {
@@ -134,7 +135,7 @@ export function makeTriggerBackupHandler(client) {
             throw new Error(`Backup job "${jobName}" is currently disabled - enable it in /admin/backup first.`);
         }
         const run = await client.post(`/admin/backup/jobs/${job.id}/run`, {})
-            .catch(rewrite403('trigger_backup'));
+            .catch((err) => (runningFullExportId(err) ? rethrowFullExportInProgress(err) : rewrite403('trigger_backup')(err)));
         return {
             content: [{
                     type: 'text',

package/dist/tools/admin-writes.test.js

@@ -116,4 +116,17 @@ describe('orboto_trigger_backup', () => {
         ]);
         await expect(makeTriggerBackupHandler(client)({ jobName: 'nightly' })).rejects.toThrow(/super-admin/);
     });
+    it('names the running run when a full export is already in progress (ORB-2562)', async () => {
+        const refusal = { error: 'busy', errorKey: 'errors.backups.full_export_in_progress', errorParams: { runId: '6f0c1a52-3d4e-4b8a-9c71-2e5f8a9b0c1d' } };
+        const responses = [
+            { ok: true, status: 200, body: [{ id: 'j1', name: 'nightly', scope: 'full', schedule: null, isActive: true }] },
+            { ok: false, status: 409, body: refusal },
+        ];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
+            const r = responses.shift();
+            return { ok: r.ok, status: r.status, statusText: 'x', json: async () => r.body, text: async () => JSON.stringify(r.body) };
+        });
+        await expect(makeTriggerBackupHandler(client)({ jobName: 'nightly' }))
+            .rejects.toThrow('A full export is already running (run 6f0c1a52-3d4e-4b8a-9c71-2e5f8a9b0c1d); nothing was started.');
+    });
 });

package/dist/tools/agent-coordination.js

@@ -92,6 +92,14 @@ export function makeAgentPresenceHandler(client) {
         };
     };
 }
+/** ORB-2563 - mirror of AGENT_MESSAGE_PRIORITIES and the sender lines in @orboto/shared-schema agent-message-dedupe.ts (drift test in agent-coordination.test.ts). */
+export const NOTIFY_PRIORITIES = ['normal', 'urgent'];
+export function repeatedSendNotice(repeatCount) {
+    return `already delivered (sent ${repeatCount} times), not sent again`;
+}
+export function reminderSentNotice(reminderCount, repeatCount) {
+    return `reminder ${reminderCount} sent (sent ${repeatCount} times)`;
+}
 /** ORB-2263 - mirror of AgentNotifyRoutedToSchema in @orboto/shared-schema (drift test in agent-coordination.test.ts). */
 export const NOTIFY_ROUTED_TO = ['session', 'scope', 'account'];
 /** ORB-2264 - the 409 `no_recipient` as a tool error naming who could receive it instead. */
@@ -130,9 +138,24 @@ export function ownerMismatchText(err) {
     const text = p.ownerHint?.text ?? `"${p.topic ?? '?'}" belongs to ${p.owner ?? '?'}, not ${p.target ?? '?'}`;
     return `not sent: ${text}. Send again with route: true to deliver it to ${p.owner ?? 'the owner'}, or forceTarget: true to keep the target.`;
 }
+/** ORB-2563 - the 429 `reminder_too_soon` as a tool error naming when the next reminder is allowed. */
+export function reminderTooSoonText(err) {
+    if (err.status !== 429)
+        return null;
+    let body;
+    try {
+        body = JSON.parse(err.body);
+    }
+    catch {
+        return null;
+    }
+    if (body.errorKey !== 'errors.agents.reminder_too_soon')
+        return null;
+    return `not sent: message ${body.errorParams?.messageId ?? '?'} was sent or reminded too recently; the next reminder is allowed in ${body.errorParams?.retryAfter ?? '?'} seconds.`;
+}
 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.',
+    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.',
     inputSchema: z.object({
         targetEmail: z.string().email().optional(),
         to: z.string().min(3).max(200).optional(),
@@ -147,6 +170,8 @@ export const agentNotifyToolConfig = {
         toSessionRef: z.string().min(1).max(200).optional(),
         route: z.boolean().optional(),
         forceTarget: z.boolean().optional(),
+        remind: z.boolean().optional(),
+        urgent: z.boolean().optional(),
     }).shape,
     outputSchema: z.object({
         ok: z.literal(true),
@@ -205,10 +230,11 @@ export function makeAgentNotifyHandler(client) {
         const senderRef = mcpInstanceToken(args.senderRef, extra);
         let res;
         try {
-            res = await client.post('/v1/agent/notify', { ...args, senderRef, ownerCheck: 'refuse' }, { instanceToken: mcpInstanceToken(undefined, extra) });
+            const { urgent, ...rest } = args;
+            res = await client.post('/v1/agent/notify', { ...rest, ...(urgent ? { priority: NOTIFY_PRIORITIES[1] } : {}), senderRef, ownerCheck: 'refuse' }, { instanceToken: mcpInstanceToken(undefined, extra) });
         }
         catch (err) {
-            const refused = err instanceof OrbotoApiError ? noRecipientText(err) ?? ownerMismatchText(err) : null;
+            const refused = err instanceof OrbotoApiError ? noRecipientText(err) ?? ownerMismatchText(err) ?? reminderTooSoonText(err) : null;
             if (refused)
                 return { isError: true, content: [{ type: 'text', text: refused }] };
             throw err;
@@ -218,6 +244,16 @@ export function makeAgentNotifyHandler(client) {
         const target = recipients.length > 1 ? recipients.join(', ') : res.toSessionId ? `${who} session ${res.toSessionId.slice(0, 8)}` : who;
         const routedTo = res.routedTo ?? (res.toSessionId ? 'session' : 'account');
         const note = res.routingNote ? ` - ${res.routingNote}` : '';
+        if (res.deduplicated) {
+            const repeats = res.repeatCount ?? 2;
+            const line = res.reminded ? reminderSentNotice(res.reminderCount ?? 1, repeats) : repeatedSendNotice(repeats);
+            return {
+                content: [{ type: 'text', text: `${line}: ${target} (message ${res.messageId})` }],
+                structuredContent: {
+                    ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null, routedTo,
+                },
+            };
+        }
         return {
             content: [{ type: 'text', text: `${res.queued ? 'queued for' : 'notified'} ${target} (message ${res.messageId}, routed to ${routedTo}${note})${res.ownerHint?.routed ? `\nrouted to the owner of "${res.ownerHint.topic}" instead of ${res.ownerHint.target}` : ''}${res.hint ? `\nhint: ${res.hint}` : ''}` }],
             structuredContent: {

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

@@ -8,8 +8,8 @@
  */
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { readFileSync } from 'node:fs';
-import { OrbotoClient } from '../orboto-client.js';
-import { NOTIFY_ROUTED_TO, agentNotifyToolConfig, makeAgentHeartbeatHandler, makeAgentPresenceHandler, makeAgentNotifyHandler, } from './agent-coordination.js';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { NOTIFY_PRIORITIES, NOTIFY_ROUTED_TO, agentNotifyToolConfig, reminderSentNotice, reminderTooSoonText, repeatedSendNotice, makeAgentHeartbeatHandler, makeAgentPresenceHandler, makeAgentNotifyHandler, } from './agent-coordination.js';
 import { makeAgentMessagesHandler } from './agent-messages.js';
 afterEach(() => { vi.restoreAllMocks(); });
 function stub(responses) {
@@ -348,3 +348,41 @@ describe('orboto_agent_notify role addresses (ORB-2264)', () => {
         expect(agentNotifyToolConfig.description).toContain('integrator@KEY');
     });
 });
+describe('orboto_agent_notify dedupe and reminders (ORB-2563)', () => {
+    afterEach(() => { vi.restoreAllMocks(); });
+    it('mirrors the priorities and sender lines of the shared schema', () => {
+        const shared = readFileSync(new URL('../../../../packages/shared-schema/src/agent-message-dedupe.ts', import.meta.url), 'utf8');
+        const match = shared.match(/AGENT_MESSAGE_PRIORITIES = \[([^\]]+)\]/);
+        expect(match[1].split(',').map((v) => v.trim().replace(/'/g, ''))).toEqual([...NOTIFY_PRIORITIES]);
+        expect(shared).toContain('`already delivered (sent ${repeatCount} times), not sent again`');
+        expect(shared).toContain('`reminder ${reminderCount} sent (sent ${repeatCount} times)`');
+        expect(repeatedSendNotice(3)).toBe('already delivered (sent 3 times), not sent again');
+        expect(reminderSentNotice(1, 4)).toBe('reminder 1 sent (sent 4 times)');
+        expect(agentNotifyToolConfig.description).toContain('remind: true');
+        expect(agentNotifyToolConfig.description).toContain('Loops and retries never set remind or urgent');
+    });
+    it('says a deduplicated send was not sent again, and a reminder that it notified again', async () => {
+        const answers = [
+            { ok: true, messageId: '00000000-0000-4000-8000-000000000001', toSessionId: null, routedTo: 'account', deduplicated: true, repeatCount: 8 },
+            { ok: true, messageId: '00000000-0000-4000-8000-000000000001', toSessionId: null, routedTo: 'account', deduplicated: true, repeatCount: 9, reminded: true, reminderCount: 1 },
+        ];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
+            const body = answers.shift();
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const handler = makeAgentNotifyHandler(client);
+        const silent = await handler({ targetEmail: 'bob@example.com', subject: 'hi' });
+        expect(silent.content[0].text).toContain('already delivered (sent 8 times), not sent again');
+        expect(silent.structuredContent).toMatchObject({ messageId: '00000000-0000-4000-8000-000000000001' });
+        const reminder = await handler({ targetEmail: 'bob@example.com', subject: 'hi', remind: true, urgent: true });
+        expect(reminder.content[0].text).toContain('reminder 1 sent (sent 9 times)');
+        const sent = JSON.parse(String(fetch.mock.calls[1][1].body));
+        expect(sent).toMatchObject({ remind: true, priority: 'urgent' });
+        expect(sent).not.toHaveProperty('urgent');
+    });
+    it('turns the 429 reminder_too_soon into a tool error with the wait', () => {
+        const err = new OrbotoApiError(429, JSON.stringify({ errorKey: 'errors.agents.reminder_too_soon', errorParams: { messageId: 'm-1', retryAfter: 300 } }), 'http://x');
+        expect(reminderTooSoonText(err)).toContain('allowed in 300 seconds');
+        expect(reminderTooSoonText(new OrbotoApiError(409, '{}', 'http://x'))).toBeNull();
+    });
+});

package/dist/tools/agent-messages.js

@@ -11,6 +11,15 @@ import { z } from 'zod';
 import { makeAgentMessageWorkHandler } from './agent-message-work.js';
 import { mcpInstanceToken } from './shared.js';
 const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
+/** ORB-2563 - `[urgent]`, `sent N times` and `reminder N` next to a message, the same words the CLI prints. */
+export function repeatMarks(m) {
+    const marks = [
+        m.priority === 'urgent' ? 'urgent' : '',
+        m.repeatCount && m.repeatCount > 1 ? `sent ${m.repeatCount} times` : '',
+        m.reminderCount ? `reminder ${m.reminderCount}` : '',
+    ].filter(Boolean);
+    return marks.length ? ` [${marks.join(', ')}]` : '';
+}
 const UNREGISTERED_INBOX_HINT = 'Not registered: only account mail is listed. Register with orboto_session_start to see the mail addressed to your session.';
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
@@ -116,7 +125,7 @@ export function makeAgentMessagesHandler(client) {
         else
             q.set('excludeRef', instanceToken);
         const { messages, sessionId, counts } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
-        const header = (m) => `${m.own ? `[sent] ${sentState(m)} ` : ''}[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})`;
+        const header = (m) => `${m.own ? `[sent] ${sentState(m)} ` : ''}[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''}${repeatMarks(m)} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})`;
         const lines = messages.length === 0
             ? [acked > 0 ? `Acknowledged ${acked} message(s). Inbox empty.` : 'Inbox empty.']
             : messages.flatMap((m) => (compact ? compactLines(m, header(m)) : [`${header(m)}${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`]));

package/dist/tools/backup.js

@@ -8,6 +8,7 @@
  * download mechanism. `OrbotoClient.postBinary` / `getBinary` fetch the bytes.
  */
 import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
 /**
  * ORB-1504 - an operator passphrase is deliberately NOT an MCP input: it
  * would land in the conversation transcript and the tool-call audit. The
@@ -16,15 +17,38 @@ import { z } from 'zod';
  */
 const seal = (run) => run.sealed ? ` [encrypted, ${run.sealCustody ?? 'platform'} key${run.sealKeyFingerprint ? ` ${run.sealKeyFingerprint}` : ''}]` : '';
 const mb = (n) => `${Math.round((n / 1024 / 1024) * 10) / 10} MB`;
+/** ORB-2562 - the running run's id when the API refused a full export start with 409 errors.backups.full_export_in_progress. */
+export function runningFullExportId(err) {
+    if (!(err instanceof OrbotoApiError) || err.status !== 409)
+        return null;
+    try {
+        const body = JSON.parse(err.body);
+        if (body.errorKey !== 'errors.backups.full_export_in_progress')
+            return null;
+        return typeof body.errorParams?.runId === 'string' ? body.errorParams.runId : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rethrows a full-export refusal as a sentence that names the running run. */
+export function rethrowFullExportInProgress(err) {
+    const runId = runningFullExportId(err);
+    if (runId) {
+        throw new Error(`A full export is already running (run ${runId}); nothing was started. Download that run with orboto_download_backup once orboto_list_backups shows it as success.`);
+    }
+    throw err;
+}
 export const createFullBackupToolConfig = {
     title: 'Create + download a full workspace backup',
-    description: 'Create an on-demand FULL workspace backup (database + storage) and return it as a base64 resource attachment - one call; a background run this tool polls, minutes on a large workspace. Rows and file references share one snapshot; a missing file fails the run, never a partial archive. With backup encryption on the attachment is the sealed archive, not a ZIP. Requires admin:backup:export; scheduled jobs use orboto_trigger_backup.',
+    description: 'Create an on-demand FULL workspace backup (database + storage) and return it as a base64 resource attachment - one call; a background run this tool polls, minutes on a large workspace. Rows and file references share one snapshot; a missing file fails the run, never a partial archive. With backup encryption on the attachment is the sealed archive, not a ZIP. While another full export runs it starts nothing and names that run. Requires admin:backup:export; scheduled jobs use orboto_trigger_backup.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeCreateFullBackupHandler(client) {
     return async () => {
-        const { runId, sealed } = await client.post('/admin/backup/full', {});
+        const { runId, sealed } = await client.post('/admin/backup/full', {})
+            .catch(rethrowFullExportInProgress);
         const t0 = Date.now();
         for (;;) {
             await new Promise((r) => setTimeout(r, 3000));

package/dist/tools/backup.test.js

@@ -67,6 +67,16 @@ describe('orboto_create_full_backup (ORB-1301 / async since ORB-1717)', () => {
             vi.useRealTimers();
         }
     });
+    it('names the running run instead of starting a second full export (ORB-2562)', async () => {
+        const refusal = { error: 'busy', errorKey: 'errors.backups.full_export_in_progress', errorParams: { runId: '6f0c1a52-3d4e-4b8a-9c71-2e5f8a9b0c1d' } };
+        const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+            ok: false, status: 409, statusText: 'Conflict', headers: new Headers({ 'content-type': 'application/json' }),
+            json: async () => refusal, text: async () => JSON.stringify(refusal),
+        });
+        await expect(makeCreateFullBackupHandler(client)())
+            .rejects.toThrow('A full export is already running (run 6f0c1a52-3d4e-4b8a-9c71-2e5f8a9b0c1d); nothing was started.');
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
     it.each(['disk full', 'Backup source object is missing, unreadable or incomplete'])('a failed run surfaces %s instead of a partial ZIP', async (message) => {
         vi.useFakeTimers();
         const download = vi.spyOn(client, 'getBinary');

package/dist/tools/docs.js

@@ -276,7 +276,7 @@ export const createDocToolConfig = {
     inputSchema: z.object({
         spaceId: z.string().min(1).describe('Target doc space - key (e.g. ORB-S1), name, or UUID. Discover via orboto_list_doc_spaces.'),
         title: z.string().min(1).max(255),
-        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Pass an empty string or omit for a blank page. Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown reads as neutral, label <= 24 chars).'),
+        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Empty or omitted: a blank page. Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown = neutral, label <= 24 chars).'),
         parentDocId: z.string().uuid().nullable().optional().describe('Nest under another doc.'),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional().describe('Defaults to "workspace".'),
         icon: z.string().nullish().describe('Single emoji shown in the tree.'),

package/package.json

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