Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
34.6 KB
Raw Blame
/**
 * Git plumbing for `gbrain sync`: invocation building, repo discovery,
 * baseline-commit self-heal, and path-containment guards. Peeled out of
 * src/commands/sync.ts (containment sprint C13-C14) as a pure move.
 */
import { lstatSync, realpathSync } from 'fs';
import { execFileSync } from './spawn.ts';
import { execFileBounded } from './bounded-child-exec.ts';
import { basename, dirname, isAbsolute, join, relative, sep } from 'path';
import type { BrainEngine } from './engine.ts';
import { resolveSlugForPath, DEFAULT_SOURCE_ID } from './sync.ts';
import { DELETE_BATCH_SIZE } from './engine-constants.ts';
import { invalidateGitListingCache, knownOutsideGitRepo, noteGitFailure } from './git-visible-files.ts';
import { hasUnresolvedDbOnlyDeclaration, loadStorageConfig } from './storage-config.ts';
import { GIT_READ_ENV, gitChildEnv } from './git-env.ts';
import { recordCommit, recordIntent } from './git/commit-ledger.ts';

/**
 * v0.32.7 CJK wave (codex post-merge F4): resolve a slug by `pages.source_path`
 * first, falling back to `resolveSlugForPath(path)`.
 *
 * Frontmatter-fallback pages (emoji-only / Thai / Arabic / exotic-script
 * filenames where `slugifyPath` returns empty and the slug came from the
 * frontmatter) have a slug that ISN'T derivable from the path. Delete and
 * rename operations that only know the path would otherwise orphan these
 * pages by trying to delete the path-derived (wrong) slug.
 *
 * Returns the actual stored slug when source_path matches a row, or the
 * path-derived slug when there's no match (normal-case path-derived pages).
 */
export async function resolveSlugByPathOrSourcePath(
  engine: BrainEngine,
  path: string,
  sourceId?: string,
): Promise<string> {
  // v0.41.19.0 (D8): the batch resolveSlugsByPaths is the one SQL owner and
  // fallback semantic (#6948: the canonical page of the path, never an
  // arbitrary twin). #3583 gate14: without a sourceId it is scoped to
  // 'default', matching every WRITE the bare no-sourceId path performs
  // (updateSlug, deletePage, the rename bookkeeping repair), so resolve and
  // mutate agree on the scope.
  try {
    const slug = (await engine.resolveSlugsByPaths([path], { sourceId: sourceId ?? DEFAULT_SOURCE_ID })).get(path);
    if (slug) return slug;
  } catch {
    // Fall through — best-effort. Pre-migration brains or query errors
    // shouldn't break delete/rename for path-derived pages.
  }
  return resolveSlugForPath(path);
}

/** #3942: a fallback resolution refused because the derived slug belongs to a different file. */
export interface RefusedSlugResolution {
  /** The removed file path the caller asked about. */
  path: string;
  /** The re-slugified slug that path derived to. */
  slug: string;
  /** The DIFFERENT file the page at that slug records as its origin. */
  originPath: string;
  /** #6948: several live pages record the removed path and none is its canonical page; none is touched. */
  claimants?: string[];
}

export interface RemovedPathSlugResolution {
  /** path → slug that is safe to act on (delete / rename-from). */
  slugs: Map<string, string>;
  /** Foreign-origin fallbacks the caller must skip (and should log). */
  refused: RefusedSlugResolution[];
}

/** Separator-normalize for source_path comparisons (mirrors sync-reconcile.ts). */
function normalizeOriginPath(p: string): string {
  return p.replace(/\\/g, '/');
}

/** One-line operator warning for a refused resolution (#3942). */
export function refusedRemovedPathMessage(r: RefusedSlugResolution): string {
  if (r.claimants) {
    return `  [sync] refusing to delete a page for removed path '${r.path}': ${r.claimants.join(', ')} all record it as their origin (preview gbrain repair origin-twins to choose the page that keeps it).`;
  }
  return (
    `  [sync] refusing to touch '${r.slug}' for removed path '${r.path}': ` +
    `that page originates from '${r.originPath}' (#3942 — re-slugified paths ` +
    `can collide; remove the page directly if you really meant it).`
  );
}

