@ramon-sg/issue-flow 0.0.0-stage → 0.1.0

package/dist/start-modes.js

@@ -0,0 +1,277 @@
+/**
+ * @file The ways of `issue start` that do not open Claude in a worktree of their own:
+ * `--adopt` (a worktree another tool made, like Orca or Paseo), `--here` (the checkout of a
+ * cloud session), `--cloud` (opens a cloud session that starts the issue with `--here`)
+ * and the cloud session noted in the PR, which `--teleport` brings back. Ported from
+ * `choose_adopted`, `adopt_place`, `place_here`, `place_cloud`, `prepare_branch_here`,
+ * `note_session_in_pr` and `launch_cloud_session` in Abastio's `scripts/start-issue.sh`.
+ */
+import { spawnSync } from "node:child_process";
+import { getPr, updatePr } from "@ramon-sg/github-rest";
+import { forgetTypedAhead } from "./ask.js";
+import { checkedOutAt, currentBranch, git, hasLocal, isClean, onOrigin, ownCommits } from "./git.js";
+import { cloudSessionOf, fill, issueOfBranch, sameCloudSession, withCloudSession } from "./issue-text.js";
+import { inPath } from "./launch.js";
+import { warn } from "./output.js";
+import { again, StartError } from "./start-state.js";
+/** A branch name safe to put in the cloud session's prompt, which a skill may run. */
+const PLAIN_BRANCH = /^[A-Za-z0-9._/-]+$/;
+/** Refspec that brings every branch of origin, whatever the clone's config says. */
+const ALL_HEADS = "+refs/heads/*:refs/remotes/origin/*";
+/**
+ * The fetch of origin. In a cloud session the clone has one branch, so `--here` passes
+ * the refspec: without it neither the base nor the issue's branch would come.
+ * @param mainRoot - The main checkout.
+ * @param here - Whether it runs with `--here`.
+ * @returns True if it worked.
+ * @example fetchOrigin(root, false)
+ */
+export function fetchOrigin(mainRoot, here) {
+    return git(mainRoot, ["fetch", "-q", "--prune", "origin", ...(here ? [ALL_HEADS] : [])]).ok;
+}
+/**
+ * The branch of the worktree `--adopt` runs in, and whether it is fresh: not in origin and
+ * with no commits of its own, so the tool that made the worktree just made it.
+ * @param startRoot - The checkout where it runs.
+ * @param mainRoot - The main checkout.
+ * @param base - The base branch.
+ * @returns The branch and whether it is fresh.
+ * @throws StartError in the main checkout or on a detached HEAD.
+ * @example readAdopted(wt, root, "main") // { current: "ramon/x", fresh: true }
+ */
+export function readAdopted(startRoot, mainRoot, base) {
+    if (startRoot === mainRoot)
+        throw new StartError("--adopt runs inside a worktree, not in the main checkout.");
+    const current = currentBranch(startRoot);
+    if (current === null)
+        throw new StartError(`the worktree ${startRoot} is not on a branch; not adopting it.`);
+    return { current, fresh: !onOrigin(mainRoot, current) && ownCommits(mainRoot, current, base) === 0 };
+}
+/**
+ * The issue's work without the adopted branch when it is fresh: it is neither earlier work
+ * nor a used name.
+ * @param work - The work.
+ * @param adopted - The adopted branch.
+ * @returns The work.
+ * @example withoutFresh(work, { current: "ramon/x", fresh: true })
+ */
+export function withoutFresh(work, adopted) {
+    if (!adopted.fresh)
+        return work;
+    const other = (name) => name !== adopted.current;
+    return { ...work, known: work.known.filter(other), candidates: work.candidates.filter(other) };
+}
+/**
+ * Which branch `--adopt` takes. A live branch of the issue that the worktree is on is
+ * resumed. A fresh branch with the issue's number is the new branch as it is, with other
+ * branches or without (Paseo lets you edit the name; Orca makes one without the number).
+ * Otherwise, with no live branches the branch is renamed to the proposed one, and with
+ * some it stops: the issue goes on elsewhere.
+ * @param mainRoot - The main checkout.
+ * @param work - The issue's work.
+ * @param adopted - The adopted branch.
+ * @param number - The issue.
+ * @returns The branch resumed, or the new one already named, or neither (propose one).
+ * @throws StartError if the issue has live branches elsewhere.
+ * @example chooseAdopted(root, work, adopted, 214) // { found: null, named: "fix/214-x" }
+ */
+export function chooseAdopted(mainRoot, work, adopted, number) {
+    const { candidates } = work;
+    if (candidates.includes(adopted.current))
+        return { found: adopted.current, named: null };
+    if (adopted.fresh && issueOfBranch(adopted.current) === number)
+        return { found: null, named: adopted.current };
+    const [only] = candidates;
+    if (only === undefined)
+        return { found: null, named: null };
+    const after = "continue there with";
+    if (candidates.length > 1)
+        throw new StartError(`the issue already has ${candidates.length} branches (${candidates.join(", ")}): ${after} '${again(number)}' and delete this worktree.`);
+    const at = checkedOutAt(mainRoot, only);
+    const where = at !== null ? `at ${at}` : hasLocal(mainRoot, only) ? "local, without a worktree" : "only in origin";
+    throw new StartError(`the issue already has branch ${only} (${where}): ${after} '${again(number)}' and delete this worktree.`);
+}
+/**
+ * The place of `--adopt`: the worktree where it runs. If it is already on the branch there
+ * is nothing to check (an `--adopt` repeated or resumed); if not, it must be fresh and
+ * without uncommitted changes, so a branch with other work is never renamed. Untracked
+ * files do not count: the tool may leave its own.
+ * @param state - What it knows: the branch, the start checkout and the adopted branch.
+ * @returns The mode and the folder.
+ * @throws StartError if the worktree is not fresh.
+ * @example placeAdopted({ branch, startRoot, adopted })
+ */
+export function placeAdopted(state) {
+    const { branch, startRoot, adopted } = state;
+    const place = { mode: "worktree", workDir: startRoot };
+    if (branch === adopted.current)
+        return place;
+    if (!adopted.fresh)
+        throw new StartError(`branch ${adopted.current} is in origin or has commits of its own: only a just-made worktree is adopted.`);
+    if (!isClean(startRoot, false))
+        throw new StartError(`the worktree ${startRoot} has uncommitted changes: only a just-made worktree is adopted.`);
+    return place;
+}
+/**
+ * Renames the adopted worktree's branch to the issue's (to the same name, it does
+ * nothing). The tool that made the worktree knows it by its path, so the rename does not
+ * unlink it.
+ * @param state - The start.
+ * @throws StartError if git cannot.
+ * @example renameAdopted(state)
+ */
+export function renameAdopted(state) {
+    const current = state.adopted?.current;
+    if (current === undefined)
+        return;
+    if (!git(state.startRoot, ["branch", "-m", state.branch]).ok)
+        throw new StartError(`could not rename ${current} to ${state.branch}.`);
+}
+/**
+ * The place of `--here`: the checkout where it runs. Stops if the branch is checked out in
+ * another one, or this one has uncommitted changes (untracked files do not count: the
+ * cloud's hook leaves its own, and git says if one is in the way).
+ * @param mainRoot - The main checkout.
+ * @param startRoot - The checkout where it runs.
+ * @param branch - The branch.
+ * @param number - The issue.
+ * @returns The mode and the folder.
+ * @throws StartError if the place is taken.
+ * @example placeHere(root, root, "feat/42-x", 42)
+ */
+export function placeHere(mainRoot, startRoot, branch, number) {
+    const at = checkedOutAt(mainRoot, branch);
+    if (at !== null && at !== startRoot)
+        throw new StartError(`branch ${branch} is already at ${at}: continue there with '${again(number)}'.`);
+    if (!isClean(startRoot, false))
+        throw new StartError("this checkout has uncommitted changes; commit or stash them first. No stash is made.");
+    return { mode: "here", workDir: startRoot };
+}
+/**
+ * The place of `--cloud`: the cloud session does the work, launched from the main
+ * checkout. Stops if the branch is checked out, or exists only locally, where the cloud
+ * would not see it.
+ * @param mainRoot - The main checkout.
+ * @param branch - The branch.
+ * @param found - The branch being resumed, or null.
+ * @param number - The issue.
+ * @returns The mode and the folder.
+ * @throws StartError if the cloud cannot take the branch.
+ * @example placeCloud(root, "feat/42-x", null, 42)
+ */
+export function placeCloud(mainRoot, branch, found, number) {
+    const at = checkedOutAt(mainRoot, branch);
+    if (at !== null)
+        throw new StartError(`branch ${branch} is already at ${at}: continue there with '${again(number)}', without --cloud.`);
+    if (found !== null && !onOrigin(mainRoot, branch))
+        throw new StartError(`branch ${branch} is only local: push it or go on without --cloud.`);
+    return { mode: "cloud", workDir: mainRoot };
+}
+/**
+ * With `--here`, leaves the checkout on the branch without needing a local base: a new one
+ * comes from `origin/<base>`, an existing one from `origin/<branch>` (the fetch of every
+ * branch already brought it). A branch missing from origin is only local, somewhere else;
+ * a local branch with commits origin lacks stops it, so `-B` does not overwrite them.
+ * @param state - The start.
+ * @throws StartError if git cannot or the branch cannot be brought.
+ * @example prepareHere(state)
+ */
+export function prepareHere(state) {
+    const { workDir, branch, base, mainRoot } = state;
+    const checkout = (args) => {
+        if (!git(workDir, ["checkout", "-q", ...args]).ok)
+            throw new StartError(`could not leave ${branch} in this checkout.`);
+    };
+    if (state.found === null)
+        return checkout(["--no-track", "-B", branch, `origin/${base}`]);
+    if (!onOrigin(mainRoot, branch))
+        throw new StartError(`branch ${branch} is only local (on another machine or checkout): push it from there and run this again.`);
+    if (hasLocal(mainRoot, branch) && git(mainRoot, ["rev-list", "--count", branch, "--not", `origin/${branch}`]).out !== "0")
+        throw new StartError(`the local branch ${branch} has commits that are not in origin; push them or sort it out by hand.`);
+    checkout(["-B", branch, `origin/${branch}`]);
+}
+/**
+ * The cloud session noted in the PR's body, or null (no PR, none noted, or the PR cannot
+ * be read).
+ * @param repo - The repo.
+ * @param pr - The PR, or null.
+ * @returns The id, or null.
+ * @example await prCloudSession("acme/widgets", 7)
+ */
+export async function prCloudSession(repo, pr) {
+    if (pr === null)
+        return null;
+    const found = await getPr(repo, pr).catch(() => null);
+    return found === null ? null : cloudSessionOf(found.body);
+}
+/**
+ * The end of `--here`: notes this cloud session in the PR (if it runs in one and the PR
+ * does not have it yet), so `--teleport` finds it from any machine, and prints the
+ * `Prompt:` line the skill follows. It does not open Claude: it already runs in one.
+ * @param state - The start.
+ * @param pr - The PR.
+ * @param prompt - What the session goes on with.
+ * @example await finishHere(state, 900, prompt)
+ */
+export async function finishHere(state, pr, prompt) {
+    const { out, options } = state;
+    const id = options.remoteSession;
+    if (id !== null && !sameCloudSession(state.cloudSession, id)) {
+        try {
+            const found = await getPr(options.repo, pr);
+            if (found === null)
+                throw new Error(`PR #${pr} is gone`);
+            await updatePr(options.repo, pr, { body: withCloudSession(found.body, id) });
+        }
+        catch {
+            warn(out, `could not note the session in PR #${pr}.`);
+        }
+    }
+    out.stdout(`Ready: issue #${options.number} is on branch ${state.branch}, with its draft PR.\nPrompt: ${prompt}\n`);
+}
+/**
+ * The flags with which the cloud session picks the branch: `--new` if the issue has live
+ * branches and a new one was chosen here (`--new`, or `n` in the terminal), `--resume
+ * <branch>` if one of several was chosen. With one live branch resumed, none: the session
+ * resumes it.
+ * @param state - The start.
+ * @returns The flags, with a space before each.
+ * @throws StartError if the branch has characters a shell would read (anyone who can push
+ * names branches).
+ * @example cloudFlags(state) // " --resume fix/214-old"
+ */
+export function cloudFlags(state) {
+    const { found, work } = state;
+    if (found === null && work.candidates.length > 0)
+        return " --new";
+    if (work.candidates.length <= 1 || found === null)
+        return "";
+    if (!PLAIN_BRANCH.test(found))
+        throw new StartError(`branch ${JSON.stringify(found)} has characters the cloud session's prompt cannot carry; rename it.`);
+    return ` --resume ${found}`;
+}
+/**
+ * `--cloud` after the yes: opens the cloud session with the skill that starts the issue
+ * there, in the foreground and with the terminal (`claude --cloud` needs one), from the
+ * main checkout. Without `claude` or with `--no-launch`, says how to open it.
+ * @param state - The start.
+ * @param out - Where to write.
+ * @returns The exit code.
+ * @throws StartError if the session does not open.
+ * @example launchCloud(state, out)
+ */
+export function launchCloud(state, out) {
+    const { options, mainRoot, base } = state;
+    if (!options.launch || !inPath("claude")) {
+        out.stdout(`Ready. To open the cloud session: ${again(options.number, "--cloud")}\n`);
+        return 0;
+    }
+    if (currentBranch(mainRoot) !== base)
+        warn(out, `the main checkout is not on ${base}: the session clones its current branch.`);
+    const prompt = fill(options.config.start.cloudPrompt, { number: String(options.number), flags: cloudFlags(state) });
+    forgetTypedAhead();
+    if (spawnSync("claude", ["--cloud", prompt], { cwd: mainRoot, stdio: "inherit" }).status !== 0)
+        throw new StartError("could not open the cloud session.");
+    out.stdout(`To bring it here: ${again(options.number, "--teleport")}\n`);
+    return 0;
+}

