@orboto/mcp 0.202.0 → 0.204.0

package/dist/agent-head.js

@@ -9,7 +9,7 @@ export const AGENT_HEAD_HEADING = 'How to work in orboto';
 export const AGENT_HEAD_LINES = [
     'orboto is your memory and your work contract, not your context - what is not on the ticket or in a doc is gone after the next context switch.',
     'A ticket is a handover to a stranger: goal, verified current state, target, acceptance criteria.',
-    'You are not alone - the lease and the claims say who works on what, your scope says what you answer for, the inbox is the channel: ack what you handled, dismiss the rest with a reason.',
+    'You are not alone - the lease and the claims say who works on what, your scope says what you answer for, the inbox is the channel: ack what you handled and that ack closes the request unless somebody claimed it, dismiss the rest with a reason, and take orboto_message_work only for work that outlives this turn.',
     'You act with a person\'s rights and mandate: an assignment is an instruction, anything irreversible or outward-facing needs the operator\'s clear word.',
     'Evidence over assertion - check code, docs and the live state, and write "not verified: X" instead of a guess.',
     'Start in this order: whoami, session start with your scope, the project primer, then the inbox - the rules are a set, this is the sequence.',

package/dist/tools/admin-writes.js

@@ -40,7 +40,10 @@ export function makeListUsersHandler(client) {
                     tags.push('external');
                 if (!u.isActive)
                     tags.push('disabled');
-                return `- ${u.fullName} <${u.email}>${tags.length ? ` [${tags.join(', ')}]` : ''}`;
+                if (u.provisionedByPlatform)
+                    tags.push('provisioned by the platform');
+                const purpose = u.provisionedByPlatform && u.purpose ? ` - ${u.purpose}` : '';
+                return `- ${u.fullName} <${u.email}>${tags.length ? ` [${tags.join(', ')}]` : ''}${purpose}`;
             }).join('\n');
         return {
             content: [{ type: 'text', text }],
@@ -54,6 +57,8 @@ export function makeListUsersHandler(client) {
                     isExternal: u.isExternal,
                     isBot: u.isBot,
                     lastSeenAt: u.lastSeenAt ?? null,
+                    provisionedByPlatform: u.provisionedByPlatform ?? false,
+                    purpose: u.purpose ?? null,
                 })),
             },
         };

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

