Paraharness

Appearance

Class: GitCowWorktreeScopeDriver ​

Defined in: git/src/executors/git-cow-worktree-scope.ts:48

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.

Implements ​

Constructors ​

Constructor ​

ts
new GitCowWorktreeScopeDriver(node): GitCowWorktreeScopeDriver;

Defined in: git/src/executors/git-cow-worktree-scope.ts:77

Initializes a GitCowWorktreeScopeDriver from its passive GitCowWorktreeNode AST configuration.

Binds the repository path, disjoint worktree directory layout, and checkpoint policy configuration.

Parameters ​

ParameterTypeDescription
nodeGitCowWorktreeNodePassive worktree scope AST configuration node.

Returns ​

GitCowWorktreeScopeDriver

Methods ​

acquireRoot() ​

ts
acquireRoot(runId): Promise<GitWorktreeHandle>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:93

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.

Parameters ​

ParameterTypeDescription
runIdstringUnique identifier of the flow run.

Returns ​

Promise<GitWorktreeHandle>

Newly acquired root worktree handle.

Implementation of ​

BranchableScope.acquireRoot

commitChild() ​

ts
commitChild(child, parent): Promise<ReconcileResult<GitScopeReceipt>>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:263

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.

Parameters ​

ParameterTypeDescription
childGitWorktreeHandleCompleted child worktree handle.
parentGitWorktreeHandleTarget parent worktree handle.

Returns ​

Promise<ReconcileResult<GitScopeReceipt>>

Clean or conflicted reconciliation result.

Implementation of ​

BranchableScope.commitChild

diffEffects() ​

ts
diffEffects(fromCheckpoint, handle): Promise<readonly ToolEffect[]>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:175

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.

Parameters ​

ParameterTypeDescription
fromCheckpointstringPre-tool serialized checkpoint payload.
handleGitWorktreeHandleWorktree handle after subprocess tool execution.

Returns ​

Promise<readonly ToolEffect[]>

Synthesized FsToolEffect list for modified paths.

Implementation of ​

BranchableScope.diffEffects

forkChild() ​

ts
forkChild(parent, forkId): Promise<GitWorktreeHandle>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:220

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.

Parameters ​

ParameterTypeDescription
parentGitWorktreeHandleParent worktree handle to clone from.
forkIdstringUnique child fork or speculative branch identifier.

Returns ​

Promise<GitWorktreeHandle>

Newly provisioned child worktree handle.

Implementation of ​

BranchableScope.forkChild

getConflictLease() ​

ts
getConflictLease(handle): LeaseDelta | undefined;

Defined in: git/src/executors/git-cow-worktree-scope.ts:304

Returns a temporary write capability lease (fs:match-globs) for handle.unresolvedConflictPaths.

Returns undefined when handle.unresolvedConflictPaths is empty.

Parameters ​

ParameterTypeDescription
handleGitWorktreeHandleWorktree handle containing unresolved conflict paths.

Returns ​

LeaseDelta | undefined

Temporary conflict write lease delta, or undefined when clean.

Implementation of ​

BranchableScope.getConflictLease

inspect() ​

ts
inspect(handle): Promise<GitScopeReceipt>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:120

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.

Parameters ​

ParameterTypeDescription
handleGitWorktreeHandleActive worktree handle to inspect.

Returns ​

Promise<GitScopeReceipt>

Validated GitScopeReceipt without mutating live HEAD or .git/index.

Implementation of ​

BranchableScope.inspect

reattachChild() ​

ts
reattachChild(
   parent, 
   forkId, 
   checkpoint?
): Promise<GitWorktreeHandle>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:244

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.

Parameters ​

ParameterTypeDescription
parentGitWorktreeHandleReattached parent worktree handle.
forkIdstringUnique child fork identifier.
checkpoint?stringOptional serialized checkpoint fallback when the directory is missing.

Returns ​

Promise<GitWorktreeHandle>

Reattached child worktree handle.

Implementation of ​

BranchableScope.reattachChild

reattachRoot() ​

ts
reattachRoot(runId, checkpoint?): Promise<GitWorktreeHandle>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:107

Rebinds an existing Task Root Worktree at <dir>/roots/<runId> during crash recovery.

Completes interrupted pendingParentHeadSha or inFlightMerge state and rolls back inFlightCommitAndPush.

Parameters ​

ParameterTypeDescription
runIdstringUnique identifier of the recovering flow run.
checkpoint?stringOptional serialized checkpoint fallback when the worktree directory is missing.

