dorfl 0.0.0 → 0.1.0

package/dist/repo-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-key.d.ts","sourceRoot":"","sources":["../src/repo-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD"}

package/dist/repo-key.js

@@ -0,0 +1,68 @@
+/**
+ * The arbiter-URL → **hub key** encoder, extracted from `repo-mirror.ts` so it
+ * is importable WITHOUT pulling in the rest of the hub-mirror plumbing (which
+ * itself depends on `repo-config.ts`). The split exists for ONE reason: the
+ * per-machine `config.override.json` layer (resolved in `repo-config.ts`)
+ * needs the hub key to look up the per-repo override bucket — but
+ * `repo-config.ts` cannot import from `repo-mirror.ts` without a cycle. The
+ * key encoder is pure (URL → string) and has no business depending on the
+ * mirror or the per-repo config, so it lives here. `repo-mirror.ts` re-exports
+ * {@link encodeRepoKey} so existing callers see no change.
+ */
+/**
+ * Deterministically encode an arbiter remote URL into a hierarchical hub key:
+ * drop the scheme / user / `.git` suffix, then replace `.` → `-` **per path
+ * segment** (lossless and reversible; avoids the dotted-segment hazard that
+ * trips editors / tools and our own dotdir-pruning). E.g.
+ * `git@github.com:wighawag/dorfl.git` → `github-com/wighawag/dorfl`.
+ */
+export function encodeRepoKey(url) {
+    const segments = urlSegments(url);
+    return segments.map(dashDots).join('/');
+}
+/**
+ * Split a remote URL into its host + path segments (lossy only of scheme/user/
+ * port/`.git`, which carry no identity for keying). Handles the four shapes the
+ * arbiter can take: scp-like ssh (`git@host:org/repo.git`), `ssh://`, `https://`
+ * / `http://`, `file://`, and a plain local filesystem path to a bare repo.
+ */
+function urlSegments(url) {
+    const trimmed = url.trim();
+    // scp-like ssh: [user@]host:path  (no `://`, has a `:` before the path).
+    const scp = /^(?:[^@/]+@)?([^/:]+):(.+)$/;
+    if (!trimmed.includes('://')) {
+        const m = scp.exec(trimmed);
+        if (m && !trimmed.startsWith('/')) {
+            return [m[1], ...pathSegments(m[2])];
+        }
+        // Otherwise a plain local path (e.g. `/srv/git/org/repo.git`).
+        return pathSegments(trimmed);
+    }
+    // scheme://[user@]host[:port]/path  — or file:///abs/path (empty host).
+    const schemeEnd = trimmed.indexOf('://');
+    const rest = trimmed.slice(schemeEnd + 3);
+    const slash = rest.indexOf('/');
+    const authority = slash === -1 ? rest : rest.slice(0, slash);
+    const path = slash === -1 ? '' : rest.slice(slash + 1);
+    const host = stripUserAndPort(authority);
+    const hostSegments = host === '' ? [] : [host];
+    return [...hostSegments, ...pathSegments(path)];
+}
+/** Drop `user@` and `:port` from an authority, leaving the bare host. */
+function stripUserAndPort(authority) {
+    const afterUser = authority.includes('@')
+        ? authority.slice(authority.lastIndexOf('@') + 1)
+        : authority;
+    const colon = afterUser.indexOf(':');
+    return colon === -1 ? afterUser : afterUser.slice(0, colon);
+}
+/** Split a `/`-path into non-empty segments, dropping a trailing `.git`. */
+function pathSegments(path) {
+    const noGit = path.replace(/\.git\/?$/, '');
+    return noGit.split('/').filter((s) => s.length > 0);
+}
+/** Replace every `.` with `-` within a single segment (per-segment, lossless). */
+function dashDots(segment) {
+    return segment.replace(/\./g, '-');
+}
+//# sourceMappingURL=repo-key.js.map

package/dist/repo-key.js.map

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

package/dist/repo-mirror.d.ts