package/dist/start-place.d.ts

@@ -0,0 +1,61 @@
+import { type StartMode } from "./issue-text.js";
+import { type Output } from "./output.js";
+import type { Lock } from "./session-lock.js";
+import { type StartState } from "./start-state.js";
+/** The file listing what a new worktree copies from the main checkout. */
+export declare const WORKTREE_INCLUDE = ".worktreeinclude";
+/**
+ * Where the work goes. If the branch is checked out somewhere, there; if not, in a new
+ * worktree or, with `--branch`, in the main checkout, which must be clean.
+ * @param mainRoot - The main checkout.
+ * @param branch - The branch.
+ * @param branchMode - Whether `--branch` was given.
+ * @param worktreesDir - The config's folder for worktrees.
+ * @returns The mode and the folder.
+ * @throws StartError if the place is taken.
+ * @example choosePlace(root, "feat/42-x", false, ".claude/worktrees")
+ */
+export declare function choosePlace(mainRoot: string, branch: string, branchMode: boolean, worktreesDir: string): {
+    mode: StartMode;
+    workDir: string;
+};
+/**
+ * Leaves the branch in its place: a new worktree (from the base, or on the existing
+ * branch), or the main checkout on it. A new branch in the main checkout needs it on the
+ * base and in step with origin.
+ * @param state - The start.
+ * @throws StartError if git cannot, with what to run in a terminal if a sandbox stops it.
+ * @example prepareBranch(state)
+ */
+export declare function prepareBranch(state: StartState): void;
+/**
+ * The start commit, the push, the draft PR, the reopening of a closed one and the
+ * assignment, as far as they are missing. The commit takes nothing staged (`--only`). It
+ * runs before copying the included files and opening Claude, so the public trace is there
+ * even if what follows fails.
+ * @param state - The start.
+ * @returns The PR's number.
+ * @throws StartError if the commit, the push or the PR fail.
+ * @example await publish(state)
+ */
+export declare function publish(state: StartState): Promise<number>;
+/**
+ * Copies to a new worktree the files of `.worktreeinclude` it lacks, like `claude
+ * --worktree` does and `git worktree add` does not: only files git ignores (the ones a
+ * checkout cannot bring, like credentials), keeping their permissions and never
+ * overwriting.
+ * @param from - The main checkout.
+ * @param to - The worktree.
+ * @param out - Where a failed copy is reported.
+ * @example copyWorktreeIncludes(root, wt, out)
+ */
+export declare function copyWorktreeIncludes(from: string, to: string, out: Output): void;
+/**
+ * After Claude: if the PR was merged and nothing would be lost, offers to delete the
+ * worktree and the branch (or, in the main checkout, to go back to the base); if not,
+ * says how to resume.
+ * @param state - The start.
+ * @param lock - The worktree lock (shared: another session uses it).
+ * @example await afterSession(state, lock)
+ */
+export declare function afterSession(state: StartState, lock: Lock): Promise<void>;

