@jitsusama/agentic-harness.core 0.1.0

package/dist/work/tidy.d.ts

@@ -0,0 +1,147 @@
+/**
+ * What is safe to remove once work has landed.
+ *
+ * Cleaning up after a merge is done by hand today, and the cost of not
+ * doing it is quiet: stale locals and tracking refs pile up until a
+ * branch listing stops being readable. The cost of doing it carelessly
+ * is not quiet at all, so nothing here removes anything. It decides
+ * what could go and, for everything it will not touch, says why.
+ *
+ * It has to be a decision rather than a command because landing is not
+ * an instant. A change handed to a merge queue is merged later, from
+ * somewhere else, so the moment a caller asks to merge is exactly the
+ * moment nothing is cleanable yet.
+ */
+/** One worktree, as git describes it. */
+export interface WorktreeOnDisk {
+    path: string;
+    /** The branch checked out there, when one is. */
+    branch?: string;
+    /** Whether it holds changes that are not committed anywhere. */
+    dirty?: boolean;
+    /** Whether trunk already contains that branch's commits. */
+    mergedIntoTrunk?: boolean;
+}
+/** What is known when asking which trees were left behind. */
+export interface OrphanAsk {
+    /** The checkout the worktrees hang off, which is never an orphan. */
+    mainPath: string;
+    /** Every worktree git knows about, the main checkout included. */
+    worktrees: WorktreeOnDisk[];
+    /**
+     * Paths the broker still remembers holding.
+     *
+     * Must be comparable with the worktree paths above, which means the
+     * caller resolves both through the same lens before asking. The two
+     * arrive from different places, git and the broker's own record, and
+     * git reports a path with every symlink resolved: on macOS a tree
+     * under the system temp comes back as `/private/var/...` where the
+     * broker wrote `/var/...`. Compared raw, a tree somebody is actively
+     * holding reads as abandoned, which is the one wrong answer here
+     * that costs work.
+     */
+    remembered: readonly string[];
+    /**
+     * Those whose record says nothing about who cut them.
+     *
+     * Every record written before the broker stamped an owner is one of
+     * these, and there is no sound way to attribute one after the fact.
+     * The obvious rules all fail. The machine has not rebooted since
+     * they were written, so nothing can be ruled out that way, and any
+     * age threshold is a guess that takes a live session's tree the
+     * first time somebody leaves one open over a weekend.
+     *
+     * So they are neither held nor reclaimable: they are reported as a
+     * decision for a person, which is the honest answer and is also
+     * self-clearing, since a tree taken this way is gone and every tree
+     * cut from now on carries an owner.
+     */
+    unattributed?: readonly string[];
+}
+/** A tree nothing claims any more, and what was in it. */
+export interface Reclaimable {
+    path: string;
+    branch?: string;
+}
+/** A tree being left alone, and the reason. */
+export interface Retained {
+    path: string;
+    why: string;
+    /** Set when this is a judgement call rather than a refusal. */
+    decide?: boolean;
+}
+/** What reclaiming would do, and what it would decline to do. */
+export interface OrphanPlan {
+    reclaimable: Reclaimable[];
+    retained: Retained[];
+}
+/**
+ * Which trees have been left behind, without reclaiming any of them.
+ *
+ * A worktree outlives the process that cut it, which is the point of
+ * one, and it also outlives a process that was killed before it could
+ * put the tree back. Nothing then owns it: the broker's memory has no
+ * record, so every verb answers "no held tree", while git still tracks
+ * it and the disk still carries it. Fifteen accumulated in one repo
+ * over four months, all of them from an extension that no longer
+ * exists, which is what this looks like when nobody is watching.
+ *
+ * The order of the questions is the safety, as with {@link tidyPlan}.
+ * The checkout itself and anything still claimed are excluded
+ * before merge state is considered, so no confusion further down can
+ * propose removing either.
+ */
+export declare function orphanedTrees(ask: OrphanAsk): OrphanPlan;
+/** One local branch, as git describes it. */
+export interface LocalBranch {
+    name: string;
+    /** Whether trunk already contains this branch's commits. */
+    mergedIntoTrunk: boolean;
+    /** The upstream it tracks, when it tracks one. */
+    tracking?: string;
+    /** Whether that upstream has gone from the remote. */
+    remoteGone?: boolean;
+}
+/** What the working layer knows when it is asked to tidy up. */
+export interface TidyAsk {
+    trunk: string;
+    /** The branch currently checked out in the tree. */
+    current: string;
+    branches: LocalBranch[];
+    /** Branches the stack is tracking, which must be forgotten too. */
+    tracked?: string[];
+}
+/** A branch that can go, and what else goes with it. */
+export interface Removable {
+    branch: string;
+    /** Whether the stack still lists it, so it needs untracking too. */
+    alsoUntrack: boolean;
+}
+/** A branch being left alone, and the reason. */
+export interface Kept {
+    branch: string;
+    why: string;
+    /**
+     * Whether this is a judgement call rather than a refusal.
+     *
+     * Set when the work looks landed but git cannot prove it, which is
+     * what a squash merge produces and the one case where a person has
+     * to decide. Everything else here is simply not ready to go.
+     */
+    decide?: boolean;
+}
+/** What tidying up would do, and what it would decline to do. */
+export interface TidyPlan {
+    removable: Removable[];
+    keeping: Kept[];
+    /** Whether any tracking ref points at a branch the remote dropped. */
+    prunable: boolean;
+}
+/**
+ * Work out what has been spent, without spending anything.
+ *
+ * The order of the questions is the safety. Trunk and the checked-out
+ * branch are excluded before merge state is considered at all, so no
+ * amount of confusion further down can propose deleting either.
+ */
+export declare function tidyPlan(ask: TidyAsk): TidyPlan;

