@orboto/mcp 0.229.0 → 0.230.0

package/dist/http-transport-binding.test.js

@@ -71,10 +71,10 @@ const store = {
 };
 async function start(limits) {
     api = fakeApiPerUser();
-    await new Promise((r) => api.listen(0, r));
+    await new Promise((r) => api.listen(0, '127.0.0.1', r));
     const { port: apiPort } = api.address();
     server = createHttpServer({ baseUrl: `http://127.0.0.1:${apiPort}`, sessionStore: store, limits });
-    await new Promise((r) => server.listen(0, r));
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
     const { port } = server.address();
     return `http://127.0.0.1:${port}`;
 }

package/dist/http-transport.test.js

@@ -12,7 +12,7 @@ let server = null;
 afterEach(() => { server?.close(); server = null; });
 async function start() {
     server = createHttpServer({ baseUrl: 'http://api.invalid' });
-    await new Promise((resolve) => server.listen(0, resolve));
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
     const { port } = server.address();
     return `http://127.0.0.1:${port}`;
 }
@@ -226,10 +226,10 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
     });
     async function startWithFakeApi(store, fake = fakeApi()) {
         api = fake.api;
-        await new Promise((r) => api.listen(0, r));
+        await new Promise((r) => api.listen(0, '127.0.0.1', r));
         const { port: apiPort } = api.address();
         server = createHttpServer({ baseUrl: `http://127.0.0.1:${apiPort}`, sessionStore: store });
-        await new Promise((r) => server.listen(0, r));
+        await new Promise((r) => server.listen(0, '127.0.0.1', r));
         const { port } = server.address();
         const internals = server.__mcp;
         return { base: `http://127.0.0.1:${port}`, internals };
@@ -330,10 +330,10 @@ describe('ORB-1470 - per-session bearer follows the client\'s token rotation', (
     });
     async function startWithFakeApi(store, fake = fakeApi()) {
         api = fake.api;
-        await new Promise((r) => api.listen(0, r));
+        await new Promise((r) => api.listen(0, '127.0.0.1', r));
         const { port: apiPort } = api.address();
         server = createHttpServer({ baseUrl: `http://127.0.0.1:${apiPort}`, sessionStore: store });
-        await new Promise((r) => server.listen(0, r));
+        await new Promise((r) => server.listen(0, '127.0.0.1', r));
         const { port } = server.address();
         const internals = server.__mcp;
         return { base: `http://127.0.0.1:${port}`, internals, state: fake.state };

package/dist/inbox-channel.js

@@ -230,6 +230,19 @@ export class InboxChannel {
         }
         await this.emit({ content, meta: { kind: 'notice', notice } });
     }
+    /** ORB-2641 - follow the session this process joined: the stream reconnects under its token and replays that session's unread mail, also what is older than the last id this process saw. */
+    switchInstance(token) {
+        if (!token || token === this.opts.instanceToken)
+            return;
+        this.opts = { ...this.opts, instanceToken: token };
+        this.lastId = null;
+        this.since = JOINED_REPLAY_SINCE;
+        this.log(`joined the session of this process under its token; the inbox stream reconnects`);
+        try {
+            this.abort.abort();
+        }
+        catch { /* ignore */ }
+    }
     /** ORB-2209 - the id and scope the server resumed; never a channel event. */
     applySession(session) {
         this.session = session;
@@ -360,6 +373,8 @@ export class InboxChannel {
         }
     }
 }
