@paraharness/git 0.0.0-stage → 0.1.0

package/dist/executors/git-cow-worktree-scope.d.ts

@@ -0,0 +1,201 @@
+import type { BranchableScope, GitCowWorktreeNode, GitScopeReceipt, GitSyncReceipt, GitWorktreeHandle, LeaseDelta, ReconcileResult, ToolEffect } from '@paraharness/core';
+/**
+ * Tier-3 branchable Copy-on-Write Git worktree isolation scope driver (`git.cowWorktree`).
+ *
+ * Implements disjoint root/fork worktrees, git-index checkpoints, post-flight `.git` integrity diffing,
+ * automatic parent dirty-tree flushing, and stateless `git merge-tree --write-tree` 3-way reconciliation.
+ */
+export declare class GitCowWorktreeScopeDriver implements BranchableScope<GitWorktreeHandle, GitScopeReceipt, GitSyncReceipt> {
+    /** Unique identifier of this isolation scope driver instance. */
+    readonly id: string;
+    /** Zod schema validating inspection receipts returned by `inspect()`. */
+    readonly receiptSchema: import("zod").ZodObject<{
+        headRef: import("zod").ZodString;
+        baseRef: import("zod").ZodString;
+        branchName: import("zod").ZodOptional<import("zod").ZodString>;
+        baseBranch: import("zod").ZodDefault<import("zod").ZodString>;
+        diffStat: import("zod").ZodString;
+        mutatedFiles: import("zod").ZodReadonly<import("zod").ZodArray<import("zod").ZodString>>;
+    }, import("zod/v4/core").$strip>;
+    /** Zod schema validating synchronization receipts returned by `syncChild()` and `syncRoot()`. */
+    readonly syncSchema: import("zod").ZodObject<{
+        rebasedOntoRef: import("zod").ZodString;
+        baseBranch: import("zod").ZodDefault<import("zod").ZodString>;
+        updatedFiles: import("zod").ZodReadonly<import("zod").ZodArray<import("zod").ZodString>>;
+    }, import("zod/v4/core").$strip>;
+    /** Capability flag confirming git-index checkpoint serialization and rollback support. */
+    readonly supportsCheckpoints: true;
+    /** Capability flag confirming Copy-on-Write child worktree branching and 3-way reconciliation support. */
+    readonly supportsBranching: true;
+    /** Passive AST configuration node for this worktree scope. */
+    private readonly node;
+    /** Precomputed union of `node.excludeFromCloneGlobs` and `node.checkpointPolicy?.excludeGlobs`. */
+    private readonly effectiveExcludeGlobs;
+    /** Precomputed checkpoint policy with merged `effectiveExcludeGlobs`. */
+    private readonly effectiveCheckpointPolicy;
+    /** Per-parent worktree `PQueue` (`concurrency: 1`) serializing automatic parent dirty-tree flushes during `forkChild`. */
+    private readonly parentFlushQueues;
+    /**
+     * Initializes a `GitCowWorktreeScopeDriver` from its passive `GitCowWorktreeNode` AST configuration.
+     *
+     * Binds the repository path, disjoint worktree directory layout, and checkpoint policy configuration.
+     *
+     * @param {GitCowWorktreeNode} node - Passive worktree scope AST configuration node.
+     */
+    constructor(node: GitCowWorktreeNode);
+    /**
+     * Provisions an isolated Task Root Worktree at `<dir>/roots/<runId>` for `runId`.
+     *
+     * Hydrates `node_modules` according to `.lockfileGate` and `.setup` and initializes `<gitdir>/harness-meta.json`.
+     *
+     * @param {string} runId - Unique identifier of the flow run.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Newly acquired root worktree handle.
+     */
+    acquireRoot(runId: string): Promise<GitWorktreeHandle>;
+    /**
+     * Rebinds an existing Task Root Worktree at `<dir>/roots/<runId>` during crash recovery.
+     *
+     * Completes interrupted `pendingParentHeadSha` or `inFlightMerge` state and rolls back `inFlightCommitAndPush`.
+     *
+     * @param {string} runId        - Unique identifier of the recovering flow run.
+     * @param {string} [checkpoint] - Optional serialized checkpoint fallback when the worktree directory is missing.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Reattached root worktree handle.
+     */
+    reattachRoot(runId: string, checkpoint?: string): Promise<GitWorktreeHandle>;
+    /**
+     * Captures a non-mutating `GitScopeReceipt` for `handle` using a temporary `GIT_INDEX_FILE`.
+     *
+     * Pins `refs/harness/candidates/<run-id>/<branch-index>` when inspecting a speculative branch handle.
+     *
+     * @param {GitWorktreeHandle} handle - Active worktree handle to inspect.
+     *
+     * @returns {Promise<GitScopeReceipt>} Validated `GitScopeReceipt` without mutating live `HEAD` or `.git/index`.
+     */
+    inspect(handle: GitWorktreeHandle): Promise<GitScopeReceipt>;
+    /**
+     * Pins the final commit SHA under `refs/harness/completed/...` and removes the worktree directory.
+     *
+     * Prunes `<gitdir>/harness-ckpt-blobs/` and `<gitdir>/harness-ckpt-nm/` before `git worktree remove --force`.
+     *
+     * @param {GitWorktreeHandle} handle - Ephemeral root or child worktree handle to release.
+     *
+     * @returns {Promise<void>} Resolves once the completed ref is pinned and the worktree is removed.
+     */
+    release(handle: GitWorktreeHandle): Promise<void>;
+    /**
+     * Captures the uncommitted working-tree and worktree-local `.git` state of `handle` into a JSON checkpoint token.
+     *
+     * Uses `git status --porcelain=v2 -z --no-renames --untracked-files=all` and a temporary `GIT_INDEX_FILE`.
+     *
+     * @param {GitWorktreeHandle} handle - Active worktree handle to snapshot.
+     *
+     * @returns {Promise<string>} Serialized JSON `GitCheckpointPayload` string.
+     */
+    serializeCheckpoint(handle: GitWorktreeHandle): Promise<string>;
+    /**
+     * Restores `handle` to the exact state captured by `checkpoint` using the 4-step restoration protocol.
+     *
+     * Restores `.git` metadata and `.gitignore` rules, unlinks symmetric-diff extras, checks out `treeSha`, and copies back oversized blobs.
+     *
+     * @param {GitWorktreeHandle} handle     - Active worktree handle to roll back.
+     * @param {string}            checkpoint - Serialized JSON checkpoint payload.
+     *
+     * @returns {Promise<void>} Resolves once `handle` matches `checkpoint`.
+     */
+    restoreCheckpoint(handle: GitWorktreeHandle, checkpoint: string): Promise<void>;
+    /**
+     * Verifies worktree-local `.git` and `node_modules` integrity and diffs `handle` against `fromCheckpoint`.
+     *
+     * Restores `fromCheckpoint` and throws immediately if `.git` metadata or `node_modules` was tampered with.
+     *
+     * @param {string}            fromCheckpoint - Pre-tool serialized checkpoint payload.
+     * @param {GitWorktreeHandle} handle         - Worktree handle after subprocess tool execution.
+     *
+     * @returns {Promise<readonly ToolEffect[]>} Synthesized `FsToolEffect` list for modified paths.
+     */
+    diffEffects(fromCheckpoint: string, handle: GitWorktreeHandle): Promise<readonly ToolEffect[]>;
+    /**
+     * Returns or creates the serialized `PQueue` (`concurrency: 1`) for `parentWorktreePath`.
+     *
+     * @param {string} parentWorktreePath - Absolute path of the parent worktree.
+     *
+     * @returns {PQueue} Serialized parent flush queue for `parentWorktreePath`.
+     */
+    private getOrCreateParentFlushQueue;
+    /**
+     * Removes `activeQueue` from `parentFlushQueues` once no tasks remain queued or running.
+     *
+     * @param {string} parentWorktreePath - Absolute path of the parent worktree.
+     * @param {PQueue} activeQueue        - Queue instance that just completed a task.
+     */
+    private pruneIdleParentFlushQueue;
+    /**
+     * Flushes clean dirty files on `parent` under a per-parent async mutex and forks `<dir>/forks/<runId>/<forkId>`.
+     *
+     * Copies any remaining `unresolvedConflictPaths` from `parent` into the newly forked child worktree.
+     *
+     * @param {GitWorktreeHandle} parent - Parent worktree handle to clone from.
+     * @param {string}            forkId - Unique child fork or speculative branch identifier.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Newly provisioned child worktree handle.
+     */
+    forkChild(parent: GitWorktreeHandle, forkId: string): Promise<GitWorktreeHandle>;
+    /**
+     * Rebinds an existing child fork worktree at `<dir>/forks/<runId>/<forkId>` during crash recovery.
+     *
+     * Completes any interrupted `inFlightMerge` state and preserves uncommitted child edits across reboots.
+     *
+     * @param {GitWorktreeHandle} parent       - Reattached parent worktree handle.
+     * @param {string}            forkId       - Unique child fork identifier.
+     * @param {string}            [checkpoint] - Optional serialized checkpoint fallback when the directory is missing.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Reattached child worktree handle.
+     */
+    reattachChild(parent: GitWorktreeHandle, forkId: string, checkpoint?: string): Promise<GitWorktreeHandle>;
+    /**
+     * Reconciles `child` into `parent` via stateless `git merge-tree --write-tree` over shared parent $C_0$.
+     *
+     * Leaves `parent` untouched on conflict and materializes conflicted blobs into `child` with `unresolvedConflictPaths`.
+     *
+     * @param {GitWorktreeHandle} child  - Completed child worktree handle.
+     * @param {GitWorktreeHandle} parent - Target parent worktree handle.
+     *
+     * @returns {Promise<ReconcileResult<GitScopeReceipt>>} Clean or conflicted reconciliation result.
+     */
+    commitChild(child: GitWorktreeHandle, parent: GitWorktreeHandle): Promise<ReconcileResult<GitScopeReceipt>>;
+    /**
+     * Rebases/merges uncommitted changes in `pausedChild` onto an updated `parent` worktree handle.
+     *
+     * Materializes the merged tree into `pausedChild` and updates `pausedChild.baseRef` to `parent.HEAD`.
+     *
+     * @param {GitWorktreeHandle} parent      - Updated parent worktree handle.
+     * @param {GitWorktreeHandle} pausedChild - Suspended child worktree handle being resumed.
+     *
+     * @returns {Promise<ReconcileResult<GitSyncReceipt>>} Clean or conflicted synchronization result.
+     */
+    syncChild(parent: GitWorktreeHandle, pausedChild: GitWorktreeHandle): Promise<ReconcileResult<GitSyncReceipt>>;
+    /**
+     * Synchronizes `rootHandle` onto the terminal commit of completed prerequisite runs.
+     *
+     * Updates `rootHandle.baseBranch` when prerequisite branches remain unmerged on `origin/main`.
+     *
+     * @param {GitWorktreeHandle}          rootHandle           - Task root worktree handle.
+     * @param {readonly GitScopeReceipt[]} prerequisiteReceipts - Terminal scope receipts of completed prerequisites.
+     *
+     * @returns {Promise<ReconcileResult<GitSyncReceipt>>} Clean or conflicted synchronization result.
+     */
+    syncRoot(rootHandle: GitWorktreeHandle, prerequisiteReceipts: readonly GitScopeReceipt[]): Promise<ReconcileResult<GitSyncReceipt>>;
+    /**
+     * Returns a temporary write capability lease (`fs:match-globs`) for `handle.unresolvedConflictPaths`.
+     *
+     * Returns `undefined` when `handle.unresolvedConflictPaths` is empty.
+     *
+     * @param {GitWorktreeHandle} handle - Worktree handle containing unresolved conflict paths.
+     *
+     * @returns {LeaseDelta | undefined} Temporary conflict write lease delta, or `undefined` when clean.
+     */
+    getConflictLease(handle: GitWorktreeHandle): LeaseDelta | undefined;
+}
+//# sourceMappingURL=git-cow-worktree-scope.d.ts.map

package/dist/executors/git-cow-worktree-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cow-worktree-scope.d.ts","sourceRoot":"","sources":["../../src/executors/git-cow-worktree-scope.ts"],"names":[],"mappings":"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"}

package/dist/executors/git-cow-worktree-scope.js

@@ -0,0 +1,260 @@
+import PQueue from 'p-queue';
+import { GitScopeReceiptSchema, GitSyncReceiptSchema, } from '../schemas/git-receipts.schema.js';
+import { gitCheckpointDiffEffects } from './internal/git-checkpoint-diff-effects.js';
+import { gitCheckpointRestore } from './internal/git-checkpoint-restore.js';
+import { gitCheckpointSerialize } from './internal/git-checkpoint-serialize.js';
+import { gitWorktreeAcquireRoot } from './internal/git-worktree-acquire-root.js';
+import { gitWorktreeCommitChild, gitWorktreeInspectNonMutating, } from './internal/git-worktree-commit-child.js';
+import { buildConflictLeaseDelta, gitWorktreeFlushCleanParentChanges, } from './internal/git-worktree-flush-and-prune.js';
+import { gitWorktreeForkChild, gitWorktreeReleaseAndPinRef, } from './internal/git-worktree-fork-and-release.js';
+import { gitWorktreeReattachChild, gitWorktreeReattachRoot, resolveEffectiveCheckpointPolicy, } from './internal/git-worktree-reattach.js';
+import { gitWorktreeSyncChild, gitWorktreeSyncRoot, } from './internal/git-worktree-sync-child-and-root.js';
+/**
+ * Tier-3 branchable Copy-on-Write Git worktree isolation scope driver (`git.cowWorktree`).
+ *
+ * Implements disjoint root/fork worktrees, git-index checkpoints, post-flight `.git` integrity diffing,
+ * automatic parent dirty-tree flushing, and stateless `git merge-tree --write-tree` 3-way reconciliation.
+ */
+export class GitCowWorktreeScopeDriver {
+    /** Unique identifier of this isolation scope driver instance. */
+    id;
+    /** Zod schema validating inspection receipts returned by `inspect()`. */
+    receiptSchema = GitScopeReceiptSchema;
+    /** Zod schema validating synchronization receipts returned by `syncChild()` and `syncRoot()`. */
+    syncSchema = GitSyncReceiptSchema;
+    /** Capability flag confirming git-index checkpoint serialization and rollback support. */
+    supportsCheckpoints = true;
+    /** Capability flag confirming Copy-on-Write child worktree branching and 3-way reconciliation support. */
+    supportsBranching = true;
+    /** Passive AST configuration node for this worktree scope. */
+    node;
+    /** Precomputed union of `node.excludeFromCloneGlobs` and `node.checkpointPolicy?.excludeGlobs`. */
+    effectiveExcludeGlobs;
+    /** Precomputed checkpoint policy with merged `effectiveExcludeGlobs`. */
+    effectiveCheckpointPolicy;
+    /** Per-parent worktree `PQueue` (`concurrency: 1`) serializing automatic parent dirty-tree flushes during `forkChild`. */
+    parentFlushQueues = new Map();
+    /**
+     * Initializes a `GitCowWorktreeScopeDriver` from its passive `GitCowWorktreeNode` AST configuration.
+     *
+     * Binds the repository path, disjoint worktree directory layout, and checkpoint policy configuration.
+     *
+     * @param {GitCowWorktreeNode} node - Passive worktree scope AST configuration node.
+     */
+    constructor(node) {
+        this.id = node.id;
+        this.node = node;
+        this.effectiveCheckpointPolicy = resolveEffectiveCheckpointPolicy(node);
+        this.effectiveExcludeGlobs = this.effectiveCheckpointPolicy?.excludeGlobs;
+    }
+    /**
+     * Provisions an isolated Task Root Worktree at `<dir>/roots/<runId>` for `runId`.
+     *
+     * Hydrates `node_modules` according to `.lockfileGate` and `.setup` and initializes `<gitdir>/harness-meta.json`.
+     *
+     * @param {string} runId - Unique identifier of the flow run.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Newly acquired root worktree handle.
+     */
+    acquireRoot(runId) {
+        return gitWorktreeAcquireRoot(this.node, runId);
+    }
+    /**
+     * Rebinds an existing Task Root Worktree at `<dir>/roots/<runId>` during crash recovery.
+     *
+     * Completes interrupted `pendingParentHeadSha` or `inFlightMerge` state and rolls back `inFlightCommitAndPush`.
+     *
+     * @param {string} runId        - Unique identifier of the recovering flow run.
+     * @param {string} [checkpoint] - Optional serialized checkpoint fallback when the worktree directory is missing.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Reattached root worktree handle.
+     */
+    reattachRoot(runId, checkpoint) {
+        return gitWorktreeReattachRoot(this.node, runId, checkpoint);
+    }
+    /**
+     * Captures a non-mutating `GitScopeReceipt` for `handle` using a temporary `GIT_INDEX_FILE`.
+     *
+     * Pins `refs/harness/candidates/<run-id>/<branch-index>` when inspecting a speculative branch handle.
+     *
+     * @param {GitWorktreeHandle} handle - Active worktree handle to inspect.
+     *
+     * @returns {Promise<GitScopeReceipt>} Validated `GitScopeReceipt` without mutating live `HEAD` or `.git/index`.
+     */
+    inspect(handle) {
+        return gitWorktreeInspectNonMutating(handle, this.effectiveExcludeGlobs);
+    }
+    /**
+     * Pins the final commit SHA under `refs/harness/completed/...` and removes the worktree directory.
+     *
+     * Prunes `<gitdir>/harness-ckpt-blobs/` and `<gitdir>/harness-ckpt-nm/` before `git worktree remove --force`.
+     *
+     * @param {GitWorktreeHandle} handle - Ephemeral root or child worktree handle to release.
+     *
+     * @returns {Promise<void>} Resolves once the completed ref is pinned and the worktree is removed.
+     */
+    release(handle) {
+        this.parentFlushQueues.delete(handle.worktreePath);
+        return gitWorktreeReleaseAndPinRef(handle, this.effectiveExcludeGlobs);
+    }
+    /**
+     * Captures the uncommitted working-tree and worktree-local `.git` state of `handle` into a JSON checkpoint token.
+     *
+     * Uses `git status --porcelain=v2 -z --no-renames --untracked-files=all` and a temporary `GIT_INDEX_FILE`.
+     *
+     * @param {GitWorktreeHandle} handle - Active worktree handle to snapshot.
+     *
+     * @returns {Promise<string>} Serialized JSON `GitCheckpointPayload` string.
+     */
+    serializeCheckpoint(handle) {
+        return gitCheckpointSerialize(handle, this.effectiveCheckpointPolicy);
+    }
+    /**
+     * Restores `handle` to the exact state captured by `checkpoint` using the 4-step restoration protocol.
+     *
+     * Restores `.git` metadata and `.gitignore` rules, unlinks symmetric-diff extras, checks out `treeSha`, and copies back oversized blobs.
+     *
+     * @param {GitWorktreeHandle} handle     - Active worktree handle to roll back.
+     * @param {string}            checkpoint - Serialized JSON checkpoint payload.
+     *
+     * @returns {Promise<void>} Resolves once `handle` matches `checkpoint`.
+     */
+    restoreCheckpoint(handle, checkpoint) {
+        return gitCheckpointRestore(handle, checkpoint, this.effectiveCheckpointPolicy);
+    }
+    /**
+     * Verifies worktree-local `.git` and `node_modules` integrity and diffs `handle` against `fromCheckpoint`.
+     *
+     * Restores `fromCheckpoint` and throws immediately if `.git` metadata or `node_modules` was tampered with.
+     *
+     * @param {string}            fromCheckpoint - Pre-tool serialized checkpoint payload.
+     * @param {GitWorktreeHandle} handle         - Worktree handle after subprocess tool execution.
+     *
+     * @returns {Promise<readonly ToolEffect[]>} Synthesized `FsToolEffect` list for modified paths.
+     */
+    diffEffects(fromCheckpoint, handle) {
+        return gitCheckpointDiffEffects(fromCheckpoint, handle, this.effectiveCheckpointPolicy);
+    }
+    /**
+     * Returns or creates the serialized `PQueue` (`concurrency: 1`) for `parentWorktreePath`.
+     *
+     * @param {string} parentWorktreePath - Absolute path of the parent worktree.
+     *
+     * @returns {PQueue} Serialized parent flush queue for `parentWorktreePath`.
+     */
+    getOrCreateParentFlushQueue(parentWorktreePath) {
+        const existing = this.parentFlushQueues.get(parentWorktreePath);
+        if (existing !== undefined)
+            return existing;
+        const created = new PQueue({ concurrency: 1 });
+        this.parentFlushQueues.set(parentWorktreePath, created);
+        return created;
+    }
+    /**
+     * Removes `activeQueue` from `parentFlushQueues` once no tasks remain queued or running.
+     *
+     * @param {string} parentWorktreePath - Absolute path of the parent worktree.
+     * @param {PQueue} activeQueue        - Queue instance that just completed a task.
+     */
+    pruneIdleParentFlushQueue(parentWorktreePath, activeQueue) {
+        if (activeQueue.size === 0 &&
+            activeQueue.pending === 0 &&
+            this.parentFlushQueues.get(parentWorktreePath) === activeQueue) {
+            this.parentFlushQueues.delete(parentWorktreePath);
+        }
+    }
+    /**
+     * Flushes clean dirty files on `parent` under a per-parent async mutex and forks `<dir>/forks/<runId>/<forkId>`.
+     *
+     * Copies any remaining `unresolvedConflictPaths` from `parent` into the newly forked child worktree.
+     *
+     * @param {GitWorktreeHandle} parent - Parent worktree handle to clone from.
+     * @param {string}            forkId - Unique child fork or speculative branch identifier.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Newly provisioned child worktree handle.
+     */
+    async forkChild(parent, forkId) {
+        const excludeGlobs = this.effectiveExcludeGlobs;
+        const activeQueue = this.getOrCreateParentFlushQueue(parent.worktreePath);
+        try {
+            await activeQueue.add(async () => {
+                await gitWorktreeFlushCleanParentChanges(parent, excludeGlobs);
+            });
+        }
+        finally {
+            this.pruneIdleParentFlushQueue(parent.worktreePath, activeQueue);
+        }
+        return gitWorktreeForkChild(this.node, parent, forkId);
+    }
+    /**
+     * Rebinds an existing child fork worktree at `<dir>/forks/<runId>/<forkId>` during crash recovery.
+     *
+     * Completes any interrupted `inFlightMerge` state and preserves uncommitted child edits across reboots.
+     *
+     * @param {GitWorktreeHandle} parent       - Reattached parent worktree handle.
+     * @param {string}            forkId       - Unique child fork identifier.
+     * @param {string}            [checkpoint] - Optional serialized checkpoint fallback when the directory is missing.
+     *
+     * @returns {Promise<GitWorktreeHandle>} Reattached child worktree handle.
+     */
+    reattachChild(parent, forkId, checkpoint) {
+        return gitWorktreeReattachChild({
+            node: this.node,
+            parent,
+            forkId,
+            checkpoint,
+        });
+    }
+    /**
+     * Reconciles `child` into `parent` via stateless `git merge-tree --write-tree` over shared parent $C_0$.
+     *
+     * Leaves `parent` untouched on conflict and materializes conflicted blobs into `child` with `unresolvedConflictPaths`.
+     *
+     * @param {GitWorktreeHandle} child  - Completed child worktree handle.
+     * @param {GitWorktreeHandle} parent - Target parent worktree handle.
+     *
+     * @returns {Promise<ReconcileResult<GitScopeReceipt>>} Clean or conflicted reconciliation result.
+     */
+    commitChild(child, parent) {
+        return gitWorktreeCommitChild(child, parent, this.effectiveExcludeGlobs);
+    }
+    /**
+     * Rebases/merges uncommitted changes in `pausedChild` onto an updated `parent` worktree handle.
+     *
+     * Materializes the merged tree into `pausedChild` and updates `pausedChild.baseRef` to `parent.HEAD`.
+     *
+     * @param {GitWorktreeHandle} parent      - Updated parent worktree handle.
+     * @param {GitWorktreeHandle} pausedChild - Suspended child worktree handle being resumed.
+     *
+     * @returns {Promise<ReconcileResult<GitSyncReceipt>>} Clean or conflicted synchronization result.
+     */
+    syncChild(parent, pausedChild) {
+        return gitWorktreeSyncChild(parent, pausedChild, this.effectiveExcludeGlobs);
+    }
+    /**
+     * Synchronizes `rootHandle` onto the terminal commit of completed prerequisite runs.
+     *
+     * Updates `rootHandle.baseBranch` when prerequisite branches remain unmerged on `origin/main`.
+     *
+     * @param {GitWorktreeHandle}          rootHandle           - Task root worktree handle.
+     * @param {readonly GitScopeReceipt[]} prerequisiteReceipts - Terminal scope receipts of completed prerequisites.
+     *
+     * @returns {Promise<ReconcileResult<GitSyncReceipt>>} Clean or conflicted synchronization result.
+     */
+    syncRoot(rootHandle, prerequisiteReceipts) {
+        return gitWorktreeSyncRoot(rootHandle, prerequisiteReceipts, this.effectiveExcludeGlobs);
+    }
+    /**
+     * Returns a temporary write capability lease (`fs:match-globs`) for `handle.unresolvedConflictPaths`.
+     *
+     * Returns `undefined` when `handle.unresolvedConflictPaths` is empty.
+     *
+     * @param {GitWorktreeHandle} handle - Worktree handle containing unresolved conflict paths.
+     *
+     * @returns {LeaseDelta | undefined} Temporary conflict write lease delta, or `undefined` when clean.
+     */
+    getConflictLease(handle) {
+        return buildConflictLeaseDelta(handle);
+    }
+}
+//# sourceMappingURL=git-cow-worktree-scope.js.map

