@zhushanwen/pi-rename-session 0.3.0 → 0.5.0

package/README.md

@@ -1,13 +1,15 @@
 # @zhushanwen/pi-rename-session
 
-Pi rename-session 扩展 — 新 session 首 turn 完成后，自动生成会话标题并落库（`setSessionName`），让 session 列表摆脱默认的日期/序号占位，一眼可辨。
+Pi rename-session 扩展 — 新 session 首个成功 round 完成后，自动生成 slug 式会话标题并落库（`setSessionName`），让 session 列表摆脱默认的日期/序号占位，一眼可辨。
 
 ## 功能
 
-- 新 session 的**首个 turn** 完成后自动生成简短标题（3-8 个词，跟随对话语言）
-- 复用主 turn 完整上下文发起独立 LLM 调用，命中 kvcache，几乎不产生额外成本
+- 新 session 的**首个成功 round 末**自动生成 slug 式标题（名词/动名词词组，非完整句子；英文小写 kebab-case；跟随对话语言）
+- **触发时机**：只在 round 的最终 turn（`stopReason === "stop"`）评估——工具中间轮 / error / aborted / length 轮不评估，error 轮延迟到下一个成功轮命名
+- **两段输入**：`[user(首条 prompt), assistant(最终回复)]` 两段信号（各截断 4000 码点），不含 toolCall/toolResult 过程数据，token 成本不随工具数增长
+- **独立选模**：标题生成用独立的 `ModelSelector` 配置（仅支持 `ref` 精确指定 provider/model），不搭便车主 session 的昂贵模型
+- **可靠性行为**：固定 30s 超时；落库前重查手动名（防覆盖 LLM 调用窗口内的竞态）；任何失败静默跳过保留原 label，绝不阻断 agent 循环
 - 标题直接 `setSessionName` 落库，不进 session history（不污染对话记录）
-- fire-and-forget：任何失败（LLM 调用 / 提取 / auth / 读取）都静默跳过，保留原 label，绝不阻断 agent 循环
 - **子 session 自动排除**：subagent 子进程 session 不触发 rename（避免给临时产物起名）
 
 ## 安装
@@ -16,25 +18,99 @@ Pi rename-session 扩展 — 新 session 首 turn 完成后，自动生成会话
 pi install npm:@zhushanwen/pi-rename-session
 ```
 
-## 开关
+## 配置
 
-文件存在 = 开启。默认**关闭**，需显式开启。
+配置文件：`<agentDir>/config/rename-session-ext-config.json`（`<agentDir>` 默认 `~/.pi/agent`，`PI_CODING_AGENT_DIR` 可覆盖；xyz-agent 隔离环境为 `~/.xyz-agent/pi/agent`）。
 
-- **原生 pi 用户**：手动创建开关文件
-  ```bash
-  touch ~/.pi/agent/auto-rename-enabled
-  ```
-- **xyz-agent 用户**：通过 settings 的开关控制（由 xyz-agent 桥接到同一个开关文件）
+```json
+{
+  "enabled": true,
+  "model": { "type": "ref", "ref": "deepseek/deepseek-chat" },
+  "maxTitleLength": 50,
+  "thinkingLevel": "off"
+}
+```
+
+| 字段 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | 自动重命名开关（受 flag 文件覆盖，见下） |
+| `model` | `ModelSelector` | `{ "type": "ref", "ref": "" }` | 标题生成模型，仅支持精确指定 `{type:"ref", ref:"provider/modelId"}` |
+| `maxTitleLength` | `number` | `50` | 标题最大长度（Unicode 码点数，须正整数） |
+| `thinkingLevel` | `ModelThinkingLevel` | `"off"` | 标题 LLM 的 thinking 级别（`off` = 不传 reasoning，provider 默认） |
+
+文件缺失/坏 JSON 返回默认值，不抛错。改完保存即生效（mtime 读时刷新，每个 `turn_end` 重新 load）。
+
+## 开关优先级（重要）
+
+`enabled` 有两层来源，优先级从高到低：
+
+1. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：xyz-agent runtime 的开关契约——桌面端 SystemPage 开关、首启默认开启都写这个文件。**xyz-agent 用户请通过桌面端开关或 `/auto-rename` 命令管理，不要手改 JSON 的 `enabled`**（flag 存在时永远视为开，手改会被覆盖）。
+2. **config 的 `enabled` 字段**（默认 false）：flag 不存在时生效，是原生 pi CLI 用户的开关。
 
-开关文件路径可通过 `PI_CODING_AGENT_DIR` 环境变量覆盖基础目录（默认 `~/.pi/agent`）。
+## 命令
+
+```
+/auto-rename          # 查看当前状态
+/auto-rename on       # 开启（创建 flag 文件）
+/auto-rename off      # 关闭（写 config.enabled=false + 删 flag，双写同步）
+```
 
 ## 工作原理
 
-1. **监听 `turn_end`**：每个 turn 完成时触发。
-2. **开关 + subagent 过滤**：开关关闭则直接返回；session 路径含 `subagents` 段则视为子进程 session，跳过。
-3. **首 turn 判定**：统计 session entries 中 `assistant` 回复数，===1 才是首 turn（后续 turn 不重复 rename）。
-4. **LLM 生成标题**：复用主 turn 的完整上下文（system prompt + tools + messages），追加一条 rename 指令的 user message，发起一次独立 LLM 调用。由于前缀与主 turn 字节级一致，能命中 kvcache，显著省成本。
-5. **落库**：调 `setSessionName` 写入标题。**不**写入 session history（不调用 `appendEntry`），对话记录不受影响。
+1. **监听 `turn_end`**：pi 每个 iteration 结束都发一次 turn_end（工具中间轮、最终轮、异常轮各一次）。
+2. **开关 + subagent 过滤**：开关关闭（flag 不存在且 `enabled=false`）直接返回；session 路径含 `subagents` 段视为子进程 session，跳过。
+3. **O(1) 快速路径**：只有 `stopReason === "stop"` 的 turn 才继续——**rename 一定在 round 末触发**（最终 turn 的 message 即最终 assistant 回复，final text 零遍历可得），不会在首个 iteration 中途命名。
+4. **首 round 判定**：session entries 中成功（stop）assistant 回复数 === 1 才触发（后续 round 不重复 rename；error 轮的 assistant 回复不计数，延迟到下一个成功轮）。
+5. **两段输入构造**：`[user(首条 prompt), assistant(最终回复文本), user(instruction)]`——任务意图 + 轮次结论恰好与标题语义对齐，不含 toolCall/toolResult 过程数据；两段文本各截断 4000 Unicode 码点（中文场景约 4k token/段，成本可控且不随工具数增长）。assistant 段为空（纯工具结束的 round）时降级为两条。
+6. **LLM 生成 slug 标题**：独立精简 system prompt（<200 字符的 slug 词组约束，非整个 agent prompt）+ instruction（正反例 few-shot，作为追加 user message 发送）+ `tools: []` + `maxTokens: 64`，按 `config.model` 独立选模发起一次 LLM 调用；固定 30s 超时（超时归一为失败，走静默跳过）。
+7. **落库**：cleanTitle 清洗（去首尾引号 / markdown 强调标记 / 句尾标点、空白归一、按码点截断）后 `setSessionName` 写入。**落库前重查** `pi.getSessionName()`——LLM 调用窗口（2-30s）内用户手动命名的竞态由此兜住，已有名则 skip 不覆盖。**不**写入 session history，对话记录不受影响。
+
+### 可靠性行为
+
+rename 是 best-effort 副作用，任何失败静默跳过、绝不阻断 agent 循环：
+
+| 情形 | 行为 |
+|---|---|
+| 中间 iteration（工具轮）的 turn_end | skip（stopReason=toolUse），round 末才评估 |
+| error / aborted / length 轮 | skip（stopReason=<X>），error 上下文不用于命名，延迟到下一个成功轮 |
+| 非 round-1（成功回复数 ≠ 1） | skip（count=N），一次性语义 |
+| LLM 调用失败 / 超过 30s | 记录失败日志，保留原 label（不做重试；用户可手动命名） |
+| 标题清洗后为空 | skip（title empty） |
+| 落库前发现已有手动名 | skip（name exists），不覆盖 |
+| 标题模型不可用 | 记日志静默跳过 |
+
+### debug 证据链（`XYZ_AGENT_DEBUG=1`）
+
+`console.warn` 输出，前缀 `[rename-session]`。下列 8 条 debug 日志的**文案字面值是 E2E 断言硬契约**（变更须同步 `e2e/` 场景脚本与单测）：
+
+| # | 日志 | 发出侧 | 含义 |
+|---|---|---|---|
+| 1 | `skip: stopReason=<r>` | handler（带 `turnIndex=<n>`） | 快速路径拦截（toolUse/error/aborted/length） |
+| 2 | `skip: count=<n>` | handler（带 turnIndex） | 非首成功 round |
+| 3 | `skip: name exists` | handler（带 turnIndex） | 落库前防覆盖命中 |
+| 4 | `renamed to "<title>"` | handler（带 turnIndex） | 标题生成并落库成功（index.ts `.then()` 内 `setSessionName` 之后打出；竞态命中时只打 #3，无此条） |
+| 5 | `skip: no user prompt` | llm | session 无 user message（理论不发生） |
+| 6 | `skip: title empty` | llm | cleanTitle 清洗后为空 |
+| 7 | `LLM request messages: <JSON>` | llm | 传给 callLLM 的 messages 内省（role + text 的 head 200 码点 + … + tail 100 码点预览，截断单位与 truncateForTitle 统一为 Unicode 码点），在请求发起前打出 |
+| 8 | `rename with model <provider>/<id>` | llm | 成功路径模型记录（原常开日志；为避免污染 Pi 输入框改为 debug 输出，带 t=ISO 时间戳） |
+
+另有两条**非 debug 常开**日志：`rename LLM call failed: <err>`（调用失败/超时；超时时 llm-shared callLLM 内部的 extractText 将空错误文本归一为 `unknown error`——extension 侧 `result.error ?? "unknown error"` 只兜 null/undefined，空串兜底发生在 llm-shared 层）、`model not available, skipping`（选模失败）。handler 侧日志带 `t=<ISO时间>` 与 `turnIndex`；llm 侧带 `t=<ISO时间>`、无 turnIndex。
+
+## E2E 验收
+
+E2E 是本地人工触发的验收资产（真实 pi 进程 + 真实模型，不进常规 CI），覆盖五个场景：A1 触发时机证据链（流序/内容匹配/负向/行序/结构五重——结构断言 = 仅一条 LLM request + [user,assistant,user] 三元组）、A2 slug 风格 ×3、A3 防覆盖（静态/竞态/一次性）、A4 error 轮两阶段（`--session` 续跑）、A5 超时兜底（hang provider）。
+
+```bash
+cd extensions/rename-session
+node e2e/run-a1.mjs    # 单场景独立可跑（run-a1 ~ run-a5）
+node e2e/run-all.mjs   # 顺序全跑：单场景失败不阻断后续，汇总表 + exit code（任一失败（含 KEBAB_NON_COMPLIANT）→ 1）
+```
+
+- 环境要求与探针结论（auth 迁移 / RPC 协议格式 / `--session` 续跑 / 坏 provider 与 stub socket 配置写法）：`e2e/README.md`
+- harness API 与断言纯函数（单测 `e2e/harness.test.mjs` 随 vitest 跑）：`e2e/harness.mjs`
+- A2 的标题记录与人工抽查表（词组形态/语义相关/语言跟随三列）：`e2e/RESULTS.md`（run-a2 自动追加，人工填写）
+- 保留现场调试：`E2E_KEEP_TMP=1 node e2e/run-all.mjs`
+- 测试模型固定 `xiaomi-token-plan-cn/mimo-v2.5-pro`（项目规范，禁 kimi）
 
 ## 子 session 自动排除
 
@@ -48,9 +124,20 @@ rename-session/
 ├── package.json
 ├── vitest.config.ts
 ├── README.md
+├── e2e/                  # E2E 验收资产（本地人工触发，不进常规 CI）
+│   ├── README.md         # 探针结论 + 运行指南
+│   ├── harness.mjs       # pi 进程/RPC/交错时间轴/断言纯函数
+│   ├── harness.test.mjs  # 断言纯函数单测（随 vitest 跑）
+│   ├── run-a1.mjs ~ run-a5.mjs   # A1-A5 场景脚本
+│   ├── run-all.mjs       # 总结 runner（汇总 + exit code）
+│   ├── scenarios.test.mjs        # A1-A5 的 vitest 包装（仅 e2e config 收录，不进常规 CI）
+│   ├── vitest.e2e.config.ts  # E2E 专用 vitest 入口（--config 显式指定，include 含 scenarios.test.mjs）
+│   └── RESULTS.md        # A2 标题记录 + 人工抽查表
+├── skills/rename-session-ext-config/SKILL.md   # 配置指南（pi 内 agent 可发现）
 └── src/
-    ├── index.ts          # 工厂入口（注册 turn_end handler）
-    ├── pure.ts           # 纯函数（countAssistantReplies / extractTitle / isEnabled / CONFIG）
-    ├── llm.ts            # callRenameLLM（动态 import completeSimple，复用主 turn 上下文）
-    └── __tests__/        # 单测（pure 纯函数 + llm mock + index 集成）
+    ├── index.ts          # 工厂入口（注册 turn_end handler + /auto-rename 命令）
+    ├── commands.ts       # /auto-rename on|off|status 命令
+    ├── llm.ts            # callRenameLLM / 两段输入构造 / debug 内省 / 超时
+    ├── pure.ts           # 纯函数（配置 / 首轮计数 / cleanTitle）
+    └── __tests__/        # 单测（pure / commands / llm mock / index 集成）
 ```

