Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
54.7 KB
Raw Blame
import { assertUnmanagedCanonicalWriter } from './persistence/maintenance.ts';
import { managedPersistenceEnabled } from './persistence/ownership.ts';
/**
 * gbrain sources-ops — pure async functions for source-management operations
 * (v0.28). Extracted from src/commands/sources.ts so the CLI handlers and the
 * MCP ops (sources_add / list / remove / status) share one implementation.
 *
 * Atomicity contract for addSource with --url (D3, eng-review):
 *
 *                    sources add --url <url>
 *                              │
 *                              ▼
 *                  parseRemoteUrl(url) → SSRF gate
 *                              │
 *                              ▼  (URL ok)
 *                  pre-flight SELECT id ─── id taken? ──► error (Q4)
 *                              │
 *                              ▼  (id free)
 *                  mkdir $GBRAIN_HOME/clones/.tmp/<id>-<rand>/
 *                              │
 *                              ▼
 *                  cloneRepo(url, tmp/) ─── fail ──► rm -rf tmp/, throw
 *                              │
 *                              ▼
 *                  INSERT INTO sources ─── fail ──► rm -rf tmp/, throw
 *                              │
 *                              ▼
 *                  fs.renameSync(tmp/, final) ─── fail ──► rm -rf tmp/, throw
 *                                                              + best-effort
 *                                                              DELETE row
 *                              │
 *                              ▼
 *                       return SourceRow
 *
 * Symlink-safe clone-cleanup for removeSource: realpath + lstat confinement
 * mirroring src/core/operations.ts:61 validateUploadPath. String startsWith
 * is symlink-unsafe and would let $GBRAIN_HOME/clones/<id> → /etc resolve
 * out of the confine.
 */

import { existsSync, mkdirSync, renameSync, rmSync, lstatSync, realpathSync } from 'fs';
import { join, dirname, basename, isAbsolute, resolve as resolvePath } from 'path';
import { isHostAbsolutePath, isPathContained, msysToNativePath } from './path-confine.ts';
import { mkdirPrivate } from './atomic-write.ts';
import { randomBytes } from 'crypto';
import type { BrainEngine } from './engine.ts';
import {
  parseRemoteUrl,
  cloneRepo,
  validateRepoState,
  inGitCheckout,
  hasTrackedContent,
  RemoteUrlError,
  GitOperationError,
  type RepoState,
} from './git-remote.ts';
import { gbrainPath } from './config.ts';
import { isValidSourceId } from './source-id.ts';
import { googleTuningConfig } from './google/source-config.ts';
import { isSyncStrategy, type SyncStrategy } from './sync.ts';
import { DEFAULT_CALENDAR_ID } from './google/types.ts';
import { resolveSourceWithTier, type SourceTier } from './source-resolver.ts';
import { deleteSourceRow } from './source-delete.ts';
import { defaultCloneDir, isOwnedClone } from './url-clone.ts';
import { hookSessionCwd } from './session-cwd.ts';

// ── Errors ──────────────────────────────────────────────────────────────────

export type SourceOpErrorCode =
  | 'invalid_id'
  | 'source_id_taken'
  | 'overlapping_path'
  | 'invalid_remote_url'
  | 'clone_failed'
  | 'insert_failed'
  | 'rename_failed'
  | 'not_found'
  | 'protected_id'
  | 'clone_dir_outside_gbrain'
  | 'symlink_escape'
  | 'unmanaged_path'
  | 'not_a_git_repo';

export class SourceOpError extends Error {
  constructor(
    public code: SourceOpErrorCode,
    message: string,
    public cause?: unknown,
  ) {
    super(message);
    this.name = 'SourceOpError';
  }
}

// ── Types ───────────────────────────────────────────────────────────────────

export interface SourceRow {
  id: string;
  name: string;
  local_path: string | null;
  last_commit: string | null;
  last_sync_at: Date | null;
  config: Record<string, unknown>;
  created_at: Date;
  /**
   * v0.40.3.0: per-source CR mode override. NULL falls through to global
   * mode bundle. Written only by `gbrain sources set-cr-mode <id> <mode>`
   * (CLI-write-only per D15 security gate); MCP / OAuth callers cannot
   * mutate this field.
   */
  contextual_retrieval_mode?: string | null;
  /**
   * v0.40.3.0: per-source mount-frontmatter trust gate (D15). FALSE for
   * mounted sources by default. Flipped via
   * `gbrain mounts trust-frontmatter <id>`. Host source (id='default') is
   * always trusted in the resolver regardless of this column value.
   */
  trust_frontmatter_overrides?: boolean;
}

export interface SourceListEntry {
  id: string;
  name: string;
  local_path: string | null;
  remote_url: string | null;
  federated: boolean;
  /** Persisted `config.strategy` (`gbrain sources set-strategy`); null means sync falls back to 'markdown'. */
  strategy: SyncStrategy | null;
  page_count: number;
  last_sync_at: string | null;
}

export interface SourceStatus {
  id: string;
  name: string;
  local_path: string | null;
  remote_url: string | null;
  federated: boolean;
  page_count: number;
  last_sync_at: string | null;
  last_commit: string | null;
  archived: boolean;
  /**
   * Discriminated union from validateRepoState. 'not-applicable' if the
   * source has no local_path (pure DB source). Lets a remote MCP caller
   * diagnose "is the clone OK?" without SSH access to the brain host.
   */
  clone_state: RepoState | 'not-applicable';
}

