@orboto/mcp 0.226.2 → 0.228.1

package/dist/tools/agent-messages-compact.test.js

@@ -1,5 +1,5 @@
 /**
- * ORB-2502 - orboto_messages lists the newest 10 unread compactly with the exact count; all:true keeps every message in full.
+ * ORB-2502 - orboto_messages lists the newest 4 unread compactly (10 before ORB-2548) with the exact count; all:true keeps every message in full.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
@@ -23,11 +23,11 @@ function stubInbox(urls) {
     });
 }
 describe('ORB-2502 - the compact inbox on MCP', () => {
-    it('asks for the newest 10 compactly, prints the excerpt and the count, and leaves the payload out of the structured answer', async () => {
+    it('asks for the newest 4 compactly, prints the excerpt and the count, and leaves the payload out of the structured answer', async () => {
         const urls = [];
         stubInbox(urls);
         const result = await makeAgentMessagesHandler(client)({ since: '2026-09-30T00:00:00Z' }, { sessionId: 'abc' });
-        expect(urls[0]).toContain('limit=10');
+        expect(urls[0]).toContain('limit=4');
         expect(urls[0]).toContain('compact=true');
         expect(urls[0]).toContain('since=2026-09-30T00%3A00%3A00Z');
         const text = result.content[0].text;

package/dist/tools/agent-messages.js

@@ -22,10 +22,12 @@ export function repeatMarks(m) {
     ].filter(Boolean);
     return marks.length ? ` [${marks.join(', ')}]` : '';
 }
+/** ORB-2548 - the compact page an MCP inbox read returns by default, sized so it fits the 4,000-character budget. */
+export const COMPACT_PAGE_LIMIT = 4;
 const UNREGISTERED_INBOX_HINT = 'Not registered: only account mail is listed. Register with orboto_session_start to see the mail addressed to your session.';
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out (includeOwnSends lists your sends with recipient session, delivered/read state, thread), all:true is the account view in full (ORB-2136). Default: the newest 10 unread, newest first, a header plus 300 payload characters each, then `N unread, M older than 7 days`; limit and since (ISO time or message id) narrow it. Before orboto_session_start only account mail is listed; register to see mail addressed to your session (ORB-2347). messageWork carries durable work ownership (mutation schema: orboto_api_search) - claim before executing. ackIds (message ids) acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId).',
+    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out (includeOwnSends lists your sends with recipient session, delivered/read state, thread), all:true is the account view in full (ORB-2136). Default: the newest 4 unread, newest first, a header plus 300 payload characters each, then `N unread, M older than 7 days`; limit and since (ISO time or message id) narrow it. Server-side filters (ORB-2548): direction sent (only your sends, any read state), threadId (that message and its answers), kind; nextCursor continues the page (cursor). Before orboto_session_start only account mail is listed; register to see mail addressed to your session (ORB-2347). messageWork carries durable work ownership (mutation schema: orboto_api_search) - claim before executing. ackIds (message ids) acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}.'),
@@ -34,6 +36,10 @@ export const agentMessagesToolConfig = {
         since: z.string().optional(),
         project: z.string().min(1).max(64).optional().describe('Key/UUID; includes unscoped mail.'),
         includeOwnSends: z.boolean().default(false),
+        direction: z.enum(['received', 'sent']).optional(),
+        threadId: z.string().uuid().optional(),
+        kind: z.enum(['request', 'error', 'info', 'complete']).optional(),
+        cursor: z.string().max(500).optional(),
         ackIds: z.array(z.string().uuid()).max(200).optional(),
         dismiss: z.object({
             ids: z.array(z.string().uuid()).min(1).max(200),
@@ -66,6 +72,7 @@ export const agentMessagesToolConfig = {
         acked: z.number().int(),
         dismissed: z.number().int().optional(),
         closed: z.number().int().optional(),
+        nextCursor: z.string().nullable().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
@@ -116,28 +123,40 @@ export function makeAgentMessagesHandler(client) {
         const q = new URLSearchParams();
         if (args.all)
             q.set('all', 'true');
-        q.set('limit', String(args.limit ?? (compact ? 10 : 50)));
+        q.set('limit', String(args.limit ?? (compact ? COMPACT_PAGE_LIMIT : 50)));
         if (compact)
             q.set('compact', 'true');
         if (args.since)
             q.set('since', args.since);
         if (args.project)
             q.set('project', args.project);
+        if (args.direction)
+            q.set('direction', args.direction);
+        if (args.threadId)
+            q.set('threadId', args.threadId);
+        if (args.kind)
+            q.set('kind', args.kind);
+        if (args.cursor)
+            q.set('cursor', args.cursor);
         const instanceToken = mcpInstanceToken(undefined, extra);
         if (args.includeOwnSends)
             q.set('includeOwn', 'true');
-        else
+        else if (args.direction !== 'sent')
             q.set('excludeRef', instanceToken);
-        const { messages, sessionId, counts } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
+        const { messages, sessionId, counts, nextCursor } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
         const header = (m) => `${m.own ? `[sent] ${sentState(m)} ` : ''}[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''}${repeatMarks(m)} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})`;
         const lines = messages.length === 0
             ? [acked > 0 ? `Acknowledged ${acked} message(s). Inbox empty.` : 'Inbox empty.']
             : messages.flatMap((m) => (compact ? compactLines(m, header(m)) : [`${header(m)}${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`]));
+        if (messages.length === 0 && args.direction === 'sent')
+            lines[0] = 'Nothing sent matches.';
         if (messages.length > 0) {
             lines.push(`Acknowledge with ackIds once handled; reply via orboto_agent_notify with threadId (toSessionRef = the sender's instance short id reaches that session only).`);
         }
         if (compact && counts)
             lines.push(`${counts.unread} unread, ${counts.olderThan7Days} older than 7 days (all, limit N, since)`);
+        if (nextCursor)
+            lines.push(`More messages: call again with cursor "${nextCursor}".`);
         if (args.dismiss) {
             lines.unshift(`Dismissed ${dismissedCount} message(s) as ${args.dismiss.reason}${closedCount > 0 ? `, ${closedCount} closed for the account` : ''}${feedbackSent > 0 ? `, ${feedbackSent} sender(s) told about the misroute` : ''}.`);
         }
@@ -160,6 +179,7 @@ export function makeAgentMessagesHandler(client) {
                 acked,
                 dismissed: dismissedCount,
                 closed: closedCount,
+                nextCursor: nextCursor ?? null,
             },
         };
     };

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

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { AgentInventoryKindSchema, AgentSessionWakeSchema } from './agent-presence-schema.js';
+import { AgentSessionScopeSchema } from './agent-session-scope.js';
+/** ORB-2548 - one presence row as orboto_agent_presence returns it; the full inventory row is `orboto agents --json` and `GET /v1/agent/who?include=inventory`. */
+export const AgentPresenceRowSchema = z.object({
+    sessionId: z.string().uuid(),
+    userEmail: z.string(),
+    userFullName: z.string().nullable(),
+    kind: AgentInventoryKindSchema,
+    owner: z.string().nullable(),
+    status: z.string(),
+    lane: z.string().nullable(),
+    scope: AgentSessionScopeSchema.nullable(),
+    memberProjects: z.number().int(),
+    connections: z.array(z.string()),
+    wake: AgentSessionWakeSchema.optional(),
+    state: z.string().optional(),
+    origin: z.object({ host: z.string().nullable(), repo: z.string().nullable(), pid: z.number().nullable(), harness: z.string().nullable(), client: z.string().nullable() }).nullable(),
+    workingOn: z.string().nullable(),
+    lastSeenAt: z.string(),
+    redacted: z.boolean().optional(),
+});

package/dist/tools/agent-who.js

@@ -1,19 +1,25 @@
 /** ORB-2264 - the live directory: who a sender can address before sending. */
 import { z } from 'zod';
-import { AgentSessionRoleSchema } from './agent-session-scope.js';
 import { ownerLine } from './responsibilities.js';
-import { originText } from './agent-coordination.js';
+import { nextPageLine, originText, PresenceFilterShape, presenceQuery, readPresence, unknownProjectText } from './agent-coordination.js';
 import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
+export function refusalLines(refusals) {
+    if (!refusals?.length)
+        return [];
+    return ['Refused heartbeats in the last 24 hours (no role address, not listed):', ...refusals.map((r) => {
+            const where = [r.lastHost, r.lastRepo].filter(Boolean).join('/') || 'unknown origin';
+            return `- ${r.email}: ${r.count} (no scope ${r.scopeRequired}, second start ${r.sessionExists}), last ${r.lastAt} from ${where}${r.lastHarness ? ` (${r.lastHarness})` : ''}`;
+        })];
+}
 export const agentWhoToolConfig = {
     title: 'Who receives agent mail',
-    description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. Each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it).',
+    description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. GET /v1/agent/who; each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. A session without a declared scope is not listed; the refused heartbeats of the last 24 hours follow per account (refusals). `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it); email, sessionId (id or 8+ character prefix), kind and wake narrow on the server; 4 rows a page, nextCursor continues (cursor); a project that is unknown or not visible to you answers so in one line.',
     inputSchema: z.object({
         project: z.string().min(1).max(64).optional(),
-        role: AgentSessionRoleSchema.optional(),
         for: z.string().min(2).max(2000).optional(),
-        state: z.enum(['live', 'quiet', 'orphaned', 'unknown_origin']).optional(),
+        ...PresenceFilterShape,
     }).shape,
-    outputSchema: z.object({ sessions: z.array(z.unknown()), owner: z.unknown().optional() }).shape,
+    outputSchema: z.object({ sessions: z.array(z.unknown()), owner: z.unknown().optional(), nextCursor: z.string().nullable(), refusals: z.array(z.unknown()).optional() }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
 /** One directory row as a line: address, account, session, projects, channel, ticket. */
@@ -28,25 +34,19 @@ export function whoLine(s) {
 }
 export function makeAgentWhoHandler(client) {
     return async (args = {}) => {
-        const qs = new URLSearchParams();
-        if (args.state)
-            qs.set('state', args.state);
-        if (args.project)
-            qs.set('project', args.project);
-        if (args.role)
-            qs.set('role', args.role);
-        if (args.for)
-            qs.set('for', args.for);
-        const res = await client.get(`/v1/agent/who${qs.size ? `?${qs.toString()}` : ''}`);
+        const res = await readPresence(client, `/v1/agent/who?${presenceQuery(args)}`, args.project);
+        if (!res)
+            return { content: [{ type: 'text', text: unknownProjectText(args.project) }], structuredContent: { sessions: [], nextCursor: null } };
         const ownerLines = args.for
             ? [res.owner ? `Owner:\n${ownerLine(res.owner)}` : `No entry in the responsibility map matches "${args.for}".`]
             : [];
         const lines = res.sessions.length
-            ? [...ownerLines, `${res.sessions.length} live session(s):`, ...res.sessions.map(whoLine)]
+            ? [...ownerLines, `${res.sessions.length} live session(s)${res.nextCursor ? ' on this page' : ''}:`, ...res.sessions.map(whoLine), ...nextPageLine(res.nextCursor)]
             : [...ownerLines, res.owner ? `No live session answers to ${res.owner.entry.ownerAddress} - send with queue: true and project ${res.owner.entry.ownerAddress.split('@')[1]} to keep it until one declares it.` : 'No live session matches - a request sent now answers no_recipient unless it is queued.'];
+        lines.push(...refusalLines(res.refusals));
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { sessions: res.sessions, ...(args.for ? { owner: (res.owner ?? null) } : {}) },
+            structuredContent: { sessions: res.sessions, ...(args.for ? { owner: (res.owner ?? null) } : {}), nextCursor: res.nextCursor ?? null, ...(res.refusals?.length ? { refusals: res.refusals } : {}) },
         };
     };
 }

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

@@ -17,10 +17,17 @@ describe('orboto_who', () => {
             return { ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [entry] }) };
         });
         const result = await makeAgentWhoHandler(client)({ project: 'ORB', role: 'integrator' });
-        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?project=ORB&role=integrator');
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?project=ORB&role=integrator&limit=4');
         expect(result.content[0].text).toContain('integrator@ORB - claude@orboto.io session f072e1c5, working, claude-code online');
         expect(result.structuredContent).toMatchObject({ sessions: [expect.objectContaining({ shortId: 'f072e1c5' })] });
     });
+    it('ORB-2548: a project that is unknown or not visible answers in one line instead of a raw 404', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: false, status: 404, statusText: 'Not Found', headers: new Headers(), text: async () => '{"errorKey":"errors.agents.message_project_not_found"}', json: async () => ({}) }));
+        const result = await makeAgentWhoHandler(client)({ project: 'gone' });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toBe('Project "GONE" is unknown or not visible to you - no session is listed for it.');
+        expect(result.structuredContent).toEqual({ sessions: [], nextCursor: null });
+    });
     it('says a request would be refused when nobody matches, and is read-only', async () => {
         vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [] }) }));
         const result = await makeAgentWhoHandler(client)({});
@@ -41,6 +48,6 @@ describe('orboto_who', () => {
             return { ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [] }) };
         });
         await makeAgentWhoHandler(client)({ state: 'unknown_origin' });
-        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?state=unknown_origin');
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?state=unknown_origin&limit=4');
     });
 });

package/dist/tools/bulk-writes.js

@@ -15,12 +15,12 @@ const CATEGORY_TO_LEGACY = {
     wont_fix: 'WONT_FIX',
 };
 const TICKET_KEY_ARRAY = z.array(z.string().min(3)).min(1).max(200).optional()
-    .describe('Ticket keys, e.g. ["ACME-1"]; at most 200. Give ticketKeys or query.');
+    .describe('Ticket keys, at most 200; or give query.');
 /** ORB-2054 - the target set can be an OQL query instead of a key list. */
 const QUERY_SOURCE = z.string().min(1).max(8000).optional()
-    .describe('OQL selecting the tickets instead of ticketKeys (orboto_query grammar, your ACL); at most 200 matches.');
+    .describe('OQL instead of ticketKeys (your ACL), at most 200 matches.');
 const QUERY_PROJECT = z.string().optional()
-    .describe('Project key that scopes `query` (prepended as project = KEY).');
+    .describe('Project key scoping `query`.');
 /** Matches per call the MCP loop will process; above that the server-side bulk route is the right tool. */
 export const BULK_QUERY_MAX = 200;
 /** Resolve `query` to ticket keys through POST /query, paging until the cap. */

package/dist/tools/checklist-writes.js

@@ -74,7 +74,7 @@ function makeToggleHandler(client, completed) {
 const toggleInputSchema = z.object({
     ticketKey: z.string().min(3),
     item: z.union([
-        z.number().int().min(1).describe('1-based index, global across all checklists on this ticket'),
+        z.number().int().min(1).describe('1-based index across all checklists'),
         z.string().describe('Item UUID - for callers that already have it'),
     ]),
 }).shape;
@@ -169,7 +169,7 @@ export const updateCheckToolConfig = {
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         item: z.union([
-            z.number().int().min(1).describe('1-based index, global across all checklists on this ticket'),
+            z.number().int().min(1).describe('1-based index across all checklists'),
             z.string().describe('Item UUID - for callers that already have it'),
         ]),
         content: z.string().min(1).max(2000).optional().describe('New item text.'),

package/dist/tools/claim.js

@@ -16,7 +16,7 @@ const CATEGORY_TO_LEGACY = {
 };
 export const claimToolConfig = {
     title: 'Claim a ticket (assign self + in_progress + timer)',
-    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.',
+    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. The server attributes the timer to the session of this connection only (ORB-2550): a token that is not its own is refused 403, a session another harness process owns 409.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         override: z.boolean().optional().describe("Spec override; reason required."),
@@ -24,7 +24,7 @@ export const claimToolConfig = {
         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.'),
+        agentSessionToken: z.string().optional().describe('Instance token for bot timers; must be this connection\'s own.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };

package/dist/tools/doc-attachments.js

@@ -39,11 +39,11 @@ export const uploadDocAttachmentToolConfig = {
     title: 'Upload an attachment to a doc page',
     description: 'Upload a file as a doc attachment: returns its Markdown image (or link) line + a stable download URL. Bytes come in as base64 (`contentBase64`) so this works without local FS access on the agent side. Set `embed=true` to also PATCH the doc body to append the Markdown line - useful for dropping a screenshot into a page in one call. MIME / extension policy is enforced server-side: blocked types (HTML, SVG, executables) surface a 415.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         filename: z.string().min(1).describe('Display filename, e.g. "architecture-diagram.png".'),
         contentBase64: z.string().min(1).describe('File content, base64-encoded.'),
         altText: z.string().optional().describe('Alt-text for the Markdown image line. Defaults to filename.'),
-        embed: z.boolean().optional().describe('If true, PATCHes the doc body to append the Markdown line. Idempotent up to duplicate detection - re-running appends another copy.'),
+        embed: z.boolean().optional().describe('Append the Markdown line to the doc body; a re-run appends another copy.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -100,7 +100,7 @@ export const listDocAttachmentsToolConfig = {
     title: 'List attachments on a doc page',
     description: 'Return the doc\'s attachments newest-first, with stable download URLs the agent can hand to the user. Empty list = no attachments.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -139,7 +139,7 @@ export const deleteDocAttachmentToolConfig = {
     title: 'Delete an attachment from a doc page',
     description: 'DESTRUCTIVE - drops the file row + deletes the underlying S3 object. Does NOT rewrite the doc body, so embedded Markdown lines pointing at the deleted URL will surface as broken images / links. Walk those by hand if needed.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         attachmentId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },

package/dist/tools/doc-comments.js

@@ -7,7 +7,7 @@ export const listDocCommentsToolConfig = {
     title: 'List comments on a doc page',
     description: 'Return comments on a doc page, oldest-first so the reply tree reads top-to-bottom. Each row carries the author name + content + resolved state. Cursor-paged - pass `cursor` from the previous call\'s nextCursor to walk older pages.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         limit: z.number().int().min(1).max(100).optional(),
         cursor: z.string().optional(),
     }).shape,
@@ -84,7 +84,7 @@ export const postDocCommentToolConfig = {
     title: 'Post a comment on a doc page (or reply to one)',
     description: 'Add a comment to a doc page. Pass `parentCommentId` to reply (the API flattens reply chains past one level so a reply-of-reply lands as a sibling of the original reply). Optional `anchor` (`{text, before, after}`) attaches the comment to a specific highlight in the body - the frontend uses the surrounding context to re-locate the anchor even after the doc has been edited. Mention a person with the markup `@[Full Name](user:<uuid>)` - the UUIDs come from `orboto_list_users`. The response reports `mentions` (tokens that resolved to a user, who is then notified) and `unresolvedMentions` (tokens that named nobody); a mention is never silently dropped.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         content: z.string().min(1).max(4000),
         parentCommentId: z.string().uuid().optional().describe('Reply to an existing comment.'),
         anchor: z.object({
@@ -136,7 +136,7 @@ export const resolveDocCommentToolConfig = {
     title: 'Mark a doc comment thread as resolved (or reopen it)',
     description: 'Toggle a comment thread\'s resolved state. Pass `resolved=true` to fold the conversation, `resolved=false` to reopen. Always acts on the thread ROOT - resolving from a reply folds the whole conversation, same as the web UI.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         commentId: z.string().uuid(),
         resolved: z.boolean(),
     }).shape,
@@ -163,7 +163,7 @@ export const updateDocCommentToolConfig = {
     title: 'Edit your own doc comment',
     description: 'Edit a doc comment\'s body. Author OR super-admin can edit; everyone else gets a 403. Doc-comments do not carry a revision history today (unlike ticket comments), so the prior content is overwritten in place. A no-op call (same content as before) returns the unchanged row.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         commentId: z.string().uuid(),
         content: z.string().min(1).max(4000),
     }).shape,
@@ -187,7 +187,7 @@ export const deleteDocCommentToolConfig = {
     title: 'Delete a doc comment',
     description: 'DESTRUCTIVE - drops the comment + (via FK cascade) every reply under it. Only the author can delete their own comments; super-admins can delete anyone\'s. Returns success silently; 403 surfaces as an OrbotoApiError.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         commentId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },

package/dist/tools/doc-export.js

@@ -7,7 +7,7 @@ export const exportDocMdToolConfig = {
     title: 'Export a doc page as Markdown',
     description: 'Return the doc body as plain Markdown (text/markdown). Differs from orboto_get_doc.content in that the server-side export endpoint emits the canonical saved body - agents pulling docs to feed into another tool should prefer this over get_doc, which wraps the body in get-doc envelope text + backlinks.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -27,9 +27,9 @@ export function makeExportDocMdHandler(client) {
 }
 export const exportDocPdfToolConfig = {
     title: 'Export a doc page as PDF',
-    description: 'Render the doc page to PDF (Puppeteer-backed PdfService) and return the bytes as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
+    description: 'Render the doc page to PDF and return it as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };

package/dist/tools/doc-revisions.js

@@ -7,7 +7,7 @@ export const listDocRevisionsToolConfig = {
     title: 'List the revision history of a doc page',
     description: 'Return saved revisions for a doc page, newest-first. Each row carries the revision id, title at snapshot time, editor user id, and editedAt timestamp; the body content is NOT in this list (use orboto_get_doc_revision to fetch one). Cursor-paged - pass `cursor` to walk older pages.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         limit: z.number().int().min(1).max(100).optional().describe('Page size. Defaults to API default (25).'),
         cursor: z.string().optional().describe('Opaque cursor from a previous call\'s nextCursor.'),
     }).shape,
@@ -56,7 +56,7 @@ export const getDocRevisionToolConfig = {
     title: 'Get a single doc revision',
     description: 'Return the full content + title of one saved revision. Use this to diff against the current doc before deciding whether to restore.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         revisionId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -85,7 +85,7 @@ export const restoreDocRevisionToolConfig = {
     title: 'Restore a doc page to a saved revision',
     description: 'Roll back the doc to the saved revision. The API snapshots the CURRENT body to a fresh revision row first, so the restore itself is also undoable. Returns the post-restore doc state.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         revisionId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },

package/dist/tools/docs.js

@@ -152,7 +152,7 @@ export const updateDocSpaceToolConfig = {
         description: z.string().nullish(),
         icon: z.string().nullish(),
         isPublic: z.boolean().optional().describe('DEPRECATED - use guestsVisible.'),
-        visibility: z.enum(['workspace', 'project_members', 'restricted']).optional().describe('Space-level read gate: workspace = every internal member, project_members = project members whose role grants doc:view (project spaces only), restricted = standalone allowlist. Requires manage rights.'),
+        visibility: z.enum(['workspace', 'project_members', 'restricted']).optional().describe('Read gate: workspace = every internal member, project_members = members with doc:view (project spaces), restricted = allowlist. Needs manage rights.'),
         guestsVisible: z.boolean().optional().describe('Explicit guest (external user) opt-in. Requires manage rights.'),
         memberIds: z.array(z.string().uuid()).optional().describe('Replaces the restricted-space allowlist. Requires manage rights.'),
         slug: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/).optional(),
@@ -276,7 +276,7 @@ export const createDocToolConfig = {
     inputSchema: z.object({
         spaceId: z.string().min(1).describe('Target doc space - key (e.g. ORB-S1), name, or UUID. Discover via orboto_list_doc_spaces.'),
         title: z.string().min(1).max(255),
-        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Empty or omitted: a blank page. Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown = neutral, label <= 24 chars).'),
+        content: z.string().optional().describe('Markdown (GFM); omitted: a blank page. Pills: `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown = neutral, label <= 24 chars).'),
         parentDocId: z.string().uuid().nullable().optional().describe('Nest under another doc.'),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional().describe('Defaults to "workspace".'),
         icon: z.string().nullish().describe('Single emoji shown in the tree.'),
@@ -313,9 +313,9 @@ export const updateDocToolConfig = {
     title: 'Update a doc page',
     description: 'Patch a doc; content is appended unless replace. ORB-2468: title, visibility, parent and icon are set as given; content goes in as a new section (identical content twice is a no-op); replace: true replaces the whole page and the answer names the revision holding the previous body plus its restore command. Every body or title change snapshots a revision; orboto_restore_doc_revision rolls back. For one passage or section use orboto_edit_doc.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         title: z.string().min(1).max(255).optional(),
-        content: z.string().optional().describe('Markdown to append (with replace: the whole body). Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown reads as neutral, label <= 24 chars).'),
+        content: z.string().optional().describe('Markdown to append (with replace: the whole body). Pills: `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown = neutral, label <= 24 chars).'),
         replace: z.boolean().optional(),
         parentDocId: z.string().uuid().nullable().optional(),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional(),
@@ -368,7 +368,7 @@ export const deleteDocToolConfig = {
     title: 'Delete a doc page',
     description: 'DESTRUCTIVE - removes the page from the tree. Revisions are NOT auto-cascaded; the API keeps them so an admin could in principle resurrect from history, but the page itself is gone from listings. System-generated primer docs refuse deletion (the regenerator re-creates them). Returns success silently; 404 is also silent (idempotent).',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
@@ -386,9 +386,9 @@ export const moveDocToolConfig = {
     title: 'Move a doc page (reparent / reorder / cross-space)',
     description: 'Reparent a doc, change its sort order, or move it into a different space. All three target fields are optional but at least one must be supplied. Distinct from orboto_update_doc\'s parentDocId because the API endpoint emits a different WS event for the tree-rebuild path connected clients care about.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         parentDocId: z.string().uuid().nullable().optional().describe('null = top-level; UUID = nest under that doc.'),
-        spaceId: z.string().uuid().optional().describe('Move into a different space. Caller must be member of both; the parent must live in the target space, and without parentDocId the doc lands at the top level.'),
+        spaceId: z.string().uuid().optional().describe('Target space (member of both); the parent must be in it, else the doc lands at the top level.'),
         sortOrder: z.number().int().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },

package/dist/tools/get-timer.js

@@ -4,7 +4,7 @@
 import { z } from 'zod';
 export const getTimerToolConfig = {
     title: 'Get current timer',
-    description: 'Return the caller\'s currently-running stopwatch (or null if no timer is active). The lane is resolved from this session\'s instance token, so a timer started by `orboto_claim` / `orboto_timer_start` in the same checkout reads back (ORB-2137); `laneFallback: true` means the timer was matched as the account\'s only running one because this instance\'s lane was empty - another instance started it.',
+    description: 'Return the caller\'s currently-running stopwatch (or null if no timer is active). The lane is resolved from this session\'s instance token, so a timer started by `orboto_claim` / `orboto_timer_start` in the same checkout reads back (ORB-2137); `laneFallback: true` means the timer was matched as the account\'s only running one because this instance\'s lane was empty - another instance started it. The answer names who runs the timer and its agent session (ORB-2550); the fallback never takes the timer of a session another harness process owns (409 `errors.time.timer_of_other_session` on stop).',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -28,6 +28,7 @@ export function makeGetTimerHandler(client) {
             `Timer ${isPaused ? 'paused' : 'running'} on ${ticketLabel}`,
             `Elapsed: ${minutes} min (${totalSeconds}s total)`,
             `Started: ${timer.startedAt}`,
+            `Owner: ${timer.userFullName ?? timer.userEmail ?? timer.userId}${timer.agentSessionLabel ? `, session ${timer.agentSessionLabel}` : ', no agent session'}`,
             isPaused ? `Paused: ${timer.pausedAt}` : null,
             timer.laneFallback ? 'Matched via the single-active-timer fallback - another instance started it.' : null,
             timer.description ? `Note: ${timer.description}` : null,
@@ -46,6 +47,10 @@ export function makeGetTimerHandler(client) {
                     totalSeconds,
                     paused: isPaused,
                     laneFallback: timer.laneFallback === true,
+                    userId: timer.userId,
+                    userEmail: timer.userEmail ?? null,
+                    agentSessionId: timer.agentSessionId ?? null,
+                    agentSessionLabel: timer.agentSessionLabel ?? null,
                 },
             },
         };

package/dist/tools/identity.js

@@ -4,7 +4,7 @@
 import { z } from 'zod';
 export const whoamiToolConfig = {
     title: 'Show the authenticated MCP principal',
-    description: 'Return the authenticated user record `{id, email, fullName, isBot, workspaceLocale}` for the API key this server runs with. Useful for debugging which credential / bot identity is in use when multiple MCP configs are wired to different `orb_*` keys. **`workspaceLocale` (ORB-989)** is the language the workspace expects tickets / comments / docs in - check it before a mass-create so you write in the right language from the start instead of relying on the after-the-fact language-mismatch warning.',
+    description: 'Return the authenticated user record `{id, email, fullName, isBot, workspaceLocale}` for the API key this server runs with. Useful for debugging which credential / bot identity is in use when multiple MCP configs are wired to different `orb_*` keys. **`workspaceLocale` (ORB-989)** is the language the workspace expects tickets / comments / docs in - check it before a mass-create so you write in the right language from the start instead of relying on the after-the-fact language-mismatch warning. **`agentSession` (ORB-2550)** is the agent session every write of this connection is attributed to, null when the server knows none for its instance token; `foreign: true` means another harness process owns it, so writes carry no session and timers and work sessions are refused until this process has an instance token (`ORBOTO_AGENT_SESSION`) or a profile of its own.',
     inputSchema: z.object({}).shape,
     outputSchema: z.object({
         id: z.string(),
@@ -13,6 +13,7 @@ export const whoamiToolConfig = {
         isBot: z.boolean(),
         workspaceLocale: z.string().nullable(),
         actingAuthorizedBy: z.object({ id: z.string(), email: z.string(), fullName: z.string() }).nullable(),
+        agentSession: z.object({ id: z.string(), label: z.string(), harness: z.string().nullable(), pid: z.number().nullable(), foreign: z.boolean() }).nullable(),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -32,6 +33,13 @@ export function makeWhoamiHandler(client) {
         if (me.actingAuthorizedBy) {
             lines.push(`  acting as this bot, authorised by: ${me.actingAuthorizedBy.fullName} <${me.actingAuthorizedBy.email}>`);
         }
+        const session = me.agentSession ?? null;
+        if (session) {
+            lines.push(`  session: ${session.id} (${session.label})${session.foreign ? ` - owned by ${session.harness ?? 'unknown'} pid ${session.pid ?? 0}, another process: writes carry no session, timers and work sessions are refused; give this process an instance token of its own (ORBOTO_AGENT_SESSION=<own value>) or its own identity (orboto profile bind <harness> <profile>); after a restart of the same harness, orboto session-start registers the row again` : ''}`);
+        }
+        else {
+            lines.push('  session: none - the server knows no session for this connection\'s instance token yet');
+        }
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {
@@ -41,6 +49,7 @@ export function makeWhoamiHandler(client) {
                 isBot,
                 workspaceLocale,
                 actingAuthorizedBy: me.actingAuthorizedBy ?? null,
+                agentSession: session,
             },
         };
     };

package/dist/tools/identity.test.js

@@ -39,9 +39,20 @@ describe('orboto_whoami', () => {
             isBot: true,
             workspaceLocale: 'en',
             actingAuthorizedBy: null,
+            agentSession: null,
         });
         expect(res.content[0].text).toContain('agent-e@orboto.io');
     });
+    it('ORB-2550 - names the session the connection writes under, and a session another live process owns', async () => {
+        const session = { id: '0b0c3a1e-7f73-4c55-8a4e-1d0f0f0f0f0f', label: 'mcp-stdio#0b0c3a1e', harness: 'claude-code', pid: 4242, foreign: false };
+        stub([{ json: { id: 'u5', email: 'agent@orboto.io', isBot: true, agentSession: session } }, { json: { id: 'u5', email: 'agent@orboto.io', isBot: true, agentSession: { ...session, foreign: true } } }]);
+        const own = await makeWhoamiHandler(client)();
+        expect(own.structuredContent).toMatchObject({ agentSession: session });
+        expect(own.content[0].text).toContain(`session: ${session.id} (mcp-stdio#0b0c3a1e)`);
+        const foreign = await makeWhoamiHandler(client)();
+        expect(foreign.content[0].text).toContain('owned by claude-code pid 4242, another process: writes carry no session, timers and work sessions are refused; give this process an instance token of its own (ORBOTO_AGENT_SESSION=<own value>)');
+        expect(foreign.content[0].text).toContain('after a restart of the same harness, orboto session-start registers the row again');
+    });
     it('surfaces workspaceLocale in the text output when present (ORB-989)', async () => {
         stub([{ json: { id: 'u4', email: 'agent@orboto.io', fullName: 'Agent', isBot: true, workspaceLocale: 'de' } }]);
         const res = await makeWhoamiHandler(client)();

package/dist/tools/list-git-app-installations.js

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 export const listGitAppInstallationsToolConfig = {
     title: 'List GitHub App installations',
-    description: 'Every GitHub App installation orboto knows (admin:system:read): org/user, install time, suspended state and the project keys allowed to use it.',
+    description: 'Every known GitHub App installation (admin:system:read): account, install time, suspension, allowed project keys.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };

package/dist/tools/phase-b-tools.test.js

@@ -611,4 +611,11 @@ describe('orboto_get_timer', () => {
         expect(sc.timer.paused).toBe(false);
         expect(sc.timer.ticketTitle).toBe('Bug');
     });
+    it('ORB-2550 - names who runs the timer and in which agent session', async () => {
+        const startedAt = new Date().toISOString();
+        stub([{ json: { id: 'tm2', userId: 'u1', ticketId: 't1', startedAt, pausedAt: null, accumulatedSeconds: 0, description: null, userEmail: 'claude@orboto.io', userFullName: 'Claude Agent', agentSessionId: 's-1', agentSessionLabel: 'claude-code#0b0c3a1e' } }]);
+        const res = await makeGetTimerHandler(client)();
+        expect(res.content[0].text).toContain('Owner: Claude Agent, session claude-code#0b0c3a1e');
+        expect(res.structuredContent).toMatchObject({ timer: { userId: 'u1', userEmail: 'claude@orboto.io', agentSessionId: 's-1', agentSessionLabel: 'claude-code#0b0c3a1e' } });
+    });
 });