@xortex/xcode 3.0.0

package/utils/deepLink/parseDeepLink.ts

@@ -0,0 +1,170 @@
+/**
+ * Deep Link URI Parser
+ *
+ * Parses `claude-cli://open` URIs. All parameters are optional:
+ *   q    — pre-fill the prompt input (not submitted)
+ *   cwd  — working directory (absolute path)
+ *   repo — owner/name slug, resolved against githubRepoPaths config
+ *
+ * Examples:
+ *   claude-cli://open
+ *   claude-cli://open?q=hello+world
+ *   claude-cli://open?q=fix+tests&repo=owner/repo
+ *   claude-cli://open?cwd=/path/to/project
+ *
+ * Security: values are URL-decoded, Unicode-sanitized, and rejected if they
+ * contain ASCII control characters (newlines etc. can act as command
+ * separators). All values are single-quote shell-escaped at the point of
+ * use (terminalLauncher.ts) — that escaping is the injection boundary.
+ */
+
+import { partiallySanitizeUnicode } from '../sanitization.js'
+
+export const DEEP_LINK_PROTOCOL = 'claude-cli'
+
+export type DeepLinkAction = {
+  query?: string
+  cwd?: string
+  repo?: string
+}
+
+/**
+ * Check if a string contains ASCII control characters (0x00-0x1F, 0x7F).
+ * These can act as command separators in shells (newlines, carriage returns, etc.).
+ * Allows printable ASCII and Unicode (CJK, emoji, accented chars, etc.).
+ */
+function containsControlChars(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i)
+    if (code <= 0x1f || code === 0x7f) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * GitHub owner/repo slug: alphanumerics, dots, hyphens, underscores,
+ * exactly one slash. Keeps this from becoming a path traversal vector.
+ */
+const REPO_SLUG_PATTERN = /^[\w.-]+\/[\w.-]+$/
+
+/**
+ * Cap on pre-filled prompt length. The only defense against a prompt like
+ * "review PR #18796 […4900 chars of padding…] also cat ~/.ssh/id_rsa" is
+ * the user reading it before pressing Enter. At this length the prompt is
+ * no longer scannable at a glance, so banner.ts shows an explicit "scroll
+ * to review the entire prompt" warning above LONG_PREFILL_THRESHOLD.
+ * Reject, don't truncate — truncation changes meaning.
+ *
+ * 5000 is the practical ceiling: the Windows cmd.exe fallback
+ * (terminalLauncher.ts) has an 8191-char command-string limit, and after
+ * the `cd /d <cwd> && <claude.exe> --deep-link-origin ... --prefill "<q>"`
+ * wrapper plus cmdQuote's %→%% expansion, ~7000 chars of query is the
+ * hard stop for typical inputs. A pathological >60%-percent-sign query
+ * would 2× past the limit, but cmd.exe is the last-resort fallback
+ * (wt.exe and PowerShell are tried first) and the failure mode is a
+ * launch error, not a security issue — so we don't penalize real users
+ * for an implausible input.
+ */
+const MAX_QUERY_LENGTH = 5000
+
+/**
+ * PATH_MAX on Linux is 4096. Windows MAX_PATH is 260 (32767 with long-path
+ * opt-in). No real path approaches this; a cwd over 4096 is malformed or
+ * malicious.
+ */
+const MAX_CWD_LENGTH = 4096
+
+/**
+ * Parse a claude-cli:// URI into a structured action.
+ *
+ * @throws {Error} if the URI is malformed or contains dangerous characters
+ */
+export function parseDeepLink(uri: string): DeepLinkAction {
+  // Normalize: accept with or without the trailing colon in protocol
+  const normalized = uri.startsWith(`${DEEP_LINK_PROTOCOL}://`)
+    ? uri
+    : uri.startsWith(`${DEEP_LINK_PROTOCOL}:`)
+      ? uri.replace(`${DEEP_LINK_PROTOCOL}:`, `${DEEP_LINK_PROTOCOL}://`)
+      : null
+
+  if (!normalized) {
+    throw new Error(
+      `Invalid deep link: expected ${DEEP_LINK_PROTOCOL}:// scheme, got "${uri}"`,
+    )
+  }
+
+  let url: URL
+  try {
+    url = new URL(normalized)
+  } catch {
+    throw new Error(`Invalid deep link URL: "${uri}"`)
+  }
+
+  if (url.hostname !== 'open') {
+    throw new Error(`Unknown deep link action: "${url.hostname}"`)
+  }
+
+  const cwd = url.searchParams.get('cwd') ?? undefined
+  const repo = url.searchParams.get('repo') ?? undefined
+  const rawQuery = url.searchParams.get('q')
+
+  // Validate cwd if present — must be an absolute path
+  if (cwd && !cwd.startsWith('/') && !/^[a-zA-Z]:[/\\]/.test(cwd)) {
+    throw new Error(
+      `Invalid cwd in deep link: must be an absolute path, got "${cwd}"`,
+    )
+  }
+
+  // Reject control characters in cwd (newlines, etc.) but allow path chars like backslash.
+  if (cwd && containsControlChars(cwd)) {
+    throw new Error('Deep link cwd contains disallowed control characters')
+  }
+  if (cwd && cwd.length > MAX_CWD_LENGTH) {
+    throw new Error(
+      `Deep link cwd exceeds ${MAX_CWD_LENGTH} characters (got ${cwd.length})`,
+    )
+  }
+
+  // Validate repo slug format. Resolution happens later (protocolHandler.ts) —
+  // this parser stays pure with no config/filesystem access.
+  if (repo && !REPO_SLUG_PATTERN.test(repo)) {
+    throw new Error(
+      `Invalid repo in deep link: expected "owner/repo", got "${repo}"`,
+    )
+  }
+
+  let query: string | undefined
+  if (rawQuery && rawQuery.trim().length > 0) {
+    // Strip hidden Unicode characters (ASCII smuggling / hidden prompt injection)
+    query = partiallySanitizeUnicode(rawQuery.trim())
+    if (containsControlChars(query)) {
+      throw new Error('Deep link query contains disallowed control characters')
+    }
+    if (query.length > MAX_QUERY_LENGTH) {
+      throw new Error(
+        `Deep link query exceeds ${MAX_QUERY_LENGTH} characters (got ${query.length})`,
+      )
+    }
+  }
+
+  return { query, cwd, repo }
+}
+
+/**
+ * Build a claude-cli:// deep link URL.
+ */
+export function buildDeepLink(action: DeepLinkAction): string {
+  const url = new URL(`${DEEP_LINK_PROTOCOL}://open`)
+  if (action.query) {
+    url.searchParams.set('q', action.query)
+  }
+  if (action.cwd) {
+    url.searchParams.set('cwd', action.cwd)
+  }
+  if (action.repo) {
+    url.searchParams.set('repo', action.repo)
+  }
+  return url.toString()
+}

