dorfl 0.0.0 → 0.1.0

package/dist/integrator.js

@@ -0,0 +1,400 @@
+import { git, run } from './git.js';
+import { isAncestor } from './gc.js';
+import { pushProposeBranchWithStaleLeaseRetry } from './continue-branch.js';
+/**
+ * The graceful-degradation provider (ADR §6): it opens NO review request (there
+ * is no API — e.g. a local `--bare` arbiter) and instead tells the human to open
+ * one manually. The branch is already pushed, so the work is safe regardless.
+ */
+export class NoneProvider {
+    name = 'none';
+    async openRequest(input) {
+        return {
+            opened: false,
+            instruction: `Pushed ${input.branch} to ${input.arbiter}. Open a review request ` +
+                'manually to land it on main (no review provider configured).' +
+                manualRequestText(input),
+        };
+    }
+    /**
+     * No API to post a comment (a local `--bare` arbiter has no review concept), so
+     * DEGRADE: surface the review text in the result instead of throwing — the
+     * verdict stays in the run output, never lost (ADR §6). The caller treats this
+     * as a clean no-op for the PR (nothing was posted).
+     */
+    postPRComment(input) {
+        return {
+            posted: false,
+            instruction: 'No review provider configured — the review was not posted as a PR ' +
+                `comment. The review:\n${input.body}`,
+        };
+    }
+    /**
+     * No API to resolve a PR from a branch (a local `--bare` arbiter has no review
+     * concept), so DEGRADE exactly like {@link postPRComment}: surface the review
+     * text, post nothing, never throw. A clean no-op for the PR.
+     */
+    postPRCommentOnBranch(input) {
+        return {
+            posted: false,
+            instruction: 'No review provider configured — the review was not posted as a PR ' +
+                `comment. The review:\n${input.body}`,
+        };
+    }
+}
+export class Integrator {
+    provider;
+    constructor(options = {}) {
+        this.provider = options.provider ?? new NoneProvider();
+    }
+    /**
+     * Integrate WITHOUT rebasing (assumes the caller already rebased, or the
+     * branch is known up-to-date). `merge` pushes the branch to `main` (plain,
+     * non-force push); `propose` pushes the branch under its own ref + asks the
+     * provider to request review. NEVER `--force` (and NEVER force-touches main).
+     */
+    async integrate(input) {
+        if (input.mode === 'merge') {
+            // Race-1 (claim-vs-integrate): push `${branch}:main` ONCE. On a
+            // non-fast-forward rejection (a sibling same-repo claim/integrate advanced
+            // `<arbiter>/main` during our push window) report it so the integration-core
+            // step-4 tail re-rebases (with its sibling-ledger reconcile) + retries the
+            // push. We never rebase here (that would miss the ledger reconcile arms) and
+            // never `--force` main.
+            const pushed = mergePushOnce(input);
+            if (pushed.kind === 'non-fast-forward') {
+                // Signal the caller to re-rebase via step-4 and call integrate again.
+                return {
+                    mode: 'merge',
+                    mergedToMain: false,
+                    pushedRef: 'main',
+                    provider: 'none',
+                    requestOpened: false,
+                    mergeNonFastForward: true,
+                };
+            }
+            // Capture the SHA that LANDED on `main` — the work branch's tip is exactly
+            // what `${branch}:main` pushed (additive `commit?`, the merge-mode twin of
+            // propose's `url`). Best-effort: a failed read leaves `commit` absent, so a
+            // caller that links it (intake) simply omits the link rather than throwing.
+            const commit = resolveBranchTip(input);
+            // Part (b): reap the remote head INLINE now the merge has landed. The work
+            // is on `main` (we just pushed it there), so the head is provably merged and
+            // safe to delete — the exact merge moment, no sweep needed. Idempotent +
+            // best-effort: a no-remote-head merge (the common `${branch}:main` push) is a
+            // clean no-op. NEVER `--force`. Gated by `deleteMergedHead` so the bare
+            // `integrate` callers / tests are unchanged.
+            if (input.deleteMergedHead === true) {
+                deleteMergedHeadBranch(input);
+            }
+            return {
+                mode: 'merge',
+                mergedToMain: true,
+                pushedRef: 'main',
+                provider: 'none',
+                requestOpened: false,
+                ...(commit !== undefined ? { commit } : {}),
+            };
+        }
+        // propose: push the branch under its own name (the safety-bearing step),
+        // THEN ask the provider to request review. Reconcile with --force-with-lease
+        // on the WORK BRANCH ONLY (§11: a work branch is unshared) so a RECOVERY
+        // complete — which rebases the kept branch onto fresh `main` (a PLAIN rebase
+        // after the per-item-lock cut-over: no transient status lands on a branch, so
+        // there is nothing to drop) and so REWRITES the tip vs an already-pushed
+        // `work/<slug>` (the bounce now pushes it via the seam) — lands cleanly
+        // instead of failing non-fast-forward. The lease guards the CAS; this
+        // is NEVER a plain `--force`, and NEVER touches main.
+        //
+        // STALE-LEASE SURVIVAL + BENIGN ALREADY-LANDED (task `propose-push-
+        // survives-stale-lease-on-reaped-work-ref`): route through the propose
+        // stale-lease retry helper (the sibling of
+        // `pushContinuedBranchWithStaleLeaseRetry`, sharing its `stale info`
+        // detection + bounded retry, with the propose-specific addition of the
+        // gone-ref + ancestor-of-`<arbiter>/main` = BENIGN already-landed predicate
+        // — mirroring `deleteMergedHeadBranch`'s ancestor guard + the leased-delete
+        // `already-reaped` precedent). Survives a `stale info` rejection when the
+        // arbiter's view of the unshared work ref moved under us (re-leases against
+        // the freshly-observed tip); reports `alreadyLanded` (no PR re-open against
+        // a vanished ref) when the work already landed via a sibling's merge +
+        // reap; SURFACES every non-stale failure (connectivity, protected ref,
+        // auth) and a non-provably-landed stale-info-after-cap as a terminal throw.
+        // For a first-time propose (no remote ref yet) the helper's create-only
+        // empty-expected lease shape (`<branch>:`) accepts the new ref unchanged.
+        const proposePush = pushProposeBranchWithStaleLeaseRetry({
+            cwd: input.cwd,
+            branch: input.branch,
+            arbiter: input.arbiter,
+            env: input.env,
+        });
+        if (proposePush.kind === 'already-landed') {
+            // BENIGN already-landed: the work is provably on `<arbiter>/main` and the
+            // head was reaped. Do NOT call the provider — there is no ref to open a
+            // review request against, and asking the provider to open a PR for
+            // landed work would be a confusing no-op. Distinct from a real failure:
+            // `alreadyLanded: true`, no throw, no PR.
+            return {
+                mode: 'propose',
+                mergedToMain: false,
+                pushedRef: input.branch,
+                provider: 'none',
+                requestOpened: false,
+                alreadyLanded: true,
+                instruction: `${input.branch}: the work is already on ${input.arbiter}/main ` +
+                    'and its remote head was reaped — nothing to propose (clean no-op).',
+            };
+        }
+        // PR-INTENT (`noPR: true`): the branch is now pushed (safe) — deliberately do
+        // NOT open a review request (the explicit suppress-PR intent). No warning: the
+        // no-PR outcome is intended, not a degrade. The provider is reported as `none`
+        // (no request opened), exactly as a push-only propose surfaces.
+        if (input.noPR === true) {
+            return {
+                mode: 'propose',
+                mergedToMain: false,
+                pushedRef: input.branch,
+                provider: 'none',
+                requestOpened: false,
+                instruction: `Pushed ${input.branch} to ${input.arbiter}. No PR was opened ` +
+                    '(noPR is set — the suppress-PR intent).',
+            };
+        }
+        const review = await this.provider.openRequest({
+            cwd: input.cwd,
+            branch: input.branch,
+            arbiter: input.arbiter,
+            title: input.title,
+            body: input.body,
+            env: input.env,
+            backoff: input.backoff,
+            sleep: input.sleep,
+        });
+        return {
+            mode: 'propose',
+            mergedToMain: false,
+            pushedRef: input.branch,
+            provider: this.provider.name,
+            requestOpened: review.opened,
+            instruction: review.instruction,
+            url: review.url,
+        };
+    }
+    /**
+     * Rebase-before-integrate (ADR §10): fetch + rebase the branch onto the latest
+     * `<arbiter>/main`. Clean → integrate. Conflict → the rebase is already
+     * aborted by `rebaseOntoArbiterMain`; we return `needs-attention` (NEVER
+     * auto-resolve, NEVER push a half-merged tree).
+     */
+    async integrateWithRebase(input) {
+        const rebase = rebaseOntoArbiterMain({
+            cwd: input.cwd,
+            arbiter: input.arbiter,
+            branch: input.branch,
+            env: input.env,
+        });
+        if (!rebase.clean) {
+            return {
+                outcome: 'needs-attention',
+                reason: `Rebasing ${input.branch} onto ${input.arbiter}/main conflicted; ` +
+                    'the rebase was aborted (never auto-resolved). A human must resolve ' +
+                    'against the latest main, then re-integrate.',
+            };
+        }
+        return { outcome: 'integrated', integration: await this.integrate(input) };
+    }
+}
+/**
+ * Deterministically rebase `branch` onto the freshly-fetched `<arbiter>/main`
+ * (ADR §10). A clean rebase leaves the branch on top of main. A conflicting
+ * rebase is `git rebase --abort`ed (restoring the pre-rebase state) and reported
+ * as `conflicted` — we NEVER pick `--ours`/`--theirs` or any heuristic
+ * (resolution requires semantic judgement; a wrong-but-compiling merge is the
+ * worst outcome). Must be called with `branch` checked out.
+ */
+export function rebaseOntoArbiterMain(input) {
+    const env = input.env;
+    // Fetch the arbiter's `main` into the `<arbiter>/main` remote-tracking ref
+    // EXPLICITLY. A job worktree is cut from a bare hub mirror whose `origin`
+    // remote has no fetch refspec (so `origin/main` would not otherwise resolve);
+    // a normal clone already has it but the explicit refspec is harmless there.
+    git([
+        'fetch',
+        '--quiet',
+        input.arbiter,
+        `+refs/heads/main:refs/remotes/${input.arbiter}/main`,
+    ], input.cwd, { env });
+    // Ensure we are on the branch we intend to rebase.
+    git(['checkout', '--quiet', input.branch], input.cwd, { env });
+    const rebase = run('git', ['rebase', `${input.arbiter}/main`], input.cwd, {
+        env,
+    });
+    if (rebase.status === 0) {
+        return { clean: true, conflicted: false };
+    }
+    // Conflict (or any non-zero): abort to restore the pre-rebase state. NEVER
+    // auto-resolve. `--abort` is best-effort; if there is nothing to abort it is
+    // a no-op error we can ignore.
+    run('git', ['rebase', '--abort'], input.cwd, { env });
+    return { clean: false, conflicted: true };
+}
+/**
+ * Push `${branch}:main` (merge mode) ONCE, classifying the outcome for the
+ * caller's bounded re-rebase-and-retry loop (Race 1: claim-vs-integrate, task
+ * `run-fleet-claim-integrate-and-sibling-rebase-concurrency-safe`). It does NOT
+ * rebase itself: the rebase belongs to the integration-core step-4 tail, which
+ * ALSO carries the sibling-ledger + divergent-done-move reconciliation arms a bare
+ * rebase here would miss. This function's only job is to push and tell the caller
+ * whether to LOOP (re-rebase via step-4) or STOP.
+ *
+ *   - `landed` — the push succeeded, OR (under the non-atomic `file://` transport)
+ *     it reported failure but our tip is ALREADY reachable on `<arbiter>/main`
+ *     (the push genuinely landed — an IDEMPOTENT no-op; never re-rebase our own
+ *     already-landed commit, which would self-conflict). The `isAncestor` probe is
+ *     the SAME merged-vs-unmerged predicate `gc.ts`/`finishStrandedBranch` use.
+ *   - `non-fast-forward` — a SIBLING advanced `<arbiter>/main` during our push
+ *     window (a claim CAS commit, or a sibling integrate); the caller must
+ *     re-fetch + re-run the step-4 rebase (reconciling sibling-ledger divergence)
+ *     and retry the push. We NEVER `--force` main.
+ *
+ * Any OTHER push failure (unreachable arbiter, refused ref) THROWS, exactly as a
+ * plain `git push` would.
+ */
+function mergePushOnce(input) {
+    const env = input.env;
+    const refspec = `${input.branch}:main`;
+    const arbiterRef = `refs/remotes/${input.arbiter}/main`;
+    const push = run('git', ['push', input.arbiter, refspec], input.cwd, { env });
+    if (push.status === 0) {
+        return { kind: 'landed' };
+    }
+    // Distinguish a CONTENTION rejection (main advanced — recoverable by a step-4
+    // re-rebase) from any other push failure (which surfaces as today's throw).
+    const combined = `${push.stderr}\n${push.stdout}`;
+    const nonFastForward = /non-fast-forward|fetch first|\[rejected\]|failed to push/i.test(combined);
+    if (!nonFastForward) {
+        throw new Error(`git push ${input.arbiter} ${refspec} failed (exit ${push.status}): ` +
+            `${push.stderr.trim() || push.stdout.trim()}`);
+    }
+    // Re-fetch the arbiter's main and check IDEMPOTENCY first: under `file://` a
+    // reported failure can have actually landed. If our tip is already on main, it
+    // landed — never re-rebase our own commit onto a main that has it.
+    git(['fetch', '--quiet', input.arbiter, `+refs/heads/main:${arbiterRef}`], input.cwd, { env });
+    const tip = run('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${input.branch}`], input.cwd, { env }).stdout.trim();
+    if (tip !== '' && isAncestor(input.cwd, tip, arbiterRef, env)) {
+        return { kind: 'landed' };
+    }
+    // A genuine sibling main-advance: the caller re-runs the step-4 rebase + retries.
+    return { kind: 'non-fast-forward' };
+}
+/**
+ * Push a branch to the arbiter. Used by both modes; `merge` targets `main`
+ * (plain, never forced), `propose` targets the branch's own ref. The caller may
+ * pass extra git args (e.g. `--force-with-lease=<work-branch>` on the propose
+ * path, to reconcile a recovery-rewritten WORK branch — §11, unshared, lease-
+ * guarded). There is NEVER a plain `--force`, and `main` is NEVER forced; the
+ * only leases in the system are this work-branch one + the claim micro-commit's.
+ */
+function pushBranch(input, refspec, ...extraArgs) {
+    git(['push', input.arbiter, refspec, ...extraArgs], input.cwd, {
+        env: input.env,
+    });
+}
+/**
+ * Reap the remote `work/<slug>` HEAD branch on the arbiter AFTER its work landed
+ * on `main` (merge mode, part (b)). The merge push above already put the commits
+ * on `main`, so the head is PROVABLY merged — it is the recovery point no longer
+ * (its work is on main), exactly the never-delete invariant's release condition.
+ * We additionally CONFIRM the head, when it exists, is an ancestor of
+ * `<arbiter>/main` before deleting, so a racing un-merged amend is never reaped.
+ *
+ * BEST-EFFORT + idempotent (soft `run`, never throws): the deletion of a
+ * fully-merged ref needs NO force (and we never pass one); a no-remote-head merge
+ * (the plain `${branch}:main` push opened none) is a clean no-op; an unreachable
+ * arbiter / already-gone ref is tolerated. The integrate's safety rides on the
+ * merge push, never on this hygiene step.
+ */
+function deleteMergedHeadBranch(input) {
+    const env = input.env;
+    const arbiter = input.arbiter;
+    const branch = input.branch;
+    // Does a remote head exist at all? (`ls-remote` exits 0 with empty stdout when
+    // absent.) No head ⇒ nothing to reap (the common direct-merge case).
+    const ls = run('git', ['ls-remote', '--heads', arbiter, branch], input.cwd, {
+        env,
+    });
+    if (ls.status !== 0 || ls.stdout.trim() === '') {
+        return; // unreachable arbiter, or no remote head — nothing to delete.
+    }
+    // The head exists. Confirm it is an ancestor of <arbiter>/main before deleting
+    // (it just merged, so this holds; the guard refuses a racing un-merged amend).
+    run('git', [
+        'fetch',
+        '--quiet',
+        arbiter,
+        `+refs/heads/main:refs/remotes/${arbiter}/main`,
+        `+refs/heads/${branch}:refs/remotes/${arbiter}/${branch}`,
+    ], input.cwd, { env });
+    const headSha = parseLsRemoteSha(ls.stdout);
+    if (headSha !== undefined) {
+        const isMerged = run('git', ['merge-base', '--is-ancestor', headSha, `refs/remotes/${arbiter}/main`], input.cwd, { env });
+        if (isMerged.status !== 0) {
+            return; // NOT provably merged (a racing un-merged amend) — never reap.
+        }
+    }
+    // Provably merged: WRITE-THROUGH delete — drop the LOCAL tracking ref FIRST
+    // (the ref that drives continue-detection), THEN the arbiter head (NEVER
+    // `--force`). The asymmetry is the point: an arbiter-delete failure leaves
+    // the local store BEHIND (self-healing on next fetch), never AHEAD (a stale
+    // `refs/remotes/<arbiter>/work/<slug>` that drives a wrong "continue" — the
+    // permanent stale-continue bug today's arbiter-first ordering creates).
+    run('git', ['update-ref', '-d', `refs/remotes/${arbiter}/${branch}`], input.cwd, { env });
+    run('git', ['push', arbiter, '--delete', branch], input.cwd, { env });
+}
+/** First sha from a `git ls-remote` output line (`<sha>\t<ref>`), or undefined. */
+function parseLsRemoteSha(stdout) {
+    const m = /^([0-9a-f]{40})\s/m.exec(stdout.trim());
+    return m ? m[1] : undefined;
+}
+/**
+ * Resolve the SHA the merge path just pushed to `main` — the work branch's tip
+ * (`${branch}:main` pushes exactly that). BEST-EFFORT (soft `run`, never throws):
+ * on any failure it returns `undefined`, so the additive {@link
+ * IntegrateResult.commit} stays absent rather than breaking the integrate. Used to
+ * link the landed commit (intake's completion comment); the integrate's safety
+ * rides on the push above, never on this read.
+ */
+function resolveBranchTip(input) {
+    const res = run('git', ['rev-parse', input.branch], input.cwd, {
+        env: input.env,
+    });
+    if (res.status !== 0) {
+        return undefined;
+    }
+    const sha = res.stdout.trim();
+    return sha === '' ? undefined : sha;
+}
+/**
+ * Render the runner-synthesised TITLE + BODY into a human's MANUAL review-request
+ * instructions (the `none` provider, and the GitHub provider's degraded path),
+ * so a human opening the request by hand reuses the SAME title/body the
+ * autonomous path would have set. Returns '' when neither is present (today's
+ * bare instruction — no regression). Surfaced as a trailing block so the
+ * leading instruction line stays clean.
+ */
+export function manualRequestText(input) {
+    const parts = [];
+    if (input.title) {
+        parts.push(`\nSuggested title: ${input.title}`);
+    }
+    if (input.body) {
+        parts.push(`\nSuggested body:\n${input.body}`);
+    }
+    return parts.join('');
+}
+/** True if the arbiter's `main` currently contains `commitish` (work landed). */
+export function arbiterMainContains(cwd, arbiter, commitish, env) {
+    run('git', ['fetch', '-q', arbiter], cwd, { env });
+    const res = run('git', ['merge-base', '--is-ancestor', commitish, `${arbiter}/main`], cwd, { env });
+    return res.status === 0;
+}
+//# sourceMappingURL=integrator.js.map

package/dist/integrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrator.js","sourceRoot":"","sources":["../src/integrator.ts"],"names":[],"mappings":"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"}

package/dist/isolation.d.ts

@@ -0,0 +1,219 @@
+import { type Job } from './workspace.js';
+import { type SlugNamespace } from './slug-namespace.js';
+/**
+ * The **isolation-strategy seam** (`docs/adr/command-surface-and-journeys.md`
+ * §3; substrate ADR §1/§2/§4): one seam, two strategies, selected by whether
+ * there is a checkout —
+ *
+ *   - **in-place** — the current checkout (a human's clone, or the CI container)
+ *     IS the isolation: claim + build + gate + integrate operate directly in the
+ *     current working tree on its `work/<slug>` branch. NO hub mirror, NO
+ *     external worktree, NO reap (the human's checkout is left in a defined
+ *     state, never deleted).
+ *   - **job-worktree** — materialise a hub mirror + an external job worktree in
+ *     the agents' area (`workspacesDir`), EXACTLY as `run`'s `createJob` path
+ *     does (ADR §1/§2), with end-of-job teardown re-applying the §4
+ *     provably-safe deletion predicate (`reapJob`).
+ *
+ * The load-bearing design constraint is the **uniform handle** ({@link
+ * IsolatedTree}): both strategies expose the SAME fields the post-claim pipeline
+ * reads (`dir`/`branch`/`arbiterRemote`/`arbiterUrl`) plus a strategy-appropriate
+ * `teardown`, so the shared build→gate→done-move→rebase→integrate→teardown steps
+ * run against EITHER strategy without knowing WHERE the tree lives. This removes
+ * the `Job`-shape coupling from the pipeline (`run`'s old `runOneItem` read a
+ * concrete `Job`).
+ *
+ * Wiring a COMMAND to the in-place strategy is the `do-in-place` task — this
+ * module only provides the seam + both implementors; `run` keeps using the
+ * job-worktree strategy (its observable behaviour is byte-identical).
+ */
+/**
+ * The uniform handle the post-claim pipeline reads from — satisfied IDENTICALLY
+ * by both strategies, so the shared steps never depend on a concrete `Job` (and
+ * thus never assume a hub mirror / external worktree).
+ */
+export interface IsolatedTree {
+    /**
+     * The working tree the agent + tests run in: the job worktree (job-worktree
+     * strategy) or the current checkout (in-place strategy).
+     */
+    dir: string;
+    /** The work branch checked out there (`work/<type>-<slug>`). */
+    branch: string;
+    /**
+     * The git remote NAME, VALID INSIDE `dir`, that tracks the arbiter — the
+     * rebase/integrate push target. Job-worktree: `origin` (the bare hub mirror's
+     * clone remote). In-place: the checkout's own arbiter remote name.
+     */
+    arbiterRemote: string;
+    /**
+     * The arbiter remote URL used for provider auto-detection (a GitHub URL ⇒ the
+     * `gh` provider). Job-worktree: the mirror's resolved arbiter URL
+     * (`job.mirror.url` today). In-place: the checkout's arbiter remote URL.
+     */
+    arbiterUrl: string;
+    /**
+     * True iff this tree CONTINUED a kept arbiter `work/<slug>` branch (a requeue)
+     * rather than cutting fresh off main — the SAME continue-detection both
+     * onboarding paths use. The prompt assembly injects a CONTINUE block when set
+     * (the `agent-prompt-continue-context` task). Absent / false on a fresh cut.
+     */
+    continued?: boolean;
+    /**
+     * True iff a CONTINUE rebase onto fresh main CONFLICTED at onboard-time
+     * (a requeue kept a `work/<slug>` whose commits did not replay onto the
+     * current main; aborted, never auto-resolved). The pipeline routes the item
+     * to needs-attention (the §10 path) instead of running the agent. Absent /
+     * false on a fresh cut and on a clean continue.
+     */
+    continueRebaseConflict?: boolean;
+    /**
+     * Set iff the CONTINUE reconcile push to the arbiter FAILED TERMINALLY at
+     * onboard-time (the stale-lease retry cap exhausted, or a non-stale-lease
+     * rejection / unreachable arbiter) — the push helper THROWS, caught so the run
+     * does NOT crash leaving the task silently in-progress on the arbiter (the
+     * stale-lease-strand bug). The pipeline routes the item to needs-attention,
+     * the kept work left committed + recoverable on the branch. Absent on a fresh
+     * cut, a clean continue that pushed, and a rebase conflict (which sets
+     * {@link continueRebaseConflict} instead).
+     */
+    continuePushFailure?: string;
+    /**
+     * Tear the isolated tree down per the strategy. Job-worktree: re-apply the §4
+     * deletion-safety predicate and `git worktree remove`/prune the worktree ONLY
+     * if provably safe (`reapJob`). In-place: a NO-OP — the human's checkout is
+     * left in a defined state, NEVER reaped. Always safe to call (e.g. in a
+     * `finally`).
+     *
+     * `opts.reachableOnly` (job-worktree only) drops the clean-tree half of the
+     * predicate, keeping the reachable-on-arbiter half: a worktree whose durable
+     * branch is provably on the arbiter is reaped EVEN WHEN its tree has incidental
+     * churn. This is the FAILURE-path opt-in (`performDoRemote`'s needs-attention
+     * return, where the seam has already surfaced + pushed the branch), so a
+     * churn-dirty-but-arbiter-safe worktree does not linger to poison the next
+     * build. It NEVER reaps work not yet on the arbiter (reachability stands).
+     * The in-place teardown ignores it (still a no-op).
+     */
+    teardown(opts?: {
+        reachableOnly?: boolean;
+    }): void;
+}
+/** What a strategy needs to prepare an isolated tree for one work item. */
+export interface PrepareInput {
+    /** The work slug being processed (→ branch `work/<type>-<slug>`). */
+    slug: string;
+    /**
+     * The item TYPE — `'task'` for a build (intake/`do task:`), `'prd'` for a
+     * prd-tasking run (`do prd:`). It NAMESPACES the work branch via
+     * {@link workBranchRef} so a same-slug task and prd never collide on the
+     * arbiter branch. Defaults to `'task'` (the overwhelmingly-common build
+     * path); the prd-tasking path passes `'prd'` explicitly.
+     */
+    type?: SlugNamespace;
+    /**
+     * The sha of the claim commit (`claim: <slug>`) just landed on the arbiter,
+     * surfaced out of `performClaim`. The in-place FRESH path branches the work
+     * branch from THIS exact commit (and HARD-FAILS if it is unreachable from
+     * `<arbiter>/main`) — never a stale same-named branch or a not-yet-advanced
+     * local main. Absent on a resume/continue or when the caller has no claim
+     * commit (the job-worktree strategy ignores it).
+     */
+    claimCommit?: string;
+    /** Environment for child git/agent processes. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * A way to acquire (and tear down) an isolated working tree on a freshly-fetched
+ * main for a slug. The signatures stay SEMANTIC — "prepare an isolated tree;
+ * expose a uniform handle; tear it down" — and DO NOT assume WHERE the tree
+ * lives, so `do --remote`/`run` (job-worktree) and `do-in-place` (in-place) each
+ * select their strategy without the pipeline knowing.
+ */
+export interface IsolationStrategy {
+    /** Stable strategy name (for diagnostics / records). */
+    readonly name: 'in-place' | 'job-worktree';
+    /**
+     * Prepare an isolated working tree for `slug` on a freshly-fetched main and
+     * return the uniform handle. The handle's `teardown` reverses it per strategy.
+     */
+    prepare(input: PrepareInput): IsolatedTree;
+}
+/**
+ * The **job-worktree** strategy — `run`'s EXISTING isolation, extracted behind
+ * the seam UNCHANGED. `prepare` ensures the hub mirror + cuts a per-job worktree
+ * off the freshly-fetched `<hub>/main` (`createJob`); the handle's `teardown`
+ * re-applies the §4 provably-safe deletion predicate (`reapJob`) — reaping the
+ * worktree iff its work is clean AND on the arbiter, retaining it otherwise (the
+ * never-lose-work signal). The arbiter remote inside the worktree is `origin`
+ * (the bare mirror's clone remote), and provider detection keys off the mirror's
+ * resolved arbiter URL — byte-identical to today's `run`.
+ */
+export declare function jobWorktreeStrategy(options: {
+    /** A working repo to resolve the arbiter URL from (with `arbiter`). */
+    fromRepo: string;
+    /** Remote name in `fromRepo` whose URL to mirror (default `origin`). */
+    arbiter?: string;
+    /** The execution working area (config `workspacesDir`). */
+    workspacesDir: string;
+}): IsolationStrategy;
+/**
+ * Build the uniform handle for a job-worktree `Job` — the EXACT fields `run`'s
+ * pipeline read off `job` today (`dir`/`branch`/`arbiterRemote`/`mirror.url`)
+ * plus the `reapJob` teardown. Exposed so a caller that already created the
+ * `Job` (e.g. `run`'s pipeline, mid-extraction) can wrap it without re-creating.
+ */
+export declare function jobWorktreeHandle(job: Job, env: NodeJS.ProcessEnv | undefined): IsolatedTree;
+/**
+ * The **in-place** strategy — the current checkout (a human's clone, or the CI
+ * container) IS the isolation. `prepare` fetches the arbiter and switches the
+ * checkout to `work/<slug>` cut from the freshly-fetched `<arbiter>/main` (the
+ * SAME "every worktree is cut from a fresh main" guarantee, ADR §6), WITHOUT a
+ * hub mirror or external worktree. The handle's `arbiterRemote`/`arbiterUrl` come
+ * from the checkout's own arbiter remote; `teardown` is a NO-OP — the checkout is
+ * left in a defined state on `work/<slug>`, NEVER reaped (it is the human's tree
+ * / the only copy of CI's work).
+ *
+ * NOTE: this strategy assumes the slug is already CLAIMED (the same contract as
+ * the job-worktree strategy, whose caller claims before `prepare`). It does not
+ * itself claim — `do-in-place` composes the claim (and `start`/`complete`) around
+ * the seam. `prepare` here is the thin "put the checkout on a fresh work branch"
+ * step the shared pipeline needs; it is unwired in this task.
+ */
+export declare function inPlaceStrategy(options: {
+    /** The current checkout to operate in. */
+    checkout: string;
+    /** Name of the checkout's arbiter git remote. Defaults to `origin`. */
+    arbiter?: string;
+}): IsolationStrategy;
+/** How {@link selectIsolationStrategy} chooses between the two strategies. */
+export interface SelectIsolationInput {
+    /**
+     * The current checkout, when there IS one (the human's clone / CI container).
+     * Its presence selects the **in-place** strategy. Absent ⇒ the **job-worktree**
+     * strategy (materialise a mirror + worktree in the agents' area).
+     */
+    checkout?: string;
+    /**
+     * A working repo to resolve the arbiter URL from for the job-worktree
+     * strategy (with `arbiter`). Required when `checkout` is absent.
+     */
+    fromRepo?: string;
+    /** Arbiter remote name (default `origin`), used by either strategy. */
+    arbiter?: string;
+    /** The execution working area for the job-worktree strategy (`workspacesDir`). */
+    workspacesDir?: string;
+}
+/**
+ * Select the isolation strategy by **"is there a checkout"** (ADR §3) — NOT a
+ * hardcoded path:
+ *
+ *   - `checkout` present ⇒ {@link inPlaceStrategy} (the checkout IS the
+ *     isolation; `do <slug>` in a checkout, the in-place human path).
+ *   - `checkout` absent ⇒ {@link jobWorktreeStrategy} (mirror + worktree in the
+ *     agents' area; `do --remote` / `run`).
+ *
+ * Both yield the same uniform handle, so the caller's pipeline is identical
+ * regardless of which strategy was selected.
+ */
+export declare function selectIsolationStrategy(input: SelectIsolationInput): IsolationStrategy;
+//# sourceMappingURL=isolation.d.ts.map

package/dist/isolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolation.d.ts","sourceRoot":"","sources":["../src/isolation.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,GAAG,EAAC,MAAM,gBAAgB,CAAC;AAOnD,OAAO,EAAgB,KAAK,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;;;;OASG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,GAAG,IAAI,CAAC;CACjD;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC5B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAAC;IAC3C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAAC;CAC3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC5C,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;CACtB,GAAG,iBAAiB,CAepB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,GAChC,YAAY,CA6Bd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACxC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,iBAAiB,CA+IpB;AA4CD,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,oBAAoB,GACzB,iBAAiB,CAkBnB"}