@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/lib/decide.ts

@@ -1,10 +1,7 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { execFileSync } from 'node:child_process';
 import { VERSION } from './version.ts';
-import { resolveTaskRef } from './task/resolve-ref.ts';
-
-const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+import { parseTaskScope } from './task/command-options.ts';
+import { applyHumanDecision } from './task/decision-intents.ts';
+import { canonicalTimestamp } from './task/write.ts';
 
 type DecideOptions = {
   repoRoot?: string;
@@ -12,106 +9,69 @@ type DecideOptions = {
   version?: string;
 };
 
-function detectRepoRoot(): string {
-  return execFileSync('git', ['rev-parse', '--show-toplevel'], {
-    encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'pipe']
-  }).trim();
-}
-
-function defaultNow(): string {
-  return new Intl.DateTimeFormat('sv-SE', {
-    timeZoneName: 'longOffset',
-    year: 'numeric',
-    month: '2-digit',
-    day: '2-digit',
-    hour: '2-digit',
-    minute: '2-digit',
-    second: '2-digit',
-    hour12: false
-  })
-    .format(new Date())
-    .replace(' GMT', '');
-}
-
-function taskPath(repoRoot: string, ref: string): string {
-  if (!TASK_ID_RE.test(ref)) {
-    const resolved = resolveTaskRef(ref);
-    if (!resolved.ok) throw new Error(resolved.message);
-    if (!resolved.taskDir.includes(`${path.join('.agents', 'workspace', 'active')}${path.sep}`)) {
-      throw new Error(`task ${resolved.taskId} is not active`);
+function parseDecisionParts(parts: string[]): { decision: string; needsImplementation: boolean | undefined } {
+  const decision: string[] = [];
+  let needsImplementation: boolean | undefined;
+  for (let index = 0; index < parts.length; index += 1) {
+    if (parts[index] !== '--needs-implementation') {
+      decision.push(parts[index]!);
+      continue;
+    }
+    if (needsImplementation !== undefined) throw new Error("duplicate option '--needs-implementation'");
+    const value = parts[++index];
+    if (value !== 'true' && value !== 'false') {
+      throw new Error("--needs-implementation must be 'true' or 'false'");
     }
-    return resolved.taskMdPath;
+    needsImplementation = value === 'true';
   }
-  const candidate = path.join(repoRoot, '.agents', 'workspace', 'active', ref, 'task.md');
-  if (!fs.existsSync(candidate)) throw new Error(`active task not found: ${ref}`);
-  return candidate;
-}
-
-function replaceFrontmatterField(content: string, field: string, value: string): string {
-  const re = new RegExp(`^${field}:.*$`, 'm');
-  if (re.test(content)) return content.replace(re, `${field}: ${value}`);
-  return content.replace(/^---\n/, `---\n${field}: ${value}\n`);
+  if (decision.length === 0) throw new Error('decision content is required');
+  return { decision: decision.join(' '), needsImplementation };
 }
 
-function replaceLedgerRow(content: string, hdId: string): { content: string; found: boolean; pending: boolean } {
-  const lines = content.split('\n');
-  let found = false;
-  let pending = false;
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i] as string;
-    if (!line.trim().startsWith(`| ${hdId} |`)) continue;
-    found = true;
-    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim());
-    if (cells[4] !== 'needs-human-decision') break;
-    pending = true;
-    cells[4] = 'human-decided';
-    cells[5] = `task.md#${hdId}`;
-    lines[i] = `| ${cells.join(' | ')} |`;
-    break;
+export async function decide(args: string[], options: DecideOptions = {}): Promise<number> {
+  let scope;
+  try { scope = parseTaskScope(args); } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`); return 1;
   }
-  return { content: lines.join('\n'), found, pending };
-}
-
-function appendUnderHeading(content: string, heading: string, block: string): string {
-  if (!content.includes(`${heading}\n`)) {
-    return `${content.trimEnd()}\n\n${heading}\n\n${block}\n`;
+  let item: string | undefined;
+  const operands: string[] = [];
+  for (let index = 0; index < scope.positionals.length; index += 1) {
+    const arg = scope.positionals[index]!;
+    if (arg === '--item' || arg === '-i') {
+      if (item !== undefined) { process.stderr.write("Error: duplicate option '--item'\n"); return 1; }
+      item = scope.positionals[++index];
+      if (!item) { process.stderr.write(`Error: ${arg} requires a value\n`); return 1; }
+    } else if (arg.startsWith('--item=')) {
+      if (item !== undefined) { process.stderr.write("Error: duplicate option '--item'\n"); return 1; }
+      item = arg.slice('--item='.length);
+      if (item === '') { process.stderr.write('Error: --item requires a value\n'); return 1; }
+    } else operands.push(arg);
   }
-  const idx = content.indexOf(`${heading}\n`) + heading.length + 1;
-  const before = content.slice(0, idx);
-  const after = content.slice(idx);
-  return `${before}\n${block}\n${after.replace(/^\n/, '')}`;
-}
-
-export async function decide(args: string[], options: DecideOptions = {}): Promise<number> {
-  const [taskRef, hdId, ...decisionParts] = args;
-  if (!taskRef || !hdId || decisionParts.length === 0) {
-    process.stderr.write('Usage: ai decide <task-ref> <HD-id> <decision>\n');
+  let taskRef = scope.taskRef;
+  let selector = item;
+  let decisionParts: string[];
+  if (item !== undefined) {
+    decisionParts = operands;
+  } else if (!scope.explicit) {
+    [taskRef, selector, ...decisionParts] = operands;
+  } else {
+    decisionParts = [];
+  }
+  if (!selector || decisionParts.length === 0) {
+    process.stderr.write('Usage: ai decide [--task <ref>] --item <ordinal|ledger-id> [--needs-implementation true|false] <decision>\n       ai decide <task-ref> <ordinal|ledger-id> [--needs-implementation true|false] <decision>\n');
     return 1;
   }
   try {
-    const repoRoot = options.repoRoot ?? detectRepoRoot();
-    const file = taskPath(repoRoot, taskRef);
-    let content = fs.readFileSync(file, 'utf8');
-    const replaced = replaceLedgerRow(content, hdId);
-    if (!replaced.found) throw new Error(`${hdId} not found in review ledger`);
-    if (!replaced.pending) throw new Error(`${hdId} is not needs-human-decision`);
-    content = replaced.content;
-    const now = (options.now ?? defaultNow)();
-    content = replaceFrontmatterField(content, 'updated_at', now);
-    content = replaceFrontmatterField(content, 'agent_infra_version', options.version ?? VERSION);
-    const decision = decisionParts.join(' ');
-    content = appendUnderHeading(
-      content,
-      '## 人工裁决',
-      `### ${hdId}\n\n- **裁决时间**：${now}\n- **裁决结果**：${decision}`
-    );
-    content = appendUnderHeading(
-      content,
-      '## 活动日志',
-      `- ${now} — **Human Decision** by human — ${hdId} decided`
-    );
-    fs.writeFileSync(file, content);
+    const parsedDecision = parseDecisionParts(decisionParts);
+    const now = (options.now ?? canonicalTimestamp)();
+    const result = applyHumanDecision({
+      taskRef, selector, decision: parsedDecision.decision,
+      needsImplementation: parsedDecision.needsImplementation
+    }, {
+      repoRoot: options.repoRoot,
+      metadataProvider: () => ({ timestamp: now, agentInfraVersion: options.version ?? VERSION })
+    });
+    if (result.error) throw new Error(result.error.message);
     return 0;
   } catch (error) {
     process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);

package/lib/defaults.json

@@ -42,6 +42,7 @@
       ".claude/commands/",
       ".codex/hooks.json",
       ".gemini/commands/",
+      ".git-hooks/check-large-files.cjs",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
       ".github/workflows/metadata-sync.yml",

package/lib/git/review-snapshot.ts

@@ -0,0 +1,73 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function git(repoRoot: string, args: string[], options: { env?: NodeJS.ProcessEnv; encoding?: BufferEncoding | 'buffer' } = {}) {
+  return execFileSync('git', args, { cwd: repoRoot, encoding: options.encoding ?? 'utf8', env: options.env ?? process.env });
+}
+
+function splitNull(output: string): string[] { return output.split('\0').filter(Boolean); }
+function exists(filePath: string): boolean { try { fs.lstatSync(filePath); return true; } catch { return false; } }
+
+function withTemporaryIndex<T>(repoRoot: string, baseline: string, callback: (env: NodeJS.ProcessEnv) => T): T {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-review-index-'));
+  const env = { ...process.env, GIT_INDEX_FILE: path.join(tempDir, 'index') };
+  try {
+    execFileSync('git', ['read-tree', baseline], { cwd: repoRoot, env });
+    return callback(env);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function projectWorktree(repoRoot: string, baseline: string, globs: string[], env: NodeJS.ProcessEnv) {
+  const tracked = splitNull(String(git(repoRoot, ['diff', '--name-only', '-z', baseline, '--', ...globs])));
+  const untracked = splitNull(String(git(repoRoot, ['ls-files', '-o', '--exclude-standard', '-z', '--', ...globs])));
+  for (const filePath of new Set([...tracked, ...untracked])) {
+    const args = exists(path.join(repoRoot, filePath)) ? ['update-index', '--add', '--', filePath] : ['update-index', '--remove', '--', filePath];
+    execFileSync('git', args, { cwd: repoRoot, env });
+  }
+}
+
+function projectStaged(repoRoot: string, baseline: string, globs: string[], env: NodeJS.ProcessEnv) {
+  for (const filePath of splitNull(String(git(repoRoot, ['diff', '--cached', '--name-only', '-z', baseline, '--', ...globs])))) {
+    const entry = execFileSync('git', ['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', filePath], { cwd: repoRoot, encoding: 'buffer' });
+    execFileSync('git', ['update-index', '-z', '--index-info'], {
+      cwd: repoRoot, env, input: entry.length > 0 ? entry : Buffer.from(`0 ${'0'.repeat(40)}\t${filePath}\0`)
+    });
+  }
+}
+
+function snapshotReview(input: { cwd: string; mode: 'worktree' | 'staged'; baseline: string; globs: string[] }) {
+  const repoRoot = String(git(input.cwd, ['rev-parse', '--show-toplevel'])).trim();
+  const resolvedBaseline = String(git(repoRoot, ['rev-parse', '--verify', `${input.baseline}^{commit}`])).trim();
+  return withTemporaryIndex(repoRoot, resolvedBaseline, (env) => {
+    if (input.mode === 'worktree') projectWorktree(repoRoot, resolvedBaseline, input.globs, env);
+    else projectStaged(repoRoot, resolvedBaseline, input.globs, env);
+    const diff = execFileSync('git', ['diff', '--cached', '--binary', resolvedBaseline, '--', ...input.globs], { cwd: repoRoot, encoding: 'buffer', env });
+    return {
+      baseline: resolvedBaseline,
+      fingerprint: `sha256:${crypto.createHash('sha256').update(diff).digest('hex')}`,
+      tree: String(git(repoRoot, ['write-tree'], { env })).trim()
+    };
+  });
+}
+
+function compareReviewTrees(input: { cwd: string; expected: string; actual: string }) {
+  const repoRoot = String(git(input.cwd, ['rev-parse', '--show-toplevel'])).trim();
+  git(repoRoot, ['rev-parse', '--verify', `${input.expected}^{tree}`]);
+  git(repoRoot, ['rev-parse', '--verify', `${input.actual}^{tree}`]);
+  const fields = splitNull(String(git(repoRoot, ['diff', '--name-status', '-z', '--no-renames', input.expected, input.actual])));
+  const result = { equal: fields.length === 0, added: [] as string[], missing: [] as string[], different: [] as string[] };
+  for (let index = 0; index < fields.length; index += 2) {
+    const status = fields[index]; const filePath = fields[index + 1]!;
+    if (status === 'A') result.added.push(filePath);
+    else if (status === 'D') result.missing.push(filePath);
+    else result.different.push(filePath);
+  }
+  return result;
+}
+
+export { compareReviewTrees, snapshotReview };

package/lib/git/workflow.ts

@@ -0,0 +1,101 @@
+import { spawnSync } from 'node:child_process';
+
+type CommandResult = { status: number | null; stdout: string; stderr: string };
+type GitRunner = (args: readonly string[], cwd: string) => CommandResult;
+type GitOperation = { name: string; status: 'applied' | 'no-op' | 'failed'; ref?: string; message?: string };
+
+const defaultRunner: GitRunner = (args, cwd) => {
+  const result = spawnSync('git', [...args], { cwd, encoding: 'utf8' });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+};
+
+function run(runner: GitRunner, cwd: string, args: readonly string[]): CommandResult {
+  return runner(args, cwd);
+}
+
+function value(runner: GitRunner, cwd: string, args: readonly string[], trim = true): string | null {
+  const result = run(runner, cwd, args);
+  return result.status === 0 ? (trim ? result.stdout.trim() : result.stdout.replace(/\n$/, '')) : null;
+}
+
+function inspectGitWorkflow(cwd: string, runner: GitRunner = defaultRunner, remoteInput?: { remote: string; refs: readonly string[] }) {
+  const head = value(runner, cwd, ['rev-parse', 'HEAD']);
+  const branch = value(runner, cwd, ['branch', '--show-current']);
+  const upstream = value(runner, cwd, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+  const porcelain = value(runner, cwd, ['status', '--porcelain=v1'], false);
+  if (!head || branch === null || porcelain === null) {
+    return { status: 'failed' as const, changed: false, snapshot: null, operations: [], error: { code: 'GIT_INSPECT_FAILED', message: 'Unable to inspect Git repository' } };
+  }
+  const lines = porcelain ? porcelain.split('\n') : [];
+  const remoteRefs = remoteInput ? Object.fromEntries(remoteInput.refs.map((ref) => {
+    const canonical = ref.startsWith('refs/') ? ref : `refs/heads/${ref}`;
+    const remote = run(runner, cwd, ['ls-remote', '--exit-code', remoteInput.remote, canonical]);
+    return [ref, remote.status === 0 ? remote.stdout.trim().split(/\s+/)[0] ?? null : null];
+  })) : {};
+  return {
+    status: 'no-op' as const, changed: false,
+    snapshot: {
+      head, branch, upstream,
+      worktree: lines.filter((line) => line.startsWith('??') || line[1] !== ' ').map((line) => line.slice(3)),
+      staged: lines.filter((line) => !line.startsWith('??') && line[0] !== ' ').map((line) => line.slice(3)),
+      remoteRefs
+    },
+    operations: [], error: null
+  };
+}
+
+function validatePaths(paths: readonly string[]): string | null {
+  if (paths.length === 0) return 'At least one explicit path is required';
+  for (const candidate of paths) {
+    if (!candidate || candidate.startsWith('/') || candidate.split(/[\\/]/).includes('..')) return `Path escapes repository: ${candidate}`;
+    if (/(^|\/)(?:\.env|credentials\.json|id_rsa)(?:$|\/)/i.test(candidate)) return `Sensitive path is not allowed: ${candidate}`;
+  }
+  return null;
+}
+
+function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; message: string; expectedHead?: string; expectedTree?: string }, runner: GitRunner = defaultRunner) {
+  const invalid = validatePaths(input.paths);
+  if (invalid || !input.message.trim()) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [], error: { code: 'GIT_COMMIT_INPUT_INVALID', message: invalid ?? 'Commit message is required' } };
+  const before = inspectGitWorkflow(input.cwd, runner);
+  if (!before.snapshot) return before;
+  if (input.expectedHead && before.snapshot.head !== input.expectedHead) return { status: 'failed' as const, changed: false, snapshot: before.snapshot, operations: [], error: { code: 'GIT_HEAD_MISMATCH', message: `Expected HEAD ${input.expectedHead}, received ${before.snapshot.head}` } };
+  const selected = new Set(input.paths);
+  const unrelatedStaged = before.snapshot.staged.filter((candidate) => !selected.has(candidate));
+  if (unrelatedStaged.length > 0) return { status: 'failed' as const, changed: false, snapshot: before.snapshot, operations: [], error: { code: 'GIT_STAGED_SCOPE_MISMATCH', message: `Unrelated staged paths: ${unrelatedStaged.join(', ')}` } };
+  const add = run(runner, input.cwd, ['add', '--', ...input.paths]);
+  if (add.status !== 0) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'failed' as const, message: add.stderr.trim() }], error: { code: 'GIT_STAGE_FAILED', message: add.stderr.trim() } };
+  const staged = run(runner, input.cwd, ['diff', '--cached', '--quiet', '--']);
+  if (staged.status === 0) return { status: 'no-op' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'no-op' as const }], error: null };
+  if (input.expectedTree) {
+    const tree = value(runner, input.cwd, ['write-tree']);
+    if (tree !== input.expectedTree) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'applied' as const }], error: { code: 'GIT_TREE_MISMATCH', message: `Expected staged tree ${input.expectedTree}, received ${tree ?? 'unavailable'}` } };
+  }
+  const commit = run(runner, input.cwd, ['commit', '-m', input.message]);
+  const after = inspectGitWorkflow(input.cwd, runner);
+  if (commit.status !== 0) return { status: 'failed' as const, changed: false, snapshot: after.snapshot, operations: [{ name: 'commit', status: 'failed' as const, message: commit.stderr.trim() }], error: { code: 'GIT_COMMIT_FAILED', message: commit.stderr.trim() } };
+  return { status: 'applied' as const, changed: true, snapshot: after.snapshot, operations: [{ name: 'stage', status: 'applied' as const }, { name: 'commit', status: 'applied' as const }], error: null };
+}
+
+function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string[] }, runner: GitRunner = defaultRunner) {
+  if (!input.remote || input.refs.length === 0) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [], error: { code: 'GIT_PUSH_INPUT_INVALID', message: 'Remote and refs are required' } };
+  const operations: GitOperation[] = [];
+  for (const ref of input.refs) {
+    if (!/^(?:refs\/(?:heads|tags)\/)?[A-Za-z0-9._/-]+$/.test(ref) || ref.startsWith('-')) {
+      operations.push({ name: 'push', ref, status: 'failed', message: 'Invalid ref' });
+      continue;
+    }
+    const pushed = run(runner, input.cwd, ['push', input.remote, ref]);
+    if (pushed.status !== 0) {
+      operations.push({ name: 'push', ref, status: 'failed', message: pushed.stderr.trim() });
+      continue;
+    }
+    const canonical = ref.startsWith('refs/') ? ref : `refs/heads/${ref}`;
+    const remoteFact = run(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, canonical]);
+    operations.push({ name: 'push', ref, status: remoteFact.status === 0 ? 'applied' : 'failed', message: remoteFact.status === 0 ? undefined : 'Remote ref verification failed' });
+  }
+  const failures = operations.filter((item) => item.status === 'failed').length;
+  return { status: failures === 0 ? 'applied' as const : failures === operations.length ? 'failed' as const : 'degraded' as const, changed: failures < operations.length, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations, error: failures ? { code: 'GIT_PUSH_PARTIAL', message: `${failures} ref push operation(s) failed` } : null };
+}
+
+export { commitExplicitPaths, inspectGitWorkflow, pushGitRefs };
+export type { CommandResult, GitRunner };

