Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
76.9 KB
Raw Blame
import { writeJsonDocument } from '../core/cli-force-exit.ts';
import { cliRenderContext, renderNotice } from '../core/agent-output.ts';
import { ignoredPrivacyLabelRunNotice } from '../core/search/ignored-privacy-labels.ts';
import { importFenceTally, type FencesNormalized } from '../core/fence-repair/report.ts';
import { opError } from '../core/ops/contract.ts';
import { hasSourceFilesystemLock, withSourceFilesystemLock, currentSourceFilesystemSignal } from '../core/minions/source-filesystem.ts';
import { readdirSync, lstatSync, existsSync, mkdirSync } from 'fs';
import { recordFunnelEvent } from '../core/funnel.ts';
import { execFileSync } from '../core/spawn.ts';
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'path';
import { cpus, totalmem } from 'os';
import type { BrainEngine } from '../core/engine.ts';
import { OperationError } from '../core/ops/contract.ts';
import { importFile, importImageFile, isImageFilePath, type ImportResult } from '../core/import-file.ts';
import { gitFirstCommitDates } from '../core/git-first-commit.ts';
import { gitLsFiles } from '../core/git-visible-files.ts';
import { currentCompanyBrainSync, importCompanyBrainFile } from '../core/company-brain/profile.ts';
import { loadConfig, gbrainPath } from '../core/config.ts';
import { createProgress } from '../core/progress.ts';
import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';
import {
  hasMalformedPathSegment,
  sanitizePathForDisplay,
  isCodeFilePath,
  isMarkdownFilePath,
  isImageFilePath as isImageFilePathFromSync,
  matchesAnyGlob,
  pruneDir,
  isPathPruned,
  isSyncMetafile,
  DEFAULT_METAFILE_PAGES_MODE, readMetafilePagesMode, type MetafilePagesMode,
  type SyncStrategy,
} from '../core/sync.ts';
import { diskMetafileHeads, metafilePagePredicate } from '../core/sync-metafile-pages.ts';
import { sortNewestFirst } from '../core/sort-newest-first.ts';
import {
  loadCheckpoint,
  saveCheckpoint,
  clearCheckpoint,
  resolveImportTargetDir,
  resumeFilter,
} from '../core/import-checkpoint.ts';
import { realpathOrResolve } from '../core/path-confine.ts';
import { slog } from '../core/console-prefix.ts';
import { refreshProjectionStatistics } from '../core/search/projection-statistics.ts';
import { importAnalyzeEveryPages, maybeRefreshPlannerStats, PLANNER_STATS_REPAIR_COMMAND } from '../core/planner-stats.ts';
import { importManagedFile, managedImportWriteThroughRefusal, nextImportBatch, settleManagedImportBatch } from '../core/persistence/import-mutations.ts';
import { acceptedPendingReceipt } from '../core/persistence/accepted-pending.ts';
import { estimateCostFromChars, lookupEmbeddingPrice } from '../core/embedding-pricing.ts';
import { getEmbeddingModel } from '../core/ai/gateway.ts';
import { managedRootMarkerFor } from '../core/persistence/root-registry.ts';
import { readManagedMode } from '../core/persistence/ownership.ts';
import { readPageBodyPolicy } from '../core/page-body/limits.ts';
import { importSourceRefusal } from './import-source-refusal.ts';

/** Return a refusal when an import target lies outside every admitted root. */
export function configuredRootImportError(dir: string, configuredRoots: string[]): string | null {
  if (configuredRoots.length === 0) return null;
  const target = realpathOrResolve(dir);
  const admitted = configuredRoots.some((candidate) => {
    const root = realpathOrResolve(candidate);
    const rel = relative(root, target);
    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
  });
  if (admitted) return null;
  return (
    `Import root ${target} is not under the configured root for the destination source ` +
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- error-message hint construction, no fs operation
        `(${configuredRoots.map((root) => resolve(root)).join(', ')}). ` +
    `Pass --allow-noncanonical-root to override deliberately.`
  );
}

