@orboto/mcp 0.222.0 → 0.223.0

package/dist/agent-context.js

@@ -0,0 +1,49 @@
+/** ORB-2576 - the agent context of a stdio MCP server, read exactly as the CLI reads it (cli/internal/cmd/session_context.go). */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The session id Claude Code hands its stdio MCP servers; an HTTP server never sees it. */
+export const CLAUDE_SESSION_ENV = 'CLAUDE_CODE_SESSION_ID';
+/** The Claude Code hook events the CLI registers (claude_hook_settings.go OrbotoHookEvents). */
+export const ORBOTO_HOOK_EVENTS = ['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'Stop', 'StopFailure', 'SessionStart', 'SubagentStart', 'SubagentStop', 'SessionEnd', 'Notification'];
+/** The project settings file the hooks are registered in. */
+export const PROJECT_CLAUDE_SETTINGS = '.claude/settings.local.json';
+/** The turn-state file name the CLI hook writes for a session. */
+export function turnStateName(sessionId) {
+    return `${sessionId.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80) || 'session'}.json`;
+}
+/** The orboto hook events a checkout's settings lack; null when the file cannot be read. */
+export function missingTurnHooks(dir) {
+    let hooks = {};
+    try {
+        hooks = JSON.parse(readFileSync(join(dir, PROJECT_CLAUDE_SETTINGS), 'utf8')).hooks ?? {};
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            return null;
+    }
+    const covered = (groups) => Array.isArray(groups) && groups.some((g) => Array.isArray(g?.hooks)
+        && (g.hooks).some((h) => String(h?.command ?? '').includes('claude-hook')));
+    return ORBOTO_HOOK_EVENTS.filter((event) => !covered(hooks[event]));
+}
+/** The context key, or '' when no complete hook set confirms the current generation or a subagent shares the session. */
+export function agentContextKey(env = process.env, home = homedir()) {
+    const id = (env[CLAUDE_SESSION_ENV] ?? '').trim();
+    if (!id)
+        return '';
+    let state;
+    try {
+        state = JSON.parse(readFileSync(join(home, '.orboto', 'claude-turn', turnStateName(id)), 'utf8'));
+    }
+    catch {
+        return '';
+    }
+    if (!state.state || typeof state.contextStartedAt !== 'string' || !state.contextStartedAt)
+        return '';
+    if (Array.isArray(state.activeSubagents) && state.activeSubagents.length > 0)
+        return '';
+    const missing = typeof state.cwd === 'string' ? missingTurnHooks(state.cwd) : null;
+    if (!missing || missing.length > 0)
+        return '';
+    return `claude-code ${id} ${state.contextStartedAt}`;
+}

package/dist/agent-context.test.js

@@ -0,0 +1,45 @@
+/** ORB-2576 - a stdio server reads the agent context the CLI hook recorded; anything else is an unknown context. */
+import { describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ORBOTO_HOOK_EVENTS, agentContextKey, missingTurnHooks, turnStateName } from './agent-context.js';
+function hooks(dir, events = ORBOTO_HOOK_EVENTS) {
+    mkdirSync(join(dir, '.claude'), { recursive: true });
+    writeFileSync(join(dir, '.claude', 'settings.local.json'), JSON.stringify({ hooks: Object.fromEntries(events.map((e) => [e, [{ hooks: [{ type: 'command', command: 'orboto claude-hook' }] }]])) }));
+}
+function home(session, contextStartedAt, extra = {}) {
+    const dir = mkdtempSync(join(tmpdir(), 'orboto-mcp-context-'));
+    hooks(dir);
+    if (session) {
+        mkdirSync(join(dir, '.orboto', 'claude-turn'), { recursive: true });
+        writeFileSync(join(dir, '.orboto', 'claude-turn', turnStateName(session)), JSON.stringify({ sessionId: session, cwd: dir, state: 'idle', contextStartedAt, ...extra }));
+    }
+    return dir;
+}
+describe('agentContextKey (ORB-2576)', () => {
+    it('names the Claude Code session and the generation its SessionStart hook recorded', () => {
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home('sess-a', '2026-10-18T10:00:00Z'))).toBe('claude-code sess-a 2026-10-18T10:00:00Z');
+    });
+    it('is unknown without the session id, without the hook record, or without a generation', () => {
+        expect(agentContextKey({}, home('sess-a', '2026-10-18T10:00:00Z'))).toBe('');
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home())).toBe('');
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home('sess-a'))).toBe('');
+    });
+    it('a subagent inside a running session gets the rules in full: its session id is the parent\'s, so the context is unknown while it runs', () => {
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home('sess-a', '2026-10-18T10:00:00Z', { activeSubagents: ['agent-1'] }))).toBe('');
+    });
+    it('a hook set without the subagent events is an unknown context', () => {
+        const dir = home('sess-a', '2026-10-18T10:00:00Z');
+        hooks(dir, ORBOTO_HOOK_EVENTS.filter((e) => !e.startsWith('Subagent')));
+        expect(missingTurnHooks(dir)).toEqual(['SubagentStart', 'SubagentStop']);
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, dir)).toBe('');
+    });
+    it('registers the same hook events as the CLI and names the turn file like it does', () => {
+        const go = readFileSync(new URL('../../../cli/internal/cmd/claude_hook.go', import.meta.url), 'utf8') + readFileSync(new URL('../../../cli/internal/cmd/claude_hook_settings.go', import.meta.url), 'utf8');
+        for (const event of ORBOTO_HOOK_EVENTS)
+            expect(go).toContain(`"${event}"`);
+        expect(turnStateName('a/b..c')).toBe('abc.json');
+        expect(turnStateName('///')).toBe('session.json');
+    });
+});

