export interface WorktreeInfo { path: string; branch: string; commitHash: string; } /** * True when a directory holds no entry at all (readdir returns only `.`/`..`, * which Node omits). A path we cannot read is treated as NOT empty on purpose: * "cannot inspect" must never be the reason bytes are deleted. Exported for * the regression test that pins that rule. */ export declare function isDirEmpty(dir: string): boolean; /** * Arbitrated create (IMP-950): exclusive lock on the main repo while the * worktree is registered. Returns null when the workspace stays busy past * the wait budget - the caller reports failure instead of corrupting state. */ export declare function createWorktreeAsync(repoPath: string, branch: string, baseBranch: string, taskId: string, agentId?: string, opts?: { worktreePath?: string; detach?: boolean; }): Promise; /** Arbitrated remove (IMP-950). */ export declare function removeWorktreeAsync(repoPath: string, worktreePath: string, agentId?: string): Promise; export interface SafeRemoveResult { removed: boolean; /** Uncommitted changes existed and were committed+pushed before removal. */ rescued?: boolean; /** Branch the rescue commit landed on (also where preserved work lives * when removal was refused). */ branch?: string; commitHash?: string; /** Refused because the tree was dirty and could not be rescued. */ dirty?: boolean; path?: string; error?: string; /** * Whether the rescue commit reached the remote. * * Distinct from `rescued`, and the reason it exists: a push failure does NOT * refuse removal once the work is on a real branch and the checkout was * detached (`detachedRescue`), so `rescued: true` can still mean "local only". * A caller that reports progress to a human (the stop handler) must not claim * the work was pushed when it was not. Undefined when nothing was rescued. */ pushed?: boolean; } /** * DATA-LOSS GUARD (2026-08-25 Ptad incident): a zombie requeue tore down a * live worker's worktree; the old removeWorktree() ran `git checkout -- .` + * `git clean -fd` first and vaporized hours of uncommitted agent work. * * Safe removal order: * 1. dirty? -> rescue: `git add -A` + WIP commit on the worktree branch, * pushed to origin. Removal only proceeds once the work exists on the * remote. * 2. rescue fails (no remote / push error) -> REFUSE. The directory is * left untouched for human recovery; caller alerts instead of deleting. * 3. clean (or rescued) -> remove, then sweep an empty husk dir Windows * sometimes leaves behind. * Never discards anything - there is no `checkout -- .`/`clean -fd` here. */ export declare function removeWorktreeSafeAsync(repoPath: string, worktreePath: string, opts?: { agentId?: string; reason?: string; rescueBranch?: string; }): Promise; export interface GitStatus { branch: string; dirty: boolean; ahead: number; files: string[]; } /** * Why a path may NOT be used as a REPOSITORY (a linked folder the human chose), * or `null` when it is fine (2026-11-13). * * Always rejected: network (UNC) paths and a real `..` segment. * * **Deliberately NOT rejected: a folder outside the user profile.** The old * check here refused any path that did not start with `%USERPROFILE%`, which * silently killed EVERY code run on a project kept on another local drive: * `D:\Stuff\Work\CourseBuilder\course-builder` produced * `Invalid repository path: …` from `createWorktree`, `failIsolation()` blocked * the wake in ~4 s, and a human pressing "Run task" saw a task that never * attempted to start (each press resets the failure count, so it never even * suspended and explained itself). Seven linked projects on this machine were * dead that way. * * The link-time preflight (`preflightFolder` in `lib/config.ts`) is the * authority for "is this a usable project folder": it checks existence, * read+write access, UNC, OneDrive and mapped network drives, and it accepted * that D: folder. Re-checking a stricter rule later can only contradict it. */ export declare function repoPathRejection(p: string): string | null; /** * Get the worktree root directory for a project. * * Workspace state (2026-10): mirrors live OUTSIDE every tracked folder, under * the per-machine workspace root (`~/.teamshare/workspace//worktrees`), * never as a sibling `/../.teamshare-worktrees`. The sibling path * survives only as `legacyWorktreeRootFor()` for sweeps. */ export declare function getWorktreeRoot(projectPath: string): string; /** Legacy sibling root. Read-only: sweeps still reap orphan trees there. */ export declare function getLegacyWorktreeRoot(projectPath: string): string; /** * Create a new Git worktree for an orchestrator task. */ export declare function createWorktree(repoPath: string, branch: string, baseBranch: string, taskId: string, opts?: { worktreePath?: string; detach?: boolean; }): WorktreeInfo; /** * Remove a Git worktree. * DATA-LOSS GUARD: uncommitted changes are rescued via a WIP commit on the * worktree branch before removal - this function NEVER discards work. * (`git checkout -- .` + `git clean -fd` here previously vaporized a live * worker's uncommitted files during zombie cleanup - 2026-08-25 Ptad.) */ export declare function removeWorktree(repoPath: string, worktreePath: string): void; /** * Get git status for a worktree. */ export declare function gitStatus(worktreePath: string): GitStatus; /** * Commit changes in a worktree. */ export declare function gitCommit(worktreePath: string, message: string, files?: string[]): string; /** * Merge a branch into the integration branch - arbitrated (IMP-950). * gitMerge CHECKS OUT the target branch inside the MAIN repo tree; without * the lock a concurrent session could have its working files swapped * mid-edit. Returns { skipped: true } when the workspace stayed busy. */ export declare function gitMergeAsync(repoPath: string, sourceBranch: string, targetBranch: string, agentId?: string): Promise<{ success: boolean; conflictFiles?: string[]; skipped?: boolean; }>; /** The branch `repoPath` currently has checked out, or null (detached/unborn). */ export declare function checkedOutBranch(repoPath: string): string | null; /** * Is `ref` safe to hand to git as a single argv element? * * Even without a shell there is one remaining hazard: an argument beginning * with `-` is parsed by git as an OPTION (`--upload-pack`, `--exec`), and * whitespace would split an argument that some caller reconstructs into a * command line. The character set also mirrors git's own ref rules, so a * value that fails here would have been rejected by git anyway. */ export declare function validateRef(ref: string): boolean; /** * Merge a branch into the integration branch. */ export declare function gitMerge(repoPath: string, sourceBranch: string, targetBranch: string): { success: boolean; conflictFiles?: string[]; }; /** * Get the diff for a worktree. */ export declare function gitDiff(worktreePath: string): string; /** * Push a branch to a remote. * Uses the given remote name (defaults to 'origin'). Returns success or the error. */ export declare function gitPush(repoPath: string, branch: string, remote?: string, setUpstream?: boolean): { success: boolean; remoteRef?: string; error?: string; }; /** * Revert the last commit in a worktree (git revert HEAD --no-edit). * Returns the new commit hash after the revert. */ export declare function gitRevertHead(worktreePath: string): { commitHash: string; }; /** * Hard reset a worktree to a specific commit (git reset --hard ). * Discards ALL uncommitted changes and moves HEAD to the target commit. */ export declare function gitResetHead(worktreePath: string, commitHash: string): { success: boolean; }; /** * Get the remote URL for a git repo. Returns null if not a git repo or no remote. */ export declare function gitRemoteUrl(repoPath: string, remote?: string): string | null; /** * Check whether a directory is a git repository. */ export declare function isGitRepo(dir: string): boolean; /** * Initialize a git repository in a directory (git init + optional remote). * Returns the origin URL if a remote was added, else null. */ export declare function gitInit(dir: string, remoteName?: string, originUrl?: string): { success: boolean; originUrl?: string; error?: string; }; /** * Ensure a directory is a git repository. If not, initialise it. * This allows the orchestrator to work on projects that have no git repo yet. */ export declare function ensureRepoExists(repoPath: string): void; /** True when `ref` resolves to a real commit object (not an unborn branch). */ export declare function refResolvesToCommit(repoPath: string, ref: string): boolean; /** * Detect the ACTUAL default branch of a repo (never a hardcoded `main`). * Resolution order, every candidate verified to resolve to a commit: * origin/HEAD -> origin/main -> origin/master -> main -> master * -> git config init.defaultBranch -> current branch (unless detached). * Returns null when nothing resolves (empty/unborn repo) so callers can * queue instead of running a doomed `git worktree add`. */ export declare function detectDefaultBranch(repoPath: string): string | null; /** * Ensure a local bare repo exists and is configured as the origin remote for * `repoPath`. When no remote is configured (the user hasn't linked a GitHub / * Gitea repo), this allows `git push` to succeed against a local bare repo * at `~/.teamshare/bare-repos/.git/`. */ export declare function ensureLocalBareRepo(repoPath: string, projectId: string): string;