export interface AddSourceOpts {
  id: string;
  name?: string;
  requestId?: string;
  expectedIncarnation?: string;
  localPath?: string | null;
  remoteUrl?: string;
  /** The URL came from a remote caller: its clone and every later pull run without git-lfs downloads. */
  addedByRemoteCaller?: boolean;
  federated?: boolean | null;
  /**
   * Override clone destination. Defaults to $GBRAIN_HOME/clones/<id>/.
   * Only honored when remoteUrl is set.
   */
  cloneDir?: string;
  /**
   * Skip the #2707 git-repo validation on `localPath`. Opt-in escape hatch
   * for registering a path before it's git-initialized (e.g. an automated
   * pipeline that populates + `git init`s the directory after `sources add`
   * runs). Does NOT auto-`git init` anything — see `addSource` docstring.
   */
  force?: boolean;
  /**
   * v0.46: register a github-kind source (issues/PR sync). When set, the
   * row is inserted with kind=github config and a managed local_path, and
   * no git validation or clone happens. See src/core/github-source.ts.
   */
  github?: {
    tokenEnv: string;
    handle: string;
    scope: 'auto' | 'repos';
    repos: string[];
    dir: string;
    involvement: boolean;
    /** GitHub App id; with appPemPath the sync mints installation tokens itself. */
    appId?: number;
    /** Path to the app's private key PEM. */
    appPemPath?: string;
    /** Installation id; optional, first installation is used when absent. */
    appInstallId?: number;
  };
  /**
   * v0.47: register a google-kind source (Gmail/Calendar/Contacts sync).
   * API-backed like github; credentials come from the vault
   * (`gbrain google connect`), and `account` is only a pointer into it —
   * no secret ever lands in sources.config. See src/core/google/google-source.ts.
   */
  google?: {
    /** Account email — vault credential pointer (vault mode) or identity only. */
    account: string;
    /** Subset of gmail,calendar,contacts (comma-joined into config). */
    services: string[];
    /** Backfill/reconcile window in days. */
    historyDays: number;
    /** Calendar swept by this source (default DEFAULT_CALENDAR_ID). */
    calendarId?: string;
    /** #4845: directory under `dir` for contact pages (`g_contacts_dir`; default `people`). */
    contactsDir?: string;
    /** #5442: days ahead the calendar sweep covers (`g_future_days`; default CALENDAR_HORIZON_DAYS when absent). */
    futureDays?: number;
    /** #5445: Gmail label names/ids whose threads never enter loop extraction (`g_loops_exclude_labels`). */
    loopsExcludeLabels?: string[];
    /** Managed dir where pages are materialized. */
    dir: string;
    /** Token acquisition: gbrain vault (default), a token-printing command, or an env var. */
    access?: 'vault' | 'command' | 'env';
    tokenCommand?: string;
    tokenEnv?: string;
  };
  /**
   * Register a meetings-kind source (meeting notes from a provider API). The
   * API key lives in the connector credential store or the env var named by
   * `tokenEnv`; no secret lands in sources.config. See src/core/meetings/.
   */
  meetings?: import('./meetings/source-add.ts').AddSourceMeetingsOpts;
  /**
   * Register a slack-kind source (channel history from the Slack Web API). The
   * token lives in the connector credential store or the env var named by
   * `tokenEnv`; no secret lands in sources.config. See src/core/slack/.
   */
  slack?: import('./slack/source-add.ts').AddSourceSlackOpts;
  /** Register an imessage-kind source (the GBrain Helper on this Mac); always database-recorded and owner-only. See src/core/imessage/. */
  imessage?: import('./imessage/source-add.ts').AddSourceIMessageOpts;
}

export interface RemoveSourceOpts {
  id: string;
  confirmDestructive?: boolean;
  yes?: boolean;
  dryRun?: boolean;
  keepStorage?: boolean;
  requestId?: string;
  expectedIncarnation?: string;
}

// ── Helpers ─────────────────────────────────────────────────────────────────

/**
 * POSIX single-quote `arg` unless it's already shell-safe. #2707 codex round
 * 1: the `not_a_git_repo` remediation error prints a pasteable `git ...`
 * command built from the caller-supplied path — spaces, `$()`, backticks,
 * etc. must be inert literals when pasted, which double-quoting would not
 * guarantee (command substitution still runs inside "..."). Mirrors
 * `src/commands/connect.ts:shellQuote` (not imported — that file is a
 * commands/ caller of core/, not the other way around).
 */
function shellQuote(arg: string): string {
  if (/^[A-Za-z0-9_.:/@-]+$/.test(arg)) return arg;
  return `'${arg.replace(/'/g, "'\\''")}'`;
}

/**
 * Validate via the canonical regex from `source-id.ts` but rethrow as the
 * sources-ops-tagged error so `gbrain sources add` keeps its user-facing
 * SourceOpError shape. The regex itself is in one place; only the error
 * envelope differs per caller.
 */
function validateSourceId(id: string): void {
  if (!isValidSourceId(id)) {
    throw new SourceOpError(
      'invalid_id',
      `Invalid source id "${id}". Must be 1-32 lowercase alnum chars with optional interior hyphens.`,
    );
  }
}

function parseConfig(config: unknown): Record<string, unknown> {
  if (typeof config === 'string') {
    try {
      return JSON.parse(config) as Record<string, unknown>;
    } catch {
      return {};
    }
  }
  if (typeof config === 'object' && config !== null) return config as Record<string, unknown>;
  return {};
}

function isFederated(config: unknown): boolean {
  return parseConfig(config).federated === true;
}

function getRemoteUrl(config: unknown): string | null {
  const v = parseConfig(config).remote_url;
  return typeof v === 'string' ? v : null;
}

async function fetchSourceRow(engine: BrainEngine, id: string): Promise<SourceRow | null> {
  const rows = await engine.executeRaw<{
    id: string;
    name: string;
    local_path: string | null;
    last_commit: string | null;
    last_sync_at: Date | null;
    config: unknown;
    created_at: Date;
  }>(
    `SELECT id, name, local_path, last_commit, last_sync_at, config, created_at
       FROM sources WHERE id = $1`,
    [id],
  );
  const r = rows[0];
  if (!r) return null;
  return { ...r, config: parseConfig(r.config) };
}

async function countAllPages(engine: BrainEngine, id: string): Promise<number> {
  const rows = await engine.executeRaw<{ n: number }>(
    `SELECT COUNT(*)::int AS n FROM pages WHERE source_id = $1`,
    [id],
  );
  return rows[0]?.n ?? 0;
}

async function countVisiblePages(engine: BrainEngine, id: string): Promise<number> {
  const rows = await engine.executeRaw<{ n: number }>(
    `SELECT COUNT(*)::int AS n FROM pages WHERE source_id = $1 AND deleted_at IS NULL`,
    [id],
  );
  return rows[0]?.n ?? 0;
}

/** Temp clone dir under $GBRAIN_HOME/clones/.tmp/<id>-<rand>/ */
function makeTempCloneDir(id: string): string {
  const rand = randomBytes(6).toString('hex');
  return gbrainPath('clones', '.tmp', `${id}-${rand}`);
}

// `isPathContained` moved to `src/core/path-confine.ts` (shared with the
// dotfile-trust + skills-dir confinement helpers). Re-exported here so existing
// importers (and recloneIfMissing below) keep working unchanged.
export { isPathContained };

// `isOwnedClone` and `defaultCloneDir` live in url-clone.ts (shared with the #6946 write guards).
export { defaultCloneDir, isOwnedClone };

/**
 * Recovery hint for an unowned source with a remote_url. Splits guidance by
 * on-disk state: a healthy unowned path syncs read-only (just drop remote_url),
 * but a degraded one (missing/no-git/not-a-dir) cannot be recovered by dropping
 * remote_url — that would only defer the failure to the "Not a git repository"
 * check. Shared by the core SourceOpError and the sync.ts CLI error so they read
 * identically.
 */
