@fitlab-ai/agent-infra 0.9.2 → 0.9.4

package/lib/agent-clients/config.ts

@@ -6,7 +6,8 @@ import type {
   AgentClientConfig,
   AgentClientId,
   AgentClientsConfig,
-  AgentClientState
+  AgentClientState,
+  OrchestrationModelPolicy
 } from './types.ts';
 
 type AgentClientConfigInput = Readonly<{
@@ -65,12 +66,49 @@ function fail(code: AgentClientDiagnosticCode, path: string): never {
   throw new AgentClientConfigError({ code, path });
 }
 
+function parseExactText(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.length === 0 || value.trim() !== value) {
+    fail('INVALID_AGENT_CLIENTS', path);
+  }
+  return value;
+}
+
+function parseOrchestrationPolicy(value: unknown, path: string): OrchestrationModelPolicy {
+  if (!isRecord(value)) fail('INVALID_AGENT_CLIENTS', path);
+  const keys = Object.keys(value);
+  if (
+    keys.length !== 2
+    || !hasOwn(value, 'executor')
+    || !hasOwn(value, 'reviewer')
+  ) {
+    fail('INVALID_AGENT_CLIENTS', path);
+  }
+  const parseRole = (candidate: unknown, rolePath: string) => {
+    if (
+      !isRecord(candidate)
+      || Object.keys(candidate).length !== 2
+      || !hasOwn(candidate, 'model')
+      || !hasOwn(candidate, 'reasoningEffort')
+    ) {
+      fail('INVALID_AGENT_CLIENTS', rolePath);
+    }
+    return Object.freeze({
+      model: parseExactText(candidate.model, `${rolePath}.model`),
+      reasoningEffort: parseExactText(candidate.reasoningEffort, `${rolePath}.reasoningEffort`)
+    });
+  };
+  const executor = parseRole(value.executor, `${path}.executor`);
+  const reviewer = parseRole(value.reviewer, `${path}.reviewer`);
+  return Object.freeze({ executor, reviewer });
+}
+
 function parseCanonical(value: unknown): AgentClientState {
   if (!Array.isArray(value)) fail('INVALID_AGENT_CLIENTS', 'agentClients');
 
   const entries = new Map<AgentClientId, Readonly<{
     enabled: boolean;
     installInSandbox: boolean;
+    orchestration?: OrchestrationModelPolicy;
   }>>();
 
   for (const [index, candidate] of value.entries()) {
@@ -79,10 +117,11 @@ function parseCanonical(value: unknown): AgentClientState {
 
     const keys = Object.keys(candidate);
     if (
-      keys.length !== 3
+      (keys.length !== 3 && keys.length !== 4)
       || !hasOwn(candidate, 'id')
       || !hasOwn(candidate, 'enabled')
       || !hasOwn(candidate, 'installInSandbox')
+      || (keys.length === 4 && !hasOwn(candidate, 'orchestration'))
     ) {
       fail('INVALID_AGENT_CLIENTS', path);
     }
@@ -100,7 +139,10 @@ function parseCanonical(value: unknown): AgentClientState {
     }
     entries.set(candidate.id, {
       enabled: candidate.enabled,
-      installInSandbox: candidate.installInSandbox
+      installInSandbox: candidate.installInSandbox,
+      ...(hasOwn(candidate, 'orchestration')
+        ? { orchestration: parseOrchestrationPolicy(candidate.orchestration, `${path}.orchestration`) }
+        : {})
     });
   }
 
@@ -117,7 +159,10 @@ function serializeAgentClients(state: AgentClientState): AgentClientsConfig {
   return AGENT_CLIENT_IDS.map((id): AgentClientConfig => ({
     id,
     enabled: state[id].enabled,
-    installInSandbox: state[id].installInSandbox
+    installInSandbox: state[id].installInSandbox,
+    ...(state[id].orchestration
+      ? { orchestration: structuredClone(state[id].orchestration) }
+      : {})
   }));
 }
 

package/lib/agent-clients/next-steps.ts

@@ -1,5 +1,6 @@
 import { listEnabledAgentClientAdapters } from './registry.ts';
 import { renderAgentClientInvocation } from './invocation.ts';
+import semver from 'semver';
 import type { CustomTUI } from './custom-tuis.ts';
 import type { AgentClientId, AgentClientState } from './types.ts';
 
@@ -16,6 +17,7 @@ type RenderNextStepsInput = Readonly<{
   customTUIs: readonly CustomTUI[];
   skillName: string;
   taskRef?: string;
+  version?: string;
 }>;
 
 const SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
@@ -35,6 +37,17 @@ function renderNextStepCommands(
   if (input.taskRef !== undefined && !SAFE_TASK_REF.test(input.taskRef)) {
     throw new Error('Invalid task ref');
   }
+  if (
+    input.version !== undefined
+    && (!/^[0-9]/.test(input.version) || semver.valid(input.version) !== input.version)
+  ) {
+    throw new Error('Invalid version');
+  }
+
+  const args = [
+    ...(input.taskRef === undefined ? [] : [input.taskRef]),
+    ...(input.version === undefined ? [] : [input.version])
+  ];
 
   const builtins = listEnabledAgentClientAdapters(input.state).map(
     (adapter): NextStepCommand => Object.freeze({
@@ -46,7 +59,7 @@ function renderNextStepCommands(
         {
           projectName: input.projectName,
           skillName: input.skillName,
-          args: input.taskRef === undefined ? [] : [input.taskRef]
+          args
         }
       )
     })
@@ -60,7 +73,7 @@ function renderNextStepCommands(
         {
           projectName: input.projectName,
           skillName: input.skillName,
-          args: input.taskRef === undefined ? [] : [input.taskRef]
+          args
         }
       )
     })

package/lib/agent-clients/reconcile.ts

@@ -236,7 +236,8 @@ function planAgentClientReconciliation(input: Readonly<{
   const actionableSeed = seedOperations.some((operation) =>
     operation.kind === 'write' || operation.kind === 'remove'
   );
-  const changed = JSON.stringify(nextConfig) !== JSON.stringify(input.config) || actionableSeed;
+  const changed = JSON.stringify(nextConfig) !== JSON.stringify(input.config)
+    || actionableSeed;
 
   return Object.freeze({
     source: normalized.source,

package/lib/agent-clients/registry.ts

@@ -104,6 +104,14 @@ function getAgentClientCapability(
   return getAgentClientAdapter(id).capabilities[capability];
 }
 
+function getAgentClientModelSelection(id: unknown) {
+  return getAgentClientAdapter(id).modelSelection;
+}
+
+function getAgentClientDelegationEvidence(id: unknown) {
+  return getAgentClientAdapter(id).delegationEvidence;
+}
+
 function listEnabledAgentClientAdaptersByCapability(
   state: AgentClientState,
   capability: AgentClientCapabilityId,
@@ -127,7 +135,15 @@ function createAgentClientManifest(): readonly AgentClientManifestEntry[] {
       ownedPathPrefixes: Object.freeze([...adapter.project.ownedPathPrefixes]),
       managed: Object.freeze([...adapter.project.managed]),
       merged: Object.freeze([...adapter.project.merged]),
-      ejected: Object.freeze([...adapter.project.ejected])
+      ejected: Object.freeze([...adapter.project.ejected]),
+      ...(adapter.project.customCommand === undefined
+        ? {}
+        : {
+          customCommand: Object.freeze({
+            ...adapter.project.customCommand,
+            frontmatter: Object.freeze({ ...adapter.project.customCommand.frontmatter })
+          })
+        })
     }))
   );
 }
@@ -137,6 +153,8 @@ export {
   createAgentClientManifest,
   getAgentClientAdapter,
   getAgentClientCapability,
+  getAgentClientDelegationEvidence,
+  getAgentClientModelSelection,
   listAgentClientAdapters,
   listEnabledAgentClientAdapters,
   listEnabledAgentClientAdaptersByCapability,

package/lib/agent-clients/schema.ts

@@ -29,6 +29,15 @@ const AGENT_CLIENTS_SCHEMA = {
           },
           installInSandbox: {
             type: 'boolean'
+          },
+          orchestration: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['executor', 'reviewer'],
+            properties: {
+              executor: { $ref: '#/definitions/orchestrationRolePolicy' },
+              reviewer: { $ref: '#/definitions/orchestrationRolePolicy' }
+            }
           }
         }
       }
@@ -48,6 +57,15 @@ const AGENT_CLIENTS_SCHEMA = {
     }
   },
   definitions: {
+    orchestrationRolePolicy: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['model', 'reasoningEffort'],
+      properties: {
+        model: { type: 'string', minLength: 1 },
+        reasoningEffort: { type: 'string', minLength: 1 }
+      }
+    },
     agentClientCapabilityId: {
       type: 'string',
       enum: [...AGENT_CLIENT_CAPABILITY_IDS]

package/lib/agent-clients/tokens.ts

@@ -0,0 +1,53 @@
+// Active AI collaborator short tokens — the write-side whitelist for the
+// activity log. Migrated from lib/task/commands/log.ts so that the write-side
+// internal commands and the rendering side share one definition. Historical
+// Gemini tokens remain read-only and are handled by classifyAgent below.
+export const KNOWN_AI_AGENTS: ReadonlySet<string> =
+  new Set(['claude', 'codex', 'antigravity', 'opencode', 'cursor']);
+
+// Long name -> short name mapping (HD-4, decision A): `claude-code` reuses the
+// existing orchestration precedent, and `antigravity-cli` is the active
+// client. `gemini-cli` is intentionally not writable.
+export const AGENT_LONG_NAMES: Readonly<Record<string, string>> = {
+  'claude-code': 'claude',
+  'antigravity-cli': 'antigravity'
+};
+
+export const AGENT_USAGE_HINT =
+  "agent must be a short token (claude/codex/antigravity/opencode/cursor), " +
+  "a long name (claude-code -> claude, antigravity-cli -> antigravity), or 'human'";
+
+// Read-side historical compatibility for activity-log rendering: `gemini` and
+// `gemini-cli` stay recognizable when displaying old logs, but are never
+// accepted by normalizeAgentToken (write side).
+const READ_KNOWN_AI_AGENTS: ReadonlySet<string> =
+  new Set([...KNOWN_AI_AGENTS, 'gemini']);
+
+const READ_AGENT_LONG_NAMES: Readonly<Record<string, string>> = {
+  ...AGENT_LONG_NAMES,
+  'gemini-cli': 'gemini'
+};
+
+// Strict write-side validation: the value must be exactly a short token, a
+// long name, or 'human'; returns the normalized short token, or null when
+// the value is not a recognized agent.
+export function normalizeAgentToken(value: string): string | null {
+  const trimmed = value.trim();
+  if (trimmed === 'human') return 'human';
+  if (KNOWN_AI_AGENTS.has(trimmed)) return trimmed;
+  const short = AGENT_LONG_NAMES[trimmed];
+  return short ?? null;
+}
+
+// Loose rendering-side classification: tolerates historical parenthetical
+// annotations; unknown tokens keep the `human` grouping but get a visible
+// signal. The "known AI token" test is `classifyAgent(value).status === 'ai'`.
+export function classifyAgent(raw: string):
+  { status: 'ai' | 'human' | 'unknown'; display: string } {
+  const token = raw.trim().split(/\s+/)[0]?.replace(/\(.*$/, '') ?? '';
+  if (token === '') return { status: 'unknown', display: 'human' };
+  if (token === 'human') return { status: 'human', display: 'human' };
+  if (READ_KNOWN_AI_AGENTS.has(token)) return { status: 'ai', display: token };
+  const short = READ_AGENT_LONG_NAMES[token];
+  return short ? { status: 'ai', display: short } : { status: 'unknown', display: 'human' };
+}

package/lib/agent-clients/types.ts

@@ -1,16 +1,27 @@
 const AGENT_CLIENT_IDS = [
   'claude-code',
   'codex',
-  'gemini-cli',
+  'antigravity-cli',
   'opencode'
 ] as const;
 
 type AgentClientId = (typeof AGENT_CLIENT_IDS)[number];
 
+type OrchestrationRolePolicy = Readonly<{
+  model: string;
+  reasoningEffort: string;
+}>;
+
+type OrchestrationModelPolicy = Readonly<{
+  executor: OrchestrationRolePolicy;
+  reviewer: OrchestrationRolePolicy;
+}>;
+
 type AgentClientConfig = Readonly<{
   id: AgentClientId;
   enabled: boolean;
   installInSandbox: boolean;
+  orchestration?: OrchestrationModelPolicy;
 }>;
 
 type AgentClientsConfig = readonly AgentClientConfig[];
@@ -21,6 +32,7 @@ type AgentClientState = Readonly<
     Readonly<{
       enabled: boolean;
       installInSandbox: boolean;
+      orchestration?: OrchestrationModelPolicy;
     }>
   >
 >;
@@ -68,6 +80,8 @@ export {
 };
 export type {
   AgentClientId,
+  OrchestrationRolePolicy,
+  OrchestrationModelPolicy,
   AgentClientConfig,
   AgentClientsConfig,
   AgentClientState,

package/lib/defaults.json

@@ -14,7 +14,7 @@
       "installInSandbox": true
     },
     {
-      "id": "gemini-cli",
+      "id": "antigravity-cli",
       "enabled": true,
       "installInSandbox": true
     },

package/lib/git/workflow.ts

@@ -1,4 +1,6 @@
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
 type CommandResult = { status: number | null; stdout: string; stderr: string };
 type GitRunner = (args: readonly string[], cwd: string) => CommandResult;
@@ -18,6 +20,10 @@ function value(runner: GitRunner, cwd: string, args: readonly string[], trim = t
   return result.status === 0 ? (trim ? result.stdout.trim() : result.stdout.replace(/\n$/, '')) : null;
 }
 
+function cleanMessage(message: string): string {
+  return message.replace(/(https?:\/\/)[^\s/@:]+(?::[^\s/@]*)?@/gi, '$1***@').trim();
+}
+
 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']);
@@ -97,5 +103,63 @@ function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string
   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 };
+type PushRebasedInput = {
+  cwd: string;
+  remote: string;
+  branch: string;
+  expectedOldHead: string;
+  newHead: string;
+  baseBranch: string;
+  expectedBaseHead: string;
+};
+
+function pushRebasedBranch(input: PushRebasedInput, runner: GitRunner = defaultRunner) {
+  const sha = /^[0-9a-f]{40}$/i;
+  const refName = /^(?!-)(?!.*\.\.)(?!.*(?:^|\/)\.)(?!.*[~^:?*\[\\\s])(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+  if (!input.remote || !refName.test(input.remote) || !refName.test(input.branch) || !refName.test(input.baseBranch) ||
+      !sha.test(input.expectedOldHead) || !sha.test(input.newHead) || !sha.test(input.expectedBaseHead)) {
+    return { status: 'failed' as const, changed: false, snapshot: null, operations: [], error: { code: 'GIT_REBASED_INPUT_INVALID', message: 'Remote, branches, and full 40-character SHAs are required' } };
+  }
+  const snapshot = inspectGitWorkflow(input.cwd, runner).snapshot;
+  if (!snapshot) return { status: 'failed' as const, changed: false, snapshot: null, operations: [], error: { code: 'GIT_INSPECT_FAILED', message: 'Unable to inspect Git repository' } };
+  if (snapshot.branch !== input.branch || snapshot.head !== input.newHead) {
+    return { status: 'failed' as const, changed: false, snapshot, operations: [], error: { code: 'GIT_LOCAL_IDENTITY_MISMATCH', message: 'Current branch or HEAD does not match the rebased intent' } };
+  }
+  const rebasePaths = ['rebase-merge', 'rebase-apply']
+    .map((name) => value(runner, input.cwd, ['rev-parse', '--git-path', name]))
+    .filter((candidate): candidate is string => Boolean(candidate));
+  if (snapshot.worktree.length > 0 || snapshot.staged.length > 0 ||
+      run(runner, input.cwd, ['rev-parse', '-q', '--verify', 'REBASE_HEAD']).status === 0 ||
+      rebasePaths.some((candidate) => fs.existsSync(path.isAbsolute(candidate) ? candidate : path.join(input.cwd, candidate)))) {
+    return { status: 'failed' as const, changed: false, snapshot, operations: [], error: { code: 'GIT_LOCAL_STATE_UNSAFE', message: 'Working tree must be clean with no rebase in progress' } };
+  }
+  const remoteRef = `refs/heads/${input.branch}`;
+  const baseRef = `refs/heads/${input.baseBranch}`;
+  const remoteHead = value(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, remoteRef])?.split(/\s+/)[0] ?? null;
+  if (remoteHead !== input.expectedOldHead) {
+    return { status: 'failed' as const, changed: false, snapshot, operations: [], error: { code: 'GIT_REMOTE_HEAD_MISMATCH', message: `Expected remote head ${input.expectedOldHead}, received ${remoteHead ?? 'unavailable'}` } };
+  }
+  const baseHead = value(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, baseRef])?.split(/\s+/)[0] ?? null;
+  if (baseHead !== input.expectedBaseHead) {
+    return { status: 'failed' as const, changed: false, snapshot, operations: [], error: { code: 'GIT_REMOTE_BASE_MISMATCH', message: `Expected base head ${input.expectedBaseHead}, received ${baseHead ?? 'unavailable'}` } };
+  }
+  if (run(runner, input.cwd, ['merge-base', '--is-ancestor', input.expectedBaseHead, input.newHead]).status !== 0) {
+    return { status: 'failed' as const, changed: false, snapshot, operations: [], error: { code: 'GIT_REBASED_ANCESTOR_MISMATCH', message: 'Rebased head does not contain the expected base head' } };
+  }
+  const pushed = run(runner, input.cwd, [
+    'push', `--force-with-lease=${remoteRef}:${input.expectedOldHead}`,
+    input.remote, `${input.newHead}:${remoteRef}`
+  ]);
+  if (pushed.status !== 0) {
+    const message = cleanMessage(pushed.stderr) || 'Rebased branch push was rejected';
+    return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'failed' as const, ref: input.branch, message }], error: { code: 'GIT_REBASED_PUSH_REJECTED', message } };
+  }
+  const verified = value(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, remoteRef])?.split(/\s+/)[0] ?? null;
+  if (verified !== input.newHead) {
+    return { status: 'failed' as const, changed: true, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'failed' as const, ref: input.branch, message: 'Remote ref verification failed' }], error: { code: 'GIT_REBASED_VERIFY_FAILED', message: `Expected pushed head ${input.newHead}, received ${verified ?? 'unavailable'}` } };
+  }
+  return { status: 'applied' as const, changed: true, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'applied' as const, ref: input.branch }], error: null };
+}
+
+export { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch };
+export type { CommandResult, GitRunner, PushRebasedInput };

