Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

228 KB
Raw Blame
import { type SpawnSyncReturns, spawnSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import {
  accessSync,
  existsSync,
  constants as fsConstants,
  lstatSync,
  readFileSync,
  realpathSync,
  statSync,
  writeFileSync,
} from 'node:fs';
import { homedir } from 'node:os';
import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
import type { Document, Extension } from '@hocuspocus/server';
import { Hocuspocus, IncomingMessage, MessageType } from '@hocuspocus/server';
import {
  type BasenameIndex,
  CONFIG_DOC_NAME_OKIGNORE,
  CONFIG_DOC_NAME_PROJECT,
  CONFIG_DOC_NAME_PROJECT_LOCAL,
  CONFIG_DOC_NAME_USER,
  CONFIG_DOC_NAMES,
  type ConfigDiagnosticsReport,
  type ConfigDocName,
  type ConfigIssue,
  createBasenameIndex,
  DEFAULT_ATTACHMENT_FOLDER_PATH,
  DEFAULT_LINKS_VALIDATION,
  DEFAULT_LINTER_CONFIG,
  DEFAULT_SIGTERM_GRACE_MS,
  DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
  DOCUMENT_OPEN_BYTE_LIMIT,
  humanFormat,
  isKnownConfigError,
  type LinterConfig,
  type MarkdownManager,
  modeFromCommittedDefault,
  type PersistedLinterConfig,
  type Principal,
  parseGlobalSkillBundleDoc,
  parseManagedArtifactName,
  resolveAutoSyncIntervals,
  resolveLocalAutoSyncMode,
  type SyncMode,
  type SyncModeChangeSource,
  toEffectiveBase,
} from '@inkeep/open-knowledge-core';
import {
  atomicWriteFile,
  collectConfigDiagnostics,
  readConfigSafely,
  resolveConfigPath,
  writeConfigPatch,
} from '@inkeep/open-knowledge-core/server';
import {
  type CheckpointKind,
  formatReconcileSubject,
  gitAuthorWriterId,
  resolveGitDir,
  resolveShadowDir,
} from '@inkeep/open-knowledge-core/shadow-repo-layout';
import simpleGit from 'simple-git';
import type { Doc } from 'yjs';
import { AcpPermissionStore } from './acp/permissions.ts';
import { AcpRegistry, loadCustomAgents } from './acp/registry.ts';
import { AgentFocusBroadcaster } from './agent-focus.ts';
import { AgentPresenceBroadcaster } from './agent-presence.ts';
import type { AgentRegistryHostSeam } from './agent-registry-apply.ts';
import { AgentSessionManager } from './agent-sessions.ts';
import { type CommentDocHooks, createApiExtension, isSafeDocName } from './api-extension.ts';
import { assetReferencesChanged } from './asset-references.ts';
import { seedBasenameIndex, seedSingleDirBasenameIndex } from './asset-walk.ts';
import {
  HocuspocusAuthRejection,
  type HocuspocusAuthRejectionReason,
  parseHocuspocusAuthToken,
} from './auth-token-schema.ts';
import { bootElapsedMs, recordBootPhase, setBootField } from './boot-timings.ts';
import {
  type BridgeDeriveLossReporter,
  createBridgeDeriveLossReporter,
} from './bridge-loss-detector.ts';
import {
  CC1Broadcaster,
  isConfigDoc,
  isEditableTextDoc,
  isExcalidrawDoc,
  isManagedArtifactDoc,
  isMermaidDoc,
  isPersistenceExcludedDoc,
  isReservedForUserTree,
  SYSTEM_DOC_NAME,
} from './cc1-broadcast.ts';
import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';
import { getLocalDir } from './config/paths.ts';
import {
  type ConfigFileWatcherUnsubscribe,
  startConfigFileWatcher,
  startMultiPathConfigFileWatcher,
} from './config-file-watcher.ts';
import {
  applyExternalConfigChange,
  configDocAbsPath,
  isConfigEcho,
  resetConfigDocForTest,
} from './config-persistence.ts';
import { bindConflictAuthority, ConflictAuthority } from './conflict-authority.ts';
import { createGeneratedIndexWarningScope } from './content/generate-index.ts';
import { type GeneratedArtifactEnv, writeGeneratedArtifact } from './content/generated-artifact.ts';
import {
  type GeneratedIndexGitAttributesStatus,
  inspectGeneratedIndexGitAttributes,
  updateGeneratedIndexGitAttributes,
} from './content/generated-index-git-attributes.ts';
import {
  collectIndexDirectories,
  directoryChainToRoot,
  directoryOf,
  indexedFieldsChanged,
  indexedMetadataChanged,
  isGeneratedIndexDocName,
  type PreviousIndexedFields,
  planDirectoryIndexRegenerations,
  ROOT_INDEX_DOC_NAME,
} from './content/regenerate-index.ts';
import {
  type ContentFilter,
  createContentFilter,
  isShareableOkArtifact,
} from './content-filter.ts';
import { isWithinContentDir, safeContentPath } from './content-path.ts';
import { dropPendingDocs, recordContributor } from './contributor-tracker.ts';
import {
  DerivedDocumentIndex,
  type DerivedDocumentIndexBranchTransition,
} from './derived-document-index.ts';
import { resolveDirectoryRoot } from './directory-root.ts';
import { applyDiskContentToDoc } from './disk-content-intake.ts';
import { DiskReceiptLog, receiptFileIsGoneIn } from './disk-receipts.ts';
import { displayPathFor } from './display-path.ts';
import {
  canonicalDocName,
  docNameToRelativePath,
  getDocExtension,
  isRegisteredMarkdownDocName,
  stripDocExtension,
} from './doc-extensions.ts';
import { runDocLineageGuard } from './doc-lineage-guard.ts';
import { DocNoticeLedger, type NoticeFile } from './doc-notices.ts';
import {
  DocumentDurabilityState,
  type StaleExternalWriteConflict,
  type StoreIntakeMerge,
  type WrittenThrough,
  writtenThroughOf,
} from './document-durability-state.ts';
import {
  createReconnectRefreshExtension,
  type DocumentRefreshResult,
  type DocumentRefreshTrigger,
} from './document-refresh.ts';
import {
  type Embedder,
  type EmbeddingsKeyStore,
  type LoadOpenAiEmbedderInput,
  loadOpenAiEmbedder,
  normalizeProviderId,
  type ResolvedSemanticConfig,
  readProjectLocalSemanticConfig,
  SemanticSearchService,
  secretsFilePath,
} from './embeddings/index.ts';
import {
  applyExternalChange,
  FILE_WATCHER_ORIGIN,
  type FrozenResidentRevival,
  redactedErrorSummary,
  refuseStaleExternalWrite,
  reportReconcileBothKept,
  reportReconcileCheckFailed,
  reportReconcileKeptLive,
  reviveFrozenResidentDoc,
  serializeYDocSource,
  wireReasonForRefusal,
} from './external-change.ts';
import {
  assertNeverDiskEvent,
  contentHash,
  type DiskEvent,
  getMarkdownEventFacts,
  getMarkdownRemovalCurrentness,
  hasAdmittedMarkdownFile,
  type NativeWatcherBackend,
  pathToDocName,
  type RecheckResult,
  reconcileFileIndexAfterFilterRebuild,
  registerRemoval,
  registerWrite,
  retractRemoval,
  startWatcher,
  type WatcherHandle,
} from './file-watcher.ts';
import { canonicalContentPathIsRefused, SymlinkEscapeError } from './fs-safety.ts';
import {
  normalizeFsPath,
  tracedMkdirSync,
  tracedUnlinkSync,
  tracedWriteFileSync,
} from './fs-traced.ts';
import { createGitInstance } from './git-handle.ts';
import type {
  CheckPushPermissionOptions,
  DetectGhAccountsFn,
  DetectGhFn,
  ProbeTokenStore,
  PushPermission,
} from './github-permissions.ts';
import { createGitHubTokenResolver } from './github-reference/token-resolver.ts';
import { type HeadWatcherHandle, readProjectHeadState, startHeadWatcher } from './head-watcher.ts';
import { errnoCode } from './http/handler-utils.ts';
import type { NativeApiHandle } from './http/http-app.ts';
import type { LocalApiDispatch } from './http/local-api-dispatch.ts';
import type { GeneratedIndexSettingsStatus } from './http/workspace-tools-routes.ts';
import {
  scanGlobalInPlaceSkillsAsync,
  scanInPlaceSkillDirs,
  scanInPlaceSkills,
  skillRootPathsFor,
} from './in-place-skills.ts';
import {
  buildIngressPolicy,
  type IngressPolicy,
  isHostAdmitted,
  isPeerAdmitted,
} from './ingress-policy.ts';
import type { LinkAdvisoryPolicy } from './link-advisory-policy.ts';
import { ensureOkfSchemaFiles } from './lint/write-okf-schemas.ts';
import { createLiveDerivedIndexExtension } from './live-derived-index.ts';
import { wikiFilePath } from './local-target-assessment.ts';
import {
  createTrackedFileResolver,
  createTrackedWikiFileResolver,
  localTargetInventoryFromWatcher,
} from './local-target-inventory.ts';
import { getLogger } from './logger.ts';
import { LossCaptureRing } from './loss-capture.ts';
import {
  createMaintenanceCoordinator,
  type MaintenanceCoordinator,
} from './maintenance-coordinator.ts';
import {
  applyExternalManagedArtifactChange,
  homeFor,
  managedArtifactAbsPath,
  managedArtifactDocNameForPath,
  managedArtifactSkillsRoots,
} from './managed-artifact-persistence.ts';
import { startManagedArtifactWatcher } from './managed-artifact-watcher.ts';
import { recoverPendingManagedRename } from './managed-rename-journal.ts';
import type { NativeTomlMcpEditor } from './mcp-config-reconciler.ts';
import { mdManager, schema } from './md-manager.ts';
import { createMergeHistoryRecorder, type MergeHistoryWriter } from './merge-history.ts';
import { applyExternalEnginelessChange } from './mermaid-persistence.ts';
import {
  incrementBatch,
  incrementBranchSwitch,
  incrementBranchSwitchRecheckShortfalls,
  incrementConflict,
  incrementDiskAuthoritativeIngest,
  incrementDiskAuthoritativeIngestApplyFailures,
  incrementDiskAuthoritativeIngestUnrescued,
  incrementOutsideRenameClaimFailures,
  incrementOutsideRenameRecordFailures,
  incrementPark,
  incrementReceiptIntakeSkip,
  incrementRecentlyRemovedDocsEviction,
  incrementReconcile,
  incrementReconcileInsertDedupSkipped,
  incrementRescueBuffer,
  incrementRescueBufferWriteFailures,
  incrementRescueCheckpointWriteFailures,
  incrementUpstreamImport,
  recordVanishOutcome,
  setRecentlyRemovedDocsSize,
} from './metrics.ts';
import { destroyParsePool } from './parse-pool.ts';
import { isWithinDir, toPosix } from './path-utils.ts';
import { createPersistenceExtension, type PersistenceOptions } from './persistence.ts';
import {
  createPersistenceStalenessWatchdog,
  type StalenessWatchdogHandle,
  StructuralDiskReadError,
} from './persistence-staleness-watchdog.ts';
import { loadPrincipal } from './principal.ts';
import { createPrivateSkillTrustAdmission } from './private-skill-trust-admission.ts';
import { RecentlyRemovedDocs } from './recently-removed-docs.ts';
import { type ReconcileOutcome, reconcile } from './reconciliation.ts';
import { reconcileRecoveredFileTarget } from './recovered-file-target.ts';
import { runRemovalRedirectGuard } from './removal-redirect-guard.ts';
import { loadRemovedDocsJournal, saveRemovedDocsJournal } from './removed-docs-journal.ts';
import {
  gcRenameLog,
  getOrLoadRenameLogIndex,
  loadRenameLogIndex,
  setRenameLogIndex,
  sweepLazyPopOrphans,
} from './rename-log.ts';
import { followRenameRecords } from './rename-records.ts';
import {
  acquireServerAuthority,
  contentScopeContainsPath,
  ServerAuthorityCollisionError,
} from './server-authority.ts';
import {
  assertCapturedServerContentPath,
  assertServerContentPath,
  assertServerContentSubtree,
  ContentScopeAdmissionError,
  canonicalContentPath,
  contentScopedAtomicFs,
  ServerMutationShuttingDownError,
  snapshotServerContentScope,
} from './server-content-policy.ts';
import {
  acquireServerLock,
  markServerLockDraining,
  readServerLock,
  releaseServerLock,
  ServerLockCollisionError,
} from './server-lock.ts';
import { createServerObserverExtension } from './server-observer-extension.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
import {
  installServerWorkloadGauges,
  registerAgentSessionCountsProvider,
  registerConnectionCountsProvider,
  registerLoadedDocsProvider,
  registerPersistenceQueueDepthProvider,
} from './server-workload-telemetry.ts';
import { AttachmentFolderPathConfigError } from './services/assets.ts';
import { shadowOpGateFor } from './shadow-op-gate.ts';
import {
  buildWipTree,
  commitUpstreamImport,
  configureShadowGc,
  destroyShadowRepo,
  FILE_SYSTEM_WRITER,
  initShadowRepo,
  isShadowExcludesDegraded,
  OK_GENERATOR_WRITER,
  type ParkableDoc,
  parkBranch,
  SERVICE_WRITER,
  type ShadowHandle,
  type ShadowRef,
  safetyCheckpoint,
  saveInMemoryCheckpoint,
  shadowGit,
} from './shadow-repo.ts';
import {
  createSyncCredentialConfigResolver,
  readDeclaredGitHubHosts,
} from './share/git-context.ts';
import { resyncRecordedSkillCopies } from './skill-placements.ts';
import { skillStateYamlPath } from './skill-state.ts';
import { assertCompatibleStateManifest } from './state-manifest.ts';
import { classifyIntakeAgainstReceipt, receiptIntakeSkipOf } from './store-compare.ts';
import { assertRealpathWithinDir } from './symlink-guard.ts';
import { SyncEngine } from './sync-engine.ts';
import { createSyncHandshakeSpanExtension } from './sync-handshake-span-extension.ts';
import { initTelemetry, shutdownTelemetry, withSpan } from './telemetry.ts';
import { trustSystemCertificates } from './trust-system-ca.ts';
import { cleanupOrphanUploadTempfiles } from './upload-streaming.ts';
import {
  type RecentCreate,
  VANISH_HOLD_LIMIT_MS,
  VANISH_OVERDUE_FAULT_LIMIT,
  VANISH_RECHECK_DELAY_MS,
  type VanishedDocument,
  VanishedDocuments,
} from './vanished-documents.ts';
import { type WatcherClock, type WatcherTimer, watcherClock } from './watcher-clock.ts';
import { FRESHNESS_BASE_INTERVAL_MS } from './watcher-freshness.ts';

export interface ServerOptions {
  acpRegistryFetchImpl?: typeof fetch;
  ingressPolicy?: IngressPolicy;
  port?: number;
  host?: string;
  contentDir: string;
  projectDir?: string;
  quiet?: boolean;
  debounce?: number;
  maxDebounce?: number;
  stalenessGraceMs?: number;
  stalenessSweepIntervalMs?: number;
  agentSessionOptions?: {
    maxSessions?: number;
    minEvictableIdleMs?: number;
  };
  gitEnabled?: boolean;
  mcpTomlEditor?: NativeTomlMcpEditor;
  commitDebounceMs?: number;
  wipRef?: string;
  enableTestRoutes?: boolean;
  getCollabClientCount?: () => number;
  shadowRepo?: ShadowHandle;
  contentRoot?: string;
  destroyTimeoutMs?: number;
  authorityRegistryPath?: string;
  onAgentWrite?: () => void;
  localOpCliArgs?: string[];
  authStreamHeartbeatMs?: number;
  lockKind?: 'interactive' | 'mcp-spawned';
  capabilities?: string[];
  skipStateManifestCheck?: boolean;
  configHomedirOverride?: string;
  mdManager?: MarkdownManager;
  detectGh?: DetectGhFn;
  agentIntegrations?: AgentRegistryHostSeam;
  detectGhAccounts?: DetectGhAccountsFn;
  tokenStore?: ProbeTokenStore | null;
  checkPushPermissionFn?: (opts: CheckPushPermissionOptions) => Promise<PushPermission>;
  pullIntervalSeconds?: number;
  pushIntervalSeconds?: number;
  embeddingsKeyStore?: EmbeddingsKeyStore | null;
  embedderLoader?: (input: LoadOpenAiEmbedderInput) => Promise<Embedder | null>;
  singleDocRelPath?: string;
  ephemeral?: boolean;
  watcherBackend?: NativeWatcherBackend;
  watcherClock?: WatcherClock;
  freshnessIntervalMs?: number | null;
  mergeHistoryWriter?: MergeHistoryWriter;
  generatedIndexTestHooks?: {
    beforePlan?: (context: { fullSweep: boolean; signal: AbortSignal }) => Promise<void> | void;
    beforeDecision?: (context: {
      directory: string;
      fullSweep: boolean;
      signal: AbortSignal;
    }) => Promise<void> | void;
    afterWrite?: (context: {
      docName: string;
      fullSweep: boolean;
      signal: AbortSignal;
    }) => Promise<void> | void;
    onKickWhileInFlight?: () => void;
    onIdle?: () => void;
  };
}

type GeneratedIndexSweepResult =
  | { status: 'completed'; indexCount: number }
  | { status: 'disabled'; indexCount: number }
  | { status: 'blocked'; indexCount: number }
  | { status: 'failed'; indexCount: number }
  | { status: 'cancelled'; indexCount: number };

export interface ServerInstance {
  hocuspocus: Hocuspocus;
  sessionManager: AgentSessionManager;
  nativeApi: NativeApiHandle;
  localApi: LocalApiDispatch;
  cc1Broadcaster: CC1Broadcaster;
  agentFocusBroadcaster: AgentFocusBroadcaster;
  agentPresenceBroadcaster: AgentPresenceBroadcaster;
  maintenanceCoordinator?: MaintenanceCoordinator;
  contentFilter: ContentFilter;
  basenameIndex: BasenameIndex;
  readonly serverInstanceId: string;
  readonly durabilityState: DocumentDurabilityState;
  destroy: () => Promise<void>;
  ready: Promise<void>;
  generatedIndexSweepReady: Promise<GeneratedIndexSweepResult>;
  readonly degraded: readonly string[];
  readonly lockDir: string;
  readonly syncEngine: SyncEngine | null;
  readonly conflicts: ConflictAuthority;
  readonly getLinkPreviewsEnabled: () => boolean;
  readonly resolveEmbed: (basename: string, sourcePath: string) => string | null;
  readonly resolveTrackedFile: (relativePath: string) => string | undefined;
  readonly acpRegistry: AcpRegistry;
  readonly acpPermissions: AcpPermissionStore;
  readonly recheckDisk: () => Promise<RecheckResult>;
}

export function observeShutdownDocumentRetirements(
  hocuspocus: Hocuspocus,
  onDocumentRetired: () => void,
): () => void {
  let active = true;
  const observer: Extension = {
    async afterUnloadDocument() {
      if (active) onDocumentRetired();
    },
  };
  hocuspocus.configuration.extensions.unshift(observer);
  return () => {
    active = false;
    const extensions = hocuspocus.configuration.extensions;
    const index = extensions.indexOf(observer);
    if (index !== -1) extensions.splice(index, 1);
  };
}

export const SHADOW_FANOUT_WARMUP_MS = 3000;

export const BRANCH_SWITCH_FOLLOW_UP_LIMIT = 3;

export const BRANCH_SWITCH_FOLLOW_UP_DELAY_MS = 5_000;

const PARK_SNAPSHOT_ORIGIN = (() => {
  const ctx = Object.freeze({ origin: 'park-snapshot', paired: true as const });
  return Object.freeze({
    source: 'local' as const,
    skipStoreHooks: false,
    context: ctx,
  }) satisfies PairedWriteOrigin;
})();

const GENERATED_ARTIFACT_ORIGIN = (() => {
  const ctx = Object.freeze({ origin: 'generated-index', paired: true as const });
  return Object.freeze({
    source: 'local' as const,
    skipStoreHooks: false,
    context: ctx,
  }) satisfies PairedWriteOrigin;
})();

export interface UpstreamAuthor {
  name: string;
  email: string;
}

export function resolveUpstreamChanges(
  projectDir: string,
  contentDir: string,
  oldHead: string | null,
  newHead: string,
): Map<string, UpstreamAuthor> {
  const changes = new Map<string, UpstreamAuthor>();
  if (!oldHead) return changes;
  let result: SpawnSyncReturns<string>;
  try {
    result = spawnSync(
      'git',
      [
        '-c',
        'core.quotePath=false',
        'log',
        `${oldHead}..${newHead}`,
        '--no-merges',
        '--name-only',
        '--format=C%x00%an%x00%ae',
      ],
      withHiddenWindowsConsole({ cwd: projectDir, encoding: 'utf-8', timeout: 5000 }),
    );
  } catch (err) {
    getLogger('upstream-attribution').warn(
      { err, oldHead, newHead },
      'git log spawn threw; upstream docs keep file-system attribution',
    );
    return changes;
  }
  if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
    getLogger('upstream-attribution').warn(
      {
        err: result.error,
        status: result.status,
        signal: result.signal,
        stderr: typeof result.stderr === 'string' ? result.stderr.slice(0, 500) : undefined,
        oldHead,
        newHead,
      },
      'git log failed; upstream docs keep file-system attribution',
    );
    return changes;
  }

  let current: UpstreamAuthor | null = null;
  for (const rawLine of result.stdout.split('\n')) {
    const line = rawLine.trim();
    if (line === '') continue;
    if (line.startsWith('C\0')) {
      const [, name, email] = line.split('\0');
      current = name && email ? { name, email } : null;
      continue;
    }
    if (!current) continue;
    if (!line.endsWith('.md') && !line.endsWith('.mdx')) continue;
    const abs = resolve(projectDir, line);
    if (!isWithinContentDir(abs, contentDir)) continue;
    const docName = pathToDocName(abs, contentDir);
    if (changes.has(docName)) continue;
    if (!existsSync(abs)) continue;
    changes.set(docName, current);
  }
  return changes;
}

export function createServer(options: ServerOptions): ServerInstance {
  trustSystemCertificates();
  const ingressPolicy = options.ingressPolicy ?? buildIngressPolicy({});
  const {
    contentDir,
    projectDir = contentDir,
    quiet = true,
    debounce = 2000,
    maxDebounce = 10000,
    gitEnabled = true,
    commitDebounceMs = 30_000,
    wipRef = 'refs/wip/main',
    configHomedirOverride,
    enableTestRoutes = false,
    shadowRepo,
    contentRoot,
    destroyTimeoutMs = 10_000,
    localOpCliArgs,
    authStreamHeartbeatMs,
    skipStateManifestCheck = false,
    singleDocRelPath,
    ephemeral = false,
  } = options;
  const canonicalContentDir = resolveDirectoryRoot(contentDir, {
    root: 'content',
    component: 'server-factory',
  });
  const declaredGitHubHosts = readDeclaredGitHubHosts(configHomedirOverride);
  const resolveSyncCredentialConfig = createSyncCredentialConfigResolver({
    projectDir,
    tokenStore: options.tokenStore,
    localOpCliArgs,
    declaredGitHubHosts,
  });

  const log = getLogger('server');
  let headWatcher: HeadWatcherHandle | null = null;
  const getStorageBranch = () => headWatcher?.getLastKnownBranch() ?? null;
  const getReportedBranch = () =>
    headWatcher ? headWatcher.getLastKnownBranch() : readProjectHeadState(projectDir).branch;
  const generatedIndexWarningScope = createGeneratedIndexWarningScope(resolve(contentDir));
  let cc1Broadcaster: CC1Broadcaster | null = null;
  const initialBranch = readProjectHeadState(projectDir).branch ?? 'main';
  const diskReceipts = new DiskReceiptLog({
    path: join(getLocalDir(projectDir), 'receipts.jsonl'),
  });
  const receiptFileIsGone = receiptFileIsGoneIn(contentDir);
  const durabilityState = new DocumentDurabilityState(initialBranch, {
    persistencePath: join(getLocalDir(projectDir), 'stale-external-writes.json'),
    receipts: diskReceipts,
    onStaleExternalWriteChange: () => {
      cc1Broadcaster?.signal('sync-status');
      hydrateStaleExternalWrites();
    },
    onStoreRefused: (docName) => {
      if (rescueDocToShadowBuffer(docName, 'refused-store-mark') === 'lost') {
        log.warn(
          { docName },
          `[rescue] refused-store content for ${docName} was not durably buffered at refusal time`,
        );
      }
    },
    fileForDocName: (docName) =>
      relative(projectDir, safeContentPath(docName, contentDir)).replaceAll('\\', '/'),
    hasResolvedExtension: isRegisteredMarkdownDocName,
  });
  const getActiveBranch = () => durabilityState.getActiveBranch();
  const getReconciledBase = (docName: string) => durabilityState.getReconciledBase(docName);
  const setReconciledBase = (docName: string, content: string) =>
    durabilityState.setReconciledBase(docName, content);
  const deleteReconciledBase = (docName: string) => durabilityState.deleteReconciledBase(docName);
  const switchReconciledBaseScope = (branch: string) =>
    durabilityState.switchReconciledBaseScope(branch);
  const vanishedDocuments = new VanishedDocuments();
  const holdBatch = (owner: string): void => durabilityState.holdBatch(owner);
  const releaseBatchHold = (owner: string): boolean => durabilityState.releaseBatch(owner);
  const finishBatch = async (): Promise<void> => {
    try {
      await drainEventBuffer();
    } finally {
      disposeBufferedRemovalScopes();
    }
    await persistence.flushDeferredStores('within-branch');
  };
  const batchFlagFor =
    (owner: string) =>
    (value: boolean): void => {
      if (value) {
        holdBatch(owner);
        return;
      }
      if (!releaseBatchHold(owner)) return;
      void finishBatch().catch((err: unknown) => {
        log.error({ err, owner }, '[batch] draining after the batch failed');
      });
    };
  const isBatchInProgress = () => durabilityState.isBatchInProgress();

  const conflicts = new ConflictAuthority({
    projectDir,
    contentDir,
    assertResolutionPath: assertConflictContentPath,
    branch: initialBranch,
    signal: { signal: (channel) => cc1Broadcaster?.signal(channel) },
    io: {
      gitRaw: async (args) =>
        createGitInstance(projectDir, { credentialConfig: [], timeoutMs: 30_000 }).git.raw(args),
      writeProjectFileUntracked: (absPath, bytes) => {
        assertConflictContentPath(absPath);
        tracedWriteFileSync(absPath, bytes, 'utf-8');
      },
      unlinkProjectFileUndeclared: (absPath) => {
        assertConflictContentPath(absPath);
        tracedUnlinkSync(absPath);
      },
      deleteResolvedContent: (docName, absPath) => {
        assertContentPath(absPath);
        const declaration = registerRemoval(absPath);
        try {
          tracedUnlinkSync(absPath);
        } catch (cause) {
          retractRemoval(declaration);
          throw cause;
        }
        contentFilter.decrementMdDir(dirname(docName));
        commentDocHooksRef.current?.deleted(docName);
      },
      applyResolvedContent: async (docName, absPath, bytes) => {
        assertContentPath(absPath);
        const absent = !existsSync(absPath);
        registerWrite(absPath, contentHash(bytes));
        await atomicWriteFile(absPath, bytes, { fs: scopedAtomicFs });
        if (absent) contentFilter.incrementMdDir(dirname(docName));
        if (hocuspocus.documents.get(docName)) applyToDoc(docName, bytes);
        setReconciledBase(docName, bytes);
        await derivedDocumentIndex.recordDiskUpsert(docName, bytes);
      },
      readLiveContent: (docName) => serializeDoc(docName),
      finalizeReconcileResolution: async (entry, strategy, docName) => {
        let priorStaleExternalWrite:
          | { conflict: StaleExternalWriteConflict; branch: string }
          | undefined;
        if (entry.reason === 'stale-external-write') {
          const conflict = durabilityState.getStaleExternalWrite(docName);
          if (conflict) {
            priorStaleExternalWrite = { conflict, branch: durabilityState.getActiveBranch() };
          }
          if (strategy === 'mine' || strategy === 'content') {
            durabilityState.recordDisplacedVersion(docName, entry.stages.theirs);
          } else {
            durabilityState.clearDisplacedVersions(docName);
          }
          durabilityState.clearStaleExternalWrite(docName);
        }
        if (strategy === 'delete' && hasAdmittedMarkdownBinding(docName)) {
          log.debug(
            { docName, source: 'resolve-delete', bindingRecreated: true },
            `[reconcile] delete skipped: ${docName} (binding recreated)`,
          );
          return;
        }
        const document = hocuspocus.documents.get(docName);
        const lifecycle = document?.getMap('lifecycle');
        if (strategy === 'delete') {
          const removal = beginRemoval(docName);
          try {
            const isDirty =
              removal.residentCurrent() && document
                ? rescueUnflushedEditsBeforeTeardown(
                    docName,
                    headWatcher?.getLastKnownBranch() ?? 'main',
                    'delete',
                    true,
                  )
                : false;
            if (removal.namespaceCurrent()) {
              commentDocHooksRef.current?.deleted(docName);
              await derivedDocumentIndex.recordDiskDelete(docName);
            }
            if (!removal.namespaceCurrent() && !removal.residentCurrent()) {
              log.debug(
                {
                  docName,
                  source: 'resolve-delete',
                  namespaceCurrent: false,
                  residentCurrent: false,
                },
                `[reconcile] delete skipped: ${docName} (stale removal)`,
              );
              return;
            }
            log.info(
              { docName, isDirty, source: 'resolve-delete' },
              `[reconcile] delete: ${docName} (dirty=${isDirty})`,
            );
            const priorLifecycle = lifecycle
              ? {
                  status: lifecycle.get('status'),
                  reason: lifecycle.get('reason'),
                  detectedAt: lifecycle.get('detectedAt'),
                }
              : undefined;
            if (document && removal.residentCurrent()) {
              lifecycle?.set('status', 'deleted-upstream');
              lifecycle?.delete('reason');
              lifecycle?.delete('detectedAt');
              try {
                hocuspocus.closeConnections(docName);
                await forceUnloadDocument(document, removal.residentCurrent);
              } catch (cause) {
                if (removal.residentCurrent() && lifecycle && priorLifecycle) {
                  for (const [key, value] of Object.entries(priorLifecycle)) {
                    if (value === undefined) lifecycle.delete(key);
                    else lifecycle.set(key, value);
                  }
                }
                if (removal.namespaceCurrent() && priorStaleExternalWrite) {
                  try {
                    durabilityState.restoreStaleExternalWrite(
                      priorStaleExternalWrite.conflict,
                      priorStaleExternalWrite.branch,
                    );
                  } catch (rollbackFailure) {
                    log.error(
                      { err: rollbackFailure, docName },
                      `[reconcile] stale-external-write rollback failed for ${docName}; the retry may not find the conflict`,
                    );
                  }
                }
                throw cause;
              }
            }
            if (!removal.namespaceCurrent()) {
              log.debug(
                {
                  docName,
                  source: 'resolve-delete',
                  namespaceCurrent: false,
                  residentCurrent: removal.residentCurrent(),
                },
                `[reconcile] delete: ${docName} not recorded as removed (stale removal)`,
              );
              return;
            }
            deleteReconciledBase(docName);
            onUpstreamDelete(docName);
            scheduleIndexRegenerationAfterRemoval(docName);
            console.info(
              JSON.stringify({
                event: 'recently-removed-docs-populate',
                docName,
                kind: 'deleted',
                source: 'resolve-delete',
              }),
            );
          } finally {
            removal.dispose();
          }
        } else if (lifecycle?.get('reason') === entry.reason) {
          lifecycle.delete('status');
          lifecycle.delete('reason');
          lifecycle.delete('detectedAt');
        }
        signalChannel('files');
      },
    },
  });

  function hydrateStaleExternalWrites(): void {
    for (const stale of durabilityState.listStaleExternalWrites()) {
      const base = getReconciledBase(stale.docName) ?? stale.diskContent;
      conflicts.raise({
        kind: 'reconcile',
        file: stale.file,
        reason: 'stale-external-write',
        detectedAt: stale.detectedAt,
        stages: {
          base,
          ours: stale.retainedContent ?? base,
          theirs: stale.diskContent,
        },
      });
    }
  }
  hydrateStaleExternalWrites();

  function readProjectAttachmentFolderPath(options?: { requireValid?: boolean }): string {
    const project = readConfigSafely({
      absPath: resolveConfigPath('project', projectDir),
      sideline: false,
      warn: (message) => log.warn({ message }, '[config] could not read project config'),
    });
    if (!project.valid) {
      const attachmentIssues =
        isKnownConfigError(project.error) && project.error.code === 'SCHEMA_INVALID'
          ? (project.error.issues as ConfigIssue[]).filter(
              (issue) => issue.path.map(String).join('.') === 'content.attachmentFolderPath',
            )
          : [];
      if (attachmentIssues.length > 0) {
        throw new AttachmentFolderPathConfigError(attachmentIssues.map((issue) => issue.message));
      }
      if (options?.requireValid) {
        throw new Error('Project config is invalid', { cause: project.error });
      }
      log.warn(
        {},
        '[config] committed content.attachmentFolderPath unavailable (project config invalid) — using default attachment placement',
      );
    }
    return project.value.content.attachmentFolderPath ?? DEFAULT_ATTACHMENT_FOLDER_PATH;
  }

  function readProjectAutoSyncMode(): { mode: SyncMode; source: SyncModeChangeSource } {
    const local = readConfigSafely({
      absPath: resolveConfigPath('project-local', projectDir),
      sideline: false,
      warn: (message) => log.warn({ message }, '[config] could not read project-local config'),
    });
    const localMode = resolveLocalAutoSyncMode(local.value.autoSync);
    if (localMode !== null) {
      return { mode: localMode, source: 'config' };
    }
    if (!local.valid) {
      log.warn(
        {},
        '[config] project-local autoSync.mode unavailable (config invalid) — falling back to the committed project default',
      );
    }
    const project = readConfigSafely({
      absPath: resolveConfigPath('project', projectDir),
      sideline: false,
      warn: (message) => log.warn({ message }, '[config] could not read project config'),
    });
    if (!project.valid) {
      log.warn(
        {},
        '[config] committed autoSync.default unavailable (project config invalid) — defaulting to disabled',
      );
    }
    return {
      mode: modeFromCommittedDefault(project.value.autoSync?.default) ?? 'off',
      source: 'committed-default',
    };
  }

  function readProjectAutoSyncIntervals(): {
    pullIntervalSeconds: number;
    pushIntervalSeconds: number;
  } {
    const local = readConfigSafely({
      absPath: resolveConfigPath('project-local', projectDir),
      sideline: false,
      warn: (message) => log.warn({ message }, '[config] could not read project-local config'),
    });
    return resolveAutoSyncIntervals(local.value.autoSync);
  }

  function readLinterBaseConfig(): LinterConfig {
    const project = readConfigSafely({
      absPath: resolveConfigPath('project', projectDir),
      sideline: false,
      warn: (message) => log.warn({ message }, '[config] could not read project config for linter'),
    });
    const persisted = project.value.contentRules as PersistedLinterConfig | undefined;
    const base = persisted ? toEffectiveBase(persisted) : DEFAULT_LINTER_CONFIG;
    ensureOkfSchemaFiles(projectDir, base.plugins.okf);
    return base;
  }

  function readLinkAdvisoryPolicy(): LinkAdvisoryPolicy {
    const project = readConfigSafely({
      absPath: resolveConfigPath('project', projectDir),
      sideline: false,
      warn: (message) =>
        log.warn({ message }, '[config] could not read project config for link validation'),
    });
    return {
      links: project.value.validation?.links ?? DEFAULT_LINKS_VALIDATION,
      suppressLogLinkAdvisories:
        project.value.validation?.suppressLogLinkAdvisories ?? DEFAULT_SUPPRESS_LOG_LINK_ADVISORIES,
    };
  }

  function readSemanticSearchConfig(): ResolvedSemanticConfig {
    return readProjectLocalSemanticConfig(projectDir, {
      configHomedirOverride,
      onWarn: (message) => log.warn({ message }, '[config] could not read project-local config'),
    });
  }

  function readLinkPreviewsEnabled(): boolean {
    const local = readConfigSafely({
      absPath: resolveConfigPath('project-local', projectDir, configHomedirOverride),
      sideline: false,
      warn: (message) => log.warn({ message }, '[config] could not read project-local config'),
    });
    if (!local.valid) return false;
    return local.value.linkPreviews?.enabled === true;
  }

  function readConfigDiagnostics(): ConfigDiagnosticsReport {
    return collectConfigDiagnostics({
      cwd: projectDir,
      homedirOverride: configHomedirOverride,
      warn: (message) => log.debug({ message }, '[config] diagnostics read'),
    });
  }

  function logConfigDiagnostics(configDocName?: string): void {
    const configDocNamesByScope = {
      user: CONFIG_DOC_NAME_USER,
      project: CONFIG_DOC_NAME_PROJECT,
      'project-local': CONFIG_DOC_NAME_PROJECT_LOCAL,
    };
    for (const finding of readConfigDiagnostics().diagnostics) {
      if (configDocName !== undefined && configDocNamesByScope[finding.scope] !== configDocName) {
        continue;
      }
      if (finding.code === 'VALUE_FALLBACK') {
        for (const issue of finding.issues) {
          log.warn(
            {
              code: finding.code,
              scope: finding.scope,
              file: finding.file,
              path: issue.path.join('.'),
              line: issue.line,
              column: issue.column,
            },
            `[config] ${issue.path.join('.')}: ${issue.message}`,
          );
        }
        continue;
      }
      if (finding.code !== 'REMOVED_KEY') continue;
      log.warn(
        { scope: finding.scope, file: finding.file, path: finding.path.join('.') },
        `[config] ${finding.path.join('.')} is no longer read and was ignored. ${finding.redirect}`,
      );
    }
  }

  function semanticProviderFingerprint(cfg: ResolvedSemanticConfig): string {
    return `${normalizeProviderId(cfg.baseUrl)}|${cfg.model}|${cfg.dimensions ?? 'auto'}`;
  }

  function semanticTransportFingerprint(cfg: ResolvedSemanticConfig): string {
    return `${cfg.maxBatchSize}|${cfg.maxBatchChars}|${cfg.docTimeoutMs}`;
  }

  let lastAppliedAttachmentFolderPath: string | undefined;
  let projectConfigEpoch = 0;

  function applyPersistedConfigToConsumers(
    configDocName: string,
    generatedIndexEnabledOverride?: boolean,
  ): void {
    let appliedAutoSyncMode: SyncMode | undefined;
    if (
      configDocName === CONFIG_DOC_NAME_PROJECT ||
      configDocName === CONFIG_DOC_NAME_PROJECT_LOCAL
    ) {
      const resolved = readProjectAutoSyncMode();
      appliedAutoSyncMode = resolved.mode;
      void syncEngine?.setMode(resolved.mode, resolved.source).catch((err) => {
        log.warn(
          { err, mode: resolved.mode, docName: configDocName },
          '[sync] failed to apply autoSync mode from config',
        );
      });
      const intervals = readProjectAutoSyncIntervals();
      syncEngine?.setIntervals(intervals.pullIntervalSeconds, intervals.pushIntervalSeconds);
    }
    const semCfg = readSemanticSearchConfig();
    semanticSearch.applyConfig({
      enabled: semCfg.enabled,
      providerFingerprint: semanticProviderFingerprint(semCfg),
      transportFingerprint: semanticTransportFingerprint(semCfg),
      maxBatchSize: semCfg.maxBatchSize,
    });
    if (configDocName === CONFIG_DOC_NAME_PROJECT) {
      projectConfigEpoch += 1;
      try {
        const nextAttachmentFolderPath = readProjectAttachmentFolderPath({ requireValid: true });
        contentFilter?.setAttachmentFolderPath(nextAttachmentFolderPath);
        if (
          lastAppliedAttachmentFolderPath !== undefined &&
          nextAttachmentFolderPath !== lastAppliedAttachmentFolderPath
        ) {
          log.warn(
            { previous: lastAppliedAttachmentFolderPath, next: nextAttachmentFolderPath },
            '[content-filter] attachment folder changed — files under the previous folder no longer sync',
          );
        }
        lastAppliedAttachmentFolderPath = nextAttachmentFolderPath;
      } catch (err) {
        log.warn(
          { err },
          '[content-filter] project config invalid — keeping previous attachment admission',
        );
      }
      cc1Broadcaster?.signal('lint-config');
      const generatedIndexEnabled =
        generatedIndexEnabledOverride ??
        readLinterBaseConfig().plugins.okf?.generate?.index === true;
      if (!generatedIndexEnabled) {
        void updateGeneratedIndexGitAttributes({
          projectDir,
          contentDir,
          generatedDocNames: generatedIndexDocNamesForGitAttributes(),
          enabled: false,
        }).then((result) => {
          if (!result.ok) {
            log.warn(
              { state: result.status.state },
              '[index] could not remove Open Knowledge generated-index Git attributes',
            );
          }
        });
      }
      scheduleFullIndexSweep();
    }
    log.info(
      {
        docName: configDocName,
        autoSyncMode: appliedAutoSyncMode,
        semanticEnabled: semCfg.enabled,
      },
      '[config] applied persisted config to in-process consumers',
    );
  }

  initTelemetry();

  const serverInstanceId = randomUUID();
  let authorityRetired = false;
  let documentAdmissionClosed = false;
  let authorityScope = snapshotServerContentScope(contentDir, singleDocRelPath);
  const assertContentPath = (path: string): void => {
    if (authorityRetired) throw new ServerMutationShuttingDownError(false);
    assertServerContentPath(authorityScope, path);
  };
  const assertContentSubtree = (path: string): void => {
    assertContentPath(path);
    assertServerContentSubtree(authorityScope, path);
  };
  const scopedAtomicFs = contentScopedAtomicFs(assertContentPath);
  function assertConflictContentPath(path: string): void {
    assertRealpathWithinDir(path, projectDir, { allowShareableOkArtifact: isShareableOkArtifact });
    const canonical = canonicalContentPath(path);
    const projectPath = toPosix(relative(canonicalContentPath(projectDir), canonical));
    if (
      authorityScope.kind === 'tree' &&
      !contentScopeContainsPath(
        { kind: 'tree', path: authorityScope.path, excluded: [] },
        canonical,
      ) &&
      isShareableOkArtifact(projectPath)
    )
      return;
    assertContentPath(canonical);
  }

  const lockDir = getLocalDir(projectDir);

  const acpRegistry = new AcpRegistry({
    localDir: lockDir,
    log: getLogger('acp-registry'),
    fetchImpl: options.acpRegistryFetchImpl,
  });
  const acpPermissions = new AcpPermissionStore(lockDir, getLogger('acp-permissions'));

  let authority: ReturnType<typeof acquireServerAuthority>;
  try {
    authority = acquireServerAuthority({
      scope: authorityScope,
      projectDir: canonicalContentPath(projectDir),
      serverInstanceId,
      registryPath: options.authorityRegistryPath,
    });
  } catch (error) {
    if (
      error instanceof ServerAuthorityCollisionError &&
      error.existing.projectDir === canonicalContentPath(projectDir)
    ) {
      const existing = readServerLock(lockDir);
      if (existing?.pid === error.existing.pid) {
        throw new ServerLockCollisionError(existing, join(lockDir, 'server.lock'));
      }
    }
    throw error;
  }
  authorityScope = authority.scope;
  let primaryLockAcquired = false;
  try {
    acquireServerLock(lockDir, {
      port: 0,
      worktreeRoot: projectDir,
      kind: options.lockKind ?? 'interactive',
      capabilities: options.capabilities ?? ['http', 'ws'],
    });
    primaryLockAcquired = true;
    if (!skipStateManifestCheck) {
      assertCompatibleStateManifest({
        lockDir,
        shadowRepoDir: resolveShadowDir(projectDir),
      });
    }
  } catch (error) {
    if (primaryLockAcquired) releaseServerLock(lockDir);
    try {
      authority.release();
    } catch (cleanupError) {
      log.error({ err: cleanupError }, '[server] startup authority release failed');
    }
    throw error;
  }

  const basenameIndex: BasenameIndex = createBasenameIndex();

  const resolveTrackedFile = createTrackedFileResolver(() =>
    localTargetInventoryFromWatcher(watcher, contentDir),
  );
  const resolveTrackedWikiFile = createTrackedWikiFileResolver(() =>
    localTargetInventoryFromWatcher(watcher, contentDir),
  );

  const resolveEmbed = (target: string, sourcePath: string): string | null => {
    const wikiPath = wikiFilePath(target);
    if (wikiPath === null || !wikiPath.includes('/')) {
      return basenameIndex.resolveEmbed(target, sourcePath);
    }
    return resolveTrackedWikiFile(wikiPath) ?? null;
  };

  const resolveSize = (basename: string, sourcePath: string): number | null => {
    let candidatePath: string | null = resolveEmbed(basename, sourcePath);
    if (!candidatePath && basename.includes('/')) {
      candidatePath = basename.replace(/^\.?\//, '');
    }
    if (!candidatePath) return null;
    const fullPath = resolve(contentDir, candidatePath);
    const contentDirAbs = resolve(contentDir);
    if (!isWithinDir(fullPath, contentDirAbs)) {
      return null;
    }
    try {
      const stat = statSync(fullPath);
      return stat.isFile() ? stat.size : null;
    } catch {
      return null;
    }
  };

  let contentFilter: ReturnType<typeof createContentFilter>;
  let derivedDocumentIndex: DerivedDocumentIndex;
  let shadowRef: ShadowRef;
  let maintenanceCoordinator: MaintenanceCoordinator | undefined;
  let persistence: ReturnType<typeof createPersistenceExtension>;
  let lossRing: LossCaptureRing | undefined;
  let hocuspocus: Hocuspocus;
  let sessionManager: AgentSessionManager;
  let nativeApi: NativeApiHandle;
  let localApi: LocalApiDispatch;
  let shutdownLocalOps: () => Promise<void>;
  let bridgeLossReporter: BridgeDeriveLossReporter | undefined;
  let inPlaceRescanTimer: ReturnType<typeof setTimeout> | null = null;
  let shadowWarmupTimer: ReturnType<typeof setTimeout> | null = null;
  const IN_PLACE_RESCAN_DEBOUNCE_MS = 500;
  let agentFocusBroadcaster: AgentFocusBroadcaster | null = null;
  let agentPresenceBroadcaster: AgentPresenceBroadcaster | null = null;
  let invalidateReferencedAssetsCache: (() => void) | null = null;
  let stalenessWatchdog: StalenessWatchdogHandle | null = null;

  const initialSemanticConfig = readSemanticSearchConfig();
  const semanticSearch = new SemanticSearchService({
    loadEmbedder: () => {
      const cfg = readSemanticSearchConfig();
      const input: LoadOpenAiEmbedderInput = {
        keyStore: options.embeddingsKeyStore ?? null,
        projectDir,
        config: { baseUrl: cfg.baseUrl, model: cfg.model, dimensions: cfg.dimensions },
        options: {
          maxBatchSize: cfg.maxBatchSize,
          maxBatchChars: cfg.maxBatchChars,
          docTimeoutMs: cfg.docTimeoutMs,
        },
      };
      return (options.embedderLoader ?? loadOpenAiEmbedder)(input);
    },
    cacheDir: join(getLocalDir(projectDir), 'embeddings'),
    enabled: initialSemanticConfig.enabled,
    providerFingerprint: semanticProviderFingerprint(initialSemanticConfig),
    transportFingerprint: semanticTransportFingerprint(initialSemanticConfig),
    maxBatchSize: initialSemanticConfig.maxBatchSize,
  });

  let loadedPrincipal: Principal | null = null;
  const forceUnloadRequests = new Map<Document, Set<() => boolean>>();
  let shutdownAllowsUnload = false;
  const unregisterWorkloadProviders: Array<() => void> = [];
  let forceUnloadDocument!: (document: Document, isCurrent?: () => boolean) => Promise<void>;
  let defaultShouldUnloadDocument!: (document: Document) => boolean;

  const {
    promise: ready,
    resolve: resolveReady,
    reject: rejectReady,
  } = Promise.withResolvers<void>();
  let readyForNotices = false;
  void ready.then(
    () => {
      readyForNotices = true;
    },
    () => {},
  );
  const noticeDisplayPath = (abs: string): string =>
    displayPathFor(abs, projectDir, configHomedirOverride ?? homedir());
  let heldSaveProbe: (docName: string) => boolean = () => true;
  const noticeFileOutsideContent = (docName: string): NoticeFile | null => {
    let abs: string;
    try {
      if (isConfigDoc(docName)) abs = configDocAbsPath(docName, persistence.configPersistenceCtx);
      else if (isManagedArtifactDoc(docName)) {
        abs = managedArtifactAbsPath(docName, persistence.managedArtifactCtx);
      } else return null;
    } catch (err) {
      log.debug(
        { err, docName },
        '[doc-notices] no file to name for a notice outside the content folder',
      );
      return null;
    }
    return { abs, display: noticeDisplayPath(abs) };
  };
  const docNotices = new DocNoticeLedger({
    projectDir,
    contentDir,
    getShadow: () => shadowRef?.current,
    isReady: () => readyForNotices,
    signal: () => cc1Broadcaster?.signal('sync-status'),
    isHeld: (docName) => vanishedDocuments.has(docName),
    isSaveHeld: (docName) => heldSaveProbe(docName),
    resolveFile: noticeFileOutsideContent,
  });
  const mergeHistory = createMergeHistoryRecorder({
    getShadow: () => shadowRef?.current,
    contentRoot: contentRoot ?? '',
    getBranch: getStorageBranch,
    writeCheckpoint: options.mergeHistoryWriter,
    notices: docNotices,
  });
  const offlineRemovalsReconciled = Promise.withResolvers<void>();

  const { promise: branchScopeAligned, resolve: resolveBranchScopeAligned } =
    Promise.withResolvers<void>();

  const BRANCH_SCOPE_GATE_TIMEOUT_MS = 10_000;

  async function resolveBranchForClaimCheck(): Promise<string | null> {
    let timer: ReturnType<typeof setTimeout> | undefined;
    const expired = Symbol('branch-scope-gate-timeout');
    const timeout = new Promise<typeof expired>((res) => {
      timer = setTimeout(() => res(expired), BRANCH_SCOPE_GATE_TIMEOUT_MS);
      timer.unref?.();
    });
    try {
      const outcome = await Promise.race([branchScopeAligned, timeout]);
      if (outcome !== expired) return getActiveBranch();
    } finally {
      if (timer) clearTimeout(timer);
    }
    try {
      return readProjectHeadState(projectDir).branch ?? null;
    } catch (err) {
      log.warn(
        { err },
        '[auth] branch scope gate expired and HEAD is unreadable — skipping the branch claim check',
      );
      return null;
    }
  }

  function signalChannel(
    channel:
      | 'files'
      | 'backlinks'
      | 'graph'
      | 'tags'
      | 'comments'
      | 'lint-config'
      | 'local-targets',
  ): void {
    cc1Broadcaster?.signal(channel);
  }

  const INDEX_REGENERATION_DEBOUNCE_MS = 500;
  let indexRegenerationTimer: NodeJS.Timeout | undefined;
  let indexRegenerationImmediate: NodeJS.Immediate | undefined;
  let indexRegenerationInFlight: Promise<void> | undefined;
  let indexRegenerationReady = false;
  let indexRegenerationClosed = false;
  const indexRegenerationAbort = new AbortController();
  const pendingIndexDirectories = new Set<string>();
  let pendingIndexFullSweep = false;
  let pendingBootIndexSweep = false;

  let generatedIndexSweepSettled = false;
  let generatedIndexBootSweepCount = 0;
  const { promise: generatedIndexSweepReady, resolve: resolveGeneratedIndexSweep } =
    Promise.withResolvers<GeneratedIndexSweepResult>();

  function settleGeneratedIndexSweep(result: GeneratedIndexSweepResult): void {
    if (generatedIndexSweepSettled) return;
    generatedIndexSweepSettled = true;
    resolveGeneratedIndexSweep(result);
  }

  type IndexRegenerationRequest =
    | { fullSweep: true }
    | { fullSweep: false; directories: ReadonlySet<string> };

  type IndexRegenerationPassResult =
    | GeneratedIndexSweepResult
    | { status: 'deferred'; indexCount: number };

  function hasPendingIndexRegeneration(): boolean {
    return pendingIndexFullSweep || pendingIndexDirectories.size > 0;
  }

  function armIndexRegeneration(): void {
    if (indexRegenerationClosed || !indexRegenerationReady) return;
    if (indexRegenerationTimer !== undefined) clearTimeout(indexRegenerationTimer);
    indexRegenerationTimer = setTimeout(() => {
      indexRegenerationTimer = undefined;
      kickIndexRegeneration();
    }, INDEX_REGENERATION_DEBOUNCE_MS);
    indexRegenerationTimer.unref?.();
  }

  function deferBootIndexSweep(): void {
    if (indexRegenerationClosed) {
      settleGeneratedIndexSweep({ status: 'cancelled', indexCount: 0 });
      return;
    }
    pendingIndexFullSweep = true;
    pendingBootIndexSweep = true;
    indexRegenerationImmediate = setImmediate(() => {
      indexRegenerationImmediate = undefined;
      kickIndexRegeneration();
    });
  }

  let shadowHousekeepingImmediate: NodeJS.Immediate | undefined;
  let shadowHousekeepingInFlight: Promise<void> | undefined;
  let shadowHousekeepingClosed = false;
  let bootRenameLogIndex: ReturnType<typeof loadRenameLogIndex> | null = null;

  async function runShadowHousekeeping(): Promise<void> {
    const shadow = shadowRef.current;
    if (!shadow || shadowHousekeepingClosed) return;
    const startedAtMono = performance.now();
    log.info({ gitDir: shadow.gitDir }, '[shadow-housekeeping] deferred boot housekeeping started');
    try {
      await configureShadowGc(shadow);
    } catch (e) {
      log.warn({ err: e }, 'failed to write gc config (non-fatal)');
    }
    if (shadowHousekeepingClosed) return;
    if (bootRenameLogIndex) {
      try {
        const RETRY_BUDGET = 30;
        const retryIntervalMs =
          Number.parseInt(process.env.OK_BOOT_RENAME_GC_RETRY_INTERVAL_MS ?? '', 10) || 1_000;
        let rebuilt = false;
        for (let attempt = 0; attempt < RETRY_BUDGET; attempt++) {
          const gc = await gcRenameLog(shadow, bootRenameLogIndex, { rebuild: true });
          if (!gc.skipped) {
            rebuilt = true;
            break;
          }
          if (attempt === RETRY_BUDGET - 1) break;
          await new Promise((r) => {
            setTimeout(r, retryIntervalMs).unref?.();
          });
          if (shadowHousekeepingClosed) return;
        }
        if (!rebuilt) {
          log.warn(
            { gitDir: shadow.gitDir },
            '[rename-log] deferred boot GC/rebuild retry budget exhausted (persistent GC contention); rebuild deferred to next boot',
          );
        }
      } catch (e) {
        log.warn(
          { err: e, gitDir: shadow.gitDir },
          '[rename-log] deferred boot GC/rebuild failed; index loaded without GC',
        );
      }
    }
    if (shadowHousekeepingClosed) return;
    try {
      await maintenanceCoordinator?.runBootMaintenance();
    } catch (e) {
      log.warn({ err: e }, '[shadow-maintenance] boot maintenance failed (non-fatal)');
    }
    log.info(
      { gitDir: shadow.gitDir, durationMs: Math.round(performance.now() - startedAtMono) },
      '[shadow-housekeeping] deferred boot housekeeping complete',
    );
  }

  function deferShadowHousekeeping(): void {
    if (shadowHousekeepingClosed) return;
    shadowHousekeepingImmediate = setImmediate(() => {
      shadowHousekeepingImmediate = undefined;
      shadowHousekeepingInFlight = runShadowHousekeeping().catch((err) => {
        log.error({ err }, '[shadow-housekeeping] unexpected uncaught failure');
      });
    });
  }

  async function closeShadowHousekeeping(): Promise<void> {
    shadowHousekeepingClosed = true;
    if (shadowHousekeepingImmediate !== undefined) {
      clearImmediate(shadowHousekeepingImmediate);
      shadowHousekeepingImmediate = undefined;
    }
    if (!shadowHousekeepingInFlight) return;
    let timer: ReturnType<typeof setTimeout> | undefined;
    const timedOut = new Promise<'timeout'>((r) => {
      timer = setTimeout(() => r('timeout'), destroyTimeoutMs);
    });
    try {
      const outcome = await Promise.race([shadowHousekeepingInFlight, timedOut]);
      if (outcome === 'timeout') {
        throw new Error(
          `shadow housekeeping drain timed out after ${destroyTimeoutMs}ms — abandoning in-flight housekeeping`,
        );
      }
    } finally {
      if (timer !== undefined) clearTimeout(timer);
    }
  }

  function kickIndexRegeneration(): void {
    if (indexRegenerationClosed || !indexRegenerationReady || !hasPendingIndexRegeneration()) {
      return;
    }
    if (indexRegenerationInFlight !== undefined) {
      options.generatedIndexTestHooks?.onKickWhileInFlight?.();
      return;
    }
    if (durabilityState.isBatchInProgress()) {
      armIndexRegeneration();
      return;
    }

    const fullSweep = pendingIndexFullSweep;
    const directories = new Set(pendingIndexDirectories);
    const includesBootSweep = pendingBootIndexSweep;
    pendingIndexFullSweep = false;
    pendingIndexDirectories.clear();
    pendingBootIndexSweep = false;
    const request: IndexRegenerationRequest = fullSweep
      ? { fullSweep: true }
      : { fullSweep: false, directories };

    indexRegenerationInFlight = (async () => {
      const result = await regenerateIndexes(request, indexRegenerationAbort.signal);
      if (result.status === 'deferred') {
        pendingIndexFullSweep = true;
        if (includesBootSweep) {
          generatedIndexBootSweepCount += result.indexCount;
          pendingBootIndexSweep = true;
        }
        return;
      }
      if (includesBootSweep) {
        generatedIndexBootSweepCount += result.indexCount;
        if (result.status === 'completed' && hasPendingIndexRegeneration()) {
          pendingBootIndexSweep = true;
        } else {
          settleGeneratedIndexSweep({ ...result, indexCount: generatedIndexBootSweepCount });
        }
      }
    })()
      .catch((err: unknown) => {
        log.warn({ err }, '[index] index regeneration coordinator failed');
        if (includesBootSweep) settleGeneratedIndexSweep({ status: 'failed', indexCount: 0 });
      })
      .finally(() => {
        indexRegenerationInFlight = undefined;
        if (indexRegenerationClosed) {
          if (includesBootSweep) {
            settleGeneratedIndexSweep({ status: 'cancelled', indexCount: 0 });
          }
          return;
        }
        if (hasPendingIndexRegeneration() && indexRegenerationTimer === undefined) {
          armIndexRegeneration();
        } else if (!hasPendingIndexRegeneration() && indexRegenerationTimer === undefined) {
          options.generatedIndexTestHooks?.onIdle?.();
        }
      });
  }

  async function closeIndexRegeneration(): Promise<void> {
    if (!indexRegenerationClosed) {
      const inFlight = indexRegenerationInFlight;
      indexRegenerationClosed = true;
      indexRegenerationAbort.abort();
      if (indexRegenerationTimer !== undefined) {
        clearTimeout(indexRegenerationTimer);
        indexRegenerationTimer = undefined;
      }
      if (indexRegenerationImmediate !== undefined) {
        clearImmediate(indexRegenerationImmediate);
        indexRegenerationImmediate = undefined;
      }
      pendingIndexDirectories.clear();
      pendingIndexFullSweep = false;
      pendingBootIndexSweep = false;
      if (inFlight === undefined) {
        settleGeneratedIndexSweep({ status: 'cancelled', indexCount: 0 });
      }
    }
    await indexRegenerationInFlight;
  }

  function scheduleIndexRegeneration(docName: string): void {
    if (indexRegenerationClosed || isGeneratedIndexDocName(docName)) return;
    pendingIndexDirectories.add(directoryOf(docName));
    armIndexRegeneration();
  }

  function scheduleSubdirectoryIndexRegeneration(directory: string): void {
    if (indexRegenerationClosed) return;
    for (const ancestor of directoryChainToRoot(directory)) {
      pendingIndexDirectories.add(ancestor);
    }
    armIndexRegeneration();
  }

  function scheduleIndexRegenerationAfterRemoval(docName: string): void {
    const fileIndex = watcher?.getFileIndex();
    if (!fileIndex) {
      scheduleIndexRegeneration(docName);
      return;
    }

    const sourceDirectory = directoryOf(docName);
    const desiredDirectories = collectIndexDirectories(fileIndex.keys());
    if (desiredDirectories.has(sourceDirectory)) {
      scheduleIndexRegeneration(docName);
      return;
    }

    scheduleSubdirectoryIndexRegeneration(directoryOf(sourceDirectory));
  }

  function scheduleFullIndexSweep(): void {
    if (indexRegenerationClosed) return;
    pendingIndexFullSweep = true;
    armIndexRegeneration();
  }

  function currentIndexedFields(docName: string): PreviousIndexedFields | undefined {
    const entry = watcher?.getFileIndex().get(docName);
    if (!entry) return undefined;
    return { title: entry.title, description: entry.description, type: entry.type };
  }

  let generatedAttributionPending = false;
  const generatedArtifactEnv: GeneratedArtifactEnv = {
    origin: GENERATED_ARTIFACT_ORIGIN,
    writer: OK_GENERATOR_WRITER,
    isConflict: (docName) => conflicts.has(docName),
    getDocument: (docName) => hocuspocus.documents.get(docName),
    writeDisk: async (absPath, markdown) => {
      assertContentPath(absPath);
      tracedMkdirSync(dirname(absPath), { recursive: true });
      await atomicWriteFile(absPath, markdown, { fs: scopedAtomicFs });
    },
    registerWrite: (absPath, markdown) => registerWrite(absPath, contentHash(markdown)),
    noteFileIndex: (event) =>
      watcher?.mutateFileIndex({
        kind: event.kind,
        path: event.absPath,
        docName: event.docName,
        content: event.markdown,
      }),
    signalFiles: () => signalChannel('files'),
    attribute: async (docName, writer) => {
      recordContributor(docName, writer.id, writer.name, writer.id);
      generatedAttributionPending = true;
    },
  };

  function indexDocNameFor(directory: string): string {
    return directory === '' ? ROOT_INDEX_DOC_NAME : `${directory}/${ROOT_INDEX_DOC_NAME}`;
  }

  function generatedIndexDocNamesForGitAttributes(): string[] {
    const directories = watcher
      ? collectIndexDirectories(watcher.getFileIndex().keys())
      : new Set<string>(['']);
    return [...directories].map(indexDocNameFor);
  }

  function toGeneratedIndexSettingsStatus(
    git: GeneratedIndexGitAttributesStatus,
  ): GeneratedIndexSettingsStatus {
    const enabled = readLinterBaseConfig().plugins.okf?.generate?.index === true;
    const admitted = git.state === 'ready' || git.state === 'not-applicable';
    return {
      enabled,
      active: enabled && admitted,
      git:
        git.state === 'ready'
          ? { state: git.state, ownership: git.ownership }
          : { state: git.state },
    };
  }

  function getGeneratedIndexSettingsStatus(): GeneratedIndexSettingsStatus {
    return toGeneratedIndexSettingsStatus(
      inspectGeneratedIndexGitAttributes({
        projectDir,
        contentDir,
        generatedDocNames: generatedIndexDocNamesForGitAttributes(),
      }),
    );
  }

  async function setGeneratedIndexEnabled(enabled: boolean): Promise<GeneratedIndexSettingsStatus> {
    const attributes = await updateGeneratedIndexGitAttributes({
      projectDir,
      contentDir,
      generatedDocNames: generatedIndexDocNamesForGitAttributes(),
      enabled,
    });
    if (!attributes.ok) {
      return {
        ...getGeneratedIndexSettingsStatus(),
        applied: false,
        reason: attributes.status.state === 'conflict' ? 'git-conflict' : 'git-unavailable',
      };
    }

    const configResult = await writeConfigPatch({
      cwd: projectDir,
      scope: 'project',
      patch: { contentRules: { okf: { generate: { index: enabled } } } },
    });
    if (!configResult.ok) {
      try {
        await attributes.rollback();
      } catch (err) {
        log.error({ err }, '[index] could not roll back generated-index Git attributes');
      }
      return { ...getGeneratedIndexSettingsStatus(), applied: false, reason: 'config-write' };
    }

    try {
      const content = readFileSync(configResult.path, 'utf-8');
      await applyExternalConfigChange(
        hocuspocus.documents.get(CONFIG_DOC_NAME_PROJECT) ?? null,
        CONFIG_DOC_NAME_PROJECT,
        content,
        persistence.configPersistenceCtx,
      );
    } catch (err) {
      log.warn({ err }, '[index] generated-index settings reflection deferred to config watcher');
    }
    applyPersistedConfigToConsumers(CONFIG_DOC_NAME_PROJECT, enabled);
    logConfigDiagnostics(CONFIG_DOC_NAME_PROJECT);
    return { ...getGeneratedIndexSettingsStatus(), applied: true };
  }

  async function regenerateIndexes(
    request: IndexRegenerationRequest,
    signal: AbortSignal,
  ): Promise<IndexRegenerationPassResult> {
    let generatedIndexCount = 0;
    const sweepStartedAt = request.fullSweep ? performance.now() : undefined;
    const generationIsDisabled = () => readLinterBaseConfig().plugins.okf?.generate?.index !== true;
    try {
      if (signal.aborted) return { status: 'cancelled', indexCount: 0 };
      if (generationIsDisabled()) {
        return { status: 'disabled', indexCount: 0 };
      }

      const fileIndex = watcher?.getFileIndex();
      if (!fileIndex) return { status: 'failed', indexCount: 0 };

      try {
        await options.generatedIndexTestHooks?.beforePlan?.({
          fullSweep: request.fullSweep,
          signal,
        });
        if (signal.aborted) return { status: 'cancelled', indexCount: generatedIndexCount };
        if (generationIsDisabled()) {
          return { status: 'disabled', indexCount: generatedIndexCount };
        }
        if (durabilityState.isBatchInProgress()) {
          return { status: 'deferred', indexCount: generatedIndexCount };
        }
        const decisions = planDirectoryIndexRegenerations({
          docs: fileIndex,
          docExtension: getDocExtension,
          currentMarkdownFor: () => null,
          warningScope: generatedIndexWarningScope,
        });
        const gitAttributes = inspectGeneratedIndexGitAttributes({
          projectDir,
          contentDir,
          generatedDocNames: decisions.map(({ directory }) => indexDocNameFor(directory)),
        });
        if (gitAttributes.state !== 'ready' && gitAttributes.state !== 'not-applicable') {
          log.warn(
            { state: gitAttributes.state },
            '[index] generated index regeneration paused by Git attributes',
          );
          return { status: 'blocked', indexCount: generatedIndexCount };
        }

        for (const { directory, markdown } of decisions) {
          if (!request.fullSweep && !request.directories.has(directory)) continue;
          if (signal.aborted) {
            return { status: 'cancelled', indexCount: generatedIndexCount };
          }
          if (generationIsDisabled()) {
            return { status: 'disabled', indexCount: generatedIndexCount };
          }
          if (durabilityState.isBatchInProgress()) {
            return { status: 'deferred', indexCount: generatedIndexCount };
          }

          await options.generatedIndexTestHooks?.beforeDecision?.({
            directory,
            fullSweep: request.fullSweep,
            signal,
          });
          if (signal.aborted) {
            return { status: 'cancelled', indexCount: generatedIndexCount };
          }
          if (generationIsDisabled()) {
            return { status: 'disabled', indexCount: generatedIndexCount };
          }

          const docName = indexDocNameFor(directory);
          const absPath = resolve(contentDir, `${docName}.md`);
          assertContentPath(absPath);
          let currentMarkdown: string | null;
          try {
            currentMarkdown = readFileSync(absPath, 'utf-8');
          } catch (error) {
            if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
              log.warn(
                { err: error, path: normalizeFsPath(absPath) },
                '[index] could not read the existing generated index; treating it as absent',
              );
            }
            currentMarkdown = null;
          }

          generatedIndexCount += 1;
          const outcome = await writeGeneratedArtifact(
            { docName, absPath, markdown, currentMarkdown },
            generatedArtifactEnv,
          );
          if (outcome === 'blocked-conflict') {
            log.warn(
              {
                event: 'generated-index-regeneration',
                outcome: 'blocked',
                directory,
                reason: 'conflict',
              },
              '[index] generated index regeneration blocked by active conflict',
            );
          } else {
            log.info(
              {
                event: 'generated-index-regeneration',
                outcome: outcome === 'unchanged' ? 'unchanged' : 'written',
                directory,
              },
              '[index] generated index regeneration completed',
            );
          }
          await options.generatedIndexTestHooks?.afterWrite?.({
            docName,
            fullSweep: request.fullSweep,
            signal,
          });

          if (!request.fullSweep && directory !== '' && currentMarkdown === null) {
            scheduleSubdirectoryIndexRegeneration(directoryOf(directory));
          }
        }
      } finally {
        if (generatedAttributionPending) {
          await persistence.waitForPendingCommits();
          await persistence.flushContributors();
          generatedAttributionPending = false;
        }
        if (sweepStartedAt !== undefined) {
          recordBootPhase(
            'generatedIndexSweepMs',
            Math.round((performance.now() - sweepStartedAt) * 100) / 100,
          );
          setBootField('generatedIndexCount', generatedIndexCount);
        }
      }
      return { status: 'completed', indexCount: generatedIndexCount };
    } catch (err) {
      log.warn({ err }, '[index] index regeneration failed');
      return { status: 'failed', indexCount: generatedIndexCount };
    }
  }

  const REMOVED_DOCS_JOURNAL_SAVE_DEBOUNCE_MS = 2000;
  let removedDocsJournalTimer: ReturnType<typeof setTimeout> | null = null;
  let removedDocsJournalWritable = false;
  const writeRemovedDocsJournalNow = (): void => {
    try {
      saveRemovedDocsJournal(projectDir, recentlyRemovedDocs.entries());
    } catch (err) {
      log.warn({ err }, '[removed-docs-journal] failed to persist removal journal');
    }
  };
  const scheduleRemovedDocsJournalSave = (): void => {
    if (!removedDocsJournalWritable || removedDocsJournalTimer !== null) return;
    removedDocsJournalTimer = setTimeout(() => {
      removedDocsJournalTimer = null;
      writeRemovedDocsJournalNow();
    }, REMOVED_DOCS_JOURNAL_SAVE_DEBOUNCE_MS);
  };
  const recentlyRemovedDocs = new RecentlyRemovedDocs(undefined, {
    onEviction: () => incrementRecentlyRemovedDocsEviction(),
    onSizeChange: (size) => setRecentlyRemovedDocsSize(size),
    onMutate: scheduleRemovedDocsJournalSave,
  });
  for (const [journaledDocName, entry] of loadRemovedDocsJournal(projectDir)) {
    if (isReservedForUserTree(journaledDocName)) continue;
    if (!isSafeDocName(journaledDocName)) continue;
    const recreated = ['.md', '.mdx'].some((ext) => {
      const candidate = resolve(contentDir, `${journaledDocName}${ext}`);
      return isWithinDir(candidate, resolve(contentDir)) && existsSync(candidate);
    });
    if (recreated) continue;
    recentlyRemovedDocs.restore(journaledDocName, entry);
  }
  removedDocsJournalWritable = true;
  const commentDocHooksRef: { current: CommentDocHooks | null } = { current: null };

  type ResidentOccurrence = {
    source: string | undefined;
    mutation: { occurrence: ResidentOccurrence } | undefined;
    adoption: object | undefined;
    pendingRetirement: boolean;
  };
  let residentOccurrences = new WeakMap<Doc, ResidentOccurrence>();
  type RemovalOperation = { namespaceAllowed: boolean; residentAllowed: boolean };
  const activeRemovals = new Map<string, Set<RemovalOperation>>();

  const resolvedContentDir = resolve(contentDir);
  function resolveDocFilePath(docName: string): string | null {
    if (!isSafeDocName(docName)) return null;
    const relativePath = docNameToRelativePath(docName);
    const filePath = resolve(resolvedContentDir, relativePath);
    if (!isWithinDir(filePath, resolvedContentDir)) return null;
    return filePath;
  }

  function hasAdmittedMarkdownBinding(docName: string): boolean {
    const owner = watcher?.getFileIndex().get(docName);
    const filePath = owner?.canonicalPath ?? resolveDocFilePath(docName);
    if (filePath === null) return false;
    return hasAdmittedMarkdownFile(docName, filePath, contentDir, contentFilter);
  }

  function occurrenceFor(document: Doc): ResidentOccurrence {
    let occurrence = residentOccurrences.get(document);
    if (!occurrence) {
      occurrence = {
        source: document.getText('source').toString(),
        mutation: undefined,
        adoption: undefined,
        pendingRetirement: false,
      };
      residentOccurrences.set(document, occurrence);
    }
    return occurrence;
  }

  function revokeNamespaceRemovals(docName: string): void {
    for (const removal of activeRemovals.get(docName) ?? []) removal.namespaceAllowed = false;
  }

  function acceptResident(document: Doc, docName: string): void {
    if (
      documentAdmissionClosed ||
      document.isDestroyed ||
      hocuspocus.documents.get(docName) !== document
    )
      return;
    const occurrence = occurrenceFor(document);
    occurrence.pendingRetirement = false;
    occurrence.adoption = {};
    for (const removal of activeRemovals.get(docName) ?? []) {
      removal.namespaceAllowed = false;
      removal.residentAllowed = false;
    }
  }

  function markResidentForRetirement(document: Doc): void {
    residentOccurrences.set(document, {
      source: document.getText('source').toString(),
      mutation: undefined,
      adoption: undefined,
      pendingRetirement: true,
    });
  }

  function acceptNamespaceCreate(docName: string): void {
    if (documentAdmissionClosed) return;
    revokeNamespaceRemovals(docName);
    const document = hocuspocus.documents.get(docName);
    if (document) markResidentForRetirement(document);
    commentDocHooksRef.current?.deleted(docName);
  }

  function captureNamespaceMove(docName: string): () => void {
    const document = hocuspocus.documents.get(docName);
    const occurrence = document ? occurrenceFor(document) : undefined;
    const adoption = occurrence?.adoption;
    return () => {
      if (documentAdmissionClosed) return;
      revokeNamespaceRemovals(docName);
      if (
        document &&
        hocuspocus.documents.get(docName) === document &&
        residentOccurrences.get(document) === occurrence &&
        occurrence?.adoption === adoption
      )
        markResidentForRetirement(document);
    };
  }

  function capturePublicationReceipt(document: Doc, docName: string): (() => void) | undefined {
    const mutation = residentOccurrences.get(document)?.mutation;
    if (!mutation) return undefined;
    return () => {
      if (residentOccurrences.get(document) === mutation.occurrence)
        acceptResident(document, docName);
    };
  }

  function acceptConnectedDocument(docName: string, document: Document): void {
    if (hasAdmittedMarkdownBinding(docName)) acceptResident(document, docName);
  }

  function beginRemoval(docName: string, observedCurrent?: () => boolean) {
    const document = hocuspocus.documents.get(docName);
    const isApplicable = () =>
      (observedCurrent?.() ?? true) && !hasAdmittedMarkdownBinding(docName);
    const namespaceAllowed = !documentAdmissionClosed && isApplicable();
    const operation: RemovalOperation = {
      namespaceAllowed,
      residentAllowed:
        !documentAdmissionClosed &&
        document !== undefined &&
        (namespaceAllowed || occurrenceFor(document).pendingRetirement),
    };
    const removals = activeRemovals.get(docName) ?? new Set<RemovalOperation>();
    if (!documentAdmissionClosed) {
      removals.add(operation);
      activeRemovals.set(docName, removals);
    }
    const namespaceCurrent = () => {
      if (operation.namespaceAllowed && !isApplicable()) operation.namespaceAllowed = false;
      return operation.namespaceAllowed;
    };
    return {
      document,
      namespaceCurrent,
      residentCurrent: () => {
        if (
          operation.residentAllowed &&
          (document === undefined ||
            document.isDestroyed ||
            hocuspocus.documents.get(docName) !== document)
        )
          operation.residentAllowed = false;
        return operation.residentAllowed;
      },
      dispose: () => {
        operation.namespaceAllowed = false;
        operation.residentAllowed = false;
        removals.delete(operation);
        if (removals.size === 0) activeRemovals.delete(docName);
      },
    };
  }

  const onUpstreamRename = (oldDocName: string, newDocName: string): void => {
    if (isReservedForUserTree(oldDocName)) return;
    recentlyRemovedDocs.setRenamed(oldDocName, newDocName);
  };
  const onUpstreamDelete = (docName: string): void => {
    if (isReservedForUserTree(docName)) return;
    if (recentlyRemovedDocs.peek(docName)?.kind === 'renamed') {
      console.info(
        JSON.stringify({
          event: 'recently-removed-docs-unpaired-delete-suppressed',
          docName,
          source: 'watcher-delete',
        }),
      );
      return;
    }
    recentlyRemovedDocs.setDeleted(docName);
  };
  const onUpstreamAdd = (docName: string): void => {
    if (isReservedForUserTree(docName)) return;
    recentlyRemovedDocs.delete(docName);
  };

  try {
    let initialAttachmentFolderPath = DEFAULT_ATTACHMENT_FOLDER_PATH;
    try {
      initialAttachmentFolderPath = readProjectAttachmentFolderPath();
    } catch (err) {
      log.warn(
        { err },
        '[content-filter] invalid attachment folder at boot — using default attachment placement',
      );
    }
    lastAppliedAttachmentFolderPath = initialAttachmentFolderPath;
    contentFilter = createContentFilter({
      projectDir,
      contentDir,
      isContentScopeExcluded: (path) => {
        if (authorityScope.kind !== 'tree') return false;
        try {
          const target = canonicalContentPath(path);
          return authorityScope.excluded.some((root) =>
            contentScopeContainsPath({ kind: 'tree', path: root, excluded: [] }, target),
          );
        } catch (err) {
          const code = errnoCode(err);
          if (!(err instanceof SymlinkEscapeError) && code !== 'EACCES' && code !== 'EPERM')
            throw err;
          log.warn(
            { path: normalizeFsPath(path), code },
            '[content-filter] scope path could not be inspected',
          );
          return true;
        }
      },
      singleDocRelPath,
      attachmentFolderPath: initialAttachmentFolderPath,
      inPlaceSkillDirs: new Set(scanInPlaceSkills(contentDir).map((skill) => skill.dir)),
      rescanInPlaceSkillDirs: (priorAdmission) => scanInPlaceSkillDirs(contentDir, priorAdmission),
      skillRootPaths: skillRootPathsFor(contentDir),
      onAfterRebuild: () => {
        void derivedDocumentIndex.refreshContentScope().catch((err) => {
          getLogger('server-factory').warn(
            { err },
            '[content-filter] derived-index rebuild failed after onAfterRebuild',
          );
        });
        void reconcileFileIndexAfterFilterRebuild(watcher)
          .then(({ prunedFiles, prunedFolders }) => {
            const pruned = prunedFiles + prunedFolders;
            if (pruned > 0) {
              getLogger('server-factory').info(
                { pruned, prunedFiles, prunedFolders },
                '[content-filter] reconciled file indexes after onAfterRebuild',
              );
            } else {
              getLogger('server-factory').debug(
                { prunedFiles, prunedFolders },
                '[content-filter] file index reconcile completed after onAfterRebuild (no entries pruned; rescan may have added entries)',
              );
            }
          })
          .catch((err) => {
            getLogger('server-factory').warn(
              { err },
              '[content-filter] file index reconcile failed after onAfterRebuild',
            );
          });
      },
    });
    derivedDocumentIndex = new DerivedDocumentIndex({
      projectDir,
      contentDir,
      contentFilter,
      getGlobalSkillRoots: () => managedArtifactSkillsRoots(persistence.managedArtifactCtx),
      signalChannel,
      getLocalTargetInventory: () => localTargetInventoryFromWatcher(watcher, canonicalContentDir),
      onRecoveredFileTarget: (relativePath, exists) => {
        if (!watcher) return;
        reconcileRecoveredFileTarget({
          watcher,
          contentDir,
          relativePath,
          exists,
          invalidateReferencedAssetsCache,
        });
      },
    });

    shadowRef = { current: shadowRepo };

    maintenanceCoordinator = gitEnabled
      ? createMaintenanceCoordinator({
          getShadow: () => shadowRef.current ?? null,
          getCurrentBranch: getStorageBranch,
          contentRoot: contentRoot ?? '',
          projectGitDir: resolveGitDir(projectDir) ?? undefined,
          isWriterLive: (writerId) => {
            if (!agentPresenceBroadcaster && !sessionManager) {
              getLogger('server-factory').debug(
                { writerId },
                '[server-factory] isWriterLive called before liveness deps populated — treating writer as dead',
              );
              return false;
            }
            if (agentPresenceBroadcaster?.getPresenceMap()[writerId]) return true;
            const connId = writerId.startsWith('agent-')
              ? writerId.slice('agent-'.length)
              : writerId;
            for (const _session of sessionManager?.sessionsForConnection(connId) ?? []) {
              return true;
            }
            return false;
          },
        })
      : undefined;

    let globalCopyResyncTimer: ReturnType<typeof setTimeout> | null = null;
    const persistenceOpts: PersistenceOptions = {
      contentDir,
      assertContentPath,
      projectDir,
      conflicts,
      lifecycleOf: (document, docName) => conflicts.lifecycleOf(document, docName),
      gitEnabled,
      commitDebounceMs,
      wipRef,
      shadowRef,
      ephemeral,
      contentRoot,
      derivedDocumentIndex,
      configHomedirOverride,
      getCurrentBranch: getStorageBranch,
      resolveEmbed,
      resolveSize,
      getPrincipal: () => loadedPrincipal,
      onAgentCommit: () => cc1Broadcaster?.signal('session-activity'),
      onFlushCommit: () => maintenanceCoordinator?.noteFlushCommit(),
      capturePublicationReceipt,
      onDiskFlush: (docName, sv, persistedMarkdown, previousMarkdown) => {
        cc1Broadcaster?.emitDiskAck(docName, sv);
        if (isReservedForUserTree(docName)) return;
        if (indexedFieldsChanged(previousMarkdown, persistedMarkdown, docName)) {
          scheduleIndexRegeneration(docName);
        }
        if (!assetReferencesChanged(previousMarkdown, persistedMarkdown)) return;
        invalidateReferencedAssetsCache?.();
        signalChannel('files');
      },
      onConfigRejected: (docName, error) =>
        cc1Broadcaster?.emitConfigValidationRejected(docName, error),
      onConfigPersisted: (docName) => {
        applyPersistedConfigToConsumers(docName);
        logConfigDiagnostics(docName);
      },
      onManagedSkillPersisted: (docName) => {
        const parsed = parseManagedArtifactName(docName);
        if (parsed?.kind !== 'skill' || parsed.scope !== 'global') return;
        if (globalCopyResyncTimer !== null) clearTimeout(globalCopyResyncTimer);
        globalCopyResyncTimer = setTimeout(() => {
          globalCopyResyncTimer = null;
          const home = configHomedirOverride ?? homedir();
          void scanGlobalInPlaceSkillsAsync(home)
            .then((inPlace) => resyncRecordedSkillCopies(home, home, inPlace))
            .then((n) => {
              if (n > 0) log.info({ refreshed: n }, '[in-place-skills] post-edit copy re-sync');
            })
            .catch((err) => log.warn({ err }, '[in-place-skills] post-edit copy re-sync failed'));
        }, 2000);
        globalCopyResyncTimer.unref?.();
      },
      isRecentlyRemoved: (docName) => recentlyRemovedDocs.has(docName),
      mdManager: options.mdManager,
      getLossRing: () => lossRing,
      mergeHistory,
      ingestDiskAtStore: async (docName, absPath, content) => {
        let outcome: DiskIntakeOutcome;
        try {
          outcome = await intakeDiskUpdate({ kind: 'update', path: absPath, docName, content });
        } catch (error) {
          return { kind: 'failed', error };
        }
        switch (outcome.kind) {
          case 'applied':
            return outcome.merge === undefined
              ? { kind: 'taken-in' }
              : { kind: 'taken-in', merge: outcome.merge };
          case 'nothing-to-take':
            return { kind: 'taken-in' };
          case 'conflict':
            return { kind: 'conflict' };
          case 'failed':
            return { kind: 'failed', error: outcome.error };
          default:
            return assertNeverDiskIntakeOutcome(outcome);
        }
      },
    };

    persistence = createPersistenceExtension({ ...persistenceOpts, durabilityState });
    heldSaveProbe = (docName) => persistence.hasHeldSave(docName);

    hocuspocus = new Hocuspocus({
      quiet,
      debounce,
      maxDebounce,
      extensions: [persistence.extension],
    });

    const dispatchHooks = hocuspocus.hooks.bind(hocuspocus);
    hocuspocus.hooks = (name, payload, callback) => {
      if (
        (name === 'afterLoadDocument' || name === 'onChange') &&
        'document' in payload &&
        !isReservedForUserTree(payload.document.name)
      ) {
        const document = payload.document;
        const occurrence = occurrenceFor(document);
        if (name === 'onChange' && occurrence.mutation === undefined) {
          const source = document.getText('source').toString();
          if (source !== occurrence.source) {
            occurrence.source = undefined;
            occurrence.mutation = { occurrence };
          }
        }
      }
      if (
        name === 'connected' &&
        'connection' in payload &&
        payload.connection &&
        !isReservedForUserTree(payload.documentName)
      ) {
        acceptConnectedDocument(payload.documentName, payload.connection.document);
      }
      return dispatchHooks(name, payload, callback);
    };

    const openDirect = hocuspocus.openDirectConnection.bind(hocuspocus);
    function assertDocumentProjectScope(documentName: string): void {
      if (documentAdmissionClosed) throw new ServerMutationShuttingDownError(false);
      if (isReservedForUserTree(documentName)) {
        if (
          singleDocRelPath !== undefined &&
          documentName !== SYSTEM_DOC_NAME &&
          !isConfigDoc(documentName)
        )
          throw new ContentScopeAdmissionError();
        return;
      }
      if (
        singleDocRelPath !== undefined &&
        canonicalDocName(documentName) !== canonicalDocName(stripDocExtension(singleDocRelPath))
      )
        throw new ContentScopeAdmissionError();
      if (authorityRetired) throw new ServerMutationShuttingDownError(false);
      assertCapturedServerContentPath(authorityScope, safeContentPath(documentName, contentDir));
    }

    hocuspocus.openDirectConnection = (async (documentName: string, context?: unknown) => {
      const canonicalName = canonicalDocName(documentName);
      assertDocumentProjectScope(canonicalName);
      return openDirect(canonicalName, context);
    }) as typeof hocuspocus.openDirectConnection;

    const hp = hocuspocus;
    unregisterWorkloadProviders.push(
      registerLoadedDocsProvider(() => hp.documents.size),
      registerPersistenceQueueDepthProvider(() => persistence.getQueueDepths()),
      registerConnectionCountsProvider(() => {
        let direct = 0;
        for (const doc of hp.documents.values()) {
          direct += doc.directConnectionsCount;
        }
        return { websocket: hp.getConnectionsCount() - direct, direct };
      }),
    );
    installServerWorkloadGauges();

    if (!ephemeral) {
      stalenessWatchdog = createPersistenceStalenessWatchdog({
        getLoadedDocuments: () => hp.documents,
        lifecycleOf: (document, documentName) => conflicts.lifecycleOf(document, documentName),
        forceStore: (document, documentName) => persistence.forceStore(document, documentName),
        isHeldSaveDue: (documentName) => persistence.isHeldSaveDue(documentName),
        retryHeldSave: (document, documentName) =>
          persistence.retryHeldSave(document, documentName),
        getBase: (documentName) => durabilityState.getReconciledBase(documentName),
        isBatchActive: () => durabilityState.isBatchInProgress(),
        hasInFlight: (documentName) => durabilityState.inFlightFlushCount(documentName) > 0,
        readDiskBytes: (documentName) => {
          const requestedPath = safeContentPath(documentName, contentDir);
          let canonical: string;
          let size: number;
          try {
            canonical = realpathSync(requestedPath);
            size = statSync(canonical).size;
          } catch (err) {
            const code = errnoCode(err);
            if (code === 'ENOENT') return null;
            if (code === 'ELOOP') {
              throw new StructuralDiskReadError(`symlink cycle at content path: ${documentName}`);
            }
            throw err;
          }
          if (canonicalContentPathIsRefused(requestedPath, canonical, contentDir)) {
            throw new StructuralDiskReadError(
              `symlink-escape: ${requestedPath} resolves outside the content dir or into private state`,
            );
          }
          if (size > DOCUMENT_OPEN_BYTE_LIMIT) {
            throw new StructuralDiskReadError(
              `document exceeds the open byte limit: ${documentName}`,
            );
          }
          try {
            return readFileSync(canonical, 'utf-8');
          } catch (err) {
            if (errnoCode(err) === 'ENOENT') return null;
            throw err;
          }
        },
        graceMs: options.stalenessGraceMs,
        sweepIntervalMs: options.stalenessSweepIntervalMs,
      });
    }

    defaultShouldUnloadDocument = hocuspocus.shouldUnloadDocument.bind(hocuspocus);
    hocuspocus.shouldUnloadDocument = (document) => {
      const requests = forceUnloadRequests.get(document);
      if (requests) return [...requests].some((isCurrent) => isCurrent());
      if (
        shutdownAllowsUnload &&
        !isReservedForUserTree(document.name) &&
        durabilityState.isStoreRefused(document.name)
      ) {
        return false;
      }
      if (shutdownAllowsUnload && defaultShouldUnloadDocument(document)) {
        return true;
      }
      const name = document.name;
      if (isReservedForUserTree(name)) return false;
      if (getReconciledBase(name) !== undefined) return false;
      if (document.getXmlFragment('default').length !== 0) return false;
      if (document.getText('source').length !== 0) return false;
      return defaultShouldUnloadDocument(document);
    };

    forceUnloadDocument = async (document, isCurrent): Promise<void> => {
      const request = () =>
        hocuspocus.documents.get(document.name) === document && (isCurrent?.() ?? true);
      const requests = forceUnloadRequests.get(document) ?? new Set<() => boolean>();
      requests.add(request);
      forceUnloadRequests.set(document, requests);
      try {
        await hocuspocus.unloadDocument(document);
      } finally {
        requests.delete(request);
        if (requests.size === 0) forceUnloadRequests.delete(document);
      }
    };

    cc1Broadcaster = new CC1Broadcaster(hocuspocus);
    agentFocusBroadcaster = new AgentFocusBroadcaster(hocuspocus);
    agentPresenceBroadcaster = new AgentPresenceBroadcaster(hocuspocus);

    sessionManager = new AgentSessionManager(hocuspocus, {
      ...options.agentSessionOptions,
      assertDocumentScope: assertDocumentProjectScope,
      awaitWriteAdmission: () => durabilityState.whenWriteAdmitted(),
    });
    const sm = sessionManager;
    unregisterWorkloadProviders.push(
      registerAgentSessionCountsProvider(() => ({
        active: sm.liveSessionCount,
        limit: sm.sessionLimit,
      })),
    );
    const liveDerivedIndexExtension = createLiveDerivedIndexExtension({
      derivedDocumentIndex,
      onDocumentSettled: (docName) => commentDocHooksRef.current?.changed(docName),
    });
    hocuspocus.configuration.extensions.push(liveDerivedIndexExtension);

    type AuthRejectionLogReason = HocuspocusAuthRejectionReason | 'config-doc-admission-denied';
    function logAuthRejection(
      reason: AuthRejectionLogReason,
      documentName: string | undefined,
      detail: Record<string, unknown> = {},
    ): void {
      log.warn({ reason, docName: documentName, ...detail }, `[auth-rejection] ${reason}`);
    }

    const principalAuthExtension: Extension & { __kind: 'principal-auth' } = {
      __kind: 'principal-auth',
      async beforeHandleMessage(payload) {
        assertDocumentProjectScope(payload.documentName);
      },
      async onAuthenticate(payload) {
        assertDocumentProjectScope(payload.documentName);
        const tokenStr = payload.token;
        const parsed = parseHocuspocusAuthToken(tokenStr);

        const claimed = parsed?.expectedServerInstanceId;
        if (typeof claimed === 'string' && claimed.length > 0 && claimed !== serverInstanceId) {
          logAuthRejection('server-instance-mismatch', payload.documentName, {
            claimedServerInstanceId: claimed,
            currentServerInstanceId: serverInstanceId,
          });
          throw new HocuspocusAuthRejection(
            'server-instance-mismatch',
            `server instance mismatch: client claimed ${claimed}, this server is ${serverInstanceId}`,
          );
        }

        const claimedBranch = parsed?.expectedBranch;
        if (typeof claimedBranch === 'string' && claimedBranch.length > 0) {
          const currentBranch = await resolveBranchForClaimCheck();
          if (currentBranch !== null && claimedBranch !== currentBranch) {
            logAuthRejection('branch-mismatch', payload.documentName, {
              claimedBranch,
              currentBranch,
            });
            throw new HocuspocusAuthRejection(
              'branch-mismatch',
              `branch mismatch: client claimed ${claimedBranch}, server is on ${currentBranch}`,
            );
          }
        }

        if (!parsed) return;
        const ctx = payload.context as Record<string, unknown>;
        if (typeof parsed.principalId === 'string') {
          if (loadedPrincipal && parsed.principalId === loadedPrincipal.id) {
            ctx.principalId = loadedPrincipal.id;
          } else if (loadedPrincipal) {
            console.warn(
              JSON.stringify({
                event: 'principal-token-mismatch',
                claimed: parsed.principalId,
                loaded: loadedPrincipal.id,
              }),
            );
          } else {
            ctx.principalId = parsed.principalId;
          }
        }
        if (typeof parsed.tabSessionId === 'string') {
          ctx.tabSessionId = parsed.tabSessionId;
        }
        ctx.kind = 'human';
      },
    };
    hocuspocus.configuration.extensions.push(principalAuthExtension);

    const configDocAdmissionGuard: Extension & { __kind: 'config-doc-admission-guard' } = {
      __kind: 'config-doc-admission-guard',
      async onAuthenticate(payload) {
        if (!isConfigDoc(payload.documentName) && !isManagedArtifactDoc(payload.documentName)) {
          return;
        }
        const req = payload.request as unknown as {
          socket?: { remoteAddress?: string };
          headers?: { host?: string };
        };
        const peer = req.socket?.remoteAddress;
        if (peer !== undefined && !isPeerAdmitted(peer, ingressPolicy)) {
          logAuthRejection('config-doc-admission-denied', payload.documentName, { check: 'peer' });
          throw new Error(
            `config-doc admission requires loopback peer (peer=${peer}, doc=${payload.documentName})`,
          );
        }
        const headersBag = (payload as { requestHeaders?: Headers }).requestHeaders;
        const host =
          (headersBag && typeof headersBag.get === 'function' ? headersBag.get('host') : null) ??
          req.headers?.host ??
          undefined;
        if (!isHostAdmitted(host, ingressPolicy)) {
          logAuthRejection('config-doc-admission-denied', payload.documentName, { check: 'host' });
          throw new Error(
            `config-doc admission requires a loopback or remote Host header (host=${host ?? '<absent>'}, doc=${payload.documentName})`,
          );
        }
      },
    };
    hocuspocus.configuration.extensions.push(configDocAdmissionGuard);
    hocuspocus.configuration.extensions.push(
      createPrivateSkillTrustAdmission((rejectionClass) =>
        logAuthRejection('config-doc-admission-denied', CONFIG_DOC_NAME_USER, {
          check: 'private-skill-trust',
          rejectionClass,
        }),
      ),
    );

    const removalRedirectGuard: Extension & { __kind: 'removal-redirect-guard' } = {
      __kind: 'removal-redirect-guard',
      async onAuthenticate(payload) {
        if (!isReservedForUserTree(payload.documentName)) {
          const path = resolveDocFilePath(payload.documentName);
          if (path !== null && !existsSync(path)) {
            try {
              await Promise.race([offlineRemovalsReconciled.promise, ready]);
            } catch (err) {
              log.error(
                { err, docName: payload.documentName },
                '[removal-guard] missing-document admission refused after startup failure',
              );
              throw err;
            }
          }
        }
        await runRemovalRedirectGuard(payload.documentName, {
          recentlyRemovedDocs,
          resolveFilePath: resolveDocFilePath,
          fileExists: existsSync,
        });
      },
    };
    hocuspocus.configuration.extensions.push(removalRedirectGuard);

    const docLineageGuard: Extension & { __kind: 'doc-lineage-guard' } = {
      __kind: 'doc-lineage-guard',
      async onAuthenticate(payload) {
        const parsed = parseHocuspocusAuthToken(payload.token);
        runDocLineageGuard(payload.documentName, parsed?.expectedDocLineageEpoch, {
          getLoadedDoc: (name) => hocuspocus.documents.get(name),
        });
      },
    };
    hocuspocus.configuration.extensions.push(docLineageGuard);

    const systemDocBroadcastGuard: Extension & { __kind: 'system-doc-broadcast-guard' } = {
      __kind: 'system-doc-broadcast-guard',
      async beforeHandleMessage(payload) {
        if (payload.documentName !== SYSTEM_DOC_NAME) return;
        const message = new IncomingMessage(payload.update);
        message.readVarString();
        const type = message.readVarUint();
        if (type === MessageType.BroadcastStateless) {
          throw new Error(
            `inbound BroadcastStateless on ${SYSTEM_DOC_NAME} rejected — server-only channel`,
          );
        }
      },
    };
    hocuspocus.configuration.extensions.push(systemDocBroadcastGuard);

    const renameCarryRetirement: Extension = {
      async afterUnloadDocument({ documentName }) {
        durabilityState.endRenameCarry(documentName);
      },
    };
    hocuspocus.configuration.extensions.push(renameCarryRetirement);

    const apiExtension = createApiExtension({
      mergeHistoryWriter: options.mergeHistoryWriter,
      docNotices,
      declaredGitHubHosts,
      resolveSyncCredentialConfig,
      hocuspocus,
      durabilityState,
      ingressPolicy,
      sessionManager,
      commentDocHooksRef,
      onNamespaceCreateAccepted: acceptNamespaceCreate,
      capturePublicationReceipt,
      captureNamespaceMove,
      onResidentAdopted: acceptResident,
      contentDir,
      assertContentPath,
      assertContentSubtree,
      getGeneratedIndexSettingsStatus,
      setGeneratedIndexEnabled,
      contentFilter,
      serverInstanceId,
      getFileIndex: () => (watcher ? watcher.getFileIndex() : new Map()),
      getAttachmentFolderPath: readProjectAttachmentFolderPath,
      getAllFilesIndex: () => (watcher ? watcher.getAllFilesIndex() : new Map()),
      getFileIndexGeneration: () => watcher?.getFileIndexGeneration() ?? 0,
      mutateFileIndex: (event) => {
        const previousIndexedFields =
          event.kind === 'update' ? currentIndexedFields(event.docName) : undefined;
        watcher?.mutateFileIndex(event);
        switch (event.kind) {
          case 'update':
            if (indexedMetadataChanged(previousIndexedFields, event.content, event.docName)) {
              scheduleIndexRegeneration(event.docName);
            }
            break;
          case 'create':
            reviveFrozenResident(event.docName, event.content);
            scheduleIndexRegeneration(event.docName);
            break;
          case 'conflict':
            scheduleIndexRegeneration(event.docName);
            break;
          case 'delete':
            commentDocHooksRef.current?.deleted(event.docName);
            scheduleIndexRegenerationAfterRemoval(event.docName);
            break;
          case 'rename':
            scheduleIndexRegenerationAfterRemoval(event.oldDocName);
            scheduleIndexRegeneration(event.newDocName);
            break;
          case 'folder-create':
          case 'folder-delete':
            scheduleSubdirectoryIndexRegeneration(event.relativePath);
            break;
          case 'asset-create':
          case 'asset-delete':
          case 'file-create':
          case 'file-update':
          case 'file-delete':
            break;
          default:
            assertNeverDiskEvent(event);
        }
      },
      getFolderIndex: () => (watcher ? watcher.getFolderIndex() : new Map()),
      getAliasMap: () => (watcher ? watcher.getAliasMap() : new Map()),
      getFolderAliasIndex: () => (watcher ? watcher.getFolderAliasIndex() : new Map()),
      resolveTrackedFile,
      rescanFiles: () => watcher?.rescanFromDisk(),
      settleDiskEventsForTest: async () => {
        await watcher?.settle();
      },
      enableTestRoutes,
      shadowRef,
      flushGitCommit: () => persistence.flushPendingGitCommit(),
      flushContributors: () => persistence.flushContributors(),
      getCurrentBranch: getStorageBranch,
      getReportedBranch,
      getDiskAckSVs: () => cc1Broadcaster?.getLatestDiskAckSVsAsBase64() ?? {},
      getCollabClientCount: options.getCollabClientCount,
      contentRoot,
      derivedDocumentIndex,
      signalChannel,
      agentFocusBroadcaster,
      agentPresenceBroadcaster,
      onAgentWrite: options.onAgentWrite,
      getSyncEngine: () => syncEngine,
      conflicts,
      setBatchInProgress: batchFlagFor('conflict-resolve'),
      refreshDocumentsFromDisk,
      localOpCliArgs,
      authStreamHeartbeatMs,
      projectDir,
      resolveEmbed,
      getBridgeLossReporter: () => bridgeLossReporter,
      getPrincipal: () => loadedPrincipal,
      agentIntegrations: options.agentIntegrations,
      acpRegistry,
      loadAcpCustomAgents: () => loadCustomAgents(lockDir, getLogger('acp-registry')),
      homeDirOverride: configHomedirOverride,
      resetSettingsForTest:
        configHomedirOverride === undefined
          ? undefined
          : () => {
              for (const configDocName of CONFIG_DOC_NAMES) {
                resetConfigDocForTest(
                  hocuspocus.documents.get(configDocName) ?? null,
                  configDocName,
                  persistence.configPersistenceCtx,
                );
                configFileWatcherResyncs.get(configDocName)?.();
                applyPersistedConfigToConsumers(configDocName);
              }
            },
      forceUnloadDocument,
      ready,
      recentlyRemovedDocs,
      serializeDoc,
      evictManagedArtifactLkg: (docName: string) => {
        persistence.managedArtifactCtx.lkgCache.delete(docName);
      },
      semanticSearch,
      getSemanticSimilarityFloor: () => readSemanticSearchConfig().similarityFloor,
      getLinterBaseConfig: () => readLinterBaseConfig(),
      getLinkAdvisoryPolicy: readLinkAdvisoryPolicy,
      getProjectConfigEpoch: () => projectConfigEpoch,
      getLinkPreviewsEnabled: readLinkPreviewsEnabled,
      resolveGitHubToken: createGitHubTokenResolver(options.detectGh, options.tokenStore),
      getConfigDiagnostics: readConfigDiagnostics,
      embeddingsSecretsFile: secretsFilePath(configHomedirOverride),
      readSemanticProviderConfig: readSemanticSearchConfig,
      ephemeral,
      onReferencedAssetsCacheInvalidator: (invalidate) => {
        invalidateReferencedAssetsCache = invalidate;
      },
    });
    hocuspocus.configuration.extensions.push(apiExtension);
    hocuspocus.configuration.extensions.push(
      createReconnectRefreshExtension({
        clock: options.watcherClock ?? watcherClock(),
        refresh: refreshDocumentsFromDisk,
      }),
    );
    nativeApi = apiExtension.nativeApi;
    localApi = apiExtension.localApi;
    shutdownLocalOps = apiExtension.shutdownLocalOps;

    const bridgeGuardConfig = readConfigSafely({
      absPath: resolveConfigPath('project', projectDir),
      sideline: false,
      warn: (message) =>
        log.warn({ message }, '[config] could not read project config for bridge guards'),
    });
    const deferGuardEnabled = bridgeGuardConfig.value.bridge.deferGuard.enabled;
    const fixedPointBackstopEnabled = bridgeGuardConfig.value.bridge.fixedPoint.enabled;
    const preDrainEnabled = bridgeGuardConfig.value.bridge.preDrain.enabled;
    lossRing = bridgeGuardConfig.value.lossCapture.enabled
      ? new LossCaptureRing({
          projectDir,
          maxBytes: bridgeGuardConfig.value.lossCapture.maxBytes,
        })
      : undefined;

    if (bridgeGuardConfig.value.bridge.lossDetector.enabled) {
      bridgeLossReporter = createBridgeDeriveLossReporter({
        shadow: () => shadowRef.current,
        ring: lossRing,
        getBranch: () => getStorageBranch() ?? 'main',
        contentRoot: contentRoot ?? '',
      });
      sessionManager.attachBridgeLossReporter(bridgeLossReporter);
    }

    hocuspocus.configuration.extensions.push(
      createServerObserverExtension({
        mdManager,
        schema,
        shadowRef,
        contentRoot,
        getCurrentBranch: getStorageBranch,
        resolveEmbed,
        resolveSize,
        deferGuardEnabled,
        lossDetectorEnabled: bridgeGuardConfig.value.bridge.lossDetector.enabled,
        fixedPointBackstopEnabled,
        preDrainEnabled,
        lossRing,
      }),
    );

    hocuspocus.configuration.extensions.push(createSyncHandshakeSpanExtension());

    hocuspocus.configuration.extensions.push({
      async afterLoadDocument({ document }) {
        bindConflictAuthority(document, conflicts);
      },
    });
  } catch (err) {
    for (const unregister of unregisterWorkloadProviders.splice(0)) {
      unregister();
    }
    void stalenessWatchdog?.dispose();
    stalenessWatchdog = null;
    authorityRetired = true;
    releaseServerLock(lockDir);
    try {
      authority.release();
    } catch (cleanupError) {
      log.error({ err: cleanupError }, '[server] construction authority release failed');
    }
    throw err;
  }

  let systemDocConnection: Awaited<ReturnType<Hocuspocus['openDirectConnection']>> | null = null;
  const configDocConnections = new Map<
    string,
    Awaited<ReturnType<Hocuspocus['openDirectConnection']>>
  >();

  const configFileWatcherCleanups: Array<{
    docName: string;
    cleanup: ConfigFileWatcherUnsubscribe;
  }> = [];
  const configFileWatcherResyncs = new Map<ConfigDocName, () => void>();

  function safeRescuePath(shadowGitDir: string, docName: string): string | null {
    const rescueBase = resolve(shadowGitDir, 'rescue');
    const relativePath = docNameToRelativePath(docName);
    const filePath = resolve(rescueBase, relativePath);
    if (!isWithinDir(filePath, rescueBase)) return null;
    return filePath;
  }

  function serializeDoc(docName: string): string | null {
    const document = hocuspocus.documents.get(docName);
    if (!document) return null;
    return serializeYDocSource(document);
  }

  const applyToDoc = (docName: string, content: string): void => {
    const document = hocuspocus.documents.get(docName);
    applyExternalChange(
      durabilityState,
      hocuspocus,
      docName,
      content,
      resolveEmbed,
      resolveSize,
      bridgeLossReporter,
    );
    if (document && hasAdmittedMarkdownBinding(docName)) acceptResident(document, docName);
  };

  const reviveFrozenResident = (docName: string, content: string): FrozenResidentRevival => {
    const result = reviveFrozenResidentDoc(
      durabilityState,
      hocuspocus,
      docName,
      content,
      resolveEmbed,
      resolveSize,
      bridgeLossReporter,
    );
    const document = hocuspocus.documents.get(docName);
    if (result === 'revived' && document && hasAdmittedMarkdownBinding(docName)) {
      acceptResident(document, docName);
    }
    return result;
  };

  const refreshLoadedEmbeds = (
    needle: string,
    context: { reason: 'startup' } | { reason: 'asset-event'; assetBasename: string },
  ): number => {
    let refreshed = 0;
    for (const [docName] of hocuspocus.documents) {
      if (isReservedForUserTree(docName)) continue;
      const document = hocuspocus.documents.get(docName);
      if (!document) continue;
      const source = document.getText('source').toString();
      if (!source.includes(needle)) continue;
      try {
        document.transact(() => {
          applyDiskContentToDoc(document, source, resolveEmbed, docName);
        }, FILE_WATCHER_ORIGIN);
        refreshed++;
      } catch (err) {
        log.error(
          { originalError: redactedErrorSummary(err), docName, ...context },
          context.reason === 'asset-event'
            ? `[asset-event] failed to re-render ${docName} for asset basename ${context.assetBasename}`
            : `[basename-index] failed to refresh loaded startup embeds in ${docName}`,
        );
      }
    }
    return refreshed;
  };

  const rerenderDocsReferencingAssetBasename = (assetBasename: string): void => {
    if (!assetBasename) return;
    refreshLoadedEmbeds(`[[${assetBasename}]]`, { reason: 'asset-event', assetBasename });
  };

  const refreshStartupEmbeds = (): void => {
    try {
      const documentCount = refreshLoadedEmbeds('![[', { reason: 'startup' });
      log.debug({ documentCount }, '[basename-index] refreshed loaded startup embeds');
    } catch (err) {
      log.warn({ err }, '[basename-index] loaded startup embed refresh failed');
    }
  };

  let pendingAssetRerenderBasenames: Set<string> | null = null;
  const scheduleAssetRerender = (assetBasename: string): void => {
    if (!assetBasename) return;
    if (pendingAssetRerenderBasenames === null) {
      pendingAssetRerenderBasenames = new Set();
      setImmediate(() => {
        const toRender = pendingAssetRerenderBasenames;
        pendingAssetRerenderBasenames = null;
        if (!toRender) return;
        try {
          for (const b of toRender) rerenderDocsReferencingAssetBasename(b);
        } catch (err) {
          log.error({ err, basenames: [...toRender] }, '[asset-event] dedup rerender pass crashed');
        }
      });
    }
    pendingAssetRerenderBasenames.add(assetBasename);
  };

  function diskEventLabel(event: DiskEvent): string {
    switch (event.kind) {
      case 'rename':
        return event.newDocName;
      case 'asset-create':
      case 'asset-delete':
      case 'folder-create':
      case 'folder-delete':
      case 'file-create':
      case 'file-update':
      case 'file-delete':
        return event.relativePath;
      case 'create':
      case 'update':
      case 'delete':
      case 'conflict':
        return event.docName;
      default:
        return assertNeverDiskEvent(event);
    }
  }

  const CHECKPOINT_KIND_BY_MINT_SITE = {
    delete: 'external-change-rescue',
    rename: 'external-change-rescue',
    'branch-switch': 'external-change-rescue',
    'disk-update': 'external-change-rescue-disk-update',
  } as const satisfies Record<
    'delete' | 'rename' | 'branch-switch' | 'disk-update',
    CheckpointKind
  >;

  /* WARN: mint-site → checkpoint-kind → GC bucket coupling; the per-kind retention budgets and
   * the external-change-rescue split are recorded in packages/core/src/bridge/README.md
   * (external-change-rescue exception paragraph). */
  const mintExternalChangeRescue = (
    docName: string,
    ours: string,
    branch: string,
    site: keyof typeof CHECKPOINT_KIND_BY_MINT_SITE,
    incomingDiskSha = '',
    followedByContentLoss = false,
  ): boolean => {
    if (!shadowRef.current) {
      const consequence = !followedByContentLoss
        ? ''
        : site === 'delete'
          ? ' — the delete that follows destroys the document content'
          : ' — the overwrite that follows replaces the document content';
      log.warn(
        { docName, site },
        `[reconcile] rescue checkpoint not minted for ${docName} (${site}) — shadow repo unavailable${consequence}`,
      );
      incrementRescueBufferWriteFailures();
      return false;
    }
    const shadowForCheckpoint = shadowRef.current;
    queueMicrotask(() => {
      saveInMemoryCheckpoint(shadowForCheckpoint, contentRoot ?? '', {
        kind: CHECKPOINT_KIND_BY_MINT_SITE[site],
        docName,
        contents: ours,
        label: `External change recovered @ ${new Date().toISOString()}`,
        branch,
        metadata: { incomingDiskSha },
      })
        .then(() => {
          incrementRescueBuffer();
          log.info({ docName, site }, `[reconcile] rescue checkpoint saved (${site}): ${docName}`);
        })
        .catch((e: unknown) => {
          incrementRescueCheckpointWriteFailures();
          const consequence = !followedByContentLoss
            ? ''
            : site === 'delete'
              ? ' — the delete that follows destroys the document content'
              : ' — the overwrite that follows replaces the document content';
          log.error(
            { docName, site, err: e },
            `[reconcile] rescue checkpoint write failed (${site}): ${docName}${consequence}`,
          );
        });
    });
    return true;
  };

  const settledVanishEvents = new WeakSet<DiskEvent>();
  const vanishClock = options.watcherClock ?? watcherClock();
  let vanishRecheckTimer: WatcherTimer | null = null;
  let vanishRecheckRunning = false;

  const holdVanished = (entry: VanishedDocument): void => {
    vanishedDocuments.hold(entry);
    durabilityState.holdStores(entry.docName);
  };

  const reportedUnreadableReturns = new Set<string>();
  const overdueFaults = new Map<string, number>();

  const releaseVanished = (docName: string): void => {
    vanishedDocuments.release(docName);
    overdueFaults.delete(docName);
    reportedUnreadableReturns.delete(docName);
    durabilityState.releaseStores(docName);
  };

  let branchSwitchFollowUpTimer: WatcherTimer | null = null;
  let branchSwitchFollowUpGeneration = 0;

  function supersedeBranchSwitchFollowUps(): void {
    branchSwitchFollowUpGeneration += 1;
    vanishClock.clearTimeout(branchSwitchFollowUpTimer);
    branchSwitchFollowUpTimer = null;
  }

  function followUpBranchSwitchRecheck(branch: string): void {
    supersedeBranchSwitchFollowUps();
    void runBranchSwitchFollowUp(branch, branchSwitchFollowUpGeneration, 1).catch(
      (err: unknown) => {
        log.error({ err, branch }, '[branch-switch] the follow-up re-checks stopped');
      },
    );
  }

  async function runBranchSwitchFollowUp(
    branch: string,
    generation: number,
    attempt: number,
  ): Promise<void> {
    if (!watcher || generation !== branchSwitchFollowUpGeneration) return;
    let result: RecheckResult | undefined;
    try {
      result = await watcher.recheck('full');
    } catch (err) {
      log.warn(
        { err, branch, attempt },
        `[branch-switch] follow-up re-check ${attempt} after switching to ${branch} failed`,
      );
    }
    if (generation !== branchSwitchFollowUpGeneration || result?.status === 'closed') return;
    if (result?.status === 'completed' && !result.partial) {
      log.info(
        { branch, attempt },
        `[branch-switch] follow-up re-check ${attempt} observed the whole tree after switching to ${branch}`,
      );
      return;
    }
    incrementBranchSwitchRecheckShortfalls();
    const details = {
      branch,
      attempt,
      status: result?.status ?? 'failed',
      partial: result?.partial === true,
    };
    if (attempt >= BRANCH_SWITCH_FOLLOW_UP_LIMIT) {
      log.warn(
        details,
        `[branch-switch] ${attempt} follow-up re-checks after switching to ${branch} did not observe the whole tree; open documents may keep text from the previous branch until a later re-check observes it`,
      );
      return;
    }
    log.warn(
      details,
      `[branch-switch] follow-up re-check ${attempt} after switching to ${branch} did not observe the whole tree; trying again in ${BRANCH_SWITCH_FOLLOW_UP_DELAY_MS / 1000} s`,
    );
    branchSwitchFollowUpTimer = vanishClock.setTimeout(() => {
      branchSwitchFollowUpTimer = null;
      void runBranchSwitchFollowUp(branch, generation, attempt + 1).catch((err: unknown) => {
        log.error({ err, branch }, '[branch-switch] the follow-up re-checks stopped');
      });
    }, BRANCH_SWITCH_FOLLOW_UP_DELAY_MS);
    branchSwitchFollowUpTimer.unref();
  }

  const scheduleVanishRecheck = (): void => {
    if (vanishRecheckTimer || vanishRecheckRunning || vanishedDocuments.size === 0) return;
    vanishRecheckTimer = vanishClock.setTimeout(() => {
      vanishRecheckTimer = null;
      void runVanishRecheck().catch((err: unknown) => {
        log.error({ err }, '[reconcile] the re-check loop for vanished documents failed');
      });
    }, VANISH_RECHECK_DELAY_MS);
    vanishRecheckTimer.unref();
  };

  async function runVanishRecheck(): Promise<void> {
    if (!watcher) return;
    vanishRecheckRunning = true;
    let result: RecheckResult | undefined;
    try {
      result = await watcher.recheck('metadata');
    } catch (err) {
      log.warn({ err }, '[reconcile] the re-check for vanished documents failed');
    } finally {
      vanishRecheckRunning = false;
    }
    try {
      if (vanishedDocuments.size > 0 && (result?.status !== 'completed' || result.partial)) {
        log.info(
          { status: result?.status ?? 'failed', partial: result?.partial === true },
          `[reconcile] the re-check for ${vanishedDocuments.size} vanished document(s) did not observe the whole tree; trying again`,
        );
      }
      await resolveOverdueVanishedDocuments();
    } finally {
      scheduleVanishRecheck();
    }
  }

  function pathIsOccupied(path: string): boolean {
    try {
      lstatSync(path);
      return true;
    } catch (err) {
      const code = errnoCode(err);
      if (code === 'ENOENT' || code === 'ENOTDIR') return false;
      log.warn({ err, path }, '[reconcile] could not tell whether a vanished file is gone');
      return true;
    }
  }

  type MarkdownFileProbe =
    | { readonly kind: 'present'; readonly path: string; readonly content: string }
    | { readonly kind: 'absent' }
    | { readonly kind: 'refused' }
    | { readonly kind: 'unreadable'; readonly code: string };

  function probeMarkdownFile(docName: string, path: string): MarkdownFileProbe {
    const unreadable = (err: unknown): MarkdownFileProbe => {
      const code = errnoCode(err);
      if (code === 'ENOENT' || code === 'ENOTDIR') return { kind: 'absent' };
      return { kind: 'unreadable', code: code ?? 'unknown' };
    };
    try {
      lstatSync(path);
      accessSync(path, fsConstants.R_OK);
    } catch (err) {
      const probe = unreadable(err);
      if (probe.kind === 'absent' || errnoCode(err) !== 'ELOOP') return probe;
    }
    if (!hasAdmittedMarkdownFile(docName, path, contentDir, contentFilter))
      return { kind: 'refused' };
    try {
      return { kind: 'present', path, content: readFileSync(path, 'utf-8') };
    } catch (err) {
      return unreadable(err);
    }
  }

  function probeVanishedFile(entry: VanishedDocument): MarkdownFileProbe {
    const path =
      watcher?.getFileIndex().get(entry.docName)?.canonicalPath ??
      resolveDocFilePath(entry.docName) ??
      entry.path;
    return probeMarkdownFile(entry.docName, path);
  }

  async function holdVanishedDocument(
    event: Extract<DiskEvent, { kind: 'delete' }>,
  ): Promise<boolean> {
    if (!watcher || pathIsOccupied(event.path)) return false;
    const facts = getMarkdownEventFacts(event);
    const base = getReconciledBase(event.docName);
    const hashes = new Set<string>();
    if (facts.lastHash !== undefined) hashes.add(facts.lastHash);
    if (base !== undefined) hashes.add(contentHash(base));
    const vanished = {
      docName: event.docName,
      path: event.path,
      identity: facts.identity,
      size: facts.size,
      modified: facts.modified,
      hashes,
      text: base ?? serializeDoc(event.docName) ?? undefined,
    };
    const readRecentCreate = (create: RecentCreate): string | undefined => {
      const probe = probeMarkdownFile(create.docName, create.path);
      return probe.kind === 'present' ? probe.content : undefined;
    };
    const recent = vanishedDocuments.matchRecentCreate(
      vanished,
      vanishClock.now(),
      readRecentCreate,
    );
    if (recent) {
      const probe = probeMarkdownFile(recent.create.docName, recent.create.path);
      if (probe.kind === 'present') {
        recordVanishOutcome(recent.by === 'identity' ? 'paired-identity' : 'paired-hash');
        await handleDiskEvent({
          kind: 'rename',
          oldPath: event.path,
          newPath: recent.create.path,
          oldDocName: event.docName,
          newDocName: recent.create.docName,
          content: probe.content,
        });
        return true;
      }
      log.info(
        { docName: event.docName, create: recent.create.docName, probe: probe.kind },
        `[reconcile] ${event.docName}: a recent create could not be read; holding the document instead`,
      );
    }
    holdVanished({
      ...vanished,
      afterPass: watcher.recoveryPassesStarted(),
      heldAt: vanishClock.now(),
    });
    recordVanishOutcome('pending');
    log.info(
      { docName: event.docName },
      `[reconcile] ${event.docName}: its file vanished; it stays open until a re-check of the whole tree, in case it was moved`,
    );
    scheduleVanishRecheck();
    return true;
  }

  const flushReleasedStores = (): void => {
    if (isBatchInProgress()) return;
    void persistence.flushDeferredStores('within-branch').catch((err: unknown) => {
      log.error(
        { err },
        '[persistence] deferred store drain failed after a vanished file resolved',
      );
    });
  };

  async function takeReturnedFile(
    entry: VanishedDocument,
    probe: Extract<MarkdownFileProbe, { kind: 'present' }>,
  ): Promise<void> {
    releaseVanished(entry.docName);
    try {
      recordVanishOutcome('recreated');
      log.info(
        { docName: entry.docName },
        `[reconcile] ${entry.docName}: its file is back; taking it in as an update`,
      );
      await onDiskEvent({
        kind: 'update',
        path: probe.path,
        docName: entry.docName,
        content: probe.content,
      });
    } finally {
      flushReleasedStores();
    }
  }

  async function standVanishedDelete(
    entry: VanishedDocument,
    outcome: 'deleted' | 'unconfirmed',
  ): Promise<void> {
    persistence.discardDeferredStore(entry.docName, { kind: 'deleted-outside' });
    releaseVanished(entry.docName);
    recordVanishOutcome(outcome);
    const deleteEvent: DiskEvent = { kind: 'delete', path: entry.path, docName: entry.docName };
    settledVanishEvents.add(deleteEvent);
    await onDiskEvent(deleteEvent);
  }

  function keepUnreadableHeld(entry: VanishedDocument, code: string): void {
    if (reportedUnreadableReturns.has(entry.docName)) return;
    reportedUnreadableReturns.add(entry.docName);
    log.warn(
      { docName: entry.docName, code },
      `[reconcile] ${entry.docName}: a file is at its path but cannot be read (${code}); it stays held until it can be read or the hold limit passes`,
    );
  }

  interface VanishStep {
    action: string;
  }

  function reportVanishFault(
    entry: VanishedDocument,
    step: VanishStep,
    err: unknown,
    overdueAttempt?: number,
  ): void {
    const stillHeld = vanishedDocuments.has(entry.docName);
    const attempt =
      overdueAttempt === undefined
        ? ''
        : ` (attempt ${overdueAttempt} of ${VANISH_OVERDUE_FAULT_LIMIT} past the hold limit)`;
    log.error(
      { err, docName: entry.docName, action: step.action, stillHeld, overdueAttempt },
      stillHeld
        ? `[reconcile] ${entry.docName}: ${step.action} failed with an internal error${attempt}; it is still held`
        : `[reconcile] ${entry.docName}: ${step.action} failed with an internal error${attempt}; its hold had already ended`,
    );
  }

  function endHoldAfterOverdueFaults(entry: VanishedDocument, attempts: number): void {
    releaseVanished(entry.docName);
    flushReleasedStores();
    log.error(
      { docName: entry.docName, attempts },
      `[reconcile] ${entry.docName}: ended its hold after ${attempts} failed attempts past the hold limit; its deferred saves were released to run as normal saves`,
    );
  }

  async function settleVanishedDocuments(pass: number, whole: boolean): Promise<void> {
    if (!whole) return;
    for (const entry of vanishedDocuments.dueAfter(pass)) {
      const step: VanishStep = { action: 'checking its path' };
      try {
        await settleVanishedDocument(entry, step);
      } catch (err) {
        reportVanishFault(entry, step, err);
      }
    }
  }

  async function settleVanishedDocument(entry: VanishedDocument, step: VanishStep): Promise<void> {
    const probe = probeVanishedFile(entry);
    switch (probe.kind) {
      case 'present':
        step.action = 'taking its returned file in';
        await takeReturnedFile(entry, probe);
        return;
      case 'unreadable':
        keepUnreadableHeld(entry, probe.code);
        return;
      case 'absent':
      case 'refused':
        step.action = 'applying the delete';
        log.info(
          { docName: entry.docName, probe: probe.kind },
          `[reconcile] ${entry.docName}: no move found after a re-check of the whole tree; the delete stands`,
        );
        await standVanishedDelete(entry, 'deleted');
        return;
      default: {
        const unhandled: never = probe;
        throw new Error(`unhandled file probe: ${JSON.stringify(unhandled)}`);
      }
    }
  }

  async function resolveOverdueVanishedDocuments(): Promise<void> {
    for (const entry of vanishedDocuments.heldBefore(vanishClock.now() - VANISH_HOLD_LIMIT_MS)) {
      const step: VanishStep = { action: 'resolving its hold at the limit' };
      try {
        await resolveOverdueVanishedDocument(entry, step);
      } catch (err) {
        if (!vanishedDocuments.has(entry.docName)) {
          reportVanishFault(entry, step, err);
          continue;
        }
        const attempts = (overdueFaults.get(entry.docName) ?? 0) + 1;
        overdueFaults.set(entry.docName, attempts);
        reportVanishFault(entry, step, err, attempts);
        if (attempts >= VANISH_OVERDUE_FAULT_LIMIT) endHoldAfterOverdueFaults(entry, attempts);
      }
    }
  }

  async function resolveOverdueVanishedDocument(
    entry: VanishedDocument,
    step: VanishStep,
  ): Promise<void> {
    const limit = `${VANISH_HOLD_LIMIT_MS / 1000} s`;
    let probe: MarkdownFileProbe | undefined;
    try {
      probe = probeVanishedFile(entry);
    } catch (err) {
      log.error(
        { err, docName: entry.docName, limitMs: VANISH_HOLD_LIMIT_MS },
        `[reconcile] ${entry.docName}: checking its path at the hold limit failed with an internal error; the delete stands as at any hold limit`,
      );
    }
    switch (probe?.kind) {
      case undefined:
        break;
      case 'present':
        step.action = 'taking its returned file in';
        await takeReturnedFile(entry, probe);
        return;
      case 'absent':
        log.warn(
          { docName: entry.docName, probe: probe.kind, limitMs: VANISH_HOLD_LIMIT_MS },
          `[reconcile] ${entry.docName}: its file is gone and no re-check observed the whole tree within ${limit}; the delete stands and unsaved typing is in its history`,
        );
        break;
      case 'unreadable':
        log.warn(
          {
            docName: entry.docName,
            probe: probe.kind,
            code: probe.code,
            limitMs: VANISH_HOLD_LIMIT_MS,
          },
          `[reconcile] ${entry.docName}: a file at its path still cannot be read (${probe.code}) after ${limit}; the hold ends, the document closes and unsaved typing is in its history`,
        );
        break;
      case 'refused':
        log.warn(
          { docName: entry.docName, probe: probe.kind, limitMs: VANISH_HOLD_LIMIT_MS },
          `[reconcile] ${entry.docName}: the entry at its path is still not an admitted Markdown file after ${limit}; the hold ends, the document closes and unsaved typing is in its history`,
        );
        break;
      default: {
        const unhandled: never = probe;
        throw new Error(`unhandled file probe: ${JSON.stringify(unhandled)}`);
      }
    }
    step.action = 'applying the delete at the hold limit';
    await standVanishedDelete(entry, 'unconfirmed');
  }

  function followRecordsAcrossRename(
    oldDocName: string,
    newDocName: string,
    newPath: string,
  ): void {
    const branch = getStorageBranch() ?? 'main';
    const move = { from: oldDocName, to: newDocName, toFile: `${newDocName}${extname(newPath)}` };
    const writer = {
      writerId: FILE_SYSTEM_WRITER.id,
      displayName: FILE_SYSTEM_WRITER.name,
      colorSeed: FILE_SYSTEM_WRITER.id,
    };
    followRenameRecords({
      moves: [move],
      kind: 'file',
      branch,
      writer,
      shadow: undefined,
      notices: docNotices,
    });
    const shadow = shadowRef.current;
    if (!shadow) return;
    void recordOutsideRenameInHistory(shadow, branch, move, writer);
  }

  async function readWriterHeads(shadow: ShadowHandle, branch: string): Promise<string[]> {
    try {
      const raw = await shadowGit(shadow).raw(
        'for-each-ref',
        '--sort=-committerdate',
        '--format=%(objectname)',
        `refs/wip/${branch}/`,
      );
      return raw
        .split('\n')
        .map((line) => line.trim())
        .filter((sha) => /^[0-9a-f]{40}$/.test(sha));
    } catch (err) {
      log.warn(
        { err, branch },
        "[reconcile] rename: could not read the writers' history heads; the move is recorded without them",
      );
      return [];
    }
  }

  async function recordOutsideRenameInHistory(
    shadow: ShadowHandle,
    branch: string,
    move: { from: string; to: string; toFile: string },
    writer: { writerId: string; displayName: string; colorSeed: string },
  ): Promise<void> {
    const anchors = await readWriterHeads(shadow, branch);
    let appended: number;
    try {
      appended = followRenameRecords({
        moves: [move],
        kind: 'file',
        branch,
        writer,
        shadow,
        notices: undefined,
        anchors,
      });
    } catch (err) {
      incrementOutsideRenameRecordFailures();
      log.warn(
        { err, oldDocName: move.from, newDocName: move.to },
        `[reconcile] rename: could not write the rename-log entry for ${move.from} -> ${move.to}; history before the move will not show under the new name`,
      );
      return;
    }
    if (appended === 0) return;
    let flushError: unknown;
    try {
      await persistence.flushContributors();
    } catch (err) {
      flushError = err;
    }
    const recorded = getOrLoadRenameLogIndex(shadow.gitDir).byTo.get(move.to);
    if (recorded !== undefined && recorded.commitSha === '') {
      incrementOutsideRenameClaimFailures();
      log.warn(
        { err: flushError, oldDocName: move.from, newDocName: move.to },
        `[reconcile] rename: wrote the rename-log entry for ${move.from} -> ${move.to}, but no commit claimed it yet; a later commit by the file-system writer claims it, and the next start drops it if none does`,
      );
      return;
    }
    if (flushError !== undefined) {
      log.warn(
        { err: flushError, oldDocName: move.from, newDocName: move.to },
        '[reconcile] rename: the commit after recording the move failed',
      );
    }
  }

  async function carryLiveTextAcrossRename(
    newDocName: string,
    newPath: string,
    base: string,
    live: string,
    diskContent: string,
  ): Promise<boolean> {
    let connection: Awaited<ReturnType<Hocuspocus['openDirectConnection']>> | undefined;
    try {
      connection = await hocuspocus.openDirectConnection(newDocName);
      applyToDoc(newDocName, live);
      setReconciledBase(newDocName, base);
      if (diskContent !== base) {
        await handleDiskEvent({
          kind: 'update',
          path: newPath,
          docName: newDocName,
          content: diskContent,
        });
      }
      log.info({ newDocName }, `[reconcile] rename: unsaved typing carried into ${newDocName}`);
      return true;
    } catch (err) {
      log.error(
        { err, newDocName },
        `[reconcile] rename: could not carry unsaved typing into ${newDocName}; it is in the rename checkpoint`,
      );
      return false;
    } finally {
      await connection?.disconnect();
    }
  }

  function tombstoneResidentsResolvingIntoPrivateState(branch: string): void {
    for (const [docName, document] of hocuspocus.documents) {
      if (isReservedForUserTree(docName)) continue;
      if (document.getMap('lifecycle').get('status') !== undefined) continue;
      try {
        const filePath = safeContentPath(docName, contentDir);
        if (!existsSync(filePath)) continue;
        if (!canonicalContentPathIsRefused(filePath, realpathSync(filePath), contentDir)) continue;
        rescueUnflushedEditsBeforeTeardown(docName, branch, 'branch-switch');
        document.getMap('lifecycle').set('status', 'deleted-upstream');
        log.warn(
          { docName, branch },
          `[branch-switch] tombstone: ${docName} resolves outside the content dir or into private state on ${branch}`,
        );
      } catch (err) {
        log.error({ err, docName }, `[branch-switch] could not check where ${docName} resolves`);
      }
    }
  }

  const rescueUnflushedEditsBeforeTeardown = (
    docName: string,
    branch: string,
    site: 'delete' | 'rename' | 'branch-switch',
    followedByContentLoss = false,
  ): boolean => {
    const reconciledBase = getReconciledBase(docName);
    const ours = serializeDoc(docName) ?? '';
    const isDirty = reconciledBase === undefined ? ours !== '' : ours !== reconciledBase;
    if (!isDirty) return isDirty;
    mintExternalChangeRescue(docName, ours, branch, site, '', followedByContentLoss);
    return isDirty;
  };

  function dissolveNonGitConflicts(docName: string): void {
    conflicts.dissolveReconcile(docName);
    conflicts.dissolveWorkingTree(conflicts.fileOf(docName));
  }

  const reportInsertDedupSkipped = (
    docName: string,
    outcome: ReconcileOutcome,
    ours: string,
    theirs: string,
  ): void => {
    if (outcome.kind !== 'merged' && outcome.kind !== 'both-kept') return;
    if (!outcome.dedupSkipped) return;
    incrementReconcileInsertDedupSkipped();
    log.warn(
      {
        docName,
        oursLen: ours.length,
        theirsLen: theirs.length,
        newLen: outcome.newContent.length,
      },
      `[reconcile] ${docName} insert-group dedup skipped (LCS cell cap); union emitted with possible same-block duplication`,
    );
  };

  const applyDiskAuthoritativeIngest = async (
    docName: string,
    theirs: string,
    priorBase: string | undefined,
  ): Promise<DiskIntakeOutcome> => {
    const baseAbsent = priorBase === undefined;
    incrementDiskAuthoritativeIngest();
    const ours = serializeDoc(docName) ?? '';
    const branch = getStorageBranch() ?? 'main';
    const theirsH = contentHash(theirs).slice(0, 6);
    const liveOnlyContentAtRisk = ours !== '' && ours !== theirs;
    const rescue: 'not-needed' | 'rescued' | 'lost' = !liveOnlyContentAtRisk
      ? 'not-needed'
      : rescueDocToShadowBuffer(docName, 'disk-authoritative-ingest');
    if (liveOnlyContentAtRisk) {
      mintExternalChangeRescue(docName, ours, branch, 'disk-update', theirsH, true);
    }
    const oursH = contentHash(ours).slice(0, 6);
    const baseToken = baseAbsent ? 'absent' : 'blockless';
    let applyError: unknown;
    let ingested = false;
    try {
      applyToDoc(docName, theirs);
      dissolveNonGitConflicts(docName);
      ingested = true;
    } catch (e) {
      applyError = e;
      incrementDiskAuthoritativeIngestApplyFailures();
      log.error(
        { err: e, docName },
        `[reconcile] failed to apply disk-authoritative ingest to Y.Doc for ${docName}`,
      );
      mintExternalChangeRescue(docName, theirs, branch, 'disk-update', theirsH, true);
      dissolveNonGitConflicts(docName);
      let surviving: string | undefined;
      try {
        surviving = serializeDoc(docName) ?? undefined;
      } catch (readError) {
        log.error(
          { err: readError, docName },
          `[reconcile] unable to read ${docName} back after a failed disk-authoritative ingest; treating the live content as lost`,
        );
      }
      if (surviving === theirs) setReconciledBase(docName, theirs);
      else durabilityState.restoreReconciledBase(docName, priorBase);
      if (rescue === 'lost' && surviving !== ours) {
        incrementDiskAuthoritativeIngestUnrescued();
        log.warn(
          {
            docName,
            baseAbsent,
            reason: 'no-base',
            ours: oursH,
            theirs: theirsH,
            result: 'clean-unrescued',
            rescue,
            applyFailed: true,
          },
          `[reconcile] ${docName} base=${baseToken} reason=no-base result=clean-unrescued ours=${oursH} theirs=${theirsH} rescue=${rescue} applyFailed=true`,
        );
      }
    }
    if (ingested) {
      const result = rescue === 'lost' ? 'clean-unrescued' : 'clean';
      if (rescue === 'lost') incrementDiskAuthoritativeIngestUnrescued();
      const emit = rescue === 'lost' ? log.warn.bind(log) : log.info.bind(log);
      emit(
        {
          docName,
          baseAbsent,
          reason: 'no-base',
          ours: oursH,
          theirs: theirsH,
          result,
          rescue,
        },
        `[reconcile] ${docName} base=${baseToken} reason=no-base result=${result} ours=${oursH} theirs=${theirsH} rescue=${rescue}`,
      );
      await recordUpsertAfterIntake(docName, theirs);
      return liveOnlyContentAtRisk
        ? { kind: 'applied', merge: 'disk-replaced' }
        : { kind: 'applied' };
    }
    return { kind: 'failed', error: applyError };
  };

  const recordUpsertAfterIntake = async (docName: string, theirs: string): Promise<void> => {
    try {
      await derivedDocumentIndex.recordDiskUpsert(docName, theirs);
    } catch (err) {
      log.warn(
        { err, docName },
        `[reconcile] ${docName}: the derived index could not record the disk version`,
      );
    }
  };

  type DiskIntakeOutcome =
    | { readonly kind: 'applied'; readonly merge?: StoreIntakeMerge }
    | { readonly kind: 'nothing-to-take' }
    | { readonly kind: 'conflict' }
    | { readonly kind: 'failed'; readonly error: unknown };

  function assertNeverDiskIntakeOutcome(outcome: never): never {
    throw new Error(`unhandled disk intake outcome: ${(outcome as { kind: string }).kind}`);
  }

  function assertNeverReconcileOutcome(outcome: never): never {
    throw new Error(`unhandled reconcile outcome: ${(outcome as { kind: string }).kind}`);
  }

  async function intakeDiskUpdate(
    event: Extract<DiskEvent, { kind: 'update' }>,
  ): Promise<DiskIntakeOutcome> {
    const { docName, content: theirs } = event;
    onUpstreamAdd(docName);
    if (indexedMetadataChanged(event.previousIndexedFields, theirs, docName)) {
      scheduleIndexRegeneration(docName);
    }
    if (conflicts.findByDocName(docName)?.kind === 'merge-native') {
      try {
        await conflicts.pruneMergeNativeAgainstGit();
      } catch (err) {
        log.warn({ err, docName }, '[reconcile] conflict prune against git failed');
      }
    }

    const document = hocuspocus.documents.get(docName);
    if (!document) {
      if (!refuseStaleExternalWrite(durabilityState, undefined, docName, theirs, conflicts)) {
        durabilityState.refreshReceiptWithoutBase(docName, theirs);
      }
      await derivedDocumentIndex.recordDiskUpsert(docName, theirs);
      return { kind: 'nothing-to-take' };
    }
    if (reviveFrozenResident(docName, theirs) !== 'not-frozen') {
      await derivedDocumentIndex.recordDiskUpsert(docName, theirs);
      return { kind: 'nothing-to-take' };
    }

    const theirsHash = contentHash(theirs);
    const receiptIntake = classifyIntakeAgainstReceipt({
      receiptHash: durabilityState.getReceipt(docName)?.hash,
      eventHash: theirsHash,
      isRecentOwnWrite: durabilityState.isRecentOwnWrite(docName, theirsHash),
      readDiskHash: () => {
        try {
          return contentHash(readFileSync(event.path, 'utf-8'));
        } catch {
          return null;
        }
      },
    });
    const receiptSkip = receiptIntakeSkipOf(receiptIntake);
    if (receiptSkip !== null && durabilityState.getStaleExternalWrite(docName) === undefined) {
      incrementReceiptIntakeSkip(receiptSkip);
      log.debug(
        { docName, receiptIntake },
        `[reconcile] ${docName}: the disk bytes match its receipt (${receiptIntake}); nothing to take in`,
      );
      conflicts.dissolveReconcile(docName);
      await recordUpsertAfterIntake(docName, theirs);
      return { kind: 'nothing-to-take' };
    }

    const base = getReconciledBase(docName);
    const ours = serializeDoc(docName) ?? base ?? '';

    if (refuseStaleExternalWrite(durabilityState, document, docName, theirs, conflicts, ours)) {
      await recordUpsertAfterIntake(docName, theirs);
      return { kind: 'conflict' };
    }

    if (base === undefined) {
      return applyDiskAuthoritativeIngest(docName, theirs, undefined);
    }

    const result = reconcile({ docName, base, ours, theirs });

    const baseH = contentHash(base).slice(0, 6);
    const oursH = contentHash(ours).slice(0, 6);
    const theirsH = contentHash(theirs).slice(0, 6);
    const oursLen = ours.length;
    const theirsLen = theirs.length;
    const newLen =
      result.kind === 'clean' || result.kind === 'merged' || result.kind === 'both-kept'
        ? result.newContent.length
        : undefined;
    const delta = newLen === undefined ? undefined : newLen - Math.max(oursLen, theirsLen);
    const sizeSuffix = newLen === undefined ? '' : ` newLen=${newLen} delta=${delta}`;
    log.info(
      {
        docName,
        base: baseH,
        ours: oursH,
        theirs: theirsH,
        result: result.kind,
        oursLen,
        theirsLen,
        ...(newLen === undefined ? {} : { newLen, delta }),
      },
      `[reconcile] ${docName} base=${baseH} ours=${oursH} theirs=${theirsH} result=${result.kind} oursLen=${oursLen} theirsLen=${theirsLen}${sizeSuffix}`,
    );

    reportInsertDedupSkipped(docName, result, ours, theirs);

    switch (result.kind) {
      case 'noop':
        conflicts.dissolveReconcile(docName);
        await recordUpsertAfterIntake(docName, theirs);
        return { kind: 'nothing-to-take' };

      case 'clean':
        try {
          applyToDoc(docName, result.newContent);
        } catch (e) {
          log.error(
            { err: e, docName },
            `[reconcile] failed to apply clean content to Y.Doc for ${docName}`,
          );
          setReconciledBase(docName, base);
          conflicts.dissolveReconcile(docName);
          return { kind: 'failed', error: e };
        }
        setReconciledBase(docName, result.newContent);
        incrementReconcile();
        conflicts.dissolveReconcile(docName);
        await recordUpsertAfterIntake(docName, theirs);
        return { kind: 'applied', merge: 'clean' };

      case 'merged':
        try {
          applyToDoc(docName, result.newContent);
        } catch (e) {
          log.error(
            { err: e, docName },
            `[reconcile] failed to apply merged content to Y.Doc for ${docName}`,
          );
          setReconciledBase(docName, base);
          conflicts.dissolveReconcile(docName);
          return { kind: 'failed', error: e };
        }
        setReconciledBase(docName, theirs);
        incrementReconcile();
        conflicts.dissolveReconcile(docName);
        await recordUpsertAfterIntake(docName, theirs);
        return { kind: 'applied', merge: 'merged' };

      case 'both-kept': {
        try {
          applyToDoc(docName, result.newContent);
        } catch (e) {
          log.error(
            { err: e, docName },
            `[reconcile] failed to apply both-kept content to Y.Doc for ${docName}; raising the conflict`,
          );
          setReconciledBase(docName, base);
          incrementConflict();
          conflicts.raise({
            kind: 'reconcile',
            file: conflicts.fileOf(docName),
            reason: 'merged-with-markers',
            stages: { base, ours, theirs },
          });
          return { kind: 'failed', error: e };
        }
        mergeHistory.bothKept(docName, { ours, theirs }, result.kept);
        setReconciledBase(docName, theirs);
        incrementReconcile();
        reportReconcileBothKept(docName, result.kept, 'watcher');
        conflicts.dissolveReconcile(docName);
        await recordUpsertAfterIntake(docName, theirs);
        return { kind: 'applied', merge: 'both-kept' };
      }

      case 'refused': {
        if (result.reason === 'no-base') {
          return applyDiskAuthoritativeIngest(docName, theirs, base);
        }
        reportReconcileCheckFailed(docName, result, 'watcher');
        if (result.reason === 'check-failed' || result.reason === 'too-large') {
          if (
            await mergeHistory.keptLive(docName, { side: 'theirs', bytes: theirs }, result.reason)
          ) {
            setReconciledBase(docName, theirs);
            reportReconcileKeptLive(docName, result.reason, 'watcher');
            conflicts.dissolveReconcile(docName);
            await recordUpsertAfterIntake(docName, theirs);
            return { kind: 'applied', merge: 'kept-live' };
          }
        }
        incrementConflict();
        conflicts.raise({
          kind: 'reconcile',
          file: conflicts.fileOf(docName),
          reason: wireReasonForRefusal(result.reason),
          stages: { base, ours, theirs },
        });
        return { kind: 'conflict' };
      }
      default:
        return assertNeverReconcileOutcome(result);
    }
  }

  const bufferedRemovalScopes = new Map<
    Extract<DiskEvent, { kind: 'delete' | 'rename' }>,
    ReturnType<typeof beginRemoval>
  >();

  async function handleDiskEvent(
    event: DiskEvent,
    preparedRemoval = event.kind === 'delete' || event.kind === 'rename'
      ? (bufferedRemovalScopes.get(event) ??
        beginRemoval(
          event.kind === 'delete' ? event.docName : event.oldDocName,
          getMarkdownRemovalCurrentness(event),
        ))
      : undefined,
  ): Promise<void> {
    try {
      switch (event.kind) {
        case 'create': {
          const facts = getMarkdownEventFacts(event);
          const createdHash = contentHash(event.content);
          const paired = vanishedDocuments.matchCreate({
            docName: event.docName,
            identity: facts.identity,
            size: facts.size,
            modified: facts.modified,
            hash: createdHash,
            content: event.content,
          });
          if (paired) {
            releaseVanished(paired.vanished.docName);
            if (paired.by === 'same-name') {
              recordVanishOutcome('recreated');
              log.info(
                { docName: event.docName },
                `[reconcile] ${event.docName}: its file came back; taking it in as an update`,
              );
              await handleDiskEvent({
                kind: 'update',
                path: event.path,
                docName: event.docName,
                content: event.content,
              });
              flushReleasedStores();
              break;
            }
            const carry = durabilityState.beginRenameCarry(paired.vanished.docName);
            try {
              persistence.discardDeferredStore(paired.vanished.docName, {
                kind: 'renamed-outside',
                to: event.docName,
                carry,
              });
              recordVanishOutcome(paired.by === 'identity' ? 'paired-identity' : 'paired-hash');
              await handleDiskEvent({
                kind: 'rename',
                oldPath: paired.vanished.path,
                newPath: event.path,
                oldDocName: paired.vanished.docName,
                newDocName: event.docName,
                content: event.content,
              });
            } finally {
              durabilityState.abandonRenameCarry(paired.vanished.docName);
            }
            break;
          }
          vanishedDocuments.rememberCreate({
            docName: event.docName,
            path: event.path,
            identity: facts.identity,
            size: facts.size,
            modified: facts.modified,
            hash: createdHash,
            at: vanishClock.now(),
          });
          log.info({ docName: event.docName }, `[reconcile] create: ${event.docName}`);
          reviveFrozenResident(event.docName, event.content);
          await derivedDocumentIndex.recordDiskUpsert(event.docName, event.content);
          signalChannel('files');
          scheduleIndexRegeneration(event.docName);
          onUpstreamAdd(event.docName);
          break;
        }

        case 'update': {
          await intakeDiskUpdate(event);
          break;
        }

        case 'delete': {
          const { docName } = event;
          const removal =
            preparedRemoval ?? beginRemoval(docName, getMarkdownRemovalCurrentness(event));
          bufferedRemovalScopes.delete(event);
          try {
            const namespaceCurrent = removal.namespaceCurrent();
            const residentCurrent = removal.residentCurrent();
            if (!namespaceCurrent && !residentCurrent) {
              log.debug(
                { docName, source: 'watcher-delete', namespaceCurrent, residentCurrent },
                `[reconcile] delete skipped: ${docName} (stale removal)`,
              );
              return;
            }
            if (
              namespaceCurrent &&
              residentCurrent &&
              removal.document &&
              !settledVanishEvents.has(event) &&
              (await holdVanishedDocument(event))
            ) {
              return;
            }
            if (namespaceCurrent) {
              dissolveNonGitConflicts(docName);
              commentDocHooksRef.current?.deleted(docName);
            }
            const { document } = removal;
            const isDirty =
              residentCurrent && document
                ? rescueUnflushedEditsBeforeTeardown(
                    docName,
                    getStorageBranch() ?? 'main',
                    'delete',
                    true,
                  )
                : false;
            if (residentCurrent) {
              document?.getMap('lifecycle').set('status', 'deleted-upstream');
              durabilityState.endRenameCarry(docName);
            }
            if (namespaceCurrent) deleteReconciledBase(docName);
            if (namespaceCurrent) await derivedDocumentIndex.recordDiskDelete(docName);
            if (!removal.namespaceCurrent() && !removal.residentCurrent()) {
              log.debug(
                {
                  docName,
                  source: 'watcher-delete',
                  namespaceCurrent: false,
                  residentCurrent: false,
                },
                `[reconcile] delete skipped: ${docName} (stale removal)`,
              );
              return;
            }
            log.info(
              { docName, isDirty, source: 'watcher-delete' },
              `[reconcile] delete: ${docName} (dirty=${isDirty})`,
            );
            if (removal.residentCurrent() && document) {
              hocuspocus.closeConnections(docName);
              await forceUnloadDocument(document, removal.residentCurrent);
            }
            if (!removal.namespaceCurrent()) {
              log.debug(
                {
                  docName,
                  source: 'watcher-delete',
                  namespaceCurrent: false,
                  residentCurrent: removal.residentCurrent(),
                },
                `[reconcile] delete: ${docName} not recorded as removed (stale removal)`,
              );
              return;
            }
            signalChannel('files');
            onUpstreamDelete(docName);
            scheduleIndexRegenerationAfterRemoval(docName);
            console.info(
              JSON.stringify({
                event: 'recently-removed-docs-populate',
                docName,
                kind: 'deleted',
                source: 'watcher-delete',
              }),
            );
          } finally {
            removal.dispose();
          }
          break;
        }

        case 'rename': {
          const { oldDocName, newDocName, content } = event;
          const removal =
            preparedRemoval ?? beginRemoval(oldDocName, getMarkdownRemovalCurrentness(event));
          bufferedRemovalScopes.delete(event);
          durabilityState.beginRenameCarry(oldDocName);
          let carriedThrough: WrittenThrough | null = null;
          let retiredResident = false;
          try {
            const document = removal.document;
            const residentBeforeRename = removal.residentCurrent() && document ? document : null;
            const liveBeforeRename = residentBeforeRename ? serializeDoc(oldDocName) : null;
            const textBeforeRename = residentBeforeRename
              ? writtenThroughOf(residentBeforeRename)
              : null;
            const baseBeforeRename = getReconciledBase(oldDocName);
            const freezeAsRenamed = (doc: Document): void => {
              const lifecycle = doc.getMap('lifecycle');
              lifecycle.set('status', 'renamed');
              lifecycle.set('newPath', newDocName);
            };
            const isDirty =
              removal.residentCurrent() && document
                ? rescueUnflushedEditsBeforeTeardown(
                    oldDocName,
                    getStorageBranch() ?? 'main',
                    'rename',
                  )
                : false;
            if (removal.residentCurrent() && document) freezeAsRenamed(document);
            if (removal.namespaceCurrent()) {
              dissolveNonGitConflicts(oldDocName);
              deleteReconciledBase(oldDocName);
              persistence.forgetObservedFile(oldDocName);
              onUpstreamRename(oldDocName, newDocName);
            }
            setReconciledBase(newDocName, content);
            log.info(
              { oldDocName, newDocName, isDirty },
              `[reconcile] rename: ${oldDocName} → ${newDocName} (dirty=${isDirty})`,
            );
            signalChannel('files');
            onUpstreamAdd(newDocName);
            try {
              if (removal.namespaceCurrent()) {
                await derivedDocumentIndex.recordDiskRename(oldDocName, newDocName, content);
              } else {
                await derivedDocumentIndex.recordDiskUpsert(newDocName, content);
              }
            } catch (err) {
              log.error(
                { oldDocName, newDocName, err },
                `[reconcile] rename: index update failed for ${oldDocName} → ${newDocName}; completing client teardown anyway`,
              );
            }
            const loadedDuringIndex = removal.namespaceCurrent()
              ? hocuspocus.documents.get(oldDocName)
              : undefined;
            const lateResident = loadedDuringIndex !== document ? loadedDuringIndex : undefined;
            if (lateResident) freezeAsRenamed(lateResident);
            reviveFrozenResident(newDocName, content);
            scheduleIndexRegeneration(newDocName);
            if (removal.namespaceCurrent()) {
              followRecordsAcrossRename(oldDocName, newDocName, event.newPath);
            }
            if (liveBeforeRename !== null && baseBeforeRename !== undefined) {
              const carried =
                liveBeforeRename === baseBeforeRename ||
                (await carryLiveTextAcrossRename(
                  newDocName,
                  event.newPath,
                  baseBeforeRename,
                  liveBeforeRename,
                  content,
                ));
              if (carried) carriedThrough = textBeforeRename;
            }
            const retired = removal.residentCurrent() && document ? document : lateResident;
            retiredResident = Boolean(retired);
            if (retired) {
              const closedConnections = retired.getConnectionsCount();
              /* WARN: the `delete` branch above and `captureAndCloseDocuments` pair their
               close with `forceUnloadDocument`; this branch does not, so the frozen doc
               stays resident under the old name and template-watcher-capabilities.test.ts
               pins that residency. The destination clear above is what stops a move back
               to this path from being served that stale frozen doc. */
              hocuspocus.closeConnections(oldDocName);
              await sessionManager.closeAllForDoc(oldDocName);
              if (closedConnections > 0) {
                log.info(
                  { oldDocName, newDocName, closedConnections },
                  `[reconcile] rename: closed ${closedConnections} connection(s) on ${oldDocName}`,
                );
              }
            }
            if (!removal.namespaceCurrent()) {
              log.debug(
                {
                  docName: oldDocName,
                  newDocName,
                  source: 'watcher-rename',
                  namespaceCurrent: false,
                  residentCurrent: removal.residentCurrent(),
                },
                `[reconcile] rename: ${oldDocName} not recorded as removed (stale removal)`,
              );
              break;
            }
            console.info(
              JSON.stringify({
                event: 'recently-removed-docs-populate',
                from: oldDocName,
                to: newDocName,
                kind: 'renamed',
                source: 'watcher-rename',
              }),
            );
            scheduleIndexRegenerationAfterRemoval(oldDocName);
          } finally {
            durabilityState.settleRenameCarry(oldDocName, carriedThrough);
            if (!retiredResident) durabilityState.endRenameCarry(oldDocName);
            removal.dispose();
          }
          break;
        }

        case 'conflict': {
          const { docName } = event;
          const document = hocuspocus.documents.get(docName);
          if (!document) return;

          const priorBase = getReconciledBase(docName) ?? '';
          const ours = serializeDoc(docName);
          if (ours !== null) {
            setReconciledBase(docName, ours);
          } else {
            log.warn(
              { docName },
              `[reconcile] case 'conflict': serializeDoc returned null for ${docName}; reconciledBase snapshot skipped — post-resolution reconcile may degrade to 3-way merge`,
            );
          }

          conflicts.raise({
            kind: 'reconcile',
            file: conflicts.fileOf(docName),
            reason: 'disk-markers',
            stages: { base: priorBase, ours: ours ?? priorBase, theirs: event.content },
          });
          log.info({ docName }, `[reconcile] conflict markers detected: ${docName}`);
          break;
        }

        case 'asset-create': {
          basenameIndex.add(event.relativePath);
          signalChannel('files');
          scheduleAssetRerender(basename(event.relativePath));
          break;
        }
        case 'asset-delete': {
          basenameIndex.remove(event.relativePath);
          signalChannel('files');
          scheduleAssetRerender(basename(event.relativePath));
          break;
        }
        case 'folder-create':
        case 'folder-delete': {
          signalChannel('files');
          scheduleSubdirectoryIndexRegeneration(event.relativePath);
          break;
        }
        case 'file-create':
        case 'file-update': {
          await derivedDocumentIndex.recordFileTargetUpsert(event.relativePath);
          invalidateReferencedAssetsCache?.();
          signalChannel('files');
          await takeInEnginelessChange(event.relativePath);
          break;
        }
        case 'file-delete': {
          await derivedDocumentIndex.recordFileTargetDelete(event.relativePath);
          invalidateReferencedAssetsCache?.();
          signalChannel('files');
          break;
        }
        default:
          assertNeverDiskEvent(event);
      }
    } catch (err) {
      const label = diskEventLabel(event);
      log.error(
        { err, kind: event.kind, label },
        `[reconcile] failed to handle ${event.kind} for ${label}`,
      );
    }
  }

  const eventBuffer: DiskEvent[] = [];

  async function onDiskEvent(event: DiskEvent): Promise<void> {
    if (documentAdmissionClosed) return;
    if ((event.kind === 'delete' || event.kind === 'rename') && !bufferedRemovalScopes.has(event)) {
      bufferedRemovalScopes.set(
        event,
        beginRemoval(
          event.kind === 'delete' ? event.docName : event.oldDocName,
          getMarkdownRemovalCurrentness(event),
        ),
      );
    }
    if (isBatchInProgress() || draining !== null) {
      eventBuffer.push(event);
      return;
    }
    await handleDiskEvent(event);
  }

  let draining: Promise<void> | null = null;

  function drainEventBuffer(): Promise<void> {
    if (draining) return draining;
    if (eventBuffer.length === 0) return Promise.resolve();
    const done = Promise.withResolvers<void>();
    draining = done.promise;
    void (async () => {
      try {
        while (eventBuffer.length > 0) {
          const events = eventBuffer.splice(0, eventBuffer.length);
          for (const event of events) await handleDiskEvent(event);
        }
        done.resolve();
      } catch (err) {
        done.reject(err);
      } finally {
        draining = null;
      }
    })();
    return done.promise;
  }

  function disposeBufferedRemovalScopes(): void {
    for (const scope of bufferedRemovalScopes.values()) scope.dispose();
    bufferedRemovalScopes.clear();
  }

  let watcher: WatcherHandle | null = null;

  function isEnginelessDoc(docName: string): boolean {
    return isMermaidDoc(docName) || isExcalidrawDoc(docName) || isEditableTextDoc(docName);
  }

  async function takeInEnginelessChange(docName: string): Promise<boolean> {
    if (!isEnginelessDoc(docName)) return false;
    const document = hocuspocus.documents.get(docName);
    if (!document) return false;
    const outcome = await applyExternalEnginelessChange(
      document,
      docName,
      persistence.mermaidPersistenceCtx,
    );
    return outcome !== 'unchanged';
  }

  async function refreshDocumentsFromDisk(
    docNames: readonly string[],
    trigger: DocumentRefreshTrigger,
  ): Promise<DocumentRefreshResult> {
    if (!watcher) return { checked: 0, found: 0 };
    const aliases = watcher.getAliasMap();
    const index = watcher.getFileIndex();
    const paths: string[] = [];
    const engineless = { checked: 0, found: 0 };
    for (const requested of new Set(docNames)) {
      const docName = aliases.get(requested) ?? requested;
      if (isReservedForUserTree(docName)) continue;
      if (isEnginelessDoc(docName)) {
        engineless.checked++;
        if (await takeInEnginelessChange(docName)) engineless.found++;
        continue;
      }
      const indexed = index.get(docName)?.canonicalPath;
      if (indexed !== undefined) {
        paths.push(indexed);
        continue;
      }
      try {
        paths.push(safeContentPath(docName, contentDir));
      } catch (err) {
        log.debug(
          { err, trigger },
          '[reconcile] skipped a re-read for a name outside the content tree',
        );
      }
    }
    const rechecked =
      paths.length === 0 ? { checked: 0, found: 0 } : await watcher.recheckPaths(paths);
    const result = {
      checked: rechecked.checked + engineless.checked,
      found: rechecked.found + engineless.found,
    };
    const summary = { trigger, ...result };
    if (result.found > 0)
      log.info(summary, `[reconcile] re-read on ${trigger} found outside changes`);
    else log.debug(summary, `[reconcile] re-read on ${trigger} found nothing new`);
    return result;
  }
  let syncEngine: SyncEngine | null = null;
  let inflightDestroy: Promise<void> | null = null;
  let retirementStarted = false;
  let watcherReleaseState: {
    phaseErrors: Array<{ phase: string; error: string }>;
    authorityGateReached: boolean;
  } | null = null;

  function recordWatcherReleaseFailure(watched: 'head' | 'content', err: unknown): void {
    const state = watcherReleaseState;
    if (state === null || state.authorityGateReached) {
      log.error({ err, watched }, '[server] late watcher release failed after shutdown');
      return;
    }
    state.phaseErrors.push({
      phase: 'watcher-unsubscribe',
      error: err instanceof Error ? err.message : String(err),
    });
    log.error({ err, watched }, '[server] shutdown phase-1 watcher unsubscribe failed');
  }

  async function adoptWatcher<T extends { unsubscribe(): Promise<void> }>(
    start: () => Promise<T>,
    publish: (handle: T) => void,
    watched: 'head' | 'content',
  ): Promise<void> {
    if (retirementStarted) return;
    const handle = await start();
    if (retirementStarted) {
      try {
        await handle.unsubscribe();
      } catch (err) {
        recordWatcherReleaseFailure(watched, err);
      }
      return;
    }
    publish(handle);
  }

  const rescueDocToShadowBuffer = (
    docName: string,
    context:
      | 'refused-store-shutdown'
      | 'refused-store-mark'
      | 'flush-timeout'
      | 'disk-authoritative-ingest',
  ): 'rescued' | 'lost' => {
    const shadow = shadowRef.current;
    if (!shadow) {
      log.warn(
        { docName, context },
        `[rescue] shadow repo unavailable — cannot buffer ${docName} (${context})`,
      );
      incrementRescueBufferWriteFailures();
      return 'lost';
    }
    try {
      const ours = isPersistenceExcludedDoc(docName)
        ? (hocuspocus.documents.get(docName)?.getText('source').toString() ?? null)
        : serializeDoc(docName);
      if (ours === null) {
        log.warn(
          { docName, context },
          `[rescue] skipping ${docName} — document dropped from map mid-rescue (${context})`,
        );
        incrementRescueBufferWriteFailures();
        return 'lost';
      }
      const rescuePath = safeRescuePath(shadow.gitDir, docName);
      if (!rescuePath) {
        log.warn(
          { docName, gitDir: shadow.gitDir, context },
          `[rescue] path-traversal guard rejected docName: ${docName} (${context})`,
        );
        incrementRescueBufferWriteFailures();
        return 'lost';
      }
      tracedMkdirSync(dirname(rescuePath), { recursive: true });
      tracedWriteFileSync(rescuePath, ours, 'utf-8');
      incrementRescueBuffer();
      log.info({ docName, context }, `[rescue] rescue buffer saved (${context}): ${docName}`);
      return 'rescued';
    } catch (e) {
      log.error(
        { err: e, docName, context },
        `[rescue] failed to write rescue buffer for ${docName} (${context})`,
      );
      incrementRescueBufferWriteFailures();
      return 'lost';
    }
  };

  async function flushAllStoresAndWait(timeoutMs: number): Promise<void> {
    if (hocuspocus.documents.size === 0) return;

    let settled = false;
    let flushDeadline = Date.now() + timeoutMs;
    const raceFloorMs = 250;
    let timeoutState: { id: ReturnType<typeof setTimeout>; expire: () => void } | undefined;
    const allDone = Promise.withResolvers<void>();
    const stopObserving = observeShutdownDocumentRetirements(hocuspocus, () => {
      if (settled) return;
      flushDeadline = Date.now() + timeoutMs;
      if (timeoutState) {
        clearTimeout(timeoutState.id);
        timeoutState.id = setTimeout(
          timeoutState.expire,
          Math.max(flushDeadline - Date.now(), raceFloorMs),
        );
      }
    });
    const allDoneExtension: Extension = {
      async afterUnloadDocument({ instance }) {
        if (!settled && instance.getDocumentsCount() === 0) {
          settled = true;
          allDone.resolve();
        }
      },
    };
    hocuspocus.configuration.extensions.push(allDoneExtension);

    try {
      const pendingDocNames = Array.from(hocuspocus.documents.keys());

      hocuspocus.closeConnections();
      hocuspocus.flushPendingStores();

      for (const doc of hocuspocus.documents.values()) {
        if (doc.getConnectionsCount() === 0) {
          void hocuspocus.unloadDocument(doc).catch((err: unknown) => {
            console.warn(
              JSON.stringify({
                event: 'ok-shutdown-unload-document-failed',
                docName: doc.name,
                reason: err instanceof Error ? err.message : String(err),
              }),
            );
          });
        }
      }

      while (Date.now() < flushDeadline - raceFloorMs) {
        const unsettled = Array.from(hocuspocus.documents.values()).some(
          (doc) => doc.getConnectionsCount() === 0 && !defaultShouldUnloadDocument(doc),
        );
        if (!unsettled) break;
        await new Promise((r) => setTimeout(r, 25));
      }

      const perDocUnloadFloorMs = 50;
      for (const docName of durabilityState.getRefusedStoreDocNames()) {
        if (isReservedForUserTree(docName)) continue;
        const doc = hocuspocus.documents.get(docName);
        if (!doc) continue;
        if (!defaultShouldUnloadDocument(doc)) continue;
        if (flushDeadline - Date.now() < perDocUnloadFloorMs) {
          log.warn(
            { docName },
            `[rescue] refused-store pass out of budget before ${docName}; leaving it and any remaining refused docs to the flush timeout path`,
          );
          break;
        }
        if (rescueDocToShadowBuffer(docName, 'refused-store-shutdown') !== 'rescued') {
          log.warn(
            { docName },
            `[rescue] refused-store doc rescue failed; leaving ${docName} to the flush timeout path`,
          );
          continue;
        }
        let unloadSettled = false;
        let unloadFailed = false;
        const unload = forceUnloadDocument(doc)
          .then(() => {
            unloadSettled = true;
          })
          .catch((err: unknown) => {
            unloadFailed = true;
            unloadSettled = true;
            log.warn(
              { docName, err },
              `[rescue] refused-store doc unload failed at shutdown: ${docName}`,
            );
          });
        let unloadDeadline = 0;
        do {
          const unloadSlice = Math.max(flushDeadline - Date.now(), perDocUnloadFloorMs);
          unloadDeadline += unloadSlice;
          let waitTimer: ReturnType<typeof setTimeout> | undefined;
          try {
            await Promise.race([
              unload,
              new Promise<void>((resolve) => {
                waitTimer = setTimeout(resolve, unloadSlice);
              }),
            ]);
          } finally {
            if (waitTimer !== undefined) clearTimeout(waitTimer);
          }
        } while (!unloadSettled && Date.now() < flushDeadline);
        if (!unloadSettled) {
          log.warn(
            { docName, unloadDeadline },
            `[rescue] refused-store doc unload did not finish before the flush deadline; leaving ${docName} to the flush timeout path`,
          );
          void unload.then(() => {
            if (!unloadFailed) {
              log.info(
                { docName },
                `[rescue] refused-store doc unload completed after the flush deadline: ${docName}`,
              );
            }
          });
          continue;
        }
        if (!unloadFailed) {
          log.info(
            { docName },
            `[rescue] refused-store doc rescued and unloaded at shutdown: ${docName}`,
          );
        }
      }

      const timeout = new Promise<never>((_, reject) => {
        const expire = () => {
          if (settled) return;
          settled = true;
          stopObserving();
          const stillLoaded = Array.from(hocuspocus.documents.keys());

          const rescued: string[] = [];
          const rescueFailed: string[] = [];
          if (shadowRef.current) {
            for (const docName of stillLoaded) {
              if (isReservedForUserTree(docName)) continue;
              if (rescueDocToShadowBuffer(docName, 'flush-timeout') === 'rescued') {
                rescued.push(docName);
              } else {
                rescueFailed.push(docName);
              }
            }
          } else {
            log.warn(
              { stillLoadedCount: stillLoaded.length },
              `[rescue] shadow repo unavailable at flush timeout — ${stillLoaded.length} doc(s) will be lost: [${stillLoaded.join(', ')}]`,
            );
            for (const docName of stillLoaded) {
              if (isReservedForUserTree(docName)) continue;
              rescueFailed.push(docName);
              incrementRescueBufferWriteFailures();
            }
          }

          const rescueSummary =
            rescued.length > 0 || rescueFailed.length > 0
              ? ` — rescued [${rescued.join(', ')}]${
                  rescueFailed.length > 0 ? `, lost [${rescueFailed.join(', ')}]` : ''
                }`
              : '';

          reject(
            new Error(
              `flushAllStoresAndWait timeout: no document retired for ${timeoutMs}ms — ${stillLoaded.length}/${pendingDocNames.length} docs did not unload: [${stillLoaded.join(', ')}]${rescueSummary}`,
            ),
          );
        };
        timeoutState = {
          id: setTimeout(expire, Math.max(flushDeadline - Date.now(), raceFloorMs)),
          expire,
        };
      });

      await Promise.race([allDone.promise, timeout]);
    } finally {
      settled = true;
      stopObserving();
      const extensions = hocuspocus.configuration.extensions;
      const index = extensions.indexOf(allDoneExtension);
      if (index !== -1) extensions.splice(index, 1);
      if (timeoutState) clearTimeout(timeoutState.id);
    }
  }

  async function destroy(): Promise<void> {
    if (inflightDestroy) return inflightDestroy;
    retirementStarted = true;

    inflightDestroy = (async () => {
      const t0 = Date.now();
      const phaseErrors: Array<{ phase: string; error: string }> = [];
      const releaseState = { phaseErrors, authorityGateReached: false };
      watcherReleaseState = releaseState;
      const graceShareMs = Math.min(destroyTimeoutMs, DEFAULT_SIGTERM_GRACE_MS / 5);
      const preludeDeadline = Date.now() + graceShareMs;
      const preludeRemaining = () => Math.max(1, preludeDeadline - Date.now());
      const joinPrelude = async <T>(operation: Promise<T>, phase: string): Promise<T> => {
        let timer: ReturnType<typeof setTimeout> | undefined;
        try {
          return await Promise.race([
            operation,
            new Promise<never>((_, reject) => {
              timer = setTimeout(
                () => reject(new Error(`${phase} did not retire before the pre-flush deadline`)),
                preludeRemaining(),
              );
            }),
          ]);
        } finally {
          clearTimeout(timer);
        }
      };
      shutdownAllowsUnload = true;
      const authShutdown = Promise.allSettled([shutdownLocalOps()]);
      let authResult: PromiseSettledResult<void> | undefined;
      try {
        [authResult] = await joinPrelude(authShutdown, 'mutation-drain');
      } catch (err) {
        phaseErrors.push({ phase: 'mutation-drain', error: String(err) });
        log.error({ err }, '[server] shutdown mutation drain failed');
      }
      vanishClock.clearTimeout(vanishRecheckTimer);
      vanishRecheckTimer = null;
      supersedeBranchSwitchFollowUps();
      for (const entry of vanishedDocuments.all()) {
        persistence.discardDeferredStore(entry.docName, { kind: 'shutdown' });
        rescueUnflushedEditsBeforeTeardown(
          entry.docName,
          getStorageBranch() ?? 'main',
          'delete',
          true,
        );
        recordVanishOutcome('shutdown');
        durabilityState.releaseStores(entry.docName);
      }
      vanishedDocuments.clear();
      durabilityState.endAllRenameCarries();
      reportedUnreadableReturns.clear();
      overdueFaults.clear();
      documentAdmissionClosed = true;
      disposeBufferedRemovalScopes();
      for (const removals of activeRemovals.values()) {
        for (const removal of removals) {
          removal.namespaceAllowed = false;
          removal.residentAllowed = false;
        }
      }
      activeRemovals.clear();
      residentOccurrences = new WeakMap();

      try {
        await joinPrelude(closeIndexRegeneration(), 'generated-index');
      } catch (err) {
        log.warn({ err }, '[index] generated index shutdown drain failed');
        phaseErrors.push({ phase: 'generated-index-drain', error: String(err) });
      }

      for (const unregister of unregisterWorkloadProviders.splice(0)) {
        unregister();
      }
      try {
        await joinPrelude(Promise.resolve(stalenessWatchdog?.dispose()), 'staleness-watchdog');
      } catch (err) {
        log.warn({ err }, '[server] staleness watchdog drain failed during destroy');
        phaseErrors.push({ phase: 'staleness-watchdog-drain', error: String(err) });
      }
      stalenessWatchdog = null;

      try {
        markServerLockDraining(lockDir);
      } catch (err) {
        log.warn({ err }, '[server] failed to mark server.lock draining');
      }

      maintenanceCoordinator?.destroy();

      try {
        await joinPrelude(closeShadowHousekeeping(), 'shadow-housekeeping');
      } catch (err) {
        log.warn({ err }, '[shadow-housekeeping] shutdown drain failed');
        phaseErrors.push({ phase: 'shadow-housekeeping-drain', error: String(err) });
      }

      if (removedDocsJournalTimer !== null) {
        clearTimeout(removedDocsJournalTimer);
        removedDocsJournalTimer = null;
      }
      if (removedDocsJournalWritable) {
        try {
          saveRemovedDocsJournal(projectDir, recentlyRemovedDocs.entries());
        } catch (err) {
          log.warn(
            { err },
            '[removed-docs-journal] failed to persist removal journal during shutdown',
          );
          phaseErrors.push({ phase: 'removed-docs-journal-flush', error: String(err) });
        }
      }

      let initTimeoutId: ReturnType<typeof setTimeout> | undefined;
      const initSettled = await Promise.race([
        ready.then(
          () => 'completed' as const,
          (err) => {
            log.debug({ err }, '[server] init incomplete during shutdown');
            return 'failed' as const;
          },
        ),
        new Promise<'timeout'>((r) => {
          initTimeoutId = setTimeout(() => r('timeout'), preludeRemaining());
        }),
      ]);
      if (initTimeoutId !== undefined) clearTimeout(initTimeoutId);
      if (initSettled === 'timeout') {
        log.warn({}, '[server] init did not complete before the pre-flush deadline');
        phaseErrors.push({
          phase: 'initialization-drain',
          error: 'Initialization remains pending',
        });
      }

      let loadDrainTimer: ReturnType<typeof setTimeout> | undefined;
      try {
        await Promise.race([
          Promise.allSettled(hocuspocus.loadingDocuments.values()),
          new Promise<never>((_, reject) => {
            loadDrainTimer = setTimeout(
              () => reject(new Error('Pending document loads did not retire')),
              preludeRemaining(),
            );
          }),
        ]);
      } catch (err) {
        phaseErrors.push({ phase: 'document-load-drain', error: String(err) });
        log.error({ err }, '[server] shutdown document load drain failed');
      } finally {
        clearTimeout(loadDrainTimer);
      }

      const documentCount = hocuspocus.documents.size;
      const releaseWatcher = async (
        release: { unsubscribe(): Promise<void> } | null,
        watched: 'head' | 'content',
      ): Promise<void> => {
        if (release === null) return;
        try {
          await release.unsubscribe();
        } catch (err) {
          recordWatcherReleaseFailure(watched, err);
        }
      };

      try {
        try {
          if (inPlaceRescanTimer) {
            clearTimeout(inPlaceRescanTimer);
            inPlaceRescanTimer = null;
          }
          if (shadowWarmupTimer) {
            clearTimeout(shadowWarmupTimer);
            shadowWarmupTimer = null;
          }
          await releaseWatcher(headWatcher, 'head');
          headWatcher = null;
          await releaseWatcher(watcher, 'content');
          watcher = null;
          for (const { docName, cleanup } of configFileWatcherCleanups) {
            try {
              await cleanup();
            } catch (cfgErr) {
              log.warn(
                { err: cfgErr, docName },
                `[server] failed to stop config-file-watcher for ${docName}`,
              );
            }
          }
          configFileWatcherCleanups.length = 0;
          configFileWatcherResyncs.clear();

          try {
            cc1Broadcaster?.destroy();
            agentPresenceBroadcaster?.destroy();
            if (systemDocConnection) {
              await systemDocConnection.disconnect();
              systemDocConnection = null;
            }
            for (const [docName, connection] of configDocConnections) {
              try {
                await connection.disconnect();
              } catch (configErr) {
                log.warn(
                  { err: configErr, docName },
                  `[server] failed to disconnect ${docName} during shutdown`,
                );
              }
            }
            configDocConnections.clear();
          } catch (err) {
            phaseErrors.push({
              phase: 'cc1-teardown',
              error: err instanceof Error ? err.message : String(err),
            });
            log.error({ err }, '[server] shutdown phase-1b CC1 teardown failed');
          }

          try {
            await sessionManager.closeAll();
          } catch (err) {
            phaseErrors.push({
              phase: 'agent-session-drain',
              error: err instanceof Error ? err.message : String(err),
            });
            log.error({ err }, '[server] shutdown phase-2 agent session drain failed');
          }

          try {
            await destroyParsePool();
          } catch (err) {
            phaseErrors.push({
              phase: 'parse-pool-teardown',
              error: err instanceof Error ? err.message : String(err),
            });
            log.error({ err }, '[server] shutdown phase-2b parse pool teardown failed');
          }

          try {
            await flushAllStoresAndWait(destroyTimeoutMs);
          } catch (err) {
            phaseErrors.push({
              phase: 'flush-all-stores',
              error: err instanceof Error ? err.message : String(err),
            });
            log.error({ err }, '[server] shutdown phase-3 flush failed');
          }

          let derivedIndexCloseTimeoutId: ReturnType<typeof setTimeout> | undefined;
          try {
            await Promise.race([
              derivedDocumentIndex.close(),
              new Promise<never>((_, reject) => {
                derivedIndexCloseTimeoutId = setTimeout(
                  () =>
                    reject(
                      new Error(`derived index close did not settle within ${graceShareMs}ms`),
                    ),
                  graceShareMs,
                );
              }),
            ]);
          } catch (err) {
            phaseErrors.push({
              phase: 'derived-index-close',
              error: err instanceof Error ? err.message : String(err),
            });
            log.error({ err }, '[server] shutdown derived-index close failed');
          } finally {
            if (derivedIndexCloseTimeoutId !== undefined) clearTimeout(derivedIndexCloseTimeoutId);
          }

          let l2TimeoutId: ReturnType<typeof setTimeout> | undefined;
          try {
            await Promise.race([
              (async () => {
                await persistence.flushPendingGitCommit();
                await persistence.waitForPendingCommits();
              })(),
              new Promise<void>((_, reject) => {
                l2TimeoutId = setTimeout(
                  () => reject(new Error('L2 git flush timeout')),
                  destroyTimeoutMs,
                );
              }),
            ]);
          } catch (err) {
            phaseErrors.push({
              phase: 'git-commit-flush',
              error: err instanceof Error ? err.message : String(err),
            });
            log.error({ err }, '[server] shutdown phase-4 git commit flush failed');
          } finally {
            if (l2TimeoutId !== undefined) clearTimeout(l2TimeoutId);
          }
          try {
            if (syncEngine) {
              await syncEngine.destroy();
              syncEngine = null;
            }
          } catch (err) {
            phaseErrors.push({
              phase: 'sync-engine-stop',
              error: err instanceof Error ? err.message : String(err),
            });
            log.error({ err }, '[server] shutdown sync-engine-stop failed');
          }
        } finally {
          if (shadowRef.current) {
            let shadowDrainTimeoutId: ReturnType<typeof setTimeout> | undefined;
            try {
              await Promise.race([
                shadowOpGateFor(shadowRef.current).drain(),
                new Promise<void>((_, reject) => {
                  shadowDrainTimeoutId = setTimeout(
                    () => reject(new Error('shadow mutator drain timeout')),
                    destroyTimeoutMs,
                  );
                }),
              ]);
            } catch (err) {
              phaseErrors.push({
                phase: 'shadow-mutator-drain',
                error: err instanceof Error ? err.message : String(err),
              });
              log.error({ err }, '[server] shutdown phase-5 shadow mutator drain failed');
            } finally {
              if (shadowDrainTimeoutId !== undefined) clearTimeout(shadowDrainTimeoutId);
            }

            try {
              const projectGit = simpleGit({ baseDir: projectDir, timeout: { block: 5_000 } });
              const currentHead = (await projectGit.revparse('HEAD')).trim();
              if (currentHead) {
                writeFileSync(
                  resolve(shadowRef.current.gitDir, 'last-known-head'),
                  currentHead,
                  'utf-8',
                );
              }
            } catch {}

            try {
              destroyShadowRepo(shadowRef.current);
            } catch (err) {
              phaseErrors.push({
                phase: 'shadow-repo-release',
                error: err instanceof Error ? err.message : String(err),
              });
              log.error({ err }, '[server] shutdown phase-5 destroyShadowRepo failed');
            }
          }

          if (authResult?.status === 'rejected') {
            const reason: unknown = authResult.reason;
            const failures = reason instanceof AggregateError ? reason.errors : [reason];
            phaseErrors.push({
              phase: 'local-op-subprocess-shutdown',
              error: failures
                .map((failure) => (failure instanceof Error ? failure.message : String(failure)))
                .join('; '),
            });
            log.error({ err: reason }, '[server] shutdown local-op subprocess drain failed');
          }
          const durationMs = Date.now() - t0;
          releaseState.authorityGateReached = true;
          if (phaseErrors.length === 0) {
            authorityRetired = true;
            try {
              authority.release();
            } catch (err) {
              phaseErrors.push({ phase: 'authority-release', error: String(err) });
              log.error({ err }, '[server] shutdown authority release failed');
            }
            log.info(
              { documentCount, durationMs },
              `[server] shutdown flushed ${documentCount} documents in ${durationMs}ms`,
            );
          } else {
            log.warn(
              { documentCount, durationMs, phaseErrors },
              `[server] shutdown flushed ${documentCount} documents in ${durationMs}ms with ${phaseErrors.length} phase error(s)`,
            );
          }
        }
      } finally {
        try {
          releaseServerLock(lockDir, { deferUnlinkToExit: true });
        } catch (err) {
          phaseErrors.push({
            phase: 'server-lock-release',
            error: err instanceof Error ? err.message : String(err),
          });
          log.error({ err }, '[server] shutdown phase-6 releaseServerLock failed');
        }
        try {
          await shutdownTelemetry();
        } catch (err) {
          phaseErrors.push({
            phase: 'telemetry-shutdown',
            error: err instanceof Error ? err.message : String(err),
          });
        }
        if (watcherReleaseState === releaseState) watcherReleaseState = null;
      }
      if (authResult?.status === 'rejected') throw authResult.reason;
    })();

    return inflightDestroy;
  }

  const degraded: string[] = [];

  async function initAsync(): Promise<void> {
    try {
      loadedPrincipal = await loadPrincipal(projectDir);
      log.info({ principalId: loadedPrincipal.id }, '[server] principal loaded');
    } catch (e) {
      log.warn(
        { err: e },
        '[server] principal load failed — browser writes will use SERVICE_WRITER',
      );
    }

    if (!shadowRef.current) {
      try {
        shadowRef.current = await initShadowRepo(projectDir, { deferGcConfig: true });
        log.info(
          { gitDir: shadowRef.current.gitDir },
          `[server] history repo initialized at ${shadowRef.current.gitDir}`,
        );
        if (isShadowExcludesDegraded(shadowRef.current) && !degraded.includes('shadow-excludes')) {
          degraded.push('shadow-excludes');
        }
      } catch (e) {
        log.error({ err: e }, '[server] history repo init failed');
        degraded.push('shadow-repo');
      }
    }

    if (shadowRef.current) {
      try {
        const renameLogIndex = loadRenameLogIndex(shadowRef.current.gitDir);
        sweepLazyPopOrphans(shadowRef.current.gitDir, renameLogIndex);
        setRenameLogIndex(shadowRef.current.gitDir, renameLogIndex);
        bootRenameLogIndex = renameLogIndex;
        log.info(
          { entries: renameLogIndex.byTo.size },
          `[server] rename log loaded (${renameLogIndex.byTo.size} entries)`,
        );
      } catch (e) {
        log.warn(
          { err: e },
          '[rename-log] boot-time load/sweep failed; rename history unavailable',
        );
      }
    }

    if (shadowRef.current) {
      try {
        const sg = shadowGit(shadowRef.current);
        await sg.raw('rev-parse', '--git-dir');
      } catch (e) {
        const msg = e instanceof Error ? e.message : String(e);
        if (msg.includes('not a git repository') || msg.includes('invalid object')) {
          log.warn({}, '[server] history repo appears corrupted — reinitializing');
          try {
            shadowRef.current = await initShadowRepo(projectDir, { deferGcConfig: true });
            if (
              isShadowExcludesDegraded(shadowRef.current) &&
              !degraded.includes('shadow-excludes')
            ) {
              degraded.push('shadow-excludes');
            }
          } catch (e2) {
            log.error({ err: e2 }, '[server] history repo reinit failed');
            shadowRef.current = undefined;
            if (!degraded.includes('shadow-repo')) degraded.push('shadow-repo');
          }
        } else {
          log.error({ err: e }, '[server] history repo check failed (transient?)');
        }
      }
    }

    if (shadowRef.current && inflightDestroy === null) {
      const warmShadow = shadowRef.current;
      const warmContentRoot = toPosix(relative(projectDir, contentDir)) || '.';
      shadowWarmupTimer = setTimeout(() => {
        shadowWarmupTimer = null;
        void buildWipTree(warmShadow, warmContentRoot).catch((e) => {
          log.debug({ err: e }, '[shadow] fan-out index warm-up failed (non-fatal)');
        });
      }, SHADOW_FANOUT_WARMUP_MS);
      shadowWarmupTimer.unref?.();
    }

    if (shadowRef.current) {
      try {
        const lastKnownHeadPath = resolve(shadowRef.current.gitDir, 'last-known-head');

        let lastKnownHead: string | null = null;
        try {
          lastKnownHead = readFileSync(lastKnownHeadPath, 'utf-8').trim() || null;
        } catch {}

        let currentHead: string | null = null;
        try {
          const projectGit = simpleGit({ baseDir: projectDir, timeout: { block: 10_000 } });
          currentHead = (await projectGit.revparse('HEAD')).trim() || null;
        } catch {}

        if (currentHead !== null) {
          if (currentHead !== lastKnownHead) {
            let branch = 'main';
            try {
              const projectGit = simpleGit({ baseDir: projectDir, timeout: { block: 10_000 } });
              const b = (await projectGit.raw('rev-parse', '--abbrev-ref', 'HEAD')).trim();
              if (b && b !== 'HEAD') branch = b;
            } catch {}

            log.info(
              { lastKnownHead, currentHead, branch },
              `[head-drift] lastKnownHead=${lastKnownHead ?? 'null'}, currentHead=${currentHead}, action=import`,
            );

            try {
              await commitUpstreamImport(
                shadowRef.current,
                contentRoot ?? '',
                lastKnownHead,
                currentHead,
                branch,
              );
              incrementUpstreamImport();
            } catch (e) {
              log.warn({ err: e }, '[head-drift] commitUpstreamImport failed — continuing');
            }
          } else {
            log.info(
              { currentHead },
              `[head-drift] lastKnownHead=${lastKnownHead ?? 'null'}, currentHead=${currentHead}, action=noop`,
            );
          }

          try {
            writeFileSync(lastKnownHeadPath, currentHead, 'utf-8');
          } catch (e) {
            log.warn({ err: e }, '[head-drift] failed to write last-known-head');
          }
        }
      } catch (e) {
        log.warn({ err: e }, '[head-drift] check failed — continuing');
      }
    }

    try {
      const recovery = recoverPendingManagedRename(contentDir, projectDir);
      if (recovery.recovered && recovery.journal) {
        const fromPath =
          recovery.journal.version === 2
            ? recovery.journal.fromPath
            : recovery.journal.sourceDocName;
        const toPath =
          recovery.journal.version === 2
            ? recovery.journal.toPath
            : recovery.journal.destinationDocName;
        log.warn(
          {
            journalVersion: recovery.journal.version,
            fromPath,
            toPath,
            restoredDocNames: recovery.restoredDocNames,
          },
          `[managed-rename] recovered pending rename ${fromPath} -> ${toPath}`,
        );
      }
    } catch (err) {
      log.error({ err }, '[server] managed rename recovery failed');
      degraded.push('managed-rename-recovery');
    }

    try {
      const sweep = cleanupOrphanUploadTempfiles(projectDir);
      if (sweep.deleted > 0 || sweep.errors > 0) {
        log.info(
          {
            scanned: sweep.scanned,
            deleted: sweep.deleted,
            errors: sweep.errors,
          },
          `[upload-tempfile-sweep] swept ${sweep.deleted} orphan tempfile(s)`,
        );
      }
    } catch (err) {
      log.error({ err }, '[server] upload-tempfile sweep failed');
      degraded.push('upload-tempfile-sweep');
    }

    try {
      systemDocConnection = await hocuspocus.openDirectConnection(SYSTEM_DOC_NAME);
      cc1Broadcaster?.emitServerInfo(serverInstanceId, getReportedBranch() ?? undefined);
    } catch (err) {
      log.error(
        { err },
        '[server] failed to open __system__ direct connection — CC1 push disabled',
      );
      degraded.push('cc1-push');
    }

    const configDocNamesToBind = ephemeral ? [] : CONFIG_DOC_NAMES;

    for (const configDocName of configDocNamesToBind) {
      try {
        const connection = await hocuspocus.openDirectConnection(configDocName);
        configDocConnections.set(configDocName, connection);
      } catch (err) {
        log.error(
          { err, docName: configDocName },
          `[server] failed to open ${configDocName} direct connection — config bind degraded`,
        );
        degraded.push(`config-doc:${configDocName}`);
      }
    }

    const configPathByDoc = new Map<string, string>([
      [CONFIG_DOC_NAME_PROJECT, resolveConfigPath('project', projectDir)],
      [CONFIG_DOC_NAME_PROJECT_LOCAL, resolveConfigPath('project-local', projectDir)],
      [CONFIG_DOC_NAME_USER, resolveConfigPath('user', projectDir, configHomedirOverride)],
    ]);
    for (const configDocName of configDocNamesToBind) {
      const absPath = configPathByDoc.get(configDocName);
      if (!absPath) continue;
      try {
        log.info({ docName: configDocName, path: absPath }, '[config-file-watcher] starting');
        const takeInConfigChange = async (content: string): Promise<void> => {
          const document = hocuspocus.documents.get(configDocName);
          const alreadyApplied = isConfigEcho(
            configDocName,
            content,
            persistence.configPersistenceCtx,
          );
          log.info(
            {
              docName: configDocName,
              hasDocument: document !== undefined,
              contentLength: content.length,
            },
            '[config-file-watcher] file changed',
          );
          const outcome = await applyExternalConfigChange(
            document ?? null,
            configDocName,
            content,
            persistence.configPersistenceCtx,
          );
          log.info(
            { docName: configDocName, outcome, isEcho: alreadyApplied },
            '[config-file-watcher] applyExternalConfigChange outcome',
          );
          applyPersistedConfigToConsumers(configDocName);
          if (!alreadyApplied) {
            logConfigDiagnostics(configDocName);
          }
        };
        const cleanup = await startConfigFileWatcher(absPath, (content) => {
          void takeInConfigChange(content).catch((err: unknown) => {
            log.warn(
              { err, docName: configDocName },
              '[config-file-watcher] change handler failed',
            );
          });
        });
        configFileWatcherCleanups.push({ docName: configDocName, cleanup });
        configFileWatcherResyncs.set(configDocName, cleanup.resync);
        log.info({ docName: configDocName, path: absPath }, '[config-file-watcher] started');
      } catch (err) {
        log.warn(
          { err, docName: configDocName, path: absPath },
          `[config-file-watcher] failed to start for ${configDocName}`,
        );
        degraded.push(`config-file-watcher:${configDocName}`);
      }
    }

    if (!ephemeral) {
      let globalSkillNodesTimer: NodeJS.Timeout | null = null;
      const scheduleGlobalSkillNodesRefresh = (docName: string): void => {
        if (globalSkillNodesTimer !== null) clearTimeout(globalSkillNodesTimer);
        globalSkillNodesTimer = setTimeout(() => {
          globalSkillNodesTimer = null;
          void derivedDocumentIndex.refreshGlobalSkillNodes().catch((err) => {
            log.warn({ err, docName }, '[backlinks] global skill bundle re-ingest failed');
          });
        }, 300);
      };
      const reconcileManagedArtifactDisk = async (absPath: string, content: string) => {
        const docName = managedArtifactDocNameForPath(absPath, persistence.managedArtifactCtx);
        if (!docName) return;
        const document = hocuspocus.documents.get(docName);
        const outcome = await applyExternalManagedArtifactChange(
          document ?? null,
          docName,
          content,
          persistence.managedArtifactCtx,
        );
        log.info({ docName, outcome }, '[managed-artifact-watcher] external change');
        signalChannel('files');
        if (parseGlobalSkillBundleDoc(docName)) {
          scheduleGlobalSkillNodesRefresh(docName);
        }
      };

      const handleManagedArtifactUnlink = (absPath: string): void => {
        const docName = managedArtifactDocNameForPath(absPath, persistence.managedArtifactCtx);
        signalChannel('files');
        if (docName && parseGlobalSkillBundleDoc(docName)) {
          scheduleGlobalSkillNodesRefresh(docName);
        }
      };

      try {
        const skillsRoots = managedArtifactSkillsRoots(persistence.managedArtifactCtx);
        const skillsCleanup = await startManagedArtifactWatcher(
          skillsRoots,
          reconcileManagedArtifactDisk,
          handleManagedArtifactUnlink,
        );
        configFileWatcherCleanups.push({ docName: '__skill-files__', cleanup: skillsCleanup });
        log.info({ roots: skillsRoots }, '[managed-artifact-watcher] skills started');
      } catch (err) {
        log.warn({ err }, '[managed-artifact-watcher] skills failed to start');
        degraded.push('managed-artifact-watcher:skills');
      }

      try {
        const skillStatePath = skillStateYamlPath(homeFor(persistence.managedArtifactCtx));
        const skillStateCleanup = await startConfigFileWatcher(skillStatePath, () => {
          signalChannel('files');
        });
        configFileWatcherCleanups.push({ docName: '__skill-state__', cleanup: skillStateCleanup });
        log.info({ path: skillStatePath }, '[skill-state-watcher] started');
      } catch (err) {
        log.warn({ err }, '[skill-state-watcher] failed to start');
        degraded.push('skill-state-watcher');
      }
    }

    try {
      const okignorePath = resolve(contentDir, '.okignore');
      const gitignorePath = resolve(projectDir, '.gitignore');
      let gitInfoExcludePath: string | null = null;
      try {
        const probe = spawnSync(
          'git',
          ['rev-parse', '--git-common-dir'],
          withHiddenWindowsConsole({
            cwd: projectDir,
            encoding: 'utf-8',
            timeout: 5_000,
          }),
        );
        if (probe.status === 0 && probe.stdout) {
          const commonDir = resolve(projectDir, probe.stdout.trim());
          const candidate = join(commonDir, 'info', 'exclude');
          if (existsSync(dirname(candidate))) gitInfoExcludePath = candidate;
        }
      } catch {}
      const ignorePaths = gitInfoExcludePath
        ? [okignorePath, gitignorePath, gitInfoExcludePath]
        : [okignorePath, gitignorePath];
      const ignoreLog = log;
      ignoreLog.info(
        { okignorePath, gitignorePath, gitInfoExcludePath, ephemeral },
        '[ignore-watcher] starting multi-path watcher for .okignore + .gitignore (+ .git/info/exclude when present)',
      );
      const ignoreCleanup = ephemeral
        ? null
        : await startMultiPathConfigFileWatcher(ignorePaths, (changedPath, content) => {
            void (async () => {
              if (changedPath === okignorePath) {
                try {
                  const document = hocuspocus.documents.get(CONFIG_DOC_NAME_OKIGNORE) ?? null;
                  const outcome = await applyExternalConfigChange(
                    document,
                    CONFIG_DOC_NAME_OKIGNORE,
                    content,
                    persistence.configPersistenceCtx,
                  );
                  ignoreLog.info(
                    { docName: CONFIG_DOC_NAME_OKIGNORE, outcome },
                    '[ignore-watcher] applyExternalConfigChange outcome',
                  );
                } catch (err) {
                  ignoreLog.error(
                    { err, changedPath: relative(projectDir, changedPath) },
                    '[ignore-watcher] applyExternalConfigChange failed; rebuild proceeds independently',
                  );
                }
              }

              const result = await contentFilter.rebuildIgnorePatterns();
              if (result.ok) {
                ignoreLog.info(
                  {
                    changedPath: relative(projectDir, changedPath),
                    patternCount: result.patternCount,
                    nestedFileCount: result.nestedFileCount,
                    durationMs: result.durationMs,
                  },
                  '[ignore-watcher] rebuild succeeded — broadcasting files channel',
                );
                cc1Broadcaster?.signal('files');
              } else {
                const projectRelPath = relative(projectDir, changedPath) || '.';
                ignoreLog.warn(
                  { changedPath: projectRelPath, error: result.error.message },
                  '[ignore-watcher] rebuild failed — emitting config-ignore-nested-error',
                );
                cc1Broadcaster?.emitConfigIgnoreNestedError(projectRelPath, result.error.message);
              }
            })().catch((err) => {
              ignoreLog.error(
                { err, changedPath: relative(projectDir, changedPath) || '.' },
                '[ignore-watcher] handler threw',
              );
            });
          });
      if (ignoreCleanup) {
        configFileWatcherCleanups.push({ docName: '__ignore-files__', cleanup: ignoreCleanup });
        configFileWatcherResyncs.set(CONFIG_DOC_NAME_OKIGNORE, ignoreCleanup.resync);
        ignoreLog.info(
          { okignorePath, gitignorePath },
          '[ignore-watcher] multi-path watcher started',
        );
      }
    } catch (err) {
      log.warn(
        { err, projectDir, contentDir },
        '[ignore-watcher] failed to start multi-path watcher',
      );
      degraded.push('ignore-files-watcher');
    }

    const startupBranch = readProjectHeadState(projectDir).branch ?? 'main';
    switchReconciledBaseScope(startupBranch);
    resolveBranchScopeAligned();
    const derivedIndexStartup = derivedDocumentIndex.beginStartup(startupBranch);
    let derivedIndexStartupSettled = false;

    const indexesStartMono = performance.now();
    try {
      await withSpan('ok.boot.indexes', undefined, async () => {
        const deletedDocNames = await derivedIndexStartup.offlineDeletionsReady;
        let tombstonedOffline = 0;
        for (const deletedDocName of deletedDocNames) {
          if (isReservedForUserTree(deletedDocName)) continue;
          if (recentlyRemovedDocs.peek(deletedDocName)?.kind === 'renamed') continue;
          recentlyRemovedDocs.setDeleted(deletedDocName);
          tombstonedOffline++;
        }
        if (tombstonedOffline > 0) {
          log.info(
            { count: tombstonedOffline },
            '[removal-guard] tombstoned docs deleted while the server was down',
          );
        }
        offlineRemovalsReconciled.resolve();
        const { backlinkIndexDegraded } = await derivedIndexStartup.backlinksReady;
        if (backlinkIndexDegraded) degraded.push('backlink-index');
        const seedWalkStartMono = performance.now();
        const HOST_SKILLS_EVENT_RE = /^\.(?!ok\/)[A-Za-z0-9_-]+\/skills\//;
        let lastInPlaceDirs: ReadonlySet<string> = contentFilter
          ? new Set(scanInPlaceSkills(contentDir).map((skill) => skill.dir))
          : new Set<string>();
        const onRawBatch = (absPaths: readonly string[]): void => {
          if (
            !absPaths.some((p) =>
              HOST_SKILLS_EVENT_RE.test(relative(canonicalContentDir, p).split(sep).join('/')),
            )
          ) {
            return;
          }
          if (inPlaceRescanTimer) clearTimeout(inPlaceRescanTimer);
          inPlaceRescanTimer = setTimeout(() => {
            inPlaceRescanTimer = null;
            try {
              void resyncRecordedSkillCopies(projectDir, contentDir)
                .then((n) => {
                  if (n > 0) {
                    log.info({ refreshed: n }, '[in-place-skills] re-synced recorded copies');
                    cc1Broadcaster?.signal('files');
                  }
                })
                .catch((err) => log.warn({ err }, '[in-place-skills] copy re-sync failed'));
              const next = scanInPlaceSkillDirs(contentDir, lastInPlaceDirs);
              const changed =
                next.size !== lastInPlaceDirs.size ||
                [...next].some((d) => !lastInPlaceDirs.has(d));
              if (!changed) return;
              lastInPlaceDirs = next;
              void contentFilter
                .rebuildIgnorePatterns()
                .then((result) => {
                  if (result.ok) {
                    log.info(
                      { skillDirs: next.size },
                      '[in-place-skills] canonical set changed — filter rebuilt',
                    );
                    cc1Broadcaster?.signal('files');
                  } else {
                    log.warn(
                      { error: result.error.message },
                      '[in-place-skills] filter rebuild failed after skill re-scan',
                    );
                  }
                })
                .catch((err) => log.warn({ err }, '[in-place-skills] rebuild threw'));
            } catch (err) {
              log.warn({ err }, '[in-place-skills] re-scan trigger failed');
            }
          }, IN_PLACE_RESCAN_DEBOUNCE_MS);
        };
        await adoptWatcher(
          () =>
            withSpan('ok.boot.seed-walk', undefined, async () =>
              startWatcher(canonicalContentDir, onDiskEvent, contentFilter, {
                onRawBatch,
                onRecoveryComplete: () => derivedDocumentIndex.recordInventoryReconciled(),
                onRecoveryPassCompleted: (pass, whole) => settleVanishedDocuments(pass, whole),
                nativeBackend: options.watcherBackend,
                clock: options.watcherClock,
                freshnessIntervalMs:
                  options.freshnessIntervalMs === undefined
                    ? FRESHNESS_BASE_INTERVAL_MS
                    : options.freshnessIntervalMs,
              }),
            ),
          (handle) => {
            watcher = handle;
          },
          'content',
        );
        void resyncRecordedSkillCopies(projectDir, contentDir)
          .then((n) => {
            if (n > 0) log.info({ refreshed: n }, '[in-place-skills] boot copy re-sync');
          })
          .catch((err) => log.warn({ err }, '[in-place-skills] boot copy re-sync failed'));
        {
          const home = configHomedirOverride ?? homedir();
          void scanGlobalInPlaceSkillsAsync(home)
            .then((inPlace) => resyncRecordedSkillCopies(home, home, inPlace))
            .then((n) => {
              if (n > 0) log.info({ refreshed: n }, '[in-place-skills] global boot copy re-sync');
            })
            .catch((err) => log.warn({ err }, '[in-place-skills] global copy re-sync failed'));
        }
        recordBootPhase('seedWalkMs', Math.round(performance.now() - seedWalkStartMono));

        {
          const sweepContentDir = resolve(contentDir);
          let healedJournalEntries = 0;
          for (const [removedDocName] of recentlyRemovedDocs.entries()) {
            if (!isSafeDocName(removedDocName)) continue;
            const filePath = resolve(
              sweepContentDir,
              `${removedDocName}${getDocExtension(removedDocName)}`,
            );
            if (isWithinDir(filePath, sweepContentDir) && existsSync(filePath)) {
              recentlyRemovedDocs.delete(removedDocName);
              healedJournalEntries++;
            }
          }
          if (healedJournalEntries > 0) {
            log.info(
              { count: healedJournalEntries },
              '[removal-guard] dropped journaled removal entries whose file re-appeared while the server was down',
            );
          }
        }
        const derivedIndexSettlement = await derivedDocumentIndex.settleStartupAfterWatcherSeed();
        derivedIndexStartupSettled = true;
        if (derivedIndexSettlement.tagIndexDegraded) degraded.push('tag-index');
        let seedSkipCount = 0;
        try {
          if (singleDocRelPath !== undefined) {
            seedSingleDirBasenameIndex({
              contentDir,
              basenameIndex,
              onSkip: (reason, code, path) => {
                seedSkipCount++;
                log.warn(
                  { reason, code, path },
                  `[basename-index] skipped entry during single-file seed (${reason}${code ? ` ${code}` : ''})`,
                );
              },
            });
          } else {
            await seedBasenameIndex({
              contentDir,
              contentFilter,
              basenameIndex,
              onSkip: (reason, code, path) => {
                seedSkipCount++;
                log.warn(
                  { reason, code, path },
                  `[basename-index] skipped entry during seed (${reason}${code ? ` ${code}` : ''})`,
                );
              },
            });
          }
          if (seedSkipCount > 0) {
            log.warn(
              { count: seedSkipCount },
              `[basename-index] startup seed completed with ${seedSkipCount} skipped entries — embeds under inaccessible subtrees will not resolve`,
            );
            degraded.push('basename-index-partial');
          }
        } catch (err) {
          log.error({ err }, '[basename-index] startup seed failed');
          degraded.push('basename-index');
        }
      });
    } catch (err) {
      log.error({ err }, '[server] disk bridge watcher failed to start');
      degraded.push('file-watcher');
      if (!derivedIndexStartupSettled) {
        const settlement = await derivedDocumentIndex.settleStartupAfterWatcherSeed();
        derivedIndexStartupSettled = true;
        if (settlement.tagIndexDegraded) degraded.push('tag-index');
      }
    } finally {
      recordBootPhase('indexesMs', Math.round(performance.now() - indexesStartMono));
      if (watcher) setBootField('fileCount', watcher.getFileIndex().size);
      refreshStartupEmbeds();
    }

    let releaseHeadBatchAdmission = () => {};
    try {
      await adoptWatcher(
        () =>
          startHeadWatcher(
            projectDir,
            async ({ trigger }) => {
              log.info({ trigger }, `[batch] begin trigger=${trigger}`);
              incrementBatch();
              hocuspocus.flushPendingStores();
              await persistence.flushPendingGitCommit();

              holdBatch('head-watcher');
              releaseHeadBatchAdmission();
              releaseHeadBatchAdmission = durabilityState.holdWriteAdmission();

              if (shadowRef.current) {
                const currentBranch = getActiveBranch();
                const newBranch = readProjectHeadState(projectDir).branch ?? currentBranch;
                const docs: ParkableDoc[] = [];
                let absentBaseParkSkips = 0;
                for (const [docName, document] of hocuspocus.documents) {
                  if (isReservedForUserTree(docName)) continue;
                  let markdown: string | null = null;
                  document.transact(() => {
                    markdown = serializeDoc(docName);
                  }, PARK_SNAPSHOT_ORIGIN);
                  if (markdown === null) continue;
                  const diskSnapshot = getReconciledBase(docName);
                  if (diskSnapshot === undefined) {
                    absentBaseParkSkips++;
                    continue;
                  }
                  docs.push({ docName, markdown, diskSnapshot });
                }
                if (absentBaseParkSkips > 0) {
                  log.warn(
                    { count: absentBaseParkSkips, branch: currentBranch },
                    `[history] skipped parking ${absentBaseParkSkips} doc(s) with no reconciled base; their content was not parked to the shadow history`,
                  );
                }
                if (docs.length > 0) {
                  try {
                    const sha = await parkBranch(
                      shadowRef.current,
                      currentBranch,
                      SERVICE_WRITER.id,
                      docs,
                      newBranch,
                    );
                    if (sha) {
                      incrementPark();
                      log.info(
                        { count: docs.length, branch: currentBranch, sha: sha.slice(0, 8) },
                        `[history] parked ${docs.length} docs on ${currentBranch} → ${sha.slice(0, 8)}`,
                      );
                    }
                  } catch (e) {
                    log.error({ err: e }, '[shadow] park failed');
                  }
                }
              }
            },
            async (info) => {
              const bufferedCount = eventBuffer.length;
              const newBranch = info.newBranch ?? 'main';

              log.info(
                {
                  kind: info.batchKind,
                  headMoved: info.headMoved,
                  docs: bufferedCount,
                  timeout: !!info.timeout,
                },
                `[batch] end kind=${info.batchKind} headMoved=${info.headMoved} docs=${bufferedCount}${info.timeout ? ' timeout' : ''}`,
              );

              if (info.batchKind === 'within-branch') {
                try {
                  try {
                    await drainEventBuffer();
                  } finally {
                    disposeBufferedRemovalScopes();
                  }

                  if (info.headMoved && info.newHead) {
                    const changes = resolveUpstreamChanges(
                      projectDir,
                      resolve(contentDir),
                      info.oldHead,
                      info.newHead,
                    );
                    if (changes.size > 0) {
                      dropPendingDocs(changes.keys());
                      for (const [docName, author] of changes) {
                        recordContributor(
                          docName,
                          gitAuthorWriterId(author.email),
                          author.name,
                          author.email,
                          formatReconcileSubject(docName),
                        );
                      }
                      await persistence.flushContributors();
                    }
                  }
                } finally {
                  try {
                    if (releaseBatchHold('head-watcher')) await finishBatch();
                  } finally {
                    releaseHeadBatchAdmission();
                  }
                }
                try {
                  await conflicts.pruneMergeNativeAgainstGit();
                } catch (err) {
                  log.warn({ err }, '[head-watcher] conflict prune against git failed');
                }
              } else {
                incrementBranchSwitch();
                supersedeBranchSwitchFollowUps();
                let batchReleased = false;
                let switchPassFellShort = false;
                let branchTransition: DerivedDocumentIndexBranchTransition | undefined;
                try {
                  switchReconciledBaseScope(newBranch);
                  conflicts.setBranch(newBranch);
                  hydrateStaleExternalWrites();
                  branchTransition = await derivedDocumentIndex.beginBranchSwitch(newBranch);

                  contentFilter.rebuildDirCount();

                  try {
                    let reseedSkipCount = 0;
                    basenameIndex.clear();
                    await seedBasenameIndex({
                      contentDir,
                      contentFilter,
                      basenameIndex,
                      onSkip: (reason, code, path) => {
                        reseedSkipCount++;
                        log.warn(
                          { reason, code, path, branch: newBranch },
                          `[basename-index] skipped entry during branch-switch reseed (${reason}${code ? ` ${code}` : ''})`,
                        );
                      },
                    });
                    if (reseedSkipCount > 0) {
                      log.warn(
                        { count: reseedSkipCount, branch: newBranch },
                        `[basename-index] branch-switch reseed completed with ${reseedSkipCount} skipped entries — embeds under inaccessible subtrees will not resolve on this branch`,
                      );
                      if (!degraded.includes('basename-index-partial')) {
                        degraded.push('basename-index-partial');
                      }
                    }
                  } catch (err) {
                    log.error(
                      { err, branch: newBranch },
                      '[basename-index] branch-switch reseed failed',
                    );
                  }

                  try {
                    await derivedDocumentIndex.settleBranchFromDisk(branchTransition);
                  } catch (err) {
                    derivedDocumentIndex.abortBranchSwitch(branchTransition);
                    log.error(
                      { err, branch: newBranch },
                      '[derived-index] branch-switch rebuild failed; relationship views may be stale',
                    );
                  }

                  try {
                    await drainEventBuffer();
                    const switchPass = await watcher?.recheck('full');
                    if (switchPass && (switchPass.status !== 'completed' || switchPass.partial)) {
                      switchPassFellShort = true;
                      incrementBranchSwitchRecheckShortfalls();
                      log.warn(
                        {
                          branch: newBranch,
                          status: switchPass.status,
                          partial: switchPass.partial === true,
                        },
                        `[branch-switch] the re-check after switching to ${newBranch} did not observe the whole tree; another one runs once the switch ends`,
                      );
                    }
                    await drainEventBuffer();
                  } finally {
                    disposeBufferedRemovalScopes();
                  }
                  tombstoneResidentsResolvingIntoPrivateState(newBranch);
                  log.info(
                    { branch: newBranch, docCount: hocuspocus.documents.size },
                    `[branch-switch] loaded branch ${newBranch} (${hocuspocus.documents.size} docs)`,
                  );

                  if (info.oldBranch?.startsWith('detached-') && shadowRef.current) {
                    try {
                      const sg = shadowGit(shadowRef.current);
                      const refs = (
                        await sg.raw(
                          'for-each-ref',
                          `refs/wip/${info.oldBranch}/`,
                          '--format=%(refname)',
                        )
                      ).trim();
                      if (refs) {
                        await shadowOpGateFor(shadowRef.current).withMutator(async () => {
                          for (const ref of refs.split('\n')) {
                            if (ref) {
                              await sg.raw('update-ref', '-d', ref);
                            }
                          }
                        });
                        log.info(
                          { context: info.oldBranch },
                          `[branch-switch] cleaned up detached context ${info.oldBranch}`,
                        );
                      }
                    } catch (e) {
                      log.error({ err: e }, '[branch-switch] detached cleanup failed');
                    }
                  }

                  batchReleased = true;
                  if (releaseBatchHold('head-watcher')) await finishBatch();
                  cc1Broadcaster?.emitBranchSwitched(newBranch);
                  if (switchPassFellShort) followUpBranchSwitchRecheck(newBranch);
                } finally {
                  try {
                    derivedDocumentIndex.abortBranchSwitch(branchTransition);
                    if (!batchReleased && releaseBatchHold('head-watcher')) await finishBatch();
                  } finally {
                    releaseHeadBatchAdmission();
                  }
                }
              }

              if (info.headMoved && info.newHead && shadowRef.current && bufferedCount > 0) {
                const contentRootForShadow = contentRoot ?? '.';
                try {
                  const sha = await commitUpstreamImport(
                    shadowRef.current,
                    contentRootForShadow,
                    info.oldHead,
                    info.newHead,
                    newBranch,
                  );
                  incrementUpstreamImport();
                  log.info(
                    {
                      oldHead: info.oldHead?.slice(0, 8) ?? 'null',
                      newHead: info.newHead.slice(0, 8),
                      sha: sha.slice(0, 8),
                    },
                    `[history] upstream-import from ${info.oldHead?.slice(0, 8) ?? 'null'}..${info.newHead.slice(0, 8)} → ${sha.slice(0, 8)}`,
                  );
                } catch (e) {
                  log.error({ err: e }, '[shadow] upstream-import failed');
                }
              }
            },
            {
              nativeBackend: options.watcherBackend,
              clock: options.watcherClock,
              onGaveUp: () => {
                if (!degraded.includes('head-watcher')) degraded.push('head-watcher');
              },
              onBack: () => {
                const at = degraded.indexOf('head-watcher');
                if (at !== -1) degraded.splice(at, 1);
              },
            },
          ),
        (handle) => {
          headWatcher = handle;
        },
        'head',
      );
    } catch (err) {
      log.error({ err }, '[server] HEAD watcher failed to start');
      degraded.push('head-watcher');
    }

    conflicts.subscribe((change) => {
      if (change.type !== 'raised') return;
      if (change.conflict.kind === 'reconcile') return;
      const docName = change.docName;
      if (docName === null) return;
      if (!hocuspocus.documents.get(docName)) return;
      const ours = serializeDoc(docName);
      if (ours !== null) {
        setReconciledBase(docName, ours);
      } else {
        log.warn(
          { docName, file: change.conflict.file },
          '[sync] content conflict: serializeDoc returned null; reconciledBase snapshot skipped',
        );
      }
    });

    try {
      await conflicts.pruneMergeNativeAgainstGit();
    } catch (err) {
      log.warn({ err }, '[conflicts] boot prune of merge-native entries failed');
    }

    const syncCredentialConfig = await resolveSyncCredentialConfig();
    const bootAutoSyncMode = readProjectAutoSyncMode();
    const bootAutoSyncIntervals = readProjectAutoSyncIntervals();
    if (bootAutoSyncMode.mode !== 'off') {
      log.info(
        { mode: bootAutoSyncMode.mode, source: bootAutoSyncMode.source },
        '[sync] mode active at boot',
      );
    }
    try {
      syncEngine = new SyncEngine({
        declaredGitHubHosts,
        projectDir,
        contentDir,
        contentFilter,
        contentRoot,
        mcpTomlEditor: options.mcpTomlEditor,
        mode: bootAutoSyncMode.mode,
        pullIntervalSeconds:
          options.pullIntervalSeconds ?? bootAutoSyncIntervals.pullIntervalSeconds,
        pushIntervalSeconds:
          options.pushIntervalSeconds ?? bootAutoSyncIntervals.pushIntervalSeconds,
        credentialConfig: syncCredentialConfig,
        resolveCredentialConfig: resolveSyncCredentialConfig,
        cc1Broadcaster,
        conflicts,
        detectGh: options.detectGh,
        detectGhAccounts: options.detectGhAccounts,
        tokenStore: options.tokenStore,
        checkPushPermissionFn: options.checkPushPermissionFn,
        setBatchInProgress: batchFlagFor('sync-engine'),
        onStateChange: (state) => {
          log.info({ state }, `[sync] state → ${state}`);
        },
        checkpointBeforeStrandedConversion: async ({ branch, ahead }) => {
          const shadow = shadowRef.current;
          if (!shadow) return;
          await safetyCheckpoint(
            shadow,
            contentRoot ?? '',
            { action: 'pull-only-stranded-conversion', context: { ahead } },
            branch,
          );
        },
        checkpointBeforeOverlayRestore: async ({ branch, paths }) => {
          const shadow = shadowRef.current;
          if (!shadow) return;
          await safetyCheckpoint(
            shadow,
            contentRoot ?? '',
            { action: 'pull-only-overlay-restore', context: { paths } },
            branch,
          );
        },
        onAutoDisable: async (reason) => {
          log.warn({ reason }, '[sync] auto-disabled — persisting to project-local config');
          const result = await writeConfigPatch({
            cwd: projectDir,
            scope: 'project-local',
            patch: { autoSync: { enabled: false } },
          });
          if (!result.ok) {
            log.error(
              {
                result,
                reason,
                humanError: humanFormat(result.error),
                configPath: resolveConfigPath('project-local', projectDir),
              },
              '[sync] failed to persist auto-disable — next restart WILL re-enable sync and re-trigger the same failure. Check permissions on the config path.',
            );
          }
        },
      });
      await syncEngine.start();
    } catch (err) {
      log.warn({ err }, '[server] SyncEngine failed to start — sync disabled');
      syncEngine = null;
    }

    signalChannel('files');
    derivedDocumentIndex.announceReadyViews();

    const readyElapsed = bootElapsedMs();
    if (readyElapsed !== undefined) recordBootPhase('readyMs', readyElapsed);

    logConfigDiagnostics();
  }

  initAsync().then(
    () => {
      indexRegenerationReady = true;
      resolveReady();
      setImmediate(() => {
        const pruned = diskReceipts.pruneGone(receiptFileIsGone);
        if (pruned > 0)
          log.info({ pruned }, `[disk-receipts] dropped ${pruned} receipt(s) whose file is gone`);
      }).unref();
      deferBootIndexSweep();
      deferShadowHousekeeping();
    },
    (err) => {
      indexRegenerationClosed = true;
      indexRegenerationAbort.abort();
      settleGeneratedIndexSweep({ status: 'failed', indexCount: 0 });
      void derivedDocumentIndex.close();
      resolveBranchScopeAligned();
      rejectReady(err);
    },
  );

  return {
    hocuspocus,
    durabilityState,
    sessionManager,
    nativeApi,
    localApi,
    cc1Broadcaster,
    agentFocusBroadcaster,
    agentPresenceBroadcaster,
    maintenanceCoordinator,
    contentFilter,
    basenameIndex,
    serverInstanceId,
    destroy,
    ready,
    generatedIndexSweepReady,
    degraded,
    lockDir,
    get syncEngine() {
      return syncEngine;
    },
    conflicts,
    getLinkPreviewsEnabled: readLinkPreviewsEnabled,
    resolveEmbed,
    resolveTrackedFile,
    acpRegistry,
    acpPermissions,
    recheckDisk: () => {
      if (!watcher) {
        return Promise.reject(
          new Error('the file watcher is not running, so there is nothing to re-check'),
        );
      }
      return watcher.recheck();
    },
  };
}