export function unownedHint(
  src: { id: string; local_path: string | null },
  state: RepoState,
): string {
  const path = src.local_path ?? '(none)';
  if (state === 'healthy') {
    return (
      `Source "${src.id}" has config.remote_url set but local_path ${path} is not a ` +
      `clone gbrain created. gbrain syncs it read-only and will never re-clone or delete ` +
      `it. To silence this, drop config.remote_url, or re-register with --url so gbrain ` +
      `owns the clone.`
    );
  }
  return (
    `Source "${src.id}" has config.remote_url set but local_path ${path} is not a clone ` +
    `gbrain created and is not a usable git repo (state: ${state}). gbrain will NOT ` +
    `re-clone over it (it is your working tree, not a gbrain-managed mirror). Restore the ` +
    `directory yourself, or remove + re-add the source with --url to let gbrain manage the ` +
    `clone.`
  );
}

// ── addSource ───────────────────────────────────────────────────────────────

/**
 * Overlapping-path guard shared by every surface that binds a local_path to a
 * source (`sources add`, `sources set-path`): a path equal to, nested inside,
 * or enclosing any OTHER source's local_path is rejected as
 * `overlapping_path`. Overlapping trees make sync / write-through attribute
 * files to the wrong source, so no add or repair path may skip this.
 */
export async function assertNoOverlappingPath(
  engine: BrainEngine,
  id: string,
  path: string,
): Promise<void> {
  const others = await engine.executeRaw<{ id: string; local_path: string }>(
    `SELECT id, local_path FROM sources WHERE local_path IS NOT NULL AND id != $1`,
    [id],
  );
  // Compare by spelling AND by realpath: a symlink whose spelling shares no
  // prefix with another source's tree still resolves onto that tree, and the
  // sibling may itself be registered via a symlink. Realpath only when the
  // path exists (a dangling/absent path keeps its spelling — the string check
  // still applies); the stored value and the error message keep the spelling.
  const real = (p: string): string => {
    try {
      return realpathSync(p);
    } catch {
      return p;
    }
  };
  const overlaps = (x: string, y: string): boolean =>
    x === y || x.startsWith(y + '/') || y.startsWith(x + '/');
  const realPath = real(path);
  for (const other of others) {
    const b = other.local_path;
    // #7630: a relative local_path names whatever directory gbrain runs from, never a tree, so it overlaps nothing.
    if (!isAbsolute(b)) continue;
    if (overlaps(path, b) || overlaps(realPath, real(b))) {
      throw new SourceOpError(
        'overlapping_path',
        `path "${path}" overlaps with existing source "${other.id}" at "${b}". ` +
          `Overlapping sources are not allowed.`,
      );
    }
  }
}

/**
 * #2707: `--path` registration used to accept any existing directory with
 * zero git validation, deferring the failure to the first `gbrain sync`
 * ("Not inside a git repository: ..."). By the time that surfaces the
 * source has already been silently stale for however long nobody read the
 * sync logs. This is registration-time, fail-fast validation ONLY — it
 * never auto-`git init`s the directory (that would cross the consent
 * boundary #2967 established for sync-time self-heal: a `--path` source is
 * the user's own external directory, and gbrain must not mutate it without
 * explicit ask). Callers who want to register before git-init exists opt in
 * via `force: true` (CLI: `--force`).
 */
/**
 * Path E of `addSource`: `--kind meetings` and `--kind slack`. API-backed, so nothing is cloned.
 * `database` records keep no directory (local_path NULL); `git` records commit
 * pages into --dir, inside a Git checkout that no other source covers (a nested
 * root would import every page twice).
 */
async function insertApiSource(engine: BrainEngine, opts: AddSourceOpts, kind: 'meetings' | 'slack' | 'imessage'): Promise<void> {
  if (kind === 'imessage') {
    const { imessageSourceConfig } = await import('./imessage/source-add.ts');
    await engine.executeRaw('INSERT INTO sources (id, name, local_path, config) VALUES ($1, $2, NULL, $3::text::jsonb)',
      [opts.id, opts.name ?? opts.id, JSON.stringify(imessageSourceConfig(opts.imessage!, opts.federated))]);
    return;
  }
  const { chooseMeetingsRecord, meetingsSourceConfig } = await import('./meetings/source-add.ts');
  const { slackSourceConfig } = await import('./slack/source-add.ts');
  const request = kind === 'slack' ? opts.slack! : opts.meetings!;
  const choice = chooseMeetingsRecord(opts.id, request.record, request.dir, kind);
  if (choice.dir) {
    const overlap = (await engine.executeRaw<{ id: string; local_path: string }>('SELECT id,local_path FROM sources WHERE local_path IS NOT NULL'))
      .find(row => isPathContained(choice.dir!, row.local_path) || isPathContained(row.local_path, choice.dir!));
    if (overlap) throw new SourceOpError('overlapping_path',
      `${choice.dir} overlaps source "${overlap.id}" at ${overlap.local_path}; its pages would be imported by both sources. Choose a directory no other source covers.`);
    mkdirPrivate(choice.dir);
  }
  await engine.executeRaw(
    `INSERT INTO sources (id, name, local_path, config)
         VALUES ($1, $2, $3, $4::text::jsonb)`,
    [opts.id, opts.name ?? opts.id, choice.dir, JSON.stringify(kind === 'slack' ? slackSourceConfig(opts.slack!, choice, opts.federated, false)
      : meetingsSourceConfig(opts.meetings!, choice, opts.federated, false))],
  );
}