+/** ORB-2641 - the replay anchor after joining another session: its whole unread backlog, deduplicated by message id. */
+export const JOINED_REPLAY_SINCE = '2020-01-01T00:00:00.000Z';
 /** ORB-2175 - the notice name the stale-CLI finding is delivered under. */
 export const CLI_OUTDATED_NOTICE = 'cli_outdated';
 /**

package/dist/inbox-channel.test.js

@@ -5,7 +5,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, CLI_OUTDATED_NOTICE, InboxChannel, RESTART_REQUESTED_NOTICE, cliOutdatedNotice, digestMinutesFromEnv, isImmediate, renderEvent, scopeHintWithKey } from './inbox-channel.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, CLI_OUTDATED_NOTICE, InboxChannel, JOINED_REPLAY_SINCE, RESTART_REQUESTED_NOTICE, cliOutdatedNotice, digestMinutesFromEnv, isImmediate, renderEvent, scopeHintWithKey } from './inbox-channel.js';
 import { buildOrbotoMcpServer } from './server.js';
 import { _forgetDeclaredScopes, rememberDeclaredScope, rememberedScope } from './session-scope-memory.js';
 function mockMcp() {
@@ -292,3 +292,52 @@ describe('server capability', () => {
         await off.server.close();
     });
 });
+describe('ORB-2641 - a proxy that joins the session of its process', () => {
+    beforeEach(() => { vi.useFakeTimers(); });
+    afterEach(() => { vi.useRealTimers(); });
+    it('reconnects the inbox stream under the joined token, and every later call of the process acts under it', async () => {
+        const { mcp } = mockMcp();
+        const held = (_url, init) => new Promise((_resolve, reject) => {
+            init.signal.addEventListener('abort', () => reject(new Error('aborted')));
+        });
+        const fetchFn = vi.fn().mockImplementation(held);
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'agent-checkout', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        channel.start();
+        await vi.waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(1));
+        channel.switchInstance('agent-checkout');
+        channel.switchInstance('agent-checkout-ns');
+        await vi.advanceTimersByTimeAsync(2_000);
+        await vi.waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(2));
+        expect(fetchFn.mock.calls[0][1].headers['x-orboto-agent-session']).toBe('agent-checkout');
+        expect(fetchFn.mock.calls[1][1].headers['x-orboto-agent-session']).toBe('agent-checkout-ns');
+        expect(String(fetchFn.mock.calls[1][0])).toContain(`since=${encodeURIComponent(JOINED_REPLAY_SINCE)}`);
+        channel.close();
+        const { adoptProcessInstance, mcpProcessInstance, mcpInstanceToken } = await import('./tools/shared.js');
+        const before = mcpProcessInstance();
+        adoptProcessInstance('bad token with spaces');
+        expect(mcpProcessInstance()).toBe(before);
+        adoptProcessInstance('agent-checkout-ns');
+        expect(mcpProcessInstance()).toBe('agent-checkout-ns');
+        expect(mcpInstanceToken()).toBe('agent-checkout-ns');
+        adoptProcessInstance(before);
+    });
+});
+describe('ORB-2641 - a server without a channel joins the session of its process too', () => {
+    it('its one tool-server beat adopts the joined token, and an answer without one changes nothing', async () => {
+        const { beatAsToolServer, mcpProcessInstance, adoptProcessInstance } = await import('./tools/shared.js');
+        const before = mcpProcessInstance();
+        const seen = [];
+        const client = (joined) => ({
+            post: async (_path, body, options) => {
+                seen.push({ body, token: options?.instanceToken });
+                return (joined ? { sessionId: 's', joined: { sessionId: 's', shortId: 's', instanceToken: joined } } : { sessionId: 's' });
+            },
+        });
+        expect(await beatAsToolServer(client(), { toolServer: true })).toBeNull();
+        expect(mcpProcessInstance()).toBe(before);
+        expect(await beatAsToolServer(client('agent-cli-declared'), { toolServer: true })).toBe('agent-cli-declared');
+        expect(mcpProcessInstance()).toBe('agent-cli-declared');
+        expect(seen).toEqual([{ body: { clientInfo: { toolServer: true } }, token: before }, { body: { clientInfo: { toolServer: true } }, token: before }]);
+        adoptProcessInstance(before);
+    });
+});

package/dist/index.js

@@ -67,8 +67,8 @@ async function main() {
         const releaseCapacity = releaseCapacityOnStdinEnd(process.stdin, preflightClient, (await import('./tools/shared.js')).mcpProcessInstance());
         if (channel) {
             const { InboxChannel, digestMinutesFromEnv, cliOutdatedNotice, CLI_OUTDATED_NOTICE } = await import('./inbox-channel.js');
-            const { mcpProcessInstance } = await import('./tools/shared.js');
-            const instanceToken = mcpProcessInstance();
+            const { mcpProcessInstance, adoptJoined } = await import('./tools/shared.js');
+            let instanceToken = mcpProcessInstance();
             const { declareEnvProjectScope } = await import('./project-scope.js');
             const declared = await declareEnvProjectScope(preflightClient, instanceToken);
             const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
@@ -83,7 +83,14 @@ async function main() {
             let refusalLogged = false;
             const beat = () => {
                 preflightClient.post('/v1/agent/heartbeat', { clientInfo: channelClientInfo(readClaudeContext(process.cwd()), undefined, channelStart ?? undefined) }, { instanceToken })
-                    .then(() => { refusalLogged = false; })
+                    .then((res) => {
+                    refusalLogged = false;
+                    const joined = adoptJoined(res);
+                    if (joined) {
+                        instanceToken = joined;
+                        inbox.switchInstance(joined);
+                    }
+                })
                     .catch((err) => {
                     const refused = presenceRefusal(err);
                     if (refused && refusalLogged)
@@ -102,7 +109,8 @@ async function main() {
         }
         else {
             const { toolServerHeartbeat } = await import('./claude-context.js');
-            preflightClient.post('/v1/agent/heartbeat', { clientInfo: toolServerHeartbeat() }, { instanceToken: (await import('./tools/shared.js')).mcpProcessInstance() })
+            const { beatAsToolServer } = await import('./tools/shared.js');
+            beatAsToolServer(preflightClient, toolServerHeartbeat())
                 .catch((err) => { console.error(`[orboto-mcp] heartbeat failed: ${err.message}`); });
         }
         return;

package/dist/session-origin.test.js

@@ -111,10 +111,10 @@ describe('ORB-2544 - an MCP client reconnecting five times', () => {
             res.writeHead(200, { 'content-type': 'application/json' });
             res.end(url.startsWith('/agent-instructions') ? JSON.stringify({ instructions: '' }) : '{}');
         });
-        await new Promise((r) => api.listen(0, r));
+        await new Promise((r) => api.listen(0, '127.0.0.1', r));
         const store = { register: async () => { }, resolve: async () => false, remove: async () => { } };
         server = createHttpServer({ baseUrl: `http://127.0.0.1:${api.address().port}`, sessionStore: store });
-        await new Promise((r) => server.listen(0, r));
+        await new Promise((r) => server.listen(0, '127.0.0.1', r));
         const base = `http://127.0.0.1:${server.address().port}`;
         const init = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 't', version: '1' } } });
         for (let i = 0; i < 5; i += 1) {

package/dist/tools/api-call.js

@@ -16,7 +16,9 @@ export const apiCallToolConfig = {
         + 'Find the endpoint + its schema with `orboto_api_search` first. Runs with YOUR permissions '
         + 'only (the API enforces them server-side); the response is an envelope carrying the inner '
         + 'HTTP status + body verbatim, so react to a 403/404/422 as data. Auth/OAuth/setup/webhook '
-        + 'paths are blocked at the proxy. Prefer named tools when one exists - they are more ergonomic.',
+        + 'paths are blocked at the proxy. Over an OAuth connection, API keys, OAuth clients, sign-in factors and passwords '
+        + 'need the web login (403 errors.auth.oauth_credential_route_refused). '
+        + 'Prefer named tools when one exists - they are more ergonomic.',
     inputSchema: z.object({
         method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
         path: z.string().min(1).max(500)

package/dist/tools/git-rotate-token.js

@@ -10,7 +10,7 @@ import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
 export const gitRotateTokenToolConfig = {
     title: 'Rotate a git connection\'s access token',
-    description: 'Replace a git connection\'s access token (ssh: private key). The provider is probed with the new credential first; on success it is re-sealed under the same connection id, on failure 422 and the old one stays. reinstallWebhook also reinstalls the hook. App / OAuth connections answer 422.',
+    description: 'Replace a git connection\'s access token (ssh: private key). The provider is probed with the new credential first; on success it is re-sealed under the same connection id, on failure 422 and the old one stays. reinstallWebhook also reinstalls the hook. App / OAuth connections answer 422. Needs an API key or the web login: an OAuth MCP connection gets 403 errors.auth.oauth_credential_route_refused.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key, e.g. ORB.'),
         connectionId: z.string().uuid().describe('Git connection id.'),

package/dist/tools/presence-scope.test.js

@@ -18,9 +18,9 @@ import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 const SESSION_EXISTS = {
-    error: 'Another live session of this account runs in sample-repo on build-host: 0123abcd (claude-code, 42 min, ORB-7). Start again with --adopt to take over its scope, mail and leases, or with --end-previous to end it.',
+    error: 'Another live session of this account runs in sample-repo on build-host with an overlapping scope (ORB): 0123abcd (claude-code, 42 min, ORB-7). Start with a scope that shares none of these keys to run both side by side, or again with --adopt to take over the scope, mail and leases of every overlapping session (0123abcd, 4567ef01, 89ab0123), or with --end-previous to end them.',
     errorKey: 'errors.agents.session_exists',
-    errorParams: { sessionId: '0123abcd-0000-4000-8000-000000000000', shortId: '0123abcd', ageMinutes: 42, ticket: 'ORB-7', host: 'build-host', repo: 'sample-repo', harness: 'claude-code', role: 'integrator', projects: 'ORB' },
+    errorParams: { sessionId: '0123abcd-0000-4000-8000-000000000000', shortId: '0123abcd', ageMinutes: 42, ticket: 'ORB-7', host: 'build-host', repo: 'sample-repo', harness: 'claude-code', role: 'integrator', projects: 'ORB', overlap: 'ORB', sessionIds: '0123abcd, 4567ef01, 89ab0123', alsoOverlapping: '4567ef01, 89ab0123' },
 };
 const SCOPE_REQUIRED = { error: 'This session declares no scope', errorKey: 'errors.agents.scope_required', errorParams: { command: 'orboto session-start --role <role> --scope-projects <KEY>', notes: ['Not carried over: the earlier scope.'] } };
 beforeEach(() => { _forgetDeclaredScopes(); });
@@ -55,7 +55,9 @@ describe('ORB-2553 - the refusal on the MCP side', () => {
         const res = await makeSessionStartHandler(client)({ scope: { role: 'integrator', projectKeys: ['ORB'] }, previous: 'adopt' }, { sessionId: 'ps1' });
         expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({ start: true, previous: 'adopt', scope: { role: 'integrator', projectKeys: ['ORB'] } });
         const text = res.content[0].text;
-        expect(text).toContain('Not registered: Another live session of this account runs in sample-repo on build-host: 0123abcd');
+        expect(text).toContain('Not registered: Another live session of this account runs in sample-repo on build-host with an overlapping scope (ORB): 0123abcd');
+        expect(text).toContain('once the scope shares none of its keys');
+        expect(text).toContain('to replace it and 2 more: 4567ef01, 89ab0123 - all of them');
         expect(text).toContain('previous: "adopt" or "end"');
         expect(text).not.toContain('Peers reach exactly this session');
         expect(res.structuredContent.session.refused).toContain('0123abcd');
@@ -69,6 +71,17 @@ describe('ORB-2553 - the refusal on the MCP side', () => {
         expect(res.content[0].text).toContain('Adopted session 0123abcd: 2 unread message(s) and the leases on ORB-7 moved here, it is ended.');
         expect(takeoverLine({ action: 'ended', shortId: 'abcd0123', movedMessages: 0, movedLeases: [], releasedTickets: ['ORB-9'] })).toBe('Ended the previous session abcd0123 in this repository; its leases on ORB-9 are released.');
     });
+    it('ORB-2639 - a start that took over several overlapping sessions names each', async () => {
+        const seen = [];
+        const one = { action: 'ended', sessionId: '0123abcd-0000-4000-8000-000000000000', shortId: '0123abcd', movedMessages: 0, movedLeases: [], releasedTickets: [] };
+        const two = { ...one, sessionId: '4567ef01-0000-4000-8000-000000000000', shortId: '4567ef01', releasedTickets: ['IMG-57'] };
+        stub({ status: 200, body: { sessionToken: 'mcp-ps3', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'lead', projectKeys: ['WEB', 'IMG'] }, takeover: one, takeovers: [one, two] } }, seen);
+        const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'orb_k' });
+        const res = await makeSessionStartHandler(client)({ previous: 'end' }, { sessionId: 'ps3' });
+        const text = res.content[0].text;
+        expect(text).toContain('Ended the previous session 0123abcd in this repository.');
+        expect(text).toContain('Ended the previous session 4567ef01 in this repository; its leases on IMG-57 are released.');
+    });
     it('the proxy declares the checkout project as a start and hands back the refusal', async () => {
         const calls = [];
         const refusing = {

package/dist/tools/sentry.js

@@ -9,7 +9,7 @@ import { mcpInstanceToken, resolveProjectByKey, resolveTicketByKey } from './sha
 const ACTIONS = ['list', 'health', 'connect', 'update', 'rotate_secret', 'disconnect', 'triage_lane', 'verdict'];
 export const sentryToolConfig = {
     title: 'Sentry connector',
-    description: 'Sentry connector (ORB-2123). Actions: list, health, connect (orgSlug, projectSlug, clientSecret), update (triageMode comment|fix_branch), rotate_secret, disconnect, triage_lane (laneId, empty unbinds), verdict (ticketKey, verdict known_fixed|regression|new, summary). Secrets never come back; docs/sentry-intake.md.',
+    description: 'Sentry connector (ORB-2123). Actions: list, health, connect (orgSlug, projectSlug, clientSecret), update (triageMode comment|fix_branch), rotate_secret, disconnect, triage_lane (laneId, empty unbinds), verdict (ticketKey, verdict known_fixed|regression|new, summary). Secrets never come back; docs/sentry-intake.md. connect and rotate_secret need an API key or the web login (403 over OAuth).',
     inputSchema: z.object({
         action: z.enum(ACTIONS),
         projectKey: z.string().min(1),

package/dist/tools/session-start.js

@@ -23,7 +23,7 @@ import { agentContextKey } from '../agent-context.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
     description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it FIRST in a session and AFTER every context compaction. Returns the rules in full (above the full-text bound: one title per rule plus every must-read rule in full, the rest via `rulesOnly: true`); a compact "unchanged" ack only on a repeat inside the same agent context. Also returns your in-progress tickets (LANDED, IDLE = a linked commit but no move for days: finished work never handed to review), your timer and unhealthy git connections. Not orboto_list_agent_instructions - that one edits rule blocks for admins. Registers this session (a heartbeat on its instance row), otherwise read-only. '
-        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text, never truncated. `projectId` adds that project\'s rules. `ticketKey` ("ACME-42") bundles that ticket\'s primer, detail, dependencies, checklists, git health and other agent sessions. `forceRules: true` returns the full text inline even above the bound or after an ack - use it whenever the rules are NOT in your context. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) target rule blocks and per-tier text. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; session.ref is what peers pass as toSessionRef (ORB-2136). `previous` (adopt | end) answers a second-start refusal (ORB-2553). '
+        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text, never truncated. `projectId` adds that project\'s rules. `ticketKey` ("ACME-42") bundles that ticket\'s primer, detail, dependencies, checklists, git health and other agent sessions. `forceRules: true` returns the full text inline even above the bound or after an ack - use it whenever the rules are NOT in your context. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) target rule blocks and per-tier text. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; session.ref is what peers pass as toSessionRef (ORB-2136). `previous` (adopt | end) answers a second-start refusal (ORB-2553); it comes only when the scope overlaps another live session of the account in this checkout (the keys in errorParams.overlap) - a scope that shares no project or ticket with it runs beside it (ORB-2639). '
         + 'Also carries the Knowledge block (ORB-2225: the wiki index of your declared projects and the Operations wiki; ask with orboto_knowledge_ask before a person, file durable facts with orboto_knowledge_add) and the Responsibilities block (ORB-2542: who owns the topics of your projects, orboto_who before agent mail). Right after the rules come Where knowledge lives (ORB-2575: rules bind behaviour, project facts hold fixed decisions, the wiki the long tail; a decision goes to a fact proposal, orboto_primer_fact_add with observed: true) and the Project facts of your declared projects.',
     inputSchema: z.object({
         projectId: z.string().uuid().optional(),
@@ -177,6 +177,11 @@ function knowledgeSummary(index, handle) {
     };
 }
 /** ORB-2209 - a declared scope stays with the instance token; the agent declares it once per terminal. */
