Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: pre-landing review fixes (#7679, #7685)
garrytana36534bf8f9c
diff --git a/docs/architecture/key-files/core-persistence-continued.md b/docs/architecture/key-files/core-persistence-continued.mdindex cf1c0448e9..632831415d 100644--- a/docs/architecture/key-files/core-persistence-continued.md+++ b/docs/architecture/key-files/core-persistence-continued.md@@ -4,7 +4,7 @@Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.The #6188 fence check and fence repair live in [fence repair](core-fence-repair.md). Managed connector ingestion, connector item holds and the no-op kernel (checkpoint validation and the fault seams: [request indexes and fault seams](core-persistence-request-indexes.md)). Also the persistence verb types and errors, database-write and manual links, write attribution and loop-fact retirement; the managed purge of deleted pages is under [memory purge](memory-purge.md).-- `src/core/persistence/{worktree-refresh,worktree-refresh-schema}.ts` — `gbrain sources refresh` (F0), the one sanctioned managed Git writer. `persistence_worktree_refreshes` holds one row per refresh with a partial unique index (one active refresh per worktree; its 23505 maps to `refresh_in_progress`). `refreshWorktree` prechecks with no database state (managed, owner host, upstream, no active refresh, no recovery, no unexhausted managed-sync cursor, hardened `git fetch` bounded by `sources.refresh_fetch_timeout_ms`, ancestry, dirty paths intersected with the incoming diff), then: `draining` (inserted under `withTopologyLocks` + `lockTopologyRows`; admission in `journal.ts` refuses `worktree_refreshing` for every request with that `worktree_id`, and `assertManagedSyncAllowed` refuses a managed sync before discovery), poll until no queued/running/recovering request, no queued/running `git`/`withdrawal-mirror` effect and no recovery record remain (else `refresh_drain_timeout`, aborted), `fenced` (both native locks held, rechecked in one transaction; `refreshFenceClear` stops request and effect claims), HEAD verified, dirt rechecked, `git merge --ff-only`, HEAD verified again, then one transaction `merged` + upstream observation + `syncing`; native locks are released and the managed `--no-pull` sync runs per member (only `managed_sync_*` `submit_job` admissions pass during `syncing`); `completed` when every member's `last_commit` is the target or descends from it, or with `outcome.sync_blocked` when a member sync blocks. A per-worktree `refresh-<worktree>.lock` held for the whole run proves liveness: `resumeWorktreeRefreshes` (called from `recoverSourceTopologies`, so on owner start) touches only interrupted `draining`/`fenced`/`merged` rows whose lock is free and applies the section 1.5 table (draining or fenced at the old HEAD abort; HEAD at the verified target moves to `syncing`; anything else is `recovery_required`, which admission refuses with `refresh_recovery_required`). Admission also completes a `syncing` row whose members all reached the target. #7679: each row records its holder (`outcome.holder`: host id, hostname, pid, process start; `previous_holder` after a recovery adopts it). A row whose lock is free is orphaned: `resumeWorktreeRefreshes` (every consumer topology scan) also completes an orphaned `syncing` row once every member's `last_commit` reached the target or a descendant, and a plain `gbrain sources refresh` on the owner host finishes any orphaned non-`recovery_required` row through the `--resume` path (`adoptOrphanedRefresh` + `resumeHeld`) before its own refresh, reporting it as `recovered`. A holder recorded on another host is never adopted. `refreshHolderReport` (writer status `worktree_refreshes`, sync status `worktree_refresh`) names the holder, `liveness` (`live` / `orphaned` / `unknown` off the lock's host, from an instant probe of the refresh lock) and a fix naming `--resume`. `--resume` converges and runs the member syncs; `--abandon` lifts a fence only with HEAD back at the start commit. `gbrain sources writer status` lists active refreshes as `worktree_refreshes` (state, heads, the next command), which the refusal hints point at. Doctor `worktree_refresh_stuck` lists rows active over 15 minutes. CLI body: `src/commands/sources-refresh.ts` (#7685: `--json` prints a refusal's structured fix as the v1 `fix` RenderedAction when it has one, else the legacy command string; `refresh_in_progress` carries the writer-status read); while a resident PGLite owner (`gbrain serve`, stdio MCP) holds the database, `src/commands/sources-refresh-delegate.ts` runs the refresh inside it through the `writer_refresh` administration operation (trusted CLI registration only) and prints the same result or refusal. The consumer's idle probe applies `refreshFenceClear` to effects like the claims, so a fenced worktree's queued effects do not wake it. Tests: `test/persistence-worktree-refresh.test.ts`, `test/persistence-worktree-refresh-restart.test.ts` (child-process crash after merge), `test/worktree-refresh-orphan-7679.test.ts` (SIGKILL mid-syncing, live-holder no-steal), Postgres via `test/e2e/worktree-refresh-postgres.test.ts`, owner delegation in `test/persistence-sync-stdio-owner.test.ts`.+- `src/core/persistence/{worktree-refresh,worktree-refresh-schema}.ts` — `gbrain sources refresh` (F0), the one sanctioned managed Git writer. `persistence_worktree_refreshes` holds one row per refresh with a partial unique index (one active refresh per worktree; its 23505 maps to `refresh_in_progress`). `refreshWorktree` prechecks with no database state (managed, owner host, upstream, no active refresh, no recovery, no unexhausted managed-sync cursor, hardened `git fetch` bounded by `sources.refresh_fetch_timeout_ms`, ancestry, dirty paths intersected with the incoming diff), then: `draining` (inserted under `withTopologyLocks` + `lockTopologyRows`; admission in `journal.ts` refuses `worktree_refreshing` for every request with that `worktree_id`, and `assertManagedSyncAllowed` refuses a managed sync before discovery), poll until no queued/running/recovering request, no queued/running `git`/`withdrawal-mirror` effect and no recovery record remain (else `refresh_drain_timeout`, aborted), `fenced` (both native locks held, rechecked in one transaction; `refreshFenceClear` stops request and effect claims), HEAD verified, dirt rechecked, `git merge --ff-only`, HEAD verified again, then one transaction `merged` + upstream observation + `syncing`; native locks are released and the managed `--no-pull` sync runs per member (only `managed_sync_*` `submit_job` admissions pass during `syncing`); `completed` when every member's `last_commit` is the target or descends from it, or with `outcome.sync_blocked` when a member sync blocks. A per-worktree `refresh-<worktree>.lock` held for the whole run proves liveness: `resumeWorktreeRefreshes` (called from `recoverSourceTopologies` on every consumer topology scan) touches interrupted `draining`/`fenced`/`merged` rows whose lock is free and applies the section 1.5 table (draining or fenced at the old HEAD abort; HEAD at the verified target moves to `syncing`; anything else is `recovery_required`, which admission refuses with `refresh_recovery_required`). Admission also completes a `syncing` row whose members all reached the target. #7679: each row records its holder (`outcome.holder`: host id, hostname, pid, process start; `previous_holder` after a recovery adopts it). A row whose lock is free is orphaned: `resumeWorktreeRefreshes` (every consumer topology scan) also completes an orphaned `syncing` row once every member's `last_commit` reached the target or a descendant, and a plain `gbrain sources refresh` on the owner host finishes any orphaned non-`recovery_required` row through the `--resume` path (`adoptOrphanedRefresh` + `resumeHeld`) before its own refresh, reporting it as `recovered`. A holder recorded on another host is never adopted. `refreshHolderReport` (writer status `worktree_refreshes`, sync status `worktree_refresh`) names the holder, `liveness` (`live` / `orphaned` / `unknown` off the lock's host, from an instant probe of the refresh lock) and a fix naming `--resume`. `--resume` converges and runs the member syncs; `--abandon` lifts a fence only with HEAD back at the start commit. `gbrain sources writer status` lists active refreshes as `worktree_refreshes` (state, heads, the next command), which the refusal hints point at. Doctor `worktree_refresh_stuck` lists rows active over 15 minutes. CLI body: `src/commands/sources-refresh.ts` (#7685: `--json` prints a refusal's structured fix as the v1 `fix` RenderedAction when it has one, else the legacy command string; `refresh_in_progress` carries the writer-status read); while a resident PGLite owner (`gbrain serve`, stdio MCP) holds the database, `src/commands/sources-refresh-delegate.ts` runs the refresh inside it through the `writer_refresh` administration operation (trusted CLI registration only) and prints the same result or refusal. The consumer's idle probe applies `refreshFenceClear` to effects like the claims, so a fenced worktree's queued effects do not wake it. Tests: `test/persistence-worktree-refresh.test.ts`, `test/persistence-worktree-refresh-restart.test.ts` (child-process crash after merge), `test/worktree-refresh-orphan-7679.test.ts` (SIGKILL mid-syncing, live-holder no-steal), Postgres via `test/e2e/worktree-refresh-postgres.test.ts`, owner delegation in `test/persistence-sync-stdio-owner.test.ts`.- `src/core/persistence/git-gap.ts` + `src/commands/sources-git-gap.ts` + `src/commands/doctor/checks/db-ahead-of-git.ts` — git-canonical memory, wave G1 (`docs/designs/GIT_CANONICAL_MEMORY.md#the-git-gap-census`), read-only. `declaredDatabaseOnly` is the one predicate for pages that may not have a tracked file, tested in order: a read-only mirror source, a private page (`isPrivatePage`), an alias-private page (`isDerivationPrivate`), lineage-private (computed in SQL from `privatePagesFilterFragment`), `database_only_reason`, a `storage.db_only` prefix (`isSourceDbOnlySlug`, refusing an invalid gbrain.yml), a never-filed derive-phase page (page-prepare.ts `isNeverFiledDerivedPage`: no `source_path`/`source_uri` under `DERIVE_PHASE_DB_ONLY_DEFAULTS`), a path the checkout's Git ignores (`ignoredPaths`: filter-free `check-ignore -z --stdin`, tracked files never reported, exit 1 = none, null when Git cannot answer). The equality contract compares a committed blob with the page's export view (`readExportPage`, withdrawals overlaid): an inline blob parsed as reconcile parses a canonical file, aligned with the stored type, subtype and #6429 stamp and compared by `reconcileCanonical` digest; a segmented page by the Git blob id of its streamed export. HEAD is read with hardened plumbing only (`readHeadTree`: one `ls-tree -r -l -z --full-tree` under the source's directory; `readBlobs`: `cat-file --batch` in calls of at most 64 MiB) and the working tree by hashing raw bytes (`worktreeBlobOid`), never `git status`/`git diff`, so no repository filter, textconv or fsmonitor runs. `gbrain sources git-gap <id> [--sample n] [--json]` (trusted local CLI, not an MCP op) puts every live page in one state (`equal`, `database_ahead`, `git_ahead` when the sync import record's `blob_oid`/`disk_blob_oid` differs from HEAD, else folded into `database_ahead` and counted in `database_ahead_without_import_record`, `declared_database_only` per class, `undeclared_database_only`, `worktree_only`, `unparseable`, `unsafe_path`), reports the working tree separately, and counts rows with no Git home (unfenced active facts, fenced facts on a missing page or a page without a committed file, links whose `link_source` is not in `DERIVED_LINK_SOURCES`, timeline rows on pages without a file), open `sync-hold` records by code and parked effect targets by kind and code. Each 256-page batch reads in its own read-only transaction. Doctor `db_ahead_of_git` runs the census per non-archived source whose directory is a Git checkout (others are only counted) under `GBRAIN_DOCTOR_GIT_GAP_TIMEOUT_MS` (default 10 s) and the entry deadline; it is always `ok` (informational) and lists totals only, a source the budget stopped or never reached as partial. Tests: `test/git-gap-census.test.ts` (PGLite and Postgres).- `src/core/persistence/git-declared.ts` + `src/core/persistence/git-canonical-schema.ts` (migration `git_canonical_declared`) — git-canonical memory, wave G7a: the declared database-only classes of a strict source (`sources.config.canonical = "git"`, default off). `strictPageClass` judges a page by its slug and prior file (`declaredPathClass`: `db_only_prefix` for a `storage.db_only` dir, `derive_folder` for a never-filed derive-phase page; G3's indexer reads the same function) and then its rendered content (`privacyClass`: `private`, `alias_private`, or `lineage_private` from the same SQL remote reads use, `privatePagesFilterFragment`, over the page's own values). `page-prepare.ts` `prepareFileTarget` asks it before it builds a strict file target: a declared page gets no target (no file, no door commit, no Git effect), an untracked ignored target is `git_ignored`, a page turning private gets the removal of the file it still has in the worktree or at HEAD, and a path whose `filter` attribute is `lfs` passes `assertLfsTarget` only with `storage.git_lfs` and a checkout that configures the LFS filter (`git_lfs_not_enabled`). `preparePrivateTransition` (page-prepare.ts) is that removal for other writers (GBRA-60). In `publishMutation` and `publishGroup`, `assertNoPrivateCommit` refuses a file target carrying a private page's bytes before anything is written (`git_private_commit_refused`; a group rolls back whole), and `declareStrictPublication` (after apply, before the door commit) refuses a declared page's file or an undeclared file-less page (`git_home_required`), stamps `pages.database_only_reason` and, for a privacy class, clears `source_path`/`source_uri` in the transaction of the door commit that removed the file. A managed import builds its own file target, so it meets only these publication checks. `assertStrictGitHome` is the refusal for writers with no file form yet (G4, G5). The managed writer guard (`writer-guard-schema.ts`) refuses rows of a strict source unless the writer declares `gbrain.git_protocol` (`withCoordinatedWrite` does), behind the `git_canonical_brain.strict_sources` counter kept by `sources` triggers (`git_protocol_required`, mapped in `publication-failure.ts`). The census (`git-gap.ts`) adds `database_only_source` (a source with no checkout) and maps the stamped reasons to their own classes. Tests: `test/git-canonical-declared-g7a.test.ts` (both engines).diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex f92e62345c..56b2eac454 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -519,7 +519,7 @@ this anchor (`--json` puts them in one object on stdout); the command exits 1.| <a id="refresh_diverged"></a>`refresh_diverged` | `refresh_diverged` | The checkout has commits its upstream lacks, so a fast-forward is impossible. Nothing changed. | Ask the user, then publish the local commits merged with the upstream: `gbrain git commit-push --push-only --keep-checkout --path <checkout>` merges in memory, pushes the merge, refuses on a conflicting file and never moves the checkout (the refusal's fix fills in the real path and counts the local commits). Then retry `gbrain sources refresh <source>`, which fast-forwards to the merge. `gbrain sources reclone <source>` replaces the checkout instead and drops the local commits. || <a id="refresh_dirty"></a>`refresh_dirty` | `refresh_dirty` | Uncommitted or untracked files overlap the incoming upstream changes (the first 20 are named), or `git merge --ff-only` refused for the same reason. HEAD did not move. Uncommitted files outside the incoming changes do not refuse; they are kept and listed as `preserved_uncommitted`. | Commit or discard the named paths, then retry. Check `gbrain sources writer status <source> --json` first: a pending Git effect may be about to commit a gbrain-published file. || <a id="sync_in_progress"></a>`sync_in_progress` | `sync_in_progress` | A managed sync of one of the checkout's sources has an unfinished cursor. Moving the checkout now would strand it, and the refresh never waits on a sync. `gbrain repair frontmatter --apply` refuses the same way while an unfinished cursor still names a selected file. | Run the printed `gbrain sync --source <source> --no-pull ...` resume command (it keeps the cursor's options), then retry (for a repair, preview again and approve the new hash). |-| <a id="refresh_in_progress"></a>`refresh_in_progress` | `refresh_in_progress` | Another refresh of the same checkout is active and its process is still running (the message names its pid and host), or a command that changes which sources share the checkout (`sources add`, `remove`, `archive`, `restore`, `reclone`) ran while one was active. A refresh whose process died is not a reason to refuse: the next refresh on the owner host finishes it first. | Wait for the running refresh, or check it with `gbrain sources writer status <source>` (`liveness`, `holder`). `gbrain sources refresh <source> --resume` finishes an orphaned one now; then retry the source command with the same request ID. |+| <a id="refresh_in_progress"></a>`refresh_in_progress` | `refresh_in_progress` | Another refresh of the same checkout is active and its process is still running (the message names its holder's pid and host when the active refresh row is already readable), or a command that changes which sources share the checkout (`sources add`, `remove`, `archive`, `restore`, `reclone`) ran while one was active. A refresh whose process died is not a reason to refuse: the next refresh on the owner host finishes it first (`--dry-run` does not, so it still refuses while the orphan stands). An interrupted refresh that needs a reset decision refuses `refresh_recovery_required` instead. | Wait for the running refresh, or check it with `gbrain sources writer status <source>` (`liveness`, `holder`). `gbrain sources refresh <source> --resume` finishes an orphaned one now; then retry the source command with the same request ID. || <a id="refresh_drain_timeout"></a>`refresh_drain_timeout` | `refresh_drain_timeout` | Queued writes or Git effects on the checkout did not finish within `--wait-drain` (default 60 s; `sources.refresh_drain_wait_ms`; `GBRAIN_REFRESH_DRAIN_WAIT_MS`). The counts are in the message. The fence was lifted and HEAD did not move. | Retry, or wait longer with `--wait-drain <seconds>`. Inspect what is queued with `gbrain sources writer status <source> --json`. || <a id="refresh_source_changed"></a>`refresh_source_changed` | `refresh_source_changed` | HEAD moved (an outside commit or checkout), or the checkout's ownership or set of sources changed, between the precheck and the merge. Nothing was merged and the fence was lifted. | Retry `gbrain sources refresh <source>`. || <a id="refresh_recovery_required"></a>`refresh_recovery_required` | `refresh_recovery_required` | Publication or source recovery is pending on the checkout, or a refresh was interrupted and HEAD is neither the commit it started from nor the verified upstream commit. Writes to the checkout stay refused until it is resolved; gbrain never adopts a HEAD it cannot verify. | `gbrain sources writer status <source>`, then `gbrain sources refresh <source> --resume`. When HEAD is unverified the fix names both ways out: reset to the start commit and run `--abandon`, or reset to the upstream commit and run `--resume`. Resetting is destructive, so ask the user first. |diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex dd0dc6de9c..b5c967d429 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1314,6 +1314,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.467.0', id: 'cli_flag_equals', text: 'A CLI flag value written with `=` that a command used to ignore now exits 2 (`invalid_params`) and names the two-argument spelling the command reads: `gbrain auth create --scopes=read` minted a full-access token. A switch never takes a value (`--yes=n`, `--dry-run=true`, `--apply=false` and `-y=n` exit 2 instead of being ignored). The `=` spellings a command reads on every path keep working, and so do the spending cap and plan hash the consent check of a command reads; a few that only some paths read now exit 2 with the two-argument fix, among them the source id given that way to `gbrain extract` for stale extraction, the checkout path given that way to the database-free `gbrain sources pull`, and the values given that way to the managed `gbrain sources` lifecycle subcommands (add, remove, archive, restore, purge, set-path, reclone). A value written with `=` on a flag that the help of the command declares used to be ignored and now applies, so check scripts that pass these that way: an all-interfaces bind address given to `gbrain serve` bound loopback and now listens on every interface; a public URL given to `gbrain serve` now sets the OAuth issuer and resource, so clients authorized under the old localhost issuer must reconnect, and admin cookies become Secure on https; the serve port, token lifetime and stdio idle timeout, the sync interval, source and repository, the import worker count, the autopilot install repository and supervisor, and the target engine and URL the legacy `gbrain migrate` copier reads take effect the same way; a spend cap given to `gbrain onboard` (off included) now applies, and one given to a resumed `gbrain doctor` remediation overrides the cap its checkpoint recorded; and `gbrain apply-migrations` now honors an accepted reviewed inventory and a forced retry of a wedged migration. An upgrade restart of a `gbrain jobs supervisor` started with values written that way (which it ignored) starts it again without them. A script that passes a value with `=` to a command that does not read that form now stops with the fix instead of running without the value.' },// Bun floor 1.4.4 (#7644, #7596). `since` is stamped at the merge slot.{ since: '0.60.468.0', id: 'bun_floor_1_4_4', text: 'GBrain now requires Bun 1.4.4 or newer (previously 1.4.0). On Bun 1.4.0 to 1.4.3 every command except `gbrain --version` exits 1 before it starts with `GBrain requires Bun 1.4.4 or newer (found Bun <version>)` and the fix (`bun upgrade`, then restart GBrain; `gbrain post-upgrade` finishes an interrupted upgrade); `--version` prints the same refusal and exits 0. On Bun 1.4.0 to 1.4.2 a postgres.js connection over TLS keeps every chunk it receives, so a full sync or conversion pass over a TLS Postgres or pooler grew by about the bytes it read until memory guards killed it (#7644, #7596); 1.4.4 also carries the Brotli fix for CVE-2026-111497. Standalone gbrain binaries already embed Bun 1.4.4; a source or `bun install` install runs `bun upgrade` first, and `gbrain upgrade` on an older host Bun stops (autopilot holds) with the same fix.' },+ // #7679 / #7685 orphaned worktree refresh. `since` is stamped at the merge slot.+ { since: '0.60.470.0', id: 'refresh_orphan_7679', text: 'A managed `gbrain sources refresh` whose process died (for example a container replaced mid-refresh) no longer wedges the checkout: the next plain `gbrain sources refresh` on the owner host finishes the orphaned refresh through the `--resume` path before its own refresh and reports it as `recovered`, and the owner completes an orphaned `syncing` refresh once every member has synced to its target. A refresh whose holder is still running, or is recorded on another host, is never taken over. `gbrain sources writer status` and `gbrain sync status` now name the holder and its `liveness` (`live`, `orphaned`, `unknown`) with a fix naming `--resume`. With `--json`, a refusal that carries a structured fix (`refresh_in_progress`, `refresh_diverged`, a git read failure) now prints `fix` as an object (argv, actor, next) instead of a string; the prose stays in `suggestion`, so read that when a script needs text. A plain refresh of a checkout whose interrupted refresh needs a reset decision now refuses `refresh_recovery_required` (it refused `refresh_in_progress`).' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/persistence/worktree-refresh.ts b/src/core/persistence/worktree-refresh.tsindex c436ac087a..409d4664f6 100644--- a/src/core/persistence/worktree-refresh.ts+++ b/src/core/persistence/worktree-refresh.ts@@ -229,6 +229,11 @@ async function precheck(engine: BrainEngine, git: Git, sourceId: string, fetchTiassertRefreshOwner(binding, sourceId, 'move its checkout');const root = binding.local_path;const active = await readActiveRefresh(engine, binding.worktree_id);+ if (active?.state === 'recovery_required') {+ const stored = (active.outcome.refusal ?? {}) as { cause?: string; fix?: string };+ throw refusal('refresh_recovery_required', stored.cause ?? `Refresh ${active.id} could not verify the checkout HEAD, so no refresh recovers it on its own.`,+ stored.fix ?? `gbrain sources writer status ${sourceId}, then gbrain sources refresh ${sourceId} --resume`, active.id);+ }if (active) throw inProgress(`Refresh ${active.id} of this worktree is ${active.state}, held by ${describeHolder(holderOf(active))}; only one refresh per worktree runs at a time.`,`gbrain sources refresh ${sourceId} --resume`, sourceId, active.id);if (binding.state !== 'active' || await worktreeRecoveryPending(engine, binding)) throw refusal('refresh_recovery_required',@@ -501,7 +506,7 @@ async function fenceDraining(engine: BrainEngine, sourceId: string, plan: Plan,plan.oldHead, plan.targetHead, plan.upstreamRef, plan.preserved, JSON.stringify({ holder: refreshHolder() })]);return row;})).catch(error => {- if ((error as { code?: string }).code === '23505' && !classifyOriginUniqueViolation(error)) throw refusal('refresh_in_progress', 'Another refresh of this worktree started first.', `gbrain sources refresh ${sourceId} --resume`);+ if ((error as { code?: string }).code === '23505' && !classifyOriginUniqueViolation(error)) throw inProgress('Another refresh of this worktree started first.', `gbrain sources refresh ${sourceId} --resume`, sourceId);throw error;});}@@ -597,6 +602,7 @@ export async function resumeWorktreeRefreshes(engine: BrainEngine, opts: { hostIconst host = opts.hostId ?? localHostId();const rows = await engine.executeRaw<WorktreeRefreshRow>(`SELECT f.* FROM persistence_worktree_refreshes fJOIN persistence_worktrees w ON w.id=f.worktree_id WHERE w.owner_host_id=$1::uuid AND f.state IN ('draining','fenced','merged','syncing')+ AND (f.state<>'syncing' OR NOT EXISTS (SELECT 1 FROM sources s WHERE s.id=ANY(f.source_ids) AND (s.last_commit IS NULL OR s.last_commit=f.old_head)))ORDER BY f.created_at LIMIT 16`, [host]);let moved = 0;for (const row of rows) {@@ -645,7 +651,7 @@ async function resumeOrAbandon(engine: BrainEngine, sourceId: string, opts: Refrold_head: null, target_head: null, upstream_ref: null, preserved_uncommitted: [], synced: [], next: `gbrain sources refresh ${sourceId}` };if (!active) return empty;const lock = await acquireNativeLock(refreshLockPath(binding.worktree_id), { timeoutMs: 1000 }).catch(() => null as NativeLockHandle | null);- if (!lock) throw inProgress(`Refresh ${active.id} is still running in another process.`, `Wait for it, then gbrain sources refresh ${sourceId} --resume`, sourceId, active.id);+ if (!lock) throw inProgress(`Refresh ${active.id} is still running in another process (${describeHolder(holderOf(active))}).`, `Wait for it, then gbrain sources refresh ${sourceId} --resume`, sourceId, active.id);try {return await withGit(async git => {const head = await headOf(git, root);@@ -769,7 +775,7 @@ export async function refreshHolderReport(row: Pick<WorktreeRefreshRow, 'id' | 'why: `Refresh ${row.id} could not verify the checkout HEAD, so nothing recovers it on its own. --resume changes nothing here: it prints the two ways out (reset to the start commit and --abandon, or to the upstream commit and --resume); resetting is destructive, so ask the user first.` } };if (liveness === 'live') return { ...base, auto_recovery: 'none', fix: null };if (liveness === 'orphaned') return { ...base, auto_recovery: 'next_refresh', fix: { argv: resume, consent: [], actor: 'agent', requires_exclusive: false, verify,- why: `No process holds refresh ${row.id}'s lock (its holder, ${describeHolder(holder)}, exited), so it is orphaned. The next gbrain sources refresh ${source} finishes it on its own through the --resume path`+ why: `No process holds refresh ${row.id}'s lock (recorded holder: ${describeHolder(holder)}), so it is orphaned. The next gbrain sources refresh ${source} finishes it on its own through the --resume path`+ `${row.state === 'syncing' ? ', and the owner completes it once every member has synced to its target' : ''}; --resume finishes it now.` } };return { ...base, auto_recovery: 'unknown', fix: { argv: verify.argv, consent: [], actor: 'host_admin', requires_exclusive: false,why: `Refresh ${row.id}'s lock lives on host ${holderHost ?? 'unknown'}, not this one, so only that host can tell whether ${describeHolder(holder)} is alive. Run this there; if it reports the refresh orphaned, or that host is gone for good, gbrain sources refresh ${source} --resume on the owner host finishes it (a plain refresh does not adopt another host's refresh).` } };diff --git a/test/persistence-worktree-refresh.test.ts b/test/persistence-worktree-refresh.test.tsindex 044206df29..89ccf3ceec 100644--- a/test/persistence-worktree-refresh.test.ts+++ b/test/persistence-worktree-refresh.test.ts@@ -320,12 +320,107 @@ test('7. a crash leaving HEAD on an unrelated commit is recovery_required; writeexpect(refused.suggestion).toContain(`gbrain sources refresh ${f.alpha} --resume`);const resume = await refusedWith(refreshWorktree(f.engine, f.alpha, { resume: true }), 'refresh_recovery_required');expect(resume.suggestion).toContain(`reset --hard ${old}`);+ // Ship audit, #7679. Value: protects=a plain refresh never adopts a recovery_required row, and writer status says nothing recovers it on its+ // own (auto_recovery none, ask the user before resetting); fails_when=adoption drops its recovery_required guard, or the holder report treats+ // it as an orphan the next refresh finishes; why_new=the #7679 tests cover syncing orphans only; seam=none; no_claim=the reset choice itself.+ // The plain refresh refuses with the row's own code and stored fix (both resets), not refresh_in_progress: no process will finish it.+ const plain = await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_recovery_required');+ expect(plain.suggestion).toContain(`reset --hard ${old}`);+ expect((await f.refreshRows()).map(r => r.state)).toEqual(['recovery_required']);+ const [held] = (await runPersistenceAdministration(f.engine, 'writer_status', { source_id: f.alpha }) as { worktree_refreshes: Array<Record<string, any>> }).worktree_refreshes;+ expect(held).toMatchObject({ state: 'recovery_required', auto_recovery: 'none', fix: { argv: ['gbrain', 'sources', 'refresh', f.alpha, '--resume'], actor: 'agent' } });+ expect(held.fix.why).toContain('ask the user');+ expect(await resumeWorktreeRefreshes(f.engine)).toBe(0);+ expect((await f.refreshRows()).map(r => r.state)).toEqual(['recovery_required']);git(f.root, 'reset', '-q', '--hard', old);expect((await refreshWorktree(f.engine, f.alpha, { abandon: true })).status).toBe('abandoned');expect((await f.refreshRows()).map(r => r.state)).toEqual(['aborted']);expect((await f.put(f.alpha, 'notes/after', page('After', 'admitted again'))).state ?? 'committed').toBe('committed');}), 180_000);+test('7b. #7679: a plain refresh rolls back an orphan that died before merging, then runs its own refresh', () => each(async f => {+ // Ship audit. Value: protects=an orphan that died while fenced (HEAD unmoved) is rolled back by the next plain refresh, which then fast-forwards;+ // fails_when=refreshWorktree returns the abandoned recovery instead of refreshing, or adoption skips pre-syncing rows; why_new=the #7679 tests+ // kill only at syncing; seam=none; no_claim=a real process death (the crash is a hook throw; the refresh lock is released as on exit).+ const target = f.push('alpha/two.md', page('Alpha two', 'Upstream.'));+ const old = f.head();+ await expect(refreshWorktree(f.engine, f.alpha, { hooks: { boundary: point => { if (point === 'fenced') throw new Error('simulated crash while fenced'); } } }))+ .rejects.toThrow('simulated crash');+ await disposePersistenceConsumer(f.engine);+ const [orphan] = await f.refreshRows();+ // The resident consumer's owner scan may already have rolled it back; restore what the crash left so only the plain refresh recovers it.+ await f.engine.executeRaw(`UPDATE persistence_worktree_refreshes SET state='fenced',completed_at=NULL WHERE id=$1::uuid`, [orphan.id]);+ expect(f.head()).toBe(old);+ const result = await refreshWorktree(f.engine, f.alpha);+ expect(result).toMatchObject({ status: 'completed', old_head: old, target_head: target,+ recovered: { refresh_id: orphan.id, state: 'aborted', status: 'abandoned', previous_holder: { pid: process.pid } } });+ expect((await f.refreshRows()).map(r => r.state)).toEqual(['aborted', 'completed']);+ expect(f.head()).toBe(target);+ expect(await f.lastCommit(f.alpha)).toBe(target);+}), 180_000);++test('7c. #7679 state matrix: an interrupted refresh of each kind, settled by the owner scan, a plain refresh and --resume', async () => {+ // Value: protects=each kind of interrupted refresh row leaves the row section 1.5 names when the owner scan, a plain refresh (adoption) or+ // --resume (resumeHeld) settles it; fails_when=a kind falls through to a sibling's path (an unverified HEAD adopted as the target, a syncing+ // row with an unrelated HEAD completed or refreshed over, a dead drain left standing); why_new=the #7679 tests cover syncing orphans with HEAD at+ // the target only; seam=none; no_claim=a real process death (the crash is a hook throw; the refresh lock is released as on exit).+ type Kind = 'draining' | 'fenced_old' | 'fenced_target' | 'fenced_unrelated' | 'syncing_at_target' | 'syncing_unrelated';+ type Action = 'owner_scan' | 'plain' | 'resume';+ const crashAt = { draining: 'drained', fenced_old: 'fenced', fenced_target: 'fenced', fenced_unrelated: 'fenced', syncing_at_target: 'syncing', syncing_unrelated: 'syncing' } as const;+ const cells: Array<[Kind, Action]> = [['draining', 'owner_scan'], ['fenced_old', 'owner_scan'], ['syncing_unrelated', 'owner_scan'],+ ['draining', 'plain'], ['fenced_target', 'plain'], ['fenced_unrelated', 'plain'], ['syncing_at_target', 'plain'], ['syncing_unrelated', 'plain'],+ ['draining', 'resume'], ['fenced_old', 'resume'], ['fenced_target', 'resume'], ['fenced_unrelated', 'resume'], ['syncing_unrelated', 'resume']];+ for (const engine of engines) for (const [kind, action] of cells) await withRefreshFixture(engine, async f => {+ const label = `${kind} x ${action}`;+ const target = f.push('alpha/two.md', page('Alpha two', 'Upstream.'));+ const old = f.head();+ await expect(refreshWorktree(f.engine, f.alpha, { hooks: { boundary: point => { if (point === crashAt[kind]) throw new Error(`simulated crash at ${point}`); } } }))+ .rejects.toThrow('simulated crash');+ await disposePersistenceConsumer(f.engine);+ const [orphan] = await f.refreshRows();+ // The resident consumer's owner scan may already have settled it; restore what the crash left.+ const state = kind === 'draining' ? 'draining' : kind.startsWith('fenced') ? 'fenced' : 'syncing';+ await f.engine.executeRaw(`UPDATE persistence_worktree_refreshes SET state=$2,completed_at=NULL WHERE id=$1::uuid`, [orphan.id, state]);+ if (kind === 'fenced_target') git(f.root, 'merge', '-q', '--ff-only', target);+ if (kind.endsWith('_unrelated')) { git(f.root, 'reset', '-q', '--hard', old); commitFile(f.root, 'beta/unrelated.md', page('Unrelated', 'Not the upstream commit.')); }+ if (kind === 'syncing_at_target') for (const member of [f.alpha, f.beta]) await f.engine.transaction(tx => withCoordinatedWrite(tx, [member],+ () => tx.executeRaw('UPDATE sources SET last_commit=$2 WHERE id=$1', [member, target]), TEST_WRITE_ATTRIBUTION));+ const head = f.head();+ const rows = async () => (await f.refreshRows()).map(r => r.state);+ if (action === 'owner_scan') {+ const moved = await resumeWorktreeRefreshes(f.engine);+ if (kind === 'syncing_unrelated') { expect(moved, label).toBe(0); expect(await rows(), label).toEqual(['syncing']); }+ else { expect(moved, label).toBe(1); expect(await rows(), label).toEqual(['aborted']); }+ expect(f.head(), label).toBe(head);+ return;+ }+ const run = refreshWorktree(f.engine, f.alpha, action === 'resume' ? { resume: true } : {});+ if (kind.endsWith('_unrelated')) {+ await refusedWith(run, 'refresh_recovery_required');+ expect(await rows(), label).toEqual(['recovery_required']);+ expect(f.head(), label).toBe(head);+ return;+ }+ const result = await run;+ if (action === 'resume') {+ expect(result, label).toMatchObject(kind === 'fenced_target' ? { status: 'completed', refresh_id: orphan.id } : { status: 'abandoned', refresh_id: orphan.id });+ expect(await rows(), label).toEqual([kind === 'fenced_target' ? 'completed' : 'aborted']);+ expect(f.head(), label).toBe(head);+ return;+ }+ if (kind === 'draining') {+ expect(result, label).toMatchObject({ status: 'completed', target_head: target, recovered: { refresh_id: orphan.id, state: 'aborted', status: 'abandoned' } });+ expect(await rows(), label).toEqual(['aborted', 'completed']);+ } else {+ expect(result, label).toMatchObject({ status: 'already_current', recovered: { refresh_id: orphan.id, state: 'completed', status: 'completed', previous_holder: { pid: process.pid } } });+ expect(await rows(), label).toEqual(['completed']);+ }+ expect(f.head(), label).toBe(target);+ expect(await f.lastCommit(f.alpha), label).toBe(target);+ expect(await f.lastCommit(f.beta), label).toBe(target);+ });+}, 600_000);+test('8. a queued git effect drains before fenced, and nothing on the worktree is claimed while fenced', () => each(async f => {f.push('alpha/two.md', page('Alpha two', 'Upstream.'));await f.put(f.beta, 'notes/effect', page('Effect', 'Has a git effect.'));@@ -396,6 +491,11 @@ test('10. source add and remove on the worktree during a refresh refuse refresh_expect(add.suggestion).toContain('--resume');await refusedWith(runManagedSourceLifecycle(f.engine, { operation: 'remove', sourceId: f.beta, confirmDestructive: true }), 'refresh_in_progress');await refusedWith(refreshWorktree(f.engine, f.beta), 'refresh_in_progress');+ // Ship audit, #7679. Value: protects=writer status tells writers to retry a live draining refresh, never to --resume it; fails_when=the+ // draining branch is removed or ordered after the live branch, or liveness misreports the holder; why_new=no test read writer status while draining; seam=none; no_claim=other-host liveness.+ const [draining] = (await runPersistenceAdministration(f.engine, 'writer_status', { source_id: f.beta }) as { worktree_refreshes: Array<Record<string, any>> }).worktree_refreshes;+ expect(draining).toMatchObject({ state: 'draining', liveness: 'live', fix: null });+ expect(draining.next).toContain('queued work drains');} } });expect(result.status).toBe('completed');}), 180_000);@@ -551,13 +651,17 @@ test('admission completes a syncing refresh whose members all reached the targetexpect((await refreshWorktree(f.engine, f.alpha)).status).toBe('completed');const [row] = await f.refreshRows();// A refresh whose process died in `syncing` after a later cycle sync caught one member up but not the other.+ // #7679: the owner scan completes such a row too, so the consumer is stopped to leave it to admission.+ await disposePersistenceConsumer(f.engine);await f.engine.executeRaw(`UPDATE persistence_worktree_refreshes SET state='syncing',completed_at=NULL WHERE id=$1::uuid`, [row.id]);const setLastCommit = (sha: string) => f.engine.transaction(tx => withCoordinatedWrite(tx, [f.beta], () => tx.executeRaw('UPDATE sources SET last_commit=$2 WHERE id=$1', [f.beta, sha]), TEST_WRITE_ATTRIBUTION));await setLastCommit(git(f.root, 'rev-parse', 'HEAD~1'));await refusedWith(f.put(f.alpha, 'notes/lagging', page('Lagging', 'refused')), 'worktree_refreshing');await setLastCommit(target);expect((await f.put(f.alpha, 'notes/caught-up', page('Caught up', 'admitted'))).state ?? 'committed').toBe('committed');- expect((await f.refreshRows()).map(r => r.state)).toEqual(['completed']);+ const done = await f.refreshRows();+ expect(done.map(r => r.state)).toEqual(['completed']);+ expect(done[0].outcome.completed_by).toBeUndefined();}), 120_000);test('#6712 wave: a refresh completes once every member synced to a descendant of the target, and --resume completes it the same way', () => each(async f => {diff --git a/test/worktree-refresh-orphan-7679.test.ts b/test/worktree-refresh-orphan-7679.test.tsindex 4c8f0cc464..2498c4b8c9 100644--- a/test/worktree-refresh-orphan-7679.test.ts+++ b/test/worktree-refresh-orphan-7679.test.ts@@ -109,6 +109,11 @@ test('#7679: a refresh killed mid-syncing is reported orphaned with its holder,// The wedge: every page write to the worktree is refused while the orphan stands.await refusedWith(f.put(f.beta, 'notes/while-orphaned', page('While orphaned', 'refused')), 'worktree_refreshing');+ // Ship audit. Value: protects=a --dry-run reports the orphan and writes nothing (no adoption, holder unchanged); fails_when=the dryRun guard on+ // adoption is dropped; why_new=no dry run ran against an orphan; seam=none; no_claim=none beyond protects.+ await refusedWith(refreshWorktree(f.engine, f.alpha, { dryRun: true }), 'refresh_in_progress');+ expect((await f.refreshRows() as Row[]).map(row => [row.state, row.outcome.holder?.pid, row.outcome.previous_holder])).toEqual([['syncing', pid, undefined]]);+const next = f.push('alpha/three.md', page('Alpha three', 'Landed upstream while the refresh was orphaned.'));const result = await refreshWorktree(f.engine, f.alpha);expect(result).toMatchObject({ status: 'completed', old_head: target, target_head: next,@@ -193,6 +198,26 @@ test('#7679: a live refresh is never stolen: owner recovery, a plain refresh and}}, 300_000);+test('#7679: an orphan written before holders were recorded is reported orphaned on the owner host, and the next plain refresh adopts it', async () => {+ // Ship audit. Value: protects=a refresh row with no outcome.holder (left by a binary older than #7679) is still adopted and reported orphaned;+ // fails_when=adoption or the holder report requires a recorded holder, so the upgrade-era orphan stays wedged; why_new=every #7679 test row+ // carries a holder; seam=none; no_claim=a row written by an actual older binary (the holder is removed with SQL).+ for (const item of cases) await withKilledRefresh(item, async ({ f, target, orphan }) => {+ await f.engine.executeRaw(`UPDATE persistence_worktree_refreshes SET outcome=outcome-'holder' WHERE id=$1::uuid`, [orphan.id]);+ const [status] = await writerRefreshes(f, f.alpha);+ expect(status).toMatchObject({ refresh_id: orphan.id, holder: null, liveness: 'orphaned', orphaned: true, auto_recovery: 'next_refresh',+ fix: { argv: ['gbrain', 'sources', 'refresh', f.alpha, '--resume'] } });+ expect(status.fix.why).toContain('a process that recorded no holder');+ const result = await refreshWorktree(f.engine, f.alpha);+ expect(result).toMatchObject({ status: 'already_current', recovered: { refresh_id: orphan.id, state: 'completed', status: 'completed', previous_holder: null } });+ const rows = await f.refreshRows() as Row[];+ expect(rows.map(row => row.state)).toEqual(['completed']);+ expect(rows[0].outcome.holder.pid).toBe(process.pid);+ expect(await f.lastCommit(f.alpha)).toBe(target);+ expect(await f.lastCommit(f.beta)).toBe(target);+ });+}, 300_000);+test('#7679: an orphan whose recorded holder is on another host is reported unknown and is not adopted by a plain refresh; --resume on the owner finishes it', async () => {for (const item of cases) await withKilledRefresh(item, async ({ f, target, orphan }) => {const elsewhere = randomUUID();@@ -201,6 +226,9 @@ test('#7679: an orphan whose recorded holder is on another host is reported unknexpect(status).toMatchObject({ liveness: 'unknown', orphaned: null, auto_recovery: 'unknown', fix: { actor: 'host_admin' } });expect(status.fix.why).toContain(elsewhere);expect(status.fix.why).toContain('--resume');+ const sync = await readSyncStatus(f.engine, f.alpha, { detail: false });+ expect(sync.worktree_refresh).toMatchObject({ refresh_id: orphan.id, liveness: 'unknown', orphaned: null });+ expect(sync.next).toMatchObject({ actor: 'host_admin', argv: ['gbrain', 'sources', 'writer', 'status', '--source', f.alpha, '--json'] });await refusedWith(refreshWorktree(f.engine, f.alpha), 'refresh_in_progress');expect((await f.refreshRows()).map(row => row.state)).toEqual(['syncing']);expect(await refreshWorktree(f.engine, f.alpha, { resume: true })).toMatchObject({ status: 'completed', refresh_id: orphan.id, target_head: target });