subagent-cli 0.3.0 → 0.3.1

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

@@ -1,12 +0,0 @@
-/**
- * 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/src/utils/sanitization.ts

@@ -1,91 +0,0 @@
-/**
- * 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/src/utils/screenshotClipboard.ts

@@ -1,121 +0,0 @@
-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/src/utils/sdkEventQueue.ts

@@ -1,134 +0,0 @@
-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/src/utils/sdkHeapDumpMonitor.ts

@@ -1,2 +0,0 @@
-// Auto-generated stub
-export {}

package/src/utils/secureStorage/fallbackStorage.ts

@@ -1,70 +0,0 @@
-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/src/utils/secureStorage/index.ts

@@ -1,17 +0,0 @@
-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/src/utils/secureStorage/keychainPrefetch.ts

@@ -1,116 +0,0 @@
-/**
- * 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/src/utils/secureStorage/macOsKeychainHelpers.ts

@@ -1,111 +0,0 @@
-/**
- * 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() }
-}