@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/lib/internal/platform-issue.ts

@@ -0,0 +1,116 @@
+import path from 'node:path';
+
+import {
+  bindPlatformIssue,
+  createPlatformIssue,
+  inspectPlatformIssue,
+  syncPlatformIssue
+} from '../platform/issues.ts';
+import type { IssueResult } from '../platform/issues.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-issue inspect <task-ref> [--cwd <path>]
+       agent-infra-internal platform-issue create <task-ref> --agent <agent> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-issue bind <task-ref> --issue <N> --agent <agent> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-issue sync <task-ref> --agent <agent> [--status <suffix|none>] [--assignees current|none] [--milestone initial|specific|none] [--issue-type] [--fields] [--requirements] [--in-labels from-diff|none] [--base <branch>] [--state open|closed] [--close-reason completed|not_planned] [--dry-run] [--cwd <path>]
+`;
+
+const BOOLEAN_FLAGS = new Set(['--dry-run', '--issue-type', '--fields', '--requirements']);
+const VALUE_FLAGS = new Set([
+  '--cwd', '--agent', '--issue', '--status', '--assignees', '--milestone', '--in-labels', '--base', '--state', '--close-reason'
+]);
+
+function key(flag: string): string {
+  return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ISSUE_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(output: IssueResult): void {
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (output.status === 'failed') process.exitCode = 1;
+  if (output.status === 'blocked') process.exitCode = 2;
+}
+
+function parse(args: string[], start: number) {
+  const values: Record<string, string | boolean> = {};
+  const seen = new Set<string>();
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!BOOLEAN_FLAGS.has(flag) && !VALUE_FLAGS.has(flag)) return { values, error: `unknown option '${flag}'` };
+    if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
+    seen.add(flag);
+    if (BOOLEAN_FLAGS.has(flag)) { values[key(flag)] = true; continue; }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    values[key(flag)] = value;
+  }
+  return { values };
+}
+
+function oneOf(values: Record<string, string | boolean>, name: string, allowed: string[]): string | undefined {
+  const value = values[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !allowed.includes(value)) throw new Error(`--${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)} must be one of ${allowed.join('|')}`);
+  return value;
+}
+
+function platformIssue(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['inspect', 'create', 'bind', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  const taskRef = args[1];
+  if (!taskRef || taskRef.startsWith('--')) { fail(`${operation} requires a task ref`); return; }
+  const parsed = parse(args, 2);
+  if (parsed.error) { fail(parsed.error); return; }
+  const values = parsed.values;
+  const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
+  const allowed: Record<string, string[]> = {
+    inspect: ['cwd'], create: ['cwd', 'agent', 'dryRun'], bind: ['cwd', 'agent', 'dryRun', 'issue'],
+    sync: ['cwd', 'agent', 'dryRun', 'status', 'assignees', 'milestone', 'issueType', 'fields', 'requirements', 'inLabels', 'base', 'state', 'closeReason']
+  };
+  const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
+  if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
+  if (operation === 'inspect') { finish(inspectPlatformIssue(taskRef, { cwd })); return; }
+  if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
+  if (operation === 'create') {
+    finish(createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
+  }
+  if (operation === 'bind') {
+    const issue = Number(values.issue);
+    if (!Number.isInteger(issue) || issue <= 0) { fail('bind requires a positive --issue'); return; }
+    finish(bindPlatformIssue(taskRef, { cwd, agent: values.agent, issue, dryRun: values.dryRun === true })); return;
+  }
+  try {
+    const assignees = oneOf(values, 'assignees', ['current', 'none']);
+    const milestone = oneOf(values, 'milestone', ['initial', 'specific', 'none']);
+    const inLabels = oneOf(values, 'inLabels', ['from-diff', 'none']);
+    const state = oneOf(values, 'state', ['open', 'closed']);
+    const closeReason = oneOf(values, 'closeReason', ['completed', 'not_planned']);
+    if (inLabels === 'from-diff' && typeof values.base !== 'string') throw new Error('--in-labels from-diff requires --base');
+    if (inLabels !== 'from-diff' && values.base !== undefined) throw new Error('--base requires --in-labels from-diff');
+    if (closeReason && state !== 'closed') throw new Error('--close-reason requires --state closed');
+    const desiredKeys = ['status', 'assignees', 'milestone', 'issueType', 'fields', 'requirements', 'inLabels', 'state'];
+    if (!desiredKeys.some((name) => values[name] !== undefined)) throw new Error('sync requires at least one desired-state option');
+    finish(syncPlatformIssue(taskRef, {
+      cwd, agent: values.agent, dryRun: values.dryRun === true,
+      status: typeof values.status === 'string' ? values.status : undefined,
+      assignees: assignees as 'current' | 'none' | undefined,
+      milestone: milestone as 'initial' | 'specific' | 'none' | undefined,
+      issueType: values.issueType === true,
+      fields: values.fields === true,
+      requirements: values.requirements === true,
+      inLabels: inLabels as 'from-diff' | 'none' | undefined,
+      base: typeof values.base === 'string' ? values.base : undefined,
+      state: state as 'open' | 'closed' | undefined,
+      closeReason: closeReason as 'completed' | 'not_planned' | undefined
+    }));
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+export { platformIssue };

package/lib/internal/platform-pr.ts

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  bindPlatformPullRequest,
+  createPlatformPullRequest,
+  inspectPlatformPullRequest,
+  syncPlatformPullRequest
+} from '../platform/pull-requests.ts';
+import type { PullRequestResult } from '../platform/pull-requests.ts';
+import { summaryContext, syncPullRequestSummary } from '../platform/pr-summary.ts';
+import type { PlatformResult } from '../platform/types.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd <path>]
+       agent-infra-internal platform-pr create <task-ref> --agent <agent> --base <branch> --head <branch> --title-file <path|-> --body-file <path|-> [--draft] [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr bind <task-ref> --pr <N> --agent <agent> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr summary-context <task-ref> [--cwd <path>]
+       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> [--dry-run] [--cwd <path>]
+`;
+
+const BOOLEAN_FLAGS = new Set(['--draft', '--dry-run', '--metadata', '--closing-issue']);
+const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--pr']);
+
+function key(flag: string): string {
+  return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PR_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(output: PlatformResult | PullRequestResult): void {
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (output.status === 'failed') process.exitCode = 1;
+  if (output.status === 'blocked') process.exitCode = 2;
+}
+
+function parse(args: string[], start: number) {
+  const values: Record<string, string | boolean> = {};
+  const seen = new Set<string>();
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!BOOLEAN_FLAGS.has(flag) && !VALUE_FLAGS.has(flag)) return { values, error: `unknown option '${flag}'` };
+    if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
+    seen.add(flag);
+    if (BOOLEAN_FLAGS.has(flag)) { values[key(flag)] = true; continue; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    values[key(flag)] = value;
+  }
+  return { values };
+}
+
+function readFile(value: string, cwd: string): string {
+  return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
+}
+
+function platformPr(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['inspect', 'create', 'bind', 'sync', 'summary-context', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  const taskRef = args[1];
+  if (!taskRef || taskRef.startsWith('--')) { fail(`${operation} requires a task ref`); return; }
+  const parsed = parse(args, 2);
+  if (parsed.error) { fail(parsed.error); return; }
+  const values = parsed.values;
+  const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
+  const allowed: Record<string, string[]> = {
+    inspect: ['cwd'],
+    create: ['cwd', 'agent', 'base', 'head', 'titleFile', 'bodyFile', 'draft', 'dryRun'],
+    bind: ['cwd', 'agent', 'pr', 'dryRun'],
+    sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'dryRun'],
+    'summary-context': ['cwd'],
+    'summary-sync': ['cwd', 'agent', 'bodyFile', 'dryRun']
+  };
+  const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
+  if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
+  if (operation === 'inspect') { finish(inspectPlatformPullRequest(taskRef, { cwd })); return; }
+  if (operation === 'summary-context') { finish(summaryContext(taskRef, { cwd })); return; }
+  if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
+  if (operation === 'bind') {
+    const pr = Number(values.pr);
+    if (!Number.isInteger(pr) || pr <= 0) { fail('bind requires a positive --pr'); return; }
+    finish(bindPlatformPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
+    return;
+  }
+  if (operation === 'sync') {
+    if (values.metadata !== true && values.closingIssue !== true) { fail('sync requires --metadata or --closing-issue'); return; }
+    finish(syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, dryRun: values.dryRun === true }));
+    return;
+  }
+  if (operation === 'summary-sync') {
+    if (typeof values.bodyFile !== 'string') { fail('summary-sync requires --body-file'); return; }
+    try {
+      finish(syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), dryRun: values.dryRun === true }));
+    } catch (error) {
+      fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return;
+  }
+  if (typeof values.base !== 'string' || typeof values.head !== 'string' || typeof values.titleFile !== 'string' || typeof values.bodyFile !== 'string') {
+    fail('create requires --base, --head, --title-file and --body-file');
+    return;
+  }
+  try {
+    finish(createPlatformPullRequest(taskRef, {
+      cwd, agent: values.agent, base: values.base, head: values.head,
+      title: readFile(values.titleFile, cwd), body: readFile(values.bodyFile, cwd),
+      draft: values.draft === true, dryRun: values.dryRun === true
+    }));
+  } catch (error) {
+    fail(`unable to read PR payload file: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export { platformPr };

package/lib/internal/release-workflow.ts

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import semver from 'semver';
+
+import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.ts';
+import { inspectPlatformRelease, reconcileReleaseMilestones } from '../platform/releases.ts';
+import { inspectHomebrewChannel, inspectNpmChannel } from '../release/channels.ts';
+import { releaseSnapshot } from '../release/workflow.ts';
+import type { ReleaseFacts } from '../release/workflow.ts';
+
+function command(cwd: string, executable: string, args: string[]) {
+  return spawnSync(executable, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+type CommandResult = ReturnType<typeof command>;
+type CommandRunner = (cwd: string, executable: string, args: string[]) => CommandResult;
+type DemoResult = {
+  status: 'recorded' | 'skipped' | 'failed';
+  reasonCode: 'VHS_MISSING' | 'FFMPEG_MISSING' | 'DEMO_COMMAND_FAILED' | 'DEMO_OUTPUT_MISSING' | null;
+  message: string | null;
+  outputPath: string | null;
+};
+
+function runOptionalDemo(cwd: string, run: CommandRunner = command): DemoResult {
+  const vhs = run(cwd, 'vhs', ['--version']);
+  if (vhs.status !== 0) return { status: 'skipped', reasonCode: 'VHS_MISSING', message: null, outputPath: null };
+  const ffmpeg = run(cwd, 'ffmpeg', ['-version']);
+  if (ffmpeg.status !== 0) return { status: 'skipped', reasonCode: 'FFMPEG_MISSING', message: null, outputPath: null };
+  const demo = run(cwd, 'npm', ['run', 'demo:regen']);
+  if (demo.status !== 0) {
+    return {
+      status: 'failed',
+      reasonCode: 'DEMO_COMMAND_FAILED',
+      message: String(demo.stderr || demo.stdout),
+      outputPath: null
+    };
+  }
+  const outputPath = 'assets/demo-init.gif';
+  if (!fs.existsSync(path.join(cwd, outputPath))) {
+    return {
+      status: 'failed',
+      reasonCode: 'DEMO_OUTPUT_MISSING',
+      message: `${outputPath} was not generated`,
+      outputPath: null
+    };
+  }
+  return { status: 'recorded', reasonCode: null, message: null, outputPath };
+}
+
+function git(cwd: string, args: string[]): string | null {
+  const result = command(cwd, 'git', args);
+  return result.status === 0 ? String(result.stdout).trim() : 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 };
+  const tag = `v${version}`;
+  const branch = git(cwd, ['branch', '--show-current']) || '';
+  const head = git(cwd, ['rev-parse', 'HEAD']);
+  const localTagTarget = git(cwd, ['rev-parse', '--verify', `${tag}^{commit}`]);
+  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 });
+  const npm = await inspectNpmChannel(pkg.name, version);
+  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']) || '';
+  return {
+    localTag: Boolean(localTagTarget && localTagTarget === head),
+    localTagConflict: Boolean(localTagTarget && localTagTarget !== head),
+    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}`)
+  };
+}
+
+function changedPaths(cwd: string): string[] {
+  const output = git(cwd, ['status', '--porcelain=v1']) || '';
+  return output.split('\n').filter(Boolean).map((line) => line.slice(3)).filter((value, index, all) => all.indexOf(value) === index);
+}
+
+function updateReleaseMetadata(cwd: string, version: string): void {
+  const [major = '0', minor = '0'] = version.split('.');
+  const aircPath = path.join(cwd, '.agents', '.airc.json');
+  const airc = JSON.parse(fs.readFileSync(aircPath, 'utf8')) as Record<string, unknown>;
+  fs.writeFileSync(aircPath, `${JSON.stringify({ ...airc, templateVersion: `v${version}` }, null, 2)}\n`);
+  for (const [fileName, supported, unsupported] of [
+    ['SECURITY.md', `| v${major}.${minor}.x   | Supported             |`, `| < v${major}.${minor}.0 | Not Supported         |`],
+    ['SECURITY.zh-CN.md', `| v${major}.${minor}.x   | 支持中                |`, `| < v${major}.${minor}.0 | 不再支持              |`]
+  ] as const) {
+    const filePath = path.join(cwd, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    const content = fs.readFileSync(filePath, 'utf8')
+      .replace(/^\| v\d+\.\d+\.x\s+\| (?:Supported|支持中)\s+\|$/m, supported)
+      .replace(/^\| < v\d+\.\d+\.0\s+\| (?:Not Supported|不再支持)\s+\|$/m, unsupported);
+    fs.writeFileSync(filePath, content);
+  }
+}
+
+async function releaseWorkflow(args: string[] = []): Promise<void> {
+  const [action, rawVersion, ...rest] = args;
+  const version = String(rawVersion || '').replace(/^v/, '');
+  const cwdIndex = rest.indexOf('--cwd');
+  const cwd = path.resolve(cwdIndex >= 0 && rest[cwdIndex + 1] ? rest[cwdIndex + 1]! : process.cwd());
+  if (!['inspect', 'prepare', 'publish', 'post'].includes(action || '') || !semver.valid(version)) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'RELEASE_INPUT_INVALID', message: 'Usage: release-workflow inspect|prepare|publish|post <version>' } })}\n`);
+    process.exitCode = 1; return;
+  }
+  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 (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`);
+      process.exitCode = milestones.status === 'failed' ? 1 : milestones.status === 'blocked' ? 2 : 0;
+      return;
+    }
+    const entropyIndex = rest.indexOf('--entropy-report');
+    const entropy = entropyIndex >= 0 ? rest[entropyIndex + 1] : null;
+    if (!entropy || !fs.existsSync(path.resolve(cwd, entropy))) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'ENTROPY_REPORT_REQUIRED', message: '--entropy-report must reference an existing report' } })}\n`); process.exitCode = 1; return; }
+    const entropyContent = fs.readFileSync(path.resolve(cwd, entropy), 'utf8');
+    const blockingCount = Number(/^\|\s*release-blocking\s*\|\s*(\d+)\s*\|/m.exec(entropyContent)?.[1] ?? NaN);
+    if (!Number.isFinite(blockingCount) || blockingCount > 0) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'ENTROPY_REPORT_BLOCKING', message: 'Entropy report is invalid or contains release-blocking findings' } })}\n`); process.exitCode = 1; return; }
+    const inspected = inspectGitWorkflow(cwd);
+    if (!inspected.snapshot || inspected.snapshot.worktree.length || inspected.snapshot.staged.length) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, snapshot: before, error: { code: 'WORKTREE_DIRTY', message: 'Release prepare requires a clean worktree' } })}\n`); process.exitCode = 1; return; }
+    for (const [exe, commandArgs] of [['npm', ['test']], ['npm', ['version', version, '--no-git-tag-version']], ['npm', ['install', '--package-lock-only']], [process.execPath, ['scripts/build-inline.js']]] as Array<[string, string[]]>) {
+      if (exe === process.execPath) updateReleaseMetadata(cwd, version);
+      const result = command(cwd, exe, commandArgs); if (result.status !== 0) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_PREPARE_COMMAND_FAILED', message: String(result.stderr || result.stdout) } })}\n`); process.exitCode = 1; return; }
+    }
+    const committed = commitExplicitPaths({ cwd, paths: changedPaths(cwd), message: `chore: release v${version}` });
+    if (committed.status === 'failed') { process.stdout.write(`${JSON.stringify(committed)}\n`); process.exitCode = 1; return; }
+    const tagged = command(cwd, 'git', ['tag', '-a', `v${version}`, '-m', `Release v${version}`]);
+    const milestones = tagged.status === 0 ? reconcileReleaseMilestones(version, { cwd }) : null;
+    const snapshot = releaseSnapshot(version, await inspectFacts(cwd, version));
+    const failed = tagged.status !== 0 || milestones?.status === 'failed';
+    const blocked = milestones?.status === 'blocked';
+    const status = failed ? 'failed' : blocked ? 'blocked' : 'applied';
+    process.stdout.write(`${JSON.stringify({ status, changed: true, snapshot, operations: milestones?.operations ?? [], error: tagged.status !== 0 ? { code: 'GIT_TAG_FAILED', message: String(tagged.stderr) } : milestones?.error ?? null })}\n`);
+    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; }
+    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;
+  }
+  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 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`);
+    process.exitCode = 1; return;
+  }
+  const demo = runOptionalDemo(cwd);
+  if (demo.status === 'failed') {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, demo, error: { code: 'RELEASE_POST_DEMO_FAILED', message: demo.message } })}\n`);
+    process.exitCode = 1; return;
+  }
+  for (const [exe, commandArgs] of [['npm', ['version', 'prerelease', '--preid=alpha', '--no-git-tag-version']], ['npm', ['install', '--package-lock-only']], [process.execPath, ['scripts/build-inline.js']]] as Array<[string, string[]]>) {
+    const result = command(cwd, exe, commandArgs); if (result.status !== 0) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: true, snapshot: before, error: { code: 'RELEASE_POST_COMMAND_FAILED', message: String(result.stderr || result.stdout) } })}\n`); process.exitCode = 1; return; }
+  }
+  const committed = commitExplicitPaths({ cwd, paths: changedPaths(cwd), message: `chore: prepare next dev iteration after v${version}` });
+  if (committed.status === 'failed') { process.stdout.write(`${JSON.stringify(committed)}\n`); process.exitCode = 1; return; }
+  const branch = git(cwd, ['branch', '--show-current']) || '';
+  const pushed = pushGitRefs({ cwd, remote: 'origin', refs: [branch] });
+  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 { inspectFacts, releaseWorkflow, runOptionalDemo };
+export type { CommandRunner, DemoResult };

package/lib/internal/task-artifact.ts

@@ -0,0 +1,47 @@
+import { resolveArtifactContext } from '../task/artifact-lifecycle.ts';
+
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n\nInspect one workflow artifact family and print a read-only JSON context.\n`;
+
+function failUsage(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 2;
+}
+
+function taskArtifact(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args.length < 2) { failUsage('task ref and operation are required'); return; }
+  if (args[1] !== 'inspect') { failUsage(`unknown operation '${args[1]}'`); return; }
+  let family = '';
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag !== '--family') { failUsage(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { failUsage(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) { failUsage(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    family = value;
+  }
+  if (!family) { failUsage("option '--family' is required"); return; }
+  const result = resolveArtifactContext(args[0]!, family);
+  const output = family === 'code' && result.codeMode ? {
+    ...result,
+    mode: result.codeMode.mode,
+    code_max: result.codeMode.codeMax,
+    rev_max: result.codeMode.reviewMax,
+    verdict: result.codeMode.verdict,
+    next_round: result.next?.round ?? null,
+    next_artifact: result.next?.name ?? null,
+    review_artifact: result.codeMode.reviewArtifact,
+    implementation_input: result.codeMode.implementationInput,
+    decision_id: result.codeMode.decisionId,
+    decision_evidence: result.codeMode.decisionEvidence,
+    message: result.codeMode.message
+  } : result;
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (result.status === 'refused') process.exitCode = 1;
+  else if (result.status === 'failed') process.exitCode = 2;
+}
+
+export { taskArtifact };

package/lib/internal/task-context.ts

@@ -0,0 +1,35 @@
+import { parseTaskScope } from '../task/command-options.ts';
+import { resolveTaskContext } from '../task/resolve-ref.ts';
+
+const USAGE = `Usage: agent-infra-internal task-context resolve [<task-ref> | --task <task-ref> | -t <task-ref>]\n`;
+
+function fail(code: string, message: string, usage = false): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code, message } })}\n`);
+  if (usage) process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskContext(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args[0] !== 'resolve') { fail('TASK_CONTEXT_PAYLOAD_INVALID', "operation 'resolve' is required", true); return; }
+  let scope;
+  try {
+    scope = parseTaskScope(args.slice(1));
+  } catch (error) {
+    fail('TASK_CONTEXT_PAYLOAD_INVALID', error instanceof Error ? error.message : String(error), true);
+    return;
+  }
+  if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
+    fail('TASK_CONTEXT_PAYLOAD_INVALID', 'task ref must be provided once', true);
+    return;
+  }
+  const taskRef = scope.taskRef ?? scope.positionals[0];
+  const result = resolveTaskContext(taskRef);
+  if (!result.ok) { fail(result.code, result.message); return; }
+  process.stdout.write(`${JSON.stringify({
+    status: 'resolved', changed: false, taskId: result.taskId, taskDir: result.taskDir,
+    taskMdPath: result.taskMdPath, taskState: result.state, error: null
+  })}\n`);
+}
+
+export { taskContext };

package/lib/internal/task-event.ts

@@ -0,0 +1,51 @@
+import { applyTaskEvent, eventCatalog } from '../task/events.ts';
+import type { TaskEventRequest, Verdict } from '../task/events.ts';
+
+const USAGE = `Usage: agent-infra-internal task-event <N | TASK-id> <event> --agent <agent> [event options] [--dry-run]
+
+Apply one closed-set task lifecycle event and print a structured JSON result.
+Events: ${eventCatalog.join(', ')}
+`;
+
+const FLAGS: Record<string, keyof TaskEventRequest> = {
+  '--agent': 'agent', '--round': 'round', '--question': 'question', '--artifact': 'artifact',
+  '--fix-for': 'fixFor', '--implementation-input': 'implementationInput',
+  '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
+  '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
+  '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult'
+};
+const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'EVENT_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskEvent(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args.length < 2) { usageFailure('task ref and event are required'); return; }
+  const request: TaskEventRequest = { taskRef: args[0]!, event: args[1]!, agent: '' };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); request.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    if (NUMERIC.has(key)) (request as Record<string, unknown>)[key] = Number(value);
+    else if (key === 'verdict') request.verdict = value as Verdict;
+    else (request as Record<string, unknown>)[key] = value;
+  }
+  const result = applyTaskEvent(request);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskEvent };

package/lib/internal/task-ledger.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+
+import { applyLedgerIntent } from '../task/ledger-intents.ts';
+import type { LedgerIntent } from '../task/ledger-intents.ts';
+import { isReviewStage, parseLedger, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+
+const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, stage-status\n`;
+const FLAGS: Record<string, string> = {
+  '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
+  '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
+  '--status': 'status', '--artifact': 'artifact'
+};
+const NUMERIC = new Set(['ordinal', 'round']);
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LEDGER_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskLedger(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const [taskRef, kind] = args;
+  if (!taskRef || !kind) { usageFailure('task ref and intent are required'); return; }
+  if (!['finding-upsert', 'finding-respond', 'finding-review', 'decision-next-id', 'decision-upsert', 'stage-status'].includes(kind)) {
+    usageFailure(`unknown ledger intent '${kind}'`); return;
+  }
+  const values: Record<string, unknown> = { kind, taskRef };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); values.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag); values[key] = NUMERIC.has(key) ? Number(value) : value;
+  }
+  const required: Record<string, string[]> = {
+    'finding-upsert': ['stage', 'reviewArtifact', 'ordinal', 'severity', 'evidence'],
+    'finding-respond': ['id', 'round', 'status', 'evidence'],
+    'finding-review': ['id', 'status', 'evidence'],
+    'decision-next-id': [],
+    'decision-upsert': ['id', 'stage', 'artifact'],
+    'stage-status': ['stage']
+  };
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!]);
+  const unexpected = Object.keys(values).find((key) => !allowed.has(key));
+  const missing = required[kind]!.find((key) => values[key] === undefined);
+  if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
+  if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
+  if (kind === 'stage-status') {
+    if (!isReviewStage(String(values.stage))) { usageFailure(`stage-status requires a valid review stage`); return; }
+    const resolved = resolveTaskRef(taskRef);
+    if (!resolved.ok || resolved.state !== 'active') {
+      const message = resolved.ok ? `task ${resolved.taskId} is ${resolved.state}, expected active` : resolved.message;
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.ok ? 'TASK_STATE_MISMATCH' : resolved.code, message } })}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const rows = parseLedger(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+      const invalid = validateLedgerRows(rows);
+      if (invalid) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: invalid })}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      process.stdout.write(`${JSON.stringify({ status: 'ready', changed: false, taskId: resolved.taskId, stageStatus: summarizeLedgerStage(rows, values.stage as 'analysis' | 'plan' | 'code'), error: null })}\n`);
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: { code: 'LEDGER_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) } })}\n`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const result = applyLedgerIntent(values as LedgerIntent);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskLedger };