feat: Gate session writer lease behind opt-in

[doudouOUC]

What this PR does

This PR adds experimental.sessionWriterLease as an explicit, restart-required opt-in for cross-process write fencing, with a default value of false. The lease is enabled only when the setting is the boolean value true and the session is running through ACP or the daemon; interactive and headless sessions continue to use the legacy recorder path. ACP snapshots the effective gate from its bootstrap configuration and reuses it for every session served by that process, so per-session settings reloads cannot mix leased and legacy writers before a restart. The settings UI, user documentation, design documentation, generated settings schema, and regression coverage are updated to describe and preserve the rollout behavior.

Why it's needed

#7237 introduced session writer leases to prevent concurrent ACP processes from corrupting persisted session history, but the protocol is safe only when every concurrent writer participates. Enabling it automatically makes mixed-version or mixed-configuration deployments unsafe during rollout and rollback, while allowing a live ACP process to change modes on a settings reload could create the same unsafe mix inside one process lifetime. A default-off, process-stable opt-in lets operators drain existing writers, enable the protocol consistently across ACP and daemon processes, and restart them in a controlled order.

Reviewer Test Plan

How to verify

1. Start an ACP session without experimental.sessionWriterLease, or set it to false, and confirm recording continues through the legacy path without acquiring a writer lease.
2. Set experimental.sessionWriterLease to true, restart the ACP or daemon process, and confirm the existing lease contention, authoritative reload, write fencing, and release behavior remains active.
3. Enable the setting in an interactive or headless session and confirm it still uses the legacy recorder path.
4. Supply an invalid truthy value such as the string "true" and confirm it does not enable the lease.
5. Change the setting without restarting an existing ACP process, then create another session through that process; confirm both disabled-to-enabled and enabled-to-disabled changes keep the startup value until restart.
6. Run the complete ACP agent test file; all 325 tests should pass, including both process-stability cases.
7. Run cd packages/cli && npx vitest run src/config/config.test.ts src/config/settingsSchema.test.ts src/utils/settingsUtils.test.ts; all 422 tests should pass.
8. Run the focused Core gate tests and cd packages/core && npx vitest run src/services/session-writer-lease.test.ts; the gate tests should pass, and the lease suite should report 21 passed with one platform-specific skip.
9. Run the Core typecheck, targeted ESLint, Prettier check, settings-schema generator, and git diff --check; all should complete successfully.

Evidence (Before & After)

Before: ACP sessions automatically entered the session writer lease protocol, and there was no rollout control in settings.

After: the Experimental settings expose “Enable ACP Session Writer Lease” as a restart-required boolean that defaults to off; only an explicit boolean true activates the protocol for ACP and daemon sessions, and an ACP process keeps its startup value for every session until that process restarts.

Tested on

OS	Status
🍏 macOS	✅ tested
🪟 Windows	⚠️ not tested
🐧 Linux	⚠️ not tested

Environment (optional)

macOS 26.4.1, Node.js v22.22.3, npm 10.9.8, local workspace without a sandbox.

Risk & Scope

• Main risk or tradeoff: Mixed-version or mixed-configuration ACP writers remain unsafe because writers with the setting disabled do not honor the lease; operators must enable the setting consistently, drain old writers during rollout or rollback, and restart each ACP or daemon process before expecting a settings change to take effect.
• Not validated / out of scope: Windows and Linux were not tested locally, and no live TUI screenshot was captured. Full CLI typecheck was not used as evidence because the local dependency state reports existing Ink selection API type mismatches in files outside this change.
• Breaking changes / migration notes: There is no schema migration. The writer lease behavior added by fix(core): Fence concurrent ACP session writers #7237 is now disabled by default; deployments that rely on it must enable experimental.sessionWriterLease for every concurrent ACP or daemon writer and restart those processes.

Linked Issues

Follow-up to #7237.

中文说明

本 PR 的改动

本 PR 新增 experimental.sessionWriterLease，作为跨进程写入隔离的显式开关；该设置需要重启才能生效，默认值为 false。只有设置值严格为布尔值 true，并且会话通过 ACP 或 daemon 运行时，才会启用写入租约；交互式和 headless 会话继续使用旧记录器路径。ACP 会从启动配置中快照有效门控值，并将其复用于该进程服务的每个会话，因此按会话重新加载设置不会在重启前混用租约和旧写入方。同时更新设置界面、用户文档、设计文档、生成的设置 schema 和回归测试，以说明并固定这一发布行为。

为什么需要

#7237 引入了会话写入租约，用于防止多个 ACP 进程并发写入时损坏持久化会话历史，但该协议只有在所有并发写入方都参与时才安全。自动启用会导致混合版本或混合配置部署在发布和回滚期间处于不安全状态，而允许存活的 ACP 进程在重新加载设置时切换模式，也可能在单个进程生命周期内产生同样的不安全混用。默认关闭且进程内稳定的显式开关允许运维人员先排空已有写入进程，再统一为 ACP 和 daemon 进程启用协议，并按可控顺序重启。

Reviewer 测试计划

如何验证

1. 在未配置 experimental.sessionWriterLease 或将其设置为 false 的情况下启动 ACP 会话，确认记录功能继续走旧路径且不会获取写入租约。
2. 将 experimental.sessionWriterLease 设置为 true，重启 ACP 或 daemon 进程，确认现有的租约竞争、权威数据重载、写入隔离和释放行为仍然生效。
3. 在交互式或 headless 会话中启用该设置，确认仍然使用旧记录器路径。
4. 提供字符串 "true" 等非法 truthy 值，确认不会启用租约。
5. 在不重启现有 ACP 进程的情况下修改设置，再通过该进程创建另一个会话；确认从关闭改为开启和从开启改为关闭两种情况都保持启动值，直到进程重启。
6. 运行完整 ACP agent 测试文件；预期 325 个测试全部通过，包括两个进程稳定性用例。
7. 运行 cd packages/cli && npx vitest run src/config/config.test.ts src/config/settingsSchema.test.ts src/utils/settingsUtils.test.ts；预期 422 个测试全部通过。
8. 运行聚焦的 Core 门控测试和 cd packages/core && npx vitest run src/services/session-writer-lease.test.ts；预期门控测试通过，租约测试为 21 个通过、1 个平台相关跳过。
9. 运行 Core 类型检查、目标 ESLint、Prettier 检查、设置 schema 生成器和 git diff --check；预期全部成功完成。

证据（Before & After）

Before：ACP 会话会自动进入会话写入租约协议，设置中没有发布控制开关。

After：Experimental 设置中会显示“Enable ACP Session Writer Lease”，它是一个需要重启、默认关闭的布尔开关；只有显式设置为布尔值 true 时，ACP 和 daemon 会话才会启用该协议，并且 ACP 进程会对其服务的每个会话保持启动值，直到该进程重启。

测试平台

OS	状态
🍏 macOS	✅ 已测试
🪟 Windows	⚠️ 未测试
🐧 Linux	⚠️ 未测试

环境（可选）

macOS 26.4.1、Node.js v22.22.3、npm 10.9.8，本地工作区，未使用 sandbox。

风险与范围

• 主要风险或权衡：混合版本或混合配置的 ACP 写入方仍然不安全，因为未启用设置的写入方不会遵守租约；发布或回滚期间，运维人员必须统一启用设置、排空旧写入进程，并重启每个 ACP 或 daemon 进程后，才能期望设置变更生效。
• 未验证 / 范围之外：未在本地测试 Windows 和 Linux，也未采集实时 TUI 截图。完整 CLI 类型检查未作为验证证据，因为本地依赖状态在本次改动之外的文件中报告了现有 Ink selection API 类型不匹配。
• 破坏性变更 / 迁移说明：没有 schema 迁移。fix(core): Fence concurrent ACP session writers #7237 新增的写入租约行为现在默认关闭；依赖该行为的部署必须为每个并发 ACP 或 daemon 写入进程启用 experimental.sessionWriterLease 并重启这些进程。

关联问题

#7237 的后续改动。

[qwen-code-ci-bot]

Qwen Code review did not complete successfully. Run review failed. See workflow logs for details. A transient error is retried automatically; if you are seeing this, retry with @qwen-code /review. See workflow logs.

[qwen-code-ci-bot]

✅ Qwen Triage finished — CI landed green on a789291 and the deferred approval was posted. finalize run

✅ Qwen Triage 已完成 —— a789291 的 CI 全绿，延迟审批已提交。查看 finalize 运行

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: This is a real operational concern, not theoretical hardening. #7237 (merged) auto-enables the session writer lease for all ACP sessions, but the protocol is only safe when every concurrent writer participates. During a rolling deployment or rollback, mixed-version processes that don't understand the lease will corrupt session history. The PR provides a before/after explanation and links the originating PR as evidence.

Direction: Aligned. Gating a safety-critical cross-process protocol behind an explicit opt-in is standard rollout practice — it lets operators drain old writers and enable the protocol consistently before restarting. This is squarely within qwen-code's session persistence mission.

Size: 48 production logic lines (config plumbing + schema + ACP snapshot), 159 test lines, 11 docs lines, 5 generated schema lines. Well within bounds — no maintainer escalation needed.

Approach: The scope is tight and every edit serves the stated goal. The strict === true check (rejecting "true" strings) is a nice touch for a setting that gates a safety protocol. The ACP startup snapshot mechanism correctly prevents per-session settings reloads from mixing leased and legacy writers within one process lifetime. No drive-by refactors or unrelated changes.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：这是一个真实的运维问题，不是理论性加固。#7237（已合并）对所有 ACP 会话自动启用写入租约，但该协议只有在所有并发写入方都参与时才安全。滚动部署或回滚期间，不理解租约的混合版本进程会损坏会话历史。PR 提供了 before/after 说明并关联了原始 PR 作为证据。

方向：对齐。将安全关键的跨进程协议放在显式开关后面是标准的发布实践——允许运维人员排空旧写入进程，统一启用协议后再重启。这完全在 qwen-code 会话持久化的核心使命内。

规模：48 行生产逻辑（配置管道 + schema + ACP 快照），159 行测试，11 行文档，5 行生成 schema。远在阈值内——无需维护者关注。

方案：范围紧凑，每处改动都服务于既定目标。严格的 === true 检查（拒绝 "true" 字符串）对于安全协议的开关来说是个好设计。ACP 启动快照机制正确防止了按会话设置重载在单个进程生命周期内混用租约和旧写入方。没有顺手重构或无关改动。

进入代码审查 🔍

— Qwen Code · qwen3.8-max-preview

_{Reviewed at a7892915769a985207dcee2b73a637d34234bf6d · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code Review

Independent proposal: Given the goal — gate the session writer lease behind an explicit opt-in — I would add a sessionWriterLeaseEnabled boolean to ConfigParameters, compute it as experimentalZedIntegration && params.sessionWriterLeaseEnabled === true in the Config constructor, replace the experimentalZedIntegration guard in activateChatRecording() with the new combined flag, pass it to ChatRecordingService as writerLeaseRequired, wire it through the CLI settings schema and loadCliConfig, snapshot it at ACP startup to prevent per-session reloads from mixing modes, and update docs/tests.

Comparison with the diff: The PR does exactly this. The implementation is clean and minimal:

• The combined gate (experimentalZedIntegration === true && params.sessionWriterLeaseEnabled === true) correctly ensures non-ACP sessions never acquire the lease regardless of the setting, and ACP sessions require the explicit boolean true.
• The strict === true check in both Config and loadCliConfig rejects invalid truthy values like the string "true" — appropriate for a safety-protocol gate.
• createChatRecordingService() now passes sessionWriterLeaseEnabled instead of experimentalZedIntegration, so writerLeaseRequired in the recorder correctly reflects the combined gate. When disabled, the recorder starts in the legacy path (immediate active state, no write barrier, no lease binding).
• The ChatRecordingService default parameter fallback chain (isSessionWriterLeaseEnabled?.() ?? getExperimentalZedIntegration?.() ?? true) preserves backward compatibility for direct construction outside createChatRecordingService.
• Non-lease uses of getExperimentalZedIntegration() (auto-title, tool scheduler, prompts, askUserQuestion, enterPlanMode) are correctly left untouched.
• The ACP startup snapshot (sessionWriterLeaseEnabledAtStartup) is captured before the first await in runAcpAgent, passed to the QwenAgent constructor, and injected into every session's mergedSettings — correctly preventing per-session settings reloads from changing the gate within one process lifetime.
• Existing lease tests are updated to pass sessionWriterLeaseEnabled: true so they continue exercising the leased path. New parametrized tests cover the three gate-negative cases (ACP without opt-in, non-ACP with setting, ACP with invalid truthy) and both process-stability directions (disabled-to-enabled, enabled-to-disabled).

No critical blockers. No AGENTS.md violations. No over-abstraction or duplication.

CI Test Evidence

Final CI results for a789291 (auto-updated by the triage finalize job after CI completed):

Check	Conclusion
Classify PR	✅ success
macos-latest / Java 21	✅ success
Real daemon E2E / Java 11	✅ success
Test (ubuntu-latest, Node 22.x)	✅ success
ubuntu-latest / Java 11	✅ success
ubuntu-latest / Java 17	✅ success
ubuntu-latest / Java 21	✅ success
web-shell E2E Smoke (ubuntu-latest, Node 22.x)	✅ success
windows-latest / Java 21	✅ success

_{One row per check name (latest run); skipped checks omitted; failures sort first. / 每个检查名一行（取最新一次运行），省略 skipped，失败项排在最前。}

Precheck (lint, format, typecheck) passed. Ubuntu unit tests are still running; macOS and Windows are skipped pending ubuntu completion. The review-pr and route cancellations visible in the check list are bot orchestration jobs (infrastructure), not PR CI tests.

Not verified: live ACP/daemon lease behavior (requires multi-process ACP setup not available in this review context). The author reports macOS testing; Windows and Linux were not tested by the author.

中文说明

代码审查

独立方案与 PR 实现完全一致。改动干净、最小化：

• 组合门控（experimentalZedIntegration === true && params.sessionWriterLeaseEnabled === true）正确确保非 ACP 会话永远不会获取租约，ACP 会话需要显式布尔值 true。
• 严格 === true 检查拒绝无效 truthy 值（如字符串 "true"）——对安全协议开关来说设计合理。
• createChatRecordingService() 传递 sessionWriterLeaseEnabled 而非 experimentalZedIntegration，使记录器的 writerLeaseRequired 正确反映组合门控。禁用时记录器走旧路径（立即进入 active 状态，无写入屏障、无租约绑定）。
• ChatRecordingService 默认参数回退链（isSessionWriterLeaseEnabled?.() ?? getExperimentalZedIntegration?.() ?? true）保持了直接构造时的向后兼容性。
• 非租约用途的 getExperimentalZedIntegration()（自动标题、工具调度器、提示词、askUserQuestion、enterPlanMode）正确保持不变。
• ACP 启动快照（sessionWriterLeaseEnabledAtStartup）在 runAcpAgent 的第一个 await 之前捕获，传入 QwenAgent 构造函数，并注入每个会话的 mergedSettings——正确防止按会话设置重载在单个进程生命周期内更改门控。
• 现有租约测试已更新为传入 sessionWriterLeaseEnabled: true，继续覆盖租约路径。新参数化测试覆盖三个门控否定场景和两个进程稳定性方向。

无关键阻塞项。无 AGENTS.md 违规。无过度抽象或重复。

CI 测试证据

precheck（lint、格式化、类型检查）通过。ubuntu 单元测试仍在运行中；macOS 和 Windows 等待 ubuntu 完成后执行。review-pr 和 route 取消是机器人编排作业（基础设施），不是 PR CI 测试。

未验证：实际 ACP/daemon 租约行为（需要多进程 ACP 环境，本次审查上下文中不可用）。作者报告了 macOS 测试；Windows 和 Linux 未经作者测试。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at a7892915769a985207dcee2b73a637d34234bf6d · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — Clean across every stage; would merge without hesitation once CI lands.

This is a textbook feature gate. The problem is real (#7237 auto-enables a cross-process protocol that's only safe when all writers participate), the solution is 48 lines of config plumbing with a strict boolean check and a process-stability snapshot, and the test coverage hits every gate-negative case plus both reload directions. The design doc and user docs are updated in the same PR. Nothing extraneous, nothing missing.

The one behavioral note: this changes the default from "lease active for all ACP sessions" to "lease off unless explicitly opted in." The PR calls this out clearly in the migration notes, and it's the correct tradeoff — a partially-participating lease is worse than no lease.

Approval deferred until CI lands green on a7892915769a985207dcee2b73a637d34234bf6d — ubuntu unit tests are still running.

中文说明

置信度：5/5 — 每个阶段都很干净；CI 通过后即可合并。

这是一个教科书级的功能开关。问题真实存在（#7237 自动启用了一个只有所有写入方都参与才安全的跨进程协议），方案是 48 行配置管道加严格布尔检查和进程稳定性快照，测试覆盖了所有门控否定场景和两个重载方向。设计文档和用户文档在同一 PR 中更新。没有多余内容，也没有遗漏。

唯一的行为变化：默认值从"所有 ACP 会话启用租约"变为"除非显式启用否则关闭"。PR 在迁移说明中清楚说明了这一点，这是正确的权衡——部分参与的租约比没有租约更危险。

审批延迟至 CI 在 a7892915769a985207dcee2b73a637d34234bf6d 上全部通过后执行——ubuntu 单元测试仍在运行中。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at a7892915769a985207dcee2b73a637d34234bf6d · re-run with @qwen-code /triage}

[doudouOUC]

@qwen-code /takeover

[ytahdn]

Found one rollout-safety blocker. The restart-required lease gate is currently re-read for each ACP/daemon session, so a running process can contain both legacy and leased writers after the setting changes.

[doudouOUC]

整体 LGTM，改动本身正确，没有发现功能性 bug。以下是验证记录和几条建议。

已验证

项	结果
packages/core 全量 tsc --noEmit	✅
ESLint / Prettier（改动文件 + 两个 md）	✅
scripts/generate-settings-schema.ts 后 git status	✅ 无 drift
core: config.test.ts + session-writer-lease.test.ts + chatRecordingService.test.ts	✅ 528 passed / 1 skipped
cli: settingsSchema.test.ts + settingsUtils.test.ts	✅ 118 passed
cli: acp-integration/acpAgent.test.ts	✅ 323 passed
cli: config/config.test.ts	⚠️ 本地 @qwen-code/channel-github 解析失败，在 main 上同样失败，属本地 workspace 未 install 的环境问题，与本 PR 无关

关键降级路径逐条走查，确认安全：

• 构造顺序：sessionWriterLeaseEnabled 在 experimentalZedIntegration 之后赋值；构造函数内没有任何地方提前触发 getChatRecordingService()。
• 两条写入路径落在同一个文件：lease 路径 Config.getTranscriptPath() 与 legacy 路径 ensureConversationFile() 都解析到 <projectDir>/chats/<sessionId>.jsonl，所以开关来回切换不会把同一 session 的 transcript 劈成两份。
• 所有 lease 下游消费者都能正确退化：hasSessionWriteOwnership()（shutdownSessionConfig 不会误抛）、runWithWriteBarrier、enqueueRecordWrite（走 jsonl.writeLine）、resetStoragePaths（ACP /cd 不再抛错）、Config.assertCanStartTurn。
• 不存在漏传新参数的生产路径：全仓非测试 new Config( 只有 4 处，唯一设置 experimentalZedIntegration 的是 loadCliConfig；ACP 与 daemon（经 acp-bridge/spawnChannel.ts 的 --acp）都走它，PR 描述中 "ACP or daemon" 的说法成立。

需要讨论的三点

1. ChatRecordingService 构造函数的默认参数仍是旧 gate（见 packages/core/src/config/config.ts:6706 的行内评论）——生产无影响，但默认值现在与真实 gate 矛盾，失效模式是静默丢记录。
2. showInDialog: true 与同为 ACP/daemon-only 的 todoStopGuard（false）不一致，且交互式会话永远不可能启用它。
3. gate 从 merged settings 读取，workspace scope 可覆盖 —— 而 lease 的安全性质是机器全局的。

关于「默认关闭」这个决策

理由成立，Risk 段也如实披露了。需要 reviewer 明确知道的权衡是：#7237 修的「并发 ACP 写入方静默损坏 transcript」事故，从此对所有默认用户重新暴露，且该路径默认死掉后容易腐化。值得一并讨论的替代方案是「默认开启 + 紧急关闭开关」——混合版本的风险在旧二进制上本来就存在（旧 writer 根本不认识锁），本设置并不能消除它，它真正提供的是混合配置下的可控性。属产品决策，不反对当前选择。

[yiliang114]

LGTM — gate logic is sound (=== true strict comparison, compound ACP+opt-in check, private readonly freeze). Strictly more restrictive than prior behavior, no bypass path.

Two non-blocking suggestions:

1. Confirm daemon sessions set experimentalZedIntegration (likely true via ACP transport) — a code comment would help future readers.
2. Consider adding negative test cases for null, 1, and explicit false to guard against a future truthy-check refactor.

[ytahdn]

The rollout blocker is fixed in b4bab7a. The effective lease gate is now snapshotted at ACP process startup and forced into every new/load/resume session Config, with regression coverage for both setting-transition directions. No remaining blockers from my review.

[doudouOUC]

@qwen-code /triage

[yiliang114]

Re-review after b4bab7a + a789291: freeze semantics are sound (snapshot before first await, override per-session settings, constructor default). Recorder alignment maintains backward compat via ?? fallback chain. Previous P2s (daemon path confirmation, negative test cases) are resolved. 6 new test cases cover freeze both directions + recorder gate. No regressions to legacy/interactive paths. LGTM.

[qwen-code-ci-bot]

Triage re-run completed without a new review.

⚠️ The bot has no review of its own on a7892915769a985207dcee2b73a637d34234bf6d. If this re-run was meant to approve, it did not — an approval left by another account is a separate vote and does not count as the bot's own.

The stage comments above were updated with the latest result. View workflow run.

[qwen-code-ci-bot]

⚠️ Downgraded from Approve to Comment: CI still running. Reviewed.

中文说明

⚠️ 已从批准降级为评论：CI still running。 已审查。

— qwen3.7-max via Qwen Code /review

[qwen-code-ci-bot]

LGTM, looks ready to ship — CI landed green after the review. ✅

[qwen-code-ci-bot]

Released in v0.21.1.

[yiliang114]

⚠️ Failed to process this request. Please re-mention the bot to retry.