@orboto/mcp 0.227.0 → 0.229.0

package/dist/index.js

@@ -70,16 +70,27 @@ async function main() {
             const { mcpProcessInstance } = await import('./tools/shared.js');
             const instanceToken = mcpProcessInstance();
             const { declareEnvProjectScope } = await import('./project-scope.js');
-            await declareEnvProjectScope(preflightClient, instanceToken);
+            const declared = await declareEnvProjectScope(preflightClient, instanceToken);
             const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
             inbox.start();
+            if (declared?.refusal)
+                void inbox.deliverNotice('session_exists', declared.refusal);
             const outdated = cliOutdatedNotice(process.env.ORBOTO_MCP_CLI_OUTDATED);
             if (outdated)
                 void inbox.deliverNotice(CLI_OUTDATED_NOTICE, outdated);
             const { readClaudeContext, channelClientInfo } = await import('./claude-context.js');
+            const { presenceRefusal } = await import('./tools/shared.js');
+            let refusalLogged = false;
             const beat = () => {
                 preflightClient.post('/v1/agent/heartbeat', { clientInfo: channelClientInfo(readClaudeContext(process.cwd()), undefined, channelStart ?? undefined) }, { instanceToken })
-                    .catch((err) => { console.error(`[orboto-mcp] channel heartbeat failed: ${err.message}`); });
+                    .then(() => { refusalLogged = false; })
+                    .catch((err) => {
+                    const refused = presenceRefusal(err);
+                    if (refused && refusalLogged)
+                        return;
+                    refusalLogged = Boolean(refused);
+                    console.error(`[orboto-mcp] channel heartbeat ${refused ? 'refused' : 'failed'}: ${refused?.message ?? err.message}`);
+                });
             };
             beat();
             const beats = setInterval(beat, 60_000);

package/dist/manifest-size.test.js

@@ -62,6 +62,9 @@ afterEach(() => { vi.restoreAllMocks(); });
  * ORB-2563 gave `orboto_agent_notify` `remind` and `urgent` inside the
  * ceiling: the docs `content` parameter description shrank to pay for it
  * (full = 171,194).
+ * ORB-2579 added the four rule proposal tools to the full tier after
+ * tightening repeated parameter descriptions (doc ids, bulk selectors,
+ * work-session leases, primer facts) by 3.0k (full = 169,607).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/project-scope.js

@@ -43,7 +43,21 @@ export async function declareEnvProjectScope(client, instanceToken, raw = proces
     const current = await client.get('/v1/agent/session', { instanceToken }).catch(() => null);
     if (current && scopeDeclared(current.scope))
         return current;
-    const row = await client.post('/v1/agent/heartbeat', { scope, scopeDefault: true }, { instanceToken }).catch(() => null);
+    const declaration = { scope, scopeDefault: true, start: true };
+    const row = await client.post('/v1/agent/heartbeat', declaration, { instanceToken })
+        .catch(async (err) => {
+        const { exitedPredecessor, presenceRefusal } = await import('./tools/shared.js');
+        const { machineId, shortHost } = await import('./session-origin.js');
+        const refused = presenceRefusal(err);
+        const dead = exitedPredecessor(refused, { machine: machineId(), host: shortHost() });
+        if (dead) {
+            const again = await client.post('/v1/agent/heartbeat', { ...declaration, previous: 'end' }, { instanceToken }).catch(() => null);
+            if (again)
+                console.error(`[orboto-mcp] ${dead.line}`);
+            return again;
+        }
+        return refused ? { refusal: refused.message } : null;
+    });
     if (row && typeof row.sessionId === 'string')
         rememberDeclaredScope(instanceToken, row.scope ?? scope);
     return row;

package/dist/project-scope.test.js

@@ -18,7 +18,7 @@ function fakeClient(row) {
         },
     };
 }
-beforeEach(() => { _forgetDeclaredScopes(); });
+beforeEach(() => { _forgetDeclaredScopes(); vi.stubEnv(PROJECT_KEY_ENV, ''); vi.stubEnv(SESSION_ROLE_ENV, ''); });
 afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
 describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
     it('names the same variable the CLI writes into the entry and hands to the session', () => {
@@ -41,7 +41,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         await declareEnvProjectScope(client, 'agent-abc', 'ACME');
         expect(client.calls).toEqual([
             { method: 'GET', path: '/v1/agent/session', instanceToken: 'agent-abc' },
-            { method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }, instanceToken: 'agent-abc' },
+            { method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }, instanceToken: 'agent-abc' },
         ]);
         expect(rememberedScope('agent-abc')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
     });
@@ -58,7 +58,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         expect(await declareEnvProjectScope(none, 'agent-none', '')).toBeNull();
         expect(none.calls).toEqual([]);
     });