package/dist/inbox-channel-acknowledged.test.js

@@ -0,0 +1,19 @@
+/** ORB-2564 - a person's acknowledgement wakes the sending session as kind `acknowledged`, and the inbox names the ladder step of urgent mail. */
+import { describe, expect, it } from 'vitest';
+import { eventKind, renderEvent } from './inbox-channel.js';
+import { repeatMarks } from './tools/agent-messages.js';
+describe('ORB-2564 - acknowledged wake', () => {
+    it('renders the acknowledgement as its own kind and any other message by its kind', () => {
+        const ack = { id: 'a1', kind: 'info', subject: 'acknowledged: disk full', payload: { type: 'acknowledged', acknowledgedMessageId: 'm1' }, createdAt: new Date().toISOString() };
+        expect(eventKind(ack)).toBe('acknowledged');
+        const event = renderEvent(ack, Date.now());
+        expect(event.meta.kind).toBe('acknowledged');
+        expect(event.content.startsWith('[acknowledged] acknowledged: disk full')).toBe(true);
+        expect(eventKind({ kind: 'request', payload: { type: 'ticket_ready' } })).toBe('request');
+    });
+    it('marks how far an urgent message escalated', () => {
+        expect(repeatMarks({ priority: 'urgent', escalationStep: 2 })).toBe(' [urgent, escalated: deputy]');
+        expect(repeatMarks({ priority: 'urgent', escalationStep: 1, reminderCount: 1 })).toBe(' [urgent, reminder 1, escalated: mail and channels]');
+        expect(repeatMarks({ priority: 'normal' })).toBe('');
+    });
+});

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,19 +83,27 @@ 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)
         return true;
     return ASK.test(`${m.subject} ${firstLine(m.payload)}`);
 }
+/** ORB-2564 - a person acknowledged a message this session sent: the event kind is `acknowledged`, so the sender stops reminding. */
+export function eventKind(m) {
+    return m.payload?.type === 'acknowledged' ? 'acknowledged' : m.kind;
+}
 export function renderEvent(m, now) {
+    const kind = eventKind(m);
     const from = m.from?.label ?? m.fromUserId ?? 'unknown';
     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} ` : ''}[${kind}] ${m.subject}`,
         `from ${from} to ${to}${m.projectKey ? ` | project ${m.projectKey}` : ''} | id ${m.id}${m.threadId ? ` | thread ${m.threadId}` : ''}`,
     ];
     if (body)
