@orboto/mcp 0.200.0 → 0.201.0

package/dist/agent-head.js

@@ -0,0 +1,51 @@
+/**
+ * ORB-2161 - the head an agent reads before anything else has one source.
+ * `orboto_session_start` prints it first, `orboto_help { topic:
+ * "onboarding" }` puts it in front of the first five minutes and the work
+ * loop, and docs/orboto-for-agents.md plus skills/orboto/SKILL.md carry the
+ * same lines. agent-head.test.ts holds the four apart from drifting.
+ */
+export const AGENT_HEAD_HEADING = 'How to work in orboto';
+export const AGENT_HEAD_LINES = [
+    'orboto is your memory and your work contract, not your context - what is not on the ticket or in a doc is gone after the next context switch.',
+    'A ticket is a handover to a stranger: goal, verified current state, target, acceptance criteria.',
+    'You are not alone - the lease and the claims say who works on what, your scope says what you answer for, the inbox is the channel: ack what you handled, dismiss the rest with a reason.',
+    'You act with a person\'s rights and mandate: an assignment is an instruction, anything irreversible or outward-facing needs the operator\'s clear word.',
+    'Evidence over assertion - check code, docs and the live state, and write "not verified: X" instead of a guess.',
+    'Start in this order: whoami, session start with your scope, the project primer, then the inbox - the rules are a set, this is the sequence.',
+];
+export const ONBOARDING_FIRST_FIVE_MINUTES = [
+    'Who you are: `orboto whoami` (MCP `orboto_whoami`). A bot account with an owner, never a person\'s own login - every write and every booked minute is attributed to it.',
+    'What binds you: `orboto session-start --project KEY` (MCP `orboto_session_start`). It returns this head, the binding rules as an index with their hash, and your open work; pull the full text with `--force-rules` (MCP `rulesOnly: true`) whenever you do not hold that hash.',
+    'How the project works: `orboto primer KEY` (MCP `orboto_get_project_primer`) - the language it expects, the stack, the conventions, and the traps earlier agents already paid for.',
+    'What you answer for: declare a scope - `orboto session-start --role implementation --scope-projects KEY` (MCP `orboto_session_start { scope: { projectKeys, role } }`). Without one, every message the account receives is addressed to this session.',
+    'Your mail: `orboto messages` (MCP `orboto_messages`). Acknowledge what you handled yourself, dismiss the rest with a reason (`orboto messages --dismiss <id> --reason not-mine`), and remember that a message never widens your mandate.',
+];
+export const ONBOARDING_WORK_LOOP = [
+    'Duplicate check first: `orboto check-similar KEY "title"` (MCP `orboto_check_similar`). Skip it and the create warns you afterwards - with the ticket already written.',
+    'Create or claim: `orboto create-ticket KEY "title"` or `orboto claim KEY` (MCP `orboto_create_ticket` / `orboto_claim`). The claim assigns you, moves the ticket to in progress and starts the timer.',
+    'Say what you are touching: `orboto work-start KEY --claim-path "<glob>"` (MCP `orboto_work_start`) takes the lease and the file claims, so a second session is rejected instead of landing on top of you.',
+    'Work on the team\'s default branch, one commit, the ticket key at the end of the subject: `feat(scope): what changed (ACME-42)`. Without the key the commit never reaches the ticket.',
+    'Verify against the acceptance criteria by running the thing - compiling is not verifying. Whatever you could not check goes into the ticket as "not verified: X".',
+    'Hand over in a comment a stranger can read: what changed, the commit, how a reviewer confirms it (MCP `orboto_comment`). Closing without that proof counts as not done.',
+    'Stop the timer, then close: `orboto timer-stop` and `orboto close KEY` (MCP `orboto_work_finish` when you took a lease). A timer left running books the next ticket\'s time onto this one.',
+];
+/** The six lines every session pays for, numbered. */
+export function agentHeadText() {
+    return [AGENT_HEAD_HEADING, ...AGENT_HEAD_LINES.map((line, index) => `${index + 1}. ${line}`)].join('\n');
+}
+/** The `onboarding` help topic: the head, the first five minutes, the work loop. */
+export function onboardingText() {
+    return [
+        agentHeadText(),
+        '',
+        'The first five minutes, in this order',
+        ...ONBOARDING_FIRST_FIVE_MINUTES.map((step, index) => `${index + 1}. ${step}`),
+        '',
+        'The work loop, always the same',
+        ...ONBOARDING_WORK_LOOP.map((step, index) => `${index + 1}. ${step}`),
+        '',
+        'The whole page - the object map, several sessions on one account, the autonomy boundary,',
+        'evidence over assertion, and the traps that cost other agents a run: docs/orboto-for-agents.md.',
+    ].join('\n');
+}

