Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
32.9 KB
Raw Blame
import { type ManagedSyncFailure } from '../core/persistence/sync-failures.ts';
import { startMemoryTrace } from '../core/memory-trace.ts';
import type { BrainEngine } from '../core/engine.ts';
import { DEFAULT_PARALLEL_SOURCES } from '../core/sync-concurrency.ts';
import { withHumanLogsToStderr, withSourcePrefix } from '../core/console-prefix.ts';
import { msysToNativePath } from '../core/path-confine.ts';
import { performSync } from './sync/perform.ts';
import { clearTerminationFallback, runSyncInner } from './sync/run.ts';

// Refactor wave 1 (W4 sync): the implementation lives in src/commands/sync/.
// This file keeps the SyncResult / SyncOpts types and every export, so
// existing importers need no change (CLAUDE.md façade rule).
export { shouldNudgeAfterSync, printSyncResult } from './sync/report.ts';
export { runSyncTrigger } from './sync/trigger.ts';
export { performSync } from './sync/perform.ts';
export { parseMissingPathMode, partitionMissingPathSources, type MissingPathMode } from './sync/missing-path.ts';
export { __resetPGLiteTierWarn, manageGitignore } from './sync/gitignore.ts';

export interface SyncResult {
  failures?: ManagedSyncFailure[];
  runId?: string;
  managedWrite?: import('../core/persistence/sync-run.ts').ManagedSyncWriteDiagnostic;
  /** #6643: the request a rediscovery that retries a recorded failure waits for (its producer and slug), instead of a silent no-op. */
  retryWait?: import('../core/persistence/sync-run.ts').RetryWait;
  /** #7167: a managed dry run's read of the source's writer: open write requests (queued, running or recovering) and the oldest one's age. */
  writer?: import('../core/persistence/sync-dry-run-writer.ts').DryRunWriterState;
  /** #6712 PR 1: another drainer holds (or took) the source's drain lease; `resumable`, nothing admitted by this run. */
  leaseHeld?: import('../core/persistence/sync-lease.ts').DrainLeaseHeld;
  /**
   * #6712 PR 1 (#6552 §1): processing opt-outs this run kept from the unfinished cursor it resumed though the caller did
   * not set them (`gbrain embed --stale` / `gbrain extract --stale` settle the pages they skipped).
   */
  inherited_options?: Array<'noEmbed' | 'noExtract' | 'noSchemaPack'>;
  /** #6693: caller remembers refused while their page's file awaited import (or was held), replayed after this sync imported it. */
  replayedRemembers?: import('../core/repair/failed-writes.ts').ImportReplayReport;
  /** #6712 PR 2 (L4): live pages whose canonical file is gone (ghost pages), counted after a managed sync with the read-only repair preview; sync never deletes them. */
  ghostPages?: import('../core/persistence/sync-ghosts.ts').SyncGhostPages; /** #6865: stray slug: lines naming no page this sync removed (repair/slug-autoheal.ts). */ slug_lines_removed?: import('../core/repair/slug-autoheal.ts').SlugHealReport;
  /** #6948: held duplicate-origin files whose verified twins this sync merged, or why it left them (repair/origin-twins-heal.ts). */
  origin_twins_resolved?: import('../core/repair/origin-twins-heal.ts').OriginHealReport;
  /** #6722: pages this run left large or embed_skip (chunked, keyword-searchable) and their embedding state. */ size_states?: import('../core/page-embedding-budget.ts').SyncSizeStates;
  status: 'up_to_date' | 'synced' | 'first_sync' | 'dry_run' | 'blocked_by_failures' | 'partial';
  fromCommit: string | null;
  toCommit: string;
  added: number;
  modified: number;
  deleted: number;
  renamed: number;
  chunksCreated: number;
  /** Pages re-embedded during this sync's auto-embed step. 0 if --no-embed or skipped. */
  embedded: number;
  embedDeferralReason?: 'large_sync';
  pagesAffected: string[]; /** #5867: a Google sweep's loops_extract enqueue (sweep plus managed catch-up). */ loops_enqueue?: { enqueued: number; deferred: number; skipped_reason: string | null };
  failedFiles?: number; // count of parse failures (Bug 9)
  /**
   * #3875: code breakdown of the blocking failures (set on
   * `blocked_by_failures` only). Lets printSyncResult (and --json consumers)
   * distinguish provider-infra failures (EMBEDDING_TIMEOUT / RATE_LIMIT /
   * QUOTA — retry after fixing the provider) from genuine file poison
   * (--skip-failed territory).
   */
  failureCodes?: Array<{ code: string; count: number }>; /** GST-2492 PR 2: advice for a cause in the source's mode, not the files (`strict_requires_managed`). */ failureAdvice?: string;
  /**
   * Files skipped because their FILENAME contains bracket/control characters
   * (SyncableReason 'malformed-path'). Informational — these never gate
   * bookmark advancement; rename the files to import them.
   */
  malformedSkipped?: number;
  /** #5751: unchanged managed working-tree files skipped although a no-op publication cannot resolve their admit reason. */
  legacySkips?: { contextualMode: number; canonicalBytes: number }; /** #5984: managed entries advanced without a write (DX-A7), and how a still-unfinished managed write's wait ended (DX-A3). */ waived?: { imports: number; deletes: number };
  /** #6712 PR 1: of `waived.imports`, the entries the guarded no-op kernel passed straight from the discovery prescreen (no freeze or preparation). */
  prescreened?: number; writeWait?: import('../core/persistence/sync-write-diagnostic.ts').ManagedSyncWriteWait;
  /** Managed sync: files skipped because another origin keeps their slug, and links derived after the checkpoint. */
  slugCollisions?: import('../core/persistence/sync-discovery.ts').SyncSlugCollision[];
  fileRefusals?: import('../core/persistence/sync-discovery.ts').SyncFileRefusal[]; links?: import('../core/persistence/links-maintenance.ts').ManagedLinkExtraction; /** #6729: inexact renames split into delete + add; once recorded each is an IdentityDowngrade (old slug, what stayed on it). */ identityDowngrades?: Array<import('../core/sync.ts').DowngradedRename | import('../core/sync-identity-downgrades.ts').IdentityDowngrade>;
  /** #6712 PR 2 (L5): the owed post-checkpoint tail (statistics, links) this call ran after releasing the lease; a degraded tail carries its notice. */
  tail?: Omit<import('../core/persistence/sync-tail.ts').SyncTailReport, 'links'>;
  /** GBRA-217: the pass's change-reason notices (a failed or capped trailer scan, a secret in a pushed trailer) and its count of skipped malformed trailers. */
  reason_notices?: import('../core/agent-output.ts').Notice[];
  /** GST-2462: the run's one `privacy_label_ignored` notice, counting by value the pages it wrote whose privacy label gbrain ignores. */
  privacy_label_notice?: import('../core/agent-output.ts').Notice;
  reason_trailers_malformed?: number;
  /** #5459 (P4.5): live pages a `--full` tree walk kept because their file is in the working tree and their import provenance is the working tree or unknown. */
  working_tree_kept?: number;
  /** #8007: pages whose file is gone kept because gbrain.yml's storage section is invalid. */ storage_invalid_kept?: number;
  /**
   * Aggregated alias/undeclared explicit-type warnings (schema.type_warnings,
   * default on) — one entry per distinct non-canonical type this run.
   * Carried on the RESULT (not just stderr) so worker-driven syncs surface it
   * in job results where daemon stderr is invisible.
   */
  type_warnings?: Array<{ kind: 'alias_of' | 'undeclared'; type: string; canonical?: string; directory?: string; count: number }>;
  /**
   * Working-tree files invisible to commit-driven sync (attached HEAD without
   * --working-tree): untracked/added, modified, and deleted counts AFTER the
   * same scope/exclude/isSyncable filters imports use. Uncommitted renames are
   * decomposed as add(new path) + delete(old path). Absent when zero, or when
   * the working tree was imported (detached HEAD or --working-tree).
   */
  uncommitted?: { added: number; modified: number; deleted: number };
  /** Post-sync link/timeline extraction failure (A15); the affected pages stay stale. */
  extract_error?: string;
  /** #5050: full sync re-sealed unchanged pages at the safe-chunk fence (see RunImportResult.resealed). */
  resealed?: import('./import.ts').RunImportResult['resealed'];
  /** GBRA-287: DB-only pages (#2426) a full sync kept but could not re-export to the working tree; the run still completed. */
  reexport_failures?: import('./sync/full.ts').ReexportFailure[];
  /**
   * v0.41.13.0 partial-sync fields (only set when status === 'partial').
   *
   * D-V3-1 (honest scope): --timeout aborts ONLY in pre-bookmark phases
   * (pull, delete, rename, import). Extract + embed run to completion if
   * reached. By construction, partial fires BEFORE the bookmark write at
   * sync.ts:1261 so last_commit is never advanced on partial — the D4
   * invariant is enforced by checkpoint-topology, not by post-write
   * rollback.
   *
   * `files_imported` reflects ACTUAL persisted count (not the
   * not-yet-attempted set). `reason` distinguishes the partial cause so
   * cron operators can disambiguate timeout vs pull-timeout in monitoring; connector item failures / early stop exit 1 (isFailedPartial).
   */
  filesImported?: number;
  reason?: 'timeout' | 'pull_timeout' | 'pull_failed' | 'stall_timeout' | 'checkpoint_unavailable' | 'writer_pending' | 'writer_yield' | 'connector_item_failures' | 'connector_partial' | 'drain_lease_held' | import('../core/persistence/sync-pass-row.ts').PassResultReason;
  /** #6712 PR 4b: the live pass behind this result (`PassResultSummary`); `reconcile` is a remote caller's `reconcile_host_required` detail (design §5). */
  pass?: import('../core/persistence/sync-pass-row.ts').PassResultSummary;
  reconcile?: import('../core/persistence/sync-pass-apply.ts').RemoteReconcile;
  /**
   * v0.42.x (#1794): cumulative file paths durably banked to the checkpoint
   * across THIS run + prior resumed runs. Surfaced on every partial/blocked
   * exit so an operator who kills a sync can see progress was banked — instead
   * of reading only `last_commit` (unchanged by design) and concluding "lost
   * everything," the exact misdiagnosis in the #1794 recurrence report.
   */
  bankedFiles?: number;
  /** #5984: the managed drain's verdict and the next step for the agent (see sync-drain.ts). */
  drain?: import('../core/persistence/sync-drain.ts').DrainReport;
  /** #6349: this run synced a staged first-parent commit (`target`) short of `head`, because the delta to HEAD exceeded the cursor bound; `stages` counts the stages a CLI loop took. P4.4: `slice` names the path slice of `target` this run committed when the target itself exceeds the bound. */
  staged?: { target: string; head: string; stages?: number; slice?: { phase: 'import' | 'delete'; after: string | null } };
  /** #6278: the run stopped because too many writes stalled while preparing (one systemic diagnostic instead of a pile of holds). */
  breaker?: import('../core/persistence/sync-run.ts').ManagedSyncBreaker;
  /** #5984: managed cursor position (`index` of `total` manifest entries) and its active drain window. */
  managedCursor?: { index: number; total: number; progress?: import('../core/persistence/sync-run.ts').CursorProgress };
  /** Fix wave 4: connector items held after repeated item-scoped failures (not blocking freshness). */
  connectorHolds?: { held: number; newly_held: number; retry_command: string; status_command: string };
  /**
   * #5988 Git holds: files held this run instead of blocking (detail capped at
   * `GBRAIN_SYNC_HOLD_CAP`), their count (#7199: how many wait on a person), the source's outstanding total and the
   * exact inspect and repair commands. Remote callers get `held_count` and
   * `holds_fix` (a host-operator relay) only.
   */
  held?: import('../core/persistence/sync-holds.ts').GitHoldItem[];
  held_count?: number; held_needs_human?: number; carried?: import('../core/persistence/sync-holds.ts').CarriedHolds[]; skipped?: { symlink_dangling: { count: number; sample: string[] } };
  holds_outstanding?: number; holds_released?: number;
  holds_escalated?: boolean;
  holds_truncated?: boolean;
  /** A sliced run (`writer_yield`) has not screened every entry yet. */
  holds_pending_screen?: boolean;
  holds_fix?: import('../core/agent-output.ts').Action;
  /** Requests of a blocked cursor this run converted in place (held, or re-frozen after the file was fixed). */
  converted_from_failed?: string[];
  /** Files imported by quoting unquoted frontmatter values, and (#6188) files whose fences Tier 1 rewrote, cumulative for the run. */
  recovered_frontmatter?: import('../core/persistence/sync-holds.ts').RecoveredFrontmatter; fences_normalized?: import('../core/fence-repair/report.ts').FencesNormalized; fence_issues?: ReturnType<ReturnType<typeof import('../core/fence-repair/report.ts').importFenceTally>['fields']>['fence_issues'];
  /** Dry run: files the run would hold or (#6188) normalize, and entries the screen could not judge (never holds). */
  dry_run?: true; would_normalize?: Array<{ path: string; classes: string[] }>; would_normalize_count?: number;
  would_hold?: import('../core/persistence/sync-holds.ts').GitHoldItem[];
  would_hold_count?: number;
  screen_skipped?: Array<{ path: string; code: string }>;
}

