@orboto/mcp 0.221.0 → 0.221.11

package/dist/event-bridge.js

@@ -1,3 +1,4 @@
+import { originHeader } from './session-origin.js';
 const HEARTBEAT_GRACE_MS = 90_000;
 const OVERFLOW_THRESHOLD = 100;
 const RECONNECT_DELAY_MS = 2_000;
@@ -119,6 +120,7 @@ export class EventBridge {
                 Authorization: `Bearer ${bearer}`,
                 Accept: 'text/event-stream',
                 ...(this.opts.instanceToken ? { 'x-orboto-agent-session': this.opts.instanceToken } : {}),
+                'x-orboto-origin': originHeader(),
             },
             signal: this.abort.signal,
         });

package/dist/http-transport.js

@@ -11,7 +11,8 @@ import { buildOrbotoMcpServer } from './server.js';
 import { resolveToolset } from './toolset.js';
 import { OrbotoClient, preflightMcpSession } from './orboto-client.js';
 import { EventBridge } from './event-bridge.js';
-import { mcpInstanceToken } from './tools/shared.js';
+import { bindSessionInstance, mcpInstanceToken, releaseSessionInstance, stableClientInstance } from './tools/shared.js';
+import { useHttpOrigin } from './session-origin.js';
 import { releaseCapacityAtSessionEnd } from './tools/capacity-session.js';
 import { idleSessions, resolveSessionLimits, sessionsOverOwnerCap } from './session-limits.js';
 /** Default store backed by the api's `/system/mcp/sessions` endpoints. Each
@@ -168,6 +169,18 @@ function wwwAuthChallenge(req, baseUrl, error, description) {
     return `Bearer realm="orboto-mcp", error="${error}", error_description="${description.replace(/"/g, '\\"')}", resource_metadata="${resourceMetadata}"`;
 }
 export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides }) {
+    useHttpOrigin();
+    /** ORB-2544 - a closed MCP session ends its row resumably unless another live session of the same client still acts under the token. */
+    const endInstance = (sessionId, client) => {
+        const { token, shared } = releaseSessionInstance(sessionId);
+        if (token && !shared)
+            void client.post('/v1/agent/end-session', { resumable: true }, { instanceToken: token }).catch(() => { });
+    };
+    const bindStable = (sessionId, userEmail, credential, client) => {
+        const stable = stableClientInstance({ userEmail, credential, client });
+        if (stable)
+            bindSessionInstance(sessionId, stable);
+    };
     const sessions = new Map();
     const limits = resolveSessionLimits(undefined, limitOverrides);
     async function makeRoomFor(userEmail) {
@@ -197,11 +210,12 @@ export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides
             return null;
         }
     }
