@orboto/mcp 0.221.0 → 0.221.11

package/dist/tools/docs.js

@@ -4,7 +4,7 @@
  * @see ORB-1004, ORB-1015, ORB-912, ORB-911
  */
 import { z } from 'zod';
-import { resolveProjectByKey } from './shared.js';
+import { replacedLines, resolveProjectByKey } from './shared.js';
 export const listDocSpacesToolConfig = {
     title: 'List doc spaces',
     description: 'List wiki spaces (global and project-scoped) the caller can read. Each space contains a tree of docs accessed via orboto_get_doc.',
@@ -311,11 +311,12 @@ export function makeCreateDocHandler(client) {
 }
 export const updateDocToolConfig = {
     title: 'Update a doc page',
-    description: 'Patch a doc\'s title / content / visibility / parent / icon. Content-only updates do not require sending the title. Every body or title change snapshots the previous version into the revision history automatically - agents can roll back via orboto_restore_doc_revision (when that tool ships in Phase 5). Re-embeds the doc when content or title change.',
+    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).'),
         title: z.string().min(1).max(255).optional(),
-        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Send the full new content; the API replaces, not appends. 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). Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown reads as neutral, label <= 24 chars).'),
+        replace: z.boolean().optional(),
         parentDocId: z.string().uuid().nullable().optional(),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional(),
         icon: z.string().nullish(),