+/** ORB-2639 - what `previous` replaces: the session the refusal names, and every further overlapping one by short id. */
+export function overlappingTarget(alsoOverlapping) {
+    const ids = alsoOverlapping.split(/[\s,]+/).filter(Boolean);
+    return ids.length ? `it and ${ids.length} more: ${ids.join(', ')} - all of them` : 'it';
+}
 /** ORB-2553 - what the start did to the session it ran into. */
 export function takeoverLine(t) {
     if (t.action === 'ended')
@@ -232,9 +237,17 @@ export function makeSessionStartHandler(client, opts = {}) {
             sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt,
             wake: r.wake, scopeExpired: r.scopeExpired ?? null, scopeContinued: r.scopeContinued ?? null, notes: Array.isArray(r.notes) ? r.notes.filter((n) => typeof n === 'string') : [],
             ...(r.takeover ? { takeover: r.takeover } : {}),
+            ...(r.takeovers?.length ? { takeovers: r.takeovers } : {}),
         } : null);
         let refusal = null;
-        const refused = (err) => { refusal = presenceRefusal(err)?.message ?? refusal; return null; };
+        let alsoOverlapping = '';
+        const refused = (err) => {
+            const found = presenceRefusal(err);
+            refusal = found?.message ?? refusal;
+            if (found && typeof found.params.alsoOverlapping === 'string')
+                alsoOverlapping = found.params.alsoOverlapping.trim();
+            return null;
+        };
         const host = localSessionHost(extra);
         const fallbackScope = input.scope === undefined && !supervisorScopePending() ? envProjectScope() : null;
         const startBody = {
@@ -368,11 +381,13 @@ export function makeSessionStartHandler(client, opts = {}) {
                 ? 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it'
                 : 'registration failed - only account mail is listed; retry orboto_session_start or check mcp:use';
         if (refusal)
-            lines.push(`ref ${instanceToken}. Not registered: ${refusal}`, 'With MCP: pass scope: { role, projectKeys } and, for another live session in this repository, previous: "adopt" or "end".');
+            lines.push(`ref ${instanceToken}. Not registered: ${refusal}`, `With MCP: pass scope: { role, projectKeys }; another live session in this repository whose scope overlaps runs beside this one once the scope shares none of its keys, or pass previous: "adopt" or "end" to replace ${overlappingTarget(alsoOverlapping)}.`);
         else
             lines.push(`ref ${instanceToken}${registration ? `, instance ${registration.sessionId.slice(0, 8)}` : ''}. ${scopeText}. Peers reach exactly this session with orboto_agent_notify { toSessionRef: "${registration ? registration.sessionId.slice(0, 8) : instanceToken}" }.`);
         if (exitedLine)
             lines.push(exitedLine);
+        else if (registration?.takeovers?.length)
+            lines.push(...registration.takeovers.map(takeoverLine));
         else if (registration?.takeover)
             lines.push(takeoverLine(registration.takeover));
         const roleAddresses = registration?.scope?.role ? (registration.scope.projectKeys ?? []).map((k) => `${registration.scope.role}@${k}`) : [];
@@ -420,6 +435,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                     scopeContinued: registration?.scopeContinued ?? null,
                     ...(refusal ? { refused: refusal } : {}),
                     ...(registration?.takeover ? { takeover: registration.takeover } : {}),
+                    ...(registration?.takeovers?.length ? { takeovers: registration.takeovers } : {}),
                 },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections

package/dist/tools/shared.js

@@ -122,7 +122,25 @@ export function checkoutInstanceToken(env = process.env, host = hostname(), cwd
     const explicit = (env.ORBOTO_AGENT_SESSION ?? '').trim();
     return explicit || `agent-${createHash('sha256').update(`${host}:${cwd}`).digest('hex').slice(0, 12)}`;
 }
-const MCP_PROCESS_INSTANCE = checkoutInstanceToken();
+let MCP_PROCESS_INSTANCE = checkoutInstanceToken();
+/** ORB-2641 - the process joins the session its harness process already declared under another token: every later call acts under that token. */
+export function adoptProcessInstance(token) {
+    if (/^[\x21-\x7e]{1,200}$/.test(token))
+        MCP_PROCESS_INSTANCE = token;
+}
+/** ORB-2641 - a heartbeat answer that names the session of this process (`joined`): the process continues under its token; returns that token, or null when nothing changed. */
+export function adoptJoined(res) {
+    const token = res?.joined?.instanceToken;
+    if (!token || token === MCP_PROCESS_INSTANCE)
+        return null;
+    adoptProcessInstance(token);
+    return MCP_PROCESS_INSTANCE === token ? token : null;
+}
+/** ORB-2641 - the one heartbeat of a stdio server without a channel: it says so, and joins the session of its process when the answer names one. */
+export async function beatAsToolServer(client, clientInfo) {
+    const res = await client.post('/v1/agent/heartbeat', { clientInfo }, { instanceToken: MCP_PROCESS_INSTANCE });
+    return adoptJoined(res);
+}
 /** ORB-2465 - the machine a stdio proxy runs on, lower-cased, as `agent-broadcast live --host` matches it; an HTTP connection (per-connection session id) runs on the server, so it reports none. */
 export function localSessionHost(extra, host = hostname()) {
     if (extra?.sessionId)

package/dist/tools/time-writes.js

@@ -6,7 +6,7 @@ import { OrbotoApiError } from '../orboto-client.js';
 import { resolveTicketByKey } from './shared.js';
 export const timerStartToolConfig = {
     title: 'Start a timer on a ticket',
-    description: 'Start the user\'s stopwatch on a ticket. If a timer is already running on a different ticket, pass replace=true to auto-stop the previous one (its elapsed time is committed to time_entries before the new timer begins). Description becomes the time entry\'s note when this timer eventually stops.',
+    description: 'Start the user\'s stopwatch on a ticket. If a timer is already running on a different ticket, pass replace=true to auto-stop the previous one (its elapsed time is committed to time_entries before the new timer begins). Description becomes the time entry\'s note when this timer eventually stops. Needs time:log on the ticket\'s project (403 errors.time.log_permission_required) and a ticket you can read (404).',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         description: z.string().optional().describe('Note for the time entry; set at start, not at stop.'),
@@ -46,7 +46,7 @@ export function makeTimerStartHandler(client) {
 }
 export const timerStopToolConfig = {
     title: 'Stop the running timer',
-    description: 'Stop the user\'s stopwatch. The API commits a time_entries row using the description set at start (or pause/resume), then deletes the active-timer record. Returns the duration in minutes.',
+    description: 'Stop the user\'s stopwatch. The API commits a time_entries row using the description set at start (or pause/resume), then deletes the active-timer record. Returns the duration in minutes; bookingRefused: true means the timer ran but booked nothing because you can no longer read the ticket or lost time:log on its project.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
@@ -60,6 +60,12 @@ export function makeTimerStopHandler(client) {
                     structuredContent: { durationMinutes: 0, alreadyStopped: true },
                 };
             }
+            if (res.bookingRefused) {
+                return {
+                    content: [{ type: 'text', text: 'Timer stopped - nothing booked: you can no longer read the ticket or lost time:log on its project.' }],
+                    structuredContent: { durationMinutes: 0, bookingRefused: true },
+                };
+            }
             return {
                 content: [{
                         type: 'text',

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

@@ -74,6 +74,12 @@ describe('orboto_timer_stop', () => {
         const sc = res.structuredContent;
         expect(sc.alreadyStopped).toBe(true);
     });
+    it('ORB-2632 - says nothing was booked when the API refused the booking', async () => {
+        stub([{ json: { durationMinutes: 0, stopped: true, laneFallback: false, bookingRefused: true } }]);
+        const res = await makeTimerStopHandler(client)();
+        expect(res.structuredContent).toEqual({ durationMinutes: 0, bookingRefused: true });
+        expect(res.content[0].text).toContain('nothing booked');
+    });
 });
 describe('orboto_log_time', () => {
     it('POSTs durationMinutes + optional description', async () => {

package/package.json

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