@miphamai/cli 0.85.1 → 0.85.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.85.1",
+  "version": "0.85.2",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/src/agent/agent-experience.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs'
+import { mkdirSync, readFileSync, existsSync, unlinkSync } from 'node:fs'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 import { join } from 'node:path'
 import { ExperienceRuleExtractor, type ExperienceRule } from './experience-rules.js'
 import { miphamHome } from '../core/paths.ts'
@@ -109,6 +110,6 @@ export class AgentExperience {
       },
     )
 
-    writeFileSync(this.expFile, content, 'utf-8')
+    atomicWriteFileSync(this.expFile, content, { mode: 0o644 })
   }
 }

package/src/agent/background-registry.ts

@@ -83,12 +83,16 @@ export class BackgroundAgentRegistry {
    *
    * @param description - Human-readable description
    * @param agentType - Sub-agent type (general, explore, plan, code-review)
-   * @param executor - Async function that performs the work
+   * @param executor - Async function that performs the work. Given the task's
+   *   abort signal **and its id**: the id is minted here, and it is the address
+   *   peers send to (`SendMessage` → `MessageRouter` → this `bg-…`), so an
+   *   executor that never learns it has no way to be reachable. Callers that do
+   *   not need it can keep declaring just the signal.
    */
   spawn(
     description: string,
     agentType: string,
-    executor: (signal: AbortSignal) => Promise<string>,
+    executor: (signal: AbortSignal, id: string) => Promise<string>,
     kind: BackgroundTaskKind = 'interactive',
   ): string {
     const id = `bg-${++this.idCounter}-${Date.now().toString(36)}`
@@ -132,7 +136,7 @@ export class BackgroundAgentRegistry {
     }
 
     // Execute in background — do NOT await
-    executor(task.abortController.signal)
+    executor(task.abortController.signal, id)
       .then((result) => {
         task.status = 'completed'
         task.completedAt = new Date()

package/src/agent/cross-session/discovery.ts

@@ -1,12 +1,5 @@
-import {
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  mkdirSync,
-  unlinkSync,
-  statSync,
-} from 'node:fs'
+import { readdirSync, readFileSync, existsSync, mkdirSync, unlinkSync, statSync } from 'node:fs'
+import { atomicWriteFileSync } from '../../shared/atomic-write'
 import { join, basename } from 'node:path'
 import { hostname } from 'node:os'
 import type { SessionInfo, CrossSessionInbound } from '../../shared/types'
@@ -25,7 +18,7 @@ const STALE_SESSION_TTL_MS = 10 * 60 * 1000 // 10 min — heartbeat is 30s
 export function registerActiveSession(info: SessionInfo): void {
   mkdirSync(ACTIVE_SESSIONS_DIR, { recursive: true })
   const filePath = join(ACTIVE_SESSIONS_DIR, `${info.id}.json`)
-  writeFileSync(filePath, JSON.stringify(info, null, 2), 'utf-8')
+  atomicWriteFileSync(filePath, JSON.stringify(info, null, 2), { mode: 0o644 })
 }
 
 /**
@@ -36,7 +29,7 @@ export function heartbeatSession(sessionId: string): void {
   if (existsSync(filePath)) {
     // Touch the file by rewriting it
     const raw = readFileSync(filePath, 'utf-8')
-    writeFileSync(filePath, raw, 'utf-8') // updates mtime
+    atomicWriteFileSync(filePath, raw, { mode: 0o644 }) // updates mtime
   }
 }
 
@@ -141,7 +134,7 @@ export function renameActiveSession(sessionId: string, newName: string): string
   const info = JSON.parse(raw) as SessionInfo
   const others = discoverSessions().filter((s) => s.id !== sessionId)
   info.name = ensureUniqueSessionName(newName, others)
-  writeFileSync(filePath, JSON.stringify(info, null, 2), 'utf-8')
+  atomicWriteFileSync(filePath, JSON.stringify(info, null, 2), { mode: 0o644 })
   return info.name
 }
 

package/src/agent/cross-session/file-inbox.ts

@@ -1,6 +1,5 @@
 import {
   mkdirSync,
-  writeFileSync,
   readdirSync,
   readFileSync,
   unlinkSync,
@@ -8,6 +7,7 @@ import {
   renameSync,
   lstatSync,
 } from 'node:fs'
+import { atomicWriteFileSync } from '../../shared/atomic-write'
 import { join } from 'node:path'
 import type { CrossSessionTransport } from './transport'
 import type { AgentMessage } from '../message-bus'
@@ -69,7 +69,7 @@ export class FileInboxTransport implements CrossSessionTransport {
 
       // Atomic write: temp file then rename
       const tmpPath = filePath + '.tmp'
-      writeFileSync(tmpPath, JSON.stringify(envelope, null, 2), 'utf-8')
+      atomicWriteFileSync(tmpPath, JSON.stringify(envelope, null, 2), { mode: 0o644 })
       renameSync(tmpPath, filePath)
 
       return true

package/src/agent/effectiveness-tracker.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { mkdirSync, readFileSync, existsSync } from 'node:fs'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 import { join, dirname } from 'node:path'
 import type { CrsiProvenanceBridge, CrsiVerdict } from './crsi-provenance-bridge.js'
 import { isRecoverableToolFailure } from './recoverable-failure.js'
@@ -174,7 +175,7 @@ export class EffectivenessTracker {
     for (const [k, v] of this.data) {
       obj[k] = v
     }
-    writeFileSync(this.storePath, JSON.stringify(obj, null, 2), 'utf-8')
+    atomicWriteFileSync(this.storePath, JSON.stringify(obj, null, 2), { mode: 0o644 })
   }
 
   load(): void {

package/src/agent/sub-agent.ts

@@ -1,10 +1,10 @@
 import type { ProviderRegistry } from '../providers/registry'
 import type { Llm } from '../providers/llm'
-import type { ToolDefinition, ToolContext } from '../shared/index.ts'
+import type { Message, ToolDefinition, ToolContext } from '../shared/index.ts'
 import type { SubAgentType, SubAgentOptions, AgentDefinition } from './types'
 import { createAgentContext } from './agent-context'
 import { getBackgroundAgentRegistry } from './background-registry'
-import { getMessageBus } from './message-bus'
+import { formatInboundMessage, getMessageBus } from './message-bus'
 import type { HookEngine } from '../core/hooks'
 import { PermissionSystem } from '../core/permission'
 import { AgentExperience } from './agent-experience'
@@ -91,14 +91,14 @@ export class SubAgent {
     if (options.runInBackground) {
       const bgRegistry = getBackgroundAgentRegistry()
 
-      const taskId = bgRegistry.spawn(description, agentType, async (signal) => {
+      const taskId = bgRegistry.spawn(description, agentType, async (signal, agentId) => {
         // Run the synchronous execution inside the background executor, reporting
         // cumulative token usage back to the registry for live footer display.
         const opts: SubAgentOptions = {
           ...options,
           onTokenUsage: (total) => bgRegistry.updateTokenUsage(taskId, total),
         }
-        return this.runExecution(prompt, opts, signal)
+        return this.runExecution(prompt, opts, signal, agentId)
       })
 
       // Register completion callback for hook firing
@@ -210,10 +210,35 @@ export class SubAgent {
   /**
    * Internal execution method — shared by sync and background paths.
    */
+  /**
+   * Drain same-process messages addressed to *this* agent into its own turn,
+   * mirroring `Engine.drainInboundMessages` for the main session.
+   *
+   * Only the background path has an address to drain: `bg-…` is the recipient the
+   * message router publishes to, and it is minted by the registry — which is why
+   * `spawn` hands it to the executor. Until this ran, `SendMessage` to a running
+   * background agent returned `success: true, routedTo: 'bus'` and the message was
+   * read by nobody: the bus's only reader polled `[sessionId, 'main']`, so what
+   * the sender was told had been delivered sat there until the 1-hour prune.
+   * (The same hole the max-turns notice advertises away — "Use SendMessage to
+   * continue this sub-agent".)
+   */
+  private drainInboundMessages(agentId: string | undefined, messages: Message[]): number {
+    if (!agentId) return 0
+    const bus = getMessageBus()
+    const inbound = bus.poll(agentId)
+    for (const msg of inbound) {
+      messages.push({ role: 'user', content: formatInboundMessage(msg) })
+    }
+    if (inbound.length > 0) bus.markAllRead(agentId)
+    return inbound.length
+  }
+
   private async runExecution(
     prompt: string,
     options: SubAgentOptions,
     signal?: AbortSignal,
+    agentId?: string,
   ): Promise<string> {
     if (!this.registry.getActive()) {
       throw new Error('No active provider available for sub-agent execution')
@@ -391,6 +416,10 @@ export class SubAgent {
           throw new DOMException('Aborted', 'AbortError')
         }
 
+        // Per turn, not once per run: a peer can write while this agent is mid
+        // task, and the point of the channel is to steer the work in progress.
+        this.drainInboundMessages(agentId, currentMessages)
+
         const toolUses: Array<{ id: string; name: string; input: Record<string, unknown> }> = []
         let turnText = ''
 
@@ -506,6 +535,12 @@ export class SubAgent {
           // `createSubAgentPermission`), so the default sub-agent is unchanged.
           const decision = await gate.resolveApproval(tool, effectiveInput, { signal })
           if (decision.level === 'ask') {
+            // Same circuit breaker as `Engine.executeTool`, sharing its threshold:
+            // after this many refusals in a row, say so, so the model stops
+            // re-issuing the call. It matters more here — a sub-agent gets five
+            // turns and cannot ask anyone, so a silent retry loop spends the whole
+            // run on a route that is closed to it.
+            const limitExceeded = gate.incrementBlockCounter()
             currentMessages.push({
               role: 'user' as const,
               content:
@@ -513,10 +548,15 @@ export class SubAgent {
                 `Cannot execute in non-interactive sub-agent context.` +
                 (decision.source === 'classifier' && decision.classifierReason
                   ? ` Classifier: ${decision.classifierReason}`
+                  : '') +
+                (limitExceeded
+                  ? '\n(Consecutive block limit reached. This route stays closed for the rest of this run — try a different approach instead of retrying this call.)'
                   : ''),
             })
             continue
           }
+          // Allowed — the streak is broken (mirrors the engine's reset).
+          gate.resetBlockCounter()
 
           try {
             const result = await tool.execute(effectiveInput, toolContext)

package/src/agent-view/dashboard.tsx

@@ -13,6 +13,7 @@ import { Box, Text, useInput } from 'ink'
 import { AgentViewManager, type AgentSession, type SessionStatus } from './agent-view-manager'
 import { SessionRow } from './session-row'
 import { SessionPeek } from './session-peek'
+import { useCtrlCConfirm } from '../ui/ctrl-c-confirm'
 
 interface DashboardProps {
   manager: AgentViewManager
@@ -35,6 +36,9 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
   // Bump to force flatList recompute after a session is removed (list membership change).
   const [version, setVersion] = useState(0)
 
+  // Ctrl+C 的「再按一次才退」，与主界面同源（见 ui/ctrl-c-confirm.ts）
+  const ctrlC = useCtrlCConfirm()
+
   // Flash a brief feedback message that auto-clears
   const showFeedback = useCallback((msg: string) => {
     setFeedback(msg)
@@ -112,6 +116,24 @@ export function AgentViewDashboard({ manager, onAttach, onExit }: DashboardProps
   )
 
   useInput((input, key) => {
+    // Ctrl+C 不再一下就退出（Ink 的 `exitOnCtrlC` 已在 render 处关掉，见
+    // src/index.tsx）：第一次只提示，再按一次才走。面板里 Esc 已经是退出键，
+    // 所以这里只补「误按一次不带走整个面板」。
+    if (key.ctrl && input === 'c') {
+      if (peekingSessionId) {
+        setPeekingSessionId(null)
+        ctrlC.reset()
+        return
+      }
+      if (ctrlC.isArmed()) {
+        onExit()
+        return
+      }
+      ctrlC.arm()
+      showFeedback('Ctrl+C again to exit')
+      return
+    }
+
     if (key.escape) {
       if (peekingSessionId) {
         setPeekingSessionId(null)

package/src/commands/autoloop-journal.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs'
+import { mkdirSync, readFileSync, readdirSync, existsSync } from 'node:fs'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 import { join } from 'node:path'
 import { miphamHome } from '../core/paths.ts'
 
@@ -43,7 +44,7 @@ export function createAutoloopJournal(
     totalTokens: 0,
     maxIterations: 100,
   }
-  writeFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), 'utf-8')
+  atomicWriteFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), { mode: 0o644 })
   return journal
 }
 
@@ -52,7 +53,7 @@ export function recordLoopTokens(sessionId: string, delta: number): void {
   const journal = readAutoloopJournal(sessionId)
   if (!journal) return
   journal.totalTokens += delta
-  writeFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), 'utf-8')
+  atomicWriteFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), { mode: 0o644 })
 }
 
 /** Read the journal for an autonomous loop. */
@@ -88,7 +89,7 @@ export function logAutoloopIteration(sessionId: string, summary: string): void {
   journal.logs.push(`[${journal.lastIteration}] #${journal.iterations}: ${summary.slice(0, 200)}`)
   // Keep last 50 log entries
   if (journal.logs.length > 50) journal.logs = journal.logs.slice(-50)
-  writeFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), 'utf-8')
+  atomicWriteFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), { mode: 0o644 })
 }
 
 /** Mark an autonomous loop as completed or stopped. */
@@ -97,7 +98,7 @@ export function completeAutoloopJournal(sessionId: string, status: 'completed' |
   if (!journal) return
   journal.status = status
   journal.lastIteration = new Date().toISOString()
-  writeFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), 'utf-8')
+  atomicWriteFileSync(journalPath(sessionId), JSON.stringify(journal, null, 2), { mode: 0o644 })
 }
 
 /** List all active autonomous loops. */

package/src/commands/environment.ts

@@ -89,7 +89,8 @@ Full changelog: https://mipham.ai/code/releases`,
 // ═══════════════════════════════════════════════════════════════
 
 const ideCmd: CommandHandler = async (_ctx) => {
-  const { mkdirSync, writeFileSync } = await import('node:fs')
+  const { mkdirSync } = await import('node:fs')
+  const { atomicWriteFileSync } = await import('../shared/atomic-write')
   const { join } = await import('node:path')
 
   const cwd = process.cwd()
@@ -121,7 +122,7 @@ const ideCmd: CommandHandler = async (_ctx) => {
       },
     },
   }
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8')
+  atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', { mode: 0o644 })
   files.push('.vscode/settings.json')
 
   // ── keybindings.json: Cmd+Esc launch ──
