@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/ui-tui/src/lib/memory.test.ts

@@ -0,0 +1,162 @@
+import { mkdtempSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { performHeapDump } from './memory.js'
+
+const ENV_KEYS = ['HERMES_AUTO_HEAPDUMP', 'HERMES_HEAPDUMP_DIR', 'HERMES_HEAPDUMP_MAX_BYTES'] as const
+
+describe('performHeapDump auto opt-in gate (#21767)', () => {
+  let saved: Record<string, string | undefined>
+  let dir: string
+
+  beforeEach(() => {
+    saved = {}
+
+    for (const k of ENV_KEYS) {
+      saved[k] = process.env[k]
+      delete process.env[k]
+    }
+
+    dir = mkdtempSync(join(tmpdir(), 'hermes-heapdump-test-'))
+    process.env.HERMES_HEAPDUMP_DIR = dir
+  })
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) {
+        delete process.env[k]
+      } else {
+        process.env[k] = saved[k]
+      }
+    }
+
+    rmSync(dir, { force: true, recursive: true })
+  })
+
+  it('writes diagnostics only for auto-high without HERMES_AUTO_HEAPDUMP', async () => {
+    const result = await performHeapDump('auto-high')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBe(true)
+    expect(result.diagPath).toBeDefined()
+    expect(result.heapPath).toBeUndefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.diagnostics.json'))).toBe(true)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(false)
+  })
+
+  it('writes diagnostics only for auto-critical without HERMES_AUTO_HEAPDUMP', async () => {
+    const result = await performHeapDump('auto-critical')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBe(true)
+    expect(result.heapPath).toBeUndefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(false)
+  })
+
+  it('writes both diagnostics and snapshot for auto-high when HERMES_AUTO_HEAPDUMP=1', async () => {
+    process.env.HERMES_AUTO_HEAPDUMP = '1'
+
+    const result = await performHeapDump('auto-high')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBeUndefined()
+    expect(result.diagPath).toBeDefined()
+    expect(result.heapPath).toBeDefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(true)
+  })
+
+  it('accepts truthy spellings (true|yes|on, case-insensitive) as opt-in', async () => {
+    for (const value of ['true', 'YES', 'On']) {
+      process.env.HERMES_AUTO_HEAPDUMP = value
+      const result = await performHeapDump('auto-high')
+
+      expect(result.success).toBe(true)
+      expect(result.heapPath).toBeDefined()
+    }
+  })
+
+  it('treats other values (0, off, garbage) as opt-out for auto triggers', async () => {
+    for (const value of ['0', 'off', 'nope']) {
+      process.env.HERMES_AUTO_HEAPDUMP = value
+      const result = await performHeapDump('auto-high')
+
+      expect(result.success).toBe(true)
+      expect(result.suppressed).toBe(true)
+      expect(result.heapPath).toBeUndefined()
+    }
+  })
+
+  it('writes both for manual triggers regardless of HERMES_AUTO_HEAPDUMP', async () => {
+    const result = await performHeapDump('manual')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBeUndefined()
+    expect(result.heapPath).toBeDefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(true)
+  })
+})
+
+describe('heapdump retention guard (#21767)', () => {
+  let savedDir: string | undefined
+  let savedMax: string | undefined
+  let dir: string
+
+  beforeEach(() => {
+    savedDir = process.env.HERMES_HEAPDUMP_DIR
+    savedMax = process.env.HERMES_HEAPDUMP_MAX_BYTES
+    delete process.env.HERMES_AUTO_HEAPDUMP
+    dir = mkdtempSync(join(tmpdir(), 'hermes-heapdump-prune-'))
+    process.env.HERMES_HEAPDUMP_DIR = dir
+  })
+
+  afterEach(() => {
+    if (savedDir === undefined) {delete process.env.HERMES_HEAPDUMP_DIR}
+    else {process.env.HERMES_HEAPDUMP_DIR = savedDir}
+
+    if (savedMax === undefined) {delete process.env.HERMES_HEAPDUMP_MAX_BYTES}
+    else {process.env.HERMES_HEAPDUMP_MAX_BYTES = savedMax}
+
+    rmSync(dir, { force: true, recursive: true })
+  })
+
+  it('evicts oldest files when total bytes exceed the cap, retaining the newest', async () => {
+    // 4 pre-existing dumps, 1KB each, with ascending mtimes (oldest first).
+    const blob = 'x'.repeat(1024)
+    const now = Date.now()
+
+    for (let i = 0; i < 4; i++) {
+      const p = join(dir, `old-${i}.heapsnapshot`)
+      writeFileSync(p, blob)
+      const t = (now - (4 - i) * 60_000) / 1000
+      utimesSync(p, t, t)
+    }
+
+    // Cap at 2KB → a fresh diagnostics write should trigger a prune down to ~cap.
+    process.env.HERMES_HEAPDUMP_MAX_BYTES = String(2 * 1024)
+
+    const result = await performHeapDump('auto-high')
+    expect(result.success).toBe(true)
+
+    const remaining = readdirSync(dir)
+    const totalBytes = remaining.reduce((acc, f) => acc + statSync(join(dir, f)).size, 0)
+    // Contract: prune evicts oldest-first until total <= cap, but always keeps
+    // the single newest file even if it alone exceeds the cap. So either the
+    // total is under cap, or exactly one (newest) file remains.
+    expect(totalBytes <= 2 * 1024 || remaining.length === 1).toBe(true)
+    // The old 1KB dumps must have been pruned down from the original four.
+    expect(remaining.length).toBeLessThan(5)
+    // The brand-new diagnostics sidecar must survive the prune.
+    expect(remaining.some(f => f.endsWith('.diagnostics.json'))).toBe(true)
+  })
+})

