@quantiya/codevibe-core 2.0.0 → 2.0.2

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 {};