yzcode-cli 1.0.0

package/utils/sandbox/sandbox-ui-utils.ts

@@ -0,0 +1,12 @@
+/**
+ * UI utilities for sandbox violations
+ * These utilities are used for displaying sandbox-related information in the UI
+ */
+
+/**
+ * Remove <sandbox_violations> tags from text
+ * Used to clean up error messages for display purposes
+ */
+export function removeSandboxViolationTags(text: string): string {
+  return text.replace(/<sandbox_violations>[\s\S]*?<\/sandbox_violations>/g, '')
+}

package/utils/sanitization.ts

@@ -0,0 +1,91 @@
+/**
+ * Unicode Sanitization for Hidden Character Attack Mitigation
+ *
+ * This module implements security measures against Unicode-based hidden character attacks,
+ * specifically targeting ASCII Smuggling and Hidden Prompt Injection vulnerabilities.
+ * These attacks use invisible Unicode characters (such as Tag characters, format controls,
+ * private use areas, and noncharacters) to hide malicious instructions that are invisible
+ * to users but processed by AI models.
+ *
+ * The vulnerability was demonstrated in HackerOne report #3086545 targeting Claude Desktop's
+ * MCP (Model Context Protocol) implementation, where attackers could inject hidden instructions
+ * using Unicode Tag characters that would be executed by Claude but remain invisible to users.
+ *
+ * Reference: https://embracethered.com/blog/posts/2024/hiding-and-finding-text-with-unicode-tags/
+ *
+ * This implementation provides comprehensive protection by:
+ * 1. Applying NFKC Unicode normalization to handle composed character sequences
+ * 2. Removing dangerous Unicode categories while preserving legitimate text and formatting
+ * 3. Supporting recursive sanitization of complex nested data structures
+ * 4. Maintaining performance with efficient regex processing
+ *
+ * The sanitization is always enabled to protect against these attacks.
+ */
+
+export function partiallySanitizeUnicode(prompt: string): string {
+  let current = prompt
+  let previous = ''
+  let iterations = 0
+  const MAX_ITERATIONS = 10 // Safety limit to prevent infinite loops
+
+  // Iteratively sanitize until no more changes occur or max iterations reached
+  while (current !== previous && iterations < MAX_ITERATIONS) {
+    previous = current
+
+    // Apply NFKC normalization to handle composed character sequences
+    current = current.normalize('NFKC')
+
+    // Remove dangerous Unicode categories using explicit character ranges
+
+    // Method 1: Strip dangerous Unicode property classes
+    // This is the primary defence and is the solution that is widely used in OSS libraries.
+    current = current.replace(/[\p{Cf}\p{Co}\p{Cn}]/gu, '')
+
+    // Method 2: Explicit character ranges. There are some subtle issues with the above method
+    // failing in certain environments that don't support regexes for unicode property classes,
+    // so we also implement a fallback that strips out some specifically known dangerous ranges.
+    current = current
+      .replace(/[\u200B-\u200F]/g, '') // Zero-width spaces, LTR/RTL marks
+      .replace(/[\u202A-\u202E]/g, '') // Directional formatting characters
+      .replace(/[\u2066-\u2069]/g, '') // Directional isolates
+      .replace(/[\uFEFF]/g, '') // Byte order mark
+      .replace(/[\uE000-\uF8FF]/g, '') // Basic Multilingual Plane private use
+
+    iterations++
+  }
+
+  // If we hit max iterations, crash loudly. This should only ever happen if there is a bug or if someone purposefully created a deeply nested unicode string.
+  if (iterations >= MAX_ITERATIONS) {
+    throw new Error(
+      `Unicode sanitization reached maximum iterations (${MAX_ITERATIONS}) for input: ${prompt.slice(0, 100)}`,
+    )
+  }
+
+  return current
+}
+
+export function recursivelySanitizeUnicode(value: string): string
+export function recursivelySanitizeUnicode<T>(value: T[]): T[]
+export function recursivelySanitizeUnicode<T extends object>(value: T): T
+export function recursivelySanitizeUnicode<T>(value: T): T
+export function recursivelySanitizeUnicode(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return partiallySanitizeUnicode(value)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(recursivelySanitizeUnicode)
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const sanitized: Record<string, unknown> = {}
+    for (const [key, val] of Object.entries(value)) {
+      sanitized[recursivelySanitizeUnicode(key)] =
+        recursivelySanitizeUnicode(val)
+    }
+    return sanitized
+  }
+
+  // Return other primitive values (numbers, booleans, null, undefined) unchanged
+  return value
+}

