gutterpress 0.0.0

package/dist/lib/remote-auth/recovery/inspect.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Preflight repo health probe for the sync-recovery subsystem.
+ *
+ * inspectRepo() reads local filesystem state ONLY — no network, no git objects,
+ * never throws. It returns a RepoHealth snapshot that the classifier and policy
+ * lookup use to decide which recovery path to take.
+ *
+ * Reuses:
+ *   - gitDirFor (source-provider.ts) for the .git dir path
+ *   - hasPendingChanges (source-provider.ts) for local-changes detection
+ *
+ * Notes on two health facts:
+ *   - hasGitDir is true whenever `.git/` EXISTS, even with a missing/corrupt
+ *     HEAD (a damaged repo is still a repo — see the inline note at the check).
+ *   - hasStaleLock uses the stale-lock handler's OWN lock scanner
+ *     (findLockCandidates in recover-stale-lock.ts) — one implementation, so
+ *     health and handler can never disagree about which locks exist.
+ *
+ * All probes are best-effort and throw-free (the caller must never see an
+ * exception from a preflight probe).
+ */
+import type { LogData } from "../operation-log.ts";
+import type { RepoHealth, RecoveryContext, SyncErrorKind } from "./types.ts";
+/**
+ * Probe the local repository and return a RepoHealth snapshot.
+ * Never throws — on any error the relevant flag is set conservatively.
+ *
+ * `checkLocalChanges: false` skips the hasPendingChanges working-tree walk
+ * (the one non-trivial probe) and reports hasLocalChanges=false. Use it when
+ * only the structural flags matter — e.g. syncProject's preflight, whose
+ * pull step immediately performs the same walk anyway (sync-simplicity
+ * mandate: no redundant walks on the hot path).
+ */
+export declare function inspectRepo(ctx: Pick<RecoveryContext, "repoDir" | "source">, opts?: {
+    checkLocalChanges?: boolean;
+}): Promise<RepoHealth>;
+/**
+ * Confirm the repo's object store is actually readable: resolve HEAD, read
+ * its commit, and read its root tree. Throws when any step fails (missing or
+ * corrupt object/ref); resolves when the repo is fully readable.
+ *
+ * This is the SAME verification recover-missing-objects.ts performs to check
+ * whether a fetch actually repaired the object store — it is exported here so
+ * that check and the repair command's diagnosis step share ONE implementation
+ * rather than two copies that could drift. `inspectRepo`'s health flags are
+ * all filesystem-presence checks (no object is ever read), so they cannot
+ * detect object-store corruption on their own — callers that need to catch
+ * `corrupt_index` / `missing_or_corrupt_objects` / `unrelated_histories` /
+ * `wrong_remote_or_branch` must run this probe and feed a caught error
+ * through `classifyGitError`.
+ */
+export declare function verifyRepoReadable(dir: string): Promise<void>;
+/**
+ * True when HEAD names a branch that simply has no commits yet — a fresh
+ * `git init` before the first snapshot. In that state `verifyRepoReadable`
+ * throws the SAME NotFoundError as a damaged ref store, but the repo is
+ * healthy, not corrupt. The distinguishing signal is the object store: a
+ * fresh repo has NO objects at all, while ref damage on a real repo leaves
+ * loose objects and/or packfiles behind.
+ */
+export declare function isUnbornRepo(repoDir: string): boolean;
+/**
+ * The SINGLE health signal that drove classification. Derived from the KIND
+ * classifyFromHealth returned (a pure mapping — it cannot drift from the
+ * classifier's decision order, because it never re-implements it).
+ */
+export declare function preflightStructuralReason(kind: SyncErrorKind | null): string;
+/**
+ * Build a flat, secret-free record of the preflight decision inputs for the
+ * operation log. Every health boolean is recorded (so support can see the FULL
+ * picture, not just the one-word kind), plus the opened dir vs repo root, the
+ * chosen kind, and the single reason that drove it.
+ */
+export declare function buildPreflightDiagnostics(openedDir: string, repoDir: string, health: RepoHealth, kind: SyncErrorKind | null): LogData;

