Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(record-origin): clear a lock-down key's values with --unset-all before writing it, so the CLI flag registry does not change

garrytanab96618c8c69
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a4a09d3fc9..21e0a4b78e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ identifiers and attribution are available in the pre-removal Git revision
### Itemized changes
-- `src/core/url-source-origin.ts`: on a managed brain each apply runs inside `withTopologyLocks` and `lockTopologyRows` (a held lock or a running refresh refuses `source_busy`); `--remote --apply` writes the clone-time lock-down (`lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`) into the checkout's `.git/config` with `git config --file` before the row, into the repository's shared config (`--git-common-dir`, so a linked worktree is covered), then reads back the values Git uses there and refuses `write_failed`, naming the key, when a worktree-scoped or included setting overrides one; a source already recorded as remote whose checkout lacks the lock-down gets it (`recorded`, with no `lfs_tracked` refusal even when its files now use git-lfs), and one that has it stays `already_recorded`; each key is written with `--replace-all`, so one that holds several values gets the one clone-time value; a throw is reported per id as `write_failed`, saying whether the checkout already got all or part of the lock-down, and the batch continues. The committed-attributes read splits each `ls-tree -z` record at its first tab, reads only blobs, and ignores comment lines; a declared-only filter refuses `lfs_tracked` with its own wording. An unborn HEAD with an empty index counts as no committed attributes. The top-level comparison realpath-normalizes both sides. `lfs_unknown` reasons name the cause from Git's own error: checkout missing, not its own repository's top level (an enclosing repository, or none), owned by another user (`safe.directory`), or a Git read failed (for example a corrupt `.git`).
+- `src/core/url-source-origin.ts`: on a managed brain each apply runs inside `withTopologyLocks` and `lockTopologyRows` (a held lock or a running refresh refuses `source_busy`); `--remote --apply` writes the clone-time lock-down (`lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`) into the checkout's `.git/config` with `git config --file` before the row, into the repository's shared config (`--git-common-dir`, so a linked worktree is covered), then reads back the values Git uses there and refuses `write_failed`, naming the key, when a worktree-scoped or included setting overrides one; a source already recorded as remote whose checkout lacks the lock-down gets it (`recorded`, with no `lfs_tracked` refusal even when its files now use git-lfs), and one that has it stays `already_recorded`; each key's existing values are removed before its one value is written, so one that holds several values gets the one clone-time value; a throw is reported per id as `write_failed`, saying whether the checkout already got all or part of the lock-down, and the batch continues. The committed-attributes read splits each `ls-tree -z` record at its first tab, reads only blobs, and ignores comment lines; a declared-only filter refuses `lfs_tracked` with its own wording. An unborn HEAD with an empty index counts as no committed attributes. The top-level comparison realpath-normalizes both sides. `lfs_unknown` reasons name the cause from Git's own error: checkout missing, not its own repository's top level (an enclosing repository, or none), owned by another user (`safe.directory`), or a Git read failed (for example a corrupt `.git`).
- `src/core/hardened-git.ts`: `rev-parse --git-common-dir` joins the read-only allow-list, so the lock-down finds a linked worktree's shared config.
- `src/core/persistence/topology-clone.ts`: a managed clone or reclone takes the source config it clones with from its locked admission read, not from the read before it took its locks.
- `src/core/behavior-change-notice.ts`: one row for the changed `record-origin` behavior.
diff --git a/docs/architecture/key-files/files-and-sync-2.md b/docs/architecture/key-files/files-and-sync-2.md
index 5a389396d2..0808b90b95 100644
--- a/docs/architecture/key-files/files-and-sync-2.md
+++ b/docs/architecture/key-files/files-and-sync-2.md
@@ -29,5 +29,5 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/persistence/sync-entry-fault.ts` — GBRA-133 (#6712 PR 4b): the per-entry faults of a managed sync freeze, so one odd file never stops its source. `nullBytesRefusal` holds a Markdown text with U+0000 `content_null_bytes` (line of the first NUL; a UTF-16 byte order mark says save as UTF-8), from `screenFrozenImport` with holds on and as a typed run stop under `sync.holds=fail`. `committedContentOrMissing` (called by `pinnedContent` when the pinned read fails) imports a committed file whose blob object is gone from working-tree bytes that hash to that blob id, else throws `git_object_missing`; a committed name with U+FFFD that names nothing on disk (a name that is not UTF-8) throws `path_not_utf8` first. `directoryAt` lets a deletion whose name became a directory apply (freeze and the owner's raw-hash check). `freezeFaultHold` is `freezeEntry`'s catch (`sync-run.ts` wraps `freezeEntryOnce`): `git_object_missing` and `path_not_utf8` are held under their codes; a page-body fault (`PAGE_BODY_FAULT_CODES`: `page_body_segmented`, `page_body_rows_unreadable`, e.g. a segmented page whose segment rows don't cover its body) is held `page_write_failed` with `write_failure.code` set to that code, which `sync status` classifies by the `freeze_page_body_*` rows of `SYNC_FAULT_TABLE`; any other `OperationError` and every run-scoped error (`classifyItemFailure` scope run, connection, statement timeout, lock, back-pressure, abort) rethrows, and an unexpected throw is held `page_write_failed` with `write_failure.origin: 'freeze'` and `request_id: null`, re-tested by every sync until held `HOLD_ATTEMPTS_NEEDS_HUMAN` times; a run with `ITEM_BREAKER_MIN_ITEMS` faults and no more clean freezes than faults is systemic and rethrows.
- `src/core/url-clone.ts` — gbrain-owned `sources add --url` clones (#6946, GBRA-130 C-2). `isOwnedClone` (config `managed_clone` or a `local_path` under the default clone dir) and `defaultCloneDir`; `urlCloneReadOnly` is the one predicate (owned clone on a brain without managed persistence) the fence writer (`fence-write.ts`, `databaseOnlyReason: 'url_clone'`), write-through (`skipped: 'url_clone'`), timeline write-through, unfenced-facts adoption, the empty-fence guard and `sourceMirrorReadOnly` consult, so nothing gbrain writes lands in a checkout it updates with `git pull --ff-only`. `urlClonePullBlock` reads the tracked changes of a clone whose pull failed and returns `pull_blocked_local_changes` with an `ask_user` fix naming the preview `gbrain repair url-clone-fences --source <id>`; `formatUrlClonePullBlock` renders it for sync's stderr (`sync/preflight.ts`) and `cycle.ts` puts it in the sync phase detail as `pull_blocked`. Test: `test/pathological/c2-url-clone-fences.test.ts`.
-- `src/core/url-source-origin.ts`, `src/commands/sources-record-origin.ts` and `src/commands/doctor/checks/url-source-origin.ts` — who added a URL source (`sources.config.added_by_remote_caller`). Both add paths write it (`true` for a remote caller, `false` for the local operator); only an explicit `true` reads as remote. URL sources added before that record existed carry none, and nothing stored tells a remote caller's add from the local operator's (same row, same default clone directory); a clone outside `$GBRAIN_HOME/clones/<id>` (or a `clones/<id>` under an earlier home) proves a local add. A URL clone counts when `isOwnedClone` accepts it, so an unmarked clone at the default directory is listed too. `urlSourcesWithoutOrigin` (read-only) feeds the wave check `url_source_origin` (host-only, `resolution: 'operator'`, `warn` with an `ask_user` fix whose argv is the preview). `recordSourceOrigin(engine, ids, { origin, apply, remote })` backs `gbrain sources record-origin <id>... --remote|--local [--apply] [--json]`: it throws `trusted_local_only` unless `remote === false`, previews unless `apply`, writes `true` (`--remote`) or `false` (`--local`) in one transaction that re-reads the row `FOR UPDATE` and refuses `source_changed` if its path or URL moved; on a managed brain that transaction runs inside `withTopologyLocks` after `lockTopologyRows`, the locks a reclone takes (a held lock refuses the id `source_busy`), and `runManagedSourceClone` takes the config it clones with from its own locked admission read, so a record and a reclone never interleave. `--remote --apply` also writes `LFS_OFF_CLONE_CONFIG` into the repository's shared config (`--git-common-dir`; `git config --file`, not run in the checkout) before the row, reads the effective values back (`lockDownGaps`) and throws when a worktree-scoped or included setting overrides one, and locks down an already-remote source whose checkout lacks it (no git-lfs refusal for it unless Git cannot place the checkout, `lfs_unknown`); each key is written with `--replace-all`; a throw is reported for its id as `write_failed` and the batch continues. It never removes a `true`, and refuses `--remote` for a checkout with any tracked `filter=lfs` path or a committed `.gitattributes` declaring `filter=lfs` outside a comment line (`lfs_tracked`, worded per case; read with `hardenedGitSync` `ls-files -- ':(attr:filter=lfs)'` plus every committed `.gitattributes` blob from `ls-tree -z` records split at their first tab, then `cat-file`, so clone-local attributes cannot hide one, and read again under the locks), or one it cannot inspect (`lfs_unknown`, whose reason names the cause: checkout missing, not its own repository's top level by a realpath comparison, owned by another user (`safe.directory`), or a Git read failed), because a lock-down reclone would not match the stored writer manifest there. An unborn HEAD with an empty index (a clone of an empty repository) has no committed attributes and passes. Without git-lfs files the tracked bytes are the same, so no manifest is written. Pinned by `test/url-source-origin.test.ts` (PGLite and Postgres).
+- `src/core/url-source-origin.ts`, `src/commands/sources-record-origin.ts` and `src/commands/doctor/checks/url-source-origin.ts` — who added a URL source (`sources.config.added_by_remote_caller`). Both add paths write it (`true` for a remote caller, `false` for the local operator); only an explicit `true` reads as remote. URL sources added before that record existed carry none, and nothing stored tells a remote caller's add from the local operator's (same row, same default clone directory); a clone outside `$GBRAIN_HOME/clones/<id>` (or a `clones/<id>` under an earlier home) proves a local add. A URL clone counts when `isOwnedClone` accepts it, so an unmarked clone at the default directory is listed too. `urlSourcesWithoutOrigin` (read-only) feeds the wave check `url_source_origin` (host-only, `resolution: 'operator'`, `warn` with an `ask_user` fix whose argv is the preview). `recordSourceOrigin(engine, ids, { origin, apply, remote })` backs `gbrain sources record-origin <id>... --remote|--local [--apply] [--json]`: it throws `trusted_local_only` unless `remote === false`, previews unless `apply`, writes `true` (`--remote`) or `false` (`--local`) in one transaction that re-reads the row `FOR UPDATE` and refuses `source_changed` if its path or URL moved; on a managed brain that transaction runs inside `withTopologyLocks` after `lockTopologyRows`, the locks a reclone takes (a held lock refuses the id `source_busy`), and `runManagedSourceClone` takes the config it clones with from its own locked admission read, so a record and a reclone never interleave. `--remote --apply` also writes `LFS_OFF_CLONE_CONFIG` into the repository's shared config (`--git-common-dir`; `git config --file`, not run in the checkout) before the row, reads the effective values back (`lockDownGaps`) and throws when a worktree-scoped or included setting overrides one, and locks down an already-remote source whose checkout lacks it (no git-lfs refusal for it unless Git cannot place the checkout, `lfs_unknown`); each key's existing values are removed before its one value is written; a throw is reported for its id as `write_failed` and the batch continues. It never removes a `true`, and refuses `--remote` for a checkout with any tracked `filter=lfs` path or a committed `.gitattributes` declaring `filter=lfs` outside a comment line (`lfs_tracked`, worded per case; read with `hardenedGitSync` `ls-files -- ':(attr:filter=lfs)'` plus every committed `.gitattributes` blob from `ls-tree -z` records split at their first tab, then `cat-file`, so clone-local attributes cannot hide one, and read again under the locks), or one it cannot inspect (`lfs_unknown`, whose reason names the cause: checkout missing, not its own repository's top level by a realpath comparison, owned by another user (`safe.directory`), or a Git read failed), because a lock-down reclone would not match the stored writer manifest there. An unborn HEAD with an empty index (a clone of an empty repository) has no committed attributes and passes. Without git-lfs files the tracked bytes are the same, so no manifest is written. Pinned by `test/url-source-origin.test.ts` (PGLite and Postgres).
- `src/core/write-through.ts` — shared atomic disk write-through for the canonical ingestion path. `resolvePageWriteTarget(engine, slug, sourceId, { includeDeleted? })` (active rows by default; `includeDeleted: true` resolves a tombstone's recorded `source_path` for the purge remediation retry) is the exported single source of truth for the ONE file a (source, slug) pair lives in on disk: a source with its own `local_path` writes at that tree's ROOT (never nested under `.sources/`); a source without one nests under the host repo (`sync.repo_path`, default at root, non-default under `.sources/<id>/`) unless that path is another source's own working tree (leak guard → `source_repo_belongs_to_other_source`; a live source whose `local_path` is relative counts as owning every tree, and a relative `local_path` or `sync.repo_path` target is `repo_not_found`); the page's recorded `source_path` (or a contained absolute `file://` `source_uri`; a relative or host-only `file://` names no local file and is read as absent) is preferred over a slug-derived name so writes land in the file of record instead of minting a twin; and `isWriteTargetContained` rejects hostile rows escaping the tree (`path_escapes_source_root`). The ok-result also carries `sourcePathToBind` — the target expressed in the file scanner's `source_path` convention for the source's pinned `slug_root_mode` (or the mode its first sync would pin, via `scannerSlugRootMode`): GIT-ROOT-relative under `git-root` when the scan root sits inside a git repo, scan-root-relative under `source-root` and for non-git or git-root scan roots, so a put-born page binds the same form managed sync and delete-reconcile key on. Every recorded-path reader (write targets, takes, reconcile, audit, export restore, doctor) decodes with the same mode (`resolveSourceLocalFilePath(..., slugRootMode)`): under `source-root` the scope prefix is removed only from the legacy Git-root form whose remainder names the page slug, and basename rows resolve under the unstripped slug directory. The resolver is shared by `writePageThrough`, the facts fence writer (`src/core/facts/fence-write.ts`), and fence forget (`src/core/facts/forget.ts`) — the fence appends to the page's file, so all writers MUST compute the identical path or the fence lands in a file sync never reads back and the next extract_facts reconcile deletes the fence-owned DB rows. `writePageThrough(engine, slug, {sourceId?, frontmatterOverrides?, inlineOnly?, logger?, expectedFileBytes?, deferCommit?})` resolves the target through it, re-reads the just-written DB row (`getPage`), renders an inline page via `serializePageToMarkdown`, and writes the `.md`. A page stored in segments is never rendered whole: its file is measured from its segments at the snapshot's revision (`unreadPageFile`; a page that moved since refuses `revision_conflict`), checked against `PUSH_SCAN_MAX_FILE_BYTES` before `source_path` is bound (a body already over the cap by `body_bytes` is refused without streaming), streamed through `stageStreamedContent` on the engine it was given (so a caller inside a transaction works) keeping the existing file's mode, and renamed over the target after the file-changed check; `frontmatterOverrides` on such a page return an error result, and `inlineOnly` (the derived writer) skips it as `segmented_page` so the brain has a committable artifact that round-trips through `gbrain sync`. Rendering from the row keeps the serialized content consistent at write time. The fsync-backed `atomicWriteFileSync` stages and renames the file after required source-path bookkeeping; lock/lease checks run before publication. `put_page` holds the root lock before importing and invokes write-through inside its database transaction, so ordinary filesystem rejection rolls back existing content, tags, chunks, and versions. A crash or database COMMIT failure after rename can still leave canonical Markdown ahead of the index; this is not distributed ACID or a durable queue. Never throws — returns `WriteThroughResult { written, path?, content? (the bytes written; inline pages only), skipped?: 'disabled_by_config' | 'url_clone' | 'no_repo_configured' | 'repo_not_found' | 'source_repo_belongs_to_other_source' | 'page_not_found_after_write' | 'path_escapes_source_root' | 'case_insensitive_collision' | 'file_changed' | 'over_push_scan_cap' | 'segmented_page', warning?, error? }` (`file_changed`: the caller's `expectedFileBytes` preimage, null for absent, no longer matches the file under the source filesystem lock, so the file is left untouched) so the caller decides messaging + exit codes. `withNoRepoWriteThroughWarning(result, sourceId)` decorates an unwritten `no_repo_configured` result with `warning` (the write landed only in the database; bind the token/server to a git-backed source or configure `local_path`/`sync.repo_path`); `put_page` applies it for untrusted callers only (`ctx.remote !== false`), so local CLI responses and the `disabled_by_config` operator opt-out stay silent. `isWriteThroughDisabled` (shared with the fence lane, ~30s per-engine cache) honors the `sync.write_through` opt-out. Trust gating (subagent sandbox, dry-run) stays at the CALLER. On a durability-hardened repo (`isDurabilityHardened` — the gbrain post-commit hook is installed, i.e. the user ran `gbrain sources harden`), a successful write is best-effort COMMITTED via `commitWriteThroughFile` (path-limited `git commit -- <file>`, never sweeps unrelated edits; the hook then background-pushes) unless the caller passes `deferCommit` (the derived write-through commits its batch itself, #8073; `deletePageThrough` takes it too) so write-through content reaches git instead of accumulating uncommitted forever; result carries `committed?: boolean`. Unhardened repos keep write-only behavior. `deletePageThrough(engine, slug, {sourceId?, target?, logger?})` is the delete-side sink (sole caller: the `delete_page` op): resolves the same target, unlinks the `.md`, and on a hardened repo best-effort commits the removal path-limited through the same helper with subject `gbrain: delete write-through <slug>`, reporting `committed?: boolean` on `DeleteThroughResult` (absent when unhardened or when the commit did not land — the unlink still stands; a never-committed page leaves nothing to commit, so no empty commit). Pinned by `test/delete-write-through-commit.test.ts`. Consumers: `put_page` op and `gbrain brainstorm/lsd --save` via `persistSavedIdea`. Pinned by `test/write-through.test.ts` + `test/write-through-commit.test.ts`. The `put_page` op is that deciding caller for direct writes: a skip outside the deliberate DB-only set (`no_repo_configured`/`disabled_by_config`/`subagent_sandbox`/`dry_run`) throws `storage_error` inside the import transaction, rolling back the page revision, tags, chunks and version snapshot instead of deleting a just-created row afterward. #6946: on a gbrain-owned `--url` clone of an unmanaged brain (`urlCloneReadOnly`), `writePageThrough` returns `skipped: 'url_clone'` and `deletePageThrough` returns `removed: false, skipped: 'url_clone'`; `timeline-write-through.ts` skips the same way.
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index a8a2e9d0a5..8e054deef6 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -2851,9 +2851,8 @@ A source already recorded as remote whose checkout lacks the lock-down (one
recorded before this) gets it on `--remote --apply` and reports `recorded`,
even when its files now use git-lfs (no `lfs_tracked` refusal for it; only a
checkout Git cannot place refuses it, as `lfs_unknown`); one that has it stays
-`already_recorded`, and the record is never removed. Each setting is written
-with `--replace-all`, so a key that already holds several values ends with the
-one clone-time value.
+`already_recorded`, and the record is never removed. Each setting's existing values are removed before it is written, so a key that
+already holds several values ends with the one clone-time value.
Only `.git/config` changes, never a tracked file; a gbrain frontmatter
hook wired through `core.hooksPath` stops running there, as on any clone a
remote caller adds. `--local` records a local add and changes no checkout, and
diff --git a/src/core/url-source-origin.ts b/src/core/url-source-origin.ts
index 594a861de5..18083b2fb0 100644
--- a/src/core/url-source-origin.ts
+++ b/src/core/url-source-origin.ts
@@ -115,7 +115,8 @@ function lockDownGaps(root: string): string[] {
/**
* Writes the clone-time lock-down (`LFS_OFF_CLONE_CONFIG`) into the repository's shared config (`--git-common-dir`, so a linked
* worktree's repository gets it too), without running Git in the checkout, then reads back what Git uses there and throws when a
- * worktree-scoped or included setting still overrides a key. `progress` says how far it got: `started` before the first write,
+ * worktree-scoped or included setting still overrides a key. Each key's existing values are removed before its one value is
+ * written, so a key that held several ends with the clone-time value. `progress` says how far it got: `started` before the first write,
* `written` once every key is in the file.
*/
function lockDownCheckout(root: string, progress: { state: 'none' | 'started' | 'written' | 'done' }): void {
@@ -123,8 +124,12 @@ function lockDownCheckout(root: string, progress: { state: 'none' | 'started' |
if (!commonDir.ok) throw new Error(`Git could not locate the repository of ${root}.`);
const file = join(resolve(root, commonDir.stdout.toString('utf8').replace(/\n$/, '')), 'config');
progress.state = 'started';
- for (const [key, value] of LOCK_DOWN)
- execFileSync('git', ['config', '--file', file, '--replace-all', key, value], { cwd: dirname(file), env: hardenedGitEnvironment(), stdio: 'pipe', timeout: GIT_LIMITS.timeoutMs });
+ const options = { cwd: dirname(file), env: hardenedGitEnvironment(), stdio: 'pipe', timeout: GIT_LIMITS.timeoutMs } as const;
+ for (const [key, value] of LOCK_DOWN) {
+ try { execFileSync('git', ['config', '--file', file, '--unset-all', key], options); }
+ catch (error) { if ((error as { status?: number }).status !== 5) throw error; }
+ execFileSync('git', ['config', '--file', file, key, value], options);
+ }
progress.state = 'written';
const gaps = lockDownGaps(root);
if (gaps.length) throw new Error(`Git in the checkout at ${root} still reads another value for ${gaps.join(', ')} (a worktree-scoped or included config overrides ${file}).`);
diff --git a/test/url-source-origin.test.ts b/test/url-source-origin.test.ts
index 62b87bf12b..04a63035e2 100644
--- a/test/url-source-origin.test.ts
+++ b/test/url-source-origin.test.ts
@@ -401,7 +401,7 @@ for (const flavor of ['pglite', ...(databaseUrl ? ['postgres'] : [])] as const)
const original = childProcess.execFileSync;
let writes = 0;
const patched = spyOn(childProcess, 'execFileSync').mockImplementation(((file: string, args?: readonly string[], options?: object) => {
- if (file === 'git' && args?.includes('--file') && ++writes === 2) throw new Error('config write failed (example)');
+ if (file === 'git' && args?.includes('--file') && !args.includes('--unset-all') && ++writes === 2) throw new Error('config write failed (example)');
return original(file, args as string[], options as never);
}) as typeof childProcess.execFileSync);
let report: Awaited<ReturnType<typeof recordSourceOrigin>>;