@cr1992/agentkit 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/)。
 
+## Unreleased
+
+## 1.1.1 - 2026-09-08
+
+- 修复 `doctor` 对已回收 record 仍生成需要活树才能收敛的 metadata finding。`stack_parent`、
+  `history_operation` 和 `review_refresh` 三个分支缺少 `worktree_state` 过滤，对已删除目录报
+  `STACK_PARENT_ADVANCED` 等提示，其补救动作（managed rebase/retarget、`rebase --continue`、
+  `refresh-review`）在回收后都无法执行，噪声永远清不掉；其中 error 级的还会按「任何 error 都暂停
+  `spawn/adopt`」把后续派工钉死。生命周期与 watcher 两个收集器早已是这个口径，本次补齐 metadata。
+- `manage-worktrees` 补齐 `--no-watch` 的使用判据：只用于确定不会合入，或武装失败原因为永久性
+  （否则 pending 会积一条清不掉的 `AUTO_RECLAIM_NOT_ARMED`）。明确禁止因 watcher 活不过会话或
+  为压后台进程数而关闭——前者是 `watch-service` 的职责，后者不成立（`disabled` 持久且不重试）。
+- `watch-service status` 进入强制流程表的「恢复/盘点」行，不再只以表外散文形式存在。
+- 四个 SKILL.md 对 `docs/<域>/` 的引用从相对链接改为 `agentkit docs <域> <主题>` 命令。宿主把 Skill
+  基目录报成安装路径（常为软链），Read 工具按词法折叠 `..`，原 `../docs/...` 链接在安装态全部不可达，
+  agent 只剩摘要表。`validate-skills` 新增安装态检查：SKILL.md 相对链接越出 Skill 目录即报错，
+  `agentkit docs` 引用的主题必须真实存在。
+
+## 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,29 @@ 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`。
+
+`--no-watch` 只用于两种情况：change request 确定不会合入（与 `unwatch` 同一判据）；或该树的合入在结构上
+无法被 watcher 观测且原因是永久的（例如仓库没有可刷新的远端 target），此时留在 pending 只会积一条永远清不
+掉的 `AUTO_RECLAIM_NOT_ARMED`（error），按强制流程会挡住后续 `spawn/adopt`。除此之外一律不要关：watcher
+活不过当前会话是 `watch-service` 要解决的问题，不是关 watcher 的理由；也不能拿它临时压后台进程数——
+`disabled` 是持久策略，`resume-all` 不重试，没有“解除节流”这一步。dirty、未 push、网络等**可恢复**原因
+导致的武装失败，留在 pending 等重试，不要转成 `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 +110,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,10 +35,18 @@ export function createCommands(deps) {
     buildListing,
     learningRoot,
     isSettledWorktreeState,
+    watchServiceStatus,
   } = deps;
 
   function collectDoctorRecordMetadataFindings(loaded, listing, recordsById, record, findings) {
-    if (record.storage_class === 'ephemeral' && record.worktree_state !== 'reclaimed') findings.push({ code: 'EPHEMERAL_WORKTREE', severity: 'warning', worktree_id: record.worktree_id, path: record.path });
+    // 本收集器的每条 finding 都要求一棵活树才能收敛：commit+push、rebase --continue、
+    // refresh-review --continue/--abort、managed rebase 或 retarget、补记 base_reason。
+    // record 一旦 reclaimed，目录已经删除，这些提示既没有补救动作也永远不会消失；其中 error 级的
+    // （MANAGED_HISTORY_OPERATION_PENDING / REVIEW_REFRESH_PENDING / STACK_PARENT_*）还会按
+    // SKILL 的「任何 error 都暂停 spawn/adopt」把后续派工钉死。生命周期与 watcher 两个收集器
+    // 已经是这个口径，这里补齐；archived 更早一步在调用方 continue，所以只需排除 reclaimed。
+    if (record.worktree_state === 'reclaimed') return;
+    if (record.storage_class === 'ephemeral') findings.push({ code: 'EPHEMERAL_WORKTREE', severity: 'warning', worktree_id: record.worktree_id, path: record.path });
     if (record.history_operation) {
       findings.push({
         code: 'MANAGED_HISTORY_OPERATION_PENDING',
@@ -102,7 +110,6 @@ export function createCommands(deps) {
       }
     }
     if (
-      record.worktree_state !== 'reclaimed' &&
       loaded.profile.default_base &&
       record.base_ref &&
       record.base_ref !== loaded.profile.default_base
@@ -243,10 +250,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 +300,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 +504,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

@@ -23,7 +23,7 @@ metadata:
 下文多行示例采用 POSIX 续行语法；PowerShell/cmd 保留相同 argv 即可。不要把 `python3`、`bash`、
 `~` 展开或 `/tmp` 视为跨平台常量。
 
-不要假设目标仓库有同名脚本。仓库可以通过根目录 `.worktree-trace.json` 提供 Profile，但 portable core 不执行 Profile 中的任意 shell command。配置 schema 和项目适配边界见 [Profile 配置](../docs/worktree/profile.md)。
+不要假设目标仓库有同名脚本。仓库可以通过根目录 `.worktree-trace.json` 提供 Profile，但 portable core 不执行 Profile 中的任意 shell command。配置 schema 和项目适配边界见 Profile 配置（`agentkit docs worktree profile`）。
 
 所有命令都必须从**目标 Git 仓库的任意 worktree 内**执行：manager 以当前工作目录解析 repository
 identity、primary worktree 和 Profile。
@@ -58,14 +58,18 @@ manager 的 trace/common-dir 状态只应由受信 operator/controller 与 runti
 
 | 阶段 | 最小命令面 | 硬门禁与按需文档 |
 |---|---|---|
-| 恢复/盘点 | `resume-all` → `list` → `doctor` | `list/doctor` 只读；`UNTRACKED` 不等于无人使用；`EPHEMERAL` 优先 commit+push；任何 error 都暂停 `spawn/adopt` |
+| 恢复/盘点 | `watch-service status` → `resume-all` → `list` → `doctor` | 常驻服务未安装时只报告并建议 `watch-service install`，不得用 `--no-watch` 顶替；`list/doctor` 只读；`UNTRACKED` 不等于无人使用；`EPHEMERAL` 优先 commit+push；任何 error 都暂停 `spawn/adopt` |
 | 碰撞扫描 | `scan --target <paths>` | `COLLIDE`、范围不确定或重做昂贵时隔离；`CLEAR` 仅在 owner 明确且改动小时共享；低置信后缀匹配先人工核对路径基准 |
-| 交付身份 | 选择复用/并存/替代 | branch、MR 或目录名不同不能单独证明独立交付；同一 agent 有存量树或需要替代时读[交付身份](../docs/worktree/delivery-identity.md) |
-| 创建/接管 | `spawn <semantic-slug>` / `adopt <path>` | 使用真实 agent-id，不猜身份；task 至少两个 lowercase 语义分词；base、root、堆叠、rebase/retarget 读[创建与堆叠](../docs/worktree/spawn-and-stack.md) |
-| 更新/交接 | `touch` / `handoff` / `refresh-review` | `ready_for_review` 默认武装冻结 HEAD；handoff 只接受 clean、已 push 边界，禁止 stash 搬运；读[评审生命周期](../docs/worktree/review-lifecycle.md) |
+| 交付身份 | 选择复用/并存/替代 | branch、MR 或目录名不同不能单独证明独立交付；同一 agent 有存量树或需要替代时读交付身份（`agentkit docs worktree delivery-identity`） |
+| 创建/接管 | `spawn <semantic-slug>` / `adopt <path>` | 使用真实 agent-id，不猜身份；task 至少两个 lowercase 语义分词；base、root、堆叠、rebase/retarget 读创建与堆叠（`agentkit docs worktree spawn-and-stack`） |
+| 更新/交接 | `touch` / `handoff` / `refresh-review` | `ready_for_review` 默认武装冻结 HEAD；handoff 只接受 clean、已 push 边界，禁止 stash 搬运；读评审生命周期（`agentkit docs worktree review-lifecycle`） |
 | 审计/提交 | `audit` / `submit` | portable core 不决定 MR/PR 或直推策略；先服从目标仓规则，再原子登记 change request 与 watcher target |
-| 批量集成 | `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) |
+| 批量集成 | `plan-batch` → `batch-integrate` → `batch-step` → `batch-result` | 同仓同 target：≥3 默认聚合，2 个仅在碰撞时；只合成冻结 SHA，不代跑门禁；合同/顺序/target 变化即重规划；读批量集成（`agentkit docs worktree batch-integration`） |
+| 回收 | `reclaim` / `archive` | 必须有远端/其他 ref 可达证明或明确 archive evidence；dirty、stash、submodule、权限或 branch-tip 异常一律 `KEEP`；替代树默认先归档，`--discard` 需人工明确授权；读回收与看护（`agentkit docs worktree reclaim-and-watch`） |
+
+`resume-all` 只提供当次恢复。跨 Agent 会话、注销或重启后仍要自动恢复 watcher，靠的是常驻维护器：
+macOS 由用户一次性显式执行 `watch-service install`。未安装时不得把进程级 watcher 描述成跨会话保证，
+也不得因此改用 `--no-watch`（判据见评审生命周期）——那只会把待回收的树变成无人看护。
 
 不得按目录年龄、名称或“看起来干净”删除。禁止 `rm -rf`、`git worktree remove --force`、`branch -D`
 和 feature owner 手工 rebase。watcher 的 `merge-tree` 结果只是目标前进后的只读成本预判，不保证逐