package/agent/ui-tui/src/lib/memory.ts

@@ -1,5 +1,5 @@
 import { createWriteStream } from 'node:fs'
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises'
 import { homedir, tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
@@ -51,6 +51,9 @@ export interface HeapDumpResult {
   diagPath?: string
   error?: string
   heapPath?: string
+  // True when an auto trigger wrote diagnostics only and intentionally skipped
+  // the heavy snapshot because HERMES_AUTO_HEAPDUMP was not enabled (#21767).
+  suppressed?: boolean
   success: boolean
 }
 
@@ -153,8 +156,26 @@ export async function performHeapDump(trigger: MemoryTrigger = 'manual'): Promis
     const heapPath = join(dir, `${base}.heapsnapshot`)
     const diagPath = join(dir, `${base}.diagnostics.json`)
 
+    // The diagnostics JSON is KB-sized and the most useful artifact when a
+    // full snapshot is suppressed by the auto-heapdump opt-in gate below.
     await writeFile(diagPath, JSON.stringify(diagnostics, null, 2), { mode: 0o600 })
+
+    // Auto triggers require explicit opt-in: multi-GiB snapshots written on
+    // every threshold cross can fill the user's disk (issue #21767).
+    const isAuto = trigger === 'auto-critical' || trigger === 'auto-high'
+    const autoEnabled = /^(?:1|true|yes|on)$/i.test((process.env.HERMES_AUTO_HEAPDUMP ?? '').trim())
+
+    if (isAuto && !autoEnabled) {
+      await pruneHeapdumps(dir).catch(() => undefined)
+
+      // Not an error: the dump did its job — it wrote the lightweight
+      // diagnostics sidecar and intentionally skipped the heavy snapshot.
+      // `heapPath` is omitted so callers/notices report diagnostics-only.
+      return { diagPath, suppressed: true, success: true }
+    }
+
     await pipeline(getHeapSnapshot(), createWriteStream(heapPath, { mode: 0o600 }))
+    await pruneHeapdumps(dir).catch(() => undefined)
 
     return { diagPath, heapPath, success: true }
   } catch (e) {
@@ -162,6 +183,44 @@ export async function performHeapDump(trigger: MemoryTrigger = 'manual'): Promis
   }
 }
 
