@brunobracaioli/aibrain 0.2.0-beta.1 → 0.3.0-beta.13

package/dist/mcp.mjs

@@ -3,6 +3,9 @@ import { createHash, randomUUID } from 'node:crypto';
 const MAX_BODY = 256 * 1024;
 const MAX_SESSION_ID = 256;
 const TIMEOUT_MS = 10_000;
+const MAX_BUDGET_SNAPSHOT_AGE_MS = 15_000;
+const MAX_RETRY_AFTER_MS = 3_600_000;
+const SAFE_IDENTIFIER = /^[A-Za-z0-9._:-]{1,128}$/u;
 const MAX_ENDPOINT_LENGTH = 2_048;
 const SUPPORTED_PROTOCOL_VERSIONS = new Set([
   '2024-11-05',
@@ -147,11 +150,12 @@ async function responseObject(response) {
  * @param {JsonObject} body
  * @param {string | undefined} sessionId
  * @param {string | undefined} protocolVersion
+ * @param {number} [timeoutMs]
  * @returns {Promise<CallResult>}
  */
-async function call(url, token, body, sessionId, protocolVersion) {
+async function call(url, token, body, sessionId, protocolVersion, timeoutMs = TIMEOUT_MS) {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
   const expectedId = Object.hasOwn(body, 'id') ? body.id : undefined;
   try {
     const response = await fetch(url, {
@@ -216,6 +220,324 @@ async function call(url, token, body, sessionId, protocolVersion) {
   }
 }
 
+/**
+ * Send one already validated, content-free telemetry report over the existing
+ * authenticated MCP transport. The tool name and all protocol fields are
+ * fixed here; callers cannot select a server or tool.
+ *
+ * @param {string} endpoint
+ * @param {string} token
+ * @param {JsonObject} report
+ * @param {number} [deadlineMs]
+ * @returns {Promise<{accepted:true, duplicate:boolean}>}
+ */
+export async function reportContextTelemetry(endpoint, token, report, deadlineMs = 8_000) {
+  if (!Number.isFinite(deadlineMs) || deadlineMs <= 0 || deadlineMs > 8_000)
+    throw new Error('mcp_deadline_invalid');
+  const url = endpointUrl(endpoint).toString();
+  if (typeof token !== 'string' || token.trim() === '') throw new Error('mcp_auth_denied');
+  const deadline = Date.now() + deadlineMs;
+  const remaining = () => {
+    const value = deadline - Date.now();
+    if (value <= 0) throw new Error('mcp_request_timeout');
+    return Math.min(TIMEOUT_MS, value);
+  };
+  const initialized = await call(
+    url,
+    token,
+    {
+      jsonrpc: '2.0',
+      id: randomUUID(),
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-03-26',
+        capabilities: {},
+        clientInfo: { name: 'aibrain-telemetry-report', version: '0.3.0-beta.9' },
+      },
+    },
+    undefined,
+    undefined,
+    remaining(),
+  );
+  const initializeResult = initialized.parsed?.result;
+  if (
+    !initialized.response.ok ||
+    initialized.parsed?.error ||
+    !isObject(initializeResult) ||
+    typeof initializeResult.protocolVersion !== 'string' ||
+    !SUPPORTED_PROTOCOL_VERSIONS.has(initializeResult.protocolVersion)
+  )
+    throw new Error(responseError(initialized.response, 'mcp_initialize_denied'));
+  const protocolVersion = initializeResult.protocolVersion;
+  const initializedNotification = await call(
+    url,
+    token,
+    { jsonrpc: '2.0', method: 'notifications/initialized', params: {} },
+    initialized.sessionId,
+    protocolVersion,
+    remaining(),
+  );
+  if (
+    !initializedNotification.response.ok &&
+    ![202, 204].includes(initializedNotification.response.status)
+  )
+    throw new Error(responseError(initializedNotification.response, 'mcp_initialize_denied'));
+  const reportResponse = await call(
+    url,
+    token,
+    {
+      jsonrpc: '2.0',
+      id: randomUUID(),
+      method: 'tools/call',
+      params: { name: 'brain_context_report', arguments: report },
+    },
+    initialized.sessionId,
+    protocolVersion,
+    remaining(),
+  );
+  const result = reportResponse.parsed?.result;
+  if (!reportResponse.response.ok || reportResponse.parsed?.error || !isObject(result))
+    throw new Error(responseError(reportResponse.response, 'mcp_report_rejected'));
+  if (result.isError === true)
+    throw new Error(structuredErrorCode(result) ?? 'mcp_report_rejected');
+  const structured = isObject(result.structuredContent) ? result.structuredContent : result;
+  if (
+    !isObject(structured) ||
+    structured.accepted !== true ||
+    typeof structured.duplicate !== 'boolean'
+  )
+    throw new Error('mcp_report_rejected');
+  return { accepted: true, duplicate: structured.duplicate };
+}
+
+/**
+ * Ask the fixed v2 selection tool for a shadow decision. The caller supplies
+ * only the already-redacted projection; this function owns the destination,
+ * MCP lifecycle and response binding.
+ * @param {string} endpoint
+ * @param {string} token
+ * @param {JsonObject} request
+ * @param {number} [deadlineMs]
+ * @returns {Promise<JsonObject>}
+ */
+export async function selectContextShadow(endpoint, token, request, deadlineMs = 15_000) {
+  if (!Number.isFinite(deadlineMs) || deadlineMs <= 0 || deadlineMs > 15_000)
+    throw new Error('mcp_deadline_invalid');
+  const url = endpointUrl(endpoint).toString();
+  if (typeof token !== 'string' || token.trim() === '') throw new Error('mcp_auth_denied');
+  const projection = isObject(request.projection) ? request.projection : null;
+  const options = isObject(request.options) ? request.options : null;
+  if (projection === null || options === null) throw new Error('mcp_shadow_request_invalid');
+  const deadline = Date.now() + deadlineMs;
+  const remaining = () => {
+    const value = deadline - Date.now();
+    if (value <= 0) throw new Error('mcp_request_timeout');
+    return Math.min(TIMEOUT_MS, value);
+  };
+  const initialized = await call(
+    url,
+    token,
+    {
+      jsonrpc: '2.0',
+      id: randomUUID(),
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-03-26',
+        capabilities: {},
+        clientInfo: { name: 'aibrain-claude-shadow', version: '0.3.0-beta.9' },
+      },
+    },
+    undefined,
+    undefined,
+    remaining(),
+  );
+  const initializeResult = initialized.parsed?.result;
+  if (
+    !initialized.response.ok ||
+    initialized.parsed?.error ||
+    !isObject(initializeResult) ||
+    typeof initializeResult.protocolVersion !== 'string' ||
+    !SUPPORTED_PROTOCOL_VERSIONS.has(initializeResult.protocolVersion)
+  )
+    throw new Error(responseError(initialized.response, 'mcp_initialize_denied'));
+  const protocolVersion = initializeResult.protocolVersion;
+  const initializedNotification = await call(
+    url,
+    token,
+    { jsonrpc: '2.0', method: 'notifications/initialized', params: {} },
+    initialized.sessionId,
+    protocolVersion,
+    remaining(),
+  );
+  if (
+    !initializedNotification.response.ok &&
+    ![202, 204].includes(initializedNotification.response.status)
+  )
+    throw new Error(responseError(initializedNotification.response, 'mcp_initialize_denied'));
+  const response = await call(
+    url,
+    token,
+    {
+      jsonrpc: '2.0',
+      id: randomUUID(),
+      method: 'tools/call',
+      params: { name: 'brain_context_select', arguments: request },
+    },
+    initialized.sessionId,
+    protocolVersion,
+    remaining(),
+  );
+  const result = response.parsed?.result;
+  if (!response.response.ok || response.parsed?.error || !isObject(result))
+    throw new Error(responseError(response.response, 'mcp_shadow_rejected'));
+  if (result.isError === true)
+    throw new Error(structuredErrorCode(result) ?? 'mcp_shadow_rejected');
+  const structured = isObject(result.structuredContent) ? result.structuredContent : result;
+  if (!isObject(structured)) throw new Error('mcp_shadow_rejected');
+  return structured;
+}
+
+/**
+ * Read the provider-free shared capacity snapshot. The snapshot is advisory;
+ * atomic admission remains authoritative and this helper never retries or
+ * reserves capacity.
+ * @param {string} endpoint
+ * @param {string} token
+ * @param {number} [deadlineMs]
+ * @returns {Promise<JsonObject>}
+ */
+export async function readContextBudget(endpoint, token, deadlineMs = 8_000) {
+  if (!Number.isFinite(deadlineMs) || deadlineMs <= 0 || deadlineMs > 8_000)
+    throw new Error('mcp_deadline_invalid');
+  const url = endpointUrl(endpoint).toString();
+  if (typeof token !== 'string' || token.trim() === '') throw new Error('mcp_auth_denied');
+  const fetchedAt = Date.now();
+  const deadline = Date.now() + deadlineMs;
+  const remaining = () => {
+    const value = deadline - Date.now();
+    if (value <= 0) throw new Error('mcp_request_timeout');
+    return Math.min(TIMEOUT_MS, value);
+  };
+  const initialized = await call(
+    url,
+    token,
+    {
+      jsonrpc: '2.0',
+      id: randomUUID(),
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-03-26',
+        capabilities: {},
+        clientInfo: { name: 'aibrain-context-budget', version: '0.3.0-beta.9' },
+      },
+    },
+    undefined,
+    undefined,
+    remaining(),
+  );
+  const initializeResult = initialized.parsed?.result;
+  if (
+    !initialized.response.ok ||
+    initialized.parsed?.error ||
+    !isObject(initializeResult) ||
+    typeof initializeResult.protocolVersion !== 'string' ||
+    !SUPPORTED_PROTOCOL_VERSIONS.has(initializeResult.protocolVersion)
+  )
+    throw new Error(responseError(initialized.response, 'mcp_initialize_denied'));
+  const protocolVersion = initializeResult.protocolVersion;
+  const initializedNotification = await call(
+    url,
+    token,
+    { jsonrpc: '2.0', method: 'notifications/initialized', params: {} },
+    initialized.sessionId,
+    protocolVersion,
+    remaining(),
+  );
+  if (
+    !initializedNotification.response.ok &&
+    ![202, 204].includes(initializedNotification.response.status)
+  )
+    throw new Error(responseError(initializedNotification.response, 'mcp_initialize_denied'));
+  const response = await call(
+    url,
+    token,
+    {
+      jsonrpc: '2.0',
+      id: randomUUID(),
+      method: 'tools/call',
+      params: { name: 'brain_context_budget', arguments: { schema_version: 1 } },
+    },
+    initialized.sessionId,
+    protocolVersion,
+    remaining(),
+  );
+  const result = response.parsed?.result;
+  if (!response.response.ok || response.parsed?.error || !isObject(result))
+    throw new Error(responseError(response.response, 'mcp_budget_unavailable'));
+  if (result.isError === true) throw new Error(structuredErrorCode(result) ?? 'mcp_budget_denied');
+  const structured = isObject(result.structuredContent) ? result.structuredContent : result;
+  if (!isObject(structured)) throw new Error('mcp_budget_unavailable');
+  const numericFields = [
+    structured.available_requests,
+    structured.available_tokens,
+    structured.output_token_allowance,
+    structured.max_batches_per_operation,
+    structured.retry_after_ms,
+    structured.provider_batches,
+  ];
+  const numericFieldsValid = numericFields.every(
+    (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0,
+  );
+  const maxBatches = structured.max_batches_per_operation;
+  const retryAfter = structured.retry_after_ms;
+  const serverTime = Date.parse(String(structured.server_time));
+  const expiresAt = Date.parse(String(structured.expires_at));
+  const windowEnd = Date.parse(String(structured.window_end));
+  const localElapsed = Date.now() - fetchedAt;
+  const allowed = new Set([
+    'schema_version',
+    'server_time',
+    'expires_at',
+    'window_end',
+    'available_requests',
+    'available_tokens',
+    'output_token_allowance',
+    'max_batches_per_operation',
+    'account_in_flight',
+    'retry_after_ms',
+    'provider_batches',
+    'provider_model',
+    'correlation_id',
+  ]);
+  if (
+    Object.keys(structured).some((key) => !allowed.has(key)) ||
+    structured.schema_version !== 1 ||
+    !validTimestamp(structured.server_time) ||
+    !validTimestamp(structured.expires_at) ||
+    !validTimestamp(structured.window_end) ||
+    !Number.isFinite(serverTime) ||
+    !Number.isFinite(expiresAt) ||
+    !Number.isFinite(windowEnd) ||
+    localElapsed < 0 ||
+    localElapsed > MAX_BUDGET_SNAPSHOT_AGE_MS ||
+    expiresAt <= serverTime ||
+    expiresAt - serverTime > MAX_BUDGET_SNAPSHOT_AGE_MS ||
+    expiresAt > windowEnd ||
+    !numericFieldsValid ||
+    typeof maxBatches !== 'number' ||
+    maxBatches > 4 ||
+    typeof retryAfter !== 'number' ||
+    retryAfter > MAX_RETRY_AFTER_MS ||
+    typeof structured.account_in_flight !== 'boolean' ||
+    (structured.provider_model !== null &&
+      (typeof structured.provider_model !== 'string' || structured.provider_model.length > 128)) ||
+    typeof structured.correlation_id !== 'string' ||
+    !SAFE_IDENTIFIER.test(structured.correlation_id)
+  )
+    throw new Error('mcp_budget_response_invalid');
+  return structured;
+}
+
 /** @param {unknown} value @returns {boolean} */
 function validTimestamp(value) {
   return typeof value === 'string' && Number.isFinite(Date.parse(value));
@@ -256,7 +578,7 @@ async function providerFreeProbeV1(endpoint, token) {
       params: {
         protocolVersion: '2025-03-26',
         capabilities: {},
-        clientInfo: { name: 'aibrain', version: '0.2.0-beta.1' },
+        clientInfo: { name: 'aibrain', version: '0.3.0-beta.9' },
       },
     },
     undefined,
@@ -310,7 +632,7 @@ async function providerFreeProbeV1(endpoint, token) {
         arguments: {
           schema_version: 1,
           client: 'codex_app_server',
-          client_version: '0.2.0-beta.1',
+          client_version: '0.3.0-beta.9',
           session_ref: sessionRef,
           revision,
           observed_at: new Date().toISOString(),
@@ -402,7 +724,7 @@ export async function providerFreeProbeV2(endpoint, token, policy, clients) {
       params: {
         protocolVersion: '2025-03-26',
         capabilities: {},
-        clientInfo: { name: 'aibrain', version: '0.2.0-beta.1' },
+        clientInfo: { name: 'aibrain', version: '0.3.0-beta.9' },
       },
     },
     undefined,
@@ -606,7 +928,7 @@ export async function providerFreeProbeV2(endpoint, token, policy, clients) {
   await callTool(2, 'brain_context_select', {
     schema_version: 2,
     client: clients === 'claude' ? 'claude_code' : 'codex_app_server',
-    client_version: '0.2.0-beta.1',
+    client_version: '0.3.0-beta.9',
     session_ref: sessionRef,
     revision,
     observed_at: now,
@@ -619,7 +941,7 @@ export async function providerFreeProbeV2(endpoint, token, policy, clients) {
     await callTool(3, 'brain_context_compact', {
       schema_version: 2,
       client: 'claude_code',
-      client_version: '0.2.0-beta.1',
+      client_version: '0.3.0-beta.9',
       session_ref: sessionRef,
       revision,
       observed_at: now,

package/dist/monitor.mjs

@@ -6,6 +6,12 @@ import { constants } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  CODEX_APP_SERVER_PROFILE,
+  CODEX_LAUNCH_ENVELOPE,
+  ownedAppServerConfigArgs,
+  parseCodexLaunchEnvelope,
+} from './codex-permissions.mjs';
 
 const root = dirname(fileURLToPath(import.meta.url));
 const endpoint = process.env.AIBRAIN_MCP_URL?.trim();
@@ -25,6 +31,7 @@ if (parsed.username || parsed.password || parsed.hash)
 if (parsed.search) throw new Error('aibrain_monitor_endpoint_query');
 const canonical = join(root, 'assets', 'codex-context-compaction.mjs');
 await access(canonical, constants.R_OK);
+const launchEnvelope = parseCodexLaunchEnvelope(process.env[CODEX_LAUNCH_ENVELOPE]);
 const policyText = process.env.CODEX_CONTEXT_POLICY_JSON;
 let policy;
 if (policyText === undefined) {
@@ -80,6 +87,9 @@ const env = {
   CODEX_RECOVERY_MCP_TOKEN: token,
   CODEX_CONTEXT_COMPACT_AT: String(policy?.compactAtPercent ?? 85),
 };
+delete env[CODEX_LAUNCH_ENVELOPE];
+delete env[CODEX_APP_SERVER_PROFILE];
+if (launchEnvelope?.profile !== undefined) env[CODEX_APP_SERVER_PROFILE] = launchEnvelope.profile;
 if (policy !== null) env.CODEX_CONTEXT_POLICY_JSON = JSON.stringify(policy);
 else delete env.CODEX_CONTEXT_POLICY_JSON;
 delete env.JEV_API_KEY;
@@ -98,6 +108,7 @@ const child = spawn(
     `mcp_servers.aibrain_context.url=${parsed.toString()}`,
     '-c',
     'mcp_servers.aibrain_context.bearer_token_env_var="CODEX_RECOVERY_MCP_TOKEN"',
+    ...(launchEnvelope === null ? [] : ownedAppServerConfigArgs(launchEnvelope)),
   ],
   { cwd: process.cwd(), env, stdio: 'inherit' },
 );

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.2.0-beta.1",
+  "version": "0.3.0-beta.13",
   "type": "module"
 }

package/dist/platform.mjs

@@ -70,13 +70,43 @@ export function nativeVersion(executable, environment = process.env) {
 export function isTestedNativeVersion(client, version) {
   const value = version.trim();
   if (client === 'claude')
-    return /^(?:(?:claude(?:\s+code)?)\s+)?2\.1\.(?:294|295|296)(?:\s+\(Claude\s+Code\))?$/iu.test(
+    return /^(?:(?:claude(?:\s+code)?)\s+)?2\.1\.(?:294|295|296|299|300|301|302)(?:\s+\(Claude\s+Code\))?$/iu.test(
       value,
     );
-  return /^(?:codex(?:-cli)?\s+)?0\.16(?:1\.0|2\.0|2\.1)$/iu.test(value);
+  return /^(?:codex(?:-cli)?\s+)?0\.16(?:1\.0|2\.0|2\.1|3\.0)$/iu.test(value);
+}
+
+const TESTED_NATIVE_VERSIONS = Object.freeze({
+  claude: Object.freeze([
+    '2.1.294',
+    '2.1.295',
+    '2.1.296',
+    '2.1.299',
+    '2.1.300',
+    '2.1.301',
+    '2.1.302',
+  ]),
+  codex: Object.freeze(['0.161.0', '0.162.0', '0.162.1', '0.163.0']),
+});
+
+/** @param {'claude'|'codex'} client @param {string} version */
+export function nativeVersionDiagnostic(client, version) {
+  const detected = version.trim();
+  const versionPattern =
+    client === 'claude'
+      ? /^(?:(?:claude(?:\s+code)?)\s+)?(\d{1,3})\.(\d{1,3})\.(\d{1,3})(-[A-Za-z0-9.-]+)?(?:\s+\(Claude\s+Code\))?$/iu
+      : /^(?:codex(?:-cli)?\s+)?(\d{1,3})\.(\d{1,3})\.(\d{1,3})(-[A-Za-z0-9.-]+)?$/iu;
+  const versionMatch = detected.match(versionPattern);
+  const safeDetected = versionMatch
+    ? `${versionMatch[1]}.${versionMatch[2]}.${versionMatch[3]}${versionMatch[4] ? '-prerelease' : ''}`
+    : 'unavailable';
+  const label = client === 'claude' ? 'Claude Code' : 'Codex CLI';
+  const tested = TESTED_NATIVE_VERSIONS[client].join(', ');
+  return `${client}_version_unverified: ${label} detected version ${safeDetected}; tested stable versions: ${tested}. Update AI Brain to a compatible version, then run aibrain doctor --json or install a qualified stable native version.`;
 }
 
 /** @param {'claude'|'codex'} client @param {string} version */
 export function assertTestedNativeVersion(client, version) {
-  if (!isTestedNativeVersion(client, version)) throw new Error(`${client}_version_unverified`);
+  if (!isTestedNativeVersion(client, version))
+    throw new Error(nativeVersionDiagnostic(client, version));
 }

package/dist/state.mjs

@@ -30,7 +30,9 @@ import { isValidPolicy } from './policy.mjs';
  *   token: string,
  *   tokenSha256: string,
  *   probe: Probe,
- *   context?: import('./policy.mjs').ContextPolicy
+ *   context?: import('./policy.mjs').ContextPolicy,
+ *   telemetry?: { enabled: boolean, disclosedAt: string | null },
+ *   claudeObservation?: { shadowEnabled: boolean, diagnosticsEnabled: boolean, disclosedAt: string | null }
  * }} Config
  */
 
@@ -125,6 +127,35 @@ function isDisclosure(value) {
   return value === DISCLOSURE_VERSION || value === LEGACY_DISCLOSURE_VERSION;
 }
 
+/** @param {unknown} value */
+function isTelemetry(value) {
+  return (
+    isRecord(value) &&
+    typeof value.enabled === 'boolean' &&
+    (value.disclosedAt === null ||
+      (typeof value.disclosedAt === 'string' &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value.disclosedAt) &&
+        Number.isFinite(Date.parse(value.disclosedAt)))) &&
+    Object.keys(value).every((key) => ['enabled', 'disclosedAt'].includes(key))
+  );
+}
+
+/** @param {unknown} value */
+function isClaudeObservation(value) {
+  return (
+    isRecord(value) &&
+    typeof value.shadowEnabled === 'boolean' &&
+    typeof value.diagnosticsEnabled === 'boolean' &&
+    (value.disclosedAt === null ||
+      (typeof value.disclosedAt === 'string' &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value.disclosedAt) &&
+        Number.isFinite(Date.parse(value.disclosedAt)))) &&
+    Object.keys(value).every((key) =>
+      ['shadowEnabled', 'diagnosticsEnabled', 'disclosedAt'].includes(key),
+    )
+  );
+}
+
 /** @param {unknown} value */
 function isConfig(value) {
   if (!isRecord(value)) return false;
@@ -166,6 +197,9 @@ function isConfig(value) {
   )
     return false;
   if (value.schemaVersion === 1 && value.context !== undefined) return false;
+  if (value.telemetry !== undefined && !isTelemetry(value.telemetry)) return false;
+  if (value.claudeObservation !== undefined && !isClaudeObservation(value.claudeObservation))
+    return false;
   const allowed = new Set([
     'schemaVersion',
     'packageVersion',
@@ -180,6 +214,8 @@ function isConfig(value) {
     'tokenSha256',
     'probe',
     'context',
+    'telemetry',
+    'claudeObservation',
   ]);
   return Object.keys(value).every((key) => allowed.has(key));
 }
@@ -189,9 +225,9 @@ export function isValidConfig(value) {
   return isConfig(value);
 }
 
-/** @returns {Promise<Config | null>} */
-export async function readConfig() {
-  const root = stateRoot();
+/** @param {string | undefined} [rootOverride] @returns {Promise<Config | null>} */
+export async function readConfig(rootOverride) {
+  const root = rootOverride === undefined ? stateRoot() : resolve(rootOverride);
   await assertSafePath(root);
   const path = join(root, 'config.json');
   try {
@@ -254,6 +290,73 @@ export async function tokenDigest(token) {
   return createHash('sha256').update(token, 'utf8').digest('hex');
 }
 
+/** @param {{endpoint: string, token: string, telemetry?: {enabled: boolean, disclosedAt?: string | null}}} config */
+export function telemetryConfigBinding(config) {
+  if (
+    !isRecord(config) ||
+    typeof config.endpoint !== 'string' ||
+    typeof config.token !== 'string' ||
+    !isRecord(config.telemetry) ||
+    config.telemetry.enabled !== true ||
+    typeof config.telemetry.disclosedAt !== 'string'
+  )
+    throw new Error('telemetry_state_mismatch');
+  let endpoint;
+  try {
+    endpoint = new URL(config.endpoint).toString();
+  } catch {
+    throw new Error('telemetry_state_mismatch');
+  }
+  return createHash('sha256')
+    .update(`${endpoint}\u0000${config.token}\u0000${config.telemetry.disclosedAt}`, 'utf8')
+    .digest('hex');
+}
+
+/** @param {{endpoint: string, token: string, claudeObservation?: {shadowEnabled?: boolean, diagnosticsEnabled?: boolean, disclosedAt?: string | null}}} config */
+export function claudeObservationConfigBinding(config) {
+  if (
+    !isRecord(config) ||
+    typeof config.endpoint !== 'string' ||
+    typeof config.token !== 'string' ||
+    !isRecord(config.claudeObservation) ||
+    typeof config.claudeObservation.disclosedAt !== 'string'
+  )
+    throw new Error('claude_observation_state_mismatch');
+  let endpoint;
+  try {
+    endpoint = new URL(config.endpoint).toString();
+  } catch {
+    throw new Error('claude_observation_state_mismatch');
+  }
+  return createHash('sha256')
+    .update(`${endpoint}\u0000${config.token}\u0000${config.claudeObservation.disclosedAt}`, 'utf8')
+    .digest('hex');
+}
+
+/**
+ * Bind launcher-managed Claude checkpoints to the authenticated account and
+ * disclosure, independently of shadow/diagnostics opt-ins.
+ * @param {{endpoint: string, token: string, disclosedAt?: string}} config
+ */
+export function claudeCheckpointConfigBinding(config) {
+  if (
+    !isRecord(config) ||
+    typeof config.endpoint !== 'string' ||
+    typeof config.token !== 'string' ||
+    typeof config.disclosedAt !== 'string'
+  )
+    throw new Error('claude_checkpoint_state_mismatch');
+  let endpoint;
+  try {
+    endpoint = new URL(config.endpoint).toString();
+  } catch {
+    throw new Error('claude_checkpoint_state_mismatch');
+  }
+  return createHash('sha256')
+    .update(`${endpoint}\u0000${config.token}\u0000${config.disclosedAt}`, 'utf8')
+    .digest('hex');
+}
+
 /** @param {string} path */
 export async function readPrivateToken(path) {
   const resolved = resolve(path);