@orboto/mcp 0.221.3 → 0.222.0

package/dist/tools/agent-coordination.js

@@ -43,9 +43,16 @@ export function makeAgentHeartbeatHandler(client) {
         };
     };
 }
+export function originText(s) {
+    if (!s.origin)
+        return '';
+    const o = s.origin;
+    const where = [o.host ?? 'unknown host', o.repo, o.pid ? `pid ${o.pid}` : null, o.harness, o.client ? `${o.client}${o.clientVersion ? ` ${o.clientVersion}` : ''}` : null].filter(Boolean).join(' ');
+    return ` [${s.state ?? 'live'}] on ${where}${o.startedAt ? ` since ${o.startedAt}` : ''}`;
+}
 export const agentPresenceToolConfig = {
     title: 'Workspace agent presence',
-    description: 'Returns all active orboto agent instances: lane workers/reviewers, inbox and MCP connections, 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. Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, the ticket it works on, and `reconnects` survived under the same id and scope. Check it before dispatching a sub-task so you do not 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.',
+    description: 'Active agent instances. The orboto_who set: lane workers and reviewers, inbox, MCP and runner connections; rows carry kind (agent | human, by credential; isBot is its alias), actsAs, owner, projects, connections, lane, sessionId, userEmail, runtime (clientInfo.name), capabilities, status, current ticket, reconnects, origin (host, repo, pid, client, harness, credential) and state (live | quiet | orphaned | unknown_origin). Operators (admin:agents:read or admin:system:read) see the workspace, others their own sessions and those declared on their projects, a foreign row redacted (redacted: true, no pid, repo, machine, connections, inbox or owner). Check it before dispatching a sub-task. projectKey and kind filter client-side like `orboto agents --project KEY --bots|--humans`.',
     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.'),
@@ -62,7 +69,7 @@ export function filterPresenceRows(rows, args) {
 }
 export function makeAgentPresenceHandler(client) {
     return async (args = {}) => {
-        const all = await client.get('/v1/agent/inventory');
+        const all = (await client.get('/v1/agent/who?include=inventory')).inventory ?? [];
         const sessions = filterPresenceRows(all, args);
         const lines = [];
         if (sessions.length === 0) {
@@ -76,7 +83,7 @@ export function makeAgentPresenceHandler(client) {
                 const work = s.workingOnTicket
                     ? ` · working on [${s.workingOnTicket.projectKey ?? '?'}] ${s.workingOnTicket.key ?? s.workingOnTicket.id} (${s.workingOnTicket.title})`
                     : '';
-                lines.push(`- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${work}; owner: ${s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self')}${s.lane ? `; lane: ${s.lane.name}` : ''}${s.projects.length ? `; projects: ${s.projects.map((p) => p.key).join(', ')}` : ''}${s.connections.length ? `; connections: ${s.connections.map((c) => c.type).join(', ')}` : ''}`);
+                lines.push(`- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${originText(s)}${work}; owner: ${s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self')}${s.lane ? `; lane: ${s.lane.name}` : ''}${s.projects.length ? `; projects: ${s.projects.map((p) => p.key).join(', ')}` : ''}${s.connections.length ? `; connections: ${s.connections.map((c) => c.type).join(', ')}` : ''}`);
             }
         }
         return {
@@ -106,9 +113,26 @@ export function noRecipientText(err) {
         + (live.length ? `Live sessions: ${live.join('; ')}. ` : 'No live session declared the project. ')
         + 'Address one of them, or send again with queue: true and project to keep it until a session declares the project.';
 }
+/** ORB-2542 - the 409 `owner_mismatch` as a tool error naming the owner and both ways on. */
+export function ownerMismatchText(err) {
+    if (err.status !== 409)
+        return null;
+    let body;
+    try {
+        body = JSON.parse(err.body);
+    }
+    catch {
+        return null;
+    }
+    if (body.errorKey !== 'errors.agents.owner_mismatch')
+        return null;
+    const p = body.errorParams ?? {};
+    const text = p.ownerHint?.text ?? `"${p.topic ?? '?'}" belongs to ${p.owner ?? '?'}, not ${p.target ?? '?'}`;
+    return `not sent: ${text}. Send again with route: true to deliver it to ${p.owner ?? 'the owner'}, or forceTarget: true to keep the target.`;
+}
 export const agentNotifyToolConfig = {
-    title: 'Notify another agent / user',
-    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account, each as addressed mail), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it (ORB-2136). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; orboto_who lists them before sending) unless queue: true keeps it in the inbox until a session declares the project (ORB-2264). The answer names routedTo (session, scope or account); routingNote "no session declared KEY" means nothing wakes - escalate instead of assuming delivery (ORB-2263).',
+    title: 'Notify an agent or user',
+    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it. A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session.',
     inputSchema: z.object({
         targetEmail: z.string().email().optional(),
         to: z.string().min(3).max(200).optional(),
@@ -118,9 +142,11 @@ export const agentNotifyToolConfig = {
         outcome: z.string().min(10).max(1000).optional(),
         payload: z.record(z.string(), z.unknown()).optional(),
         threadId: z.string().uuid().optional(),
-        project: z.string().min(1).max(64).optional().describe('Project key or UUID.'),
-        senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref; default: this MCP session.'),
+        project: z.string().min(1).max(64).optional(),
+        senderRef: z.string().min(1).max(128).optional(),
         toSessionRef: z.string().min(1).max(200).optional(),
+        route: z.boolean().optional(),
+        forceTarget: z.boolean().optional(),
     }).shape,
     outputSchema: z.object({
         ok: z.literal(true),
@@ -130,6 +156,7 @@ export const agentNotifyToolConfig = {
         routingNote: z.string().optional(),
         recipients: z.array(z.string()).optional(),
         queued: z.boolean().optional(),
+        owner: z.string().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -178,26 +205,27 @@ export function makeAgentNotifyHandler(client) {
         const senderRef = mcpInstanceToken(args.senderRef, extra);
         let res;
         try {
-            res = await client.post('/v1/agent/notify', { ...args, senderRef }, { instanceToken: mcpInstanceToken(undefined, extra) });
+            res = await client.post('/v1/agent/notify', { ...args, senderRef, ownerCheck: 'refuse' }, { instanceToken: mcpInstanceToken(undefined, extra) });
         }
         catch (err) {
-            const refused = err instanceof OrbotoApiError ? noRecipientText(err) : null;
+            const refused = err instanceof OrbotoApiError ? noRecipientText(err) ?? ownerMismatchText(err) : null;
             if (refused)
                 return { isError: true, content: [{ type: 'text', text: refused }] };
             throw err;
         }
-        const who = args.to ?? args.targetEmail ?? '?';
+        const who = res.ownerHint?.routed ? res.ownerHint.ownerAddress : args.to ?? args.targetEmail ?? '?';
         const recipients = (res.recipients ?? []).map((r) => r.label);
         const target = recipients.length > 1 ? recipients.join(', ') : res.toSessionId ? `${who} session ${res.toSessionId.slice(0, 8)}` : who;
         const routedTo = res.routedTo ?? (res.toSessionId ? 'session' : 'account');
         const note = res.routingNote ? ` - ${res.routingNote}` : '';
         return {
-            content: [{ type: 'text', text: `${res.queued ? 'queued for' : 'notified'} ${target} (message ${res.messageId}, routed to ${routedTo}${note})${res.hint ? `\nhint: ${res.hint}` : ''}` }],
+            content: [{ type: 'text', text: `${res.queued ? 'queued for' : 'notified'} ${target} (message ${res.messageId}, routed to ${routedTo}${note})${res.ownerHint?.routed ? `\nrouted to the owner of "${res.ownerHint.topic}" instead of ${res.ownerHint.target}` : ''}${res.hint ? `\nhint: ${res.hint}` : ''}` }],
             structuredContent: {
                 ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null, routedTo,
                 ...(res.routingNote ? { routingNote: res.routingNote } : {}),
                 ...(recipients.length ? { recipients } : {}),
                 ...(res.queued ? { queued: true } : {}),
+                ...(res.ownerHint?.routed ? { owner: res.ownerHint.ownerAddress } : {}),
             },
         };
     };

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

@@ -44,47 +44,49 @@ describe('orboto_agent_heartbeat', () => {
     });
 });
 describe('orboto_agent_presence', () => {
-    it('GETs /v1/agent/inventory and renders one line per session', async () => {
+    it('GETs the inventory through /v1/agent/who and renders one line per session with its origin and state (ORB-2544)', async () => {
         stub([{
-                json: [
-                    {
-                        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: [], connections: [], workSessions: [],
-                        sessionId: '00000000-0000-0000-0000-000000000010',
-                        status: 'working',
-                        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(),
-                        createdAt: new Date().toISOString(),
-                    },
-                    {
-                        userId: '00000000-0000-0000-0000-000000000002',
-                        userEmail: 'bot@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: 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,
-                        capabilities: [],
-                        clientInfo: { name: 'dispatcher-daemon' },
-                        lastSeenAt: new Date().toISOString(),
-                        createdAt: new Date().toISOString(),
-                    },
-                ],
+                json: { sessions: [], inventory: [
+                        {
+                            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: [], connections: [], workSessions: [],
+                            sessionId: '00000000-0000-0000-0000-000000000010',
+                            status: 'working',
+                            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(),
+                            createdAt: new Date().toISOString(),
+                        },
+                        {
+                            userId: '00000000-0000-0000-0000-000000000002',
+                            userEmail: 'bot@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: 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,
+                            capabilities: [],
+                            clientInfo: { name: 'dispatcher-daemon' },
+                            lastSeenAt: new Date().toISOString(),
+                            createdAt: new Date().toISOString(),
+                            origin: { host: 'build-host', repo: 'sample-repo', pid: 4242, client: 'orboto-cli', clientVersion: '1.2.3', harness: 'claude-code', startedAt: null },
+                            state: 'orphaned',
+                        },
+                    ] },
             }]);
         const handler = makeAgentPresenceHandler(client);
         const result = await handler();
         const text = result.content[0].text;
         expect(text).toContain('2 active session(s)');
         expect(text).toContain('Alice <alice@x.test> (claude-code, instance 00000000-0000-0000-0000-000000000010) - working · working on [ORB] ORB-42');
-        expect(text).toContain('bot@x.test <bot@x.test> (dispatcher-daemon, instance 00000000-0000-0000-0000-000000000011) - idle; owner: Alice');
-        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/inventory');
+        expect(text).toContain('bot@x.test <bot@x.test> (dispatcher-daemon, instance 00000000-0000-0000-0000-000000000011) - idle [orphaned] on build-host sample-repo pid 4242 claude-code orboto-cli 1.2.3; owner: Alice');
+        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory');
         expect(result.structuredContent.sessions).toHaveLength(2);
     });
     it('handles an empty workspace gracefully', async () => {
-        stub([{ json: [] }]);
+        stub([{ json: { sessions: [], inventory: [] } }]);
         const handler = makeAgentPresenceHandler(client);
         const result = await handler();
         expect(result.content[0].text).toBe('No active agent sessions in the workspace.');
@@ -97,9 +99,9 @@ describe('orboto_agent_presence', () => {
     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() }]);
+            stub([{ json: { sessions: [], inventory: presenceRows() } }]);
             const result = await handler(args);
-            expect(vi.mocked(fetch).mock.calls.at(-1)?.[0]).toBe('https://orboto.example.com/v1/agent/inventory');
+            expect(vi.mocked(fetch).mock.calls.at(-1)?.[0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory');
             return result.structuredContent.sessions.map((s) => s.sessionId.slice(-2));
         };
         expect(await ids({})).toEqual(['10', '11', '12']);
@@ -110,12 +112,12 @@ describe('orboto_agent_presence', () => {
         expect(await ids({ projectKey: 'NONE' })).toEqual([]);
     });
     it('says when a filter matched nothing but the workspace is not empty', async () => {
-        stub([{ json: presenceRows() }]);
+        stub([{ json: { sessions: [], inventory: 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() }]);
+        stub([{ json: { sessions: [], inventory: presenceRows() } }]);
         const text = (await makeAgentPresenceHandler(client)({ kind: 'agent' })).content[0].text;
         expect(text).toContain('2 active session(s)');
         expect(text).toContain('owner: Alice; lane: worker-1; projects: ACME, ORB; connections: lane, live_events');
@@ -228,6 +230,22 @@ describe('orboto_messages (ORB-1742 self-echo exclusion)', () => {
         expect(urls[0]).toContain('excludeRef=mcp-abc123');
         await handler({ includeOwnSends: true }, { sessionId: 'abc123' });
         expect(urls[1]).not.toContain('excludeRef');
+        expect(urls[1]).toContain('includeOwn=true');
+    });
+    it('ORB-2547: an own send renders as sent with the recipient session, its delivered/read state and the thread', async () => {
+        const party = (label, sessionId) => ({ userId: 'u', email: 'e', sessionId, role: null, label });
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+            ok: true, status: 200, statusText: 'OK',
+            json: async () => ({ sessionId: '11111111-1111-4111-8111-111111111111', messages: [
+                    { id: '22222222-2222-4222-8222-222222222222', fromUserId: 'u', toUserId: 'v', from: party('me (11111111)', '11111111'), to: party('peer (44444444)', '44444444'), kind: 'complete', subject: 'done', payload: null, threadId: '33333333-3333-4333-8333-333333333333', projectKey: 'ALPHA', createdAt: '2026-10-16T10:00:00Z', deliveredAt: '2026-10-16T10:00:05Z', readAt: null, dismissed: null, own: true },
+                ] }),
+            text: async () => '',
+        }));
+        const result = await makeAgentMessagesHandler(client)({ includeOwnSends: true }, { sessionId: 'abc123' });
+        const text = result.content[0].text;
+        expect(text).toContain('[sent] delivered 2026-10-16T10:00:05Z, unread [complete] [ALPHA] done (from me (11111111) to peer (44444444)');
+        expect(text).toContain('thread 33333333-3333-4333-8333-333333333333');
+        expect(result.structuredContent.messages[0]).toMatchObject({ own: true, deliveredAt: '2026-10-16T10:00:05Z', threadId: '33333333-3333-4333-8333-333333333333' });
     });
 });
 describe('ORB-2136 - session addressing', () => {

package/dist/tools/agent-messages.js

@@ -14,16 +14,16 @@ const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId:
 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, all:true is the account view with every message in full (ORB-2136). By default it lists the newest 10 unread, newest first, each as a header plus the first 300 payload characters, then the line `N unread, M older than 7 days`; limit and since (ISO time or message id) narrow it (ORB-2502). Before orboto_session_start only account mail is listed; register to see mail addressed to your session (ORB-2347). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss is the third answer: 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 reaches that instance).',
+    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).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
-            .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),
+            .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}.'),
         all: z.boolean().default(false),
         limit: z.number().int().min(1).max(200).optional(),
         since: z.string().optional(),
         project: z.string().min(1).max(64).optional().describe('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.'),
+        ackIds: z.array(z.string().uuid()).max(200).optional(),
         dismiss: z.object({
             ids: z.array(z.string().uuid()).min(1).max(200),
             reason: z.enum(['not_mine', 'obsolete', 'duplicate']),
@@ -45,7 +45,9 @@ export const agentMessagesToolConfig = {
             threadId: z.string().nullable(),
             projectKey: z.string().nullable(),
             createdAt: z.string(),
+            deliveredAt: z.string().nullable().optional(),
             readAt: z.string().nullable(),
+            own: z.boolean().optional(),
             dismissed: z.object({
                 reason: z.string(), note: z.string().nullable(), duplicateOf: z.string().nullable(), createdAt: z.string(),
             }).nullable(),
@@ -66,6 +68,12 @@ function compactLines(m, header) {
         ...(rest > 0 ? [`  ... ${rest} more characters (all:true prints everything)`] : []),
     ];
 }
+/** ORB-2547 - an own send's state at the recipient. */
+function sentState(m) {
+    if (m.readAt)
+        return `read ${m.readAt}`;
+    return m.deliveredAt ? `delivered ${m.deliveredAt}, unread` : 'not delivered yet';
+}
 export function makeAgentMessagesHandler(client) {
     return async (args, extra) => {
         if (args.messageWork) {
@@ -103,10 +111,12 @@ export function makeAgentMessagesHandler(client) {
         if (args.project)
             q.set('project', args.project);
         const instanceToken = mcpInstanceToken(undefined, extra);
-        if (!args.includeOwnSends)
+        if (args.includeOwnSends)
+            q.set('includeOwn', 'true');
+        else
             q.set('excludeRef', instanceToken);
         const { messages, sessionId, counts } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
-        const header = (m) => `[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${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 header = (m) => `${m.own ? `[sent] ${sentState(m)} ` : ''}[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${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)}` : ''}`]));
@@ -130,6 +140,7 @@ export function makeAgentMessagesHandler(client) {
                     id: m.id, fromUserId: m.fromUserId, from: m.from, to: m.to, kind: m.kind, subject: m.subject,
                     payload: compact ? null : m.payload, threadId: m.threadId, projectKey: m.projectKey ?? null,
                     createdAt: m.createdAt, readAt: m.readAt, dismissed: m.dismissed ?? null,
+                    ...(m.own ? { own: true, deliveredAt: m.deliveredAt ?? null } : {}),
                 })),
                 acked,
                 dismissed: dismissedCount,

package/dist/tools/agent-who.js

@@ -1,14 +1,18 @@
 /** 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';
 export const agentWhoToolConfig = {
-    title: 'Who can receive 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.',
+    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).',
     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(),
     }).shape,
-    outputSchema: z.object({ sessions: z.array(z.record(z.string(), z.unknown())) }).shape,
+    outputSchema: z.object({ sessions: z.array(z.unknown()), owner: z.unknown().optional() }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
 /** One directory row as a line: address, account, session, projects, channel, ticket. */
@@ -16,20 +20,31 @@ export function whoLine(s) {
     const address = s.addresses.join(', ') || (s.role ? `${s.role} (no project)` : 'no scope');
     const channel = s.channel.announced ? `${s.channel.announced}${s.channel.online ? ' online' : ' offline'}` : 'no channel';
     const ticket = s.currentTicket ? `; on ${s.currentTicket.key ?? s.currentTicket.title}` : '';
-    const host = s.host ? `, host ${s.host}` : '';
-    return `- ${address} - ${s.email} session ${s.shortId}${host}, ${s.status}, ${channel}, last seen ${s.lastSeenAt}${ticket}`;
+    const host = s.origin ? originText(s) : s.host ? `, host ${s.host}` : '';
+    const shared = s.sharedAddresses?.length ? `; also held by another live session: ${s.sharedAddresses.join(', ')}` : '';
+    return `- ${address} - ${s.email} session ${s.shortId}${host}, ${s.status}, ${channel}, last seen ${s.lastSeenAt}${ticket}${shared}`;
 }
 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 ownerLines = args.for
+            ? [res.owner ? `Owner:\n${ownerLine(res.owner)}` : `No entry in the responsibility map matches "${args.for}".`]
+            : [];
         const lines = res.sessions.length
-            ? [`${res.sessions.length} live session(s):`, ...res.sessions.map(whoLine)]
-            : ['No live session matches - a request sent now answers no_recipient unless it is queued.'];
-        return { content: [{ type: 'text', text: lines.join('\n') }], structuredContent: { sessions: res.sessions } };
+            ? [...ownerLines, `${res.sessions.length} live session(s):`, ...res.sessions.map(whoLine)]
+            : [...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.'];
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: { sessions: res.sessions, ...(args.for ? { owner: (res.owner ?? null) } : {}) },
+        };
     };
 }

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

@@ -31,4 +31,16 @@ describe('orboto_who', () => {
     it('ORB-2465: names the host a live notice filters on', () => {
         expect(whoLine({ ...entry, host: 'build-host-a' })).toContain('session f072e1c5, host build-host-a, working');
     });
+    it('ORB-2544: prints origin, state and a shared address, and passes the state filter', async () => {
+        const line = whoLine({ ...entry, state: 'orphaned', sharedAddresses: ['integrator@ORB'], origin: { host: 'build-host', repo: 'sample-repo', pid: 4242, client: 'orboto-cli', clientVersion: '1.2.3', harness: 'claude-code', startedAt: '2026-10-16T08:00:00.000Z' } });
+        expect(line).toContain('session f072e1c5 [orphaned] on build-host sample-repo pid 4242 claude-code orboto-cli 1.2.3 since 2026-10-16T08:00:00.000Z, working');
+        expect(line).toContain('also held by another live session: integrator@ORB');
+        const urls = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+            urls.push(String(url));
+            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');
+    });
 });

package/dist/tools/check-similar.js

@@ -3,7 +3,7 @@
  */
 import { z } from 'zod';
 import { trimSimilarEntries } from './similar-projection.js';
-import { resolveProjectByKey, resolveTicketByKey } from './shared.js';
+import { resolveProjectByKey, resolveTicketByKey, SEMANTIC_DEGRADED_LINE } from './shared.js';
 export const checkSimilarToolConfig = {
     title: 'Check for similar tickets before creating',
     description: 'Run the duplicate check against a proposed title + description without creating anything. The pipeline is tsvector plus an AI-embedding rerank when configured. Returns up to `limit` candidates ranked by similarity. Use this BEFORE `orboto_create_ticket` when you want to confirm a feature is not already tracked - if a high-similarity candidate exists, prefer to comment on / claim / extend it instead of opening a new ticket. Empty result = safe to create. `orboto_create_ticket` runs the same check after the fact and surfaces `similarWarnings` in its response, so this tool is optional but cheaper than a create-then-close round trip. Only an AI-embedding candidate carries an absolute similarity; a full-text candidate prints as "text match" without a percentage (its rank is relative, so the best text match always scores 1.000) and can never trigger the hard duplicate-block, and neither can a match against a CLOSED ticket (ORB-2185). An empty result from a LONG, solution-framed title is weak evidence - detection ranks by term co-occurrence, so also probe with a single distinctive STABLE token (file/component/error-string fragment) and the SYMPTOM wording, not just your intended fix.',
@@ -43,7 +43,8 @@ export function makeCheckSimilarHandler(client) {
             : strong
                 ? `HIGH-SIMILARITY MATCH FOUND - review [${strong.ticketKey ?? strong.id.slice(0, 8)}] "${strong.title}" before creating; this may already be tracked.`
                 : 'Possible related tickets - review the list and decide whether the new ticket adds distinct scope.';
-        const text = result.candidates.length === 0
+        const degradedNote = result.semanticDegraded ? `(${SEMANTIC_DEGRADED_LINE})\n` : '';
+        const text = degradedNote + (result.candidates.length === 0
             ? `${recommendation} (match mode: ${result.mode})`
             : [
                 recommendation,
@@ -55,12 +56,13 @@ export function makeCheckSimilarHandler(client) {
                     const rel = c.relation ? ` (related: ${c.relation})` : '';
                     return `  - ${key}${status} (${score})${rel}: ${c.title}`;
                 }),
-            ].join('\n');
+            ].join('\n'));
         return {
             content: [{ type: 'text', text }],
             structuredContent: {
                 similar: trimSimilarEntries(result.candidates),
                 mode: result.mode,
+                semanticDegraded: result.semanticDegraded ?? false,
                 recommendation,
             },
         };

package/dist/tools/doc-edits.js

@@ -6,7 +6,7 @@
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { resolveDocId } from './docs.js';
-import { resolveProjectByKey } from './shared.js';
+import { resolveProjectByKey, SEMANTIC_DEGRADED_LINE } from './shared.js';
 /** Turn a 409 from POST /docs/:id/edits into a clear, non-throwing tool
  *  result the model can act on. Returns null for any non-409 so the caller
  *  rethrows (a genuine transport/permission failure should still surface). */
@@ -100,10 +100,11 @@ export function makeSearchDocsHandler(client) {
         if (input.limit)
             qs.set('limit', String(input.limit));
         const res = await client.get(`/docs/search?${qs.toString()}`);
+        const degradedNote = res.semanticDegraded ? `(${SEMANTIC_DEGRADED_LINE})\n` : '';
         if (res.items.length === 0) {
             return {
-                content: [{ type: 'text', text: `No docs matched "${input.q}".` }],
-                structuredContent: { items: [], total: 0 },
+                content: [{ type: 'text', text: `${degradedNote}No docs matched "${input.q}".` }],
+                structuredContent: { items: [], total: 0, semanticDegraded: res.semanticDegraded ?? false },
             };
         }
         const lines = res.items.map((h) => {
@@ -112,7 +113,7 @@ export function makeSearchDocsHandler(client) {
             return `- ${h.title} (${h.docKey ?? h.id})${anchor}${where}\n    ${h.snippet.replace(/\s+/g, ' ').trim()}`;
         });
         return {
-            content: [{ type: 'text', text: lines.join('\n') }],
+            content: [{ type: 'text', text: degradedNote + lines.join('\n') }],
             structuredContent: {
                 items: res.items.map((h) => ({
                     id: h.id,
@@ -129,6 +130,7 @@ export function makeSearchDocsHandler(client) {
                     url: h.url,
                 })),
                 total: res.total,
+                semanticDegraded: res.semanticDegraded ?? false,
             },
         };
     };

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

@@ -0,0 +1,81 @@
+/**
+ * ORB-2468 - the skill wrapper's `doc edit` appends content unless --replace,
+ * a replace prints the replaced revision and restore command, `doc restore`
+ * posts the revision restore.
+ */
+import { expect, it } from 'vitest';
+import { cp, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const DOC = 'd0c00000-2222-4222-8222-222222222222';
+const REV = 'bbbbbbbb-0000-4000-8000-000000000000';
+it('doc edit appends by default, --replace names the replaced revision, doc restore posts the restore', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'orboto-2468-wrapper-'));
+    const requests = [];
+    const server = createServer(async (req, res) => {
+        let raw = '';
+        for await (const chunk of req)
+            raw += String(chunk);
+        const url = req.url ?? '';
+        requests.push({ method: req.method ?? '', url, body: raw ? JSON.parse(raw) : {} });
+        res.setHeader('Content-Type', 'application/json');
+        const row = { id: DOC, docKey: 'ORB-D7', title: 'Runbook', webUrl: 'https://orboto.example/docs/ORB-D7' };
+        if (req.method === 'POST' && url === '/docs/ORB-D7/append-section')
+            res.end(JSON.stringify({ appended: true }));
+        else if (req.method === 'PATCH' && url === '/docs/ORB-D7')
+            res.end(JSON.stringify({ ...row, replaced: { docId: DOC, revisionId: REV, restoreCommand: `orboto doc restore ORB-D7 ${REV}` } }));
+        else if (req.method === 'POST' && url === `/docs/ORB-D7/revisions/${REV}/restore`)
+            res.end(JSON.stringify(row));
+        else {
+            res.statusCode = 404;
+            res.end(JSON.stringify({ error: `unexpected ${req.method} ${url}` }));
+        }
+    });
+    try {
+        await mkdir(join(dir, 'skills/orboto'), { recursive: true });
+        await cp(new URL('../../../../skills/orboto/scripts', import.meta.url), join(dir, 'skills/orboto/scripts'), { recursive: true });
+        await new Promise((ok) => server.listen(0, '127.0.0.1', ok));
+        const address = server.address();
+        if (!address || typeof address === 'string')
+            throw new Error('Fixture address missing');
+        const origin = `http://127.0.0.1:${address.port}`;
+        const guard = join(dir, 'network.mjs');
+        await writeFile(guard, `const original = globalThis.fetch; globalThis.fetch = (input, init) => { if (new URL(input).origin !== ${JSON.stringify(origin)}) throw new Error('Fixture refused nonlocal request'); return original(input, init); };`);
+        const run = (args) => new Promise((ok, no) => {
+            const child = spawn(process.execPath, ['--import', guard, join(dir, 'skills/orboto/scripts/orboto.mjs'), ...args], {
+                cwd: dir, env: { ...process.env, ORBOTO_PROFILE: '', ORBOTO_BASE_URL: origin, ORBOTO_TOKEN: 'orb_fixture', ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' },
+                timeout: 20_000,
+            });
+            let out = '', err = '';
+            child.stdout.on('data', (chunk) => { out += chunk.toString(); });
+            child.stderr.on('data', (chunk) => { err += chunk.toString(); });
+            child.on('error', no);
+            child.on('close', (code) => ok({ code, out, err }));
+            child.stdin.end('');
+        });
+        const appended = await run(['doc', 'edit', 'ORB-D7', '--content', 'new fact']);
+        expect(appended.code, appended.err).toBe(0);
+        expect(requests.at(-1)).toMatchObject({ method: 'POST', url: '/docs/ORB-D7/append-section', body: { content: 'new fact' } });
+        expect(requests.some((r) => r.method === 'PATCH')).toBe(false);
+        expect(appended.err).toContain('Appended to doc ORB-D7');
+        const replaced = await run(['doc', 'edit', 'ORB-D7', '--replace', '--content', 'whole new body']);
+        expect(replaced.code, replaced.err).toBe(0);
+        expect(requests.at(-1)).toMatchObject({ method: 'PATCH', url: '/docs/ORB-D7', body: { content: 'whole new body', replace: true } });
+        expect(replaced.err).toContain(REV);
+        expect(replaced.err).toContain(`orboto doc restore ORB-D7 ${REV}`);
+        const refused = await run(['doc', 'edit', 'ORB-D7', '--replace', '--old', 'a', '--new', 'b']);
+        expect(refused.code).toBe(2);
+        const restored = await run(['doc', 'restore', 'ORB-D7', REV]);
+        expect(restored.code, restored.err).toBe(0);
+        expect(requests.at(-1)).toMatchObject({ method: 'POST', url: `/docs/ORB-D7/revisions/${REV}/restore` });
+        expect(restored.err).toContain('Restored doc ORB-D7');
+    }
+    finally {
+        server.closeAllConnections();
+        if (server.listening)
+            await new Promise((ok, no) => server.close((err) => err ? no(err) : ok()));
+        await rm(dir, { recursive: true, force: true });
+    }
+}, 60_000);

package/dist/tools/docs-ai.js

@@ -2,6 +2,7 @@
  * ORB-799 - docs-AI surface (ask + ingest).
  */
 import { z } from 'zod';
+import { SEMANTIC_DEGRADED_LINE } from './shared.js';
 export const askDocsToolConfig = {
     title: 'Ask a question against the wiki (RAG)',
     description: 'Run a natural-language question against the wiki via the workspace\'s RAG pipeline. Returns an `answer` (Markdown) + `citations` array `[{index, title, link, spaceName}]`. The model is the workspace\'s configured AI provider; retrieval requires the embedding provider too - call `orboto_ai_status` to verify both before relying on this. Restrict to a single doc space with `spaceId` when scoping a query (e.g. "only the runbooks space"). Latency is dominated by retrieval + LLM round-trip; expect 2-10s.',
@@ -29,6 +30,8 @@ export function makeAskDocsHandler(client) {
         if (res.abstained)
             lines.push('', '(abstained: no claim in the answer could be tied to a retrieved doc - treat as "not in the docs", do not guess)');
         lines.push('', `(retrieval mode: ${res.mode})`);
+        if (res.semanticDegraded)
+            lines.push(`(${SEMANTIC_DEGRADED_LINE})`);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {
@@ -36,6 +39,7 @@ export function makeAskDocsHandler(client) {
                 citations: res.citations,
                 mode: res.mode,
                 abstained: res.abstained ?? false,
+                semanticDegraded: res.semanticDegraded ?? false,
             },
         };
     };