@fitlab-ai/agent-infra 0.11.1 → 0.11.3

package/lib/task/review-finalization.ts

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 
 import { parseArtifactName } from './artifact-name.ts';
-import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.ts';
+import { validateCompletedArtifact, validateArtifactPublication } from './artifact-lifecycle.ts';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { LedgerStageStatus, ReviewStage } from './ledger.ts';
 import { finalizeReviewSummaryContent } from './review-artifacts.ts';
@@ -15,17 +17,6 @@ import type { ManualOverrideCapability } from './guard-override.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.ts';
 import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.ts';
-import { readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
-import {
-  beginArtifactRecovery,
-  commitArtifactRecovery,
-  prepareArtifactRecoveryFinal,
-  prepareArtifactRecoveryCommit,
-  reconcileArtifactRecovery,
-  recoveryContextFromIntent,
-  stageArtifactCandidate
-} from './artifact-recovery.ts';
-import type { ArtifactRecoveryContext } from './artifact-recovery.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -51,7 +42,6 @@ type ReviewFinalizationRequest = {
   artifact: string;
   orchestrated?: boolean;
   dryRun?: boolean;
-  recoveryId?: string;
 };
 type ReviewFinalizationResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed';
@@ -64,12 +54,6 @@ type ReviewFinalizationResult = {
   stageStatus: LedgerStageStatus | null;
   artifactSha256: string | null;
   semanticDigest: string | null;
-  recovery?: Readonly<{
-    recoveryId: string;
-    candidatePath: string;
-    baselineSha256: string;
-    baselineSemanticDigest: string;
-  }>;
   operations: readonly {
     kind: 'artifact';
     artifact: string;
@@ -90,7 +74,6 @@ type ReviewFinalizationOptions = {
   fileSystem?: Partial<ReviewFileSystem>;
   manualOverride?: ManualOverrideCapability;
   lockAlreadyHeld?: boolean;
-  startRecovery?: boolean;
 };
 
 const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code' }> = {
@@ -143,7 +126,7 @@ function preflightFailed(
   };
 }
 
-/** Validate and seal a review draft before any finding-ledger write. */
+/** Validate the current review draft before any finding-ledger write. */
 function preflightReviewSummaryUnlocked(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
@@ -162,28 +145,13 @@ function preflightReviewSummaryUnlocked(
 
   let taskContent: string;
   let content: string;
-  let recovery: ArtifactRecoveryContext | undefined;
   try {
     taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    if (request.recoveryId) {
-      const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
-      if (!intent || intent.recoveryOperationId !== request.recoveryId) return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal', resolved.taskId);
-      if (!['awaiting-preflight-recovery', 'preflight-ready'].includes(intent.state)) return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`, resolved.taskId);
-      recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
-      content = fs.existsSync(recovery.stagingPath)
-        ? fs.readFileSync(recovery.stagingPath, 'utf8')
-        : fs.readFileSync(recovery.formalPath, 'utf8');
-    } else {
-      const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
-      if (!validated.ok) return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
-      content = fs.readFileSync(validated.artifact.path, 'utf8');
-      const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
-      if (intent?.state === 'preflight-ready') recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
-      if (intent?.state === 'consumed') return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'review artifact was already finalized', resolved.taskId);
-    }
+    const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
+    if (!validated.ok) return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
+    content = fs.readFileSync(validated.artifact.path, 'utf8');
   } catch (error) { return preflightFailed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId); }
 
-  if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`, resolved.taskId);
   const execution = validateLifecycleExecution(request.taskRef, {
     mode: request.orchestrated ? 'orchestrated' : 'standalone',
     identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
@@ -204,14 +172,6 @@ function preflightReviewSummaryUnlocked(
   });
   const qualificationError = qualification.ok ? null : qualification;
   if (!detail.ok || !structure.ok || qualificationError) {
-    if (!recovery && !request.dryRun) {
-      try {
-        recovery = beginArtifactRecovery({
-          taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-          requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
-        }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-      } catch (error) { return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId); }
-    }
     const diagnostics = [
       ...(!detail.ok ? [`${detail.code}: ${detail.message}`] : []),
       ...structure.diagnostics.map((item) => `${item.code}: ${item.message}`),
@@ -219,27 +179,18 @@ function preflightReviewSummaryUnlocked(
     ].join('; ');
     return preflightFailed(request, !detail.ok ? 'REVIEW_DECISION_DETAIL_INVALID' : !structure.ok ? 'REVIEW_ARTIFACT_STRUCTURE_INVALID' : 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', diagnostics, resolved.taskId, {
       artifactSha256, semanticDigest,
-      ...(recovery ? { recovery: recoveryInfo(recovery) } : {})
     });
   }
-  if (request.dryRun || recovery && readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact)?.state === 'preflight-ready') {
+  if (request.dryRun) {
     return {
-      ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, ...(recovery ? { recovery: recoveryInfo(recovery) } : {}) }),
+      ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
       status: 'passed', changed: false, error: null
     };
   }
-  try {
-    recovery ??= beginArtifactRecovery({
-      taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-      requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
-    }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-    const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: options.lockAlreadyHeld });
-    prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: options.lockAlreadyHeld });
-    return {
-      ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, recovery: recoveryInfo(recovery) }),
-      status: 'passed', changed: false, error: null
-    };
-  } catch (error) { return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, { artifactSha256, semanticDigest }); }
+  return {
+    ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
+    status: 'passed', changed: false, error: null
+  };
 }
 
 function preflightReviewSummary(
@@ -265,19 +216,9 @@ function preflightReviewSummary(
 type ReviewSummaryCandidatePreparation = Readonly<{
   result: ReviewFinalizationResult;
   content: string;
-  recovery?: ArtifactRecoveryContext;
   lockAlreadyHeld?: boolean;
 }>;
 
-function recoveryInfo(recovery: ArtifactRecoveryContext): NonNullable<ReviewFinalizationResult['recovery']> {
-  return {
-    recoveryId: recovery.recoveryId,
-    candidatePath: recovery.stagingPath,
-    baselineSha256: recovery.baselineSha256,
-    baselineSemanticDigest: recovery.baselineSemanticDigest
-  };
-}
-
 /** Prepare domain validation, summary bytes and provenance before any publication. */
 function prepareReviewSummaryCandidate(
   request: ReviewFinalizationRequest,
@@ -306,36 +247,9 @@ function prepareReviewSummaryCandidate(
   let taskContent: string;
   try { taskContent = (options.fileSystem?.readFileSync ?? DEFAULT_FILE_SYSTEM.readFileSync)(resolved.taskMdPath); }
   catch (error) { return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error)); }
-  let recovery: ArtifactRecoveryContext | undefined;
-  if (request.recoveryId) {
-    try {
-      const intent = readArtifactRecoveryIntent(resolved.repoRoot, taskId!, spec.family, request.artifact);
-      if (!intent || intent.recoveryOperationId !== request.recoveryId) return reject('REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal');
-      if (!['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started'].includes(intent.state)) return reject('REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`);
-      recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
-      artifactContent = fs.existsSync(recovery.stagingPath)
-        ? fs.readFileSync(recovery.stagingPath, 'utf8')
-        : fs.readFileSync(recovery.formalPath, 'utf8');
-    } catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error)); }
-  }
   const artifactSha256 = sha256Content(artifactContent);
   const semanticDigest = canonicalSemanticDigest(artifactContent);
   const digests = { artifactSha256, semanticDigest };
-  let repairIntent;
-  try { repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId!, spec.family, request.artifact); }
-  catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), digests); }
-  if (repairIntent?.state === 'consumed') {
-    if (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest) {
-      return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
-    }
-  }
-  if (repairIntent?.state === 'passed'
-    && (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest)) {
-    repairIntent = undefined;
-  }
-  if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
-    return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
-  }
   const execution = validateLifecycleExecution(request.taskRef, {
     mode: request.orchestrated ? 'orchestrated' : 'standalone',
     identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
@@ -356,59 +270,15 @@ function prepareReviewSummaryCandidate(
   const schema = getArtifactSchema(spec.family)!;
   const structure = inspectArtifactContract(artifactContent, schema);
   if (!structure.ok) {
-    if (!recovery && !request.dryRun && options.startRecovery) {
-      try {
-        recovery = beginArtifactRecovery({
-          taskId: taskId!, family: spec.family, artifact: request.artifact, round: parsed.round,
-          requestId: `review-finalize:${taskId!}:${stage}:${parsed.round}`
-        }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-      } catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), digests); }
-    }
-    return {
-      ...reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
-        artifactSha256, semanticDigest: structure.semanticDigest,
-        ...(recovery ? { recovery: {
-          recoveryId: recovery.recoveryId,
-          candidatePath: recovery.stagingPath,
-          baselineSha256: recovery.baselineSha256,
-          baselineSemanticDigest: recovery.baselineSemanticDigest
-        } } : {})
-      }),
-      ...(recovery ? { recovery } : {})
-    };
+    return reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
+      artifactSha256, semanticDigest: structure.semanticDigest
+    });
   }
   const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts, {
-    refreshNumericCounts: Boolean(request.recoveryId && recovery)
+    refreshNumericCounts: true
   });
   if (!transformed.ok) return reject(transformed.code, transformed.message);
   const finalDigests = { artifactSha256: sha256Content(transformed.content), semanticDigest: canonicalSemanticDigest(transformed.content) };
-  if (!recovery && repairIntent?.state === 'commit-started') {
-    if (repairIntent.finalArtifactSha256 !== finalDigests.artifactSha256 || repairIntent.finalSemanticDigest !== finalDigests.semanticDigest) {
-      return reject('REVIEW_PROVENANCE_INVALID', 'formal review artifact does not match the interrupted recovery journal', finalDigests);
-    }
-    recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, repairIntent);
-  }
-  if (!recovery && (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')) {
-    if (transformed.changed) return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact requires changes after its completed recovery was consumed', finalDigests);
-    return {
-      content: transformed.content,
-      result: {
-        ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', taskId, stageStatus, finalDigests),
-        status: 'no-op',
-        changed: false,
-        error: null
-      },
-      lockAlreadyHeld: options.lockAlreadyHeld
-    };
-  }
-  if (!recovery && !request.dryRun && options.startRecovery) {
-    try {
-      recovery = beginArtifactRecovery({
-        taskId: taskId!, family: spec.family, artifact: request.artifact, round: parsed.round,
-        requestId: `review-finalize:${taskId!}:${stage}:${parsed.round}`
-      }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-    } catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), finalDigests); }
-  }
   return {
     content: transformed.content,
     result: {
@@ -418,7 +288,6 @@ function prepareReviewSummaryCandidate(
       operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
       error: null
     },
-    ...(recovery ? { recovery } : {}),
     lockAlreadyHeld: options.lockAlreadyHeld
   };
 }
@@ -428,51 +297,18 @@ function commitReviewSummaryProvenance(
   repoRoot: string,
   options: Readonly<{ afterPublish?: () => void }> = {}
 ): ReviewFinalizationResult {
-  if (prepared.result.status === 'failed' || !prepared.recovery) return prepared.result;
+  return prepared.result;
+}
+
+function replaceCurrentArtifactAtomically(file: string, content: string): void {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
   try {
-    const intent = readArtifactRecoveryIntent(prepared.recovery.repoRoot, prepared.recovery.taskId, prepared.recovery.family, prepared.recovery.artifact);
-    if (!intent) throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
-    let committed;
-    if (intent.state === 'passed' || intent.state === 'consumed') {
-      return {
-        ...prepared.result,
-        status: 'no-op',
-        changed: false,
-        artifactSha256: intent.finalArtifactSha256,
-        semanticDigest: intent.finalSemanticDigest,
-        error: null
-      };
-    } else if (intent.state === 'commit-started') {
-      const reconciled = reconcileArtifactRecovery(prepared.recovery, {
-        lockAlreadyHeld: prepared.lockAlreadyHeld,
-        afterPublish: options.afterPublish
-      });
-      committed = reconciled.intent;
-    } else if (intent.state === 'awaiting-preflight-recovery') {
-      const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
-      prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-    } else if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+    fs.writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
+    fs.renameSync(temporary, file);
+  } finally {
+    try { fs.unlinkSync(temporary); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
     }
-    if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
-      prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
-    } else if (intent.state === 'full-finalizer-ready') {
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
-    }
-    if (!committed || committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
-    return {
-      ...prepared.result,
-      artifactSha256: committed.finalArtifactSha256,
-      semanticDigest: committed.finalSemanticDigest,
-      error: null
-    };
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:')) throw error;
-    return { ...prepared.result, status: 'failed', error: {
-      code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
-    } };
   }
 }
 
@@ -494,14 +330,30 @@ function finalizeReviewSummaryUnlocked(
   catch (error) { return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId); }
   const prepared = prepareReviewSummaryCandidate(request, content, options);
   if (request.dryRun) return prepared.result;
-  return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
+  if (prepared.result.status === 'failed' || !prepared.result.changed) return prepared.result;
+  try {
+    replaceCurrentArtifactAtomically(validated.artifact.path, prepared.content);
+    return {
+      ...prepared.result,
+      status: 'applied',
+      artifactSha256: sha256Content(prepared.content),
+      semanticDigest: canonicalSemanticDigest(prepared.content)
+    };
+  } catch (error) {
+    return failed(
+      request,
+      'REVIEW_RECOVERY_COMMIT_FAILED',
+      `cannot update current review artifact: ${error instanceof Error ? error.message : String(error)}`,
+      resolved.taskId
+    );
+  }
 }
 
 function finalizeReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
-  const effectiveOptions = { ...options, startRecovery: !request.dryRun };
+  const effectiveOptions = options;
   if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, effectiveOptions);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, effectiveOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -52,7 +52,7 @@
     "installer"
   ],
   "dependencies": {
-    "@clack/prompts": "1.7.0",
+    "@clack/prompts": "1.8.1",
     "@larksuiteoapi/node-sdk": "^1.68.0",
     "cross-spawn": "^7.0.6",
     "fs-native-extensions": "1.5.1",

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

@@ -5,26 +5,40 @@
 - 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. The child must pass the activation barrier before any stage side effect. Missing, late, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run (on the claude-code path, missing or mismatched model/effort evidence, and fork/spawn-mode evidence this host structurally does not provide, follow the recording rules in `.agents/skills/run-task/reference/host-validation.md` instead and are exempt from this; missing or mismatched `parentId`/`childId` still pauses). Cross-root package/build/contract or hook/profile content drift is a deliverable warning; the current receipt's hook/evidence binding remains hard.
+- 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.
 
-## Recovery
+## Current Execution Records
 
-`orchestration.json` is the detailed state source. A current run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Readers accept only the complete structure emitted by the current writer; unknown fields, missing fields, invalid provenance, and old runs fail closed without rewriting. If the state cannot be recognized, preserve the file, advise rebuilding the sandbox or manually repairing it, do not migrate it, and do not create a follow-up task. Finish or clear every active run before upgrading agent-infra. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no consumed authorization, and no matching unconsumed active lifecycle evidence.
+`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. Existing task write locks and atomic writes protect updates.
 
-## Codex Host and Capability
+## Current Host
 
-- Direct-host accepts only trusted project or managed lifecycle hooks. A task-bound sandbox requires a controlled nested controller and isolated `CODEX_HOME`; only user hooks bound to that controller context are accepted. Ordinary user/plugin hooks are not evidence. The actual hook/profile used by the run is the source of record; content drift is reported as a warning with rebuild guidance.
-- The controller starts a nested loop only after control generation, task binding, protocol version, profiles, and hook discovery pass. Build/contract and content drift is reported as a structured warning with rebuild guidance instead of blocking natural evolution. Both bypass flags are restricted to this task-bound launch path.
-- Every prepare arms a one-use capability attested by the current loop's real PostToolUse. Atomic consumption binds task/session/build/controller and retains only a redacted tombstone.
+- 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.
+- Codex controller `open`, `verify`, and `close` remain restricted broker operations. After `open`, complete typed `verify` with the same lease proof before accepting the task, control-generation, and controller-instance binding.
+- 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, stop the wrapper/controller, and preserve the worktree, task/run/orchestration state, receipts, registration, 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, controller adapter, 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, proof, or request.
+- On either the new or rolled-back version, first confirm the same task through `status`/`route`, then require a successful typed controller `open`→`verify`. 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. Each mismatch needs its own fallback reason (the claude-code path may leave this blank and follow the recording rules instead), and requested values must never be fabricated as actual evidence.
+- 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.
-- claude-code's requested reasoning effort does not yet support per-role dispatch (concurrent tasks would race on a shared file); `delegationEvidence.actualReasoningEffort` is declared `spawn-ack`, meaning it is only recorded when honestly observed in a native spawn lifecycle event (Start/Stop) — it is not a promise of per-role dispatch and does not gate activation.
+- 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
 

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

@@ -5,26 +5,40 @@
 - 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
 - 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
 - reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
-- active run 中只有一个 pending delegation。child 必须在任何阶段副作用前通过 activation barrier；缺失、超时、错配、fork、重放、hook 不可用或工作区漂移一律暂停（claude-code 路径下 model/effort 证据的缺失或错配、以及该宿主结构上不提供的 fork/spawn-mode 证据，按 `.agents/skills/run-task/reference/host-validation.md` 的记录规则处理，不在此列；`parentId`/`childId` 的缺失或错配仍然暂停）。跨根 package/build/contract 或 hook/profile 内容漂移只输出可交付 warning；本轮 receipt 的 hook/evidence 绑定仍硬校验。
+- active run 中只有一个 pending delegation；阶段与实际 child 身份保持一致，启动和终态失败如实记录。
 - 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
 
-## 恢复语义
+## 当前执行记录
 
-`orchestration.json` 是详细状态源。current run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。读取时只接受当前 writer 的完整结构；未知字段、缺失字段、非法 provenance 或旧 run 一律失败关闭且不改写。遇到无法识别的 `orchestration.json`，保留原文件并提示重建 sandbox 或人工修复后重试，不做 schema 迁移，也不创建 follow-up task。升级 agent-infra 前必须完成或清空所有 active run。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。
+`orchestration.json` 记录阶段、模型策略、child 身份及实际执行结果。记录必须符合当前结构；本地操作者可直接修正后重新校验。已有任务写锁与原子写入继续保护写操作。
 
-## Codex 宿主与 capability
+## 当前宿主
 
-- direct-host 只接受 trusted project 或 managed lifecycle hooks。task-bound sandbox 必须由受控 nested controller 建立隔离 `CODEX_HOME`，仅接受绑定 controller context 的 user hooks；普通 user/plugin hook 不得成为证据源。使用本轮实际加载的 hook/profile，内容漂移只记录 warning 并提示重建 sandbox。
-- controller 只有在 control generation、task binding、协议版本、profile 与 hook discovery 全部通过后才能启动 nested loop；build/contract 及内容漂移通过结构化 warning 告知并建议重建 sandbox，不阻塞自然演进。两个 bypass 参数只允许出现在该 task-bound 启动路径。
-- 每次 prepare 前必须 arm 一次性 capability，并由同一当前 loop 的真实 PostToolUse attestation；token 原子消费后保留去敏 tombstone，不能重放或跨 task/session/build/controller 使用。
+- 使用当前宿主的原生 spawn、wait 与 App Server 结果；task-bound sandbox 在当前 worktree 本地执行普通任务编排。
+- Codex controller 的 `open`、`verify`、`close` 继续通过受限 broker 执行。`open` 后必须用同一 lease proof 完成 typed `verify`，再接受 task、control generation 和 controller instance 绑定。
+- 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 返回，停止 wrapper/controller，并保留 worktree、task/run/orchestration 状态、receipts、registration 与 audit。结果未知时先用本地 `status`/`route` 判断 domain 是否已提交，再按现有 recover/advance 语义处理；旧 broker request 不重放。
+- CLI、broker、controller adapter 和协议必须作为同一版本单元部署或回退。停止旧 container/broker 后执行 rebuild 与 `ai sandbox start --recreate <task-ref>`，以新 control generation 恢复执行；旧 token、proof 和 request 不得复用。
+- 新版本或回退版本都必须先核对同一任务的 `status`/`route`，再要求 controller typed `open`→`verify` 成功。任一检查失败时继续保持静默并保留证据，不局部混用组件或改写 domain 事实。
 
 ## 模型策略
 
 - 新 run 必须固化 executor/reviewer 各自的 model 与 reasoning effort；显式策略必须四字段原子完整，完全没有显式字段时才读取当前 client 的 `agentClients[].orchestration`。重入不得静默改写策略。
 - route 按 role 返回 requested model/effort，prepare 必须在工作区快照前精确匹配两者；原生 spawn 不能继承会话默认值。
-- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason（claude-code 路径下允许留空，按记录规则处理）；requested 值不得补造 actual 证据。
+- 原生 start 必须记录宿主观察到的 actual model/effort。适配器声明无法观察的字段按记录规则处理；任一可观察字段与 requested 不同时必须记录独立 fallback reason，requested 值不得补造 actual 证据。
 - 模型选择能力必须标记 complete catalog、partial catalog 或 interactive-only guidance；局部 override 枚举不得冒充完整目录。
-- claude-code 的 requested reasoning effort 暂不支持按角色下发（跨任务共享文件存在写入竞态）；`delegationEvidence.actualReasoningEffort` 声明为 `spawn-ack`，语义为"仅能在宿主原生 spawn 生命周期事件（Start/Stop）里如实观察到时记录，不构成按角色下发的承诺，也不构成放行门禁"。
+- 客户端无法按角色下发的策略字段必须由适配器明确声明；宿主事件中观察到的值只作为实际证据，不构成下发承诺或放行门禁。
 
 ## 稳定暂停条件
 

package/templates/.agents/rules/local-artifact-repair.en.md

@@ -1,73 +1,27 @@
-# General Rule - Model-Driven Local Artifact Recovery
+# Shared Rule - Current Local Artifact Revalidation
 
-This rule covers the pre-completion gate for `analyze-task`, `plan-task`, and `code-task`, plus the summary finalizers for the three review skills. It handles one canonical artifact in the current task directory only. It does not authorize changes to `task.md`, ledgers, receipts, source code, Git, platform resources, or lifecycle state.
+This rule applies to lifecycle artifact validation. Finalizers read the canonical artifact directly and do not create recovery candidates, generations, baselines, journals, or recovery identities.
 
-## Pre-completion gate
+## Current validation
 
-- Run the applicable finalizer before a completed event; pass only that invocation's `artifactSha256` and `semanticDigest` to the event.
-- When artifact content is invalid, the finalizer returns a controlled `recovery` with a `recoveryId`, `candidatePath`, and baseline digests. The formal artifact remains unchanged until recovery commit.
-- After the mechanical safety gates pass, the model may edit only the returned `candidatePath`. After each byte-changing edit, rerun the complete finalizer with the same task, stage/family, artifact, and `--recovery-id`. Never edit the formal artifact directly and call it a candidate.
-- Preflight stable-reads and validates candidate `S`, then seals immutable digest-addressed generation `R`; candidate SHA is an observation rather than an edit guard.
-- Preflight publishes active `R` through `preflight-ready → preflight-commit-started → preflight-passed`; the business finalizer publishes `F` through `full-finalizer-ready → commit-started → passed` and reuses `R` when `F=R`.
-- Candidate-only is a protocol authorization boundary, not OS isolation: a same-UID process with arbitrary host filesystem write access may tamper with recovery internals. Identity, fingerprint, and state checks detect such anomalies and fail closed, but the protocol does not claim an independent security principal or cross-platform isolation.
+1. Run the applicable finalizer before a completed event and use its returned `artifactSha256` and `semanticDigest`.
+2. On failure, read diagnostics, make one minimal repair to the canonical artifact, and rerun with the same task, family/stage, and artifact.
+3. Every rerun validates structure, qualification, upstream relations, ledger state, and current digests. Stop without publishing completed when there is no progress or repair is unsafe.
 
-## Recovery continuation context
+## Editing boundary
 
-Whenever a preflight or finalizer returns `recovery`, bind the complete continuation context from that response for the current execution: `taskRef`, `stage/family`, `artifact`, `recoveryId`, `candidatePath`, baseline digests, and the original entry point. These fields belong to one controlled transaction; do not regenerate, guess, or mix any of them for a later call.
+Agents may edit only the artifact declared by the current skill.
 
-- For a preflight failure, edit only that `candidatePath`, then rerun the same preflight entry point with the same `--recovery-id`. Only the successful response's recovery context may proceed to ledger writes or summary/finalization.
-- For a finalizer failure, edit only that `candidatePath`, then rerun that same finalizer entry point with the same `--recovery-id`.
-- Stop when the context is lost, the tuple differs, or the formal artifact was edited directly. A fresh invocation without `--recovery-id` cannot replace recovery, and a formal artifact is never a candidate.
+## Completed events
 
-## Authorization boundary
+Completed events still validate current digests, rounds, inputs, and external facts.
 
-- The finalizer and recovery core validate identity, state, permissions, stable reads, complete artifact semantics, and fingerprints. They do not infer repairability or expose a text-operation allow-list.
-- The model may edit only the one ordinary artifact declared by the current skill. It must not edit `task.md`, ledgers, receipts, source code, other reports, or remote resources.
-- `changed=false`, an error code, or a format shape is diagnostic evidence, not edit authorization. Stop on unproven human-decision semantics, concurrency, permission, I/O, identity, provenance, or unknown state.
-
-## Non-bypassable mechanical gates
-
-Before every candidate edit, confirm that:
-
-1. the finalizer failed with the same controlled recovery context and nothing formal was committed;
-2. task, family/stage, round, artifact, request/authority, and baseline fingerprints still match;
-3. `candidatePath` is the ordinary file generated by the recovery core and the formal target has not changed externally;
-4. the edit does not change human-decision semantics, detail or ledger identity, and introduces no other side effect.
-
-If any condition fails, stop without editing or publishing a completed event.
-
-## Durable recovery states
-
-| State | Formal artifact | Allowed action |
-| --- | --- | --- |
-| `awaiting-preflight-recovery` | baseline `B` | Edit `S`; stable-read, validate, and create `R` |
-| `preflight-ready` / `preflight-commit-started` | `B` or `R` | Reconcile/publish only active immutable `R` |
-| `preflight-passed` | `R` | Run the business finalizer for `F` |
-| `full-finalizer-ready` / `commit-started` | `R` or `F` | Reconcile/publish only pending immutable `F` |
-| `passed` | `F` | Completed event validates the final digest and consumes the intent |
-| `consumed` | `F` | Cleanup may reclaim the controlled staging and backup |
-| `aborted` | verified restored `B` | Preserve diagnostics; never fabricate success |
-
-The intent is current-only schema version 4. Legacy schemas fail closed; do not add migration, adapters, or dual writes. Candidate, baseline, generation, and intent files live in controlled repo-local directories and use canonical recovery IDs, regular-file checks, stable reads, the task lock, and expected-value CAS. No cross-file atomicity is claimed; unknown combinations remain indeterminate and retain their evidence.
-
-## Dynamic convergence loop
-
-1. Run the finalizer with the fixed invocation.
-2. On every failure that passes the gates, read the structured diagnostic and `candidatePath`, then make only one minimal, explainable candidate edit.
-3. Confirm byte-level progress and rerun every finalizer check with the same `--recovery-id`; if it still fails with a new diagnostic and fingerprint, return to step 2.
-4. Stop on repeated diagnostics or fingerprints, no byte progress, unknown recovery state, an unsafe repair, or the eight-edit limit for the current invocation. Do not publish a completed event or generate a cross-stage next step.
-
-## Shared entry points
-
-The current entry points are `task-artifact ... inspect|init|finalize-local` and `task-review ... finalize-summary`. Recovery retries use the `recoveryId` returned by the finalizer, for example:
+## Shared entry point
 
 ```text
-agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact} --recovery-id {recovery-id}
-agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} --recovery-id {recovery-id}
+agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact}
 ```
 
-There is no `task-artifact repair`, `replace-line`, `insert-section`, or `repairable` authorization. The structural engine returns diagnostics and digests only; the current skill's gates and the model decide whether and how to edit the candidate.
-
-## Lifecycle isolation
+## Stop conditions
 
-A completed event may legitimately modify `task.md`, but only after finalizer recovery is `passed` and digest, round, request, and authority all match. If authority consumption fails after the event write, retain the formal artifact and use the existing lifecycle recovery compensation; do not replay the completed write or roll back a passed artifact.
+Stop when repair is unsafe or makes no progress.