@orboto/mcp 0.226.2 → 0.228.1

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

@@ -99,16 +99,16 @@ export function makePrimerFactListHandler(client) {
 }
 export const primerFactAddToolConfig = {
     title: 'Record a new project primer fact',
-    description: 'Record a new structured fact about the project that future AI agents should see at session start. Use when you learn something during work that is missing from the primer (a library version, a convention, a deployment quirk, an architecture decision). Note: the auto-generated primer does NOT automatically include CLAUDE.md / AGENTS.md content unless the operator configured repo briefings and the API host can read those files from disk - most deployments cannot. Treat key conventions documented in CLAUDE.md / AGENTS.md as fair game to record here so they survive cross-deployment. Set observed=true when you are recording from a bot/agent context - the fact will land as agent_observed and require operator verification before losing the (observed) marker.'
+    description: 'Record a new structured fact about the project that future AI agents should see at session start. Use when you learn something during work that is missing from the primer (a library version, a convention, a deployment quirk, an architecture decision). Note: the auto-generated primer does NOT automatically include CLAUDE.md / AGENTS.md content unless the operator configured repo briefings and the API host can read those files from disk - most deployments cannot. Treat key conventions documented in CLAUDE.md / AGENTS.md as fair game to record here so they survive cross-deployment. Set observed=true when you are recording from a bot/agent context - the fact will land as agent_observed and require a person to verify it before it loses the (observed) marker (CLI: orboto primer-fact add <KEY> --category <c> --key <k> --value "<v>" --observed).'
         + 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. Bots without project:edit get coerced to agent_observed server-side regardless.'),
-        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 },
 };