export async function addSource(
  engine: BrainEngine,
  opts: AddSourceOpts,
): Promise<SourceRow> {
  opts = await (await import('./source-default-search.ts')).withDefaultSearchChoice(engine, opts); if(await managedPersistenceEnabled(engine))return (await import('./persistence/managed-sources.ts')).addManagedSource(engine,opts);
  await assertUnmanagedCanonicalWriter(engine, 'sources add');
  validateSourceId(opts.id);

  // gbrain#2955: normalize a Git Bash / MSYS drive path (`/c/Users/x`,
  // `/cygdrive/c/x`) to native Windows form BEFORE the overlap check and the
  // INSERT — otherwise the recorded local_path later join-resolves to a
  // phantom `C:\c\Users\x` and sync/write-through silently miss the real
  // directory. Identity on POSIX and for already-native paths.
  if (opts.localPath) {
    // #3696: resolve to ABSOLUTE before the overlap check and the INSERT.
    // A relative `--path .` used to be stored verbatim; every later consumer
    // that runs from a different cwd (launchd daemon at cwd=/, autopilot
    // dispatch, sync anchors) then join-resolved a phantom path and silently
    // missed the real directory.
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- localPath only flows here from the trusted local CLI: the sources_add op hard-rejects `path` unless ctx.remote === false (remote callers get null), so this is the operator registering their own directory; absolutizing it is the #3696 fix
    opts = { ...opts, localPath: resolvePath(msysToNativePath(opts.localPath)) };
  }
  if (opts.cloneDir) {
    // #3696 residual: same phantom-path class as localPath above — a relative
    // `--clone-dir clones/x` was stored verbatim as local_path, so every
    // consumer running from a different cwd (launchd daemon at cwd=/,
    // autopilot dispatch, sync anchors) join-resolved a path that does not
    // exist and silently missed the clone.
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- cloneDir only flows here from the trusted local CLI (sources_add hard-rejects it unless ctx.remote === false); absolutizing the operator's own directory is the #3696 fix
    opts = { ...opts, cloneDir: resolvePath(msysToNativePath(opts.cloneDir)) };
  }
  if (opts.github) {
    // #3696 residual (sibling of the cloneDir case above): `--kind github
    // --dir clones/x` stores opts.github.dir verbatim as local_path (Path C
    // below never resolves it), so the same phantom-path class survives
    // through the github-kind registration path — a launchd daemon at
    // cwd=/, autopilot dispatch, or a sync anchor running from a different
    // cwd than the CLI join-resolves a path that does not exist.
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- opts.github.dir only flows here from the trusted local CLI (sources_add hard-rejects opts.github unless ctx.remote === false); absolutizing the operator's own directory is the #3696 fix
    opts = { ...opts, github: { ...opts.github, dir: resolvePath(msysToNativePath(opts.github.dir)) } };
  }
  if (opts.google) {
    // Same #3696 phantom-path class as the github dir above.
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- opts.google.dir only flows here from the trusted local CLI (sources_add hard-rejects opts.google unless ctx.remote === false); absolutizing the operator's own directory is the #3696 fix
    opts = { ...opts, google: { ...opts.google, dir: resolvePath(msysToNativePath(opts.google.dir)) } };
  }

  // Q4: pre-flight collision check before any clone work.
  const existing = await engine.executeRaw<{ id: string; local_path: string | null }>(
    `SELECT id, local_path FROM sources WHERE id = $1`,
    [opts.id],
  );
  // #3903: attach, don't collide. `gbrain sync --source X` on a path-less
  // source prints "Run: gbrain sources add X --path <path>" — so when the
  // existing row has NO local_path and the caller supplies exactly a --path
  // (no --url, no --kind github), treat this as attaching a working tree to
  // the existing row (non-destructive UPDATE) instead of demanding
  // `sources remove --confirm-destructive`, which cascades page deletion.
  const attachPath =
    existing.length > 0 &&
    existing[0]!.local_path === null &&
    !!opts.localPath &&
    !opts.remoteUrl &&
    !opts.github &&
    !opts.google && !opts.meetings && !opts.slack && !opts.imessage;
  if (existing.length > 0 && !attachPath) {
    const pathNote = existing[0]!.local_path
      ? ` with local_path ${existing[0]!.local_path}`
      : '';
    throw new SourceOpError(
      'source_id_taken',
      `Source id "${opts.id}" is already registered${pathNote}. ` +
        `To replace it, run 'gbrain sources remove ${opts.id} --confirm-destructive' ` +
        `first, then re-add — WARNING: remove permanently deletes every page ` +
        `imported for this source.`,
    );
  }

  // Validate URL before doing any filesystem work.
  let parsedUrl: { url: string; hostname: string } | null = null;
  if (opts.remoteUrl) {
    try {
      parsedUrl = parseRemoteUrl(opts.remoteUrl);
    } catch (e) {
      if (e instanceof RemoteUrlError) {
        throw new SourceOpError('invalid_remote_url', e.message, e);
      }
      throw e;
    }
  }

  // Overlap check for any local path (existing behavior).
  let finalPath = opts.localPath ?? null;
  if (parsedUrl) {
    finalPath = opts.cloneDir ?? defaultCloneDir(opts.id);
  }
  if (finalPath) await assertNoOverlappingPath(engine, opts.id, finalPath);

  // ── Path A: --url (clone + INSERT + rename) ────────────────────────────
  if (parsedUrl) {
    const tempDir = makeTempCloneDir(opts.id);
    mkdirSync(dirname(tempDir), { recursive: true });

    try {
      cloneRepo(parsedUrl.url, tempDir, { skipLfs: opts.addedByRemoteCaller === true });
    } catch (e) {
      // Clone failed before we've touched the DB. tempDir may or may not
      // exist; nuke it just in case.
      rmSync(tempDir, { recursive: true, force: true });
      if (e instanceof GitOperationError) {
        throw new SourceOpError('clone_failed', e.message, e);
      }
      throw e;
    }

    // managed_clone:true is the ownership marker (#1881). It authorizes
    // recloneIfMissing to rm+replace this clone — gbrain created it, here or at
    // a --clone-dir path. A user-tree row (created by an external INSERT, no
    // --url) never carries this, so it can never be deleted by reclone.
    const config: Record<string, unknown> = { remote_url: parsedUrl.url, managed_clone: true };
    config.added_by_remote_caller = opts.addedByRemoteCaller === true;
    if (opts.federated !== null && opts.federated !== undefined) {
      config.federated = opts.federated;
    }
    const displayName = opts.name ?? opts.id;

    try {
      await engine.executeRaw(
        `INSERT INTO sources (id, name, local_path, config)
             VALUES ($1, $2, $3, $4::text::jsonb)`,
        [opts.id, displayName, finalPath, JSON.stringify(config)],
      );
    } catch (e) {
      rmSync(tempDir, { recursive: true, force: true });
      throw new SourceOpError(
        'insert_failed',
        `INSERT failed for source "${opts.id}": ${(e as Error).message}`,
        e,
      );
    }

    // Final step: rename temp dir to final clone path. EXDEV (cross-device
    // rename) is rare on a single-host brain but possible if $GBRAIN_HOME
    // and the temp dir are on different mounts. We don't fall back to
    // recursive copy because the temp dir is in $GBRAIN_HOME by design.
    try {
      mkdirSync(dirname(finalPath!), { recursive: true });
      // Refuse to rename over an existing path. If finalPath exists at this
      // point (race: another process created it between our pre-flight and
      // now), back out cleanly.
      if (existsSync(finalPath!)) {
        throw new Error(`destination ${finalPath} appeared mid-flight`);
      }
      renameSync(tempDir, finalPath!);
    } catch (e) {
      rmSync(tempDir, { recursive: true, force: true });
      // Best-effort DB rollback.
      await engine
        .executeRaw(`DELETE FROM sources WHERE id = $1`, [opts.id])
        .catch(() => {});
      throw new SourceOpError(
        'rename_failed',
        `Could not move clone to final path ${finalPath}: ${(e as Error).message}`,
        e,
      );
    }
  } else if (opts.github) {
    // ── Path C: --kind github (v0.46) ─────────────────────────────────────
    // API-backed source: no git repo, no clone. The managed dir is created
    // here so `sources status` and webhook repo matching work immediately;
    // the materializer populates it on first sync.
    const finalPath = opts.github.dir;
    mkdirSync(finalPath, { recursive: true });
    const config: Record<string, unknown> = {
      kind: 'github',
      gh_token_env: opts.github.tokenEnv,
      gh_handle: opts.github.handle,
      gh_scope: opts.github.scope,
      gh_repos: opts.github.repos.join(','),
      gh_involvement: opts.github.involvement,
      // Ownership marker: the dir is gbrain-managed only when it is the
      // default clone location. A custom --dir points at user-owned
      // storage and must never be deleted by purge.
      gh_managed: finalPath === defaultCloneDir(`${opts.id}-github`),
      // v0.46: a github-kind mirror is a first-class citizen of unqualified
      // reads (search/query/get_page without an explicit source_id). The
      // federated widening in localFederatedSourceIds spans sources with
      // config.federated=true — without this default, a fresh mirror is
      // invisible to search. Explicit --no-federated opts out.
      federated: opts.federated ?? true,
    };
    if (opts.github.appId !== undefined && opts.github.appPemPath !== undefined) {
      config.gh_app_id = opts.github.appId;
      config.gh_app_pem_path = opts.github.appPemPath;
      if (opts.github.appInstallId !== undefined) {
        config.gh_app_install_id = opts.github.appInstallId;
      }
    }
    const displayName = opts.name ?? opts.id;
    await engine.executeRaw(
      `INSERT INTO sources (id, name, local_path, config)
           VALUES ($1, $2, $3, $4::text::jsonb)`,
      [opts.id, displayName, finalPath, JSON.stringify(config)],
    );
  } else if (opts.google) {
    // ── Path D: --kind google (v0.47) ─────────────────────────────────────
    // API-backed source: no git repo, no clone. Credentials live in the
    // vault; config carries only the account POINTER (mirrors gh_token_env
    // storing an env NAME — check:source-config-leak stays trivially green).
    const finalPath = opts.google.dir;
    mkdirPrivate(finalPath);
    const config: Record<string, unknown> = {
      kind: 'google',
      g_account: opts.google.account,
      g_services: opts.google.services.join(','),
      g_history_days: opts.google.historyDays,
      // Only written when non-default so every existing source's config keeps
      // its exact shape (DEFAULT_CALENDAR_ID stays the parse-time fallback).
      ...googleTuningConfig(opts.google),
      // Non-vault access (v0.47): 'command' runs g_token_command locally at
      // sync time (same trust class as recipe health_check argv — the google
      // kind is hard-rejected on remote sources_add and these keys are not
      // reachable over MCP); 'env' reads the env var NAMED here (never a
      // secret value — the gh_token_env pattern).
      ...(opts.google.access && opts.google.access !== 'vault'
        ? { g_access: opts.google.access }
        : {}),
      ...(opts.google.tokenCommand ? { g_token_command: opts.google.tokenCommand } : {}),
      ...(opts.google.tokenEnv ? { g_token_env: opts.google.tokenEnv } : {}),
      g_managed: finalPath === defaultCloneDir(`${opts.id}-google`),
      // Same default as github mirrors: a fresh google source participates
      // in unqualified reads unless --no-federated opts out.
      federated: opts.federated ?? true,
    };
    const displayName = opts.name ?? opts.id;
    await engine.executeRaw(
      `INSERT INTO sources (id, name, local_path, config)
           VALUES ($1, $2, $3, $4::text::jsonb)`,
      [opts.id, displayName, finalPath, JSON.stringify(config)],
    );
  } else if (opts.meetings || opts.slack || opts.imessage) {
    await insertApiSource(engine, opts, opts.imessage ? 'imessage' : opts.slack ? 'slack' : 'meetings');
  } else {
    // ── Path B: --path or no path (existing behavior, pre-v0.28) ─────────
    // #2707: only validate when the path actually exists — a not-yet-created
    // path is a different (pre-existing, out of scope) failure mode, and
    // gating on existsSync keeps this a fail-fast check on the exact bug
    // report ("plain directory accepted, sync fails later") rather than a
    // broader "does this path exist" check nobody asked for.
    //
    // GST-2732: a plain folder outside any git repository registers as a plain
    // directory (sync imports its files without Git, #7973). Inside a
    // repository, hasTrackedContent must hold: isInsideGitRepo alone lets through a `git init`ed-but-never-committed directory (fails
    // sync's "No commits in repo ..."), AND an empty-commit-then-untracked-
    // files directory (git resolves HEAD fine but the tree is empty — the
    // exact silent-staleness footgun #2707(c) describes: sync "succeeds"
    // importing nothing, then never notices the untracked files change).
    // hasTrackedContent's `ls-tree HEAD -- .` catches both (codex round 2).
    if (
      opts.localPath &&
      !opts.force &&
      existsSync(opts.localPath) &&
      inGitCheckout(opts.localPath) &&
      !hasTrackedContent(opts.localPath)
    ) {
      const q = shellQuote(opts.localPath);
      throw new SourceOpError(
        'not_a_git_repo',
        `"${opts.localPath}" is not a git repository with committed, tracked files ` +
          `(or a subdirectory of one). GBrain sync requires every --path source to ` +
          `be git-initialized, with the files actually committed — an empty commit ` +
          `is not enough (the walker reads through git objects, so untracked files ` +
          `stay invisible). Fix: \`git -C ${q} init && git -C ${q} add -A && ` +
          `git -C ${q} commit -m "initial import"\`, then re-run this command. To ` +
          `register it as a plain directory, pass --force: sync then imports its files without Git, and a file removed from it keeps its page.`,
      );
    }
    if (attachPath) {
      // #3903: non-destructive attach — the row already exists (path-less).
      // local_path is set, and an explicitly-passed --name / --federated is
      // applied too (silently dropping them would lie to the caller who
      // typed them). Unmentioned fields, other config keys, and pages all
      // survive. No JSON.stringify into ::jsonb — the federated flag merges
      // via jsonb_build_object on a bound boolean.
      await engine.executeRaw(
        `UPDATE sources
            SET local_path = $2,
                name = COALESCE($3, name),
                config = CASE WHEN $4::boolean IS NULL THEN config
                              ELSE COALESCE(config, '{}'::jsonb)
                                   || jsonb_build_object('federated', $4::boolean) END
          WHERE id = $1`,
        [opts.id, finalPath, opts.name ?? null, opts.federated ?? null],
      );
    } else {
      const config: Record<string, unknown> = {};
      if (opts.federated !== null && opts.federated !== undefined) {
        config.federated = opts.federated;
      }
      const displayName = opts.name ?? opts.id;
      await engine.executeRaw(
        `INSERT INTO sources (id, name, local_path, config)
             VALUES ($1, $2, $3, $4::text::jsonb)`,
        [opts.id, displayName, finalPath, JSON.stringify(config)],
      );
    }
  }

  const created = await fetchSourceRow(engine, opts.id);
  if (!created) {
    throw new SourceOpError(
      'insert_failed',
      `Source "${opts.id}" disappeared after INSERT (concurrent delete?).`,
    );
  }
  return created;
}

