@infinisys/is-devops 0.0.0-stage → 0.1.1

package/lib/git-repository.js

@@ -0,0 +1,1364 @@
+/**
+ * Audited local Git operations exposed through `infinity_git`.
+ *
+ * The service never trusts a model-supplied repository path: every command runs
+ * at the workspace's Git root, and every staged file must stay inside the
+ * session workspace (and, in Team Collaboration Mode, inside the role's write
+ * boundary). Push credentials come from `infinitySettings` and are injected
+ * through a URL-scoped credential helper in the child environment, so the
+ * access token never enters argv.
+ *
+ * Staging is recorded per seat (see `commit-scope.js`), so a commit contains
+ * exactly the paths that seat staged: another seat's staged work, or an edit
+ * made after the seat staged, cannot ride along.
+ */
+import { access, stat as statFile, unlink } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+import { commitIdentityFor } from './bot-identity.js';
+import {
+  commitStagedEntries,
+  forgetStagedEntries,
+  readStagedEntries,
+  recordStagedEntries,
+  withCommitLock,
+} from './commit-scope.js';
+import { DEFAULT_GIT_TIMEOUT_MS, PUSH_TIMEOUT_MS, runGit } from './git-exec.js';
+import {
+  LOG_FORMAT,
+  normalizeRepoPaths,
+  parseLogRecords,
+  parsePorcelainZ,
+  projectRemoteUrl,
+  validateBranchName,
+} from './git-parse.js';
+import { GitFoxError, parseProject } from './gitfox-api.js';
+
+/** Branches that reject force-with-lease from automation. */
+const PROTECTED_BRANCHES = new Set(['main', 'master']);
+
+/** Inline Git credential helper; reads the token from the child environment. */
+const CREDENTIAL_HELPER =
+  '!f() { printf \'username=%s\\npassword=%s\\n\' "$INFINITY_GIT_USERNAME" "$INFINITY_GIT_TOKEN"; }; f';
+
+/**
+ * @returns {GitFoxError} the error raised when GitFox credentials are absent.
+ */
+function notConnectedError() {
+  return new GitFoxError(
+    'GitFox is not connected. Open Settings → Infinity System and add an access token.',
+    { status: 503, code: 'not-configured' },
+  );
+}
+
+/**
+ * @param {{ canWriteGit?: boolean, actor?: string }} actor - resolved actor.
+ * @returns {void}
+ * @throws {GitFoxError} when the actor may not mutate Git state.
+ */
+function assertGitWrite(actor) {
+  if (actor?.canWriteGit === false) {
+    throw new GitFoxError(
+      `actor "${actor.actor ?? 'unknown'}" may not stage, commit or push in Team Collaboration Mode`,
+      { code: 'git-write-denied' },
+    );
+  }
+}
+
+/**
+ * @param {object} actor - resolved actor.
+ * @param {{ namespace: string, name: string }} project - target project.
+ * @returns {void}
+ * @throws {GitFoxError} when the actor may not write the pinned project.
+ */
+function assertProjectAllowed(actor, project) {
+  if (typeof actor?.isProjectAllowed !== 'function') return;
+  if (actor.isProjectAllowed(`${project.namespace}/${project.name}`) === false) {
+    throw new GitFoxError(
+      `actor "${actor.actor ?? 'unknown'}" may only push the team's pinned GitFox project`,
+      { code: 'git-project-denied' },
+    );
+  }
+}
+
+/**
+ * @param {object} actor - resolved actor.
+ * @param {string} path - workspace-relative path.
+ * @returns {void}
+ * @throws {GitFoxError} when the role's write boundary excludes the path.
+ */
+function assertRolePath(actor, path) {
+  if (typeof actor?.isPathAllowed !== 'function') return;
+  if (actor.isPathAllowed(path) === false) {
+    throw new GitFoxError(`actor "${actor.actor ?? 'unknown'}" may not write "${path}"`, {
+      code: 'git-path-denied',
+    });
+  }
+}
+
+/**
+ * Convert a workspace-relative path into a repo-relative path and prove it did
+ * not escape the workspace.
+ *
+ * @param {{ workspaceRoot: string, root: string }} context - repository context.
+ * @param {string} path - normalized workspace-relative path.
+ * @returns {string} repo-relative path.
+ * @throws {GitFoxError} when the path escapes the workspace.
+ */
+function toRepoPath(context, path) {
+  const absolute = resolve(context.workspaceRoot, path);
+  const workspaceRelative = relative(context.workspaceRoot, absolute);
+  if (workspaceRelative.startsWith('..') || isAbsolute(workspaceRelative)) {
+    throw new GitFoxError(`path "${path}" escapes the session workspace`, {
+      code: 'git-path-denied',
+    });
+  }
+  const repoPath = relative(context.root, absolute).replaceAll('\\', '/');
+  if (repoPath === '' || repoPath.startsWith('..') || isAbsolute(repoPath)) {
+    throw new GitFoxError(`path "${path}" is outside the Git repository`, {
+      code: 'git-path-denied',
+    });
+  }
+  return repoPath;
+}
+
+/**
+ * Validate every staged path against the workspace and role boundary.
+ *
+ * @param {object} actor - resolved actor.
+ * @param {{ workspaceRoot: string, root: string }} context - repository context.
+ * @param {string[]} paths - repo-relative paths from the index.
+ * @returns {void}
+ */
+function assertStagedPaths(actor, context, paths) {
+  for (const path of paths) {
+    const absolute = resolve(context.root, path);
+    const workspaceRelative = relative(context.workspaceRoot, absolute);
+    if (workspaceRelative.startsWith('..') || isAbsolute(workspaceRelative)) {
+      throw new GitFoxError(`staged path "${path}" is outside the session workspace`, {
+        code: 'git-path-denied',
+      });
+    }
+    assertRolePath(actor, workspaceRelative.replaceAll('\\', '/'));
+  }
+}
+
+/**
+ * Build Git config arguments that scope our helper to the GitFox origin and
+ * remove any ambient helper that could answer for a different host.
+ *
+ * @param {string} origin - URL origin of the push target.
+ * @returns {string[]} `-c key=value` pairs.
+ */
+function credentialConfigArgs(origin) {
+  const section = `credential.${origin}`;
+  return [
+    '-c',
+    'credential.helper=',
+    '-c',
+    `${section}.helper=`,
+    '-c',
+    `${section}.helper=${CREDENTIAL_HELPER}`,
+  ];
+}
+
+/**
+ * Make a Git HTTP authentication failure actionable without echoing the token.
+ *
+ * The built-in `infinity-system` OAuth client historically requested only
+ * `read_repository`; GitFox correctly rejects a push from such a token. The
+ * message points at the two working configurations instead of leaving the raw
+ * "403" from the workhorse.
+ *
+ * @param {unknown} error - thrown push error.
+ * @returns {unknown} mapped error.
+ */
+function pushFailure(error) {
+  if (!(error instanceof GitFoxError)) return error;
+  const message = error.message.toLowerCase();
+  const scopeDenied =
+    message.includes('write_repository') || message.includes('repository:write');
+  if (scopeDenied) {
+    return new GitFoxError(
+      'GitFox rejected the push: the OAuth2 grant lacks write_repository. Re-authorize the GitFox connection in Settings → Infinity System (the connection only holds the scopes it was signed in with), or use a PAT with write_repository.',
+      { status: 403, code: 'push-scope-denied' },
+    );
+  }
+  const unauthenticated =
+    message.includes('authentication failed') || message.includes('401 unauthorized');
+  if (unauthenticated) {
+    return new GitFoxError(
+      'GitFox rejected the push credentials. Reconnect GitFox in Settings → Infinity System or use a valid PAT.',
+      { status: 401, code: 'push-unauthenticated' },
+    );
+  }
+  return error;
+}
+
+/**
+ * Format a bounded push summary without leaking credentials.
+ *
+ * @param {string} stdout - `git push --porcelain` output.
+ * @param {string} stderr - Git stderr.
+ * @returns {string} bounded summary.
+ */
+function pushSummary(stdout, stderr) {
+  const text = `${stdout.trim()}\n${stderr.trim()}`.trim();
+  return text.length <= 8_000 ? text : `${text.slice(0, 8_000)}\n… (truncated)`;
+}
+
+/**
+ * @param {number | undefined} value - requested log size.
+ * @returns {number} bounded positive count.
+ */
+function logLimit(value) {
+  const parsed = Number(value ?? 20);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new GitFoxError('limit must be a positive integer', { code: 'invalid-arguments' });
+  }
+  return Math.min(parsed, 100);
+}
+
+/**
+ * Resolve the workspace's Git root.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {string} workspaceRoot - session working directory.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<{ workspaceRoot: string, root: string }>} repository context.
+ */
+async function contextOf(runtime, workspaceRoot, signal) {
+  const cwd = isAbsolute(workspaceRoot) ? workspaceRoot : resolve(workspaceRoot);
+  const { stdout } = await runtime.runGitImpl({
+    args: ['rev-parse', '--show-toplevel'],
+    cwd,
+    signal,
+  });
+  const root = stdout.trim();
+  if (root === '') {
+    throw new GitFoxError('workspace is not a Git repository', { code: 'not-a-repository' });
+  }
+  return { workspaceRoot: cwd, root };
+}
+
+/**
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<string | null>} current branch, or null when detached.
+ */
+async function branchOf(runtime, context, signal) {
+  try {
+    const { stdout } = await runtime.runGitImpl({
+      args: ['symbolic-ref', '--quiet', '--short', 'HEAD'],
+      cwd: context.root,
+      signal,
+    });
+    return stdout.trim() || null;
+  } catch (error) {
+    if (error instanceof GitFoxError && error.code === 'git-failed') return null;
+    throw error;
+  }
+}
+
+/**
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<string>} HEAD commit.
+ */
+async function headSha(runtime, context, signal) {
+  try {
+    const { stdout } = await runtime.runGitImpl({
+      args: ['rev-parse', '--verify', 'HEAD'],
+      cwd: context.root,
+      signal,
+    });
+    return stdout.trim();
+  } catch (error) {
+    if (error instanceof GitFoxError && error.code === 'git-failed') {
+      throw new GitFoxError('the repository has no commits yet', { code: 'no-commits' });
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<string[]>} repo-relative staged paths.
+ */
+async function stagedPaths(runtime, context, signal) {
+  const { stdout } = await runtime.runGitImpl({
+    args: ['diff', '--cached', '--name-only', '-z'],
+    cwd: context.root,
+    signal,
+  });
+  return stdout.split('\0').filter((path) => path !== '');
+}
+
+/**
+ * Parse NUL-separated `--name-status` records.
+ *
+ * @param {string} raw - Git output.
+ * @returns {{ path: string, status: string }[]} entries.
+ */
+function parseNameStatusZ(raw) {
+  const tokens = raw.split('\0').filter((token) => token !== '');
+  const entries = [];
+  for (let index = 0; index + 1 < tokens.length; index += 2) {
+    const status = tokens[index];
+    const path = tokens[index + 1];
+    if (typeof status === 'string' && status !== '' && typeof path === 'string') {
+      entries.push({ path, status: status.slice(0, 1) });
+    }
+  }
+  return entries;
+}
+
+/**
+ * The index as paths with their status letter.
+ *
+ * `status` is what makes "this change deletes a work record" distinguishable
+ * from "this change adds one": a deletion is the correct fix for a record that
+ * already sits in the tree, and callers that only see paths cannot tell.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @param {string[]} [paths] - optional repo-relative pathspec.
+ * @returns {Promise<{ path: string, status: string }[]>} staged entries.
+ */
+async function stagedEntries(runtime, context, signal, paths) {
+  const args = ['diff', '--cached', '--name-status', '-z', '--no-renames'];
+  if (Array.isArray(paths) && paths.length > 0) args.push('--', ...paths);
+  const { stdout } = await runtime.runGitImpl({ args, cwd: context.root, signal });
+  return parseNameStatusZ(stdout);
+}
+
+/**
+ * Resolve the repository's Git directory.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<string>} absolute Git directory.
+ */
+async function gitDirOf(runtime, context, signal) {
+  const { stdout } = await runtime.runGitImpl({
+    args: ['rev-parse', '--absolute-git-dir'],
+    cwd: context.root,
+    signal,
+  });
+  return stdout.trim();
+}
+
+/**
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<string | null>} HEAD commit, or null before the first commit.
+ */
+async function headOrNull(runtime, context, signal) {
+  try {
+    return await headSha(runtime, context, signal);
+  } catch (error) {
+    if (error instanceof GitFoxError && error.code === 'no-commits') return null;
+    throw error;
+  }
+}
+
+/**
+ * Read index records (mode and blob) for the given paths.
+ *
+ * The blob is the content that was staged, so replaying it later commits what
+ * the seat staged even if the worktree file has changed since.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {string[]} paths - repo-relative paths.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<{ path: string, mode: string, sha: string }[]>} records.
+ */
+async function indexRecordsOf(runtime, context, paths, signal) {
+  const { stdout } = await runtime.runGitImpl({
+    args: ['ls-files', '-s', '-z', '--', ...paths],
+    cwd: context.root,
+    signal,
+  });
+  const records = [];
+  for (const record of stdout.split('\0')) {
+    if (record === '') continue;
+    const tab = record.indexOf('\t');
+    if (tab === -1) continue;
+    const [mode, sha, stage] = record.slice(0, tab).split(' ');
+    if (stage !== '0' || typeof mode !== 'string' || typeof sha !== 'string') continue;
+    records.push({ path: record.slice(tab + 1), mode, sha });
+  }
+  return records;
+}
+
+/**
+ * Paths tracked at HEAD, for telling a staged modification from an addition.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<string[]>} repo-relative paths.
+ */
+async function trackedPaths(runtime, context, signal) {
+  const { stdout } = await runtime.runGitImpl({
+    args: ['ls-tree', '-r', '--name-only', '-z', 'HEAD'],
+    cwd: context.root,
+    signal,
+  });
+  return stdout.split('\0').filter((path) => path !== '');
+}
+
+/**
+ * The entries a `stage` added, keyed for the seat's ledger.
+ *
+ * Deletions carry no blob: the entry records that the path must leave the tree.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {string[]} paths - repo-relative pathspec.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<{ path: string, mode?: string, sha?: string, deleted?: boolean }[]>} entries.
+ */
+async function stagedRecordsOf(runtime, context, paths, signal) {
+  const changes = await stagedEntries(runtime, context, signal, paths);
+  const modified = changes.filter((change) => change.status !== 'D').map((change) => change.path);
+  const records = modified.length > 0
+    ? await indexRecordsOf(runtime, context, modified, signal)
+    : [];
+  const byPath = new Map(records.map((record) => [record.path, record]));
+  return changes
+    .map((change) => (change.status === 'D'
+      ? { path: change.path, deleted: true }
+      : byPath.get(change.path)))
+    .filter((entry) => entry !== undefined);
+}
+
+/**
+ * Explain an empty commit target in the terms the caller can act on.
+ *
+ * When the working tree holds staged work this seat did not stage, say so: the
+ * old behaviour put that work into the commit without naming it.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @param {string[]} requested - paths the caller named, if any.
+ * @returns {Promise<string>} message.
+ */
+async function nothingStagedText(runtime, context, signal, requested) {
+  if (requested.length > 0) {
+    return `nothing to commit for ${requested.join(', ')}: those paths already match the newest commit or hold no staged change`;
+  }
+  const shared = await stagedPaths(runtime, context, signal);
+  if (shared.length === 0) {
+    return 'there is nothing staged to commit: stage the paths first — a commit contains exactly what this seat staged';
+  }
+  const shown = shared.slice(0, 5).join(', ');
+  const more = shared.length > 5 ? ` and ${shared.length - 5} more` : '';
+  return `nothing is staged for this seat, but ${shared.length} path(s) were staged elsewhere in this working tree (${shown}${more}); those belong to another seat and cannot enter your commit — stage the paths you mean to commit`;
+}
+
+/**
+ * @param {{ path: string }[]} entries - ledger entries.
+ * @param {string[]} repoPaths - repo-relative pathspec.
+ * @returns {{ path: string }[]} entries the pathspec names.
+ */
+function selectEntries(entries, repoPaths) {
+  return entries.filter((entry) => repoPaths.some(
+    (path) => entry.path === path || entry.path.startsWith(`${path}/`),
+  ));
+}
+
+/**
+ * Build the local ref and worktree maintenance operations.
+ *
+ * A seat can cut branches and linked worktrees while gathering evidence; with
+ * no way to remove them the checkout keeps refs and metadata no tool can see or
+ * clean (issue #56, note on the R-0016 leftovers).
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @returns {object} delete_branch/prune_worktrees methods.
+ */
+function createRefOperations(runtime) {
+  return {
+    /**
+     * Delete a local branch.
+     *
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, branch?: unknown, force?: boolean }} options - invocation.
+     * @returns {Promise<object>} deleted branch.
+     */
+    async delete_branch(actor, { workspaceRoot, signal, branch, force = false }) {
+      assertGitWrite(actor);
+      const name = validateBranchName(branch);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const current = await branchOf(runtime, context, signal);
+      if (current === name) {
+        throw new GitFoxError(`"${name}" is checked out; switch to another branch before deleting it`, {
+          code: 'branch-in-use',
+        });
+      }
+      if (PROTECTED_BRANCHES.has(name)) {
+        throw new GitFoxError(
+          `deleting "${name}" is denied; remove it from a terminal outside the team if that is really intended`,
+          { code: 'protected-branch' },
+        );
+      }
+      const ref = `refs/heads/${name}`;
+      if (!(await refExists(runtime, context, ref, signal))) {
+        throw new GitFoxError(`there is no local branch named "${name}"`, { code: 'branch-not-found' });
+      }
+      try {
+        await runtime.runGitImpl({
+          args: ['branch', force === true ? '-D' : '-d', '--', name],
+          cwd: context.root,
+          signal,
+        });
+      } catch (error) {
+        const stillThere = await refExists(runtime, context, ref, signal);
+        if (error instanceof GitFoxError && error.code === 'git-failed' && stillThere
+          && !(await isMergedIntoHead(runtime, context, ref, signal))) {
+          throw new GitFoxError(
+            `"${name}" is not fully merged; delete it with force: true if its commits are meant to be discarded`,
+            { code: 'branch-not-merged' },
+          );
+        }
+        throw error;
+      }
+      return { deleted: name, repository: context.root };
+    },
+
+    /**
+     * Remove worktree metadata whose directory no longer exists.
+     *
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal }} options - invocation.
+     * @returns {Promise<object>} pruned worktrees.
+     */
+    async prune_worktrees(actor, { workspaceRoot, signal }) {
+      assertGitWrite(actor);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const { stdout, stderr } = await runtime.runGitImpl({
+        args: ['worktree', 'prune', '--verbose'],
+        cwd: context.root,
+        signal,
+      });
+      const pruned = `${stdout}\n${stderr}`
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '');
+      return { pruned, repository: context.root };
+    },
+  };
+}
+
+/**
+ * Build the read-only operations.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @returns {object} status/diff/log methods.
+ */
+function createReadOperations(runtime) {
+  return {
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal }} options - invocation.
+     * @returns {Promise<object>} branch and porcelain entries.
+     */
+    async status(actor, { workspaceRoot, signal }) {
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const branch = await branchOf(runtime, context, signal);
+      const { stdout } = await runtime.runGitImpl({
+        args: ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+        cwd: context.root,
+        signal,
+      });
+      const entries = parsePorcelainZ(stdout);
+      const gitDir = await gitDirOf(runtime, context, signal);
+      const staged = await readStagedEntries(gitDir, actor?.actor);
+      const mine = new Set(staged.map((entry) => entry.path));
+      const shared = await stagedPaths(runtime, context, signal);
+      return {
+        repository: context.root,
+        branch,
+        detached: branch === null,
+        clean: entries.length === 0,
+        entries,
+        staged: staged.map((entry) => (entry.deleted === true ? `${entry.path} (deleted)` : entry.path)),
+        stagedByOthers: shared.filter((path) => !mine.has(path)),
+        actor: actor?.actor ?? 'agent',
+      };
+    },
+
+    /**
+     * The entries this seat's next commit would contain.
+     *
+     * The seat's own ledger is the answer; without an identity the shared index
+     * is still readable for callers that only need "what is staged somewhere".
+     *
+     * @param {object} [actor] - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal }} options - invocation.
+     * @returns {Promise<{ path: string, status: string }[]>} staged entries.
+     */
+    async stagedFiles(actor, { workspaceRoot, signal }) {
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      if (actor === undefined || actor === null) {
+        return stagedEntries(runtime, context, signal);
+      }
+      const gitDir = await gitDirOf(runtime, context, signal);
+      const entries = await readStagedEntries(gitDir, actor?.actor);
+      if (entries.length === 0) return [];
+      const head = await headOrNull(runtime, context, signal);
+      const tracked = new Set(head === null ? [] : await trackedPaths(runtime, context, signal));
+      return entries.map((entry) => {
+        if (entry.deleted === true) return { path: entry.path, status: 'D' };
+        return { path: entry.path, status: tracked.has(entry.path) ? 'M' : 'A' };
+      });
+    },
+
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, staged?: boolean, paths?: unknown, stat?: boolean }} options - invocation.
+     * @returns {Promise<object>} diff text.
+     */
+    async diff(actor, { workspaceRoot, signal, staged = false, paths, stat = false }) {
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const normalized = normalizeRepoPaths(paths).map((path) => toRepoPath(context, path));
+      const args = ['diff', '--no-ext-diff', '--no-color'];
+      if (staged === true) args.push('--cached');
+      if (stat === true) args.push('--stat');
+      args.push('--', ...normalized);
+      const { stdout } = await runtime.runGitImpl({ args, cwd: context.root, signal });
+      return {
+        repository: context.root,
+        staged: staged === true,
+        text: stdout,
+        empty: stdout.trim() === '',
+      };
+    },
+
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, limit?: number, paths?: unknown }} options - invocation.
+     * @returns {Promise<object>} recent commits.
+     */
+    async log(actor, { workspaceRoot, signal, limit, paths }) {
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const normalized = normalizeRepoPaths(paths).map((path) => toRepoPath(context, path));
+      const args = ['log', `--max-count=${logLimit(limit)}`, `--pretty=format:${LOG_FORMAT}`];
+      args.push('--', ...normalized);
+      try {
+        const { stdout } = await runtime.runGitImpl({ args, cwd: context.root, signal });
+        return { repository: context.root, commits: parseLogRecords(stdout) };
+      } catch (error) {
+        if (error instanceof GitFoxError && error.code === 'git-failed') {
+          return { repository: context.root, commits: [] };
+        }
+        throw error;
+      }
+    },
+
+    /**
+     * Read the workspace's `origin` remote without mutating anything. Project
+     * discovery needs the URL even when the workspace is not yet a checkout.
+     *
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal }} options - invocation.
+     * @returns {Promise<{ repository: string | null, remote: string | null }>} origin URL.
+     */
+    async remoteUrl(actor, { workspaceRoot, signal }) {
+      let context;
+      try {
+        context = await contextOf(runtime, workspaceRoot, signal);
+      } catch (error) {
+        if (error instanceof GitFoxError && ['not-a-repository', 'git-failed'].includes(error.code)) {
+          return { repository: null, remote: null };
+        }
+        throw error;
+      }
+      try {
+        const { stdout } = await runtime.runGitImpl({
+          args: ['remote', 'get-url', 'origin'],
+          cwd: context.root,
+          signal,
+        });
+        const remote = stdout.trim();
+        return { repository: context.root, remote: remote === '' ? null : remote };
+      } catch {
+        return { repository: context.root, remote: null };
+      }
+    },
+  };
+}
+
+/**
+ * Build the index operations.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @returns {object} stage/unstage methods.
+ */
+function createIndexOperations(runtime) {
+  return {
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, paths?: unknown }} options - invocation.
+     * @returns {Promise<object>} staged paths.
+     */
+    async stage(actor, { workspaceRoot, signal, paths }) {
+      assertGitWrite(actor);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const normalized = normalizeRepoPaths(paths, { required: true });
+      const repoPaths = normalized.map((path) => toRepoPath(context, path));
+      assertStagedPaths(actor, context, repoPaths);
+      await runtime.runGitImpl({ args: ['add', '--', ...repoPaths], cwd: context.root, signal });
+      const gitDir = await gitDirOf(runtime, context, signal);
+      const entries = await stagedRecordsOf(runtime, context, repoPaths, signal);
+      await recordStagedEntries(gitDir, actor?.actor, entries);
+      return { staged: normalized, repository: context.root };
+    },
+
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, paths?: unknown }} options - invocation.
+     * @returns {Promise<object>} unstaged paths.
+     */
+    async unstage(actor, { workspaceRoot, signal, paths }) {
+      assertGitWrite(actor);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const normalized = normalizeRepoPaths(paths, { required: true });
+      const repoPaths = normalized.map((path) => toRepoPath(context, path));
+      assertStagedPaths(actor, context, repoPaths);
+      const gitDir = await gitDirOf(runtime, context, signal);
+      const targets = selectEntries(await readStagedEntries(gitDir, actor?.actor), repoPaths);
+      if (targets.length === 0) {
+        return {
+          unstaged: [],
+          repository: context.root,
+          note: 'nothing was staged by this seat under those paths; another seat’s staging is untouched',
+        };
+      }
+      const dropped = targets.map((entry) => entry.path);
+      try {
+        await runtime.runGitImpl({
+          args: ['restore', '--staged', '--', ...dropped],
+          cwd: context.root,
+          signal,
+        });
+      } catch (error) {
+        if (!(error instanceof GitFoxError) || !/HEAD|unborn|ambiguous/i.test(error.message)) {
+          throw error;
+        }
+        await runtime.runGitImpl({
+          args: ['rm', '--cached', '--quiet', '--', ...dropped],
+          cwd: context.root,
+          signal,
+        });
+      }
+      await forgetStagedEntries(gitDir, actor?.actor, dropped);
+      return { unstaged: dropped, repository: context.root };
+    },
+  };
+}
+
+/** Age after which a leftover `index.lock` is debris from a dead Git process. */
+const STALE_LOCK_MS = 30_000;
+
+/**
+ * @param {unknown} value - model-supplied start point.
+ * @returns {void}
+ * @throws {GitFoxError} when the value could become an option or a bad ref.
+ */
+function assertStartPoint(value) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  const hasControl = [...text].some((character) => character.charCodeAt(0) <= 0x20 || character === '\0');
+  if (text === '') return;
+  if (hasControl || text.length > 200 || text.startsWith('-')) {
+    throw new GitFoxError(`invalid start point "${String(value)}"`, { code: 'invalid-arguments' });
+  }
+}
+
+/**
+ * Remove a leftover `index.lock` that no live Git process can still own.
+ *
+ * A crashed or killed command leaves the lock behind, and every later mutation
+ * then fails with "Unable to create .../index.lock: File exists" although
+ * nothing holds it. The tool repairs that state itself; the user is never asked
+ * to delete a file by hand.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<boolean>} whether a stale lock was removed.
+ */
+async function clearStaleLock(runtime, context, signal) {
+  try {
+    const { stdout } = await runtime.runGitImpl({
+      args: ['rev-parse', '--git-path', 'index.lock'],
+      cwd: context.root,
+      signal,
+    });
+    const lock = resolve(context.root, stdout.trim());
+    const info = await statFile(lock);
+    if (Date.now() - info.mtimeMs < STALE_LOCK_MS) return false;
+    await unlink(lock);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether one revision resolves to a commit in this repository.
+ *
+ * Git is run under the user's locale, so failure messages are translated. Every
+ * branch decision here is taken from an exit code instead of a message, so the
+ * tool behaves the same in Chinese and English environments.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {string} revision - branch, tag or commit-ish.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<boolean>} whether the revision exists.
+ */
+async function refExists(runtime, context, revision, signal) {
+  try {
+    await runtime.runGitImpl({
+      args: ['rev-parse', '--verify', '--quiet', revision],
+      cwd: context.root,
+      signal,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Report whether a ref is an ancestor of HEAD.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {string} ref - ref to test.
+ * @param {AbortSignal | undefined} signal - caller cancellation.
+ * @returns {Promise<boolean>} whether HEAD already contains the ref.
+ */
+async function isMergedIntoHead(runtime, context, ref, signal) {
+  try {
+    await runtime.runGitImpl({
+      args: ['merge-base', '--is-ancestor', ref, 'HEAD'],
+      cwd: context.root,
+      signal,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Park uncommitted work so a switch can proceed.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {string} target - requested branch, used in the stash message.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<boolean>} whether anything was stashed.
+ */
+async function stashWorktree(runtime, context, target, signal) {
+  const { stdout } = await runtime.runGitImpl({
+    args: ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+    cwd: context.root,
+    signal,
+  });
+  if (parsePorcelainZ(stdout).length === 0) return false;
+  try {
+    await runtime.runGitImpl({
+      args: ['stash', 'push', '--quiet', '--include-untracked', '-m', `infinity_git: carry onto ${target}`],
+      cwd: context.root,
+      signal,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Put the parked work back, reporting conflicts instead of throwing.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - cancellation.
+ * @returns {Promise<{ restored: boolean, files: string[] }>} restore outcome.
+ */
+async function restoreWorktree(runtime, context, signal) {
+  try {
+    await runtime.runGitImpl({ args: ['stash', 'pop', '--quiet'], cwd: context.root, signal });
+    return { restored: true, files: [] };
+  } catch {
+    return { restored: false, files: await conflictedPaths(runtime, context, signal) };
+  }
+}
+
+/**
+ * Build the branch checkout operation.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @returns {object} switch method.
+ */
+function createCheckoutOperations(runtime) {
+  return {
+    /**
+     * Check out a branch, creating it from `from` when asked. Uncommitted work
+     * is carried across the switch (stash, switch, pop) so a dirty worktree
+     * left by an earlier run never turns into a request for the user to run Git
+     * by hand.
+     *
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, branch?: unknown, create?: boolean, from?: unknown }} options - invocation.
+     * @returns {Promise<object>} checkout record.
+     */
+    async switch(actor, { workspaceRoot, signal, branch, create = false, from }) {
+      assertGitWrite(actor);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const target = validateBranchName(branch);
+      const start = typeof from === 'string' ? from.trim() : '';
+      assertStartPoint(start);
+      if (create === true && (await refExists(runtime, context, `refs/heads/${target}`, signal))) {
+        throw new GitFoxError(
+          `branch "${target}" already exists; call switch without "create" to check it out`,
+          { code: 'branch-exists' },
+        );
+      }
+      if (start !== '' && !(await refExists(runtime, context, `${start}^{commit}`, signal))) {
+        throw new GitFoxError(`"${start}" does not resolve to a commit in this repository`, {
+          code: 'unknown-start-point',
+        });
+      }
+      const previous = await branchOf(runtime, context, signal);
+      await clearStaleLock(runtime, context, signal);
+      const args = create === true
+        ? ['switch', '-c', target, ...(start === '' ? [] : [start])]
+        : ['switch', target];
+      const carried = await stashWorktree(runtime, context, target, signal);
+      try {
+        await runtime.runGitImpl({ args, cwd: context.root, signal });
+      } catch (error) {
+        if (carried) await restoreWorktree(runtime, context, signal);
+        throw error;
+      }
+      const branchNow = await branchOf(runtime, context, signal);
+      const commit = await headSha(runtime, context, signal);
+      if (carried) {
+        const restore = await restoreWorktree(runtime, context, signal);
+        if (!restore.restored) {
+          return {
+            status: 'conflicted',
+            branch: branchNow,
+            previous,
+            created: create === true,
+            carried: true,
+            commit,
+            files: restore.files,
+            note: 'the switch happened and the uncommitted work is parked in a stash; resolve the listed files, stage them, then drop the stash entry',
+          };
+        }
+      }
+      const { stdout } = await runtime.runGitImpl({
+        args: ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+        cwd: context.root,
+        signal,
+      });
+      const entries = parsePorcelainZ(stdout);
+      return {
+        branch: branchNow,
+        previous,
+        created: create === true,
+        carried,
+        commit,
+        detached: branchNow === null,
+        clean: entries.length === 0,
+        entries,
+      };
+    },
+  };
+}
+
+/**
+ * Resolve the exact lease value for a force push.
+ *
+ * `--force-with-lease` without an explicit expected value consults a
+ * remote-tracking ref, which a direct-URL push does not maintain. Reading the
+ * current remote head first makes the lease meaningful: if anyone pushes in
+ * between, Git rejects the force push instead of overwriting their work.
+ *
+ * @param {{ runGitImpl: typeof runGit }} runtime - service wiring.
+ * @param {{ credentialArgs: string[], env: Record<string, string>, context: { root: string }, remote: string, branch: string, signal?: AbortSignal }} input - push wiring.
+ * @returns {Promise<string[]>} lease argument, or an empty list.
+ */
+async function forceLease(runtime, input) {
+  const { stdout } = await runtime.runGitImpl({
+    args: [...input.credentialArgs, 'ls-remote', '--heads', input.remote, `refs/heads/${input.branch}`],
+    cwd: input.context.root,
+    env: input.env,
+    timeoutMs: PUSH_TIMEOUT_MS,
+    signal: input.signal,
+  });
+  const remoteSha = stdout.trim().split(/\s+/)[0] ?? '';
+  return [`--force-with-lease=refs/heads/${input.branch}:${remoteSha}`];
+}
+
+/**
+ * Build the commit and push operations.
+ *
+ * @param {{ runGitImpl: typeof runGit, resolveConfig: () => Promise<{ baseUrl: string, token: string }> }} runtime - service wiring.
+ * @returns {object} commit/push methods.
+ */
+function createPublishOperations(runtime) {
+  return {
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, message?: unknown, paths?: unknown }} options - invocation.
+     * @returns {Promise<object>} commit record.
+     */
+    async commit(actor, { workspaceRoot, signal, message, paths }) {
+      assertGitWrite(actor);
+      const text = typeof message === 'string' ? message.trim() : '';
+      if (text === '') {
+        throw new GitFoxError('commit message is required', { code: 'invalid-arguments' });
+      }
+      if (text.length > 20_000 || text.includes('\0')) {
+        throw new GitFoxError('commit message is too long or contains NUL', {
+          code: 'invalid-arguments',
+        });
+      }
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const gitDir = await gitDirOf(runtime, context, signal);
+      const normalized = normalizeRepoPaths(paths);
+      let targets = await readStagedEntries(gitDir, actor?.actor);
+      if (normalized.length > 0) {
+        const repoPaths = normalized.map((path) => toRepoPath(context, path));
+        assertStagedPaths(actor, context, repoPaths);
+        await runtime.runGitImpl({ args: ['add', '--', ...repoPaths], cwd: context.root, signal });
+        const records = await stagedRecordsOf(runtime, context, repoPaths, signal);
+        await recordStagedEntries(gitDir, actor?.actor, records);
+        targets = selectEntries(await readStagedEntries(gitDir, actor?.actor), repoPaths);
+      }
+      if (targets.length === 0) {
+        throw new GitFoxError(await nothingStagedText(runtime, context, signal, normalized), {
+          code: 'nothing-staged',
+        });
+      }
+      assertStagedPaths(actor, context, targets.map((entry) => entry.path));
+      const identity = commitIdentityFor(actor?.actor);
+      const committed = await withCommitLock(`${gitDir}#commit`, async () => {
+        const head = await headOrNull(runtime, context, signal);
+        return commitStagedEntries({
+          runGit: (args, env) => runtime.runGitImpl({ args, cwd: context.root, env, signal }),
+          gitDir,
+          head,
+          entries: targets,
+          message: text,
+          identity,
+        });
+      });
+      await forgetStagedEntries(gitDir, actor?.actor, committed.files);
+      return {
+        commit: committed.commit,
+        branch: await branchOf(runtime, context, signal),
+        author: identity.name,
+        email: identity.email,
+        files: committed.files,
+      };
+    },
+
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, project?: unknown, branch?: unknown, force?: boolean }} options - invocation.
+     * @returns {Promise<object>} push result.
+     */
+    async push(actor, { workspaceRoot, signal, project, branch, force = false }) {
+      assertGitWrite(actor);
+      const parsed = parseProject(project);
+      assertProjectAllowed(actor, parsed);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const current = await branchOf(runtime, context, signal);
+      if (branch === undefined || branch === null || branch === '') {
+        if (current === null) {
+          throw new GitFoxError('HEAD is detached; specify the remote branch explicitly', {
+            code: 'detached-head',
+          });
+        }
+      }
+      const targetBranch = validateBranchName(branch ?? current);
+      if (force === true && PROTECTED_BRANCHES.has(targetBranch)) {
+        throw new GitFoxError(`force-push to protected branch "${targetBranch}" is denied`, {
+          code: 'protected-branch',
+        });
+      }
+      const commit = await headSha(runtime, context, signal);
+      const config = await runtime.resolveConfig();
+      if (config.token === '') throw notConnectedError();
+      const remote = projectRemoteUrl(config.baseUrl, parsed);
+      const origin = new URL(remote).origin;
+      const credentialArgs = credentialConfigArgs(origin);
+      const env = {
+        GIT_TERMINAL_PROMPT: '0',
+        GCM_INTERACTIVE: 'never',
+        INFINITY_GIT_USERNAME: actor?.botName ?? 'infinsys-agent',
+        INFINITY_GIT_TOKEN: config.token,
+      };
+      const lease = force === true ? await forceLease(runtime, { credentialArgs, env, context, remote, branch: targetBranch, signal }) : [];
+      const args = [
+        ...credentialArgs,
+        'push',
+        '--porcelain',
+        '--no-verify',
+        ...lease,
+        remote,
+        `HEAD:refs/heads/${targetBranch}`,
+      ];
+      let pushed;
+      try {
+        pushed = await runtime.runGitImpl({
+          args,
+          cwd: context.root,
+          env,
+          timeoutMs: PUSH_TIMEOUT_MS,
+          signal,
+        });
+      } catch (error) {
+        throw pushFailure(error);
+      }
+      const { stdout, stderr } = pushed;
+      return {
+        project: `${parsed.namespace}/${parsed.name}`,
+        branch: targetBranch,
+        commit,
+        remote,
+        forced: force === true,
+        output: pushSummary(stdout, stderr),
+      };
+    },
+  };
+}
+
+/**
+ * Whether a rebase is stopped mid-flight (conflicts or a pending edit).
+ *
+ * @param {{ runGitImpl: object }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - caller cancellation.
+ * @returns {Promise<string | null>} state directory, or null when no rebase runs.
+ */
+async function rebaseStopped(runtime, context, signal) {
+  for (const name of ['rebase-merge', 'rebase-apply']) {
+    try {
+      const { stdout } = await runtime.runGitImpl({
+        args: ['rev-parse', '--git-path', name],
+        cwd: context.root,
+        signal,
+      });
+      const directory = resolve(context.root, stdout.trim());
+      await access(directory);
+      return directory;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Unmerged paths left by a stopped rebase.
+ *
+ * @param {{ runGitImpl: object }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {AbortSignal | undefined} signal - caller cancellation.
+ * @returns {Promise<string[]>} conflicted repo-relative paths.
+ */
+async function conflictedPaths(runtime, context, signal) {
+  const { stdout } = await runtime.runGitImpl({
+    args: ['diff', '--name-only', '--diff-filter=U', '-z'],
+    cwd: context.root,
+    signal,
+  });
+  return stdout.split('\0').filter((path) => path !== '');
+}
+
+/** Editors that keep a rebase from blocking on a commit message. */
+const REBASE_ENV = Object.freeze({ GIT_EDITOR: 'true', GIT_SEQUENCE_EDITOR: 'true' });
+
+/**
+ * Run one rebase step and translate a conflict stop into a structured result.
+ *
+ * @param {{ runGitImpl: object }} runtime - service wiring.
+ * @param {{ root: string }} context - repository context.
+ * @param {{ args: string[], branch: string | null, signal?: AbortSignal }} input - step.
+ * @returns {Promise<object>} completed or conflicted outcome.
+ */
+async function runRebaseStep(runtime, context, input) {
+  try {
+    const { stdout, stderr } = await runtime.runGitImpl({
+      args: input.args,
+      cwd: context.root,
+      env: REBASE_ENV,
+      signal: input.signal,
+    });
+    return {
+      status: 'completed',
+      branch: input.branch,
+      commit: await headSha(runtime, context, input.signal),
+      output: `${stdout.trim()}\n${stderr.trim()}`.trim(),
+    };
+  } catch (error) {
+    const stopped = error instanceof GitFoxError && error.code === 'git-failed'
+      ? await rebaseStopped(runtime, context, input.signal)
+      : null;
+    if (stopped === null || stopped === undefined) throw error;
+    return {
+      status: 'conflicted',
+      branch: input.branch,
+      files: await conflictedPaths(runtime, context, input.signal),
+      note: 'resolve the listed files, stage them with action "stage", then call action "rebase_continue" (or "rebase_abort")',
+    };
+  }
+}
+
+/**
+ * Build the rebase operations: fetch the target, then rebase the checked-out
+ * branch locally, resolving (or aborting) conflict stops.
+ *
+ * @param {{ runGitImpl: typeof runGit, resolveConfig: () => Promise<object> }} runtime - service wiring.
+ * @returns {object} fetch/rebase methods.
+ */
+function createRebaseOperations(runtime) {
+  return {
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, project?: unknown, branch?: unknown }} options - invocation.
+     * @returns {Promise<object>} fetched ref.
+     */
+    async fetch(actor, { workspaceRoot, signal, project, branch }) {
+      const parsed = parseProject(project);
+      assertProjectAllowed(actor, parsed);
+      if (typeof branch !== 'string' || branch.trim() === '') {
+        throw new GitFoxError('action "fetch" requires "branch"', { code: 'invalid-arguments' });
+      }
+      const target = validateBranchName(branch.trim());
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const config = await runtime.resolveConfig();
+      if (config.token === '') throw notConnectedError();
+      const remote = projectRemoteUrl(config.baseUrl, parsed);
+      const origin = new URL(remote).origin;
+      const env = {
+        GIT_TERMINAL_PROMPT: '0',
+        GCM_INTERACTIVE: 'never',
+        INFINITY_GIT_USERNAME: actor?.botName ?? 'infinsys-agent',
+        INFINITY_GIT_TOKEN: config.token,
+      };
+      await runtime.runGitImpl({
+        args: [
+          ...credentialConfigArgs(origin),
+          'fetch',
+          '--no-tags',
+          remote,
+          `+refs/heads/${target}:refs/remotes/origin/${target}`,
+        ],
+        cwd: context.root,
+        env,
+        timeoutMs: PUSH_TIMEOUT_MS,
+        signal,
+      });
+      return { project: `${parsed.namespace}/${parsed.name}`, branch: target, ref: `origin/${target}` };
+    },
+
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal, onto?: unknown, branch?: unknown }} options - invocation.
+     * @returns {Promise<object>} completed or conflicted outcome.
+     */
+    async rebase(actor, { workspaceRoot, signal, onto, branch }) {
+      assertGitWrite(actor);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const current = await branchOf(runtime, context, signal);
+      if (current === null) {
+        throw new GitFoxError('HEAD is detached; check out the branch before rebasing', {
+          code: 'detached-head',
+        });
+      }
+      const requested = typeof branch === 'string' ? branch.trim() : '';
+      if (requested !== '' && requested !== current) {
+        throw new GitFoxError(
+          `rebase applies to the checked-out branch "${current}", not "${requested}"`,
+          { code: 'invalid-arguments' },
+        );
+      }
+      const target = typeof onto === 'string' ? onto.trim() : '';
+      const args = target === '' ? ['rebase'] : ['rebase', target];
+      return runRebaseStep(runtime, context, { args, branch: current, signal });
+    },
+
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal }} options - invocation.
+     * @returns {Promise<object>} completed or conflicted outcome.
+     */
+    async rebase_continue(actor, { workspaceRoot, signal }) {
+      assertGitWrite(actor);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const branch = await branchOf(runtime, context, signal);
+      const stopped = await rebaseStopped(runtime, context, signal);
+      if (stopped === null) {
+        throw new GitFoxError('no rebase is in progress', { code: 'no-rebase-in-progress' });
+      }
+      return runRebaseStep(runtime, context, { args: ['rebase', '--continue'], branch, signal });
+    },
+
+    /**
+     * @param {object} actor - resolved actor.
+     * @param {{ workspaceRoot: string, signal?: AbortSignal }} options - invocation.
+     * @returns {Promise<object>} abort outcome.
+     */
+    async rebase_abort(actor, { workspaceRoot, signal }) {
+      assertGitWrite(actor);
+      const context = await contextOf(runtime, workspaceRoot, signal);
+      const branch = await branchOf(runtime, context, signal);
+      const stopped = await rebaseStopped(runtime, context, signal);
+      if (stopped === null) {
+        throw new GitFoxError('no rebase is in progress', { code: 'no-rebase-in-progress' });
+      }
+      await runtime.runGitImpl({ args: ['rebase', '--abort'], cwd: context.root, env: REBASE_ENV, signal });
+      return { status: 'aborted', branch, commit: await headSha(runtime, context, signal) };
+    },
+  };
+}
+
+/**
+ * Create the local Git service.
+ *
+ * @param {{ resolveConfig: () => Promise<{ baseUrl: string, token: string }>, runGitImpl?: typeof runGit }} options - wiring.
+ * @returns {object} service with one method per `infinity_git` action.
+ */
+export function createGitRepository({ resolveConfig, runGitImpl = runGit }) {
+  const runtime = { resolveConfig, runGitImpl };
+  return {
+    ...createReadOperations(runtime),
+    ...createIndexOperations(runtime),
+    ...createCheckoutOperations(runtime),
+    ...createRebaseOperations(runtime),
+    ...createPublishOperations(runtime),
+    ...createRefOperations(runtime),
+  };
+}
+
+/** Re-exported for tests that exercise the default timeout. */
+export { DEFAULT_GIT_TIMEOUT_MS };