package/package.json

@@ -1,23 +1,29 @@
 {
   "name": "@zhushanwen/pi-rename-session",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "index.ts",
   "pi": {
     "extensions": [
       "./index.ts"
     ],
-    "skills": []
+    "skills": [
+      "./skills"
+    ]
   },
   "keywords": [
     "pi-package"
   ],
+  "dependencies": {
+    "@zhushanwen/pi-llm-shared": "0.3.0"
+  },
   "devDependencies": {
     "vitest": "^4.1.8"
   },
   "files": [
     "index.ts",
     "src/**/*.ts",
+    "skills/",
     "vitest.config.ts"
   ],
   "peerDependencies": {

package/skills/rename-session-ext-config/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: rename-session-ext-config
+description: "配置 @zhushanwen/pi-rename-session（会话自动重命名）时加载。含配置文件路径、RenameSessionConfig schema、ModelSelector ref 精确指定、触发时机（首 turn）、maxTitleLength 约束、默认值、示例、生效时机、开关优先级（flag 覆盖）。触发词：配置重命名、rename 配置、自动标题、rename-session config、auto-rename 设置、首 turn、触发时机、开关不生效。"
+---
+
+# rename-session 配置指南
+
+> @zhushanwen/pi-rename-session：新 session 首个成功 round 完成后，用独立小模型生成会话标题（不搭便车主 session 的昂贵模型）。
+
+## 配置文件位置
+
+`<agentDir>/config/rename-session-ext-config.json`
+
+- `<agentDir>` = pi agent 目录（`PI_CODING_AGENT_DIR` 覆盖，默认 `~/.pi/agent`；xyz-agent 隔离环境为 `~/.xyz-agent/pi/agent`）
+- 走 llm-shared 泛型 config（config/ 子目录 + getAgentDir 派生 + mtime+size 缓存 + 原子写）
+- 文件缺失/坏 JSON 返回默认值，不抛错
+
+## 何时触发重命名（重要）
+
+**仅在新 session 的首个成功 round 完成后触发一次**（判定条件：round 最终 turn 的 `stopReason === "stop"`，且 session 内成功（stop）assistant 回复数 === 1）。
+
+- 已存在的多 turn session **不会回溯重命名**——开启 `enabled` 后只对之后新建的 session 生效
+- 每个 session 最多重命名一次（首个成功 round 后不再触发）
+- 工具中间轮（`stopReason === "toolUse"`）不评估；error/aborted/length 轮延迟到下一个成功轮再命名
+- 若首个成功 round 时 LLM 调用失败，静默跳过保留原标题，不重试
+
+> 改完配置「没看到 session 被重命名」的常见原因：当前 session 已过首个成功 round。新建一个 session 测试。
+
+## Schema
+
+```ts
+interface RenameSessionConfig {
+  enabled: boolean;        // 自动重命名开关，默认 false
+  model: ModelSelector;    // 标题生成模型，默认 { type: "ref", ref: "" }（未配置则解析不到，跳过 rename）
+  maxTitleLength: number;  // 标题最大长度（Unicode 码点），默认 50
+  thinkingLevel: ModelThinkingLevel;  // 标题 LLM 的 thinking 级别，默认 "off"
+}
+```
+
+### ModelSelector（仅支持 ref 精确指定）
+
+| type | 形式 | 语义 |
+|---|---|---|
+| `ref` | `{type:"ref", ref:"provider/modelId"}` | 精确指定（需配 auth） |
+
+不再支持 `fallback` / `available` / `scoped`。需要自动选模时请在调用方（如 permission 的 `"auto"`）自行基于 `ctx.modelRegistry` 实现。
+
+### maxTitleLength 约束
+
+必须是**正整数**（`Number.isInteger && > 0`）。传小数（`50.5`）、0、负数、非数字都会回落默认值 50。截断按 Unicode 码点（不会截断多字节字符）。
+
+### thinkingLevel 取值
+
+标题 LLM 的 thinking 级别，枚举 `off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`（pi 的 `ModelThinkingLevel`）。默认 `"off"`：直接透传给 llm-shared，由 llm-shared 映射为不传 reasoning（provider 默认行为）；`minimal`~`max` 透传给 reasoning（provider 不支持时静默忽略）。缺失或非法值回落 `"off"`。
+
+## 默认值
+
+```json
+{ "enabled": false, "model": { "type": "ref", "ref": "" }, "maxTitleLength": 50, "thinkingLevel": "off" }
+```
+
+## 环境变量覆盖（容器化部署/CI-CD）
+
+支持通过环境变量覆盖配置，适用于容器化部署、CI/CD 等场景。环境变量优先级最高，覆盖配置文件和 flag 文件。
+
+| 环境变量 | 说明 | 示例值 |
+|---|---|---|
+| `PI_RENAME_ENABLED` | 自动重命名开关 | `true` / `false` |
+| `PI_RENAME_MODEL` | 模型引用（`provider/model` 格式，映射为 `{type:"ref", ref:"provider/model"}`） | `deepseek/chat` |
+| `PI_RENAME_MAX_TITLE_LENGTH` | 标题最大长度（正整数） | `30` |
+| `PI_RENAME_THINKING_LEVEL` | thinking 级别 | `minimal` / `high` |
+
+**注意事项：**
+- 环境变量值无效时静默忽略，回落到配置文件或默认值
+- 环境变量优先级最高，即使 flag 文件存在，`PI_RENAME_ENABLED=false` 也会禁用重命名
+- 环境变量每次调用时 live 读取，修改后无需重启进程（下一个 `turn_end` 生效）
+- 环境变量只支持简单 `provider/model` 覆盖；ModelSelector 本身仅支持 ref 精确指定
+
+**使用示例：**
+```bash
+# 容器化部署：启用重命名 + 指定便宜模型
+PI_RENAME_ENABLED=true PI_RENAME_MODEL=deepseek/chat node app.js
+
+# CI/CD 禁用重命名
+PI_RENAME_ENABLED=false npm test
+
+# 开发环境：使用轻量 thinking
+PI_RENAME_ENABLED=true PI_RENAME_THINKING_LEVEL=minimal npm run dev
+```
+
+## 配置示例
+
+固定用便宜模型生成标题：
+```json
+{
+  "enabled": true,
+  "model": { "type": "ref", "ref": "deepseek/deepseek-chat" },
+  "maxTitleLength": 50,
+  "thinkingLevel": "off"
+}
+```
+
+> 必须精确指定 `ref`；未配置或 ref 为空时解析不到模型，rename 会静默跳过。
+
+## 配置生效时机
+
+配置走 mtime+size 读时刷新（每个 `turn_end` 都重新 load）。改完 JSON 保存后，**下一个新 session 的首个成功 round** 即按新配置触发（已过首个成功 round 的 session 不受影响）。
+
+**环境变量生效时机：** 环境变量每次调用时 live 读取（`process.env`），修改后无需重启进程，下一个 `turn_end` 即按新环境变量生效。
+
+## 排除项
+
+subagent 子进程 session 不重命名（`isSubagentSession` 判定 session 目录）——子 session 是临时产物，重命名会产生噪音。如果你发现某个 session 没被重命名，先确认它不是 subagent session。
+
+## 开关优先级（重要）
+
+`enabled` 有三层来源，优先级从高到低：
+
+1. **环境变量 `PI_RENAME_ENABLED`**（最高优先级）：适用于容器化部署、CI/CD 等场景。`true`/`false` 字符串，live 读取。覆盖 flag 文件和配置文件。
+2. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：这是 xyz-agent runtime 的开关契约（SystemPage 开关 / 首启默认开启都写这个文件，live 检查每次 turn_end 生效）。**xyz-agent 用户不要手改 JSON 里的 enabled**——桌面端的开关状态存在 flag 文件里，手改 JSON 会被 flag 覆盖（flag 存在时永远视为开）。
+3. **config 的 `enabled` 字段**（默认 false）：flag 不存在时生效，是原生 pi CLI 用户的开关（手改 JSON 或 `/auto-rename on|off` 命令）。
+
+`/auto-rename on` 只创建 flag；`/auto-rename off` 写 config.enabled=false + 删 flag（双写同步）。旧版升级用户：旧 flag 文件保留不动，仍作为开关生效，无需任何迁移操作。
+
+## LLM 调用特性
+
+- 独立 model（不搭便车主 session 模型）
+- 独立精简 system prompt（<200 字符的 slug 词组约束 + 正反例 few-shot，非整个 agent prompt）
+- 不传 tools（纯文本标题生成）
+- fire-and-forget（不阻塞 turn_end handler）
+- model 不可用 → 静默跳过（日志 `[rename-session] model not available, skipping`），不阻断主对话

package/src/__tests__/commands.test.ts

@@ -2,66 +2,89 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { clearConfigCache } from "@zhushanwen/pi-llm-shared";
 
 import { executeAutoRenameCommand } from "../commands.js";
 
 /**
- * executeAutoRenameCommand 依赖模块级 CONFIG.switchFilePath，用 vi.mock("./pure.js")
- * 注入可控路径，避免读写真实 ~/.pi/agent 目录。
+ * executeAutoRenameCommand 读写 `<agentDir>/config/rename-session-ext-config.json`（经 llm-shared loadConfig/saveConfig，
+ * 路径走 getAgentDir）。用 PI_CODING_AGENT_DIR 隔离到临时目录，避免读写真实 ~/.pi/agent。
+ * 每次写入后 clearConfigCache 确保读盘（不命中 mtime 缓存），验证真实落盘行为。
  */
-vi.mock("../pure.js", async (importActual) => {
-	const actual = await importActual<typeof import("../pure.js")>();
-	const tmpFile = path.join(os.tmpdir(), `rename-cmd-${Date.now()}-enabled`);
-	return {
-		...actual,
-		CONFIG: { ...actual.CONFIG, switchFilePath: tmpFile },
-		isEnabled: (p: string) => fs.existsSync(p),
-		setSwitch: actual.setSwitch,
-	};
-});
+describe("executeAutoRenameCommand", () => {
+	let tmpAgentDir: string;
+	let origEnv: string | undefined;
 
-// 被测模块须在 vi.mock 之后 import（vitest 提升 vi.mock）
-import { CONFIG as MOCKED_CONFIG } from "../pure.js";
+	beforeEach(() => {
+		tmpAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "rename-cmd-"));
+		origEnv = process.env.PI_CODING_AGENT_DIR;
+		process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
+		clearConfigCache();
+	});
 
-describe("executeAutoRenameCommand", () => {
 	afterEach(() => {
-		try { fs.unlinkSync(MOCKED_CONFIG.switchFilePath); } catch (e) { console.debug("cleanup skip:", e); }
+		if (origEnv === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = origEnv;
+		clearConfigCache();
+		fs.rmSync(tmpAgentDir, { recursive: true, force: true });
 	});
 
-	it("无参数 → 显示当前状态 + 用法", () => {
+	function configPath(): string {
+		return path.join(tmpAgentDir, "config", "rename-session-ext-config.json");
+	}
+
+	it("无参数 → 显示当前状态（默认关闭）+ 用法", () => {
 		const msg = executeAutoRenameCommand("");
 		expect(msg).toContain("自动重命名会话");
+		expect(msg).toContain("已关闭");
 		expect(msg).toContain("用法");
 	});
 
 	it("status → 同无参数", () => {
-		const msg = executeAutoRenameCommand("status");
-		expect(msg).toContain("自动重命名会话");
+		expect(executeAutoRenameCommand("status")).toContain("已关闭");
 	});
 
-	it("on → 开启并创建文件", () => {
+	it("on → 创建 flag 文件（不写 config，避免残留 enabled=true）", () => {
 		const msg = executeAutoRenameCommand("on");
 		expect(msg).toContain("已开启");
-		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(true);
+		// 开启走 flag 契约（live 覆盖源），不落 config
+		expect(fs.existsSync(path.join(tmpAgentDir, "auto-rename-enabled"))).toBe(true);
+		expect(fs.existsSync(configPath())).toBe(false);
+	});
+
+	it("on 后 status 显示已开启（缓存一致，无需 clearConfigCache）", () => {
+		executeAutoRenameCommand("on");
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
 	});
 
-	it("off → 关闭并删除文件", () => {
-		fs.writeFileSync(MOCKED_CONFIG.switchFilePath, "");
+	it("off → 写 config.enabled=false 落盘 + 删除 flag（双写同步）", () => {
+		executeAutoRenameCommand("on");
 		const msg = executeAutoRenameCommand("off");
 		expect(msg).toContain("已关闭");
-		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(false);
+		clearConfigCache();
+		const raw = JSON.parse(fs.readFileSync(configPath(), "utf-8"));
+		expect(raw.enabled).toBe(false);
+		expect(fs.existsSync(path.join(tmpAgentDir, "auto-rename-enabled"))).toBe(false);
 	});
 
 	it("enable/disable 作为 on/off 别名", () => {
-		expect(executeAutoRenameCommand("enable")).toContain("已开启");
-		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(true);
-		expect(executeAutoRenameCommand("disable")).toContain("已关闭");
+		executeAutoRenameCommand("enable");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
+		executeAutoRenameCommand("disable");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已关闭");
 	});
 
 	it("大小写不敏感（ON / Off）", () => {
-		expect(executeAutoRenameCommand("ON")).toContain("已开启");
-		expect(executeAutoRenameCommand("Off")).toContain("已关闭");
+		executeAutoRenameCommand("ON");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
+		executeAutoRenameCommand("Off");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已关闭");
 	});
 
 	it("未知参数 → 提示用法", () => {
@@ -69,4 +92,24 @@ describe("executeAutoRenameCommand", () => {
 		expect(msg).toContain("未知参数");
 		expect(msg).toContain("用法");
 	});
+
+	it("on 不动 config（手写 enabled/model/maxTitleLength 均保留）", () => {
+		// 预置含自定义 model + maxTitleLength 的配置
+		fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+		fs.writeFileSync(
+			configPath(),
+			JSON.stringify({ enabled: false, model: { type: "ref", ref: "a/b" }, maxTitleLength: 30 }),
+		);
+		clearConfigCache();
+
+		executeAutoRenameCommand("on");
+		clearConfigCache();
+
+		// on 只建 flag，config 原封不动（enabled 仍 false，但 loadRenameConfig 被 flag 覆盖为 true）
+		const raw = JSON.parse(fs.readFileSync(configPath(), "utf-8"));
+		expect(raw.enabled).toBe(false);
+		expect(raw.model).toEqual({ type: "ref", ref: "a/b" });
+		expect(raw.maxTitleLength).toBe(30);
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
+	});
 });