/**
 * #3942 — THE delete-side slug resolver. Every sync lane that turns a
 * REMOVED file path into a slug to delete (or rename away from) routes
 * through here, so the delete side can never act on a re-slugified
 * approximation that names a different file's page.
 *
 * Two phases:
 *
 *  1. Exact `source_path` match — the import side's own record (the same
 *     derivation that wrote the row). Scoped via `resolveSlugsByPaths` when
 *     `sourceId` is set; the legacy unscoped shape otherwise.
 *  2. Path-derived fallback (`resolveSlugForPath`, identical to the import
 *     side's `slugifyPath` dispatch) — but VERIFIED before use:
 *     `slugifySegment` strips trailing hyphens (among other lossy rewrites),
 *     so `extracts/propose-/x.md` and `extracts/propose/x.md` derive the SAME
 *     slug. Verification inspects ALL live rows at the derived slug (the
 *     unscoped lane can see one per source): if every one records a DIFFERENT
 *     origin file, the resolution is REFUSED (returned in `refused`, absent
 *     from `slugs`) instead of silently deleting a page whose own file is
 *     untouched; any row whose origin IS the removed path allows it. Pages
 *     with a NULL `source_path` (legacy pre-source_path imports) and slugs
 *     with no live row at all (no-op deletes) keep today's fallback behavior;
 *     soft-deleted rows are ignored on both phases.
 *
 * Fail-open on lookup errors (pre-migration schemas): a failed verification
 * query preserves the legacy fallback rather than wedging deletes — matching
 * the long-standing best-effort posture of `resolveSlugByPathOrSourcePath`.
 */
export async function resolveSlugsForRemovedPaths(
  engine: BrainEngine,
  paths: string[],
  sourceId: string | undefined,
): Promise<RemovedPathSlugResolution> {
  const slugs = new Map<string, string>();
  const refused: RefusedSlugResolution[] = [];
  if (paths.length === 0) return { slugs, refused };

  // Phase 1: exact source_path → slug (chunked to the engine batch cap).
  const exact = new Map<string, string>();
  if (sourceId !== undefined) {
    for (let i = 0; i < paths.length; i += DELETE_BATCH_SIZE) {
      try {
        const m = await engine.resolveSlugsByPaths(paths.slice(i, i + DELETE_BATCH_SIZE), { sourceId });
        for (const [p, s] of m) exact.set(p, s);
      } catch {
        // Best-effort — fall through to the verified phase-2 fallback.
      }
    }
  } else {
    for (const p of paths) {
      try {
        // Unscoped lane: only LIVE rows may drive resolution (a soft-deleted
        // row's record must not name a slug for the delete side to act on),
        // and the pick is ORDER BY-deterministic when a multi-source brain
        // holds several rows for the same source_path.
        const rows = await engine.executeRaw<{ slug: string }>(
          `SELECT slug FROM pages WHERE source_path = $1 AND deleted_at IS NULL
            ORDER BY source_id, slug LIMIT 1`,
          [p],
        );
        if (rows.length > 0 && rows[0].slug) exact.set(p, rows[0].slug);
      } catch {
        // Best-effort.
      }
    }
  }

  const twins = new Map<string, string[]>();
  const unresolved = paths.filter(p => !exact.has(p));
  for (let i = 0; sourceId !== undefined && i < unresolved.length; i += DELETE_BATCH_SIZE) {
    try {
      const rows = await engine.executeRaw<{ source_path: string; slugs: string[] }>(`SELECT source_path, array_agg(slug ORDER BY slug) AS slugs FROM pages
        WHERE source_id = $1 AND deleted_at IS NULL AND source_path = ANY($2::text[]) GROUP BY source_path HAVING count(*) > 1`, [sourceId, unresolved.slice(i, i + DELETE_BATCH_SIZE)]);
      for (const row of rows) twins.set(row.source_path, row.slugs);
    } catch {
      // Best-effort, like phase 1.
    }
  }
  const fallbacks: Array<{ path: string; slug: string }> = [];
  for (const p of paths) {
    const claimants = twins.get(p);
    if (claimants) { refused.push({ path: p, slug: claimants[0]!, originPath: p, claimants }); continue; }
    const hit = exact.get(p);
    if (hit !== undefined) slugs.set(p, hit);
    else fallbacks.push({ path: p, slug: resolveSlugForPath(p) });
  }
  if (fallbacks.length === 0) return { slugs, refused };

  // Phase 2: verify each derived slug's recorded origin before trusting it.
  // Per-item placeholders (not ANY(array)) so the same executeRaw shape binds
  // identically on both engines — a query error here fails OPEN, which would
  // silently disable the guard, so the boring portable form wins.
  //
  // Collect ALL live rows per slug: the unscoped lane can see one row per
  // source at the same slug, and a single-value (last-row-wins) map made
  // refuse-vs-allow depend on engine row order. `deleted_at IS NULL` keeps
  // soft-deleted rows from vetoing (or licensing) a delete, and the ORDER BY
  // makes the reported refusal origin deterministic. The scoped lane has at
  // most one live row per slug, so its behavior is unchanged.
  const originsBySlug = new Map<string, Array<string | null>>();
  for (let i = 0; i < fallbacks.length; i += DELETE_BATCH_SIZE) {
    const chunk = fallbacks.slice(i, i + DELETE_BATCH_SIZE).map(f => f.slug);
    try {
      const params: unknown[] = [...chunk];
      const placeholders = chunk.map((_, j) => `$${j + 1}`).join(', ');
      let where = `slug IN (${placeholders}) AND deleted_at IS NULL`;
      if (sourceId !== undefined) {
        params.push(sourceId);
        where += ` AND source_id = $${params.length}`;
      }
      const rows = await engine.executeRaw<{ slug: string; source_path: string | null }>(
        `SELECT slug, source_path FROM pages WHERE ${where} ORDER BY source_id, slug`,
        params,
      );
      for (const r of rows) {
        const list = originsBySlug.get(r.slug);
        if (list) list.push(r.source_path);
        else originsBySlug.set(r.slug, [r.source_path]);
      }
    } catch {
      // Fail-open: without origin evidence, keep the legacy fallback.
    }
  }
  for (const f of fallbacks) {
    const origins = originsBySlug.get(f.slug) ?? [];
    // Allow when: no live row at the slug (harmless no-op delete), any legacy
    // NULL-origin row (pre-source_path brains keep today's fallback), or ANY
    // live row that records the removed path itself as its origin. Refuse
    // only when every live row positively names a DIFFERENT origin file.
    const anyNullOrigin = origins.some(o => o == null);
    const anyMatch = origins.some(
      o => o != null && normalizeOriginPath(o) === normalizeOriginPath(f.path),
    );
    if (origins.length > 0 && !anyNullOrigin && !anyMatch) {
      // All origins are non-null mismatches; origins[0] is source_id-ordered,
      // so the reported path is deterministic.
      refused.push({ path: f.path, slug: f.slug, originPath: origins[0] as string });
    } else {
      slugs.set(f.path, f.slug);
    }
  }
  return { slugs, refused };
}

