praxis-agent 0.60.1 → 0.62.0

package/dist/application/managed-worktree.js

@@ -5,11 +5,18 @@ import { lstat, mkdir, open, realpath } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { promisify } from 'node:util';
-import { ManagedWorktreeStore, } from '../persistence/managed-worktree-store.js';
+import { ManagedWorktreeStore, inspectManagedWorktreeRegistry, } from '../persistence/managed-worktree-store.js';
 import { resolveProjectIdentity } from '../platform/project-identity.js';
+import { sanitizeProjectPath } from '../platform/project-path-key.js';
 import { writeFileAtomically } from '../platform/atomic-write.js';
 import { ExclusiveFileLease, } from '../platform/exclusive-file-lease.js';
+import { isTerminalLifecycleState } from '../core/agent-orchestration.js';
+import { SubagentLifecycleStore } from '../persistence/subagent-lifecycle-store.js';
+import { parseAgentWorktreeOwner } from './agent-worktree-owner.js';
+import { isWorkflowAgentId, isWorkflowRunId } from '../native/workflow.js';
+import { parseTeamId } from '../core/team-ownership.js';
 const execFileAsync = promisify(execFile);
+const reconciliationCache = new Map();
 async function gitRaw(cwd, args) {
     return (await execFileAsync('git', ['-C', cwd, ...args], { encoding: 'utf8' })).stdout;
 }
@@ -26,6 +33,52 @@ async function gitOptional(cwd, args) {
         throw error;
     }
 }
