@orboto/mcp 0.192.0 → 0.194.0

package/dist/http-transport.test.js

@@ -26,10 +26,6 @@ describe('ORB-1175 - stale MCP session recovery', () => {
             body: NON_INIT,
         });
         expect(res.status).toBe(404);
-        // ORB-1324 - NO WWW-Authenticate: the token is fine, only the session is
-        // gone. Attaching an auth challenge made clients kick off a manual OAuth
-        // re-auth instead of the automatic re-initialise the 404 already signals.
-        // (Token expiry is still caught on the re-init path's preflight.)
         expect(res.headers.get('www-authenticate')).toBeNull();
         const body = await res.json();
         expect(body.error).toMatch(/reinitialize/i);
@@ -68,7 +64,6 @@ describe('ORB-1424 - GET /mcp OAuth-discovery probe', () => {
         });
         expect(res.status).toBe(405);
         expect(res.headers.get('allow')).toBe('POST, DELETE');
-        // A held token needs no auth challenge on the 405.
         expect(res.headers.get('www-authenticate')).toBeNull();
     });
 });
@@ -96,7 +91,6 @@ describe('ORB-941 - graceful close of in-flight MCP sessions on kill-switch', ()
         expect(b.log).toHaveBeenCalledOnce();
         expect(a.close).toHaveBeenCalledOnce();
         expect(b.close).toHaveBeenCalledOnce();
-        // The reason is surfaced to the client in the notification payload.
         expect(a.log.mock.calls[0][0]).toMatchObject({ level: 'warning' });
         expect(a.log.mock.calls[0][0].data).toContain('disabled by admin.');
     });
@@ -108,13 +102,9 @@ describe('ORB-941 - graceful close of in-flight MCP sessions on kill-switch', ()
         expect(s.close).toHaveBeenCalledOnce();
     });
 });