package/dist/lib/remote-auth/recovery/manual-guidance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Plain-language guidance builders for the sync-recovery subsystem.
+ *
+ * AUTHOR-FACING COPY RULES (non-negotiable):
+ *   - No git words ("branch", "commit", "rebase", "ref", "HEAD", etc.)
+ *   - No tokens or credentials
+ *   - No internal file paths (no .git/, no /tmp paths in userSummary)
+ *   - No technical error codes in user-facing fields
+ *   - supportDetails MAY contain technical info for support tickets
+ *
+ * Each SyncErrorKind gets its own copy block. The host maps the
+ * ManualGuidance to its display surface.
+ */
+import type { ManualGuidance, RecoveryContext, SyncErrorKind } from "./types.ts";
+/**
+ * Build a ManualGuidance for a given error kind. The guidance is shown when
+ * a repair is blocked, failed, or needs user action. Never throws.
+ *
+ * SAFETY-COPY HONESTY: the "a safety copy was saved" reassurance is generated
+ * in ONE place, from the actual `backupZipPath` — never hardcoded per kind.
+ * The backup gate creates (and verifies) the zip BEFORE confirmation, so
+ * whenever this guidance is shown for a backup-requiring kind, a present
+ * backupZipPath means the copy really exists, and an absent one means backup
+ * creation FAILED and nothing was changed (failsafe.ts returns
+ * failed_no_changes_made without any writes). Promising a safety copy in that
+ * second case would be false — the one moment the promise matters most.
+ */
+export declare function makeManualGuidance(ctx: Pick<RecoveryContext, "repoSlug" | "remoteUrl">, kind: SyncErrorKind, error?: unknown, backupZipPath?: string): ManualGuidance;

package/dist/lib/remote-auth/recovery/outcome-mapping.d.ts

@@ -0,0 +1,58 @@
+/**
+ * outcome-mapping.ts — shared SyncOutcome/PullOutcome → RecoveryResult mapping.
+ *
+ * WHY this exists: five thin recovery handlers (recover-non-fast-forward,
+ * recover-auth, recover-network, recover-merge-conflict, recover-binary-conflict)
+ * all build the SAME syncProject/pullChanges options object from the context and
+ * then translate the typed outcome union into a RecoveryResult. The option
+ * object was copied verbatim five times, and the outcome→result maps had drifted
+ * apart (e.g. an `offline` outcome mapped to `retry_later` in one handler and to
+ * `needs_user` in another). This module owns the ONE default map; each handler
+ * passes only the per-status `overrides` where its behavior INTENTIONALLY
+ * differs, so the disagreements are explicit rather than accidental copies.
+ *
+ * DEFAULT OUTCOME MAP (what a handler gets with no overrides):
+ *   synced       → recovered              { message: outcome.message }
+ *   pulled       → recovered              { message: outcome.message }
+ *   up-to-date   → recovered              { message: outcome.message }
+ *   conflict     → needs_user             { message, guidance: merge_conflict, files }
+ *   auth         → needs_user             { message, guidance: auth_required }
+ *   offline      → retry_later            { message, retryAfterMs: RETRY_AFTER_MS }
+ *   error /      → failed_no_changes_made { message, guidance: unknown }
+ *   (unknown)
+ *
+ * An override wins over the default for its status. An UNKNOWN/future status
+ * routes to the `error` builder (override first, then default) — mirroring the
+ * `default:` arm every handler used to carry.
+ */
+import type { PullOutcome, SyncOutcome } from "../sync.ts";
+import type { RecoveryContext, RecoveryResult } from "./types.ts";
+/** Fixed delay before the next automated retry (30 seconds). */
+export declare const RETRY_AFTER_MS = 30000;
+/** The typed outcome unions the recovery handlers translate. */
+export type AnyOutcome = SyncOutcome | PullOutcome;
+/** Every status either outcome union can carry. */
+export type OutcomeStatus = AnyOutcome["status"];
+/** Builds a RecoveryResult from the context and the (already-classified) outcome. */
+export type OutcomeBuilder = (ctx: RecoveryContext, outcome: AnyOutcome) => RecoveryResult;
+/** Per-status overrides a handler supplies where it intentionally differs. */
+export type OutcomeOverrides = Partial<Record<OutcomeStatus, OutcomeBuilder>>;
+/**
+ * The shared options object every handler feeds to syncProject / pullChanges.
+ * Extracted so the five copies can never drift.
+ */
+export declare function syncOptionsFrom(ctx: RecoveryContext): {
+    projectDir: string;
+    credential: import("../token-store.ts").HostCredential | undefined;
+    tokenStore: import("../token-store.ts").TokenStore | undefined;
+    authorName: string | undefined;
+    authorEmail: string | undefined;
+    httpClient: typeof import("isomorphic-git/http/node").default | undefined;
+};
+/**
+ * Translate a SyncOutcome/PullOutcome into a RecoveryResult using the default
+ * map, letting per-status `overrides` win. Any status not present in the map
+ * (a future/unknown status) falls through to the `error` builder — override
+ * first, then default — matching each handler's original `default:` arm.
+ */
+export declare function mapOutcomeToResult(ctx: RecoveryContext, outcome: AnyOutcome, overrides?: OutcomeOverrides): RecoveryResult;

package/dist/lib/remote-auth/recovery/policy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Recovery policy matrix — pure data, no I/O.
+ *
+ * Each SyncErrorKind maps to a policy that controls:
+ *   - risk: how much irreversible change the repair makes
+ *   - createBackup: whether the repair MUST create a /tmp zip before running
+ *   - requireConfirmation: whether the user must approve the repair
+ *   - mayChangeLocalFiles: whether the repair can modify user-visible files
+ *   - mayChangeGitMetadata: whether the repair can modify .git/ metadata
+ *   - mayChangeRemote: whether the repair can push to the remote
+ *   - automate: whether the repair can run without user interaction at all
+ *
+ * Safety invariants (from the spec):
+ *   - detached_head, corrupt_index, missing_git_dir, missing_or_corrupt_objects,
+ *     unrelated_histories → always backup + confirm
+ *   - auth_required, network_unavailable, non_fast_forward → no backup needed,
+ *     no confirmation required (they are thin delegates to sync.ts)
+ *   - wrong_remote_or_branch → no repair attempted (pure block with guidance),
+ *     so no backup is needed either
+ */
+import type { RecoveryRisk, SyncErrorKind } from "./types.ts";
+export interface RecoveryPolicy {
+    risk: RecoveryRisk;
+    createBackup: boolean;
+    requireConfirmation: boolean;
+    mayChangeLocalFiles: boolean;
+    mayChangeGitMetadata: boolean;
+    mayChangeRemote: boolean;
+    /** True when the repair can run transparently without prompting the user. */
+    automate: boolean;
+    /**
+     * True when the dispatcher must run the handler inside withRepoLock (the
+     * per-repo FIFO queue): every handler that mutates `.git` via RAW git.* /
+     * node:fs calls. MUST be false for the thin sync.ts delegates — they call
+     * lock-wrapped functions (syncProject/pullChanges) internally, and the FIFO
+     * queue is non-reentrant (locking them at the dispatcher would deadlock).
+     */
+    serializeRepo: boolean;
+}
+export declare const recoveryPolicy: Record<SyncErrorKind, RecoveryPolicy>;
+/** Look up the policy for a kind (always succeeds — every kind has an entry). */
+export declare function policyFor(kind: SyncErrorKind): RecoveryPolicy;
+/**
+ * Refinement: detached HEAD with local changes is riskier — escalate to high
+ * risk and always require confirmation regardless of the base policy.
+ */
+export declare function detachedHeadWithLocalChangesPolicy(hasLocalChanges: boolean): RecoveryPolicy;

package/dist/lib/remote-auth/recovery/recover-auth.d.ts

@@ -0,0 +1,42 @@
+/**
+ * recover-auth.ts — Auth failure: clear the bad credential, ask the author
+ * to reconnect.
+ *
+ * WHY this module exists: when the remote rejects the saved connection
+ * (401 / 403), the right behavior is:
+ *
+ *   1. Attempt sync so the snapshot-first invariant (ADR 0006 D5) still runs
+ *      if possible — any unsaved local work gets committed before the network
+ *      call, so nothing is lost regardless of what the server says.
+ *   2. If the result is `auth`, delete the stale credential from the token
+ *      store so the next reconnect flow starts clean.
+ *   3. Return `needs_user` with plain-language reconnect guidance.
+ *      recommendedAction is always "Reconnect" — no git words, no tokens.
+ *   4. Never create a backup zip (policy.createBackup = false for auth_required
+ *      — there is nothing locally at risk; the author's work is already
+ *      committed by the snapshot-first step in sync.ts).
+ *   5. Never ask for confirmation (no repair changes anything).
+ *   6. Never force-push (syncProject / pushChanges never does this either).
+ *
+ * This is a THIN WRAPPER around syncProject from sync.ts. The snapshot step,
+ * the network call, and the "auth" classification all live there. The only
+ * delta this module adds is:
+ *   - Calling ctx.tokenStore.delete(host) when the outcome is `auth`.
+ *   - Translating SyncOutcome { status: "auth" } → RecoveryResult { status:
+ *     "needs_user" } with the auth_required ManualGuidance.
+ */
+import type { RecoveryContext, RecoveryResult } from "./types.ts";
+/**
+ * Handle an `auth_required` classification.
+ *
+ * - Delegates the sync attempt (including the snapshot-first step) to
+ *   `syncProject` from sync.ts.
+ * - On `auth` outcome: clears the bad credential from ctx.tokenStore (best-
+ *   effort — missing store is silently ignored) and returns `needs_user` with
+ *   author-friendly reconnect guidance.
+ * - On any successful outcome (the good-credential path): returns `recovered`
+ *   so the host can refresh. The credential is NOT cleared on success.
+ * - On other failure outcomes (offline, conflict, error): passes through an
+ *   appropriate RecoveryResult without touching the credential store.
+ */
+export declare function recover(ctx: RecoveryContext, _error?: unknown): Promise<RecoveryResult>;