package/utils/screenshotClipboard.ts

@@ -0,0 +1,121 @@
+import { mkdir, unlink, writeFile } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { type AnsiToPngOptions, ansiToPng } from './ansiToPng.js'
+import { execFileNoThrowWithCwd } from './execFileNoThrow.js'
+import { logError } from './log.js'
+import { getPlatform } from './platform.js'
+
+/**
+ * Copies an image (from ANSI text) to the system clipboard.
+ * Supports macOS, Linux (with xclip/xsel), and Windows.
+ *
+ * Pure-TS pipeline: ANSI text → bitmap-font render → PNG encode. No WASM,
+ * no system fonts, so this works in every build (native and JS).
+ */
+export async function copyAnsiToClipboard(
+  ansiText: string,
+  options?: AnsiToPngOptions,
+): Promise<{ success: boolean; message: string }> {
+  try {
+    const tempDir = join(tmpdir(), 'claude-code-screenshots')
+    await mkdir(tempDir, { recursive: true })
+
+    const pngPath = join(tempDir, `screenshot-${Date.now()}.png`)
+    const pngBuffer = ansiToPng(ansiText, options)
+    await writeFile(pngPath, pngBuffer)
+
+    const result = await copyPngToClipboard(pngPath)
+
+    try {
+      await unlink(pngPath)
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    return result
+  } catch (error) {
+    logError(error)
+    return {
+      success: false,
+      message: `Failed to copy screenshot: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    }
+  }
+}
+
+async function copyPngToClipboard(
+  pngPath: string,
+): Promise<{ success: boolean; message: string }> {
+  const platform = getPlatform()
+
+  if (platform === 'macos') {
+    // macOS: Use osascript to copy PNG to clipboard
+    // Escape backslashes and double quotes for AppleScript string
+    const escapedPath = pngPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+    const script = `set the clipboard to (read (POSIX file "${escapedPath}") as «class PNGf»)`
+    const result = await execFileNoThrowWithCwd('osascript', ['-e', script], {
+      timeout: 5000,
+    })
+
+    if (result.code === 0) {
+      return { success: true, message: 'Screenshot copied to clipboard' }
+    }
+    return {
+      success: false,
+      message: `Failed to copy to clipboard: ${result.stderr}`,
+    }
+  }
+
+  if (platform === 'linux') {
+    // Linux: Try xclip first, then xsel
+    const xclipResult = await execFileNoThrowWithCwd(
+      'xclip',
+      ['-selection', 'clipboard', '-t', 'image/png', '-i', pngPath],
+      { timeout: 5000 },
+    )
+
+    if (xclipResult.code === 0) {
+      return { success: true, message: 'Screenshot copied to clipboard' }
+    }
+
+    // Try xsel as fallback
+    const xselResult = await execFileNoThrowWithCwd(
+      'xsel',
+      ['--clipboard', '--input', '--type', 'image/png'],
+      { timeout: 5000 },
+    )
+
+    if (xselResult.code === 0) {
+      return { success: true, message: 'Screenshot copied to clipboard' }
+    }
+
+    return {
+      success: false,
+      message:
+        'Failed to copy to clipboard. Please install xclip or xsel: sudo apt install xclip',
+    }
+  }
+
+  if (platform === 'windows') {
+    // Windows: Use PowerShell to copy image to clipboard
+    const psScript = `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::SetImage([System.Drawing.Image]::FromFile('${pngPath.replace(/'/g, "''")}'))`
+    const result = await execFileNoThrowWithCwd(
+      'powershell',
+      ['-NoProfile', '-Command', psScript],
+      { timeout: 5000 },
+    )
+
+    if (result.code === 0) {
+      return { success: true, message: 'Screenshot copied to clipboard' }
+    }
+    return {
+      success: false,
+      message: `Failed to copy to clipboard: ${result.stderr}`,
+    }
+  }
+
+  return {
+    success: false,
+    message: `Screenshot to clipboard is not supported on ${platform}`,
+  }
+}

package/utils/sdkEventQueue.ts

@@ -0,0 +1,134 @@
+import type { UUID } from 'crypto'
+import { randomUUID } from 'crypto'
+import { getIsNonInteractiveSession, getSessionId } from '../bootstrap/state.js'
+import type { SdkWorkflowProgress } from '../types/tools.js'
+
+type TaskStartedEvent = {
+  type: 'system'
+  subtype: 'task_started'
+  task_id: string
+  tool_use_id?: string
+  description: string
+  task_type?: string
+  workflow_name?: string
+  prompt?: string
+}
+
+type TaskProgressEvent = {
+  type: 'system'
+  subtype: 'task_progress'
+  task_id: string
+  tool_use_id?: string
+  description: string
+  usage: {
+    total_tokens: number
+    tool_uses: number
+    duration_ms: number
+  }
+  last_tool_name?: string
+  summary?: string
+  // Delta batch of workflow state changes. Clients upsert by
+  // `${type}:${index}` then group by phaseIndex to rebuild the phase tree,
+  // same fold as collectFromEvents + groupByPhase in PhaseProgress.tsx.
+  workflow_progress?: SdkWorkflowProgress[]
+}
+
+// Emitted when a foreground agent completes without being backgrounded.
+// Drained by drainSdkEvents() directly into the output stream — does NOT
+// go through the print.ts XML task_notification parser and does NOT trigger
+// the LLM loop. Consumers (e.g. VS Code session.ts) use this to remove the
+// task from the subagent panel.
+type TaskNotificationSdkEvent = {
+  type: 'system'
+  subtype: 'task_notification'
+  task_id: string
+  tool_use_id?: string
+  status: 'completed' | 'failed' | 'stopped'
+  output_file: string
+  summary: string
+  usage?: {
+    total_tokens: number
+    tool_uses: number
+    duration_ms: number
+  }
+}
+
+// Mirrors notifySessionStateChanged. The CCR bridge already receives this
+// via its own listener; SDK consumers (scmuxd, VS Code) need the same signal
+// to know when the main turn's generator is idle vs actively producing.
+// The 'idle' transition fires AFTER heldBackResult flushes and the bg-agent
+// do-while loop exits — so SDK consumers can trust it as the authoritative
+// "turn is over" signal even when result was withheld for background agents.
+type SessionStateChangedEvent = {
+  type: 'system'
+  subtype: 'session_state_changed'
+  state: 'idle' | 'running' | 'requires_action'
+}
+
+export type SdkEvent =
+  | TaskStartedEvent
+  | TaskProgressEvent
+  | TaskNotificationSdkEvent
+  | SessionStateChangedEvent
+
+const MAX_QUEUE_SIZE = 1000
+const queue: SdkEvent[] = []
+
+export function enqueueSdkEvent(event: SdkEvent): void {
+  // SDK events are only consumed (drained) in headless/streaming mode.
+  // In TUI mode they would accumulate up to the cap and never be read.
+  if (!getIsNonInteractiveSession()) {
+    return
+  }
+  if (queue.length >= MAX_QUEUE_SIZE) {
+    queue.shift()
+  }
+  queue.push(event)
+}
+
+export function drainSdkEvents(): Array<
+  SdkEvent & { uuid: UUID; session_id: string }
+> {
+  if (queue.length === 0) {
+    return []
+  }
+  const events = queue.splice(0)
+  return events.map(e => ({
+    ...e,
+    uuid: randomUUID(),
+    session_id: getSessionId(),
+  }))
+}
+
+/**
+ * Emit a task_notification SDK event for a task reaching a terminal state.
+ *
+ * registerTask() always emits task_started; this is the closing bookend.
+ * Call this from any exit path that sets a task terminal WITHOUT going
+ * through enqueuePendingNotification-with-<task-id> (print.ts parses that
+ * XML into the same SDK event, so paths that do both would double-emit).
+ * Paths that suppress the XML notification (notified:true pre-set, kill
+ * paths, abort branches) must call this directly so SDK consumers
+ * (Scuttle's bg-task dot, VS Code subagent panel) see the task close.
+ */
+export function emitTaskTerminatedSdk(
+  taskId: string,
+  status: 'completed' | 'failed' | 'stopped',
+  opts?: {
+    toolUseId?: string
+    summary?: string
+    outputFile?: string
+    usage?: { total_tokens: number; tool_uses: number; duration_ms: number }
+  },
+): void {
+  enqueueSdkEvent({
+    type: 'system',
+    subtype: 'task_notification',
+    task_id: taskId,
+    tool_use_id: opts?.toolUseId,
+    status,
+    output_file: opts?.outputFile ?? '',
+    summary: opts?.summary ?? '',
+    usage: opts?.usage,
+  })
+}

package/utils/secureStorage/fallbackStorage.ts

@@ -0,0 +1,70 @@
+import type { SecureStorage, SecureStorageData } from './types.js'
+
+/**
+ * Creates a fallback storage that tries to use the primary storage first,
+ * and if that fails, falls back to the secondary storage
+ */
+export function createFallbackStorage(
+  primary: SecureStorage,
+  secondary: SecureStorage,
+): SecureStorage {
+  return {
+    name: `${primary.name}-with-${secondary.name}-fallback`,
+    read(): SecureStorageData {
+      const result = primary.read()
+      if (result !== null && result !== undefined) {
+        return result
+      }
+      return secondary.read() || {}
+    },
+    async readAsync(): Promise<SecureStorageData | null> {
+      const result = await primary.readAsync()
+      if (result !== null && result !== undefined) {
+        return result
+      }
+      return (await secondary.readAsync()) || {}
+    },
+    update(data: SecureStorageData): { success: boolean; warning?: string } {
+      // Capture state before update
+      const primaryDataBefore = primary.read()
+
+      const result = primary.update(data)
+
+      if (result.success) {
+        // Delete secondary when migrating to primary for the first time
+        // This preserves credentials when sharing .claude between host and containers
+        // See: https://github.com/anthropics/claude-code/issues/1414
+        if (primaryDataBefore === null) {
+          secondary.delete()
+        }
+        return result
+      }
+
+      const fallbackResult = secondary.update(data)
+
+      if (fallbackResult.success) {
+        // Primary write failed but primary may still hold an *older* valid
+        // entry. read() prefers primary whenever it returns non-null, so that
+        // stale entry would shadow the fresh data we just wrote to secondary —
+        // e.g. a refresh token the server has already rotated away, causing a
+        // /login loop (#30337). Best-effort delete; if this also fails the
+        // user's keychain is in a bad state we can't fix from here.
+        if (primaryDataBefore !== null) {
+          primary.delete()
+        }
+        return {
+          success: true,
+          warning: fallbackResult.warning,
+        }
+      }
+
+      return { success: false }
+    },
+    delete(): boolean {
+      const primarySuccess = primary.delete()
+      const secondarySuccess = secondary.delete()
+
+      return primarySuccess || secondarySuccess
+    },
+  }
+}

package/utils/secureStorage/index.ts

@@ -0,0 +1,17 @@
+import { createFallbackStorage } from './fallbackStorage.js'
+import { macOsKeychainStorage } from './macOsKeychainStorage.js'
+import { plainTextStorage } from './plainTextStorage.js'
+import type { SecureStorage } from './types.js'
+
+/**
+ * Get the appropriate secure storage implementation for the current platform
+ */
+export function getSecureStorage(): SecureStorage {
+  if (process.platform === 'darwin') {
+    return createFallbackStorage(macOsKeychainStorage, plainTextStorage)
+  }
+
+  // TODO: add libsecret support for Linux
+
+  return plainTextStorage
+}

package/utils/secureStorage/keychainPrefetch.ts

@@ -0,0 +1,116 @@
+/**
+ * Minimal module for firing macOS keychain reads in parallel with main.tsx
+ * module evaluation, same pattern as startMdmRawRead() in settings/mdm/rawRead.ts.
+ *
+ * isRemoteManagedSettingsEligible() reads two separate keychain entries
+ * SEQUENTIALLY via sync execSync during applySafeConfigEnvironmentVariables():
+ *   1. "Claude Code-credentials" (OAuth tokens)  — ~32ms
+ *   2. "Claude Code" (legacy API key)            — ~33ms
+ * Sequential cost: ~65ms on every macOS startup.
+ *
+ * Firing both here lets the subprocesses run in parallel with the ~65ms of
+ * main.tsx imports. ensureKeychainPrefetchCompleted() is awaited alongside
+ * ensureMdmSettingsLoaded() in main.tsx preAction — nearly free since the
+ * subprocesses finish during import evaluation. Sync read() and
+ * getApiKeyFromConfigOrMacOSKeychain() then hit their caches.
+ *
+ * Imports stay minimal: child_process + macOsKeychainHelpers.ts (NOT
+ * macOsKeychainStorage.ts — that pulls in execa → human-signals →
+ * cross-spawn, ~58ms of synchronous module init). The helpers file's own
+ * import chain (envUtils, oauth constants, crypto) is already evaluated by
+ * startupProfiler.ts at main.tsx:5, so no new module-init cost lands here.
+ */
+
+import { execFile } from 'child_process'
+import { isBareMode } from '../envUtils.js'
+import {
+  CREDENTIALS_SERVICE_SUFFIX,
+  getMacOsKeychainStorageServiceName,
+  getUsername,
+  primeKeychainCacheFromPrefetch,
+} from './macOsKeychainHelpers.js'
+
+const KEYCHAIN_PREFETCH_TIMEOUT_MS = 10_000
+
+// Shared with auth.ts getApiKeyFromConfigOrMacOSKeychain() so it can skip its
+// sync spawn when the prefetch already landed. Distinguishing "not started" (null)
+// from "completed with no key" ({ stdout: null }) lets the sync reader only
+// trust a completed prefetch.
+let legacyApiKeyPrefetch: { stdout: string | null } | null = null
+
+let prefetchPromise: Promise<void> | null = null
+
+type SpawnResult = { stdout: string | null; timedOut: boolean }
+
+function spawnSecurity(serviceName: string): Promise<SpawnResult> {
+  return new Promise(resolve => {
+    execFile(
+      'security',
+      ['find-generic-password', '-a', getUsername(), '-w', '-s', serviceName],
+      { encoding: 'utf-8', timeout: KEYCHAIN_PREFETCH_TIMEOUT_MS },
+      (err, stdout) => {
+        // Exit 44 (entry not found) is a valid "no key" result and safe to
+        // prime as null. But timeout (err.killed) means the keychain MAY have
+        // a key we couldn't fetch — don't prime, let sync spawn retry.
+        // biome-ignore lint/nursery/noFloatingPromises: resolve() is not a floating promise
+        resolve({
+          stdout: err ? null : stdout?.trim() || null,
+          timedOut: Boolean(err && 'killed' in err && err.killed),
+        })
+      },
+    )
+  })
+}
+
+/**
+ * Fire both keychain reads in parallel. Called at main.tsx top-level
+ * immediately after startMdmRawRead(). Non-darwin is a no-op.
+ */
+export function startKeychainPrefetch(): void {
+  if (process.platform !== 'darwin' || prefetchPromise || isBareMode()) return
+
+  // Fire both subprocesses immediately (non-blocking). They run in parallel
+  // with each other AND with main.tsx imports. The await in Promise.all
+  // happens later via ensureKeychainPrefetchCompleted().
+  const oauthSpawn = spawnSecurity(
+    getMacOsKeychainStorageServiceName(CREDENTIALS_SERVICE_SUFFIX),
+  )
+  const legacySpawn = spawnSecurity(getMacOsKeychainStorageServiceName())
+
+  prefetchPromise = Promise.all([oauthSpawn, legacySpawn]).then(
+    ([oauth, legacy]) => {
+      // Timed-out prefetch: don't prime. Sync read/spawn will retry with its
+      // own (longer) timeout. Priming null here would shadow a key that the
+      // sync path might successfully fetch.
+      if (!oauth.timedOut) primeKeychainCacheFromPrefetch(oauth.stdout)
+      if (!legacy.timedOut) legacyApiKeyPrefetch = { stdout: legacy.stdout }
+    },
+  )
+}
+
+/**
+ * Await prefetch completion. Called in main.tsx preAction alongside
+ * ensureMdmSettingsLoaded() — nearly free since subprocesses finish during
+ * the ~65ms of main.tsx imports. Resolves immediately on non-darwin.
+ */
+export async function ensureKeychainPrefetchCompleted(): Promise<void> {
+  if (prefetchPromise) await prefetchPromise
+}
+
+/**
+ * Consumed by getApiKeyFromConfigOrMacOSKeychain() in auth.ts before it
+ * falls through to sync execSync. Returns null if prefetch hasn't completed.
+ */
+export function getLegacyApiKeyPrefetchResult(): {
+  stdout: string | null
+} | null {
+  return legacyApiKeyPrefetch
+}
+
+/**
+ * Clear prefetch result. Called alongside getApiKeyFromConfigOrMacOSKeychain
+ * cache invalidation so a stale prefetch doesn't shadow a fresh write.
+ */
+export function clearLegacyApiKeyPrefetch(): void {
+  legacyApiKeyPrefetch = null
+}

package/utils/secureStorage/macOsKeychainHelpers.ts

@@ -0,0 +1,111 @@
+/**
+ * Lightweight helpers shared between keychainPrefetch.ts and
+ * macOsKeychainStorage.ts.
+ *
+ * This module MUST NOT import execa, execFileNoThrow, or
+ * execFileNoThrowPortable. keychainPrefetch.ts fires at the very top of
+ * main.tsx (before the ~65ms of module evaluation it parallelizes), and Bun's
+ * __esm wrapper evaluates the ENTIRE module when any symbol is accessed —
+ * so a heavy transitive import here defeats the prefetch. The execa →
+ * human-signals → cross-spawn chain alone is ~58ms of synchronous init.
+ *
+ * The imports below (envUtils, oauth constants, crypto, os) are already
+ * evaluated by startupProfiler.ts at main.tsx:5, so they add no module-init
+ * cost when keychainPrefetch.ts pulls this file in.
+ */
+
+import { createHash } from 'crypto'
+import { userInfo } from 'os'
+import { getOauthConfig } from 'src/constants/oauth.js'
+import { getClaudeConfigHomeDir } from '../envUtils.js'
+import type { SecureStorageData } from './types.js'
+
+// Suffix distinguishing the OAuth credentials keychain entry from the legacy
+// API key entry (which uses no suffix). Both share the service name base.
+// DO NOT change this value — it's part of the keychain lookup key and would
+// orphan existing stored credentials.
+export const CREDENTIALS_SERVICE_SUFFIX = '-credentials'
+
+export function getMacOsKeychainStorageServiceName(
+  serviceSuffix: string = '',
+): string {
+  const configDir = getClaudeConfigHomeDir()
+  const isDefaultDir = !process.env.CLAUDE_CONFIG_DIR
+
+  // Use a hash of the config dir path to create a unique but stable suffix
+  // Only add suffix for non-default directories to maintain backwards compatibility
+  const dirHash = isDefaultDir
+    ? ''
+    : `-${createHash('sha256').update(configDir).digest('hex').substring(0, 8)}`
+  return `Claude Code${getOauthConfig().OAUTH_FILE_SUFFIX}${serviceSuffix}${dirHash}`
+}
+
+export function getUsername(): string {
+  try {
+    return process.env.USER || userInfo().username
+  } catch {
+    return 'claude-code-user'
+  }
+}
+
+// --
+
+// Cache for keychain reads to avoid repeated expensive security CLI calls.
+// TTL bounds staleness for cross-process scenarios (another CC instance
+// refreshing/invalidating tokens) without forcing a blocking spawnSync on
+// every read. In-process writes invalidate via clearKeychainCache() directly.
+//
+// The sync read() path takes ~500ms per `security` spawn. With 50+ claude.ai
+// MCP connectors authenticating at startup, a short TTL expires mid-storm and
+// triggers repeat sync reads — observed as a 5.5s event-loop stall
+// (go/ccshare/adamj-20260326-212235). 30s of cross-process staleness is fine:
+// OAuth tokens expire in hours, and the only cross-process writer is another
+// CC instance's /login or refresh.
+//
+// Lives here (not in macOsKeychainStorage.ts) so keychainPrefetch.ts can
+// prime it without pulling in execa. Wrapped in an object because ES module
+// `let` bindings aren't writable across module boundaries — both this file
+// and macOsKeychainStorage.ts need to mutate all three fields.
+export const KEYCHAIN_CACHE_TTL_MS = 30_000
+
+export const keychainCacheState: {
+  cache: { data: SecureStorageData | null; cachedAt: number } // cachedAt 0 = invalid
+  // Incremented on every cache invalidation. readAsync() captures this before
+  // spawning and skips its cache write if a newer generation exists, preventing
+  // a stale subprocess result from overwriting fresh data written by update().
+  generation: number
+  // Deduplicates concurrent readAsync() calls so TTL expiry under load spawns
+  // one subprocess, not N. Cleared on invalidation so fresh reads don't join
+  // a stale in-flight promise.
+  readInFlight: Promise<SecureStorageData | null> | null
+} = {
+  cache: { data: null, cachedAt: 0 },
+  generation: 0,
+  readInFlight: null,
+}
+
+export function clearKeychainCache(): void {
+  keychainCacheState.cache = { data: null, cachedAt: 0 }
+  keychainCacheState.generation++
+  keychainCacheState.readInFlight = null
+}
+
+/**
+ * Prime the keychain cache from a prefetch result (keychainPrefetch.ts).
+ * Only writes if the cache hasn't been touched yet — if sync read() or
+ * update() already ran, their result is authoritative and we discard this.
+ */
+export function primeKeychainCacheFromPrefetch(stdout: string | null): void {
+  if (keychainCacheState.cache.cachedAt !== 0) return
+  let data: SecureStorageData | null = null
+  if (stdout) {
+    try {
+      // eslint-disable-next-line custom-rules/no-direct-json-operations -- jsonParse() pulls slowOperations (lodash-es/cloneDeep) into the early-startup import chain; see file header
+      data = JSON.parse(stdout)
+    } catch {
+      // malformed prefetch result — let sync read() re-fetch
+      return
+    }
+  }
+  keychainCacheState.cache = { data, cachedAt: Date.now() }
+}