gutterpress 0.10.0 → 0.10.1-beta.1

package/dist/lib/git-fs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `node:fs`, with crash-atomic writes for git's MUTABLE metadata.
+ *
+ * WHY THIS EXISTS. isomorphic-git writes `.git/index`, `HEAD`, `packed-refs`
+ * and loose refs with a plain `fs.writeFile` — an open-truncate-write. If the
+ * process dies between the truncate and the write (the writer force-quits the
+ * app, the OS kills it, the machine sleeps badly) the file is left EMPTY or
+ * half-written, and the repository can no longer be read. That is the one
+ * class of history damage Gutterpress itself causes; every other class needs
+ * an outside actor. Since isomorphic-git takes `fs` as a parameter, replacing
+ * the write with temp-file + `rename` removes the truncation window entirely
+ * — a reader sees either the old file or the new one, never a torn one.
+ *
+ * SCOPE. Only git's mutable metadata is redirected. Working-tree files and
+ * content-addressed objects keep the plain write: objects are written once
+ * under a hash of their contents (a torn object is a NEW file that simply
+ * fails to inflate, it never destroys a good one), and the working tree is
+ * the author's own files, which `rename` semantics would not improve.
+ *
+ * NOT A DURABILITY BARRIER. There is deliberately no `fsync`: this closes the
+ * PROCESS-DEATH window, where the page cache survives and `rename` is atomic
+ * to every reader. Surviving sudden power loss would mean fsync-ing the temp
+ * file and its directory on every ref write, which is a real cost on the
+ * snapshot hot path and guards a failure the app does not cause.
+ *
+ * Everything not named below passes through to `node:fs` unchanged, so
+ * `import { gitFs as fs }` is a drop-in for `import * as fs from "node:fs"`.
+ */
+import * as nodeFs from "node:fs";
+/** True when `file` is git metadata that must be replaced, never truncated. */
+export declare function needsAtomicWrite(file: unknown): file is string;
+/**
+ * `node:fs` with the two writers above swapped in — the object callers import
+ * as `fs` and hand to isomorphic-git. Everything else passes through
+ * untouched.
+ *
+ * WHY an object and not `export * from "node:fs"`: bun build with
+ * `--packages=external` compiles a star re-export of a BUILTIN into a
+ * `__reExport(exports, node_fs)` call whose `node_fs` binding is never
+ * emitted, so the built lib throws `ReferenceError: node_fs is not defined`
+ * on import. A plain spread has no such hazard.
+ */
+export declare const gitFs: typeof nodeFs;

package/dist/lib/host-policy.d.ts