package/dist/executors/git-cow-worktree-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cow-worktree-scope.js","sourceRoot":"","sources":["../../src/executors/git-cow-worktree-scope.ts"],"names":[],"mappings":"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"}

package/dist/executors/git-cross-verifiers-and-tools.d.ts

@@ -0,0 +1,42 @@
+import type { CrossVerifierBranchCandidate, GitCandidateComparisonToolNode, GitPatchEquivalenceNode, GitPublicSurfaceCrossTesterNode, GitRefReaderToolNode, GitWorktreeHandle, StepExecutionContext, ToolDriver } from '@paraharness/core';
+/**
+ * Executes a `GitPublicSurfaceCrossTesterNode` (`git.publicSurfaceCrossTester`) across speculative candidates.
+ *
+ * Collects boundary-only tests from each candidate and transplants them into sibling candidates inside a checkpoint sandbox.
+ *
+ * @param {GitPublicSurfaceCrossTesterNode<unknown>}                       node       - Public-surface cross-tester AST node.
+ * @param {ReadonlyArray<CrossVerifierBranchCandidate<GitWorktreeHandle>>} candidates - Surviving speculative candidate branches.
+ * @param {StepExecutionContext<GitWorktreeHandle>}                        ctx        - Active step execution context.
+ *
+ * @returns {Promise<Readonly<Record<number, unknown>>>} Per-branch cross-testing report indexed by `branchIndex`.
+ */
+export declare function executeGitPublicSurfaceCrossTester(node: GitPublicSurfaceCrossTesterNode<unknown>, candidates: ReadonlyArray<CrossVerifierBranchCandidate<GitWorktreeHandle>>, ctx: StepExecutionContext<GitWorktreeHandle>): Promise<Readonly<Record<number, unknown>>>;
+/**
+ * Executes a `GitPatchEquivalenceNode` (`git.patchEquivalence`) across speculative worktree candidates.
+ *
+ * Computes normalized patch digests relative to `baseRef` and groups equivalent candidate branch indices.
+ *
+ * @param {GitPatchEquivalenceNode<unknown>}                               node       - Patch-equivalence cross-verifier AST node.
+ * @param {ReadonlyArray<CrossVerifierBranchCandidate<GitWorktreeHandle>>} candidates - Surviving speculative candidate branches.
+ * @param {StepExecutionContext<GitWorktreeHandle>}                        _ctx       - Active step execution context.
+ *
+ * @returns {Promise<Readonly<Record<number, unknown>>>} Per-branch patch equivalence report indexed by `branchIndex`.
+ */
+export declare function executeGitPatchEquivalence(node: GitPatchEquivalenceNode<unknown>, candidates: ReadonlyArray<CrossVerifierBranchCandidate<GitWorktreeHandle>>, _ctx: StepExecutionContext<GitWorktreeHandle>): Promise<Readonly<Record<number, unknown>>>;
+/**
+ * Creates the `ToolDriver` handling `GitRefReaderToolNode` (`git:ref-reader-tool`) invocations.
+ *
+ * Declares zero scope effects (`describeEffects: () => []`) and dispatches `readRefFile`, `diffRefs`, and `listRefFiles`.
+ *
+ * @returns {ToolDriver<GitRefReaderToolNode<GitWorktreeHandle>, GitWorktreeHandle>} Stateless ref-reader tool driver.
+ */
+export declare function createGitRefReaderToolDrivers(): ToolDriver<GitRefReaderToolNode<GitWorktreeHandle>, GitWorktreeHandle>;
+/**
+ * Creates the `ToolDriver` handling `GitCandidateComparisonToolNode` (`git:candidate-comparison-tool`) invocations.
+ *
+ * Declares zero scope effects (`describeEffects: () => []`) and dispatches `diffCandidates`, `readCandidateFile`, and `evalInCandidates`.
+ *
+ * @returns {ToolDriver<GitCandidateComparisonToolNode<GitWorktreeHandle>, GitWorktreeHandle>} Stateless candidate comparison tool driver.
+ */
+export declare function createGitCandidateComparisonToolDrivers(): ToolDriver<GitCandidateComparisonToolNode<GitWorktreeHandle>, GitWorktreeHandle>;
+//# sourceMappingURL=git-cross-verifiers-and-tools.d.ts.map