// The cost-gate / token-estimate cluster (estimateSourceTreeTokens,
// estimateInlineNewTokens, runInlineCostGate, ...) was peeled to
// src/core/sync-cost-gate.ts (pure move). Re-exported so existing importers
// keep working.
export {
  estimateSourceTreeTokens,
  estimateInlineNewTokens,
  type EstimateKind,
  type InlineEstimate,
} from '../core/sync-cost-gate.ts';

export interface SyncOpts {
  /** #6712 PR 4b (design §7): the owner approved this sync's paid work (`--yes`); an unknown pass cost no longer defers it. */
  costApproved?: boolean;
  repoPath?: string;
  dryRun?: boolean;
  full?: boolean;
  noPull?: boolean;
  noEmbed?: boolean;
  noExtract?: boolean;
  /**
   * #3969: opt back into per-poll ingest_log rows. By default a sync that
   * landed nothing (no pages written, no chunks, no failures acknowledged)
   * skips the ingest_log write — mirrors runImport's shouldLogIngest gate.
   */
  logNoop?: boolean;
  /** Bug 9 — acknowledge + skip past current failure set (CLI --skip-failed). */
  skipFailed?: boolean;
  /** CLI --retry-failed: a deprecated alias (#6712 PR 3); a plain sync retries a recorded failure. Connector syncs still read it. */
  retryFailed?: boolean;
  /** Managed connector sources: discard the connector checkpoint and re-walk the window once (CLI --reset-checkpoint). */
  resetCheckpoint?: boolean;
  /**
   * v0.41.37.0 #1569 — skip loading the active schema pack during sync. When set,
   * `loadActivePack` is not called, so no user-supplied pack page-type regex
   * (markdown.ts subtype path_pattern) runs during import. Pages fall back to
   * legacy prefix typing. Escape hatch for completing a sync when a suspect
   * pack regex is the suspected cause of a wedge; re-run extraction later.
   * Threaded through performSync AND syncOneSource so `sync --all` honors it.
   */
  noSchemaPack?: boolean;
  /** #6696 (A7): server-only; the drain's first pass checks the run's estimated receipts against the capacity left before admitting. */
  capacityPreflight?: boolean;
  /** #6696: a runtime paid-work constraint (the cost gate deferred this run's embedding); never a processing option, never lifted by cursor adoption. */
  embedDeferred?: boolean;
  /**
   * G8 (persistence/git-conversion.ts): the conversion apply's strict-equivalent full pass, run before the source row says
   * `canonical: git`. Internal: no CLI flag or MCP parameter sets it, it refuses a remote caller, and it cannot reach
   * working-tree mode (resolveManagedSyncContext refuses `--working-tree` for a strict-classified pass).
   */
  canonicalOverride?: 'git';
  /** #7866, internal (the conversion's strict passes): a full round without a `--full` episode, so a page equal to its blob is not re-imported. */
  fullRound?: boolean;
  /** PR A, internal (the conversion's strict passes): the Git verdicts over database versions the plan approved; any other is held (sync-pass.ts ConversionBinding). */
  conversionBinding?: import('../core/persistence/sync-pass.ts').ConversionBinding;
  /**
   * v0.18.0 Step 5 — sync a specific named source. When set, sync reads
   * local_path + last_commit from the sources table (not the global
   * config.sync.* keys) and writes last_commit + last_sync_at back to
   * the same row. Backward compat: when undefined, sync uses the
   * pre-v0.17 global-config path unchanged.
   */
  sourceId?: string;
  /**
   * github source kind: refresh exactly one item (webhook path).
   * When set, sync skips the sweep and re-fetches this single issue/PR.
   */
  githubItem?: { repo: string; number: number; kind: 'issue' | 'pr'; deleted?: boolean };
  /** Multi-repo: sync strategy override (markdown, code, auto). */
  strategy?: 'markdown' | 'code' | 'auto';
  /**
   * #753/#774 — sync only files under this subdirectory of the git repo.
   * Git operations (pull, diff, rev-parse) still run against the repo root
   * (discovered via `git rev-parse --show-toplevel`); file walking, imports,
   * deletes and renames are scoped to the subpath. Slugs are git-root-relative
   * (`wiki/page1.md` → slug `wiki/page1`) so full and incremental syncs of
   * the same scope agree. Enables N logical sources in one git repo.
   *
   * SECURITY (NAV-1/NAV-2): the resolved subpath must realpath-resolve inside
   * the git root — `../escape` and symlinked subdirs pointing outside the repo
   * are rejected before any git op runs.
   */
  srcSubpath?: string;
  /**
   * #753/#774 — glob patterns for files to exclude from sync (repeatable
   * `--exclude` on the CLI). Matched against the scope-relative path in both
   * the full-sync and incremental paths. Excluded files are never imported;
   * exclusion does NOT delete previously-imported pages (conservative,
   * matching the #1433 metafile posture).
   *
   * Unioned with the persisted `sync.exclude` config key (comma- or
   * newline-separated; a trailing `/` is normalized to a `/**` subtree glob),
   * so callers that never touch the CLI — autopilot, minion sync jobs, the
   * dream cycle — inherit the same indexing scope. Union, not override: an
   * ad-hoc flag narrows further but never silently re-opens a scope the
   * operator persisted. Best-effort read, as with `sync.include_working_tree`.
   */
  exclude?: string[];
  /**
   * Repeatable `--include-hidden <glob>` on the CLI — same glob dialect as
   * `exclude`, but waives the leading-dot part of `pruneDir`'s exclusion
   * (`.git`, `.obsidian`, and any other dot-prefixed directory) for paths
   * that match, instead of removing paths. See `isPathPruned` in
   * core/sync.ts for exactly what is and isn't waivable, and its doc
   * comment for the one gap (non-git directory imports via the FS-walk
   * fallback aren't covered). Unlike `exclude`, this has to reach the
   * collection step itself — a pruned path is never collected in the first
   * place, so there's nothing for a post-collection filter to add back.
   *
   * Unioned with the persisted `sync.include_hidden` config key (same dialect
   * and trailing-`/` normalization as `sync.exclude`), so callers that never
   * touch the CLI — `sync --all`, autopilot, the dream cycle — inherit the
   * waiver. Union, not override; unset admits nothing.
   */
  includeHidden?: string[];
  /**
   * Include files matched by .gitignore. Git cannot report untracked ignored
   * changes in diffs, so sync uses the full filesystem walker when this is set.
   */
  includeGitignored?: boolean;
  /**
   * Import uncommitted working-tree state (untracked files + uncommitted
   * tracked edits/deletes) on an ATTACHED HEAD, via the same manifest-merge
   * path detached-HEAD syncs have always used. Off by default: commit-driven
   * sync stays the contract, and uncommitted drift is counted + reported
   * either way (see SyncResult.uncommitted). CLI `--working-tree`; persist
   * with config `sync.include_working_tree=true`. NOTE: the inline cost
   * estimator does not price working-tree files on attached repos, so the
   * gate can underestimate an explicit --working-tree run.
   */
  workingTree?: boolean;
  /**
   * Number of parallel workers for the import phase. When > 1, each worker
   * gets its own small Postgres connection pool and files are dispatched via
   * an atomic queue index (same pattern as `import --workers N`).
   *
   * Deletes and renames remain serial (order-dependent).
   * Default: undefined → auto-concurrency picks (`src/core/sync-concurrency.ts`).
   *
   * v0.22.13 (PR #490 Q1): when this is explicitly set, the >50-file floor
   * is bypassed — explicit user intent beats the auto-path safety net.
   */
  concurrency?: number;
  /**
   * Internal: skip acquiring the gbrain-sync DB lock. Set by the cycle
   * handler (cycle.ts) which already holds gbrain-cycle and therefore
   * already serializes against other cycle runs. CLI sync, jobs handler,
   * and any external caller leave this undefined so they take the lock.
   *
   * v0.22.13 (PR #490 CODEX-2). Not part of the public CLI surface.
   */
  skipLock?: boolean;
  /**
   * Internal: override the DB lock id taken around the writer window.
   * Not part of the public CLI surface — explicit escape hatch for
   * callers that already know which lock id they want.
   *
   * Defaults to:
   *   - `gbrain-sync:<sourceId>` when `opts.sourceId` is set
   *     (multi-source / federated brains; the per-source invariant)
   *   - `gbrain-sync` (the legacy global lock) when `sourceId` is unset
   *     (single-default-source brains; preserves bit-for-bit behavior
   *      for installs that never set up multiple sources)
   *
   * Why source-id keyed by default (v0.40.3.0):
   *   PR #1314 originally only changed the lock id inside the parallel
   *   `sync --all` fan-out. That introduced a worse race than the global
   *   lock fixes — `gbrain sync --all` (per-source lock) running
   *   concurrently with `gbrain sync --source foo` (global lock) would
   *   both write source foo simultaneously. The fix: every source-scoped
   *   sync (CLI, --all fan-out, cycle, jobs handler) defaults to the
   *   per-source lock. Same source = same lock id, always.
   *
   * For the per-source path, `performSync` ALSO switches from bare
   * `tryAcquireDbLock` to `withRefreshingLock` so long-running sources
   * (the PR's whole motivation — media-corpus, 250K+ chunks) don't lose
   * their lock at the 30-minute TTL mid-run. The legacy global-lock
   * path keeps bare `tryAcquireDbLock` for back-compat (no caller
   * depends on the global lock surviving past 30 minutes today).
   *
   * Total live Postgres connections per parallel `sync --all` wave:
   *   parallel  ×  workers  ×  2 (per-file pool inside each worker)
   *   + parent pool. See DEFAULT_PARALLEL_SOURCES in sync-concurrency.ts.
   */
  lockId?: string;
  /**
   * v0.41.13.0 — graceful self-termination signal (PR closing #1472).
   *
   * When set, performSyncInner checks `signal.aborted` at the top of every
   * pre-bookmark iteration (pull, delete loop, rename loop, serial import
   * loop, parallel worker while loop). On abort the function returns
   * `SyncResult { status: 'partial', filesImported, reason: 'timeout' }`,
   * releases the lock cleanly, and the CLI exits 0 so cron doesn't
   * classify the run as failure.
   *
   * D-V3-1 (honest scope): abort checks fire ONLY in pre-bookmark phases.
   * The `last_commit` bookmark writes at sync.ts:1261 BEFORE extract +
   * embed phases run; checking after that line would advance the bookmark
   * for a partial sync. By construction, partial fires before the write,
   * so the D4 invariant "never advance last_commit on partial" is
   * enforced by topology, not by post-write rollback.
   *
   * D-V3-3 (per-source budgets for --all): the CLI's --timeout --all path
   * creates ONE AbortController per source inside `runOne` (sync.ts:1823)
   * so each source gets its own --timeout countdown starting when its
   * runOne invocation starts. NOT a shared global controller.
   *
   * Precedent: CycleOpts.signal at src/core/cycle.ts (v0.22.1 #403).
   */
  signal?: AbortSignal;
  /**
   * Serve-delegated sync progress seam: fired at phase boundaries and on every
   * durable checkpoint flush (cumulative bankedFiles). Sync-fire, never
   * awaited — the delegated-job runner mirrors these into the record that
   * `sync_status` IPC polls read. Absent for direct CLI runs (stderr
   * breadcrumbs already cover that surface).
   */
  onProgress?: (p: { phase: string; bankedFiles?: number; total?: number; waived?: boolean; group?: number;
    /** #5984 lanes (phase `managed_sync.lanes`). */ lanes?: { effective: number; stepDown: string | null; overlapped: number; fallbacks: number }; /** #7243: a pass round (`managed_sync.round_level`, `managed_sync.round_admit`; #7866 `managed_sync.round_batch`: `batch` of `batches`, starting at candidate `base`). */ round?: { round: number; target: string; paths: number; read_ms?: number; imports?: number; deletes?: number; in_flight?: number; batch?: number; batches?: number; base?: number } }) => void;
  /**
   * #5984: managed sync only. Re-enter the single-pass managed sync until the
   * cursor is done, the caller's signal/deadline stops it, or it is blocked
   * (src/core/persistence/sync-drain.ts). Set by the CLI, serve and the `sync` job (#6706); others stay single-pass.
   */
  drain?: boolean;
  /** #6712 PR 1: who takes the source's drain lease (kind and id shown to a follower), and whether a busy lease is followed instead of refused. */
  drainHolder?: import('../core/persistence/sync-lease.ts').DrainHolderRef; followDrainLease?: boolean;
  /** #6706: absolute epoch ms a managed drain stops before (`resumable / deadline`). */ deadlineAtMs?: number;
  /** #5984: wall-clock ms the current drain started; managed cursors measure their rate from it. */ drainStartedAt?: number;
  /** Test seam: how often the drain's governor looks and how long it confirms a blocker (`DrainInput.governMs`). */ governMs?: number;
  /** #5984: `--no-bulk`; and the drain's resolved bulk settings (internal; absent = one request per pass step). */ noBulk?: boolean; bulk?: import('../core/persistence/sync-group.ts').BulkSettings;
  /** #5984 lanes: `--lanes N` (1..16) or `--no-lanes` (1). */ lanes?: number;
}

