@jitsusama/agentic-harness.core 0.1.0

package/dist/work/memory.js

@@ -0,0 +1,203 @@
+/**
+ * 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 { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { askedOnce, isOwner, ownerNow, ownerStanding, sameProcess, systemFacts, } from "../process/index.js";
+/**
+ * The holders a record names, ignoring anything malformed.
+ *
+ * Checks that it is an array before filtering it. A record is a file
+ * anybody can edit, and `owners: {}` on one of them would otherwise
+ * throw out of here and take tidy and reclaim down with it: one bad
+ * file, and the whole cleanup path stops for every repo.
+ */
+function named(tree) {
+    const owners = tree.owners;
+    if (!Array.isArray(owners))
+        return [];
+    return owners.filter(isOwner);
+}
+/** Whether two records name one process. */
+function sameOwner(one, two) {
+    return one.pid === two.pid && sameProcess(one.startedAt, two.startedAt);
+}
+/** Whether a record read back off disk says enough to be useful. */
+function usable(written) {
+    return (typeof written.path === "string" &&
+        typeof written.providerId === "string" &&
+        typeof written.identity?.key === "string");
+}
+/**
+ * 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 function createTreeMemory(dir) {
+    const fileFor = (key) => join(dir, `${key.replaceAll("/", "-")}.json`);
+    function all() {
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((name) => name.endsWith(".json"))
+            .flatMap((name) => {
+            const at = join(dir, name);
+            try {
+                const written = JSON.parse(readFileSync(at, "utf8"));
+                // A record we cannot read is worse than no record, because it
+                // would mean a tree reported with a broken identity. Skip it
+                // and leave it alone: deleting somebody's file to tidy a
+                // listing is not this function's decision.
+                return usable(written)
+                    ? [{ at, held: written }]
+                    : [];
+            }
+            catch {
+                // Unreadable or half-written, which a concurrent write can
+                // produce. The tree is still on disk and still reachable by
+                // path; only its identity is lost, and next cut rewrites it.
+                return [];
+            }
+        });
+    }
+    return {
+        remember(held) {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(fileFor(held.identity.key), JSON.stringify(held, null, 2), "utf8");
+        },
+        async rememberHeldByUs(held, facts = systemFacts) {
+            // Stamped here rather than by the caller, so a tree cannot be
+            // written down without the identity that lets it be released
+            // later. The owner is this process: whoever asks the broker for a
+            // tree is the session that will be holding it.
+            const us = await ownerNow(facts);
+            if (us === undefined) {
+                // The machine will not say when we started, so we cannot write
+                // an identity anybody could check later. Recording the tree
+                // without one is right: it reads as unattributable, which is
+                // held, and a tree wrongly held costs disk where a tree
+                // wrongly reclaimed costs work.
+                this.remember(held);
+                return;
+            }
+            // Added to whoever else holds it rather than replacing them. A
+            // snapshot is shareable, so two sessions can hold one tree, and
+            // the one that wrote last is not the only one that would miss it.
+            // Dead holders are left to be filtered on the way out rather than
+            // probed here, since this is on the path of every cut.
+            const before = (this.recall().find((tree) => tree.path === held.path)?.owners ??
+                held.owners ??
+                []).filter((one) => isOwner(one) && !sameOwner(one, us));
+            this.remember({ ...held, owners: [...before, us] });
+        },
+        forget(path) {
+            for (const { at, held } of all()) {
+                if (held.path === path)
+                    rmSync(at, { force: true });
+            }
+        },
+        recall() {
+            const found = [];
+            for (const { at, held } of all()) {
+                // The directory is the truth. A record whose tree has been
+                // removed by hand is dropped and its record with it, which is
+                // how somebody who cleaned up by hand stops being nagged about
+                // it forever.
+                if (existsSync(held.path)) {
+                    found.push(held);
+                    continue;
+                }
+                rmSync(at, { force: true });
+            }
+            return found;
+        },
+        unattributed() {
+            return this.recall().filter((tree) => named(tree).length === 0);
+        },
+        async otherHolders(path, facts = systemFacts) {
+            const tree = this.recall().find((one) => one.path === path);
+            if (tree === undefined)
+                return [];
+            const once = askedOnce(facts);
+            const us = await ownerNow(once);
+            const others = [];
+            for (const owner of named(tree)) {
+                if (us !== undefined && sameOwner(owner, us))
+                    continue;
+                if ((await ownerStanding(owner, once)) !== "gone")
+                    others.push(owner);
+            }
+            return others;
+        },
+        async forgetUsAsHolder(path, facts = systemFacts) {
+            const tree = this.recall().find((one) => one.path === path);
+            if (tree === undefined)
+                return;
+            const us = await ownerNow(facts);
+            if (us === undefined)
+                return;
+            this.remember({
+                ...tree,
+                owners: named(tree).filter((owner) => !sameOwner(owner, us)),
+            });
+        },
+        async heldNow(facts = systemFacts) {
+            const held = [];
+            // One question per process, not per record. Every reviewer of
+            // one round shares a session, so the same handful of pids
+            // recurs across the whole directory: without this, tidy forked
+            // `ps` once per record, serially, which is 59 spawns on the
+            // machine this was found on.
+            //
+            // The fact is cached, never the verdict. A standing compares
+            // the pid's real start time against the one a given record
+            // wrote down, so it belongs to the record and not to the pid:
+            // held per pid, one stale record answers for a live session
+            // wearing the same number, which is the exact confusion this
+            // module exists to prevent.
+            const once = askedOnce(facts);
+            for (const tree of this.recall()) {
+                const owners = named(tree);
+                // Nobody recorded means nobody can say, and every record
+                // written before owners existed is one of these. Reading it as
+                // nobody's would offer a live session's trees for reclaiming on
+                // the first run of this code, which is worse than the leak it
+                // fixes.
+                if (owners.length === 0) {
+                    held.push(tree);
+                    continue;
+                }
+                // Any one of them is enough. A shared snapshot outlives the
+                // first holder to finish with it.
+                const stands = await Promise.all(owners.map((owner) => ownerStanding(owner, once)));
+                if (stands.some((one) => one !== "gone"))
+                    held.push(tree);
+            }
+            return held;
+        },
+    };
+}

package/dist/work/objection.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Asking whether anybody objects before publishing a branch.
+ *
+ * This exists because of one seam. Publishing a branch is a working-layer
+ * action, and the reason not to publish is often a hosting-layer fact: on a
+ * backend with a merge queue, pushing to an enqueued branch ejects it and
+ * everything speculatively batched with it, and re-running the checks for the
+ * rest is measured in hundreds of jobs. The working layer cannot see that, and
+ * teaching it to would mean giving it a route to the review contract, which is
+ * the coupling this whole substrate exists to avoid.
+ *
+ * So it asks instead. Anything that knows something about a branch can object,
+ * and the objection carries its own words: the layer that knows why is the layer
+ * that explains it. Nothing here knows what a queue is.
+ *
+ * Silence means nobody objected, which is not the same as safe. That is the
+ * honest reading and it is why this is an objection rather than an approval: a
+ * check that nothing answers must not turn a push into a refusal, or a session
+ * with no hosting provider loaded could never publish anything.
+ */
+/** What is about to be published. */
+export interface PublishIntent {
+    /** The repo, keyed the way the working layer keys one. */
+    repoKey: string;
+    /** The branch about to be pushed. */
+    branch: string;
+    /** Where it is being pushed from, for anything that needs to look. */
+    treePath: string;
+    /** True when the push would replace commits the remote already has. */
+    replacing: boolean;
+}
+/** Somebody's reason not to publish. */
+export interface Objection {
+    /** Who is objecting, so a reader knows which system is worried. */
+    from: string;
+    /** Why, in words a person can act on. */
+    reason: string;
+    /** What to do instead, when there is a sensible alternative. */
+    instead?: string;
+    /**
+     * Whether this stops the push or merely says something about it.
+     *
+     * The distinction is not politeness, it is the difference between a guard
+     * people keep and a guard people disable. A backend that knows a change is
+     * queued can block; a backend that only knows it *would* refuse a queued
+     * change, without being able to say whether this one is queued, has a real
+     * thing to tell you and no business stopping every push you make. Blocking
+     * on a suspicion would refuse every push on such a backend, and a guard
+     * that refuses everything protects nothing once it is turned off.
+     *
+     * Defaults to blocking, since an objection whose author did not think about
+     * this is more likely to be a genuine one.
+     */
+    blocking?: boolean;
+}
+/**
+ * An objection collector, handed to whoever might have one.
+ *
+ * A function rather than a return value because the bus fans out: several
+ * listeners may each have something to say, and the last one to answer must not
+ * overwrite the first.
+ */
+export interface PublishReview {
+    intent: PublishIntent;
+    object(objection: Objection): void;
+}
+/**
+ * Emitted before a branch is published, so anything that knows a reason to stop
+ * can say so.
+ *
+ * Advisory by construction. A listener that throws, hangs or says nothing does
+ * not prevent a push, because the alternative is a working layer that stops
+ * working when an unrelated extension has a bad day.
+ */
+export declare const WORK_PUBLISH_CHECK = "work:publish:check:v1";
+/**
+ * Read a set of objections as one refusal, or nothing.
+ *
+ * Every objection is named and kept. Summarizing several into one would drop
+ * whichever the reader most needed, and two systems objecting for two reasons is
+ * a fact about the push rather than a formatting problem.
+ */
+export declare function refusalFrom(objections: readonly Objection[]): string | undefined;
+/**
+ * What was said that did not stop the push, to print beside what happened.
+ *
+ * Said after the fact rather than before it, because that is what a caution is:
+ * it decorates the outcome instead of becoming one. Printed at all because the
+ * alternative is a backend that knows something useful and has no way to say it
+ * without also blocking.
+ */
+export declare function cautionsFrom(objections: readonly Objection[]): readonly string[];