package/lib/internal/agent-client.ts

@@ -7,12 +7,15 @@ import {
 } from '../agent-clients/config.ts';
 import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
 import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
+import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
+import { isAgentClientId } from '../agent-clients/types.ts';
 
-const USAGE = 'Usage: agent-infra-internal agent-client next-steps --skill <skill-name> [--task-ref <NN|TASK-id>] [--format text|json]\n';
+const USAGE = 'Usage: agent-infra-internal agent-client <next-steps|model-selection> [options]\n';
 
 type ParsedArgs = Readonly<{
   skillName: string;
   taskRef?: string;
+  version?: string;
   format: 'text' | 'json';
 }>;
 
@@ -38,11 +41,12 @@ function parseArgs(args: string[]): ParsedArgs | null {
   }
   let skillName: string | undefined;
   let taskRef: string | undefined;
+  let version: string | undefined;
   let format: 'text' | 'json' = 'text';
   const seen = new Set<string>();
   for (let index = 1; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (!['--skill', '--task-ref', '--format'].includes(flag)) {
+    if (!['--skill', '--task-ref', '--version', '--format'].includes(flag)) {
       failure('AGENT_CLIENT_PAYLOAD_INVALID', `unknown option '${flag}'`);
       return null;
     }
@@ -58,6 +62,7 @@ function parseArgs(args: string[]): ParsedArgs | null {
     seen.add(flag);
     if (flag === '--skill') skillName = value;
     if (flag === '--task-ref') taskRef = value;
+    if (flag === '--version') version = value;
     if (flag === '--format') {
       if (value !== 'text' && value !== 'json') {
         failure('AGENT_CLIENT_PAYLOAD_INVALID', "format must be 'text' or 'json'");
@@ -70,10 +75,59 @@ function parseArgs(args: string[]): ParsedArgs | null {
     failure('AGENT_CLIENT_PAYLOAD_INVALID', "option '--skill' is required");
     return null;
   }
-  return { skillName, ...(taskRef ? { taskRef } : {}), format };
+  return {
+    skillName,
+    ...(taskRef ? { taskRef } : {}),
+    ...(version ? { version } : {}),
+    format
+  };
 }
 
 function agentClient(args: string[] = []): void {
+  if (args[0] === 'model-selection') {
+    const values: Record<string, string> = {};
+    const seen = new Set<string>();
+    for (let index = 1; index < args.length; index += 1) {
+      const flag = args[index]!;
+      if (!['--client', '--format'].includes(flag) || seen.has(flag)) {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
+        return;
+      }
+      const value = args[++index];
+      if (!value || value.startsWith('--')) {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+        return;
+      }
+      seen.add(flag);
+      values[flag] = value;
+    }
+    const client = values['--client'];
+    const format = values['--format'] ?? 'text';
+    if (!isAgentClientId(client) || !['text', 'json'].includes(format)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', 'model-selection requires a known --client and text|json format');
+      return;
+    }
+    const context = getAgentClientModelSelection(client);
+    if (format === 'json') {
+      process.stdout.write(`${JSON.stringify({
+        status: 'resolved', changed: false, client, context, error: null
+      })}\n`);
+      return;
+    }
+    if (context.kind === 'interactive-only') {
+      process.stdout.write(`Model selection: interactive-only\nCommand: ${context.command}\n${context.guidance}\n`);
+    } else {
+      process.stdout.write(`Model selection: ${context.completeness} catalog\nSource: ${context.source}\n`);
+      for (const model of context.models) {
+        const efforts = model.reasoningEfforts?.length
+          ? ` (${model.reasoningEfforts.join(', ')})`
+          : '';
+        process.stdout.write(`- ${model.id}${efforts}\n`);
+      }
+      if (context.guidance) process.stdout.write(`${context.guidance}\n`);
+    }
+    return;
+  }
   const parsed = parseArgs(args);
   if (!parsed || process.exitCode) return;
 
@@ -98,7 +152,8 @@ function agentClient(args: string[] = []): void {
       state: clients.state,
       customTUIs: custom.items,
       skillName: parsed.skillName,
-      ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {})
+      ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
+      ...(parsed.version ? { version: parsed.version } : {})
     });
     if (parsed.format === 'json') {
       process.stdout.write(`${JSON.stringify({

package/lib/internal/git-workflow.ts

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.ts';
+import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch } from '../git/workflow.ts';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
 
@@ -23,6 +23,10 @@ function gitWorkflow(args: string[] = []): void {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     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 === 'push-rebased') {
+    const inputIndex = rest.indexOf('--input');
+    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
+    result = input ? pushRebasedBranch({ 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;

package/lib/internal/platform-checks.ts

@@ -2,9 +2,9 @@ import path from 'node:path';
 
 import {
   fetchPlatformCheckLogs,
-  inspectRequiredChecks,
+  inspectPullRequestReadiness,
   resolvePlatformCheckRun,
-  watchPlatformChecks
+  watchPullRequestReadiness
 } from '../platform/pr-checks.ts';
 import type { ChecksResult } from '../platform/pr-checks.ts';
 
@@ -70,7 +70,7 @@ async function platformChecks(args: string[] = []): Promise<void> {
   };
   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 === 'inspect') { finish(inspectPullRequestReadiness(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 }));
@@ -91,7 +91,7 @@ async function platformChecks(args: string[] = []): Promise<void> {
   process.once('SIGINT', abort);
   process.once('SIGTERM', abort);
   try {
-    finish(await watchPlatformChecks(taskRef, { cwd, intervalSeconds, deadlineSeconds, signal: controller.signal }));
+    finish(await watchPullRequestReadiness(taskRef, { cwd, intervalSeconds, deadlineSeconds, signal: controller.signal }));
   } finally {
     process.removeListener('SIGINT', abort);
     process.removeListener('SIGTERM', abort);

package/lib/internal/platform-comment.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   checkPlatformCommentOwner,
   listPlatformComments,
@@ -8,9 +9,11 @@ import {
 } from '../platform/issue-comments.ts';
 import type { CommentKind } from '../platform/issue-comments.ts';
 import type { PlatformResult } from '../platform/types.ts';
+import { backfillCompletionComments } from '../platform/completion-backfill.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 backfill <task-ref> --agent <agent> [--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>]
 `;
 
@@ -52,7 +55,7 @@ function readBodyFile(value: string, cwd: string): string {
 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; }
+  if (!operation || !['list', 'owner', 'backfill', '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; }
@@ -73,10 +76,22 @@ function platformComment(args: string[] = []): void {
     finish(checkPlatformCommentOwner(taskRef!, { cwd }));
     return;
   }
+  if (operation === 'backfill') {
+    const unexpected = Object.keys(parsed.values).find((key) => !['cwd', 'agent'].includes(key));
+    if (unexpected) { fail(`backfill does not accept '--${unexpected}'`); return; }
+    const agent = parsed.values.agent;
+    if (typeof agent !== 'string' || !agent) { fail('backfill requires --agent'); return; }
+    const normalizedAgent = normalizeAgentToken(agent);
+    if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); return; }
+    finish(backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
+    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; }
+  const normalizedAgent = normalizeAgentToken(agent);
+  if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); 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;
@@ -88,7 +103,7 @@ function platformComment(args: string[] = []): void {
   }
   finish(syncPlatformComment(taskRef!, {
     kind: kind as CommentKind,
-    agent,
+    agent: normalizedAgent,
     artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,
     body,
     backfill: parsed.values.backfill === true,

package/lib/internal/platform-issue.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   bindPlatformIssue,
   createPlatformIssue,
@@ -76,6 +77,9 @@ function platformIssue(args: string[] = []): void {
   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; }
+  const agent = normalizeAgentToken(values.agent);
+  if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
+  values.agent = agent;
   if (operation === 'create') {
     finish(createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
   }