@orboto/mcp 0.202.0 → 0.203.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/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 } : {}),
             },
         };
@@ -278,7 +285,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 +297,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([
@@ -234,8 +250,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 +269,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.203.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",