@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/lib/init.ts

@@ -8,13 +8,13 @@ import { resolveTemplateDir } from './paths.ts';
 import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
 import { enginesForPlatform } from './sandbox/engines/index.ts';
 import { VERSION } from './version.ts';
+import { listAgentClientAdapters } from './agent-clients/registry.ts';
+import { serializeAgentClients } from './agent-clients/config.ts';
 import {
-  BUILTIN_TUI_IDS,
-  BUILTIN_TUI_DISPLAY,
-  isPathOwnedByDisabledTUI,
-  resolveEnabledTUIs
-} from './builtin-tuis.ts';
-import type { BuiltinTUIId } from './builtin-tuis.ts';
+  applyAgentClientReconciliation,
+  planAgentClientReconciliation
+} from './agent-clients/reconcile.ts';
+import type { AgentClientState } from './agent-clients/types.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -28,6 +28,7 @@ type SourceEntry = {
 };
 
 type Defaults = {
+  agentClients: AgentConfig['agentClients'];
   files: FileRegistry;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
@@ -44,7 +45,7 @@ type AgentConfig = {
   task: { shortIdLength: number };
   labels: Record<string, unknown>;
   files: FileRegistry;
-  tuis: string[];
+  agentClients: ReturnType<typeof serializeAgentClients>;
   templates?: { sources: SourceEntry[] };
   skills?: { sources: SourceEntry[] };
 };
@@ -59,28 +60,6 @@ const PLATFORM_DEFAULT_ENGINES = Object.freeze({
   win32: 'wsl2'
 });
 
-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 buildDefaultFiles(platformType: string, enabledTUIs: Set<BuiltinTUIId>): FileRegistry {
-  const ownedByDisabled = (entry: string) => isPathOwnedByDisabledTUI(entry, enabledTUIs);
-  return {
-    managed: (defaults.files.managed || []).filter(
-      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
-    ),
-    merged: (defaults.files.merged || []).filter(
-      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
-    ),
-    ejected: structuredClone(defaults.files.ejected || [])
-  };
-}
-
 function detectProjectName(): string {
   try {
     const url = execSync('git remote get-url origin', { stdio: ['pipe', 'pipe', 'pipe'] })
@@ -222,11 +201,12 @@ async function cmdInit(): Promise<void> {
     );
   }
 
-  let enabledTUIs: string[];
+  const adapters = listAgentClientAdapters();
+  let enabledClientIds: string[];
   try {
-    enabledTUIs = await multiSelect(
-      'Built-in TUI command files to install/manage',
-      BUILTIN_TUI_IDS.map((id) => ({ id, label: BUILTIN_TUI_DISPLAY[id] }))
+    enabledClientIds = await multiSelect(
+      'Agent Client project integrations to enable',
+      adapters.map((adapter) => ({ id: adapter.id, label: adapter.displayName }))
     );
   } catch (e) {
     err(e instanceof Error ? e.message : String(e));
@@ -234,7 +214,7 @@ async function cmdInit(): Promise<void> {
     process.exitCode = 1;
     return;
   }
-  const enabledTUISet = resolveEnabledTUIs(enabledTUIs);
+  const enabledClientSet = new Set(enabledClientIds);
 
   const templateSources = parseLocalSources(await prompt(
     'Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)',
@@ -249,6 +229,39 @@ async function cmdInit(): Promise<void> {
   const project = projectName;
   const replacements = { project, org: orgName };
 
+  const defaultState = Object.fromEntries(defaults.agentClients.map((entry) => [
+    entry.id,
+    {
+      enabled: enabledClientSet.has(entry.id),
+      installInSandbox: entry.installInSandbox
+    }
+  ])) as AgentClientState;
+  const config: AgentConfig = {
+    project: projectName,
+    org: orgName,
+    language,
+    platform: { type: platformType },
+    templateVersion: VERSION,
+    sandbox: structuredClone(defaults.sandbox),
+    task: structuredClone(defaults.task),
+    labels: structuredClone(defaults.labels),
+    files: { managed: [], merged: [], ejected: [] },
+    agentClients: serializeAgentClients(defaultState)
+  };
+
+  if (sandboxEngine) config.sandbox.engine = sandboxEngine;
+  if (templateSources.length > 0) config.templates = { sources: templateSources };
+  if (skillSources.length > 0) config.skills = { sources: skillSources };
+
+  const workflowPlan = planAgentClientReconciliation({
+    config: config as unknown as Record<string, unknown>,
+    mutation: { type: 'none' },
+    projectRoot: process.cwd(),
+    templateRoot: templateDir,
+    platformType,
+    language
+  });
+
   console.log('');
   if (orgName) {
     info(`Installing update-agent-infra seed command for: ${projectName} (${orgName})`);
@@ -257,18 +270,6 @@ async function cmdInit(): Promise<void> {
   }
   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';
-  }
-
   // install skill
   copySkillDir(
     path.join(templateDir, '.agents', 'skills', 'update-agent-infra'),
@@ -285,68 +286,8 @@ async function cmdInit(): Promise<void> {
   );
   ok('Installed .agents/scripts/lib/agent-infra-package.js');
 
-  // install Claude command (only if enabled)
-  if (enabledTUISet.has('claude-code')) {
-    renderFile(
-      path.join(templateDir, '.claude', 'commands', claudeSrc),
-      path.join('.claude', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Installed .claude/commands/update-agent-infra.md');
-  }
-
-  // install Gemini command (only if enabled)
-  if (enabledTUISet.has('gemini-cli')) {
-    renderFile(
-      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-      replacements
-    );
-    ok(`Installed .gemini/commands/${project}/update-agent-infra.toml`);
-  }
-
-  // install OpenCode command (only if enabled)
-  if (enabledTUISet.has('opencode')) {
-    renderFile(
-      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-      path.join('.opencode', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Installed .opencode/commands/update-agent-infra.md');
-  }
-
-  // generate .agents/.airc.json
-  const config: AgentConfig = {
-    project: projectName,
-    org: orgName,
-    language,
-    platform: { type: platformType },
-    templateVersion: VERSION,
-    sandbox: structuredClone(defaults.sandbox),
-    task: structuredClone(defaults.task),
-    labels: structuredClone(defaults.labels),
-    files: buildDefaultFiles(platformType, enabledTUISet),
-    tuis: enabledTUIs
-  };
-
-  if (sandboxEngine) {
-    config.sandbox.engine = sandboxEngine;
-  }
-
-  if (templateSources.length > 0) {
-    config.templates = {
-      sources: templateSources
-    };
-  }
-
-  if (skillSources.length > 0) {
-    config.skills = {
-      sources: skillSources
-    };
-  }
-
-  fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  const reconcileResult = applyAgentClientReconciliation(workflowPlan);
+  for (const target of reconcileResult.applied) ok(`Installed ${target}`);
   ok(`Generated ${configPath}`);
 
   // done
@@ -356,24 +297,15 @@ async function cmdInit(): Promise<void> {
   console.log('  If this init used npx, install agent-infra persistently before update or validation:');
   console.log('    npm install -g @fitlab-ai/agent-infra');
   console.log('');
-  if (enabledTUISet.size === 0) {
-    console.log('  No built-in TUI selected.');
+  if (workflowPlan.nextSteps.length === 0) {
+    console.log('  No Agent Client project integration enabled.');
     console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);
     console.log('');
   } else {
     console.log('  Next step: open this project in any AI TUI and run:');
     console.log('');
-    const claudeOrOpencode: string[] = [];
-    if (enabledTUISet.has('claude-code')) claudeOrOpencode.push('Claude Code');
-    if (enabledTUISet.has('opencode')) claudeOrOpencode.push('OpenCode');
-    if (claudeOrOpencode.length > 0) {
-      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
-    }
-    if (enabledTUISet.has('gemini-cli')) {
-      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-    }
-    if (enabledTUISet.has('codex')) {
-      console.log('    Codex CLI:               $update-agent-infra');
+    for (const nextStep of workflowPlan.nextSteps) {
+      console.log(`    ${nextStep.displayName}: ${nextStep.command}`);
     }
     console.log('');
     console.log('  This will render all templates and set up the full');

package/lib/internal/agent-client.ts

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  AgentClientConfigError,
+  normalizeAgentClients
+} from '../agent-clients/config.ts';
+import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
+import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
+
+const USAGE = 'Usage: agent-infra-internal agent-client next-steps --skill <skill-name> [--task-ref <NN|TASK-id>] [--format text|json]\n';
+
+type ParsedArgs = Readonly<{
+  skillName: string;
+  taskRef?: string;
+  format: 'text' | 'json';
+}>;
+
+function failure(code: string, message: string): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed',
+    changed: false,
+    commands: [],
+    diagnostics: [],
+    error: { code, message }
+  })}\n`);
+  process.exitCode = 1;
+}
+
+function parseArgs(args: string[]): ParsedArgs | null {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return null;
+  }
+  if (args[0] !== 'next-steps') {
+    failure('AGENT_CLIENT_PAYLOAD_INVALID', "operation must be 'next-steps'");
+    return null;
+  }
+  let skillName: string | undefined;
+  let taskRef: string | undefined;
+  let format: 'text' | 'json' = 'text';
+  const seen = new Set<string>();
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!['--skill', '--task-ref', '--format'].includes(flag)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `unknown option '${flag}'`);
+      return null;
+    }
+    if (seen.has(flag)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `duplicate option '${flag}'`);
+      return null;
+    }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+      return null;
+    }
+    seen.add(flag);
+    if (flag === '--skill') skillName = value;
+    if (flag === '--task-ref') taskRef = value;
+    if (flag === '--format') {
+      if (value !== 'text' && value !== 'json') {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', "format must be 'text' or 'json'");
+        return null;
+      }
+      format = value;
+    }
+  }
+  if (!skillName) {
+    failure('AGENT_CLIENT_PAYLOAD_INVALID', "option '--skill' is required");
+    return null;
+  }
+  return { skillName, ...(taskRef ? { taskRef } : {}), format };
+}
+
+function agentClient(args: string[] = []): void {
+  const parsed = parseArgs(args);
+  if (!parsed || process.exitCode) return;
+
+  let config: Record<string, unknown>;
+  try {
+    const configPath = path.join(process.cwd(), '.agents', '.airc.json');
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as unknown;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      throw new Error('configuration root must be an object');
+    }
+    config = raw as Record<string, unknown>;
+  } catch (error) {
+    failure('AGENT_CLIENT_CONFIG_INVALID', String(error));
+    return;
+  }
+
+  try {
+    const clients = normalizeAgentClients(config);
+    const custom = normalizeCustomTUIs(process.cwd(), config.customTUIs ?? []);
+    const commands = renderNextStepCommands({
+      projectName: String(config.project ?? ''),
+      state: clients.state,
+      customTUIs: custom.items,
+      skillName: parsed.skillName,
+      ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {})
+    });
+    if (parsed.format === 'json') {
+      process.stdout.write(`${JSON.stringify({
+        status: 'rendered',
+        changed: false,
+        commands,
+        diagnostics: custom.diagnostics,
+        error: null
+      })}\n`);
+      return;
+    }
+    for (const command of commands) {
+      process.stdout.write(`  - ${command.displayName}: ${command.command}\n`);
+    }
+    for (const diagnostic of custom.diagnostics) {
+      process.stderr.write(`${diagnostic.code} at ${diagnostic.path}\n`);
+    }
+  } catch (error) {
+    if (error instanceof AgentClientConfigError) {
+      failure(error.code, error.message);
+      return;
+    }
+    failure(
+      'AGENT_CLIENT_RENDER_INVALID',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+
+export { agentClient };

package/lib/internal/git-workflow.ts

@@ -27,7 +27,7 @@ function gitWorkflow(args: string[] = []): void {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     if (!input) result = { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-    else if (action === 'snapshot') result = { status: 'no-op', changed: false, snapshot: snapshotReview({ cwd: cwd ?? process.cwd(), mode: input.mode, baseline: input.baseline, globs: input.globs ?? resolvePostReviewGlobs({}, {}) }), error: null };
+    else if (action === 'snapshot') result = { status: 'no-op', changed: false, snapshot: snapshotReview({ cwd: cwd ?? process.cwd(), mode: input.mode, baseline: input.baseline, diffBase: input.diffBase, globs: input.globs ?? resolvePostReviewGlobs({}, {}) }), error: null };
     else result = { status: 'no-op', changed: false, comparison: compareReviewTrees({ cwd: cwd ?? process.cwd(), expected: input.expected, actual: input.actual }), error: null };
   } else result = { status: 'failed', changed: false, error: { code: 'GIT_ACTION_INVALID', message: `Unknown git-workflow action '${action ?? ''}'` } };
   output(result);

package/lib/internal/release-workflow.ts

@@ -150,11 +150,58 @@ function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult
   return { status: 'recorded', reasonCode: null, message: null, outputPath };
 }
 
-function git(cwd: string, args: string[]): string | null {
-  const result = command(cwd, 'git', args);
+function git(cwd: string, args: string[], run: CommandRunner = command): string | null {
+  const result = run(cwd, 'git', args);
   return result.status === 0 ? String(result.stdout).trim() : null;
 }
 
+function inspectLocalReleaseFacts(cwd: string, version: string, run: CommandRunner = command) {
+  const tag = `v${version}`;
+  const head = git(cwd, ['rev-parse', 'HEAD'], run);
+  const tagCommit = git(cwd, ['rev-parse', '--verify', `${tag}^{commit}`], run);
+  const localTag = Boolean(tagCommit && tagCommit === head);
+  const localTagAncestor = Boolean(
+    tagCommit && head && !localTag
+    && run(cwd, 'git', ['merge-base', '--is-ancestor', tagCommit, head]).status === 0
+  );
+  const localTagConflict = Boolean(tagCommit && !localTag && !localTagAncestor);
+  const postSubject = `chore: prepare next dev iteration after v${version}`;
+  const postLog = localTag || localTagAncestor
+    ? git(cwd, ['log', '--format=%s', `${tag}..HEAD`], run) ?? ''
+    : '';
+  const postCommit = postLog.split('\n').some((subject) => subject === postSubject);
+  return { localTag, localTagAncestor, localTagConflict, postCommit };
+}
+
+function releaseSmokeStatus(workflows: Array<Record<string, unknown>>, version: string, tagCommit: string | null): ReleaseFacts['smoke'] {
+  const manualTitle = `Post-Release Smoke v${version}`;
+  const targets = workflows.filter((run) => {
+    if (String(run.workflowName || run.name) !== 'Post-Release Smoke') return false;
+    if (String(run.event) === 'workflow_run') return Boolean(tagCommit && String(run.headSha) === tagCommit);
+    return String(run.event) === 'workflow_dispatch' && String(run.displayTitle) === manualTitle;
+  }).sort((left, right) => {
+    const leftOrder = [Date.parse(String(left.createdAt || '')) || 0, Number(left.databaseId) || 0, Number(left.attempt) || 0];
+    const rightOrder = [Date.parse(String(right.createdAt || '')) || 0, Number(right.databaseId) || 0, Number(right.attempt) || 0];
+    for (let index = 0; index < leftOrder.length; index += 1) {
+      if (leftOrder[index] !== rightOrder[index]) return rightOrder[index]! - leftOrder[index]!;
+    }
+    return 0;
+  });
+  const latest = targets[0];
+  if (!latest) return null;
+  if (String(latest.status) !== 'completed') return 'pending';
+  return String(latest.conclusion) === 'success' ? 'success' : 'failed';
+}
+
+function inspectPostWorktree(cwd: string) {
+  const inspected = inspectGitWorkflow(cwd);
+  if (!inspected.snapshot) return inspected.error ?? { code: 'GIT_INSPECT_FAILED', message: 'Unable to inspect Git repository' };
+  if (inspected.snapshot.worktree.length || inspected.snapshot.staged.length) {
+    return { code: 'WORKTREE_DIRTY', message: 'Release post requires a clean worktree' };
+  }
+  return null;
+}
+
 async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts> {
   const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')) as { name: string };
   const config = JSON.parse(fs.readFileSync(path.join(cwd, '.agents', '.airc.json'), 'utf8')) as { project: string; org: string };
@@ -162,6 +209,7 @@ async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts>
   const branch = git(cwd, ['branch', '--show-current']) || '';
   const head = git(cwd, ['rev-parse', 'HEAD']);
   const localTagTarget = git(cwd, ['rev-parse', '--verify', `${tag}^{commit}`]);
+  const local = inspectLocalReleaseFacts(cwd, version);
   const remoteBranch = branch ? git(cwd, ['ls-remote', '--heads', 'origin', branch]) : null;
   const remoteTag = git(cwd, ['ls-remote', '--tags', 'origin', `refs/tags/${tag}`]);
   const platform = inspectPlatformRelease(tag, { cwd });
@@ -169,18 +217,14 @@ async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts>
   const formulaUrl = `https://raw.githubusercontent.com/${config.org}/homebrew-tap/main/Formula/${config.project}.rb`;
   const homebrew = await inspectHomebrewChannel(formulaUrl, version);
   const workflows = platform.workflows as Array<Record<string, unknown>>;
-  const smokeRun = workflows.find((run) => String(run.name).toLowerCase().includes('post-release-smoke') && String(run.headBranch) === tag);
-  const smoke = smokeRun ? String(smokeRun.conclusion) === 'success' ? 'success' : String(smokeRun.status) === 'completed' ? 'failed' : 'pending' : null;
-  const postMessage = git(cwd, ['log', '-1', '--pretty=%s']) || '';
+  const smoke = releaseSmokeStatus(workflows, version, localTagTarget);
   return {
-    localTag: Boolean(localTagTarget && localTagTarget === head),
-    localTagConflict: Boolean(localTagTarget && localTagTarget !== head),
+    ...local,
     remoteBranch: Boolean(remoteBranch && remoteBranch.split(/\s+/)[0] === head), remoteTag: Boolean(remoteTag),
     githubRelease: platform.platform.type !== 'github'
       ? true
       : platform.status === 'blocked' ? null : Boolean(platform.release?.published),
-    npm: npm.published, homebrew: homebrew.published, smoke,
-    postCommit: postMessage.includes(`after v${version}`)
+    npm: npm.published, homebrew: homebrew.published, smoke
   };
 }
 
@@ -218,12 +262,11 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   }
   const before = releaseSnapshot(version, await inspectFacts(cwd, version));
   if (action === 'inspect') { process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`); return; }
+  if (before.facts.localTagConflict) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'GIT_TAG_CONFLICT', message: `Tag v${version} is not reachable from HEAD` } })}\n`);
+    process.exitCode = 1; return;
+  }
   if (action === 'prepare') {
-    if (before.facts.localTagConflict) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'GIT_TAG_CONFLICT', message: `Tag v${version} does not point to HEAD` } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
     if (before.phase !== 'unprepared') {
       const milestones = reconcileReleaseMilestones(version, { cwd });
       process.stdout.write(`${JSON.stringify({ ...milestones, snapshot: before })}\n`);
@@ -254,16 +297,25 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
     process.exitCode = failed ? 1 : blocked ? 2 : 0; return;
   }
   if (action === 'publish') {
-    if (!['prepared', 'partially-published'].includes(before.phase)) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_PHASE_INVALID', message: `Cannot publish from ${before.phase}` } })}\n`); process.exitCode = 1; return; }
+    if (!before.facts.localTag || !['prepared', 'partially-published'].includes(before.phase)) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'RELEASE_PHASE_INVALID', message: `Cannot publish from ${before.phase}` } })}\n`); process.exitCode = 1; return; }
     const branch = git(cwd, ['branch', '--show-current']) || '';
     const refs = [...(!before.facts.remoteBranch ? [branch] : []), ...(!before.facts.remoteTag ? [`refs/tags/v${version}`] : [])];
     const result = pushGitRefs({ cwd, remote: 'origin', refs });
     process.stdout.write(`${JSON.stringify({ ...result, snapshot: releaseSnapshot(version, await inspectFacts(cwd, version)) })}\n`); process.exitCode = result.status === 'failed' ? 1 : result.status === 'degraded' ? 2 : 0; return;
   }
+  if (before.phase === 'complete') {
+    process.stdout.write(`${JSON.stringify({ status: 'no-op', changed: false, snapshot: before, error: null })}\n`);
+    return;
+  }
   const channelsComplete = before.facts.githubRelease === true && before.facts.npm === true && before.facts.homebrew === true;
   if (!['published', 'post-pending'].includes(before.phase) || !channelsComplete || before.facts.smoke !== 'success') {
     process.stdout.write(`${JSON.stringify({ status: before.facts.smoke === 'failed' ? 'failed' : 'blocked', changed: false, snapshot: before, error: { code: 'RELEASE_CHANNELS_PENDING', message: 'Release channels or smoke workflow are not complete' } })}\n`); process.exitCode = before.facts.smoke === 'failed' ? 1 : 2; return;
   }
+  const worktreeError = inspectPostWorktree(cwd);
+  if (worktreeError) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: worktreeError })}\n`);
+    process.exitCode = 1; return;
+  }
   const built = command(cwd, 'npm', ['run', 'build']);
   if (built.status !== 0) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_POST_COMMAND_FAILED', message: String(built.stderr || built.stdout) } })}\n`);
@@ -284,5 +336,5 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   process.stdout.write(`${JSON.stringify({ ...pushed, demo, snapshot: releaseSnapshot(version, await inspectFacts(cwd, version)) })}\n`); process.exitCode = pushed.status === 'failed' ? 1 : pushed.status === 'degraded' ? 2 : 0;
 }
 
-export { computeDemoInputDigest, inspectFacts, releaseWorkflow, runOptionalDemo };
+export { computeDemoInputDigest, inspectFacts, inspectLocalReleaseFacts, inspectPostWorktree, releaseSmokeStatus, releaseWorkflow, runOptionalDemo };
 export type { CommandRunner, DemoResult };

package/lib/internal/task-orchestration.ts

@@ -0,0 +1,132 @@
+import {
+  activateMatchingOrchestrationDelegation,
+  activateOrchestrationDelegation,
+  advanceOrchestration,
+  beginOrResumeOrchestration,
+  completeCommitOrchestrationStage,
+  pauseOrchestration,
+  prepareOrchestrationDelegation,
+  routeOrchestration,
+  sealMatchingOrchestrationDelegation,
+  sealOrchestrationDelegation,
+  statusOrchestration
+} from '../task/orchestration.ts';
+import type { AgentClientId } from '../agent-clients/types.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|stage-completed|hook-stop|advance|pause|status> [options]\n';
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed', changed: false,
+    error: { code: 'ORCHESTRATION_PAYLOAD_INVALID', message }
+  })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 2;
+}
+
+function taskOrchestration(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.length < 2) {
+    usageFailure('task ref and intent are required');
+    return;
+  }
+  const [taskRef, intent] = args;
+  if (!['begin-or-resume', 'route', 'prepare', 'hook-start', 'stage-completed', 'hook-stop', 'advance', 'pause', 'status'].includes(intent!)) {
+    usageFailure(`unknown intent '${intent}'`);
+    return;
+  }
+  const values: Record<string, string> = {};
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (![
+      '--max-steps', '--client', '--requested-model', '--parent-id', '--before-fingerprint',
+      '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--fallback-reason',
+      '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent'
+    ].includes(flag)) {
+      usageFailure(`unknown option '${flag}'`);
+      return;
+    }
+    if (seen.has(flag)) {
+      usageFailure(`duplicate option '${flag}'`);
+      return;
+    }
+    seen.add(flag);
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      usageFailure(`option '${flag}' requires a value`);
+      return;
+    }
+    values[flag] = value;
+  }
+  const requireValues = (flags: string[]) => flags.find((flag) => values[flag] === undefined);
+  let result;
+  if (intent === 'begin-or-resume') {
+    const maxSteps = values['--max-steps'] === undefined ? undefined : Number(values['--max-steps']);
+    if (maxSteps !== undefined && (!Number.isInteger(maxSteps) || maxSteps < 1)) {
+      usageFailure('--max-steps must be a positive integer'); return;
+    }
+    result = beginOrResumeOrchestration(taskRef!, { maxSteps });
+  } else if (intent === 'route') {
+    result = routeOrchestration(taskRef!);
+  } else if (intent === 'status') {
+    result = statusOrchestration(taskRef!);
+  } else if (intent === 'prepare') {
+    const missing = requireValues(['--client']);
+    if (missing) { usageFailure(`intent 'prepare' requires '${missing}'`); return; }
+    result = prepareOrchestrationDelegation(taskRef!, {
+      client: values['--client'] as AgentClientId,
+      requestedModel: values['--requested-model']
+    });
+  } else if (intent === 'hook-start') {
+    const missing = requireValues([
+      ...(taskRef === 'auto' ? ['--client'] : []),
+      '--native-agent', '--child-id', '--parent-id', '--spawn-mode'
+    ]);
+    if (missing) { usageFailure(`intent 'hook-start' requires '${missing}'`); return; }
+    const event = {
+      nativeAgent: values['--native-agent']!, childId: values['--child-id']!,
+      parentId: values['--parent-id']!, spawnMode: values['--spawn-mode']!,
+      actualModel: values['--actual-model'], modelFallbackReason: values['--fallback-reason']
+    };
+    result = taskRef === 'auto'
+      ? activateMatchingOrchestrationDelegation(values['--client'] as AgentClientId, event)
+      : activateOrchestrationDelegation(taskRef!, event);
+  } else if (intent === 'hook-stop') {
+    if (taskRef === 'auto') {
+      const missing = requireValues(['--client', '--native-agent', '--child-id']);
+      if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
+      result = sealMatchingOrchestrationDelegation(values['--client'] as AgentClientId, {
+        nativeAgent: values['--native-agent']!, childId: values['--child-id']!
+      });
+    } else {
+      const missing = requireValues(['--child-id', '--exit-code', '--after-fingerprint']);
+      if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
+      const exitCode = Number(values['--exit-code']);
+      if (!Number.isInteger(exitCode)) { usageFailure('--exit-code must be an integer'); return; }
+      result = sealOrchestrationDelegation(taskRef!, {
+        childId: values['--child-id']!, exitCode,
+        afterFingerprint: values['--after-fingerprint']!,
+        changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : []
+      });
+    }
+  } else if (intent === 'stage-completed') {
+    const missing = requireValues(['--agent']);
+    if (missing) { usageFailure(`intent 'stage-completed' requires '${missing}'`); return; }
+    result = completeCommitOrchestrationStage(taskRef!, values['--agent']!);
+  } else if (intent === 'advance') {
+    result = advanceOrchestration(taskRef!);
+  } else {
+    const missing = requireValues(['--code', '--message', '--recoverable']);
+    if (missing) { usageFailure(`intent 'pause' requires '${missing}'`); return; }
+    if (!['true', 'false'].includes(values['--recoverable']!)) { usageFailure('--recoverable must be true or false'); return; }
+    result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true');
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskOrchestration };