vellum 0.2.12 → 0.2.14

package/src/tools/network/web-search.ts

@@ -5,31 +5,12 @@ import { registerTool } from '../registry.js';
 import { getConfig } from '../../config/loader.js';
 import { getSecureKey } from '../../security/secure-keys.js';
 import { getLogger } from '../../util/logger.js';
+import { getHttpRetryDelay, sleep, DEFAULT_MAX_RETRIES, DEFAULT_BASE_DELAY_MS } from '../../util/retry.js';
 
 const log = getLogger('web-search');
 
 const BRAVE_API_URL = 'https://api.search.brave.com/res/v1/web/search';
 const PERPLEXITY_API_URL = 'https://api.perplexity.ai/chat/completions';
-const RATE_LIMIT_MAX_RETRIES = 3;
-const RATE_LIMIT_BASE_DELAY_MS = 1000;
-
-/**
- * Parse a Retry-After header value into milliseconds.
- * RFC 7231 allows either delta-seconds (e.g. "120") or an HTTP-date
- * (e.g. "Tue, 17 Feb 2026 12:00:00 GMT"). Returns undefined if unparseable.
- */
-function parseRetryAfterMs(value: string): number | undefined {
-  const seconds = Number(value);
-  if (!isNaN(seconds)) {
-    return seconds * 1000;
-  }
-  // Try HTTP-date format — Date.parse handles RFC 2822 / IMF-fixdate
-  const dateMs = Date.parse(value);
-  if (!isNaN(dateMs)) {
-    return Math.max(0, dateMs - Date.now());
-  }
-  return undefined;
-}
 
 type WebSearchProvider = 'perplexity' | 'brave';
 
