/** * Branch name for a task run: readable slug /. Falls * back to `tasks/` when project/title are unknown (legacy callers). */ export declare function branchForTask(taskId: string, ctx?: { projectSlug?: string; taskTitle?: string; }): string; /** * Branch this run should use: an explicit `branchName` (hub-assigned) when * present, else the branch this task already DELIVERED on (`deliveryBranch`, * set by the bridge after a guarded rename), else the readable * `branchForTask()` derivation. * * The middle step is load-bearing for retries: without it a task whose delivery * branch an agent named would be re-run on the derived name, which does not * contain any of the previous attempt's commits - so the agent would implement * the same work a second time. */ export declare function desiredBranch(opts: { taskId: string; branchName?: string; deliveryBranch?: string | null; projectSlug?: string; taskTitle?: string; }): string; /** * The branch checked out in `gitRoot`, or **null when HEAD is DETACHED**. * * `git rev-parse --abbrev-ref HEAD` answers the LITERAL string `HEAD` when HEAD * is detached — a value that looks like a branch name and is not one. Treating * it as one is what produced (2026-11-18): * * Git: committed 2 file(s) on `HEAD` (5dfe7fc) * Push failed: `error: The destination you provided is not a full refname * (i.e. starting with "refs/"). ...` * * `git push -u origin HEAD` has to guess a destination, and `HEAD` is not a ref * the remote can name. The commit is real but belongs to NO branch: it cannot * be pushed, and once the (temporary) mirror is torn down nothing points at it * any more. Every caller that names a branch must go through this, not through * `abbrev-ref` directly. */ export declare function currentBranchName(gitRoot: string): string | null; export type DetachedHeadNaming = { ok: true; branch: string; /** * created - the branch did not exist; it now points at this commit. * advanced - it existed and was an ANCESTOR of this commit (fast-forward). * sibling - it existed with DIFFERENT history; the work was published on * `-run-` instead of rewriting it. */ mode: 'created' | 'advanced' | 'sibling'; } | { ok: false; detail: string; }; /** * Give a commit made on a DETACHED HEAD a branch to live on (2026-11-18). * * Mirrors are created detached (`createWorktree(..., { detach: true })`), so * "make the delivery branch" normally happens in `prepare`. When that is not * possible — the common case being a mirror based on a NEWER base than the * task's own branch already pushed, where `git checkout ` refuses with * "local changes would be overwritten" — the run used to commit on the detached * HEAD and then try to push `HEAD`. Now the commit is named instead: * * 1. the branch does not exist -> create it AT THIS COMMIT (safe: there * is no other history to lose); * 2. it exists and is an ancestor -> move it forward (a fast-forward); * 3. it exists with diverging history -> NEVER reset it. Publish this run's * commit on `-run-` and let the report say so: the existing * branch may carry a previous attempt someone is reviewing, and silently * repointing it is how work disappears. * * Never throws; `ok: false` means git refused (index locked) and the caller must * report an unnamed commit rather than pretend it was delivered. */ export declare function nameDetachedHead(gitRoot: string, desired: string, sha: string): DetachedHeadNaming; /** * Put an existing (detached) tree ON its branch, at the commit it is already on. * * This is what makes the whole pipeline predictable (2026-11-18): the mirror is * created detached at the TASK'S OWN branch tip, and this attaches it. Because * HEAD is already the branch's commit, `checkout ` moves no content and * `checkout -B ` cannot move history — unlike `prepare`'s old * `git checkout ` over a tree cut from a DIFFERENT base, which git * refuses ("local changes would be overwritten") and which is how runs ended up * committing on a detached HEAD called `HEAD`. * * Returns `created: true` when the local branch did not exist and was made here * (the commit only existed on `origin/`). */ export declare function attachBranchAtHead(gitRoot: string, branch: string): { ok: boolean; out: string; created: boolean; branch: string; }; export interface BranchSyncResult { /** True when the tree is usable (merged cleanly, already current, or skipped). */ ok: boolean; /** Commits the base carried that the branch did not have. */ incoming: number; /** Unmerged paths left in the tree for the agent to resolve. */ conflicts: string[]; /** Why a non-conflict failure happened (reported, never fatal). */ detail?: string; } /** * Bring the branch up to date with the branch it STARTED from (2026-11-18). * * The human's rule: "always from your own task branch, but pull to get updated * state — nudge the agent to resolve any merge conflict that may have come in." * * So this merges the recorded base INTO the task branch. A clean merge is a * fast-forward (no task commits yet) or a merge commit; a CONFLICT is * deliberately left in the tree, because resolving it needs judgement the * bridge must not fake. The brief then tells the agent to resolve it first. */ export declare function syncBranchFrom(gitRoot: string, ref: string): BranchSyncResult; /** * The base-branch ladder for a fresh task branch (2026-12). THE single source * of truth for "where does new work start" - the mirror, `prepareRunGit` and * `finalizeRunGit` must all ask this, or a run branches from one ref and its * pull request targets another. * * Order, first hit wins: * 1. `continueFrom` - the task's OWN branch from a previous attempt, so a * retry continues instead of re-implementing. * 2. `configuredBase` - the project-wide base branch a human set in the UI. * 3. `currentBranch` - the branch checked out in the linked folder, i.e. * what the human means by "the folder is on staging". * 4. `defaultBranch` - the repo default, only when nothing else exists. * * Pure on purpose: the ORDER is the bug-prone part and must be testable * without a working tree (`tests/git-base-branch.test.mjs`). */ export declare function chooseBaseRef(c: { continueFrom?: string | null; configuredBase?: string | null; currentBranch?: string | null; defaultBranch?: string | null; }): string; /** * The branch NAME a forge expects for a PR base, from any resolved ref: * `origin/staging` -> `staging`, `refs/remotes/origin/staging` -> `staging`, * `refs/heads/main` -> `main`. Anything else is passed through. * * Load-bearing (2026-12): `detectDefaultBranch` resolves `origin/main`, and * handing that to GitHub as `base` fails the PR while the branch it was cut * from was fine. */ export declare function baseBranchName(ref: string | null | undefined): string; /** * Base ref a fresh task branch should start from, in priority order: * explicit chain base > independent default base > '' (current HEAD). * `fetch` is only honored on the independent path. */ export declare function startPointFor(gitRoot: string, opts: { baseBranch?: string | null; /** Project-wide base branch (TeamShare project setting). */ configuredBase?: string | null; independentBase?: boolean; projectId?: string | null; /** True when this tree IS an isolation mirror (already based correctly). */ mirror?: boolean; }, fetch: boolean): string;