@fitlab-ai/agent-infra 0.12.1 → 0.12.2

package/lib/task/verification-checks.ts

@@ -1,10 +0,0 @@
-const LOCAL_VERIFICATION_CHECKS = [
-  'task-meta', 'artifact', 'implementation-input', 'activity-log', 'completion-checklist',
-  'orchestration-state', 'orchestration-evidence'
-] as const;
-
-function isLocalVerificationCheck(value: string): value is typeof LOCAL_VERIFICATION_CHECKS[number] {
-  return (LOCAL_VERIFICATION_CHECKS as readonly string[]).includes(value);
-}
-
-export { LOCAL_VERIFICATION_CHECKS, isLocalVerificationCheck };

package/lib/task/workspace-snapshot.ts

@@ -1,144 +0,0 @@
-import { createHash } from 'node:crypto';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { resolveProjectTaskWorkspaceRoot } from './workspace-root.ts';
-
-function git(repoRoot: string, indexFile: string | null, args: string[]): string {
-  const env = indexFile ? { ...process.env, GIT_INDEX_FILE: indexFile } : process.env;
-  const result = spawnSync('git', args, { cwd: repoRoot, env, encoding: 'utf8' });
-  if (result.status !== 0) {
-    throw new Error(String(result.stderr || result.stdout || `git ${args[0]} failed`).trim());
-  }
-  return result.stdout;
-}
-
-type RepositorySnapshot = Readonly<{
-  head: string;
-  headTree: string;
-  worktreeTree: string;
-}>;
-
-type WorkspaceSnapshotContext = Readonly<{
-  gitRoot: string;
-  stateRoot: string;
-  taskId: string | null;
-}>;
-
-type TaskFileFingerprint = Readonly<{
-  path: string;
-  mode: number;
-  kind: 'file' | 'symlink';
-  sha256: string;
-}>;
-
-type OrchestrationWorkspaceFingerprint = Readonly<{
-  version: 2;
-  gitTree: string;
-  taskFiles: readonly TaskFileFingerprint[];
-}>;
-
-function captureWorktreeTree(repoRoot: string, forcedPath: string | null): string {
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-orchestration-index-'));
-  const indexFile = path.join(tempDir, 'index');
-  try {
-    try { git(repoRoot, indexFile, ['read-tree', 'HEAD']); }
-    catch { git(repoRoot, indexFile, ['read-tree', '--empty']); }
-    git(repoRoot, indexFile, ['add', '-A', '--', ':/']);
-    if (forcedPath && fs.existsSync(path.join(repoRoot, forcedPath))) {
-      git(repoRoot, indexFile, ['add', '-f', '--', forcedPath]);
-    }
-    return git(repoRoot, indexFile, ['write-tree']).trim();
-  } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true });
-  }
-}
-
-function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFileFingerprint[] {
-  const activeRoot = path.join(resolveProjectTaskWorkspaceRoot(stateRoot), 'active');
-  const roots = taskId ? [path.join(activeRoot, taskId)] : [activeRoot];
-  const records: TaskFileFingerprint[] = [];
-  const visit = (absolute: string, relative: string): void => {
-    const stat = fs.lstatSync(absolute);
-    if (stat.isDirectory()) {
-      for (const name of fs.readdirSync(absolute).sort()) {
-        visit(path.join(absolute, name), path.posix.join(relative, name));
-      }
-      return;
-    }
-    if (!stat.isFile() && !stat.isSymbolicLink()) return;
-    if (/^task-workspace\/(?:active|blocked|completed)\/TASK-[0-9]{8}-[0-9]{6}\/\.runtime\/orchestration\.json$/u.test(relative)) return;
-    const content = stat.isSymbolicLink()
-      ? Buffer.from(fs.readlinkSync(absolute))
-      : fs.readFileSync(absolute);
-    records.push({
-      path: relative,
-      mode: stat.mode & 0o777,
-      kind: stat.isSymbolicLink() ? 'symlink' : 'file',
-      sha256: createHash('sha256').update(content).digest('hex')
-    });
-  };
-  for (const root of roots) {
-    if (!fs.existsSync(root)) continue;
-    const relative = path.posix.join('task-workspace/active', path.relative(activeRoot, root).split(path.sep).join('/'));
-    visit(root, relative.replace(/\/$/, ''));
-  }
-  return records.sort((left, right) => left.path.localeCompare(right.path));
-}
-
-function encodeWorkspaceFingerprint(value: OrchestrationWorkspaceFingerprint): string {
-  return `ws2:${Buffer.from(JSON.stringify(value)).toString('base64url')}`;
-}
-
-function decodeWorkspaceFingerprint(value: string): OrchestrationWorkspaceFingerprint | null {
-  if (!value.startsWith('ws2:')) return null;
-  try {
-    const parsed = JSON.parse(Buffer.from(value.slice(4), 'base64url').toString('utf8')) as OrchestrationWorkspaceFingerprint;
-    if (parsed.version !== 2 || !/^[a-f0-9]{40,64}$/.test(parsed.gitTree) || !Array.isArray(parsed.taskFiles)) {
-      throw new Error('invalid workspace fingerprint fields');
-    }
-    return parsed;
-  } catch (error) {
-    throw new Error(`ORCHESTRATION_SNAPSHOT_FAILED: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-function captureWorkspaceSnapshot(context: WorkspaceSnapshotContext): string {
-  return encodeWorkspaceFingerprint({
-    version: 2,
-    gitTree: captureWorktreeTree(context.gitRoot, null),
-    taskFiles: taskFileFingerprints(context.stateRoot, context.taskId)
-  });
-}
-
-function captureRepositorySnapshot(repoRoot: string): RepositorySnapshot {
-  return {
-    head: git(repoRoot, null, ['rev-parse', 'HEAD']).trim(),
-    headTree: git(repoRoot, null, ['rev-parse', 'HEAD^{tree}']).trim(),
-    worktreeTree: captureWorktreeTree(repoRoot, null)
-  };
-}
-
-function diffWorkspaceSnapshots(repoRoot: string, before: string, after: string): string[] {
-  const beforeV2 = decodeWorkspaceFingerprint(before);
-  const afterV2 = decodeWorkspaceFingerprint(after);
-  if ((beforeV2 === null) !== (afterV2 === null)) {
-    throw new Error('ORCHESTRATION_SNAPSHOT_FAILED: workspace fingerprint versions cannot be mixed');
-  }
-  if (!beforeV2 || !afterV2) {
-    const output = git(repoRoot, null, ['diff', '--name-only', '-z', before, after]);
-    return output.split('\0').filter(Boolean);
-  }
-  const output = git(repoRoot, null, ['diff', '--name-only', '-z', beforeV2.gitTree, afterV2.gitTree]);
-  const changed = new Set(output.split('\0').filter(Boolean));
-  const beforeFiles = new Map(beforeV2.taskFiles.map((record) => [record.path, JSON.stringify(record)]));
-  const afterFiles = new Map(afterV2.taskFiles.map((record) => [record.path, JSON.stringify(record)]));
-  for (const filePath of new Set([...beforeFiles.keys(), ...afterFiles.keys()])) {
-    if (beforeFiles.get(filePath) !== afterFiles.get(filePath)) changed.add(filePath);
-  }
-  return [...changed].sort();
-}
-
-export { captureRepositorySnapshot, captureWorkspaceSnapshot, captureWorktreeTree, diffWorkspaceSnapshots };
-export type { OrchestrationWorkspaceFingerprint, RepositorySnapshot, WorkspaceSnapshotContext };

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -1,140 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-const MAX_INPUT_BYTES = 64 * 1024;
-const codexHooks = fileURLToPath(new URL('../../.codex/hooks.json', import.meta.url));
-const clientIndex = process.argv.indexOf('--client');
-const client = clientIndex >= 0 ? process.argv[clientIndex + 1] : '';
-if (client !== 'claude-code' && client !== 'codex') {
-  process.stderr.write('Lifecycle delegation hook requires a supported --client value\n');
-  process.exit(1);
-}
-
-function internalCliInvocation(args) {
-  return { command: 'agent-infra-internal', commandArgs: args, shell: process.platform === 'win32' };
-}
-
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => {
-  input += chunk;
-  if (Buffer.byteLength(input) > MAX_INPUT_BYTES) {
-    process.stderr.write('Lifecycle delegation hook input exceeds 64 KiB\n');
-    process.exit(1);
-  }
-});
-process.stdin.on('end', () => {
-  let event;
-  try {
-    event = JSON.parse(input || '{}');
-  } catch {
-    process.stderr.write('Lifecycle delegation hook received invalid JSON\n');
-    process.exit(1);
-  }
-  const phaseIndex = process.argv.indexOf('--event');
-  const explicitPhase = phaseIndex >= 0 ? process.argv[phaseIndex + 1] : '';
-  const hook = String(explicitPhase || event.hook_event_name || event.event || '').toLowerCase();
-  const toolInput = event.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
-  const toolName = String(event.tool_name || event.tool || '').toLowerCase();
-  let toolResponse = {};
-  try {
-    toolResponse = typeof event.tool_response === 'string'
-      ? JSON.parse(event.tool_response)
-      : (event.tool_response || {});
-  } catch {
-    // Core ignores opaque tool responses; only the host timeout bit is forwarded.
-  }
-  const nativeAgent = event.agent_name || event.agent_type || event.agent?.name
-    || toolInput.agent_type || toolInput.agent || toolInput.name;
-  if (client === 'codex') {
-    const phases = new Set(['pre-tool', 'subagent-start', 'post-tool', 'subagent-stop']);
-    if (!phases.has(hook)) {
-      process.stderr.write('Managed Codex lifecycle hook event has an unknown type\n');
-      process.exit(1);
-    }
-    const managedAgent = /^agent-infra-lifecycle-(executor|reviewer)$/.test(String(nativeAgent || ''));
-    const parentReconcile = hook === 'post-tool'
-      && toolName === 'collaborationwait_agent'
-      && toolResponse.timed_out !== true;
-    if (!managedAgent && !parentReconcile) process.exit(0);
-    const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
-    const normalized = {
-      sessionId: String(event.session_id || ''),
-      turnId: String(event.turn_id || ''),
-      toolUseId: String(event.tool_use_id || ''),
-      childThreadId: String(event.agent_id || event.child_id || event.thread_id || event.tool_response?.agent_id || ''),
-      nativeAgent: String(nativeAgent),
-      requestedModel: String(toolInput.model || ''),
-      requestedReasoningEffort: String(toolInput.reasoning_effort || toolInput.reasoningEffort || ''),
-      hookDefinitionHash,
-      toolName,
-      taskName: String(toolInput.task_name || ''),
-      transcriptPath: String(event.transcript_path || '')
-    };
-    const args = ['codex-lifecycle', 'hook-event', '--event', hook, '--bridge', 'true'];
-    try {
-      const { command, commandArgs, shell } = internalCliInvocation(args);
-      const output = execFileSync(command, commandArgs, {
-        encoding: 'utf8',
-        input: JSON.stringify(normalized),
-        shell,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        timeout: 30_000
-      });
-      process.stdout.write(output);
-    } catch (error) {
-      if (error.stdout) process.stdout.write(String(error.stdout));
-      if (error.stderr) process.stderr.write(String(error.stderr));
-      process.exit(typeof error.status === 'number' ? error.status : 1);
-    }
-    return;
-  }
-  if (!/^agent-infra-lifecycle-(executor|reviewer)$/.test(String(nativeAgent || ''))) process.exit(0);
-  const start = hook.includes('start');
-  const stop = hook.includes('stop');
-  if (!start && !stop) {
-    process.stderr.write('Managed lifecycle hook event has an unknown type\n');
-    process.exit(1);
-  }
-  const args = ['task-orchestration', 'auto', start ? 'hook-start' : 'hook-stop', '--client', client];
-  if (start) {
-    args.push(
-      '--native-agent', String(nativeAgent),
-      '--child-id', String(event.child_id || event.agent_id || event.thread_id || ''),
-      '--parent-id', String(event.parent_id || event.parent_session_id || event.session_id || '')
-    );
-    if (event.spawn_mode) args.push('--spawn-mode', String(event.spawn_mode));
-    if (event.model) args.push('--actual-model', String(event.model));
-    const actualEffort = event.effort?.level || event.actual_reasoning_effort || event.reasoning_effort || event.model_reasoning_effort;
-    if (actualEffort) args.push('--actual-reasoning-effort', String(actualEffort));
-    if (event.model_fallback_reason) args.push('--model-fallback-reason', String(event.model_fallback_reason));
-    if (event.reasoning_effort_fallback_reason) {
-      args.push('--reasoning-effort-fallback-reason', String(event.reasoning_effort_fallback_reason));
-    }
-  } else {
-    args.push(
-      '--native-agent', String(nativeAgent),
-      '--child-id', String(event.child_id || event.agent_id || event.thread_id || '')
-    );
-    if (client === 'claude-code') {
-      if (event.model) args.push('--actual-model', String(event.model));
-      const actualEffort = event.effort?.level || event.actual_reasoning_effort || event.reasoning_effort;
-      if (actualEffort) args.push('--actual-reasoning-effort', String(actualEffort));
-    }
-  }
-  try {
-    const { command, commandArgs, shell } = internalCliInvocation(args);
-    const output = execFileSync(command, commandArgs, {
-      encoding: 'utf8',
-      shell,
-      stdio: ['ignore', 'pipe', 'pipe']
-    });
-    process.stdout.write(output);
-  } catch (error) {
-    if (error.stdout) process.stdout.write(String(error.stdout));
-    if (error.stderr) process.stderr.write(String(error.stderr));
-    process.exit(typeof error.status === 'number' ? error.status : 1);
-  }
-});

package/templates/.agents/rules/lifecycle-orchestration.en.md

@@ -1,44 +0,0 @@
-# Common Rule - Lifecycle Orchestration
-
-## Guarantee Boundary
-
-- The orchestrator only routes and delegates. Stage skills remain the single source of truth for behavior and artifacts.
-- Every stage and rework round uses a fresh executor. Every review uses a fresh reviewer; follow-up reuse is forbidden.
-- A reviewer may only write its review artifact and core-generated task metadata. Business-code, HEAD, or index changes invalidate the receipt.
-- An active run has one pending delegation. Keep the stage associated with the observed child and report actual start and terminal failures.
-- The first release ends after one existing safely gated `commit`; it does not create a PR, monitor checks, or complete the task.
-
-## Current Execution Records
-
-`orchestration.json` records stages, model policy, child identity, and actual outcomes. Records use the current structure; trusted local operators may correct them and rerun validation. Stages for one task run sequentially; atomic writes and identity/state validation continue to protect state updates.
-
-## Current Host
-
-- Use native spawn, wait, and App Server results from the current host. A task-bound sandbox executes ordinary task orchestration locally in the current worktree.
-- Prepare validates the current task, model policy, and host preflight. Start and terminal records associate observed parent/child identity; failure must not be recorded as success.
-- Client-specific preflight, event sources, and stop-evidence validation belong to the client adapter. The common orchestrator calls only the shared capability and contains no client-ID branches.
-
-## Activated Delegation Recovery
-
-- Before `begin-or-resume`, the orchestrator calls internal `task-lifecycle <task> recover-started --agent <client> --auto`. This entry is not user-facing and never infers child termination from missing liveness evidence.
-- The client adapter declares recovery support and validates trusted stop evidence for the current pending delegation. Unsupported adapters and runs without an activated pending delegation return `no-op`; uncertain termination fails closed.
-- Recovery consumes stop evidence, saves an aborted receipt while clearing pending, then appends the Activity Log terminal row. If the run save succeeds and the log write fails, the next invocation appends only the missing row.
-- Routing continues only after `no-op` or `applied`. Lost control responses are not reconstructed; the next operator invocation relies on the idempotent persisted state.
-
-## Current-only Cutover and Rollback
-
-- Enter a quiet window before cutover: let in-flight orchestration intents return and preserve the worktree, task/run/orchestration state, receipts, and audit. For an unknown result, inspect local `status`/`route` before using existing recover/advance semantics; do not replay an old broker request.
-- Deploy or roll back the CLI, broker, and protocol as one versioned unit. After stopping the old container/broker, rebuild and run `ai sandbox start --recreate <task-ref>` to resume with a new control generation; never reuse an old token or request.
-- On either the new or rolled-back version, first confirm the same task through `status`/`route`. Keep the quiet window and evidence intact if any check fails; do not mix component versions or rewrite domain facts.
-
-## Model Policy
-
-- A new run persists model and reasoning effort for both roles. Explicit policy is atomic across all four role fields; only a fully absent explicit policy may fall back to the current client's `agentClients[].orchestration`.
-- Route resolves requested model/effort by role, and prepare matches both before snapshotting. Native spawn must not inherit session defaults.
-- Native start records host-observed actual model/effort. Fields declared unobservable by the adapter follow the recording rules; each observable mismatch needs its own fallback reason, and requested values must never be fabricated as actual evidence.
-- Model selection is labeled as a complete catalog, partial catalog, or interactive-only guidance; a local override enum must not be presented as complete.
-- An adapter must declare any policy field it cannot dispatch per role. Values observed in host events are actual evidence only; they do not promise dispatch or gate activation.
-
-## Stable Pause Conditions
-
-Human decisions, manual validation, handshake or step limits, permissions/network failures, worktree conflicts, unsupported client capability, and unknown hook schemas are persisted as pauses. The orchestrator must not ask mid-flow or degrade to same-context self-review.

package/templates/.agents/rules/lifecycle-orchestration.zh-CN.md

@@ -1,44 +0,0 @@
-# 通用规则 - 生命周期总控
-
-## 保证边界
-
-- 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
-- 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
-- reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
-- active run 中只有一个 pending delegation；阶段与实际 child 身份保持一致，启动和终态失败如实记录。
-- 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
-
-## 当前执行记录
-
-`orchestration.json` 记录阶段、模型策略、child 身份及实际执行结果。记录必须符合当前结构；本地操作者可直接修正后重新校验。同一任务的阶段按序调用；原子写入、身份校验和状态校验继续保护状态更新。
-
-## 当前宿主
-
-- 使用当前宿主的原生 spawn、wait 与 App Server 结果；task-bound sandbox 在当前 worktree 本地执行普通任务编排。
-- prepare 校验当前任务、模型策略与宿主 preflight。启动和完成记录关联实际 parent/child 身份，失败不得写成成功。
-- 客户端特有的 preflight、事件来源与停止证据校验由客户端适配器实现；公共总控只调用统一能力。不得在公共流程中新增客户端 ID 分支。
-
-## Activated delegation 自动恢复
-
-- 总控在 `begin-or-resume` 前调用内部 `task-lifecycle <task> recover-started --agent <client> --auto`。该入口不公开给用户，也不从缺少存活证据推断 child 已终止。
-- 客户端适配器决定是否支持恢复，并验证当前 pending delegation 的可信停止证据；不支持或没有 activated pending 时返回 `no-op`，无法确认停止时失败关闭。
-- 恢复按固定顺序消费停止证据、保存 aborted receipt 并清除 pending，再写 Activity Log 结束记录。任务状态已保存而日志未写时，下次调用只补日志。
-- 只有 `no-op` 或 `applied` 才能继续 route。控制响应丢失时不重建恢复结果；下一次人为调用依靠幂等状态继续。
-
-## Current-only 切换与回滚
-
-- 切换前进入静默窗口：等待在途编排 intent 返回，并保留 worktree、task/run/orchestration 状态、receipts 与 audit。结果未知时先用本地 `status`/`route` 判断 domain 是否已提交，再按现有 recover/advance 语义处理；不重放旧 broker request。
-- CLI、broker 与协议必须作为同一版本单元部署或回退。停止旧 container/broker 后执行 rebuild 与 `ai sandbox start --recreate <task-ref>`，以新的 control generation 恢复执行；旧 token 和 request 不得复用。
-- 新版本或回滚版本都必须先核对同一任务的 `status`/`route`。任一检查失败时继续保持静默并保留证据，不局部混用组件或改写 domain 事实。
-
-## 模型策略
-
-- 新 run 必须固化 executor/reviewer 各自的 model 与 reasoning effort；显式策略必须四字段原子完整，完全没有显式字段时才读取当前 client 的 `agentClients[].orchestration`。重入不得静默改写策略。
-- route 按 role 返回 requested model/effort，prepare 必须在工作区快照前精确匹配两者；原生 spawn 不能继承会话默认值。
-- 原生 start 必须记录宿主观察到的 actual model/effort。适配器声明无法观察的字段按记录规则处理；任一可观察字段与 requested 不同时必须记录独立 fallback reason，requested 值不得补造 actual 证据。
-- 模型选择能力必须标记 complete catalog、partial catalog 或 interactive-only guidance；局部 override 枚举不得冒充完整目录。
-- 客户端无法按角色下发的策略字段必须由适配器明确声明；宿主事件中观察到的值只作为实际证据，不构成下发承诺或放行门禁。
-
-## 稳定暂停条件
-
-人工裁决、人工验证、握手或总步骤上限、权限/网络失败、用户工作区冲突、客户端 capability 不支持及未知 hook schema 都持久化为暂停原因。总控不得中途询问或降级为同上下文自审。

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

@@ -1,29 +0,0 @@
----
-name: run-task
-description: >
-  Orchestrate lifecycle stages from the task's current state with fresh executors/reviewers and recorded execution results.
-  Use when one entry should advance an existing task until a safe commit or stable pause.
----
-
-# 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.
-2. Use the current host's native child spawn, wait, and result interfaces. Task-bound sandboxes execute ordinary task orchestration locally in the current worktree. Retain task binding and checks for real external process operations.
-3. Before each loop, run `agent-infra-internal task-lifecycle {task-id} recover-started --agent {client} --auto`. The client adapter owns recovery capability and stop-evidence validation; an unsupported adapter or a run that needs no recovery returns `no-op`. Continue only after `no-op` or `applied`. Stop on every other result; a later operator invocation retries from persisted state without routing or dispatching a child.
-4. 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.
-5. Run `route`. On `completed`, run `agent-infra-internal task-verify {task-id} run-task.completed --format text`, present its summary per `.agents/rules/validation-output.md` while retaining necessary diagnostics, and stop. Only a `running` result with non-null `next` supplies action, role, round, artifact, requested model, and requested effort.
-6. Call `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}` with route's exact policy. The client adapter runs host preflight. Report actual task, policy, or host failures.
-7. After prepare, forward the optional `adapterContext` unchanged to `agent-infra-internal agent-client launch-carrier --client {client} --adapter-context {adapterContext} --stage {stage} --round {round} --role {role} --format json`. The shared skill must not parse, rewrite, or validate this opaque value. The controlled entry point calls the current Agent Client adapter's `createLaunchCarrier` and returns a carrier for native spawn. Stop dispatch with the structured error if carrier support is unavailable or conversion fails. Then run `task-orchestration <task-ref> dispatch` with route's exact model/effort, passing the short task ref, skill, `--orchestrated`, stage/round/artifact/role, and the returned carrier unchanged to native spawn. The child calls `await-activation --stage ... --round ... --artifact ... --role ...` to associate its actual identity before executing. Code-task creates the local checkpoint; do not delegate a separate commit stage or push. Execute task stages sequentially; state updates retain atomic writes and identity/state validation.
-8. Record actual start and terminal results through the current host's native lifecycle events and result interfaces. A timed-out wait does not imply success. Pause on actual identity, transport, or terminal failures. After the stage and child finish, call `advance`; repeat step 3 only while running.
-9. Create a fresh child each round and never reuse a reviewer. Record actual model/effort and host fallback reasons. Validate current identity, artifacts, ledger, and execution results. User rulings override derived historical plan requirements. Do not introduce child discovery, orphan recovery, or a dedicated recovery protocol.
-10. On pause or completion, run the matching typed verification and report the structured endpoint.
-
-## Stop
-
-Stop after a safe `commit` or reviewed-head-clean endpoint; do not create a PR, monitor checks, or archive the task.

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

@@ -1,29 +0,0 @@
----
-name: run-task
-description: >
-  从任务当前状态持续编排生命周期阶段，使用 fresh executor/reviewer 并记录实际执行结果。
-  当用户希望通过单一入口推进已有任务直到安全提交或稳定暂停时使用。
----
-
-# 运行任务生命周期
-
-## 任务上下文解析
-
-入口可省略 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 字段必须完整，不得与配置拼接；两个角色可以使用同一模型。
-2. 使用当前宿主的原生子 Agent 启动、等待与结果接口。task-bound sandbox 在当前 worktree 本地执行普通任务编排。保留任务绑定与真实外部进程操作检查。
-3. 每次进入循环时先调用 `agent-infra-internal task-lifecycle {task-id} recover-started --agent {client} --auto`。客户端适配器负责恢复能力和停止证据校验；没有该能力或无需恢复时返回 `no-op`。仅在结构化结果为 `no-op` 或 `applied` 时继续，其他结果安全停止；下一次人为调用按持久化状态幂等重试，不 route、不派发 child。
-4. 调用 `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，按结构化结果停止。
-5. 调用 `route` 并读取结构化结果。若返回 `completed`，立即运行 `agent-infra-internal task-verify {task-id} run-task.completed --format text` 并停止；按 `.agents/rules/validation-output.md` 展示摘要并保留必要诊断。仅当返回 `running` 且 `next` 非空时读取唯一 action、role、round、artifact、`requestedModel` 和 `requestedReasoningEffort`，不得自行推断。
-6. 调用 `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}`，使用 route 返回的精确策略。客户端适配器执行宿主 preflight；任务身份、策略或宿主检查失败时记录实际诊断。
-7. prepare 成功后，原样转发返回的可选 `adapterContext`，调用 `agent-infra-internal agent-client launch-carrier --client {client} --adapter-context {adapterContext} --stage {stage} --round {round} --role {role} --format json`。共享技能不解析、重写或验证该不透明值；受控入口调用当前 Agent Client adapter 的 `createLaunchCarrier`，并返回可直接交给 native spawn 的 carrier。缺少 carrier 能力或转换失败时按结构化错误停止派发。随后执行 `task-orchestration <task-ref> dispatch`，显式指定 route 返回的 model/effort；传递短任务引用、skill 名、`--orchestrated` 与 stage/round/artifact/role，并把返回的 carrier 原样交给 native spawn。child 调用 `await-activation --stage ... --round ... --artifact ... --role ...`，确认当前阶段与实际 child 关联后执行。代码阶段通过 code-task 创建本地 checkpoint；禁止单独委派 commit 阶段或推送。任务阶段按序执行，状态更新保留原子写入与身份、状态校验。
-8. 通过当前宿主的原生生命周期事件和结果接口记录实际启动及终态。timed-out wait 不推断成功；身份、传输或异常终态失败如实暂停。阶段结果和 child 完成后调用 `advance`；只有 `running` 才重复步骤 3。
-9. 每轮创建新 child；禁止 follow-up 复用 reviewer。如实记录 actual model/effort 及宿主降级理由。检查当前身份、产物、账本与实际执行结果；用户裁决优先于历史方案派生要求。不得新增 child discovery、孤立 child 恢复或专用恢复协议。
-10. 完成或暂停后运行对应 typed verification，并把结构化 run 摘要、暂停原因、commit 终点或 clean completion evidence 告知用户。
-
-## 停止
-
-在安全 `commit` 或 reviewed-head-clean 终点后结束；不要继续创建 PR、监控 checks 或归档任务。

package/templates/.agents/skills/run-task/config/verify.en.json

@@ -1,10 +0,0 @@
-{
-  "skill": "run-task",
-  "checks": {
-    "task-meta": {
-      "required_fields": ["id", "status", "updated_at", "agent_infra_version", "current_step", "assigned_to"]
-    },
-    "orchestration-state": {},
-    "orchestration-evidence": {}
-  }
-}

package/templates/.agents/skills/run-task/config/verify.zh-CN.json

@@ -1,10 +0,0 @@
-{
-  "skill": "run-task",
-  "checks": {
-    "task-meta": {
-      "required_fields": ["id", "status", "updated_at", "agent_infra_version", "current_step", "assigned_to"]
-    },
-    "orchestration-state": {},
-    "orchestration-evidence": {}
-  }
-}

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

@@ -1,24 +0,0 @@
-# Host Contract Validation
-
-Before publishing support for a client, prove the lifecycle evidence chain with real host events. Bridge tests prove field mapping only; they do not prove host provenance.
-
-## Required Evidence
-
-- Client version, enabled multi-agent capability, launch surface, and trust boundary.
-- 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.
-  > Direct-host clients that structurally do not emit fork/spawn-mode event fields (currently claude-code) may derive identity correlation solely from parent/child identity uniqueness plus the receipt's one-shot state machine, without an additional fresh-spawn-mode proof; the client must still honestly record this gap and how the substitute guarantee is composed, and must never fabricate spawn-mode evidence. This exception does not apply to any other client. Concretely, claude-code's identity guarantee is provided only by non-empty and mutually distinct `parentId`/`childId`, a unique `childId` within the same run, and the receipt's one-shot state machine — it carries none of Codex's `spawn_mode` fork proof and is weaker than Codex's.
-- Explicit requested model/effort reaches each executor/reviewer. A fallback of either field reports the corresponding actual value and its own non-empty reason.
-  > claude-code exception: requested reasoning effort does not yet support per-role dispatch to executor/reviewer — `.claude/agents/{executor,reviewer}.md` is a repository-level shared singleton, and writing it per role would race across concurrent tasks. This client only needs to honestly record the actual model/actual reasoning effort observed in native Start/Stop host events (`delegationEvidence.actualReasoningEffort` is declared `spawn-ack`); when not observed it is recorded as missing, which is not treated as a fallback requiring its own reason and does not fail closed. This exception does not apply to any other client.
-- Candidate-checkout and packed-install behavior match, with model policy, receipts, and verification results auditable in `orchestration.json`.
-- Use the hooks/profiles actually loaded by the current host and verify observed parent/child identity and terminal results. Prepare does not depend on historical capability or controller attestation.
-
-## 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. 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. Confirm package/build/contract or hook/profile content drift produces only an actionable warning telling the user to rebuild the sandbox.
-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. 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 record verifiable execution results. The fallback may wait only for empty turns or protocol `inProgress`; malformed, identity/transport errors, or abnormal terminals pause deterministically. The claude-code exception above is already scoped in the second bullet and does not change this rule's fail-closed requirement for any other field or client.

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

@@ -1,24 +0,0 @@
-# 宿主契约验证
-
-发布支持某个客户端前，必须用真实宿主事件证明生命周期证据链；bridge 单测只证明字段映射，不能证明事件来自宿主。
-
-## 必须证明的字段
-
-- 客户端版本、启用的多代理能力、启动入口与信任边界。
-- 原始 start/stop 事件，或 custom role 缺少它们时的 parent PostTool spawn/completed-wait fallback，能稳定关联 managed agent、parent/child identity、fresh spawn mode、actual model 和 actual reasoning effort。
-  > 结构上不提供 fork/spawn-mode 事件字段的 direct-host 客户端（当前为 claude-code），身份关联允许仅由 parent/child identity 的唯一性与一次性状态机提供，不要求额外的 fresh spawn mode 证明；该客户端仍需如实记录这一缺口与替代保证的构成，不得补造 spawn mode 证据。此例外不适用于其他客户端。具体而言，claude-code 的身份保证仅由 `parentId`/`childId` 非空且互不相等、同一 run 内 `childId` 唯一、receipt 一次性状态机三者提供，不含 codex 式的 `spawn_mode` fork 证明，强度弱于 codex。
-- 显式 requested model/effort 能传给 executor/reviewer；宿主对任一字段回退时，事件能给出对应 actual 值与独立的非空 fallback reason。
-  > claude-code 例外：requested reasoning effort 暂不支持按角色下发给 executor/reviewer——`.claude/agents/{executor,reviewer}.md` 是仓库级共享单例，动态写入存在跨任务竞态，解决该竞态超出本任务范围。该客户端只要求如实记录宿主原生 Start/Stop 事件中能观察到的 actual model/actual reasoning effort（`delegationEvidence.actualReasoningEffort` 声明为 `spawn-ack`）；观察不到时记录为缺失，不视为需要独立 fallback reason 的回退场景，也不构成 fail-closed 阻断。此例外不适用于其他客户端。
-- candidate checkout 与打包安装后的行为一致，且模型策略、receipt 与验证结果可从 `orchestration.json` 复核。
-- 使用当前宿主实际加载的 hook/profile，并核对实际 parent/child 身份与终态；prepare 不依赖历史 capability 或 controller attestation。
-
-## 验证顺序
-
-1. 在干净临时仓库记录客户端版本、feature 状态和启动命令。
-2. 分别启动 fresh executor 与 fresh reviewer，保存去敏后的原始 stdin 和结构化 run；同时验证原生 start/stop 与 parent PostTool fallback。timed-out wait 必须无动作；不得补写宿主未产生的字段。
-3. 分别验证 model/effort 的 requested/actual 一致路径、单项与双项有理由 fallback 路径，并确认缺 actual 字段会失败关闭；对 package/build/contract 或 hook/profile 内容漂移确认只产生可操作 warning，并提示用户重建 sandbox。
-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`，并把缺口记录为人工验证项。Codex 可声明为 `experimental`，但每次 `prepare` 仍必须通过静态 preflight，且原生 start/stop 或 parent spawn/completed-wait fallback 必须记录可核对的实际执行结果。fallback 只允许 empty turns/协议 `inProgress` 等待；malformed、身份/传输错误或异常 terminal 都稳定暂停。上述关于 claude-code 的例外已在第 2 条单独说明，不改变本条对其余字段/客户端的 fail-closed 要求。

package/templates/.claude/agents/agent-infra-lifecycle-executor.en.md

@@ -1,6 +0,0 @@
----
-name: agent-infra-lifecycle-executor
-description: Execute exactly one agent-infra lifecycle stage in a fresh context.
----
-
-Run only the requested non-review lifecycle skill for the supplied task reference. Do not run any `review-*` skill. Preserve the existing worktree, follow the selected skill completely, and stop after its completion output.

package/templates/.claude/agents/agent-infra-lifecycle-executor.zh-CN.md

@@ -1,6 +0,0 @@
----
-name: agent-infra-lifecycle-executor
-description: 在全新上下文中只执行一个 agent-infra 生命周期阶段。
----
-
-只为给定任务引用运行指定的非审查生命周期技能。不得运行任何 `review-*` 技能。保留现有工作树，完整遵循所选技能，并在该技能完成输出后停止。

package/templates/.claude/agents/agent-infra-lifecycle-reviewer.en.md

@@ -1,6 +0,0 @@
----
-name: agent-infra-lifecycle-reviewer
-description: Review exactly one agent-infra lifecycle artifact in a fresh isolated context.
----
-
-Run only the requested `review-*` skill for the supplied task reference. Do not modify business code, do not execute implementation skills, and stop after producing and finalizing the review artifact.

package/templates/.claude/agents/agent-infra-lifecycle-reviewer.zh-CN.md

@@ -1,6 +0,0 @@
----
-name: agent-infra-lifecycle-reviewer
-description: 在全新隔离上下文中只审查一个 agent-infra 生命周期产物。
----
-
-只为给定任务引用运行指定的 `review-*` 技能。不得修改业务代码，不得执行实现技能，并在生成和最终化审查产物后停止。

package/templates/.claude/commands/run-task.en.md

@@ -1,8 +0,0 @@
----
-description: "Orchestrate a task lifecycle with fresh isolated agents"
-usage: "/run-task [--task <ref> | -t <ref>] [--executor-model <model> --executor-reasoning-effort <effort> --reviewer-model <model> --reviewer-reasoning-effort <effort>]"
----
-
-Read and execute the run-task skill from `.agents/skills/run-task/SKILL.md`.
-
-Follow all steps defined in the skill exactly.

package/templates/.claude/commands/run-task.zh-CN.md

@@ -1,8 +0,0 @@
----
-description: "使用 fresh 隔离 Agent 总控任务生命周期"
-usage: "/run-task [--task <ref> | -t <ref>] [--executor-model <model> --executor-reasoning-effort <effort> --reviewer-model <model> --reviewer-reasoning-effort <effort>]"
----
-
-读取并执行 `.agents/skills/run-task/SKILL.md` 中的 run-task 技能。
-
-严格按照技能中定义的所有步骤执行。

package/templates/.codex/agents/agent-infra-lifecycle-executor.en.toml

@@ -1,3 +0,0 @@
-name = "agent-infra-lifecycle-executor"
-description = "Execute exactly one agent-infra lifecycle stage in a fresh thread."
-developer_instructions = "Run only the requested non-review lifecycle skill for the supplied task reference. Never run review-* skills. Stop after the stage completes."

package/templates/.codex/agents/agent-infra-lifecycle-executor.zh-CN.toml

@@ -1,3 +0,0 @@
-name = "agent-infra-lifecycle-executor"
-description = "在全新线程中只执行一个 agent-infra 生命周期阶段。"
-developer_instructions = "只为给定任务引用运行指定的非审查生命周期技能。不得运行 review-* 技能。阶段完成后停止。"

package/templates/.codex/agents/agent-infra-lifecycle-reviewer.en.toml

@@ -1,3 +0,0 @@
-name = "agent-infra-lifecycle-reviewer"
-description = "Review exactly one lifecycle artifact in a fresh isolated thread."
-developer_instructions = "Run only the requested review-* skill. Never modify business code or execute implementation skills. Stop after the review artifact is finalized."

package/templates/.codex/agents/agent-infra-lifecycle-reviewer.zh-CN.toml

@@ -1,3 +0,0 @@
-name = "agent-infra-lifecycle-reviewer"
-description = "在全新隔离线程中只审查一个生命周期产物。"
-developer_instructions = "只运行指定的 review-* 技能。不得修改业务代码或执行实现技能。审查产物最终化后停止。"

package/templates/.opencode/commands/run-task.en.md

@@ -1,11 +0,0 @@
----
-description: "Orchestrate a task lifecycle with fresh isolated agents"
-agent: general
-subtask: false
----
-
-Run task lifecycle $ARGUMENTS.
-
-Read and execute the run-task skill from `.agents/skills/run-task/SKILL.md`.
-
-Follow all steps defined in the skill exactly.