@jitsusama/agentic-harness.core 0.1.0

package/dist/work/events.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The bus contract between the working layer and its providers.
+ *
+ * A provider registers over the event bus rather than by importing
+ * the registry, so it can live in a different package from the host
+ * without either depending on the other's module graph. The names
+ * are versioned because the payload is a public contract; a breaking
+ * change ships as `:v2` beside the old one rather than quietly
+ * changing what `:v1` means.
+ *
+ * The names are owned by the domain, `work:`, not by whichever
+ * extension happens to host it. An event named after an extension
+ * makes every other extension depend on that one's continued
+ * existence, which is the coupling the bus is here to avoid.
+ *
+ * Both directions of the handshake matter. The host emits
+ * {@link WORK_READY} when its registry is live, and a provider
+ * listens for it so it can re-register after the host reloads. A
+ * provider also emits {@link WORK_REGISTER_TREE_PROVIDER} on its own
+ * activation, in case the host was already up. Either order works,
+ * and both are idempotent because registration replaces by id.
+ *
+ * A consumer needs the same courtesy for the opposite reason. The
+ * bus does not replay, so a consumer that activated after the host
+ * missed the announcement and has no way to know it happened.
+ * {@link WORK_REQUEST} is how it asks; the host answers by
+ * announcing itself again. Load order therefore decides nothing,
+ * which is the point: an extension cannot choose when it is loaded
+ * relative to another.
+ */
+import type { TreeBroker, TreeProvider } from "./broker.js";
+/** Emitted by the host once its registry accepts providers. */
+export declare const WORK_READY = "work:ready:v1";
+/** Emitted by a provider to register itself with the host. */
+export declare const WORK_REGISTER_TREE_PROVIDER = "work:tree-provider:register:v1";
+/**
+ * Emitted by a consumer asking the host to announce itself, for when
+ * the consumer loaded second and missed {@link WORK_READY}.
+ */
+export declare const WORK_REQUEST = "work:request:v1";
+/**
+ * Emitted before reclaiming trees, asking who else holds one.
+ *
+ * The working layer is not the only thing that cuts a worktree. A
+ * quest holds trees against a piece of work and knows nothing about
+ * this broker's memory, and any other package may do the same. From
+ * git's side those are indistinguishable from a tree somebody leaked:
+ * the directory is there, the broker has no record, and every check
+ * short of asking says abandoned.
+ *
+ * So reclamation asks first, and anything holding trees answers by
+ * pushing its paths onto {@link TreeClaims.paths}. Silence is the
+ * dangerous default here rather than the safe one, which is why this
+ * is a broadcast question and not a lookup against a registry: an
+ * owner that never registered still gets to speak, and an owner that
+ * is not loaded cannot be spoken for.
+ */
+export declare const WORK_TREE_CLAIMS = "work:tree-claims:v1";
+/** What holders write their trees into, in answer to the question. */
+export interface TreeClaims {
+    /**
+     * Every tree some other substrate is holding.
+     *
+     * Appended to rather than returned, because there is no telling how
+     * many holders exist and a handler that replaced this would silently
+     * drop the answers of everything that ran before it.
+     */
+    paths: string[];
+}
+/**
+ * What the host hands out over {@link WORK_READY}.
+ *
+ * Adding a member to this, or to a type it hands back, is not the
+ * breaking change the version tag is for. A consumer that does not
+ * know about a member cannot call it, so every existing consumer
+ * keeps working unchanged; what breaks is a consumer calling a member
+ * an older host does not have, and that consumer is the one that has
+ * to be careful, since a version bump would only turn a missing
+ * method into a host it never hears from at all.
+ *
+ * Removing a member, renaming one, or changing what one returns is
+ * the breaking kind, and that is what ships as `:v2`.
+ */
+export interface WorkApi {
+    /** Register a tree provider. Replaces one with the same id. */
+    registerTreeProvider(provider: TreeProvider): void;
+    /** Ids of every registered provider, most specific first. */
+    listTreeProviders(): readonly string[];
+    /**
+     * The host's own broker.
+     *
+     * Shared rather than rebuilt, so a consumer works against the
+     * same held trees the host does. A consumer with its own broker
+     * would hold a second set of trees for the same commits, cut
+     * them twice, and release each other's out from under them.
+     */
+    broker(): TreeBroker;
+}

