@orboto/mcp 0.195.1 → 0.198.0

package/dist/tools/sentry.js

@@ -0,0 +1,85 @@
+/**
+ * ORB-2123 - `orboto_sentry`: the Sentry connector in one tool. Mapping
+ * CRUD, health, secret rotation, the triage-lane binding and the lane's
+ * verdict write share an `action` so the full manifest stays under its
+ * shrink-only ceiling.
+ */
+import { z } from 'zod';
+import { mcpInstanceToken, resolveProjectByKey, resolveTicketByKey } from './shared.js';
+const ACTIONS = ['list', 'health', 'connect', 'update', 'rotate_secret', 'disconnect', 'triage_lane', 'verdict'];
+export const sentryToolConfig = {
+    title: 'Sentry connector',
+    description: 'Sentry connector (ORB-2123): list, health, connect (orgSlug, projectSlug, clientSecret), update (triageMode comment|fix_branch), rotate_secret, disconnect, triage_lane (laneId, empty unbinds), verdict (ticketKey, verdict known_fixed|regression|new, summary). Secrets never come back; docs/sentry-intake.md.',
+    inputSchema: z.object({
+        action: z.enum(ACTIONS),
+        projectKey: z.string().min(1),
+        connectionId: z.string().uuid().optional(),
+        orgSlug: z.string().optional(),
+        projectSlug: z.string().optional(),
+        clientSecret: z.string().optional(),
+        triageMode: z.enum(['comment', 'fix_branch']).optional(),
+        laneId: z.string().optional(),
+        ticketKey: z.string().optional(),
+        verdict: z.enum(['known_fixed', 'regression', 'new']).optional(),
+        summary: z.string().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+function line(c) {
+    return `- ${c.id} ${c.orgSlug}/${c.projectSlug} mode=${c.triageMode} ${c.enabled ? 'enabled' : 'paused'} token=${c.hasAuthToken ? 'yes' : 'no'} deliveries=${c.webhookCount} last=${c.lastWebhookAt ?? 'never'}${c.lastError ? ` error=${c.lastError}` : ''}\n  webhook ${c.webhookUrl}`;
+}
+function text(result, summary) {
+    return { content: [{ type: 'text', text: summary }], structuredContent: result };
+}
+export function makeSentryHandler(client) {
+    return async (args) => {
+        const project = await resolveProjectByKey(client, args.projectKey);
+        const need = (field) => { if (args[field] === undefined || args[field] === null || args[field] === '')
+            throw new Error(`${args.action} needs ${String(field)}.`); };
+        if (args.action === 'list') {
+            const rows = await client.get(`/projects/${project.id}/sentry-connections`);
+            return text({ connections: rows }, rows.length ? rows.map(line).join('\n') : `No Sentry connection on ${project.key}.`);
+        }
+        if (args.action === 'connect') {
+            need('orgSlug');
+            need('projectSlug');
+            need('clientSecret');
+            const created = await client.post(`/projects/${project.id}/sentry-connections`, {
+                orgSlug: args.orgSlug, projectSlug: args.projectSlug, clientSecret: args.clientSecret,
+                ...(args.triageMode ? { triageMode: args.triageMode } : {}),
+            });
+            const { webhookUrlWarning, ...connection } = created;
+            return text({ connection }, `Connected ${created.orgSlug}/${created.projectSlug} to ${project.key} (${created.id}).\n${line(created)}${webhookUrlWarning ? `\nWarning: ${webhookUrlWarning.message}` : ''}`);
+        }
+        need('connectionId');
+        if (args.action === 'health') {
+            const health = await client.get(`/projects/${project.id}/sentry-connections/${args.connectionId}/health`);
+            return text(health, `${health.healthy ? 'healthy' : 'needs attention'} - deliveries=${health.webhookCount} last=${health.lastWebhookAt ?? 'never'} linked=${health.linkedIssues} open=${health.openLinkedIssues}${health.lastError ? ` error=${health.lastError}` : ''}`);
+        }
+        if (args.action === 'update') {
+            need('triageMode');
+            const row = await client.patch(`/projects/${project.id}/sentry-connections/${args.connectionId}`, { triageMode: args.triageMode });
+            return text({ connection: row }, `Triage mode is now ${row.triageMode}.\n${line(row)}`);
+        }
+        if (args.action === 'rotate_secret') {
+            need('clientSecret');
+            const row = await client.post(`/projects/${project.id}/sentry-connections/${args.connectionId}/rotate-secret`, { clientSecret: args.clientSecret });
+            return text({ connection: row }, `Client secret replaced on ${row.id}; deliveries signed with the old secret are rejected from now on.`);
+        }
+        if (args.action === 'disconnect') {
+            await client.delete(`/projects/${project.id}/sentry-connections/${args.connectionId}`);
+            return text({ deleted: true, connectionId: args.connectionId }, `Disconnected ${args.connectionId} from ${project.key}.`);
+        }
+        if (args.action === 'triage_lane') {
+            const out = await client.put(`/projects/${project.id}/sentry-connections/${args.connectionId}/triage-lane`, { laneId: args.laneId || null });
+            return text(out, out.lane ? `Lane ${out.lane.name} bound (assignment v${out.lane.assignmentVersion}); mandate follows mode ${out.connection.triageMode}.` : 'Triage lane unbound; the mandate was withdrawn.');
+        }
+        need('ticketKey');
+        need('verdict');
+        need('summary');
+        const ticket = await resolveTicketByKey(client, args.ticketKey);
+        const body = { verdict: args.verdict, summary: args.summary, agentSessionToken: mcpInstanceToken() };
+        const result = await client.post(`/projects/${project.id}/sentry-connections/${args.connectionId}/triage/${ticket.id}/verdict`, body);
+        return text(result, `${result.ticketKey ?? ticket.id}: ${result.verdict} (${result.mode}) priority=${result.priority ?? '-'}${result.closed ? ' closed' : ''}${result.escalated ? ' escalated' : ''}${result.branchName ? ` branch=${result.branchName} session=${result.workSessionId}` : ''} next=${result.nextStep}`);
+    };
+}

package/dist/tools/sentry.test.js

@@ -0,0 +1,107 @@
+/**
+ * ORB-2123 - `orboto_sentry` handler tests: every action hits the right
+ * route, secrets never come back in the text, and a missing field fails
+ * before any write.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeSentryHandler, sentryToolConfig } from './sentry.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const u = url.toString();
+        const m = init?.method ?? 'GET';
+        const b = init?.body ? JSON.parse(init.body) : undefined;
+        calls.push({ url: u, method: m, body: b });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch ${m} ${u}`);
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: r.ok === false ? 'Error' : 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => JSON.stringify('json' in r ? r.json : {}),
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const project = { id: '11111111-1111-4111-8111-111111111111', key: 'TEN', name: '10monkeys' };
+const connectionId = '22222222-2222-4222-8222-222222222222';
+const connection = {
+    id: connectionId, orgSlug: 'edyoutec', projectSlug: '10monkeys-next', enabled: true, triageMode: 'comment', hasAuthToken: false,
+    webhookUrl: 'https://orboto.example.com/inbound/sentry/' + connectionId, lastWebhookAt: null, lastSignatureOk: null, lastError: null, webhookCount: 0,
+    triageLaneId: null, dailyTriageLimit: null, escalationUserId: null,
+};
+describe('orboto_sentry', () => {
+    it('declares a short title and explicit annotations', () => {
+        expect(sentryToolConfig.title.length).toBeLessThanOrEqual(64);
+        expect(sentryToolConfig.annotations).toEqual({ readOnlyHint: false, destructiveHint: true, idempotentHint: false });
+    });
+    it('lists connections with their webhook URL and health', async () => {
+        stub([{ json: project }, { json: [connection] }]);
+        const out = await makeSentryHandler(client)({ action: 'list', projectKey: 'TEN' });
+        const text = out.content[0].text;
+        expect(text).toContain('edyoutec/10monkeys-next mode=comment enabled token=no');
+        expect(text).toContain(connection.webhookUrl);
+        expect(out.structuredContent).toEqual({ connections: [connection] });
+    });
+    it('connects with the client secret in the body and never in the text', async () => {
+        const calls = stub([{ json: project }, { json: { ...connection, triageMode: 'fix_branch', webhookUrlWarning: { code: 'webhook_url_from_request', message: 'set API_PUBLIC_URL' } } }]);
+        const out = await makeSentryHandler(client)({ action: 'connect', projectKey: 'TEN', orgSlug: 'edyoutec', projectSlug: '10monkeys-next', clientSecret: 'sec_value_123', triageMode: 'fix_branch' });
+        expect(calls[1]).toMatchObject({ method: 'POST', url: expect.stringContaining(`/projects/${project.id}/sentry-connections`), body: { orgSlug: 'edyoutec', projectSlug: '10monkeys-next', clientSecret: 'sec_value_123', triageMode: 'fix_branch' } });
+        const text = out.content[0].text;
+        expect(text).toContain('Connected edyoutec/10monkeys-next to TEN');
+        expect(text).toContain('Warning: set API_PUBLIC_URL');
+        expect(text).not.toContain('sec_value_123');
+        expect(JSON.stringify(out.structuredContent)).not.toContain('sec_value_123');
+    });
+    it('refuses a connect without the secret before any write', async () => {
+        const calls = stub([{ json: project }]);
+        await expect(makeSentryHandler(client)({ action: 'connect', projectKey: 'TEN', orgSlug: 'edyoutec', projectSlug: 'p' })).rejects.toThrow('connect needs clientSecret.');
+        expect(calls).toHaveLength(1);
+    });
+    it('routes health, update, rotate_secret, disconnect and triage_lane to their endpoints', async () => {
+        const calls = stub([
+            { json: project }, { json: { healthy: true, lastWebhookAt: '2026-09-14T08:00:00Z', lastError: null, linkedIssues: 3, openLinkedIssues: 1, webhookCount: 9 } },
+            { json: project }, { json: { ...connection, triageMode: 'fix_branch' } },
+            { json: project }, { json: connection },
+            { json: project }, { json: { deleted: true } },
+            { json: project }, { json: { connection, lane: { id: 'l1', name: 'sentry-triage-1', assignmentVersion: 3 } } },
+            { json: project }, { json: { connection, lane: null } },
+        ]);
+        const h = makeSentryHandler(client);
+        expect((await h({ action: 'health', projectKey: 'TEN', connectionId })).content[0]).toMatchObject({ text: expect.stringContaining('healthy - deliveries=9') });
+        expect((await h({ action: 'update', projectKey: 'TEN', connectionId, triageMode: 'fix_branch' })).content[0]).toMatchObject({ text: expect.stringContaining('Triage mode is now fix_branch') });
+        expect((await h({ action: 'rotate_secret', projectKey: 'TEN', connectionId, clientSecret: 'new_secret_value' })).content[0]).toMatchObject({ text: expect.not.stringContaining('new_secret_value') });
+        expect((await h({ action: 'disconnect', projectKey: 'TEN', connectionId })).structuredContent).toEqual({ deleted: true, connectionId });
+        expect((await h({ action: 'triage_lane', projectKey: 'TEN', connectionId, laneId: 'l1' })).content[0]).toMatchObject({ text: expect.stringContaining('Lane sentry-triage-1 bound (assignment v3)') });
+        expect((await h({ action: 'triage_lane', projectKey: 'TEN', connectionId })).content[0]).toMatchObject({ text: expect.stringContaining('unbound') });
+        expect(calls.map((c) => `${c.method} ${c.url.replace('https://orboto.example.com', '')}`)).toEqual([
+            'GET /projects/by-key/TEN', `GET /projects/${project.id}/sentry-connections/${connectionId}/health`,
+            'GET /projects/by-key/TEN', `PATCH /projects/${project.id}/sentry-connections/${connectionId}`,
+            'GET /projects/by-key/TEN', `POST /projects/${project.id}/sentry-connections/${connectionId}/rotate-secret`,
+            'GET /projects/by-key/TEN', `DELETE /projects/${project.id}/sentry-connections/${connectionId}`,
+            'GET /projects/by-key/TEN', `PUT /projects/${project.id}/sentry-connections/${connectionId}/triage-lane`,
+            'GET /projects/by-key/TEN', `PUT /projects/${project.id}/sentry-connections/${connectionId}/triage-lane`,
+        ]);
+        expect(calls[9].body).toEqual({ laneId: 'l1' });
+        expect(calls[11].body).toEqual({ laneId: null });
+    });
+    it('records a verdict on the ticket resolved by key and reports the hand-off', async () => {
+        const calls = stub([
+            { json: project },
+            { json: project },
+            { json: { id: '33333333-3333-4333-8333-333333333333', ticketKey: 'TEN-7', title: 'x' } },
+            { json: { ticketKey: 'TEN-7', verdict: 'new', mode: 'fix_branch', closed: false, escalated: false, branchName: 'sentry/ten-7-fix', workSessionId: 'ws1', nextStep: 'implement_then_finish', priority: 'high' } },
+        ]);
+        const out = await makeSentryHandler(client)({ action: 'verdict', projectKey: 'TEN', connectionId, ticketKey: 'TEN-7', verdict: 'new', summary: 'Unguarded read of session.cart.' });
+        expect(calls[3]).toMatchObject({ method: 'POST', url: expect.stringContaining(`/sentry-connections/${connectionId}/triage/33333333-3333-4333-8333-333333333333/verdict`) });
+        expect(calls[3].body).toMatchObject({ verdict: 'new', summary: 'Unguarded read of session.cart.' });
+        expect(typeof calls[3].body.agentSessionToken).toBe('string');
+        expect(out.content[0].text).toBe('TEN-7: new (fix_branch) priority=high branch=sentry/ten-7-fix session=ws1 next=implement_then_finish');
+    });
+});

package/dist/tools/session-start.js

@@ -9,14 +9,15 @@
  * @see ORB-1605, ORB-1607, ORB-1818
  */
 import { z } from 'zod';
-import { resolveTicketByKey, applyAgentProfile } from './shared.js';
+import { resolveTicketByKey, applyAgentProfile, mcpInstanceToken } from './shared.js';
+import { AgentSessionScopeSchema } from './agent-session-scope.js';
 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';
 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.) Read-only; no side effects. '
-        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them.',
+    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. '
+        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136).',
     inputSchema: z.object({
         projectId: z.string().uuid().optional().describe('Also load this project\'s rules.'),
         ticketKey: z.string().min(3).optional().describe('Ticket key ("ACME-42") - bundles that ticket\'s full context.'),
@@ -24,8 +25,9 @@ export const sessionStartToolConfig = {
         rulesOnly: z.boolean().optional().describe('Return ONLY the complete rules text.'),
         agentKind: z.string().min(1).max(32).optional().describe('coding | orchestrator | reviewer | runner.'),
         modelTier: z.string().min(1).max(32).optional().describe('frontier | standard | small.'),
+        scope: AgentSessionScopeSchema.optional(),
     }).shape,
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
 const MAX_GIT_HEALTH_PROJECTS = 8;
 /** ORB-1607 - build the `--ticket` one-shot bundle. Never throws: an
@@ -128,7 +130,8 @@ async function buildTicketBundle(client, ticketKey) {
 }
 export function makeSessionStartHandler(client) {
     let lastKnownRulesHash;
-    return async (input = {}) => {
+    return async (input = {}, extra) => {
+        const instanceToken = mcpInstanceToken(undefined, extra);
         const rulesParams = new URLSearchParams();
         if (input.projectId)
             rulesParams.set('projectId', input.projectId);
@@ -163,16 +166,19 @@ export function makeSessionStartHandler(client) {
                 },
             };
         }
+        const registration = await client.post('/v1/agent/heartbeat', input.scope !== undefined ? { scope: input.scope } : {}, { instanceToken })
+            .then((r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null } : null))
+            .catch(() => null);
         const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             client.get('/users/me/assigned-tickets?statuses=IN_PROGRESS,IN_REVIEW&limit=20').catch(() => ({ items: [] })),
             client.get('/time/timer').catch(() => null),
-            client.get('/v1/agent/messages?limit=10')
+            client.get('/v1/agent/messages?limit=10', { instanceToken })
                 .then((r) => (Array.isArray(r?.messages) ? r.messages : []))
                 .catch(() => []),
         ]);
-        const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
+        const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, from: m.from?.label ?? m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
         const projectIds = [...new Set(tickets.map((t) => t.projectId).filter((id) => !!id))].slice(0, MAX_GIT_HEALTH_PROJECTS);
         const gitHealthByProject = await Promise.all(projectIds.map(async (projectId) => ({
@@ -245,10 +251,15 @@ export function makeSessionStartHandler(client) {
         }
         lines.push('', '## Timer');
         lines.push(timer?.ticketId ? `Running on ${timer.ticketKey ?? timer.ticketId} since ${timer.startedAt ?? 'earlier'}.` : 'No timer running.');
+        lines.push('', '## This session');
+        const scopeText = registration?.scope
+            ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
+            : 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it';
+        lines.push(`ref ${instanceToken}${registration ? `, instance ${registration.sessionId.slice(0, 8)}` : ''}. ${scopeText}. Peers reach exactly this session with orboto_agent_notify { toSessionRef: "${registration ? registration.sessionId.slice(0, 8) : instanceToken}" }.`);
         if (pendingMessages.length > 0) {
             lines.push('', '## Agent messages - unread');
             for (const m of pendingMessages)
-                lines.push(`- [${m.kind}] ${m.subject} (from ${m.fromUserId}, ${m.createdAt}, id ${m.id})`);
+                lines.push(`- [${m.kind}] ${m.subject} (from ${m.from}, ${m.createdAt}, id ${m.id})`);
             lines.push('Handle them, then acknowledge via orboto_messages { ackIds: [...] }; reply via orboto_agent_notify with threadId.');
         }
         if (bundle)
@@ -274,6 +285,7 @@ export function makeSessionStartHandler(client) {
                 })),
                 ...(elsewhereCount > 0 ? { inProgressElsewhereCount: elsewhereCount } : {}),
                 timer: timer?.ticketId ? { ticketKey: timer.ticketKey ?? null, startedAt: timer.startedAt ?? null } : null,
+                session: { ref: instanceToken, id: registration?.sessionId ?? null, scope: registration?.scope ?? null },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections
                         .map((p) => ({ projectId: p.projectId, connections: p.connections.filter((c) => !c.healthy) }))

package/dist/tools/session-start.test.js

@@ -523,3 +523,47 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         expect(res.content[0].text).toContain(RULES_TEXT);
     });
 });
+describe('ORB-2136 - session scope and ref', () => {
+    it('registers the scope on this MCP session via heartbeat with the session header and reports the session ref', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            const path = u.pathname + u.search;
+            seen.push({ path, headers: (init?.headers ?? {}), body: init?.body ? JSON.parse(init.body) : undefined });
+            const map = {
+                '/v1/agent/heartbeat': { sessionToken: 'mcp-abc123', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] } },
+                '/users/me/assigned-tickets': { items: [] },
+                '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
+                '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
+                '/time/timer': {},
+                '/v1/agent/messages': { sessionId: 'cbb52195-0000-4000-8000-000000000000', messages: [{ id: 'm1', fromUserId: 'u1', from: { label: 'spec@orboto.io (spec, s1)' }, kind: 'request', subject: 'ticket-ready:ORB-1', createdAt: 'now' }] },
+            };
+            const key = Object.keys(map).find((k) => path.startsWith(k));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => (key ? map[key] : {}), text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(client)({ scope: { role: 'integrator', projectKeys: ['orb'] } }, { sessionId: 'abc123' });
+        const beat = seen.find((c) => c.path === '/v1/agent/heartbeat');
+        expect(beat?.headers['x-orboto-agent-session']).toBe('mcp-abc123');
+        expect(beat?.body).toEqual({ scope: { role: 'integrator', projectKeys: ['orb'] } });
+        expect(seen.find((c) => c.path.startsWith('/v1/agent/messages'))?.headers['x-orboto-agent-session']).toBe('mcp-abc123');
+        const text = res.content[0].text;
+        expect(text).toContain('ref mcp-abc123, instance cbb52195. role integrator; projects ORB');
+        expect(text).toContain('toSessionRef: "cbb52195"');
+        expect(text).toContain('from spec@orboto.io (spec, s1)');
+        expect(res.structuredContent).toMatchObject({ session: { ref: 'mcp-abc123', id: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] } } });
+    });
+    it('without a scope the heartbeat body stays empty and the digest says no scope is declared', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            seen.push({ path: u.pathname, body: init?.body ? JSON.parse(init.body) : undefined });
+            const body = u.pathname === '/v1/agent/heartbeat'
+                ? { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null }
+                : u.pathname === '/agent-instructions' ? { instructions: 'rules here', rulesHash: 'fixture' } : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(client)({}, { sessionId: 'abc123' });
+        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({});
+        expect(res.content[0].text).toContain('no scope declared');
+    });
+});

package/dist/tools/shared.js

@@ -27,6 +27,8 @@ export function agentTicketListRow(t, verbose = false) {
             title: t.title,
             status: t.statusName ?? t.status,
             statusCategory: t.statusCategory ?? null,
+            specState: t.specState ?? 'none',
+            ...specReleaseInfo(t),
             priority: t.priority,
             type: t.type,
             dueDate: t.dueDate ?? null,
@@ -43,8 +45,10 @@ export function agentTicketListRow(t, verbose = false) {
     const assigneeNames = (t.assignees ?? []).map((a) => a.fullName || a.email);
     return {
         key: t.ticketKey,
+        ...specReleaseInfo(t),
         title: t.title,
         statusCategory: t.statusCategory ?? null,
+        ...(t.specState && t.specState !== 'none' ? { specState: t.specState } : {}),
         ...(t.priority && t.priority !== 'normal' ? { priority: t.priority } : {}),
         ...(t.type && t.type !== 'task' ? { type: t.type } : {}),
         ...(t.dueDate ? { dueDate: t.dueDate } : {}),
@@ -183,3 +187,8 @@ export function resolveByName(candidates, ref, getName) {
         return { match: null, ambiguous: normMatches };
     return { match: null, ambiguous: null };
 }
+export function specReleaseInfo(t) {
+    if (t.specReleasedBy === undefined)
+        return {};
+    return { specReleasedBy: t.specReleasedBy, specReleasedByFullName: t.specReleasedByFullName ?? null, specReleasedAt: t.specReleasedAt ?? null, specReleasePolicy: t.specReleasePolicy ?? null, specReleaseRole: t.specReleaseRole ?? null };
+}

package/dist/tools/spec-check.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { resolveTicketByKey } from './shared.js';
+export const specCheckToolConfig = {
+    title: 'Check build order',
+    description: 'Validate a build order. Returns issues, template, human authorId and releaseBy policy. Release permission is checked separately.',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    inputSchema: z.object({ ticketKey: z.string().min(1) }),
+};
+export function makeSpecCheckHandler(client) {
+    return async (input) => {
+        const ticket = await resolveTicketByKey(client, input.ticketKey);
+        const result = await client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}/spec-check`);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+    };
+}

package/dist/tools/spec-check.test.js

@@ -0,0 +1,23 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient, OrbotoApiError } from '../orboto-client.js';
+import { makeSpecCheckHandler, specCheckToolConfig } from './spec-check.js';
+afterEach(() => { vi.restoreAllMocks(); });
+describe('spec check', () => {
+    it('returns the authoritative diagnostics and template without writes', async () => {
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+        const report = { authorId: 'human-author', releaseBy: 'author', check: { valid: false, criteriaCount: 0, openQuestionCount: 2, missingHeadings: ['Goal'] }, template: 'template' };
+        const get = vi.spyOn(client, 'get').mockResolvedValueOnce({ id: 'p', key: 'ORB' }).mockResolvedValueOnce({ id: 't', projectId: 'p' }).mockResolvedValueOnce(report);
+        const post = vi.spyOn(client, 'post');
+        const patch = vi.spyOn(client, 'patch');
+        expect(await makeSpecCheckHandler(client)({ ticketKey: 'ORB-2099' })).toMatchObject({ structuredContent: report });
+        expect(get).toHaveBeenLastCalledWith('/projects/p/tickets/t/spec-check');
+        expect(post).not.toHaveBeenCalled();
+        expect(patch).not.toHaveBeenCalled();
+        expect(specCheckToolConfig.annotations).toMatchObject({ readOnlyHint: true, destructiveHint: false });
+    });
+    it('propagates read authorization errors', async () => {
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+        vi.spyOn(client, 'get').mockResolvedValueOnce({ id: 'p', key: 'ORB' }).mockResolvedValueOnce({ id: 't', projectId: 'p' }).mockRejectedValueOnce(new OrbotoApiError(404, '{}', 'test'));
+        await expect(makeSpecCheckHandler(client)({ ticketKey: 'ORB-2099' })).rejects.toMatchObject({ status: 404 });
+    });
+});

package/dist/tools/spec-readiness.test.js

@@ -0,0 +1,85 @@
+import { specReleaseInfo } from './shared.js';
+import { makeWorkSessionsHandler } from './work-sessions.js';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeWorkStartHandler, makeWorkSessionStartHandler, workStartToolConfig } from './work-sessions.js';
+import { makeClaimHandler } from './claim.js';
+import { specGateFailure, TicketSpecStateSchema } from './spec-schemas.js';
+import { updateProjectToolConfig } from './update-project.js';
+import { makeAssignHandler, updateTicketToolConfig } from './ticket-writes.js';
+afterEach(() => { vi.restoreAllMocks(); });
+describe('spec readiness tool contracts', () => {
+    it('keeps the isolated MCP state enum in sync with the API contract', () => {
+        const canonical = readFileSync(path.resolve(process.cwd(), '../../packages/shared-schema/src/spec-readiness.ts'), 'utf8');
+        const states = canonical.match(/TicketSpecStateSchema = z\.enum\(\[([^\]]+)\]/)?.[1].match(/'([^']+)'/g)?.map((value) => value.slice(1, -1));
+        expect(states).toEqual(TicketSpecStateSchema.options);
+    });
+    it.each([makeWorkStartHandler, makeWorkSessionStartHandler])('forwards a reasoned override and explains the server gate', async (factory) => {
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+        vi.spyOn(client, 'get').mockResolvedValueOnce({ id: 'project', key: 'ORB' }).mockResolvedValueOnce({ id: 'ticket', projectId: 'project' });
+        const post = vi.spyOn(client, 'post').mockRejectedValue(new OrbotoApiError(409, JSON.stringify({ errorKey: 'errors.tickets.spec_not_ready', errorParams: { state: 'needs_spec' } }), 'test'));
+        const result = await factory(client)({ ticketKey: 'ORB-2098', override: true, reason: 'Approved recovery' });
+        expect(post.mock.calls[0][1]).toMatchObject({ ticketId: 'ticket', override: true, reason: 'Approved recovery' });
+        expect(result).toMatchObject({ isError: true, structuredContent: { specGate: true, errorKey: 'errors.tickets.spec_not_ready', errorParams: { state: 'needs_spec' } } });
+        expect(JSON.stringify(result.content)).toContain('release the specification');
+    });
+    it('stops a repeated sole claim at the gate before removing someone else', async () => {
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+        vi.spyOn(client, 'get').mockResolvedValueOnce({ id: 'me' }).mockResolvedValueOnce({ id: 'project', key: 'ORB' }).mockResolvedValueOnce({ id: 'ticket', projectId: 'project', statusCategory: 'in_progress', assignees: [{ userId: 'me' }, { userId: 'other' }] });
+        vi.spyOn(client, 'post').mockRejectedValue(new OrbotoApiError(409, '{"errorKey":"errors.tickets.spec_not_ready"}', 'test'));
+        const remove = vi.spyOn(client, 'delete');
+        const patch = vi.spyOn(client, 'patch');
+        expect(await makeClaimHandler(client)({ ticketKey: 'ORB-2098', sole: true })).toMatchObject({ isError: true, structuredContent: { specGate: true } });
+        expect(remove).not.toHaveBeenCalled();
+        expect(patch).not.toHaveBeenCalled();
+    });
+    it.each([
+        ['errors.tickets.already_assigned', true],
+        ['errors.tickets.spec_not_ready', false],
+        ['errors.work_sessions.lease_held', false],
+    ])('only tolerates an already-assigned conflict: %s', async (errorKey, tolerated) => {
+        for (const kind of ['claim', 'assign']) {
+            const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+            const get = vi.spyOn(client, 'get');
+            if (kind === 'claim')
+                get.mockResolvedValueOnce({ id: 'me' });
+            get.mockResolvedValueOnce({ id: 'project', key: 'ORB' }).mockResolvedValueOnce({ id: 'ticket', projectId: 'project', statusCategory: 'in_progress', assignees: [{ userId: 'me' }] });
+            if (kind === 'assign')
+                get.mockResolvedValueOnce([{ userId: 'me', user: { id: 'me', email: 'me@spec.test' } }]);
+            const error = new OrbotoApiError(409, JSON.stringify({ errorKey }), 'test');
+            vi.spyOn(client, 'post').mockRejectedValue(error);
+            const result = kind === 'claim' ? makeClaimHandler(client)({ ticketKey: 'ORB-2098', noTimer: true }) : makeAssignHandler(client)({ ticketKey: 'ORB-2098', assigneeEmail: 'me@spec.test' });
+            if (tolerated)
+                expect(await result).not.toHaveProperty('isError', true);
+            else if (kind === 'claim' && errorKey === 'errors.tickets.spec_not_ready')
+                expect(await result).toHaveProperty('isError', true);
+            else
+                await expect(result).rejects.toBe(error);
+        }
+    });
+    it('exposes the settings, state and spec role and preserves unrelated conflict parsing', () => {
+        expect(z.object(workStartToolConfig.inputSchema).parse({ ticketKey: 'ORB-2098', role: 'spec' }).role).toBe('spec');
+        expect(z.object(updateTicketToolConfig.inputSchema).parse({ ticketKey: 'ORB-2098', patch: { specState: 'ready' } }).patch.specState).toBe('ready');
+        expect(z.object(updateProjectToolConfig.inputSchema).parse({ projectKey: 'ORB', patch: { spec: { enabled: true, requiredTypes: ['story'], releaseBy: 'author' } } }).patch.spec?.releaseBy).toBe('author');
+        expect(z.object(updateProjectToolConfig.inputSchema).parse({ projectKey: 'ORB', patch: { spec: { enabled: true } } }).patch.spec).toEqual({ enabled: true });
+        expect(specGateFailure('not json')).toBeUndefined();
+        expect(specGateFailure('{"errorKey":"errors.work_sessions.lease_held"}')).toBeUndefined();
+        expect(JSON.stringify(specGateFailure('{"errorKey":"errors.tickets.epic_not_claimable"}'))).toContain('child stories');
+    });
+});
+it('preserves release provenance without exposing the internal fingerprint', () => {
+    const ticket = { specReleasedBy: 'author', specReleasedByFullName: 'Alice', specReleasedAt: '2026-09-14T10:00:00Z', specReleasePolicy: 'author', specReleaseRole: 'author', specReleaseFingerprint: 'internal-proof' };
+    expect(specReleaseInfo(ticket)).toEqual({ specReleasedBy: 'author', specReleasedByFullName: 'Alice', specReleasedAt: '2026-09-14T10:00:00Z', specReleasePolicy: 'author', specReleaseRole: 'author' });
+});
+it('describes waiting tasks as parked sessions and preserves the question reference', async () => {
+    const client = new OrbotoClient({ baseUrl: 'https://orboto.example.test', apiKey: 'test' });
+    const row = { id: 'session', ticketId: 'ticket', ticketKey: 'ORB-2100', role: 'spec', status: 'finished', waitingForAnswers: true, taskId: 'task', waitingCommentId: 'question', leaseUntil: 'past' };
+    vi.spyOn(client, 'get').mockResolvedValue([row]);
+    const result = await makeWorkSessionsHandler(client)({});
+    expect(result.structuredContent).toEqual({ sessions: [row] });
+    expect(JSON.stringify(result.content)).toContain('waiting for answers; session finished; task task; question question');
+    expect(JSON.stringify(result.content)).not.toContain('lease until');
+});

package/dist/tools/spec-schemas.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export const TicketSpecStateSchema = z.enum(['none', 'needs_spec', 'in_spec', 'ready']);
+export const ProjectSpecSettingsSchema = z.object({
+    enabled: z.boolean().optional(),
+    requiredTypes: z.array(z.enum(['epic', 'story', 'task', 'bug'])).optional(),
+    releaseBy: z.enum(['agent', 'author']).optional(),
+}).strict();
+export function specGateFailure(body) {
+    let failure;
+    try {
+        failure = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (!failure || !['errors.tickets.spec_not_ready', 'errors.tickets.epic_not_claimable'].includes(failure.errorKey ?? ''))
+        return undefined;
+    return {
+        isError: true,
+        content: [{ type: 'text', text: failure.errorKey === 'errors.tickets.spec_not_ready'
+                    ? `Specification is ${failure.errorParams?.state ?? 'not ready'}. Complete and release the specification, or explicitly set override=true with a reason.`
+                    : 'Epics are task groups. Use the spec role to prepare child stories.' }],
+        structuredContent: { ...failure, specGate: true },
+    };
+}
+export function isAlreadyAssigned(body) {
+    try {
+        const error = JSON.parse(body);
+        return error?.errorKey === 'errors.tickets.already_assigned' || (!error?.errorKey && error?.error?.trim().toLowerCase() === 'already assigned');
+    }
+    catch {
+        return false;
+    }
+}