+async function ownedBranchRef(repositoryRoot, branch, baseCommit) {
+    try {
+        const checked = await git(repositoryRoot, [
+            'check-ref-format',
+            '--branch',
+            branch,
+        ]);
+        if (checked !== branch)
+            return 'ambiguous';
+    }
+    catch {
+        return 'ambiguous';
+    }
+    try {
+        const value = await git(repositoryRoot, [
+            'rev-parse',
+            '--verify',
+            '--quiet',
+            `refs/heads/${branch}`,
+        ]);
+        return value === baseCommit ? 'match' : 'ambiguous';
+    }
+    catch (error) {
+        return Number(error.code) === 1
+            ? 'absent'
+            : 'ambiguous';
+    }
+}
+async function removeOwnedBranch(repositoryRoot, branch, baseCommit) {
+    const ref = await ownedBranchRef(repositoryRoot, branch, baseCommit);
+    if (ref === 'absent')
+        return;
+    if (ref === 'ambiguous')
+        throw new Error('owned branch moved or is ambiguous');
+    try {
+        await git(repositoryRoot, [
+            'update-ref',
+            '-d',
+            `refs/heads/${branch}`,
+            baseCommit,
+        ]);
+    }
+    catch (error) {
+        throw new Error(`could not safely remove owned branch: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 async function registeredWorktrees(root) {
     const output = await gitRaw(root, ['worktree', 'list', '--porcelain', '-z']);
     return new Set(output
@@ -49,6 +102,19 @@ function validOwnerId(ownerId) {
             return code <= 0x1f || code === 0x7f;
         }));
 }
+function validRetentionReason(reason) {
+    return (typeof reason === 'string' &&
+        reason.trim().length > 0 &&
+        reason.length <= 1024 &&
+        !Array.from(reason).some((character) => {
+            const code = character.codePointAt(0) ?? 0;
+            return code <= 0x1f || code === 0x7f;
+        }));
+}
+function assertRetentionReason(reason) {
+    if (!validRetentionReason(reason))
+        throw new Error('Managed worktree retention reason is invalid');
+}
 function worktreeError(options, message) {
     return new Error(`${options.label} worktree ${message}`);
 }
@@ -186,6 +252,13 @@ async function writeMarker(path, record) {
         throw new Error('Managed worktree marker already exists');
 }
 async function readMarker(worktreePath, record) {
+    const marker = await readMarkerIdentity(worktreePath);
+    if (marker.worktreeId !== record.worktreeId ||
+        marker.repositoryRoot !== record.repositoryRoot) {
+        throw new Error('worktree marker does not match ownership record');
+    }
+}
+async function readMarkerIdentity(worktreePath) {
     const markerPath = join(await linkedGitDirectory(worktreePath), 'PRAXIS_WORKTREE');
     let marker;
     try {
@@ -200,10 +273,20 @@ async function readMarker(worktreePath, record) {
         Object.keys(marker).length !== MARKER_FIELDS.size ||
         Object.keys(marker).some((key) => !MARKER_FIELDS.has(key)) ||
         marker.version !== 1 ||
-        marker.worktreeId !== record.worktreeId ||
-        marker.repositoryRoot !== record.repositoryRoot) {
-        throw new Error('worktree marker does not match ownership record');
+        typeof marker.worktreeId !== 'string' ||
+        typeof marker.repositoryRoot !== 'string') {
+        throw new Error('worktree marker is invalid');
+    }
+    const fields = marker;
+    if (!/^[a-f0-9]{32,64}$/u.test(String(fields.worktreeId)) ||
+        !isAbsolute(String(fields.repositoryRoot)) ||
+        resolve(String(fields.repositoryRoot)) !== String(fields.repositoryRoot)) {
+        throw new Error('worktree marker is invalid');
     }
+    return {
+        worktreeId: fields.worktreeId,
+        repositoryRoot: fields.repositoryRoot,
+    };
 }
 async function inspectOwnedCheckout(record, registered) {
     const registrations = registered ?? (await registeredWorktrees(record.repositoryRoot));
@@ -238,8 +321,13 @@ async function inspectOwnedCheckout(record, registered) {
         '--short',
         'HEAD',
     ]);
-    if (branch)
-        throw new Error('worktree is not detached');
+    if (record.branch === null) {
+        if (branch)
+            throw new Error('worktree is not detached');
+    }
+    else if (branch !== record.branch) {
+        throw new Error('worktree branch does not match ownership record');
+    }
     return { status, head };
 }
 function sameOwnership(left, right) {
@@ -275,7 +363,650 @@ async function retain(store, record, reason) {
         };
     }
 }
+async function reconciliationRetain(store, record, base, reason) {
+    const result = await retain(store, record, reason);
+    return {
+        ...base,
+        disposition: 'retained',
+        reason: result.reason ?? reason,
+    };
+}
+async function reconcileAgentLifecycle(stateRoot, record) {
+    const owner = parseAgentWorktreeOwner(record.ownerId);
+    if (!owner)
+        return { safe: false, reason: 'Agent owner ID is malformed' };
+    try {
+        const lifecycleStore = new SubagentLifecycleStore(stateRoot, owner.sessionId, owner.agentId);
+        const ownership = await lifecycleStore.reconcileOwnerLoss();
+        if (ownership.owned)
+            return { safe: false, reason: 'Agent lifecycle owner is live' };
+        const lifecycle = await lifecycleStore.read();
+        const classification = classifyAgentLifecycle(lifecycle, owner);
+        return classification.status === 'safely-releasable'
+            ? { safe: true }
+            : { safe: false, reason: classification.reason };
+    }
+    catch (error) {
+        return {
+            safe: false,
+            reason: `Agent lifecycle state is unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function classifyAgentLifecycle(lifecycle, owner) {
+    if (!lifecycle)
+        return { status: 'unsafe', reason: 'Agent lifecycle state is missing' };
+    const snapshot = lifecycle.lifecycle;
+    const matchingToken = isTerminalLifecycleState(snapshot.state)
+        ? snapshot.previousOwnerToken === owner.executionToken
+        : snapshot.owner?.token === owner.executionToken;
+    if (!matchingToken)
+        return {
+            status: 'unsafe',
+            reason: 'Agent lifecycle owner token does not match worktree owner',
+        };
+    if (snapshot.state === 'failed' || snapshot.state === 'cancelled')
+        return {
+            status: 'retained',
+            reason: `Agent lifecycle is ${snapshot.state}; evidence was retained`,
+        };
+    if (snapshot.state === 'orphaned')
+        return {
+            status: 'retained',
+            reason: 'Agent lifecycle is orphaned; evidence was retained',
+        };
+    if (!isTerminalLifecycleState(snapshot.state))
+        return {
+            status: 'unsafe',
+            reason: `Agent lifecycle remains ${snapshot.state}; owner state is unavailable`,
+        };
+    if (snapshot.state !== 'completed')
+        return { status: 'unsafe', reason: `Agent lifecycle is ${snapshot.state}` };
+    return {
+        status: 'safely-releasable',
+        reason: 'ownership and Git state are clean',
+    };
+}
+async function inspectAgentLifecycle(stateRoot, record) {
+    const owner = parseAgentWorktreeOwner(record.ownerId);
+    if (!owner)
+        return { status: 'unsafe', reason: 'Agent owner ID is malformed' };
+    let lifecycle;
+    try {
+        lifecycle = await new SubagentLifecycleStore(stateRoot, owner.sessionId, owner.agentId).read();
+    }
+    catch {
+        return {
+            status: 'unsafe',
+            reason: 'Agent lifecycle state is unavailable',
+        };
+    }
+    return classifyAgentLifecycle(lifecycle, owner);
+}
+function healthEntry(recordPath, record, present, status, reason) {
+    return {
+        recordPath,
+        worktreeId: record.worktreeId,
+        kind: record.kind,
+        policy: record.policy,
+        recordState: record.state,
+        worktreePath: record.worktreePath,
+        branch: record.branch,
+        present,
+        status,
+        reason: boundedHealthReason(reason),
+    };
+}
+const HEALTH_STABLE_REASONS = new Set([
+    'managed worktree path must not be a symlink',
+    'managed worktree path must be a directory',
+    'worktree path is not a real directory',
+    'worktree path is not canonical',
+    'worktree is not registered',
+    'registered worktree root does not match',
+    'repository identity does not match',
+    'worktree marker does not match ownership record',
+    'worktree marker is invalid',
+    'worktree is not detached',
+    'worktree branch does not match ownership record',
+]);
+function boundedHealthReason(reason) {
+    const codePoints = Array.from(reason);
+    return codePoints.length <= 256 ? reason : codePoints.slice(0, 256).join('');
+}
+function healthErrorReason(error, fallback) {
+    const message = error instanceof Error ? error.message : '';
+    return HEALTH_STABLE_REASONS.has(message) ? message : fallback;
+}
+function validHealthOwner(record) {
+    const parts = record.ownerId.split(':');
+    if (record.kind === 'workflow')
+        return (parts.length === 3 &&
+            parts[0] === 'workflow' &&
+            isWorkflowRunId(parts[1] ?? '') &&
+            isWorkflowAgentId(parts[2] ?? ''));
+    if (record.kind === 'agent')
+        return parseAgentWorktreeOwner(record.ownerId) !== null;
+    if (parts.length !== 5 || parts[0] !== 'team')
+        return false;
+    try {
+        parseTeamId(parts[1]);
+    }
+    catch {
+        return false;
+    }
+    return (/^[1-9]\d*$/u.test(parts[2] ?? '') &&
+        Number.isSafeInteger(Number(parts[2])) &&
+        Number(parts[2]) > 0 &&
+        /^[a-f0-9]{24}$/u.test(parts[3] ?? '') &&
+        /^[A-Za-z0-9_-]{1,128}$/u.test(parts[4] ?? ''));
+}
+async function preflightHealthPath(record) {
+    let entry;
+    try {
+        entry = await lstat(record.worktreePath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        await assertRealDirectory(record.worktreePath, 'managed worktree path');
+        return false;
+    }
+    if (entry.isSymbolicLink() || !entry.isDirectory())
+        throw new Error('worktree path is not a real directory');
+    await assertRealDirectory(record.worktreePath, 'managed worktree path');
+    if ((await realpath(record.worktreePath)) !== resolve(record.worktreePath))
+        throw new Error('worktree path is not canonical');
+    return true;
+}
+function classifyCleanHealthRecord(record, absent, agentLifecycle) {
+    if (record.state === 'retained')
+        return {
+            status: 'retained',
+            reason: record.retentionReason ?? 'record is retained',
+        };
+    if (record.policy === 'durable' || record.kind === 'team')
+        return {
+            status: 'retained',
+            reason: record.policy === 'durable'
+                ? 'durable retention policy'
+                : 'team worktree is retained',
+        };
+    if (record.kind === 'agent')
+        return (agentLifecycle ?? {
+            status: 'unsafe',
+            reason: 'Agent lifecycle state is missing',
+        });
+    return {
+        status: 'safely-releasable',
+        reason: absent
+            ? 'checkout is absent and remaining ownership evidence is releasable'
+            : 'ownership and Git state are clean',
+    };
+}
+export async function inspectManagedWorktreeHealth(options) {
+    const limit = options.limit ?? 64;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64)
+        throw new Error('Managed worktree health limit must be an integer from 1 to 64');
+    const repositoryRoot = await resolveProjectIdentity(options.cwd);
+    const registryDirectory = resolve(options.stateRoot, 'managed-worktrees', sanitizeProjectPath(repositoryRoot));
+    const stateRoot = resolve(options.stateRoot);
+    const managedRoot = resolve(stateRoot, 'managed-worktrees');
+    for (const [path, description] of [
+        [stateRoot, 'managed worktree state root'],
+        [managedRoot, 'managed worktree registry root'],
+    ]) {
+        try {
+            const info = await lstat(path);
+            if (info.isSymbolicLink())
+                throw new Error(`${description} must not be a symlink`);
+            if (!info.isDirectory())
+                throw new Error(`${description} must be a directory`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    try {
+        const info = await lstat(registryDirectory);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new Error('managed worktree registry must be a real directory');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return {
+            repositoryRoot,
+            inspected: 0,
+            truncated: false,
+            counts: {
+                active: 0,
+                retained: 0,
+                safelyReleasable: 0,
+                released: 0,
+                unsafe: 0,
+            },
+            entries: [],
+        };
+    }
+    const snapshot = await inspectManagedWorktreeRegistry({
+        stateRoot: options.stateRoot,
+        repositoryRoot,
+        limit,
+    });
+    const entries = [];
+    for (const item of snapshot.entries) {
+        if ('error' in item) {
+            entries.push({
+                recordPath: item.path,
+                worktreeId: null,
+                kind: null,
+                policy: null,
+                recordState: null,
+                worktreePath: null,
+                branch: null,
+                present: null,
+                status: 'unsafe',
+                reason: 'managed worktree record is invalid',
+            });
+            continue;
+        }
+        const original = item.record;
+        if (!validHealthOwner(original)) {
+            entries.push(healthEntry(item.path, original, null, 'unsafe', `${original.kind[0]?.toUpperCase() ?? ''}${original.kind.slice(1)} owner ID is malformed`));
+            continue;
+        }
+        let preflightPresent;
+        try {
+            preflightPresent = await preflightHealthPath(original);
+        }
+        catch (error) {
+            entries.push(healthEntry(item.path, original, true, 'unsafe', healthErrorReason(error, 'worktree path could not be inspected safely')));
+            continue;
+        }
+        const base = new ManagedWorktreeStore(options.stateRoot, repositoryRoot, original.worktreeId);
+        const lease = await base.acquireLease();
+        if (!lease) {
+            const unavailableStatus = original.state === 'released'
+                ? 'unsafe'
+                : ['creating', 'active', 'releasing'].includes(original.state)
+                    ? 'active'
+                    : 'retained';
+            entries.push(healthEntry(item.path, original, preflightPresent, unavailableStatus, original.state === 'released'
+                ? 'released record has a live or unavailable lease'
+                : unavailableStatus === 'active'
+                    ? 'worktree lease is live or unavailable'
+                    : (original.retentionReason ?? 'record is retained')));
+            continue;
+        }
+        try {
+            let record;
+            try {
+                record = await base.read();
+            }
+            catch {
+                entries.push(healthEntry(item.path, original, null, 'unsafe', 'managed worktree record could not be reread safely'));
+                continue;
+            }
+            if (!sameOwnership(record, original)) {
+                entries.push(healthEntry(item.path, record, null, 'unsafe', 'ownership record changed during inspection'));
+                continue;
+            }
+            const registered = await registeredWorktrees(record.repositoryRoot).catch(() => null);
+            if (!registered) {
+                entries.push(healthEntry(item.path, record, null, 'unsafe', 'could not inspect registered worktrees'));
+                continue;
+            }
+            let present = false;
+            try {
+                const info = await lstat(record.worktreePath);
+                present = true;
+                if (info.isSymbolicLink() || !info.isDirectory())
+                    throw new Error('worktree path is not a real directory');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    entries.push(healthEntry(item.path, record, true, 'unsafe', healthErrorReason(error, 'worktree ownership and Git state could not be validated')));
+                    continue;
+                }
+            }
+            const registeredPath = registered.has(resolve(record.worktreePath));
+            if (record.state === 'released') {
+                let branchEvidence = 'absent';
+                if (record.branch !== null)
+                    branchEvidence = await ownedBranchRef(record.repositoryRoot, record.branch, record.baseCommit);
+                if (present || registeredPath || branchEvidence !== 'absent') {
+                    entries.push(healthEntry(item.path, record, present, 'unsafe', 'released record has contradictory checkout or branch evidence'));
+                }
+                else {
+                    entries.push(healthEntry(item.path, record, false, 'released', 'record is released'));
+                }
+                continue;
+            }
+            if (!present) {
+                if (registeredPath) {
+                    entries.push(healthEntry(item.path, record, false, 'unsafe', 'worktree is missing but remains registered'));
+                    continue;
+                }
+                if (record.branch !== null) {
+                    const branchEvidence = await ownedBranchRef(record.repositoryRoot, record.branch, record.baseCommit);
+                    if (branchEvidence === 'ambiguous') {
+                        entries.push(healthEntry(item.path, record, false, 'unsafe', 'owned branch is missing or moved'));
+                        continue;
+                    }
+                }
+                const agentLifecycle = record.kind === 'agent'
+                    ? await inspectAgentLifecycle(options.stateRoot, record)
+                    : null;
+                if (agentLifecycle?.status === 'unsafe') {
+                    entries.push(healthEntry(item.path, record, false, 'unsafe', agentLifecycle.reason));
+                    continue;
+                }
+                const clean = classifyCleanHealthRecord(record, true, agentLifecycle);
+                entries.push(healthEntry(item.path, record, false, clean.status, clean.reason));
+                continue;
+            }
+            let inspection;
+            try {
+                inspection = await inspectOwnedCheckout(record, registered);
+            }
+            catch (error) {
+                entries.push(healthEntry(item.path, record, true, 'unsafe', healthErrorReason(error, 'worktree ownership and Git state could not be validated')));
+                continue;
+            }
+            const agentLifecycle = record.kind === 'agent'
+                ? await inspectAgentLifecycle(options.stateRoot, record)
+                : null;
+            if (agentLifecycle?.status === 'unsafe') {
+                entries.push(healthEntry(item.path, record, true, 'unsafe', agentLifecycle.reason));
+                continue;
+            }
+            if (agentLifecycle?.status === 'retained') {
+                entries.push(healthEntry(item.path, record, true, 'retained', agentLifecycle.reason));
+                continue;
+            }
+            if (inspection.status) {
+                entries.push(healthEntry(item.path, record, true, 'retained', 'worktree has uncommitted changes'));
+                continue;
+            }
+            if (inspection.head !== record.baseCommit) {
+                entries.push(healthEntry(item.path, record, true, 'retained', 'worktree HEAD does not match base commit'));
+                continue;
+            }
+            const clean = classifyCleanHealthRecord(record, false, agentLifecycle);
+            entries.push(healthEntry(item.path, record, true, clean.status, clean.reason));
+        }
+        finally {
+            await lease.release();
+        }
+    }
+    const counts = {
+        active: entries.filter((entry) => entry.status === 'active').length,
+        retained: entries.filter((entry) => entry.status === 'retained').length,
+        safelyReleasable: entries.filter((entry) => entry.status === 'safely-releasable').length,
+        released: entries.filter((entry) => entry.status === 'released').length,
+        unsafe: entries.filter((entry) => entry.status === 'unsafe').length,
+    };
+    return {
+        repositoryRoot,
+        inspected: snapshot.entries.length,
+        truncated: snapshot.truncated,
+        counts,
+        entries,
+    };
+}
+export async function reconcileManagedWorktrees(options) {
+    const repositoryRoot = await resolveProjectIdentity(options.cwd);
+    const snapshot = await inspectManagedWorktreeRegistry({
+        stateRoot: options.stateRoot,
+        repositoryRoot,
+        limit: 64,
+    });
+    const entries = [];
+    for (const item of snapshot.entries) {
+        if ('error' in item) {
+            entries.push({
+                recordPath: item.path,
+                disposition: 'invalid',
+                reason: item.error,
+            });
+            continue;
+        }
+        const original = item.record;
+        const baseEntry = { recordPath: item.path, worktreeId: original.worktreeId };
+        const store = new ManagedWorktreeStore(options.stateRoot, repositoryRoot, original.worktreeId);
+        const lease = await store.acquireLease();
+        if (!lease) {
+            entries.push({
+                ...baseEntry,
+                disposition: 'skipped',
+                reason: 'worktree lease is live or unavailable',
+            });
+            continue;
+        }
+        try {
+            let record;
+            try {
+                record = await store.read();
+            }
+            catch (error) {
+                entries.push({
+                    ...baseEntry,
+                    disposition: 'invalid',
+                    reason: `record could not be reread: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                continue;
+            }
+            if (!sameOwnership(record, original)) {
+                entries.push({
+                    ...baseEntry,
+                    disposition: 'retained',
+                    reason: 'ownership record changed during reconciliation',
+                });
+                continue;
+            }
+            if (record.state === 'released') {
+                entries.push({
+                    ...baseEntry,
+                    disposition: 'skipped',
+                    reason: 'already released',
+                });
+                continue;
+            }
+            if (record.state === 'retained') {
+                entries.push({
+                    ...baseEntry,
+                    disposition: 'retained',
+                    reason: record.retentionReason ?? 'record is retained',
+                });
+                continue;
+            }
+            if (record.policy === 'durable' || record.kind === 'team') {
+                entries.push(await reconciliationRetain(store, record, baseEntry, record.policy === 'durable'
+                    ? 'durable retention policy'
+                    : 'team worktree is retained'));
+                continue;
+            }
+            if (!['workflow', 'agent'].includes(record.kind) ||
+                !record.ownerId.startsWith(`${record.kind}:`) ||
+                !['creating', 'active', 'releasing'].includes(record.state)) {
+                entries.push(await reconciliationRetain(store, record, baseEntry, 'record is not an interrupted ephemeral owner'));
+                continue;
+            }
+            if (record.kind === 'agent') {
+                const lifecycle = await reconcileAgentLifecycle(options.stateRoot, record);
+                if (!lifecycle.safe) {
+                    entries.push(await reconciliationRetain(store, record, baseEntry, lifecycle.reason));
+                    continue;
+                }
+            }
+            const releasing = record.state === 'creating' ? record : nextRecord(record, 'releasing');
+            if (record.state !== 'creating') {
+                try {
+                    await store.update(releasing);
+                }
+                catch (error) {
+                    entries.push({
+                        ...baseEntry,
+                        disposition: 'retained',
+                        reason: `could not mark releasing: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                    continue;
+                }
+            }
+            const registered = await registeredWorktrees(repositoryRoot).catch(() => null);
+            if (!registered) {
+                entries.push(await reconciliationRetain(store, releasing, baseEntry, 'could not inspect registered worktrees'));
+                continue;
+            }
+            let exists = false;
+            try {
+                const info = await lstat(record.worktreePath);
+                exists = true;
+                if (info.isSymbolicLink())
+                    throw new Error('worktree path is a symlink');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    entries.push(await reconciliationRetain(store, releasing, baseEntry, error.message));
+                    continue;
+                }
+            }
+            if (!exists) {
+                if (registered.has(resolve(record.worktreePath))) {
+                    entries.push(await reconciliationRetain(store, releasing, baseEntry, 'worktree is missing but remains registered'));
+                    continue;
+                }
+                if (record.branch !== null) {
+                    const ref = await ownedBranchRef(repositoryRoot, record.branch, record.baseCommit);
+                    if (ref === 'ambiguous') {
+                        entries.push(await reconciliationRetain(store, releasing, baseEntry, 'owned branch is missing or moved'));
+                        continue;
+                    }
+                    try {
+                        if (ref === 'match')
+                            await removeOwnedBranch(repositoryRoot, record.branch, record.baseCommit);
+                    }
+                    catch (error) {
+                        entries.push(await reconciliationRetain(store, releasing, baseEntry, `could not remove owned branch: ${error.message}`));
+                        continue;
+                    }
+                }
+                try {
+                    await store.update(nextRecord(releasing, 'released'));
+                }
+                catch (error) {
+                    entries.push({
+                        ...baseEntry,
+                        disposition: 'released',
+                        reason: `released; state finalization warning: ${error.message}`,
+                    });
+                    continue;
+                }
+                entries.push({
+                    ...baseEntry,
+                    disposition: 'released',
+                    reason: 'checkout already absent',
+                });
+                continue;
+            }
+            let inspection;
+            try {
+                inspection = await inspectOwnedCheckout(record, registered);
+            }
+            catch (error) {
+                entries.push(await reconciliationRetain(store, releasing, baseEntry, error.message));
+                continue;
+            }
+            if (inspection.status || inspection.head !== record.baseCommit) {
+                const reason = inspection.status
+                    ? 'worktree has uncommitted changes'
+                    : 'worktree HEAD does not match base commit';
+                entries.push(await reconciliationRetain(store, releasing, baseEntry, reason));
+                continue;
+            }
+            if (options.hooks) {
+                try {
+                    const outcome = await options.hooks.beforeRemove({
+                        worktreePath: record.worktreePath,
+                        worktreeKind: record.kind,
+                        worktreeId: record.worktreeId,
+                        ownerId: record.ownerId,
+                        baseCommit: record.baseCommit,
+                        reason: 'reconcile',
+                    });
+                    if (outcome.blockedReason)
+                        throw new Error(`hook blocked: ${outcome.blockedReason}`);
+                }
+                catch (error) {
+                    const reason = `WorktreeRemove hook failed: ${error instanceof Error ? error.message : String(error)}`;
+                    entries.push(await reconciliationRetain(store, releasing, baseEntry, reason));
+                    continue;
+                }
+                try {
+                    const post = await inspectOwnedCheckout(record);
+                    if (post.status || post.head !== record.baseCommit)
+                        throw new Error('hook left worktree unsafe');
+                }
+                catch (error) {
+                    const reason = error.message;
+                    entries.push(await reconciliationRetain(store, releasing, baseEntry, reason));
+                    continue;
+                }
+            }
+            try {
+                if (record.branch !== null &&
+                    (await ownedBranchRef(repositoryRoot, record.branch, record.baseCommit)) === 'ambiguous')
+                    throw new Error('owned branch moved');
+                await git(repositoryRoot, ['worktree', 'remove', record.worktreePath]);
+            }
+            catch (error) {
+                const reason = error.message;
+                entries.push(await reconciliationRetain(store, releasing, baseEntry, reason));
+                continue;
+            }
+            try {
+                if (record.branch !== null)
+                    await removeOwnedBranch(repositoryRoot, record.branch, record.baseCommit);
+            }
+            catch (error) {
+                const reason = `checkout removed but owned branch was preserved: ${error.message}`;
+                entries.push(await reconciliationRetain(store, releasing, baseEntry, reason));
+                continue;
+            }
+            try {
+                await store.update(nextRecord(releasing, 'released'));
+                entries.push({
+                    ...baseEntry,
+                    disposition: 'released',
+                    reason: 'reconciled abandoned worktree',
+                });
+            }
+            catch (error) {
+                entries.push({
+                    ...baseEntry,
+                    disposition: 'released',
+                    reason: `released; state finalization warning: ${error.message}`,
+                });
+            }
+        }
+        finally {
+            await lease.release();
+        }
+    }
+    return {
+        repositoryRoot,
+        inspected: snapshot.entries.length,
+        truncated: snapshot.truncated,
+        entries,
+    };
+}
 export async function createOwnedManagedWorktree(options) {
+    if (options.parentDirectoryName !== undefined &&
+        !COMPONENT_PATTERN.test(options.parentDirectoryName)) {
+        throw worktreeError(options, 'parent name is invalid');
+    }
     if (!COMPONENT_PATTERN.test(options.directoryName)) {
         throw worktreeError(options, 'name is invalid');
     }
@@ -297,8 +1028,36 @@ export async function createOwnedManagedWorktree(options) {
     catch {
         throw worktreeError(options, 'isolation requires a Git repository');
     }
+    if (options.branch !== undefined) {
+        try {
+            const checked = await git(repositoryRoot, [
+                'check-ref-format',
+                '--branch',
+                options.branch,
+            ]);
+            if (checked !== options.branch)
+                throw new Error('branch was normalized');
+        }
+        catch {
+            throw worktreeError(options, 'branch name is invalid');
+        }
+    }
+    const reconciliationKey = repositoryRoot;
+    let reconciliation = reconciliationCache.get(reconciliationKey);
+    if (!reconciliation) {
+        reconciliation = reconcileManagedWorktrees({
+            cwd: repositoryRoot,
+            stateRoot: options.stateRoot,
+            ...(options.hooks ? { hooks: options.hooks } : {}),
+        });
+        reconciliationCache.set(reconciliationKey, reconciliation);
+    }
+    await reconciliation;
     const kindRoot = join(repositoryRoot, '.praxis', 'worktrees', options.kind);
-    const worktreePath = join(kindRoot, options.directoryName);
+    const worktreeParent = options.parentDirectoryName
+        ? join(kindRoot, options.parentDirectoryName)
+        : kindRoot;
+    const worktreePath = join(worktreeParent, options.directoryName);
     const rootRelative = relative(kindRoot, worktreePath);
     if (!rootRelative ||
         rootRelative === '..' ||
@@ -309,6 +1068,8 @@ export async function createOwnedManagedWorktree(options) {
     await assertRealDirectory(join(repositoryRoot, '.praxis'), 'managed worktree parent');
     await assertRealDirectory(join(repositoryRoot, '.praxis', 'worktrees'), 'managed worktree parent');
     await assertRealDirectory(kindRoot, 'managed worktree kind root');
+    if (options.parentDirectoryName)
+        await assertRealDirectory(worktreeParent, 'managed worktree parent');
     await ensureManagedRootIgnored(repositoryRoot);
     const worktreeId = managedWorktreeId(repositoryRoot, options.kind, options.ownerId);
     const store = new ManagedWorktreeStore(options.stateRoot, repositoryRoot, worktreeId);
@@ -324,7 +1085,7 @@ export async function createOwnedManagedWorktree(options) {
         ownerId: options.ownerId,
         repositoryRoot,
         worktreePath,
-        branch: null,
+        branch: options.branch ?? null,
         baseCommit,
         state: 'creating',
         createdAt: now,
@@ -333,6 +1094,7 @@ export async function createOwnedManagedWorktree(options) {
     let recordCreated = false;
     let gitCreated = false;
     let markerCreated = false;
+    let branchBeforeAttempt;
     let created = false;
     try {
         await store.create(record);
@@ -348,18 +1110,40 @@ export async function createOwnedManagedWorktree(options) {
             if (error.code !== 'ENOENT')
                 throw error;
         }
-        await mkdir(kindRoot, { recursive: true });
-        await assertRealDirectory(kindRoot, 'managed worktree kind root');
-        await git(repositoryRoot, [
-            'worktree',
-            'add',
-            '--detach',
-            worktreePath,
-            baseCommit,
-        ]);
+        await mkdir(worktreeParent, { recursive: true });
+        await assertRealDirectory(worktreeParent, 'managed worktree parent');
+        if (options.branch !== undefined) {
+            branchBeforeAttempt = await gitOptional(repositoryRoot, [
+                'rev-parse',
+                '--verify',
+                '--quiet',
+                `refs/heads/${options.branch}`,
+            ]);
+        }
+        await git(repositoryRoot, options.branch === undefined
+            ? ['worktree', 'add', '--detach', worktreePath, baseCommit]
+            : ['worktree', 'add', '-b', options.branch, worktreePath, baseCommit]);
         gitCreated = true;
         await writeMarker(worktreePath, record);
         markerCreated = true;
+        if (options.hooks) {
+            let outcome;
+            try {
+                outcome = await options.hooks.afterCreate({
+                    worktreePath,
+                    worktreeKind: record.kind,
+                    worktreeId: record.worktreeId,
+                    ownerId: record.ownerId,
+                    baseCommit: record.baseCommit,
+                });
+            }
+            catch (error) {
+                throw new Error(`WorktreeCreate hook failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+            if (outcome.blockedReason) {
+                throw new Error(`WorktreeCreate hook blocked: ${outcome.blockedReason}`);
+            }
+        }
         await store.update(nextRecord(record, 'active'));
         created = true;
     }
@@ -379,6 +1163,9 @@ export async function createOwnedManagedWorktree(options) {
                     throw new Error('created worktree HEAD no longer matches its base');
                 }
                 await git(repositoryRoot, ['worktree', 'remove', worktreePath]);
+                if (record.branch !== null) {
+                    await removeOwnedBranch(repositoryRoot, record.branch, record.baseCommit);
+                }
             }
             catch (removeError) {
                 rollbackError = removeError;
@@ -396,6 +1183,20 @@ export async function createOwnedManagedWorktree(options) {
                     throw pathError;
                 });
                 uncertainArtifact = pathExists || registered.has(resolve(worktreePath));
+                if (record.branch !== null) {
+                    const branchAfterAttempt = await gitOptional(repositoryRoot, [
+                        'rev-parse',
+                        '--verify',
+                        '--quiet',
+                        `refs/heads/${record.branch}`,
+                    ]);
+                    if (branchBeforeAttempt === undefined ||
+                        (branchBeforeAttempt === null
+                            ? branchAfterAttempt !== null
+                            : branchAfterAttempt !== branchBeforeAttempt)) {
+                        uncertainArtifact = true;
+                    }
+                }
             }
             catch {
                 uncertainArtifact = true;
@@ -424,37 +1225,14 @@ export async function createOwnedManagedWorktree(options) {
         if (!created)
             await lease.release();
     }
-    let executionLease = lease;
-    let removedResult;
-    let cleanupInFlight;
-    return {
-        cwd: worktreePath,
-        cleanup: async () => {
-            if (removedResult)
-                return removedResult;
-            if (cleanupInFlight)
-                return cleanupInFlight;
-            const heldLease = executionLease;
-            executionLease = undefined;
-            cleanupInFlight = cleanupOwnedManagedWorktree(store, options, record, heldLease);
-            try {
-                const result = await cleanupInFlight;
-                if (!result.retained)
-                    removedResult = result;
-                return result;
-            }
-            finally {
-                cleanupInFlight = undefined;
-            }
-        },
-    };
+    return createManagedWorktreeHandle(store, options, record, lease);
 }
-async function cleanupOwnedManagedWorktree(store, options, original, heldLease) {
+async function settleOwnedManagedWorktree(store, options, original, mode, heldLease) {
     const lease = heldLease ?? (await store.acquireLease());
     if (!lease)
         return {
             retained: true,
-            reason: `${options.label} worktree cleanup is already in progress`,
+            reason: `${options.label} worktree ${mode === 'release' ? 'release' : 'cleanup'} is already in progress`,
         };
     try {
         let record;
@@ -483,7 +1261,8 @@ async function cleanupOwnedManagedWorktree(store, options, original, heldLease)
                 reason: `${options.label} worktree is not releasable`,
             };
         }
-        if (record.policy === 'durable') {
+        const explicitDurableRelease = mode === 'release' && record.policy === 'durable';
+        if (mode === 'cleanup' && record.policy === 'durable') {
             return retain(store, record, `${options.label} worktree uses durable retention policy`);
         }
         const releasing = nextRecord(record, 'releasing');
@@ -510,6 +1289,18 @@ async function cleanupOwnedManagedWorktree(store, options, original, heldLease)
             if (registered.has(resolve(record.worktreePath))) {
                 return retain(store, releasing, `${options.label} worktree is missing but remains registered at ${record.worktreePath}`);
             }
+            if (record.branch !== null) {
+                const ref = await ownedBranchRef(record.repositoryRoot, record.branch, record.baseCommit);
+                if (ref === 'ambiguous')
+                    return retain(store, releasing, `${options.label} worktree owned branch moved or is ambiguous`);
+                try {
+                    if (ref === 'match')
+                        await removeOwnedBranch(record.repositoryRoot, record.branch, record.baseCommit);
+                }
+                catch (error) {
+                    return retain(store, releasing, `${options.label} worktree owned branch could not be removed: ${error.message}`);
+                }
+            }
             try {
                 await store.update(nextRecord(releasing, 'released'));
                 return { retained: false };
@@ -529,25 +1320,79 @@ async function cleanupOwnedManagedWorktree(store, options, original, heldLease)
             const reason = `Could not verify ${options.label.toLowerCase()} worktree ${record.worktreePath}: ${error.message}`;
             return retain(store, releasing, reason);
         }
-        if (inspection.status.length > 0) {
+        if (!explicitDurableRelease && inspection.status.length > 0) {
             const reason = `${options.label} worktree has uncommitted changes and was retained at ${record.worktreePath}`;
             return retain(store, releasing, reason);
         }
-        if (inspection.head !== record.baseCommit) {
+        if (!explicitDurableRelease && inspection.head !== record.baseCommit) {
             const reason = `${options.label} worktree has commits and was retained at ${record.worktreePath}`;
             return retain(store, releasing, reason);
         }
+        if (options.hooks) {
+            let outcome;
+            try {
+                outcome = await options.hooks.beforeRemove({
+                    worktreePath: record.worktreePath,
+                    worktreeKind: record.kind,
+                    worktreeId: record.worktreeId,
+                    ownerId: record.ownerId,
+                    baseCommit: record.baseCommit,
+                    reason: 'normal',
+                });
+            }
+            catch (error) {
+                return retain(store, releasing, `WorktreeRemove hook failed for ${record.worktreePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (outcome.blockedReason) {
+                return retain(store, releasing, `WorktreeRemove hook blocked for ${record.worktreePath}: ${outcome.blockedReason}`);
+            }
+            try {
+                const postHookRegistered = await registeredWorktrees(record.repositoryRoot);
+                const postHookInspection = await inspectOwnedCheckout(record, postHookRegistered);
+                inspection = postHookInspection;
+                if (!explicitDurableRelease && postHookInspection.status.length > 0) {
+                    return retain(store, releasing, `WorktreeRemove hook left uncommitted changes in ${record.worktreePath}; worktree was retained at ${record.worktreePath}`);
+                }
+                if (!explicitDurableRelease &&
+                    postHookInspection.head !== record.baseCommit) {
+                    return retain(store, releasing, `WorktreeRemove hook created commits in ${record.worktreePath}; worktree was retained at ${record.worktreePath}`);
+                }
+            }
+            catch (error) {
+                return retain(store, releasing, `WorktreeRemove hook left worktree unsafe at ${record.worktreePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         try {
-            await git(record.repositoryRoot, [
-                'worktree',
-                'remove',
-                record.worktreePath,
-            ]);
+            if (record.branch !== null &&
+                (await ownedBranchRef(record.repositoryRoot, record.branch, explicitDurableRelease ? inspection.head : record.baseCommit)) === 'ambiguous') {
+                return retain(store, releasing, `${options.label} worktree owned branch moved or is ambiguous`);
+            }
+            await git(record.repositoryRoot, explicitDurableRelease
+                ? ['worktree', 'remove', '--force', record.worktreePath]
+                : ['worktree', 'remove', record.worktreePath]);
         }
         catch (error) {
             const reason = `Could not remove ${options.label.toLowerCase()} worktree ${record.worktreePath}: ${error.message}`;
             return retain(store, releasing, reason);
         }
+        if (record.branch !== null) {
+            try {
+                await removeOwnedBranch(record.repositoryRoot, record.branch, explicitDurableRelease ? inspection.head : record.baseCommit);
+            }
+            catch (error) {
+                let stateWarning = '';
+                try {
+                    await store.update(nextRecord(releasing, 'released'));
+                }
+                catch (stateError) {
+                    stateWarning = `; could not finalize release state: ${stateError instanceof Error ? stateError.message : String(stateError)}`;
+                }
+                return {
+                    retained: false,
+                    reason: `checkout removed but owned branch was preserved: ${error.message}${stateWarning}`,
+                };
+            }
+        }
         try {
             await store.update(nextRecord(releasing, 'released'));
         }
@@ -563,6 +1408,181 @@ async function cleanupOwnedManagedWorktree(store, options, original, heldLease)
         await lease.release();
     }
 }
+async function cleanupOwnedManagedWorktree(store, options, original, heldLease) {
+    return settleOwnedManagedWorktree(store, options, original, 'cleanup', heldLease);
+}
+async function releaseOwnedManagedWorktree(store, options, original, heldLease) {
+    return settleOwnedManagedWorktree(store, options, original, 'release', heldLease);
+}
+async function retainOwnedManagedWorktree(store, options, original, reason, heldLease) {
+    assertRetentionReason(reason);
+    const lease = heldLease ?? (await store.acquireLease());
+    if (!lease)
+        return {
+            retained: true,
+            reason: `${options.label} worktree retention is already in progress`,
+        };
+    try {
+        let record;
+        try {
+            record = await store.read();
+        }
+        catch (error) {
+            return {
+                retained: true,
+                reason: `Could not inspect ${options.label.toLowerCase()} worktree record: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        if (!sameOwnership(record, original))
+            return {
+                retained: true,
+                reason: `${options.label} worktree ownership record does not match`,
+            };
+        if (record.state === 'released')
+            return { retained: false };
+        try {
+            await store.update(nextRecord(record, 'retained', reason));
+        }
+        catch (error) {
+            return {
+                retained: true,
+                reason: `${reason}; could not persist retention state: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        return { retained: true, reason };
+    }
+    finally {
+        await lease.release();
+    }
+}
+function createManagedWorktreeSettlement(initialLease) {
+    let executionLease = initialLease;
+    let removedResult;
+    let operationInFlight;
+    return (operation) => {
+        if (removedResult)
+            return Promise.resolve(removedResult);
+        if (operationInFlight)
+            return operationInFlight;
+        const heldLease = executionLease;
+        executionLease = undefined;
+        operationInFlight = operation(heldLease);
+        return operationInFlight
+            .then((result) => {
+            if (!result.retained)
+                removedResult = result;
+            return result;
+        })
+            .finally(() => {
+            operationInFlight = undefined;
+        });
+    };
+}
+function createManagedWorktreeHandle(store, options, record, lease) {
+    const settle = createManagedWorktreeSettlement(lease);
+    return {
+        cwd: record.worktreePath,
+        cleanup: () => settle((heldLease) => cleanupOwnedManagedWorktree(store, options, record, heldLease)),
+        retain: async (reason) => {
+            assertRetentionReason(reason);
+            return settle((heldLease) => retainOwnedManagedWorktree(store, options, record, reason, heldLease));
+        },
+        release: () => settle((heldLease) => releaseOwnedManagedWorktree(store, options, record, heldLease)),
+    };
+}
+/** Restore a checkout only when its complete managed ownership proof matches. */
+export async function restoreOwnedManagedWorktree(options) {
+    if (options.parentDirectoryName !== undefined &&
+        !COMPONENT_PATTERN.test(options.parentDirectoryName)) {
+        throw worktreeError(options, 'parent name is invalid');
+    }
+    if (!COMPONENT_PATTERN.test(options.directoryName)) {
+        throw worktreeError(options, 'name is invalid');
+    }
+    if (!options.path ||
+        !isAbsolute(options.path) ||
+        options.path.includes('\0')) {
+        throw worktreeError(options, 'path is invalid');
+    }
+    if (!options.ownerPrefix || !validOwnerId(options.ownerPrefix)) {
+        throw worktreeError(options, 'owner prefix is invalid');
+    }
+    if (options.ownerId !== undefined && !validOwnerId(options.ownerId)) {
+        throw worktreeError(options, 'owner ID is invalid');
+    }
+    let repositoryRoot;
+    try {
+        repositoryRoot = await resolveProjectIdentity(options.cwd);
+    }
+    catch {
+        throw worktreeError(options, 'restore requires a Git repository');
+    }
+    if (options.branch !== undefined) {
+        try {
+            const checked = await git(repositoryRoot, [
+                'check-ref-format',
+                '--branch',
+                options.branch,
+            ]);
+            if (checked !== options.branch)
+                throw new Error('branch was normalized');
+        }
+        catch {
+            throw worktreeError(options, 'branch name is invalid');
+        }
+    }
+    const kindRoot = join(repositoryRoot, '.praxis', 'worktrees', options.kind);
+    const expectedParent = options.parentDirectoryName
+        ? join(kindRoot, options.parentDirectoryName)
+        : kindRoot;
+    const expectedPath = join(expectedParent, options.directoryName);
+    const path = resolve(options.path);
+    if (path !== expectedPath) {
+        throw worktreeError(options, 'path does not match its managed checkout');
+    }
+    try {
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink() || !entry.isDirectory()) {
+            throw new Error('worktree path is not a real directory');
+        }
+        if ((await realpath(path)) !== path) {
+            throw new Error('worktree path is not canonical');
+        }
+    }
+    catch (error) {
+        throw worktreeError(options, `could not inspect checkout: ${error.message}`);
+    }
+    const marker = await readMarkerIdentity(path);
+    if (marker.repositoryRoot !== repositoryRoot) {
+        throw worktreeError(options, 'marker repository identity does not match');
+    }
+    const store = new ManagedWorktreeStore(options.stateRoot, repositoryRoot, marker.worktreeId);
+    const lease = await store.acquireLease();
+    if (!lease)
+        throw worktreeError(options, 'restore is already owned');
+    let accepted = false;
+    try {
+        const record = await store.read();
+        if (record.repositoryRoot !== repositoryRoot ||
+            record.worktreeId !== marker.worktreeId ||
+            record.worktreePath !== expectedPath ||
+            record.kind !== options.kind ||
+            record.policy !== options.policy ||
+            !['active', 'retained', 'releasing'].includes(record.state) ||
+            !record.ownerId.startsWith(options.ownerPrefix) ||
+            (options.ownerId !== undefined && record.ownerId !== options.ownerId) ||
+            (options.branch !== undefined && record.branch !== options.branch)) {
+            throw worktreeError(options, 'ownership evidence does not match');
+        }
+        await inspectOwnedCheckout(record);
+        accepted = true;
+        return createManagedWorktreeHandle(store, options, record, lease);
+    }
+    finally {
+        if (!accepted)
+            await lease.release();
+    }
+}
 export async function createManagedWorktree(options) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,191}$/u.test(options.directoryName)) {
         throw new Error(`Invalid ${options.label.toLowerCase()} worktree name`);
@@ -614,63 +1634,56 @@ export async function createManagedWorktree(options) {
             throw new Error(`Could not create ${options.label.toLowerCase()} worktree: ${error.message}`);
         }
     }
-    let removedResult;
-    let cleanupInFlight;
+    const settle = createManagedWorktreeSettlement();
+    const cleanup = () => settle(async () => {
+        let status;
+        let head;
+        try {
+            ;
+            [status, head] = await Promise.all([
+                git(path, ['status', '--porcelain']),
+                git(path, ['rev-parse', 'HEAD']),
+            ]);
+        }
+        catch (error) {
+            return {
+                retained: true,
+                reason: `Could not inspect ${options.label.toLowerCase()} worktree ${path}: ${error.message}`,
+            };
+        }
+        if (status.length > 0) {
+            return {
+                retained: true,
+                reason: `${options.label} worktree has uncommitted changes and was retained at ${path}`,
+            };
+        }
+        if (head !== initialHead) {
+            return {
+                retained: true,
+                reason: `${options.label} worktree has commits and was retained at ${path}`,
+            };
+        }
+        try {
+            await git(root, ['worktree', 'remove', path]);
+            return { retained: false };
+        }
+        catch (error) {
+            return {
+                retained: true,
+                reason: `Could not remove ${options.label.toLowerCase()} worktree ${path}: ${error.message}`,
+            };
+        }
+    });
     return {
         cwd: path,
-        cleanup: async () => {
-            if (removedResult)
-                return removedResult;
-            if (cleanupInFlight)
-                return cleanupInFlight;
-            cleanupInFlight = (async () => {
-                let status;
-                let head;
-                try {
-                    ;
-                    [status, head] = await Promise.all([
-                        git(path, ['status', '--porcelain']),
-                        git(path, ['rev-parse', 'HEAD']),
-                    ]);
-                }
-                catch (error) {
-                    return {
-                        retained: true,
-                        reason: `Could not inspect ${options.label.toLowerCase()} worktree ${path}: ${error.message}`,
-                    };
-                }
-                if (status.length > 0) {
-                    return {
-                        retained: true,
-                        reason: `${options.label} worktree has uncommitted changes and was retained at ${path}`,
-                    };
-                }
-                if (head !== initialHead) {
-                    return {
-                        retained: true,
-                        reason: `${options.label} worktree has commits and was retained at ${path}`,
-                    };
-                }
-                try {
-                    await git(root, ['worktree', 'remove', path]);
-                    return { retained: false };
-                }
-                catch (error) {
-                    return {
-                        retained: true,
-                        reason: `Could not remove ${options.label.toLowerCase()} worktree ${path}: ${error.message}`,
-                    };
-                }
-            })();
-            try {
-                const result = await cleanupInFlight;
-                if (!result.retained)
-                    removedResult = result;
-                return result;
-            }
-            finally {
-                cleanupInFlight = undefined;
-            }
+        cleanup,
+        release: cleanup,
+        retain: async (reason) => {
+            assertRetentionReason(reason);
+            return settle(async () => ({
+                retained: true,
+                reason,
+            }));
         },
     };
 }
@@ -724,6 +1737,16 @@ export async function restoreManagedWorktree(options) {
                 reason: `${options.label} worktree was restored and retained at ${path}`,
             };
         },
+        async release() {
+            return {
+                retained: true,
+                reason: `${options.label} worktree was restored and retained at ${path}`,
+            };
+        },
+        async retain(reason) {
+            assertRetentionReason(reason);
+            return { retained: true, reason };
+        },
     };
 }
 //# sourceMappingURL=managed-worktree.js.map