package/dist/work/objection.js

@@ -0,0 +1,72 @@
+/**
+ * Asking whether anybody objects before publishing a branch.
+ *
+ * This exists because of one seam. Publishing a branch is a working-layer
+ * action, and the reason not to publish is often a hosting-layer fact: on a
+ * backend with a merge queue, pushing to an enqueued branch ejects it and
+ * everything speculatively batched with it, and re-running the checks for the
+ * rest is measured in hundreds of jobs. The working layer cannot see that, and
+ * teaching it to would mean giving it a route to the review contract, which is
+ * the coupling this whole substrate exists to avoid.
+ *
+ * So it asks instead. Anything that knows something about a branch can object,
+ * and the objection carries its own words: the layer that knows why is the layer
+ * that explains it. Nothing here knows what a queue is.
+ *
+ * Silence means nobody objected, which is not the same as safe. That is the
+ * honest reading and it is why this is an objection rather than an approval: a
+ * check that nothing answers must not turn a push into a refusal, or a session
+ * with no hosting provider loaded could never publish anything.
+ */
+/**
+ * Emitted before a branch is published, so anything that knows a reason to stop
+ * can say so.
+ *
+ * Advisory by construction. A listener that throws, hangs or says nothing does
+ * not prevent a push, because the alternative is a working layer that stops
+ * working when an unrelated extension has a bad day.
+ */
+export const WORK_PUBLISH_CHECK = "work:publish:check:v1";
+/**
+ * Read a set of objections as one refusal, or nothing.
+ *
+ * Every objection is named and kept. Summarizing several into one would drop
+ * whichever the reader most needed, and two systems objecting for two reasons is
+ * a fact about the push rather than a formatting problem.
+ */
+export function refusalFrom(objections) {
+    const blocking = objections.filter((one) => one.blocking !== false);
+    if (blocking.length === 0)
+        return undefined;
+    if (blocking.length === 1) {
+        const [only] = blocking;
+        return [
+            `${only.from} says not to publish this yet. ${only.reason}`,
+            ...(only.instead === undefined ? [] : ["", only.instead]),
+        ].join("\n");
+    }
+    return [
+        `${blocking.length} systems say not to publish this yet.`,
+        ...blocking.flatMap((one) => [
+            "",
+            `${one.from}: ${one.reason}`,
+            ...(one.instead === undefined ? [] : [`   ${one.instead}`]),
+        ]),
+    ].join("\n");
+}
+/**
+ * What was said that did not stop the push, to print beside what happened.
+ *
+ * Said after the fact rather than before it, because that is what a caution is:
+ * it decorates the outcome instead of becoming one. Printed at all because the
+ * alternative is a backend that knows something useful and has no way to say it
+ * without also blocking.
+ */
+export function cautionsFrom(objections) {
+    return objections
+        .filter((one) => one.blocking === false)
+        .map((one) => [
+        `${one.from}: ${one.reason}`,
+        ...(one.instead === undefined ? [] : [one.instead]),
+    ].join(" "));
+}

