@orboto/mcp 0.222.2 → 0.224.0

package/dist/tools/agent-presence-schema.js

@@ -9,6 +9,15 @@ const AgentAccountRefSchema = z.object({ id: z.string().uuid(), name: z.string()
 export const AgentInventoryKindSchema = z.enum(['agent', 'human']);
 export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web', 'channel']);
 export const AgentInventoryConnectionSchema = z.object({ type: AgentConnectionTypeSchema, label: z.string() });
+/** ORB-2584 - mirror of AgentSessionWakeSchema in @orboto/shared-schema agent-session-wake.ts. */
+export const AgentSessionWakeSchema = z.enum(['channel', 'stream', 'lane', 'on_call']);
+/** ORB-2584 - mirror of AGENT_WAKE_LABELS: what presence lines print for each wake. */
+export const AGENT_WAKE_LABELS = {
+    channel: 'reachable by channel',
+    stream: 'reachable by inbox stream',
+    lane: 'reachable as a lane',
+    on_call: 'reads mail only on its own calls',
+};
 export const AgentInventoryProjectSchema = z.object({ id: z.string().uuid(), key: z.string(), name: z.string() });
 export const AgentInventoryEntrySchema = z.object({
     userId: z.string().uuid(),
@@ -25,6 +34,8 @@ export const AgentInventoryEntrySchema = z.object({
     lane: z.object({ id: z.string().uuid(), name: z.string(), role: z.string(), paused: z.boolean() }).nullable(),
     projects: z.array(AgentInventoryProjectSchema),
     connections: z.array(AgentInventoryConnectionSchema),
+    /** ORB-2584 - whether mail wakes the session (channel, stream, lane) or it reads mail only on its own calls (`on_call`). */
+    wake: AgentSessionWakeSchema.optional(),
     workingOnTicket: z.object({ id: z.string().uuid(), key: z.string().nullable(), title: z.string(), projectKey: z.string().nullable() }).nullable(),
     workSessions: z.array(z.object({
         ticketId: z.string().uuid(), ticketKey: z.string().nullable(), role: z.string(), leaseUntil: z.string(),

package/dist/tools/agent-wakes.js

@@ -3,6 +3,7 @@
  * did with it and what it cost.
  */
 import { z } from 'zod';
+import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
 export const agentWakesToolConfig = {
     title: 'Wake ledger',
     description: 'The wake ledger: who woke this account\'s sessions and at what cost. It names the visibility rule that delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
@@ -21,7 +22,8 @@ function statsLine(e) {
     const precision = e.precision === null ? 'unjudged' : `${Math.round(e.precision * 100)}%`;
     const tokens = e.wrongWakeContextTokens > 0 ? `, wrong wakes cost ${e.wrongWakeContextTokens} tokens` : '';
     const backlog = e.backlogSeen > 0 ? `, ${e.backlogSeen} backlog seen` : '';
-    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}${backlog}`;
+    const wake = e.wake ? `, now ${AGENT_WAKE_LABELS[e.wake]}` : '';
+    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}${backlog}${wake}`;
 }
 export function makeAgentWakesHandler(client) {
     return async (args) => {

package/dist/tools/agent-wakes.test.js

@@ -25,6 +25,14 @@ describe('orboto_agent_wakes', () => {
         expect(text).toContain('- worker (ef56ab78): 1 wakes, precision unjudged, median ? ms, top rule -');
         expect(text).toContain('Senders:\n- (none)');
     });
+    it('ORB-2584 - names how mail reaches each session now', async () => {
+        const { client } = clientReturning({
+            hours: 24,
+            sessions: [{ label: 'coordinator (aa11bb22)', wakes: 2, precision: null, medianLatencyMs: null, topRule: null, wrongWakeContextTokens: 0, backlogSeen: 0, wake: 'on_call' }],
+            senders: [],
+        });
+        expect(textOf(await makeAgentWakesHandler(client)({ stats: true }))).toContain('- coordinator (aa11bb22): 2 wakes, precision unjudged, median ? ms, top rule -, now reads mail only on its own calls');
+    });
     it('says so when nothing woke anyone', async () => {
         const { client } = clientReturning({ hours: 24, sessions: [], senders: [] });
         expect(textOf(await makeAgentWakesHandler(client)({ stats: true }))).toContain('- (no wakes)');

package/dist/tools/agent-who.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { AgentSessionRoleSchema } from './agent-session-scope.js';
 import { ownerLine } from './responsibilities.js';
 import { originText } from './agent-coordination.js';
+import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
 export const agentWhoToolConfig = {
     title: 'Who receives agent mail',
     description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. Each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it).',
@@ -18,7 +19,8 @@ export const agentWhoToolConfig = {
 /** One directory row as a line: address, account, session, projects, channel, ticket. */
 export function whoLine(s) {
     const address = s.addresses.join(', ') || (s.role ? `${s.role} (no project)` : 'no scope');
-    const channel = s.channel.announced ? `${s.channel.announced}${s.channel.online ? ' online' : ' offline'}` : 'no channel';
+    const announced = s.channel.announced ? `${s.channel.announced}${s.channel.online ? ' online' : ' offline'}` : 'no channel';
+    const channel = s.wake === 'channel' || !s.wake ? announced : AGENT_WAKE_LABELS[s.wake];
     const ticket = s.currentTicket ? `; on ${s.currentTicket.key ?? s.currentTicket.title}` : '';
     const host = s.origin ? originText(s) : s.host ? `, host ${s.host}` : '';
     const shared = s.sharedAddresses?.length ? `; also held by another live session: ${s.sharedAddresses.join(', ')}` : '';

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 },
@@ -201,7 +220,10 @@ export function makeSessionStartHandler(client, opts = {}) {
                 },
             };
         }
-        const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt } : null);
+        const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? {
+            sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt,
+            wake: r.wake, scopeExpired: r.scopeExpired ?? null, notes: Array.isArray(r.notes) ? r.notes.filter((n) => typeof n === 'string') : [],
+        } : null);
         const host = localSessionHost(extra);
         let registration = await client.post('/v1/agent/heartbeat', { ...(input.scope !== undefined ? { scope: input.scope } : {}), ...(host ? { clientInfo: { host } } : {}) }, { instanceToken })
             .then(toRegistration)
@@ -211,7 +233,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 +247,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 +281,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 +300,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.');
@@ -316,6 +346,8 @@ export function makeSessionStartHandler(client, opts = {}) {
             lines.push(`Address form: peers reach this session and every other ${registration.scope.role} of the project with orboto_agent_notify { to: "${roleAddresses[0]}" } (${roleAddresses.join(', ')}); address a role, never a session id copied from a log.`);
         if (registration?.scope)
             lines.push(identityLine(registration));
+        for (const note of registration?.notes ?? [])
+            lines.push(note);
         if (opts.channel)
             lines.push('', ...channelStartLines());
         if (pendingMessages.length > 0) {
@@ -336,7 +368,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) => ({
@@ -350,6 +382,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                 session: {
                     ref: instanceToken, id: registration?.sessionId ?? null, scope: registration?.scope ?? null,
                     reconnects: registration?.reconnects ?? 0, reconnectedAt: registration?.lastReconnectAt ?? null,
+                    ...(registration?.wake ? { wake: registration.wake } : {}), scopeExpired: registration?.scopeExpired ?? null,
                 },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections
@@ -358,12 +391,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;
     };
 }