@orboto/mcp 0.226.2 → 0.228.1

package/dist/index.js

@@ -70,16 +70,27 @@ async function main() {
             const { mcpProcessInstance } = await import('./tools/shared.js');
             const instanceToken = mcpProcessInstance();
             const { declareEnvProjectScope } = await import('./project-scope.js');
-            await declareEnvProjectScope(preflightClient, instanceToken);
+            const declared = await declareEnvProjectScope(preflightClient, instanceToken);
             const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
             inbox.start();
+            if (declared?.refusal)
+                void inbox.deliverNotice('session_exists', declared.refusal);
             const outdated = cliOutdatedNotice(process.env.ORBOTO_MCP_CLI_OUTDATED);
             if (outdated)
                 void inbox.deliverNotice(CLI_OUTDATED_NOTICE, outdated);
             const { readClaudeContext, channelClientInfo } = await import('./claude-context.js');
+            const { presenceRefusal } = await import('./tools/shared.js');
+            let refusalLogged = false;
             const beat = () => {
                 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}`); });
+                    .then(() => { refusalLogged = false; })
+                    .catch((err) => {
+                    const refused = presenceRefusal(err);
+                    if (refused && refusalLogged)
+                        return;
+                    refusalLogged = Boolean(refused);
+                    console.error(`[orboto-mcp] channel heartbeat ${refused ? 'refused' : 'failed'}: ${refused?.message ?? err.message}`);
+                });
             };
             beat();
             const beats = setInterval(beat, 60_000);

package/dist/manifest-size.test.js

@@ -62,6 +62,9 @@ afterEach(() => { vi.restoreAllMocks(); });
  * 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).
+ * ORB-2579 added the four rule proposal tools to the full tier after
+ * tightening repeated parameter descriptions (doc ids, bulk selectors,
+ * work-session leases, primer facts) by 3.0k (full = 169,607).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/project-scope.js

@@ -43,7 +43,21 @@ export async function declareEnvProjectScope(client, instanceToken, raw = proces
     const current = await client.get('/v1/agent/session', { instanceToken }).catch(() => null);
     if (current && scopeDeclared(current.scope))
         return current;
-    const row = await client.post('/v1/agent/heartbeat', { scope, scopeDefault: true }, { instanceToken }).catch(() => null);
+    const declaration = { scope, scopeDefault: true, start: true };
+    const row = await client.post('/v1/agent/heartbeat', declaration, { instanceToken })
+        .catch(async (err) => {
+        const { exitedPredecessor, presenceRefusal } = await import('./tools/shared.js');
+        const { machineId, shortHost } = await import('./session-origin.js');
+        const refused = presenceRefusal(err);
+        const dead = exitedPredecessor(refused, { machine: machineId(), host: shortHost() });
+        if (dead) {
+            const again = await client.post('/v1/agent/heartbeat', { ...declaration, previous: 'end' }, { instanceToken }).catch(() => null);
+            if (again)
+                console.error(`[orboto-mcp] ${dead.line}`);
+            return again;
+        }
+        return refused ? { refusal: refused.message } : null;
+    });
     if (row && typeof row.sessionId === 'string')
         rememberDeclaredScope(instanceToken, row.scope ?? scope);
     return row;

package/dist/project-scope.test.js

@@ -18,7 +18,7 @@ function fakeClient(row) {
         },
     };
 }
-beforeEach(() => { _forgetDeclaredScopes(); });
+beforeEach(() => { _forgetDeclaredScopes(); vi.stubEnv(PROJECT_KEY_ENV, ''); vi.stubEnv(SESSION_ROLE_ENV, ''); });
 afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
 describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
     it('names the same variable the CLI writes into the entry and hands to the session', () => {
@@ -41,7 +41,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         await declareEnvProjectScope(client, 'agent-abc', 'ACME');
         expect(client.calls).toEqual([
             { method: 'GET', path: '/v1/agent/session', instanceToken: 'agent-abc' },
-            { method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }, instanceToken: 'agent-abc' },
+            { method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }, instanceToken: 'agent-abc' },
         ]);
         expect(rememberedScope('agent-abc')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
     });
@@ -58,7 +58,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         expect(await declareEnvProjectScope(none, 'agent-none', '')).toBeNull();
         expect(none.calls).toEqual([]);
     });
-    it('orboto_session_start without a scope declares the environment project on a row that has none', async () => {
+    it('orboto_session_start without a scope sends the environment project as fallbackScope and declares it itself on an instance that ignores it', async () => {
         vi.stubEnv(PROJECT_KEY_ENV, 'acme');
         const beats = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
@@ -79,7 +79,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         });
         const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'k' });
         const res = await makeSessionStartHandler(client)({}, { sessionId: 'scope1' });
-        expect(beats).toEqual([{}, { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }]);
+        expect(beats).toEqual([{ start: true, fallbackScope: { role: 'worker', projectKeys: ['ACME'] } }, { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }]);
         expect(res.content[0].text).toContain('projects ACME');
         expect(rememberedScope('mcp-scope1')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
     });
@@ -99,10 +99,10 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
         expect(envProjectScope(undefined, 'lead')).toBeNull();
         const client = fakeClient({ sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null });
         await declareEnvProjectScope(client, 'agent-control', undefined, 'coordinator');
-        expect(client.calls[1]).toEqual({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'coordinator' }, scopeDefault: true }, instanceToken: 'agent-control' });
+        expect(client.calls[1]).toEqual({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'coordinator' }, scopeDefault: true, start: true }, instanceToken: 'agent-control' });
         expect(rememberedScope('agent-control')).toEqual({ role: 'coordinator' });
     });
-    it('orboto_session_start without a scope declares the control session the environment names', async () => {
+    it('orboto_session_start without a scope sends the control session the environment names as fallbackScope in its one start beat', async () => {
         vi.stubEnv(SESSION_ROLE_ENV, 'coordinator');
         vi.stubEnv(PROJECT_KEY_ENV, 'ACME');
         const beats = [];
@@ -112,7 +112,7 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
             if (u.pathname === '/v1/agent/heartbeat') {
                 const sent = init?.body ? JSON.parse(init.body) : {};
                 beats.push(sent);
-                body = { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: sent.scope ?? null };
+                body = { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: sent.scope ?? sent.fallbackScope ?? null };
             }
             else if (u.pathname === '/v1/agent/session') {
                 body = { sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null };
@@ -124,7 +124,7 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
         });
         const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'k' });
         await makeSessionStartHandler(client)({}, { sessionId: 'control1' });
-        expect(beats).toEqual([{}, { scope: { role: 'coordinator' }, scopeDefault: true }]);
+        expect(beats).toEqual([{ start: true, fallbackScope: { role: 'coordinator' } }]);
         expect(rememberedScope('mcp-control1')).toEqual({ role: 'coordinator' });
     });
 });
@@ -145,6 +145,6 @@ describe('ORB-2593 - a picker-pending orboto claude start', () => {
         writeFileSync(join(dir, 'state.json'), JSON.stringify({ pid: 4000 }));
         const resolved = fakeClient({ sessionId: 'x', scope: null });
         await declareEnvProjectScope(resolved, 'agent-abc', 'ACME', undefined, supervisorScopePending(env));
-        expect(resolved.calls.filter((c) => c.method === 'POST')).toEqual([{ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }, instanceToken: 'agent-abc' }]);
+        expect(resolved.calls.filter((c) => c.method === 'POST')).toEqual([{ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }, instanceToken: 'agent-abc' }]);
     });
 });

package/dist/response-budget.js

@@ -239,7 +239,7 @@ export const TruncationBlockSchema = z.object({
  */
 export const TruncationBlockAdvertisedSchema = z.object({ handle: z.string() })
     .passthrough()
-    .describe('Response cut; pass `handle` to orboto_response_expand.');
+    .describe('Cut: pass handle to orboto_response_expand.');
 function stringMarker(omitted, handle, path) {
     return `... [truncated ${omitted} chars - full value: orboto_response_expand handle="${handle}" path="${path}"]`;
 }

package/dist/server.js

@@ -24,6 +24,7 @@ import { helpToolConfig, makeHelpHandler } from './tools/help.js';
 import { apiSearchToolConfig, makeApiSearchHandler } from './tools/api-search.js';
 import { apiCallToolConfig, makeApiCallHandler } from './tools/api-call.js';
 import { listAgentInstructionsToolConfig, makeListAgentInstructionsHandler, createAgentInstructionToolConfig, makeCreateAgentInstructionHandler, updateAgentInstructionToolConfig, makeUpdateAgentInstructionHandler, resetAgentInstructionToolConfig, makeResetAgentInstructionHandler, deleteAgentInstructionToolConfig, makeDeleteAgentInstructionHandler, } from './tools/agent-instructions.js';
+import { ruleProposeToolConfig, makeRuleProposeHandler, ruleProposalsToolConfig, makeRuleProposalsHandler, ruleProposalAcceptToolConfig, makeRuleProposalAcceptHandler, ruleProposalRejectToolConfig, makeRuleProposalRejectHandler, } from './tools/rule-proposals.js';
 import { agentHeartbeatToolConfig, makeAgentHeartbeatHandler, agentPresenceToolConfig, makeAgentPresenceHandler, agentNotifyToolConfig, makeAgentNotifyHandler, } from './tools/agent-coordination.js';
 import { agentBroadcastToolConfig, makeAgentBroadcastHandler, } from './tools/agent-coordination.js';
 import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './tools/agent-message-work.js';
@@ -200,6 +201,10 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_update_agent_instruction', updateAgentInstructionToolConfig, makeUpdateAgentInstructionHandler(client));
     reg('orboto_reset_agent_instruction', resetAgentInstructionToolConfig, makeResetAgentInstructionHandler(client));
     reg('orboto_delete_agent_instruction', deleteAgentInstructionToolConfig, makeDeleteAgentInstructionHandler(client));
+    reg('orboto_rule_propose', ruleProposeToolConfig, makeRuleProposeHandler(client));
+    reg('orboto_rule_proposals', ruleProposalsToolConfig, makeRuleProposalsHandler(client));
+    reg('orboto_rule_proposal_accept', ruleProposalAcceptToolConfig, makeRuleProposalAcceptHandler(client));
+    reg('orboto_rule_proposal_reject', ruleProposalRejectToolConfig, makeRuleProposalRejectHandler(client));
     reg('orboto_agent_heartbeat', agentHeartbeatToolConfig, makeAgentHeartbeatHandler(client));
     reg('orboto_agent_presence', agentPresenceToolConfig, makeAgentPresenceHandler(client));
     reg('orboto_who', agentWhoToolConfig, makeAgentWhoHandler(client));

package/dist/session-origin.js

@@ -6,12 +6,12 @@
  */
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 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'], ['model', 'model'],
+    ['host', 'host'], ['machine', 'machineId'], ['repo', 'repo'], ['pid', 'pid'], ['start', 'startedAt'], ['client', 'client'], ['version', 'clientVersion'], ['harness', 'harness'], ['model', 'model'], ['checkout', 'checkout'],
 ];
 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. */
@@ -55,6 +55,26 @@ export function repoBasename(cwd = process.cwd()) {
     }
     return basename(cwd) || null;
 }
+/** ORB-2553 - the hashed working tree the directory sits in (a linked worktree is its own), the same value the CLI sends; never a path. */
+export function checkoutHash(cwd = process.cwd()) {
+    let root = cwd;
+    for (let dir = cwd, i = 0; i < 40; i += 1) {
+        if (existsSync(join(dir, '.git'))) {
+            root = dir;
+            break;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    let physical = root;
+    try {
+        physical = realpathSync(root);
+    }
+    catch { /* an unreadable path hashes as given */ }
+    return createHash('sha256').update(physical).digest('hex').slice(0, 16);
+}
 let machine;
 /** A hashed stable machine id (the platform UUID on macOS, /etc/machine-id elsewhere); null when none is readable. */
 export function machineId(read = readMachineId) {
@@ -87,7 +107,7 @@ export function stdioOrigin(env = process.env) {
         return params.toString();
     }
     return formatOrigin({
-        host: shortHost(), machineId: machineId(), repo: repoBasename(), pid: process.ppid || null,
+        host: shortHost(), machineId: machineId(), repo: repoBasename(), checkout: checkoutHash(), pid: process.ppid || null,
         client: 'orboto-mcp', clientVersion: VERSION,
         harness: stdioHarness(env),
         model: /^[\x21-\x7e]{1,80}$/.test((env.ORBOTO_MODEL ?? '').trim()) ? env.ORBOTO_MODEL.trim() : null,

package/dist/tools/agent-coordination.js

@@ -4,10 +4,11 @@
  * @see ORB-704, ORB-706
  */
 import { z } from 'zod';
-import { AGENT_WAKE_LABELS, AgentInventoryEntrySchema, AgentInventoryKindSchema } from './agent-presence-schema.js';
+import { AGENT_WAKE_LABELS, AgentInventoryKindSchema, AgentSessionWakeSchema, } from './agent-presence-schema.js';
+import { AgentPresenceRowSchema } from './agent-presence-row.js';
 import { OrbotoApiError } from '../orboto-client.js';
-import { mcpInstanceToken } from './shared.js';
-import { AgentSessionScopeSchema } from './agent-session-scope.js';
+import { mcpInstanceToken, presenceRefusal } from './shared.js';
+import { AgentSessionRoleSchema, AgentSessionScopeSchema } from './agent-session-scope.js';
 export const agentHeartbeatToolConfig = {
     title: 'Agent heartbeat (Multi-Agent Coordination)',
     description: 'Register or refresh this agent\'s presence with status detail. A live connection already counts as online (an open MCP event stream, `orboto messages --follow`, the agent WebSocket) - the heartbeat adds status: idle (default) | working (+workingOnTicketId) | blocked, capabilities (free-form strings for operator filters) and clientInfo.name (the runtime), and is the only presence path for turn-based clients without a standing connection. Rows older than 90 s count as offline; persist the returned sessionToken and send it on later heartbeats. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility (ORB-2136); an empty object clears it. `startedBy`: starter session id, same account.',
@@ -35,7 +36,16 @@ export const agentHeartbeatToolConfig = {
 };
 export function makeAgentHeartbeatHandler(client) {
     return async (args, extra) => {
-        const res = await client.post('/v1/agent/heartbeat', args, { instanceToken: mcpInstanceToken(undefined, extra) });
+        let res;
+        try {
+            res = await client.post('/v1/agent/heartbeat', args, { instanceToken: mcpInstanceToken(undefined, extra) });
+        }
+        catch (err) {
+            const refused = presenceRefusal(err);
+            if (!refused)
+                throw err;
+            return { content: [{ type: 'text', text: `heartbeat refused (ORB-2553) - ${refused.message}` }], isError: true };
+        }
         const scope = res.scope ? ` scope=${JSON.stringify(res.scope)}` : '';
         const notes = (res.notes ?? []).map((n) => `\n${n}`).join('');
         return {
@@ -54,45 +64,99 @@ export function originText(s) {
     const where = [o.host ?? 'unknown host', o.repo, o.pid ? `pid ${o.pid}` : null, o.harness, o.client ? `${o.client}${o.clientVersion ? ` ${o.clientVersion}` : ''}` : null].filter(Boolean).join(' ');
     return ` [${s.state ?? 'live'}] on ${where}${o.startedAt ? ` since ${o.startedAt}` : ''}`;
 }
+/** ORB-2548 - the page an MCP presence read returns by default, sized so four rows fit the 4,000-character budget. */
+export const PRESENCE_PAGE_LIMIT = 4;
+export const PresenceFilterShape = {
+    role: AgentSessionRoleSchema.optional(),
+    state: z.enum(['live', 'quiet', 'orphaned', 'unknown_origin']).optional(),
+    email: z.string().min(3).max(320).optional(),
+    sessionId: z.string().min(8).max(36).optional(),
+    kind: AgentInventoryKindSchema.optional(),
+    wake: AgentSessionWakeSchema.optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().max(500).optional(),
+};
+export function presenceQuery(args, extra = {}) {
+    const qs = new URLSearchParams(extra);
+    for (const key of ['project', 'role', 'state', 'email', 'sessionId', 'kind', 'wake', 'cursor', 'for']) {
+        const value = args[key]?.trim();
+        if (value)
+            qs.set(key, value);
+    }
+    qs.set('limit', String(args.limit ?? PRESENCE_PAGE_LIMIT));
+    return qs.toString();
+}
+/** ORB-2548 - the answer for a project filter the API does not know or the caller may not see (its 404). */
+export function unknownProjectText(key) {
+    return `Project "${key.trim().toUpperCase()}" is unknown or not visible to you - no session is listed for it.`;
+}
+/** Runs the presence read; a 404 for a project filter becomes null, so the tool answers unknownProjectText instead of a raw error. */
+export async function readPresence(client, path, project) {
+    try {
+        return await client.get(path);
+    }
+    catch (err) {
+        if (project?.trim() && err instanceof OrbotoApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+/** The line that ends a page with more rows behind it. */
+export function nextPageLine(nextCursor) {
+    return nextCursor ? [`More sessions: call again with cursor "${nextCursor}", or narrow with email, sessionId, project, role, kind, wake or state.`] : [];
+}
+function presenceRow(s) {
+    const o = s.origin;
+    return {
+        sessionId: s.sessionId, userEmail: s.userEmail, userFullName: s.userFullName, kind: s.kind,
+        owner: s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : null),
+        status: s.status, lane: s.lane?.name ?? null, scope: s.scope ?? null, memberProjects: s.projects.length,
+        connections: [...new Set(s.connections.map((c) => c.type))], ...(s.wake ? { wake: s.wake } : {}), ...(s.state ? { state: s.state } : {}),
+        origin: o ? { host: o.host, repo: o.repo, pid: o.pid, harness: o.harness, client: o.client } : null,
+        workingOn: s.workingOnTicket ? s.workingOnTicket.key ?? s.workingOnTicket.id : null,
+        lastSeenAt: String(s.lastSeenAt), ...(s.redacted ? { redacted: true } : {}),
+    };
+}
+function presenceLine(s) {
+    const name = s.userFullName ?? s.userEmail;
+    const runtime = s.clientInfo.name ?? 'unknown';
+    const work = s.workingOnTicket ? ` · working on [${s.workingOnTicket.projectKey ?? '?'}] ${s.workingOnTicket.key ?? s.workingOnTicket.id} (${s.workingOnTicket.title})` : '';
+    const owner = s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self');
+    const declared = s.scope?.projectKeys ?? [];
+    const scope = s.scope?.role || declared.length ? `; scope: ${s.scope?.role ?? 'no role'}${declared.length ? ` on ${declared.join(', ')}` : ''}` : '';
+    const keys = s.projects.map((p) => p.key);
+    const projects = keys.length === 0 ? '' : keys.length <= 8 ? `; projects: ${keys.join(', ')}` : `; member of ${keys.length} projects`;
+    const connections = s.connections.length ? `; connections: ${[...new Set(s.connections.map((c) => c.type))].join(', ')}` : '';
+    return `- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${originText(s)}${work}; owner: ${owner}${s.lane ? `; lane: ${s.lane.name}` : ''}${scope}${projects}${connections}${s.wake ? `; ${AGENT_WAKE_LABELS[s.wake]}` : ''}`;
+}
 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; 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`).',