/**
 * Single-path convenience over `resolveSlugsForRemovedPaths` for the per-path
 * sync lanes. Logs any refusal through `warn` and returns undefined so the
 * caller skips the destructive action (#3942).
 */
export async function resolveRemovedPathSlug(
  engine: BrainEngine,
  path: string,
  sourceId: string | undefined,
  warn: (msg: string) => void,
): Promise<string | undefined> {
  const res = await resolveSlugsForRemovedPaths(engine, [path], sourceId);
  for (const r of res.refused) warn(refusedRemovedPathMessage(r));
  return res.slugs.get(path);
}

/**
 * git CLI helper.
 *
 * `configs` flags are emitted as `-c key=val` pairs BEFORE `-C repoPath` and
 * BEFORE the subcommand. `core.quotepath=false` is always emitted first so CJK
 * (and other non-ASCII) paths arrive as UTF-8 in `diff --name-status` and
 * sibling commands. Callers that need additional git config should pass via
 * the `configs` parameter; never inline `-c` into `args`.
 *
 * Exported for `test/sync.test.ts` invariant assertion only.
 */
export function buildGitInvocation(repoPath: string, args: string[], configs: string[] = []): string[] {
  const cfg = ['core.quotepath=false', ...configs].flatMap(c => ['-c', c]);
  return [...cfg, '-C', repoPath, ...args];
}

export function buildAutoEmbedArgs(slugs: string[], sourceId?: string): string[] {
  return sourceId ? ['--source', sourceId, '--slugs', ...slugs] : ['--slugs', ...slugs];
}

/**
 * Resolve sync's effective no-embed mode from CLI args + config.
 *
 * The deferred-setup sentinel (`embedding_disabled: true`, written by
 * `gbrain init --no-embedding`) is an implicit `--no-embed`: without this,
 * the embed credential preflight demands provider credentials the user
 * deliberately deferred at init, and every `gbrain sync` on a keyless
 * brain exits 1. See embed-preflight.ts's skip protocol — the sentinel is
 * meant to be honored before the credential check ever runs.
 *
 * Exported for `test/sync-no-embed-sentinel.test.ts`.
 */
export function resolveNoEmbed(
  args: string[],
  cfg: { embedding_disabled?: boolean } | null,
): boolean {
  return args.includes('--no-embed') || cfg?.embedding_disabled === true;
}