package/dist/work/provider.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Choosing which provider cuts a tree.
+ *
+ * This replaces two brokers that sorted their providers in
+ * opposite directions. One took the smallest priority number,
+ * documented as "built-ins live at 100; downstream
+ * specialisations use smaller numbers to take over". The other
+ * took the largest, documented as "higher-priority providers are
+ * consulted first". Both downstream World providers were correct
+ * under their own broker while holding the same constant name at
+ * 50 and at 100.
+ *
+ * Unifying them on either direction would silently invert one, and
+ * silently is the operative word: losing does not raise anything,
+ * because the general provider still produces a tree. It would
+ * just be a plain git worktree where a `dev tree` was wanted,
+ * which works well enough to go unnoticed.
+ *
+ * So the number is not a priority. A provider says how *specific*
+ * it is, and more specific wins. "Priority" genuinely reads both
+ * ways in English, since priority 1 can mean first or last;
+ * "specificity" does not, because a provider for one repo is
+ * plainly more specific than one for any repo.
+ */
+import type { RepoLocator } from "../review/index.js";
+/** What choosing needs to know about a provider. */
+export interface TreeProviderInfo {
+    /** Stable identifier, used when reporting the choice. */
+    id: string;
+    /**
+     * How narrow this provider's remit is. Higher wins. A
+     * provider serving any repo declares 0; one serving a
+     * particular repo declares more.
+     */
+    specificity: number;
+    /**
+     * Whether this provider serves the given repo. Cheap and
+     * synchronous: it is asked about every provider on every
+     * choice.
+     */
+    appliesTo(repo: RepoLocator): boolean;
+}
+/**
+ * Which provider serves a repo.
+ *
+ * Three outcomes, because the caller has to say something
+ * different about each: use it, tell somebody nothing is
+ * configured, or tell somebody two things are configured to do the
+ * same job.
+ */
+export type TreeProviderChoice<P> = 
+/** Exactly one provider is the most specific that applies. */
+{
+    kind: "chosen";
+    provider: P;
+}
+/**
+ * Several apply and are equally specific, so which one serves
+ * is arbitrary. Reported rather than resolved: picking by
+ * registration order hides a configuration mistake behind a
+ * tree that looks fine.
+ */
+ | {
+    kind: "ambiguous";
+    providers: readonly P[];
+}
+/** Nothing applies. */
+ | {
+    kind: "none";
+};
+/**
+ * Choose the provider that serves a repo.
+ *
+ * Ties are reported with the contenders named and in a stable
+ * order, so the same misconfiguration reads the same way whichever
+ * order the providers happened to register in. A tie below the
+ * winner is not a tie at all and is ignored.
+ */
+export declare function chooseTreeProvider<P extends TreeProviderInfo>(providers: readonly P[], repo: RepoLocator): TreeProviderChoice<P>;

