@hearsay-tools/squawk 0.0.0-stage → 0.17.0-pr3058.5683

package/dist/delegation/workspace.d.ts

@@ -0,0 +1,40 @@
+import type { WorkerDestroyResult, WorkerDiff, WorkerWorkspace } from '../contract/index.js';
+import type { RunRecord } from '../runs/store.ts';
+/** The repository's shared Git directory (where refs, reflogs and linked-worktree admin dirs live), resolved. */
+export declare function gitCommonDir(cwd: string): Promise<string>;
+/** Reads only committed state in the server-known parent cwd; never flushes its edits. */
+export declare function resolveWorkerBaseline(repoRoot: string, parentCwd: string, baseline: string): Promise<string>;
+/** No resource side effects. Persist this exact reference/receipt before enqueueing. */
+export declare function planOwnedWorkspace(repoRoot: string, workerId: string, baselineSha: string): Promise<WorkerWorkspace>;
+/** The receipt and cleanup checkpoint files in the repository's shared receipt directory, checked
+ *  as `receiptLocation` checks it; none when it does not exist. The project migration rewrites them. */
+export declare function ownedWorkspaceRecordFiles(repoRoot: string): Promise<string[]>;
+/** One receipt or cleanup checkpoint, read with the identity-file checks. */
+export declare function readOwnedWorkspaceRecord(path: string): Promise<string>;
+/** Replace one receipt or cleanup checkpoint atomically and privately, as cleanup checkpoints are. */
+export declare function replaceOwnedWorkspaceRecord(path: string, content: string): Promise<void>;
+/** Fresh-only primitive. Runtime callers supply the already-durable preallocated intent. */
+export declare function createOwnedWorkspace(repoRoot: string, workerId: string, baselineSha: string, intent?: WorkerWorkspace): Promise<WorkerWorkspace>;
+/** Resource identity only, not caller authorization or permission to delete a repurposed branch. */
+export declare function verifyOwnedWorkspace(repoRoot: string, run: RunRecord): Promise<WorkerWorkspace>;
+/** Reuse only proven resources. No reattachment/replacement after resource loss or ambiguous provisioning. */
+export declare function ensureOwnedWorkspace(repoRoot: string, run: RunRecord): Promise<WorkerWorkspace>;
+export declare function readOwnedDiff(repoRoot: string, run: RunRecord): Promise<WorkerDiff>;
+/** A removal that could not take the worktree mutation lock in time. Contention clears without
+ * changing anything a destroy can observe, so a retry must not skip it (hearsay-tools/cezarion#879). */
+export declare const WORKTREE_LOCK_BUSY_ERROR = "Owned resources retained: worktree mutation lock is busy; retry destroy later";
+/** Thrown by a removal's `assertUnheld` when live processes may hold the worker's resources. */
+export declare class WorkspaceHeldError extends Error {
+    readonly pids: readonly number[];
+    constructor(pids: readonly number[]);
+}
+/**
+ * Checked cleanup after persisted destroy intent and termination proof. Keep the private
+ * checkpoint beyond Git-directory removal; compare exact ref/reflog identity before retrying
+ * deletion.
+ */
+export type RemovalReport = {
+    held?: (pids: readonly number[]) => void;
+    unexplained?: () => void;
+};
+export declare function removeOwnedWorkspace(repoRoot: string, value: WorkerWorkspace, assertCurrent?: () => void, beforeRemove?: () => Promise<void>, assertUnheld?: () => void, report?: RemovalReport): Promise<WorkerDestroyResult>;

package/dist/delegation/workspace.js

