@orboto/mcp 0.193.0 → 0.194.0

package/dist/event-bridge.js

@@ -1,13 +1,10 @@
-const HEARTBEAT_GRACE_MS = 90_000; // 3× the server's 30s ping
+const HEARTBEAT_GRACE_MS = 90_000;
 const OVERFLOW_THRESHOLD = 100;
 const RECONNECT_DELAY_MS = 2_000;
 /** Map a raw event to the set of `orboto://` URIs that should be
  *  notified. Returns an empty array for events that don't map to any
  *  subscribed resource shape (no-op). */
 export function eventToUris(event) {
-    // Ticket-level events. Include the ticket URI (when the payload
-    // carries a ticketKey) AND the project URI so a project-scoped
-    // subscriber learns about activity inside it.
     if (event.type === 'ticket:created' || event.type === 'ticket:updated' || event.type === 'ticket:deleted'
         || event.type === 'ticket:activity'
         || event.type === 'comment:created' || event.type === 'comment:updated' || event.type === 'comment:deleted'
@@ -17,16 +14,8 @@ export function eventToUris(event) {
         const key = event.payload?.ticketKey;
         if (key)
             uris.push(`orboto://ticket/${key}`);
-        // The MCP bridge doesn't know each project's key; the project URI
-        // form uses the projectKey which isn't on the wire. We fall back
-        // to projectId, which the resource handler accepts via
-        // resolveProjectByKey's lookup path.
         if (event.projectId)
             uris.push(`orboto://project/${event.projectId}`);
-        // ORB-962 - hand-off "wake on close". When a ticket:updated
-        // payload's statusCategory is `done`, emit an additional URI
-        // dedicated to close-events so subscribers don't have to filter
-        // every ticket:updated client-side.
         if (event.type === 'ticket:updated' && key && event.payload?.statusCategory === 'done') {
             uris.push(`orboto://handoff/closed/${key}`);
         }
@@ -35,19 +24,9 @@ export function eventToUris(event) {
     if (event.type === 'project:bulk-activity' || event.type === 'member:joined' || event.type === 'member:removed') {
         return event.projectId ? [`orboto://project/${event.projectId}`] : [];
     }
-    // ORB-1616 - dispatcher wake-on-unblock. Project-scoped (not per-ticket
-    // like `handoff/closed`) because a worker pool doesn't know in advance
-    // which ticket will become ready next - it subscribes to the PROJECT's
-    // ready channel and pulls via `orboto_work_next` on push. The
-    // notification carries no payload (the resource-subscription protocol
-    // never does) - `ticket.ready` is the webhook channel that carries the
-    // actual ticket key for external consumers.
     if (event.type === 'ticket:ready') {
         return event.projectId ? [`orboto://ready/${event.projectId}`] : [];
     }
-    // ORB-1616 - escalation push: collision / failed checks / review
-    // rejection / missing decision / git failure. Project-scoped, same
-    // reasoning as `ready` above.
     if (event.type === 'agent_escalation:raised') {
         return event.projectId ? [`orboto://escalation/${event.projectId}`] : [];
     }
@@ -57,9 +36,6 @@ export function eventToUris(event) {
     if (event.type === 'timer:changed') {
         return [`orboto://timer`];
     }
-    // ORB-964 - agent broadcast. Map to the scope-specific URI so
-    // subscribers can register interest in just the scope they care
-    // about. For workspace scope, scopeId is the empty string.
     if (event.type === 'agent_broadcast:posted') {
         const p = event.payload;
         if (p?.scopeType) {
@@ -68,22 +44,13 @@ export function eventToUris(event) {
         }
         return [];
     }
-    // ORB-970 - quorum lifecycle.
     if (event.type === 'agent_quorum:opened' || event.type === 'agent_quorum:approved') {
         const p = event.payload;
         return p?.topicKey ? [`orboto://quorum/${p.topicKey}`] : [];
     }
-    // ORB-706 - mention real-time push. Every notification row firing
-    // for the calling user surfaces on `orboto://user/me/notifications`.
-    // The API-side SSE bridge already filters notification:new events
-    // to only deliver them to the matching user's session, so this
-    // URI is naturally per-user-scoped.
     if (event.type === 'notification:new') {
         return [`orboto://user/me/notifications`];
     }
-    // restore:progress / system-task:* are user-scoped infrastructure
-    // events that don't map to a public resource URI today. The MCP
-    // bridge ignores them - the user gets them via the in-app UI.
     return [];
 }
 export class EventBridge {
@@ -137,13 +104,8 @@ export class EventBridge {
     }
     async consume() {
         const fetchFn = this.opts.fetchFn ?? fetch;
-        // Fresh abort controller per attempt so close() during a retry
-        // window doesn't leak the previous signal.
         this.abort = new AbortController();
         const url = `${this.opts.baseUrl.replace(/\/$/, '')}/sse/mcp-events`;
-        // ORB-1470 - resolve the current bearer per connect so a rotated OAuth
-        // access token is picked up on the next reconnect instead of pinning the
-        // stream to the session's creation-time token.
         const bearer = this.opts.tokenProvider
             ? await this.opts.tokenProvider.getAccessToken()
             : (this.opts.apiKey ?? '');
@@ -164,9 +126,6 @@ export class EventBridge {
         let buf = '';
         let lastFrame = Date.now();
         const heartbeat = setInterval(() => {
-            // If the server's ping stops arriving the underlying TCP
-            // connection might be dead silent (Coolify / NAT timeout). Force
-            // a reconnect so we don't sit forever on a zombie stream.
             if (Date.now() - lastFrame > HEARTBEAT_GRACE_MS) {
                 try {
                     this.abort.abort();
@@ -175,8 +134,6 @@ export class EventBridge {
             }
         }, 30_000);
         try {
-            // Read until the stream ends, the request was aborted, or the
-            // process is shutting down.
             // eslint-disable-next-line no-constant-condition
             while (true) {
                 const { done, value } = await reader.read();
@@ -184,9 +141,6 @@ export class EventBridge {
                     break;
                 lastFrame = Date.now();
                 buf += decoder.decode(value, { stream: true });
-                // SSE frames are split by '\n\n'. We handle both 'data: ...'
-                // and ': ping' (comment / heartbeat) lines; the latter become
-                // a no-op event.
                 let idx;
                 // eslint-disable-next-line no-cond-assign
                 while ((idx = buf.indexOf('\n\n')) !== -1) {

package/dist/event-bridge.test.js

@@ -1,16 +1,5 @@
 /**
  * ORB-940 - EventBridge unit tests.
- *
- * Three concerns:
- *   1. Event → URI mapping (pure function, no I/O)
- *   2. Dispatch behaviour - subscribed URIs trigger
- *      sendResourceUpdated, unsubscribed do not
- *   3. Backpressure - > 100 forwarded events → one
- *      sendResourceListChanged instead of more updates
- *
- * The actual SSE consumption path is exercised via a streaming
- * mock fetch; the response body is a ReadableStream that yields
- * one frame per chunk, then closes.
  */
 import { describe, expect, it, vi } from 'vitest';
 import { EventBridge, eventToUris } from './event-bridge.js';
@@ -64,9 +53,6 @@ describe('eventToUris', () => {
         expect(eventToUris({ type: 'timer:changed', userId: 'u1' })).toEqual(['orboto://timer']);
     });
     it('maps notification:new to the calling user\'s notifications resource (ORB-706)', () => {
-        // The mcp-events SSE handler already filters notification:new
-        // to only deliver to the matching user; the URI is per-user
-        // scoped by construction.
         expect(eventToUris({ type: 'notification:new', userId: 'u1' })).toEqual(['orboto://user/me/notifications']);
     });
     it('returns [] for restore-progress / system-task events (infrastructure-only)', () => {
@@ -107,7 +93,6 @@ describe('EventBridge.dispatch', () => {
             log: () => { },
         });
         bridge.start();
-        // Give the microtask loop a couple of ticks to drain.
         await new Promise((r) => setTimeout(r, 50));
         bridge.close();
         expect(mcp.sendResourceUpdated).toHaveBeenCalledTimes(1);
@@ -116,8 +101,6 @@ describe('EventBridge.dispatch', () => {
     it('falls back to sendResourceListChanged after the overflow threshold', async () => {
         const mcp = mockMcp();
         const subscriptions = new Set(['orboto://timer']);
-        // 101 timer events - one more than the threshold so the 101st
-        // round trips through the list_changed path.
         const frames = Array.from({ length: 101 }, () => ({ type: 'timer:changed', userId: 'u1' }));
         const fetchFn = vi.fn().mockResolvedValueOnce(mockSseResponse(frames));
         const bridge = new EventBridge({
@@ -137,8 +120,6 @@ describe('EventBridge.dispatch', () => {
     it('survives malformed frames without aborting the stream', async () => {
         const mcp = mockMcp();
         const subscriptions = new Set(['orboto://ticket/ORB-42']);
-        // Inject one bad frame between two good ones - the bad frame is
-        // a non-JSON 'data:' line, which the bridge should skip.
         const encoder = new TextEncoder();
         const stream = new ReadableStream({
             start(controller) {

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

@@ -102,11 +102,9 @@ describe('ORB-1576 - session binding', () => {
     it('rotation adopted for the SAME user, rejected for a different user', async () => {
         const base = await start();
         const sid = await initSession(base, 'orb_alice');
-        // Same user, rotated token -> adopted (200).
         const rotated = await post(base, NON_INIT, { authorization: 'Bearer orb_alice_rot', 'mcp-session-id': sid });
         expect(rotated.status).toBe(200);
         await rotated.text();
-        // Different user with a VALID token -> 401, holder not adopted.
         const hijack = await post(base, NON_INIT, { authorization: 'Bearer orb_mallory', 'mcp-session-id': sid });
         expect(hijack.status).toBe(401);
         await hijack.text();
@@ -142,10 +140,9 @@ describe('ORB-1576 - request body cap', () => {
             await res.text();
         }
         catch {
-            errored = true; // connection reset mid-write is an acceptable outcome too
+            errored = true;
         }
         expect(errored || status === 400).toBe(true);
     });
 });
-// vitest fake-timer hygiene for the bridge internals
 void vi;

package/dist/http-transport.js

@@ -1,33 +1,7 @@
 /**
  * ORB-244 Phase A - Streamable HTTP transport for the MCP server.
  *
- * Used by the Self-Hosted-inline delivery variant: a separate
- * container alongside the API, listening on `ORBOTO_MCP_PORT` (default
- * 3100). The reverse proxy routes `/mcp` to this port.
- *
- * Per-request auth: every POST must carry `Authorization: Bearer
- * orb_*` in the header. We build one `McpServer` per session so each
- * session gets its own OrbotoClient bound to that session's token -
- * no mid-session token mutation, no cross-session leakage.
- *
- * Sessions are indexed by the MCP-spec-mandated `mcp-session-id`
- * header the transport generates on initialise. Closing the session
- * deletes the transport; a fresh initialise spins up a new one.
- *
- * ORB-1353 - session resilience. The in-memory session map is wiped on every
- * api restart/deploy, which used to invalidate every connected client at once
- * (a real ZCode adapter then dead-looped on the resulting 404 for hours). Two
- * server-side layers fix this: (1) the session registry is PERSISTED to the db
- * via `/system/mcp/sessions`, so a request carrying a session id we no longer
- * hold in memory is rehydrated under the SAME id after a restart; (2) an
- * unknown session id under otherwise-valid auth is transparently AUTO-ADOPTED
- * under a fresh id (MCP tool calls are stateless per-call, so re-establishing
- * loses nothing). The ORB-1324 404 re-initialise contract stays ONLY for
- * requests without valid auth; the kill-switch + mcp:use preflight still fires
- * on every (re)hydration.
- *
- * No Express dep - Node's built-in http server is enough for a
- * single-route MCP endpoint and keeps the production image small.
+ * @see ORB-1353, ORB-1324
  */
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
@@ -112,19 +86,6 @@ export function clientInfoLabel(body) {
 /**
  * ORB-941 - graceful close of every active MCP session when the
  * workspace kill-switch (`system_config.mcp_enabled`) flips to disabled.
- *
- * The MCP spec has no standard `notifications/server/closing` method, so
- * the closest correct behaviour is: emit a best-effort logging
- * notification (visible to clients that negotiated the logging
- * capability) explaining WHY, then close the transport. Closing the
- * transport ends the SSE stream; the client's next request lands on the
- * unknown-session 404 branch, which per the Streamable-HTTP spec
- * triggers a transparent re-initialise - and our per-session preflight
- * then refuses that re-init with the clear "administrator has disabled
- * MCP access" error. So an in-flight session is dropped promptly and the
- * client gets an actionable reason rather than an opaque hang.
- *
- * Exported for unit testing with fake sessions.
  */
 export async function closeAllMcpSessions(sessions, reason) {
     let closed = 0;
@@ -190,25 +151,10 @@ function sendError(res, status, message, extraHeaders) {
 /** ORB-957 - RFC 6750 §3 WWW-Authenticate challenge for /mcp 401s.
  *  MCP-aware clients (Claude Desktop, Cursor, VS Code Copilot) follow
  *  the resource_metadata URL to auto-discover the OAuth flow.
- *
- *  The resource_metadata URL must point at the PUBLIC host the AI
- *  client can reach - NOT the internal `http://api:3000` baseUrl the
- *  MCP container uses to talk to the API. We derive the public URL
- *  from the incoming request's Host + X-Forwarded-Proto headers,
- *  which the reverse proxy (nginx → web container) sets for us.
- *  Falls back to baseUrl only when the headers are missing (local
- *  dev / direct connections).
  */
 function wwwAuthChallenge(req, baseUrl, error, description) {
     const host = req.headers['x-forwarded-host']
         || req.headers.host;
-    // Multi-layer proxies (Coolify's outer Caddy → web container's nginx
-    // → mcp container) sometimes lose the original scheme. Trust an
-    // explicit X-Forwarded-Proto header if present; otherwise default to
-    // https UNLESS the host is obviously localhost / a private IP (local
-    // dev). The MCP container only runs in TLS-terminated deployments,
-    // so https-by-default is right for production + lets local dev
-    // explicitly send X-Forwarded-Proto=http if needed.
     const hostIsLocal = !!host && /^(localhost|127\.|::1|192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(host);
     const protoHeader = req.headers['x-forwarded-proto'];
     const proto = protoHeader || (hostIsLocal ? 'http' : 'https');
@@ -219,45 +165,16 @@ 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 }) {
-    // One transport + server per MCP session. The session-id comes from
-    // the transport's `onsessioninitialized` hook, which fires after
-    // the `initialize` request lands and we've minted a fresh id.
     const sessions = new Map();
-    // ORB-1353 - persisted-session store (survives api restarts). Defaults to
-    // the api-backed store; tests inject a fake.
     const store = sessionStore ?? createApiSessionStore(baseUrl);
-    // Build the per-session core (client + subscription set + MCP server +
-    // event bridge) bound to a token. Shared by the new-session, rehydrate, and
-    // adopt paths so they can't drift apart.
     async function buildSessionCore(tokenHolder, userAgentSuffix, toolset) {
-        // ORB-1470 - bind every long-lived per-session consumer (kill-switch
-        // client, tool-handler client, SSE bridge) to the SAME mutable holder so
-        // one `holder.current = <request bearer>` update rotates the bearer for
-        // all of them at once.
         const tokenProvider = holderTokenProvider(tokenHolder);
         const sessionClient = new OrbotoClient({ baseUrl, tokenProvider, userAgentSuffix });
-        // ORB-940 - per-session subscription set + live-event bridge. The set is
-        // mutated by resources/subscribe + resources/unsubscribe handlers inside
-        // the McpServer; the bridge reads it to decide which incoming API events
-        // deserve a push.
-        //
-        // ORB-1353 subscription boundary: a rehydrated (layer 1) or adopted
-        // (layer 2) session ALWAYS starts with an empty subscription set + a fresh
-        // bridge. Live subscription state is per-session in-memory state tied to a
-        // now-dead SSE socket, so it cannot be carried across an api restart even
-        // for the same session id - per the MCP spec, re-subscribing after a
-        // session change is the client's job. Rehydrating under the SAME id keeps
-        // the deploy case coherent (the client's own session bookkeeping stays
-        // valid and its re-subscribe resumes pushes); adoption gives a new id so
-        // the client treats it as a fresh session and re-subscribes from scratch.
         const subscriptions = new Set();
         const mcp = await buildOrbotoMcpServer({ baseUrl, tokenProvider, userAgentSuffix, subscriptions, toolset });
         const bridge = new EventBridge({ baseUrl, tokenProvider, mcp, subscriptions });
         return { sessionClient, subscriptions, mcp, bridge };
     }
-    // Rehydrate/adopt: stand up a session bound to `token` and force it into the
-    // initialized state under `chosenSessionId` WITHOUT replaying the initialize
-    // handshake, so the client's in-flight non-init request validates against it.
     /** ORB-1576 - resolve a bearer's owner identity via the status preflight;
      *  null on any failure (invalid token, MCP off, network) = fail closed. */
     async function resolveUserEmail(token) {
@@ -283,18 +200,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
         bridge.start();
         return session;
     }
-    // ORB-941 / ORB-942 - MCP kill-switch poll. Two kill-switches ride the
-    // same `/system/mcp/status` probe while sessions are live:
-    //   - workspace-wide (`system_config.mcp_enabled`, ORB-941): an admin
-    //     flip closes EVERY in-flight session (any session's response is
-    //     authoritative for the whole workspace).
-    //   - per-user (`users.mcp_enabled`, ORB-942): a user flipping their own
-    //     opt-out closes only THAT user's sessions. Since the flag is
-    //     per-identity, each session is probed with its own token and the
-    //     `userMcpEnabled` field is read from the same response.
-    // New sessions (and rehydrate/adopt) are already refused at preflight, so
-    // the poll only needs to reap existing sessions. Only polls while sessions
-    // exist → zero cost when idle. Interval is env-tunable for tests.
     const pollMs = Number(process.env.ORBOTO_MCP_KILLSWITCH_POLL_MS ?? 30_000);
     async function pollKillSwitch() {
         if (sessions.size === 0)
@@ -304,8 +209,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             try {
                 const status = await session.client.get('/system/mcp/status');
                 if (!status.enabled) {
-                    // Workspace-wide off wins and is authoritative for everyone -
-                    // close all sessions and stop probing.
                     await closeAllMcpSessions(sessions.values(), 'the workspace administrator has disabled MCP access.');
                     return;
                 }
@@ -321,23 +224,13 @@ export function createHttpServer({ baseUrl, sessionStore }) {
         }
     }
     const killSwitchTimer = setInterval(() => { void pollKillSwitch(); }, pollMs);
-    // Don't let the poll keep the process (or a test) alive on its own.
     killSwitchTimer.unref?.();
     const server = createServer(async (req, res) => {
-        // Health probe - stays cheap, zero-auth so docker healthchecks
-        // don't need a token. Doesn't reveal anything about config.
         if (req.method === 'GET' && req.url === '/health') {
             res.writeHead(200, { 'content-type': 'application/json' });
             res.end(JSON.stringify({ status: 'ok' }));
             return;
         }
-        // Route: all MCP traffic lands on /mcp per spec convention.
-        // Anything else is 404 so an accidental probe at / doesn't leak
-        // the transport. ORB-1520 - a query string is allowed (and used):
-        // `?toolset=full` opts a connection into the full named-tool
-        // manifest without server-side env access. The param rides on EVERY
-        // request from a client configured with that URL, so it needs no
-        // session persistence.
         const requestUrl = new URL(req.url ?? '', 'http://localhost');
         if (requestUrl.pathname !== '/mcp') {
             sendError(res, 404, 'Not found');
@@ -345,25 +238,12 @@ export function createHttpServer({ baseUrl, sessionStore }) {
         }
         const toolset = resolveToolset(requestUrl.searchParams.get('toolset')
             ?? req.headers['x-orboto-toolset'], process.env.ORBOTO_MCP_TOOLSET);
-        // Reject non-POST + non-DELETE. GET on /mcp is legal per the spec
-        // (SSE resumption) but that is unimplemented here.
-        //
-        // ORB-1424 - an UNAUTHENTICATED GET/HEAD on /mcp is almost always an
-        // OAuth-discovery probe (rmcp/Codex hit the resource to read the
-        // WWW-Authenticate challenge). Answering a bare 405 there left the
-        // client without the resource_metadata pointer and logged a noisy
-        // "405 Method Not Allowed". Return 401 + WWW-Authenticate instead so
-        // the probe discovers the OAuth flow cleanly. An AUTHENTICATED GET
-        // (a real client attempting SSE resumption) still 405s - it already
-        // holds a token and needs no discovery pointer, so spec-conform
-        // clients (Claude Desktop / Cursor) do not regress.
         if (req.method !== 'POST' && req.method !== 'DELETE') {
             const probeAuth = (req.headers.authorization ?? '');
             const hasBearer = probeAuth.startsWith('Bearer ') && probeAuth.slice(7).trim().length > 0;
             if ((req.method === 'GET' || req.method === 'HEAD') && !hasBearer) {
                 const challenge = wwwAuthChallenge(req, baseUrl, 'invalid_request', 'Bearer token required');
                 if (req.method === 'HEAD') {
-                    // HEAD carries no body per HTTP semantics.
                     res.writeHead(401, { 'content-type': 'application/json', 'WWW-Authenticate': challenge });
                     res.end();
                 }
@@ -376,16 +256,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             res.end();
             return;
         }
-        // Extract the bearer token. Per-session auth - the same token
-        // is used for the session's whole lifetime (reconnect without
-        // re-init would land on a new session id and fresh auth anyway).
-        //
-        // Two acceptable token shapes:
-        //   orb_* - service-account API key (operator-minted)
-        //   JWT (3 segs) - OAuth-issued access token from the /oauth/
-        //                    authorize + /oauth/token flow (ORB-957)
-        // Both go to the API unchanged; the API's authenticate decorator
-        // distinguishes them.
         const authHeader = (req.headers.authorization ?? '');
         const token = authHeader.startsWith('Bearer ')
             ? authHeader.slice(7).trim()
@@ -397,32 +267,23 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             return;
         }
         const sessionId = (req.headers['mcp-session-id'] ?? '');
-        // DELETE is the client's explicit session-close. We forward it
-        // to the transport's handleRequest which tears down cleanly.
         if (req.method === 'DELETE') {
             const existing = sessions.get(sessionId);
             if (existing) {
-                // ORB-1576 - only the session's owner may tear it down (a leaked id
-                // must not let someone kill or probe another user's session).
                 const presented = await resolveUserEmail(token);
                 if (!presented || presented !== existing.userEmail) {
                     return sendError(res, 404, 'Unknown MCP session');
                 }
             }
-            // ORB-1353 - drop the persisted row too so a closed session doesn't
-            // linger until the retention sweep. Best-effort + scoped to the caller.
             void store.remove(token, sessionId).catch(() => { });
             if (existing) {
                 await existing.transport.handleRequest(req, res);
                 return;
             }
-            // Not in memory - e.g. the client is closing a session we only know from
-            // persistence after a restart. Acknowledge the close idempotently.
             res.writeHead(200, { 'content-type': 'application/json' });
             res.end(JSON.stringify({ ok: true }));
             return;
         }
-        // POST path. Parse body so we can route (new-session vs. existing).
         let body;
         try {
             body = await readJsonBody(req);
@@ -434,36 +295,16 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             ?.split('/')[0] || undefined;
         const userAgent = req.headers['user-agent'];
         if (sessionId && sessions.has(sessionId)) {
-            // Existing session - hand straight to its transport.
             const session = sessions.get(sessionId);
-            // ORB-1470 - adopt the bearer the client presents on THIS request. The
-            // client's OAuth layer rotates its short-lived (1h) access token; without
-            // this the session stays pinned to the token captured at creation and
-            // dead-ends with a 401 "OAuth access token expired" once that token ages
-            // out, even though the request carried a valid refreshed bearer. Updating
-            // the shared holder rotates the bearer for the tool-handler client, the
-            // kill-switch client, and the SSE bridge in one assignment.
             if (session.tokenHolder.current !== token) {
-                // The client rotated its access token mid-session (the exact case that
-                // used to brick the session). ORB-1576 - adopt the new bearer ONLY
-                // after it resolves to the session owner's identity: a session id
-                // plus ANY valid token must not hijack the session's subscription set
-                // / token holder (the id is a 122-bit UUID, but a leaked id is no
-                // longer a capability on its own).
                 const presented = await resolveUserEmail(token);
                 if (!presented || presented !== session.userEmail) {
                     return sendError(res, 401, 'Bearer does not match the session owner');
                 }
-                // Breadcrumb to stderr - Sentry lives on the api side - so operators
-                // can see rotations are being absorbed, not re-hitting the pinned-
-                // token 401. Low-noise: only on an actual change.
                 process.stderr.write(`[orboto-mcp] session ${sessionId} bearer rotated - adopting client's current access token\n`);
                 session.tokenHolder.current = token;
             }
             await session.transport.handleRequest(req, res, body);
-            // ORB-1353 - slide the persistence TTL on activity so an actively-used
-            // session never idle-expires. Throttled + fire-and-forget so it adds no
-            // latency and no per-call write storm.
             const now = Date.now();
             if (now - session.lastTouchAt >= TOUCH_THROTTLE_MS) {
                 session.lastTouchAt = now;
@@ -471,28 +312,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             }
             return;
         }
-        // ORB-1175 / ORB-1324 / ORB-1353 - the client presented a session id we
-        // don't hold in memory. The common cause is a deploy: the MCP container
-        // restarted and lost its in-memory `sessions` map, so every connected
-        // client's session id is now unknown. Three outcomes on a non-init request,
-        // decided by whether the token is valid and whether the id is a persisted
-        // session owned by that token:
-        //
-        //   - no valid auth (or MCP disabled / mcp:use missing) → keep the ORB-1324
-        //     404 so spec-conform clients transparently re-initialise (and hit the
-        //     clear preflight error on the re-init path). NO WWW-Authenticate: the
-        //     token, not the session, is the thing to fix only when it's actually
-        //     invalid - which the re-init preflight then challenges.
-        //   - valid auth + persisted session owned by caller → REHYDRATE under the
-        //     SAME id (layer 1): the deploy is invisible to a well-behaved client.
-        //   - valid auth + unknown id → AUTO-ADOPT under a fresh id (layer 2): a
-        //     buggy client that keeps replaying a dead id self-heals instead of
-        //     dead-looping on the 404. MCP tool calls are stateless per-call, so
-        //     silently re-establishing the session loses nothing.
-        //
-        // The preflight below enforces the kill-switch (ORB-941) + per-user mcp:use
-        // on EVERY rehydrate/adopt, exactly like a fresh session - a disabled
-        // workspace refuses adopted sessions (they fall to the 404).
         if (sessionId && !isInitializeRequest(body)) {
             const preflightClient = new OrbotoClient({ baseUrl, apiKey: token, userAgentSuffix });
             let authValid = false;
@@ -503,8 +322,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                 callerEmail = preflight.userEmail;
             }
             catch {
-                // Invalid token, MCP disabled, or mcp:use missing → refuse to
-                // re-establish; fall back to the re-initialise 404.
                 authValid = false;
             }
             let isPersisted = false;
@@ -513,8 +330,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                     isPersisted = await store.resolve(token, sessionId);
                 }
                 catch {
-                    // Store hiccup - treat as not-persisted and let adoption handle it
-                    // (auth is already valid, so re-establishing is safe).
                     isPersisted = false;
                 }
             }
@@ -524,21 +339,13 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             }
             if (action === 'rehydrate') {
                 const session = await establishForcedSession({ current: token }, userAgentSuffix, sessionId, callerEmail, toolset);
-                // Touch persistence so the TTL slides; same id, so no adoptedFrom.
                 void store.register(token, { sessionId, userAgent }).catch(() => { });
                 await session.transport.handleRequest(req, res, body);
                 return;
             }
-            // action === 'adopt' - mint a fresh id and re-establish under it.
             const newSessionId = randomUUID();
             const session = await establishForcedSession({ current: token }, userAgentSuffix, newSessionId, callerEmail, toolset);
-            // Rewrite the in-flight request's session header so the transport
-            // validates it against the fresh id AND the response advertises the new
-            // id. A well-behaved client migrates to it; a client that keeps sending
-            // the dead id simply gets re-adopted each call - self-healing either way.
             overrideSessionIdHeader(req, newSessionId);
-            // Record the adoption (old id, new id, client). Stderr here; the api
-            // upsert emits the Sentry breadcrumb (Sentry lives on the api side).
             process.stderr.write(`[orboto-mcp] auto-adopted stale session ${sessionId} → ${newSessionId} (client=${userAgent ?? 'unknown'})\n`);
             void store
                 .register(token, { sessionId: newSessionId, userAgent, adoptedFrom: sessionId })
@@ -547,14 +354,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             return;
         }
         if (!sessionId && isInitializeRequest(body)) {
-            // New session - mint a transport + server pair bound to this
-            // request's token, register with the session map once
-            // `onsessioninitialized` fires.
-            // Preflight: verify mcp:use + mcp_enabled BEFORE we stand up the server,
-            // so a refused session costs nothing. If either fails we refuse at the
-            // transport level - much clearer than letting the first tool call 403.
-            // WWW-Authenticate included on 401-shape failures so the client can
-            // auto-discover OAuth.
             const preflightClient = new OrbotoClient({ baseUrl, apiKey: token, userAgentSuffix });
             let ownerEmail;
             try {
@@ -565,12 +364,8 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                     'WWW-Authenticate': wwwAuthChallenge(req, baseUrl, 'invalid_token', err.message),
                 });
             }
-            // ORB-1470 - the session's mutable bearer holder starts at this request's
-            // token and is updated to the client's current bearer on every later call.
             const tokenHolder = { current: token };
             const { sessionClient, mcp, bridge } = await buildSessionCore(tokenHolder, userAgentSuffix, toolset);
-            // "name@version" of the client's declared clientInfo, for observability
-            // of which adapter owns the session.
             const clientInfo = clientInfoLabel(body);
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: () => randomUUID(),
@@ -579,8 +374,6 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                         transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail: ownerEmail, lastTouchAt: Date.now(),
                     });
                     bridge.start();
-                    // ORB-1353 - persist the freshly-minted session so it survives an
-                    // api restart (a later request with this id then rehydrates).
                     void store
                         .register(token, { sessionId: sid, clientInfo, userAgent })
                         .catch(() => { });
@@ -595,14 +388,9 @@ export function createHttpServer({ baseUrl, sessionStore }) {
             await transport.handleRequest(req, res, body);
             return;
         }
-        // Neither an init nor a known session - the client is confused.
         sendError(res, 400, 'Missing mcp-session-id header or initialize request');
     });
-    // Stop the kill-switch poll when the HTTP server is torn down.
     server.on('close', () => clearInterval(killSwitchTimer));
-    // ORB-1353 - expose the in-memory registry + store for tests to drive the
-    // restart-simulation (clear `sessions` to mimic a process restart while the
-    // injected store keeps its persisted rows) and to close lingering sessions.
     server.__mcp = { sessions, store };
     return server;
 }