@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/templates/.agents/skills/run-manual-validation/SKILL.zh-CN.md

@@ -8,12 +8,17 @@ description: >
 
 # 运行人工校验
 
+## 任务上下文解析
+
+入口可省略 task ref；显式 task scope 仅接受 `--task <ref>` 或 `-t <ref>`，不再解释位置 task ref。先解析 `--scope`、`--timeout`、`--format`，在 `--` 后原样保留用户命令，再调用 `agent-infra-internal task-context resolve {task-scope}`。解析失败时透传非零退出码，不自行扫描任务。内部 `task-validate` 协议仍使用位置 task ref。
+
 ## 行为边界
 
 - 本技能负责选择校验模式、调用唯一机械入口并记录证据；不把 PR 人工校验标为完成。
 - `complete-manual-validation` 仍是维护者确认覆盖充分后的最终登记入口。
 - 禁止直接操作临时 worktree、lease 或 container；只调用 `agent-infra-internal task-validate`。
 - 产物不得记录 token、环境变量、完整 argv、绝对用户路径或原始 transcript。
+- 生成会同步到 Issue 的验证 artifact Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；Issue 同步保持透明，不解析或改写正文。
 
 ## 第 0 步：状态核对（执行前硬约束）
 

package/templates/.agents/skills/run-task/SKILL.en.md

@@ -7,6 +7,10 @@ description: >
 
 # Run Task Lifecycle
 
+## Task Context Resolution
+
+The entry point may omit the task ref; explicit task scope accepts only `--task <ref>` or `-t <ref>`, and positional task refs are not interpreted. Preserve the four policy options and their values, then call `agent-infra-internal task-context resolve {task-scope}`. Pass through resolution failures without scanning tasks locally. The internal orchestration protocol continues to use a positional task ref.
+
 The orchestrator delegates only and never executes a stage skill itself. First read `.agents/rules/no-mid-flow-questions.md`, `.agents/rules/lifecycle-orchestration.md`, and `reference/host-validation.md`.
 
 1. Resolve the canonical task ID, current Agent Client, and optional atomic policy flags, then run `task-snapshot`. If one explicit role field is present, all four are required.
@@ -14,7 +18,7 @@ The orchestrator delegates only and never executes a stage skill itself. First r
 3. Run `task-orchestration {task-id} begin-or-resume --client {client}` with the complete explicit policy. With no explicit policy, core reads that client's configured policy; existing runs use persisted policy. Disk state outside the complete current structure fails closed without rewriting; finish or clear active runs before upgrading. Stop on paused/completed results.
 4. Run `route`. On `completed`, run `agent-infra-internal task-verify {task-id} run-task.completed --format text` and stop. Only a `running` result with non-null `next` supplies action, role, round, artifact, requested model, and requested effort.
 5. Codex runs `codex-lifecycle capability-arm --task-id {task-id}` once. The current loop's real PostToolUse must attest that ordinary tool response. Pass its marker token, the exact routed model, and the exact routed reasoning effort to `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort} --capability-token {token}`. Core first validates the exact routed model/effort, capability provenance, and controller binding, then captures a read-only snapshot, builds an in-memory prepared receipt, atomically consumes the token, and saves the prepared state with the capability session, turn, and tool-use origin. Activation then verifies that spawn belongs to the same session and turn and uses a distinct tool-use. Other clients use the same prepare without a token. Failure creates no baseline, receipt, or child.
-6. After prepare, run `task-orchestration <task-ref> dispatch` immediately before calling the fresh native child, then use route's exact model/effort and only the short task ref, skill, `--orchestrated`, and stage identity. The trusted hook-spawn first-observation time must fall between dispatch and the deadline. Its first provenance-sensitive command must be `await-activation --stage ... --round ... --artifact ... --role ...`; before `running`, it must not snapshot, emit stage-started, write business files, or start commit. Only explicit `recover-prepared` may clear an expired orphan when the task fingerprint is exact and no matching unconsumed active lifecycle evidence remains.
+6. After prepare, run `task-orchestration <task-ref> dispatch` immediately before calling the fresh native child, then use route's exact model/effort and only the short task ref, skill, `--orchestrated`, and stage identity. The trusted hook-spawn first-observation time must fall between dispatch and the deadline. Its first provenance-sensitive command must be `await-activation --stage ... --round ... --artifact ... --role ...`; before `running`, it must not snapshot, emit stage-started, or write business files. The code stage may create a local checkpoint only through code-task's durable intent core; it must not delegate a separate commit stage or push. Only explicit `recover-prepared` may clear an expired orphan when the task fingerprint is exact and no matching unconsumed active lifecycle evidence remains.
 7. Codex uses SubagentStart/Stop and App Server actual evidence to activate, consume, and seal one receipt; trusted parent fallback must produce the same complete provenance. Timed-out waits do nothing. Advance only a sealed receipt and repeat step 4 only while running.
 8. Create a fresh child each round and never follow up with an old reviewer. Each requested/actual mismatch needs its own host fallback reason. Protocol, capability, receipt hook/evidence binding, source, controller, identity, ledger, or fingerprint failure pauses and fails closed; cross-root package/build/contract or hook/profile content drift is delivered as a warning instead of blocking natural evolution.
 9. On pause or completion, run the matching typed verification and report the structured endpoint.