/** Subcommands that never change a repository; any other one drops the doctor-run git memo (git-visible-files.ts). */
const READ_ONLY_GIT = new Set(['rev-parse', 'ls-files', 'ls-tree', 'cat-file', 'diff', 'log', 'show', 'status', 'rev-list', 'merge-base',
  'for-each-ref', 'show-ref', 'describe', 'check-ignore', 'name-rev', 'blame', 'grep', 'check-attr', 'var', 'version']);

function noteGitCommand(args: string[]): void {
  if (!READ_ONLY_GIT.has(args[0] ?? '')) invalidateGitListingCache();
}

/** `GIT_READ_ENV` for a read-only subcommand (no optional index lock), nothing for one that writes. */
function readOnlyEnv(args: string[]): NodeJS.ProcessEnv {
  return READ_ONLY_GIT.has(args[0] ?? '') ? GIT_READ_ENV : {};
}

/**
 * Shell out to git with a generous maxBuffer.
 *
 * Node's default maxBuffer is 1 MiB.  `git diff --name-status -M` on a
 * 60–100K file repo easily exceeds that, causing an ENOBUFS crash that
 * kills the sync process with no error message in the log.
 *
 * 100 MiB is generous but still bounded — a 100K-file diff with long
 * paths tops out around 10–20 MiB in practice.
 *
 * `silenceStderr`: Node's `execFileSync` writes the child's stderr straight
 * through to the parent's real stderr by default (in addition to attaching
 * it to the thrown error's `.stderr`) *unless* an explicit `stdio` array is
 * given. Callers that treat a failure as an expected, self-handled outcome
 * (rather than a crash to surface) pass `silenceStderr: true` so git's raw
 * `fatal: ...` line never reaches the process's own stderr — only the
 * caller's own (usually friendlier) handling of the caught error does.
 * Default `false` preserves today's passthrough for every other call site.
 */
export function git(
  repoPath: string,
  args: string[],
  configs: string[] = [],
  timeoutMs = 30000,
  { silenceStderr = false }: { silenceStderr?: boolean } = {},
): string {
  noteGitCommand(args);
  return execFileSync('git', buildGitInvocation(repoPath, args, configs), {
    env: gitChildEnv(readOnlyEnv(args)),
    encoding: 'utf-8',
    timeout: timeoutMs,
    maxBuffer: 100 * 1024 * 1024,
    ...(silenceStderr ? { stdio: ['ignore', 'pipe', 'pipe'] as const } : {}),
  }).trim();
}

/**
 * GBRA-133 2b.3: `git()` without blocking the event loop, for the classic sync a resident (serve, the jobs worker,
 * autopilot) runs in-process on a commit. Same invocation, environment, timeout and buffer. A failure rejects like
 * `execFileSync` throws (`status`, `signal`, `stdout`, `stderr`), and git's stderr reaches this process's stderr unless
 * silenced, as `execFileSync` passes it through. `raw` keeps the output untrimmed (NUL-delimited listings).
 */
export async function gitAsync(
  repoPath: string,
  args: string[],
  { configs = [], timeoutMs = 30000, silenceStderr = false, raw = false }: { configs?: string[]; timeoutMs?: number; silenceStderr?: boolean; raw?: boolean } = {},
): Promise<string> {
  noteGitCommand(args);
  const r = await execFileBounded('git', buildGitInvocation(repoPath, args, configs), {
    env: gitChildEnv(readOnlyEnv(args)), timeout: timeoutMs, maxBuffer: 100 * 1024 * 1024,
  });
  if (r.stderr && !silenceStderr) process.stderr.write(r.stderr);
  if (r.error) {
    const code = (r.error as { code?: unknown }).code;
    throw Object.assign(new Error(r.error.message), { status: typeof code === 'number' ? code : null, signal: r.error.signal ?? null,
      code, stdout: r.stdout, stderr: r.stderr });
  }
  return raw ? r.stdout : r.stdout.trim();
}

/**
 * git() minus the trim — REQUIRED for NUL-delimited listings (`ls-files -z`,
 * `ls-tree -z`): a filename that begins with a space is the FIRST entry of
 * the listing, and trim() silently rewrites it into a different path (#3583
 * review — the misread let a decoy blob stand in for the real file and a
 * live page was deleted on the corrupted evidence).
 */
