@orboto/mcp 0.222.2 → 0.224.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/channel-start.js

@@ -0,0 +1,52 @@
+/**
+ * ORB-2584 - a stdio server is a wake channel only when its harness delivers
+ * one: `orboto claude` marks the start in ORBOTO_CLAUDE_CHANNEL (the Go
+ * `orboto mcp serve` checks that the marker names this harness's launcher),
+ * or the operator opts in with ORBOTO_MCP_CHANNEL=1. `orboto mcp serve` runs
+ * this server at the instance's version, so a launching CLI released before
+ * the marker, and a start with no CLI at all, keep the channel they always had
+ * (`legacy`). Anything else runs as a plain tool server.
+ */
+export const CLAUDE_CHANNEL_ENV = 'ORBOTO_CLAUDE_CHANNEL';
+/** Mirror of CHANNEL_START_CUTOVER_VERSION in @orboto/shared-schema agent-session-wake.ts. */
+export const CHANNEL_START_CUTOVER_VERSION = '0.224.0';
+function semver(raw) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(raw.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+/** Mirror of releasedBeforeChannelStart: a released version below the cut-over; a dev build, 0.0.0 or no version is current. */
+export function releasedBeforeChannelStart(version) {
+    const parsed = version ? semver(version) : null;
+    const cut = semver(CHANNEL_START_CUTOVER_VERSION);
+    if (!parsed || parsed.every((n) => n === 0))
+        return false;
+    for (let i = 0; i < 3; i += 1)
+        if (parsed[i] !== cut[i])
+            return parsed[i] < cut[i];
+    return false;
+}
+/** The version of the CLI that launched this server, from the origin it handed over in ORBOTO_ORIGIN; null without one. */
+function launchingCliVersion(env) {
+    const handed = (env.ORBOTO_ORIGIN ?? '').trim();
+    if (!handed)
+        return null;
+    return new URLSearchParams(handed).get('version')?.trim() ?? '';
+}
+/**
+ * The start that delivers this server's channel, or null. ORBOTO_MCP_CHANNEL=0 wins, then the launcher marker, then
+ * ORBOTO_MCP_CHANNEL=1; without them a launching CLI released before the marker (its ORBOTO_ORIGIN version, or only
+ * ORBOTO_MCP_CLI_OUTDATED from a CLI too old to hand an origin over) and a start without any CLI are `legacy`.
+ */
+export function channelStartFromEnv(env = process.env) {
+    const flag = (env.ORBOTO_MCP_CHANNEL ?? '').trim();
+    if (flag === '0')
+        return null;
+    if (/^[1-9]\d{0,9}$/.test((env[CLAUDE_CHANNEL_ENV] ?? '').trim()))
+        return 'orboto-claude';
+    if (flag === '1')
+        return 'explicit';
+    const cli = launchingCliVersion(env);
+    if (cli !== null)
+        return releasedBeforeChannelStart(cli) ? 'legacy' : null;
+    return 'legacy';
+}

package/dist/channel-start.test.js

@@ -0,0 +1,83 @@
+/**
+ * ORB-2584 - the stdio server is a wake channel only for a start that
+ * delivers one; the session-start digest prints the lines the server renders.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CHANNEL_START_CUTOVER_VERSION, channelStartFromEnv, CLAUDE_CHANNEL_ENV, releasedBeforeChannelStart } from './channel-start.js';
+import { channelClientInfo, toolServerHeartbeat } from './claude-context.js';
+import { OrbotoClient } from './orboto-client.js';
+import { makeSessionStartHandler } from './tools/session-start.js';
+import { whoLine } from './tools/agent-who.js';
+import { AGENT_WAKE_LABELS } from './tools/agent-presence-schema.js';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+afterEach(() => { vi.restoreAllMocks(); });
+describe('ORB-2584 - the channel needs a channel-enabled start', () => {
+    const origin = (version) => `host=build-host&pid=4100&client=orboto-cli&version=${version}&harness=claude-code`;
+    it('a plain claude launched by a current CLI runs a tool server; orboto claude marks it; ORBOTO_MCP_CHANNEL=0 always wins', () => {
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin(CHANNEL_START_CUTOVER_VERSION) })).toBeNull();
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin('0.224.3'), CLAUDECODE: '1' })).toBeNull();
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin(CHANNEL_START_CUTOVER_VERSION), [CLAUDE_CHANNEL_ENV]: '4242' })).toBe('orboto-claude');
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin(CHANNEL_START_CUTOVER_VERSION), [CLAUDE_CHANNEL_ENV]: 'yes' })).toBeNull();
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin(CHANNEL_START_CUTOVER_VERSION), ORBOTO_MCP_CHANNEL: '1' })).toBe('explicit');
+        expect(channelStartFromEnv({ ORBOTO_MCP_CHANNEL: '0', [CLAUDE_CHANNEL_ENV]: '4242' })).toBeNull();
+        expect(channelStartFromEnv({ ORBOTO_MCP_CHANNEL: '0' })).toBeNull();
+    });
+    it('a launching CLI released before the marker keeps the channel as legacy, read from ORBOTO_ORIGIN or, for a CLI too old to hand one over, ORBOTO_MCP_CLI_OUTDATED; a dev CLI is current', () => {
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin('0.223.0') })).toBe('legacy');
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin('0.223.1'), ORBOTO_MCP_CLI_OUTDATED: 'orboto CLI 0.223.1 is older than the instance (0.224.0)' })).toBe('legacy');
+        expect(channelStartFromEnv({ ORBOTO_MCP_CLI_OUTDATED: 'orboto CLI 0.220.4 is older than the instance (0.224.0)' })).toBe('legacy');
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin('0.224.0'), ORBOTO_MCP_CLI_OUTDATED: 'orboto CLI 0.224.0 is older than the instance (0.224.1)' })).toBeNull();
+        expect(channelStartFromEnv({ ORBOTO_ORIGIN: origin('dev') })).toBeNull();
+    });
+    it('a start without any CLI (a hand-configured npx entry) keeps the channel it had before the marker, as legacy', () => {
+        expect(channelStartFromEnv({})).toBe('legacy');
+        expect(channelStartFromEnv({ CLAUDECODE: '1' })).toBe('legacy');
+    });
+    it('the cut-over mirrors @orboto/shared-schema', () => {
+        const shared = readFileSync(resolve(process.cwd(), '../../packages/shared-schema/src/agent-session-wake.ts'), 'utf8');
+        expect(shared).toContain(`export const CHANNEL_START_CUTOVER_VERSION = '${CHANNEL_START_CUTOVER_VERSION}';`);
+        for (const v of ['0.223.0', '0.223.1'])
+            expect(releasedBeforeChannelStart(v)).toBe(true);
+        for (const v of ['0.224.0', '0.224.0-rc.1', 'dev', '0.0.0', ''])
+            expect(releasedBeforeChannelStart(v)).toBe(false);
+    });
+    it('a stdio server without a channel heartbeats once as a tool server', () => {
+        expect(toolServerHeartbeat(' Build-Host ')).toEqual({ toolServer: true, host: 'build-host' });
+    });
+    it('the channel heartbeat carries the start marker', () => {
+        expect(channelClientInfo(null, '', 'orboto-claude')).toEqual({ channel: 'claude-code', channelStart: 'orboto-claude' });
+        expect(channelClientInfo(null, '')).toEqual({ channel: 'claude-code' });
+    });
+    it('the wake enum and labels mirror @orboto/shared-schema agent-session-wake.ts', () => {
+        const shared = readFileSync(resolve(process.cwd(), '../../packages/shared-schema/src/agent-session-wake.ts'), 'utf8');
+        expect(shared).toContain("export const AgentSessionWakeSchema = z.enum(['channel', 'stream', 'lane', 'on_call']);");
+        for (const [wake, label] of Object.entries(AGENT_WAKE_LABELS))
+            expect(shared).toContain(`  ${wake}: '${label}',`);
+    });
+    it('a directory line names a session nothing wakes', () => {
+        const line = whoLine({
+            sessionId: 's', shortId: 'abcd1234', email: 'claude@example.invalid', role: 'coordinator', projectKeys: [], addresses: [],
+            lastSeenAt: 'now', channel: { announced: null, online: false }, wake: 'on_call', currentTicket: null, status: 'idle',
+        });
+        expect(line).toContain('reads mail only on its own calls');
+    });
+    it('orboto_session_start prints the server notes and reports the wake', async () => {
+        const notes = ['Not carried over: the scope an earlier process of this session row declared (role coordinator; pid 4100).', 'Mail does not wake this session: start it with `orboto claude` to be woken.'];
+        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 },
+                '/users/me': { email: 'dev@example.invalid', fullName: 'Dev' },
+                '/agent-instructions': { instructions: 'rules', rulesHash: 'h' },
+            };
+            const key = Object.keys(map).find((k) => path === k);
+            return { ok: true, status: 200, statusText: 'OK', json: async () => (key ? map[key] : {}), text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(new OrbotoClient({ baseUrl: 'https://orboto.example.invalid', apiKey: 'orb_x' }))({}, { sessionId: 'x' });
+        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' } } } });
+    });
+});

package/dist/claude-context.js

@@ -46,8 +46,13 @@ export function readClaudeContext(dir, now = Date.now(), root = claudeContextDir
     }
     return fresh.length === 1 ? fresh[0] : null;
 }
-/** ORB-2465 - the channel heartbeat's clientInfo: the wake channel, the host `--host` filters on, and the context report. */
-export function channelClientInfo(context, host = hostname()) {
+/** ORB-2584 - the one heartbeat of a stdio server without a channel: its host and `toolServer`, so the API drops a `legacy` channel an older proxy of this row announced. */
+export function toolServerHeartbeat(host = hostname()) {
     const value = host.trim().toLowerCase().slice(0, 200);
-    return { channel: 'claude-code', ...(value ? { host: value } : {}), ...(context ?? {}) };
+    return { toolServer: true, ...(value ? { host: value } : {}) };
+}
+/** ORB-2465 - the channel heartbeat's clientInfo: the wake channel, the host `--host` filters on, and the context report; ORB-2584 - the start that delivers the channel. */
+export function channelClientInfo(context, host = hostname(), start) {
+    const value = host.trim().toLowerCase().slice(0, 200);
+    return { channel: 'claude-code', ...(start ? { channelStart: start } : {}), ...(value ? { host: value } : {}), ...(context ?? {}) };
 }

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

@@ -37,11 +37,11 @@ export const CHANNEL_START_COMMANDS = {
     continueLatest: 'orboto claude --continue',
     resumeById: 'orboto claude --resume <session id>',
 };
-/** The raw Claude Code form, for a machine without the orboto CLI. */
+/** The raw Claude Code form, for a machine without the orboto CLI; ORB-2584 - ORBOTO_MCP_CHANNEL=1 is the operator's marker that this start delivers the channel. */
 export const CHANNEL_START_COMMANDS_WITHOUT_CLI = {
-    fresh: `claude ${START_FLAG}`,
-    continueLatest: `claude ${START_FLAG} --continue`,
-    resumeById: `claude ${START_FLAG} --resume <session id>`,
+    fresh: `ORBOTO_MCP_CHANNEL=1 claude ${START_FLAG}`,
+    continueLatest: `ORBOTO_MCP_CHANNEL=1 claude ${START_FLAG} --continue`,
+    resumeById: `ORBOTO_MCP_CHANNEL=1 claude ${START_FLAG} --resume <session id>`,
 };
 /** The `orboto_session_start` block of a stdio proxy whose channel is on. */
 export function channelStartLines() {
@@ -91,14 +91,19 @@ export function isImmediate(m, now, digestMinutes) {
         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 = [
-        `${marks ? `${marks} ` : ''}[${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)
@@ -110,7 +115,7 @@ 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' } : {}),

package/dist/index.js

@@ -53,7 +53,12 @@ async function main() {
             console.error(`[orboto-mcp] ${err.message}`);
             process.exit(1);
         }
-        const channel = (process.env.ORBOTO_MCP_CHANNEL ?? '1') !== '0';
+        const { channelStartFromEnv } = await import('./channel-start.js');
+        const channelStart = channelStartFromEnv({
+            ORBOTO_MCP_CHANNEL: process.env.ORBOTO_MCP_CHANNEL, ORBOTO_CLAUDE_CHANNEL: process.env.ORBOTO_CLAUDE_CHANNEL,
+            ORBOTO_ORIGIN: process.env.ORBOTO_ORIGIN, ORBOTO_MCP_CLI_OUTDATED: process.env.ORBOTO_MCP_CLI_OUTDATED,
+        });
+        const channel = channelStart !== null;
         const server = await buildOrbotoMcpServer({ ...clientConfig, channel, instanceToken: (await import('./tools/shared.js')).mcpProcessInstance() });
         const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
         const stdio = new StdioServerTransport();
@@ -73,7 +78,7 @@ async function main() {
                 void inbox.deliverNotice(CLI_OUTDATED_NOTICE, outdated);
             const { readClaudeContext, channelClientInfo } = await import('./claude-context.js');
             const beat = () => {
-                preflightClient.post('/v1/agent/heartbeat', { clientInfo: channelClientInfo(readClaudeContext(process.cwd())) }, { instanceToken })
+                preflightClient.post('/v1/agent/heartbeat', { clientInfo: channelClientInfo(readClaudeContext(process.cwd()), undefined, channelStart ?? undefined) }, { instanceToken })
                     .catch((err) => { console.error(`[orboto-mcp] channel heartbeat failed: ${err.message}`); });
             };
             beat();
@@ -84,6 +89,11 @@ async function main() {
             const { endProbeSessionOnStdinEnd } = await import('./probe-session.js');
             endProbeSessionOnStdinEnd({ env: process.env, stdin: process.stdin, client: preflightClient, instanceToken, cleanup, exit: (code) => process.exit(code), settle: releaseCapacity });
         }
+        else {
+            const { toolServerHeartbeat } = await import('./claude-context.js');
+            preflightClient.post('/v1/agent/heartbeat', { clientInfo: toolServerHeartbeat() }, { instanceToken: (await import('./tools/shared.js')).mcpProcessInstance() })
+                .catch((err) => { console.error(`[orboto-mcp] heartbeat failed: ${err.message}`); });
+        }
         return;
     }
     if (transport === 'http') {

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/agent-coordination.js

@@ -4,7 +4,7 @@
  * @see ORB-704, ORB-706
  */
 import { z } from 'zod';
-import { AgentInventoryEntrySchema, AgentInventoryKindSchema } from './agent-presence-schema.js';
+import { AGENT_WAKE_LABELS, AgentInventoryEntrySchema, AgentInventoryKindSchema } from './agent-presence-schema.js';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken } from './shared.js';
 import { AgentSessionScopeSchema } from './agent-session-scope.js';
@@ -37,9 +37,13 @@ export function makeAgentHeartbeatHandler(client) {
     return async (args, extra) => {
         const res = await client.post('/v1/agent/heartbeat', args, { instanceToken: mcpInstanceToken(undefined, extra) });
         const scope = res.scope ? ` scope=${JSON.stringify(res.scope)}` : '';
+        const notes = (res.notes ?? []).map((n) => `\n${n}`).join('');
         return {
-            content: [{ type: 'text', text: `heartbeat ack - sessionToken=${res.sessionToken.slice(0, 8)}… session ${res.sessionId.slice(0, 8)}${scope}` }],
-            structuredContent: { sessionToken: res.sessionToken, sessionId: res.sessionId, scope: res.scope ?? null, ...(res.startedBy !== undefined ? { startedBy: res.startedBy } : {}) },
+            content: [{ type: 'text', text: `heartbeat ack - sessionToken=${res.sessionToken.slice(0, 8)}… session ${res.sessionId.slice(0, 8)}${scope}${notes}` }],
+            structuredContent: {
+                sessionToken: res.sessionToken, sessionId: res.sessionId, scope: res.scope ?? null, ...(res.startedBy !== undefined ? { startedBy: res.startedBy } : {}),
+                ...(res.wake ? { wake: res.wake } : {}), ...(res.notes ? { notes: res.notes } : {}),
+            },
         };
     };
 }
@@ -52,10 +56,10 @@ export function originText(s) {
 }
 export const agentPresenceToolConfig = {
     title: 'Workspace agent presence',
-    description: 'Active agent instances. The orboto_who set: lane workers and reviewers, inbox, MCP and runner connections; rows carry kind (agent | human, by credential; isBot is its alias), actsAs, owner, projects, connections, lane, sessionId, userEmail, runtime (clientInfo.name), capabilities, status, current ticket, reconnects, origin (host, repo, pid, client, harness, credential) and state (live | quiet | orphaned | unknown_origin). Operators (admin:agents:read or admin:system:read) see the workspace, others their own sessions and those declared on their projects, a foreign row redacted (redacted: true, no pid, repo, machine, connections, inbox or owner). Check it before dispatching a sub-task. projectKey and kind filter client-side like `orboto agents --project KEY --bots|--humans`.',
+    description: 'Active agent instances. The orboto_who set: lane workers and reviewers, inbox, MCP and runner connections; rows carry kind (agent | human by credential; alias isBot), actsAs, owner, projects, connections, wake (on_call: nothing wakes it), lane, sessionId, userEmail, runtime, capabilities, status, current ticket, reconnects, origin (host, repo, pid, client, harness, credential), state (live | quiet | orphaned | unknown_origin). Operators (admin:agents:read or admin:system:read) see the workspace, others their own sessions and those on their projects, a foreign row redacted (no pid, repo, machine, connections, inbox, owner). projectKey and kind filter client-side (`orboto agents --project KEY --bots|--humans`).',
     inputSchema: z.object({
-        projectKey: z.string().min(1).max(64).optional().describe('Keep only rows whose projects contain this project key (case-insensitive).'),
-        kind: AgentInventoryKindSchema.optional().describe('Keep only rows classified as agent or human by their credential.'),
+        projectKey: z.string().min(1).max(64).optional().describe('Only rows whose projects hold this key.'),
+        kind: AgentInventoryKindSchema.optional().describe('Only rows of this kind (by credential).'),
     }).shape,
     outputSchema: z.object({
         sessions: z.array(AgentInventoryEntrySchema),
@@ -83,7 +87,7 @@ export function makeAgentPresenceHandler(client) {
                 const work = s.workingOnTicket
                     ? ` · working on [${s.workingOnTicket.projectKey ?? '?'}] ${s.workingOnTicket.key ?? s.workingOnTicket.id} (${s.workingOnTicket.title})`
                     : '';
-                lines.push(`- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${originText(s)}${work}; owner: ${s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self')}${s.lane ? `; lane: ${s.lane.name}` : ''}${s.projects.length ? `; projects: ${s.projects.map((p) => p.key).join(', ')}` : ''}${s.connections.length ? `; connections: ${s.connections.map((c) => c.type).join(', ')}` : ''}`);
+                lines.push(`- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${originText(s)}${work}; owner: ${s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self')}${s.lane ? `; lane: ${s.lane.name}` : ''}${s.projects.length ? `; projects: ${s.projects.map((p) => p.key).join(', ')}` : ''}${s.connections.length ? `; connections: ${s.connections.map((c) => c.type).join(', ')}` : ''}${s.wake ? `; ${AGENT_WAKE_LABELS[s.wake]}` : ''}`);
             }
         }
         return {
@@ -262,6 +266,7 @@ export function makeAgentNotifyHandler(client) {
                 ...(recipients.length ? { recipients } : {}),
                 ...(res.queued ? { queued: true } : {}),
                 ...(res.ownerHint?.routed ? { owner: res.ownerHint.ownerAddress } : {}),
+                ...(res.wakeable !== undefined ? { wakeable: res.wakeable } : {}),
             },
         };
     };

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,12 +11,14 @@ 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. */
+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(', ')}]` : '';
 }
@@ -104,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();
@@ -137,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