package/dist/work/events.js

@@ -0,0 +1,57 @@
+/**
+ * The bus contract between the working layer and its providers.
+ *
+ * A provider registers over the event bus rather than by importing
+ * the registry, so it can live in a different package from the host
+ * without either depending on the other's module graph. The names
+ * are versioned because the payload is a public contract; a breaking
+ * change ships as `:v2` beside the old one rather than quietly
+ * changing what `:v1` means.
+ *
+ * The names are owned by the domain, `work:`, not by whichever
+ * extension happens to host it. An event named after an extension
+ * makes every other extension depend on that one's continued
+ * existence, which is the coupling the bus is here to avoid.
+ *
+ * Both directions of the handshake matter. The host emits
+ * {@link WORK_READY} when its registry is live, and a provider
+ * listens for it so it can re-register after the host reloads. A
+ * provider also emits {@link WORK_REGISTER_TREE_PROVIDER} on its own
+ * activation, in case the host was already up. Either order works,
+ * and both are idempotent because registration replaces by id.
+ *
+ * A consumer needs the same courtesy for the opposite reason. The
+ * bus does not replay, so a consumer that activated after the host
+ * missed the announcement and has no way to know it happened.
+ * {@link WORK_REQUEST} is how it asks; the host answers by
+ * announcing itself again. Load order therefore decides nothing,
+ * which is the point: an extension cannot choose when it is loaded
+ * relative to another.
+ */
+/** Emitted by the host once its registry accepts providers. */
+export const WORK_READY = "work:ready:v1";
+/** Emitted by a provider to register itself with the host. */
+export const WORK_REGISTER_TREE_PROVIDER = "work:tree-provider:register:v1";
+/**
+ * Emitted by a consumer asking the host to announce itself, for when
+ * the consumer loaded second and missed {@link WORK_READY}.
+ */
+export const WORK_REQUEST = "work:request:v1";
+/**
+ * Emitted before reclaiming trees, asking who else holds one.
+ *
+ * The working layer is not the only thing that cuts a worktree. A
+ * quest holds trees against a piece of work and knows nothing about
+ * this broker's memory, and any other package may do the same. From
+ * git's side those are indistinguishable from a tree somebody leaked:
+ * the directory is there, the broker has no record, and every check
+ * short of asking says abandoned.
+ *
+ * So reclamation asks first, and anything holding trees answers by
+ * pushing its paths onto {@link TreeClaims.paths}. Silence is the
+ * dangerous default here rather than the safe one, which is why this
+ * is a broadcast question and not a lookup against a registry: an
+ * owner that never registered still gets to speak, and an owner that
+ * is not loaded cannot be spoken for.
+ */
+export const WORK_TREE_CLAIMS = "work:tree-claims:v1";

package/dist/work/history.d.ts

@@ -0,0 +1,69 @@
+/**
+ * What a tree currently holds, and whether anything may move it.
+ *
+ * The working layer needs this before it re-points a tree, because
+ * stepping through a stack means checking a different commit out of
+ * a directory somebody may be working in. Overwriting a modified
+ * file is bad; overwriting an untracked one is unrecoverable, so an
+ * untracked file counts as work here rather than as noise.
+ */
+import { type Exec } from "../exec/index.js";
+import type { LocalBranch, WorktreeOnDisk } from "./tidy.js";
+/** One path git reports as changed, and how. */
+export interface ChangedPath {
+    path: string;
+    /** Staged for commit, as opposed to modified in the tree. */
+    staged: boolean;
+    kind: "modified" | "added" | "deleted" | "renamed" | "untracked";
+}
+/** What a tree holds beyond its last commit. */
+export interface WorkingState {
+    clean: boolean;
+    changed: readonly ChangedPath[];
+}
+/**
+ * Where a tree points.
+ *
+ * `branch` is absent rather than empty when the tree is detached. A
+ * snapshot is detached by design, so inventing a name would make
+ * every snapshot look like a branch tree.
+ */
+export interface TreeHead {
+    commit: string;
+    branch?: string;
+}
+/** Reading a tree's current state. */
+export interface WorkHistory {
+    status(treePath: string): Promise<WorkingState>;
+    head(treePath: string): Promise<TreeHead>;
+    /**
+     * Every local branch, with what trunk and the remote say about it.
+     *
+     * Reported rather than acted on: deciding what is spent is
+     * {@link tidyPlan}'s job, and it needs all three facts together to
+     * tell a squash merge from lost work.
+     */
+    branches(treePath: string, trunk: string): Promise<LocalBranch[]>;
+    /**
+     * Every worktree git tracks for this repo, with what is in each.
+     *
+     * Reported rather than acted on, for the same reason as
+     * {@link branches}: whether a tree has been left behind is
+     * {@link orphanedTrees}'s decision, and it needs the merge state and
+     * the dirty state together to tell an abandoned tree from the only
+     * copy of somebody's work.
+     */
+    worktrees(treePath: string, trunk: string): Promise<WorktreeOnDisk[]>;
+}
+/** Read a tree's state with plain git. */
+export declare function createGitHistory(deps: {
+    exec: Exec;
+}): WorkHistory;
+/**
+ * Why a tree may not be re-pointed, or nothing if it may.
+ *
+ * Returns the sentence rather than a boolean, because a refusal that
+ * does not say what is in the way leaves the person to go and look,
+ * which is the entire cost of refusing.
+ */
+export declare function blocksRepoint(state: WorkingState): string | undefined;