@@ -2,11 +2,14 @@ import { z } from 'zod';
 import { mcpInstanceToken } from './shared.js';
 export const agentMessageWorkToolConfig = {
     title: 'Inspect or explicitly handle message work',
-    description: 'List, inspect or mutate durable message work (mutation schema: orboto_api_search). ACK is a separate read receipt and finishes nothing.',
+    description: 'List, inspect or mutate durable message work (mutation schema: orboto_api_search). Only request/error mail carries work; an ack completes it unless somebody claimed it.',
     inputSchema: z.object({ messageId: z.string().uuid().optional(), mutation: z.record(z.unknown()).optional(),
         cursor: z.string().optional(), limit: z.number().int().min(1).max(100).default(25), openOnly: z.boolean().default(true) }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
+/** ORB-2190 - the resolved states, said once in the tool output rather than in the manifest. */
+export const WORK_STATE_NOTE = 'carriesWork false = info/complete/digest mail, no work state. An open list holds requests and errors only, oldest first; '
+    + 'presence unclaimed | active | stalled | expired, and completed once you finish it, an ack closes it, a dismissal closes it or its ticket resolves it.';
 export function makeAgentMessageWorkHandler(client) {
     return async (args, extra) => {
         if (args.mutation && !args.messageId)
@@ -17,6 +20,6 @@ export function makeAgentMessageWorkHandler(client) {
         const result = args.mutation
             ? await client.post(`/v1/agent/messages/${args.messageId}/work`, { ...args.mutation, instanceToken: mcpInstanceToken(undefined, extra) })
             : await client.get(`${args.messageId ? `/v1/agent/messages/${args.messageId}` : '/v1/agent/message-work'}?${q}`, { instanceToken: mcpInstanceToken(undefined, extra) });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+        return { content: [{ type: 'text', text: `${JSON.stringify(result)}\n${WORK_STATE_NOTE}` }], structuredContent: result };
     };
 }

package/dist/tools/agent-messages.js

@@ -13,7 +13,7 @@ import { mcpInstanceToken } from './shared.js';
 const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox as THIS session sees it: mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds is a plain read receipt: no claim needed, finishes nothing. 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: mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request, never claimed work. 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).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),

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

@@ -49,6 +49,8 @@ export const AgentInventoryEntrySchema = z.object({
     restartPending: z.boolean(),
     /** ORB-2181 - the reason the requester gave; null when nothing is pending. */
     restartReason: z.string().nullable(),
+    /** ORB-2189 - the answering instance holds this session's live wake channel, so a restart request can reach it. */
+    restartable: z.boolean(),
     lastSeenAt: z.string(),
     createdAt: z.string(),
 });

package/dist/tools/backup.js

@@ -8,16 +8,23 @@
  * download mechanism. `OrbotoClient.postBinary` / `getBinary` fetch the bytes.
  */
 import { z } from 'zod';
+/**
+ * ORB-1504 - an operator passphrase is deliberately NOT an MCP input: it
+ * would land in the conversation transcript and the tool-call audit. The
+ * passphrase paths are REST and `orboto backup --passphrase-stdin`; an agent
+ * that must drive one uses the escape hatch `orboto_api_call`.
+ */
+const seal = (run) => run.sealed ? ` [encrypted, ${run.sealCustody ?? 'platform'} key${run.sealKeyFingerprint ? ` ${run.sealKeyFingerprint}` : ''}]` : '';
 const mb = (n) => `${Math.round((n / 1024 / 1024) * 10) / 10} MB`;
 export const createFullBackupToolConfig = {
     title: 'Create + download a full workspace backup',
-    description: 'Create an on-demand FULL workspace backup (database + storage) and return the ZIP as a base64 application/zip resource attachment - create, wait and download in one call (the server runs the export as a background run and this tool polls it; large workspaces can take minutes). Rows and file references share one snapshot; missing or incomplete files fail the run, never return a partial ZIP. Requires admin:backup:export. For the scheduled named jobs use orboto_trigger_backup instead.',
+    description: 'Create an on-demand FULL workspace backup (database + storage) and return it as a base64 resource attachment - one call; a background run this tool polls, minutes on a large workspace. Rows and file references share one snapshot; a missing file fails the run, never a partial archive. With backup encryption on the attachment is the sealed archive, not a ZIP. Requires admin:backup:export; scheduled jobs use orboto_trigger_backup.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeCreateFullBackupHandler(client) {
     return async () => {
-        const { runId } = await client.post('/admin/backup/full', {});
+        const { runId, sealed } = await client.post('/admin/backup/full', {});
         const t0 = Date.now();
         for (;;) {
             await new Promise((r) => setTimeout(r, 3000));
@@ -31,12 +38,15 @@ export function makeCreateFullBackupHandler(client) {
         }
         const { bytes, contentType } = await client.getBinary(`/admin/backup/runs/${runId}/download`);
         const base64 = Buffer.from(bytes).toString('base64');
+        const note = sealed
+            ? ' The archive is encrypted with the instance key - it only restores where that key exists.'
+            : '';
         return {
             content: [
-                { type: 'resource', resource: { uri: 'orboto://backup/full.zip', mimeType: contentType, blob: base64 } },
-                { type: 'text', text: `Created full workspace backup (${mb(bytes.byteLength)}), run ${runId}.` },
+                { type: 'resource', resource: { uri: sealed ? 'orboto://backup/full.zip.orbenc' : 'orboto://backup/full.zip', mimeType: contentType, blob: base64 } },
+                { type: 'text', text: `Created full workspace backup (${mb(bytes.byteLength)}), run ${runId}.${note}` },
             ],
-            structuredContent: { sizeBytes: bytes.byteLength, contentType, runId },
+            structuredContent: { sizeBytes: bytes.byteLength, contentType, runId, sealed },
         };
     };
 }
@@ -50,7 +60,7 @@ export function makeListBackupsHandler(client) {
     return async () => {
         const page = await client.get('/admin/backup/runs');
         const items = page.items ?? [];
-        const lines = items.map((r) => `- ${r.id} - ${r.status}${r.fileSizeBytes ? ` (${mb(r.fileSizeBytes)})` : ''} - ${r.completedAt ?? r.startedAt}`);
+        const lines = items.map((r) => `- ${r.id} - ${r.status}${r.fileSizeBytes ? ` (${mb(r.fileSizeBytes)})` : ''} - ${r.completedAt ?? r.startedAt}${seal(r)}`);
         return {
             content: [{ type: 'text', text: items.length ? `Backup runs:\n${lines.join('\n')}` : 'No backup runs yet.' }],
             structuredContent: { runs: items },
@@ -59,7 +69,7 @@ export function makeListBackupsHandler(client) {
 }
 export const downloadBackupToolConfig = {
     title: 'Download a stored backup run',
-    description: 'Download a stored backup run\'s ZIP by run id (from orboto_list_backups - e.g. the nightly job\'s run) as a base64 application/zip resource attachment. Requires admin:backup:read.',
+    description: 'Download a stored backup run by run id (from orboto_list_backups) as a base64 resource attachment; an encrypted run downloads sealed and needs its key to restore. Requires admin:backup:read.',
     inputSchema: z.object({
         runId: z.string().uuid().describe('Backup run id from orboto_list_backups.'),
     }).shape,
@@ -71,7 +81,7 @@ export function makeDownloadBackupHandler(client) {
         const base64 = Buffer.from(bytes).toString('base64');
         return {
             content: [
-                { type: 'resource', resource: { uri: `orboto://backup/run-${runId}.zip`, mimeType: contentType, blob: base64 } },
+                { type: 'resource', resource: { uri: `orboto://backup/run-${runId}${contentType.includes('sealed') ? '.zip.orbenc' : '.zip'}`, mimeType: contentType, blob: base64 } },
                 { type: 'text', text: `Downloaded backup run ${runId.slice(0, 8)} (${mb(bytes.byteLength)}).` },
             ],
             structuredContent: { runId, sizeBytes: bytes.byteLength, contentType },

package/dist/tools/bulk-create.js

@@ -35,7 +35,7 @@ export const bulkCreateTicketsToolConfig = {
         failed: z.array(z.object({ index: z.number().int(), title: z.string(), error: z.string() })),
         duplicateFlags: z.array(z.object({
             key: z.string().describe('The new, flagged ticket.'),
-            matches: z.array(z.object({ ticketKey: z.string().nullable(), similarity: z.number() })),
+            matches: z.array(z.object({ ticketKey: z.string().nullable(), similarity: z.number().nullable() })),
         })),
         languageWarnings: z.number().int().describe('Drafts with a language warning.'),
     }).shape,
@@ -65,6 +65,7 @@ export function makeBulkCreateTicketsHandler(client) {
         const created = [];
         const failed = [];
         const duplicateFlags = [];
+        let degraded = 0;
         let languageWarnings = 0;
         for (let i = 0; i < input.tickets.length; i++) {
             const draft = input.tickets[i];
@@ -91,13 +92,15 @@ export function makeBulkCreateTicketsHandler(client) {
                 created.push(res.ticketKey ?? res.id);
                 if (res.languageWarning)
                     languageWarnings++;
+                if (res.duplicateCheckDegraded)
+                    degraded++;
                 const warnings = res.similarWarnings ?? [];
                 if (warnings.length > 0) {
                     duplicateFlags.push({
                         key: res.ticketKey ?? res.id,
                         matches: warnings.slice(0, 3).map((w) => ({
                             ticketKey: w.ticketKey,
-                            similarity: Math.round(w.similarity * 100) / 100,
+                            similarity: w.matchMode === 'embedding' ? Math.round(w.similarity * 100) / 100 : null,
                         })),
                     });
                 }
@@ -115,7 +118,7 @@ export function makeBulkCreateTicketsHandler(client) {
         if (created.length > 0)
             lines.push(`Created: ${created.join(', ')}`);
         for (const f of duplicateFlags) {
-            lines.push(`⚠ ${f.key} may duplicate ${f.matches.map((m) => `${m.ticketKey ?? '?'} (${m.similarity})`).join(', ')} - review before treating as new work.`);
+            lines.push(`⚠ ${f.key} may duplicate ${f.matches.map((m) => `${m.ticketKey ?? '?'} (${m.similarity === null ? 'text match' : m.similarity})`).join(', ')} - review before treating as new work.`);
         }
         for (const f of failed) {
             lines.push(`✗ draft ${f.index} "${f.title}": ${f.error}`);
@@ -123,6 +126,9 @@ export function makeBulkCreateTicketsHandler(client) {
         if (languageWarnings > 0) {
             lines.push(`⚠ ${languageWarnings} draft(s) in a non-workspace language - consider rewriting for search/duplicate consistency.`);
         }
+        if (degraded > 0) {
+            lines.push(`ℹ ${degraded} draft(s) ran a degraded duplicate-check - the block is on but only full-text candidates were found, whose rank is relative, so nothing was compared with the threshold.`);
+        }
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: { created, failed, duplicateFlags, languageWarnings },

package/dist/tools/check-similar.js

@@ -6,7 +6,7 @@ import { trimSimilarEntries } from './similar-projection.js';
 import { resolveProjectByKey, resolveTicketByKey } from './shared.js';
 export const checkSimilarToolConfig = {
     title: 'Check for similar tickets before creating',
-    description: 'Run the duplicate-detection pipeline (tsvector + AI-embedding rerank when configured) against a proposed title + description, without creating anything. 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. 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.',
+    description: 'Run the duplicate-detection pipeline (tsvector + AI-embedding rerank when configured) against a proposed title + description, without creating anything. 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.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
         title: z.string().min(1).describe('Proposed ticket title.'),
@@ -35,12 +35,13 @@ export function makeCheckSimilarHandler(client) {
         const result = await client.get(`/projects/${project.id}/tickets/similar?${qs.toString()}`);
         const realDuplicates = result.candidates.filter((c) => !c.relation);
         const related = result.candidates.filter((c) => c.relation);
+        const strong = realDuplicates.find((c) => c.matchMode === 'embedding' && c.similarity >= 0.9);
         const recommendation = realDuplicates.length === 0
             ? (related.length === 0
                 ? 'No similar tickets found - safe to create.'
                 : 'Only related context found (parent/sibling/epic) - safe to create; link them instead of treating as duplicates.')
-            : (realDuplicates[0].similarity >= 0.9)
-                ? `HIGH-SIMILARITY MATCH FOUND - review [${realDuplicates[0].ticketKey ?? realDuplicates[0].id.slice(0, 8)}] "${realDuplicates[0].title}" before creating; this may already be tracked.`
+            : 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
             ? `${recommendation} (match mode: ${result.mode})`
@@ -48,11 +49,11 @@ export function makeCheckSimilarHandler(client) {
                 recommendation,
                 `Found ${result.candidates.length} candidate(s) via ${result.mode === 'embedding' ? 'AI embedding rerank' : 'tsvector search'}:`,
                 ...result.candidates.map((c) => {
-                    const pct = `${Math.round(c.similarity * 100)}%`;
+                    const score = c.matchMode === 'embedding' ? `${Math.round(c.similarity * 100)}% AI match` : 'text match';
                     const status = c.statusName ? ` [${c.statusName}]` : '';
                     const key = c.ticketKey ?? c.id.slice(0, 8);
                     const rel = c.relation ? ` (related: ${c.relation})` : '';
-                    return `  - ${key}${status} (${pct} ${c.matchMode})${rel}: ${c.title}`;
+                    return `  - ${key}${status} (${score})${rel}: ${c.title}`;
                 }),
             ].join('\n');
         return {

package/dist/tools/list-projects.js

@@ -4,13 +4,13 @@
 import { z } from 'zod';
 export const listProjectsToolConfig = {
     title: 'List projects',
-    description: 'Return projects the authenticated user can see (key, name, status). Useful first step of a workflow. '
-        + 'If you are after one project, pass `query` to filter by key/name instead of pulling the whole list - '
-        + 'and note you can usually use a project key directly with other tools without listing at all. '
-        + 'When the result says it is partial, refine with `query` rather than re-calling.',
+    description: 'Projects the user can see. To find one, pass `search` (key, name, description, customer) '
+        + 'instead of pulling the whole list; a project key usually works directly with other tools. '
+        + 'When the result is partial, refine rather than re-call.',
     inputSchema: z.object({
-        query: z.string().optional().describe('Substring matched against key or name.'),
-        limit: z.number().int().min(1).max(200).optional().describe('Max projects. Default 50.'),
+        search: z.string().optional().describe('Key, name, description, customer.'),
+        query: z.string().optional().describe('Key/name substring.'),
+        limit: z.number().int().min(1).max(200).optional().describe('Default 50.'),
     }).shape,
     outputSchema: z.object({
         projects: z.array(z.object({
@@ -27,22 +27,28 @@ export const listProjectsToolConfig = {
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
 export function makeListProjectsHandler(client) {
-    return async ({ query, limit } = {}) => {
-        const projects = await client.get('/projects');
+    return async ({ search, query, limit } = {}) => {
+        const s = (search ?? '').trim();
+        const [projects, found] = await Promise.all([
+            client.get('/projects'),
+            s ? client.get(`/projects?search=${encodeURIComponent(s)}`) : Promise.resolve(null),
+        ]);
         const q = (query ?? '').trim().toLowerCase();
+        const base = found ?? projects;
         const matched = q
-            ? projects.filter((p) => `${p.key} ${p.name}`.toLowerCase().includes(q))
-            : projects;
+            ? base.filter((p) => `${p.key} ${p.name}`.toLowerCase().includes(q))
+            : base;
+        const term = [s, q].filter(Boolean).map((v) => `"${v}"`).join(' and ');
         const cap = Math.min(limit ?? 50, 200);
         const shown = matched.slice(0, cap);
         const rows = shown.map((p) => ({ id: p.id, key: p.key, name: p.name, status: p.status, description: p.description }));
         const lines = rows.map((r) => `- ${r.key} - ${r.name} (${r.status})`);
         const partial = shown.length < matched.length;
         const footer = matched.length === 0
-            ? (q ? `No projects match "${q}".` : 'No projects visible to this user.')
+            ? (term ? `No projects match ${term}.` : 'No projects visible to this user.')
             : partial
-                ? `\nShowing first ${shown.length} of ${matched.length} match(es) (of ${projects.length} total) - pass a narrower query to filter.`
-                : `\n(${matched.length} project(s)${q ? ` matching "${q}"` : ''}, complete.)`;
+                ? `\nShowing first ${shown.length} of ${matched.length} match(es) (of ${projects.length} total) - pass a narrower search to filter.`
+                : `\n(${matched.length} project(s)${term ? ` matching ${term}` : ''}, complete.)`;
         const text = matched.length === 0 ? footer : lines.join('\n') + footer;
         return {
             content: [{ type: 'text', text }],

package/dist/tools/list-projects.test.js

@@ -57,6 +57,27 @@ describe('tools/list-projects', () => {
         expect(text).toContain('Showing first 2 of 5 match(es)');
         expect(result.structuredContent).toMatchObject({ total: 5, totalProjects: 5 });
     });
+    it('ORB-2203: search asks the API with ?search= and still counts every visible project', async () => {
+        const all = [
+            { id: 'p1', key: 'ACME', name: 'Acme', description: 'Customer portal', status: 'active' },
+            { id: 'p2', key: 'TOOL', name: 'Internal Tools', description: null, status: 'draft' },
+        ];
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+            const url = String(input);
+            const body = url.includes('search=') ? [all[0]] : all;
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body };
+        });
+        const result = await makeListProjectsHandler(client)({ search: ' portal ' });
+        const urls = fetchSpy.mock.calls.map(([input]) => String(input));
+        expect(urls.some((u) => u.endsWith('/projects?search=portal'))).toBe(true);
+        expect(result.content[0]).toEqual({ type: 'text', text: '- ACME - Acme (active)\n(1 project(s) matching "portal", complete.)' });
+        expect(result.structuredContent).toMatchObject({ total: 1, totalProjects: 2, query: null });
+    });
+    it('ORB-2203: without search only the plain list is fetched', async () => {
+        const fetchSpy = mockFetch([]);
+        await makeListProjectsHandler(client)({ query: 'x' });
+        expect(fetchSpy.mock.calls.map(([input]) => String(input)).every((u) => !u.includes('search='))).toBe(true);
+    });
     it('renders an empty-state text block when the API returns no rows', async () => {
         mockFetch([]);
         const result = await makeListProjectsHandler(client)();

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

@@ -490,6 +490,27 @@ describe('orboto_search', () => {
         expect(sc.total).toBe(42);
         expect(sc.hasMore).toBe(true);
     });
+    it('ORB-2201: passes the jump types and renders project and milestone hits by key', async () => {
+        const calls = stub([
+            {
+                json: {
+                    items: [
+                        { type: 'project', id: 'p1', key: 'ACME', projectKey: 'ACME', title: 'Acme', excerpt: '', projectId: 'p1', projectName: 'Acme', spaceId: null, spaceName: null, url: '/projects/acme', rank: 2000 },
+                        { type: 'milestone', id: 'm1', key: 'ACME-M1', projectKey: 'ACME', title: 'Launch', excerpt: '', projectId: 'p1', projectName: 'Acme', spaceId: null, spaceName: null, url: '/projects/acme?milestoneIds=m1', rank: 200 },
+                    ],
+                    nextCursor: null,
+                    total: 2,
+                },
+            },
+        ]);
+        const res = await makeSearchHandler(client)({ query: 'acme', types: ['project', 'milestone'] });
+        expect(calls[0]).toContain('types=project%2Cmilestone');
+        const text = res.content[0].text;
+        expect(text).toContain('- [PROJECT ACME] Acme');
+        expect(text).toContain('- [MILESTONE ACME-M1 · Acme] Launch');
+        const sc = res.structuredContent;
+        expect(sc.hits.map((h) => [h.key, h.projectKey])).toEqual([['ACME', 'ACME'], ['ACME-M1', 'ACME']]);
+    });
 });
 describe('doc tools', () => {
     it('list: uses DocSpace.type to label scope, not a joined projectName', async () => {

package/dist/tools/search.js

@@ -5,13 +5,13 @@
  */
 import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
+const SEARCH_TYPES = ['ticket', 'comment', 'doc', 'project', 'milestone', 'space', 'customer'];
 export const searchToolConfig = {
     title: 'Search across orboto',
-    description: 'Full-text search across tickets, comments, and docs. Honours the caller\'s visibility - private tickets and internal comments never appear unless the caller can already see them. Recall (ORB-1695): when the strict all-terms pass finds nothing, the server automatically retries with an OR-relaxed pass plus semantic (embedding) recall - the response\'s `pass` field says which pass produced the hits, and relaxed-pass hits deserve a skeptical read (they matched SOME terms or only the meaning, not all terms). Still prefer a single distinctive STABLE token (file/component/error-string fragment like "AdminCodesPage") and search the SYMPTOM, not your intended fix.',
+    description: 'Search tickets, comments and docs; `types` adds projects, milestones, spaces, customers. Content matches full text, jump types match key and name; `types` defaults to ticket, comment, doc. Honours the caller\'s visibility - private tickets and internal comments never appear unless the caller can already see them. Recall (ORB-1695): when the strict all-terms pass finds nothing, the server automatically retries with an OR-relaxed pass plus semantic (embedding) recall - the response\'s `pass` field says which pass produced the hits, and relaxed-pass hits deserve a skeptical read (they matched SOME terms or only the meaning, not all terms). Still prefer a single distinctive STABLE token (file/component/error-string fragment like "AdminCodesPage") and search the SYMPTOM, not your intended fix.',
     inputSchema: z.object({
         query: z.string().min(1).describe('Search terms, e.g. "queue worker retry".'),
-        types: z.array(z.enum(['ticket', 'comment', 'doc'])).optional()
-            .describe('Restrict to entity types. Omit for all.'),
+        types: z.array(z.enum(SEARCH_TYPES)).optional(),
         projectKey: z.string().optional().describe('Restrict to one project.'),
         limit: z.number().int().min(1).max(50).default(15),
     }).shape,
@@ -39,9 +39,10 @@ export function makeSearchHandler(client) {
             ? `No hits for "${input.query}".`
             : `Hits${headerHint}${relaxedNote}:\n\n` + res.items.map((h) => {
                 const tag = h.type.toUpperCase();
-                const ident = h.ticketKey ?? h.id;
-                const project = h.projectName ? ` · ${h.projectName}` : '';
-                return `- [${tag} ${ident}${project}] ${h.title}\n  ${h.excerpt}`;
+                const ident = h.ticketKey ?? h.key ?? h.id;
+                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');
         return {
             content: [{ type: 'text', text }],
@@ -56,6 +57,8 @@ export function makeSearchHandler(client) {
                     title: h.title,
                     excerpt: h.excerpt,
                     ticketKey: h.ticketKey ?? null,
+                    key: h.key ?? h.ticketKey ?? null,
+                    projectKey: h.projectKey ?? null,
                     projectName: h.projectName,
                     spaceName: h.spaceName,
                     url: h.url,

package/dist/tools/similar-projection.js

@@ -2,11 +2,13 @@
  * ORB-1693 - the agent-facing projection of a duplicate-warning entry.
  */
 export function trimSimilarEntry(w) {
+    const matchMode = w.matchMode ?? 'embedding';
     return {
         ticketKey: w.ticketKey ?? w.id.slice(0, 8),
         title: w.title,
         statusCategory: w.statusCategory ?? null,
-        similarity: Math.round(w.similarity * 100) / 100,
+        similarity: matchMode === 'embedding' ? Math.round(w.similarity * 100) / 100 : null,
+        matchMode,
         relation: w.relation ?? null,
     };
 }

package/dist/tools/ticket-writes.js

@@ -53,7 +53,7 @@ function ticketStructured(t) {
 }
 export const createTicketToolConfig = {
     title: 'Create a ticket',
-    description: 'Create a new ticket in the given project. Creating more than ~3 tickets? Use `orboto_bulk_create_tickets` instead - one call, one compact response. Returns the new ticket\'s key (e.g. "ACME-42") so callers can chain follow-ups. **Read the new key from `structuredContent.createdTicketKey` (ORB-1176) - never from `similarWarnings[].ticketKey`, which are OTHER, possibly-duplicate tickets.** The caller must have `ticket:create` on the project. **Duplicate-detection safety-net (ORB-831):** if `similarWarnings` appears in the response with one or more entries, the ticket WAS created but you should review whether to close it as a duplicate of the listed ticket(s) instead. The warnings are advisory - never blocking - but each entry is a ticket the system thinks the new one overlaps with. Prefer `orboto_check_similar` BEFORE creating when you want a dry-run. **Deferred check under load (ORB-1437):** if `duplicateCheckDeferred: true` appears, the project was under a create burst so the duplicate-check was run in the background instead of inline - `similarWarnings` is then empty because it did NOT run synchronously, which is NOT the same as "no duplicates found". A strong match, if any, is posted as an advisory comment on the new ticket a moment later; check the ticket comments before treating it as new work. **Duplicate-check recall (ORB-1121):** when you search/check-similar first, results rank by term co-occurrence - a long, solution-framed title with rare terms can return 0 hits even when a short, symptom-framed dup sharing one distinctive token exists. Probe with a single distinctive STABLE token (file/component/error-string fragment), keep queries SHORT, and search the SYMPTOM not your fix; a 0-result long query is not "no dup". **Language-mismatch warning (ORB-890):** if `languageWarning` appears, the ticket was written in a language different from the workspace default. Consider rewriting in the expected language so search + duplicate-detection stay consistent. Non-blocking. **Before a mass-create (ORB-989):** call `orboto_whoami` first - its `workspaceLocale` field is the language you should write every ticket in. If the same `languageWarning` repeats, stop and clarify the intended language rather than pushing through the whole batch. **Strict mode (ORB-990):** if the workspace enforces ticket language, a mismatch is rejected (the tool returns a `blocked` result, not a created ticket) - rewrite in the workspace language, or set `allowLanguageMismatch: true` only when the language is genuinely intentional. **Hard duplicate-block (ORB-1471):** some workspaces REFUSE a create whose top similarity match is at/above a configured threshold - the tool returns a `duplicateBlocked` result (NOT a created ticket) listing the matching tickets. Extend or comment on one of those instead. If you have confirmed none of them cover this work, retry with `allowDuplicate: true` AND a `duplicateJustification` explaining why - the justification is persisted as a comment on the new ticket. '
+    description: 'Create a new ticket in the given project. Creating more than ~3 tickets? Use `orboto_bulk_create_tickets` instead - one call, one compact response. Returns the new ticket\'s key (e.g. "ACME-42") so callers can chain follow-ups. **Read the new key from `structuredContent.createdTicketKey` (ORB-1176) - never from `similarWarnings[].ticketKey`, which are OTHER, possibly-duplicate tickets.** The caller must have `ticket:create` on the project. **Duplicate-detection safety-net (ORB-831):** if `similarWarnings` appears in the response with one or more entries, the ticket WAS created but you should review whether to close it as a duplicate of the listed ticket(s) instead. The warnings are advisory - never blocking - but each entry is a ticket the system thinks the new one overlaps with. Prefer `orboto_check_similar` BEFORE creating when you want a dry-run. **Deferred check under load (ORB-1437):** if `duplicateCheckDeferred: true` appears, the project was under a create burst so the duplicate-check was run in the background instead of inline - `similarWarnings` is then empty because it did NOT run synchronously, which is NOT the same as "no duplicates found". A strong match, if any, is posted as an advisory comment on the new ticket a moment later; check the ticket comments before treating it as new work. **Duplicate-check recall (ORB-1121):** when you search/check-similar first, results rank by term co-occurrence - a long, solution-framed title with rare terms can return 0 hits even when a short, symptom-framed dup sharing one distinctive token exists. Probe with a single distinctive STABLE token (file/component/error-string fragment), keep queries SHORT, and search the SYMPTOM not your fix; a 0-result long query is not "no dup". **Language-mismatch warning (ORB-890):** if `languageWarning` appears, the ticket was written in a language different from the workspace default. Consider rewriting in the expected language so search + duplicate-detection stay consistent. Non-blocking. **Before a mass-create (ORB-989):** call `orboto_whoami` first - its `workspaceLocale` field is the language you should write every ticket in. If the same `languageWarning` repeats, stop and clarify the intended language rather than pushing through the whole batch. **Strict mode (ORB-990):** if the workspace enforces ticket language, a mismatch is rejected (the tool returns a `blocked` result, not a created ticket) - rewrite in the workspace language, or set `allowLanguageMismatch: true` only when the language is genuinely intentional. **Hard duplicate-block (ORB-1471, ORB-2185):** a workspace can REFUSE a create - the tool returns `duplicateBlocked` (no ticket) with the candidates. ONLY an AI-embedding match at/above the threshold against an OPEN ticket blocks; a text match and a closed match stay warnings, and a text match is printed WITHOUT a percentage because a text rank is relative, not a similarity. Extend one of the candidates, or retry with `allowDuplicate: true` AND a `duplicateJustification` (saved as a comment). `duplicateCheckDegraded: true` = the block was on but only text candidates existed, so nothing could be compared and the create went through unchecked. '
         + '**Pre-flight (ORB-2162):** `dryRun: true` runs the same language, type, label and duplicate checks the write runs and returns their verdicts WITHOUT creating anything - `structuredContent.preflight` carries `ok`, `severity`, `blockedBy` and one verdict per check, each with the exact message the real create would answer with. Use it when a create would otherwise cost a round trip to fix the payload afterwards; re-send the same arguments without `dryRun` once the verdicts are clean. '
         + '**Parameter notes.** `deliveryMode` (ORB-1608) is the role-aware commit policy that replaced the blanket one-commit-per-ticket rule: implementation/docs expect exactly one linked commit (closing without one is a non-blocking warning); review/admin/epic never expect one - reviews are read-only, admin work carries external evidence, epics derive completion from their children; unset defaults to "epic" when type=epic, else "implementation". `milestone` takes a key ("ORB-M3"), a name, or a UUID and is looked up in the project including closed milestones - unknown or ambiguous is an error, so pass the key/UUID when a name repeats. `labels` and `assigneeEmails` attach ATOMICALLY inside the create (ORB-1416): an unknown label or non-member email rolls the whole create back with a 400, leaving no orphan ticket - there is no separate attach call to retry.',
     inputSchema: z.object({
@@ -142,6 +142,7 @@ export function makeCreateTicketHandler(client) {
         const warnings = created.similarWarnings ?? [];
         const langWarning = created.languageWarning;
         const deferred = created.duplicateCheckDeferred === true;
+        const degraded = created.duplicateCheckDegraded === true;
         const baseText = ticketSummaryText('Created', created);
         const parts = [baseText];
         if (deferred) {
@@ -149,6 +150,11 @@ export function makeCreateTicketHandler(client) {
                 + `An empty duplicate list here does NOT mean "no duplicates". If a strong match is found, an advisory comment `
                 + `will be posted on [${created.ticketKey}] shortly; review it before treating this as new work.`);
         }
+        if (degraded) {
+            parts.push(`\nℹ Duplicate-check degraded - the workspace blocks duplicates, but this check found only full-text candidates. `
+                + `A text rank is relative (the best match always scores 1.000), so nothing could be compared with the threshold and the create was allowed. `
+                + `Read the candidates below yourself; if embeddings are missing workspace-wide, tell the operator (orboto_embedding_status).`);
+        }
         if (warnings.length > 0) {
             parts.push(`\n⚠ Potential duplicates found - review before treating this as new work:\n${warnings.map((w) => `  - [${w.ticketKey ?? w.id.slice(0, 8)}] "${w.title}" (${formatSimilarity(w)})`).join('\n')}\n  If one of these covers the work, close [${created.ticketKey}] as a duplicate via orboto_close_ticket.`);
         }
@@ -163,6 +169,7 @@ export function makeCreateTicketHandler(client) {
                 createdTicketKey: created.ticketKey,
                 similarWarnings: trimSimilarEntries(warnings),
                 ...(deferred ? { duplicateCheckDeferred: true } : {}),
+                ...(degraded ? { duplicateCheckDegraded: true } : {}),
                 ...(langWarning ? { languageWarning: langWarning } : {}),
             },
         };
@@ -179,7 +186,7 @@ function preflightResult(preflight, projectKey) {
         preflight.ok
             ? `✓ Pre-flight clean for ${projectKey} - re-send the same arguments without dryRun to create the ticket.`
             : `⛔ Pre-flight BLOCKED for ${projectKey} (${preflight.blockedBy.join(', ')}) - nothing was created. Fix the payload and run the pre-flight again.`,
-        `  ${icon[preflight.verdicts.language.severity]} language: ${preflight.verdicts.language.message}`,
+        `  ${icon[preflight.verdicts.language.severity]} language: ${preflight.verdicts.language.message}${preflight.verdicts.language.hint ? ` Keep it only on purpose: ${preflight.verdicts.language.hint.query}.` : ''}`,
         `  ${icon[preflight.verdicts.type.severity]} type: ${preflight.verdicts.type.message}`,
         `  ${icon[preflight.verdicts.labels.severity]} labels: ${preflight.verdicts.labels.message}`,
         `  ${icon[preflight.verdicts.duplicates.severity]} duplicates: ${preflight.verdicts.duplicates.message}`,
@@ -250,12 +257,13 @@ function languageBlockResult(err, verb) {
     if (!parsed.languageWarning)
         return null;
     const lw = parsed.languageWarning;
+    const retry = `retry the same call with ${parsed.hint?.query ?? 'allowLanguageMismatch=true'}`;
     const text = `⛔ ${verb} blocked - strict ticket-language enforcement is on.\n` +
         `This content reads as "${lw.detected}" but the workspace language is "${lw.expected}".\n` +
-        `Rewrite it in ${lw.expected.toUpperCase()}, or - only if you are sure the language is intentional - retry the same call with allowLanguageMismatch=true.`;
+        `Rewrite it in ${lw.expected.toUpperCase()}, or - only if you are sure the language is intentional - ${retry}.`;
     return {
         content: [{ type: 'text', text }],
-        structuredContent: { blocked: true, languageWarning: lw },
+        structuredContent: { blocked: true, languageWarning: lw, ...(parsed.hint ? { hint: parsed.hint } : {}) },
         isError: true,
     };
 }
@@ -278,7 +286,10 @@ function duplicateBlockResult(err) {
         return null;
     const candidates = parsed.similarWarnings;
     const lines = candidates.map((w) => `  - [${w.ticketKey ?? w.id.slice(0, 8)}] "${w.title}" (${formatSimilarity(w)})`);
-    const text = `⛔ Ticket create BLOCKED - this looks like a duplicate (top match ${Math.round((parsed.topSimilarity ?? 0) * 100)}%, block threshold ${Math.round((parsed.threshold ?? 0) * 100)}%).\n` +
+    const decidedBy = parsed.decidingTicketKey
+        ? `${parsed.decidingTicketKey}, AI embedding match`
+        : 'an AI embedding match';
+    const text = `⛔ Ticket create BLOCKED - this looks like a duplicate (top match ${Math.round((parsed.topSimilarity ?? 0) * 100)}%, block threshold ${Math.round((parsed.threshold ?? 0) * 100)}%, decided by ${decidedBy} on an OPEN ticket).\n` +
         `Existing tickets it overlaps with:\n${lines.join('\n')}\n` +
         `Extend or comment on one of these instead. If you have confirmed NONE of them cover this work, retry orboto_create_ticket with allowDuplicate: true AND a duplicateJustification explaining why it is not a duplicate (it is saved as a comment on the new ticket).`;
     return {
@@ -287,14 +298,17 @@ function duplicateBlockResult(err) {
             duplicateBlocked: true,
             threshold: parsed.threshold ?? null,
             topSimilarity: parsed.topSimilarity ?? null,
+            decidingMode: parsed.decidingMode ?? 'embedding',
+            decidingTicketKey: parsed.decidingTicketKey ?? null,
             similarWarnings: trimSimilarEntries(candidates),
         },
         isError: true,
     };
 }
+/** ORB-2185 - a full-text rank is relative, so a text match is never a percentage. */
 function formatSimilarity(w) {
-    const pct = `${Math.round(w.similarity * 100)}% ${w.matchMode === 'embedding' ? 'AI match' : 'text match'}`;
-    return w.statusName ? `${w.statusName}, ${pct}` : pct;
+    const score = w.matchMode === 'embedding' ? `${Math.round(w.similarity * 100)}% AI match` : 'text match';
+    return w.statusName ? `${w.statusName}, ${score}` : score;
 }
 export const updateTicketToolConfig = {
     title: 'Update a ticket',

package/dist/tools/ticket-writes.test.js

@@ -116,17 +116,33 @@ describe('orboto_create_ticket', () => {
         expect(text).toContain('ACME-42');
         expect(text).toContain('91% AI match');
         expect(text).toContain('ACME-13');
+        expect(text).toContain('Done, text match');
+        expect(text).not.toContain('72%');
         const sc = res.structuredContent;
         expect(sc.similarWarnings).toHaveLength(2);
         expect(sc.createdTicketKey).toBe('ACME-99');
         expect(sc.similarWarnings.map((w) => w.ticketKey)).not.toContain(sc.createdTicketKey);
         for (const w of sc.similarWarnings) {
-            expect(Object.keys(w).sort()).toEqual(['relation', 'similarity', 'statusCategory', 'ticketKey', 'title']);
+            expect(Object.keys(w).sort()).toEqual(['matchMode', 'relation', 'similarity', 'statusCategory', 'ticketKey', 'title']);
         }
         expect(sc.similarWarnings[0]).toEqual({
             ticketKey: 'ACME-42', title: 'Authentication breaks for SAML',
-            statusCategory: 'in_progress', similarity: 0.91, relation: null,
+            statusCategory: 'in_progress', similarity: 0.91, matchMode: 'embedding', relation: null,
         });
+        expect(sc.similarWarnings[1]).toEqual({
+            ticketKey: 'ACME-13', title: 'Auth flow regressed',
+            statusCategory: 'done', similarity: null, matchMode: 'tsvector', relation: null,
+        });
+    });
+    it('a degraded duplicate-check is surfaced on the created ticket (ORB-2185)', async () => {
+        stub([
+            { json: PROJ },
+            { json: { ...TICKET, ticketKey: 'ACME-101', duplicateCheckDegraded: true, similarWarnings: [] } },
+        ]);
+        const res = await makeCreateTicketHandler(client)({ projectKey: 'ACME', title: 'degraded check' });
+        const text = res.content[0].text;
+        expect(text).toContain('Duplicate-check degraded');
+        expect(res.structuredContent.duplicateCheckDegraded).toBe(true);
     });
     it('returns no warning block when similarWarnings is empty', async () => {
         stub([
@@ -212,6 +228,25 @@ describe('orboto_create_ticket', () => {
         expect(sc.blocked).toBe(true);
         expect(sc.languageWarning.severity).toBe('block');
     });
+    it('reads the way out from the hint, never from the sentence written for a person (ORB-2200)', async () => {
+        const blockBody = JSON.stringify({
+            error: 'This ticket looks like it is written in a different language (de) than this project expects (en). If the language is intentional, you can keep the ticket as it is.',
+            errorKey: 'errors.tickets.language_mismatch',
+            languageWarning: { code: 'language_mismatch', severity: 'block', detected: 'de', expected: 'en' },
+            hint: { query: 'allowLanguageMismatch=true' },
+        });
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            if ((init?.method ?? 'GET') === 'GET') {
+                return { ok: true, status: 200, statusText: 'OK', json: async () => PROJ, text: async () => '' };
+            }
+            return { ok: false, status: 422, statusText: 'Unprocessable', json: async () => ({}), text: async () => blockBody };
+        });
+        const res = await makeCreateTicketHandler(client)({ projectKey: 'ACME', title: 'Authentifizierung schlägt fehl bei externen Nutzern' });
+        const text = res.content[0].text;
+        expect(text).toContain('retry the same call with allowLanguageMismatch=true');
+        expect(text).not.toContain('keep the ticket as it is');
+        expect(res.structuredContent.hint).toEqual({ query: 'allowLanguageMismatch=true' });
+    });
     it('passes allowLanguageMismatch as a query param when the override is set (ORB-990)', async () => {
         let createUrl = '';
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
@@ -234,8 +269,10 @@ describe('orboto_create_ticket', () => {
             errorKey: 'errors.tickets.duplicate_blocked',
             threshold: 0.9,
             topSimilarity: 0.98,
+            decidingMode: 'embedding',
+            decidingTicketKey: 'ACME-7',
             similarWarnings: [
-                { id: 't1', ticketKey: 'ACME-7', title: 'Webhook signature mismatch', statusName: 'To Do', statusColor: null, statusCategory: 'todo', similarity: 0.98, matchMode: 'tsvector' },
+                { id: 't1', ticketKey: 'ACME-7', title: 'Webhook signature mismatch', statusName: 'To Do', statusColor: null, statusCategory: 'todo', similarity: 0.98, matchMode: 'embedding' },
             ],
         });
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
@@ -251,8 +288,11 @@ describe('orboto_create_ticket', () => {
         expect(text).toContain('BLOCKED');
         expect(text).toContain('ACME-7');
         expect(text).toContain('allowDuplicate: true');
+        expect(text).toContain('decided by ACME-7, AI embedding match on an OPEN ticket');
         const sc = res.structuredContent;
         expect(sc.duplicateBlocked).toBe(true);
+        expect(sc.decidingMode).toBe('embedding');
+        expect(sc.decidingTicketKey).toBe('ACME-7');
         expect(sc.similarWarnings).toHaveLength(1);
     });
     it('passes allowDuplicate as a query param and the justification in the body when overriding (ORB-1471)', async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.202.0",
+  "version": "0.204.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",