// ── resolveDefaultSource ────────────────────────────────────────────────────
//
// v0.34 W0b — canonical helper for CLI commands that take an optional
// --source flag. The contract per the eng review D7:
//   - exactly 1 registered source → return its id (single-source brains,
//     the 80% case; --source flag is unnecessary friction)
//   - 0 sources → throw (no source to scope to)
//   - 2+ sources → throw with the list, forcing the caller to be explicit
//
// Codex finding #7: src/commands/code-callers.ts:54 + code-callees.ts:43
// historically set `allSources: allSources || !sourceId` — which means
// the documented "source-scoped by default" behavior INVERTED to global
// whenever `--source` was omitted. Multi-source brains silently
// cross-contaminated structural retrieval despite the docstring claim.
//
// Helper consolidates the resolution rule so blast/flow/clusters/wiki
// (v0.34 new commands) and code-callers/callees (v0.20.0 retrofit)
// behave identically.

export class SourceResolutionError extends Error {
  constructor(
    message: string,
    public readonly code: 'no_sources' | 'multiple_sources_ambiguous',
    public readonly availableSources: string[],
  ) {
    super(message);
    this.name = 'SourceResolutionError';
  }
}

export async function resolveDefaultSource(engine: BrainEngine): Promise<string> {
  const sources = await listSources(engine);
  if (sources.length === 0) {
    throw new SourceResolutionError(
      'no sources registered; run `gbrain sources add` first',
      'no_sources',
      [],
    );
  }
  if (sources.length === 1) {
    return sources[0]!.id;
  }
  const ids = sources.map((s) => s.id);
  throw new SourceResolutionError(
    `multi-source brain — specify --source from: ${ids.join(', ')}`,
    'multiple_sources_ambiguous',
    ids,
  );
}

