@orboto/mcp 0.195.1 → 0.197.0

package/dist/event-bridge.js

@@ -67,6 +67,10 @@ export class EventBridge {
         }
         catch { /* ignore */ } });
     }
+    /** ORB-2132 - pin the instance token once the transport session id is known; applies to the next (re)connect. */
+    setInstanceToken(token) {
+        this.opts = { ...this.opts, instanceToken: token };
+    }
     /** Open the SSE stream and start forwarding. Resolves immediately;
      *  the actual forwarding happens on the returned background loop. */
     start() {
@@ -114,6 +118,7 @@ export class EventBridge {
             headers: {
                 Authorization: `Bearer ${bearer}`,
                 Accept: 'text/event-stream',
+                ...(this.opts.instanceToken ? { 'x-orboto-agent-session': this.opts.instanceToken } : {}),
             },
             signal: this.abort.signal,
         });

package/dist/event-bridge.test.js

@@ -144,3 +144,37 @@ describe('EventBridge.dispatch', () => {
         expect(mcp.sendResourceUpdated).toHaveBeenCalledTimes(2);
     });
 });
+describe('ORB-2132 - the bridge identifies its tool session', () => {
+    async function connectOnce(opts) {
+        const fetchFn = vi.fn().mockResolvedValue(mockSseResponse([]));
+        const bridge = new EventBridge({
+            baseUrl: 'https://orboto.example.com',
+            apiKey: 'orb_x',
+            ...(opts.instanceToken ? { instanceToken: opts.instanceToken } : {}),
+            mcp: mockMcp(),
+            subscriptions: new Set(),
+            fetchFn: fetchFn,
+            log: () => { },
+        });
+        if (opts.pin)
+            bridge.setInstanceToken(opts.pin);
+        bridge.start();
+        await new Promise((r) => setTimeout(r, 30));
+        bridge.close();
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchFn.mock.calls[0];
+        expect(url).toBe('https://orboto.example.com/sse/mcp-events');
+        return init.headers;
+    }
+    it('sends x-orboto-agent-session with the instance token given at construction', async () => {
+        expect(await connectOnce({ instanceToken: 'mcp-session-1' })).toMatchObject({
+            Authorization: 'Bearer orb_x', 'x-orboto-agent-session': 'mcp-session-1',
+        });
+    });
+    it('sends the token pinned after construction, once the transport session id is known', async () => {
+        expect((await connectOnce({ pin: 'mcp-session-2' }))['x-orboto-agent-session']).toBe('mcp-session-2');
+    });
+    it('omits the header when no instance token is known', async () => {
+        expect(await connectOnce({})).not.toHaveProperty('x-orboto-agent-session');
+    });
+});

package/dist/http-transport.js

@@ -11,6 +11,7 @@ import { buildOrbotoMcpServer } from './server.js';
 import { resolveToolset } from './toolset.js';
 import { OrbotoClient, preflightMcpSession } from './orboto-client.js';
 import { EventBridge } from './event-bridge.js';
+import { mcpInstanceToken } from './tools/shared.js';
 /** Default store backed by the api's `/system/mcp/sessions` endpoints. Each
  *  call builds a short-lived OrbotoClient bound to the request's token so the
  *  api scopes every read/write to that identity. */