export function gitRawOutput(repoPath: string, args: string[]): string {
  noteGitCommand(args);
  return execFileSync('git', buildGitInvocation(repoPath, args, []), {
    env: gitChildEnv(readOnlyEnv(args)),
    encoding: 'utf-8',
    timeout: 30000,
    maxBuffer: 100 * 1024 * 1024,
  });
}

/**
 * #753/#774: walk up from inputPath to the nearest git repo root via
 * `git -C <path> rev-parse --show-toplevel`. Handles worktrees and submodules
 * natively (git itself resolves them). Throws a user-friendly error when no
 * git repo is found.
 *
 * The probe's failure is expected and routine (a non-git-yet brain dir, a
 * scratch dir, a caller checking "is this a repo?") — `sync.ts` self-heals
 * it (git-init) or surfaces the message below, never the raw git stderr.
 * `silenceStderr: true` keeps git's own `fatal: not a git repository ...`
 * off the process's real stderr so operator log-scanning for `fatal:` as a
 * crash signature doesn't false-alarm on every routine probe miss (#2964
 * auto-recovery made the *outcome* self-healing; this keeps the *log* quiet
 * about the expected miss that triggered it).
 */
export function discoverGitRoot(inputPath: string): string {
  try {
    if (knownOutsideGitRepo(inputPath)) throw new Error('outside a git repository');
    return git(inputPath, ['rev-parse', '--show-toplevel'], [], 30000, { silenceStderr: true });
  } catch (error) {
    throw notAGitRepository(inputPath, error);
  }
}

/** `discoverGitRoot` without blocking the event loop (GBRA-133 2b.3). */
export async function discoverGitRootAsync(inputPath: string): Promise<string> {
  try {
    if (knownOutsideGitRepo(inputPath)) throw new Error('outside a git repository');
    return await gitAsync(inputPath, ['rev-parse', '--show-toplevel'], { silenceStderr: true });
  } catch (error) {
    throw notAGitRepository(inputPath, error);
  }
}

function notAGitRepository(inputPath: string, error: unknown): Error {
  noteGitFailure(inputPath, error);
  return new Error(`Not inside a git repository: ${inputPath}. GBrain sync requires a git-initialized repo (or a subdirectory of one).`);
}

/**
 * #2964: snapshot the CURRENT on-disk state of a gbrain-owned brain dir as
 * a baseline commit — used both right after a self-healing `git init` (no
 * `.git` at all) and to recover a repo left with `.git` but zero commits
 * (an interrupted prior self-heal, or a `git init` from some other source
 * that never got a first commit). Respects `.gitignore` (written first) so
 * future incremental syncs diff against what's actually here rather than
 * an empty tree — an empty initial commit would make every existing file
 * look "added" again on the next sync, even though the full-sync pass that
 * follows already imported them from disk directly.
 *
 * `--no-gpg-sign` + explicit `-c user.name/user.email`: this runs from a
 * headless nightly cron/launchd invocation, which has no reason to have
 * git signing/identity configured, and must not block on an unavailable
 * signing agent or pinentry prompt.
 *
 * db_only exclusion is recomputed directly and passed to `git add` as
 * negative pathspecs, rather than relying solely on `manageGitignore`
 * having written `.gitignore` successfully: that helper is deliberately
 * best-effort (a broken gbrain.yml parse, or an unwritable .gitignore,
 * only warns and returns — the right default for its OTHER callers, where
 * .gitignore management is a side effect that must never kill the sync
 * job). For a commit we are about to create ourselves, "fail open" there
 * would mean silently committing db_only content into git history. Fail
 * closed instead: db_only exclusion doesn't depend on the .gitignore
 * write having succeeded. `loadStorageConfig` throwing (unreadable
 * gbrain.yml, or a semantic overlap) propagates — better to leave this
 * self-heal wedged with a clear error than commit unknown content.
 */
/**
 * Classify a caught `git rev-parse --verify --quiet HEAD` failure for the
 * baseline-commit guard. A genuinely UNBORN HEAD makes git exit with status
 * EXACTLY 1 and nothing on stderr — precisely what `--verify --quiet` emits
 * for an unresolvable HEAD (verified empirically: unborn => exit 1, empty
 * stderr; born => exit 0). Every OTHER failure shape — a 30s timeout (killed
 * by signal, so `status` is null), an index/ref lock (`fatal: Unable to
 * create ...lock`, non-empty stderr), or any nonzero-but-not-1 exit — is NOT
 * proof the repo is empty; it is the transient-probe-failure class that
 * corrupted the live brain on 2026-08-10. Return 'unborn' ONLY for the clean
 * signal so the caller fails CLOSED on 'ambiguous'. Pure (no I/O) so the
 * distinction is unit-testable without fault injection.
 */
