@zhushanwen/pi-plan 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-plan",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Lightweight plan mode for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -25,7 +25,7 @@
     "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27",
     "@earendil-works/pi-ai": "^1.0.0",
-    "@zhushanwen/pi-goal": "0.14.11"
+    "@zhushanwen/pi-goal": "0.14.13"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {
@@ -50,11 +50,11 @@
     "templates/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.18.0",
+    "@zhushanwen/extension-protocol": "0.20.0",
     "@zhushanwen/pi-exec-skills": "0.2.1",
-    "@zhushanwen/pi-ext-guards": "0.4.3",
+    "@zhushanwen/pi-ext-guards": "0.4.4",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-llm-shared": "0.11.1",
+    "@zhushanwen/pi-llm-shared": "0.11.2",
     "@zhushanwen/pi-session-path": "0.1.0"
   },
   "scripts": {

package/src/__tests__/command.test.ts

@@ -182,10 +182,9 @@ describe("registerPlanCommand", () => {
   it("enters plan mode with slugified path", async () => {
     await handler("Implement User Auth", ctx);
 
-    expect(fs.mkdirSync).toHaveBeenCalledWith(
-      "/tmp/test-project/.tmp/plans/implement-user-auth",
-      { recursive: true },
-    );
+    // 目录落盘（原子唯一性）：plansRoot 父目录 recursive 建立 + 候选目录非 recursive mkdir
+    expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans", { recursive: true });
+    expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans/implement-user-auth");
     expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
     expect(pi.sendMessage).toHaveBeenCalledWith(...planContextMessage(expect.stringContaining("[PLAN MODE]")));
     expect(pi.sendMessage).toHaveBeenCalledWith(...planContextMessage(expect.stringContaining("Implement User Auth")));
@@ -207,20 +206,14 @@ describe("registerPlanCommand", () => {
   it("handles special characters in requirement for slug", async () => {
     await handler("Fix bug #123: 中文标题!", ctx);
 
-    expect(fs.mkdirSync).toHaveBeenCalledWith(
-      expect.stringContaining("/.tmp/plans/fix-bug-123"),
-      { recursive: true },
-    );
+    expect(fs.mkdirSync).toHaveBeenCalledWith(expect.stringContaining("/.tmp/plans/fix-bug-123"));
   });
 
   it("uses 'untitled' slug when no args", async () => {
     // No existing plans (readdirSync returns [])
     await handler("", ctx);
 
-    expect(fs.mkdirSync).toHaveBeenCalledWith(
-      "/tmp/test-project/.tmp/plans/untitled",
-      { recursive: true },
-    );
+    expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans/untitled");
   });
 
   it("超长 requirement 进入：state/entry 按 64KB 封顶，提示词仍携带全文（MF-1-3）", async () => {

package/src/__tests__/enter.test.ts

@@ -92,6 +92,9 @@ function setup(skillCommands: Array<{ name: string; path: string }> = []) {
 describe("plan(action='enter') — agent 自助进入（plan-mode-agent-enter U1）", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    // clearAllMocks 不清 mockImplementation——mkdirSync 的 EEXIST/EACCES 抛错实现
+    // 会跨用例泄漏，显式 reset 回无实现桩
+    vi.mocked(fs.mkdirSync).mockReset();
   });
 
   it("idle 进入：收工具到白名单 + 持久化 isActive=true + tool result 携带只读纪律提示词", async () => {
@@ -102,11 +105,10 @@ describe("plan(action='enter') — agent 自助进入（plan-mode-agent-enter U1
     expect(pi.setActiveTools).toHaveBeenCalledWith(PLAN_MODE_TOOLS);
     // 状态持久化 isActive=true（投影链驱动 GUI 显形的锚点）
     expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", expect.objectContaining({ isActive: true }));
-    // plan 目录创建（.tmp/plans/<slug>，slug 由 requirement 派生）
-    expect(fs.mkdirSync).toHaveBeenCalledWith(
-      expect.stringMatching(/\.tmp[/\\]plans[/\\]/),
-      expect.objectContaining({ recursive: true }),
-    );
+    // 目录落盘（原子唯一性）：plansRoot 父目录 recursive 建立 + 候选目录非 recursive
+    // mkdir 独占创建（已被占用抛 EEXIST 重探）
+    expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans", { recursive: true });
+    expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans/auth");
     // 提示词经 tool result 直返（不经对话流消息注入——对本次调用的直接响应）
     expect(pi.sendMessage).not.toHaveBeenCalled();
     expect(res.details.action).toBe("enter");
@@ -207,4 +209,72 @@ describe("plan(action='enter') — agent 自助进入（plan-mode-agent-enter U1
     expect(lastEntry.state).toBe("reviewing");
     expect(lastEntry.isActive).toBe(true);
   });
+
+  it("纯中文需求两轮进入不互覆：slug 折叠空串回落 untitled，第二轮候选位被占（mkdir 抛 EEXIST）重探落 untitled-2", async () => {
+    const { exec, sessions } = setup();
+    // 原子 mkdir 语义模拟：untitled 目录已被占用 → mkdirSync 抛 EEXIST（existsSync
+    // 预探已退役，冲突信号由 mkdir 自身承载——TOCTOU 竞态修复的机制锚）
+    let untitledTaken = false;
+    vi.mocked(fs.mkdirSync).mockImplementation(((p: fs.PathLike) => {
+      if (untitledTaken && String(p).endsWith("/.tmp/plans/untitled")) {
+        throw Object.assign(new Error("EEXIST: file already exists, mkdir"), { code: "EEXIST" });
+      }
+      return undefined;
+    }) as typeof fs.mkdirSync);
+
+    // 第一轮：目录不存在 → 落 untitled
+    await exec({ action: "enter", requirement: "重构认证模块" });
+    expect((sessions.get("test-session") as PlanState).planFilePath).toBe(
+      "/tmp/test-project/.tmp/plans/untitled/plan.md",
+    );
+
+    // 终局本轮（exited --enter--> 新一轮），untitled 目录已在盘上 = 第一轮已落盘
+    const state = sessions.get("test-session") as PlanState;
+    state.isActive = false;
+    state.state = "exited";
+    untitledTaken = true;
+
+    await exec({ action: "enter", requirement: "重构登录模块" });
+
+    // 第二轮经 EEXIST 重探落 untitled-2：两轮 plan.md 路径不同，不互覆
+    expect((sessions.get("test-session") as PlanState).planFilePath).toBe(
+      "/tmp/test-project/.tmp/plans/untitled-2/plan.md",
+    );
+  });
+
+  it("英文 slug 冲突递增（EEXIST 驱动）：base 与 -2 均被占用 → 落 -3", async () => {
+    const { exec } = setup();
+    vi.mocked(fs.mkdirSync).mockImplementation(((p: fs.PathLike) => {
+      const s = String(p);
+      if (s.includes("implement-user-auth") && !s.endsWith("implement-user-auth-3")) {
+        throw Object.assign(new Error("EEXIST: file already exists, mkdir"), { code: "EEXIST" });
+      }
+      return undefined;
+    }) as typeof fs.mkdirSync);
+
+    await exec({ action: "enter", requirement: "Implement User Auth" });
+
+    const mkdirCalls = (fs.mkdirSync as ReturnType<typeof vi.fn>).mock.calls as Array<[string]>;
+    expect(mkdirCalls.at(-1)?.[0]).toBe("/tmp/test-project/.tmp/plans/implement-user-auth-3");
+  });
+
+  it("非 EEXIST 的 mkdir 失败照常上抛（fail-fast，不吞真实故障）", async () => {
+    const { exec } = setup();
+    vi.mocked(fs.mkdirSync).mockImplementation((() => {
+      throw Object.assign(new Error("EACCES: permission denied, mkdir"), { code: "EACCES" });
+    }) as typeof fs.mkdirSync);
+
+    await expect(exec({ action: "enter", requirement: "r" })).rejects.toThrow(/EACCES/);
+  });
+
+  it("空需求（requirement 省略）走 untitled 目录", async () => {
+    const { exec, sessions } = setup();
+
+    const res = await exec({ action: "enter" });
+
+    expect(res.details.action).toBe("enter");
+    expect((sessions.get("test-session") as PlanState).planFilePath).toBe(
+      "/tmp/test-project/.tmp/plans/untitled/plan.md",
+    );
+  });
 });

package/src/__tests__/skills.test.ts

@@ -231,8 +231,8 @@ describe("E1 fail-fast via /plan handler", () => {
     await handler("重构 auth --skills tech-design,code review", ctx);
 
     expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
-    // slug 只保留 [a-z0-9]：「重构 auth」→ "auth"
-    expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans/auth", { recursive: true });
+    // slug 只保留 [a-z0-9]：「重构 auth」→ "auth"；候选目录走非 recursive mkdir（原子唯一性）
+    expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.tmp/plans/auth");
     expect(pi.appendEntry).toHaveBeenCalledWith(
       "plan-state",
       expect.objectContaining({

package/src/enter.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isErrnoWithCode } from "@zhushanwen/pi-ext-guards";
 
 // 技能执行门禁（resolveSkills + SkillResolution）单源在 ADR-0074 共享包
 // @zhushanwen/pi-exec-skills（plan-mode-audit-remediation 批次 4②b 迁入，含空请求
@@ -61,12 +62,33 @@ export function activatePlanMode(
   const state = getPlanState(sessions, sessionId, ctx);
   const { requirement, skills, projectDir } = input;
 
+  // slug 折叠后可能为空串（纯中文需求）——回落 "untitled"，保证目录名恒为
+  // <slug> 形态而非退化为 plans 骨架
   const slug = requirement
     ? requirement.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, MAX_SLUG_LENGTH)
-    : "untitled";
+    : "";
+  const baseSlug = slug || "untitled";
 
-  const planDir = path.join(projectDir, ".tmp", "plans", slug);
-  fs.mkdirSync(planDir, { recursive: true });
+  // 目录唯一性：探测与落盘收敛为一次原子操作——候选目录走非 recursive mkdirSync，
+  // 已被占用即抛 EEXIST，catch 后 <base>-2/-3 递增重探。存在性探测（existsSync）与
+  // recursive mkdir 落盘分离会留检查时刻与使用时刻竞态窗口（TOCTOU）：recursive 对
+  // 已存在目录静默成功，两进程并发 enter 可同探同一空位双双落盘、互覆 plan.md。
+  const plansRoot = path.join(projectDir, ".tmp", "plans");
+  fs.mkdirSync(plansRoot, { recursive: true });
+  let planDir = path.join(plansRoot, baseSlug);
+  for (let n = 2; ; n += 1) {
+    try {
+      fs.mkdirSync(planDir);
+      break;
+    } catch (error) {
+      // 仅 EEXIST（候选位被并发方/上一轮抢先命中）递增重探；其余 mkdir 失败
+      //（权限等真实故障）照常上抛，不吞
+      if (!isErrnoWithCode(error, "EEXIST")) {
+        throw error;
+      }
+      planDir = path.join(plansRoot, `${baseSlug}-${n}`);
+    }
+  }
   const planFilePath = path.join(planDir, "plan.md");
 
   state.isActive = true;

package/src/execution-notice.ts

@@ -51,11 +51,9 @@ function getGoalInit(): GoalInitFn | undefined {
 
 /**
  * goal 桥侧 slug（仅 widget 标题 + history 展示用，不注入 prompt）。生产输入恒为
- * <project>/.tmp/plans/<slug>/plan.md（enter.ts 构造）——展示名取目录名（requirement
- * slug 段，2026-09-27 用户裁决；已归档缺陷档案（plan-cjk-slug-data-loss） 缺陷 3 同源修复）。
- * kebab 链对 enter slug 幂等，只防 planFilePath 非生产形态的通用输入；提取为空回
- * "plan-execution"。中文需求且缺陷 2（enter 期目录唯一性）未修的窗口内，plan.md 直落
- * .tmp/plans 使本函数取到骨架名 "plans"——该形态随缺陷 2 修复消除。
+ * <project>/.tmp/plans/<slug>/plan.md（enter.ts 构造，目录名 = requirement slug 段，
+ * 已存在时 <base>-2/-3 递增保证唯一）——展示名取实际目录名。kebab 链对 enter slug
+ * 幂等，只防 planFilePath 非生产形态的通用输入；提取为空回 "plan-execution"。
  */
 function buildPlanSlug(planFilePath: string): string {
   const stem = basename(dirname(planFilePath))