@orboto/mcp 0.181.1 → 0.182.0

package/dist/orboto-client.js

@@ -107,8 +107,8 @@ export class OrbotoClient {
         return res;
     }
     /** GET a JSON endpoint. Throws `OrbotoApiError` on non-2xx. */
-    async get(path) {
-        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET' });
+    async get(path, options = {}) {
+        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET', signal: options.signal });
         return (await res.json());
     }
     /** POST a JSON body. */

package/dist/required-rules-wrapper.test.js

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { cp, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+const cleanup = [];
+afterEach(async () => { for (const fn of cleanup.splice(0).reverse())
+    await fn(); });
+async function fixture() {
+    const dir = await mkdtemp(join(tmpdir(), 'orboto-rules-wrapper-'));
+    cleanup.push(() => rm(dir, { recursive: true, force: true }));
+    await mkdir(join(dir, 'skills/orboto'), { recursive: true });
+    await cp(join(root, 'skills/orboto/scripts'), join(dir, 'skills/orboto/scripts'), { recursive: true });
+    const cache = join(dir, 'skills/orboto/.rules-hash');
+    await writeFile(cache, 'keep-hash\n');
+    let rules = '{}', next = '{}', status = 200, ruleReads = 0;
+    const server = createServer((req, res) => {
+        res.setHeader('Content-Type', 'application/json');
+        if (req.url?.startsWith('/agent-instructions')) {
+            ruleReads++;
+            res.statusCode = status;
+            res.end(rules);
+        }
+        else if (req.url?.startsWith('/work-sessions/next'))
+            res.end(next);
+        else if (req.url?.startsWith('/users/me/assigned-tickets'))
+            res.end('{"items":[]}');
+        else if (req.url?.startsWith('/users/me'))
+            res.end('{"id":"me","email":"fixture@example.test"}');
+        else
+            res.end('null');
+    });
+    await new Promise((ok) => server.listen(0, '127.0.0.1', ok));
+    cleanup.push(() => new Promise((ok, no) => server.close((err) => err ? no(err) : ok())));
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('fixture address missing');
+    const origin = `http://127.0.0.1:${address.port}`;
+    const guard = join(dir, 'fixture-network.mjs');
+    await writeFile(guard, `const original = globalThis.fetch; globalThis.fetch = (input, init) => { if (new URL(input).origin !== ${JSON.stringify(origin)}) throw new Error('Fixture refused a nonlocal request'); return original(input, init); };`);
+    const run = (args = ['session-start', '--force-rules']) => new Promise((ok, no) => {
+        const child = spawn(process.execPath, ['--import', guard, join(dir, 'skills/orboto/scripts/orboto.mjs'), ...args], {
+            cwd: dir, env: { ...process.env, ORBOTO_PROFILE: '', ORBOTO_BASE_URL: `http://127.0.0.1:${address.port}`, ORBOTO_TOKEN: 'orb_fixture', ORBOTO_DAEMON: '', ORBOTO_AGENT_SESSION: 'fixture' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let out = '', err = '';
+        child.stdout.on('data', (chunk) => { out += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { err += chunk.toString(); });
+        child.on('error', no);
+        child.on('close', (code) => ok({ code, out, err }));
+    });
+    return { run, cache, ruleReads: () => ruleReads, set: (body, code = 200) => { rules = body; status = code; }, setNext: (body) => { next = body; } };
+}
+describe('wrapper required rules through the real CLI', () => {
+    it('does not turn malformed work-next responses into an idle result', async () => {
+        const f = await fixture();
+        for (const body of ['{}', 'null', '[]', '{"reserved":null}', '{"reserved":""}', '<html>unavailable</html>']) {
+            f.setNext(body);
+            const result = await f.run(['work-next', 'ORB']);
+            expect(result.code).toBe(1);
+            expect(result.out).not.toContain('Nothing ready');
+            expect(await readFile(f.cache, 'utf8')).toBe('keep-hash\n');
+        }
+        f.setNext('{"reserved":null,"reason":"none-matching","retryAfterSeconds":null,"earliestFreeAt":null,"candidatesConsidered":0,"landedIdle":[]}');
+        expect((await f.run(['work-next', 'ORB'])).code).toBe(3);
+        f.setNext(JSON.stringify({ reserved: {
+                session: { id: 'session', role: 'implementation', leaseUntil: 'later' },
+                ticket: { ticketKey: 'ORB-42', title: 'fixture' }, reused: true,
+                rulesHash: 'keep-hash', rulesUnchanged: true,
+                primer: { markdown: '', totalTokens: 0 }, checklists: [], dependencies: { blocks: [], blockedBy: [] }, gitHealth: [], siblingSessions: [],
+            }, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle: [] }));
+        const ack = await f.run(['work-next', 'ORB']);
+        expect(ack.code).toBe(0);
+        expect(ack.out).toContain('not currently in your context');
+        expect(ack.out).toContain('session-start --force-rules');
+        expect(ack.out).not.toContain('keep following what you already loaded');
+    });
+    it('does not silently omit an explicitly requested init rules snapshot', async () => {
+        const f = await fixture();
+        f.set('{}');
+        const result = await f.run(['init', '--with-rules']);
+        expect(result.code).toBe(1);
+        expect(result.err).toContain('Required agent rules');
+        expect(f.ruleReads()).toBe(1);
+    });
+    it('fails closed without poisoning the cache, then recovers with a valid empty ruleset', async () => {
+        const f = await fixture();
+        for (const body of ['{}', 'null', '[]', '{"instructions":', '<html>secret-token</html>', '{"instructions":"","rulesHash":null}', '{"rulesHash":"keep-hash","rulesUnchanged":true}']) {
+            f.set(body);
+            const result = await f.run();
+            expect(result.code).toBe(1);
+            expect(result.out).not.toContain('no workspace rules');
+            expect(result.err).toContain('Required agent rules');
+            expect(result.err).not.toContain('secret-token');
+            expect(await readFile(f.cache, 'utf8')).toBe('keep-hash\n');
+        }
+        for (const status of [401, 403, 500, 503]) {
+            f.set('{"error":"secret-token"}', status);
+            const result = await f.run();
+            expect(result.code).toBe(1);
+            expect(result.err).toContain(`HTTP ${status}`);
+            expect(result.err).not.toContain('secret-token');
+        }
+        f.set('{"instructions":"","rulesHash":"empty","requireSessionStart":true}');
+        const result = await f.run();
+        expect(result.code).toBe(0);
+        expect(result.out).toContain('no workspace rules configured');
+        expect((await readFile(f.cache, 'utf8')).trim()).toBe('empty');
+    });
+});

package/dist/required-rules.js

@@ -0,0 +1,92 @@
+import { OrbotoApiError } from './orboto-client.js';
+/** Fixed diagnostics only: neither rule text nor upstream bodies belong in logs. */
+export class RequiredRulesError extends Error {
+    reason;
+    status;
+    errorKey = 'errors.agent_rules.unavailable';
+    constructor(reason, status) {
+        super(`Required agent rules could not be loaded (${reason}${status ? ` ${status}` : ''}). Do not proceed without the rules. Check connectivity and authentication, then retry session-start with forceRules.`);
+        this.reason = reason;
+        this.status = status;
+        this.name = 'RequiredRulesError';
+    }
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Validate receipts before caching their hash or claiming delivery succeeded. */
+export function validateRulesReceipt(value, knownHash, textField = 'instructions') {
+    if (!record(value) || typeof value.rulesHash !== 'string' || !value.rulesHash
+        || ('rulesUnchanged' in value && typeof value.rulesUnchanged !== 'boolean')) {
+        throw new RequiredRulesError('invalid_response');
+    }
+    if (value.rulesUnchanged === true) {
+        if (!knownHash || value.rulesHash !== knownHash)
+            throw new RequiredRulesError('unbound_ack');
+    }
+    else if (typeof value[textField] !== 'string') {
+        throw new RequiredRulesError('invalid_response');
+    }
+    if (('requireSessionStart' in value && typeof value.requireSessionStart !== 'boolean')
+        || ('rulesChars' in value && (!Number.isInteger(value.rulesChars) || Number(value.rulesChars) < 0))
+        || ('rulesIndex' in value && (!Array.isArray(value.rulesIndex) || value.rulesIndex.some((row) => !record(row)
+            || typeof row.title !== 'string' || !Number.isInteger(row.chars) || Number(row.chars) < 0)))) {
+        throw new RequiredRulesError('invalid_response');
+    }
+}
+export function validateNextWorkEnvelope(value, peek = false) {
+    const integer = (n) => Number.isInteger(n) && Number(n) >= 0;
+    const candidate = record(value) ? value.candidate : undefined;
+    const hasCandidate = candidate !== undefined && candidate !== null;
+    if (!record(value) || !('reserved' in value) || (value.reserved !== null && !record(value.reserved))
+        || (peek && value.reserved !== null)
+        || (hasCandidate && (!peek || value.reserved !== null || value.reason !== null
+            || !record(candidate) || typeof candidate.ticketId !== 'string' || !candidate.ticketId
+            || (candidate.ticketKey !== null && typeof candidate.ticketKey !== 'string')
+            || typeof candidate.title !== 'string' || (candidate.priority !== null && typeof candidate.priority !== 'string')))
+        || (value.reserved === null
+            ? !hasCandidate && (typeof value.reason !== 'string' || !['all-blocked', 'all-leased', 'none-matching', 'autonomy_paused', 'lane_paused', 'lane_limit_reached'].includes(value.reason))
+            : value.reason !== null)
+        || !integer(value.candidatesConsidered)
+        || (value.retryAfterSeconds !== null && !integer(value.retryAfterSeconds))
+        || (value.earliestFreeAt !== null && typeof value.earliestFreeAt !== 'string')
+        || !Array.isArray(value.landedIdle)
+        || value.landedIdle.some((row) => !record(row) || typeof row.ticketId !== 'string' || !row.ticketId
+            || (row.ticketKey !== null && typeof row.ticketKey !== 'string') || typeof row.title !== 'string'
+            || typeof row.lastActivityAt !== 'string' || !integer(row.idleWorkingDays) || !integer(row.commitCount))) {
+        throw new RequiredRulesError('invalid_response');
+    }
+}
+/** One bounded, required read shared by session-start, resources and connect. */
+export async function loadRequiredRules(client, path, knownHash) {
+    let value;
+    const controller = new AbortController();
+    let deadline;
+    const timeout = new Promise((_resolve, reject) => {
+        deadline = setTimeout(() => {
+            controller.abort();
+            reject(new RequiredRulesError('timeout'));
+        }, 10_000);
+    });
+    try {
+        // Race the whole operation: OAuth token/keychain acquisition can stall
+        // before fetch starts and therefore cannot observe fetch's abort signal.
+        value = await Promise.race([client.get(path, { signal: controller.signal }), timeout]);
+    }
+    catch (error) {
+        if (error instanceof RequiredRulesError)
+            throw error;
+        if (error instanceof OrbotoApiError)
+            throw new RequiredRulesError('http', error.status);
+        if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError'))
+            throw new RequiredRulesError('timeout');
+        if (error instanceof SyntaxError)
+            throw new RequiredRulesError('invalid_response');
+        throw new RequiredRulesError('transport');
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+    validateRulesReceipt(value, knownHash);
+    return value;
+}

package/dist/required-rules.test.js

@@ -0,0 +1,110 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from './orboto-client.js';
+import { loadRequiredRules, RequiredRulesError, validateRulesReceipt } from './required-rules.js';
+import { makeSessionStartHandler } from './tools/session-start.js';
+import { makeWorkNextHandler } from './tools/work-sessions.js';
+import { createNudgeState, SESSION_START_TOOL } from './session-nudge.js';
+import { withMetrics } from './with-metrics.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const makeClient = () => new OrbotoClient({ baseUrl: 'https://fixture.invalid', apiKey: 'orb_fixture' });
+const full = { instructions: '  exact rules\n', rulesHash: 'hash', requireSessionStart: true };
+describe('required rule delivery', () => {
+    it.each([null, {}, [], { reserved: null }, { reserved: '' }, { reserved: null, reason: ['none-matching'] }])('does not turn an incomplete dispatch response into idle %#', async (body) => {
+        const client = makeClient();
+        vi.spyOn(client, 'post').mockResolvedValue(body);
+        await expect(makeWorkNextHandler(client)({ projectKey: 'ORB' })).rejects.toBeInstanceOf(RequiredRulesError);
+    });
+    it.each([null, [], {}, 'HTML secret', { rulesHash: 'hash' }, { instructions: '' },
+        { instructions: null, rulesHash: 'hash' }, { ...full, rulesUnchanged: null },
+        { ...full, rulesIndex: [{}] }, { ...full, rulesChars: -1 }, { ...full, requireSessionStart: 'false' },
+    ])('rejects incomplete successful response %# without leaking it', async (body) => {
+        const client = makeClient();
+        vi.spyOn(client, 'get').mockResolvedValue(body);
+        await expect(loadRequiredRules(client, '/agent-instructions')).rejects.toMatchObject({ reason: 'invalid_response' });
+    });
+    it.each([new Error('orb_secret network detail'), new DOMException('secret', 'TimeoutError'),
+        new SyntaxError('secret invalid JSON'), ...[401, 403, 500, 503].map((s) => new OrbotoApiError(s, 'secret body', 'https://secret.invalid')),
+    ])('reports transport/auth/server failures safely %#', async (failure) => {
+        const client = makeClient();
+        vi.spyOn(client, 'get').mockRejectedValue(failure);
+        const error = await loadRequiredRules(client, '/agent-instructions').catch((e) => e);
+        expect(error).toBeInstanceOf(RequiredRulesError);
+        expect(String(error)).not.toContain('secret');
+        expect(String(error).length).toBeLessThan(512);
+    });
+    it('preserves exact full text, valid empty rules and bound acknowledgements', async () => {
+        const client = makeClient();
+        const get = vi.spyOn(client, 'get').mockResolvedValueOnce(full).mockResolvedValueOnce({ ...full, instructions: '' });
+        expect(await loadRequiredRules(client, '/agent-instructions')).toEqual(full);
+        expect((await loadRequiredRules(client, '/agent-instructions')).instructions).toBe('');
+        expect(get.mock.calls[0][1]?.signal).toBeInstanceOf(AbortSignal);
+        expect(() => validateRulesReceipt({ rulesHash: 'hash', rulesUnchanged: true }, 'hash')).not.toThrow();
+        expect(() => validateRulesReceipt({ rulesHash: 'hash', rulesUnchanged: true })).toThrow(RequiredRulesError);
+        expect(() => validateRulesReceipt({ rulesHash: 'other', rulesUnchanged: true }, 'hash')).toThrow(RequiredRulesError);
+    });
+    it.each([false, true])('failed session-start rulesOnly=%s stays gated and recovery succeeds without a poisoned ack', async (rulesOnly) => {
+        const client = makeClient();
+        let broken = true;
+        const paths = [];
+        vi.spyOn(client, 'post').mockResolvedValue({});
+        vi.spyOn(client, 'get').mockImplementation(async (path) => {
+            if (path.startsWith('/agent-instructions')) {
+                paths.push(path);
+                if (broken)
+                    throw new Error('secret transport');
+                return full;
+            }
+            if (path.includes('assigned-tickets'))
+                return { items: [] };
+            if (path.includes('/messages'))
+                return { messages: [] };
+            return null;
+        });
+        const state = createNudgeState(true);
+        const session = withMetrics(client, SESSION_START_TOOL, undefined, makeSessionStartHandler(client), state);
+        const write = vi.fn(async () => ({ content: [] }));
+        const other = withMetrics(client, 'orboto_create_ticket', undefined, write, state);
+        const failed = await session({ rulesOnly, forceRules: true });
+        expect(failed.isError).toBe(true);
+        expect(failed.structuredContent).toMatchObject({ errorKey: 'errors.agent_rules.unavailable' });
+        expect(state.sessionStartRan).toBe(false);
+        expect((await other({})).isError).toBe(true);
+        expect(write).not.toHaveBeenCalled();
+        broken = false;
+        expect((await session({ rulesOnly, forceRules: true })).isError).not.toBe(true);
+        expect(state.sessionStartRan).toBe(true);
+        await other({});
+        expect(write).toHaveBeenCalledOnce();
+        expect(paths.every((path) => !path.includes('knownRulesHash'))).toBe(true);
+        broken = true;
+        expect((await session({ rulesOnly, forceRules: true })).isError).toBe(true);
+        expect(state.sessionStartRan).toBe(false);
+    });
+    it.each(['token', 'refresh', 'fetch'])('bounds the complete operation including a stalled %s', async (stage) => {
+        vi.useFakeTimers();
+        try {
+            const never = () => new Promise(() => { });
+            const client = new OrbotoClient({ baseUrl: 'https://fixture.invalid', tokenProvider: {
+                    getAccessToken: stage === 'token' ? never : async () => 'fixture',
+                    forceRefresh: never,
+                } });
+            let signal;
+            const fetch = vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                signal = init?.signal;
+                if (stage === 'refresh')
+                    return new Response('', { status: 401 });
+                return new Promise(() => { });
+            });
+            const rejected = expect(loadRequiredRules(client, '/agent-instructions')).rejects.toMatchObject({ reason: 'timeout' });
+            await vi.advanceTimersByTimeAsync(10_000);
+            await rejected;
+            if (stage === 'token')
+                expect(fetch).not.toHaveBeenCalled();
+            else
+                expect(signal?.aborted).toBe(true);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});

package/dist/resources.js

@@ -26,6 +26,7 @@
  */
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { OrbotoApiError } from './orboto-client.js';
+import { loadRequiredRules } from './required-rules.js';
 import { resolveProjectByKey, resolveTicketByKey } from './tools/shared.js';
 export function registerOrbotoResources(server, client) {
     // -------------------------------------------------------------------------
@@ -41,8 +42,8 @@ export function registerOrbotoResources(server, client) {
         description: 'The complete, assembled binding rules you must follow as an agent in this workspace - cap-independent (the MCP instructions block may be truncated; this resource is not). orboto_session_start returns the same rules plus your in-progress work.',
         mimeType: 'text/markdown',
     }, async (uri) => {
-        const res = await client.get('/agent-instructions').catch(() => ({ instructions: '' }));
-        const rules = res?.instructions?.trim() || '(no workspace rules configured)';
+        const res = await loadRequiredRules(client, '/agent-instructions');
+        const rules = res.instructions || '(no workspace rules configured)';
         return {
             contents: [{ uri: uri.href, mimeType: 'text/markdown', text: `# orboto workspace agent rules\n\n${rules}` }],
         };

package/dist/resources.test.js

@@ -171,8 +171,18 @@ describe('orboto:// search resource', () => {
     });
 });
 describe('orboto:// rules resource (ORB-1177)', () => {
+    it.each([null, {}, [], { instructions: '' }])('refuses unavailable or malformed rules %#', async (body) => {
+        stub([{ json: body }]);
+        const handler = getTemplateHandler(buildServerWithResources(), 'rules');
+        await expect(handler(new URL('orboto://rules'), {})).rejects.toThrow('Required agent rules');
+    });
+    it('refuses a failed fetch instead of returning an empty placeholder', async () => {
+        stub([{ ok: false, status: 503 }]);
+        const handler = getTemplateHandler(buildServerWithResources(), 'rules');
+        await expect(handler(new URL('orboto://rules'), {})).rejects.toThrow('Required agent rules');
+    });
     it('returns the complete assembled workspace rules', async () => {
-        stub([{ json: { instructions: 'RULE 1: ticket-first.\nRULE 2: one commit per ticket.' } }]);
+        stub([{ json: { instructions: 'RULE 1: ticket-first.\nRULE 2: one commit per ticket.', rulesHash: 'fixture' } }]);
         const server = buildServerWithResources();
         const handler = getTemplateHandler(server, 'rules');
         const out = await handler(new URL('orboto://rules'), {});
@@ -182,7 +192,7 @@ describe('orboto:// rules resource (ORB-1177)', () => {
         expect(text).toContain('RULE 2: one commit per ticket.');
     });
     it('degrades to a placeholder when no rules are configured', async () => {
-        stub([{ json: { instructions: '' } }]);
+        stub([{ json: { instructions: '', rulesHash: 'empty' } }]);
         const server = buildServerWithResources();
         const handler = getTemplateHandler(server, 'rules');
         const out = await handler(new URL('orboto://rules'), {});

package/dist/server.js

@@ -26,6 +26,7 @@ import { aiStatusToolConfig, makeAiStatusHandler } from './tools/ai-status.js';
 import { embeddingStatusToolConfig, makeEmbeddingStatusHandler } from './tools/embedding-status.js';
 import { aiUsageToolConfig, makeAiUsageHandler } from './tools/ai-usage.js';
 import { sessionStartToolConfig, makeSessionStartHandler } from './tools/session-start.js';
+import { loadRequiredRules } from './required-rules.js';
 import { responseExpandToolConfig, makeResponseExpandHandler } from './tools/response-expand.js';
 import { helpToolConfig, makeHelpHandler } from './tools/help.js';
 import { apiSearchToolConfig, makeApiSearchHandler } from './tools/api-search.js';
@@ -171,14 +172,13 @@ export async function buildOrbotoMcpServer(opts) {
     // ORB-1090 - fetch the workspace's configurable working-rules at
     // connect so admin edits propagate to every new MCP session. The
     // instructions block is the one place every MCP client reliably sees
-    // the rules (clients don't read the repo's CLAUDE.md). Best-effort:
-    // fall back to the built-in rules if the instance predates ORB-1086
-    // or the fetch fails.
+    // the rules (clients don't read the repo's CLAUDE.md). If unavailable,
+    // keep the connection usable for recovery but gate all other tools.
     let workingRules = FALLBACK_WORKING_RULES;
     // ORB-1471 - the same connect-time fetch also reports whether this
     // workspace requires `orboto_session_start` before any other tool call
-    // (the hard gate). Default off; a fetch failure keeps it off.
-    let requireSessionStart = false;
+    // (the hard gate). Unknown policy must never silently disable the gate.
+    let requireSessionStart = true;
     try {
         // ORB-1753 - stdio deployments can declare their profile via
         // ORBOTO_AGENT_KIND / ORBOTO_MODEL_TIER; api-key standing profiles
@@ -186,13 +186,13 @@ export async function buildOrbotoMcpServer(opts) {
         const connectParams = new URLSearchParams();
         applyAgentProfile(connectParams);
         const connectQs = connectParams.toString();
-        const res = await client.get(`/agent-instructions${connectQs ? `?${connectQs}` : ''}`);
+        const res = await loadRequiredRules(client, `/agent-instructions${connectQs ? `?${connectQs}` : ''}`);
         if (res?.instructions?.trim())
             workingRules = res.instructions.trim();
-        requireSessionStart = res?.requireSessionStart === true;
+        requireSessionStart = res.requireSessionStart ?? true;
     }
     catch {
-        // keep the fallback
+        workingRules = 'Workspace rules are unavailable. Built-in hints are not a substitute. Call orboto_session_start with forceRules and retry after connectivity or authentication recovers.';
     }
     const server = new McpServer({ name: 'orboto', version: VERSION }, {
         // ORB-940 - advertise resources/subscribe so MCP-aware clients

package/dist/session-nudge.js

@@ -49,29 +49,32 @@ export const SESSION_START_GATE_MESSAGE = 'This workspace requires you to load i
     'other action. Call `orboto_session_start` now - it returns the rules you ' +
     'must follow plus your in-progress work - then retry this call.';
 /**
- * ORB-1471 - advance the gate state for one dispatch and report whether this
+ * Advance the gate state for one dispatch and report whether this
  * dispatch must be REFUSED (returned an instructive error without running the
  * handler).
  *
  * Semantics when the gate is enabled: every tool call other than
  * `orboto_session_start` is refused until `orboto_session_start` has run once
- * this session. Calling `orboto_session_start` marks the session unlocked
+ * this session. A rule refresh locks the session until its result succeeds
  * (and is itself never gated). When the gate is disabled, nothing is ever
  * refused (returns false) - default behaviour is unchanged.
  *
- * Idempotent bookkeeping: running `orboto_session_start` flips
- * `sessionStartRan` so all later calls pass.
+ * The metrics wrapper records successful completion separately; dispatch
+ * alone is not evidence of rule delivery.
  */
 export function shouldGate(state, toolName) {
     if (toolName === SESSION_START_TOOL) {
-        // The rule-loading tool always runs, and running it unlocks the session.
-        state.sessionStartRan = true;
+        state.sessionStartRan = false;
         return false;
     }
     if (!state.gateEnabled)
         return false;
     return !state.sessionStartRan;
 }
+export function recordSessionStartResult(state, toolName, success) {
+    if (toolName === SESSION_START_TOOL)
+        state.sessionStartRan = success;
+}
 /** ORB-1471 - the instructive refusal result the gate returns. */
 export function gateResult() {
     return {

package/dist/session-nudge.test.js

@@ -6,7 +6,7 @@
  * call is orboto_session_start, and never mutate structuredContent.
  */
 import { describe, it, expect } from 'vitest';
-import { SESSION_START_TOOL, SESSION_START_NUDGE, SESSION_START_GATE_MESSAGE, createNudgeState, shouldNudge, shouldGate, gateResult, prependNudge, } from './session-nudge.js';
+import { SESSION_START_TOOL, SESSION_START_NUDGE, SESSION_START_GATE_MESSAGE, createNudgeState, shouldNudge, shouldGate, recordSessionStartResult, gateResult, prependNudge, } from './session-nudge.js';
 describe('shouldNudge (ORB-1331)', () => {
     it('nudges on the first tool call when it is not session_start, then never again', () => {
         const state = createNudgeState();
@@ -44,15 +44,20 @@ describe('shouldGate (ORB-1471)', () => {
         // Pre session_start: every other tool is gated.
         expect(shouldGate(state, 'orboto_list_projects')).toBe(true);
         expect(shouldGate(state, 'orboto_create_ticket')).toBe(true);
-        // session_start itself is never gated AND unlocks the session.
+        // Dispatch is not proof of delivery; only successful completion unlocks.
         expect(shouldGate(state, SESSION_START_TOOL)).toBe(false);
+        expect(shouldGate(state, 'orboto_list_projects')).toBe(true);
+        recordSessionStartResult(state, SESSION_START_TOOL, true);
         // Post session_start: everything passes.
         expect(shouldGate(state, 'orboto_list_projects')).toBe(false);
         expect(shouldGate(state, 'orboto_create_ticket')).toBe(false);
     });
-    it('session_start as the very first call unlocks immediately (one-call cost avoided)', () => {
+    it('a failed refresh keeps the gate closed and a successful retry unlocks', () => {
         const state = createNudgeState(true);
         expect(shouldGate(state, SESSION_START_TOOL)).toBe(false);
+        recordSessionStartResult(state, SESSION_START_TOOL, false);
+        expect(shouldGate(state, 'orboto_get_ticket')).toBe(true);
+        recordSessionStartResult(state, SESSION_START_TOOL, true);
         expect(shouldGate(state, 'orboto_get_ticket')).toBe(false);
     });
     it('gateResult is an instructive isError result pointing at session_start', () => {

package/dist/session-nudge.transport.test.js

@@ -24,14 +24,14 @@ import { SESSION_START_NUDGE } from './session-nudge.js';
 // Every API call the tools make resolves to a benign empty payload so
 // the handlers succeed without a live backend. list_projects → [] →
 // "no projects" text + valid structuredContent; session_start's sub-
-// calls are all .catch-guarded so [] is harmless.
+// rules read is required and carries an explicit valid empty ruleset.
 function mockApi() {
-    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => ({
         ok: true,
         status: 200,
         statusText: 'OK',
         headers: new Headers({ 'content-type': 'application/json' }),
-        json: async () => [],
+        json: async () => String(url).includes('/agent-instructions') ? { instructions: '', rulesHash: 'empty', requireSessionStart: false } : [],
         text: async () => '[]',
     }));
 }
@@ -54,6 +54,24 @@ function firstText(res) {
     return content[0]?.text ?? '';
 }
 describe('ORB-1331 - HTTP transport (per-session nudge)', () => {
+    it('keeps an unavailable connect policy gated until rules are loaded successfully', async () => {
+        vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('secret offline'));
+        const client = await connectSession();
+        try {
+            const blocked = await client.callTool({ name: 'orboto_list_projects', arguments: {} });
+            expect(blocked.isError).toBe(true);
+            const failed = await client.callTool({ name: 'orboto_session_start', arguments: { rulesOnly: true } });
+            expect(failed.isError).toBe(true);
+            expect(firstText(failed)).not.toContain('secret');
+            mockApi();
+            const recovered = await client.callTool({ name: 'orboto_session_start', arguments: { rulesOnly: true } });
+            expect(recovered.isError).not.toBe(true);
+            expect((await client.callTool({ name: 'orboto_list_projects', arguments: {} })).isError).not.toBe(true);
+        }
+        finally {
+            await client.close();
+        }
+    });
     it('prepends the nudge exactly once when the first call is orboto_list_projects; the second call is clean', async () => {
         const client = await connectSession();
         const first = await client.callTool({ name: 'orboto_list_projects', arguments: {} });

package/dist/tool-annotations.test.js

@@ -41,6 +41,12 @@ import { buildOrbotoMcpServer } from './server.js';
  *  also just good UI hygiene - a title that long is a description. */
 const TITLE_MAX = 64;
 let tools;
+function unsafeTakeoverTools(list) {
+    return list
+        .filter((tool) => Object.prototype.hasOwnProperty.call(tool.inputSchema?.properties ?? {}, 'takeover'))
+        .filter((tool) => tool.annotations?.readOnlyHint !== false || tool.annotations?.destructiveHint !== true)
+        .map((tool) => tool.name);
+}
 beforeAll(async () => {
     // Port 1 is never listened on -> the connect-time /agent-instructions
     // fetch fails immediately and the server falls back to its built-in
@@ -84,6 +90,22 @@ describe('MCP tool safety annotations (ORB-1669)', () => {
             .map((t) => t.name);
         expect(offenders, `Contradictory annotations on: ${offenders.join(', ')}`).toEqual([]);
     });
+    it('every takeover-capable tool is a destructive write for all argument combinations', () => {
+        const capable = tools.filter((tool) => Object.prototype.hasOwnProperty.call(tool.inputSchema?.properties ?? {}, 'takeover'));
+        // Pin the actual siblings so losing schema discovery cannot pass vacuously.
+        expect(capable.map((tool) => tool.name)).toEqual(expect.arrayContaining(['orboto_work_start', 'orboto_work_session_start']));
+        expect(unsafeTakeoverTools(tools)).toEqual([]);
+        // Reservation without a takeover path is not an account-state takeover.
+        expect(tools.find((tool) => tool.name === 'orboto_work_next')?.annotations).toMatchObject({ readOnlyHint: false, destructiveHint: false });
+    });
+    it('the takeover ratchet catches missing, false and contradictory hints on future tools', () => {
+        const future = { name: 'future_takeover', inputSchema: { properties: { takeover: { type: 'boolean' } } } };
+        for (const annotations of [undefined, { readOnlyHint: false }, { readOnlyHint: false, destructiveHint: false }, { readOnlyHint: true, destructiveHint: true }]) {
+            expect(unsafeTakeoverTools([{ ...future, annotations }])).toEqual(['future_takeover']);
+        }
+        expect(unsafeTakeoverTools([{ ...future, annotations: { readOnlyHint: false, destructiveHint: true } }])).toEqual([]);
+        expect(unsafeTakeoverTools([{ name: 'ordinary_read', annotations: { readOnlyHint: true } }])).toEqual([]);
+    });
     it(`every tool has a human-readable title of at most ${TITLE_MAX} characters`, () => {
         const missing = tools.filter((t) => !(t.title ?? t.annotations?.title)).map((t) => t.name);
         expect(missing, `Tools with no title: ${missing.join(', ')}`).toEqual([]);

package/dist/tool-docs.test.js

@@ -55,6 +55,7 @@ describe('orboto_help handler', () => {
 });
 describe('live manifest vs help registry (no guidance lost)', () => {
     it('every tool in the full manifest has a one-line wire description and full docs behind orboto_help', async () => {
+        vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ instructions: '', rulesHash: 'empty', requireSessionStart: false }), { status: 200 }));
         const server = await buildOrbotoMcpServer({
             baseUrl: 'https://orboto.example.com', apiKey: 'orb_test', toolset: 'full',
         });

package/dist/tools/git-health-reasons.js

@@ -0,0 +1,10 @@
+// Shared rendering vocabulary for session-start and work-session bundles.
+export const GIT_HEALTH_REASON_TEXT = {
+    connection_inactive: 'connection is deactivated',
+    app_installation_suspended: 'GitHub App installation is suspended',
+    oauth_token_expired: 'OAuth token expired with no refresh path',
+    history_backfill_error: 'last history backfill failed',
+    awaiting_first_event: 'webhook installed but has never delivered an event',
+    outbound_unreachable: 'orboto cannot reach the provider',
+    delivery_failing: 'webhook deliveries from the provider are not arriving',
+};

package/dist/tools/session-start.js

@@ -50,6 +50,8 @@
 import { z } from 'zod';
 import { resolveTicketByKey, applyAgentProfile } from './shared.js';
 import { PROTECT_TEXT_META, storePayload } from '../response-budget.js';
+import { loadRequiredRules } from '../required-rules.js';
+import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.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.) Read-only; no side effects. '
@@ -72,18 +74,6 @@ export const sessionStartToolConfig = {
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
-const GIT_HEALTH_REASON_TEXT = {
-    connection_inactive: 'connection is deactivated',
-    app_installation_suspended: 'GitHub App installation is suspended',
-    oauth_token_expired: 'OAuth token expired with no refresh path',
-    history_backfill_error: 'last history backfill failed',
-    // ORB-1638
-    awaiting_first_event: 'webhook installed but has never delivered an event',
-    outbound_unreachable: 'orboto cannot reach the provider',
-    // ORB-1785 - two derivations now: the provider reporting a failed
-    // delivery, and the probe inferring one from commits that never arrived.
-    delivery_failing: 'webhook deliveries from the provider are not arriving',
-};
 // Cap how many distinct projects we probe for git health - a session's
 // in-progress work is capped at 20 tickets already, so this rarely
 // exceeds a handful, but bound it defensively so a pathological account
@@ -241,10 +231,10 @@ export function makeSessionStartHandler(client) {
         // rules from the API instead, costs one call, and skips the whole rest
         // of the digest. Protected in both halves: it IS the rule text.
         if (input.rulesOnly) {
-            const rules = await client.get(rulesPath).catch(() => ({}));
+            const rules = await loadRequiredRules(client, rulesPath);
             if (rules.rulesHash)
                 lastKnownRulesHash = rules.rulesHash;
-            const text = rules.instructions?.trim() ?? '';
+            const text = rules.instructions ?? '';
             return {
                 _meta: { [PROTECT_TEXT_META]: true },
                 content: [{
@@ -267,7 +257,7 @@ export function makeSessionStartHandler(client) {
         }
         const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
             client.get('/users/me').catch(() => null),
-            client.get(rulesPath).catch(() => ({})),
+            loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             // ORB-1330 - a re-orientation briefing must only list OPEN work.
             // Filter to in_progress + in_review so DONE tickets can't pose as
             // "what you're working on" at the moment the agent has the least
@@ -282,8 +272,6 @@ export function makeSessionStartHandler(client) {
                 .catch(() => []),
         ]);
         const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
-        if (rules.rulesHash)
-            lastKnownRulesHash = rules.rulesHash;
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
         // ORB-1605 - git-connection health for every project the caller has
         // open work in right now. Cheap, computed, read-only (see
@@ -326,7 +314,7 @@ export function makeSessionStartHandler(client) {
         //   index  - one line per rule + the hash + a handle; the default.
         //   full   - the text inline (forceRules, or an API too old to send
         //            an index - never leave a caller without its rules).
-        const rulesText = rules.instructions?.trim() ?? '';
+        const rulesText = rules.instructions ?? '';
         const rulesIndex = Array.isArray(rules.rulesIndex)
             ? rules.rulesIndex.map((e) => e?.title).filter((t) => typeof t === 'string' && t.length > 0)
             : [];
@@ -391,7 +379,7 @@ export function makeSessionStartHandler(client) {
         if (bundle)
             lines.push(...bundle.lines);
         lines.push('', 'Re-run this after any context compaction to re-sync.');
-        return {
+        const result = {
             // ORB-1818 - when the full rule text IS the payload, neither half
             // may be cut; see PROTECT_TEXT_META. The index answer carries no
             // rule text and is budgeted like any other response.
@@ -431,5 +419,7 @@ export function makeSessionStartHandler(client) {
                 ...(bundle ? { ticketBundle: bundle.structured } : {}),
             },
         };
+        lastKnownRulesHash = rules.rulesHash;
+        return result;
     };
 }

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

@@ -44,7 +44,7 @@ describe('orboto_session_start (ORB-1093)', () => {
         const calls = stubByPath({
             '/users/me/assigned-tickets': { items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Progress' }] },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev', workspaceLocale: 'en' },
-            '/agent-instructions': { instructions: 'claim -> commit -> close' },
+            '/agent-instructions': { instructions: 'claim -> commit -> close', rulesHash: 'fixture' },
             '/time/timer': { ticketId: 't1', ticketKey: 'ORB-42', startedAt: '2026-06-15T10:00:00Z' },
         });
         const res = await makeSessionStartHandler(client)();
@@ -65,7 +65,7 @@ describe('orboto_session_start (ORB-1093)', () => {
         stubByPath({
             '/users/me/assigned-tickets': { items: [] },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
         });
         const res = await makeSessionStartHandler(client)();
@@ -82,7 +82,7 @@ describe('orboto_session_start (ORB-1093)', () => {
                 items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Review', projectId: 'proj-1' }],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/projects/proj-1/git-health': {
                 connections: [{
@@ -109,7 +109,7 @@ describe('orboto_session_start (ORB-1093)', () => {
                 items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Review', projectId: 'proj-1' }],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/projects/proj-1/git-health': {
                 connections: [{
@@ -298,7 +298,7 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
                 items: [{ ticketKey: 'ORB-42', title: 'Wire it up', statusName: 'In Review', projectId: 'proj-1' }],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/projects/proj-1/git-health': {
                 connections: [{
@@ -332,7 +332,7 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
                 ],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
             '/v1/agent/presence': [],
         });
@@ -355,7 +355,7 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
                 ],
             },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
             '/time/timer': {},
         });
         const res = await makeSessionStartHandler(client)();
@@ -383,7 +383,7 @@ describe('orboto_session_start - a 200 with an unexpected body never kills the d
             '/projects/proj-1/tickets/by-key/42': { id: 'tick-1', projectId: 'proj-1', ticketKey: 'ORB-42', title: 'Bug' },
             '/users/me/assigned-tickets': { items: [] },
             '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
-            '/agent-instructions': { instructions: 'rules here' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
         });
         const res = await makeSessionStartHandler(client)({ ticketKey: 'ORB-42' });
         const text = res.content[0].text;

package/dist/tools/ticket-writes.js

@@ -428,19 +428,20 @@ export function makeDeleteTicketHandler(client) {
     };
 }
 export const commentToolConfig = {
-    title: 'Post a comment on a ticket',
-    description: 'Append a comment. Supports Markdown. `isInternal=true` hides the comment from external/guest users (use for implementation chatter the customer shouldn\'t see).',
+    title: 'Post a comment',
+    description: 'Post Markdown. isInternal=true hides it from guests. Attachment drafts are claimed atomically with the comment; never use public ticket uploads for private comments.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         text: z.string().min(1),
-        isInternal: z.boolean().optional().describe('Default: false (visible to all members + guests).'),
+        isInternal: z.boolean().optional().describe('Default false: guests can read.'),
+        attachmentDraftIds: z.array(z.string().uuid()).max(20).optional().describe('Private /attachment-drafts/tickets/:ticketId uploads only.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeCommentHandler(client) {
-    return async ({ ticketKey, text, isInternal }) => {
+    return async ({ ticketKey, text, isInternal, attachmentDraftIds }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
-        const created = await client.post(`/tickets/${ticket.id}/comments`, { content: text, isInternal: isInternal ?? false });
+        const created = await client.post(`/tickets/${ticket.id}/comments`, { content: text, isInternal: isInternal ?? false, ...(attachmentDraftIds ? { attachmentDraftIds } : {}) });
         return {
             content: [{
                     type: 'text',

package/dist/tools/ticket-writes.test.js

@@ -395,6 +395,12 @@ describe('orboto_delete_ticket', () => {
     });
 });
 describe('orboto_comment', () => {
+    it('forwards private upload claims without dropping the internal flag', async () => {
+        const calls = stub([{ json: PROJ }, { json: TICKET }, { json: { id: 'c1', content: 'private image', isInternal: true, createdAt: 'now' } }]);
+        const ids = ['aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa'];
+        await makeCommentHandler(client)({ ticketKey: 'ACME-1', text: 'private image', isInternal: true, attachmentDraftIds: ids });
+        expect(calls[2].body).toEqual({ content: 'private image', isInternal: true, attachmentDraftIds: ids });
+    });
     it('posts a regular (non-internal) comment by default', async () => {
         const calls = stub([
             { json: PROJ },

package/dist/tools/work-next.js

@@ -6,6 +6,7 @@
  */
 import { z } from 'zod';
 import { mcpInstanceToken } from './shared.js';
+import { validateNextWorkEnvelope, validateRulesReceipt } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT, ResourceClaimShape } from './work-sessions-shared.js';
 /** ORB-1799 - rendered identically on every exit (reserved, empty, paused):
  *  an agent that just pulled fresh work is exactly the one about to forget
@@ -61,6 +62,7 @@ export function makeWorkNextHandler(client) {
             agentSessionToken: token,
             ...(lastKnownRulesHash ? { knownRulesHash: lastKnownRulesHash } : {}),
         });
+        validateNextWorkEnvelope(res, args.peek);
         if (!res.reserved) {
             // ORB-1930 - a peek that found work: name it, reserve nothing.
             if (args.peek && res.candidate) {
@@ -123,8 +125,7 @@ export function makeWorkNextHandler(client) {
             };
         }
         const r = res.reserved;
-        if (r.rulesHash)
-            lastKnownRulesHash = r.rulesHash;
+        validateRulesReceipt(r, lastKnownRulesHash, 'rules');
         const lines = [
             r.reused
                 ? `Renewed your existing ${r.session.role} session on ${r.ticket.ticketKey ?? r.session.ticketId}.`
@@ -138,7 +139,7 @@ export function makeWorkNextHandler(client) {
         }
         lines.push('', '## Working rules');
         if (r.rulesUnchanged) {
-            lines.push(`Unchanged since your last call on this connection (hash ${r.rulesHash}) - keep following what you already loaded.`);
+            lines.push(`Unchanged since your last call on this connection (hash ${r.rulesHash}). If these rules are not currently in your context, call orboto_session_start with rulesOnly: true before proceeding.`);
         }
         else {
             lines.push(r.rules?.trim() || '(no workspace rules configured)');
@@ -179,6 +180,7 @@ export function makeWorkNextHandler(client) {
             ? '(none)'
             : r.siblingSessions.map((s) => `  - [${s.role}] ${s.userFullName ?? s.userEmail ?? 'unknown'} - lease until ${s.leaseUntil}`).join('\n'));
         lines.push(...landedIdleLines(res.landedIdle));
+        lastKnownRulesHash = r.rulesHash;
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {

package/dist/tools/work-sessions-next.test.js

@@ -65,8 +65,31 @@ const RESERVED = {
     siblingSessions: [],
 };
 describe('orboto_work_next', () => {
+    const peekResponse = {
+        reserved: null, reason: null, retryAfterSeconds: null, earliestFreeAt: null,
+        candidatesConsidered: 1, landedIdle: [],
+        candidate: { ticketId: 't1', ticketKey: 'ACME-42', title: 'Ready', priority: null },
+    };
+    it('validates a peek candidate without claiming rules delivery or a reservation', async () => {
+        const calls = stub([{ json: peekResponse }, { json: peekResponse }]);
+        const handler = makeWorkNextHandler(client);
+        const result = await handler({ projectKey: 'ACME', peek: true });
+        expect(result.structuredContent).toMatchObject({ reserved: null, candidate: peekResponse.candidate });
+        expect(calls[0].body).toMatchObject({ peek: true });
+        expect(calls[0].body).not.toHaveProperty('knownRulesHash');
+        await expect(handler({ projectKey: 'ACME' })).rejects.toMatchObject({ reason: 'invalid_response' });
+    });
+    it.each([
+        { candidate: {} }, { candidate: { ticketId: '', ticketKey: null, title: '', priority: null } },
+        { candidate: { ticketId: 't1', title: 'Ready', priority: null } },
+        { candidate: { ticketId: 't1', ticketKey: null, title: 42, priority: null } },
+        { reason: 'none-matching' }, { reserved: RESERVED }, { candidatesConsidered: -1 },
+    ])('rejects malformed or contradictory peek responses %#', async (patch) => {
+        stub([{ json: { ...peekResponse, ...patch } }]);
+        await expect(makeWorkNextHandler(client)({ projectKey: 'ACME', peek: true })).rejects.toMatchObject({ reason: 'invalid_response' });
+    });
     it('reserves the winning candidate and renders the full bundle, sending projectKey straight through', async () => {
-        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 3 } }]);
+        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 3, landedIdle: [] } }]);
         const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
         expect(calls).toHaveLength(1);
         expect(calls[0].method).toBe('POST');
@@ -87,25 +110,28 @@ describe('orboto_work_next', () => {
     });
     it('caches the rules hash across calls and renders "Renewed" on a reused session', async () => {
         const handler = makeWorkNextHandler(client);
-        stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1 } }]);
+        stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle: [] } }]);
         await handler({ projectKey: 'ACME' });
         const calls2 = stub([{
                 json: {
                     reserved: { ...RESERVED, reused: true, rulesUnchanged: true, rules: undefined },
-                    reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1,
+                    reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle: [],
                 },
             }]);
         const res2 = await handler({ projectKey: 'ACME' });
         expect(calls2[0].body?.knownRulesHash).toBe('abc123');
         const text2 = res2.content[0].text;
         expect(text2).toContain('Unchanged since your last call');
+        expect(text2).toContain('not currently in your context');
+        expect(text2).toContain('rulesOnly: true');
+        expect(text2).not.toContain('keep following what you already loaded');
         expect(text2).toContain('Renewed your existing');
     });
     it('renders a structured empty result with a retry hint (all-leased)', async () => {
         stub([{
                 json: {
                     reserved: null, reason: 'all-leased', retryAfterSeconds: 420,
-                    earliestFreeAt: '2026-07-24T10:15:00Z', candidatesConsidered: 4,
+                    earliestFreeAt: '2026-07-24T10:15:00Z', candidatesConsidered: 4, landedIdle: [],
                 },
             }]);
         const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
@@ -124,7 +150,7 @@ describe('orboto_work_next', () => {
         stub([{
                 json: {
                     reserved: null, reason: 'none-matching', retryAfterSeconds: null,
-                    earliestFreeAt: null, candidatesConsidered: 0,
+                    earliestFreeAt: null, candidatesConsidered: 0, landedIdle: [],
                 },
             }]);
         const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
@@ -134,7 +160,7 @@ describe('orboto_work_next', () => {
         expect(text).not.toContain('Retry in');
     });
     it('forwards role, leaseSeconds, and resourceClaims to the API', async () => {
-        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1 } }]);
+        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1, landedIdle: [] } }]);
         await makeWorkNextHandler(client)({
             projectKey: 'ACME',
             role: 'review',

package/dist/tools/work-sessions-shared.js

@@ -14,9 +14,4 @@ export const ResourceClaimShape = {
 /** Shared 409-body reader: the endpoint's body carries EITHER `holder`
  *  (a lease conflict) OR `claimConflicts` (a resource-claim conflict) -
  *  never both, since the lease is checked before claims are applied. */
-export const GIT_HEALTH_REASON_TEXT = {
-    connection_inactive: 'connection is deactivated',
-    app_installation_suspended: 'GitHub App installation is suspended',
-    oauth_token_expired: 'OAuth token expired with no refresh path',
-    history_backfill_error: 'last history backfill failed',
-};
+export { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';

package/dist/tools/work-sessions-start.test.js

@@ -122,6 +122,9 @@ describe('orboto_work_start', () => {
         expect(post2.body?.knownRulesHash).toBe('abc123');
         const text2 = res2.content[0].text;
         expect(text2).toContain('Unchanged since your last work-start');
+        expect(text2).toContain('not currently in your context');
+        expect(text2).toContain('rulesOnly: true');
+        expect(text2).not.toContain('keep following what you already loaded');
         expect(text2).toContain('Renewed your existing');
     });
     it('surfaces the lease holder on a 409 instead of throwing', async () => {

package/dist/tools/work-sessions.js

@@ -18,6 +18,8 @@
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken, resolveTicketByKey } from './shared.js';
+import { validateRulesReceipt } from '../required-rules.js';
+export { makeWorkNextHandler, workNextToolConfig } from './work-next.js';
 import { GIT_HEALTH_REASON_TEXT, ResourceClaimShape, } from './work-sessions-shared.js';
 function parseClaimConflicts(err) {
     try {
@@ -68,7 +70,8 @@ export const workStartToolConfig = {
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set. Default `reject`.'),
     }).shape,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    // takeover=true cancels another holder; hints describe the worst allowed call.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeWorkStartHandler(client) {
     // Per-connection rules-hash cache, mirrored from session-start.ts's
@@ -96,8 +99,7 @@ export function makeWorkStartHandler(client) {
                 agentSessionToken: token,
                 ...(lastKnownRulesHash ? { knownRulesHash: lastKnownRulesHash } : {}),
             });
-            if (res.rulesHash)
-                lastKnownRulesHash = res.rulesHash;
+            validateRulesReceipt(res, lastKnownRulesHash, 'rules');
             const lines = [
                 res.reused
                     ? `Renewed your existing ${res.session.role} session on ${args.ticketKey}.`
@@ -114,7 +116,7 @@ export function makeWorkStartHandler(client) {
             }
             lines.push('', '## Working rules');
             if (res.rulesUnchanged) {
-                lines.push(`Unchanged since your last work-start on this connection (hash ${res.rulesHash}) - keep following what you already loaded.`);
+                lines.push(`Unchanged since your last work-start on this connection (hash ${res.rulesHash}). If these rules are not currently in your context, call orboto_session_start with rulesOnly: true before proceeding.`);
             }
             else {
                 lines.push(res.rules?.trim() || '(no workspace rules configured)');
@@ -156,6 +158,7 @@ export function makeWorkStartHandler(client) {
             lines.push(res.siblingSessions.length === 0
                 ? '(none)'
                 : res.siblingSessions.map((s) => `  - [${s.role}] ${s.userFullName ?? s.userEmail ?? 'unknown'} - lease until ${s.leaseUntil}`).join('\n'));
+            lastKnownRulesHash = res.rulesHash;
             return {
                 content: [{ type: 'text', text: lines.join('\n') }],
                 structuredContent: {
@@ -236,7 +239,8 @@ export const workSessionStartToolConfig = {
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set. Default `reject`: a conflicting write claim fails the WHOLE call with the conflicting holder(s) named - if this call would have created a brand-new session, that session is rolled back rather than left holding the lease without its claims. `queue`: the conflicting claim is accepted as `state: "waiting"` instead of failing; it is promoted automatically once the conflict clears (release, finish, or the next orboto_work_sessions read).'),
     }).shape,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    // The optional takeover can displace someone else's active session.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeWorkSessionStartHandler(client) {
     return async (args, extra) => {

package/dist/with-metrics.js

@@ -1,5 +1,6 @@
 import { OrbotoApiError } from './orboto-client.js';
-import { shouldNudge, prependNudge, shouldGate, gateResult } from './session-nudge.js';
+import { shouldNudge, prependNudge, shouldGate, gateResult, recordSessionStartResult } from './session-nudge.js';
+import { RequiredRulesError } from './required-rules.js';
 import { applyResponseBudget, TruncationBlockAdvertisedSchema } from './response-budget.js';
 import { buildStrictInputSchema, isRawShape } from './input-schema.js';
 import { captureToolDoc, summarizeToolDescription } from './tool-docs.js';
@@ -62,8 +63,7 @@ nudge) {
         // regardless of its outcome. Applied to the returned result below.
         const wantsNudge = nudge ? shouldNudge(nudge, toolName) : false;
         // ORB-1471 - HARD session-start gate. When the workspace requires it,
-        // refuse every tool call until `orboto_session_start` has run (this also
-        // flips the "ran" flag when the tool IS session_start). The gate message
+        // refuse every tool call until `orboto_session_start` succeeds. The gate message
         // supersedes the soft nudge, so we return it directly without running the
         // handler. Disabled by default => `shouldGate` returns false and nothing
         // below changes.
@@ -92,6 +92,8 @@ nudge) {
             // as success=false in the log so dashboards reflect actual
             // user-visible failures.
             const isError = result.isError === true;
+            if (nudge)
+                recordSessionStartResult(nudge, toolName, !isError);
             void postLogEntry(client, {
                 toolName,
                 durationMs: Date.now() - start,
@@ -113,6 +115,12 @@ nudge) {
         }
         catch (err) {
             const durationMs = Date.now() - start;
+            if (nudge)
+                recordSessionStartResult(nudge, toolName, false);
+            if (err instanceof RequiredRulesError) {
+                void postLogEntry(client, { toolName, durationMs, success: false, statusCode: err.status, errorMessage: err.message, clientHint });
+                return { isError: true, content: [{ type: 'text', text: err.message }], structuredContent: { errorKey: err.errorKey, reason: err.reason, ...(err.status ? { status: err.status } : {}) } };
+            }
             // ORB-1174 - an OrbotoApiError carries a real HTTP status + message.
             // Return it as a structured isError result so the agent + human see
             // WHY (401 vs 404 vs 500) and can self-correct, instead of the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.181.1",
+  "version": "0.182.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",