export function classifyHeadProbeError(err: unknown): 'unborn' | 'ambiguous' {
  const e = (err ?? {}) as { status?: number | null; signal?: string | null; stderr?: unknown };
  const stderr = e.stderr == null ? '' : String(e.stderr).trim();
  return e.status === 1 && e.signal == null && stderr === '' ? 'unborn' : 'ambiguous';
}

export function createSyncBaselineCommit(repoPath: string): void {
  // Fail-closed backstop (2026-08-10 auto-init incident). This function's
  // ENTIRE contract is "snapshot an unborn/uninitialized repo as its FIRST
  // commit". It must NEVER run on a repo that already has commits: doing so
  // stacks a spurious `gbrain: initial commit (auto-init by sync)` commit ON
  // TOP of real history and, on a case-insensitive filesystem, re-cases the
  // whole tree (`projects` -> `Projects`) as a `git add -A` side effect.
  //
  // Both call sites are *supposed* to reach here only on an unborn/non-git
  // repo, but each infers "unborn" from a FAILURE to observe git state
  // (`discoverGitRoot` threw / `git rev-parse HEAD` threw), and those probes
  // ALSO fail transiently — a 30s timeout on a large brain, or a concurrent
  // `gbrain-sync` holding a git lock — against a fully-populated repo, which
  // is exactly what corrupted the live brain on 2026-08-10. So we cannot
  // trust "the caller said it's unborn"; verify POSITIVELY here — and, since
  // this very probe is subject to the same transient failures, accept ONLY a
  // CLEAN unborn signal. A born HEAD (exit 0) OR an ambiguous probe failure
  // (timeout / lock / other) both REFUSE, so the backstop is fail-closed
  // against every corruption path, not just the born-HEAD one.
  // `classifyHeadProbeError` isolates that born/unborn/ambiguous distinction
  // as a pure, unit-tested predicate.
  //
  // Known non-incident edge (B2, documented not fixed): an orphan branch
  // (`git switch --orphan`) in a repo with history elsewhere probes as unborn
  // and would still be baselined. A gbrain brain is never in that state; it is
  // not the incident (no stacking on real history, no re-case of other
  // branches), so it is left as a limitation rather than complicating the
  // guard with a `rev-list --all` "commits anywhere" probe.
  let headState: 'born' | 'unborn' | 'ambiguous';
  try {
    git(repoPath, ['rev-parse', '--verify', '--quiet', 'HEAD'], [], 30000, { silenceStderr: true });
    headState = 'born';
  } catch (err) {
    headState = classifyHeadProbeError(err);
  }
  if (headState !== 'unborn') {
    throw new Error(
      `Refusing to create a sync baseline commit in ${repoPath}: HEAD probe is ` +
        `'${headState}', expected a clean unborn HEAD. 'born' = the repo already ` +
        `has commits (real history); 'ambiguous' = the HEAD check failed ` +
        `transiently (30s timeout, or a concurrent gbrain-sync holding a git ` +
        `lock), which is NOT proof the repo is empty. Committing either way ` +
        `would stack a bogus auto-init commit on real history and re-case the ` +
        `tree on a case-insensitive filesystem.`,
    );
  }
  // #2964: db_only exclusion is computed directly from loadStorageConfig
  // and passed to `git add` as pathspecs — deliberately NOT via
  // manageGitignore/.gitignore, for two independent reasons:
  //
  // 1. Ordering (Codex review round 6, P1): `collectSyncableFiles` — the
  //    file enumeration `performFullSync` runs right after this function
  //    returns — honors `.gitignore` via `git ls-files --exclude-standard`.
  //    Writing db_only entries into `.gitignore` BEFORE that first import
  //    would silently exclude those pages from the database entirely.
  //    That's the exact bug class `runSync`'s existing "manage .gitignore
  //    ONLY on successful sync" ordering (this file, `manageGitignoreAtGitRoot`
  //    callers below — itself a prior Codex P1 fix) exists to prevent. Leave
  //    `.gitignore` untouched here; the existing post-sync flow writes it
  //    once this sync completes, same as it does for every other sync.
  // 2. Fail-closed (rounds 5-6): `manageGitignore`'s "warn and return" on a
  //    broken gbrain.yml/unwritable .gitignore is the right default for its
  //    OTHER callers (a side effect that must never kill the sync job), but
  //    wrong for a commit we are creating ourselves — silently committing
  //    db_only content into git history.
  const storageConfig = loadStorageConfig(repoPath);
  const dbOnlyDirs = storageConfig?.db_only ?? [];
  // Sniff-test fail-closed (round 6, P2): `loadStorageConfig` warns-and-
  // returns an EMPTY config for syntactically-valid-but-unsupported YAML
  // (e.g. a flow list split over lines; the narrow custom parser handles
  // block lists and one-line flow lists), which would silently resolve zero
  // exclusions from a file that clearly intended some. If gbrain.yml has a
  // db_only (or deprecated `supabase_only`) key line but nothing resolved
  // from it, refuse rather than guess; `hasUnresolvedDbOnlyDeclaration`
  // owns the key-line rules (an explicit empty `db_only: []` declares none, #8007);
  // silently committing db_only content into permanent git history is high-cost and hard to undo.
  if (hasUnresolvedDbOnlyDeclaration(repoPath, storageConfig)) {
    const yamlPath = join(repoPath, 'gbrain.yml');
    throw new Error(
      `${yamlPath} mentions db_only but no directories resolved from it — refusing to ` +
        `auto-commit (cannot tell "genuinely empty" from "unsupported syntax silently ignored"). ` +
        `Fix gbrain.yml's storage.db_only syntax, or git-init this directory manually.`,
    );
  }
  // #2964 (round 9, P1): every db_only dir is ALWAYS pathspec-excluded,
  // unconditionally — never pre-filtered against what an existing
  // `.gitignore` claims to already cover. An earlier version checked
  // `git check-ignore -q dir` first and skipped the pathspec when it
  // already reported "ignored" (to dodge the advisory error below), but
  // `check-ignore` on a directory can say "ignored" even when a
  // pre-existing `.gitignore` re-includes a child via negation (e.g.
  // `private-cache/*` + `!private-cache/index.md`) — the filter would
  // then skip excluding it via pathspec, and `git add -A` would stage
  // that re-included child despite the whole directory being declared
  // db_only. Our OWN pathspec exclusion is unconditional and doesn't
  // consult `.gitignore` at all, so it can't be defeated by ANY
  // .gitignore content, negated or not. `:(exclude,literal)dir` (not the
  // `:!dir` shorthand) so a db_only dir name that itself starts with a
  // pathspec magic character like `:` is excluded literally rather than
  // reinterpreted (round 9, P2).
  const excludePathspecs = dbOnlyDirs.map((dir) => `:(exclude,literal)${dir}`);
  // Clear the index before staging (round 6, P1): the unborn-HEAD
  // recovery site can reach this function with a repo whose index
  // already has entries staged from some OTHER prior operation (a manual
  // `git add`, an interrupted workflow) before gbrain ever touched it.
  // `add -A` only adds/updates — it does not drop an already-staged path
  // that our exclusion pathspecs above now want excluded. `read-tree
  // --empty` resets the index without touching the working tree; a
  // no-op on a freshly-`git init`-ed repo, whose index is already empty.
  git(repoPath, ['read-tree', '--empty']);
  try {
    // #2964: 10 minutes, not the shared git() helper's 30s default — this
    // full-tree `git add -A` walks a legacy brain that may hold years of
    // accumulated content. A 30s timeout would abort staging after `git
    // init` already created `.git`, leaving an unborn repo that every
    // subsequent sync would retry (and time out identically) forever;
    // the unborn-HEAD recovery path exists for OTHER causes of that
    // state, not to be this one's normal first outcome.
    git(repoPath, ['add', '-A', '--', '.', ...excludePathspecs], [], 600_000);
  } catch (err) {
    // Now that exclusion is always applied (never pre-filtered), an
    // explicit pathspec exclusion for a path a pre-existing `.gitignore`
    // ALSO happens to cover trips git's advice.addIgnoredFile: nonzero
    // exit + "paths ignored by one of your .gitignore files, use -f",
    // even though the add otherwise fully succeeded (verified directly:
    // `git status --short` right after this exact error shows every
    // non-excluded path staged correctly). Recognize and swallow ONLY
    // this exact advisory; anything else (timeout, permission denied,
    // real corruption) rethrows.
    const stderr = err && typeof err === 'object' && 'stderr' in err ? String((err as { stderr: unknown }).stderr) : '';
    if (!stderr.includes('ignored by one of your .gitignore files')) throw err;
  }
  recordIntent(repoPath, { writer: 'sync_init', head_before: null, message: 'gbrain: initial commit (auto-init by sync)' });
  git(
    repoPath,
    // --no-verify only skips pre-commit/commit-msg — prepare-commit-msg
    // and (worse, since it runs AFTER the commit object already exists,
    // synchronously inside this same git invocation) post-commit are
    // NOT covered by it. An operator's global core.hooksPath or
    // init.templateDir can wire either, expecting project tooling,
    // prompting interactively, or hanging — none of which a headless
    // self-heal commit can satisfy, and a hanging post-commit hook would
    // burn the 600s budget above without even being the slow step.
    // `-c core.hooksPath=/dev/null` (in configs, below) makes git look
    // for hook scripts inside a location that can't contain any,
    // disabling the entire hooks path for this one invocation — the
    // complete form of what --no-verify only partially covers, kept for
    // explicitness on the two hooks it does name.
    [
      'commit', '--quiet', '--allow-empty', '--no-gpg-sign', '--no-verify',
      '-m', 'gbrain: initial commit (auto-init by sync)',
    ],
    ['user.name=gbrain', 'user.email=gbrain@localhost', 'core.hooksPath=/dev/null'],
  );
  recordCommit(repoPath, { sha: git(repoPath, ['rev-parse', 'HEAD']), writer: 'sync_init' });
}