// The git-plumbing cluster (git(), discoverGitRoot, createSyncBaselineCommit,
// path-containment guards, ...) was peeled to src/core/sync-git.ts (pure
// move). Re-exported so existing importers keep working.
export {
  resolveSlugByPathOrSourcePath,
  buildGitInvocation,
  buildAutoEmbedArgs,
  resolveNoEmbed,
  discoverGitRoot,
  classifyHeadProbeError,
  createSyncBaselineCommit,
  isWithinRoot,
} from '../core/sync-git.ts';

// The anchor / chunker-version cluster (readSyncAnchor, writeSyncAnchor,
// readChunkerVersion, ...) was peeled to src/core/sync-anchor.ts (pure move).
export { writeSyncAnchor } from '../core/sync-anchor.ts';

// The lock layer minus performSync (SyncLockBusyError, formatLockBusyMessage,
// runBreakLock, buildPartialResult) was peeled to src/core/sync-lock.ts
// (pure move). Re-exported so existing importers keep working.
export { SyncLockBusyError, runBreakLock } from '../core/sync-lock.ts';

// The reconcile + deadline cluster (planReconcileDeletes, the #2828
// mass-delete valve, resolveSyncHardDeadline, composeAbortSignals, ...) was
// peeled to src/core/sync-reconcile.ts (pure move). Re-exported so existing
// importers keep working.
export {
  MASS_RECONCILE_RATIO,
  MASS_RECONCILE_MIN_PAGES,
  type ReconcilePlan,
  planReconcileDeletes,
  listEverCommittedPaths,
  massReconcileAllowed,
  HARD_DEADLINE_GRACE_SEC,
  type HardDeadlineResolution,
  DEFAULT_SYNC_STALL_ABORT_SEC,
  resolveStallAbortSeconds,
  resolveSyncHardDeadline,
  composeAbortSignals,
} from '../core/sync-reconcile.ts';

