Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

123 KB
Raw Blame
import { execFile } from 'node:child_process';
import {
  type Dirent,
  existsSync,
  readdirSync,
  readFileSync,
  unlinkSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join, relative, resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { promisify } from 'node:util';
import {
  OK_DIR,
  type PullOutcome,
  pathspecArgs,
  REFUSED_SYMLINK_PATHS_CAP,
  SYNC_PAUSED_REASONS,
  type SyncMode,
  type SyncModeChangeSource,
  type SyncPausedReason,
  tryLineLevelCombine,
} from '@inkeep/open-knowledge-core';
import { inspectGitRepository } from '@inkeep/open-knowledge-core/git-repository';
import { resolveConfigPath } from '@inkeep/open-knowledge-core/server';
import { resolveGitDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';
import type { CC1Broadcaster } from './cc1-broadcast.ts';
import { getLocalDir } from './config/paths.ts';
import type { ConflictAuthority, RaiseInput } from './conflict-authority.ts';
import type { Conflict } from './conflict-kinds.ts';
import { holdsMarkersOnDisk } from './conflict-kinds.ts';
import type { ContentFilter } from './content-filter.ts';
import { isShareableOkArtifact } from './content-filter.ts';
import { isSupportedDocFile } from './doc-extensions.ts';
import {
  type ClassifiedError,
  classifyGitError,
  type UserFacingErrorCode,
} from './error-classification.ts';
import { tracedRenameSync, tracedUnlinkSync, tracedWriteFileSync } from './fs-traced.ts';
import { createGhTokenSource, type GhTokenSource } from './gh-token-source.ts';
import {
  applyGitEnv,
  createGitInstance,
  type GitHandle,
  type RelayGhToken,
  withParentLock,
} from './git-handle.ts';
import { resolveGitIdentity } from './git-identity.ts';
import {
  listNameStatus,
  listNames,
  listPorcelainEntries,
  PORCELAIN_STATUS_ARGS,
  type PorcelainEntry,
} from './git-paths.ts';
import {
  type CheckPushPermissionOptions,
  type DetectGhAccountsFn,
  type DetectGhFn,
  checkPushPermission as defaultCheckPushPermission,
  type ProbeTokenStore,
  type PushPermission,
} from './github-permissions.ts';
import {
  assertIncomingSymlinksSafe,
  assertMergeNameResolvesTo,
  IncomingRefMovedError,
  IncomingRefShadowedError,
  resolveIncomingCommit,
  UnsafeIncomingSymlinkError,
} from './incoming-symlink-guard.ts';
import { getLogger } from './logger.ts';
import {
  applyManagedMcpEntry,
  getMcpUnownedShell,
  type NativeTomlMcpEditor,
  reconcileTrackedMcpConfig,
  TRACKED_MCP_CONFIG_TARGETS,
} from './mcp-config-reconciler.ts';
import { toPosix } from './path-utils.ts';
import {
  readDeclaredGitHubHosts,
  readOriginGitHubRepo,
  readSyncRemoteInfo,
  type SyncRemoteInfo,
  sameGitHubLogin,
} from './share/git-context.ts';
import {
  type CachedGitHubAccountResolver,
  type CredentialUrlMatchReader,
  createCachedGitHubAccountResolver,
  type GitHubAccount,
} from './share/github-account.ts';
import { assertRealpathWithinDir } from './symlink-guard.ts';
import { computeRemainingMs } from './sync-timing.ts';

const log = getLogger('sync-engine');
const TRACKED_MCP_CONFIG_TARGET_SET: ReadonlySet<string> = new Set(TRACKED_MCP_CONFIG_TARGETS);

const SHA_HEX_40 = /^[0-9a-f]{40}$/i;

const execFileAsync = promisify(execFile);

class GitOperationInProgressError extends Error {
  constructor() {
    super('Sync paused while a Git operation is in progress or the index has unresolved conflicts');
    this.name = 'GitOperationInProgressError';
  }
}

class ShareableOkEnumerationError extends Error {
  constructor(relDir: string, cause: unknown) {
    super(`Shareable .ok subtree "${relDir}" could not be fully enumerated; sync staging aborted`, {
      cause,
    });
    this.name = 'ShareableOkEnumerationError';
  }
}

export type FastForwardRefusal = 'overlay-overlap' | 'divergence' | 'unknown';

export function classifyFastForwardRefusal(input: {
  exitCode?: number | null;
  stderr: string;
}): FastForwardRefusal {
  const { exitCode, stderr } = input;
  const s = stderr ?? '';
  if (exitCode === 128 || (/^fatal:/m.test(s) && /not possible to fast-forward/i.test(s))) {
    return 'divergence';
  }
  if (/^error:/m.test(s) && /would be overwritten by merge/i.test(s)) {
    return 'overlay-overlap';
  }
  return 'unknown';
}

export type SyncState =
  | 'dormant'
  | 'idle'
  | 'fetching'
  | 'pulling'
  | 'pushing'
  | 'conflict'
  | 'offline'
  | 'auth-error'
  | 'disabled';

export type PushPermissionStatus =
  | { checkStatus: 'allowed' }
  | ({
      checkStatus: 'denied';
      deniedReason: Extract<PushPermission, { kind: 'denied' }>['reason'];
    } & Pick<
      Extract<PushPermission, { kind: 'denied' }>,
      'resolvedLogin' | 'declaredLogin' | 'declaredSource'
    >)
  | {
      checkStatus: 'unknown';
      unknownError?: Extract<PushPermission, { kind: 'unknown' }>['error'];
    };

function pushPermissionStatusFrom(p: PushPermission): PushPermissionStatus {
  if (p.kind === 'allowed') return { checkStatus: 'allowed' };
  if (p.kind === 'denied') {
    return {
      checkStatus: 'denied',
      deniedReason: p.reason,
      ...(p.resolvedLogin !== undefined ? { resolvedLogin: p.resolvedLogin } : {}),
      ...(p.declaredLogin !== undefined ? { declaredLogin: p.declaredLogin } : {}),
      ...(p.declaredSource !== undefined ? { declaredSource: p.declaredSource } : {}),
    };
  }
  return { checkStatus: 'unknown', unknownError: p.error };
}

function pushPermissionStatusEqual(
  a: PushPermissionStatus | null,
  b: PushPermissionStatus | null,
): boolean {
  if (a === b) return true;
  if (a === null || b === null) return false;
  if (a.checkStatus !== b.checkStatus) return false;
  if (a.checkStatus === 'denied' && b.checkStatus === 'denied') {
    return (
      a.deniedReason === b.deniedReason &&
      a.resolvedLogin === b.resolvedLogin &&
      a.declaredLogin === b.declaredLogin &&
      a.declaredSource === b.declaredSource
    );
  }
  if (a.checkStatus === 'unknown' && b.checkStatus === 'unknown') {
    return a.unknownError === b.unknownError;
  }
  return true;
}

interface SyncStatus {
  state: SyncState;
  lastSyncUtc: string | null;
  lastRunUtc: string | null;
  lastPullOkUtc: string | null;
  lastPushOkUtc: string | null;
  lastFetchUtc: string | null;
  lastPushedSha: string | null;
  lastPullUtc: string | null;
  lastPullOutcome: PullOutcome | null;
  ahead: number;
  behind: number;
  consecutiveFailures: number;
  consecutivePushFailures: number;
  conflictCount: number;
  hasRemote: boolean;
  syncEnabled: boolean;
  syncMode: SyncMode;
  identityUnresolved: boolean;
  remote: SyncRemoteInfo | null;
  pushError?: string;
  pushErrorCode?: UserFacingErrorCode;
  pullError?: string;
  pullErrorCode?: UserFacingErrorCode;
  pausedReason?: SyncPausedReason;
  pushPermission?: PushPermissionStatus;
}

interface ContentFileEntry {
  contentRelPath: string;
  projectRelPath: string;
}

interface PreparedMcpReconciliation {
  path: string;
  raw: string;
  winnerEntry: Record<string, unknown>;
}

interface MergePreparation {
  proceed: boolean;
  needsStashPop: boolean;
  reconciled: PreparedMcpReconciliation[];
}

/**
 * ContentFilter read-opts for the two staging-path consultations, admitting the shareable `.ok`
 * artifact allow-list. Both must consult the identical predicate (precedent #55): a HEAD path the
 * listing admits but the gather walk refuses commits as a spurious deletion on every push.
 */
const CONTENT_SYNC_STAGING_SCOPE = { syncScope: { pathBase: 'content' } } as const;
const PROJECT_SYNC_STAGING_SCOPE = { syncScope: { pathBase: 'project' } } as const;
type SyncStagingScope = typeof CONTENT_SYNC_STAGING_SCOPE | typeof PROJECT_SYNC_STAGING_SCOPE;

type PullInvocation = 'explicit' | 'sync';

const BLOCKING_PATHS_CAP = 50;
const LOGGED_PATHS_CAP = 20;
const PROMISED_PATHS_CAP = 100;
const INDEX_LOCK_PATH_IN_STDERR = /(^|[/\\])index\.lock\b/i;
const INDEX_RESET_RETRY_DELAY_SECONDS = 0.05;

type SyncCycleOp = 'push' | 'pull';
type IndexResetOp = SyncCycleOp | 'mcp-reconcile';

const SYNC_PAUSED_REASON_VALUES = new Set<string>(SYNC_PAUSED_REASONS);

function isSyncPausedReason(value: string): value is SyncPausedReason {
  return SYNC_PAUSED_REASON_VALUES.has(value);
}

const ONE_SHOT_PAUSES: ReadonlySet<SyncPausedReason | undefined> = new Set<SyncPausedReason>([
  'diverged-local-commits',
  'external-changes-pending',
  'git-index-locked',
  'git-operation-in-progress',
  'no-commits-yet',
  'unsafe-incoming-symlinks',
]);

const NON_PERSISTED_PAUSE_LIST = [
  'no-push-permission',
  'auth-error',
  'git-index-locked',
  'git-operation-in-progress',
  'no-commits-yet',
  'unsafe-incoming-symlinks',
] as const satisfies readonly SyncPausedReason[];

const NON_PERSISTED_PAUSES: ReadonlySet<SyncPausedReason | undefined> = new Set<SyncPausedReason>(
  NON_PERSISTED_PAUSE_LIST,
);

const NON_RESTORED_PAUSES: ReadonlySet<SyncPausedReason | undefined> = new Set<SyncPausedReason>([
  ...NON_PERSISTED_PAUSE_LIST,
  'external-changes-pending',
]);

const COMMIT_BLOCKING_MESSAGE = 'Commit local changes before syncing';

interface PersistedSyncState {
  version: 1;
  lastSyncUtc: string | null;
  lastPullOkUtc?: string | null;
  lastPushOkUtc?: string | null;
  lastFetchUtc: string | null;
  lastPushedSha: string | null;
  consecutiveFailures: number;
  consecutivePushFailures?: number;
  pushStreakIsConnectivity?: boolean;
  pausedReason?: string;
  pausedSinceUtc?: string;
}

interface SyncEngineOptions {
  declaredGitHubHosts?: ReadonlySet<string>;
  projectDir: string;
  contentDir: string;
  contentFilter: ContentFilter;
  contentRoot?: string;
  pullIntervalSeconds?: number;
  pushIntervalSeconds?: number;
  mode?: SyncMode;
  syncEnabled?: boolean;
  credentialConfig?: string[];
  resolveCredentialConfig?: () => Promise<string[]>;
  cc1Broadcaster?: Pick<CC1Broadcaster, 'signal'> | null;
  conflicts: ConflictAuthority;
  onStateChange?: (state: SyncState) => void;
  setBatchInProgress?: (value: boolean) => void;
  onAutoDisable?: (reason: 'protected-branch') => void | Promise<void>;
  checkpointBeforeStrandedConversion?: (context: {
    branch: string;
    ahead: number;
  }) => void | Promise<void>;
  checkpointBeforeOverlayRestore?: (context: {
    branch: string;
    paths: number;
  }) => void | Promise<void>;
  mcpTomlEditor?: NativeTomlMcpEditor;
  detectGh?: DetectGhFn;
  detectGhAccounts?: DetectGhAccountsFn;
  _readCredentialUrlMatch?: CredentialUrlMatchReader;
  _beforeRealIndexResetRetry?: () => void | Promise<void>;
  tokenStore?: ProbeTokenStore | null;
  checkPushPermissionFn?: (opts: CheckPushPermissionOptions) => Promise<PushPermission>;
}

function jitteredMs(seconds: number): number {
  const base = seconds * 1000;
  const jitter = base * 0.15 * (2 * Math.random() - 1);
  return Math.round(base + jitter);
}

function sleepMs(ms: number): Promise<void> {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

function isUnbornHead(projectDir: string): boolean {
  const inspected = inspectGitRepository(projectDir);
  if (inspected.kind !== 'repository') return false;
  const head = inspected.repository.readHead();
  if (head.kind !== 'branch') return false;
  return inspected.repository.readRef(head.ref).kind === 'absent';
}

export const CONTENTION_WARN_THRESHOLD = 3;

export function isFetchDisprovableFailure(
  classified: Pick<ClassifiedError, 'class' | 'subclass'>,
): boolean {
  return (
    classified.class === 'network' && classified.subclass !== '429' && classified.subclass !== '5xx'
  );
}

function backoffMs(consecutiveFailures: number): number {
  if (consecutiveFailures >= 8) return 60 * 60 * 1000;
  if (consecutiveFailures >= 5) return 15 * 60 * 1000;
  if (consecutiveFailures >= 3) return 5 * 60 * 1000;
  return 0;
}

const FF_ONLY_TIMEOUT_MS = 120_000;

const GIT_BLOCK_TIMEOUT_MS = 120_000;

export class SyncEngine {
  private readonly declaredGitHubHosts: ReadonlySet<string>;
  private state: SyncState = 'dormant';
  private projectDir: string;
  private contentDir: string;
  private contentFilter: ContentFilter;
  private contentRoot: string;
  /**
   * The push cycle then runs a second enumeration rooted at the project root so shareable `.ok`
   * artifacts still stage and deletion-track; gather and head listing consult this flag in
   * lock-step (precedent #55).
   */
  private rootOkOutsideContentWalk: boolean;
  private pullIntervalSeconds: number;
  private pushIntervalSeconds: number;
  private mode: SyncMode;
  private credentialConfig: string[];
  private readonly resolveCredentialConfig: (() => Promise<string[]>) | undefined;
  private cc1Broadcaster: Pick<CC1Broadcaster, 'signal'> | null;
  private onStateChange: ((state: SyncState) => void) | undefined;
  private setBatchInProgress: ((value: boolean) => void) | undefined;
  private onAutoDisable: ((reason: 'protected-branch') => void | Promise<void>) | undefined;
  private checkpointBeforeStrandedConversion:
    | ((context: { branch: string; ahead: number }) => void | Promise<void>)
    | undefined;
  private checkpointBeforeOverlayRestore:
    | ((context: { branch: string; paths: number }) => void | Promise<void>)
    | undefined;
  private beforeRealIndexResetRetry: (() => void | Promise<void>) | undefined;
  private mcpTomlEditor: NativeTomlMcpEditor | undefined;
  private detectGh: DetectGhFn | undefined;

  private detectGhAccounts: DetectGhAccountsFn | undefined;
  private ghTokenSource: GhTokenSource;
  private ghAccountResolver: CachedGitHubAccountResolver;
  private declaredAccountWarnKey: string | undefined;
  private tokenStore: ProbeTokenStore | null | undefined;
  private checkPushPermissionFn: (opts: CheckPushPermissionOptions) => Promise<PushPermission>;
  private pushPermission: PushPermissionStatus | null = null;
  private pushPermissionProbeInFlight = false;

  private pullTimer: ReturnType<typeof setTimeout> | null = null;
  private pushTimer: ReturnType<typeof setTimeout> | null = null;
  private stateSaveTimer: ReturnType<typeof setTimeout> | null = null;

  private lastSyncUtc: string | null = null;
  private get lastRunUtc(): string | null {
    if (this.lastPullOkUtc === null) return this.lastPushOkUtc;
    if (this.lastPushOkUtc === null) return this.lastPullOkUtc;
    return this.lastPullOkUtc > this.lastPushOkUtc ? this.lastPullOkUtc : this.lastPushOkUtc;
  }
  private lastPullOkUtc: string | null = null;
  private lastPushOkUtc: string | null = null;
  private pushCycleLanded = false;
  private fetchOnlyInFlight = false;
  private lastFetchUtc: string | null = null;
  private lastPushedSha: string | null = null;
  private lastPullUtc: string | null = null;
  private lastPullOutcome: PullOutcome | null = null;
  private consecutivePullFailures = 0;
  private consecutivePushFailures = 0;
  private pushStreakIsConnectivity = false;
  private consecutiveContentions = 0;
  private ahead = 0;
  private behind = 0;
  private get conflictCount(): number {
    let total = 0;
    for (const entry of this.conflicts.list()) {
      if (holdsMarkersOnDisk(entry)) total++;
    }
    return total;
  }
  private pushError: string | undefined;
  private pushErrorCode: UserFacingErrorCode | undefined;
  private pullError: string | undefined;
  private pullErrorCode: UserFacingErrorCode | undefined;
  private pausedReason: SyncPausedReason | undefined;
  private indexLockHitThisCycle = false;
  private lastLockNoticeKind: 'index-locked' | 'git-lock-held' | undefined;
  private restingIndexLockPause: SyncPausedReason | undefined;
  private blockingPaths: string[] = [];
  private loggedSymlinkRefusal: string | undefined;
  private refusedSymlinkPaths: string[] = [];
  private currentBranch = 'main';

  private cycleInFlight: 'pull' | 'push' | null = null;

  private hasRemote = false;

  private identityUnresolved = false;

  private statePath: string;
  private readonly conflicts: ConflictAuthority;
  private unsubscribeConflicts: (() => void) | null = null;

  constructor(options: SyncEngineOptions) {
    this.projectDir = options.projectDir;
    this.declaredGitHubHosts = options.declaredGitHubHosts ?? readDeclaredGitHubHosts();
    this.contentDir = options.contentDir;
    this.contentFilter = options.contentFilter;
    this.contentRoot = options.contentRoot ?? '';
    this.rootOkOutsideContentWalk = toPosix(
      relative(this.contentDir, join(this.projectDir, OK_DIR)),
    ).startsWith('..');
    this.pullIntervalSeconds = options.pullIntervalSeconds ?? 30;
    this.pushIntervalSeconds = options.pushIntervalSeconds ?? 60;
    this.mode = options.mode ?? (options.syncEnabled === true ? 'full' : 'off');
    this.credentialConfig = options.credentialConfig ?? [];
    this.resolveCredentialConfig = options.resolveCredentialConfig;
    this.cc1Broadcaster = options.cc1Broadcaster ?? null;
    this.onStateChange = options.onStateChange;
    this.setBatchInProgress = options.setBatchInProgress;
    this.onAutoDisable = options.onAutoDisable;
    this.checkpointBeforeStrandedConversion = options.checkpointBeforeStrandedConversion;
    this.checkpointBeforeOverlayRestore = options.checkpointBeforeOverlayRestore;
    this.beforeRealIndexResetRetry = options._beforeRealIndexResetRetry;
    this.mcpTomlEditor = options.mcpTomlEditor;
    this.detectGh = options.detectGh;
    this.detectGhAccounts = options.detectGhAccounts;
    this.ghTokenSource = createGhTokenSource(options.detectGh);
    this.ghAccountResolver = createCachedGitHubAccountResolver({
      _readCredentialUrlMatch: options._readCredentialUrlMatch,
    });
    this.tokenStore = options.tokenStore;
    this.checkPushPermissionFn = options.checkPushPermissionFn ?? defaultCheckPushPermission;
    this.statePath = resolve(getLocalDir(this.projectDir), 'sync-state.json');
    this.conflicts = options.conflicts;
  }

  private syncGhTarget(): { account: GitHubAccount; host: string } {
    const account = this.ghAccountResolver.resolve(this.projectDir);
    return { account, host: account.host ?? 'github.com' };
  }

  private resolveRelayGhToken(): RelayGhToken | null {
    const { account, host } = this.syncGhTarget();
    const relay = this.ghTokenSource.get(host, account.login);
    this.noteDeclaredAccountOutcome(account, host, relay);
    return relay;
  }

  private noteDeclaredAccountOutcome(
    account: GitHubAccount,
    host: string,
    relay: RelayGhToken | null,
  ): void {
    const declared = account.login;
    const resolvedLogin = relay === null ? undefined : (relay.login ?? this.activeGhLogin(host));
    const missed =
      declared !== undefined && (relay === null || !sameGitHubLogin(resolvedLogin, declared));
    if (!missed) {
      this.declaredAccountWarnKey = undefined;
      return;
    }
    const key = `${host}\0${declared}\0${account.source}\0${relay === null ? 'none' : 'fallback'}`;
    if (key !== this.declaredAccountWarnKey) {
      if (relay === null) {
        log.warn(
          { host, declaredLogin: declared, declaredSource: account.source },
          '[sync] declared GitHub account produced no gh token — git runs with no relayed credential',
        );
      } else {
        log.warn(
          {
            host,
            declaredLogin: declared,
            declaredSource: account.source,
            resolvedLogin,
          },
          '[sync] declared GitHub account did not produce the gh token — using the active account',
        );
      }
    }
    this.declaredAccountWarnKey = key;
  }

  private parkedOnAmbiguousNotFound(): boolean {
    return (
      (this.state === 'auth-error' || this.pausedReason === 'auth-error') &&
      (this.pushErrorCode === 'auth-not-found-as-identity' ||
        this.pullErrorCode === 'auth-not-found-as-identity')
    );
  }

  private activeGhLogin(host: string): string | undefined {
    if (!this.detectGhAccounts) return undefined;
    try {
      return this.detectGhAccounts(host)?.find((a) => a.active)?.login;
    } catch (err) {
      log.warn({ err, host }, '[sync] detectGhAccounts failed — fallback identity stays unnamed');
      return undefined;
    }
  }

  private gitHandle(gitIndexFile?: string): GitHandle {
    return createGitInstance(this.projectDir, {
      credentialConfig: this.credentialConfig,
      gitIndexFile,
      ghToken: this.resolveRelayGhToken() ?? undefined,
      timeoutMs: GIT_BLOCK_TIMEOUT_MS,
    });
  }

  async start(): Promise<void> {
    if (this.state !== 'dormant') return;

    this.loadState();

    let hasRemote = false;
    try {
      const handle = this.gitHandle();
      const remoteOutput = await handle.git.raw('remote', '-v');
      hasRemote = remoteOutput.trim().length > 0;
      this.hasRemote = hasRemote;

      try {
        const b = (await handle.git.raw('rev-parse', '--abbrev-ref', 'HEAD')).trim();
        if (b && b !== 'HEAD') {
          this.currentBranch = b;
          this.conflicts.setBranch(b);
        }
      } catch {}
    } catch (e) {
      log.warn({ err: e }, '[sync] remote detection failed');
    }

    if (hasRemote) {
      void this.probePushPermissionInternal('start');
    }

    if (this.mode === 'off') {
      if (hasRemote) this.transitionTo('disabled');
      log.info({ hasRemote, mode: this.mode }, '[sync] sync not enabled — staying inactive');
      return;
    }

    if (!hasRemote) {
      log.info({}, '[sync] no remote detected — staying dormant');
      return;
    }

    this.transitionTo('idle');

    const gitDir = resolveGitDir(this.projectDir);
    const mergeHeadPath = gitDir ? join(gitDir, 'MERGE_HEAD') : null;
    const mergeInProgress = mergeHeadPath !== null && existsSync(mergeHeadPath);

    await this.conflicts.pruneMergeNativeAgainstGit();
    const hasMergeNative = (): boolean =>
      this.conflicts.list().some((e) => e.kind === 'merge-native');

    if (mergeInProgress && !hasMergeNative()) {
      log.warn({}, '[sync] stale MERGE_HEAD detected with no tracked conflicts — aborting merge');
      try {
        const handle = this.gitHandle();
        await handle.git.raw(['merge', '--abort']);
      } catch (e) {
        log.warn({ err: e }, '[sync] git merge --abort for stale MERGE_HEAD failed');
      }
    }

    this.subscribeToConflicts();

    if (hasMergeNative()) {
      this.transitionTo('conflict');
      log.warn(
        { count: this.conflictCount },
        '[sync] restarted with active conflicts — sync paused',
      );
      return;
    }

    const pullRemainingMs = computeRemainingMs(this.lastFetchUtc, this.pullIntervalSeconds);
    const pushRemainingMs = computeRemainingMs(this.lastPushOkUtc, this.pushIntervalSeconds);
    this.schedulePull(pullRemainingMs > 0 ? pullRemainingMs : undefined);
    this.schedulePush(pushRemainingMs > 0 ? pushRemainingMs : undefined);
    log.info(
      { branch: this.currentBranch, pullDelayMs: pullRemainingMs, pushDelayMs: pushRemainingMs },
      '[sync] started',
    );
  }

  stop(): void {
    this.unsubscribeConflicts?.();
    this.unsubscribeConflicts = null;
    if (this.pullTimer !== null) {
      clearTimeout(this.pullTimer);
      this.pullTimer = null;
    }
    if (this.pushTimer !== null) {
      clearTimeout(this.pushTimer);
      this.pushTimer = null;
    }
    if (this.stateSaveTimer !== null) {
      clearTimeout(this.stateSaveTimer);
      this.stateSaveTimer = null;
    }
    if (this.state !== 'dormant') {
      this.transitionTo('dormant');
    }
  }

  async destroy(): Promise<void> {
    this.stop();
    this.saveStateNow();
  }

  setIntervals(pullIntervalSeconds: number, pushIntervalSeconds: number): void {
    const pullChanged = this.pullIntervalSeconds !== pullIntervalSeconds;
    const pushChanged = this.pushIntervalSeconds !== pushIntervalSeconds;
    if (!pullChanged && !pushChanged) return;
    log.info(
      {
        pullFrom: this.pullIntervalSeconds,
        pullTo: pullIntervalSeconds,
        pushFrom: this.pushIntervalSeconds,
        pushTo: pushIntervalSeconds,
      },
      '[sync] cycle intervals changed',
    );
    this.pullIntervalSeconds = pullIntervalSeconds;
    this.pushIntervalSeconds = pushIntervalSeconds;
    if (pullChanged && this.pullTimer !== null) this.schedulePull();
    if (pushChanged && this.pushTimer !== null) this.schedulePush();
  }

  async setMode(mode: SyncMode, source: SyncModeChangeSource = 'config'): Promise<void> {
    if (this.mode === mode) return;
    const from = this.mode;
    this.mode = mode;
    log.info({ from, to: mode, source }, '[sync] mode changed');

    if (mode === 'off') {
      this.cancelScheduledCycles();
      await this.drainInFlightCycles();
      this.pausedReason = undefined;
      this.clearPushError();
      this.clearPullError();
      this.transitionTo(this.hasRemote ? 'disabled' : 'dormant');
      this.saveStateNow();
      return;
    }

    this.hasRemote = await this.probeRemote();

    this.pausedReason = undefined;
    this.clearPushError();
    this.clearPullError();
    this.consecutivePullFailures = 0;
    this.consecutivePushFailures = 0;
    this.pushStreakIsConnectivity = false;

    if (!this.hasRemote) {
      this.transitionTo('dormant');
      this.saveStateNow();
      return;
    }

    if (mode === 'follow') {
      await this.drainInFlightCycles();
      this.cancelScheduledCycles();
      await this.convertStrandedCommitsToOverlay();
    }

    this.transitionTo('idle');
    this.schedulePull(0);
    this.schedulePush(0);
    this.saveStateNow();
    void this.probePushPermissionInternal('refresh');
  }

  async setEnabled(enabled: boolean): Promise<void> {
    await this.setMode(enabled ? 'full' : 'off');
  }

  private cancelScheduledCycles(): void {
    if (this.pullTimer !== null) {
      clearTimeout(this.pullTimer);
      this.pullTimer = null;
    }
    if (this.pushTimer !== null) {
      clearTimeout(this.pushTimer);
      this.pushTimer = null;
    }
  }

  private async drainInFlightCycles(): Promise<void> {
    const DRAIN_TIMEOUT_MS = 30_000;
    const drainStartMs = Date.now();
    while (this.cycleInFlight !== null) {
      if (Date.now() - drainStartMs > DRAIN_TIMEOUT_MS) {
        log.warn(
          { cycleInFlight: this.cycleInFlight },
          '[sync] drain: timed out waiting for in-flight cycle',
        );
        break;
      }
      await wait(50);
    }
  }

  async probeUnpushedCommitCount(): Promise<number> {
    if (!this.hasRemote || isUnbornHead(this.projectDir)) return 0;
    return this.unpushedCommitCount(this.gitHandle());
  }

  private async unpushedCommitCount(handle: GitHandle): Promise<number> {
    try {
      const status = await handle.git.status();
      if (status.tracking) return status.ahead;
    } catch {}
    try {
      const out = (
        await handle.git.raw(['rev-list', '--count', `origin/${this.currentBranch}..HEAD`])
      ).trim();
      const n = Number.parseInt(out, 10);
      return Number.isFinite(n) ? n : 0;
    } catch {
      return 0;
    }
  }

  private async convertStrandedCommitsToOverlay(): Promise<void> {
    if (!this.hasRemote || isUnbornHead(this.projectDir)) return;
    const handle = this.gitHandle();

    let ahead: number;
    try {
      ahead = await this.unpushedCommitCount(handle);
    } catch (e) {
      log.warn(
        { err: e },
        '[sync] pull-only: could not probe stranded commits — skipping conversion',
      );
      return;
    }
    if (ahead === 0) return;

    try {
      await this.checkpointBeforeStrandedConversion?.({ branch: this.currentBranch, ahead });
    } catch (e) {
      log.warn({ err: e }, '[sync] pull-only: stranded-commit checkpoint failed — proceeding');
    }

    try {
      const base = (
        await handle.git.raw(['merge-base', 'HEAD', `origin/${this.currentBranch}`])
      ).trim();
      this.setBatchInProgress?.(true);
      try {
        await withParentLock(() => handle.git.raw(['reset', '--mixed', base]));
      } finally {
        this.setBatchInProgress?.(false);
      }
      const status = await handle.git.status();
      this.ahead = status.ahead;
      this.behind = status.behind;
      this.pausedReason = undefined;
      log.info(
        { ahead, behind: this.behind },
        '[sync] pull-only: folded stranded local commits into a working-tree overlay',
      );
    } catch (e) {
      this.pausedReason = 'diverged-local-commits';
      log.warn(
        { err: e },
        '[sync] pull-only: stranded-commit conversion failed — leaving branch as-is',
      );
    }
  }

  getCredentialConfig(): string[] {
    return this.credentialConfig;
  }

  private async refreshCredentialConfig(): Promise<void> {
    if (!this.resolveCredentialConfig) return;
    try {
      this.credentialConfig = await this.resolveCredentialConfig();
    } catch (err) {
      log.warn({ err }, '[sync] credential config refresh failed — keeping the previous chain');
    }
  }

  async notifyCredentialsChanged(): Promise<void> {
    await this.refreshCredentialConfig();
    if (this.mode === 'off') return;

    this.ghTokenSource.invalidate();
    this.ghAccountResolver.invalidate();

    if (this.state !== 'auth-error' && this.pausedReason !== 'auth-error') return;

    this.pausedReason = undefined;
    this.clearPushError();
    this.clearPullError();
    this.consecutivePullFailures = 0;
    this.consecutivePushFailures = 0;
    this.pushStreakIsConnectivity = false;

    this.hasRemote = await this.probeRemote();
    if (!this.hasRemote) {
      this.transitionTo('dormant');
      this.saveStateNow();
      return;
    }

    this.transitionTo('idle');
    this.schedulePull(0);
    this.schedulePush(0);
    this.saveStateNow();
    void this.probePushPermissionInternal('refresh');
  }

  async trigger(op: 'sync' | 'push' | 'pull' | 'fetch' = 'sync'): Promise<void> {
    if (op === 'fetch') {
      await this.fetchOnly();
      return;
    }
    this.consecutivePullFailures = 0;
    this.consecutivePushFailures = 0;
    this.pushStreakIsConnectivity = false;
    this.consecutiveContentions = 0;
    if (
      this.pausedReason === 'dirty-tree' ||
      this.pausedReason === 'external-changes-pending' ||
      this.pausedReason === 'non-content-merge-failure' ||
      this.pausedReason === 'git-index-locked' ||
      this.pausedReason === 'no-commits-yet'
    ) {
      this.pausedReason = undefined;
      this.clearPullError();
    }
    if (this.parkedOnAmbiguousNotFound()) {
      this.ghTokenSource.invalidate();
      this.ghAccountResolver.invalidate();
      this.pausedReason = undefined;
      this.clearPushError();
      this.clearPullError();
      this.transitionTo('idle');
      this.schedulePull();
      this.schedulePush();
    }
    void this.probePushPermissionInternal('refresh');

    if (op === 'pull') {
      await this.pullOnce();
      return;
    }

    if (op === 'push') {
      await this.pushOnce();
      return;
    }

    if (this.state === 'dormant' || this.state === 'conflict' || this.state === 'auth-error') {
      log.warn(
        {
          op,
          state: this.state,
          mode: this.mode,
          hasRemote: this.hasRemote,
          pausedReason: this.pausedReason,
          conflictCount: this.conflictCount,
        },
        `[sync] trigger(${op}) ignored — state=${this.state}`,
      );
    } else {
      log.info({ op, state: this.state }, `[sync] trigger(${op}) running`);
    }
    await this.pushOnce();
    await this.pullOnce('sync');
  }

  async pushOnce(): Promise<void> {
    if (this.mode === 'full') {
      await this.runPushCycle();
      return;
    }
    await this.runOneShotPush();
  }

  private async runOneShotPush(): Promise<void> {
    if (this.cycleInFlight !== null) {
      log.info(
        { cycleInFlight: this.cycleInFlight },
        '[sync] one-shot push refused — a cycle is already in flight',
      );
      return;
    }
    if (this.state === 'conflict' || this.state === 'auth-error') {
      log.info({ state: this.state }, `[sync] one-shot push refused — state=${this.state}`);
      return;
    }
    if (this.conflictCount > 0) {
      log.info(
        { conflictCount: this.conflictCount },
        '[sync] one-shot push refused — unresolved conflicts hold the tree',
      );
      return;
    }

    if (!this.hasRemote) {
      log.info({ hasRemote: false }, '[sync] one-shot push refused — no remote');
      return;
    }
    if (isUnbornHead(this.projectDir)) {
      this.noteUnbornHeadRefusal();
      return;
    }
    this.clearUnbornHeadPause();

    const restingState = this.state;
    this.cycleInFlight = 'push';
    this.beginIndexLockWatch('push');
    try {
      await this.doPushCycle(1);
    } finally {
      this.cycleInFlight = null;
      this.settleIndexLockPause('push');
      if (this.pushCycleLanded) this.markRun();
      const settled = this.currentState();
      if (settled !== 'conflict' && settled !== 'auth-error') {
        this.transitionTo(restingState);
      }
      this.cc1Broadcaster?.signal('sync-status');
    }
  }

  async fetchOnly(): Promise<boolean> {
    if (!this.hasRemote || isUnbornHead(this.projectDir)) return false;
    if (this.cycleInFlight !== null || this.fetchOnlyInFlight) return false;

    this.fetchOnlyInFlight = true;
    await this.refreshCredentialConfig();
    const handle = this.gitHandle();
    try {
      await handle.git.fetch('origin');
      this.lastFetchUtc = new Date().toISOString();
      this.scheduleSaveState();
    } catch (err) {
      log.debug({ err }, '[sync] panel-open fetch failed — counts left as they were');
      return false;
    } finally {
      this.fetchOnlyInFlight = false;
    }
    await this.refreshDivergenceCounts(handle);
    this.cc1Broadcaster?.signal('sync-status');
    return true;
  }

  private async refreshDivergenceCounts(handle: GitHandle): Promise<void> {
    try {
      const status = await handle.git.status();
      this.ahead = status.ahead;
      this.behind = status.behind;
    } catch (err) {
      log.debug({ err }, '[sync] divergence-count refresh failed — keeping previous counts');
    }
  }

  async pullOnce(invocation: PullInvocation = 'explicit'): Promise<PullOutcome> {
    const mode = this.mode;
    const outcome = await this.runOneShotPull(invocation);
    log.info({ mode, outcome }, '[sync] one-shot pull complete');
    return outcome;
  }

  private async runOneShotPull(invocation: PullInvocation): Promise<PullOutcome> {
    if (this.cycleInFlight !== null) {
      log.info(
        { cycleInFlight: this.cycleInFlight },
        '[sync] one-shot pull refused — a cycle is already in flight',
      );
      return this.recordPullOutcome('refused');
    }
    if (this.state === 'conflict') {
      log.info(
        { state: this.state },
        '[sync] one-shot pull refused — the conflict resolver holds the tree',
      );
      return this.recordPullOutcome('refused');
    }
    if (!this.hasRemote || isUnbornHead(this.projectDir)) {
      log.info(
        { hasRemote: this.hasRemote },
        '[sync] one-shot pull refused — no remote, or no commits yet',
      );
      return this.recordPullOutcome('refused');
    }
    this.clearUnbornHeadPause();

    const restingMode = this.mode;
    const restingState = this.state;
    const restingPausedReason = this.pausedReason;
    this.cycleInFlight = 'pull';
    this.beginIndexLockWatch('pull');
    try {
      return this.recordPullOutcome(await this.doPullCycle(invocation));
    } finally {
      this.cycleInFlight = null;
      this.settleIndexLockPause('pull');
      if (restingMode === 'off') {
        if (!ONE_SHOT_PAUSES.has(this.pausedReason)) {
          if (!ONE_SHOT_PAUSES.has(restingPausedReason)) {
            this.pausedReason = restingPausedReason;
          }
        }
        this.transitionTo(restingState);
      } else {
        this.schedulePull();
      }
    }
  }

  private recordPullOutcome(outcome: PullOutcome): PullOutcome {
    this.lastPullUtc = new Date().toISOString();
    this.lastPullOutcome = outcome;
    if (outcome === 'succeeded' || outcome === 'up-to-date' || outcome === 'conflict') {
      this.lastPullOkUtc = new Date().toISOString();
      this.saveStateNow();
    }
    this.cc1Broadcaster?.signal('sync-status');
    return outcome;
  }

  getStatus(): SyncStatus {
    return {
      state: this.state,
      lastSyncUtc: this.lastSyncUtc,
      lastRunUtc: this.lastRunUtc,
      lastPullOkUtc: this.lastPullOkUtc,
      lastPushOkUtc: this.lastPushOkUtc,
      lastFetchUtc: this.lastFetchUtc,
      lastPushedSha: this.lastPushedSha,
      lastPullUtc: this.lastPullUtc,
      lastPullOutcome: this.lastPullOutcome,
      ahead: this.ahead,
      behind: this.behind,
      consecutiveFailures: this.consecutivePullFailures,
      consecutivePushFailures: this.consecutivePushFailures,
      conflictCount: this.conflictCount,
      hasRemote: this.hasRemote,
      syncEnabled: this.mode !== 'off',
      syncMode: this.mode,
      identityUnresolved: this.identityUnresolved,
      remote: this.hasRemote ? readSyncRemoteInfo(this.projectDir, this.declaredGitHubHosts) : null,
      ...(this.pushError !== undefined ? { pushError: this.pushError } : {}),
      ...(this.pushErrorCode !== undefined ? { pushErrorCode: this.pushErrorCode } : {}),
      ...(this.pullError !== undefined ? { pullError: this.pullError } : {}),
      ...(this.pullErrorCode !== undefined ? { pullErrorCode: this.pullErrorCode } : {}),
      pausedReason: this.pausedReason,
      ...(this.blockingPathsForStatus().length > 0
        ? { blockingPaths: this.blockingPathsForStatus() }
        : {}),
      ...(this.pausedReason === 'unsafe-incoming-symlinks' && this.refusedSymlinkPaths.length > 0
        ? { refusedSymlinkPaths: this.refusedSymlinkPaths.slice(0, REFUSED_SYMLINK_PATHS_CAP) }
        : {}),
      ...(this.pushPermission !== null ? { pushPermission: this.pushPermission } : {}),
    };
  }

  private blockingPathsForStatus(): string[] {
    if (this.pausedReason !== 'external-changes-pending') return [];
    return this.blockingPaths.slice(0, BLOCKING_PATHS_CAP);
  }

  getBlockingPaths(): string[] {
    return this.pausedReason === 'external-changes-pending' ? [...this.blockingPaths] : [];
  }

  async commitBlockingPaths(): Promise<string | null> {
    const paths = this.getBlockingPaths();
    if (paths.length === 0) return null;
    const handle = this.gitHandle();
    return withParentLock(async () => {
      await this.applyCommitIdentity(handle);
      try {
        await handle.git.raw(['add', ...pathspecArgs(paths)]);
        const staged = await listNames(handle.git, [
          'diff',
          '--cached',
          '--name-only',
          ...pathspecArgs(paths),
        ]);
        if (staged.length === 0) return null;
        await handle.git.raw(['commit', '-m', COMMIT_BLOCKING_MESSAGE, ...pathspecArgs(paths)]);
      } catch (err) {
        await handle.git.raw(['reset', ...pathspecArgs(paths)]).catch((resetErr: unknown) => {
          log.warn(
            { resetErr, files: paths.length },
            '[sync] blocking-path index reset failed; paths may remain staged',
          );
        });
        log.error({ err, files: paths.length }, '[sync] commit of blocking paths failed');
        throw err;
      }
      const sha = (await handle.git.revparse('HEAD')).trim();
      this.clearBlockingPause();
      log.info({ files: paths.length }, '[sync] committed overlapping paths at user request');
      return sha;
    });
  }

  private clearBlockingPause(): void {
    this.blockingPaths = [];
    this.pausedReason = undefined;
    this.clearPullError();
    this.consecutivePullFailures = 0;
    this.consecutivePushFailures = 0;
    this.pushStreakIsConnectivity = false;
    this.cc1Broadcaster?.signal('sync-status');
    this.scheduleSaveState();
  }

  async refreshPushPermission(): Promise<PushPermissionStatus | null> {
    return this.probePushPermissionInternal('refresh');
  }

  async refreshIdentity(): Promise<void> {
    const identity = await resolveGitIdentity(this.projectDir);
    const next = identity === null;
    if (this.identityUnresolved !== next) {
      this.identityUnresolved = next;
      this.cc1Broadcaster?.signal('sync-status');
    }
  }

  private async applyCommitIdentity(handle: GitHandle): Promise<void> {
    const identity = await resolveGitIdentity(this.projectDir);
    const nextUnresolved = identity === null;
    if (this.identityUnresolved !== nextUnresolved) {
      this.identityUnresolved = nextUnresolved;
      this.cc1Broadcaster?.signal('sync-status');
    }
    const name = identity?.name ?? 'OpenKnowledge';
    const email = identity?.email ?? '[email protected]';
    applyGitEnv(handle, {
      GIT_AUTHOR_NAME: name,
      GIT_AUTHOR_EMAIL: email,
      GIT_COMMITTER_NAME: name,
      GIT_COMMITTER_EMAIL: email,
    });
  }

  private async probePushPermissionInternal(
    caller: 'start' | 'refresh',
  ): Promise<PushPermissionStatus | null> {
    if (!this.hasRemote) return null;
    if (this.pushPermissionProbeInFlight) return null;

    const origin = readOriginGitHubRepo(this.projectDir, this.declaredGitHubHosts);
    if (origin.kind !== 'ok') {
      const next: PushPermissionStatus = { checkStatus: 'unknown' };
      const prev = this.pushPermission;
      this.pushPermission = next;
      if (this.pausedReason === 'no-push-permission') {
        this.pausedReason = undefined;
        if (this.state === 'disabled' && this.mode === 'full') {
          this.transitionTo('idle');
        }
        log.info(
          { caller, originKind: origin.kind },
          '[sync] push-permission pause cleared — origin is no longer a GitHub host',
        );
        this.cc1Broadcaster?.signal('sync-status');
      } else if (!pushPermissionStatusEqual(prev, next)) {
        this.cc1Broadcaster?.signal('sync-status');
      }
      return next;
    }

    this.pushPermissionProbeInFlight = true;
    log.info(
      {
        caller,
        host: origin.host,
        hasDetectGh: this.detectGh !== undefined,
        hasTokenStore: this.tokenStore !== undefined && this.tokenStore !== null,
      },
      '[sync] push-permission probe dispatching',
    );
    const { account } = this.syncGhTarget();
    let outcome: PushPermission;
    try {
      outcome = await this.checkPushPermissionFn({
        owner: origin.owner,
        repo: origin.repo,
        host: origin.host,
        transport: origin.transport,
        account,
        detectGh: this.detectGh,
        detectGhAccounts: this.detectGhAccounts,
        tokenStore: this.tokenStore,
      });
    } catch (err) {
      log.warn({ err, caller }, '[sync] push-permission probe threw — recording unknown/network');
      outcome = { kind: 'unknown', error: 'network' };
    } finally {
      this.pushPermissionProbeInFlight = false;
    }

    const next = pushPermissionStatusFrom(outcome);
    const prev = this.pushPermission;
    this.pushPermission = next;

    let transitioned = false;
    if (next.checkStatus === 'denied' && this.mode === 'full' && this.parkedOnAmbiguousNotFound()) {
      log.info(
        { reason: next.deniedReason, caller },
        '[sync] probe denial not applied — repository-not-found park is the more specific diagnosis',
      );
    }
    if (
      next.checkStatus === 'denied' &&
      this.mode === 'full' &&
      !this.parkedOnAmbiguousNotFound()
    ) {
      if (this.pausedReason !== 'no-push-permission' || this.state !== 'disabled') {
        this.pausedReason = 'no-push-permission';
        this.transitionTo('disabled');
        transitioned = true;
        log.info(
          { reason: next.deniedReason, caller },
          '[sync] paused — no push permission on origin',
        );
      }
    } else if (next.checkStatus === 'allowed' && this.pausedReason === 'no-push-permission') {
      this.pausedReason = undefined;
      if (this.state === 'disabled' && this.mode === 'full') {
        this.transitionTo('idle');
      }
      transitioned = true;
      log.info({ caller, priorState: this.state }, '[sync] push permission restored');
    }

    if (!transitioned && !pushPermissionStatusEqual(prev, next)) {
      this.cc1Broadcaster?.signal('sync-status');
    }

    return next;
  }

  async refreshRemote(): Promise<void> {
    if (this.hasRemote) return;

    const detected = await this.probeRemote();
    if (!detected) return;

    this.hasRemote = true;
    log.info({ mode: this.mode }, '[sync] remote detected post-boot — re-evaluating state');

    if (this.mode !== 'off') {
      this.transitionTo('idle');
      this.schedulePull(0);
      this.schedulePush();
    } else {
      this.transitionTo('disabled');
    }
  }

  private async probeRemote(): Promise<boolean> {
    if (!existsSync(join(this.projectDir, '.git'))) return false;
    try {
      const handle = this.gitHandle();
      const remoteOutput = await handle.git.raw('remote', '-v');
      return remoteOutput.trim().length > 0;
    } catch (e) {
      log.warn({ err: e }, '[sync] remote detection failed');
      return false;
    }
  }

  private subscribeToConflicts(): void {
    if (this.unsubscribeConflicts !== null) return;
    this.unsubscribeConflicts = this.conflicts.subscribe(() => {
      const blocking = this.conflicts.list().some((e) => e.kind === 'merge-native');
      if (blocking && this.state !== 'conflict') {
        this.transitionTo('conflict');
        this.scheduleSaveState();
        return;
      }
      if (!blocking && this.state === 'conflict') {
        this.transitionTo('idle');
        this.pausedReason = undefined;
        this.schedulePull();
        this.schedulePush();
        this.scheduleSaveState();
      }
    });
  }

  updateCurrentBranch(branch: string | null): void {
    if (branch === null) {
      if (this.state !== 'dormant' && this.state !== 'disabled') {
        this.transitionTo('disabled');
        this.pausedReason = 'detached-head';
        this.scheduleSaveState();
      }
    } else if (this.currentBranch !== branch) {
      this.currentBranch = branch;
      this.conflicts.setBranch(branch);
      if (this.state === 'disabled' && this.pausedReason === 'detached-head') {
        this.pausedReason = undefined;
        this.transitionTo('idle');
        this.schedulePull();
        this.schedulePush(0);
      }
    }
  }

  private schedulePull(overrideDelayMs?: number): void {
    if (this.pullTimer !== null) clearTimeout(this.pullTimer);
    const delayMs = overrideDelayMs ?? this.effectivePullDelayMs();
    this.pullTimer = setTimeout(() => {
      this.pullTimer = null;
      this.runPullCycle().catch((e) => {
        log.error({ err: e }, '[sync] pull cycle uncaught error');
      });
    }, delayMs);
  }

  private schedulePush(overrideDelayMs?: number): void {
    if (this.mode !== 'full') return;
    if (this.pushTimer !== null) clearTimeout(this.pushTimer);
    const delayMs = overrideDelayMs ?? this.effectivePushDelayMs();
    this.pushTimer = setTimeout(() => {
      this.pushTimer = null;
      this.runPushCycle().catch((e) => {
        log.error({ err: e }, '[sync] push cycle uncaught error');
      });
    }, delayMs);
  }

  private effectivePullDelayMs(): number {
    const bkoff = backoffMs(this.consecutivePullFailures);
    const backoffSeconds = bkoff > 0 ? bkoff / 1000 : 0;
    return jitteredMs(Math.max(backoffSeconds, this.pullIntervalSeconds));
  }

  private effectivePushDelayMs(): number {
    const bkoff = backoffMs(this.consecutivePushFailures);
    const backoffSeconds = bkoff > 0 ? bkoff / 1000 : 0;
    return jitteredMs(Math.max(backoffSeconds, this.pushIntervalSeconds));
  }

  private logContention(): void {
    const fields = {
      consecutiveContentions: this.consecutiveContentions,
      consecutivePushFailures: this.consecutivePushFailures,
      releasedConnectivityStreak: this.pushStreakIsConnectivity,
    };
    if (this.consecutiveContentions >= CONTENTION_WARN_THRESHOLD) {
      log.warn(
        fields,
        '[sync] push repeatedly losing to remote contention — not backing off by design',
      );
    } else {
      log.info(
        fields,
        '[sync] push still rejected after retry (contention) — scheduling next push at base cadence',
      );
    }
  }

  private bumpFailureCount(op: 'push' | 'pull', connectivityClass = false): void {
    if (op === 'push') {
      this.consecutiveContentions = 0;
      this.consecutivePushFailures++;
      this.pushStreakIsConnectivity =
        this.consecutivePushFailures === 1
          ? connectivityClass
          : this.pushStreakIsConnectivity && connectivityClass;
    } else this.consecutivePullFailures++;
  }

  private async runPullCycle(): Promise<void> {
    if (this.cycleInFlight !== null) {
      if (this.cycleInFlight === 'push' && this.pullTimer === null) this.schedulePull();
      return;
    }
    if (this.state === 'dormant' || this.state === 'disabled' || this.state === 'auth-error')
      return;
    if (this.state === 'conflict') {
      this.schedulePull();
      return;
    }
    if (isUnbornHead(this.projectDir)) {
      this.schedulePull();
      return;
    }
    this.clearUnbornHeadPause();

    this.cycleInFlight = 'pull';
    this.beginIndexLockWatch('pull');
    try {
      this.recordPullOutcome(await this.doPullCycle(this.mode === 'full' ? 'sync' : 'explicit'));
    } finally {
      this.cycleInFlight = null;
      this.settleIndexLockPause('pull');
      this.schedulePull();
    }
  }

  private async doPullCycle(invocation: PullInvocation): Promise<PullOutcome> {
    if (this.pausedReason === 'git-operation-in-progress') {
      try {
        await this.assertNoGitOperationInProgress();
      } catch (e) {
        if (e instanceof GitOperationInProgressError) {
          this.handleGitOperationRefusal(e, 'pull');
          return 'refused';
        }
        this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
        return 'error';
      }
    }
    await this.refreshCredentialConfig();
    const handle = this.gitHandle();

    let branch: string;
    try {
      const b = (await handle.git.raw('rev-parse', '--abbrev-ref', 'HEAD')).trim();
      if (!b || b === 'HEAD') {
        this.transitionTo('disabled');
        this.pausedReason = 'detached-head';
        log.warn({}, '[sync] detached HEAD — pausing sync');
        return 'refused';
      }
      branch = b;
      this.currentBranch = branch;
    } catch (e) {
      this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
      return 'error';
    }

    this.transitionTo('fetching');
    try {
      await handle.git.fetch('origin');
      this.lastFetchUtc = new Date().toISOString();
      this.consecutivePullFailures = 0;
      this.clearPullError();
      if (this.consecutivePushFailures > 0 && this.pushStreakIsConnectivity) {
        log.info(
          { cleared: this.consecutivePushFailures },
          '[sync] fetch succeeded — releasing connectivity-class push backoff',
        );
        this.consecutivePushFailures = 0;
        this.pushStreakIsConnectivity = false;
        this.schedulePush();
      }
    } catch (e) {
      const classified = classifyGitError(e instanceof Error ? e : new Error(String(e)));
      this.handleError(classified, 'pull');
      return 'error';
    }

    await this.refreshDivergenceCounts(handle);

    let incoming = '';
    const willLand =
      this.behind > 0 && (invocation === 'explicit' ? this.ahead === 0 : this.conflictCount === 0);
    if (willLand) {
      try {
        incoming = await this.validateIncomingSymlinks(handle, branch);
      } catch (e) {
        if (e instanceof UnsafeIncomingSymlinkError) {
          this.handleIncomingSymlinkRefusal(e, 'pull');
          return 'refused';
        }
        this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
        return 'error';
      }
    } else if (this.behind === 0) {
      this.clearIncomingSymlinkPause();
    }

    if (this.behind > 0 && invocation === 'explicit') {
      const outcome = await this.doPullCycleB1(handle, branch, incoming);
      this.scheduleSaveState();
      return outcome;
    }
    if (this.behind > 0 && this.conflictCount === 0) {
      if (this.pausedReason === 'diverged-local-commits') this.pausedReason = undefined;
      this.transitionTo('pulling');
      this.setBatchInProgress?.(true);
      let stashRestored = true;
      let overlaysRestored = true;
      try {
        await this.commitDirtyContentFilesToHead(handle, 'pull');
        await this.validateIncomingSymlinks(handle, branch, incoming);
        const mergePrep = await this.prepareForMerge(handle, branch, incoming);
        if (!mergePrep.proceed) return 'refused';
        try {
          await this.applyCommitIdentity(handle);
          await this.mergeIncomingCommit(handle, branch, incoming);
          this.lastSyncUtc = new Date().toISOString();
          this.behind = 0;
          if (this.pausedReason === 'external-changes-pending') this.clearBlockingPause();
          this.transitionTo('idle');
        } finally {
          if (mergePrep.needsStashPop) {
            stashRestored = await this.popPreMergeStash(handle);
          }
          overlaysRestored = this.restoreReconciledMcpOverlays(mergePrep.reconciled);
        }
        if (!stashRestored) throw new Error('failed to replay pre-merge working-tree state');
        if (!overlaysRestored) throw new Error('failed to restore reconciled MCP overlays');
        await this.persistReconciledMcpEntries(mergePrep.reconciled);
        this.scheduleSaveState();
        return 'succeeded';
      } catch (e) {
        if (e instanceof GitOperationInProgressError) {
          this.handleGitOperationRefusal(e, 'pull');
          return 'refused';
        }
        if (e instanceof UnsafeIncomingSymlinkError) {
          this.handleIncomingSymlinkRefusal(e, 'pull');
          return 'refused';
        }
        if (e instanceof IncomingRefMovedError && stashRestored && overlaysRestored) {
          log.info(
            { branch, incoming, ref: e.ref },
            '[sync] incoming commit moved after inspection; re-inspecting next cycle',
          );
          this.transitionTo('idle');
          return 'refused';
        }
        const failure = !(e instanceof IncomingRefMovedError)
          ? e
          : new Error(
              stashRestored
                ? 'failed to restore reconciled MCP overlays'
                : 'failed to replay pre-merge working-tree state',
            );
        const classified = classifyGitError(
          failure instanceof Error ? failure : new Error(String(failure)),
        );
        if (classified.class === 'semantic' && classified.subclass === 'merge-conflict') {
          await this.handleMergeConflict();
          if (this.state === 'conflict') return 'conflict';
          return this.pullError ? 'error' : 'succeeded';
        }
        this.handleError(classified, 'pull');
        return 'error';
      } finally {
        this.setBatchInProgress?.(false);
      }
    }
    this.transitionTo('idle');
    this.scheduleSaveState();
    return this.behind === 0 ? 'up-to-date' : 'conflict';
  }

  private async doPullCycleB1(
    handle: GitHandle,
    branch: string,
    incomingCommit: string,
  ): Promise<PullOutcome> {
    this.transitionTo('pulling');

    if (this.ahead > 0) {
      this.clearPullError();
      this.pausedReason = 'diverged-local-commits';
      this.transitionTo('idle');
      log.warn(
        { ahead: this.ahead, behind: this.behind },
        '[sync] pull-only: local history diverged — not fast-forwardable, skipping cycle',
      );
      return 'refused';
    }

    let oldHead: string;
    let overlapping: string[];
    try {
      oldHead = (await handle.git.revparse(['HEAD'])).trim();
      const overlayPaths = await listNames(handle.git, ['diff-index', '--name-only', 'HEAD']);
      const incoming = new Set(
        await listNames(handle.git, ['diff', '--name-only', `HEAD..${incomingCommit}`]),
      );
      overlapping = overlayPaths.filter((p) => incoming.has(p));
    } catch (e) {
      this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
      return 'error';
    }

    const existing = new Map<string, Extract<Conflict, { kind: 'working-tree' }>>();
    for (const e of this.conflicts.list()) {
      if (e.kind === 'working-tree') existing.set(e.file, e);
    }

    let plan: Awaited<ReturnType<typeof this.planOverlapReconciliation>>;
    try {
      plan = await this.planOverlapReconciliation(
        handle,
        incomingCommit,
        oldHead,
        overlapping,
        existing,
      );
    } catch (e) {
      this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
      return 'error';
    }

    this.setBatchInProgress?.(true);
    try {
      if (overlapping.length > 0) {
        try {
          await this.checkpointBeforeOverlayRestore?.({ branch, paths: overlapping.length });
        } catch (e) {
          log.warn(
            { err: e, paths: overlapping.length },
            '[sync] pull-only: overlay checkpoint failed before restore — proceeding',
          );
        }
        try {
          await handle.git.raw([
            'restore',
            '--source=HEAD',
            '--staged',
            '--worktree',
            ...pathspecArgs(overlapping),
          ]);
        } catch (e) {
          log.warn(
            { err: e },
            '[sync] pull-only: failed to restore overlay before fast-forward — skipping cycle',
          );
          this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
          return 'error';
        }
      }

      const ff = await this.fastForwardOnly(handle, incomingCommit);
      if (!ff.ok) {
        try {
          this.applyOverlayPlan(plan.mineRestore, plan.deletions);
        } catch (e) {
          log.error(
            { err: e, refusal: ff.refusal },
            '[sync] pull-only: failed to restore overlay after fast-forward refusal',
          );
          this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
          return 'error';
        }
        if (ff.timedOut) {
          log.warn({}, '[sync] pull-only: fast-forward timed out — backing off');
          this.handleError(
            classifyGitError(
              new Error(`git merge --ff-only timed out after ${FF_ONLY_TIMEOUT_MS}ms`),
            ),
            'pull',
          );
          return 'error';
        }
        if (ff.refusal === 'divergence') this.pausedReason = 'diverged-local-commits';
        this.transitionTo('idle');
        log.warn(
          { refusal: ff.refusal, stderr: ff.stderr.slice(0, 200) },
          '[sync] pull-only: fast-forward refused — skipping cycle',
        );
        return 'refused';
      }

      try {
        this.applyOverlayPlan(plan.writes, plan.deletions);
      } catch (e) {
        log.error({ err: e }, '[sync] pull-only: failed to apply overlay after fast-forward');
        this.handleError(classifyGitError(e instanceof Error ? e : new Error(String(e))), 'pull');
        return 'error';
      }
      for (const entry of plan.upserts) {
        this.conflicts.raise(entry);
      }
      for (const file of plan.dissolved) {
        this.conflicts.dissolveWorkingTree(file);
      }

      this.lastSyncUtc = new Date().toISOString();
      this.behind = 0;
      this.clearPullError();
      this.pausedReason = undefined;
      this.blockingPaths = [];
      this.transitionTo('idle');

      const overlayStock = await this.countStandingOverlay(handle);
      log.info(
        {
          created: plan.newConflicts.length,
          autoCombined: plan.autoCombined.length,
          autoDissolved: plan.dissolved.length,
          autoRestored: plan.autoRestored.length,
          overlayStock,
        },
        '[sync] pull-only: fast-forwarded to origin tip',
      );

      return plan.newConflicts.length > 0 ? 'conflict' : 'succeeded';
    } finally {
      this.setBatchInProgress?.(false);
    }
  }

  private async fastForwardOnly(
    handle: GitHandle,
    incoming: string,
  ): Promise<
    | { ok: true }
    | {
        ok: false;
        refusal: FastForwardRefusal;
        stderr: string;
        exitCode: number | null;
        timedOut: boolean;
      }
  > {
    try {
      await execFileAsync('git', ['-c', 'core.autocrlf=false', 'merge', '--ff-only', incoming], {
        cwd: this.projectDir,
        env: handle.env,
        windowsHide: true,
        timeout: FF_ONLY_TIMEOUT_MS,
      });
      return { ok: true };
    } catch (e) {
      const err = e as {
        code?: number | string;
        stderr?: string;
        killed?: boolean;
        signal?: string;
      };
      const timedOut = err.killed === true || err.signal === 'SIGTERM';
      const exitCode = typeof err.code === 'number' ? err.code : null;
      const stderr =
        typeof err.stderr === 'string' ? err.stderr : e instanceof Error ? e.message : String(e);
      return {
        ok: false,
        refusal: classifyFastForwardRefusal({ exitCode, stderr }),
        stderr,
        exitCode,
        timedOut,
      };
    }
  }

  private async planOverlapReconciliation(
    handle: GitHandle,
    incoming: string,
    oldHead: string,
    overlapping: string[],
    existing: Map<string, Extract<Conflict, { kind: 'working-tree' }>>,
  ): Promise<{
    writes: Array<{ path: string; bytes: Buffer }>;
    mineRestore: Array<{ path: string; bytes: Buffer }>;
    deletions: string[];
    upserts: Array<Extract<RaiseInput, { kind: 'working-tree' }>>;
    dissolved: string[];
    newConflicts: string[];
    autoCombined: string[];
    autoRestored: string[];
  }> {
    const writes: Array<{ path: string; bytes: Buffer }> = [];
    const mineRestore: Array<{ path: string; bytes: Buffer }> = [];
    const deletions: string[] = [];
    const upserts: Array<Extract<RaiseInput, { kind: 'working-tree' }>> = [];
    const dissolved: string[] = [];
    const newConflicts: string[] = [];
    const autoCombined: string[] = [];
    const autoRestored: string[] = [];

    for (const p of overlapping) {
      const priorEntry = existing.get(p);
      const hadEntry = priorEntry !== undefined;

      if (!existsSync(join(this.projectDir, p))) {
        try {
          await handle.git.revparse([`${incoming}:${p}`]);
        } catch (e) {
          if (this.classifyRefReadFailure(e) === 'error') {
            deletions.push(p);
            log.warn(
              { err: e, path: p },
              '[sync] pull-only: unexpected error probing origin for a deleted overlay — deferring reconcile',
            );
            continue;
          }
          deletions.push(p);
          if (hadEntry) dissolved.push(p);
          continue;
        }
        if (!this.isContentConflictPath(p)) {
          deletions.push(p);
          continue;
        }
        autoRestored.push(p);
        if (hadEntry) dissolved.push(p);
        continue;
      }

      let mineBuf: Buffer;
      try {
        mineBuf = readFileSync(join(this.projectDir, p));
      } catch {
        continue;
      }
      mineRestore.push({ path: p, bytes: mineBuf });
      const mineStr = mineBuf.toString('utf-8');

      let theirsStr: string | null = null;
      try {
        theirsStr = await handle.git.raw(['show', `${incoming}:${p}`]);
      } catch (e) {
        if (this.classifyRefReadFailure(e) === 'error') {
          log.warn(
            { err: e, path: p },
            '[sync] pull-only: unexpected error reading origin blob — keeping overlay, deferring reconcile',
          );
        }
        theirsStr = null;
      }

      if (theirsStr !== null && theirsStr === mineStr) {
        if (hadEntry) dissolved.push(p);
        continue;
      }

      if (theirsStr !== null && TRACKED_MCP_CONFIG_TARGET_SET.has(p)) {
        const head = await this.readMcpGitBlob(handle, oldHead, p);
        const index = await this.readMcpGitBlob(handle, '', p);
        const mcpPlan = reconcileTrackedMcpConfig({
          target: p,
          layers: {
            base: head,
            head,
            index,
            worktree: mineStr,
            incoming: theirsStr,
          },
          tomlEditor: this.mcpTomlEditor,
        });
        if (mcpPlan.kind === 'resolved') {
          if (mcpPlan.raw !== theirsStr) {
            writes.push({ path: p, bytes: Buffer.from(mcpPlan.raw, 'utf8') });
          }
          log.info(
            { event: 'mcp-config-reconcile', target: p, outcome: 'auto-resolved' },
            '[sync] pull-only: auto-resolved OpenKnowledge MCP entry overlap',
          );
          continue;
        }
        if (mcpPlan.kind === 'declined') {
          log.warn(
            {
              event: 'mcp-config-reconcile',
              target: p,
              outcome: 'declined',
              reason: mcpPlan.reason,
            },
            '[sync] pull-only: declined OpenKnowledge MCP entry reconciliation',
          );
        }
      }

      if (theirsStr === null || !this.isContentConflictPath(p)) {
        writes.push({ path: p, bytes: mineBuf });
        continue;
      }

      const baseSha = hadEntry
        ? priorEntry.baseSha
        : await this.gitBlobSha(handle, `${oldHead}:${p}`);
      const baseStr = baseSha ? await this.gitBlobContent(handle, baseSha) : '';
      const combined = tryLineLevelCombine(baseStr, mineStr, theirsStr);
      if (combined.clean) {
        writes.push({ path: p, bytes: Buffer.from(combined.merged, 'utf-8') });
        autoCombined.push(p);
        if (hadEntry) dissolved.push(p);
        continue;
      }

      writes.push({ path: p, bytes: mineBuf });
      const theirsSha = await this.gitBlobSha(handle, `${incoming}:${p}`);
      if (theirsSha === undefined) {
        log.warn(
          { path: p },
          '[sync] pull-only: could not pin origin blob for a collision — keeping overlay, deferring',
        );
        continue;
      }
      upserts.push({
        kind: 'working-tree',
        file: p,
        theirsSha,
        ...(baseSha === undefined ? {} : { baseSha }),
      });
      if (!hadEntry) newConflicts.push(p);
    }

    return {
      writes,
      mineRestore,
      deletions,
      upserts,
      dissolved,
      newConflicts,
      autoCombined,
      autoRestored,
    };
  }

  private applyOverlayPlan(
    writes: Array<{ path: string; bytes: Buffer }>,
    deletions: string[],
  ): void {
    const guardOpts = { allowShareableOkArtifact: isShareableOkArtifact };
    for (const { path, bytes } of writes) {
      const abs = join(this.projectDir, path);
      const target = assertRealpathWithinDir(abs, this.projectDir, guardOpts);
      tracedWriteFileSync(target, bytes);
    }
    for (const path of deletions) {
      const abs = join(this.projectDir, path);
      assertRealpathWithinDir(abs, this.projectDir, guardOpts);
      try {
        tracedUnlinkSync(abs);
      } catch (e) {
        if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e;
      }
    }
  }

  private isContentConflictPath(file: string): boolean {
    const absPath = join(this.projectDir, file);
    const contentRelPath = toPosix(relative(this.contentDir, absPath));
    return (
      !contentRelPath.startsWith('..') &&
      isSupportedDocFile(contentRelPath) &&
      !this.contentFilter.isExcluded(contentRelPath)
    );
  }

  private async gitBlobSha(handle: GitHandle, ref: string): Promise<string | undefined> {
    try {
      return (await handle.git.revparse([ref])).trim();
    } catch {
      return undefined;
    }
  }

  private classifyRefReadFailure(err: unknown): 'absent' | 'error' {
    const msg = err instanceof Error ? err.message : String(err);
    return /does not exist in|exists on disk, but not in/i.test(msg) ? 'absent' : 'error';
  }

  private async gitBlobContent(handle: GitHandle, sha: string): Promise<string> {
    return handle.git.raw(['cat-file', 'blob', sha]);
  }

  private async countStandingOverlay(handle: GitHandle): Promise<number | null> {
    try {
      const overlayPaths = await listNames(handle.git, ['diff-index', '--name-only', 'HEAD']);
      return overlayPaths.filter((p) => this.isContentConflictPath(p)).length;
    } catch {
      return null;
    }
  }

  private async runPushCycle(): Promise<void> {
    if (this.mode !== 'full') return;
    if (this.state === 'dormant' || this.state === 'disabled') return;
    if (this.state === 'conflict' || this.state === 'auth-error') return;
    if (this.conflictCount > 0) {
      this.schedulePush();
      return;
    }
    if (isUnbornHead(this.projectDir)) {
      if (this.hasRemote) this.noteUnbornHeadRefusal();
      this.schedulePush();
      return;
    }
    this.clearUnbornHeadPause();
    if (this.cycleInFlight !== null) {
      if (this.cycleInFlight === 'pull' && this.pushTimer === null) this.schedulePush();
      return;
    }
    if (this.pausedReason === 'unsafe-incoming-symlinks') {
      this.schedulePush();
      return;
    }

    this.cycleInFlight = 'push';
    this.beginIndexLockWatch('push');
    try {
      await this.doPushCycle(1);
    } finally {
      this.cycleInFlight = null;
      this.settleIndexLockPause('push');
      if (this.pushCycleLanded) this.markRun();
      this.schedulePush();
    }
  }

  private async doPushCycle(retriesLeft = 0): Promise<void> {
    this.pushCycleLanded = false;
    await this.refreshCredentialConfig();
    const tmpIndexPath = join(tmpdir(), `ok-sync-idx-${process.pid}-${Date.now()}.idx`);
    let commitSha: string | null = null;

    try {
      const contentFiles = this.gatherContentFilesSync();
      const promisedPaths = await this.snapshotPromisedPaths();
      const committedPaths = new Set<string>();
      await withParentLock(async () => {
        await this.assertNoGitOperationInProgress();
        this.transitionTo('pushing');
        try {
          const handle = this.gitHandle(tmpIndexPath);

          if (isUnbornHead(this.projectDir)) {
            log.info({}, '[sync] repo has no commits yet — skipping push cycle');
            this.transitionTo('idle');
            return;
          }
          let headSha: string;
          try {
            headSha = (await handle.git.revparse('HEAD')).trim();
          } catch (e) {
            const msg = e instanceof Error ? e.message : String(e);
            const raw = (e as { git?: unknown }).git?.toString() ?? msg;
            const combined = `${msg}\n${raw}`;
            if (
              /unknown revision or path not in the working tree/i.test(combined) ||
              /ambiguous argument 'HEAD'/i.test(combined) ||
              /does not have any commits yet/i.test(combined)
            ) {
              log.info({}, '[sync] repo has no commits yet — skipping push cycle');
              this.transitionTo('idle');
              return;
            }
            this.handleError(
              classifyGitError(e instanceof Error ? e : new Error(String(e))),
              'push',
            );
            return;
          }

          await handle.git.raw(['read-tree', headSha]);

          const headContentSet = await this.listHeadContentPaths(handle, headSha);

          const staged = await this.stageContentFiles(handle, contentFiles);

          const onDiskSet = new Set(staged.map((f) => f.projectRelPath));
          const deleted = [...headContentSet].filter((f) => !onDiskSet.has(f));
          await this.removePathsFromIndex(handle, deleted);

          const newTreeSha = (await handle.git.raw(['write-tree'])).trim();

          let headTreeSha = '';
          try {
            headTreeSha = (await handle.git.raw(['rev-parse', `${headSha}^{tree}`])).trim();
          } catch {}
          if (headTreeSha && headTreeSha === newTreeSha) {
            let upstreamSha: string | null = null;
            try {
              upstreamSha = (
                await handle.git.raw(['rev-parse', `origin/${this.currentBranch}`])
              ).trim();
            } catch {}

            if (upstreamSha === headSha) {
              log.info(
                { contentFileCount: contentFiles.length, headSha },
                '[sync] push cycle: nothing to commit (tree unchanged, origin matches HEAD)',
              );
              this.lastPushedSha = headSha;
              this.lastSyncUtc = new Date().toISOString();
              this.pushCycleLanded = true;
              this.consecutivePushFailures = 0;
              this.consecutiveContentions = 0;
              this.pushStreakIsConnectivity = false;
              this.clearPushError();
              this.transitionTo('idle');
              return;
            }

            log.info(
              { headSha, upstreamSha },
              '[sync] push cycle: tree unchanged but local ahead of origin — pushing existing commits',
            );

            let hasUpstream = false;
            try {
              await handle.git.raw(['rev-parse', '--abbrev-ref', `${this.currentBranch}@{u}`]);
              hasUpstream = true;
            } catch {}

            if (hasUpstream) {
              await handle.git.raw(['push', 'origin', this.currentBranch]);
            } else {
              await handle.git.raw(['push', '--set-upstream', 'origin', this.currentBranch]);
            }

            commitSha = headSha;
            return;
          }

          let changedProjectRelPaths: string[] = [];
          let changedContentRelPaths: string[] = [];
          try {
            const diffPaths = await listNames(handle.git, [
              'diff-tree',
              '--name-only',
              '-r',
              headSha,
              newTreeSha,
            ]);
            if (diffPaths.length > 0) {
              const contentFileByProjRel = new Map(
                contentFiles.map((f) => [f.projectRelPath, f.contentRelPath]),
              );
              for (const projRelPath of diffPaths) {
                changedProjectRelPaths.push(projRelPath);
                const contentRelPath =
                  contentFileByProjRel.get(projRelPath) ??
                  toPosix(relative(this.contentDir, join(this.projectDir, projRelPath)));
                if (contentRelPath && !contentRelPath.startsWith('..')) {
                  changedContentRelPaths.push(contentRelPath);
                }
              }
            }
          } catch {
            changedProjectRelPaths = contentFiles.map((f) => f.projectRelPath).concat(deleted);
            changedContentRelPaths = contentFiles.map((f) => f.contentRelPath);
          }
          const message = this.buildCommitMessage(changedContentRelPaths);

          await this.applyCommitIdentity(handle);

          const newCommitSha = (
            await handle.git.raw(['commit-tree', newTreeSha, '-p', headSha, '-m', message])
          ).trim();

          if (!newCommitSha || !SHA_HEX_40.test(newCommitSha)) {
            log.warn(
              { raw: newCommitSha },
              '[sync] commit-tree returned invalid SHA — aborting push',
            );
            this.transitionTo('idle');
            return;
          }

          await handle.git.raw([
            'update-ref',
            `refs/heads/${this.currentBranch}`,
            newCommitSha,
            headSha,
          ]);

          await this.resetRealIndexForPaths(changedProjectRelPaths, 'push');
          for (const projRelPath of changedProjectRelPaths) committedPaths.add(projRelPath);

          let hasUpstream = false;
          try {
            await handle.git.raw(['rev-parse', '--abbrev-ref', `${this.currentBranch}@{u}`]);
            hasUpstream = true;
          } catch {}

          if (hasUpstream) {
            await handle.git.raw(['push', 'origin', this.currentBranch]);
          } else {
            await handle.git.raw(['push', '--set-upstream', 'origin', this.currentBranch]);
          }

          commitSha = newCommitSha;
        } finally {
          await this.healStaleRealIndex(promisedPaths, committedPaths);
        }
      });

      if (commitSha) {
        this.lastPushedSha = commitSha;
        this.lastSyncUtc = new Date().toISOString();
        this.pushCycleLanded = true;
        this.ahead = 0;
        this.consecutivePushFailures = 0;
        this.consecutiveContentions = 0;
        this.pushStreakIsConnectivity = false;
        this.clearPushError();
        if (this.state === 'pushing') {
          this.transitionTo('idle');
        }
        if (this.pausedReason === 'dirty-tree') {
          this.pausedReason = undefined;
          this.clearPullError();
          this.schedulePull(0);
        }
      }
    } catch (e) {
      if (e instanceof GitOperationInProgressError) {
        this.handleGitOperationRefusal(e, 'push');
        return;
      }
      const err = e instanceof Error ? e : new Error(String(e));
      if (err instanceof ShareableOkEnumerationError) {
        log.warn({ err }, '[sync] push cycle: staging error detail');
      }
      const classified = classifyGitError(err);
      if (classified.class === 'semantic' && classified.subclass === 'non-fast-forward') {
        if (retriesLeft > 0) {
          log.info({}, '[sync] push rejected (non-fast-forward) — fetching, merging, retrying');
          const retryHandle = this.gitHandle();
          this.setBatchInProgress?.(true);
          let retryStage: 'fetch' | 'merge' | 'push' = 'fetch';
          let stashRestored = true;
          let overlaysRestored = true;
          try {
            await retryHandle.git.fetch('origin');
            const incoming = await this.validateIncomingSymlinks(retryHandle, this.currentBranch);
            retryStage = 'push';
            await this.commitDirtyContentFilesToHead(retryHandle, 'push');
            retryStage = 'fetch';
            await this.validateIncomingSymlinks(retryHandle, this.currentBranch, incoming);
            retryStage = 'push';
            const mergePrep = await this.prepareForMerge(retryHandle, this.currentBranch, incoming);
            if (!mergePrep.proceed) {
              this.setBatchInProgress?.(false);
              return;
            }
            try {
              await this.applyCommitIdentity(retryHandle);
              retryStage = 'merge';
              await this.mergeIncomingCommit(retryHandle, this.currentBranch, incoming);
              retryStage = 'push';
            } finally {
              if (mergePrep.needsStashPop) {
                stashRestored = await this.popPreMergeStash(retryHandle);
              }
              overlaysRestored = this.restoreReconciledMcpOverlays(mergePrep.reconciled);
            }
            if (!stashRestored) throw new Error('failed to replay pre-merge working-tree state');
            if (!overlaysRestored) throw new Error('failed to restore reconciled MCP overlays');
            await this.persistReconciledMcpEntries(mergePrep.reconciled);
          } catch (mergeErr) {
            if (mergeErr instanceof GitOperationInProgressError) {
              this.handleGitOperationRefusal(mergeErr, 'push');
              return;
            }
            if (mergeErr instanceof UnsafeIncomingSymlinkError) {
              this.handleIncomingSymlinkRefusal(mergeErr, 'push');
              return;
            }
            if (mergeErr instanceof IncomingRefMovedError && stashRestored && overlaysRestored) {
              log.info(
                { ref: mergeErr.ref },
                '[sync] push retry: incoming commit moved after inspection; re-inspecting next cycle',
              );
              if (this.state === 'pushing') this.transitionTo('idle');
              this.scheduleSaveState();
              return;
            }
            const failure = !(mergeErr instanceof IncomingRefMovedError)
              ? mergeErr
              : new Error(
                  stashRestored
                    ? 'failed to restore reconciled MCP overlays'
                    : 'failed to replay pre-merge working-tree state',
                );
            const mc = classifyGitError(
              failure instanceof Error ? failure : new Error(String(failure)),
            );
            if (mc.class === 'semantic' && mc.subclass === 'merge-conflict') {
              await this.handleMergeConflict();
            } else {
              const leg = retryStage === 'merge' || retryStage === 'fetch' ? 'pull' : 'push';
              log.warn({ err: mergeErr, stage: retryStage }, '[sync] push retry error detail');
              this.handleError(mc, leg);
            }
            this.scheduleSaveState();
            return;
          } finally {
            this.setBatchInProgress?.(false);
          }
          await this.doPushCycle(0);
          return;
        }
        this.consecutiveContentions++;
        this.logContention();
        if (this.pushStreakIsConnectivity) {
          this.consecutivePushFailures = 0;
          this.pushStreakIsConnectivity = false;
          this.clearPushError();
        }
        if (this.state === 'pushing') this.transitionTo('idle');
      } else {
        this.handleError(classified, 'push');
      }
    } finally {
      try {
        unlinkSync(tmpIndexPath);
      } catch {}
    }

    this.scheduleSaveState();
  }

  private async commitDirtyContentFilesToHead(
    handle: GitHandle,
    op: SyncCycleOp,
  ): Promise<string | null> {
    await this.assertNoGitOperationInProgress();
    const status = await handle.git.status();
    if (status.files.length === 0) return null;

    const headSha = (await handle.git.revparse('HEAD')).trim();
    const contentFiles = this.gatherContentFilesSync();
    const headContentSet = await this.listHeadContentPaths(handle, headSha);
    if (contentFiles.length === 0 && headContentSet.size === 0) return null;

    const tmpIndex = join(tmpdir(), `ok-sync-retry-idx-${process.pid}-${Date.now()}.idx`);
    const isoHandle = this.gitHandle(tmpIndex);
    try {
      await isoHandle.git.raw(['read-tree', headSha]);
      const staged = await this.stageContentFiles(isoHandle, contentFiles);
      const onDiskSet = new Set(staged.map((f) => f.projectRelPath));
      const deleted = [...headContentSet].filter((f) => !onDiskSet.has(f));
      await this.removePathsFromIndex(isoHandle, deleted);
      const newTreeSha = (await isoHandle.git.raw(['write-tree'])).trim();
      const headTreeSha = (await isoHandle.git.raw(['rev-parse', `${headSha}^{tree}`])).trim();
      if (newTreeSha === headTreeSha) return null;
      let changedProjectRelPaths: string[] = [];
      try {
        changedProjectRelPaths = await listNames(isoHandle.git, [
          'diff-tree',
          '--name-only',
          '-r',
          headSha,
          newTreeSha,
        ]);
      } catch {
        changedProjectRelPaths = contentFiles.map((f) => f.projectRelPath).concat(deleted);
      }

      await this.applyCommitIdentity(isoHandle);

      const message = 'Auto-save: interim before merge';
      const newCommitSha = (
        await isoHandle.git.raw(['commit-tree', newTreeSha, '-p', headSha, '-m', message])
      ).trim();
      if (!newCommitSha || !SHA_HEX_40.test(newCommitSha)) {
        log.warn(
          { raw: newCommitSha },
          '[sync] commit-tree returned invalid SHA in commitDirtyContentFilesToHead',
        );
        return null;
      }

      await handle.git.raw([
        'update-ref',
        `refs/heads/${this.currentBranch}`,
        newCommitSha,
        headSha,
      ]);

      await this.resetRealIndexForPaths(changedProjectRelPaths, op, handle);

      return newCommitSha;
    } finally {
      try {
        unlinkSync(tmpIndex);
      } catch {}
    }
  }

  private async readMcpGitBlob(
    handle: GitHandle,
    revision: string,
    path: string,
  ): Promise<string | null> {
    try {
      await handle.git.raw(['cat-file', '-e', `${revision}:${path}`]);
      return await handle.git.raw(['show', `${revision}:${path}`]);
    } catch {
      return null;
    }
  }

  private async planTrackedMcpOverlap(
    handle: GitHandle,
    incomingCommit: string,
    path: string,
  ): Promise<ReturnType<typeof reconcileTrackedMcpConfig>> {
    let baseRevision: string;
    try {
      baseRevision = (await handle.git.raw(['merge-base', 'HEAD', incomingCommit])).trim();
    } catch (err) {
      log.warn(
        { err, incomingCommit, path },
        '[sync] MCP reconciliation merge-base unavailable — declining',
      );
      return { kind: 'declined', reason: 'merge-base-unavailable' };
    }
    const [base, head, index, incoming] = await Promise.all([
      this.readMcpGitBlob(handle, baseRevision, path),
      this.readMcpGitBlob(handle, 'HEAD', path),
      this.readMcpGitBlob(handle, '', path),
      this.readMcpGitBlob(handle, incomingCommit, path),
    ]);
    let worktree: string | null = null;
    try {
      worktree = readFileSync(join(this.projectDir, path), 'utf8');
    } catch {}
    return reconcileTrackedMcpConfig({
      target: path,
      layers: { base, head, index, worktree, incoming },
      tomlEditor: this.mcpTomlEditor,
    });
  }

  private async prepareForMerge(
    handle: GitHandle,
    branch: string,
    incoming: string,
  ): Promise<MergePreparation> {
    const reconciled: PreparedMcpReconciliation[] = [];
    let dirtyPaths: string[];
    try {
      dirtyPaths = await listNames(handle.git, ['diff-index', '--name-only', 'HEAD']);
    } catch (err) {
      log.warn({ err, branch }, '[sync] diff-index failed — allowing merge attempt');
      return { proceed: true, needsStashPop: false, reconciled };
    }
    if (dirtyPaths.length === 0) return { proceed: true, needsStashPop: false, reconciled };

    let mergePaths: Set<string>;
    try {
      mergePaths = new Set(
        await listNames(handle.git, ['diff', '--name-only', `HEAD..${incoming}`]),
      );
    } catch (err) {
      log.warn({ err, branch }, '[sync] merge-path diff failed — allowing merge attempt');
      return { proceed: true, needsStashPop: false, reconciled };
    }
    let blocking = dirtyPaths.filter((p) => mergePaths.has(p));

    const trackedTargets = TRACKED_MCP_CONFIG_TARGET_SET;
    const mcpOverlaps = blocking.filter((path) => trackedTargets.has(path));
    if (mcpOverlaps.length > 0) {
      const plans = await Promise.all(
        mcpOverlaps.map(async (path) => ({
          path,
          plan: await this.planTrackedMcpOverlap(handle, incoming, path),
        })),
      );
      const declined = plans.find(({ plan }) => plan.kind === 'declined');
      const hasOtherBlockingPath = blocking.some((path) => !trackedTargets.has(path));
      if (!declined && !hasOtherBlockingPath) {
        for (const { path, plan } of plans) {
          if (plan.kind !== 'resolved') continue;
          reconciled.push({ path, raw: plan.raw, winnerEntry: plan.winnerEntry });
          log.info(
            { event: 'mcp-config-reconcile', target: path, outcome: 'auto-resolved' },
            '[sync] auto-resolved OpenKnowledge MCP entry overlap',
          );
        }
        blocking = blocking.filter((path) => !trackedTargets.has(path));
      } else if (declined) {
        log.warn(
          {
            event: 'mcp-config-reconcile',
            target: declined.path,
            outcome: 'declined',
            reason: declined.plan.kind === 'declined' ? declined.plan.reason : undefined,
          },
          '[sync] declined OpenKnowledge MCP entry reconciliation',
        );
      } else if (hasOtherBlockingPath) {
        log.info(
          {
            event: 'mcp-config-reconcile',
            targets: mcpOverlaps,
            outcome: 'suppressed',
            reason: 'other-blocking-path',
          },
          '[sync] suppressed MCP entry reconciliation because another path blocks the merge',
        );
      }
    }

    if (blocking.length > 0) {
      const display = blocking.slice(0, 3).join(', ');
      const rest = blocking.length > 3 ? `, +${blocking.length - 3} more` : '';
      this.blockingPaths = blocking;
      this.pullErrorCode = undefined;
      this.pullError = `Sync paused — your local changes to ${display}${rest} conflict with incoming changes. Commit, stash, or discard them before syncing.`;
      this.pausedReason = 'external-changes-pending';
      this.consecutivePullFailures = 0;
      this.transitionTo('idle');
      this.scheduleSaveState();
      log.warn({ files: blocking }, '[sync] paused — dirty paths overlap incoming merge');
      return { proceed: false, needsStashPop: false, reconciled: [] };
    }

    if (reconciled.length > 0) {
      try {
        await handle.git.raw([
          'restore',
          '--source=HEAD',
          '--staged',
          '--worktree',
          ...pathspecArgs(reconciled.map((item) => item.path)),
        ]);
      } catch (err) {
        log.warn({ err }, '[sync] could not isolate reconciled MCP paths from pre-merge stash');
        this.pullError =
          'Sync paused — OpenKnowledge could not safely isolate local MCP launcher changes before merging.';
        this.pausedReason = 'external-changes-pending';
        this.blockingPaths = [];
        this.transitionTo('idle');
        this.scheduleSaveState();
        return { proceed: false, needsStashPop: false, reconciled: [] };
      }
    }

    const reconciledPaths = new Set(reconciled.map((item) => item.path));
    if (dirtyPaths.every((path) => reconciledPaths.has(path))) {
      return { proceed: true, needsStashPop: false, reconciled };
    }

    const stashMessage = `ok-sync: pre-merge stash @ ${new Date().toISOString()}`;
    try {
      await handle.git.raw(['stash', 'push', '-m', stashMessage]);
    } catch (err) {
      log.warn({ err }, '[sync] stash push failed — proceeding without stash');
      return { proceed: true, needsStashPop: false, reconciled };
    }
    return { proceed: true, needsStashPop: true, reconciled };
  }

  private restoreReconciledMcpOverlays(reconciled: PreparedMcpReconciliation[]): boolean {
    let restored = true;
    for (const item of reconciled) {
      try {
        const absolutePath = join(this.projectDir, item.path);
        const target = assertRealpathWithinDir(absolutePath, this.projectDir);
        let existing: string | null = null;
        try {
          existing = readFileSync(target, 'utf8');
        } catch (err) {
          log.warn(
            { err, path: item.path },
            '[sync] could not read MCP config before restoring reconciled overlay',
          );
        }
        if (existing !== item.raw) tracedWriteFileSync(target, item.raw, 'utf8');
      } catch (err) {
        restored = false;
        log.warn({ err, path: item.path }, '[sync] could not restore reconciled MCP overlay');
      }
    }
    return restored;
  }

  private async popPreMergeStash(handle: GitHandle): Promise<boolean> {
    try {
      await handle.git.raw(['stash', 'pop']);
      return true;
    } catch (err) {
      log.warn({ err }, '[sync] stash pop failed — stash remains on stack');
      return false;
    }
  }

  private async assertNoGitOperationInProgress(): Promise<void> {
    if (this.hasGitOperationInProgress()) throw new GitOperationInProgressError();
    const unmerged = await listNames(this.gitHandle().git, [
      'diff',
      '--name-only',
      '--diff-filter=U',
    ]);
    if (unmerged.length > 0 || this.hasGitOperationInProgress()) {
      throw new GitOperationInProgressError();
    }
    if (this.pausedReason === 'git-operation-in-progress') {
      this.pausedReason = undefined;
      this.cc1Broadcaster?.signal('sync-status');
      this.scheduleSaveState();
    }
  }

  private handleGitOperationRefusal(error: GitOperationInProgressError, op: 'push' | 'pull'): void {
    if (this.state === 'conflict' || this.conflictCount > 0) {
      this.transitionTo('conflict');
    } else {
      this.pausedReason = 'git-operation-in-progress';
      if (op === 'push') this.clearPushError();
      else this.clearPullError();
      if (this.state === 'pushing' || this.state === 'pulling' || this.state === 'fetching') {
        this.transitionTo('idle');
      }
    }
    log.error(
      { event: 'git-operation-refusal', err: error, op, branch: this.currentBranch },
      '[sync] cycle refused because a Git operation holds the tree — finish or abort it to resume sync',
    );
    this.cc1Broadcaster?.signal('sync-status');
    this.scheduleSaveState();
  }

  private async validateIncomingSymlinks(
    handle: GitHandle,
    branch: string,
    inspected?: string,
  ): Promise<string> {
    const trackingRef = `refs/remotes/origin/${branch}`;
    let incoming = inspected;
    try {
      incoming ??= await resolveIncomingCommit(handle.git, trackingRef);
      await assertIncomingSymlinksSafe(handle.git, incoming, 'merge', handle.env);
    } catch (e) {
      const links =
        e instanceof UnsafeIncomingSymlinkError
          ? e.unsafe.slice(0, REFUSED_SYMLINK_PATHS_CAP)
          : null;
      const refusalKey = links === null ? undefined : JSON.stringify([incoming, links]);
      if (links !== null && refusalKey !== this.loggedSymlinkRefusal) {
        this.loggedSymlinkRefusal = refusalKey;
        log.warn(
          { event: 'unsafe-incoming-symlinks', branch, incoming, links },
          '[sync] refusing incoming changes with unsafe symlinks until they are fixed',
        );
      }
      if (links === null) {
        log.warn(
          { err: e, branch, trackingRef, incoming },
          '[sync] incoming symlink inspection failed',
        );
      }
      throw e;
    }
    this.clearIncomingSymlinkPause();
    return incoming;
  }

  private handleIncomingSymlinkRefusal(
    error: UnsafeIncomingSymlinkError,
    op: 'push' | 'pull',
  ): void {
    this.pausedReason = 'unsafe-incoming-symlinks';
    this.refusedSymlinkPaths = error.displayPaths();
    if (op === 'push') this.clearPushError();
    else this.clearPullError();
    if (this.state === 'pushing' || this.state === 'pulling' || this.state === 'fetching') {
      this.transitionTo('idle');
    }
    this.cc1Broadcaster?.signal('sync-status');
    this.scheduleSaveState();
  }

  private clearIncomingSymlinkPause(): void {
    this.loggedSymlinkRefusal = undefined;
    if (this.pausedReason !== 'unsafe-incoming-symlinks') return;
    this.pausedReason = undefined;
    this.refusedSymlinkPaths = [];
    this.cc1Broadcaster?.signal('sync-status');
  }

  private async mergeIncomingCommit(
    handle: GitHandle,
    branch: string,
    incoming: string,
  ): Promise<void> {
    const name = `origin/${branch}`;
    try {
      await assertMergeNameResolvesTo(handle.git, {
        name,
        trackingRef: `refs/remotes/${name}`,
        commit: incoming,
      });
    } catch (e) {
      if (e instanceof IncomingRefShadowedError) {
        log.warn(
          { event: 'incoming-ref-shadowed', shadowedName: e.shadowedName, incoming },
          '[sync] another ref shadows the incoming branch name; delete it locally and on the remote',
        );
      }
      throw e;
    }
    await handle.git.merge([name]);
  }

  private hasGitOperationInProgress(): boolean {
    const gitDir = resolveGitDir(this.projectDir);
    if (!gitDir) return true;
    return ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply'].some(
      (marker) => existsSync(join(gitDir, marker)),
    );
  }

  private async persistReconciledMcpEntries(
    reconciled: PreparedMcpReconciliation[],
  ): Promise<void> {
    if (reconciled.length === 0) return;
    if (this.hasGitOperationInProgress()) {
      throw new GitOperationInProgressError();
    }

    await withParentLock(async () => {
      const tmpIndex = join(tmpdir(), `ok-mcp-sync-idx-${process.pid}-${Date.now()}.idx`);
      const tempBlobs: string[] = [];
      try {
        const realHandle = this.gitHandle();
        const isolated = this.gitHandle(tmpIndex);
        const headSha = (await isolated.git.revparse('HEAD')).trim();
        const branch = (await isolated.git.revparse(['--abbrev-ref', 'HEAD'])).trim();
        if (branch === 'HEAD') throw new Error('refusing MCP entry commit on detached HEAD');
        await isolated.git.raw(['read-tree', headSha]);

        const replayEntries: Array<{ path: string; mode: string; blobSha: string; raw: string }> =
          [];
        for (let i = 0; i < reconciled.length; i++) {
          const item = reconciled[i];
          if (!item) continue;
          const headRaw = await this.readMcpGitBlob(isolated, headSha, item.path);
          if (headRaw === null) throw new Error(`tracked MCP path disappeared: ${item.path}`);
          const commitRaw = applyManagedMcpEntry({
            target: item.path,
            raw: headRaw,
            entry: item.winnerEntry,
            tomlEditor: this.mcpTomlEditor,
          });
          if (commitRaw === null) throw new Error(`cannot edit tracked MCP path: ${item.path}`);

          const treeLine = await isolated.git.raw([
            'ls-tree',
            headSha,
            ...pathspecArgs([item.path]),
          ]);
          const mode = treeLine.match(/^(100644|100755)\s/)?.[1];
          if (!mode) throw new Error(`unsafe tracked MCP mode: ${item.path}`);

          const commitBlobPath = `${tmpIndex}.commit-${i}`;
          tempBlobs.push(commitBlobPath);
          writeFileSync(commitBlobPath, commitRaw, 'utf8');
          const commitBlobSha = (
            await isolated.git.raw(['hash-object', '-w', commitBlobPath])
          ).trim();
          await isolated.git.raw([
            'update-index',
            '--add',
            '--cacheinfo',
            `${mode},${commitBlobSha},${item.path}`,
          ]);

          const committedShell = getMcpUnownedShell({
            target: item.path,
            raw: commitRaw,
            tomlEditor: this.mcpTomlEditor,
          });
          const overlayShell = getMcpUnownedShell({
            target: item.path,
            raw: item.raw,
            tomlEditor: this.mcpTomlEditor,
          });
          const replayRaw =
            committedShell !== null && committedShell === overlayShell ? commitRaw : item.raw;
          const replayBlobPath = `${tmpIndex}.replay-${i}`;
          tempBlobs.push(replayBlobPath);
          writeFileSync(replayBlobPath, replayRaw, 'utf8');
          const replayBlobSha = (
            await isolated.git.raw(['hash-object', '-w', replayBlobPath])
          ).trim();
          replayEntries.push({ path: item.path, mode, blobSha: replayBlobSha, raw: replayRaw });
        }

        const newTree = (await isolated.git.raw(['write-tree'])).trim();
        const headTree = (await isolated.git.raw(['rev-parse', `${headSha}^{tree}`])).trim();
        if (newTree === headTree) return;

        await this.applyCommitIdentity(isolated);
        const commitSha = (
          await isolated.git.raw([
            'commit-tree',
            newTree,
            '-p',
            headSha,
            '-m',
            'Update OpenKnowledge MCP launcher',
          ])
        ).trim();
        if (!SHA_HEX_40.test(commitSha)) throw new Error('commit-tree returned an invalid SHA');
        try {
          await isolated.git.raw(['update-ref', `refs/heads/${branch}`, commitSha, headSha]);
        } catch (err) {
          log.info(
            { event: 'mcp-config-reconcile', outcome: 'ref-race', branch, err },
            '[sync] skipped MCP launcher commit because the branch moved',
          );
          return;
        }

        try {
          for (const replay of replayEntries) {
            await realHandle.git.raw([
              'update-index',
              '--add',
              '--cacheinfo',
              `${replay.mode},${replay.blobSha},${replay.path}`,
            ]);
            const absolutePath = join(this.projectDir, replay.path);
            const target = assertRealpathWithinDir(absolutePath, this.projectDir);
            if (readFileSync(target, 'utf8') !== replay.raw) {
              tracedWriteFileSync(target, replay.raw, 'utf8');
            }
          }
        } catch (err) {
          log.warn(
            { event: 'mcp-config-reconcile', outcome: 'overlay-replay-failed', err },
            '[sync] MCP overlay replay failed; resetting the affected index entries',
          );
          await this.resetRealIndexForPaths(
            replayEntries.map((entry) => entry.path),
            'mcp-reconcile',
          );
          this.restoreReconciledMcpOverlays(reconciled);
        }
        log.info(
          { event: 'mcp-config-reconcile', outcome: 'persisted-entry-commit' },
          '[sync] persisted OpenKnowledge MCP launcher entry commit',
        );
      } finally {
        for (const path of tempBlobs) {
          try {
            unlinkSync(path);
          } catch {}
        }
        try {
          unlinkSync(tmpIndex);
        } catch {}
      }
    });
  }

  /**
   * Precedent #55 (walker and `git add` agree on scope) is enforced here rather than in content
   * admission.
   */
  private async stageContentFiles(
    handle: GitHandle,
    files: ContentFileEntry[],
  ): Promise<ContentFileEntry[]> {
    if (files.length === 0) return files;
    const BATCH = 100;
    const refused = new Set<string>();
    let probeOk = true;
    for (let i = 0; i < files.length; i += BATCH) {
      const batch = files.slice(i, i + BATCH).map((f) => f.projectRelPath);
      try {
        const ignored = await listNames(handle.git, [
          'ls-files',
          '--others',
          '--ignored',
          '--exclude-standard',
          ...pathspecArgs(batch),
        ]);
        for (const p of ignored) refused.add(p);
      } catch (err) {
        probeOk = false;
        log.warn({ err }, '[sync] ignored-path probe failed — staging unfiltered without -f');
      }
    }
    if (refused.size > 0) {
      log.info(
        { count: refused.size, sample: [...refused].slice(0, 5) },
        '[sync] skipping gitignored untracked path(s) — in content scope but excluded from git',
      );
    }
    const refusedDirs = [...refused].filter((p) => p.endsWith('/'));
    const isRefused = (p: string) => refused.has(p) || refusedDirs.some((d) => p.startsWith(d));
    const stageable = probeOk ? files.filter((f) => !isRefused(f.projectRelPath)) : files;
    const hasOkSegment = (p: string) => p.startsWith(`${OK_DIR}/`) || p.includes(`/${OK_DIR}/`);
    const forced = probeOk ? stageable.filter((f) => hasOkSegment(f.projectRelPath)) : [];
    const plain = probeOk ? stageable.filter((f) => !hasOkSegment(f.projectRelPath)) : stageable;
    for (const [addArgs, group] of [
      [['add'], plain],
      [['add', '-f'], forced],
    ] as const) {
      for (let i = 0; i < group.length; i += BATCH) {
        const batch = group.slice(i, i + BATCH).map((f) => f.projectRelPath);
        await handle.git.raw([...addArgs, ...pathspecArgs(batch)]);
      }
    }
    return stageable;
  }

  private gatherContentFilesSync(): ContentFileEntry[] {
    const results: ContentFileEntry[] = [];
    const failUnreadableOkSubtree = (err: unknown, dir: string) => {
      const relDir = toPosix(relative(this.projectDir, dir)) || '.';
      throw new ShareableOkEnumerationError(relDir, err);
    };

    const walk = (
      dir: string,
      filterBase: string,
      stagingScope: SyncStagingScope,
      onError?: (err: unknown, dir: string) => void,
    ) => {
      let entries: Dirent[];
      try {
        entries = readdirSync(dir, { withFileTypes: true });
      } catch (err) {
        onError?.(err, dir);
        return;
      }
      for (const entry of entries) {
        const fullPath = join(dir, entry.name);
        if (entry.isDirectory()) {
          const dirRelPath = toPosix(relative(filterBase, fullPath));
          if (
            !dirRelPath.startsWith('..') &&
            this.contentFilter.isDirExcluded(dirRelPath, stagingScope)
          )
            continue;
          const entersOkSubtree = dirRelPath
            .split('/')
            .some((segment) => segment.toLowerCase() === OK_DIR);
          walk(
            fullPath,
            filterBase,
            stagingScope,
            onError ?? (entersOkSubtree ? failUnreadableOkSubtree : undefined),
          );
        } else if (entry.isFile() || entry.isSymbolicLink()) {
          const filterRelPath = toPosix(relative(filterBase, fullPath));
          if (
            !filterRelPath.startsWith('..') &&
            !this.contentFilter.isExcluded(filterRelPath, stagingScope)
          ) {
            const contentRelPath = toPosix(relative(this.contentDir, fullPath));
            const projectRelPath = toPosix(relative(this.projectDir, fullPath));
            results.push({ contentRelPath, projectRelPath });
          }
        }
      }
    };

    if (existsSync(this.contentDir)) {
      walk(this.contentDir, this.contentDir, CONTENT_SYNC_STAGING_SCOPE);
    }
    if (this.rootOkOutsideContentWalk) {
      const rootOkDir = join(this.projectDir, OK_DIR);
      if (
        existsSync(rootOkDir) &&
        !this.contentFilter.isDirExcluded(OK_DIR, PROJECT_SYNC_STAGING_SCOPE)
      ) {
        walk(rootOkDir, this.projectDir, PROJECT_SYNC_STAGING_SCOPE, failUnreadableOkSubtree);
      }
    }
    return results;
  }

  /**
   * The staging walk, HEAD deletion tracking, and the working-tree status surface must all answer
   * this identically — a path one admits and another refuses is precedent #55's failure mode (a
   * HEAD path the gather walk refuses gets committed as a spurious deletion every cycle).
   */
  isSyncScopedPath(projRelPath: string): boolean {
    const absPath = join(this.projectDir, projRelPath);
    const contentRelPath = toPosix(relative(this.contentDir, absPath));
    const inContentWalk =
      !contentRelPath.startsWith('..') &&
      !this.contentFilter.isExcluded(contentRelPath, CONTENT_SYNC_STAGING_SCOPE);
    const inRootOkWalk =
      this.rootOkOutsideContentWalk &&
      projRelPath.startsWith(`${OK_DIR}/`) &&
      !this.contentFilter.isExcluded(projRelPath, PROJECT_SYNC_STAGING_SCOPE);
    return inContentWalk || inRootOkWalk;
  }

  private async listHeadContentPaths(handle: GitHandle, headSha: string): Promise<Set<string>> {
    const paths = new Set<string>();
    try {
      const headPaths = await listNames(handle.git, ['ls-tree', '-r', '--name-only', headSha]);
      for (const projRelPath of headPaths) {
        if (this.isSyncScopedPath(projRelPath)) {
          paths.add(projRelPath);
        }
      }
    } catch {}
    return paths;
  }

  private async removePathsFromIndex(handle: GitHandle, paths: string[]): Promise<void> {
    if (paths.length === 0) return;
    const unique = [...new Set(paths)];
    const BATCH = 100;
    for (let i = 0; i < unique.length; i += BATCH) {
      const batch = unique.slice(i, i + BATCH);
      await handle.git.raw(['rm', '--cached', ...pathspecArgs(batch)]);
    }
  }

  private async snapshotPromisedPaths(): Promise<string[]> {
    let entries: PorcelainEntry[];
    let unmerged: ReadonlySet<string>;
    try {
      const { git } = this.gitHandle();
      entries = await listPorcelainEntries(git, PORCELAIN_STATUS_ARGS);
      unmerged = new Set(await listNames(git, ['diff', '--name-only', '--diff-filter=U']));
    } catch (e) {
      log.warn(
        { event: 'snapshot-read-failed', err: e, branch: this.currentBranch },
        '[sync] could not read the real index before the push cycle — skipping stale-index self-heal',
      );
      return [];
    }

    const paths: string[] = [];
    for (const entry of entries) {
      if (unmerged.has(entry.path)) continue;
      if (!this.isSyncScopedPath(entry.path)) continue;
      paths.push(entry.path);
      if (paths.length === PROMISED_PATHS_CAP) break;
    }
    return paths;
  }

  private async healStaleRealIndex(
    promisedPaths: string[],
    committedPaths: ReadonlySet<string>,
  ): Promise<void> {
    const promised = new Set(promisedPaths.filter((p) => !committedPaths.has(p)));
    if (promised.size === 0) return;

    if (this.hasGitOperationInProgress()) {
      log.warn(
        {
          event: 'self-heal-skipped-git-operation',
          branch: this.currentBranch,
          pathCount: promised.size,
          paths: [...promised].slice(0, LOGGED_PATHS_CAP),
        },
        '[sync] self-heal skipped — a Git operation now holds the tree, so the promised paths stay listed until it ends',
      );
      return;
    }

    const handle = this.gitHandle();
    let stagedAgainstHead: string[];
    let changedInWorktree: string[];
    try {
      const rows = await listNameStatus(handle.git, [
        'diff-index',
        '--cached',
        '--name-status',
        'HEAD',
      ]);
      stagedAgainstHead = rows.flatMap((row) =>
        row.status[0] === 'R' || row.status[0] === 'C' ? [row.from, row.to] : [row.to],
      );
      changedInWorktree = await listNames(handle.git, ['diff', '--name-only', 'HEAD']);
    } catch (e) {
      log.error(
        {
          event: 'self-heal-skipped',
          branch: this.currentBranch,
          pathCount: promised.size,
          paths: [...promised].slice(0, LOGGED_PATHS_CAP),
          err: e,
        },
        '[sync] self-heal could not compare the real index against HEAD — the promised paths stay listed in the real index',
      );
      return;
    }

    const worktreeDiffers = new Set(changedInWorktree);
    const healable = [
      ...new Set(stagedAgainstHead.filter((p) => promised.has(p) && !worktreeDiffers.has(p))),
    ];
    if (healable.length === 0) return;

    await this.resetRealIndexForPaths(healable, 'push', handle);
    log.warn(
      {
        event: 'self-heal-applied',
        branch: this.currentBranch,
        pathCount: healable.length,
        paths: healable.slice(0, LOGGED_PATHS_CAP),
      },
      '[sync] self-heal cleared stale real-index entries left behind by an earlier push cycle',
    );
  }

  private async resetRealIndexForPaths(
    paths: string[],
    op: IndexResetOp,
    handle?: GitHandle,
  ): Promise<void> {
    if (paths.length === 0) return;
    const realIndexHandle = handle ?? this.gitHandle();
    const unique = [...new Set(paths)];
    const BATCH = 100;
    for (let i = 0; i < unique.length; i += BATCH) {
      const batch = unique.slice(i, i + BATCH);
      await this.resetRealIndexBatch(realIndexHandle, batch, op);
    }
  }

  private async resetRealIndexBatch(
    handle: GitHandle,
    batch: string[],
    op: IndexResetOp,
  ): Promise<void> {
    let firstError: unknown;
    try {
      await handle.git.raw(['reset', 'HEAD', ...pathspecArgs(batch)]);
      return;
    } catch (e) {
      firstError = e;
    }

    let classified = classifyGitError(firstError);
    let finalError = firstError;
    let recovered = false;

    if (classified.class === 'local' && classified.subclass === 'index-lock') {
      await this.beforeRealIndexResetRetry?.();
      await sleepMs(jitteredMs(INDEX_RESET_RETRY_DELAY_SECONDS));
      try {
        await handle.git.raw(['reset', 'HEAD', ...pathspecArgs(batch)]);
        recovered = true;
      } catch (e) {
        finalError = e;
        classified = classifyGitError(e);
      }
    }

    const fields = {
      event: 'stale-index-reset',
      outcome: recovered ? 'recovered-on-retry' : 'failed',
      op,
      branch: this.currentBranch,
      pathCount: batch.length,
      paths: batch.slice(0, LOGGED_PATHS_CAP),
      errorClass: classified.class,
      errorSubclass: classified.subclass,
      err: finalError,
    };
    if (recovered) {
      log.warn(
        fields,
        '[sync] stale-index reset needed a second attempt — it succeeded, so the panel listing is current',
      );
    } else {
      log.error(fields, '[sync] stale-index reset failed — the panel listing may stay stale');
    }

    if (!recovered && classified.class === 'local' && classified.subclass === 'index-lock') {
      this.noteIndexLockEncountered(op, classified);
    }
  }

  private buildCommitMessage(contentRelPaths: string[]): string {
    if (contentRelPaths.length === 0) {
      return 'Auto-save: changes saved';
    }
    if (contentRelPaths.length <= 3) {
      return `Auto-save: Updated ${contentRelPaths.join(', ')}`;
    }
    return `Auto-save: ${contentRelPaths.length} files changed`;
  }

  private async handleMergeConflict(): Promise<void> {
    const handle = this.gitHandle();

    let conflictedFiles: string[] = [];
    try {
      conflictedFiles = await listNames(handle.git, ['diff', '--name-only', '--diff-filter=U']);
    } catch (e) {
      log.error(
        { err: e },
        '[sync] failed to list conflicted files — aborting merge to avoid committing unresolved state',
      );
      try {
        await handle.git.raw(['merge', '--abort']);
      } catch (abortErr) {
        log.warn({ err: abortErr }, '[sync] git merge --abort failed during cleanup');
      }
      this.pullErrorCode = undefined;
      this.pullError = 'Failed to detect conflict files — merge aborted';
      this.pausedReason = undefined;
      this.transitionTo('idle');
      return;
    }

    const contentConflicts: string[] = [];
    const nonContentConflicts: string[] = [];

    for (const file of conflictedFiles) {
      if (this.isContentConflictPath(file)) {
        contentConflicts.push(file);
      } else {
        nonContentConflicts.push(file);
      }
    }

    const nonContentResolveFailures: Array<{ file: string; err: unknown }> = [];
    const projectConfigRelPath = toPosix(
      relative(this.projectDir, resolveConfigPath('project', this.projectDir)),
    );
    for (const file of nonContentConflicts) {
      try {
        await handle.git.raw(['checkout', '--theirs', ...pathspecArgs([file])]);
        await handle.git.raw(['add', ...pathspecArgs([file])]);
        if (file.toLowerCase() === projectConfigRelPath.toLowerCase()) {
          log.warn(
            { file },
            '[sync] auto-resolved .ok/config.yml conflict with theirs: local project config edits were overwritten by the remote version',
          );
        } else {
          log.info({ file }, '[sync] auto-resolved non-content conflict with theirs');
        }
      } catch (e) {
        log.warn(
          { err: e, file },
          '[sync] non-content auto-resolve failed — will abort merge and pause sync',
        );
        nonContentResolveFailures.push({ file, err: e });
      }
    }

    if (nonContentResolveFailures.length > 0) {
      const failedFiles = nonContentResolveFailures.map((f) => f.file);
      try {
        await handle.git.raw(['merge', '--abort']);
      } catch (abortErr) {
        log.warn(
          { err: abortErr, files: failedFiles },
          '[sync] git merge --abort failed during non-content cleanup',
        );
      }
      const display = failedFiles.slice(0, 3).join(', ');
      const rest = failedFiles.length > 3 ? `, +${failedFiles.length - 3} more` : '';
      this.pullErrorCode = undefined;
      this.pullError = `Sync paused — couldn't auto-resolve ${display}${rest}. Resolve in your terminal (e.g. \`git rm <file>\` or \`git checkout --ours/--theirs <file> && git add <file>\`), then retry sync.`;
      this.pausedReason = 'non-content-merge-failure';
      this.consecutivePullFailures = 0;
      this.transitionTo('idle');
      this.scheduleSaveState();
      log.warn(
        { files: failedFiles },
        '[sync] non-content auto-resolve failed — merge aborted, sync paused',
      );
      return;
    }

    if (contentConflicts.length > 0) {
      for (const file of contentConflicts) {
        this.conflicts.raise({ kind: 'merge-native', file });
      }

      if (this.pullTimer !== null) {
        clearTimeout(this.pullTimer);
        this.pullTimer = null;
      }
      if (this.pushTimer !== null) {
        clearTimeout(this.pushTimer);
        this.pushTimer = null;
      }

      this.transitionTo('conflict');
      log.warn(
        { files: contentConflicts },
        '[sync] content conflicts — sync paused until resolved',
      );
    } else {
      let committed = false;
      try {
        await this.applyCommitIdentity(handle);
        await handle.git.raw(['commit', '--no-edit']);
        const gitDir = resolveGitDir(this.projectDir);
        committed = gitDir === null || !existsSync(join(gitDir, 'MERGE_HEAD'));
      } catch (e) {
        log.warn({ err: e }, '[sync] failed to commit after auto-resolving conflicts');
      }
      if (committed) {
        this.lastSyncUtc = new Date().toISOString();
        this.behind = 0;
        this.transitionTo('idle');
        log.info({}, '[sync] all conflicts auto-resolved — merge committed');
      } else {
        try {
          await handle.git.raw(['merge', '--abort']);
        } catch (abortErr) {
          log.warn({ err: abortErr }, '[sync] git merge --abort failed during cleanup');
        }
        this.pullError = 'Sync paused — could not finalize the merge. Retry sync to try again.';
        this.transitionTo('idle');
        log.warn(
          {},
          '[sync] could not finalize merge after auto-resolving conflicts — merge aborted',
        );
      }
    }
  }

  private clearPushError(): void {
    this.pushError = undefined;
    this.pushErrorCode = undefined;
  }

  private clearPullError(): void {
    this.pullError = undefined;
    this.pullErrorCode = undefined;
  }

  private handleError(classified: ClassifiedError, op: SyncCycleOp): void {
    if (classified.userFacingCode !== null) {
      if (op === 'push') {
        this.pushErrorCode = classified.userFacingCode;
        this.pushError = undefined;
      } else {
        this.pullErrorCode = classified.userFacingCode;
        this.pullError = undefined;
      }
    } else if (op === 'push') {
      this.pushErrorCode = undefined;
      this.pushError = classified.message;
    } else {
      this.pullErrorCode = undefined;
      this.pullError = classified.message;
    }
    log.warn(
      {
        class: classified.class,
        subclass: classified.subclass,
        retryable: classified.retryable,
        rawStderr: classified.rawStderr,
      },
      `[sync-error] ${classified.message}`,
    );

    if (classified.class === 'auth') {
      this.ghTokenSource.invalidate();
      this.ghAccountResolver.invalidate();
      this.transitionTo('auth-error');
      this.pausedReason = 'auth-error';
    } else if (classified.class === 'semantic' && classified.subclass === 'protected-branch') {
      this.mode = 'off';
      this.transitionTo('disabled');
      this.pausedReason = 'protected-branch';
      void this.onAutoDisable?.('protected-branch');
    } else if (classified.class === 'local' && classified.subclass === 'index-lock') {
      this.bumpFailureCount(op);
      if (this.state === 'pushing' || this.state === 'pulling' || this.state === 'fetching') {
        this.transitionTo('idle');
      }
      this.noteIndexLockEncountered(op, classified);
    } else if (classified.class === 'local' && classified.subclass === 'dirty-tree') {
      if (this.state === 'conflict' || this.conflictCount > 0) {
        this.transitionTo('conflict');
        return;
      }
      this.bumpFailureCount(op);
      this.transitionTo('idle');
      this.pausedReason = 'dirty-tree';
      this.schedulePush(0);
    } else if (classified.retryable) {
      this.bumpFailureCount(op, isFetchDisprovableFailure(classified));
      this.transitionTo('offline');
    } else {
      this.bumpFailureCount(op);
      this.transitionTo('idle');
    }
  }

  private otherLegInFlight(op: SyncCycleOp): boolean {
    return this.cycleInFlight !== null && this.cycleInFlight !== op;
  }

  private beginIndexLockWatch(op: SyncCycleOp): void {
    if (this.otherLegInFlight(op)) return;
    const alreadyLocked = this.pausedReason === 'git-index-locked';
    this.indexLockHitThisCycle = false;
    if (!alreadyLocked) this.lastLockNoticeKind = undefined;
    this.restingIndexLockPause = alreadyLocked ? undefined : this.pausedReason;
  }

  private holdsIndexLock(classified: ClassifiedError): boolean {
    return INDEX_LOCK_PATH_IN_STDERR.test(`${classified.message}\n${classified.rawStderr ?? ''}`);
  }

  private noteIndexLockEncountered(op: IndexResetOp, classified: ClassifiedError): void {
    const isIndexLock = this.holdsIndexLock(classified);
    const noticeKind = isIndexLock ? 'index-locked' : 'git-lock-held';
    if (this.lastLockNoticeKind !== noticeKind) {
      this.lastLockNoticeKind = noticeKind;
      const fields = {
        event: noticeKind,
        op,
        branch: this.currentBranch,
        errorClass: classified.class,
        errorSubclass: classified.subclass,
      };
      if (isIndexLock) {
        log.error(
          fields,
          '[sync] index locked — another program is holding .git/index.lock, so sync cannot update it',
        );
      } else {
        log.error(
          fields,
          '[sync] a git lock file blocked the operation — the held lock is not .git/index.lock, so the listing is not paused on it',
        );
      }
    }
    if (!isIndexLock) return;
    this.indexLockHitThisCycle = true;
    if (this.pausedReason === 'git-index-locked') return;
    this.pausedReason = 'git-index-locked';
    this.cc1Broadcaster?.signal('sync-status');
  }

  private noteUnbornHeadRefusal(): void {
    if (this.pausedReason !== 'no-commits-yet') {
      log.error(
        { event: 'unborn-head-refusal', branch: this.currentBranch },
        '[sync] push refused — this repository has no commits yet, so there is nothing to send',
      );
    }
    this.pausedReason = 'no-commits-yet';
    this.cc1Broadcaster?.signal('sync-status');
  }

  private clearUnbornHeadPause(): void {
    if (this.pausedReason !== 'no-commits-yet') return;
    this.pausedReason = undefined;
    this.cc1Broadcaster?.signal('sync-status');
  }

  private settleIndexLockPause(op: SyncCycleOp): void {
    if (this.otherLegInFlight(op)) return;
    if (this.indexLockHitThisCycle) return;
    if (this.pausedReason !== 'git-index-locked') return;
    this.pausedReason = this.restingIndexLockPause;
    this.cc1Broadcaster?.signal('sync-status');
  }

  private currentState(): SyncState {
    return this.state;
  }

  private markRun(): void {
    this.lastPushOkUtc = new Date().toISOString();
    this.saveStateNow();
    this.cc1Broadcaster?.signal('sync-status');
  }

  private transitionTo(newState: SyncState): void {
    if (this.state === newState) return;
    const prev = this.state;
    this.state = newState;
    log.info({ from: prev, to: newState }, `[sync] state: ${prev} → ${newState}`);
    this.onStateChange?.(newState);
    this.cc1Broadcaster?.signal('sync-status');
  }

  private scheduleSaveState(): void {
    if (this.stateSaveTimer !== null) return;
    this.stateSaveTimer = setTimeout(() => {
      this.stateSaveTimer = null;
      this.saveStateNow();
    }, 5_000);
  }

  private saveStateNow(): void {
    if (this.stateSaveTimer !== null) {
      clearTimeout(this.stateSaveTimer);
      this.stateSaveTimer = null;
    }
    try {
      const persistedReason = NON_PERSISTED_PAUSES.has(this.pausedReason)
        ? undefined
        : this.pausedReason;
      const data: PersistedSyncState = {
        version: 1,
        lastSyncUtc: this.lastSyncUtc,
        lastPullOkUtc: this.lastPullOkUtc,
        lastPushOkUtc: this.lastPushOkUtc,
        lastFetchUtc: this.lastFetchUtc,
        lastPushedSha: this.lastPushedSha,
        consecutiveFailures: this.consecutivePullFailures,
        consecutivePushFailures: this.consecutivePushFailures,
        pushStreakIsConnectivity: this.pushStreakIsConnectivity,
        pausedReason: persistedReason,
        pausedSinceUtc: persistedReason ? new Date().toISOString() : undefined,
      };
      const tmpStatePath = `${this.statePath}.tmp`;
      tracedWriteFileSync(tmpStatePath, JSON.stringify(data, null, 2), 'utf-8');
      tracedRenameSync(tmpStatePath, this.statePath);
    } catch (e) {
      log.warn({ err: e }, '[sync] failed to persist sync state');
    }
  }

  private loadState(): void {
    if (!existsSync(this.statePath)) return;
    try {
      const raw = readFileSync(this.statePath, 'utf-8');
      const data = JSON.parse(raw) as Partial<PersistedSyncState>;
      if (data.version !== 1) return;
      this.lastSyncUtc = data.lastSyncUtc ?? null;
      this.lastPullOkUtc = data.lastPullOkUtc ?? null;
      this.lastPushOkUtc = data.lastPushOkUtc ?? null;
      this.lastFetchUtc = data.lastFetchUtc ?? null;
      this.lastPushedSha = data.lastPushedSha ?? null;
      this.consecutivePullFailures = data.consecutiveFailures ?? 0;
      this.consecutivePushFailures = data.consecutivePushFailures ?? 0;
      this.pushStreakIsConnectivity = data.pushStreakIsConnectivity ?? false;
      const rawReason = typeof data.pausedReason === 'string' ? data.pausedReason : undefined;
      const storedReason =
        rawReason !== undefined && isSyncPausedReason(rawReason) ? rawReason : undefined;
      if (rawReason !== undefined && storedReason === undefined && rawReason.length > 0) {
        log.warn(
          { event: 'paused-reason-unrecognized', pausedReason: rawReason },
          '[sync] persisted pause reason is not one this build knows — dropping it and continuing without a pause',
        );
      }
      this.pausedReason = NON_RESTORED_PAUSES.has(storedReason) ? undefined : storedReason;
    } catch (e) {
      log.warn({ err: e }, '[sync] failed to load sync state');
    }
  }
}