@orboto/mcp 0.178.0

package/dist/version-guard.test.js

@@ -0,0 +1,51 @@
+/**
+ * ORB-1173 - guard against version literals drifting from package.json.
+ *
+ * Version used to be hardcoded ('0.51.0') in three spots and release.mjs
+ * never touched them, so serverInfo + the User-Agent lied about the real
+ * release. Now everything reads VERSION (← package.json, ORB-1166). This
+ * test fails CI if (a) VERSION stops matching package.json, or (b) someone
+ * reintroduces a hardcoded semver string literal anywhere in src.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import { VERSION } from './version.js';
+const SRC = dirname(fileURLToPath(import.meta.url));
+const pkg = createRequire(import.meta.url)('../package.json');
+// version.ts legitimately holds the '0.0.0' runtime fallback literal.
+const ALLOWED = new Set(['version.ts']);
+function walk(dir, acc = []) {
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, acc);
+        else if (/\.tsx?$/.test(entry) && !entry.endsWith('.test.ts') && !entry.endsWith('.test.tsx') && !ALLOWED.has(entry)) {
+            acc.push(full);
+        }
+    }
+    return acc;
+}
+describe('ORB-1173 - version literal guard', () => {
+    it('VERSION matches package.json (and is not the runtime fallback)', () => {
+        expect(VERSION).toBe(pkg.version);
+        expect(VERSION).not.toBe('0.0.0');
+    });
+    it('no hardcoded semver string literal in src (use VERSION instead)', () => {
+        const offenders = [];
+        // A quoted X.Y.Z literal - what a drifting hardcoded version looks
+        // like. Comments (// v0.110.1) and ticket refs (ORB-1166) are not
+        // quoted semver, so they don't trip this.
+        const semverLiteral = /['"]\d+\.\d+\.\d+['"]/;
+        for (const file of walk(SRC)) {
+            const text = readFileSync(file, 'utf8');
+            text.split('\n').forEach((line, i) => {
+                if (semverLiteral.test(line))
+                    offenders.push(`${file.replace(SRC, 'src')}:${i + 1}: ${line.trim()}`);
+            });
+        }
+        expect(offenders, `Hardcoded version literal(s) found - read VERSION from version.ts instead:\n${offenders.join('\n')}`).toEqual([]);
+    });
+});

package/dist/version.js

@@ -0,0 +1,28 @@
+/**
+ * ORB-1166 - single source of truth for the MCP server version.
+ *
+ * Read from package.json (which release.mjs bumps) so serverInfo.version
+ * + the User-Agent header always reflect the real release instead of a
+ * hardcoded literal that drifts.
+ *
+ * WRAPPED IN try/catch on purpose: the Docker runtime image is stripped
+ * to `dist/` + `node_modules/` and may not ship package.json at the path
+ * `createRequire` resolves. A bare `require('../package.json')` at module
+ * load threw there and crash-looped the MCP container (took prod down in
+ * v0.110.1). The catch guarantees this module can NEVER crash the server
+ * on boot; the Dockerfile now also copies package.json so the real
+ * version resolves in-container.
+ */
+import { createRequire } from 'node:module';
+function readVersion() {
+    try {
+        const pkg = createRequire(import.meta.url)('../package.json');
+        if (typeof pkg?.version === 'string' && pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // package.json not present in this runtime - fall through to the default.
+    }
+    return '0.0.0';
+}
+export const VERSION = readVersion();

package/dist/with-metrics-mail-nudge.test.js

@@ -0,0 +1,41 @@
+/**
+ * ORB-1733 - the pending-mail nudge must NEVER touch structuredContent.
+ *
+ * The SDK validates structuredContent against the tool's declared
+ * outputSchema; the ORB-1727 version injected `__pendingAgentMessages`
+ * into every result while mail was pending, which failed validation on
+ * every strict-schema tool and rendered the whole MCP surface unusable
+ * for that identity until the mail was acked. The nudge lives only in a
+ * text content block.
+ */
+import { describe, it, expect } from 'vitest';
+import { appendMailNudge } from './with-metrics.js';
+function clientWithMail(count) {
+    return { pendingAgentMail: count };
+}
+function structuredResult() {
+    return {
+        content: [{ type: 'text', text: 'projects listed' }],
+        structuredContent: { projects: [{ key: 'ORB', name: 'orboto' }] },
+    };
+}
+describe('ORB-1733: mail nudge vs output schemas', () => {
+    it('leaves structuredContent byte-identical while mail is pending - the nudge is a text block only', () => {
+        const original = structuredResult();
+        const out = appendMailNudge(clientWithMail(2), 'orboto_list_projects', original);
+        expect(out.structuredContent).toEqual({ projects: [{ key: 'ORB', name: 'orboto' }] });
+        expect(JSON.stringify(out.structuredContent)).not.toContain('__pendingAgentMessages');
+        const texts = out.content.filter((c) => c.type === 'text').map((c) => c.text);
+        expect(texts.some((t) => t.includes('2 unread agent message'))).toBe(true);
+    });
+    it('no mail = result passed through untouched', () => {
+        const original = structuredResult();
+        const out = appendMailNudge(clientWithMail(0), 'orboto_list_projects', original);
+        expect(out).toBe(original);
+    });
+    it('orboto_messages itself is never nudged', () => {
+        const original = structuredResult();
+        const out = appendMailNudge(clientWithMail(5), 'orboto_messages', original);
+        expect(out).toBe(original);
+    });
+});

package/dist/with-metrics-output-schema.test.js

@@ -0,0 +1,91 @@
+/**
+ * ORB-1738 - declared output schemas ADVERTISE the response budget's
+ * `__truncation` marker.
+ *
+ * Second instance of the ORB-1733 class: the budget injects the marker
+ * into structuredContent, the SDK advertises output schemas with
+ * additionalProperties:false, and strict clients validate structured
+ * content against that - so every over-budget response of a tool with a
+ * declared outputSchema was rejected wholesale (orboto_list_projects
+ * failed on EVERY call of this 57-project workspace; reported via the
+ * agent inbox 2026-08-28).
+ */
+import { describe, it, expect } from 'vitest';
+import { listProjectsToolConfig } from './tools/list-projects.js';
+import { TruncationBlockSchema, TruncationBlockAdvertisedSchema, applyResponseBudget, resetPayloadStore, } from './response-budget.js';
+/** Mirrors the reg() transformation in with-metrics.ts (ORB-1805: the
+ *  advertised form is the compact, open one). */
+function advertisedOutputShape(shape) {
+    return { ...shape, __truncation: TruncationBlockAdvertisedSchema.optional() };
+}
+/** What additionalProperties:false enforces on a strict client: every key
+ *  of the payload must be a declared property. */
+function strictClientAccepts(shape, payload) {
+    return Object.keys(payload).every((k) => k in shape);
+}
+describe('ORB-1738 - __truncation is part of the advertised output schema', () => {
+    it('list_projects: an over-budget payload with the marker passes the strict-client check', () => {
+        resetPayloadStore();
+        const bigResult = {
+            content: [{ type: 'text', text: 'projects' }],
+            structuredContent: {
+                projects: Array.from({ length: 60 }, (_, i) => ({
+                    id: `id-${i}`, key: `P${i}`, name: `Project ${i} ${'x'.repeat(120)}`,
+                    status: 'active', description: 'y'.repeat(120),
+                })),
+                total: 60,
+                totalProjects: 60,
+                query: null,
+            },
+        };
+        const { result } = applyResponseBudget('orboto_list_projects', bigResult);
+        const sc = result.structuredContent;
+        // The budget DID cut and marked it.
+        expect(sc.__truncation).toBeDefined();
+        const shape = advertisedOutputShape(listProjectsToolConfig.outputSchema);
+        // Before the fix this was false - the marker was undeclared.
+        expect(strictClientAccepts(shape, sc)).toBe(true);
+        // And the marker itself matches BOTH the exact runtime shape and the
+        // compact schema actually advertised on the wire (ORB-1805).
+        expect(TruncationBlockSchema.safeParse(sc.__truncation).success).toBe(true);
+        expect(TruncationBlockAdvertisedSchema.safeParse(sc.__truncation).success).toBe(true);
+    });
+    it('ORB-1805 - the advertised marker schema is strictly more permissive than the exact one', () => {
+        // Anything the exact shape accepts, the advertised one must accept -
+        // otherwise the diet would start rejecting valid payloads.
+        const block = {
+            handle: 'h1', budgetChars: 4000, originalChars: 9000, omittedChars: 5000,
+            omitted: [{ path: 'items', kind: 'array', omittedItems: 12, keptItems: 3 }],
+            howToGetTheRest: 'call orboto_response_expand',
+        };
+        expect(TruncationBlockSchema.safeParse(block).success).toBe(true);
+        expect(TruncationBlockAdvertisedSchema.safeParse(block).success).toBe(true);
+        // A future field added to the runtime block must not break clients.
+        expect(TruncationBlockAdvertisedSchema.safeParse({ ...block, futureField: 1 }).success).toBe(true);
+    });
+    it('the budget layer adds exactly ONE key - __truncation - and nothing else (class sweep)', () => {
+        resetPayloadStore();
+        const original = {
+            content: [{ type: 'text', text: 'x' }],
+            structuredContent: {
+                projects: Array.from({ length: 40 }, (_, i) => ({ id: `p-${i}`, key: `K${i}`, name: 'n'.repeat(150), status: 'active', description: 'd'.repeat(150) })),
+                total: 40, totalProjects: 40, query: null,
+            },
+        };
+        const before = Object.keys(original.structuredContent);
+        const { result } = applyResponseBudget('orboto_list_projects', original);
+        const after = Object.keys(result.structuredContent);
+        expect(after.filter((k) => !before.includes(k))).toEqual(['__truncation']);
+    });
+    it('under-budget responses stay byte-identical (no marker, still schema-clean)', () => {
+        resetPayloadStore();
+        const small = {
+            content: [{ type: 'text', text: 'ok' }],
+            structuredContent: { projects: [], total: 0, totalProjects: 0, query: null },
+        };
+        const { result } = applyResponseBudget('orboto_list_projects', small);
+        const sc = result.structuredContent;
+        expect(sc.__truncation).toBeUndefined();
+        expect(strictClientAccepts(advertisedOutputShape(listProjectsToolConfig.outputSchema), sc)).toBe(true);
+    });
+});

package/dist/with-metrics.js

@@ -0,0 +1,211 @@
+import { OrbotoApiError } from './orboto-client.js';
+import { shouldNudge, prependNudge, shouldGate, gateResult } from './session-nudge.js';
+import { applyResponseBudget, TruncationBlockAdvertisedSchema } from './response-budget.js';
+import { buildStrictInputSchema, isRawShape } from './input-schema.js';
+import { captureToolDoc, summarizeToolDescription } from './tool-docs.js';
+import { postLogEntry, redactSecrets } from './mcp-instrument.js';
+/**
+ * ORB-1174 - turn an OrbotoApiError into an actionable, agent-visible
+ * tool-error message. Before this, a thrown error reached the MCP runtime
+ * as a generic "Error occurred during tool execution" - an MCP-only agent
+ * couldn't tell 401 (auth) from 404 (not found) from 500 (server) and so
+ * couldn't self-correct. We surface the status + a one-line hint + the
+ * API's own message. The API error body is workspace error text (no
+ * secrets); we still cap its length defensively.
+ */
+function formatApiError(err) {
+    let detail = err.body || '';
+    try {
+        const parsed = JSON.parse(err.body);
+        if (parsed.error)
+            detail = parsed.error;
+    }
+    catch { /* body wasn't JSON - use it raw */ }
+    detail = detail.slice(0, 400);
+    const hint = err.status === 401 ? 'Authentication failed - your token is invalid or expired. Re-authenticate (re-run the OAuth connect, or check the API key).'
+        : err.status === 403 ? 'Permission denied - your account lacks the required permission for this action.'
+            : err.status === 404 ? 'Not found - the referenced ticket / project / resource does not exist or you cannot see it.'
+                : err.status === 409 ? 'Conflict - the resource already exists or is in a state that blocks this change.'
+                    : err.status === 422 ? 'Validation failed - the request was understood but rejected; adjust the input.'
+                        : err.status === 429 ? 'Rate limited - slow down and retry shortly.'
+                            : err.status >= 500 ? 'orboto server error - transient; retry shortly. If it persists the API may be mid-deploy.'
+                                : 'Request rejected.';
+    return `orboto API error ${err.status}. ${hint}\nDetail: ${detail || '(no message)'}`;
+}
+// ORB-1817 - McpLogEntry / redactSecrets / postLogEntry live in
+// mcp-instrument.ts (a leaf module) so input-schema.ts can log validation
+// failures through the same instrument path without an import cycle
+// (this file already imports FROM input-schema.ts).
+/**
+ * Wrap a CallToolResult-returning handler so every invocation posts
+ * one row to mcp_call_log via /admin/mcp/instrument.
+ *
+ * Used as: `withMetrics(client, 'orboto_get_ticket', clientHint, makeGetTicketHandler(client))`
+ *
+ * Wired centrally in `server.ts` so per-tool files don't need to
+ * know about instrumentation.
+ */
+export function withMetrics(client, toolName, clientHint, 
+// ORB-1252 - forward the SDK's `extra` (RequestHandlerExtra) so handlers can
+// read the per-connection MCP sessionId (distinct per HTTP client even on a
+// shared server). Backward-compatible: handlers that ignore it are unaffected.
+handler, 
+// ORB-1331 - per-session/-process nudge state. When present, the first
+// tool dispatch that is not `orboto_session_start` gets the one-time
+// reminder prepended to its response. Optional so direct callers/tests
+// that don't care are unaffected.
+nudge) {
+    return async (args, extra) => {
+        const start = Date.now();
+        // ORB-1331 - decide (and advance the flag) once per dispatch, before
+        // the handler runs, so the "first tool call" is the first dispatch
+        // regardless of its outcome. Applied to the returned result below.
+        const wantsNudge = nudge ? shouldNudge(nudge, toolName) : false;
+        // ORB-1471 - HARD session-start gate. When the workspace requires it,
+        // refuse every tool call until `orboto_session_start` has run (this also
+        // flips the "ran" flag when the tool IS session_start). The gate message
+        // supersedes the soft nudge, so we return it directly without running the
+        // handler. Disabled by default => `shouldGate` returns false and nothing
+        // below changes.
+        if (nudge && shouldGate(nudge, toolName)) {
+            const gated = gateResult();
+            void postLogEntry(client, {
+                toolName,
+                durationMs: Date.now() - start,
+                success: false,
+                errorMessage: 'session-start gate: call orboto_session_start first',
+                clientHint,
+            });
+            return gated;
+        }
+        try {
+            const handlerResult = await handler(args, extra);
+            // ORB-1697 - the central response budget. Applied HERE, once, so it
+            // covers every registered tool instead of relying on 168 handlers to
+            // each stay small. Over-budget payloads come back truncated with an
+            // explicit `__truncation` block + a handle for the remainder; the
+            // measured sizes go into the call log either way.
+            const budgeted = applyResponseBudget(toolName, handlerResult);
+            const result = budgeted.result;
+            // Success path - but the handler can also signal a "soft"
+            // failure via { isError: true } in the result. We treat that
+            // as success=false in the log so dashboards reflect actual
+            // user-visible failures.
+            const isError = result.isError === true;
+            void postLogEntry(client, {
+                toolName,
+                durationMs: Date.now() - start,
+                success: !isError,
+                errorMessage: isError && result.content[0] && 'text' in result.content[0]
+                    ? redactSecrets(String(result.content[0].text)).slice(0, 500)
+                    : undefined,
+                clientHint,
+                responseChars: budgeted.responseChars,
+                truncatedChars: budgeted.truncatedChars,
+            });
+            // ORB-1727 - agent-mail piggyback: the client captured the api's
+            // `x-orboto-agent-mail` header on the request this tool just made.
+            // Append a compact pointer while mail is pending - zero bytes when
+            // the inbox is empty, and never on the messages tool itself (the
+            // caller is already fetching).
+            const withMail = appendMailNudge(client, toolName, result);
+            return wantsNudge ? prependNudge(withMail) : withMail;
+        }
+        catch (err) {
+            const durationMs = Date.now() - start;
+            // ORB-1174 - an OrbotoApiError carries a real HTTP status + message.
+            // Return it as a structured isError result so the agent + human see
+            // WHY (401 vs 404 vs 500) and can self-correct, instead of the
+            // runtime's opaque "Error occurred during tool execution".
+            if (err instanceof OrbotoApiError) {
+                const text = formatApiError(err);
+                void postLogEntry(client, { toolName, durationMs, success: false, statusCode: err.status, errorMessage: redactSecrets(text).slice(0, 500), clientHint });
+                // Still surface the reminder alongside the actionable error so a
+                // first-call failure doesn't swallow the one-time nudge.
+                const errResult = { isError: true, content: [{ type: 'text', text }] };
+                return wantsNudge ? prependNudge(errResult) : errResult;
+            }
+            // Anything else is unexpected (a bug, not an API rejection) - log
+            // and re-throw so it surfaces loudly rather than being swallowed.
+            void postLogEntry(client, {
+                toolName,
+                durationMs,
+                success: false,
+                errorMessage: redactSecrets(err instanceof Error ? err.message : String(err)).slice(0, 500),
+                clientHint,
+            });
+            throw err;
+        }
+    };
+}
+/**
+ * Both `config` and the registerTool call use loose types - the SDK
+ * has multiple overloads (with / without input schema) and threading
+ * generic params through the wrapper makes TS pick the wrong overload
+ * for some tools (the admin ones in this case land on the
+ * no-input-schema overload). Type-correctness is enforced at the
+ * original tool-config declaration site instead.
+ */
+/**
+ * ORB-1727 - append the pending-inbox pointer to a tool result. Reads the
+ * count the OrbotoClient captured from the last response header; costs
+ * nothing when the inbox is empty and skips the fetch/ack tool itself.
+ */
+/** Exported for the ORB-1733 regression test. */
+export function appendMailNudge(client, toolName, result) {
+    if (!client.pendingAgentMail || toolName === 'orboto_messages')
+        return result;
+    // ORB-1733: the nudge lives ONLY in a text content block. Never touch
+    // structuredContent - the SDK validates it against the tool's declared
+    // outputSchema, and an injected extra key fails validation and errors
+    // the entire tool call for as long as mail sits unread.
+    const line = `You have ${client.pendingAgentMail} unread agent message(s) - fetch them with orboto_messages.`;
+    return {
+        ...result,
+        content: [...result.content, { type: 'text', text: line }],
+    };
+}
+export function registerWithMetrics(server, client, clientHint, 
+// ORB-1331 - shared per-session/-process nudge state. Every tool
+// registered through this closure reads/advances the same flag, so the
+// one-time session-start reminder fires on whichever tool is called
+// first (unless it is `orboto_session_start`).
+nudge) {
+    return (toolName, config, handler) => {
+        // ORB-1692 - every raw-shape input becomes strict + alias-resolving.
+        // Central here so a new tool cannot ship permissive; empty/absent
+        // shapes stay untouched (they carry no fields to guard).
+        let cfg = config?.inputSchema && isRawShape(config.inputSchema)
+            // ORB-1817 - `client` + `clientHint` let a validation failure log
+            // through the same instrument path as a handler error (Part C):
+            // the SDK validates BEFORE this handler wrapper ever runs, so this
+            // is the only place that sees the failure.
+            ? { ...config, inputSchema: buildStrictInputSchema(toolName, config.inputSchema, client, clientHint) }
+            : config;
+        // ORB-1738 - every declared output shape ADVERTISES the response
+        // budget's optional __truncation marker. The SDK emits
+        // additionalProperties:false for output schemas, and strict clients
+        // validate structuredContent against that - an over-budget response
+        // carrying the (undeclared) marker was rejected wholesale
+        // (list_projects failed on EVERY call). Same central place as the
+        // input fix so no tool can ship an outputSchema that fights the
+        // budget layer.
+        if (cfg?.outputSchema && isRawShape(cfg.outputSchema)) {
+            cfg = {
+                ...cfg,
+                // ORB-1805 - the ADVERTISED (compact, open) form; the exact
+                // shape stays TruncationBlockSchema for runtime assertions.
+                outputSchema: { ...cfg.outputSchema, __truncation: TruncationBlockAdvertisedSchema.optional() },
+            };
+        }
+        // ORB-1741 - manifest diet: the wire manifest carries a one-sentence
+        // summary; the full guidance is captured for orboto_help. Central
+        // here so a new tool cannot ship a manifest essay by accident.
+        if (typeof cfg?.description === 'string' && cfg.description.length > 0) {
+            captureToolDoc(toolName, cfg.description);
+            cfg = { ...cfg, description: summarizeToolDescription(toolName, cfg.description) };
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        server.registerTool(toolName, cfg, withMetrics(client, toolName, clientHint, handler, nudge));
+    };
+}

package/dist/with-metrics.test.js

@@ -0,0 +1,230 @@
+/**
+ * ORB-311 Phase F - withMetrics wrapper unit tests.
+ *
+ * The wrapper's contract:
+ *   - Always calls the underlying handler exactly once.
+ *   - On success: posts {toolName, durationMs, success: true, ...}.
+ *   - On thrown error: posts success: false + errorMessage, re-throws.
+ *   - On `result.isError === true`: treats as success: false.
+ * - The instrument POST is fire-and-forget - never delays the caller.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient, OrbotoApiError } from './orboto-client.js';
+import { withMetrics } from './with-metrics.js';
+import { createNudgeState, SESSION_START_NUDGE, SESSION_START_GATE_MESSAGE } from './session-nudge.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+/** Capture every POST body the client makes and let the test inspect them. */
+function captureFetch() {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const body = init?.body ? JSON.parse(init.body) : undefined;
+        calls.push({ url: url.toString(), body });
+        return {
+            ok: true, status: 201, statusText: 'OK',
+            json: async () => ({ id: '00000000-0000-0000-0000-000000000001' }),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+describe('withMetrics', () => {
+    it('logs success: true with measured duration on a normal handler', async () => {
+        const calls = captureFetch();
+        const wrapped = withMetrics(client, 'orboto_test', undefined, async () => ({
+            content: [{ type: 'text', text: 'ok' }],
+        }));
+        const result = await wrapped({});
+        expect(result.content[0]).toEqual({ type: 'text', text: 'ok' });
+        // Wait one microtask so the fire-and-forget POST resolves.
+        await new Promise((r) => setImmediate(r));
+        expect(calls).toHaveLength(1);
+        expect(calls[0].url).toContain('/admin/mcp/instrument');
+        const body = calls[0].body;
+        expect(body.toolName).toBe('orboto_test');
+        expect(body.success).toBe(true);
+        expect(body.durationMs).toBeGreaterThanOrEqual(0);
+    });
+    it('logs success: false + errorMessage when the handler throws, then re-throws', async () => {
+        const calls = captureFetch();
+        const wrapped = withMetrics(client, 'orboto_explode', undefined, async () => {
+            throw new Error('kaboom');
+        });
+        await expect(wrapped({})).rejects.toThrow('kaboom');
+        await new Promise((r) => setImmediate(r));
+        const body = calls[0].body;
+        expect(body.success).toBe(false);
+        expect(body.errorMessage).toBe('kaboom');
+    });
+    // ORB-1174 - an OrbotoApiError becomes a structured, actionable isError
+    // result (not the runtime's opaque generic) so the agent can self-correct.
+    it('maps OrbotoApiError to a distinct, actionable isError result per status', async () => {
+        captureFetch();
+        const run = async (status, body) => {
+            const wrapped = withMetrics(client, 'orboto_x', undefined, async () => {
+                throw new OrbotoApiError(status, body, 'https://orboto.example/x');
+            });
+            const res = await wrapped({});
+            expect(res.isError).toBe(true);
+            return res.content[0].text;
+        };
+        const unauth = await run(401, '{"error":"Invalid API key"}');
+        expect(unauth).toContain('401');
+        expect(unauth).toMatch(/re-?authenticate/i);
+        expect(unauth).toContain('Invalid API key'); // the API's own message
+        const notFound = await run(404, '{"error":"Ticket not found"}');
+        expect(notFound).toContain('404');
+        expect(notFound).toMatch(/not found/i);
+        const server = await run(503, 'upstream down');
+        expect(server).toContain('503');
+        expect(server).toMatch(/retry/i);
+        // distinct messages, not the same opaque blob
+        expect(unauth).not.toBe(notFound);
+        expect(notFound).not.toBe(server);
+    });
+    it('treats result.isError=true as success: false (soft failure)', async () => {
+        const calls = captureFetch();
+        const wrapped = withMetrics(client, 'orboto_softfail', undefined, async () => ({
+            content: [{ type: 'text', text: 'permission denied' }],
+            isError: true,
+        }));
+        const result = await wrapped({});
+        expect(result.isError).toBe(true);
+        await new Promise((r) => setImmediate(r));
+        const body = calls[0].body;
+        expect(body.success).toBe(false);
+        expect(body.errorMessage).toBe('permission denied');
+    });
+    it('threads clientHint into the log entry', async () => {
+        const calls = captureFetch();
+        const wrapped = withMetrics(client, 'orboto_test', 'cursor', async () => ({
+            content: [{ type: 'text', text: 'ok' }],
+        }));
+        await wrapped({});
+        await new Promise((r) => setImmediate(r));
+        const body = calls[0].body;
+        expect(body.clientHint).toBe('cursor');
+    });
+    it('does not block when the instrument POST fails - handler still resolves', async () => {
+        // First call (the handler-as-fetch?) returns ok; but our handler
+        // doesn't fetch; the only fetch the wrapper makes is to /instrument.
+        // Mock that one to fail - caller must still get the original
+        // result back.
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+            ok: false, status: 500, statusText: 'Server Error',
+            json: async () => ({ error: 'kaboom' }),
+            text: async () => '',
+        }));
+        const wrapped = withMetrics(client, 'orboto_test', undefined, async () => ({
+            content: [{ type: 'text', text: 'survives' }],
+        }));
+        const result = await wrapped({});
+        expect(result.content[0]).toEqual({ type: 'text', text: 'survives' });
+    });
+    // ORB-1180 - admin-panel visibility: the failure log carries the
+    // structured HTTP status, and any secret-shaped text is redacted.
+    it('logs the structured statusCode on an OrbotoApiError', async () => {
+        const calls = captureFetch();
+        const wrapped = withMetrics(client, 'orboto_x', undefined, async () => {
+            throw new OrbotoApiError(403, '{"error":"Forbidden"}', 'https://orboto.example/x');
+        });
+        await wrapped({});
+        await new Promise((r) => setImmediate(r));
+        const body = calls[0].body;
+        expect(body.success).toBe(false);
+        expect(body.statusCode).toBe(403);
+        expect(body.errorMessage).toContain('403');
+    });
+    // ORB-1331 - the shared nudge state threads through the wrapper: the
+    // first non-session_start dispatch carries the one-time reminder,
+    // later dispatches are clean, and a session_start-first flow never
+    // sees it. structuredContent is left intact.
+    it('prepends the session-start nudge on the first non-session_start dispatch, once', async () => {
+        captureFetch();
+        const nudge = createNudgeState();
+        const handler = async () => ({
+            content: [{ type: 'text', text: 'ok' }],
+            structuredContent: { a: 1 },
+        });
+        const list = withMetrics(client, 'orboto_list_projects', undefined, handler, nudge);
+        const first = await list({});
+        expect(first.content[0].text).toBe(SESSION_START_NUDGE);
+        expect(first.content[1].text).toBe('ok');
+        expect(first.structuredContent).toEqual({ a: 1 }); // untouched
+        const second = await list({});
+        expect(second.content[0].text).toBe('ok'); // clean
+    });
+    it('does not nudge when the first dispatch IS orboto_session_start', async () => {
+        captureFetch();
+        const nudge = createNudgeState();
+        const handler = async () => ({ content: [{ type: 'text', text: 'rules' }] });
+        const start = withMetrics(client, 'orboto_session_start', undefined, handler, nudge);
+        const list = withMetrics(client, 'orboto_list_projects', undefined, handler, nudge);
+        const first = await start({});
+        expect(first.content[0].text).toBe('rules'); // no nudge
+        const second = await list({});
+        expect(second.content[0].text).toBe('rules'); // still clean
+    });
+    it('surfaces the nudge alongside an OrbotoApiError on a first-call failure', async () => {
+        captureFetch();
+        const nudge = createNudgeState();
+        const wrapped = withMetrics(client, 'orboto_list_projects', undefined, async () => {
+            throw new OrbotoApiError(403, '{"error":"Forbidden"}', 'https://orboto.example/x');
+        }, nudge);
+        const res = await wrapped({});
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toBe(SESSION_START_NUDGE);
+        expect(res.content[1].text).toContain('403');
+    });
+    // ORB-1471 - the HARD session-start gate. When the workspace requires it,
+    // the wrapper REFUSES a non-session-start tool without running its handler,
+    // returns the instructive gate message, and logs the refusal. A
+    // session_start call unlocks the session; after that everything runs.
+    it('gates a non-session-start tool until session_start runs, without invoking the handler', async () => {
+        const calls = captureFetch();
+        const nudge = createNudgeState(true); // gate ON
+        const listHandler = vi.fn(async () => ({ content: [{ type: 'text', text: 'projects' }] }));
+        const startHandler = vi.fn(async () => ({ content: [{ type: 'text', text: 'rules' }] }));
+        const list = withMetrics(client, 'orboto_list_projects', undefined, listHandler, nudge);
+        const start = withMetrics(client, 'orboto_session_start', undefined, startHandler, nudge);
+        // First call is refused - handler never runs.
+        const refused = await list({});
+        expect(refused.isError).toBe(true);
+        expect(refused.content[0].text).toBe(SESSION_START_GATE_MESSAGE);
+        expect(listHandler).not.toHaveBeenCalled();
+        await new Promise((r) => setImmediate(r));
+        const gateLog = calls.find((c) => c.body?.errorMessage?.includes('session-start gate'));
+        expect(gateLog).toBeDefined();
+        // Running session_start unlocks the session.
+        const rules = await start({});
+        expect(rules.content[0].text).toBe('rules');
+        expect(startHandler).toHaveBeenCalledTimes(1);
+        // Now the previously-gated tool runs normally.
+        const ok = await list({});
+        expect(ok.content[0].text).toBe('projects');
+        expect(listHandler).toHaveBeenCalledTimes(1);
+    });
+    it('does not gate anything when the gate is disabled (default)', async () => {
+        captureFetch();
+        const nudge = createNudgeState(); // gate OFF
+        const handler = vi.fn(async () => ({ content: [{ type: 'text', text: 'ok' }] }));
+        const list = withMetrics(client, 'orboto_list_projects', undefined, handler, nudge);
+        const res = await list({});
+        // Still nudged (soft), but NOT refused - the handler ran.
+        expect(res.content[1].text).toBe('ok');
+        expect(handler).toHaveBeenCalledTimes(1);
+    });
+    it('redacts secret-shaped text from the logged errorMessage', async () => {
+        const calls = captureFetch();
+        const wrapped = withMetrics(client, 'orboto_x', undefined, async () => {
+            throw new Error('failed with token orb_abcdef1234567890 and Bearer eyJabcdefghij.k.l');
+        });
+        await expect(wrapped({})).rejects.toThrow();
+        await new Promise((r) => setImmediate(r));
+        const body = calls[0].body;
+        expect(body.errorMessage).not.toContain('orb_abcdef1234567890');
+        expect(body.errorMessage).toContain('orb_[redacted]');
+        expect(body.errorMessage).not.toContain('eyJabcdefghij.k.l');
+    });
+});