@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/templates/.agents/skills/run-task/reference/host-validation.en.md

@@ -5,16 +5,18 @@ Before publishing support for a client, prove the lifecycle evidence chain with
 ## Required Evidence
 
 - Client version, enabled multi-agent capability, launch surface, and trust boundary.
-- Raw start/stop events stably provide event type, managed agent, parent/child identity, fresh spawn mode, actual model, and actual reasoning effort.
+- Raw start/stop events, or the parent PostTool spawn/completed-wait fallback when custom roles omit them, stably correlate the managed agent, parent/child identity, fresh spawn mode, actual model, and actual reasoning effort.
 - Explicit requested model/effort reaches each executor/reviewer. A fallback of either field reports the corresponding actual value and its own non-empty reason.
 - Candidate-checkout and packed-install behavior match, with model policy, receipts, and verification results auditable in `orchestration.json`.
+- Direct-host project/managed source and sandbox isolated-user source preserve the same build, contract, profile, and controller provenance through prepare/start/stop/consume.
 
 ## Validation Sequence
 
 1. Record client version, feature state, and launch command in a clean temporary repository.
-2. Start a fresh executor and reviewer, retaining redacted raw stdin and the structured run. Never synthesize a field the host did not emit.
+2. Start a fresh executor and reviewer, retaining redacted raw stdin and the structured run. Validate both native start/stop and the parent PostTool fallback; timed-out waits must do nothing. Never synthesize a field the host did not emit.
 3. Validate model/effort match paths, single and dual justified fallbacks, and fail-closed behavior for missing actual fields.
 4. Validate the same commit from a candidate checkout and an `npm pack` install; record the tarball hash and results.
 5. Commit only redacted summaries and non-sensitive fixtures. Remove or replace tokens, user-specific absolute paths, transcript content, and credentials.
+6. For sandbox, run at least ten cold executor starts and ten cold reviewer starts. Record monotonic prepared, spawn-dispatch, SubagentStart, and activation-completed timestamps plus p50/p95/max. Enable only when max plus 20% fits the deadline and symlink/config/plugin/lease/context/build failure injection and terminal cleanup audits pass.
 
-If any required field cannot be observed reliably from the real host, keep that client's orchestration capability `unsupported` and record the gap as manual validation.
+If any required field cannot be observed reliably from the real host, keep that client's orchestration capability `unsupported` and record the gap as manual validation. Codex may advertise `experimental`, but every `prepare` must still pass static preflight and either native start/stop or the parent spawn/completed-wait fallback must produce verifiable consumed host evidence. The fallback may wait only for empty turns or protocol `inProgress`; malformed, identity/transport errors, or abnormal terminals pause deterministically.

package/templates/.agents/skills/run-task/reference/host-validation.zh-CN.md

@@ -5,16 +5,18 @@
 ## 必须证明的字段
 
 - 客户端版本、启用的多代理能力、启动入口与信任边界。
-- 原始 start/stop 事件能稳定给出 event type、managed agent、parent/child identity、fresh spawn mode、actual model 和 actual reasoning effort。
+- 原始 start/stop 事件，或 custom role 缺少它们时的 parent PostTool spawn/completed-wait fallback，能稳定关联 managed agent、parent/child identity、fresh spawn mode、actual model 和 actual reasoning effort。
 - 显式 requested model/effort 能传给 executor/reviewer；宿主对任一字段回退时，事件能给出对应 actual 值与独立的非空 fallback reason。
 - candidate checkout 与打包安装后的行为一致，且模型策略、receipt 与验证结果可从 `orchestration.json` 复核。
+- direct-host 的 project/managed source 与 sandbox controller 的 isolated-user source、build/contract/profile/controller digest 必须在 prepare/start/stop/consume 全链路一致。
 
 ## 验证顺序
 
 1. 在干净临时仓库记录客户端版本、feature 状态和启动命令。
-2. 分别启动 fresh executor 与 fresh reviewer，保存去敏后的原始 stdin 和结构化 run；不得补写宿主未产生的字段。
+2. 分别启动 fresh executor 与 fresh reviewer，保存去敏后的原始 stdin 和结构化 run；同时验证原生 start/stop 与 parent PostTool fallback。timed-out wait 必须无动作；不得补写宿主未产生的字段。
 3. 分别验证 model/effort 的 requested/actual 一致路径、单项与双项有理由 fallback 路径，并确认缺 actual 字段会失败关闭。
 4. 对同一 commit 执行 candidate checkout 与 `npm pack` 安装验证，记录 tarball 哈希和结果。
 5. 仅把去敏摘要与非敏感 fixture 纳入版本库；token、绝对用户路径、transcript 内容和凭证必须删除或替换。
+6. sandbox backend 另做至少 10 次 executor 与 10 次 reviewer 冷启动，记录 prepared、spawn dispatch、SubagentStart、activation completed 的单调时钟及 p50/p95/max；仅当 max 加 20% 余量不超过 deadline，并通过 symlink/config/plugin/lease/context/build 失败注入和终态清理审计时启用。
 
-任一字段无法从真实宿主稳定观察时，该客户端的 orchestration capability 保持 `unsupported`，并把缺口记录为人工验证项。
+任一字段无法从真实宿主稳定观察时，该客户端的 orchestration capability 保持 `unsupported`，并把缺口记录为人工验证项。Codex 可声明为 `experimental`，但每次 `prepare` 仍必须通过静态 preflight，且原生 start/stop 或 parent spawn/completed-wait fallback 必须形成可验证的 consumed host evidence。fallback 只允许 empty turns/协议 `inProgress` 等待；malformed、身份/传输错误或异常 terminal 都稳定暂停。

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

@@ -82,7 +82,6 @@ const DEFAULTS = {
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
-      ".agents/workspace/README.md",
       ".git-hooks/check-large-files.cjs",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
@@ -110,7 +109,16 @@ const DEFAULTS = {
       ".git-hooks/pre-commit",
       ".gitignore"
     ],
-    "ejected": []
+    "ejected": [],
+    "retiredManaged": [
+      {
+        "path": ".agents/workspace/README.md",
+        "templateHashes": [
+          "sha256:967b27ca4008154c5abf99a1df728242f80ed3ace9bd98eb2828bc1c76af826c",
+          "sha256:15aa21942cf2a1396d27834f1d3d723b61a46f8d14600b706f39f3bebc21aea3"
+        ]
+      }
+    ]
   }
 };
 
@@ -1224,6 +1232,26 @@ function entryVariantRels(entry, allSet, platform) {
   return rels;
 }
 
+function ensureRuntimeWorkspace(projectRoot) {
+  const directories = [
+    path.join(projectRoot, '.agents'),
+    path.join(projectRoot, '.agents', 'workspace'),
+    ...['active', 'blocked', 'completed', 'archive'].map((state) =>
+      path.join(projectRoot, '.agents', 'workspace', state)
+    )
+  ];
+  for (const directory of directories) {
+    if (fs.existsSync(directory)) {
+      const stat = fs.lstatSync(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Runtime workspace path must be a real directory: ${directory}`);
+      }
+      continue;
+    }
+    fs.mkdirSync(directory, { mode: 0o700 });
+  }
+}
+
 function syncTemplates(projectRoot, templateRootOverride) {
   const configDir = path.join(projectRoot, '.agents');
   const cfgPath = path.join(configDir, '.airc.json');
@@ -1234,6 +1262,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
 
   const originalConfigText = fs.readFileSync(cfgPath, 'utf8');
   const cfg = JSON.parse(originalConfigText);
+  ensureRuntimeWorkspace(projectRoot);
   const configPathRel = norm(path.relative(projectRoot, cfgPath));
   let templateRoot = templateRootOverride;
   if (!templateRoot) {
@@ -1271,6 +1300,16 @@ function syncTemplates(projectRoot, templateRootOverride) {
     merged: [...(cfg.files.merged || [])],
     ejected: [...(cfg.files.ejected || [])]
   };
+  const retiredManaged = new Map((DEFAULTS.files.retiredManaged || []).map((retired) => {
+    const descriptor = typeof retired === 'string' ? { path: retired } : retired;
+    return [norm(descriptor.path), new Set(
+      (descriptor.templateHashes || []).map(trustedBaseline).filter(Boolean)
+    )];
+  }));
+  const planningRegistry = {
+    ...currentRegistry,
+    managed: currentRegistry.managed.filter((entry) => !retiredManaged.has(norm(entry)))
+  };
   const sharedDefaults = {
     managed: (DEFAULTS.files.managed || []).filter(
       (entry) => !isPathOwnedByOtherPlatform(entry, platformType)
@@ -1280,7 +1319,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
     ),
     ejected: [...(DEFAULTS.files.ejected || [])]
   };
-  const assetPlan = planProjectRegistry(currentRegistry, sharedDefaults, enabledTUIs);
+  const assetPlan = planProjectRegistry(planningRegistry, sharedDefaults, enabledTUIs);
   const managed = [...assetPlan.registry.managed];
   const merged = [...assetPlan.registry.merged];
   const ejected = [...assetPlan.registry.ejected];
@@ -1295,6 +1334,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
   for (const target of Object.keys(managedBaselines)) {
     if (
       !guardedManaged.has(norm(target))
+      && !retiredManaged.has(norm(target))
       && !allClientManaged.some((entry) => assetMatches(entry, target))
     ) {
       delete managedBaselines[target];
@@ -1369,6 +1409,38 @@ function syncTemplates(projectRoot, templateRootOverride) {
     )
   );
 
+  for (const [entry, historicalTemplateHashes] of retiredManaged) {
+    const target = path.join(projectRoot, entry);
+    const owned = currentRegistry.managed.some((candidate) => norm(candidate) === entry);
+    if (!fs.existsSync(target)) continue;
+    const stat = fs.lstatSync(target);
+    const baseline = trustedBaseline(managedBaselines[entry]);
+    const localHash = stat.isFile() && !stat.isSymbolicLink()
+      ? sha256(fs.readFileSync(target))
+      : null;
+    const safeToRemove = owned
+      && localHash !== null
+      && (localHash === baseline || historicalTemplateHashes.has(localHash));
+    if (safeToRemove) {
+      fs.unlinkSync(target);
+      report.managed.removed.push(entry);
+      if (Object.prototype.hasOwnProperty.call(managedBaselines, entry)) {
+        delete managedBaselines[entry];
+        baselinesChanged = true;
+      }
+    } else {
+      report.managed.protected.push({
+        target: entry,
+        reason: owned && localHash !== null && baseline !== null
+          ? 'user-modified'
+          : (owned && localHash === null ? 'invalid-type' : 'unknown-origin'),
+        baseline,
+        local: localHash,
+        template: null
+      });
+    }
+  }
+
   const templateSources = Array.isArray(cfg.templates?.sources) ? cfg.templates.sources : [];
   report.templateSources.configured = templateSources.length;
   const { mergedRels, sourceMap } = mergeTemplateSources(templateRoot, templateSources, report);

package/templates/.claude/commands/run-manual-validation.en.md

@@ -0,0 +1,9 @@
+---
+description: "Run host-side task validation and record sanitized evidence"
+usage: "/run-manual-validation <task-ref> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] -- <command...>"
+disable-model-invocation: true
+---
+
+Read and execute the run-manual-validation skill from `.agents/skills/run-manual-validation/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.claude/commands/run-manual-validation.zh-CN.md

@@ -0,0 +1,9 @@
+---
+description: "运行宿主侧任务校验并记录去敏证据"
+usage: "/run-manual-validation <task-ref> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] -- <command...>"
+disable-model-invocation: true
+---
+
+读取并执行 `.agents/skills/run-manual-validation/SKILL.md` 中的 run-manual-validation 技能。
+
+严格按照技能中定义的所有步骤执行。

package/templates/.codex/hooks.json

@@ -13,12 +13,12 @@
         ]
       },
       {
-        "matcher": "^collaborationspawn_agent$",
+      "matcher": "^collaborationspawn_agent$",
         "hooks": [
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js\" --client codex --event pre-tool",
-            "timeout": 5,
+            "timeout": 15,
             "statusMessage": "Recording Codex lifecycle spawn evidence"
           }
         ]
@@ -26,12 +26,12 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "^collaborationspawn_agent$",
+      "matcher": "",
         "hooks": [
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js\" --client codex --event post-tool",
-            "timeout": 5,
+            "timeout": 15,
             "statusMessage": "Recording Codex lifecycle tool completion"
           }
         ]
@@ -39,12 +39,12 @@
     ],
     "SubagentStart": [
       {
-        "matcher": "^agent-infra-lifecycle-(executor|reviewer)$",
+        "matcher": "",
         "hooks": [
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js\" --client codex --event subagent-start",
-            "timeout": 5,
+            "timeout": 15,
             "statusMessage": "Recording Codex child identity"
           }
         ]
@@ -52,12 +52,12 @@
     ],
     "SubagentStop": [
       {
-        "matcher": "^agent-infra-lifecycle-(executor|reviewer)$",
+        "matcher": "",
         "hooks": [
           {
             "type": "command",
             "command": "node \"$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js\" --client codex --event subagent-stop",
-            "timeout": 5,
+            "timeout": 15,
             "statusMessage": "Recording Codex child stop evidence"
           }
         ]

package/templates/.opencode/commands/run-manual-validation.en.md

@@ -0,0 +1,11 @@
+---
+description: "Run host-side task validation and record sanitized evidence"
+agent: general
+subtask: false
+---
+
+Run manual validation: $ARGUMENTS
+
+Read and execute the run-manual-validation skill from `.agents/skills/run-manual-validation/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.opencode/commands/run-manual-validation.zh-CN.md

@@ -0,0 +1,11 @@
+---
+description: "运行宿主侧任务校验并记录去敏证据"
+agent: general
+subtask: false
+---
+
+运行人工校验：$ARGUMENTS
+
+读取并执行 `.agents/skills/run-manual-validation/SKILL.md` 中的 run-manual-validation 技能。
+
+严格按照技能中定义的所有步骤执行。

package/templates/.agents/workspace/README.en.md

@@ -1,26 +0,0 @@
-# AI Workspace
-
-This directory is the runtime workspace for multi-AI collaboration. All contents are **git-ignored** except for this README and `.gitkeep` files.
-
-## Directory Structure
-
-```
-.agents/workspace/
-  active/           # Currently active tasks and handoff documents
-  blocked/          # Tasks that are blocked and waiting for resolution
-  completed/        # Completed tasks (kept for reference)
-  logs/             # Collaboration logs and session records
-```
-
-## Usage
-
-- **active/**: Place task files here when work begins. Move them to `completed/` or `blocked/` as appropriate.
-- **blocked/**: Move tasks here when they cannot proceed. Document the blocker in the task file.
-- **completed/**: Move tasks here when they are done. These serve as a historical record.
-- **logs/**: Store session logs, AI conversation exports, or collaboration notes.
-
-## Important
-
-- Contents of this directory are **not version-controlled** (git-ignored).
-- Do not store anything here that needs to be shared via git.
-- Templates and workflow definitions belong in `.agents/`, not here.

package/templates/.agents/workspace/README.zh-CN.md

@@ -1,26 +0,0 @@
-# AI 工作区
-
-本目录是多 AI 协作的运行时工作区。除本 README 和 `.gitkeep` 文件外，所有内容均被 **git ignore**。
-
-## 目录结构
-
-```
-.agents/workspace/
-  active/           # 当前活跃的任务和交接文档
-  blocked/          # 被阻塞的任务，等待解决
-  completed/        # 已完成的任务（保留供参考）
-  logs/             # 协作日志和会话记录
-```
-
-## 使用方法
-
-- **active/**：工作开始时将任务文件放在这里。根据情况将其移至 `completed/` 或 `blocked/`。
-- **blocked/**：当任务无法继续时将其移至此处。在任务文件中记录阻塞原因。
-- **completed/**：任务完成后将其移至此处。这些作为历史记录保留。
-- **logs/**：存储会话日志、AI 对话导出或协作笔记。
-
-## 重要事项
-
-- 本目录的内容**不受版本控制**（已被 git ignore）。
-- 不要在这里存储需要通过 git 共享的内容。
-- 模板和工作流定义属于 `.agents/` 目录，而非此处。