-    async function establishForcedSession(tokenHolder, userAgentSuffix, chosenSessionId, userEmail, toolset) {
+    async function establishForcedSession(tokenHolder, userAgentSuffix, chosenSessionId, userEmail, toolset, credential) {
         await makeRoomFor(userEmail);
+        bindStable(chosenSessionId, userEmail, credential, userAgentSuffix);
         const { sessionClient, mcp, bridge } = await buildSessionCore(tokenHolder, userAgentSuffix, toolset, chosenSessionId);
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
-        transport.onclose = () => { sessions.delete(chosenSessionId); bridge.close(); };
+        transport.onclose = () => { sessions.delete(chosenSessionId); bridge.close(); endInstance(chosenSessionId, sessionClient); };
         await mcp.connect(transport);
         forceInitialized(transport, chosenSessionId);
         const session = {
@@ -336,10 +350,12 @@ export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides
             const preflightClient = new OrbotoClient({ baseUrl, apiKey: token, userAgentSuffix });
             let authValid = false;
             let callerEmail = '';
+            let callerCredential;
             try {
                 const preflight = await preflightMcpSession(preflightClient);
                 authValid = true;
                 callerEmail = preflight.userEmail;
+                callerCredential = preflight.credential;
             }
             catch {
                 authValid = false;
@@ -358,13 +374,13 @@ export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides
                 return sendError(res, 404, 'Unknown or expired MCP session - reinitialize (the server restarted since this session began).');
             }
             if (action === 'rehydrate') {
-                const session = await establishForcedSession({ current: token }, userAgentSuffix, sessionId, callerEmail, toolset);
+                const session = await establishForcedSession({ current: token }, userAgentSuffix, sessionId, callerEmail, toolset, callerCredential);
                 void store.register(token, { sessionId, userAgent }).catch(() => { });
                 await session.transport.handleRequest(req, res, body);
                 return;
             }
             const newSessionId = randomUUID();
-            const session = await establishForcedSession({ current: token }, userAgentSuffix, newSessionId, callerEmail, toolset);
+            const session = await establishForcedSession({ current: token }, userAgentSuffix, newSessionId, callerEmail, toolset, callerCredential);
             overrideSessionIdHeader(req, newSessionId);
             process.stderr.write(`[orboto-mcp] auto-adopted stale session ${sessionId} → ${newSessionId} (client=${userAgent ?? 'unknown'})\n`);
             void store
@@ -376,8 +392,11 @@ export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides
         if (!sessionId && isInitializeRequest(body)) {
             const preflightClient = new OrbotoClient({ baseUrl, apiKey: token, userAgentSuffix });
             let ownerEmail;
+            let ownerCredential;
             try {
-                ownerEmail = (await preflightMcpSession(preflightClient)).userEmail;
+                const preflight = await preflightMcpSession(preflightClient);
+                ownerEmail = preflight.userEmail;
+                ownerCredential = preflight.credential;
             }
             catch (err) {
                 return sendError(res, 401, err.message, {
@@ -394,6 +413,7 @@ export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides
                     sessions.set(sid, {
                         transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail: ownerEmail, lastTouchAt: Date.now(), lastActiveAt: Date.now(),
                     });
+                    bindStable(sid, ownerEmail, ownerCredential, userAgentSuffix);
                     bridge.setInstanceToken(mcpInstanceToken(undefined, { sessionId: sid }));
                     bridge.start();
                     void store
@@ -405,6 +425,8 @@ export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides
                 if (transport.sessionId)
                     sessions.delete(transport.sessionId);
                 bridge.close();
+                if (transport.sessionId)
+                    endInstance(transport.sessionId, sessionClient);
             };
             await mcp.connect(transport);
             await transport.handleRequest(req, res, body);

package/dist/inbox-channel.js

@@ -1,10 +1,13 @@
 import { RESTART_REQUESTED_NOTICE, writeRestartRequest } from './session-restart.js';
 import { confirmScope, rememberedScope } from './session-scope-memory.js';
+import { originHeader } from './session-origin.js';
 export { RESTART_REQUESTED_NOTICE };
 export const CHANNEL_METHOD = 'notifications/claude/channel';
 /** ORB-2263 - the server notice an unscoped channel session gets; the session sees it once, with the exact CLI call. */
 export const DECLARE_SCOPE_NOTICE = 'declare_scope';
 export const CHANNEL_CAPABILITY = 'claude/channel';
+/** ORB-2544 - the operator ended this session: the event says so and the channel stops for good. */
+export const SESSION_ENDED_NOTICE = 'session_ended';
 export const DEFAULT_DIGEST_MINUTES = 15;
 const IMMEDIATE_AFTER_MS = 5 * 60_000;
 const CONTENT_CAP = 2000;
@@ -18,16 +21,11 @@ export function attachmentLine(m) {
     return m.attachments?.count ? `attachments: ${m.attachments.label} (orboto messages --download ${m.id})` : '';
 }
 /** The instructions paragraph Claude Code delivers on connect when the channel is active. */
-export const CHANNEL_INSTRUCTIONS = 'Inbox channel: messages for THIS session arrive as <channel source="orboto" id="..." kind="..." ...> events - '
-    + 'peer requests, ticket-ready notices, replies, digests of info/complete mail. Treat each like an inbox message under the rules: '
-    + 'a ticket-ready or a request inside your scope is the operator\'s instruction, act on it; read the full message with orboto_messages when the event is cut; '
-    + 'reply with orboto_agent_notify (toSessionRef = the sender\'s instance short id in the from attribute) and acknowledge with orboto_messages { ackIds } once handled. '
-    + 'Never answer the channel itself and never ack what you did not handle - dismiss it instead with orboto_messages { dismiss: { ids, reason } }: '
-    + 'not_mine for another session\'s mail (the sender is told, and the message never reaches this session again), obsolete or duplicate with a note when the request is already done. '
-    + 'A session that declared no scope is woken by mail addressed to it and by broadcasts only, and gets one notice event saying so on connect: '
-    + 'declare the scope through the CLI in the shell, `orboto session-start --role worker --scope-projects <KEY>`, to be woken by the account\'s project mail again - never through the claude.ai connector, which is another session - '
-    + 'the rest of the account\'s inbox stays readable with orboto_messages the whole time. '
-    + 'Declare it once: the session keeps its id and scope across reconnects and restarts of this terminal.';
+export const CHANNEL_INSTRUCTIONS = 'Wake channel: messages for THIS session arrive as <channel source="orboto" id="..." kind="..."> events. '
+    + 'A ticket-ready or a request inside your scope is the operator\'s instruction - act on it. '
+    + 'Read a cut message with orboto_messages, reply with orboto_agent_notify, acknowledge with orboto_messages { ackIds } once handled, '
+    + 'dismiss what is not yours with orboto_messages { dismiss: { ids, reason } }. Never answer the channel itself. '
+    + 'Declare the scope once in the shell with `orboto session-start --role worker --scope-projects <KEY>`, never through the claude.ai connector; details: orboto://rules.';
 const START_FLAG = '--dangerously-load-development-channels server:orboto';
 /** ORB-2148 - the commands an agent hands its operator verbatim; docs/claude-code.md carries the same lines. */
 export const CHANNEL_START_COMMANDS = {
@@ -207,6 +205,11 @@ export class InboxChannel {
             return;
         }
         this.stats.notices += 1;
+        if (notice === SESSION_ENDED_NOTICE) {
+            await this.emit({ content, meta: { kind: 'notice', notice } });
+            this.close();
+            return;
+        }
         if (notice === RESTART_REQUESTED_NOTICE) {
             await this.emit({ content: this.takeRestartRequest(content), meta: { kind: 'notice', notice } });
             return;
@@ -283,7 +286,7 @@ export class InboxChannel {
         const bearer = this.opts.tokenProvider ? await this.opts.tokenProvider.getAccessToken() : (this.opts.apiKey ?? '');
         const res = await fetchFn(url, {
             method: 'GET',
-            headers: { Authorization: `Bearer ${bearer}`, Accept: 'text/event-stream', 'x-orboto-agent-session': this.opts.instanceToken },
+            headers: { Authorization: `Bearer ${bearer}`, Accept: 'text/event-stream', 'x-orboto-agent-session': this.opts.instanceToken, 'x-orboto-origin': originHeader() },
             signal: this.abort.signal,
         });
         if (!res.ok || !res.body)

package/dist/instructions-budget.test.js

@@ -3,9 +3,14 @@
  * client can't silently truncate it mid-rule; the head always survives
  * and the rules are cut at a whole-line boundary with a pointer to the
  * cap-independent full set.
+ *
+ * @see ORB-2552
  */
-import { describe, it, expect } from 'vitest';
-import { assembleInstructions } from './server.js';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { assembleInstructions, buildOrbotoMcpServer, CLIENT_INSTRUCTIONS_CAP, MANDATORY_FIRST_ACTION } from './server.js';
+import { CHANNEL_INSTRUCTIONS } from './inbox-channel.js';
 const HEADING = 'Working rules for this workspace:\n';
 describe('assembleInstructions (ORB-1177)', () => {
     it('passes through unchanged when under budget', () => {
@@ -30,3 +35,68 @@ describe('assembleInstructions (ORB-1177)', () => {
         expect(kept.length).toBeLessThan(lines.length);
     });
 });
+const HUGE_RULES = Array.from({ length: 200 }, (_, i) => `rule ${i}: ${'x'.repeat(60)}`).join('\n');
+async function deliveredInstructions(toolset, channel) {
+    const body = { instructions: HUGE_RULES, rulesHash: 'orb-2552-fixture' };
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+        ok: true,
+        status: 200,
+        headers: new Headers({ 'content-type': 'application/json' }),
+        json: async () => body,
+        text: async () => JSON.stringify(body),
+    });
+    const server = await buildOrbotoMcpServer({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test', toolset, channel });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'instructions-cap', version: '0.0.0' });
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    try {
+        return client.getInstructions() ?? '';
+    }
+    finally {
+        await client.close();
+        await server.close();
+        vi.restoreAllMocks();
+    }
+}
+function clientCut(text) {
+    return text.length > CLIENT_INSTRUCTIONS_CAP ? text.slice(0, CLIENT_INSTRUCTIONS_CAP) : text;
+}
+describe('ORB-2552 - the mandatory first action survives the client cap', () => {
+    beforeEach(() => { delete process.env.ORBOTO_MCP_TOOLSET; });
+    afterEach(() => { vi.restoreAllMocks(); });
+    it('the cap is the measured Claude Code 2.1.301 value', () => {
+        expect(CLIENT_INSTRUCTIONS_CAP).toBe(2048);
+        expect(MANDATORY_FIRST_ACTION.startsWith('FIRST ACTION')).toBe(true);
+        expect(MANDATORY_FIRST_ACTION).toContain('orboto_session_start');
+        expect(MANDATORY_FIRST_ACTION).toContain('orboto://rules');
+    });
+    for (const toolset of ['minimal', 'curated', 'full']) {
+        for (const channel of [false, true]) {
+            it(`${toolset}${channel ? ' + wake channel' : ''}: starts with the first action and keeps it whole inside the cap`, async () => {
+                const text = await deliveredInstructions(toolset, channel);
+                expect(text.startsWith(MANDATORY_FIRST_ACTION)).toBe(true);
+                expect(clientCut(text)).toContain(MANDATORY_FIRST_ACTION);
+                if (channel)
+                    expect(clientCut(text)).toContain(CHANNEL_INSTRUCTIONS);
+                expect(text.length).toBeLessThanOrEqual(CLIENT_INSTRUCTIONS_CAP);
+                if (toolset !== 'full')
+                    expect(clientCut(text)).toMatch(/orboto_api_search.*orboto_api_call/);
+            });
+        }
+    }
+    it('curated and full point at the complete rules inside the cap when the workspace rules overflow it', async () => {
+        for (const toolset of ['curated', 'full']) {
+            const visible = clientCut(await deliveredInstructions(toolset, false));
+            expect(visible).toContain('rules truncated');
+            expect(visible).toContain('orboto://rules');
+        }
+    });
+    for (const channel of [false, true]) {
+        it(`channel toolset${channel ? ' + wake channel' : ''}: the CLI first action opens the block inside the cap`, async () => {
+            const text = await deliveredInstructions('channel', channel);
+            const first = /^FIRST ACTION[^]*?compaction\./.exec(text)?.[0] ?? '';
+            expect(first).toContain('`orboto session-start`');
+            expect(text.length).toBeLessThanOrEqual(CLIENT_INSTRUCTIONS_CAP);
+        });
+    }
+});

package/dist/manifest-size.test.js

@@ -51,6 +51,14 @@ afterEach(() => { vi.restoreAllMocks(); });
  * (full = 171,194 chars, 6 free).
  * ORB-2502 gave `orboto_messages` a `since` parameter inside the ceiling: the
  * limit lost its schema default and the project hint shrank (full = 171,197).
+ * ORB-2542 added no named tool: the owner lookup rides `orboto_who` `for` and
+ * the escape hatch; the route/forceTarget parameters fit after tightening the
+ * agent_notify description.
+ * ORB-2546 gave `orboto_list_tickets` a described `sort` enum inside the
+ * ceiling: its parameter descriptions shrank to pay for it (full = 171,197).
+ * ORB-2544 added no named tool: ending a session rides the escape hatch;
+ * orboto_who `state` and the agent_presence redaction line fit after the
+ * agent_presence summary shrank (full = 171,160).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/orboto-client.js

@@ -3,6 +3,7 @@
  * the orboto API.
  */
 import { VERSION } from './version.js';
+import { originHeader } from './session-origin.js';
 export class OrbotoApiError extends Error {
     status;
     body;
@@ -63,6 +64,7 @@ export class OrbotoClient {
             const headers = {
                 ...this.baseHeaders,
                 ...(this.instanceToken ? { 'x-orboto-agent-session': this.instanceToken } : {}),
+                'x-orboto-origin': originHeader(),
                 ...(accept ? { Accept: accept } : {}),
                 ...(init.headers ?? {}),
                 Authorization: `Bearer ${token}`,
@@ -219,5 +221,5 @@ export async function preflightMcpSession(client) {
     if (!status.userMcpEnabled) {
         throw new Error('MCP preflight failed: you have disabled MCP access for your account. Re-enable it in Profile - Connect an AI Client.');
     }
-    return { userEmail: status.userEmail };
+    return { userEmail: status.userEmail, credential: status.credential ?? null };
 }

package/dist/orboto-client.test.js

@@ -99,7 +99,7 @@ describe('preflightMcpSession', () => {
     it('resolves {userEmail} when enabled + mcpUseGranted + userMcpEnabled', async () => {
         mockFetch({ json: async () => ({ enabled: true, mcpUseGranted: true, userMcpEnabled: true, userEmail: 'a@b.c' }) });
         const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
-        await expect(preflightMcpSession(client)).resolves.toEqual({ userEmail: 'a@b.c' });
+        await expect(preflightMcpSession(client)).resolves.toEqual({ userEmail: 'a@b.c', credential: null });
     });
     it('throws the per-user opt-out message when userMcpEnabled=false (ORB-942)', async () => {
         mockFetch({ json: async () => ({ enabled: true, mcpUseGranted: true, userMcpEnabled: false, userEmail: 'a@b.c' }) });

package/dist/server.js

@@ -103,32 +103,30 @@ const FALLBACK_WORKING_RULES = [
     'When you write a git commit that touches a ticket, put the ticket key (e.g. `ORB-42`) in parentheses at the END of the subject line - `feat(auth): add token rotation (ORB-42)`. The orboto git-activity parser links the commit by that key.',
     'Use sub-tickets for steps large enough to need their own commit / time tracking / review, and checklists for one-liners inside a single ticket\'s scope. Big features (Epic + 3+ phase tickets): create a milestone FIRST, then the Epic, then phase tickets as children on that milestone.',
 ].join(' ');
+/** ORB-2552 - Claude Code 2.1.301 keeps the first 2048 UTF-16 characters of a server's instructions and appends "… [truncated]" (measured on the claude.ai connector, docs/agent-access-paths.md). */
+export const CLIENT_INSTRUCTIONS_CAP = 2048;
+/** ORB-2552 - the mandatory first action, always the first characters of every tool-carrying instructions block. */
+export const MANDATORY_FIRST_ACTION = 'FIRST ACTION, before anything else: call `orboto_session_start` - it returns the binding workspace rules and your in-progress work; call it again after a context compaction. Non-negotiables: claim or create a ticket before touching code, one commit per ticket with the key in the subject, push after each commit, never mark work done that is not done. Complete rules: `orboto_session_start` or the `orboto://rules` resource.';
 function staticMcpHints(toolset) {
     if (toolset === 'minimal') {
         return [
-            'orboto is a ticket + project management system. Ticket keys look like `PROJ-123`; the first segment is the project key.',
-            'This is the MINIMAL tool manifest (12 tools) for small context windows. Every other endpoint stays reachable: find it with `orboto_api_search`, run it with `orboto_api_call`. Bigger manifests are opt-in: `?toolset=curated` / `full` (HTTP) or ORBOTO_MCP_TOOLSET (stdio).',
-            'Writes respect the caller\'s permissions - a 403 is the API refusing, not this server.',
+            'orboto is a ticket + project management system; ticket keys look like `PROJ-123`.',
+            'This is the MINIMAL manifest (12 tools). Every other endpoint: find it with `orboto_api_search`, run it with `orboto_api_call`. Bigger manifests: `?toolset=curated|full` (HTTP) or ORBOTO_MCP_TOOLSET (stdio).',
+            'A 403 is the API refusing, not this server.',
         ].join(' ');
     }
     return [
-        'orboto is a ticket + project management system.',
-        'When starting on a project, call `orboto_get_project_primer(<PROJECT_KEY>)` once to load its conventions (tech stack, commands, gotchas, expected ticket language).',
-        'Use `orboto_list_projects` first to discover what the user can see.',
-        'Ticket keys look like `PROJ-123`; the first segment is the project key.',
-        'For "what am I working on?" prefer `orboto_my_tickets`; for "anything about X?" prefer `orboto_search`.',
+        'orboto is a ticket + project management system; ticket keys look like `PROJ-123`.',
+        'Discover projects with `orboto_list_projects`, load one project\'s conventions once with `orboto_get_project_primer(<KEY>)`; "what am I working on?" is `orboto_my_tickets`, "anything about X?" is `orboto_search`.',
         toolset === 'full'
-            ? 'Checklists: `orboto_get_ticket` includes them inline; use `orboto_get_checklists` when you only need the items. A linked-ticket suffix (`↪ [ACME-99]`) means the item is automatically checked/unchecked as that ticket\'s status moves.'
-            : 'Checklists: `orboto_get_ticket` includes them inline. A linked-ticket suffix (`↪ [ACME-99]`) means the item is automatically checked/unchecked as that ticket\'s status moves.',
-        toolset === 'curated'
-            ? 'This is the CURATED tool manifest (the daily high-frequency set). The ENTIRE REST API stays reachable: find any other endpoint + its schema with `orboto_api_search`, then execute it with `orboto_api_call` - permissions are enforced server-side exactly as for named tools. The full named-tool manifest is opt-in: connect with `?toolset=full` (HTTP) or set ORBOTO_MCP_TOOLSET=full (stdio).'
-            : '',
-        'Resources (`orboto://rules`, `orboto://ticket/<key>`, `orboto://doc/<id>`, `orboto://project/<key>`, `orboto://search/<query>`) return read-only Markdown. The `orboto://` URI scheme stays canonical. `orboto://rules` returns the COMPLETE binding rules cap-independently (this instructions block may be truncated by the client). Prompts (`plan-sprint`, `triage-my-tickets`, `summarize-project`, `estimate-ticket`, `find-duplicates`) are one-click guided workflows.',
-        'A few natural parameter spellings (`key`, `query`, `id`, `projectId`, `milestoneId`, `comment`/`message`, `max`, `page`, ...) are silently normalised to the documented name; anything else that still doesn\'t match returns an error naming the tool\'s full parameter list and the closest valid name.',
-        'All writes respect the caller\'s project-level permissions - a 403 means the API rejected the write, not the MCP server.',
-    ].filter((s) => s.length > 0).join(' ');
+            ? '`orboto_get_ticket` includes checklists inline, `orboto_get_checklists` returns only the items.'
+            : 'This is the CURATED tool manifest. The ENTIRE REST API stays reachable: find an endpoint with `orboto_api_search`, run it with `orboto_api_call`; the full manifest is `?toolset=full` (HTTP) or ORBOTO_MCP_TOOLSET=full (stdio).',
+        'Read-only resources: `orboto://ticket/<key>`, `orboto://doc/<id>`, `orboto://project/<key>`, `orboto://search/<query>`.',
+        '`orboto_list_agent_instructions` manages rule blocks for admins; it is not how you read the rules.',
+        'A 403 is the API refusing the write, not this server.',
+    ].join(' ');
 }
-const INSTRUCTIONS_BUDGET = 4000;
+const INSTRUCTIONS_BUDGET = CLIENT_INSTRUCTIONS_CAP;
 const RULES_HEADING = 'Working rules for this workspace:\n';
 const TRUNCATION_MARKER = '\n\n[... rules truncated to fit the client cap - read the COMPLETE rules via the orboto_session_start tool or the orboto://rules resource ...]';
 export function assembleInstructions(head, workingRules, budget = INSTRUCTIONS_BUDGET) {
@@ -174,16 +172,8 @@ export async function buildOrbotoMcpServer(opts) {
         instructions: toolset === 'channel'
             ? [CHANNEL_TOOLSET_INSTRUCTIONS, ...(opts.channel ? [CHANNEL_TOOLSET_WAKE_INSTRUCTIONS] : [])].join('\n\n')
             : toolset === 'minimal'
-                ? [
-                    staticMcpHints(toolset),
-                    'FIRST ACTION: call `orboto_session_start` - it returns the binding workspace rules plus your in-progress work. Re-run it after any context compaction. Non-negotiables: claim or create a ticket before touching code, one commit per ticket with the ticket key in the subject, push after each commit, never mark work done that is not done.',
-                    ...channelHint,
-                ].join('\n\n')
-                : assembleInstructions([
-                    staticMcpHints(toolset),
-                    'FIRST ACTION this session: call the `orboto_session_start` tool - it returns the complete, authoritative binding rules you must follow (plus your in-progress work). Re-run it after any context compaction. If the rules below look cut off, `orboto_session_start` and the `orboto://rules` resource always have the full set. (Do NOT use `orboto_list_agent_instructions` to read the rules - that manages rule blocks for admins.) Core non-negotiables: ticket-first (claim or create a ticket before touching code), one commit per ticket with the ticket key in the subject line, push after each commit, and never mark work done that is not actually done.',
-                    ...channelHint,
-                ].join('\n\n'), workingRules),
+                ? [MANDATORY_FIRST_ACTION, ...channelHint, staticMcpHints(toolset)].join('\n\n')
+                : assembleInstructions([MANDATORY_FIRST_ACTION, ...channelHint, staticMcpHints(toolset)].join('\n\n'), workingRules),
     });
     const nudgeState = createNudgeState(requireSessionStart);
     const regAll = registerWithMetrics(server, client, opts.userAgentSuffix, nudgeState);

package/dist/session-origin.js

@@ -0,0 +1,100 @@
+/**
+ * ORB-2544 - the `x-orboto-origin` header every request of this MCP server
+ * carries: a stdio proxy names the harness that started it (or the origin the
+ * CLI handed over in ORBOTO_ORIGIN), the HTTP server names itself as an
+ * mcp-oauth process; a repository is only ever its basename.
+ */
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { VERSION } from './version.js';
+const KEYS = [
+    ['host', 'host'], ['machine', 'machineId'], ['repo', 'repo'], ['pid', 'pid'], ['start', 'startedAt'], ['client', 'client'], ['version', 'clientVersion'], ['harness', 'harness'],
+];
+/** The header value; empty fields are left out. */
+export function formatOrigin(origin) {
+    const params = new URLSearchParams();
+    for (const [key, field] of KEYS) {
+        const value = origin[field];
+        if (value !== null && value !== undefined && value !== '')
+            params.set(key, String(value));
+    }
+    return params.toString();
+}
+/** The first label of the host name, lower-cased. */
+export function shortHost(raw = hostname()) {
+    const first = raw.trim().toLowerCase().replace(/\.+$/, '').split('.')[0]?.replace(/[^a-z0-9_-]/g, '') ?? '';
+    return first || null;
+}
+/** The repository the working directory sits in, as a basename; the directory's own basename outside a repository. */
+export function repoBasename(cwd = process.cwd()) {
+    let dir = cwd;
+    for (let i = 0; i < 40; i += 1) {
+        if (existsSync(join(dir, '.git')))
+            return basename(dir) || null;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return basename(cwd) || null;
+}
+let machine;
+/** A hashed stable machine id (the platform UUID on macOS, /etc/machine-id elsewhere); null when none is readable. */
+export function machineId(read = readMachineId) {
+    if (machine !== undefined)
+        return machine;
+    const raw = read();
+    machine = raw ? createHash('sha256').update(raw.trim()).digest('hex').slice(0, 16) : null;
+    return machine;
+}
+function readMachineId() {
+    try {
+        if (process.platform === 'darwin') {
+            const out = execFileSync('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8', timeout: 2000 });
+            return /"IOPlatformUUID" = "([^"]+)"/.exec(out)?.[1] ?? null;
+        }
+        for (const path of ['/etc/machine-id', '/var/lib/dbus/machine-id'])
+            if (existsSync(path))
+                return readFileSync(path, 'utf8').trim() || null;
+    }
+    catch { /* an unreadable id leaves the origin without one */ }
+    return null;
+}
+/** The stdio proxy's origin: what the CLI handed over, else the harness that started this process. */
+export function stdioOrigin(env = process.env) {
+    const handed = (env.ORBOTO_ORIGIN ?? '').trim();
+    if (handed) {
+        const params = new URLSearchParams(handed);
+        params.set('client', 'orboto-mcp');
+        params.set('version', VERSION);
+        return params.toString();
+    }
+    return formatOrigin({
+        host: shortHost(), machineId: machineId(), repo: repoBasename(), pid: process.ppid || null,
+        client: 'orboto-mcp', clientVersion: VERSION,
+        harness: env.CLAUDECODE ? 'claude-code' : env.CODEX_THREAD_ID || env.CODEX_SESSION_ID ? 'codex' : 'mcp-stdio',
+    });
+}
+/** The HTTP server's origin: the server process itself, the identity of every connection is its OAuth client. */
+export function httpOrigin() {
+    return formatOrigin({
+        pid: process.pid, startedAt: new Date(Date.now() - Math.round(process.uptime() * 1000)).toISOString(),
+        client: 'orboto-mcp', clientVersion: VERSION, harness: 'mcp-oauth',
+    });
+}
+let mode = 'stdio';
+let cached = null;
+/** The HTTP transport switches the process to its own origin on start. */
+export function useHttpOrigin() {
+    mode = 'http';
+    cached = null;
+}
+/** The header value every request of this process sends. */
+export function originHeader() {
+    if (!cached || cached.mode !== mode)
+        cached = { mode, value: mode === 'http' ? httpOrigin() : stdioOrigin() };
+    return cached.value;
+}

package/dist/session-origin.test.js

@@ -0,0 +1,127 @@
+/**
+ * ORB-2544 - the origin header and one session row per MCP client.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createServer as createNodeServer } from 'node:http';
+import { mkdtempSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHttpServer } from './http-transport.js';
+import { formatOrigin, machineId, repoBasename, shortHost, stdioOrigin } from './session-origin.js';
+import { bindSessionInstance, mcpInstanceToken, releaseSessionInstance, stableClientInstance } from './tools/shared.js';
+import { InboxChannel, SESSION_ENDED_NOTICE } from './inbox-channel.js';
+describe('ORB-2544 - the origin header', () => {
+    it('formats the fields it has and leaves the rest out', () => {
+        expect(formatOrigin({ host: 'build-host', pid: 12, harness: 'claude-code', repo: null })).toBe('host=build-host&pid=12&harness=claude-code');
+    });
+    it('a stdio proxy takes the origin the CLI handed over and names itself as the client', () => {
+        const params = new URLSearchParams(stdioOrigin({ ORBOTO_ORIGIN: 'host=build-host&pid=99&harness=claude-code&client=orboto-cli&version=1.0.0' }));
+        expect(params.get('pid')).toBe('99');
+        expect(params.get('harness')).toBe('claude-code');
+        expect(params.get('client')).toBe('orboto-mcp');
+    });
+    it('reduces the host to its first label and a checkout to the repository basename', () => {
+        expect(shortHost('Build-Host.example.lan.')).toBe('build-host');
+        const root = mkdtempSync(join(tmpdir(), 'origin-'));
+        mkdirSync(join(root, 'sample-repo', '.git'), { recursive: true });
+        mkdirSync(join(root, 'sample-repo', 'apps', 'api'), { recursive: true });
+        expect(repoBasename(join(root, 'sample-repo', 'apps', 'api'))).toBe('sample-repo');
+    });
+    it('hashes the machine id once', () => {
+        const read = vi.fn(() => 'platform-uuid');
+        const first = machineId(read);
+        expect(first === null || /^[0-9a-f]{16}$/.test(first)).toBe(true);
+        expect(machineId(read)).toBe(first);
+    });
+});
+describe('ORB-2544 - one token per MCP client', () => {
+    it('the same account, credential and client keep one token; another client id gets its own; no id falls back', () => {
+        const one = stableClientInstance({ userEmail: 'a@example.com', credential: { kind: 'oauth', id: 'client-1' }, client: 'claude-code@2.0' });
+        expect(one).toMatch(/^mcp-[0-9a-f]{16}$/);
+        expect(stableClientInstance({ userEmail: 'A@example.com', credential: { kind: 'oauth', id: 'client-1' }, client: 'claude-code@2.1' })).toBe(one);
+        expect(stableClientInstance({ userEmail: 'a@example.com', credential: { kind: 'oauth', id: 'client-2' }, client: 'claude-code' })).not.toBe(one);
+        expect(stableClientInstance({ userEmail: 'a@example.com', credential: null })).toBeNull();
+    });
+    it('a bound transport session acts under the stable token until it is released', () => {
+        bindSessionInstance('sid-1', 'mcp-stable');
+        bindSessionInstance('sid-2', 'mcp-stable');
+        expect(mcpInstanceToken(undefined, { sessionId: 'sid-1' })).toBe('mcp-stable');
+        expect(releaseSessionInstance('sid-1')).toEqual({ token: 'mcp-stable', shared: true });
+        expect(releaseSessionInstance('sid-2')).toEqual({ token: 'mcp-stable', shared: false });
+        expect(mcpInstanceToken(undefined, { sessionId: 'sid-1' })).toBe('mcp-sid-1');
+    });
+});
+let server = null;
+let api = null;
+afterEach(async () => {
+    if (server) {
+        const internals = server.__mcp;
+        for (const s of internals?.sessions.values() ?? []) {
+            try {
+                await s.transport.close();
+            }
+            catch { /* ignore */ }
+        }
+        server.close();
+        server = null;
+    }
+    await new Promise((r) => (api ? api.close(() => r()) : r()));
+    api = null;
+});
+describe('ORB-2544 - an MCP client reconnecting five times', () => {
+    it('opens every live-events stream under one token and ends it resumably on each close', async () => {
+        const streams = [];
+        const ended = [];
+        const origins = [];
+        api = createNodeServer((req, res) => {
+            const url = req.url ?? '';
+            if (url.startsWith('/system/mcp/status')) {
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ enabled: true, mcpUseGranted: true, userMcpEnabled: true, userEmail: 'alice@example.com', credential: { kind: 'oauth', id: 'client-1' } }));
+                return;
+            }
+            if (url.startsWith('/sse/mcp-events')) {
+                streams.push(String(req.headers['x-orboto-agent-session'] ?? ''));
+                origins.push(String(req.headers['x-orboto-origin'] ?? ''));
+                res.writeHead(200, { 'content-type': 'text/event-stream' });
+                res.end();
+                return;
+            }
+            if (url.startsWith('/v1/agent/end-session')) {
+                ended.push(String(req.headers['x-orboto-agent-session'] ?? ''));
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end('{}');
+                return;
+            }
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(url.startsWith('/agent-instructions') ? JSON.stringify({ instructions: '' }) : '{}');
+        });
+        await new Promise((r) => api.listen(0, 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));
+        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) {
+            const res = await fetch(`${base}/mcp`, { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: 'Bearer orb_alice', 'user-agent': 'claude-code/2.0' }, body: init });
+            const sid = res.headers.get('mcp-session-id');
+            await res.text();
+            await vi.waitFor(() => expect(streams.length).toBe(i + 1));
+            await fetch(`${base}/mcp`, { method: 'DELETE', headers: { authorization: 'Bearer orb_alice', 'mcp-session-id': sid } });
+            await vi.waitFor(() => expect(ended.length).toBe(i + 1));
+        }
+        const expected = stableClientInstance({ userEmail: 'alice@example.com', credential: { kind: 'oauth', id: 'client-1' }, client: 'claude-code' });
+        expect(new Set(streams)).toEqual(new Set([expected]));
+        expect(new Set(ended)).toEqual(new Set([expected]));
+        expect(new URLSearchParams(origins[0]).get('harness')).toBe('mcp-oauth');
+    });
+});
+describe('ORB-2544 - the end notice on the wake channel', () => {
+    it('emits the notice once and stops the channel', async () => {
+        const notification = vi.fn(async () => { });
+        const channel = new InboxChannel({ baseUrl: 'http://127.0.0.1:1', apiKey: 'k', instanceToken: 'tok', mcp: { server: { notification } }, fetchFn: (() => new Promise(() => { })) });
+        await channel.deliverNotice(SESSION_ENDED_NOTICE, 'The operator ended this orboto session (stale).');
+        expect(notification).toHaveBeenCalledTimes(1);
+        expect(channel.closed).toBe(true);
+    });
+});