Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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; 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; 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, spawnSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { chmodSync, closeSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { basename, 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 { INDEX_LOCK_GRACE_FOR_TESTS } from '../src/core/persistence/effect-git.ts';
import { commitThroughDoor, doorSeams, indexCommitIo } from '../src/core/persistence/git-door.ts';
import { localHostId } from '../src/core/persistence/identity.ts';
import { processTableBlind, proveIndexLockAbandoned, readIndexLockReclaims, type IndexLockVerdict } 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';
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[] = [];
const io = { ...indexCommitIo };
afterEach(() => {
delete doorSeams.beforeUpdateRef; delete doorSeams.indexLockHeld; Object.assign(indexCommitIo, io);
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-'));
/** Why the #6932 proof may keep a lock on a host it cannot fully see: another user's git, or one that stayed unreadable while it exited. */
const HOST_DOUBT = /not reclaimed: git process \d+ \(.*\) (belongs to another user|could not be inspected|is this user's, but it stayed unreadable)/;
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([]);
});
test('in a linked worktree the door locks and refreshes that worktree\'s own index, never the main checkout\'s', async () => {
const main = realpathSync(mkdtempSync(join(tmpdir(), 'gbrain-door-lock-')));
dirs.push(main);
git(main, 'init', '-q', '-b', 'main');
git(main, 'config', 'user.name', 'Example Writer'); git(main, 'config', 'user.email', '[email protected]');
mkdirSync(join(main, 'notes'));
writeFileSync(join(main, 'notes/a.md'), 'a\n');
git(main, 'add', '-A'); git(main, 'commit', '-qm', 'seed');
const root = join(main, '..', `${main.split('/').pop()}-linked`);
dirs.push(root);
git(main, 'worktree', 'add', '-q', '-b', 'side', root);
const lock = `${git(root, 'rev-parse', '--path-format=absolute', '--git-path', 'index')}.lock`;
expect(lock).not.toBe(join(main, '.git', 'index.lock'));
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" ] && { [ -f '${lock}' ] && : > '${bin}/locked'; [ -f '${join(main, '.git', 'index.lock')}' ] && : > '${bin}/main-locked'; };; esac\nPATH='${process.env.PATH}' exec '${realGit()}' "$@"\n`, { mode: 0o755 });
const mainIndex = readFileSync(join(main, '.git', 'index'));
writeFileSync(join(root, 'notes/a.md'), 'door\n');
await withEnv({ PATH: `${bin}:${process.env.PATH}` }, () => commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }]));
expect({ locked: existsSync(join(bin, 'locked')), mainLocked: existsSync(join(bin, 'main-locked')) }).toEqual({ locked: true, mainLocked: false });
expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('door');
expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
expect(readFileSync(join(main, '.git', 'index')).equals(mainIndex)).toBe(true);
expect(git(main, 'show', 'main:notes/a.md')).toBe('a');
const gitDir = join(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, or another user's git runs, where the lock must stay and the landed failure stands. The oracle is the door's own
// verdict (its receipt, or the reason its refusal names), never a second proof that a git starting in between could flip (#7758)
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 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');
const reclaims = readIndexLockReclaims().filter(receipt => receipt.lock === lock);
if (error) {
const blind = processTableBlind();
expect(error).toMatchObject({ code: 'git_unavailable', message: expect.stringContaining('landed, but the index'),
suggestion: blind ? expect.stringContaining(`not reclaimed: ${blind}`) : expect.stringMatching(HOST_DOUBT) });
expect(existsSync(lock)).toBe(true);
expect(reclaims).toEqual([]);
return;
}
expect(reclaims).toHaveLength(1);
expect(existsSync(lock)).toBe(false);
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(); }
});
});
// Value: protects=index copies a refresh killed before its cleanup left in the git directory (and their Git locks) are removed by the next
// refresh while it holds index.lock, once their process is gone, while a live process's copy stays (#7755); fails_when=nothing sweeps
// index.gbrain-*, so each crash leaves an index-sized file; why_new=no test plants a stale copy; seam=none; no_claim=a reused pid
test('index copies a killed refresh left are removed under the lock once their process is gone; a live process\'s copy stays', async () => {
const root = seeded(), gitDir = join(root, '.git');
const dead = spawnSync('true').pid;
expect(() => process.kill(dead, 0)).toThrow();
const stale = [`index.gbrain-${dead}-0123456789ab`, `index.gbrain-${dead}-0123456789ab.lock`], live = `index.gbrain-${process.ppid}-ba9876543210`;
for (const name of [...stale, live]) writeFileSync(join(gitDir, name), 'a copy of the index');
writeFileSync(join(root, 'notes/a.md'), 'door\n');
expect(await commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }])).toBe(git(root, 'rev-parse', 'HEAD'));
expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
expect(leftovers(root)).toEqual([live]);
});
// Value: protects=a dead process's leftover the sweep cannot remove (a directory here; EBUSY or EPERM on Windows) never fails the refresh
// of a commit that landed (#7755 review); fails_when=the sweep's removal error ends the write with the landed git_unavailable failure and
// leaves the index behind HEAD on every later write; why_new=the sweep test plants only removable files; seam=none; no_claim=a real EBUSY
test('a stale index copy the sweep cannot remove is left in place and the refresh still completes', async () => {
const root = seeded(), gitDir = join(root, '.git');
const dead = spawnSync('true').pid;
const stuck = `index.gbrain-${dead}-0123456789ab`;
mkdirSync(join(gitDir, stuck));
writeFileSync(join(gitDir, stuck, 'x'), 'x');
writeFileSync(join(root, 'notes/a.md'), 'door\n');
expect(await commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }])).toBe(git(root, 'rev-parse', 'HEAD'));
expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
expect(leftovers(root)).toEqual([stuck]);
});
// Value: protects=on win32 a transient sharing violation (EPERM, EBUSY, EACCES) on the renames that commit the refreshed index is retried,
// as Git for Windows retries its own, while other platforms fail at once as before (#7756); fails_when=one refused rename ends the write
// with the landed failure on Windows, or a retry runs elsewhere; why_new=no Windows path was tested; seam=indexCommitIo (rename, platform);
// no_claim=a real Windows sharing violation
for (const platform of ['win32', 'linux'] as const) test(`a transiently refused index rename is retried on win32 only (${platform})`, async () => {
const root = seeded(), before = git(root, 'rev-parse', ':notes/a.md');
const renames: string[] = [];
let refused = 0;
Object.assign(indexCommitIo, { platform, rename: (from: string, to: string) => {
renames.push(basename(to));
if (refused++ < 2) throw Object.assign(new Error(`EPERM: operation not permitted, rename '${from}' -> '${to}'`), { code: 'EPERM' });
renameSync(from, to);
} });
writeFileSync(join(root, 'notes/a.md'), 'door\n');
const error = await refusal(commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }]));
expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('door');
if (platform === 'win32') {
expect(error).toBeNull();
expect(renames).toEqual(['index.lock', 'index.lock', 'index.lock', 'index']);
expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
} else {
expect(error).toMatchObject({ code: 'git_unavailable', message: expect.stringContaining('landed, but the index'), suggestion: expect.stringContaining('EPERM') });
expect(renames).toEqual(['index.lock']);
expect(git(root, 'rev-parse', ':notes/a.md')).toBe(before);
}
expect(leftovers(root)).toEqual([]);
});
// Value: protects=the door keeps its index.lock descriptor open while it refreshes the index, so the #6932 abandoned-lock proof run at that
// moment (an aged, empty lock, no git child running) names this process as the holder and never counts the lock abandoned (#7757);
// fails_when=the descriptor is closed right after the create; why_new=every other door test passes with it closed early;
// seam=doorSeams.indexLockHeld; no_claim=hosts where the proof cannot see every process (the test skips there)
test.skipIf(processTableBlind() !== null)('the door holds its index.lock open during the refresh, so the abandoned-lock proof finds it held', async () => {
const root = seeded(), lock = join(root, '.git', 'index.lock');
let verdict: IndexLockVerdict | undefined;
doorSeams.indexLockHeld = held => {
const old = new Date(Date.now() - 60_000);
utimesSync(held, old, old);
verdict = proveIndexLockAbandoned(held, root, INDEX_LOCK_GRACE_FOR_TESTS);
};
writeFileSync(join(root, 'notes/a.md'), 'door\n');
expect(await commitThroughDoor(root, [{ path: join(root, 'notes/a.md'), planned: sha256('door\n') }])).toBe(git(root, 'rev-parse', 'HEAD'));
expect(verdict).toEqual({ abandoned: false, reason: expect.stringMatching(new RegExp(`^process ${process.pid} \\(.*\\) has the lock open$`)) });
expect(existsSync(lock)).toBe(false);
expect(git(root, 'rev-parse', ':notes/a.md')).toBe(git(root, 'rev-parse', 'HEAD:notes/a.md'));
});
// Value: protects=a close of the held index.lock that fails (EIO on a network filesystem) still ends in the landed failure and removes the
// lock and the index copy (#7758); fails_when=the finally closes the released descriptor again, its EBADF escapes the landed failure and
// skips the cleanup; why_new=no close failure was tested; seam=indexCommitIo.close; no_claim=a real EIO
test('a failed close of the held index.lock still reports the landed commit and leaves no lock or index copy', async () => {
const root = seeded(), before = git(root, 'rev-parse', ':notes/a.md');
indexCommitIo.close = (fd: number) => { closeSync(fd); throw Object.assign(new Error('EIO: i/o error, close'), { code: 'EIO' }); };
writeFileSync(join(root, 'notes/a.md'), 'door\n');
const error = await 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'), suggestion: expect.stringContaining('EIO') });
expect(git(root, 'show', 'HEAD:notes/a.md')).toBe('door');
expect(git(root, 'rev-parse', ':notes/a.md')).toBe(before);
expect(leftovers(root)).toEqual([]);
});
});