@orboto/mcp 0.195.0 → 0.197.0

package/dist/tools/claim.test.js

@@ -75,7 +75,7 @@ describe('orboto_claim', () => {
             noop: false,
         });
     });
-    it('idempotent: skip assign POST + status PATCH when already-in-progress + already-assigned', async () => {
+    it('idempotent re-claim rechecks assignment readiness without changing status', async () => {
         const calls = stub([
             { json: ME },
             { json: PROJ },
@@ -83,10 +83,11 @@ describe('orboto_claim', () => {
                     ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress',
                     assignees: [{ id: 'me1', email: 'agent-e@orboto.io', fullName: 'Agent E' }],
                 } },
+            { json: {} },
             { json: { ticketId: 't1' } }, // GET /time/timer - already on same ticket
         ]);
         const res = await makeClaimHandler(client)({ ticketKey: 'ACME-1' });
-        expect(calls).toHaveLength(4);
+        expect(calls).toHaveLength(5);
         expect(calls.some((c) => c.method === 'PATCH')).toBe(false);
         expect(calls.some((c) => c.url.includes('/timer/start'))).toBe(false);
         expect(res.structuredContent).toMatchObject({
@@ -94,7 +95,7 @@ describe('orboto_claim', () => {
             noop: true,
         });
     });
-    it('sole=true removes every other assignee before adding self', async () => {
+    it('sole=true verifies self assignment before removing other assignees', async () => {
         const calls = stub([
             { json: ME },
             { json: PROJ },
@@ -111,8 +112,9 @@ describe('orboto_claim', () => {
         ]);
         await makeClaimHandler(client)({ ticketKey: 'ACME-1', sole: true });
         expect(calls.filter((c) => c.method === 'DELETE')).toHaveLength(2);
-        expect(calls[3].url).toContain('/assignees/other1');
-        expect(calls[4].url).toContain('/assignees/other2');
+        expect(calls[3].url).toContain('/assignees/me1');
+        expect(calls[4].url).toContain('/assignees/other1');
+        expect(calls[5].url).toContain('/assignees/other2');
     });
     it('refuses to claim a done ticket without force=true', async () => {
         stub([

package/dist/tools/get-ticket.js

@@ -1,3 +1,4 @@
+import { specReleaseInfo } from './shared.js';
 /**
  * ORB-244 Phase B - `orboto_get_ticket`.
  *
@@ -73,6 +74,8 @@ export function makeGetTicketHandler(client) {
                     : null,
                 priority: full.priority,
                 type: full.type,
+                specState: full.specState ?? 'none',
+                ...specReleaseInfo(full),
                 deliveryMode: full.deliveryMode ?? 'implementation',
                 dueDate: full.dueDate,
                 startDate: full.startDate,

package/dist/tools/git-rotate-token.js

@@ -0,0 +1,61 @@
+/**
+ * ORB-2112 - `orboto_git_rotate_token`.
+ *
+ * Replace the credential a project's git connection uses. orboto probes
+ * the provider with the new one first, so a bad paste leaves the working
+ * credential in place and the connection id, its activities and issue
+ * links untouched.
+ */
+import { z } from 'zod';
+import { resolveProjectByKey } from './shared.js';
+export const gitRotateTokenToolConfig = {
+    title: 'Rotate a git connection\'s access token',
+    description: 'Replace a git connection\'s access token (ssh: private key). The provider is probed with the new credential first; on success it is re-sealed under the same connection id, on failure 422 and the old one stays. reinstallWebhook also reinstalls the hook. App / OAuth connections answer 422.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key, e.g. ORB.'),
+        connectionId: z.string().uuid().describe('Git connection id.'),
+        accessToken: z.string().min(1).optional().describe('New access token (every provider but ssh).'),
+        privateKey: z.string().min(1).optional().describe('New SSH private key (ssh only).'),
+        reinstallWebhook: z.boolean().optional().describe('Also reinstall the provider hook.'),
+    }).shape,
+    outputSchema: z.object({
+        connectionId: z.string(),
+        name: z.string(),
+        healthy: z.boolean(),
+        tokenState: z.enum(['ok', 'unauthorized', 'unknown']),
+        reason: z.string().nullable(),
+        webhookUrl: z.string().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeGitRotateTokenHandler(client) {
+    return async (args) => {
+        if ((args.accessToken ? 1 : 0) + (args.privateKey ? 1 : 0) !== 1) {
+            throw new Error('Pass exactly one of accessToken or privateKey.');
+        }
+        const project = await resolveProjectByKey(client, args.projectKey);
+        const res = await client.post(`/projects/${project.id}/git-connections/${args.connectionId}/rotate-token`, {
+            ...(args.accessToken ? { accessToken: args.accessToken } : {}),
+            ...(args.privateKey ? { privateKey: args.privateKey } : {}),
+            ...(args.reinstallWebhook ? { reinstallWebhook: true } : {}),
+        });
+        const lines = [
+            `Rotated the credential on "${res.health.name}" (${res.health.connectionId}).`,
+            `Token state: ${res.health.tokenState}; healthy: ${res.health.healthy}${res.health.reason ? ` (${res.health.reason})` : ''}.`,
+        ];
+        if (res.webhookUrl) {
+            lines.push(`Webhook ${res.webhookAutoInstalled ? 'reinstalled on' : 'install failed for'} ${res.webhookUrl}${res.webhookInstallError ? ` - ${res.webhookInstallError}` : ''}.`);
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                connectionId: res.health.connectionId,
+                name: res.health.name,
+                healthy: res.health.healthy,
+                tokenState: res.health.tokenState,
+                reason: res.health.reason,
+                ...(res.webhookUrl ? { webhookUrl: res.webhookUrl } : {}),
+            },
+        };
+    };
+}

package/dist/tools/git-rotate-token.test.js

@@ -0,0 +1,87 @@
+/**
+ * ORB-2114 - `orboto_git_rotate_token` handler tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { gitRotateTokenToolConfig, makeGitRotateTokenHandler } from './git-rotate-token.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: 'ORB', name: 'orboto' };
+const connectionId = '22222222-2222-4222-8222-222222222222';
+const health = { connectionId, name: 'Forgejo - orboto/orboto', healthy: true, tokenState: 'ok', unhealthySince: null, reason: null };
+describe('orboto_git_rotate_token', () => {
+    it('posts the new access token to the rotate route and returns the health row', async () => {
+        const calls = stub([{ json: project }, { json: { rotated: true, health } }]);
+        const out = await makeGitRotateTokenHandler(client)({ projectKey: 'ORB', connectionId, accessToken: 'tok_new' });
+        expect(calls[0]).toMatchObject({ method: 'GET', url: expect.stringContaining('/projects/by-key/ORB') });
+        expect(calls[1]).toMatchObject({
+            method: 'POST',
+            url: expect.stringContaining(`/projects/${project.id}/git-connections/${connectionId}/rotate-token`),
+            body: { accessToken: 'tok_new' },
+        });
+        expect(out.structuredContent).toEqual({ connectionId, name: health.name, healthy: true, tokenState: 'ok', reason: null });
+        const text = out.content[0].text;
+        expect(text).toContain('Rotated the credential');
+        expect(text).not.toContain('tok_new');
+    });
+    it('passes privateKey and reinstallWebhook through and reports the reinstalled hook', async () => {
+        const calls = stub([
+            { json: project },
+            { json: { rotated: true, health, webhookUrl: 'https://orboto.example.com/git/webhook/x', webhookAutoInstalled: true, webhookInstallError: null } },
+        ]);
+        const out = await makeGitRotateTokenHandler(client)({ projectKey: 'ORB', connectionId, privateKey: '-----BEGIN KEY-----', reinstallWebhook: true });
+        expect(calls[1].body).toEqual({ privateKey: '-----BEGIN KEY-----', reinstallWebhook: true });
+        expect(out.content[0].text).toContain('Webhook reinstalled on https://orboto.example.com/git/webhook/x');
+        expect(out.structuredContent).toMatchObject({ webhookUrl: 'https://orboto.example.com/git/webhook/x' });
+    });
+    it('reports a failed webhook install with its error', async () => {
+        stub([
+            { json: project },
+            { json: { rotated: true, health: { ...health, healthy: false, tokenState: 'unknown', reason: 'outbound_unreachable' }, webhookUrl: 'https://orboto.example.com/git/webhook/x', webhookAutoInstalled: false, webhookInstallError: 'Gitea: 403' } },
+        ]);
+        const out = await makeGitRotateTokenHandler(client)({ projectKey: 'ORB', connectionId, accessToken: 'tok' });
+        const text = out.content[0].text;
+        expect(text).toContain('Webhook install failed for https://orboto.example.com/git/webhook/x - Gitea: 403');
+        expect(text).toContain('(outbound_unreachable)');
+    });
+    it('refuses when neither or both credentials are given, before any request', async () => {
+        const calls = stub([]);
+        await expect(makeGitRotateTokenHandler(client)({ projectKey: 'ORB', connectionId })).rejects.toThrow('exactly one');
+        await expect(makeGitRotateTokenHandler(client)({ projectKey: 'ORB', connectionId, accessToken: 'a', privateKey: 'b' })).rejects.toThrow('exactly one');
+        expect(calls).toHaveLength(0);
+    });
+    it('surfaces a rejected token as the API error', async () => {
+        stub([{ json: project }, { ok: false, status: 422, json: { error: 'errors.git.token_rejected' } }]);
+        await expect(makeGitRotateTokenHandler(client)({ projectKey: 'ORB', connectionId, accessToken: 'bad' })).rejects.toThrow();
+    });
+    it('names an unknown project key', async () => {
+        stub([{ ok: false, status: 404, json: { error: 'errors.projects.not_found' } }]);
+        await expect(makeGitRotateTokenHandler(client)({ projectKey: 'NOPE', connectionId, accessToken: 'tok' })).rejects.toThrow('Project "NOPE" not found');
+    });
+    it('declares a write tool with a title and an output schema', () => {
+        expect(gitRotateTokenToolConfig.title).toMatch(/rotate/i);
+        expect(gitRotateTokenToolConfig.annotations.readOnlyHint).toBe(false);
+        expect(Object.keys(gitRotateTokenToolConfig.outputSchema)).toEqual(expect.arrayContaining(['connectionId', 'tokenState']));
+    });
+});

package/dist/tools/list-git-app-installations.js

@@ -11,17 +11,8 @@
 import { z } from 'zod';
 export const listGitAppInstallationsToolConfig = {
     title: 'List GitHub App installations',
-    description: 'Return every GitHub App installation orboto knows about (across all projects). Requires super-admin on the API side. Each row carries the org/user the App is installed on, when it was installed, and whether it is currently suspended.',
+    description: 'Every GitHub App installation orboto knows about, across projects (super-admin): the org/user, install time and whether it is suspended.',
     inputSchema: z.object({}).shape,
-    outputSchema: z.object({
-        installations: z.array(z.object({
-            provider: z.string(),
-            accountLogin: z.string(),
-            accountType: z.string(),
-            installedAt: z.string(),
-            suspended: z.boolean(),
-        })),
-    }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
 export function makeListGitAppInstallationsHandler(client) {

package/dist/tools/list-tickets.js

@@ -1,3 +1,4 @@
+import { TicketSpecStateSchema } from './spec-schemas.js';
 /**
  * ORB-244 Phase B - `orboto_list_tickets`.
  *
@@ -15,6 +16,7 @@ export const listTicketsToolConfig = {
     description: 'List tickets in a project, optionally filtered by status category, milestone name, or assignee email. Set unscheduled=true for the product backlog (everything not planned into a milestone yet). Returns up to 50 tickets per call.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        specState: TicketSpecStateSchema.optional(),
         statusCategory: z
             .enum(['todo', 'in_progress', 'in_review', 'done', 'wont_fix'])
             .optional()
@@ -45,6 +47,8 @@ export function makeListTicketsHandler(client) {
         const project = await resolveProjectByKey(client, input.projectKey);
         const qs = new URLSearchParams();
         qs.set('limit', String(input.limit ?? 25));
+        if (input.specState)
+            qs.set('specState', input.specState);
         if (input.statusCategory)
             qs.set('statusCategory', input.statusCategory);
         if (input.unscheduled && input.milestone) {

package/dist/tools/project-readiness-schema.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const ProjectReadinessStatusSchema = z.enum(['ok', 'missing', 'n/a']);
+export const ProjectReadinessItemIdSchema = z.enum(['project_record', 'human_manager', 'milestones', 'git_connection', 'doc_primer', 'instructions', 'tech_stack', 'commands', 'lane_assignment', 'acceptance', 'spec_settings', 'sentry_intake']);
+export const ProjectReadinessItemSchema = z.object({
+    id: ProjectReadinessItemIdSchema,
+    status: ProjectReadinessStatusSchema,
+    reason: z.string(),
+    checked: z.number().int().nonnegative(),
+    missing: z.number().int().nonnegative(),
+    fix: z.object({ method: z.string(), route: z.string(), mcpTool: z.string(), cliCommand: z.string(), settingsPath: z.string() }),
+});
+export const ProjectReadinessSchema = z.object({
+    projectId: z.string().uuid(), projectKey: z.string(), ready: z.boolean(), language: z.string(),
+    ticketScope: z.literal('visible'),
+    items: z.array(ProjectReadinessItemSchema),
+});

package/dist/tools/project-readiness.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import { ProjectReadinessSchema } from './project-readiness-schema.js';
+import { resolveProjectByKey } from './shared.js';
+export const projectReadinessToolConfig = {
+    title: 'Check project readiness',
+    description: 'Check setup before autonomous work: measured ok/missing/n/a items with reasons and fix actions. Visible tickets only; no external probes.',
+    inputSchema: z.object({ projectKey: z.string().min(1).describe('Project key, case-insensitive.') }).shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+};
+export function makeProjectReadinessHandler(client) {
+    return async ({ projectKey }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const report = ProjectReadinessSchema.parse(await client.get(`/projects/${project.id}/readiness`));
+        return { content: [{ type: 'text', text: `${report.projectKey}: ${report.ready ? 'ready' : 'setup incomplete'}\n${report.items.map(i => `${i.status}: ${i.id} (${i.reason})`).join('\n')}` }], structuredContent: report };
+    };
+}

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

@@ -0,0 +1,19 @@
+import { expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { makeProjectReadinessHandler } from './project-readiness.js';
+it('returns measured readiness after project key resolution and preserves fix actions', async () => {
+    const report = { projectId: '11111111-2222-4333-8444-555555555555', projectKey: 'TEST', language: 'en', ready: false, ticketScope: 'visible', items: [{ id: 'commands', status: 'missing', reason: 'commands_missing', checked: 1, missing: 1, fix: { method: 'POST', route: '/projects/p/primer-facts', mcpTool: 'orboto_primer_fact_add', cliCommand: 'orboto post /projects/p/primer-facts', settingsPath: '/projects/test/settings?tab=aiPrimer' } }] };
+    const get = vi.fn().mockResolvedValueOnce({ id: report.projectId, key: 'TEST', name: 'Test' }).mockResolvedValueOnce(report);
+    const result = await makeProjectReadinessHandler({ get })({ projectKey: 'test' });
+    expect(get).toHaveBeenLastCalledWith(`/projects/${report.projectId}/readiness`);
+    expect(result.structuredContent).toEqual(report);
+});
+it('pins the standalone schema mirror to shared-schema', () => {
+    const root = resolve(process.cwd(), '../..');
+    expect(readFileSync(resolve(root, 'apps/mcp/src/tools/project-readiness-schema.ts'), 'utf8')).toBe(readFileSync(resolve(root, 'packages/shared-schema/src/project-readiness.ts'), 'utf8').replace("import { ProjectSchema } from './projects.ts';\n", '').replace('\nexport const CreatedProjectSchema = ProjectSchema.extend({ readiness: ProjectReadinessSchema });\n', ''));
+});
+it('propagates denied access instead of reporting readiness', async () => {
+    const get = vi.fn().mockRejectedValue(new Error('404'));
+    await expect(makeProjectReadinessHandler({ get })({ projectKey: 'private' })).rejects.toThrow();
+});

package/dist/tools/raci.js

@@ -65,15 +65,17 @@ export const setRaciToolConfig = {
         ticketKey: z.string().min(3).describe('Ticket key (e.g. "ORB-42").'),
         userEmail: z.string().email().describe('Email of a project member.'),
         role: z.enum(ROLES).describe('R, A, C, or I.'),
+        override: z.boolean().optional(),
+        reason: z.string().trim().min(1).max(2000).optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
 export function makeSetRaciHandler(client) {
-    return async ({ ticketKey, userEmail, role }) => {
+    return async ({ ticketKey, userEmail, role, override, reason }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
         const userId = await resolveMemberId(client, ticket.projectId, userEmail);
         try {
-            await client.put(`/projects/${ticket.projectId}/tickets/${ticket.id}/raci/${userId}`, { role });
+            await client.put(`/projects/${ticket.projectId}/tickets/${ticket.id}/raci/${userId}`, { role, override, reason });
         }
         catch (err) {
             if (err instanceof OrbotoApiError && err.status === 409) {

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/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 });
+    });
+});