@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/local-executor/promote-wal-store.d.ts

@@ -0,0 +1,301 @@
+/** The current promote-WAL schema version (append-only; bump on a breaking shape change). */
+export declare const PROMOTE_WAL_VERSION: 1;
+/**
+ * The three promote modes (§3.1). They differ ONLY in the adopt target a crash
+ * recovery must reconstruct:
+ *   - `clean`              — FF the user ref+index+worktree to `integration_tip`.
+ *   - `dirty_committed`    — `git merge integration_tip` into the user branch →
+ *                            a MERGE commit with parents [pre_promote_user_ref,
+ *                            integration_tip] (NOT a FF to integration_tip).
+ *   - `dirty_uncommitted`  — advance the ref to integration_tip + apply the tree
+ *                            preserving the non-overlapping uncommitted edits.
+ */
+export type PromoteMode = 'clean' | 'dirty_committed' | 'dirty_uncommitted';
+/** The durable promote-WAL record (§3.1). */
+export interface PromoteWalRecord {
+    version: typeof PROMOTE_WAL_VERSION;
+    taskGroupId: string;
+    repoId: string;
+    /** The per-repo base snapshot = user repo HEAD at dispatch. */
+    baseSha: string;
+    /** The integration branch tip we are promoting onto the user tree. */
+    integrationTip: string;
+    /** The user's branch ref NAME (e.g. `refs/heads/main`) being advanced. */
+    userRefName: string;
+    /** Which of the three promote modes this WAL is for (drives mode-aware adopt). */
+    promoteMode: PromoteMode;
+    /**
+     * The user's ref value BEFORE the promote (the EXACT restore target for revert/
+     * recovery — NEVER `base_sha`; the user may have committed `U` before dispatch).
+     */
+    prePromoteUserRef: string;
+    /**
+     * The durable stash-commit SHA capturing the user's TRACKED working-tree +
+     * index at promote time (= `codevibe/stash/<group>/<repo>`). Restored on revert/
+     * recovery. `null` only when the tracked tree was clean with nothing to stash.
+     *
+     * NOTE (W1 HIGH-1 fix): `git stash create` does NOT durably capture UNTRACKED
+     * files (proven against real git 2.50.x — the `create`-produced commit has no
+     * untracked `^3` parent, and `git stash apply <raw-sha>` never restores `-u`
+     * content). So untracked files are captured SEPARATELY in
+     * {@link preImageUntrackedTree}; this ref covers tracked+index only.
+     */
+    preImageManifestRef: string | null;
+    /**
+     * The durable TREE sha capturing the user's UNTRACKED (non-ignored) files at
+     * promote time (= `codevibe/untracked/<group>/<repo>`), built via a temp-index
+     * `write-tree` over the exact `git ls-files --others --exclude-standard` set.
+     * Restored on revert/recovery so a dirty-uncommitted promote's untracked edits
+     * survive the `clean -fd` that pairs with the restore reset (LOCK #C14-REVERT,
+     * "never auto-discard user work"). `null` / the empty tree when none existed.
+     * Absent on records written by an older W1 build (treated as "no untracked").
+     */
+    preImageUntrackedTree?: string | null;
+    /**
+     * The expected post-promote TREE sha (§3.1 r4 Codex). For `dirty_committed`
+     * this is the tree of the user-merge commit; for clean/dirty_uncommitted it is
+     * the integration tip's tree (clean) or the merged-preserving tree (uncommitted).
+     * Recovery matches the adopt target by parents AND tree.
+     */
+    expectedPostPromoteTree: string;
+    /**
+     * The expected post-promote WORKTREE snapshot tree (W1 Stage-2 H1/H2/H3). A
+     * git tree of the user's COMPLETE post-promote worktree — every TRACKED file
+     * (with its live, possibly-unstaged content + mode) AND every UNTRACKED
+     * (non-ignored) file, built by an `add -A` over a temp index seeded from HEAD.
+     *
+     * Unlike {@link expectedPostPromoteTree} (the INDEX tree — which for
+     * `dirty_uncommitted` matches the integration tree and so does NOT capture the
+     * preserved unstaged tracked edit, nor any untracked file), this captures the
+     * EXACT on-disk state the promote leaves behind. Revert/recovery recompute the
+     * live snapshot and `diff-tree` it against this; ANY difference (a tracked edit,
+     * an untracked add/delete, a mode/exec-bit or file↔symlink type change) is the
+     * user's post-promote work → rescue, never auto-clobber (LOCK #C14-REVERT). It
+     * is symlink-correct natively (git stores a symlink as a 120000 blob of its
+     * target-path string), closing the `hash-object`-follows-symlink false-rescue.
+     *
+     * Absent on records written by an older W1 build (treated as "no worktree
+     * manifest" → the legacy index-tree CAS still applies, fail-safe).
+     */
+    expectedPostPromoteWorktreeTree?: string | null;
+    /**
+     * The user's PRE-promote WORKTREE snapshot tree (W1 Stage-2 H6) — the complete
+     * on-disk state (tracked-with-unstaged + untracked, mode/type/symlink-aware)
+     * captured BEFORE any mutation. Crash recovery uses it as the SECOND known-good
+     * anchor: a partial mid-mutation worktree's content is, path-by-path, drawn from
+     * EITHER this pre-promote snapshot OR the {@link expectedPostPromoteWorktreeTree}.
+     * Any live path whose content matches NEITHER is the user's POST-CRASH work → the
+     * recovery rescue-refs + surfaces instead of clobbering it (never auto-discard).
+     * Absent on older W1 records (H6 guard then no-ops → legacy partial restore).
+     */
+    prePromoteWorktreeTree?: string | null;
+    /**
+     * W1 Stage-2 (Codex r12 H1 / M1) — the RAW-BYTE digest over the NORMALIZING-attribute
+     * paths ({@link filteredSurfacePaths}: `text`/`eol`/`filter`/encoding/`ident`) of the
+     * PRE-promote worktree, captured from the live on-disk bytes BEFORE any mutation (when
+     * the worktree is provably the pre-promote state).
+     *
+     * Why persist it: the worktree-snapshot trees ({@link prePromoteWorktreeTree},
+     * {@link expectedPostPromoteWorktreeTree}) are built by `git add -A`, which NORMALIZES
+     * a path carrying such an attribute — so two DIFFERENT raw byte states (e.g. CRLF vs LF)
+     * map to the SAME snapshot blob. The transient op-site `PreOpAnchor` carried a live raw
+     * digest, but the durable WAL did not — so (a) the op-site guard could not use a
+     * KNOWN-tree anchor without losing raw-byte protection (Codex r12 H1), and (b)
+     * `detectWorktreeDrift` / `unexplainedRecoveryPaths` FAILED CLOSED on the mere PRESENCE
+     * of a normalizing path (Codex r12 M1: a false RESCUE on an unchanged `.gitattributes
+     * *.txt text` repo). Persisting the digest lets both compare RAW bytes: an unchanged
+     * normalizing surface yields the SAME digest → clean restore/recover; a real raw-byte
+     * change yields a DIFFERENT digest → rescue. Absent on older W1 records (the consumers
+     * fall back to the conservative fail-closed-on-presence stance, fail-safe-as-before).
+     */
+    prePromoteNormalizingRawDigest?: string | null;
+    /**
+     * W1 Stage-2 (Codex r12 H1 / M1) — the RAW-BYTE digest over the normalizing-attribute
+     * paths of the POST-promote worktree, captured from the live on-disk bytes right after
+     * the promote landed (when the worktree is provably the post-promote state). The
+     * post-promote analog of {@link prePromoteNormalizingRawDigest}. Absent on older W1
+     * records (consumers fall back to fail-closed-on-presence).
+     */
+    expectedPostPromoteNormalizingRawDigest?: string | null;
+    /**
+     * `blake3`-class key over the PRE-promote inputs (§3.1):
+     *   hash(repoId, base_sha, integration_tip, merge_impl_id, promote_mode,
+     *        pre_promote_user_ref).
+     * Includes `promote_mode` + `pre_promote_user_ref` because the dirty-committed
+     * mode lands a user-MERGE commit (not a FF), so its adopt target differs by mode.
+     */
+    expectedPromoteKey: string;
+    /**
+     * The actually-promoted tip — written only on `promote_committed` (the adopt
+     * target HEAD that landed). `null` while still `promote_started`.
+     */
+    promotedTip: string | null;
+    /**
+     * The promote-WAL state (§3.1 + round-5 Codex #3):
+     *   - `promote_started`   — written BEFORE any mutation; the recovery work-set.
+     *   - `promote_committed` — the promote fully landed; recovery is a no-op.
+     *   - `promote_aborted`   — a TERMINAL no-crash abort (a preflight conflict / overlap,
+     *     or a rolled-back read-tree refusal): NOTHING was left mutated (the user tree is
+     *     byte-identical to pre-promote), so this is NOT recovery work.
+     *     {@link PromoteWalStore.listStartedNotCommitted} EXCLUDES it — otherwise a
+     *     completed non-crash abort would be mistaken for a crashed-mid-promote record
+     *     and drive a stale-anchor partial-restore/rescue loop. The record is retained
+     *     (not deleted) as an audit trail; a retry overwrites it via `writeStarted`.
+     */
+    state: 'promote_started' | 'promote_committed' | 'promote_aborted';
+    /** Why the promote terminally aborted (round-5 Codex #3) — set only on `promote_aborted`. */
+    abortReason?: string | null;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+/** The inputs the engine hands to {@link PromoteWalStore.writeStarted}. */
+export interface PromoteStartedInput {
+    baseSha: string;
+    integrationTip: string;
+    userRefName: string;
+    promoteMode: PromoteMode;
+    prePromoteUserRef: string;
+    preImageManifestRef: string | null;
+    /** The durable untracked-files tree (HIGH-1) — `null`/empty-tree when none. */
+    preImageUntrackedTree?: string | null;
+    expectedPostPromoteTree: string;
+    /**
+     * The expected post-promote WORKTREE snapshot tree (W1 Stage-2 H1/H2/H3) — the
+     * complete on-disk state (tracked-with-unstaged-content + untracked, mode/type/
+     * symlink-aware) the promote leaves behind. `null`/absent → no manifest.
+     */
+    expectedPostPromoteWorktreeTree?: string | null;
+    /**
+     * The user's PRE-promote WORKTREE snapshot tree (W1 Stage-2 H6) — the second
+     * known-good anchor for crash-recovery's divergence guard. `null`/absent → none.
+     */
+    prePromoteWorktreeTree?: string | null;
+    /**
+     * W1 Stage-2 (Codex r12 H1 / M1) — the raw-byte digest over the pre-promote
+     * normalizing-attribute paths (live on-disk bytes, captured BEFORE any mutation).
+     * `null`/absent → none (consumers fall back to fail-closed-on-presence).
+     */
+    prePromoteNormalizingRawDigest?: string | null;
+    /** The pinned merge implementation id (§4.2) folded into the key. */
+    mergeImplId: string;
+}
+/**
+ * The pre-input-only promote key (§3.1). A `sha256` over the ordered pre-promote
+ * inputs (we use sha256 — the codebase's hash primitive — in lieu of blake3; the
+ * design's "blake3" is the discipline, not a binding algorithm choice, and the
+ * #589 store hashes with sha256 too). Determinism is what matters: identical
+ * inputs → identical key → a crash-redelivered promote dedups.
+ */
+export declare function computePromoteKey(args: {
+    repoId: string;
+    baseSha: string;
+    integrationTip: string;
+    mergeImplId: string;
+    promoteMode: PromoteMode;
+    prePromoteUserRef: string;
+}): string;
+/**
+ * The pure durable promote-WAL store. ONE instance per desktop; all paths derive
+ * from {@link rootDir} (overridable for deterministic tests). Mirrors the #589
+ * `RevertManifestStore` at-rest guards exactly.
+ */
+export declare class PromoteWalStore {
+    private readonly rootDir;
+    constructor(opts?: {
+        rootDir?: string;
+    });
+    /** The per-`(group, repo)` directory `<root>/<taskGroupId>/<repoId>/`. */
+    private repoDir;
+    /**
+     * Validate `seg` is a safe SINGLE path segment so a malicious id can't escape
+     * `<root>/` (defense-in-depth, mirrors #589-G `RevertManifestStore.safeSegment`).
+     */
+    private safeSegment;
+    private mkdirSecure;
+    /**
+     * Refuse to operate under a path whose any in-`rootDir` component is a symlink
+     * (LOCK #589-G "no symlink following"). lstat each component from `rootDir`
+     * down; a symlinked component throws. Missing components are fine.
+     */
+    private assertNoSymlinkComponents;
+    /** Atomic write: `<final>.tmp.<pid>.<rand>` (0600) → fsync → rename → fsync(dir). */
+    private atomicWrite;
+    private readJson;
+    /**
+     * Write the `promote_started` WAL record BEFORE any tree mutation (§3.1). The
+     * `expected_promote_key` is computed from the pre-promote inputs + `repoId`.
+     * Idempotent: a re-call for the SAME `(group, repo)` whose key matches an
+     * existing record returns it WITHOUT re-writing (a crash-redelivered promote
+     * dedups). A re-call whose key DIFFERS (the user moved the ref between prepare
+     * and promote → a recapture) overwrites the fresh record — but ONLY while the
+     * existing record is still `promote_started` (see W1 Stage-2 H1 below).
+     *
+     * W1 Stage-2 H1 — NEVER overwrite a `promote_committed` record (regardless of
+     * key). Once a promote has committed, its `pre_promote_user_ref` +
+     * `pre_image_manifest_ref` ARE the durable restore target a future revert/recovery
+     * depends on (LOCK #C14-REVERT). A redelivered promote that arrives AFTER success —
+     * with a DIFFERENT key because the user moved the ref since (so the pre-input dedup
+     * at the matching-key branch below does not catch it) — must NOT replace that
+     * committed restore target with a fresh `promote_started` whose
+     * `pre_image_manifest_ref` captures the POST-promote state. Doing so would make a
+     * later revert restore the wrong tree. So a `promote_committed` record is
+     * IMMUTABLE here: we return it unchanged. A genuine recapture (`expected_promote_key`
+     * change because the user moved the ref) is only honored BEFORE any mutation, i.e.
+     * while the record is still `promote_started`; the engine recovers an existing
+     * started record before a retry writes a new one.
+     */
+    writeStarted(taskGroupId: string, repoId: string, input: PromoteStartedInput): Promise<PromoteWalRecord>;
+    /**
+     * Atomically UPDATE the now-known expected-tree fields of an in-flight
+     * `promote_started` record IN PLACE (W1 Stage-2 M1). Some expected-state values
+     * are only known AFTER the user-tree mutation lands (the `dirty_committed`
+     * merge-commit tree; the post-promote worktree snapshot tree for every mode), so
+     * the engine records a preliminary record up front, mutates, then calls this to
+     * pin the real values.
+     *
+     * CRITICAL (M1 — the delete-then-rewrite crash window): this re-uses the SAME
+     * atomic write→fsync→rename of {@link atomicWrite} on the SAME record path, so
+     * the WAL file is NEVER absent at any instant — a crash leaves either the old or
+     * the new `promote_started` record, both recoverable by
+     * {@link listStartedNotCommitted}. (The previous delete-then-`writeStarted`
+     * left a no-WAL window in which an advanced user ref had NO record to recover.)
+     *
+     * No-op (returns the record unchanged) when there is no record, the record is
+     * not `promote_started`, or nothing actually changed. NEVER changes the
+     * `expectedPromoteKey` (the pre-input identity) — only the post-mutation fields.
+     */
+    updateStarted(taskGroupId: string, repoId: string, fields: {
+        expectedPostPromoteTree?: string;
+        expectedPostPromoteWorktreeTree?: string | null;
+        expectedPostPromoteNormalizingRawDigest?: string | null;
+    }): Promise<PromoteWalRecord | null>;
+    /**
+     * Mark a started promote COMMITTED, recording the actually-promoted tip (§3.1).
+     * No-op when there is no record (nothing started). Idempotent.
+     */
+    writeCommitted(taskGroupId: string, repoId: string, promotedTip: string): Promise<void>;
+    /**
+     * Round-5 (Codex #3) — mark a started promote TERMINALLY ABORTED. Called after a
+     * no-mutation preflight/overlap abort OR a successfully ROLLED-BACK read-tree
+     * refusal: the user tree is byte-identical to pre-promote, so this record is NOT
+     * recovery work and {@link listStartedNotCommitted} must exclude it. We write a
+     * terminal `promote_aborted` state (retained as an audit trail; a retry overwrites
+     * it via {@link writeStarted}).
+     *
+     * NEVER downgrades a `promote_committed` record (idempotent + immutable-once-committed
+     * — a committed restore target is durable, LOCK #C14-REVERT). No-op when there is no
+     * record. Idempotent on an already-`promote_aborted` record.
+     */
+    markAborted(taskGroupId: string, repoId: string, abortReason?: string): Promise<void>;
+    /** Read the WAL record for `(group, repo)`, or `null` if none. */
+    readRecord(taskGroupId: string, repoId: string): Promise<PromoteWalRecord | null>;
+    private writeRecord;
+    /** Delete the WAL record for `(group, repo)` (terminal cleanup / GC). */
+    deleteRecord(taskGroupId: string, repoId: string): Promise<void>;
+    /**
+     * List every `(group, repo)` that has a started-but-not-committed WAL record —
+     * the recovery work-set (§3.2). A `promote_committed` record is NOT returned
+     * (the promote fully landed; recovery is a no-op there).
+     */
+    listStartedNotCommitted(): Promise<PromoteWalRecord[]>;
+}

package/dist/local-executor/resolution-set-index.d.ts

@@ -0,0 +1,51 @@
+import type { ConflictClass } from './conflict-types';
+/**
+ * The canonical, durable description of one resolved slot's resolution set.
+ * Keyed in the index by its `resolution_set_hash` (== {@link computeResolutionSetHash}
+ * of this entry). Carries everything the verify walk needs to PROVE the trigger
+ * without re-running the resolver: which conflicts, their classes, and the
+ * composed-file integrity hashes (the §4.5 file-level `resolved_blob_hash`).
+ */
+export interface ResolutionSetEntry {
+    /** The conflict_ids resolved in this slot (any order; canonicalized in the hash). */
+    conflictIds: string[];
+    /** conflict_id → its resolution class (1 deterministic reconcile / 2 LLM). */
+    classByConflictId: Record<string, ConflictClass>;
+    /**
+     * Resolved path → SHA-256 of the COMPOSED file bytes (the §4.5 file-integrity
+     * hash; SEPARATE from the per-hunk `resolved_blob_hash` so hunk-replay is
+     * unaffected — Stage-2 r2 agy HIGH / r1 codex MED). The verify walk re-hashes
+     * the committed tree's blob at this path and requires equality.
+     */
+    composedFileHashByPath: Record<string, string>;
+}
+/**
+ * The CANONICAL `resolution_set_hash` over an entry (Stage-2 r3 codex HIGH).
+ * Deterministic + reproducible at BOTH the live-resolve site (the trailer it
+ * stamps) and the verify/replay sites (so a resumed re-resolve reproduces the
+ * IDENTICAL trailer → the byte-identical merge-commit SHA the §3.2 recovery
+ * relies on). Folds in the class of every conflict + the composed-file hash of
+ * every path, length-prefixed + NUL-separated so no two distinct sets collide
+ * via field-boundary ambiguity (mirrors `computeConflictId`).
+ */
+export declare function computeResolutionSetHash(entry: ResolutionSetEntry): string;
+/**
+ * The durable resolution-set index (§2.3). Keyed by `resolution_set_hash`. Written
+ * AUDIT-BEFORE-REF (before the resolved merge commits + the integration ref
+ * advances) alongside the `ConflictResolution` records, so the ref never advances
+ * past a resolution set whose class summary + composed-file hashes are not durable.
+ * Idempotent on the set-hash key (the entry for a given hash is immutable — a
+ * second put with the same hash is a no-op / keeps the original).
+ */
+export interface ResolutionSetIndex {
+    get(setHash: string): Promise<ResolutionSetEntry | null>;
+    put(setHash: string, entry: ResolutionSetEntry): Promise<void>;
+}
+/** In-memory {@link ResolutionSetIndex} (tests + same-process cache). */
+export declare class InMemoryResolutionSetIndex implements ResolutionSetIndex {
+    private readonly bySetHash;
+    get(setHash: string): Promise<ResolutionSetEntry | null>;
+    put(setHash: string, entry: ResolutionSetEntry): Promise<void>;
+    /** Test helper: number of distinct durable resolution sets. */
+    get size(): number;
+}

package/dist/local-executor/revert-reconcile.d.ts

@@ -0,0 +1,89 @@
+import { RevertManifestStore } from './durable-store';
+/** The engine's terminal view of a group, for the reconcile decision. */
+export type EngineGroupState = 'in_flight' | 'terminal_kept' | 'terminal_rejected' | 'unknown';
+/**
+ * Minimal COMMIT-only contract for the two-phase `claimGroupDecision` wire, used
+ * by the CLAIM-crash recovery (HIGH-1) to drive the persisted claim terminal. A
+ * structural subset of the desktop `ClaimGroupDecisionClient` (gate-decision-submit.ts)
+ * so the reconcile stays decoupled from the heavier AppSync surface. The reconcile
+ * only ever issues the `commit` phase (the CLAIM already landed pre-crash); on an
+ * already-terminal group the engine echoes `already_committed` (idempotent).
+ */
+export interface ReconcileCommitClient {
+    claimGroupDecision(input: {
+        taskGroupId: string;
+        sessionId: string;
+        phase: 'commit';
+        decision: string;
+        verdictIdempotencyKey: string;
+        claimToken: string;
+        notes?: string;
+    }, sessionKeyBase64?: string): Promise<{
+        phase: string;
+        decision: string;
+        claimToken: string;
+        groupStatus?: string;
+    }>;
+}
+export interface ReconcileDeps {
+    store: RevertManifestStore;
+    /**
+     * Probe the engine's terminal view of a group. ABSENT for a group the engine
+     * no longer knows about → `'unknown'` (an orphan; the TTL fallback GC's it).
+     */
+    probeEngineState: (taskGroupId: string) => Promise<EngineGroupState>;
+    /**
+     * Run the (idempotent, crash-resumable) revert for a reject-terminal group.
+     * Drives the journal-backed reverse-apply to completion-or-conflict-stop and
+     * marks the lifecycle `reject_revert_complete`.
+     */
+    revertGroup: (taskGroupId: string) => Promise<{
+        reverted: string[];
+        alreadyReverted: string[];
+        conflicts: string[];
+    }>;
+    /**
+     * HIGH-1 / LOCK #589-J — the COMMIT transport for CLAIM-crash recovery. Present
+     * for a TEAM session (the same `claimGroupDecision` SDK the live decision uses).
+     * ABSENT → CLAIM-crash recovery is skipped (the marker survives for the next
+     * startup; tests that don't exercise crash recovery omit it). The COMMIT echoes
+     * the PERSISTED `claimToken`; an already-terminal group returns `already_committed`.
+     */
+    commitClient?: ReconcileCommitClient;
+    /**
+     * HIGH-1 — the session id the COMMIT is scoped to (the desktop's live session).
+     * Required alongside `commitClient`. ABSENT → CLAIM-crash recovery is skipped.
+     */
+    sessionId?: string;
+    /**
+     * HIGH-1 — the session-key resolver, consulted ONLY when the persisted
+     * `pendingDecision.notes` is present (a `*_WITH_NOTES` decision re-encrypts its
+     * notes on the resumed COMMIT, exactly as the live path does). ABSENT or
+     * resolving `null` for a notes-bearing pending decision → the COMMIT is deferred
+     * to a later start (the marker survives; never block on a missing key).
+     */
+    getSessionKey?: (sessionId: string) => Promise<string | null>;
+    /** Optional clock injection for deterministic GC tests. */
+    now?: () => number;
+}
+export interface ReconcileResult {
+    /** Groups whose revert was (re)driven this startup. */
+    reverted: string[];
+    /** Groups marked accepted (engine kept; manifest flips GC-eligible). */
+    accepted: string[];
+    /**
+     * HIGH-1 — groups whose CLAIMED-but-not-COMMITted decision was resumed +
+     * driven terminal this startup (the persisted `claimToken` re-COMMITted).
+     */
+    recoveredCommits: string[];
+    /** Group ids GC'd after reconcile. */
+    gced: string[];
+}
+/**
+ * PHASE-589/469 W3.1 (C4) — reconcile every durable revert manifest against the
+ * engine's terminal view, THEN GC. Reconcile MUST run before GC so a
+ * terminal-but-not-yet-reverted group is reverted before its manifest could be
+ * collected. NEVER throws — a per-group error is logged + skipped (the manifest
+ * survives for the next startup).
+ */
+export declare function reconcileRevertManifestsThenGc(deps: ReconcileDeps): Promise<ReconcileResult>;

package/dist/local-executor/revert-runner.d.ts

@@ -0,0 +1,17 @@
+import { RevertManifestStore } from './durable-store';
+/** The outcome of a group revert (Fork A: clean-where-safe + surface). */
+export interface RevertResult {
+    /** Paths reverted (created→deleted, modified/deleted→restored) THIS pass. */
+    reverted: string[];
+    /** Paths already at their pre-image (idempotent no-op; NOT a conflict). */
+    alreadyReverted: string[];
+    /** Paths the user edited after apply — left as-is, surfaced (NEVER clobbered). */
+    conflicts: string[];
+}
+/**
+ * Revert the whole group's applied tree off its durable manifest + journal.
+ * Reverse `promoteOrder`; clean-where-safe; idempotent + crash-resumable.
+ *
+ * `workingDir` is the real workspace root the team applied into.
+ */
+export declare function revertGroup(store: RevertManifestStore, taskGroupId: string, workingDir: string): Promise<RevertResult>;

package/dist/local-executor/shared-contract-detector.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The structural category a path matched. `lockfile` is special — it is a
+ * shared-contract surface, but the classifier routes it to the class-1
+ * deterministic reconciler FIRST (§4.3); every other category is a hard
+ * route-to-human (class-3) surface.
+ */
+export type SharedContractCategory = 'proto' | 'graphql' | 'thrift' | 'avro' | 'flatbuffers' | 'capnp' | 'xsd' | 'wsdl' | 'openapi' | 'lockfile' | 'always_gate_glob' | 'planner';
+/** A positive shared-contract match for a path. `null` = not a shared contract. */
+export interface SharedContractMatch {
+    /** The structural category that matched. */
+    category: SharedContractCategory;
+    /** Whether this is a HARD route-to-human (class-3) surface. `false` ONLY for
+     * `lockfile` (a deterministic class-1 reconciler is tried first, §4.3). */
+    hardGate: boolean;
+    /** Human-readable reason (for audit + the human-gate surface). */
+    reason: string;
+    /** The matching rule (extension / glob / basename / planner pattern). */
+    rule: string;
+}
+/** Tuning inputs (injected for tests; production wires the team config). */
+export interface SharedContractDetectorOptions {
+    /** Operator/config "always gate" globs (additive class-3). Default: none. */
+    alwaysGateGlobs?: readonly string[];
+    /** The planner's `shared_contracts` paths/globs (§7) — ADDITIVE class-3. */
+    plannerSharedContracts?: readonly string[];
+}
+/**
+ * Compile a path glob to a RegExp. Supports `**` (any path segments incl. `/`),
+ * `*` (any chars except `/`), `?` (one char except `/`), and literal segments.
+ * Anchored full-match. Path separators are normalized to `/`. Deterministic and
+ * dependency-free (we deliberately avoid adding minimatch). Matching is
+ * case-SENSITIVE for globs (paths are case-sensitive on the platforms we target
+ * for the merge worktree); extension/basename surfaces above are the
+ * case-insensitive ones.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+/**
+ * Does `path` match `glob`? A glob with NO `/` is matched against the BASENAME
+ * (so `*.proto` matches `a/b/x.proto`); a glob WITH `/` is matched against the
+ * full normalized path. Mirrors common .gitignore/CODEOWNERS glob intuition.
+ */
+export declare function pathMatchesGlob(path: string, glob: string): boolean;
+/**
+ * Classify a single repo-relative `path` as a shared-contract surface, or
+ * `null` if the path/glob tier does not flag it. Order (first match wins, most
+ * specific first): hard-gate extensions → OpenAPI basename → lockfile basename
+ * → always-gate globs → planner shared_contracts. The planner set is checked
+ * LAST and is purely ADDITIVE — it never suppresses a structural match.
+ */
+export declare function detectSharedContract(path: string, opts?: SharedContractDetectorOptions): SharedContractMatch | null;
+/**
+ * True iff `path` is a HARD route-to-human (class-3) shared-contract surface —
+ * i.e. a structural/glob/planner match that is NOT the deferred lockfile case.
+ * Convenience for the classifier; lockfiles return `false` here (they go to the
+ * class-1 reconciler first).
+ */
+export declare function isHardSharedContract(path: string, opts?: SharedContractDetectorOptions): boolean;

package/dist/local-executor/spawn.d.ts

@@ -0,0 +1,34 @@
+import { AuthorityScope } from './authority';
+import { ImplementorHandle, ProbeHandle, ProcessRole, ReviewerHandle, SpawnArgs, SpawnHandleBase } from './types';
+/**
+ * CP-7 §3.6 — build the COMPLETE env a substrate-confined implementor sees.
+ * The LE calls this when constructing the `SubstrateSpec` (the env is baked into
+ * the sandbox at `launch()`, so `exec()` injects nothing further).
+ *
+ * It folds the three marker keys (`CHILD`/`ROLE`/`QUORUM`) INTO the wiped base
+ * env — it does **NOT** merge `process.env` (that ambient passthrough is exactly
+ * the I1 path the substrate exists to close). The collision guard runs first:
+ * the wiped base MUST NOT itself carry a marker key (the LE owns those).
+ *
+ * `sanitizedBase` is the already-wiped env the LE assembled (no ambient creds);
+ * the role is always `'implementor'` for the substrate path, but taken as a
+ * parameter so the marker value is explicit + testable.
+ */
+export declare function buildSubstrateImplementorEnv(role: ProcessRole, sanitizedBase: Readonly<Record<string, string>>): Record<string, string>;
+export declare function spawnImplementor(scope: AuthorityScope, args: SpawnArgs): Promise<ImplementorHandle>;
+/**
+ * CP-7 §8 (Stage-1-resolved) — LOW-LEVEL legacy reviewer spawn primitive.
+ *
+ * **DEAD for quorum reviewers.** The LIVE reviewer path is
+ * `QuorumLoop.spawnOneSeat` → `ReviewerRegistry.evaluate` → provider
+ * `.evaluate` → `runReviewer` (`reviewer/subprocess.ts`), which runs the
+ * reviewer UNDER the CP-7 substrate + broker. This primitive (and its only
+ * production-shaped caller, `LocalExecutor.spawnReviewer`, which now THROWS)
+ * runs UNSANDBOXED with the merged `process.env` — it must NEVER be used to
+ * spawn a quorum reviewer (it would leak ambient vendor creds, the moat hole
+ * CP-7 closes). Kept exported only for the low-level `spawn.test.ts` unit test
+ * of the marker/lifecycle plumbing. Do NOT wire it into a reviewer dispatch.
+ */
+export declare function spawnReviewer(scope: AuthorityScope, args: SpawnArgs): Promise<ReviewerHandle>;
+export declare function spawnHealthProbe(scope: AuthorityScope, args: SpawnArgs): Promise<ProbeHandle>;
+export declare function spawnSubprocess(scope: AuthorityScope, args: SpawnArgs): Promise<SpawnHandleBase>;