Returns ​

Promise<GitWorktreeHandle>

Reattached root worktree handle.

Implementation of ​

BranchableScope.reattachRoot

release() ​

ts
release(handle): Promise<void>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:133

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.

Parameters ​

ParameterTypeDescription
handleGitWorktreeHandleEphemeral root or child worktree handle to release.

Returns ​

Promise<void>

Resolves once the completed ref is pinned and the worktree is removed.

Implementation of ​

BranchableScope.release

restoreCheckpoint() ​

ts
restoreCheckpoint(handle, checkpoint): Promise<void>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:161

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.

Parameters ​

ParameterTypeDescription
handleGitWorktreeHandleActive worktree handle to roll back.
checkpointstringSerialized JSON checkpoint payload.

Returns ​

Promise<void>

Resolves once handle matches checkpoint.

Implementation of ​

BranchableScope.restoreCheckpoint

serializeCheckpoint() ​

ts
serializeCheckpoint(handle): Promise<string>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:147

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.

Parameters ​

ParameterTypeDescription
handleGitWorktreeHandleActive worktree handle to snapshot.

Returns ​

Promise<string>

Serialized JSON GitCheckpointPayload string.

Implementation of ​

BranchableScope.serializeCheckpoint

syncChild() ​

ts
syncChild(parent, pausedChild): Promise<ReconcileResult<GitSyncReceipt>>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:277

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.

Parameters ​

ParameterTypeDescription
parentGitWorktreeHandleUpdated parent worktree handle.
pausedChildGitWorktreeHandleSuspended child worktree handle being resumed.

Returns ​

Promise<ReconcileResult<GitSyncReceipt>>

Clean or conflicted synchronization result.

Implementation of ​

BranchableScope.syncChild

syncRoot() ​

ts
syncRoot(rootHandle, prerequisiteReceipts): Promise<ReconcileResult<GitSyncReceipt>>;

Defined in: git/src/executors/git-cow-worktree-scope.ts:291

Synchronizes rootHandle onto the terminal commit of completed prerequisite runs.

Updates rootHandle.baseBranch when prerequisite branches remain unmerged on origin/main.

Parameters ​

ParameterTypeDescription
rootHandleGitWorktreeHandleTask root worktree handle.
prerequisiteReceiptsreadonly GitScopeReceipt[]Terminal scope receipts of completed prerequisites.

Returns ​

Promise<ReconcileResult<GitSyncReceipt>>

Clean or conflicted synchronization result.

Implementation of ​

BranchableScope.syncRoot

Properties ​

id ​

ts
readonly id: string;

Defined in: git/src/executors/git-cow-worktree-scope.ts:52

Unique identifier of this isolation scope driver instance.

Implementation of ​

BranchableScope.id

receiptSchema ​

ts
readonly receiptSchema: ZodObject<{
  baseBranch: ZodDefault<ZodString>;
  baseRef: ZodString;
  branchName: ZodOptional<ZodString>;
  diffStat: ZodString;
  headRef: ZodString;
  mutatedFiles: ZodReadonly<ZodArray<ZodString>>;
}, $strip> = GitScopeReceiptSchema;

Defined in: git/src/executors/git-cow-worktree-scope.ts:54

Zod schema validating inspection receipts returned by inspect().

Implementation of ​

BranchableScope.receiptSchema

supportsBranching ​

ts
readonly supportsBranching: true;

Defined in: git/src/executors/git-cow-worktree-scope.ts:60

Capability flag confirming Copy-on-Write child worktree branching and 3-way reconciliation support.

Implementation of ​

BranchableScope.supportsBranching

supportsCheckpoints ​

ts
readonly supportsCheckpoints: true;

Defined in: git/src/executors/git-cow-worktree-scope.ts:58

Capability flag confirming git-index checkpoint serialization and rollback support.

Implementation of ​

BranchableScope.supportsCheckpoints

syncSchema ​

ts
readonly syncSchema: ZodObject<{
  baseBranch: ZodDefault<ZodString>;
  rebasedOntoRef: ZodString;
  updatedFiles: ZodReadonly<ZodArray<ZodString>>;
}, $strip> = GitSyncReceiptSchema;

Defined in: git/src/executors/git-cow-worktree-scope.ts:56

Zod schema validating synchronization receipts returned by syncChild() and syncRoot().

Implementation of ​

BranchableScope.syncSchema

Released under the MIT License.

Copyright © 2026 Tornike Tsomaia