package/dist/work/provider.js

@@ -0,0 +1,45 @@
+/**
+ * Choosing which provider cuts a tree.
+ *
+ * This replaces two brokers that sorted their providers in
+ * opposite directions. One took the smallest priority number,
+ * documented as "built-ins live at 100; downstream
+ * specialisations use smaller numbers to take over". The other
+ * took the largest, documented as "higher-priority providers are
+ * consulted first". Both downstream World providers were correct
+ * under their own broker while holding the same constant name at
+ * 50 and at 100.
+ *
+ * Unifying them on either direction would silently invert one, and
+ * silently is the operative word: losing does not raise anything,
+ * because the general provider still produces a tree. It would
+ * just be a plain git worktree where a `dev tree` was wanted,
+ * which works well enough to go unnoticed.
+ *
+ * So the number is not a priority. A provider says how *specific*
+ * it is, and more specific wins. "Priority" genuinely reads both
+ * ways in English, since priority 1 can mean first or last;
+ * "specificity" does not, because a provider for one repo is
+ * plainly more specific than one for any repo.
+ */
+/**
+ * Choose the provider that serves a repo.
+ *
+ * Ties are reported with the contenders named and in a stable
+ * order, so the same misconfiguration reads the same way whichever
+ * order the providers happened to register in. A tie below the
+ * winner is not a tie at all and is ignored.
+ */
+export function chooseTreeProvider(providers, repo) {
+    const applicable = providers.filter((candidate) => candidate.appliesTo(repo));
+    if (applicable.length === 0)
+        return { kind: "none" };
+    const narrowest = Math.max(...applicable.map((c) => c.specificity));
+    const contenders = applicable
+        .filter((candidate) => candidate.specificity === narrowest)
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const [only] = contenders;
+    if (only && contenders.length === 1)
+        return { kind: "chosen", provider: only };
+    return { kind: "ambiguous", providers: contenders };
+}

