thumbgate 1.34.3 → 1.37.1

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,89 @@
+# Third-Party Notices
+
+This document lists the third-party open-source software and assets used in the
+ThumbGate project (`thumbgate` npm package and related repositories).
+
+The ThumbGate source code itself is released under the MIT License (see `LICENSE`).
+The following notices are required by the respective upstream licenses.
+
+## Open-Source Dependencies
+
+The following direct dependencies are bundled or used in ThumbGate runtime
+services:
+
+| Package | License | Publisher / Source |
+| --- | --- | --- |
+| `@anthropic-ai/sdk` | MIT | Anthropic, PBC |
+| `@google/genai` | Apache-2.0 | Google LLC |
+| `@lancedb/lancedb` | Apache-2.0 | LanceDB.com |
+| `apache-arrow` | Apache-2.0 | Apache Software Foundation |
+| `better-sqlite3` | MIT | Joshua Wise |
+| `dotenv` | BSD-2-Clause | scottmotte / Motdotla, Inc. |
+| `js-yaml` | MIT | Vitaly Puzrin |
+| `playwright-core` | Apache-2.0 | Microsoft Corporation |
+| `protobufjs` | Apache-2.0 / BSD-3-Clause | Daniel Wirtz |
+| `stripe` | MIT | Stripe, Inc. |
+
+The following development dependencies are used to build, test, and release
+ThumbGate:
+
+| Package | License | Publisher / Source |
+| --- | --- | --- |
+| `@changesets/changelog-github` | MIT | Thinkmill |
+| `@changesets/cli` | MIT | Thinkmill |
+| `@playwright/test` | Apache-2.0 | Microsoft Corporation |
+| `c8` | MIT |bcoe / c8 contributors |
+| `undici` | MIT | Matteo Collina |
+
+Additional transitive dependencies are installed automatically by npm. A
+complete machine-readable dependency tree can be generated by running:
+
+```bash
+npm install -g license-checker
+license-checker --direct 0 --out licenses.json
+```
+
+## Trademarks and Brand Attribution
+
+ThumbGate® is an independent product. The following trademarks and brands are
+owned by their respective owners and are referenced solely for compatibility
+and nominative fair use:
+
+- Anthropic, Claude, and Claude Code are trademarks of Anthropic, PBC.
+- OpenAI, ChatGPT, and Codex are trademarks of OpenAI, Inc.
+- Cursor is a trademark of Anysphere, Inc.
+- GitHub is a trademark of GitHub, Inc.
+- Google, Gemini, and Google Cloud Platform are trademarks of Google LLC.
+- Perplexity is a trademark of Perplexity AI, Inc.
+- Hermes Agent is a project by Nous Research.
+- Model Context Protocol (MCP) is a protocol introduced by Anthropic, PBC.
+- Nvidia is a trademark of Nvidia Corporation.
+- Railway is a trademark of Railway Corporation.
+- Stripe is a trademark of Stripe, Inc.
+- Supabase is a trademark of Supabase, Inc.
+- PostHog is a trademark of PostHog, Inc.
+- Plausible is a trademark of Plausible Insights OÜ.
+
+Use of any third-party mark in this documentation, marketing material, or code
+does not imply affiliation with, endorsement by, or sponsorship from the trademark
+owner.
+
+## Font and Asset Attribution
+
+ThumbGate uses system and open-source fonts where applicable. Any brand icons,
+diagrams, or demo media that are not original to ThumbGate are credited in the
+`public/assets/` directory or in the asset metadata file where applicable.
+
+## Proprietary Boundary
+
+The open-source `thumbgate` npm package (MIT licensed) covers the local CLI,
+MCP server, and public adapters. Hosted cloud services, enterprise dashboards,
+multi-tenant adapters, commercial policy-sync engines, and operational tooling
+for `thumbgate.app` are proprietary and not licensed under the public repository
+terms unless a separate written agreement is executed.
+
+## Updates
+
+This file is updated as part of each release. If you believe an attribution is
+missing or incorrect, please open an issue at:
+https://github.com/IgorGanapolsky/ThumbGate/issues