+    description: 'Active agent instances. The orboto_who set from GET /v1/agent/who?include=inventory: lane workers and reviewers, inbox, MCP and runner connections. Each row: sessionId, account, kind (agent | human by credential), owner or acts-as, status, lane, declared scope, member project count, connection types, wake (on_call: nothing wakes it), state (live | quiet | orphaned | unknown_origin), origin (host, repo, pid, harness, client), current ticket. Filters run on the server: email, sessionId (id or 8+ character prefix), projectKey (sessions declared on it), role, kind, wake, state; 4 rows a page, nextCursor continues (cursor). A projectKey that is unknown or not visible to you answers so in one line, with no rows. Operators (admin:agents:read or admin:system:read) see the workspace, others their own sessions and those on their projects, a foreign row redacted. The full inventory row: `orboto agents --json`.',
     inputSchema: z.object({
-        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).'),
+        projectKey: z.string().min(1).max(64).optional(),
+        ...PresenceFilterShape,
     }).shape,
     outputSchema: z.object({
-        sessions: z.array(AgentInventoryEntrySchema),
+        sessions: z.array(AgentPresenceRowSchema),
+        nextCursor: z.string().nullable(),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
-/** Client-side view filter (ORB-2135); the inventory route stays unfiltered and the chat mirror applies the same rule. */
-export function filterPresenceRows(rows, args) {
-    const key = args.projectKey?.trim().toUpperCase();
-    return rows.filter((row) => (!args.kind || row.kind === args.kind) && (!key || row.projects.some((p) => p.key.toUpperCase() === key)));
-}
 export function makeAgentPresenceHandler(client) {
     return async (args = {}) => {
-        const all = (await client.get('/v1/agent/who?include=inventory')).inventory ?? [];
-        const sessions = filterPresenceRows(all, args);
-        const lines = [];
-        if (sessions.length === 0) {
-            lines.push(all.length === 0 ? 'No active agent sessions in the workspace.' : `No active agent sessions match the filter (${all.length} active in the workspace).`);
-        }
-        else {
-            lines.push(`${sessions.length} active session(s):`);
-            for (const s of sessions) {
-                const name = s.userFullName ?? s.userEmail;
-                const runtime = s.clientInfo.name ?? 'unknown';
-                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(', ')}` : ''}${s.wake ? `; ${AGENT_WAKE_LABELS[s.wake]}` : ''}`);
-            }
-        }
+        const { projectKey, ...filters } = args;
+        const project = projectKey ?? filters.project;
+        const res = await readPresence(client, `/v1/agent/who?${presenceQuery({ ...filters, project }, { include: 'inventory' })}`, project);
+        if (!res)
+            return { content: [{ type: 'text', text: unknownProjectText(project) }], structuredContent: { sessions: [], nextCursor: null } };
+        const rows = res.inventory ?? [];
+        const filtered = Object.entries(args).some(([key, value]) => key !== 'limit' && key !== 'cursor' && value !== undefined && value !== '');
+        const lines = rows.length === 0
+            ? [filtered ? 'No active agent session matches the filter.' : 'No active agent sessions in the workspace.']
+            : [`${rows.length} active session(s)${res.nextCursor ? ' on this page' : ''}:`, ...rows.map(presenceLine), ...nextPageLine(res.nextCursor)];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { sessions },
+            structuredContent: { sessions: rows.map(presenceRow), nextCursor: res.nextCursor ?? null },
         };
     };
 }
