@orboto/mcp 0.195.1 → 0.198.0

package/dist/tools/agent-messages.js

@@ -8,21 +8,29 @@
  * api's `x-orboto-agent-mail` response header - no polling anywhere).
  */
 import { z } from 'zod';
+import { makeAgentMessageWorkHandler } from './agent-message-work.js';
 import { mcpInstanceToken } from './shared.js';
+const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
 export const agentMessagesToolConfig = {
-    title: 'Fetch / acknowledge your agent inbox',
-    description: 'Your store-and-forward inbox: messages other agents sent you, broadcasts to your scopes (payload.broadcast names the scope) and ticket_ready wake-ups (subject ticket-ready:<KEY>, payload.type ticket_ready with ticketKey, reason assigned | labeled | unblocked: the ticket is yours to claim; claim or answer, then ack). Default = unread, marked delivered on fetch; ackIds marks read. Reply via orboto_agent_notify with threadId = the message id.',
+    title: 'Agent inbox and message work',
+    description: 'Your inbox as THIS session sees it: mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds is a plain read receipt: no claim needed, finishes nothing. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
     inputSchema: z.object({
-        all: z.boolean().default(false).describe('true = include already-read messages'),
+        messageWork: z.record(z.unknown()).optional()
+            .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),
+        all: z.boolean().default(false),
         limit: z.number().int().min(1).max(200).default(50),
-        project: z.string().min(1).max(64).optional().describe('Project key or UUID: scoped messages for this project plus unscoped ones. Ack only messages that are yours.'),
-        includeOwnSends: z.boolean().default(false).describe('true = also list messages this session sent (hidden by default so a shared identity never wakes itself).'),
-        ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark as read'),
+        project: z.string().min(1).max(64).optional().describe('Project key/UUID; includes unscoped mail.'),
+        includeOwnSends: z.boolean().default(false),
+        ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark read.'),
     }).shape,
     outputSchema: z.object({
+        work: z.record(z.unknown()).optional(),
+        sessionId: z.string().nullable().optional(),
         messages: z.array(z.object({
             id: z.string(),
             fromUserId: z.string(),
+            from: PartySchema,
+            to: PartySchema,
             kind: z.string(),
             subject: z.string(),
             payload: z.record(z.string(), z.unknown()).nullable(),
@@ -33,13 +41,19 @@ export const agentMessagesToolConfig = {
         })),
         acked: z.number().int(),
     }).shape,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
 export function makeAgentMessagesHandler(client) {
     return async (args, extra) => {
+        if (args.messageWork) {
+            if (args.ackIds?.length)
+                throw new Error('Use a separate explicit ACK call.');
+            const result = await makeAgentMessageWorkHandler(client)(args.messageWork, extra);
+            return { content: result.content, structuredContent: { messages: [], acked: 0, work: result.structuredContent } };
+        }
         let acked = 0;
         if (args.ackIds && args.ackIds.length > 0) {
-            const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds });
+            const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds, instanceToken: mcpInstanceToken(undefined, extra) });
             acked = res.acked;
         }
         const q = new URLSearchParams();
