tumwater 0.1.3 → 0.3.0

package/dist/src/landing/landing-git.js

@@ -1,190 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { COMMIT_IDENT, git, gitTry, runGit } from "../git/git-run.js";
-import { writeBytesAtomic } from "../files/files.js";
-import { currentBranch, gitLines, headOf } from "../git/git.js";
-import { unquotePorcelainPath } from "../git/git-diff.js";
-import { CONFIG_BASENAME, configPath, primaryWorktreeLockPath } from "../paths.js";
-import { withStateLockAsync } from "../concurrency/lock.js";
-/** Git plumbing for the landing flow: rebasing a worktree branch onto main, inspecting and
- * finishing a conflicted rebase, and fast-forwarding main — the mechanics, with no landing policy
- * of their own. Landing policy (lock → rebase → verify → ff, conflict resolution, batch ff)
- * lives in landing-merge.ts on top of these. Moved here from landing-merge.ts: the cluster started
- * as landing-merge.ts-only helpers (organize tick 78, moving them out of git/git.ts), but the
- * lander and the batch lander grew to call them directly, leaving landing-merge.ts exporting
- * generic rebase/ff plumbing that had nothing to do with merging. */
-/** Paths currently in conflict (unmerged) in the worktree. C-quoted names are decoded to
- * real paths — a non-ASCII conflicted file arrives as `"h\303\251llo.ts"` (core.quotePath is on
- * by default), and undecoded it does not exist on disk: hasConflictMarkers could never read
- * it, so an unresolved conflict in such a file passed the marker check and continueRebase
- * committed its markers to main. */
-export async function conflictedFiles(wt) {
-    const out = await gitTry(wt, "diff", "--name-only", "--diff-filter=U");
-    return gitLines(out).map(unquotePorcelainPath);
-}
-/** How many main commits the resolver prompt lists, and how many body lines it keeps per
- * commit: enough to explain a deliberate removal without filling the window. */
-const MAX_INTENT_COMMITS = 15;
-const MAX_INTENT_BODY_LINES = 20;
-function capIntentBody(body) {
-    const lines = body.split("\n");
-    if (lines.length <= MAX_INTENT_BODY_LINES)
-        return body;
-    const kept = lines.slice(0, MAX_INTENT_BODY_LINES).join("\n");
-    return `${kept}\n… (${lines.length - MAX_INTENT_BODY_LINES} more lines)`;
-}
-/** The commits on `mainBranch` since `since` (the change's merge-base with main) that touched
- * any of `files`, newest first. resolveConflict threads this into the resolver prompt so pi
- * reads what main deliberately changed instead of guessing from the markers. The list is
- * capped at MAX_INTENT_COMMITS and each body at MAX_INTENT_BODY_LINES; `omitted` counts the
- * commits the cap dropped so the prompt can say so. An empty result is the normal case of a
- * fork point with no later main commits touching the files. */
-export async function mainCommitsTouching(wt, since, mainBranch, files) {
-    if (files.length === 0)
-        return { commits: [], omitted: 0 };
-    const out = await gitTry(wt, "log", "--format=%h%x1f%s%x1f%b%x1e", `${since}..${mainBranch}`, "--", ...files);
-    const parsed = (out ?? "")
-        .split("\x1e")
-        .map((record) => record.trim())
-        .filter(Boolean)
-        .map((record) => {
-        const [sha = "", subject = "", ...rest] = record.split("\x1f");
-        return { sha, subject, body: capIntentBody(rest.join("\x1f").trim()) };
-    });
-    return {
-        commits: parsed.slice(0, MAX_INTENT_COMMITS),
-        omitted: Math.max(0, parsed.length - MAX_INTENT_COMMITS),
-    };
-}
-/** Attempt to rebase the worktree branch onto main and classify the outcome WITHOUT
- * cleaning up: "rebased" (including already up to date), "conflict" (the rebase stopped on
- * unmerged paths, which remain in the worktree for a resolver), or "other" (any other
- * failure). Shared by the two rebase wrappers below, which differ only in cleanup policy.
- * Rebase — not merge — keeps main's history linear: each tick lands as its own commit on top
- * of whatever main holds. */
-async function attemptRebase(wt, mainBranch) {
-    try {
-        // The -c ident is needed for the rewritten committer identity. diff3 carries the base
-        // section of every conflict, which the deterministic backlog resolver reads
-        // (plans/parallel-work-instances.md, part 3/7); rebaseOntoMain aborts on conflict, so the
-        // marker style only matters to its leave-conflicts sibling.
-        await runGit(wt, [...COMMIT_IDENT, "-c", "merge.conflictStyle=diff3", "rebase", mainBranch]);
-        return "rebased";
-    }
-    catch {
-        return (await conflictedFiles(wt)).length > 0 ? "conflict" : "other";
-    }
-}
-/** Rebase the worktree branch onto main (main may have advanced during the tick).
- * Returns false and aborts the rebase on conflict. */
-export async function rebaseOntoMain(wt, mainBranch) {
-    const state = await attemptRebase(wt, mainBranch);
-    if (state !== "rebased")
-        await gitTry(wt, "rebase", "--abort");
-    return state === "rebased";
-}
-/** Rebase the worktree branch onto main, leaving conflict markers in place for a
- * resolver to work on. "clean" = rebased (or already up to date); "conflict" = the rebase
- * stopped on conflicts and the worktree holds them mid-rebase; "failed" = anything else
- * (aborted and cleaned up). */
-export async function rebaseOntoMainLeaveConflicts(wt, mainBranch) {
-    const state = await attemptRebase(wt, mainBranch);
-    if (state === "other")
-        await gitTry(wt, "rebase", "--abort");
-    return state === "rebased" ? "clean" : state === "conflict" ? "conflict" : "failed";
-}
-/** True if any of the given files still contains a git conflict marker.
- * A deleted file counts as resolved (the resolver chose the deletion). */
-export function hasConflictMarkers(wt, files) {
-    // Only start/end markers are checked: every real conflict block carries them, while a bare
-    // `=======` line is legitimate content (a markdown setext or RST underline of exactly seven
-    // characters), and flagging it would reject clean resolutions forever. A resolver that
-    // leaves only a separator line behind is treated as resolved; its stray line is content the
-    // project's own tests can catch.
-    const marker = /^(<{7}|>{7})( |$)/m;
-    return files.some((f) => {
-        const p = path.join(wt, f);
-        try {
-            return marker.test(fs.readFileSync(p, "utf8"));
-        }
-        catch {
-            return false;
-        }
-    });
-}
-/** The reason naming every changed file that still carries a conflict marker, or undefined when
- * none do — the one home of the wording, shared by the stage check's pre-queue finding
- * (stage-check.ts) and the review gate's hard rejection (review.ts), so the two surfaces cannot
- * name the same leftover marker differently. Committing or landing one would put raw `<<<<<<<`
- * lines on main (PLANS.md "Robust conflict landing, part 2/2"). Builds on hasConflictMarkers
- * above, the shared definition of what a marker is. */
-export function conflictMarkerReason(wt, files) {
-    const marked = files.filter((f) => hasConflictMarkers(wt, [f]));
-    return marked.length > 0 ? `conflict markers remain in: ${marked.join(", ")}` : undefined;
-}
-/** Conclude an in-progress rebase with everything in the worktree as the resolution.
- * GIT_EDITOR=true so `rebase --continue` can never block on a commit-message prompt. A
- * resolution that leaves no unique content (the branch's change was fully superseded by
- * main) is skipped automatically by git, finishing the rebase cleanly. Throws when the
- * rebase stops again — e.g. on a second conflict from a later commit the resolution run added; the caller aborts and reports merge_conflict. */
-export async function continueRebase(wt) {
-    await git(wt, "add", "-A");
-    await runGit(wt, [...COMMIT_IDENT, "rebase", "--continue"], { GIT_EDITOR: "true" });
-    return headOf(wt, "HEAD");
-}
-/** The live config's bytes, when the landing about to fast-forward `ref` would delete it
- * (plans/portability.md §4b/7): the config file exists, is tracked in the current index (and
- * HEAD — a staged-or-dirty config makes `git merge --ff-only` refuse below, so the two agree
- * on every merge that can succeed), and is absent from the incoming tree. Anything else —
- * already untracked, already absent, present in `ref` — needs no preserve step. */
-export async function configBytesToPreserve(root, ref) {
-    const cfg = configPath(root);
-    if (!fs.existsSync(cfg))
-        return null;
-    if ((await gitTry(root, "ls-files", "--error-unmatch", CONFIG_BASENAME)) === null)
-        return null;
-    if ((await gitTry(root, "cat-file", "-e", `${ref}:${CONFIG_BASENAME}`)) !== null)
-        return null;
-    return fs.readFileSync(cfg);
-}
-/** The preserve step's write-back, restore-only-when-absent: write the saved bytes only when
- * the live config is absent at write-back time. The merge deletes the file mid-window, so a
- * config request applied in that window (3/7's applyConfigRequest runs outside the merge lock)
- * recreates it — the newer bytes win (latest instruction wins), which also makes the step
- * idempotent. Called only after a successful merge: a refused merge leaves the file untouched.
- * Written through writeBytesAtomic (tmp+rename), like every other tumwater.json writer, so a
- * crash mid-write cannot leave the live config torn for the ~2 s config poll or the next
- * generation's startup load. */
-export function restoreConfigBytes(root, saved) {
-    if (!saved)
-        return;
-    const cfg = configPath(root);
-    if (fs.existsSync(cfg))
-        return;
-    writeBytesAtomic(cfg, saved);
-}
-/** Fast-forward main to `ref`, without touching any remote. Callers pass the worktree's
- * post-rebase HEAD — a bare sha, which both arms accept (`merge --ff-only <sha>` and
- * `push . <sha>:<main>`). Uses a working-tree merge when the primary checkout is on main (so its
- * files update), otherwise a local ref push. Returns true on success. The working-tree arm
- * preserves the live config across a landing that untracks it (plans/portability.md §4b/7):
- * without the write-back, the commit that removes the tracked config would delete the fleet's
- * running config out from under it and the next config poll would fall back to defaults. */
-export async function ffMainTo(root, ref, mainBranch) {
-    const primaryBranch = await currentBranch(root);
-    if (primaryBranch === mainBranch) {
-        // The working-tree arm rewrites the same tracked files the CLI backlog writers read and
-        // rewrite, so it shares their primary-worktree lock (paths.ts): without it a `tumwater bug`
-        // that read before this merge can rename its stale whole-file write over the landed change.
-        // The ref-push arm below touches no working tree and needs no lock; the save/merge/restore
-        // stays one short section, never held across a build re-check.
-        return withStateLockAsync(primaryWorktreeLockPath(root), async () => {
-            const saved = await configBytesToPreserve(root, ref);
-            if ((await gitTry(root, "merge", "--ff-only", ref)) === null)
-                return false;
-            restoreConfigBytes(root, saved);
-            return true;
-        });
-    }
-    return (await gitTry(root, "push", ".", `${ref}:${mainBranch}`)) !== null;
-}