package/adapters/claude/.mcp.json

@@ -2,13 +2,13 @@
   "mcpServers": {
     "thumbgate": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.34.3", "thumbgate", "serve"]
+      "args": ["--yes", "--package", "thumbgate@1.37.1", "thumbgate", "serve"]
     }
   },
   "hooks": {
     "preToolUse": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.34.3", "thumbgate", "gate-check"]
+      "args": ["--yes", "--package", "thumbgate@1.37.1", "thumbgate", "gate-check"]
     }
   }
 }

package/adapters/forge/forge.yaml

@@ -9,12 +9,12 @@ version: "1"
 skills:
   thumbgate-gate-check:
     description: "ThumbGate PreToolUse gate — blocks known-bad tool calls"
-    command: "npx --yes --package thumbgate@1.34.3 thumbgate gate-check"
+    command: "npx --yes --package thumbgate@1.37.1 thumbgate gate-check"
     trigger: pre_tool_use
 
   thumbgate-feedback:
     description: "ThumbGate feedback capture — logs user prompt context"
-    command: "npx --yes --package thumbgate@1.34.3 thumbgate hook-auto-capture"
+    command: "npx --yes --package thumbgate@1.37.1 thumbgate hook-auto-capture"
     trigger: user_prompt
 
 mcp:
@@ -23,6 +23,6 @@ mcp:
     args:
       - "--yes"
       - "--package"
-      - "thumbgate@1.34.3"
+      - "thumbgate@1.37.1"
       - "thumbgate"
       - "serve"

package/adapters/future-agi/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "thumbgate": {
+      "command": "npx",
+      "args": ["--yes", "--package", "thumbgate@1.37.1", "thumbgate", "serve"]
+    }
+  }
+}

package/adapters/future-agi/FUTURE_AGI.md

@@ -0,0 +1,23 @@
+# Future AGI Integration Guide
+
+> Bridging Open-Source Agent Evaluation, Simulation, and Tracing with Deterministic PreToolUse Guardrails.
+
+## Overview
+Future AGI (`future-agi/future-agi`) provides an open-source platform collapsing simulation, evals, guardrails, tracing, gateway, and optimization into a single feedback loop.
+
+**ThumbGate** acts as the **deterministic pre-action execution firewall** at the tool-call interface. When paired together:
+1. **Simulation to Gate Synthesis**: Adversarial test failures in Future AGI are compiled into fail-closed PreToolUse gates in ThumbGate.
+2. **Runtime Action Receipts**: Blocked mutations, tool calls, and human approvals in ThumbGate emit OTel spans back to Future AGI for continuous model optimization.
+
+## Model Candidates
+- `future-agi/agentic-eval-v1`: Specialized evaluator model for multi-turn tool calling and groundedness verification.
+- `future-agi/guardrail-scanner`: Sub-10ms scanner for prompt injection and PII detection.
+
+## Quickstart
+```bash
+# Evaluate a tool call payload with the Future AGI simulation rubric:
+npx --package=thumbgate futureagi-bridge --simulate '{"tool": "Bash", "command": "publish_release"}'
+
+# Run the Doctor check on the Future AGI bridge:
+npx --package=thumbgate futureagi-bridge --doctor
+```

package/adapters/future-agi/config.toml

@@ -0,0 +1,3 @@
+[mcp.servers.thumbgate]
+command = "npx"
+args = ["--yes", "--package", "thumbgate@1.37.1", "thumbgate", "serve"]

package/adapters/future-agi/future-agi-bridge.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const { evaluatePayload, synthesizeSelfHealingGate, exportOtelSpan } = require('../../scripts/future-agi-evaluator.js');
+
+module.exports = {
+  evaluatePayload,
+  synthesizeSelfHealingGate,
+  exportOtelSpan,
+};

package/adapters/future-agi/opencode.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "thumbgate": {
+      "command": "npx",
+      "args": ["--yes", "--package", "thumbgate@1.37.1", "thumbgate", "serve"]
+    }
+  }
+}

