@orboto/mcp 0.223.0 → 0.225.0

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.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() {

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/required-rules-wrapper.test.js

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

package/dist/test/child-window-test-timeout.test.js

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

package/dist/test/ci-window.js

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

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

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

package/dist/tools/agent-coordination.js

@@ -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-presence-schema.js

@@ -9,6 +9,15 @@ const AgentAccountRefSchema = z.object({ id: z.string().uuid(), name: z.string()
 export const AgentInventoryKindSchema = z.enum(['agent', 'human']);
 export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web', 'channel']);
 export const AgentInventoryConnectionSchema = z.object({ type: AgentConnectionTypeSchema, label: z.string() });
+/** ORB-2584 - mirror of AgentSessionWakeSchema in @orboto/shared-schema agent-session-wake.ts. */
+export const AgentSessionWakeSchema = z.enum(['channel', 'stream', 'lane', 'on_call']);
+/** ORB-2584 - mirror of AGENT_WAKE_LABELS: what presence lines print for each wake. */
+export const AGENT_WAKE_LABELS = {
+    channel: 'reachable by channel',
+    stream: 'reachable by inbox stream',
+    lane: 'reachable as a lane',
+    on_call: 'reads mail only on its own calls',
+};
 export const AgentInventoryProjectSchema = z.object({ id: z.string().uuid(), key: z.string(), name: z.string() });
 export const AgentInventoryEntrySchema = z.object({
     userId: z.string().uuid(),
@@ -25,6 +34,8 @@ export const AgentInventoryEntrySchema = z.object({
     lane: z.object({ id: z.string().uuid(), name: z.string(), role: z.string(), paused: z.boolean() }).nullable(),
     projects: z.array(AgentInventoryProjectSchema),
     connections: z.array(AgentInventoryConnectionSchema),
+    /** ORB-2584 - whether mail wakes the session (channel, stream, lane) or it reads mail only on its own calls (`on_call`). */
+    wake: AgentSessionWakeSchema.optional(),
     workingOnTicket: z.object({ id: z.string().uuid(), key: z.string().nullable(), title: z.string(), projectKey: z.string().nullable() }).nullable(),
     workSessions: z.array(z.object({
         ticketId: z.string().uuid(), ticketKey: z.string().nullable(), role: z.string(), leaseUntil: z.string(),

package/dist/tools/agent-wakes.js

@@ -3,6 +3,7 @@
  * did with it and what it cost.
  */
 import { z } from 'zod';
+import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
 export const agentWakesToolConfig = {
     title: 'Wake ledger',
     description: 'The wake ledger: who woke this account\'s sessions and at what cost. It names the visibility rule that delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
@@ -21,7 +22,8 @@ function statsLine(e) {
     const precision = e.precision === null ? 'unjudged' : `${Math.round(e.precision * 100)}%`;
     const tokens = e.wrongWakeContextTokens > 0 ? `, wrong wakes cost ${e.wrongWakeContextTokens} tokens` : '';
     const backlog = e.backlogSeen > 0 ? `, ${e.backlogSeen} backlog seen` : '';
-    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}${backlog}`;
+    const wake = e.wake ? `, now ${AGENT_WAKE_LABELS[e.wake]}` : '';
+    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}${backlog}${wake}`;
 }
 export function makeAgentWakesHandler(client) {
     return async (args) => {

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

@@ -25,6 +25,14 @@ describe('orboto_agent_wakes', () => {
         expect(text).toContain('- worker (ef56ab78): 1 wakes, precision unjudged, median ? ms, top rule -');
         expect(text).toContain('Senders:\n- (none)');
     });
+    it('ORB-2584 - names how mail reaches each session now', async () => {
+        const { client } = clientReturning({
+            hours: 24,
+            sessions: [{ label: 'coordinator (aa11bb22)', wakes: 2, precision: null, medianLatencyMs: null, topRule: null, wrongWakeContextTokens: 0, backlogSeen: 0, wake: 'on_call' }],
+            senders: [],
+        });
+        expect(textOf(await makeAgentWakesHandler(client)({ stats: true }))).toContain('- coordinator (aa11bb22): 2 wakes, precision unjudged, median ? ms, top rule -, now reads mail only on its own calls');
+    });
     it('says so when nothing woke anyone', async () => {
         const { client } = clientReturning({ hours: 24, sessions: [], senders: [] });
         expect(textOf(await makeAgentWakesHandler(client)({ stats: true }))).toContain('- (no wakes)');

package/dist/tools/agent-who.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { AgentSessionRoleSchema } from './agent-session-scope.js';
 import { ownerLine } from './responsibilities.js';
 import { originText } from './agent-coordination.js';
+import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
 export const agentWhoToolConfig = {
     title: 'Who receives agent mail',
     description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. Each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it).',
@@ -18,7 +19,8 @@ export const agentWhoToolConfig = {
 /** One directory row as a line: address, account, session, projects, channel, ticket. */
 export function whoLine(s) {
     const address = s.addresses.join(', ') || (s.role ? `${s.role} (no project)` : 'no scope');
-    const channel = s.channel.announced ? `${s.channel.announced}${s.channel.online ? ' online' : ' offline'}` : 'no channel';
+    const announced = s.channel.announced ? `${s.channel.announced}${s.channel.online ? ' online' : ' offline'}` : 'no channel';
+    const channel = s.wake === 'channel' || !s.wake ? announced : AGENT_WAKE_LABELS[s.wake];
     const ticket = s.currentTicket ? `; on ${s.currentTicket.key ?? s.currentTicket.title}` : '';
     const host = s.origin ? originText(s) : s.host ? `, host ${s.host}` : '';
     const shared = s.sharedAddresses?.length ? `; also held by another live session: ${s.sharedAddresses.join(', ')}` : '';

package/dist/tools/doc-replace-wrapper.test.js

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

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

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

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

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

package/dist/tools/session-start.js

@@ -220,7 +220,10 @@ export function makeSessionStartHandler(client, opts = {}) {
                 },
             };
         }
-        const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt } : null);
+        const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? {
+            sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt,
+            wake: r.wake, scopeExpired: r.scopeExpired ?? null, notes: Array.isArray(r.notes) ? r.notes.filter((n) => typeof n === 'string') : [],
+        } : null);
         const host = localSessionHost(extra);
         let registration = await client.post('/v1/agent/heartbeat', { ...(input.scope !== undefined ? { scope: input.scope } : {}), ...(host ? { clientInfo: { host } } : {}) }, { instanceToken })
             .then(toRegistration)
@@ -343,6 +346,8 @@ export function makeSessionStartHandler(client, opts = {}) {
             lines.push(`Address form: peers reach this session and every other ${registration.scope.role} of the project with orboto_agent_notify { to: "${roleAddresses[0]}" } (${roleAddresses.join(', ')}); address a role, never a session id copied from a log.`);
         if (registration?.scope)
             lines.push(identityLine(registration));
+        for (const note of registration?.notes ?? [])
+            lines.push(note);
         if (opts.channel)
             lines.push('', ...channelStartLines());
         if (pendingMessages.length > 0) {
@@ -377,6 +382,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                 session: {
                     ref: instanceToken, id: registration?.sessionId ?? null, scope: registration?.scope ?? null,
                     reconnects: registration?.reconnects ?? 0, reconnectedAt: registration?.lastReconnectAt ?? null,
+                    ...(registration?.wake ? { wake: registration.wake } : {}), scopeExpired: registration?.scopeExpired ?? null,
                 },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections

package/dist/version-guard.test.js

@@ -16,6 +16,8 @@ import { VERSION } from './version.js';
 const SRC = dirname(fileURLToPath(import.meta.url));
 const pkg = createRequire(import.meta.url)('../package.json');
 const ALLOWED = new Set(['version.ts']);
+/** ORB-2584 - the channel-start cut-over is a protocol version pinned to shared-schema by channel-start.test.ts, not the package version. */
+const ALLOWED_LINES = [/^export const CHANNEL_START_CUTOVER_VERSION = '\d+\.\d+\.\d+';$/];
 function walk(dir, acc = []) {
     for (const entry of readdirSync(dir)) {
         const full = join(dir, entry);
@@ -38,7 +40,7 @@ describe('ORB-1173 - version literal guard', () => {
         for (const file of walk(SRC)) {
             const text = readFileSync(file, 'utf8');
             text.split('\n').forEach((line, i) => {
-                if (semverLiteral.test(line))
+                if (semverLiteral.test(line) && !ALLOWED_LINES.some((allowed) => allowed.test(line.trim())))
                     offenders.push(`${file.replace(SRC, 'src')}:${i + 1}: ${line.trim()}`);
             });
         }

package/package.json

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