package/dist/work/history.js

@@ -0,0 +1,174 @@
+/**
+ * What a tree currently holds, and whether anything may move it.
+ *
+ * The working layer needs this before it re-points a tree, because
+ * stepping through a stack means checking a different commit out of
+ * a directory somebody may be working in. Overwriting a modified
+ * file is bad; overwriting an untracked one is unrecoverable, so an
+ * untracked file counts as work here rather than as noise.
+ */
+import { run } from "../exec/index.js";
+import { displayPath } from "../ui/path.js";
+/** Porcelain v1 status codes, mapped to what they mean. */
+const KIND = {
+    M: "modified",
+    A: "added",
+    D: "deleted",
+    R: "renamed",
+    C: "added",
+    U: "modified",
+};
+/**
+ * Read one porcelain v1 line.
+ *
+ * The format is two status columns then a space then the path, and a
+ * rename carries both names as `old -> new`. The new name is the one
+ * that matters: it is what is on disk, and what a re-point would
+ * overwrite.
+ */
+function parseLine(line) {
+    if (line.length < 4)
+        return undefined;
+    const [x, y] = [line[0], line[1]];
+    const raw = line.slice(3);
+    const path = raw.includes(" -> ") ? raw.split(" -> ")[1] : raw;
+    if (path === undefined || path === "")
+        return undefined;
+    if (x === "?" && y === "?") {
+        return { path, staged: false, kind: "untracked" };
+    }
+    const staged = x !== " " && x !== "?";
+    const code = staged ? x : y;
+    const kind = code === undefined ? undefined : KIND[code];
+    if (kind === undefined)
+        return undefined;
+    return { path, staged, kind };
+}
+/** Read a tree's state with plain git. */
+export function createGitHistory(deps) {
+    return {
+        async status(treePath) {
+            const out = await run(deps.exec, "git", ["-C", treePath, "status", "--porcelain=v1", "--untracked-files=all"], `Reading what ${displayPath(treePath)} holds`);
+            const changed = out
+                .split("\n")
+                .map((line) => parseLine(line))
+                .filter((entry) => entry !== undefined);
+            return { clean: changed.length === 0, changed };
+        },
+        async head(treePath) {
+            const commit = (await run(deps.exec, "git", ["-C", treePath, "rev-parse", "HEAD"], `Reading where ${displayPath(treePath)} points`)).trim();
+            // A detached tree makes this fail rather than answer, which
+            // is the answer: there is no branch to name.
+            const branch = await deps.exec("git", [
+                "-C",
+                treePath,
+                "symbolic-ref",
+                "--short",
+                "HEAD",
+            ]);
+            if (branch.code !== 0)
+                return { commit };
+            const name = branch.stdout.trim();
+            return name === "" ? { commit } : { commit, branch: name };
+        },
+        async branches(treePath, trunk) {
+            // One pass for the whole picture. Asking `--merged` separately
+            // and joining the answers means two listings taken at different
+            // moments, and the join is on a name that can move between them.
+            const listed = await run(deps.exec, "git", [
+                "-C",
+                treePath,
+                "for-each-ref",
+                "--format=%(refname:short)\t%(upstream:short)\t%(upstream:track,nobracket)",
+                "refs/heads",
+            ], `Listing the branches in ${displayPath(treePath)}`);
+            const merged = new Set((await run(deps.exec, "git", [
+                "-C",
+                treePath,
+                "branch",
+                "--format=%(refname:short)",
+                "--merged",
+                trunk,
+            ], `Asking which branches ${trunk} already contains`))
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line !== ""));
+            return listed
+                .split("\n")
+                .map((line) => line.split("\t"))
+                .filter(([name]) => name !== undefined && name !== "")
+                .map(([name, upstream, track]) => ({
+                name: name,
+                mergedIntoTrunk: merged.has(name),
+                ...(upstream ? { tracking: upstream } : {}),
+                // Git spells a vanished upstream "gone" in the track field,
+                // which is the only place it says so without a fetch.
+                ...(track === "gone" ? { remoteGone: true } : {}),
+            }));
+        },
+        async worktrees(treePath, trunk) {
+            // Porcelain, because the human-readable listing puts the branch
+            // in square brackets and a detached tree in the same column, so
+            // parsing it means telling those apart by punctuation.
+            const listed = await run(deps.exec, "git", ["-C", treePath, "worktree", "list", "--porcelain"], `Listing the worktrees beside ${displayPath(treePath)}`);
+            const merged = new Set((await run(deps.exec, "git", [
+                "-C",
+                treePath,
+                "branch",
+                "--format=%(refname:short)",
+                "--merged",
+                trunk,
+            ], `Asking which branches ${trunk} already contains`))
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line !== ""));
+            // A porcelain record is a run of lines per tree, separated by a
+            // blank one: `worktree <path>`, then optionally `branch <ref>`
+            // or `detached`.
+            const trees = [];
+            for (const record of listed.split("\n\n")) {
+                let path;
+                let branch;
+                for (const line of record.split("\n")) {
+                    if (line.startsWith("worktree "))
+                        path = line.slice(9).trim();
+                    if (line.startsWith("branch ")) {
+                        branch = line
+                            .slice(7)
+                            .trim()
+                            .replace(/^refs\/heads\//, "");
+                    }
+                }
+                if (!path)
+                    continue;
+                // Asked per tree, because a dirty tree is the one refusal here
+                // that cannot be recovered from and no listing reports it.
+                const state = await this.status(path);
+                trees.push({
+                    path,
+                    ...(branch ? { branch } : {}),
+                    ...(state.clean ? {} : { dirty: true }),
+                    ...(branch && merged.has(branch) ? { mergedIntoTrunk: true } : {}),
+                });
+            }
+            return trees;
+        },
+    };
+}
+/** How many paths a refusal names before it summarises. */
+const NAMED_IN_REFUSAL = 5;
+/**
+ * Why a tree may not be re-pointed, or nothing if it may.
+ *
+ * Returns the sentence rather than a boolean, because a refusal that
+ * does not say what is in the way leaves the person to go and look,
+ * which is the entire cost of refusing.
+ */
+export function blocksRepoint(state) {
+    if (state.clean)
+        return undefined;
+    const named = state.changed.slice(0, NAMED_IN_REFUSAL).map((c) => c.path);
+    const rest = state.changed.length - named.length;
+    const tail = rest > 0 ? `, and ${rest} more` : "";
+    return `This tree is holding uncommitted work (${named.join(", ")}${tail}), so re-pointing it would throw that away. Commit it, stash it, or ask for a different tree.`;
+}

