@orboto/mcp 0.181.0 → 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';
@@ -87,7 +88,8 @@ import { setParentToolConfig, makeSetParentHandler } from './tools/set-parent.js
 import { applyAgentProfile } from './tools/shared.js';
 import { updateProjectToolConfig, makeUpdateProjectHandler, createProjectToolConfig, makeCreateProjectHandler, archiveProjectToolConfig, makeArchiveProjectHandler, } from './tools/update-project.js';
 import { checkSimilarToolConfig, makeCheckSimilarHandler } from './tools/check-similar.js';
-import { workSessionStartToolConfig, makeWorkSessionStartHandler, workSessionFinishToolConfig, makeWorkSessionFinishHandler, workSessionsToolConfig, makeWorkSessionsHandler, workSessionClaimsAddToolConfig, makeWorkSessionClaimsAddHandler, workSessionClaimsReleaseToolConfig, makeWorkSessionClaimsReleaseHandler, workStartToolConfig, makeWorkStartHandler, workFinishToolConfig, makeWorkFinishHandler, workNextToolConfig, makeWorkNextHandler, } from './tools/work-sessions.js';
+import { workSessionStartToolConfig, makeWorkSessionStartHandler, workSessionFinishToolConfig, makeWorkSessionFinishHandler, workSessionsToolConfig, makeWorkSessionsHandler, workSessionClaimsAddToolConfig, makeWorkSessionClaimsAddHandler, workSessionClaimsReleaseToolConfig, makeWorkSessionClaimsReleaseHandler, workStartToolConfig, makeWorkStartHandler, workFinishToolConfig, makeWorkFinishHandler, } from './tools/work-sessions.js';
+import { workNextToolConfig, makeWorkNextHandler } from './tools/work-next.js';
 import { listAdminTranslationsToolConfig, makeListAdminTranslationsHandler, approveTranslationToolConfig, makeApproveTranslationHandler, revertTranslationToolConfig, makeAdminRevertTranslationHandler, } from './tools/admin-translations.js';
 import { listAgentDriftToolConfig, makeListAgentDriftHandler, resolveAgentDriftToolConfig, makeResolveAgentDriftHandler, } from './tools/agent-drift.js';
 /** ORB-1090 - the workspace's configurable working-rules, used as the
@@ -170,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
@@ -185,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',
+};