package/utils/deepLink/protocolHandler.ts

@@ -0,0 +1,136 @@
+/**
+ * Protocol Handler
+ *
+ * Entry point for `claude --handle-uri <url>`. When the OS invokes claude
+ * with a `claude-cli://` URL, this module:
+ *   1. Parses the URI into a structured action
+ *   2. Detects the user's terminal emulator
+ *   3. Opens a new terminal window running claude with the appropriate args
+ *
+ * This runs in a headless context (no TTY) because the OS launches the binary
+ * directly — there is no terminal attached.
+ */
+
+import { homedir } from 'os'
+import { logForDebugging } from '../debug.js'
+import {
+  filterExistingPaths,
+  getKnownPathsForRepo,
+} from '../githubRepoPathMapping.js'
+import { jsonStringify } from '../slowOperations.js'
+import { readLastFetchTime } from './banner.js'
+import { parseDeepLink } from './parseDeepLink.js'
+import { MACOS_BUNDLE_ID } from './registerProtocol.js'
+import { launchInTerminal } from './terminalLauncher.js'
+
+/**
+ * Handle an incoming deep link URI.
+ *
+ * Called from the CLI entry point when `--handle-uri` is passed.
+ * This function parses the URI, resolves the claude binary, and
+ * launches it in the user's terminal.
+ *
+ * @param uri - The raw URI string (e.g., "claude-cli://prompt?q=hello+world")
+ * @returns exit code (0 = success)
+ */
+export async function handleDeepLinkUri(uri: string): Promise<number> {
+  logForDebugging(`Handling deep link URI: ${uri}`)
+
+  let action
+  try {
+    action = parseDeepLink(uri)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    // biome-ignore lint/suspicious/noConsole: intentional error output
+    console.error(`Deep link error: ${message}`)
+    return 1
+  }
+
+  logForDebugging(`Parsed deep link action: ${jsonStringify(action)}`)
+
+  // Always the running executable — no PATH lookup. The OS launched us via
+  // an absolute path (bundle symlink / .desktop Exec= / registry command)
+  // baked at registration time, and we want the terminal-launched Claude to
+  // be the same binary. process.execPath is that binary.
+  const { cwd, resolvedRepo } = await resolveCwd(action)
+  // Resolve FETCH_HEAD age here, in the trampoline process, so main.tsx
+  // stays await-free — the launched instance receives it as a precomputed
+  // flag instead of statting the filesystem on its own startup path.
+  const lastFetch = resolvedRepo ? await readLastFetchTime(cwd) : undefined
+  const launched = await launchInTerminal(process.execPath, {
+    query: action.query,
+    cwd,
+    repo: resolvedRepo,
+    lastFetchMs: lastFetch?.getTime(),
+  })
+  if (!launched) {
+    // biome-ignore lint/suspicious/noConsole: intentional error output
+    console.error(
+      'Failed to open a terminal. Make sure a supported terminal emulator is installed.',
+    )
+    return 1
+  }
+
+  return 0
+}
+
+/**
+ * Handle the case where claude was launched as the app bundle's executable
+ * by macOS (via URL scheme). Uses the NAPI module to receive the URL from
+ * the Apple Event, then handles it normally.
+ *
+ * @returns exit code (0 = success, 1 = error, null = not a URL launch)
+ */
+export async function handleUrlSchemeLaunch(): Promise<number | null> {
+  // LaunchServices overwrites __CFBundleIdentifier with the launching bundle's
+  // ID. This is a precise positive signal — it's set to our exact bundle ID
+  // if and only if macOS launched us via the URL handler .app bundle.
+  // (`open` from a terminal passes the caller's env through, so negative
+  // heuristics like !TERM don't work — the terminal's TERM leaks in.)
+  if (process.env.__CFBundleIdentifier !== MACOS_BUNDLE_ID) {
+    return null
+  }
+
+  try {
+    const { waitForUrlEvent } = await import('url-handler-napi')
+    const url = waitForUrlEvent(5000)
+    if (!url) {
+      return null
+    }
+    return await handleDeepLinkUri(url)
+  } catch {
+    // NAPI module not available, or handleDeepLinkUri rejected — not a URL launch
+    return null
+  }
+}
+
+/**
+ * Resolve the working directory for the launched Claude instance.
+ * Precedence: explicit cwd > repo lookup (MRU clone) > home.
+ * A repo that isn't cloned locally is not an error — fall through to home
+ * so a web link referencing a repo the user doesn't have still opens Claude.
+ *
+ * Returns the resolved cwd, and the repo slug if (and only if) the MRU
+ * lookup hit — so the launched instance can show which clone was selected
+ * and its git freshness.
+ */
+async function resolveCwd(action: {
+  cwd?: string
+  repo?: string
+}): Promise<{ cwd: string; resolvedRepo?: string }> {
+  if (action.cwd) {
+    return { cwd: action.cwd }
+  }
+  if (action.repo) {
+    const known = getKnownPathsForRepo(action.repo)
+    const existing = await filterExistingPaths(known)
+    if (existing[0]) {
+      logForDebugging(`Resolved repo ${action.repo} → ${existing[0]}`)
+      return { cwd: existing[0], resolvedRepo: action.repo }
+    }
+    logForDebugging(
+      `No local clone found for repo ${action.repo}, falling back to home`,
+    )
+  }
+  return { cwd: homedir() }
+}