package/dist/work/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The working layer: branches, commits, trees and stacks.
+ *
+ * Reviewing a change and working on one are different jobs, and
+ * this is the second. It is deliberately not called `git`: git is
+ * one implementation of it, and on a stacked workflow the backend
+ * that tracks the stack knows things plain git cannot be asked.
+ *
+ * Only the trees question is answered so far: where a tree gets
+ * cut from, and whether one already on disk answers a fresh
+ * request. Both are here before the council moves across, because
+ * the council cannot become provider-agnostic while it is asking a
+ * forge-shaped question.
+ */
+export type { AskedRepo, TreeAsk, TreeRequestOutcome, } from "./ask.js";
+export { treeRequestFrom } from "./ask.js";
+export type { BranchOptions, CommitMessage, WorkAuthor, } from "./author.js";
+export { createGitAuthor, namingComplaints, safeBranchName, } from "./author.js";
+export type { HeldTree, TreeBroker, TreeProvider } from "./broker.js";
+export { createTreeBroker } from "./broker.js";
+export type { TreeClaims, WorkApi } from "./events.js";
+export { WORK_READY, WORK_REGISTER_TREE_PROVIDER, WORK_REQUEST, WORK_TREE_CLAIMS, } from "./events.js";
+export type { ChangedPath, TreeHead, WorkHistory, WorkingState, } from "./history.js";
+export { blocksRepoint, createGitHistory } from "./history.js";
+export type { TreeAmbiguous, TreeInPlay } from "./inplay.js";
+export { chooseTree, treeInPlay } from "./inplay.js";
+export { createTreeMemory, type TreeMemory } from "./memory.js";
+export type { Objection, PublishIntent, PublishReview, } from "./objection.js";
+export { cautionsFrom, refusalFrom, WORK_PUBLISH_CHECK, } from "./objection.js";
+export type { TreeProviderChoice, TreeProviderInfo } from "./provider.js";
+export { chooseTreeProvider } from "./provider.js";
+export { createGitTreeProvider } from "./providers/git.js";
+export type { PushOptions, PushOutcome, WorkPublisher } from "./publish.js";
+export { createGitPublisher } from "./publish.js";
+export type { RebaseOutcome, ResumeOutcome, WorkRebaser, } from "./rebase.js";
+export { createGitRebaser } from "./rebase.js";
+export type { ReclaimDeps, ReclaimedTree, ReclaimOutcome, } from "./reclaim.js";
+export { reclaimTrees } from "./reclaim.js";
+export { clearTreeProviders, listTreeProviders, registerTreeProvider, unregisterTreeProvider, } from "./register.js";
+export type { Faulted, ReorderPlan, ReparentStep, ReplayStep, RestackPlan, StackedBranch, StackFault, StackOrder, } from "./stack.js";
+export { descendantsOf, orderStack, planReorder, planRestack, reparentFault, } from "./stack.js";
+export type { ReplayResult, RestackOutcome, ShapeOutcome, SyncOutcome, WorkStacks, } from "./stacks.js";
+export { createGitStacks } from "./stacks.js";
+export type { SurveyRequest, SurveyTarget } from "./survey.js";
+export { surveyTarget } from "./survey.js";
+export type { Kept, LocalBranch, OrphanAsk, OrphanPlan, Reclaimable, Removable, Retained, TidyAsk, TidyPlan, WorktreeOnDisk, } from "./tidy.js";
+export { orphanedTrees, tidyPlan } from "./tidy.js";
+export type { TreeIdentity, TreeRequest, TreeSource } from "./tree.js";
+export { satisfies, treeIdentity, treeSource } from "./tree.js";