package/dist/src/landing/landing-pipeline.js

@@ -1,96 +0,0 @@
-import { runOnAbort } from "../process/process.js";
-import { warnEventBestEffort } from "../events/events.js";
-import { errorMessage } from "../text/text.js";
-import { deleteRef } from "../git/git.js";
-import { removeLandingChange, writeLandingOutcome } from "./landing-slot.js";
-import { landingRefName, rejectedRefName } from "../paths.js";
-/** A fresh pipeline: nothing in flight anywhere — no vet running, no approved change waiting,
- * no merge holding main. The orchestrator builds one per fleet start (orchestrator.ts). */
-export function newLandingPipeline() {
-    return { vetting: new Map(), vetted: new Map(), merge: null };
-}
-/** Every landing task in flight — each vet holding its permit, and the merge — for the shutdown
- * and restart waits. A parked vet is not one of them: it has started nothing, and a shutdown
- * (its controller) or a closed start gate (at its grant) settles it without a run. */
-export function landingTasks(p) {
-    return [...[...p.vetting.values()].filter((v) => !v.parked), ...(p.merge ? [p.merge] : [])];
-}
-/** Everything `tumwater abort --role` can reach: every task in flight, plus each vetted change
- * waiting with no task of its own. A parked vet is out of reach, as a plainly queued entry
- * always was: its change has not started landing. */
-export function abortableLandings(p) {
-    return [...landingTasks(p), ...p.vetted.values()];
-}
-/** Wire harness shutdown to one task's own controller — through the shared register/abort
- * race helper, so an already-fired signal aborts at once. Returns the detach function. The
- * fleet shutdown signal outlives every landing, so each task that settles while the signal is
- * still live must detach in its own finally; without that, the one long-lived signal
- * accumulates a listener (and the retained controller behind it) for every landing the fleet
- * ever runs, growing without bound until the shutdown it was waiting for. */
-export function abortOnShutdown(signal, controller) {
-    return runOnAbort(signal, () => controller.abort());
-}
-/** Wrap a landing task's stored promise so it can never reject: the tasks are fire-and-forget
- * during normal operation (only the shutdown/restart drain awaits them), and an unexpected
- * throw out of their bookkeeping — an unwritable state file, event feed, or marker while
- * settling an outcome — would otherwise surface as an unhandled rejection and take the
- * orchestrator down. The throw is reported best-effort; the task's own finally has already
- * released its slot and controller, and the surviving queue entry and pin recover on the next
- * poll. */
-export function guardLandingTask(root, role, promise) {
-    return promise.catch((err) => {
-        warnEventBestEffort(root, "harness", `landing task for ${role} could not settle: ${errorMessage(err)}`);
-    });
-}
-/** Take a permit at `tier` unless `signal` fires first: resolves to its release, or to null
- * when the signal won — a grant that arrives after that is handed straight back (a hop, never
- * a leak), so a parked vet that a shutdown settles holds nothing. */
-export async function acquireUnlessAborted(semaphore, tier, signal) {
-    if (signal.aborted)
-        return null;
-    const granted = semaphore.acquire(tier).then(() => true);
-    const stopped = new Promise((resolve) => signal.addEventListener("abort", () => resolve(false), { once: true }));
-    if (await Promise.race([granted, stopped]))
-        return () => semaphore.release();
-    void granted.then(() => semaphore.release());
-    return null;
-}
-/** The roles the pipeline holds right now — vetting (parked or not), vetted, or merging. */
-export function liveRoles(p) {
-    return new Set([...p.vetting.keys(), ...p.vetted.keys(), ...(p.merge?.roles ?? [])]);
-}
-/** Discard the pinned landing refs of every role in a deliberately-aborted landing.
- * `tumwater abort --role` throws the committed work away, and the pin is what would otherwise
- * recover it, so the ref must go; a shutdown abort leaves `userAborted` unset and every ref
- * survives for recovery. Shared by every task's settling code so their discard semantics
- * cannot drift. A ref that is already gone is not an error. */
-export async function discardPinnedRefs(root, roles) {
-    for (const role of roles) {
-        try {
-            await deleteRef(root, landingRefName(role));
-        }
-        catch {
-            /* already gone */
-        }
-    }
-}
-/** Settle a landing queue entry that reached a terminal outcome — the one home of the
- * write-plus-drop pairing every settled landing goes through: the result lands in the role's
- * state and the landed/land_failed event (writeLandingOutcome), then the change's marker record
- * is dropped (removeLandingChange — landing-slot leaves the marker to the caller). Shared by
- * settleAbortedVetted, the vet's final-verdict branch, and the merge's per-change write-back, so
- * no settled entry can keep a stale marker or lose its outcome write. The pinned-ref discard
- * stays with the callers: only a user abort throws work away, and the merge discards its whole
- * stack at once rather than change by change. */
-export async function settleLandingOutcome(root, entry, state, result, durationMs, usage, file) {
-    writeLandingOutcome(root, entry, state, result, durationMs, usage, file);
-    // A revision that lands ends the rejected change's life: drop the rejected ref (plans/revise-
-    // rejected.md). A rejection repoints or deletes it in landing-core.ts, so this is the only
-    // ref cleanup a landed revision needs here. Guarded on the entry's revisionRound, not just a
-    // `changed` result: a fresh change can land while a different rejection's revision is still
-    // pending, and its landing must leave that pending revision's ref alone.
-    if (result === "changed" && entry.revisionRound !== undefined) {
-        await deleteRef(root, rejectedRefName(entry.role));
-    }
-    removeLandingChange(root, entry.role);
-}