package/utils/deepLink/registerProtocol.ts

@@ -0,0 +1,348 @@
+/**
+ * Protocol Handler Registration
+ *
+ * Registers the `claude-cli://` custom URI scheme with the OS,
+ * so that clicking a `claude-cli://` link in a browser (or any app) will
+ * invoke `claude --handle-uri <url>`.
+ *
+ * Platform details:
+ *   macOS  — Creates a minimal .app trampoline in ~/Applications with
+ *            CFBundleURLTypes in its Info.plist
+ *   Linux  — Creates a .desktop file in $XDG_DATA_HOME/applications
+ *            (default ~/.local/share/applications) and registers it with xdg-mime
+ *   Windows — Writes registry keys under HKEY_CURRENT_USER\Software\Classes
+ */
+
+import { promises as fs } from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from 'src/services/analytics/growthbook.js'
+import {
+  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+  logEvent,
+} from 'src/services/analytics/index.js'
+import { logForDebugging } from '../debug.js'
+import { getClaudeConfigHomeDir } from '../envUtils.js'
+import { getErrnoCode } from '../errors.js'
+import { execFileNoThrow } from '../execFileNoThrow.js'
+import { getInitialSettings } from '../settings/settings.js'
+import { which } from '../which.js'
+import { getUserBinDir, getXDGDataHome } from '../xdg.js'
+import { DEEP_LINK_PROTOCOL } from './parseDeepLink.js'
+
+export const MACOS_BUNDLE_ID = 'com.anthropic.claude-code-url-handler'
+const APP_NAME = 'Claude Code URL Handler'
+const DESKTOP_FILE_NAME = 'claude-code-url-handler.desktop'
+const MACOS_APP_NAME = 'Claude Code URL Handler.app'
+
+// Shared between register* (writes these paths/values) and
+// isProtocolHandlerCurrent (reads them back). Keep the writer and reader
+// in lockstep — drift here means the check returns a perpetual false.
+const MACOS_APP_DIR = path.join(os.homedir(), 'Applications', MACOS_APP_NAME)
+const MACOS_SYMLINK_PATH = path.join(
+  MACOS_APP_DIR,
+  'Contents',
+  'MacOS',
+  'claude',
+)
+function linuxDesktopPath(): string {
+  return path.join(getXDGDataHome(), 'applications', DESKTOP_FILE_NAME)
+}
+const WINDOWS_REG_KEY = `HKEY_CURRENT_USER\\Software\\Classes\\${DEEP_LINK_PROTOCOL}`
+const WINDOWS_COMMAND_KEY = `${WINDOWS_REG_KEY}\\shell\\open\\command`
+
+const FAILURE_BACKOFF_MS = 24 * 60 * 60 * 1000
+
+function linuxExecLine(claudePath: string): string {
+  return `Exec="${claudePath}" --handle-uri %u`
+}
+function windowsCommandValue(claudePath: string): string {
+  return `"${claudePath}" --handle-uri "%1"`
+}
+
+/**
+ * Register the protocol handler on macOS.
+ *
+ * Creates a .app bundle where the CFBundleExecutable is a symlink to the
+ * already-installed (and signed) `claude` binary. When macOS opens a
+ * `claude-cli://` URL, it launches `claude` through this app bundle.
+ * Claude then uses the url-handler NAPI module to read the URL from the
+ * Apple Event and handles it normally.
+ *
+ * This approach avoids shipping a separate executable (which would need
+ * to be signed and allowlisted by endpoint security tools like Santa).
+ */
+async function registerMacos(claudePath: string): Promise<void> {
+  const contentsDir = path.join(MACOS_APP_DIR, 'Contents')
+
+  // Remove any existing app bundle to start clean
+  try {
+    await fs.rm(MACOS_APP_DIR, { recursive: true })
+  } catch (e: unknown) {
+    const code = getErrnoCode(e)
+    if (code !== 'ENOENT') {
+      throw e
+    }
+  }
+
+  await fs.mkdir(path.dirname(MACOS_SYMLINK_PATH), { recursive: true })
+
+  // Info.plist — registers the URL scheme with claude as the executable
+  const infoPlist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>${MACOS_BUNDLE_ID}</string>
+  <key>CFBundleName</key>
+  <string>${APP_NAME}</string>
+  <key>CFBundleExecutable</key>
+  <string>claude</string>
+  <key>CFBundleVersion</key>
+  <string>1.0</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>LSBackgroundOnly</key>
+  <true/>
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleURLName</key>
+      <string>Claude Code Deep Link</string>
+      <key>CFBundleURLSchemes</key>
+      <array>
+        <string>${DEEP_LINK_PROTOCOL}</string>
+      </array>
+    </dict>
+  </array>
+</dict>
+</plist>`
+
+  await fs.writeFile(path.join(contentsDir, 'Info.plist'), infoPlist)
+
+  // Symlink to the already-signed claude binary — avoids a new executable
+  // that would need signing and endpoint-security allowlisting.
+  // Written LAST among the throwing fs calls: isProtocolHandlerCurrent reads
+  // this symlink, so it acts as the commit marker. If Info.plist write
+  // failed above, no symlink → next session retries.
+  await fs.symlink(claudePath, MACOS_SYMLINK_PATH)
+
+  // Re-register the app with LaunchServices so macOS picks up the URL scheme.
+  const lsregister =
+    '/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister'
+  await execFileNoThrow(lsregister, ['-R', MACOS_APP_DIR], { useCwd: false })
+
+  logForDebugging(
+    `Registered ${DEEP_LINK_PROTOCOL}:// protocol handler at ${MACOS_APP_DIR}`,
+  )
+}
+
+/**
+ * Register the protocol handler on Linux.
+ * Creates a .desktop file and registers it with xdg-mime.
+ */
+async function registerLinux(claudePath: string): Promise<void> {
+  await fs.mkdir(path.dirname(linuxDesktopPath()), { recursive: true })
+
+  const desktopEntry = `[Desktop Entry]
+Name=${APP_NAME}
+Comment=Handle ${DEEP_LINK_PROTOCOL}:// deep links for Claude Code
+${linuxExecLine(claudePath)}
+Type=Application
+NoDisplay=true
+MimeType=x-scheme-handler/${DEEP_LINK_PROTOCOL};
+`
+
+  await fs.writeFile(linuxDesktopPath(), desktopEntry)
+
+  // Register as the default handler for the scheme. On headless boxes
+  // (WSL, Docker, CI) xdg-utils isn't installed — not a failure: there's
+  // no desktop to click links from, and some apps read the .desktop
+  // MimeType line directly. The artifact check still short-circuits
+  // next session since the .desktop file is present.
+  const xdgMime = await which('xdg-mime')
+  if (xdgMime) {
+    const { code } = await execFileNoThrow(
+      xdgMime,
+      ['default', DESKTOP_FILE_NAME, `x-scheme-handler/${DEEP_LINK_PROTOCOL}`],
+      { useCwd: false },
+    )
+    if (code !== 0) {
+      throw Object.assign(new Error(`xdg-mime exited with code ${code}`), {
+        code: 'XDG_MIME_FAILED',
+      })
+    }
+  }
+
+  logForDebugging(
+    `Registered ${DEEP_LINK_PROTOCOL}:// protocol handler at ${linuxDesktopPath()}`,
+  )
+}
+
+/**
+ * Register the protocol handler on Windows via the registry.
+ */
+async function registerWindows(claudePath: string): Promise<void> {
+  for (const args of [
+    ['add', WINDOWS_REG_KEY, '/ve', '/d', `URL:${APP_NAME}`, '/f'],
+    ['add', WINDOWS_REG_KEY, '/v', 'URL Protocol', '/d', '', '/f'],
+    [
+      'add',
+      WINDOWS_COMMAND_KEY,
+      '/ve',
+      '/d',
+      windowsCommandValue(claudePath),
+      '/f',
+    ],
+  ]) {
+    const { code } = await execFileNoThrow('reg', args, { useCwd: false })
+    if (code !== 0) {
+      throw Object.assign(new Error(`reg add exited with code ${code}`), {
+        code: 'REG_FAILED',
+      })
+    }
+  }
+
+  logForDebugging(
+    `Registered ${DEEP_LINK_PROTOCOL}:// protocol handler in Windows registry`,
+  )
+}
+
+/**
+ * Register the `claude-cli://` protocol handler with the operating system.
+ * After registration, clicking a `claude-cli://` link will invoke claude.
+ */
+export async function registerProtocolHandler(
+  claudePath?: string,
+): Promise<void> {
+  const resolved = claudePath ?? (await resolveClaudePath())
+
+  switch (process.platform) {
+    case 'darwin':
+      await registerMacos(resolved)
+      break
+    case 'linux':
+      await registerLinux(resolved)
+      break
+    case 'win32':
+      await registerWindows(resolved)
+      break
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`)
+  }
+}
+
+/**
+ * Resolve the claude binary path for protocol registration. Prefers the
+ * native installer's stable symlink (~/.local/bin/claude) which survives
+ * auto-updates; falls back to process.execPath when the symlink is absent
+ * (dev builds, non-native installs).
+ */
+async function resolveClaudePath(): Promise<string> {
+  const binaryName = process.platform === 'win32' ? 'claude.exe' : 'claude'
+  const stablePath = path.join(getUserBinDir(), binaryName)
+  try {
+    await fs.realpath(stablePath)
+    return stablePath
+  } catch {
+    return process.execPath
+  }
+}
+
+/**
+ * Check whether the OS-level protocol handler is already registered AND
+ * points at the expected `claude` binary. Reads the registration artifact
+ * directly (symlink target, .desktop Exec line, registry value) rather than
+ * a cached flag in ~/.claude.json, so:
+ *   - the check is per-machine (config can sync across machines; OS state can't)
+ *   - stale paths self-heal (install-method change → re-register next session)
+ *   - deleted artifacts self-heal
+ *
+ * Any read error (ENOENT, EACCES, reg nonzero) → false → re-register.
+ */
+export async function isProtocolHandlerCurrent(
+  claudePath: string,
+): Promise<boolean> {
+  try {
+    switch (process.platform) {
+      case 'darwin': {
+        const target = await fs.readlink(MACOS_SYMLINK_PATH)
+        return target === claudePath
+      }
+      case 'linux': {
+        const content = await fs.readFile(linuxDesktopPath(), 'utf8')
+        return content.includes(linuxExecLine(claudePath))
+      }
+      case 'win32': {
+        const { stdout, code } = await execFileNoThrow(
+          'reg',
+          ['query', WINDOWS_COMMAND_KEY, '/ve'],
+          { useCwd: false },
+        )
+        return code === 0 && stdout.includes(windowsCommandValue(claudePath))
+      }
+      default:
+        return false
+    }
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Auto-register the claude-cli:// deep link protocol handler when missing
+ * or stale. Runs every session from backgroundHousekeeping (fire-and-forget),
+ * but the artifact check makes it a no-op after the first successful run
+ * unless the install path moves or the OS artifact is deleted.
+ */
+export async function ensureDeepLinkProtocolRegistered(): Promise<void> {
+  if (getInitialSettings().disableDeepLinkRegistration === 'disable') {
+    return
+  }
+  if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_lodestone_enabled', false)) {
+    return
+  }
+
+  const claudePath = await resolveClaudePath()
+  if (await isProtocolHandlerCurrent(claudePath)) {
+    return
+  }
+
+  // EACCES/ENOSPC are deterministic — retrying next session won't help.
+  // Throttle to once per 24h so a read-only ~/.local/share/applications
+  // doesn't generate a failure event on every startup. Marker lives in
+  // ~/.claude (per-machine, not synced) rather than ~/.claude.json (can sync).
+  const failureMarkerPath = path.join(
+    getClaudeConfigHomeDir(),
+    '.deep-link-register-failed',
+  )
+  try {
+    const stat = await fs.stat(failureMarkerPath)
+    if (Date.now() - stat.mtimeMs < FAILURE_BACKOFF_MS) {
+      return
+    }
+  } catch {
+    // Marker absent — proceed.
+  }
+
+  try {
+    await registerProtocolHandler(claudePath)
+    logEvent('tengu_deep_link_registered', { success: true })
+    logForDebugging('Auto-registered claude-cli:// deep link protocol handler')
+    await fs.rm(failureMarkerPath, { force: true }).catch(() => {})
+  } catch (error) {
+    const code = getErrnoCode(error)
+    logEvent('tengu_deep_link_registered', {
+      success: false,
+      error_code:
+        code as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    })
+    logForDebugging(
+      `Failed to auto-register deep link protocol handler: ${error instanceof Error ? error.message : String(error)}`,
+      { level: 'warn' },
+    )
+    if (code === 'EACCES' || code === 'ENOSPC') {
+      await fs.writeFile(failureMarkerPath, '').catch(() => {})
+    }
+  }
+}