@orboto/mcp 0.201.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/claude-context.js

@@ -41,6 +41,7 @@ export function readClaudeContext(dir, now = Date.now(), root = claudeContextDir
             ...(typeof parsed.contextWindowSize === 'number' && Number.isFinite(parsed.contextWindowSize)
                 ? { contextWindowSize: Math.max(0, Math.round(parsed.contextWindowSize)) }
                 : {}),
+            ...(typeof parsed.sessionId === 'string' && parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
         });
     }
     return fresh.length === 1 ? fresh[0] : null;

package/dist/claude-context.test.js

@@ -6,7 +6,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { readClaudeContext } from './claude-context.js';
+import { claudeContextDir, readClaudeContext } from './claude-context.js';
 let root;
 beforeEach(() => {
     root = mkdtempSync(path.join(tmpdir(), 'orboto-ctx-'));
@@ -36,3 +36,8 @@ describe('ORB-2149 - claude statusline context reports', () => {
         expect(readClaudeContext('/work/repo', Date.now(), path.join(root, 'missing'))).toBeNull();
     });
 });
+describe('ORB-2149 - the report directory', () => {
+    it('lives under the orboto state directory of the user', () => {
+        expect(claudeContextDir().endsWith(path.join('.orboto', 'claude-context'))).toBe(true);
+    });
+});

package/dist/connect-script.js

@@ -8,7 +8,7 @@ export const CONNECT_SCRIPT_HEADING = 'If you are an AI agent helping a person s
 export const CONNECT_SCRIPT_STEPS = [
     'Work one step per message: say in one sentence what the step does and why, run it, show the result, and only then move on.',
     'Run every step you can run yourself - `orboto connect --yes` checks Node and Claude Code, writes the `orboto` server entry for this directory and prints the exact start command with the standing arguments.',
-    'Hand the person only the steps that need a human: the browser login, quitting and restarting the session with that command, confirming the servers from `.mcp.json` and the local-development prompt, and, on a Team or Enterprise plan, the one Owner switch that allows channels.',
+    'Hand the person only the steps that need a human: the browser login, the two `/plugin` commands that install the orboto plugin (a CLI cannot type into a running session), quitting and restarting the session with that command, confirming the servers from `.mcp.json` and, in the development form, the local-development prompt, and, on a Team or Enterprise plan, the one Owner switch that allows channels and lists the plugin.',
     'Give every command the person runs verbatim in its own code block, never paraphrased and never merged into prose.',
     'Verify before you continue: `orboto whoami` for the identity, `orboto mcp status` for the entry of this directory, `orboto connect --verify` for the channel.',
     'Never paste a reference page into the chat - link it and keep the message to the step you are on.',

package/dist/inbox-channel.js

@@ -1,3 +1,5 @@
+import { RESTART_REQUESTED_NOTICE, writeRestartRequest } from './session-restart.js';
+export { RESTART_REQUESTED_NOTICE };
 export const CHANNEL_METHOD = 'notifications/claude/channel';
 export const CHANNEL_CAPABILITY = 'claude/channel';
 export const DEFAULT_DIGEST_MINUTES = 15;
@@ -171,8 +173,24 @@ export class InboxChannel {
         if (!content)
             return;
         this.stats.notices += 1;
+        if (notice === RESTART_REQUESTED_NOTICE) {
+            await this.emit({ content: this.takeRestartRequest(content), meta: { kind: 'notice', notice } });
+            return;
+        }
         await this.emit({ content, meta: { kind: 'notice', notice } });
     }
+    /** ORB-2181 - an admin restart notice becomes the supervisor's request file. */
+    takeRestartRequest(reason) {
+        try {
+            const result = (this.opts.writeRestart ?? writeRestartRequest)(process.cwd(), { reason, source: 'channel' });
+            return result.written
+                ? `restart requested by the operator (${reason}) - the orboto claude supervisor restarts this session as soon as this turn ends and resumes the same conversation; Claude Code asks for the development-channel confirmation in that terminal.`
+                : `restart requested by the operator (${reason}), but nothing could be written: ${result.detail}. Run \`orboto claude --restart --reason "${reason}"\` in this session's terminal instead.`;
+        }
+        catch (err) {
+            return `restart requested by the operator (${reason}), but the request file could not be written: ${err.message}`;
+        }
+    }
     async flushDigest() {
         if (this.batch.length === 0)
             return;
@@ -279,6 +297,20 @@ export class InboxChannel {
         }
     }
 }