@@ -167,12 +168,13 @@ function wwwAuthChallenge(req, baseUrl, error, description) {
 export function createHttpServer({ baseUrl, sessionStore }) {
     const sessions = new Map();
     const store = sessionStore ?? createApiSessionStore(baseUrl);
-    async function buildSessionCore(tokenHolder, userAgentSuffix, toolset) {
+    async function buildSessionCore(tokenHolder, userAgentSuffix, toolset, sessionId) {
         const tokenProvider = holderTokenProvider(tokenHolder);
         const sessionClient = new OrbotoClient({ baseUrl, tokenProvider, userAgentSuffix });
         const subscriptions = new Set();
         const mcp = await buildOrbotoMcpServer({ baseUrl, tokenProvider, userAgentSuffix, subscriptions, toolset });
-        const bridge = new EventBridge({ baseUrl, tokenProvider, mcp, subscriptions });
+        const bridge = new EventBridge({ baseUrl, tokenProvider, mcp, subscriptions,
+            ...(sessionId ? { instanceToken: mcpInstanceToken(undefined, { sessionId }) } : {}) });
         return { sessionClient, subscriptions, mcp, bridge };
     }
     /** ORB-1576 - resolve a bearer's owner identity via the status preflight;
@@ -188,7 +190,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
         }
     }
     async function establishForcedSession(tokenHolder, userAgentSuffix, chosenSessionId, userEmail, toolset) {
-        const { sessionClient, mcp, bridge } = await buildSessionCore(tokenHolder, userAgentSuffix, toolset);
+        const { sessionClient, mcp, bridge } = await buildSessionCore(tokenHolder, userAgentSuffix, toolset, chosenSessionId);
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
         transport.onclose = () => { sessions.delete(chosenSessionId); bridge.close(); };
         await mcp.connect(transport);
@@ -373,6 +375,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                     sessions.set(sid, {
                         transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail: ownerEmail, lastTouchAt: Date.now(),
                     });
+                    bridge.setInstanceToken(mcpInstanceToken(undefined, { sessionId: sid }));
                     bridge.start();
                     void store
                         .register(token, { sessionId: sid, clientInfo, userAgent })

package/dist/manifest-size.test.js

@@ -24,12 +24,14 @@ afterEach(() => { vi.restoreAllMocks(); });
  * edits - a description essay creeping back in is exactly what these
  * must catch, so the headroom is deliberately tighter than the old
  * 20 %. Shrink-only: raising either number is a conscious decision to
- * grow every session's connect cost.
+ * grow every session's connect cost. ORB-2132 raised the full ceiling by
+ * 2,000 chars because the agent_presence output schema now carries kind,
+ * actsAs, projects and connections (measured full = 165,759 chars).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */
 const CURATED_MAX_CHARS = 37_500;
-const FULL_MAX_CHARS = 165_000;
+const FULL_MAX_CHARS = 167_000;
 /**
  * ORB-1805 - the estimator the ticket measured the failure with
  * (`n_keep: 13533 >= n_ctx: 8192` in LM Studio): characters / 3.6. It is

package/dist/orboto-client.js

@@ -80,7 +80,7 @@ export class OrbotoClient {
     }
     /** GET a JSON endpoint. Throws `OrbotoApiError` on non-2xx. */
     async get(path, options = {}) {
-        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET', signal: options.signal });
+        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET', signal: options.signal, ...(options.instanceToken ? { headers: { 'x-orboto-agent-session': options.instanceToken } } : {}) });
         return (await res.json());
     }
     /** POST a JSON body. */

package/dist/server.js

@@ -23,9 +23,11 @@ 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 { 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';
 import { agentMessagesToolConfig, makeAgentMessagesHandler } from './tools/agent-messages.js';
 import { listProjectsToolConfig, makeListProjectsHandler } from './tools/list-projects.js';
 import { getProjectToolConfig, makeGetProjectHandler } from './tools/get-project.js';
+import { projectReadinessToolConfig, makeProjectReadinessHandler } from './tools/project-readiness.js';
 import { getProjectPrimerToolConfig, makeGetProjectPrimerHandler } from './tools/get-project-primer.js';
 import { listTicketsToolConfig, makeListTicketsHandler } from './tools/list-tickets.js';
 import { criticalPathToolConfig, makeCriticalPathHandler } from './tools/critical-path.js';
@@ -39,6 +41,7 @@ import { searchToolConfig, makeSearchHandler } from './tools/search.js';
 import { queryToolConfig, makeQueryHandler } from './tools/query.js';
 import { customerReportToolConfig, makeCustomerReportHandler } from './tools/customer-report.js';
 import { requirementsSpecToolConfig, makeRequirementsSpecHandler } from './tools/requirements-spec.js';
+import { specCheckToolConfig, makeSpecCheckHandler } from './tools/spec-check.js';
 import { wikiIngestUrlToolConfig, makeWikiIngestUrlHandler, wikiAskToolConfig, makeWikiAskHandler, wikiLintToolConfig, makeWikiLintHandler, wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler, wikiApplyPlanToolConfig, makeWikiApplyPlanHandler, wikiRecordToolConfig, makeWikiRecordHandler, wikiAppendSectionToolConfig, makeWikiAppendSectionHandler, wikiFlagStaleToolConfig, makeWikiFlagStaleHandler, wikiSaveAnswerToolConfig, makeWikiSaveAnswerHandler, } from './tools/wiki.js';
 import { personalFactListToolConfig, makePersonalFactListHandler, personalFactAddToolConfig, makePersonalFactAddHandler, personalFactUpdateToolConfig, makePersonalFactUpdateHandler, personalFactDeleteToolConfig, makePersonalFactDeleteHandler, } from './tools/personal-facts.js';
 import { listDocSpacesToolConfig, makeListDocSpacesHandler, getDocToolConfig, makeGetDocHandler, createDocSpaceToolConfig, makeCreateDocSpaceHandler, updateDocSpaceToolConfig, makeUpdateDocSpaceHandler, deleteDocSpaceToolConfig, makeDeleteDocSpaceHandler, listDocsInSpaceToolConfig, makeListDocsInSpaceHandler, createDocToolConfig, makeCreateDocHandler, updateDocToolConfig, makeUpdateDocHandler, deleteDocToolConfig, makeDeleteDocHandler, moveDocToolConfig, makeMoveDocHandler, duplicateDocSpaceToolConfig, makeDuplicateDocSpaceHandler, resolveDocSmartLinksToolConfig, makeResolveDocSmartLinksHandler, } from './tools/docs.js';
@@ -53,6 +56,8 @@ import { listCrossProjectLinksToolConfig, makeListCrossProjectLinksHandler, addC
 import { getTimerToolConfig, makeGetTimerHandler } from './tools/get-timer.js';
 import { getChecklistsToolConfig, makeGetChecklistsHandler } from './tools/get-checklists.js';
 import { listGitAppInstallationsToolConfig, makeListGitAppInstallationsHandler } from './tools/list-git-app-installations.js';
+import { gitRotateTokenToolConfig, makeGitRotateTokenHandler } from './tools/git-rotate-token.js';
+import { sentryToolConfig, makeSentryHandler } from './tools/sentry.js';
 import { createTicketToolConfig, makeCreateTicketHandler, updateTicketToolConfig, makeUpdateTicketHandler, moveTicketToolConfig, makeMoveTicketHandler, closeTicketToolConfig, makeCloseTicketHandler, deleteTicketToolConfig, makeDeleteTicketHandler, commentToolConfig, makeCommentHandler, updateCommentToolConfig, makeUpdateCommentHandler, deleteCommentToolConfig, makeDeleteCommentHandler, assignToolConfig, makeAssignHandler, unassignToolConfig, makeUnassignHandler, labelTicketToolConfig, makeLabelTicketHandler, unlabelTicketToolConfig, makeUnlabelTicketHandler, setMilestoneToolConfig, makeSetMilestoneHandler, addTicketDependencyToolConfig, makeAddTicketDependencyHandler, removeTicketDependencyToolConfig, makeRemoveTicketDependencyHandler, listTicketDependenciesToolConfig, makeListTicketDependenciesHandler, } from './tools/ticket-writes.js';
 import { timerStartToolConfig, makeTimerStartHandler, timerStopToolConfig, makeTimerStopHandler, logTimeToolConfig, makeLogTimeHandler, listTimeEntriesToolConfig, makeListTimeEntriesHandler, editTimeEntryToolConfig, makeEditTimeEntryHandler, deleteTimeEntryToolConfig, makeDeleteTimeEntryHandler, } from './tools/time-writes.js';
 import { listTicketSchedulesToolConfig, makeListTicketSchedulesHandler, scheduleTicketSessionToolConfig, makeScheduleTicketSessionHandler, cancelTicketSessionToolConfig, makeCancelTicketSessionHandler, } from './tools/ticket-schedules.js';
@@ -191,6 +196,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_agent_heartbeat', agentHeartbeatToolConfig, makeAgentHeartbeatHandler(client));
     reg('orboto_agent_presence', agentPresenceToolConfig, makeAgentPresenceHandler(client));
     reg('orboto_agent_notify', agentNotifyToolConfig, makeAgentNotifyHandler(client));
+    reg('orboto_message_work', agentMessageWorkToolConfig, makeAgentMessageWorkHandler(client));
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));
     reg('orboto_agent_broadcast', agentBroadcastToolConfig, makeAgentBroadcastHandler(client));
     reg('orboto_list_projects', listProjectsToolConfig, makeListProjectsHandler(client));
@@ -209,6 +215,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_query', queryToolConfig, makeQueryHandler(client));
     reg('orboto_customer_report', customerReportToolConfig, makeCustomerReportHandler(client));
     reg('orboto_requirements_spec', requirementsSpecToolConfig, makeRequirementsSpecHandler(client));
+    reg('orboto_spec_check', specCheckToolConfig, makeSpecCheckHandler(client));
     reg('orboto_list_doc_spaces', listDocSpacesToolConfig, makeListDocSpacesHandler(client));
     reg('orboto_get_doc', getDocToolConfig, makeGetDocHandler(client));
     reg('orboto_search_docs', searchDocsToolConfig, makeSearchDocsHandler(client));
@@ -261,6 +268,8 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_personal_fact_delete', personalFactDeleteToolConfig, makePersonalFactDeleteHandler(client));
     reg('orboto_get_timer', getTimerToolConfig, makeGetTimerHandler(client));
     reg('orboto_list_git_app_installations', listGitAppInstallationsToolConfig, makeListGitAppInstallationsHandler(client));
+    reg('orboto_git_rotate_token', gitRotateTokenToolConfig, makeGitRotateTokenHandler(client));
+    reg('orboto_sentry', sentryToolConfig, makeSentryHandler(client));
     reg('orboto_create_ticket', createTicketToolConfig, makeCreateTicketHandler(client));
     reg('orboto_update_ticket', updateTicketToolConfig, makeUpdateTicketHandler(client));
     reg('orboto_move_ticket', moveTicketToolConfig, makeMoveTicketHandler(client));
@@ -336,6 +345,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_attach_to_ticket', attachToTicketToolConfig, makeAttachToTicketHandler(client));
     reg('orboto_set_parent', setParentToolConfig, makeSetParentHandler(client));
     reg('orboto_update_project', updateProjectToolConfig, makeUpdateProjectHandler(client));
+    reg('orboto_project_readiness', projectReadinessToolConfig, makeProjectReadinessHandler(client));
     reg('orboto_create_project', createProjectToolConfig, makeCreateProjectHandler(client));
     reg('orboto_archive_project', archiveProjectToolConfig, makeArchiveProjectHandler(client));
     reg('orboto_check_similar', checkSimilarToolConfig, makeCheckSimilarHandler(client));

package/dist/tool-docs.js

@@ -13,7 +13,7 @@ export const SUMMARY_MAX_CHARS = 220;
  */
 const SUMMARY_OVERRIDES = {
     orboto_create_full_backup: 'Start a full-workspace backup job (all projects, users, config, attachments); returns the job id to poll via orboto_list_backups.',
-    orboto_get_ticket: 'Fetch one ticket by key (ORB-42) or UUID: full detail incl. description, status, assignees, checklists, dependencies and comments.',
+    orboto_get_ticket: 'Fetch one ticket by key or UUID with description, status, assignees, checklists and comments.',
     orboto_requirements_spec: 'Generate a structured requirements spec for a project or milestone from its tickets (scope, actors, functional + non-functional requirements).',
     orboto_update_doc_space: 'Update a doc space\'s name, description, icon, project binding or access mode (open/restricted) by space id.',
     orboto_search_docs: 'Full-text search over doc/wiki pages (query, optional space or project filter); returns matching pages with snippets.',

package/dist/tools/agent-coordination.js

@@ -4,6 +4,7 @@
  * @see ORB-704, ORB-706
  */
 import { z } from 'zod';
+import { AgentInventoryEntrySchema, AgentInventoryKindSchema } from './agent-presence-schema.js';
 import { mcpInstanceToken } from './shared.js';
 export const agentHeartbeatToolConfig = {
     title: 'Agent heartbeat (Multi-Agent Coordination)',
@@ -37,35 +38,28 @@ export function makeAgentHeartbeatHandler(client) {
 }
 export const agentPresenceToolConfig = {
     title: 'Workspace agent presence',
-    description: 'Returns currently-active agent sessions in the workspace. Active = heartbeat within the last 90 s. Super-admins see every agent; regular users see only their own sessions (useful for "is my dispatcher daemon alive?" checks). Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, and the ticket the agent is working on if any. Use this to plan multi-agent work - e.g. before dispatching a sub-task, look up which other agents are active and what they\'re working on so you don\'t step on a parallel run.',
-    inputSchema: z.object({}).shape,
+    description: 'Returns all active orboto agent instances, including lane workers/reviewers, inbox and MCP connections and registered runners. Session freshness is 90 seconds; lanes retain their 300-second heartbeat grace. Unexpired work leases keep their owning instance visible. Ticket metadata and claims retain ordinary ticket visibility. Rows include `kind` (agent or human, classified by the credential: agent API key, OAuth grant, lane, external token or bot account; `isBot` is its alias), `actsAs` (the human account an AI client acts under), `projects` (memberships plus lane projects), `connections` (type + label per credential or attachment, `live_events` for the MCP event bridge), owner, lane and stable sessionId; separate instances of one account remain separate. Callers with admin:system:read see every agent; other users see only their own sessions (useful for "is my dispatcher daemon alive?" checks). Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, and the ticket the agent is working on if any. Use this to plan multi-agent work - e.g. before dispatching a sub-task, look up which other agents are active and what they\'re working on so you don\'t step on a parallel run. Filters `projectKey` (rows whose `projects` contain the key) and `kind` (agent | human) narrow the list client-side, the same way `orboto agents --project KEY --bots|--humans` does.',
+    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.'),
+    }).shape,
     outputSchema: z.object({
-        sessions: z.array(z.object({
-            userId: z.string().uuid(),
-            userEmail: z.string(),
-            userFullName: z.string().nullable(),
-            sessionId: z.string().uuid(),
-            status: z.string(),
-            workingOnTicket: z.object({
-                id: z.string().uuid(),
-                key: z.string().nullable(),
-                title: z.string(),
-                projectKey: z.string().nullable(),
-            }).nullable(),
-            capabilities: z.array(z.string()),
-            clientInfo: z.record(z.string(), z.string()),
-            lastSeenAt: z.string(),
-            createdAt: z.string(),
-        })),
+        sessions: z.array(AgentInventoryEntrySchema),
     }).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 () => {
-        const sessions = await client.get('/v1/agent/presence');
+    return async (args = {}) => {
+        const all = await client.get('/v1/agent/inventory');
+        const sessions = filterPresenceRows(all, args);
         const lines = [];
         if (sessions.length === 0) {
-            lines.push('No active agent sessions in the workspace.');
+            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):`);
@@ -75,7 +69,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} (${runtime}) - ${s.status}${work}`);
+                lines.push(`- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${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(', ')}` : ''}`);
             }
         }
         return {

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

@@ -43,16 +43,16 @@ describe('orboto_agent_heartbeat', () => {
     });
 });
 describe('orboto_agent_presence', () => {
-    it('GETs /v1/agent/presence and renders one line per session', async () => {
+    it('GETs /v1/agent/inventory and renders one line per session', async () => {
         stub([{
                 json: [
                     {
                         userId: '00000000-0000-0000-0000-000000000001',
                         userEmail: 'alice@x.test',
-                        userFullName: 'Alice',
+                        userFullName: 'Alice', kind: 'human', isBot: false, actsAs: null, owner: null, autonomyPaused: false, lane: null, projects: [], connections: [], workSessions: [],
                         sessionId: '00000000-0000-0000-0000-000000000010',
                         status: 'working',
-                        workingOnTicket: { id: 't1', key: 'ORB-42', title: 'Test', projectKey: 'ORB' },
+                        workingOnTicket: { id: '00000000-0000-0000-0000-000000000020', key: 'ORB-42', title: 'Test', projectKey: 'ORB' },
                         capabilities: ['writes-tickets'],
                         clientInfo: { name: 'claude-code' },
                         lastSeenAt: new Date().toISOString(),
@@ -61,7 +61,8 @@ describe('orboto_agent_presence', () => {
                     {
                         userId: '00000000-0000-0000-0000-000000000002',
                         userEmail: 'bot@x.test',
-                        userFullName: null,
+                        userFullName: null, kind: 'agent', isBot: true, actsAs: null, owner: { id: '00000000-0000-0000-0000-000000000001', name: 'Alice', email: 'alice@x.test' },
+                        autonomyPaused: false, lane: null, projects: [{ id: '00000000-0000-0000-0000-000000000030', key: 'ORB', name: 'orboto' }], connections: [{ type: 'api_key', label: 'dispatcher' }], workSessions: [],
                         sessionId: '00000000-0000-0000-0000-000000000011',
                         status: 'idle',
                         workingOnTicket: null,
@@ -76,8 +77,9 @@ describe('orboto_agent_presence', () => {
         const result = await handler();
         const text = result.content[0].text;
         expect(text).toContain('2 active session(s)');
-        expect(text).toContain('Alice (claude-code) - working · working on [ORB] ORB-42');
-        expect(text).toContain('bot@x.test (dispatcher-daemon) - idle');
+        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; owner: Alice');
+        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/inventory');
         expect(result.structuredContent.sessions).toHaveLength(2);
     });
     it('handles an empty workspace gracefully', async () => {
@@ -86,6 +88,38 @@ describe('orboto_agent_presence', () => {
         const result = await handler();
         expect(result.content[0].text).toBe('No active agent sessions in the workspace.');
     });
+    const presenceRows = () => [
+        { userId: '00000000-0000-0000-0000-000000000001', userEmail: 'alice@x.test', userFullName: 'Alice', kind: 'human', isBot: false, actsAs: null, owner: null, autonomyPaused: false, lane: null, projects: [{ id: '00000000-0000-0000-0000-000000000030', key: 'ORB', name: 'orboto' }], connections: [{ type: 'api_key', label: 'laptop' }], workSessions: [], sessionId: '00000000-0000-0000-0000-000000000010', status: 'working', workingOnTicket: null, capabilities: [], clientInfo: { name: 'claude-code' }, lastSeenAt: new Date().toISOString(), createdAt: new Date().toISOString() },
+        { 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 () => {
+        const handler = makeAgentPresenceHandler(client);
+        const ids = async (args) => {
+            stub([{ json: presenceRows() }]);
+            const result = await handler(args);
+            expect(vi.mocked(fetch).mock.calls.at(-1)?.[0]).toBe('https://orboto.example.com/v1/agent/inventory');
+            return result.structuredContent.sessions.map((s) => s.sessionId.slice(-2));
+        };
+        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: presenceRows() }]);
+        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).');
+    });
+    it('renders acts-as, lane, projects and connection types on each line', async () => {
+        stub([{ json: 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');
+        expect(text).toContain('owner: acts as Alice; connections: oauth');
+    });
 });
 describe('orboto_agent_notify', () => {
     it('POSTs to /v1/agent/notify with the body the user supplied', async () => {

package/dist/tools/agent-message-work.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
+export const agentMessageWorkToolConfig = {
+    title: 'Inspect or explicitly handle message work',
+    description: 'List, inspect or mutate durable message work (mutation schema: orboto_api_search). ACK is a separate read receipt and finishes nothing.',
+    inputSchema: z.object({ messageId: z.string().uuid().optional(), mutation: z.record(z.unknown()).optional(),
+        cursor: z.string().optional(), limit: z.number().int().min(1).max(100).default(25), openOnly: z.boolean().default(true) }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+export function makeAgentMessageWorkHandler(client) {
+    return async (args, extra) => {
+        if (args.mutation && !args.messageId)
+            throw new Error('messageId is required for a mutation');
+        const q = new URLSearchParams({ limit: String(args.limit ?? 25), openOnly: String(args.openOnly ?? true) });
+        if (args.cursor)
+            q.set('cursor', args.cursor);
+        const result = args.mutation
+            ? await client.post(`/v1/agent/messages/${args.messageId}/work`, { ...args.mutation, instanceToken: mcpInstanceToken(undefined, extra) })
+            : await client.get(`${args.messageId ? `/v1/agent/messages/${args.messageId}` : '/v1/agent/message-work'}?${q}`, { instanceToken: mcpInstanceToken(undefined, extra) });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+    };
+}

package/dist/tools/agent-message-work.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './agent-message-work.js';
+import { makeAgentMessagesHandler } from './agent-messages.js';
+describe('message work MCP parity', () => {
+    it('carries no second copy of the shared mutation schema', () => {
+        const shared = readFileSync(new URL('../../../../packages/shared-schema/src/agent-message-work.ts', import.meta.url), 'utf8');
+        const local = readFileSync(new URL('./agent-message-work.ts', import.meta.url), 'utf8');
+        const stepBlock = shared.slice(shared.indexOf('export const MessageWorkStepSchema'), shared.indexOf('export const MessageWorkMutationSchema'));
+        expect(local).not.toContain(stepBlock.replaceAll('export const', 'const'));
+        expect(local).not.toContain('MessageWorkStepSchema');
+        expect(agentMessageWorkToolConfig.description).toContain('orboto_api_search');
+    });
+    it('uses each MCP connection identity and reads exact IDs without ACK', async () => {
+        const get = vi.fn().mockResolvedValueOnce({ message: { id: 'message' } }).mockResolvedValue({ messages: [] });
+        const post = vi.fn().mockResolvedValue({ state: 'in_work' });
+        const client = { get, post };
+        const handler = makeAgentMessageWorkHandler(client);
+        await handler({ messageId: 'message' }, { sessionId: 'a' });
+        expect(get).toHaveBeenCalledWith('/v1/agent/messages/message?limit=25&openOnly=true', { instanceToken: 'mcp-a' });
+        expect(post).not.toHaveBeenCalled();
+        await handler({ messageId: 'message', mutation: { action: 'claim', summary: 'Explicit acceptance', evidence: [], leaseSeconds: 900 } }, { sessionId: 'a' });
+        expect(post).toHaveBeenCalledWith('/v1/agent/messages/message/work', expect.objectContaining({ instanceToken: 'mcp-a' }));
+    });
+    it('ACK is a plain read receipt - no evidence travels with it', async () => {
+        const get = vi.fn().mockResolvedValue({ messages: [] });
+        const post = vi.fn().mockResolvedValue({ acked: 1 });
+        const client = { get, post };
+        await makeAgentMessagesHandler(client)({ ackIds: ['message'] }, { sessionId: 'b' });
+        expect(post).toHaveBeenCalledWith('/v1/agent/messages/ack', { ids: ['message'], instanceToken: 'mcp-b' });
+        expect(JSON.stringify(post.mock.calls)).not.toContain('evidence');
+    });
+});

package/dist/tools/agent-messages.js

@@ -8,18 +8,22 @@
  * api's `x-orboto-agent-mail` response header - no polling anywhere).
  */
 import { z } from 'zod';
+import { makeAgentMessageWorkHandler } from './agent-message-work.js';
 import { mcpInstanceToken } from './shared.js';
 export const agentMessagesToolConfig = {
-    title: 'Fetch / acknowledge your agent inbox',
-    description: 'Your store-and-forward inbox: messages other agents sent you, broadcasts to your scopes (payload.broadcast names the scope) and ticket_ready wake-ups (subject ticket-ready:<KEY>, payload.type ticket_ready with ticketKey, reason assigned | labeled | unblocked: the ticket is yours to claim; claim or answer, then ack). Default = unread, marked delivered on fetch; ackIds marks read. Reply via orboto_agent_notify with threadId = the message id.',
+    title: 'Agent inbox and message work',
+    description: 'Your inbox. messageWork carries durable work ownership - claim before executing. ackIds is a plain read receipt: no claim needed, finishes nothing. Reply via orboto_agent_notify with threadId.',
     inputSchema: z.object({
-        all: z.boolean().default(false).describe('true = include already-read messages'),
+        messageWork: z.record(z.unknown()).optional()
+            .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),
+        all: z.boolean().default(false),
         limit: z.number().int().min(1).max(200).default(50),
-        project: z.string().min(1).max(64).optional().describe('Project key or UUID: scoped messages for this project plus unscoped ones. Ack only messages that are yours.'),
-        includeOwnSends: z.boolean().default(false).describe('true = also list messages this session sent (hidden by default so a shared identity never wakes itself).'),
-        ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark as read'),
+        project: z.string().min(1).max(64).optional().describe('Project key/UUID; includes unscoped mail.'),
+        includeOwnSends: z.boolean().default(false),
+        ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark read.'),
     }).shape,
     outputSchema: z.object({
+        work: z.record(z.unknown()).optional(),
         messages: z.array(z.object({
             id: z.string(),
             fromUserId: z.string(),
@@ -33,13 +37,19 @@ export const agentMessagesToolConfig = {
         })),
         acked: z.number().int(),
     }).shape,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
 export function makeAgentMessagesHandler(client) {
     return async (args, extra) => {
+        if (args.messageWork) {
+            if (args.ackIds?.length)
+                throw new Error('Use a separate explicit ACK call.');
+            const result = await makeAgentMessageWorkHandler(client)(args.messageWork, extra);
+            return { content: result.content, structuredContent: { messages: [], acked: 0, work: result.structuredContent } };
+        }
         let acked = 0;
         if (args.ackIds && args.ackIds.length > 0) {
-            const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds });
+            const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds, instanceToken: mcpInstanceToken(undefined, extra) });
             acked = res.acked;
         }
         const q = new URLSearchParams();

package/dist/tools/agent-presence-schema.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+const WorkSessionResourceClaimSchema = z.object({
+    kind: z.enum(['path', 'named']), value: z.string().min(1).max(500), mode: z.enum(['read', 'write']),
+    state: z.enum(['granted', 'waiting']).optional(), requestedAt: z.string().optional(),
+});
+export const AgentInventoryKindSchema = z.enum(['agent', 'human']);
+export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web']);
+export const AgentInventoryConnectionSchema = z.object({ type: AgentConnectionTypeSchema, label: z.string() });
+export const AgentInventoryProjectSchema = z.object({ id: z.string().uuid(), key: z.string(), name: z.string() });
+export const AgentInventoryEntrySchema = z.object({
+    userId: z.string().uuid(),
+    userEmail: z.string(),
+    userFullName: z.string().nullable(),
+    kind: AgentInventoryKindSchema,
+    /** Alias of `kind === 'agent'`. */
+    isBot: z.boolean(),
+    actsAs: z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() }).nullable(),
+    owner: z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() }).nullable(),
+    autonomyPaused: z.boolean(),
+    sessionId: z.string().uuid(),
+    status: z.string(),
+    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),
+    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(),
+        resourceClaims: z.array(WorkSessionResourceClaimSchema),
+    })),
+    capabilities: z.array(z.string()),
+    clientInfo: z.record(z.string(), z.string()),
+    lastSeenAt: z.string(),
+    createdAt: z.string(),
+});
+export const AgentInventorySchema = z.array(AgentInventoryEntrySchema);

package/dist/tools/claim.js

@@ -3,6 +3,7 @@
  *
  * @see ORB-179, ORB-181
  */
+import { specGateFailure, isAlreadyAssigned } from './spec-schemas.js';
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken, resolveTicketByKey } from './shared.js';
@@ -15,33 +16,44 @@ const CATEGORY_TO_LEGACY = {
 };
 export const claimToolConfig = {
     title: 'Claim a ticket (assign self + in_progress + timer)',
-    description: 'Composite of `assign self → move to in_progress → start timer` - the canonical "I am picking this up now" move. Idempotent: re-claiming an already-claimed in_progress ticket is a no-op. Set `sole=true` to remove every other assignee first (destructive take-over). Set `force=true` to allow re-claiming a `done` ticket (otherwise refuses, to prevent accidental reopens). Set `noTimer=true` to skip the timer start (e.g. when you only want ownership, not time tracking). If a different ticket has an active timer, it is stopped first (its elapsed time commits a time entry under the previous ticket). '
-        + '`agentSessionToken` is a stable per-agent-instance token: on a bot/service account it scopes the timer to YOUR instance - concurrent per-instance timers and NO auto-stop, so you own both start and stop. Omit it on human accounts, which keep the single-timer behaviour.',
+    description: 'Assign yourself, move to in_progress and start a timer. Repeated claims recheck the specification gate. Worker bots need ready, or override=true with a reason; enabled epics are blocked. sole removes other assignees after the gate passes. force permits reopening done tickets. noTimer skips time tracking. On human accounts a different active timer is stopped first and its elapsed time booked to that ticket. Bot timers are per instance and never auto-stop each other: agentSessionToken defaults to this MCP connection; own both start and stop.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
-        sole: z.boolean().optional().describe('Take-over: remove every other assignee first.'),
-        force: z.boolean().optional().describe('Allow re-claiming a `done` ticket.'),
-        noTimer: z.boolean().optional().describe('Skip the timer start.'),
-        agentSessionToken: z.string().optional().describe('Per-agent-instance token; scopes the timer on bot accounts.'),
+        override: z.boolean().optional().describe("Spec override; reason required."),
+        reason: z.string().trim().min(1).max(2000).optional(),
+        sole: z.boolean().optional().describe('Remove other assignees after gate.'),
+        force: z.boolean().optional().describe('Reopen done.'),
+        noTimer: z.boolean().optional().describe('No timer.'),
+        agentSessionToken: z.string().optional().describe('Instance token for bot timers.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeClaimHandler(client) {
-    return async ({ ticketKey, sole, force, noTimer, agentSessionToken }, extra) => {
+    return async ({ ticketKey, sole, force, override, reason, noTimer, agentSessionToken }, extra) => {
         const me = await client.get('/users/me');
         const current = await resolveTicketByKey(client, ticketKey);
         const currentAssignees = current.assignees ?? [];
-        const alreadyAssigned = currentAssignees.some((a) => a.id === me.id);
+        const alreadyAssigned = currentAssignees.some((a) => (a.userId ?? a.id) === me.id);
         const currentCategory = current.statusCategory;
         if (currentCategory === 'done' && !force) {
             throw new Error(`Refusing to claim [${current.ticketKey}]: status is "done". Pass force=true to reopen + claim.`);
         }
+        try {
+            await client.post(`/projects/${current.projectId}/tickets/${current.id}/assignees/${me.id}`, { override, reason });
+        }
+        catch (error) {
+            const gate = error instanceof OrbotoApiError && error.status === 409 ? specGateFailure(error.body) : undefined;
+            if (gate)
+                return gate;
+            if (!(error instanceof OrbotoApiError) || error.status !== 409 || !isAlreadyAssigned(error.body))
+                throw error;
+        }
         if (sole) {
             for (const a of currentAssignees) {
-                if (a.id === me.id)
+                if ((a.userId ?? a.id) === me.id)
                     continue;
                 try {
-                    await client.delete(`/projects/${current.projectId}/tickets/${current.id}/assignees/${a.id}`);
+                    await client.delete(`/projects/${current.projectId}/tickets/${current.id}/assignees/${a.userId ?? a.id}`);
                 }
                 catch (err) {
                     if (!(err instanceof OrbotoApiError) || err.status !== 404)
@@ -49,15 +61,6 @@ export function makeClaimHandler(client) {
                 }
             }
         }
-        if (!alreadyAssigned) {
-            try {
-                await client.post(`/projects/${current.projectId}/tickets/${current.id}/assignees/${me.id}`, {});
-            }
-            catch (err) {
-                if (!(err instanceof OrbotoApiError) || err.status !== 409)
-                    throw err;
-            }
-        }
         let finalTicket = current;
         if (currentCategory !== 'in_progress') {
             finalTicket = await client.patch(`/projects/${current.projectId}/tickets/${current.id}`, { status: CATEGORY_TO_LEGACY.in_progress });