dorfl 0.11.1 → 0.11.3

package/dist/worktree-writer-lock.d.ts

@@ -0,0 +1,99 @@
+/**
+ * **The per-WORKING-TREE writer sentinel** (observation
+ * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+ *
+ * The per-item lock (`item-lock.ts`) guards the ITEM: it answers "who owns this
+ * task?" and it is what claim / requeue / bounce move around. Nothing guarded the
+ * WORKING TREE. Those are different resources, and the deadline checkpoint is
+ * exactly where they come apart: the checkpoint releases the item lock so the
+ * next tick can continue the task, but the tree the previous agent was editing is
+ * reused by the successor. If the predecessor is still alive, two agents write to
+ * one tree.
+ *
+ * The primary fix is to reap the predecessor and VERIFY it is gone before the
+ * lock moves (`reap-agent-tree.ts`). This sentinel is the INDEPENDENT backstop:
+ * even if a live writer survives by some route the reap did not cover (a
+ * deliberately `setsid`-ed grandchild, a stale run from a crashed runner, an
+ * operator manually re-driving an item), a second agent physically cannot onboard
+ * into a tree that already has a LIVE holder. It is deliberately keyed on the
+ * TREE, not on the item: two different items sharing one worktree is just as
+ * unsafe as two attempts at the same item.
+ *
+ * ## Where the sentinel lives, and why not in the tree
+ *
+ * It is written to the worktree's PRIVATE git directory (`git rev-parse
+ * --absolute-git-dir`, which for a linked worktree is
+ * `.../.git/worktrees/<name>/`), NOT to a file inside the working tree. That
+ * placement is load-bearing:
+ *
+ *  - it is per-worktree (linked worktrees each get their own git dir), which is
+ *    precisely the granularity we are guarding;
+ *  - it can never appear in `git status`, so it cannot be mistaken for agent work,
+ *    cannot be swept into a commit by a `git add -A`, and needs no new exclusion
+ *    in the empty-diff backstop / `gc`'s cleanliness predicate (unlike
+ *    `.dorfl-job.json`, which each of those has to filter out by name);
+ *  - it is removed with the worktree, so it cannot outlive what it guards.
+ *
+ * ## Liveness, not presence
+ *
+ * A pid file that only records presence becomes a permanent blocker the first
+ * time a runner is `kill -9`ed. So the holder is checked for LIVENESS (its
+ * process group first, falling back to its pid) and a dead holder's sentinel is
+ * treated as stale and taken over. Only a genuinely live foreign writer refuses.
+ */
+/** The sentinel filename inside the worktree's private git directory. */
+export declare const WRITER_SENTINEL_FILENAME = "dorfl-writer.json";
+/** The recorded holder of a worktree's writer sentinel. */
+export interface WorktreeWriter {
+    /** The runner process that owns the agent writing in this tree. */
+    pid: number;
+    /** The agent's process GROUP, when the harness spawned a killable one. */
+    pgid?: number;
+    /** The item being built in this tree (diagnostics: names the other writer). */
+    slug: string;
+    /** ISO timestamp of acquisition (diagnostics: how long it has been held). */
+    startedAt: string;
+}
+/** The outcome of trying to become a worktree's sole writer. */
+export type WorktreeWriterLock = {
+    acquired: true;
+    /** Release the sentinel. Idempotent, and safe if it was already stolen. */
+    release(): void;
+} | {
+    acquired: false;
+    /** The LIVE holder that refused us (when it could be parsed). */
+    holder?: WorktreeWriter;
+    /** Human-readable refusal, naming the other writer. */
+    reason: string;
+};
+/** The sentinel path for `dir`, or `undefined` when `dir` is not a worktree. */
+export declare function writerSentinelPath(dir: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** Read + parse the sentinel, or `undefined` when absent/corrupt. */
+export declare function readWorktreeWriter(dir: string, env?: NodeJS.ProcessEnv): WorktreeWriter | undefined;
+/**
+ * Is the recorded holder still running? Prefers the agent's process GROUP (which
+ * survives the group leader's death and so catches exactly the orphaned-writer
+ * case this exists for), and falls back to the runner pid.
+ */
+export declare function writerAlive(holder: WorktreeWriter): boolean;
+/**
+ * Claim `dir` as the SOLE agent-writable working tree for `slug`.
+ *
+ * Refuses when a DIFFERENT, still-LIVE writer holds it — the second-agent case
+ * the observation describes. A dead holder's sentinel is stale and is taken over
+ * silently (a `kill -9`ed runner must not poison the worktree forever), and our
+ * OWN pid re-acquiring is a no-op re-entry rather than a refusal.
+ *
+ * When `dir` is not a git worktree there is nowhere private to record the
+ * sentinel; that is reported as acquired with a no-op release, because this is a
+ * defence-in-depth backstop and must never become a new way for a legitimate run
+ * to fail.
+ */
+export declare function acquireWorktreeWriterLock(params: {
+    dir: string;
+    slug: string;
+    /** The agent's process group, when known (the strongest liveness anchor). */
+    pgid?: number;
+    env?: NodeJS.ProcessEnv;
+}): WorktreeWriterLock;
+//# sourceMappingURL=worktree-writer-lock.d.ts.map

package/dist/worktree-writer-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-writer-lock.d.ts","sourceRoot":"","sources":["../src/worktree-writer-lock.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC9B,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,gEAAgE;AAChE,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,EAAE,IAAI,CAAC;IACf,2EAA2E;IAC3E,OAAO,IAAI,IAAI,CAAC;CACf,GACD;IACA,QAAQ,EAAE,KAAK,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CACd,CAAC;AAmBL,gFAAgF;AAChF,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,GAAG,SAAS,CAKpB;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,cAAc,GAAG,SAAS,CAa5B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAK3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,kBAAkB,CAoDrB"}

package/dist/worktree-writer-lock.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { run } from './git.js';
+import { pidAlive } from './harness.js';
+import { processGroupAlive } from './reap-agent-tree.js';
+/**
+ * **The per-WORKING-TREE writer sentinel** (observation
+ * `checkpoint-releases-lock-while-predecessor-agent-still-writes`).
+ *
+ * The per-item lock (`item-lock.ts`) guards the ITEM: it answers "who owns this
+ * task?" and it is what claim / requeue / bounce move around. Nothing guarded the
+ * WORKING TREE. Those are different resources, and the deadline checkpoint is
+ * exactly where they come apart: the checkpoint releases the item lock so the
+ * next tick can continue the task, but the tree the previous agent was editing is
+ * reused by the successor. If the predecessor is still alive, two agents write to
+ * one tree.
+ *
+ * The primary fix is to reap the predecessor and VERIFY it is gone before the
+ * lock moves (`reap-agent-tree.ts`). This sentinel is the INDEPENDENT backstop:
+ * even if a live writer survives by some route the reap did not cover (a
+ * deliberately `setsid`-ed grandchild, a stale run from a crashed runner, an
+ * operator manually re-driving an item), a second agent physically cannot onboard
+ * into a tree that already has a LIVE holder. It is deliberately keyed on the
+ * TREE, not on the item: two different items sharing one worktree is just as
+ * unsafe as two attempts at the same item.
+ *
+ * ## Where the sentinel lives, and why not in the tree
+ *
+ * It is written to the worktree's PRIVATE git directory (`git rev-parse
+ * --absolute-git-dir`, which for a linked worktree is
+ * `.../.git/worktrees/<name>/`), NOT to a file inside the working tree. That
+ * placement is load-bearing:
+ *
+ *  - it is per-worktree (linked worktrees each get their own git dir), which is
+ *    precisely the granularity we are guarding;
+ *  - it can never appear in `git status`, so it cannot be mistaken for agent work,
+ *    cannot be swept into a commit by a `git add -A`, and needs no new exclusion
+ *    in the empty-diff backstop / `gc`'s cleanliness predicate (unlike
+ *    `.dorfl-job.json`, which each of those has to filter out by name);
+ *  - it is removed with the worktree, so it cannot outlive what it guards.
+ *
+ * ## Liveness, not presence
+ *
+ * A pid file that only records presence becomes a permanent blocker the first
+ * time a runner is `kill -9`ed. So the holder is checked for LIVENESS (its
+ * process group first, falling back to its pid) and a dead holder's sentinel is
+ * treated as stale and taken over. Only a genuinely live foreign writer refuses.
+ */
+/** The sentinel filename inside the worktree's private git directory. */
+export const WRITER_SENTINEL_FILENAME = 'dorfl-writer.json';
+/**
+ * The worktree's PRIVATE git directory, or `undefined` when `dir` is not a git
+ * worktree (in which case there is no sentinel location and the caller proceeds
+ * unguarded rather than failing — this is a backstop, not a gate).
+ */
+function worktreeGitDir(dir, env) {
+    const result = run('git', ['rev-parse', '--absolute-git-dir'], dir, { env });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    const path = result.stdout.trim();
+    return path === '' ? undefined : path;
+}
+/** The sentinel path for `dir`, or `undefined` when `dir` is not a worktree. */
+export function writerSentinelPath(dir, env) {
+    const gitDir = worktreeGitDir(dir, env);
+    return gitDir === undefined
+        ? undefined
+        : join(gitDir, WRITER_SENTINEL_FILENAME);
+}
+/** Read + parse the sentinel, or `undefined` when absent/corrupt. */
+export function readWorktreeWriter(dir, env) {
+    const path = writerSentinelPath(dir, env);
+    if (path === undefined || !existsSync(path)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed?.pid === 'number' ? parsed : undefined;
+    }
+    catch {
+        // A corrupt sentinel records nothing we can trust; treat it as absent so it
+        // self-heals on the next acquire rather than wedging the worktree forever.
+        return undefined;
+    }
+}
+/**
+ * Is the recorded holder still running? Prefers the agent's process GROUP (which
+ * survives the group leader's death and so catches exactly the orphaned-writer
+ * case this exists for), and falls back to the runner pid.
+ */
+export function writerAlive(holder) {
+    if (holder.pgid !== undefined && processGroupAlive(holder.pgid)) {
+        return true;
+    }
+    return pidAlive(holder.pid);
+}
+/**
+ * Claim `dir` as the SOLE agent-writable working tree for `slug`.
+ *
+ * Refuses when a DIFFERENT, still-LIVE writer holds it — the second-agent case
+ * the observation describes. A dead holder's sentinel is stale and is taken over
+ * silently (a `kill -9`ed runner must not poison the worktree forever), and our
+ * OWN pid re-acquiring is a no-op re-entry rather than a refusal.
+ *
+ * When `dir` is not a git worktree there is nowhere private to record the
+ * sentinel; that is reported as acquired with a no-op release, because this is a
+ * defence-in-depth backstop and must never become a new way for a legitimate run
+ * to fail.
+ */
+export function acquireWorktreeWriterLock(params) {
+    const { dir, slug, pgid, env } = params;
+    const path = writerSentinelPath(dir, env);
+    if (path === undefined) {
+        return { acquired: true, release: () => { } };
+    }
+    const existing = readWorktreeWriter(dir, env);
+    if (existing !== undefined &&
+        existing.pid !== process.pid &&
+        writerAlive(existing)) {
+        return {
+            acquired: false,
+            holder: existing,
+            reason: `worktree ${dir} already has a LIVE agent writer: pid ${existing.pid}` +
+                (existing.pgid !== undefined ? ` (group ${existing.pgid})` : '') +
+                ` building '${existing.slug}' since ${existing.startedAt}. Refusing to ` +
+                `onboard '${slug}' into the same working tree: two live agents in one ` +
+                'tree can clobber each other’s edits, and the second can commit the ' +
+                'first’s half-finished work under a message describing something else. ' +
+                'Wait for it to exit, or kill it, then retry.',
+        };
+    }
+    const record = {
+        pid: process.pid,
+        ...(pgid !== undefined ? { pgid } : {}),
+        slug,
+        startedAt: new Date().toISOString(),
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    let released = false;
+    return {
+        acquired: true,
+        release: () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            // Only remove a sentinel that is still OURS: if it was stolen as stale by
+            // another runner, deleting it would silently un-guard that runner's tree.
+            const current = readWorktreeWriter(dir, env);
+            if (current === undefined || current.pid === process.pid) {
+                rmSync(path, { force: true });
+            }
+        },
+    };
+}
+//# sourceMappingURL=worktree-writer-lock.js.map

package/dist/worktree-writer-lock.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dorfl",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wighawag/dorfl.git",

package/src/arbiter-refs.ts

@@ -0,0 +1,222 @@
+import {runAsync} from './git.js';
+
+/**
+ * **The ONE arbiter-ref refresh + authoritative-read seam** (observation
+ * `checkpoint-path-reports-its-own-write-as-absent`).
+ *
+ * Every "did my own write land?" / "is the branch on the arbiter?" question in
+ * the checkpoint + surface paths used to be answered the same wrong way: run a
+ * PLAIN `git fetch <arbiter>`, then `git rev-parse <arbiter>/<branch>` — i.e.
+ * read a REMOTE-TRACKING ref (`refs/remotes/<arbiter>/…`) and trust it. That is
+ * unsound in the configuration dorfl itself creates for `--isolated` runs, and
+ * it produced two field defects where dorfl reported its OWN successful write as
+ * absent:
+ *
+ *  1. A job worktree is `git worktree add`ed from the BARE HUB MIRROR
+ *     (`workspace.ts` `createJob` → `repo-mirror.ts` `ensureMirror`), whose
+ *     `origin` carries the MIRROR-style refspec `+refs/heads/*:refs/heads/*`.
+ *     So a plain fetch there writes `refs/heads/main`, and **never populates**
+ *     `refs/remotes/origin/main` at all. `rev-parse origin/main` then returns
+ *     whatever a PRIOR explicit-refspec fetch happened to leave behind — a value
+ *     that PREDATES the write being verified. A push that genuinely landed reads
+ *     back as "not our commit ⇒ rejected".
+ *  2. Worse, in that same worktree a plain `git fetch origin` **fails outright**
+ *     (`fatal: refusing to fetch into branch 'refs/heads/work/<slug>' checked out
+ *     at …`), because the mirror refspec's destination IS the branch the worktree
+ *     has checked out. So it refreshes NOTHING, and a follow-up
+ *     `rev-parse <arbiter>/work/<slug>` fails against a ref that never existed —
+ *     reported as "no work branch on <arbiter>" while the branch (and an hour of
+ *     agent work) sits on the arbiter.
+ *
+ * Both call sites now route through this module, which fixes the class rather
+ * than the two instances:
+ *
+ *   - {@link refreshArbiterRefs} prune-fetches with an EXPLICIT, per-branch
+ *     refspec into the `refs/remotes/<arbiter>/…` namespace the readers actually
+ *     read, tolerating the checked-out-branch refusal instead of being silently
+ *     defeated by it.
+ *   - {@link resolveArbiterBranch} answers the sha question from the ARBITER
+ *     ITSELF (`git ls-remote`), so no local ref-namespace/refspec accident can
+ *     make a landed write look absent. The local tracking ref is only a FALLBACK,
+ *     used when the arbiter cannot be reached at all.
+ *
+ * The `ls-remote`-is-authoritative stance is not new — it is the same one
+ * `continue-branch.ts` (`branchAheadOfArbiter`), `workspace.ts`, `integrator.ts`
+ * and `reap-branches.ts` already take for continue-detection and branch reaping.
+ * This module makes it the SHARED default for the post-write verification too,
+ * instead of each site re-deciding.
+ */
+
+/** How a {@link ResolvedArbiterBranch} sha was obtained — the read's PROVENANCE. */
+export type ArbiterRefAuthority =
+	/** Read from the arbiter itself (`git ls-remote`): AUTHORITATIVE. */
+	| 'arbiter'
+	/**
+	 * The arbiter could not be reached (offline / broken remote), so the local
+	 * remote-tracking ref was used. Best-effort: it may be stale, so a caller
+	 * deciding "did MY write land?" must NOT treat a mismatch here as proof of
+	 * a loss (see {@link ResolvedArbiterBranch.trustworthy}).
+	 */
+	| 'local-fallback'
+	/** Neither the arbiter nor any local ref has this branch. */
+	| 'absent';
+
+/** The resolved state of ONE branch on the arbiter (a single, coherent read). */
+export interface ResolvedArbiterBranch {
+	/** The unqualified branch name that was resolved (e.g. `main`, `work/task-x`). */
+	branch: string;
+	/** Its sha, or `undefined` when the branch exists nowhere we could look. */
+	sha?: string;
+	/** Where {@link sha} came from. */
+	authority: ArbiterRefAuthority;
+	/**
+	 * True iff the arbiter answered (`authority` is `arbiter` or `absent` off a
+	 * REACHABLE arbiter). When false the read is a stale-capable local fallback,
+	 * so a mismatch proves nothing and callers must not report a loss from it.
+	 */
+	trustworthy: boolean;
+	/** The `ls-remote` stderr when the arbiter could not be reached (diagnostics). */
+	unreachableDetail?: string;
+}
+
+/** The explicit refspec that maps an arbiter branch into the namespace we READ. */
+function trackingRefspec(arbiter: string, branch: string): string {
+	return `+refs/heads/${branch}:refs/remotes/${arbiter}/${branch}`;
+}
+
+/**
+ * PRUNE-FETCH the named arbiter branches into `refs/remotes/<arbiter>/<branch>`
+ * — the namespace every reader in this codebase actually reads — using an
+ * EXPLICIT per-branch refspec.
+ *
+ * Three properties matter, and all three are the reason this is not just
+ * `git fetch <arbiter>`:
+ *
+ *  - **Explicit refspec.** A bare-hub-mirror worktree's `origin` maps
+ *    `+refs/heads/*:refs/heads/*`, so a plain fetch never writes
+ *    `refs/remotes/<arbiter>/*`. Naming the destination makes the refresh work
+ *    identically in a normal clone AND in a mirror worktree.
+ *  - **`--prune`.** A branch DELETED on the arbiter (a `requeue --reset`, a
+ *    merge-reap, a cross-machine `gc`) must disappear from our view too;
+ *    otherwise a stale tracking ref answers a liveness question with a ghost.
+ *  - **Per-branch and SOFT.** Fetching branch-at-a-time means the one refspec
+ *    git refuses (the destination that is checked out in THIS worktree — see the
+ *    module doc) cannot abort the refresh of the others, which is exactly how the
+ *    single combined fetch silently refreshed nothing. Every failure is
+ *    tolerated and reported rather than thrown: this is a REFRESH, and the
+ *    authoritative answer comes from {@link resolveArbiterBranch} anyway.
+ *
+ * Returns the branches that could not be refreshed (for diagnostics only — a
+ * caller should not gate on it, because the authoritative read does not depend
+ * on the refresh succeeding).
+ */
+export async function refreshArbiterRefs(params: {
+	cwd: string;
+	arbiter: string;
+	/** Unqualified branch names to refresh (e.g. `['main', 'work/task-x']`). */
+	branches: readonly string[];
+	env?: NodeJS.ProcessEnv;
+}): Promise<{failed: string[]}> {
+	const {cwd, arbiter, branches, env} = params;
+	const failed: string[] = [];
+	for (const branch of branches) {
+		const fetched = await runAsync(
+			'git',
+			[
+				'fetch',
+				'--quiet',
+				'--prune',
+				arbiter,
+				trackingRefspec(arbiter, branch),
+			],
+			cwd,
+			{env},
+		);
+		if (fetched.status !== 0) {
+			failed.push(branch);
+		}
+	}
+	return {failed};
+}
+
+/**
+ * Resolve ONE branch's sha on the arbiter, ARBITER-AUTHORITATIVELY.
+ *
+ * `git ls-remote --heads <arbiter> <branch>` asks the arbiter directly, so the
+ * answer cannot be defeated by a local refspec/namespace accident — which is the
+ * whole point: this is the read a post-write verification uses to decide whether
+ * its OWN push landed, and that decision must never be made from a view that
+ * predates the push.
+ *
+ * Decision order:
+ *   - `ls-remote` exits 0 with a sha ⇒ `{sha, authority: 'arbiter'}` (trustworthy).
+ *   - `ls-remote` exits 0 with EMPTY output ⇒ the arbiter genuinely does not have
+ *     the branch ⇒ `{authority: 'absent'}` (trustworthy: a definite "no").
+ *   - `ls-remote` exits non-zero (unreachable / no such remote) ⇒ fall back to the
+ *     local `refs/remotes/<arbiter>/<branch>`, flagged `trustworthy: false` so a
+ *     caller cannot mistake a stale local read for proof of anything.
+ *
+ * Always call {@link refreshArbiterRefs} first when the caller ALSO needs the
+ * objects locally (a CAS base, a `merge-base` / `rev-list` comparison): a sha
+ * from `ls-remote` names a commit this repo may not have yet.
+ */
+export async function resolveArbiterBranch(params: {
+	cwd: string;
+	arbiter: string;
+	branch: string;
+	env?: NodeJS.ProcessEnv;
+}): Promise<ResolvedArbiterBranch> {
+	const {cwd, arbiter, branch, env} = params;
+	const ls = await runAsync(
+		'git',
+		['ls-remote', '--heads', arbiter, branch],
+		cwd,
+		{env},
+	);
+	if (ls.status === 0) {
+		// `<sha>\t<ref>` lines. `--heads <branch>` can match several refs when the
+		// name is a glob-ish prefix, so take the line whose ref is EXACTLY ours.
+		const sha = ls.stdout
+			.split('\n')
+			.map((line) => line.trim())
+			.filter((line) => line !== '')
+			.map((line) => line.split(/\s+/))
+			.find(([, ref]) => ref === `refs/heads/${branch}`)?.[0];
+		if (sha !== undefined && sha !== '') {
+			return {branch, sha, authority: 'arbiter', trustworthy: true};
+		}
+		// Reachable arbiter that does NOT have the branch: a definite, trustworthy
+		// "absent" (a stale local ref must not be able to resurrect it).
+		return {branch, authority: 'absent', trustworthy: true};
+	}
+	// Unreachable arbiter: best-effort local read, explicitly NOT trustworthy.
+	const local = await runAsync(
+		'git',
+		[
+			'rev-parse',
+			'--verify',
+			'--quiet',
+			`refs/remotes/${arbiter}/${branch}^{commit}`,
+		],
+		cwd,
+		{env},
+	);
+	const localSha = local.status === 0 ? local.stdout.trim() : '';
+	const unreachableDetail =
+		ls.stderr.trim() || `git ls-remote exit ${ls.status}`;
+	if (localSha !== '') {
+		return {
+			branch,
+			sha: localSha,
+			authority: 'local-fallback',
+			trustworthy: false,
+			unreachableDetail,
+		};
+	}
+	return {
+		branch,
+		authority: 'absent',
+		trustworthy: false,
+		unreachableDetail,
+	};
+}