package/dist/start-place.js

@@ -0,0 +1,301 @@
+/**
+ * @file Where the work of an issue happens and what `issue start` changes: the worktree or
+ * the main checkout on the branch, the start commit, the push, the draft PR, the
+ * assignment, the files of `.worktreeinclude`, and the cleanup after a merged PR. Ported
+ * from `choose_place`, `prepare_branch`, `publish` and `after_session` in Abastio's
+ * `scripts/start-issue.sh`.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { assign, createPr, findPr, getPr, updatePr } from "@ramon-sg/github-rest";
+import { confirm } from "./ask.js";
+import { checkedOutAt, currentBranch, git, gitLines, hasLocal, isClean, onOrigin, safeToDelete } from "./git.js";
+import { bodyToPartOf, dirName, fill, prBody } from "./issue-text.js";
+import { forgetSession } from "./launch.js";
+import { warn } from "./output.js";
+import { again, StartError } from "./start-state.js";
+import { needsStartCommit, stepPlaceOf } from "./start-summary.js";
+import { teardownWorktree } from "./worktree-steps.js";
+import { openPrsElsewhere } from "./work-state.js";
+/** The file listing what a new worktree copies from the main checkout. */
+export const WORKTREE_INCLUDE = ".worktreeinclude";
+/** Characters that make a path segment a pattern. */
+const GLOB = /[*?[]/;
+/**
+ * Where the work goes. If the branch is checked out somewhere, there; if not, in a new
+ * worktree or, with `--branch`, in the main checkout, which must be clean.
+ * @param mainRoot - The main checkout.
+ * @param branch - The branch.
+ * @param branchMode - Whether `--branch` was given.
+ * @param worktreesDir - The config's folder for worktrees.
+ * @returns The mode and the folder.
+ * @throws StartError if the place is taken.
+ * @example choosePlace(root, "feat/42-x", false, ".claude/worktrees")
+ */
+export function choosePlace(mainRoot, branch, branchMode, worktreesDir) {
+    const at = checkedOutAt(mainRoot, branch);
+    if (at !== null) {
+        const mode = at === mainRoot ? "branch" : "worktree";
+        if (branchMode && mode === "worktree")
+            throw new StartError(`branch ${branch} is already in the worktree ${at}; run without --branch.`);
+        return { mode, workDir: at };
+    }
+    if (branchMode) {
+        if (!isClean(mainRoot))
+            throw new StartError("the main checkout has uncommitted changes; commit or stash them first. No stash is made.");
+        return { mode: "branch", workDir: mainRoot };
+    }
+    const workDir = join(mainRoot, worktreesDir, dirName(branch));
+    if (existsSync(workDir))
+        throw new StartError(`${workDir} already exists and is not a worktree of ${branch}; check it by hand.`);
+    return { mode: "worktree", workDir };
+}
+/**
+ * Runs git and stops with the message if it fails.
+ * @param cwd - Where.
+ * @param args - The arguments.
+ * @param what - What failed, for the message.
+ * @throws StartError if git fails.
+ */
+function mustGit(cwd, args, what) {
+    const result = git(cwd, args);
+    if (!result.ok)
+        throw new StartError(`${what}${result.err === "" ? "" : `: ${result.err}`}`);
+}
+/**
+ * Leaves the branch in its place: a new worktree (from the base, or on the existing
+ * branch), or the main checkout on it. A new branch in the main checkout needs it on the
+ * base and in step with origin.
+ * @param state - The start.
+ * @throws StartError if git cannot, with what to run in a terminal if a sandbox stops it.
+ * @example prepareBranch(state)
+ */
+export function prepareBranch(state) {
+    const { mainRoot, branch, base, found } = state;
+    if (state.mode === "worktree") {
+        if (existsSync(state.workDir))
+            return;
+        const args = found === null ? ["-b", branch, `origin/${base}`] : [branch];
+        const result = git(mainRoot, ["worktree", "add", "-q", state.workDir, ...args]);
+        if (!result.ok)
+            throw new StartError(`could not create the worktree: ${result.err}. If a sandbox stopped it, run in a terminal: ${again(state.options.number, "--yes")}`);
+        return;
+    }
+    if (currentBranch(mainRoot) === branch)
+        return;
+    if (!isClean(mainRoot))
+        throw new StartError("the main checkout has uncommitted changes; commit or stash them first. No stash is made.");
+    if (found !== null)
+        return mustGit(mainRoot, ["checkout", "-q", branch], `could not check out ${branch}`);
+    if (currentBranch(mainRoot) !== base)
+        throw new StartError(`the main checkout is not on ${base}.`);
+    if (git(mainRoot, ["rev-list", "--count", `origin/${base}..${base}`]).out !== "0")
+        throw new StartError(`local ${base} has commits that are not in origin/${base}; sort it out by hand.`);
+    mustGit(mainRoot, ["merge", "-q", "--ff-only", `origin/${base}`], `local ${base} diverged from origin/${base}`);
+    mustGit(mainRoot, ["checkout", "-q", "-b", branch], `could not create ${branch}`);
+}
+/**
+ * Turns into `Part of` the open PRs of other branches that closed the issue, because it
+ * now has more than one branch. Never stops: a PR it cannot edit gets a warning.
+ * @param state - The start.
+ */
+async function markOthersPartOf(state) {
+    const { repo, number } = state.options;
+    for (const other of openPrsElsewhere(state.work.prs, state.branch)) {
+        try {
+            const pr = await getPr(repo, other);
+            if (pr === null)
+                continue;
+            const body = bodyToPartOf(pr.body, number);
+            if (body !== pr.body)
+                await updatePr(repo, other, { body });
+        }
+        catch {
+            warn(state.out, `could not turn PR #${other} into Part of #${number}; edit it by hand.`);
+        }
+    }
+}
+/**
+ * The start commit, the push, the draft PR, the reopening of a closed one and the
+ * assignment, as far as they are missing. The commit takes nothing staged (`--only`). It
+ * runs before copying the included files and opening Claude, so the public trace is there
+ * even if what follows fails.
+ * @param state - The start.
+ * @returns The PR's number.
+ * @throws StartError if the commit, the push or the PR fail.
+ * @example await publish(state)
+ */
+export async function publish(state) {
+    const { workDir, branch, options } = state;
+    const commit = needsStartCommit(state);
+    if (commit) {
+        const message = fill(options.config.start.commitMessage, { number: String(options.number) });
+        mustGit(workDir, ["commit", "-q", "--allow-empty", "--only", "-m", message], "could not make the start commit");
+    }
+    if (commit || !onOrigin(workDir, branch))
+        mustGit(workDir, ["push", "-q", "-u", "origin", branch], `could not push ${branch}`);
+    if (!git(workDir, ["rev-parse", "-q", "--verify", "@{u}"]).ok)
+        git(workDir, ["branch", "-q", `--set-upstream-to=origin/${branch}`, branch]);
+    let number = state.pr?.number ?? null;
+    if (number === null) {
+        const created = await createPr(options.repo, {
+            head: branch,
+            base: state.base,
+            title: state.issue.title,
+            body: prBody(options.config.start.prBody, options.number, state.kind),
+            draft: true,
+        });
+        state.out.stdout(`${created.url}\n`);
+        number = created.number;
+        if (state.kind === "part")
+            await markOthersPartOf(state);
+    }
+    if (state.pr?.state === "CLOSED")
+        await updatePr(options.repo, number, { state: "open" });
+    if (state.issue.assignees.length === 0) {
+        try {
+            await assign(options.repo, options.number, ["@me"]);
+        }
+        catch {
+            warn(state.out, `could not assign issue #${options.number} to you.`);
+        }
+    }
+    return number;
+}
+/**
+ * The paths that match a pattern of `.worktreeinclude`, relative to the folder. Each
+ * segment may have `*`, `?` or `[…]`, like the shell; names starting with `.` match only
+ * a pattern that starts with `.`.
+ * @param root - The folder.
+ * @param pattern - The pattern.
+ * @returns The paths that exist.
+ */
+function expand(root, pattern) {
+    let paths = [""];
+    for (const segment of pattern.split("/").filter((part) => part !== "")) {
+        if (!GLOB.test(segment)) {
+            paths = paths.map((path) => join(path, segment)).filter((path) => existsSync(join(root, path)));
+            continue;
+        }
+        const source = segment.replace(/[.+^${}()|\\]/g, "\\$&").replaceAll("*", ".*").replaceAll("?", ".");
+        const matcher = new RegExp(`^${source}$`);
+        paths = paths.flatMap((path) => {
+            const dir = join(root, path);
+            if (!existsSync(dir))
+                return [];
+            return readdirSync(dir)
+                .filter((name) => matcher.test(name) && (!name.startsWith(".") || segment.startsWith(".")))
+                .map((name) => join(path, name));
+        });
+    }
+    return paths.filter((path) => path !== "");
+}
+/**
+ * Copies to a new worktree the files of `.worktreeinclude` it lacks, like `claude
+ * --worktree` does and `git worktree add` does not: only files git ignores (the ones a
+ * checkout cannot bring, like credentials), keeping their permissions and never
+ * overwriting.
+ * @param from - The main checkout.
+ * @param to - The worktree.
+ * @param out - Where a failed copy is reported.
+ * @example copyWorktreeIncludes(root, wt, out)
+ */
+export function copyWorktreeIncludes(from, to, out) {
+    const list = join(from, WORKTREE_INCLUDE);
+    if (!existsSync(list))
+        return;
+    for (const raw of readFileSync(list, "utf8").split("\n")) {
+        const pattern = raw.replace(/\r$/, "").trim();
+        if (pattern === "" || pattern.startsWith("#"))
+            continue;
+        let files;
+        try {
+            files = expand(from, pattern);
+        }
+        catch {
+            warn(out, `skipping "${pattern}" of ${WORKTREE_INCLUDE}: it is not a valid pattern.`);
+            continue;
+        }
+        for (const file of files) {
+            if (existsSync(join(to, file)) || !git(from, ["check-ignore", "-q", file]).ok)
+                continue;
+            try {
+                mkdirSync(dirname(join(to, file)), { recursive: true });
+                cpSync(join(from, file), join(to, file), { recursive: true });
+            }
+            catch {
+                warn(out, `could not copy ${file} to the worktree.`);
+            }
+        }
+    }
+}
+/** Ignored files named at most in the question before deleting a worktree. */
+const MAX_LISTED = 5;
+/**
+ * The ignored files of a worktree, which `git worktree remove` deletes and a clean status
+ * does not show: local notes, a local database, `settings.local.json`.
+ * @param workDir - The worktree.
+ * @returns Their paths (a folder counts once).
+ */
+function ignoredFiles(workDir) {
+    return gitLines(workDir, ["ls-files", "--others", "--ignored", "--exclude-standard", "--directory"]);
+}
+/**
+ * The reason not to clean up after a merged PR, or null if it can be.
+ * @param state - The start.
+ * @param lock - The worktree lock.
+ * @param head - The merged PR's head.
+ * @returns The message, or null.
+ */
+function keepReason(state, lock, head) {
+    if (lock.shared)
+        return "The PR was merged, but another session uses the worktree: not offering to delete it.";
+    if (!isClean(state.workDir))
+        return `The PR was merged, but ${state.workDir} has uncommitted changes: deleting nothing.`;
+    if (!safeToDelete(state.mainRoot, state.branch, head))
+        return `The PR was merged, but ${state.branch} has commits that are not in origin: deleting nothing.`;
+    return null;
+}
+/**
+ * After Claude: if the PR was merged and nothing would be lost, offers to delete the
+ * worktree and the branch (or, in the main checkout, to go back to the base); if not,
+ * says how to resume.
+ * @param state - The start.
+ * @param lock - The worktree lock (shared: another session uses it).
+ * @example await afterSession(state, lock)
+ */
+export async function afterSession(state, lock) {
+    const { out, mainRoot, branch, commonDir, base } = state;
+    const pr = await findPr(state.options.repo, branch).catch(() => null);
+    if (pr?.state !== "MERGED") {
+        out.stdout(`The session is saved. To resume it: ${again(state.options.number)}\n`);
+        return;
+    }
+    if (!hasLocal(mainRoot, branch)) {
+        forgetSession(commonDir, branch);
+        out.stdout(`The PR was merged and the local branch ${branch} no longer exists: nothing to delete.\n`);
+        return;
+    }
+    const reason = keepReason(state, lock, pr.head);
+    if (reason !== null)
+        return out.stdout(`${reason}\n`);
+    if (state.mode === "worktree") {
+        const where = relative(mainRoot, state.workDir);
+        const lost = ignoredFiles(state.workDir);
+        const also = lost.length === 0 ? "" : ` Its ignored files go too: ${lost.slice(0, MAX_LISTED).join(", ")}${lost.length > MAX_LISTED ? ", …" : ""}.`;
+        if (!(await confirm(out, `The PR was merged. Delete the worktree ${where} and the local branch ${branch}?${also}`)))
+            return;
+        await teardownWorktree(stepPlaceOf(state));
+        mustGit(mainRoot, ["worktree", "remove", state.workDir], `could not delete ${where} (its teardown already ran)`);
+    }
+    else {
+        if (!(await confirm(out, `The PR was merged. Go back to ${base} and delete the local branch ${branch}?`)))
+            return;
+        mustGit(mainRoot, ["checkout", "-q", base], `could not check out ${base}`);
+        const updated = git(mainRoot, ["fetch", "-q", "origin"]).ok && git(mainRoot, ["merge", "-q", "--ff-only", `origin/${base}`]).ok;
+        if (!updated)
+            warn(out, `could not update ${base}; do it by hand.`);
+    }
+    mustGit(mainRoot, ["branch", "-q", "-D", branch], `could not delete ${branch}`);
+    forgetSession(commonDir, branch);
+}