/**
 * True when `childReal` is `rootReal` itself or lives inside it. Both arguments
 * must already be realpath-resolved. Containment is decided by `relative()`
 * rather than a string prefix, so it holds on Windows too: `realpathSync`
 * returns backslash paths there, and a literal `rootReal + '/'` prefix can
 * never match one. A sibling (`root-evil`) is rejected because `relative`
 * yields `../root-evil`, and a cross-drive path because it yields an absolute.
 * On Windows this intentionally follows the platform path semantics exposed by
 * `win32.relative`, including case-insensitive segment matching; detecting rare
 * per-directory case-sensitive NTFS siblings would require filesystem identity
 * checks rather than a pure path check. (#4044/#4144)
 */
interface PathContainmentOps {
  relative(from: string, to: string): string;
  isAbsolute(path: string): boolean;
  sep: string;
}

const nativePathContainmentOps: PathContainmentOps = { relative, isAbsolute, sep };

export function gitRelativePath(
  from: string,
  to: string,
  pathOps: Pick<PathContainmentOps, 'relative'> = nativePathContainmentOps,
): string {
  return pathOps.relative(from, to).replace(/\\/g, '/');
}

export function isWithinRoot(
  childReal: string,
  rootReal: string,
  pathOps: PathContainmentOps = nativePathContainmentOps,
): boolean {
  if (childReal === rootReal) return true;
  const rel = pathOps.relative(rootReal, childReal);
  if (rel === '') return true;
  return rel !== '..' && !rel.startsWith('..' + pathOps.sep) && !pathOps.isAbsolute(rel);
}

