@miphamai/cli 0.81.7 → 0.81.8

package/README.md

@@ -1,4 +1,4 @@
-# Mipham Code v0.81.6
+# Mipham Code v0.81.7
 
 **Multi-model open-core intelligent coding terminal** — 12 AI providers, 137 commands, 31 tools, 28 skills + marketplace, self-update. AI-assisted code generation, security auditing, MCP protocol, and extensible skills — in a single CLI.
 

package/package.json

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

package/src/artifacts/manifest.ts

@@ -1,47 +1,95 @@
-import {
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  mkdirSync,
-  renameSync,
-  copyFileSync,
-  unlinkSync,
-} from 'node:fs'
+import { readFileSync, existsSync, mkdirSync, renameSync, copyFileSync, unlinkSync } from 'node:fs'
 import { join } from 'node:path'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 import type { ArtifactManifest, ArtifactEntry } from '../shared/types'
 
+function emptyManifest(): ArtifactManifest {
+  return { version: 1, artifacts: [] }
+}
+
 /**
  * Read the artifact manifest from disk, or return an empty one if it doesn't exist.
+ *
+ * An unreadable index also yields an empty manifest — the callers here only *show*
+ * artifacts (gallery, `/artifact list`), and showing none beats throwing at them.
+ * Writers must not go through this path: see `readManifestForUpdate`.
  */
 export function readManifest(dir: string): ArtifactManifest {
   const path = join(dir, 'index.json')
   if (!existsSync(path)) {
-    return { version: 1, artifacts: [] }
+    return emptyManifest()
   }
   try {
     return JSON.parse(readFileSync(path, 'utf-8'))
   } catch {
-    return { version: 1, artifacts: [] }
+    return emptyManifest()
+  }
+}
+
+/**
+ * Read the manifest for a caller that is about to write it back.
+ *
+ * The difference from `readManifest` is what happens when the file exists but does
+ * not parse: a writer must not treat that as "empty", because writing back an
+ * empty manifest replaces every other artifact's entry with nothing — the files
+ * stay on disk, but the gallery and `/artifact list` lose them. So the unreadable
+ * file is renamed aside (bytes kept, recoverable by hand) and reported, and the
+ * caller decides what to tell the user.
+ */
+function readManifestForUpdate(dir: string): {
+  manifest: ArtifactManifest
+  quarantined?: string
+} {
+  const path = join(dir, 'index.json')
+  if (!existsSync(path)) return { manifest: emptyManifest() }
+  try {
+    return { manifest: JSON.parse(readFileSync(path, 'utf-8')) }
+  } catch {
+    const quarantined = `${path}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`
+    // If this rename fails we let it throw: the alternative is overwriting the
+    // only copy of the index with a manifest built from nothing.
+    renameSync(path, quarantined)
+    return { manifest: emptyManifest(), quarantined }
   }
 }
 
 /**
  * Write the manifest to disk, creating parent directories as needed.
+ *
+ * Atomic: a crash mid-write used to leave a truncated `index.json`, which is
+ * exactly the corruption `readManifestForUpdate` then has to quarantine.
  */
 export function writeManifest(dir: string, manifest: ArtifactManifest): void {
   mkdirSync(dir, { recursive: true })
-  writeFileSync(join(dir, 'index.json'), JSON.stringify(manifest, null, 2), 'utf-8')
+  atomicWriteFileSync(join(dir, 'index.json'), JSON.stringify(manifest, null, 2), {
+    mode: 0o644,
+  })
 }
 
 /**
  * Add an entry to the manifest and persist it.
- * If an entry with the same name already exists, it is replaced.
+ *
+ * An entry is identified by `name` **and** `sessionId`, matching how the tool
+ * looks one up: the manifest is a single global `index.json` holding every
+ * session's artifacts, so keying on the name alone made two sessions publishing
+ * the same name overwrite each other's entry — the loser's file stayed on disk
+ * but vanished from the index.
+ *
+ * Returns the written manifest plus, when the previous index was unreadable, the
+ * path its bytes were moved to — the caller is expected to say so rather than
+ * let an artifact appear to publish cleanly over a lost index.
  */
