@quantiya/codevibe-core 2.0.1 → 2.0.3

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

@@ -1,7 +1,8 @@
 import type { ChildProcess } from 'node:child_process';
+import type { SubstrateHandle, SubstrateProc } from '../substrate/types';
 import type { AuthorityRefusal, AuthorityScope } from './authority';
 export type ProcessRole = 'implementor' | 'reviewer' | 'health_probe' | 'auth_probe' | 'model_probe';
-export type AgentKind = 'CLAUDE' | 'GEMINI' | 'CODEX';
+export type AgentKind = 'CLAUDE' | 'GEMINI' | 'CODEX' | 'ANTIGRAVITY';
 export type FailureClass = null | 'quota_exhausted' | 'auth_failed' | 'timeout' | 'unavailable' | 'user_aborted';
 export interface SpawnArgs {
     argv: string[];
@@ -13,8 +14,11 @@ export interface SpawnArgs {
     stdinTty?: boolean;
     stdinPayload?: string;
     signal?: AbortSignal;
+    taskId?: string;
     onProcessSpawned?: ProcessSpawnedHook;
     onProcessExited?: ProcessExitedHook;
+    substrate?: SubstrateHandle;
+    requireConfined?: boolean;
 }
 export interface ProcessSpawnedInfo {
     pid: number;
@@ -58,6 +62,10 @@ export declare class SpawnArgsInvalid extends Error {
     readonly offendingKey?: string | undefined;
     constructor(reason: string, offendingKey?: string | undefined);
 }
+export declare class SpawnConfinementUnavailable extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
 export declare const MARKER_ENV_KEYS: {
     readonly CHILD: "CODEVIBE_CHILD_PROCESS";
     readonly ROLE: "CODEVIBE_PROCESS_ROLE";
@@ -78,6 +86,32 @@ export type AuthorityAction = {
     command: string;
     argv: string[];
 };
+export interface GateDispatchPayload {
+    /** The DETERMINISTIC gate_id of this gate-run (the round-0 proposal gate id at START). */
+    gateRunId: string;
+    /** `"verification" | "reviewer_quorum" | "final_approval"` (snake_case wire form). */
+    gateType: string;
+    /** Present ONLY for `verification` gates (CP-3 — out of scope for CP-1.f single-task). */
+    verificationChecks?: string[];
+    /**
+     * Present ONLY once the per-seat reviewer panel is resolved. ABSENT at START
+     * (the proposal hasn't arrived) — `start_ports.rs:296` sets `reviewer_seats:
+     * None`. Each row is the camelCase `ReviewerSeatRow`
+     * (`{seatId, agentKind, role, reviewerPacketRef}`).
+     */
+    reviewerSeats?: GateDispatchReviewerSeat[];
+    /** Present ONLY for `final_approval` gates. */
+    finalApprovalSurface?: string;
+}
+/** One reviewer-seat row inside `GateDispatchPayload.reviewerSeats` (camelCase). */
+export interface GateDispatchReviewerSeat {
+    seatId: number;
+    /** UPPERCASE agent kind: `"CLAUDE" | "CODEX" | "GEMINI"`. */
+    agentKind: string;
+    /** UPPERCASE lens: `"ARCHITECTURE" | "CORRECTNESS" | ...`. */
+    role: string;
+    reviewerPacketRef: string;
+}
 export interface SignedEnvelope {
     algorithm: 'ed25519' | 'p384-ecdsa';
     publicKeyId: string;
@@ -85,6 +119,168 @@ export interface SignedEnvelope {
     issuedAt: string;
     nonceUlid: string;
 }
+/**
+ * Cross-track-conflict dispute context (§2.2, #C12-19). Present ONLY on a
+ * dispute re-dispatch; ABSENT (undefined) on a fresh `TrackAssigned`. The
+ * re-dispatched implementor/reviewers use it to know what to reconcile.
+ */
+export interface TrackConflictContext {
+    conflict_id: string;
+    shared_contract_ref: string;
+    peer_track_findings: unknown;
+}
+/**
+ * §2.2 `TrackAssigned` payload — launch track N. The LE spawns the implementor
+ * for this track in `state_dir`, idempotent by
+ * `(task_group_id, track_index, dispatch_generation)` (#C12-14/#C12-17).
+ */
+export interface TrackAssignedPayload {
+    task_group_id: string;
+    track_index: number;
+    task_id: string;
+    /** UPPERCASE adapter discriminator (CLAUDE | GEMINI | CODEX). */
+    implementor_agent: AgentKind;
+    /** snake_case OwnershipScope (advanced to the per-track authority scope). */
+    ownership_scope: {
+        write_paths: string[];
+        shared_contracts: {
+            path: string;
+            access: 'write' | 'read';
+        }[];
+        test_surfaces: string[];
+        auto_modified_files: string[];
+    };
+    is_shared_test_owner: boolean;
+    /** `<repo>/.codevibe/state/<task_group_id>/<track_index>/`. */
+    state_dir: string;
+    dispatch_id: string;
+    dispatch_generation: number;
+    /** Option — present on a dispute re-dispatch (#C12-19), absent on fresh. */
+    conflict_context?: TrackConflictContext;
+}
+/**
+ * §2.2 `MergeGateDispatch` payload — run the shared integration verification.
+ * The `owner_track_index` track runs the integration check named by
+ * `integration_check_spec` (§12 Q1 — CP-3 verification-gate kinds, NOT a
+ * free-form shell), classifies + signs the result (#C12-8), and reports
+ * `submitMergeGateVerdict`.
+ */
+export interface MergeGateDispatchPayload {
+    task_group_id: string;
+    merge_gate_id: string;
+    /**
+     * §12 Q1 — names CP-3 verification-runner wrapper(s). On the wire this is the
+     * `VerificationGateKind` list the owner track named at `createTaskGroup`. A
+     * single string is accepted for forward-compat and coerced to a 1-element
+     * list by the runner.
+     */
+    integration_check_spec: string | string[];
+    owner_track_index: number;
+    dispatch_id: string;
+    dispatch_generation: number;
+}
+/**
+ * §2.2 `TaskGroupHalted` payload — group halted/escalated (expanded escalation
+ * fields per the Stage-2 §11.3 fix). The LE surfaces the choices to the UI
+ * (NOTIFICATION) + signals the in-flight track processes to stop. The deep
+ * auto-resolution decision tree is server-side (#C12-3) — the LE only consumes,
+ * surfaces, and stops. [DEFERRED — GA/CP-12 Wave 3+] for choice-driven
+ * auto-actions.
+ */
+export interface TaskGroupHaltedPayload {
+    task_group_id: string;
+    halt_reason: string;
+    per_track_status: {
+        track_index: number;
+        state: string;
+        agent?: string;
+    }[];
+    gates_passed_failed?: unknown;
+    /**
+     * #584 r2 — internally-tagged union pinned to core-rs `HaltFixOwner`
+     * (`class_b_envelope.rs`, `rename_all = "snake_case"` tags +
+     * `rename_all_fields = "camelCase"`): wire `{kind: "track", trackIndex}` |
+     * `{kind: "serial_owner"}`. `normalizeTaskGroupHaltedWire` maps the field to
+     * the internal snake_case `track_index`.
+     */
+    recommended_fix_owner?: {
+        kind: string;
+        track_index?: number;
+    };
+    remaining_budget?: {
+        auto_revise_used?: number;
+        auto_revise_cap?: number;
+        wallclock_elapsed_ms?: number;
+        wallclock_cap_ms?: number;
+    };
+    /**
+     * #584 r2 — pinned to core-rs `HaltChoice` (same serde shape as
+     * `HaltFixOwner`): wire `{kind: "retry_serial_owner" | "retry_track" |
+     * "continue_manually" | "accept_partial" | "abort", trackIndex?}` — NOT a
+     * string list (the pre-#584 annotation was a wrong pin). Display-only.
+     */
+    choices: {
+        kind: string;
+        track_index?: number;
+    }[];
+}
+import type { AgentKind as ReviewerAgentKind, ReviewerRole } from '../reviewer/types';
+/**
+ * CP-1.f §3.C.21 — `REVIEWER_DISPATCH` Class B payload (engine → desktop).
+ * Tells the desktop to spawn one reviewer subprocess for the named seat; the
+ * rendered prompt is FETCHED out-of-band via `getReviewerPrompt` (the dispatch
+ * carries no inline prompt). Pinned to `class_b_envelope.rs::ReviewerDispatchPayload`.
+ */
+export interface ReviewerDispatchPayload {
+    /** Gate this dispatch belongs to (UUID string). */
+    gateId: string;
+    /**
+     * RESOLVED seat-id STRING (post-promotion), e.g. `"1::codex"` or bare `"1"`.
+     * The numeric seat for `getReviewerPrompt` is the substring before `"::"`.
+     */
+    seatId: string;
+    /** Lowercase agent kind (`"claude" | "gemini" | "codex"`) — chosen from the resolved plan. */
+    agentKind: ReviewerAgentKind;
+    /** snake_case reviewer lens for the seat (e.g. `"correctness"`). */
+    role: ReviewerRole;
+    /** Deterministic dispatch ULID (LOCK #C3F-6). */
+    dispatchUlid: string;
+    /** Attempt number (0-indexed) used as the ULID seed. */
+    attemptNumber: number;
+    /** Producer process-id (no-same-process self-review check, LOCK #C3F-7). */
+    producerProcessId: string;
+    /** Producer session-id (paired with `producerProcessId`). */
+    producerSessionId: string;
+}
+/** One reviewer's REVISE finding inside `ReviseFeedbackPayload.seatFindings`. */
+export interface ReviseSeatFinding {
+    /** Resolved seat-id string (post-promotion if applicable). */
+    seatId: string;
+    /** snake_case reviewer lens. */
+    role: ReviewerRole;
+    /** Free-form findings narrative. */
+    findings: string;
+}
+/**
+ * CP-1.f §3.C.23 — `REVISE_FEEDBACK` Class B payload (engine → desktop). The
+ * desktop re-runs the implementor for round N+1 with the aggregated findings,
+ * then `submitImplementorOutput(nextGateId, nextRound)`. Pinned to
+ * `class_b_envelope.rs::ReviseFeedbackPayload`.
+ */
+export interface ReviseFeedbackPayload {
+    /** The OLD (parent) gate id that produced the REVISE. */
+    gateId: string;
+    /** Per-seat REVISE findings (ordered by ascending seat_id). */
+    seatFindings: ReviseSeatFinding[];
+    /** Round number (0-indexed) the REVISE landed at. */
+    roundNumber: number;
+    /** The DETERMINISTIC round-N+1 gate id the desktop targets with `submitImplementorOutput`. */
+    nextGateId: string;
+    /** The round number of the next round (`roundNumber + 1`). */
+    nextRound: number;
+    /** DETERMINISTIC dedup key keyed `(parentGateId, nextGateId, nextRound)` — the double-spawn guard. */
+    reviseFeedbackId: string;
+}
 export type ClassBInbound = {
     kind: 'PlannerDecisionApproved';
     signedEnvelope: SignedEnvelope;
@@ -105,6 +301,26 @@ export type ClassBInbound = {
     kind: 'PolicyRejection';
     signedEnvelope: SignedEnvelope;
     payload: unknown;
+} | {
+    kind: 'TrackAssigned';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'MergeGateDispatch';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'TaskGroupHalted';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'ReviewerDispatch';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
+} | {
+    kind: 'ReviseFeedback';
+    signedEnvelope: SignedEnvelope;
+    payload: unknown;
 };
 export type ExecutorError = {
     kind: 'AuthorityRefusal';
@@ -170,11 +386,29 @@ export interface LocalExecutor {
     ingestHookEvent(event: HookEvent): Promise<void>;
     /** Read-only view of the current TASK_AUTHORIZED.authorityScope. */
     authorityScope(): Readonly<AuthorityScope>;
-    /** CP-1.c STUB; CP-1.e wires real AppSync subscription + signature verification. */
-    consumeClassB(packet: ClassBInbound): Promise<void>;
+    /**
+     * CP-1.c STUB; CP-1.e wires real AppSync subscription + signature verification.
+     * `envelopeTaskId` (Audited-path fix B) — the outer Class B envelope's taskId,
+     * forwarded so a PolicyRejection (payload carries no taskId) discards exactly
+     * the rejected task's shadow. Optional for non-WS callers / tests.
+     */
+    consumeClassB(packet: ClassBInbound, envelopeTaskId?: string): Promise<void>;
+    /**
+     * CP-12 W4 (#593) — team-dispatch recovery. Re-launch a track whose round-0
+     * `TrackAssigned` was dropped by the emit-before-subscribe race (the engine
+     * emits the per-track dispatch ~0.5s before the desktop's Class B subscription
+     * is established → live AppSync does not replay it). Exposes the private
+     * `launchTrack` body (register + brief bridge) and returns the explicit result
+     * the QuorumLoop `recoverTeamTracks` discriminates (`duplicate` returned BEFORE
+     * the bridge → recovery repairs the brief; `rejected` did not launch → skip).
+     * The single-track LE / non-team path never calls this (recovery is gated on a
+     * team session). Optional on the interface for non-team `LocalExecutor`
+     * implementations / tests.
+     */
+    recoverLaunchTrack?(payload: TrackAssignedPayload): Promise<'registered' | 'duplicate' | 'rejected'>;
 }
 export interface SpawnedProcess {
-    child: ChildProcess;
+    child: ChildProcess | SubstrateProc;
     pid: number;
     role: ProcessRole;
     agentKind: AgentKind | undefined;

package/dist/local-executor/wb2-review-bundle.d.ts

@@ -0,0 +1,59 @@
+/**
+ * §2.6 — a single conflicted path rendered to concrete 3-way CONTENT for the
+ * reviewer prompt. Each side is either decoded text, a per-side snippet (head+tail
+ * with a truncation marker), or a placeholder line (`[absent…]`/`[binary…]`/
+ * `[non-UTF-8…]`). Additive — absent ⇒ today's bare base→tip diff.
+ */
+export interface RenderedConflict {
+    path: string;
+    /** Rendered content OR a placeholder. base = the merge-base side. */
+    base: string;
+    /** integration-tip side (`ours`). */
+    ours: string;
+    /** incoming-track side (`theirs`). */
+    theirs: string;
+}
+/** §2.6 — one track's intent diff (base → trackTip), already byte-bounded. */
+export interface TrackIntentDiff {
+    trackIndex: number;
+    implementorAgent?: string;
+    /** unified base→trackTip diff (byte-bounded by `readDiffHermetic`). */
+    diff: string;
+}
+/** §2.6 — the rendered intent bundle handed to the dispatcher (additive callback fields). */
+export interface RenderedTier2Bundle {
+    conflictBundle: readonly RenderedConflict[];
+    trackIntentDiffs: readonly TrackIntentDiff[];
+}
+/** §2.6 (locked) byte budgets. The aggregate ceiling must clear the 512 KiB diff with headroom. */
+export declare const WAVE_B_TIER2_MAX_BUNDLE_BYTES: number;
+export declare const WB2_BUNDLE_PER_SIDE_MAX_BYTES: number;
+export declare const WB2_INTENT_DIFF_MAX_BYTES: number;
+/**
+ * Render ONE side of a conflict (already-fetched bytes) to prompt-safe text under
+ * the per-side cap. NEVER emits raw bytes for a binary / non-UTF-8 / absent side —
+ * a placeholder line instead (Q-BINARY locked). A side over the per-side cap is
+ * snippet-trimmed head+tail with an explicit `[…truncated N bytes…]` marker
+ * (Q-OVERFLOW locked — the ONLY truncate-with-marker affordance).
+ *
+ * @param bytes the side's raw blob bytes, or `null` when the path is absent on this side.
+ * @param oid   the side's blob OID (for the binary/non-UTF-8 placeholder), if known.
+ */
+export declare function renderConflictSide(bytes: Buffer | null, oid: string | undefined, perSideMaxBytes?: number): string;
+/**
+ * Render the §2.6 bundle into prompt sections, appended AFTER the base→tip diff
+ * block. Returns `''` when the bundle is empty/absent (graceful degrade → today's
+ * behavior). Pure string assembly — no overflow decision here (the dispatcher owns
+ * the aggregate-ceiling fail-closed check, see {@link bundleSectionsOverBudget}).
+ */
+export declare function renderTier2BundleSections(bundle: {
+    conflictBundle?: readonly RenderedConflict[];
+    trackIntentDiffs?: readonly TrackIntentDiff[];
+}): string;
+/**
+ * The LOCK fail-closed aggregate check: TRUE iff the rendered diff + bundle sections
+ * exceed the aggregate ceiling. The dispatcher fails closed (NO-PROMOTE) when true —
+ * the per-side snippet trim keeps individual sides under the per-side cap, but the
+ * AGGREGATE never silently drops a whole conflict or intent diff to fit (§2.6 line 108).
+ */
+export declare function bundleSectionsOverBudget(diff: string, bundleSections: string, maxBundleBytes?: number): boolean;

package/dist/local-executor/workspace-shadow.d.ts

@@ -0,0 +1,290 @@
+import type { PromoteManifestInput } from './durable-store';
+/** Default TTL after which an orphaned shadow is GC-eligible (#GC-1). */
+export declare const DEFAULT_SHADOW_TTL_MS: number;
+/** `change_kind` values mirroring the pinned engine `ExecuteFirstFile` contract. */
+export type ShadowChangeKind = 'created' | 'modified' | 'deleted';
+/** One captured changed file in the shadow-vs-real diff (§D3). */
+export interface ShadowDiffFile {
+    /** Path RELATIVE to the workspace root (matches the engine contract). */
+    path: string;
+    change_kind: ShadowChangeKind;
+    /** The captured content (created/modified) or empty for deleted. */
+    content: string;
+}
+/** Persisted promote-state marker (#PR-4). */
+type ShadowPromoteState = 'pending' | 'promoted';
+/** Injected for deterministic tests; production uses the real fs/git. */
+export interface ShadowEnv {
+    /** Sleep between git-op retries. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Override the per-task state dir root (default `~/.codevibe/shadow-state`). */
+    stateRootDir?: string;
+    /** Override the shadow temp-dir root (default `os.tmpdir()`). */
+    shadowRootDir?: string;
+    /** TTL for the GC reaper. */
+    ttlMs?: number;
+    /** Hook to terminate task-spawned children rooted in the shadow before teardown. */
+    killChildrenInShadow?: (shadowDir: string) => Promise<void>;
+}
+/**
+ * CP-14 Wave A (`team.execution=worktree_merge`) — make the shadow worktree a
+ * PERSISTENT track branch instead of a detached HEAD, so the merge-train can
+ * merge the track's committed tip. `baseSha` is the ONE group base pinned BEFORE
+ * the first track shadow is created (so every track roots at the same base — a
+ * deterministic merge-train input). Git-only: a non-git workspace is ineligible.
+ */
+export interface TrackBranchSpec {
+    /** The persistent branch name, e.g. `codevibe/track/<groupId>/<trackIndex>`. */
+    name: string;
+    /** The pinned group base commit the branch is created at. */
+    baseSha: string;
+}
+/**
+ * The desktop's per-task shadow workspace. ONE instance per active task; the
+ * QuorumLoop creates it before the round-0 spawn, points the implementor cwd at
+ * `shadowDir`, captures the diff after the implementor exits, and the class-B
+ * consumer promotes (TaskAuthorized) or discards (every other terminal).
+ */
+export declare class WorkspaceShadow {
+    readonly taskId: string;
+    /** The real workspace root (canonical). */
+    readonly workingDir: string;
+    /** The shadow dir the implementor spawns in (its cwd). */
+    readonly shadowDir: string;
+    /** True when the shadow is a `git worktree` (vs a non-git file copy). */
+    readonly isGit: boolean;
+    /**
+     * CP-14 Wave A — the persistent track branch this shadow worktree sits on
+     * (`worktree_merge` only); undefined on the legacy detached-HEAD path. When
+     * set, the seam commits to this branch (see {@link commitTrack}) instead of
+     * the in-place promote.
+     */
+    readonly trackBranch?: string;
+    /** Paths (RELATIVE to workingDir) materialized into the shadow — the TRACKED SET. */
+    private trackedSet;
+    /** Pre-task content hash per tracked path (null = absent at create), #PR-2. */
+    private preTaskHashes;
+    /** The per-task durable state dir (under the app-data dir), survives restarts. */
+    private readonly stateDir;
+    private readonly env;
+    private readonly sleep;
+    private constructor();
+    /** @internal — test introspection of the tracked set. */
+    get trackedSetForTests(): ReadonlySet<string>;
+    /**
+     * Create the shadow BEFORE the round-0 spawn + record the TRACKED SET.
+     *
+     * - git repo → `git worktree add` (PRIMARY: cheap, shared object store, real
+     *   `.git` so the agent's own `npm test`/`git diff` work).
+     * - non-git → file-copy of `workingDir` excluding `.git`/secrets/gitignored
+     *   + symlink the real `node_modules` (read-through, never a promote target).
+     *
+     * Fail-closed (#SR-2): a create failure throws — the caller surfaces it and
+     * does NOT spawn against a half-built shadow.
+     */
+    static create(taskId: string, workingDir: string, env?: ShadowEnv, opts?: {
+        trackBranch?: TrackBranchSpec;
+    }): Promise<WorkspaceShadow>;
+    /**
+     * Capture the shadow-vs-real diff AFTER `await handle.done`, bounded STRICTLY
+     * to the tracked set (#PM-2 / agy H2):
+     *   - created  — in shadow, NOT in the tracked baseline.
+     *   - modified — tracked path whose shadow content differs from the baseline.
+     *   - deleted  — was in the tracked baseline AND the agent removed it from the
+     *                shadow (NOT merely "absent from shadow", which would falsely
+     *                flag every excluded path → catastrophic-delete).
+     *
+     * git → `git diff` (already tracked-scoped); non-git → tree-compare bounded to
+     * the tracked set. Across revise rounds the diff is CUMULATIVE shadow-vs-real.
+     */
+    captureDiff(): Promise<ShadowDiffFile[]>;
+    private captureGitDiff;
+    private captureCopyDiff;
+    /**
+     * CP-14 Wave A (`worktree_merge`) — commit the shadow worktree's full content
+     * (the dirty-replay baseline + the implementor's edits + any new untracked
+     * files) onto the persistent track branch, and return the committed tip SHA
+     * (the merge-train input). This REPLACES the legacy in-place {@link promote}
+     * for track shadows: the user tree is NOT touched here — the change lands only
+     * when the merge gate promotes the integration tip.
+     *
+     * Deterministic for recovery-replay stability: pinned bot identity + a pinned
+     * `@0` author/committer date + hooks/gpg disabled, so a re-run over identical
+     * content yields an identical SHA. `--allow-empty` so a no-op track still
+     * produces a real base-rooted tip (no `#EF-1`-style born-halt; the merge-train
+     * fast-forwards it).
+     *
+     * Requires a git track-branch shadow (created with `opts.trackBranch`); throws
+     * otherwise — a missing tip must FAIL CLOSED upstream, never be silently empty.
+     *
+     * REVIEW-INTEGRITY (#598-11 parity, Stage-1 HIGH): the commit is built from the
+     * REVIEWED, drift-checked `diff` content (the in-memory `ShadowDiffFile[]` the
+     * caller already validated against the reviewed snapshot) via a THROWAWAY index
+     * + `git hash-object`/`commit-tree` — the live worktree is NEVER re-read. This
+     * matches the legacy `promote(diff)`, which applies the captured `diff[].content`
+     * (not a re-read), so a detached writer that mutates the worktree after the
+     * drift-check cannot inject UNREVIEWED bytes into the track tip. The branch sits
+     * at the pinned base (its only commit-to-be) and the diff is "everything vs
+     * base", so `read-tree base` + apply-diff reconstructs exactly the reviewed tree.
+     */
+    commitTrack(diff: readonly ShadowDiffFile[], opts?: {
+        message?: string;
+    }): Promise<string>;
+    /**
+     * Materialize the changed-file SET over the TRACKED SET ONLY (#PM-1/#PM-2):
+     * copy the shadow's changed files onto the real tree (create/overwrite) +
+     * delete the real files that were in the tracked baseline AND the agent
+     * removed. NEVER touches a real-tree path outside the tracked set.
+     *
+     * Idempotent (#PR-4): a `promoted` marker short-circuits — a packet +
+     * recovery double-fire is a safe no-op.
+     *
+     * Per-file TOCTOU guard (#PR-2): before overwrite/delete, the real file's
+     * current hash is compared to the pre-task hash (null = absent). A mismatch
+     * (concurrent edit/create/delete) is ESCALATED via the returned conflicts —
+     * never blind-clobbered.
+     *
+     * Fail-closed (#SR-2): on any conflict OR fs error the caller surfaces
+     * "could not promote — N files at <paths>". Returns the conflicts/errors so
+     * the caller renders them; throws only on a marker-write failure.
+     */
+    promote(diff: ShadowDiffFile[], opts?: {
+        /**
+         * PHASE-589/469 W3.1 (C1) — capture a durable revert manifest for a TEAM
+         * track. For each in-scope, hash-matched file the promote is about to
+         * apply, read its PRE-IMAGE content + hash BEFORE the tree mutates and
+         * emit a {@link PromoteManifestInput} entry. `trackIndex` / the starting
+         * `promoteOrder` are caller-supplied (the group-wide monotonic order); the
+         * captured entries carry `promoteOrder = base + i` in capture order.
+         * Single-impl promotes pass no opts → byte-identical to the legacy path.
+         *
+         * `persist` (REQUIRED when `captureManifest` is set) is awaited with the
+         * captured entries BEFORE the FIRST file is mutated (LOCK #589-I: the
+         * manifest is durable before the tree changes, so a mid-promote crash
+         * still leaves a recoverable undo record). The entries are captured in a
+         * read-only PRE-PASS (no mutation), persisted, THEN applied.
+         */
+        captureManifest?: {
+            trackIndex: number;
+            promoteOrderBase: number;
+            persist: (entries: PromoteManifestInput[]) => Promise<void>;
+        };
+    }): Promise<{
+        /**
+         * Whether this call actually MATERIALIZED files onto the real tree. `false`
+         * means it was an idempotent no-op (a prior promote already landed via the
+         * durable `promoted` marker — a packet + recovery double-fire). The caller
+         * uses this to suppress duplicate `promoting`/`promoted` progress + the
+         * "Applied N files" milestone on a re-delivered TaskAuthorized packet.
+         */
+        materialized: boolean;
+        promoted: string[];
+        conflicts: string[];
+        errors: Array<{
+            path: string;
+            error: string;
+        }>;
+        /**
+         * PHASE-589/469 W3.1 (C1) — the captured pre-image manifest entries (only
+         * populated when `opts.captureManifest` was passed). The caller persists
+         * these via `RevertManifestStore.appendPromote` BEFORE relying on the
+         * applied tree (the capture itself already ran before the mutation). One
+         * entry per file that the promote actually applied.
+         */
+        manifestEntries: PromoteManifestInput[];
+    }>;
+    /**
+     * Tear down the shadow on every non-`TaskAuthorized` terminal (reject/abort,
+     * each Halted reason, parser-empty, session-end, crash). Leaves the real tree
+     * byte-identical to its pre-task state (a discard never touched it).
+     *
+     * git-worktree → `git worktree remove --force` (+ `git worktree prune`),
+     * NEVER raw `rm -rf` (leaks `.git/worktrees/`, #GC-2). Non-git copy → `rm -rf`
+     * (the symlinked `node_modules` is unlinked, never follow-delete).
+     *
+     * Before teardown, terminate task-spawned children rooted in the shadow; if
+     * removal still fails (stray watcher), the durable marker is left in place so
+     * the next-startup GC retries (#GC-2 lazy cleanup).
+     *
+     * `preserveStateDir` (the ORPHAN-teardown mode, restart-race fix 2026-06-11):
+     * tear down ONLY this instance's uuid-suffixed `shadowDir` and NEVER the
+     * per-task SHARED `stateDir`. A restart reuses the SAME taskId, so a fresh
+     * shadow B's durable `pending` marker lives in the same `stateDir`; tearing
+     * down the orphaned old instance A with a full `discard()` would `fs.rm` that
+     * SHARED dir and delete B's authorized-but-pending #PR-4 marker (B becomes
+     * unrecoverable after a crash — a sealed-LOCK violation). The orphan branch in
+     * QuorumLoop.discardShadow passes `{ preserveStateDir: true }` because the
+     * shared `stateDir` belongs to the LIVE mapped shadow B, not the orphan.
+     */
+    discard(opts?: {
+        preserveStateDir?: boolean;
+    }): Promise<void>;
+    /**
+     * Orphan-teardown shorthand (restart-race fix 2026-06-11): tear down ONLY this
+     * instance's `shadowDir` (worktree-aware per #GC-2) and PRESERVE the SHARED
+     * per-task `stateDir` — used by `QuorumLoop.discardShadow`'s instance-mismatch
+     * branch when a newer shadow (same taskId) has replaced this one in the map.
+     */
+    discardOrphan(): Promise<void>;
+    private removeGitWorktree;
+    private writeStateMarker;
+    private readStateMarker;
+    /**
+     * Read the durable promote-state marker WITHOUT mutating the tree (#PR-4). The
+     * QuorumLoop checks this BEFORE `captureDiff` so a re-delivered TaskAuthorized
+     * packet (the promote already landed) short-circuits to a silent no-op without
+     * a wasteful diff re-capture + without re-emitting the `promoting`/`promoted`
+     * progress + the "Applied N files" milestone. `null` = no marker (a fresh /
+     * torn-down shadow) → caller treats it as not-yet-promoted (the promote()
+     * idempotency guard is still the authority).
+     */
+    readPromoteState(): Promise<ShadowPromoteState | null>;
+    /**
+     * Reconstruct a `WorkspaceShadow` from a durable marker (a crash lost the
+     * in-memory tracked set + pre-task hashes). The tracked set is re-derived
+     * from the live shadow + real tree; promote then re-captures the diff. Used
+     * ONLY by the recovery/GC paths (`reopenShadow` / `reapOrphanShadows`).
+     */
+    static fromRecovered(recovered: RecoveredShadow, env?: ShadowEnv): Promise<WorkspaceShadow>;
+}
+/** A recovered shadow state (read from the durable per-task marker). */
+export interface RecoveredShadow {
+    taskId: string;
+    shadowDir: string;
+    workingDir: string;
+    isGit: boolean;
+    promoteState: ShadowPromoteState;
+    createdAtMs: number;
+    /** The durable state dir for this task (for cleanup). */
+    stateDir: string;
+}
+/**
+ * Read every durable per-task shadow marker under the state root. The reconnect/
+ * startup recovery (#PR-4) reads these to find an authorized-but-pending shadow
+ * to promote; the GC reaper (#GC-1) reads them to delete orphaned shadows.
+ */
+export declare function listRecoverableShadows(env?: ShadowEnv): Promise<RecoveredShadow[]>;
+/**
+ * Reconstruct a `WorkspaceShadow` from a durable marker so the recovery path
+ * can re-run promote/discard against an already-created shadow. The tracked set
+ * + pre-task hashes are re-derived from the live shadow vs the real tree (a
+ * crash lost the in-memory state). For a git worktree this is `git status`; for
+ * a copy shadow it is a tree-compare. The promote then re-captures the diff.
+ */
+export declare function reopenShadow(recovered: RecoveredShadow, env?: ShadowEnv): Promise<WorkspaceShadow | null>;
+/**
+ * GC orphaned shadows (#GC-1): on session-start/WS-resync, discard any shadow
+ * whose task is NOT in `activeTaskIds` AND whose promote-state is NOT `promoted`
+ * pending an authorized-but-not-yet-promoted recovery, PLUS a TTL on shadow age.
+ * NEVER deletes an authorized-but-pending shadow (that is the recovery path's job).
+ *
+ * `keepTaskIds` are the tasks the desktop still considers active/recoverable
+ * (the caller passes the active task id + any authorized-but-pending tasks it
+ * intends to recover). A `promoted` shadow whose code already landed is GC'd
+ * (its real tree is done) regardless of TTL.
+ */
+export declare function reapOrphanShadows(keepTaskIds: ReadonlySet<string>, env?: ShadowEnv): Promise<{
+    reaped: string[];
+    retained: string[];
+}>;
+export {};