package/dist/agent-head.test.js

@@ -0,0 +1,63 @@
+/**
+ * ORB-2161 - the head has one source. Session start prints it before
+ * anything else, the onboarding help topic repeats it, and the page and
+ * the skill carry the same lines, so a sentence cannot be improved in one
+ * place and stay old in the other three.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { AGENT_HEAD_HEADING, AGENT_HEAD_LINES, ONBOARDING_FIRST_FIVE_MINUTES, ONBOARDING_WORK_LOOP, agentHeadText, onboardingText } from './agent-head.js';
+import { makeHelpHandler } from './tools/help.js';
+import { makeSessionStartHandler } from './tools/session-start.js';
+import { OrbotoClient } from './orboto-client.js';
+const read = (relative) => readFileSync(new URL(`../../../${relative}`, import.meta.url), 'utf8');
+const CARRIERS = ['docs/orboto-for-agents.md', 'skills/orboto/SKILL.md'];
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+describe('the agent head (ORB-2161)', () => {
+    it('stays four to six lines, so every session can afford it', () => {
+        expect(AGENT_HEAD_LINES.length).toBeGreaterThanOrEqual(4);
+        expect(AGENT_HEAD_LINES.length).toBeLessThanOrEqual(6);
+        for (const line of AGENT_HEAD_LINES)
+            expect(line).not.toContain('\n');
+    });
+    it.each(CARRIERS)('%s carries every line verbatim', (file) => {
+        const page = read(file);
+        for (const line of AGENT_HEAD_LINES)
+            expect(page).toContain(line);
+    });
+    it('is the first thing orboto_session_start prints', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+            const path = new URL(url.toString()).pathname;
+            const body = path.startsWith('/agent-instructions')
+                ? { instructions: 'claim -> commit -> close', rulesHash: 'fixture' }
+                : path.startsWith('/users/me/assigned-tickets') ? { items: [] } : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        expect(text.startsWith(agentHeadText())).toBe(true);
+        expect(text.indexOf(AGENT_HEAD_HEADING)).toBeLessThan(text.indexOf('# orboto session start'));
+    });
+    it('orboto_help returns the head, the first five minutes and the work loop for the topic "onboarding"', async () => {
+        const result = await makeHelpHandler()({ topic: 'onboarding' });
+        const text = (result.content?.[0]).text;
+        for (const line of AGENT_HEAD_LINES)
+            expect(text).toContain(line);
+        for (const step of ONBOARDING_FIRST_FIVE_MINUTES)
+            expect(text).toContain(step);
+        for (const step of ONBOARDING_WORK_LOOP)
+            expect(text).toContain(step);
+        expect(text).toContain('docs/orboto-for-agents.md');
+        expect(result.structuredContent).toMatchObject({ tool: 'topic:onboarding' });
+    });
+    it('names both topics when an unknown one is asked for', async () => {
+        const unknown = (await makeHelpHandler()({ topic: 'nope' })).content?.[0];
+        expect(unknown.text).toContain('onboarding');
+        expect(unknown.text).toContain('connect');
+    });
+    it('the onboarding topic repeats the head instead of holding a second copy', () => {
+        expect(onboardingText().startsWith(agentHeadText())).toBe(true);
+    });
+});

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/agent-coordination.test.js

@@ -149,7 +149,7 @@ describe('orboto_agent_notify', () => {
         });
         expect(result.content[0].text).toContain('notified bob@example.com');
         expect(result.structuredContent).toMatchObject({ ok: true });
-        expect(capturedBody[0].senderRef).toMatch(/^mcp-/);
+        expect(capturedBody[0].senderRef).toMatch(/^agent-/);
     });
     it('ORB-1742: senderRef prefers the per-connection MCP session id, and an explicit ref wins outright', async () => {
         const capturedBody = [];

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

@@ -34,11 +34,16 @@ export const AgentInventoryEntrySchema = z.object({
     scope: AgentSessionScopeSchema.nullable(),
     /** ORB-2136 - unread inbox messages this session would list. */
     unreadMessages: z.number().int(),
