@orboto/mcp 0.227.0 → 0.229.0

package/dist/tools/get-timer.js

@@ -4,7 +4,7 @@
 import { z } from 'zod';
 export const getTimerToolConfig = {
     title: 'Get current timer',
-    description: 'Return the caller\'s currently-running stopwatch (or null if no timer is active). The lane is resolved from this session\'s instance token, so a timer started by `orboto_claim` / `orboto_timer_start` in the same checkout reads back (ORB-2137); `laneFallback: true` means the timer was matched as the account\'s only running one because this instance\'s lane was empty - another instance started it.',
+    description: 'Return the caller\'s currently-running stopwatch (or null if no timer is active). The lane is resolved from this session\'s instance token, so a timer started by `orboto_claim` / `orboto_timer_start` in the same checkout reads back (ORB-2137); `laneFallback: true` means the timer was matched as the account\'s only running one because this instance\'s lane was empty - another instance started it. The answer names who runs the timer and its agent session (ORB-2550); the fallback never takes the timer of a session another harness process owns (409 `errors.time.timer_of_other_session` on stop).',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -28,6 +28,7 @@ export function makeGetTimerHandler(client) {
             `Timer ${isPaused ? 'paused' : 'running'} on ${ticketLabel}`,
             `Elapsed: ${minutes} min (${totalSeconds}s total)`,
             `Started: ${timer.startedAt}`,
+            `Owner: ${timer.userFullName ?? timer.userEmail ?? timer.userId}${timer.agentSessionLabel ? `, session ${timer.agentSessionLabel}` : ', no agent session'}`,
             isPaused ? `Paused: ${timer.pausedAt}` : null,
             timer.laneFallback ? 'Matched via the single-active-timer fallback - another instance started it.' : null,
             timer.description ? `Note: ${timer.description}` : null,
@@ -46,6 +47,10 @@ export function makeGetTimerHandler(client) {
                     totalSeconds,
                     paused: isPaused,
                     laneFallback: timer.laneFallback === true,
+                    userId: timer.userId,
+                    userEmail: timer.userEmail ?? null,
+                    agentSessionId: timer.agentSessionId ?? null,
+                    agentSessionLabel: timer.agentSessionLabel ?? null,
                 },
             },
         };

package/dist/tools/identity.js

