Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes for the door's locked index refresh (#7742)

garrytan3688d30ee836
diff --git a/src/core/persistence/effect-git.ts b/src/core/persistence/effect-git.ts
index e1643713ea..8050915185 100644
--- a/src/core/persistence/effect-git.ts
+++ b/src/core/persistence/effect-git.ts
@@ -99,6 +99,18 @@ const staleLockFix = (root: string, lock: string, why: string): Action => ({
verify: { argv: ['gbrain', 'sources', 'writer', 'status', '--json'] },
});
+/**
+ * #6932: while this session's caller holds the checkout's writer lock, reclaims `lock` once it is proven abandoned
+ * (index-lock-reclaim.ts). True when it was reclaimed; otherwise why it stays.
+ */
+export function reclaimAbandonedIndexLock(session: GitSession, lock: string): true | string {
+ if (!session.owner || session.owner.writerLock.released) return 'this caller does not hold the checkout\'s writer lock';
+ const verdict = proveIndexLockAbandoned(lock, session.root, INDEX_LOCK_GRACE_MS);
+ const receipt = verdict.abandoned ? reclaimIndexLock(lock, session.root, verdict) : null;
+ if (receipt) { session.owner.onReclaim?.(receipt); return true; }
+ return verdict.abandoned ? 'the lock changed while it was being reclaimed' : verdict.reason;
+}
+
/**
* Git refused because another process holds this checkout's index lock. Only the checkout's own index lock
* (`git rev-parse --git-path index.lock`, so linked worktrees resolve) qualifies; a ref or remote lock with
@@ -117,11 +129,10 @@ async function indexLockError(session: GitSession, stderr: string, mayReclaim: b
let age: number;
try { age = Date.now() - statSync(lock).mtimeMs; } catch { return null; }
let why = 'this caller does not hold the checkout\'s writer lock';
- if (session.owner && !session.owner.writerLock.released && mayReclaim) {
- const verdict = proveIndexLockAbandoned(lock, session.root, INDEX_LOCK_GRACE_MS);
- const receipt = verdict.abandoned ? reclaimIndexLock(lock, session.root, verdict) : null;
- if (receipt) { session.owner.onReclaim?.(receipt); return 'reclaimed'; }
- why = verdict.abandoned ? 'the lock changed while it was being reclaimed' : verdict.reason;
+ if (mayReclaim) {
+ const reclaimed = reclaimAbandonedIndexLock(session, lock);
+ if (reclaimed === true) return 'reclaimed';
+ why = reclaimed;
}
if (age >= 0 && age < INDEX_LOCK_GRACE_MS) {
return new OperationError('git_index_locked', 'Another Git process holds the canonical checkout index lock.', 'The effect is retried shortly.');
diff --git a/src/core/persistence/git-door.ts b/src/core/persistence/git-door.ts
index 242ed91854..1574a98772 100644
--- a/src/core/persistence/git-door.ts
+++ b/src/core/persistence/git-door.ts
@@ -43,7 +43,7 @@ import { closeSync, copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, mk
import { join, relative, resolve, sep } from 'node:path';
import type { Notice } from '../agent-output.ts';
import { OperationError, opError } from '../ops/contract.ts';
-import { commitMessage, git, gitBytes, gitFailure, gitStepTimeoutMs, ignoredTargetError, withSession, type GitSession } from './effect-git.ts';
+import { commitMessage, git, gitBytes, gitFailure, gitStepTimeoutMs, ignoredTargetError, reclaimAbandonedIndexLock, withSession, type GitSession } from './effect-git.ts';
import type { GitCommitNote } from './effect-model.ts';
import { persistenceHome } from './identity.ts';
import { ignoreCandidates } from './ignore-rules.ts';
@@ -435,16 +435,22 @@ async function replacedEntries(session: GitSession, commit: string, targets: Tar
* 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.
+ * A writer that reads the index before locking it (a raw `git commit -- <path>`) is outside this guarantee. The lock
+ * stays open until its rename, so the #6932 proof never takes it for abandoned; a lock that proof does find abandoned is
+ * reclaimed under the caller's writer lock before the refresh gives up.
*/
async function syncIndex(session: GitSession, root: string, prefix: string, index: string, targets: Target[], commit: string, seen: IndexSnapshot): Promise<void> {
- let failure = '', restaged: Target[] = [], held = false;
+ let failure = '', restaged: Target[] = [], held = false, fd: number | null = null;
const lock = `${index}.lock`, copy = `${index}.gbrain-${process.pid}-${randomBytes(6).toString('hex')}`;
+ const take = () => {
+ try { return openSync(lock, 'wx'); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'EEXIST') return null; throw error; }
+ };
try {
- 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`;
- }
+ fd = take();
+ const reclaimed = fd === null ? reclaimAbandonedIndexLock(session, lock) : true;
+ if (fd === null && reclaimed === true) fd = take();
+ held = fd !== null;
+ if (!held) failure = `Unable to create '${lock}': File exists; another git process holds the index lock${reclaimed === true ? '' : ` (not reclaimed: ${reclaimed})`}`;
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.
@@ -456,14 +462,15 @@ async function syncIndex(session: GitSession, root: string, prefix: string, inde
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}`]),
+ const updated = await git({ ...session, indexFile: copy }, ['update-index', '--add', '--force-write-index', ...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; }
+ else { closeSync(fd!); fd = null; renameSync(copy, lock); renameSync(lock, index); held = false; }
}
}
} catch (error) { failure = error instanceof Error ? error.message : String(error); }
finally {
+ if (fd !== null) closeSync(fd);
rmSync(copy, { force: true });
if (held) rmSync(lock, { force: true });
}
diff --git a/test/git-door-index-lock-7742.test.ts b/test/git-door-index-lock-7742.test.ts
index 1e084fb07e..3ef923b541 100644
--- a/test/git-door-index-lock-7742.test.ts
+++ b/test/git-door-index-lock-7742.test.ts
@@ -9,12 +9,14 @@
* - 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; in a linked worktree the lock
- * and the refresh are on that worktree's own index (rev-parse --git-path index), never the main checkout's.
+ * and the refresh are on that worktree's own index (rev-parse --git-path index), never the main checkout's; an
+ * unrelated path staged between the door's pre-commit read and its lock survives the locked write; a lock the door
+ * cannot create for a reason other than an existing lock still reports the landed commit and names that cause.
*/
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 { chmodSync, 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';
@@ -23,9 +25,12 @@ 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 { INDEX_LOCK_GRACE_FOR_TESTS } from '../src/core/persistence/effect-git.ts';
+import { commitThroughDoor, doorSeams } from '../src/core/persistence/git-door.ts';
import { localHostId } from '../src/core/persistence/identity.ts';
+import { proveIndexLockAbandoned } from '../src/core/persistence/index-lock-reclaim.ts';
import { admitWrite, claimNextWrite } from '../src/core/persistence/journal.ts';
+import { tryAcquireNativeLock } from '../src/core/persistence/native-lock.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';
@@ -45,7 +50,7 @@ const page = (title: string) => `---\ntype: note\ntitle: ${title}\n---\n\nA smal
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 }); });
+afterEach(() => { delete doorSeams.beforeUpdateRef; 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> `
@@ -197,4 +202,106 @@ describe('door plumbing: the index lock', () => {
expect(readdirSync(gitDir).filter(name => name === 'index.lock' || name.startsWith('index.gbrain-'))).toEqual([]);
expect(leftovers(main)).toEqual([]);
});
+
+ /** A plain repository whose seed commit holds notes/a.md and other/b.md. */
+ const seeded = () => {
+ 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')); mkdirSync(join(root, 'other'));
+ writeFileSync(join(root, 'notes/a.md'), 'a\n'); writeFileSync(join(root, 'other/b.md'), 'b\n');
+ git(root, 'add', '-A'); git(root, 'commit', '-qm', 'seed');
+ return root;
+ };
+
+ // Value: protects=an unrelated path staged after the door's pre-commit index read stays staged once the door renames its locked index
+ // copy into place, and the target is refreshed; fails_when=the copy is taken before the lock (a stale snapshot) or holds only the
+ // targets; why_new=gbra133 stages its unrelated path before the write (index unmoved) and the #7705 mid-write stage is a target;
+ // seam=none; no_claim=a writer that stages without index.lock (doorSeams.beforeUpdateRef stands in for a concurrent git add)
+ test('an unrelated path staged between the pre-commit read and the lock stays staged; the target is refreshed', async () => {
+ const root = seeded();
+ let staged = '';
+ doorSeams.beforeUpdateRef = () => {
+ writeFileSync(join(root, 'other/b.md'), 'staged meanwhile\n'); git(root, 'add', 'other/b.md');
+ staged = git(root, 'rev-parse', ':other/b.md');
+ };
+ writeFileSync(join(root, 'notes/a.md'), 'door\n');
+ const commit = await commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }]);
+ expect(commit).toBe(git(root, 'rev-parse', 'HEAD'));
+ expect(git(root, 'show', '--name-only', '--format=', commit!)).toBe('notes/a.md');
+ expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
+ expect(git(root, 'rev-parse', ':other/b.md')).toBe(staged);
+ expect(git(root, 'diff', '--cached', '--name-only')).toBe('other/b.md');
+ expect(leftovers(root)).toEqual([]);
+ });
+
+ // Value: protects=a lock create failing other than EEXIST (an unwritable git dir) still reports the landed commit, names that cause and
+ // leaves the index as it was; fails_when=any lock error is reported as another git holding the lock, or escapes as not published;
+ // why_new=the existing lock test covers only EEXIST; seam=none; no_claim=root runs (chmod does not bind root, so the test skips there); a git shim makes the dir read-only after update-ref
+ test.skipIf(process.getuid?.() === 0)('a lock the door cannot create for another reason reports the landed commit and names the cause; the index is left as it was', async () => {
+ const root = seeded(), gitDir = join(root, '.git');
+ const before = git(root, 'rev-parse', ':notes/a.md');
+ const bin = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-git-shim-')));
+ dirs.push(bin);
+ writeFileSync(join(bin, 'git'), `#!/bin/sh\ncase " $* " in *" update-ref "*) PATH='${process.env.PATH}' '${realGit()}' "$@"; rc=$?; chmod 555 '${gitDir}'; exit $rc;; esac\nPATH='${process.env.PATH}' exec '${realGit()}' "$@"\n`, { mode: 0o755 });
+ writeFileSync(join(root, 'notes/a.md'), 'door\n');
+ let error: { code?: string; message?: string; suggestion?: string } | null;
+ try {
+ error = await withEnv({ PATH: `${bin}:${process.env.PATH}` }, () => refusal(commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }])));
+ } finally { chmodSync(gitDir, 0o755); }
+ expect(error).toMatchObject({ code: 'git_unavailable', message: expect.stringContaining('landed, but the index'), suggestion: expect.stringMatching(/permission denied/i) });
+ expect(/another git process holds the index lock/.test(error!.suggestion!)).toBe(false);
+ expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('door');
+ expect(git(root, 'rev-parse', ':notes/a.md')).toBe(before);
+ expect(leftovers(root)).toEqual([]);
+ });
+ // Value: protects=a refresh whose index update changes nothing (only removals of paths the index lacks) leaves no index.lock behind and
+ // no hard-linked second name for the index; fails_when=the door renames an unwritten hard-linked copy onto the lock and the lock onto the
+ // index, a no-op that keeps both names; why_new=every other refresh case changes an entry, so Git writes a new file; seam=none;
+ // no_claim=indexes with a TREE extension, where Git always writes (doorSeams.beforeUpdateRef stands in for a concurrent git update-index)
+ test('a refresh whose update changes nothing leaves no index.lock behind', async () => {
+ const root = seeded();
+ rmSync(join(root, '.git', 'index'));
+ git(root, 'update-index', '--add', 'notes/a.md', 'other/b.md');
+ doorSeams.beforeUpdateRef = () => {
+ const oid = execFileSync('git', ['-C', root, 'hash-object', '-w', '--stdin'], { input: 'staged meanwhile\n', encoding: 'utf8' }).trim();
+ git(root, 'update-index', '--cacheinfo', `100644,${oid},notes/a.md`);
+ };
+ writeFileSync(join(root, 'notes/a.md'), 'door\n');
+ const error = await refusal(commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }, { path: join(root, 'notes/ghost.md'), planned: null }]));
+ expect(error).toMatchObject({ code: 'git_unavailable', message: expect.stringContaining('was left as it was for notes/a.md') });
+ expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('door');
+ expect(leftovers(root)).toEqual([]);
+ expect(git(root, 'diff', '--cached', '--name-only')).toBe('notes/a.md');
+ });
+ // Value: protects=the door, holding the writer lock, reclaims an index.lock no live process holds (#6932) and finishes its refresh,
+ // as it did when update-index ran through effect-git; fails_when=the door's own exclusive create answers any existing lock with the
+ // landed failure; why_new=the held-lock test uses a fresh lock no proof accepts; seam=none; no_claim=hosts where the proof cannot see
+ // every process, where the lock must stay and the landed failure stands (the oracle is the same proof the door runs)
+ test('an abandoned index.lock is reclaimed under the writer lock and the refresh completes', async () => {
+ const root = seeded(), lock = join(root, '.git', 'index.lock');
+ const home = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-door-home-')));
+ dirs.push(home);
+ writeFileSync(lock, '');
+ const old = new Date(Date.now() - 60_000);
+ utimesSync(lock, old, old);
+ writeFileSync(join(root, 'notes/a.md'), 'door\n');
+ await withEnv({ GBRAIN_HOME: home }, async () => {
+ const writer = (await tryAcquireNativeLock(join(home, 'writer.lock')))!;
+ try {
+ const provable = proveIndexLockAbandoned(lock, root, INDEX_LOCK_GRACE_FOR_TESTS).abandoned;
+ const error = await refusal(commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }], writer));
+ expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('door');
+ if (!provable) {
+ expect(error).toMatchObject({ code: 'git_unavailable', message: expect.stringContaining('landed, but the index') });
+ expect(existsSync(lock)).toBe(true);
+ return;
+ }
+ expect(error).toBeNull();
+ expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
+ expect(leftovers(root)).toEqual([]);
+ } finally { await writer.release(); }
+ });
+ });
});