/**
 * #774 NAV-1 TOCTOU: true only if filePath realpath-resolves inside gitRoot.
 * Guards symlink escape at the per-file level (a committed symlink whose
 * target lives outside the repo), not just at scope entry. GBRA-133 S-4: a
 * leaf that is not a symlink resolves through its parent directory (Bun's
 * realpathSync returns ENOENT for an existing name containing a backslash).
 */
export function isPathSafe(filePath: string, gitRoot: string): boolean {
  try {
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- this is the containment guard: join normalizes the realpath'd parent plus basename, and isWithinRoot below rejects any result outside gitRoot
    const real = lstatSync(filePath).isSymbolicLink() ? realpathSync(filePath) : join(realpathSync(dirname(filePath)), basename(filePath));
    return isWithinRoot(real, realpathSync(gitRoot));
  } catch {
    return false;
  }
}

export function hasOriginRemote(repoPath: string): boolean {
  try {
    execFileSync('git', buildGitInvocation(repoPath, ['remote', 'get-url', 'origin']), {
      env: gitChildEnv(GIT_READ_ENV),
      encoding: 'utf-8',
      timeout: 30000,
      stdio: ['ignore', 'ignore', 'ignore'],
    });
    return true;
  } catch {
    return false;
  }
}

export function isDetachedHead(repoPath: string): boolean {
  try {
    git(repoPath, ['symbolic-ref', '--quiet', 'HEAD']);
    return false;
  } catch {
    return true;
  }
}

/** `isDetachedHead` without blocking the event loop (GBRA-133 2b.3). */
export async function isDetachedHeadAsync(repoPath: string): Promise<boolean> {
  return gitAsync(repoPath, ['symbolic-ref', '--quiet', 'HEAD']).then(() => false, () => true);
}

export function unique<T>(items: T[]): T[] {
  return [...new Set(items)];
}