package/dist/work/tidy.js

@@ -0,0 +1,136 @@
+/**
+ * What is safe to remove once work has landed.
+ *
+ * Cleaning up after a merge is done by hand today, and the cost of not
+ * doing it is quiet: stale locals and tracking refs pile up until a
+ * branch listing stops being readable. The cost of doing it carelessly
+ * is not quiet at all, so nothing here removes anything. It decides
+ * what could go and, for everything it will not touch, says why.
+ *
+ * It has to be a decision rather than a command because landing is not
+ * an instant. A change handed to a merge queue is merged later, from
+ * somewhere else, so the moment a caller asks to merge is exactly the
+ * moment nothing is cleanable yet.
+ */
+/**
+ * Which trees have been left behind, without reclaiming any of them.
+ *
+ * A worktree outlives the process that cut it, which is the point of
+ * one, and it also outlives a process that was killed before it could
+ * put the tree back. Nothing then owns it: the broker's memory has no
+ * record, so every verb answers "no held tree", while git still tracks
+ * it and the disk still carries it. Fifteen accumulated in one repo
+ * over four months, all of them from an extension that no longer
+ * exists, which is what this looks like when nobody is watching.
+ *
+ * The order of the questions is the safety, as with {@link tidyPlan}.
+ * The checkout itself and anything still claimed are excluded
+ * before merge state is considered, so no confusion further down can
+ * propose removing either.
+ */
+export function orphanedTrees(ask) {
+    const held = new Set(ask.remembered);
+    const unattributed = new Set(ask.unattributed ?? []);
+    const reclaimable = [];
+    const retained = [];
+    for (const tree of ask.worktrees) {
+        const keep = (why, decide) => {
+            retained.push({ path: tree.path, why, ...(decide ? { decide } : {}) });
+        };
+        if (tree.path === ask.mainPath) {
+            keep("it is the checkout the others hang off");
+            continue;
+        }
+        if (held.has(tree.path)) {
+            // Not an orphan at all, and saying so matters: giving it back
+            // goes through whatever cut it, which knows things about taking
+            // a tree down that this does not. Deliberately vague about who
+            // holds it, because the broker is not the only one that can: a
+            // quest holds trees against a piece of work and answers the
+            // same question. Naming the broker would be wrong for those.
+            keep("something still holds it, so give it back rather than reclaiming it");
+            continue;
+        }
+        if (tree.dirty) {
+            // A refusal, not a decision. An uncommitted change exists in
+            // exactly one place and removing the tree ends it.
+            keep("it has uncommitted changes, which exist nowhere else");
+            continue;
+        }
+        if (unattributed.has(tree.path)) {
+            // Third, and each step of the order is a safety. Above a claim
+            // it downgraded somebody saying they want this now to nobody
+            // can say, which put a freshly claimed tree into the list a
+            // person is invited to clear. Above the dirty check it offered
+            // up a tree holding uncommitted work as a judgement call, and
+            // that work exists in exactly one place.
+            //
+            // Everything left here is unclaimed and committed, so the only
+            // thing missing is who wanted it.
+            keep("nothing recorded who cut it, so nothing can say whether a running session still wants it", true);
+            continue;
+        }
+        if (tree.mergedIntoTrunk) {
+            reclaimable.push({
+                path: tree.path,
+                ...(tree.branch ? { branch: tree.branch } : {}),
+            });
+            continue;
+        }
+        // The same ambiguity a branch has, for the same reason, and named
+        // the same way rather than guessed at.
+        keep(`nothing holds it, but ${tree.branch ?? "its branch"} is not contained in trunk, so it is either a squash merge or the only copy of that work`, true);
+    }
+    return { reclaimable, retained };
+}
+/**
+ * Work out what has been spent, without spending anything.
+ *
+ * The order of the questions is the safety. Trunk and the checked-out
+ * branch are excluded before merge state is considered at all, so no
+ * amount of confusion further down can propose deleting either.
+ */
+export function tidyPlan(ask) {
+    const tracked = new Set(ask.tracked ?? []);
+    const removable = [];
+    const keeping = [];
+    for (const branch of ask.branches) {
+        const kept = (why, decide) => {
+            keeping.push({ branch: branch.name, why, ...(decide ? { decide } : {}) });
+        };
+        if (branch.name === ask.trunk) {
+            kept("it is the trunk");
+            continue;
+        }
+        if (branch.name === ask.current) {
+            // Git refuses this anyway, and hearing why from here beats
+            // hearing it from a command that has already deleted three
+            // other branches and then stopped.
+            kept("it is checked out here, so move off it first");
+            continue;
+        }
+        if (branch.mergedIntoTrunk) {
+            removable.push({
+                branch: branch.name,
+                alsoUntrack: tracked.has(branch.name),
+            });
+            continue;
+        }
+        if (branch.remoteGone) {
+            // The case worth slowing down for. A squash merge lands the
+            // work as a new commit, so the branch is not an ancestor of
+            // trunk and git will not call it merged, while the remote
+            // branch is gone because the merge deleted it. It looks
+            // exactly like a branch somebody deleted out from under
+            // unmerged work, and only a person can tell the two apart.
+            kept(`its upstream ${branch.tracking ?? "branch"} is gone but ${ask.trunk} does not contain it, which is what a squash merge looks like and also what losing work looks like`, true);
+            continue;
+        }
+        kept(`${ask.trunk} does not contain it yet`);
+    }
+    return {
+        removable,
+        keeping,
+        prunable: ask.branches.some((branch) => branch.remoteGone === true),
+    };
+}