package/templates/.agents/skills/run-task/SKILL.zh-CN.md

@@ -7,6 +7,10 @@ description: >
 
 # 运行任务生命周期
 
+## 任务上下文解析
+
+入口可省略 task ref；显式 task scope 仅接受 `--task <ref>` 或 `-t <ref>`，不再解释位置 task ref。保留四个策略选项及其值，再调用 `agent-infra-internal task-context resolve {task-scope}`。解析失败时透传非零退出码，不自行扫描任务。内部 orchestration 协议仍使用位置 task ref。
+
 总控只编排，不直接执行任何阶段技能。执行前先读取 `.agents/rules/no-mid-flow-questions.md`、`.agents/rules/lifecycle-orchestration.md` 与 `reference/host-validation.md`。
 
 1. 解析规范任务 ID、当前 Agent Client，以及可选的原子策略 `--executor-model`、`--executor-reasoning-effort`、`--reviewer-model`、`--reviewer-reasoning-effort`，并执行 `agent-infra-internal task-snapshot {task-id} --format text`。任一显式策略字段出现时四个 role 字段必须完整，不得与配置拼接；两个角色可以使用同一模型。
@@ -14,7 +18,7 @@ description: >
 3. 调用 `agent-infra-internal task-orchestration {task-id} begin-or-resume --client {client}` 并转发完整显式策略。完全没有显式策略时由核心读取当前 client 的 `agentClients[].orchestration`；existing run 使用持久化策略。磁盘状态不符合当前完整结构时核心失败关闭且不改写；升级前必须完成或清空 active run。仅当核心返回 `ORCHESTRATION_MODEL_POLICY_REQUIRED` 时，先用 `agent-client model-selection` 展示 complete/partial/interactive-only 来源，再一次收集完整策略；未回答则不创建 run。若为 paused/completed，按结构化结果停止。
 4. 调用 `route` 并读取结构化结果。若返回 `completed`，立即运行 `agent-infra-internal task-verify {task-id} run-task.completed --format text` 并停止；仅当返回 `running` 且 `next` 非空时读取唯一 action、role、round、artifact、`requestedModel` 和 `requestedReasoningEffort`，不得自行推断。
 5. Codex 先调用一次 `agent-infra-internal codex-lifecycle capability-arm --task-id {task-id}`。该普通工具调用必须由当前 loop 的真实 PostToolUse 回写 attestation；把 route 返回的精确 model、effort 和 marker 中 token 一并传给 `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort} --capability-token {token}`。核心先校验精确的 model/effort、capability provenance 与 controller binding，再只读捕获快照、构造内存中的 prepared receipt，最后原子消费 token 并保存 prepared 状态，同时持久化 capability 的 session、turn、tool-use 来源。activation 再校验 spawn 与该来源属于同一 session/turn，且 spawn 使用独立的 tool-use。其他客户端直接调用同一 prepare（无 token）。任一失败不得创建 baseline、receipt 或 child。
-6. prepare 成功后，在调用 fresh 原生子 Agent 的紧邻前一步执行 `task-orchestration <task-ref> dispatch`，再显式覆盖 route 返回的 model/effort；只传短任务引用、skill 名、`--orchestrated` 与 stage/round/artifact/role。可信 hook-spawn 首次观察时间必须位于 dispatch 与 deadline 之间。child 的第一条 provenance-sensitive 命令必须是 `await-activation --stage ... --round ... --artifact ... --role ...`；返回 running 前禁止 snapshot、阶段 started、业务写入或 commit。超时由核心暂停；崩溃遗留 prepared receipt 只能在 exact workspace fingerprint、无匹配的未消费 active lifecycle evidence 且 deadline 已过时显式 `recover-prepared`。
+6. prepare 成功后，在调用 fresh 原生子 Agent 的紧邻前一步执行 `task-orchestration <task-ref> dispatch`，再显式覆盖 route 返回的 model/effort；只传短任务引用、skill 名、`--orchestrated` 与 stage/round/artifact/role。可信 hook-spawn 首次观察时间必须位于 dispatch 与 deadline 之间。child 的第一条 provenance-sensitive 命令必须是 `await-activation --stage ... --round ... --artifact ... --role ...`；返回 running 前禁止 snapshot、阶段 started 或业务写入；代码阶段的本地 checkpoint 只能通过 code-task 的持久化 intent 核心完成，禁止单独委派 commit 阶段或推送。超时由核心暂停；崩溃遗留 prepared receipt 只能在 exact workspace fingerprint、无匹配的未消费 active lifecycle evidence 且 deadline 已过时显式 `recover-prepared`。
 7. Codex 用 SubagentStart/Stop 与 App Server actual evidence 激活、消费并封存唯一 receipt；受信 parent fallback 仍必须形成相同的完整 provenance。timed-out wait 无动作；只有 empty turns 或协议 `inProgress` 可等待，malformed、身份/传输错误或异常 terminal 均暂停。子 Agent 返回后只对 sealed receipt 调用 `advance`；只有 `running` 才重复步骤 4。
 8. 每轮创建新 child；禁止 follow-up 复用 reviewer。actual model/effort 与 requested 不同时必须有各自的宿主降级理由。protocol、capability、receipt 内 hook/evidence binding、source、controller、身份、账本或 fingerprint 异常都调用 `pause` 并失败关闭；跨根 package/build/contract 或 hook/profile 内容漂移按 warning 交付，不把自然演进差异当成硬失败。
 9. 完成或暂停后运行对应 typed verification，并把结构化 run 摘要、暂停原因、commit 终点或 clean completion evidence 告知用户。

package/templates/.agents/skills/update-agent-infra/SKILL.en.md

@@ -51,7 +51,7 @@ The script outputs JSON to stdout. Parse and record the report.
 - `managed.conflicts`: guarded managed files with unknown origin, two-sided changes, or ownership that cannot be proven during a platform switch; list each target, reason, and three-way hash
 - `managed.removed`: deleted managed files (including old paths removed during template migrations)
 - `managed.skippedPlatform`: managed / merged entries skipped because they belong to a different platform
-- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in Agent Client whose `agentClients[].enabled` is `false` (legacy `tuis` is migration-only; customTUI command files under the same path prefix are preserved)
+- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in Agent Client whose `agentClients[].enabled` is `false` (customTUI command files under the same path prefix are preserved)
 - `merged.pending`: list of merged files for AI to process
   - Each item has `target` (project-relative path) and `template` (template-root-relative path)
 - `registryAdded`: newly added file registry entries
@@ -131,7 +131,7 @@ warning to the end of the report:
 > **Rationale**: The current execution used the old skill logic; the new version
 > may contain additional processing steps. Running again ensures the new logic
 > is fully applied.
-> Alternatively, users can run `ai update` before executing the skill to
+> Alternatively, users can run `ai sync` before executing the skill to
 > pre-update the seed files and avoid the need for a second run.
 
 ### Output report

package/templates/.agents/skills/update-agent-infra/SKILL.zh-CN.md

@@ -43,7 +43,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 - `managed.conflicts`：来源未知、双边修改或平台切换时无法证明官方所有权的 guarded managed 冲突；必须逐项展示 target、reason 与三方哈希
 - `managed.removed`：被删除的 managed 文件（包括模板迁移时移除的旧路径）
 - `managed.skippedPlatform`：因归属其他平台而被跳过的 managed / merged 条目
-- `managed.skippedTUI`：因对应内建 Agent Client 的 `agentClients[].enabled` 为 `false` 而被跳过的 managed / merged 条目（旧 `tuis` 仅用于迁移；落在同一路径前缀下的 customTUI 命令文件会被保留）
+- `managed.skippedTUI`：因对应内建 Agent Client 的 `agentClients[].enabled` 为 `false` 而被跳过的 managed / merged 条目（落在同一路径前缀下的 customTUI 命令文件会被保留）
 - `merged.pending`：需要 AI 处理的 merged 文件列表
   - 每项包含 `target`（项目中的目标路径）和 `template`（模板根目录下的相对路径）
 - `registryAdded`：新增的文件注册条目
@@ -116,7 +116,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 
 > **原因**：本次执行使用的是旧版技能逻辑，新版技能可能包含额外的处理步骤。
 > 再次执行可确保新逻辑完整应用。
-> 用户也可以在执行前先运行 `ai update` 来预先更新技能文件，避免需要两次执行。
+> 用户也可以在执行前先运行 `ai sync` 来预先更新技能文件，避免需要两次执行。
 
 ### 输出报告
 

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -74,6 +74,10 @@ const DEFAULTS = {
   "task": {
     "shortIdLength": 2
   },
+  "delivery": {
+    "remote": "origin",
+    "baseRef": "main"
+  },
   "labels": {
     "in": {}
   },
@@ -116,6 +120,10 @@ const DEFAULTS = {
     ],
     "ejected": [],
     "retiredManaged": [
+      {
+        "path": ".trae/skills/",
+        "templateHashes": []
+      },
       {
         "path": ".agents/workspace/README.md",
         "templateHashes": [
@@ -200,18 +208,17 @@ const AGENT_CLIENT_MANIFEST = [
     "displayName": "TraeCode CLI",
     "invocation": "/${skillName}",
     "ownedPathPrefixes": [
-      ".trae/"
+      ".traecli/"
     ],
     "managed": [
-      ".trae/skills/"
+      ".traecli/commands/"
     ],
     "merged": [],
     "ejected": [],
     "customCommand": {
-      "target": ".trae/skills/${skillName}.md",
+      "target": ".traecli/commands/${skillName}.md",
       "frontmatter": {},
-      "includeUsage": true,
-      "inheritDisableModelInvocation": true
+      "argumentsToken": "$ARGUMENTS"
     }
   }
 ];
@@ -230,84 +237,19 @@ const CUSTOM_TUI_CONTRACT = {
 const KNOWN_PLATFORMS = new Set(['github', 'none']);
 const KNOWN_LANGUAGES = new Set(['en', 'zh-CN']);
 
-const BUILTIN_TUI_IDS = AGENT_CLIENT_MANIFEST.map((entry) => entry.id);
+const AGENT_CLIENT_IDS = AGENT_CLIENT_MANIFEST.map((entry) => entry.id);
 
 function normalizeAgentClientConfig(cfg) {
   const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
-  const diagnostics = [];
   const failure = (code, path) => ({
-    source: null,
     state: null,
     canonical: null,
-    remainingSandboxTools: undefined,
-    removeLegacyTuis: false,
-    changed: false,
-    diagnostics,
     error: `${code} at ${path}`,
     errorCode: code,
     errorPath: path
   });
-  const projectTuis = (value) => {
-    if (!Array.isArray(value)) {
-      return Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, true]));
-    }
-    const enabled = new Set();
-    for (const [index, candidate] of value.entries()) {
-      if (BUILTIN_TUI_IDS.includes(candidate)) enabled.add(candidate);
-      else diagnostics.push({ code: 'LEGACY_VALUE_IGNORED', path: `tuis[${index}]` });
-    }
-    return Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, enabled.has(id)]));
-  };
-  const projectSandbox = (value) => {
-    if (!Array.isArray(value) || value.length === 0) {
-      return {
-        installed: Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, true])),
-        clientSignals: new Set(),
-        remainingTools: Array.isArray(value) ? [] : undefined
-      };
-    }
-    const installed = new Set();
-    const remainingTools = [];
-    for (const [index, candidate] of value.entries()) {
-      if (BUILTIN_TUI_IDS.includes(candidate)) installed.add(candidate);
-      else if (typeof candidate === 'string') remainingTools.push(candidate);
-      else diagnostics.push({ code: 'LEGACY_VALUE_IGNORED', path: `sandbox.tools[${index}]` });
-    }
-    return {
-      installed: Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, installed.has(id)])),
-      clientSignals: installed,
-      remainingTools
-    };
-  };
-  const serialize = (state) => BUILTIN_TUI_IDS.map((id) => ({ id, ...state[id] }));
-  const hasCanonical = own(cfg, 'agentClients');
-  const hasLegacyTuis = own(cfg, 'tuis');
-  const sandbox = cfg.sandbox && typeof cfg.sandbox === 'object' && !Array.isArray(cfg.sandbox)
-    ? cfg.sandbox
-    : undefined;
-  const hasSandboxTools = sandbox !== undefined && own(sandbox, 'tools');
-  const tuiProjection = projectTuis(cfg.tuis);
-  const sandboxProjection = projectSandbox(sandbox?.tools);
-
-  if (!hasCanonical) {
-    const state = Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, {
-      enabled: tuiProjection[id],
-      installInSandbox: sandboxProjection.installed[id]
-    }]));
-    return {
-      source: 'legacy',
-      state,
-      canonical: serialize(state),
-      remainingSandboxTools: sandboxProjection.remainingTools,
-      removeLegacyTuis: hasLegacyTuis,
-      changed: true,
-      diagnostics,
-      error: null,
-      errorCode: null,
-      errorPath: null
-    };
-  }
-
+  const serialize = (state) => AGENT_CLIENT_IDS.map((id) => ({ id, ...state[id] }));
+  if (!own(cfg, 'agentClients')) return failure('MISSING_AGENT_CLIENT', 'agentClients');
   if (!Array.isArray(cfg.agentClients)) return failure('INVALID_AGENT_CLIENTS', 'agentClients');
   const entries = new Map();
   for (const [index, candidate] of cfg.agentClients.entries()) {
@@ -325,7 +267,7 @@ function normalizeAgentClientConfig(cfg) {
     ) {
       return failure('INVALID_AGENT_CLIENTS', entryPath);
     }
-    if (!BUILTIN_TUI_IDS.includes(candidate.id)) {
+    if (!AGENT_CLIENT_IDS.includes(candidate.id)) {
       return failure('UNKNOWN_AGENT_CLIENT', `${entryPath}.id`);
     }
     if (entries.has(candidate.id)) return failure('DUPLICATE_AGENT_CLIENT', `${entryPath}.id`);
@@ -335,24 +277,44 @@ function normalizeAgentClientConfig(cfg) {
     let orchestration;
     if (own(candidate, 'orchestration')) {
       const policy = candidate.orchestration;
-      const exact = (value) => typeof value === 'string' && value.length > 0 && value.trim() === value;
-      const validRole = (role) => role
-        && typeof role === 'object'
-        && !Array.isArray(role)
-        && Object.keys(role).length === 2
-        && exact(role.model)
-        && exact(role.reasoningEffort);
       if (
         !policy
         || typeof policy !== 'object'
         || Array.isArray(policy)
         || Object.keys(policy).length !== 2
-        || !validRole(policy.executor)
-        || !validRole(policy.reviewer)
+        || !own(policy, 'executor')
+        || !own(policy, 'reviewer')
       ) {
         return failure('INVALID_AGENT_CLIENTS', `${entryPath}.orchestration`);
       }
-      orchestration = structuredClone(policy);
+      const parseExact = (value, path) => {
+        if (typeof value !== 'string' || value.length === 0 || value.trim() !== value) {
+          return failure('INVALID_AGENT_CLIENTS', path);
+        }
+        return value;
+      };
+      const parseRole = (role, rolePath) => {
+        if (
+          !role
+          || typeof role !== 'object'
+          || Array.isArray(role)
+          || Object.keys(role).length !== 2
+          || !own(role, 'model')
+          || !own(role, 'reasoningEffort')
+        ) {
+          return failure('INVALID_AGENT_CLIENTS', rolePath);
+        }
+        const model = parseExact(role.model, `${rolePath}.model`);
+        if (typeof model !== 'string') return model;
+        const reasoningEffort = parseExact(role.reasoningEffort, `${rolePath}.reasoningEffort`);
+        if (typeof reasoningEffort !== 'string') return reasoningEffort;
+        return { model, reasoningEffort };
+      };
+      const executor = parseRole(policy.executor, `${entryPath}.orchestration.executor`);
+      if (executor.errorCode) return executor;
+      const reviewer = parseRole(policy.reviewer, `${entryPath}.orchestration.reviewer`);
+      if (reviewer.errorCode) return reviewer;
+      orchestration = { executor, reviewer };
     }
     entries.set(candidate.id, {
       enabled: candidate.enabled,
@@ -360,25 +322,29 @@ function normalizeAgentClientConfig(cfg) {
       ...(orchestration ? { orchestration } : {})
     });
   }
-  if (BUILTIN_TUI_IDS.some((id) => !entries.has(id))) {
+  if (AGENT_CLIENT_IDS.some((id) => !entries.has(id))) {
     return failure('MISSING_AGENT_CLIENT', 'agentClients');
   }
-  const state = Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, entries.get(id)]));
-  if (hasLegacyTuis && BUILTIN_TUI_IDS.some((id) => state[id].enabled !== tuiProjection[id])) {
-    return failure('LEGACY_CONFLICT', 'tuis');
+  for (const [index, id] of AGENT_CLIENT_IDS.entries()) {
+    if (cfg.agentClients[index]?.id !== id) {
+      return failure('INVALID_AGENT_CLIENTS', `agentClients[${index}].id`);
+    }
   }
-  if ([...sandboxProjection.clientSignals].some((id) => !state[id].installInSandbox)) {
-    return failure('LEGACY_CONFLICT', 'sandbox.tools');
+  if (own(cfg, 'tuis')) return failure('INVALID_AGENT_CLIENTS', 'tuis');
+  const sandbox = cfg.sandbox && typeof cfg.sandbox === 'object' && !Array.isArray(cfg.sandbox)
+    ? cfg.sandbox
+    : undefined;
+  if (Array.isArray(sandbox?.tools)) {
+    for (const [index, tool] of sandbox.tools.entries()) {
+      if (AGENT_CLIENT_IDS.includes(tool)) {
+        return failure('INVALID_AGENT_CLIENTS', `sandbox.tools[${index}]`);
+      }
+    }
   }
-  const sameOrder = cfg.agentClients.every((entry, index) => entry.id === BUILTIN_TUI_IDS[index]);
+  const state = Object.fromEntries(AGENT_CLIENT_IDS.map((id) => [id, entries.get(id)]));
   return {
-    source: 'canonical',
     state,
     canonical: serialize(state),
-    remainingSandboxTools: hasSandboxTools ? sandboxProjection.remainingTools : undefined,
-    removeLegacyTuis: hasLegacyTuis,
-    changed: hasLegacyTuis || sandboxProjection.clientSignals.size > 0 || !sameOrder,
-    diagnostics,
     error: null,
     errorCode: null,
     errorPath: null
@@ -387,16 +353,6 @@ function normalizeAgentClientConfig(cfg) {
 
 function materializeAgentClientConfig(cfg, normalized) {
   cfg.agentClients = normalized.canonical;
-  delete cfg.tuis;
-  if (normalized.remainingSandboxTools !== undefined) {
-    cfg.sandbox = {
-      ...(cfg.sandbox || {}),
-      tools: [
-        'agent-infra',
-        ...normalized.remainingSandboxTools.filter((tool) => tool !== 'agent-infra')
-      ]
-    };
-  }
 }
 
 function assetMatches(entry, target) {
@@ -483,6 +439,17 @@ function isInsideProject(projectRoot, relativePath) {
   return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
+function isInsideProjectDirectory(projectRoot, directory, relativePath) {
+  if (!isInsideProject(projectRoot, directory) || !isInsideProject(projectRoot, relativePath)) {
+    return false;
+  }
+
+  const root = path.resolve(projectRoot, directory);
+  const resolved = path.resolve(projectRoot, relativePath);
+  const rel = path.relative(root, resolved);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
 function isPathOwnedByOtherPlatform(relativePath, platformType) {
   const normalized = norm(relativePath).replace(/^\.\//, '');
   const top = normalized.split('/')[0];
@@ -1310,7 +1277,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
     return { error: enabledResolution.error };
   }
   const enabledTUIs = new Set(
-    BUILTIN_TUI_IDS.filter((id) => enabledResolution.state[id].enabled)
+    AGENT_CLIENT_IDS.filter((id) => enabledResolution.state[id].enabled)
   );
   materializeAgentClientConfig(cfg, enabledResolution);
   const customTUIsConfig = Array.isArray(cfg.customTUIs) ? cfg.customTUIs : [];
@@ -1330,6 +1297,10 @@ function syncTemplates(projectRoot, templateRootOverride) {
       (descriptor.templateHashes || []).map(trustedBaseline).filter(Boolean)
     )];
   }));
+  const retiredManagedForTarget = (target) => [...retiredManaged.entries()].find(
+    ([entry]) => assetMatches(entry, target)
+      && (!entry.endsWith('/') || isInsideProjectDirectory(projectRoot, entry, target))
+  );
   const planningRegistry = {
     ...currentRegistry,
     managed: currentRegistry.managed.filter((entry) => !retiredManaged.has(norm(entry)))
@@ -1358,7 +1329,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
   for (const target of Object.keys(managedBaselines)) {
     if (
       !guardedManaged.has(norm(target))
-      && !retiredManaged.has(norm(target))
+      && !retiredManagedForTarget(target)
       && !allClientManaged.some((entry) => assetMatches(entry, target))
     ) {
       delete managedBaselines[target];
@@ -1434,8 +1405,72 @@ function syncTemplates(projectRoot, templateRootOverride) {
   );
 
   for (const [entry, historicalTemplateHashes] of retiredManaged) {
-    const target = path.join(projectRoot, entry);
+    const target = path.join(projectRoot, entry.endsWith('/') ? entry.slice(0, -1) : entry);
     const owned = currentRegistry.managed.some((candidate) => norm(candidate) === entry);
+    if (entry.endsWith('/')) {
+      if (fs.existsSync(target)) {
+        const targetStat = fs.lstatSync(target);
+        if (!targetStat.isDirectory() || targetStat.isSymbolicLink()) {
+          report.managed.protected.push({
+            target: entry,
+            reason: 'invalid-type',
+            baseline: null,
+            local: null,
+            template: null
+          });
+          continue;
+        }
+      }
+      const candidates = new Set(
+        Object.keys(managedBaselines).filter((candidate) =>
+          assetMatches(entry, candidate)
+            && isInsideProjectDirectory(projectRoot, entry, candidate)
+        )
+      );
+      if (owned && fs.existsSync(target)) {
+        for (const filePath of walkDir(target)) {
+          candidates.add(norm(path.relative(projectRoot, filePath)));
+        }
+      }
+
+      for (const candidate of candidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        const baseline = trustedBaseline(managedBaselines[candidate]);
+        if (!fs.existsSync(candidatePath)) {
+          if (Object.prototype.hasOwnProperty.call(managedBaselines, candidate)) {
+            delete managedBaselines[candidate];
+            baselinesChanged = true;
+          }
+          continue;
+        }
+        const stat = fs.lstatSync(candidatePath);
+        const localHash = stat.isFile() && !stat.isSymbolicLink()
+          ? sha256(fs.readFileSync(candidatePath))
+          : null;
+        const safeToRemove = localHash !== null
+          && (localHash === baseline || historicalTemplateHashes.has(localHash));
+        if (safeToRemove) {
+          fs.unlinkSync(candidatePath);
+          report.managed.removed.push(candidate);
+        } else {
+          report.managed.protected.push({
+            target: candidate,
+            reason: localHash === null
+              ? 'invalid-type'
+              : (baseline !== null ? 'user-modified' : 'unknown-origin'),
+            baseline,
+            local: localHash,
+            template: null
+          });
+        }
+        if (Object.prototype.hasOwnProperty.call(managedBaselines, candidate)) {
+          delete managedBaselines[candidate];
+          baselinesChanged = true;
+        }
+      }
+      removeEmptyDirs(target);
+      continue;
+    }
     if (!fs.existsSync(target)) continue;
     const stat = fs.lstatSync(target);
     const baseline = trustedBaseline(managedBaselines[entry]);

package/templates/.agents/skills/watch-pr/SKILL.en.md

@@ -21,7 +21,7 @@ Version stamp rule: before creating or updating `task.md` frontmatter, read `.ag
 
 ## Task Context Resolution
 
-> Keep `--pr <number>` and PR URLs on the existing PR-anchored path. Otherwise, the task path may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments, then call `agent-infra-internal task-context resolve {task-scope}` and bind `{task-id}` to the returned full `taskId`. A PR anchor and task scope are mutually exclusive.
+> Keep `--pr <number>` and PR URLs on the existing PR-anchored path. Otherwise, the task path may omit the task ref; explicit task scope accepts only `--task <ref>` or `-t <ref>`, and positional task refs are not interpreted. Separate task scope from the full arguments, then call `agent-infra-internal task-context resolve {task-scope}` and bind `{task-id}` to the returned full `taskId`. A PR anchor and task scope are mutually exclusive.
 
 ## Step Start: Write the started Marker
 
@@ -39,8 +39,8 @@ After prerequisites pass and before this round's first artifact action, append a
 
 Resolve the target PR number `{pr#}` and an optional `{task-id}` via these deterministic branches:
 
-- Scenario A (argument omitted): reverse-lookup the active task from the current branch, then read its `pr_number`.
-- Scenario B (omitted task ref, positional task ref, or `--task/-t`, **task-anchored primary path**): resolve the full `{task-id}` via "Task Context Resolution" and read `.agents/workspace/active/{task-id}/task.md` for `pr_number` as `{pr#}`; if `pr_number` is empty, follow "Error Handling" to prompt running `create-pr` first, then stop.
+- Scenario A (argument omitted): reverse-lookup the active task from the current branch, then read its verified `pr_delivery_fact.identity.number`.
+- Scenario B (omitted task ref or `--task/-t`, **task-anchored primary path**): resolve the full `{task-id}` via "Task Context Resolution" and read `.agents/workspace/active/{task-id}/task.md` for verified `pr_delivery_fact.identity.number` as `{pr#}`; if the fact is unbound, follow "Error Handling" to prompt running `create-pr` first, then stop.
 - Scenario C (`--pr <number>` or a PR URL): use that PR number directly as `{pr#}`; then determine `{task-id}` via "Reverse-lookup task".
 - Reverse-lookup task (scenarios A / C): use task context/query capabilities to find the unique active task bound to `{pr#}`. If none exists, stop and request binding first; the typed checks intent does not create a second taskless state machine.
 
@@ -74,7 +74,7 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - `assigned_to`: {current agent}
 - `updated_at`: {current time}
 - `agent_infra_version`: per `.agents/rules/version-stamp.md`
-- **Do not change** `pr_status` (keep `created`) or `current_step`
+- **Do not change** `pr_delivery_fact` or `current_step`
 - **Append** to `## Activity Log` (do not overwrite prior entries; `{N}` = number of existing Watch PR entries for this task + 1):
   ```
   - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Watch PR (Round {N})** by {agent} — {success: PR ready, repair commits: {k} [{SHA summary}] / blocked: blocked: {summary}}
@@ -148,6 +148,6 @@ Stop immediately after the checklist. The green exit waits for the user to run `
 
 ## Error Handling
 
-- Cannot locate a PR (task short id resolves but task.md has no `pr_number`, and no `--pr` was passed and the current branch has no PR): prompt "Run `create-pr` first, or specify the PR with `--pr <number>`", then stop.
+- Cannot locate a PR (task short id resolves but task.md has no verified bound `pr_delivery_fact`, and no `--pr` was passed and the current branch has no PR): prompt "Run `create-pr` first, or specify the PR with `--pr <number>`", then stop.
 - Platform CLI not authenticated or API unavailable: prompt that manual intervention is needed, then stop.
 - Short-id resolution failure: pass through `task-short-id.js`'s exit code and error message; do not rewrite it.

package/templates/.agents/skills/watch-pr/SKILL.zh-CN.md

@@ -21,7 +21,7 @@ description: >
 
 ## 任务上下文解析
 
-> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
+> 入口允许省略 task ref，也接受 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
 
 ## 步骤开始：写入 started 标记
 
@@ -39,8 +39,8 @@ description: >
 
 按以下确定性分支解析出目标 PR 号 `{pr#}` 与可选 `{task-id}`：
 
-- 场景 A（省略入参）：从当前分支反查 active task；定位后读取其 `pr_number`。
-- 场景 B（省略 task ref、旧位置 task ref 或 `--task/-t`，**任务锚定主路径**）：按「任务上下文解析」取得完整 `{task-id}`。读 `.agents/workspace/active/{task-id}/task.md` 取 `pr_number` 作为 `{pr#}`；`pr_number` 为空时按「错误处理」提示先 `create-pr`，停止。
+- 场景 A（省略入参）：从当前分支反查 active task；定位后读取其 verified `pr_delivery_fact.identity.number`。
+- 场景 B（省略 task ref 或 `--task/-t`，**任务锚定主路径**）：按「任务上下文解析」取得完整 `{task-id}`。读 `.agents/workspace/active/{task-id}/task.md` 取 verified `pr_delivery_fact.identity.number` 作为 `{pr#}`；fact 未绑定时按「错误处理」提示先 `create-pr`，停止。
 - 场景 C（`--pr <number>` 或 PR URL）：直接取该 PR 号为 `{pr#}`；随后按「反查任务」确定 `{task-id}`。
 - 反查任务（场景 A / C）：通过任务上下文/任务查询取得与 `{pr#}` 唯一绑定的 active task。未命中时停止并提示先绑定 PR；typed checks intent 不建立第二套无任务状态机。
 
@@ -74,7 +74,7 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 - `assigned_to`：{当前代理}
 - `updated_at`：{当前时间}
 - `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
-- **不改** `pr_status`（保持 `created`）与 `current_step`
+- **不改** `pr_delivery_fact` 与 `current_step`
 - **追加**到 `## 活动日志`（不要覆盖之前的记录；`{N}` = 本任务已有 Watch PR 条目数 + 1）：
   ```
   - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Watch PR (Round {N})** by {agent} — {成功：PR ready, repair commits: {k} [{sha 摘要}] / 阻塞：blocked: {简述}}
@@ -148,6 +148,6 @@ agent-infra-internal task-verify {task-id} watch-pr.completed --format text
 
 ## 错误处理
 
-- 无法定位 PR（任务短号命中但 task.md 无 `pr_number`，且未传 `--pr`、当前分支也无 PR）：提示「请先运行 `create-pr`，或用 `--pr <number>` 指定 PR」，停止。
+- 无法定位 PR（任务短号命中但 task.md 无 verified bound `pr_delivery_fact`，且未传 `--pr`、当前分支也无 PR）：提示「请先运行 `create-pr`，或用 `--pr <number>` 指定 PR」，停止。
 - 平台 CLI 未认证或 API 不可用：提示需人工介入，停止。
 - 短号解析失败：透传 `task-short-id.js` 的退出码与错误信息，不重写。

package/templates/.agents/templates/task.en.md

@@ -13,7 +13,11 @@ start_date:                     # Optional Issue field for Feature: YYYY-MM-DD
 target_date:                    # Optional Issue field for Feature: YYYY-MM-DD
 current_step: requirement-analysis # requirement-analysis | requirement-analysis-review | technical-design | technical-design-review | code | code-review | completed
 assigned_to:                   # claude | codex | antigravity | opencode | human
-pr_status: pending             # PR status: pending (default) | created (PR created) | skipped (explicitly skipped)
+pr_delivery_fact: '{"version":1,"state":"unbound","reason":"initial"}'
+delivery_remote: origin        # Git remote used to deliver the task branch
+delivery_base_ref: main        # Target branch for the task PR
+checkpoint_commit:             # Most recent local checkpoint commit
+delivery_remote_head:          # Most recent successfully delivered task branch SHA
 ---
 
 # Task: [Title]
@@ -80,7 +84,7 @@ pr_status: pending             # PR status: pending (default) | created (PR crea
 
 ## Human Rulings
 
-<!-- Use ai decide <task-ref> <ordinal|ledger-id> [--needs-implementation true|false] <decision> for needs-human-decision rulings; upstream AI predeclares implementation intent for new code decisions, while the explicit option remains for legacy tasks or consistency checks. -->
+<!-- Use ai decide [--task <ref> | -t <ref>] (--item <ordinal|ledger-id> | -i <ordinal|ledger-id>) [--needs-implementation true|false] <decision> for needs-human-decision rulings; upstream AI predeclares implementation intent for new code decisions, while the explicit option remains for legacy tasks or consistency checks. -->
 
 ## Implementation Inputs
 

package/templates/.agents/templates/task.zh-CN.md

@@ -13,7 +13,11 @@ start_date:                     # Feature 可选 Issue 字段：YYYY-MM-DD
 target_date:                    # Feature 可选 Issue 字段：YYYY-MM-DD
 current_step: requirement-analysis # requirement-analysis | requirement-analysis-review | technical-design | technical-design-review | code | code-review | completed
 assigned_to:                   # claude | codex | antigravity | opencode | human
-pr_status: pending             # PR 状态：pending（默认）| created（已创建 PR）| skipped（显式跳过）
+pr_delivery_fact: '{"version":1,"state":"unbound","reason":"initial"}'
+delivery_remote: origin        # 任务分支交付使用的 Git remote
+delivery_base_ref: main        # 任务 PR 的目标分支
+checkpoint_commit:             # 最近一次本地 checkpoint commit
+delivery_remote_head:          # 最近一次成功交付到 remote 的任务分支 SHA
 ---
 
 # 任务：[标题]
@@ -80,7 +84,7 @@ pr_status: pending             # PR 状态：pending（默认）| created（已
 
 ## 人工裁决
 
-<!-- 使用 ai decide <task-ref> <序号|账本ID> [--needs-implementation true|false] <裁决内容> 写入 needs-human-decision 裁定；新建 code 裁决的实现意图由上游 AI 预先声明，显式参数仅用于历史任务兼容或一致性复核。 -->
+<!-- 使用 ai decide [--task <ref> | -t <ref>] (--item <序号|账本ID> | -i <序号|账本ID>) [--needs-implementation true|false] <裁决内容> 写入 needs-human-decision 裁定；新建 code 裁决的实现意图由上游 AI 预先声明，显式参数仅用于历史任务兼容或一致性复核。 -->
 
 ## 实现输入