+/** ORB-2175 - the notice name the stale-CLI finding is delivered under. */
+export const CLI_OUTDATED_NOTICE = 'cli_outdated';
+/**
+ * ORB-2175 - `orboto mcp serve` hands its version-skew finding to the proxy in
+ * ORBOTO_MCP_CLI_OUTDATED; the channel says it once on connect, because a CLI
+ * older than the instance leaves this session under a second identity.
+ */
+export function cliOutdatedNotice(raw) {
+    const finding = (raw ?? '').trim();
+    if (!finding)
+        return '';
+    return `${finding}. Until then this checkout runs under two instance tokens, so this session is woken by its own edits. `
+        + 'Fix it yourself: run `orboto self-update`, then `orboto claude --restart --reason "CLI updated"` - the supervisor restarts this session on the same conversation as soon as your turn ends.';
+}
 /** ORB-2140 - the digest window from the environment; NaN or negative fall back to the default. */
 export function digestMinutesFromEnv(raw) {
     if (raw === undefined || raw.trim() === '')

package/dist/inbox-channel.test.js

@@ -5,7 +5,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, InboxChannel, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, CLI_OUTDATED_NOTICE, InboxChannel, RESTART_REQUESTED_NOTICE, cliOutdatedNotice, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
 import { buildOrbotoMcpServer } from './server.js';
 function mockMcp() {
     const notification = vi.fn().mockResolvedValue(undefined);
@@ -115,6 +115,47 @@ describe('InboxChannel', () => {
         expect(String(fetchFn.mock.calls[1][0])).toContain('since=m1');
         channel.close();
     });
+    it('ORB-2181 - a restart_requested notice becomes the supervisor request file and says so', async () => {
+        const { mcp, notification } = mockMcp();
+        const writeRestart = vi.fn().mockReturnValue({ written: true, sessionId: 'sess-1', path: '/home/a/.orboto/claude/sess-1/restart.json', detail: 'ok' });
+        const fetchFn = vi.fn().mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0, writeRestart });
+        await channel.deliverNotice(RESTART_REQUESTED_NOTICE, 'the CLI was updated');
+        expect(writeRestart).toHaveBeenCalledWith(process.cwd(), { reason: 'the CLI was updated', source: 'channel' });
+        const sent = notification.mock.calls[0][0];
+        expect(sent.params.meta).toEqual({ kind: 'notice', notice: 'restart_requested' });
+        expect(sent.params.content).toContain('resumes the same conversation');
+        expect(channel.stats).toMatchObject({ notices: 1, delivered: 0 });
+        channel.close();
+    });
+    it('ORB-2181 - a restart_requested notice that cannot be written says why instead of pretending', async () => {
+        const { mcp, notification } = mockMcp();
+        const writeRestart = vi.fn().mockReturnValue({ written: false, sessionId: null, path: null, detail: 'no status line report' });
+        const fetchFn = vi.fn().mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0, writeRestart });
+        await channel.deliverNotice(RESTART_REQUESTED_NOTICE, 'rotated key');
+        const sent = notification.mock.calls[0][0];
+        expect(sent.params.content).toContain('no status line report');
+        channel.close();
+    });
+    it('ORB-2175 - the stale-CLI finding from `mcp serve` becomes one cli_outdated notice on connect', async () => {
+        expect(cliOutdatedNotice(undefined)).toBe('');
+        expect(cliOutdatedNotice('   ')).toBe('');
+        const finding = 'CLI 0.200.0 is older than the instance 0.201.0 - run `orboto self-update` and restart this session';
+        const content = cliOutdatedNotice(finding);
+        expect(content).toContain(finding);
+        expect(content).toContain('two instance tokens');
+        const { mcp, notification } = mockMcp();
+        const fetchFn = vi.fn().mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        await channel.deliverNotice(CLI_OUTDATED_NOTICE, content);
+        expect(notification).toHaveBeenCalledTimes(1);
+        const sent = notification.mock.calls[0][0];
+        expect(sent.params.meta).toEqual({ kind: 'notice', notice: 'cli_outdated' });
+        expect(sent.params.content).toBe(content);
+        expect(channel.stats).toMatchObject({ notices: 1, delivered: 0 });
+        channel.close();
+    });
 });
 describe('server capability', () => {
     async function connect(channel) {

package/dist/index.js

@@ -59,11 +59,14 @@ async function main() {
         const stdio = new StdioServerTransport();
         await server.connect(stdio);
         if (channel) {
-            const { InboxChannel, digestMinutesFromEnv } = await import('./inbox-channel.js');
+            const { InboxChannel, digestMinutesFromEnv, cliOutdatedNotice, CLI_OUTDATED_NOTICE } = await import('./inbox-channel.js');
             const { mcpProcessInstance } = await import('./tools/shared.js');
             const instanceToken = mcpProcessInstance();
             const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
             inbox.start();
+            const outdated = cliOutdatedNotice(process.env.ORBOTO_MCP_CLI_OUTDATED);
+            if (outdated)
+                void inbox.deliverNotice(CLI_OUTDATED_NOTICE, outdated);
             const { readClaudeContext } = await import('./claude-context.js');
             const beat = () => {
                 const context = readClaudeContext(process.cwd());

package/dist/session-restart.js

@@ -0,0 +1,59 @@
+/**
+ * ORB-2181 - the proxy half of the session restart: whatever asked for it -
+ * the agent through `orboto_session_restart` or the operator through the
+ * `restart_requested` channel notice - ends as the same request file the
+ * `orboto claude` supervisor consumes. No socket, no signal, no network
+ * listener: one 0600 file in a 0700 directory of the caller's own home.
+ */
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { claudeContextDir, readClaudeContext } from './claude-context.js';
+export const RESTART_REQUESTED_NOTICE = 'restart_requested';
+export function claudeSessionsDir() {
+    return path.join(homedir(), '.orboto', 'claude');
+}
+/** Keeps a session id from escaping the session root. */
+export function safeSessionName(id) {
+    const cleaned = [...id].filter((c) => /[A-Za-z0-9_-]/.test(c)).join('').slice(0, 80);
+    return cleaned || 'session';
+}
+export function writeRestartRequest(dir, input, roots = {}) {
+    const now = roots.now ?? Date.now();
+    const root = roots.root ?? claudeSessionsDir();
+    const report = readClaudeContext(dir, now, roots.contextRoot ?? claudeContextDir());
+    const sessionId = report?.sessionId;
+    if (!sessionId) {
+        return {
+            written: false,
+            sessionId: null,
+            path: null,
+            detail: 'no status line report identifies a Claude Code session in this directory - wire the reporter up with `orboto mcp install --statusline`, then ask again',
+        };
+    }
+    const target = path.join(root, safeSessionName(sessionId));
+    const body = JSON.stringify({
+        reason: input.reason,
+        source: input.source,
+        requestedAt: new Date(now).toISOString(),
+        ...(input.requestedBy ? { requestedBy: input.requestedBy } : {}),
+        idleTimeoutSeconds: input.idleTimeoutSeconds ?? 0,
+    });
+    const staging = path.join(target, `.restart-${process.pid}.tmp`);
+    const file = path.join(target, 'restart.json');
+    mkdirSync(target, { recursive: true, mode: 0o700 });
+    writeFileSync(staging, body, { mode: 0o600 });
+    try {
+        renameSync(staging, file);
+    }
+    catch (err) {
+        rmSync(staging, { force: true });
+        throw err;
+    }
+    return {
+        written: true,
+        sessionId,
+        path: file,
+        detail: 'the supervisor restarts this session as soon as no turn is running; it never interrupts one',
+    };
+}

package/dist/session-restart.test.js

@@ -0,0 +1,56 @@
+/**
+ * ORB-2181 - the proxy writes one 0600 request file into a 0700 directory
+ * named after the Claude Code session, and refuses when no status line
+ * report names one.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { claudeSessionsDir, safeSessionName, writeRestartRequest } from './session-restart.js';
+let contexts;
+let sessions;
+const NOW = Date.parse('2026-09-19T10:00:00Z');
+beforeEach(() => {
+    contexts = mkdtempSync(path.join(tmpdir(), 'orboto-ctx-'));
+    sessions = mkdtempSync(path.join(tmpdir(), 'orboto-sessions-'));
+});
+afterEach(() => {
+    rmSync(contexts, { recursive: true, force: true });
+    rmSync(sessions, { recursive: true, force: true });
+});
+function report(body, root = contexts) {
+    mkdirSync(root, { recursive: true });
+    writeFileSync(path.join(root, 'report.json'), JSON.stringify(body));
+}
+describe('ORB-2181 - the restart request file', () => {
+    it('writes the request under the reported session id, owner only', () => {
+        report({ cwd: '/work/repo', sessionId: 'sess-7f3a2b1c', contextTokens: 10, updatedAt: new Date(NOW).toISOString() });
+        const result = writeRestartRequestHere('/work/repo', 'the CLI was updated');
+        expect(result.written).toBe(true);
+        expect(result.sessionId).toBe('sess-7f3a2b1c');
+        const file = path.join(sessions, 'sess-7f3a2b1c', 'restart.json');
+        expect(result.path).toBe(file);
+        expect(statSync(file).mode & 0o777).toBe(0o600);
+        expect(statSync(path.dirname(file)).mode & 0o777).toBe(0o700);
+        expect(JSON.parse(readFileSync(file, 'utf8'))).toMatchObject({ reason: 'the CLI was updated', source: 'mcp' });
+    });
+    it('refuses without a status line report and names the fix', () => {
+        const result = writeRestartRequestHere('/work/repo', 'rotated key');
+        expect(result.written).toBe(false);
+        expect(result.sessionId).toBeNull();
+        expect(result.detail).toContain('orboto mcp install --statusline');
+    });
+    it('keeps a session id from escaping the session root', () => {
+        expect(safeSessionName('../../etc/passwd')).toBe('etcpasswd');
+        expect(safeSessionName('!!!')).toBe('session');
+    });
+});
+function writeRestartRequestHere(dir, reason) {
+    return writeRestartRequest(dir, { reason, source: 'mcp' }, { now: NOW, root: sessions, contextRoot: contexts });
+}
+describe('ORB-2181 - the session root', () => {
+    it('lives under the orboto state directory of the user', () => {
+        expect(claudeSessionsDir().endsWith(path.join('.orboto', 'claude'))).toBe(true);
+    });
+});

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

@@ -45,6 +45,12 @@ export const AgentInventoryEntrySchema = z.object({
         wrongWakeContextTokens: z.number().int(),
         backlogSeen: z.number().int(),
     }),
+    /** ORB-2181 - a restart was requested for this session and its supervisor has not reconnected yet. */
+    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/agent-wakes.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest';
+import { makeAgentWakesHandler } from './agent-wakes.js';
+function clientReturning(body) {
+    const get = vi.fn().mockResolvedValue(body);
+    return { client: { get }, get };
+}
+function textOf(result) {
+    return result.content[0].text;
+}
+describe('orboto_agent_wakes', () => {
+    it('renders the stats with precision, wrong-wake cost and backlog per session and sender', async () => {
+        const { client, get } = clientReturning({
+            hours: 12,
+            sessions: [
+                { label: 'lead (ab12cd34)', wakes: 4, precision: 0.75, medianLatencyMs: 20, topRule: 'addressed', wrongWakeContextTokens: 1200, backlogSeen: 3 },
+                { label: 'worker (ef56ab78)', wakes: 1, precision: null, medianLatencyMs: null, topRule: null, wrongWakeContextTokens: 0, backlogSeen: 0 },
+            ],
+            senders: [],
+        });
+        const result = await makeAgentWakesHandler(client)({ stats: true, hours: 12, sessionId: 'ab12cd34' });
+        expect(get).toHaveBeenCalledWith('/admin/agents/wake-stats?sessionId=ab12cd34&hours=12');
+        const text = textOf(result);
+        expect(text).toContain('Last 12 h - woken sessions:');
+        expect(text).toContain('- lead (ab12cd34): 4 wakes, precision 75%, median 20 ms, top rule addressed, wrong wakes cost 1200 tokens, 3 backlog seen');
+        expect(text).toContain('- worker (ef56ab78): 1 wakes, precision unjudged, median ? ms, top rule -');
+        expect(text).toContain('Senders:\n- (none)');
+    });
+    it('says so when nothing woke anyone', async () => {
+        const { client } = clientReturning({ hours: 24, sessions: [], senders: [] });
+        expect(textOf(await makeAgentWakesHandler(client)({ stats: true }))).toContain('- (no wakes)');
+    });
+    it('lists the ledger rows with latency, context cost and the next cursor', async () => {
+        const { client, get } = clientReturning({
+            rows: [
+                { wokenAt: '2026-01-02T03:04:05Z', subject: 'probe', senderLabel: 'lead (ab12cd34)', rule: 'addressed', transport: 'channel', outcome: 'handled', latencyMs: 18, contextTokens: 900 },
+                { wokenAt: '2026-01-02T03:05:05Z', subject: 'digest', senderLabel: 'worker (ef56ab78)', rule: 'scope_project', transport: 'poll', outcome: 'pending', latencyMs: null, contextTokens: null },
+            ],
+            nextCursor: 'abc',
+        });
+        const text = textOf(await makeAgentWakesHandler(client)({ project: 'ACME', outcome: 'handled', limit: 2, cursor: 'c0' }));
+        expect(get).toHaveBeenCalledWith('/v1/agent/wakes?project=ACME&outcome=handled&limit=2&cursor=c0');
+        expect(text).toContain('- 2026-01-02T03:04:05Z probe - from lead (ab12cd34) via addressed/channel -> handled (18 ms, 900 ctx tokens)');
+        expect(text).toContain('via scope_project/poll -> pending');
+        expect(text).toContain('(next cursor: abc)');
+    });
+    it('reports an empty ledger', async () => {
+        const { client } = clientReturning({ rows: [], nextCursor: null });
+        expect(textOf(await makeAgentWakesHandler(client)({}))).toBe('(no wakes recorded)');
+    });
+});

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/docs.js

@@ -276,7 +276,7 @@ export const createDocToolConfig = {
     inputSchema: z.object({
         spaceId: z.string().min(1).describe('Target doc space - key (e.g. ORB-S1), name, or UUID. Discover via orboto_list_doc_spaces.'),
         title: z.string().min(1).max(255),
-        content: z.string().optional().describe('Markdown body. Pass an empty string or omit for a blank page.'),
+        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Pass an empty string or omit for a blank page. Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown reads as neutral, label <= 24 chars).'),
         parentDocId: z.string().uuid().nullable().optional().describe('Nest under another doc.'),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional().describe('Defaults to "workspace".'),
         icon: z.string().nullish().describe('Single emoji shown in the tree.'),
@@ -315,7 +315,7 @@ export const updateDocToolConfig = {
     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. Send the full new content; the API replaces, not appends.'),
+        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).'),
         parentDocId: z.string().uuid().nullable().optional(),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional(),
         icon: z.string().nullish(),

package/dist/tools/shared.test.js

@@ -8,7 +8,7 @@
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
-import { resolveProjectByKey, resolveTicketByKey, ticketLine, normalizeName, resolveByName } from './shared.js';
+import { resolveProjectByKey, resolveTicketByKey, ticketLine, normalizeName, resolveByName, mcpProcessInstance, checkoutInstanceToken } from './shared.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
 function sequence(responses) {
@@ -171,3 +171,9 @@ describe('ORB-2171 - the stdio proxy shares the checkout token with the CLI and
         expect(checkoutInstanceToken({}, 'build-host', '/srv/other')).not.toBe('agent-e0b18afc9cec');
     });
 });
+describe('mcpProcessInstance', () => {
+    it('is the checkout token this process derived at start', () => {
+        expect(mcpProcessInstance()).toBe(checkoutInstanceToken());
+        expect(mcpProcessInstance().length).toBeGreaterThan(0);
+    });
+});

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.201.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",