package/dist/work/tree.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Where a tree for a change gets cut from.
+ *
+ * This exists because the answer used to be a guess. The review
+ * worktree provider resolved a source repo as
+ * `~/src/github.com/{owner}/{repo}`, which is correct on GitHub
+ * and silently wrong everywhere else: a change on another system
+ * resolves to a directory that does not exist, and the failure
+ * surfaces as a missing checkout rather than as the assumption it
+ * really is. A forge name baked into a path is the hardest kind of
+ * assumption to notice, because every test against that forge
+ * passes.
+ *
+ * So the question is answered from what the substrate already
+ * knows. A provider that resolved a change has already said where
+ * its repo is, locally or by remote, and a repo it could say
+ * neither about is reported as unplaceable rather than guessed at.
+ */
+import type { RepoLocator } from "../review/index.js";
+/**
+ * Where the source for a tree comes from.
+ *
+ * Three outcomes rather than a path or nothing, because the caller
+ * has to act differently on each: use it, fetch it first, or tell
+ * somebody it cannot be found. Collapsing the last two loses the
+ * difference between work to do and a question to ask.
+ */
+export type TreeSource = 
+/** A checkout already on disk; cut the tree from here. */
+{
+    kind: "checkout";
+    path: string;
+}
+/** Known only by remote, so it has to be fetched first. */
+ | {
+    kind: "clone";
+    remoteUrl: string;
+}
+/** Neither known. Say so; do not invent a path. */
+ | {
+    kind: "unknown";
+    repoKey: string;
+};
+/**
+ * Decide where a change's tree should be cut from.
+ *
+ * A local checkout wins over a remote, because it is already
+ * there and cutting a tree from it costs a fraction of a fetch.
+ */
+export declare function treeSource(repo: RepoLocator): TreeSource;
+/**
+ * What a tree is wanted for.
+ *
+ * Two lifecycles, not three. The review worktrees, the fix
+ * worktrees and the quest trees looked like three contracts, but
+ * the fix and quest cases differ only in what names them: both are
+ * a durable branch you edit in. What actually varies is what the
+ * tree is pinned to, and that changes the reuse rule.
+ *
+ * A `snapshot` is pinned to a commit and read rather than edited,
+ * so readers can share one. A `worktree` is pinned to a branch and
+ * expects to be committed in, so it belongs to one stream of work.
+ */
+export type TreeRequest = {
+    intent: "snapshot";
+    repo: RepoLocator;
+    purpose: string;
+    commit: string;
+    paths?: readonly string[];
+} | {
+    intent: "worktree";
+    repo: RepoLocator;
+    purpose: string;
+    branch: string;
+    baseBranch?: string;
+};
+/** What a tree is, for the purpose of reusing it. */
+export interface TreeIdentity {
+    /**
+     * Stable, filesystem-safe name for this tree. Safe to use as
+     * a directory component: repo keys carry colons and change
+     * labels carry slashes and hashes, and a key holding those
+     * either nests where nobody expected a directory or fails
+     * outright.
+     */
+    key: string;
+    /**
+     * Whether two callers wanting this same tree may be handed
+     * the same one. True for a snapshot, since reading does not
+     * disturb a reader. False for a worktree, because somebody is
+     * editing in it, and that is a property of the intent rather
+     * than a caller's judgement call.
+     */
+    shareable: boolean;
+}
+/**
+ * Work out what tree a request is asking for.
+ *
+ * A snapshot's identity carries its commit, so asking for another
+ * commit asks for another tree. A worktree's identity deliberately
+ * does not: the branch moves under it every time you commit, and
+ * an identity that moved with HEAD would orphan the tree you are
+ * working in on your first commit.
+ *
+ * Both are scoped to the repo, because a branch name and even a
+ * commit can appear in two repos and they are not the same tree.
+ *
+ * The `paths` a snapshot may narrow itself to are left out. Scoping
+ * is a provider's optimisation, not part of what the tree is;
+ * folding it in would fragment reuse per distinct file set.
+ */
+export declare function treeIdentity(request: TreeRequest): TreeIdentity;
+/**
+ * Whether a tree already held answers a fresh request.
+ *
+ * Compared by identity rather than field by field, so the reuse
+ * rule lives in one place and cannot drift between the caller that
+ * provisions and the caller that looks one up.
+ */
+export declare function satisfies(held: TreeIdentity, request: TreeRequest): boolean;

package/dist/work/tree.js

@@ -0,0 +1,69 @@
+/**
+ * Where a tree for a change gets cut from.
+ *
+ * This exists because the answer used to be a guess. The review
+ * worktree provider resolved a source repo as
+ * `~/src/github.com/{owner}/{repo}`, which is correct on GitHub
+ * and silently wrong everywhere else: a change on another system
+ * resolves to a directory that does not exist, and the failure
+ * surfaces as a missing checkout rather than as the assumption it
+ * really is. A forge name baked into a path is the hardest kind of
+ * assumption to notice, because every test against that forge
+ * passes.
+ *
+ * So the question is answered from what the substrate already
+ * knows. A provider that resolved a change has already said where
+ * its repo is, locally or by remote, and a repo it could say
+ * neither about is reported as unplaceable rather than guessed at.
+ */
+/**
+ * Decide where a change's tree should be cut from.
+ *
+ * A local checkout wins over a remote, because it is already
+ * there and cutting a tree from it costs a fraction of a fetch.
+ */
+export function treeSource(repo) {
+    if (repo.localPath)
+        return { kind: "checkout", path: repo.localPath };
+    if (repo.remoteUrl)
+        return { kind: "clone", remoteUrl: repo.remoteUrl };
+    return { kind: "unknown", repoKey: repo.key };
+}
+/** Characters that must not reach a directory name. */
+const UNSAFE_IN_PATH = /[^a-zA-Z0-9._-]+/g;
+function slug(value) {
+    return value.replace(UNSAFE_IN_PATH, "-");
+}
+/**
+ * Work out what tree a request is asking for.
+ *
+ * A snapshot's identity carries its commit, so asking for another
+ * commit asks for another tree. A worktree's identity deliberately
+ * does not: the branch moves under it every time you commit, and
+ * an identity that moved with HEAD would orphan the tree you are
+ * working in on your first commit.
+ *
+ * Both are scoped to the repo, because a branch name and even a
+ * commit can appear in two repos and they are not the same tree.
+ *
+ * The `paths` a snapshot may narrow itself to are left out. Scoping
+ * is a provider's optimisation, not part of what the tree is;
+ * folding it in would fragment reuse per distinct file set.
+ */
+export function treeIdentity(request) {
+    const repo = slug(request.repo.key);
+    if (request.intent === "snapshot") {
+        return { key: `snapshot-${repo}-${slug(request.commit)}`, shareable: true };
+    }
+    return { key: `worktree-${repo}-${slug(request.branch)}`, shareable: false };
+}
+/**
+ * Whether a tree already held answers a fresh request.
+ *
+ * Compared by identity rather than field by field, so the reuse
+ * rule lives in one place and cannot drift between the caller that
+ * provisions and the caller that looks one up.
+ */
+export function satisfies(held, request) {
+    return held.key === treeIdentity(request).key;
+}