export async function runSync(engine: BrainEngine, args: string[], opts: { ownSignals?: boolean } = {}) {
  // #4888: under --json, stdout is reserved for the ONE JSON envelope (#4684:
  // the cost-gate status object rides inside it as `cost_gate`); every slog()
  // human line from performSync and its callees routes to stderr instead.
  // serr/progress are stderr already. The envelope (sync/run.ts emitJson) and
  // `sync status|unblock --json` (sync/operator.ts) write through
  // writeJsonDocument, the guard's only stdout path.
  const stopTrace = startMemoryTrace('sync');
  try { const out = await (args.includes('--json') ? withHumanLogsToStderr(() => runSyncInner(engine, args, opts)) : runSyncInner(engine, args, opts)); await (await import('./sources-add-next.ts')).noteSyncOutOfSearch(engine, args); return out; } finally { stopTrace(); clearTerminationFallback(); }
}

/**
 * v0.40.3.0 — resolve effective per-source concurrency for `sync --all`.
 *
 * Inputs:
 *   - sourceCount: number of `syncEnabled !== false` sources to walk
 *   - explicitParallel: user's `--parallel N` value (post `parseWorkers`),
 *     `undefined` when the flag was not provided
 *   - workers: user's `--workers N` value, used as a soft cap when no
 *     explicit `--parallel` is given. The per-source budget can't exceed
 *     the per-file worker count because each per-file worker opens its
 *     own PostgresEngine pool — see DEFAULT_PARALLEL_SOURCES in
 *     `src/core/sync-concurrency.ts` for the connection-math story.
 *   - engineKind: PGLite is single-connection → always returns 1.
 *
 * Rules:
 *   - PGLite → always 1
 *   - sourceCount <= 0 → 1 (divide-by-zero guard)
 *   - explicit `--parallel` → wins, clamped to `[1, sourceCount]`
 *   - auto path → `min(sourceCount, workers ?? DEFAULT_PARALLEL_SOURCES)`
 *
 * Returns >= 1. Single-source brains return 1 (no point fanning out).
 */