-export function addToManifest(dir: string, entry: ArtifactEntry, port?: number): ArtifactManifest {
-  const manifest = readManifest(dir)
+export function addToManifest(
+  dir: string,
+  entry: ArtifactEntry,
+  port?: number,
+): { manifest: ArtifactManifest; quarantined?: string } {
+  const { manifest, quarantined } = readManifestForUpdate(dir)
   if (port !== undefined) manifest.port = port
 
-  const idx = manifest.artifacts.findIndex((a) => a.name === entry.name)
+  const idx = manifest.artifacts.findIndex(
+    (a) => a.name === entry.name && a.sessionId === entry.sessionId,
+  )
   if (idx >= 0) {
     manifest.artifacts[idx] = entry
   } else {
@@ -49,7 +97,7 @@ export function addToManifest(dir: string, entry: ArtifactEntry, port?: number):
   }
 
   writeManifest(dir, manifest)
-  return manifest
+  return { manifest, quarantined }
 }
 
 /**
@@ -64,31 +112,39 @@ export function getSessionArtifacts(dir: string, sessionId: string): ArtifactEnt
  * Archive an existing artifact file by renaming it with a version tag.
  * e.g. dashboard.html → dashboard.v1.html, dashboard.v1.html → dashboard.v2.html.
  *
- * Returns the version tag assigned to the archived file.
+ * Returns the version tag assigned to the archived file, or `undefined` when
+ * there was nothing to archive — in which case the manifest is left untouched.
+ *
+ * 「没归档就什么都不记」是刻意的：源文件找不到时照样推进版本号、往 `versions` 里
+ * 塞一个标签，等于在 manifest 里留一版磁盘上并不存在的版本。走到那条路并不难
+ * —— 条目按 name 找、文件按 `<session>/<name><ext>` 找，把同一个名字从 html 改
+ * 成 svg 就错开了。宁可少记一版，也不能记一版假的。
  */
-export function archiveVersion(dir: string, entry: ArtifactEntry): string {
-  const manifest = readManifest(dir)
-  const versionCount = (entry.versionCount || 1) + 1
+export function archiveVersion(dir: string, entry: ArtifactEntry): string | undefined {
   const ext = entry.type === 'svg' ? '.svg' : '.html'
-  const versionTag = `v${versionCount}`
-
-  // Rename the current file to a versioned copy
   const baseName = entry.name
   const currentPath = join(dir, entry.sessionId, `${baseName}${ext}`)
+
+  if (!existsSync(currentPath)) return undefined
+
+  const versionCount = (entry.versionCount || 1) + 1
+  const versionTag = `v${versionCount}`
   const archivedPath = join(dir, entry.sessionId, `${baseName}.${versionTag}${ext}`)
 
-  if (existsSync(currentPath)) {
-    try {
-      renameSync(currentPath, archivedPath)
-    } catch {
-      // If rename fails (e.g. cross-device), copy instead
-      copyFileSync(currentPath, archivedPath)
-      unlinkSync(currentPath)
-    }
+  try {
+    renameSync(currentPath, archivedPath)
+  } catch {
+    // If rename fails (e.g. cross-device), copy instead
+    copyFileSync(currentPath, archivedPath)
+    unlinkSync(currentPath)
   }
 
-  // Update manifest entry
-  const artifact = manifest.artifacts.find((a) => a.name === entry.name)
+  // Update manifest entry — keyed on name *and* session, like every other
+  // lookup here: a same-named artifact in another session is a different one.
+  const manifest = readManifest(dir)
+  const artifact = manifest.artifacts.find(
+    (a) => a.name === entry.name && a.sessionId === entry.sessionId,
+  )
   if (artifact) {
     const versions = artifact.versions || ['v1']
     versions.push(versionTag)

package/src/artifacts/paths.ts

@@ -0,0 +1,19 @@
+import { join } from 'node:path'
+import { ARTIFACTS_DIR, MIPHAM_DIR } from '../shared/constants'
+
+/**
+ * The one place that decides *where on disk an artifact lives*.
+ *
+ * Three sites need to agree on this: the Artifact tool (writes the file and the
+ * manifest), the ArtifactServer (serves files and builds the gallery from the
+ * manifest rooted here), and `/artifact list` (reads the manifest). Each of them
+ * computing the path itself is what produced the original bug: the tool wrote
+ * `<cwd>/artifacts/...` while the server served `<cwd>/.mipham/artifacts/...`,
+ * so the URL the tool reported was a guaranteed 404 — the two halves never met.
+ *
+ * Keeping them joined here means a change moves all three together; the guard
+ * test asserts the *behaviour* (the reported URL resolves), not the literal.
+ */
+export function artifactsRoot(cwd: string): string {
+  return join(cwd, MIPHAM_DIR, ARTIFACTS_DIR)
+}

package/src/artifacts/server.ts

@@ -1,9 +1,9 @@
 import { createServer, type Server } from 'node:http'
-import { createReadStream, existsSync, statSync } from 'node:fs'
+import type { Socket } from 'node:net'
+import { createReadStream, existsSync, readFileSync, statSync } from 'node:fs'
 import { join, normalize, extname } from 'node:path'
 import { ARTIFACT_ALLOWED_EXTENSIONS } from '../shared/constants'
 import { readManifest } from './manifest'
-import { ArtifactVersioning } from './versioning'
 import type { ArtifactEntry } from '../shared/types'
 import { getMetrics } from '../core/metrics'
 
@@ -29,12 +29,11 @@ export class ArtifactServer {
   private started = false
   private sseClients: SseClient[] = []
   private sseIdCounter = 0
-  private versioning: ArtifactVersioning
+  private sockets = new Set<Socket>()
 
   constructor(artifactsDir: string, preferredPort: number) {
     this.artifactsDir = artifactsDir
     this.port = preferredPort
-    this.versioning = new ArtifactVersioning(artifactsDir)
   }
 
   /** Notify all connected SSE clients to reload. Called after artifact changes. */
@@ -82,6 +81,12 @@ export class ArtifactServer {
       this.server = null
       this.started = false
     }
+
+    // `close()` only stops *accepting* — sockets already established (a browser's
+    // keep-alive, an SSE stream) stay open and keep being served, so a "stopped"
+    // server answers on the old port until the client hangs up. Destroy them.
+    for (const socket of this.sockets) socket.destroy()
+    this.sockets.clear()
   }
 
   getPort(): number {
@@ -114,6 +119,10 @@ export class ArtifactServer {
       const srv = createServer((req, res) => {
         this.handleRequest(req, res)
       })
+      srv.on('connection', (socket) => {
+        this.sockets.add(socket)
+        socket.on('close', () => this.sockets.delete(socket))
+      })
       srv.on('error', reject)
       srv.listen(port, () => {
         this.server = srv
@@ -216,8 +225,31 @@ export class ArtifactServer {
     })
   }
 
-  /** Per-artifact SSE stream: pushes content updates to connected browsers every 500ms. */
+  /**
+   * Per-artifact SSE stream: pushes the artifact's content to connected browsers
+   * every 500ms, so a page can follow an artifact the AI rewrites in place.
+   *
+   * Resolves the file through `resolveFile` — the same coordinate the gallery
+   * links to and the same traversal guard the static path uses — and 404s when no
+   * artifact carries that name, instead of holding a stream open on a file that
+   * does not exist.
+   */
   private handleNameSse(name: string, res: any): void {
+    const entry = readManifest(this.artifactsDir).artifacts.find((a) => a.name === name)
+    if (!entry) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' })
+      res.end(`No artifact named "${name}"`)
+      return
+    }
+
+    const ext = entry.type === 'svg' ? '.svg' : '.html'
+    const { filePath, error, status } = this.resolveFile(`/${entry.sessionId}/${entry.name}${ext}`)
+    if (error) {
+      res.writeHead(status || 404, { 'Content-Type': 'text/plain' })
+      res.end(error)
+      return
+    }
+
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
@@ -225,10 +257,18 @@ export class ArtifactServer {
       'Access-Control-Allow-Origin': '*',
     })
 
+    let last: string | null = null
     const interval = setInterval(() => {
-      const content = this.versioning.getVersion(name)
-      if (content) {
-        res.write(`data: ${JSON.stringify({ type: 'update', name, content })}\n\n`)
+      try {
+        const content = readFileSync(filePath, 'utf-8')
+        // Only on change: without this the stream re-sends the whole file every
+        // 500ms per client for as long as the tab stays open.
+        if (content !== last) {
+          last = content
+          res.write(`data: ${JSON.stringify({ type: 'update', name, content })}\n\n`)
+        }
+      } catch {
+        // Momentarily absent (archiving renames it) — skip this tick, try the next.
       }
     }, 500)
 

package/src/config/keys-manager.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { homedir } from 'node:os'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 import { saveProviderApiKey } from './loader'
 
 const MIPHAM_HOME = join(homedir(), '.mipham')
@@ -39,14 +40,12 @@ function loadKeys(): KeysData {
 
 function saveKeys(data: KeysData): void {
   mkdirSync(dirname(KEYS_FILE), { recursive: true })
-  const tmp = KEYS_FILE + '.tmp'
-  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
-  writeFileSync(KEYS_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
-  try {
-    chmodSync(KEYS_FILE, 0o600)
-  } catch {
-    // chmod on Windows is a no-op
-  }
+  // 从前这里「转了一半」：先写一个固定名的 `.tmp`，**然后不 rename、直接再写一遍
+  // 目标**。留在磁盘上的 `.tmp` 是废物，目标仍然非原子 —— 并发 `/keys rotate` 撞进
+  // 同一个临时名，或写到一半被打断，`loadKeys` 把不可解析的 JSON 吞成 `{}`
+  // （见上面的 catch）⇒ 全部轮换元数据静默消失。atomicWriteFileSync 自己写唯一名
+  // 临时文件再 rename，两者一起解决。
+  atomicWriteFileSync(KEYS_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
 }
 
 function daysSince(iso: string): number {

package/src/config/preferences.ts

@@ -5,9 +5,10 @@
  * NOT for config.yml settings — those belong in the YAML config system.
  * NOT for secrets — this file is plain JSON, not encrypted.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { readFileSync, existsSync, mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { atomicWriteFileSync } from '../shared/atomic-write'
 
 const PREFS_PATH = join(homedir(), '.mipham', 'preferences.json')
 
@@ -27,7 +28,9 @@ function writePrefs(prefs: Record<string, string>): void {
   try {
     const dir = join(homedir(), '.mipham')
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
-    writeFileSync(PREFS_PATH, JSON.stringify(prefs, null, 2), { mode: 0o600, encoding: 'utf-8' })
+    // 原子写：裸 writeFileSync 原地截断，崩在写中途就留下一份不可解析的文件，
+    // 而 readPrefs 把不可解析吞成「空」⇒ **全部**偏好静默消失（不是丢一项）。
+    atomicWriteFileSync(PREFS_PATH, JSON.stringify(prefs, null, 2), { mode: 0o600 })
   } catch {
     // best-effort; never crash because preferences failed to save
   }

package/src/core/cron-poller.ts

@@ -9,9 +9,22 @@ import { computeNextFire } from './cron'
 import type { CronJob } from '../tools/scheduling/cron'
 import { readAllJobs, writeJob, deleteJobFile } from '../tools/scheduling/cron'
 
-/** Jobs whose nextFire is at or before `now`. Pure — separated for tests. */
-export function findDueJobs(jobs: CronJob[], now: Date): CronJob[] {
-  return jobs.filter((j) => new Date(j.nextFire).getTime() <= now.getTime())
+/**
+ * Whether a job belongs to `cwd`.
+ *
+ * A job with no `cwd` is from a file written before jobs carried one; it matches
+ * anywhere so an existing user's schedule keeps firing instead of going silent.
+ * `cwd === undefined` means the caller did not ask for scoping at all (the pure
+ * helpers' existing callers), so nothing is filtered.
+ */
+function matchesCwd(job: CronJob, cwd?: string): boolean {
+  if (job.cwd === undefined || cwd === undefined) return true
+  return job.cwd === cwd
+}
+
+/** Jobs whose nextFire is at or before `now` — and which belong to `cwd`. */
+export function findDueJobs(jobs: CronJob[], now: Date, cwd?: string): CronJob[] {
+  return jobs.filter((j) => new Date(j.nextFire).getTime() <= now.getTime() && matchesCwd(j, cwd))
 }
 
 /** Next state after firing a due job: recurring advances; one-shot → null (delete). */
@@ -24,9 +37,20 @@ export function advanceJob(job: CronJob, now: Date): CronJob | null {
   }
 }
 
-/** Read due jobs, enqueue their prompts, and advance/delete. Returns fired count. */
-export function checkCronJobs(enqueue: (prompt: string) => void, now = new Date()): number {
-  const due = findDueJobs(readAllJobs(), now)
+/**
+ * Read due jobs, enqueue their prompts, and advance/delete. Returns fired count.
+ *
+ * `cwd` defaults to the process's working directory — the same source
+ * `ToolContext.cwd` comes from — because the enqueued prompt lands in *this*
+ * session and is executed here. Without the filter, a schedule created in one
+ * project would be run by whatever session happened to be open in another.
+ */
+export function checkCronJobs(
+  enqueue: (prompt: string) => void,
+  now = new Date(),
+  cwd = process.cwd(),
+): number {
+  const due = findDueJobs(readAllJobs(), now, cwd)
   for (const job of due) {
     enqueue(job.prompt)
     const next = advanceJob(job, now)

package/src/core/permission-rules.ts

@@ -1,3 +1,5 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import type { PermissionRuleEntry } from '../shared/index.ts'
 import { matchPath } from './credential-masker/matcher'
 
@@ -106,6 +108,9 @@ const PREFIX_COMMANDS = new Set([
   'stdbuf',
 ])
 
+/** `timeout` 的 duration 形态：`5` / `0.5` / `30s` / `2m` / `1h` / `1d`。 */
+const TIMEOUT_DURATION_RE = /^\d+(\.\d+)?[smhd]?$/
+
 /** Value-taking options of wrapper commands (consume the following token). */
 const PREFIX_VALUE_OPTIONS = new Set([
   '-u',
@@ -193,6 +198,76 @@ function stripQuotes(s: string): string {
   return s
 }
 
+/** Shell 结构符号：分组与取反 —— 它们自身不是命令，紧跟其后的是。 */
+const LEADING_SHELL_PUNCT = new Set(['(', '{', '!'])
+
+/** Shell 关键字：其后才是真正的命令（`do rm -rf x` 执行的命令是 `rm`）。 */
+const LEADING_SHELL_KEYWORDS = new Set([
+  'do',
+  'then',
+  'else',
+  'elif',
+  'if',
+  'while',
+  'until',
+  'for',
+  'case',
+  'time',
+  'coproc',
+])
+
+/** 一条前导赋值：`NAME=value`（name 是合法标识符，`=` 前无引号）。 */
+const LEADING_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/
+
+/**
+ * 剥掉一段 shell 片段**前导**的噪声 token，露出真正的基命令。
+ *
+ * 为什么需要它：`Bash(rm *)` / `Read(secret)` 这类规则要匹配的是**命令本身**，
+ * 而 shell 允许在命令前放赋值（`IFS=x rm -rf x`）、分组符号（`( rm -rf x )`）、
+ * 关键字（`for …; do rm -rf x; done`）。这些都不改变「执行了什么命令」，却足以
+ * 让匹配器看不到 `rm`，于是 deny 规则被一个空格级的改写绕过。
+ *
+ * 只剥前导、可反复剥（`FOO=1 ! rm …`）。剥多了一律是过匹配，而 deny 规则的过
+ * 匹配是安全方向。关键字自己的裸 flag 也一并剥掉（`time -p rm …` 里的 `-p`），
+ * 否则关键字被剥走后会剩下 `-p rm …`，仍然看不见 `rm`。
+ *
+ * 不剥尾随符号（`rm -rf x )` 里的 `)`）：`wildcardMatch` 的 `*` 已经吃掉它。
+ */
+export function stripLeadingShellNoise(segment: string): string {
+  let tokens = segment.trim().split(/\s+/).filter(Boolean)
+  let stripped = false
+  let skipFlags = false
+  for (;;) {
+    const head = tokens[0]
+    if (!head) break
+    if (skipFlags && /^--?[A-Za-z]/.test(head)) {
+      tokens = tokens.slice(1)
+      stripped = true
+      continue
+    }
+    skipFlags = false
+    const bare = head.replace(/^[({!]+/, '') // `(!` 这类连写
+    if (bare !== head) {
+      tokens = bare ? [bare, ...tokens.slice(1)] : tokens.slice(1)
+      stripped = true
+      continue
+    }
+    if (LEADING_SHELL_PUNCT.has(head) || LEADING_ASSIGNMENT_RE.test(head)) {
+      tokens = tokens.slice(1)
+      stripped = true
+      continue
+    }
+    if (LEADING_SHELL_KEYWORDS.has(head)) {
+      tokens = tokens.slice(1)
+      stripped = true
+      skipFlags = true // `time -p rm …` —— 关键字自己的裸 flag 不是命令
+      continue
+    }
+    break
+  }
+  return stripped ? tokens.join(' ') : segment
+}
+
 function uniq(items: string[]): string[] {
   return [...new Set(items)]
 }
@@ -203,6 +278,29 @@ export interface BashFileAccess {
   write: string[]
 }
 
+/**
+ * 展开候选路径里**已知**的变量：前导 `~`、`$HOME`/`${HOME}`。
+ *
+ * 为什么需要：规则里写的是绝对路径（`Read(/Users/me/.ssh/id_rsa)`），而用户敲的
+ * 是同一个文件的另一种拼法（`cat ~/.ssh/id_rsa`）—— 不展开即等于放行。展开后
+ * 两种拼法落到同一个字符串上，绝对路径形与路径通配形（如「.ssh 下任意文件」）
+ * 规则都能命中。
+ *
+ * **只展开 HOME**。`$FOO` 这类未知变量原样保留：展开它需要求值环境，静默展开成
+ * 空串会让 `/x/$FOO/y` 变成 `/x//y` —— 那是**新增**一个漏判方向，比不展开更坏。
+ * `$PWD` 同理需要 cwd，而 `matchBashRule` 的调用点拿不到 cwd，故未覆盖。这两条
+ * 都是本函数已知的边界，不是遗漏。
+ *
+ * `~` 只在**开头**展开（`a/~/b` 里的 `~` 是普通字符，shell 也不展开它）。
+ */
+export function expandKnownPathVars(p: string): string {
+  const home = homedir() // 每次取，不在模块加载时绑定（HOME 可能被测试隔离改写）
+  let out = p
+  if (out === '~') out = home
+  else if (out.startsWith('~/')) out = join(home, out.slice(2))
+  return out.replace(/\$\{?HOME\}?/g, home)
+}
+
 /**
  * Extract the file paths a Bash command reads or writes, so Read()/Write()/
  * Edit() deny rules also apply to Bash (not just the Read/Write/Edit tools).
@@ -231,7 +329,9 @@ export function extractBashFileAccess(command: string): BashFileAccess {
   //    recursing into `$(...)` / backtick substitutions.
   scanReaderWriterCommands(command, read, write)
 
-  return { read: uniq(read), write: uniq(write) }
+  // 展开放在出口这一处，而不是每个 push 点 —— 重定向与读/写命令、以及它们的
+  // 递归内层都汇进这两个数组，一处展开即全覆盖。
+  return { read: uniq(read.map(expandKnownPathVars)), write: uniq(write.map(expandKnownPathVars)) }
 }
 
 /** Extract the inner commands of `$(...)` and backtick substitutions. */
@@ -244,6 +344,12 @@ function extractSubstitutions(command: string): string[] {
   while ((m = dollarParen.exec(command)) !== null) inners.push(m[1]!)
   const backtick = /`([^`]*)`/g
   while ((m = backtick.exec(command)) !== null) inners.push(m[1]!)
+  // 进程替换 `<(cmd)` / `>(cmd)`：`cat <(cat secret)` 里读 secret 的是里层的
+  // `cat`，外层只是把它的 stdout 当成一个文件名。参数排除 `<>` 是因为
+  // `<(cat secret)` 的捕获若允许 `>`，遇到 `>(...)` 形态会被提前截断；非嵌套组
+  // 由调用方的递归处理。
+  const procSub = /[<>]\(([^()<>]*)\)/g
+  while ((m = procSub.exec(command)) !== null) inners.push(m[1]!)
   return inners
 }
 
@@ -261,6 +367,12 @@ function flattenCommand(command: string, depth = 0): string[] {
     out.push(seg)
     const stripped = stripPrefixCommand(seg)
     if (stripped !== seg) out.push(stripped)
+    // 剥掉前导噪声后的形态也要参与匹配：`IFS=x rm -rf x` / `( rm -rf x )` /
+    // `for …; do rm -rf x; done` 执行的仍是 `rm`，规则必须看得见它。同一个函数
+    // 也被 scanReaderWriterCommands 用（Read/Write/Edit 桥接那条路径）—— 两条
+    // 路径共用一份归一化，只接一条就是只修一半。
+    const denoised = stripLeadingShellNoise(seg)
+    if (denoised !== seg) out.push(denoised)
     for (const inner of extractSubstitutions(seg)) {
       out.push(...flattenCommand(inner, depth + 1))
     }
@@ -303,7 +415,10 @@ function effectiveCommand(tokens: string[]): {
     if (name === 'env') {
       while (i < tokens.length && tokens[i]!.includes('=')) i++ // `VAR=value` assignments
     }
-    if (name === 'timeout') i++ // positional duration
+    // `timeout` 的位置参数是 duration，**不是**必然存在：`timeout 5 cmd` 有，
+    // `timeout --preserve-status cmd` 没有。无条件 `i++` 会把后者真正的命令
+    // （`cat`）当成 duration 吃掉，基命令退化成它的第一个参数。
+    if (name === 'timeout' && i < tokens.length && TIMEOUT_DURATION_RE.test(tokens[i]!)) i++
     // `eval`'s remaining arguments are themselves a command line, and must be
     // captured here rather than via the SHELL_COMMANDS branch below: `eval "cat
     // secret"` tokenizes to ['eval', '"cat', 'secret"'], so the base degrades to
@@ -388,7 +503,10 @@ function scanReaderWriterCommands(
   depth = 0,
 ): void {
   for (const seg of splitShellSegments(command)) {
-    const tokens = seg.split(/\s+/).filter(Boolean)
+    // 先剥前导噪声再 tokenize：`IFS=x cat secret` / `! cat secret` /
+    // `time -p cat secret` 读的是同一个文件，Read() 规则必须看得见 `cat`。
+    // 与 flattenCommand 共用 stripLeadingShellNoise —— 两条路径一份归一化。
+    const tokens = stripLeadingShellNoise(seg).split(/\s+/).filter(Boolean)
     if (tokens.length > 0) {
       const { base, args, payload } = effectiveCommand(tokens)
       if (READER_COMMANDS.has(base)) {
@@ -418,6 +536,13 @@ function scanReaderWriterCommands(
   }
 }
 
+/**
+ * `matchBashRule` 真正会按参数匹配工具名的集合。**与 matchBashRule 的分支一一
+ * 对应** —— 那里 `return false` 的工具，参数化规则在 validateRulePattern 里必须
+ * 被拒（否则规则永远不命中，是静默空防护）。改一边必须改另一边。
+ */
+const PARAMETERISED_TOOLS = new Set(['Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob'])
+
 // Match a tool(parameter) rule against an actual tool call.
 //
 // Pattern formats:
@@ -500,6 +625,10 @@ export function wildcardMatch(pattern: string, input: string): boolean {
  * `Bash()`) is silently dead today — this returns a human-readable reason so
  * the caller can report it as an invalid setting instead of ignoring it.
  *
+ * 校验的是**结构 + 工具名**（后者见 PARAMETERISED_TOOLS）。**不**校验子模式本身
+ * 能否匹配任何东西 —— `Bash(zzz *)` 合法、装得上、只是不会命中，那是用户自己的
+ * 选择，不是配置错误。
+ *
  * Returns null when the pattern is valid, or a reason string when malformed.
  */
 export function validateRulePattern(pattern: string): string | null {
@@ -510,9 +639,16 @@ export function validateRulePattern(pattern: string): string | null {
     // Empty parameter: `Bash()` or `Bash( )`
     if (/\(\s*\)$/.test(pattern)) return 'empty parameter'
     // Must be exactly `ToolName(param)` with nothing before or after.
-    if (!/^(\w+)\((.+)\)$/.test(pattern)) {
+    const shape = pattern.match(/^(\w+)\((.+)\)$/)
+    if (!shape) {
       return 'unexpected text after the closing parenthesis'
     }
+    // 工具名必须落在 matchBashRule 真正会按参数匹配的那一集合里，否则这条规则是
+    // **静默空防护**：语法合法、装得上、永远不命中，而用户以为配了保护。
+    const tool = shape[1]!
+    if (!PARAMETERISED_TOOLS.has(tool)) {
+      return `parameterised rules are not supported for tool "${tool}" (it would never match)`
+    }
     return null
   }