package/dist/src/landing/landing-queue-render.js

@@ -1,56 +0,0 @@
-/** The renderer behind `tumwater queue` — the operator-facing text for the land queue view the
- * reader gathers (landing-queue.ts's readLandingQueue, beside it): one line per queued landing
- * in execution order, plus the count of queue files the reader skipped. Pure function of the
- * collected view and a `now` instant — no I/O, no clock reads — so the age it prints can be
- * pinned by a test. */
-import { humanSeconds, secondsSince } from "../text/datetime.js";
-import { shortSha } from "../text/format.js";
-import { plural } from "../text/phrases.js";
-import { landingChanges, LANDING_STAGE_LABELS } from "./landing-slot.js";
-/** The bracketed-label text for one queue entry, in the wording the loop rows use (status-model's
- * loopPhase): `landing <elapsed> · <stage>` while a vet or the merge holds the change,
- * `vetted, awaiting merge` once vetted, and "" when the marker is absent, names no record for
- * `sha`, or the record is `done`. Reads the marker through landingChanges, so an older-generation
- * single-change marker counts as one `landing` record. */
-export function queueEntryLandingLabel(sha, inFlight, now) {
-    if (!inFlight)
-        return "";
-    const change = landingChanges(inFlight).find((c) => c.sha === sha);
-    if (!change || change.status === "done")
-        return "";
-    if (change.status === "vetted")
-        return "vetted, awaiting merge";
-    let label = "landing";
-    if (change.startedAt)
-        label += ` ${humanSeconds(secondsSince(change.startedAt, now))}`;
-    if (change.stage)
-        label += ` · ${LANDING_STAGE_LABELS[change.stage]}`;
-    return label;
-}
-/** Render the queue as the text `tumwater queue` prints: a `land queue (<depth>):` header then
- * one 1-based line per readable entry, oldest first, carrying the loop, tick number, short
- * pinned sha, age, and summary. An empty queue (no entries and nothing skipped) prints
- * `land queue empty`; a non-zero skip count appends one `(+N unreadable queue file(s) skipped)`
- * line so a torn or foreign file the reader dropped is visible rather than silent. An entry the
- * optional in-flight marker has a live record for carries ` · [<label>]` after its age
- * (queueEntryLandingLabel). */
-export function renderLandingQueue(view, now, inFlight) {
-    const depth = view.entries.length + view.unreadable;
-    const lines = [];
-    if (depth === 0) {
-        lines.push("land queue empty");
-    }
-    else {
-        lines.push(`land queue (${depth}):`);
-        view.entries.forEach((e, i) => {
-            const age = humanSeconds(secondsSince(e.enqueuedAt, now));
-            const label = queueEntryLandingLabel(e.sha, inFlight, now);
-            const tag = label ? ` · [${label}]` : "";
-            lines.push(`  ${i + 1}. ${e.role} tick #${e.tick} · ${shortSha(e.sha)} · ${age} ago${tag} · ${e.summary}`);
-        });
-    }
-    if (view.unreadable > 0) {
-        lines.push(`  (+${plural(view.unreadable, "unreadable queue file")} skipped)`);
-    }
-    return lines.join("\n");
-}

