@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/lib/pr-review/evidence-grading.ts

@@ -0,0 +1,318 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+
+// ---------------------------------------------------------------------------
+// Host resolution (PL-4): PR -> unique / ambiguous / none.
+// ---------------------------------------------------------------------------
+
+export type HostCandidate = {
+  taskId: string;
+  taskDir: string;
+  issueNumber: number | null;
+  prNumber: number | null;
+};
+
+export type HostResolution =
+  | { kind: 'unique'; taskId: string; taskDir: string; issueNumber: number; prNumber: number }
+  | { kind: 'ambiguous'; candidates: Array<{ taskId: string; issueNumber: number }> }
+  | { kind: 'none' };
+
+export type HostResolutionErrorCode = 'HOST_AMBIGUOUS' | 'HOST_RESOLUTION_INVALID';
+
+export class HostResolutionError extends Error {
+  code: HostResolutionErrorCode;
+
+  constructor(code: HostResolutionErrorCode, message: string) {
+    super(message);
+    this.name = 'HostResolutionError';
+    this.code = code;
+  }
+}
+
+function toPositiveNumber(value: unknown): number | null {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * Parse the PR body for closing-issue references. Handles the conventional
+ * `Closes #1` / `Fixes: #2, #3` shapes (case-insensitive, comma/space
+ * separated, optional keyword list on the same logical line).
+ */
+export function extractClosingIssueNumbers(body: string): number[] {
+  const result: number[] = [];
+  const seen = new Set<number>();
+  const linePattern = /(?:^|\n)[^\n]*\b(?:close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)\b[^\n]*/gi;
+  let lineMatch: RegExpExecArray | null;
+  while ((lineMatch = linePattern.exec(body)) !== null) {
+    const line = lineMatch[0]!;
+    for (const numMatch of line.matchAll(/#(\d+)/g)) {
+      const n = Number(numMatch[1]!);
+      if (Number.isInteger(n) && n > 0 && !seen.has(n)) {
+        seen.add(n);
+        result.push(n);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Scan `.agents/workspace/active/{task-id}/task.md` files for tasks bound to the
+ * PR number or to one of the PR's closing issues. A task is emitted at most once;
+ * a direct `pr_number` hit takes priority over the issue-number reverse lookup.
+ */
+export function collectHostCandidates(input: {
+  prNumber: number;
+  closingIssues: number[];
+  workspaceRoot: string;
+}): HostCandidate[] {
+  const activeRoot = path.join(input.workspaceRoot, '.agents', 'workspace', 'active');
+  const candidates: HostCandidate[] = [];
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(activeRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const taskDir = path.join(activeRoot, entry.name);
+    const taskMdPath = path.join(taskDir, 'task.md');
+    let content: string;
+    try {
+      content = fs.readFileSync(taskMdPath, 'utf8');
+    } catch {
+      continue;
+    }
+    const frontmatter = parseTaskFrontmatter(content);
+    const issueNumber = toPositiveNumber(frontmatter.issue_number);
+    const prNumber = toPositiveNumber(frontmatter.pr_number);
+    if (prNumber === input.prNumber) {
+      candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber });
+    } else if (issueNumber !== null && input.closingIssues.includes(issueNumber)) {
+      candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Collapse a candidate list into a typed HostResolution. Zero candidates ->
+ * none; exactly one -> unique; more than one (no stable selection rule) ->
+ * ambiguous (fail closed, AN-6).
+ */
+export function resolveHostFromCandidates(candidates: HostCandidate[]): HostResolution {
+  if (candidates.length === 0) return { kind: 'none' };
+  if (candidates.length === 1) {
+    const candidate = candidates[0]!;
+    return {
+      kind: 'unique',
+      taskId: candidate.taskId,
+      taskDir: candidate.taskDir,
+      issueNumber: candidate.issueNumber ?? 0,
+      prNumber: candidate.prNumber ?? 0
+    };
+  }
+  return {
+    kind: 'ambiguous',
+    candidates: candidates.map((candidate) => ({ taskId: candidate.taskId, issueNumber: candidate.issueNumber ?? 0 }))
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Evidence presence, head state, scenarios, risk and mode (AN-5/6/7, PL-3/5/9).
+// ---------------------------------------------------------------------------
+
+export type ArtifactPresence = {
+  hasAnalysis: boolean;
+  hasPlan: boolean;
+  hasCode: boolean;
+  hasReviewAnalysis: boolean;
+  hasReviewPlan: boolean;
+  hasReviewCode: boolean;
+  hasPriorPrReview: boolean;
+};
+
+export type HeadState = {
+  currentHeadSha: string;
+  priorHeadSha: string | null;
+  issueNumberBound: boolean;
+  taskIssueMatches: boolean;
+  prNumberBound: boolean;
+  taskPrMatches: boolean;
+};
+
+export type EvidenceScenario = 'S1' | 'S2' | 'S3';
+export type Freshness = 'fresh' | 'stale' | 'n/a';
+export type Alignment = 'aligned' | 'misaligned' | 'n/a';
+export type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH';
+export type ReviewMode = 'verify' | 'audit' | 'reconstruct';
+
+export type RiskFactors = {
+  changeSize: 'LOW' | 'HIGH';
+  sensitivity: 'LOW' | 'HIGH';
+  structural: 'LOW' | 'HIGH';
+  testCoverage: 'LOW' | 'HIGH';
+  sourceCredibility: 'LOW' | 'HIGH';
+  recoveryImpact: 'LOW' | 'HIGH';
+};
+
+export type DecisionRecord = {
+  host: HostResolution;
+  scenario: EvidenceScenario;
+  freshness: Freshness;
+  alignment: Alignment;
+  risk: RiskLevel;
+  mode: ReviewMode;
+  firstReview: boolean;
+  reason: string;
+};
+
+function hasNoLifecycleArtifacts(presence: ArtifactPresence): boolean {
+  return !presence.hasAnalysis && !presence.hasPlan && !presence.hasCode &&
+    !presence.hasReviewAnalysis && !presence.hasReviewPlan && !presence.hasReviewCode &&
+    !presence.hasPriorPrReview;
+}
+
+function hasFullArtifacts(presence: ArtifactPresence): boolean {
+  return presence.hasAnalysis && presence.hasPlan && presence.hasCode &&
+    presence.hasReviewAnalysis && presence.hasReviewPlan && presence.hasReviewCode;
+}
+
+function isTrusted(head: HeadState): boolean {
+  return head.issueNumberBound && head.taskIssueMatches && (!head.prNumberBound || head.taskPrMatches);
+}
+
+/**
+ * Derive the S1(a) trust factor `taskIssueMatches` (PL-3) mechanically from
+ * resolved data: a unique host is trusted on the issue dimension only when the
+ * task's bound issue_number is among the PR's closing issues. Ambiguous/none
+ * hosts and tasks without a positive issue_number cannot be confirmed -> false
+ * (fail closed to S2/audit). `resolve-host` emits this value so the prompt layer
+ * does not derive the trust factor ad hoc (CD-2).
+ */
+export function deriveTaskIssueMatches(host: HostResolution, closingIssues: number[]): boolean {
+  return host.kind === 'unique' && host.issueNumber > 0 && closingIssues.includes(host.issueNumber);
+}
+
+/**
+ * S1 -> S2 -> S3 classification (analysis §6.1). The ambiguous host is rejected
+ * before classification (AN-6 fail closed). S3(a) is host.kind === 'none';
+ * S3(b) is a unique task with no lifecycle artifacts and no prior pr-review
+ * (PL-5/PL-9 symmetric: any review-only task falls to S2).
+ */
+export function classifyScenario(host: HostResolution, presence: ArtifactPresence, head: HeadState): EvidenceScenario {
+  if (host.kind === 'ambiguous') {
+    throw new HostResolutionError('HOST_AMBIGUOUS', 'multiple candidate hosts; resolve before evidence classification');
+  }
+  if (host.kind === 'none') return 'S3';
+  if (hasNoLifecycleArtifacts(presence)) return 'S3';
+  const priorHeadMatches = presence.hasPriorPrReview && head.priorHeadSha !== null && head.priorHeadSha === head.currentHeadSha;
+  if (hasFullArtifacts(presence) && priorHeadMatches && isTrusted(head)) return 'S1';
+  return 'S2';
+}
+
+/**
+ * Freshness is benchmarked against the prior `pr-review*` reviewed head SHA
+ * (analysis §6.2, AN-7). No prior review -> n/a/n/a (first-review special case).
+ */
+export function evaluateHead(head: HeadState): { freshness: Freshness; alignment: Alignment } {
+  if (head.priorHeadSha === null) return { freshness: 'n/a', alignment: 'n/a' };
+  const freshness: Freshness = head.priorHeadSha === head.currentHeadSha ? 'fresh' : 'stale';
+  const aligned = freshness === 'fresh' && isTrusted(head);
+  return { freshness, alignment: aligned ? 'aligned' : 'misaligned' };
+}
+
+/**
+ * Pure-evidence risk aggregation (analysis §6.3, AN-5): any priority factor
+ * (sensitivity / sourceCredibility) HIGH -> HIGH; otherwise any HIGH -> MEDIUM;
+ * all LOW -> LOW. Identity factors are structurally absent from the input type.
+ */
+export function gradeRisk(factors: RiskFactors): RiskLevel {
+  const priority = [factors.sensitivity, factors.sourceCredibility] as const;
+  if (priority.includes('HIGH')) return 'HIGH';
+  const values = Object.values(factors) as Array<'LOW' | 'HIGH'>;
+  if (values.includes('HIGH')) return 'MEDIUM';
+  return 'LOW';
+}
+
+/**
+ * verify / audit / reconstruct selection matrix (analysis §6.4). S3 ->
+ * reconstruct; S2 -> audit; S1 fresh+aligned -> verify (LOW/MEDIUM risk) or
+ * audit (HIGH risk); any other S1 combination falls back to audit.
+ */
+export function selectMode(scenario: EvidenceScenario, freshness: Freshness, alignment: Alignment, risk: RiskLevel): ReviewMode {
+  if (scenario === 'S3') return 'reconstruct';
+  if (scenario === 'S2') return 'audit';
+  if (freshness === 'fresh' && alignment === 'aligned') {
+    return risk === 'HIGH' ? 'audit' : 'verify';
+  }
+  return 'audit';
+}
+
+function buildReason(input: {
+  scenario: EvidenceScenario;
+  freshness: Freshness;
+  alignment: Alignment;
+  risk: RiskLevel;
+  mode: ReviewMode;
+  firstReview: boolean;
+  hasPriorPrReview: boolean;
+}): string {
+  const pieces: string[] = [];
+  if (input.firstReview) pieces.push('first review (no prior pr-review head)');
+  if (input.hasPriorPrReview) pieces.push(`prior head ${input.freshness}`);
+  if (input.freshness === 'fresh') pieces.push(`alignment ${input.alignment}`);
+  pieces.push(`evidence scenario ${input.scenario}`);
+  pieces.push(`risk ${input.risk}`);
+  pieces.push(`mode ${input.mode}`);
+  return pieces.join('; ');
+}
+
+/**
+ * Full decision pipeline: classify -> freshness/alignment -> risk -> mode,
+ * producing a traceable DecisionRecord (AC3). Ambiguous hosts are rejected
+ * before any classification runs (AN-6).
+ */
+export function decide(input: {
+  host: HostResolution;
+  presence: ArtifactPresence;
+  head: HeadState;
+  riskFactors: RiskFactors;
+}): DecisionRecord {
+  if (input.host.kind === 'ambiguous') {
+    throw new HostResolutionError('HOST_AMBIGUOUS', 'ambiguous host; resolve before evidence classification');
+  }
+  const scenario = classifyScenario(input.host, input.presence, input.head);
+  const { freshness, alignment } = evaluateHead(input.head);
+  const risk = gradeRisk(input.riskFactors);
+  const mode = selectMode(scenario, freshness, alignment, risk);
+  const firstReview = !input.presence.hasPriorPrReview;
+  return {
+    host: input.host,
+    scenario,
+    freshness,
+    alignment,
+    risk,
+    mode,
+    firstReview,
+    reason: buildReason({
+      scenario,
+      freshness,
+      alignment,
+      risk,
+      mode,
+      firstReview,
+      hasPriorPrReview: input.presence.hasPriorPrReview
+    })
+  };
+}
+
+export {
+  hasFullArtifacts,
+  hasNoLifecycleArtifacts,
+  isTrusted
+};

package/lib/run/tui.ts

@@ -1,9 +1,9 @@
 import { renderAgentClientInvocation } from '../agent-clients/invocation.ts';
 import { getAgentClientAdapter } from '../agent-clients/registry.ts';
 
-export type TuiName = 'claude' | 'codex' | 'gemini' | 'opencode';
+export type TuiName = 'claude' | 'codex' | 'antigravity' | 'opencode';
 
-const TUI_NAMES = new Set(['claude', 'codex', 'gemini', 'opencode']);
+const TUI_NAMES = new Set(['claude', 'codex', 'antigravity', 'opencode']);
 
 export type CommandConfig = {
   defaultTui?: unknown;
@@ -36,13 +36,12 @@ export function renderPrompt(params: { tui: TuiName; skill: string; args: string
       args: params.args
     });
   }
-  if (params.tui === 'gemini') return `/agent-infra:${suffix}`;
   return `/${suffix}`;
 }
 
 export function buildTuiCommand(tui: TuiName, prompt: string): [string, string[]] {
   if (tui === 'claude') return ['claude', ['--dangerously-skip-permissions', '--print', prompt]];
-  if (tui === 'gemini') return ['gemini', ['--approval-mode', 'yolo', '--prompt', prompt]];
+  if (tui === 'antigravity') return ['agy', ['--dangerously-skip-permissions', '--print', prompt]];
   if (tui === 'opencode') return ['opencode', ['run', '--dangerously-skip-permissions', prompt]];
   return ['codex', ['exec', '--dangerously-bypass-approvals-and-sandbox', prompt]];
 }

package/lib/sandbox/commands/create.ts

@@ -1010,22 +1010,6 @@ export function ensureOpenCodeModelInheritance(toolDir: string, hostHomeDir?: st
   }
 }
 
-export function ensureGeminiWorkspaceTrust(toolDir: string): void {
-  const trustPath = path.join(toolDir, 'trustedFolders.json');
-  let data: Record<string, string> = {};
-  if (fs.existsSync(trustPath)) {
-    try {
-      data = JSON.parse(fs.readFileSync(trustPath, 'utf8')) as Record<string, string>;
-    } catch {
-      // malformed JSON, start fresh
-    }
-  }
-  if (data['/workspace'] !== 'TRUST_FOLDER') {
-    data['/workspace'] = 'TRUST_FOLDER';
-    fs.writeFileSync(trustPath, JSON.stringify(data, null, 2), 'utf8');
-  }
-}
-
 export function sandboxAliasesPath(home: string): string {
   return hostJoin(home, '.agent-infra', 'aliases', 'sandbox.sh');
 }
@@ -1523,10 +1507,6 @@ export async function create(args: string[]): Promise<void> {
               // provider/API settings are enough for Claude Code. If no usable
               // auth was present, the claude-code entry was removed above.
             }
-            const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
-            if (geminiEntry) {
-              ensureGeminiWorkspaceTrust(geminiEntry.dir);
-            }
             const opencodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'opencode');
             if (opencodeEntry) {
               // The TUI reads <toolDir>/opencode.json via OPENCODE_CONFIG pinned in tools.js.

package/lib/sandbox/commands/show.ts

@@ -10,7 +10,7 @@ import { resolveTools, toolConfigDirCandidates } from '../tools.ts';
 const USAGE = `Usage: ai sandbox show <branch | TASK-id | N>
 
 Shows one sandbox's worktree path and per-tool state paths (Claude Code,
-Codex, Gemini CLI, OpenCode). The argument follows the same contract as
+Codex, Antigravity CLI, OpenCode). The argument follows the same contract as
 'ai sandbox exec' and 'ai sandbox start': N (bare) is the recommended form
 for task short ids (e.g. 'ai sandbox show 11'); a TASK-id or a plain
 branch name are also accepted. Use 'ai sandbox ls' for the container list.`;

package/lib/server/server.schema.json

@@ -75,14 +75,14 @@
       "properties": {
         "defaultTui": {
           "type": "string",
-          "enum": ["claude", "codex", "gemini", "opencode"],
+          "enum": ["claude", "codex", "antigravity", "opencode"],
           "default": "codex"
         },
         "skillTuiDefaults": {
           "type": "object",
           "additionalProperties": {
             "type": "string",
-            "enum": ["claude", "codex", "gemini", "opencode"]
+            "enum": ["claude", "codex", "antigravity", "opencode"]
           }
         },
         "allowedSkills": {

package/lib/task/activity-intent.ts

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { resolveTaskRef } from './resolve-ref.ts';
+import { locateActivityLog, appendActivityEntry } from './activity-log.ts';
+import { buildArtifactLinkSection, parseArtifactName } from './artifact-lifecycle.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+
+export type ActivityAppendIntent = {
+  kind: 'append';
+  taskRef: string;
+  step: string;
+  agent: string;
+  note: string;
+  artifact?: string;
+  dryRun?: boolean;
+};
+
+export type ActivityIntentResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  intent: 'append';
+  taskId: string | null;
+  artifact: string | null;
+  operations: readonly TaskOperationSummary[];
+  error: { code: string; message: string } | null;
+};
+
+function failed(intent: ActivityAppendIntent, code: string, message: string, taskId: string | null = null): ActivityIntentResult {
+  return {
+    status: 'failed', changed: false, intent: 'append', taskId,
+    artifact: intent.artifact ?? null, operations: [], error: { code, message }
+  };
+}
+
+function oneLine(value: string): string {
+  return value.replace(/\s*\r?\n\s*/g, ' ').trim();
+}
+
+/**
+ * Append an Activity Log entry (and, optionally, a `## 审查反馈` artifact link)
+ * to an active task via the atomic `writeTask` path. `current_step` is never
+ * touched (PL-2): review-pr does not join the standard stage chain.
+ */
+export function applyActivityAppendIntent(intent: ActivityAppendIntent, options: TaskWriteOptions = {}): ActivityIntentResult {
+  if (intent.kind !== 'append') return failed(intent, 'ACTIVITY_INTENT_INVALID', 'intent kind must be append');
+  const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
+  if (resolved.state !== 'active') {
+    return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  }
+  const step = oneLine(intent.step);
+  const agent = oneLine(intent.agent);
+  const note = oneLine(intent.note);
+  if (!step || !agent || !note || /[\r\n]/.test(intent.step) || /[\r\n]/.test(intent.agent) || /[\r\n]/.test(intent.note)) {
+    return failed(intent, 'ACTIVITY_INTENT_INVALID', 'step, agent and note must be non-empty single-line values', resolved.taskId);
+  }
+
+  let artifact: ReturnType<typeof parseArtifactName> | null = null;
+  if (intent.artifact !== undefined) {
+    artifact = parseArtifactName(intent.artifact);
+    if (!artifact || artifact.family !== 'pr-review') {
+      return failed(intent, 'ACTIVITY_ARTIFACT_INVALID', `artifact '${intent.artifact}' is not a canonical pr-review artifact`, resolved.taskId);
+    }
+  }
+
+  let content: string;
+  try {
+    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  } catch (error) {
+    return failed(intent, 'TASK_READ_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
+  const section = locateActivityLog(content);
+  if (!section) {
+    return failed(intent, 'ACTIVITY_SECTION_MISSING', 'task has no unique Activity Log section', resolved.taskId);
+  }
+
+  let metadata;
+  try {
+    metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+  } catch (error) {
+    return failed(intent, 'METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
+
+  const mutations: TaskMutation[] = [];
+  const activityBody = appendActivityEntry(section, { time: metadata.timestamp, step, agent, note });
+  mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body: activityBody });
+  if (artifact) {
+    const link = buildArtifactLinkSection(content, {
+      ...artifact,
+      path: path.join(resolved.taskDir, artifact.name),
+      size: 0,
+      mtimeMs: 0
+    });
+    mutations.push({ kind: 'section', aliases: link.aliases, heading: link.heading, body: link.body });
+  }
+
+  const writeResult = writeTask({
+    taskRef: intent.taskRef,
+    expectedState: 'active',
+    mutations,
+    dryRun: intent.dryRun
+  }, {
+    ...options,
+    taskLocation: {
+      repoRoot: resolved.repoRoot,
+      taskId: resolved.taskId,
+      taskMdPath: resolved.taskMdPath,
+      state: resolved.state
+    },
+    metadataProvider: () => metadata
+  });
+  if (writeResult.status === 'failed') {
+    return failed(intent, writeResult.error.code, writeResult.error.message, writeResult.taskId);
+  }
+  return {
+    status: writeResult.status,
+    changed: writeResult.changed,
+    intent: 'append',
+    taskId: writeResult.taskId,
+    artifact: intent.artifact ?? null,
+    operations: writeResult.operations,
+    error: null
+  };
+}
+
+export type { TaskWriteOptions } from './write.ts';

package/lib/task/artifact-lifecycle.ts

@@ -15,7 +15,8 @@ const artifactFamilyCatalog = [
   { family: 'review-plan', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['技术方案审查', 'Plan Review'] },
   { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
   { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
-  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] }
+  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
+  { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
 ] as const;
 
 type ArtifactFamily = (typeof artifactFamilyCatalog)[number]['family'];

package/lib/task/commands/log.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { classifyAgent } from '../../agent-clients/tokens.ts';
 import { formatTable } from '../../table.ts';
 import { parseTaskScope } from '../command-options.ts';
 import { resolveTaskContext } from '../resolve-ref.ts';
@@ -34,11 +35,11 @@ const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'] as const
 // with ` [started]`; the matching done entry carries the identical base action
 // without the suffix. Pairing therefore keys on the base action (including any
 // `(Round N)`), so every round and every repeated execution pairs on its own.
-// Short agent tokens that actually appear in activity logs for AI executors
-// (workflow recommended_agents claude/codex/gemini/cursor + enabled TUI opencode;
-// note these differ from the `.airc.json` long names claude-code/gemini-cli).
-// Any other executor token (a human name, possibly CJK) is treated as human.
-const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'gemini', 'opencode', 'cursor']);
+// Known AI tokens, long-name mapping, and loose rendering classification live
+// in lib/agent-clients/tokens.ts (single source of truth shared with the
+// write-side internal commands). Any other executor token (a human name,
+// possibly CJK, or an unknown value) is rendered as human with a visible
+// `(unknown)` marker.
 const REVIEW_STAGE_PREFIXES: { prefix: string; stage: ReviewStage }[] = [
   { prefix: 'Review Analysis', stage: 'analysis' },
   { prefix: 'Review Plan', stage: 'plan' },
@@ -90,12 +91,11 @@ function isHumanCountField(field: string): boolean {
   return fieldNumber(field, 'manual-validation') !== undefined || fieldNumber(field, 'human-decision') !== undefined;
 }
 
-// A step is human-executed when its agent token is not a known AI token. Take
-// the first whitespace-delimited token and drop any trailing parenthetical
-// annotation (e.g. `张三 (executed on host)` -> `张三`) before the lookup.
-function isHumanAgent(agent: string): boolean {
-  const token = agent.trim().split(/\s+/)[0]?.replace(/\(.*$/, '') ?? '';
-  return token !== '' && !KNOWN_AI_AGENTS.has(token);
+// A step is human-executed when its agent token is not a known AI token.
+// Known long names (claude-code -> claude, gemini-cli -> gemini) classify as
+// AI; empty or unknown tokens classify as non-AI (human).
+export function isHumanAgent(agent: string): boolean {
+  return classifyAgent(agent).status !== 'ai';
 }
 
 // Fold the two human counts into a review row's verdict NOTE: comma-joined, right
@@ -152,8 +152,9 @@ function log(args: string[] = []): void {
     const note = stage
       ? foldHumanCounts(s.note, humanDecisionCounts.get(stage) ?? 0, humanValidationCount(s.note))
       : s.note;
-    const human = isHumanAgent(s.agent);
-    const agent = human ? 'human' : s.agent;
+    const { status, display } = classifyAgent(s.agent);
+    const human = status !== 'ai';
+    const agent = status === 'unknown' ? `${display} (unknown)` : display;
     const started = s.started || (human ? '-' : '');
     return [String(idx + 1), s.step, agent, started, s.done || (s.started ? '(in progress)' : ''), note];
   });
@@ -163,4 +164,4 @@ function log(args: string[] = []): void {
   process.stdout.write(`Total: ${steps.length} steps\n`);
 }
 
-export { log, isHumanAgent };
+export { log };