imprint-mcp 0.7.0 → 0.7.2

package/src/imprint/credential-store.ts

@@ -17,17 +17,21 @@
  * a downstream agent (OpenClaw/Hermes) which credentials it needs to ask
  * for when consuming a shared skill.
  */
+import { createHash, randomUUID } from 'node:crypto';
 import {
   existsSync,
   mkdirSync,
   readFileSync,
   readdirSync,
+  renameSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
 import { dirname, join as pathJoin } from 'node:path';
 import { argon2id } from '@noble/hashes/argon2.js';
 import envPaths from 'env-paths';
+import { withCredentialLock } from './credential-lock.ts';
+import { credentialObservation, recordCredentialEvent } from './credential-observation.ts';
 
 const PATHS = envPaths('imprint', { suffix: '' });
 const SERVICE_NAME = 'imprint';
@@ -62,6 +66,8 @@ export interface CookieRecord {
   sameSite?: string;
   hostOnly?: boolean;
   creationIndex?: number;
+  /** Independent HTTP observation retained alongside its exact browser baseline. */
+  httpResponse?: { browserSnapshotHash: string | null; deleted?: boolean };
 }
 
 export interface StorageRecord {
@@ -75,6 +81,10 @@ export interface StorageRecord {
  *  await to keep the call sites uniform. */
 export interface CredentialBackend {
   readonly id: 'keyring' | 'encrypted-file' | 'legacy-json';
+  /** One lock for the actual backend namespace, independent of IMPRINT_HOME. */
+  readonly lockDirectory?: string;
+  /** Refresh process-local data once the namespace lock is held. */
+  refresh?(): Promise<void>;
   getSecret(site: string, name: string): Promise<string | null>;
   setSecret(site: string, name: string, value: string): Promise<void>;
   deleteSecret(site: string, name: string): Promise<void>;
@@ -206,10 +216,19 @@ class EncryptedFileBackend implements CredentialBackend {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic libsodium ref
   private sodium: any;
   private cachedKey: Uint8Array | null = null;
+  private cachedSaltB64: string | null = null;
   /** Cached decrypted shape — flushed back to disk on every mutation. */
   private cachedData: EncryptedFileShape | null = null;
   private passphraseProvider: () => Promise<string>;
 
+  get lockDirectory(): string {
+    return `${this.filePath}.lock`;
+  }
+
+  async refresh(): Promise<void> {
+    this.cachedData = null;
+  }
+
   constructor(opts: {
     filePath: string;
     // biome-ignore lint/suspicious/noExplicitAny: dynamic libsodium ref
@@ -226,6 +245,8 @@ class EncryptedFileBackend implements CredentialBackend {
     const sodium = this.sodium;
 
     if (!existsSync(this.filePath)) {
+      this.cachedKey = null;
+      this.cachedSaltB64 = null;
       // No store yet. For a READ (forWrite !== true), short-circuit with an
       // empty in-memory shape — there cannot be any credentials to return,
       // and prompting for a passphrase here would hang non-interactive
@@ -258,8 +279,10 @@ class EncryptedFileBackend implements CredentialBackend {
 
     // Try cached passphrase first if the user has set $IMPRINT_PASSPHRASE
     // and re-entered process.
-    const passphrase = await this.passphraseProvider();
-    const key = deriveKey(passphrase, salt);
+    const key =
+      this.cachedKey && this.cachedSaltB64 === parsed.saltB64
+        ? this.cachedKey
+        : deriveKey(await this.passphraseProvider(), salt);
     let plain: Uint8Array;
     try {
       plain = sodium.crypto_secretbox_open_easy(ct, nonce, key);
@@ -270,6 +293,7 @@ class EncryptedFileBackend implements CredentialBackend {
     }
     const text = new TextDecoder().decode(plain);
     this.cachedKey = key;
+    this.cachedSaltB64 = parsed.saltB64;
     this.cachedData = JSON.parse(text) as EncryptedFileShape;
   }
 
@@ -286,7 +310,18 @@ class EncryptedFileBackend implements CredentialBackend {
       ctB64: b64encode(ct),
     };
     mkdirSync(dirname(this.filePath), { recursive: true });
-    writeFileSync(this.filePath, JSON.stringify(wire), 'utf8');
+    const temporary = `${this.filePath}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporary, JSON.stringify(wire), { encoding: 'utf8', mode: 0o600 });
+      renameSync(temporary, this.filePath);
+      this.cachedSaltB64 = wire.saltB64;
+    } finally {
+      try {
+        unlinkSync(temporary);
+      } catch {
+        // Cleanup must not replace a failed write with a secondary error.
+      }
+    }
   }
 
   /** Persist using the SAME salt the file was loaded with. */
@@ -652,17 +687,103 @@ export function markLegacyStoreMigrated(site: string): void {
 // ─── High-level convenience API ────────────────────────────────────────────
 
 /** A site's full credential view: secrets values + cookies. Used by runtime. */
-interface SiteCredentialView {
+export interface SiteCredentialView {
   site: string;
   cookies: CookieRecord[];
   values: Record<string, string>;
   storage: StorageRecord[];
+  /** Raw durable material identity, before runtime normalization or env input. */
+  revision: string;
+  legacy?: true;
+}
+
+function credentialRevision(material: Omit<SiteCredentialView, 'revision'>): string {
+  const canonical = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(canonical);
+    if (value && typeof value === 'object')
+      return Object.fromEntries(
+        Object.entries(value)
+          .filter(([, entry]) => entry !== undefined)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([key, entry]) => [key, canonical(entry)]),
+      );
+    return value;
+  };
+  return createHash('sha256')
+    .update(JSON.stringify(canonical(material)))
+    .digest('hex');
+}
+
+function credentialLockDirectory(site: string, backend: CredentialBackend): string {
+  return (
+    backend.lockDirectory ??
+    pathJoin(
+      PATHS.config,
+      'credential-locks',
+      backend.id,
+      createHash('sha256').update(site).digest('hex'),
+    )
+  );
+}
+
+async function withSiteCredentialLock<T>(
+  site: string,
+  signal: AbortSignal | undefined,
+  work: (backend: CredentialBackend) => Promise<T>,
+): Promise<T> {
+  signal?.throwIfAborted();
+  const backend = await getCredentialBackend();
+  return withCredentialLock(credentialLockDirectory(site, backend), signal, async () => {
+    await backend.refresh?.();
+    signal?.throwIfAborted();
+    return work(backend);
+  });
+}
+
+/** Serializes a complete sign-in independently of the credential reads and commits it performs. */
+export async function acquireSiteAuthRecoveryLock(
+  site: string,
+  signal: AbortSignal,
+): Promise<() => Promise<void>> {
+  signal.throwIfAborted();
+  const backend = await getCredentialBackend();
+  const directory = pathJoin(
+    `${credentialLockDirectory(site, backend)}-auth-recovery`,
+    createHash('sha256').update(site).digest('hex'),
+  );
+  return new Promise((resolve, reject) => {
+    const held = withCredentialLock(
+      directory,
+      signal,
+      () =>
+        new Promise<void>((release) => {
+          resolve(() => {
+            release();
+            return held;
+          });
+        }),
+      250,
+    );
+    void held.catch(reject);
+  });
 }
 
 /** Loads everything we know about a site, falling back through the backends.
  *  Used at request time by runtime.executeWorkflow. */
-export async function loadSiteCredentials(site: string): Promise<SiteCredentialView> {
-  const backend = await getCredentialBackend();
+export async function loadSiteCredentials(
+  site: string,
+  options?: { signal?: AbortSignal },
+): Promise<SiteCredentialView> {
+  return withSiteCredentialLock(site, options?.signal, (backend) =>
+    loadSiteCredentialsUnlocked(site, backend),
+  );
+}
+
+async function loadSiteCredentialsUnlocked(
+  site: string,
+  backend: CredentialBackend,
+  includeLegacy = true,
+): Promise<SiteCredentialView> {
   const names = await backend.listSecrets(site);
   const values: Record<string, string> = {};
   for (const n of names) {
@@ -673,26 +794,113 @@ export async function loadSiteCredentials(site: string): Promise<SiteCredentialV
   const storage = (await backend.getStorage?.(site)) ?? [];
 
   // Fall through to legacy if the backend has nothing.
-  if (Object.keys(values).length === 0 && cookies.length === 0 && storage.length === 0) {
+  if (
+    includeLegacy &&
+    Object.keys(values).length === 0 &&
+    cookies.length === 0 &&
+    storage.length === 0
+  ) {
     const legacy = readLegacyStore(site);
     if (legacy) {
-      return { site, cookies: legacy.cookies, values: legacy.values, storage: [] };
+      const material = structuredClone({
+        site,
+        cookies: legacy.cookies,
+        values: legacy.values,
+        storage: [],
+      });
+      const result = { ...material, revision: credentialRevision(material), legacy: true as const };
+      const observation = credentialObservation(result, 'legacy-json');
+      if (observation) recordCredentialEvent('load', observation);
+      return result;
     }
   }
-  return { site, cookies, values, storage };
+  const material = structuredClone({ site, cookies, values, storage });
+  const result = { ...material, revision: credentialRevision(material) };
+  const observation = credentialObservation(result, backend.id);
+  if (observation) recordCredentialEvent('load', observation);
+  return result;
 }
 
 /** Convenience wrapper to persist cookies after a successful auth tool run.
  *  Delegates to the active credential backend's setCookies. */
-export async function saveSiteCookies(site: string, cookies: CookieRecord[]): Promise<void> {
-  const backend = await getCredentialBackend();
-  await backend.setCookies(site, cookies);
+export async function saveSiteCookies(
+  site: string,
+  cookies: CookieRecord[],
+  options?: { signal?: AbortSignal },
+): Promise<void> {
+  const signal = options?.signal;
+  await withSiteCredentialLock(site, signal, async (backend) => {
+    const previous = structuredClone(await backend.getCookies(site));
+    signal?.throwIfAborted();
+    try {
+      await backend.setCookies(site, cookies);
+      signal?.throwIfAborted();
+      await observeCommittedCredentials(site, backend);
+      signal?.throwIfAborted();
+    } catch (error) {
+      await backend.setCookies(site, previous);
+      throw error;
+    }
+  });
 }
 
 /** Persist browser storage through the active credential backend. */
-export async function saveSiteStorage(site: string, storage: StorageRecord[]): Promise<void> {
-  const backend = await getCredentialBackend();
-  await backend.setStorage?.(site, storage);
+export async function saveSiteStorage(
+  site: string,
+  storage: StorageRecord[],
+  options?: { signal?: AbortSignal },
+): Promise<void> {
+  const signal = options?.signal;
+  await withSiteCredentialLock(site, signal, async (backend) => {
+    const previous = structuredClone((await backend.getStorage?.(site)) ?? []);
+    signal?.throwIfAborted();
+    try {
+      await backend.setStorage?.(site, storage);
+      signal?.throwIfAborted();
+      await observeCommittedCredentials(site, backend);
+      signal?.throwIfAborted();
+    } catch (error) {
+      await backend.setStorage?.(site, previous);
+      throw error;
+    }
+  });
+}
+
+/** Publish a successful browser's complete cookie snapshot only if its durable
+ * starting revision is still current. Never merges removed cookies back in or
+ * overwrites newer auth, secrets or storage. Legacy fallback is read-only. */
+export async function compareAndSwapSiteCookies(
+  site: string,
+  expectedRevision: string,
+  cookies: CookieRecord[],
+  options?: { signal?: AbortSignal },
+): Promise<{ status: 'updated' | 'unchanged' | 'stale'; revision: string }> {
+  const signal = options?.signal;
+  const nextCookies = structuredClone(cookies);
+  return withSiteCredentialLock(site, signal, async (backend) => {
+    const current = await loadSiteCredentialsUnlocked(site, backend, false);
+    signal?.throwIfAborted();
+    if (current.revision !== expectedRevision)
+      return { status: 'stale', revision: current.revision };
+    const nextRevision = credentialRevision({
+      site,
+      cookies: nextCookies,
+      values: current.values,
+      storage: current.storage,
+    });
+    if (nextRevision === current.revision)
+      return { status: 'unchanged', revision: current.revision };
+    try {
+      await backend.setCookies(site, nextCookies);
+      signal?.throwIfAborted();
+      await observeCommittedCredentials(site, backend);
+      signal?.throwIfAborted();
+      return { status: 'updated', revision: nextRevision };
+    } catch (error) {
+      await backend.setCookies(site, current.cookies);
+      throw error;
+    }
+  });
 }
 
 /** Replace the durable auth material as one logical commit. Backends such as
@@ -702,43 +910,75 @@ export async function commitSiteAuthState(
   site: string,
   cookies: CookieRecord[],
   secrets: Record<string, string>,
+  options?: { signal?: AbortSignal; expectedRevision?: string },
 ): Promise<void> {
-  const backend = await getCredentialBackend();
-  const previousCookies = await backend.getCookies(site);
-  const previousSecrets = new Map<string, string | null>();
-  for (const name of Object.keys(secrets)) {
-    previousSecrets.set(name, await backend.getSecret(site, name));
-  }
-
-  try {
-    await backend.setCookies(site, cookies);
-    for (const [name, value] of Object.entries(secrets)) {
-      await backend.setSecret(site, name, value);
+  const signal = options?.signal;
+  await withSiteCredentialLock(site, signal, async (backend) => {
+    signal?.throwIfAborted();
+    let nextSecrets = secrets;
+    if (options?.expectedRevision !== undefined) {
+      const current = await loadSiteCredentialsUnlocked(site, backend);
+      if (current.revision !== options.expectedRevision) {
+        throw new Error('the saved session changed while this sign-in was running');
+      }
+      if (current.legacy) nextSecrets = { ...current.values, ...secrets };
     }
-  } catch (err) {
-    const rollbackFailures: string[] = [];
-    try {
-      await backend.setCookies(site, previousCookies);
-    } catch (rollbackErr) {
-      rollbackFailures.push(
-        `cookies: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
-      );
+    const previousCookies = structuredClone(await backend.getCookies(site));
+    const previousSecrets = new Map<string, string | null>();
+    for (const name of Object.keys(nextSecrets)) {
+      signal?.throwIfAborted();
+      previousSecrets.set(name, await backend.getSecret(site, name));
     }
-    for (const [name, value] of previousSecrets) {
+
+    try {
+      signal?.throwIfAborted();
+      await backend.setCookies(site, cookies);
+      signal?.throwIfAborted();
+      for (const [name, value] of Object.entries(nextSecrets)) {
+        await backend.setSecret(site, name, value);
+        signal?.throwIfAborted();
+      }
+      await observeCommittedCredentials(site, backend);
+      signal?.throwIfAborted();
+    } catch (err) {
+      const rollbackFailures: string[] = [];
       try {
-        if (value === null) await backend.deleteSecret(site, name);
-        else await backend.setSecret(site, name, value);
+        await backend.setCookies(site, previousCookies);
       } catch (rollbackErr) {
         rollbackFailures.push(
-          `${name}: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
+          `cookies: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
         );
       }
+      for (const [name, value] of previousSecrets) {
+        try {
+          if (value === null) await backend.deleteSecret(site, name);
+          else await backend.setSecret(site, name, value);
+        } catch (rollbackErr) {
+          rollbackFailures.push(
+            `${name}: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`,
+          );
+        }
+      }
+      const original = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        rollbackFailures.length > 0
+          ? `${original}; rollback also failed for ${rollbackFailures.join(', ')}`
+          : original,
+      );
     }
-    const original = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      rollbackFailures.length > 0
-        ? `${original}; rollback also failed for ${rollbackFailures.join(', ')}`
-        : original,
-    );
+  });
+}
+
+async function observeCommittedCredentials(
+  site: string,
+  backend: CredentialBackend,
+): Promise<void> {
+  if (!process.env.IMPRINT_CREDENTIAL_DIAGNOSTICS_PATH) return;
+  try {
+    const material = await loadSiteCredentialsUnlocked(site, backend);
+    const observation = credentialObservation(material, 'durable-commit');
+    if (observation) recordCredentialEvent('commit', observation);
+  } catch {
+    // A diagnostics read failure cannot invalidate a completed credential write.
   }
 }

package/src/imprint/live-component-recovery.ts

@@ -0,0 +1,73 @@
+import type { ComponentRecoveryOwner } from './component-recovery.ts';
+import {
+  type LiveComponentRecoveryInput,
+  type MasterTeachAgentOptions,
+  requestLiveComponentRecovery,
+} from './master-teach-agents.ts';
+import { currentUserInteraction, requestAgentInteraction } from './user-interaction.ts';
+
+/** Select an existing owner; never infer one from names or HTTP status. */
+export async function selectLiveComponentRecovery(
+  input: Omit<
+    LiveComponentRecoveryInput,
+    'contexts' | 'components' | 'authenticationAvailable' | 'phase'
+  > & {
+    phase?: string;
+    allowAuthentication?: boolean;
+    owners: readonly ComponentRecoveryOwner[];
+    agent: MasterTeachAgentOptions;
+  },
+): Promise<{ owner: ComponentRecoveryOwner; reason: string } | undefined> {
+  const interaction = currentUserInteraction();
+  const { agent, owners, allowAuthentication = true, ...failure } = input;
+  const applicable = owners.filter((owner) =>
+    owner.toolIds.includes(input.toolId ?? input.toolName),
+  );
+  const authenticationAvailable = allowAuthentication && (interaction?.hasAuthentication ?? false);
+  if (!authenticationAvailable && applicable.length === 0) return undefined;
+  if (new Set(applicable.map(({ id }) => id)).size !== applicable.length)
+    throw new Error('Component recovery owner ids must be unique for a caller');
+  const decision = await requestLiveComponentRecovery(
+    {
+      ...failure,
+      phase: input.phase ?? 'live',
+      authenticationAvailable,
+      components: applicable.map(({ recover: _recover, ...component }) => ({
+        ...component,
+        toolIds: [...component.toolIds],
+      })),
+      contexts:
+        interaction?.authenticationContexts().map((context) => ({
+          contextRef: context.contextRef,
+          label: context.label,
+          workflowPath: context.workflowPath,
+          latestAction: context.latestAction,
+          latestOk: context.latestOk,
+          latestStatus: context.latestStatus,
+          latestError: context.latestError,
+        })) ?? [],
+    },
+    agent,
+  );
+  if (decision.action === 'return_failure') return undefined;
+  if (decision.action === 'recover_component') {
+    const owner = applicable.find((owner) => owner.id === decision.componentId);
+    return owner ? { owner, reason: decision.reason } : undefined;
+  }
+  return {
+    owner: {
+      id: `authentication:${decision.plan.contextRef ?? decision.plan.toolName}`,
+      kind: 'authentication',
+      label: decision.plan.toolName,
+      toolIds: [input.toolId ?? input.toolName],
+      recover: async () => {
+        const result = await requestAgentInteraction(
+          { action: 'authenticate', plan: decision.plan },
+          agent.signal,
+        );
+        return result.status === 'authenticated';
+      },
+    },
+    reason: decision.reason,
+  };
+}

package/src/imprint/llm.ts

@@ -1192,7 +1192,7 @@ function createProvider(name: ProviderName, opts: LLMOptions = {}): LLMProvider
       return new ClaudeCliProvider({ model });
     case 'codex-cli':
       return new CodexCliProvider({
-        model: opts.model ?? process.env.CODEX_MODEL ?? 'gpt-6-sol',
+        model: opts.model ?? process.env.CODEX_MODEL ?? 'gpt-6.1-sol',
       });
     case 'cursor-cli':
       return new CursorCliProvider({ model: opts.model });
@@ -1275,7 +1275,7 @@ export function preferredAgentModel(provider: ProviderName): string {
     case 'claude-cli':
       return 'claude-opus-4-8';
     case 'codex-cli':
-      return 'gpt-6-sol';
+      return 'gpt-6.1-sol';
     case 'cursor-cli':
       return 'claude-opus-4-8'; // best-effort; cursor passes through
   }
@@ -1321,7 +1321,8 @@ export function availableModelsForProvider(provider: ProviderName): ModelOption[
       ];
     case 'codex-cli':
       return [
-        { model: 'gpt-6-sol', isDefault: true },
+        { model: 'gpt-6.1-sol', isDefault: true },
+        { model: 'gpt-6-sol', isDefault: false },
         { model: 'gpt-5.6-sol', isDefault: false },
         { model: 'gpt-5.6-terra', isDefault: false },
         { model: 'gpt-5.6-luna', isDefault: false },

package/src/imprint/log.ts

@@ -15,11 +15,26 @@ type Log = (msg: string) => void;
 
 const isQuiet = (): boolean => process.env.IMPRINT_QUIET === '1';
 export const isDebug = (): boolean => process.env.IMPRINT_DEBUG === '1';
+let promptDepth = 0;
+const pendingLines: string[] = [];
+
+/** Keep parallel-agent progress from overwriting an active terminal question. */
+export function pauseLogsForPrompt(): () => void {
+  promptDepth += 1;
+  return () => {
+    promptDepth -= 1;
+    if (promptDepth === 0) {
+      for (const line of pendingLines.splice(0)) process.stderr.write(line);
+    }
+  };
+}
 
 export function createLog(area: string): Log {
   const prefix = `[imprint ${area}]`;
   return (msg: string): void => {
     if (isQuiet()) return;
-    process.stderr.write(`${prefix} ${msg}\n`);
+    const line = `${prefix} ${msg}\n`;
+    if (promptDepth > 0) pendingLines.push(line);
+    else process.stderr.write(line);
   };
 }

package/src/imprint/login.ts

@@ -198,6 +198,15 @@ function collectSessionCaptures(site: string): SessionCaptureBinding[] {
           }
         }
       }
+      const lastStep = action.steps.at(-1);
+      const request = lastStep && workflow.requests[lastStep.request];
+      if (request) {
+        for (const { when } of action.branches ?? []) {
+          for (const credentialName of persistedByCapture.get(when.name) ?? []) {
+            addCapture(credentialName, when, request);
+          }
+        }
+      }
     }
   }
   return captures;

package/src/imprint/master-teach-agent-contracts.ts

@@ -2,6 +2,7 @@
 import { z } from 'zod';
 import type { BackendAttemptFact } from './backend-ladder.ts';
 import type { BodyComparison } from './body-structure.ts';
+import type { CredentialObservation, DispatchObservation } from './credential-observation.ts';
 import {
   ChainEdgeSchema,
   ConcreteTeachingParameterSchema,
@@ -113,10 +114,25 @@ export const FocusedPlannerInputSchema = strictObject({
   siblingToolEvidence: z.array(SiblingToolEvidenceSchema),
   incomingChainEdges: z.array(ChainEdgeSchema),
   outgoingChainEdges: z.array(ChainEdgeSchema),
-  /** Completed request research for every selected operation. Planning runs
-   * only after these handoffs exist so cross-tool dependencies can be chosen
-   * from tested calls and response shapes rather than guesses. */
+  /** Exact research for this tool and its declared dependencies. Other
+   * completed operations remain discoverable through apiResearchIndex. */
   apiResearch: z.array(z.lazy(() => ApiResearchHandoffSchema)).default([]),
+  apiResearchIndex: z
+    .array(
+      strictObject({
+        toolName: SemanticToolCandidateSchema.shape.toolName,
+        researchInputsSha256: PromptShaSchema,
+        status: z.enum(['proven', 'partial', 'blocked']),
+        summary: utf8Text(1, 2_000),
+        observationId: PromptIdSchema.optional(),
+        executionMechanism: utf8Text(1, 128).optional(),
+        resultOk: z.boolean().optional(),
+        /** Read the exact handoff through run-local shared research only
+         * when its details matter to a proposed dependency or boundary. */
+        handoffRef: ContentAddressedRefSchema.optional(),
+      }),
+    )
+    .default([]),
   evidence: PromptEvidenceProjectionSchema,
   /** Optional input-only handoff from the immediately preceding failed
    * attempt. The planner never echoes this object. */
@@ -141,6 +157,26 @@ export const ApiResearchCandidateSchema = strictObject({
     .optional(),
 });
 export type ApiResearchCandidate = z.infer<typeof ApiResearchCandidateSchema>;
+// Runtime diagnostics cross the same retained research/input/handoff boundary.
+// Keep their typed wire shape aligned without interpreting credential validity.
+const CredentialObservationSchema: z.ZodType<CredentialObservation> = strictObject({
+  scope: z.string(),
+  revision: z.string(),
+  source: z.string(),
+  cookieCount: z.number().int().nonnegative(),
+  valueCount: z.number().int().nonnegative(),
+  storageCount: z.number().int().nonnegative(),
+});
+const DispatchObservationSchema: z.ZodType<DispatchObservation> = strictObject({
+  invocationId: z.string(),
+  requestIndex: z.number().int().nonnegative(),
+  credentials: CredentialObservationSchema,
+  effectiveCredentials: CredentialObservationSchema.optional(),
+  preparedRequestIdentity: z.string(),
+  requestTargetIdentity: z.string(),
+  preparedCookieHeaderIdentity: z.string().optional(),
+  cookieSource: z.enum(['browser-owned', 'runtime-prepared']),
+});
 const BackendResponseObservationSchema = strictObject({
   backend: z.enum(['fetch', 'fetch-bootstrap', 'cdp-replay', 'stealth-fetch', 'playbook']),
   requestIndex: z.number().int().nonnegative(),
@@ -151,6 +187,7 @@ const BackendResponseObservationSchema = strictObject({
   valueType: z.enum(['null', 'array', 'object', 'string', 'number', 'boolean']),
   topLevelKeys: z.array(utf8Text(0, 200)).max(32).optional(),
   arrayLength: z.number().int().nonnegative().optional(),
+  dispatch: DispatchObservationSchema.optional(),
 });
 const PreparedRequestComparisonSchema = strictObject({
   backend: z.enum(['fetch', 'fetch-bootstrap', 'cdp-replay', 'stealth-fetch', 'playbook']),