Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { withCompanyBrainSource } from './company-brain/profile.ts';
/**
* Sync anchor + chunker-version state helpers (source-scoped vs legacy
* global-config storage). Peeled out of src/commands/sync.ts (containment
* sprint C13-C14) as a pure move.
*/
import { realpathSync } from 'fs';
import { syncDispatchRow } from './sync-dispatch-read.ts';
import { resolve as pathResolve } from 'path';
import { isHostAbsolutePath } from './path-confine.ts';
import type { BrainEngine } from './engine.ts';
import type { SyncOpts } from '../commands/sync.ts';
import { ownsGlobalSyncAnchor, sameRepoDir } from './sync.ts';
import { isWithinRoot } from './sync-git.ts';
import { serr } from './console-prefix.ts';
import { SOURCE_CONFIG_OBJECT_SQL } from './source-config-sql.ts';
// v0.18.0 Step 5: source-scoped sync state helpers. When opts.sourceId
// is set, read/write the per-source row instead of the global config
// keys. These wrappers centralize the branch so every read/write site
// picks the right storage — future Step 5 work (failure-tracking per
// source) hooks here too.
export async function readSyncAnchor(
engine: BrainEngine,
sourceId: string | undefined,
which: 'repo_path' | 'last_commit',
): Promise<string | null> {
if (sourceId) {
// GBRA-133: inside a CLI sync's routing scope the source's routing row answers the repo path (sync-dispatch-read.ts).
const routing = which === 'repo_path' ? await syncDispatchRow(engine, sourceId) : undefined;
if (routing) return routing.local_path;
const col = which === 'repo_path' ? 'local_path' : 'last_commit';
const rows = await engine.executeRaw<Record<string, string | null>>(
`SELECT ${col} AS value FROM sources WHERE id = $1`,
[sourceId],
);
return rows[0]?.value ?? null;
}
return await engine.getConfig(`sync.${which}`);
}
/**
* #2964: is `repoPath` gbrain's own default-brain anchor, as opposed to a
* path some caller merely happened to pass through unchanged?
*
* `!opts.sourceId` alone is NOT sufficient — and neither is rejecting
* `opts.sourceId` outright: migration `sources_table_additive` (v20)
* seeds a `'default'` source row whose `local_path` is copied FROM
* `config.sync.repo_path` on every brain that has ever run it (i.e.
* effectively all of them by now), and `writeSyncAnchor` keeps that row's
* `local_path` current on every sync thereafter. So on a real installed
* brain, `resolveSourceForDir` (dream cycle) and the CLI's bare `gbrain
* sync` both resolve `sourceId: 'default'`, NOT `undefined` — rejecting
* all non-empty `sourceId` (an earlier, insufficiently-reviewed version
* of this check) made self-heal never fire on that real path either,
* masked in tests only because a freshly-`initSchema()`'d test brain's
* `'default'` row has a null `local_path` (Codex review round 5).
*
* The actual boundary: `'default'` is gbrain's own bootstrap identity,
* not something a caller names — a DIFFERENT, non-default `sourceId` is
* what an explicit `sources add <id> --path <dir>` registration (a
* user's own external directory) looks like, and that's what must keep
* failing loudly. So: permit `sourceId` when it's exactly `undefined` or
* `'default'`, reject any other id, and for BOTH permitted cases prove
* ownership by VALUE — reread the live anchor for that same identity
* (`sources.default.local_path` when sourceId='default', else
* `config.sync.repo_path`) and require the resolved `repoPath` to
* REALPATH-equal it (not raw string equality: `dream`'s `resolveBrainDir`
* normalizes via `path.resolve`, so a trailing slash or `..` in the
* stored anchor must not defeat the match — Codex review round 5, P2).
* An arbitrary caller-supplied path (e.g. an admin-scope
* `submit_job({name:'sync', data:{repoPath}})`) only passes this check
* if it already equals gbrain's own anchor by realpath identity — at
* which point self-healing it is exactly the legitimate case, not an
* escalation.
*
* `opts.srcSubpath` disqualifies unconditionally: a subpath-scoped sync
* only wants THAT subdirectory captured, but the self-heal baseline
* commit runs `git add -A` at the git root (there's no file list yet to
* scope it to — collection happens after this point) — see the P2 review
* finding on `createSyncBaselineCommit`'s callers.
*
* #7630: a relative stored anchor (a legacy `local_path` of ".") proves
* nothing: it realpath-resolves against the process cwd, so it "equals"
* whatever directory the sync runs from. Only an absolute anchor can.
*/
export async function isAnchorOwnedSyncPath(
engine: BrainEngine,
opts: SyncOpts,
repoPath: string,
): Promise<boolean> {
if (opts.srcSubpath) return false;
if (opts.sourceId && opts.sourceId !== 'default') return false;
const anchor = await readSyncAnchor(engine, opts.sourceId, 'repo_path');
if (anchor === null || !isHostAbsolutePath(anchor)) return false;
try {
return realpathSync(anchor) === realpathSync(repoPath);
} catch {
// Anchor or repoPath doesn't realpath-resolve (dangling/nonexistent) —
// can't prove identity, so don't self-heal.
return false;
}
}
export interface SourceAnchorOwnership {
owns: boolean;
/** The path ownership was judged against, or null when the source has no
* directory identity yet (bootstrap allowed). */
configured: string | null;
}
/**
* #4369 — may a sync of `dir` move THIS source's directory anchor
* (`sources.local_path`)? The per-source analog of `ownsGlobalSyncAnchor`,
* one level down: `local_path` is the source's registered directory
* identity, and `writeSyncAnchor`'s per-source branch used to UPDATE it
* unconditionally — an explicit `--source <id>` paired with a foreign
* directory (or a fallback that resolved the wrong dir) silently repointed
* an explicitly-registered source, poisoning put_page write-through and
* that source's incremental anchor. Ownership rules:
* - `'default'` delegates to `ownsGlobalSyncAnchor` (the default source
* IS the brain repo; its identity rules — global key first, then the
* row's local_path, bootstrap only when neither exists — already live
* there, so the two layers cannot drift).
* - any other id: the row's `local_path` when set (realpath-tolerant via
* `sameRepoDir`, so a symlinked/case-variant spelling can't
* false-refuse the source's own directory); a null `local_path`
* bootstraps (first sync of a freshly-registered source).
* Best-effort: a failed row read fails OPEN (a guard bug must never block
* anchor writes — the UPDATE itself surfaces real DB trouble).
*/
export async function ownsSourceSyncAnchor(
engine: BrainEngine,
sourceId: string,
dir: string,
): Promise<SourceAnchorOwnership> {
if (sourceId === 'default') {
return await ownsGlobalSyncAnchor(engine, sourceId, dir);
}
try {
const rows = await engine.executeRaw<{ local_path: string | null }>(
`SELECT local_path FROM sources WHERE id = $1`,
[sourceId],
);
const configured = rows[0]?.local_path ?? null;
if (configured === null) return { owns: true, configured: null };
if (!isHostAbsolutePath(configured)) return { owns: false, configured };
return { owns: sameRepoDir(configured, dir), configured };
} catch {
return { owns: true, configured: null };
}
}
/** Realpath-normalize a directory (the same fallback ladder as
* `sync.ts:sameRepoDir`'s inner norm — resolve, native realpath, realpath,
* else the resolved spelling). */
function normRepoDir(p: string): string {
const abs = pathResolve(p); // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- this resolve IS the ownership guard (#4369): canonicalizes before same-repo containment comparison
try {
return realpathSync.native(abs);
} catch {
// fall through
}
try {
return realpathSync(abs);
} catch {
return abs;
}
}
/** Equal, or nested in EITHER direction after realpath normalization. The
* commit-anchor guard's comparator: a subpath-scoped sync passes the git
* ROOT while the registered `local_path` is the scope root inside it (and a
* nested-repo registration is the mirror shape) — both are the same tree.
* Only two disjoint trees (a foreign repo) fail. */
function sameOrNestedRepoDir(a: string, b: string): boolean {
const na = normRepoDir(a);
const nb = normRepoDir(b);
return na === nb || isWithinRoot(na, nb) || isWithinRoot(nb, na);
}
/**
* Wave-D review (#4369 follow-up) — may a sync running against git root
* `repoDir` advance THIS source's commit-anchor trio (`last_commit` /
* `last_sync_at` / `newest_content_at`)? Deliberately WEAKER than
* `ownsSourceSyncAnchor` (which pins the directory identity itself with an
* equality compare): a subpath-scoped sync legitimately advances the commit
* anchor while the dir it passes (the git root) differs from the registered
* scope root — so containment in either direction is allowed, and only a
* FOREIGN repo (disjoint trees) is refused. Without this, a sync fallback
* that resolved the wrong source (or an explicit `--source` paired with a
* foreign directory) stamps another repo's HEAD into this source's
* incremental anchor, silently skipping every future delta between the
* poisoned hash and reality.
*
* Identity resolution mirrors `ownsGlobalSyncAnchor` for `'default'` (global
* `sync.repo_path` key first, else the row's `local_path`); other ids use the
* row's `local_path`. A null identity bootstraps (first sync of a
* freshly-registered source); #7646: a relative `sync.repo_path` behind a null
* `default` row is a stored identity that proves nothing, so it refuses rather
* than bootstraps. Best-effort: a failed read fails OPEN — a guard bug must
* never block anchor writes.
*/
export async function sourceCommitAnchorAllowed(
engine: BrainEngine,
sourceId: string,
repoDir: string,
): Promise<SourceAnchorOwnership> {
try {
let configured: string | null = null;
let relativeGlobal: string | null = null;
if (sourceId === 'default') {
const globalPath = (await engine.getConfig('sync.repo_path')) || null;
if (globalPath && isHostAbsolutePath(globalPath)) configured = globalPath;
else relativeGlobal = globalPath;
}
if (configured === null) {
const rows = await engine.executeRaw<{ local_path: string | null }>(
`SELECT local_path FROM sources WHERE id = $1`,
[sourceId],
);
configured = rows[0]?.local_path ?? relativeGlobal;
}
if (configured === null) return { owns: true, configured: null };
if (!isHostAbsolutePath(configured)) return { owns: false, configured };
return { owns: sameOrNestedRepoDir(configured, repoDir), configured };
} catch {
return { owns: true, configured: null };
}
}
export async function writeSyncAnchor(
engine: BrainEngine,
sourceId: string | undefined,
which: 'repo_path' | 'last_commit',
value: string,
// v0.41.32.0 (supersedes #1623): on `last_commit` advances, also stamp the
// durable newest-COMMIT timestamp (HEAD committer time, epoch ms) in the SAME
// atomic UPDATE as last_sync_at — no separate write to leave partial state,
// no clock-domain split (last_sync_at = DB now(); newest_content_at = the
// git-intrinsic committer time of the HEAD we just synced). `undefined` keeps
// the legacy 2-column write; `null` clears the column (git unavailable).
newestContentEpochMs?: number | null,
// #2114: the repo dir this anchor write is FOR. Required to guard the
// legacy branch's `last_commit` writes (where `value` is a hash, not a
// dir). `repo_path` writes self-describe via `value`. Callers that omit
// it on a legacy-path last_commit write keep pre-#2114 behavior.
repoDir?: string,
): Promise<void> {
return withCompanyBrainSource(engine, sourceId, async engine => {
if (sourceId) {
const col = which === 'repo_path' ? 'local_path' : 'last_commit';
// last_sync_at bookmarked on every last_commit advance.
if (which === 'last_commit') {
// Wave-D review (#4369 follow-up): guard the commit-anchor trio
// (last_commit / last_sync_at / newest_content_at) too. A foreign
// REPO's HEAD stamped here poisons the incremental anchor — every
// future sync diffs from a hash that isn't in the registered repo's
// history. Same-tree containment (git root vs registered scope root,
// either direction) stays allowed so subpath-scoped syncs keep
// advancing; callers that omit repoDir keep pre-guard behavior (the
// dir is unknown, and a guard that can't see it must not refuse).
if (repoDir !== undefined) {
const { owns, configured } = await sourceCommitAnchorAllowed(engine, sourceId, repoDir);
if (!owns) {
serr(configured !== null && !isHostAbsolutePath(configured)
? `[sync] sources.last_commit for "${sourceId}" not advanced — its stored path "${configured}" is not an ` +
`absolute directory on this host, so it cannot prove "${repoDir}" is its tree. Ask the user which directory ` +
`holds it, then run: gbrain sources set-path ${sourceId} <absolute-directory>`
: `[sync] sources.last_commit for "${sourceId}" not advanced — syncing repo ` +
`"${repoDir}" is neither the registered directory ${configured ?? '(unset)'} nor ` +
`within the same tree. Sync from the registered directory, or re-register the ` +
`source to move it intentionally.`,
);
return;
}
}
if (newestContentEpochMs !== undefined) {
const iso = newestContentEpochMs === null
? null
: new Date(newestContentEpochMs).toISOString();
await engine.executeRaw(
`UPDATE sources SET last_commit = $1, last_sync_at = now(), newest_content_at = $3 WHERE id = $2`,
[value, sourceId, iso],
);
} else {
await engine.executeRaw(
`UPDATE sources SET last_commit = $1, last_sync_at = now() WHERE id = $2`,
[value, sourceId],
);
}
// GBRA-133 PR 2a: the host that advanced a classic source is the one whose resident notifier watches it.
await (await import('./notifier/store.ts')).recordLocalSyncer(engine, sourceId);
} else {
// #4369: repo_path repoints require directory-identity EQUALITY
// (ownsSourceSyncAnchor); last_commit advances above use the weaker
// same-tree containment guard (sourceCommitAnchorAllowed) so
// subpath-scoped syncs — whose git root differs from the registered
// scope root — keep advancing while foreign repos are refused.
const { owns, configured } = await ownsSourceSyncAnchor(engine, sourceId, value);
if (!owns) {
serr(
`[sync] sources.local_path for "${sourceId}" stays at ${configured ?? '(unset)'} — ` +
`not repointing the source at "${value}". Sync from the registered directory, ` +
`or re-register the source to move it intentionally.`,
);
return;
}
await engine.executeRaw(
`UPDATE sources SET ${col} = $1 WHERE id = $2`,
[value, sourceId],
);
}
return;
}
// Legacy no-sourceId path (pre-v0.18 global config; also reached when a
// caller could not resolve a source for the dir — dream --dir on an
// unregistered directory, minion sync with an unmatched repoPath). #2114:
// these globals describe THE brain repo, and this branch used to write
// them unconditionally — a full-sync fallback against a foreign directory
// silently repointed put_page write-through and poisoned the incremental
// anchor. Refuse to move them for a directory that isn't the brain repo.
const anchorDir = which === 'repo_path' ? value : repoDir;
if (anchorDir !== undefined) {
const { owns, configured } = await ownsGlobalSyncAnchor(engine, undefined, anchorDir);
if (!owns) {
serr(
`[sync] sync.${which} stays at ${configured ?? '(unset)'} — not moving the ` +
`global anchor for "${anchorDir}". To make that directory the brain repo: ` +
`gbrain config set sync.repo_path "${anchorDir}"`,
);
return;
}
}
await engine.setConfig(`sync.${which}`, value);
});
}
/**
* v0.20.0 Cathedral II Layer 12 (SP-1 fix) — read/write the chunker version
* last used to sync a given source. When it mismatches CURRENT_CHUNKER_VERSION,
* `performSync` forces a full walk regardless of git HEAD equality. Without
* this gate, bumping CHUNKER_VERSION does NOTHING on an unchanged repo
* because sync short-circuits at `up_to_date` before reaching
* `importCodeFile`'s content_hash check.
*
* Per-source storage matches writeSyncAnchor's shape — sources.chunker_version
* TEXT column from the v27 migration. No global fallback: non-source syncs
* (pre-v0.17 brains with no sources table) never had CHUNKER_VERSION
* version-gating, so they keep the v0.19.0 behavior.
*/
export async function readChunkerVersion(
engine: BrainEngine,
sourceId: string | undefined,
): Promise<string | null> {
if (!sourceId) return null;
const rows = await engine.executeRaw<{ chunker_version: string | null }>(
`SELECT chunker_version FROM sources WHERE id = $1`,
[sourceId],
);
return rows[0]?.chunker_version ?? null;
}
export async function writeChunkerVersion(
engine: BrainEngine,
sourceId: string | undefined,
version: string,
): Promise<void> {
return withCompanyBrainSource(engine, sourceId, async engine => {
if (!sourceId) return;
await engine.executeRaw(
`UPDATE sources SET chunker_version = $1 WHERE id = $2`,
[version, sourceId],
);
});
}
// ─── #4342 — sticky per-source slug-root mode ─────────────────────────────
//
// When a source's local_path is a SUBDIRECTORY of a git repo, sync has two
// possible slug namespaces:
// 'git-root' — slugs carry the subdir prefix (git-diff-path shaped; the
// historical #774 behavior, and the only sane shape when
// the user explicitly scoped with --src-subpath)
// 'source-root' — slugs are local_path-relative (matches what a plain
// `gbrain import <dir>` of the same tree produces)
//
// The choice used to be IMPLICIT (whatever the first sync inferred), and a
// later sync from a different spelling silently re-namespaced every slug.
// The mode is now decided ONCE, persisted (sources.config.slug_root_mode for
// scoped sources, `sync.slug_root_mode` config for the legacy no-source
// path), and every subsequent sync obeys the pin.
export type SlugRootMode = 'git-root' | 'source-root';
function asSlugRootMode(raw: unknown): SlugRootMode | null {
return raw === 'git-root' || raw === 'source-root' ? raw : null;
}
export async function readSlugRootMode(
engine: BrainEngine,
sourceId: string | undefined,
): Promise<SlugRootMode | null> {
if (sourceId) {
const rows = await engine.executeRaw<{ mode: string | null }>(
`SELECT config->>'slug_root_mode' AS mode FROM sources WHERE id = $1`,
[sourceId],
);
return asSlugRootMode(rows[0]?.mode);
}
return asSlugRootMode(await engine.getConfig('sync.slug_root_mode'));
}
export async function writeSlugRootMode(
engine: BrainEngine,
sourceId: string | undefined,
mode: SlugRootMode,
): Promise<void> {
if (sourceId) {
// jsonb_set on a bound ::text — never JSON.stringify into ::jsonb.
//
// #4521: a historical string-scalar (or array-shaped) sources.config made
// the plain `jsonb_set(COALESCE(config, '{}'::jsonb), …)` throw
// `cannot set path in scalar` and abort every subdir-scoped sync right
// after sync.discover_git_root. Heal-on-write instead: coerce the column
// through the canonical SOURCE_CONFIG_OBJECT_SQL recovery expression
// (unwraps double-encoded object strings so their keys SURVIVE; anything
// unrecoverable collapses to '{}') before setting the key.
try {
await engine.executeRaw(
`UPDATE sources
SET config = jsonb_set(${SOURCE_CONFIG_OBJECT_SQL}, '{slug_root_mode}', to_jsonb($2::text))
WHERE id = $1`,
[sourceId, mode],
);
} catch (e) {
// Name the source — "cannot set path in scalar" alone gives the
// operator nothing to act on.
throw new Error(
`failed to pin slug_root_mode on sources.config for source '${sourceId}': ` +
`${e instanceof Error ? e.message : String(e)}`,
e instanceof Error ? { cause: e } : undefined,
);
}
return;
}
await engine.setConfig('sync.slug_root_mode', mode);
}
/** Escape LIKE metacharacters so a slug prefix can't wildcard-match. */
function escapeLike(s: string): string {
return s.replace(/([\\%_])/g, '\\$1');
}
/**
* Resolve (and PIN) the slug-root mode for a scoped sync. Precedence:
* 1. the stored pin (sticky forever — a live install never re-slugs)
* 2. explicit --src-subpath → 'git-root' (the #774 contract: the caller
* named the git root as the slug base)
* 3. auto-pin 'git-root' when existing pages already carry the inferred
* git-root prefix (this install has lived with git-root slugs; flipping
* would strand every page + its links/takes under the old namespace)
* 4. else 'source-root' (local_path-relative — what `gbrain import <dir>`
* of the same tree produces, and the least surprising default)
* The decision is persisted before returning so every later sync agrees.
*
* `slugPrefix` is the SLUGIFIED git-root-relative scope prefix WITHOUT a
* trailing slash (callers derive it via resolveSlugForPath so the probe
* matches slug spelling, not raw path spelling).
*
* `dryRun: true` resolves the mode in-memory only and skips the persist —
* a `sync --dry-run` must never mutate config (#4342 review fix). The pin
* is written by the first REAL sync instead.
*/
export async function resolveSlugRootMode(
engine: BrainEngine,
opts: {
sourceId: string | undefined;
explicitGitRoot: boolean;
slugPrefix: string;
dryRun?: boolean;
},
): Promise<SlugRootMode> {
const stored = await readSlugRootMode(engine, opts.sourceId);
if (stored) return stored;
let mode: SlugRootMode;
if (opts.explicitGitRoot) {
mode = 'git-root';
} else {
const rows = await engine.executeRaw<{ one: number }>(
`SELECT 1 AS one FROM pages
WHERE source_id = $1 AND deleted_at IS NULL AND slug LIKE $2 LIMIT 1`,
[opts.sourceId ?? 'default', `${escapeLike(opts.slugPrefix)}/%`],
);
mode = rows.length > 0 ? 'git-root' : 'source-root';
}
if (opts.dryRun !== true) {
await writeSlugRootMode(engine, opts.sourceId, mode);
}
return mode;
}