@north-light/api 0.3.580 → 0.3.587

package/dist/core/worktree-containment.js

@@ -0,0 +1,48 @@
+import { gitAsync } from './git.js';
+async function revParseRef(cwd, ref) {
+    const result = await gitAsync(['rev-parse', '--verify', '--quiet', ref], cwd);
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+/** Resolve the base branch's configured upstream, or its origin fallback. */
+export async function upstreamTip(cwd, baseRef) {
+    const upstream = await gitAsync(['rev-parse', '--symbolic-full-name', '--verify', `${baseRef}@{upstream}`], cwd);
+    const ref = upstream.status === 0 && upstream.stdout.trim().startsWith('refs/')
+        ? upstream.stdout.trim()
+        : `refs/remotes/origin/${baseRef}`;
+    const sha = await revParseRef(cwd, ref);
+    return sha === null ? null : { ref, sha };
+}
+/** Prove that a recorded base or its upstream already carries a branch's
+ * committed content. This is the one decision point for explicit close and
+ * sweep cleanup: destination resolution happens only when this returns null. */
+export async function proveBranchContained(cwd, wt, branchSha) {
+    const candidates = [];
+    const localBaseRef = `refs/heads/${wt.base_ref}`;
+    const localBase = await revParseRef(cwd, localBaseRef);
+    if (localBase !== null)
+        candidates.push({ ref: localBaseRef, sha: localBase });
+    const upstream = await upstreamTip(cwd, wt.base_ref);
+    if (upstream !== null)
+        candidates.push(upstream);
+    for (const candidate of candidates) {
+        if ((await gitAsync(['merge-base', '--is-ancestor', branchSha, candidate.sha], cwd)).status === 0)
+            return { containingRef: candidate.ref, containingSha: candidate.sha };
+    }
+    for (const candidate of candidates) {
+        const cherry = await gitAsync(['cherry', candidate.sha, branchSha], cwd);
+        if (cherry.status !== 0)
+            continue;
+        const lines = cherry.stdout.split('\n').map((line) => line.trim()).filter((line) => line !== '');
+        if (lines.every((line) => line.startsWith('-')))
+            return { containingRef: candidate.ref, containingSha: candidate.sha };
+    }
+    for (const candidate of candidates) {
+        const candidateTree = await revParseRef(cwd, `${candidate.sha}^{tree}`);
+        if (candidateTree === null)
+            continue;
+        const merged = await gitAsync(['merge-tree', '--write-tree', candidate.sha, branchSha], cwd);
+        if (merged.status === 0 && merged.stdout.split('\n')[0]?.trim() === candidateTree)
+            return { containingRef: candidate.ref, containingSha: candidate.sha };
+    }
+    return null;
+}

package/dist/core/worktree-landing.d.ts

@@ -0,0 +1,44 @@
+/** Tracked-but-modified and untracked paths from `git status --porcelain`. */
+export interface CheckoutStatus {
+    /** Paths with modifications to a tracked file (staged, unstaged, or both). */
+    tracked: string[];
+    /** Paths Git does not track at all. */
+    untracked: string[];
+}
+/** Split `git status --porcelain` (v1 format) into tracked modifications and
+ *  untracked paths. A rename entry (`R  old -> new`) reports the destination:
+ *  that is the path an incoming commit would collide with. */
+export declare function parseStatusPorcelain(porcelain: string): CheckoutStatus;
+export type LandPlan = 
+/** Nothing local overlaps the incoming commits — fast-forward directly. */
+{
+    kind: 'direct';
+}
+/** Local modifications touch incoming files; land underneath them. */
+ | {
+    kind: 'stash';
+    overlapping: string[];
+}
+/** An incoming commit adds a path that already exists here, untracked. */
+ | {
+    kind: 'refuse';
+    collisions: string[];
+};
+/** How to fast-forward a base checkout that may hold local changes.
+ *
+ *  Git is less fragile than it looks here: a fast-forward refuses only when an
+ *  incoming commit touches a file with local modifications, so DISJOINT local
+ *  changes are carried along fine and need no stash at all. Overlap is the
+ *  blocker, not dirt.
+ *
+ *  Untracked files are different. They also do not block a fast-forward unless
+ *  an incoming commit adds the same path — and that collision is a refusal
+ *  rather than a stash, because sweeping a person's untracked file into a stash
+ *  to make room for a commit is not a trade this code may make on their behalf. */
+export declare function planLandIntoCheckout(status: CheckoutStatus, incoming: readonly string[]): LandPlan;
+/** The `git update-ref --stdin` body that deletes a managed branch ONLY while
+ *  the ref that proved its content already landed is still at the exact SHA the
+ *  proof inspected. Compare-and-delete is the whole ownership guard: a branch
+ *  or base someone else moved between the proof and this transaction aborts it
+ *  instead of losing the work. */
+export declare function refDeleteTransactionStdin(branch: string, branchSha: string, containingRef: string, containingSha: string): string;

package/dist/core/worktree-landing.js

@@ -0,0 +1,56 @@
+// The judgment shared by every path that lands a managed worktree onto its
+// base branch. These functions run no subprocesses and touch no filesystem:
+// they decide from Git output that the caller already has in hand.
+//
+// Two callers execute the same decision in two forms — `worktree.ts`'s
+// synchronous `close` (an API handler, already blocking) and
+// `worktree-sweep.ts`'s asynchronous daemon sweep (which must never block the
+// event loop). Only the process plumbing differs; the rules that decide whether
+// local work is at risk live here once, so the two can never drift.
+/** Split `git status --porcelain` (v1 format) into tracked modifications and
+ *  untracked paths. A rename entry (`R  old -> new`) reports the destination:
+ *  that is the path an incoming commit would collide with. */
+export function parseStatusPorcelain(porcelain) {
+    const tracked = [];
+    const untracked = [];
+    for (const line of porcelain.split('\n')) {
+        if (line.length < 4)
+            continue;
+        const code = line.slice(0, 2);
+        const rest = line.slice(3);
+        const path = rest.includes(' -> ') ? rest.slice(rest.indexOf(' -> ') + 4) : rest;
+        const unquoted = path.startsWith('"') && path.endsWith('"') ? path.slice(1, -1) : path;
+        if (code === '??')
+            untracked.push(unquoted);
+        else if (code !== '!!')
+            tracked.push(unquoted);
+    }
+    return { tracked, untracked };
+}
+/** How to fast-forward a base checkout that may hold local changes.
+ *
+ *  Git is less fragile than it looks here: a fast-forward refuses only when an
+ *  incoming commit touches a file with local modifications, so DISJOINT local
+ *  changes are carried along fine and need no stash at all. Overlap is the
+ *  blocker, not dirt.
+ *
+ *  Untracked files are different. They also do not block a fast-forward unless
+ *  an incoming commit adds the same path — and that collision is a refusal
+ *  rather than a stash, because sweeping a person's untracked file into a stash
+ *  to make room for a commit is not a trade this code may make on their behalf. */
+export function planLandIntoCheckout(status, incoming) {
+    const arriving = new Set(incoming);
+    const collisions = status.untracked.filter((path) => arriving.has(path));
+    if (collisions.length > 0)
+        return { kind: 'refuse', collisions };
+    const overlapping = status.tracked.filter((path) => arriving.has(path));
+    return overlapping.length > 0 ? { kind: 'stash', overlapping } : { kind: 'direct' };
+}
+/** The `git update-ref --stdin` body that deletes a managed branch ONLY while
+ *  the ref that proved its content already landed is still at the exact SHA the
+ *  proof inspected. Compare-and-delete is the whole ownership guard: a branch
+ *  or base someone else moved between the proof and this transaction aborts it
+ *  instead of losing the work. */
+export function refDeleteTransactionStdin(branch, branchSha, containingRef, containingSha) {
+    return `verify ${containingRef} ${containingSha}\ndelete refs/heads/${branch} ${branchSha}\n`;
+}

package/dist/core/worktree-mutation-async.d.ts

@@ -0,0 +1,23 @@
+import { type ManagedWorktree } from './canvas/index.js';
+import { type AbandonManagedWorktreeResult, type AutoDroppedWorktree } from './worktree.js';
+/** Run `admit` — the step that persists a node whose cwd is `cwd` — under the
+ *  repository lock the cleanup sweep removes checkouts under, when `cwd` is in
+ *  another node's managed checkout. The repository comes from that owner's
+ *  recorded managed worktree, not from the checkout on disk, so the lock is
+ *  still taken after the sweep has removed the checkout. The sweep decides to
+ *  remove a checkout and removes it inside that lock, and a node admitted inside
+ *  the same lock is either seen by that decision or finds the checkout already
+ *  gone and is refused here, instead of being persisted with a cwd that no
+ *  longer exists. */
+export declare function admitIntoManagedCheckout<T>(cwd: string, nodeId: string, admit: () => Promise<T>): Promise<T>;
+export declare function rollbackManagedWorktreeAsync(wt: ManagedWorktree): Promise<void>;
+export declare function createManagedWorktreeAsync(cwd: string, nodeId: string, baseRef?: string): Promise<ManagedWorktree>;
+export interface AbsentWorktreeConclusion {
+    dropped: AutoDroppedWorktree;
+    landedSha: string;
+}
+/** Conclude an absent checkout only from the same branch-delivery proof used by
+ * push-final and explicit close. */
+export declare function concludeAbsentManagedWorktreeAsync(nodeId: string): Promise<AbsentWorktreeConclusion | null>;
+export declare function autoDropCleanManagedWorktreeAsync(nodeId: string): Promise<AutoDroppedWorktree | null>;
+export declare function abandonManagedWorktreeAsync(nodeId: string, by: string): Promise<AbandonManagedWorktreeResult>;

package/dist/core/worktree-mutation-async.js

@@ -0,0 +1,335 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { abandonWorktreeAndRepoint, getNode, readWorktree } from './canvas/index.js';
+import { isPidAlive } from './canvas/pid.js';
+import { InputError } from './io.js';
+import { CONFIG_FILE, CRTR_DIR_NAME, STATE_FILE } from '../types.js';
+import { withExclusiveDirectoryLockAsync } from './exclusive-lock.js';
+import { gitAsync } from './git.js';
+import { WORKTREE_LOCK_WAIT_MS, canonicalPath, checkoutPathForBranchInList, isManagedWorktreeBase, managedWorktreesRoot, managedWorktreePath, persistClosedWorktreeState, worktreeLockPathForCommonDir, WorktreeError } from './worktree.js';
+import { proveBranchContained } from './worktree-containment.js';
+import { refDeleteTransactionStdin } from './worktree-landing.js';
+import { deleteTrashAsync, removeWorktreeCheckoutAsync } from './worktree-remove.js';
+// A function, not a constant: `runtime/nodes.ts` imports this module and sits in an import cycle with `worktree.ts`, so a module-level read of its exports would run before they exist.
+const lockWaitMs = () => Math.min(WORKTREE_LOCK_WAIT_MS, 25_000);
+function detailOf(result) { return (result.stderr.trim() || result.stdout.trim()).trim(); }
+async function runGit(cwd, args, code, next) {
+    const result = await gitAsync(args, cwd);
+    if (result.status !== 0)
+        throw new WorktreeError(code, `git ${args.join(' ')} failed`, next, detailOf(result));
+    return result.stdout.trim();
+}
+async function commonGitDir(cwd) {
+    return realpathSync(resolve(cwd, await runGit(cwd, ['rev-parse', '--git-common-dir'], 'git_common_dir_failed', 'Inspect the repository git metadata, then retry.')));
+}
+async function withRepositoryLock(cwd, action) {
+    const commonDir = await commonGitDir(cwd);
+    return withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), action, {
+        timeoutMs: lockWaitMs(),
+        timeoutError: () => new WorktreeError('worktree_lock_timeout', `timed out waiting for the managed-worktree lock in ${commonDir}`, 'Wait for the other managed-worktree operation to finish, then retry.'),
+    });
+}
+/** The existing managed checkout `cwd` lies in or beneath, when some other node
+ *  owns it (`<managed root>/<owner id>[/...]`); null for any other directory. */
+function foreignManagedCheckout(cwd, nodeId) {
+    const root = canonicalPath(managedWorktreesRoot());
+    const rel = relative(root, canonicalPath(cwd));
+    if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return null;
+    const owner = rel.split(sep)[0];
+    return owner === nodeId ? null : join(root, owner);
+}
+/** Run `admit` — the step that persists a node whose cwd is `cwd` — under the
+ *  repository lock the cleanup sweep removes checkouts under, when `cwd` is in
+ *  another node's managed checkout. The repository comes from that owner's
+ *  recorded managed worktree, not from the checkout on disk, so the lock is
+ *  still taken after the sweep has removed the checkout. The sweep decides to
+ *  remove a checkout and removes it inside that lock, and a node admitted inside
+ *  the same lock is either seen by that decision or finds the checkout already
+ *  gone and is refused here, instead of being persisted with a cwd that no
+ *  longer exists. */
+export async function admitIntoManagedCheckout(cwd, nodeId, admit) {
+    const checkout = foreignManagedCheckout(cwd, nodeId);
+    if (checkout === null)
+        return admit();
+    const owner = await readWorktree(basename(checkout));
+    if (owner === null)
+        return admit();
+    return withRepositoryLock(owner.repo_root, async () => {
+        if (!existsSync(cwd)) {
+            throw new InputError({ error: 'cwd_missing', message: `cwd is not an existing directory: ${cwd}`, received: cwd, field: 'cwd', next: 'Pass an existing directory; the managed checkout it was in has been cleaned up.' });
+        }
+        return admit();
+    });
+}
+async function resolveLandableBase(cwd, baseRef) {
+    const ref = `refs/heads/${baseRef}`;
+    const exists = await gitAsync(['show-ref', '--verify', '--quiet', ref], cwd);
+    if (exists.status === 1 && exists.executionFailed !== true)
+        throw new WorktreeError('missing_base_branch', `managed worktree base '${baseRef}' does not name an existing local branch`, 'The base must be a local branch that landing can fast-forward — freshen your local branch from origin first (rebase-not-merge), then base on it.');
+    if (exists.status !== 0)
+        throw new WorktreeError('base_branch_inspection_failed', `could not inspect local base branch '${baseRef}' (git show-ref exited with status ${exists.status})`, 'Inspect the repository and its Git metadata, then retry.', `status: ${exists.status}\nstderr: ${exists.stderr.trim() || '<empty>'}`);
+    return runGit(cwd, ['rev-parse', '--verify', ref], 'base_branch_resolve_failed', 'Inspect the local base branch, then retry.');
+}
+function seedExclude(repoRoot, commonDir) {
+    try {
+        const path = join(commonDir, 'info', 'exclude');
+        mkdirSync(dirname(path), { recursive: true });
+        let current = '';
+        try {
+            current = readFileSync(path, 'utf8');
+        }
+        catch { /* first write */ }
+        const patterns = [`/${CRTR_DIR_NAME}/${CONFIG_FILE}`, `/${CRTR_DIR_NAME}/${STATE_FILE}`];
+        if (patterns.every((pattern) => current.split('\n').map((line) => line.trim()).includes(pattern)))
+            return;
+        writeFileSync(path, `${current}${current !== '' && !current.endsWith('\n') ? '\n' : ''}# crtr: exclude crtr's own untracked project-scope bookkeeping (auto-added at managed-worktree creation)\n${patterns.filter((pattern) => !current.split('\n').map((line) => line.trim()).includes(pattern)).join('\n')}\n`);
+    }
+    catch { /* cosmetic only */ }
+}
+export async function rollbackManagedWorktreeAsync(wt) {
+    await withRepositoryLock(wt.repo_root, async () => {
+        const branch = await gitAsync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], wt.repo_root);
+        if (branch.status !== 0 || branch.stdout.trim() !== wt.base_sha)
+            return;
+        const list = await gitAsync(['worktree', 'list', '--porcelain'], wt.repo_root);
+        if (list.status !== 0)
+            return;
+        if (list.stdout.split('\n').some((line) => line.trim() === `branch refs/heads/${wt.branch}`)) {
+            if ((await gitAsync(['worktree', 'remove', '--force', wt.path], wt.repo_root)).status !== 0)
+                return;
+        }
+        else if (existsSync(wt.path)) {
+            try {
+                rmSync(wt.path, { recursive: true, force: true });
+            }
+            catch {
+                return;
+            }
+        }
+        await gitAsync(['update-ref', '-d', `refs/heads/${wt.branch}`, wt.base_sha], wt.repo_root);
+    });
+}
+export async function createManagedWorktreeAsync(cwd, nodeId, baseRef = 'main') {
+    const repoRoot = await runGit(cwd, ['rev-parse', '--show-toplevel'], 'not_git_repo', 'Pass --cwd <real repo> pointing inside a git repository.');
+    if (isManagedWorktreeBase(repoRoot)) {
+        throw new WorktreeError('managed_worktree_base', `cwd ${repoRoot} is a managed worktree and cannot be used as a managed worktree base`, 'Pass `--cwd` pointing at the repository’s primary checkout and keep `--worktree` set to the desired existing local base branch, including the parent branch.');
+    }
+    const commonDir = await commonGitDir(repoRoot);
+    return withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), async () => {
+        const baseSha = await resolveLandableBase(repoRoot, baseRef);
+        const path = managedWorktreePath(nodeId);
+        const branch = `crtr/${nodeId}`;
+        if (existsSync(path))
+            throw new WorktreeError('worktree_path_exists', `managed worktree path already exists: ${path}`, 'Remove the stale path or choose a fresh node id.');
+        if ((await gitAsync(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], repoRoot)).status === 0)
+            throw new WorktreeError('worktree_branch_exists', `managed worktree branch already exists: ${branch}`, 'Remove the stale branch or choose a fresh node id.');
+        const wt = { state: 'open', path, branch, repo_root: repoRoot, base_ref: baseRef, base_sha: baseSha, created: new Date().toISOString() };
+        await runGit(repoRoot, ['branch', branch, baseSha], 'worktree_branch_create_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
+        const added = await gitAsync(['worktree', 'add', path, branch], repoRoot);
+        if (added.status !== 0) {
+            await gitAsync(['update-ref', '-d', `refs/heads/${branch}`, baseSha], repoRoot);
+            throw new WorktreeError('worktree_add_failed', 'git worktree add failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.', detailOf(added));
+        }
+        seedExclude(repoRoot, commonDir);
+        return wt;
+    }, { timeoutMs: lockWaitMs(), timeoutError: () => new WorktreeError('worktree_lock_timeout', `timed out waiting to create a managed worktree in ${commonDir}`, 'Wait for the other managed-worktree operation to finish, then retry.') });
+}
+async function cleanTip(wt) {
+    if (wt.state !== 'open' || !existsSync(wt.path))
+        return null;
+    const branch = await gitAsync(['rev-parse', '--abbrev-ref', 'HEAD'], wt.path);
+    const status = await gitAsync(['status', '--porcelain'], wt.path);
+    const head = await gitAsync(['rev-parse', 'HEAD'], wt.path);
+    if (branch.status !== 0 || branch.stdout.trim() !== wt.branch || status.status !== 0 || status.stdout.trim() !== '' || head.status !== 0)
+        return null;
+    const gitPath = await gitAsync(['rev-parse', '--git-path', 'rebase-merge'], wt.path);
+    if (gitPath.status !== 0 || existsSync(gitPath.stdout.trim()))
+        return null;
+    return head.stdout.trim();
+}
+async function containedInLocalBase(wt, head) {
+    try {
+        const base = await resolveLandableBase(wt.path, wt.base_ref);
+        return (await gitAsync(['merge-base', '--is-ancestor', head, base], wt.path)).status === 0;
+    }
+    catch (error) {
+        // A deleted base contains nothing but the creation SHA; any other tip is not provably landed, so
+        // return false and let the caller's origin-retention check decide instead of failing finalization.
+        if (error instanceof WorktreeError && error.code === 'missing_base_branch')
+            return head === wt.base_sha;
+        throw error;
+    }
+}
+function deferred(wt) {
+    return { node_id: '', branch: wt.branch, worktree_path: wt.path, worktree_removed: false, worktree_remove_error: `cleanup pending: the caller checkout at ${wt.path} remains intact.`, branch_deleted: false, branch_delete_error: `cleanup pending: local branch ${wt.branch} remains checked out at ${wt.path}.` };
+}
+/** A missing checkout can be concluded only when its branch is already gone,
+ * or the recorded base or its upstream contains the branch and it has no other
+ * checkout. */
+async function proveAbsentPathManagedWorktree(wt) {
+    if (wt.state !== 'open' || existsSync(wt.path))
+        return null;
+    const branchRef = `refs/heads/${wt.branch}`;
+    const branchExists = await gitAsync(['show-ref', '--verify', '--quiet', branchRef], wt.repo_root);
+    if (branchExists.status === 1 && branchExists.executionFailed !== true)
+        return { branchSha: null };
+    if (branchExists.status !== 0)
+        return null;
+    const branch = await gitAsync(['rev-parse', '--verify', branchRef], wt.repo_root);
+    if (branch.status !== 0)
+        return null;
+    const branchSha = branch.stdout.trim();
+    const worktreeList = await gitAsync(['worktree', 'list', '--porcelain'], wt.repo_root);
+    if (worktreeList.status !== 0 || checkoutPathForBranchInList(worktreeList.stdout, wt.branch) !== null)
+        return null;
+    const containment = await proveBranchContained(wt.repo_root, wt, branchSha);
+    return containment === null ? null : { branchSha, containment };
+}
+async function autoDropAbsentPathManagedWorktreeLocked(nodeId, wt, proof) {
+    if (existsSync(wt.path))
+        return null;
+    if (proof.branchSha === null) {
+        await persistClosedWorktreeState(nodeId, wt, 'complete');
+        return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, worktree_removed: true, branch_deleted: true };
+    }
+    if (proof.containment === undefined)
+        return null;
+    // `update-ref` bypasses Git's checked-out-branch protection. A person can
+    // add a worktree after the list above, so the delivered branch stays intact:
+    // its containment proof concludes this node without risking that checkout.
+    await persistClosedWorktreeState(nodeId, wt, 'complete');
+    return { node_id: nodeId, branch: wt.branch, worktree_path: wt.path, worktree_removed: true, branch_deleted: false, branch_delete_error: `local branch ${wt.branch} is delivered but retained because its checkout status can change outside crtr's repository lock.` };
+}
+/** Conclude an absent checkout only from the same branch-delivery proof used by
+ * push-final and explicit close. */
+export async function concludeAbsentManagedWorktreeAsync(nodeId) {
+    const wt = (await getNode(nodeId))?.managed_worktree;
+    if (wt === undefined || wt === null || wt.state !== 'open' || existsSync(wt.path))
+        return null;
+    if (await proveAbsentPathManagedWorktree(wt) === null)
+        return null;
+    return withRepositoryLock(wt.repo_root, async () => {
+        const locked = (await getNode(nodeId))?.managed_worktree;
+        if (locked === undefined || locked === null || locked.state !== 'open')
+            return null;
+        const proof = await proveAbsentPathManagedWorktree(locked);
+        if (proof === null)
+            return null;
+        const dropped = await autoDropAbsentPathManagedWorktreeLocked(nodeId, locked, proof);
+        return dropped === null ? null : { dropped, landedSha: proof.branchSha ?? locked.base_sha };
+    });
+}
+export async function autoDropCleanManagedWorktreeAsync(nodeId) {
+    const wt = (await getNode(nodeId))?.managed_worktree;
+    if (wt === undefined || wt === null || wt.state !== 'open')
+        return null;
+    if (!existsSync(wt.path))
+        return (await concludeAbsentManagedWorktreeAsync(nodeId))?.dropped ?? null;
+    const initial = await cleanTip(wt);
+    if (initial === null || !(await containedInLocalBase(wt, initial)))
+        return null;
+    return withRepositoryLock(wt.path, async () => {
+        const locked = (await getNode(nodeId))?.managed_worktree;
+        if (locked === undefined || locked === null || locked.state !== 'open')
+            return null;
+        const head = await cleanTip(locked);
+        if (head === null || head !== initial || !(await containedInLocalBase(locked, head)))
+            return null;
+        await persistClosedWorktreeState(nodeId, locked, 'pending');
+        return { ...deferred(locked), node_id: nodeId };
+    });
+}
+async function rebaseInProgress(cwd) {
+    for (const path of ['rebase-merge', 'rebase-apply']) {
+        const result = await gitAsync(['rev-parse', '--git-path', path], cwd);
+        if (result.status !== 0 || existsSync(result.stdout.trim()))
+            return true;
+    }
+    return false;
+}
+async function persistAbandoned(nodeId, wt, tip, at, by, branch = wt.branch) {
+    await abandonWorktreeAndRepoint(nodeId, { cwd: wt.repo_root, abandoned: { branch, tip_sha: tip, at, by } });
+}
+export async function abandonManagedWorktreeAsync(nodeId, by) {
+    const wt = (await getNode(nodeId))?.managed_worktree;
+    if (wt === undefined || wt === null || wt.state !== 'open')
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to abandon for this node.');
+    const trash = [];
+    try {
+        return await withRepositoryLock(wt.path, () => abandonLocked(nodeId, by, trash));
+    }
+    finally {
+        // Removal moved the checkout's files to the trash under the lock; delete
+        // them only after releasing it.
+        await deleteTrashAsync(wt.path, trash[0]);
+    }
+}
+/** `git worktree remove` without `--force`, deferring the file delete. */
+async function removeCheckout(wt, trash) {
+    const { result: removed, trash: moved } = await removeWorktreeCheckoutAsync(wt.repo_root, wt.path);
+    if (moved !== undefined)
+        trash.push(moved);
+    if (removed.status !== 0)
+        throw new WorktreeError('worktree_remove_failed', `git worktree remove ${wt.path} failed`, 'Inspect the worktree manually, then retry.', detailOf(removed));
+}
+async function abandonLocked(nodeId, by, trash) {
+    const node = await getNode(nodeId);
+    const current = node?.managed_worktree;
+    if (node === null || current === undefined || current === null || current.state !== 'open')
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to abandon for this node.');
+    if (node.status === 'active' || node.status === 'idle' || isPidAlive(node.pi_pid))
+        throw new WorktreeError('node_running', `node ${nodeId} is still running`, 'Abandon requires a stopped node with no live broker process. From the running owner, use `crtr node worktree close` to land locally, or make the checkout clean, push its current tip to origin, and rerun `crtr push final`.');
+    if (!existsSync(current.path))
+        throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${current.path}`, 'Inspect the branch and worktree registration, then retry.');
+    const branch = await runGit(current.path, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.');
+    const recorded = await gitAsync(['show-ref', '--verify', '--quiet', `refs/heads/${current.branch}`], current.path);
+    if (branch !== current.branch) {
+        if (recorded.status === 0 || branch === 'HEAD')
+            throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${current.branch}, found ${branch === 'HEAD' ? 'detached HEAD' : branch})`, `Inspect ${current.path}, then rerun \`crtr node worktree abandon\`.`);
+        if (await rebaseInProgress(current.path) || (await runGit(current.path, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.')) !== '')
+            throw new WorktreeError('dirty_worktree', 'managed worktree has uncommitted changes', `Commit or stash them in ${current.path}, then rerun \`crtr node worktree abandon\`.`);
+        const tip = await runGit(current.path, ['rev-parse', 'HEAD'], 'abandon_tip_failed', 'Inspect the worktree manually, then retry.');
+        await removeCheckout(current, trash);
+        const at = new Date().toISOString();
+        await persistAbandoned(nodeId, current, tip, at, by, branch);
+        return { node_id: nodeId, branch, tip_sha: tip, worktree_path: current.path, branch_deleted: false };
+    }
+    const head = await runGit(current.path, ['rev-parse', 'HEAD'], 'abandon_tip_failed', 'Inspect the branch manually, then retry.');
+    let cleanBase = null;
+    try {
+        const base = await resolveLandableBase(current.path, current.base_ref);
+        if ((await gitAsync(['merge-base', '--is-ancestor', head, base], current.path)).status === 0)
+            cleanBase = base;
+    }
+    catch (error) {
+        if (!(error instanceof WorktreeError) || error.code !== 'missing_base_branch')
+            throw error;
+    }
+    const at = new Date().toISOString();
+    const status = await runGit(current.path, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.');
+    if (cleanBase !== null && head === current.base_sha) {
+        const tree = await runGit(current.repo_root, ['rev-parse', `${head}^{tree}`], 'abandon_tree_failed', 'Inspect the branch manually, then retry.');
+        const marker = await runGit(current.repo_root, ['-c', 'user.name=crtr-abandon', '-c', 'user.email=crtr-abandon@localhost', 'commit-tree', tree, '-p', head, '-m', 'crtr-abandon', '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the branch manually, then retry.');
+        await runGit(current.repo_root, ['update-ref', `refs/heads/${current.branch}`, marker, head], 'abandon_marker_failed', 'The branch changed while abandon was starting; inspect the worktree, then retry.');
+        await removeCheckout(current, trash);
+        const deleted = await gitAsync(['update-ref', '--stdin'], current.repo_root, refDeleteTransactionStdin(current.branch, marker, `refs/heads/${current.base_ref}`, cleanBase));
+        if (deleted.status === 0) {
+            await persistClosedWorktreeState(nodeId, current, 'complete');
+            return { node_id: nodeId, branch: current.branch, tip_sha: marker, worktree_path: current.path, branch_deleted: true };
+        }
+        await persistAbandoned(nodeId, current, marker, at, by);
+        return { node_id: nodeId, branch: current.branch, tip_sha: marker, worktree_path: current.path, branch_deleted: false };
+    }
+    if (!await rebaseInProgress(current.path) && status === '') {
+        await removeCheckout(current, trash);
+        await persistAbandoned(nodeId, current, head, at, by);
+        return { node_id: nodeId, branch: current.branch, tip_sha: head, worktree_path: current.path, branch_deleted: false };
+    }
+    await runGit(current.path, ['add', '--all'], 'abandon_stage_failed', 'Inspect the worktree manually, then retry.');
+    await runGit(current.path, ['-c', 'user.name=crtr-abandon', '-c', 'user.email=crtr-abandon@localhost', 'commit', '--allow-empty', '-m', 'crtr-abandon', '-m', `Crtr-Abandon: ${nodeId} ${at}`], 'abandon_commit_failed', 'Inspect the worktree manually, then retry.');
+    const tip = await runGit(current.path, ['rev-parse', 'HEAD'], 'abandon_tip_failed', 'Inspect the branch manually, then retry.');
+    await removeCheckout(current, trash);
+    await persistAbandoned(nodeId, current, tip, at, by);
+    return { node_id: nodeId, branch: current.branch, tip_sha: tip, worktree_path: current.path, branch_deleted: false };
+}

package/dist/core/worktree-remove.d.ts

@@ -0,0 +1,15 @@
+import { type GitResult } from './git.js';
+export interface CheckoutRemoval {
+    result: GitResult;
+    /** The checkout's files, now in the trash; delete with `deleteTrashAsync` after releasing the lock. */
+    trash?: string;
+}
+/** `git worktree remove <path>` (no `--force`) that leaves the checkout's files
+ *  in the trash instead of deleting them. Call with the repository lock held,
+ *  from `cwd` outside the checkout. */
+export declare function removeWorktreeCheckoutAsync(cwd: string, path: string): Promise<CheckoutRemoval>;
+/** Delete `trash` (a removal's own entry, when given) plus any leftovers
+ *  beside `path` from an interrupted earlier delete. Runs `rm` as a child
+ *  process so the delete occupies neither the event loop nor libuv's
+ *  threadpool. Never throws. */
+export declare function deleteTrashAsync(path: string, trash?: string): Promise<void>;

package/dist/core/worktree-remove.js

@@ -0,0 +1,84 @@
+// Removing a managed checkout without holding the repository lock for the
+// delete.
+//
+// `git worktree remove` deletes the checkout's files itself, and a checkout
+// with node_modules takes tens of seconds to delete. Held under the managed
+// worktree lock, that delete made every concurrent `node new --worktree` time
+// out. So the lock covers only the fast steps: git's own removal checks, a
+// rename of the checkout into a sibling trash directory (same filesystem, so
+// the rename is instant), and `git worktree remove` of the now-missing path,
+// which only drops Git's bookkeeping. The caller deletes the trash after it
+// releases the lock. Each entry's name carries its creation time, so a later
+// cleanup can take leftovers from an interrupted delete without ever touching
+// an entry a removal in progress may still rename back.
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { gitAsync } from './git.js';
+function trashDirFor(path) {
+    return join(dirname(path), '.crtr-trash');
+}
+function refused(stderr) {
+    return { status: 1, stdout: '', stderr };
+}
+/** Entries older than this are leftovers: a removal renames back, if at all,
+ *  within its one locked step. */
+const LEFTOVER_AGE_MS = 10 * 60 * 1000;
+/** `git worktree remove <path>` (no `--force`) that leaves the checkout's files
+ *  in the trash instead of deleting them. Call with the repository lock held,
+ *  from `cwd` outside the checkout. */
+export async function removeWorktreeCheckoutAsync(cwd, path) {
+    // Git refuses a locked or unclean checkout, but once the files are renamed
+    // away it sees neither. Refuse those (and git's submodule refusal) here, before anything moves, so a
+    // refused removal never has to put the files back.
+    const adminDir = await gitAsync(['rev-parse', '--absolute-git-dir'], path);
+    if (adminDir.status !== 0)
+        return { result: adminDir };
+    if (existsSync(join(adminDir.stdout.trim(), 'locked')))
+        return { result: refused(`fatal: cannot remove a locked working tree: ${path}`) };
+    if (existsSync(join(adminDir.stdout.trim(), 'modules')))
+        return { result: refused(`fatal: working trees containing submodules cannot be moved or removed: ${path}`) };
+    const status = await gitAsync(['status', '--porcelain', '--ignore-submodules=none'], path);
+    if (status.status !== 0)
+        return { result: status };
+    if (status.stdout.trim() !== '')
+        return { result: refused(`fatal: '${path}' contains modified or untracked files, use --force to delete it`) };
+    const trash = join(trashDirFor(path), `${Date.now()}-${basename(path)}-${randomUUID()}`);
+    try {
+        mkdirSync(dirname(trash), { recursive: true });
+        renameSync(path, trash);
+    }
+    catch {
+        return { result: await gitAsync(['worktree', 'remove', path], cwd) }; // e.g. EXDEV: delete in place, as before
+    }
+    const result = await gitAsync(['worktree', 'remove', path], cwd);
+    if (result.status === 0)
+        return { result, trash };
+    try {
+        renameSync(trash, path);
+    }
+    catch { /* the files stay in the trash; the refusal is still reported */ }
+    return { result };
+}
+/** Delete `trash` (a removal's own entry, when given) plus any leftovers
+ *  beside `path` from an interrupted earlier delete. Runs `rm` as a child
+ *  process so the delete occupies neither the event loop nor libuv's
+ *  threadpool. Never throws. */
+export async function deleteTrashAsync(path, trash) {
+    const dir = trashDirFor(path);
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch { /* no trash yet */ }
+    const cutoff = Date.now() - LEFTOVER_AGE_MS;
+    const targets = entries.filter((entry) => Number(entry.split('-', 1)[0]) < cutoff).map((entry) => join(dir, entry));
+    if (trash !== undefined && !targets.includes(trash))
+        targets.push(trash);
+    if (targets.length === 0)
+        return;
+    await new Promise((resolve) => {
+        execFile('rm', ['-rf', '--', ...targets], () => resolve());
+    });
+}