@miphamai/cli 0.85.5 → 0.85.6

package/bin/mipham.ts

@@ -293,13 +293,26 @@ async function runUpdate(): Promise<boolean> {
   if (!result.ok) {
     console.log()
     console.log(`✗ Update failed: ${result.reason ?? 'unknown error'}`)
-    if (result.rolledBack) {
-      console.log(
-        `  Your previous install (v${currentVersion}) has been restored — mipham still works.`,
-      )
-    } else {
-      console.log('  ⚠ The previous install could not be restored.')
-      console.log(`    Reinstall with: npm install -g ${PACKAGE}@${currentVersion}`)
+    // 这句必须只说**我们知道的**：staging 之后最常见的失败（装在旁边那步挂了）压根没碰过
+    // 旧树，此时沿用「未能恢复」就是在讲一件没发生的事。
+    switch (result.installState) {
+      case 'untouched':
+        console.log(
+          `  Your previous install (v${currentVersion}) was not touched — mipham still works.`,
+        )
+        break
+      case 'restored':
+        console.log(
+          `  Your previous install (v${currentVersion}) has been restored — mipham still works.`,
+        )
+        break
+      case 'unknown':
+        console.log('  ⚠ Could not locate the global install path — unable to tell.')
+        console.log(`    Check with: mipham --version`)
+        break
+      default:
+        console.log('  ⚠ The previous install could not be restored.')
+        console.log(`    Reinstall with: npm install -g ${PACKAGE}@${currentVersion}`)
     }
     if (backupPath && existsSync(backupPath)) {
       console.log(`  Your config backup is at: ${backupPath}`)
@@ -1249,6 +1262,8 @@ Flags:
   --resume <name>            Open a saved session (see /resume for names)
   --permission <mode>        Start in this mode: ${ALL_MODES.join('|')}
                              (also accepted by 'mipham attach'; the daemon may clamp it)
+  --provider <id>            Start on this provider (overrides config.yml)
+  --model <id>               Start on this model (overrides config.yml)
   --version, -v, -V          Print version
 
 Docs: https://mipham.ai/code
@@ -1384,12 +1399,38 @@ npm:  https://www.npmjs.com/package/@miphamai/cli`)
     process.exit(1)
   }
 
+  // Parse --provider <id> / --model <id>: the provider and model the session starts
+  // on. Same shape as `--resume`/`--permission` — `RunOptions` declared both fields all
+  // along, `index.tsx` already reads them *ahead of* the merged config, and **nothing
+  // ever passed them**. That third instance cost more than the first two: both shipped
+  // IDE integrations build this exact command from their settings
+  // (`infrastructure/vscode/extension.js` `buildFlags()`, `MiphamAction.kt`
+  // `buildCommand()`), so a user who set a provider there got
+  // `Unknown command: mipham deepseek` and no CLI at all. Their values are open — a
+  // provider may be user-defined — so the value is forwarded as typed and an unknown id
+  // is refused by the registry (`ProviderRegistry.getActive()` throws with the id named),
+  // exactly as the same value already was when it came from `config.yml`.
+  const flagValue = (name: string): string | undefined => {
+    const at = process.argv.indexOf(name)
+    if (at === -1) return undefined
+    const value = process.argv[at + 1]
+    if (!value || value.startsWith('-')) {
+      console.error(`Usage: mipham ${name} <id>`)
+      process.exit(1)
+    }
+    return value
+  }
+  const providerFlag = flagValue('--provider')
+  const modelFlag = flagValue('--model')
+
   try {
     const { runApp } = await import('../src/index')
     await runApp({
       version: APP_VERSION,
       resume: resumeName,
       permission: permissionFlag.kind === 'ok' ? permissionFlag.mode : undefined,
+      provider: providerFlag,
+      model: modelFlag,
     })
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.85.5",
+  "version": "0.85.6",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",
@@ -40,7 +40,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "knip": "knip --production --no-progress --no-exit-code",
-    "coverage": "vitest run --coverage",
+    "coverage": "vitest run --coverage --reporter=default --reporter=json --outputFile.json=coverage/vitest-report.json",
     "mutate": "stryker run"
   },
   "dependencies": {

package/src/agent/agent-context.ts

@@ -13,6 +13,13 @@ import { MIPHAM_DIR } from '../shared/constants.ts'
 export interface AgentContextResult {
   context: ContextManager
   allowedTools: ToolDefinition[]
+  /**
+   * 组装好的系统提示（**含** agent memory）。
+   *
+   * 必须由这里交出去、而不是让调用方自己再拼一份：memory 的拼接规则只此一处，调用方
+   * 拿不到它就等于重新推导一遍（漏掉的那一遍正是缺陷本身 —— 请求里从来没有记忆）。
+   */
+  systemPrompt: string
 }
 
 /**
@@ -145,5 +152,5 @@ export function createAgentContext(
     allowedTools = allowedTools.filter((t) => !denySet.has(t.name))
   }
 
-  return { context, allowedTools }
+  return { context, allowedTools, systemPrompt }
 }

package/src/agent/effectiveness-tracker.ts

@@ -181,8 +181,22 @@ export class EffectivenessTracker {
   load(): void {
     if (!existsSync(this.storePath)) return
     try {
-      const raw = JSON.parse(readFileSync(this.storePath, 'utf-8'))
-      this.data = new Map(Object.entries(raw))
+      const parsed: unknown = JSON.parse(readFileSync(this.storePath, 'utf-8'))
+      // 形状门：要的是「**以规则 id 为键的对象**」。`Object.entries` 对数组会拿**下标**
+      // 当键（`{"0":"x"}` ⇒ 一条 ruleId 为 undefined 的记录），而 `new Map(...)` 照收，
+      // 于是 `allRules` 把非规则对象当规则报出去。
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        this.data = new Map()
+        return
+      }
+      const data = new Map<string, RuleEffectiveness>()
+      for (const [k, v] of Object.entries(parsed)) {
+        if (!v || typeof v !== 'object' || Array.isArray(v)) continue
+        const rec = v as { ruleId?: unknown }
+        if (typeof rec.ruleId !== 'string') continue
+        data.set(k, v as RuleEffectiveness)
+      }
+      this.data = data
     } catch {
       // Corrupt file — start fresh
       this.data = new Map()

package/src/agent/sub-agent.ts

@@ -339,23 +339,31 @@ export class SubAgent {
     }
 
     // Create isolated context with tool scoping, sized to the resolved model.
-    const resolvedDef: AgentDefinition = agentDef || {
-      name: agentType,
-      description: '',
-      systemPrompt,
-      model: options.modelOverride || 'inherit',
-      permissionMode: 'inherit',
-      background: false,
-      source: 'builtin',
-    }
+    // `systemPrompt` 是运行时**解析出来的那一份**（定义 > 调用方传入 > 内建类型），
+    // 定义自己没写时就落到解析结果上 —— 否则 `createAgentContext()` 拿到的是空串，
+    // 记忆会拼在一个空的基座上。
+    const resolvedDef: AgentDefinition = agentDef
+      ? { ...agentDef, systemPrompt: agentDef.systemPrompt || systemPrompt }
+      : {
+          name: agentType,
+          description: '',
+          systemPrompt,
+          model: options.modelOverride || 'inherit',
+          permissionMode: 'inherit',
+          background: false,
+          source: 'builtin',
+        }
     const contextWindow = this.registry.findModel(finalModel)?.contextWindow
-    const { context, allowedTools } = createAgentContext(
-      resolvedDef,
-      this.toolRegistry,
-      contextWindow,
-    )
+    // 这一份**已含 agent memory**，是发出去的那个提示的唯一来源。
+    const {
+      context,
+      allowedTools,
+      systemPrompt: composedSystemPrompt,
+    } = createAgentContext(resolvedDef, this.toolRegistry, contextWindow)
 
-    context.setSystemPrompt(systemPrompt)
+    // 别再 `context.setSystemPrompt(systemPrompt)`：`createAgentContext` 已经拿**含记忆**的
+    // 那一份设过上下文，这里用裸提示再设一遍只会把记忆从上下文里抹掉，而请求读的又不是
+    // 上下文 —— 两处各设一次的结果是「上下文里没有、请求里也没有」。
 
     // Seed inherited parent conversation (fork inheritance) as a byte-identical
     // prefix so the provider prompt cache is reused.
@@ -405,8 +413,8 @@ export class SubAgent {
     // 权限段随**唯一**带提示的那一轮走，而不是每轮派生。
     const permissionBlock = buildPermissionBlock(gate.getMode())
     let currentSystemPrompt = permissionBlock
-      ? `${systemPrompt}\n\n---\n\n${permissionBlock}`
-      : systemPrompt
+      ? `${composedSystemPrompt}\n\n---\n\n${permissionBlock}`
+      : composedSystemPrompt
     let totalTokens = 0
 
     // Context for the sub-agent's own tool calls. Built once per run: the caller's

package/src/core/autocomplete.ts

@@ -7,16 +7,39 @@ export const AUTOCOMPLETE_SYSTEM_PROMPT =
 /** 带上最近几条对话（含待续写输入），供续写贴合上下文。 */
 export const AUTOCOMPLETE_MAX_CONTEXT = 6
 
+/**
+ * 每条上下文消息最多带这么多**字符**（保留尾部）。
+ *
+ * 上面那个常数限的是**条数**，而一条 `content` 可以任意长 —— 贴进来一个文件、
+ * 或一条长回复，6 条就是上万 token，而用户每次 >400ms 的停顿都要买一次。
+ * 续写要看的是「刚说到哪儿」，所以砍头留尾；加 `…` 是免得把片段读成消息开头。
+ * 每条封顶 + 条数封顶，总量就是封死的，不需要再维护第二个预算常数。
+ */
+export const AUTOCOMPLETE_MAX_CHARS_PER_MESSAGE = 2000
+
 export interface RecentMessage {
   role: 'user' | 'assistant'
   content: string
 }
 
-/** 拼续写请求：systemPrompt + 最近 N 条 + 当前输入作为待续写消息。 */
+function tailOf(content: string): string {
+  return content.length <= AUTOCOMPLETE_MAX_CHARS_PER_MESSAGE
+    ? content
+    : '…' + content.slice(-AUTOCOMPLETE_MAX_CHARS_PER_MESSAGE)
+}
+
+/** 拼续写请求：systemPrompt + 最近 N 条（每条限长）+ 当前输入作为待续写消息。 */
 export function buildAutocompleteRequest(recent: RecentMessage[], input: string): ChatRequest {
   return {
     model: '', // falsy → registry 回退 active model
-    messages: [...recent.slice(-AUTOCOMPLETE_MAX_CONTEXT), { role: 'user', content: input }],
+    // 待续写的当前输入**不截断**：它是被续写的那条本身，且 extractCompletion 的
+    // 判据依赖它的完整值。上限落在历史消息上。
+    messages: [
+      ...recent
+        .slice(-AUTOCOMPLETE_MAX_CONTEXT)
+        .map((m) => ({ role: m.role, content: tailOf(m.content) })),
+      { role: 'user', content: input },
+    ],
     systemPrompt: AUTOCOMPLETE_SYSTEM_PROMPT,
     temperature: 0,
     maxTokens: 64,
@@ -57,6 +80,11 @@ export async function requestSuggestion(
   const req = buildAutocompleteRequest(recent, input)
   let text = ''
   for await (const chunk of llm.chat(req)) {
+    // 用户又敲了一下 ⇒ 这条请求已经过期，当场走人。`break` 不只是「不再读」：
+    // 它触发生成器的 `.return()` ⇒ provider 的 `finally` ⇒ `reader.cancel()`，
+    // 连接当场释放。若把这一判挪到循环外，就等于**先把整条流读完**再丢掉结果 ——
+    // 那正是「取消不掉」：每次 >400ms 的停顿都买一个完整 completion。
+    if (isStale()) break
     if (chunk.type === 'text' && chunk.content) text += chunk.content
   }
   if (isStale()) return null

package/src/core/context.ts

@@ -137,7 +137,11 @@ export class ContextManager {
 
   setSystemPrompt(prompt: string): void {
     this.systemPrompt = prompt
-    this.estimatedTokens = this.estimateTokens(this.composedSystemPrompt())
+    // 估值必须**含 messages** —— 走 `reEstimateTokens()` 这一条唯一推导，别在这儿手写
+    // 第二份。`--resume` 路径（`index.tsx:584-585`）先 `restoreLog()` 算出含消息的完整
+    // 估值，紧接着调这里；只按系统提示重算会把它**覆盖成偏低值** ⇒ `needsCompaction()`
+    // 长期偏 false ⇒ 压缩迟触发（上下文越滚越大才动手）。
+    this.reEstimateTokens()
   }
 
   /**

package/src/core/dream-engine.ts

@@ -521,7 +521,11 @@ export class DreamEngine {
 
       let log: Array<{ timestamp: string; actions: DreamAction[] }> = []
       if (existsSync(this.dreamLog)) {
-        log = JSON.parse(readFileSync(this.dreamLog, 'utf-8'))
+        // 形状门：`{"a":1}` 是**合法 JSON**，不抛 —— 而 `log.unshift` 会抛，被下面的
+        // `catch` 吞掉 ⇒ 这一轮梦白做、且用户看不到任何提示。退成空表继续，
+        // 让这一轮活下来，别让它给一个坏文件陪葬。
+        const parsed: unknown = JSON.parse(readFileSync(this.dreamLog, 'utf-8'))
+        if (Array.isArray(parsed)) log = parsed
       }
       log.unshift({ timestamp, actions })
       // Keep last 10 dream cycles
@@ -536,7 +540,18 @@ export class DreamEngine {
   getDreamHistory(): Array<{ timestamp: string; actions: DreamAction[] }> {
     try {
       if (!existsSync(this.dreamLog)) return []
-      return JSON.parse(readFileSync(this.dreamLog, 'utf-8'))
+      const parsed: unknown = JSON.parse(readFileSync(this.dreamLog, 'utf-8'))
+      // 声明返回数组，就必须真的是数组：`{"a":1}` 合法且不抛，而调用方
+      // （`ui/commands.ts` 的 `/dream --status`）紧接着 `.length` / `.slice` /
+      // `entry.actions.length` ⇒ `try` 护不住调用点，TypeError 直接冒到 UI。
+      if (!Array.isArray(parsed)) return []
+      return parsed.filter(
+        (e): e is { timestamp: string; actions: DreamAction[] } =>
+          !!e &&
+          typeof e === 'object' &&
+          typeof e.timestamp === 'string' &&
+          Array.isArray(e.actions),
+      )
     } catch {
       return []
     }

package/src/core/error-signature-db.ts

@@ -87,8 +87,13 @@ export class ErrorSignatureDB {
     try {
       if (!existsSync(this.storePath)) return
       const raw = readFileSync(this.storePath, 'utf-8')
-      const arr: ErrorSignature[] = JSON.parse(raw)
-      for (const sig of arr) {
+      const parsed: unknown = JSON.parse(raw)
+      // 形状门：`["x"]` 是合法 JSON、`for…of` 也照收 —— `sig.id` 是 `undefined`，
+      // 于是库里躺着一个**没有 id 的成员**（后面 `get(id)` 永远找不到它，
+      // 而 `getStats()` 的分母把它算进去）。形状不验 = 垃圾静默入库。
+      if (!Array.isArray(parsed)) return
+      for (const sig of parsed) {
+        if (!sig || typeof sig !== 'object' || typeof sig.id !== 'string') continue
         this.signatures.set(sig.id, sig)
       }
     } catch {

package/src/core/memory/memory-manager.ts

@@ -546,9 +546,13 @@ export class MemoryManager {
     const path = join(this.memoryDir, LINKS_FILE)
     if (!existsSync(path)) return false
     try {
-      const raw = JSON.parse(readFileSync(path, 'utf-8'))
+      const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'))
+      // 形状门：值必须是**字符串数组**。`new Set("bc")` 会**按字符**迭代 ⇒ 一条链接被
+      // 拆成 'b'、'c' 两条（而 `as string[]` 让 TS 一声不吭）。对象/数组本身也过了门才用。
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return false
       for (const [k, v] of Object.entries(raw)) {
-        this.linkGraph.set(k, new Set(v as string[]))
+        if (!Array.isArray(v)) continue
+        this.linkGraph.set(k, new Set(v.filter((x): x is string => typeof x === 'string')))
       }
       return this.linkGraph.size > 0
     } catch {
@@ -587,12 +591,16 @@ export class MemoryManager {
     const path = join(this.memoryDir, RECALL_STATS_FILE)
     if (!existsSync(path)) return
     try {
-      const raw = JSON.parse(readFileSync(path, 'utf-8'))
+      const raw: unknown = JSON.parse(readFileSync(path, 'utf-8'))
+      if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return
       for (const [k, v] of Object.entries(raw)) {
-        const rec = v as { recallCount?: number; lastRecalledAt?: string }
+        // 逐条门控（不是整表退回）：`catch` 在循环外，一个坏条目会把**后面所有**条目
+        // 一起带走 —— 一条脏记录赔上整份召回统计。
+        if (!v || typeof v !== 'object' || Array.isArray(v)) continue
+        const rec = v as { recallCount?: unknown; lastRecalledAt?: unknown }
         this.recallStats.set(k, {
-          recallCount: rec.recallCount ?? 0,
-          lastRecalledAt: rec.lastRecalledAt ?? '',
+          recallCount: typeof rec.recallCount === 'number' ? rec.recallCount : 0,
+          lastRecalledAt: typeof rec.lastRecalledAt === 'string' ? rec.lastRecalledAt : '',
         })
       }
     } catch {

package/src/core/permission-classifier.ts

@@ -57,15 +57,27 @@ import type { PermissionMode } from '../shared/index.ts'
 export const PROMPT_VERSION = 'mipham-auto-classifier/1'
 
 /**
- * Milliseconds before a ruling is abandoned. Same bound as
- * `self-critique.ts:52`, which is the only measured precedent in this repo.
+ * Milliseconds before a ruling is abandoned.
+ *
+ * This used to be declared as "same bound as `self-critique.ts`" — that pairing
+ * is gone, and deliberately not restored in either direction. The two are both
+ * secondary model calls, but they fail in *opposite* directions: `self-critique`
+ * fails **open** (a timeout ⇒ `null` ⇒ the tool runs), so its budget is bounded
+ * by "how often do we want the critique to actually happen"; this one fails
+ * **closed**, so its budget is bounded by "how long may a legitimate call be
+ * refused for". A budget derived from the fail-open side would be a budget
+ * derived from the wrong question.
  *
  * A tighter bound was considered (it is on the gated path, so every ruled call
  * costs the user the full wait) and rejected: with a fail-closed default, a
  * timeout is indistinguishable from a denial to the user, so shrinking this
- * trades "slow" for "auto mode intermittently refuses legitimate work" — and
- * nobody has measured where the real latency distribution sits. Making it
- * configurable is the right fix when someone does.
+ * trades "slow" for "auto mode intermittently refuses legitimate work" — and the
+ * classifier's own latency distribution still has not been measured. (A sibling
+ * measurement does now exist — `self-critique`'s, median 3.95s over 30 real
+ * calls — and it is a reason to *distrust* this 2s, not a reading that may be
+ * substituted for one.) Making it configurable, or re-basing it, needs that
+ * measurement first; the prompts, the target model and the output shape all
+ * differ from the sibling.
  */
 export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 2000
 

package/src/core/rule-engine.ts

@@ -18,6 +18,23 @@ export interface ToolRule {
   enabled: boolean
 }
 
+/**
+ * 一条**能真正生效**的规则必须自带 `match`/`fix` —— 而这两个是函数，落不了盘。
+ * 判据放在这里而不是内联，是为了让「载回来的规则必须是能用的规则」只有一处定义。
+ */
+function isUsableRule(candidate: unknown): candidate is ToolRule {
+  const r = candidate as Partial<ToolRule> | null
+  return (
+    !!r &&
+    typeof r === 'object' &&
+    typeof r.id === 'string' &&
+    r.id.length > 0 &&
+    typeof r.toolName === 'string' &&
+    typeof r.match === 'function' &&
+    typeof r.fix === 'function'
+  )
+}
+
 const BUILTIN_RULES: ToolRule[] = [
   {
     id: 'rule-timeout-bash-heavy',
@@ -168,9 +185,17 @@ export class ExperienceRuleEngine {
   load(): void {
     if (!existsSync(this.storePath)) return
     try {
-      const raw = JSON.parse(readFileSync(this.storePath, 'utf-8')) as ToolRule[]
+      const parsed: unknown = JSON.parse(readFileSync(this.storePath, 'utf-8'))
+      // 形状门 —— 这一格的门比别处严，因为**这个 store 载不动一条可用的规则**：
+      // `ToolRule.match`/`fix` 是函数，`JSON.stringify` 必然丢，所以 `persist()` 写出去的
+      // 形状里不可能带回来它们。旧读法把这种条目照收，`getActiveRules()` 再把它报成
+      // active（`/rules` 面板跟着说它是活的），而 `intercept()` 里 `rule.match` 不存在
+      // → 抛 → 被那个 `try/catch` 吞成**静默惰性**。列出来是活的、实际永不触发 ——
+      // 正是本仓库反复收的那种账。收不进就是收不进：不校验形状 = 报一份假的活跃清单。
+      if (!Array.isArray(parsed)) return
       const reservedIds = new Set([...BUILTIN_RULES, ...MANAGED_RULES].map((r) => r.id))
-      for (const rule of raw) {
+      for (const rule of parsed) {
+        if (!isUsableRule(rule)) continue
         // Reject if a builtin/managed rule with the same ID exists (source rules always win)
         if (reservedIds.has(rule.id)) continue
         this.rules.push(rule)

package/src/core/self-critique.ts

@@ -3,8 +3,11 @@
  *
  * Inspired by Anthropic's RLAIF (Reinforcement Learning from AI Feedback):
  * instead of relying on human feedback loops, the AI critiques its own
- * tool calls before execution. A fast model (Flash / Qwen2.5-1.5B) performs
- * a lightweight safety & correctness check with <200ms latency.
+ * tool calls before execution. A fast model performs a lightweight safety &
+ * correctness check — but "lightweight" is about the *prompt*, not the clock:
+ * it is a full model round-trip, measured at a median ≈4s on the configured
+ * provider (see `DEFAULT_SELF_CRITIQUE_CONFIG.timeoutMs`), not the sub-200ms
+ * this comment used to claim.
  *
  * Architecture:
  *   Model generates tool call
@@ -58,7 +61,16 @@ export const DEFAULT_SELF_CRITIQUE_CONFIG: SelfCritiqueConfig = {
   enabled: false, // Opt-in by default — user enables via /crsi critique on
   threshold: 0.6,
   targetTools: ['Bash', 'Write', 'Edit', 'Agent'],
-  timeoutMs: 2000,
+  // Measured, not chosen: 30 real critiques against the configured provider
+  // (`findFastestModel` → `deepseek-v4-flash`; default model is the slower
+  // `-pro`) took min 1.85s / median 3.95s / max 17.9s, and **28 of 30 exceeded
+  // 2s** — the value this replaced. At 2s the budget would have skipped 93% of
+  // critiques, and since `critique()` fails *open* (null ⇒ the tool runs
+  // unreviewed) that failure is silent: `/crsi critique` would look enabled and
+  // do nothing. 15s keeps 90% (27/30) while still bounding a gated tool call to
+  // well under the provider's 90s stream-idle backstop. One model, one day —
+  // re-measure if the critique model changes.
+  timeoutMs: 15_000,
 }
 
 // ── Prompt Templates ──

package/src/daemon/launch.ts

@@ -12,7 +12,7 @@
  */
 
 import { spawn, type SpawnOptions } from 'node:child_process'
-import { closeSync, mkdirSync, openSync, readFileSync, statSync } from 'node:fs'
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { miphamHome } from '../core/paths.ts'
 
@@ -141,6 +141,13 @@ const READY_TIMEOUT_MS = 10_000
 const POLL_INTERVAL_MS = 100
 /** How long `restart` waits for the *old* daemon to go before refusing. */
 const OLD_DAEMON_EXIT_TIMEOUT_MS = 10_000
+/**
+ * Bound on the daemon log, enforced by `rotateLogIfLarge`. Two files at this size
+ * are invisible on any disk it will sit on, while the reader only ever wants a tail
+ * (`tailLog` takes the last 800 bytes) — so what the bound has to preserve is not
+ * volume but *the previous generation* of a start that keeps failing.
+ */
+export const MAX_LOG_BYTES = 5 * 1024 * 1024
 
 async function defaultGetStatus(): Promise<DaemonStatusLike | null> {
   const { getDaemonStatus } = await import('./index')
@@ -157,6 +164,45 @@ function tailLog(logPath: string, maxBytes = 800): string {
   }
 }
 
+/**
+ * Bound the log the daemon is about to append to.
+ *
+ * Called before the child is spawned, which is the only moment nothing holds it:
+ * `startDetachedDaemon` returns early when a daemon is already up, so by here its
+ * pid file was gone. (A daemon that died without unlinking the pid file could still
+ * hold the old inode — its lines then land in the renamed file, which loses nothing
+ * and corrupts nothing.)
+ *
+ * **Rename, not truncate.** Either bounds the file, and the reader only wants a tail
+ * — but the case this exists for is a start that keeps failing, and there the
+ * previous generation *is* the evidence. Keeping exactly one bounds the sink at two
+ * files; `renameSync` overwrites the target, so that is also the oldest generation's
+ * cleanup. There is never a `.2`.
+ *
+ * Failing to bound is never fatal: a daemon that refuses to start because its log
+ * could not be rotated trades a slow hazard for an immediate one. And an unreadable
+ * size means the append below is about to fail loudly anyway, so `return` is not a
+ * silent degradation of anything that was working.
+ */
+export function rotateLogIfLarge(logPath: string, maxBytes: number = MAX_LOG_BYTES): void {
+  let size: number
+  try {
+    size = statSync(logPath).size
+  } catch {
+    return // no log yet (every first start)
+  }
+  if (size < maxBytes) return
+  try {
+    renameSync(logPath, `${logPath}.1`)
+  } catch (err) {
+    // Printed rather than thrown, but never swallowed: a bound that switched itself
+    // off in silence is the defect class this whole file is about.
+    process.stderr.write(
+      `⚠️  daemon 日志轮转失败，本次仍按无上限追加: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+  }
+}
+
 /**
  * Start the daemon detached and *wait until it is actually up*.
  *
@@ -177,6 +223,7 @@ export async function startDetachedDaemon(
 
   const plan = planDaemonSpawn()
   mkdirSync(dirname(plan.logPath), { recursive: true, mode: 0o700 })
+  rotateLogIfLarge(plan.logPath)
 
   let spawnError: Error | null = null
   let exitCode: number | null = null
@@ -217,9 +264,29 @@ export async function startDetachedDaemon(
       }
     }
   }
+  // The deadline is a prediction, not a fact. Probe once more before acting on
+  // it: a child that became ready inside the last poll interval is up, and
+  // reporting failure for it — then killing it — would be this module's own
+  // "success with no daemon behind it" defect wearing the opposite sign.
+  const late = await getStatus()
+  if (late) return { ok: true, pid: late.pid, port: late.port }
+
+  // Reclaim the child. Leaving it running makes a failed start a half-truth the
+  // caller cannot act on: `getStatus()` is a pid file plus `kill(pid, 0)`, so the
+  // next `daemon start` finds the abandoned process and reports *success* with
+  // its pid. SIGKILL, not SIGTERM: this process is by definition not ready, so
+  // there is no session to drain — and a child that has already ignored the
+  // deadline is exactly the one that may ignore a polite signal too.
+  const reclaimed = child.kill('SIGKILL')
   return {
     ok: false,
-    reason: `daemon did not become ready within ${opts.timeoutMs ?? READY_TIMEOUT_MS}ms (log: ${plan.logPath})`,
+    reason:
+      `daemon did not become ready within ${opts.timeoutMs ?? READY_TIMEOUT_MS}ms` +
+      // Claim the kill only when it happened: `kill()` also returns false for a
+      // child that exited on its own between the probe and here, and that is not
+      // something to report as "reclaimed".
+      (reclaimed ? '; the child it spawned was killed so no daemon is left running' : '') +
+      ` (log: ${plan.logPath})`,
   }
 }