package/orchestrate-subagents/SKILL.md

@@ -38,7 +38,7 @@ controller 始终拥有闭环对象、完成标准、任务图、依赖/barrier
 
 派生后维护“活跃 Agent”“本批已完成”，存在并行时再维护“工作进展”；在派发、批次收口、用户询问
 和最终答复时更新，无活跃 worker 明示为 0，不虚构百分比。字段与状态变换见
-[编排运行时](../docs/orchestrate/orchestration-runtime.md)「派发台账的三张表」。台账也是回收清单：收口前
+编排运行时（`agentkit docs orchestrate orchestration-runtime`）「派发台账的三张表」。台账也是回收清单：收口前
 确认没有孤儿 worker/worktree/运行时资源。任务图与台账只写仓库外会话状态；完整档用 mechanical
 ledger，轻量档用单一 JSON 快照，闭环后清理。
 
@@ -48,7 +48,7 @@ ledger，轻量档用单一 JSON 快照，闭环后清理。
 只有 `allowed` 可用。输入已随合同完整提供、节点不依赖额外宿主能力时 requirements 可为空，
 此时记 `not_required` 及依据即可。同机、本地或过去恒过都不构成豁免。探针只在比 controller 自做或
 缩小节点更便宜时派发，并计入 worker 与 Token 预算。能力键前缀、binding 与复用规则、反应矩阵见