@@ -40,6 +40,17 @@ export interface AutoSyncPolicy {
 export declare const AUTO_SYNC_MIN_MINUTES = 1;
 export declare const AUTO_SYNC_MAX_MINUTES: number;
 export declare const AUTO_SYNC_DEFAULT_MINUTES = 2;
+/**
+ * Minutes between PUSH-enabled auto-sync passes (owner decision 2026-08-23).
+ * Every ~2-minute tick still PULLS — a collaborator's work keeps arriving
+ * promptly — but only a tick whose push window has elapsed also pushes, and
+ * the desktop pushes once more on project close/app exit. This is what keeps
+ * an actively-typing author from minting a snapshot-and-push every 2 minutes
+ * (the "commit wall"): between push windows, ticks with an unmoved remote
+ * commit nothing at all. Deliberately a constant, NOT a settings knob — the
+ * sync cadence is hidden policy, same as the tick interval's default.
+ */
+export declare const AUTO_SYNC_PUSH_INTERVAL_MINUTES = 15;
 /**
  * Resolve the debounce delay (ms) for the host's auto-snapshot timer, or
  * `null` when automatic snapshots are disabled. Pure — the testable core of
@@ -61,8 +72,9 @@ export declare function autoSnapshotDelayMs(policy: Partial<AutoSnapshotPolicy>
  * the default and is then clamped into [AUTO_SYNC_MIN_MINUTES,
  * AUTO_SYNC_MAX_MINUTES].
  *
- * Note: the host orchestrator ALSO debounces on file-change triggers; this
- * cadence governs only the periodic safety timer (§4.2 "Periodic safety").
+ * Note: this is the host orchestrator's ONLY sync trigger — the file-change
+ * debounce that used to sit beside it was removed (it could never fire before
+ * this interval already had).
  */
 export declare function autoSyncDelayMs(policy: Partial<AutoSyncPolicy> | undefined): number | null;
 /**

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

@@ -7,22 +7,6 @@ export interface CloneProgressEvent {
     loaded: number;
     total?: number;
 }
-/**
- * Provider provenance recorded next to a cloned project (ADR 0006 D4):
- * metadata for the repo picker / re-auth UX, never consulted by the
- * editing/preview/build paths.
- */
-export interface ProjectProvenance {
-    provider: "github";
-    owner: string;
-    repo: string;
-    /**
-     * Legacy GitHub-App installation id. New clones never write it (the OAuth
-     * App model has no installations — ADR 0006 D1 amendment 2026-06-10); kept
-     * optional so provenance files written by 0.4.x betas still parse.
-     */
-    installationId?: string;
-}
 export interface CloneRepositoryOptions {
     /** HTTPS clone URL. Tokens embedded in the URL are stripped (D7). */
     url: string;
@@ -49,8 +33,6 @@ export interface CloneRepositoryOptions {
     onProgress?: (event: CloneProgressEvent) => void;
     /** When provided, credentials embedded in `url` are migrated into it (D7). */
     tokenStore?: TokenStore;
-    /** Provider provenance to record beside the clone (ADR 0006 D4). */
-    provenance?: ProjectProvenance;
     /**
      * Injectable git HTTP transport for tests (isomorphic-git's `http` client
      * shape). Defaults to isomorphic-git's node client.
@@ -63,9 +45,6 @@ export interface CloneRepositoryResult {
     /** The checked-out branch. */
     branch?: string;
 }
-export declare function provenancePath(projectDir: string): string;
-/** Read recorded provider provenance for a project, if any. Never throws. */
-export declare function readProjectProvenance(projectDir: string): Promise<ProjectProvenance | null>;
 /**
  * Reduce a (possibly renderer-/user-supplied) project folder name to a single
  * safe path segment: path separators become dashes and leading dots are

package/dist/lib/remote-auth/converge-merge.d.ts

@@ -1,5 +1,23 @@
-import type { GitCache, ImageClash } from "./sync-types.ts";
-export type { ImageClash };
+import { onlineSiblingPath, isOnlineSibling } from "./sync-messages.ts";
+export { onlineSiblingPath, isOnlineSibling };
+import type { GitCache, KeptBothFile } from "./sync-types.ts";
+export type { KeptBothFile };
+/** Type guard exposing MergeConflictError's per-file payload. */
+export declare function isMergeConflictError(e: unknown): e is {
+    data: {
+        filepaths: string[];
+        bothModified: string[];
+        deleteByUs: string[];
+        deleteByTheirs: string[];
+    };
+};
+/**
+ * A non-forced `git.checkout` refused to overwrite working-tree files whose
+ * content moved after we committed them. isomorphic-git detects this in its
+ * analysis pass and throws BEFORE touching the tree, so the refusal is
+ * atomic: nothing on disk has been written.
+ */
+export declare function isCheckoutConflict(e: unknown): boolean;
 export interface ConvergeResult {
     /** The branch tip after the merge (the merge commit, or the ff/no-op tip). */
     oid: string;
@@ -8,13 +26,13 @@ export interface ConvergeResult {
      * the writer should blend these. Empty when everything merged cleanly.
      */
     combinedFiles: string[];
-    /** Clashing images (newer version kept) for the non-blocking picker. */
-    imageClashes: ImageClash[];
+    /** Files kept as a pair: ours at `path`, theirs at `onlinePath`. */
+    keptBothFiles: KeptBothFile[];
 }
 /** Snapshot message for the equalization commit (driver-unreachable cases). */
 export declare const CONVERGE_PREPARE_MESSAGE = "Getting your changes ready to combine with the online version";
-/** Snapshot message for the post-merge restore commit (newer-wins/edits). */
-export declare const CONVERGE_RESTORE_MESSAGE = "Kept the newest version of files that can't be combined";
+/** Snapshot message for the post-merge restore commit (kept-both/edits). */
+export declare const CONVERGE_RESTORE_MESSAGE = "Kept both versions of the files that can't be combined";
 /** The merge commit message (same wording the old sync used). */
 export declare const CONVERGE_MERGE_MESSAGE = "Combined your changes with the online version";
 /**
@@ -44,5 +62,4 @@ export declare function convergeMerge(params: {
     };
     authorName?: string;
     authorEmail?: string;
-    allowUnrelatedHistories?: boolean;
 }): Promise<ConvergeResult>;

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

@@ -15,7 +15,6 @@
  * SECURITY INVARIANT: token values never appear in error messages or logs.
  */
 import type httpNode from "isomorphic-git/http/node";
-import type { HostCallbacks, RemoteAuthProvider } from "./github-auth.ts";
 import { type HostCredential } from "./token-store.ts";
 /** What the Advanced Setup UI collects for "Connect a Git server". */
 export interface GenericTokenConnectInput {
@@ -38,14 +37,6 @@ export interface GenericTokenConnectInput {
      */
     repoUrl?: string;
 }
-/**
- * The {@link RemoteAuthProvider} `connect` input for the generic provider:
- * the UI-collected fields plus the standard host callbacks (`onUserCode` is
- * part of the shared contract but unused — there is no device code in the
- * token flow; pass a no-op, or use {@link connectGenericHost} directly).
- */
-export interface GenericHostCallbacks extends HostCallbacks, GenericTokenConnectInput {
-}
 export interface GenericAuthOptions {
     /** Injectable git HTTP transport for tests. */
     httpClient?: typeof httpNode;
@@ -82,16 +73,3 @@ export declare function knownForgeTokenUrl(host: string): string | null;
  * a full end-to-end verification of the token against a real repository.
  */
 export declare function connectGenericHost(input: GenericTokenConnectInput, options?: GenericAuthOptions): Promise<HostCredential>;
-/**
- * {@link RemoteAuthProvider} wrapper for the generic token flow, so host apps
- * can route any non-GitHub origin through the shared provider contract.
- */
-export declare class GenericTokenAuthProvider implements RemoteAuthProvider {
-    private readonly options;
-    constructor(options?: GenericAuthOptions);
-    /** Handles any smart-HTTP(S) host that is not github.com (device flow). */
-    matches(origin: URL): boolean;
-    connect(callbacks: GenericHostCallbacks): Promise<HostCredential>;
-    /** Revalidate a stored credential: false only on a definitive rejection. */
-    validate(credential: HostCredential): Promise<boolean>;
-}

package/dist/lib/remote-auth/git-http.d.ts

@@ -31,7 +31,7 @@
  *
  * One timer serves the whole request (re-armed via `refresh()`; no per-chunk
  * allocation). On timeout the thrown error's message classifies as offline in
- * recovery/classify.ts. Known limitation (documented, not fixable at this
+ * transport.ts. Known limitation (documented, not fixable at this
  * layer): isomorphic-git's client accepts no AbortSignal, so an abandoned
  * timed-out transfer's socket is left to the OS/agent to reap.
  *

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>;