@orboto/mcp 0.200.1 → 0.202.0

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/manifest-size.test.js

@@ -39,10 +39,16 @@ afterEach(() => { vi.restoreAllMocks(); });
  * the wake ledger and the delivery precision per session and per sender
  * in the full toolset (measured full = 170,030 chars); the curated tier
  * reaches it through the escape hatch and is unchanged.
+ * ORB-2162 raised the curated ceiling to 39,900 and the curated token
+ * ceiling to 11,100: `orboto_create_ticket` gained `dryRun`, the pre-flight
+ * that returns the language, type, label and duplicate verdicts before the
+ * write instead of after it (measured curated = 39,679 chars / 11,022
+ * tokens, from 39,461 / 10,961 - one boolean parameter, no new tool). The
+ * verdicts themselves ride the response, not the manifest.
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */
-const CURATED_MAX_CHARS = 39_700;
+const CURATED_MAX_CHARS = 39_900;
 const FULL_MAX_CHARS = 171_200;
 /**
  * ORB-1805 - the estimator the ticket measured the failure with
@@ -64,7 +70,7 @@ const MINIMAL_MAX_TOKENS = 3_200;
  * The curated tier is ratcheted on its TOOL SCHEMAS (the instructions
  * block has its own budget, enforced in instructions-budget.test.ts).
  */
-const CURATED_SCHEMA_MAX_TOKENS = 11_000;
+const CURATED_SCHEMA_MAX_TOKENS = 11_100;
 async function measuredManifest(toolset) {
     const server = await buildOrbotoMcpServer({
         baseUrl: 'https://orboto.example.com',

package/dist/response-budget.js

@@ -59,6 +59,10 @@ const MIN_ARRAY_CUT = 3;
 const MAX_CUT_PASSES = 64;
 export const HANDLE_TTL_MS = 15 * 60 * 1000;
 export const MAX_HANDLES = 16;
+/** ORB-2164 - the budget is an MCP-server artefact; the same data over REST or
+ *  either CLI comes back whole, which is the way out that outlives a handle. */
+export const UNCUT_ELSEWHERE = 'The cut is an MCP-server artefact: the REST API and both CLIs return the complete body '
+    + '(`orboto get <path>`, `orboto_api_call`, or the named CLI command). There is no CLI expand.';
 /**
  * `ORBOTO_MCP_RESPONSE_BUDGET=off` disables the cap entirely (escape
  * hatch for a client that genuinely wants everything);
@@ -326,7 +330,8 @@ function shrink(toolName, result, budget, originalChars, protectText = false) {
     const notice = allOmitted.length > 0
         ? `[Response truncated to the MCP response budget (${budget} chars) - it would otherwise cost `
             + `${originalChars} chars on EVERY later request in this session. Omitted content is not lost: `
-            + `call orboto_response_expand with handle "${handle}" and one of the paths in __truncation.omitted.]`
+            + `call orboto_response_expand with handle "${handle}" and one of the paths in __truncation.omitted. `
+            + `${UNCUT_ELSEWHERE}]`
         : `[Response is ${originalChars} chars, over the MCP response budget (${budget} chars), and nothing in it `
             + 'could be cut safely - it is protected or uncuttable content. NOTHING was omitted; there is no remainder to fetch.]';
     if (structured !== undefined && structured !== null && typeof structured === 'object' && !Array.isArray(structured)) {
@@ -337,7 +342,8 @@ function shrink(toolName, result, budget, originalChars, protectText = false) {
             omittedChars: 0, // filled in below, once the final size is known
             omitted: allOmitted,
             howToGetTheRest: `Call orboto_response_expand { handle: "${handle}", path: "<one of omitted[].path>" } for the omitted `
-                + 'remainder. Omit `path` to list what is available. The handle expires 15 minutes after this call.',
+                + 'remainder. Omit `path` to list what is available. The handle lives in this MCP server process and '
+                + `expires 15 minutes after this call. ${UNCUT_ELSEWHERE}`,
             ...(atFloor ? { atFloor: true } : {}),
         };
         structured.__truncation = block;

package/dist/response-budget.test.js

@@ -2,7 +2,7 @@
  * ORB-1697 - the central response budget.
  */
 import { describe, it, expect, beforeEach } from 'vitest';
-import { applyResponseBudget, budgetFor, budgetEnabled, measureHalves, measureResult, readPayload, resetPayloadStore, resolvePath, DEFAULT_BUDGET_CHARS, MAX_HANDLES, HANDLE_TTL_MS, storePayload, PROTECT_TEXT_META, } from './response-budget.js';
+import { applyResponseBudget, budgetFor, budgetEnabled, measureHalves, measureResult, readPayload, resetPayloadStore, resolvePath, DEFAULT_BUDGET_CHARS, MAX_HANDLES, HANDLE_TTL_MS, storePayload, PROTECT_TEXT_META, UNCUT_ELSEWHERE, } from './response-budget.js';
 import { makeResponseExpandHandler } from './tools/response-expand.js';
 const TOOL = 'orboto_test_tool';
 function result(structured, text = 'text block') {
@@ -84,6 +84,19 @@ describe('over budget', () => {
         expect(text).toContain('orboto_response_expand');
         expect(text).toContain(out.handle);
     });
+    it('ORB-2164: the hint names BOTH ways out - the expand handle and the uncut body over REST or the CLI', () => {
+        const out = applyResponseBudget(TOOL, result({ description: 'd'.repeat(30_000) }));
+        const block = truncationOf(out.result);
+        const how = String(block.howToGetTheRest);
+        expect(how).toContain('orboto_response_expand');
+        expect(how).toContain('expires 15 minutes');
+        expect(how).toContain('this MCP server process');
+        expect(how).toContain(UNCUT_ELSEWHERE);
+        const text = out.result.content[0].text;
+        expect(text).toContain(UNCUT_ELSEWHERE);
+        expect(UNCUT_ELSEWHERE).toContain('REST API and both CLIs');
+        expect(UNCUT_ELSEWHERE).toContain('no CLI expand');
+    });
     it('marks the cut inside the value, so a reader cannot mistake it for the whole', () => {
         const out = applyResponseBudget(TOOL, result({ description: 'd'.repeat(30_000) }));
         const sc = out.result.structuredContent;

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/agent-presence-schema.js

@@ -45,6 +45,10 @@ 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(),
     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/doc-comments.js

@@ -82,7 +82,7 @@ export function makeListDocCommentsHandler(client) {
 }
 export const postDocCommentToolConfig = {
     title: 'Post a comment on a doc page (or reply to one)',
-    description: 'Add a comment to a doc page. Pass `parentCommentId` to reply (the API flattens reply chains past one level so a reply-of-reply lands as a sibling of the original reply). Optional `anchor` (`{text, before, after}`) attaches the comment to a specific highlight in the body - the frontend uses the surrounding context to re-locate the anchor even after the doc has been edited. Mentions in the content body (`@username`) fire notifications automatically.',
+    description: 'Add a comment to a doc page. Pass `parentCommentId` to reply (the API flattens reply chains past one level so a reply-of-reply lands as a sibling of the original reply). Optional `anchor` (`{text, before, after}`) attaches the comment to a specific highlight in the body - the frontend uses the surrounding context to re-locate the anchor even after the doc has been edited. Mention a person with the markup `@[Full Name](user:<uuid>)` - the UUIDs come from `orboto_list_users`. The response reports `mentions` (tokens that resolved to a user, who is then notified) and `unresolvedMentions` (tokens that named nobody); a mention is never silently dropped.',
     inputSchema: z.object({
         docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
         content: z.string().min(1).max(4000),
@@ -104,10 +104,20 @@ export function makePostDocCommentHandler(client) {
         if (anchor)
             body.anchor = anchor;
         const row = await client.post(`/docs/${docId}/comments`, body);
+        const resolved = row.mentions ?? [];
+        const unresolved = row.unresolvedMentions ?? [];
+        const mentionParts = [];
+        if (resolved.length > 0)
+            mentionParts.push(`notified ${resolved.map((m) => m.fullName ?? m.email).join(', ')}`);
+        if (unresolved.length > 0)
+            mentionParts.push(`UNRESOLVED ${unresolved.map((m) => `${m.token} (${m.reason})`).join(', ')}`);
         return {
             content: [{
                     type: 'text',
-                    text: `Posted comment ${row.id} on doc ${docId}${row.parentCommentId ? ` (reply to ${row.parentCommentId})` : ''}.`,
+                    text: [
+                        `Posted comment ${row.id} on doc ${docId}${row.parentCommentId ? ` (reply to ${row.parentCommentId})` : ''}.`,
+                        ...(mentionParts.length > 0 ? [`Mentions: ${mentionParts.join(' · ')}`] : []),
+                    ].join('\n'),
                 }],
             structuredContent: {
                 id: row.id,
@@ -116,6 +126,8 @@ export function makePostDocCommentHandler(client) {
                 content: row.content,
                 anchor: row.anchor,
                 createdAt: row.createdAt,
+                mentions: resolved,
+                unresolvedMentions: unresolved,
             },
         };
     };

package/dist/tools/docs-ai.js

@@ -90,7 +90,7 @@ function mimetypeFor(filename) {
 }
 export const ingestFileToolConfig = {
     title: 'Ingest a local file into a wiki space (multipart upload)',
-    description: 'Upload a file (PDF / DOCX / Markdown / plain text) into `spaceId` via multipart. The model passes the bytes as a base64 `contentBase64` field (so this works without local FS access on the agent side). Use `filename` to give the doc a meaningful title - the backend sniffs the mimetype but also uses the filename for display. Optional `parentDocId` nests under an existing doc.',
+    description: 'Upload a file (PDF / DOCX / Markdown / plain text) into `spaceId` via multipart. The model passes the bytes as a base64 `contentBase64` field (so this works without local FS access on the agent side). Use `filename` to give the doc a meaningful title - the backend sniffs the mimetype but also uses the filename for display. Optional `parentDocId` nests under an existing doc. The uploaded file is ALSO attached to the doc it produces (ORB-2167): the response names `attachmentId`, `orboto_list_doc_attachments` lists it and `orboto_get_attachment` downloads the original bytes, so the extracted text and its source stay together.',
     inputSchema: z.object({
         spaceId: z.string().uuid(),
         filename: z.string().min(1).describe('Display filename, e.g. "ADR-12-secrets-rotation.pdf".'),
@@ -124,6 +124,7 @@ export function makeIngestFileHandler(client) {
             `  slug: ${res.slug}`,
             `  format: ${res.kind}`,
             `  uploaded ${Math.round(res.sizeBytes / 1024)} KB → ${res.markdownChars} chars of markdown`,
+            `  source attached: ${res.attachmentId ?? '(none)'}`,
         ];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
@@ -134,6 +135,7 @@ export function makeIngestFileHandler(client) {
                 kind: res.kind,
                 sizeBytes: res.sizeBytes,
                 markdownChars: res.markdownChars,
+                attachmentId: res.attachmentId ?? null,
             },
         };
     };

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/get-project-primer.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
 export const getProjectPrimerToolConfig = {
     title: 'Get project primer (AI Context Pack)',
-    description: 'Returns the project\'s auto-generated session primer in a single call: active milestones, ticket counts, recently-closed milestones, top docs, structured primer facts, and recent activity. Primer facts merge three scopes in order Workspace -> Project -> Personal: the Personal block ("Your preferences") is the calling user\'s own personal-scope facts, included only when that user has opted in (ai_preferences_enabled) and never showing another user\'s. Repo briefings (CLAUDE.md / AGENTS.md) are included ONLY when the operator configured them AND the API host can read those files from disk - most deployments will not have them, so do not assume CLAUDE.md / AGENTS.md content is in the response. Token-budget aware - pass `maxTokens` to constrain the output. Input is the project key (e.g. "ORB"), case-insensitive.',
+    description: 'Returns the project\'s auto-generated session primer in a single call: the project vocabulary a create has to get right (ticket type enum, the project\'s labels, its status names per category, its open milestone keys), active milestones, ticket counts, recently-closed milestones, top docs, structured primer facts, and recent activity. Primer facts merge three scopes in order Workspace -> Project -> Personal: the Personal block ("Your preferences") is the calling user\'s own personal-scope facts, included only when that user has opted in (ai_preferences_enabled) and never showing another user\'s. Repo briefings (CLAUDE.md / AGENTS.md) are included ONLY when the operator configured them AND the API host can read those files from disk - most deployments will not have them, so do not assume CLAUDE.md / AGENTS.md content is in the response. Token-budget aware - pass `maxTokens` to constrain the output. Input is the project key (e.g. "ORB"), case-insensitive.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key, case-insensitive.'),
         maxTokens: z.number().int().positive().max(200000).optional()

package/dist/tools/get-ticket.js

@@ -6,11 +6,11 @@ import { specReleaseInfo } from './shared.js';
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
-import { resolveTicketByKey } from './shared.js';
+import { formatDependencySummary, resolveTicketByKey } from './shared.js';
 const COMMENT_PAGE_SIZE = 50;
 export const getTicketToolConfig = {
     title: 'Get ticket details',
-    description: 'Return a ticket\'s decision card: description, status, priority, milestone, assignees, labels, dates, estimate/logged time, checklist progress, parent + sub-ticket count - plus COUNTS for everything omitted (commentCount, gitActivityCount, attachmentCount, childCount). Full blocks are opt-in via `include` (ORB-1698): pass e.g. include: ["comments"] to get the comment bodies, ["git","attachments","children","raci","checklistItems"] likewise. Input is the ticket key like "ACME-42".',
+    description: 'Return a ticket\'s decision card: description, status, priority, milestone, assignees, labels, dates, estimate/logged time, checklist progress, parent + sub-ticket count, the OPEN dependency edges in both directions ("Blocked by" / "Blocks", keys + statuses - the full graph stays on orboto_list_ticket_dependencies) - plus COUNTS for everything omitted (commentCount, gitActivityCount, attachmentCount, childCount). Full blocks are opt-in via `include` (ORB-1698): pass e.g. include: ["comments"] to get the comment bodies, ["git","attachments","children","raci","checklistItems"] likewise. Input is the ticket key like "ACME-42".',
     inputSchema: z.object({
         ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
         include: z.array(z.enum(['comments', 'git', 'attachments', 'children', 'raci', 'checklistItems']))
@@ -91,6 +91,15 @@ export function makeGetTicketHandler(client) {
                     statusCategory: parent.statusCategory ?? null,
                 } : null,
                 childCount: children.length,
+                webUrl: full.webUrl ?? null,
+                blockedBy: {
+                    openCount: full.blockedByOpenCount ?? 0,
+                    tickets: (full.blockedByOpen ?? []).map(dependencyEdge),
+                },
+                blocks: {
+                    openCount: full.blocksOpenCount ?? 0,
+                    tickets: (full.blocksOpen ?? []).map(dependencyEdge),
+                },
                 ...(inc.has('children') ? {
                     children: children.map((c) => ({
                         key: c.ticketKey,
@@ -166,6 +175,14 @@ function swallow404(fallback) {
         throw err;
     };
 }
+function dependencyEdge(e) {
+    return {
+        key: e.ticketKey,
+        title: e.title,
+        status: e.statusName ?? null,
+        ...(e.external ? { external: true } : {}),
+    };
+}
 function formatTicket(ticket, inc, comments, hasMoreComments, checklists, gitActivity, parent, children, attachments, includeHint) {
     const header = [
         `[${ticket.ticketKey}] ${ticket.title}`,
@@ -197,6 +214,9 @@ function formatTicket(ticket, inc, comments, hasMoreComments, checklists, gitAct
         ticket.labels && ticket.labels.length > 0
             ? `Labels: ${ticket.labels.map((l) => l.name).join(', ')}`
             : null,
+        ticket.webUrl ? `Link: ${ticket.webUrl}` : null,
+        formatDependencySummary('Blocked by', ticket.blockedByOpenCount, ticket.blockedByOpen),
+        formatDependencySummary('Blocks', ticket.blocksOpenCount, ticket.blocksOpen),
     ].filter((s) => s !== null);
     if (inc.has('children') && children.length > 0) {
         header.push('', 'Children:');

package/dist/tools/get-timer.js

@@ -4,7 +4,7 @@
 import { z } from 'zod';
 export const getTimerToolConfig = {
     title: 'Get current timer',
-    description: 'Return the caller\'s currently-running stopwatch (or null if no timer is active).',
+    description: 'Return the caller\'s currently-running stopwatch (or null if no timer is active). The lane is resolved from this session\'s instance token, so a timer started by `orboto_claim` / `orboto_timer_start` in the same checkout reads back (ORB-2137); `laneFallback: true` means the timer was matched as the account\'s only running one because this instance\'s lane was empty - another instance started it.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -29,6 +29,7 @@ export function makeGetTimerHandler(client) {
             `Elapsed: ${minutes} min (${totalSeconds}s total)`,
             `Started: ${timer.startedAt}`,
             isPaused ? `Paused: ${timer.pausedAt}` : null,
+            timer.laneFallback ? 'Matched via the single-active-timer fallback - another instance started it.' : null,
             timer.description ? `Note: ${timer.description}` : null,
         ].filter((l) => l !== null).join('\n');
         return {
@@ -44,6 +45,7 @@ export function makeGetTimerHandler(client) {
                     accumulatedSeconds: timer.accumulatedSeconds,
                     totalSeconds,
                     paused: isPaused,
+                    laneFallback: timer.laneFallback === true,
                 },
             },
         };

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

@@ -192,6 +192,57 @@ describe('orboto_get_ticket', () => {
         expect(text).toContain('Comments: 3');
         expect(text).toContain('Checklists: 1/2 done');
     });
+    it('ORB-2169: the card shows the open dependency edges in both directions', async () => {
+        stub([
+            { json: PROJ },
+            { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-5', title: 'Bug', status: 'TODO', statusName: 'To Do', type: 'bug', priority: 'normal', gitActivityCount: 0, parentTicketId: null } },
+            { json: {
+                    id: 't1', projectId: 'p1', ticketKey: 'ACME-5', title: 'Bug', status: 'TODO', statusName: 'To Do',
+                    statusCategory: 'todo', type: 'bug', priority: 'normal', commentCount: 0, gitActivityCount: 0,
+                    blockedByOpenCount: 2,
+                    blockedByOpen: [
+                        { ticketKey: 'ACME-2', title: 'Schema first', statusName: 'In Progress', external: false },
+                        { ticketKey: null, title: null, statusName: null, external: true },
+                    ],
+                    blocksOpenCount: 1,
+                    blocksOpen: [{ ticketKey: 'ACME-9', title: 'Rollout', statusName: 'To Do', external: false }],
+                } },
+            NO_CHILDREN,
+            { json: [] },
+        ]);
+        const res = await makeGetTicketHandler(client)({ ticketKey: 'ACME-5' });
+        const text = res.content[0].text;
+        expect(text).toContain('Blocked by: 2 open - [ACME-2] Schema first (In Progress), External dependency (access restricted)');
+        expect(text).toContain('Blocks: 1 open - [ACME-9] Rollout (To Do)');
+        const sc = res.structuredContent;
+        expect(sc.blockedBy).toEqual({
+            openCount: 2,
+            tickets: [
+                { key: 'ACME-2', title: 'Schema first', status: 'In Progress' },
+                { key: null, title: null, status: null, external: true },
+            ],
+        });
+        expect(sc.blocks).toEqual({
+            openCount: 1,
+            tickets: [{ key: 'ACME-9', title: 'Rollout', status: 'To Do' }],
+        });
+    });
+    it('ORB-2169: a ticket with no dependency edge prints no blocker line', async () => {
+        stub([
+            { json: PROJ },
+            { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-5', title: 'Bug', status: 'TODO', statusName: 'To Do', type: 'bug', priority: 'normal', gitActivityCount: 0, parentTicketId: null } },
+            { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-5', title: 'Bug', status: 'TODO', statusName: 'To Do', statusCategory: 'todo', type: 'bug', priority: 'normal', commentCount: 0, gitActivityCount: 0, blockedByOpenCount: 0, blockedByOpen: [], blocksOpenCount: 0, blocksOpen: [] } },
+            NO_CHILDREN,
+            { json: [] },
+        ]);
+        const res = await makeGetTicketHandler(client)({ ticketKey: 'ACME-5' });
+        const text = res.content[0].text;
+        expect(text).not.toContain('Blocked by');
+        expect(text).not.toContain('Blocks');
+        const sc = res.structuredContent;
+        expect(sc.blockedBy).toEqual({ openCount: 0, tickets: [] });
+        expect(sc.blocks).toEqual({ openCount: 0, tickets: [] });
+    });
     it('ORB-1698: the default response for a 30+-comment ticket stays under the 4k budget', async () => {
         stub([
             { json: PROJ },

package/dist/tools/shared.js

@@ -10,6 +10,17 @@ export async function resolveProjectByKey(client, key) {
         throw err;
     }
 }
+/** ORB-2169 - the "Blocked by" / "Blocks" lines of a ticket decision card. */
+export function formatDependencySummary(label, count, edges) {
+    const total = count ?? 0;
+    if (total === 0)
+        return null;
+    const shown = (edges ?? []).map((e) => (e.ticketKey
+        ? `[${e.ticketKey}] ${e.title ?? ''}${e.statusName ? ` (${e.statusName})` : ''}`.trim()
+        : 'External dependency (access restricted)'));
+    const more = total > shown.length ? `, +${total - shown.length} more` : '';
+    return `${label}: ${total} open - ${shown.join(', ')}${more}`;
+}
 /**
  * ORB-1699 - the ONE agent-facing list-row builder. A list call is a
  * decision aid ("which of these do I open?"); the default row carries

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/ticket-writes.js

@@ -54,6 +54,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. '
+        + '**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({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
@@ -74,12 +75,26 @@ export const createTicketToolConfig = {
         allowLanguageMismatch: z.boolean().optional().describe('Override the language block.'),
         allowDuplicate: z.boolean().optional().describe('Override the duplicate block.'),
         duplicateJustification: z.string().optional().describe('Why this is not a duplicate.'),
+        dryRun: z.boolean().optional().describe('Pre-flight only: return the verdicts, create nothing.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeCreateTicketHandler(client) {
     return async (input) => {
         const project = await resolveProjectByKey(client, input.projectKey);
+        if (input.dryRun) {
+            const parentTicketId = input.parentTicketKey
+                ? (await resolveTicketByKey(client, input.parentTicketKey)).id
+                : undefined;
+            const preflight = await client.post(`/projects/${project.id}/tickets/preflight`, {
+                title: input.title,
+                description: input.description ?? null,
+                ...(input.type ? { type: input.type } : {}),
+                ...(input.labels && input.labels.length > 0 ? { labelNames: input.labels } : {}),
+                ...(parentTicketId ? { parentTicketId } : {}),
+            });
+            return preflightResult(preflight, input.projectKey);
+        }
         const body = {
             title: input.title,
             description: input.description ?? null,
@@ -153,6 +168,43 @@ export function makeCreateTicketHandler(client) {
         };
     };
 }
+/**
+ * ORB-2162 - render the dry run: one line per verdict plus the next step.
+ * Never an error result - a blocking verdict is the answer the caller asked
+ * for, not a failed call.
+ */
+function preflightResult(preflight, projectKey) {
+    const icon = { ok: '✓', warn: '⚠', block: '⛔' };
+    const lines = [
+        preflight.ok
+            ? `✓ Pre-flight clean for ${projectKey} - re-send the same arguments without dryRun to create the ticket.`
+            : `⛔ Pre-flight BLOCKED for ${projectKey} (${preflight.blockedBy.join(', ')}) - nothing was created. Fix the payload and run the pre-flight again.`,
+        `  ${icon[preflight.verdicts.language.severity]} language: ${preflight.verdicts.language.message}`,
+        `  ${icon[preflight.verdicts.type.severity]} type: ${preflight.verdicts.type.message}`,
+        `  ${icon[preflight.verdicts.labels.severity]} labels: ${preflight.verdicts.labels.message}`,
+        `  ${icon[preflight.verdicts.duplicates.severity]} duplicates: ${preflight.verdicts.duplicates.message}`,
+    ];
+    for (const c of preflight.verdicts.duplicates.candidates) {
+        lines.push(`      - [${c.ticketKey ?? c.id.slice(0, 8)}] "${c.title}" (${formatSimilarity(c)})`);
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: {
+            preflight: {
+                ok: preflight.ok,
+                severity: preflight.severity,
+                blockedBy: preflight.blockedBy,
+                verdicts: {
+                    ...preflight.verdicts,
+                    duplicates: {
+                        ...preflight.verdicts.duplicates,
+                        candidates: trimSimilarEntries(preflight.verdicts.duplicates.candidates),
+                    },
+                },
+            },
+        },
+    };
+}
 /** Append the summaryWarning (ORB-1332) to a move/close result - extra text
  *  line + the structured field - so both the model's prose read and any
  *  structured consumer see it. No-op when the backend didn't warn. */
@@ -354,9 +406,22 @@ export function makeDeleteTicketHandler(client) {
         };
     };
 }
+/** ORB-2168 - the "who did this reach" line of a comment write. */
+function mentionLine(created) {
+    const resolved = created.mentions ?? [];
+    const unresolved = created.unresolvedMentions ?? [];
+    if (resolved.length === 0 && unresolved.length === 0)
+        return null;
+    const parts = [];
+    if (resolved.length > 0)
+        parts.push(`notified ${resolved.map((m) => m.fullName ?? m.email).join(', ')}`);
+    if (unresolved.length > 0)
+        parts.push(`UNRESOLVED ${unresolved.map((m) => `${m.token} (${m.reason})`).join(', ')}`);
+    return `Mentions: ${parts.join(' · ')}`;
+}
 export const commentToolConfig = {
     title: 'Post a comment',
-    description: 'Post Markdown. isInternal=true hides it from guests. Attachment drafts are claimed atomically with the comment; never use public ticket uploads for private comments.',
+    description: 'Post Markdown. isInternal=true hides it from guests. Attachment drafts are claimed atomically with the comment; never use public ticket uploads for private comments. Mention a person with the markup `@[Full Name](user:<uuid>)` - the UUIDs come from `orboto_list_users`. The response reports `mentions` (tokens that resolved to a user, who is then notified) and `unresolvedMentions` (tokens that named nobody); a mention is never silently dropped.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         text: z.string().min(1),
@@ -369,16 +434,22 @@ export function makeCommentHandler(client) {
     return async ({ ticketKey, text, isInternal, attachmentDraftIds }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
         const created = await client.post(`/tickets/${ticket.id}/comments`, { content: text, isInternal: isInternal ?? false, ...(attachmentDraftIds ? { attachmentDraftIds } : {}) });
+        const mentions = mentionLine(created);
         return {
             content: [{
                     type: 'text',
-                    text: `Posted comment on [${ticket.ticketKey}]${created.isInternal ? ' (internal)' : ''}.`,
+                    text: [
+                        `Posted comment on [${ticket.ticketKey}]${created.isInternal ? ' (internal)' : ''}.`,
+                        ...(mentions ? [mentions] : []),
+                    ].join('\n'),
                 }],
             structuredContent: {
                 ticketKey: ticket.ticketKey,
                 commentId: created.id,
                 isInternal: created.isInternal,
                 createdAt: created.createdAt,
+                mentions: created.mentions ?? [],
+                unresolvedMentions: created.unresolvedMentions ?? [],
             },
         };
     };

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

@@ -275,6 +275,38 @@ describe('orboto_create_ticket', () => {
         expect(createUrl).toContain('allowDuplicate=true');
         expect(createBody.duplicateJustification).toBe('Different provider - Stripe vs PayPal.');
     });
+    it('dryRun hits the pre-flight route, creates nothing and reports every verdict (ORB-2162)', async () => {
+        const calls = stub([
+            { json: PROJ },
+            {
+                json: {
+                    ok: false,
+                    severity: 'block',
+                    blockedBy: ['labels'],
+                    verdicts: {
+                        language: { severity: 'ok', code: null, detected: null, expected: 'en', enforced: false, message: 'Language matches the workspace default (en).' },
+                        type: { severity: 'ok', value: 'bug', allowed: ['epic', 'story', 'task', 'bug'], message: 'Type "bug" is valid.' },
+                        labels: { severity: 'block', requested: ['ghost'], resolved: [], unknown: ['ghost'], ambiguous: [], available: ['infra'], message: 'Label "ghost" does not exist on this project. Create it first, then reference it by name.' },
+                        duplicates: { severity: 'warn', threshold: 0, topSimilarity: 0.41, mode: 'tsvector', message: 'Possible duplicates - review the candidates before creating (top match 41%).', candidates: [{ id: 'x1', ticketKey: 'ACME-3', title: 'Timer reads null', statusName: 'To Do', statusColor: null, statusCategory: 'todo', similarity: 0.41, matchMode: 'tsvector' }] },
+                    },
+                },
+            },
+        ]);
+        const res = await makeCreateTicketHandler(client)({
+            projectKey: 'ACME', title: 'Timer reads null after a claim', type: 'bug', labels: ['ghost'], dryRun: true,
+        });
+        expect(calls[1].method).toBe('POST');
+        expect(calls[1].url).toBe('https://orboto.example.com/projects/p1/tickets/preflight');
+        expect(calls[1].body).toMatchObject({ title: 'Timer reads null after a claim', type: 'bug', labelNames: ['ghost'] });
+        const text = res.content[0].text;
+        expect(text).toContain('Pre-flight BLOCKED for ACME (labels)');
+        expect(text).toContain('does not exist on this project');
+        expect(text).toContain('ACME-3');
+        expect(res.isError).toBeUndefined();
+        const structured = res.structuredContent;
+        expect(structured.preflight.ok).toBe(false);
+        expect(structured.preflight.blockedBy).toEqual(['labels']);
+    });
 });
 describe('orboto_update_ticket', () => {
     it('PATCHes only the supplied fields, leaves others untouched', async () => {

package/dist/tools/work-sessions.js

@@ -8,6 +8,16 @@ import { mcpInstanceToken, resolveTicketByKey } from './shared.js';
 import { validateRulesReceipt } from '../required-rules.js';
 export { makeWorkNextHandler, workNextToolConfig } from './work-next.js';
 import { GIT_HEALTH_REASON_TEXT, ResourceClaimShape, } from './work-sessions-shared.js';
+/** ORB-2173 - the phrase for a `bookedBy` value other than `finish` (the
+ *  ordinary "this call stopped it" path, which stays silent). */
+function describeBookedBy(bookedBy) {
+    switch (bookedBy) {
+        case 'transition': return 'by the status transition';
+        case 'lane_stop': return 'by an earlier timer stop';
+        case 'expiry': return 'by the lease expiring';
+        default: return null;
+    }
+}
 function parseClaimConflicts(err) {
     try {
         return JSON.parse(err.body).claimConflicts;
@@ -328,12 +338,21 @@ export function makeWorkSessionFinishHandler(client) {
             ...(args.commitSha ? { commitSha: args.commitSha } : {}),
             ...(args.verification ? { verification: args.verification } : {}),
         });
+        const bookedByPhrase = describeBookedBy(res.bookedBy);
         const text = res.changed
-            ? `Session ${args.sessionId} ${res.session.status}. Booked ${res.durationMinutes} min; the ${res.session.role} lease on ${res.session.ticketKey ?? res.session.ticketId} is free.`
-            : `Session ${args.sessionId} was already ${res.session.status} - nothing to book. (Idempotent finish.)`;
+            ? `Session ${args.sessionId} ${res.session.status}. Booked ${res.durationMinutes} min${bookedByPhrase ? ` (${bookedByPhrase})` : ''}; the ${res.session.role} lease on ${res.session.ticketKey ?? res.session.ticketId} is free.`
+            : res.durationMinutes > 0
+                ? `Session ${args.sessionId} was already ${res.session.status} - ${res.durationMinutes} min already booked${bookedByPhrase ? ` (${bookedByPhrase})` : ''}. (Idempotent finish.)`
+                : `Session ${args.sessionId} was already ${res.session.status} - nothing to book. (Idempotent finish.)`;
         return {
             content: [{ type: 'text', text }],
-            structuredContent: { session: res.session, durationMinutes: res.durationMinutes, changed: res.changed },
+            structuredContent: {
+                session: res.session,
+                durationMinutes: res.durationMinutes,
+                timeEntryId: res.timeEntryId,
+                bookedBy: res.bookedBy,
+                changed: res.changed,
+            },
         };
     };
 }
@@ -368,10 +387,13 @@ export function makeWorkFinishHandler(client) {
             ...(args.targetCategory ? { targetCategory: args.targetCategory } : {}),
             ...(args.note ? { note: args.note } : {}),
         });
+        const bookedByPhrase = describeBookedBy(res.bookedBy);
         const lines = [
             res.changed
-                ? `Session ${args.sessionId} ${res.session.status}. Booked ${res.durationMinutes} min; the ${res.session.role} lease on ${res.session.ticketKey ?? res.session.ticketId} is free.`
-                : `Session ${args.sessionId} was already ${res.session.status} - nothing to book. (Idempotent finish.)`,
+                ? `Session ${args.sessionId} ${res.session.status}. Booked ${res.durationMinutes} min${bookedByPhrase ? ` (${bookedByPhrase})` : ''}; the ${res.session.role} lease on ${res.session.ticketKey ?? res.session.ticketId} is free.`
+                : res.durationMinutes > 0
+                    ? `Session ${args.sessionId} was already ${res.session.status} - ${res.durationMinutes} min already booked${bookedByPhrase ? ` (${bookedByPhrase})` : ''}. (Idempotent finish.)`
+                    : `Session ${args.sessionId} was already ${res.session.status} - nothing to book. (Idempotent finish.)`,
         ];
         if (res.session.commitSha) {
             lines.push(`Commit ${res.session.commitSha}${res.session.commitVerified ? ' (verified by git ingestion)' : ' (attested - pending git verification)'}.`);
@@ -387,6 +409,8 @@ export function makeWorkFinishHandler(client) {
             structuredContent: {
                 session: res.session,
                 durationMinutes: res.durationMinutes,
+                timeEntryId: res.timeEntryId,
+                bookedBy: res.bookedBy,
                 changed: res.changed,
                 ticketTransitioned: res.ticketTransitioned,
                 ticketStatusCategory: res.ticketStatusCategory,

package/dist/tools/work-sessions.test.js

@@ -131,6 +131,36 @@ describe('orboto_work_session_finish', () => {
         expect(res.isError).toBeUndefined();
         expect(res.content[0].text).toContain('Idempotent finish');
     });
+    it('ORB-2173 - reports the minutes a status transition already booked instead of zero', async () => {
+        stub([{
+                json: {
+                    session: { ...SESSION, status: 'active', activeTimerId: null },
+                    durationMinutes: 106,
+                    timeEntryId: 'te1',
+                    bookedBy: 'transition',
+                    changed: true,
+                },
+            }]);
+        const res = await makeWorkSessionFinishHandler(client)({ sessionId: 'ws1' });
+        const text = res.content[0].text;
+        expect(text).toContain('Booked 106 min (by the status transition)');
+        expect(res.structuredContent.bookedBy).toBe('transition');
+    });
+    it('ORB-2173 - an idempotent re-finish still reports the already-booked minutes and source', async () => {
+        stub([{
+                json: {
+                    session: { ...SESSION, status: 'finished' },
+                    durationMinutes: 42,
+                    timeEntryId: 'te2',
+                    bookedBy: 'lane_stop',
+                    changed: false,
+                },
+            }]);
+        const res = await makeWorkSessionFinishHandler(client)({ sessionId: 'ws1' });
+        const text = res.content[0].text;
+        expect(text).toContain('42 min already booked (by an earlier timer stop)');
+        expect(text).toContain('Idempotent finish');
+    });
 });
 describe('ORB-1612 - orboto_work_finish', () => {
     it('reports the ticket transition and the completion note', async () => {
@@ -196,6 +226,25 @@ describe('ORB-1612 - orboto_work_finish', () => {
         expect(text).toContain('Idempotent finish');
         expect(text).toContain('No completion note posted');
     });
+    it('ORB-2173 - reports the minutes a status transition already booked instead of zero', async () => {
+        stub([
+            {
+                json: {
+                    session: { ...SESSION, status: 'active', activeTimerId: null },
+                    durationMinutes: 106,
+                    timeEntryId: 'te1',
+                    bookedBy: 'transition',
+                    changed: true,
+                    ticketTransitioned: false,
+                    ticketStatusCategory: 'in_review',
+                    noteCommented: true,
+                },
+            },
+        ]);
+        const res = await makeWorkFinishHandler(client)({ sessionId: 'ws1' });
+        expect(res.content[0].text).toContain('Booked 106 min (by the status transition)');
+        expect(res.structuredContent.bookedBy).toBe('transition');
+    });
     it('surfaces a deliveryModeWarning without failing the call', async () => {
         stub([
             {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.200.1",
+  "version": "0.202.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",