-// ---------------------------------------------------------------------------
-// ORB-1353 - session resilience: persist across restarts + auto-adopt.
-// ---------------------------------------------------------------------------
 describe('ORB-1353 - classifyUnknownSession (pure decision)', () => {
     it('keeps the 404 re-init contract when auth is invalid', () => {
         expect(classifyUnknownSession({ hasValidAuth: false, isPersistedForCaller: false })).toBe('reinit-404');
-        // Even a "persisted" id must not resurrect without valid auth.
         expect(classifyUnknownSession({ hasValidAuth: false, isPersistedForCaller: true })).toBe('reinit-404');
     });
     it('rehydrates a persisted session owned by the caller (layer 1)', () => {
@@ -134,25 +124,17 @@ describe('ORB-1353 - clientInfoLabel', () => {
         expect(clientInfoLabel(null)).toBeUndefined();
     });
 });
-// A controllable in-process fake of the api endpoints the transport touches:
-// preflight (/system/mcp/status), the working-rules fetch, and the event
-// bridge's SSE endpoint. DB-free - the persisted-session store is injected
-// separately so a "restart" is just clearing the in-memory registry.
 function fakeApi(opts = {}) {
     const state = {
         enabled: opts.enabled ?? true,
         mcpUseGranted: opts.mcpUseGranted ?? true,
-        // ORB-942 - per-user MCP opt-out. Defaults on so existing flows are unaffected.
         userMcpEnabled: opts.userMcpEnabled ?? true,
-        // ORB-1470 - record every Authorization header the api sees so a test can
-        // assert which bearer the transport forwarded upstream.
         seenAuth: [],
     };
     const api = createNodeServer((req, res) => {
         const url = req.url ?? '';
         if (url.startsWith('/system/mcp/status')) {
             state.seenAuth.push((req.headers.authorization ?? ''));
-            // A token of `Bearer invalid` models an expired/invalid credential.
             if ((req.headers.authorization ?? '') === 'Bearer invalid') {
                 res.writeHead(401, { 'content-type': 'application/json' });
                 res.end(JSON.stringify({ error: 'invalid token' }));
@@ -173,7 +155,6 @@ function fakeApi(opts = {}) {
             return;
         }
         if (url.startsWith('/sse/mcp-events')) {
-            // Empty stream - the bridge reconnects on close, cleared by session close.
             res.writeHead(200, { 'content-type': 'text/event-stream' });
             res.end();
             return;
@@ -208,7 +189,6 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
     let api = null;
     const cleanups = [];
     afterEach(async () => {
-        // Close any live MCP sessions so their event-bridge retry timers don't leak.
         for (const c of cleanups.splice(0))
             c();
         if (server) {
@@ -245,18 +225,13 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
     it('rehydrates the SAME session id after an in-memory restart (layer 1)', async () => {
         const store = fakeStore();
         const { base, internals } = await startWithFakeApi(store.store);
-        // 1. Initialise a session and capture its id.
         const initRes = await post(base, INIT_BODY, { authorization: 'Bearer orb_alice' });
         expect(initRes.status).toBe(200);
         const sid = initRes.headers.get('mcp-session-id');
         await initRes.text();
         expect(sid).toBeTruthy();
-        // The freshly-minted session was persisted.
         await vi.waitFor(() => expect(store.rows.has(sid)).toBe(true));
-        // 2. Simulate an api restart: the in-memory registry is wiped, the store
-        //    (DB) survives.
         internals.sessions.clear();
-        // 3. The next call with the OLD id + valid auth rehydrates under the SAME id.
         const res = await post(base, NON_INIT, { authorization: 'Bearer orb_alice', 'mcp-session-id': sid });
         expect(res.status).toBe(200);
         expect(res.headers.get('mcp-session-id')).toBe(sid);
@@ -273,7 +248,6 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
         await res.text();
         expect(newId).toBeTruthy();
         expect(newId).not.toBe(stale);
-        // Adoption is recorded old -> new.
         expect(store.register).toHaveBeenCalledWith('orb_bob', expect.objectContaining({ sessionId: newId, adoptedFrom: stale }));
     });
     it('keeps the ORB-1324 404 contract for an unknown id WITHOUT valid auth', async () => {
@@ -284,7 +258,6 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
         expect(res.headers.get('www-authenticate')).toBeNull();
         const bodyText = await res.text();
         expect(bodyText).toMatch(/reinitialize/i);
-        // No session was adopted for an unauthenticated request.
         expect(store.register).not.toHaveBeenCalled();
     });
     it('refuses to adopt when the MCP kill-switch is OFF (returns 404, not a session)', async () => {
@@ -297,9 +270,6 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
     });
     it('refuses to adopt when the per-user MCP opt-out is OFF (ORB-942, returns 404)', async () => {
         const store = fakeStore();
-        // Workspace is enabled but the caller flipped their own users.mcp_enabled
-        // off - the shared preflight refuses, so the stale id falls to the 404
-        // re-init branch and no session is (re)established.
         const { base } = await startWithFakeApi(store.store, fakeApi({ enabled: true, userMcpEnabled: false }));
         const res = await post(base, NON_INIT, { authorization: 'Bearer orb_dave', 'mcp-session-id': 'sess_stale' });
         expect(res.status).toBe(404);
@@ -307,19 +277,6 @@ describe('ORB-1353 - persisted-session resilience (transport, fake api)', () =>
         expect(store.register).not.toHaveBeenCalled();
     });
 });
-// ---------------------------------------------------------------------------
-// ORB-1470 - a long-lived MCP session must follow the client's OAuth access-
-// token rotation, not pin itself to the token captured at session creation.
-//
-// Root cause of the field 401s: the transport bound each session's OrbotoClient
-// (+ tool-handler client + SSE bridge) to the bearer seen at creation and
-// reused it for the session's whole life. An OAuth access token has a 1h TTL and
-// the client rotates it; once the pinned token aged out the api answered 401
-// "OAuth access token expired" on the NEXT tool call - even though that request
-// carried a valid refreshed bearer. If the session was initialised with an
-// already-aged cached token, that was only minutes after connect. The fix makes
-// the per-request bearer authoritative via a mutable per-session token holder.
-// ---------------------------------------------------------------------------
 describe('ORB-1470 - per-session bearer follows the client\'s token rotation', () => {
     let api = null;
     afterEach(async () => {
@@ -357,25 +314,17 @@ describe('ORB-1470 - per-session bearer follows the client\'s token rotation', (
     it('adopts the bearer presented on each request and forwards the fresh token upstream (no pinned-token 401)', async () => {
         const store = fakeStore();
         const { base, internals, state } = await startWithFakeApi(store.store);
-        // 1. Connect: initialise a session with the first access token (v1).
         const initRes = await post(base, INIT_BODY, { authorization: 'Bearer orb_tok_v1' });
         expect(initRes.status).toBe(200);
         const sid = initRes.headers.get('mcp-session-id');
         await initRes.text();
         expect(sid).toBeTruthy();
-        // The session's mutable holder starts at the creation-time bearer.
         const session = internals.sessions.get(sid);
         expect(session.tokenHolder.current).toBe('orb_tok_v1');
-        // 2. The client's OAuth layer rotates its access token (v1 -> v2) and sends
-        //    the next request on the SAME session id with the fresh bearer.
         const res2 = await post(base, NON_INIT, { authorization: 'Bearer orb_tok_v2', 'mcp-session-id': sid });
         expect(res2.status).toBe(200);
         await res2.text();
-        // The session adopted the rotated bearer. Before the fix the session stayed
-        // pinned to v1 and would 401 "expired" once v1 aged out.
         expect(session.tokenHolder.current).toBe('orb_tok_v2');
-        // End-to-end: the session's actual OrbotoClient now forwards v2 upstream, so
-        // the api never sees the stale v1 token again.
         state.seenAuth.length = 0;
         await session.client.get('/system/mcp/status');
         expect(state.seenAuth).toContain('Bearer orb_tok_v2');
@@ -384,16 +333,11 @@ describe('ORB-1470 - per-session bearer follows the client\'s token rotation', (
     it('adopts the current bearer when rehydrating a session after a restart', async () => {
         const store = fakeStore();
         const { base, internals, state } = await startWithFakeApi(store.store);
-        // Connect with v1, then simulate an api restart wiping the in-memory map.
         const initRes = await post(base, INIT_BODY, { authorization: 'Bearer orb_tok_v1' });
         const sid = initRes.headers.get('mcp-session-id');
         await initRes.text();
         internals.sessions.clear();
-        // The client (now on a refreshed v2) reconnects under the SAME id.
         const res = await post(base, NON_INIT, { authorization: 'Bearer orb_tok_v1', 'mcp-session-id': sid });
-        // ^ rehydration is keyed on the persisted-store owner (token == userId in
-        //   the fake), so the rehydrate itself uses the presented token. Then a
-        //   follow-up request rotates to v2.
         expect(res.status).toBe(200);
         await res.text();
         const res2 = await post(base, NON_INIT, { authorization: 'Bearer orb_tok_v2', 'mcp-session-id': sid });

package/dist/index.js

@@ -2,34 +2,7 @@
 /**
  * ORB-244 Phase A - entry point for `@orboto/mcp`.
  *
- * Two transport modes, picked by env:
- *   ORBOTO_MCP_TRANSPORT=stdio (default) - JSON-RPC over stdin/stdout,
- *     used by the Local-Proxy delivery variant. Claude Desktop spawns
- *     this process via the `claude_desktop_config.json` snippet and
- *     talks over its own stdio pair.
- *   ORBOTO_MCP_TRANSPORT=http - Streamable HTTP per MCP
- *     spec. Used by the Self-Hosted-inline + Cloud-Managed variants
- *     (separate container listening on a port the reverse proxy maps
- *     to `/mcp`). Sessions carry `mcp-session-id` for server→client
- *     notifications.
- *
- * Config (env-only - no config file):
- *   ORBOTO_API_URL        required - base URL of the orboto API
- *   ORBOTO_API_KEY        optional - `orb_*` API key with `mcp:use`
- *                         scope (stdio mode). Service-account fallback;
- *                         when omitted, stdio mode bootstraps via OAuth
- *                         (ORB-943) so a desktop user connects through the
- *                         workspace login without pasting a token. Per-
- *                         session bearer is read from the Authorization
- *                         header in http mode.
- *   ORBOTO_AUTH           optional - `pat` | `oauth`. Defaults to `pat`
- *                         when ORBOTO_API_KEY is set, else `oauth`. Force
- *                         `oauth` to run the browser bootstrap even with a
- *                         key present.
- *   ORBOTO_MCP_TRANSPORT  optional - `stdio` (default) | `http`
- *   ORBOTO_MCP_PORT       optional - port for http transport, default 3100
- *   ORBOTO_MCP_CLIENT     optional - client hint for User-Agent (e.g.
- *                         `claude-desktop`, `cursor`).
+ * @see ORB-943
  */
 import { buildOrbotoMcpServer } from './server.js';
 import { OrbotoClient, preflightMcpSession } from './orboto-client.js';
@@ -45,12 +18,6 @@ function requireEnv(name) {
 async function main() {
     const transport = (process.env.ORBOTO_MCP_TRANSPORT ?? 'stdio').toLowerCase();
     if (transport === 'stdio') {
-        // Local-Proxy mode - one MCP client, one process, one identity. The
-        // identity is either a static `orb_*` PAT (service-account fallback) OR,
-        // when no key is configured, an OAuth session bootstrapped through the
-        // workspace login (ORB-943) so a desktop user never pastes a token. All
-        // config read at boot; no per-request auth needed because the only user of
-        // this stdio pair is the client that spawned us.
         const baseUrl = requireEnv('ORBOTO_API_URL');
         const apiKey = process.env.ORBOTO_API_KEY;
         const userAgentSuffix = process.env.ORBOTO_MCP_CLIENT;
@@ -60,8 +27,6 @@ async function main() {
             console.error('[orboto-mcp] ORBOTO_AUTH=pat requires ORBOTO_API_KEY. Unset it to use OAuth, or provide a key.');
             process.exit(2);
         }
-        // clientConfig carries either the PAT or the OAuth token provider; both
-        // shapes satisfy OrbotoClientConfig.
         let clientConfig;
         if (authMode === 'oauth') {
             try {
@@ -77,9 +42,6 @@ async function main() {
         else {
             clientConfig = { baseUrl, userAgentSuffix, apiKey };
         }
-        // Preflight BEFORE spinning up the transport - so a
-        // mis-configured install fails loudly to stderr instead of
-        // silently hanging on stdin waiting for JSON-RPC frames.
         const preflightClient = new OrbotoClient(clientConfig);
         try {
             const { userEmail } = await preflightMcpSession(preflightClient);
@@ -95,23 +57,14 @@ async function main() {
         const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
         const stdio = new StdioServerTransport();
         await server.connect(stdio);
-        // The SDK writes its own "connected" log to stderr; we don't
-        // echo anything here - stdout is reserved for JSON-RPC frames
-        // and an accidental console.log would corrupt the protocol.
         return;
     }
     if (transport === 'http') {
-        // Self-Hosted + Cloud-Managed mode. The bearer token comes from
-        // the caller (Claude Desktop / Cursor) on every POST - a per-
-        // session server is built so each session carries its own
-        // API-key scoped OrbotoClient.
         const port = Number(process.env.ORBOTO_MCP_PORT ?? '3100');
         const baseUrl = requireEnv('ORBOTO_API_URL');
         const { createHttpServer } = await import('./http-transport.js');
         const httpServer = createHttpServer({ baseUrl });
         httpServer.listen(port, () => {
-            // stderr so self-hosted operators can tail the container log
-            // without parsing the JSON on stdout (stdio mode).
             // eslint-disable-next-line no-console
             console.error(`[orboto-mcp] http listening on :${port} → ${baseUrl}`);
         });

package/dist/input-schema.js

@@ -1,60 +1,7 @@
 /**
  * ORB-1692 - strict tool inputs + the aliases agents actually send.
  *
- * Measured across 32 transcripts: 55.6% of all MCP errors were "Required"
- * validation failures where the agent guessed a plausible-but-wrong
- * parameter name (`body` for `text`, `parentKey` for `parentTicketKey`,
- * ...). Worse, zod strips unknown keys by default, so a wrong key on an
- * otherwise-valid call VANISHED silently - `create_ticket` with
- * `parentKey` created ORB-1684 with no parent and no warning.
- *
- * Fix, applied centrally at registration (with-metrics `reg()`):
- *  1. every tool input becomes `.strict()` - an unknown key errors,
- *     naming the offender;
- *  2. the measured aliases resolve silently to the canonical field via a
- *     GUARDED global rename: `alias -> canonical` fires only when the
- *     canonical field exists in that tool's shape, the alias does not,
- *     and the caller did not also send the canonical - so a tool whose
- *     REAL field is `body` (agent-instruction blocks) is never touched;
- *  3. `orboto_update_ticket` folds flat patch fields into `patch` when no
- *     `patch` was sent - agents routinely write `{ticketKey, description}`.
- *
- * ORB-1817 - "we do not force keys that make no sense - key and query are
- * sensible names" (operator). Extends the alias table with the sensible
- * spellings a caller actually reaches for (`key`, `query`, `projectId`,
- * ...) plus one DYNAMIC alias - `id` resolves to the tool's own single
- * id-shaped parameter (`ticketKey` / `docId` / `milestone` / `commentId`)
- * only when exactly one of those exists in that tool's shape - and adds a
- * teaching error: when a call still can't be resolved, the thrown message
- * is a structured JSON block naming every parameter the tool accepts plus
- * a Levenshtein<=2 guess for each unrecognized key (same distance the mjs
- * wrapper's `suggestFlag` uses for `--flag` typos). The failure is also
- * logged through the same `/admin/mcp/instrument` path a handler error
- * uses - see the module doc on `mcp-instrument.ts` for why that needs a
- * dedicated leaf module instead of importing from with-metrics.ts.
- *
- * SDK mechanics: `registerTool` accepts either a raw shape or a zod
- * schema. A top-level `z.preprocess(...)` has no `.shape`, which would
- * make the SDK advertise an EMPTY input schema in tools/list. Stamping
- * the inner object's `.shape` onto the effects schema keeps the
- * advertisement byte-identical to the strict object (verified: the SDK's
- * `normalizeObjectSchema` only checks `.shape !== undefined`, and its
- * json-schema emitter unwraps effects with pipeStrategy "input").
- *
- * ORB-1817 - the preprocess callback is also where the teaching error is
- * thrown (verified against @modelcontextprotocol/sdk 1.29's zod-compat +
- * server/mcp.js): a `preprocess` effect calls `effect.transform(data,
- * checkCtx)` BEFORE the inner schema ever parses, and unlike `refine` /
- * `transform`, a synchronous throw from inside it is NOT caught by zod -
- * it propagates out of `ZodEffects._parse`, out of the SDK's
- * `safeParseAsync` (converted to a rejected promise, since that's an
- * `async function`), and lands in the SDK's own `CallToolRequestSchema`
- * handler's outer try/catch, which for a plain (non-McpError) `Error`
- * returns `{isError: true, content: [{type: 'text', text: error.message}]}`
- * with NO extra wrapping. That is what lets us hand back exactly our
- * structured JSON with nothing else attached - `.superRefine()` cannot do
- * this (it never even runs once the base object parse has already failed,
- * which is the common case: a missing-required or unrecognized-key input).
+ * @see ORB-1684, ORB-1817
  */
 import { z } from 'zod';
 import { postLogEntry, redactSecrets } from './mcp-instrument.js';
@@ -73,16 +20,12 @@ export const GLOBAL_INPUT_ALIASES = {
     milestoneKey: 'milestone',
     ticket: 'ticketKey',
     project: 'projectKey',
-    // ORB-1817 - measured 2026-09-03: both cost one retry in the same
-    // session. "key" and "query" are what a reasonable caller types.
     key: 'ticketKey',
     query: 'oql',
     projectId: 'projectKey',
     milestoneId: 'milestone',
     comment: 'text',
     message: 'text',
-    // Bulk tools all take `ticketKeys` (plural) - singular-sounding `keys`
-    // is the natural typo/guess.
     keys: 'ticketKeys',
     max: 'limit',
     page: 'cursor',
@@ -112,7 +55,6 @@ function applyAliases(toolName, shape, value) {
             out = { ...rest, [canonical]: aliased };
         }
     }
-    // ORB-1817 - `id` -> the tool's single id-shaped parameter.
     if ('id' in out && !('id' in shape)) {
         const candidates = ID_LIKE_CANONICALS.filter((c) => c in shape && !(c in out));
         if (candidates.length === 1) {
@@ -121,9 +63,6 @@ function applyAliases(toolName, shape, value) {
             out = { ...rest, [canonical]: id };
         }
     }
-    // update_ticket: flat fields become an implicit patch. Only when the
-    // caller sent no patch at all - a partial patch plus flat extras stays
-    // an error (ambiguous intent must not be guessed).
     if (toolName === 'orboto_update_ticket' && !('patch' in out)) {
         const patch = {};
         const rest = {};
@@ -142,10 +81,6 @@ function applyAliases(toolName, shape, value) {
     }
     return out;
 }
-// ---------------------------------------------------------------------------
-// ORB-1817 - teaching error: structured `expected` block + closest-name
-// guess, built when the strict + alias-resolved value STILL doesn't parse.
-// ---------------------------------------------------------------------------
 /** Levenshtein-1/2 match, same algorithm skills/orboto/scripts/orboto.mjs
  *  uses for `--flag` typos (`suggestFlag` / `levenshtein`) - keep them in
  *  sync if the distance metric ever changes. */
@@ -247,12 +182,7 @@ function buildTeachingError(toolName, shape, issues) {
  * validates against. Returns a schema whose `.shape` is stamped so
  * tools/list advertisement stays identical to the plain object form.
  *
- * `client` + `clientHint` are optional (tests construct schemas without
- * them) - when present, a validation failure that survives aliasing is
- * logged through the SAME `/admin/mcp/instrument` path a handler error
- * uses (ORB-1817 Part C), because the SDK validates input BEFORE
- * with-metrics.ts's handler wrapper ever runs - this preprocess step is
- * the only place that ever sees the failure.
+ * @see ORB-1817
  */
 export function buildStrictInputSchema(toolName, shape, client, clientHint) {
     const inner = z.object(shape).strict();
@@ -273,12 +203,8 @@ export function buildStrictInputSchema(toolName, shape, client, clientHint) {
                 clientHint,
             });
         }
-        // See the module doc: thrown here (inside a "preprocess" effect, not
-        // a refinement/transform), this is NOT caught by zod - it becomes the
-        // exact isError text the caller sees.
         throw new Error(message);
     }, inner);
-    // SDK contract (see module doc): .shape must exist for advertisement.
     effects.shape = inner.shape;
     return effects;
 }

package/dist/input-schema.test.js

@@ -2,18 +2,7 @@
  * ORB-1692 / ORB-1817 - strict inputs + measured aliases + the teaching
  * error.
  *
- * Table-driven against the REAL tool configs: each alias from the
- * measurement table must resolve to the canonical field, unknown keys
- * must error naming the offender, and the ORB-1684 silent-drop case
- * (create_ticket with parentKey) must never come back.
- *
- * ORB-1817 - a call that still can't be resolved after aliasing now
- * THROWS (from every parse entry point, `.safeParse()` included - see
- * the module doc on `buildStrictInputSchema` for why: the teaching error
- * is thrown from inside a zod "preprocess" effect, which runs before the
- * sync/async branch even exists). That's an intentional behaviour change
- * from plain zod (whose `.safeParse()` never throws) - every test below
- * that used to check `parsed.success === false` now checks the throw.
+ * @see ORB-1684
  */
 import { describe, it, expect, vi } from 'vitest';
 import { z } from 'zod';
@@ -105,7 +94,6 @@ describe('alias guard: canonical-field collisions are never renamed', () => {
         }
     });
     it('alias is ignored when the caller also sent the canonical field', () => {
-        // both present: no rename happens, so `body` is an unknown key -> error
         const body = throwsWith(schemaFor('orboto_comment', commentToolConfig), { ticketKey: 'ORB-1', text: 'real', body: 'stray' });
         expect(body.unrecognized).toEqual(['body']);
     });
@@ -121,7 +109,6 @@ describe('ORB-1817: extended alias table', () => {
         { tool: 'orboto_bulk_move_tickets', config: bulkMoveTicketsToolConfig, send: { keys: ['ORB-1', 'ORB-2'], statusCategory: 'done' }, expectKey: 'ticketKeys', expectValue: ['ORB-1', 'ORB-2'] },
         { tool: 'orboto_query', config: queryToolConfig, send: { oql: 'project = ORB', max: 10 }, expectKey: 'limit', expectValue: 10 },
         { tool: 'orboto_query', config: queryToolConfig, send: { oql: 'project = ORB', page: 'c1' }, expectKey: 'cursor', expectValue: 'c1' },
-        // `id` -> the tool's single id-shaped parameter (ticketKey here).
         { tool: 'orboto_get_ticket', config: getTicketToolConfig, send: { id: 'ORB-1' }, expectKey: 'ticketKey', expectValue: 'ORB-1' },
         { tool: 'orboto_get_doc', config: getDocToolConfig, send: { id: 'ORB-D12' }, expectKey: 'docId', expectValue: 'ORB-D12' },
     ];
@@ -136,7 +123,6 @@ describe('ORB-1817: extended alias table', () => {
         });
     }
     it('`id` is left alone (and errors) when the tool has more than one id-shaped parameter', () => {
-        // orboto_update_comment has BOTH ticketKey and commentId - ambiguous.
         const body = throwsWith(schemaFor('orboto_update_comment', updateCommentToolConfig), { id: 'ORB-1', text: 'hi' });
         expect(body.unrecognized).toEqual(['id']);
     });

package/dist/instructions-budget.test.js

@@ -23,12 +23,10 @@ describe('assembleInstructions (ORB-1177)', () => {
         expect(out).toContain('orboto://rules');
         expect(out).toContain('orboto_session_start');
         expect(out).toContain('truncated');
-        // Every kept rule line is a COMPLETE original line (no mid-line cut).
         const body = out.slice(`${head}\n\n${HEADING}`.length).split('\n\n[... rules truncated')[0];
         const kept = body.length ? body.split('\n') : [];
         for (const line of kept)
             expect(lines).toContain(line);
-        // And it actually kept fewer than all lines (proves truncation happened).
         expect(kept.length).toBeLessThan(lines.length);
     });
 });

package/dist/manifest-size.test.js

@@ -1,17 +1,6 @@
 /**
  * ORB-1521 - manifest-size measurement + regression ratchet (epic
  * ORB-1517).
- *
- * Measures the REAL `tools/list` payload an eager-loading client pays
- * at connect time - through an actual MCP client over an in-memory
- * transport, so the numbers include the SDK's zod->JSON-schema
- * conversion, exactly what Codex/Cursor/Claude Desktop receive.
- *
- * The curated assertion is the RATCHET (mirroring the dark-mode / i18n
- * shrink-only checks): if someone re-registers the tail into the
- * default manifest - or the curated set quietly balloons - this fails
- * before a release ships the token bill. Raising CURATED_MAX_CHARS is a
- * conscious decision to grow the default connect cost, not a formality.
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -37,34 +26,9 @@ afterEach(() => { vi.restoreAllMocks(); });
  * 20 %. Shrink-only: raising either number is a conscious decision to
  * grow every session's connect cost.
  *
- * ORB-1805, measured 2026-09-01 with the schema diet + the compact
- * advertised `__truncation` block: minimal = 12 tools / 9,440 chars;
- * curated = 31 tools / 27,945 chars (was 34,015); full = 175 tools /
- * 142,366 chars (was 152,348).
- *
- * ORB-1669, landed 2026-09-04: every tool carries an MCP `annotations`
- * block (readOnlyHint / destructiveHint / idempotentHint) - clients use
- * them for confirmation UX, so they are spec conformance, not payload
- * fat. Measured cost: minimal +688 chars (12 tools), curated +1,276,
- * full +9,836 (175 tools, ~56 chars each). FULL_MAX_CHARS and
- * MINIMAL_MAX_TOKENS were raised by exactly that, deliberately.
- *
- * ORB-1910 (2026-09-05): orboto_report_feedback joins the curated set (32
- * tools) - an agent that hits a bug must be able to report it without
- * ?toolset=full. Measured curated = 30,652 chars after trimming the tool's
- * schema to the minimum (one describe() on `page`); ceiling re-pinned to
- * 32,500 (~6 % headroom), deliberately, for that one addition.
+ * @see ORB-1805, ORB-1669, ORB-1910
  */
-// ORB-1959 - re-pinned at 37,500 (measured 36,714): the four agent
-// coordination tools (messages, notify, broadcast, heartbeat) joined the
-// curated tier so an agent on the DEFAULT connection can fetch, act on and
-// ack its mail - the binding workspace rule the old manifest made impossible
-// to follow. Their descriptions were cut to the load-bearing facts first
-// (286 chars); the remaining ~4.2k chars are input/output schemas and the
-// per-tool keys the SDK emits. Decision by the operator, 2026-09-06.
 const CURATED_MAX_CHARS = 37_500;
-// ORB-2000 - orboto_draft_customer_reply joins the full tier (measured
-// 155,669 chars with it); ceiling re-pinned with ~6 % headroom.
 const FULL_MAX_CHARS = 165_000;
 /**
  * ORB-1805 - the estimator the ticket measured the failure with
@@ -85,22 +49,8 @@ const MINIMAL_MAX_TOKENS = 3_100;
 /**
  * The curated tier is ratcheted on its TOOL SCHEMAS (the instructions
  * block has its own budget, enforced in instructions-budget.test.ts).
- *
- * Why this is not the ticket's aspirational 6,000: measured 2026-09-01,
- * the curated manifest with EVERY description and title stripped out is
- * still 17,379 chars (~4,827 tokens) - 31 tools' names, parameter names,
- * types, enums, plus ~2,700 chars of per-tool `$schema` and `execution`
- * keys the MCP SDK emits and we do not control. A 6,000-token ceiling
- * would leave ~4,200 chars for all 31 tools' text combined, i.e. the
- * one-line summaries and NOTHING else - no "Key (ORB-M3), name, or
- * UUID", no "YYYY-MM-DD", no "Default: task". Those pay for themselves
- * in avoided failed calls. The tier that genuinely fits a small window
- * is `minimal`; curated is the desktop-client default, and this ceiling
- * holds the 18 % the diet won.
  */
-// ORB-1910 - re-pinned with CURATED_MAX_CHARS (32,500 / 3.6): the curated set
-// gained orboto_report_feedback; measured 8,514 estimated tokens.
-const CURATED_SCHEMA_MAX_TOKENS = 10_450; // ORB-1959: measured 10,198 with the coordination tools
+const CURATED_SCHEMA_MAX_TOKENS = 10_450;
 async function measuredManifest(toolset) {
     const server = await buildOrbotoMcpServer({
         baseUrl: 'https://orboto.example.com',
@@ -111,9 +61,6 @@ async function measuredManifest(toolset) {
     const client = new Client({ name: 'manifest-measure', version: '0.0.0' });
     await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
     try {
-        // Walk pagination defensively; the SDK serves all tools in one page
-        // today but the measurement must not silently undercount if that
-        // changes.
         let cursor;
         const tools = [];
         do {
@@ -121,9 +68,6 @@ async function measuredManifest(toolset) {
             tools.push(...page.tools);
             cursor = page.nextCursor;
         } while (cursor);
-        // `_instructions` verified against @modelcontextprotocol/sdk 1.29.
-        // Assert non-empty at the call sites so an SDK rename fails loudly
-        // instead of scoring the block as free.
         const instructions = String(server.server._instructions ?? '');
         return { count: tools.length, chars: JSON.stringify(tools).length, instructionsChars: instructions.length };
     }
@@ -137,9 +81,6 @@ describe('ORB-1521 - eager-load manifest size', () => {
         const { count, chars } = await measuredManifest();
         // eslint-disable-next-line no-console
         console.log(`[manifest-size] curated: ${count} tools, ${chars} chars (~${estTokens(chars)} tokens)`);
-        // 31 = the ORB-1741-dieted set + the two ORB-1694 bulk tools (each
-        // REPLACES dozens of per-call responses, so they earn their slot);
-        // ORB-1910 added report_feedback, ORB-1959 the four coordination tools.
         expect(count).toBeLessThanOrEqual(36);
         expect(chars).toBeLessThanOrEqual(CURATED_MAX_CHARS);
         expect(estTokens(chars)).toBeLessThanOrEqual(CURATED_SCHEMA_MAX_TOKENS);
@@ -150,11 +91,7 @@ describe('ORB-1521 - eager-load manifest size', () => {
         // eslint-disable-next-line no-console
         console.log(`[manifest-size] full: ${full.count} tools, ${full.chars} chars (~${estTokens(full.chars)} tokens)`);
         expect(full.count).toBeGreaterThan(150);
-        // ORB-1741 - the full manifest is ratcheted too: the diet's savings
-        // live mostly here (per-tool description essays), so this is where
-        // regression would land first.
         expect(full.chars).toBeLessThanOrEqual(FULL_MAX_CHARS);
-        // The reduction claim the epic makes - keep it honest in CI.
         expect(full.chars / curated.chars).toBeGreaterThan(3);
     });
 });
@@ -174,7 +111,7 @@ describe('ORB-1805 - minimal manifest fits a small context window', () => {
             + ` + instructions ${instructionsChars} chars (~${estTokens(instructionsChars)} tokens)`
             + ` = ~${estTokens(total)} tokens`);
         expect(count).toBe(12);
-        expect(instructionsChars).toBeGreaterThan(100); // SDK rename guard
+        expect(instructionsChars).toBeGreaterThan(100);
         expect(estTokens(total)).toBeLessThanOrEqual(MINIMAL_MAX_TOKENS);
     });
     it('minimal is a strict subset of curated, which is a strict subset of full', async () => {
@@ -186,12 +123,6 @@ describe('ORB-1805 - minimal manifest fits a small context window', () => {
         expect(minimal.chars).toBeLessThan(curated.chars);
     });
     it('minimal instructions are a CONSTANT - a long workspace rule set cannot grow them', async () => {
-        // The tier ships the head only: no workspace rules block, so a
-        // workspace with a 200-line rule set costs the same as an empty one.
-        // (The rules are not lost - orboto_session_start returns them, on
-        // the caller's budget rather than as a connect-time tax.) Curated,
-        // by contrast, embeds them up to its 4k budget - assert BOTH so this
-        // stays a real difference and not a coincidence of the fixture.
         const offline = await measuredManifest('minimal');
         const hugeRules = Array.from({ length: 200 }, (_, i) => `rule ${i}: ${'x'.repeat(60)}`).join('\n');
         vi.spyOn(globalThis, 'fetch').mockResolvedValue({