@@ -49,21 +63,24 @@ export function makeAgentMessagesHandler(client) {
             q.set('limit', String(args.limit));
         if (args.project)
             q.set('project', args.project);
-        if (!args.includeOwnSends) {
-            q.set('excludeRef', mcpInstanceToken(undefined, extra));
-        }
-        const { messages } = await client.get(`/v1/agent/messages${q.toString() ? `?${q.toString()}` : ''}`);
+        const instanceToken = mcpInstanceToken(undefined, extra);
+        if (!args.includeOwnSends)
+            q.set('excludeRef', instanceToken);
+        const { messages, sessionId } = await client.get(`/v1/agent/messages${q.toString() ? `?${q.toString()}` : ''}`, { instanceToken });
         const lines = messages.length === 0
             ? [acked > 0 ? `Acknowledged ${acked} message(s). Inbox empty.` : 'Inbox empty.']
-            : messages.map((m) => `[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${m.subject} (from ${m.fromUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`);
+            : messages.map((m) => `[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`);
         if (messages.length > 0) {
-            lines.push(`Acknowledge with ackIds once handled; reply via orboto_agent_notify with threadId.`);
+            lines.push(`Acknowledge with ackIds once handled; reply via orboto_agent_notify with threadId (toSessionRef = the sender's instance short id reaches that session only).`);
         }
+        if (sessionId)
+            lines.push(`This session: ${sessionId.slice(0, 8)} (ref ${instanceToken}).`);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {
+                sessionId: sessionId ?? null,
                 messages: messages.map((m) => ({
-                    id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject,
+                    id: m.id, fromUserId: m.fromUserId, from: m.from, to: m.to, kind: m.kind, subject: m.subject,
                     payload: m.payload, threadId: m.threadId, projectKey: m.projectKey ?? null,
                     createdAt: m.createdAt, readAt: m.readAt,
                 })),

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

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { AgentSessionScopeSchema } from './agent-session-scope.js';
+const WorkSessionResourceClaimSchema = z.object({
+    kind: z.enum(['path', 'named']), value: z.string().min(1).max(500), mode: z.enum(['read', 'write']),
+    state: z.enum(['granted', 'waiting']).optional(), requestedAt: z.string().optional(),
+});
+export const AgentInventoryKindSchema = z.enum(['agent', 'human']);
+export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web']);
+export const AgentInventoryConnectionSchema = z.object({ type: AgentConnectionTypeSchema, label: z.string() });
+export const AgentInventoryProjectSchema = z.object({ id: z.string().uuid(), key: z.string(), name: z.string() });
+export const AgentInventoryEntrySchema = z.object({
+    userId: z.string().uuid(),
+    userEmail: z.string(),
+    userFullName: z.string().nullable(),
+    kind: AgentInventoryKindSchema,
+    /** Alias of `kind === 'agent'`. */
+    isBot: z.boolean(),
+    actsAs: z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() }).nullable(),
+    owner: z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() }).nullable(),
+    autonomyPaused: z.boolean(),
+    sessionId: z.string().uuid(),
+    status: z.string(),
+    lane: z.object({ id: z.string().uuid(), name: z.string(), role: z.string(), paused: z.boolean() }).nullable(),
+    projects: z.array(AgentInventoryProjectSchema),
+    connections: z.array(AgentInventoryConnectionSchema),
+    workingOnTicket: z.object({ id: z.string().uuid(), key: z.string().nullable(), title: z.string(), projectKey: z.string().nullable() }).nullable(),
+    workSessions: z.array(z.object({
+        ticketId: z.string().uuid(), ticketKey: z.string().nullable(), role: z.string(), leaseUntil: z.string(),
+        resourceClaims: z.array(WorkSessionResourceClaimSchema),
+    })),
+    capabilities: z.array(z.string()),
+    clientInfo: z.record(z.string(), z.string()),
+    /** ORB-2136 - the scope the session declared; null when it declared none. */
+    scope: AgentSessionScopeSchema.nullable(),
+    /** ORB-2136 - unread inbox messages this session would list. */
+    unreadMessages: z.number().int(),
+    lastSeenAt: z.string(),
+    createdAt: z.string(),
+});
+export const AgentInventorySchema = z.array(AgentInventoryEntrySchema);

package/dist/tools/agent-session-scope.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** ORB-2136 - standalone mirror of `@orboto/shared-schema` agent-session-scope (the MCP package does not depend on it). */
+export const AgentSessionRoleSchema = z.enum(['integrator', 'lead', 'worker', 'spec', 'review', 'coordinator']);
+export const AgentSessionScopeSchema = z.object({
+    projectKeys: z.array(z.string()).optional(),
+    ticketKeys: z.array(z.string()).optional(),
+    role: AgentSessionRoleSchema.optional(),
+});

package/dist/tools/claim.js

@@ -3,6 +3,7 @@
  *
  * @see ORB-179, ORB-181
  */
