@quantiya/codevibe-core 2.0.1 → 2.0.3

package/dist/local-executor/worktree-merge.d.ts

@@ -0,0 +1,601 @@
+import type { ConflictFileMeta } from './conflict-types';
+import { PromoteWalStore, type PromoteMode, type PromoteWalRecord } from './promote-wal-store';
+/**
+ * The pinned merge-implementation id (§4.2) folded into the promote key. W1 pins
+ * the host git version + the determinism contract id; a change yields a new key
+ * → no stale cross-version replay.
+ *
+ * W1's promote has NO hunk segmentation, so a STATIC pin is sound here (the
+ * `TODO(W2)`'s own observation): the promote key only needs a stable per-build
+ * identity. W2's merge-train IS hunk-segmentation-sensitive, so it derives a
+ * VERSION-AWARE id via {@link resolveMergeImplId} (the W2 finalization of the
+ * TODO) — a host-git upgrade whose diff3/ort hunk boundaries differ yields a new
+ * key → a cache-miss → re-resolve, never a stale cross-version replay. W1's promote
+ * path keeps using this static const (byte-identical); only W2's train uses the
+ * derived id.
+ */
+export declare const MERGE_IMPL_ID = "git-host-v1";
+/**
+ * Resolve the W2 merge-implementation id (§4.2, the finalization of the W1
+ * `MERGE_IMPL_ID` TODO). Derives from the REAL host `git --version` folded with the
+ * {@link DETERMINISM_CONTRACT_ID} → `git-<version>+<DETERMINISM_CONTRACT_ID>`. A host-git
+ * upgrade whose hunk segmentation differs across versions yields a DIFFERENT id, so
+ * the merge journal's `expected_merge_key` (which folds in `merge_impl_id`) and any
+ * version-sensitive replay change → re-merge, never a stale cross-version replay.
+ *
+ * Cached per process (the host git binary does not change mid-run). On a failure to
+ * read `git --version` it falls back to the static {@link MERGE_IMPL_ID} (fail-safe:
+ * a stable id, never a throw). NOT a vendored merge impl — the design's "preferred"
+ * vendored option is a later choice; W2 pins the host git version, which is the
+ * minimal-correct, deterministic finalization.
+ */
+export declare function resolveMergeImplId(): Promise<string>;
+/** Branch namespaces (§3.1). */
+export declare function trackBranchName(taskGroupId: string, trackIndex: number): string;
+export declare function integrationBranchName(taskGroupId: string, repoId: string): string;
+export declare function stashBranchName(taskGroupId: string, repoId: string): string;
+/** The ref pinning the durable UNTRACKED-files tree (HIGH-1) so GC can't reap it. */
+export declare function untrackedTreeRefName(taskGroupId: string, repoId: string): string;
+/**
+ * The ref pinning the expected POST-PROMOTE WORKTREE snapshot tree (W1 Stage-2
+ * H1/H2/H3) so GC can't reap it before a revert/recovery drift-check needs it.
+ */
+export declare function worktreeSnapshotRefName(taskGroupId: string, repoId: string): string;
+/**
+ * The ref pinning the PRE-PROMOTE WORKTREE snapshot tree (W1 Stage-2 H6) so GC
+ * can't reap it before crash recovery's divergence guard needs it.
+ */
+export declare function prePromoteSnapshotRefName(taskGroupId: string, repoId: string): string;
+export declare function rescueRefName(taskGroupId: string, repoId: string): string;
+/**
+ * Stage-2 H2 (W1 FINAL) — the durable GC-anchor for the off-branch `dirty_committed`
+ * merge/candidate commit. {@link commitTreeOffBranch} produces an otherwise-unreferenced
+ * commit; until {@link PromoteWalStore.writeCommitted} records its SHA, it is reachable
+ * ONLY via detached `HEAD` (and even after commit the WAL stores the SHA, not a GC root).
+ * If the user checks out a branch (HEAD becomes symbolic) before a recovery/revert pins a
+ * rescue ref, a `git gc --prune=now` would prune the merge commit and strand the WAL's
+ * recovery target (reproduced against real git 2.50.x). So the candidate commit is pinned
+ * here IMMEDIATELY when created (BEFORE the landing CAS) and only deleted at terminal
+ * cleanup ({@link cleanupGroupRepo}); recovery resolves the promoted tip from this ref when
+ * the WAL's `promotedTip` is null (a crash after the CAS, before `writeCommitted`).
+ */
+export declare function promotedTipRefName(taskGroupId: string, repoId: string): string;
+/**
+ * Stage-2 H2 (W1 round-15) — a SECOND rescue ref for the post-CAS `guard-refused`
+ * detached-promote case. When a DETACHED promote's revert/recovery has ALREADY CAS-moved
+ * the literal `HEAD` back to `pre_promote_user_ref` and the user THEN checks out a branch
+ * (HEAD becomes symbolic) before `restorePrePromote`'s reset, the guard refuses. The
+ * PRIMARY {@link rescueRefName} must pin the PRE-CAS recoverable tip (the promoted/crash
+ * commit — otherwise it survives only in reflog/WAL text). If the live (now-symbolic) tip
+ * the user switched to is DIFFERENT and not already reachable from the primary rescue, it
+ * is ALSO pinned here so neither the promoted work NOR the live tip is orphaned.
+ */
+export declare function rescueLiveRefName(taskGroupId: string, repoId: string): string;
+export declare function treeOf(repoDir: string, commitish: string, opts?: {
+    hermetic?: boolean;
+}): Promise<string>;
+/**
+ * W2 seam — run a git command under the SAME pinned, deterministic
+ * {@link PINNED_GIT_CONFIG} every CP-14 op uses (§4.2). Exported so the merge-train
+ * engine (merge-train.ts) shares the EXACT pinned invocation (no divergent config)
+ * without re-exporting the bare module-private {@link git}. `allowFail` mirrors the
+ * internal helper: a non-zero exit returns its stdout/stderr/code instead of throwing.
+ *
+ * W2 Stage-2 r3 (H1 + M1): the W2 seam ALWAYS runs HERMETIC — `hermetic: true` disables
+ * git hooks (`core.hooksPath=/dev/null`, so the Tier-1 `worktree add` checkout cannot run a
+ * track-committed `post-checkout`/other hook) AND scrubs the inherited ambient `GIT_*`
+ * redirect vars (so an ambient `GIT_DIR`/`GIT_OBJECT_DIRECTORY`/etc. cannot redirect the
+ * train off the intended repo). Every W2 git call routes through here, so EVERY W2
+ * checkout/ref/merge op is hooks-disabled + env-scrubbed. W1 keeps using the bare
+ * module-private {@link git} (no `hermetic`), so it is byte-identical.
+ */
+export declare function pinnedGit(repoDir: string, args: readonly string[], opts?: {
+    allowFail?: boolean;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+/**
+ * CP-14 WB2 — a HERMETIC git invocation that accepts STDIN (the `git()` helper
+ * uses `execFile`, which cannot pipe stdin). Same hardening as {@link pinnedGit}:
+ * the W2 `-c` config pins + the {@link sanitizeGitEnv} allowlist env (no ambient
+ * `GIT_*`, replace-refs disabled), so an agent-controlled disposable `.git` /
+ * source config cannot inject a hook/redirect. Used to feed an OID list to
+ * `pack-objects` for the disposable-repo object import (NO clone / upload-pack).
+ * `stdout` is captured as text (the OID-list/pack-objects path writes pack FILES,
+ * not binary stdout).
+ */
+export declare function pinnedGitWithInput(repoDir: string, args: readonly string[], input: string, opts?: {
+    allowFail?: boolean;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+/** The result of standing up the per-group branch foundation for one repo. */
+export interface BranchFoundation {
+    repoId: string;
+    baseSha: string;
+    integrationBranch: string;
+    integrationTip: string;
+}
+/**
+ * Codex #6 (round-7) — thrown when a `create*Branch` REPLAY finds the branch already
+ * present at a SHA that is NOT the expected `base_sha` AND is NOT reachable-from-base
+ * (so it carries commits a force-reset would orphan). The caller surfaces it instead of
+ * silently force-resetting the accumulated work.
+ */
+export declare class BranchStateMismatchError extends Error {
+    readonly branch: string;
+    readonly expectedBaseSha: string;
+    readonly actualSha: string;
+    constructor(branch: string, expectedBaseSha: string, actualSha: string);
+}
+/**
+ * Stand up the per-repo INTEGRATION branch at `base_sha` (§3.1 item 2). W1 does
+ * NOT merge onto it (that is W2); it creates the branch + records the base
+ * snapshot so W2 has a deterministic root.
+ *
+ * Codex #6 (round-7) — CREATE-ONLY (not force-update). A replay over an integration
+ * branch that has accumulated commits (W2 merge-train work) must NOT force-reset it back
+ * to `base_sha` (orphaning that work). Create when absent; when present, leave it (an
+ * idempotent re-create at base, or a legitimate base-rooted advance) and return its LIVE
+ * tip — or surface a {@link BranchStateMismatchError} on a divergent branch.
+ */
+export declare function createIntegrationBranch(repoDir: string, taskGroupId: string, repoId: string, baseSha: string): Promise<BranchFoundation>;
+/**
+ * Create the persistent per-(track,repo) TRACK branch at `base_sha` (§3.1 item 1).
+ * The implementor's worktree-shadow (workspace-shadow.ts) commits onto it. W1
+ * just stands the branch up; the shadow lifecycle is reused unchanged.
+ *
+ * Codex #6 (round-7) — CREATE-ONLY (not force-update). A replay over a track branch the
+ * implementor's shadow already committed onto must NOT force-reset it back to `base_sha`
+ * (orphaning the implementor's commits). Create when absent; when present, leave it
+ * untouched (an idempotent re-create at base, or a base-rooted advance) — or surface a
+ * {@link BranchStateMismatchError} on a divergent branch.
+ */
+export declare function createTrackBranch(repoDir: string, taskGroupId: string, trackIndex: number, baseSha: string): Promise<string>;
+/** A surfaced, non-throwing promote outcome (atomic-or-nothing). */
+export interface PromoteOutcome {
+    /** `'promoted'` — the user tree advanced; `'aborted'` — nothing changed + surfaced. */
+    status: 'promoted' | 'aborted';
+    promoteMode: PromoteMode;
+    /** The adopted HEAD (when promoted). */
+    promotedTip?: string;
+    /**
+     * When aborted: the human-readable reason + the overlapping/conflicting paths
+     * the caller surfaces. The user tree is byte-identical to its pre-promote state.
+     */
+    abortReason?: string;
+    conflictPaths?: string[];
+}
+/**
+ * Codex #1/#2 — a test-only seam to drive the compare-and-swap race deterministically.
+ * The TOCTOU window the fix closes lives BETWEEN the surrounding code reading the
+ * live ref/state and the destructive mutation. Production passes no hook; a test
+ * passes `beforeMutateHook` to fire EXACTLY inside that window (e.g. to commit a
+ * concurrent user change) so the test asserts the CAS / re-validate actually
+ * refuses-and-rescues against REAL git, not a mock. Never used in production.
+ */
+export interface WorktreeMergeRaceHooks {
+    /** Fires immediately before the first destructive ref/tree mutation (in-window). */
+    beforeMutateHook?: () => void | Promise<void>;
+    /**
+     * agy HIGH — fires inside `promoteDirtyUncommitted` AFTER the ref CAS-advanced to
+     * integration_tip but BEFORE the `read-tree -m -u` rollback path, so a test can both
+     * force a read-tree refusal AND move the ref in the rollback window (proving the
+     * rollback-CAS-failure → rescue, never-blind-restore guarantee). ALSO drives the
+     * round-5 post-CAS BRANCH-SWITCH race (Codex #1): a same-SHA `git checkout` here makes
+     * `read-tree -m -u` target the WRONG branch — the `guardedWorktreeSync` re-check must
+     * refuse. Never used in prod.
+     */
+    beforeReadTreeRollbackHook?: () => void | Promise<void>;
+    /**
+     * Codex #2 (round-5) — fires inside `revertToPrePromote` / `recoverPromote` AFTER the
+     * CAS ref-move to `pre_promote_user_ref` but BEFORE the `restorePrePromote` guarded
+     * `reset --hard`, so a test can switch HEAD to a same-SHA branch IN that window and
+     * prove the restore's symbolic-ref re-check refuses (never rewinds the wrong branch).
+     * Never used in prod (typed seam, no live caller).
+     */
+    beforeRestoreResetHook?: () => void | Promise<void>;
+    /**
+     * Round-6 (Codex #4) — fires inside `promoteClean` / `promoteDirtyCommitted` AFTER the
+     * landing CAS advanced the user branch to the promoted tip but BEFORE the
+     * `syncWorktreeToRef` worktree sync, so a test can switch HEAD to a same-SHA sibling
+     * branch IN that post-CAS window and prove the landing sync's guard refuses AND the
+     * advanced ref is rolled back to `pre_promote_user_ref` (atomic-or-nothing — the
+     * branch ref must NOT stay moved when the promote reports aborted, LOCK
+     * #C14-PROMOTE-ATOMIC). Never used in prod (typed seam, no live caller).
+     */
+    beforeWorktreeSyncHook?: () => void | Promise<void>;
+    /**
+     * Round-7 (Codex #2 + agy MEDIUM) — fires inside a guarded destructive callback
+     * IMMEDIATELY before EACH `recheck()` (i.e. between two destructive commands of the
+     * SAME callback: between `reset --hard` and `clean -fd`; between the untracked
+     * `checkout` and the un-stage `reset`; before the stash-apply fallback). A test
+     * switches HEAD to a same-SHA branch here to prove the per-command re-check refuses
+     * the SECOND command (no wrong-branch `clean`/`reset`/`stash apply`). Never used in
+     * prod (typed seam, no live caller).
+     */
+    betweenDestructiveCommandsHook?: () => void | Promise<void>;
+    /**
+     * Round-7 (Codex #2 + agy MEDIUM) — fires inside `restorePrePromote` AFTER the
+     * guarded `reset --hard` + `clean -fd` completed but BEFORE the now-IN-GUARD
+     * `stash apply` runs, so a test can switch HEAD to a same-SHA branch in that window
+     * and prove the stash-apply guard refuses (no wrong-branch `stash apply`). The
+     * PRE-FIX code ran `stash apply` OUTSIDE any guard. Never used in prod.
+     */
+    beforeStashApplyHook?: () => void | Promise<void>;
+    /**
+     * Stage-2 H1 (W1 round-14, Codex HIGH) (FAIL-ON-OLD) — fires inside `restorePrePromote`
+     * in the window AFTER `git stash apply --index` REFUSED but BEFORE the point where the
+     * PRE-FIX code ran the plain `stash apply` fallback (a SECOND destructive worktree mutation
+     * after the first failed, guarded by ONLY the 3 specific checks — symbolic-ref/ref-at/
+     * ignored — so a tracked/staged user change landing here was invisible and the fallback
+     * could merge/overwrite it). A test stages/edits a stash-surface path here; with the
+     * fail-closed fix (NO plain apply: status=`conflicted`, the durable stash ref surfaced) the
+     * in-window bytes/index SURVIVE untouched. Against the pre-fix code the plain apply runs and
+     * clobbers them (the test FAILS). Never used in prod (typed seam, no live caller).
+     */
+    betweenStashIndexApplyAndFallbackHook?: () => void | Promise<void>;
+    /**
+     * Round-11 (Codex HIGH H3) — fires inside `restorePrePromote` AFTER the untracked
+     * `checkout <tree> -- .` pre-op anchor is captured but BEFORE `restoreUntrackedTree`
+     * runs the checkout, so a test can create a NON-IGNORED file in that window and prove
+     * the (now-anchored) untracked-checkout guard refuses (`pre-op-drift`) instead of
+     * overwriting it. The pre-fix code passed NO anchor to the untracked checkout. Never
+     * used in prod (typed seam, no live caller).
+     */
+    beforeUntrackedCheckoutHook?: () => void | Promise<void>;
+    /**
+     * Stage-2 H1 (W1 round-13, Codex HIGH) (FAIL-ON-OLD) — fires inside `restorePrePromote` in
+     * the PRE-CAPTURE window of the untracked re-materialize: AFTER the guarded stash apply (or,
+     * with no stash, the reset/clean) completes but BEFORE the point where the PRE-FIX code
+     * captured the LIVE untracked-checkout anchor (`capturePreOpAnchor`) — the exact window an
+     * external process writes a file at a path the durable untracked tree carries. With the Stage-2
+     * H1 fix the anchor is RECONSTRUCTED from recorded inputs (no-stash → `prePromoteUserRef` tree;
+     * clean `--index` apply → `stash^{tree}` + `stash^2^{tree}`), so a write here makes
+     * `live ≠ reconstructed` → `pre-op-drift` → the checkout never runs → the file is PRESERVED.
+     * Against the pre-fix live-capture code the write is ADOPTED into the anchor and the checkout
+     * clobbers it (the test FAILS). Distinct from `beforeUntrackedCheckoutHook`, which fires AFTER
+     * the (former) live capture (covering only the post-capture window). Never used in prod.
+     */
+    beforeUntrackedCheckoutAnchorHook?: () => void | Promise<void>;
+    /**
+     * Round-7 (Codex #4) — fires inside each promote mode AFTER the landing CAS + worktree
+     * sync succeeded (the ref is at the promoted tip) but BEFORE `recordPostPromoteState`
+     * / `writeCommitted`. A test THROWS from here to simulate a post-mutation
+     * snapshot/WAL-write failure, proving the generic promote-error path rolls the
+     * CAS-advanced ref BACK to pre-promote + marks the WAL terminal (never leaves the
+     * branch promoted + the WAL `promote_started`). Never used in prod.
+     */
+    afterLandingBeforeCommitHook?: () => void | Promise<void>;
+    /**
+     * Codex r12 H1 (FAIL-ON-OLD) — fires in the PRE-CAPTURE WINDOW of the landing sync /
+     * read-tree / restore reset: AFTER the CAS / pre-reset positioning but BEFORE the point
+     * where the PRE-FIX code captured the LIVE `preOpAnchor` (which would have ADOPTED a write
+     * landing here and then clobbered it). With the Codex r12 H1 fix the op-site anchor is a
+     * RECORDED tree (fixed at promote entry), so a write here makes `live ≠ recorded` →
+     * `pre-op-drift` → rescue (the write is PRESERVED). Against the pre-fix live-capture code
+     * this hook's write is absorbed into the anchor and clobbered (the test FAILS). Never used
+     * in prod (typed seam, no live caller). Distinct from the post-capture
+     * `beforeWorktreeSyncHook` / `beforeRestoreResetHook` / `beforeReadTreeRollbackHook`, which
+     * only cover the window AFTER the (former) capture.
+     */
+    beforePreOpAnchorHook?: () => void | Promise<void>;
+    /**
+     * Stage-1 (W1) H1 (FAIL-ON-OLD) — fires in the BETWEEN-`reset`/`clean` PRE-CAPTURE WINDOW
+     * of `syncWorktreeToRef` / `restorePrePromote`: AFTER the guarded `reset --hard` returns but
+     * BEFORE the point where the PRE-FIX code captured the LIVE between-command anchor
+     * (`capturePreOpAnchor`) — the exact window an external process (the user's shared-worktree
+     * IDE) writes a NEW untracked non-ignored file the paired `clean -fd` would then delete. With
+     * the W1 fix the between-command anchor is RECONSTRUCTED from RECORDED inputs
+     * (`reconstructPostResetAnchor`), so a write here makes `live ≠ reconstructed` → `pre-op-drift`
+     * → rescue (the file is PRESERVED). Against the pre-fix live-capture code the write is ADOPTED
+     * into the live anchor and `clean -fd` deletes it (the test FAILS). Distinct from
+     * `betweenDestructiveCommandsHook` (which fires INSIDE `recheck()`, AFTER the anchor is built,
+     * via `onBeforeRecheck` — too late to demonstrate the pre-capture window). Never used in prod.
+     */
+    beforeCleanRecheckAnchorHook?: () => void | Promise<void>;
+}
+/**
+ * Preflight-atomic promote of the integration tip onto the user's tree (§3.1).
+ *
+ * ALWAYS, before ANY mutation:
+ *   1. Capture `pre_promote_user_ref` (the user's current ref value).
+ *   2. Stash-commit the user's working-tree+index → `pre_image_manifest_ref`.
+ *   3. Write the `promote_started` WAL (mode-aware, keyed on pre-inputs).
+ *
+ * Then one of three modes (chosen by the user's actual state):
+ *   - clean             : FF ref+index+worktree to `integration_tip`.
+ *   - dirty-committed   : `git merge integration_tip` into the user branch (a
+ *                         merge commit). Preflight the merge — any conflict →
+ *                         abort (promote nothing) + restore the stash + surface.
+ *   - dirty-uncommitted : preflight the apply-set (incl. UNTRACKED) vs the
+ *                         uncommitted edits; no overlap → advance ref + `read-tree
+ *                         -m -u` to sync index/worktree preserving the edits;
+ *                         overlap → abort + restore stash + surface.
+ *
+ * Atomic-or-nothing: a preflight abort restores the pre-promote tree (pops the
+ * stash, §16 r4-agy) and the user tree is byte-identical to pre-promote.
+ */
+export declare function promoteIntegration(repoDir: string, taskGroupId: string, foundation: BranchFoundation, wal: PromoteWalStore, hooks?: WorktreeMergeRaceHooks): Promise<PromoteOutcome>;
+/**
+ * The result of an OFF-BRANCH 3-way merge computed by `git merge-tree --write-tree`
+ * (Codex #2 / LOCK #C14-PROMOTE-ATOMIC architectural fix): the merge is computed
+ * WITHOUT touching any branch ref or the worktree. `clean` carries the merged tree
+ * SHA; `conflicted` carries the conflicting paths to surface. NOTHING in the user's
+ * repo moved.
+ */
+export type MergeTreeResult = {
+    kind: 'clean';
+    mergedTree: string;
+} | {
+    kind: 'conflicted';
+    conflictPaths: string[];
+    conflictedTree: string;
+};
+/**
+ * Codex #2 (LOCK #C14-PROMOTE-ATOMIC) — compute the 3-way merge of two commits
+ * OFF-BRANCH via `git merge-tree --write-tree -z <a> <b>`. This writes the merged
+ * tree to the object store and prints it, but **moves NO ref and touches NO
+ * worktree** — replacing the old in-place `git reset --hard <pre> && git merge` that
+ * advanced the user's branch as a non-atomic side effect (so a concurrent commit in
+ * the window was orphaned). On a clean merge git returns rc 0 and prints the tree on
+ * line 1; on a conflict it returns rc 1 and emits a conflicted-file-info block whose
+ * stage entries (`<mode> <oid> <stage>\t<path>`) name every conflicting path.
+ *
+ * The `-z` form is NUL-delimited and machine-stable (verified against real git
+ * 2.50.x): `parts[0]` = the tree OID; subsequent parts up to a blank are the
+ * conflicted index entries (each a TAB-containing `<meta>\t<path>`); the trailing
+ * parts are human messages we do NOT parse. We extract the conflict paths from the
+ * TAB-bearing stage entries — robust to the exact message wording.
+ */
+export declare function mergeTreeOffBranch(repoDir: string, oursCommit: string, theirsCommit: string, opts?: {
+    hermetic?: boolean;
+}): Promise<MergeTreeResult>;
+/** The merge-base commit of `a` and `b`, or null if they share no ancestor. */
+export declare function mergeBaseOf(repoDir: string, a: string, b: string): Promise<string | null>;
+/**
+ * ALL merge-bases of `a` and `b` (`git merge-base --all`). >1 result means a
+ * criss-cross history, where `-s ort`'s merge-tree uses a RECURSIVE VIRTUAL base
+ * that a single `merge-base` does NOT reproduce — so the 3-way blobs the resolver
+ * would see could differ from what produced the conflicted tree (Stage-1 LOW-4).
+ * The CP-14 train model shouldn't produce criss-crosses (tracks branch from the
+ * shared `base_sha` and never merge each other), but `extractThreeWayConflict`
+ * fail-CLOSES to the human gate on >1 base rather than resolve against a base
+ * that may not match the merge.
+ */
+export declare function mergeBaseAllOf(repoDir: string, a: string, b: string): Promise<string[]>;
+/** A single path's tree entry on a commit (the git object identity for one side). */
+export interface TreeEntry {
+    mode: string;
+    type: 'blob' | 'commit' | 'tree';
+    oid: string;
+}
+/** The tree entry for `p` on `commitish`, or null if the path is absent there. */
+export declare function lsTreeEntry(repoDir: string, commitish: string, p: string): Promise<TreeEntry | null>;
+/**
+ * Read the raw blob bytes at `commitish:path`, or `null` if no blob is there
+ * (the path is absent / a tree / a gitlink). Hermetic + binary-safe. Used by the
+ * Wave B verified-negative walk (`merge-train.ts::requiresFinalTier2`) to re-hash
+ * the committed bytes of a resolved path and confirm they match the audited
+ * composed-file hash (§4.5 file integrity — the committed bytes ARE the audited
+ * resolution, never a tampered tree the gate would skip-Tier-2 over).
+ */
+export declare function readBlobAtPath(repoDir: string, commitish: string, p: string): Promise<Buffer | null>;
+/**
+ * The HERMETIC integration diff `a..b`, or `null` when it exceeds `maxBytes` or
+ * cannot be produced (the caller fails closed — never reviews a partial/altered
+ * diff). Runs under the SAME hermetic env + pinned config every CP-14 git op uses
+ * AND explicitly disables `--no-ext-diff` / `--no-textconv` (Wave B Stage-2 r1
+ * codex HIGH): an ambient `GIT_EXTERNAL_DIFF` / `diff.external` / a textconv driver
+ * must NOT be able to alter or hide the bytes the mandatory final-tip Tier-2
+ * reviewer sees. `--no-color` keeps the output plain for the prompt.
+ */
+export declare function readDiffHermetic(repoDir: string, a: string, b: string, maxBytes: number): Promise<string | null>;
+/**
+ * 3-way merge of three blob OIDs at the BLOB level via `git merge-file -p
+ * --diff3` (§4.2). Writes the blobs to temp files (NOT the worktree) so no
+ * `.gitattributes` driver/filter applies; `--diff3` forces the base section
+ * regardless of `merge.conflictStyle`. A null `baseOid` (add/add) uses an empty
+ * base. Returns the merged text (with diff3 conflict markers where it couldn't
+ * auto-merge). `merge-file` exits non-zero on conflicts — that is expected
+ * (allowFail), not an error.
+ */
+export declare function diff3MergeBlobs(repoDir: string, oursOid: string, baseOid: string | null, theirsOid: string): Promise<string>;
+/**
+ * Extract the full 3-way {@link ConflictFileMeta} for one conflicting `path`,
+ * plus the diff3 conflicted blob (for content-eligible conflicts; null
+ * otherwise). `oursCommit` = the current integration tip (the §4.5 COUNTERPART);
+ * `theirsCommit` = the merging TRACK branch — matching
+ * `mergeTreeOffBranch(currentTip, trackTip)`'s arg order. The conflict KIND is
+ * derived structurally from the three tree entries; non-regular / mode / type /
+ * delete / submodule conflicts are surfaced via `conflictKind` so the classifier
+ * routes them to the human gate (§4.3 class-3). `hasLfs` / `hasDangerousAttr` are
+ * set by the caller from the existing W2 pre-scans (they cover the whole touched
+ * set, not just conflicts).
+ */
+export declare function extractThreeWayConflict(repoDir: string, oursCommit: string, theirsCommit: string, p: string): Promise<{
+    meta: ConflictFileMeta;
+    conflictedBlob: string | null;
+    multipleMergeBases: boolean;
+}>;
+/**
+ * Assemble a CLEAN resolved tree (§4.3): start from the conflicted tree that
+ * `mergeTreeOffBranch` wrote, and REPLACE each resolved path's conflicted blob
+ * with the clean resolved blob. Uses a throwaway HERMETIC index (`read-tree` →
+ * `update-index --cacheinfo` per resolved path → `write-tree`), so the user's
+ * real index is never touched and no ambient `GIT_*` perturbs it. Returns the
+ * resolved tree OID (which the merge-train then commits + CAS-advances onto the
+ * integration ref, AFTER the ConflictResolution audit is durable — §3.2).
+ */
+export declare function assembleResolvedTree(repoDir: string, conflictedTree: string, resolved: ReadonlyMap<string, {
+    bytes: Buffer;
+    mode: string;
+}>): Promise<string>;
+/**
+ * Build a commit object for `tree` with the given ordered `parents` via
+ * `git commit-tree` — NO ref moves, NO worktree touch (Codex #2 architectural fix).
+ * Returns the new commit SHA. The author/committer identity comes from the repo's
+ * own git config (the same identity a `git merge` would have used).
+ *
+ * `opts.date` (W2 — Stage-1 M1) — when provided, the AUTHOR and COMMITTER dates are
+ * BOTH pinned to this value (a git date string, e.g. an ISO-8601 or `@<epoch> +0000`)
+ * so the resulting commit SHA is a PURE FUNCTION of `(tree, parents, message, identity,
+ * date)`. The W2 merge-train passes a deterministic, input-derived date so a crash-
+ * recovery re-merge reproduces the BYTE-IDENTICAL commit (not just an identical tree) —
+ * making the §3.2 "deterministically identical commit" guarantee true, and removing the
+ * wall-clock-time SHA-instability landmine for any future SHA-based dedup. When ABSENT
+ * (the W1 promote path), behavior is BYTE-IDENTICAL to before: the commit picks up the
+ * ambient wall-clock date exactly as a `git merge` would (W1 keys on refs/trees, never on
+ * a commit SHA's stability).
+ *
+ * `opts.identity` (W2 — Stage-2 r1 M1 / agy F-02) — when provided, the commit's
+ * author+committer NAME and EMAIL are pinned to this generic bot identity, the commit
+ * encoding is forced to `UTF-8` (`-c i18n.commitEncoding=UTF-8`, neutralizing an ambient
+ * `i18n.commitEncoding` that would otherwise add an `encoding` header), and signing is
+ * disabled (`-c commit.gpgsign=false`, no `-S`). Without these pins `commit-tree` reads
+ * `user.name`/`user.email` from the ambient env/config, so two hosts (or the same host
+ * after a config change) produce DIFFERENT merge commit SHAs for identical inputs —
+ * breaking the §3.2 deterministic-replay / SHA-dedup guarantee. With the pin the
+ * merge-train commit SHA is a PURE function of `(tree, parents, message, fixed identity,
+ * fixed date, fixed encoding, no signature)`. The pins apply ONLY to CodeVibe's own
+ * machine-generated MERGE commits on the integration branch — the user's own work commits
+ * (on the track branches) are NEVER touched. `opts.identity` is W2-only; the W1 promote
+ * path passes neither `date` nor `identity` and stays BYTE-IDENTICAL (ambient identity +
+ * date + config, exactly as a `git merge` would).
+ */
+export declare function commitTreeOffBranch(repoDir: string, tree: string, parents: readonly string[], message: string, opts?: {
+    date?: string;
+    identity?: {
+        name: string;
+        email: string;
+    };
+}): Promise<string>;
+export interface RevertToPrePromoteOutcome {
+    status: 'restored' | 'rescued' | 'noop';
+    /** When rescued: the rescue ref + the user's divergent tip we preserved. */
+    rescueRef?: string;
+    userTip?: string;
+    /** Why the revert rescued instead of restoring (surfaced to the user). */
+    rescueReason?: string;
+}
+/**
+ * Restore a PROMOTED-then-rejected group's user tree to its PRE-PROMOTE state
+ * (LOCK #C14-REVERT, §3.1): ref + index + worktree → `pre_promote_user_ref` +
+ * the tracked stash (`pre_image_manifest_ref`) + the durable untracked tree
+ * (HIGH-1) — NEVER `base_sha`, NEVER content-only.
+ *
+ * COMPARE-AND-SWAP: auto-restore ONLY if the user's ref is still exactly the
+ * recorded `promoted_tip` AND the index/worktree match the expected promoted tree.
+ * If the user MOVED the ref / committed on top since promote → create a RESCUE ref
+ * `codevibe/rescue/<group>/<repo>` at the user's current tip and route to surface
+ * (never auto-discard user commits).
+ *
+ * HIGH-2: a post-promote UNTRACKED add doesn't change the index tree, so the CAS
+ * tree-match still passes — but the restore's `clean -fd` WOULD delete it. So
+ * BEFORE restoring, snapshot the live untracked set; any untracked path that was
+ * NOT part of the pre-promote capture is the user's post-promote work →
+ * rescue-ref + surface instead of `clean`-ing it away (LOCK #C14-REVERT).
+ *
+ * NEW-MEDIUM (same data-loss class as HIGH-2, narrower trigger): HIGH-2's guard is a
+ * path-name SET DIFFERENCE — it catches only *newly added* untracked paths. A user
+ * who EDITS THE CONTENT of a PRE-EXISTING untracked file (same path, no rename) after
+ * a `dirty_uncommitted` promote passes that guard; then the restore's
+ * `restoreUntrackedTree` (`checkout <pre-promote-tree> -- .`) would overwrite it with
+ * the captured pre-promote content, silently LOSING the post-promote edit — and
+ * report `restored`. `clean`/`dirty_committed` are immune (their worktree-clean CAS
+ * catches any drift), but `dirty_uncommitted` sets `requireCleanWorktree = false`, so
+ * nothing else catches it. So BEFORE restoring, hash-compare each live untracked path
+ * that IS in the pre-image set against its captured blob; ANY mismatch → rescue-ref +
+ * surface (mirror the addition-rescue path), never silently overwrite.
+ *
+ * MEDIUM-1: if re-applying the tracked stash conflicts, do NOT report `restored` —
+ * rescue-ref the conflicted state + surface.
+ */
+export declare function revertToPrePromote(repoDir: string, taskGroupId: string, repoId: string, wal: PromoteWalStore, hooks?: WorktreeMergeRaceHooks): Promise<RevertToPrePromoteOutcome>;
+export interface PromoteRecoveryOutcome {
+    taskGroupId: string;
+    repoId: string;
+    /**
+     * - `fully_promoted`   : user HEAD already == the mode-aware expected promoted
+     *                        HEAD → record `promote_committed` (no tree mutation).
+     * - `untouched`        : user ref still == pre_promote_user_ref + clean → the
+     *                        promote never started its mutation; resume is the
+     *                        caller's job (W1 reports it; no-op here).
+     * - `partial_restored` : a partial mutation was found → restored from the stash.
+     * - `rescued`          : the live worktree carries user POST-CRASH work (a path/
+     *                        content in NEITHER the pre- nor post-promote snapshot) →
+     *                        rescue-ref'd + surfaced, NEVER auto-restored over (H6).
+     */
+    resolution: 'fully_promoted' | 'untouched' | 'partial_restored' | 'rescued';
+    /** When rescued (H6): the rescue ref + the unexplained user paths surfaced. */
+    rescueRef?: string;
+    rescueReason?: string;
+}
+/**
+ * Mode-aware crash recovery for one `(group, repo)` with a `promote_started` WAL
+ * but no `promote_committed` (§3.2). The expected promoted HEAD depends on
+ * `promote_mode`:
+ *   - clean             → integration_tip
+ *   - dirty_committed   → a commit with parents [pre_promote_user_ref,
+ *                         integration_tip] AND tree == expected_post_promote_tree
+ *   - dirty_uncommitted → integration_tip (+ preserved-edits, tree-matched)
+ *
+ * Then: fully-promoted (HEAD matches by parents+tree) → write `promote_committed`;
+ * untouched (ref == pre_promote_user_ref, clean) → report untouched (resume/no-op);
+ * partial → restore from the stash (`pre_image_manifest_ref`).
+ */
+export declare function recoverPromote(repoDir: string, rec: PromoteWalRecord, wal: PromoteWalStore, hooks?: WorktreeMergeRaceHooks): Promise<PromoteRecoveryOutcome>;
+/**
+ * Recover EVERY `(group, repo)` with a started-but-not-committed promote WAL
+ * (startup reconciliation, §3.2). Idempotent on replay: a fully-promoted record
+ * just writes `promote_committed`; an untouched one is a no-op; a partial one
+ * restores. Returns one outcome per recovered record.
+ */
+export declare function recoverAllPromotes(resolveRepoDir: (rec: PromoteWalRecord) => string | null, wal: PromoteWalStore): Promise<PromoteRecoveryOutcome[]>;
+/**
+ * Hot-path GC after a per-promote/recovery transition (§16 r4-agy) — SHARED-OBJECT-
+ * STORE SAFE (MEDIUM-2). The user's real repo shares its object store with
+ * concurrent worktree shadows (`workspace-shadow.ts`); a sibling worktree's
+ * in-flight merge may hold loose objects NOT yet anchored to any ref. `git gc
+ * --prune=now` drops git's 2-week grace and would prune exactly those → corrupting
+ * a concurrent op. So the per-promote path does NOT aggressively prune: it only
+ * `git worktree prune` (reaps administrative records for removed worktrees — never
+ * touches a sibling's live objects) and a `git gc --auto` (which respects the
+ * default grace + only runs when git's own heuristics say it's worth it).
+ * Aggressive `--prune=now` is reserved for {@link gcGroupTerminal}, which is called
+ * ONLY when the whole group is terminal (no sibling worktree is in flight).
+ * Best-effort — a GC failure is non-fatal.
+ */
+export declare function gcDanglingPromptly(repoDir: string, opts?: {
+    hermetic?: boolean;
+}): Promise<void>;
+/**
+ * GC for a GROUP-TERMINAL transition (MEDIUM-2). This group's worktrees/branches
+ * are being torn down, but the user's repo SHARES its object store with concurrent
+ * UNRELATED groups' worktree shadows (`workspace-shadow.ts`), whose in-flight merges
+ * may hold loose objects NOT yet anchored to any ref — and a human gate review can
+ * legitimately keep such a sibling op un-anchored for far longer than a few minutes.
+ *
+ * M2 FIX: the previous `--prune=10.minutes.ago` could reap a concurrent >10-min
+ * review's unanchored objects → corruption. So we do NOT use a sub-hour prune on
+ * the shared store: `git worktree prune` (admin records only — never a sibling's
+ * objects) + `git gc --auto` (git's default 2-week prune grace + its own
+ * worth-it heuristics). Reaping THIS group's aborted-merge loose objects is left
+ * to git's normal grace-respecting GC — correctness over promptness on a shared
+ * store. Best-effort.
+ */
+export declare function gcGroupTerminal(repoDir: string): Promise<void>;
+/**
+ * Terminal cleanup of a group's CP-14 branch resources for one repo: delete the
+ * track/integration/stash/rescue refs + the promote WAL, then GC. Called on a
+ * group-terminal state (accept-after-promote OR reject-revert-complete). Keeps
+ * the rescue ref when one was created (the user's divergent work) unless
+ * `dropRescue` is set.
+ */
+export declare function cleanupGroupRepo(repoDir: string, taskGroupId: string, repoId: string, trackIndices: readonly number[], wal: PromoteWalStore, opts?: {
+    dropRescue?: boolean;
+}): Promise<void>;

package/dist/local-model/__tests__/installer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-model/__tests__/manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-model/__tests__/ollama.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-model/__tests__/runtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/local-model/__tests__/state.test.d.ts

@@ -0,0 +1 @@
+export {};