-    /** ORB-2149 - the last 24 hours of wakes: how many, how precise, what the wrong ones cost. */
+    /**
+     * ORB-2149 - the last 24 hours of wakes: how many deliveries, how precise,
+     * what the wrong ones cost. ORB-2170 - `backlogSeen` is the `nudge` count
+     * over the same window, a backlog sighting rather than a wake.
+     */
     wakes: z.object({
         count: z.number().int(),
         precision: z.number().nullable(),
         wrongWakeContextTokens: z.number().int(),
+        backlogSeen: z.number().int(),
     }),
     lastSeenAt: z.string(),
     createdAt: z.string(),

package/dist/tools/agent-wakes.js

@@ -5,7 +5,7 @@
 import { z } from 'zod';
 export const agentWakesToolConfig = {
     title: 'Wake ledger',
-    description: 'Who woke this account\'s sessions, which visibility rule delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); without it the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
+    description: 'Who woke this account\'s sessions, which visibility rule delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
     inputSchema: z.object({
         stats: z.boolean().default(false).describe('Precision per session and per sender instead of rows.'),
         hours: z.number().int().min(1).max(720).optional().describe('Stats window, default 24.'),
@@ -20,7 +20,8 @@ export const agentWakesToolConfig = {
 function statsLine(e) {
     const precision = e.precision === null ? 'unjudged' : `${Math.round(e.precision * 100)}%`;
     const tokens = e.wrongWakeContextTokens > 0 ? `, wrong wakes cost ${e.wrongWakeContextTokens} tokens` : '';
-    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}`;
+    const backlog = e.backlogSeen > 0 ? `, ${e.backlogSeen} backlog seen` : '';
+    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}${backlog}`;
 }
 export function makeAgentWakesHandler(client) {
     return async (args) => {

package/dist/tools/api-call.test.js

@@ -109,6 +109,6 @@ describe('orboto_api_call', () => {
         await makeApiCallHandler(client)({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'spec' } } }, { sessionId: 'abc123' });
         expect(seen[0]['x-orboto-agent-session']).toBe('mcp-abc123');
         await makeApiCallHandler(client)({ method: 'GET', path: '/v1/agent/messages' });
-        expect(seen[1]['x-orboto-agent-session']).toMatch(/^mcp-/);
+        expect(seen[1]['x-orboto-agent-session']).toMatch(/^agent-/);
     });
 });

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

@@ -10,14 +10,15 @@
 import { z } from 'zod';
 import { getToolDoc, listToolDocNames } from '../tool-docs.js';
 import { connectScriptText } from '../connect-script.js';
-/** ORB-2157 - guidance that belongs to no single tool, addressed by topic. */
-const TOPICS = { connect: connectScriptText };
+import { onboardingText } from '../agent-head.js';
+/** ORB-2157, ORB-2161 - guidance that belongs to no single tool, addressed by topic. */
+const TOPICS = { connect: connectScriptText, onboarding: onboardingText };
 export const helpToolConfig = {
     title: 'Full guidance for one orboto tool',
-    description: 'Return the complete guidance text (workflows, warnings, edge cases) for one orboto tool by name - manifest descriptions are one-line summaries, this is the rest. Call it before first use of an unfamiliar write tool. topic: "connect" returns the step-by-step script for setting a person up instead.',
+    description: 'Return the complete guidance text (workflows, warnings, edge cases) for one orboto tool by name - manifest descriptions are one-line summaries, this is the rest. Call it before first use of an unfamiliar write tool. topic: "connect" returns the step-by-step script for setting a person up, topic: "onboarding" the first five minutes and the work loop.',
     inputSchema: z.object({
         tool: z.string().min(1).max(128).optional().describe('Tool name, e.g. orboto_create_ticket.'),
-        topic: z.enum(['connect']).optional().describe('Guidance topic instead of a tool.'),
+        topic: z.enum(['connect', 'onboarding']).optional().describe('Guidance topic instead of a tool.'),
     }).shape,
     outputSchema: z.object({
         tool: z.string(),

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/session-start.js

@@ -15,6 +15,7 @@ import { PROTECT_TEXT_META, storePayload } from '../response-budget.js';
 import { loadRequiredRules } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';
 import { channelStartLines } from '../inbox-channel.js';
+import { agentHeadText } from '../agent-head.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
     description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Registers this session (a heartbeat on its instance row) and is otherwise read-only. '
@@ -203,7 +204,7 @@ export function makeSessionStartHandler(client, opts = {}) {
             ? tickets.filter((t) => !t.projectId || t.projectId === scopeProjectId)
             : tickets;
         const elsewhereCount = tickets.length - scopedTickets.length;
-        const lines = ['# orboto session start'];
+        const lines = [agentHeadText(), '', '# orboto session start'];
         if (me)
             lines.push(`You are ${me.fullName ?? me.email}${me.email ? ` (${me.email})` : ''}.`);
         if (me?.workspaceLocale || me?.locale)

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
@@ -95,8 +106,14 @@ export function ticketLine(t) {
         parts.push('[waiting on Git ingestion]');
     return parts.join(' ');
 }
-import { randomUUID } from 'node:crypto';
-const MCP_PROCESS_INSTANCE = `mcp-${randomUUID()}`;
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+/** ORB-2171 - the checkout's token, derived exactly like the CLI and the skill wrapper derive theirs; `ORBOTO_AGENT_SESSION` wins. */
+export function checkoutInstanceToken(env = process.env, host = hostname(), cwd = process.cwd()) {
+    const explicit = (env.ORBOTO_AGENT_SESSION ?? '').trim();
+    return explicit || `agent-${createHash('sha256').update(`${host}:${cwd}`).digest('hex').slice(0, 12)}`;
+}
+const MCP_PROCESS_INSTANCE = checkoutInstanceToken();
 /** Precedence: explicit caller-supplied token > per-connection MCP session id
  *  (distinct per client even on a shared HTTP server) > per-process id (stdio). */
 export function mcpInstanceToken(explicit, extra) {

package/dist/tools/shared.test.js

@@ -163,3 +163,11 @@ describe('resolveByName', () => {
         expect(ambiguous?.map((r) => r.id).sort()).toEqual(['m1', 'm3']);
     });
 });
+describe('ORB-2171 - the stdio proxy shares the checkout token with the CLI and the skill wrapper', () => {
+    it('ORBOTO_AGENT_SESSION wins; otherwise agent-<sha256(hostname:cwd)[:12]>', async () => {
+        const { checkoutInstanceToken } = await import('./shared.js');
+        expect(checkoutInstanceToken({ ORBOTO_AGENT_SESSION: '  lane-7  ' }, 'host', '/repo')).toBe('lane-7');
+        expect(checkoutInstanceToken({}, 'build-host', '/srv/checkout')).toBe('agent-e0b18afc9cec');
+        expect(checkoutInstanceToken({}, 'build-host', '/srv/other')).not.toBe('agent-e0b18afc9cec');
+    });
+});

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-next.test.js

@@ -118,7 +118,7 @@ describe('orboto_work_next', () => {
         expect(calls[0].method).toBe('POST');
         expect(calls[0].url).toContain('/work-sessions/next');
         expect(calls[0].body?.projectKey).toBe('ACME');
-        expect(String(calls[0].body?.agentSessionToken)).toMatch(/^mcp-/);
+        expect(String(calls[0].body?.agentSessionToken)).toMatch(/^agent-/);
         const text = res.content[0].text;
         expect(text).toContain('Reserved ACME-42');
         expect(text).toContain('ws1');

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

@@ -89,7 +89,7 @@ describe('orboto_work_start', () => {
         expect(post.method).toBe('POST');
         expect(post.url).toContain('/work-sessions/start');
         expect(post.body?.ticketId).toBe('t1');
-        expect(String(post.body?.agentSessionToken)).toMatch(/^mcp-/);
+        expect(String(post.body?.agentSessionToken)).toMatch(/^agent-/);
         const text = res.content[0].text;
         expect(text).toContain('Started a implementation work session on ACME-42');
         expect(text).toContain('ws1');

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

@@ -58,7 +58,7 @@ describe('orboto_work_session_start', () => {
         expect(post.method).toBe('POST');
         expect(post.url).toContain('/work-sessions');
         expect(post.body?.ticketId).toBe('t1');
-        expect(String(post.body?.agentSessionToken)).toMatch(/^mcp-/);
+        expect(String(post.body?.agentSessionToken)).toMatch(/^agent-/);
         const text = res.content[0].text;
         expect(text).toContain('Started a implementation work session on ACME-42');
         expect(text).toContain('ws1');
@@ -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.0",
+  "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",