package/dist/work/index.js

@@ -0,0 +1,33 @@
+/**
+ * The working layer: branches, commits, trees and stacks.
+ *
+ * Reviewing a change and working on one are different jobs, and
+ * this is the second. It is deliberately not called `git`: git is
+ * one implementation of it, and on a stacked workflow the backend
+ * that tracks the stack knows things plain git cannot be asked.
+ *
+ * Only the trees question is answered so far: where a tree gets
+ * cut from, and whether one already on disk answers a fresh
+ * request. Both are here before the council moves across, because
+ * the council cannot become provider-agnostic while it is asking a
+ * forge-shaped question.
+ */
+export { treeRequestFrom } from "./ask.js";
+export { createGitAuthor, namingComplaints, safeBranchName, } from "./author.js";
+export { createTreeBroker } from "./broker.js";
+export { WORK_READY, WORK_REGISTER_TREE_PROVIDER, WORK_REQUEST, WORK_TREE_CLAIMS, } from "./events.js";
+export { blocksRepoint, createGitHistory } from "./history.js";
+export { chooseTree, treeInPlay } from "./inplay.js";
+export { createTreeMemory } from "./memory.js";
+export { cautionsFrom, refusalFrom, WORK_PUBLISH_CHECK, } from "./objection.js";
+export { chooseTreeProvider } from "./provider.js";
+export { createGitTreeProvider } from "./providers/git.js";
+export { createGitPublisher } from "./publish.js";
+export { createGitRebaser } from "./rebase.js";
+export { reclaimTrees } from "./reclaim.js";
+export { clearTreeProviders, listTreeProviders, registerTreeProvider, unregisterTreeProvider, } from "./register.js";
+export { descendantsOf, orderStack, planReorder, planRestack, reparentFault, } from "./stack.js";
+export { createGitStacks } from "./stacks.js";
+export { surveyTarget } from "./survey.js";
+export { orphanedTrees, tidyPlan } from "./tidy.js";
+export { satisfies, treeIdentity, treeSource } from "./tree.js";