@@ -328,27 +329,37 @@ export function makeUpdateDocHandler(client) {
         const body = {};
         if (input.title !== undefined)
             body.title = input.title;
-        if (input.content !== undefined)
-            body.content = input.content;
+        if (input.content !== undefined && input.replace)
+            Object.assign(body, { content: input.content, replace: true });
         if (input.parentDocId !== undefined)
             body.parentDocId = input.parentDocId;
         if (input.visibility !== undefined)
             body.visibility = input.visibility;
         if (input.icon !== undefined)
             body.icon = input.icon;
-        if (Object.keys(body).length === 0) {
+        const append = input.content !== undefined && !input.replace;
+        if (Object.keys(body).length === 0 && !append) {
             throw new Error('Pass at least one field to update.');
         }
-        const row = await client.patch(`/docs/${input.docId}`, body);
+        if (append && !input.content.trim())
+            throw new Error('Nothing to append - pass content, or replace: true to replace the whole page.');
+        const row = Object.keys(body).length > 0 ? await client.patch(`/docs/${input.docId}`, body) : null;
+        const appended = append ? (await client.post(`/docs/${input.docId}/append-section`, { content: input.content })).appended : null;
+        const current = row ?? await client.get(`/docs/${input.docId}`);
+        const replaced = row?.replaced ?? null;
+        const how = appended === null ? '' : appended ? '\n  content: appended as a new section' : '\n  content: no change - an identical section is already present';
         return {
-            content: [{ type: 'text', text: `Updated doc: ${row.title}\n  id: ${row.id}\n  updatedAt: ${row.updatedAt}` }],
+            content: [{ type: 'text', text: `Updated doc: ${current.title}\n  id: ${current.id}\n  updatedAt: ${current.updatedAt}${how}${replacedLines(replaced ? [replaced] : [])}` }],
             structuredContent: {
-                id: row.id,
-                title: row.title,
-                spaceId: row.spaceId,
-                parentDocId: row.parentDocId,
-                visibility: row.visibility,
-                updatedAt: row.updatedAt,
+                id: current.id,
+                title: current.title,
+                spaceId: current.spaceId,
+                parentDocId: current.parentDocId,
+                visibility: current.visibility,
+                updatedAt: current.updatedAt,
+                mode: append ? 'append' : input.content !== undefined ? 'replace' : 'fields',
+                appended,
+                replaced,
             },
         };
     };

package/dist/tools/docs.test.js

@@ -232,25 +232,38 @@ describe('orboto_update_doc', () => {
     it('resolves a doc key to the UUID before writing', async () => {
         const calls = stubJSON([
             { json: DOC }, // by-key resolve
-            { json: { ...DOC, content: 'appended' } }, // the PATCH
+            { json: { ...DOC, title: 'Renamed' } }, // the PATCH
         ]);
-        await makeUpdateDocHandler(client)({ docId: 'DOC-4', content: 'appended' });
+        await makeUpdateDocHandler(client)({ docId: 'DOC-4', title: 'Renamed' });
         expect(calls[0]).toMatchObject({ method: 'GET', url: 'https://orboto.example.com/docs/by-key/DOC-4' });
         expect(calls[1]).toMatchObject({
             method: 'PATCH',
             url: `https://orboto.example.com/docs/${DOC.id}`,
-            body: { content: 'appended' },
+            body: { title: 'Renamed' },
         });
     });
-    it('PATCHes only the content field when only content was supplied', async () => {
-        const calls = stubJSON([{ json: { ...DOC, content: 'new body' } }]);
-        await makeUpdateDocHandler(client)({ docId: DOC.id, content: 'new body' });
-        expect(calls[0]).toMatchObject({
-            method: 'PATCH',
-            url: `https://orboto.example.com/docs/${DOC.id}`,
-            body: { content: 'new body' },
-        });
-        expect(Object.keys(calls[0].body)).toEqual(['content']);
+    it('ORB-2468 - appends content as a section and never PATCHes the body without replace', async () => {
+        const calls = stubJSON([{ json: { appended: true } }, { json: DOC }]);
+        const res = await makeUpdateDocHandler(client)({ docId: DOC.id, content: 'new fact' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/docs/${DOC.id}/append-section`, body: { content: 'new fact' } });
+        expect(calls.some((c) => c.method === 'PATCH')).toBe(false);
+        expect(res.structuredContent).toMatchObject({ mode: 'append', appended: true, replaced: null });
+        expect(res.content[0].text).toContain('appended as a new section');
+    });
+    it('ORB-2468 - replace: true PATCHes the whole body and prints the replaced revision with the restore command', async () => {
+        const replaced = { docId: DOC.id, revisionId: 'bbbbbbbb-0000-4000-8000-000000000000', restoreCommand: `orboto doc restore DOC-4 bbbbbbbb-0000-4000-8000-000000000000` };
+        const calls = stubJSON([{ json: { ...DOC, content: 'new body', replaced } }]);
+        const res = await makeUpdateDocHandler(client)({ docId: DOC.id, content: 'new body', replace: true });
+        expect(calls[0]).toMatchObject({ method: 'PATCH', url: `https://orboto.example.com/docs/${DOC.id}`, body: { content: 'new body', replace: true } });
+        expect(res.structuredContent).toMatchObject({ mode: 'replace', replaced });
+        const text = res.content[0].text;
+        expect(text).toContain(replaced.revisionId);
+        expect(text).toContain(replaced.restoreCommand);
+    });
+    it('ORB-2468 - refuses an empty append before hitting the API', async () => {
+        const calls = stubJSON([]);
+        await expect(makeUpdateDocHandler(client)({ docId: DOC.id, content: '  ' })).rejects.toThrow(/Nothing to append/);
+        expect(calls).toHaveLength(0);
     });
     it('refuses the no-op call before hitting the API', async () => {
         const calls = stubJSON([]);

package/dist/tools/embedding-status.js

@@ -42,6 +42,9 @@ export function makeEmbeddingStatusHandler(client) {
             lines.push(`Coverage: ${o.embedded} / ${o.embeddable} embeddable embedded · ${o.pending} pending${o.noContent > 0 ? ` · ${o.noContent} with no embeddable content (excluded)` : ''}`);
             lines.push(`  tickets ${s.coverage.ticket.embedded}/${s.coverage.ticket.embeddable} · comments ${s.coverage.comment.embedded}/${s.coverage.comment.embeddable} · docs ${s.coverage.doc.embedded}/${s.coverage.doc.embeddable} (embeddable)`);
             lines.push(`Circuit breaker: ${s.breaker.tripped ? `TRIPPED - ${s.breaker.lastTrippedReason ?? 'unknown reason'} (${s.breaker.consecutiveFailures} consecutive failures)` : 'ok'}`);
+            if (s.breaker.interactive?.tripped) {
+                lines.push(`Query breaker: TRIPPED until ${s.breaker.interactive.trippedUntil ?? 'unknown'} - ${s.breaker.interactive.lastTrippedReason ?? 'unknown reason'}; search, ask-docs and duplicate checks serve full-text results until it closes.`);
+            }
             if (s.billingGate?.gated) {
                 lines.push(`BILLING GATE: managed AI is paused for billing${s.billingGate.reason ? ` (${s.billingGate.reason})` : ''} since ${s.billingGate.blockedAt ?? 'unknown'}. The workspace admin resolves this in their orboto account; queued items embed automatically after the unblock.`);
             }

package/dist/tools/knowledge.js

@@ -1,6 +1,6 @@
 /** ORB-2225 - the wiki as the agents' knowledge base: ask it first, file durable facts in it. */
 import { z } from 'zod';
-import { mcpInstanceToken } from './shared.js';
+import { mcpInstanceToken, SEMANTIC_DEGRADED_LINE } from './shared.js';
 import { droppedLines } from './wiki.js';
 export const knowledgeAskToolConfig = {
     title: 'Ask the wiki',
@@ -14,7 +14,7 @@ export function makeKnowledgeAskHandler(client) {
         const where = res.spaces.map((s) => s.spaceKey ?? s.spaceName).join(', ');
         const cites = res.citations.map((c) => `[${c.index}] ${c.title} - ${c.link}`).join('\n');
         return {
-            content: [{ type: 'text', text: [res.answer, cites ? `Sources:\n${cites}` : '', `Asked: ${where}.`].filter(Boolean).join('\n\n') }],
+            content: [{ type: 'text', text: [res.answer, cites ? `Sources:\n${cites}` : '', `Asked: ${where}.`, res.semanticDegraded ? `(${SEMANTIC_DEGRADED_LINE})` : ''].filter(Boolean).join('\n\n') }],
             structuredContent: res,
         };
     };

package/dist/tools/knowledge.test.js

@@ -34,6 +34,14 @@ describe('ORB-2225 orboto_knowledge_ask and orboto_knowledge_add', () => {
         expect(textOf(result)).toContain('- Runner (target ACME-D99): unknown_target');
         expect(result.structuredContent).toMatchObject({ droppedOps });
     });
+    it('ORB-2468 - a repeated add returns the first request it answered with, nothing filed again', async () => {
+        const duplicate = { of: 'ingesting', requestedAt: '2026-10-16T08:00:00Z', run: { id: '44444444-0000-4000-8000-000000000000', status: 'pending_review' } };
+        const post = vi.fn().mockResolvedValue({ action: 'duplicate', duplicate, text: 'Already ingesting as source ACME-D9 "Runner notes" in the ACME-S1 wiki (/s/d, run 44444444-0000-4000-8000-000000000000 pending_review); not filed again.', pages: [], source: { id: 'd9', key: 'ACME-D9', title: 'Runner notes', webUrl: '/s/d' }, droppedOps: [] });
+        const result = await makeKnowledgeAddHandler({ post })({ title: 'Runner notes', content: 'x', projectKey: 'ACME' });
+        expect(post).toHaveBeenCalledTimes(1);
+        expect(textOf(result)).toContain('Already ingesting as source ACME-D9');
+        expect(result.structuredContent).toMatchObject({ action: 'duplicate', duplicate });
+    });
     it('both tools carry a title and annotations; ask is read-only, add is not', () => {
         expect(knowledgeAskToolConfig.title).toBeTruthy();
         expect(knowledgeAskToolConfig.annotations.readOnlyHint).toBe(true);

package/dist/tools/list-tickets.js

@@ -1,4 +1,4 @@
-import { TicketSpecStateSchema } from './spec-schemas.js';
+import { TicketListSortSchema, TicketSpecStateSchema } from './spec-schemas.js';
 /**
  * ORB-244 Phase B - `orboto_list_tickets`.
  *
@@ -13,18 +13,18 @@ import { resolveProjectByKey, resolveTicketByKey, ticketLine, agentTicketListRow
 import { resolveMilestoneByNameOrId } from './milestones.js';
 export const listTicketsToolConfig = {
     title: 'List tickets',
-    description: 'List tickets in a project, filtered by status category, milestone or assignee email. unscheduled=true = the backlog (no milestone yet). Up to 50 per call.',
+    description: 'List a project\'s tickets by status category, milestone or assignee email. unscheduled=true = the backlog (no milestone yet). Up to 50 per call.',
     inputSchema: z.object({
-        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        projectKey: z.string().min(1).describe('Project key.'),
         specState: TicketSpecStateSchema.optional(),
         statusCategory: z
             .enum(['todo', 'in_progress', 'in_review', 'done', 'wont_fix'])
             .optional()
-            .describe('One workflow category. Omit for all.'),
+            .describe('One workflow category.'),
         open: z
             .boolean()
             .optional()
-            .describe('true = only todo, in_progress, in_review. Not with statusCategory.'),
+            .describe('true = todo, in_progress, in_review. Not with statusCategory.'),
         milestone: z
             .string()
             .optional()
@@ -32,16 +32,17 @@ export const listTicketsToolConfig = {
         unscheduled: z
             .boolean()
             .optional()
-            .describe('true = only tickets with no milestone. Not with `milestone`.'),
+            .describe('true = no milestone. Not with `milestone`.'),
         assigneeEmail: z
             .string()
             .optional()
-            .describe('Project-member email.'),
+            .describe('Member email.'),
         parentTicketKey: z
             .string()
             .optional()
-            .describe('Only children of this ticket - walks an epic.'),
-        limit: z.number().int().min(1).max(50).default(25).describe('Max rows to return.'),
+            .describe('Children of this ticket.'),
+        sort: TicketListSortSchema.optional().describe('Newest first; default updated.'),
+        limit: z.number().int().min(1).max(50).default(25).describe('Max rows.'),
         verbose: z.boolean().default(false).describe('true = full rows.'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -60,6 +61,8 @@ export function makeListTicketsHandler(client) {
         }
         if (input.open)
             qs.set('open', 'true');
+        if (input.sort)
+            qs.set('sort', input.sort);
         if (input.unscheduled && input.milestone) {
             throw new Error('Pass either `milestone` or `unscheduled: true`, not both.');
         }

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

@@ -8,7 +8,9 @@
  * break, which is exactly what we want.
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
 import { OrbotoClient } from '../orboto-client.js';
+import { TicketListSortSchema } from './spec-schemas.js';
 import { makeGetProjectHandler } from './get-project.js';
 import { makeListTicketsHandler } from './list-tickets.js';
 import { makeGetTicketHandler } from './get-ticket.js';
@@ -80,6 +82,22 @@ describe('orboto_list_tickets', () => {
         expect(calls[1]).toContain('unscheduled=true');
         expect(calls[1]).toContain('statusCategory=todo');
     });
+    it('passes sort=created and leaves the default order to the API (ORB-2546)', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: { items: [], nextCursor: null } },
+            { json: PROJ },
+            { json: { items: [], nextCursor: null } },
+        ]);
+        await makeListTicketsHandler(client)({ projectKey: 'ACME', sort: 'created' });
+        expect(calls[1]).toContain('sort=created');
+        await makeListTicketsHandler(client)({ projectKey: 'ACME' });
+        expect(calls[3]).not.toContain('sort=');
+    });
+    it('mirrors the shared TicketListSortSchema options (ORB-2546)', () => {
+        const shared = readFileSync(new URL('../../../../packages/shared-schema/src/tickets.ts', import.meta.url), 'utf8');
+        expect(shared).toContain(`TicketListSortSchema = z.enum(${JSON.stringify([...TicketListSortSchema.options]).replace(/"/g, "'").replace(/,/g, ', ')})`);
+    });
     it('refuses unscheduled together with milestone', async () => {
         stub([{ json: PROJ }]);
         await expect(makeListTicketsHandler(client)({ projectKey: 'ACME', unscheduled: true, milestone: 'ACME-M1' })).rejects.toThrow(/not both/);

package/dist/tools/responsibilities.js

@@ -0,0 +1,10 @@
+function person(u) {
+    return u ? u.fullName ?? u.email : '';
+}
+/** One match as a line: owner address, topic, human owner, why it matched. */
+export function ownerLine(m) {
+    const human = m.entry.humanOwner ? `, human ${person(m.entry.humanOwner)}` : '';
+    const deputy = m.entry.deputy ? `, deputy ${person(m.entry.deputy)}` : '';
+    const why = m.matched.length ? `${m.reason}: ${m.matched.join(', ')}` : m.reason;
+    return `- ${m.entry.ownerAddress} - ${m.entry.topic}${human}${deputy} (score ${m.score}, ${why}${m.routes ? '' : ', too weak to route'})`;
+}

package/dist/tools/responsibilities.test.js

@@ -0,0 +1,60 @@
+/** ORB-2542 - the owner check of orboto_agent_notify and orboto_who for. */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { ownerLine } from './responsibilities.js';
+import { makeAgentNotifyHandler } from './agent-coordination.js';
+import { makeAgentWhoHandler } from './agent-who.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+const match = {
+    entry: { id: '6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0', topic: 'Game development', ownerAddress: 'worker@GAMES', keywords: ['unity'], humanOwner: { email: 'owner@orboto.test', fullName: 'Owner Person' }, deputy: null },
+    score: 0.8, reason: 'keyword', matched: ['unity', 'asset'], routes: true,
+};
+function respond(status, body, urls = [], bodies = []) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        urls.push(String(url));
+        if (init?.body)
+            bodies.push(JSON.parse(init.body));
+        return { ok: status < 400, status, statusText: 'x', json: async () => body, text: async () => JSON.stringify(body) };
+    });
+}
+describe('ownerLine', () => {
+    it('prints owner address, topic, human owner and why it matched, and marks a weak match', () => {
+        expect(ownerLine(match)).toBe('- worker@GAMES - Game development, human Owner Person (score 0.8, keyword: unity, asset)');
+        expect(ownerLine({ ...match, routes: false, reason: 'embedding', matched: [] })).toContain('embedding, too weak to route');
+    });
+});
+describe('orboto_agent_notify owner check', () => {
+    const request = { to: 'integrator@OPS', kind: 'request', subject: 'Unity asset on storage', outcome: 'The asset is stored for the game.' };
+    it('sends ownerCheck refuse and turns 409 owner_mismatch into a tool error naming the owner and both ways on', async () => {
+        const bodies = [];
+        respond(409, { error: 'x', errorKey: 'errors.agents.owner_mismatch', errorParams: { topic: 'Game development', owner: 'worker@GAMES', target: 'integrator@OPS', ownerHint: { text: '"Game development" belongs to worker@GAMES, not integrator@OPS' } } }, [], bodies);
+        const result = await makeAgentNotifyHandler(client)(request);
+        expect(bodies[0].ownerCheck).toBe('refuse');
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        expect(text).toContain('belongs to worker@GAMES');
+        expect(text).toContain('route: true');
+        expect(text).toContain('forceTarget: true');
+    });
+    it('passes route on and reports the owner it went to', async () => {
+        const bodies = [];
+        respond(200, { ok: true, messageId: '6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f1', toSessionId: null, routedTo: 'session', recipients: [{ label: 'w@orboto.test (worker, aaaaaaaa)', sessionId: null }, { label: 'w2@orboto.test (worker, bbbbbbbb)', sessionId: null }], ownerHint: { ownerAddress: 'worker@GAMES', topic: 'Game development', target: 'integrator@OPS', routed: true, text: '' } }, [], bodies);
+        const result = await makeAgentNotifyHandler(client)({ ...request, route: true });
+        expect(bodies[0]).toMatchObject({ route: true, ownerCheck: 'refuse' });
+        expect(result.content[0].text).toContain('routed to the owner of "Game development" instead of integrator@OPS');
+        expect(result.structuredContent).toMatchObject({ owner: 'worker@GAMES' });
+    });
+});
+describe('orboto_who for', () => {
+    it('passes for, names the owner, and points at the queue when nobody answers', async () => {
+        const urls = [];
+        respond(200, { sessions: [], owner: match }, urls);
+        const result = await makeAgentWhoHandler(client)({ for: 'unity asset' });
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?for=unity+asset');
+        const text = result.content[0].text;
+        expect(text).toContain('Owner:\n- worker@GAMES');
+        expect(text).toContain('No live session answers to worker@GAMES - send with queue: true and project GAMES');
+        expect(result.structuredContent).toMatchObject({ owner: expect.objectContaining({ reason: 'keyword' }) });
+    });
+});

package/dist/tools/search.js

@@ -4,7 +4,7 @@
  * @see ORB-272
  */
 import { z } from 'zod';
-import { resolveProjectByKey } from './shared.js';
+import { resolveProjectByKey, SEMANTIC_DEGRADED_LINE } from './shared.js';
 const SEARCH_TYPES = ['ticket', 'comment', 'doc', 'project', 'milestone', 'space', 'customer'];
 export const searchToolConfig = {
     title: 'Search across orboto',
@@ -35,7 +35,8 @@ export function makeSearchHandler(client) {
         const relaxedNote = res.pass === 'relaxed'
             ? ' [relaxed pass: no row matched ALL terms - these matched some terms or the meaning]'
             : '';
-        const text = res.items.length === 0
+        const degradedNote = res.semanticDegraded ? `(${SEMANTIC_DEGRADED_LINE})\n` : '';
+        const text = degradedNote + (res.items.length === 0
             ? `No hits for "${input.query}".`
             : `Hits${headerHint}${relaxedNote}:\n\n` + res.items.map((h) => {
                 const tag = h.type.toUpperCase();
@@ -43,7 +44,7 @@ export function makeSearchHandler(client) {
                 const project = h.projectName && h.type !== 'project' ? ` · ${h.projectName}` : '';
                 const excerpt = h.excerpt ? `\n  ${h.excerpt}` : '';
                 return `- [${tag} ${ident}${project}] ${h.title}${excerpt}`;
-            }).join('\n\n');
+            }).join('\n\n'));
         return {
             content: [{ type: 'text', text }],
             structuredContent: {
@@ -51,6 +52,7 @@ export function makeSearchHandler(client) {
                 shown,
                 hasMore,
                 pass: res.pass ?? 'strict',
+                semanticDegraded: res.semanticDegraded ?? false,
                 hits: res.items.map((h) => ({
                     type: h.type,
                     id: h.id, // ORB-1084 - full id, usable as write-tool input

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

@@ -0,0 +1,70 @@
+/**
+ * ORB-2543 - the skill wrapper names a full-text-only answer on stderr and
+ * keeps stdout unchanged.
+ */
+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 LINE = 'semantic search unavailable, showing full-text results';
+it('search, search-docs, ask-docs and check-similar print the degraded line on stderr', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'orboto-2543-wrapper-'));
+    const server = createServer(async (req, res) => {
+        for await (const chunk of req)
+            void chunk;
+        const url = req.url ?? '';
+        res.setHeader('Content-Type', 'application/json');
+        if (url === '/projects')
+            res.end(JSON.stringify([{ id: 'p', key: 'ORB' }]));
+        else if (url.startsWith('/projects/by-key/'))
+            res.end(JSON.stringify({ id: 'p', key: 'ORB' }));
+        else if (url.startsWith('/search?'))
+            res.end(JSON.stringify({ items: [{ type: 'ticket', id: 't', ticketKey: 'ORB-1', title: 'Frobnicator jams', excerpt: '' }], nextCursor: null, total: 1, semanticDegraded: true }));
+        else if (url.startsWith('/docs/search?'))
+            res.end(JSON.stringify({ items: [], total: 0, mode: 'fts', semantic: false, semanticDegraded: true }));
+        else if (url === '/ai/ask-docs')
+            res.end(JSON.stringify({ answer: 'Restart it [1].', citations: [{ index: 1, title: 'Runbook', link: '/l' }], mode: 'keyword', abstained: false, semanticDegraded: true }));
+        else if (url.startsWith('/projects/p/tickets/similar?'))
+            res.end(JSON.stringify({ candidates: [], mode: 'tsvector', semanticDegraded: true }));
+        else {
+            res.statusCode = 404;
+            res.end(JSON.stringify({ error: `unexpected ${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) => code === 0 ? ok({ out, err }) : no(new Error(`Wrapper exit ${code}: ${err}`)));
+            child.stdin.end('');
+        });
+        for (const args of [['search', 'frobnicator'], ['search-docs', 'frobnicator'], ['ask-docs', 'how to restart'], ['check-similar', 'ORB', 'Frobnicator jams']]) {
+            const { out, err } = await run(args);
+            expect(err, args.join(' ')).toContain(LINE);
+            expect(out, args.join(' ')).not.toContain(LINE);
+        }
+    }
+    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/semantic-degraded.test.js

@@ -0,0 +1,65 @@
+/**
+ * ORB-2543 - every search-shaped tool prints one line when the API answered
+ * from full text because the query embedding timed out or the breaker is open.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeSearchHandler } from './search.js';
+import { makeSearchDocsHandler } from './doc-edits.js';
+import { makeAskDocsHandler } from './docs-ai.js';
+import { makeWikiAskHandler } from './wiki.js';
+import { makeKnowledgeAskHandler } from './knowledge.js';
+import { makeCheckSimilarHandler } from './check-similar.js';
+import { SEMANTIC_DEGRADED_LINE } from './shared.js';
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
+        const json = responses.shift();
+        if (json === undefined)
+            throw new Error('unexpected extra fetch');
+        return { ok: true, status: 200, statusText: 'OK', json: async () => json, text: async () => JSON.stringify(json) };
+    });
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+const text = (r) => r.content[0].text;
+const ANSWER = { answer: 'Restart it [1].', citations: [{ index: 1, title: 'Runbook', link: '/d/1' }], mode: 'keyword', abstained: false };
+describe('ORB-2543 - semanticDegraded reaches the agent', () => {
+    it('orboto_search prints the line and carries the flag', async () => {
+        stub([{ items: [], nextCursor: null, total: 0, semanticDegraded: true }]);
+        const res = await makeSearchHandler(client)({ query: 'frobnicator' });
+        expect(text(res)).toContain(SEMANTIC_DEGRADED_LINE);
+        expect(res.structuredContent.semanticDegraded).toBe(true);
+    });
+    it('orboto_search stays silent when the semantic path worked', async () => {
+        stub([{ items: [], nextCursor: null, total: 0, semanticDegraded: false }]);
+        const res = await makeSearchHandler(client)({ query: 'frobnicator' });
+        expect(text(res)).not.toContain(SEMANTIC_DEGRADED_LINE);
+    });
+    it('orboto_search_docs prints the line on hits and on an empty result', async () => {
+        stub([{ items: [], total: 0, mode: 'fts', semantic: false, semanticDegraded: true }]);
+        const empty = await makeSearchDocsHandler(client)({ q: 'frobnicator' });
+        expect(text(empty)).toContain(SEMANTIC_DEGRADED_LINE);
+        stub([{
+                items: [{ id: 'd1', docKey: 'DOC-1', title: 'Runbook', spaceId: 's1', spaceName: 'Ops', projectId: null, snippet: 'restart', headingPath: [], charOffset: 0, lineOffset: 1, rank: 1, url: '/d/1' }],
+                total: 1, mode: 'fts', semantic: false, semanticDegraded: true,
+            }]);
+        const hits = await makeSearchDocsHandler(client)({ q: 'frobnicator' });
+        expect(text(hits)).toContain(SEMANTIC_DEGRADED_LINE);
+        expect(hits.structuredContent.semanticDegraded).toBe(true);
+    });
+    it('ask-docs, wiki ask and knowledge ask print the line', async () => {
+        stub([{ ...ANSWER, semanticDegraded: true }]);
+        expect(text(await makeAskDocsHandler(client)({ question: 'how to restart' }))).toContain(SEMANTIC_DEGRADED_LINE);
+        stub([{ ...ANSWER, semanticDegraded: true }]);
+        expect(text(await makeWikiAskHandler(client)({ question: 'how to restart' }))).toContain(SEMANTIC_DEGRADED_LINE);
+        stub([{ ...ANSWER, semanticDegraded: true, source: 'declared', spaces: [{ spaceKey: 'ORB-S1', spaceName: 'Wiki', projectKey: 'ORB' }] }]);
+        expect(text(await makeKnowledgeAskHandler(client)({ question: 'how to restart' }))).toContain(SEMANTIC_DEGRADED_LINE);
+    });
+    it('orboto_check_similar prints the line', async () => {
+        stub([PROJ, { candidates: [], mode: 'tsvector', semanticDegraded: true }]);
+        const res = await makeCheckSimilarHandler(client)({ projectKey: 'ACME', title: 'Frobnicator jams' });
+        expect(text(res)).toContain(SEMANTIC_DEGRADED_LINE);
+        expect(res.structuredContent.semanticDegraded).toBe(true);
+    });
+});

package/dist/tools/session-start.js

@@ -22,7 +22,7 @@ export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
     description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Registers this session (a heartbeat on its instance row) and is otherwise read-only. '
         + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136). '
-        + 'The digest also carries the Knowledge block (ORB-2225): the wiki index of your declared projects and of the Operations wiki, their latest log entries and open lint issues; ask the wiki with orboto_knowledge_ask before asking a person, file durable facts with orboto_knowledge_add.',
+        + 'The digest also carries the Knowledge block (ORB-2225): the wiki index of your declared projects and of the Operations wiki, their latest log entries and open lint issues; ask the wiki with orboto_knowledge_ask before asking a person, file durable facts with orboto_knowledge_add. It also carries the Responsibilities block (ORB-2542): who owns the topics of your declared projects, looked up with orboto_who for before you send agent mail.',
     inputSchema: z.object({
         projectId: z.string().uuid().optional().describe('Also load this project\'s rules.'),
         ticketKey: z.string().min(3).optional().describe('Ticket key ("ACME-42") - bundles that ticket\'s full context.'),
@@ -211,7 +211,7 @@ export function makeSessionStartHandler(client, opts = {}) {
         if (input.scope === undefined && registration && !registration.scope && envProjectScope()) {
             registration = toRegistration(await declareEnvProjectScope(client, instanceToken)) ?? registration;
         }
-        const [me, rules, assigned, timer, inboxRaw, knowledge] = await Promise.all([
+        const [me, rules, assigned, timer, inboxRaw, knowledge, owners] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             client.get('/users/me/assigned-tickets?statuses=IN_PROGRESS,IN_REVIEW&limit=20').catch(() => ({ items: [] })),
@@ -222,6 +222,9 @@ export function makeSessionStartHandler(client, opts = {}) {
             client.get('/knowledge', { instanceToken })
                 .then((r) => (typeof r?.text === 'string' && Array.isArray(r.spaces) && Array.isArray(r.missing) ? r : null))
                 .catch(() => null),
+            client.get('/responsibilities/block', { instanceToken })
+                .then((r) => (typeof r?.text === 'string' && r.text ? { text: r.text, scoped: Array.isArray(r.entries) ? r.entries.length : 0, total: r.total ?? 0 } : null))
+                .catch(() => null),
         ]);
         const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, from: m.from?.label ?? m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
@@ -299,6 +302,8 @@ export function makeSessionStartHandler(client, opts = {}) {
         const knowledgeBlock = knowledge?.text ? knowledgeLines(knowledge.text, client) : null;
         if (knowledgeBlock)
             lines.push('', ...knowledgeBlock.lines);
+        if (owners)
+            lines.push('', owners.text);
         lines.push('', '## This session');
         const scopeText = registration?.scope
             ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
@@ -353,6 +358,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                     healthyCount: gitHealthWithConnections.reduce((n, p) => n + p.connections.filter((c) => c.healthy).length, 0),
                 },
                 ...(knowledge ? { knowledge: knowledgeSummary(knowledge, knowledgeBlock?.handle) } : {}),
+                ...(owners ? { responsibilities: { scoped: owners.scoped, total: owners.total } } : {}),
                 ...(pendingMessages.length > 0 ? { pendingMessages } : {}),
                 ...(bundle ? { ticketBundle: bundle.structured } : {}),
             },

package/dist/tools/shared.js

@@ -1,4 +1,12 @@
 import { OrbotoApiError } from '../orboto-client.js';
+/** ORB-2543 - the line every search-shaped tool prints when the API flags `semanticDegraded`. */
+export const SEMANTIC_DEGRADED_LINE = 'semantic search unavailable, showing full-text results';
+/** ORB-2468 - the pages a write replaced, each with the revision holding the previous body and its restore command. */
+export function replacedLines(replaced) {
+    if (replaced.length === 0)
+        return '';
+    return `\nReplaced: ${replaced.length}\n${replaced.map((r) => `- ${r.docId}: previous body in revision ${r.revisionId}, restore with: ${r.restoreCommand}`).join('\n')}`;
+}
 export async function resolveProjectByKey(client, key) {
     try {
         return await client.get(`/projects/by-key/${encodeURIComponent(key)}`);
@@ -121,10 +129,30 @@ export function localSessionHost(extra, host = hostname()) {
     const value = host.trim().toLowerCase().slice(0, 200);
     return value || undefined;
 }
-/** Precedence: explicit caller-supplied token > per-connection MCP session id
- *  (distinct per client even on a shared HTTP server) > per-process id (stdio). */
+/** ORB-2544 - the stable token an HTTP MCP session acts under, bound by the transport for the session's lifetime. */
+const sessionInstances = new Map();
+/** The HTTP transport binds a transport session to the stable token of its client. */
+export function bindSessionInstance(sessionId, token) {
+    sessionInstances.set(sessionId, token);
+}
+/** Drops the binding; answers whether another live session still acts under the same token. */
+export function releaseSessionInstance(sessionId) {
+    const token = sessionInstances.get(sessionId) ?? null;
+    sessionInstances.delete(sessionId);
+    return { token, shared: token !== null && [...sessionInstances.values()].includes(token) };
+}
+/** ORB-2544 - one token per account, credential and client name: every reconnect of that client resumes one session row. */
+export function stableClientInstance(input) {
+    if (!input.credential?.id)
+        return null;
+    const client = (input.client ?? '').split('@')[0].trim().toLowerCase();
+    const key = createHash('sha256').update([input.userEmail.toLowerCase(), input.credential.kind, input.credential.id, client].join('\n')).digest('hex').slice(0, 16);
+    return `mcp-${key}`;
+}
+/** Precedence: explicit caller-supplied token > the stable token the transport bound to the MCP session (ORB-2544), else the
+ *  per-connection session id > per-process id (stdio). */
 export function mcpInstanceToken(explicit, extra) {
-    return explicit ?? (extra?.sessionId ? `mcp-${extra.sessionId}` : MCP_PROCESS_INSTANCE);
+    return explicit ?? (extra?.sessionId ? (sessionInstances.get(extra.sessionId) ?? `mcp-${extra.sessionId}`) : MCP_PROCESS_INSTANCE);
 }
 /** ORB-2140 - the stdio process's own instance token, the one the inbox channel follows the stream with. */
 export function mcpProcessInstance() {

package/dist/tools/spec-schemas.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 export const TicketSpecStateSchema = z.enum(['none', 'needs_spec', 'in_spec', 'ready']);
+/** ORB-2546 - mirror of TicketListSortSchema in @orboto/shared-schema (the MCP package does not depend on it; drift test in phase-b-tools.test.ts). */
+export const TicketListSortSchema = z.enum(['updated', 'created']);
 export const ProjectSpecSettingsSchema = z.object({
     enabled: z.boolean().optional(),
     requiredTypes: z.array(z.enum(['epic', 'story', 'task', 'bug'])).optional(),