/** Result of `resolveScopedSourceOrThrow`: the resolved source id plus the
 * tier that won, so callers can nudge (sole_non_default) or surface the
 * source in their output envelope. */
export interface ScopedSourceResolution {
  source_id: string;
  tier: SourceTier;
}

/**
 * Source scope for the structural-retrieval commands (`code-callers` /
 * `code-callees`) when neither `--source` nor `--all-sources` is given.
 *
 * Runs the FULL 7-tier resolution chain via `resolveSourceWithTier`
 * (flag → env → dotfile → local_path → brain_default → sole_non_default →
 * seed_default), so a `.gbrain-source` pin (or any real signal) selects the
 * source. The multi-source ambiguity guard (`resolveDefaultSource`) is
 * applied ONLY when the chain matched nothing real (tier `seed_default`):
 * 1 source → returns it, 0 → `no_sources` throw, 2+ → `multiple_sources_ambiguous`.
 *
 * Contrast with `resolveSourceId` (silently returns `'default'` and never
 * throws on ambiguity) — this helper deliberately preserves the loud
 * multi-source error when there's genuinely no signal.
 *
 * @throws SourceResolutionError  on a no-signal 0/2+-source brain (seed_default tier).
 * @throws Error ("Source \"…\" not found." / "Invalid …")  on a bad pin / env value
 *         via `assertSourceExists` inside `resolveSourceWithTier` — callers should
 *         surface these as clean usage errors, not uncaught stacks.
 */
export async function resolveScopedSourceOrThrow(
  engine: BrainEngine,
  cwd: string = hookSessionCwd(),
): Promise<ScopedSourceResolution> {
  const resolved = await resolveSourceWithTier(engine, null, cwd);
  if (resolved.tier !== 'seed_default') {
    return { source_id: resolved.source_id, tier: resolved.tier };
  }
  // Nothing in the chain matched → apply the ambiguity guard (may throw).
  const id = await resolveDefaultSource(engine);
  return { source_id: id, tier: 'seed_default' };
}

// ── listSources ─────────────────────────────────────────────────────────────

export async function listSources(
  engine: BrainEngine,
  opts: { includeArchived?: boolean; allowedSourceIds?: readonly string[] } = {},
): Promise<SourceListEntry[]> {
  // v0.28.1 codex finding (MEDIUM): the prior version ignored the
  // includeArchived flag and returned every row. That leaked archived
  // sources' ids, local_paths, and remote_urls to read-scoped MCP callers
  // who shouldn't see soft-deleted state. Filter at the SQL level so the
  // archived rows never reach the wire by default.
  //
  // #4433: `allowedSourceIds` row-filters to the caller's source scope —
  // a scoped remote MCP caller must not enumerate other sources' ids,
  // local_paths, or remote_urls. Row-filter (not field redaction) so
  // out-of-scope rows never reach the wire; an explicit empty array matches
  // nothing (fail-closed); undefined = unscoped (trusted local CLI and
  // internal callers — since wave-L, remote scalar/no-grant callers pass
  // their resolved scope here too instead of arriving unscoped).
  const conds: string[] = [];
  const params: unknown[] = [];
  if (!opts.includeArchived) conds.push('archived IS NOT TRUE');
  if (opts.allowedSourceIds !== undefined) {
    params.push([...opts.allowedSourceIds]);
    conds.push(`id = ANY($${params.length})`);
  }
  const where = conds.length > 0 ? `WHERE ${conds.join(' AND ')}` : '';
  const rows = await engine.executeRaw<{
    id: string;
    name: string;
    local_path: string | null;
    last_sync_at: Date | null;
    config: unknown;
  }>(
    `SELECT id, name, local_path, last_sync_at, config
       FROM sources ${where} ORDER BY (id = 'default') DESC, id`,
    params,
  );
  const out: SourceListEntry[] = [];
  for (const r of rows) {
    const cfg = parseConfig(r.config);
    out.push({
      id: r.id,
      name: r.name,
      local_path: r.local_path,
      remote_url: typeof cfg.remote_url === 'string' ? cfg.remote_url : null,
      federated: cfg.federated === true,
      strategy: isSyncStrategy(cfg.strategy) ? cfg.strategy : null,
      page_count: await countVisiblePages(engine, r.id),
      last_sync_at: r.last_sync_at ? new Date(r.last_sync_at).toISOString() : null,
    });
  }
  return out;
}

// ── removeSource ────────────────────────────────────────────────────────────

export interface RemoveResult {
  id: string;
  pages_deleted: number;
  clone_removed: boolean;
  clone_path: string | null;
  /** #7646: why a gbrain-managed clone was left on disk (`relative_path`: its stored path names no fixed directory). */
  clone_skipped_reason?: 'relative_path';
  dryRun: boolean;
}