@@ -137,7 +138,7 @@ const ideCmd: CommandHandler = async (_ctx) => {
       command: 'workbench.action.terminal.new',
     },
   ]
-  writeFileSync(keybindingsPath, JSON.stringify(keybindings, null, 2) + '\n', 'utf-8')
+  atomicWriteFileSync(keybindingsPath, JSON.stringify(keybindings, null, 2) + '\n', { mode: 0o644 })
   files.push('.vscode/keybindings.json')
 
   // ── extensions.json: recommended ──
@@ -145,7 +146,7 @@ const ideCmd: CommandHandler = async (_ctx) => {
   const extensions = {
     recommendations: ['miphamai.mipham-code'],
   }
-  writeFileSync(extensionsPath, JSON.stringify(extensions, null, 2) + '\n', 'utf-8')
+  atomicWriteFileSync(extensionsPath, JSON.stringify(extensions, null, 2) + '\n', { mode: 0o644 })
   files.push('.vscode/extensions.json')
 
   return {
@@ -178,8 +179,9 @@ const ideCmd: CommandHandler = async (_ctx) => {
 // ═══════════════════════════════════════════════════════════════
 
 const terminalSetupCmd: CommandHandler = async () => {
-  const { writeFileSync, appendFileSync, existsSync, mkdirSync, readFileSync } =
-    await import('node:fs')
+  const { existsSync, mkdirSync, readFileSync } = await import('node:fs')
+  const { atomicWriteFileSync } = await import('../shared/atomic-write')
+  const { appendRegularFileSync } = await import('../shared/regular-file')
   const { join } = await import('node:path')
   const { homedir } = await import('node:os')
 
@@ -210,7 +212,7 @@ const terminalSetupCmd: CommandHandler = async () => {
     '  export MIPHAM_PROVIDER=$(grep "defaultProvider:" ~/.mipham/config.yml | awk "{print \$2}")',
     'fi',
   ].join('\n')
-  writeFileSync(shellScript, shellContent + '\n', 'utf-8')
+  atomicWriteFileSync(shellScript, shellContent + '\n', { mode: 0o644 })
   lines.push(`  ✅ Generated: ${shellScript}`)
 
   // ── 2. Append to shell profile ──
@@ -224,7 +226,8 @@ const terminalSetupCmd: CommandHandler = async () => {
     if (existing.includes('shell-setup.sh')) {
       lines.push(`  ⏭  ${profileName} already has Mipham Code integration`)
     } else {
-      appendFileSync(profilePath, sourceLine, 'utf-8')
+      // 写不进去（含 profile 路径上是个 FIFO）就与下面 catch 同路：把命令印给用户。
+      if (!appendRegularFileSync(profilePath, sourceLine)) throw new Error('not a regular file')
       lines.push(`  ✅ Added to ~/${profileName}`)
     }
   } catch {

package/src/config/credential-crypto.ts

@@ -8,6 +8,7 @@ import {
   statSync,
 } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { isRegularFile } from '../shared/regular-file'
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
 
 /**
@@ -43,7 +44,9 @@ export function getCredentialKey(keyDir: string): Buffer {
   const keyPath = join(keyDir, CREDENTIAL_KEY_FILENAME)
   if (!existsSync(keyPath)) {
     const legacyPath = join(keyDir, LEGACY_KEY_FILENAME)
-    if (existsSync(legacyPath)) {
+    // 迁移的**源**要过类型闸：`copyFileSync` 打开 FIFO 读端会一直等到有写者
+    // （见 shared/regular-file.ts）。
+    if (isRegularFile(legacyPath)) {
       copyFileSync(legacyPath, keyPath)
       chmodSync(keyPath, 0o400)
     }
@@ -58,6 +61,15 @@ export function getCredentialKey(keyDir: string): Buffer {
  * would ever notice.
  */
 function readKeyFile(keyPath: string): Buffer {
+  // 类型闸先过：这里两次进入都在**启动链**上（配置里任何 `enc:v1:` 都要它解密），
+  // 而 `readFileSync` 读 FIFO/socket 会一直等到有写者为止 —— 挂住时用户看不到报错、
+  // 也没有计时器救得回来。明确失败，并把「去删掉那个东西」写进消息里。
+  if (!isRegularFile(keyPath)) {
+    throw new Error(
+      `${keyPath} is not a regular file — refusing to read the credential key from it ` +
+        `(remove or replace it with a regular file).`,
+    )
+  }
   if ((statSync(keyPath).mode & 0o777) !== 0o400) chmodSync(keyPath, 0o400)
   return readFileSync(keyPath)
 }

package/src/config/keys-manager.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs'
+import { mkdirSync, chmodSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { atomicWriteFileSync } from '../shared/atomic-write'
+import { readRegularFileSync } from '../shared/regular-file'
 import { saveProviderApiKey } from './loader'
 import { miphamHome } from '../core/paths.ts'
 
@@ -29,9 +30,11 @@ export interface KeysData {
 }
 
 function loadKeys(): KeysData {
-  if (!existsSync(KEYS_FILE)) return {}
   try {
-    const raw = readFileSync(KEYS_FILE, 'utf-8')
+    // 类型闸在读取之前（`~/.mipham/keys.json` 若是个 FIFO，`readFileSync` 会
+    // 一直等写者）—— 见 shared/regular-file.ts。
+    const raw = readRegularFileSync(KEYS_FILE)
+    if (raw === null) return {}
     const parsed: unknown = JSON.parse(raw)
     // Valid JSON is not necessarily a key map. `null` throws straight out of
     // `Object.entries` in `list()` — i.e. on the startup path, not in some corner
@@ -92,7 +95,7 @@ export class KeyManager {
       const backupDir = join(MIPHAM_HOME, 'keys')
       mkdirSync(backupDir, { recursive: true })
       const backupPath = join(backupDir, `${provider}.backup`)
-      writeFileSync(backupPath, JSON.stringify(existing, null, 2) + '\n', { mode: 0o600 })
+      atomicWriteFileSync(backupPath, JSON.stringify(existing, null, 2) + '\n', { mode: 0o600 })
       try {
         chmodSync(backupPath, 0o600)
       } catch {

package/src/config/loader.ts

@@ -1,15 +1,8 @@
-import {
-  readFileSync,
-  existsSync,
-  copyFileSync,
-  mkdirSync,
-  readdirSync,
-  unlinkSync,
-  chmodSync,
-} from 'node:fs'
+import { existsSync, copyFileSync, mkdirSync, readdirSync, unlinkSync, chmodSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { atomicWriteFileSync } from '../shared/atomic-write'
+import { isRegularFile, readRegularFileSync } from '../shared/regular-file'
 import type {
   MiphamConfig,
   ProviderConfig,
@@ -41,7 +34,16 @@ const BACKUP_PREFIX = 'config.backup-'
 function safeParseYaml(path: string, label: string): Partial<MiphamConfig> | null {
   try {
     if (!existsSync(path)) return null
-    const raw = readFileSync(path, 'utf-8')
+    // `existsSync` 先过一遍只为「缺席不吭声」；真正决定读不读的是**文件类型**
+    // —— FIFO 上 `readFileSync` 会阻塞到有写者出现，那次挂死没有报错也没有
+    // 计时器救得回来（见 shared/regular-file.ts）。
+    const raw = readRegularFileSync(path)
+    if (raw === null) {
+      process.stderr.write(
+        `⚠ Mipham Code: ${label} (${path}) is not a readable regular file — ignoring it.\n`,
+      )
+      return null
+    }
     return parseYaml(raw) as Partial<MiphamConfig>
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err)
@@ -151,7 +153,8 @@ function mergeConfig(
  */
 function backupConfig(configPath: string): void {
   try {
-    if (!existsSync(configPath)) return
+    // 备份源同样要过类型闸：`copyFileSync` 打开 FIFO 读端一样会等到有写者为止。
+    if (!isRegularFile(configPath)) return
     mkdirSync(MIPHAM_HOME, { recursive: true, mode: 0o700 })
 
     const ts = new Date().toISOString().replace(/[:.]/g, '-')
@@ -190,6 +193,10 @@ export function tryRestoreFromBackup(configPath: string): boolean {
 
     if (files.length === 0) return false
 
+    // 目标已经在那儿而且不是普通文件（FIFO/socket/目录）时不还原：往 FIFO 写
+    // 会挡在「等读者」上，把「恢复」变成又一次挂死；目录则会 EISDIR。缺席才写。
+    if (existsSync(configPath) && !isRegularFile(configPath)) return false
+
     const latestBackup = join(MIPHAM_HOME, files[0]!)
     copyFileSync(latestBackup, configPath)
     process.stderr.write(`⚠ Mipham Code: restored config from backup (${files[0]})\n`)
@@ -220,8 +227,8 @@ function loadMcpJson(cwd: string): McpServerConfig[] {
 
   for (const path of searchPaths) {
     try {
-      if (!existsSync(path)) continue
-      const raw = readFileSync(path, 'utf-8')
+      const raw = readRegularFileSync(path)
+      if (raw === null) continue
       // Every McpServerConfig field is optional here (the name comes from the
       // key), so a field added to the type is accepted without touching this.
       const parsed = JSON.parse(raw) as {
@@ -304,8 +311,8 @@ export function loadSettingsJson(
 
   for (const { path, readHooks, isProject } of searchPaths) {
     try {
-      if (!existsSync(path)) continue
-      const raw = readFileSync(path, 'utf-8')
+      const raw = readRegularFileSync(path)
+      if (raw === null) continue
       const parsed = JSON.parse(raw) as {
         hooks?: Record<string, unknown>
         permissions?: { allow?: unknown; deny?: unknown }
@@ -376,10 +383,11 @@ export function settingsPathFor(scope: SettingsScope, cwd: string = process.cwd(
  * not something to clobber — the user's other settings live in the same file.
  */
 export function readSettingsDoc(path: string): Record<string, unknown> {
-  if (!existsSync(path)) return {}
+  const raw = readRegularFileSync(path)
+  if (raw === null) return {}
   let parsed: unknown
   try {
-    parsed = JSON.parse(readFileSync(path, 'utf-8'))
+    parsed = JSON.parse(raw)
   } catch {
     throw new Error(`${path} is not valid JSON. Fix or remove it, then retry.`)
   }
@@ -452,8 +460,10 @@ export function loadConfig(cwd: string = process.cwd()): MiphamConfig {
   const projectConfig = safeParseYaml(configPath, 'project config')
   if (projectConfig) {
     config = mergeConfig(config, projectConfig, false)
-  } else if (existsSync(configPath)) {
-    // File exists but failed to parse — try to restore from backup
+  } else if (isRegularFile(configPath)) {
+    // A real file is there but failed to parse — try to restore from backup.
+    // 非普通文件走不到这里：那不是「损坏的配置」，而是根本不该当配置读的东西
+    // （FIFO/socket/目录），「恢复」对它会变成往 FIFO 里写、又一次挂死。
     process.stderr.write(`⚠ Mipham Code: project config is corrupted, attempting recovery...\n`)
     if (!tryRestoreFromBackup(configPath)) {
       process.stderr.write(`⚠ Mipham Code: no backup available for project config. Skipping.\n`)
@@ -470,8 +480,9 @@ export function loadConfig(cwd: string = process.cwd()): MiphamConfig {
   const userConfig = safeParseYaml(userConfigPath, 'user config')
   if (userConfig) {
     config = mergeConfig(config, userConfig, true)
-  } else if (existsSync(userConfigPath)) {
-    // File exists but failed to parse — try to restore from backup
+  } else if (isRegularFile(userConfigPath)) {
+    // 用户的 config.yml 是真文件但解析不了 —— 才谈得上「恢复」。判据同上：
+    // 非普通文件不是损坏的配置。
     process.stderr.write(`⚠ Mipham Code: user config is corrupted, attempting recovery...\n`)
     if (!tryRestoreFromBackup(userConfigPath)) {
       process.stderr.write(`⚠ Mipham Code: no backup available for user config. Skipping.\n`)
@@ -545,8 +556,8 @@ export function loadInferenceHookConfig(): InferenceHookConfig {
   const paths = [userConfigPath]
   for (const path of paths) {
     try {
-      if (!existsSync(path)) continue
-      const raw = readFileSync(path, 'utf-8')
+      const raw = readRegularFileSync(path)
+      if (raw === null) continue
       const parsed = parseYaml(raw) as Record<string, unknown>
       const section = parsed.inference_hooks as Partial<InferenceHookConfig> | undefined
       if (section) {
@@ -587,8 +598,8 @@ function mergeCredentialMaskingFile(
   allowLoosening: boolean,
 ): CredentialMaskingConfig {
   try {
-    if (!existsSync(path)) return merged
-    const raw = readFileSync(path, 'utf-8')
+    const raw = readRegularFileSync(path)
+    if (raw === null) return merged
     const parsed = parseYaml(raw) as Record<string, unknown>
     const section = parsed.credential_masking as Partial<CredentialMaskingConfig> | undefined
     if (!section) return merged
@@ -664,8 +675,8 @@ export function loadBackgroundAgentConfig(cwd: string = process.cwd()): Backgrou
   const paths = [userConfigPath, configPath]
   for (const path of paths) {
     try {
-      if (!existsSync(path)) continue
-      const raw = readFileSync(path, 'utf-8')
+      const raw = readRegularFileSync(path)
+      if (raw === null) continue
       const parsed = parseYaml(raw) as Record<string, unknown>
       const section = parsed.background_agent as Partial<BackgroundAgentConfig> | undefined
       if (section) {
@@ -697,8 +708,8 @@ export function loadCrossSessionConfig(cwd: string = process.cwd()): CrossSessio
   const paths = [userConfigPath, configPath] // project wins (loaded last)
   for (const path of paths) {
     try {
-      if (!existsSync(path)) continue
-      const raw = readFileSync(path, 'utf-8')
+      const raw = readRegularFileSync(path)
+      if (raw === null) continue
       const parsed = parseYaml(raw) as Record<string, unknown>
       const section = parsed.cross_session as Partial<CrossSessionConfig> | undefined
       if (section) {
@@ -753,11 +764,11 @@ function decryptProviderApiKeys(providers: ProviderConfig[] | undefined): void {
 export function getProviderApiKey(providerId: string, cwd: string = process.cwd()): string | null {
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
   const projectConfigPath = join(cwd, MIPHAM_DIR, 'config.yml')
-  const configPath = existsSync(userConfigPath) ? userConfigPath : projectConfigPath
+  const configPath = isRegularFile(userConfigPath) ? userConfigPath : projectConfigPath
 
   try {
-    if (!existsSync(configPath)) return null
-    const raw = readFileSync(configPath, 'utf-8')
+    const raw = readRegularFileSync(configPath)
+    if (raw === null) return null
     const doc = (parseYaml(raw) as Record<string, unknown>) || {}
     const providers = (doc.providers as Array<Record<string, unknown>>) || []
     const p = providers.find((x) => x.id === providerId)
@@ -788,9 +799,9 @@ export function saveProviderApiKey(providerId: string, apiKey: string): boolean
 
     // Read existing config (or start fresh)
     let doc: Record<string, unknown> = {}
-    if (existsSync(configPath)) {
-      const raw = readFileSync(configPath, 'utf-8')
-      doc = (parseYaml(raw) as Record<string, unknown>) || {}
+    const existing = readRegularFileSync(configPath)
+    if (existing !== null) {
+      doc = (parseYaml(existing) as Record<string, unknown>) || {}
     }
 
     // Find and update the provider in the providers array