@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/lib/agent-clients/adapter.ts

@@ -20,6 +20,28 @@ import type {
 
 type AgentClientCapabilities = AgentClientCapabilityMap;
 
+type AgentClientModelSelectionContext =
+  | Readonly<{
+      kind: 'catalog';
+      completeness: 'complete' | 'partial';
+      source: string;
+      models: readonly Readonly<{
+        id: string;
+        reasoningEfforts?: readonly string[];
+      }>[];
+      guidance?: string;
+    }>
+  | Readonly<{
+      kind: 'interactive-only';
+      command: string;
+      guidance: string;
+    }>;
+
+type AgentClientDelegationEvidence = Readonly<{
+  actualModel: 'host-event' | 'unavailable';
+  actualReasoningEffort: 'host-event' | 'spawn-ack' | 'unavailable';
+}>;
+
 type AgentClientSeedCommand = Readonly<{
   templates: Readonly<{
     en: string;
@@ -41,6 +63,8 @@ type AgentClientAdapter = Readonly<{
   displayName: string;
   invocation: string;
   capabilities: AgentClientCapabilities;
+  modelSelection: AgentClientModelSelectionContext;
+  delegationEvidence: AgentClientDelegationEvidence;
   project: AgentClientProjectDescriptor;
   sandbox: AgentClientSandboxDescriptor;
 }>;
@@ -211,6 +235,51 @@ function defineAgentClientAdapter(
     })
   ) as AgentClientCapabilities;
 
+  const modelSelection = candidate.modelSelection;
+  if (!modelSelection || typeof modelSelection !== 'object') {
+    throw new Error(`Agent Client '${candidate.id}' has an invalid model-selection context`);
+  }
+  let frozenModelSelection: AgentClientModelSelectionContext;
+  if (modelSelection.kind === 'interactive-only') {
+    if (!modelSelection.command?.trim() || !modelSelection.guidance?.trim()) {
+      throw new Error(`Agent Client '${candidate.id}' has an invalid model-selection context`);
+    }
+    frozenModelSelection = Object.freeze({ ...modelSelection });
+  } else if (
+    modelSelection.kind === 'catalog'
+    && ['complete', 'partial'].includes(modelSelection.completeness)
+    && typeof modelSelection.source === 'string'
+    && modelSelection.source.trim() !== ''
+    && Array.isArray(modelSelection.models)
+  ) {
+    const models = modelSelection.models.map((model) => {
+      if (!model?.id?.trim() || (model.reasoningEfforts && !Array.isArray(model.reasoningEfforts))) {
+        throw new Error(`Agent Client '${candidate.id}' has an invalid model-selection context`);
+      }
+      return Object.freeze({
+        id: model.id,
+        ...(model.reasoningEfforts
+          ? { reasoningEfforts: Object.freeze([...model.reasoningEfforts]) }
+          : {})
+      });
+    });
+    frozenModelSelection = Object.freeze({
+      ...modelSelection,
+      models: Object.freeze(models)
+    });
+  } else {
+    throw new Error(`Agent Client '${candidate.id}' has an invalid model-selection context`);
+  }
+
+  const evidence = candidate.delegationEvidence;
+  if (
+    !evidence
+    || !['host-event', 'unavailable'].includes(evidence.actualModel)
+    || !['host-event', 'spawn-ack', 'unavailable'].includes(evidence.actualReasoningEffort)
+  ) {
+    throw new Error(`Agent Client '${candidate.id}' has invalid delegation evidence`);
+  }
+
   if (
     typeof candidate.project !== 'object'
     || candidate.project === null
@@ -219,8 +288,8 @@ function defineAgentClientAdapter(
     throw new Error(`Agent Client '${candidate.id}' has an invalid project descriptor`);
   }
   const ownedPathPrefixes = candidate.project.ownedPathPrefixes;
-  if (!Array.isArray(ownedPathPrefixes) || ownedPathPrefixes.length === 0) {
-    throw new Error(`Agent Client '${candidate.id}' requires owned path prefixes`);
+  if (!Array.isArray(ownedPathPrefixes)) {
+    throw new Error(`Agent Client '${candidate.id}' has invalid owned path prefixes`);
   }
 
   const paths = ownedPathPrefixes.map((prefix) => {
@@ -441,6 +510,8 @@ function defineAgentClientAdapter(
     displayName: candidate.displayName,
     invocation: candidate.invocation,
     capabilities: Object.freeze(capabilities),
+    modelSelection: frozenModelSelection,
+    delegationEvidence: Object.freeze({ ...evidence }),
     project: Object.freeze({
       ownedPathPrefixes: Object.freeze(paths),
       ...projectAssets,
@@ -454,7 +525,9 @@ export { defineAgentClientAdapter };
 export type {
   AgentClientAdapter,
   AgentClientCapabilities,
+  AgentClientDelegationEvidence,
   AgentClientManifestEntry,
+  AgentClientModelSelectionContext,
   AgentClientProjectDescriptor,
   AgentClientSeedCommand,
   AgentClientRegistry

package/lib/agent-clients/adapters/antigravity-cli.ts

@@ -0,0 +1,65 @@
+import { defineAgentClientAdapter } from '../adapter.ts';
+import { hostJoin } from '../../sandbox/engines/wsl2-paths.ts';
+
+const antigravityCliAdapter = defineAgentClientAdapter({
+  id: 'antigravity-cli',
+  displayName: 'Antigravity CLI',
+  invocation: '/${skillName}',
+  capabilities: {
+    instructions: { level: 'compatible' },
+    skills: { level: 'integrated' },
+    commands: { level: 'integrated' },
+    hooks: { level: 'compatible' },
+    subagents: { level: 'unsupported' },
+    orchestration: { level: 'unsupported' },
+    sandbox: { level: 'integrated' },
+    verification: { level: 'compatible' }
+  },
+  modelSelection: {
+    kind: 'interactive-only',
+    command: '/model',
+    guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
+  },
+  delegationEvidence: {
+    actualModel: 'unavailable',
+    actualReasoningEffort: 'unavailable'
+  },
+  project: {
+    ownedPathPrefixes: [],
+    managed: [],
+    merged: [],
+    ejected: [],
+    seedCommands: []
+  },
+  sandbox: {
+    createTool: ({ home }) => ({
+      id: 'antigravity-cli',
+      name: 'Antigravity CLI',
+      install: {
+        type: 'shell',
+        cmd: 'curl -fsSL https://antigravity.google/cli/install.sh | bash -s -- --dir /home/devuser/.npm-global/bin'
+      },
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'antigravity-cli'),
+      containerMount: '/home/devuser/.gemini',
+      versionCmd: 'agy --version',
+      setupHint: 'Run agy inside the container to finish authentication.',
+      hostPreSeedFiles: [
+        {
+          hostPath: hostJoin(home, '.gemini', 'antigravity-cli', 'keybindings.json'),
+          sandboxName: 'antigravity-cli/keybindings.json'
+        },
+        {
+          hostPath: hostJoin(home, '.gemini', 'config', 'mcp_config.json'),
+          sandboxName: 'config/mcp_config.json'
+        }
+      ]
+    }),
+    aliases: [
+      { name: 'antigravity-yolo', command: 'agy --dangerously-skip-permissions; tput ed' },
+      { name: 'agy-yolo', command: 'agy --dangerously-skip-permissions; tput ed' }
+    ],
+    hooks: []
+  }
+});
+
+export { antigravityCliAdapter };

package/lib/agent-clients/adapters/claude-code.ts

@@ -11,10 +11,19 @@ const claudeCodeAdapter = defineAgentClientAdapter({
     commands: { level: 'integrated' },
     hooks: { level: 'integrated' },
     subagents: { level: 'experimental' },
-    orchestration: { level: 'experimental' },
+    orchestration: { level: 'unsupported' },
     sandbox: { level: 'integrated' },
     verification: { level: 'compatible' }
   },
+  modelSelection: {
+    kind: 'interactive-only',
+    command: '/model',
+    guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
+  },
+  delegationEvidence: {
+    actualModel: 'unavailable',
+    actualReasoningEffort: 'unavailable'
+  },
   project: {
     ownedPathPrefixes: ['.claude/'],
     managed: ['.claude/commands/', '.claude/agents/'],

package/lib/agent-clients/adapters/codex.ts

@@ -19,6 +19,15 @@ const codexAdapter = defineAgentClientAdapter({
     sandbox: { level: 'integrated' },
     verification: { level: 'compatible' }
   },
+  modelSelection: {
+    kind: 'interactive-only',
+    command: '/model',
+    guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
+  },
+  delegationEvidence: {
+    actualModel: 'unavailable',
+    actualReasoningEffort: 'unavailable'
+  },
   project: {
     ownedPathPrefixes: ['.codex/'],
     managed: ['.codex/hooks.json', '.codex/agents/'],

package/lib/agent-clients/adapters/index.ts

@@ -2,14 +2,14 @@ import { AGENT_CLIENT_IDS } from '../types.ts';
 import type { AgentClientAdapter } from '../adapter.ts';
 import { claudeCodeAdapter } from './claude-code.ts';
 import { codexAdapter } from './codex.ts';
-import { geminiCliAdapter } from './gemini-cli.ts';
+import { antigravityCliAdapter } from './antigravity-cli.ts';
 import { opencodeAdapter } from './opencode.ts';
 
 const adaptersById = new Map(
   [
     claudeCodeAdapter,
     codexAdapter,
-    geminiCliAdapter,
+    antigravityCliAdapter,
     opencodeAdapter
   ].map((adapter) => [adapter.id, adapter])
 );

package/lib/agent-clients/adapters/opencode.ts

@@ -17,6 +17,15 @@ const opencodeAdapter = defineAgentClientAdapter({
     sandbox: { level: 'integrated' },
     verification: { level: 'compatible' }
   },
+  modelSelection: {
+    kind: 'interactive-only',
+    command: '/models',
+    guidance: 'Use the host model picker for the complete model and reasoning-effort catalog.'
+  },
+  delegationEvidence: {
+    actualModel: 'unavailable',
+    actualReasoningEffort: 'unavailable'
+  },
   project: {
     ownedPathPrefixes: ['.opencode/'],
     managed: ['.opencode/commands/'],

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,
@@ -137,6 +145,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 };