/**
 * Hard-remove a source row + cascade. v0.28 additions:
 *  - protected-id guard for "default"
 *  - clone-cleanup: delete the on-disk clone IFF its resolved path is
 *    confined under $GBRAIN_HOME/clones/. realpath+lstat (not startsWith)
 *    to defeat symlink escape attacks.
 *
 * Soft-delete (archive / restore) lives in destructive-guard.ts and is the
 * preferred path for users; this hard-remove is for the admin operator
 * confirming via --confirm-destructive after the impact preview.
 */
export async function removeSource(
  engine: BrainEngine,
  opts: RemoveSourceOpts,
): Promise<RemoveResult> {
  validateSourceId(opts.id);

  if (opts.id === 'default') {
    throw new SourceOpError(
      'protected_id',
      'Cannot remove the "default" source (it backs the pre-v0.17 brain).',
    );
  }

  if(await managedPersistenceEnabled(engine)){
    const {runManagedSourceLifecycle}=await import('./persistence/source-lifecycle.ts');
    const result=await runManagedSourceLifecycle(engine,{operation:'remove',sourceId:opts.id,confirmDestructive:opts.confirmDestructive||opts.yes,
      dryRun:opts.dryRun,requestId:opts.requestId,expectedIncarnation:opts.expectedIncarnation});
    if(!opts.dryRun)(await import('./persistence/managed-sources.ts')).assertTopologyCommitted(result);
    return {id:opts.id,pages_deleted:Number(result.pages_deleted??0),clone_removed:false,
      clone_path:typeof result.local_path==='string'?result.local_path:typeof result.path==='string'?result.path:null,dryRun:opts.dryRun===true};
  }

  const src = await fetchSourceRow(engine, opts.id);
  if (!src) {
    throw new SourceOpError('not_found', `Source "${opts.id}" not found.`);
  }

  const pageCount = await countAllPages(engine, opts.id);

  if (opts.dryRun) {
    return {
      id: opts.id,
      pages_deleted: pageCount,
      clone_removed: false,
      clone_path: src.local_path,
      dryRun: true,
    };
  }


  await assertUnmanagedCanonicalWriter(engine, 'sources remove');

  // Confirmation gate (caller should usually have already shown the impact
  // preview from destructive-guard.ts).
  if (pageCount > 0 && !opts.confirmDestructive && !opts.yes) {
    throw new SourceOpError(
      'protected_id', // closest existing code; caller can frame as "needs confirm"
      `Refusing to remove source "${opts.id}" with ${pageCount} pages without --confirm-destructive or --yes.`,
    );
  }

  // Decide whether we own the clone dir before removing the row.
  const remoteUrl = getRemoteUrl(src.config);
  const ghCfg = (typeof src.config === 'string' ? JSON.parse(src.config) : (src.config ?? {})) as Record<string, unknown>;
  // v0.46: github-kind mirrors at the default clone location are owned by
  // gbrain (gh_managed marker) and get the same cleanup as --url clones.
  const ghManaged = ghCfg.kind === 'github' && ghCfg.gh_managed === true;
  // v0.47: google-kind mirrors mark g_managed the same way.
  const gManaged = ghCfg.kind === 'google' && ghCfg.g_managed === true;
  const cloneRoot = gbrainPath('clones');
  let cloneRemoved = false;
  let cloneSkippedReason: RemoveResult['clone_skipped_reason'];
  if (!opts.keepStorage && src.local_path && (remoteUrl || ghManaged || gManaged) && !isHostAbsolutePath(src.local_path)) {
    cloneSkippedReason = 'relative_path';
    const cloneDir = defaultCloneDir(opts.id);
    console.error(
      `[gbrain] WARN: clone cleanup skipped for "${opts.id}": its stored local_path "${src.local_path}" is not absolute on this host, so it would name the current directory. ` +
      (existsSync(cloneDir) ? `gbrain's clone directory for this source is ${cloneDir}; delete it by hand if you still want it gone (a later sources add ${opts.id} --url refuses while it holds files).` : 'Delete the clone by hand if you still want it gone.'),
    );
  } else if (
    !opts.keepStorage &&
    src.local_path &&
    (remoteUrl || ghManaged || gManaged) && // only auto-clean when gbrain managed the dir
    isPathContained(src.local_path, cloneRoot)
  ) {
    try {
      // Extra symlink-escape paranoia: lstat the resolved final path; if
      // it's a symlink itself (not just contained under the parent), bail
      // out rather than rm -rf following the link.
      const lst = lstatSync(src.local_path);
      if (lst.isSymbolicLink()) {
        throw new SourceOpError(
          'symlink_escape',
          `Refusing to delete clone at ${src.local_path}: path is a symlink.`,
        );
      }
      rmSync(src.local_path, { recursive: true, force: true });
      cloneRemoved = true;
    } catch (e) {
      if (e instanceof SourceOpError) throw e;
      // Don't fail the whole remove if rmSync had a permission hiccup — log
      // and continue. The DB row deletion is the user-facing operation.
      console.error(
        `[gbrain] WARN: clone cleanup at ${src.local_path} failed: ${(e as Error).message}`,
      );
    }
  }

  await deleteSourceRow(engine, opts.id);

  return {
    id: opts.id,
    pages_deleted: pageCount,
    clone_removed: cloneRemoved,
    clone_path: src.local_path,
    ...(cloneSkippedReason ? { clone_skipped_reason: cloneSkippedReason } : {}),
    dryRun: false,
  };
}

// ── getSourceStatus ─────────────────────────────────────────────────────────

export async function getSourceStatus(
  engine: BrainEngine,
  id: string,
): Promise<SourceStatus> {
  validateSourceId(id);
  const src = await fetchSourceRow(engine, id);
  if (!src) {
    throw new SourceOpError('not_found', `Source "${id}" not found.`);
  }

  // Archived check — sources.config.archived is a forward-compat slot;
  // schema.sql also has dedicated `archived` column post-v0.26.5. Read the
  // column directly via a separate query so we don't need to widen the
  // SourceRow shape just for status.
  const archivedRows = await engine.executeRaw<{ archived: boolean | null }>(
    `SELECT archived FROM sources WHERE id = $1`,
    [id],
  );
  const archived = archivedRows[0]?.archived === true;

  const remoteUrl = getRemoteUrl(src.config);
  const sourceConfig =
    typeof src.config === 'string'
      ? (JSON.parse(src.config) as Record<string, unknown>)
      : ((src.config ?? {}) as Record<string, unknown>);
  let cloneState: SourceStatus['clone_state'] = 'not-applicable';
  if (src.local_path && sourceConfig.kind !== 'github') {
    cloneState = validateRepoState(src.local_path, remoteUrl ?? undefined);
  }

  return {
    id: src.id,
    name: src.name,
    local_path: src.local_path,
    remote_url: remoteUrl,
    federated: isFederated(src.config),
    page_count: await countVisiblePages(engine, id),
    last_sync_at: src.last_sync_at ? new Date(src.last_sync_at).toISOString() : null,
    last_commit: src.last_commit,
    archived,
    clone_state: cloneState,
  };
}

