@orboto/mcp 0.222.0 → 0.223.0

package/dist/tools/backup.js

@@ -8,6 +8,7 @@
  * download mechanism. `OrbotoClient.postBinary` / `getBinary` fetch the bytes.
  */
 import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
 /**
  * ORB-1504 - an operator passphrase is deliberately NOT an MCP input: it
  * would land in the conversation transcript and the tool-call audit. The
@@ -16,15 +17,38 @@ import { z } from 'zod';
  */
 const seal = (run) => run.sealed ? ` [encrypted, ${run.sealCustody ?? 'platform'} key${run.sealKeyFingerprint ? ` ${run.sealKeyFingerprint}` : ''}]` : '';
 const mb = (n) => `${Math.round((n / 1024 / 1024) * 10) / 10} MB`;
+/** ORB-2562 - the running run's id when the API refused a full export start with 409 errors.backups.full_export_in_progress. */
+export function runningFullExportId(err) {
+    if (!(err instanceof OrbotoApiError) || err.status !== 409)
+        return null;
+    try {
+        const body = JSON.parse(err.body);
+        if (body.errorKey !== 'errors.backups.full_export_in_progress')
+            return null;
+        return typeof body.errorParams?.runId === 'string' ? body.errorParams.runId : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rethrows a full-export refusal as a sentence that names the running run. */
+export function rethrowFullExportInProgress(err) {
+    const runId = runningFullExportId(err);
+    if (runId) {
+        throw new Error(`A full export is already running (run ${runId}); nothing was started. Download that run with orboto_download_backup once orboto_list_backups shows it as success.`);
+    }
+    throw err;
+}
 export const createFullBackupToolConfig = {
     title: 'Create + download a full workspace backup',
-    description: 'Create an on-demand FULL workspace backup (database + storage) and return it as a base64 resource attachment - one call; a background run this tool polls, minutes on a large workspace. Rows and file references share one snapshot; a missing file fails the run, never a partial archive. With backup encryption on the attachment is the sealed archive, not a ZIP. Requires admin:backup:export; scheduled jobs use orboto_trigger_backup.',
+    description: 'Create an on-demand FULL workspace backup (database + storage) and return it as a base64 resource attachment - one call; a background run this tool polls, minutes on a large workspace. Rows and file references share one snapshot; a missing file fails the run, never a partial archive. With backup encryption on the attachment is the sealed archive, not a ZIP. While another full export runs it starts nothing and names that run. Requires admin:backup:export; scheduled jobs use orboto_trigger_backup.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeCreateFullBackupHandler(client) {
     return async () => {
-        const { runId, sealed } = await client.post('/admin/backup/full', {});
+        const { runId, sealed } = await client.post('/admin/backup/full', {})
+            .catch(rethrowFullExportInProgress);
         const t0 = Date.now();
         for (;;) {
             await new Promise((r) => setTimeout(r, 3000));

package/dist/tools/backup.test.js

@@ -67,6 +67,16 @@ describe('orboto_create_full_backup (ORB-1301 / async since ORB-1717)', () => {
             vi.useRealTimers();
         }
     });
+    it('names the running run instead of starting a second full export (ORB-2562)', async () => {
+        const refusal = { error: 'busy', errorKey: 'errors.backups.full_export_in_progress', errorParams: { runId: '6f0c1a52-3d4e-4b8a-9c71-2e5f8a9b0c1d' } };
+        const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+            ok: false, status: 409, statusText: 'Conflict', headers: new Headers({ 'content-type': 'application/json' }),
+            json: async () => refusal, text: async () => JSON.stringify(refusal),
+        });
+        await expect(makeCreateFullBackupHandler(client)())
+            .rejects.toThrow('A full export is already running (run 6f0c1a52-3d4e-4b8a-9c71-2e5f8a9b0c1d); nothing was started.');
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
     it.each(['disk full', 'Backup source object is missing, unreadable or incomplete'])('a failed run surfaces %s instead of a partial ZIP', async (message) => {
         vi.useFakeTimers();
         const download = vi.spyOn(client, 'getBinary');

package/dist/tools/docs.js

@@ -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). Pass an empty string or omit for a blank page. 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 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).'),
         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.'),

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