Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(import): refuse a managed import once when sync.write_through is off (#7085)

garrytana66686f193ad
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index e43d770ea2..9c79950b75 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -78,6 +78,7 @@ of making a duplicate.
| <a id="recovery_version_unsupported"></a>`recovery_version_unsupported` | `recovery_version_unsupported` (effect `error_code`; head blocker state) | A publication or withdrawal-mirror recovery record on the source's worktree has a version this gbrain does not know: a newer gbrain wrote it. Recovery refused before reading it, so the record, its staged files and the canonical file are exactly as they were; the effect keeps retrying (it never parks) and writes on that worktree wait for it. `gbrain sources writer status` and a stalled sync name it (`effect_recovery` or `request_recovery` with this state) as needing intervention. v0.60.290.0 and older predate this check: they read a version 2 withdrawal-mirror record as version 1 and fail every attempt with `effect_unavailable` (an untyped TypeError) instead, without deleting the record or its staging file. | `fix.next` is `tell_user_to_run` `gbrain upgrade`: upgrade gbrain on the host that owns the source's canonical worktree and restart its serve, sync and worker processes; the upgraded writer finishes the recovery. Verify with `gbrain sources writer status --source <source> --json`. Never delete the record or its staged files, and never transfer the source to an older host to force it through. |
| <a id="segmented_mirror_writer_gate"></a>`segmented_mirror_writer_gate` | effect `error_code`, then the parked target's code (`targets_parked`) | A withdrawal (`forget`, `forget_fact`, `purge_fact`) on a page stored in segments committed, but a gbrain older than the segmented writer floor that doctor `segmented_storage` still warns about wrote to the brain in the last 7 days: another host, an older `serve` or worker still running on this host, or an older write this build has not matched (doctor names the host and when the hold clears). This host's own writes from before it upgraded, once the upgraded build has made the same kind of write after them (doctor's information case), keep `pages.segmented_storage` off but do not hold the mirror. Its mirror would write a version 2 recovery record that gbrain cannot read (v0.60.290.0 wedges the worktree on it, see [`recovery_version_unsupported`](#recovery_version_unsupported)), so it wrote nothing: the canonical file keeps the withdrawn row, the withdrawal's Git effect waits, and the mirror retries and parks after five attempts like any failed target, so writes on the worktree go on. The refusal names each older host with its version, the kind of write and when it was last seen. | `fix.next` is `tell_user_to_run` `gbrain upgrade` on the named hosts (and a restart of their serve, sync or worker processes). Once those hosts are upgraded and their older writes are 7 days old, the owner retries the parked mirror by itself (checked at most once a minute); the file loses the row and the Git effect commits it. `gbrain sources writer retry-effects <source> --request-id <request>` retries it sooner; it parks again while the hold lasts. |
| `unbound_source` | `owner_unavailable` (`remember`: `unavailable` with `write_error: owner_unavailable`) | On Postgres, a page write or a `remember` about an existing page went to a source that has a checkout path but no canonical owner. It is refused by default because another host may own the files. The same reason appears when the source was bound, or the page gained a canonical file, after a database-only write was accepted, and (as a `source_changed` sync failure) when a canonical file appears at the path of a page written while the source was unbound. | Classic mode: write the file, commit, `gbrain sync --source <source>` (a remote agent asks the user to). Otherwise bind the source (`gbrain sources writer status <source> --json`, then `gbrain sources writer claim <source> --path <checkout> --admin-intent writer_claim --expected-state <admin_state>`), or opt in with `gbrain config set persistence.unbound_write database_only`. Not retryable. See [unbound sources on Postgres](#unbound-sources-on-postgres). |
+| `disabled_by_config` | `owner_unavailable` (`gbrain import` on a managed brain) | `sync.write_through` is off, so a page write records no canonical worktree, and a managed import publishes only through the source's canonical owner. The import refuses once, before it admits any file, and spends no write capacity. | Copy the files into the source's checkout, commit them, then run `gbrain sync --source <id>`. |
| <a id="embedding_zero_norm"></a>`zero_norm`, `non_finite` or `empty_input` | `embedding_zero_norm` | The embedding provider returned a vector with no direction (all zeros, NaN or infinity) for a chunk, or the chunk text was empty. A vector index silently skips such a row, so gbrain refuses to store it. Only that chunk is refused: the page text and every other chunk's vector are saved, and the page is left for `gbrain embed --stale`. It is never retried as a rate limit or network error. | Inspect the named page's chunk text (empty, whitespace- or symbol-only chunks are the usual cause) or the embedding provider, fix it, then run `gbrain embed <slug>` (add `--source <source>` for a non-default source). If normal text also returns zero vectors, the provider or model is broken; check it with `gbrain doctor`. |
| `targets_parked` (doctor: `parked_effects`) | effect `error_code` | A Git backup or withdrawal target failed five times in a row and was set aside so the other pages keep committing. An effect `error_code` of `git_index_stale` means an index lock older than 10 minutes blocks the checkout: `.git/index.lock` in it (`git -C <checkout> rev-parse --git-path index.lock` for a linked worktree). The canonical writer removes such a lock by itself when it can prove no process holds it and no git runs in that checkout, and then retries the effects it parked; the error's `fix` says why it could not prove that (another platform, a container, a network filesystem, or a live git). Otherwise remove it only if no git command is running there, then run the `retry-effects` command. A fresher lock (`git_index_locked`) is retried as contention and never parks. An effect `error_code` of `git_target_pending` means Git still lists a removed page file in the index (on Windows, a program such as a sync watcher, an indexer or antivirus may still hold it open): close that program, check with `git -c core.fscache=false status` on the brain host, then run the `retry-effects` command. It is retried 30 seconds apart and parks after five attempts like other target failures. The page write itself committed; its Git backup or withdrawal is incomplete. Contention, dependency waits, shutdown and transient database errors never count toward the five. | `gbrain sources writer status <source>`, fix the cause it names, preview with `gbrain sources writer retry-effects <source> --request-id <id> --dry-run`, then run it without `--dry-run`. Each run grants one more attempt per parked target; a target that fails again parks again. A target no retry can move (declared `db_only` since, or left in a former canonical worktree) is [settled on proof](#settle-effects) instead. |
| <a id="writer_admin_locked"></a>`writer_admin_locked` | `writer_admin_locked` | The operator set the brain's writer admin lock (`gbrain sources writer lock`), so writer claim, activate, transfer prepare and transfer accept refuse for every caller. Ordinary writes are not affected. | Agents: stop and ask the operator; do not unlock it yourself. The operator runs, on the brain host, `gbrain sources writer unlock`, re-reads `gbrain sources writer status <source> --json`, administers, then `gbrain sources writer lock` again. See the [writer admin lock](../architecture/topologies.md#writer-admin-lock). |
diff --git a/src/commands/import.ts b/src/commands/import.ts
index a0f357626b..0e82650b5c 100644
--- a/src/commands/import.ts
+++ b/src/commands/import.ts
@@ -48,6 +48,7 @@ import { estimateCostFromChars, lookupEmbeddingPrice } from '../core/embedding-p
import { getEmbeddingModel } from '../core/ai/gateway.ts';
import { managedRootMarkerFor } from '../core/persistence/root-registry.ts';
import { readManagedMode } from '../core/persistence/ownership.ts';
+import { writeThroughConfigured } from '../core/persistence/switches.ts';
import { readPageBodyPolicy } from '../core/page-body/limits.ts';
/** Return a refusal when an import target lies outside every admitted root. */
@@ -168,6 +169,20 @@ function symlinkedRootAbort(dirArg: string, dir: string): ImportAbortError {
return new ImportAbortError('managed import refuses a symlinked input root');
}
+/**
+ * #7085: with `sync.write_through` off a page write records no worktree, and a managed import publishes only through
+ * the source's canonical owner, so every file would be admitted and then refused. Refuse once, before any admission.
+ */
+function writeThroughOffAbort(sourceId: string): ImportAbortError {
+ const error = opError('owner_unavailable', 'Managed import publishes through the canonical owner, and sync.write_through is off on this brain.',
+ `Nothing was imported and no write was admitted. Copy the files into source ${sourceId}'s checkout, commit them, then run gbrain sync --source ${sourceId}.`,
+ { detail: 'disabled_by_config', retryable: false, fix: { argv: ['gbrain', 'sync', '--source', sourceId], consent: [], actor: 'agent',
+ why: `Imports the files committed in source ${sourceId}'s checkout; run it after committing them.`, requires_exclusive: false } });
+ console.error(`Error [${error.code}]: ${error.message}`);
+ console.error(`Fix: ${error.suggestion}`);
+ return new ImportAbortError('sync.write_through is off, so a managed import cannot publish', 1, undefined, error);
+}
+
/** A refused source filesystem lock admission: print its code, message and fix, and keep it as the cause. */
function lockAdmissionAbort(dirArg: string, dir: string, error: unknown): ImportAbortError {
const message = error instanceof Error ? error.message : String(error);
@@ -521,6 +536,9 @@ export async function runImport(
const managedImport = await readManagedMode(engine);
if (managedImport && dir !== resolve(dirArg)) throw symlinkedRootAbort(dirArg, dir);
+ if (managedImport && !opts.managedBookmark && !currentCompanyBrainSync(sourceId) && !writeThroughConfigured(await engine.getConfig('sync.write_through'))) {
+ throw writeThroughOffAbort(sourceId ?? 'default');
+ }
const singleFile = managedImport && lstatSync(dir).isFile();
const importRoot = singleFile ? dirname(dir) : dir;
diff --git a/test/import-write-through-off-7085.test.ts b/test/import-write-through-off-7085.test.ts
new file mode 100644
index 0000000000..0c21aaf709
--- /dev/null
+++ b/test/import-write-through-off-7085.test.ts
@@ -0,0 +1,95 @@
+/**
+ * #7085: a managed `gbrain import --source <id>` on a brain with
+ * `sync.write_through=false` admitted every file as a write request (spending
+ * write capacity) that its publication then refused with `owner_unavailable`:
+ * the admission records no worktree when write-through is off, and a managed
+ * import publishes only through the source's canonical owner.
+ *
+ * Git is the parent, so import does not fall back to writing the database
+ * first. Protects: the import refuses once, before its per-file loop, with a
+ * typed refusal (`owner_unavailable`, `detail: disabled_by_config`, not
+ * retryable) whose fix names the supported path (commit the files, then
+ * `gbrain sync --source <id>`); it admits no write request and spends no write
+ * capacity. With write-through on, the same import still lands.
+ * Seams: none; PGLite always, Postgres when DATABASE_URL is set.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { OperationError } from '../src/core/ops/contract.ts';
+import { claimWorktree } from '../src/core/persistence/ownership.ts';
+import { registerLocalWriter } from '../src/core/persistence/identity.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+import { ImportAbortError, runImport } from '../src/commands/import.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { withEnv } from './helpers/with-env.ts';
+
+const home = mkdtempSync(join(tmpdir(), 'gbrain-import-7085-'));
+const engines: BrainEngine[] = [];
+let closePostgres: (() => Promise<void>) | undefined;
+const env = { GBRAIN_HOME: home, OPENAI_API_KEY: undefined, VOYAGE_API_KEY: undefined, ANTHROPIC_API_KEY: undefined };
+
+beforeAll(async () => {
+ const lite = new PGLiteEngine(); await lite.connect({}); await lite.initSchema(); engines.push(lite);
+ if (process.env.DATABASE_URL) { const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL); engines.push(pg.engine); closePostgres = pg.close; }
+}, 120_000);
+afterAll(async () => {
+ await withEnv(env, async () => {
+ for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
+ await closePostgres?.();
+ });
+ rmSync(home, { recursive: true, force: true });
+});
+
+async function fixture(engine: BrainEngine) {
+ const sourceId = `source-a-${randomUUID().slice(0, 8)}`;
+ const root = join(home, sourceId), input = join(home, `${sourceId}-input`);
+ mkdirSync(root); mkdirSync(input);
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ await engine.executeRaw('INSERT INTO sources(id,name,local_path) VALUES($1,$1,$2)', [sourceId, root]);
+ await registerLocalWriter(engine, 'cli');
+ await claimWorktree(engine, sourceId, root);
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
+ for (const name of ['alpha', 'beta', 'gamma']) writeFileSync(join(input, `${name}.md`), `# ${name}\n\nA synthetic note about acme-example.\n`);
+ return { sourceId, input };
+}
+
+async function captureStderr<T>(fn: () => Promise<T>): Promise<{ value?: T; error?: unknown; stderr: string }> {
+ const lines: string[] = [];
+ const original = console.error;
+ console.error = (...args: unknown[]) => { lines.push(args.map(String).join(' ')); };
+ try {
+ return { value: await fn(), stderr: lines.join('\n') };
+ } catch (error) {
+ return { error, stderr: lines.join('\n') };
+ } finally {
+ console.error = original;
+ }
+}
+
+test('write_through=false: managed import refuses once before admitting any file, naming commit + sync', async () => withEnv(env, async () => {
+ for (const engine of engines) {
+ const f = await fixture(engine);
+ await engine.setConfig('sync.write_through', 'false');
+ try {
+ const run = await captureStderr(() => runImport(engine, [f.input, '--no-embed', '--fresh'], { sourceId: f.sourceId }));
+ expect(await engine.executeRaw('SELECT id FROM persistence_requests WHERE source_id=$1', [f.sourceId])).toHaveLength(0);
+ expect(run.value).toBeUndefined();
+ expect(run.error).toBeInstanceOf(ImportAbortError);
+ const cause = (run.error as ImportAbortError).cause;
+ expect(cause).toBeInstanceOf(OperationError);
+ expect(cause).toMatchObject({ code: 'owner_unavailable', detail: 'disabled_by_config', retryable: false });
+ expect((cause as OperationError).suggestion).toContain(`gbrain sync --source ${f.sourceId}`);
+ expect((cause as OperationError).fix?.argv).toEqual(['gbrain', 'sync', '--source', f.sourceId]);
+ expect(run.stderr.match(/owner_unavailable/g)).toHaveLength(1);
+ expect(run.stderr).toContain(`gbrain sync --source ${f.sourceId}`);
+ } finally {
+ await engine.setConfig('sync.write_through', 'true');
+ }
+ expect(await runImport(engine, [f.input, '--no-embed', '--fresh'], { sourceId: f.sourceId })).toMatchObject({ imported: 3, errors: 0 });
+ }
+}), 120_000);
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index 306d1894d5..1450ca1d45 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -120,6 +120,7 @@ test/import-file-result-callback-gbra130.test.ts
test/import-frontmatter-key-order-5158.test.ts
test/import-inline-chunk-keep.test.ts
test/import-revision-concurrency.test.ts
+test/import-write-through-off-7085.test.ts
test/init-cold-home-embedding.test.ts
test/keyword-statement-timeout-knob-6495.test.ts
test/keyword-timeout-negative-cache-6495.test.ts