package/dist/executors/git-cross-verifiers-and-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cross-verifiers-and-tools.d.ts","sourceRoot":"","sources":["../../src/executors/git-cross-verifiers-and-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,+BAA+B,EAC/B,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAQ3B;;;;;;;;;;GAUG;AACH,wBAAsB,kCAAkC,CACtD,IAAI,EAAE,+BAA+B,CAAC,OAAO,CAAC,EAC9C,UAAU,EAAE,aAAa,CAAC,4BAA4B,CAAC,iBAAiB,CAAC,CAAC,EAC1E,GAAG,EAAE,oBAAoB,CAAC,iBAAiB,CAAC,GAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAO5C;AA6BD;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,uBAAuB,CAAC,OAAO,CAAC,EACtC,UAAU,EAAE,aAAa,CAAC,4BAA4B,CAAC,iBAAiB,CAAC,CAAC,EAC1E,IAAI,EAAE,oBAAoB,CAAC,iBAAiB,CAAC,GAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CA0B5C;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,UAAU,CACzD,oBAAoB,CAAC,iBAAiB,CAAC,EACvC,iBAAiB,CAClB,CASA;AAED;;;;;;GAMG;AACH,wBAAgB,uCAAuC,IAAI,UAAU,CACnE,8BAA8B,CAAC,iBAAiB,CAAC,EACjD,iBAAiB,CAClB,CASA"}

