@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/internal/platform-pr.ts

@@ -1,10 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   bindPlatformPullRequest,
   createPlatformPullRequest,
   inspectPlatformPullRequest,
+  resolveExternalPullRequest,
   syncPlatformPullRequest
 } from '../platform/pull-requests.ts';
 import type { PullRequestResult } from '../platform/pull-requests.ts';
@@ -12,6 +14,7 @@ import { summaryContext, syncPullRequestSummary } from '../platform/pr-summary.t
 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 resolve-external <task-ref> --agent <agent> [--pr <N>] [--dry-run] [--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>]
@@ -61,7 +64,7 @@ function readFile(value: string, cwd: string): string {
 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; }
+  if (!operation || !['inspect', 'resolve-external', '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);
@@ -70,6 +73,7 @@ function platformPr(args: string[] = []): void {
   const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
   const allowed: Record<string, string[]> = {
     inspect: ['cwd'],
+    'resolve-external': ['cwd', 'agent', 'pr', 'dryRun'],
     create: ['cwd', 'agent', 'base', 'head', 'titleFile', 'bodyFile', 'draft', 'dryRun'],
     bind: ['cwd', 'agent', 'pr', 'dryRun'],
     sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'dryRun'],
@@ -81,6 +85,15 @@ function platformPr(args: string[] = []): void {
   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; }
+  const agent = normalizeAgentToken(values.agent);
+  if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
+  values.agent = agent;
+  if (operation === 'resolve-external') {
+    const pr = values.pr === undefined ? undefined : Number(values.pr);
+    if (pr !== undefined && (!Number.isInteger(pr) || pr <= 0)) { fail('resolve-external requires a positive --pr'); return; }
+    finish(resolveExternalPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
+    return;
+  }
   if (operation === 'bind') {
     const pr = Number(values.pr);
     if (!Number.isInteger(pr) || pr <= 0) { fail('bind requires a positive --pr'); return; }

package/lib/internal/platform-release-notes.ts

@@ -1,11 +1,34 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { publishReleaseNotes, releaseNoteContext } from '../platform/release-notes.ts';
+import { publishReleaseNotes, releaseNoteContext, stageReleaseNotes } from '../platform/release-notes.ts';
 
-function option(args: string[], name: string): string | null {
-  const index = args.indexOf(name);
-  return index >= 0 && args[index + 1] ? args[index + 1]! : null;
+type ParsedOptions = Readonly<{ values: ReadonlyMap<string, string>; switches: ReadonlySet<string> }>;
+
+function parseOptions(
+  args: string[],
+  valueFlags: readonly string[],
+  switchFlags: readonly string[] = []
+): ParsedOptions | null {
+  const values = new Map<string, string>();
+  const switches = new Set<string>();
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (values.has(flag) || switches.has(flag)) return null;
+    if (switchFlags.includes(flag)) {
+      switches.add(flag);
+      continue;
+    }
+    if (!valueFlags.includes(flag)) return null;
+    const value = args[++index];
+    if (!value || value.startsWith('--')) return null;
+    values.set(flag, value);
+  }
+  return { values, switches };
+}
+
+function invalidInput(message: string) {
+  return { status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message, retryable: false } };
 }
 
 function finish(result: { status: string; [key: string]: unknown }): void {
@@ -15,21 +38,40 @@ function finish(result: { status: string; [key: string]: unknown }): void {
 
 function platformReleaseNotes(args: string[] = []): void {
   const [action, ...rest] = args;
-  const cwd = path.resolve(option(rest, '--cwd') || process.cwd());
   if (action === 'context') {
-    const historyRaw = option(rest, '--history-limit');
+    const parsed = parseOptions(rest, ['--cwd', '--history-limit', '--from-tag', '--to-tag', '--branch']);
+    if (!parsed) return finish(invalidInput('invalid context options'));
+    const cwd = path.resolve(parsed.values.get('--cwd') || process.cwd());
+    const historyRaw = parsed.values.get('--history-limit') ?? null;
     finish(releaseNoteContext({
-      fromTag: option(rest, '--from-tag') || '',
-      toTag: option(rest, '--to-tag') || '',
-      branch: option(rest, '--branch') || '',
+      fromTag: parsed.values.get('--from-tag') || '',
+      toTag: parsed.values.get('--to-tag') || '',
+      branch: parsed.values.get('--branch') || '',
       historyLimit: historyRaw === null ? undefined : Number(historyRaw)
     }, { cwd }));
     return;
   }
+  if (action === 'stage') {
+    const parsed = parseOptions(rest, ['--cwd', '--notes-file']);
+    if (!parsed) return finish(invalidInput('invalid stage options'));
+    const notesFile = parsed.values.get('--notes-file');
+    if (!notesFile) return finish(invalidInput('notes-file is required'));
+    finish(stageReleaseNotes(
+      { notesFile },
+      { cwd: path.resolve(parsed.values.get('--cwd') || process.cwd()) }
+    ));
+    return;
+  }
   if (action === 'publish') {
-    const notesPath = option(rest, '--notes-file');
+    const parsed = parseOptions(
+      rest,
+      ['--cwd', '--notes-file', '--tag', '--title', '--expected-sha256'],
+      ['--dry-run']
+    );
+    if (!parsed) return finish(invalidInput('invalid publish options'));
+    const notesPath = parsed.values.get('--notes-file');
     if (!notesPath) {
-      finish({ status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'notes-file is required', retryable: false } });
+      finish(invalidInput('notes-file is required'));
       return;
     }
     let resolvedNotesPath = notesPath;
@@ -39,17 +81,18 @@ function platformReleaseNotes(args: string[] = []): void {
     }
     try {
       finish(publishReleaseNotes({
-        tag: option(rest, '--tag') || '',
-        title: option(rest, '--title') || option(rest, '--tag') || '',
+        tag: parsed.values.get('--tag') || '',
+        title: parsed.values.get('--title') || parsed.values.get('--tag') || '',
         notesFile: resolvedNotesPath,
-        dryRun: rest.includes('--dry-run')
-      }, { cwd }));
+        expectedSha256: parsed.values.get('--expected-sha256') || '',
+        dryRun: parsed.switches.has('--dry-run')
+      }, { cwd: path.resolve(parsed.values.get('--cwd') || process.cwd()) }));
     } finally {
       if (notesPath === '-') fs.rmSync(resolvedNotesPath, { force: true });
     }
     return;
   }
-  finish({ status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'Usage: platform-release-notes context|publish', retryable: false } });
+  finish(invalidInput('Usage: platform-release-notes context|stage|publish'));
 }
 
 export { platformReleaseNotes };

package/lib/internal/pr-review-grade.ts

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  collectHostCandidates,
+  decide,
+  deriveTaskIssueMatches,
+  extractClosingIssueNumbers,
+  resolveHostFromCandidates
+} from '../pr-review/evidence-grading.ts';
+import type { DecisionRecord, HostResolution } from '../pr-review/evidence-grading.ts';
+import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.ts';
+import { verifyInProcess } from '../task/verification-engine.ts';
+
+const USAGE = `Usage: agent-infra-internal pr-review-grade decide --input-file <path|-> [--cwd <path>]
+       agent-infra-internal pr-review-grade resolve-host --pr <N> [--cwd <path>]
+       agent-infra-internal pr-review-grade verify-artifact --artifact-file <path> [--cwd <path>]
+`;
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PR_REVIEW_GRADE_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(result: unknown, exitCode = 0): void {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (exitCode !== 0) process.exitCode = exitCode;
+}
+
+function parseFlags(args: string[], start: number): { values: Record<string, string | boolean>; error?: string } {
+  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 (!['--input-file', '--artifact-file', '--cwd', '--pr'].includes(flag)) {
+      return { values, error: `unknown option '${flag}'` };
+    }
+    if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
+    seen.add(flag);
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    values[flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())] = value;
+  }
+  return { values };
+}
+
+function readInput(value: string, cwd: string): string {
+  return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
+}
+
+function prReviewGrade(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['decide', 'resolve-host', 'verify-artifact'].includes(operation)) { fail('a valid operation is required'); return; }
+  const parsed = parseFlags(args, 1);
+  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[]> = {
+    decide: ['cwd', 'inputFile'],
+    'resolve-host': ['cwd', 'pr'],
+    'verify-artifact': ['cwd', 'artifactFile']
+  };
+  const unexpected = Object.keys(values).find((key) => !allowed[operation]!.includes(key));
+  if (unexpected) { fail(`${operation} does not accept '--${unexpected}'`); return; }
+
+  if (operation === 'decide') {
+    if (typeof values.inputFile !== 'string') { fail('decide requires --input-file'); return; }
+    let input: unknown;
+    try {
+      input = JSON.parse(readInput(values.inputFile, cwd));
+    } catch (error) {
+      fail(`unable to read decide input: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    try {
+      const record: DecisionRecord = decide(input as Parameters<typeof decide>[0]);
+      finish(record);
+    } catch (error) {
+      const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : 'DECIDE_FAILED';
+      finish({ status: 'failed', changed: false, error: { code, message: error instanceof Error ? error.message : String(error) } }, 1);
+    }
+    return;
+  }
+
+  if (operation === 'resolve-host') {
+    const pr = Number(values.pr);
+    if (!Number.isInteger(pr) || pr <= 0) { fail('resolve-host requires a positive --pr'); return; }
+    const inspected = inspectPlatformPullRequestByNumber(pr, { cwd });
+    if (!inspected.pullRequest) {
+      finish({
+        status: 'failed', changed: false, host: null, candidates: [], closingIssues: [],
+        error: inspected.error ?? { code: 'PR_INSPECTION_INVALID', message: 'unable to inspect the pull request', retryable: false }
+      }, inspected.status === 'blocked' ? 2 : 1);
+      return;
+    }
+    const closingIssues = extractClosingIssueNumbers(inspected.pullRequest.body);
+    const candidates = collectHostCandidates({ prNumber: pr, closingIssues, workspaceRoot: cwd });
+    const host: HostResolution = resolveHostFromCandidates(candidates);
+    finish({
+      status: 'ok', changed: false,
+      pr: { number: pr, baseSha: inspected.pullRequest.base.sha, headSha: inspected.pullRequest.head.sha, state: inspected.pullRequest.state },
+      closingIssues, candidates, host,
+      taskIssueMatches: deriveTaskIssueMatches(host, closingIssues), error: null
+    });
+    return;
+  }
+
+  if (typeof values.artifactFile !== 'string') { fail('verify-artifact requires --artifact-file'); return; }
+  const artifactPath = path.resolve(cwd, values.artifactFile);
+  let result: Record<string, unknown>;
+  try {
+    result = verifyInProcess({
+      mode: 'checks',
+      skillName: 'review-pr',
+      taskDir: path.dirname(artifactPath),
+      artifactFile: path.basename(artifactPath),
+      checks: ['artifact'],
+      repositoryRoot: cwd
+    }) as Record<string, unknown>;
+  } catch (error) {
+    finish({ status: 'failed', changed: false, error: { code: 'VERIFY_ARTIFACT_INVALID', message: error instanceof Error ? error.message : String(error) } }, 1);
+    return;
+  }
+  const status = result.status as 'pass' | 'fail' | 'blocked';
+  finish(result, ({ pass: 0, fail: 1, blocked: 2 } as const)[status]);
+}
+
+export { prReviewGrade };

package/lib/internal/release-workflow.ts

@@ -150,9 +150,57 @@ 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);
-  return result.status === 0 ? String(result.stdout).trim() : null;
+function git(cwd: string, args: string[], run: CommandRunner = command, trim = true): string | null {
+  const result = run(cwd, 'git', args);
+  const stdout = String(result.stdout);
+  return result.status === 0 ? (trim ? stdout.trim() : stdout) : 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> {
@@ -162,6 +210,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,24 +218,26 @@ 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
   };
 }
 
-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 parsePorcelainPath(record: string): string {
+  const match = /^.. (.+)$/.exec(record);
+  if (!match) throw new Error('Invalid git status --porcelain=v1 record');
+  return match[1]!;
+}
+
+function changedPaths(cwd: string, run: CommandRunner = command): string[] {
+  const output = git(cwd, ['status', '--porcelain=v1'], run, false) || '';
+  return output.split(/\r?\n/).filter(Boolean).map(parsePorcelainPath).filter((value, index, all) => all.indexOf(value) === index);
 }
 
 function updateReleaseMetadata(cwd: string, version: string): void {
@@ -218,12 +269,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 +304,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 +343,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 { changedPaths, computeDemoInputDigest, inspectFacts, inspectLocalReleaseFacts, inspectPostWorktree, releaseSmokeStatus, releaseWorkflow, runOptionalDemo };
 export type { CommandRunner, DemoResult };

package/lib/internal/task-activity.ts

@@ -0,0 +1,55 @@
+import { applyActivityAppendIntent } from '../task/activity-intent.ts';
+import type { ActivityAppendIntent } from '../task/activity-intent.ts';
+
+const USAGE = `Usage: agent-infra-internal task-activity <task-ref> append --step <step> --agent <agent> --note <note> [--artifact <canonical.md>] [--dry-run]
+`;
+const FLAGS: Record<string, string> = {
+  '--step': 'step',
+  '--agent': 'agent',
+  '--note': 'note',
+  '--artifact': 'artifact'
+};
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ACTIVITY_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskActivity(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const [taskRef, kind] = args;
+  if (!taskRef || taskRef.startsWith('--') || !kind || kind !== 'append') {
+    usageFailure('task ref and the append intent are required');
+    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] = value;
+  }
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', 'step', 'agent', 'note', 'artifact']);
+  const unexpected = Object.keys(values).find((key) => !allowed.has(key));
+  if (unexpected) { usageFailure(`append does not accept '${unexpected}'`); return; }
+  for (const key of ['step', 'agent', 'note']) {
+    if (values[key] === undefined) { usageFailure(`append requires '${key}'`); return; }
+  }
+  const result = applyActivityAppendIntent(values as ActivityAppendIntent);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskActivity };

package/lib/internal/task-event.ts

@@ -1,7 +1,8 @@
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 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]
+const USAGE = `Usage: agent-infra-internal task-event <N | TASK-id> <event> --agent <agent> [event options] [--orchestrated] [--dry-run]
 
 Apply one closed-set task lifecycle event and print a structured JSON result.
 Events: ${eventCatalog.join(', ')}
@@ -29,6 +30,10 @@ function taskEvent(args: string[] = []): void {
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
+    if (flag === '--orchestrated') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); request.orchestrated = true; continue;
+    }
     if (flag === '--dry-run') {
       if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
       seen.add(flag); request.dryRun = true; continue;
@@ -43,6 +48,9 @@ function taskEvent(args: string[] = []): void {
     else if (key === 'verdict') request.verdict = value as Verdict;
     else (request as Record<string, unknown>)[key] = value;
   }
+  const agent = normalizeAgentToken(String(request.agent ?? ''));
+  if (!agent) { usageFailure(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`); return; }
+  request.agent = agent;
   const result = applyTaskEvent(request);
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;

package/lib/internal/task-lifecycle.ts

@@ -1,3 +1,4 @@
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.ts';
 import type { TaskLifecycleRequest } from '../task/lifecycle.ts';
 
@@ -33,6 +34,9 @@ function taskLifecycle(args: string[] = []): void {
     seen.add(flag);
     values[key] = key === 'alertNumber' || key === 'issueNumber' ? Number(value) : value;
   }
+  const agent = normalizeAgentToken(String(values.agent ?? ''));
+  if (!agent) { usageFailure(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
+  values.agent = agent;
   const result = applyTaskLifecycle(values as TaskLifecycleRequest);
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;