@miphamai/cli 0.81.6 → 0.81.8

package/src/commands/project.ts

@@ -8,6 +8,7 @@
 import type { CommandHandler, CommandContext, CommandResult } from '../ui/commands.js'
 import { getWorkspaceTrust } from '../core/workspace-trust'
 import { atomicWriteFileSync } from '../shared/atomic-write'
+import { CLOUD_PROVIDERS } from '../config/wizard-config'
 import { homedir } from 'node:os'
 
 export {
@@ -21,6 +22,18 @@ export {
   trustCmd,
 }
 
+/**
+ * provider id → 环境变量名，例如 `minimax-global` → `MINIMAX_GLOBAL_API_KEY`。
+ *
+ * 非字母数字字符必须归一为 `_`：生成的模板里写着 `export <名字>=...`，
+ * 而带连字符的 `export MINIMAX-GLOBAL_API_KEY=…` 是 shell 语法错误
+ * （`openai-compat.ts` 的 `${VAR}` 解析器另一条 `$VAR` 分支也只认
+ * `[A-Z_][A-Z0-9_]*`）。`/init` 过去只输出无连字符的 mipham，所以这条一直不可达。
+ */
+function envVarFor(providerId: string): string {
+  return `${providerId.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_API_KEY`
+}
+
 const initCmd: CommandHandler = async (ctx) => {
   const { existsSync, mkdirSync } = await import('node:fs')
   const { join } = await import('node:path')
@@ -33,8 +46,11 @@ const initCmd: CommandHandler = async (ctx) => {
   if (!existsSync(userConfigPath)) {
     mkdirSync(join(home, '.mipham'), { recursive: true })
 
-    const activeProviders = ctx.config.providers.filter((p) => p.status === 'active')
-    const providerYaml = activeProviders
+    // 生成物必须来自随包发布的清单，不能来自 ctx.config —— 后者的 status 表达
+    // 的是「用户停用了哪家」这个**运行时**状态，而 12 家里只有 mipham 声明了它
+    // （其余 status 全在 model 层），拿它筛会恒得 1 家。
+    const presetProviders = CLOUD_PROVIDERS
+    const providerYaml = presetProviders
       .map((p) => {
         const tips: Record<string, string> = {
           anthropic: '# Get key: https://console.anthropic.com/',
@@ -51,7 +67,7 @@ const initCmd: CommandHandler = async (ctx) => {
         return `  ${comment}
   - id: ${p.id}
     name: "${p.name}"${baseUrlLine}
-    apiKey: "\${${p.id.toUpperCase()}_API_KEY}"`
+    apiKey: "\${${envVarFor(p.id)}}"`
       })
       .join('\n\n')
 
@@ -75,7 +91,7 @@ defaultProvider: ${ctx.providerId}
 defaultModel: ${ctx.modelId}
 permission: ask
 
-# ── Providers (${activeProviders.length} pre-configured — just add your API keys) ──
+# ── Providers (${presetProviders.length} pre-configured — just add your API keys) ──
 providers:
 ${providerYaml}
 `
@@ -84,14 +100,14 @@ ${providerYaml}
     return {
       content: `✅ Mipham Code initialized!
 
-Created: ~/.mipham/config.yml (${activeProviders.length} providers pre-configured)
+Created: ~/.mipham/config.yml (${presetProviders.length} providers pre-configured)
 
 Next steps:
   1. Edit ~/.mipham/config.yml — replace API key placeholders with your real keys
   2. Run mipham to start
 
 Providers configured:
-${activeProviders.map((p) => `  • ${p.name} — ${p.id.toUpperCase()}_API_KEY`).join('\n')}
+${presetProviders.map((p) => `  • ${p.name} — ${envVarFor(p.id)}`).join('\n')}
 
 Tip: /setup for the full 6-step wizard.`,
     }
@@ -105,10 +121,64 @@ Run /setup for the full wizard, or /config to view current settings.`,
   }
 }
 
-const permissionsCmd: CommandHandler = (ctx) => {
+const permissionsCmd: CommandHandler = async (ctx, args) => {
   const c = ctx.engine.getContext()
   const msgs = c.getMessages()
 
+  // ── Rule persistence: allow/deny/remove <rule> [--user] ──
+  const positional = args.filter((a) => !a.startsWith('--'))
+  const scope: 'project' | 'user' = args.includes('--user') ? 'user' : 'project'
+  const verb = positional[0]
+  const rule = positional[1]
+
+  if (verb === 'allow' || verb === 'deny' || verb === 'remove') {
+    const { validateRulePattern } = await import('../core/permission-rules')
+    const { addSettingsRule, removeSettingsRule, settingsPathFor } =
+      await import('../config/loader')
+
+    // A rule that can't match is worse than no rule: it reads as protection
+    // that isn't there. Validate before writing.
+    const invalid = validateRulePattern(rule ?? '')
+    const usage =
+      `Usage: /permissions <allow|deny|remove> <rule> [--user]\n\n` +
+      `  rule   Tool pattern — "Bash" or "Bash(npm test)".\n` +
+      `  --user Write to ~/.mipham/settings.json instead of .mipham/settings.json.`
+
+    if (verb !== 'remove' && !rule) {
+      return { content: `Missing rule.\n\n${usage}` }
+    }
+    if (invalid && verb !== 'remove') {
+      return { content: `Invalid rule "${rule}": ${invalid}.\n\n${usage}` }
+    }
+
+    const perm = ctx.engine.getPermission()
+
+    if (verb === 'remove') {
+      const removed = removeSettingsRule(rule!, scope)
+      if (!removed) {
+        return { content: `No rule "${rule}" in ${settingsPathFor(scope)}.` }
+      }
+      perm.removeRule(rule!)
+      return {
+        content: `Removed from ${removed.path}\n\npermissions.${removed.key}:\n  ${rule}`,
+      }
+    }
+
+    const path = addSettingsRule(verb, rule!, scope)
+    if (verb === 'allow') perm.allow(rule!)
+    else perm.deny(rule!)
+    return {
+      content:
+        `Added to ${path}\n\n` +
+        `permissions.${verb}:\n  ${rule}\n\n` +
+        `This rule persists across sessions and applies from now on.`,
+    }
+  }
+
+  const settings = await import('../config/loader').then((m) => m.loadSettingsJson())
+  const ruleLines = (label: string, rules: string[]) =>
+    rules.length > 0 ? `  ${label}\n${rules.map((r) => `    ${r}`).join('\n')}` : `  no ${label}`
+
   return {
     content: `─ Permission Settings ─
 
@@ -125,6 +195,15 @@ Switch mode with Shift+Tab. Modes (least → most permissive):
 To let Bash run without asking: press Shift+Tab until the status line shows
 "acceptEdits", then send your message again.
 
+Persisted rules (settings.json):
+${ruleLines('allow', settings.permissions.allow)}
+${ruleLines('deny', settings.permissions.deny)}
+
+Persist a rule with:
+  /permissions allow "Bash(npm test)"     → .mipham/settings.json
+  /permissions deny  "Bash(rm *)" --user  → ~/.mipham/settings.json
+  /permissions remove "Bash(npm test)"
+
 Current directory permissions:
   CWD:      ${process.cwd()}
 
@@ -384,8 +463,9 @@ async function setupStep1(ctx: CommandContext): Promise<CommandResult> {
   if (!existsSync(configPath)) {
     // Generate a user-friendly config with all providers pre-populated.
     // Users just need to replace the API key placeholders with their real keys.
-    const activeProviders = ctx.config.providers.filter((p) => p.status === 'active')
-    const providerYaml = activeProviders
+    // 同 /init：清单来自 CLOUD_PROVIDERS，与运行时 status 无关（见上方注释）。
+    const presetProviders = CLOUD_PROVIDERS
+    const providerYaml = presetProviders
       .map((p) => {
         const comment =
           p.id === 'anthropic'
@@ -409,12 +489,12 @@ async function setupStep1(ctx: CommandContext): Promise<CommandResult> {
         return `  ${comment}
   - id: ${p.id}
     name: "${p.name}"${baseUrlLine}
-    apiKey: "\${${p.id.toUpperCase()}_API_KEY}"`
+    apiKey: "\${${envVarFor(p.id)}}"`
       })
       .join('\n\n')
 
     const defaultConfig = `# Mipham Code — User Configuration
-# Location: ~/.mipham/config.yml
+# Location: <project>/.mipham/config.yml  (project-level; ~/.mipham/config.yml is the user-level file — both are read)
 # Docs:     https://mipham.ai/code/docs/config
 #
 # ═══ Quick Start ═══
@@ -433,7 +513,7 @@ defaultProvider: ${ctx.providerId}
 defaultModel: ${ctx.modelId}
 permission: ask
 
-# ── Providers (8 configured, just add your API keys) ──
+# ── Providers (${presetProviders.length} pre-configured — just add your API keys) ──
 providers:
 ${providerYaml}
 `

package/src/config/keys-manager.ts

@@ -1,10 +1,11 @@
 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_DIR = join(homedir(), '.mipham')
-const KEYS_FILE = join(MIPHAM_DIR, 'keys.json')
+const MIPHAM_HOME = join(homedir(), '.mipham')
+const KEYS_FILE = join(MIPHAM_HOME, 'keys.json')
 const EXPIRY_DAYS = 90
 
 export interface KeyEntry {
@@ -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 {
@@ -84,7 +83,7 @@ export class KeyManager {
 
     // Backup old entry if it exists
     if (existing) {
-      const backupDir = join(MIPHAM_DIR, 'keys')
+      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 })

package/src/config/loader.ts

@@ -7,7 +7,7 @@ import {
   unlinkSync,
   chmodSync,
 } from 'node:fs'
-import { join } from 'node:path'
+import { join, dirname } from 'node:path'
 import { homedir } from 'node:os'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { atomicWriteFileSync } from '../shared/atomic-write'
@@ -271,6 +271,87 @@ export function loadSettingsJson(cwd: string = process.cwd()): SettingsJson {
   return { hooks, permissions }
 }
 
+/** Which settings.json a permission rule is persisted to. */
+export type SettingsScope = 'project' | 'user'
+
+export function settingsPathFor(scope: SettingsScope, cwd: string = process.cwd()): string {
+  return scope === 'user'
+    ? join(MIPHAM_HOME, 'settings.json')
+    : join(cwd, '.mipham', 'settings.json')
+}
+
+/**
+ * Read a settings.json as a plain object, preserving any key we don't model
+ * (hooks, and anything a future version adds). A malformed file is an error,
+ * 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 {}
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    throw new Error(`${path} is not valid JSON. Fix or remove it, then retry.`)
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${path} does not contain a JSON object. Fix or remove it, then retry.`)
+  }
+  return parsed as Record<string, unknown>
+}
+
+export function writeSettingsDoc(path: string, doc: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true })
+  atomicWriteFileSync(path, JSON.stringify(doc, null, 2) + '\n')
+}
+
+/**
+ * Persist one rule into `permissions.<key>` of a scope's settings.json.
+ * Idempotent: re-adding an existing rule leaves the file unchanged.
+ * Returns the path written.
+ */
+export function addSettingsRule(
+  key: 'allow' | 'deny',
+  rule: string,
+  scope: SettingsScope = 'project',
+  cwd: string = process.cwd(),
+): string {
+  const path = settingsPathFor(scope, cwd)
+  const doc = readSettingsDoc(path)
+  const perms = (doc.permissions ?? {}) as Record<string, unknown>
+  const list = Array.isArray(perms[key]) ? perms[key] : []
+  const strings = (list as unknown[]).filter((r): r is string => typeof r === 'string')
+  if (!strings.includes(rule)) strings.push(rule)
+  perms[key] = strings
+  doc.permissions = perms
+  writeSettingsDoc(path, doc)
+  return path
+}
+
+/**
+ * Remove a rule from whichever `permissions` list holds it. Returns the path
+ * and key it was removed from, or null when the rule was not present.
+ */
+export function removeSettingsRule(
+  rule: string,
+  scope: SettingsScope = 'project',
+  cwd: string = process.cwd(),
+): { path: string; key: 'allow' | 'deny' } | null {
+  const path = settingsPathFor(scope, cwd)
+  const doc = readSettingsDoc(path)
+  const perms = (doc.permissions ?? {}) as Record<string, unknown>
+
+  for (const key of ['allow', 'deny'] as const) {
+    if (!Array.isArray(perms[key])) continue
+    const list = (perms[key] as unknown[]).filter((r): r is string => typeof r === 'string')
+    if (!list.includes(rule)) continue
+    perms[key] = list.filter((r) => r !== rule)
+    doc.permissions = perms
+    writeSettingsDoc(path, doc)
+    return { path, key }
+  }
+  return null
+}
+
 export function loadConfig(cwd: string = process.cwd()): MiphamConfig {
   const configPath = join(cwd, '.mipham', 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')

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/context.ts

@@ -146,7 +146,15 @@ export class ContextManager {
     const content = result.success ? result.content : result.error || result.content
     const msg: Message = {
       role: 'user',
-      content: [{ type: 'tool_result', tool_use_id: toolUseId, content }],
+      content: [
+        {
+          type: 'tool_result',
+          tool_use_id: toolUseId,
+          content,
+          // 成功不写该键 —— 与 session-log.deriveMessages 的展平式对称（保字节级互逆）
+          ...(result.success ? {} : { is_error: true }),
+        },
+      ],
     }
     this.messages.push(msg)
     this.estimatedTokens += this.estimateTokens(JSON.stringify(msg.content))
@@ -369,7 +377,7 @@ export class ContextManager {
     if (usage > microThreshold) {
       this.compressionPending = true
       // Schedule microcompact asynchronously (fire-and-forget)
-      Promise.resolve().then(() => {
+      void Promise.resolve().then(() => {
         this.runMicrocompact()
         this.compressionPending = false
       })

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/engine.ts

@@ -701,6 +701,7 @@ export class QueryEngine {
         type: 'tool_result',
         tool_use_id: toolUse.id,
         content: result.success ? result.content : result.error || result.content,
+        isError: !result.success,
       }
 
       // Collect tool call record for CRSI auto-reflection
@@ -1040,7 +1041,10 @@ export class QueryEngine {
         yield {
           type: 'tool_result',
           tool_use_id: toolUse.id,
-          content: result.content,
+          // 失败结果的 `content` 是空串（错误在 `error` 里，见 executeTool 的拒绝分支）
+          // —— 直接发 `content` 会让模型收到一个**空** tool_result，错误文案整个丢失。
+          content: result.success ? result.content : result.error || result.content,
+          isError: !result.success,
         }
 
         // DeepSeek V4 thinking mode requires reasoning_content on every assistant message
@@ -1333,7 +1337,15 @@ export class QueryEngine {
     return this.llm
   }
 
-  /** 注入 LLM 适配缝（换 chat 实现）。 */
+  /**
+   * 注入 LLM 适配缝（换 chat 实现）。
+   *
+   * 不变量：**缝 = 与 `registry` 不同的对象**。`chatWithFallback` 靠
+   * `this.llm !== this.registry` 判定「这个缝是否拥有整个 chat 流程」——
+   * 而生产路径注入的恰恰就是 registry 本身（`providers/llm.ts` 的 `mountLlm`
+   * 是原样 `provide(LLM_KEY, llm)`，`index.tsx` 把 `registry` 传了进去）。
+   * 若改成「非空即缝」，provider 回退分支就永远走不到，回退只活在测试里。
+   */
   setLlm(llm: Llm): void {
     this.llm = llm
   }
@@ -1384,8 +1396,11 @@ export class QueryEngine {
     }
 
     // ── Fallback: configured default provider, once ──
-    // 若已注入 Llm 缝，缝拥有整个 chat 流程——不回退（避免切 registry 状态 + 二次调用）
-    if (this.llm) {
+    // 若注入了**异己**的 Llm 缝，缝拥有整个 chat 流程——不回退（避免切 registry 状态 + 二次调用）。
+    // `!== this.registry` 不可省：生产路径注入的正是 registry 自己（`index.tsx` →
+    // `mountLlm(vajraContext, registry)` → `setLlm`），按「非空即缝」判定会让本分支
+    // 在生产恒不可达，而测试里构造引擎时不注入缝 ⇒ 套件全绿也发现不了。
+    if (this.llm && this.llm !== this.registry) {
       yield { type: 'error', error: failure }
       return
     }

package/src/core/metrics.ts

@@ -278,6 +278,9 @@ export class MetricsRegistry {
   /** Tool call counter, labelled by tool_name.  Callers use .inc({tool_name}). */
   readonly toolCalls: Counter
 
+  /** Slash-command counter, labelled by command_name. Callers use .inc({command_name}). */
+  readonly commandCalls: Counter
+
   /** Model API request counter, labelled by provider and model. */
   readonly modelRequests: Counter
 
@@ -308,6 +311,11 @@ export class MetricsRegistry {
 
     this.toolCalls = this.counter('mipham_code_tool_calls_total', 'Number of tool invocations')
 
+    this.commandCalls = this.counter(
+      'mipham_code_command_calls_total',
+      'Number of slash-command invocations',
+    )
+
     this.modelRequests = this.counter(
       'mipham_code_model_requests_total',
       'Number of model API requests',

package/src/core/paths.ts

@@ -0,0 +1,79 @@
+/**
+ * 项目内数据目录的路径单一真源。
+ *
+ * 写入一律落在 `.mipham/`（我们自己的目录）；`.claude/` 只保留**只读兼容** ——
+ * 早期版本把 worktree 建在 `.claude/worktrees/` 下，那些工作树今天仍要可列举、
+ * 可退出、可隔离。因此隔离判据必须同时认两个前缀：只认新前缀会让旧工作树
+ * 突然失去隔离保护（隔离度只许增不许减）。
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { MIPHAM_DIR } from '../shared/constants.ts'
+
+/** 只读兼容目录名。 */
+export const LEGACY_CLAUDE_DIR = '.claude'
+
+/**
+ * worktree 的识别标记（含结尾斜杠），新前缀在前。
+ * 用于从 `cwd` 反推 worktree 所属的项目根。
+ */
+export const WORKTREE_MARKERS = [
+  `${MIPHAM_DIR}/worktrees/`,
+  `${LEGACY_CLAUDE_DIR}/worktrees/`,
+] as const
+
+/** 新建 worktree 的根目录（绝对路径）。 */
+export function worktreeRoot(cwd: string): string {
+  return join(cwd, MIPHAM_DIR, 'worktrees')
+}
+
+/** 历史与当前的全部 worktree 根目录，写入根在前。 */
+export function worktreeRoots(cwd: string): string[] {
+  return [worktreeRoot(cwd), join(cwd, LEGACY_CLAUDE_DIR, 'worktrees')]
+}
+
+/**
+ * 在 `cwd` 中定位 worktree 标记，返回项目根与命中的标记。
+ * 不在任何 worktree 内时返回 null。
+ */
+/**
+ * Locate the project root by looking for a worktree marker in `cwd`.
+ *
+ * The returned `root` has no trailing separator: callers compose it as
+ * `root + '/'` for a prefix compare, and a trailing slash there would make
+ * the pattern `${root}//` match nothing.
+ */
+export function findWorktreeMarker(cwd: string): { root: string; marker: string } | null {
+  for (const marker of WORKTREE_MARKERS) {
+    const index = cwd.indexOf(marker)
+    if (index !== -1) return { root: cwd.substring(0, index).replace(/\/+$/, ''), marker }
+  }
+  return null
+}
+
+/**
+ * 新建 workflow 脚本的目录（绝对路径）。与 worktree 同理：写入落在 `.mipham/`。
+ *
+ * 注意别与**运行产物**目录混淆：`~/.mipham/workflows/<runId>/`（见
+ * `workflow/journal.ts`）同名但不同义，装的是 journal 与转录。两者靠「非递归
+ * readdir + 只收 .js」区分，属巧合而非设计，故本函数绝不返回那个根。
+ */
+export function workflowScriptDir(cwd: string): string {
+  return join(cwd, MIPHAM_DIR, 'workflows')
+}
+
+/**
+ * 全部可读的 workflow 脚本目录，写入根在前。
+ *
+ * 读侧必须同时认新旧前缀，否则升级后第一次 `/workflow save` 会失败 ——
+ * 上一次运行的 `.last-run.json` 还在旧目录里。用户级旧前缀也保留在列，
+ * 但**没有**对应的 `~/.mipham/workflows` 用户级脚本根：那里是运行产物的地盘。
+ */
+export function workflowScriptDirs(cwd: string): string[] {
+  return [
+    workflowScriptDir(cwd),
+    join(cwd, LEGACY_CLAUDE_DIR, 'workflows'),
+    join(homedir(), LEGACY_CLAUDE_DIR, 'workflows'),
+  ]
+}