package/dist/work/providers/git.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cutting trees with plain git.
+ *
+ * The general case, so that the broker works before anything
+ * downstream registers. A repo with a checkout on disk gets a git
+ * worktree beside the state directory, detached at a commit for a
+ * snapshot or on its branch for a worktree.
+ *
+ * It deliberately does not clone. A repo known only by a remote is
+ * refused with the remote named, because a clone of an unasked-for
+ * repo can be enormous and quietly spending ten minutes on one is a
+ * surprising thing for a tool to do on its own. Saying what is
+ * needed leaves the choice with whoever knows how big it is; a
+ * downstream provider that knows a particular repo can serve it
+ * without asking.
+ */
+import { type Exec } from "../../exec/index.js";
+import type { TreeProvider } from "../broker.js";
+/**
+ * A tree provider backed by `git worktree`.
+ *
+ * Applies to every repo, since git is what the general case means.
+ * Anything more specific outranks it by declaring a higher
+ * specificity.
+ */
+export declare function createGitTreeProvider(deps: {
+    exec: Exec;
+    stateDir: string;
+}): TreeProvider;

package/dist/work/providers/git.js

@@ -0,0 +1,87 @@
+/**
+ * Cutting trees with plain git.
+ *
+ * The general case, so that the broker works before anything
+ * downstream registers. A repo with a checkout on disk gets a git
+ * worktree beside the state directory, detached at a commit for a
+ * snapshot or on its branch for a worktree.
+ *
+ * It deliberately does not clone. A repo known only by a remote is
+ * refused with the remote named, because a clone of an unasked-for
+ * repo can be enormous and quietly spending ten minutes on one is a
+ * surprising thing for a tool to do on its own. Saying what is
+ * needed leaves the choice with whoever knows how big it is; a
+ * downstream provider that knows a particular repo can serve it
+ * without asking.
+ */
+import { join } from "node:path";
+import { run } from "../../exec/index.js";
+import { withoutCredentials } from "../../remote/index.js";
+import { displayPath } from "../../ui/path.js";
+import { treeIdentity, treeSource } from "../tree.js";
+/** The built-in provider's id, and the general case's specificity. */
+const ID = "git-worktree";
+const GENERAL = 0;
+/**
+ * A tree provider backed by `git worktree`.
+ *
+ * Applies to every repo, since git is what the general case means.
+ * Anything more specific outranks it by declaring a higher
+ * specificity.
+ */
+export function createGitTreeProvider(deps) {
+    return {
+        id: ID,
+        specificity: GENERAL,
+        appliesTo: () => true,
+        async ensure(request) {
+            const source = treeSource(request.repo);
+            if (source.kind === "unknown") {
+                throw new Error(`Nothing is known about where ${request.repo.key} lives, locally or by remote, so there is nowhere to cut a tree from.`);
+            }
+            if (source.kind === "clone") {
+                throw new Error(`${request.repo.key} is known only as ${withoutCredentials(source.remoteUrl)}, and cloning a repo you did not ask for can take a very long time. Clone it yourself, or register a provider that knows this repo.`);
+            }
+            const path = join(deps.stateDir, treeIdentity(request).key);
+            // Already there is the ordinary case, not a failure. `ensure` means
+            // make sure it exists, a snapshot is shareable between readers by
+            // design, and the broker holding one only remembers for as long as
+            // the session does while the directory outlives it. So the second
+            // session to review a commit found the tree its predecessor cut and
+            // died on `fatal: already exists`, then fell back to letting
+            // reviewers read the working checkout.
+            const standing = await deps.exec("git", [
+                "-C",
+                path,
+                "rev-parse",
+                "HEAD",
+            ]);
+            if (standing.code === 0) {
+                const head = standing.stdout.trim();
+                // A snapshot's commit is part of its identity, so a tree under
+                // this name standing anywhere else is not the thing being asked
+                // for. Refuse rather than hand it over: silently reviewing a
+                // different commit is the one outcome nobody could detect.
+                if (request.intent === "snapshot" && head !== request.commit) {
+                    throw new Error(`A tree for ${request.repo.key} already sits at ${displayPath(path)} but stands at ${head} rather than ${request.commit}. Release it before pinning a snapshot there.`);
+                }
+                return { path };
+            }
+            const at = request.intent === "snapshot"
+                ? ["--detach", path, request.commit]
+                : [path, request.branch];
+            await run(deps.exec, "git", ["-C", source.path, "worktree", "add", ...at], `Cutting a tree for ${request.purpose}`);
+            return { path };
+        },
+        async release(held) {
+            // Scoped to the tree itself, which is the one repo guaranteed
+            // to know about it. Without a -C this ran against whatever
+            // repo the process happened to be sitting in, and git then
+            // reports that the path is not a working tree, which is true
+            // of that repo and beside the point. A worktree's .git file
+            // names its main repo, so asking from inside is enough and
+            // needs no source path carried on the held tree.
+            await run(deps.exec, "git", ["-C", held.path, "worktree", "remove", held.path], `Releasing the tree at ${displayPath(held.path)}`);
+        },
+    };
+}

