Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(door): refresh the index under Git's index lock, so a stage can't land between the compare and the write (#7742)
garrytanf09fbe25918f
diff --git a/docs/architecture/key-files/core-persistence-continued.md b/docs/architecture/key-files/core-persistence-continued.mdindex 36bb6018ef..ddd096cd7d 100644--- a/docs/architecture/key-files/core-persistence-continued.md+++ b/docs/architecture/key-files/core-persistence-continued.md@@ -46,5 +46,5 @@ The #6188 fence check and fence repair live in [fence repair](core-fence-repair.- `src/core/postgres-engine/reserved-transactions.ts` with `isPersistenceDeclaration` (`src/core/persistence/protocol.ts`) — BEGIN pipelining. `isPersistenceDeclaration` (GBRA-156) accepts exactly the `protocol.ts` declarations (transaction-local `set_config` calls and the brain row FOR SHARE). Admission, the FIFO claim, the effect claims and source guards, the receipt true-up, the single publication (`coordinator.ts`) and the consumer's lent lane transactions (`consumer.ts` `onLane`, through `reservedTransactions`) pass it as `TransactionOptions.pipelineFirst`, so behind a transaction-mode pooler the declaration goes out with BEGIN (one round trip less per transaction) while every later statement still waits for BEGIN's answer; if BEGIN fails, only the declaration has run, in autocommit, where it changes nothing. A reserved transaction gates every statement its body can reach, savepoint and nested-transaction bodies and `file()` included. A sync lane group's publication passes none: its begun mark must follow BEGIN's answer (`sync-lanes.ts` `awaitLaneBegin`). Tests: `test/persistence-pipeline-first.test.ts` (the predicate and the reviewed call sites), `test/e2e/pgbouncer-transaction-pipeline-6930.test.ts`.- `src/core/persistence/checkout-state.ts` (`readCheckoutState`) — Q1: a canonical checkout against its last fetched upstream, read-only and time-bounded (no fetch): ahead/behind, `diverged`, each commit the upstream lacks (sha, author, date, subject, paths; at most 20) and porcelain counts. `sources writer status` reports it as `checkouts`; doctor `git_convergence` adds the commits and counts for a managed checkout and warns at once on a diverged one.- `src/core/links-fence.ts` + `src/core/links-fence-projection.ts` — the `## Links` fence (G5): the markdown form of authored (manual) edges, `<!--- gbrain:links:begin -->` / `end` around `| to | type | source | valid_from | valid_until | context |`, one row per (to, type, source), source defaulting to `manual`; a reconciliation-managed provenance (`MANAGED_LINK_SOURCES`, exported here and re-exported by `ops/links.ts`), a bad date or a duplicate key is a skipped row with a warning. `parseLinksFence` (state `absent` / `parsed` / `malformed`), the deterministic `renderLinksFence` (rows sorted by key), `upsertLinksFenceRow` (omitted context and dates keep the stored ones; identical row = unchanged body), `removeLinksFenceRows` (leaves an empty fence), `replaceOrInsertLinksFence` (a `## Links` section at the end of compiled_truth, above an unclosed code block) and `maskLinksFence`, which `extractBodyLinks` applies so the fence cells are never also extracted as markdown, wikilink or bare-slug edges. A rewrite of a fence that parses with warnings throws `LinksFenceRewriteRefusal`. Cells use `escapeFenceCell` plus the same one-level marker encoding for `gbrain:links:*`. `projectLinksFence(tx, page, rows)` reconciles only what the page's fence owns: edges with origin_page_id = the page and origin_field `links_fence` (deleted, context-updated, inserted by key) and `manual` transitions with origin_page_id = the page, then refreshes the touched relationships; a row whose target is not a live page in the source yields no edge. `linksFenceProjectionRows` returns null for an absent or malformed fence, so such a body changes no edge (an absent fence retires nothing, as for facts; unlike facts no held generation is recorded, so after a hand deletion of the whole section the database keeps edges git no longer has until `remove_link` or the G3 indexer), and drops rows typed with a link type the active pack does not declare. Callers: `prepareCanonicalProjections` (every projected page publication, quarantined and segmented-unread bodies excepted), `prepareAutomaticLinks` (put_page auto-links and the managed links maintenance, so `extract --stale` restores a lost fence edge) and `persistence/manual-links.ts`. Database-only manual edges (origin_field NULL) are never touched by any of them. Pinned by `test/links-fence.test.ts` and `test/managed-links-fence.test.ts`.-- `src/core/persistence/git-door.ts`: G2, the door of git-canonical memory (Git is the source of truth, the database derives from it). A source with `sources.config.canonical = "git"` (strict, default off; nothing sets it yet) commits each published file before its database row. `publishMutation` (`coordinator.ts`) and `publishGroup` (`group-publish.ts`, one commit per group, after its lane turn) call `commitThroughDoor` under the writer lock, between the file rename and the transaction commit. It commits by plumbing without the checkout's index: `hash-object -w` per file, the trees along the changed paths rebuilt from HEAD (`cat-file tree`, `hash-object -w -t tree`), `commit-tree` with `commitGitTargets`' message, `update-ref` compare-and-swap (one rebuild if the branch moved, then a refusal), then `update-index --cacheinfo` for exactly the published paths (an entry someone staged during the write is left as it is, and the write says its commit landed); detached HEAD and unborn branches refuse typed. Each `DoorFile` carries its planned state (`planned`: the sha256 of the bytes the publication wrote, or null for a removal), and the door commits exactly that state or nothing: the file must hash to the plan before and after `hash-object -w` (else `git_target_changed`: nothing is committed and the edit stays on disk; the write is held in recovery as `unexpected_file_bytes` when the file holds neither its bytes nor the version before it, and fails with nothing held when the file holds the version before it), and each target's index entry must equal HEAD's (else `git_index_conflict`, index untouched). An entry that still holds the version its path's last commit replaced (an interrupted door refresh) counts as clean: the write restores it to HEAD and reports the paths as `outcome.persistence.git_index_restored` and the `git_index_restored` notice (`indexRestoredNotice`, emitted by `page-mutations.ts` `emitFenceNotice`). The step deadline is sized from one stat of the index (`gitStepTimeoutMs`), and `refuseIgnored` asks `check-ignore` only about new targets `ignore-rules.ts` cannot clear. Door commits are not coalesced across single writes (each holds its worktree lock exclusively and the consumer runs one per root); a batch commits once through publishGroup. The publication stamps the commit as `outcome.persistence.git_commit` (`git_state: committed`); a target Git refuses rolls the publication back. The Git effect carries `push_only` and joins the push without staging (`effects.ts`). The recovery record carries `door` (checkout and starting HEAD); `recoverPublication` keeps a file whose commit landed (`doorCommitLanded`) instead of restoring it, and the replay completes against it: `replayAfterDoorCommit` in `publishMutation` and the strict exceptions in `page-prepare.ts` (own bytes committed, or a removal HEAD already holds). Old binaries ignore `door`; strict stays off until conversion fences them. Tests: `test/git-door-strict-gbra133.test.ts` (both engines), `test/git-door-plumbing-gbra133.test.ts`, `test/git-door-planned-state.test.ts`, `test/git-door-write-cost.test.ts`; per-write overhead bench `scripts/bench/door-write-overhead.ts` (opt-in, smoke `test/bench-door-write-overhead.test.ts`).+- `src/core/persistence/git-door.ts`: G2, the door of git-canonical memory (Git is the source of truth, the database derives from it). A source with `sources.config.canonical = "git"` (strict, default off; nothing sets it yet) commits each published file before its database row. `publishMutation` (`coordinator.ts`) and `publishGroup` (`group-publish.ts`, one commit per group, after its lane turn) call `commitThroughDoor` under the writer lock, between the file rename and the transaction commit. It commits by plumbing without the checkout's index: `hash-object -w` per file, the trees along the changed paths rebuilt from HEAD (`cat-file tree`, `hash-object -w -t tree`), `commit-tree` with `commitGitTargets`' message, `update-ref` compare-and-swap (one rebuild if the branch moved, then a refusal), then `update-index --cacheinfo` for exactly the published paths (an entry someone staged during the write is left as it is, and the write says its commit landed). That refresh runs under Git's own index lock: `syncIndex` creates `<index>.lock` exclusively (an existing lock refuses with the landed failure), compares the entries, updates a hard-linked copy of the index through `GIT_INDEX_FILE`, and renames the copy onto the lock and the lock onto the index, so no writer that takes the lock can stage between the compare and the write; detached HEAD and unborn branches refuse typed. Each `DoorFile` carries its planned state (`planned`: the sha256 of the bytes the publication wrote, or null for a removal), and the door commits exactly that state or nothing: the file must hash to the plan before and after `hash-object -w` (else `git_target_changed`: nothing is committed and the edit stays on disk; the write is held in recovery as `unexpected_file_bytes` when the file holds neither its bytes nor the version before it, and fails with nothing held when the file holds the version before it), and each target's index entry must equal HEAD's (else `git_index_conflict`, index untouched). An entry that still holds the version its path's last commit replaced (an interrupted door refresh) counts as clean: the write restores it to HEAD and reports the paths as `outcome.persistence.git_index_restored` and the `git_index_restored` notice (`indexRestoredNotice`, emitted by `page-mutations.ts` `emitFenceNotice`). The step deadline is sized from one stat of the index (`gitStepTimeoutMs`), and `refuseIgnored` asks `check-ignore` only about new targets `ignore-rules.ts` cannot clear. Door commits are not coalesced across single writes (each holds its worktree lock exclusively and the consumer runs one per root); a batch commits once through publishGroup. The publication stamps the commit as `outcome.persistence.git_commit` (`git_state: committed`); a target Git refuses rolls the publication back. The Git effect carries `push_only` and joins the push without staging (`effects.ts`). The recovery record carries `door` (checkout and starting HEAD); `recoverPublication` keeps a file whose commit landed (`doorCommitLanded`) instead of restoring it, and the replay completes against it: `replayAfterDoorCommit` in `publishMutation` and the strict exceptions in `page-prepare.ts` (own bytes committed, or a removal HEAD already holds). Old binaries ignore `door`; strict stays off until conversion fences them. Tests: `test/git-door-strict-gbra133.test.ts` (both engines), `test/git-door-plumbing-gbra133.test.ts`, `test/git-door-planned-state.test.ts`, `test/git-door-write-cost.test.ts`, `test/git-door-index-lock-7742.test.ts` (both engines); per-write overhead bench `scripts/bench/door-write-overhead.ts` (opt-in, smoke `test/bench-door-write-overhead.test.ts`).- `src/core/persistence/ignore-rules.ts` — the ignore filter in front of `git check-ignore`; Git stays the only judge of an ignored path. `ignoreCandidates(root, paths)` returns every path some positive ignore rule could match, read from every `.gitignore` from the top level down to the path, `info/exclude` and `core.excludesFile`; a path it drops is one no rule could match. It over-approximates: negated rules are dropped, every wildcard matches any run of characters including `/`, directory-only rules match files, letters compare case-insensitively, each rule is tested against the path and every directory above it in its own and NFC spelling, and an unreadable or non-UTF-8 ignore file or a rule with a backslash or a character outside printable ASCII matches everything under its directory. Every path goes to Git on a sparse checkout or skip-worktree entry, a split or sparse index, an unresolvable `core.excludesFile` or include, a gitlink or symlink along the path, or a failed probe. The probe (rev-parse layout and the configuration with its origin files) is cached per checkout and taken again when a configuration file it read or could read, HEAD or the configuration environment changes; ignore files are re-read on every call and parsed once per content. Callers: `git-door.ts` `refuseIgnored` and `sync-origin-evidence.ts` `gitIgnoresUntracked`. Tests: `test/ignore-rules.test.ts`.diff --git a/src/core/persistence/effect-git.ts b/src/core/persistence/effect-git.tsindex c4357c2633..e1643713ea 100644--- a/src/core/persistence/effect-git.ts+++ b/src/core/persistence/effect-git.ts@@ -60,19 +60,20 @@ export interface GitEffectOwner {onReclaim?: (receipt: IndexLockReclaim) => void;}-export interface GitSession { root: string; hooks: string; signal?: AbortSignal; timeoutMs: number; owner?: GitEffectOwner }+export interface GitSession { root: string; hooks: string; signal?: AbortSignal; timeoutMs: number; owner?: GitEffectOwner; indexFile?: string }const gitArgs = (session: GitSession, args: string[], literal: boolean) =>[...(literal ? ['--literal-pathspecs'] : []), '-C', session.root, '-c', `core.hooksPath=${session.hooks}`, '-c', 'commit.gpgsign=false', ...args];const gitOptions = (session: GitSession) => ({ timeout: session.timeoutMs, termGraceMs: GIT_TERM_GRACE_MS, maxBuffer: 1024 * 1024, signal: session.signal });+const gitEnv = (session: GitSession) => gitChildEnv(session.indexFile ? { ...GIT_ENV, GIT_INDEX_FILE: session.indexFile } : GIT_ENV);function run(session: GitSession, args: string[], literal = true) {- return execFileBounded('git', gitArgs(session, args, literal), { ...gitOptions(session), env: gitChildEnv(GIT_ENV) });+ return execFileBounded('git', gitArgs(session, args, literal), { ...gitOptions(session), env: gitEnv(session) });}/** A read-only git step whose stdout is raw bytes (a tree object); null when git exits non-zero. */export async function gitBytes(session: GitSession, args: string[]): Promise<Buffer | null> {- const { error, stdout } = await execFileBounded('git', gitArgs(session, args, true), { ...gitOptions(session), env: gitChildEnv(GIT_ENV), maxBuffer: 256 * 1024 * 1024, encoding: 'buffer' });+ const { error, stdout } = await execFileBounded('git', gitArgs(session, args, true), { ...gitOptions(session), env: gitEnv(session), maxBuffer: 256 * 1024 * 1024, encoding: 'buffer' });if (error && (error.killed || typeof error.code !== 'number')) throw gitFailure('Git execution did not finish within its bounded attempt.',`A git command in the canonical checkout did not finish within ${Math.round(session.timeoutMs / 1000)} seconds or could not start.`);return error ? null : stdout;diff --git a/src/core/persistence/git-door.ts b/src/core/persistence/git-door.tsindex 6f3bde7c19..242ed91854 100644--- a/src/core/persistence/git-door.ts+++ b/src/core/persistence/git-door.ts@@ -38,8 +38,8 @@* waiting at the door to join. Batching independent writes needs those three to change; until then a batch commits* once through publishGroup.*/-import { createHash } from 'node:crypto';-import { existsSync, lstatSync, mkdirSync, mkdtempSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';+import { createHash, randomBytes } from 'node:crypto';+import { closeSync, copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';import { join, relative, resolve, sep } from 'node:path';import type { Notice } from '../agent-output.ts';import { OperationError, opError } from '../ops/contract.ts';@@ -431,22 +431,42 @@ async function replacedEntries(session: GitSession, commit: string, targets: Tar* Points the checkout's index entries of the targets at `commit`'s (a removed target leaves the index) and touches no* other entry. An entry that changed since `seen` was read (someone staged it during the write) is left as it is. A* failure here comes after the commit landed, so it says so instead of claiming nothing was published.+ *+ * The compare and the write run under Git's own index lock (`<index>.lock`, created exclusively): the entries are read+ * and a copy of the index is updated while the lock is held, and the copy is renamed onto the lock and the lock onto the+ * index, as Git commits an index. No writer that takes the lock can change the index between the compare and the write.+ * A writer that reads the index before locking it (a raw `git commit -- <path>`) is outside this guarantee.*/async function syncIndex(session: GitSession, root: string, prefix: string, index: string, targets: Target[], commit: string, seen: IndexSnapshot): Promise<void> {- let failure = '', restaged: Target[] = [];+ let failure = '', restaged: Target[] = [], held = false;+ const lock = `${index}.lock`, copy = `${index}.gbrain-${process.pid}-${randomBytes(6).toString('hex')}`;try {- if (indexSignature(index) !== seen.signature) {- const now = await readIndex(session, index, targets);- restaged = targets.filter(target => now.entries.get(target.rel) !== seen.entries.get(target.rel));+ try { closeSync(openSync(lock, 'wx')); held = true; } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;+ failure = `Unable to create '${lock}': File exists; another git process holds the index lock`;}- const synced = targets.filter(target => !restaged.includes(target));- const kept = synced.filter(target => target.oid), removed = synced.filter(target => !target.oid);- if (synced.length) {- const updated = await git(session, ['update-index', '--add', ...kept.flatMap(target => ['--cacheinfo', `${target.mode},${target.oid},${prefix}${target.rel}`]),- ...(removed.length ? ['--force-remove', '--', ...removed.map(target => target.rel)] : [])]);- if (updated.code !== 0) failure = updated.stderr.trim().slice(0, 300) || `exit ${updated.code}`;+ if (held) {+ const moved = indexSignature(index) !== seen.signature;+ // Git never rewrites an index in place (it writes <file>.lock and renames it), so a hard link is a safe copy.+ if (existsSync(index)) try { linkSync(index, copy); } catch { copyFileSync(index, copy); }+ if (moved) {+ const now = await readIndex({ ...session, indexFile: copy }, copy, targets);+ restaged = targets.filter(target => now.entries.get(target.rel) !== seen.entries.get(target.rel));+ }+ const synced = targets.filter(target => !restaged.includes(target));+ const kept = synced.filter(target => target.oid), removed = synced.filter(target => !target.oid);+ if (synced.length) {+ const updated = await git({ ...session, indexFile: copy }, ['update-index', '--add', ...kept.flatMap(target => ['--cacheinfo', `${target.mode},${target.oid},${prefix}${target.rel}`]),+ ...(removed.length ? ['--force-remove', '--', ...removed.map(target => target.rel)] : [])]);+ if (updated.code !== 0) failure = updated.stderr.trim().slice(0, 300) || `exit ${updated.code}`;+ else { renameSync(copy, lock); renameSync(lock, index); held = false; }+ }}} catch (error) { failure = error instanceof Error ? error.message : String(error); }+ finally {+ rmSync(copy, { force: true });+ if (held) rmSync(lock, { force: true });+ }if (!failure && !restaged.length) return;const error = failure? opError('git_unavailable', `The strict source's commit ${commit.slice(0, 12)} landed, but the index of ${root} was not updated for ${targets.map(target => target.rel).join(', ')}.`,diff --git a/test/git-door-index-lock-7742.test.ts b/test/git-door-index-lock-7742.test.tsnew file mode 100644index 0000000000..18754c2c77--- /dev/null+++ b/test/git-door-index-lock-7742.test.ts@@ -0,0 +1,170 @@+/**+ * The door's index refresh after its commit is atomic against every Git writer that takes the index lock+ * (src/core/persistence/git-door.ts syncIndex, gbrain#7742). Protects, on both engines:+ * - a stage attempted at the moment the door writes the index (after its last read of the entries) is never silently+ * overwritten: Git refuses it on `index.lock`, the door's publication commits, and a retry of the stage then holds+ * (red before: the stage was accepted, the door's update-index wrote its own blob over it and reported committed);+ * - a stage that lands after the door's pre-commit check and before it takes the lock is left staged, and the refusal+ * says the commit landed and names the path;+ * - another writer holding `index.lock` while the door refreshes the index makes the refresh refuse with the landed+ * failure; the holder's lock is left to its holder and the door leaves no lock or index copy behind;+ * - plumbing: a failed update of the index copy releases the lock and removes the copy.+ */+import { afterEach, describe, expect, test } from 'bun:test';+import { execFileSync } from 'node:child_process';+import { randomUUID } from 'node:crypto';+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, utimesSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import type { BrainEngine } from '../src/core/engine.ts';+import { gitChildEnv } from '../src/core/git-env.ts';+import { operations, type OperationContext } from '../src/core/operations.ts';+import { submissionAuthority } from '../src/core/persistence/authority.ts';+import { publishMutation, type PublicationHooks } from '../src/core/persistence/coordinator.ts';+import { sha256 } from '../src/core/persistence/digest.ts';+import { commitThroughDoor } from '../src/core/persistence/git-door.ts';+import { localHostId } from '../src/core/persistence/identity.ts';+import { admitWrite, claimNextWrite } from '../src/core/persistence/journal.ts';+import { getWorktreeBinding } from '../src/core/persistence/ownership.ts';+import { preparePageMutation } from '../src/core/persistence/page-prepare.ts';+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';+import { durableGitRepo } from './helpers/git-publication.ts';+import { withEnv } from './helpers/with-env.ts';+import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';++const env = gitChildEnv();+const git = (root: string, ...args: string[]) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env }).trim();+const refusal = (work: Promise<unknown>) => work.then(() => null, (error: { code?: string; message?: string }) => error);+const realGit = () => execFileSync('sh', ['-c', 'command -v git'], { encoding: 'utf8' }).trim();++const SLUG = 'notes/probe';+const FILE = `${SLUG}.md`;+const page = (title: string) => `---\ntype: note\ntitle: ${title}\n---\n\nA small single-file page body.\n`;+const setup = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };+const putPage = operations.find(op => op.name === 'put_page')!;+const dirs: string[] = [];+afterEach(() => { for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }); });++/**+ * A git on PATH that hands every call to the real git. Once armed, the first call whose arguments contain ` <trigger> `+ * first runs `action` (a shell snippet with $REAL, $ROOT and $DIR set; GIT_INDEX_FILE is unset, so it acts on the+ * checkout's own index as a separate git process would).+ */+function gitShim(root: string, trigger: string, action: string): { dir: string; path: string; arm(): void } {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-git-shim-')));+ dirs.push(dir);+ mkdirSync(join(dir, 'bin'));+ writeFileSync(join(dir, 'bin', 'git'), [+ '#!/bin/sh',+ `REAL='${realGit()}'; ROOT='${root}'; DIR='${dir}'`,+ `case " $* " in *" ${trigger} "*)`,+ ' if [ -f "$DIR/arm" ] && [ ! -f "$DIR/fired" ]; then',+ ' : > "$DIR/fired"',+ ` ( unset GIT_INDEX_FILE; ${action} )`,+ ' fi;;',+ 'esac',+ `PATH='${process.env.PATH}' exec "$REAL" "$@"`,+ '',+ ].join('\n'), { mode: 0o755 });+ return { dir, path: `${join(dir, 'bin')}:${process.env.PATH}`, arm: () => writeFileSync(join(dir, 'arm'), '') };+}++/** The shim action that stages $DIR/user.md as the page, recording the blob, the exit code and git's output. */+const STAGE_USER = `oid=$("$REAL" -C "$ROOT" hash-object -w -- "$DIR/user.md"); printf %s "$oid" > "$DIR/user.oid"; "$REAL" -C "$ROOT" update-index --add --cacheinfo "100644,$oid,${FILE}" > "$DIR/stage.out" 2>&1; echo $? > "$DIR/stage.rc"`;++/** A strict source holding one committed page titled First. */+async function committedPage(engine: BrainEngine, ctx: OperationContext): Promise<void> {+ await engine.executeRaw(`UPDATE sources SET config = config || '{"canonical":"git"}'::jsonb WHERE id='default'`);+ expect(await putPage.handler(ctx, { slug: SLUG, content: page('First'), request_id: randomUUID(), wait_ms: 30_000 })).toMatchObject({ state: 'committed' });+ await settleManagedGitEffects(engine);+}++/** One put_page publication of `content` through the door, with the coordinator's boundary hooks. */+async function publish(engine: BrainEngine, ctx: OperationContext, content: string, hooks: PublicationHooks = {}) {+ await disposePersistenceConsumer(engine);+ const host = localHostId(), binding = (await getWorktreeBinding(engine, 'default', host))!, old = (await engine.readPageSnapshot(SLUG, { sourceId: 'default' }))!;+ const authority = await submissionAuthority(ctx, 'put_page', 'default', binding.source_incarnation, SLUG);+ const intent = { slug: SLUG, content, expected_revision: old.revision };+ await admitWrite(engine, { principal: authority.principal, authority, operation: 'put_page', sourceId: 'default', sourceIncarnation: binding.source_incarnation,+ slug: SLUG, pageId: old.page.id, requestId: randomUUID(), callerIntent: intent, intent, worktreeId: binding.worktree_id, topologyGeneration: binding.topology_generation });+ const row = (await claimNextWrite(engine, host))!;+ return publishMutation(engine, row, await preparePageMutation(engine, row, ctx.config), host, hooks);+}++/** Arms the shim once the publication's file is in place, with a user edit of the page ready to stage. */+const armAfterPublication = (root: string, shim: { dir: string; arm(): void }): PublicationHooks => ({ boundary: async name => {+ if (name !== 'after_publication') return;+ writeFileSync(join(shim.dir, 'user.md'), readFileSync(join(root, FILE), 'utf8').replace(/title: .*/, 'title: USER STAGED EDIT'));+ shim.arm();+} });++/** Index locks and door index copies left in the checkout's git directory. */+const leftovers = (root: string) => readdirSync(join(root, '.git')).filter(name => name === 'index.lock' || name.startsWith('index.gbrain-'));++for (const backend of testBackends()) describe(`[${backend}] the door's index refresh holds the index lock`, () => {+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;++ test('a stage attempted while the door writes the index is refused on index.lock, never overwritten; a retry then holds', () => managedBrain(async ({ engine, ctx, root }) => {+ await committedPage(engine, ctx);+ const shim = gitShim(root, 'update-index --add', STAGE_USER);+ const result = await withEnv({ PATH: shim.path }, () => publish(engine, ctx, page('Second'), armAfterPublication(root, shim)));+ expect(existsSync(join(shim.dir, 'fired'))).toBe(true);+ const userOid = readFileSync(join(shim.dir, 'user.oid'), 'utf8');+ const accepted = readFileSync(join(shim.dir, 'stage.rc'), 'utf8').trim() === '0';+ expect({ accepted, kept: git(root, 'rev-parse', `:${FILE}`) === userOid, refusedOnLock: /index\.lock/.test(readFileSync(join(shim.dir, 'stage.out'), 'utf8')) })+ .toEqual({ accepted: false, kept: false, refusedOnLock: true });+ expect(result).toMatchObject({ state: 'committed' });+ expect(git(root, 'rev-parse', `:${FILE}`)).toBe(git(root, 'rev-parse', `HEAD:${FILE}`));+ expect(leftovers(root)).toEqual([]);+ git(root, 'update-index', '--add', '--cacheinfo', `100644,${userOid},${FILE}`);+ expect(git(root, 'rev-parse', `:${FILE}`)).toBe(userOid);+ }, { databaseUrl, setup }), 120_000);++ test('a stage that lands after the pre-commit check and before the lock is left staged; the refusal says the commit landed and names the path', () => managedBrain(async ({ engine, ctx, root }) => {+ await committedPage(engine, ctx);+ const shim = gitShim(root, 'update-ref', STAGE_USER);+ const result = await withEnv({ PATH: shim.path }, () => publish(engine, ctx, page('Second'), armAfterPublication(root, shim)));+ expect(readFileSync(join(shim.dir, 'stage.rc'), 'utf8').trim()).toBe('0');+ const userOid = readFileSync(join(shim.dir, 'user.oid'), 'utf8');+ expect(git(root, 'rev-parse', `:${FILE}`)).toBe(userOid);+ expect(/^title: (.*)$/m.exec(git(root, 'show', `HEAD:${FILE}`))?.[1]).toBe('Second');+ expect(result).toMatchObject({ state: 'failed', error_code: 'git_unavailable', error_message: expect.stringMatching(new RegExp(`landed, but the index of .* was left as it was for ${FILE}`)),+ outcome: { persistence: { git_state: 'committed', git_commit: git(root, 'rev-parse', 'HEAD') } } });+ expect(leftovers(root)).toEqual([]);+ }, { databaseUrl, setup }), 120_000);++ test('another writer holding index.lock during the refresh makes it refuse with the landed failure; its lock is left to it and the door leaves nothing behind', () => managedBrain(async ({ engine, ctx, root }) => {+ await committedPage(engine, ctx);+ const shim = gitShim(root, 'update-ref', `printf 'held by another writer' > "$ROOT/.git/index.lock"`);+ const result = await withEnv({ PATH: shim.path }, () => publish(engine, ctx, page('Second'), armAfterPublication(root, shim)));+ expect(result).toMatchObject({ state: 'failed', error_code: 'git_unavailable', error_message: expect.stringMatching(/landed, but the index of .* was not updated for notes\/probe\.md/),+ outcome: { persistence: { git_state: 'committed', git_commit: git(root, 'rev-parse', 'HEAD') } } });+ expect(/^title: (.*)$/m.exec(git(root, 'show', `HEAD:${FILE}`))?.[1]).toBe('Second');+ expect(readFileSync(join(root, '.git', 'index.lock'), 'utf8')).toBe('held by another writer');+ expect(leftovers(root)).toEqual(['index.lock']);+ rmSync(join(root, '.git', 'index.lock'));+ expect(leftovers(root)).toEqual([]);+ }, { databaseUrl, setup }), 120_000);+});++describe('door plumbing: the index lock', () => {+ test('a failed update of the index copy releases the lock and removes the copy; the refusal says the commit landed', async () => {+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-door-lock-')));+ dirs.push(root);+ git(root, 'init', '-q', '-b', 'main');+ git(root, 'config', 'user.name', 'Example Writer'); git(root, 'config', 'user.email', '[email protected]');+ mkdirSync(join(root, 'notes'));+ writeFileSync(join(root, 'notes/a.md'), 'a\n');+ git(root, 'add', '-A'); git(root, 'commit', '-qm', 'seed');+ const bin = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-git-shim-')));+ dirs.push(bin);+ writeFileSync(join(bin, 'git'), `#!/bin/sh\ncase " $* " in *" update-index "*) [ -n "$GIT_INDEX_FILE" ] && { echo 'fatal: refused by the test' >&2; exit 1; };; esac\nPATH='${process.env.PATH}' exec '${realGit()}' "$@"\n`, { mode: 0o755 });+ writeFileSync(join(root, 'notes/a.md'), 'door\n');+ utimesSync(join(root, 'notes/a.md'), new Date('2001-01-01T00:00:00Z'), new Date('2001-01-01T00:00:00Z'));+ const error = await withEnv({ PATH: `${bin}:${process.env.PATH}` }, () => refusal(commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }])));+ expect(error).toMatchObject({ code: 'git_unavailable', message: expect.stringContaining('landed, but the index') });+ expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('door');+ expect(leftovers(root)).toEqual([]);+ });+});