chainlesschain 0.162.163 → 0.162.164

package/src/data/changelog.json

@@ -3,7 +3,7 @@
   "releases": [
     {
       "productVersion": "Unreleased",
-      "cliVersion": "0.162.163",
+      "cliVersion": "0.162.164",
       "cliVersions": [
         "0.4.46",
         "0.4.51",
@@ -21,14 +21,15 @@
         "0.162.160",
         "0.162.161",
         "0.162.162",
-        "0.162.163"
+        "0.162.163",
+        "0.162.164"
       ],
       "date": null,
       "title": "",
       "sections": [
         {
-          "heading": "Added — cc CLI 0.162.163：增量 gap-analysis last-mile 运行时接线收尾 + REPL /goal·coverage-aware /rewind + Monitor 源扩展 + 每任务调度策略 + Plugin/Schedule 工具增强（CLI-only npm 发版）",
-          "body": "> `chainlesschain` 0.162.162 → **0.162.163** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。命令面只加子命令（`cc agenda prune`、`cc plugin consent`、`cc hook replay`/`events-log`、`cc context --sources`）与 REPL slash（`/goal`）+ 工具参数/flag，**顶层命令数 175 不变**。本版把 0.162.162 announce 的多数纯核落成真实**运行时接线**，并补齐 `docs/CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12.md` 各节的 last-mile「仍欠」。全套本地三层全绿（unit+integration 25,008 + e2e 628，0 真失败）。\n\n- **Subagent 契约全轴强制（P1）**：`_executeSpawnSubAgent` 真正消费 `resolveSubagentContract`（spawnArgs > agent-file > 父级天花板），tighten-only 强制 skills/mcp/hooks/memory capability INTERSECT、permissionMode（plan→只读工具集）、budget/effort/context、worktree fail-closed、递归深度/宽度上限；非 plan confirmer 线程化 + headless 与交互 REPL 均以运行模式播种子级天花板；子级专属无 confirmer ApprovalGate 强制 run_shell/run_code/browser_act 会话策略。\n- **跨 Agent 授权边界接线（P0）**：本地 headless 审批链路携带并校验 `tool_call_id + normalized_arguments + policy_digest` 绑定（重放/参数替换/错投的批准判 `binding-mismatch` 拒绝）；入站 channel 事件显式打 steer authority（其载荷里的 \"approved\" 只是文本，不能代表用户批准）。\n- **会话完成条件引擎接线（P1）**：`--goal-condition <spec>`（exit-zero/file-exists/contains/regex/model）驱动 headless 外层回合，跨进程 `--resume` 续跑（持久 `goal_snapshot`），REPL `/goal <condition>` 交互入口；`goal_started/evaluated/completed/exhausted` 事件。\n- **Turn↔Checkpoint 绑定持久化 + coverage-aware /rewind（P1）**：绑定作为链式会话事件持久化；`/rewind` 打印诚实的 coverage/警告（副作用 / 缺 checkpoint / 对话-文件漂移），永不过度承诺可恢复范围。\n- **副作用台账崩溃恢复（P0 纯核）**：`side-effect-ledger.js` 两阶段记账 `prepare→start→commit|fail|unknown` + `reconcileSideEffects` 分桶 redo/inspect/skip（file-write/git-push/package-install 中途强杀不重复副作用）。\n- **持久 Scheduler/Monitor 扩展（P1）**：`cc agenda prune`（回收终态条目）+ 过期退休（`expiresAt`/`retireExpired`）+ Monitor 文件/HTTP/mtime-change 源（替每 tick spawn shell）+ agent `schedule` 工具透传 `expires`/`jitter` + 每任务 permission-mode/worktree/turn 预算。\n- **Plugin 能力 consent 生命周期（P1）**：consent 存储 + load-path chokepoint enforcement（opt-in）+ `cc plugin consent` + `add`/`upgrade` 渲染能力清单+diff+re-consent 提示 + doctor 未同意/坏 manifest 告警。\n- **Monorepo 上下文（P1）**：`instructionExcludes` 从分层 settings 接进 `composeSystemPrompt`（排除 legacy/vendor/generated 子树，含 @import）+ `cc context --sources`（逐来源 token 归因）+ 懒加载子树指令纯核。\n- **Hooks 持久事件日志 + Replay（P2）**：哈希链 JSONL 事件日志（opt-in `CC_HOOK_EVENT_LOG`）+ `cc hook replay`（决策类事件必显式 `--sandbox`，绝不 re-gate 真流程）/`cc hook events-log`（列出/校验链）。\n- **JSON Schema（P2）**：`--json-schema` 接受 inline JSON + 与 `stream-json` 兼容（终局 `structured_result` NDJSON 行）+ format/if-then-else 断言 + 约束式重试改用富校验器（带 RFC 6901 JSON Pointer 提示）。\n- **多 Agent Review（P2）**：`cc review --multi`（correctness/security/performance/tests 分维 finder 扇出）+ `--verify`（skeptic 复现剔除 refuted）+ high effort 自动双开。\n- **OTel（P2）**：`--otlp-content` opt-in 输出 prompt/response/tool_arguments（默认脱敏 `[redacted]`）+ 每 span 归一化 session/agent id。"
+          "heading": "Added — cc CLI 0.162.164：IDE 增量 gap-analysis (2026-07-13) 全批接线落地——凭据脱敏三导出面 / /rewind 从这里分支 / cc doctor 执行位置 / cc session pr-status / 复杂 Diff 行评论锚定 / 终端上下文策略 / worktree 清理安全闸 / 崩溃恢复台账 / 无人值守动作门 / 跨设备操作指纹（CLI-only npm 发版）",
+          "body": "> `chainlesschain` 0.162.163 → **0.162.164** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。命令面只加 **session 子命令 `cc session pr-status`** 与 REPL `/rewind <n> --branch`、`cc doctor` 新增「Execution context」诊断段 + 工具 flag，**顶层命令数 175 不变**。本版把 `docs/CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md` 的可 Windows 落地项整批接线（纯核已建、本版补真实运行时/命令面接线，默认路径保持字节不变）。\n\n- **8.1 凭据脱敏三导出面全闸**：一份导出物离机必须朝「不泄漏」失败——`cc session export` 导出前对渲染 transcript 跑召回优先 secret-scan（命中替 `[REDACTED]`，脱敏计数写 stderr，`--no-redact` 保原值）；OTLP `toOtlp()` 对 span/event 字符串属性（含 exception message）默认脱敏（`cc agent/team --otlp`、`cc eval`）；诊断包 `cc doctor --export-bundle` 强制脱敏（P1-9）。三面共用同一 recall-first 扫描器。\n- **P0-2 崩溃恢复副作用台账**：两阶段记账 `prepare→start→commit|fail|unknown` 接进 headless 与 IDE/Bridge/Extension-Host resume——`--resume` reconcile 台账，started-未落定-非幂等 op 注入去标识「Recovery notice」而非盲目重跑；Diff-Apply 内容哈希幂等（old 已改+new 已在→幂等 no-op 不重写）；外部操作 Idempotency Key + 0-重复副作用度量。\n- **P0-3「从这里分支」进 `/rewind`**：`/rewind <n> --branch [--write]`（`--fork` 别名）从选中 turn 派生独立会话，保留分支点之前历史并从此分叉，**父会话绝不被截断**；确定性分支 id + `session_branch` 血统事件 + 幂等重放 + traversal fail-closed。\n- **P1-1 复杂 Diff 行评论锚定**：review finding 锚到它所指的**代码**（file+baseHash+锚定行原文+上下文）而非裸坐标；agent 改文件后可 `reanchorComment` 重定位/标 outdated，绝不复用旧行号（接进 `review-pipeline` finding 输出 + `cc review` 尽力填 fileContents）。\n- **P1-2 终端上下文策略 + 后台任务脱敏**：`selectTerminalContextForModel` fail-closed（非显式 opt-in 绝不把终端 scrollback 塞进模型上下文）+ ANSI-strip→secret-redact→scrollback-cap；`check_shell {list}` / `/tasks` 后台任务快照对命令串脱敏并暴露 PID（stoppable 仅在握真 PID 时）。\n- **P1-4 PR/CI 监控 + 受控合并**：新子命令 `cc session pr-status [id] [--pr N] [--checks-file <json>] [--enable] [--json]`——从 PR-link ledger 取会话关联 PR，`gh pr view` 或 `--checks-file` 采信号，渲染状态条 + **默认关**的 auto-merge 合格性判定（穷举列未满足项：分支保护/Review/待审批/失败或 pending check/缺席必需 check）。\n- **P1-5 worktree 清理安全闸**：后台 agent worktree reaper 清理前过 fail-closed 安全闸——未提交/未追踪/未 push/关联 PR 任一命中即**保留**（旧「全清」逃生门 `force:true` 保留）；`git` 读不出→保留（绝不销毁无法核实的工作）。\n- **P1-6 会话级 agent 工具准入 + 归因**：extension 层工具（run_skill/spawn_sub_agent/browser/schedule/publish_artifact/MCP）需 Capability+Policy+权限+预算+UI 五闸全过；每次调用记只带来源的安全归因（可落 transcript）。\n- **P1-7 执行位置一等属性**：`cc doctor` 新增「Execution context」诊断段——检测 ambient location（Codespaces/SSH/Container/WSL/Local），remote/unknown fail-closed 到只读地板并列 policy 违规；凭据只显示来源/作用域不显示值。\n- **P1-8 无人值守动作门**：`cc agenda` 定时/事件任务默认拦截 notify/publish_artifact 等高危外呼（`unattendedAllowlist` 显式放回）；action-class 分级 fail-closed。\n- **P1-9 脱敏诊断包**：`cc doctor --export-bundle` 一键导出去标识诊断包（版本/平台/Capability/连接/脱敏事件/进程·端口·锁文件·worktree 摘要；默认不含源码/Key/Cookie/完整环境变量；导出前强制 secret-scan）。\n- **8.2 跨设备操作指纹**：远程审批 `remote-approval-bridge` 升级到全元组 `OperationApprovalRegistry`（工具名/规范化参数/目标环境/workspace/session/策略版本/有效期）；`permission.request` 发完整指纹 + 短标识 + 无秘密摘要，`approval.resolve` 失败关闭（mismatch/superseded/duplicate/过窗）。\n- **Monorepo / P2 硬化**：worktree `sparsePaths` 稀疏检出 + `symlinkDirectories` 逃逸守卫接进 team runner；`cc doctor` 新增沙箱真能力/静默降级、重复 skill 影子、settings.json hook 配置静态校验、async-hook 可靠性健康检查；LSP 服务器可选指数退避重启；每 span 归一 OTel session/agent id + `permission.decision_id`。\n\n> `chainlesschain` 0.162.162 → **0.162.163** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。命令面只加子命令（`cc agenda prune`、`cc plugin consent`、`cc hook replay`/`events-log`、`cc context --sources`）与 REPL slash（`/goal`）+ 工具参数/flag，**顶层命令数 175 不变**。本版把 0.162.162 announce 的多数纯核落成真实**运行时接线**，并补齐 `docs/CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12.md` 各节的 last-mile「仍欠」。全套本地三层全绿（unit+integration 25,008 + e2e 628，0 真失败）。\n\n- **Subagent 契约全轴强制（P1）**：`_executeSpawnSubAgent` 真正消费 `resolveSubagentContract`（spawnArgs > agent-file > 父级天花板），tighten-only 强制 skills/mcp/hooks/memory capability INTERSECT、permissionMode（plan→只读工具集）、budget/effort/context、worktree fail-closed、递归深度/宽度上限；非 plan confirmer 线程化 + headless 与交互 REPL 均以运行模式播种子级天花板；子级专属无 confirmer ApprovalGate 强制 run_shell/run_code/browser_act 会话策略。\n- **跨 Agent 授权边界接线（P0）**：本地 headless 审批链路携带并校验 `tool_call_id + normalized_arguments + policy_digest` 绑定（重放/参数替换/错投的批准判 `binding-mismatch` 拒绝）；入站 channel 事件显式打 steer authority（其载荷里的 \"approved\" 只是文本，不能代表用户批准）。\n- **会话完成条件引擎接线（P1）**：`--goal-condition <spec>`（exit-zero/file-exists/contains/regex/model）驱动 headless 外层回合，跨进程 `--resume` 续跑（持久 `goal_snapshot`），REPL `/goal <condition>` 交互入口；`goal_started/evaluated/completed/exhausted` 事件。\n- **Turn↔Checkpoint 绑定持久化 + coverage-aware /rewind（P1）**：绑定作为链式会话事件持久化；`/rewind` 打印诚实的 coverage/警告（副作用 / 缺 checkpoint / 对话-文件漂移），永不过度承诺可恢复范围。\n- **副作用台账崩溃恢复（P0 纯核）**：`side-effect-ledger.js` 两阶段记账 `prepare→start→commit|fail|unknown` + `reconcileSideEffects` 分桶 redo/inspect/skip（file-write/git-push/package-install 中途强杀不重复副作用）。\n- **持久 Scheduler/Monitor 扩展（P1）**：`cc agenda prune`（回收终态条目）+ 过期退休（`expiresAt`/`retireExpired`）+ Monitor 文件/HTTP/mtime-change 源（替每 tick spawn shell）+ agent `schedule` 工具透传 `expires`/`jitter` + 每任务 permission-mode/worktree/turn 预算。\n- **Plugin 能力 consent 生命周期（P1）**：consent 存储 + load-path chokepoint enforcement（opt-in）+ `cc plugin consent` + `add`/`upgrade` 渲染能力清单+diff+re-consent 提示 + doctor 未同意/坏 manifest 告警。\n- **Monorepo 上下文（P1）**：`instructionExcludes` 从分层 settings 接进 `composeSystemPrompt`（排除 legacy/vendor/generated 子树，含 @import）+ `cc context --sources`（逐来源 token 归因）+ 懒加载子树指令纯核。\n- **Hooks 持久事件日志 + Replay（P2）**：哈希链 JSONL 事件日志（opt-in `CC_HOOK_EVENT_LOG`）+ `cc hook replay`（决策类事件必显式 `--sandbox`，绝不 re-gate 真流程）/`cc hook events-log`（列出/校验链）。\n- **JSON Schema（P2）**：`--json-schema` 接受 inline JSON + 与 `stream-json` 兼容（终局 `structured_result` NDJSON 行）+ format/if-then-else 断言 + 约束式重试改用富校验器（带 RFC 6901 JSON Pointer 提示）。\n- **多 Agent Review（P2）**：`cc review --multi`（correctness/security/performance/tests 分维 finder 扇出）+ `--verify`（skeptic 复现剔除 refuted）+ high effort 自动双开。\n- **OTel（P2）**：`--otlp-content` opt-in 输出 prompt/response/tool_arguments（默认脱敏 `[redacted]`）+ 每 span 归一化 session/agent id。"
         },
         {
           "heading": "Added — cc CLI 0.162.162：增量 gap-analysis 收尾（P1 Subagent 契约/Turn-Checkpoint 绑定/Plugin 能力 Schema + P2 Hooks 事件总线/JSON Schema/多 Agent Review + LSP 诊断/Doctor+文档+OTel）+ IDE gap P0（远程审批指纹/会话生命周期）（CLI-only npm 发版）",

package/src/gateways/ws/session-protocol.js

@@ -5,6 +5,46 @@ import {
   CODING_AGENT_EVENT_TYPES,
 } from "../../runtime/runtime-events.js";
 import { createSessionRecord } from "../../runtime/contracts/session-record.js";
+import { loadSideEffectLedger } from "../../lib/side-effect-ledger-store.js";
+import { reconcileSideEffects } from "../../lib/side-effect-ledger.js";
+
+/**
+ * P0-2: on a bridge/IDE resume, surface any irreversible tool that was in flight
+ * when the prior worker died. Returns a de-identified recovery descriptor (kind
+ * + short key + reason, never argument values) plus a human-readable notice, or
+ * null when nothing needs verification. PURE apart from reading the ledger.
+ */
+function buildResumeRecovery(sessionId) {
+  try {
+    const ledger = loadSideEffectLedger(sessionId);
+    const plan = reconcileSideEffects(ledger);
+    if (!plan.inspect.length) return null;
+    const items = plan.plans
+      .filter((p) => p.action === "inspect")
+      .map((p) => {
+        const op = ledger.get(p.opId) || {};
+        return {
+          kind: op.kind || "unknown",
+          key: op.key || null,
+          reason: p.reason,
+        };
+      });
+    const notice =
+      "Recovery notice — the previous run was interrupted while these " +
+      "irreversible operations were in flight; their outcome is UNKNOWN. Do " +
+      "NOT blindly re-run them. Verify whether each already took effect before " +
+      "repeating it, and ask the user if unsure:\n" +
+      items
+        .map(
+          (it) =>
+            `  • [${it.kind}]${it.key ? ` (${it.key})` : ""} — ${it.reason}`,
+        )
+        .join("\n");
+    return { count: items.length, items, notice };
+  } catch {
+    return null;
+  }
+}
 
 // Build a unified envelope for a solicited WS response. The bridge correlates
 // by `requestId` (the inbound request's id) and unwraps `payload` for callers
@@ -226,6 +266,14 @@ export async function handleSessionResume(server, id, ws, message) {
     status: "resumed",
   });
 
+  // P0-2: reconcile the crash-safe side-effect ledger. If a dangerous tool was
+  // in flight when the prior worker died, warn the IDE client AND inject a
+  // system note so the resumed model does not silently replay it.
+  const recovery = buildResumeRecovery(session.id);
+  if (recovery && Array.isArray(session.messages)) {
+    session.messages.push({ role: "system", content: recovery.notice });
+  }
+
   server.emit(
     RUNTIME_EVENTS.SESSION_RESUME,
     createRuntimeEvent(
@@ -235,6 +283,7 @@ export async function handleSessionResume(server, id, ws, message) {
         historyCount: history.length,
         sessionType: session.type || null,
         record,
+        ...(recovery ? { recovery } : {}),
       },
       { kind: "server", sessionId: session.id },
     ),
@@ -249,6 +298,7 @@ export async function handleSessionResume(server, id, ws, message) {
         sessionId: session.id,
         history,
         record,
+        ...(recovery ? { recovery } : {}),
       },
       session.id,
     ),

package/src/gateways/ws/ws-agent-handler.js

@@ -12,6 +12,12 @@
  */
 
 import { agentLoop, formatToolArgs } from "../../runtime/agent-core.js";
+import { classifyToolSideEffect } from "../../lib/side-effect-ledger.js";
+import {
+  loadSideEffectLedger,
+  persistSideEffectLedger,
+} from "../../lib/side-effect-ledger-store.js";
+import { operationIdempotencyKey } from "../../lib/idempotency.js";
 import {
   detectTaskType,
   selectModelForTask,
@@ -35,6 +41,9 @@ export class WSAgentHandler {
     this._processing = false;
     this._abortController = null;
     this._activeRequestId = null;
+    // P0-2: monotonic sequence for crash-safe side-effect ledger op ids. The
+    // session id + a per-op nonce keep ids unique across turns and processes.
+    this._sideEffectSeq = 0;
   }
 
   /**
@@ -120,6 +129,14 @@ export class WSAgentHandler {
         signal: abortController.signal,
       };
 
+      // P0-2: crash-safe side-effect ledger for the IDE/bridge path — mirrors
+      // the headless runner. A dangerous tool is recorded prepare→start (snapshot
+      // persisted BEFORE it settles) and commit/fail on its result, so a bridge
+      // worker killed mid-flight is surfaced for verification on resume (see
+      // handleSessionResume) instead of being blindly replayed.
+      const sideEffectLedger = loadSideEffectLedger(session.id);
+      let currentSideEffectOpId = null;
+
       for await (const event of agentLoop(session.messages, loopOptions)) {
         switch (event.type) {
           case "slot-filling":
@@ -137,6 +154,28 @@ export class WSAgentHandler {
               args: event.args,
               display: formatToolArgs(event.tool, event.args),
             });
+            currentSideEffectOpId = null;
+            {
+              const se = classifyToolSideEffect(event.tool, event.args);
+              if (se) {
+                const opId = `ws:${session.id}:${Date.now()}:${this._sideEffectSeq++}`;
+                currentSideEffectOpId = opId;
+                sideEffectLedger
+                  .prepare(opId, {
+                    kind: se.kind,
+                    key: se.key,
+                    meta: {
+                      tool: event.tool,
+                      idempotencyKey: operationIdempotencyKey({
+                        tool: event.tool,
+                        args: event.args,
+                      }),
+                    },
+                  })
+                  .start(opId);
+                persistSideEffectLedger(session.id, sideEffectLedger);
+              }
+            }
             break;
 
           case "tool-result":
@@ -146,6 +185,17 @@ export class WSAgentHandler {
               result: event.result,
               error: event.error,
             });
+            if (currentSideEffectOpId) {
+              const err = event.error || event.result?.error || null;
+              if (err)
+                sideEffectLedger.fail(
+                  currentSideEffectOpId,
+                  String(err).slice(0, 200),
+                );
+              else sideEffectLedger.commit(currentSideEffectOpId);
+              persistSideEffectLedger(session.id, sideEffectLedger);
+              currentSideEffectOpId = null;
+            }
             break;
 
           case "response-complete":

package/src/harness/jsonl-session-store.js

@@ -385,6 +385,66 @@ export function forkSession(sourceId) {
   return newId;
 }
 
+/**
+ * Create an independent BRANCH session ("从这里分支" — P0-3's fourth restore
+ * action) that keeps a parent's conversation up to a chosen turn and diverges
+ * from there. Unlike forkSession() (whole-session copy, random id, no lineage),
+ * this writes ONLY the caller-supplied pre-branch messages under a deterministic
+ * id (see deriveBranchSessionId) and records parent lineage — so the origin
+ * session is never touched (preservesParent) and a replayed branch request
+ * resolves to the SAME file instead of a duplicate (idempotent).
+ *
+ * @param {object} params
+ * @param {string} params.branchSessionId   deterministic branch id
+ * @param {string|null} [params.parentSessionId]
+ * @param {string|null} [params.parentTurnId]
+ * @param {Array<{role:string,content:any}>} [params.messages]  pre-branch turns
+ * @param {{title?:string,provider?:string,model?:string}} [params.meta]
+ * @returns {{branchSessionId:string, created:boolean, messages:number}}
+ */
+export function createBranchSession({
+  branchSessionId,
+  parentSessionId = null,
+  parentTurnId = null,
+  messages = [],
+  meta = {},
+} = {}) {
+  if (isUnsafeSessionId(branchSessionId)) {
+    throw new Error(
+      `unsafe branch session id: ${String(branchSessionId).slice(0, 60)}`,
+    );
+  }
+  // Idempotent: a replayed branch request resolves to the existing branch
+  // rather than doubling it (matches deriveBranchId's determinism).
+  if (existsSync(sessionPath(branchSessionId))) {
+    return { branchSessionId, created: false, messages: 0 };
+  }
+
+  startSession(branchSessionId, {
+    title: meta.title || `Branch of ${parentSessionId ?? "session"}`,
+    provider: meta.provider || "",
+    model: meta.model || "",
+  });
+  appendEvent(branchSessionId, "session_branch", {
+    parentSessionId: parentSessionId == null ? null : String(parentSessionId),
+    parentTurnId: parentTurnId == null ? null : String(parentTurnId),
+  });
+
+  let count = 0;
+  for (const m of Array.isArray(messages) ? messages : []) {
+    if (!m || m.role == null) continue;
+    if (m.role === "user") {
+      appendUserMessage(branchSessionId, m.content);
+      count += 1;
+    } else if (m.role === "assistant") {
+      appendAssistantMessage(branchSessionId, m.content);
+      count += 1;
+    }
+    // system prompt + tool scaffolding are re-established on resume; skip here.
+  }
+  return { branchSessionId, created: true, messages: count };
+}
+
 export function sessionExists(sessionId) {
   if (isUnsafeSessionId(sessionId)) return false; // never resolve a traversal id
   return existsSync(sessionPath(sessionId));

package/src/harness/worktree-isolator.js

@@ -8,8 +8,8 @@
  */
 
 import { execSync } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, rmSync, symlinkSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
 import {
   isGitRepo,
   gitExec,
@@ -17,10 +17,15 @@ import {
   assertSafeGitRef,
   assertSafeGitPath,
 } from "../lib/git-integration.js";
+import { evaluateWorktreeCleanup } from "../lib/worktree-cleanup-safety.js";
+import {
+  normalizeSparsePaths,
+  planSymlinkDirectories,
+} from "../lib/worktree-sparse.js";
 
 const WORKTREE_DIR = ".worktrees";
 
-export function createWorktree(repoDir, branchName, baseBranch) {
+export function createWorktree(repoDir, branchName, baseBranch, options = {}) {
   assertSafeGitRef(branchName, "branch name");
   if (baseBranch) assertSafeGitRef(baseBranch, "base branch");
   if (!isGitRepo(repoDir)) {
@@ -40,7 +45,46 @@ export function createWorktree(repoDir, branchName, baseBranch) {
   const base = baseBranch || "HEAD";
   gitExec(`worktree add "${worktreePath}" -b "${branchName}" ${base}`, repoDir);
 
-  return { path: worktreePath, branch: branchName };
+  const result = { path: worktreePath, branch: branchName };
+
+  // Sparse checkout: only materialize the packages this task needs. For a
+  // large monorepo this cuts worktree creation time and disk. Cone mode wants
+  // directory paths — our sparsePaths are package dirs. Fail-closed on unsafe
+  // paths (normalizeSparsePaths drops them); empty/absent → full checkout,
+  // byte-identical to the no-sparse path.
+  const sparsePaths = normalizeSparsePaths(options.sparsePaths);
+  if (sparsePaths) {
+    for (const p of sparsePaths) assertSafeGitPath(p, "sparse path");
+    gitExecArgs(["sparse-checkout", "set", ...sparsePaths], worktreePath);
+    result.sparsePaths = sparsePaths;
+  }
+
+  // Dependency reuse: link explicitly-approved directories (e.g. node_modules)
+  // from the main checkout into the worktree so the task does not reinstall.
+  // planSymlinkDirectories throws (fail-closed) on any junction/symlink escape.
+  if (options.symlinkDirectories != null) {
+    const plan = planSymlinkDirectories(options.symlinkDirectories, {
+      repoDir,
+      worktreePath,
+    });
+    const linked = [];
+    for (const { name, source, dest } of plan) {
+      if (!existsSync(source)) continue; // approved but absent — nothing to reuse
+      if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
+      mkdirSync(dirname(dest), { recursive: true });
+      // 'junction' on Windows needs no admin and works for directories;
+      // 'dir' elsewhere. Both resolve to an absolute source we validated.
+      symlinkSync(
+        source,
+        dest,
+        process.platform === "win32" ? "junction" : "dir",
+      );
+      linked.push(name);
+    }
+    if (linked.length > 0) result.symlinkedDirectories = linked;
+  }
+
+  return result;
 }
 
 export function removeWorktree(repoDir, worktreePath, options = {}) {
@@ -145,12 +189,103 @@ export async function isolateTask(repoDir, taskId, fn) {
   }
 }
 
-export function cleanupAgentWorktrees(repoDir) {
+/**
+ * Gather the cleanup-safety state of one worktree for
+ * [[worktree-cleanup-safety.js]] `evaluateWorktreeCleanup`. Fail-closed: any git
+ * command that cannot be read leaves the worktree marked unverifiable (→ kept).
+ * `linkedPrs` is not known at this layer (no PR store here) and is left empty;
+ * a higher layer that knows about PRs can call `evaluateWorktreeCleanup` itself.
+ */
+function _worktreeCleanupState(repoDir, wt) {
+  const state = {
+    readable: true,
+    uncommitted: false,
+    untracked: false,
+    unpushed: false,
+    linkedPrs: [],
+  };
+
+  // Dirty state: separate tracked modifications from untracked files.
+  try {
+    const porcelain = execSync("git status --porcelain", {
+      cwd: wt.path,
+      encoding: "utf-8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    const lines = porcelain.split("\n").filter((l) => l.trim().length > 0);
+    state.untracked = lines.some((l) => l.startsWith("??"));
+    state.uncommitted = lines.some((l) => !l.startsWith("??"));
+  } catch (_e) {
+    state.readable = false; // cannot verify → fail-closed keep
+    return state;
+  }
+
+  // Unpushed: only relevant if the branch has commits beyond the repo HEAD; if
+  // it does, they are unpushed unless a remote branch contains them.
+  try {
+    assertSafeGitRef(wt.branch, "branch name");
+    if (_hasBranchCommits(repoDir, wt.branch)) {
+      const remotes = gitExecArgs(
+        ["branch", "-r", "--contains", wt.branch],
+        repoDir,
+      );
+      state.unpushed = remotes.trim().length === 0;
+    }
+  } catch (_e) {
+    state.unpushed = true; // cannot prove the commits are pushed → keep
+  }
+
+  return state;
+}
+
+/**
+ * Assess (read-only) which `agent/*` worktrees are safe to remove. Returns the
+ * per-worktree decision from [[worktree-cleanup-safety.js]] without deleting
+ * anything — the "清理前检查未提交修改、未追踪文件、未 Push Commit 和关联 PR"
+ * report from IDE gap P1-5.
+ */
+export function assessAgentWorktreeCleanup(repoDir) {
+  const worktrees = listWorktrees(repoDir);
+  const assessments = [];
+  for (const wt of worktrees) {
+    if (!(wt.branch && wt.branch.startsWith("agent/"))) continue;
+    const state = _worktreeCleanupState(repoDir, wt);
+    const decision = evaluateWorktreeCleanup(state);
+    assessments.push({
+      path: wt.path,
+      branch: wt.branch,
+      safeToRemove: decision.safeToRemove,
+      blockers: decision.blockers,
+    });
+  }
+  return {
+    assessments,
+    removable: assessments.filter((a) => a.safeToRemove).length,
+    kept: assessments.filter((a) => !a.safeToRemove).length,
+  };
+}
+
+/**
+ * Remove `agent/*` worktrees. By DEFAULT this is now fail-closed: a worktree
+ * with uncommitted / untracked / unpushed work (or one whose state cannot be
+ * read) is KEPT, not force-deleted — the P1-5 data-loss guard. Pass
+ * `{ force: true }` for the legacy "wipe every agent worktree" behavior.
+ *
+ * @returns {number} count of worktrees actually removed
+ */
+export function cleanupAgentWorktrees(repoDir, options = {}) {
+  const force = options.force === true;
   const worktrees = listWorktrees(repoDir);
   let cleaned = 0;
 
   for (const wt of worktrees) {
     if (wt.branch && wt.branch.startsWith("agent/")) {
+      if (!force) {
+        const decision = evaluateWorktreeCleanup(
+          _worktreeCleanupState(repoDir, wt),
+        );
+        if (!decision.safeToRemove) continue; // keep work we cannot safely lose
+      }
       try {
         removeWorktree(repoDir, wt.path, { deleteBranch: true });
         cleaned++;

package/src/lib/agent-schedule-store.js

@@ -26,6 +26,7 @@ import { randomUUID } from "crypto";
 import { isEntryExpired, effectiveFireAt } from "./schedule-planner.js";
 import { SUBAGENT_PERMISSION_MODES } from "./subagent-contract.js";
 import { parseGoalCondition } from "./goal-condition-engine.js";
+import { normalizeActionClass } from "./unattended-action-policy.js";
 
 export const SCHEDULE_KINDS = Object.freeze(["wakeup", "cron", "monitor"]);
 
@@ -83,6 +84,7 @@ export function normalizeRunPolicy({
   goalMaxCost = null,
   goalMaxTime = null,
   maxOuterTurns = null,
+  unattendedAllowlist = null,
 } = {}) {
   const policy = {};
   if (
@@ -119,6 +121,17 @@ export function normalizeRunPolicy({
       if (Number.isFinite(outer) && outer > 0) policy.maxOuterTurns = outer;
     }
   }
+
+  // P1-8: action classes this UNATTENDED task may still perform (e.g. "publish",
+  // "external_message"). Validated against the known classes; unknowns dropped.
+  // Absent → the scheduled run gets the default-deny high-risk tool set.
+  if (Array.isArray(unattendedAllowlist)) {
+    const cleaned = [
+      ...new Set(unattendedAllowlist.map(normalizeActionClass).filter(Boolean)),
+    ];
+    if (cleaned.length > 0) policy.unattendedAllowlist = cleaned;
+  }
+
   return Object.keys(policy).length > 0 ? policy : null;
 }
 
@@ -575,7 +588,13 @@ export class AgentScheduleStore {
    */
   recordMonitorCheck(
     id,
-    { matched = false, atMs = null, mtimeMs = null } = {},
+    {
+      matched = false,
+      atMs = null,
+      mtimeMs = null,
+      eventId = null,
+      authority = null,
+    } = {},
   ) {
     const now = atMs != null ? atMs : this._now();
     return this._mutate("monitor", id, (entry) => {
@@ -590,6 +609,16 @@ export class AgentScheduleStore {
       if (matched) {
         entry.status = "matched";
         entry.matchedAt = now;
+        // Audit record of the firing: the deterministic monitor-event id + the
+        // (always SYSTEM/steer) authority the event was delivered under. Durable
+        // on the entry so `cc agenda list --json` and a future resident daemon
+        // can recognise / dedup the exact observation. Only stamped when the
+        // caller supplies them, so legacy callers stay byte-identical.
+        if (eventId != null) {
+          entry.lastEventId = String(eventId);
+          entry.lastEventAt = now;
+        }
+        if (authority != null) entry.lastAuthority = String(authority);
       } else if (entry.maxChecks != null && entry.checks >= entry.maxChecks) {
         entry.status = "exhausted";
       } else {

package/src/lib/agent-team/team-worktree.js

@@ -22,8 +22,31 @@ import {
   mergeWorktree as _mergeWorktree,
 } from "../../harness/worktree-isolator.js";
 import { isGitRepo as _isGitRepo } from "../../lib/git-integration.js";
+import { normalizeSparsePaths } from "../../lib/worktree-sparse.js";
 import { execFileSync, spawn } from "node:child_process";
 
+/**
+ * Resolve the sparse-checkout / dependency-symlink options for a task, letting a
+ * per-task value (from the plan) override the coordinator-wide default. Returns
+ * `undefined` when nothing is configured so `createWorktree` takes its unchanged
+ * full-checkout path (byte-identical to before this feature).
+ */
+function resolveWorktreeOptions(task, defaults) {
+  const t = task || {};
+  const sparse = normalizeSparsePaths(
+    t.sparsePaths ?? t.metadata?.sparsePaths ?? defaults.sparsePaths ?? null,
+  );
+  const symlink =
+    t.symlinkDirectories ??
+    t.metadata?.symlinkDirectories ??
+    defaults.symlinkDirectories ??
+    null;
+  const opts = {};
+  if (sparse) opts.sparsePaths = sparse;
+  if (symlink != null) opts.symlinkDirectories = symlink;
+  return Object.keys(opts).length ? opts : undefined;
+}
+
 function defaultRunShell(command, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, { cwd, shell: true, env: process.env });
@@ -72,9 +95,15 @@ export const _deps = {
 };
 
 export class TeamWorktreeCoordinator {
-  constructor(repoDir) {
+  constructor(repoDir, options = {}) {
     this.repoDir = repoDir;
     this._created = new Map(); // key → { branch, path, committed }
+    // Coordinator-wide sparse-checkout / dependency-symlink defaults; a per-task
+    // value (task.sparsePaths / task.metadata.sparsePaths) overrides these.
+    this._worktreeDefaults = {
+      sparsePaths: options.sparsePaths ?? null,
+      symlinkDirectories: options.symlinkDirectories ?? null,
+    };
   }
 
   isGitRepo() {
@@ -114,7 +143,13 @@ export class TeamWorktreeCoordinator {
         }
         this._created.delete(key);
       }
-      const { path: worktreePath } = _deps.createWorktree(this.repoDir, branch);
+      const wtOptions = resolveWorktreeOptions(task, this._worktreeDefaults);
+      const { path: worktreePath } = _deps.createWorktree(
+        this.repoDir,
+        branch,
+        null,
+        wtOptions,
+      );
       this._created.set(key, { branch, path: worktreePath, committed: false });
       if (typeof runInWorktree === "function") {
         await runInWorktree({ key, task, holder, cwd: worktreePath });