@brimveyn/aimux 1.12.2 → 1.13.0

package/src/pty/assistant-status-detector.ts

@@ -20,6 +20,7 @@ const ACTIVE_CHANGE_WINDOW_MS = 600
 
 /** Spinner glyphs used by claude code's status lines. */
 const CLAUDE_SPINNER_GLYPHS = '·✱✲✳✴✵✶✷✸✹✺✻✼✽✾✿❀❁❂❃❇❈❉❊❋✢✣✤✥✦✧✨⊛⊕⊙◉◎◍⁂⁕※⍟☼★☆'
+const CLAUDE_SPINNER_GLYPH_SET = new Set(CLAUDE_SPINNER_GLYPHS)
 
 const SHELL_COMMAND_PATTERN =
   /(^|\/)(bash|zsh|fish|sh|dash|ash|ksh|tcsh|csh|nu|pwsh|powershell|elvish|xonsh)(\.exe)?$/i
@@ -85,7 +86,8 @@ export class AssistantStatusDetector {
 }
 
 function extractTailText(viewport: TerminalSnapshot, lineCount: number): string {
-  const lines = viewport.tailLines ?? viewport.lines
+  const isScrolledToBottom = viewport.viewportY === viewport.baseY
+  const lines = isScrolledToBottom ? viewport.lines : (viewport.tailLines ?? viewport.lines)
   // Full-screen TUIs (claude, opencode) paint in the alternate buffer and
   // often leave the last rows blank, putting their status bar higher up.
   // Skip trailing blank rows before taking the last `lineCount`.
@@ -152,10 +154,17 @@ function classifyClaude(haystack: string, rawTail: string): TabActivity {
   return 'idle'
 }
 
+// A real spinner line looks like `✱ Thinking…`: glyph at the line start, with
+// the ellipsis on the same line. Anchoring to the line start rejects the `·`
+// separators Claude scatters mid-line through its header/footer (e.g.
+// `Opus 4.7 … · Claude Max`, `… · ← for agents`), which would otherwise pair
+// with a stray `...` placeholder and mark an idle home screen as working.
 function hasClaudeSpinner(rawTail: string): boolean {
-  if (!rawTail.includes('…') && !rawTail.includes('...')) return false
-  for (const ch of CLAUDE_SPINNER_GLYPHS) {
-    if (rawTail.includes(ch)) return true
+  for (const line of rawTail.split('\n')) {
+    const trimmed = line.trimStart()
+    const first = trimmed[0]
+    if (first == null || !CLAUDE_SPINNER_GLYPH_SET.has(first)) continue
+    if (trimmed.includes('…') || trimmed.includes('...')) return true
   }
   return false
 }
@@ -219,8 +228,8 @@ function classifyGeneric(haystack: string, changedAt: number, now: number): TabA
 }
 
 export function isShellCommand(command: string | undefined): boolean {
-  if (!command) return false
+  if (!(command != null && command !== '')) return false
   const first = command.trim().split(/\s+/u)[0]
-  if (!first) return false
+  if (!(first != null && first !== '')) return false
   return SHELL_COMMAND_PATTERN.test(first)
 }

package/src/pty/command-registry.ts

@@ -7,7 +7,8 @@ export interface AssistantOption {
   description: string
 }
 
-const DEFAULT_SHELL = process.env.SHELL || 'sh'
+const DEFAULT_SHELL =
+  process.env.SHELL != null && process.env.SHELL !== '' ? process.env.SHELL : 'sh'
 const SHELL_NAME = DEFAULT_SHELL.split('/').pop() ?? 'shell'
 
 export const ASSISTANT_OPTIONS: AssistantOption[] = [
@@ -29,6 +30,12 @@ export const ASSISTANT_OPTIONS: AssistantOption[] = [
     id: 'opencode',
     label: 'OpenCode',
   },
+  {
+    command: 'agy',
+    description: 'Antigravity CLI',
+    id: 'antigravity',
+    label: 'Antigravity',
+  },
   {
     command: DEFAULT_SHELL,
     description: `Plain terminal (${SHELL_NAME})`,

package/src/pty/pty-manager.ts

@@ -7,7 +7,7 @@ import type { ScrollIntent, TerminalModeState, TerminalSnapshot } from '../state
 import { logDebug } from '../debug/input-log'
 import { areTerminalSnapshotsEqual, snapshotTerminal } from './terminal-snapshot'
 
-type PtyManagerEvents = {
+interface PtyManagerEvents {
   render: [tabId: string, viewport: TerminalSnapshot, terminalModes: TerminalModeState]
   exit: [tabId: string, exitCode: number]
   error: [tabId: string, message: string]

package/src/services/ai-usage/adapters/claude.ts

@@ -47,7 +47,7 @@ let cachedCreds: ClaudeOAuthCreds | null = null
 const CREDS_EXPIRY_BUFFER_MS = 60_000
 
 function normalizePlanTier(raw: string | undefined | null): string | null {
-  if (!raw) return null
+  if (!(raw != null && raw !== '')) return null
   const trimmed = raw.trim()
   if (!trimmed) return null
   const lower = trimmed.toLowerCase()
@@ -64,7 +64,7 @@ function planTierFromPayload(payload: ClaudeKeychainPayload): string | null {
   if (!o) return null
   const raw = o.rateLimitTier ?? o.rate_limit_tier ?? o.subscriptionType
   const normalized = normalizePlanTier(raw)
-  if (normalized) return normalized
+  if (normalized != null && normalized !== '') return normalized
   if (Array.isArray(o.scopes)) {
     for (const scope of o.scopes) {
       const s = scope.toLowerCase()
@@ -101,7 +101,7 @@ async function readClaudeCreds(): Promise<ClaudeOAuthCreds> {
   }
   const parsed = JSON.parse(result.stdout.trim()) as ClaudeKeychainPayload
   const access = parsed.claudeAiOauth?.accessToken
-  if (!access) {
+  if (!(access != null && access !== '')) {
     throw new Error('no accessToken in Claude Code keychain')
   }
   cachedCreds = {
@@ -123,8 +123,8 @@ function buildWindow(
   const util = typeof payload.utilization === 'number' ? payload.utilization : null
   const percent = util === null ? null : Math.max(0, Math.min(100, util))
   const resetAt = payload.resets_at ?? null
-  const resetAtMs = resetAt ? new Date(resetAt).getTime() : null
-  if (percent === null && !resetAt) return null
+  const resetAtMs = resetAt != null && resetAt !== '' ? new Date(resetAt).getTime() : null
+  if (percent === null && !(resetAt != null && resetAt !== '')) return null
   return {
     kind,
     label,

package/src/services/ai-usage/adapters/codex.ts

@@ -40,7 +40,7 @@ const AUTH_TIMEOUT_MS = 15_000
 
 function codexHome(): string {
   const env = process.env.CODEX_HOME?.trim()
-  if (env) return env
+  if (env != null && env !== '') return env
   return join(homedir(), '.codex')
 }
 
@@ -81,7 +81,7 @@ async function resolveUsageURL(): Promise<string> {
   try {
     const contents = await readFile(join(codexHome(), 'config.toml'), 'utf8')
     const parsed = parseChatGPTBaseFromConfig(contents)
-    if (parsed) base = parsed
+    if (parsed != null && parsed !== '') base = parsed
   } catch {
     // no config.toml or unreadable — fall back to default
   }
@@ -94,7 +94,7 @@ async function loadAuth(): Promise<{ accessToken: string; accountId: string | nu
   const raw = await readFile(join(codexHome(), 'auth.json'), 'utf8')
   const parsed = JSON.parse(raw) as CodexAuthFile
   const accessToken = parsed.tokens?.access_token
-  if (!accessToken) {
+  if (!(accessToken != null && accessToken !== '')) {
     throw new Error('no access_token in ~/.codex/auth.json — run `codex` to sign in')
   }
   return {
@@ -104,7 +104,7 @@ async function loadAuth(): Promise<{ accessToken: string; accountId: string | nu
 }
 
 function normalizePlanTier(raw: string | undefined | null): string | null {
-  if (!raw) return null
+  if (!(raw != null && raw !== '')) return null
   const trimmed = raw.trim()
   if (!trimmed) return null
   const lower = trimmed.toLowerCase()
@@ -128,11 +128,11 @@ function buildCodexWindow(
   if (!window) return null
   const percent =
     typeof window.used_percent === 'number' ? Math.max(0, Math.min(100, window.used_percent)) : null
-  const resetAtMs = window.reset_at ? window.reset_at * 1000 : null
-  const resetAt = resetAtMs ? new Date(resetAtMs).toISOString() : null
+  const resetAtMs = window.reset_at != null && window.reset_at !== 0 ? window.reset_at * 1000 : null
+  const resetAt = resetAtMs != null && resetAtMs !== 0 ? new Date(resetAtMs).toISOString() : null
   const windowSeconds =
     typeof window.limit_window_seconds === 'number' ? window.limit_window_seconds : null
-  if (percent === null && !resetAt) return null
+  if (percent === null && !(resetAt != null && resetAt !== '')) return null
   return {
     kind,
     label,
@@ -186,7 +186,7 @@ export async function fetchCodexUsage(_config: AIUsageToolConfig): Promise<Usage
       'Authorization': `Bearer ${accessToken}`,
       'User-Agent': 'aimux',
     }
-    if (accountId) headers['ChatGPT-Account-Id'] = accountId
+    if (accountId != null && accountId !== '') headers['ChatGPT-Account-Id'] = accountId
 
     const controller = new AbortController()
     const timer = setTimeout(() => controller.abort(), AUTH_TIMEOUT_MS)

package/src/services/ai-usage/cache.ts

@@ -40,12 +40,12 @@ export function loadCachedSnapshot(tool: AIUsageTool, maxAgeMs: number): CachedS
   if (typeof entry.fetchedAt !== 'number') return null
   const ageMs = Date.now() - entry.fetchedAt
   if (ageMs > maxAgeMs) return null
-  if (!entry.snapshot || entry.snapshot.tool !== tool) return null
+  if (entry.snapshot.tool !== tool) return null
   return { ageMs, snapshot: entry.snapshot }
 }
 
 export function saveCachedSnapshot(snapshot: UsageSnapshot): void {
-  if (snapshot.error) return
+  if (snapshot.error != null && snapshot.error !== '') return
   if (snapshot.percent === null) return
   try {
     mkdirSync(CACHE_DIR, { recursive: true })

package/src/services/ai-usage/pace.ts

@@ -29,7 +29,7 @@ export function computePace(opts: {
 }): UsagePace | null {
   const { percent, resetAtMs, windowSeconds } = opts
   const now = opts.now ?? Date.now()
-  if (percent === null || resetAtMs === null || !windowSeconds || windowSeconds <= 0) {
+  if (percent === null || resetAtMs === null || windowSeconds == null || windowSeconds <= 0) {
     return null
   }
 
@@ -49,11 +49,8 @@ export function computePace(opts: {
     if (rate > 0) {
       const remaining = Math.max(0, 100 - actual)
       const candidate = remaining / rate
-      if (candidate >= timeUntilReset) {
-        rightText = 'Lasts to reset'
-      } else {
-        rightText = `Runs out in ${formatDuration(candidate)}`
-      }
+      rightText =
+        candidate >= timeUntilReset ? 'Lasts to reset' : `Runs out in ${formatDuration(candidate)}`
     }
   } else if (elapsed > 0 && actual === 0) {
     rightText = 'Lasts to reset'

package/src/services/ai-usage/provider.ts

@@ -49,7 +49,7 @@ export function startAIUsageService(
     }
 
     if (toFetch.length > 0) {
-      const results = await Promise.allSettled(toFetch.map((t) => fetchFor(t, config)))
+      const results = await Promise.allSettled(toFetch.map(async (t) => fetchFor(t, config)))
       if (stopped) return
       for (let i = 0; i < results.length; i++) {
         const result = results[i]

package/src/session-backend/bootstrap.ts

@@ -48,7 +48,7 @@ async function spawnDaemon(): Promise<void> {
 
 async function canConnectToDaemon(socketPath: string): Promise<boolean> {
   const securityIssue = getSocketSecurityIssue(socketPath)
-  if (securityIssue) {
+  if (securityIssue != null && securityIssue !== '') {
     logDebug('backend.healthcheck.socketIssue', { issue: securityIssue, socketPath })
     return false
   }
@@ -77,7 +77,7 @@ export async function probeDaemonProtocolCompatibility(
   socketPath: string
 ): Promise<DaemonHandshakeProbeResult> {
   const securityIssue = getSocketSecurityIssue(socketPath)
-  if (securityIssue) {
+  if (securityIssue != null && securityIssue !== '') {
     return { compatible: false, error: securityIssue }
   }
 

package/src/session-backend/local-session-backend.ts

@@ -114,7 +114,7 @@ export class LocalSessionBackend
     rows: number
     cwd?: string
   }): void {
-    if (!this.currentSessionId) {
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) {
       logDebug('backend.local.skipCreateWithoutSession', { tabId: options.tabId })
       return
     }
@@ -127,7 +127,7 @@ export class LocalSessionBackend
   }
 
   write(tabId: string, input: string): void {
-    if (!this.currentSessionId) {
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) {
       logDebug('backend.local.skipWriteWithoutSession', { inputLength: input.length, tabId })
       return
     }
@@ -140,22 +140,22 @@ export class LocalSessionBackend
   }
 
   scrollViewport(tabId: string, deltaLines: number): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.scroll(this.currentSessionId, tabId, deltaLines)
   }
 
   scrollViewportToBottom(tabId: string): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.scrollToBottom(this.currentSessionId, tabId)
   }
 
   reapplyScrollIntent(tabId: string, intent: ScrollIntent): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.reapplyScrollIntent(this.currentSessionId, tabId, intent)
   }
 
   setActiveTab(tabId: string | null): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     logDebug('backend.local.setActiveTab', { sessionId: this.currentSessionId, tabId })
     this.sessionManager.setActiveTab(this.currentSessionId, tabId)
   }
@@ -166,7 +166,7 @@ export class LocalSessionBackend
     intents?: Map<string, ScrollIntent>,
     options?: { sync?: boolean }
   ): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.resize(this.currentSessionId, cols, rows, intents, options)
   }
 
@@ -177,25 +177,25 @@ export class LocalSessionBackend
     intent?: ScrollIntent,
     options?: { sync?: boolean }
   ): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     this.sessionManager.resizeTab(this.currentSessionId, tabId, cols, rows, intent, options)
   }
 
   disposeSession(tabId: string): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     logDebug('backend.local.disposeSession', { sessionId: this.currentSessionId, tabId })
     this.sessionManager.closeTab(this.currentSessionId, tabId)
   }
 
   disposeAll(): void {
-    if (!this.currentSessionId) return
+    if (!(this.currentSessionId != null && this.currentSessionId !== '')) return
     logDebug('backend.local.disposeAll', { sessionId: this.currentSessionId })
     this.sessionManager.disposeSession(this.currentSessionId)
   }
 
   destroy(keepSessions = true): void {
     logDebug('backend.local.destroy', { keepSessions, sessionId: this.currentSessionId })
-    if (!keepSessions && this.currentSessionId) {
+    if (!keepSessions && this.currentSessionId != null && this.currentSessionId !== '') {
       this.sessionManager.disposeSession(this.currentSessionId)
     }
     this.statusLoop.stop()

package/src/session-backend/remote-session-backend.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events'
-import { connect, Socket } from 'node:net'
+import { connect, type Socket } from 'node:net'
 
 import type { AssistantId, ScrollIntent, WorkspaceSnapshotV1 } from '../state/types'
 import type { SessionBackend, SessionBackendEvents } from './types'
@@ -96,7 +96,7 @@ export class RemoteSessionBackend
     return this.socket
   }
 
-  private send(request: ClientRequest): Promise<ServerResponse> {
+  private async send(request: ClientRequest): Promise<ServerResponse> {
     const socket = this.getConnectedSocket()
     logDebug('backend.remote.send', { id: request.id, type: request.type })
     return new Promise((resolve, reject) => {
@@ -139,7 +139,7 @@ export class RemoteSessionBackend
   private reportCommandError(context: string, error: unknown, tabId?: string): void {
     const message = error instanceof Error ? error.message : String(error)
     logDebug('backend.remote.commandError', { context, error: message, tabId })
-    if (tabId) {
+    if (tabId != null && tabId !== '') {
       this.emit('error', tabId, message)
     }
   }

package/src/session-backend/types.ts

@@ -10,7 +10,7 @@ import type {
   WorkspaceSnapshotV1,
 } from '../state/types'
 
-export type SessionBackendEvents = {
+export interface SessionBackendEvents {
   render: [tabId: string, viewport: TerminalSnapshot, terminalModes: TerminalModeState]
   exit: [tabId: string, exitCode: number]
   error: [tabId: string, message: string]
@@ -26,7 +26,7 @@ export interface BackendAttachResult {
    * atomically with tab hydration to prevent an unknown-tab race on
    * separate `sessionActivity` events.
    */
-  initialSessionStatuses: Array<{ sessionId: string; status: SessionStatus }>
+  initialSessionStatuses: { sessionId: string; status: SessionStatus }[]
 }
 
 export interface SessionBackend extends EventEmitter<SessionBackendEvents> {

package/src/snippets/expand-variables.ts

@@ -0,0 +1,112 @@
+import type { SnippetRecord } from '../state/types'
+
+/**
+ * Snippet/macro content expander.
+ *
+ * Supports:
+ *  - Custom (per-snippet) variables resolved upstream and passed via `customVars`.
+ *    These shadow built-ins on name collision.
+ *  - `{{date}}`, `{{date:FORMAT}}` with tokens YYYY MM DD HH mm ss
+ *  - `{{cwd}}` (resolved from context)
+ *  - `{{branch}}` (resolved from context; empty string when null)
+ *  - `{{clipboard}}` (async; only available via `expandSnippet`)
+ *  - `$|` cursor placeholder (first occurrence wins; subsequent are stripped)
+ *  - Unknown `{{...}}` tokens are left literal.
+ */
+
+export interface ExpansionContext {
+  cwd: string
+  branch: string | null
+  now: Date
+  customVars: ReadonlyMap<string, string>
+  clipboard: () => Promise<string>
+}
+
+export type SyncExpansionContext = Omit<ExpansionContext, 'clipboard'>
+
+export interface ExpansionResult {
+  text: string
+  cursorOffset: number
+}
+
+const VAR_RE = /\{\{([^{}]+)\}\}/g
+
+const TWO = (n: number): string => String(n).padStart(2, '0')
+
+function formatDate(date: Date, format?: string): string {
+  if (!(format != null && format !== '')) {
+    return `${date.getFullYear()}-${TWO(date.getMonth() + 1)}-${TWO(date.getDate())}`
+  }
+  return format
+    .replaceAll('YYYY', String(date.getFullYear()))
+    .replaceAll('MM', TWO(date.getMonth() + 1))
+    .replaceAll('DD', TWO(date.getDate()))
+    .replaceAll('HH', TWO(date.getHours()))
+    .replaceAll('mm', TWO(date.getMinutes()))
+    .replaceAll('ss', TWO(date.getSeconds()))
+}
+
+function resolveSyncVariable(name: string, ctx: SyncExpansionContext): string | null {
+  const custom = ctx.customVars.get(name)
+  if (custom !== undefined) return custom
+  if (name === 'date') return formatDate(ctx.now)
+  if (name.startsWith('date:')) return formatDate(ctx.now, name.slice('date:'.length))
+  if (name === 'cwd') return ctx.cwd
+  if (name === 'branch') return ctx.branch ?? ''
+  return null
+}
+
+/**
+ * Replace `$|` with a cursor offset.
+ * First occurrence becomes the offset; additional ones are stripped.
+ * If none present, cursor is placed at the end of the text.
+ */
+function extractCursor(text: string): ExpansionResult {
+  const firstIndex = text.indexOf('$|')
+  if (firstIndex === -1) {
+    return { cursorOffset: text.length, text }
+  }
+  const before = text.slice(0, firstIndex)
+  const after = text
+    .slice(firstIndex + 2)
+    .split('$|')
+    .join('')
+  return { cursorOffset: before.length, text: before + after }
+}
+
+export function contentNeedsClipboard(content: string): boolean {
+  return /\{\{\s*clipboard\s*\}\}/.test(content)
+}
+
+export function requiresAsyncExpansion(snippet: SnippetRecord): boolean {
+  const hasVars = snippet.vars !== undefined && Object.keys(snippet.vars).length > 0
+  return hasVars || contentNeedsClipboard(snippet.content)
+}
+
+export function expandSnippetSync(content: string, ctx: SyncExpansionContext): ExpansionResult {
+  const replaced = content.replace(VAR_RE, (match, rawName: string) => {
+    const name = rawName.trim()
+    if (name === 'clipboard') return match
+    const resolved = resolveSyncVariable(name, ctx)
+    return resolved ?? match
+  })
+  return extractCursor(replaced)
+}
+
+export async function expandSnippet(
+  content: string,
+  ctx: ExpansionContext
+): Promise<ExpansionResult> {
+  let clipboardValue: string | null = null
+  const needsClipboard = contentNeedsClipboard(content) && !ctx.customVars.has('clipboard')
+  if (needsClipboard) {
+    clipboardValue = await ctx.clipboard()
+  }
+  const replaced = content.replace(VAR_RE, (match, rawName: string) => {
+    const name = rawName.trim()
+    if (name === 'clipboard' && clipboardValue !== null) return clipboardValue
+    const resolved = resolveSyncVariable(name, ctx)
+    return resolved ?? match
+  })
+  return extractCursor(replaced)
+}

package/src/snippets/run-shell-var.ts

@@ -0,0 +1,93 @@
+import type { SnippetShellVar } from '@brimveyn/aimux-config'
+
+import { logDebug } from '../debug/input-log'
+
+const DEFAULT_TIMEOUT_MS = 5000
+/** Hard ceiling on any user-supplied timeout to prevent runaway expansions. */
+const MAX_TIMEOUT_MS = 30_000
+
+/**
+ * Build the shell argv. We default to `$SHELL -l -c <cmd>` so the user's
+ * login shell rc files (e.g. /etc/zprofile → path_helper on macOS) populate
+ * PATH and make tools like `gh`, `jira`, `brew` resolvable — matching
+ * Espanso's behavior. Falls back to `/bin/sh -c` if SHELL is unset.
+ */
+function buildShellArgv(cmd: string): string[] {
+  const userShell = process.env.SHELL
+  if (userShell != null && userShell !== '' && userShell.length > 0) {
+    return [userShell, '-l', '-c', cmd]
+  }
+  return ['/bin/sh', '-c', cmd]
+}
+
+/**
+ * Run a snippet shell var via the user's login shell, capture stdout.
+ *
+ * Returns the trimmed stdout on success, or '' on error / timeout / non-zero
+ * exit. Stderr is captured for logging but never propagated into the result —
+ * snippet content is for the terminal, not for surfacing failures.
+ */
+export async function runShellVar(name: string, v: SnippetShellVar): Promise<string> {
+  const requested = v.timeout ?? DEFAULT_TIMEOUT_MS
+  const timeoutMs = Math.min(Math.max(requested, 0), MAX_TIMEOUT_MS)
+
+  let proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'>
+  try {
+    proc = Bun.spawn(buildShellArgv(v.sh), {
+      stderr: 'pipe',
+      stdin: 'ignore',
+      stdout: 'pipe',
+    })
+  } catch (error) {
+    logDebug('snippets.shellVar.spawnError', {
+      cmd: v.sh,
+      error: error instanceof Error ? error.message : String(error),
+      name,
+    })
+    return ''
+  }
+
+  let timeoutFired = false
+  const timeoutHandle = setTimeout(() => {
+    timeoutFired = true
+    try {
+      proc.kill()
+    } catch {
+      // process already gone
+    }
+  }, timeoutMs)
+
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+
+    if (timeoutFired) {
+      logDebug('snippets.shellVar.timeout', { cmd: v.sh, name, timeoutMs })
+      return ''
+    }
+
+    if (exitCode !== 0) {
+      logDebug('snippets.shellVar.nonZeroExit', {
+        cmd: v.sh,
+        exitCode,
+        name,
+        stderr: stderr.slice(0, 200),
+      })
+      return ''
+    }
+
+    return v.trim === false ? stdout : stdout.replace(/\s+$/, '')
+  } catch (error) {
+    logDebug('snippets.shellVar.error', {
+      cmd: v.sh,
+      error: error instanceof Error ? error.message : String(error),
+      name,
+    })
+    return ''
+  } finally {
+    clearTimeout(timeoutHandle)
+  }
+}