@@ -103,9 +115,11 @@ export function renderEvent(m, now) {
     return {
         content: lines.join('\n'),
         meta: {
-            id: m.id, kind: m.kind, project: m.projectKey ?? '',
+            id: m.id, 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 +189,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/orboto-client.js

@@ -4,15 +4,27 @@
  */
 import { VERSION } from './version.js';
 import { originHeader } from './session-origin.js';
+/** ORB-2581 - the seconds a `Retry-After` header asks for (delta-seconds or an HTTP date); null when absent or unreadable. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (value == null || value.trim() === '')
+        return null;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const at = Date.parse(trimmed);
+    return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - now) / 1000));
+}
 export class OrbotoApiError extends Error {
     status;
     body;
     url;
-    constructor(status, body, url) {
+    retryAfterSeconds;
+    constructor(status, body, url, retryAfterSeconds = null) {
         super(`orboto API ${status}: ${body || '(empty body)'}`);
         this.status = status;
         this.body = body;
         this.url = url;
+        this.retryAfterSeconds = retryAfterSeconds;
         this.name = 'OrbotoApiError';
     }
 }
@@ -79,7 +91,7 @@ export class OrbotoClient {
         this.pendingAgentMail = mail ? Number(mail) || 0 : 0;
         if (!res.ok) {
             const body = await res.text().catch(() => '');
-            throw new OrbotoApiError(res.status, body, url);
+            throw new OrbotoApiError(res.status, body, url, parseRetryAfter(res.headers?.get?.('retry-after')));
         }
         return res;
     }

package/dist/session-origin.js

@@ -11,8 +11,22 @@ import { hostname } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { VERSION } from './version.js';
 const KEYS = [
-    ['host', 'host'], ['machine', 'machineId'], ['repo', 'repo'], ['pid', 'pid'], ['start', 'startedAt'], ['client', 'client'], ['version', 'clientVersion'], ['harness', 'harness'],
+    ['host', 'host'], ['machine', 'machineId'], ['repo', 'repo'], ['pid', 'pid'], ['start', 'startedAt'], ['client', 'client'], ['version', 'clientVersion'], ['harness', 'harness'], ['model', 'model'],
 ];
+const WRAPPED_HARNESSES = { claude: 'claude-code', 'claude-code': 'claude-code', codex: 'codex', gemini: 'gemini', kimi: 'kimi', agy: 'agy', antigravity: 'agy' };
+/** ORB-2571 - the harness that started a stdio proxy: the one `orboto <harness>` named, else the markers a harness sets. */
+export function stdioHarness(env = process.env) {
+    const wrapped = WRAPPED_HARNESSES[(env.ORBOTO_HARNESS ?? '').trim().toLowerCase()];
+    if (wrapped)
+        return wrapped;
+    if (env.CLAUDECODE)
+        return 'claude-code';
+    if (env.CODEX_THREAD_ID || env.CODEX_SESSION_ID)
+        return 'codex';
+    if (env.GEMINI_CLI)
+        return 'gemini';
+    return 'mcp-stdio';
+}
 /** The header value; empty fields are left out. */
 export function formatOrigin(origin) {
     const params = new URLSearchParams();
@@ -75,7 +89,8 @@ export function stdioOrigin(env = process.env) {
     return formatOrigin({
         host: shortHost(), machineId: machineId(), repo: repoBasename(), pid: process.ppid || null,
         client: 'orboto-mcp', clientVersion: VERSION,
-        harness: env.CLAUDECODE ? 'claude-code' : env.CODEX_THREAD_ID || env.CODEX_SESSION_ID ? 'codex' : 'mcp-stdio',
+        harness: stdioHarness(env),
+        model: /^[\x21-\x7e]{1,80}$/.test((env.ORBOTO_MODEL ?? '').trim()) ? env.ORBOTO_MODEL.trim() : null,
     });
 }
 /** The HTTP server's origin: the server process itself, the identity of every connection is its OAuth client. */

package/dist/session-origin.test.js

@@ -7,7 +7,7 @@ import { mkdtempSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createHttpServer } from './http-transport.js';
-import { formatOrigin, machineId, repoBasename, shortHost, stdioOrigin } from './session-origin.js';
+import { formatOrigin, machineId, repoBasename, shortHost, stdioHarness, stdioOrigin } from './session-origin.js';
 import { bindSessionInstance, mcpInstanceToken, releaseSessionInstance, stableClientInstance } from './tools/shared.js';
 import { InboxChannel, SESSION_ENDED_NOTICE } from './inbox-channel.js';
 describe('ORB-2544 - the origin header', () => {
@@ -20,6 +20,17 @@ describe('ORB-2544 - the origin header', () => {
         expect(params.get('harness')).toBe('claude-code');
         expect(params.get('client')).toBe('orboto-mcp');
     });
+    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');
+        expect(stdioHarness({ GEMINI_CLI: '1' })).toBe('gemini');
+        expect(stdioHarness({ CODEX_SESSION_ID: 's' })).toBe('codex');
+        expect(stdioHarness({})).toBe('mcp-stdio');
+        const params = new URLSearchParams(stdioOrigin({ ORBOTO_HARNESS: 'agy', ORBOTO_MODEL: 'gemini-4-argon' }));
+        expect(params.get('harness')).toBe('agy');
+        expect(params.get('model')).toBe('gemini-4-argon');
+        expect(new URLSearchParams(stdioOrigin({ ORBOTO_MODEL: 'has spaces' })).has('model')).toBe(false);
+    });
     it('reduces the host to its first label and a checkout to the repository basename', () => {
         expect(shortHost('Build-Host.example.lan.')).toBe('build-host');
         const root = mkdtempSync(join(tmpdir(), 'origin-'));

package/dist/tail-labels.js

@@ -36,6 +36,8 @@ export const TAIL_LABELS = [
     { method: 'GET', path: new RegExp(`^/v1/agent/messages/${SEG}/attachments(/${SEG}/url)?$`), label: 'orboto_agent_message_attachments' },
     { method: 'GET', path: /^\/admin\/agents\/transfers$/, label: 'orboto_agent_transfers' },
     { method: 'DELETE', path: new RegExp(`^/admin/agents/transfers/${SEG}$`), label: 'orboto_agent_transfers' },
+    { method: 'GET', path: new RegExp(`^/admin/agents/identities/${SEG}/query-rate-limit$`), label: 'orboto_agent_query_rate_limit' },
+    { method: 'PUT', path: new RegExp(`^/admin/agents/identities/${SEG}/query-rate-limit$`), label: 'orboto_agent_query_rate_limit' },
 ];
 /** The metrics label of one tool call: the stand-in tool name for a labelled api_call, else the tool name itself. */
 export function metricsToolName(toolName, args) {

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-instructions.js

@@ -12,7 +12,7 @@ function excerptOf(body) {
     return firstLine.length > 200 ? `${firstLine.slice(0, 199)}\u2026` : firstLine;
 }
 function renderBlock(b) {
-    const flag = b.enabled ? '' : ' [disabled]';
+    const flag = (b.enabled ? '' : ' [disabled]') + (b.mustRead ? ' [must read]' : '');
     const kind = b.builtinKey ? `default:${b.builtinKey}` : 'custom';
     return `- ${b.title}${flag}  (${kind}, ${b.body.length} chars, id ${b.id})\n  ${excerptOf(b.body)}`;
 }
@@ -62,6 +62,7 @@ export function makeListAgentInstructionsHandler(client) {
                     id: b.id,
                     title: b.title,
                     enabled: b.enabled,
+                    ...(b.mustRead ? { mustRead: true } : {}),
                     contentChars: b.body.length,
                     ...(b.builtinKey ? { builtinKey: b.builtinKey } : {}),
                 })),
@@ -81,9 +82,10 @@ export const createAgentInstructionToolConfig = {
         projectId: z.string().uuid().optional().describe('Required for scope=project.'),
         customerId: z.string().uuid().optional().describe('Required for scope=customer.'),
         enabled: z.boolean().optional(),
+        mustRead: z.boolean().optional(),
         sortOrder: z.number().int().optional(),
-        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (400*2 chars). Only after a call was blocked.'),
-        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this body genuinely needs the length. Audit-logged.'),
+        allowOversize: z.boolean().optional().describe('Override the hard size cap (800 chars) after a blocked call.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true: why the body needs the length (audit-logged).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -113,9 +115,10 @@ export const updateAgentInstructionToolConfig = {
         title: z.string().min(1).max(120).optional(),
         body: z.string().min(1).max(8000).optional(),
         enabled: z.boolean().optional(),
+        mustRead: z.boolean().optional(),
         sortOrder: z.number().int().optional(),
-        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (400*2 chars). Only after a call was blocked.'),
-        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this body genuinely needs the length. Audit-logged.'),
+        allowOversize: z.boolean().optional().describe('Override the hard size cap (800 chars) after a blocked call.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true: why the body needs the length (audit-logged).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };

package/dist/tools/agent-messages.js

@@ -11,6 +11,17 @@ 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() });
+const ESCALATED = ['', 'escalated: mail and channels', 'escalated: deputy'];
+/** ORB-2563 - `[urgent]`, `sent N times` and `reminder N` next to a message, the same words the CLI prints; ORB-2564 - the ladder step it reached. */
+export function repeatMarks(m) {
+    const marks = [
+        m.priority === 'urgent' ? 'urgent' : '',
+        m.repeatCount && m.repeatCount > 1 ? `sent ${m.repeatCount} times` : '',
+        m.reminderCount ? `reminder ${m.reminderCount}` : '',
+        ESCALATED[m.escalationStep ?? 0] ?? '',
+    ].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',
@@ -95,9 +106,11 @@ export function makeAgentMessagesHandler(client) {
             feedbackSent = res.feedbackSent;
         }
         let acked = 0;
+        let escalationsStopped = 0;
         if (args.ackIds && args.ackIds.length > 0) {
             const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds, instanceToken: mcpInstanceToken(undefined, extra) });
             acked = res.acked;
+            escalationsStopped = res.escalationsStopped ?? 0;
         }
         const compact = !args.all;
         const q = new URLSearchParams();
@@ -116,7 +129,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)}` : ''}`]));
@@ -128,6 +141,8 @@ export function makeAgentMessagesHandler(client) {
         if (args.dismiss) {
             lines.unshift(`Dismissed ${dismissedCount} message(s) as ${args.dismiss.reason}${closedCount > 0 ? `, ${closedCount} closed for the account` : ''}${feedbackSent > 0 ? `, ${feedbackSent} sender(s) told about the misroute` : ''}.`);
         }
+        if (escalationsStopped > 0)
+            lines.unshift(`Stopped the urgent escalation of ${escalationsStopped} message(s).`);
         if (sessionId)
             lines.push(`This session: ${sessionId.slice(0, 8)} (ref ${instanceToken}).`);
         else