+// Cap total bytes of files in `dir`, deleting oldest first. Covers both
+// `.heapsnapshot` and `.diagnostics.json` artifacts so orphan sidecars from
+// gated auto-triggers cannot accumulate without bound. The newest file is
+// always retained even if it alone exceeds the cap.
+async function pruneHeapdumps(dir: string): Promise<void> {
+  const raw = process.env.HERMES_HEAPDUMP_MAX_BYTES?.trim()
+  const parsed = raw ? Number(raw) : NaN
+  const cap = Number.isFinite(parsed) && parsed > 0 ? parsed : 2 * 1024 ** 3
+
+  const names = await readdir(dir)
+
+  const stats = await Promise.all(
+    names.map(async name => {
+      const path = join(dir, name)
+      const s = await stat(path).catch(() => null)
+
+      return s && s.isFile() ? { mtimeMs: s.mtimeMs, path, size: s.size } : null
+    })
+  )
+
+  const valid = stats.filter((s): s is { mtimeMs: number; path: string; size: number } => s !== null)
+
+  valid.sort((a, b) => b.mtimeMs - a.mtimeMs)
+
+  let total = valid.reduce((acc, s) => acc + s.size, 0)
+
+  while (total > cap && valid.length > 1) {
+    const oldest = valid.pop()
+
+    if (!oldest) {
+      break
+    }
+
+    await unlink(oldest.path).catch(() => undefined)
+    total -= oldest.size
+  }
+}
+
 export function formatBytes(bytes: number): string {
   if (!Number.isFinite(bytes) || bytes <= 0) {
     return '0B'

package/agent/ui-tui/src/lib/memoryMonitor.ts

@@ -1,3 +1,5 @@
+import { getHeapStatistics } from 'node:v8'
+
 import { type HeapDumpResult, performHeapDump } from './memory.js'
 
 export type MemoryLevel = 'critical' | 'high' | 'normal'
@@ -14,9 +16,41 @@ export interface MemoryMonitorOptions {
   intervalMs?: number
   onCritical?: (snap: MemorySnapshot, dump: HeapDumpResult | null) => void
   onHigh?: (snap: MemorySnapshot, dump: HeapDumpResult | null) => void
+  // Fired ONCE when heap growth looks abnormal while still far below the
+  // critical exit threshold — the regime where the TUI used to die silently
+  // (#34095: Node OOMs from an Ink render-tree blowup at a few hundred MB,
+  // well under criticalBytes, so onCritical never fired and the gateway death
+  // showed up only as a bare `stdin EOF`). A visible warning here makes that
+  // class of death diagnosable instead of silent.
+  onWarn?: (snap: MemorySnapshot) => void
+  warnBytes?: number
 }
 
 const GB = 1024 ** 3
+const MB = 1024 ** 2
+
+// Resolve the exit / dump thresholds RELATIVE to the actual V8 heap ceiling
+// (--max-old-space-size, 8GB for the TUI) instead of hardcoding 2.5GB. The old
+// constant killed the process — and silently closed the gateway's stdin — at
+// ~31% of an 8GB ceiling, treating a normal long-session heap as an OOM. We now
+// exit only when genuinely near the ceiling (critical ~88%, high ~70%), and
+// clamp to sane floors/ceilings so a tiny --max-old-space-size can't drive the
+// thresholds below the warn watermark. Callers may still override explicitly.
+function resolveThresholds(criticalBytes?: number, highBytes?: number) {
+  let limit = 0
+  try {
+    limit = getHeapStatistics().heap_size_limit || 0
+  } catch {
+    limit = 0
+  }
+
+  // Fall back to the historical 8GB ceiling if V8 doesn't report one.
+  const ceiling = limit > 0 ? limit : 8 * GB
+  const critical = criticalBytes ?? Math.max(2 * GB, Math.round(ceiling * 0.88))
+  const high = highBytes ?? Math.max(1 * GB, Math.min(critical - 256 * MB, Math.round(ceiling * 0.7)))
+
+  return { critical, high }
+}
 
 // Deferred @hermes/ink import: loading `@hermes/ink` at module top-level
 // pulls the full ~414KB Ink bundle (React, renderer, components, hooks) onto
@@ -53,18 +87,54 @@ async function _ensureEvictInkCaches(): Promise<(level: 'all' | 'half') => unkno
 }
 
 export function startMemoryMonitor({
-  criticalBytes = 2.5 * GB,
-  highBytes = 1.5 * GB,
+  criticalBytes,
+  highBytes,
   intervalMs = 10_000,
   onCritical,
-  onHigh
+  onHigh,
+  onWarn,
+  warnBytes = 600 * MB
 }: MemoryMonitorOptions = {}): () => void {
+  const { critical, high } = resolveThresholds(criticalBytes, highBytes)
   const dumped = new Set<Exclude<MemoryLevel, 'normal'>>()
   const inFlight = new Set<Exclude<MemoryLevel, 'normal'>>()
 
+  // Early-warning state (#34095): the silent-death regime is BELOW `high`, so
+  // the level machine above never sees it. Track the previous sample and fire
+  // onWarn at most once when heap both crosses a modest absolute floor AND is
+  // climbing steeply (≥150MB between 10s ticks) — the signature of a render-
+  // tree blowup — so the user gets a visible heads-up before Node OOMs under
+  // the exit threshold. Re-armed only after heap falls back below the floor.
+  // `lastHeap < 0` marks the un-seeded first sample so a cold start that opens
+  // already-high can't be mistaken for sudden growth (growth = current - last).
+  let lastHeap = -1
+  let warned = false
+  const WARN_GROWTH_STEP = 150 * MB
+
+  // Cooldown prevents repeated auto dumps when heap oscillates around the
+  // threshold (issue #21767). `dumped` alone is not enough — it clears on
+  // every transition back to `normal`.
+  const cooldownRaw = process.env.HERMES_AUTO_HEAPDUMP_COOLDOWN_MS?.trim()
+  const cooldownParsed = cooldownRaw ? Number(cooldownRaw) : NaN
+  const cooldownMs = Number.isFinite(cooldownParsed) && cooldownParsed >= 0 ? cooldownParsed : 600_000
+  let lastAutoDumpAt = 0
+
   const tick = async () => {
     const { heapUsed, rss } = process.memoryUsage()
-    const level: MemoryLevel = heapUsed >= criticalBytes ? 'critical' : heapUsed >= highBytes ? 'high' : 'normal'
+
+    // Sub-threshold abnormal-growth warning. Skip on the first (un-seeded)
+    // sample — we need a prior reading to measure a delta against.
+    if (heapUsed < high && lastHeap >= 0) {
+      if (!warned && heapUsed >= warnBytes && heapUsed - lastHeap >= WARN_GROWTH_STEP) {
+        warned = true
+        onWarn?.({ heapUsed, level: 'normal', rss })
+      } else if (heapUsed < warnBytes) {
+        warned = false
+      }
+    }
+    lastHeap = heapUsed
+
+    const level: MemoryLevel = heapUsed >= critical ? 'critical' : heapUsed >= high ? 'high' : 'normal'
 
     if (level === 'normal') {
       dumped.clear()
@@ -75,7 +145,12 @@ export function startMemoryMonitor({
       return
     }
 
+    if (Date.now() - lastAutoDumpAt < cooldownMs) {
+      return
+    }
+
     inFlight.add(level)
+    lastAutoDumpAt = Date.now()
 
     // Prune Ink content caches before dump/exit — half on 'high' (recoverable),
     // full on 'critical' (post-dump RSS reduction, keeps user running).

package/agent/ui-tui/src/lib/osc52.ts

@@ -53,7 +53,7 @@ export async function readOsc52Clipboard(querier: null | OscQuerier, timeoutMs =
     return null
   }
 
-  const timeout = new Promise<undefined>(resolve => setTimeout(resolve, timeoutMs))
+  const timeout = new Promise<void>(resolve => setTimeout(resolve, timeoutMs))
 
   const query = querier.send<OscResponse>({
     request: buildOsc52ClipboardQuery(),

package/agent/ui-tui/src/lib/text.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { stripTrailingPasteNewlines } from './text.js'
+import { formatAbandonedClarify, stripTrailingPasteNewlines } from './text.js'
 
 describe('stripTrailingPasteNewlines', () => {
   it('removes trailing newline runs from pasted text', () => {
@@ -16,3 +16,34 @@ describe('stripTrailingPasteNewlines', () => {
     expect(stripTrailingPasteNewlines('\n\n')).toBe('\n\n')
   })
 })
+
+describe('formatAbandonedClarify', () => {
+  it('renders the question, numbered options, and reason', () => {
+    const out = formatAbandonedClarify('How do you want to scope?', ['Option A', 'Option B', 'Option C'], 'timed out')
+
+    expect(out).toBe(
+      ['ask How do you want to scope?', '  1. Option A', '  2. Option B', '  3. Option C', '  (timed out — no selection)'].join(
+        '\n'
+      )
+    )
+  })
+
+  it('handles a prompt with no choices (free-text clarify)', () => {
+    const out = formatAbandonedClarify('What is the target branch?', null, 'cancelled')
+
+    expect(out).toBe(['ask What is the target branch?', '  (cancelled — no selection)'].join('\n'))
+  })
+
+  it('trims surrounding whitespace on the question', () => {
+    const out = formatAbandonedClarify('  trailing space  ', [], 'timed out')
+
+    expect(out.split('\n')[0]).toBe('ask trailing space')
+  })
+
+  it('numbers options 1-based to match the live ClarifyPrompt', () => {
+    const out = formatAbandonedClarify('q', ['first'], 'timed out')
+
+    expect(out).toContain('  1. first')
+    expect(out).not.toContain('  0.')
+  })
+})

package/agent/ui-tui/src/lib/text.ts

@@ -1,7 +1,9 @@
 import {
   LIVE_RENDER_MAX_CHARS,
   LIVE_RENDER_MAX_LINES,
-  THINKING_COT_MAX
+  THINKING_COT_MAX,
+  VERBOSE_TRAIL_MAX_CHARS,
+  VERBOSE_TRAIL_MAX_LINES
 } from '../config/limits.js'
 import { VERBS } from '../content/verbs.js'
 import type { ThinkingMode } from '../types.js'
@@ -215,7 +217,16 @@ export const buildToolTrailLine = (
 const verboseToolBlock = (label: string, text?: string) => {
   const body = (text ?? '').trim()
 
-  return body ? `${label}:\n${boundedLiveRenderText(body)}` : ''
+  // Persisted trail blocks are kept all session and rendered expanded by
+  // default — cap to a small readable preview (NOT the 16KB live-render
+  // budget) so a large tool output can't balloon the Ink render tree and
+  // silently OOM-kill the TUI. See VERBOSE_TRAIL_MAX_CHARS (#34095).
+  return body
+    ? `${label}:\n${boundedLiveRenderText(body, {
+        maxChars: VERBOSE_TRAIL_MAX_CHARS,
+        maxLines: VERBOSE_TRAIL_MAX_LINES
+      })}`
+    : ''
 }
 
 export const buildVerboseToolTrailLine = (
@@ -327,6 +338,22 @@ export const estimateRows = (text: string, w: number, compact = false) => {
   return Math.max(1, rows)
 }
 
+/**
+ * Render an unanswered clarify prompt (timed out, or cancelled with Esc/Ctrl+C)
+ * as a persistent transcript block.  The live `ClarifyPrompt` overlay is torn
+ * down the moment the turn settles, so without this the question + options
+ * vanish from the screen while the agent's follow-up still refers to "the
+ * options above".  Mirrors the option formatting in ClarifyPrompt (the same
+ * 1-based numbered list) so the persisted record reads identically to what was
+ * on screen.  `reason` states why the prompt ended ("timed out", "cancelled").
+ */
+export const formatAbandonedClarify = (question: string, choices: string[] | null, reason: string) => {
+  const head = `ask ${question.trim()}`
+  const opts = (choices ?? []).map((c, i) => `  ${i + 1}. ${c}`)
+
+  return [head, ...opts, `  (${reason} — no selection)`].join('\n')
+}
+
 export const flat = (r: Record<string, string[]>) => Object.values(r).flat()
 
 const COMPACT_NUMBER = new Intl.NumberFormat('en-US', { maximumFractionDigits: 1, notation: 'compact' })

package/agent/ui-tui/src/lib/virtualHeights.ts

@@ -72,6 +72,7 @@ export const estimatedMsgHeight = (
   {
     compact,
     details,
+    leadGap = false,
     thinkingVisible = details,
     toolsVisible = details,
     userPrompt = '',
@@ -79,6 +80,7 @@ export const estimatedMsgHeight = (
   }: {
     compact: boolean
     details: boolean
+    leadGap?: boolean
     thinkingVisible?: boolean
     toolsVisible?: boolean
     userPrompt?: string
@@ -129,11 +131,22 @@ export const estimatedMsgHeight = (
   }
 
   if (msg.role === 'user' || msg.kind === 'diff') {
+    // Top + bottom blank line.
     h += 2
   } else if (msg.kind === 'slash') {
     h++
   }
 
+  // Group-boundary blank line owned by BlockSlot: model prose, reasoning/tool
+  // trails, and notes/errors each start a new visual group when the block
+  // above them is a different kind. The caller resolves the boundary against
+  // the previous row (see domain/blockLayout.ts::hasLeadGap) and passes the
+  // result here so the estimate matches the rendered marginTop before Yoga
+  // remeasures. user / diff / slash never set this — they own their margins.
+  if (leadGap) {
+    h++
+  }
+
   // Inter-turn separator above non-first user messages (1 rule row + 1
   // top-margin row). The render-side gate is in appLayout.tsx; we trust
   // the caller to pass `withSeparator` only when it matches that gate.

package/agent/ui-tui/src/types.ts

@@ -90,6 +90,8 @@ export interface DelegationStatus {
 }
 
 export interface ApprovalReq {
+  // false when the backend won't honor a permanent allow (tirith warning) → hide "Always allow".
+  allowPermanent?: boolean
   command: string
   description: string
 }
@@ -138,6 +140,8 @@ export type SectionVisibility = Partial<Record<SectionName, DetailsMode>>
 
 export interface McpServerStatus {
   connected: boolean
+  disabled?: boolean
+  status?: 'configured' | 'connecting' | 'connected' | 'disabled' | 'failed'
   name: string
   tools: number
   transport: string
@@ -170,6 +174,7 @@ export interface Usage {
   context_used?: number
   cost_status?: string
   cost_usd?: number
+  dev_credits_spent_micros?: number
   input: number
   output: number
   reasoning?: number

package/agent/ui-tui/tsconfig.build.json

@@ -1,7 +1,6 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
-    "baseUrl": ".",
     "paths": {
       "@hermes/ink": ["src/types/hermes-ink.d.ts"]
     }

package/agent/ui-tui/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
-    "target": "ES2022",
+    "target": "ES2023",
+    "lib": ["ES2023"],
     "module": "nodenext",
     "moduleResolution": "nodenext",
     "jsx": "react-jsx",

package/agent/utils.py

@@ -1,8 +1,10 @@
 """Shared utility functions for hermes-agent."""
 
+import errno
 import json
 import logging
 import os
+import shutil
 import stat
 import tempfile
 from pathlib import Path
@@ -71,14 +73,38 @@ def atomic_replace(tmp_path: Union[str, Path], target: Union[str, Path]) -> str:
     This helper resolves the symlink first so ``os.replace`` writes to
     the real file in-place while the symlink survives.  For non-symlink
     and non-existent paths the behavior is identical to a plain
-    ``os.replace`` call.
+    ``os.replace`` call unless the rename fails with ``EXDEV`` or ``EBUSY``;
+    those cases fall back to copy/fsync/unlink for cross-device, bind-mount,
+    and busy-file deployments.
 
     Returns the resolved real path used for the replace, so callers that
     need to re-apply permissions can target it instead of the symlink.
     """
     target_str = str(target)
     real_path = os.path.realpath(target_str) if os.path.islink(target_str) else target_str
-    os.replace(str(tmp_path), real_path)
+    tmp_str = str(tmp_path)
+    try:
+        os.replace(tmp_str, real_path)
+    except OSError as exc:
+        if exc.errno not in (errno.EXDEV, errno.EBUSY):
+            raise
+        logger.debug(
+            "atomic_replace: %s -> %s failed with %s; falling back to copy",
+            tmp_str,
+            real_path,
+            errno.errorcode.get(exc.errno, exc.errno),
+        )
+        shutil.copyfile(tmp_str, real_path)
+        try:
+            shutil.copystat(tmp_str, real_path)
+        except OSError:
+            pass
+        try:
+            with open(real_path, "rb") as f:
+                os.fsync(f.fileno())
+        except OSError:
+            pass
+        os.unlink(tmp_str)
     return real_path
 
 
@@ -355,6 +381,44 @@ def base_url_hostname(base_url: str) -> str:
     return (parsed.hostname or "").lower().rstrip(".")
 
 
+# ─── Model Capability Detection ──────────────────────────────────────────────
+
+
+def model_forces_max_completion_tokens(model: str) -> bool:
+    """Return True for model families that require ``max_completion_tokens``.
+
+    OpenAI's newer families reject ``max_tokens`` on /v1/chat/completions with
+    HTTP 400 ``unsupported_parameter`` — the caller must send
+    ``max_completion_tokens`` instead. This covers:
+
+    - ``gpt-4o`` / ``gpt-4o-mini`` / ``gpt-4o-*``
+    - ``gpt-4.1`` / ``gpt-4.1-*``
+    - ``gpt-5`` / ``gpt-5.x`` / ``gpt-5-*``
+    - ``o1`` / ``o1-*``
+    - ``o3`` / ``o3-*``
+    - ``o4`` / ``o4-*``
+
+    Handles vendor prefixes like ``openai/gpt-5.4`` by stripping to the tail.
+    The URL-based check (``base_url_hostname == "api.openai.com"``) misses
+    third-party OpenAI-compatible endpoints (custom OpenAI gateways,
+    OpenRouter) that front these models and enforce the same parameter
+    constraint, so name-based detection is required as a fallback.
+    """
+    m = (model or "").strip().lower()
+    if not m:
+        return False
+    if "/" in m:
+        m = m.rsplit("/", 1)[-1]
+    return (
+        m.startswith("gpt-4o")
+        or m.startswith("gpt-4.1")
+        or m.startswith("gpt-5")
+        or m.startswith("o1")
+        or m.startswith("o3")
+        or m.startswith("o4")
+    )
+
+
 def base_url_host_matches(base_url: str, domain: str) -> bool:
     """Return True when the base URL's hostname is ``domain`` or a subdomain.