package/dist/executors/git-cross-verifiers-and-tools.js

@@ -0,0 +1,112 @@
+import { runGitCommand } from './internal/git-cli-runner.js';
+import { runPublicSurfaceCrossVerification } from './internal/git-cross-test-import-scanner.js';
+import { dispatchCandidateComparisonToolCall, dispatchRefReaderToolCall, } from './internal/git-tool-dispatchers.js';
+/**
+ * Executes a `GitPublicSurfaceCrossTesterNode` (`git.publicSurfaceCrossTester`) across speculative candidates.
+ *
+ * Collects boundary-only tests from each candidate and transplants them into sibling candidates inside a checkpoint sandbox.
+ *
+ * @param {GitPublicSurfaceCrossTesterNode<unknown>}                       node       - Public-surface cross-tester AST node.
+ * @param {ReadonlyArray<CrossVerifierBranchCandidate<GitWorktreeHandle>>} candidates - Surviving speculative candidate branches.
+ * @param {StepExecutionContext<GitWorktreeHandle>}                        ctx        - Active step execution context.
+ *
+ * @returns {Promise<Readonly<Record<number, unknown>>>} Per-branch cross-testing report indexed by `branchIndex`.
+ */
+export async function executeGitPublicSurfaceCrossTester(node, candidates, ctx) {
+    const runVerifier = () => runPublicSurfaceCrossVerification(node, candidates, ctx.signal);
+    if (node.runner !== undefined && typeof ctx.getRunner === 'function') {
+        return ctx.getRunner(node.runner).withSlot(runVerifier, ctx.signal);
+    }
+    return runVerifier();
+}
+/**
+ * Computes the normalized `git patch-id --stable` digest for a single speculative candidate branch.
+ *
+ * @param {CrossVerifierBranchCandidate<GitWorktreeHandle>} candidate - Speculative candidate descriptor.
+ *
+ * @returns {Promise<string>} Stable normalized patch digest, or `'EMPTY_PATCH'` when the diff is empty.
+ */
+async function computeCandidatePatchDigest(candidate) {
+    const cwd = candidate.scopeHandle.worktreePath;
+    const headSha = typeof candidate.scopeReceipt['headRef'] === 'string'
+        ? candidate.scopeReceipt['headRef']
+        : (candidate.scopeHandle.headRef ?? candidate.scopeHandle.baseRef);
+    const diffOutput = await runGitCommand({
+        cwd,
+        args: ['diff', '--no-ext-diff', '--no-color', candidate.scopeHandle.baseRef, headSha],
+    });
+    if (diffOutput.stdout.trim().length === 0)
+        return 'EMPTY_PATCH';
+    const patchOutput = await runGitCommand({
+        cwd,
+        args: ['patch-id', '--stable'],
+        stdin: diffOutput.stdout,
+    });
+    return patchOutput.stdout.trim().split(/\s+/)[0] || 'EMPTY_PATCH';
+}
+/**
+ * Executes a `GitPatchEquivalenceNode` (`git.patchEquivalence`) across speculative worktree candidates.
+ *
+ * Computes normalized patch digests relative to `baseRef` and groups equivalent candidate branch indices.
+ *
+ * @param {GitPatchEquivalenceNode<unknown>}                               node       - Patch-equivalence cross-verifier AST node.
+ * @param {ReadonlyArray<CrossVerifierBranchCandidate<GitWorktreeHandle>>} candidates - Surviving speculative candidate branches.
+ * @param {StepExecutionContext<GitWorktreeHandle>}                        _ctx       - Active step execution context.
+ *
+ * @returns {Promise<Readonly<Record<number, unknown>>>} Per-branch patch equivalence report indexed by `branchIndex`.
+ */
+export async function executeGitPatchEquivalence(node, candidates, _ctx) {
+    const digestByBranch = new Map();
+    const branchesByDigest = new Map();
+    const groupIndexByDigest = new Map();
+    for (const cand of candidates) {
+        const digest = await computeCandidatePatchDigest(cand);
+        digestByBranch.set(cand.branchIndex, digest);
+        const existingGroup = branchesByDigest.get(digest);
+        if (existingGroup !== undefined)
+            existingGroup.push(cand.branchIndex);
+        else {
+            groupIndexByDigest.set(digest, branchesByDigest.size);
+            branchesByDigest.set(digest, [cand.branchIndex]);
+        }
+    }
+    const reports = {};
+    for (const cand of candidates) {
+        const digest = digestByBranch.get(cand.branchIndex) ?? '';
+        const equivalenceGroupIndex = groupIndexByDigest.get(digest) ?? 0;
+        const equivalentBranchIndices = branchesByDigest.get(digest) ?? [cand.branchIndex];
+        reports[cand.branchIndex] = node.reportSchema.parse({
+            equivalenceGroupIndex,
+            equivalentBranchIndices,
+            normalizedPatchDigest: digest,
+        });
+    }
+    return Object.freeze(reports);
+}
+/**
+ * Creates the `ToolDriver` handling `GitRefReaderToolNode` (`git:ref-reader-tool`) invocations.
+ *
+ * Declares zero scope effects (`describeEffects: () => []`) and dispatches `readRefFile`, `diffRefs`, and `listRefFiles`.
+ *
+ * @returns {ToolDriver<GitRefReaderToolNode<GitWorktreeHandle>, GitWorktreeHandle>} Stateless ref-reader tool driver.
+ */
+export function createGitRefReaderToolDrivers() {
+    return Object.freeze({
+        describeEffects: () => [],
+        execute: (node, args, ctx) => dispatchRefReaderToolCall(node, args, ctx),
+    });
+}
+/**
+ * Creates the `ToolDriver` handling `GitCandidateComparisonToolNode` (`git:candidate-comparison-tool`) invocations.
+ *
+ * Declares zero scope effects (`describeEffects: () => []`) and dispatches `diffCandidates`, `readCandidateFile`, and `evalInCandidates`.
+ *
+ * @returns {ToolDriver<GitCandidateComparisonToolNode<GitWorktreeHandle>, GitWorktreeHandle>} Stateless candidate comparison tool driver.
+ */
+export function createGitCandidateComparisonToolDrivers() {
+    return Object.freeze({
+        describeEffects: () => [],
+        execute: (node, args, ctx) => dispatchCandidateComparisonToolCall(node, args, ctx),
+    });
+}
+//# sourceMappingURL=git-cross-verifiers-and-tools.js.map

package/dist/executors/git-cross-verifiers-and-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-cross-verifiers-and-tools.js","sourceRoot":"","sources":["../../src/executors/git-cross-verifiers-and-tools.ts"],"names":[],"mappings":"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"}

package/dist/executors/git-executors.constants.d.ts

@@ -0,0 +1,4 @@
+import type { RuntimeExecutorRegistrySlice } from '@paraharness/core';
+/** Default frozen `RuntimeExecutorRegistrySlice` instance for `@paraharness/git`. */
+export declare const gitExecutors: RuntimeExecutorRegistrySlice;
+//# sourceMappingURL=git-executors.constants.d.ts.map