export function resolveParallelism(input: {
  sourceCount: number;
  explicitParallel?: number;
  workers?: number;
  engineKind: 'pglite' | 'postgres';
}): number {
  if (input.engineKind === 'pglite') return 1;
  if (input.sourceCount <= 0) return 1;
  if (input.explicitParallel !== undefined) {
    return Math.max(1, Math.min(input.explicitParallel, input.sourceCount));
  }
  const ceiling = input.workers && input.workers > 0
    ? Math.min(input.workers, DEFAULT_PARALLEL_SOURCES)
    : DEFAULT_PARALLEL_SOURCES;
  return Math.max(1, Math.min(input.sourceCount, ceiling));
}

/**
 * v0.40.3.0 — per-source sync wrapper for the `--all` worker pool.
 *
 * Three responsibilities:
 *   1. Build the per-source `SyncOpts` from the shared CLI flags.
 *   2. Wrap the call in `withSourcePrefix(src.id, ...)` so every
 *      `slog`/`serr` line emitted from inside `performSync` (and its
 *      callees) gets prefixed with `[<source-id>] ` for greppable
 *      parallel output (D6 + D12 + D13).
 *   3. Pre-render the start banner into the returned `log` string so
 *      the worker pool flushes it (and any subsequent `printSyncResult`)
 *      via the human sink — which `--json` routes to stderr to keep
 *      stdout JSON-only (D4).
 *
 * Note: source.name is shown in the start banner (one-shot, easy to
 * escape) but the prefix on every line uses source.id (slug-validated;
 * no newline-injection risk per D13).
 *
 * The per-source DB lock invariant (D8) fires inside `performSync` —
 * since `repoOpts.sourceId` is set, the per-source lock is the default.
 * `withRefreshingLock` (D11) handles TTL renewal automatically for
 * sources that exceed 30 minutes.
 */