@@ -121,7 +185,7 @@ export function noRecipientText(err) {
         return null;
     const p = body.errorParams ?? {};
     const live = (p.liveSessions ?? []).map((s) => `${s.addresses[0] ?? s.email} (${s.email}, ${s.shortId})`);
-    const ways = 'a role address in `to` (integrator@KEY), `toSessionRef` with an instance short id, or `queue: true` with `project` to keep it until a session declares the project';
+    const ways = 'a role address in `to` (integrator@KEY), `toSessionRef` with an instance short id, or `queue: true` with `project` (a role address needs no project) to keep it until a session declares the project or the role';
     if (p.reason === 'ambiguous_account') {
         return `not sent: ${p.address ?? 'that account'} has ${live.length} live sessions you may address and a request needs one of them. Sessions: ${live.join('; ')}. Send again with \`toSessionRef\` set to the instance short id of one, or address a role (${ways}).`;
     }
@@ -163,7 +227,7 @@ export function reminderTooSoonText(err) {
 }
 export const agentNotifyToolConfig = {
     title: 'Notify an agent or user',
-    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). outcome: one sentence, 10 to 1000 characters; body: the plain text of the message (any length, lands in payload.body; payload may carry other JSON); threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it. A request to an account email without project or toSessionRef goes to its one live session, with several it is refused listing them (pick one with toSessionRef). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session. An identical send (same recipient, project, kind, subject, payload; no threadId, no attachments) within the dedupe window (default 24 h) is not delivered again: the text says so and names the existing message. remind: true is a deliberate reminder of it (notifies again, at most one per 15 min, faster is refused with retryAfter); urgent: true is never suppressed and counts as a reminder. Loops and retries never set remind or urgent.',
+    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). outcome: one sentence, 10 to 1000 characters; body: the plain text of the message (any length, lands in payload.body; payload may carry other JSON); threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; alone (no to, no targetEmail) a session id or short id addresses that session; project scopes an account message to sessions declared on it. A request to an account email without project or toSessionRef goes to its one live session, with several it is refused listing them (pick one with toSessionRef). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project; queued to a role address (worker@KEY) it waits for the first session that declares that role, and a queued request to an account address on the project of the owner address goes to the owner role. 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(),
@@ -235,8 +299,8 @@ export function notifyExample(kind, to) {
 export function notifyDefinitionError(args) {
     const kind = args.kind ?? 'info';
     const example = (text) => `Invalid arguments: ${text} Example: ${notifyExample(kind, args.to)}`;
-    if (!args.to && !args.targetEmail)
-        return example('name a recipient - `to` (integrator@KEY, an email or a session id) or `targetEmail`.');
+    if (!args.to && !args.targetEmail && !args.toSessionRef?.trim())
+        return example('name a recipient - `to` (integrator@KEY, an email or a session id), `targetEmail`, or `toSessionRef` (a session id or its short id).');
     const outcome = args.outcome?.trim() ?? '';
     if ((kind === 'request' || kind === 'complete') && !outcome) {
         return example(`\`outcome\` is required for a ${kind} - the outcome sentence (what must be true when it is done, or what was delivered), ${NOTIFY_OUTCOME_MIN} to ${NOTIFY_OUTCOME_MAX} characters.`);
@@ -275,7 +339,8 @@ export function makeAgentNotifyHandler(client) {
         }
         const who = res.ownerHint?.routed ? res.ownerHint.ownerAddress : args.to ?? args.targetEmail ?? '?';
         const recipients = (res.recipients ?? []).map((r) => r.label);
-        const target = recipients.length > 1 ? recipients.join(', ') : res.toSessionId ? `${who} session ${res.toSessionId.slice(0, 8)}` : who;
+        const sessionOnly = !res.ownerHint?.routed && !args.to && !args.targetEmail;
+        const target = recipients.length > 1 ? recipients.join(', ') : res.toSessionId ? `${sessionOnly ? '' : `${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) {

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

@@ -82,7 +82,7 @@ describe('orboto_agent_presence', () => {
         expect(text).toContain('2 active session(s)');
         expect(text).toContain('Alice <alice@x.test> (claude-code, instance 00000000-0000-0000-0000-000000000010) - working · working on [ORB] ORB-42');
         expect(text).toContain('bot@x.test <bot@x.test> (dispatcher-daemon, instance 00000000-0000-0000-0000-000000000011) - idle [orphaned] on build-host sample-repo pid 4242 claude-code orboto-cli 1.2.3; owner: Alice');
-        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory');
+        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory&limit=4');
         expect(result.structuredContent.sessions).toHaveLength(2);
     });
     it('handles an empty workspace gracefully', async () => {
@@ -96,32 +96,56 @@ describe('orboto_agent_presence', () => {
         { userId: '00000000-0000-0000-0000-000000000002', userEmail: 'worker@x.test', userFullName: null, kind: 'agent', isBot: true, actsAs: null, owner: { id: '00000000-0000-0000-0000-000000000001', name: 'Alice', email: 'alice@x.test' }, autonomyPaused: false, lane: { id: '00000000-0000-0000-0000-000000000040', name: 'worker-1', role: 'implementation', paused: false }, projects: [{ id: '00000000-0000-0000-0000-000000000031', key: 'ACME', name: 'Acme' }, { id: '00000000-0000-0000-0000-000000000030', key: 'ORB', name: 'orboto' }], connections: [{ type: 'lane', label: 'worker-1' }, { type: 'live_events', label: 'MCP live events' }], workSessions: [], sessionId: '00000000-0000-0000-0000-000000000011', status: 'idle', workingOnTicket: null, capabilities: [], clientInfo: { name: 'pi' }, lastSeenAt: new Date().toISOString(), createdAt: new Date().toISOString() },
         { userId: '00000000-0000-0000-0000-000000000001', userEmail: 'alice@x.test', userFullName: 'Alice', kind: 'agent', isBot: true, actsAs: { id: '00000000-0000-0000-0000-000000000001', name: 'Alice', email: 'alice@x.test' }, owner: null, autonomyPaused: false, lane: null, projects: [], connections: [{ type: 'oauth', label: 'claude.ai' }], workSessions: [], sessionId: '00000000-0000-0000-0000-000000000012', status: 'idle', workingOnTicket: null, capabilities: [], clientInfo: {}, lastSeenAt: new Date().toISOString(), createdAt: new Date().toISOString() },
     ];
-    it('filters by projectKey (case-insensitive, projects only) and kind on the client side (ORB-2135)', async () => {
+    it('ORB-2548: sends every filter to the one presence read, projectKey as project, four rows a page by default', async () => {
         const handler = makeAgentPresenceHandler(client);
-        const ids = async (args) => {
-            stub([{ json: { sessions: [], inventory: presenceRows() } }]);
-            const result = await handler(args);
-            expect(vi.mocked(fetch).mock.calls.at(-1)?.[0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory');
-            return result.structuredContent.sessions.map((s) => s.sessionId.slice(-2));
+        const url = async (args) => {
+            stub([{ json: { sessions: [], inventory: [] } }]);
+            await handler(args);
+            return String(vi.mocked(fetch).mock.calls.at(-1)?.[0]);
         };
-        expect(await ids({})).toEqual(['10', '11', '12']);
-        expect(await ids({ kind: 'agent' })).toEqual(['11', '12']);
-        expect(await ids({ kind: 'human' })).toEqual(['10']);
-        expect(await ids({ projectKey: 'acme' })).toEqual(['11']);
-        expect(await ids({ projectKey: 'ORB', kind: 'human' })).toEqual(['10']);
-        expect(await ids({ projectKey: 'NONE' })).toEqual([]);
-    });
-    it('says when a filter matched nothing but the workspace is not empty', async () => {
-        stub([{ json: { sessions: [], inventory: presenceRows() } }]);
+        expect(await url({})).toBe('https://orboto.example.com/v1/agent/who?include=inventory&limit=4');
+        expect(await url({ projectKey: 'acme', kind: 'agent' })).toBe('https://orboto.example.com/v1/agent/who?include=inventory&project=acme&kind=agent&limit=4');
+        expect(await url({ email: 'w@x.test', sessionId: 'c785946f', role: 'worker', wake: 'on_call', state: 'live', limit: 2, cursor: 'next-1' }))
+            .toBe('https://orboto.example.com/v1/agent/who?include=inventory&role=worker&state=live&email=w%40x.test&sessionId=c785946f&wake=on_call&cursor=next-1&limit=2');
+    });
+    it('ORB-2548: a projectKey that is unknown or not visible answers in one line instead of a raw 404', async () => {
+        stub([{ ok: false, status: 404, json: { errorKey: 'errors.agents.message_project_not_found' } }]);
+        const result = await makeAgentPresenceHandler(client)({ projectKey: 'nope' });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toBe('Project "NOPE" is unknown or not visible to you - no session is listed for it.');
+        expect(result.structuredContent).toEqual({ sessions: [], nextCursor: null });
+        stub([{ ok: false, status: 404, json: {} }]);
+        await expect(makeAgentPresenceHandler(client)({ email: 'x@y.test' })).rejects.toThrow();
+    });
+    it('says when a filter matched nothing', async () => {
+        stub([{ json: { sessions: [], inventory: [] } }]);
         const result = await makeAgentPresenceHandler(client)({ projectKey: 'NONE' });
-        expect(result.content[0].text).toBe('No active agent sessions match the filter (3 active in the workspace).');
+        expect(result.content[0].text).toBe('No active agent session matches the filter.');
     });
-    it('renders acts-as, lane, projects and connection types on each line', async () => {
-        stub([{ json: { sessions: [], inventory: presenceRows() } }]);
-        const text = (await makeAgentPresenceHandler(client)({ kind: 'agent' })).content[0].text;
-        expect(text).toContain('2 active session(s)');
-        expect(text).toContain('owner: Alice; lane: worker-1; projects: ACME, ORB; connections: lane, live_events');
+    it('renders acts-as, lane, scope, projects and connection types on each line and returns the compact row', async () => {
+        const rows = presenceRows().filter((row) => row.kind === 'agent').map((row, i) => (i === 0 ? { ...row, scope: { role: 'worker', projectKeys: ['ACME'] }, wake: 'channel' } : row));
+        stub([{ json: { sessions: [], inventory: rows, nextCursor: 'cursor-2' } }]);
+        const result = await makeAgentPresenceHandler(client)({ kind: 'agent' });
+        const text = result.content[0].text;
+        expect(text).toContain('2 active session(s) on this page');
+        expect(text).toContain('owner: Alice; lane: worker-1; scope: worker on ACME; projects: ACME, ORB; connections: lane, live_events; reachable by channel');
         expect(text).toContain('owner: acts as Alice; connections: oauth');
+        expect(text).toContain('More sessions: call again with cursor "cursor-2"');
+        const structured = result.structuredContent;
+        expect(structured.nextCursor).toBe('cursor-2');
+        expect(structured.sessions[0]).toEqual({
+            sessionId: '00000000-0000-0000-0000-000000000011', userEmail: 'worker@x.test', userFullName: null, kind: 'agent', owner: 'Alice',
+            status: 'idle', lane: 'worker-1', scope: { role: 'worker', projectKeys: ['ACME'] }, memberProjects: 2, connections: ['lane', 'live_events'],
+            wake: 'channel', origin: null, workingOn: null, lastSeenAt: rows[0].lastSeenAt,
+        });
+        expect(structured.sessions[1]).toMatchObject({ owner: 'acts as Alice', memberProjects: 0, connections: ['oauth'] });
+    });
+    it('names the member count instead of listing more than eight projects', async () => {
+        const many = Array.from({ length: 99 }, (_, i) => ({ id: '00000000-0000-0000-0000-000000000030', key: `P${i}`, name: `Project ${i}` }));
+        stub([{ json: { sessions: [], inventory: [{ ...presenceRows()[1], projects: many }] } }]);
+        const text = (await makeAgentPresenceHandler(client)({})).content[0].text;
+        expect(text).toContain('; member of 99 projects;');
+        expect(text).not.toContain('P98');
     });
 });
 describe('orboto_agent_notify', () => {
@@ -263,6 +287,22 @@ describe('ORB-2136 - session addressing', () => {
         expect(result.content[0].text).toContain('bob@example.com session cbb52195');
         expect(result.structuredContent).toMatchObject({ toSessionId: 'cbb52195-0000-4000-8000-000000000000' });
     });
+    it('ORB-2548: toSessionRef alone is a recipient - sent without to or targetEmail, the answer names the session', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push(JSON.parse(init?.body ?? '{}'));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({ ok: true, messageId: '00000000-0000-4000-8000-000000000000', toSessionId: 'cbb52195-0000-4000-8000-000000000000', routedTo: 'session' }), text: async () => '' };
+        });
+        const result = await makeAgentNotifyHandler(client)({ subject: 'hi', toSessionRef: 'cbb52195' }, { sessionId: 'abc123' });
+        expect(result.isError).toBeUndefined();
+        expect(seen[0]).toMatchObject({ toSessionRef: 'cbb52195', subject: 'hi' });
+        expect(seen[0]).not.toHaveProperty('to');
+        expect(result.content[0].text).toContain('notified session cbb52195 (message');
+        vi.restoreAllMocks();
+        const none = await makeAgentNotifyHandler(client)({ subject: 'hi' });
+        expect(none.isError).toBe(true);
+        expect(none.content[0].text).toContain('`toSessionRef` (a session id or its short id)');
+    });
     it('orboto_messages identifies this session on the fetch and renders sender and receiver identities', async () => {
         const seen = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {

package/dist/tools/agent-instructions.js

@@ -6,6 +6,7 @@
  */
 import { z } from 'zod';
 import { sizeBlockResult } from './shared.js';
+const AGENTS_PROPOSE = ' Agents propose shared rules with orboto_rule_propose (403 errors.agent_rules.write_needs_person).';
 const RULE_WRITING_CONTRACT = ' Rule: title = one imperative sentence; body <= 400 chars, Rule / Why / How, no long examples, nothing another block says.';
 function excerptOf(body) {
     const firstLine = body.split('\n', 1)[0] ?? '';
@@ -74,7 +75,7 @@ export function makeListAgentInstructionsHandler(client) {
 export const createAgentInstructionToolConfig = {
     title: 'Add a custom coding-agent rule block',
     description: 'Create a custom rule block at a scope (workspace, customer, project or personal). Workspace reaches every agent (admin:ai:write), customer every project of one customer (customer:write), project one project (project:edit), personal only you. For scope=customer pass customerId; for scope=project pass projectId.'
-        + RULE_WRITING_CONTRACT,
+        + AGENTS_PROPOSE + RULE_WRITING_CONTRACT,
     inputSchema: z.object({
         title: z.string().min(1).max(120),
         body: z.string().min(1).max(8000).describe('The rule text the agent should follow.'),
@@ -109,7 +110,7 @@ export function makeCreateAgentInstructionHandler(client) {
 export const updateAgentInstructionToolConfig = {
     title: 'Edit / toggle / reorder a coding-agent rule block',
     description: 'Patch a rule block: title, body, enabled (toggle a rule on/off), or sortOrder. Works on default AND custom blocks (defaults keep their builtinKey and can be reset later). Needs admin:ai:write.'
-        + RULE_WRITING_CONTRACT,
+        + AGENTS_PROPOSE + RULE_WRITING_CONTRACT,
     inputSchema: z.object({
         id: z.string().uuid(),
         title: z.string().min(1).max(120).optional(),
@@ -141,7 +142,7 @@ export function makeUpdateAgentInstructionHandler(client) {
 }
 export const resetAgentInstructionToolConfig = {
     title: 'Reset a default rule block to its shipped text',
-    description: 'Restore a seeded DEFAULT rule block (one with a builtinKey) to the text orboto ships. No-op for custom blocks. Needs admin:ai:write.',
+    description: 'Restore a seeded DEFAULT rule block (one with a builtinKey) to the text orboto ships. No-op for custom blocks. Needs admin:ai:write.' + AGENTS_PROPOSE,
     inputSchema: z.object({ id: z.string().uuid() }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
@@ -153,7 +154,7 @@ export function makeResetAgentInstructionHandler(client) {
 }
 export const deleteAgentInstructionToolConfig = {
     title: 'Delete a custom coding-agent rule block',
-    description: 'Delete a CUSTOM rule block. Default (builtin) blocks cannot be deleted - disable them via update instead. Needs admin:ai:write.',
+    description: 'Delete a CUSTOM rule block. Default (builtin) blocks cannot be deleted - disable them via update instead. Needs admin:ai:write.' + AGENTS_PROPOSE,
     inputSchema: z.object({ id: z.string().uuid() }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };