@cr1992/agentkit 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/)。
 
+## Unreleased
+
+## 1.1.0 - 2026-09-07
+
+- 修复从待回收 worktree 自身执行 `reclaim` 时，目录删除后误判本地分支已不存在的问题；未完成的
+  branch cleanup 现在返回非零并可幂等重试。
+- `manage-worktrees` 持久化评审 watcher 的 pending/disabled 意图，让 `doctor` 与 `resume-all` 不再忽略未武装记录。
+- 新增 macOS `watch-service` LaunchAgent，为已登记 watcher 提供跨 Agent 会话与重启后的自动恢复触发。
+
 ## 1.0.0 - 2026-09-04
 
 - 将四个 Agent 工程 Skill 收敛为一个零依赖 Node.js CLI 与四个薄壳。

package/README.en.md

@@ -12,7 +12,7 @@ the `orchestrate-subagents` control plane, which then chooses lightweight or ful
 rerouting from effective capabilities, task scale, and local model policy. Providers remain independently usable and
 compose through frozen Artifact, Binding, and Evidence envelopes.
 
-[Detailed collaboration contracts and safety boundaries (Chinese, v1.0.0)](./docs/architecture/skill-system-architecture.md)
+[Detailed collaboration contracts and safety boundaries (Chinese, v1.1.0)](./docs/architecture/skill-system-architecture.md)
 
 ## Included skills
 
@@ -39,6 +39,18 @@ npm install -g @cr1992/agentkit
 agentkit doctor
 ```
 
+On macOS, explicitly install the per-repository user service when worktree merge watchers must recover across agent
+sessions and restarts:
+
+```bash
+agentkit worktree watch-service install
+agentkit worktree watch-service status
+```
+
+The npm install does not create a persistent service. The service pins the Node and agentkit paths present at install
+time; rerun `watch-service install` after moving either installation, and inspect `program_available` in
+`status --json`. Other platforms currently use `agentkit worktree resume-all` for manual recovery.
+
 ### Skills
 
 Install all four skills:

package/README.md

@@ -11,7 +11,7 @@
 其内部再按有效能力、任务规模、本地模型配置和验收证据选择轻量或完整运行方式及后续重路由。
 各 provider 仍可独立使用，并通过冻结的 Artifact、Binding 和 Evidence envelope 按需组合。
 
-[Agent Skills 协作契约与安全边界（v1.0.0）](./docs/architecture/skill-system-architecture.md)
+[Agent Skills 协作契约与安全边界（v1.1.0）](./docs/architecture/skill-system-architecture.md)
 
 ## 包含的 Skill
 
@@ -37,6 +37,17 @@ npm install -g @cr1992/agentkit
 agentkit doctor
 ```
 
+macOS 上若要让 worktree 合入监听跨 Agent 会话和重启持续恢复，可按仓库显式安装用户级维护器：
+
+```bash
+agentkit worktree watch-service install
+agentkit worktree watch-service status
+```
+
+它不会随 npm install 自动常驻。服务固定安装时的 Node 与 agentkit 路径；升级 agentkit、切换 Node
+安装位置后应重新执行 `watch-service install`，`status --json` 的 `program_available` 可检查原路径。
+其他平台当前使用 `agentkit worktree resume-all` 手工恢复。
+
 ### Skill
 
 安装全部 Skill：

package/docs/worktree/reclaim-and-watch.md

@@ -6,7 +6,15 @@
 
 监听绑定“冻结的 head SHA 已成为目标 ref 祖先”这一事实，不绑定 change request 载体。载体改为他人代推、
 聚合 MR 或其他分支时不解除监听。进入 `ready_for_review` 默认武装；`submit` 只是其中一个入口。电脑重启后
-由 `resume-all` 恢复 stale watcher；change request 已关闭且明确不会合入时用 `unwatch`。
+由 `resume-all` 恢复 stale watcher；macOS 要让这一步无需新 Agent 会话触发，显式安装用户级维护器：
+
+```bash
+agentkit worktree watch-service install
+```
+
+维护器定期执行有限的 `resume-all`，实际 watcher 仍用 token/event CAS 与 heartbeat 裁决；它不放宽任何
+回收前置条件。`watch-service status` 检查 plist、launchd job 与当前 Node/runtime 路径，`uninstall` 解除。
+未安装时只有进程级自动回收，不得称作跨会话保证。change request 已关闭且明确不会合入时用 `unwatch`。
 
 ## 已推送成果
 
@@ -20,6 +28,11 @@ agentkit worktree reclaim <task-or-id> --pushed <sha-or-unique-prefix>
 final_snapshot -> reclaim_ready -> git worktree remove -> branch cleanup -> reclaimed
 ```
 
+命令可以从待回收 worktree 自身发起；runtime 在删除目录前冻结 primary worktree 作为后续仓库级 Git
+操作的稳定 cwd。branch probe 只有在 `show-ref` 明确返回“不存在”时才记为 `absent`，cwd、权限或其他
+执行错误一律 fail closed。目录已删除但 branch cleanup 未完成时保留 `BRANCH_PENDING`，命令返回非零，
+从任一仍存在的 worktree 重跑同一 `reclaim` 完成对账。
+
 终态事件将非 `abandoned` 任务收敛为 `done`，并以最终 source HEAD 闭合 ownership epoch。旧版本若留下
 `reclaimed` 但状态或 epoch 未闭合，重复同一命令会追加 reconciliation event 后再对账。
 
@@ -88,7 +101,8 @@ agentkit worktree reclaim old-task \
 
 - `abandoned` 只冻结写入，不等于已回收；`doctor` 持续报告残留树和断裂替代关系。
 - 禁止 `rm -rf`、`git worktree remove --force` 和 `branch -D`。
-- branch cleanup 失败时保留 `BRANCH_PENDING`；修复占用后重跑相同 `reclaim`，工具重新验证 branch tip。
+- branch cleanup 失败时保留 `BRANCH_PENDING` 并返回非零；修复占用后从仍存在的 worktree 重跑相同
+  `reclaim`，工具重新验证 branch tip。
 - `git worktree remove` 失败返回非零 `KEEP` 并记录原始错误。即使 Git 登记已解除，物理目录仍在也不能
   标为 `reclaimed`；先恢复权限或登记关系，不用强删掩盖孤儿目录。
 - 含 submodule 的树逐个验证已初始化工作区干净，再自动 deinit 并清理该树私有元数据。submodule 脏、

package/docs/worktree/review-lifecycle.md

@@ -13,7 +13,22 @@ agentkit worktree touch <selector> --status ready_for_review
 `ready_for_review` 默认按该树登记的 `base_ref` 武装监听，Profile `default_base` 只在 record 没有 base 时
 兜底；显式 target 与既有人工 target 仍然优先。HEAD 前进时同一 event 使旧 watcher 失效，
 再尝试冻结新 HEAD。worktree dirty、HEAD 未推送或远端主干不可刷新时 fail-soft，状态更新成功但明确
-回报未武装原因。补齐前提后重跑，或用 `--no-watch` 明确接受人工回收。
+回报未武装原因，并把 `review_watch=auto/pending` 与原因写入 trace；`resume-all` 会重试。`--no-watch`
+则持久登记 `disabled`，与启动失败严格区分。`doctor` 对 pending、缺失 intent 和显式退出分别报告
+`AUTO_RECLAIM_NOT_ARMED`、`AUTO_RECLAIM_INTENT_MISSING` 与 `AUTO_RECLAIM_DISABLED`。
+
+进程级 watcher 只保证当前宿主允许后台进程存活期间的即时回收。需要跨 Agent 会话或机器重启：
+
+```bash
+agentkit worktree watch-service install
+agentkit worktree watch-service status --json
+```
+
+macOS adapter 安装用户级 LaunchAgent，每 60 秒（可用 `--interval-seconds` 调整）从 primary worktree
+运行一次 `resume-all`。安装是显式动作，不随 npm install 自动发生，不保存调用会话的环境变量或凭证。
+服务固定安装时的 Node 与 manager script 绝对路径；升级 agentkit 或切换 Node 安装位置后重跑 install，
+`status --json` 的 `program_available` 会检查这两个路径。卸载使用 `watch-service uninstall`。其他平台仍可
+手工运行 `resume-all`，在相应 service adapter 落地前不宣称跨会话保证。
 
 人工 `watch --target` 可改默认目标；已经显式武装的 target 不被静默改写，换目标先 `unwatch`。陈旧
 watcher 不能覆盖并发 rearm 或 `merge_detected`。旧 SHA 合入不代表新 HEAD 已完成。
@@ -88,5 +103,7 @@ agentkit worktree touch <selector> \
 未给 target 时使用 record 的 `base_ref`；远端 MR target 不同时先核对 provider/UI，再显式传
 真实目标。`--mr` 只接受 HTTP(S) URL；纯文本载体使用 `--change-ref`。
 
-watcher 只在冻结 SHA 成为目标 ref 祖先后回收。重启后 `resume-all` 恢复 stale watcher；change request
-关闭且确定不会合入时 `unwatch`。详细回收见 [reclaim-and-watch.md](reclaim-and-watch.md)。
+watcher 只在冻结 SHA 成为目标 ref 祖先后回收。`resume-all` 恢复 stale watcher 和已登记的 pending
+intent；对没有 intent 的 legacy 评审记录只报告 skipped，要求重新 `touch ready_for_review`，不猜测它
+是否曾显式 `--no-watch`。change request 关闭且确定不会合入时 `unwatch`。详细回收见
+[reclaim-and-watch.md](reclaim-and-watch.md)。

package/domains/worktree/worktree-core.mjs

@@ -346,7 +346,7 @@ export function readJsonFileOrDie(path, label) {
 export function parseArgs(argv) {
   const flags = new Map();
   const positionals = [];
-  const booleanFlags = new Set(['json', 'all', 'present', 'archived', 'verbose', 'recover-lock', 'no-watch', 'abort-on-conflict', 'no-rerere', 'recompose', 'scan-conflicts', 'abort', 'continue', 'pause-before-push']);
+  const booleanFlags = new Set(['json', 'all', 'present', 'archived', 'verbose', 'quiet', 'recover-lock', 'no-watch', 'abort-on-conflict', 'no-rerere', 'recompose', 'scan-conflicts', 'abort', 'continue', 'pause-before-push']);
   for (let index = 0; index < argv.length; index++) {
     const value = argv[index];
     if (!value.startsWith('--')) {

package/domains/worktree/worktree-doctor.mjs

@@ -35,6 +35,7 @@ export function createCommands(deps) {
     buildListing,
     learningRoot,
     isSettledWorktreeState,
+    watchServiceStatus,
   } = deps;
 
   function collectDoctorRecordMetadataFindings(loaded, listing, recordsById, record, findings) {
@@ -243,10 +244,45 @@ export function createCommands(deps) {
 
   /** @param {ReturnType<typeof loadRepositoryProfile>} loaded @param {Record<string,any>} record @param {Record<string,any>[]} findings */
   function collectDoctorRecordWatcherFindings(loaded, record, findings) {
-    if (record.auto_reclaim && !['disarmed', 'reclaimed'].includes(record.auto_reclaim.state) && record.worktree_state !== 'reclaimed') {
+    const reviewLifecycle = ['ready_for_review', 'integrating'].includes(record.task_status)
+      && !['reclaimed', 'archived'].includes(record.worktree_state);
+    const activeWatch = record.auto_reclaim && !['disarmed', 'reclaimed'].includes(record.auto_reclaim.state)
+      ? record.auto_reclaim
+      : null;
+    if (reviewLifecycle && !activeWatch) {
+      if (record.review_watch?.policy === 'disabled') {
+        findings.push({
+          code: 'AUTO_RECLAIM_DISABLED',
+          severity: 'warning',
+          worktree_id: record.worktree_id,
+          path: record.path,
+          detail: `已显式关闭跨会话回收（${record.review_watch.reason ?? 'no reason'}）；合入后需要人工 reclaim。`,
+        });
+      } else if (record.review_watch?.policy === 'auto') {
+        findings.push({
+          code: 'AUTO_RECLAIM_NOT_ARMED',
+          severity: 'error',
+          worktree_id: record.worktree_id,
+          path: record.path,
+          target_ref: record.review_watch.target_ref ?? null,
+          head_sha: record.review_watch.head_sha ?? null,
+          detail: record.review_watch.reason ?? '自动回收 intent 已登记，但 watcher 尚未武装；运行 resume-all 重试。',
+        });
+      } else {
+        findings.push({
+          code: 'AUTO_RECLAIM_INTENT_MISSING',
+          severity: 'error',
+          worktree_id: record.worktree_id,
+          path: record.path,
+          detail: `评审态 record 没有 watcher 或显式退出记录；运行 touch ${record.task} --status ready_for_review 重新登记。`,
+        });
+      }
+      return;
+    }
+    if (activeWatch) {
       const heartbeat = readWatcherHeartbeat(loaded.context.common_dir, record.worktree_id);
       const health = watcherHealth(record, heartbeat);
-      const advance = record.auto_reclaim.target_advance;
+      const advance = activeWatch.target_advance;
       if (advance) {
         const prediction = advance.prediction?.state ?? 'unknown';
         findings.push({
@@ -258,7 +294,7 @@ export function createCommands(deps) {
           severity: 'warning',
           worktree_id: record.worktree_id,
           path: record.path,
-          target_ref: record.auto_reclaim.target_ref,
+          target_ref: activeWatch.target_ref,
           target_sha: advance.target_sha,
           recorded_base_sha: advance.recorded_base_sha,
           prediction: advance.prediction,
@@ -462,6 +498,21 @@ export function createCommands(deps) {
       }
     }
     collectDoctorRecordFindings(loaded, listing, recordsById, findings);
+    const expectsDurableWatch = listing.rows.some((row) => row.record
+      && ['ready_for_review', 'integrating'].includes(row.record.task_status)
+      && (row.record.review_watch?.policy === 'auto'
+        || (row.record.auto_reclaim && !['disarmed', 'reclaimed'].includes(row.record.auto_reclaim.state))));
+    if (expectsDurableWatch) {
+      const service = watchServiceStatus(loaded);
+      if (service.supported && (!service.installed || !service.loaded || !service.program_available)) {
+        findings.push({
+          code: 'AUTO_RECLAIM_SERVICE_INACTIVE',
+          severity: 'warning',
+          path: service.plist_path ?? loaded.context.primary_worktree,
+          detail: '当前 watcher 只有进程级存活保证；运行 agentkit worktree watch-service install 启用跨会话恢复。',
+        });
+      }
+    }
     collectDoctorSupersessionFindings(listing, findings);
     collectDoctorSessionFindings(listing, findings);
     collectDoctorRuntimeFindings(loaded, findings);

package/domains/worktree/worktree-mgr.mjs

@@ -4,7 +4,7 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -25,6 +25,7 @@ import { createCommands as createLifecycleCommands } from './worktree-lifecycle.
 import { createCommands as createReclaimCommands } from './worktree-reclaim.mjs';
 import { createCommands as createReviewRefreshCommands } from './worktree-review-refresh.mjs';
 import { createCommands as createReviewWatchCommands } from './worktree-review-watch.mjs';
+import { createCommands as createWatchServiceCommands } from './worktree-watch-service.mjs';
 
 export { runFileCapture, runFileTry } from './worktree-process.mjs';
 export {
@@ -71,12 +72,16 @@ const dependencies = {
   statSync,
   writeFileSync,
   tmpdir,
+  homedir,
   basename,
   dirname,
   join,
   resolve,
   fileURLToPath,
   managerScript,
+  processPlatform: process.platform,
+  processExecPath: process.execPath,
+  processGetuid: () => typeof process.getuid === 'function' ? process.getuid() : 0,
   ...mergePreview,
   ...profile,
   ...provider,
@@ -119,6 +124,8 @@ const artifactCommands = createArtifactCommands(dependencies);
 assignNew(dependencies, artifactCommands, 'worktree-artifact');
 const learningCommands = createLearningCommands(dependencies);
 assignNew(dependencies, learningCommands, 'worktree-learning');
+const watchServiceCommands = createWatchServiceCommands(dependencies);
+assignNew(dependencies, watchServiceCommands, 'worktree-watch-service');
 const doctorCommands = createDoctorCommands(dependencies);
 
 export const batchFingerprint = batchCommands.batchFingerprint;
@@ -126,7 +133,7 @@ export const verifyArtifactEnvelope = artifactCommands.verifyArtifactEnvelope;
 
 function cmdCapabilities(args) {
   rejectUnknownFlags(args.flags, ['json']);
-  console.log(JSON.stringify({ skill: 'manage-worktrees', runtime_version: '1.3.0', contracts: { worktree_binding: [1], artifact_ref: [1], reflection_record: [1], improvement_proposal: [1], batch_result: [1] }, features: ['git-common-dir-ledger', 'ownership-epochs', 'artifact-verification', 'incident-reflection', 'proposed-only-improvement', 'batch-integrate', 'batch-conflict-scan', 'declared-post-integrate-steps', 'batch-result', 'evidence-archive-reclaim', 'durable-pushed-ref-proof', 'auto-armed-review-watch', 'review-target-advance-prediction', 'explicit-review-refresh', 'managed-history-rewrite', 'stack-parent-attribution', 'structured-change-registration'], content_digest: worktreeSkillDigest() }, null, 2));
+  console.log(JSON.stringify({ skill: 'manage-worktrees', runtime_version: '1.4.0', contracts: { worktree_binding: [1], artifact_ref: [1], reflection_record: [1], improvement_proposal: [1], batch_result: [1] }, features: ['git-common-dir-ledger', 'ownership-epochs', 'artifact-verification', 'incident-reflection', 'proposed-only-improvement', 'batch-integrate', 'batch-conflict-scan', 'declared-post-integrate-steps', 'batch-result', 'evidence-archive-reclaim', 'durable-pushed-ref-proof', 'auto-armed-review-watch', 'persistent-review-watch-intent', 'launchd-watch-service', 'review-target-advance-prediction', 'explicit-review-refresh', 'managed-history-rewrite', 'stack-parent-attribution', 'structured-change-registration'], content_digest: worktreeSkillDigest() }, null, 2));
 }
 
 function usage() {
@@ -165,7 +172,9 @@ doctor [--json] [--verbose]
 rebuild [<selector>] [--id <uuid>] [--recover-lock]
 watch <selector> [--target <remote/ref>] [--interval-ms <ms>] [--change-ref <text>] [--notify auto|off] [--id <uuid>]
 submit <selector> [--title <text>] [--description <text>] [--target <branch>] [--remote <name>] [--interval-ms <ms>] [--notify auto|off] [--id <uuid>]
-resume-all [--json]
+resume-all [--json] [--quiet]
+watch-service install|status|uninstall [--json] [--interval-seconds <seconds>]
+  macOS 用户级 LaunchAgent 定期运行 resume-all；显式安装，不在 npm install 时自动常驻
 unwatch <selector> [--id <uuid>]
 reclaim <selector> --pushed <sha> [--id <uuid>]
 reclaim <selector> --superseded-by <replacement-selector> [--discard <exact-old-head>] [--id <uuid>] [--replacement-id <uuid>]
@@ -211,6 +220,7 @@ function main(argv = process.argv.slice(2)) {
     submit: reviewCommands.cmdSubmit,
     watch: reviewCommands.cmdWatch,
     'resume-all': reviewCommands.cmdResumeAll,
+    'watch-service': watchServiceCommands.cmdWatchService,
     unwatch: reviewCommands.cmdUnwatch,
     'watch-worker': reviewCommands.cmdWatchWorker,
     reclaim: reclaimCommands.cmdReclaim,

package/domains/worktree/worktree-reclaim.mjs

@@ -281,19 +281,49 @@ export function createCommands(deps) {
     return refs.out.split('\n').filter(Boolean).filter((ref) => ref !== ownBranch).sort();
   }
 
+  /**
+   * 回收可以从目标 worktree 自身发起。目标目录一旦被移除，命令启动时的 current_worktree
+   * 就不再是合法 cwd；后续仓库级 Git 操作必须固定使用不会被本次回收删除的 primary worktree。
+   * @param {ReturnType<typeof loadRepositoryProfile>} loaded
+   */
+  function repositoryGitCwd(loaded) {
+    return loaded.context.primary_worktree ?? loaded.context.current_worktree;
+  }
+
+  /**
+   * `git show-ref --verify --quiet` 的退出码 1 才表示 ref 不存在。ENOENT、权限错误或其他
+   * operational failure 不能降级成 absent，否则会产生“branch=absent”假成功。
+   * @param {ReturnType<typeof loadRepositoryProfile>} loaded
+   * @param {Record<string,any>} record
+   */
+  function inspectLocalBranch(loaded, record) {
+    if (!record.branch) return { state: 'absent', reason: null };
+    const checked = gitTry(
+      ['show-ref', '--verify', '--quiet', `refs/heads/${record.branch}`],
+      repositoryGitCwd(loaded),
+    );
+    if (checked.ok) return { state: 'exists', reason: null };
+    const status = checked.error && typeof checked.error === 'object' && 'status' in checked.error
+      ? checked.error.status
+      : null;
+    if (status === 1) return { state: 'absent', reason: null };
+    return {
+      state: 'error',
+      reason: commandFailureReason(checked, `unable to inspect local branch ${record.branch}`),
+    };
+  }
+
   /** @param {ReturnType<typeof loadRepositoryProfile>} loaded @param {Record<string,any>} record */
   function localBranchExists(loaded, record) {
-    return Boolean(record.branch) && gitTry(
-      ['show-ref', '--verify', '--quiet', `refs/heads/${record.branch}`],
-      loaded.context.current_worktree,
-    ).ok;
+    return inspectLocalBranch(loaded, record).state !== 'absent';
   }
 
   /** @param {ReturnType<typeof loadRepositoryProfile>} loaded @param {Record<string,any>} record @param {string} pushed */
   function attemptLocalBranchCleanup(loaded, record, pushed) {
     const checkedAt = new Date().toISOString();
     const previousAttempts = Number(record.branch_cleanup?.attempts ?? 0);
-    if (!record.branch || !localBranchExists(loaded, record)) {
+    const branchState = inspectLocalBranch(loaded, record);
+    if (branchState.state === 'absent') {
       return {
         status: 'absent',
         branch: record.branch ?? null,
@@ -302,7 +332,17 @@ export function createCommands(deps) {
         reason: null,
       };
     }
-    if (!gitTry(['merge-base', '--is-ancestor', record.branch, pushed], loaded.context.current_worktree).ok) {
+    if (branchState.state === 'error') {
+      return {
+        status: 'failed',
+        branch: record.branch,
+        attempts: previousAttempts + 1,
+        checked_at: checkedAt,
+        reason: branchState.reason,
+      };
+    }
+    const cwd = repositoryGitCwd(loaded);
+    if (!gitTry(['merge-base', '--is-ancestor', record.branch, pushed], cwd).ok) {
       return {
         status: 'failed',
         branch: record.branch,
@@ -311,7 +351,7 @@ export function createCommands(deps) {
         reason: `local branch tip is not merged into pushed sha: ${pushed}`,
       };
     }
-    const removed = gitTry(['branch', '-D', '--', record.branch], loaded.context.current_worktree);
+    const removed = gitTry(['branch', '-D', '--', record.branch], cwd);
     if (removed.ok) {
       return {
         status: 'deleted',
@@ -332,8 +372,8 @@ export function createCommands(deps) {
 
   /** @param {ReturnType<typeof loadRepositoryProfile>} loaded @param {Record<string,any>} record @param {string} pushed */
   function reconcileReclaimedBranchCleanup(loaded, record, pushed) {
-    const branchExists = localBranchExists(loaded, record);
-    if (['deleted', 'absent'].includes(record.branch_cleanup?.status) && !branchExists) {
+    const branchState = inspectLocalBranch(loaded, record);
+    if (['deleted', 'absent'].includes(record.branch_cleanup?.status) && branchState.state === 'absent') {
       return { record, branch_cleanup: record.branch_cleanup, changed: false };
     }
     const cleanup = attemptLocalBranchCleanup(loaded, record, pushed);
@@ -511,7 +551,8 @@ export function createCommands(deps) {
         branch_cleanup_changed: terminal.changed || reconciled.changed,
       };
     }
-    const registeredAtStart = parseWorktrees(loaded.context.current_worktree)
+    const repositoryCwd = repositoryGitCwd(loaded);
+    const registeredAtStart = parseWorktrees(repositoryCwd)
       .find((worktree) => worktree.path === canonicalSelectorPath(record.path));
     if (!registeredAtStart && existsSync(record.path)) {
       return {
@@ -538,14 +579,14 @@ export function createCommands(deps) {
       }, { pushed, evidence: options.evidence ?? null });
     }
 
-    const live = parseWorktrees(loaded.context.current_worktree).find((worktree) => worktree.path === canonicalSelectorPath(record.path));
+    const live = parseWorktrees(repositoryCwd).find((worktree) => worktree.path === canonicalSelectorPath(record.path));
     if (live) {
       const submodules = reclaimSubmodules(live.path);
       if (submodules.reason) return { reclaimed: false, reason: submodules.reason, record };
-      const removed = gitTry(['worktree', 'remove', live.path], loaded.context.current_worktree);
+      const removed = gitTry(['worktree', 'remove', live.path], repositoryCwd);
       if (!removed.ok) {
         const detail = commandFailureReason(removed, 'git worktree remove refused');
-        const stillRegistered = parseWorktrees(loaded.context.current_worktree)
+        const stillRegistered = parseWorktrees(repositoryCwd)
           .some((worktree) => worktree.path === canonicalSelectorPath(record.path));
         const residue = !stillRegistered && existsSync(record.path)
           ? '; Git registration was removed but the physical directory remains'
@@ -569,7 +610,7 @@ export function createCommands(deps) {
         };
       }
     }
-    gitTry(['worktree', 'prune'], loaded.context.current_worktree);
+    gitTry(['worktree', 'prune'], repositoryCwd);
     const branchCleanup = attemptLocalBranchCleanup(loaded, record, pushed);
     record = appendReclaimEvent(loaded.context.common_dir, record, 'reclaimed', (next) => {
       const completedAt = new Date().toISOString();
@@ -659,6 +700,7 @@ export function createCommands(deps) {
     }
     if (result.branch_cleanup?.status === 'failed') {
       log(`目录已回收 ${result.record.worktree_id.slice(0, 8)}；本地分支 ${result.record.branch} 清理待重试: ${result.branch_cleanup.reason}`);
+      process.exitCode = 1;
       return;
     }
     const recovery = result.record.evidence_archive?.archive_ref

package/domains/worktree/worktree-review-watch.mjs

@@ -48,14 +48,103 @@ export function createCommands(deps) {
     reclaimRecord,
   } = deps;
 
+  /** @param {Record<string,any>} record */
+  function activeAutoReclaim(record) {
+    return record.auto_reclaim && !['disarmed', 'reclaimed'].includes(record.auto_reclaim.state)
+      ? record.auto_reclaim
+      : null;
+  }
+
+  /**
+   * review_watch 是“应不应该自动回收”的持久意图；auto_reclaim 是某一次实际 watcher 的租约。
+   * 两者分开后，启动前置条件失败、宿主杀进程和显式 --no-watch 不再都坍缩成字段缺失。
+   * @param {ReturnType<typeof loadRepositoryProfile>} loaded
+   * @param {Record<string,any>} record
+   * @param {{flags:Map<string,unknown>}} args
+   * @param {{head:string|null}} snapshot
+   */
+  function reviewWatchIntent(loaded, record, args, snapshot) {
+    const previous = record.review_watch?.policy === 'auto'
+      ? record.review_watch
+      : record.auto_reclaim ?? null;
+    const targetRef = aliasedFlag(args.flags, 'target', 'watch-target')
+      ?? previous?.target_ref
+      ?? record.base_ref
+      ?? loaded.profile.default_base
+      ?? null;
+    const changeRefValue = aliasedFlag(args.flags, 'change-ref', 'mr');
+    return {
+      policy: 'auto',
+      state: 'pending',
+      target_ref: targetRef,
+      head_sha: snapshot.head,
+      interval_ms: parseWatchInterval(flag(args.flags, 'interval-ms') ?? previous?.interval_ms),
+      change_ref: changeRefValue
+        ? oneLine(changeRefValue, 'change-ref', 1000)
+        : previous?.change_ref ?? null,
+      notify: parseNotifyMode(flag(args.flags, 'notify') ?? previous?.notify),
+      reason: null,
+      source: 'auto_touch',
+      updated_at: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * @param {ReturnType<typeof loadRepositoryProfile>} loaded
+   * @param {Record<string,any>} record
+   * @param {Record<string,any>} intent
+   * @param {'pending'|'disabled'} state
+   * @param {string} reason
+   * @param {string|null} [disarmToken]
+   */
+  function persistReviewWatchIntent(loaded, record, intent, state, reason, disarmToken = null) {
+    const now = new Date().toISOString();
+    return appendTraceEvent({
+      commonDir: loaded.context.common_dir,
+      worktreeId: record.worktree_id,
+      eventType: state === 'disabled' ? 'review_watch_disabled' : 'review_watch_pending',
+      actor: record.agent,
+      details: {
+        policy: state === 'disabled' ? 'disabled' : 'auto',
+        target_ref: intent.target_ref,
+        head_sha: intent.head_sha,
+        reason,
+      },
+      mutate(current) {
+        if (current.worktree_state === 'reclaimed' || current.worktree_state === 'archived') {
+          throw new WorktreeTraceError('WATCH_INTENT_SETTLED', `已结算 record 不能更新 watch intent: ${record.worktree_id}`);
+        }
+        const next = structuredClone(current);
+        if (disarmToken) {
+          if (next.auto_reclaim?.token !== disarmToken || ['disarmed', 'reclaimed'].includes(next.auto_reclaim?.state)) {
+            throw new WorktreeTraceError('WATCHER_CHANGED', `watch token 已被并发更新或解除: ${record.worktree_id}`);
+          }
+          next.auto_reclaim.state = 'disarmed';
+          next.auto_reclaim.disarmed_at = now;
+          next.auto_reclaim.disarm_reason = 'explicit_no_watch';
+        }
+        next.review_watch = {
+          ...intent,
+          policy: state === 'disabled' ? 'disabled' : 'auto',
+          state,
+          reason,
+          updated_at: now,
+        };
+        next.updated_at = now;
+        return next;
+      },
+    }).record;
+  }
+
   function autoArmReviewWatch(loaded, record, args, snapshot) {
+    const existing = activeAutoReclaim(record);
+    const intent = reviewWatchIntent(loaded, record, args, snapshot);
     if (args.flags.get('no-watch')) {
+      persistReviewWatchIntent(loaded, record, intent, 'disabled', 'explicit_no_watch', existing?.token ?? null);
+      if (existing?.token) removeWatcherHeartbeat(loaded.context.common_dir, record.worktree_id, existing.token);
       log('watch 未武装：--no-watch 显式退出；合入后需要人工回收。');
       return;
     }
-    const existing = record.auto_reclaim && !['disarmed', 'reclaimed'].includes(record.auto_reclaim.state)
-      ? record.auto_reclaim
-      : null;
     // 原子失效旧 watcher 后仍沿用它的 target/interval/change-ref 默认值，避免自动重冻结
     // 把人工显式选择的 target 静默改回该树登记的 base。
     const previous = record.auto_reclaim ?? null;
@@ -63,8 +152,11 @@ export function createCommands(deps) {
       log('watch 保持原冻结 SHA：目标分支已确认包含该 head，自动回收已进入提交阶段。');
       return;
     }
-    const skip = (reason) => log(`watch 未武装：${reason}；自动回收保持关闭，可补齐前提后重新 touch。`);
-    const targetRef = aliasedFlag(args.flags, 'target', 'watch-target') ?? previous?.target_ref ?? record.base_ref ?? loaded.profile.default_base;
+    const skip = (reason) => {
+      persistReviewWatchIntent(loaded, record, intent, 'pending', reason);
+      log(`watch 未武装：${reason}；自动回收保持关闭，已登记 pending，resume-all/维护服务会重试。`);
+    };
+    const targetRef = intent.target_ref;
     if (!targetRef || !targetRef.includes('/')) {
       skip(`无法确定远端主干 target（Profile default_base=${loaded.profile.default_base ?? 'null'}）`);
       return;
@@ -102,11 +194,9 @@ export function createCommands(deps) {
         targetRef,
         targetSha: refreshedTarget.target_sha,
         headSha: snapshot.head,
-        intervalMs: parseWatchInterval(flag(args.flags, 'interval-ms') ?? previous?.interval_ms),
-        changeRef: aliasedFlag(args.flags, 'change-ref', 'mr')
-          ? oneLine(aliasedFlag(args.flags, 'change-ref', 'mr'), 'change-ref', 1000)
-          : previous?.change_ref ?? null,
-        notifyMode: parseNotifyMode(flag(args.flags, 'notify') ?? previous?.notify),
+        intervalMs: intent.interval_ms,
+        changeRef: intent.change_ref,
+        notifyMode: intent.notify,
         explicitConfig: flag(args.flags, 'config') ? loaded.profile_path : null,
         previousHealth: health.reason,
         armedBy: 'auto_touch',
@@ -197,6 +287,18 @@ export function createCommands(deps) {
           disarm_reason: null,
           pid: null,
         };
+        next.review_watch = {
+          policy: 'auto',
+          state: 'armed',
+          target_ref: options.targetRef,
+          head_sha: options.headSha,
+          interval_ms: options.intervalMs,
+          change_ref: options.changeRef,
+          notify: options.notifyMode,
+          reason: null,
+          source: options.armedBy ?? existing?.armed_by ?? 'explicit',
+          updated_at: now,
+        };
         next.updated_at = now;
         return next;
       },
@@ -465,24 +567,71 @@ export function createCommands(deps) {
   }
 
   function cmdResumeAll(args) {
-    rejectUnknownFlags(args.flags, ['json', 'config']);
+    rejectUnknownFlags(args.flags, ['json', 'quiet', 'config']);
     if (args.positionals.length) die('resume-all 不接受 selector；它只扫描已 arm record。', 2);
     const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
     const result = { resumed: [], healthy: [], skipped: [] };
-    const records = loadRecords(loaded.context.common_dir).filter((record) =>
-      record.auto_reclaim &&
-      !['disarmed', 'reclaimed'].includes(record.auto_reclaim.state) &&
-      // archive 的前置条件本身已经要求 watcher 先 disarm，正常路径不会走到这里；这里保留
-      // 一道防线，避免归档记录被任何遗留/异常状态误当作待恢复 watcher。
-      record.worktree_state !== 'reclaimed' && record.worktree_state !== 'archived');
+    const records = loadRecords(loaded.context.common_dir).filter((record) => {
+      if (record.worktree_state === 'reclaimed' || record.worktree_state === 'archived') return false;
+      if (activeAutoReclaim(record)) return true;
+      if (!['ready_for_review', 'integrating'].includes(record.task_status)) return false;
+      // auto intent 要重试；没有任何 intent 的 legacy/live record 也必须进入 skipped，不能继续 0/0/0 隐身。
+      return record.review_watch?.policy === 'auto' || !record.review_watch;
+    });
     for (const record of records) {
+      const existing = activeAutoReclaim(record);
+      if (!existing) {
+        const intent = record.review_watch;
+        if (!intent) {
+          result.skipped.push({ worktree_id: record.worktree_id, task: record.task, reason: 'review watch intent missing; touch ready_for_review again' });
+          continue;
+        }
+        const snapshot = liveGitSnapshot(record);
+        let reason = null;
+        if (!snapshot.present) reason = 'worktree missing';
+        else if (snapshot.dirty !== false) reason = 'worktree dirty';
+        else if (!snapshot.head || snapshot.head !== intent.head_sha) reason = 'live head differs from pending intent';
+        else {
+          const upstream = gitTry(['rev-parse', '@{upstream}^{commit}'], record.path);
+          if (!upstream.ok || upstream.out !== snapshot.head) reason = 'current head not fully pushed to upstream';
+        }
+        if (!intent.target_ref || typeof intent.target_ref !== 'string') reason ??= 'target ref missing';
+        const intervalMs = Number(intent.interval_ms);
+        if (!Number.isInteger(intervalMs) || intervalMs < WATCH_MIN_INTERVAL_MS || intervalMs > WATCH_MAX_INTERVAL_MS) reason ??= 'interval invalid';
+        let refreshed = null;
+        if (!reason) {
+          refreshed = refreshTargetRef(intent.target_ref, loaded.context.current_worktree);
+          if (!refreshed.ok) reason = `target ref unavailable: ${intent.target_ref}`;
+        }
+        if (reason) {
+          result.skipped.push({ worktree_id: record.worktree_id, task: record.task, reason });
+          continue;
+        }
+        try {
+          const started = startWatcher(loaded, record, {
+            targetRef: intent.target_ref,
+            targetSha: refreshed.target_sha,
+            headSha: intent.head_sha,
+            intervalMs,
+            changeRef: intent.change_ref ?? null,
+            notifyMode: intent.notify ?? 'auto',
+            explicitConfig: flag(args.flags, 'config') ? loaded.profile_path : null,
+            previousHealth: intent.reason ?? 'pending intent',
+            armedBy: intent.source ?? 'auto_touch',
+          });
+          result.resumed.push({ worktree_id: record.worktree_id, task: record.task, pid: started.pid, previous_health: intent.reason ?? 'pending intent', dirty: false });
+        } catch (error) {
+          result.skipped.push({ worktree_id: record.worktree_id, task: record.task, reason: error instanceof Error ? error.message : String(error) });
+        }
+        continue;
+      }
       const heartbeat = readWatcherHeartbeat(loaded.context.common_dir, record.worktree_id);
       const health = watcherHealth(record, heartbeat);
       if (health.healthy) {
         result.healthy.push({ worktree_id: record.worktree_id, task: record.task, pid: heartbeat.state.pid });
         continue;
       }
-      const auto = record.auto_reclaim;
+      const auto = existing;
       const intervalMs = Number(auto.interval_ms);
       const snapshot = liveGitSnapshot(record);
       let reason = null;
@@ -512,6 +661,7 @@ export function createCommands(deps) {
         result.skipped.push({ worktree_id: record.worktree_id, task: record.task, reason: error instanceof Error ? error.message : String(error) });
       }
     }
+    if (args.flags.get('quiet')) return;
     if (args.flags.get('json')) {
       console.log(JSON.stringify(result, null, 2));
       return;
@@ -526,17 +676,45 @@ export function createCommands(deps) {
     rejectUnknownFlags(args.flags, ['id', 'config']);
     const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
     let record = selectRecord(loadRecords(loaded.context.common_dir), args.positionals[0] ?? null, flag(args.flags, 'id'));
-    const token = record.auto_reclaim?.token;
-    if (!token || ['disarmed', 'reclaimed'].includes(record.auto_reclaim.state)) {
-      log(`watcher 未 arm: ${record.worktree_id.slice(0, 8)}`);
+    if (record.worktree_state === 'reclaimed' || record.worktree_state === 'archived') {
+      log(`已结算，无需 unwatch: ${record.worktree_id.slice(0, 8)}`);
       return;
     }
-    if (record.auto_reclaim.state === 'merge_detected') {
+    const active = activeAutoReclaim(record);
+    const token = active?.token;
+    if (!token) {
+      if (record.review_watch?.policy === 'disabled') {
+        log(`watcher 未 arm: ${record.worktree_id.slice(0, 8)}`);
+        return;
+      }
+      const snapshot = liveGitSnapshot(record);
+      const intent = {
+        ...(record.review_watch ?? {}),
+        target_ref: record.review_watch?.target_ref ?? record.base_ref ?? null,
+        head_sha: record.review_watch?.head_sha ?? snapshot.head,
+        interval_ms: record.review_watch?.interval_ms ?? parseWatchInterval(null),
+        change_ref: record.review_watch?.change_ref ?? null,
+        notify: record.review_watch?.notify ?? 'auto',
+        source: record.review_watch?.source ?? 'explicit',
+      };
+      persistReviewWatchIntent(loaded, record, intent, 'disabled', 'explicit_unwatch');
+      log(`auto-reclaim 已明确关闭: ${record.worktree_id.slice(0, 8)}`);
+      return;
+    }
+    if (active.state === 'merge_detected') {
       die('目标分支已确认包含冻结的 MR head，自动回收已进入提交阶段，不能再 unwatch。');
     }
     record = appendReclaimEvent(loaded.context.common_dir, record, 'auto_reclaim_disarmed', (next) => {
       next.auto_reclaim.state = 'disarmed';
       next.auto_reclaim.disarmed_at = new Date().toISOString();
+      next.auto_reclaim.disarm_reason = 'explicit_unwatch';
+      next.review_watch = {
+        ...(next.review_watch ?? {}),
+        policy: 'disabled',
+        state: 'disabled',
+        reason: 'explicit_unwatch',
+        updated_at: new Date().toISOString(),
+      };
     });
     removeWatcherHeartbeat(loaded.context.common_dir, record.worktree_id, token);
     log(`auto-reclaim watcher 已解除: ${record.worktree_id.slice(0, 8)}`);

package/domains/worktree/worktree-watch-service.mjs

@@ -0,0 +1,224 @@
+// @ts-check
+
+const DEFAULT_INTERVAL_SECONDS = 60;
+const MIN_INTERVAL_SECONDS = 30;
+const MAX_INTERVAL_SECONDS = 60 * 60;
+
+/** @param {string} value */
+function xmlEscape(value) {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+/** @param {string} repositoryId */
+export function launchAgentLabel(repositoryId) {
+  const suffix = String(repositoryId).toLowerCase().replaceAll(/[^a-z0-9]/gu, '').slice(0, 32);
+  if (!suffix) throw new Error('repository id 不能生成 launchd label。');
+  return `io.github.cr1992.agentkit.worktree.${suffix}`;
+}
+
+/**
+ * 生成固定 argv 的 LaunchAgent；不经过 shell，也不把调用会话的环境变量或凭证写进 plist。
+ * @param {{label:string,nodePath:string,managerScript:string,workingDirectory:string,intervalSeconds:number,logPath:string,configPath?:string|null}} options
+ */
+export function renderLaunchAgentPlist(options) {
+  const args = [options.nodePath, options.managerScript, 'resume-all', '--quiet'];
+  if (options.configPath) args.push('--config', options.configPath);
+  const argumentXml = args.map((arg) => `      <string>${xmlEscape(arg)}</string>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xmlEscape(options.label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${argumentXml}
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${xmlEscape(options.workingDirectory)}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StartInterval</key>
+    <integer>${options.intervalSeconds}</integer>
+    <key>AbandonProcessGroup</key>
+    <true/>
+    <key>ProcessType</key>
+    <string>Background</string>
+    <key>StandardOutPath</key>
+    <string>/dev/null</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(options.logPath)}</string>
+  </dict>
+</plist>
+`;
+}
+
+/** @param {unknown} raw */
+export function parseServiceInterval(raw) {
+  const value = raw === null || raw === undefined ? DEFAULT_INTERVAL_SECONDS : Number(raw);
+  if (!Number.isInteger(value) || value < MIN_INTERVAL_SECONDS || value > MAX_INTERVAL_SECONDS) {
+    throw new Error(`--interval-seconds 必须是 ${MIN_INTERVAL_SECONDS}-${MAX_INTERVAL_SECONDS} 的整数。`);
+  }
+  return value;
+}
+
+/**
+ * @param {Record<string,any>} deps
+ */
+export function createCommands(deps) {
+  const {
+    processPlatform,
+    processExecPath,
+    processGetuid,
+    homedir,
+    randomUUID,
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    renameSync,
+    rmSync,
+    writeFileSync,
+    dirname,
+    join,
+    managerScript,
+    runFileCapture,
+    loadRepositoryProfile,
+    readRepositoryIdentity,
+    ensureRepositoryIdentity,
+    traceLayout,
+    flag,
+    rejectUnknownFlags,
+    die,
+    log,
+  } = deps;
+
+  /** @param {ReturnType<typeof loadRepositoryProfile>} loaded @param {boolean} createIdentity */
+  function descriptor(loaded, createIdentity) {
+    const identity = createIdentity
+      ? ensureRepositoryIdentity(loaded.context)
+      : readRepositoryIdentity(loaded.context);
+    if (!identity) return null;
+    const label = launchAgentLabel(identity.repository_id);
+    const plistPath = join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+    const logPath = join(traceLayout(loaded.context.common_dir).root, 'watch-service.log');
+    const uid = processGetuid();
+    return {
+      label,
+      plist_path: plistPath,
+      log_path: logPath,
+      domain: `gui/${uid}`,
+      service_target: `gui/${uid}/${label}`,
+      working_directory: loaded.context.primary_worktree,
+      config_path: loaded.profile_source === 'explicit' ? loaded.profile_path : null,
+    };
+  }
+
+  /** @param {ReturnType<typeof loadRepositoryProfile>} loaded */
+  function watchServiceStatus(loaded) {
+    if (processPlatform !== 'darwin') {
+      return { supported: false, installed: false, loaded: false, platform: processPlatform, reason: 'macOS LaunchAgent adapter only' };
+    }
+    const value = descriptor(loaded, false);
+    if (!value) {
+      return { supported: true, installed: false, loaded: false, platform: processPlatform, reason: 'repository identity missing' };
+    }
+    const probe = runFileCapture('/bin/launchctl', ['print', value.service_target], { cwd: loaded.context.primary_worktree });
+    return {
+      supported: true,
+      installed: existsSync(value.plist_path),
+      loaded: probe.ok,
+      platform: processPlatform,
+      label: value.label,
+      plist_path: value.plist_path,
+      log_path: value.log_path,
+      node_path: processExecPath,
+      manager_script: managerScript,
+      program_available: existsSync(processExecPath) && existsSync(managerScript),
+      reason: probe.ok ? null : (probe.out || 'launchd job not loaded'),
+    };
+  }
+
+  /** @param {ReturnType<typeof loadRepositoryProfile>} loaded @param {number} intervalSeconds */
+  function install(loaded, intervalSeconds) {
+    if (processPlatform !== 'darwin') die(`watch-service install 当前只支持 macOS；${processPlatform} 可继续手工运行 resume-all。`, 2);
+    const value = descriptor(loaded, true);
+    const plist = renderLaunchAgentPlist({
+      label: value.label,
+      nodePath: processExecPath,
+      managerScript,
+      workingDirectory: value.working_directory,
+      intervalSeconds,
+      logPath: value.log_path,
+      configPath: value.config_path,
+    });
+    mkdirSync(dirname(value.plist_path), { recursive: true });
+    mkdirSync(dirname(value.log_path), { recursive: true });
+    const previous = existsSync(value.plist_path) ? readFileSync(value.plist_path, 'utf8') : null;
+    const temporary = `${value.plist_path}.${processGetuid()}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, plist, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+
+    const wasLoaded = runFileCapture('/bin/launchctl', ['print', value.service_target], { cwd: value.working_directory }).ok;
+    if (wasLoaded) {
+      const stopped = runFileCapture('/bin/launchctl', ['bootout', value.service_target], { cwd: value.working_directory });
+      if (!stopped.ok) {
+        rmSync(temporary, { force: true });
+        die(`无法重载现有 LaunchAgent：${stopped.out || 'launchctl bootout failed'}`);
+      }
+    }
+    renameSync(temporary, value.plist_path);
+    const started = runFileCapture('/bin/launchctl', ['bootstrap', value.domain, value.plist_path], { cwd: value.working_directory });
+    if (!started.ok) {
+      if (previous === null) rmSync(value.plist_path, { force: true });
+      else writeFileSync(value.plist_path, previous, { encoding: 'utf8', mode: 0o600 });
+      if (wasLoaded && previous !== null) runFileCapture('/bin/launchctl', ['bootstrap', value.domain, value.plist_path], { cwd: value.working_directory });
+      die(`LaunchAgent 安装失败：${started.out || 'launchctl bootstrap failed'}`);
+    }
+    const kicked = runFileCapture('/bin/launchctl', ['kickstart', '-k', value.service_target], { cwd: value.working_directory });
+    if (!kicked.ok) die(`LaunchAgent 已加载但首次执行失败：${kicked.out || 'launchctl kickstart failed'}`);
+    return { ...watchServiceStatus(loaded), interval_seconds: intervalSeconds };
+  }
+
+  /** @param {ReturnType<typeof loadRepositoryProfile>} loaded */
+  function uninstall(loaded) {
+    if (processPlatform !== 'darwin') die(`watch-service uninstall 当前只支持 macOS；当前平台 ${processPlatform}。`, 2);
+    const value = descriptor(loaded, false);
+    if (!value) return { supported: true, installed: false, loaded: false, removed: false };
+    const loadedBefore = runFileCapture('/bin/launchctl', ['print', value.service_target], { cwd: value.working_directory }).ok;
+    if (loadedBefore) {
+      const stopped = runFileCapture('/bin/launchctl', ['bootout', value.service_target], { cwd: value.working_directory });
+      if (!stopped.ok) die(`LaunchAgent 停止失败：${stopped.out || 'launchctl bootout failed'}`);
+    }
+    const installedBefore = existsSync(value.plist_path);
+    rmSync(value.plist_path, { force: true });
+    return { supported: true, installed: false, loaded: false, removed: installedBefore || loadedBefore, label: value.label, plist_path: value.plist_path };
+  }
+
+  function cmdWatchService(args) {
+    rejectUnknownFlags(args.flags, ['json', 'config', 'interval-seconds']);
+    const action = args.positionals[0] ?? 'status';
+    if (args.positionals.length > 1 || !['install', 'status', 'uninstall'].includes(action)) {
+      die('watch-service 用法：watch-service install|status|uninstall [--json] [--interval-seconds <seconds>]', 2);
+    }
+    const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
+    let result;
+    if (action === 'install') {
+      let intervalSeconds;
+      try { intervalSeconds = parseServiceInterval(flag(args.flags, 'interval-seconds')); }
+      catch (error) { die(error instanceof Error ? error.message : String(error), 2); }
+      result = install(loaded, intervalSeconds);
+    } else if (action === 'uninstall') {
+      result = uninstall(loaded);
+    } else {
+      result = watchServiceStatus(loaded);
+    }
+    if (args.flags.get('json')) console.log(JSON.stringify(result, null, 2));
+    else if (action === 'install') log(`跨会话 watch-service 已安装 label=${result.label} interval=${result.interval_seconds}s`);
+    else if (action === 'uninstall') log(`跨会话 watch-service ${result.removed ? '已卸载' : '原本未安装'}`);
+    else log(`watch-service supported=${result.supported} installed=${result.installed} loaded=${result.loaded}${result.reason ? ` reason=${result.reason}` : ''}`);
+  }
+
+  return { cmdWatchService, watchServiceStatus };
+}

package/manage-worktrees/SKILL.md

@@ -67,6 +67,10 @@ manager 的 trace/common-dir 状态只应由受信 operator/controller 与 runti
 | 批量集成 | `plan-batch` → `batch-integrate` → `batch-step` → `batch-result` | 同仓同 target：≥3 默认聚合，2 个仅在碰撞时；只合成冻结 SHA，不代跑门禁；合同/顺序/target 变化即重规划；读[批量集成](../docs/worktree/batch-integration.md) |
 | 回收 | `reclaim` / `archive` | 必须有远端/其他 ref 可达证明或明确 archive evidence；dirty、stash、submodule、权限或 branch-tip 异常一律 `KEEP`；替代树默认先归档，`--discard` 需人工明确授权；读[回收与看护](../docs/worktree/reclaim-and-watch.md) |
 
+`resume-all` 只提供当次恢复。需要跨 Agent 会话、注销或重启后仍自动恢复 watcher 时，先检查
+`agentkit worktree watch-service status`；macOS 可由用户一次性显式执行 `watch-service install`。
+未安装常驻维护器时不得把进程级 watcher 描述成跨会话保证。
+
 不得按目录年龄、名称或“看起来干净”删除。禁止 `rm -rf`、`git worktree remove --force`、`branch -D`
 和 feature owner 手工 rebase。watcher 的 `merge-tree` 结果只是目标前进后的只读成本预判，不保证逐
 commit rebase 成功；`batch-result` 只冻结 controller 已完成的验收结论，不替代验证。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr1992/agentkit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Agent engineering toolkit: orchestration, git worktree isolation, independent verification and bounded verify loops.",
   "license": "MIT",
   "repository": {

package/shell-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "package_name": "@cr1992/agentkit",
-  "package_version": "1.0.0",
+  "package_version": "1.1.0",
   "cli": {
     "command": "agentkit",
     "entry": "bin/agentkit.mjs"