@@ -148,7 +129,7 @@ async function executeBraveSearch(
 
   const url = `${BRAVE_API_URL}?${params.toString()}`;
 
-  for (let attempt = 0; attempt <= RATE_LIMIT_MAX_RETRIES; attempt++) {
+  for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
     const response = await fetch(url, {
       headers: {
         'Accept': 'application/json',
@@ -169,12 +150,10 @@ async function executeBraveSearch(
       return { content: 'Error: Invalid or expired Brave Search API key', isError: true };
     }
 
-    if (response.status === 429 && attempt < RATE_LIMIT_MAX_RETRIES) {
-      const retryAfter = response.headers.get('retry-after');
-      const parsed = retryAfter ? parseRetryAfterMs(retryAfter) : undefined;
-      const delayMs = parsed ?? RATE_LIMIT_BASE_DELAY_MS * Math.pow(2, attempt);
+    if (response.status === 429 && attempt < DEFAULT_MAX_RETRIES) {
+      const delayMs = getHttpRetryDelay(response, attempt, DEFAULT_BASE_DELAY_MS);
       log.warn({ attempt: attempt + 1, delayMs }, 'Brave Search rate limited, retrying');
-      await new Promise(resolve => setTimeout(resolve, delayMs));
+      await sleep(delayMs);
       continue;
     }
 
@@ -192,7 +171,7 @@ async function executePerplexitySearch(
   query: string,
   apiKey: string,
 ): Promise<ToolExecutionResult> {
-  for (let attempt = 0; attempt <= RATE_LIMIT_MAX_RETRIES; attempt++) {
+  for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
     const response = await fetch(PERPLEXITY_API_URL, {
       method: 'POST',
       headers: {
@@ -218,12 +197,10 @@ async function executePerplexitySearch(
       return { content: 'Error: Invalid or expired Perplexity API key', isError: true };
     }
 
-    if (response.status === 429 && attempt < RATE_LIMIT_MAX_RETRIES) {
-      const retryAfter = response.headers.get('retry-after');
-      const parsed = retryAfter ? parseRetryAfterMs(retryAfter) : undefined;
-      const delayMs = parsed ?? RATE_LIMIT_BASE_DELAY_MS * Math.pow(2, attempt);
+    if (response.status === 429 && attempt < DEFAULT_MAX_RETRIES) {
+      const delayMs = getHttpRetryDelay(response, attempt, DEFAULT_BASE_DELAY_MS);
       log.warn({ attempt: attempt + 1, delayMs }, 'Perplexity rate limited, retrying');
-      await new Promise(resolve => setTimeout(resolve, delayMs));
+      await sleep(delayMs);
       continue;
     }
 

package/src/tools/policy-context.ts

@@ -0,0 +1,29 @@
+import type { PolicyContext } from '../permissions/types.js';
+import type { Tool, ToolContext } from './types.js';
+import { getTaskRunRules } from '../tasks/ephemeral-permissions.js';
+
+/**
+ * Build a PolicyContext from tool metadata and execution context.
+ * When executing within a task run, ephemeral permission rules are
+ * included so pre-approved tools are auto-allowed without prompting.
+ */
+export function buildPolicyContext(tool: Tool, context?: ToolContext): PolicyContext | undefined {
+  const ephemeralRules = context?.taskRunId
+    ? getTaskRunRules(context.taskRunId)
+    : undefined;
+
+  if (tool.origin === 'skill') {
+    return {
+      executionTarget: tool.executionTarget,
+      ephemeralRules: ephemeralRules?.length ? ephemeralRules : undefined,
+    };
+  }
+
+  if (context?.taskRunId && ephemeralRules?.length) {
+    return {
+      ephemeralRules,
+    };
+  }
+
+  return undefined;
+}

package/src/tools/schedule/update.ts

@@ -1,6 +1,6 @@
 import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { updateSchedule, formatLocalDate, describeCronExpression } from '../../schedule/schedule-store.js';
-import { normalizeScheduleSyntax, type ScheduleSyntax } from '../../schedule/recurrence-types.js';
+import { normalizeScheduleSyntax, detectScheduleSyntax, type ScheduleSyntax } from '../../schedule/recurrence-types.js';
 import { validateRruleSetLines } from '../../schedule/recurrence-engine.js';
 
 export async function executeScheduleUpdate(
@@ -31,9 +31,16 @@ export async function executeScheduleUpdate(
       updates.expression = resolved.expression;
     } else if (input.expression !== undefined) {
       updates.expression = input.expression;
+      const detected = detectScheduleSyntax(input.expression as string);
+      if (detected) updates.syntax = detected;
     } else if (input.cron_expression !== undefined) {
       updates.cronExpression = input.cron_expression;
     }
+    // When only syntax is provided (no expression), normalizeScheduleSyntax returns null
+    // but we still need to persist the explicit syntax value.
+    if (input.syntax !== undefined && updates.syntax === undefined) {
+      updates.syntax = input.syntax;
+    }
   }
 
   if (Object.keys(updates).length === 0) {

package/src/tools/terminal/parser.ts

@@ -3,6 +3,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { getLogger } from '../../util/logger.js';
 import { IntegrityError } from '../../util/errors.js';
+import { PromiseGuard } from '../../util/promise-guard.js';
 import { Parser, Language, type Node as TSNode } from 'web-tree-sitter';
 
 const log = getLogger('shell-parser');
@@ -73,7 +74,7 @@ function verifyWasmChecksum(filePath: string, label: string): void {
 }
 
 let parserInstance: Parser | null = null;
-let initPromise: Promise<void> | null = null;
+const initGuard = new PromiseGuard<void>();
 
 /**
  * Locate a WASM file from a dependency package.
@@ -105,27 +106,24 @@ function findWasmPath(pkg: string, file: string): string {
 async function ensureParser(): Promise<Parser> {
   if (parserInstance) return parserInstance;
 
-  if (!initPromise) {
-    initPromise = (async () => {
-      const treeSitterWasm = findWasmPath('web-tree-sitter', 'web-tree-sitter.wasm');
-      const bashWasmPath = findWasmPath('tree-sitter-bash', 'tree-sitter-bash.wasm');
+  await initGuard.run(async () => {
+    const treeSitterWasm = findWasmPath('web-tree-sitter', 'web-tree-sitter.wasm');
+    const bashWasmPath = findWasmPath('tree-sitter-bash', 'tree-sitter-bash.wasm');
 
-      verifyWasmChecksum(treeSitterWasm, 'web-tree-sitter.wasm');
-      verifyWasmChecksum(bashWasmPath, 'tree-sitter-bash.wasm');
+    verifyWasmChecksum(treeSitterWasm, 'web-tree-sitter.wasm');
+    verifyWasmChecksum(bashWasmPath, 'tree-sitter-bash.wasm');
 
-      await Parser.init({
-        locateFile: () => treeSitterWasm,
-      });
+    await Parser.init({
+      locateFile: () => treeSitterWasm,
+    });
 
-      const Bash = await Language.load(bashWasmPath);
-      const parser = new Parser();
-      parser.setLanguage(Bash);
-      parserInstance = parser;
-      log.info('Shell parser initialized (web-tree-sitter + bash, checksums verified)');
-    })();
-  }
+    const Bash = await Language.load(bashWasmPath);
+    const parser = new Parser();
+    parser.setLanguage(Bash);
+    parserInstance = parser;
+    log.info('Shell parser initialized (web-tree-sitter + bash, checksums verified)');
+  });
 
-  await initPromise;
   return parserInstance!;
 }
 

package/src/tools/types.ts

@@ -1,4 +1,4 @@
-import type { RiskLevel, AllowlistOption, ScopeOption, ToolPrincipalKind } from '../permissions/types.js';
+import type { RiskLevel, AllowlistOption, ScopeOption } from '../permissions/types.js';
 import type { ToolDefinition, ContentBlock } from '../providers/types.js';
 import type { SecretPromptResult } from '../permissions/secret-prompter.js';
 
@@ -12,12 +12,6 @@ interface ToolLifecycleEventBase {
   conversationId: string;
   requestId?: string;
   executionTarget?: ExecutionTarget;
-  /** Security principal kind (e.g. 'core', 'skill', or 'task'). */
-  principalKind?: ToolPrincipalKind;
-  /** Security principal ID (skill ID when principalKind is 'skill'; task ID when 'task'). */
-  principalId?: string;
-  /** Content-hash of the principal's source at invocation time. */
-  principalVersion?: string;
 }
 
 export interface ToolExecutionStartEvent extends ToolLifecycleEventBase {
@@ -109,16 +103,13 @@ export interface ToolContext {
   proxyToolResolver?: ProxyToolResolver;
   /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
   allowedToolNames?: Set<string>;
-  /** Principal that owns this tool invocation (set by executor from tool metadata). */
-  principal?: { kind?: string; id?: string; version?: string };
   /** Request user confirmation for a sub-tool operation (used by claude_code tool). */
   requestConfirmation?: (req: {
     toolName: string;
     input: Record<string, unknown>;
     riskLevel: string;
     executionTarget?: ExecutionTarget;
-    /** Principal that owns the parent tool invocation. */
-    principal?: { kind?: string; id?: string; version?: string };
+    principal?: string;
   }) => Promise<{ decision: 'allow' | 'deny' }>;
   /** Prompt the user for a secret value via native SecureField UI. */
   requestSecret?: (params: {
@@ -141,6 +132,8 @@ export interface ToolContext {
   forcePromptSideEffects?: boolean;
   /** Approval callback for proxy policy decisions that require user confirmation. */
   proxyApprovalCallback?: import('./network/script-proxy/types.js').ProxyApprovalCallback;
+  /** Optional principal identifier propagated to sub-tool confirmation flows. */
+  principal?: string;
 }
 
 export interface DiffInfo {

package/src/twitter/oauth-client.ts

@@ -0,0 +1,102 @@
+/**
+ * OAuth-backed Twitter API client.
+ *
+ * Uses stored OAuth2 Bearer tokens (via the token manager) to execute
+ * Twitter API v2 operations directly, without requiring a browser session.
+ * Currently supports post and reply; all other operations fall back to the
+ * browser-based CDP client.
+ */
+
+import { withValidToken } from '../security/token-manager.js';
+import { getSecureKey } from '../security/secure-keys.js';
+
+const TWITTER_API_BASE = 'https://api.x.com/2';
+const SERVICE = 'integration:twitter';
+
+/** Operations that the OAuth client can handle natively. */
+const SUPPORTED_OPERATIONS = new Set(['post', 'reply']);
+
+export interface OAuthPostResult {
+  tweetId: string;
+  text: string;
+  url?: string;
+}
+
+export interface OAuthOperationError {
+  message: string;
+  suggestFallback: boolean;
+  fallbackPath: 'browser';
+  operation: string;
+}
+
+export class UnsupportedOAuthOperationError extends Error {
+  public readonly suggestFallback = true;
+  public readonly fallbackPath = 'browser' as const;
+  public readonly operation: string;
+  constructor(operation: string) {
+    super(`The "${operation}" operation is not available via the OAuth API. Use the browser path instead.`);
+    this.name = 'UnsupportedOAuthOperationError';
+    this.operation = operation;
+  }
+}
+
+/**
+ * Post a tweet (or reply) using OAuth2 Bearer token authentication.
+ *
+ * The token manager handles refresh transparently — if the stored token
+ * is expired it will be refreshed before (or after a 401) calling the API.
+ */
+export async function oauthPostTweet(
+  text: string,
+  opts?: { inReplyToTweetId?: string },
+): Promise<OAuthPostResult> {
+  return withValidToken(SERVICE, async (token) => {
+    const body: Record<string, unknown> = { text };
+    if (opts?.inReplyToTweetId) {
+      body.reply = { in_reply_to_tweet_id: opts.inReplyToTweetId };
+    }
+
+    const res = await fetch(`${TWITTER_API_BASE}/tweets`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const errorBody = await res.text().catch(() => '');
+      const err = new Error(
+        `Twitter API error (${res.status}): ${errorBody.slice(0, 500)}`,
+      );
+      // Attach status so the token manager's 401-retry logic can detect it.
+      (err as Error & { status: number }).status = res.status;
+      throw err;
+    }
+
+    const json = (await res.json()) as { data: { id: string; text: string } };
+    return {
+      tweetId: json.data.id,
+      text: json.data.text,
+    };
+  });
+}
+
+/**
+ * Check whether OAuth credentials are available for the Twitter integration.
+ * Returns true if an access token has been stored (the token manager will
+ * handle refresh if it's expired).
+ */
+export function oauthIsAvailable(): boolean {
+  return getSecureKey('credential:integration:twitter:access_token') !== undefined;
+}
+
+/**
+ * Check whether a given operation is supported via the OAuth API path.
+ * Only `post` and `reply` are currently supported; everything else
+ * (timeline, search, bookmarks, etc.) requires the browser path.
+ */
+export function oauthSupportsOperation(operation: string): boolean {
+  return SUPPORTED_OPERATIONS.has(operation);
+}

package/src/twitter/router.ts

@@ -0,0 +1,101 @@
+/**
+ * Strategy router for Twitter operations.
+ * Selects OAuth or browser path based on persisted preference and capability.
+ */
+
+import { loadRawConfig } from '../config/loader.js';
+import { oauthPostTweet, oauthIsAvailable, oauthSupportsOperation } from './oauth-client.js';
+import { postTweet as browserPostTweet, SessionExpiredError } from './client.js';
+import type { PostTweetResult } from './client.js';
+
+export type TwitterStrategy = 'oauth' | 'browser' | 'auto';
+
+export interface RoutedResult<T> {
+  result: T;
+  pathUsed: TwitterStrategy;
+}
+
+export interface RoutedError {
+  message: string;
+  pathUsed: TwitterStrategy;
+  suggestAlternative?: TwitterStrategy;
+  alternativeSetupHint?: string;
+}
+
+function getPreferredStrategy(): TwitterStrategy {
+  try {
+    const raw = loadRawConfig();
+    const strategy = raw.twitterOperationStrategy as string | undefined;
+    if (strategy === 'oauth' || strategy === 'browser') return strategy;
+  } catch { /* fall through */ }
+  return 'auto';
+}
+
+export async function routedPostTweet(
+  text: string,
+  opts?: { inReplyToTweetId?: string },
+): Promise<RoutedResult<PostTweetResult>> {
+  const strategy = getPreferredStrategy();
+  const operation = opts?.inReplyToTweetId ? 'reply' : 'post';
+
+  if (strategy === 'oauth') {
+    // User explicitly wants OAuth
+    if (!oauthIsAvailable()) {
+      throw Object.assign(new Error('OAuth is not configured. Set up OAuth credentials in Settings, or switch to browser strategy: `vellum x strategy set browser`.'), {
+        pathUsed: 'oauth' as const,
+        suggestAlternative: 'browser' as const,
+      });
+    }
+    const result = await oauthPostTweet(text, opts);
+    return { result: { tweetId: result.tweetId, text: result.text, url: result.url ?? `https://x.com/i/status/${result.tweetId}` }, pathUsed: 'oauth' };
+  }
+
+  if (strategy === 'browser') {
+    // User explicitly wants browser
+    try {
+      const result = await browserPostTweet(text, opts);
+      return { result, pathUsed: 'browser' };
+    } catch (err) {
+      if (err instanceof SessionExpiredError) {
+        throw Object.assign(err, {
+          pathUsed: 'browser' as const,
+          suggestAlternative: 'oauth' as const,
+        });
+      }
+      throw err;
+    }
+  }
+
+  // auto strategy: try OAuth first if available and supported, fallback to browser
+  let oauthError: Error | undefined;
+  if (oauthIsAvailable() && oauthSupportsOperation(operation)) {
+    try {
+      const result = await oauthPostTweet(text, opts);
+      return { result: { tweetId: result.tweetId, text: result.text, url: result.url ?? `https://x.com/i/status/${result.tweetId}` }, pathUsed: 'oauth' };
+    } catch (err) {
+      oauthError = err instanceof Error ? err : new Error(String(err));
+      // Fall through to browser
+    }
+  }
+
+  // Fallback to browser
+  try {
+    const result = await browserPostTweet(text, opts);
+    return { result, pathUsed: 'browser' };
+  } catch (err) {
+    if (err instanceof SessionExpiredError) {
+      throw Object.assign(err, {
+        pathUsed: 'auto' as const,
+        oauthError: oauthError?.message,
+      });
+    }
+    if (oauthError) {
+      const browserError = err instanceof Error ? err : new Error(String(err));
+      throw Object.assign(browserError, {
+        pathUsed: 'auto' as const,
+        oauthError: oauthError.message,
+      });
+    }
+    throw err;
+  }
+}

package/src/util/debounce.ts

@@ -0,0 +1,88 @@
+/**
+ * Single-key debouncer. Delays execution until no new calls arrive
+ * within the specified delay period.
+ */
+export class Debouncer {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly delayMs: number) {}
+
+  schedule(fn: () => void): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      fn();
+    }, this.delayMs);
+  }
+
+  cancel(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+/**
+ * Multi-key debouncer. Each key gets its own independent timer.
+ * Includes an optional entry limit with eviction of oldest non-protected entries.
+ */
+export class DebouncerMap {
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly defaultDelayMs: number;
+  private readonly maxEntries: number;
+  private readonly protectedKeyPrefix: string;
+
+  constructor(options: {
+    defaultDelayMs: number;
+    maxEntries?: number;
+    protectedKeyPrefix?: string;
+  }) {
+    this.defaultDelayMs = options.defaultDelayMs;
+    this.maxEntries = options.maxEntries ?? Infinity;
+    this.protectedKeyPrefix = options.protectedKeyPrefix ?? '';
+  }
+
+  schedule(key: string, fn: () => void, delayMs?: number): void {
+    const existing = this.timers.get(key);
+    if (existing) clearTimeout(existing);
+    const timer = setTimeout(() => {
+      this.timers.delete(key);
+      fn();
+    }, delayMs ?? this.defaultDelayMs);
+    this.timers.set(key, timer);
+    this.enforceLimit();
+  }
+
+  cancel(key: string): void {
+    const timer = this.timers.get(key);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(key);
+    }
+  }
+
+  cancelAll(): void {
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+  }
+
+  get size(): number {
+    return this.timers.size;
+  }
+
+  private enforceLimit(): void {
+    if (this.timers.size <= this.maxEntries) return;
+    const excess = this.timers.size - this.maxEntries;
+    let removed = 0;
+    for (const [key, timer] of this.timers) {
+      if (removed >= excess) break;
+      if (this.protectedKeyPrefix && key.startsWith(this.protectedKeyPrefix)) continue;
+      clearTimeout(timer);
+      this.timers.delete(key);
+      removed++;
+    }
+  }
+}

package/src/util/network-info.ts

@@ -0,0 +1,47 @@
+import { networkInterfaces } from 'node:os';
+
+/**
+ * Returns the local IPv4 address most likely to be reachable from other
+ * devices on the same LAN.
+ *
+ * Priority order:
+ *   1. en0 (Wi-Fi on macOS)
+ *   2. en1 (secondary network on macOS)
+ *   3. First non-loopback IPv4 on any interface
+ *
+ * Skips link-local addresses (169.254.x.x) and IPv6.
+ * Returns null if no suitable address is found (e.g. no network).
+ */
+export function getLocalIPv4(): string | null {
+  const ifaces = networkInterfaces();
+
+  // Priority interfaces in order
+  const priorityInterfaces = ['en0', 'en1'];
+
+  for (const ifName of priorityInterfaces) {
+    const addrs = ifaces[ifName];
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === 'IPv4' && !addr.internal && !isLinkLocal(addr.address)) {
+        return addr.address;
+      }
+    }
+  }
+
+  // Fallback: first non-loopback, non-link-local IPv4 on any interface
+  for (const [, addrs] of Object.entries(ifaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === 'IPv4' && !addr.internal && !isLinkLocal(addr.address)) {
+        return addr.address;
+      }
+    }
+  }
+
+  return null;
+}
+
+/** Returns true for IPv4 link-local addresses (169.254.x.x). */
+function isLinkLocal(address: string): boolean {
+  return address.startsWith('169.254.');
+}

package/src/util/platform.ts

@@ -135,12 +135,37 @@ export function isTCPEnabled(): boolean {
 
 /**
  * Returns the hostname/address for the TCP listener.
- * Reads VELLUM_DAEMON_TCP_HOST env var; defaults to '127.0.0.1' (localhost only).
- * Set VELLUM_DAEMON_TCP_HOST=0.0.0.0 to accept connections from all interfaces
- * (required for real iOS device connections over a local network).
+ * Resolution order (first match wins):
+ *   1. VELLUM_DAEMON_TCP_HOST env var (explicit override)
+ *   2. If iOS pairing is enabled: '0.0.0.0' (LAN-accessible)
+ *   3. Default: '127.0.0.1' (localhost only)
  */
 export function getTCPHost(): string {
-  return process.env.VELLUM_DAEMON_TCP_HOST?.trim() || '127.0.0.1';
+  const override = process.env.VELLUM_DAEMON_TCP_HOST?.trim();
+  if (override) return override;
+  if (isIOSPairingEnabled()) return '0.0.0.0';
+  return '127.0.0.1';
+}
+
+/**
+ * Returns whether iOS pairing mode is enabled.
+ * When enabled, the TCP listener binds to 0.0.0.0 (all interfaces)
+ * instead of 127.0.0.1 (localhost only), making the daemon reachable
+ * from iOS devices on the same local network.
+ *
+ * Resolution order (first match wins):
+ *   1. VELLUM_DAEMON_IOS_PAIRING env var ('true'/'1' → on, 'false'/'0' → off)
+ *   2. Presence of the flag file ~/.vellum/ios-pairing-enabled (exists → on)
+ *   3. Default: false
+ *
+ * This is separate from isTCPEnabled() — TCP can be enabled for localhost-only
+ * access without exposing the daemon to the LAN.
+ */
+export function isIOSPairingEnabled(): boolean {
+  const override = process.env.VELLUM_DAEMON_IOS_PAIRING?.trim();
+  if (override === 'true' || override === '1') return true;
+  if (override === 'false' || override === '0') return false;
+  return existsSync(join(getRootDir(), 'ios-pairing-enabled'));
 }
 
 export function getHttpTokenPath(): string {

package/src/util/promise-guard.ts

@@ -0,0 +1,37 @@
+/**
+ * Guards against concurrent execution of an async factory.
+ * Multiple concurrent callers share the same in-flight promise.
+ * On failure, the guard resets so subsequent calls can retry.
+ */
+export class PromiseGuard<T> {
+  private promise: Promise<T> | null = null;
+
+  /** Whether a promise is currently in-flight. */
+  get active(): boolean {
+    return this.promise !== null;
+  }
+
+  /**
+   * Execute the factory, deduplicating concurrent calls.
+   * If a call is already in-flight, returns the same promise.
+   * On failure, clears the cached promise to allow retry.
+   *
+   * @param factory - Creates the promise on first call.
+   * @param onError - Optional callback invoked when the factory rejects (before re-throwing).
+   */
+  run(factory: () => Promise<T>, onError?: (err: unknown) => void): Promise<T> {
+    if (this.promise) return this.promise;
+
+    this.promise = factory();
+    this.promise.catch((err) => {
+      this.promise = null;
+      onError?.(err);
+    });
+    return this.promise;
+  }
+
+  /** Reset the guard, allowing the next call to create a new promise. */
+  reset(): void {
+    this.promise = null;
+  }
+}