package/dist/work/unattended.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Git, told that there is nobody here to ask.
+ *
+ * Found by driving `resume` and watching it never come back. `git rebase
+ * --continue` finishes a conflicted pick by running
+ * `git commit -F .git/rebase-merge/message -e`, and the `-e` means edit: git
+ * launched an editor and waited for a human on a stdin that no human was
+ * attached to. The tool sat there forever, and because the working layer never
+ * passed the caller's abort signal down to the child, there was no way to stop
+ * it either. Two faults, and the second is what turned a wrong answer into a
+ * wedged session.
+ *
+ * A worse property than the hang itself: the tree is left mid-rebase. Somebody
+ * who kills the session finds a repository in a state they did not ask for and
+ * no tool willing to talk about it, which is the exact situation the halt design
+ * exists to prevent.
+ *
+ * So every git call that can reach an editor says up front that there is not one.
+ * `true` exits zero without reading anything, so git accepts the message it
+ * already had, which is the message the commit is supposed to keep.
+ *
+ * That is the rebase family and not `commit`, which this layer always calls with
+ * `-m`: git never consults an editor when the message is on the command line, and
+ * flags that cannot change an outcome are noise at the call site. A passphrase
+ * prompt from a signing key is a real hang and a different problem, since the
+ * honest answer to it is not to disable signing. The abort signal covers that
+ * one.
+ */
+/**
+ * Git arguments with the editor turned off.
+ *
+ * Wrap the whole argument list rather than remembering to add flags at each call
+ * site, since the call that forgets is the one that hangs, and it hangs only when
+ * a rebase actually conflicts. That is a fault which passes every test and waits
+ * for somebody's real conflict to appear.
+ *
+ * These are global flags, so they go before the subcommand. Anything already
+ * global in the list, `-C` in particular, stays valid in any order beside them.
+ */
+export declare function unattended(args: readonly string[]): string[];

package/dist/work/unattended.js

@@ -0,0 +1,57 @@
+/**
+ * Git, told that there is nobody here to ask.
+ *
+ * Found by driving `resume` and watching it never come back. `git rebase
+ * --continue` finishes a conflicted pick by running
+ * `git commit -F .git/rebase-merge/message -e`, and the `-e` means edit: git
+ * launched an editor and waited for a human on a stdin that no human was
+ * attached to. The tool sat there forever, and because the working layer never
+ * passed the caller's abort signal down to the child, there was no way to stop
+ * it either. Two faults, and the second is what turned a wrong answer into a
+ * wedged session.
+ *
+ * A worse property than the hang itself: the tree is left mid-rebase. Somebody
+ * who kills the session finds a repository in a state they did not ask for and
+ * no tool willing to talk about it, which is the exact situation the halt design
+ * exists to prevent.
+ *
+ * So every git call that can reach an editor says up front that there is not one.
+ * `true` exits zero without reading anything, so git accepts the message it
+ * already had, which is the message the commit is supposed to keep.
+ *
+ * That is the rebase family and not `commit`, which this layer always calls with
+ * `-m`: git never consults an editor when the message is on the command line, and
+ * flags that cannot change an outcome are noise at the call site. A passphrase
+ * prompt from a signing key is a real hang and a different problem, since the
+ * honest answer to it is not to disable signing. The abort signal covers that
+ * one.
+ */
+/**
+ * Global git flags that guarantee a command cannot stop to ask a human.
+ *
+ * Both editors are named because git reaches for two different ones and only one
+ * of them is the commit message. `sequence.editor` presents a todo list, which
+ * an interactive rebase needs and nothing here asks for today. It is set anyway:
+ * the cost is two arguments nobody sees, and the failure it prevents is a
+ * process wedged with a repository half-rewritten.
+ */
+const NO_EDITOR = [
+    "-c",
+    "core.editor=true",
+    "-c",
+    "sequence.editor=true",
+];
+/**
+ * Git arguments with the editor turned off.
+ *
+ * Wrap the whole argument list rather than remembering to add flags at each call
+ * site, since the call that forgets is the one that hangs, and it hangs only when
+ * a rebase actually conflicts. That is a fault which passes every test and waits
+ * for somebody's real conflict to appear.
+ *
+ * These are global flags, so they go before the subcommand. Anything already
+ * global in the list, `-C` in particular, stays valid in any order beside them.
+ */
+export function unattended(args) {
+    return [...NO_EDITOR, ...args];
+}