@orboto/mcp 0.222.2 → 0.223.0

package/dist/agent-context.js

@@ -0,0 +1,49 @@
+/** ORB-2576 - the agent context of a stdio MCP server, read exactly as the CLI reads it (cli/internal/cmd/session_context.go). */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The session id Claude Code hands its stdio MCP servers; an HTTP server never sees it. */
+export const CLAUDE_SESSION_ENV = 'CLAUDE_CODE_SESSION_ID';
+/** The Claude Code hook events the CLI registers (claude_hook_settings.go OrbotoHookEvents). */
+export const ORBOTO_HOOK_EVENTS = ['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'Stop', 'StopFailure', 'SessionStart', 'SubagentStart', 'SubagentStop', 'SessionEnd', 'Notification'];
+/** The project settings file the hooks are registered in. */
+export const PROJECT_CLAUDE_SETTINGS = '.claude/settings.local.json';
+/** The turn-state file name the CLI hook writes for a session. */
+export function turnStateName(sessionId) {
+    return `${sessionId.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80) || 'session'}.json`;
+}
+/** The orboto hook events a checkout's settings lack; null when the file cannot be read. */
+export function missingTurnHooks(dir) {
+    let hooks = {};
+    try {
+        hooks = JSON.parse(readFileSync(join(dir, PROJECT_CLAUDE_SETTINGS), 'utf8')).hooks ?? {};
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            return null;
+    }
+    const covered = (groups) => Array.isArray(groups) && groups.some((g) => Array.isArray(g?.hooks)
+        && (g.hooks).some((h) => String(h?.command ?? '').includes('claude-hook')));
+    return ORBOTO_HOOK_EVENTS.filter((event) => !covered(hooks[event]));
+}
+/** The context key, or '' when no complete hook set confirms the current generation or a subagent shares the session. */
+export function agentContextKey(env = process.env, home = homedir()) {
+    const id = (env[CLAUDE_SESSION_ENV] ?? '').trim();
+    if (!id)
+        return '';
+    let state;
+    try {
+        state = JSON.parse(readFileSync(join(home, '.orboto', 'claude-turn', turnStateName(id)), 'utf8'));
+    }
+    catch {
+        return '';
+    }
+    if (!state.state || typeof state.contextStartedAt !== 'string' || !state.contextStartedAt)
+        return '';
+    if (Array.isArray(state.activeSubagents) && state.activeSubagents.length > 0)
+        return '';
+    const missing = typeof state.cwd === 'string' ? missingTurnHooks(state.cwd) : null;
+    if (!missing || missing.length > 0)
+        return '';
+    return `claude-code ${id} ${state.contextStartedAt}`;
+}

package/dist/agent-context.test.js

@@ -0,0 +1,45 @@
+/** ORB-2576 - a stdio server reads the agent context the CLI hook recorded; anything else is an unknown context. */
+import { describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ORBOTO_HOOK_EVENTS, agentContextKey, missingTurnHooks, turnStateName } from './agent-context.js';
+function hooks(dir, events = ORBOTO_HOOK_EVENTS) {
+    mkdirSync(join(dir, '.claude'), { recursive: true });
+    writeFileSync(join(dir, '.claude', 'settings.local.json'), JSON.stringify({ hooks: Object.fromEntries(events.map((e) => [e, [{ hooks: [{ type: 'command', command: 'orboto claude-hook' }] }]])) }));
+}
+function home(session, contextStartedAt, extra = {}) {
+    const dir = mkdtempSync(join(tmpdir(), 'orboto-mcp-context-'));
+    hooks(dir);
+    if (session) {
+        mkdirSync(join(dir, '.orboto', 'claude-turn'), { recursive: true });
+        writeFileSync(join(dir, '.orboto', 'claude-turn', turnStateName(session)), JSON.stringify({ sessionId: session, cwd: dir, state: 'idle', contextStartedAt, ...extra }));
+    }
+    return dir;
+}
+describe('agentContextKey (ORB-2576)', () => {
+    it('names the Claude Code session and the generation its SessionStart hook recorded', () => {
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home('sess-a', '2026-10-18T10:00:00Z'))).toBe('claude-code sess-a 2026-10-18T10:00:00Z');
+    });
+    it('is unknown without the session id, without the hook record, or without a generation', () => {
+        expect(agentContextKey({}, home('sess-a', '2026-10-18T10:00:00Z'))).toBe('');
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home())).toBe('');
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home('sess-a'))).toBe('');
+    });
+    it('a subagent inside a running session gets the rules in full: its session id is the parent\'s, so the context is unknown while it runs', () => {
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, home('sess-a', '2026-10-18T10:00:00Z', { activeSubagents: ['agent-1'] }))).toBe('');
+    });
+    it('a hook set without the subagent events is an unknown context', () => {
+        const dir = home('sess-a', '2026-10-18T10:00:00Z');
+        hooks(dir, ORBOTO_HOOK_EVENTS.filter((e) => !e.startsWith('Subagent')));
+        expect(missingTurnHooks(dir)).toEqual(['SubagentStart', 'SubagentStop']);
+        expect(agentContextKey({ CLAUDE_CODE_SESSION_ID: 'sess-a' }, dir)).toBe('');
+    });
+    it('registers the same hook events as the CLI and names the turn file like it does', () => {
+        const go = readFileSync(new URL('../../../cli/internal/cmd/claude_hook.go', import.meta.url), 'utf8') + readFileSync(new URL('../../../cli/internal/cmd/claude_hook_settings.go', import.meta.url), 'utf8');
+        for (const event of ORBOTO_HOOK_EVENTS)
+            expect(go).toContain(`"${event}"`);
+        expect(turnStateName('a/b..c')).toBe('abc.json');
+        expect(turnStateName('///')).toBe('session.json');
+    });
+});

package/dist/inbox-channel-acknowledged.test.js

@@ -0,0 +1,19 @@
+/** ORB-2564 - a person's acknowledgement wakes the sending session as kind `acknowledged`, and the inbox names the ladder step of urgent mail. */
+import { describe, expect, it } from 'vitest';
+import { eventKind, renderEvent } from './inbox-channel.js';
+import { repeatMarks } from './tools/agent-messages.js';
+describe('ORB-2564 - acknowledged wake', () => {
+    it('renders the acknowledgement as its own kind and any other message by its kind', () => {
+        const ack = { id: 'a1', kind: 'info', subject: 'acknowledged: disk full', payload: { type: 'acknowledged', acknowledgedMessageId: 'm1' }, createdAt: new Date().toISOString() };
+        expect(eventKind(ack)).toBe('acknowledged');
+        const event = renderEvent(ack, Date.now());
+        expect(event.meta.kind).toBe('acknowledged');
+        expect(event.content.startsWith('[acknowledged] acknowledged: disk full')).toBe(true);
+        expect(eventKind({ kind: 'request', payload: { type: 'ticket_ready' } })).toBe('request');
+    });
+    it('marks how far an urgent message escalated', () => {
+        expect(repeatMarks({ priority: 'urgent', escalationStep: 2 })).toBe(' [urgent, escalated: deputy]');
+        expect(repeatMarks({ priority: 'urgent', escalationStep: 1, reminderCount: 1 })).toBe(' [urgent, reminder 1, escalated: mail and channels]');
+        expect(repeatMarks({ priority: 'normal' })).toBe('');
+    });
+});

package/dist/inbox-channel.js

@@ -91,14 +91,19 @@ export function isImmediate(m, now, digestMinutes) {
         return true;
     return ASK.test(`${m.subject} ${firstLine(m.payload)}`);
 }
+/** ORB-2564 - a person acknowledged a message this session sent: the event kind is `acknowledged`, so the sender stops reminding. */
+export function eventKind(m) {
+    return m.payload?.type === 'acknowledged' ? 'acknowledged' : m.kind;
+}
 export function renderEvent(m, now) {
+    const kind = eventKind(m);
     const from = m.from?.label ?? m.fromUserId ?? 'unknown';
     const to = m.to?.label ?? 'you';
     const text = firstLine(m.payload);
     const body = text.length > CONTENT_CAP ? `${text.slice(0, CONTENT_CAP)} [... cut, read the rest with orboto_messages]` : text;
     const marks = [m.priority === 'urgent' ? '[urgent]' : '', m.reminderCount ? `[reminder ${m.reminderCount}]` : ''].filter(Boolean).join(' ');
     const lines = [
-        `${marks ? `${marks} ` : ''}[${m.kind}] ${m.subject}`,
+        `${marks ? `${marks} ` : ''}[${kind}] ${m.subject}`,
         `from ${from} to ${to}${m.projectKey ? ` | project ${m.projectKey}` : ''} | id ${m.id}${m.threadId ? ` | thread ${m.threadId}` : ''}`,
     ];
     if (body)
@@ -110,7 +115,7 @@ export function renderEvent(m, now) {
     return {
         content: lines.join('\n'),
         meta: {
-            id: m.id, kind: m.kind, project: m.projectKey ?? '',
+            id: m.id, kind, project: m.projectKey ?? '',
             from: from, from_session: (m.from?.sessionId ?? '').slice(0, 8), to_session: (m.to?.sessionId ?? '').slice(0, 8),
             waited_min: String(waited),
             ...(m.priority === 'urgent' ? { priority: 'urgent' } : {}),

package/dist/orboto-client.js

@@ -4,15 +4,27 @@
  */
 import { VERSION } from './version.js';
 import { originHeader } from './session-origin.js';
+/** ORB-2581 - the seconds a `Retry-After` header asks for (delta-seconds or an HTTP date); null when absent or unreadable. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (value == null || value.trim() === '')
+        return null;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const at = Date.parse(trimmed);
+    return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - now) / 1000));
+}
 export class OrbotoApiError extends Error {
     status;
     body;
     url;
-    constructor(status, body, url) {
+    retryAfterSeconds;
+    constructor(status, body, url, retryAfterSeconds = null) {
         super(`orboto API ${status}: ${body || '(empty body)'}`);
         this.status = status;
         this.body = body;
         this.url = url;
+        this.retryAfterSeconds = retryAfterSeconds;
         this.name = 'OrbotoApiError';
     }
 }
@@ -79,7 +91,7 @@ export class OrbotoClient {
         this.pendingAgentMail = mail ? Number(mail) || 0 : 0;
         if (!res.ok) {
             const body = await res.text().catch(() => '');
-            throw new OrbotoApiError(res.status, body, url);
+            throw new OrbotoApiError(res.status, body, url, parseRetryAfter(res.headers?.get?.('retry-after')));
         }
         return res;
     }

package/dist/session-origin.js

@@ -11,8 +11,22 @@ 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'],
+    ['host', 'host'], ['machine', 'machineId'], ['repo', 'repo'], ['pid', 'pid'], ['start', 'startedAt'], ['client', 'client'], ['version', 'clientVersion'], ['harness', 'harness'], ['model', 'model'],
 ];
+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. */
+export function stdioHarness(env = process.env) {
+    const wrapped = WRAPPED_HARNESSES[(env.ORBOTO_HARNESS ?? '').trim().toLowerCase()];
+    if (wrapped)
+        return wrapped;
+    if (env.CLAUDECODE)
+        return 'claude-code';
+    if (env.CODEX_THREAD_ID || env.CODEX_SESSION_ID)
+        return 'codex';
+    if (env.GEMINI_CLI)
+        return 'gemini';
+    return 'mcp-stdio';
+}
 /** The header value; empty fields are left out. */
 export function formatOrigin(origin) {
     const params = new URLSearchParams();
@@ -75,7 +89,8 @@ export function stdioOrigin(env = process.env) {
     return formatOrigin({
         host: shortHost(), machineId: machineId(), repo: repoBasename(), pid: process.ppid || null,
         client: 'orboto-mcp', clientVersion: VERSION,
-        harness: env.CLAUDECODE ? 'claude-code' : env.CODEX_THREAD_ID || env.CODEX_SESSION_ID ? 'codex' : 'mcp-stdio',
+        harness: stdioHarness(env),
+        model: /^[\x21-\x7e]{1,80}$/.test((env.ORBOTO_MODEL ?? '').trim()) ? env.ORBOTO_MODEL.trim() : null,
     });
 }
 /** The HTTP server's origin: the server process itself, the identity of every connection is its OAuth client. */

package/dist/session-origin.test.js

@@ -7,7 +7,7 @@ import { mkdtempSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createHttpServer } from './http-transport.js';
-import { formatOrigin, machineId, repoBasename, shortHost, stdioOrigin } from './session-origin.js';
+import { formatOrigin, machineId, repoBasename, shortHost, stdioHarness, stdioOrigin } from './session-origin.js';
 import { bindSessionInstance, mcpInstanceToken, releaseSessionInstance, stableClientInstance } from './tools/shared.js';
 import { InboxChannel, SESSION_ENDED_NOTICE } from './inbox-channel.js';
 describe('ORB-2544 - the origin header', () => {
@@ -20,6 +20,17 @@ describe('ORB-2544 - the origin header', () => {
         expect(params.get('harness')).toBe('claude-code');
         expect(params.get('client')).toBe('orboto-mcp');
     });
+    it('ORB-2571 - a stdio proxy names the harness orboto <harness> started and its model, else the harness markers', () => {
+        expect(stdioHarness({ ORBOTO_HARNESS: 'kimi', CLAUDECODE: '1' })).toBe('kimi');
+        expect(stdioHarness({ ORBOTO_HARNESS: 'antigravity' })).toBe('agy');
+        expect(stdioHarness({ GEMINI_CLI: '1' })).toBe('gemini');
+        expect(stdioHarness({ CODEX_SESSION_ID: 's' })).toBe('codex');
+        expect(stdioHarness({})).toBe('mcp-stdio');
+        const params = new URLSearchParams(stdioOrigin({ ORBOTO_HARNESS: 'agy', ORBOTO_MODEL: 'gemini-4-argon' }));
+        expect(params.get('harness')).toBe('agy');
+        expect(params.get('model')).toBe('gemini-4-argon');
+        expect(new URLSearchParams(stdioOrigin({ ORBOTO_MODEL: 'has spaces' })).has('model')).toBe(false);
+    });
     it('reduces the host to its first label and a checkout to the repository basename', () => {
         expect(shortHost('Build-Host.example.lan.')).toBe('build-host');
         const root = mkdtempSync(join(tmpdir(), 'origin-'));

package/dist/tail-labels.js

@@ -36,6 +36,8 @@ export const TAIL_LABELS = [
     { method: 'GET', path: new RegExp(`^/v1/agent/messages/${SEG}/attachments(/${SEG}/url)?$`), label: 'orboto_agent_message_attachments' },
     { method: 'GET', path: /^\/admin\/agents\/transfers$/, label: 'orboto_agent_transfers' },
     { method: 'DELETE', path: new RegExp(`^/admin/agents/transfers/${SEG}$`), label: 'orboto_agent_transfers' },
+    { method: 'GET', path: new RegExp(`^/admin/agents/identities/${SEG}/query-rate-limit$`), label: 'orboto_agent_query_rate_limit' },
+    { method: 'PUT', path: new RegExp(`^/admin/agents/identities/${SEG}/query-rate-limit$`), label: 'orboto_agent_query_rate_limit' },
 ];
 /** The metrics label of one tool call: the stand-in tool name for a labelled api_call, else the tool name itself. */
 export function metricsToolName(toolName, args) {

package/dist/tools/agent-instructions.js

@@ -12,7 +12,7 @@ function excerptOf(body) {
     return firstLine.length > 200 ? `${firstLine.slice(0, 199)}\u2026` : firstLine;
 }
 function renderBlock(b) {
-    const flag = b.enabled ? '' : ' [disabled]';
+    const flag = (b.enabled ? '' : ' [disabled]') + (b.mustRead ? ' [must read]' : '');
     const kind = b.builtinKey ? `default:${b.builtinKey}` : 'custom';
     return `- ${b.title}${flag}  (${kind}, ${b.body.length} chars, id ${b.id})\n  ${excerptOf(b.body)}`;
 }
@@ -62,6 +62,7 @@ export function makeListAgentInstructionsHandler(client) {
                     id: b.id,
                     title: b.title,
                     enabled: b.enabled,
+                    ...(b.mustRead ? { mustRead: true } : {}),
                     contentChars: b.body.length,
                     ...(b.builtinKey ? { builtinKey: b.builtinKey } : {}),
                 })),
@@ -81,9 +82,10 @@ export const createAgentInstructionToolConfig = {
         projectId: z.string().uuid().optional().describe('Required for scope=project.'),
         customerId: z.string().uuid().optional().describe('Required for scope=customer.'),
         enabled: z.boolean().optional(),
+        mustRead: z.boolean().optional(),
         sortOrder: z.number().int().optional(),
-        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (400*2 chars). Only after a call was blocked.'),
-        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this body genuinely needs the length. Audit-logged.'),
+        allowOversize: z.boolean().optional().describe('Override the hard size cap (800 chars) after a blocked call.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true: why the body needs the length (audit-logged).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -113,9 +115,10 @@ export const updateAgentInstructionToolConfig = {
         title: z.string().min(1).max(120).optional(),
         body: z.string().min(1).max(8000).optional(),
         enabled: z.boolean().optional(),
+        mustRead: z.boolean().optional(),
         sortOrder: z.number().int().optional(),
-        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (400*2 chars). Only after a call was blocked.'),
-        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this body genuinely needs the length. Audit-logged.'),
+        allowOversize: z.boolean().optional().describe('Override the hard size cap (800 chars) after a blocked call.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true: why the body needs the length (audit-logged).'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };

package/dist/tools/agent-messages.js

@@ -11,12 +11,14 @@ import { z } from 'zod';
 import { makeAgentMessageWorkHandler } from './agent-message-work.js';
 import { mcpInstanceToken } from './shared.js';
 const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
-/** ORB-2563 - `[urgent]`, `sent N times` and `reminder N` next to a message, the same words the CLI prints. */
+const ESCALATED = ['', 'escalated: mail and channels', 'escalated: deputy'];
+/** ORB-2563 - `[urgent]`, `sent N times` and `reminder N` next to a message, the same words the CLI prints; ORB-2564 - the ladder step it reached. */
 export function repeatMarks(m) {
     const marks = [
         m.priority === 'urgent' ? 'urgent' : '',
         m.repeatCount && m.repeatCount > 1 ? `sent ${m.repeatCount} times` : '',
         m.reminderCount ? `reminder ${m.reminderCount}` : '',
+        ESCALATED[m.escalationStep ?? 0] ?? '',
     ].filter(Boolean);
     return marks.length ? ` [${marks.join(', ')}]` : '';
 }
@@ -104,9 +106,11 @@ export function makeAgentMessagesHandler(client) {
             feedbackSent = res.feedbackSent;
         }
         let acked = 0;
+        let escalationsStopped = 0;
         if (args.ackIds && args.ackIds.length > 0) {
             const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds, instanceToken: mcpInstanceToken(undefined, extra) });
             acked = res.acked;
+            escalationsStopped = res.escalationsStopped ?? 0;
         }
         const compact = !args.all;
         const q = new URLSearchParams();
@@ -137,6 +141,8 @@ export function makeAgentMessagesHandler(client) {
         if (args.dismiss) {
             lines.unshift(`Dismissed ${dismissedCount} message(s) as ${args.dismiss.reason}${closedCount > 0 ? `, ${closedCount} closed for the account` : ''}${feedbackSent > 0 ? `, ${feedbackSent} sender(s) told about the misroute` : ''}.`);
         }
+        if (escalationsStopped > 0)
+            lines.unshift(`Stopped the urgent escalation of ${escalationsStopped} message(s).`);
         if (sessionId)
             lines.push(`This session: ${sessionId.slice(0, 8)} (ref ${instanceToken}).`);
         else

package/dist/tools/primer-facts.js

@@ -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. Operator-only action; bots without project:edit cannot self-verify. 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. 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,

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

@@ -1,13 +1,16 @@
 import { z } from 'zod';
 export const ProjectReadinessStatusSchema = z.enum(['ok', 'missing', 'n/a']);
 export const ProjectReadinessItemIdSchema = z.enum(['project_record', 'human_manager', 'milestones', 'git_connection', 'doc_primer', 'instructions', 'tech_stack', 'commands', 'lane_assignment', 'acceptance', 'spec_settings', 'sentry_intake']);
+const ProjectReadinessFixSchema = z.object({ method: z.string(), route: z.string(), mcpTool: z.string(), cliCommand: z.string(), settingsPath: z.string() });
 export const ProjectReadinessItemSchema = z.object({
     id: ProjectReadinessItemIdSchema,
     status: ProjectReadinessStatusSchema,
     reason: z.string(),
     checked: z.number().int().nonnegative(),
     missing: z.number().int().nonnegative(),
-    fix: z.object({ method: z.string(), route: z.string(), mcpTool: z.string(), cliCommand: z.string(), settingsPath: z.string() }),
+    detail: z.string().optional().describe('The stored decision text behind the reason, e.g. why a project needs no headless lane.'),
+    fix: ProjectReadinessFixSchema,
+    alternatives: z.array(ProjectReadinessFixSchema).optional().describe('Other ways to resolve the item, offered next to fix.'),
 });
 export const ProjectReadinessSchema = z.object({
     projectId: z.string().uuid(), projectKey: z.string(), ready: z.boolean(), language: z.string(),

package/dist/tools/query.js

@@ -1,23 +1,25 @@
 /**
  * ORB-273 Phase F - `orboto_query`.
  *
- * @see ORB-531
+ * @see ORB-531, ORB-2581
  */
 import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
 import { ticketLine, agentTicketListRow } from './shared.js';
 export const queryToolConfig = {
     title: 'Run an OQL / JQL query',
-    description: 'Run a typed OQL (or Jira-shaped JQL) query against the workspace and return matching tickets. '
+    description: 'Run a typed OQL (or Jira-shaped JQL) query and return matching tickets. '
         + 'OQL grammar: `[FIND tickets WHERE] field operator value [AND|OR ...] [ORDER BY ...] [LIMIT n]` (the frame is an optional alias). '
         + 'Supported fields: key, status, statusName, statusCategory, priority, type, assignee, reporter, reporterType, assigneeType, labels, milestone, version, project, isPrivate, dueDate, startDate, createdAt, updatedAt, closedAt, estimatedTimeMinutes, loggedMinutes, parentKey. '
-        + 'reporterType / assigneeType are guest|internal - use `reporterType = guest OR assigneeType = guest` to pull up everything reported by or assigned to guests without listing each guest email. '
+        + 'reporterType / assigneeType are guest|internal (`reporterType = guest OR assigneeType = guest` finds all guest tickets). '
         + 'Operators: = != < <= > >= ~ !~ IN IS [NOT] NULL IS [NOT] EMPTY. '
         + 'Functions: currentUser(), now(), startOfWeek(), endOfWeek(), startOfMonth(), endOfMonth(), daysAgo(n). '
         + 'Examples: '
         + '`project = ORB AND assignee = currentUser() AND statusCategory != done`; '
         + '`priority IN (blocker, high) AND dueDate <= now() ORDER BY dueDate ASC LIMIT 25`; '
         + '`labels = "bug" AND createdAt >= daysAgo(7)`. '
-        + 'Reach for this tool when per-entity tools (orboto_list_tickets / orboto_my_tickets) cannot express the combined filter.',
+        + 'Use it when orboto_list_tickets / orboto_my_tickets cannot express the filter. '
+        + 'A 429 is retried at most twice, then returned with structuredContent rateLimited, retryAfterSeconds, limitPerMinute.',
     inputSchema: z.object({
         oql: z.string().min(1).max(8000).describe('The query string.'),
         syntax: z.enum(['oql', 'jql']).default('oql').describe('"jql" accepts Jira-flavoured syntax.'),
@@ -27,7 +29,35 @@ export const queryToolConfig = {
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
-export function makeQueryHandler(client) {
+/** ORB-2581 - `orboto_query` waits out at most two 429s of up to 20 seconds each, then answers with the retry hint. */
+export const QUERY_RETRY = { maxRetries: 2, maxWaitSeconds: 20 };
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function rateLimitDetails(err) {
+    let params = {};
+    try {
+        params = JSON.parse(err.body).errorParams ?? {};
+    }
+    catch {
+        params = {};
+    }
+    const fromBody = typeof params.retryAfterSeconds === 'number' ? params.retryAfterSeconds : null;
+    return {
+        retryAfterSeconds: Math.max(0, err.retryAfterSeconds ?? fromBody ?? 1),
+        limitPerMinute: typeof params.limitPerMinute === 'number' ? params.limitPerMinute : null,
+    };
+}
+function rateLimitedResult(details, attempts) {
+    const limit = details.limitPerMinute !== null ? ` (${details.limitPerMinute} per minute)` : '';
+    return {
+        isError: true,
+        content: [{
+                type: 'text',
+                text: `Rate limited: this account's OQL query limit${limit} is used up. Retry after ${details.retryAfterSeconds} seconds (tried ${attempts} times).`,
+            }],
+        structuredContent: { rateLimited: true, retryAfterSeconds: details.retryAfterSeconds, limitPerMinute: details.limitPerMinute, attempts },
+    };
+}
+export function makeQueryHandler(client, sleep = realSleep) {
     return async (input) => {
         const body = {
             oql: input.oql,
@@ -35,7 +65,20 @@ export function makeQueryHandler(client) {
             cursor: input.cursor,
             limit: input.limit ?? 25,
         };
-        const page = await client.post('/query', body);
+        let page;
+        for (let attempt = 1; page === undefined; attempt += 1) {
+            try {
+                page = await client.post('/query', body);
+            }
+            catch (err) {
+                if (!(err instanceof OrbotoApiError) || err.status !== 429)
+                    throw err;
+                const details = rateLimitDetails(err);
+                if (attempt > QUERY_RETRY.maxRetries || details.retryAfterSeconds > QUERY_RETRY.maxWaitSeconds)
+                    return rateLimitedResult(details, attempt);
+                await sleep(details.retryAfterSeconds * 1000);
+            }
+        }
         const text = page.items.length === 0
             ? 'No tickets matched.'
             : page.items.map((t) => `- ${ticketLine(t)}`).join('\n');

package/dist/tools/query.test.js

@@ -86,6 +86,75 @@ describe('tools/query', () => {
         }));
     });
 });
+import { metricsToolName } from '../tail-labels.js';
+import { parseRetryAfter } from '../orboto-client.js';
+import { QUERY_RETRY } from './query.js';
+function rateLimited(retryAfter, errorParams = {}) {
+    return {
+        ok: false, status: 429, statusText: 'Too Many Requests',
+        headers: new Headers(retryAfter === null ? {} : { 'retry-after': retryAfter }),
+        text: async () => JSON.stringify({ error: 'Rate limit exceeded', errorKey: 'errors.common.rate_limited', errorParams }),
+    };
+}
+function ok(json) {
+    return { ok: true, status: 200, statusText: 'OK', headers: new Headers(), json: async () => json };
+}
+describe('tools/query - 429 and Retry-After (ORB-2581)', () => {
+    const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+    it('waits the Retry-After seconds and retries until the query answers', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch')
+            .mockResolvedValueOnce(rateLimited('3'))
+            .mockResolvedValueOnce(ok({ items: [], nextCursor: null }));
+        const sleep = vi.fn(async () => { });
+        const result = await makeQueryHandler(client, sleep)({ oql: 'project = ORB' });
+        expect(sleep).toHaveBeenCalledWith(3000);
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0]).toEqual({ type: 'text', text: 'No tickets matched.' });
+    });
+    it('stops after the bounded retries and answers with the retry hint', async () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(rateLimited('5', { retryAfterSeconds: 5, limitPerMinute: 60 }));
+        const sleep = vi.fn(async () => { });
+        const result = await makeQueryHandler(client, sleep)({ oql: 'project = ORB' });
+        expect(fetchSpy).toHaveBeenCalledTimes(QUERY_RETRY.maxRetries + 1);
+        expect(sleep).toHaveBeenCalledTimes(QUERY_RETRY.maxRetries);
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('Retry after 5 seconds');
+        expect(result.structuredContent).toEqual({ rateLimited: true, retryAfterSeconds: 5, limitPerMinute: 60, attempts: QUERY_RETRY.maxRetries + 1 });
+    });
+    it('never waits longer than the cap: a long Retry-After answers at once', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValue(rateLimited(String(QUERY_RETRY.maxWaitSeconds + 1)));
+        const sleep = vi.fn(async () => { });
+        const result = await makeQueryHandler(client, sleep)({ oql: 'project = ORB' });
+        expect(sleep).not.toHaveBeenCalled();
+        expect(result.structuredContent).toMatchObject({ rateLimited: true, retryAfterSeconds: QUERY_RETRY.maxWaitSeconds + 1, attempts: 1 });
+    });
+    it('reads the wait from errorParams when a proxy dropped the header', async () => {
+        vi.spyOn(globalThis, 'fetch')
+            .mockResolvedValueOnce(rateLimited(null, { retryAfterSeconds: 7 }))
+            .mockResolvedValueOnce(ok({ items: [], nextCursor: null }));
+        const sleep = vi.fn(async () => { });
+        await makeQueryHandler(client, sleep)({ oql: 'project = ORB' });
+        expect(sleep).toHaveBeenCalledWith(7000);
+    });
+    it('passes every other error through unchanged', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+            ok: false, status: 400, statusText: 'Bad Request', headers: new Headers(), text: async () => '{"errorKey":"errors.oql.parse"}',
+        });
+        await expect(makeQueryHandler(client, vi.fn(async () => { }))({ oql: '((' })).rejects.toMatchObject({ status: 400 });
+    });
+    it('parses delta-seconds and HTTP dates', () => {
+        expect(parseRetryAfter('12')).toBe(12);
+        expect(parseRetryAfter(null)).toBeNull();
+        expect(parseRetryAfter('soon')).toBeNull();
+        expect(parseRetryAfter(new Date(Date.UTC(2026, 9, 18, 12, 0, 30)).toUTCString(), Date.UTC(2026, 9, 18, 12, 0, 0))).toBe(30);
+    });
+    it('labels the query limit tail routes for metrics', () => {
+        const id = '00000000-0000-4000-8000-000000000000';
+        expect(metricsToolName('orboto_api_call', { method: 'GET', path: `/admin/agents/identities/${id}/query-rate-limit` })).toBe('orboto_agent_query_rate_limit');
+        expect(metricsToolName('orboto_api_call', { method: 'PUT', path: `/admin/agents/identities/${id}/query-rate-limit` })).toBe('orboto_agent_query_rate_limit');
+    });
+});
 import { agentTicketListRow } from './shared.js';
 describe('agentTicketListRow (ORB-1699)', () => {
     const FULL = {

package/dist/tools/session-start.js

@@ -18,11 +18,12 @@ import { channelStartLines } from '../inbox-channel.js';
 import { rememberDeclaredScope } from '../session-scope-memory.js';
 import { declareEnvProjectScope, envProjectScope } from '../project-scope.js';
 import { agentHeadText } from '../agent-head.js';
+import { agentContextKey } from '../agent-context.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
-    description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Registers this session (a heartbeat on its instance row) and is otherwise read-only. '
-        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136). '
-        + 'The digest also carries the Knowledge block (ORB-2225): the wiki index of your declared projects and of the Operations wiki, their latest log entries and open lint issues; ask the wiki with orboto_knowledge_ask before asking a person, file durable facts with orboto_knowledge_add. It also carries the Responsibilities block (ORB-2542): who owns the topics of your declared projects, looked up with orboto_who for before you send agent mail.',
+    description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it FIRST in a session and AFTER every context compaction. Returns the rules in full (above the full-text bound: one title per rule plus every must-read rule in full, the rest via `rulesOnly: true`); a compact "unchanged" ack only on a repeat inside the same agent context. Also returns your in-progress tickets (LANDED, IDLE = a linked commit but no move for days: finished work never handed to review), your timer and unhealthy git connections. Not orboto_list_agent_instructions - that one edits rule blocks for admins. Registers this session (a heartbeat on its instance row), otherwise read-only. '
+        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text, never truncated. `projectId` adds that project\'s rules. `ticketKey` ("ACME-42") bundles that ticket\'s primer, detail, dependencies, checklists, git health and other agent sessions. `forceRules: true` returns the full text inline even above the bound or after an ack - use it whenever the rules are NOT in your context. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) target rule blocks and per-tier text. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; session.ref is what peers pass as toSessionRef (ORB-2136). '
+        + 'Also carries the Knowledge block (ORB-2225: the wiki index of your declared projects and the Operations wiki; ask with orboto_knowledge_ask before a person, file durable facts with orboto_knowledge_add) and the Responsibilities block (ORB-2542: who owns the topics of your projects, orboto_who before agent mail). Right after the rules come Where knowledge lives (ORB-2575: rules bind behaviour, project facts hold fixed decisions, the wiki the long tail; a decision goes to a fact proposal, orboto_primer_fact_add with observed: true) and the Project facts of your declared projects.',
     inputSchema: z.object({
         projectId: z.string().uuid().optional().describe('Also load this project\'s rules.'),
         ticketKey: z.string().min(3).optional().describe('Ticket key ("ACME-42") - bundles that ticket\'s full context.'),
@@ -133,6 +134,22 @@ async function buildTicketBundle(client, ticketKey) {
         },
     };
 }
+/** ORB-2575 - the facts block stays small; the rest is one expand away, like the Knowledge block. */
+export const PROJECT_FACTS_BLOCK_CHARS = 3000;
+export function projectFactsLines(text, owner = PROCESS_OWNER) {
+    if (text.length <= PROJECT_FACTS_BLOCK_CHARS)
+        return { lines: text.split('\n') };
+    const cut = text.slice(0, PROJECT_FACTS_BLOCK_CHARS);
+    const kept = cut.slice(0, Math.max(cut.lastIndexOf('\n'), 0));
+    const handle = storePayload('orboto_session_start', {
+        structuredContent: { projectFacts: text }, text,
+        omitted: [{ path: 'projectFacts', kind: 'string', omittedChars: text.length - kept.length }],
+    }, Date.now(), owner);
+    return {
+        handle,
+        lines: [...kept.split('\n'), `(Project facts cut at ${kept.length} of ${text.length} characters: orboto_response_expand { handle: "${handle}", path: "projectFacts" }, or orboto_get_project_primer.)`],
+    };
+}
 /** ORB-2225 - the Knowledge block stays small; the rest is one expand away. */
 export const KNOWLEDGE_BLOCK_CHARS = 1500;
 export function knowledgeLines(text, owner = PROCESS_OWNER) {
@@ -164,7 +181,8 @@ export function identityLine(registration) {
     return `This scope stays with this session across reconnects and restarts; declare it again only to change it.${kept}`;
 }
 export function makeSessionStartHandler(client, opts = {}) {
-    let lastKnownRulesHash;
+    const currentContext = opts.agentContext ?? (() => agentContextKey());
+    let delivered;
     return async (input = {}, extra) => {
         const instanceToken = mcpInstanceToken(undefined, extra);
         const rulesParams = new URLSearchParams();
@@ -172,14 +190,15 @@ export function makeSessionStartHandler(client, opts = {}) {
             rulesParams.set('projectId', input.projectId);
         applyAgentProfile(rulesParams, { agentKind: input.agentKind, modelTier: input.modelTier });
         const wantsFullRules = input.forceRules === true || input.rulesOnly === true;
-        if (lastKnownRulesHash && !wantsFullRules)
-            rulesParams.set('knownRulesHash', lastKnownRulesHash);
+        const context = currentContext();
+        if (context && delivered?.context === context && !wantsFullRules)
+            rulesParams.set('knownRulesHash', delivered.hash);
         const rulesQs = rulesParams.toString();
         const rulesPath = rulesQs ? `/agent-instructions?${rulesQs}` : '/agent-instructions';
         if (input.rulesOnly) {
             const rules = await loadRequiredRules(client, rulesPath);
-            if (rules.rulesHash)
-                lastKnownRulesHash = rules.rulesHash;
+            if (context && rules.rulesHash)
+                delivered = { context, hash: rules.rulesHash };
             const text = rules.instructions ?? '';
             return {
                 _meta: { [PROTECT_TEXT_META]: true },
@@ -211,7 +230,7 @@ export function makeSessionStartHandler(client, opts = {}) {
         if (input.scope === undefined && registration && !registration.scope && envProjectScope()) {
             registration = toRegistration(await declareEnvProjectScope(client, instanceToken)) ?? registration;
         }
-        const [me, rules, assigned, timer, inboxRaw, knowledge, owners] = await Promise.all([
+        const [me, rules, assigned, timer, inboxRaw, knowledge, owners, projectFacts] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             client.get('/users/me/assigned-tickets?statuses=IN_PROGRESS,IN_REVIEW&limit=20').catch(() => ({ items: [] })),
@@ -225,6 +244,9 @@ export function makeSessionStartHandler(client, opts = {}) {
             client.get('/responsibilities/block', { instanceToken })
                 .then((r) => (typeof r?.text === 'string' && r.text ? { text: r.text, scoped: Array.isArray(r.entries) ? r.entries.length : 0, total: r.total ?? 0 } : null))
                 .catch(() => null),
+            client.get('/project-facts', { instanceToken })
+                .then((r) => (typeof r?.text === 'string' && r.text.trim() && Array.isArray(r.projects) && Array.isArray(r.unknown) ? r : null))
+                .catch(() => null),
         ]);
         const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, from: m.from?.label ?? m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
@@ -256,18 +278,18 @@ export function makeSessionStartHandler(client, opts = {}) {
         if (me?.workspaceLocale || me?.locale)
             lines.push(`Write tickets / comments / docs in: ${me.workspaceLocale ?? me.locale}.`);
         const rulesText = rules.instructions ?? '';
-        const rulesIndex = Array.isArray(rules.rulesIndex)
-            ? rules.rulesIndex.map((e) => e?.title).filter((t) => typeof t === 'string' && t.length > 0)
-            : [];
-        const deliverIndex = !rules.rulesUnchanged && input.forceRules !== true && rulesIndex.length > 0 && rulesText.length > 0;
+        const indexEntries = Array.isArray(rules.rulesIndex) ? rules.rulesIndex.filter((e) => typeof e?.title === 'string' && e.title.length > 0) : [];
+        const rulesIndex = indexEntries.map((e) => e.title);
+        const mustRead = indexEntries.filter((e) => e.mustRead === true && typeof e.body === 'string' && e.body.trim().length > 0);
+        const deliverIndex = !rules.rulesUnchanged && input.forceRules !== true && rules.rulesDelivery === 'index' && rulesIndex.length > 0 && rulesText.length > 0;
         const deliverFull = !rules.rulesUnchanged && !deliverIndex && rulesText.length > 0;
         const rulesChars = rules.rulesChars ?? rulesText.length;
         const HOW_TO_READ_RULES = 'Call orboto_session_start { rulesOnly: true } for the complete rule text (one call, never truncated). '
-            + 'Do that whenever you do not already hold this exact rulesHash - after a compaction, a /clear, or as a fresh agent.';
+            + 'Do that whenever you do not already hold this exact rulesHash.';
         let rulesHandle;
         lines.push('', '## Working rules - follow these');
         if (rules.rulesUnchanged) {
-            lines.push(`Unchanged since this connection last delivered them (hash ${rules.rulesHash}), so they were left out to save context.`, 'If the rules are NOT in your context right now - after a compaction, a /clear, or because you are a fresh agent on an existing connection - call this tool again with rulesOnly=true (rules alone) or forceRules=true (rules plus this digest) and read them in full. Do not proceed on a half-remembered rule set.');
+            lines.push(`Unchanged since this agent context received them in full (hash ${rules.rulesHash}), so they were left out to save context.`, 'If the rules are NOT in your context right now, call this tool again with rulesOnly=true (rules alone) or forceRules=true (rules plus this digest) and read them in full. Do not proceed on a half-remembered rule set.');
         }
         else if (deliverIndex) {
             rulesHandle = storePayload('orboto_session_start', {
@@ -275,11 +297,16 @@ export function makeSessionStartHandler(client, opts = {}) {
                 text: rules.instructions ?? '',
                 omitted: [{ path: 'rules', kind: 'string', omittedChars: rulesText.length }],
             }, Date.now(), client);
-            lines.push(`${rulesIndex.length} rule(s) bind you (${rulesChars} characters, hash ${rules.rulesHash}). Titles only - the full text is NOT in this response.`, `${HOW_TO_READ_RULES} Read any rule below whose title touches what you are about to do BEFORE you do it. (orboto_response_expand { handle: "${rulesHandle}", path: "rules" } serves the same text from this process for 15 minutes.)`, ...rulesIndex.map((title, i) => `${i + 1}. ${title}`));
+            lines.push(`${rulesIndex.length} rule(s) bind you (${rulesChars} characters, hash ${rules.rulesHash}). The set is above the full-text bound, so the titles are printed and the ${mustRead.length} must-read rule(s) in full.`, `${HOW_TO_READ_RULES} Read any rule below whose title touches what you are about to do BEFORE you do it. (orboto_response_expand { handle: "${rulesHandle}", path: "rules" } serves the same text from this process for 15 minutes.)`, ...indexEntries.map((e, i) => `${i + 1}. ${e.title}${mustRead.includes(e) ? ' (must read, in full below)' : ''}`));
+            for (const e of mustRead)
+                lines.push('', `### Must read: ${e.title}`, String(e.body).trim());
         }
         else {
             lines.push(rulesText || '(no workspace rules configured)');
         }
+        const factsBlock = projectFacts ? projectFactsLines(projectFacts.text.trim(), client) : null;
+        if (factsBlock)
+            lines.push('', ...factsBlock.lines);
         lines.push('', '## Your in-progress work');
         if (tickets.length === 0)
             lines.push('No tickets currently assigned to you - claim or create one before you start coding.');
@@ -336,7 +363,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                 rulesUnchanged: rules.rulesUnchanged === true,
                 rulesDelivery: rules.rulesUnchanged ? 'ack' : deliverIndex ? 'index' : 'full',
                 ...(deliverIndex
-                    ? { rulesIndex, rulesChars, rulesHandle, rulesHowToRead: HOW_TO_READ_RULES }
+                    ? { rulesIndex, rulesChars, rulesHandle, rulesHowToRead: HOW_TO_READ_RULES, mustRead: mustRead.map((e) => e.title) }
                     : {}),
                 ...(rules.rulesUnchanged ? { rulesHowToRead: HOW_TO_READ_RULES } : {}),
                 inProgress: scopedTickets.map((t) => ({
@@ -358,12 +385,22 @@ export function makeSessionStartHandler(client, opts = {}) {
                     healthyCount: gitHealthWithConnections.reduce((n, p) => n + p.connections.filter((c) => c.healthy).length, 0),
                 },
                 ...(knowledge ? { knowledge: knowledgeSummary(knowledge, knowledgeBlock?.handle) } : {}),
+                ...(projectFacts ? {
+                    projectFacts: {
+                        source: projectFacts.source,
+                        projects: projectFacts.projects.map((p) => ({ projectKey: p.projectKey, total: p.total, shown: Array.isArray(p.facts) ? p.facts.length : 0 })),
+                        workspace: { total: projectFacts.workspace?.total ?? 0, shown: Array.isArray(projectFacts.workspace?.facts) ? projectFacts.workspace.facts.length : 0 },
+                        unknown: projectFacts.unknown,
+                        ...(factsBlock?.handle ? { handle: factsBlock.handle } : {}),
+                    },
+                } : {}),
                 ...(owners ? { responsibilities: { scoped: owners.scoped, total: owners.total } } : {}),
                 ...(pendingMessages.length > 0 ? { pendingMessages } : {}),
                 ...(bundle ? { ticketBundle: bundle.structured } : {}),
             },
         };
-        lastKnownRulesHash = rules.rulesHash;
+        if (context && deliverFull && rules.rulesHash)
+            delivered = { context, hash: rules.rulesHash };
         return result;
     };
 }

package/dist/tools/session-start.test.js

@@ -11,10 +11,12 @@ import { OrbotoClient } from '../orboto-client.js';
 import { makeSessionStartHandler } from './session-start.js';
 import { _forgetDeclaredScopes, rememberedScope } from '../session-scope-memory.js';
 import { CHANNEL_START_COMMANDS, CHANNEL_START_COMMANDS_WITHOUT_CLI } from '../inbox-channel.js';
-import { readFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ORBOTO_HOOK_EVENTS, agentContextKey } from '../agent-context.js';
 import { makeResponseExpandHandler } from './response-expand.js';
 import { applyResponseBudget, budgetFor, DEFAULT_BUDGET_CHARS } from '../response-budget.js';
-import { hostname } from 'node:os';
+import { hostname, tmpdir } from 'node:os';
 import { localSessionHost } from './shared.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
@@ -120,8 +122,8 @@ describe('orboto_session_start (ORB-1093)', () => {
         expect(text).not.toContain('Git connection health - WARNING');
     });
 });
-describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
-    it('sends no knownRulesHash on the first call, then passes the received hash back on the second', async () => {
+describe('orboto_session_start - rules-hash ack (ORB-1607, ORB-2576)', () => {
+    it('sends no knownRulesHash on the first call, then passes the received hash back inside the same agent context', async () => {
         const calls = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
             const u = new URL(url.toString());
@@ -141,7 +143,8 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
             const key = Object.keys(fallback).find((k) => (u.pathname + u.search).startsWith(k));
             return { ok: true, status: 200, statusText: 'OK', json: async () => (key ? fallback[key] : {}), text: async () => '' };
         });
-        const handler = makeSessionStartHandler(client);
+        let context = 'claude-code sess-a 2026-10-18T10:00:00Z';
+        const handler = makeSessionStartHandler(client, { agentContext: () => context });
         const first = await handler();
         const firstCall = calls.find((c) => c.startsWith('/agent-instructions'));
         expect(firstCall).toBe('/agent-instructions');
@@ -155,13 +158,23 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
         const secondCall = calls.find((c) => c.startsWith('/agent-instructions'));
         expect(secondCall).toBe('/agent-instructions?knownRulesHash=abc123def456');
         const secondText = second.content[0].text;
-        expect(secondText).toContain('Unchanged since this connection last delivered them');
+        expect(secondText).toContain('Unchanged since this agent context received them in full');
         expect(secondText).toContain('forceRules=true');
         expect(secondText).not.toContain('keep following what you already loaded');
         expect(secondText).not.toContain('claim -> commit -> close');
         const secondStructured = second.structuredContent;
         expect(secondStructured.rulesHash).toBe('abc123def456');
         expect(secondStructured.rulesUnchanged).toBe(true);
+        calls.length = 0;
+        context = 'claude-code sess-a 2026-10-18T11:00:00Z';
+        const afterCompaction = await handler();
+        expect(calls.find((c) => c.startsWith('/agent-instructions'))).toBe('/agent-instructions');
+        expect(afterCompaction.content[0].text).toContain('claim -> commit -> close');
+        calls.length = 0;
+        context = '';
+        await handler();
+        await handler();
+        expect(calls.filter((c) => c.startsWith('/agent-instructions'))).toEqual(['/agent-instructions', '/agent-instructions']);
     });
     it('a fresh handler (new connection) starts with no cached hash again', async () => {
         const calls = stubByPath({
@@ -175,6 +188,46 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
         expect(call).toBe('/agent-instructions');
     });
 });
+describe('orboto_session_start - knowledge layers and project facts (ORB-2575)', () => {
+    const FACTS_TEXT = '## Where knowledge lives\n- Rules: binding behaviour.\n\n## Project facts\n### ORB (project id proj-1): 1 of 3 facts\n- tech_stack/stack: Go and Postgres\n2 more: `orboto primer ORB`';
+    const facts = (text) => ({
+        source: 'session', unknown: [], text,
+        projects: [{ projectKey: 'ORB', projectId: 'proj-1', total: 3, facts: [{ category: 'tech_stack', key: 'stack', value: 'Go and Postgres', observed: false }] }],
+        workspace: { total: 0, facts: [] },
+    });
+    const base = {
+        '/users/me/assigned-tickets': { items: [] },
+        '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
+        '/agent-instructions': { instructions: 'RULE TEXT', rulesHash: 'h1' },
+        '/time/timer': {},
+    };
+    it('prints the layers and the facts right after the rules, and summarises the counts', async () => {
+        const calls = stubByPath({ ...base, '/project-facts': facts(FACTS_TEXT) });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        expect(calls).toContain('/project-facts');
+        expect(text).toContain(`RULE TEXT\n\n${FACTS_TEXT}\n\n## Your in-progress work`);
+        expect(res.structuredContent.projectFacts).toEqual({
+            source: 'session', projects: [{ projectKey: 'ORB', total: 3, shown: 1 }], workspace: { total: 0, shown: 0 }, unknown: [],
+        });
+    });
+    it('a long facts block is cut with a handle to the rest', async () => {
+        const long = `${FACTS_TEXT}\n${Array.from({ length: 80 }, (_, i) => `- other/fact-${i}: ${'v'.repeat(60)}`).join('\n')}`;
+        stubByPath({ ...base, '/project-facts': facts(long) });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        const handle = res.structuredContent.projectFacts.handle;
+        expect(handle).toBeTruthy();
+        expect(text).toContain(`orboto_response_expand { handle: "${handle}", path: "projectFacts" }`);
+        expect(text).not.toContain('fact-79');
+    });
+    it('an API without the block, or with a malformed one, leaves the section out', async () => {
+        stubByPath({ ...base, '/project-facts': { text: '## Project facts' } });
+        const res = await makeSessionStartHandler(client)();
+        expect(res.content[0].text).not.toContain('## Project facts');
+        expect(res.structuredContent.projectFacts).toBeUndefined();
+    });
+});
 describe('orboto_session_start - ticketKey bundle (ORB-1607)', () => {
     const bundleStubs = {
         '/projects/by-key/ORB': { id: 'proj-1', key: 'ORB', name: 'orboto' },
@@ -263,9 +316,28 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
         expect(text).toContain('THE FULL RULE TEXT');
         expect(text).not.toContain('forceRules=true');
     });
-    it('without forceRules the ack path is still used - the saving is not lost', async () => {
+    it('ORB-2576 - a subagent inside a running session gets the rules in full', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'orboto-mcp-subagent-'));
+        mkdirSync(join(dir, '.claude'), { recursive: true });
+        writeFileSync(join(dir, '.claude', 'settings.local.json'), JSON.stringify({ hooks: Object.fromEntries(ORBOTO_HOOK_EVENTS.map((e) => [e, [{ hooks: [{ type: 'command', command: 'orboto claude-hook' }] }]])) }));
+        const turn = (extra) => {
+            mkdirSync(join(dir, '.orboto', 'claude-turn'), { recursive: true });
+            writeFileSync(join(dir, '.orboto', 'claude-turn', 'sess-a.json'), JSON.stringify({ sessionId: 'sess-a', cwd: dir, state: 'idle', contextStartedAt: '2026-10-18T10:00:00Z', ...extra }));
+        };
+        const env = { CLAUDE_CODE_SESSION_ID: 'sess-a' };
         const calls = stubByPath(rulesStub);
-        const handler = makeSessionStartHandler(client);
+        const handler = makeSessionStartHandler(client, { agentContext: () => agentContextKey(env, dir) });
+        turn({});
+        await handler();
+        turn({ activeSubagents: ['agent-1'], contextStartedAt: '2026-10-18T10:05:00Z' });
+        calls.length = 0;
+        const inSubagent = await handler();
+        expect(calls.find((c) => c.startsWith('/agent-instructions'))).toBe('/agent-instructions');
+        expect(inSubagent.content[0].text).toContain('THE FULL RULE TEXT');
+    });
+    it('without forceRules the ack path is still used inside one agent context - the saving is not lost', async () => {
+        const calls = stubByPath(rulesStub);
+        const handler = makeSessionStartHandler(client, { agentContext: () => 'claude-code sess-a 2026-10-18T10:00:00Z' });
         await handler();
         calls.length = 0;
         await handler();
@@ -412,7 +484,7 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
     const BLOCK_TITLES = Array.from({ length: 27 }, (_, i) => `Rule block number ${i + 1} - a realistic operator-authored title`);
     const RULES_TEXT = BLOCK_TITLES.map((t, i) => `${t}\n${'x'.repeat(650)}${i}`).join('\n\n');
     const RULES_INDEX = BLOCK_TITLES.map((title) => ({ title, chars: 651 }));
-    const rulesFull = { instructions: RULES_TEXT, rulesHash: 'hash1818aaaa', rulesIndex: RULES_INDEX, rulesChars: RULES_TEXT.length };
+    const rulesFull = { instructions: RULES_TEXT, rulesHash: 'hash1818aaaa', rulesIndex: RULES_INDEX, rulesChars: RULES_TEXT.length, rulesDelivery: 'index' };
     function stubDigest(rules) {
         return stubByPath({
             '/users/me/assigned-tickets': {
@@ -469,9 +541,9 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         expect(chunks.join('')).toBe(RULES_TEXT);
     });
     it('an acked hash returns neither the text NOR the index', async () => {
-        const handler = makeSessionStartHandler(client);
+        const handler = makeSessionStartHandler(client, { agentContext: () => 'claude-code sess-a 2026-10-18T10:00:00Z' });
         stubDigest(rulesFull);
-        await handler();
+        await handler({ forceRules: true });
         vi.restoreAllMocks();
         stubDigest({ rulesHash: 'hash1818aaaa', rulesUnchanged: true });
         const second = await handler();
@@ -480,7 +552,7 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         expect(structured.rulesIndex).toBeUndefined();
         expect(structured.rules).toBe('');
         const text = second.content[0].text;
-        expect(text).toContain('Unchanged since this connection last delivered them');
+        expect(text).toContain('Unchanged since this agent context received them in full');
         expect(text).toContain('rulesOnly=true');
         expect(text).not.toContain('Rule block number 1');
     });
@@ -521,6 +593,31 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         await handler({ rulesOnly: true });
         expect(calls[0]).toBe('/agent-instructions');
     });
+    it('ORB-2576 - a set under the bound comes in full even with an index', async () => {
+        stubDigest({ ...rulesFull, rulesDelivery: 'full' });
+        const res = await makeSessionStartHandler(client)();
+        expect(res.structuredContent.rulesDelivery).toBe('full');
+        expect(res.content[0].text).toContain(RULES_TEXT);
+    });
+    it('ORB-2576 - above the bound every must-read rule comes in full after the titles', async () => {
+        const index = RULES_INDEX.map((e, i) => (i === 1 ? { ...e, mustRead: true, body: 'MUST READ BODY' } : e));
+        stubDigest({ ...rulesFull, rulesIndex: index });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        expect(text).toContain('so the titles are printed and the 1 must-read rule(s) in full.');
+        expect(text).toContain(`2. ${BLOCK_TITLES[1]} (must read, in full below)`);
+        expect(text).toContain(`### Must read: ${BLOCK_TITLES[1]}\nMUST READ BODY`);
+        expect(res.structuredContent.mustRead).toEqual([BLOCK_TITLES[1]]);
+    });
+    it('ORB-2576 - an index delivery is no receipt: the next start in the same context sends no known hash', async () => {
+        const handler = makeSessionStartHandler(client, { agentContext: () => 'claude-code sess-a 2026-10-18T10:00:00Z' });
+        stubDigest(rulesFull);
+        await handler();
+        vi.restoreAllMocks();
+        const calls = stubDigest(rulesFull);
+        await handler();
+        expect(calls.find((c) => c.startsWith('/agent-instructions'))).toBe('/agent-instructions');
+    });
     it('an API too old to send an index still delivers the full rules inline', async () => {
         stubDigest({ instructions: RULES_TEXT, rulesHash: 'oldapi' });
         const res = await makeSessionStartHandler(client)();

package/dist/tools/update-project.js

@@ -13,7 +13,7 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 const LOCALE_CODES = ['en', 'de', 'fr', 'es', 'it', 'nl', 'pt', 'ru', 'pl', 'tr', 'cs', 'da', 'sv', 'no', 'fi', 'ja', 'zh', 'ko'];
 export const updateProjectToolConfig = {
     title: 'Update a project\'s metadata',
-    description: 'Patch a project (`name`, `description`, `key`, `status`, `branchTemplate`, `customerId`, `language`). At least one field must be set. Use `status: "archived"` or `"closed"` to take a project out of active rotation. Renaming the `key` also rewrites every ticket\'s `PROJ-N` reference - handle with care. `language` sets the project\'s expected ticket language (one of the 18 supported locales); pass null to inherit the workspace language.',
+    description: 'Patch a project; set at least one field. `status` archived or closed leaves rotation. A `key` rename rewrites `PROJ-N` references. `language` null inherits. `noLaneReason`: no headless lane needed (bots work interactively); null clears.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Current project key.'),
         patch: z.object({
@@ -28,6 +28,7 @@ export const updateProjectToolConfig = {
                 .describe('Customer UUID; null detaches.'),
             language: z.enum(LOCALE_CODES).nullable().optional()
                 .describe('Content language; null inherits workspace.'),
+            noLaneReason: z.string().nullable().optional(),
         }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' }),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -49,6 +50,7 @@ export function makeUpdateProjectHandler(client) {
                 description: updated.description,
                 status: updated.status,
                 language: updated.language ?? null,
+                noLaneReason: updated.noLaneReason ?? null,
                 spec: updated.spec,
             },
         };

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

@@ -30,6 +30,16 @@ function stub(responses) {
 const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
 const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
 describe('orboto_update_project', () => {
+    it('ORB-2569 records and clears the no-lane decision, string or null', async () => {
+        const calls = stub([{ json: PROJ }, { json: { ...PROJ, noLaneReason: 'Bots work interactively' } }, { json: PROJ }, { json: { ...PROJ, noLaneReason: null } }]);
+        const handler = makeUpdateProjectHandler(client);
+        const set = await handler({ projectKey: 'ACME', patch: { noLaneReason: 'Bots work interactively' } });
+        expect(calls[1]).toMatchObject({ method: 'PATCH', body: { noLaneReason: 'Bots work interactively' } });
+        expect(set.structuredContent).toMatchObject({ noLaneReason: 'Bots work interactively' });
+        const cleared = await handler({ projectKey: 'ACME', patch: { noLaneReason: null } });
+        expect(calls[3]).toMatchObject({ body: { noLaneReason: null } });
+        expect(cleared.structuredContent).toMatchObject({ noLaneReason: null });
+    });
     it('PATCHes only the supplied fields', async () => {
         const calls = stub([
             { json: PROJ },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.222.2",
+  "version": "0.223.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",