+import { specGateFailure, isAlreadyAssigned } from './spec-schemas.js';
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken, resolveTicketByKey } from './shared.js';
@@ -15,33 +16,44 @@ const CATEGORY_TO_LEGACY = {
 };
 export const claimToolConfig = {
     title: 'Claim a ticket (assign self + in_progress + timer)',
-    description: 'Composite of `assign self → move to in_progress → start timer` - the canonical "I am picking this up now" move. Idempotent: re-claiming an already-claimed in_progress ticket is a no-op. Set `sole=true` to remove every other assignee first (destructive take-over). Set `force=true` to allow re-claiming a `done` ticket (otherwise refuses, to prevent accidental reopens). Set `noTimer=true` to skip the timer start (e.g. when you only want ownership, not time tracking). If a different ticket has an active timer, it is stopped first (its elapsed time commits a time entry under the previous ticket). '
-        + '`agentSessionToken` is a stable per-agent-instance token: on a bot/service account it scopes the timer to YOUR instance - concurrent per-instance timers and NO auto-stop, so you own both start and stop. Omit it on human accounts, which keep the single-timer behaviour.',
+    description: 'Assign yourself, move to in_progress and start a timer. Repeated claims recheck the specification gate. Worker bots need ready, or override=true with a reason; enabled epics are blocked. sole removes other assignees after the gate passes. force permits reopening done tickets. noTimer skips time tracking. On human accounts a different active timer is stopped first and its elapsed time booked to that ticket. Bot timers are per instance and never auto-stop each other: agentSessionToken defaults to this MCP connection; own both start and stop.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
-        sole: z.boolean().optional().describe('Take-over: remove every other assignee first.'),
-        force: z.boolean().optional().describe('Allow re-claiming a `done` ticket.'),
-        noTimer: z.boolean().optional().describe('Skip the timer start.'),
-        agentSessionToken: z.string().optional().describe('Per-agent-instance token; scopes the timer on bot accounts.'),
+        override: z.boolean().optional().describe("Spec override; reason required."),
+        reason: z.string().trim().min(1).max(2000).optional(),
+        sole: z.boolean().optional().describe('Remove other assignees after gate.'),
+        force: z.boolean().optional().describe('Reopen done.'),
+        noTimer: z.boolean().optional().describe('No timer.'),
+        agentSessionToken: z.string().optional().describe('Instance token for bot timers.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeClaimHandler(client) {
-    return async ({ ticketKey, sole, force, noTimer, agentSessionToken }, extra) => {
+    return async ({ ticketKey, sole, force, override, reason, noTimer, agentSessionToken }, extra) => {
         const me = await client.get('/users/me');
         const current = await resolveTicketByKey(client, ticketKey);
         const currentAssignees = current.assignees ?? [];
-        const alreadyAssigned = currentAssignees.some((a) => a.id === me.id);
+        const alreadyAssigned = currentAssignees.some((a) => (a.userId ?? a.id) === me.id);
         const currentCategory = current.statusCategory;
         if (currentCategory === 'done' && !force) {
             throw new Error(`Refusing to claim [${current.ticketKey}]: status is "done". Pass force=true to reopen + claim.`);
         }
+        try {
+            await client.post(`/projects/${current.projectId}/tickets/${current.id}/assignees/${me.id}`, { override, reason });
+        }
+        catch (error) {
+            const gate = error instanceof OrbotoApiError && error.status === 409 ? specGateFailure(error.body) : undefined;
+            if (gate)
+                return gate;
+            if (!(error instanceof OrbotoApiError) || error.status !== 409 || !isAlreadyAssigned(error.body))
+                throw error;
+        }
         if (sole) {
             for (const a of currentAssignees) {
-                if (a.id === me.id)
+                if ((a.userId ?? a.id) === me.id)
                     continue;
                 try {
-                    await client.delete(`/projects/${current.projectId}/tickets/${current.id}/assignees/${a.id}`);
+                    await client.delete(`/projects/${current.projectId}/tickets/${current.id}/assignees/${a.userId ?? a.id}`);
                 }
                 catch (err) {
                     if (!(err instanceof OrbotoApiError) || err.status !== 404)
@@ -49,15 +61,6 @@ export function makeClaimHandler(client) {
                 }
             }
         }
-        if (!alreadyAssigned) {
-            try {
-                await client.post(`/projects/${current.projectId}/tickets/${current.id}/assignees/${me.id}`, {});
-            }
-            catch (err) {
-                if (!(err instanceof OrbotoApiError) || err.status !== 409)
-                    throw err;
-            }
-        }
         let finalTicket = current;
         if (currentCategory !== 'in_progress') {
             finalTicket = await client.patch(`/projects/${current.projectId}/tickets/${current.id}`, { status: CATEGORY_TO_LEGACY.in_progress });

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) {