package/lib/internal/git-workflow.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.ts';
+import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
+import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
+
+function output(value: unknown): void { process.stdout.write(`${JSON.stringify(value)}\n`); }
+
+function gitWorkflow(args: string[] = []): void {
+  const [action, ...rest] = args;
+  const cwdIndex = rest.indexOf('--cwd');
+  const cwd = cwdIndex >= 0 ? rest[cwdIndex + 1] : process.cwd();
+  let result;
+  if (action === 'inspect') {
+    const inputIndex = rest.indexOf('--input');
+    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) as { remote?: string; refs?: string[] } : null;
+    result = inspectGitWorkflow(cwd ?? process.cwd(), undefined, input?.remote && input.refs ? { remote: input.remote, refs: input.refs } : undefined);
+  }
+  else if (action === 'commit') {
+    const inputIndex = rest.indexOf('--input');
+    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
+    result = input ? commitExplicitPaths({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
+  } else if (action === 'push') {
+    const inputIndex = rest.indexOf('--input');
+    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
+    result = input ? pushGitRefs({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
+  } else if (action === 'snapshot' || action === 'compare-trees') {
+    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 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);
+  process.exitCode = result.status === 'failed' ? 1 : result.status === 'blocked' ? 2 : 0;
+}
+
+export { gitWorkflow };

package/lib/internal/platform-checks.ts

@@ -0,0 +1,101 @@
+import path from 'node:path';
+
+import {
+  fetchPlatformCheckLogs,
+  inspectRequiredChecks,
+  resolvePlatformCheckRun,
+  watchPlatformChecks
+} from '../platform/pr-checks.ts';
+import type { ChecksResult } from '../platform/pr-checks.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-checks inspect <task-ref> [--cwd <path>]
+       agent-infra-internal platform-checks watch <task-ref> --interval-seconds <N> --deadline-seconds <N> [--cwd <path>]
+       agent-infra-internal platform-checks resolve-run <task-ref> --check-name <name> [--details-url <url>] [--cwd <path>]
+       agent-infra-internal platform-checks logs <task-ref> --run <id> [--job <id>] [--cwd <path>]
+`;
+
+const VALUE_FLAGS = new Set(['--cwd', '--interval-seconds', '--deadline-seconds', '--check-name', '--details-url', '--run', '--job']);
+
+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: 'CHECKS_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(output: ChecksResult): 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> = {};
+  const seen = new Set<string>();
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!VALUE_FLAGS.has(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[key(flag)] = value;
+  }
+  return { values };
+}
+
+function positive(value: string | undefined): number | null {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : null;
+}
+
+async function platformChecks(args: string[] = []): Promise<void> {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['inspect', 'watch', 'resolve-run', 'logs'].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(values.cwd || process.cwd());
+  const allowed: Record<string, string[]> = {
+    inspect: ['cwd'],
+    watch: ['cwd', 'intervalSeconds', 'deadlineSeconds'],
+    'resolve-run': ['cwd', 'checkName', 'detailsUrl'],
+    logs: ['cwd', 'run', 'job']
+  };
+  const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
+  if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
+  if (operation === 'inspect') { finish(inspectRequiredChecks(taskRef, { cwd })); return; }
+  if (operation === 'resolve-run') {
+    if (!values.checkName) { fail('resolve-run requires --check-name'); return; }
+    finish(resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
+    return;
+  }
+  if (operation === 'logs') {
+    const run = positive(values.run);
+    const job = values.job === undefined ? undefined : positive(values.job);
+    if (!run || values.job !== undefined && !job) { fail('logs requires a positive --run and optional positive --job'); return; }
+    finish(fetchPlatformCheckLogs(taskRef, { cwd, run, job: job || undefined }));
+    return;
+  }
+  const intervalSeconds = positive(values.intervalSeconds);
+  const deadlineSeconds = positive(values.deadlineSeconds);
+  if (!intervalSeconds || !deadlineSeconds) { fail('watch requires positive --interval-seconds and --deadline-seconds'); return; }
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.once('SIGINT', abort);
+  process.once('SIGTERM', abort);
+  try {
+    finish(await watchPlatformChecks(taskRef, { cwd, intervalSeconds, deadlineSeconds, signal: controller.signal }));
+  } finally {
+    process.removeListener('SIGINT', abort);
+    process.removeListener('SIGTERM', abort);
+  }
+}
+
+export { platformChecks };

package/lib/internal/platform-comment.ts

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  checkPlatformCommentOwner,
+  listPlatformComments,
+  syncPlatformComment
+} from '../platform/issue-comments.ts';
+import type { CommentKind } from '../platform/issue-comments.ts';
+import type { PlatformResult } from '../platform/types.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+       agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
+       agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
+`;
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'COMMENT_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(result: PlatformResult): void {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+  if (result.status === 'blocked') process.exitCode = 2;
+}
+
+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 (!['--issue', '--cwd', '--kind', '--agent', '--artifact', '--body-file', '--status-label', '--backfill'].includes(flag)) {
+      return { values, error: `unknown option '${flag}'` };
+    }
+    if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
+    seen.add(flag);
+    if (flag === '--backfill') { values.backfill = true; continue; }
+    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 readBodyFile(value: string, cwd: string): string {
+  if (value === '-') return fs.readFileSync(0, 'utf8');
+  return fs.readFileSync(path.resolve(cwd, value), 'utf8');
+}
+
+function platformComment(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['list', 'owner', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  const hasTaskRef = operation !== 'list';
+  const taskRef = hasTaskRef ? args[1] : undefined;
+  if (hasTaskRef && (!taskRef || taskRef.startsWith('--'))) { fail(`${operation} requires a task ref`); return; }
+  const parsed = parseFlags(args, hasTaskRef ? 2 : 1);
+  if (parsed.error) { fail(parsed.error); return; }
+  const cwd = path.resolve(typeof parsed.values.cwd === 'string' ? parsed.values.cwd : process.cwd());
+  if (operation === 'list') {
+    const issue = Number(parsed.values.issue);
+    if (!Number.isInteger(issue) || issue <= 0) { fail('list requires a positive --issue'); return; }
+    const unexpected = Object.keys(parsed.values).find((key) => !['issue', 'cwd'].includes(key));
+    if (unexpected) { fail(`list does not accept '--${unexpected}'`); return; }
+    finish(listPlatformComments(issue, cwd));
+    return;
+  }
+  if (operation === 'owner') {
+    const unexpected = Object.keys(parsed.values).find((key) => key !== 'cwd');
+    if (unexpected) { fail(`owner does not accept '--${unexpected}'`); return; }
+    finish(checkPlatformCommentOwner(taskRef!, { cwd }));
+    return;
+  }
+  const kind = parsed.values.kind;
+  const agent = parsed.values.agent;
+  if (!['task', 'artifact', 'summary', 'cancel'].includes(String(kind))) { fail('sync requires a valid --kind'); return; }
+  if (typeof agent !== 'string' || !agent) { fail('sync requires --agent'); return; }
+  if (kind === 'artifact' && typeof parsed.values.artifact !== 'string') { fail('artifact sync requires --artifact'); return; }
+  if ((kind === 'summary' || kind === 'cancel') && typeof parsed.values.bodyFile !== 'string') { fail(`${kind} sync requires --body-file`); return; }
+  let body: string | undefined;
+  try {
+    if (typeof parsed.values.bodyFile === 'string') body = readBodyFile(parsed.values.bodyFile, cwd);
+  } catch (error) {
+    fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  finish(syncPlatformComment(taskRef!, {
+    kind: kind as CommentKind,
+    agent,
+    artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,
+    body,
+    backfill: parsed.values.backfill === true,
+    cwd
+  }));
+}
+
+export { platformComment };

package/lib/internal/platform-context.ts

@@ -0,0 +1,33 @@
+import path from 'node:path';
+
+import { resolvePlatformContext } from '../platform/context.ts';
+
+const USAGE = 'Usage: agent-infra-internal platform-context resolve [--cwd <path>]\n';
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PLATFORM_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function platformContext(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args[0] !== 'resolve') { fail("operation must be 'resolve'"); return; }
+  let cwd = process.cwd();
+  const seen = new Set<string>();
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag !== '--cwd') { fail(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { fail(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) { fail(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    cwd = path.resolve(value);
+  }
+  const result = resolvePlatformContext({ cwd });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+  if (result.status === 'blocked') process.exitCode = 2;
+}
+
+export { platformContext };