@orboto/mcp 0.200.1 → 0.201.0

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