package/dist/work/publish.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Publishing a branch, which is the step between committing and proposing.
+ *
+ * It was missing, and its absence was the one place this surface made you
+ * leave it: `work record` committed, `review_offer propose` needed the branch
+ * on the remote, and nothing in between was a tool. Every other seam here is
+ * something you can call.
+ *
+ * Two rules are built in rather than offered. A first push sets upstream,
+ * because a branch that pushes without one has to be told its own name every
+ * time afterwards and eventually gets told the wrong one. And a force is
+ * always a lease: `--force` overwrites whatever arrived while you were
+ * rebasing, which on a shared branch is somebody else's work, and the honest
+ * version of "I know what is there" is to say what you think is there and be
+ * refused when you are wrong.
+ */
+import type { Exec } from "../exec/index.js";
+/** Where a branch went, or why it did not. */
+export type PushOutcome = {
+    kind: "published";
+    branch: string;
+    remote: string;
+    /** True when this push is what gave the branch its upstream. */
+    tracked: boolean;
+    /** True when the push replaced commits the remote already had. */
+    replaced: boolean;
+} | {
+    kind: "already-there";
+    branch: string;
+    remote: string;
+} | {
+    kind: "refused";
+    branch?: string;
+    reason: string;
+};
+/** How to publish. */
+export interface PushOptions {
+    /**
+     * Replace what the remote has, refusing if it moved since you last
+     * fetched. Needed after a rebase, and never a bare force.
+     */
+    replace?: boolean;
+    /** Which remote. Defaults to the branch's upstream, then to origin. */
+    remote?: string;
+}
+/** Publishing the work in a tree. */
+export interface WorkPublisher {
+    push(treePath: string, options?: PushOptions): Promise<PushOutcome>;
+}
+/** Publish with plain git. */
+export declare function createGitPublisher(deps: {
+    exec: Exec;
+}): WorkPublisher;