Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(repair): keep the approved set when the last approved item throws, so the apply resumes (#8058)

garrytand123662daaec
diff --git a/docs/architecture/key-files/runtime.md b/docs/architecture/key-files/runtime.md
index bbc3cd8fbf..d8a8b735e4 100644
--- a/docs/architecture/key-files/runtime.md
+++ b/docs/architecture/key-files/runtime.md
@@ -25,7 +25,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/mcp-client.ts` — the thin-client transport (trust boundary). `RemoteMcpError`, `extractResponseMeta` and `ignoredRemoteParams` live in `src/core/remote-mcp-error.ts` (re-exported here) so local CLI paths can name them without loading the MCP SDK; the CLI imports this module only on a routed call. `callRemoteTool(config, toolName, args, opts)` with `CallRemoteToolOptions {timeoutMs, signal}`; `buildAbortController` composes an external signal with the timeout, and every request carries `X-Gbrain-Client: gbrain-remote-cli/<version>` so hosts serve it full search/query rows (it never sends `fields`); `buildMcpRequestOptions` forwards `timeoutMs` as the SDK request deadline (otherwise its own 60s default wins); an SDK `RequestTimeout` classifies as `network`/`timeout`, never unreachable. All transport errors normalize to `RemoteMcpError` via the `toRemoteMcpError` funnel: stable `RemoteMcpErrorReason` union, `RemoteMcpErrorDetail.kind` (`'timeout' | 'aborted' | 'unreachable'`) sub-tag, `RemoteMcpErrorDetail.code` carrying server-supplied error codes (e.g. `missing_scope`). A /token 429 is `rate_limited` with `RemoteMcpErrorDetail.retry_after_s` parsed from Retry-After (`parseRetryAfterSeconds` in `remote-mcp-probe.ts`); any other non-auth /token failure is `token`, never `discovery`. `extractToolErrorCode` parses the operation `{error: string, message}` shape as well as legacy envelopes. Mutation arguments retain one request UUID before the first transport attempt, across OAuth refresh and caller retries. Mutation errors retain that UUID and distinguish unknown delivery from requests never submitted; the shared CLI renderer emits same-ID retry guidance without fabricating a receipt. Received pending or terminal error receipts and frozen verb metadata survive deadlines during client cleanup, including the refreshed attempt. Only the locked SDK’s typed `StreamableHTTPError` with numeric code 401 triggers one refresh and reconstructed client; application error text never causes authentication replay. The outer abort signal reaches discovery, minting, initialization, fetch and tool calls, with per-request limits retained and clients closed after failed initialization or abort. `unpackToolResult<T>(res)` parses tool-call JSON content. `ignoredRemoteParams(res)` lists params the host reported ignoring (`_meta.warnings` `unknown_param` entries plus the warning text blocks after `content[0]`); the CLI fails when a sent scope param (`source_id`, `all_sources`) is among them and warns for other ignored params the op declares. Access tokens are cached in process and in `src/core/remote-token-cache.ts`: one 0600 file per key under `remote-tokens/` in the gbrain home, shared by every CLI process, keyed by a hash of issuer, MCP URL, client id and secret, holding only the bearer and its expiry (30 s before the host's), written by atomic rename, read through an `O_NOFOLLOW` descriptor whose `fstat` must show this user and no group/other bits (otherwise deleted); an HTTP 401 drops the entry. The host authorizes every request against the client's current grant, so a cached token never outranks it (`test/thin-client-token-cache-7360.test.ts`). `_clearMcpClientTokenCache({keepDisk})` test escape. The CLI routing seam that consumes this lives in `src/cli.ts` (`runThinClientRouted`); see `docs/architecture/thin-client.md`. Agent contract v1: a tool_error body is `content[0]` alone; `extractToolErrorDetail` keeps `code` (legacy `error`) plus `canonical_code`, `reason`, `why`, `fix`, `notices`, `contract_version`; `RemoteMcpError.toJSON` adds `code` (derived via `canonicalCodeFor` for old servers) and those fields when present; `extractNotices(res)` reads `_meta.gbrain_notices` or prefixed blocks. Skew pinned by `test/thin-client-contract-skew.test.ts` with a frozen v0.60.37.0 parser. A status-only host's 503 `serve_status_only` envelope from OAuth discovery or `/token` (`status_only` on the `remote-mcp-probe.ts` failure, with `retry_after_s`) becomes `RemoteMcpError` detail (`code`, `reason`, `why`, `fix`), which the CLI renders through the agent envelope and the thin-client doctor reports on its check (`test/remote-mcp-status-only.test.ts`).
- `src/core/op-checkpoint.ts` — DB-backed checkpoint primitive for long-running ops. Migration v67 introduces `op_checkpoints (op TEXT, fingerprint TEXT, completed_keys JSONB, updated_at TIMESTAMPTZ, PK(op, fingerprint))`. Per-op fingerprint helpers (`embedFingerprint`, `extractFingerprint`, `reindexFingerprint`, `integrityFingerprint`, `purgeFingerprint`) compute `sha8(canonical-JSON(relevant-params))` so re-running with the same params resumes from `completed_keys` and re-running with different params (e.g. `--limit 100` vs `--limit 200`) starts fresh. Cross-worker safe on Postgres (DB row, no file-lock race); PGLite degrades gracefully. The 7-day TTL GC runs in the cycle's `purge` phase. All writes (`recordCompleted`, `clearOpCheckpoint`) route through `engine.executeRawDirect` + `withRetry(BULK_RETRY_OPTS)` so they survive Supavisor pool exhaustion, and `recordCompleted` returns `boolean` (banked vs failed-after-retries) — the 9 non-sync consumers keep its REPLACE-into-`completed_keys` semantics. Resumable sync uses the additive `appendCompleted(key, deltaKeys)` / `appendCompletedOnce` (the latter no-retry for the SIGTERM path) which INSERT a delta into the `op_checkpoint_paths` child table (migration v115: `(op, fingerprint, path)` PK, FK to `op_checkpoints` ON DELETE CASCADE) via a single writable-CTE `unnest($3::text[])` write — O(delta), never an O(N²) full-set rewrite. `loadOpCheckpoint` returns the `UNION ALL` of legacy `completed_keys` + child-table paths (deduped in JS), so an in-flight upgrade loses nothing. The legacy arm is gated on `jsonb_typeof(completed_keys) = 'array'` so a non-array (scalar) parent row can't make `jsonb_array_elements_text` throw "cannot extract elements from a scalar" and take down the whole union (which would discard the valid child rows and lose all banked progress for the key); a third union arm flags the corruption so the loader logs it once and keeps the child rows. Migration v119 adds the `op_checkpoints_completed_keys_array` CHECK (`jsonb_typeof(completed_keys) = 'array'`) — a DB-enforced, always-on guard that makes the scalar-corruption class structurally impossible going forward; the migration repairs any pre-existing scalar to `'[]'` under `LOCK TABLE ... IN SHARE ROW EXCLUSIVE MODE` and `src/core/schema-embedded.generated.ts` + `src/core/pglite-schema.ts` ship the same CHECK on fresh installs (a loader hit implies schema drift, a disabled constraint, or an out-of-band writer). `recordCompleted` binds its array through `$3::text::jsonb` (NOT a bare `$3::jsonb`) so postgres.js `.unsafe()` doesn't double-encode `JSON.stringify(sorted)` into the scalar string that CHECK rejects (PGLite parses it silently, so only real Postgres surfaces the bug). A DATABASE_URL-gated `test/e2e/op-checkpoint-jsonb-parity.test.ts` (its own CI job) asserts the array shape on real Postgres. `syncFingerprint({sourceId, lastCommit})` keys the sync rows. Pinned by `test/op-checkpoint.test.ts` (incl. delta-append, union read, cascade clear, durable-write boolean, and the scalar-parent guard). `import-checkpoint.ts` stays a separate file-backed checkpoint — both systems coexist without conflict (unifying them would mean async-propagating the four sync call sites in `src/commands/import.ts`; deferred). TTL cleanup preserves unresolved managed cursors, their manifests and failure observations; a completed full cursor does not hide a different failed incremental cursor. Unfinished `managed-atoms` and `managed-atoms-generation` checkpoints survive ordinary seven-day GC so accepted output/retry state is not silently forgotten. Git sync holds (`sync-hold`), their per-source summary while it counts any, `sync-hold-retry` requests, `sync-import-provenance` rows, the blocked-cursor conversion log, the #6188 fence census (`fence-candidate`, `fence-scan`) and paid fence-repair attempt claims and memos (`fence-repair-attempt`) of a live source incarnation survive GC (they leave on resolution; a retired incarnation's rows age out), and `connector-hold-retry` requests and `stuck-recovery-resolution` audit entries (`gbrain repair stuck-recovery`) never expire.
-- `src/core/persistence/preview-approval.ts` — preview-bound approval shared by `jobs authorize-legacy --select`, `jobs cancel --select`, `repair stale-atoms`, `repair extractor-facts` and the other preview-bound repair kinds such as `repair ontology-facts` (fix wave 5, ENG-O1). `previewHash(parts)` is SHA-256 over key-sorted JSON, byte-identical to `authorityDigest`; `saveApprovedSet` / `loadApprovedSet` / `clearApprovedSet` keep the approved items in `op_checkpoints` (`op='repair-approval'`, fingerprint `<command>:<hash>`). A missing, foreign, malformed or older-than-`APPROVAL_MAX_AGE_DAYS` (7, the purge TTL) set refuses whole with `preview_changed`. Tests: `test/preview-approval.test.ts` (PGLite; Postgres via `test/e2e/preview-approval-postgres.test.ts`). #6351: `loadApprovedSet` takes an optional lazy `emptyHash` (the hash a preview of the same selection prints when it finds nothing, from current state including source incarnations); with no saved row and a matching hash it returns an empty set, so the apply command an empty preview prints succeeds while a changed incarnation still refuses `preview_changed`. The eight preview-bound repair kinds without a local `emptyPlanHash` (stale-atoms, captured-facts, conversation-labels, extractor-facts, failed-writes, frontmatter, loop-facts, ontology-facts) pass it. Pinned by `test/repair-empty-preview-apply.test.ts`.
+- `src/core/persistence/preview-approval.ts` — preview-bound approval shared by `jobs authorize-legacy --select`, `jobs cancel --select`, `repair stale-atoms`, `repair extractor-facts` and the other preview-bound repair kinds such as `repair ontology-facts` (fix wave 5, ENG-O1). `previewHash(parts)` is SHA-256 over key-sorted JSON, byte-identical to `authorityDigest`; `saveApprovedSet` / `loadApprovedSet` / `clearApprovedSet` keep the approved items in `op_checkpoints` (`op='repair-approval'`, fingerprint `<command>:<hash>`); `retireAfterLastItem` applies one item and clears the set only after the last item returns, so an item that throws keeps it and the printed apply resumes with the same `--expect` (`test/repair-timeline-order.test.ts`). A missing, foreign, malformed or older-than-`APPROVAL_MAX_AGE_DAYS` (7, the purge TTL) set refuses whole with `preview_changed`. Tests: `test/preview-approval.test.ts` (PGLite; Postgres via `test/e2e/preview-approval-postgres.test.ts`). #6351: `loadApprovedSet` takes an optional lazy `emptyHash` (the hash a preview of the same selection prints when it finds nothing, from current state including source incarnations); with no saved row and a matching hash it returns an empty set, so the apply command an empty preview prints succeeds while a changed incarnation still refuses `preview_changed`. The eight preview-bound repair kinds without a local `emptyPlanHash` (stale-atoms, captured-facts, conversation-labels, extractor-facts, failed-writes, frontmatter, loop-facts, ontology-facts) pass it. Pinned by `test/repair-empty-preview-apply.test.ts`.
- `src/core/process-cleanup.ts` — cleanup registry + abnormal-termination handlers (SIGTERM/SIGHUP/SIGPIPE, uncaughtException/unhandledRejection, EPIPE-on-stdout) that release locks before exit. `registerCleanup(name, fn)` returns a deregister handle; `tryAcquireDbLock` auto-registers. `abortOnCleanupPass(name)` wraps that for child work: it returns `{ signal, release }`, the signal aborts when the cleanup pass runs (sync's `git pull` uses it), and `release` deregisters it. `installSignalHandlers()` is idempotent and called from INSIDE cli.ts's `import.meta.main` seam (first statement before `main()`), NOT at module load — installing at import time would leak a process-wide SIGTERM→`process.exit(143)` handler into any process that merely imports cli.ts (a bun test runner would die mid-suite when a test emits a synthetic SIGTERM, misreading rc=143 as an external kill). Spawned/compiled CLI processes are entrypoints, so they still install. Every attached listener ref is recorded so `_resetForTests()` DETACHES them (clearing flags alone would leave the exit(143) listener live on the shared runner). Tests that must emit synthetic signals strip foreign listeners around the emit (see `test/run-child-entry.test.ts`). #5079: `serve --http` (detected by `isHttpServeInvocation` in `src/core/serve-invocation.ts`) installs it with `keepServingOnLogEpipe`, so a closed stdout/stderr pipe (SIGPIPE under Bun, or an EPIPE stream error) drops the log write instead of exiting; stdio `serve` and every other command still exit. Pinned by `test/serve-http-log-epipe.test.ts`. #5062: `registerSignalOwner(name, onSignal)` lets a long-lived command (`jobs supervisor`, `jobs work`) claim SIGTERM/SIGHUP/SIGPIPE and a broken stdout/stderr pipe: while an owner is registered the generic handler only forwards the signal (no cleanup pass, no exit), so the owner can drain while still holding its DB lock and then exit through `triggerCleanupAndExit`; crashes keep the generic path. Pinned by `test/process-cleanup.test.ts` and `test/e2e/supervisor-stop-drain-5062.test.ts`. The signal handler calls `noteInterrupted(signal)` (`read-heartbeat.ts`) before the cleanup pass, except on SIGPIPE.
- `src/core/read-heartbeat.ts` + `src/cli/slow-read.ts` — slow whole-brain reads say what they are doing. A `CliCommandRecord.slowRead(args)` (`src/cli/command-table.ts`) names the read for doctor, sync status, sources status, orphans, anomalies, status and diag; `beginCommandRead` (skipped for `--help` and `--quiet`) wraps the CLI_ONLY dispatch in `src/cli/main.ts` and calls `beginSlowRead`, which prints one stderr start line and an unref'd `still reading` line every `READ_HEARTBEAT_EVERY_MS` (10 s); stdout is untouched. `withReadMeta(doc)` adds `elapsed_ms` and `complete` to a `--json` document and lists `incomplete` (`{field, reason}`) from the markers the documents already carry (`incompleteFields`: a `status: not_read` object, `complete: false` or a `*_complete: false` key, `budget_hit: true`, a doctor check unknown for its budget); an error envelope gets `elapsed_ms` only and an array stays bare. `writeStdoutFinal` (`cli-force-exit.ts`) applies it to a guarded document during a slow read, and orphans, sources status and status call it directly. `noteInterrupted` prints the interrupt line and, under `--json`, writes `{error: 'interrupted', signal, read, elapsed_ms, complete: false}` at once through the writer `cli-force-exit.ts` registers (`setInterruptedDocumentWriter`); a SIGINT handler is installed only when nothing else listens. The fallback document for exits 129, 130 and 143 is `code: 'interrupted'`. Pinned by `test/read-heartbeat-cli.test.ts` (real spawned CLI fixture `test/fixtures/slow-read-cli.ts`: SIGTERM, SIGINT, SIGHUP, SIGKILL after SIGTERM, no `--json`, a kill outside a read) and `test/read-meta-diag.test.ts`.
diff --git a/src/core/persistence/preview-approval.ts b/src/core/persistence/preview-approval.ts
index 6ba5bba4c1..485edbd8c1 100644
--- a/src/core/persistence/preview-approval.ts
+++ b/src/core/persistence/preview-approval.ts
@@ -112,3 +112,10 @@ export async function loadApprovedSet<T>(engine: BrainEngine, key: ApprovedSetKe
export async function clearApprovedSet(engine: BrainEngine, key: Omit<ApprovedSetKey, 'previewCommand'>): Promise<void> {
await engine.executeRaw('DELETE FROM op_checkpoints WHERE op=$1 AND fingerprint=$2', [PREVIEW_APPROVAL_OP, fingerprint(key.command, key.hash)]);
}
+
+/** Applies one approved item and drops the set once the last item returns; an item that throws keeps the set, so the printed apply resumes with the same hash. */
+export async function retireAfterLastItem<T>(engine: BrainEngine, command: PreviewApprovalCommand, hash: string | null | undefined, last: boolean, apply: () => Promise<T>): Promise<T> {
+ const outcome = await apply();
+ if (last && hash) await clearApprovedSet(engine, { command, hash });
+ return outcome;
+}
diff --git a/src/core/repair/accepted-takes.ts b/src/core/repair/accepted-takes.ts
index f13bba4c24..0f3f01e01c 100644
--- a/src/core/repair/accepted-takes.ts
+++ b/src/core/repair/accepted-takes.ts
@@ -36,7 +36,7 @@ import { opError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { stableJson } from '../persistence/digest.ts';
import { submitPageMutation } from '../persistence/page-mutations.ts';
-import { clearApprovedSet, loadApprovedSet, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { materializedSnapshot, segmentedOverCeiling } from '../persistence/segmented-apply.ts';
import { locateOutsideCode } from '../fence-scan.ts';
import { TAKES_FENCE_BEGIN, TAKES_FENCE_END, parseTakesFence, renderTakesFence, type ParsedTake } from '../takes-fence.ts';
@@ -142,11 +142,7 @@ export const acceptedTakesRepair: RepairHandler = {
},
async apply(ctx, entry): Promise<RepairItemOutcome> {
const { take, hash, last } = entry as AcceptedTakeItem;
- try {
- return await restoreTake(ctx.engine, ctx, entry, take);
- } finally {
- if (last) await clearApprovedSet(ctx.engine, { command: 'accepted-takes', hash });
- }
+ return retireAfterLastItem(ctx.engine, 'accepted-takes', hash, last, () => restoreTake(ctx.engine, ctx, entry, take));
},
render(details) {
return [` each restored take: republished from the page version its removal archived; guide: ${details.docs}`];
diff --git a/src/core/repair/fences.ts b/src/core/repair/fences.ts
index 0435930087..92f55c4216 100644
--- a/src/core/repair/fences.ts
+++ b/src/core/repair/fences.ts
@@ -50,7 +50,7 @@ import { dailyLedger, FENCE_REPAIR_LEDGER, nextUtcMidnight } from '../budget/dai
import { pricingSetCommand } from '../budget/no-pricing.ts';
import type { CapSource } from '../consent.ts';
import { sha256 } from '../persistence/digest.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { readGitSourceHolds, recordFenceHoldRepair } from '../persistence/sync-holds.ts';
import { attemptStore } from '../fence-repair/attempts.ts';
import { listFenceCandidates, runFenceCensus, type FenceCandidate } from '../fence-repair/census.ts';
@@ -378,9 +378,8 @@ export const fencesRepair: RepairHandler = {
if (ctx.remote !== false) throw trustedCliRequired('gbrain repair fences writes files and may call a paid model, so it runs only from the trusted local CLI or the maintenance job on the brain host.');
const { entry, hash, last } = raw as FenceItem;
try {
- return await applyFence(ctx, entry, { embed: opts?.embed === true, expect: hash, allowanceUsd: opts?.llmAllowanceUsd, deadline: opts?.deadline, noLlm: opts?.noLlm === true });
+ return await retireAfterLastItem(ctx.engine, 'fences', hash, last, () => applyFence(ctx, entry, { embed: opts?.embed === true, expect: hash, allowanceUsd: opts?.llmAllowanceUsd, deadline: opts?.deadline, noLlm: opts?.noLlm === true }));
} finally {
- if (hash && last) await clearApprovedSet(ctx.engine, { command: 'fences', hash });
if (!hash) await saveRotation(ctx.engine, ROTATION_OP, await rotationBrain(ctx.engine), rotationKey(entry)).catch(() => undefined);
}
},
diff --git a/src/core/repair/frontmatter.ts b/src/core/repair/frontmatter.ts
index c1d1fda76f..0a371fe78e 100644
--- a/src/core/repair/frontmatter.ts
+++ b/src/core/repair/frontmatter.ts
@@ -58,7 +58,7 @@ import { loadRepairBusySet, repairBusy, repairBusyMessage, type RepairBusySet }
import { fenceWhere } from '../fence-repair/refusal.ts';
import type { SyncRename } from '../persistence/sync-discovery.ts';
import { canonicalRepairFields, confinedRepairTarget, managedRepairRoot, prepareRepairPublication, repairScreenConfig, submitManagedFileRepair } from '../persistence/file-repair.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import { materializedSnapshot, segmentedOverCeiling } from '../persistence/segmented-apply.ts';
import { pageBodyOverCeilingError } from '../page-body/page-shape.ts';
@@ -509,8 +509,7 @@ export const frontmatterRepair: RepairHandler = {
},
async apply(ctx, entry, opts): Promise<RepairItemOutcome> {
const { repair, selection, hash, last } = entry as FrontmatterItem;
- try { return await applyRepair(ctx, repair, selection, opts?.embed === true); }
- finally { if (last) await clearApprovedSet(ctx.engine, { command: 'frontmatter', hash }); }
+ return retireAfterLastItem(ctx.engine, 'frontmatter', hash, last, () => applyRepair(ctx, repair, selection, opts?.embed === true));
},
render(details, opts) {
const d = details as unknown as FrontmatterPreviewDetails;
diff --git a/src/core/repair/overwritten-edits.ts b/src/core/repair/overwritten-edits.ts
index 0ed99359c3..824b3f4641 100644
--- a/src/core/repair/overwritten-edits.ts
+++ b/src/core/repair/overwritten-edits.ts
@@ -24,7 +24,7 @@ import { localHostId } from '../persistence/identity.ts';
import { getWorktreeBinding } from '../persistence/ownership.ts';
import { fileMatchesSnapshot } from '../persistence/page-prepare.ts';
import { submitPageMutation } from '../persistence/page-mutations.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { overwriteContent, overwriteDigest, scanOverwrittenEdits, type OverwrittenEdit } from '../persistence/overwritten-edits.ts';
import { readTreeBlobs, readBlobContents } from '../persistence/sync-blobs.ts';
import { syncGit, syncGitPath } from '../persistence/sync-discovery.ts';
@@ -123,11 +123,7 @@ export const overwrittenEditsRepair: RepairHandler = {
},
async apply(ctx, entry): Promise<RepairItemOutcome> {
const { edit, hash, last } = entry as EditItem;
- try {
- return await restoreEdit(ctx, entry, edit);
- } finally {
- if (last) await clearApprovedSet(ctx.engine, { command: 'overwritten-edits', hash });
- }
+ return retireAfterLastItem(ctx.engine, 'overwritten-edits', hash, last, () => restoreEdit(ctx, entry, edit));
},
render(details) {
const lines: string[] = [];
diff --git a/src/core/repair/provenance.ts b/src/core/repair/provenance.ts
index 309ea849cc..eb4e98e1b8 100644
--- a/src/core/repair/provenance.ts
+++ b/src/core/repair/provenance.ts
@@ -19,7 +19,7 @@
*/
import type { BrainEngine } from '../engine.ts';
import { OperationError, opError } from '../ops/contract.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { ownerRepairFile, repairPageMarker, restorePageProvenance } from '../trust/page-handlers.ts';
import { plannedDigest, readPageDrift, scanProvenanceDrift, type DriftItem } from '../trust/provenance-drift.ts';
@@ -153,14 +153,12 @@ export const provenanceRepair: RepairHandler = {
},
async apply(ctx, entry): Promise<RepairItemOutcome> {
const { page, hash, includeAmbiguous, last } = entry as ProvenanceItem;
- try {
+ return retireAfterLastItem(ctx.engine, 'provenance', hash, last, async () => {
if (await stillPlanned(ctx.engine, page, includeAmbiguous) !== 'planned') return { applied: false, outcome: 'changed_since_preview', reason: 'the page changed since the preview' };
const input = { sourceId: page.source_id, slug: page.slug, expectedRevision: page.revision, confirmation: { via: 'preview_hash' as const }, config: ctx.config };
const result = page.action === 'restamp' ? await repairPageMarker(ctx.engine, input)
: await restorePageProvenance(ctx.engine, { ...input, planned: page.planned, includeAmbiguous });
return { applied: true, outcome: page.action === 'restamp' ? 'restamped' : 'restored', detail: { tier: result.tier, prior_tier: result.prior_tier } };
- } finally {
- if (last) await clearApprovedSet(ctx.engine, { command: 'provenance', hash });
- }
+ });
},
};
diff --git a/src/core/repair/rename-identity.ts b/src/core/repair/rename-identity.ts
index 1c4dc4c12b..7c3c370cb3 100644
--- a/src/core/repair/rename-identity.ts
+++ b/src/core/repair/rename-identity.ts
@@ -38,7 +38,7 @@ import { importFile } from '../import-file.ts';
import { movePageIdReferences } from '../page-state/rename-alias.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { lockedBeliefBatch } from '../belief/writers.ts';
import { markBeliefCommits } from '../belief/append.ts';
import { purgedSlug } from '../../commands/sync/rename-collision.ts';
@@ -202,16 +202,14 @@ export const renameIdentityRepair = {
},
async apply(ctx, entry): Promise<RepairItemOutcome> {
const { record, parts, hash } = entry as PairItem;
- try {
+ return retireAfterLastItem(ctx.engine, 'rename-identity', hash, true, async () => {
if (parts.disposition === 'close') {
if (previewHash(await identityRemedyParts(ctx.engine, record, 'close')) !== hash) throw changedSincePreview(record, 'a page of the pair changed');
if (!await settleIdentityDowngrade(ctx.engine, record.old_page_id, 'closed')) throw changedSincePreview(record, 'its record was settled since the preview');
return { applied: true, outcome: 'closed', detail: { old_slug: record.old_slug, purge_hold: 'released' } };
}
return await carryIdentity(ctx.engine, record, hash);
- } finally {
- await clearApprovedSet(ctx.engine, { command: 'rename-identity', hash });
- }
+ });
},
render(details) {
if (Array.isArray(details.pairs)) return [` each pair: preview it by name to carry or close it; guide: ${details.docs}`];
diff --git a/src/core/repair/rows-behind.ts b/src/core/repair/rows-behind.ts
index eb6b226f3a..b2b44ce137 100644
--- a/src/core/repair/rows-behind.ts
+++ b/src/core/repair/rows-behind.ts
@@ -26,7 +26,7 @@ import { sourceContext, type GhostOwner } from '../ghost-pages.ts';
import { acceptedPendingReceipt } from '../persistence/accepted-pending.ts';
import { prepareRepairPublication, repairScreenConfig, submitManagedFileRepair } from '../persistence/file-repair.ts';
import { readBlobs } from '../persistence/git-gap.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { ROWS_BEHIND_DOCS, rowRefusal, scanRowsBehind, type RowBehind } from '../persistence/rows-behind.ts';
import { SYNC_READ_BOUND } from '../persistence/sync-blobs.ts';
import { readGitHold, writeGitHold, type GitHoldRecord } from '../persistence/sync-holds.ts';
@@ -129,11 +129,7 @@ export const rowsBehindRepair: RepairHandler = {
},
async apply(ctx, entry, opts): Promise<RepairItemOutcome> {
const { row, hash, last } = entry as RowItem;
- try {
- return await applyRow(ctx, row, opts?.embed !== false);
- } finally {
- if (last) await clearApprovedSet(ctx.engine, { command: 'rows-behind', hash });
- }
+ return retireAfterLastItem(ctx.engine, 'rows-behind', hash, last, () => applyRow(ctx, row, opts?.embed !== false));
},
render(details) {
return [` checkpoint ${String(details.checkpoint ?? '').slice(0, 12)}; each re-import goes through the managed import of the committed file (no file is written); guide: ${details.docs}`];
diff --git a/src/core/repair/secret-spans.ts b/src/core/repair/secret-spans.ts
index 582201c67f..aac36fa1ab 100644
--- a/src/core/repair/secret-spans.ts
+++ b/src/core/repair/secret-spans.ts
@@ -42,7 +42,7 @@ import { digest } from '../persistence/digest.ts';
import { maintenanceAttribution } from '../persistence/attribution.ts';
import { withCoordinatedWrite, withTrustKeep, withWriteAttribution } from '../persistence/context.ts';
import { readManagedMode } from '../persistence/managed-mode.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { applySegmentedBody, sealSegmentedPage } from '../persistence/segmented-apply.ts';
import { withPageTierKept } from '../trust/fence-append.ts';
import { materializeSegmentedBody, prepareSegmentedBody } from '../page-body/ingest.ts';
@@ -420,7 +420,7 @@ export const secretSpansRepair: RepairHandler = {
const { page, hash, last } = entry as SpanItem;
const rules = resolveSecretRules((entry as SpanItem).rules);
const detail = { spans: spansOf(page), fields: page.fields.length, rules: ruleText(page.rules) };
- try {
+ return retireAfterLastItem(ctx.engine, 'secret-spans', hash, last, async () => {
if ((await receiptsOf(ctx.engine, hash, [page])).has(page.id)) return { applied: true, outcome: 'redacted', detail };
const written = await ctx.engine.transaction(async tx => {
const managed = await readManagedMode(tx, { refusal: { subject: 'repair secret-spans' } });
@@ -459,9 +459,7 @@ export const secretSpansRepair: RepairHandler = {
const residual = await residualScan(ctx.engine, page.source_id, page.slug, rules);
return { applied: true, outcome: 'redacted', detail: { ...detail, projection, embedded, residual: residual.total,
...(residual.total ? { residual_rules: ruleText(residual.rules), residual_stores: ruleText(residual.stores) } : {}) } };
- } finally {
- if (last) await clearApprovedSet(ctx.engine, { command: 'secret-spans', hash });
- }
+ });
},
render(details) {
return ((details.pages ?? []) as PlannedPage[]).flatMap(page => [` ${page.source_id}:${page.slug} (${page.storage}): ${changeDetail(page)}`,
diff --git a/src/core/repair/slug-conflicts.ts b/src/core/repair/slug-conflicts.ts
index 09654ded2e..f7d99567be 100644
--- a/src/core/repair/slug-conflicts.ts
+++ b/src/core/repair/slug-conflicts.ts
@@ -66,7 +66,7 @@ import { dailyLedger, FENCE_REPAIR_LEDGER, nextUtcMidnight } from '../budget/dai
import { pricingSetCommand } from '../budget/no-pricing.ts';
import type { CapSource } from '../consent.ts';
import { sha256 } from '../persistence/digest.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { clearGitHold, readGitHold, readGitSourceHolds, recordContentHoldRepair, recordHoldAttempt, type ContentHoldRepairState, type GitHoldRecord } from '../persistence/sync-holds.ts';
import { rotate, rotationAfter, rotationBrain, rotationKeyOf, saveRotation } from './rotation.ts';
import { confinedRepairTarget, prepareRepairPublication, repairScreenConfig, submitManagedFileRepair } from '../persistence/file-repair.ts';
@@ -533,9 +533,8 @@ export const slugConflictsRepair: RepairHandler = {
if (ctx.remote !== false) throw trustedCliRequired('gbrain repair slug-conflicts writes files and may call a paid model, so it runs only from the trusted local CLI or the maintenance job on the brain host.');
const { entry, hash, last } = raw as ConflictItem;
try {
- return await applyConflict(ctx, entry, { embed: opts?.embed === true, expect: hash, allowanceUsd: opts?.llmAllowanceUsd, deadline: opts?.deadline, noLlm: opts?.noLlm === true });
+ return await retireAfterLastItem(ctx.engine, 'slug-conflicts', hash, last, () => applyConflict(ctx, entry, { embed: opts?.embed === true, expect: hash, allowanceUsd: opts?.llmAllowanceUsd, deadline: opts?.deadline, noLlm: opts?.noLlm === true }));
} finally {
- if (hash && last) await clearApprovedSet(ctx.engine, { command: 'slug-conflicts', hash });
if (!hash) await saveRotation(ctx.engine, ROTATION_OP, await rotationBrain(ctx.engine), rotationKey(entry)).catch(() => undefined);
}
},
diff --git a/src/core/repair/timeline-order.ts b/src/core/repair/timeline-order.ts
index c8b8c58b30..ad13f2306a 100644
--- a/src/core/repair/timeline-order.ts
+++ b/src/core/repair/timeline-order.ts
@@ -30,7 +30,7 @@ import { parseMarkdown, serializePageToMarkdown } from '../markdown.ts';
import { digest } from '../persistence/digest.ts';
import { pendingTimelineRows, storedCanonicalTimeline } from '../persistence/canonical-projections.ts';
import { submitPageMutation } from '../persistence/page-mutations.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { orderTimeline, type TimelineOrderHold } from '../timeline-order.ts';
import { segmentedTimelineNote, segmentedTimelinePages } from './timeline.ts';
import { afterCursor, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairListing, type RepairPlan, type RepairScope } from './core.ts';
@@ -185,7 +185,7 @@ export const timelineOrderRepair: RepairHandler = {
},
async apply(ctx, entry): Promise<RepairItemOutcome> {
const { page, hash, last } = entry as OrderItem;
- try {
+ return retireAfterLastItem(ctx.engine, 'timeline-order', hash, last, async () => {
const requestId = requestIdOf(hash, page);
const [done] = await ctx.engine.executeRaw<{ state: string }>('SELECT state FROM persistence_requests WHERE request_id=$1::uuid', [requestId]);
const detail = { moved: page.moved, duplicates: page.duplicates, sections_joined: page.sections_joined };
@@ -197,8 +197,6 @@ export const timelineOrderRepair: RepairHandler = {
await submitPageMutation(ctx, { operation: 'put_page', params: { slug: page.slug, source_id: page.source_id, content: verdict.content,
expected_revision: snapshot.revision, request_id: requestId } });
return { applied: true, outcome: 'reordered', detail };
- } finally {
- if (last) await clearApprovedSet(ctx.engine, { command: 'timeline-order', hash });
- }
+ });
},
};
diff --git a/src/core/repair/visibility.ts b/src/core/repair/visibility.ts
index e3e03eb769..731fd830cd 100644
--- a/src/core/repair/visibility.ts
+++ b/src/core/repair/visibility.ts
@@ -44,7 +44,7 @@ import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { maintenancePreflight, submitDatabaseMaintenanceIntent } from '../persistence/prepared-maintenance.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { afterCursor, repairRequestId, type RepairHandler, type RepairItem, type RepairPlan, type RepairPlanOptions, type RepairScope, type RepairCursor } from './core.ts';
-import { clearApprovedSet, loadApprovedSet, previewChangedError, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { loadApprovedSet, previewChangedError, previewHash, retireAfterLastItem, saveApprovedSet } from '../persistence/preview-approval.ts';
import { createProgress, startHeartbeat } from '../progress.ts';
import { cliOptsToProgressOptions, getCliOptions } from '../cli-options.ts';
@@ -376,7 +376,7 @@ export const visibilityRepair: RepairHandler = {
async apply(ctx, entry) {
const item = entry as VisibilityItem;
const target = item.target ?? item.cursor;
- try {
+ return retireAfterLastItem(ctx.engine, 'visibility', item.hash, !!item.last, async () => {
if (target.phase === 4) return await applyFactItem(ctx, item, target.id);
const snapshot = await ctx.engine.readPageSnapshot(item.slug, { sourceId: item.source_id });
if (!snapshot || !item.change || Number(snapshot.page.id) !== target.id) return false;
@@ -388,9 +388,7 @@ export const visibilityRepair: RepairHandler = {
content: serializePageToMarkdown(page, snapshot.tags), expected_revision: snapshot.revision,
request_id: await repairRequestId(ctx, 'visibility', item, snapshot.revision) } });
return true;
- } finally {
- if (item.last && item.hash) await clearApprovedSet(ctx.engine, { command: 'visibility', hash: item.hash });
- }
+ });
},
};
diff --git a/test/repair-timeline-order.test.ts b/test/repair-timeline-order.test.ts
index ee26fc6af7..5dd6562d79 100644
--- a/test/repair-timeline-order.test.ts
+++ b/test/repair-timeline-order.test.ts
@@ -113,6 +113,29 @@ for (const backend of testBackends()) {
await expect(apply(second.preview_hash!)).rejects.toMatchObject({ code: 'preview_changed' });
}, { databaseUrl, setup: gitRoot }), 180_000);
+ test('#8058: a last item that throws keeps the approved set, so the printed apply resumes with the same --expect', () => managedBrain(async ({ engine, ctx }) => {
+ await put(ctx, 'source-a', 'people/carol-example', doc('Carol Example', 'A synthetic person on a database-only source.', CAROL));
+ const scope = await resolveRepairScope(engine, 'source-a');
+ const preview = await (await repairRunner(engine, { apply: false, logger })).run('timeline-order', scope, { explicit: true, sourceFlag: 'source-a' });
+ expect(preview.affected).toBe(1);
+ let fail = true;
+ const flaky = new Proxy(engine, { get(target, key) {
+ if (key === 'executeRaw') return (sql: string, params?: unknown[], o?: unknown) => {
+ if (fail && sql.startsWith('SELECT state FROM persistence_requests WHERE request_id=$1::uuid')) { fail = false; throw new Error('synthetic connection reset'); }
+ return target.executeRaw(sql, params, o as never);
+ };
+ const value = Reflect.get(target, key, target);
+ return typeof value === 'function' ? value.bind(target) : value;
+ } }) as BrainEngine;
+ const apply = (on: BrainEngine) => repairRunner(on, { apply: true, logger }).then(runner => runner.run('timeline-order', scope,
+ { explicit: true, sourceFlag: 'source-a', expect: preview.preview_hash! }));
+ await expect(apply(flaky)).rejects.toThrow('synthetic connection reset');
+ expect(await timelineOf(engine, 'source-a', 'people/carol-example')).toBe(CAROL);
+ const resumed = await apply(engine);
+ expect(resumed).toMatchObject({ applied: 1, complete: true, outcomes: { reordered: 1 } });
+ await expect(apply(engine)).rejects.toMatchObject({ code: 'preview_changed' });
+ }, { databaseUrl, setup: gitRoot }), 180_000);
+
test('--slug narrows the preview and its hash; a page whose database-only rows the write would materialize is kept', () => managedBrain(async ({ engine, ctx }) => {
await put(ctx, 'default', 'people/alice-example', doc('Alice Example', 'Alice Example is a synthetic person.', ALICE));
await put(ctx, 'default', 'people/dana-example', doc('Dana Example', 'A synthetic person.', CAROL));