@@ -151,15 +151,15 @@ export function makePrimerFactAddHandler(client) {
 }
 export const primerFactUpdateToolConfig = {
     title: 'Update an existing primer fact',
-    description: 'Update an existing fact. Use this when the value has changed (e.g. version bumped) or you are renaming the key. Bumps last_verified_at automatically when the value changes; pure renames leave it untouched. To replace a fact while preserving history, use orboto_primer_fact_supersede instead.'
+    description: 'Update an existing fact. Use this when the value has changed (e.g. version bumped) or you are renaming the key. Bumps last_verified_at automatically when the value changes; pure renames leave it untouched. To replace a fact while preserving history, use orboto_primer_fact_supersede instead. A person decides: a bot account or an agent key gets 403 errors.primer_facts.update_needs_person and proposes a corrected fact with orboto_primer_fact_add (observed) instead.'
         + FACT_WRITING_CONTRACT,
     inputSchema: z.object({
         factId: z.string().min(1).describe('UUID of the fact to update. Read it from orboto_primer_fact_list output.'),
         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 },
 };
@@ -206,15 +206,15 @@ export function makePrimerFactUpdateHandler(client) {
 }
 export const primerFactSupersedeToolConfig = {
     title: 'Replace a primer fact while preserving history',
-    description: 'Replace a fact with a corrected version, preserving the old one in history (linked via superseded_by_id). Use when you discover a previously recorded fact was wrong; do not just delete it. The old row gets a tombstoned key suffix so the partial unique index does not collide; the new row starts unverified and needs operator verification before losing the (observed) marker.'
+    description: 'Replace a fact with a corrected version, preserving the old one in history (linked via superseded_by_id). Use when you discover a previously recorded fact was wrong; do not just delete it. The old row gets a tombstoned key suffix so the partial unique index does not collide; the new row starts unverified and needs a person to verify it before it loses the (observed) marker. A person decides: a bot account or an agent key gets 403 errors.primer_facts.supersede_needs_person and proposes the corrected fact with orboto_primer_fact_add (observed) instead.'
         + FACT_WRITING_CONTRACT,
     inputSchema: z.object({
         oldFactId: z.string().min(1).describe('UUID of the fact being replaced.'),
         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 },
 };
@@ -247,7 +247,7 @@ export function makePrimerFactSupersedeHandler(client) {
 }
 export const primerFactVerifyToolConfig = {
     title: 'Verify an agent-observed primer fact',
-    description: 'Promote an agent-observed fact to verified. A person verifies: a bot account or an agent key gets 403 errors.primer_facts.verify_needs_person, so an agent proposes and never confirms. Removes the (observed) marker from the rendered primer and stamps verifiedBy / verifiedAt.',
+    description: 'Promote an agent-observed fact to verified. A person verifies: a bot account or an agent key gets 403 errors.primer_facts.verify_needs_person, so an agent proposes and never confirms (CLI: orboto primer-fact verify). Removes the (observed) marker from the rendered primer and stamps verifiedBy / verifiedAt.',
     inputSchema: z.object({
         factId: z.string().min(1).describe('UUID of the fact to verify.'),
     }).shape,
@@ -274,7 +274,7 @@ export function makePrimerFactVerifyHandler(client) {
 }
 export const primerFactDeleteToolConfig = {
     title: 'Delete a primer fact',
-    description: 'Hard-delete a fact. Prefer orboto_primer_fact_supersede when the fact is being replaced; only delete when the fact was wrong from the start or no longer relevant. Writes an audit-log entry; the row itself is gone (no soft-delete).',
+    description: 'Hard-delete a fact. Prefer orboto_primer_fact_supersede when the fact is being replaced; only delete when the fact was wrong from the start or no longer relevant. Writes an audit-log entry; the row itself is gone (no soft-delete). Deleting an unverified agent-observed fact is the Reject of the review queue. A person decides: a bot account or an agent key gets 403 errors.primer_facts.reject_needs_person (observed proposal) or errors.primer_facts.delete_needs_person (CLI: orboto primer-fact reject).',
     inputSchema: z.object({
         factId: z.string().min(1).describe('UUID of the fact to delete.'),
         reason: z.string().max(500).optional().describe('Optional human-readable reason; recorded in the audit log details for future operators.'),

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/read-budget.test.js

@@ -0,0 +1,161 @@
+/**
+ * ORB-2548 - the evidence cases of the OCP integrator (2026-10-16) answered
+ * inside the 4,000-character budget: presence returned 236,455 characters
+ * with 1 of 32 rows kept, and finding one session took ~230 kB of expand
+ * calls; the inbox needed one to three expand calls.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { DEFAULT_BUDGET_CHARS, applyResponseBudget, budgetFor, measureHalves } from '../response-budget.js';
+import { makeAgentPresenceHandler } from './agent-coordination.js';
+import { makeAgentWhoHandler } from './agent-who.js';
+import { makeAgentMessagesHandler } from './agent-messages.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+const uuid = (n, tail = 0) => `${String(n).padStart(8, '0')}-0000-4000-8000-${String(tail).padStart(12, '0')}`;
+/** One inventory row in the shape the evidence measured: a bot account that is a member of 80 projects (~10 kB, the live rows measured 1.7 to 10.3 kB). */
+function inventoryRow(i) {
+    const account = Math.floor(i / 4);
+    return {
+        userId: uuid(account, 1), userEmail: `agent-${account}-f82fd0ea@agents.internal`, userFullName: `Agent ${account}`, kind: 'agent', isBot: true,
+        actsAs: null, owner: { id: uuid(900, 2), name: 'Operator Person', email: 'operator@example.test' }, autonomyPaused: false,
+        sessionId: uuid(i, 3), status: 'idle', lane: null,
+        projects: Array.from({ length: 80 }, (_, p) => ({ id: uuid(p, 4), key: `P${String(p).padStart(3, '0')}`, name: `Project number ${p} - long name` })),
+        connections: [{ type: 'api_key', label: 'agent key for the build host' }, { type: 'channel', label: 'claude-code wake channel' }],
+        wake: 'channel', workingOnTicket: { id: uuid(i, 5), key: `ORB-${2500 + i}`, title: 'A ticket title of ordinary length for a working session', projectKey: 'ORB' },
+        workSessions: [{ ticketId: uuid(i, 5), ticketKey: `ORB-${2500 + i}`, role: 'implementation', leaseUntil: '2026-10-16T10:15:00.000Z', resourceClaims: [] }],
+        capabilities: ['writes-tickets', 'reviews'],
+        clientInfo: { name: 'claude-code', host: 'build-host.fritz.box', channel: 'claude-code', credential: 'api_key', credentialId: uuid(i, 6), credentialActor: 'agent', channelStart: 'orboto-claude', contextReportedAt: '2026-10-16T09:51:55.631Z' },
+        scope: { projectKeys: ['OCP'], role: i === 17 ? 'integrator' : 'worker' },
+        unreadMessages: 3, wakes: { count: 4, precision: 1, wrongWakeContextTokens: 0, backlogSeen: 0 },
+        guard: { held: 0, released: 2, stalled: 0, consecutiveHolds: 0, lastOutcome: 'released', lastReason: null, lastAt: '2026-10-16T09:50:00.000Z', paused: false },
+        knowledge: { writes: 0, asks: 1, lastAt: null, localPending: false },
+        restartPending: false, restartReason: null, restartable: true, reconnects: 2, lastReconnectAt: '2026-10-16T09:40:00.000Z',
+        lastSeenAt: '2026-10-16 09:54:00.504+00', createdAt: '2026-10-16 08:01:12.719715+00',
+        origin: { host: 'build-host', machineId: '4ea7904991187bf1', repo: 'orboto-control-plane', pid: 15503 + i, startedAt: '2026-10-16T08:00:00.000Z', client: 'orboto-mcp', clientVersion: '0.224.0', harness: 'claude-code', credential: 'api_key', known: true },
+        state: 'live', activity: 'live', touchedAt: '2026-10-16 09:54:00.504+00',
+    };
+}
+const WORKSPACE = Array.from({ length: 32 }, (_, i) => inventoryRow(i));
+/** The presence read as the API answers it: the ORB-2548 filters and the page on the server (the API side is tested in apps/api). */
+function servePresence() {
+    const urls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+        const url = new URL(String(input));
+        urls.push(url.pathname + url.search);
+        const q = url.searchParams;
+        const rows = WORKSPACE.filter((r) => (!q.get('sessionId') || r.sessionId.startsWith(q.get('sessionId')))
+            && (!q.get('email') || r.userEmail === q.get('email'))
+            && (!q.get('role') || r.scope.role === q.get('role')));
+        const start = q.get('cursor') ? Number(q.get('cursor')) : 0;
+        const limit = Number(q.get('limit') ?? rows.length);
+        const page = rows.slice(start, start + limit);
+        const nextCursor = start + limit < rows.length ? String(start + limit) : null;
+        const sessions = page.map((r) => ({
+            sessionId: r.sessionId, shortId: r.sessionId.slice(0, 8), userId: r.userId, email: r.userEmail, isBot: true, role: r.scope.role,
+            projectKeys: r.scope.projectKeys, ticketKeys: [], addresses: [`${r.scope.role}@OCP`], lastSeenAt: r.lastSeenAt,
+            channel: { announced: 'claude-code', online: true }, wake: r.wake, currentTicket: { key: r.workingOnTicket.key, title: r.workingOnTicket.title },
+            status: r.status, host: 'build-host.fritz.box', origin: r.origin, state: r.state, activity: r.activity, createdAt: r.createdAt,
+        }));
+        const body = q.get('include') === 'inventory' ? { sessions, inventory: page, nextCursor } : { sessions, nextCursor };
+        return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => JSON.stringify(body) };
+    });
+    return urls;
+}
+function underBudget(tool, result) {
+    const halves = measureHalves(result);
+    const outcome = applyResponseBudget(tool, result, {});
+    return { ...halves, truncated: outcome.truncatedChars, budget: budgetFor(tool, {}) };
+}
+describe('ORB-2548 - presence reads fit the MCP response budget', () => {
+    it('reproduces the evidence: the unfiltered inventory of 32 sessions is over 230 kB, far over the 4,000 budget', () => {
+        const all = JSON.stringify({ sessions: WORKSPACE }).length;
+        expect(all).toBeGreaterThan(230_000);
+        expect(budgetFor('orboto_agent_presence', {})).toBe(DEFAULT_BUDGET_CHARS);
+    });
+    it('one session by its short id comes back whole, under budget, without an expand handle', async () => {
+        const urls = servePresence();
+        const result = await makeAgentPresenceHandler(client)({ sessionId: uuid(17, 3).slice(0, 8) });
+        const m = underBudget('orboto_agent_presence', result);
+        expect(urls[0]).toBe(`/v1/agent/who?include=inventory&sessionId=${uuid(17, 3).slice(0, 8)}&limit=4`);
+        expect(m.truncated).toBe(0);
+        expect(m.structuredChars).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        expect(m.textChars).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        const { sessions } = result.structuredContent;
+        expect(sessions).toEqual([expect.objectContaining({ sessionId: uuid(17, 3), scope: { projectKeys: ['OCP'], role: 'integrator' } })]);
+        expect(result.content[0].text).toContain(`instance ${uuid(17, 3)}`);
+    });
+    it('an account email with four sessions, and the unfiltered first page of four, stay under budget with nextCursor for the rest', async () => {
+        servePresence();
+        const byEmail = await makeAgentPresenceHandler(client)({ email: 'agent-2-f82fd0ea@agents.internal' });
+        expect(byEmail.structuredContent.sessions).toHaveLength(4);
+        expect(underBudget('orboto_agent_presence', byEmail)).toMatchObject({ truncated: 0 });
+        const first = await makeAgentPresenceHandler(client)({});
+        const m = underBudget('orboto_agent_presence', first);
+        expect(m.truncated).toBe(0);
+        expect(Math.max(m.textChars, m.structuredChars)).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        expect(first.structuredContent.nextCursor).toBe('4');
+        expect(first.content[0].text).toContain('call again with cursor "4"');
+    });
+    it('orboto_who answers the same filtered set under budget', async () => {
+        const urls = servePresence();
+        const result = await makeAgentWhoHandler(client)({ role: 'integrator' });
+        expect(urls[0]).toBe('/v1/agent/who?role=integrator&limit=4');
+        expect(result.structuredContent.sessions.map((s) => s.sessionId)).toEqual([uuid(17, 3)]);
+        expect(underBudget('orboto_who', result)).toMatchObject({ truncated: 0 });
+        const page = await makeAgentWhoHandler(client)({});
+        expect(underBudget('orboto_who', page)).toMatchObject({ truncated: 0 });
+    });
+});
+const party = (n, role) => ({ userId: uuid(n, 7), email: `agent-${n}@orboto.io`, sessionId: uuid(n, 8), role, label: `agent-${n}@orboto.io (${role}, ${uuid(n, 8).slice(0, 8)})` });
+/** An inbox message in the measured live shape: a 182-character subject, a 1 kB payload, the compact excerpt. */
+function message(i, threadId) {
+    const body = `${'Status of the rollout on the tenant hosts, with the commands that ran and their exit codes. '.repeat(11)}`;
+    return {
+        id: uuid(100 + i, 9), fromUserId: uuid(1, 7), toUserId: uuid(2, 7), fromSessionId: uuid(1, 8), toSessionId: null,
+        from: party(1, 'integrator'), to: party(2, 'worker'), kind: i % 2 ? 'complete' : 'request',
+        subject: `OCP-${800 + i}: ${'rollout of the verified release to every tenant host, the backup first and core before the tenants, '.repeat(2).slice(0, 172)}`,
+        payload: { body }, threadId, projectKey: 'OCP', createdAt: `2026-10-16 09:${String(10 + i).padStart(2, '0')}:00.504123+00`,
+        deliveredAt: null, readAt: null, dismissed: null, excerpt: `body: ${body.slice(0, 294)}`, payloadChars: body.length + 6,
+    };
+}
+function serveInbox(messages) {
+    const urls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+        const url = new URL(String(input));
+        urls.push(url.pathname + url.search);
+        const q = url.searchParams;
+        const rows = messages.filter((m) => (!q.get('threadId') || m.id === q.get('threadId') || m.threadId === q.get('threadId')) && (!q.get('kind') || m.kind === q.get('kind')));
+        const limit = Number(q.get('limit'));
+        const body = { messages: rows.slice(0, limit), sessionId: uuid(2, 8), counts: { unread: rows.length, olderThan7Days: 0 }, nextCursor: rows.length > limit ? 'next-page' : null };
+        return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => JSON.stringify(body) };
+    });
+    return urls;
+}
+describe('ORB-2548 - inbox reads fit the MCP response budget', () => {
+    const inbox = [...Array.from({ length: 12 }, (_, i) => message(i, null)), ...Array.from({ length: 4 }, (_, i) => message(20 + i, uuid(100, 9)))];
+    it('the default compact page (4) of full-size messages fits; the old default of 10 did not', async () => {
+        serveInbox(inbox);
+        const page = await makeAgentMessagesHandler(client)({});
+        const m = underBudget('orboto_messages', page);
+        expect(m.truncated).toBe(0);
+        expect(Math.max(m.textChars, m.structuredChars)).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        expect(page.structuredContent.nextCursor).toBe('next-page');
+        serveInbox(inbox);
+        const old = await makeAgentMessagesHandler(client)({ limit: 10 });
+        expect(underBudget('orboto_messages', old).truncated).toBeGreaterThan(0);
+    });
+    it('one thread and one kind are filtered on the server and come back under budget', async () => {
+        const urls = serveInbox(inbox);
+        const thread = await makeAgentMessagesHandler(client)({ threadId: uuid(100, 9) });
+        expect(urls[0]).toContain(`threadId=${uuid(100, 9)}`);
+        expect(thread.structuredContent).toMatchObject({ nextCursor: 'next-page' });
+        expect(thread.structuredContent.messages).toHaveLength(4);
+        expect(underBudget('orboto_messages', thread)).toMatchObject({ truncated: 0 });
+        const sent = await makeAgentMessagesHandler(client)({ direction: 'sent', kind: 'request', limit: 3 });
+        expect(urls[1]).toContain('direction=sent');
+        expect(urls[1]).toContain('kind=request');
+        expect(urls[1]).not.toContain('excludeRef');
+        expect(underBudget('orboto_messages', sent)).toMatchObject({ truncated: 0 });
+    });
+});

package/dist/tools/responsibilities.test.js

@@ -51,7 +51,7 @@ describe('orboto_who for', () => {
         const urls = [];
         respond(200, { sessions: [], owner: match }, urls);
         const result = await makeAgentWhoHandler(client)({ for: 'unity asset' });
-        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?for=unity+asset');
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?for=unity+asset&limit=4');
         const text = result.content[0].text;
         expect(text).toContain('Owner:\n- worker@GAMES');
         expect(text).toContain('No live session answers to worker@GAMES - send with queue: true and project GAMES');

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