dorfl 0.0.0 → 0.1.0

package/dist/gc.d.ts

@@ -0,0 +1,165 @@
+import { type JobRecord } from './workspace.js';
+/**
+ * Why a job's worktree was retained (not provably safe to remove). The reaper
+ * surfaces exactly one of these per retained job (the FIRST failing clause, in
+ * predicate order: dirty tree dominates, then arbiter-reachability).
+ */
+export type RetainReason = 'dirty-tree' | 'unmerged-commits' | 'branch-not-pushed';
+/** Human-readable text for each retain reason (used in `gc` reports). */
+export declare const RETAIN_REASON_TEXT: Record<RetainReason, string>;
+/** How a job's branch tip is reachable on the arbiter (when it is). */
+export type ReachableVia = 'merged' | 'pushed';
+/** The result of applying the deletion-safety predicate to one job worktree. */
+export interface SafetyVerdict {
+    /** True iff the worktree is provably safe to remove (clean AND reachable). */
+    safe: boolean;
+    /** When `safe`, HOW the tip is reachable on the arbiter. */
+    reachableVia?: ReachableVia;
+    /** When NOT `safe`, why it was retained. */
+    reason?: RetainReason;
+}
+export interface EvaluateSafetyInput {
+    /** The job worktree directory to evaluate. */
+    dir: string;
+    /** The work branch checked out there (`work/<slug>`). */
+    branch: string;
+    /**
+     * The arbiter remote name valid inside the worktree. Defaults to `origin`
+     * (the bare hub mirror's clone remote — ADR §2). Tests with a different
+     * layout can override it.
+     */
+    arbiter?: string;
+    /**
+     * Drop the CLEAN-TREE half of the predicate, keeping ONLY the
+     * reachable-on-arbiter half. A worktree whose durable branch is provably on
+     * the arbiter is then safe to reap EVEN WHEN its tree has incidental churn
+     * (uncommitted doc-churn / artefacts) — because the durable artefact is the
+     * PUSHED branch, not the worktree files.
+     *
+     * Scoped, deliberate opt-in for the FAILURE-return path of `performDoRemote`,
+     * where the needs-attention seam has ALREADY surfaced the item + pushed the
+     * branch, so we KNOW the work is safe. The reachability half is NEVER dropped
+     * (we never reap work not yet on the arbiter — never lose work). The default
+     * (`false`) keeps the full clean-AND-reachable predicate the clean-completion
+     * path and `gc`'s default sweep use unchanged.
+     */
+    reachableOnly?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Apply the provably-safe deletion predicate (ADR §4) to ONE job worktree:
+ *
+ *   1. the working tree must be **clean** (no uncommitted changes), AND
+ *   2. the branch tip must be **reachable on the arbiter** — merged
+ *      (`merge-base --is-ancestor <tip> <arbiter>/main`) OR pushed
+ *      (`<arbiter>/<branch>` tip == local tip).
+ *
+ * Reaches out to the arbiter (a `git fetch`) so the remote-tracking refs reflect
+ * the live arbiter before checking reachability. Never mutates the worktree.
+ * Pure verdict — the caller decides whether to reap.
+ */
+export declare function evaluateDeletionSafety(input: EvaluateSafetyInput): SafetyVerdict;
+export interface ReapInput extends EvaluateSafetyInput {
+    /**
+     * The bare hub mirror the worktree was cut from. `git worktree remove` +
+     * `prune` are run there (the worktree's registration lives on the mirror).
+     */
+    mirrorPath: string;
+    /**
+     * Override the predicate: remove the worktree even when NOT provably safe
+     * (discard un-saved work). Loud + explicit — NEVER the default (ADR §4).
+     */
+    force?: boolean;
+}
+export interface ReapResult {
+    /** True iff the worktree was actually removed. */
+    removed: boolean;
+    /** The verdict the decision was based on. */
+    verdict: SafetyVerdict;
+    /** True iff removal happened only because `force` overrode the predicate. */
+    forced: boolean;
+}
+/**
+ * Auto-reap ONE job worktree iff the predicate holds (or `force` overrides):
+ * `git worktree remove` then `git worktree prune` on the hub mirror — NEVER a
+ * bare `rm -rf` (ADR §4). Returns whether it removed the worktree + the verdict
+ * it acted on (so the caller can report a retained job's reason).
+ *
+ * Used at end-of-job (the runner calls it after integrating) and by `gc` (the
+ * catch-up when auto-reap didn't run). A job whose work is NOT on the arbiter is
+ * never removed here (force is the only override, and it is explicit).
+ */
+export declare function reapJob(input: ReapInput): ReapResult;
+/** One job the `gc` sweep evaluated. */
+export interface GcJob {
+    /** Absolute path to the job worktree. */
+    dir: string;
+    /** The work slug (from the record, else derived from the dir name). */
+    slug: string;
+    /** The work branch (`work/<slug>`). */
+    branch: string;
+    /** The per-job record, when present. */
+    record?: JobRecord;
+}
+/** A worktree `gc` reaped (provably safe, or forced). */
+export interface ReapedJob extends GcJob {
+    verdict: SafetyVerdict;
+    /** True iff removed only because `--force` overrode the predicate. */
+    forced: boolean;
+}
+/** A worktree `gc` retained, with the human-readable reason it kept it. */
+export interface RetainedJob extends GcJob {
+    reason: RetainReason;
+    /** Human-readable reason text (`RETAIN_REASON_TEXT[reason]`). */
+    reasonText: string;
+}
+export interface GcOptions {
+    /** The execution working area (config `workspacesDir`, default `~/.dorfl`). */
+    workspacesDir: string;
+    /**
+     * Override the predicate for EVERY job: discard un-saved work. Loud +
+     * explicit (the CLI guards it behind a confirmation) — NEVER the default.
+     */
+    force?: boolean;
+    /** Sink for human-readable progress notes (per reaped / retained job). */
+    note?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+export interface GcResult {
+    /** The worktrees reaped this sweep (provably safe, or forced). */
+    reaped: ReapedJob[];
+    /** The worktrees retained, each with a clear reason. */
+    retained: RetainedJob[];
+}
+/**
+ * Re-apply the deletion-safety predicate across every `<workspacesDir>/work/*`
+ * job (ADR §4): reap the provably-safe ones, RETAIN the rest and report each
+ * with a clear reason. This is the safety-net catch-up for when auto-reap didn't
+ * run (a runner crash/kill left the worktree behind).
+ *
+ * `force: true` overrides the predicate for every job (discard un-saved work) —
+ * loud + explicit (the CLI confirms first), NEVER the default. A job whose work
+ * is NOT on the arbiter is never auto-removed without `force`.
+ */
+export declare function gc(options: GcOptions): GcResult;
+/**
+ * Discover every job worktree under `<workspacesDir>/work/*` (the flat layout —
+ * ADR §2). The per-job record is a SIBLING of the worktree dir
+ * (`<work-id>.json` next to `<work-id>/`, {@link jobRecordPath}) — OUTSIDE the
+ * checked-out tree so it can never be swept into a commit — so a work-id dir is
+ * a job iff its sibling record file exists (with a LEGACY fallback to an in-tree
+ * record left by an old binary, via {@link readJobRecord}). The branch comes
+ * from the record (falling back to `work/<derived-slug>`).
+ */
+export declare function discoverJobs(workspacesDir: string): GcJob[];
+/**
+ * True iff `ancestor` is an ancestor of (or equal to) `descendant`, both
+ * resolved IN the local repo `dir` (`git merge-base --is-ancestor`). This is the
+ * ONE provably-merged reachability predicate in the system: the worktree reaper
+ * above uses it for `<tip> --is-ancestor <arbiter>/main`, and the remote
+ * merged-branch sweep (`reap-branches.ts`) REUSES it (not a second predicate) to
+ * decide a remote `work/<slug>` branch is provably merged before deleting it.
+ * EXPORTED so that single source of truth is shared, never forked.
+ */
+export declare function isAncestor(dir: string, ancestor: string, descendant: string, env: NodeJS.ProcessEnv | undefined): boolean;
+//# sourceMappingURL=gc.d.ts.map

package/dist/gc.d.ts.map

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

package/dist/gc.js

@@ -0,0 +1,313 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { git, run } from './git.js';
+import { JOB_RECORD_FILENAME, jobRecordPath, readJobRecord, removeJobRecord, } from './workspace.js';
+import { workBranchRef } from './slug-namespace.js';
+/**
+ * The **reaper** for job worktrees, governed by the **provably-safe deletion
+ * predicate** (ADR §4 in `docs/adr/execution-substrate-decisions.md`, the
+ * authoritative source). Split out of `agent-workspaces` so the substrate stays
+ * thin; this module owns deletion.
+ *
+ * A job's worktree is removed (auto, at end-of-job; or by `gc`) **iff**:
+ *
+ *   1. its working tree is **clean** (no uncommitted changes), AND
+ *   2. its branch tip is **reachable on the arbiter** — either merged into
+ *      `<arbiter>/main` (`git merge-base --is-ancestor <tip> <arbiter>/main`),
+ *      OR pushed as an up-to-date branch (`<arbiter>/<branch>` tip == local tip).
+ *
+ * Both hold ⇒ the worktree is genuinely redundant (reconstructible from the
+ * arbiter) ⇒ remove. Otherwise ⇒ **retain for the human** (a retained worktree
+ * is a reliable "needs attention" signal that dovetails with `watch`'s
+ * surface-failures rail).
+ *
+ * The trigger is **provable safety, not "success"**: a successful-but-unpushed
+ * job is retained; a job whose commits are on the arbiter is reaped. One rule,
+ * no done-vs-failed special-casing. Removal is always `git worktree remove`
+ * (+ prune), NEVER a bare `rm -rf` (which would leave a dangling worktree
+ * registration on the hub).
+ *
+ * `--force` overrides the predicate (discard un-saved work) — it must be loud
+ * and explicit, NEVER the default.
+ */
+/** The arbiter remote name valid INSIDE a job worktree (ADR §2: cut from the
+ * bare hub mirror whose clone remote is `origin`). */
+const ARBITER_REMOTE = 'origin';
+/** Human-readable text for each retain reason (used in `gc` reports). */
+export const RETAIN_REASON_TEXT = {
+    'dirty-tree': 'dirty tree (uncommitted changes)',
+    'unmerged-commits': 'unmerged commits (branch tip not on the arbiter)',
+    'branch-not-pushed': 'branch not pushed (remote tip differs from local tip)',
+};
+/**
+ * Apply the provably-safe deletion predicate (ADR §4) to ONE job worktree:
+ *
+ *   1. the working tree must be **clean** (no uncommitted changes), AND
+ *   2. the branch tip must be **reachable on the arbiter** — merged
+ *      (`merge-base --is-ancestor <tip> <arbiter>/main`) OR pushed
+ *      (`<arbiter>/<branch>` tip == local tip).
+ *
+ * Reaches out to the arbiter (a `git fetch`) so the remote-tracking refs reflect
+ * the live arbiter before checking reachability. Never mutates the worktree.
+ * Pure verdict — the caller decides whether to reap.
+ */
+export function evaluateDeletionSafety(input) {
+    const env = input.env;
+    const arbiter = input.arbiter ?? ARBITER_REMOTE;
+    // 1. Clean tree? Dirty dominates (we never reap over uncommitted work) —
+    //    UNLESS `reachableOnly` was opted into (the failure path, where the branch
+    //    is already pushed so the durable artefact is the branch, not the tree).
+    if (input.reachableOnly !== true && !isWorkingTreeClean(input.dir, env)) {
+        return { safe: false, reason: 'dirty-tree' };
+    }
+    // Refresh the arbiter's refs so reachability is checked against the LIVE
+    // arbiter (not a stale local mirror). A job worktree is cut from a bare hub
+    // mirror whose `origin` remote has NO fetch refspec (so `origin/main` /
+    // `origin/<branch>` would not otherwise resolve) — so we fetch the two refs
+    // we need EXPLICITLY into remote-tracking refs (the same technique
+    // `integrator.rebaseOntoArbiterMain` uses). A plain `git fetch origin` would
+    // instead try to clobber the checked-out branch on a mirror. Best-effort: an
+    // unreachable arbiter leaves the local refs in place and the predicate reads
+    // as not-reachable → retain (the safe direction).
+    fetchTracking(input.dir, arbiter, 'main', env);
+    fetchTracking(input.dir, arbiter, input.branch, env);
+    const localTip = revParse(input.dir, 'HEAD', env);
+    // 2a. Merged: the tip is an ancestor of <arbiter>/main.
+    if (isAncestor(input.dir, localTip, `refs/remotes/${arbiter}/main`, env)) {
+        return { safe: true, reachableVia: 'merged' };
+    }
+    // 2b. Pushed: <arbiter>/<branch> exists AND its tip == the local tip.
+    const remoteTip = revParseOrUndefined(input.dir, `refs/remotes/${arbiter}/${input.branch}`, env);
+    if (remoteTip !== undefined && remoteTip === localTip) {
+        return { safe: true, reachableVia: 'pushed' };
+    }
+    // Clean, but NOT on the arbiter: distinguish "a remote branch exists but its
+    // tip differs (un-pushed amend)" from "no remote presence at all".
+    if (remoteTip !== undefined) {
+        return { safe: false, reason: 'branch-not-pushed' };
+    }
+    return { safe: false, reason: 'unmerged-commits' };
+}
+/**
+ * Auto-reap ONE job worktree iff the predicate holds (or `force` overrides):
+ * `git worktree remove` then `git worktree prune` on the hub mirror — NEVER a
+ * bare `rm -rf` (ADR §4). Returns whether it removed the worktree + the verdict
+ * it acted on (so the caller can report a retained job's reason).
+ *
+ * Used at end-of-job (the runner calls it after integrating) and by `gc` (the
+ * catch-up when auto-reap didn't run). A job whose work is NOT on the arbiter is
+ * never removed here (force is the only override, and it is explicit).
+ */
+export function reapJob(input) {
+    const verdict = evaluateDeletionSafety(input);
+    const force = input.force === true;
+    if (!verdict.safe && !force) {
+        return { removed: false, verdict, forced: false };
+    }
+    removeWorktree(input.mirrorPath, input.dir, input.branch, input.env);
+    return { removed: true, verdict, forced: !verdict.safe };
+}
+/**
+ * Re-apply the deletion-safety predicate across every `<workspacesDir>/work/*`
+ * job (ADR §4): reap the provably-safe ones, RETAIN the rest and report each
+ * with a clear reason. This is the safety-net catch-up for when auto-reap didn't
+ * run (a runner crash/kill left the worktree behind).
+ *
+ * `force: true` overrides the predicate for every job (discard un-saved work) —
+ * loud + explicit (the CLI confirms first), NEVER the default. A job whose work
+ * is NOT on the arbiter is never auto-removed without `force`.
+ */
+export function gc(options) {
+    const note = options.note ?? (() => { });
+    const env = options.env;
+    const reaped = [];
+    const retained = [];
+    for (const job of discoverJobs(options.workspacesDir)) {
+        const mirrorPath = resolveMirrorPath(options.workspacesDir, job);
+        const result = reapJob({
+            dir: job.dir,
+            branch: job.branch,
+            mirrorPath,
+            force: options.force,
+            env,
+        });
+        if (result.removed) {
+            reaped.push({ ...job, verdict: result.verdict, forced: result.forced });
+            note(result.forced
+                ? `Reaped ${job.slug} (FORCED — discarded un-saved work).`
+                : `Reaped ${job.slug} (${result.verdict.reachableVia}).`);
+            continue;
+        }
+        const reason = result.verdict.reason ?? 'unmerged-commits';
+        const reasonText = RETAIN_REASON_TEXT[reason];
+        retained.push({ ...job, reason, reasonText });
+        note(`Retained ${job.slug}: ${reasonText}.`);
+    }
+    return { reaped, retained };
+}
+/**
+ * Discover every job worktree under `<workspacesDir>/work/*` (the flat layout —
+ * ADR §2). The per-job record is a SIBLING of the worktree dir
+ * (`<work-id>.json` next to `<work-id>/`, {@link jobRecordPath}) — OUTSIDE the
+ * checked-out tree so it can never be swept into a commit — so a work-id dir is
+ * a job iff its sibling record file exists (with a LEGACY fallback to an in-tree
+ * record left by an old binary, via {@link readJobRecord}). The branch comes
+ * from the record (falling back to `work/<derived-slug>`).
+ */
+export function discoverJobs(workspacesDir) {
+    const workDir = join(workspacesDir, 'work');
+    if (!existsSync(workDir)) {
+        return [];
+    }
+    const jobs = [];
+    for (const entry of readdirSync(workDir)) {
+        const dir = join(workDir, entry);
+        let isDir;
+        try {
+            isDir = statSync(dir).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDir) {
+            continue; // skip the sibling `<work-id>.json` record files themselves
+        }
+        // A job iff a record exists — the sibling path first, then the legacy
+        // in-tree path (an old-binary worktree). Mirrors `readJobRecord`'s order.
+        if (!existsSync(jobRecordPath(dir)) &&
+            !existsSync(join(dir, JOB_RECORD_FILENAME))) {
+            continue; // not a job worktree (no record at either location)
+        }
+        const record = readJobRecord(dir);
+        const slug = record?.slug ?? deriveSlug(entry);
+        // The job record carries the (already-namespaced) branch — the SOURCE OF
+        // TRUTH. Only when a record is missing/legacy do we synthesise a fallback;
+        // the flat work-id dir name cannot recover the type, so default to the
+        // overwhelmingly-common `task` namespace (a recordless worktree is a rare
+        // legacy/corrupt case).
+        const branch = record?.branch ?? workBranchRef('task', slug);
+        jobs.push({ dir, slug, branch, record });
+    }
+    return jobs;
+}
+/** Derive a slug from a flat work-id dir name (`host__org__repo__slug`). */
+function deriveSlug(workId) {
+    const parts = workId.split('__');
+    return parts[parts.length - 1] || workId;
+}
+/**
+ * The hub mirror a job worktree was cut from. We do NOT reconstruct it from the
+ * encoded repo key (the key may not round-trip the arbiter URL): a worktree's
+ * `.git` file points at its mirror's `worktrees/<id>` admin dir, so we read the
+ * mirror's common dir directly from the worktree (robust + layout-agnostic).
+ */
+function resolveMirrorPath(workspacesDir, job) {
+    const common = run('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], job.dir);
+    const dir = common.stdout.trim();
+    if (common.status === 0 && dir !== '') {
+        return dir;
+    }
+    // Fallback: the repos hub under the workspaces dir (best-effort).
+    return join(workspacesDir, 'repos');
+}
+/**
+ * True iff the working tree has NO uncommitted WORK (tracked, staged, or
+ * untracked). The agent's edits and any untracked artefacts count: untracked
+ * work is still un-saved work.
+ *
+ * The `.dorfl-job.json` exclusion below is now INERT: the per-job record
+ * lives at a SIBLING path OUTSIDE the worktree, so it can no longer appear in
+ * the worktree's `git status` at all. It used to be load-bearing (the record
+ * was written INSIDE the worktree, so a perfectly-saved job would otherwise read
+ * as "dirty" purely because the runner wrote its own state file there). It is
+ * kept as a harmless no-op that still names the record for a hypothetical
+ * old-binary worktree whose record is still in-tree (the read-fallback case);
+ * removing it would only risk regressing that edge with no upside. The
+ * `work/`-ledger exclusion is a SEPARATE concern and stays.
+ */
+function isWorkingTreeClean(dir, env) {
+    // `status --porcelain` prints one line per change; empty ⇒ clean. Includes
+    // staged, unstaged, and untracked files.
+    const res = run('git', ['status', '--porcelain'], dir, { env });
+    if (res.status !== 0) {
+        // Can't determine cleanliness ⇒ treat as dirty (the safe direction).
+        return false;
+    }
+    const lines = res.stdout
+        .split('\n')
+        .map((l) => l.trimEnd())
+        .filter((l) => l !== '');
+    // Each porcelain line is `XY <path>` (path starts at column 3). Drop the
+    // runner's own job-record line; any remaining change ⇒ genuinely dirty.
+    const work = lines.filter((l) => l.slice(3).trim() !== JOB_RECORD_FILENAME);
+    return work.length === 0;
+}
+/**
+ * Fetch a single arbiter head into its remote-tracking ref EXPLICITLY
+ * (`+refs/heads/<head>:refs/remotes/<arbiter>/<head>`). A bare hub mirror has no
+ * fetch refspec, so this is the only way the remote-tracking ref exists; it is
+ * also harmless on a normal clone. Best-effort: the arbiter may be unreachable
+ * (offline) or the head may not exist there — either way the local ref simply
+ * stays absent/stale and the predicate reads as not-reachable → retain.
+ */
+function fetchTracking(dir, arbiter, head, env) {
+    run('git', [
+        'fetch',
+        '--quiet',
+        arbiter,
+        `+refs/heads/${head}:refs/remotes/${arbiter}/${head}`,
+    ], dir, { env });
+}
+/**
+ * True iff `ancestor` is an ancestor of (or equal to) `descendant`, both
+ * resolved IN the local repo `dir` (`git merge-base --is-ancestor`). This is the
+ * ONE provably-merged reachability predicate in the system: the worktree reaper
+ * above uses it for `<tip> --is-ancestor <arbiter>/main`, and the remote
+ * merged-branch sweep (`reap-branches.ts`) REUSES it (not a second predicate) to
+ * decide a remote `work/<slug>` branch is provably merged before deleting it.
+ * EXPORTED so that single source of truth is shared, never forked.
+ */
+export function isAncestor(dir, ancestor, descendant, env) {
+    const res = run('git', ['merge-base', '--is-ancestor', ancestor, descendant], dir, { env });
+    return res.status === 0;
+}
+/** Resolve a ref to its 40-hex sha (throws if it doesn't resolve). */
+function revParse(dir, ref, env) {
+    return git(['rev-parse', '--verify', '--quiet', ref], dir, { env }).trim();
+}
+/** Resolve a ref to its sha, or `undefined` if it doesn't resolve. */
+function revParseOrUndefined(dir, ref, env) {
+    const res = run('git', ['rev-parse', '--verify', '--quiet', ref], dir, { env });
+    if (res.status !== 0) {
+        return undefined;
+    }
+    const sha = res.stdout.trim();
+    return sha === '' ? undefined : sha;
+}
+/**
+ * Remove a job worktree the contract-safe way: `git worktree remove` then
+ * `git worktree prune` on the hub mirror, plus dropping the now-orphaned work
+ * branch AND the now-orphaned per-job record (a SIBLING of the worktree since
+ * the relocation — it no longer goes away WITH the worktree dir, so we delete it
+ * explicitly so a reaped job leaves no `<work-id>.json` litter). NEVER a bare
+ * `rm -rf` of the WORKTREE (ADR §4): a raw delete leaves a dangling worktree
+ * registration on the hub. Best-effort on prune/branch-drop/record (idempotent
+ * re-runs of `gc` must not error on an already-clean hub).
+ */
+function removeWorktree(mirrorPath, dir, branch, env) {
+    git(['worktree', 'remove', '--force', dir], mirrorPath, { env });
+    removeJobRecord(dir);
+    try {
+        git(['worktree', 'prune'], mirrorPath, { env });
+    }
+    catch {
+        // best-effort
+    }
+    try {
+        git(['branch', '-D', branch], mirrorPath, { env });
+    }
+    catch {
+        // branch may already be gone
+    }
+}
+//# sourceMappingURL=gc.js.map

package/dist/gc.js.map

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

package/dist/gh-failure.d.ts

@@ -0,0 +1,42 @@
+import { type RunResult } from './git.js';
+/**
+ * **Shared `gh`-failure diagnostics** for the two `gh`-backed provider seams (the
+ * review-request `GitHubProvider` in `github.ts` and the `GitHubIssueProvider` in
+ * `issue-provider.ts`).
+ *
+ * Both providers shell out to `gh` and must, on a failure, surface the REAL cause
+ * — the actual `gh` stderr (a rate-limit, a permissions error, a transient 5xx),
+ * NOT a hard-coded "`gh` is unavailable or unauthenticated" guess that sends an
+ * operator chasing a phantom auth problem. This module is the single source of
+ * truth for that distillation so the two providers can NEVER drift apart on the
+ * next fix (the drift the original hard-coded strings created).
+ *
+ * Both `gh`-shelling helpers (`runGh`) return `RunResult | undefined`, where
+ * `undefined` = the `gh` BINARY could not be spawned (missing / not on `PATH`).
+ * That case has no `RunResult` to read, so the PAIR below resolves it to a fixed
+ * "binary missing" string and reserves {@link ghFailureReason} for a genuine
+ * `RunResult`.
+ */
+/** The fixed reason for a missing/unspawnable `gh` binary (no `RunResult` to read). */
+export declare const GH_BINARY_MISSING = "`gh` is not available (binary missing).";
+/**
+ * Distil the REAL reason a `gh` invocation failed from its result — the trimmed
+ * stderr (the actual cause, e.g. `'dorfl:processing' not found`), falling
+ * back to the exit status when stderr is empty. This is what replaces the old
+ * hard-coded "unavailable or unauthenticated" guess: the cause must be diagnosable.
+ *
+ * Requires a NON-undefined `RunResult` (it reads `stderr`/`status`); a missing
+ * binary (`undefined`) has no result to read — use {@link ghFailureDetail} when
+ * the value may be `undefined`.
+ */
+export declare function ghFailureReason(result: RunResult): string;
+/**
+ * Resolve the real failure detail for a `gh` shell-out whose result MAY be
+ * `undefined` (binary missing) — the two-arm guard both providers' degrade paths
+ * need: a missing binary yields the fixed {@link GH_BINARY_MISSING} string, and
+ * only a genuine `RunResult` is passed to {@link ghFailureReason}. This keeps the
+ * undefined-vs-`RunResult` split in ONE place so no degrade branch ever calls
+ * `ghFailureReason(undefined)`.
+ */
+export declare function ghFailureDetail(result: RunResult | undefined): string;
+//# sourceMappingURL=gh-failure.d.ts.map

package/dist/gh-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gh-failure.d.ts","sourceRoot":"","sources":["../src/gh-failure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,SAAS,EAAC,MAAM,UAAU,CAAC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AAEH,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,4CAA4C,CAAC;AAE3E;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAMzD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAErE"}

package/dist/gh-failure.js

@@ -0,0 +1,49 @@
+/**
+ * **Shared `gh`-failure diagnostics** for the two `gh`-backed provider seams (the
+ * review-request `GitHubProvider` in `github.ts` and the `GitHubIssueProvider` in
+ * `issue-provider.ts`).
+ *
+ * Both providers shell out to `gh` and must, on a failure, surface the REAL cause
+ * — the actual `gh` stderr (a rate-limit, a permissions error, a transient 5xx),
+ * NOT a hard-coded "`gh` is unavailable or unauthenticated" guess that sends an
+ * operator chasing a phantom auth problem. This module is the single source of
+ * truth for that distillation so the two providers can NEVER drift apart on the
+ * next fix (the drift the original hard-coded strings created).
+ *
+ * Both `gh`-shelling helpers (`runGh`) return `RunResult | undefined`, where
+ * `undefined` = the `gh` BINARY could not be spawned (missing / not on `PATH`).
+ * That case has no `RunResult` to read, so the PAIR below resolves it to a fixed
+ * "binary missing" string and reserves {@link ghFailureReason} for a genuine
+ * `RunResult`.
+ */
+/** The fixed reason for a missing/unspawnable `gh` binary (no `RunResult` to read). */
+export const GH_BINARY_MISSING = '`gh` is not available (binary missing).';
+/**
+ * Distil the REAL reason a `gh` invocation failed from its result — the trimmed
+ * stderr (the actual cause, e.g. `'dorfl:processing' not found`), falling
+ * back to the exit status when stderr is empty. This is what replaces the old
+ * hard-coded "unavailable or unauthenticated" guess: the cause must be diagnosable.
+ *
+ * Requires a NON-undefined `RunResult` (it reads `stderr`/`status`); a missing
+ * binary (`undefined`) has no result to read — use {@link ghFailureDetail} when
+ * the value may be `undefined`.
+ */
+export function ghFailureReason(result) {
+    const stderr = result.stderr.trim();
+    if (stderr) {
+        return stderr;
+    }
+    return `\`gh\` exited ${result.status}.`;
+}
+/**
+ * Resolve the real failure detail for a `gh` shell-out whose result MAY be
+ * `undefined` (binary missing) — the two-arm guard both providers' degrade paths
+ * need: a missing binary yields the fixed {@link GH_BINARY_MISSING} string, and
+ * only a genuine `RunResult` is passed to {@link ghFailureReason}. This keeps the
+ * undefined-vs-`RunResult` split in ONE place so no degrade branch ever calls
+ * `ghFailureReason(undefined)`.
+ */
+export function ghFailureDetail(result) {
+    return result === undefined ? GH_BINARY_MISSING : ghFailureReason(result);
+}
+//# sourceMappingURL=gh-failure.js.map

package/dist/gh-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gh-failure.js","sourceRoot":"","sources":["../src/gh-failure.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,yCAAyC,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,MAAiB;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,MAAM,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC;IACf,CAAC;IACD,OAAO,iBAAiB,MAAM,CAAC,MAAM,GAAG,CAAC;AAC1C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAA6B;IAC5D,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;AAC3E,CAAC"}