export async function syncOneSource(
  engine: BrainEngine,
  src: { id: string; name: string; local_path: string | null; config: Record<string, unknown> },
  shared: {
    dryRun: boolean;
    full: boolean;
    noPull: boolean;
    noEmbed: boolean;
    skipFailed: boolean;
    retryFailed: boolean;
    concurrency: number | undefined;
    /** v0.41.37.0 #1569: propagate --no-schema-pack into every per-source sync. */
    noSchemaPack?: boolean;
    /** v0.42.7 #1696: propagate --no-extract into every per-source sync. */
    noExtract?: boolean;
    includeGitignored?: boolean;
    /** Untracked-gap fix: propagate --working-tree into every per-source sync. */
    workingTree?: boolean;
  },
): Promise<{ result: SyncResult; log: string }> {
  const cfg = (src.config || {}) as { strategy?: 'markdown' | 'code' | 'auto' };
  const log = `\n--- Syncing source: ${src.name} ---\n`;
  const repoOpts: SyncOpts = {
    repoPath: msysToNativePath(src.local_path!), // #2955: heal MSYS /c/... before joins
    dryRun: shared.dryRun,
    full: shared.full,
    noPull: shared.noPull,
    noEmbed: shared.noEmbed,
    noExtract: shared.noExtract,
    skipFailed: shared.skipFailed,
    retryFailed: shared.retryFailed,
    noSchemaPack: shared.noSchemaPack,
    includeGitignored: shared.includeGitignored,
    workingTree: shared.workingTree,
    sourceId: src.id,
    strategy: cfg.strategy,
    concurrency: shared.concurrency,
    // lockId defaults to `gbrain-sync:${src.id}` via the performSync invariant (sourceId triggers it).
  };
  const result = await withSourcePrefix(src.id, () => performSync(engine, repoOpts));
  return { result, log };
}

// The status-report cluster (buildSyncStatusReport, printSyncStatusReport)
// was peeled to src/core/sync-status-report.ts (pure move). Re-exported so
// existing importers keep working.
export {
  buildSyncStatusReport,
  printSyncStatusReport,
  type SyncStatusReport,
  type SyncStatusReportSource,
} from '../core/sync-status-report.ts';