/** Resolve only roots belonging to the selected import destination. */
export async function listConfiguredRoots(
  engine: BrainEngine,
  destinationSourceId: string,
): Promise<string[]> {
  const roots: string[] = [];
  try {
    const rows = await engine.executeRaw<{ local_path: string | null }>(
      `SELECT local_path FROM sources WHERE id = $1`,
      [destinationSourceId],
    );
    for (const row of rows) if (row.local_path && isAbsolute(row.local_path)) roots.push(resolve(row.local_path)); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- resolves REGISTERED roots to build the containment allowlist (#4388 guard)
    if (destinationSourceId === 'default') {
      const legacyRoot = await engine.getConfig('sync.repo_path');
      if (legacyRoot && isAbsolute(legacyRoot)) roots.push(resolve(legacyRoot)); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- same: registered root canonicalization for the guard allowlist
    }
  } catch (error) {
    throw new Error(
      `Cannot determine configured source roots: ` +
      `${error instanceof Error ? error.message : String(error)}`,
    );
  }
  return [...new Set(roots)];
}

/**
 * Records one failed file against the run's error-grouping state and
 * returns the running count for its group plus an unredacted sample
 * message for display.
 *
 * `key` groups structurally-identical errors (e.g. the same failure
 * across many files) so a single noisy failure mode doesn't produce
 * thousands of near-duplicate warning lines — quoted substrings (typically
 * a per-file slug or path) are blanked for the GROUPING key only. The
 * printed `sample` is always a real, unredacted occurrence of the error
 * (the first one seen for that key), so identifying details that are
 * constant across the whole group — a Postgres table or constraint name,
 * for instance — survive into what actually gets shown to the user.
 * Pre-fix, the redacted key itself was printed, so e.g. a `pages_source_id_fkey`
 * foreign-key violation surfaced as `table "" violates foreign key constraint ""`.
 */
export function recordImportFailure(
  errorCounts: Record<string, number>,
  errorSamples: Record<string, string>,
  msg: string,
): { key: string; count: number; sample: string } {
  const key = msg.replace(/"[^"]*"/g, '""');
  const count = (errorCounts[key] ?? 0) + 1;
  errorCounts[key] = count;
  if (!(key in errorSamples)) errorSamples[key] = msg;
  return { key, count, sample: errorSamples[key] };
}

function defaultWorkers(): number {
  const cpuCount = cpus().length;
  const memGB = totalmem() / (1024 ** 3);
  // Network-bound, so we can go higher than CPU count.
  // Cap by: DB pool (leave 2 for other queries), CPU, memory.
  const byPool = 8;
  const byCpu = Math.max(2, cpuCount);
  const byMem = Math.floor(memGB * 2);
  return Math.min(byPool, byCpu, byMem);
}

/**
 * W0 fix-wave (Tier-1 #5): typed abort for runImport's preflight/argv
 * failures. Pre-fix these five sites called process.exit(1) directly —
 * correct for the CLI, but runImport is ALSO invoked in-process by the
 * sync_brain MCP op (via performFullSync), the autopilot daemon, and the
 * minion sync handler, so a first sync with unconfigured embedding
 * credentials TERMINATED the MCP server / daemon / worker mid-call. The
 * user-facing messages are printed BEFORE the throw (byte-identical CLI
 * output); the CLI dispatch site maps this error back to exit(exitCode).
 */
export class ImportAbortError extends Error {
  readonly exitCode: number;
  /** Present only after an interrupted import has drained and checkpointed. */
  readonly partialResult?: RunImportResult;
  /** True: the user-facing message was already printed at the throw site. */
  readonly alreadyReported = true;
  /** `cause` keeps the underlying error (and its stack) for in-process callers. */
  constructor(reason: string, exitCode = 1, partialResult?: RunImportResult, cause?: unknown) {
    super(`import aborted: ${reason}`, cause === undefined ? undefined : { cause });
    this.name = 'ImportAbortError';
    this.exitCode = exitCode;
    this.partialResult = partialResult;
  }
}

// The CLI dispatch (src/cli/commands/import.ts) exits on any ImportAbortError
// without printing, so each refusal below prints its reason and the next
// command to stderr before the caller throws the returned abort.

/** A managed import of a symlinked input root: name the path, its target and the command that works. */
function symlinkedRootAbort(dirArg: string, dir: string): ImportAbortError {
  console.error(`Managed import refuses a symlinked input root: ${dirArg} resolves to ${dir}.`);
  console.error(`Fix: gbrain import ${dir}`);
  return new ImportAbortError('managed import refuses a symlinked input root');
}

/** A refused source filesystem lock admission: print its code, message and fix, and keep it as the cause. */
function lockAdmissionAbort(dirArg: string, dir: string, error: unknown): ImportAbortError {
  const message = error instanceof Error ? error.message : String(error);
  console.error(`Cannot import ${dirArg}: source filesystem lock admission failed.`);
  if (error instanceof OperationError) {
    console.error(`Error [${error.code}]: ${message}`);
    if (error.suggestion) console.error(`Fix: ${error.suggestion}`);
    const marker = error.code === 'writer_coordinator_required' ? managedRootMarkerFor(dir)?.marker : undefined;
    if (marker) console.error(`Marker: ${marker}`);
  } else {
    console.error(`Error: ${message}`);
    console.error('Fix: gbrain doctor --json');
  }
  const reason = error instanceof OperationError ? `${error.code}: ${message}` : message;
  return new ImportAbortError(`source filesystem lock admission failed (${reason})`, 1, undefined, error);
}

/**
 * #3969 — a poll that changed nothing is not an ingest event. Cron-driven
 * `import`/`sync` against a mostly-static tree was writing an ingest_log row
 * every run ("Imported 0 pages, N skipped, 0 chunks" — 93% of rows on a
 * 15-minute cadence), burying real events past get_ingest_log's default
 * LIMIT 20. Shared by runImport (directory imports) and performSync (git
 * syncs). `logNoop` (CLI `--log-noop`) opts back into per-poll rows for
 * deployments using them as a liveness signal.
 */
export function shouldLogIngest(
  counts: { imported: number; errors: number; chunksCreated: number },
  logNoop: boolean,
): boolean {
  if (logNoop) return true;
  return counts.imported > 0 || counts.errors > 0 || counts.chunksCreated > 0;
}

/** Embedding cost of the chunks a safe-chunk re-seal left without vectors; null when the model has no known price. */
function resealEmbeddingUsd(chars: number): number | null {
  try {
    const price = lookupEmbeddingPrice(getEmbeddingModel());
    return price.kind === 'known' ? estimateCostFromChars(chars, price.pricePerMTok) : null;
  } catch { return null; }
}

/** Bug 9 — surface per-file failures so callers (performFullSync) can gate state advances. */
export interface RunImportResult {
  imported: number;
  skipped: number;
  errors: number;
  chunksCreated: number;
  failures: Array<{ path: string; error: string }>;
  /** Files dropped by the malformed-filename gate (walker + per-file defense). */
  malformedSkipped?: number;
  /** Aggregated alias/undeclared explicit-type warnings (schema.type_warnings). */
  type_warnings?: Array<{ kind: 'alias_of' | 'undeclared'; type: string; canonical?: string; directory?: string; count: number }>;
  /** #5050: unchanged pages re-sealed at the safe-chunk fence, and the embedding work that left. */
  resealed?: { pages: number; pending_chunks: number; embedding_usd: number | null }; fences_normalized?: FencesNormalized; fence_issues?: unknown;
  /** GST-2462: the run's one `privacy_label_ignored` notice (counts by value of ignored privacy labels). */ privacy_label_notice?: import('../core/agent-output.ts').Notice;
}

/**
 * D2 + A1: under `--json` a keyless brain's import refusal is the one document.
 * The step the agent can take now is the same import with --no-embed (pages
 * stay keyword-searchable; vectors come later), routed explicitly to the brain
 * and source this run resolved; turning embeddings on asks the user.
 */
async function keylessImportRefusal(engine: BrainEngine, args: string[], e: unknown) {
  const { brainRoutingArgs } = await import('../core/brain-resolver.ts');
  const { resolveSourceWithTier } = await import('../core/source-resolver.ts');
  const named = args.some(a => a === '--source' || a === '--source-id' || a.startsWith('--source=') || a.startsWith('--source-id='));
  const target = named ? undefined : await resolveSourceWithTier(engine, null).then(r => r.source_id, () => undefined);
  return opError('embedding_disabled', String(e instanceof Error ? e.message.split('\n')[0] : e),
    'Embeddings are off by choice on this brain, so import needs --no-embed; turning embeddings on needs the user\'s consent (gbrain doctor --only embeddings --json shows the command).', {
      reason: 'disabled_by_choice',
      why: 'This brain was set up keyword-only. Importing with --no-embed keeps every page keyword-searchable; `gbrain embed --stale` adds vectors once embeddings are enabled.',
      fix: {
        argv: ['gbrain', 'import', ...args.filter(a => a !== '--json' && a !== '--no-embed'), '--no-embed', '--json',
          ...(target ? ['--source', target] : []), ...brainRoutingArgs()],
        consent: [], actor: 'agent', requires_exclusive: true,
        why: 'Imports the same files without computing vectors, which needs no provider key.',
      },
    });
}

type ImportFileResultCallback = (path: string, filePath: string, result: Pick<ImportResult, 'status' | 'error' | 'refusal' | 'frontmatter_recovery' | 'fences_normalized' | 'fence_issues'>) => Promise<'held' | undefined>;

/** GBRA-130 A-66: a throwing caller callback is that file's outcome, never a rejection of the whole import. */
async function reportFileResult(onFileResult: ImportFileResultCallback | undefined, ...args: Parameters<ImportFileResultCallback>): Promise<'held' | undefined> {
  try { return await onFileResult?.(...args); }
  catch (e) {
    console.error(`  Warning: could not record the outcome of ${sanitizePathForDisplay(args[0])} (${e instanceof Error ? e.message : String(e)}); it is not held, the import continues.`);
    return undefined;
  }
}

export async function runImport(
  engine: BrainEngine,
  args: string[],
  opts: {
    signal?: AbortSignal;
    commit?: string; /** GBRA-217: a full sync's reason and history-gap note per file (absolute path) for the snapshot its import archives. */ history?: (filePath: string) => import('../core/page-state/versions.ts').VersionHistory | undefined;
    strategy?: SyncStrategy;
    sourceId?: string;
    managedBookmark?: boolean;
    /** GST-2462: the run the privacy_label_ignored notice names. */ noticeRun?: 'sync';
    /** Paths the caller keeps out of this run (#5988 holds, #8620 reserved skill paths); skipped without importing, not failures. */
    heldPaths?: Pick<ReadonlySet<string>, 'has'>;
    /** #5988: each file's outcome (a throw arrives as `{ status: 'error', error }`); `'held'` = the caller held it, not a failure. */
    onFileResult?: ImportFileResultCallback;
    /**
     * #753/#774: glob patterns to exclude from the import (same semantics as
     * `isSyncable`'s `exclude` — matched against the dir-relative path).
     * Threaded by performFullSync for `gbrain sync --exclude`.
     */
    exclude?: string[];
    /**
     * #2404-class: repeatable glob patterns (same dialect as `exclude`)
     * that waive the leading-dot prune heuristic for matching paths — see
     * `isPathPruned` in core/sync.ts. Unlike `exclude`, this cannot be a
     * post-collection filter: a pruned path is never collected in the
     * first place, so it has to reach `collectSyncableFiles` itself.
     * Threaded by performFullSync for `gbrain sync --include-hidden`.
     */
    includeHidden?: string[];
    /**
     * Opt out of the git-visible fast path and walk the filesystem directly,
     * so markdown/code files matched by .gitignore can still be imported.
     */
    includeGitignored?: boolean;
    /**
     * #753/#774 monorepo subdir-source support: when set, slugs and
     * `source_path` are computed relative to this root (the git repo root)
     * instead of `dir` (the sync scope), so `wiki/page1.md` lands as slug
     * `wiki/page1` consistently across full and incremental sync.
     */
    slugRoot?: string;
  } = {},
): Promise<RunImportResult> {
  const inheritedSignal = currentSourceFilesystemSignal();
  const signal = opts.signal && inheritedSignal ? AbortSignal.any([opts.signal, inheritedSignal]) : opts.signal ?? inheritedSignal;
  signal?.throwIfAborted();
  const noEmbed = args.includes('--no-embed') || args.includes('--calls');
  const allowNoncanonicalRoot = args.includes('--allow-noncanonical-root');
  const fresh = args.includes('--fresh');
  const jsonOutput = args.includes('--json');
  // #3969: opt back into per-poll ingest_log rows (default: no-op runs skip the write).
  const logNoop = args.includes('--log-noop');
  const includeGitignored = args.includes('--include-gitignored') || opts.includeGitignored === true;

  // #3637: under --json, stdout belongs to the JSON document alone. The
  // informational lines below are useful — they just belong on the other
  // channel, the same rule progress already follows (CLAUDE.md: "Progress
  // always writes to stderr. Stdout stays clean for data output (--json
  // payloads)"). Pre-fix, `import --json` prefixed the payload with
  // "Found N markdown files", so JSON.parse of stdout failed outright.
  // The human branch goes through slog() so an in-process caller running in
  // its own --json mode (`sync --json` → performFullSync → runImport, wrapped
  // in withHumanLogsToStderr) keeps its stdout clean too; outside any wrap
  // slog IS console.log.
  const info = (msg: string): void => {
    if (jsonOutput) console.error(msg);
    else slog(msg);
  };

  // T7 (D9): refuse cleanly when init persisted the deferred-setup sentinel,
  // unless the user is explicitly skipping embedding via `--no-embed` (in
  // which case the chunks land without vectors and the user can backfill
  // later with `gbrain embed --stale` after configuring a provider).
  if (!noEmbed) {
    const { assertEmbeddingEnabled } = await import('../core/embedding-dim-check.ts');
    const { loadConfig } = await import('../core/config.ts');
    try {
      assertEmbeddingEnabled(loadConfig());
    } catch (e) {
      if (jsonOutput) throw await keylessImportRefusal(engine, args, e);
      console.error(`\n${e instanceof Error ? e.message : e}\nTip: run \`gbrain import <dir> --no-embed\` to import without embedding now.`);
      throw new ImportAbortError('embedding disabled (deferred-setup sentinel)');
    }

    // v0.41.6.0 D1: preflight embedding credentials. Closes the bug class
    // where `gbrain import` per-file embed writes N identical
    // "missing OPENAI_API_KEY" failures into sync-failures.jsonl.
    const { validateEmbeddingCreds, EmbeddingCredentialError } = await import('../core/embed-preflight.ts');
    try {
      validateEmbeddingCreds();
    } catch (e) {
      if (e instanceof EmbeddingCredentialError) {
        if (jsonOutput) {
          await writeJsonDocument(JSON.stringify({ status: 'embedding_credentials_missing', diagnosis: e.diagnosis }));
        } else {
          console.error('');
          console.error(e.userMessage);
          console.error('');
        }
        throw new ImportAbortError('embedding credentials missing');
      }
      throw e;
    }
  }
  // v0.30.x follow-up to PR #707: programmatic sourceId support so internal
  // callers (performFullSync, future Step 6 paths) can route to a named
  // source.
  //
  // #1167: the CLI flag shipped as `--source-id <id>`. #4862: `--source <id>`
  // is an alias — it is what every sibling command and the resolver's own
  // nudge tell users to pass, import has no competing --source axis, and the
  // flag registry already accepted it, so pre-alias it was silently IGNORED
  // (pages landed in default). Both spellings with different values abort.
  // Programmatic callers continue passing `opts.sourceId` directly; CLI
  // flags win over opts when both are set. Both the `--source value` and
  // `--source=value` spellings are accepted (same for --source-id); a missing
  // value (or a value that is itself a flag) is refused the way sync-delegate
  // refuses it, never read as "no scope".
  const sourceIdIdx = args.indexOf('--source-id');
  const sourceIdx = args.indexOf('--source');
  const readSourceFlag = (flag: string, idx: number): string | null => {
    const eq = args.find((a) => a.startsWith(`${flag}=`));
    const v = eq !== undefined ? eq.slice(flag.length + 1) : idx !== -1 ? args[idx + 1] : null;
    if (v === null) return null;
    if (v === undefined || v === '' || v.startsWith('--')) {
      console.error(`${flag} (missing value)`);
      throw new ImportAbortError(`${flag} (missing value)`);
    }
    return v;
  };
  const viaSourceId = readSourceFlag('--source-id', sourceIdIdx);
  const viaSource = readSourceFlag('--source', sourceIdx);
  if (viaSourceId && viaSource && viaSourceId !== viaSource) {
    console.error('Pass either --source or --source-id, not both.');
    throw new ImportAbortError('conflicting source flags');
  }
  const flagSourceId = viaSourceId ?? viaSource;
  let sourceId: string | undefined = opts.sourceId;
  if (flagSourceId) {
    // Validate + assert existence through the shared resolver (tier 1), so an
    // invalid or unregistered id fails once with the same SourceTargetError
    // sync gives — not once per file on the pages.source_id foreign key.
    const { resolveSourceWithTier, ALL_SOURCES } = await import('../core/source-resolver.ts');
    if (flagSourceId === ALL_SOURCES) {
      console.error(`import writes to one source; \`${ALL_SOURCES}\` is not a write target.`);
      throw new ImportAbortError('__all__ is not an import target');
    }
    sourceId = (await resolveSourceWithTier(engine, flagSourceId)).source_id;
  }

  // v0.41.13 (#1434): when no explicit source / env / opts.sourceId is set,
  // fall through to the resolver so the new sole_non_default tier (5.5) can
  // auto-route to the only registered non-default source. Pre-fix, import
  // followed the explicit-only design from PR #707 and silently routed
  // every import to 'default', mirroring the sync bug class.
  //
  // Resolution chain (full 7 tiers): flag → env → dotfile → local_path →
  // brain_default → sole_non_default → seed_default. The nudge fires only
  // when the resolver returns tier='sole_non_default', so explicit users
  // see no behavior change.
  if (!sourceId && process.env.GBRAIN_SOURCE) {
    const { resolveSourceId } = await import('../core/source-resolver.ts');
    sourceId = await resolveSourceId(engine, null);
  } else if (!sourceId) {
    const {
      resolveSourceWithTier,
      formatSoleNonDefaultNudge,
      defaultWriteAllowedByEnv,
      assessDefaultWriteGuardOnce,
      formatDefaultWriteWarning,
    } = await import('../core/source-resolver.ts');
    const resolved = await resolveSourceWithTier(engine, null);
    // Only adopt the resolution when it improves on the seed_default
    // fallback — that preserves the v0.30.x "default-only when unset"
    // contract for the common case AND opens the sole_non_default
    // auto-route for the single-source-brain case.
    if (resolved.tier === 'sole_non_default') {
      sourceId = resolved.source_id;
      const nudge = formatSoleNonDefaultNudge(sourceId);
      if (nudge) process.stderr.write(nudge + '\n');
    } else if (!defaultWriteAllowedByEnv()) {
      // #4583 (fixes #4564's misrouted-write symptom): an unscoped import that
      // would silently land in 'default' on a bulk-non-default brain gets a
      // loud warning. Keyed on the REAL destination, not the tier: only the
      // sole_non_default adoption above changes where this run writes, so for
      // EVERY other tier — seed_default, but also dotfile / local_path /
      // brain_default, whose resolutions runImport deliberately does not
      // adopt — `sourceId` stays undefined and the write lands in 'default'.
      // (Warning only on seed_default let exactly those non-adopted tiers
      // land in 'default' silently while the user believed the dotfile or
      // sources.default had scoped the import.) Advisory only — refusing here
      // would change behaviour for callers that never asked about source
      // routing, and runImport also runs in-process (sync_brain MCP op,
      // autopilot daemon, minion sync), where aborting takes the host down
      // mid-call. The CLI escape is the source-id flag; scripted pipelines
      // set GBRAIN_ALLOW_DEFAULT_WRITE=1. The assessment (an unindexed
      // full-`pages` aggregate) is memoized per engine for the process — the
      // in-process callers above run runImport many times on one engine.
      const assessment = await assessDefaultWriteGuardOnce(engine);
      if (assessment.shouldGuard) {
        console.error(formatDefaultWriteWarning(assessment, '--source-id'));
      }
    }
  }
  const refusedSource = await importSourceRefusal(engine, sourceId);
  if (refusedSource) throw new ImportAbortError(refusedSource);
  let importActivePack: { page_types: ReadonlyArray<{ name: string; path_prefixes: ReadonlyArray<string>; aliases?: ReadonlyArray<string> }> } | undefined;
  try {
    const { loadActivePackForEngine } = await import('../core/schema-pack/engine-resolution.ts');
    const resolved = await loadActivePackForEngine(engine, { remote: false, sourceId });
    importActivePack = { page_types: resolved.manifest.page_types };
  } catch {
    importActivePack = undefined;
  }
  const bodyPolicy = await readPageBodyPolicy(engine);

  const workersIdx = args.indexOf('--workers');
  const workersArg = workersIdx !== -1 ? args[workersIdx + 1] : null;
  // v0.22.13 (PR #490 Q2): shared parseWorkers helper rejects bad input
  // (--workers 0, -3, "foo") with a loud error instead of silently falling
  // through to 1. Mirrors sync.ts's flag handling.
  const { clampWorkersForConnectionBudget, parseWorkers, resolveMaxConnections } = await import('../core/sync-concurrency.ts');
  let workerCount: number;
  try {
    workerCount = parseWorkers(workersArg ?? undefined) ?? 1;
  } catch (e) {
    console.error(e instanceof Error ? e.message : String(e));
    throw new ImportAbortError('invalid --workers value');
  }
  // Find dir: first non-flag arg that isn't a value for --workers
  const flagValues = new Set<number>();
  if (workersIdx !== -1) flagValues.add(workersIdx + 1);
  if (sourceIdIdx !== -1) flagValues.add(sourceIdIdx + 1);
  if (sourceIdx !== -1) flagValues.add(sourceIdx + 1);
  const dirArg = args.find((a, i) => !a.startsWith('--') && !flagValues.has(i) && args[i - 1] !== '--access-policy' && args[i - 1] !== '--prefix');

  if (!dirArg) {
    console.error('Usage: gbrain import <dir> [--no-embed] [--workers N] [--fresh] [--source <id> | --source-id <id>] [--access-policy <exported-source>|none] [--include-gitignored] [--allow-noncanonical-root] [--calls [--prefix <slug prefix>]] [--json]');
    throw new ImportAbortError('no import directory given');
  }
  // #1728: capture the import target ONCE as an absolute real path. Every
  // downstream consumer of `dir` (collection, checkpoint load/save, resume
  // filtering) sees the same canonical identity — never the caller's `.`/
  // relative spelling, which would make the persisted checkpoint `dir`
  // resolve against whatever CWD a later process happens to run from.
  let dir: string;
  try {
    dir = resolveImportTargetDir(dirArg);
  } catch (e) {
    console.error(`Import target is not readable: ${dirArg} (${e instanceof Error ? e.message : String(e)})`);
    throw new ImportAbortError(`import target not readable: ${dirArg}`);
  }
  if (args.includes('--calls')) return (await import('./import-calls.ts')).runCallImport(engine, dir, args, { sourceId, json: jsonOutput });

  const managedImport = await readManagedMode(engine);
  if (managedImport && dir !== resolve(dirArg)) throw symlinkedRootAbort(dirArg, dir);
  const preAdmission = managedImport && !opts.managedBookmark && !currentCompanyBrainSync(sourceId) ? await managedImportWriteThroughRefusal(engine, sourceId ?? 'default') : null;
  if (preAdmission) {
    console.error(`Error [${preAdmission.code}]: ${preAdmission.message}\nFix: ${preAdmission.suggestion}`);
    throw new ImportAbortError(preAdmission.message, 1, undefined, preAdmission);
  }
  const singleFile = managedImport && lstatSync(dir).isFile();
  const importRoot = singleFile ? dirname(dir) : dir;

  if (!managedImport && !hasSourceFilesystemLock(dir)) {
    let entered = false;
    try {
      return await withSourceFilesystemLock(engine, dir, () => {
        entered = true;
        return runImport(engine, args, opts);
      }, { signal });
    } catch (error) {
      // Root discovery is part of admission. Preserve the CLI/library's typed
      // preflight error contract without changing errors from an import in flight.
      if (entered || signal?.aborted) throw error;
      throw lockAdmissionAbort(dirArg, dir, error);
    }
  }

  if (!allowNoncanonicalRoot) {
    try {
      const strictRoot = (await engine.getConfig('import.require_configured_root')) === 'true';
      if (strictRoot) {
        const configuredRoots = await listConfiguredRoots(engine, sourceId ?? 'default');
        if (configuredRoots.length === 0) {
          console.error(
            'import.require_configured_root is enabled but the destination source has no configured root. ' +
            'Configure its local_path or pass --allow-noncanonical-root deliberately.',
          );
          throw new ImportAbortError('configured-root admission has no destination root');
        }
        const refusal = configuredRootImportError(dir, configuredRoots);
        if (refusal) {
          console.error(refusal);
          throw new ImportAbortError('import target is outside the configured destination root');
        }
      }
    } catch (error) {
      if (error instanceof ImportAbortError) throw error;
      console.error(
        `Cannot evaluate configured-root admission: ` +
        `${error instanceof Error ? error.message : String(error)}. ` +
        `Pass --allow-noncanonical-root to bypass deliberately.`,
      );
      throw new ImportAbortError('configured-root admission failed closed');
    }
  }

  if (!opts.commit && !singleFile && !currentCompanyBrainSync(sourceId)) await (await import('../core/access/policy-transfer.ts')).importPolicyBarrier(engine, sourceId ?? 'default', dir, args, info).catch(e => { throw new ImportAbortError('folder rules not installed', 1, undefined, e); });
  // v0.31.2: collect under the right strategy. Pre-fix this called
  // collectMarkdownFiles unconditionally — code-strategy first sync
  // silently no-op'd because no code file ever made it through walker
  // enumeration (codex C11 confirms dispatch was correct; bug was here).
  const strategy: SyncStrategy = opts.strategy ?? 'markdown';
  const _walkT0 = Date.now();
  console.error(`[gbrain phase] import.collect_files start dir=${dir} strategy=${strategy}`);
  const malformedExcluded: string[] = [];
  const company = currentCompanyBrainSync(sourceId);
  let allFiles = company ? company.plan.manifest.filter(entry => entry.disposition === 'included').map(entry => join(dir, entry.path))
    : singleFile ? [dir] : collectSyncableFiles(dir, {
    strategy, includeGitignored,
    includeHidden: opts.includeHidden, metafilePages: await readMetafilePagesMode(engine),
    onExcluded: (rel) => { malformedExcluded.push(rel); },
  });
  console.error(
    `[gbrain phase] import.collect_files done ${Date.now() - _walkT0}ms files=${allFiles.length}`,
  );
  if (malformedExcluded.length > 0) {
    console.error(
      `[gbrain import] ${malformedExcluded.length} file(s) skipped: malformed filename ` +
      `(brackets/control chars; rename to import): ` +
      malformedExcluded.slice(0, 20).map(sanitizePathForDisplay).join(', ') +
      (malformedExcluded.length > 20 ? `, … (+${malformedExcluded.length - 20} more)` : ''),
    );
  }
  const fileTypeLabel = strategy === 'code' ? 'code'
    : strategy === 'auto' ? 'syncable' : 'markdown';
  // #753/#774: apply --exclude glob patterns (threaded by performFullSync).
  if (!company && opts.exclude && opts.exclude.length > 0) {
    const beforeExclude = allFiles.length;
    allFiles = allFiles.filter(abs => !matchesAnyGlob(relative(dir, abs), opts.exclude));
    info(
      `Found ${allFiles.length} ${fileTypeLabel} files ` +
      `(${beforeExclude - allFiles.length} excluded by --exclude patterns)`,
    );
    // NAV-4: everything excluded is almost always a mistyped pattern — warn.
    if (beforeExclude > 0 && allFiles.length === 0) {
      console.warn(
        `[gbrain sync] No files matched after applying ${opts.exclude.length} --exclude pattern(s). ` +
        `Check your --exclude flags. Patterns: ${JSON.stringify(opts.exclude)}`,
      );
    }
  } else {
    info(`Found ${allFiles.length} ${fileTypeLabel} files`);
  }

  // Sort newest-first so date-prefixed brain paths get embedded before older ones.
  // See src/core/sort-newest-first.ts for the policy.
  sortNewestFirst(allFiles);

  const checkpointPath = gbrainPath('import-checkpoint.json');
  const completed = new Set<string>();
  if (company) {
    await company.protect([{ op: 'company-brain-content', fingerprint: company.receiptId, kind: 'content' }]);
    const [row] = await engine.executeRaw<{ completed_keys: string[] }>("SELECT completed_keys FROM op_checkpoints WHERE op='company-brain-content' AND fingerprint=$1", [company.receiptId]);
    for (const path of row?.completed_keys ?? []) completed.add(path);
  } else if (!fresh && !managedImport) {
    const cp = loadCheckpoint(checkpointPath, dir);
    if (cp) {
      info(`Resuming from checkpoint: re-checking current files via content_hash (${cp.completedPaths.length} previously completed)`);
    }
  }
  const files = company ? resumeFilter(allFiles, dir, completed) : allFiles;

  // Determine actual worker count. Import owns the same per-worker Postgres
  // pools as sync, so it must honor the shared opt-in connection budget too
  // (GBRAIN_MAX_CONNECTIONS, same clamp sync.ts applies before its fan-out).
  // Resolve this before choosing the parallel branch: a budget that cannot
  // fit even one child worker falls through to the provided parent engine.
  let actualWorkers = workerCount > 1 ? workerCount : 1;
  if (actualWorkers > 1 && engine.kind !== 'pglite') {
    const maxConnections = resolveMaxConnections();
    if (maxConnections !== undefined) {
      const { resolvePoolSize } = await import('../core/db.ts');
      const parentPool = resolvePoolSize();
      const perWorkerPool = Math.min(2, resolvePoolSize(2));
      const clampResult = clampWorkersForConnectionBudget(actualWorkers, {
        maxConnections,
        parentPool,
        perWorkerPool,
      });
      if (clampResult.clamped) {
        const budgetDetail = clampResult.workers === 1
          ? `(serial parent engine; parent pool ${parentPool}).`
          : `(parent ${parentPool} + ${clampResult.workers}x${perWorkerPool} per-worker).`;
        console.error(
          `  [import] GBRAIN_MAX_CONNECTIONS=${maxConnections}: clamped workers ` +
          `${actualWorkers} -> ${clampResult.workers} ${budgetDetail}`,
        );
      }
      actualWorkers = clampResult.workers;
    }
  }
  if (actualWorkers > 1) {
    info(`Using ${actualWorkers} parallel workers`);
  }

  let imported = 0;
  let skipped = 0;
  let errors = 0;
  // Per-file malformed skips (defense-in-depth hits inside importFromFile);
  // the walker-level exclusions are counted separately via malformedExcluded.
  let malformedFileSkips = 0;
  let processed = 0;
  // Time-based checkpoint floor (see the save site below). Chunking cost scales
  // with paragraph count, not bytes, so a single reference-style file can take
  // many minutes; a count-only trigger leaves that work undurable.
  const CHECKPOINT_MAX_INTERVAL_MS = 120_000;
  let lastCheckpointMs = Date.now();
  let lastCheckpointSize = completed.size;
  let chunksCreated = 0;
  const resealed = { pages: 0, pendingChunks: 0, pendingChars: 0 };
  const importedSlugs: string[] = [];
  const errorCounts: Record<string, number> = {};
  const errorSamples: Record<string, string> = {};
  const failures: Array<{ path: string; error: string }> = []; // Bug 9
  // Alias-footgun visibility: aggregate per-file type_warning results once
  // per distinct type per run (same surface `gbrain sync` carries).
  const typeWarningCounts = new Map<string, import('../core/schema-pack/type-usage.ts').TypeWarningCount>(), fenceTally = importFenceTally(sourceId ?? 'default');
  const noteTypeWarning = (w: { kind: 'alias_of' | 'undeclared'; type: string; canonical?: string; directory?: string } | undefined): void => {
    if (!w) return;
    const key = `${w.kind}\t${w.type}`;
    const cur = typeWarningCounts.get(key);
    if (cur) cur.count++;
    else typeWarningCounts.set(key, { ...w, count: 1 });
  };
  // #3839: paths that succeeded (imported OR unchanged) this run, keyed the
  // same way as `failures` above (importRelPath) so a path that failed on a
  // prior run and now succeeds clears its ledger row instead of staying
  // `open` forever.
  const succeededPaths: string[] = [];
  const startTime = Date.now();

  // Progress on stderr so stdout stays clean for the final summary / --json payload.
  const progress = createProgress(cliOptsToProgressOptions(getCliOptions()));
  progress.start('import.files', files.length);

  function tickProgress() {
    progress.tick(1, `imported=${imported} skipped=${skipped} errors=${errors}`);
  }

  // A12 (opt-in): git first-commit dates anchor undated new pages instead of clone-time mtimes.
  const firstCommits = !singleFile && await engine.getConfig('sync.git_first_commit_dates').catch(() => null) === 'true'
    ? gitFirstCommitDates(dir) : null;

  // F4b: PGLite has no autovacuum; refresh stale planner statistics every N files so the import
  // never plans against the empty tables it started with (O-CEO-17).
  const analyzeEvery = await importAnalyzeEveryPages(engine);

  async function processFile(eng: BrainEngine, filePath: string, settled?: PromiseSettledResult<ImportResult>) {
    if (!settled && signal?.aborted) return;
    const relativePath = singleFile ? basename(filePath) : relative(dir, filePath);
    // #753/#774: slug + source_path base. When performFullSync syncs a
    // monorepo subdir, slugRoot is the git root so slugs stay git-root-
    // relative (matching the incremental path's git-diff paths). The
    // checkpoint (`completed`) stays dir-relative.
    const importRelPath = opts.slugRoot ? relative(opts.slugRoot, filePath) : relative(importRoot, filePath);
    if (opts.heldPaths?.has(importRelPath)) { skipped++; completed.add(relativePath); processed++; tickProgress(); return; }
    // v0.31.2 (D5): per-file slow-path log. Fires only when a single
    // file takes >5s. The user's hang surfaces as one file taking
    // forever — without this, the agent can't see which file.
    const _fileT0 = Date.now();
    try {
      // v0.27.1 (F2): dispatch image extensions to importImageFile when
      // multimodal is enabled. The walker (collectMarkdownFiles) only picks
      // up images when GBRAIN_EMBEDDING_MULTIMODAL=true so this branch is
      // unreachable when the gate is off; defense-in-depth check anyway.
      if (settled?.status === 'rejected') throw settled.reason;
      const result = settled ? settled.value : company ? await importCompanyBrainFile(eng, filePath, sourceId!) : managedImport
        ? await importManagedFile(eng, filePath, importRelPath, { noEmbed, sourceId, activePack: importActivePack, signal, slugRoot: opts.slugRoot })
        : isImageFilePath(relativePath) && process.env.GBRAIN_EMBEDDING_MULTIMODAL === 'true'
        ? await importImageFile(eng, filePath, importRelPath, { noEmbed, sourceId })
        : await importFile(eng, filePath, importRelPath, { noEmbed, sourceId, activePack: importActivePack, bodyPolicy, firstCommitAt: firstCommits?.get(filePath), history: opts.history?.(filePath) });
      // An import that landed while cancellation arrived is still complete.
      // Account for it before stopping, so resume never loses a successful path.
      noteTypeWarning((result as { type_warning?: Parameters<typeof noteTypeWarning>[0] }).type_warning); fenceTally.note(importRelPath, result);
      const _fileMs = Date.now() - _fileT0;
      if (!settled && _fileMs > 5000) {
        console.error(`[gbrain phase] import.process_file slow ${_fileMs}ms ${relativePath}`);
      }
      if (await reportFileResult(opts.onFileResult, importRelPath, filePath, result) === 'held') {
        skipped++;
        completed.add(relativePath);
      } else if (result.status === 'imported') {
        imported++;
        chunksCreated += result.chunks;
        importedSlugs.push(result.slug);
        // v0.33.2: path-based checkpoint — record only on success.
        completed.add(relativePath);
        succeededPaths.push(importRelPath); // #3839
      } else {
        skipped++;
        if ('resealed' in result && result.resealed) {
          resealed.pages++;
          resealed.pendingChunks += result.resealed.pendingChunks;
          resealed.pendingChars += result.resealed.pendingChars;
        }
        if (result.skip_reason === 'malformed_path') {
          // Informational skip (bracket/control-char filename): never a
          // failure-ledger row, and stable across runs — checkpoint as done.
          console.error(`  Skipped (malformed filename — rename to import): ${sanitizePathForDisplay(relativePath)}`);
          malformedFileSkips++;
          completed.add(relativePath);
        } else if (result.error && result.error !== 'unchanged') {
          errors++;
          console.error(`  Skipped ${relativePath}: ${result.error}`);
          // Bug 9 — non-"unchanged" skips carry a real error reason.
          // #774: ledger paths use the slug base so an incremental sync's
          // success at the same (git-root-relative) path clears the row.
          failures.push({ path: importRelPath, error: result.error });
        } else {
          // 'unchanged' or no-error skip: content_hash matched a prior
          // successful import, so this file IS done for checkpoint purposes.
          completed.add(relativePath);
          succeededPaths.push(importRelPath); // #3839
        }
      }
    } catch (e: unknown) {
      if (signal?.aborted) {
        // Do not turn an unrelated infrastructure failure into a timeout.
        if (e !== signal.reason && !(e instanceof Error && e.name === 'AbortError')) throw e;
        return;
      }
      // #5600: an accepted managed import still publishing is not a failure; the next run resumes its request.
      if (acceptedPendingReceipt(e)) { skipped++; console.error(`  Pending: ${relativePath} was accepted and is still publishing; rerun to confirm it.`); }
      else if (await reportFileResult(opts.onFileResult, importRelPath, filePath, { status: 'error', error: e instanceof Error ? e.message : String(e) }) === 'held') { skipped++; completed.add(relativePath); } else {
        const msg = e instanceof Error ? e.message : String(e);
        const { count, sample } = recordImportFailure(errorCounts, errorSamples, msg);
        if (count <= 5) {
          console.error(`  Warning: skipped ${relativePath}: ${msg}`);
        } else if (count === 6) {
          console.error(`  (suppressing further "${sample.slice(0, 60)}..." errors)`);
        }
        errors++;
        skipped++;
        failures.push({ path: importRelPath, error: msg });
      }
    }
    processed++;
    tickProgress();
    if (analyzeEvery > 0 && processed % analyzeEvery === 0) {
      await maybeRefreshPlannerStats(engine, 'import', { throttle: false }).catch((e: unknown) =>
        console.error(`  Warning: planner statistics refresh failed (${e instanceof Error ? e.message : String(e)}); the import continues. Afterwards run: ${PLANNER_STATS_REPAIR_COMMAND}`));
    }
    if (company) {
      await engine.executeRaw("INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES('company-brain-content',$1,$2::text::jsonb) ON CONFLICT(op,fingerprint) DO UPDATE SET completed_keys=EXCLUDED.completed_keys,updated_at=now()",
        [company.receiptId, JSON.stringify([...completed])]);
      return;
    }
    // Save checkpoint every 100 SUCCESSFUL adds (not every 100 processed).
    // Failed files never enter `completed`, so a flaky file can't push the
    // checkpoint past it — the next run will retry it.
    // ...and ALSO save on a time interval. On a corpus with an expensive tail
    // `completed` can advance ~1 file per several minutes, so the next
    // 100-boundary may be hours away; any kill before it discards every file
    // since the last boundary and the run can never converge.
    const nowMs = Date.now();
    const dueByCount = completed.size > 0 && completed.size % 100 === 0;
    const dueByTime = completed.size > lastCheckpointSize
      && nowMs - lastCheckpointMs >= CHECKPOINT_MAX_INTERVAL_MS;
    if (dueByCount || dueByTime) {
      lastCheckpointMs = nowMs;
      lastCheckpointSize = completed.size;
      const cpDir = gbrainPath();
      if (!existsSync(cpDir)) {
        try { const { mkdirSync } = await import('fs'); mkdirSync(cpDir, { recursive: true }); }
        catch { /* non-fatal */ }
      }
      saveCheckpoint(checkpointPath, {
        schema_version: 1,
        owner: 'gbrain',
        kind: 'import',
        dir,
        completedPaths: Array.from(completed),
        timestamp: new Date().toISOString(),
      });
    }
  }

  async function processBatch(eng: BrainEngine, batch: string[]) {
    const settled = batch.length > 1 && !signal?.aborted ? await settleManagedImportBatch(eng, batch, file => opts.slugRoot ? relative(opts.slugRoot, file)
      : relative(importRoot, file), rel => !!opts.heldPaths?.has(rel), { noEmbed, sourceId, activePack: importActivePack, signal, slugRoot: opts.slugRoot }) : undefined;
    for (const [i, file] of batch.entries()) await processFile(eng, file, settled?.[i]);
  }
  let workerError: unknown;
  let workerFailed = false;
  try {
    if (actualWorkers > 1) {
      // v0.22.13 (PR #490 A1 + Q3): use engine.kind discriminator (not config.engine
      // string sniff) and fall back to serial when database_url is unset. Both
      // checks belt-and-suspenders so we never crash on a null assertion.
      const config = loadConfig();
      if (engine.kind === 'pglite' || !config?.database_url) {
        for (let i = 0, batch: string[]; i < files.length && !signal?.aborted; i += batch.length) await processBatch(engine, batch = nextImportBatch(files, i, managedImport && !company));
      } else {
        const { PostgresEngine } = await import('../core/postgres-engine.ts');
        const { connectWithRetry, resolvePoolSize } = await import('../core/db.ts');
        // Each child keeps the established two-connection pool. GBRAIN_POOL_SIZE
        // controls the parent pool; GBRAIN_MAX_CONNECTIONS clamps the child
        // count above so the combined footprint stays within the operator's cap.
        const workerPoolSize = Math.min(2, resolvePoolSize(2));
        const databaseUrl = config.database_url;

        // v0.22.13 (PR #490 A2): connect workers serially so a partial failure
        // leaves us with the connected ones already pushed onto workerEngines
        // for the finally-block cleanup. The prior Promise.all could leak any
        // engine that connected before another's connect() rejected.
        const workerEngines: InstanceType<typeof PostgresEngine>[] = [];
        try {
          for (let i = 0; i < actualWorkers; i++) {
            if (signal?.aborted) break;
            const eng = new PostgresEngine();
            await connectWithRetry(eng, { database_url: databaseUrl, poolSize: workerPoolSize }, { retryConnectTimeout: true });
            workerEngines.push(eng);
          }

          // Thread-safe queue: atomic index counter (JS is single-threaded; the
          // read-then-increment happens between awaits so no lock is needed).
          let queueIndex = 0;
          let stopWorkers = false;
          const outcomes = await Promise.allSettled(workerEngines.map(async (eng) => {
            try {
              while (!stopWorkers && !signal?.aborted) {
                if (queueIndex >= files.length) break;
                const batch = nextImportBatch(files, queueIndex, managedImport && !company); queueIndex += batch.length;
                await processBatch(eng, batch);
              }
            } catch (error) {
              stopWorkers = true;
              throw error;
            }
          }));
          // Drain every in-flight file before disconnecting pools or releasing
          // the source lock, even when one worker fails or cancellation arrives.
          const failed = outcomes.find(outcome => outcome.status === 'rejected');
          if (failed?.status === 'rejected') throw failed.reason;
        } finally {
          // v0.22.13 (PR #490 A2): try/finally guarantees cleanup even when the
          // worker loop throws. Each disconnect is best-effort — one failing
          // disconnect must not strand the others.
          await Promise.all(
            workerEngines.map(e =>
              e.disconnect().catch((err: unknown) =>
                console.error(`  worker disconnect failed: ${err instanceof Error ? err.message : String(err)}`),
              ),
            ),
          );
        }
      } // end else (postgres parallel)
    } else {
      // Sequential: use the provided engine
      for (let i = 0, batch: string[]; i < files.length && !signal?.aborted; i += batch.length) await processBatch(engine, batch = nextImportBatch(files, i, managedImport && !company));
    }
  } catch (error) {
    workerFailed = true;
    workerError = error;
  } finally {
    progress.finish();
  }

  // Error summary
  for (const [key, count] of Object.entries(errorCounts)) {
    if (count > 5) {
      console.error(`  ${count} files failed: ${errorSamples[key].slice(0, 100)}`);
    }
  }

  // Save the successful tail on interruption/failure. Keep this synchronous:
  // checkpoint and cancellation decisions must not race another worker.
  function preserveCompletedPaths(): void {
    if (company) return;
    if (completed.size <= lastCheckpointSize) return;
    try {
      mkdirSync(gbrainPath(), { recursive: true });
      saveCheckpoint(checkpointPath, {
        schema_version: 1, owner: 'gbrain', kind: 'import', dir,
        completedPaths: Array.from(completed), timestamp: new Date().toISOString(),
      });
      lastCheckpointSize = completed.size;
    } catch { /* non-fatal: resume can safely recheck content hashes */ }
  }
  function throwIfInterrupted(): void {
    if (!signal?.aborted) return;
    preserveCompletedPaths();
    console.error(`Import interrupted: ${imported} pages imported; completed paths preserved for resume.`);
    throw new ImportAbortError('interrupted', 1, { imported, skipped, errors, chunksCreated, failures });
  }
  if (errors > 0 || workerFailed) preserveCompletedPaths();
  if (workerFailed) throw workerError;
  throwIfInterrupted();

  // v0.39 T7 — end-of-run schema mismatch warn. Fires ONCE per import,
  // not per page. Counts untyped pages in the affected source AND
  // compares to import size; warns at >=10% untyped. The doctor
  // schema_pack_consistency check (also T7) gives the persistent surface.
  // Best-effort: query failure is non-fatal.
  if (imported > 0) {
    try {
      const sid = sourceId ?? 'default';
      const rows = await engine.executeRaw<{ total: string | number; untyped: string | number }>(
        `SELECT
           COUNT(*)::text AS total,
           COUNT(*) FILTER (WHERE type IS NULL OR type = '')::text AS untyped
         FROM pages
         WHERE source_id = $1 AND deleted_at IS NULL`,
        [sid],
      );
      const total = Number(rows[0]?.total ?? 0);
      const untyped = Number(rows[0]?.untyped ?? 0);
      if (total > 0 && untyped / total >= 0.1) {
        const pct = ((untyped / total) * 100).toFixed(1);
        console.error(
          `\n[schema] ${untyped} of ${total} pages (${pct}%) in source \`${sid}\` ` +
          `have no \`type\` matching the active schema pack. Run \`gbrain schema detect\` ` +
          `to propose a pack matching your content shape, or \`gbrain doctor --json\` ` +
          `for the persistent surface (schema_pack_consistency check).`,
        );
      }
    } catch {
      // best-effort
    }
  }

  // Alias/undeclared explicit-type warnings (schema.type_warnings, default on).
  let typeWarningsEnabled = true;
  if (typeWarningCounts.size > 0) {
    try {
      const v = await engine.getConfig('schema.type_warnings');
      typeWarningsEnabled = !(v === 'false' || v === '0' || v === 'off');
    } catch { /* config unavailable → default on */ }
    if (typeWarningsEnabled) {
      const { renderTypeWarningSummary } = await import('../core/schema-pack/type-usage.ts');
      for (const line of renderTypeWarningSummary([...typeWarningCounts.values()])) {
        console.error(`  ${line}`);
      }
      console.error(`  (silence with: gbrain config set schema.type_warnings false)`);
    }
  }

  // Log the ingest. #3969: skip the row when the run changed nothing
  // (imported=0, errors=0, chunks=0) unless --log-noop — see shouldLogIngest.
  // `sourceId ?? 'default'` mirrors the fallback `processFile` itself uses
  // when calling importFile/importImageFile — this must report the source
  // the pages actually landed in, not the unresolved CLI arg (see #3838:
  // pre-fix this field always read 'default' regardless of where
  // resolveSourceWithTier actually routed the run).
  if (shouldLogIngest({ imported, errors, chunksCreated }, logNoop)) {
    await engine.logIngest({
      source_type: 'directory',
      source_ref: dir,
      source_id: sourceId ?? 'default',
      pages_updated: importedSlugs,
      summary: `Imported ${imported} pages, ${skipped} skipped, ${chunksCreated} chunks`,
    });
  }

  throwIfInterrupted();

  // Import → sync continuity: write sync checkpoint if this is a git repo.
  // Bug 9 — gate last_commit on "no failures" so import doesn't silently
  // stomp on the sync bookmark when parsing broke. last_run + repo_path are
  // written alongside it, but ONLY when this import owns the globals (#2114
  // guard below) — a foreign directory must not repoint the brain repo.
  let gitHead: string | null = null;
  try {
    if (existsSync(join(dir, '.git'))) {
      gitHead = execFileSync('git', ['-C', dir, 'rev-parse', 'HEAD'], { encoding: 'utf-8' }).trim();
    }
  } catch {
    // Not a git repo or git not available
  }

  // issue #1939: when performFullSync drives runImport it owns the failure
  // ledger + bookmark via the shared gate (applySyncFailureGate). Skipping the
  // internal handling here prevents double-recording (which would double-count
  // the auto-skip `attempts` streak) and a competing bookmark write.
  if (gitHead && !opts.managedBookmark && !managedImport) {
    // Record failures into the central JSONL so doctor can surface them.
    // Use gitHead as the commit so a later sync can tell "same broken
    // state as last time" from "new broken state." Source-scoped (#1939 #2).
    if (failures.length > 0) {
      const { recordFailures } = await import('../core/sync.ts');
      // #3838: `opts.sourceId` is the caller-supplied value, which stays
      // undefined for a bare CLI invocation unless the resolver's
      // sole_non_default tier explicitly adopted it (see the comment above
      // this function's sourceId resolution). Use the resolved `sourceId`
      // — the same value every importFile/importImageFile call in this run
      // actually wrote to — so the ledger is keyed by the true source.
      recordFailures(sourceId ?? 'default', failures, gitHead);
    }

    // #3839: a path that failed on a prior run and succeeded (imported or
    // unchanged) this run must clear its ledger row — pre-fix, clearFailures
    // existed but had no caller anywhere, so `open` rows never healed short
    // of a manual `gbrain sync --skip-failed`. Runs on every non-empty
    // success list regardless of whether this SAME run also had failures,
    // so a stale row from an earlier run gets cleared even if today's run
    // is only partially clean.
    if (succeededPaths.length > 0) {
      const { clearFailures } = await import('../core/sync.ts');
      // #3838: keyed by the resolved source, matching recordFailures above —
      // a row recorded under the resolved source must clear under it too.
      clearFailures(sourceId ?? 'default', succeededPaths);
    }

    // #2114 guard: the global sync.* keys describe THE brain repo (the
    // default source's working tree). Pre-fix this block rewrote them on
    // every git-repo import, silently repointing put_page write-through
    // and poisoning the incremental sync anchor. Ownership + the bootstrap
    // rule live in ownsGlobalSyncAnchor (shared with writeSyncAnchor's
    // legacy branch in sync.ts, so the two layers cannot drift).
    const { ownsGlobalSyncAnchor } = await import('../core/sync.ts');
    const { owns, configured } = await ownsGlobalSyncAnchor(engine, sourceId, dir);
    throwIfInterrupted();

    if (owns) {
      if (failures.length === 0) {
        await engine.setConfig('sync.last_commit', gitHead);
      } else {
        console.error(
          `\nImport completed with ${failures.length} failure(s). ` +
          `sync.last_commit NOT advanced — re-run 'gbrain sync' to retry, or ` +
          `'gbrain sync --skip-failed' to acknowledge and move past them.`,
        );
      }
      await engine.setConfig('sync.last_run', new Date().toISOString());
      await engine.setConfig('sync.repo_path', dir);
    } else if ((sourceId ?? 'default') === 'default') {
      console.error(
        `\n[import] sync.repo_path stays at ${configured ?? '(unset)'} — NOT repointing to "${dir}". ` +
        `Sync bookmarks were not advanced. If this directory IS your brain repo, run: ` +
        `gbrain config set sync.repo_path "${dir}"`,
      );
    }
    // Non-default sources: deliberately silent no-op — the globals are not
    // this import's to move (its sync anchors live on the `sources` row).
  }

  // #1691: a named source registered with `local_path` but fed only via
  // `gbrain import` (never `gbrain sync`) never got `sources.last_sync_at`
  // touched, so doctor's `sync_freshness` read it as permanently
  // "never synced". Stamp it on a clean run only (mirrors the bookmark
  // gate above). `!opts.managedBookmark` excludes performFullSync's call —
  // that path stamps its own, more-authoritative `last_sync_at` via
  // writeSyncAnchor AFTER its full gate (applySyncFailureGate) decides the
  // sync actually advanced; stamping here too would race ahead of that
  // decision. remote_url sources are excluded too: autopilot's freshness
  // dispatcher (autopilot.ts) reads last_sync_at to decide when to queue a
  // real `git pull` for those, and a plain import never pulls. A git-tracked
  // local_path is excluded too (scoped to #1691's actual "non-git local
  // source" case): `gbrain import` never advances the source's own
  // `last_commit`, so stamping last_sync_at for a git checkout would mask
  // real commit-level staleness that `gbrain sync` (not `import`) is the
  // correct pipeline to detect. Detection reuses sync's own
  // `discoverGitRoot` (rev-parse --show-toplevel, walks UP) rather than a
  // bare `.git`-at-local_path probe, so a source anchored at a SUBDIR of a
  // git checkout (the #753/#774 monorepo shape) is excluded too — that is
  // exactly the shape sync's git-root slug anchoring exists for.
  // Malformed-filename exclusions/skips (tallied into `totalMalformed`
  // below, NOT into `failures`) count toward the clean-run gate too — a run
  // that silently dropped files isn't "clean" for freshness purposes even
  // with zero recorded failures.
  const totalMalformed = malformedExcluded.length + malformedFileSkips;
  if (sourceId && failures.length === 0 && totalMalformed === 0 && !opts.managedBookmark && !managedImport) {
    try {
      const [row] = await engine.executeRaw<{ local_path: string | null; config: unknown }>(
        `SELECT local_path, config FROM sources WHERE id = $1`,
        [sourceId],
      );
      const { sourceConfigHasRemoteUrl, parseSourceConfig } = await import('../core/sources-load.ts');
      // Connector-managed sources (config.kind: github/google, v0.47 API-backed
      // shapes) own their last_sync_at via the connector's sync path — a google
      // source has a non-git local_path and no remote_url, so without this
      // check a stray `import --source-id` would mask connector staleness
      // (and flip `gbrain waiting`'s google-freshness gate). parseSourceConfig,
      // not a bare JSON.parse: nested-string / historical-array configs are
      // real shapes (#2829) and must not slip past the kind check.
      const cfg = parseSourceConfig(row?.config);
      const isConnectorManaged = typeof cfg.kind === 'string' && cfg.kind.length > 0;
      // Freshness is a claim about the WHOLE registered root. Configured-root
      // enforcement is default-off, so an import of an unrelated directory —
      // or of a mere subdirectory of the root — can complete cleanly with
      // --source-id; neither says anything about the rest of the root, so
      // only an import whose canonical target IS the registered local_path
      // may stamp. `dir` is already the canonical realpath (#1728).
      let coversRegisteredRoot = false;
      if (row?.local_path && isAbsolute(row.local_path)) {
        try {
          const { realpathSync } = await import('fs');
          coversRegisteredRoot = realpathSync(row.local_path) === dir;
        } catch {
          coversRegisteredRoot = false;
        }
      }
      let isGitTracked = false;
      if (row?.local_path) {
        try {
          const { discoverGitRoot } = await import('../core/sync-git.ts');
          discoverGitRoot(row.local_path);
          isGitTracked = true;
        } catch {
          isGitTracked = false;
        }
      }
      if (row?.local_path && coversRegisteredRoot && !sourceConfigHasRemoteUrl(row.config) && !isGitTracked && !isConnectorManaged) {
        throwIfInterrupted();
        await engine.executeRaw(`UPDATE sources SET last_sync_at = now() WHERE id = $1`, [sourceId]);
      }
    } catch (error) {
      if (error instanceof ImportAbortError) throw error;
      // best-effort — a freshness nicety never fails the import (see above).
    }
  }

  throwIfInterrupted();
  // Only a fully completed run removes resume state, including async metadata.
  if (errors === 0 && !company) clearCheckpoint(checkpointPath);
  else if (existsSync(checkpointPath)) info(`  Checkpoint preserved (${errors} errors). Run again to retry failed files.`);

  const totalTime = ((Date.now() - startTime) / 1000).toFixed(1);
  const privacyLabelNotice = await ignoredPrivacyLabelRunNotice(engine, sourceId ?? 'default', { slugs: importedSlugs }, opts.noticeRun ?? 'import');
  const resealSummary = resealed.pages > 0
    ? { pages: resealed.pages, pending_chunks: resealed.pendingChunks, embedding_usd: resealEmbeddingUsd(resealed.pendingChars) }
    : null;
  if (jsonOutput) {
    // `skipped` includes every per-file failure importFile RETURNS (invalid
    // frontmatter, oversize, symlink, slug mismatch) as well as content-hash
    // no-ops. `errors` counts both returned failures and thrown failures.
    // The failure ledger is
    // written only for git-repo dirs (see the gitHead gate below), so a caller
    // importing a scratch directory has no other channel. Emit the per-file
    // list so state can be gated per file.
    await writeJsonDocument(JSON.stringify({
      status: errors > 0 ? 'partial' : 'success', duration_s: parseFloat(totalTime),
      imported, skipped, errors, chunks: chunksCreated,
      ...(resealSummary ? { resealed: resealSummary } : {}), ...fenceTally.fields(),
      total_files: allFiles.length,
      unchanged: skipped - failures.length - malformedFileSkips,
      malformed_skipped: malformedFileSkips,
      failures,
      // Effective destination — same expression as the import-file write (import-file.ts) and the ingest_log row below.
      source_id: sourceId ?? 'default',
      ...(privacyLabelNotice ? { notices: [renderNotice(privacyLabelNotice, cliRenderContext())] } : {}),
    }));
  } else {
    slog(`\nImport complete (${totalTime}s):`);
    slog(`  ${imported} pages imported`);
    slog(`  ${skipped} pages skipped (${skipped - failures.length - malformedFileSkips} unchanged, ${errors} errors, ${malformedFileSkips} malformed filenames)`);
    slog(`  ${chunksCreated} chunks created`); for (const line of fenceTally.lines()) slog(line);
    if (resealSummary) {
      slog(`  ${resealSummary.pages} unchanged page(s) re-sealed for remote search; ${resealSummary.pending_chunks} chunk(s) need embedding`
        + `${resealSummary.embedding_usd === null ? '' : ` (~$${resealSummary.embedding_usd.toFixed(4)})`}${noEmbed ? ' — run gbrain embed --stale' : ''}`);
    }
  }

  if (imported > 0 && !opts.managedBookmark) await refreshProjectionStatistics(engine, imported);
  if (imported > 0) recordFunnelEvent('import');
  return {
    imported, skipped, errors, chunksCreated, failures,
    ...(resealSummary ? { resealed: resealSummary } : {}), ...fenceTally.fields(),
    ...(totalMalformed > 0 ? { malformedSkipped: totalMalformed } : {}),
    ...(typeWarningCounts.size > 0 && typeWarningsEnabled
      ? { type_warnings: [...typeWarningCounts.values()] }
      : {}),
    ...(privacyLabelNotice ? { privacy_label_notice: privacyLabelNotice } : {}),
  };
}

/**
 * v0.31.2: max walker depth before bailing out. 32 levels is more than
 * any real source tree on disk; reaching it is a structural cycle the
 * lstat+inode-set defenses missed (e.g., a Linux bind-mount or btrfs
 * subvolume that returns a fresh inode for the same content). Override
 * via `GBRAIN_MAX_WALK_DEPTH`.
 */
function resolveMaxWalkDepth(): number {
  const raw = process.env.GBRAIN_MAX_WALK_DEPTH;
  if (raw) {
    const n = Number(raw);
    if (Number.isFinite(n) && n > 0) return n;
  }
  return 32;
}

interface CollectOpts {
  strategy?: SyncStrategy;
  includeGitignored?: boolean;
  /**
   * Invoked (with the repo-relative path) for each file dropped by the
   * malformed-filename gate, on BOTH collection routes. Without this,
   * directory imports and full syncs silently succeed while omitting the
   * file — no rename guidance, no skipped count (structured-review finding).
   */
  onExcluded?: (relPath: string) => void;
  /** See `RunImportOpts.includeHidden` — same repeatable-glob semantics. */
  includeHidden?: string[];
  metafilePages?: MetafilePagesMode; // GBRA-150: `sync.metafile_pages`, whether a typed nested metafile under `dir` is collected
}

/**
 * v0.27.1 + v0.31.2: walker-context image admission. `isSyncable` (the
 * incremental-diff filter at sync.ts:213) admits images only on `auto`.
 * The first-sync walker historically admitted them on markdown too when
 * `GBRAIN_EMBEDDING_MULTIMODAL=true`. Codex (C5) flagged the contradiction
 * — preserve the walker semantic explicitly.
 *
 * Closes #345: exclude `SYNC_SKIP_FILES` metafiles
 * (`README.md` / `index.md` / `log.md` / `schema.md` / `RESOLVER.md`) and, since
 * #5186, the root-level `AGENTS.md` / `CLAUDE.md` (`SYNC_ROOT_SKIP_FILES`).
 * Incremental `sync` skips these via `isSyncable`, but the bulk-import
 * walker only filtered by extension — so a directory import imported every
 * directory README as a page, titled by its folder ("People", "Companies",
 * …). Those index-titled pages then trigram-corrupt fuzzy entity resolution
 * (any `people/X` slug matches the "People" page) and inflate orphan count.
 * Funnel both admission paths through the same metafile exclusion so import
 * and sync agree on what is a page.
 */
function isCollectibleForWalker(
  path: string,
  strategy: SyncStrategy,
  multimodalOn: boolean,
  includeHidden?: string[],
  metafilePage?: (relPath: string) => boolean, relPath = path,
): boolean {
  // #2607: apply the SAME segment-level prune gate as incremental sync's
  // `classifySync` (core/sync.ts) — via the shared `isPathPruned`, so this
  // and `classifySync` cannot drift the way #923/#202 drifted before
  // `PRUNE_DIR_NAMES` existed. The FS walk below prunes at descent time,
  // but the git fast path enumerates via `git ls-files` and historically
  // filtered only by extension — so `sync --full` imported (and resurrected
  // previously-deleted) pages under dot-dirs / vendored trees that incremental
  // sync excludes. Full and incremental must agree on the exclusion set.
  // (In the FS-walk route `path` is a basename, so `includeHidden` has no
  // segment to waive there — that route's directory-level prune already ran
  // via unmodified `pruneDir` before a file entry is ever reached; see
  // `isPathPruned`'s doc comment for that scope note.)
  if (isPathPruned(path, includeHidden)) return false;

  // Malformed filenames (brackets / control chars — markdown-link syntax as a
  // literal filename) are rejected on BOTH collection routes, same as
  // incremental sync's classifySync. Full and incremental must agree.
  if (hasMalformedPathSegment(path)) return false;

  // Metafiles are directory scaffolding (READMEs / index / log / schema /
  // resolver, and the root AGENTS.md / CLAUDE.md harden writes), not typed
  // brain pages — same exclusion `sync`'s `isSyncable` applies. Guards both
  // the FS-walk and the git-fast-path collection routes. GBRA-150: a nested typed one is a page (dir-relative depth).
  if (isSyncMetafile(path) && !metafilePage?.(relPath)) return false;

  switch (strategy) {
    case 'code':
      return isCodeFilePath(path);
    case 'markdown':
      return isMarkdownFilePath(path) || (multimodalOn && isImageFilePathFromSync(path));
    case 'auto':
      return (
        isMarkdownFilePath(path) ||
        isCodeFilePath(path) ||
        (multimodalOn && isImageFilePathFromSync(path))
      );
  }
}

/** Whether the git work tree around `dir` ignores `dir` itself (`git check-ignore` exits 0). */
function gitIgnoresDir(dir: string): boolean {
  try {
    execFileSync('git', ['-C', dir, 'check-ignore', '-q', '.'], { stdio: 'ignore' });
    return true;
  } catch {
    return false;
  }
}

/**
 * Git-aware fast path for `collectSyncableFiles`. Returns the strategy-filtered
 * list of syncable files when `dir` is inside a git work tree (paths absolute,
 * sorted), or `null` when `dir` is not a git repo / git is unavailable — in
 * which case the caller falls back to the recursive FS walk.
 *
 * Honors `.gitignore` (the whole point): `git ls-files --cached --others
 * --exclude-standard` lists tracked + untracked-not-ignored files, so vendored
 * / build / generated trees never reach the importer. `-z` (NUL-delimited)
 * survives paths with spaces/newlines. Each path is lstat-checked to preserve
 * the walker's no-symlink policy and to drop submodule gitlinks (which surface
 * as a single non-regular entry).
 */
function gitListSyncableFiles(
  dir: string,
  strategy: SyncStrategy,
  multimodalOn: boolean,
  onExcluded?: (relPath: string) => void,
  includeHidden?: string[],
  metafilePage?: (relPath: string) => boolean,
): string[] | null {
  const stdout = gitLsFiles(dir, ['--cached', '--others', '--exclude-standard', '-z']);
  if (stdout === null) return null; // not a git work tree, or git not on PATH → FS-walk fallback
  // A directory the enclosing repository ignores (a scratch or cache folder inside a checkout) lists
  // nothing here, so an explicit import of it would succeed with zero files. Walk it directly instead.
  if (stdout === '' && gitIgnoresDir(dir)) return null;
  const files: string[] = [];
  for (const rel of stdout.split('\0')) {
    if (!rel) continue;
    // Malformed check FIRST (separately from the collectible gate) so the
    // exclusion is reportable — other filters (strategy, prune, metafile)
    // are silent by design; this one hides renameable content.
    if (hasMalformedPathSegment(rel)) { onExcluded?.(rel); continue; }
    if (!isCollectibleForWalker(rel, strategy, multimodalOn, includeHidden, metafilePage)) continue;
    const full = join(dir, rel);
    let st;
    try {
      st = lstatSync(full);
    } catch {
      continue; // ls-files raced a deletion, or unreadable
    }
    if (st.isSymbolicLink() || !st.isFile()) continue;
    files.push(full);
  }
  return files.sort();
}

/**
 * v0.31.2 (codex C4 + C5 + C8): unified walker with five hardenings:
 *
 * 1. `lstatSync` + explicit `isSymbolicLink()` skip — never follow symlinks.
 *    Replaces the old `collectMarkdownFiles` lstat path AND the old
 *    `walkSyncableFiles` `statSync` path (the latter was the cost-preview
 *    walker, weaker than the import walker for no good reason).
 * 2. Inode-set cycle detection keyed on `${st_dev}:${st_ino}` — defense in
 *    depth for non-symlink cycles (bind mounts, ZFS snapshots).
 * 3. `MAX_WALK_DEPTH` bailout — last-line backstop if both layers above miss.
 * 4. Strategy-aware filter via `isCollectibleForWalker` — single helper that
 *    surfaces the markdown+multimodal carve-out at one site instead of
 *    leaking it across two filter paths.
 * 5. `.sort()` output — `runImport`'s checkpoint-resume at line 68–74 is
 *    index-based against a sorted list. Unstable order skips the wrong
 *    files on resume.
 */
export function collectSyncableFiles(dir: string, opts: CollectOpts = {}): string[] {
  const strategy: SyncStrategy = opts.strategy ?? 'markdown';
  const multimodalOn = process.env.GBRAIN_EMBEDDING_MULTIMODAL === 'true';
  const metafilePage = metafilePagePredicate(opts.metafilePages ?? DEFAULT_METAFILE_PAGES_MODE, diskMetafileHeads(dir));

  // v0.42.x (#1159 --respect-gitignore / #1483 .gbrainignore): when `dir` is a
  // git work tree, enumerate via `git ls-files` so the walk honors
  // `.gitignore`. Pre-fix the recursive FS walk below descended into every
  // git-ignored tree — `vendor/` (PHP Composer), `storage/`, `public/build/`,
  // etc. — so a Laravel/PHP repo's `--strategy code` sync tried to import ~50k
  // dependency/build files (and bloated DB + embedding cost on any repo with
  // vendored data/fixtures). `--cached --others --exclude-standard` = tracked
  // PLUS untracked-not-ignored, so uncommitted source is still indexed. Non-git
  // dirs (or git unavailable) fall through to the FS walk below.
  if (!opts.includeGitignored) {
    const gitFiles = gitListSyncableFiles(dir, strategy, multimodalOn, opts.onExcluded, opts.includeHidden, metafilePage);
    if (gitFiles) return gitFiles;
  }

  const maxDepth = resolveMaxWalkDepth();
  const visitedInodes = new Map<string, true>();
  const files: string[] = [];

  function walk(d: string, depth: number): void {
    if (depth >= maxDepth) {
      console.warn(`[gbrain] walker depth limit reached at ${d}; skipping`);
      return;
    }
    let entries: string[];
    try {
      entries = readdirSync(d);
    } catch {
      return;
    }
    for (const entry of entries) {
      // Descent-time prune through the canonical gate (single source of truth
      // in core/sync.ts) instead of a hand-maintained inline list that drifted
      // from it. Skips hidden dirs (`.git`, `.raw`, etc.), `node_modules`,
      // `vendor`, `dist`, `build`, `venv` (#2020), `ops`, and git submodules.
      if (!pruneDir(entry, d)) continue;
      // Control-char SEGMENT check at descent time (never legitimate). The
      // bracket check moved to the per-file RELATIVE-path test below: a
      // bracket-named DIRECTORY must still be descended for code strategies
      // (`app/[id]/page.tsx` is ubiquitous framework layout), while markdown
      // files under it are excluded per-file — mirroring classifySync so full
      // and incremental sync agree (cross-model adversarial finding).
      // eslint-disable-next-line no-control-regex
      if (/[\x00-\x1f]/.test(entry)) continue;

      const full = join(d, entry);
      let stat;
      try {
        stat = lstatSync(full);
      } catch {
        console.warn(`[gbrain import] Skipping unreadable path: ${full}`);
        continue;
      }

      if (stat.isSymbolicLink()) {
        console.warn(`[gbrain import] Skipping symlink: ${full}`);
        continue;
      }

      if (stat.isDirectory()) {
        const inodeKey = `${stat.dev}:${stat.ino}`;
        if (visitedInodes.has(inodeKey)) {
          console.warn(`[gbrain] walker cycle detected at ${full}; skipping`);
          continue;
        }
        visitedInodes.set(inodeKey, true);
        walk(full, depth + 1);
      } else if (stat.isFile()) {
        // Malformed check on the RELATIVE path (this route's
        // isCollectibleForWalker only sees the basename, which can't catch a
        // bracket directory segment above a clean-named markdown file).
        const rel = relative(dir, full);
        if (hasMalformedPathSegment(rel)) { opts.onExcluded?.(rel); continue; }
        if (!isCollectibleForWalker(entry, strategy, multimodalOn, undefined, metafilePage, rel.split(sep).join('/'))) continue;
        files.push(full);
      }
    }
  }

  walk(dir, 0);
  return files.sort();
}

/**
 * @deprecated v0.31.2: kept as a thin wrapper so legacy callers keep
 * compiling. Prefer `collectSyncableFiles(dir, { strategy: 'markdown' })`.
 */
export function collectMarkdownFiles(dir: string): string[] {
  return collectSyncableFiles(dir, { strategy: 'markdown' });
}