package/adapters/herdr/herdr-plugin.toml

@@ -0,0 +1,18 @@
+[plugin]
+id = "thumbgate-approvals"
+name = "ThumbGate Approvals"
+version = "1.37.1"
+minHerdrVersion = "0.7.0"
+description = "Pre-action governance, spend guard, and safety approval gates for multi-agent terminal sessions in Herdr."
+platforms = ["linux", "macos", "windows"]
+author = "ThumbGate"
+homepage = "https://thumbgate.ai"
+repository = "https://github.com/IgorGanapolsky/ThumbGate"
+category = "Security & Governance"
+
+[mcp_server]
+command = "npx"
+args = ["--yes", "--package", "thumbgate@1.37.1", "thumbgate", "serve"]
+
+[mcp_server.env]
+THUMBGATE_ENFORCE_ENTITLEMENTS = "1"

package/adapters/mcp/server-stdio.js

@@ -91,6 +91,12 @@ const {
   readTaskOutcomes,
   recordTaskOutcome,
 } = require('../../scripts/task-outcomes');
+const {
+  appendReceiptToLedger,
+  readReceiptLedger,
+  reconcileReceiptChain,
+  verifyBrokerReceipt,
+} = require('../../scripts/broker-execution-receipts');
 const {
   listEscalations,
   requestEscalation,
@@ -328,7 +334,7 @@ const {
   finalizeSession: finalizeFeedbackSession,
 } = require('../../scripts/feedback-session');
 
-const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.34.3' };
+const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.37.1' };
 const COMMERCE_CATEGORIES = [
   'product_recommendation',
   'brand_compliance',
@@ -638,29 +644,37 @@ function buildContextPackResponse(args = {}) {
     maxItems: Number(args.maxItems || 8),
     maxChars: Number(args.maxChars || 6000),
     namespaces,
+    strategy: args.strategy || null,
+    contextEnvelope: args.contextEnvelope || null,
   });
-  // Feed outcome-paired action receipts into the pack so an action->outcome
-  // history is available alongside lessons/rules. Additive + guarded: a
-  // receipt-store failure must never break context pack construction.
   try {
     const receiptEntries = buildReceiptContextEntries(args.query || '', Number(args.maxItems || 8));
     if (Array.isArray(receiptEntries) && receiptEntries.length && Array.isArray(pack.items)) {
       for (const entry of receiptEntries) {
+        if (pack.items.length >= pack.maxItems) break;
+        const receiptText = entry && entry.text ? String(entry.text) : '';
+        const receiptChars = `Action receipt outcome\n${receiptText}`.length;
+        if (pack.usedChars + receiptChars > pack.maxChars) continue;
         pack.items.push({
           id: `action-receipt_${entry && entry.score != null ? entry.score : ''}_${pack.items.length}`,
           namespace: 'action-receipts',
           title: 'Action receipt outcome',
-          structuredContext: { rawContent: entry && entry.text ? String(entry.text) : '' },
+          structuredContext: { rawContent: receiptText },
+          provenance: { source: 'action-receipts', freshness: 'unknown' },
           tags: ['action-receipt', 'outcome-paired'],
           score: entry && typeof entry.score === 'number' ? entry.score : 0,
         });
+        pack.usedChars += receiptChars;
       }
       if (!Array.isArray(pack.namespaces)) pack.namespaces = [];
       if (!pack.namespaces.includes('action-receipts')) pack.namespaces.push('action-receipts');
+      if (pack.visibility) {
+        pack.visibility.itemCount = pack.items.length;
+        pack.visibility.remainingCharBudget = Math.max(pack.maxChars - pack.usedChars, 0);
+        pack.visibility.visibleTitles = pack.items.slice(0, 5).map((item) => item.title);
+      }
     }
-  } catch {
-    // ignore receipt enrichment failures
-  }
+  } catch { /* ignore */ }
   return toTextResult(pack);
 }
 