@@ -0,0 +1,177 @@
+import type { Config, PartialConfig } from './config.js';
+import type { ConfigOverrideMap } from './config-override.js';
+export { encodeRepoKey } from './repo-key.js';
+/**
+ * Read a bare hub mirror's `origin` URL (`git -C <mirror> remote get-url
+ * origin`). Returns the trimmed URL, or `undefined` when the mirror has no
+ * `origin` or the read fails (a malformed mirror). The single helper both the
+ * registry enumeration (`remote ls`) and the per-machine override layer (the
+ * hub-key lookup in {@link resolveRepoConfigFromMirror}) use; defining it here
+ * avoids duplicating the `git remote get-url origin` call across modules.
+ */
+export declare function readOriginUrl(mirrorDir: string, env: NodeJS.ProcessEnv | undefined): string | undefined;
+/**
+ * The shared **hub-mirror primitive**: one bare mirror per repo under
+ * `<workspacesDir>/repos/<key>.git`, re-fetched from the arbiter. Both the
+ * autonomous job runner (`agent-workspaces`) and the human `work-on` build on
+ * it: a job worktree and a human worktree are both cut from the mirror's
+ * freshly-fetched `main`, so they always branch off the latest arbiter main
+ * (ADR §2).
+ *
+ * This module does NOT create worktrees, claim, or run anything — it only
+ * locates / creates / fetches the mirror. It is STATE, not cache (ADR §3): it
+ * lives under `~/.dorfl/` (config `workspacesDir`), never `~/.cache`.
+ */
+/**
+ * The on-disk location of the bare hub mirror for `url`:
+ * `<workspacesDir>/repos/<key>.git`. Lives under `workspacesDir` (default
+ * `~/.dorfl`), never `~/.cache` (ADR §3).
+ */
+export declare function mirrorPath(workspacesDir: string, url: string): string;
+export interface EnsureMirrorOptions {
+    /**
+     * The arbiter remote URL to mirror. Either `url` OR (`fromRepo` + `arbiter`)
+     * must be given; if both, `url` wins.
+     */
+    url?: string;
+    /** A working repo to resolve the remote URL from (with `arbiter`). */
+    fromRepo?: string;
+    /** Remote name in `fromRepo` whose URL to mirror (default `origin`). */
+    arbiter?: string;
+    /** The execution working area (config `workspacesDir`, default `~/.dorfl`). */
+    workspacesDir: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface EnsureMirrorResult {
+    /** Absolute path to the bare mirror. */
+    path: string;
+    /** The resolved arbiter URL the mirror tracks. */
+    url: string;
+    /** True iff the mirror did not exist and was just created. */
+    created: boolean;
+    /** True iff an existing mirror was fetched (not created). */
+    fetched: boolean;
+    /** The mirror's freshly-fetched `main` tip (40-hex sha). */
+    mainSha: string;
+}
+/**
+ * Locate the bare hub mirror for the arbiter; create it (`git clone --bare`) if
+ * absent, or `git fetch` it if present. Idempotent: a second call fetches and
+ * reuses the same mirror (it never re-clones, so any local mirror state — e.g.
+ * other branches/objects — survives). Returns the mirror path and its
+ * freshly-fetched `main`, so callers (job worktrees, human worktrees) always
+ * branch off the latest arbiter main.
+ */
+export declare function ensureMirror(options: EnsureMirrorOptions): EnsureMirrorResult;
+/**
+ * Locate the bare hub mirror for the arbiter and refresh ONLY its `main`,
+ * WITHOUT the all-heads `--prune` fetch {@link ensureMirror} does. Clones the
+ * mirror (`git clone --bare`) if absent — a fresh clone has no local worktrees,
+ * so the all-heads clone refspec cannot collide with any checked-out branch —
+ * but on REUSE refreshes via {@link fetchMirrorMain} (main-only, no-prune).
+ *
+ * This is the MIRROR-ENSURE for the no-checkout CONFIG READ (`do --remote`/
+ * `do --isolated` per-repo `.dorfl.json`): `git show main:.dorfl.json`
+ * only needs `main`, and using the pruning all-heads fetch here would let a
+ * `work/<slug>` branch CHECKED OUT in some other (stale) job worktree block the
+ * fetch (`git refuses to fetch into branch … checked out`), throwing the config
+ * read into its global+default fallback. Narrowing the config-read fetch to
+ * main-only (no-prune) means a checked-out worktree branch can NEVER block it
+ * (the read-path `scan`/`status`/mirror-pool-scan already use main-only fetches
+ * for exactly this reason — ADR §6).
+ *
+ * Does NOT replace {@link ensureMirror}: the build's worktree MATERIALISATION
+ * still legitimately needs the all-heads fetch (continue-detection wants the
+ * kept `work/<slug>` head as a local mirror ref). This is only for the read.
+ */
+export declare function ensureMirrorMain(options: EnsureMirrorOptions): EnsureMirrorResult;
+/**
+ * Fetch ONLY `main` from the arbiter into an existing bare mirror, WITHOUT
+ * `--prune`. Use this when the mirror also holds LOCAL-ONLY branches that must
+ * survive (e.g. the `work/<slug>` branches of live worktrees): the full
+ * mirror-style `+refs/heads/*:refs/heads/*` fetch in {@link ensureMirror} prunes
+ * any local head absent on the arbiter, which would delete (and corrupt) a
+ * checked-out `work/<slug>` worktree branch. This refreshes `main` to the latest
+ * arbiter tip while leaving every other local ref untouched. Returns the fresh
+ * `main` tip.
+ */
+export declare function fetchMirrorMain(mirrorDir: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Read the target repo's COMMITTED `.dorfl.json` from the bare hub
+ * mirror's `main` (`git show main:.dorfl.json`) — the per-repo config
+ * layer for the NO-CHECKOUT paths (`do --remote`). The committed file is a
+ * tracked file on `<arbiter>/main`, so it is reachable from the mirror without a
+ * worktree. Returns the raw file CONTENT, or `undefined` when the repo has no
+ * `.dorfl.json` on `main` (a config-less repo — the caller then resolves to
+ * exactly global + default, byte-identical to before this layer existed).
+ *
+ * This is the task's ONE genuinely-new seam: sourcing the bytes from the arbiter
+ * instead of the cwd. The parse / allow-reject filtering stays in
+ * {@link loadRepoConfigFromContent} (the existing per-repo machinery), so the
+ * host-only key rejection is identical however the bytes were sourced.
+ *
+ * A `git show` failure that is NOT "path missing on main" (a corrupt mirror, an
+ * absent `main`) is propagated — it is a genuine plumbing fault, not a
+ * config-less repo. The missing-path case (`git show` exit ≠ 0 naming the path)
+ * is read as `undefined` (no file = no per-repo layer).
+ */
+export declare function readRepoConfigFromMirrorMain(mirrorDir: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Resolve a repo's effective {@link Config} for a NO-CHECKOUT path by layering its
+ * COMMITTED `.dorfl.json` (read from the bare hub mirror's `main` via
+ * {@link readRepoConfigFromMirrorMain}) into the SAME
+ * `flag > env > per-repo > global > default` chain a working checkout uses
+ * ({@link resolveRepoConfigFromLoaded}). This is the reusable core of `do
+ * --remote`'s inline per-repo resolution (`resolveRemoteRepoConfig` in `cli.ts`):
+ * the mirror is assumed ALREADY ensured + fetched by the caller (the read paths
+ * fetch-first), so this only READS its `main` config and layers it.
+ *
+ * Resilient: a config-less repo (no file on `main`) resolves to exactly
+ * global + flags (byte-identical to the no-per-repo behaviour). A genuine
+ * read fault is propagated by {@link readRepoConfigFromMirrorMain}; a caller that
+ * must never block on a fault (a read-only scan) catches + falls back to
+ * global + flags itself.
+ */
+export declare function resolveRepoConfigFromMirror(options: {
+    /** The bare hub mirror directory whose `main:.dorfl.json` to read. */
+    mirrorPath: string;
+    /** The global + default config layer (from `loadConfig`/`mergeConfig`). */
+    global: Config;
+    /** Optional flag overrides (highest precedence). */
+    flags?: PartialConfig;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The per-machine override map (from `loadConfigOverride`), inserted between
+     * the committed per-repo file and env in the precedence chain. The hub key is
+     * derived from the mirror's own `origin` URL (via {@link readOriginUrl}); if
+     * unresolvable, the hub-key bucket is skipped and only the `"*"` bucket
+     * applies. Default: empty map (no override applied) — byte-identical to the
+     * pre-override behaviour.
+     */
+    override?: ConfigOverrideMap;
+}): Config;
+/** The bare mirror's `main` tip (40-hex sha), as freshly fetched. */
+export declare function mirrorMainSha(mirrorDir: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Fetch-first for the READ paths (`scan`/`status`, ADR
+ * `command-surface-and-journeys` §5/§6): refresh a registered mirror's `main`
+ * before reading its `work/` tree, so the read sees the remote truth (the
+ * registry model makes the remote the source of truth). It is a thin wrapper
+ * over {@link fetchMirrorMain} (the load-bearing main-only, no-prune fetch — it
+ * must NOT be the pruning `ensureMirror` fetch, which would delete live
+ * worktrees' `work/<slug>` branches, ADR §6).
+ *
+ * **Never errors out: warn + fall back to last-known.** A failed fetch (offline,
+ * a vanished origin, a dead arbiter) is NOT fatal for a read — `scan`/`status`
+ * must still report from the mirror's last-known `main`. On failure it routes a
+ * human-readable note through `warn` and returns `false`; on success it returns
+ * `true`. The freshness of the read then reflects the last SUCCESSFUL fetch.
+ */
+export declare function fetchMirrorMainOrWarn(options: {
+    /** The bare hub mirror directory whose `main` to refresh. */
+    mirrorPath: string;
+    /** Sink for the fall-back warning when the fetch fails. */
+    warn?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+//# sourceMappingURL=repo-mirror.d.ts.map

package/dist/repo-mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-mirror.d.ts","sourceRoot":"","sources":["../src/repo-mirror.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,MAAM,EAAE,aAAa,EAAC,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,sBAAsB,CAAC;AAS5D,OAAO,EAAC,aAAa,EAAC,MAAM,eAAe,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IAClC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAiD7E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,mBAAmB,GAC1B,kBAAkB,CAqBpB;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC9B,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,CAKR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,4BAA4B,CAC3C,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,GAAG,SAAS,CAqBpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACpD,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC7B,GAAG,MAAM,CAmBT;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,CAER;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC9C,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,OAAO,CAYV"}

package/dist/repo-mirror.js

@@ -0,0 +1,271 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { git, run } from './git.js';
+import { REPO_CONFIG_FILENAME, loadRepoConfigFromContent, resolveRepoConfigFromLoaded, } from './repo-config.js';
+import { encodeRepoKey } from './repo-key.js';
+export { encodeRepoKey } from './repo-key.js';
+/**
+ * Read a bare hub mirror's `origin` URL (`git -C <mirror> remote get-url
+ * origin`). Returns the trimmed URL, or `undefined` when the mirror has no
+ * `origin` or the read fails (a malformed mirror). The single helper both the
+ * registry enumeration (`remote ls`) and the per-machine override layer (the
+ * hub-key lookup in {@link resolveRepoConfigFromMirror}) use; defining it here
+ * avoids duplicating the `git remote get-url origin` call across modules.
+ */
+export function readOriginUrl(mirrorDir, env) {
+    const result = run('git', ['remote', 'get-url', 'origin'], mirrorDir, { env });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    const url = result.stdout.trim();
+    return url === '' ? undefined : url;
+}
+/**
+ * The shared **hub-mirror primitive**: one bare mirror per repo under
+ * `<workspacesDir>/repos/<key>.git`, re-fetched from the arbiter. Both the
+ * autonomous job runner (`agent-workspaces`) and the human `work-on` build on
+ * it: a job worktree and a human worktree are both cut from the mirror's
+ * freshly-fetched `main`, so they always branch off the latest arbiter main
+ * (ADR §2).
+ *
+ * This module does NOT create worktrees, claim, or run anything — it only
+ * locates / creates / fetches the mirror. It is STATE, not cache (ADR §3): it
+ * lives under `~/.dorfl/` (config `workspacesDir`), never `~/.cache`.
+ */
+/**
+ * The on-disk location of the bare hub mirror for `url`:
+ * `<workspacesDir>/repos/<key>.git`. Lives under `workspacesDir` (default
+ * `~/.dorfl`), never `~/.cache` (ADR §3).
+ */
+export function mirrorPath(workspacesDir, url) {
+    return join(workspacesDir, 'repos', `${encodeRepoKey(url)}.git`);
+}
+/**
+ * Locate the bare hub mirror for the arbiter; create it (`git clone --bare`) if
+ * absent, or `git fetch` it if present. Idempotent: a second call fetches and
+ * reuses the same mirror (it never re-clones, so any local mirror state — e.g.
+ * other branches/objects — survives). Returns the mirror path and its
+ * freshly-fetched `main`, so callers (job worktrees, human worktrees) always
+ * branch off the latest arbiter main.
+ */
+export function ensureMirror(options) {
+    const env = options.env;
+    const url = resolveUrl(options);
+    const path = mirrorPath(options.workspacesDir, url);
+    let created = false;
+    let fetched = false;
+    if (existsSync(path)) {
+        // Reuse: fetch the latest from the arbiter into the existing bare mirror.
+        //
+        // `main` is the authoritative base every worktree branches off — fetch it
+        // HARD (prune), and it can never collide with a checked-out branch (`main` is
+        // never a job worktree branch).
+        git(['fetch', '--prune', 'origin', '+refs/heads/main:refs/heads/main'], path, {
+            env,
+        });
+        // SHARED-MIRROR SIBLING-WORKTREE SAFETY (task
+        // `cutover-claim-body-stays-and-complete-sources-from-backlog`): two SAME-repo
+        // `run` jobs share ONE bare mirror, and each `git worktree add`s its own LOCAL
+        // `work/<slug>` head. The remaining all-heads fetch (which brings down each
+        // arbiter `work/<slug>` so continue-detection can read it as a local head) tries
+        // to UPDATE every such head; git REFUSES to fetch into a SIBLING's `work/<slug>`
+        // head while that sibling worktree has it checked out (`fatal: refusing to fetch
+        // into branch ... checked out`) and exits non-zero — EVEN THOUGH it still updated
+        // every OTHER ref (incl. main, above, and THIS job's own `work/<slug>`). Before
+        // this task the claim's body-move serialised the jobs enough to hide the
+        // overlap; with claim no longer writing `main` the jobs run concurrently and it
+        // surfaces. So this all-heads fetch is BEST-EFFORT (soft): a sibling's
+        // checked-out head being refused must NOT fail the whole ensure — the refs we
+        // need (main + this job's own head) are already updated, and continue-detection
+        // is arbiter-authoritative (`ls-remote` in `createJob`) anyway. A genuinely
+        // unrelated failure (e.g. an unreachable arbiter) ALSO degrades to best-effort
+        // here, but `main` (the hard fetch above) already succeeded, so the worktree
+        // materialisation has its base; the per-branch onboard reads still fail loudly
+        // downstream if a needed ref is genuinely absent.
+        run('git', ['fetch', 'origin', '+refs/heads/*:refs/heads/*'], path, { env });
+        fetched = true;
+    }
+    else {
+        // First time: a bare mirror clone (shared object store, cheap).
+        mkdirSync(dirname(path), { recursive: true });
+        git(['clone', '--quiet', '--bare', url, path], dirname(path), { env });
+        created = true;
+    }
+    return { path, url, created, fetched, mainSha: mirrorMainSha(path, env) };
+}
+/**
+ * Locate the bare hub mirror for the arbiter and refresh ONLY its `main`,
+ * WITHOUT the all-heads `--prune` fetch {@link ensureMirror} does. Clones the
+ * mirror (`git clone --bare`) if absent — a fresh clone has no local worktrees,
+ * so the all-heads clone refspec cannot collide with any checked-out branch —
+ * but on REUSE refreshes via {@link fetchMirrorMain} (main-only, no-prune).
+ *
+ * This is the MIRROR-ENSURE for the no-checkout CONFIG READ (`do --remote`/
+ * `do --isolated` per-repo `.dorfl.json`): `git show main:.dorfl.json`
+ * only needs `main`, and using the pruning all-heads fetch here would let a
+ * `work/<slug>` branch CHECKED OUT in some other (stale) job worktree block the
+ * fetch (`git refuses to fetch into branch … checked out`), throwing the config
+ * read into its global+default fallback. Narrowing the config-read fetch to
+ * main-only (no-prune) means a checked-out worktree branch can NEVER block it
+ * (the read-path `scan`/`status`/mirror-pool-scan already use main-only fetches
+ * for exactly this reason — ADR §6).
+ *
+ * Does NOT replace {@link ensureMirror}: the build's worktree MATERIALISATION
+ * still legitimately needs the all-heads fetch (continue-detection wants the
+ * kept `work/<slug>` head as a local mirror ref). This is only for the read.
+ */
+export function ensureMirrorMain(options) {
+    const env = options.env;
+    const url = resolveUrl(options);
+    const path = mirrorPath(options.workspacesDir, url);
+    let created = false;
+    let fetched = false;
+    if (existsSync(path)) {
+        // Reuse: refresh ONLY `main`, no-prune, so a `work/<slug>` branch checked
+        // out in some other worktree can never block this fetch.
+        fetchMirrorMain(path, env);
+        fetched = true;
+    }
+    else {
+        // First time: a bare mirror clone (no local worktrees yet, so the clone's
+        // own refspec can collide with nothing).
+        mkdirSync(dirname(path), { recursive: true });
+        git(['clone', '--quiet', '--bare', url, path], dirname(path), { env });
+        created = true;
+    }
+    return { path, url, created, fetched, mainSha: mirrorMainSha(path, env) };
+}
+/** Resolve the arbiter URL from `url`, or from `fromRepo` + `arbiter` remote. */
+function resolveUrl(options) {
+    if (options.url && options.url.trim() !== '') {
+        return options.url.trim();
+    }
+    if (options.fromRepo) {
+        const remote = options.arbiter ?? 'origin';
+        return git(['remote', 'get-url', remote], options.fromRepo, {
+            env: options.env,
+        }).trim();
+    }
+    throw new Error('ensureMirror requires either `url` or `fromRepo` (with `arbiter`).');
+}
+/**
+ * Fetch ONLY `main` from the arbiter into an existing bare mirror, WITHOUT
+ * `--prune`. Use this when the mirror also holds LOCAL-ONLY branches that must
+ * survive (e.g. the `work/<slug>` branches of live worktrees): the full
+ * mirror-style `+refs/heads/*:refs/heads/*` fetch in {@link ensureMirror} prunes
+ * any local head absent on the arbiter, which would delete (and corrupt) a
+ * checked-out `work/<slug>` worktree branch. This refreshes `main` to the latest
+ * arbiter tip while leaving every other local ref untouched. Returns the fresh
+ * `main` tip.
+ */
+export function fetchMirrorMain(mirrorDir, env) {
+    git(['fetch', 'origin', '+refs/heads/main:refs/heads/main'], mirrorDir, {
+        env,
+    });
+    return mirrorMainSha(mirrorDir, env);
+}
+/**
+ * Read the target repo's COMMITTED `.dorfl.json` from the bare hub
+ * mirror's `main` (`git show main:.dorfl.json`) — the per-repo config
+ * layer for the NO-CHECKOUT paths (`do --remote`). The committed file is a
+ * tracked file on `<arbiter>/main`, so it is reachable from the mirror without a
+ * worktree. Returns the raw file CONTENT, or `undefined` when the repo has no
+ * `.dorfl.json` on `main` (a config-less repo — the caller then resolves to
+ * exactly global + default, byte-identical to before this layer existed).
+ *
+ * This is the task's ONE genuinely-new seam: sourcing the bytes from the arbiter
+ * instead of the cwd. The parse / allow-reject filtering stays in
+ * {@link loadRepoConfigFromContent} (the existing per-repo machinery), so the
+ * host-only key rejection is identical however the bytes were sourced.
+ *
+ * A `git show` failure that is NOT "path missing on main" (a corrupt mirror, an
+ * absent `main`) is propagated — it is a genuine plumbing fault, not a
+ * config-less repo. The missing-path case (`git show` exit ≠ 0 naming the path)
+ * is read as `undefined` (no file = no per-repo layer).
+ */
+export function readRepoConfigFromMirrorMain(mirrorDir, env) {
+    const spec = `main:${REPO_CONFIG_FILENAME}`;
+    const res = run('git', ['show', spec], mirrorDir, { env });
+    if (res.status === 0) {
+        return res.stdout;
+    }
+    // `git show main:<path>` exits non-zero both when the PATH is absent on main
+    // (the config-less repo — expected, → undefined) and when `main`/the object is
+    // unresolvable (a genuine fault — propagate). git words the former as
+    // "...does not exist in 'main'" / "exists on disk, but not in" / "path ...
+    // does not exist"; the latter as an invalid-object/unknown-revision error.
+    const stderr = res.stderr;
+    const pathMissing = /does not exist in|exists on disk, but not in|fatal: path/i.test(stderr) ||
+        /did not match any file/i.test(stderr);
+    if (pathMissing) {
+        return undefined;
+    }
+    throw new Error(`git show ${spec} failed in ${mirrorDir} (exit ${res.status}): ${stderr.trim()}`);
+}
+/**
+ * Resolve a repo's effective {@link Config} for a NO-CHECKOUT path by layering its
+ * COMMITTED `.dorfl.json` (read from the bare hub mirror's `main` via
+ * {@link readRepoConfigFromMirrorMain}) into the SAME
+ * `flag > env > per-repo > global > default` chain a working checkout uses
+ * ({@link resolveRepoConfigFromLoaded}). This is the reusable core of `do
+ * --remote`'s inline per-repo resolution (`resolveRemoteRepoConfig` in `cli.ts`):
+ * the mirror is assumed ALREADY ensured + fetched by the caller (the read paths
+ * fetch-first), so this only READS its `main` config and layers it.
+ *
+ * Resilient: a config-less repo (no file on `main`) resolves to exactly
+ * global + flags (byte-identical to the no-per-repo behaviour). A genuine
+ * read fault is propagated by {@link readRepoConfigFromMirrorMain}; a caller that
+ * must never block on a fault (a read-only scan) catches + falls back to
+ * global + flags itself.
+ */
+export function resolveRepoConfigFromMirror(options) {
+    const { mirrorPath, global, flags, env, override } = options;
+    const content = readRepoConfigFromMirrorMain(mirrorPath, env);
+    const label = `${mirrorPath}#main:${REPO_CONFIG_FILENAME}`;
+    const loaded = content === undefined
+        ? { path: label, config: {}, rejected: [] }
+        : loadRepoConfigFromContent(content, label);
+    // The hub key for the override lookup comes from the mirror's OWN `origin`
+    // URL (the more reliable source for a no-checkout path — the mirror is what
+    // the runner actually operates on). Unresolvable ⇒ hub-key lookup skipped
+    // (graceful degrade); the `"*"` bucket still applies.
+    const arbiterUrl = readOriginUrl(mirrorPath, env);
+    return resolveRepoConfigFromLoaded(loaded, {
+        global,
+        flags,
+        override,
+        ...(arbiterUrl !== undefined ? { arbiterUrl } : {}),
+    }).config;
+}
+/** The bare mirror's `main` tip (40-hex sha), as freshly fetched. */
+export function mirrorMainSha(mirrorDir, env) {
+    return git(['rev-parse', 'main'], mirrorDir, { env }).trim();
+}
+/**
+ * Fetch-first for the READ paths (`scan`/`status`, ADR
+ * `command-surface-and-journeys` §5/§6): refresh a registered mirror's `main`
+ * before reading its `work/` tree, so the read sees the remote truth (the
+ * registry model makes the remote the source of truth). It is a thin wrapper
+ * over {@link fetchMirrorMain} (the load-bearing main-only, no-prune fetch — it
+ * must NOT be the pruning `ensureMirror` fetch, which would delete live
+ * worktrees' `work/<slug>` branches, ADR §6).
+ *
+ * **Never errors out: warn + fall back to last-known.** A failed fetch (offline,
+ * a vanished origin, a dead arbiter) is NOT fatal for a read — `scan`/`status`
+ * must still report from the mirror's last-known `main`. On failure it routes a
+ * human-readable note through `warn` and returns `false`; on success it returns
+ * `true`. The freshness of the read then reflects the last SUCCESSFUL fetch.
+ */
+export function fetchMirrorMainOrWarn(options) {
+    try {
+        fetchMirrorMain(options.mirrorPath, options.env);
+        return true;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        options.warn?.(`could not fetch mirror at ${options.mirrorPath}; ` +
+            `reading last-known state (offline). ${reason}`);
+        return false;
+    }
+}
+//# sourceMappingURL=repo-mirror.js.map

package/dist/repo-mirror.js.map

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

package/dist/retry-backoff.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A small, shared **bounded exponential-backoff** retry helper for git / provider
+ * NETWORK ops on the needs-attention route (the OBSERVABLE surface push, the
+ * RECOVERABLE branch push, and the propose-mode PR create). The route does a
+ * LOCAL move that always succeeds offline, then these best-effort remote ops; a
+ * transient OUTAGE (unreachable arbiter / flaky provider) should be RETRIED a few
+ * times with a temporal delay before a clean BOUNDED give-up into the local-only
+ * degraded state — never an indefinite hang, never an uncaught throw out of the
+ * failure handler.
+ *
+ * This is DELIBERATELY NOT the model in {@link file://./claim-cas.ts}: that loop
+ * retries CONTENTION (a REJECTED push — someone advanced the ref) INSTANTLY with
+ * NO delay, refetching+rebuilding against the new base. THIS helper is for the
+ * OUTAGE/unreachable case, which needs a temporal back-off (the remote may come
+ * back); the two are distinct and must not be conflated.
+ *
+ * Bounds (all configurable, sensible defaults):
+ *   - `initialDelayMs` (X): the first inter-attempt delay.
+ *   - `maxDelayMs` (Y): the cap the exponentially-growing delay never exceeds.
+ *   - `maxTotalMs` (Z): the wall-clock budget; once the NEXT delay would push the
+ *     cumulative sleep past this, we stop retrying (a clean bounded give-up).
+ *   - `maxAttempts`: a hard upper bound on attempts (a belt-and-braces cap so a
+ *     tiny/zero delay budget still terminates).
+ *
+ * The SLEEP is INJECTABLE (reusing the `sleep?: (ms) => Promise<void>` /
+ * `realSleep` seam `src/run.ts` already uses for the inter-tick sleep) so tests
+ * drive the whole retry TIMELINE deterministically with NO real wall-clock waits.
+ *
+ * Model-endpoint retries are NOT this helper's job — the pi harness retries its
+ * own API. This is git/provider network resilience only.
+ */
+/** A sleep seam: resolve after `ms`. The real one is `setTimeout`-backed. */
+export type Sleep = (ms: number) => Promise<void>;
+/** The default real sleep (a `setTimeout`-backed promise). */
+export declare const realSleep: Sleep;
+/** Bounds for {@link retryWithBackoff}. All optional; defaults below. */
+export interface BackoffOptions {
+    /** First inter-attempt delay (ms). Default {@link DEFAULT_BACKOFF}.initialDelayMs. */
+    initialDelayMs?: number;
+    /** Exponential-growth cap (ms). Default {@link DEFAULT_BACKOFF}.maxDelayMs. */
+    maxDelayMs?: number;
+    /** Total wall-clock budget for delays (ms). Default {@link DEFAULT_BACKOFF}.maxTotalMs. */
+    maxTotalMs?: number;
+    /** Hard attempt cap. Default {@link DEFAULT_BACKOFF}.maxAttempts. */
+    maxAttempts?: number;
+    /** Injected sleep (tests). Default {@link realSleep}. */
+    sleep?: Sleep;
+}
+/**
+ * The default bounds: a short first delay growing exponentially to a modest cap,
+ * with a small total budget — enough to ride out a blip, NOT a hang. A clean
+ * bounded give-up into the local-only degraded state beats waiting forever;
+ * CI/humans then retry deliberately.
+ */
+export declare const DEFAULT_BACKOFF: Required<Omit<BackoffOptions, 'sleep'>>;
+/** Outcome of {@link retryWithBackoff}: the op's value, or a clean give-up. */
+export type RetryResult<T> = {
+    ok: true;
+    value: T;
+    attempts: number;
+} | {
+    ok: false;
+    attempts: number;
+    lastError?: string;
+};
+/**
+ * Run `op` and, if it reports failure, RETRY it with bounded exponential backoff
+ * until it succeeds or the bounds are exhausted (then a clean give-up — NEVER an
+ * indefinite loop). `op` reports failure in EITHER of two ways, both treated the
+ * same so callers can use whichever fits the underlying API:
+ *
+ *   - it RETURNS `{ok: false, error?}` (e.g. a git `RunResult` mapped to a
+ *     boolean — a non-zero exit is a failure, not a throw), OR
+ *   - it THROWS (e.g. a git plumbing helper's hard-fetch against an unreachable
+ *     remote) — the throw is CAUGHT here and treated as a failed attempt.
+ *
+ * On success it returns `{ok: true, value}`. On exhaustion it returns
+ * `{ok: false, lastError}` — it NEVER throws out (the route must not crash on a
+ * git outage). The delay schedule is `initialDelayMs`, doubling each attempt up
+ * to `maxDelayMs`, stopping once another attempt's delay would exceed the
+ * `maxTotalMs` budget or `maxAttempts` is reached.
+ */
+export declare function retryWithBackoff<T>(op: () => Promise<{
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error?: string;
+}>, options?: BackoffOptions): Promise<RetryResult<T>>;
+//# sourceMappingURL=retry-backoff.d.ts.map

package/dist/retry-backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-backoff.d.ts","sourceRoot":"","sources":["../src/retry-backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD,8DAA8D;AAC9D,eAAO,MAAM,SAAS,EAAE,KAC0B,CAAC;AAEnD,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC9B,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,KAAK,CAAC,EAAE,KAAK,CAAC;CACd;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAKnE,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,WAAW,CAAC,CAAC,IACtB;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,GACtC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAC,GAAG;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,EACrE,OAAO,GAAE,cAAmB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAsCzB"}