package/dist/src/landing/landing-queue.js

@@ -1,149 +0,0 @@
-import path from "node:path";
-import { listQueueFiles, queueFileName, removeQueueFile } from "../files/file-queue.js";
-import { isJsonObject, nonNegativeNumber } from "../files/json-object.js";
-import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
-import { cachedByStat } from "../files/stat-cache.js";
-import { landQueueDir } from "../paths.js";
-let seq = 0;
-/** Append one landing to the queue as a single timestamped file (creating the queue dir if
- * needed). The filename orders entries across processes by wall-clock time; the per-process
- * counter and pid break ties within one process. Written atomically (tmp + rename): the
- * enqueue runs while the process can be hard-killed mid-write (the tick deadline's
- * process-group kill, a shutdown), and a torn entry the crash left behind is not always
- * recoverable — the drain repairs only an unreadable HEAD (staleHeadFile), so a torn file
- * that sorts after a healthy entry would sit in the queue dir unread forever. */
-export function enqueueLanding(root, entry) {
-    const dir = landQueueDir(root);
-    const name = queueFileName(entry.enqueuedAt, seq++, ".json");
-    writeJsonAtomic(path.join(dir, name), entry);
-}
-/** Every queue file in execution order (oldest first) — the same filename sort queuedLandings,
- * headLanding, and the orchestrator's per-poll queued-roles set read. A missing queue dir
- * reads as an empty queue. */
-function queueFiles(root) {
-    return listQueueFiles(landQueueDir(root), ".json");
-}
-/** Number of landings currently queued — a directory listing only; no file content is read.
- * A missing queue dir reads as 0, like every other reader here. */
-export function queueDepth(root) {
-    return queueFiles(root).length;
-}
-// Per-poll entry-content cache (stat-cache.cachedByStat): dashboard polls must not re-parse
-// every queued entry — each file is written once by enqueueLanding and only deleted on drop,
-// the same write-once discipline the inbox caches for prompts.
-const entryCache = new Map();
-/** True when `v` carries every field a LandingEntry requires, with the right type. The land
- * queue is one JSON object per file, so a file that parses to anything else — a scalar, an
- * array, an object missing a required field — is foreign or torn and reads as no entry.
- * Checking only `role` and `sha` left the `as LandingEntry` cast unsound: a foreign file that
- * happened to carry those two fields was handed downstream with `tick` and `summary`
- * undefined, which surface as bogus session names (`tumwater-<role>-undefined-review`) and
- * `undefined` in the reviewer's prompt. Optional fields are checked only when present.
- *
- * The three numeric fields go through nonNegativeNumber, not a bare `typeof === "number"`:
- * JSON's `1e999` parses to Infinity, so a hand-edited file could carry a non-finite tick or
- * enqueuedAt past a typeof check, and both feed plumbing downstream (session names, queue
- * ordering, the status payload). */
-function isPriorReview(v) {
-    if (!isJsonObject(v))
-        return false;
-    return (typeof v.sha === "string" &&
-        Array.isArray(v.reasons) &&
-        v.reasons.every((r) => typeof r === "string"));
-}
-function isLandingEntry(v) {
-    if (!isJsonObject(v))
-        return false;
-    const e = v;
-    return (typeof e.role === "string" &&
-        typeof e.sha === "string" &&
-        nonNegativeNumber(e.tick, null) !== null &&
-        typeof e.summary === "string" &&
-        nonNegativeNumber(e.enqueuedAt, null) !== null &&
-        (e.body === undefined || typeof e.body === "string") &&
-        (e.highFriction === undefined || typeof e.highFriction === "boolean") &&
-        (e.revisionRound === undefined || nonNegativeNumber(e.revisionRound, null) !== null) &&
-        (e.priorReview === undefined || isPriorReview(e.priorReview)));
-}
-/** Read one queue file through the stat-keyed cache: null when it vanishes mid-listing (a
- * concurrent drop — the inbox.ts race policy), is unreadable, or fails to parse or to carry
- * every required LandingEntry field (a foreign or torn file is skipped, never thrown on). A
- * shallow copy out: the entry's fields are all scalars and callers treat the result as
- * read-only. */
-function readEntry(file) {
-    return cachedByStat(entryCache, file, file, () => {
-        // readJsonFile is the shared "missing or torn reads as no data" policy; a foreign shape
-        // is still rejected by isLandingEntry.
-        const parsed = readJsonFile(file);
-        return isLandingEntry(parsed) ? parsed : null;
-    }, (e) => ({ ...e }));
-}
-/** Every queued landing in execution order (oldest first) paired with the file to drop on
- * completion. The batch drain (merge queue 5/5) reads this slice because `dropLanding` needs
- * the file, which the bare-entry readers never return. A missing queue directory reads as an
- * empty queue. */
-export function queuedLandingFiles(root) {
-    const out = [];
-    for (const file of queueFiles(root)) {
-        const entry = readEntry(file);
-        if (entry)
-            out.push({ entry, file });
-    }
-    return out;
-}
-/** All queued landings in execution order (oldest first). A missing queue directory reads as
- * an empty queue. */
-export function queuedLandings(root) {
-    return queuedLandingFiles(root).map((q) => q.entry);
-}
-/** The roles currently holding a queued landing — the maintenance quota's and the permit
- * reserve's "already in flight" input, and the scheduler's per-poll merge-queue interlock.
- * A missing queue directory reads as an empty set, like every reader here. */
-export function queuedLandingRoles(root) {
-    return new Set(queuedLandingFiles(root).map((q) => q.entry.role));
-}
-/** Read every queue file once through the stat-keyed cache, collecting the readable entries
- * (filename order) and counting the rest — the torn/foreign file policy readEntry already
- * applies, surfacing the skip count instead of hiding it. */
-export function readLandingQueue(root) {
-    const entries = [];
-    let unreadable = 0;
-    for (const file of queueFiles(root)) {
-        const entry = readEntry(file);
-        if (entry)
-            entries.push(entry);
-        else
-            unreadable++;
-    }
-    return { entries, unreadable };
-}
-/** The head of the queue — its oldest entry — plus the file to drop on completion, or null when
- * the queue is empty or its oldest file is a vanished/torn entry. */
-export function headLanding(root) {
-    const file = queueFiles(root)[0];
-    if (!file)
-        return null;
-    const entry = readEntry(file);
-    return entry ? { entry, file } : null;
-}
-/** The oldest queue file when the queue is non-empty but its head is unreadable — torn or
- * foreign (a partial write an older build left, a hand-placed file) — i.e. when headLanding
- * reads null while the queue holds files; null when the queue is empty or its head is healthy.
- * The drain drops this file with a warning so the queue can drain: headLanding reads null for
- * it forever and nothing else will remove it, stranding every live entry behind it (each
- * author's interlock, the per-poll queued-roles set, pins its ticks along with them). The
- * crashed entry's commit, if any, still lives in its landing ref — next-tick leftover recovery
- * re-lands it — so the drop loses nothing recoverable from the file (BUGS.md 2026-09-16). */
-export function staleHeadFile(root) {
-    const file = queueFiles(root)[0];
-    if (!file)
-        return null;
-    return readEntry(file) === null ? file : null;
-}
-/** Remove one queued landing's file after its landing outcome — terminal or not (a
- * non-terminal outcome keeps the landing ref; the retry is the role's next fresh tick, not a
- * queue re-drain). ENOENT is a no-op: a concurrent drop between listing and removal is a
- * normal race (the inbox.ts policy), not an error. */
-export function dropLanding(file) {
-    removeQueueFile(file);
-}