// ── recloneIfNeeded (used by sources.ts restore path) ──────────────────────

/** A source a remote caller added by URL never downloads git-lfs objects: its repository names the LFS endpoint. */
export function lfsDownloadsOff(config: unknown): boolean {
  const parsed = typeof config === 'string' ? (() => { try { return JSON.parse(config) as unknown; } catch { return null; } })() : config;
  return (parsed as Record<string, unknown> | null)?.added_by_remote_caller === true;
}

/**
 * Re-clone a source's remote_url into its local_path if the clone is
 * missing on disk. Used by `gbrain sources restore` after an operator
 * autopurged $GBRAIN_HOME/clones/. Idempotent: returns false (didn't clone)
 * if the clone is already there.
 *
 * Throws SourceOpError on clone failure. Does NOT touch the DB row.
 */
export async function recloneIfMissing(
  engine: BrainEngine,
  id: string,
): Promise<boolean> {
  if(await managedPersistenceEnabled(engine)){
    const src=await fetchSourceRow(engine,id);
    if(!src)throw new SourceOpError('not_found',`Source "${id}" not found.`);
    const remoteUrl=getRemoteUrl(src.config);
    if(!remoteUrl||!src.local_path)return false;
    const binding=await (await import('./persistence/ownership.ts')).getWorktreeBinding(engine,id);
    if(binding?.local_path&&existsSync(binding.local_path)&&validateRepoState(binding.local_path,remoteUrl)==='healthy')return false;
    const {runManagedSourceLifecycle}=await import('./persistence/source-lifecycle.ts');
    const result=await runManagedSourceLifecycle(engine,{operation:'reclone',sourceId:id});
    (await import('./persistence/managed-sources.ts')).assertTopologyCommitted(result);return true;
  }
  await assertUnmanagedCanonicalWriter(engine, 'sources reclone');
  const src = await fetchSourceRow(engine, id);
  if (!src) {
    throw new SourceOpError('not_found', `Source "${id}" not found.`);
  }
  const remoteUrl = getRemoteUrl(src.config);
  if (!remoteUrl || !src.local_path) return false;
  if (!isHostAbsolutePath(src.local_path)) {
    throw new SourceOpError('unmanaged_path',
      `Refusing to re-clone "${id}": its stored local_path "${src.local_path}" is relative, so it would name the current directory. Run gbrain sources set-path ${id} <absolute-directory>, then retry.`);
  }

  const state = validateRepoState(src.local_path, remoteUrl);
  if (state === 'healthy') return false;

  // #1881 ownership guard — abort BEFORE any filesystem op. recloneIfMissing
  // deletes local_path; gbrain may only do that to a clone it created, never a
  // user working tree. A row with remote_url + an unowned local_path (the
  // gstack-orchestrator federated shape) is refused here, loudly, untouched.
  if (!isOwnedClone(src)) {
    throw new SourceOpError('unmanaged_path', unownedHint(src, state));
  }

  // EXDEV-safe atomic reclone. Clone into a SIBLING temp of local_path (not the
  // shared clones/.tmp, which can be on a different mount than a --clone-dir
  // target → EXDEV → "deleted but not recloned"). Then swap: move old aside →
  // move new in → drop old, so local_path is never left missing-and-unrecoverable.
  const parent = dirname(src.local_path);
  mkdirSync(parent, { recursive: true });
  const rand = randomBytes(6).toString('hex');
  const tempDir = join(parent, `.gbrain-reclone-${basename(src.local_path)}-${rand}`);
  try {
    cloneRepo(remoteUrl, tempDir, { skipLfs: lfsDownloadsOff(src.config) });
  } catch (e) {
    rmSync(tempDir, { recursive: true, force: true });
    if (e instanceof GitOperationError) {
      throw new SourceOpError('clone_failed', e.message, e);
    }
    throw e;
  }

  // TOCTOU re-check immediately before the destructive move: re-confirm
  // ownership AND reject a symlink leaf swapped in after the entry check (never
  // rm-rf / rename through a symlink).
  if (!isOwnedClone(src)) {
    rmSync(tempDir, { recursive: true, force: true });
    throw new SourceOpError('unmanaged_path', unownedHint(src, state));
  }
  let aside: string | null = null;
  try {
    if (existsSync(src.local_path)) {
      // Symlink leaf guard: never rename/rm *through* a symlinked leaf — that's
      // the TOCTOU swap-in vector (an attacker plants a symlink at local_path
      // between the entry ownership check and this rename). An owned clone's leaf
      // is a real dir gbrain created; a symlink here means tamper, so fail closed.
      // (Symlinked ANCESTORS are intentionally NOT rejected here: for an owned
      // clone gbrain created the dir at this path — cloneRepo refuses a non-empty
      // dest, so a pre-existing user tree can never become an owned clone — and a
      // realpath-chain check false-positives on ubiquitous system symlinks like
      // macOS /var -> /private/var. The residual DB-trust risk, a forged
      // managed_clone marker on an arbitrary path, is tracked as a TODO and is
      // not closable by a path check.)
      if (lstatSync(src.local_path).isSymbolicLink()) {
        rmSync(tempDir, { recursive: true, force: true });
        throw new SourceOpError(
          'symlink_escape',
          `Refusing to re-clone "${id}": local_path ${src.local_path} is a symlink.`,
        );
      }
      aside = `${src.local_path}.old-${rand}`;
      renameSync(src.local_path, aside); // same fs (sibling) — no EXDEV
    }
    renameSync(tempDir, src.local_path); // same fs — no EXDEV
  } catch (e) {
    // Best-effort restore of the original if the swap left local_path missing.
    if (aside && !existsSync(src.local_path)) {
      try {
        renameSync(aside, src.local_path);
      } catch {
        /* original kept at `aside`; surfaced via the thrown error below */
      }
    }
    rmSync(tempDir, { recursive: true, force: true });
    if (e instanceof SourceOpError) throw e;
    // If the original is still parked at `aside` (restore failed), tell the user
    // exactly where it is — otherwise a "cleanup the failed reclone" reflex would
    // delete their only copy.
    const asideNote =
      aside && existsSync(aside)
        ? ` Your original clone is preserved at ${aside} — restore it manually; do not delete it.`
        : '';
    throw new SourceOpError(
      'rename_failed',
      `Could not move re-cloned repo to ${src.local_path}: ${(e as Error).message}.${asideNote}`,
      e,
    );
  }
  if (aside) rmSync(aside, { recursive: true, force: true });
  return true;
}