package/dist/lib/remote-auth/recovery/recover-binary-conflict.d.ts

@@ -0,0 +1,37 @@
+/**
+ * recover-binary-conflict.ts — never auto-merge binary files.
+ *
+ * WHY this exists: binary files (images, PDFs, audio, etc.) cannot be
+ * line-merged. When both the local copy and the online copy changed the same
+ * binary file, the only honest answer is: show the user the list of clashing
+ * files and let them choose which version to keep. The "Keep both" option
+ * works for binary files too — it keeps the author's version alongside an
+ * "(online copy)" rename.
+ *
+ * This handler is intentionally identical in shape to recover-merge-conflict.ts.
+ * The distinction between text and binary conflicts is made at a higher level
+ * (classify.ts / the merge engine) — by the time recover() is called we already
+ * know the conflict involves binary content, so we surface it the same way:
+ * a 'needs_user' result with the conflicted file list.
+ *
+ * Reuses:
+ *   pullChanges  — snapshot → fetch → merge (abortOnConflict). On a binary
+ *                  file isomorphic-git still throws MergeConflictError with the
+ *                  conflicting filepath in data.filepaths.
+ *   makeManualGuidance — jargon-free copy for binary_conflict.
+ *
+ * Policy (policy.ts): createBackup=false, requireConfirmation=false.
+ *   The working tree is left completely untouched by pullChanges
+ *   (abortOnConflict), so no backup is needed to surface the conflict to the
+ *   user. The confirmation gate is the per-file UI chooser, not withBackupGate.
+ *
+ * Safety invariants (see test file):
+ *   - NO force-push: pullChanges never pushes; this handler never calls push.
+ *   - Remote HEAD is NEVER advanced: we stop at conflict, surface needs_user.
+ *   - Both blob versions are preserved in local history (pullChanges snapshots
+ *     the working tree before merge, then aborts — no side is silently dropped).
+ *   - write_conflict_snapshot fault hook is called and, if it throws, the error
+ *     is caught and a safe fallback is returned (no unhandled throw to caller).
+ */
+import type { RecoverFn } from "./types.ts";
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-corrupt-index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * recover-corrupt-index.ts — repair a corrupt or unreadable .git/index.
+ *
+ * WHY this is needed:
+ *   The git index (staging area) can become corrupt if gutterpress or the OS
+ *   crashes mid-operation. When the index is unreadable, virtually every
+ *   git operation fails — status checks, sync, everything. The fix is simple:
+ *   delete the bad index and let git rebuild it from the last saved snapshot.
+ *   User-visible content files are NEVER touched — uncommitted edits survive.
+ *
+ * Safety invariants:
+ *   - Backup created and verified BEFORE anything is deleted.
+ *   - User must confirm before the repair runs.
+ *   - If backup creation fails → failed_no_changes_made, no further writes.
+ *   - If removal or rebuild throws after backup → failed_backup_available.
+ *   - User DENY → blocked (index left exactly as-is).
+ *   - Never force-pushes; the repair is entirely local (no remote contact).
+ *   - Uncommitted edits in the working tree are NEVER overwritten or discarded.
+ *
+ * Repair steps (all inside withBackupGate's risky callback):
+ *   1. ctx.faults?.before("remove_index") — fault injection point
+ *   2. Delete .git/index
+ *   3. ctx.faults?.before("rebuild_index") — fault injection point
+ *   4. Walk HEAD's tree, call git.resetIndex({ filepath }) for each tracked file.
+ *      resetIndex ONLY updates the index metadata (mode/oid/stat) — it does NOT
+ *      write to the working-tree file, so uncommitted edits remain byte-for-byte.
+ *   5. Return status=recovered
+ */
+import type { RecoverFn, StillAppliesFn } from "./types.ts";
+/**
+ * Precondition probe (see types.ts `StillAppliesFn`): re-probe whether the
+ * index is still unreadable right before the dispatcher hands off to
+ * `recover` below. `git.listFiles` with no `ref` reads the current staging
+ * area directly from `.git/index` — the same file this handler deletes and
+ * rebuilds — so a successful read here means the corruption is already gone
+ * (e.g. a previous attempt already rebuilt it, or the author replaced the
+ * file externally) and there is nothing left to repair.
+ */
+export declare const stillApplies: StillAppliesFn;
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-detached-head.d.ts

@@ -0,0 +1,70 @@
+/**
+ * recover-detached-head.ts — recover from a detached HEAD state.
+ *
+ * WHY: When an author's version history ends up in "detached" mode, syncing
+ * fails completely. This happens when the working copy landed on a specific
+ * saved point rather than the live named copy of the work.
+ * The repair re-attaches the copy to the named working version.
+ *
+ * All cases use a unified path through withBackupGate so fault injection
+ * points are consistent and predictable:
+ *
+ *   Case A — clean working tree, current point IS reachable from the
+ *             configured version line:
+ *             Backup → create local rescue copy at current HEAD →
+ *             checkout named version → 'recovered'.
+ *
+ *   Case B — orphan saved point (NOT reachable from the named version line):
+ *             Same path as Case A; the rescue copy preserves the orphan.
+ *
+ *   Case C — uncommitted edits in the working tree:
+ *             Backup → stage + commit edits to rescue copy →
+ *             checkout named version → 'recovered'.
+ *             DENY → blocked, everything unchanged.
+ *
+ * Branch resolution (which named version to re-attach to): the detached commit
+ * usually belongs to the author's real working branch, which is NOT always
+ * "main" (it may be "master", "trunk", …). The handler DISCOVERS that branch
+ * (resolveTargetBranch) instead of assuming "main": an explicit ctx.branch
+ * wins; otherwise it prefers a sole local branch, then the unique local branch
+ * the detached commit belongs to, then the remote's default
+ * (refs/remotes/origin/HEAD), and only finally "main". Discovery never throws.
+ *
+ * The final checkout is FORCED. By that point the prior state is preserved both
+ * on the rescue branch and in the verified /tmp backup, so forcing cannot lose
+ * work — and it avoids a spurious CheckoutConflictError from an untracked /
+ * ignored / stat-dirty file colliding with the target version.
+ *
+ * Fault injection points (called via ctx.faults?.before()):
+ *   backup_create               — before the zip is written
+ *   backup_verify               — after the zip is written, before verifying
+ *   commit_recovery_snapshot    — before staging + committing local edits (Case C)
+ *   create_recovery_branch      — before writing the rescue branch ref
+ *   checkout_branch             — before the final checkout
+ *
+ * Safety invariants:
+ *   - NEVER force-push (push is never called; the rescue copy is local-only).
+ *   - /tmp zip backup created and verified BEFORE any branch/checkout op.
+ *   - backup_create fault → failed_no_changes_made, no writes after.
+ *   - mid-repair fault → failed_backup_available, backup readable, remote unchanged.
+ *   - confirmation DENIED → blocked, local + remote unchanged.
+ *
+ * Author-facing copy: no git words, no tokens, no internal paths in userSummary.
+ */
+import type { RecoveryContext, RecoveryResult, StillAppliesFn } from "./types.ts";
+/**
+ * Precondition probe (see types.ts `StillAppliesFn`): re-probe whether HEAD is
+ * still detached right before the dispatcher hands off to `recover` below.
+ * HEAD may have been re-attached externally (e.g. the author ran a checkout
+ * in a terminal) between classification and dispatch. A thrown
+ * `currentBranch` read (HEAD/ref store unreadable) is a DIFFERENT, worse
+ * condition than detachment — conservatively report "still applies" so that
+ * case surfaces through the normal repair path rather than being swallowed
+ * here as a false no-op.
+ */
+export declare const stillApplies: StillAppliesFn;
+/**
+ * Recover from a detached HEAD state.
+ * Implements the RecoverFn contract (types.ts).
+ */
+export declare function recover(ctx: RecoveryContext, _error?: unknown): Promise<RecoveryResult>;

package/dist/lib/remote-auth/recovery/recover-interrupted-cherry-pick.d.ts

@@ -0,0 +1,23 @@
+/**
+ * recover-interrupted-cherry-pick.ts — abort a cherry-pick left unfinished.
+ *
+ * WHY: A conflicted cherry-pick stops BEFORE committing, so — unlike a rebase —
+ * it does NOT advance HEAD. There is no branch ref to rewind: only the
+ * half-applied index/worktree conflict state and the `.git/CHERRY_PICK_HEAD`
+ * marker (plus MERGE_MSG / sequencer) to clear. For a non-technical author the
+ * safe move is to UNDO the unfinished update and return to the last working
+ * state — which is a force-checkout of the current branch + marker cleanup.
+ *
+ * The shared skeleton in abort-interrupted-operation.ts owns the backup gate,
+ * TOCTOU guard, hadLocalChanges capture, fault ordering, checkout, cleanup and
+ * re-verify; this module only supplies the cherry-pick-specific config (default
+ * branch resolution: ctx.branch → git.currentBranch → "HEAD", HEAD stays
+ * attached during a cherry-pick).
+ */
+import type { RecoverFn, StillAppliesFn } from "./types.ts";
+/**
+ * Precondition probe (see types.ts `StillAppliesFn`) — the dispatcher's
+ * replacement for the abort skeleton's old hand-rolled TOCTOU guard.
+ */
+export declare const stillApplies: StillAppliesFn;
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-interrupted-merge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * recover-interrupted-merge.ts — abort a merge left unfinished.
+ *
+ * WHY: gutterpress itself never leaves a merge half-done (isomorphic-git's merge
+ * either completes or aborts in memory and never writes MERGE_HEAD), so this
+ * state comes from OUTSIDE the app: the author ran `git merge`/`git pull` in a
+ * terminal, hit conflicts, and walked away. The repo then has
+ * `.git/MERGE_HEAD` plus conflict markers in tracked files, and every sync
+ * would otherwise snapshot those markers into history. For a non-technical
+ * author the safe move is to UNDO the unfinished merge and return to the last
+ * working state.
+ *
+ * A conflicted merge stops BEFORE committing, so — like a cherry-pick and
+ * unlike a rebase — HEAD stays attached and no branch ref moved. The abort is a
+ * force-checkout of the current branch (resets index + worktree to HEAD) plus
+ * removal of the merge marker files. The shared skeleton in
+ * abort-interrupted-operation.ts owns the backup gate, TOCTOU guard,
+ * hadLocalChanges capture, fault ordering, checkout, cleanup and re-verify; this
+ * module only supplies the merge-specific config (default branch resolution:
+ * ctx.branch → git.currentBranch → "HEAD").
+ */
+import type { RecoverFn, StillAppliesFn } from "./types.ts";
+/**
+ * Precondition probe (see types.ts `StillAppliesFn`) — the dispatcher's
+ * replacement for the abort skeleton's old hand-rolled TOCTOU guard.
+ */
+export declare const stillApplies: StillAppliesFn;
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-interrupted-rebase.d.ts

@@ -0,0 +1,39 @@
+/**
+ * recover-interrupted-rebase.ts — abort a rebase that was left unfinished.
+ *
+ * WHY: If gutterpress or the OS dies partway through combining versions, the repo
+ * can be left mid-rebase: `.git/rebase-merge/` (merge/interactive backend) or
+ * `.git/rebase-apply/` (am backend) exists and HEAD is usually detached at a
+ * replay commit. Every sync then fails. There is nothing to "finish" for a
+ * non-technical author — the only safe move is to UNDO the unfinished update and
+ * return the project to its last working state. That is exactly what an abort is.
+ *
+ * Unlike a merge/cherry-pick (which stop before committing and only need the
+ * current branch reset), a rebase advances HEAD, so the abort must rewind the
+ * real branch ref to the pre-rebase commit. The shared skeleton in
+ * abort-interrupted-operation.ts owns the backup gate, TOCTOU guard,
+ * hadLocalChanges capture, fault ordering, checkout, cleanup and re-verify; this
+ * module supplies the rebase-specific `resolveTarget` that:
+ *   1. Reads the pre-rebase commit from `<stateDir>/orig-head` (fallback:
+ *      `.git/ORIG_HEAD`). If it cannot be resolved → THROW (the backup gate
+ *      converts it to failed_backup_available; the backup is safe).
+ *   2. Resolves the branch from `<stateDir>/head-name` — but ONLY when it is a
+ *      genuine `refs/heads/<x>` path. A sentinel like "detached HEAD" (the
+ *      rebase started from a detached HEAD) is NOT a branch. Falls back to
+ *      ctx.branch only when head-name was ABSENT.
+ *   3a. Named branch → rewind the branch ref to the pre-rebase commit and
+ *       force-checkout it (re-attaches HEAD, resets tree + index to the tip).
+ *   3b. No branch (detached-HEAD rebase) → force-checkout the pre-rebase commit
+ *       directly, leaving HEAD detached at it; no branch ref is touched.
+ *
+ * resolveTarget reads state with DIRECT fs checks (not inspectRepo) — the one
+ * narrow fact it needs is which backend dir still exists, not a broad preflight
+ * probe that would re-enter the per-repo lock.
+ */
+import type { RecoverFn, StillAppliesFn } from "./types.ts";
+/**
+ * Precondition probe (see types.ts `StillAppliesFn`) — the dispatcher's
+ * replacement for the abort skeleton's old hand-rolled TOCTOU guard.
+ */
+export declare const stillApplies: StillAppliesFn;
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-merge-conflict.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Recovery handler for merge_conflict — thin wrapper over pullChanges.
+ *
+ * WHY a thin wrapper: merge_conflict is NOT a broken repo. The working tree is
+ * always left clean by pullChanges (abortOnConflict keeps the tree at the
+ * pre-merge snapshot). This handler's only job is to translate a
+ * `{ status: "conflict" }` PullOutcome into a `{ status: "needs_user" }`
+ * RecoveryResult so the host can show the per-file version chooser.
+ *
+ * No merge logic is re-implemented here. All the snapshot-first invariant,
+ * conflict detection, and two-parent merge machinery lives in sync.ts.
+ *
+ * SAFETY PROPERTIES (tested in recover-merge-conflict.test.ts):
+ *   1. Result is 'needs_user' with ConflictFile[] attached.
+ *   2. Working file NEVER contains '<<<<<<<' or '>>>>>>>' markers.
+ *   3. Remote HEAD + tree UNCHANGED after recover() returns.
+ *   4. User-visible local files preserved (snapshot kept both copies).
+ *   5. No force-push is attempted (policy mayChangeRemote=false).
+ *   6. Confirmation gate is NEVER called (requireConfirmation=false).
+ *   7. No backup zip created (createBackup=false — risk is "none").
+ *
+ * Policy: merge_conflict has risk="none", createBackup=false,
+ * requireConfirmation=false. The repair is fully safe and reversible via the
+ * snapshot pullChanges takes before attempting the merge.
+ */
+import type { RecoverFn } from "./types.ts";
+/**
+ * Translate a sync.ts PullOutcome into a RecoveryResult.
+ *
+ * - conflict  → needs_user (the intended outcome: surface the per-file chooser)
+ * - pulled / up-to-date → recovered (the pull succeeded; no conflict after all)
+ * - auth / offline / error → needs_user with guidance (pass the guidance through)
+ */
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-missing-git-dir.d.ts

@@ -0,0 +1,37 @@
+/**
+ * recover-missing-git-dir.ts — reclone-and-reattach when .git/ is missing.
+ *
+ * WHY this is needed:
+ *   A project folder can lose its .git/ directory if the user copied the
+ *   project from a zip archive that stripped hidden directories, or if .git/
+ *   was accidentally deleted. Without .git/, no sync operation can run.
+ *
+ * What this repair does:
+ *   1. Creates a /tmp backup of the current folder (user files preserved).
+ *   2. Asks the user to confirm the repair.
+ *   3. Clones the remote into a TEMP directory (NEVER into the project dir).
+ *   4. Copies only the .git/ metadata from the temp clone into the project dir.
+ *   5. Cleans up the temp clone directory.
+ *   6. Returns status=recovered with user files intact and .git/ restored.
+ *
+ * Safety invariants:
+ *   - The project folder is NEVER deleted or replaced.
+ *   - The clone target is always a separate temp dir, never projectDir.
+ *   - User content files (outside .git/) are NEVER overwritten.
+ *   - No force-push is ever issued.
+ *   - Backup created and verified BEFORE any repair runs.
+ *   - Backup failure → failed_no_changes_made, no further writes.
+ *   - User DENY → blocked, no changes.
+ *   - Mid-repair failure → failed_backup_available, backup readable, remote unchanged.
+ *   - No remoteUrl → blocked with guidance (reclone is impossible).
+ */
+import type { RecoverFn, StillAppliesFn } from "./types.ts";
+/**
+ * Precondition probe (see types.ts `StillAppliesFn`): `.git/` may have
+ * reappeared between classification and dispatch (e.g. the author restored
+ * the folder or ran an init in a terminal). The dispatcher calls this INSIDE
+ * withRepoLock, immediately before invoking `recover` below, replacing what
+ * used to be a hand-rolled upfront check duplicated here.
+ */
+export declare const stillApplies: StillAppliesFn;
+export declare const recover: RecoverFn;

package/dist/lib/remote-auth/recovery/recover-missing-objects.d.ts

@@ -0,0 +1,56 @@
+/**
+ * recover-missing-objects.ts — safe fetch attempt for missing/corrupt loose objects.
+ *
+ * WHY this exists:
+ *   When isomorphic-git raises a "ReadObjectFail" or similar "missing/corrupt
+ *   object" error, the repo's on-disk object store has gaps. The safest repair
+ *   is a fetch from the remote: git.fetch() downloads only the objects the
+ *   remote has that the local repo is missing. If the remote can fill the gap,
+ *   the repo becomes healthy again. If there is no remote, or the fetch cannot
+ *   cover the damage, we stop with guidance and a backup.
+ *
+ * IMPORTANT — why we must verify after fetching:
+ *   git.fetch() downloads MISSING objects into the pack store. However, it
+ *   NEVER overwrites an already-existing (corrupt) loose object file on disk.
+ *   Git's loose-object format uses a content-hash filename; if the file at
+ *   .git/objects/xx/yyyy... already exists (even if corrupted), git skips it.
+ *   So a corrupt loose object that the remote also has will remain corrupt on
+ *   disk after a successful fetch() call. We MUST verify that the object store
+ *   is healthy after the fetch — if any read still fails, the repair did not
+ *   work and we stop with needs_user guidance instead of a false 'recovered'.
+ *
+ * Safety invariants (every test asserts these):
+ *   I1. We NEVER push — not even a no-op push. Remote history is read-only here.
+ *   I2. No force-push (we never call git.push at all).
+ *   I3. Remote HEAD and tree are unchanged after this handler runs.
+ *   I4. User-visible content files are preserved at all times.
+ *   I5. A backup zip is created and verified BEFORE any repair attempt.
+ *   I6. If backup creation fails → failed_no_changes_made; no further writes.
+ *   I7. If the fetch throws AFTER backup → failed_backup_available; zip readable.
+ *   I8. If the user denies the confirmation dialog → blocked, no-op.
+ *   I9. All non-recovered results include ManualGuidance with jargon-free copy.
+ *
+ * Repair flow (inside withBackupGate's risky callback):
+ *   1. If no remote URL is configured → stop with needs_user guidance.
+ *   2. ctx.faults?.before("fetch") — fault injection point for tests.
+ *   3. git.fetch() from the remote (no push, read-only, tags=false).
+ *   4. Verify the repair: resolve HEAD + read commit + read tree. If any read
+ *      fails, the corrupt object is still on disk → needs_user guidance.
+ *   5. If verification succeeds → recovered with the backup path.
+ *   6. If fetch throws → withBackupGate catches it → failed_backup_available.
+ *
+ * No merge logic, no push logic. All structural guard-rails live in
+ * withBackupGate (backup → confirm → risky → failsafe on throw).
+ */
+import type { RecoverFn, StillAppliesFn } from "./types.ts";
+/**
+ * Precondition probe (see types.ts `StillAppliesFn`): re-probe object-store
+ * readability right before the dispatcher hands off to `recover` below,
+ * reusing the SAME verifyRepoReadable check the handler itself uses to
+ * confirm a fetch actually repaired the store (inspect.ts) — one
+ * implementation, not a second copy that could drift. A successful read means
+ * the damage is already gone (e.g. a previous fetch attempt already fixed
+ * it), so there is nothing left to repair.
+ */
+export declare const stillApplies: StillAppliesFn;
+export declare const recover: RecoverFn;