@@ -772,13 +786,23 @@ function buildEstimateUncertaintyResponse(args = {}) {
   });
 }
 
-async function callTool(name, args = {}) {
+async function callTool(name, args = {}, options = {}) {
   const attemptStartMs = Date.now();
   const activeProfile = getActiveMcpProfile();
+  const attribution = {
+    clientId: options.clientId || null,
+    sessionId: options.sessionId || null,
+    agentId: options.agentId || null,
+    serverName: options.serverName || 'mcp',
+  };
+  const trace = (outcome = {}) => recordMcpToolTrace(name, args, {
+    ...outcome,
+    ...attribution,
+  });
   try {
     assertToolAllowed(name, activeProfile);
   } catch (error) {
-    recordMcpToolTrace(name, args, {
+    trace({
       success: false,
       category: 'profile_denied',
       evidence: [error.message],
@@ -788,7 +812,7 @@ async function callTool(name, args = {}) {
   }
   const capability = getToolCapability(name);
   if (!capability.available) {
-    recordMcpToolTrace(name, args, {
+    trace({
       success: false,
       category: 'capability',
       evidence: capability.missingModules,
@@ -806,6 +830,55 @@ async function callTool(name, args = {}) {
     throw error;
   }
 
+  // WriteGuard: pre-action MCP governance (destructive pattern + tier policy).
+  // Runs before contract validation so schema gaps cannot bypass interdiction.
+  // Covers stdio tools/call and HTTP transport (both route through callTool).
+  if (process.env.THUMBGATE_DISABLE_MCP_WRITEGUARD !== '1') {
+    const { evaluateMcpCall } = require('../../src/mcp-writeguard');
+    const writeGuardReceipt = evaluateMcpCall(
+      {
+        server: attribution.serverName || 'mcp',
+        tool: name,
+        parameters: args || {},
+        context: {
+          user: attribution.agentId || process.env.THUMBGATE_AGENT_ID || process.env.USER || 'operator',
+          client: attribution.clientId || 'mcp-client',
+          sessionId: attribution.sessionId || process.env.THUMBGATE_SESSION_AGENT || 'default-session',
+        },
+      },
+      {
+        // Existing Semantic Firewall / gates own admin escalation UX.
+        // Destructive patterns still return decision=blocked.
+        allowAdmin: options.allowAdmin !== false
+          && process.env.THUMBGATE_WRITEGUARD_STRICT_ADMIN !== '1',
+        requireReviewForPrivileged: options.requireReviewForPrivileged === true
+          || process.env.THUMBGATE_WRITEGUARD_REQUIRE_REVIEW === '1',
+      },
+    );
+    if (writeGuardReceipt.decision === 'blocked' || writeGuardReceipt.decision === 'escalated') {
+      const err = new Error(
+        `Action blocked by WriteGuard [${writeGuardReceipt.decision}]: ${
+          writeGuardReceipt.reasons.join('; ') || writeGuardReceipt.decision
+        }`,
+      );
+      err.errorCategory = 'permission';
+      err.code = writeGuardReceipt.decision === 'blocked'
+        ? 'WRITEGUARD_BLOCKED'
+        : 'WRITEGUARD_ESCALATED';
+      err.isRetryable = false;
+      err.writeGuardReceipt = writeGuardReceipt;
+      trace({
+        success: false,
+        category: 'blocked',
+        evidence: writeGuardReceipt.reasons.length > 0
+          ? writeGuardReceipt.reasons
+          : [writeGuardReceipt.decision],
+        latencyMs: Date.now() - attemptStartMs,
+      });
+      throw err;
+    }
+  }
+
   // Validate tool input contract against schema
   const { TOOLS } = require('../../scripts/tool-registry');
   const toolDef = TOOLS.find(t => t.name === name);
@@ -816,7 +889,7 @@ async function callTool(name, args = {}) {
       const err = new Error(`Tool contract violation on '${name}': ${validation.errors.join('; ')}`);
       err.errorCategory = 'contract';
       err.isRetryable = false;
-      recordMcpToolTrace(name, args, {
+      trace({
         success: false,
         category: 'contract',
         evidence: validation.errors,
@@ -826,13 +899,41 @@ async function callTool(name, args = {}) {
     }
   }
 
+  // Model-carried MCP session handles (InfoWorld correlation controls).
+  // Authorize whenever the model re-emits a handle, or when
+  // THUMBGATE_MCP_HANDLE_REQUIRED=1 forces handles on every tools/call.
+  if (process.env.THUMBGATE_DISABLE_MCP_SESSION_HANDLES !== '1') {
+    const {
+      authorizeMcpToolCall,
+    } = require('../../scripts/mcp-session-handles');
+    const handleAuth = authorizeMcpToolCall(name, args || {}, {
+      principalId: process.env.THUMBGATE_PRINCIPAL_ID || process.env.THUMBGATE_AGENT_ID || null,
+      tenantId: process.env.THUMBGATE_TENANT_ID || 'default',
+    });
+    if (handleAuth && handleAuth.allowed === false) {
+      const err = new Error(
+        `Action blocked by MCP session handle gate [${handleAuth.code}]: ${handleAuth.reason}`
+      );
+      err.errorCategory = 'permission';
+      err.code = handleAuth.code || 'SESSION_HANDLE_DENIED';
+      err.isRetryable = false;
+      trace({
+        success: false,
+        category: 'session_handle',
+        evidence: [handleAuth.code, handleAuth.reason],
+        latencyMs: Date.now() - attemptStartMs,
+      });
+      throw err;
+    }
+  }
+
   if (name !== 'workflow_sentinel' && process.env.THUMBGATE_DISABLE_MCP_FIREWALL !== '1') {
     const firewallResult = (await evaluateGatesAsync(name, args)) || evaluateSecretGuard({ tool_name: name, tool_input: args });
     if (firewallResult && firewallResult.decision === 'deny') {
       const err = new Error(`Action blocked by Semantic Firewall: ${firewallResult.message}`);
       err.errorCategory = 'permission';
       err.isRetryable = false;
-      recordMcpToolTrace(name, args, {
+      trace({
         success: false,
         category: 'permission',
         evidence: [firewallResult.message],
@@ -846,7 +947,7 @@ async function callTool(name, args = {}) {
   try {
     result = await callToolInner(name, args);
   } catch (err) {
-    recordMcpToolTrace(name, args, {
+    trace({
       success: false,
       category: err.errorCategory || 'execution',
       evidence: [err.code || err.message || 'tool execution failed'],
@@ -860,7 +961,7 @@ async function callTool(name, args = {}) {
     const err = new Error(`Structured output contract violation on '${name}': ${outputValidation.errors.join('; ')}`);
     err.errorCategory = 'output_contract';
     err.isRetryable = false;
-    recordMcpToolTrace(name, args, {
+    trace({
       success: false,
       category: 'output_contract',
       evidence: outputValidation.errors,
@@ -868,7 +969,7 @@ async function callTool(name, args = {}) {
     });
     throw err;
   }
-  recordMcpToolTrace(name, args, {
+  trace({
     success: true,
     category: 'success',
     evidence: [`tool completed in ${latencyMs}ms`],
@@ -896,17 +997,51 @@ function validateMcpToolOutput(toolDef, result) {
   return validateStructuredOutput(result.structuredContent, toolDef.outputSchema);
 }
 
+function resolveWriteRiskTierForTool(name) {
+  try {
+    const { TOOLS, inferWriteRiskTier } = require('../../scripts/tool-registry');
+    const tool = TOOLS.find((candidate) => candidate.name === name);
+    return inferWriteRiskTier(name, tool?.annotations || {});
+  } catch {
+    return null;
+  }
+}
+
 function recordMcpToolTrace(name, args, outcome = {}) {
   try {
+    const category = outcome.category || 'unknown';
+    // Policy / profile / session denials are WriteGuard "blocked"; execution
+    // and contract failures stay "failed".
+    const blockedCategories = new Set([
+      'blocked',
+      'denied',
+      'permission',
+      'session_handle',
+      'profile_denied',
+    ]);
+    const blocked = blockedCategories.has(category) || outcome.blocked === true;
+    const kpiOutcome = blocked
+      ? 'blocked'
+      : (outcome.success === true ? 'successful' : 'failed');
+    const writeRiskTier = outcome.writeRiskTier || resolveWriteRiskTierForTool(name);
+    // KPI identity must come only from trusted transport/options metadata
+    // (HTTP OAuth session, explicit callTool options). Never trust tool args —
+    // callers can poison clientId/sessionId via schemas that allow extras.
     recordToolCall({
       toolName: name,
-      serverName: 'mcp',
+      serverName: outcome.serverName || 'mcp',
       latencyMs: Number(outcome.latencyMs || 0),
       success: outcome.success === true,
-      agentId: args.agentId || args.processId || args.taskId || 'unknown',
+      outcome: kpiOutcome,
+      blocked,
+      agentId: outcome.agentId || process.env.THUMBGATE_AGENT_ID || process.env.THUMBGATE_SESSION_AGENT || 'unknown',
+      clientId: outcome.clientId || null,
+      sessionId: outcome.sessionId || null,
+      writeRiskTier,
       metadata: {
-        category: outcome.category || 'unknown',
+        category,
         traceId: args.traceId || args.taskId || null,
+        writeRiskTier,
       },
     });
   } catch {
@@ -1260,18 +1395,28 @@ async function callToolInner(name, args) {
       return toTextResult(formatUnifiedContext(ctx));
     }
     case 'satisfy_gate': {
-      if (!args.gate) {
-        throw new Error('gate is required');
+      // Accept gate | gateId | gate_id — docs/block messages historically said gateId=
+      // while the schema only lists `gate`, which deadlocked agents (2026-08-03).
+      const gateName = args.gate || args.gateId || args.gate_id;
+      if (!gateName) {
+        throw new Error('gate is required (aliases: gateId, gate_id)');
       }
-      const entry = satisfyCondition(args.gate, args.evidence || '', args.structuredReasoning || null);
-      const result = { satisfied: true, gate: args.gate, ...entry };
+      // Attribute the override to the MCP surface. Omitting this defaults the
+      // audit record to 'cli', which would misreport every agent-driven unlock.
+      const entry = satisfyCondition(
+        gateName,
+        args.evidence || '',
+        args.structuredReasoning || null,
+        { source: 'mcp', actor: args.actor || 'agent' },
+      );
+      const result = { satisfied: true, gate: gateName, ...entry };
       // Log structured reasoning to audit trail for learning
       if (args.structuredReasoning) {
         recordAuditEvent({
           toolName: 'satisfy_gate',
-          toolInput: { gate: args.gate },
+          toolInput: { gate: gateName },
           decision: 'allow',
-          gateId: args.gate,
+          gateId: gateName,
           message: `Gate satisfied with structured reasoning: ${args.structuredReasoning.conclusion || 'no conclusion'}`,
           source: 'structured-reasoning',
         });
@@ -1368,6 +1513,27 @@ async function callToolInner(name, args) {
           ? getReceiptForAction(args.actionId)
           : getRecentReceipts(Number(args.limit || 20)),
       );
+    case 'verify_broker_execution_receipt':
+      return toTextResult(verifyBrokerReceipt(args.receipt || args));
+    case 'issue_broker_execution_receipt': {
+      // Intentionally NOT on the default MCP allowlist. Even with a host key,
+      // agent-facing sessions must not mint broker signatures. Brokers call the
+      // library/CLI outside the agent tool surface.
+      const error = new Error(
+        'issue_broker_execution_receipt is not available on the agent MCP surface. '
+        + 'Credential-holding brokers must sign out-of-band via scripts/broker-execution-receipts.js.',
+      );
+      error.code = 'THUMBGATE_BROKER_ISSUE_NOT_ON_AGENT_SURFACE';
+      throw error;
+    }
+    case 'record_broker_execution_receipt': {
+      const receipt = args.receipt || args;
+      return toTextResult(appendReceiptToLedger(receipt));
+    }
+    case 'get_broker_execution_receipts':
+      return toTextResult(readReceiptLedger().slice(-Number(args.limit || 20)));
+    case 'reconcile_broker_receipt_chain':
+      return toTextResult(reconcileReceiptChain());
     case 'record_task_outcome':
       return toTextResult(recordTaskOutcome(args));
     case 'get_task_outcomes': {
@@ -1597,6 +1763,8 @@ async function callToolInner(name, args) {
         windowSize: args.windowSize,
         perEntryMaxChars: args.perEntryMaxChars,
         totalMaxChars: args.totalMaxChars,
+        matryoshkaEmbedding: args.matryoshkaEmbedding !== false,
+        matryoshkaOptions: args.matryoshkaOptions || undefined,
       }));
     case 'plan_agent_design_governance':
       return toTextResult(buildAgentDesignGovernancePlan(args));
@@ -1815,8 +1983,52 @@ function acquireLock() {
   return { lockFile, cleanupLock: () => {} };
 }
 
+/**
+ * Register this MCP session as a first-class agent identity at startup.
+ * Fulfills the registry's "called on MCP server startup" contract: a session
+ * with an attributed id gets that id registered; a session without one gets a
+ * generated id, exported via THUMBGATE_SESSION_AGENT so every audit record and
+ * the gates-engine identity gate can attribute its tool calls. Best-effort by
+ * design — identity bootstrap must never block or crash server start.
+ */
+function registerSessionIdentity() {
+  try {
+    const { registerAgent, loadAgentRegistry, getRegistryPath } = require('../../scripts/audit-trail');
+    const { withFileLedgerLock } = require('../../scripts/file-ledger-lock');
+    const envId = process.env.THUMBGATE_SESSION_AGENT || process.env.THUMBGATE_AGENT_ID || null;
+    // Check-then-append runs under the registry ledger lock: concurrent stdio
+    // servers inheriting one session id must not both pass the existence check
+    // and register duplicate rows. A busy lock throws into the catch below —
+    // the session simply starts unregistered and the next startup retries.
+    const finalId = withFileLedgerLock(`${getRegistryPath()}.lock`, () => {
+      const alreadyRegistered = envId
+        ? loadAgentRegistry().some((agent) => agent && agent.id === envId)
+        : false;
+      if (alreadyRegistered) return envId;
+      const record = registerAgent({
+        agentId: envId || undefined,
+        source: 'mcp',
+        metadata: { transport: 'stdio', pid: process.pid },
+      });
+      return record && record.id ? record.id : envId;
+    });
+    if (finalId && !process.env.THUMBGATE_SESSION_AGENT) {
+      process.env.THUMBGATE_SESSION_AGENT = finalId;
+    }
+    // MCP tool telemetry (recordMcpToolTrace) attributes via THUMBGATE_AGENT_ID;
+    // without this a generated identity would trace as agentId "unknown".
+    if (finalId && !process.env.THUMBGATE_AGENT_ID) {
+      process.env.THUMBGATE_AGENT_ID = finalId;
+    }
+    return finalId;
+  } catch {
+    return null;
+  }
+}
+
 function startStdioServer() {
   acquireLock();
+  registerSessionIdentity();
 
   process.stdin.resume();
 
@@ -1894,6 +2106,7 @@ module.exports = {
   handleRequest,
   callTool,
   startStdioServer,
+  registerSessionIdentity,
   acquireLock,
   toCaptureFeedbackTextResult,
   formatCorrectiveActionsReminder,

package/adapters/opencode/opencode.json

@@ -7,7 +7,7 @@
         "npx",
         "--yes",
         "--package",
-        "thumbgate@1.34.3",
+        "thumbgate@1.37.1",
         "thumbgate",
         "serve"
       ],