package/dist/work/inplay.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Which held tree a call should act on when nobody said.
+ *
+ * Fifteen of the tool's actions take a tree, and until this existed every one of them
+ * had to be told which, every time, even for a session holding exactly one. The review
+ * side solved the same problem for changes and the browser solved it before that for
+ * sessions; this is the third turn of one idea, so it is written the same way.
+ *
+ * It is deliberately less willing to guess than the change version, and the difference
+ * is worth stating. There, several attached changes resolve to the most recent, because
+ * attaching one is how somebody says what they are working on, so recency is a
+ * statement of intent. Nothing here makes that statement: trees accumulate as you cut
+ * them, and the tool's actions include committing, pushing and replaying, where acting
+ * on the wrong one rewrites work in a directory nobody was looking at. So one tree is
+ * used and several is a question.
+ */
+/**
+ * The tree a call will act on.
+ *
+ * No note field, deliberately, and this is where it differs from the change version
+ * again. There, a note says which change was chosen, because a change is a thing you
+ * read and the answer need not mention it. Here every action already announces itself
+ * against the tree it acted on, as in `Recorded 3 paths in worktree-fix-410`, so a note
+ * would repeat what the next line says. A field nothing reads is worse than a missing
+ * one, because it does not present as missing.
+ */
+export interface TreeInPlay {
+    readonly key: string;
+}
+/** No single answer, so the caller has to choose. */
+export interface TreeAmbiguous {
+    readonly candidates: readonly string[];
+}
+/**
+ * Resolve the tree in play from what the caller said and what is held.
+ *
+ * An explicit name is never second-guessed, even when it matches nothing: somebody who
+ * names a tree means that tree, and a typo is better reported than quietly redirected
+ * to whatever else happens to be open.
+ */
+export declare function treeInPlay(asked: string | undefined, held: readonly string[]): TreeInPlay | TreeAmbiguous;
+/** Say what to choose between, when the choice cannot be made here. */
+export declare function chooseTree(candidates: readonly string[]): string;

package/dist/work/inplay.js

@@ -0,0 +1,42 @@
+/**
+ * Which held tree a call should act on when nobody said.
+ *
+ * Fifteen of the tool's actions take a tree, and until this existed every one of them
+ * had to be told which, every time, even for a session holding exactly one. The review
+ * side solved the same problem for changes and the browser solved it before that for
+ * sessions; this is the third turn of one idea, so it is written the same way.
+ *
+ * It is deliberately less willing to guess than the change version, and the difference
+ * is worth stating. There, several attached changes resolve to the most recent, because
+ * attaching one is how somebody says what they are working on, so recency is a
+ * statement of intent. Nothing here makes that statement: trees accumulate as you cut
+ * them, and the tool's actions include committing, pushing and replaying, where acting
+ * on the wrong one rewrites work in a directory nobody was looking at. So one tree is
+ * used and several is a question.
+ */
+/**
+ * Resolve the tree in play from what the caller said and what is held.
+ *
+ * An explicit name is never second-guessed, even when it matches nothing: somebody who
+ * names a tree means that tree, and a typo is better reported than quietly redirected
+ * to whatever else happens to be open.
+ */
+export function treeInPlay(asked, held) {
+    if (asked !== undefined)
+        return { key: asked };
+    const [only, ...rest] = held;
+    if (only === undefined)
+        return { candidates: held };
+    if (rest.length > 0)
+        return { candidates: held };
+    return { key: only };
+}
+/** Say what to choose between, when the choice cannot be made here. */
+export function chooseTree(candidates) {
+    if (candidates.length === 0) {
+        return ("No tree is held. Ask for one with work tree, naming the repo, the " +
+            "branch and what it is for.");
+    }
+    return (`Say which tree, by its key or its path. ${candidates.length} are held: ` +
+        `${candidates.join(", ")}.`);
+}

