/** * The arbitration shim's fail-closed code. `shims/git.cmd` runs * `cmd -> node (shim-runner) -> git`, and an exclusive-class command that * cannot take the workspace lock exits 124 rather than running unlocked. * * That is a DIFFERENT fault from git failing: nothing is wrong with git, the * folder is busy. It needs its own message, because the two look identical in * a log without it - and "workspace lock timeout" is fixable by waiting or * clearing a stale lock, whereas "git failed" sends you to the wrong place. */ export declare const GIT_SHIM_LOCK_TIMEOUT_EXIT = 124; export interface GitOutcome { ok: boolean; /** stdout, else stderr, else a description of how the process died. */ out: string; exitCode: number; /** True when the arbitration shim refused to run git (exit 124). */ shimLockTimeout: boolean; } export type GitLogFn = (text: string, level?: 'stdout' | 'stderr') => void; export interface StashResult { gitRoot: string; repoName: string; wasDirty: boolean; stashed: boolean; /** Tagged stash message: `teamshare:[:leftover]`. */ stashRef?: string; /** Stash index for pop: `stash@{0}`. */ stashIndex?: string; /** True when the stashed dirt came from an interrupted previous run. */ leftover?: boolean; popped: boolean; popConflicts: boolean; popConflictedFiles?: string[]; error?: string; } /** * A `teamshare:*` stash entry found on disk. Report-only: the caller decides * whether to surface it, adopt it (`restoreStash`) or leave it alone. */ export interface OrphanStash { gitRoot: string; repoName: string; /** e.g. `stash@{0}`. */ stashIndex: string; /** Task id embedded in the `teamshare:[:leftover]` tag. */ taskId: string; /** True when the tag matches the task currently starting (its OWN stash). */ isSelf: boolean; /** True when the entry carries the `:leftover` provenance suffix. */ leftover: boolean; /** Stash creation date (`git log -1 --format=%ci`), or `unknown`. */ date: string; /** Paths captured by the stash (tracked + untracked when git supports it). */ files: string[]; } /** Minimal API interface — only what git-runner needs. */ export interface GitRunnerApi { addComment(dto: { taskId: string; body: string; }): Promise; } /** * Every `teamshare:*` stash entry under `gitRoot`, newest first. Includes the * current task's OWN interrupted stash (`isSelf`) instead of skipping it. * Never mutates the stash list. */ export declare function listStashes(gitRoot: string, cwd: string, currentTaskId: string): OrphanStash[]; /** * Pop a specific stash entry by ref (`git stash pop --index`). Returns true on * success, false on conflict or error. Used by the daemon's session.stop * handler to restore stashes when the CLI's finally block does not run. */ export declare function popStashByRef(gitRoot: string, ref: string, log: GitLogFn): boolean; /** * Apply a stashed entry onto the working tree WITHOUT dropping it * (`git stash apply`, not `pop`). Called only by an explicit adoption * (`--adopt-stash`) or a human/agent decision - never automatically. */ export declare function restoreStash(gitRoot: string, ref: string, cwd: string, log: GitLogFn): boolean; /** * Stash one repo's uncommitted changes before the run branches, tagged * `teamshare:[:leftover]`. * * ISOLATED TREES NEVER STASH. `refs/stash` is shared between a linked worktree * and its main repo, so stashing from inside a mirror pushed the entry onto the * USER's stash stack and could sweep an adopted retry's uncommitted files (the * only copy of the previous attempt's work) out of the tree. The call sites gate * on `isIsolatedTree`; this re-check is the backstop. * * The `teamshare/` scratch exclude still runs first, unconditionally: it is * about keeping research/tool output out of git status, not about protecting * human work, and research runs are never isolated. */ export declare function stashRepo(gitRoot: string, taskId: string, cwd: string, api: GitRunnerApi | null, log: GitLogFn, opts?: { leftover?: boolean; }): Promise; export declare function popRepo(gitRoot: string, result: StashResult, cwd: string, taskId: string, api: GitRunnerApi | null, log: GitLogFn): Promise; /** * Scan all git roots for `teamshare:*` stash entries. Returns them structured * (so the caller can surface the file list to the agent) and posts one * recovery comment per entry. Includes the CURRENT task's own interrupted * stash (`isSelf`) - a naive "belongs to this run" skip used to hide it. * * Report-only: this never applies or drops a stash. * * Isolated trees are exempt and return `[]`: `refs/stash` is shared with the * main repo, so a mirror worktree would otherwise read the USER's stash entries * back and file `[git-stash-orphaned]` comments on the task for them. The call * sites gate on `isIsolatedTree` too; this re-check keeps a future call site * from reintroducing it. */ export declare function checkOrphanedStashes(cwd: string, currentTaskId: string, api: GitRunnerApi | null, log: GitLogFn): Promise; /** * Format stash results into a markdown section for the closing comment. * `orphans` (report-only detections) are listed separately so a human can see * that other changes remain stashed and were NOT touched by this run. */ export declare function formatStashSummary(stashResults: StashResult[], orphans?: OrphanStash[]): string;