-[编排运行时](../docs/orchestrate/orchestration-runtime.md)「Worker 有效能力预检」。
+编排运行时（`agentkit docs orchestrate orchestration-runtime`）「Worker 有效能力预检」。
 
 ### 显式轻量档
 
@@ -59,7 +59,7 @@ ledger，轻量档用单一 JSON 快照，闭环后清理。
 轻量档仍冻结每个节点的目标、范围、事实/假设、输出合同、验收、证据和停止条件，并在仓库外维护
 单一 JSON 快照；它只记录事实，不伪造 journal。资格失效时停止新派发，把现状和产物收养进完整 ledger。
 Reflection 使用 `agentkit orchestrate reflection record/propose`，通用 Skill 缺口不得写入宿主能力缓存。
-快照 schema、收养步骤和 Reflection 约束见 [编排运行时](../docs/orchestrate/orchestration-runtime.md)。
+快照 schema、收养步骤和 Reflection 约束见 编排运行时（`agentkit docs orchestrate orchestration-runtime`）。
 
 ### 完整档机械台账工具
 
@@ -68,7 +68,7 @@ review-view / diff` 固定公共 Task Contract，再以仓库外 state root 初
 脚本不直接派发 Agent，controller 把宿主回执写入 `dispatch-record`。节点必须选择
 `worker_self_check`、`controller_recheck`、`independent_evidence`，只读 critic/scout 用
 `not_applicable`；依赖/barrier 未通过不派下游。命令、schema、`--expected-revision`、state root 信任
-边界和批级熔断见 [编排运行时](../docs/orchestrate/orchestration-runtime.md)。
+边界和批级熔断见 编排运行时（`agentkit docs orchestrate orchestration-runtime`）。
 Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`，不能改变当前运行。
 
 ## 1. 先过闸门
@@ -81,7 +81,7 @@ Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`
 
 规模来自真正独立且单个上下文装不下的工作块，不来自话题数；删掉不影响答案的节点。常规盘点/审计
 一轮总 Agent 数 `≤10`。扫描与核验配比、
-合并判据与各档规模见 [任务类型剧本](../docs/orchestrate/task-playbooks.md)。
+合并判据与各档规模见 任务类型剧本（`agentkit docs orchestrate task-playbooks`）。
 
 ## 3. 派发前决定环境
 
@@ -98,7 +98,7 @@ Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`
 
 仓库 dirty、任务大或包含新文件本身都不足以要求隔离；先确认第二写入者、归属冲突或路径相交。
 裁决隔离后使用 `manage-worktrees`，它不改变任务图、权限或验收。不可用时必须先读
-[无 manage-worktrees 时的隔离下限](../docs/orchestrate/isolation-fallback.md)。
+无 manage-worktrees 时的隔离下限（`agentkit docs orchestrate isolation-fallback`）。
 
 共享树中 worker 不得切换分支，只按路径 stage / commit；禁止 `git add -A`、`git commit -am`、裸 `stash`、`reset --hard`、`checkout -- .` 和并发 merge，controller 是唯一 integrator。
 
@@ -107,7 +107,7 @@ Reflection 只记证据化观察，Improvement Proposal 永远保持 `proposed`
 2-3 个独立任务用宿主轻量并行；循环、条件、逐项管线或预算驱动才使用结构化编排。多 stage 默认逐条
 pipeline，只有跨条去重、聚合、比较或早退才设 barrier。截断、采样或不重试必须披露覆盖缺口。
 barrier、critic 面板与 loop-until-dry 的具体用法见
-[编排运行时](../docs/orchestrate/orchestration-runtime.md)「编排原语选择」。具体 API 服从宿主编排工具说明。
+编排运行时（`agentkit docs orchestrate orchestration-runtime`）「编排原语选择」。具体 API 服从宿主编排工具说明。
 
 ## 5. 派发可验收的任务契约
 
@@ -118,17 +118,17 @@ stop_conditions`；写任务再冻结权限、精确仓库/workdir/branch 和 wr
 controller 圆场。
 
 派发写 worker、完整档、独立 Evidence 或失败后重派前，必须读取
-[节点派发合同](../docs/orchestrate/dispatch-contract.md) 并使用完整 envelope。轻量只读节点可只使用上述最小合同。
+节点派发合同（`agentkit docs orchestrate dispatch-contract`） 并使用完整 envelope。轻量只读节点可只使用上述最小合同。
 
 ## 6. 控制运行态与升级
 
 用户可见台账只用 `运行中 / 阻塞 / 待验收`；`partial` 由 controller 决定继续、转阻塞或停止后判
 未通过。只有 controller 能给出 `通过 / 未通过 / 取消`。台账术语不进用户汇报，对外说法见
-[面向用户的汇报词表](../docs/orchestrate/user-facing-reporting.md)。
+面向用户的汇报词表（`agentkit docs orchestrate user-facing-reporting`）。
 
 只在结论交付、需要输入、scope/写入冲突、预算将尽、新依赖、失败或置信不足时介入；“等待中”不是
 状态包。能力故障、业务失败、中断与 contract gap 分开处理，不按失败次数机械升档。失败、重派、中断
-或 controller 接手时读取[失败路由与恢复](../docs/orchestrate/failure-routing-and-recovery.md)。合同失真、
+或 controller 接手时读取失败路由与恢复（`agentkit docs orchestrate failure-routing-and-recovery`）。合同失真、
 新授权、不可逆动作、资源/结论冲突或重试耗尽必须升级，不得自行扩 scope。
 
 ## 7. 验证、收敛与停止
@@ -139,7 +139,7 @@ controller 圆场。
 复核记录；`independent_evidence` 绑定唯一 Artifact 与标准 Evidence；只读 critic/scout 用
 `not_applicable`，附一份 report 即收口。失败、不可判定、安全阻塞、
 human gate 或错绑 Evidence 均不能通过。节点专属验收合同只能用 `agentkit contract project` 从公共
-合同切出 acceptance 子集；完整门禁见 [编排运行时](../docs/orchestrate/orchestration-runtime.md)「合同投影」。
+合同切出 acceptance 子集；完整门禁见 编排运行时（`agentkit docs orchestrate orchestration-runtime`）「合同投影」。
 
 快速演进分支的迭代期只读 review 最多算 `controller_recheck`；到 RC/合入候选才冻结唯一 Artifact，
 运行 `verify-agent-output` 生成 `independent_evidence`。
@@ -153,7 +153,7 @@ human gate 或错绑 Evidence 均不能通过。节点专属验收合同只能
 独立 reviewer 是高成本资源，不与 worker 1:1 配对。对同一 Artifact 默认只允许一次 primary review；
 第二次必须由 `undecidable`、证据冲突或协议歧义触发，使用不同 lens 且可能改变处置。smoke 未通过、
 同 lens 重复、输入超出预算或已有 `blocked_safety` 时不派。考虑任何 critic/reviewer 时必须读取
-[Reviewer 数量与 Token 预算](../docs/orchestrate/review-budget.md)，冻结 `extensions.review_policy`，并在派发前运行
+Reviewer 数量与 Token 预算（`agentkit docs orchestrate review-budget`），冻结 `extensions.review_policy`，并在派发前运行
 `agentkit orchestrate review-budget evaluate`。提高 reviewer 数量或输入上限属于 re-contract。
 
 最终答复前用 `闭环项 / 标准 / 证据 / 结果` 审计：闭环对象与外部状态已重查；必要节点已验收且活跃
@@ -163,11 +163,11 @@ human gate 或错绑 Evidence 均不能通过。节点专属验收合同只能
 ## 8. 模型路由与宿主自适配
 
 controller 持续掌握目标、任务图、re-plan、失败分类和最终验收；worker 不自选模型或下一次配置。
-派发、首次建 tier、失败后调档或切模型时读[模型路由](../docs/orchestrate/model-routing-config.md)，按任务类型
-选档再读[任务剧本](../docs/orchestrate/task-playbooks.md)：使用本地配置中最低可靠 tier，model/effort 只取
+派发、首次建 tier、失败后调档或切模型时读模型路由（`agentkit docs orchestrate model-routing-config`），按任务类型
+选档再读任务剧本（`agentkit docs orchestrate task-playbooks`）：使用本地配置中最低可靠 tier，model/effort 只取
 用户配置与实时 schema，每次保存精确配置、attempt lineage、理由和预算；扩大授权或显著增费先确认。
 
 `agents/openai.yaml` 和缓存都不是能力证明。runtime/path/tool 要求先做有效能力预检；能力快照的创建、
-刷新和复用读[宿主能力缓存](../docs/orchestrate/host-capability-cache.md)。实时 schema 优先，unknown 不能被
+刷新和复用读宿主能力缓存（`agentkit docs orchestrate host-capability-cache`）。实时 schema 优先，unknown 不能被
 缓存补成 allowed，缓存不能扩大授权。`protocol_version`、`runtime_version`、`content_digest` 分别表示
 协议兼容性、实现版本和精确安装内容，不得互相替代。

package/package.json

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

package/run-agent-verify-loop/SKILL.md

@@ -51,8 +51,8 @@ verification run，消费其标准 Evidence Package。Loop 不执行或复制完
 - runtime 只生成 `embedded_verification_record`，不能导出、转换或冒充 Evidence Package；
 - 无独立 reviewer 时停止，不用实现者自审产生 pass。
 
-进入 embedded L1 前读取 [内嵌 review 适配器](../docs/loop/embedded-review-adapter.md)。
-verifier 行为语义以 [验收协议](../docs/verify/verification-protocol.md) 为唯一真源；独立安装本 Skill
+进入 embedded L1 前读取 内嵌 review 适配器（`agentkit docs loop embedded-review-adapter`）。
+verifier 行为语义以 验收协议（`agentkit docs verify verification-protocol`） 为唯一真源；独立安装本 Skill
 时，adapter 只携带绑定和最低输入要求，不重定义 verdict。
 
 ## Runtime 流程
@@ -79,8 +79,8 @@ run-embedded-l0 → 新上下文 reviewer → record-embedded-review
 ```
 
 所有状态写命令可带 `--expected-revision <n>`；revision 不匹配时拒绝写入。详细状态迁移见
-[Loop 状态机](../docs/loop/loop-state-machine.md)，恢复和熔断见
-[恢复与熔断](../docs/loop/recovery-and-fuses.md)。只有发生复制/移动、journal 恢复、
+Loop 状态机（`agentkit docs loop loop-state-machine`），恢复和熔断见
+恢复与熔断（`agentkit docs loop recovery-and-fuses`）。只有发生复制/移动、journal 恢复、
 reflection 或提案时才使用 `adopt-root / record-reflection / convergence-report / propose-improvement --help`。
 
 ## 决策规则

package/shell-manifest.json

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

package/verify-agent-output/SKILL.md

@@ -31,8 +31,8 @@ controller 必须先提供：
 4. clean workdir，`HEAD == artifact_sha`；
 5. 新上下文 reviewer，或由用户中继的第二会话。只有当前实现者上下文时停止，不得伪造独立验收。
 
-详细 envelope 与字段规则见 [Evidence schema](../docs/verify/evidence-schema.md)。进入 L1 前必须完整读取
-[验收协议](../docs/verify/verification-protocol.md)。
+详细 envelope 与字段规则见 Evidence schema（`agentkit docs verify evidence-schema`）。进入 L1 前必须完整读取
+验收协议（`agentkit docs verify verification-protocol`）。
 
 ## 标准流程
 
@@ -56,7 +56,7 @@ agentkit verify validate --run <run-dir>
 ```
 
 所有子命令支持 `--help`；写命令支持 `--expected-revision`。尚未准备输入、happy path 失败或需要完整
-诊断时，先读 [输入准备与诊断命令](../docs/verify/input-preparation.md)。readiness/preflight 失败属于环境
+诊断时，先读 输入准备与诊断命令（`agentkit docs verify input-preparation`）。readiness/preflight 失败属于环境
 前提，不得记录为 Artifact verdict。
 
 ## 状态与裁决