chainlesschain 0.162.166 → 0.162.168

package/src/commands/agent.js

@@ -506,6 +506,11 @@ export function registerAgentCommand(program) {
       let _worktree = null;
       let _worktreeFinished = false;
       let _finishAgentWorktreeFn = null;
+      // Settings hooks loaded once at worktree setup, reused by both the
+      // WorktreeCreate producer and the WorktreeRemove producer in
+      // _finishWorktree(). Null unless --worktree is active + hooks loaded.
+      let _worktreeSettingsHooks = null;
+      let _worktreeAsyncSupervisor = null;
       if (options.worktree) {
         try {
           const { setupAgentWorktree, finishAgentWorktree } =
@@ -516,6 +521,43 @@ export function registerAgentCommand(program) {
           process.stderr.write(
             `worktree: ${_worktree.path} (branch ${_worktree.branch})\n`,
           );
+          // WorktreeCreate lifecycle hook (observe-only, best-effort): a fresh
+          // isolated worktree just appeared — let automation react (register it
+          // with a tracker, seed per-branch tooling). Loaded from the REPO ROOT
+          // (its committed/user-level .claude hooks apply). No-op & byte-unchanged
+          // without a registered WorktreeCreate hook; never blocks the session.
+          try {
+            const { loadHooks } = await import("../lib/settings-hooks.cjs");
+            _worktreeSettingsHooks =
+              loadHooks({ cwd: _worktree.repoRoot }).hooks || null;
+            const { runWorktreeCreateHooks, dispatchAsyncHooks } =
+              await import("../lib/settings-hook-events.cjs");
+            runWorktreeCreateHooks(_worktreeSettingsHooks, {
+              worktreePath: _worktree.path,
+              branch: _worktree.branch,
+              baseSha: _worktree.baseSha,
+              cwd: _worktree.path,
+            });
+            if (!_worktreeAsyncSupervisor) {
+              const { AsyncHookSupervisor } =
+                await import("../lib/async-hook-supervisor.cjs");
+              _worktreeAsyncSupervisor = new AsyncHookSupervisor({
+                persistStats: true,
+              });
+            }
+            dispatchAsyncHooks(
+              _worktreeSettingsHooks,
+              "WorktreeCreate",
+              {
+                worktree_path: _worktree.path,
+                branch: _worktree.branch,
+                base_sha: _worktree.baseSha,
+              },
+              { cwd: _worktree.path, supervisor: _worktreeAsyncSupervisor },
+            );
+          } catch {
+            /* worktree lifecycle hooks are best-effort — never block */
+          }
           // The worktree is created BEFORE flag validation, and several
           // `process.exit(1)` guards below (plus any future ones) would skip the
           // normal cleanup and orphan an empty worktree + branch on disk. A sync
@@ -548,6 +590,39 @@ export function registerAgentCommand(program) {
               ? `worktree removed (${fin.reason}).\n`
               : `worktree kept (${fin.reason}): ${_worktree.path}\n${fin.mergeHint ? `  merge: ${fin.mergeHint}\n` : ""}`,
           );
+          // WorktreeRemove lifecycle hook (observe-only, best-effort): teardown
+          // just resolved — fire with `removed` distinguishing an auto-removed
+          // empty worktree from one kept for its changes. Reuses the hooks loaded
+          // at setup; no-op & byte-unchanged without a registered hook.
+          if (_worktreeSettingsHooks) {
+            try {
+              const { runWorktreeRemoveHooks, dispatchAsyncHooks } =
+                await import("../lib/settings-hook-events.cjs");
+              runWorktreeRemoveHooks(_worktreeSettingsHooks, {
+                worktreePath: _worktree.path,
+                branch: _worktree.branch,
+                removed: fin.removed === true,
+                reason: fin.reason,
+                cwd: _worktree.repoRoot,
+              });
+              dispatchAsyncHooks(
+                _worktreeSettingsHooks,
+                "WorktreeRemove",
+                {
+                  worktree_path: _worktree.path,
+                  branch: _worktree.branch,
+                  removed: fin.removed === true,
+                  reason: fin.reason,
+                },
+                {
+                  cwd: _worktree.repoRoot,
+                  supervisor: _worktreeAsyncSupervisor,
+                },
+              );
+            } catch {
+              /* WorktreeRemove firing is best-effort */
+            }
+          }
         } catch {
           /* keep silently — never block exit */
         }

package/src/commands/session.js

@@ -967,6 +967,18 @@ export function registerSessionCommand(program) {
     .option("--rebuild", "Force a full re-index (ignore mtime cache)")
     .option("--stats", "Show index-wide counters")
     .option("--mirror <ids...>", "Push session id(s) to the configured mirror")
+    .option(
+      "--mirror-delete <ids...>",
+      "Delete session id(s) from the configured mirror",
+    )
+    .option(
+      "--mirror-prune",
+      "Delete mirror entries whose session no longer exists locally (retention)",
+    )
+    .option(
+      "--mirror-rotate",
+      "Re-encrypt all mirrored sessions from session.mirror.encryptionPrevious to session.mirror.encryption (key rotation)",
+    )
     .option(
       "--limit <n>",
       "Max rows for search/list",
@@ -996,6 +1008,48 @@ export function registerSessionCommand(program) {
           return;
         }
 
+        if (options.mirrorDelete && options.mirrorDelete.length) {
+          const result = await mirrorDeleteSessions(options.mirrorDelete);
+          if (options.json) return console.log(JSON.stringify(result, null, 2));
+          if (!result.target)
+            return logger.log(chalk.yellow("No mirror configured."));
+          for (const id of result.deleted)
+            logger.log(chalk.green(`  deleted ${id} from mirror`));
+          for (const r of result.errors) logger.error(`  ${r.id}: ${r.error}`);
+          return;
+        }
+
+        if (options.mirrorPrune) {
+          const result = await mirrorPruneSessions();
+          if (options.json) return console.log(JSON.stringify(result, null, 2));
+          if (!result.target)
+            return logger.log(chalk.yellow("No mirror configured."));
+          logger.log(
+            chalk.green(
+              `  pruned ${result.deleted.length} orphaned mirror entr${
+                result.deleted.length === 1 ? "y" : "ies"
+              } (${result.kept.length} kept)`,
+            ),
+          );
+          return;
+        }
+
+        if (options.mirrorRotate) {
+          const result = await mirrorRotateKey();
+          if (options.json) return console.log(JSON.stringify(result, null, 2));
+          if (!result.target)
+            return logger.log(chalk.yellow("No mirror configured."));
+          if (result.error) return logger.error(`  ${result.error}`);
+          logger.log(
+            chalk.green(
+              `  rotated ${result.rotated.length} session(s) to key "${result.keyId}"` +
+                ` (${result.skipped.length} already current)`,
+            ),
+          );
+          for (const r of result.failed) logger.error(`  ${r.id}: ${r.error}`);
+          return;
+        }
+
         if (options.stats) {
           const st = idx.indexStats(db);
           if (options.json) return console.log(JSON.stringify(st, null, 2));
@@ -1781,6 +1835,84 @@ async function mirrorSessions(ids) {
   return { target: mirror.target, pushed, errors };
 }
 
+/** Load the configured mirror (or null). Shared by every mirror subcommand. */
+async function loadConfiguredMirror() {
+  const { createMirror } = await import("../harness/session-mirror.js");
+  let cfg = {};
+  try {
+    cfg =
+      (await import("../lib/config-manager.js")).loadConfig()?.session
+        ?.mirror || {};
+  } catch {
+    cfg = {};
+  }
+  return { mirror: createMirror(cfg), cfg };
+}
+
+/** Delete session id(s) from the configured off-box mirror. */
+async function mirrorDeleteSessions(ids) {
+  const store = await import("../harness/jsonl-session-store.js");
+  const { mirror } = await loadConfiguredMirror();
+  if (!mirror) return { target: null, deleted: [], errors: [] };
+  const deleted = [];
+  const errors = [];
+  for (const id of ids) {
+    try {
+      if (store.isUnsafeSessionId(id)) throw new Error("unsafe session id");
+      await mirror.delete(id);
+      deleted.push(id);
+    } catch (err) {
+      errors.push({ id, error: err.message });
+    }
+  }
+  return { target: mirror.target, deleted, errors };
+}
+
+/**
+ * Retention prune: delete mirror entries whose session no longer exists in the
+ * local store (the mirror is one-way derived, so local is the source of truth).
+ */
+async function mirrorPruneSessions() {
+  const store = await import("../harness/jsonl-session-store.js");
+  const { pruneMirror } = await import("../harness/session-mirror.js");
+  const { mirror } = await loadConfiguredMirror();
+  if (!mirror) return { target: null, deleted: [], kept: [] };
+  const keep = store.listSessionIds();
+  const res = await pruneMirror(mirror, { keep });
+  return { target: mirror.target, ...res };
+}
+
+/**
+ * Key rotation: re-encrypt every mirrored session from the PREVIOUS key
+ * (`session.mirror.encryptionPrevious`) to the CURRENT key
+ * (`session.mirror.encryption`). Requires both to be configured.
+ */
+async function mirrorRotateKey() {
+  const { createMirror, createMirrorCipher, rotateMirrorKey } =
+    await import("../harness/session-mirror.js");
+  const { cfg } = await loadConfiguredMirror();
+  if (!cfg || !cfg.kind || cfg.kind === "none") {
+    return { target: null };
+  }
+  const prev = cfg.encryptionPrevious || cfg.encryptionOld;
+  const next = cfg.encryption;
+  if (!prev?.passphrase || !next?.passphrase) {
+    return {
+      target: cfg.dir || cfg.baseUrl || cfg.url || null,
+      error:
+        "rotation needs both session.mirror.encryptionPrevious and session.mirror.encryption passphrases",
+    };
+  }
+  // Drive the RAW driver (createMirror without encryption) so rotation manages
+  // the ciphertext itself with the two explicit ciphers.
+  const raw = createMirror({ ...cfg, encryption: undefined });
+  const res = await rotateMirrorKey(raw, {
+    from: createMirrorCipher(prev),
+    to: createMirrorCipher(next),
+  });
+  return { target: raw.target, ...res };
+}
+
 // === Iter21 V2 governance overlay ===
 export function registerSesgovV2Commands(program) {
   const parent = program.commands.find((c) => c.name() === "session");

package/src/data/changelog.json

@@ -3,7 +3,7 @@
   "releases": [
     {
       "productVersion": "Unreleased",
-      "cliVersion": "0.162.166",
+      "cliVersion": "0.162.168",
       "cliVersions": [
         "0.4.46",
         "0.4.51",
@@ -24,11 +24,17 @@
         "0.162.163",
         "0.162.164",
         "0.162.165",
-        "0.162.166"
+        "0.162.166",
+        "0.162.167",
+        "0.162.168"
       ],
       "date": null,
       "title": "",
       "sections": [
+        {
+          "heading": "Added — cc CLI 0.162.168：增量 gap-analysis 第二批接线——后台 Agent「等待审批」真实状态 + hook 事件溯源（trace/parent）+ LSP 多根与重启退避默认开 + 严格 hook 合并真并行 + 大仓 subagent worktree/子树指令 + run_code install 审计（CLI-only npm 发版）",
+          "body": "> `chainlesschain` 0.162.167 → **0.162.168** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量（10 个 feat commit + 测试 + gap-analysis 文档状态）；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。**无新增顶层命令，命令数 175 不变**。绝大多数改动 opt-in / 默认路径字节不变；**两处默认行为变化**（均可 env 关）：LSP 重启退避默认开（`CC_LSP_RESTART_BACKOFF_MS=0` 恢复旧行为）与子树指令懒注入默认开（`CC_SUBTREE_INSTRUCTIONS=0` 关）。\n\n- **P0 后台 Agent：`waiting_permission` 真实生产者**：后台 agent 卡在人工审批（`--permission-prompt-tool` / `--remote-control`）时不再永远显示 \"Working\"——agent 子进程（经 worker 注入的 `CC_BACKGROUND_AGENT_ID`）在审批 pending 期间把 `phase:\"waiting_permission\"` + 实时 `pendingApprovals` 计数写进共享 state，settle 即恢复；Dashboard \"Needs input\" 分组从此有真数据。前台运行返回同一 confirmer 函数对象、零 IO 字节不变；worker 在每回合开始与 idle 重置计数，被 SIGKILL 于审批中途的子进程不会把会话永久钉在 \"Needs input\"。\n- **P0 沙箱：统一 install 审计扩到 `run_code`**：分类器新识别模块调用 `python`/`python3`/`py` `-m pip install …`（含 `sudo` 包裹；`-m http.server`/`-m venv`/`setup.py install` 不误报）；`run_code` 的 pip 自动安装 installed/failed 尝试在同一 opt-in 策略（`CC_INSTALL_AUDIT` / settings `installPolicy`）下落统一 `install-commands.jsonl`（`source:\"run_code_auto_install\"` + pip 分类 + global 判定）——一份审计覆盖所有「下载并运行第三方代码」入口。\n- **P2 Hooks：strictest-merge 决策合并（opt-in `CC_HOOK_STRICT_MERGE=1`）+ PreToolUse 真并行**：修掉真实安全缺口——原按序短路下**较早**的一个 `ask` 会掩盖**较晚**一个 hook 的 `block`（blocker 根本没跑）。开启后跑完全部匹配 hook 取最严（block>ask>allow>continue）；PreToolUse 路径经异步 spawn **真并行**（wall-clock=最慢单 hook 而非求和，硬超时 SIGKILL 挂死 hook）。默认关=逐字节原短路行为。\n- **P2 Hooks：trace_id/parent_id 事件溯源**：PreToolUse / PostToolUse / PermissionRequest / SubagentStop 四个 payload 构造点现带 `event_id` + `trace_id`（本 run）+ `parent_id`（spawn 方 run）；`spawn_sub_agent` 与隔离 `run_skill` 把父 trace 线程进子 loop，子 agent 的 hook 事件跨深度关联回父 trace。未线程时字段整个省略——legacy payload 字节不变；`CC_HOOK_EVENT_LOG` 开启时这些决策事件顺带可被 `cc hook replay` 寻址。\n- **P2 LSP：重启退避默认开 + 多根 workspace**：池化语言服务器重启退避默认 1s→2s→4s→8s 封顶（启动即崩的 server 不再毫秒级连爆 `maxRestarts` 次；`CC_LSP_RESTART_BACKOFF_MS` 覆盖、`=0` 恢复立即重生）。`code_intelligence` 现按**包含该文件的根**（containment 最深根胜）key 共享 server 池——`--add-dir` 根内的文件拿到它自己项目的语言服务器而非 cwd 的；`workspace_symbols` 跨全部根扇出合并、逐 symbol 标注 `root`。单根会话字节不变。\n- **P1 大仓：子树指令懒注入（tool-time）**：工具**首次访问**某子树（read_file / list_dir / write_file / edit_file / edit_file_hashed）时把该子树自带的 `cc.md`/`CLAUDE.md`/`AGENTS.md` 附到工具结果的 `subtreeInstructions` 字段（每子树每进程恰一次，honor `instructionExcludes`，fail-open）——monorepo 里 per-package 规则不再要求启动时全量注入。子树无指令文件（常态）零成本；`CC_SUBTREE_INSTRUCTIONS=0` 整体关闭。同批：post-edit 诊断从未排序裸 cap 20 改为 **severity 优先 + token 预算**封顶（error 先于 warning，`CC_EDIT_DIAGNOSTICS_TOKENS` 默认 2000）。\n- **P1 subagent/大仓三项收尾**：①subagent worktree spawn 透传 `sparsePaths`/`symlinkDirectories`（spawn-arg 胜 agent-file；隔离 worktree 只 checkout 任务需要的包 + junction 复用依赖目录）；②agent-file frontmatter `background: true` 现真生效（此前只认调用方显式传参）；③headless `--add-dir` 启动根 seed——`cc agent -p --add-dir` 现把完整根列表告知已连 MCP 服务器（`roots/list_changed`），此前它们的 `roots/list` 永远只见 cwd。\n\n> `chainlesschain` 0.162.166 → **0.162.167** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量（+ 测试 + gap-analysis 文档状态更新）；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。**无新增顶层命令，命令数 175 不变**；所有改动 opt-in / 默认路径字节不变。本版把 `docs/CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12.md` 的多个可 Windows 落地「仍欠」项整批接线。\n\n- **P0 沙箱：run_shell 远程脚本执行检测**：新增统一「代码获取」分类器——把 20+ 包管理器安装命令（npm/pip/cargo/gem/go/apt/…）与 `curl … | sh` / `wget -O- | bash` 一类**下载即执行**的远程脚本归为一类，在 shell 审批时抬高风险地板并落审计（记录带 `remoteExec` 标记）；`cat script.sh | sh`（本地文件）与 `curl -O file`（仅下载不执行）不误报。默认路径字节不变。\n- **P2 生命周期事件钩子——4 个命令层生产者**：为新的 settings.json 生命周期事件类型接上真实触发点（此前它们只在事件总线注册、无生产者、loader 不认、`cc doctor` 还会当 unknown-event 告警用户配的钩子）：`CwdChanged`（REPL `/cd` 改工作目录后）、`WorktreeCreate`/`WorktreeRemove`（`cc agent --worktree` 会话 create/finish 一对，payload 含 branch/base_sha，remove 带 `removed`/`reason` 区分自动删与保留）、`InstructionsLoaded`（会话启动组装完项目指令块后，携本会话权威指令文件清单 `{path,scope,truncated}`，**绝不含文件内容**）。全部 observe-only、无注册 hook 时字节不变；`InstructionsLoaded` 经 `composeSystemPrompt` 可选回调拿**真正注入**的那份文件集（零漂移，非另行 re-discover）。三处会话入口（headless / stream / REPL）与 SessionStart 同点触发。\n- **P2 Doctor：孤儿 agent 子进程检测**：`cc doctor` 现从持久化的后台 agent 记录探活，标出「worker 已死但子进程仍在」或「会话已消失」的泄漏进程为 error 并给对应 `taskkill`/`kill` 修复命令（进程起始时间锚定，防 PID 复用误判；仅喂持久记录不做启发式全机扫描 → 零误报）。\n- **4 项杂项 gap 接线**：①async-hook 持久重唤队列 + 崩溃恢复（失败的 async-hook 重唤按会话落盘，`--resume` 时作「Recovery notice」系统消息恢复）；②monorepo 附加根变更时向连接的 MCP 服务器广播 roots/list_changed（`/add-dir` + 启动 `--add-dir`）；③`cc doctor` LSP 就绪安装缺口检查（源文件在但对应语言服务器未装 → 代码智能静默降级为文本搜索时告警）；④Session Mirror at-rest 加密/删除/保留/密钥轮换（scrypt+AES-256-GCM，`cc session index --mirror-delete` / `--mirror-prune` / `--mirror-rotate`）。"
+        },
         {
           "heading": "Added — cc CLI 0.162.166：P1-9「Capability Manifest 与脱敏诊断包」收官——协议文档 CI byte-diff / 离线协议回放 / 治理覆盖率指标（CLI-only npm 发版）",
           "body": "> `chainlesschain` 0.162.165 → **0.162.166** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量（新增 3 个 `src/lib` 纯逻辑模块 + 3 个 `scripts/` 离线工具 + 测试）；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。**只加 npm 脚本 + 离线工具,无新增顶层命令,命令数 175 不变**;默认路径字节不变。本版把 `docs/CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md` 的 P1-9 三个剩项全部收口。\n\n- **协议能力文档 CI byte-diff 单源生成**：新增生成器 `scripts/gen-protocol-doc.mjs`（`--out`/`--check`）从唯一源 `capability-manifest.js` `renderProtocolDoc()` 投影出 `docs/cli/PROTOCOL_CAPABILITY_MANIFEST.generated.md`（协议版本 + 可协商 wire 特性表 + 权限模式）；npm 脚本 `docs:protocol` / `docs:protocol:check`；`capability-manifest.test.js` 新增 byte-diff 断言（读签入副本 = `renderProtocolDoc()`），manifest 加 wire 字段但未重生成即测试红——drift 不可能 merge 绿。\n- **离线协议回放 + 兼容审计**：新增 `protocol-replay.js`——拿一段录制的 stream-json 会话 + 协商上下文（server×client offer），**无需活体对端**离线①回放到该协商下的线上形态（未通过协商的字段按 field-gate 剥离）②审计录制是否遵守协商（任何帧携带已 gate-OFF 的可协商 wire 字段 = 前向兼容违规,fail-closed）。可 gate 字段集从唯一源 `toFieldGate()` 投影不会漂移；`sessionDigest` 键序无关可 pin golden 录制。离线工具 `scripts/replay-protocol.mjs`（`--replay`/`--audit`,违规 exit 1）+ golden fixture。\n- **治理覆盖率指标（§11.3 验收）**：新增 `governance-coverage.js`——①高风险 Tool Call Ledger/Trace 覆盖率（每个不可逆副作用调用须既有 side-effect-ledger 记录又有 trace span,「高风险」复用唯一源 `classifyToolSideEffect`）②Plugin/MCP/Skill/Hook 溯源可追溯率（外部来源调用须带 source+version+scope+权限决策）;`ok` 仅双 100% 才真(fail-closed),给逐条未覆盖项。离线工具 `scripts/coverage-report.mjs`（读 run-summary JSON,任一 gap exit 1,可对录制 run 工件 CI 强制 100%）。"

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

@@ -118,6 +118,15 @@ export function verifyAllSessions(options = {}) {
     .map((file) => verifySession(basename(file, ".jsonl")));
 }
 
+/** All locally-stored session ids (the source of truth a mirror derives from). */
+export function listSessionIds() {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => file.endsWith(".jsonl"))
+    .map((file) => basename(file, ".jsonl"));
+}
+
 export { TRANSCRIPT_CHAIN_STATUS };
 
 export function startSession(sessionId, meta = {}) {

package/src/harness/session-mirror.js

@@ -26,10 +26,20 @@ import {
   readFileSync,
   writeFileSync,
   readdirSync,
+  unlinkSync,
 } from "node:fs";
+import {
+  scryptSync,
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+} from "node:crypto";
 import { join, basename } from "node:path";
 import { isUnsafeSessionId } from "./jsonl-session-store.js";
 
+const CIPHER_VERSION = 1;
+const CIPHER_ALGO = "aes-256-gcm";
+
 /**
  * Build a mirror driver from config. `config.kind` selects the driver:
  *   { kind: "fs",   dir: "/mnt/backup/sessions" }
@@ -39,15 +49,193 @@ import { isUnsafeSessionId } from "./jsonl-session-store.js";
 export function createMirror(config = {}, deps = {}) {
   const kind = String(config.kind || config.type || "none").toLowerCase();
   if (!kind || kind === "none") return null;
+  let driver;
   if (kind === "fs" || kind === "dir" || kind === "directory") {
-    return createFsMirror(config, deps);
+    driver = createFsMirror(config, deps);
+  } else if (kind === "http" || kind === "api") {
+    driver = createHttpMirror(config, deps);
+  } else {
+    throw new Error(
+      `unknown session mirror kind "${kind}" (use fs | http, or wire an s3/webdav/redis driver)`,
+    );
   }
-  if (kind === "http" || kind === "api") {
-    return createHttpMirror(config, deps);
+  // When `encryption` (a passphrase) is configured, wrap the driver so bytes are
+  // AES-256-GCM encrypted at rest — the mirror target only ever holds ciphertext,
+  // and only the run-time passphrase can decrypt it. Absent → raw bytes (the
+  // prior behaviour, byte-for-byte).
+  const enc = config.encryption || config.encrypt;
+  if (enc && (enc.passphrase || enc.secret)) {
+    return wrapEncryptedMirror(driver, createMirrorCipher(enc, deps));
   }
-  throw new Error(
-    `unknown session mirror kind "${kind}" (use fs | http, or wire an s3/webdav/redis driver)`,
-  );
+  return driver;
+}
+
+/**
+ * Passphrase-based AES-256-GCM cipher for mirrored session bytes. scrypt derives
+ * a 256-bit key from the passphrase + a per-record random salt; a random 12-byte
+ * nonce and the GCM tag give confidentiality + integrity (a tampered ciphertext
+ * fails to decrypt). Each envelope is self-describing JSON — `{ v, alg, keyId,
+ * salt, nonce, tag, ct }`, all base64url — carrying `keyId` so key ROTATION can
+ * tell old ciphertext from new. No secret is ever stored; only the passphrase
+ * supplied at run time can read it. `randomBytes`/`scryptSync` are injectable so
+ * round-trips are unit-testable deterministically.
+ */
+export function createMirrorCipher(config = {}, deps = {}) {
+  const passphrase = config.passphrase || config.secret;
+  if (!passphrase) throw new Error("mirror encryption requires a `passphrase`");
+  const keyId = String(config.keyId || "default");
+  const _randomBytes = deps.randomBytes || randomBytes;
+  const _scrypt = deps.scryptSync || scryptSync;
+  const deriveKey = (salt) => _scrypt(String(passphrase), salt, 32);
+
+  return {
+    keyId,
+    encrypt(bytes) {
+      const salt = Buffer.from(_randomBytes(16));
+      const nonce = Buffer.from(_randomBytes(12));
+      const cipher = createCipheriv(CIPHER_ALGO, deriveKey(salt), nonce);
+      const ct = Buffer.concat([
+        cipher.update(Buffer.from(bytes, "utf-8")),
+        cipher.final(),
+      ]);
+      return JSON.stringify({
+        v: CIPHER_VERSION,
+        alg: CIPHER_ALGO,
+        keyId,
+        salt: salt.toString("base64url"),
+        nonce: nonce.toString("base64url"),
+        tag: cipher.getAuthTag().toString("base64url"),
+        ct: ct.toString("base64url"),
+      });
+    },
+    decrypt(envelope) {
+      let e;
+      try {
+        e = typeof envelope === "string" ? JSON.parse(envelope) : envelope;
+      } catch {
+        throw new Error("mirror ciphertext is not a valid envelope");
+      }
+      if (!e || e.v !== CIPHER_VERSION || e.alg !== CIPHER_ALGO) {
+        throw new Error("unsupported mirror ciphertext envelope");
+      }
+      const key = deriveKey(Buffer.from(e.salt, "base64url"));
+      const decipher = createDecipheriv(
+        CIPHER_ALGO,
+        key,
+        Buffer.from(e.nonce, "base64url"),
+      );
+      decipher.setAuthTag(Buffer.from(e.tag, "base64url"));
+      const pt = Buffer.concat([
+        decipher.update(Buffer.from(e.ct, "base64url")),
+        decipher.final(),
+      ]);
+      return pt.toString("utf-8");
+    },
+    /** Read an envelope's keyId without decrypting (rotation bookkeeping). */
+    envelopeKeyId(envelope) {
+      try {
+        const e =
+          typeof envelope === "string" ? JSON.parse(envelope) : envelope;
+        return e && e.keyId != null ? String(e.keyId) : null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Wrap a driver so push encrypts and pull decrypts transparently, keeping the
+ * raw driver reachable as `.raw` (key rotation drives the raw driver with two
+ * ciphers). list/delete pass through — ids stay plaintext in the target (they
+ * are random handles, not content).
+ */
+function wrapEncryptedMirror(driver, cipher) {
+  return {
+    ...driver,
+    encrypted: true,
+    keyId: cipher.keyId,
+    raw: driver,
+    cipher,
+    async push(id, bytes) {
+      const enc = cipher.encrypt(bytes);
+      const r = await driver.push(id, enc);
+      return {
+        ...r,
+        bytes: Buffer.byteLength(bytes),
+        storedBytes: Buffer.byteLength(enc),
+        encrypted: true,
+      };
+    },
+    async pull(id) {
+      const raw = await driver.pull(id);
+      return raw == null ? null : cipher.decrypt(raw);
+    },
+  };
+}
+
+/**
+ * RETENTION: delete every mirror entry whose id is NOT in `keep` — the mirror is
+ * one-way derived from the local store, so retention = "hold only what the local
+ * source still keeps" (e.g. the ids `cc session list` still returns). Best-effort
+ * per id; returns what was deleted vs kept.
+ */
+export async function pruneMirror(mirror, { keep = [] } = {}) {
+  if (!mirror || typeof mirror.list !== "function") {
+    return { deleted: [], kept: [] };
+  }
+  const keepSet = new Set((keep || []).map(String));
+  const ids = (await mirror.list()) || [];
+  const deleted = [];
+  for (const id of ids) {
+    if (keepSet.has(String(id))) continue;
+    try {
+      await mirror.delete(id);
+      deleted.push(id);
+    } catch {
+      /* best-effort — a failed delete must not abort the prune */
+    }
+  }
+  return { deleted, kept: ids.filter((i) => keepSet.has(String(i))) };
+}
+
+/**
+ * KEY ROTATION: re-encrypt every mirrored session from the `from` cipher to the
+ * `to` cipher, in place. Drives the RAW driver (pass `mirror.raw` for an
+ * encrypted mirror) so it reads/writes ciphertext directly. Entries already at
+ * `to.keyId` are skipped (idempotent re-runs); an entry that fails to decrypt
+ * with `from` is reported, not silently dropped.
+ */
+export async function rotateMirrorKey(driver, { from, to } = {}) {
+  if (!driver || !from || !to) {
+    throw new Error("rotateMirrorKey requires (driver, { from, to })");
+  }
+  const ids = (await driver.list()) || [];
+  const rotated = [];
+  const skipped = [];
+  const failed = [];
+  for (const id of ids) {
+    let raw;
+    try {
+      raw = await driver.pull(id);
+    } catch (e) {
+      failed.push({ id, error: e.message });
+      continue;
+    }
+    if (raw == null) continue;
+    if (from.envelopeKeyId(raw) === to.keyId) {
+      skipped.push(id);
+      continue;
+    }
+    try {
+      const plain = from.decrypt(raw);
+      await driver.push(id, to.encrypt(plain));
+      rotated.push(id);
+    } catch (e) {
+      failed.push({ id, error: e.message });
+    }
+  }
+  return { rotated, skipped, failed, keyId: to.keyId };
 }
 
 /** Directory mirror — the reference driver. */
@@ -59,6 +247,7 @@ export function createFsMirror(config = {}, deps = {}) {
   const _readFileSync = deps.readFileSync || readFileSync;
   const _writeFileSync = deps.writeFileSync || writeFileSync;
   const _readdirSync = deps.readdirSync || readdirSync;
+  const _unlinkSync = deps.unlinkSync || unlinkSync;
 
   const ensure = () => {
     if (!_existsSync(dir)) _mkdirSync(dir, { recursive: true });
@@ -88,6 +277,12 @@ export function createFsMirror(config = {}, deps = {}) {
         .filter((f) => f.endsWith(".jsonl"))
         .map((f) => basename(f, ".jsonl"));
     },
+    async delete(id) {
+      const f = fileFor(id);
+      if (!_existsSync(f)) return { id, deleted: false };
+      _unlinkSync(f);
+      return { id, deleted: true };
+    },
   };
 }
 
@@ -138,5 +333,16 @@ export function createHttpMirror(config = {}, deps = {}) {
         .map((x) => (typeof x === "string" ? x : x?.id))
         .filter(Boolean);
     },
+    async delete(id) {
+      const res = await doFetch(`${baseUrl}/sessions/${guard(id)}`, {
+        method: "DELETE",
+        headers: headers(),
+      });
+      // 404 = already gone → idempotent success, not an error.
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`mirror DELETE ${id} → HTTP ${res.status}`);
+      }
+      return { id, deleted: res.ok };
+    },
   };
 }

package/src/harness/worktree-isolator.js

@@ -163,9 +163,17 @@ export function pruneWorktrees(repoDir) {
   return before - after;
 }
 
-export async function isolateTask(repoDir, taskId, fn) {
+export async function isolateTask(repoDir, taskId, fn, options = {}) {
   const branchName = `agent/${taskId}`;
-  const { path: worktreePath } = createWorktree(repoDir, branchName);
+  // options (large-monorepo): { sparsePaths, symlinkDirectories } forwarded to
+  // createWorktree so an isolated task only materializes the packages it needs
+  // and reuses approved dep dirs. Empty/absent → full checkout (byte-identical).
+  const { path: worktreePath } = createWorktree(
+    repoDir,
+    branchName,
+    undefined,
+    options || {},
+  );
 
   try {
     const result = await fn(worktreePath);

package/src/lib/agent-core.js

@@ -46,4 +46,5 @@ export {
   _resetFileFreshness,
   _getSharedCodeIntel,
   disposeSharedCodeIntel,
+  _resetSubtreeInstructionLoaders,
 } from "../runtime/agent-core.js";