@quantiya/codevibe-core 2.0.1 → 2.0.2

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

@@ -0,0 +1,713 @@
+import { MergeJournalStore } from './merge-journal-store';
+import type { AgentKind } from './types';
+import { type BranchFoundation } from './worktree-merge';
+import { type RenderedConflict, type TrackIntentDiff } from './wb2-review-bundle';
+import { type ConflictResolverContext } from './merge-conflict-resolve';
+/**
+ * The per-track input the merge-train consumes — the W2 view of the planner's §7
+ * `Track`. `repoId` + `trackIndex` form the total ordering key; `depends_on` drives
+ * the global topological order (§4.1). `trackTip` is the resolved persistent
+ * track-branch tip (`codevibe/track/<group>/<trackIndex>`) the train merges IN.
+ * `testSurfaces` (the declared `test_surfaces`) are unioned across all tracks for
+ * Tier-1 (§4.4). `deletedPaths` carry the diff's `change_kind:'deleted'` set so the
+ * declared-test runner's deletion guard holds.
+ */
+export interface MergeTrainTrack {
+    trackIndex: number;
+    repoId: string;
+    /** The persistent track-branch tip to merge IN (`theirs`). */
+    trackTip: string;
+    /** Global topo dependencies (other tracks' `trackIndex`) — §4.1. */
+    dependsOn?: number[];
+    /** Declared `test_surfaces` (workspace-rel) unioned into Tier-1 (§4.4). */
+    testSurfaces?: string[];
+    /** The diff's `change_kind:'deleted'` paths (declared-test deletion guard). */
+    deletedPaths?: string[];
+    /**
+     * CP-14 WB2 — the implementor agent + its per-spawn task id that authored this
+     * track. The agentic class-2 resolver re-dispatches this (the INCOMING track's)
+     * implementor to resolve the slot's conflicts; folded into the generation
+     * identity (`tracksEqual`) + persisted in the journal track record. Optional on
+     * the type so pre-B2 construction sites compile; the agentic resolve path
+     * FAILS CLOSED (human-gate) when absent.
+     */
+    implementorAgent?: AgentKind;
+    implementorTaskId?: string;
+    /** The implementor's worktree-shadow path, recorded informationally in the journal. */
+    worktreePath?: string | null;
+}
+/** A resolved, total, unique, replay-stable merge-train order (§4.1). */
+export interface MergeOrder {
+    /** The tracks in execution order. */
+    ordered: MergeTrainTrack[];
+    /** The execution order as a list of `trackIndex` (the canonical journal order). */
+    resolvedOrder: number[];
+}
+/** Thrown when a decomposition cannot yield a total, unique, acyclic order (§4.1). */
+export declare class MergeOrderError extends Error {
+    readonly reason: 'cycle' | 'dangling-ref' | 'duplicate-key';
+    constructor(reason: 'cycle' | 'dangling-ref' | 'duplicate-key', message: string);
+}
+/**
+ * Compute the GLOBAL, deterministic, replay-stable merge-train order (LOCK
+ * #C14-ORDER, §4.1).
+ *
+ * Order = GLOBAL topological by `depends_on`, tiebroken by the TOTAL key
+ * `(repoId ascending, trackIndex ascending)`. Because no two tracks share
+ * `(repoId, trackIndex)`, the key is total and unique, so the order is total,
+ * unique, and re-derivable IDENTICALLY from the journal on crash recovery.
+ *
+ * Fail-closed (defensive, surfaced as {@link MergeOrderError}, never a guessed
+ * order):
+ *   - a `depends_on` referencing an unknown `trackIndex` → `dangling-ref`;
+ *   - a CYCLE in the `depends_on` graph → `cycle`;
+ *   - a DUPLICATE `(repoId, trackIndex)` key → `duplicate-key`.
+ *
+ * N-way octopus is rejected by construction — the order is strictly sequential
+ * (the train merges one slot at a time). Written GLOBAL-FIRST (the `(repoId,
+ * trackIndex)` total key spans the whole workspace) so W4's multi-repo reuses it
+ * unchanged; W2 exercises one repo's tracks (all sharing one `repoId`), where the
+ * tiebreak degenerates to `trackIndex` ascending.
+ *
+ * Determinism: Kahn's algorithm with a STABLE ready-set selection — at each step the
+ * ready node with the smallest total key is chosen, so the output is a single
+ * canonical linearization (not just "a" topo order). Identical inputs → identical
+ * order, every time + on replay.
+ */
+export declare function computeMergeOrder(tracks: readonly MergeTrainTrack[]): MergeOrder;
+/** The merge-commit trailer that carries the step's pre-input merge key (§3.2). */
+export declare const MERGE_KEY_TRAILER = "Codevibe-Merge-Key";
+/**
+ * W3 (§3.2 audit-before-ref) — the merge-commit trailer carrying the
+ * `resolution_set_hash` (the sorted set of `conflict_id`s resolved in this slot).
+ * Present ONLY on a slot that required conflict resolution; a CLEAN (auto-merged)
+ * slot's message is byte-identical to W2 (no second trailer), so the W2 recovery
+ * SHA-recomputation probe is unaffected for clean slots. For a RESOLVED slot,
+ * recovery re-derives the identical message (the resolution set replays
+ * deterministically by `conflict_id`), so the trailer is reproducible.
+ */
+export declare const RESOLUTION_SET_TRAILER = "Codevibe-Resolution-Set";
+/**
+ * CP-14 WB2 (#C14-WB2-AGENTIC-IDENTITY) — the merge-commit trailer carrying the
+ * AGENTIC resolution INSTANCE id, present ONLY on a slot resolved by the agentic
+ * (read+write) resolver. The promote-gate verify (§2.5 `verifyAgenticSlot`) + recovery
+ * read it to fetch the `AgenticResolutionRecord` (via `getAgentic`) and authenticate the
+ * committed FULL tree OID against `resolved_tree_oid` — agentic output is
+ * non-deterministic, so these commits are NEVER SHA-recomputed (recovery adopts them by
+ * parents + MERGE_KEY). Absent for clean / class-1 / legacy-llm slots, so their message
+ * stays byte-identical and their deterministic SHA-recompute recovery is unaffected.
+ */
+export declare const AGENTIC_INSTANCE_TRAILER = "Codevibe-Agentic-Instance";
+/**
+ * The DETERMINISTIC author+committer date pinned on every merge-train commit
+ * (Stage-1 M1). A fixed canonical epoch (`@0 +0000`) makes the merge commit SHA a
+ * PURE FUNCTION of `(tree, parents, message, repo identity)` — no wall-clock time
+ * leaks in — so a crash-recovery re-merge of identical inputs reproduces the
+ * BYTE-IDENTICAL commit (the §3.2 "deterministically identical commit" guarantee).
+ * A fixed value is sound: distinct merge commits still differ by their tree/parents/
+ * message (the message carries the slot + trackIndex + key), and the integration
+ * branch is CodeVibe-owned (never the user's; the date is cosmetic on it). The single
+ * user-tree mutation is the W1 promote, which keeps the ambient date (unchanged).
+ */
+export declare const MERGE_COMMIT_DATE = "@0 +0000";
+/**
+ * The generic BOT identity pinned on every merge-train commit (Stage-2 r1 M1 / agy F-02,
+ * Option B). The author+committer name/email of CodeVibe's own machine-generated MERGE
+ * commits is pinned to this fixed value so the merge-commit SHA is a PURE FUNCTION of
+ * `(tree, parents, message, this identity, MERGE_COMMIT_DATE, UTF-8 encoding, no signature)`
+ * — identical across hosts + on crash-recovery replay, regardless of the ambient
+ * `user.name`/`user.email`/`i18n.commitEncoding`/`commit.gpgsign`. Pinned ONLY for the
+ * integration-branch merge commits the train creates; the user's OWN work commits (on the
+ * track branches) keep their real identity (the train never re-authors them).
+ */
+export declare const MERGE_COMMIT_IDENTITY: {
+    readonly name: "CodeVibe Agent";
+    readonly email: "agent@codevibe.ai";
+};
+/**
+ * The CANONICAL merge-commit message for a slot (Codex MEDIUM — recovery-trailer
+ * authentication). The SINGLE source of truth for the message string used at BOTH the live
+ * train site ({@link runMergeTrain}), the recovery re-merge site ({@link recoverMergeTrain}),
+ * AND the recovery DETERMINISTIC-RECOMPUTATION probe ({@link findMergeCommitByTrailer}). The
+ * commit SHA is a pure function of `(tree, parents, message, identity, date, encoding, no-sig)`;
+ * the probe authenticates a trailer-matched candidate by RE-DERIVING the expected SHA, so the
+ * message it feeds `commit-tree` MUST be byte-for-byte the message the live train committed.
+ * Centralizing it here makes that invariant un-driftable — a future edit to the wording changes
+ * all three call sites at once.
+ */
+export declare function buildMergeCommitMessage(trackIndex: number, orderSlot: number, mergeKey: string, resolutionSetHash?: string, agenticInstanceId?: string): string;
+/** A surfaced, non-throwing merge-train outcome. */
+export type MergeTrainOutcome = {
+    /** Every slot merged (clean or W3-resolved) → integration advanced to `integrationTip`. */
+    status: 'merged';
+    integrationTip: string;
+    /**
+     * W3 (§4.4, LOCK #C14-FINAL-TIER2 / #C14-MOAT) — true if ANY class-2
+     * (LLM-assisted) resolution was applied to a slot in **THIS run**. Named to
+     * NOT overclaim authority: it is the SINGLE-PASS Tier-2 signal, NOT a
+     * resume-safe promote gate. The adopt-committed-slot fast path skips
+     * already-landed slots, so a class-2 byte from a PRIOR run is absent here.
+     *
+     * **LOCK #C14-W3-TIER2-AUTHORITY (wiring wave):** the promote gate MUST
+     * derive the authoritative "requires final-tip Tier-2" from the DURABLE
+     * ConflictResolution store (or a `RESOLUTION_SET_TRAILER` walk of the
+     * integration history) — NEVER from this single-pass boolean alone. For a
+     * single uninterrupted pass this flag IS complete; across a resume it is a
+     * lower bound only. Absent the resolver (W2) → always `false`.
+     */
+    class2ResolvedThisRun: boolean;
+    /** Per-class resolution counts applied this run (informational / audit). */
+    resolutionCounts: {
+        class1: number;
+        class2: number;
+    };
+} | {
+    /**
+     * A slot CONFLICTED → the train HALTED: no commit at that slot, the integration
+     * ref is where slot k-1 left it, NOTHING promoted, the user tree untouched.
+     */
+    status: 'conflict_halt';
+    /** The order slot (0-based) that conflicted. */
+    haltedSlot: number;
+    /** The conflicting track's index. */
+    trackIndex: number;
+    /** The conflicting paths surfaced to the user / W3 classifier. */
+    conflictPaths: string[];
+    /** The integration tip the train reached BEFORE the conflict (slot k-1's commit). */
+    integrationTip: string;
+} | {
+    /**
+     * W3 (§4.3) — a slot conflicted AND, with the conflict resolver wired, at
+     * least one conflicting path is class-3 (route-to-human): a shared-contract
+     * surface, a dangerous attr/submodule/LFS/binary/mode/type/rename conflict,
+     * a lockfile version-delta, or an over-budget / fail-closed class-2 resolve.
+     * Per LOCK #C14-AON the WHOLE slot escalates (no partial resolution): no
+     * commit at that slot, the integration ref is where slot k-1 left it,
+     * NOTHING promoted, the user tree untouched. The gated paths + their triggers
+     * go to the human gate.
+     */
+    status: 'conflict_human_gate';
+    /** The order slot (0-based) whose conflicts could not be auto-resolved. */
+    haltedSlot: number;
+    /** The conflicting track's index. */
+    trackIndex: number;
+    /** The class-3 paths + their human-gate triggers + reasons. */
+    gated: {
+        path: string;
+        trigger: string;
+        reason: string;
+    }[];
+    /** The integration tip the train reached BEFORE this slot (slot k-1's commit). */
+    integrationTip: string;
+} | {
+    /**
+     * A path carries a DANGEROUS `.gitattributes` attribute (`merge=`/`filter=`/LFS/
+     * `working-tree-encoding`/`ident`) — the train HALTS BEFORE any merge or Tier-1
+     * checkout (Stage-2 r1 H2 pre-merge touched-path scan + Stage-2 r2 H2 pre-checkout
+     * full-integration-tree scan). Nothing committed, the integration ref is untouched,
+     * NOTHING promoted, the user tree untouched. The attribute-bearing paths require a
+     * human gate (§4.2 r3-M), so a custom merge driver or a smudge filter never runs.
+     */
+    status: 'attribute_halt';
+    /** The attribute-bearing paths surfaced to the user / human gate. */
+    attributePaths: string[];
+    /** The integration tip BEFORE the halt (= the foundation tip; nothing advanced). */
+    integrationTip: string;
+} | {
+    /**
+     * (Codex FIX D) — the repo carries a non-empty `$GIT_DIR/info/grafts` file. Grafts are a
+     * SEPARATE, deprecated fake-parent mechanism that `GIT_NO_REPLACE_OBJECTS=1` does NOT
+     * disable (proven vs real git 2.50.1: a graft still rewrites `rev-list --parents` /
+     * `merge-base` reachability under the full W2 hermetic env), so they corrupt the parent
+     * graph the deterministic merge + the recovery trailer-walk depend on. The train HALTS
+     * fail-closed BEFORE any merge/checkout — nothing committed, nothing promoted, user tree
+     * untouched. Requires the human to remove/convert the grafts file.
+     */
+    status: 'grafts_halt';
+    /** The resolved grafts file path (a non-secret identifier), surfaced to the human gate. */
+    graftsPath: string;
+    /** The integration tip BEFORE the halt (= the foundation tip; nothing advanced). */
+    integrationTip: string;
+} | {
+    /**
+     * (Codex r7 FIX B) — the repo is SHALLOW (`.git/shallow` /
+     * `git rev-parse --is-shallow-repository`). A shallow boundary makes git pretend recorded
+     * parents don't exist, rewriting the merge-base / reachability graph the deterministic merge
+     * + the recovery trailer-walk depend on (a SIBLING of the grafts lever that
+     * `GIT_NO_REPLACE_OBJECTS=1` does NOT cover — proven vs real git 2.50.1 that the same base +
+     * tips clean-merge in a full repo but `refusing to merge unrelated histories` in a shallow
+     * one). The train HALTS fail-closed BEFORE any merge/checkout — nothing committed, nothing
+     * promoted, user tree untouched. Requires the human to UNSHALLOW the repo (`git fetch
+     * --unshallow`).
+     */
+    status: 'shallow_halt';
+    /** The resolved `shallow` file path (a non-secret identifier), surfaced to the human gate. */
+    shallowPath: string;
+    /** The integration tip BEFORE the halt (= the foundation tip; nothing advanced). */
+    integrationTip: string;
+} | {
+    /**
+     * (Codex r6 FIX 3, HIGH) — the EFFECTIVE git config carries a CUSTOM MERGE DRIVER
+     * (`merge.<name>.driver`). W2 never legitimately configures one, so any configured driver is
+     * pure attack surface: a track can commit a repo-local `.git/config` `merge.default=keepours`
+     * + `merge.keepours.driver=<script>` (the named-default lever — runs on attr-free files,
+     * invisible to the `.gitattributes` scan) OR a `[merge "text"] driver=<script>` that SHADOWS
+     * the built-in `text` driver the r5 `-c merge.default=text` pin relies on (PROVEN vs real git
+     * 2.50.1 this session: the shadow FIRES + silently clean-resolves a conflict). The train HALTS
+     * fail-closed BEFORE any merge/recovery/checkout — nothing committed/promoted, user tree
+     * untouched. The configured driver NAMES (not the script values) go to the human gate.
+     */
+    status: 'merge_driver_config_halt';
+    /** The configured custom-merge-driver NAMES (non-secret identifiers); never the script values. */
+    mergeDriverNames: string[];
+    /** The integration tip BEFORE the halt (= the foundation tip; nothing advanced). */
+    integrationTip: string;
+};
+/**
+ * Run the deterministic ordered merge-train for ONE repo (§4.1 / LOCK #C14-ORDER).
+ * Advances the ONE integration branch by merging each ordered track tip onto the
+ * current tip, write-ahead-journaled (§3.2). On the FIRST conflict it HALTS (no
+ * commit, ref not advanced past slot k-1) and returns `conflict_halt` — W2 has no
+ * conflict resolver (that is W3); a conflict is a deterministic dead-end here.
+ *
+ * `foundation` is the W1 {@link BranchFoundation} (the integration branch at
+ * `base_sha`); the train consumes the persistent TRACK branches directly
+ * (`trackBranchName`) — there are NO per-track promoted branches (resolved decision
+ * #3). `mergeImplId` is the W2 derived id ({@link resolveMergeImplId}).
+ *
+ * Idempotent on replay (the journal): a re-run after a crash recovers via
+ * {@link recoverMergeTrain} FIRST (the caller drives that), then re-merges only the
+ * un-landed slots deterministically — identical inputs reproduce the identical
+ * commit (off-branch `merge-tree` + `commit-tree` with a fixed message trailer).
+ */
+export declare function runMergeTrain(repoDir: string, taskGroupId: string, foundation: BranchFoundation, orderedTracks: readonly MergeTrainTrack[], journal: MergeJournalStore, mergeImplId: string, resolver?: ConflictResolverContext): Promise<MergeTrainOutcome>;
+/**
+ * Derive the `merge_gate_id` from the ACTUAL integration-tip inputs (§4.5): a
+ * `sha256` over `(base_sha, the ORDERED merged track tips, the final integration
+ * TREE)`. A real tip-move (a different ordered set or a different final tree) yields
+ * a NEW id → re-validate the gate; a pure replay of identical inputs yields the
+ * SAME id → dedup. We use `sha256` (the codebase hash primitive) in lieu of the
+ * design's blake3 (the discipline, not a binding algorithm) — same as `computePromoteKey`.
+ *
+ * AUDIT-ANCHOR identity-alignment (resolved decision #4): W2 DERIVES + surfaces this
+ * id but does NOT call `submitMergeGateVerdict` — the id it produces here is the one
+ * the eventual live verdict's `mergeGateId` must equal (the audit anchor on the
+ * shipped `MergeGateResult` kind).
+ */
+export declare function deriveMergeGateId(args: {
+    baseSha: string;
+    /** The merged track tips IN THE TRAIN ORDER (the ordered set of `theirs` inputs). */
+    orderedTrackTips: readonly string[];
+    /** The final integration TREE (not the commit — the content the promote lands). */
+    finalIntegrationTree: string;
+}): string;
+/**
+ * Test-only race-injection hooks for {@link recoverMergeTrain} (mirrors the W1
+ * `WorktreeMergeRaceHooks` idiom). Prod passes none. `beforeRewindHook` fires AFTER the
+ * PASS-1-observed integration tip is captured but BEFORE the CAS rewind, so a test can move
+ * the ref in that exact window and prove the rewind's compare-and-swap REFUSES (M2) rather
+ * than blind-clobbering the concurrent move.
+ */
+export interface MergeTrainRecoveryHooks {
+    beforeRewindHook?: () => void | Promise<void>;
+    /**
+     * Fires in the all-committed completion path (every slot found landed by PASS-1) right
+     * before the tip is ensured (F-01), so a test can delete the branch in that window and
+     * prove recovery RECREATES it rather than returning `reconciled` with the branch deleted.
+     */
+    beforeTipEnsureHook?: () => void | Promise<void>;
+}
+/** A surfaced merge-train recovery outcome (§3.2). */
+export interface MergeTrainRecoveryOutcome {
+    taskGroupId: string;
+    repoId: string;
+    /**
+     * - `reconciled`     : every started-not-committed slot was reconciled (a landed
+     *                      merge re-recorded via its trailer, or reset+re-merged) →
+     *                      the integration branch is at the deterministic resolved tip.
+     * - `blocked`        : a re-merge could not complete (e.g. a {@link MergeOrderError}
+     *                      or a CAS/state mismatch) → a TERMINAL surface state; the
+     *                      integration ref is left where it is, reconciliation keeps
+     *                      surfacing it. Never silently completes.
+     * - `nothing_to_do`  : no started-not-committed slots (a clean/terminal journal).
+     */
+    resolution: 'reconciled' | 'blocked' | 'nothing_to_do';
+    /** The integration tip after recovery (when reconciled). */
+    integrationTip?: string;
+    /** On `blocked`: the surfaced reason. */
+    blockedReason?: string;
+}
+/**
+ * Crash-resume the merge-train for one `(group, repo)` (§3.2). For each
+ * `merge_started` step WITHOUT a `merge_committed`:
+ *   - search the integration branch's REACHABLE history BACKWARD for a commit whose
+ *     `${MERGE_KEY_TRAILER}` trailer == the step's `expected_merge_key`
+ *     (`git log --grep`). git stores only PARENT pointers, so a forward scan from
+ *     `pre_tip` is impossible; the backward walk of the reachable history is the valid
+ *     recovery probe (§3.2 r3-recovery).
+ *   - FOUND (the merge landed; only the journal write was lost) → write
+ *     `merge_committed` (NO re-merge).
+ *   - NOT FOUND → reset the integration branch to the step's `pre_tip` (the W1
+ *     guarded discipline: a CAS ref rewind + `git clean -fd` of any throwaway
+ *     worktree — but the train operates OFF-BRANCH with no persistent integration
+ *     worktree, so the reset is a ref-level rewind) + RE-MERGE deterministically.
+ *
+ * RESET INVALIDATES LATER SLOTS (§3.2 r4 Codex): a reset to slot k rewinds the
+ * integration branch past any LATER slots whose trailer-commit is no longer reachable
+ * from the rewound tip — every such later slot is RE-MERGED in order. A later slot
+ * whose commit is STILL reachable (the reset didn't rewind past it) is kept.
+ *
+ * A blocked re-merge (a CAS/state mismatch, a `MergeOrderError`) → `blocked` (the
+ * `revert_halted`-equivalent terminal): reconciliation keeps surfacing it, never
+ * silently completes. After the recovery transitions, GC the dangling aborted-merge
+ * commits via {@link gcDanglingPromptly}.
+ *
+ * Idempotent on replay: a second recovery over a now-reconciled journal is a no-op.
+ */
+export declare function recoverMergeTrain(repoDir: string, taskGroupId: string, repoId: string, journal: MergeJournalStore, mergeImplId: string, hooks?: MergeTrainRecoveryHooks, resolver?: ConflictResolverContext): Promise<MergeTrainRecoveryOutcome>;
+/** A surfaced Tier-1 outcome on the merged integration tip. */
+export interface Tier1Outcome {
+    /**
+     * - `'pass'`           — build/typecheck/tests + declared surfaces all green;
+     * - `'fail'`           — at least one gate/surface failed;
+     * - `'attribute_halt'` — (Stage-2 r2 H2) a path in the FULL integration tree carries a
+     *   dangerous `.gitattributes` attribute, so the `git worktree add` checkout would run a
+     *   smudge/encoding/ident filter (or a custom merge driver materialized into the tree) on
+     *   a file. Tier-1 HALTS BEFORE the checkout — no smudge runs — and the caller surfaces a
+     *   gate-level `attribute_halt` (the human gate, §4.2 r3-M).
+     */
+    status: 'pass' | 'fail' | 'attribute_halt';
+    /** The gate that failed (when failed): a verification-gate kind or `'declared_tests'`. */
+    failedGate?: 'build' | 'tests' | 'typecheck' | 'declared_tests';
+    /** A short, content-free reason for the surface (exit codes / gate name only). */
+    reason?: string;
+    /** On `attribute_halt`: the dangerous-attribute paths in the integration tree (Stage-2 r2 H2). */
+    attributePaths?: string[];
+}
+/** Which verification gates Tier-1 runs (§4.4 build + tests; typecheck when configured). */
+export interface Tier1GateConfig {
+    build?: boolean;
+    tests?: boolean;
+    typecheck?: boolean;
+    /** Per-gate timeout (ms). */
+    timeoutMs?: number;
+}
+/**
+ * Tier-1 on the FINAL integration tip (§4.4, LOCK #C14-A): check out the integration
+ * tip into a THROWAWAY git worktree (the same `git worktree add` / `remove --force`
+ * + `prune` lifecycle workspace-shadow.ts uses for implementor shadows — applied
+ * directly here, no `WorkspaceShadow` ceremony, since this worktree is read-only +
+ * disposable), then run build/typecheck/tests (`runVerificationGates`' per-gate
+ * wrappers) + the UNION of the tracks' declared `test_surfaces`
+ * ({@link runDeclaredTestSurfaces}) with `cwd`/`shadowDir` = the integration worktree
+ * (reads worktree-confined). PASS/FAIL is derived from exit codes (LE-cannot-lie). On
+ * FAIL → surface + NO promote (all-or-nothing, §5). The worktree is torn down in a
+ * `finally` regardless of outcome.
+ *
+ * Resolved-decision note: `runVerificationGates` (verification-runner.ts) requires the
+ * live Class-A AppSync emitter pipeline — coupling this STANDALONE flag-gated W2 module
+ * to that infra would be wrong. The per-gate WRAPPERS (`runBuildGate`/`runTestsGate`/
+ * `runTypecheckGate`) are the worktree-confined primitive that yields PASS/FAIL from
+ * exit codes WITHOUT the emit infra — the minimal-correct Tier-1 substrate. The live
+ * wiring (a later migration) can route through the full emitter.
+ */
+export declare function runTier1OnIntegrationWorktree(repoDir: string, integrationTip: string, tracks: readonly MergeTrainTrack[], config?: Tier1GateConfig): Promise<Tier1Outcome>;
+/** The surfaced result of the full W2 merge gate (train → Tier-1 → promote). */
+export type MergeGateResult = {
+    /** Every step landed: train merged, Tier-1 green, the promote landed on the user tree. */
+    status: 'promoted';
+    integrationTip: string;
+    mergeGateId: string;
+    promotedTip?: string;
+} | {
+    /** A conflict halted the train — nothing promoted, user tree untouched. */
+    status: 'conflict_halt';
+    haltedSlot: number;
+    trackIndex: number;
+    conflictPaths: string[];
+} | {
+    /**
+     * A touched path carries a dangerous `.gitattributes` attribute (Stage-2 r1 H2) —
+     * the train HALTED before any merge / Tier-1 checkout; nothing promoted, user tree
+     * untouched. The attribute-bearing paths require a human gate (§4.2 r3-M).
+     */
+    status: 'attribute_halt';
+    attributePaths: string[];
+} | {
+    /**
+     * (Codex FIX D) — the repo carries a non-empty `$GIT_DIR/info/grafts` file (a deprecated
+     * fake-parent mechanism `GIT_NO_REPLACE_OBJECTS=1` does NOT disable). The train HALTED
+     * before any merge / recovery / checkout; nothing promoted, user tree untouched. The
+     * grafts file must be removed/converted (human gate).
+     */
+    status: 'grafts_halt';
+    graftsPath: string;
+} | {
+    /**
+     * (Codex r7 FIX B) — the repo is SHALLOW (`.git/shallow` /
+     * `git rev-parse --is-shallow-repository`), a parent-graph-rewrite lever sibling to grafts
+     * (`GIT_NO_REPLACE_OBJECTS=1` does NOT cover it). The gate HALTED fail-closed BEFORE recovery /
+     * any merge / checkout; nothing promoted, user tree untouched. The repo must be unshallowed
+     * (`git fetch --unshallow`) (human gate).
+     */
+    status: 'shallow_halt';
+    shallowPath: string;
+} | {
+    /**
+     * (Codex r6 FIX 3, HIGH) — the effective git config carries a CUSTOM MERGE DRIVER
+     * (`merge.<name>.driver`), which W2 never legitimately uses. The gate HALTED fail-closed
+     * BEFORE recovery / any merge / checkout (the scan runs at the gate entry, ahead of
+     * `recoverMergeTrain`'s `merge-tree`). Nothing promoted, user tree untouched. The configured
+     * driver must be removed (human gate). Closes BOTH the named-default
+     * (`merge.default=keepours` + `merge.keepours.driver`) AND the shadow-builtin
+     * (`merge.text.driver`) levers in one rule.
+     */
+    status: 'merge_driver_config_halt';
+    mergeDriverNames: string[];
+} | {
+    /** Tier-1 failed on the merged tip — nothing promoted, user tree untouched. */
+    status: 'tier1_fail';
+    integrationTip: string;
+    mergeGateId: string;
+    failedGate?: string;
+    reason?: string;
+} | {
+    /** The promote aborted (a preflight overlap) — user tree byte-identical. */
+    status: 'promote_aborted';
+    integrationTip: string;
+    mergeGateId: string;
+    reason?: string;
+    conflictPaths?: string[];
+} | {
+    /**
+     * Wave B (§2.2) — the train auto-resolved some conflicts but at least one
+     * conflicting path is class-3 (route-to-human): the WHOLE slot escalated
+     * (LOCK #C14-AON), nothing committed past slot k-1, nothing promoted, user
+     * tree untouched. Terminal FAIL → the existing convergence path.
+     */
+    status: 'conflict_human_gate';
+    haltedSlot: number;
+    trackIndex: number;
+    gated: {
+        path: string;
+        trigger: string;
+        reason: string;
+    }[];
+} | {
+    /**
+     * Wave B (§2.3) — the mandatory final-tip Tier-2 reviewer REJECTED the
+     * integration tip (a class-2 LLM resolution was present). Nothing promoted,
+     * user tree untouched (#C14-AON). Terminal FAIL → convergence.
+     */
+    status: 'tier2_reject';
+    integrationTip: string;
+    mergeGateId: string;
+    reason?: string;
+} | {
+    /**
+     * Wave B (§2.3, LOCK #C14-MOAT) — the final-tip Tier-2 trigger fired (a
+     * class-2 byte is present) but it could NOT be satisfied: the
+     * `finalTier2Reviewer` is absent / its audit scope is missing, the reviewer
+     * cannot run CONFINED (§2.1 path C), OR the resolution set is unprovable
+     * against the §4.5 records (a Tier-2 PASS cannot launder a missing audit
+     * record). Fail closed — NOTHING promoted, user tree untouched. Terminal FAIL.
+     */
+    status: 'tier2_unavailable';
+    integrationTip: string;
+    mergeGateId: string;
+    reason?: string;
+} | {
+    /** A recovery left the train BLOCKED (terminal surface) — nothing promoted. */
+    status: 'blocked';
+    reason?: string;
+};
+/** Inputs to {@link runWorktreeMergeGate} — the full all-or-nothing W2 sequence. */
+export interface WorktreeMergeGateArgs {
+    repoDir: string;
+    taskGroupId: string;
+    foundation: BranchFoundation;
+    tracks: readonly MergeTrainTrack[];
+    journal: MergeJournalStore;
+    /**
+     * The W1 promote step — injected so this module stays decoupled from the
+     * worktree-merge promote signature (and so tests can drive it without the WAL/git
+     * promote machinery when only the train/Tier-1 paths are under test). Production
+     * wires `promoteIntegration` (W1). On a non-`promoted` promote outcome the gate
+     * surfaces `promote_aborted` (the user tree is byte-identical).
+     */
+    promote: (integrationTip: string) => Promise<{
+        status: 'promoted' | 'aborted';
+        promotedTip?: string;
+        abortReason?: string;
+        conflictPaths?: string[];
+    }>;
+    /** Tier-1 gate config (default build + tests). */
+    tier1?: Tier1GateConfig;
+    /**
+     * Wave B (§2.2) — the conflict resolver context. PRESENT (worktree_merge +
+     * confinement precondition holds) → a class-2 (LLM-assisted) conflict is
+     * auto-resolved + the resolution set recorded; forwarded to BOTH the live train
+     * and the recovery re-merge. ABSENT → byte-identical halt-on-conflict (the
+     * legacy/unconfined path; `resolver === undefined`).
+     */
+    resolver?: ConflictResolverContext;
+    /**
+     * Wave B (§2.3, LOCK #C14-FINAL-TIER2 / #C14-MOAT) — the INJECTED final-tip
+     * Tier-2 reviewer. The gate cannot call the reviewer path directly
+     * (`QuorumLoop`/`ReviewerRegistry`); the desktop wires this to a real reviewer
+     * dispatch over the final integration diff (base → tip). It MUST itself run
+     * CONFINED (§2.1 (A)/(B)) — it returns `confined: false` when it cannot (path
+     * C), which the gate treats as fail-closed NO-PROMOTE. When the Tier-2 trigger
+     * fires and this is ABSENT, the scope (`ownerTaskId`) is missing, the reviewer
+     * is unconfined, or the resolution set is unprovable → the gate does NOT promote.
+     */
+    finalTier2Reviewer?: (args: {
+        ownerTaskId: string;
+        repoDir: string;
+        baseSha: string;
+        integrationTip: string;
+        /**
+         * CP-14 WB2 §2.4 — the AGENTIC resolver agents this gate (the incoming tracks'
+         * implementors that resolved a class-2 byte). The reviewer dispatch picks the
+         * strongest HOST-DETECTED reviewer that is best-effort INDEPENDENT of these
+         * (#C14-WB2-TIER2-INDEPENDENT); empty/absent → just the strongest detected. The
+         * Tier-2 trigger + fail-closed posture are UNCHANGED (still ALWAYS on class-2).
+         */
+        resolverAgents?: ReadonlySet<string>;
+        /**
+         * CP-14 WB2 §2.6 (additive) — the per-conflict 3-way CONTENT (base/ours/theirs)
+         * of every agentic-resolved slot + each track's INTENT diff (base → trackTip),
+         * folded into the reviewer prompt so it can verify BOTH tracks' intents survived.
+         * ALL OPTIONAL: absent (a pre-§2.6 caller, or the path-C branch) ⇒ today's bare
+         * base→tip diff (graceful degrade). The dispatcher fails closed (NO-PROMOTE) if
+         * the rendered bundle exceeds the aggregate ceiling.
+         */
+        conflictBundle?: readonly RenderedConflict[];
+        trackIntentDiffs?: readonly TrackIntentDiff[];
+    }) => Promise<{
+        verdict: 'pass' | 'reject';
+        confined: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Wave B (§2.3) — the merge-gate audit scope the Tier-2 reviewer (+ the §2.1
+     * resolver) carry (Stage-2 r2 codex LOW). When the Tier-2 trigger fires and this
+     * is absent, the gate fails closed (NO-PROMOTE) — an LLM byte never promotes
+     * without a scoped, confined Tier-2.
+     */
+    ownerTaskId?: string;
+}
+/**
+ * The full W2 all-or-nothing merge gate (§5 / LOCK #C14-AON). The sequence is:
+ *   (1) recover any in-flight train (crash-resume, §3.2) — blocked → surface, no promote;
+ *   (2) the deterministic ordered TRAIN — a conflict HALTS (user tree untouched);
+ *   (3) Tier-1 on the merged integration worktree — a fail HALTS (user tree untouched);
+ *   (4) ONE `promoteIntegration` lands the integration tip on the user tree.
+ * The group is treated as `joint` (the #589-preserving default; `independent`/
+ * `convergence` validation is W3). A halt at (1)/(2)/(3) leaves the user tree
+ * byte-identical (clean by construction — the train + Tier-1 never touch it).
+ *
+ * `merge_gate_id` is derived from the real integration-tip inputs (§4.5) and surfaced
+ * on every post-train outcome; W2 does NOT call `submitMergeGateVerdict` (that is the
+ * live `runMergeGate`'s wired job — resolved decision #4).
+ */
+export declare function runWorktreeMergeGate(args: WorktreeMergeGateArgs): Promise<MergeGateResult>;
+/**
+ * Fail-closed PRE-CHECKOUT FULL-TREE scan of the FINAL integration tip (Stage-2 r2 H2).
+ *
+ * The pre-merge {@link scanDangerousAttributes} only covers the base→tip TOUCHED paths —
+ * the surface the `merge-tree` 3-way merge actually combines. But the Tier-1 `git worktree
+ * add` checks out the ENTIRE integration tree and runs smudge/`working-tree-encoding`/
+ * `ident` filters (and would materialize the result of any `merge=` driver) on EVERY file,
+ * touched or not. The H2 attack: a track adds ONLY `.gitattributes` mapping an UNTOUCHED
+ * base file (e.g. `victim.txt`) to `filter=<evil>` → the touched set = `{.gitattributes}`
+ * (the pre-merge scan passes) → the `worktree add` checkout runs the smudge filter on the
+ * untouched `victim.txt` (arbitrary code). The merge-only reasoning that "an untouched file
+ * is a no-op" holds for the MERGE but NOT the CHECKOUT, which materializes the whole tree.
+ *
+ * So before the disposable Tier-1 worktree is added, enumerate ALL paths in the integration
+ * tree (`git ls-tree -r --name-only -z <integrationTip>`) and `git check-attr -a -z
+ * --source=<integrationTip>` them against {@link DANGEROUS_MERGE_ATTRS}; ANY dangerous attr
+ * on ANY path → HALT (the caller surfaces `attribute_halt`), so no smudge/encoding/ident
+ * filter runs on any file. `--source=<integrationTip>` resolves the attributes against the
+ * COMMITTED tree (the same `.gitattributes` the checkout would honor), reading the OBJECT
+ * STORE — the scan itself runs no filter. Fail-closed: a `ls-tree`/`check-attr` error or an
+ * older git without `--source` flags the slice / returns a marker → HALT (never silently
+ * proceeds past an undeterminable attribute, never lets a smudge run).
+ *
+ * Determinism + zero-knowledge: lists only PATHS (non-secret), never content.
+ */
+export declare function scanIntegrationTreeAttributes(repoDir: string, integrationTip: string): Promise<string[]>;
+/** Thrown when a recovery-rewind CAS loses the race (the integration ref moved). */
+export declare class RefCasMismatchError extends Error {
+    readonly ref: string;
+    readonly expectedOldSha: string;
+    constructor(ref: string, expectedOldSha: string);
+}
+/**
+ * The verified final-tip Tier-2 decision (Wave B §2.3, LOCK #C14-FINAL-TIER2 /
+ * #C14-W3-TIER2-AUTHORITY / #C14-MOAT). The skip-Tier-2 NEGATIVE is the dangerous
+ * direction (a stale/corrupt index claiming "all class-1" would promote an
+ * unreviewed LLM byte), so it is PROVEN — never trusted from a bare bit:
+ *   - `skip`       — no resolution, or every resolved conflict verified class-1
+ *                    against the §4.5 records + the committed tree → Tier-1 only.
+ *   - `tier2`      — a verified class-2 (LLM) resolution is present → mandatory
+ *                    final-tip Tier-2 before promote.
+ *   - `no_promote` — the resolution set could not be reconstructed+verified from
+ *                    the durable §4.5 records (a missing/tampered record, a
+ *                    composed-bytes-vs-tree mismatch, an unreadable history) →
+ *                    fail closed; a Tier-2 PASS cannot launder a missing audit
+ *                    record (Stage-2 r3 codex MED-1).
+ */
+export type FinalTier2Decision = {
+    decision: 'skip';
+    reason: string;
+} | {
+    decision: 'tier2';
+    reason: string;
+    /**
+     * CP-14 WB2 §2.4 — the set of AGENTIC resolver agents (the incoming tracks'
+     * implementors) that resolved a class-2 byte in the authenticated integration
+     * history. The gate picks a best-effort INDEPENDENT Tier-2 reviewer that is not
+     * among these when another host-detected agent is available (#C14-WB2-TIER2-INDEPENDENT).
+     * Empty when the only class-2 resolutions were legacy (deterministic/legacy-llm).
+     */
+    resolverAgents: ReadonlySet<string>;
+    /**
+     * CP-14 WB2 §2.6 — the per-conflict 3-way CONTENT (base/ours/theirs) of every
+     * agentic-resolved slot, re-derived in the verify walk ({@link verifyAgenticSlot})
+     * from the slot's re-conflicted parents + the merge-base, byte-bounded per side
+     * (Q-RENDER-SITE locked). Folded into the Tier-2 reviewer prompt so the reviewer
+     * judges whether the LLM resolution combined BOTH sides faithfully. A REQUIRED side
+     * that cannot render within budget → NO-PROMOTE (the walk returns no_promote).
+     */
+    conflictBundle: RenderedConflict[];
+} | {
+    decision: 'no_promote';
+    reason: string;
+};
+/**
+ * Cheap, bounded check: does `base_sha..integration_tip` contain ANY resolved-slot
+ * commit (one carrying a {@link RESOLUTION_SET_TRAILER})? Used as the gate's
+ * fail-closed backstop when NO audit context is available this run (Stage-2 r1
+ * codex HIGH — a path-C resume must not promote a prior run's resolved bytes
+ * unreviewed). FAILS CLOSED (returns `true`) on any enumeration error — an
+ * unreadable history is treated as possibly-carrying resolved bytes.
+ */
+export declare function integrationHistoryHasResolutionTrailer(repoDir: string, baseSha: string, integrationTip: string): Promise<boolean>;
+/**
+ * Decide whether the final integration tip requires a mandatory final-tip Tier-2
+ * re-pass (Wave B §2.3). Walks `base_sha..integration_tip` STRICTLY (never past
+ * base into a prior promoted group — Stage-2 r2 agy MED), and for every
+ * resolved-slot commit (one carrying a {@link RESOLUTION_SET_TRAILER}) PROVES the
+ * resolution set against the §4.5 source records + the committed tree before
+ * trusting any skip. See {@link FinalTier2Decision}.
+ */
+export declare function requiresFinalTier2(args: {
+    repoDir: string;
+    baseSha: string;
+    integrationTip: string;
+    repoId: string;
+    mergeImplId: string;
+    ctx: ConflictResolverContext;
+}): Promise<FinalTier2Decision>;