import type { GitLogFn, GitPolicy } from './git-core'; import { type GitNamingProposal } from './git-naming'; import type { PreparedGit } from './git-prepare'; export interface FinalizeRunGitOptions { taskId: string; taskTitle: string; agentName: string; projectId?: string | null; /** Readable branch naming: /. Used by multi-repo finalize to create branches lazily. */ projectSlug?: string; /** Explicit hub-assigned branch name (IMP-743); wins over branchForTask(). */ branchName?: string; /** * The branch this task already DELIVERED on (2026-12), recorded by the hub * after a guarded rename. Sits below `branchName` and above the title * derivation in `desiredBranch`, so a retry continues the delivered work * instead of cutting a second branch from the base. */ deliveryBranch?: string | null; /** chainMode base branch: start a FRESH branch here (existing branch wins). */ baseBranch?: string | null; /** * Project-wide base branch from TeamShare settings (2026-12). Used as the PR * base when the tree's own base cannot be recovered (a non-mirror run). */ configuredBase?: string | null; /** Independent task (ungrouped / first-of-chain): start the fresh branch from the repo's default branch (see PrepareRunGitOptions). */ independentBase?: boolean; /** Open a pull request after a successful push (needs a token). */ openPr: boolean; /** * The harness failed. Its work is still COMMITTED and PUSHED (nothing is * lost), but no pull request is opened: a PR asks a human to review finished * work, and a failed run has not produced that. The pushed branch is named in * the report so a human can open one deliberately (2026-11). */ runFailed?: boolean; /** Run identity for App-token minting: agent key sent as X-Api-Key. */ apiKey?: string | null; /** Hub base URL for App-token minting (defaults to the public API). */ apiBaseUrl?: string | null; /** * Reads the agent's delivery-naming proposal (2026-12) AT FINALIZE TIME. * * It must be a callback and not a value: an agent proposes DURING the run, so * a snapshot taken at spawn is always empty. Best-effort - a throw or an * offline hub leaves `undefined` and the pipeline uses the task title, exactly * as it did before the feature. */ loadProposal?: () => Promise; /** * Best-effort report of what the naming pipeline did, so the hub can mark the * proposal applied/refused and record the delivered branch (a retry reads it). * Never awaited for correctness: a failed call must not fail the run. */ reportDelivery?: (report: GitDeliveryReport) => Promise; /** IMP-914 per-project git automation level (undefined = legacy flags). */ policy?: GitPolicy; /** * When true, allow commits directly on the default/main branch. * Default false — agents should never commit to main. */ allowMainBranchCommit?: boolean; /** * true (default) = create the task branch in finalize for repos with * changes (run/build/orchestrator shared folder); false = legacy, work on * whatever branch is checked out (callers that own branch layout, e.g. a * backend-managed worktree). Controls lazy branch creation. */ createBranch?: boolean; log: GitLogFn; } export interface FinalizedGit { /** One-liner for run reports ("" when nothing happened). */ gitLine: string; /** Human-readable report lines appended to the closing comment. */ lines: string[]; branch?: string; sha?: string; pushed?: boolean; prUrl?: string; prNumber?: number; changedFiles?: number; /** Changed file paths (repo-relative, capped) for the run report. */ changedPaths?: string[]; /** * What the pipeline did with the agent's naming proposal (2026-12). * `applied` = at least one part was used; `refused` = it was read and the * historical naming kept; `none` = there was no live proposal. */ naming?: GitNamingOutcome; } /** The delivery-naming result of one finalize pass (see `out.naming`). */ export interface GitNamingOutcome { naming: 'applied' | 'refused' | 'none'; /** Why a proposal was not used (present when `refused`). */ reason?: string; /** The branch the work was delivered on (only set when it was renamed). */ branch?: string; } /** What the bridge reports back to `POST /tasks/:id/git-delivery`. */ export interface GitDeliveryReport { naming: 'applied' | 'refused' | 'none'; reason?: string; branch?: string; sha?: string; prUrl?: string; prNumber?: number; repos?: Array<{ repo: string; branch: string; sha?: string; prUrl?: string; }>; } /** * Post-run phase under an exclusive repo lock (IMP-950): commit/push while * no other session can switch branches or rebuild the tree underneath. * A busy workspace degrades the report - it never throws and never loses * the run's success. */ export declare function finalizeRunGit(cwd: string, prepared: PreparedGit, opts: FinalizeRunGitOptions & { lockWaitMs?: number; }): Promise; /** * Safety-net commit: if the working tree has uncommitted changes after a * harness failure (or any early exit), commit them to the task branch and * push so the next run continues from a clean tree instead of stashing and * losing the agent's progress. * * Never throws. Returns a FinalizedGit with report lines. */ export declare function commitRemainingChanges(cwd: string, prepared: PreparedGit, opts: FinalizeRunGitOptions): Promise;