-    it('orboto_session_start without a scope declares the environment project on a row that has none', async () => {
+    it('orboto_session_start without a scope sends the environment project as fallbackScope and declares it itself on an instance that ignores it', async () => {
         vi.stubEnv(PROJECT_KEY_ENV, 'acme');
         const beats = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
@@ -79,7 +79,7 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         });
         const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'k' });
         const res = await makeSessionStartHandler(client)({}, { sessionId: 'scope1' });
-        expect(beats).toEqual([{}, { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }]);
+        expect(beats).toEqual([{ start: true, fallbackScope: { role: 'worker', projectKeys: ['ACME'] } }, { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }]);
         expect(res.content[0].text).toContain('projects ACME');
         expect(rememberedScope('mcp-scope1')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
     });
@@ -99,10 +99,10 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
         expect(envProjectScope(undefined, 'lead')).toBeNull();
         const client = fakeClient({ sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null });
         await declareEnvProjectScope(client, 'agent-control', undefined, 'coordinator');
-        expect(client.calls[1]).toEqual({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'coordinator' }, scopeDefault: true }, instanceToken: 'agent-control' });
+        expect(client.calls[1]).toEqual({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'coordinator' }, scopeDefault: true, start: true }, instanceToken: 'agent-control' });
         expect(rememberedScope('agent-control')).toEqual({ role: 'coordinator' });
     });
-    it('orboto_session_start without a scope declares the control session the environment names', async () => {
+    it('orboto_session_start without a scope sends the control session the environment names as fallbackScope in its one start beat', async () => {
         vi.stubEnv(SESSION_ROLE_ENV, 'coordinator');
         vi.stubEnv(PROJECT_KEY_ENV, 'ACME');
         const beats = [];
@@ -112,7 +112,7 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
             if (u.pathname === '/v1/agent/heartbeat') {
                 const sent = init?.body ? JSON.parse(init.body) : {};
                 beats.push(sent);
-                body = { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: sent.scope ?? null };
+                body = { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: sent.scope ?? sent.fallbackScope ?? null };
             }
             else if (u.pathname === '/v1/agent/session') {
                 body = { sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null };
@@ -124,7 +124,7 @@ describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
         });
         const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'k' });
         await makeSessionStartHandler(client)({}, { sessionId: 'control1' });
-        expect(beats).toEqual([{}, { scope: { role: 'coordinator' }, scopeDefault: true }]);
+        expect(beats).toEqual([{ start: true, fallbackScope: { role: 'coordinator' } }]);
         expect(rememberedScope('mcp-control1')).toEqual({ role: 'coordinator' });
     });
 });
@@ -145,6 +145,6 @@ describe('ORB-2593 - a picker-pending orboto claude start', () => {
         writeFileSync(join(dir, 'state.json'), JSON.stringify({ pid: 4000 }));
         const resolved = fakeClient({ sessionId: 'x', scope: null });
         await declareEnvProjectScope(resolved, 'agent-abc', 'ACME', undefined, supervisorScopePending(env));
-        expect(resolved.calls.filter((c) => c.method === 'POST')).toEqual([{ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true }, instanceToken: 'agent-abc' }]);
+        expect(resolved.calls.filter((c) => c.method === 'POST')).toEqual([{ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] }, scopeDefault: true, start: true }, instanceToken: 'agent-abc' }]);
     });
 });

package/dist/response-budget.js

@@ -239,7 +239,7 @@ export const TruncationBlockSchema = z.object({
  */
 export const TruncationBlockAdvertisedSchema = z.object({ handle: z.string() })
     .passthrough()
-    .describe('Response cut; pass `handle` to orboto_response_expand.');
+    .describe('Cut: pass handle to orboto_response_expand.');
 function stringMarker(omitted, handle, path) {
     return `... [truncated ${omitted} chars - full value: orboto_response_expand handle="${handle}" path="${path}"]`;
 }

package/dist/server.js

@@ -24,6 +24,7 @@ import { helpToolConfig, makeHelpHandler } from './tools/help.js';
 import { apiSearchToolConfig, makeApiSearchHandler } from './tools/api-search.js';
 import { apiCallToolConfig, makeApiCallHandler } from './tools/api-call.js';
 import { listAgentInstructionsToolConfig, makeListAgentInstructionsHandler, createAgentInstructionToolConfig, makeCreateAgentInstructionHandler, updateAgentInstructionToolConfig, makeUpdateAgentInstructionHandler, resetAgentInstructionToolConfig, makeResetAgentInstructionHandler, deleteAgentInstructionToolConfig, makeDeleteAgentInstructionHandler, } from './tools/agent-instructions.js';
+import { ruleProposeToolConfig, makeRuleProposeHandler, ruleProposalsToolConfig, makeRuleProposalsHandler, ruleProposalAcceptToolConfig, makeRuleProposalAcceptHandler, ruleProposalRejectToolConfig, makeRuleProposalRejectHandler, } from './tools/rule-proposals.js';
 import { agentHeartbeatToolConfig, makeAgentHeartbeatHandler, agentPresenceToolConfig, makeAgentPresenceHandler, agentNotifyToolConfig, makeAgentNotifyHandler, } from './tools/agent-coordination.js';
 import { agentBroadcastToolConfig, makeAgentBroadcastHandler, } from './tools/agent-coordination.js';
 import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './tools/agent-message-work.js';
@@ -200,6 +201,10 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_update_agent_instruction', updateAgentInstructionToolConfig, makeUpdateAgentInstructionHandler(client));
     reg('orboto_reset_agent_instruction', resetAgentInstructionToolConfig, makeResetAgentInstructionHandler(client));
     reg('orboto_delete_agent_instruction', deleteAgentInstructionToolConfig, makeDeleteAgentInstructionHandler(client));
+    reg('orboto_rule_propose', ruleProposeToolConfig, makeRuleProposeHandler(client));
+    reg('orboto_rule_proposals', ruleProposalsToolConfig, makeRuleProposalsHandler(client));
+    reg('orboto_rule_proposal_accept', ruleProposalAcceptToolConfig, makeRuleProposalAcceptHandler(client));
+    reg('orboto_rule_proposal_reject', ruleProposalRejectToolConfig, makeRuleProposalRejectHandler(client));
     reg('orboto_agent_heartbeat', agentHeartbeatToolConfig, makeAgentHeartbeatHandler(client));
     reg('orboto_agent_presence', agentPresenceToolConfig, makeAgentPresenceHandler(client));
     reg('orboto_who', agentWhoToolConfig, makeAgentWhoHandler(client));

package/dist/session-origin.js

@@ -6,12 +6,12 @@
  */
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { VERSION } from './version.js';
 const KEYS = [
-    ['host', 'host'], ['machine', 'machineId'], ['repo', 'repo'], ['pid', 'pid'], ['start', 'startedAt'], ['client', 'client'], ['version', 'clientVersion'], ['harness', 'harness'], ['model', 'model'],
+    ['host', 'host'], ['machine', 'machineId'], ['repo', 'repo'], ['pid', 'pid'], ['start', 'startedAt'], ['client', 'client'], ['version', 'clientVersion'], ['harness', 'harness'], ['model', 'model'], ['checkout', 'checkout'],
 ];
 const WRAPPED_HARNESSES = { claude: 'claude-code', 'claude-code': 'claude-code', codex: 'codex', gemini: 'gemini', kimi: 'kimi', agy: 'agy', antigravity: 'agy' };
 /** ORB-2571 - the harness that started a stdio proxy: the one `orboto <harness>` named, else the markers a harness sets. */
@@ -55,6 +55,26 @@ export function repoBasename(cwd = process.cwd()) {
     }
     return basename(cwd) || null;
 }
+/** ORB-2553 - the hashed working tree the directory sits in (a linked worktree is its own), the same value the CLI sends; never a path. */
+export function checkoutHash(cwd = process.cwd()) {
+    let root = cwd;
+    for (let dir = cwd, i = 0; i < 40; i += 1) {
+        if (existsSync(join(dir, '.git'))) {
+            root = dir;
+            break;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    let physical = root;
+    try {
+        physical = realpathSync(root);
+    }
+    catch { /* an unreadable path hashes as given */ }
+    return createHash('sha256').update(physical).digest('hex').slice(0, 16);
+}
 let machine;
 /** A hashed stable machine id (the platform UUID on macOS, /etc/machine-id elsewhere); null when none is readable. */
 export function machineId(read = readMachineId) {
@@ -87,7 +107,7 @@ export function stdioOrigin(env = process.env) {
         return params.toString();
     }
     return formatOrigin({
-        host: shortHost(), machineId: machineId(), repo: repoBasename(), pid: process.ppid || null,
+        host: shortHost(), machineId: machineId(), repo: repoBasename(), checkout: checkoutHash(), pid: process.ppid || null,
         client: 'orboto-mcp', clientVersion: VERSION,
         harness: stdioHarness(env),
         model: /^[\x21-\x7e]{1,80}$/.test((env.ORBOTO_MODEL ?? '').trim()) ? env.ORBOTO_MODEL.trim() : null,

package/dist/tools/agent-coordination.js

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { AGENT_WAKE_LABELS, AgentInventoryKindSchema, AgentSessionWakeSchema, } from './agent-presence-schema.js';
 import { AgentPresenceRowSchema } from './agent-presence-row.js';
 import { OrbotoApiError } from '../orboto-client.js';
-import { mcpInstanceToken } from './shared.js';
+import { mcpInstanceToken, presenceRefusal } from './shared.js';
 import { AgentSessionRoleSchema, AgentSessionScopeSchema } from './agent-session-scope.js';
 export const agentHeartbeatToolConfig = {
     title: 'Agent heartbeat (Multi-Agent Coordination)',
@@ -36,7 +36,16 @@ export const agentHeartbeatToolConfig = {
 };
 export function makeAgentHeartbeatHandler(client) {
     return async (args, extra) => {
-        const res = await client.post('/v1/agent/heartbeat', args, { instanceToken: mcpInstanceToken(undefined, extra) });
+        let res;
+        try {
+            res = await client.post('/v1/agent/heartbeat', args, { instanceToken: mcpInstanceToken(undefined, extra) });
+        }
+        catch (err) {
+            const refused = presenceRefusal(err);
+            if (!refused)
+                throw err;
+            return { content: [{ type: 'text', text: `heartbeat refused (ORB-2553) - ${refused.message}` }], isError: true };
+        }
         const scope = res.scope ? ` scope=${JSON.stringify(res.scope)}` : '';
         const notes = (res.notes ?? []).map((n) => `\n${n}`).join('');
         return {
@@ -176,7 +185,7 @@ export function noRecipientText(err) {
         return null;
     const p = body.errorParams ?? {};
     const live = (p.liveSessions ?? []).map((s) => `${s.addresses[0] ?? s.email} (${s.email}, ${s.shortId})`);
-    const ways = 'a role address in `to` (integrator@KEY), `toSessionRef` with an instance short id, or `queue: true` with `project` to keep it until a session declares the project';
+    const ways = 'a role address in `to` (integrator@KEY), `toSessionRef` with an instance short id, or `queue: true` with `project` (a role address needs no project) to keep it until a session declares the project or the role';
     if (p.reason === 'ambiguous_account') {
         return `not sent: ${p.address ?? 'that account'} has ${live.length} live sessions you may address and a request needs one of them. Sessions: ${live.join('; ')}. Send again with \`toSessionRef\` set to the instance short id of one, or address a role (${ways}).`;
     }
@@ -218,7 +227,7 @@ export function reminderTooSoonText(err) {
 }
 export const agentNotifyToolConfig = {
     title: 'Notify an agent or user',
-    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). outcome: one sentence, 10 to 1000 characters; body: the plain text of the message (any length, lands in payload.body; payload may carry other JSON); threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; alone (no to, no targetEmail) a session id or short id addresses that session; project scopes an account message to sessions declared on it. A request to an account email without project or toSessionRef goes to its one live session, with several it is refused listing them (pick one with toSessionRef). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session. An identical send (same recipient, project, kind, subject, payload; no threadId, no attachments) within the dedupe window (default 24 h) is not delivered again: the text says so and names the existing message. remind: true is a deliberate reminder of it (notifies again, at most one per 15 min, faster is refused with retryAfter); urgent: true is never suppressed and counts as a reminder. Loops and retries never set remind or urgent.',
+    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). outcome: one sentence, 10 to 1000 characters; body: the plain text of the message (any length, lands in payload.body; payload may carry other JSON); threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; alone (no to, no targetEmail) a session id or short id addresses that session; project scopes an account message to sessions declared on it. A request to an account email without project or toSessionRef goes to its one live session, with several it is refused listing them (pick one with toSessionRef). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project; queued to a role address (worker@KEY) it waits for the first session that declares that role, and a queued request to an account address on the project of the owner address goes to the owner role. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session. An identical send (same recipient, project, kind, subject, payload; no threadId, no attachments) within the dedupe window (default 24 h) is not delivered again: the text says so and names the existing message. remind: true is a deliberate reminder of it (notifies again, at most one per 15 min, faster is refused with retryAfter); urgent: true is never suppressed and counts as a reminder. Loops and retries never set remind or urgent.',
     inputSchema: z.object({
         targetEmail: z.string().email().optional(),
         to: z.string().min(3).max(200).optional(),

package/dist/tools/agent-instructions.js

@@ -6,6 +6,7 @@
  */
 import { z } from 'zod';
 import { sizeBlockResult } from './shared.js';
+const AGENTS_PROPOSE = ' Agents propose shared rules with orboto_rule_propose (403 errors.agent_rules.write_needs_person).';
 const RULE_WRITING_CONTRACT = ' Rule: title = one imperative sentence; body <= 400 chars, Rule / Why / How, no long examples, nothing another block says.';
 function excerptOf(body) {
     const firstLine = body.split('\n', 1)[0] ?? '';
@@ -74,7 +75,7 @@ export function makeListAgentInstructionsHandler(client) {
 export const createAgentInstructionToolConfig = {
     title: 'Add a custom coding-agent rule block',
     description: 'Create a custom rule block at a scope (workspace, customer, project or personal). Workspace reaches every agent (admin:ai:write), customer every project of one customer (customer:write), project one project (project:edit), personal only you. For scope=customer pass customerId; for scope=project pass projectId.'
-        + RULE_WRITING_CONTRACT,
+        + AGENTS_PROPOSE + RULE_WRITING_CONTRACT,
     inputSchema: z.object({
         title: z.string().min(1).max(120),
         body: z.string().min(1).max(8000).describe('The rule text the agent should follow.'),
@@ -109,7 +110,7 @@ export function makeCreateAgentInstructionHandler(client) {
 export const updateAgentInstructionToolConfig = {
     title: 'Edit / toggle / reorder a coding-agent rule block',
     description: 'Patch a rule block: title, body, enabled (toggle a rule on/off), or sortOrder. Works on default AND custom blocks (defaults keep their builtinKey and can be reset later). Needs admin:ai:write.'
-        + RULE_WRITING_CONTRACT,
+        + AGENTS_PROPOSE + RULE_WRITING_CONTRACT,
     inputSchema: z.object({
         id: z.string().uuid(),
         title: z.string().min(1).max(120).optional(),
@@ -141,7 +142,7 @@ export function makeUpdateAgentInstructionHandler(client) {
 }
 export const resetAgentInstructionToolConfig = {
     title: 'Reset a default rule block to its shipped text',
-    description: 'Restore a seeded DEFAULT rule block (one with a builtinKey) to the text orboto ships. No-op for custom blocks. Needs admin:ai:write.',
+    description: 'Restore a seeded DEFAULT rule block (one with a builtinKey) to the text orboto ships. No-op for custom blocks. Needs admin:ai:write.' + AGENTS_PROPOSE,
     inputSchema: z.object({ id: z.string().uuid() }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
@@ -153,7 +154,7 @@ export function makeResetAgentInstructionHandler(client) {
 }
 export const deleteAgentInstructionToolConfig = {
     title: 'Delete a custom coding-agent rule block',
-    description: 'Delete a CUSTOM rule block. Default (builtin) blocks cannot be deleted - disable them via update instead. Needs admin:ai:write.',
+    description: 'Delete a CUSTOM rule block. Default (builtin) blocks cannot be deleted - disable them via update instead. Needs admin:ai:write.' + AGENTS_PROPOSE,
     inputSchema: z.object({ id: z.string().uuid() }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };

package/dist/tools/agent-who.js

@@ -3,15 +3,23 @@ import { z } from 'zod';
 import { ownerLine } from './responsibilities.js';
 import { nextPageLine, originText, PresenceFilterShape, presenceQuery, readPresence, unknownProjectText } from './agent-coordination.js';
 import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
+export function refusalLines(refusals) {
+    if (!refusals?.length)
+        return [];
+    return ['Refused heartbeats in the last 24 hours (no role address, not listed):', ...refusals.map((r) => {
+            const where = [r.lastHost, r.lastRepo].filter(Boolean).join('/') || 'unknown origin';
+            return `- ${r.email}: ${r.count} (no scope ${r.scopeRequired}, second start ${r.sessionExists}), last ${r.lastAt} from ${where}${r.lastHarness ? ` (${r.lastHarness})` : ''}`;
+        })];
+}
 export const agentWhoToolConfig = {
     title: 'Who receives agent mail',
-    description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. GET /v1/agent/who; each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it); email, sessionId (id or 8+ character prefix), kind and wake narrow on the server; 4 rows a page, nextCursor continues (cursor); a project that is unknown or not visible to you answers so in one line.',
+    description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. GET /v1/agent/who; each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. A session without a declared scope is not listed; the refused heartbeats of the last 24 hours follow per account (refusals). `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it); email, sessionId (id or 8+ character prefix), kind and wake narrow on the server; 4 rows a page, nextCursor continues (cursor); a project that is unknown or not visible to you answers so in one line.',
     inputSchema: z.object({
         project: z.string().min(1).max(64).optional(),
         for: z.string().min(2).max(2000).optional(),
         ...PresenceFilterShape,
     }).shape,
-    outputSchema: z.object({ sessions: z.array(z.unknown()), owner: z.unknown().optional(), nextCursor: z.string().nullable() }).shape,
+    outputSchema: z.object({ sessions: z.array(z.unknown()), owner: z.unknown().optional(), nextCursor: z.string().nullable(), refusals: z.array(z.unknown()).optional() }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
 /** One directory row as a line: address, account, session, projects, channel, ticket. */
@@ -35,9 +43,10 @@ export function makeAgentWhoHandler(client) {
         const lines = res.sessions.length
             ? [...ownerLines, `${res.sessions.length} live session(s)${res.nextCursor ? ' on this page' : ''}:`, ...res.sessions.map(whoLine), ...nextPageLine(res.nextCursor)]
             : [...ownerLines, res.owner ? `No live session answers to ${res.owner.entry.ownerAddress} - send with queue: true and project ${res.owner.entry.ownerAddress.split('@')[1]} to keep it until one declares it.` : 'No live session matches - a request sent now answers no_recipient unless it is queued.'];
+        lines.push(...refusalLines(res.refusals));
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { sessions: res.sessions, ...(args.for ? { owner: (res.owner ?? null) } : {}), nextCursor: res.nextCursor ?? null },
+            structuredContent: { sessions: res.sessions, ...(args.for ? { owner: (res.owner ?? null) } : {}), nextCursor: res.nextCursor ?? null, ...(res.refusals?.length ? { refusals: res.refusals } : {}) },
         };
     };
 }

package/dist/tools/bulk-writes.js

@@ -15,12 +15,12 @@ const CATEGORY_TO_LEGACY = {
     wont_fix: 'WONT_FIX',
 };
 const TICKET_KEY_ARRAY = z.array(z.string().min(3)).min(1).max(200).optional()
-    .describe('Ticket keys, e.g. ["ACME-1"]; at most 200. Give ticketKeys or query.');
+    .describe('Ticket keys, at most 200; or give query.');
 /** ORB-2054 - the target set can be an OQL query instead of a key list. */
 const QUERY_SOURCE = z.string().min(1).max(8000).optional()
-    .describe('OQL selecting the tickets instead of ticketKeys (orboto_query grammar, your ACL); at most 200 matches.');
+    .describe('OQL instead of ticketKeys (your ACL), at most 200 matches.');
 const QUERY_PROJECT = z.string().optional()
-    .describe('Project key that scopes `query` (prepended as project = KEY).');
+    .describe('Project key scoping `query`.');
 /** Matches per call the MCP loop will process; above that the server-side bulk route is the right tool. */
 export const BULK_QUERY_MAX = 200;
 /** Resolve `query` to ticket keys through POST /query, paging until the cap. */

package/dist/tools/checklist-writes.js

@@ -74,7 +74,7 @@ function makeToggleHandler(client, completed) {
 const toggleInputSchema = z.object({
     ticketKey: z.string().min(3),
     item: z.union([
-        z.number().int().min(1).describe('1-based index, global across all checklists on this ticket'),
+        z.number().int().min(1).describe('1-based index across all checklists'),
         z.string().describe('Item UUID - for callers that already have it'),
     ]),
 }).shape;
@@ -169,7 +169,7 @@ export const updateCheckToolConfig = {
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         item: z.union([
-            z.number().int().min(1).describe('1-based index, global across all checklists on this ticket'),
+            z.number().int().min(1).describe('1-based index across all checklists'),
             z.string().describe('Item UUID - for callers that already have it'),
         ]),
         content: z.string().min(1).max(2000).optional().describe('New item text.'),

package/dist/tools/claim.js

@@ -16,7 +16,7 @@ const CATEGORY_TO_LEGACY = {
 };
 export const claimToolConfig = {
     title: 'Claim a ticket (assign self + in_progress + timer)',
-    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.',
+    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. The server attributes the timer to the session of this connection only (ORB-2550): a token that is not its own is refused 403, a session another harness process owns 409.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         override: z.boolean().optional().describe("Spec override; reason required."),
@@ -24,7 +24,7 @@ export const claimToolConfig = {
         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.'),
+        agentSessionToken: z.string().optional().describe('Instance token for bot timers; must be this connection\'s own.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };

package/dist/tools/doc-attachments.js

@@ -39,11 +39,11 @@ export const uploadDocAttachmentToolConfig = {
     title: 'Upload an attachment to a doc page',
     description: 'Upload a file as a doc attachment: returns its Markdown image (or link) line + a stable download URL. Bytes come in as base64 (`contentBase64`) so this works without local FS access on the agent side. Set `embed=true` to also PATCH the doc body to append the Markdown line - useful for dropping a screenshot into a page in one call. MIME / extension policy is enforced server-side: blocked types (HTML, SVG, executables) surface a 415.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         filename: z.string().min(1).describe('Display filename, e.g. "architecture-diagram.png".'),
         contentBase64: z.string().min(1).describe('File content, base64-encoded.'),
         altText: z.string().optional().describe('Alt-text for the Markdown image line. Defaults to filename.'),
-        embed: z.boolean().optional().describe('If true, PATCHes the doc body to append the Markdown line. Idempotent up to duplicate detection - re-running appends another copy.'),
+        embed: z.boolean().optional().describe('Append the Markdown line to the doc body; a re-run appends another copy.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -100,7 +100,7 @@ export const listDocAttachmentsToolConfig = {
     title: 'List attachments on a doc page',
     description: 'Return the doc\'s attachments newest-first, with stable download URLs the agent can hand to the user. Empty list = no attachments.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -139,7 +139,7 @@ export const deleteDocAttachmentToolConfig = {
     title: 'Delete an attachment from a doc page',
     description: 'DESTRUCTIVE - drops the file row + deletes the underlying S3 object. Does NOT rewrite the doc body, so embedded Markdown lines pointing at the deleted URL will surface as broken images / links. Walk those by hand if needed.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         attachmentId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },

package/dist/tools/doc-comments.js

@@ -7,7 +7,7 @@ export const listDocCommentsToolConfig = {
     title: 'List comments on a doc page',
     description: 'Return comments on a doc page, oldest-first so the reply tree reads top-to-bottom. Each row carries the author name + content + resolved state. Cursor-paged - pass `cursor` from the previous call\'s nextCursor to walk older pages.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         limit: z.number().int().min(1).max(100).optional(),
         cursor: z.string().optional(),
     }).shape,
@@ -84,7 +84,7 @@ export const postDocCommentToolConfig = {
     title: 'Post a comment on a doc page (or reply to one)',
     description: 'Add a comment to a doc page. Pass `parentCommentId` to reply (the API flattens reply chains past one level so a reply-of-reply lands as a sibling of the original reply). Optional `anchor` (`{text, before, after}`) attaches the comment to a specific highlight in the body - the frontend uses the surrounding context to re-locate the anchor even after the doc has been edited. Mention a person with the markup `@[Full Name](user:<uuid>)` - the UUIDs come from `orboto_list_users`. The response reports `mentions` (tokens that resolved to a user, who is then notified) and `unresolvedMentions` (tokens that named nobody); a mention is never silently dropped.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         content: z.string().min(1).max(4000),
         parentCommentId: z.string().uuid().optional().describe('Reply to an existing comment.'),
         anchor: z.object({
@@ -136,7 +136,7 @@ export const resolveDocCommentToolConfig = {
     title: 'Mark a doc comment thread as resolved (or reopen it)',
     description: 'Toggle a comment thread\'s resolved state. Pass `resolved=true` to fold the conversation, `resolved=false` to reopen. Always acts on the thread ROOT - resolving from a reply folds the whole conversation, same as the web UI.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         commentId: z.string().uuid(),
         resolved: z.boolean(),
     }).shape,
@@ -163,7 +163,7 @@ export const updateDocCommentToolConfig = {
     title: 'Edit your own doc comment',
     description: 'Edit a doc comment\'s body. Author OR super-admin can edit; everyone else gets a 403. Doc-comments do not carry a revision history today (unlike ticket comments), so the prior content is overwritten in place. A no-op call (same content as before) returns the unchanged row.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         commentId: z.string().uuid(),
         content: z.string().min(1).max(4000),
     }).shape,
@@ -187,7 +187,7 @@ export const deleteDocCommentToolConfig = {
     title: 'Delete a doc comment',
     description: 'DESTRUCTIVE - drops the comment + (via FK cascade) every reply under it. Only the author can delete their own comments; super-admins can delete anyone\'s. Returns success silently; 403 surfaces as an OrbotoApiError.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         commentId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },

package/dist/tools/doc-export.js

@@ -7,7 +7,7 @@ export const exportDocMdToolConfig = {
     title: 'Export a doc page as Markdown',
     description: 'Return the doc body as plain Markdown (text/markdown). Differs from orboto_get_doc.content in that the server-side export endpoint emits the canonical saved body - agents pulling docs to feed into another tool should prefer this over get_doc, which wraps the body in get-doc envelope text + backlinks.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -27,9 +27,9 @@ export function makeExportDocMdHandler(client) {
 }
 export const exportDocPdfToolConfig = {
     title: 'Export a doc page as PDF',
-    description: 'Render the doc page to PDF (Puppeteer-backed PdfService) and return the bytes as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
+    description: 'Render the doc page to PDF and return it as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };

package/dist/tools/doc-revisions.js

@@ -7,7 +7,7 @@ export const listDocRevisionsToolConfig = {
     title: 'List the revision history of a doc page',
     description: 'Return saved revisions for a doc page, newest-first. Each row carries the revision id, title at snapshot time, editor user id, and editedAt timestamp; the body content is NOT in this list (use orboto_get_doc_revision to fetch one). Cursor-paged - pass `cursor` to walk older pages.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         limit: z.number().int().min(1).max(100).optional().describe('Page size. Defaults to API default (25).'),
         cursor: z.string().optional().describe('Opaque cursor from a previous call\'s nextCursor.'),
     }).shape,
@@ -56,7 +56,7 @@ export const getDocRevisionToolConfig = {
     title: 'Get a single doc revision',
     description: 'Return the full content + title of one saved revision. Use this to diff against the current doc before deciding whether to restore.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         revisionId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
@@ -85,7 +85,7 @@ export const restoreDocRevisionToolConfig = {
     title: 'Restore a doc page to a saved revision',
     description: 'Roll back the doc to the saved revision. The API snapshots the CURRENT body to a fresh revision row first, so the restore itself is also undoable. Returns the post-restore doc state.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         revisionId: z.string().uuid(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },

package/dist/tools/docs.js

@@ -152,7 +152,7 @@ export const updateDocSpaceToolConfig = {
         description: z.string().nullish(),
         icon: z.string().nullish(),
         isPublic: z.boolean().optional().describe('DEPRECATED - use guestsVisible.'),
-        visibility: z.enum(['workspace', 'project_members', 'restricted']).optional().describe('Space-level read gate: workspace = every internal member, project_members = project members whose role grants doc:view (project spaces only), restricted = standalone allowlist. Requires manage rights.'),
+        visibility: z.enum(['workspace', 'project_members', 'restricted']).optional().describe('Read gate: workspace = every internal member, project_members = members with doc:view (project spaces), restricted = allowlist. Needs manage rights.'),
         guestsVisible: z.boolean().optional().describe('Explicit guest (external user) opt-in. Requires manage rights.'),
         memberIds: z.array(z.string().uuid()).optional().describe('Replaces the restricted-space allowlist. Requires manage rights.'),
         slug: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/).optional(),
@@ -276,7 +276,7 @@ export const createDocToolConfig = {
     inputSchema: z.object({
         spaceId: z.string().min(1).describe('Target doc space - key (e.g. ORB-S1), name, or UUID. Discover via orboto_list_doc_spaces.'),
         title: z.string().min(1).max(255),
-        content: z.string().optional().describe('Markdown body (CommonMark + GFM). Empty or omitted: a blank page. Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown = neutral, label <= 24 chars).'),
+        content: z.string().optional().describe('Markdown (GFM); omitted: a blank page. Pills: `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown = neutral, label <= 24 chars).'),
         parentDocId: z.string().uuid().nullable().optional().describe('Nest under another doc.'),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional().describe('Defaults to "workspace".'),
         icon: z.string().nullish().describe('Single emoji shown in the tree.'),
@@ -313,9 +313,9 @@ export const updateDocToolConfig = {
     title: 'Update a doc page',
     description: 'Patch a doc; content is appended unless replace. ORB-2468: title, visibility, parent and icon are set as given; content goes in as a new section (identical content twice is a no-op); replace: true replaces the whole page and the answer names the revision holding the previous body plus its restore command. Every body or title change snapshots a revision; orboto_restore_doc_revision rolls back. For one passage or section use orboto_edit_doc.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         title: z.string().min(1).max(255).optional(),
-        content: z.string().optional().describe('Markdown to append (with replace: the whole body). Images are inline elements; status pills use `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown reads as neutral, label <= 24 chars).'),
+        content: z.string().optional().describe('Markdown to append (with replace: the whole body). Pills: `:badge[LABEL]{tone=success}` (neutral/info/success/warning/danger/accent, unknown = neutral, label <= 24 chars).'),
         replace: z.boolean().optional(),
         parentDocId: z.string().uuid().nullable().optional(),
         visibility: z.enum(['public', 'workspace', 'members', 'specific']).optional(),
@@ -368,7 +368,7 @@ export const deleteDocToolConfig = {
     title: 'Delete a doc page',
     description: 'DESTRUCTIVE - removes the page from the tree. Revisions are NOT auto-cascaded; the API keeps them so an admin could in principle resurrect from history, but the page itself is gone from listings. System-generated primer docs refuse deletion (the regenerator re-creates them). Returns success silently; 404 is also silent (idempotent).',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
@@ -386,9 +386,9 @@ export const moveDocToolConfig = {
     title: 'Move a doc page (reparent / reorder / cross-space)',
     description: 'Reparent a doc, change its sort order, or move it into a different space. All three target fields are optional but at least one must be supplied. Distinct from orboto_update_doc\'s parentDocId because the API endpoint emits a different WS event for the tree-rebuild path connected clients care about.',
     inputSchema: z.object({
-        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        docId: z.string().min(1).describe('Doc UUID or key (ORB-D12, DOC-5).'),
         parentDocId: z.string().uuid().nullable().optional().describe('null = top-level; UUID = nest under that doc.'),
-        spaceId: z.string().uuid().optional().describe('Move into a different space. Caller must be member of both; the parent must live in the target space, and without parentDocId the doc lands at the top level.'),
+        spaceId: z.string().uuid().optional().describe('Target space (member of both); the parent must be in it, else the doc lands at the top level.'),
         sortOrder: z.number().int().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },