@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/lib/task/verification-engine.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 
 import {
   extractReviewBaseline,
+  extractReviewDiffBase,
   extractReviewDiffFingerprint,
   extractReviewedSnapshotTree,
   findAuthoritativeReviewCodeArtifact,
@@ -17,9 +18,12 @@ import {
 import { check as checkPlatformSync } from "../platform/verification-sync.ts";
 import { check as checkRequiredChecks } from "../platform/verification-required.ts";
 import { inspectPlatformPullRequest } from "../platform/pull-requests.ts";
+import { resolveMaterializedReviewedHeadRelation } from "../platform/change-request-git-evidence.ts";
 import { resolveReviewedHeadRelation } from "../platform/merged-pr-equivalence.ts";
+import { resolveLocalReviewedCommitRelation } from "../git/reviewed-commit-equivalence.ts";
 import { parseTypedTaskFrontmatter } from "./frontmatter.ts";
-import { parseLedger } from "./ledger.ts";
+import { parseLedger, summarizeLedgerStage, validateLedgerRows } from "./ledger.ts";
+import { equalCounts, parseReviewSummary } from "./review-artifacts.ts";
 import { loadVerificationConfig } from "./verification-config.ts";
 import { snapshotReview } from "../git/review-snapshot.ts";
 
@@ -110,10 +114,14 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkCompletionChecklist(context);
     case "review-ledger":
       return checkReviewLedger(context);
+    case "review-summary":
+      return checkReviewSummary(context);
     case "review-fact":
       return checkReviewFact(context);
     case "post-review-commit":
       return checkPostReviewCommit(context);
+    case "orchestration-state":
+      return checkOrchestrationState(context);
     default: {
       const adapter = PLATFORM_ADAPTERS[type];
       if (!adapter) {
@@ -129,6 +137,32 @@ function runCheck(type: any, context: any, shared: any): any {
   }
 }
 
+function checkOrchestrationState({ taskDir }: any): any {
+  const file = path.join(taskDir, 'orchestration.json');
+  const stat = safeStat(file);
+  if (!stat?.isFile()) return failResult('orchestration-state', 'orchestration.json is missing');
+  let run: any;
+  try {
+    run = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return failResult('orchestration-state', `Invalid orchestration.json: ${String(error)}`);
+  }
+  if (run.schemaVersion !== 1 || !['paused', 'completed'].includes(run.status)) {
+    return failResult('orchestration-state', `Expected paused or completed run, received '${run.status}'`);
+  }
+  if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
+    return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
+  }
+  if (run.status === 'completed') {
+    if (run.pendingDelegation !== null || !run.commitAuthorization?.consumedAt) {
+      return failResult('orchestration-state', 'Completed run must consume commit authorization and clear pending delegation');
+    }
+  } else if (run.pendingDelegation?.status === 'sealed') {
+    return failResult('orchestration-state', 'Paused run has a sealed delegation that could still advance');
+  }
+  return passResult('orchestration-state', `Orchestration run is safely ${run.status}`);
+}
+
 // === Check Functions ===
 
 function checkTaskMeta({ taskDir, config }: any): any {
@@ -313,6 +347,43 @@ function checkArtifact({ taskDir, config, artifactFile }: any): any {
   );
 }
 
+function checkReviewSummary({ taskDir, config, artifactFile }: any): any {
+  const stage = String(config.stage || "");
+  if (!["analysis", "plan", "code"].includes(stage)) {
+    return failResult("review-summary", `Invalid review stage '${stage}'`);
+  }
+  const resolvedArtifact = resolveArtifactPath(taskDir, "", artifactFile);
+  if (!resolvedArtifact.ok || !safeStat(resolvedArtifact.path)?.isFile()) {
+    return failResult("review-summary", resolvedArtifact.message || "Review artifact is missing");
+  }
+  const parsed = parseReviewSummary(fs.readFileSync(resolvedArtifact.path, "utf8"));
+  if (!parsed.ok) return failResult("review-summary", `${parsed.code}: ${parsed.message}`);
+  if (!parsed.summary.counts) {
+    return failResult("review-summary", "Review summary finding counts are not finalized");
+  }
+  const task = loadTask(taskDir);
+  if (!task.ok) return failResult("review-summary", task.message);
+  let rows;
+  try {
+    rows = parseLedger(task.content);
+  } catch (error) {
+    return failResult("review-summary", `Invalid disagreement ledger: ${String(error)}`);
+  }
+  const invalid = validateLedgerRows(rows);
+  if (invalid) return failResult("review-summary", `${invalid.code}: ${invalid.message}`);
+  const expected = summarizeLedgerStage(rows, stage as "analysis" | "plan" | "code").unresolvedFindingCounts;
+  if (!equalCounts(parsed.summary.counts, expected)) {
+    return failResult(
+      "review-summary",
+      `Review summary counts ${JSON.stringify(parsed.summary.counts)} do not match ledger ${JSON.stringify(expected)}`
+    );
+  }
+  return passResult(
+    "review-summary",
+    `${path.basename(resolvedArtifact.path)} finding counts match the ${stage} ledger`
+  );
+}
+
 function checkImplementationInput({ taskDir, artifactFile }: any): any {
   const task = loadTask(taskDir);
   if (!task.ok) return failResult("implementation-input", task.message);
@@ -683,8 +754,51 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
   }
 
   const task = loadTask(taskDir);
-  const content = fs.readFileSync(reviewArtifact.path!, "utf8");
+  if (!task.ok) return failResult("post-review-commit", task.message);
   const lastReviewedCommit = task.ok ? (task.metadata.last_reviewed_commit || "").trim() : "";
+  const globs = resolvePostReviewGlobs(config, loadPostReviewConfig(repoRoot));
+  const hasPullRequest = Number(task.metadata.pr_number) > 0;
+  let inspected: ReturnType<typeof inspectPlatformPullRequest> | null = null;
+  if (hasPullRequest) {
+    inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: gitRoot });
+    if (!inspected.pullRequest) {
+      const message = inspected.error?.message || "PR merge snapshot is unavailable";
+      const code = inspected.error?.code || "PR_INSPECTION_INVALID";
+      return inspected.status === "blocked"
+        ? blockedResult("post-review-commit", message, code)
+        : failResult("post-review-commit", message, code);
+    }
+    if (
+      inspected.pullRequest.state === "closed" &&
+      inspected.pullRequest.mergedAt &&
+      inspected.pullRequest.mergeCommitSha
+    ) {
+      const relation = resolveMaterializedReviewedHeadRelation({
+        cwd: gitRoot,
+        platformType: inspected.platform.type,
+        lastReviewedCommit,
+        pullRequest: inspected.pullRequest
+      });
+      if (relation.status === "merged-equivalent") {
+        return passResult(
+          "post-review-commit",
+          `Reviewed PR head is content-equivalent to squash merge ${relation.mergeCommit.slice(0, 8)} on target ${relation.comparisonHead.slice(0, 8)}`
+        );
+      }
+      if (relation.status === "blocked") {
+        return blockedResult("post-review-commit", relation.message, relation.code);
+      }
+      if (relation.status === "strict") {
+        return failResult(
+          "post-review-commit",
+          "Merged PR evidence did not establish squash merge equivalence",
+          "PR_MERGE_IDENTITY_INVALID"
+        );
+      }
+      return failResult("post-review-commit", relation.message, relation.code);
+    }
+  }
+
   const baselineSource = resolvePostReviewBaseline({
     gitRoot,
     lastReviewedCommit,
@@ -695,7 +809,6 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
   }
 
   const sha = baselineSource.sha;
-  const globs = resolvePostReviewGlobs(config, loadPostReviewConfig(repoRoot));
   let commits;
   try {
     const out = execFileSync("git", ["-C", gitRoot, "rev-list", `${sha}..HEAD`, "--", ...globs], { encoding: "utf8" });
@@ -708,42 +821,50 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
     return passResult("post-review-commit", `No post-review commits to code/rule paths since ${sha.slice(0, 8)}`);
   }
 
-  if (task.ok && Number(task.metadata.pr_number) > 0) {
-    const inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: gitRoot });
-    if (inspected.pullRequest) {
-      let localHead = "";
-      try {
-        localHead = execFileSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
-      } catch {
-        return blockedResult("post-review-commit", "Unable to resolve the local HEAD");
-      }
+  let localHead = "";
+  try {
+    localHead = execFileSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+  } catch {
+    return blockedResult("post-review-commit", "Unable to resolve the local HEAD");
+  }
+
+  if (hasPullRequest) {
+    if (inspected?.pullRequest) {
       const relation = resolveReviewedHeadRelation({
         gitRoot,
-        localHead,
+        comparisonHead: localHead,
         lastReviewedCommit: sha,
-        pullRequest: inspected.pullRequest,
-        pathspecs: globs
+        pullRequest: inspected.pullRequest
       });
       if (relation.status === "merged-equivalent") {
         return passResult("post-review-commit", `Reviewed PR head is content-equivalent to squash merge ${relation.mergeCommit.slice(0, 8)}`);
       }
       if (relation.status === "blocked") {
-        return blockedResult("post-review-commit", relation.message);
+        return blockedResult("post-review-commit", relation.message, relation.code);
       }
-    } else if (inspected.status === "blocked") {
-      return blockedResult("post-review-commit", inspected.error?.message || "PR merge snapshot is unavailable");
+    }
+  } else if (commits.length === 1) {
+    const relation = resolveLocalReviewedCommitRelation({
+      gitRoot,
+      localHead,
+      lastReviewedCommit: sha,
+      rewrittenCommit: commits[0]!,
+      pathspecs: globs
+    });
+    if (relation.status === "local-equivalent") {
+      return passResult(
+        "post-review-commit",
+        `Reviewed commit is content-equivalent to local rewrite ${relation.rewrittenCommit.slice(0, 8)}`
+      );
+    }
+    if (relation.status === "blocked") {
+      return blockedResult("post-review-commit", relation.message);
     }
   }
 
-  let exempt = false;
-  try {
-    exempt = task.ok && parseLedger(task.content).some(
-      (row) => row.stage === POST_REVIEW_COMMIT_STAGE && row.status === "human-decided"
-    );
-  } catch {
-    return failResult("post-review-commit", "Invalid disagreement ledger");
-  }
-  if (exempt) {
+  const exemption = resolvePostReviewExemption(task.content);
+  if (!exemption.ok) return failResult("post-review-commit", exemption.message);
+  if (exemption.exempt) {
     return passResult(
       "post-review-commit",
       `${commits.length} post-review commit(s) covered by a human-decided exemption`
@@ -756,6 +877,21 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
   );
 }
 
+function resolvePostReviewExemption(content: string):
+  | { ok: true; exempt: boolean }
+  | { ok: false; message: string } {
+  try {
+    return {
+      ok: true,
+      exempt: parseLedger(content).some(
+        (row) => row.stage === POST_REVIEW_COMMIT_STAGE && row.status === "human-decided"
+      )
+    };
+  } catch {
+    return { ok: false, message: "Invalid disagreement ledger" };
+  }
+}
+
 function checkReviewFact({ taskDir, artifactFile }: any): any {
   const resolvedArtifact = resolveArtifactPath(
     taskDir,
@@ -774,6 +910,7 @@ function checkReviewFact({ taskDir, artifactFile }: any): any {
   const content = fs.readFileSync(resolvedArtifact.path, "utf8");
   const verdict = parseReviewVerdict(content);
   const reviewBaseline = extractReviewBaseline(content);
+  const reviewDiffBase = extractReviewDiffBase(content);
   const reviewedFingerprint = extractReviewDiffFingerprint(content);
   const reviewedTree = extractReviewedSnapshotTree(content);
 
@@ -784,10 +921,16 @@ function checkReviewFact({ taskDir, artifactFile }: any): any {
   let gitRoot;
   let head;
   let baseline;
+  let diffBase;
   try {
     gitRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
     head = execFileSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
     baseline = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewBaseline}^{commit}`], { encoding: "utf8" }).trim();
+    diffBase = execFileSync(
+      "git",
+      ["-C", gitRoot, "rev-parse", `${reviewDiffBase || reviewBaseline}^{commit}`],
+      { encoding: "utf8" }
+    ).trim();
   } catch {
     return blockedResult(
       "review-fact",
@@ -804,7 +947,13 @@ function checkReviewFact({ taskDir, artifactFile }: any): any {
 
   let actualSnapshot;
   try {
-    actualSnapshot = snapshotReview({ cwd: gitRoot, mode: "worktree", baseline, globs: resolvePostReviewGlobs({}, loadPostReviewConfig(repoRoot)) });
+    actualSnapshot = snapshotReview({
+      cwd: gitRoot,
+      mode: "worktree",
+      baseline,
+      diffBase,
+      globs: resolvePostReviewGlobs({}, loadPostReviewConfig(repoRoot))
+    });
   } catch {
     return blockedResult(
       "review-fact",

package/lib/task/verification-review.ts

@@ -1,5 +1,6 @@
 export {
   extractReviewBaseline,
+  extractReviewDiffBase,
   extractReviewDiffFingerprint,
   extractReviewedSnapshotTree,
   findAuthoritativeReviewCodeArtifact,

package/lib/task/verification.ts

@@ -16,7 +16,8 @@ type VerificationEvent =
   | 'complete-task.preflight' | 'complete-task.completed'
   | 'create-pr.completed' | 'create-task.completed'
   | 'import-codescan.completed' | 'import-dependabot.completed'
-  | 'import-issue.completed' | 'watch-pr.completed';
+  | 'import-issue.completed' | 'watch-pr.completed'
+  | 'run-task.paused' | 'run-task.completed';
 type VerificationSpec = {
   skill: string;
   expectedState: 'active' | 'blocked' | 'completed';
@@ -70,7 +71,9 @@ const VERIFICATION_CATALOG: Readonly<Record<VerificationEvent, VerificationSpec>
   'import-codescan.completed': gate('import-codescan', 'active'),
   'import-dependabot.completed': gate('import-dependabot', 'active'),
   'import-issue.completed': gate('import-issue', 'active'),
-  'watch-pr.completed': gate('watch-pr', 'active')
+  'watch-pr.completed': gate('watch-pr', 'active'),
+  'run-task.paused': { skill: 'run-task', expectedState: 'active', mode: 'checks', checks: ['orchestration-state'] },
+  'run-task.completed': { skill: 'run-task', expectedState: 'active', mode: 'checks', checks: ['orchestration-state'] }
 };
 
 function failure(request: { taskRef: string; event: string; artifact?: string }, code: string, message: string, extra: Partial<TaskVerificationResult> = {}): TaskVerificationResult {

package/lib/task/workspace-snapshot.ts

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+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;
+}
+
+function captureWorkspaceSnapshot(repoRoot: string): string {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-orchestration-index-'));
+  const indexFile = path.join(tempDir, 'index');
+  try {
+    git(repoRoot, indexFile, ['read-tree', 'HEAD']);
+    git(repoRoot, indexFile, ['add', '-A', '--', ':/']);
+    const workspace = path.join(repoRoot, '.agents', 'workspace', 'active');
+    if (fs.existsSync(workspace)) {
+      git(repoRoot, indexFile, ['add', '-f', '--', '.agents/workspace/active']);
+    }
+    return git(repoRoot, indexFile, ['write-tree']).trim();
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function diffWorkspaceSnapshots(repoRoot: string, before: string, after: string): string[] {
+  const output = git(repoRoot, null, ['diff', '--name-only', '-z', before, after]);
+  return output.split('\0').filter(Boolean);
+}
+
+export { captureWorkspaceSnapshot, diffWorkspaceSnapshots };

package/lib/update.ts

@@ -1,10 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { normalizeAgentClients } from './agent-clients/config.ts';
+import {
+  applyAgentClientReconciliation,
+  planAgentClientReconciliation
+} from './agent-clients/reconcile.ts';
 import { info, ok, err } from './log.ts';
 import { resolveTemplateDir } from './paths.ts';
-import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
-import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from './builtin-tuis.ts';
-import type { BuiltinTUIId } from './builtin-tuis.ts';
+import { renderFile, copySkillDir } from './render.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -24,6 +27,8 @@ type UpdateConfig = {
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
   tuis?: unknown;
+  agentClients?: unknown;
+  customTUIs?: unknown;
 };
 
 type Defaults = {
@@ -40,9 +45,6 @@ const defaults = JSON.parse(
 
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
-const AGENT_INFRA_SANDBOX_TOOL = 'agent-infra';
-const LEGACY_DEFAULT_SANDBOX_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'opencode'];
-const DEFAULT_SANDBOX_TOOLS = [AGENT_INFRA_SANDBOX_TOOL, ...LEGACY_DEFAULT_SANDBOX_TOOLS];
 
 // One-time migration of the legacy project-level PR switch to the three-state
 // `prFlow` preference. `true` (the old default / "PR flow on") maps to the
@@ -63,83 +65,6 @@ function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
   return null;
 }
 
-function isLegacyDefaultSandboxTools(value: unknown): value is string[] {
-  if (!Array.isArray(value) || value.length !== LEGACY_DEFAULT_SANDBOX_TOOLS.length) {
-    return false;
-  }
-  const tools = new Set(value);
-  return LEGACY_DEFAULT_SANDBOX_TOOLS.every((tool) => tools.has(tool));
-}
-
-function migrateSandboxTools(config: UpdateConfig): boolean {
-  const tools = config.sandbox?.tools;
-  if (!isLegacyDefaultSandboxTools(tools)) {
-    return false;
-  }
-  config.sandbox = {
-    ...config.sandbox,
-    tools: [...DEFAULT_SANDBOX_TOOLS]
-  };
-  return true;
-}
-
-function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
-  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
-  if (!top.startsWith('.')) return false;
-
-  const candidate = top.slice(1);
-  if (!KNOWN_PLATFORMS.has(candidate)) return false;
-  return candidate !== platformType;
-}
-
-function syncFileRegistry(config: UpdateConfig, platformType: string, enabledTUIs: Set<BuiltinTUIId>) {
-  config.files ||= {};
-  const before = JSON.stringify({
-    files: {
-      managed: config.files.managed || [],
-      merged: config.files.merged || [],
-      ejected: config.files.ejected || []
-    }
-  });
-  config.files.managed = config.files.managed || [];
-  config.files.merged = config.files.merged || [];
-  config.files.ejected = config.files.ejected || [];
-
-  const allExisting = [
-    ...config.files.managed,
-    ...config.files.merged,
-    ...config.files.ejected
-  ];
-  const added: Pick<FileRegistry, 'managed' | 'merged'> = { managed: [], merged: [] };
-
-  for (const entry of defaults.files.managed) {
-    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
-    if (!allExisting.includes(entry)) {
-      config.files.managed.push(entry);
-      added.managed.push(entry);
-    }
-  }
-  for (const entry of defaults.files.merged) {
-    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
-    if (!allExisting.includes(entry)) {
-      config.files.merged.push(entry);
-      added.merged.push(entry);
-    }
-  }
-
-  const after = JSON.stringify({
-    files: {
-      managed: config.files.managed,
-      merged: config.files.merged,
-      ejected: config.files.ejected
-    }
-  });
-
-  return { added, changed: before !== after };
-}
-
 async function cmdUpdate(): Promise<void> {
   console.log('');
   console.log('  ai update');
@@ -167,24 +92,36 @@ async function cmdUpdate(): Promise<void> {
   const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as UpdateConfig;
   const { project, org, language } = config;
   const platformType = config.platform?.type || defaults.platform.type;
-  const enabledTUIs = resolveEnabledTUIs(config.tuis);
   const replacements = { project, org };
 
+  const normalizedOriginal = normalizeAgentClients(config);
+  const currentRegistry: FileRegistry = {
+    managed: config.files?.managed || [],
+    merged: config.files?.merged || [],
+    ejected: config.files?.ejected || []
+  };
+  const platformAdded = !config.platform;
+  const sandboxAdded = !config.sandbox;
+  const taskAdded = !config.task;
+  const labelsAdded = !config.labels;
+  const prFlowMigrated = migratePrFlow(config);
+  if (platformAdded) config.platform = structuredClone(defaults.platform);
+  if (sandboxAdded) config.sandbox = structuredClone(defaults.sandbox);
+  if (taskAdded) config.task = structuredClone(defaults.task);
+  if (labelsAdded) config.labels = structuredClone(defaults.labels);
+
+  const workflowPlan = planAgentClientReconciliation({
+    config: config as unknown as Record<string, unknown>,
+    mutation: { type: 'replace-state', state: normalizedOriginal.state },
+    projectRoot: process.cwd(),
+    templateRoot: templateDir,
+    platformType,
+    language
+  });
+
   info(`Updating seed files for: ${project}`);
   console.log('');
 
-  // select language-specific template filenames
-  let claudeSrc, geminiSrc, opencodeSrc;
-  if (language === 'zh-CN') {
-    claudeSrc = 'update-agent-infra.zh-CN.md';
-    geminiSrc = 'update-agent-infra.zh-CN.toml';
-    opencodeSrc = 'update-agent-infra.zh-CN.md';
-  } else {
-    claudeSrc = 'update-agent-infra.en.md';
-    geminiSrc = 'update-agent-infra.en.toml';
-    opencodeSrc = 'update-agent-infra.en.md';
-  }
-
   // update skill
   copySkillDir(
     path.join(templateDir, '.agents', 'skills', 'update-agent-infra'),
@@ -206,76 +143,19 @@ async function cmdUpdate(): Promise<void> {
     // Ignore missing legacy script from pre-ESM installs.
   }
 
-  // update Claude command (only if enabled)
-  if (enabledTUIs.has('claude-code')) {
-    renderFile(
-      path.join(templateDir, '.claude', 'commands', claudeSrc),
-      path.join('.claude', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Updated .claude/commands/update-agent-infra.md');
-  }
-
-  // update Gemini command (only if enabled)
-  if (enabledTUIs.has('gemini-cli')) {
-    renderFile(
-      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-      replacements
-    );
-    ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
-  }
-
-  // update OpenCode command (only if enabled)
-  if (enabledTUIs.has('opencode')) {
-    renderFile(
-      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-      path.join('.opencode', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Updated .opencode/commands/update-agent-infra.md');
-  }
-
-  // sync file registry
-  const { added, changed } = syncFileRegistry(config, platformType, enabledTUIs);
+  const added = {
+    managed: workflowPlan.projectAssets.registry.managed.filter(
+      (entry) => !currentRegistry.managed.includes(entry)
+    ),
+    merged: workflowPlan.projectAssets.registry.merged.filter(
+      (entry) => !currentRegistry.merged.includes(entry)
+    )
+  };
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
-  const platformAdded = !config.platform;
-  const sandboxAdded = !config.sandbox;
-  const taskAdded = !config.task;
-  const labelsAdded = !config.labels;
-  const prFlowMigrated = migratePrFlow(config);
-  const sandboxToolsMigrated = !sandboxAdded && migrateSandboxTools(config);
-  let configChanged = changed;
+  const reconcileResult = applyAgentClientReconciliation(workflowPlan);
+  for (const target of reconcileResult.applied) ok(`Updated ${target}`);
 
-  if (platformAdded) {
-    config.platform = structuredClone(defaults.platform);
-    configChanged = true;
-  }
-
-  if (sandboxAdded) {
-    config.sandbox = structuredClone(defaults.sandbox);
-    configChanged = true;
-  }
-
-  if (taskAdded) {
-    config.task = structuredClone(defaults.task);
-    configChanged = true;
-  }
-
-  if (labelsAdded) {
-    config.labels = structuredClone(defaults.labels);
-    configChanged = true;
-  }
-
-  if (prFlowMigrated) {
-    configChanged = true;
-  }
-
-  if (sandboxToolsMigrated) {
-    configChanged = true;
-  }
-
-  if (configChanged) {
+  if (reconcileResult.configUpdated) {
     console.log('');
     if (hasNewEntries) {
       info(`New file entries synced to ${CONFIG_PATH}:`);
@@ -301,9 +181,6 @@ async function cmdUpdate(): Promise<void> {
       if (prFlowMigrated) {
         info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
       }
-      if (sandboxToolsMigrated) {
-        info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} in ${CONFIG_PATH}.`);
-      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -322,10 +199,6 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && prFlowMigrated) {
       info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
     }
-    if (hasNewEntries && sandboxToolsMigrated) {
-      info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} in ${CONFIG_PATH}.`);
-    }
-    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);
   }
 
@@ -333,24 +206,15 @@ async function cmdUpdate(): Promise<void> {
   console.log('');
   ok('Seed files updated successfully!');
   console.log('');
-  if (enabledTUIs.size === 0) {
-    console.log('  No built-in TUI enabled (tuis: []).');
+  if (workflowPlan.nextSteps.length === 0) {
+    console.log('  No Agent Client project integration enabled.');
     console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
     console.log('');
   } else {
     console.log('  Next step: run the full update in your AI TUI:');
     console.log('');
-    const claudeOrOpencode: string[] = [];
-    if (enabledTUIs.has('claude-code')) claudeOrOpencode.push('Claude Code');
-    if (enabledTUIs.has('opencode')) claudeOrOpencode.push('OpenCode');
-    if (claudeOrOpencode.length > 0) {
-      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
-    }
-    if (enabledTUIs.has('gemini-cli')) {
-      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-    }
-    if (enabledTUIs.has('codex')) {
-      console.log('    Codex CLI:               $update-agent-infra');
+    for (const nextStep of workflowPlan.nextSteps) {
+      console.log(`    ${nextStep.displayName}: ${nextStep.command}`);
     }
     console.log('');
   }