@@ -4,7 +4,7 @@
 import { z } from 'zod';
 export const whoamiToolConfig = {
     title: 'Show the authenticated MCP principal',
-    description: 'Return the authenticated user record `{id, email, fullName, isBot, workspaceLocale}` for the API key this server runs with. Useful for debugging which credential / bot identity is in use when multiple MCP configs are wired to different `orb_*` keys. **`workspaceLocale` (ORB-989)** is the language the workspace expects tickets / comments / docs in - check it before a mass-create so you write in the right language from the start instead of relying on the after-the-fact language-mismatch warning.',
+    description: 'Return the authenticated user record `{id, email, fullName, isBot, workspaceLocale}` for the API key this server runs with. Useful for debugging which credential / bot identity is in use when multiple MCP configs are wired to different `orb_*` keys. **`workspaceLocale` (ORB-989)** is the language the workspace expects tickets / comments / docs in - check it before a mass-create so you write in the right language from the start instead of relying on the after-the-fact language-mismatch warning. **`agentSession` (ORB-2550)** is the agent session every write of this connection is attributed to, null when the server knows none for its instance token; `foreign: true` means another harness process owns it, so writes carry no session and timers and work sessions are refused until this process has an instance token (`ORBOTO_AGENT_SESSION`) or a profile of its own.',
     inputSchema: z.object({}).shape,
     outputSchema: z.object({
         id: z.string(),
@@ -13,6 +13,7 @@ export const whoamiToolConfig = {
         isBot: z.boolean(),
         workspaceLocale: z.string().nullable(),
         actingAuthorizedBy: z.object({ id: z.string(), email: z.string(), fullName: z.string() }).nullable(),
+        agentSession: z.object({ id: z.string(), label: z.string(), harness: z.string().nullable(), pid: z.number().nullable(), foreign: z.boolean() }).nullable(),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -32,6 +33,13 @@ export function makeWhoamiHandler(client) {
         if (me.actingAuthorizedBy) {
             lines.push(`  acting as this bot, authorised by: ${me.actingAuthorizedBy.fullName} <${me.actingAuthorizedBy.email}>`);
         }
+        const session = me.agentSession ?? null;
+        if (session) {
+            lines.push(`  session: ${session.id} (${session.label})${session.foreign ? ` - owned by ${session.harness ?? 'unknown'} pid ${session.pid ?? 0}, another process: writes carry no session, timers and work sessions are refused; give this process an instance token of its own (ORBOTO_AGENT_SESSION=<own value>) or its own identity (orboto profile bind <harness> <profile>); after a restart of the same harness, orboto session-start registers the row again` : ''}`);
+        }
+        else {
+            lines.push('  session: none - the server knows no session for this connection\'s instance token yet');
+        }
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {
@@ -41,6 +49,7 @@ export function makeWhoamiHandler(client) {
                 isBot,
                 workspaceLocale,
                 actingAuthorizedBy: me.actingAuthorizedBy ?? null,
+                agentSession: session,
             },
         };
     };

package/dist/tools/identity.test.js

@@ -39,9 +39,20 @@ describe('orboto_whoami', () => {
             isBot: true,
             workspaceLocale: 'en',
             actingAuthorizedBy: null,
+            agentSession: null,
         });
         expect(res.content[0].text).toContain('agent-e@orboto.io');
     });
+    it('ORB-2550 - names the session the connection writes under, and a session another live process owns', async () => {
+        const session = { id: '0b0c3a1e-7f73-4c55-8a4e-1d0f0f0f0f0f', label: 'mcp-stdio#0b0c3a1e', harness: 'claude-code', pid: 4242, foreign: false };
+        stub([{ json: { id: 'u5', email: 'agent@orboto.io', isBot: true, agentSession: session } }, { json: { id: 'u5', email: 'agent@orboto.io', isBot: true, agentSession: { ...session, foreign: true } } }]);
+        const own = await makeWhoamiHandler(client)();
+        expect(own.structuredContent).toMatchObject({ agentSession: session });
+        expect(own.content[0].text).toContain(`session: ${session.id} (mcp-stdio#0b0c3a1e)`);
+        const foreign = await makeWhoamiHandler(client)();
+        expect(foreign.content[0].text).toContain('owned by claude-code pid 4242, another process: writes carry no session, timers and work sessions are refused; give this process an instance token of its own (ORBOTO_AGENT_SESSION=<own value>)');
+        expect(foreign.content[0].text).toContain('after a restart of the same harness, orboto session-start registers the row again');
+    });
     it('surfaces workspaceLocale in the text output when present (ORB-989)', async () => {
         stub([{ json: { id: 'u4', email: 'agent@orboto.io', fullName: 'Agent', isBot: true, workspaceLocale: 'de' } }]);
         const res = await makeWhoamiHandler(client)();

package/dist/tools/knowledge.test.js

@@ -92,4 +92,15 @@ describe('ORB-2225 orboto_wiki_runs', () => {
         const handler = makeWikiRunsHandler({ get, post: vi.fn() });
         expect(textOf(await handler({ spaceId: 'ACME-S1' }))).toContain('r2 applied ACME-D10 "Deploy notes" 2026-09-27T09:00:00Z (ops dropped: 1)');
     });
+    it('ORB-2611 - a queued run says how long it waits or runs and whether it stalled', async () => {
+        const get = vi.fn().mockResolvedValue({ runs: [
+                { id: 'r3', sourceKey: 'ACME-D11', sourceTitle: 'AGENTS.md study', status: 'queued', error: null, createdAt: '2026-10-20T15:53:33Z', startedAt: null, ageSeconds: 1260, stalled: true },
+                { id: 'r4', sourceKey: 'ACME-D12', sourceTitle: 'Context rules', status: 'queued', error: null, createdAt: '2026-10-20T15:53:33Z', queuedAt: '2026-10-20T15:53:33Z', startedAt: '2026-10-20T16:03:33Z', ageSeconds: 780, stalled: false },
+            ] });
+        const handler = makeWikiRunsHandler({ get, post: vi.fn() });
+        const text = textOf(await handler({ spaceId: 'ACME-S1', status: 'queued' }));
+        expect(get).toHaveBeenCalledWith('/spaces/ACME-S1/llm-wiki/ingest-runs?status=queued');
+        expect(text).toContain('r3 queued (waiting 21 min, stalled) ACME-D11');
+        expect(text).toContain('r4 queued (running 3 min) ACME-D12');
+    });
 });

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

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 export const listGitAppInstallationsToolConfig = {
     title: 'List GitHub App installations',
-    description: 'Every GitHub App installation orboto knows (admin:system:read): org/user, install time, suspended state and the project keys allowed to use it.',
+    description: 'Every known GitHub App installation (admin:system:read): account, install time, suspension, allowed project keys.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };

package/dist/tools/phase-b-tools.test.js

@@ -611,4 +611,11 @@ describe('orboto_get_timer', () => {
         expect(sc.timer.paused).toBe(false);
         expect(sc.timer.ticketTitle).toBe('Bug');
     });
+    it('ORB-2550 - names who runs the timer and in which agent session', async () => {
+        const startedAt = new Date().toISOString();
+        stub([{ json: { id: 'tm2', userId: 'u1', ticketId: 't1', startedAt, pausedAt: null, accumulatedSeconds: 0, description: null, userEmail: 'claude@orboto.io', userFullName: 'Claude Agent', agentSessionId: 's-1', agentSessionLabel: 'claude-code#0b0c3a1e' } }]);
+        const res = await makeGetTimerHandler(client)();
+        expect(res.content[0].text).toContain('Owner: Claude Agent, session claude-code#0b0c3a1e');
+        expect(res.structuredContent).toMatchObject({ timer: { userId: 'u1', userEmail: 'claude@orboto.io', agentSessionId: 's-1', agentSessionLabel: 'claude-code#0b0c3a1e' } });
+    });
 });

package/dist/tools/presence-scope.test.js

@@ -0,0 +1,170 @@
+/**
+ * ORB-2553 - the MCP side of mandatory presence scope: the refusal is read
+ * off the API error, orboto_session_start starts with `start` and renders a
+ * refusal or a takeover, the proxy's default declaration is a start, and
+ * orboto_who prints the refused heartbeats per account.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { exitedPredecessor, presenceRefusal, processAlive } from './shared.js';
+import { makeSessionStartHandler, takeoverLine } from './session-start.js';
+import { makeAgentWhoHandler, refusalLines } from './agent-who.js';
+import { makeAgentHeartbeatHandler } from './agent-coordination.js';
+import { declareEnvProjectScope } from '../project-scope.js';
+import { _forgetDeclaredScopes } from '../session-scope-memory.js';
+import { checkoutHash, machineId, shortHost, stdioOrigin } from '../session-origin.js';
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const SESSION_EXISTS = {
+    error: 'Another live session of this account runs in sample-repo on build-host: 0123abcd (claude-code, 42 min, ORB-7). Start again with --adopt to take over its scope, mail and leases, or with --end-previous to end it.',
+    errorKey: 'errors.agents.session_exists',
+    errorParams: { sessionId: '0123abcd-0000-4000-8000-000000000000', shortId: '0123abcd', ageMinutes: 42, ticket: 'ORB-7', host: 'build-host', repo: 'sample-repo', harness: 'claude-code', role: 'integrator', projects: 'ORB' },
+};
+const SCOPE_REQUIRED = { error: 'This session declares no scope', errorKey: 'errors.agents.scope_required', errorParams: { command: 'orboto session-start --role <role> --scope-projects <KEY>', notes: ['Not carried over: the earlier scope.'] } };
+beforeEach(() => { _forgetDeclaredScopes(); });
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
+function stub(heartbeat, seen, extra = {}) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const u = new URL(url.toString());
+        const path = u.pathname + u.search;
+        seen.push({ path, body: init?.body ? JSON.parse(init.body) : undefined });
+        if (u.pathname === '/v1/agent/heartbeat' && init?.method === 'POST') {
+            return { ok: heartbeat.status < 300, status: heartbeat.status, statusText: 'x', headers: new Headers(), json: async () => heartbeat.body, text: async () => JSON.stringify(heartbeat.body) };
+        }
+        const map = {
+            '/users/me/assigned-tickets': { items: [] }, '/users/me': { email: 'dev@x.io' }, '/agent-instructions': { instructions: 'rules', rulesHash: 'h' }, ...extra,
+        };
+        const key = Object.keys(map).find((k) => path.startsWith(k));
+        return { ok: true, status: 200, statusText: 'OK', headers: new Headers(), json: async () => (key ? map[key] : {}), text: async () => '' };
+    });
+}
+describe('ORB-2553 - the refusal on the MCP side', () => {
+    it('presenceRefusal reads the two refusals and their notes, nothing else', () => {
+        expect(presenceRefusal(new OrbotoApiError(409, JSON.stringify(SESSION_EXISTS), 'u'))).toMatchObject({ key: 'errors.agents.session_exists', params: { shortId: '0123abcd' } });
+        expect(presenceRefusal(new OrbotoApiError(422, JSON.stringify(SCOPE_REQUIRED), 'u'))?.message).toBe('This session declares no scope\nNot carried over: the earlier scope.');
+        expect(presenceRefusal(new OrbotoApiError(409, JSON.stringify({ errorKey: 'errors.agents.no_recipient' }), 'u'))).toBeNull();
+        expect(presenceRefusal(new OrbotoApiError(422, 'not json', 'u'))).toBeNull();
+        expect(presenceRefusal(new Error('x'))).toBeNull();
+    });
+    it('orboto_session_start sends start and previous, and renders a second start as not registered with the way out', async () => {
+        const seen = [];
+        stub({ status: 409, body: SESSION_EXISTS }, seen);
+        const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' });
+        const res = await makeSessionStartHandler(client)({ scope: { role: 'integrator', projectKeys: ['ORB'] }, previous: 'adopt' }, { sessionId: 'ps1' });
+        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({ start: true, previous: 'adopt', scope: { role: 'integrator', projectKeys: ['ORB'] } });
+        const text = res.content[0].text;
+        expect(text).toContain('Not registered: Another live session of this account runs in sample-repo on build-host: 0123abcd');
+        expect(text).toContain('previous: "adopt" or "end"');
+        expect(text).not.toContain('Peers reach exactly this session');
+        expect(res.structuredContent.session.refused).toContain('0123abcd');
+    });
+    it('a start that took over the previous session says what moved', async () => {
+        const seen = [];
+        const takeover = { action: 'adopted', sessionId: '0123abcd-0000-4000-8000-000000000000', shortId: '0123abcd', movedMessages: 2, movedLeases: ['ORB-7'], releasedTickets: [] };
+        stub({ status: 200, body: { sessionToken: 'mcp-ps2', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] }, takeover } }, seen);
+        const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' });
+        const res = await makeSessionStartHandler(client)({ previous: 'adopt' }, { sessionId: 'ps2' });
+        expect(res.content[0].text).toContain('Adopted session 0123abcd: 2 unread message(s) and the leases on ORB-7 moved here, it is ended.');
+        expect(takeoverLine({ action: 'ended', shortId: 'abcd0123', movedMessages: 0, movedLeases: [], releasedTickets: ['ORB-9'] })).toBe('Ended the previous session abcd0123 in this repository; its leases on ORB-9 are released.');
+    });
+    it('the proxy declares the checkout project as a start and hands back the refusal', async () => {
+        const calls = [];
+        const refusing = {
+            get: async () => ({ sessionId: 'x', scope: null }),
+            post: async (_path, body) => { calls.push(body); throw new OrbotoApiError(409, JSON.stringify(SESSION_EXISTS), 'u'); },
+        };
+        const row = await declareEnvProjectScope(refusing, 'agent-abc', 'ACME', undefined, false);
+        expect(calls).toEqual([{ scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }]);
+        expect(row).toEqual({ refusal: SESSION_EXISTS.error });
+    });
+    it('orboto_agent_heartbeat answers a refusal as a tool error with the hint', async () => {
+        stub({ status: 422, body: SCOPE_REQUIRED }, []);
+        const res = await makeAgentHeartbeatHandler(new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' }))({ status: 'working' }, { sessionId: 'ps3' });
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toBe('heartbeat refused (ORB-2553) - This session declares no scope\nNot carried over: the earlier scope.');
+    });
+    it('the proxy names the hashed checkout it runs in; a linked worktree is a checkout of its own', () => {
+        const main = realpathSync(mkdtempSync(join(tmpdir(), 'orboto-checkout-')));
+        mkdirSync(join(main, '.git'));
+        const tree = join(main, '.claude', 'worktrees', 'agent-1');
+        mkdirSync(join(tree, 'sub'), { recursive: true });
+        writeFileSync(join(tree, '.git'), `gitdir: ${join(main, '.git', 'worktrees', 'agent-1')}\n`);
+        const hash = (dir) => createHash('sha256').update(dir).digest('hex').slice(0, 16);
+        expect(checkoutHash(join(tree, 'sub'))).toBe(hash(tree));
+        expect(checkoutHash(main)).toBe(hash(main));
+        expect(checkoutHash(tree)).not.toBe(checkoutHash(main));
+        expect(new URLSearchParams(stdioOrigin({})).get('checkout')).toBe(checkoutHash());
+    });
+    it('orboto_session_start sends the environment project as fallbackScope in its start beat', async () => {
+        vi.stubEnv('ORBOTO_PROJECT_KEY', 'acme');
+        vi.stubEnv('ORBOTO_SESSION_ROLE', '');
+        const seen = [];
+        stub({ status: 200, body: { sessionToken: 'mcp-ps4', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'worker', projectKeys: ['ACME'] } } }, seen);
+        await makeSessionStartHandler(new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' }))({}, { sessionId: 'ps4' });
+        const beats = seen.filter((c) => c.path === '/v1/agent/heartbeat');
+        expect(beats.map((b) => b.body)).toEqual([{ start: true, fallbackScope: { role: 'worker', projectKeys: ['ACME'] } }]);
+    });
+    it('a second-start refusal on this machine whose pid has exited names an exited predecessor; a live pid or another machine does not', () => {
+        const refusal = (pid, machine, host = 'build-host') => presenceRefusal(new OrbotoApiError(409, JSON.stringify({ ...SESSION_EXISTS, errorParams: { ...SESSION_EXISTS.errorParams, pid, machineId: machine, host } }), 'u'));
+        const here = { machine: 'machine-a', host: 'build-host' };
+        expect(exitedPredecessor(refusal(4100, 'machine-a'), here, () => false)).toEqual({ shortId: '0123abcd', pid: 4100, line: 'previous session 0123abcd (pid 4100) has exited, ended it' });
+        expect(exitedPredecessor(refusal(4100, 'machine-a'), here, () => true)).toBeNull();
+        expect(exitedPredecessor(refusal(4100, 'machine-b'), here, () => false)).toBeNull();
+        expect(exitedPredecessor(refusal(4100, null), here, () => false)).not.toBeNull();
+        expect(exitedPredecessor(refusal(4100, null, 'other-host'), here, () => false)).toBeNull();
+        expect(exitedPredecessor(refusal(4100, 'machine-a', 'cloned-vm'), here, () => false)).toBeNull();
+        expect(processAlive(process.pid)).toBe(true);
+        expect(processAlive(2 ** 30)).toBe(false);
+    });
+    it('orboto_session_start ends an exited predecessor on its own and says so in one line', async () => {
+        const seen = [];
+        let calls = 0;
+        const exited = { ...SESSION_EXISTS, errorParams: { ...SESSION_EXISTS.errorParams, pid: 2 ** 30, machineId: machineId(), host: shortHost() } };
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            seen.push({ path: u.pathname + u.search, body: init?.body ? JSON.parse(init.body) : undefined });
+            if (u.pathname === '/v1/agent/heartbeat' && init?.method === 'POST' && (calls += 1) === 1) {
+                return { ok: false, status: 409, statusText: 'x', headers: new Headers(), json: async () => exited, text: async () => JSON.stringify(exited) };
+            }
+            const body = u.pathname === '/v1/agent/heartbeat'
+                ? { sessionToken: 'mcp-ps5', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'worker', projectKeys: ['ORB'] }, takeover: { action: 'ended', shortId: '0123abcd', movedMessages: 0, movedLeases: [], releasedTickets: [] } }
+                : u.pathname === '/agent-instructions' ? { instructions: 'rules', rulesHash: 'h' } : {};
+            return { ok: true, status: 200, statusText: 'OK', headers: new Headers(), json: async () => body, text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' }))({ scope: { role: 'worker', projectKeys: ['ORB'] } }, { sessionId: 'ps5' });
+        const beats = seen.filter((c) => c.path === '/v1/agent/heartbeat').map((c) => c.body);
+        expect(beats.map((b) => b.previous)).toEqual([undefined, 'end']);
+        const text = res.content[0].text;
+        expect(text).toContain('previous session 0123abcd (pid 1073741824) has exited, ended it');
+        expect(text).not.toContain('Not registered');
+    });
+    it('the proxy declaration ends an exited predecessor on its own', async () => {
+        const calls = [];
+        const exited = { ...SESSION_EXISTS, errorParams: { ...SESSION_EXISTS.errorParams, pid: 2 ** 30, machineId: machineId(), host: shortHost() } };
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const restarting = {
+            get: async () => ({ sessionId: 'x', scope: null }),
+            post: async (_path, body) => {
+                calls.push(body);
+                if (calls.length === 1)
+                    throw new OrbotoApiError(409, JSON.stringify(exited), 'u');
+                return { sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'worker', projectKeys: ['ACME'] } };
+            },
+        };
+        const row = await declareEnvProjectScope(restarting, 'agent-abc', 'ACME', undefined, false);
+        expect(calls).toEqual([{ scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }, { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true, previous: 'end' }]);
+        expect(row).toMatchObject({ sessionId: 'cbb52195-0000-4000-8000-000000000000' });
+    });
+    it('orboto_who lists the refused heartbeats per account after the sessions', async () => {
+        const refusals = [{ userId: 'u1', email: 'agent@x.io', count: 3, scopeRequired: 2, sessionExists: 1, since: 't0', lastAt: '2026-10-20T10:00:00.000Z', lastReason: 'session_exists', lastHost: 'build-host', lastRepo: 'sample-repo', lastHarness: 'claude-code' }];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: true, status: 200, statusText: 'OK', headers: new Headers(), json: async () => ({ sessions: [], refusals, nextCursor: null }), text: async () => '' }));
+        const res = await makeAgentWhoHandler(new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' }))({});
+        const text = res.content[0].text;
+        expect(text).toContain('Refused heartbeats in the last 24 hours (no role address, not listed):');
+        expect(text).toContain('- agent@x.io: 3 (no scope 2, second start 1), last 2026-10-20T10:00:00.000Z from build-host/sample-repo (claude-code)');
+        expect(res.structuredContent.refusals).toHaveLength(1);
+        expect(refusalLines(undefined)).toEqual([]);
+    });
+});

package/dist/tools/primer-facts.js

@@ -103,12 +103,12 @@ export const primerFactAddToolConfig = {
         + FACT_WRITING_CONTRACT,
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key, e.g. "ORB". Case-insensitive.'),
-        category: PrimerFactCategoryEnum.describe('Category bucket. Pick the closest fit; categories are fixed. Use "non_functional" to capture an explicit non-functional requirement (performance / security / DSGVO / operations / i18n) - the key names the sub-area, the value is the requirement; these render verbatim in the requirements-spec NFR chapter. Use "glossary" for a term/definition pair - these render only in the requirements-spec glossary chapter.'),
-        key: z.string().min(1).max(120).describe('Short machine-readable identifier, e.g. "package-manager", "node-version", "css-framework". Lowercase + dashes preferred.'),
-        value: z.string().min(1).max(8000).describe('Human-readable Markdown body, 1-3 sentences typically. Include a version number, a path, or a command where relevant.'),
-        observed: z.boolean().default(false).describe('True = source is agent_observed (needs operator verification). False = manual entry by operator. A bot account or an agent key is always coerced to agent_observed server-side, whatever is sent.'),
-        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (300*2 chars). Only after a call was blocked.'),
-        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this value genuinely needs the length. Audit-logged.'),
+        category: PrimerFactCategoryEnum.describe('Fixed category. non_functional: an NFR (key = area, value = requirement, rendered in the spec NFR chapter); glossary: a term/definition (spec glossary only).'),
+        key: z.string().min(1).max(120).describe('Short id, lowercase-dashed, e.g. "node-version".'),
+        value: z.string().min(1).max(8000).describe('Markdown, 1-3 sentences; name versions, paths, commands.'),
+        observed: z.boolean().default(false).describe('True files agent_observed (a person verifies); a bot or agent key is always agent_observed.'),
+        allowOversize: z.boolean().optional().describe('Override the 600-char hard cap after a blocked call.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('With allowOversize: why it needs the length (audited).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -158,8 +158,8 @@ export const primerFactUpdateToolConfig = {
         value: z.string().min(1).max(8000).optional().describe('New Markdown body.'),
         category: PrimerFactCategoryEnum.optional().describe('New category.'),
         key: z.string().min(1).max(120).optional().describe('New key.'),
-        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (300*2 chars). Only after a call was blocked.'),
-        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this value genuinely needs the length. Audit-logged.'),
+        allowOversize: z.boolean().optional().describe('Override the 600-char hard cap after a blocked call.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('With allowOversize: why it needs the length (audited).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
@@ -213,8 +213,8 @@ export const primerFactSupersedeToolConfig = {
         category: PrimerFactCategoryEnum.describe('Category of the new fact (usually unchanged).'),
         key: z.string().min(1).max(120).describe('Key of the new fact (usually unchanged).'),
         value: z.string().min(1).max(8000).describe('Corrected Markdown body.'),
-        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (300*2 chars). Only after a call was blocked.'),
-        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this value genuinely needs the length. Audit-logged.'),
+        allowOversize: z.boolean().optional().describe('Override the 600-char hard cap after a blocked call.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('With allowOversize: why it needs the length (audited).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };

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

@@ -1,7 +1,7 @@
 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']);
-const ProjectReadinessFixSchema = z.object({ method: z.string(), route: z.string(), mcpTool: z.string(), cliCommand: z.string(), settingsPath: z.string() });
+const ProjectReadinessFixSchema = z.object({ method: z.string(), route: z.string(), mcpTool: z.string(), cliCommand: z.string(), settingsPath: z.string(), note: z.string().optional() });
 export const ProjectReadinessItemSchema = z.object({
     id: ProjectReadinessItemIdSchema,
     status: ProjectReadinessStatusSchema,

package/dist/tools/rule-proposals.js

@@ -0,0 +1,131 @@
+/**
+ * ORB-2579 - rule proposals: an agent proposes a behaviour rule, a person with rule rights accepts or rejects it.
+ */
+import { z } from 'zod';
+import { sizeBlockResult } from './shared.js';
+const SCOPES = ['workspace', 'customer', 'project', 'personal'];
+function duplicateLines(row) {
+    return row.duplicates.map((d) => `\n  ${d.exact ? 'exact' : 'text'} match: ${d.kind} "${d.title}" (${d.id})`).join('');
+}
+function scopeLabel(row) {
+    return row.projectKey ? `${row.scope} ${row.projectKey}` : row.scope;
+}
+export const ruleProposeToolConfig = {
+    title: 'Propose a behaviour rule',
+    description: 'Propose a behaviour rule for a person to accept. It binds only once a person with rule rights accepts it, and the decision comes back as agent mail; overlapping rules are named as text matches. Title: one imperative sentence; body <= 400 chars, Rule / Why / How.',
+    inputSchema: z.object({
+        title: z.string().min(1).max(120),
+        body: z.string().min(1).max(8000),
+        scope: z.enum(SCOPES).default('workspace'),
+        projectKey: z.string().min(1).max(32).optional(),
+        customerId: z.string().uuid().optional(),
+        reason: z.string().min(1).max(1000).optional(),
+        allowOversize: z.boolean().optional(),
+        oversizeReason: z.string().min(10).max(500).optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeRuleProposeHandler(client) {
+    return async (input) => {
+        let row;
+        try {
+            row = await client.post('/agent-instructions/proposals', { ...input, scope: input.scope ?? 'workspace' });
+        }
+        catch (err) {
+            const blocked = sizeBlockResult(err, 'Rule proposal');
+            if (blocked)
+                return blocked;
+            throw err;
+        }
+        const warn = row.sizeWarning ? `\nBody is over the ${row.sizeWarning.limit}-char soft limit. ${row.sizeWarning.hint}` : '';
+        return {
+            content: [{ type: 'text', text: `Proposed rule "${row.title}" (${scopeLabel(row)}, id ${row.id}), pending review by a person with rule rights.${duplicateLines(row)}${warn}` }],
+            structuredContent: row,
+        };
+    };
+}
+export const ruleProposalsToolConfig = {
+    title: 'List rule proposals',
+    description: 'List rule proposals. Your own plus the queue you may see, newest first; canDecide marks what you may accept or reject (a person with rule rights: orboto_rule_proposal_accept, orboto_rule_proposal_reject).',
+    inputSchema: z.object({
+        status: z.enum(['pending', 'accepted', 'rejected', 'all']).default('pending'),
+        scope: z.enum(SCOPES).optional(),
+        projectId: z.string().uuid().optional(),
+        customerId: z.string().uuid().optional(),
+        mine: z.boolean().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        cursor: z.string().optional(),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeRuleProposalsHandler(client) {
+    return async (input = {}) => {
+        const p = new URLSearchParams({ status: input.status ?? 'pending' });
+        if (input.scope)
+            p.set('scope', input.scope);
+        if (input.projectId)
+            p.set('projectId', input.projectId);
+        if (input.customerId)
+            p.set('customerId', input.customerId);
+        if (input.mine !== undefined)
+            p.set('mine', String(input.mine));
+        if (input.limit !== undefined)
+            p.set('limit', String(input.limit));
+        if (input.cursor)
+            p.set('cursor', input.cursor);
+        const page = await client.get(`/agent-instructions/proposals?${p.toString()}`);
+        const lines = page.items.map((r) => `- [${r.status}] ${r.title} (${scopeLabel(r)}, id ${r.id}, by ${r.proposedByName ?? 'unknown'})${r.canDecide ? ' [you can decide]' : ''}${r.decisionReason ? `\n  reason: ${r.decisionReason}` : ''}${duplicateLines(r)}`);
+        return {
+            content: [{ type: 'text', text: (lines.length ? lines.join('\n') : 'No rule proposals.') + (page.nextCursor ? `\nMore: cursor ${page.nextCursor}` : '') }],
+            structuredContent: page,
+        };
+    };
+}
+function decisionText(verb, res) {
+    const block = res.block ? ` as rule block ${res.block.id}${res.proposal.acceptedEdited ? ' (edited)' : ''}` : '';
+    return `${verb} rule proposal "${res.proposal.title}"${block}; ${res.proposerNotified ? 'the proposer got the decision as agent mail' : 'no agent mail was sent'}.`;
+}
+export const ruleProposalAcceptToolConfig = {
+    title: 'Accept a rule proposal',
+    description: 'Accept a pending rule proposal as a rule block, as proposed or edited. A person with rule rights on its scope only, on the explicit instruction of that person; a bot account or an agent key gets 403 errors.agent_rules.review_needs_person. must-read stays off unless set.',
+    inputSchema: z.object({
+        proposalId: z.string().uuid(),
+        title: z.string().min(1).max(120).optional(),
+        body: z.string().min(1).max(8000).optional(),
+        mustRead: z.boolean().optional(),
+        note: z.string().min(1).max(1000).optional(),
+        allowOversize: z.boolean().optional(),
+        oversizeReason: z.string().min(10).max(500).optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeRuleProposalAcceptHandler(client) {
+    return async ({ proposalId, ...body }) => {
+        let res;
+        try {
+            res = await client.post(`/agent-instructions/proposals/${encodeURIComponent(proposalId)}/accept`, body);
+        }
+        catch (err) {
+            const blocked = sizeBlockResult(err, 'Rule proposal accept');
+            if (blocked)
+                return blocked;
+            throw err;
+        }
+        return { content: [{ type: 'text', text: decisionText('Accepted', res) }], structuredContent: res };
+    };
+}
+export const ruleProposalRejectToolConfig = {
+    title: 'Reject a rule proposal',
+    description: 'Reject a pending rule proposal with a reason the proposer receives. A person with rule rights on its scope only, on the explicit instruction of that person; a bot account or an agent key gets 403 errors.agent_rules.review_needs_person.',
+    inputSchema: z.object({
+        proposalId: z.string().uuid(),
+        reason: z.string().min(3).max(1000),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+export function makeRuleProposalRejectHandler(client) {
+    return async ({ proposalId, reason }) => {
+        const res = await client.post(`/agent-instructions/proposals/${encodeURIComponent(proposalId)}/reject`, { reason });
+        return { content: [{ type: 'text', text: decisionText('Rejected', res) }], structuredContent: res };
+    };
+}

package/dist/tools/rule-proposals.test.js

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeRuleProposalAcceptHandler, makeRuleProposalRejectHandler, makeRuleProposeHandler, makeRuleProposalsHandler } from './rule-proposals.js';
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({ url: url.toString(), method: init?.method ?? 'GET', body: typeof init?.body === 'string' ? JSON.parse(init.body) : undefined });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        const status = r.status ?? 200;
+        return { ok: status < 400, status, statusText: 'x', json: async () => r.json, text: async () => JSON.stringify(r.json) };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const ROW = {
+    id: '11111111-1111-1111-1111-111111111111', scope: 'project', projectKey: 'ORB', title: 'Run the gates one by one', status: 'pending',
+    duplicates: [{ kind: 'rule', id: '22222222-2222-2222-2222-222222222222', title: 'Gates run separately', exact: false }],
+    proposedByName: 'Claude Agent', decisionReason: null, canDecide: false,
+};
+describe('rule proposal MCP tools (ORB-2579)', () => {
+    it('propose posts the proposal with the workspace default and names the text matches', async () => {
+        const calls = stub([{ status: 201, json: ROW }]);
+        const res = await makeRuleProposeHandler(client)({ title: ROW.title, body: 'Rule: one gate per call.', projectKey: 'ORB', scope: 'project', reason: 'a chained call ran one gate' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: 'https://orboto.example.com/agent-instructions/proposals' });
+        expect(calls[0].body).toEqual({ title: ROW.title, body: 'Rule: one gate per call.', projectKey: 'ORB', scope: 'project', reason: 'a chained call ran one gate' });
+        const text = res.content[0].text;
+        expect(text).toContain('pending review by a person with rule rights');
+        expect(text).toContain('text match: rule "Gates run separately"');
+        expect(text).not.toMatch(/%/);
+        const calls2 = stub([{ status: 201, json: { ...ROW, scope: 'workspace', projectKey: null, duplicates: [] } }]);
+        await makeRuleProposeHandler(client)({ title: 'x', body: 'y' });
+        expect(calls2[0].body).toEqual({ title: 'x', body: 'y', scope: 'workspace' });
+    });
+    it('propose turns the hard-cap refusal into a blocked result', async () => {
+        stub([{ status: 422, json: { error: 'too long', errorKey: 'errors.agent_content.oversize', sizeWarning: { chars: 900, limit: 800, hint: 'shorten it' } } }]);
+        const res = await makeRuleProposeHandler(client)({ title: 'x', body: 'y'.repeat(900) });
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toContain('Rule proposal blocked');
+    });
+    it('list sends status, mine and cursor and marks what the caller can decide', async () => {
+        const calls = stub([{ json: { items: [{ ...ROW, canDecide: true }], nextCursor: 'abc' } }]);
+        const res = await makeRuleProposalsHandler(client)({ status: 'all', mine: true, cursor: 'c1' });
+        expect(calls[0].url).toBe('https://orboto.example.com/agent-instructions/proposals?status=all&mine=true&cursor=c1');
+        const text = res.content[0].text;
+        expect(text).toContain('[pending] Run the gates one by one (project ORB');
+        expect(text).toContain('[you can decide]');
+        expect(text).toContain('More: cursor abc');
+    });
+    it('list defaults to the pending queue and says when it is empty', async () => {
+        const calls = stub([{ json: { items: [], nextCursor: null } }]);
+        const res = await makeRuleProposalsHandler(client)();
+        expect(calls[0].url).toBe('https://orboto.example.com/agent-instructions/proposals?status=pending');
+        expect(res.content[0].text).toBe('No rule proposals.');
+    });
+    it('list forwards the scope, project, customer and limit filters', async () => {
+        const calls = stub([{ json: { items: [], nextCursor: null } }]);
+        await makeRuleProposalsHandler(client)({ scope: 'project', projectId: '44444444-4444-4444-8444-444444444444', customerId: '55555555-5555-4555-8555-555555555555', limit: 10 });
+        expect(calls[0].url).toBe('https://orboto.example.com/agent-instructions/proposals?status=pending&scope=project&projectId=44444444-4444-4444-8444-444444444444&customerId=55555555-5555-4555-8555-555555555555&limit=10');
+    });
+    it('accept posts the edits and names the new block', async () => {
+        const calls = stub([{ json: { proposal: { ...ROW, status: 'accepted', acceptedEdited: true }, block: { id: 'b1' }, proposerNotified: true } }]);
+        const res = await makeRuleProposalAcceptHandler(client)({ proposalId: ROW.id, title: 'Short', mustRead: true, note: 'tightened' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/agent-instructions/proposals/${ROW.id}/accept`, body: { title: 'Short', mustRead: true, note: 'tightened' } });
+        expect(res.content[0].text).toBe(`Accepted rule proposal "${ROW.title}" as rule block b1 (edited); the proposer got the decision as agent mail.`);
+    });
+    it('accept surfaces the person-only refusal and the hard-cap block', async () => {
+        stub([{ status: 403, json: { error: 'A person with rule rights decides on a rule proposal', errorKey: 'errors.agent_rules.review_needs_person' } }]);
+        await expect(makeRuleProposalAcceptHandler(client)({ proposalId: ROW.id })).rejects.toThrow(/403/);
+        stub([{ status: 422, json: { error: 'too long', sizeWarning: { chars: 900, limit: 800, hint: 'shorten it' } } }]);
+        const blocked = await makeRuleProposalAcceptHandler(client)({ proposalId: ROW.id, body: 'x'.repeat(900) });
+        expect(blocked.isError).toBe(true);
+    });
+    it('reject posts the reason', async () => {
+        const calls = stub([{ json: { proposal: { ...ROW, status: 'rejected', decisionReason: 'covered' }, block: null, proposerNotified: false } }]);
+        const res = await makeRuleProposalRejectHandler(client)({ proposalId: ROW.id, reason: 'covered' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/agent-instructions/proposals/${ROW.id}/reject`, body: { reason: 'covered' } });
+        expect(res.content[0].text).toBe(`Rejected rule proposal "${ROW.title}"; no agent mail was sent.`);
+    });
+});

package/dist/tools/semantic-degraded-wrapper.test.js

@@ -57,7 +57,7 @@ it('search, search-docs, ask-docs and check-similar print the degraded line on s
             child.on('close', (code) => code === 0 ? ok({ out, err }) : no(new Error(`Wrapper exit ${code}: ${err}`)));
             child.stdin.end('');
         });
-        for (const args of [['search', 'frobnicator'], ['search-docs', 'frobnicator'], ['ask-docs', 'how to restart'], ['check-similar', 'ORB', 'Frobnicator jams']]) {
+        for (const args of [['search', 'frobnicator'], ['search-docs', 'frobnicator'], ['ask-docs', 'how to restart'], ['check-similar', 'ORB', 'Frobnicator jams'], ['ticket', 'check-similar', 'ORB', 'Frobnicator jams']]) {
             const { out, err } = await run(args);
             expect(err, args.join(' ')).toContain(LINE);
             expect(out, args.join(' ')).not.toContain(LINE);