gutterpress 0.10.0 → 0.10.1-beta.2

package/dist/lib/remote-auth/github-auth.d.ts

@@ -17,19 +17,6 @@ export interface HostCallbacks {
     /** Optional cancellation (user closed the dialog). */
     signal?: AbortSignal;
 }
-/**
- * Per-host auth-acquisition plugin contract (ADR 0006 D3 layer 3). github.com
- * gets the device flow below; every other host gets the generic token flow
- * (#14, not in this change).
- */
-export interface RemoteAuthProvider {
-    /** Does this provider handle the given remote host? */
-    matches(origin: URL): boolean;
-    /** Interactive flow producing a credential for the host. */
-    connect(callbacks: HostCallbacks): Promise<HostCredential>;
-    /** Cheap revalidation for stored credentials. */
-    validate(credential: HostCredential): Promise<boolean>;
-}
 /**
  * Client id resolution: explicit option → env var → registered default.
  * Empty/whitespace-only values at any layer are treated as unset (the packaged
@@ -48,20 +35,13 @@ export interface GitHubAuthProviderOptions {
     /** Injectable sleep for tests (so polling tests run instantly). */
     sleepImpl?: (ms: number) => Promise<void>;
 }
-/** GitHub device-flow {@link RemoteAuthProvider} (ADR 0006 D1). */
-export declare class GitHubAuthProvider implements RemoteAuthProvider {
+/** GitHub device-flow credential acquisition (ADR 0006 D1). */
+export declare class GitHubAuthProvider {
     private readonly clientId;
     private readonly fetchImpl;
     private readonly sleep;
     constructor(options?: GitHubAuthProviderOptions);
-    matches(origin: URL): boolean;
     connect(callbacks: HostCallbacks): Promise<HostCredential>;
-    /**
-     * Cheap credential revalidation against `GET /user`. Returns `false` on any
-     * non-200 (401 revoked/expired, 403 forbidden/rate-limit-blocked, …);
-     * network failures are treated as "can't tell" → `true`.
-     */
-    validate(credential: HostCredential): Promise<boolean>;
     /** Best-effort login lookup after auth — failure is non-fatal. */
     private fetchUsername;
 }

package/dist/lib/remote-auth/operation-log.d.ts

@@ -20,10 +20,10 @@
  *   [ISO-timestamp] LEVEL  operation: step=<step> key=value ... | <message>
  *
  * Example:
- *   [2026-06-19T12:34:56.789Z] INFO  recovery: kind=unrelated_histories repo=my-book branch=main | starting recovery
- *   [2026-06-19T12:34:56.890Z] INFO  recovery: step=backup | backup created at /tmp/print-sync-recovery/my-book/...zip
- *   [2026-06-19T12:34:57.789Z] WARN  recovery: step=merge | merge conflicted files=manifest.yaml,notes.md
- *   [2026-06-19T12:34:57.890Z] INFO  recovery: result=needs_user | surfaced 2 conflicted files to user
+ *   [2026-06-19T12:34:56.789Z] INFO  sync: repo=my-book branch=main | starting sync
+ *   [2026-06-19T12:34:56.890Z] INFO  sync: step=snapshot | committed 3 changed files
+ *   [2026-06-19T12:34:57.789Z] WARN  sync: step=merge | combined files=manifest.yaml,notes.md
+ *   [2026-06-19T12:34:57.890Z] INFO  sync: result=synced | pushed to the online copy
  *
  * Cross-platform: uses `node:fs` appendFileSync + `node:path`. The caller
  * is responsible for providing a valid directory (the logger creates the
@@ -59,8 +59,3 @@ export declare function createFileLogger(logFile: string, operation: string, min
  * don't pass `logFile` see zero behavior change and zero file I/O).
  */
 export declare function resolveLogger(logFile: string | undefined, operation: string): OperationLogger;
-/**
- * Shorten a 40-char OID to the first 7 characters for compact log lines.
- * Same convention as `git log --oneline`.
- */
-export declare function shortOid(oid: string): string;

package/dist/lib/remote-auth/sync-messages.d.ts

@@ -1,8 +1,8 @@
 /**
- * Author-language copy for sync / pull / push / conflict-resolution (never raw
- * git words). Extracted from sync.ts so the transport, conflict-resolution and
- * orchestrator modules share ONE source of these strings — their exact wording
- * is part of the observable contract (the host renders them verbatim).
+ * Author-language copy for sync (never raw git words). Extracted from sync.ts
+ * so the transport and orchestrator modules share ONE source of these
+ * strings — their exact wording is part of the observable contract (the host
+ * renders them verbatim).
  */
 export declare const MSG_UP_TO_DATE = "Everything is in sync.";
 export declare const MSG_UP_TO_DATE_PULLED = "Everything is in sync. The latest online changes were downloaded to this computer.";
@@ -12,14 +12,37 @@ export declare const MSG_OFFLINE = "Your changes are saved on this computer. gut
 export declare const MSG_AUTH = "The online repository didn't accept the saved connection. Reconnect and try again.";
 export declare const MSG_INSECURE_TRANSPORT = "This project's online address isn't secure, so the saved connection wasn't sent \u2014 connections are never sent over an insecure address. Switch the address to a secure one (starting with https), or to a local loopback address for a server on this computer, to sync.";
 export declare const MSG_BUSY = "The online copy is changing very quickly right now. Your work is saved on this computer \u2014 try Sync again in a moment.";
-export declare const MSG_UNRELATED = "The online address points at a different project's files, so the two can't be combined. Check the project's online address.";
+/**
+ * The project's own version history is unreadable — a damaged or missing
+ * `.git`. Says the three things that are actually true and useful: the writing
+ * is safe, the HISTORY is what broke, and (sync always has a remote, so this
+ * always applies here) a fresh copy from online is the way back.
+ */
+export declare const MSG_HISTORY_UNREADABLE = "This project's version history can't be read, so syncing can't continue. Your writing is safe \u2014 every file is still here on this computer. To get history and syncing working again, download a fresh copy of the project from online, then move any recent changes into it.";
+export declare const MSG_UNRELATED = "This project and the online copy have no history in common, so they can't be combined. Either the online address points at a different project, or this project's own history was lost and started over. Your writing is safe \u2014 every file is still here on this computer. Check the online address; if it is correct, download a fresh copy from online and move any recent changes into it.";
 export declare const MSG_NO_REMOTE = "This project isn't connected to an online repository yet.";
 export declare const MSG_SSH_REMOTE = "This project's online address uses SSH (git@\u2026), which gutterpress can't sync to. Switch it to the web (HTTPS) address to sync from here.";
 export declare const MSG_NO_BRANCH = "This project's version history isn't on a named branch, so it can't be synced right now.";
-export declare const MSG_PULLED = "The latest online changes were downloaded to this computer.";
-export declare const MSG_PULLED_MERGED = "The latest online changes were combined with your changes on this computer.";
-export declare const MSG_PULL_UP_TO_DATE = "You already have the latest online changes.";
-export declare const MSG_PUSH_UP_TO_DATE = "There's nothing new to send \u2014 everything is already online.";
-export declare const MSG_PULL_FIRST = "The online copy has changes you don't have yet. Get the latest changes first, then send yours.";
-/** Message recorded on the automatic pre-sync snapshot (D5 invariant). */
-export declare const SYNC_SNAPSHOT_MESSAGE = "Snapshot before syncing";
+/** Message recorded on the automatic pre-sync snapshot (D5 invariant).
+ *  Pre-0.10.1 history carries the old spelling "Snapshot before syncing". */
+export declare const SYNC_SNAPSHOT_MESSAGE = "Automatic backup of your work";
+/**
+ * Message recorded when an edit reached disk while the fetch was in flight —
+ * after the pre-sync snapshot, before the merge (see the re-snapshot in
+ * `syncProject`). Distinct wording so the race is legible in history; the
+ * copy is already writer-voiced, so it deliberately stays unchanged (every
+ * rename permanently grows the timeline's superseded-spelling list).
+ */
+export declare const SYNC_LATE_EDIT_MESSAGE = "Saved the edit you made while syncing";
+/**
+ * The keep-both sibling contract, kept HERE rather than in converge-merge.ts
+ * because every consumer needs it and converge-merge pulls in isomorphic-git:
+ * the markdown file resolver must not render a sibling as a chapter, and the
+ * merge-marker check must report it. This file imports nothing, so any of
+ * them can depend on it.
+ *
+ * `art/cover.png` -> `art/cover.online.png`; extensionless `NOTES` -> `NOTES.online`.
+ */
+export declare function onlineSiblingPath(filepath: string): string;
+/** True for a path `onlineSiblingPath` produced — Gutterpress's artifact, not the author's. */
+export declare function isOnlineSibling(filepath: string): boolean;

package/dist/lib/remote-auth/sync-types.d.ts

@@ -16,26 +16,21 @@ import type { HostCredential, TokenStore } from "./token-store.ts";
  */
 export type GitCache = Record<string, unknown>;
 /**
- * One image file that changed on both sides. Sync already converged (the
- * NEWER side's bytes are on disk and committed — the safe default); this
- * record lets a host offer a non-blocking side-by-side picker afterwards.
- * Both blob oids are pinned by the merge commit's two parents, so the picker
- * can never go stale.
+ * One file that changed on both sides and cannot carry conflict markers (a
+ * binary, or an SVG whose XML markers would break). Both versions are on
+ * disk and committed: ours stayed at `path`, the online one was written
+ * beside it. The host names the pair so the writer can fix it by hand.
  */
-export interface ImageClash {
-    /** Repo-relative path of the image. */
+export interface KeptBothFile {
+    /** Repo-relative path holding OUR version (unchanged). */
     path: string;
-    /** Blob oid of the local version. */
-    localOid: string;
-    /** Blob oid of the online version. */
-    remoteOid: string;
-    /** Which side the automatic newer-wins policy kept on disk. */
-    kept: "local" | "online";
+    /** Repo-relative path holding the ONLINE version (`name.online.ext`). */
+    onlinePath: string;
 }
 /** Outcome of a sync attempt. Sync always converges — there is no "conflict"
  *  arm: overlapping text edits land in the file inside standard git conflict
- *  markers (`combinedFiles`), clashing binaries keep the newer side
- *  (`imageClashes` for images), and the other version is always reachable in
+ *  markers (`combinedFiles`), clashing binaries keep BOTH versions as two
+ *  files (`keptBothFiles`), and every version is always reachable in
  *  history. Owner ruling 2026-08-14. */
 export type SyncOutcome = {
     status: "synced";
@@ -48,13 +43,17 @@ export type SyncOutcome = {
     filesChanged?: boolean;
     /** Files whose text now holds BOTH versions inside git conflict markers. */
     combinedFiles?: string[];
-    /** Clashing images (newer kept) for the host's non-blocking picker. */
-    imageClashes?: ImageClash[];
+    /** Files kept as a pair (ours at `path`, theirs at `onlinePath`). */
+    keptBothFiles?: KeptBothFile[];
 } | {
     status: "up-to-date";
     message: string;
     snapshotId?: string;
     filesChanged?: boolean;
+    /** A pull-merge-only pass (`push: false`) can combine overlapping edits
+     *  and then hold the push — the converge report still surfaces here. */
+    combinedFiles?: string[];
+    keptBothFiles?: KeptBothFile[];
 } | {
     status: "auth";
     message: string;
@@ -68,90 +67,9 @@ export type SyncOutcome = {
 } | {
     status: "error";
     message: string;
-    /**
-     * Stable machine-readable signal so a host UI can route without
-     * string-matching `message` (which stays free to reword):
-     * "needs-connection-setup" — the project isn't set up right (no
-     * remote / SSH remote / no named branch); route to the connect/setup
-     * surface.
-     */
-    code?: "needs-connection-setup";
     snapshotId?: string;
     filesChanged?: boolean;
 };
-/**
- * Outcome of a pull-only attempt ({@link pullChanges}): fetch + fast-forward/
- * converge-merge of the online changes, NEVER a push. The merge always lands
- * (see converge-merge.ts) — there is no "conflict" arm.
- */
-export type PullOutcome = {
-    status: "pulled";
-    message: string;
-    /** Snapshot taken of unsaved work before pulling, if any. */
-    snapshotId?: string;
-    /**
-     * True when the pull created a combine (merge) commit — local commits
-     * existed alongside the online ones. False for a plain fast-forward.
-     */
-    merged: boolean;
-    /**
-     * True when the working tree CONTENT changed (the tip's tree differs
-     * from before) — the host should refresh its preview.
-     */
-    filesChanged: boolean;
-    /** Files whose text now holds BOTH versions inside git conflict markers. */
-    combinedFiles?: string[];
-    /** Clashing images (newer kept) for the host's non-blocking picker. */
-    imageClashes?: ImageClash[];
-} | {
-    status: "up-to-date";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "auth";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "offline";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "error";
-    message: string;
-    snapshotId?: string;
-};
-/**
- * Outcome of a push-only attempt ({@link pushChanges}): snapshot-if-needed,
- * then push — NEVER a merge. When the online copy has commits this computer
- * doesn't have, the result is the typed `"pull-first"` status (the host shows
- * a plain-language "get the latest changes first" message) — pushChanges
- * never auto-merges.
- */
-export type PushOutcome = {
-    status: "pushed";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "up-to-date";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "pull-first";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "auth";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "offline";
-    message: string;
-    snapshotId?: string;
-} | {
-    status: "error";
-    message: string;
-    snapshotId?: string;
-};
 export interface SyncProjectOptions {
     projectDir: string;
     /** Explicit credential; wins over the token store. */
@@ -162,12 +80,23 @@ export interface SyncProjectOptions {
     message?: string;
     authorName?: string;
     authorEmail?: string;
+    /**
+     * When `false`, run a pull-merge-only pass: fetch + converge-merge exactly
+     * as always (remote work still arrives promptly), but hold the network push
+     * — and mint no snapshot unless the remote moved and the merge needs one
+     * (D5), so a quiet pass creates no commit at all. Local work stays safely
+     * committed/on disk for the next push-enabled pass to send. Default `true`:
+     * the full snapshot-first → fetch → merge → push pass. Owner decision
+     * 2026-08-23 (push cadence): the desktop's 2-minute tick pulls every time
+     * and enables the push only every ~15 minutes and on app exit.
+     */
+    push?: boolean;
     /** Injectable git HTTP transport for tests. */
     httpClient?: typeof httpNode;
     /**
-     * Bounded retry policy for {@link syncProject}'s pull→push race loop. The
-     * loop is ALWAYS bounded (never infinite) and the snapshot-first guarantee
-     * holds on every path. Defaults to {@link DEFAULT_SYNC_RETRY}. `sleep` is
+     * Bounded retry policy for {@link syncProject}'s fetch→merge→push race
+     * loop. The loop is ALWAYS bounded (never infinite) and the snapshot-first
+     * guarantee holds on every path. Defaults to {@link DEFAULT_SYNC_RETRY}. `sleep` is
      * injectable so tests can drive backoff deterministically.
      */
     retry?: SyncRetryOptions;

package/dist/lib/remote-auth/sync.d.ts

@@ -1,30 +1,28 @@
 import { onAuthFor } from "./transport.ts";
-import type { PullOutcome, PushOutcome, SyncOutcome, SyncProjectOptions } from "./sync-types.ts";
+import type { SyncOutcome, SyncProjectOptions } from "./sync-types.ts";
 export { onAuthFor };
 export { SYNC_SNAPSHOT_MESSAGE } from "./sync-messages.ts";
-export type { ImageClash, PullOutcome, PushOutcome, SyncOutcome, SyncProjectOptions, } from "./sync-types.ts";
+export type { KeptBothFile, SyncOutcome, SyncProjectOptions, } from "./sync-types.ts";
 /**
- * Snapshot-first sync (ADR 0006 D5) — the composition of {@link pullChanges}
- * then {@link pushChanges}. If someone pushes between our pull and our push,
- * the push reports pull-first and the pair re-runs (their commits converge in
- * on the next pass), with a short backoff between passes. The loop is ALWAYS
- * bounded by `retry.attempts`; a remote that races every pass surfaces a
- * friendly "try again in a moment" rather than looping forever. Never throws
- * for expected outcomes — everything is reported through {@link SyncOutcome}.
+ * A push the remote refused because our branch is behind — the pull-first
+ * situation the retry loop exists for.
  */
-export declare function syncProject(options: SyncProjectOptions): Promise<SyncOutcome>;
+export declare function isPushRejected(e: unknown): boolean;
 /**
- * Pull-only operation (the History tab's "Pull"): snapshot-if-needed →
- * fetch → fast-forward or CONVERGE-merge of the online changes — NEVER a
- * push, never a question. Serialized on the per-repo lock; one
- * function-scoped object cache, released on return.
+ * Unrelated histories — the local project and the configured online project
+ * share no common starting point. Sync surfaces this as a plain setup error
+ * (a wrong online address must never be silently spliced into the book).
  */
-export declare function pullChanges(options: SyncProjectOptions): Promise<PullOutcome>;
+export declare function isUnrelatedHistories(e: unknown): boolean;
 /**
- * Push-only operation (the History tab's "Push"): snapshot-if-needed → push.
- * If the online copy has commits this computer doesn't have (non-fast-forward),
- * it does NOT auto-merge — the typed `"pull-first"` result tells the host to
- * show a plain-language "get the latest changes first" message. Serialized on
- * the per-repo lock; one function-scoped object cache, released on return.
+ * Snapshot-first sync (ADR 0006 D5). Serialized on the per-repo lock; one
+ * function-scoped object cache, released on return.
+ *
+ * If someone pushes between our fetch and our push, the push is rejected and
+ * the fetch→merge→push pass re-runs (their commits converge in on the next
+ * fetch), with a short backoff between passes. The loop is ALWAYS bounded by
+ * `retry.attempts`; a remote that races every pass surfaces a friendly "try
+ * again in a moment" rather than looping forever. Never throws for expected
+ * outcomes — everything is reported through {@link SyncOutcome}.
  */
-export declare function pushChanges(options: SyncProjectOptions): Promise<PushOutcome>;
+export declare function syncProject(options: SyncProjectOptions): Promise<SyncOutcome>;

package/dist/lib/remote-auth/token-store.d.ts

@@ -25,10 +25,6 @@ export interface TokenStore {
     /** All stored credentials (used by "connected accounts" UIs). */
     list(): Promise<HostCredential[]>;
 }
-/** A credential with the token value masked — safe for logs/diagnostics. */
-export declare function redactCredential(cred: HostCredential): Omit<HostCredential, "token"> & {
-    token: string;
-};
 /**
  * THE canonical credential-store key for a remote host — the ONE derivation
  * every writer (GitHub device flow, generic connect, embedded-URL migration)
@@ -87,9 +83,3 @@ export interface UrlCredentialExtraction {
  * display. Non-HTTP(S) or unparseable URLs pass through unchanged.
  */
 export declare function extractUrlCredential(url: string): UrlCredentialExtraction;
-/**
- * Migrate any credential embedded in `url` into `store` (only when the store
- * has no existing credential for that host — a stored credential is fresher
- * than one fossilized in a clone URL) and return the sanitized URL.
- */
-export declare function migrateUrlCredential(url: string, store: TokenStore): Promise<string>;

package/dist/lib/remote-auth/transport.d.ts

@@ -1,6 +1,5 @@
 import httpNode from "isomorphic-git/http/node";
 import { type HostCredential, type TokenStore } from "./token-store.ts";
-import type { OperationLogger } from "./operation-log.ts";
 import type { GitCache, RemoteTransport } from "./sync-types.ts";
 /**
  * The git repo directory for a project dir. A project IS its git repo, so this
@@ -17,6 +16,19 @@ export declare function repoDirFor(projectDir: string): Promise<string>;
  * http carries no network exposure, so it stays allowed.
  */
 export declare function isCredentialTransmissionSafe(url: string): boolean;
+/**
+ * Thrown by {@link onAuthFor} when a stored credential EXISTS but the remote
+ * URL fails {@link isCredentialTransmissionSafe} (non-loopback http). Loud and
+ * typed on purpose: the old behavior (silently withholding the credential)
+ * surfaced as a 401 → "auth" → "reconnect" loop. The `code` string is the
+ * STABLE contract (matchable across dynamic-import boundaries).
+ */
+export declare class InsecureTransportError extends Error {
+    readonly code = "InsecureTransport";
+    constructor();
+}
+/** Type guard for {@link InsecureTransportError} (matches on the stable code). */
+export declare function isInsecureTransportError(e: unknown): e is InsecureTransportError;
 export declare function onAuthFor(credential: HostCredential | undefined): {
     onAuth?: undefined;
 } | {
@@ -35,13 +47,19 @@ export declare function resolveTransport(dir: string, options: {
     tokenStore?: TokenStore;
 }): Promise<RemoteTransport>;
 /**
- * The failure arms shared verbatim by {@link SyncOutcome}, {@link PullOutcome}
- * and {@link PushOutcome} — so one classifier serves all three operations.
- * Decoding delegates to the shared recovery classifier
- * (classifyTransportFailure): auth_required → "auth", network_unavailable →
- * "offline", insecure_transport → "error" with its dedicated message (NEVER
- * "auth" — reconnecting can't fix an http:// address, and the auth recovery
- * path deletes the stored credential), anything else → the generic "error" arm.
+ * Decode a thrown transport error into the outcome it maps to, or null when it
+ * is not a transport failure at all. The single source of truth for transport
+ * error decoding — sync.ts and clone.ts consume it rather than keeping
+ * parallel copies.
+ */
+export declare function classifyTransportFailure(e: unknown): "auth_required" | "network_unavailable" | "insecure_transport" | null;
+/**
+ * The failure arms of {@link SyncOutcome}. Decoding delegates to
+ * {@link classifyTransportFailure}: auth_required → "auth",
+ * network_unavailable → "offline", insecure_transport → "error" with its
+ * dedicated message (NEVER "auth" — reconnecting can't fix an http:// address,
+ * and the auth recovery path deletes the stored credential), anything else →
+ * the generic "error" arm.
  */
 export declare function failureOutcome(e: unknown, snapshotId?: string): {
     status: "auth" | "offline" | "error";
@@ -51,7 +69,7 @@ export declare function failureOutcome(e: unknown, snapshotId?: string): {
 /** Friendly setup-problem message for the expected gate errors, else null. */
 export declare function setupErrorMessage(e: unknown): string | null;
 /**
- * Snapshot-first step shared by syncProject / pullChanges / pushChanges
+ * Snapshot-first step used by syncProject
  * (ADR 0006 D5): commit any unsaved work in the WHOLE repo BEFORE any network
  * or merge step, so a forced post-merge checkout can never discard it. The
  * working-tree check runs lazily at action time on the caller's function-scoped
@@ -65,44 +83,28 @@ export declare function snapshotBeforeAction(args: {
     authorEmail?: string;
     cache: GitCache;
 }): Promise<string | undefined>;
-/**
- * Structural preflight — never touch the tree of a damaged repo. An interrupted
- * merge/rebase/cherry-pick, detached HEAD, stale lock, or missing `.git` must be
- * REPAIRED before any sync work: snapshot-first would otherwise commit whatever
- * is on disk (e.g. the literal conflict markers a half-done native-git merge
- * leaves in tracked files) and push it to every collaborator. Throwing the
- * typed error routes the caller through the recover() path.
- * `checkLocalChanges: false` — only the structural flags matter here.
- *
- * Runs INSIDE the caller's repo lock. Shared by pullChanges and pushChanges.
- */
-export declare function assertNoStructuralDamage(projectDir: string, logger: OperationLogger): Promise<void>;
 export declare function currentBranchOrThrow(dir: string): Promise<string>;
 /**
- * Run `fn` (a fetch that moves remote-tracking refs) with a rollback guard
- * (deep-analysis R15): isomorphic-git updates refs/remotes/<remote>/* from
- * the ref advertisement BEFORE collecting the packfile, so an abort
- * mid-transfer (e.g. the defaultGitHttp idle timeout) leaves refs pointing
- * at oids with no local object. Such a dangling ref poisons the next fetch —
+ * Run `fn` (a fetch that moves ONE remote-tracking ref) with a rollback guard
+ * (deep-analysis R15): isomorphic-git updates `refs/remotes/<remote>/<branch>`
+ * from the ref advertisement BEFORE collecting the packfile, so an abort
+ * mid-transfer (e.g. the defaultGitHttp idle timeout) leaves the ref pointing
+ * at an oid with no local object. Such a dangling ref poisons the next fetch —
  * zero `have`s → the server streams the ENTIRE repository (the OOM
- * fetchRemoteTip's `ref` choice exists to prevent) — and resolving it reports
+ * `fetchRemoteTip`'s `ref` choice exists to prevent) — and resolving it reports
  * missing-object "corruption" on a never-corrupt repo.
  *
- * `listRefs` names the refs at risk; it runs again after a throw so refs
- * CREATED by `fn` are covered too. If `fn` throws, every ref that moved to an
- * oid whose object is MISSING locally is restored to its previous oid (or
- * deleted if it didn't exist); refs whose objects DID land are kept — the
- * pack made it. On success no ref is touched. Restoration is best-effort,
- * per ref, and never masks `fn`'s error.
+ * If `fn` throws and the ref moved to an oid whose object is MISSING locally,
+ * it is restored to its previous oid (or DELETED if it did not exist before).
+ * A ref whose object DID land is kept — the pack made it. On success no ref is
+ * touched.
+ *
+ * Every read here is best-effort and never masks `fn`'s error: a damaged ref
+ * store must not block the guarded fetch, because the recovery handlers run on
+ * exactly such repos and skipping `fn` would skip the repair itself. An
+ * unreadable pre-scan simply degrades to the delete-if-dangling arm.
  */
-export declare function guardRefs<T>(dir: string, listRefs: () => Promise<string[]>, cache: GitCache, fn: () => Promise<T>): Promise<T>;
-/** Single-ref form of {@link guardRefs} — guards one remote-tracking ref. */
 export declare function guardTrackingRef<T>(dir: string, ref: string, cache: GitCache, fn: () => Promise<T>): Promise<T>;
-/**
- * Remote-wide form of {@link guardRefs} for a fetch that may move or create
- * ANY refs/remotes/<remote>/* ref (e.g. `singleBranch: false`).
- */
-export declare function guardRemoteRefs<T>(dir: string, remote: string, cache: GitCache, fn: () => Promise<T>): Promise<T>;
 /**
  * Fetch the tracked branch's online tip. Returns `null` when the online
  * repository has no such branch yet (a freshly created empty repo).

package/dist/lib/source-provider.d.ts

@@ -38,6 +38,18 @@ export interface SnapshotOptions {
     repoRoot?: string;
     /** Optional log file for debugging snapshot operations. */
     logFile?: string;
+    /**
+     * The CALLER's object cache, when the snapshot is one step of a longer
+     * locked operation (sync). Committing rewrites `.git/index`, and
+     * isomorphic-git's index cache invalidates on a stat comparison that can
+     * miss a same-second rewrite of the same size — so a caller that keeps
+     * using its own cache afterwards would keep reading the PRE-snapshot index.
+     * That is not cosmetic: `git.checkout` derives STAGE from it, and a stale
+     * STAGE makes an unmodified file look locally modified. Pass the cache and
+     * the snapshot's own `git.add`/`git.commit` refresh it in place. Omit it
+     * for standalone snapshots — they get a private cache, released on return.
+     */
+    cache?: GitCache;
 }
 /**
  * The git repo directory a project's operations run against. A project IS its

package/dist/{lint-p2sw53d9.js → lint-c8ze8sqw.js}

@@ -1,21 +1,21 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-eq5naw4m.js";
+} from "./cli-7n848af2.js";
 import {
   log
-} from "./cli-cqtggsng.js";
+} from "./cli-0z6zf98d.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-149edp6b.js";
-import"./cli-zfcryxg8.js";
+} from "./cli-ydpf09d9.js";
+import"./cli-eewynen9.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
-import"./cli-k1065rkg.js";
+import"./cli-w692g6dx.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 

package/dist/{new-hvq0x91q.js → new-xy2qc300.js}

@@ -5,23 +5,23 @@ import {
   TARGETS,
   TARGET_IDS,
   scaffoldProject
-} from "./cli-eq5naw4m.js";
+} from "./cli-7n848af2.js";
 import {
   resolveGhostscript
-} from "./cli-cqtggsng.js";
+} from "./cli-0z6zf98d.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-149edp6b.js";
-import"./cli-zfcryxg8.js";
+} from "./cli-ydpf09d9.js";
+import"./cli-eewynen9.js";
 import {
   isToolAvailable
 } from "./cli-c41yr7he.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
-import"./cli-k1065rkg.js";
+import"./cli-w692g6dx.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 

package/dist/{plugin-pssmk0dx.js → plugin-g9hwzjsm.js}

@@ -1,19 +1,19 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-eq5naw4m.js";
-import"./cli-cqtggsng.js";
+} from "./cli-7n848af2.js";
+import"./cli-0z6zf98d.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-149edp6b.js";
-import"./cli-zfcryxg8.js";
+} from "./cli-ydpf09d9.js";
+import"./cli-eewynen9.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
-import"./cli-k1065rkg.js";
+import"./cli-w692g6dx.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 

package/dist/{preflight-4j00yd0g.js → preflight-prcvdvmk.js}

@@ -2,21 +2,21 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-eq5naw4m.js";
+} from "./cli-7n848af2.js";
 import {
   log
-} from "./cli-cqtggsng.js";
+} from "./cli-0z6zf98d.js";
 import {
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-149edp6b.js";
-import"./cli-zfcryxg8.js";
+} from "./cli-ydpf09d9.js";
+import"./cli-eewynen9.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES
 } from "./cli-46ycxe6r.js";
-import"./cli-k1065rkg.js";
+import"./cli-w692g6dx.js";
 import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";