@@ -0,0 +1,592 @@
+import { projectPaths, fallbackProjectWriteError } from '../project-paths.js';
+import { inspectGeneration } from './process-liveness.js';
+import { waitForTestAppWatcher, withIdleTestApp } from './idle-test-app.js';
+import { windowsIdentityDirectory, windowsReadIdentity, windowsWriteIdentity } from './windows-workspace-identity.js';
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, normalize } from 'node:path';
+import { z } from 'zod';
+import { copyGitIndex } from '../git-index-copy.js';
+import { delegationStateSchema, workerWorkspaceSchema } from '../contract/index.js';
+import { branchFor, createWorktree, DIFF_CAP, worktreePathFor } from '../git-worktree.js';
+import { withWorktreeMutation, WorktreeMutationLockTimeout } from '../git-worktree-lock.js';
+import { resolveTaskDiffBase } from '../git-diff-base.js';
+import { isSafeGitRef } from '../git-refs.js';
+import { DelegationPolicyError } from './policy.js';
+const RECEIPT_CAP = 16_384;
+// Filesystem primitives belong to the host that loaded this module.
+const windowsIdentities = process.platform === 'win32';
+// Identify owned branches by tip and reflog contents, not inode identity.
+// Keep file/logFile fields for older strict checkpoint readers.
+const fileIdentitySchema = z.object({ dev: z.number(), ino: z.number(), birthtimeMs: z.number() }).strict();
+const branchIdentitySchema = z.object({ file: fileIdentitySchema, prefixBytes: z.number().int().min(1).max(4096), prefixHash: z.string().length(64) }).strict();
+const receiptSchema = z.object({ workspace: workerWorkspaceSchema, gitDir: z.string().min(1), branchIdentity: branchIdentitySchema.optional() }).strict();
+const cleanupSchema = z.object({ workspace: workerWorkspaceSchema, gitDir: z.string(), sha: workerWorkspaceSchema.shape.baselineSha,
+    logFile: fileIdentitySchema, logHash: z.string().length(64), phase: z.enum(['prepared', 'worktree-removed', 'complete']) }).strict();
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const hash = (content) => createHash('sha256').update(content).digest('hex');
+const checkUnheld = (assertUnheld) => assertUnheld?.();
+// Git for Windows emits forward slashes even for native absolute paths.
+function worktreeEntries(listed) {
+    return listed.split('\0').map(entry => entry.startsWith('worktree ') ? `worktree ${normalize(entry.slice(9))}` : entry);
+}
+async function branchLog(repoRoot, workspace) {
+    const common = await gitCommonDir(repoRoot);
+    const path = join(common, 'logs/refs/heads', workspace.branch);
+    if (await realpath(path) !== path)
+        throw new Error('Branch reflog redirected');
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || info.size > 4 * 1024 * 1024)
+            throw new Error('Branch reflog unavailable');
+        const content = await file.readFile();
+        if (content.length !== info.size)
+            throw new Error('Branch reflog changed while reading');
+        return { file: { dev: info.dev, ino: info.ino, birthtimeMs: info.birthtimeMs }, content };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function verifyBranch(repoRoot, workspace, receipt) {
+    if (!receipt.branchIdentity)
+        throw new Error('Branch creation identity absent');
+    const log = await branchLog(repoRoot, workspace);
+    const initial = receipt.branchIdentity;
+    if (log.content.length < initial.prefixBytes ||
+        hash(log.content.subarray(0, initial.prefixBytes)) !== initial.prefixHash)
+        throw new Error('Branch ownership changed');
+    return { sha: await checkedGit(repoRoot, ['rev-parse', '--verify', `refs/heads/${workspace.branch}`]), log };
+}
+async function writeCleanup(path, value, assertCurrent) {
+    return replaceIdentityFile(path, JSON.stringify(value), assertCurrent);
+}
+async function replaceIdentityFile(path, content, assertCurrent) {
+    assertCurrent?.();
+    if (windowsIdentities) {
+        windowsWriteIdentity(path, content, true);
+        return;
+    }
+    if (await exists(path))
+        await readIdentityFile(path, RECEIPT_CAP);
+    assertCurrent?.();
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeIdentityFile(temporary, content);
+    try {
+        assertCurrent?.();
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function git(cwd, args, index, maxBuffer = 32 * 1024 * 1024) {
+    return new Promise((done) => {
+        execFile('git', args, {
+            cwd, encoding: 'utf8', timeout: 30_000, maxBuffer,
+            ...(index ? { env: { ...process.env, GIT_INDEX_FILE: index } } : {}),
+        }, (error, stdout) => done({
+            ok: !error, stdout: stdout ?? '', overflow: error?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+        }));
+    });
+}
+async function checkedGit(cwd, args, index) {
+    const result = await git(cwd, args, index);
+    if (!result.ok)
+        throw new Error(`Owned workspace Git ${args[0]} failed`);
+    return result.stdout.trim();
+}
+/** The repository's shared Git directory (where refs, reflogs and linked-worktree admin dirs live), resolved. */
+export async function gitCommonDir(cwd) {
+    return realpath(await checkedGit(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+}
+async function exists(path) {
+    return lstat(path).then(() => true, (error) => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    });
+}
+/** Reads only committed state in the server-known parent cwd; never flushes its edits. */
+export async function resolveWorkerBaseline(repoRoot, parentCwd, baseline) {
+    try {
+        if (!isSafeGitRef(baseline) || baseline.length > 1024 || /[\0\r\n]/.test(baseline))
+            throw new Error('Invalid ref');
+        if (await gitCommonDir(repoRoot) !== await gitCommonDir(parentCwd))
+            throw new Error('Parent is not in this repository');
+        const ref = baseline === 'parent-head' ? 'HEAD' : baseline;
+        return workerWorkspaceSchema.shape.baselineSha.parse(await checkedGit(baseline === 'parent-head' ? parentCwd : repoRoot, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]));
+    }
+    catch {
+        throw new DelegationPolicyError('invalid_baseline', 'Worker baseline must resolve to a commit in the parent repository');
+    }
+}
+/** No resource side effects. Persist this exact reference/receipt before enqueueing. */
+export async function planOwnedWorkspace(repoRoot, workerId, baselineSha) {
+    const root = await realpath(repoRoot);
+    const workspace = workerWorkspaceSchema.parse({
+        ownerRunId: workerId, resourceId: randomUUID(), kind: 'owned-isolated',
+        path: worktreePathFor(root, workerId), branch: branchFor(workerId), baselineSha,
+    });
+    await validateIntent(root, workspace);
+    return workspace;
+}
+async function validateIntent(repoRoot, value) {
+    const workspace = workerWorkspaceSchema.parse(value);
+    const root = await realpath(repoRoot);
+    if (!projectPaths(root).reads.some(directory => workspace.path === join(directory, 'worktrees', workspace.ownerRunId)) || workspace.branch !== branchFor(workspace.ownerRunId)) {
+        throw new Error('Owned workspace identity does not match the managed resource');
+    }
+    // Do not let a symlinked managed-path prefix redirect creation into another tree.
+    let prefix = dirname(workspace.path);
+    while (prefix !== root) {
+        if (await exists(prefix) && await realpath(prefix) !== prefix)
+            throw new Error('Owned workspace path is redirected');
+        prefix = dirname(prefix);
+    }
+    const sha = await checkedGit(root, ['rev-parse', '--verify', '--end-of-options', `${workspace.baselineSha}^{commit}`]);
+    if (sha !== workspace.baselineSha)
+        throw new Error('Owned baseline is not a pinned commit');
+    return workspace;
+}
+function workerWorkspace(run) {
+    const delegation = delegationStateSchema.parse(run.delegation);
+    if (delegation.role !== 'worker' || delegation.workspace.ownerRunId !== run.id)
+        throw new Error('Missing worker ownership');
+    return delegation.workspace;
+}
+async function receiptLocation(repoRoot, workspace, create = false) {
+    return join(await receiptDirectory(repoRoot, create), `${workspace.resourceId}.json`);
+}
+async function receiptDirectory(repoRoot, create) {
+    const dir = join(await gitCommonDir(repoRoot), 'cezar-owned-workspaces');
+    if (windowsIdentities) {
+        windowsIdentityDirectory(dir, create);
+        return dir;
+    }
+    if (create)
+        await mkdir(dir, { mode: 0o700 }).catch((error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+    if (await exists(dir)) {
+        const info = await lstat(dir);
+        if (!info.isDirectory() || info.isSymbolicLink() || await realpath(dir) !== dir || (info.mode & 0o077) !== 0) {
+            throw new Error('Unsafe owned workspace receipt directory');
+        }
+    }
+    return dir;
+}
+/** The receipt and cleanup checkpoint files in the repository's shared receipt directory, checked
+ *  as `receiptLocation` checks it; none when it does not exist. The project migration rewrites them. */
+export async function ownedWorkspaceRecordFiles(repoRoot) {
+    const dir = await receiptDirectory(repoRoot, false);
+    if (!await exists(dir))
+        return [];
+    return (await readdir(dir)).filter(name => name.endsWith('.json')).sort().map(name => join(dir, name));
+}
+/** One receipt or cleanup checkpoint, read with the identity-file checks. */
+export function readOwnedWorkspaceRecord(path) {
+    return readIdentityFile(path, RECEIPT_CAP);
+}
+/** Replace one receipt or cleanup checkpoint atomically and privately, as cleanup checkpoints are. */
+export function replaceOwnedWorkspaceRecord(path, content) {
+    return replaceIdentityFile(path, content);
+}
+async function readIdentityFile(path, cap, privateParent = true) {
+    if (windowsIdentities)
+        return windowsReadIdentity(path, cap, privateParent);
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error('Unsafe owned workspace identity file');
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const opened = await file.stat();
+        if (!opened.isFile() || opened.size > cap || (opened.mode & 0o077) !== 0)
+            throw new Error('Unsafe owned workspace identity file');
+        const buffer = Buffer.alloc(cap + 1);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > cap)
+            throw new Error('Oversized owned workspace identity file');
+        return buffer.subarray(0, bytesRead).toString('utf8');
+    }
+    finally {
+        await file.close();
+    }
+}
+async function writeIdentityFile(path, content, privateParent = true) {
+    if (windowsIdentities) {
+        windowsWriteIdentity(path, content, false, privateParent);
+        return;
+    }
+    const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(content);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+async function readReceipt(path) {
+    if (!await exists(path))
+        return undefined;
+    return receiptSchema.parse(JSON.parse(await readIdentityFile(path, RECEIPT_CAP)));
+}
+/** Whether any linked worktree's admin directory still carries this resource's identity marker.
+ * An unsafe or unreadable marker throws, so the caller fails closed. */
+async function markerRemains(repoRoot, workspace) {
+    const admin = join(await gitCommonDir(repoRoot), 'worktrees');
+    if (!await exists(admin))
+        return false;
+    for (const entry of await readdir(admin)) {
+        const marker = join(admin, entry, 'cezar-owned-resource');
+        if (await exists(marker) && await readIdentityFile(marker, 36, false) === workspace.resourceId)
+            return true;
+    }
+    return false;
+}
+async function liveGitDir(repoRoot, workspace) {
+    if (await realpath(workspace.path) !== workspace.path)
+        throw new Error('Owned workspace path is redirected');
+    const rootCommon = await gitCommonDir(repoRoot);
+    if (await gitCommonDir(workspace.path) !== rootCommon)
+        throw new Error('Owned workspace repository changed');
+    const top = await realpath(await checkedGit(workspace.path, ['rev-parse', '--show-toplevel']));
+    if (top !== workspace.path)
+        throw new Error('Owned workspace is no longer a Git worktree');
+    const listed = await checkedGit(repoRoot, ['worktree', 'list', '--porcelain', '-z']);
+    if (!worktreeEntries(listed).includes(`worktree ${workspace.path}`))
+        throw new Error('Owned workspace registration missing');
+    const gitDir = await realpath(await checkedGit(workspace.path, ['rev-parse', '--absolute-git-dir']));
+    // Linked worktrees have a distinct administrative directory, never the main index.
+    if (gitDir === rootCommon)
+        throw new Error('Owned workspace points at the main repository');
+    return gitDir;
+}
+/** Fresh-only primitive. Runtime callers supply the already-durable preallocated intent. */
+export async function createOwnedWorkspace(repoRoot, workerId, baselineSha, intent) {
+    const workspace = await validateIntent(repoRoot, intent ?? await planOwnedWorkspace(repoRoot, workerId, baselineSha));
+    const refusal = fallbackProjectWriteError(workspace.path);
+    if (refusal)
+        throw new Error(refusal);
+    if (workspace.ownerRunId !== workerId || workspace.baselineSha !== baselineSha)
+        throw new Error('Owned workspace intent mismatch');
+    const receiptPath = await receiptLocation(repoRoot, workspace, true);
+    if (await exists(receiptPath))
+        throw new Error('Owned workspace receipt already exists');
+    await createWorktree(repoRoot, workerId, baselineSha, { freshOnly: true });
+    // A crash/failure before this exclusive receipt leaves ambiguous resources intact.
+    // Recovery must fail closed rather than claim them from the intended path alone.
+    const log = await branchLog(repoRoot, workspace);
+    const prefix = log.content.subarray(0, Math.min(4096, log.content.length));
+    const receipt = { workspace, gitDir: await liveGitDir(repoRoot, workspace),
+        branchIdentity: { file: log.file, prefixBytes: prefix.length, prefixHash: hash(prefix) } };
+    // Git may reuse the same administrative path after remove/add. The marker dies
+    // with that directory, preventing a stale common receipt from claiming its replacement.
+    await writeIdentityFile(join(receipt.gitDir, 'cezar-owned-resource'), workspace.resourceId, false);
+    const checkedPath = await receiptLocation(repoRoot, workspace);
+    await writeIdentityFile(checkedPath, JSON.stringify(receipt));
+    return workspace;
+}
+/** Resource identity only, not caller authorization or permission to delete a repurposed branch. */
+export async function verifyOwnedWorkspace(repoRoot, run) {
+    const workspace = await validateIntent(repoRoot, workerWorkspace(run));
+    const receipt = await readReceipt(await receiptLocation(repoRoot, workspace));
+    if (!receipt || JSON.stringify(receipt.workspace) !== JSON.stringify(workspace))
+        throw new Error('Owned workspace provisioning receipt missing or mismatched');
+    if (await liveGitDir(repoRoot, workspace) !== receipt.gitDir ||
+        await readIdentityFile(join(receipt.gitDir, 'cezar-owned-resource'), 36, false) !== workspace.resourceId) {
+        throw new Error('Owned workspace Git identity changed');
+    }
+    return workspace;
+}
+/** Reuse only proven resources. No reattachment/replacement after resource loss or ambiguous provisioning. */
+export async function ensureOwnedWorkspace(repoRoot, run) {
+    const workspace = await validateIntent(repoRoot, workerWorkspace(run));
+    const refusal = fallbackProjectWriteError(workspace.path);
+    if (refusal)
+        throw new Error(refusal);
+    if (run.delegation?.role === 'worker' && run.delegation.destroy)
+        throw new Error('Worker destruction has begun');
+    const path = await receiptLocation(repoRoot, workspace);
+    if (await exists(path))
+        return verifyOwnedWorkspace(repoRoot, run);
+    return createOwnedWorkspace(repoRoot, run.id, workspace.baselineSha, workspace);
+}
+export async function readOwnedDiff(repoRoot, run) {
+    let scratch;
+    try {
+        const workspace = await verifyOwnedWorkspace(repoRoot, run);
+        scratch = await mkdtemp(join(tmpdir(), 'cez-owned-diff-'));
+        const index = join(scratch, 'index');
+        // Preserve staged membership (including force-added ignored files) without
+        // letting diff preparation mutate the worker's own linked-worktree index.
+        const workerIndex = await checkedGit(workspace.path, ['rev-parse', '--path-format=absolute', '--git-path', 'index']);
+        await copyGitIndex(workerIndex, index);
+        await checkedGit(workspace.path, ['add', '-N', '.'], index);
+        const { base } = await resolveTaskDiffBase((args) => git(workspace.path, args, index), workspace.baselineSha, { taskBranch: workspace.branch, runStartedAt: run.startedAt });
+        // The cap is characters on the wire; allow four UTF-8 bytes per character.
+        const result = await git(workspace.path, ['diff', '--no-ext-diff', '--no-textconv', base, '--'], index, DIFF_CAP * 4 + 4);
+        if (!result.ok && !(result.overflow && result.stdout.length > DIFF_CAP))
+            throw new Error('Worker diff failed');
+        return { workerId: run.id, baselineSha: workspace.baselineSha, diff: result.stdout.slice(0, DIFF_CAP), truncated: result.stdout.length > DIFF_CAP };
+    }
+    catch {
+        throw new DelegationPolicyError('unavailable_diff', 'Owned worker diff unavailable: resource missing, unverified or unreadable');
+    }
+    finally {
+        if (scratch)
+            await rm(scratch, { recursive: true, force: true });
+    }
+}
+/** A removal that could not take the worktree mutation lock in time. Contention clears without
+ * changing anything a destroy can observe, so a retry must not skip it (hearsay-tools/cezarion#879). */
+export const WORKTREE_LOCK_BUSY_ERROR = 'Owned resources retained: worktree mutation lock is busy; retry destroy later';
+/** Thrown by a removal's `assertUnheld` when live processes may hold the worker's resources. */
+export class WorkspaceHeldError extends Error {
+    pids;
+    constructor(pids) {
+        super(`Processes ${pids.join(', ')} may still hold the worker's resources`);
+        this.pids = pids;
+    }
+}
+export async function removeOwnedWorkspace(repoRoot, value, assertCurrent, beforeRemove, assertUnheld, report) {
+    const refusal = fallbackProjectWriteError(value.path);
+    if (refusal)
+        return { workerId: value.ownerRunId, state: 'incomplete', remaining: ['worktree', 'branch'], error: refusal };
+    let remaining = ['worktree', 'branch'];
+    let provisioned = false;
+    let lockBusy = false;
+    let heldBy = [];
+    const held = (pids) => { heldBy = pids; report?.held?.(pids); };
+    let stranded;
+    let testAppBlocker;
+    const result = () => ({ workerId: value.ownerRunId, state: remaining.length ? 'incomplete' : 'complete', remaining,
+        ...(remaining.length ? { error: lockBusy ? WORKTREE_LOCK_BUSY_ERROR
+                : heldBy.length ? `Owned resources retained: processes ${heldBy.join(', ')} may still hold the worker worktree or scratch; retry destroy after they exit`
+                    : testAppBlocker ? testAppBlocker
+                        : stranded ? `Owned branch ${value.branch} ${stranded}; keep what you need, delete the branch, then retry destroy`
+                            : 'Owned resources remain: resource identity or Git cleanup could not be verified. Check the worker worktree, Git lock and ownership receipt, then retry destroy after correcting the blocker' } : {}),
+        ...(provisioned ? { deleted: [
+                ...(!remaining.includes('worktree') ? [{ kind: 'worktree', path: value.path }] : []),
+                ...(!remaining.includes('branch') ? [{ kind: 'branch', ref: `refs/heads/${value.branch}` }] : []),
+            ] } : {}),
+    });
+    try {
+        return await withWorktreeMutation(repoRoot, async (mutationGit) => {
+            assertCurrent?.();
+            const workspace = await validateIntent(repoRoot, value);
+            const path = await receiptLocation(repoRoot, workspace);
+            const receipt = await readReceipt(path);
+            const registered = async () => worktreeEntries(await checkedGit(repoRoot, ['worktree', 'list', '--porcelain', '-z']));
+            const branchExists = async () => {
+                const refs = await checkedGit(repoRoot, ['for-each-ref', '--format=%(refname)', `refs/heads/${workspace.branch}`]);
+                return refs.split('\n').includes(`refs/heads/${workspace.branch}`);
+            };
+            if (!receipt) {
+                await completeWithoutReceipt();
+                return result();
+            }
+            if (!same(receipt.workspace, workspace))
+                return result();
+            provisioned = true;
+            const checkpointPath = path.replace(/\.json$/, '.cleanup.json');
+            let checkpoint = await exists(checkpointPath) ? cleanupSchema.parse(JSON.parse(await readIdentityFile(checkpointPath, RECEIPT_CAP))) : undefined;
+            if (checkpoint && (!same(checkpoint.workspace, workspace) || checkpoint.gitDir !== receipt.gitDir))
+                return result();
+            if (checkpoint?.phase === 'complete') {
+                await inspectCompletedCleanup(receipt);
+                return result();
+            }
+            if (await exists(workspace.path) && !await removePresentWorktree(receipt))
+                return result();
+            if (!checkpoint) {
+                checkpoint = await prepareMissingWorktree(receipt);
+                if (!checkpoint)
+                    return result();
+            }
+            await removeBranch(receipt, checkpoint);
+            return result();
+            // Each phase shares this attempt's partial result while the mutation fence stays held.
+            async function completeWithoutReceipt() {
+                // #878: without a receipt, the identity marker in a Git admin directory is the
+                // only trace of a moved worktree. With path, registration, branch and marker all
+                // gone, finish bookkeeping; write no checkpoint and delete nothing.
+                const absent = async () => !await exists(workspace.path) && !(await registered()).includes(`worktree ${workspace.path}`) &&
+                    !await branchExists() && !await markerRemains(repoRoot, workspace);
+                if (await absent()) {
+                    assertCurrent?.();
+                    await beforeRemove?.();
+                    assertCurrent?.();
+                    if (await absent())
+                        remaining = [];
+                }
+                // Markers in any linked admin directory decide this, and a retrying caller's observation
+                // does not read them all: a refusal here is unexplained (hearsay-tools/cezarion#879).
+                if (remaining.length)
+                    report?.unexplained?.();
+            }
+            async function inspectCompletedCleanup(receipt) {
+                remaining = [];
+                if (await exists(workspace.path) || (await registered()).includes(`worktree ${workspace.path}`) || await exists(receipt.gitDir))
+                    remaining.push('worktree');
+                if (await branchExists())
+                    remaining.push('branch');
+            }
+            async function preparePresentWorktree(receipt) {
+                if (checkpoint?.phase === 'worktree-removed')
+                    return undefined;
+                if (await liveGitDir(repoRoot, workspace) !== receipt.gitDir ||
+                    await readIdentityFile(join(receipt.gitDir, 'cezar-owned-resource'), 36, false) !== workspace.resourceId)
+                    return undefined;
+                // HEAD files (this worktree's, another's) are not in a retrying caller's observation: these
+                // refusals report unexplained, so a retry never skips them (hearsay-tools/cezarion#879).
+                if (await checkedGit(workspace.path, ['symbolic-ref', '-q', 'HEAD']) !== `refs/heads/${workspace.branch}`) {
+                    report?.unexplained?.();
+                    return undefined;
+                }
+                // Git permits duplicate checkouts with --force. Preserve both resources
+                // before the first removal if another registered path uses this branch.
+                let registeredPath;
+                for (const entry of await registered()) {
+                    if (entry.startsWith('worktree '))
+                        registeredPath = entry.slice('worktree '.length);
+                    if (entry === `branch refs/heads/${workspace.branch}` && registeredPath !== workspace.path) {
+                        report?.unexplained?.();
+                        return undefined;
+                    }
+                }
+                const current = await verifyBranch(repoRoot, workspace, receipt);
+                if (checkpoint && (checkpoint.sha !== current.sha || checkpoint.logHash !== hash(current.log.content)))
+                    return undefined;
+                checkpoint ??= { workspace, gitDir: receipt.gitDir, sha: current.sha, logFile: current.log.file, logHash: hash(current.log.content), phase: 'prepared' };
+                return checkpoint;
+            }
+            async function removePresentWorktree(receipt) {
+                const prepared = await preparePresentWorktree(receipt);
+                if (!prepared)
+                    return false;
+                await writeCleanup(checkpointPath, prepared, assertCurrent);
+                assertCurrent?.();
+                await beforeRemove?.();
+                assertCurrent?.();
+                // Preview release may itself terminate a known owned holder. Check unrelated holders
+                // only afterwards, immediately before destructive Git; they are never signalled.
+                checkUnheld(assertUnheld);
+                const removed = await withIdleTestApp(workspace.path, async (_stopped, busy, reason) => {
+                    if (busy)
+                        testAppBlocker = reason;
+                    if (busy) {
+                        report?.unexplained?.();
+                        return false;
+                    }
+                    if (!await waitForTestAppWatcher(workspace.path)) {
+                        report?.unexplained?.();
+                        return false;
+                    }
+                    assertCurrent?.();
+                    assertUnheld?.();
+                    const holders = inspectGeneration({ paths: [workspace.path] });
+                    if (holders.liveness !== 'gone') {
+                        if (holders.pids.length)
+                            held(holders.pids);
+                        else
+                            report?.unexplained?.();
+                        return false;
+                    }
+                    const removal = await mutationGit(repoRoot, ['worktree', 'remove', '--force', workspace.path]);
+                    if (!removal.ok) {
+                        report?.unexplained?.();
+                        return false;
+                    }
+                    return true;
+                });
+                if (!removed)
+                    return false;
+                remaining = ['branch'];
+                return true;
+            }
+            async function prepareMissingWorktree(receipt) {
+                const worktreeGone = async () => !await exists(workspace.path) && !await exists(receipt.gitDir) &&
+                    !(await registered()).includes(`worktree ${workspace.path}`);
+                if (!await worktreeGone())
+                    return undefined;
+                if (!await branchExists()) {
+                    // Recorded identity already gone: finish bookkeeping. Do not delete a leftover path/gitDir/branch.
+                    assertCurrent?.();
+                    await beforeRemove?.();
+                    assertCurrent?.();
+                    if (await worktreeGone() && !await branchExists())
+                        remaining = [];
+                    return undefined;
+                }
+                // hearsay-tools/cezarion#905: the worktree went away outside cezar and left its branch behind.
+                // While the branch matches the receipt, is checked out nowhere, and it and every reflog entry
+                // sit at the baseline, it holds no work: delete it through the checkpointed compare-and-swap
+                // below. A branch reset back to its baseline keeps the worker's commits only in the reflog
+                // that the delete would drop. Commits on it are a human's call.
+                remaining = ['branch'];
+                if ((await registered()).includes(`branch refs/heads/${workspace.branch}`)) {
+                    report?.unexplained?.();
+                    return undefined;
+                }
+                const current = await verifyBranch(repoRoot, workspace, receipt);
+                if (current.sha !== workspace.baselineSha) {
+                    const commits = Number(await checkedGit(repoRoot, ['rev-list', '--count', `${workspace.baselineSha}..${current.sha}`]));
+                    stranded = commits ? `holds ${commits} commit${commits === 1 ? '' : 's'} beyond its worker baseline` : 'no longer points at its worker baseline';
+                    return undefined;
+                }
+                const tips = current.log.content.toString('utf8').split('\n').filter(Boolean).map(entry => entry.split(' ')[1]);
+                if (tips.some(tip => tip !== workspace.baselineSha)) {
+                    stranded = 'returned to its worker baseline after holding other commits';
+                    return undefined;
+                }
+                assertCurrent?.();
+                await beforeRemove?.();
+                assertCurrent?.();
+                return { workspace, gitDir: receipt.gitDir, sha: current.sha, logFile: current.log.file, logHash: hash(current.log.content), phase: 'prepared' };
+            }
+            async function removeBranch(receipt, checkpoint) {
+                if (await exists(workspace.path) || await exists(receipt.gitDir) || (await registered()).includes(`worktree ${workspace.path}`))
+                    return;
+                remaining = ['branch'];
+                checkpoint = { ...checkpoint, phase: 'worktree-removed' };
+                await writeCleanup(checkpointPath, checkpoint, assertCurrent);
+                if (await branchExists()) {
+                    if ((await registered()).includes(`branch refs/heads/${workspace.branch}`)) {
+                        report?.unexplained?.();
+                        return;
+                    }
+                    const current = await verifyBranch(repoRoot, workspace, receipt);
+                    if (current.sha !== checkpoint.sha || hash(current.log.content) !== checkpoint.logHash)
+                        return;
+                    // Ref CAS: never delete a branch advanced after our verified snapshot.
+                    assertCurrent?.();
+                    assertUnheld?.();
+                    const removed = await mutationGit(repoRoot, ['update-ref', '-d', `refs/heads/${workspace.branch}`, checkpoint.sha]);
+                    if (!removed.ok || await branchExists()) {
+                        report?.unexplained?.();
+                        return;
+                    }
+                }
+                await writeCleanup(checkpointPath, { ...checkpoint, phase: 'complete' }, assertCurrent);
+                remaining = [];
+            }
+        }, { waitMs: 1_000 });
+    }
+    catch (error) {
+        // Ambiguous ownership and every failed Git/filesystem operation fail closed.
+        lockBusy = error instanceof WorktreeMutationLockTimeout;
+        if (error instanceof WorkspaceHeldError && error.pids.length)
+            held(error.pids);
+        else
+            report?.unexplained?.();
+    }
+    return result();
+}
+//# sourceMappingURL=workspace.js.map