package/dist/work/memory.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Remembering the trees a session cut, so the next session can find them.
+ *
+ * The broker held its trees in an array, which is correct for exactly as long as
+ * the process lives. A worktree outlives the process by design, so the next
+ * session opened with the trees still on disk, git still tracking them, and
+ * every verb answering "no held tree": not merely a listing that forgot, but
+ * commits stranded in a directory the tool could no longer reach, releasable
+ * only through the `git worktree` call the guide tells you never to make.
+ *
+ * No test could see it. A test builds a broker and uses it, which is one
+ * process; the fault needs two.
+ *
+ * The directory stays the source of truth for whether a tree exists, and this
+ * only supplies the identity a directory name cannot faithfully carry. When the
+ * two disagree the directory wins, because somebody who deletes a tree by hand
+ * has said something and a stale record has not.
+ *
+ * A record also says who cut it, which is a later addition and the reason
+ * anything is ever reclaimed. Without it "remembered" and "held" were one set,
+ * so every tree ever cut answered "something still holds it" forever: measured
+ * at 59 records and 649MB on one machine, growing by a snapshot per review
+ * round.
+ */
+import { type Owner, type ProcessFacts } from "../process/index.js";
+import type { HeldTree } from "./broker.js";
+/** Somewhere to write down what was cut. */
+export interface TreeMemory {
+    /** Write a tree down, so a later session can find it. */
+    remember(held: HeldTree): void;
+    /**
+     * Write a tree down as held by this session.
+     *
+     * Separate from `remember`, which stays exactly as literal as it was: a
+     * caller replaying a record, or a test constructing one, must be able to
+     * write what it means rather than have this process's identity stamped
+     * over it.
+     */
+    rememberHeldByUs(held: HeldTree, facts?: ProcessFacts): Promise<void>;
+    /** Forget one, once it has genuinely gone. */
+    forget(path: string): void;
+    /** Every tree written down that is still on disk. */
+    recall(): readonly HeldTree[];
+    /**
+     * Those a running session still holds.
+     *
+     * Distinct from `recall`, which must keep returning a dead session's
+     * trees: reusing the snapshot a finished round left behind is the point
+     * of a shareable tree, and it is what lets six reviewers of one commit
+     * share one directory. This is the narrower question tidy asks, and only
+     * tidy: whether taking the directory away would pull it out from under
+     * somebody.
+     */
+    heldNow(facts?: ProcessFacts): Promise<readonly HeldTree[]>;
+    /**
+     * Those whose record does not say who cut them.
+     *
+     * A subset of what `heldNow` returns, since an unattributable tree is
+     * counted as held: this names them so a caller can report them as the
+     * decision they are rather than as a claim somebody made.
+     */
+    unattributed(): readonly HeldTree[];
+    /**
+     * Who else is standing in this tree, this session excluded.
+     *
+     * Only holders still running count, since a dead one is not
+     * somebody a release has to be careful of. Empty for a tree nobody
+     * else holds and for one whose record names nobody, which is right
+     * for a release: the caller asked to take its own tree down, and
+     * only another live session is a reason not to.
+     */
+    otherHolders(path: string, facts?: ProcessFacts): Promise<readonly Owner[]>;
+    /** Take this session off a tree's record, leaving the record. */
+    forgetUsAsHolder(path: string, facts?: ProcessFacts): Promise<void>;
+}
+/**
+ * Remember trees in a directory of small files, one per tree.
+ *
+ * A file per tree rather than one index, for the same reason the attachment
+ * store is shaped this way: two sessions cutting trees at once both write, and
+ * the loser of a read-modify-write race on a single index is a tree nobody can
+ * find. Separate files cannot collide, since the name is the tree's own key.
+ */
+export declare function createTreeMemory(dir: string): TreeMemory;