Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(git-door): compare HEAD's entry in index mode; conditional git_target_changed advice

garrytan3f391955d0eb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c8bc89cceb..35a5ad0df8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,9 +12,9 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
-**A page write on a Git-canonical source now commits exactly what it published, or nothing, and costs less Git time per write. A full sync stops reparsing pages that are already current.**
+**A page write on a Git-canonical source now commits exactly what it published, or nothing, and a new page costs less Git time to write. A full sync stops reparsing pages that are already current.**
-Before, a write on a source with `canonical: git` committed whatever the file held on disk when Git staged it, so an edit made while the write was publishing could land in the commit while the database recorded the write's own content. A staged change of the same file was silently replaced. Both now refuse with a named code and leave your files and index as they were. Separately, every write on a large checkout ran `git check-ignore` up to three times; most writes now skip it, so per-write overhead drops on big brains. And `gbrain sync --full` (including the two passes inside `gbrain sources canonical --apply`) admits an unchanged, fully current page without re-reading it, which makes a conversion with nothing to adopt much faster.
+Before, a write on a source with `canonical: git` committed whatever the file held on disk when Git staged it, so an edit made while the write was publishing could land in the commit while the database recorded the write's own content. A staged change of the same file was silently replaced. Both now refuse with a named code and leave your files and index as they were. Separately, writing a new page on a large checkout ran `git check-ignore` up to three times; most such writes now skip it, so their overhead drops on big brains. And `gbrain sync --full` (including the two passes inside `gbrain sources canonical --apply`) admits an unchanged, fully current page without re-reading it, which makes a conversion with nothing to adopt much faster.
### What changed
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 2151a391de..6eafb98264 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -1823,7 +1823,7 @@ More: [docs/guides/write-refusals.md#git_protocol_required](../../docs/guides/wr
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A strict (canonical: git) write's file changed on disk while it was being committed, so nothing was committed and the write was not published. | The door commits exactly the bytes the write published, and checks the file's hash against them before and after Git stores it. An edit landing in between would otherwise be committed while the database records other content; recovery leaves the changed file as it is. | The write is held in recovery (blocked reason unexpected_file_bytes) and the source's later writes wait behind it. Preview with gbrain repair stuck-recovery --source <id> --json, ask the user which version to keep, then run gbrain repair stuck-recovery --source <id> --keep disk\|prior --apply --expect <preview_hash> --yes (disk keeps the edit). Run: gbrain sources writer status --json | user | `repeat the read that failed` | 1 | no |
+| A strict (canonical: git) write's file changed on disk while it was being committed, so nothing was committed and the write was not published. | The door commits exactly the bytes the write published, and checks the file's hash against them before and after Git stores it. An edit landing in between would otherwise be committed while the database records other content; recovery leaves the changed file as it is. | When the file holds neither the write's bytes nor the version before it, the write is held in recovery (blocked reason unexpected_file_bytes) and the source's later writes wait behind it; when it holds the version before the write, nothing is held and the write failed, so read the page before resubmitting it with a new request_id. To resolve a held write, preview with gbrain repair stuck-recovery --source <id> --json, ask the user which version to keep, then run gbrain repair stuck-recovery --source <id> --keep disk\|prior --apply --expect <preview_hash> --yes (disk keeps the edit). Run: gbrain sources writer status --json | user | `repeat the read that failed` | 1 | no |
### git_target_ignored
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 22a98c8fd7..c4d30ed271 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -329,7 +329,7 @@ export const CODES = {
git_target_pending: { class: 'retryable', summary: "Git still lists a removed canonical file in the index; the removal was not committed yet." },
git_operation_in_progress: { class: 'caller', summary: "A rebase, merge, cherry-pick or revert is in progress in the checkout, so gbrain will not commit or move it.", docs: 'docs/guides/shared-checkout-git.md#stuck-rebase' },
git_push_unavailable: { class: 'retryable', summary: "The canonical commit is durable locally; its push will retry." },
- git_target_changed: { class: 'caller', actor: 'user', summary: "A strict (canonical: git) write's file changed on disk while it was being committed, so nothing was committed and the write was not published.", why: "The door commits exactly the bytes the write published, and checks the file's hash against them before and after Git stores it. An edit landing in between would otherwise be committed while the database records other content; recovery leaves the changed file as it is.", suggestion: "The write is held in recovery (blocked reason unexpected_file_bytes) and the source's later writes wait behind it. Preview with gbrain repair stuck-recovery --source <id> --json, ask the user which version to keep, then run gbrain repair stuck-recovery --source <id> --keep disk|prior --apply --expect <preview_hash> --yes (disk keeps the edit).", fix: { argv: ['gbrain', 'sources', 'writer', 'status', '--json'], consent: [], actor: 'agent', why: 'Read-only: lists the held request, its source and its blocked reason.', requires_exclusive: false } },
+ git_target_changed: { class: 'caller', actor: 'user', summary: "A strict (canonical: git) write's file changed on disk while it was being committed, so nothing was committed and the write was not published.", why: "The door commits exactly the bytes the write published, and checks the file's hash against them before and after Git stores it. An edit landing in between would otherwise be committed while the database records other content; recovery leaves the changed file as it is.", suggestion: "When the file holds neither the write's bytes nor the version before it, the write is held in recovery (blocked reason unexpected_file_bytes) and the source's later writes wait behind it; when it holds the version before the write, nothing is held and the write failed, so read the page before resubmitting it with a new request_id. To resolve a held write, preview with gbrain repair stuck-recovery --source <id> --json, ask the user which version to keep, then run gbrain repair stuck-recovery --source <id> --keep disk|prior --apply --expect <preview_hash> --yes (disk keeps the edit).", fix: { argv: ['gbrain', 'sources', 'writer', 'status', '--json'], consent: [], actor: 'agent', why: 'Read-only: lists the held request, its source and its blocked reason.', requires_exclusive: false } },
git_target_ignored: { class: 'caller', summary: "A .gitignore rule excludes the canonical file, so its Git effect cannot commit it; the effect parks at once.", suggestion: 'Remove or narrow the rule and commit that change, then run gbrain sources writer retry-effects <source> --parked-code git_target_ignored; or keep the file out of Git and leave the effect parked.' },
git_target_unsafe: { class: 'caller', summary: "Git cannot identify the existing canonical file by its native spelling." },
git_unavailable: { class: 'retryable', summary: "A git command did not complete." },
diff --git a/src/core/persistence/git-door.ts b/src/core/persistence/git-door.ts
index c096402061..6f3bde7c19 100644
--- a/src/core/persistence/git-door.ts
+++ b/src/core/persistence/git-door.ts
@@ -268,7 +268,8 @@ async function doorCommit(session: GitSession, root: string, files: DoorFile[],
for (const target of targets.values()) {
const dir = dirs.get(target.dir)!;
const before = dir.found.get(target.name);
- target.head = before && before.mode !== TREE_MODE ? `${before.mode} ${before.oid.toString('hex')}` : undefined;
+ const indexMode = before && /^100[0-7]{3}$/.test(before.mode) ? (parseInt(before.mode, 8) & 0o100 ? '100755' : '100644') : before?.mode;
+ target.head = before && before.mode !== TREE_MODE ? `${indexMode} ${before.oid.toString('hex')}` : undefined;
if (target.oid) {
if (!before || before.mode === TREE_MODE) fresh.push(target);
if (before && /^100[0-7]{3}$/.test(before.mode) && target.mode !== before.mode) {
@@ -367,7 +368,7 @@ function refuseChanged(root: string, targets: Iterable<Target>): void {
const moved = [...targets].filter(target => { try { return hashFile(join(root, target.rel)) !== target.planned; } catch { return true; } }).map(target => target.rel);
if (!moved.length) return;
throw opError('git_target_changed', `${moved.join(', ')} in ${root} no longer holds the bytes this write published, so nothing was committed and the write was not published.`,
- 'Another process changed the file during the write; recovery leaves the changed file as it is and holds the write, so the source\'s later writes wait. Preview with gbrain repair stuck-recovery --source <id> --json, ask the user which version to keep, then run gbrain repair stuck-recovery --source <id> --keep disk|prior --apply --expect <preview_hash> --yes (disk keeps the edit).', { detail: moved.join(',') });
+ 'Another process changed the file during the write. If the file now holds neither this write\'s bytes nor the version before it, recovery leaves it as it is and holds the write, so the source\'s later writes wait: preview with gbrain repair stuck-recovery --json, ask the user which version to keep, then apply that choice with the --keep, --expect and --apply --yes flags the preview lists (--keep disk keeps the edit). If it holds the version before the write, nothing is held and the write failed; read the page before resubmitting it with a new request_id.', { detail: moved.join(',') });
}
/** Targets whose index entry differs from HEAD's and from the version their path's last commit replaced (a staged change, or a merge conflict) refuse as `git_index_conflict`. */
diff --git a/test/git-door-planned-state.test.ts b/test/git-door-planned-state.test.ts
index 057402213a..1356f0b1d0 100644
--- a/test/git-door-planned-state.test.ts
+++ b/test/git-door-planned-state.test.ts
@@ -181,6 +181,26 @@ for (const backend of testBackends()) describe(`[${backend}] the door commits on
expect(git(root, 'status', '--porcelain')).toBe('');
}, { databaseUrl, setup }), 180_000);
+ test('D4 resolution: repair stuck-recovery --keep prior writes the committed bytes back, ends the write failed and frees later writes', () => managedBrain(async ({ engine, ctx, root }) => {
+ await committedPage(engine, ctx);
+ const head = git(root, 'rev-parse', 'HEAD'), committed = git(root, 'rev-parse', `HEAD:${FILE}`);
+ const d4 = await publish(engine, ctx, page('Second'), { boundary: async name => {
+ if (name !== 'after_publication') return;
+ writeFileSync(join(root, FILE), readFileSync(join(root, FILE), 'utf8').replace('title: Second', 'title: USER DISK EDIT'));
+ } });
+ expect(d4).toMatchObject({ state: 'recovering', error_code: 'git_target_changed', blocked_reason: 'unexpected_file_bytes' });
+ const preview = await repairCli(engine, ['stuck-recovery', '--source', 'default', '--json']);
+ const hash = /"preview_hash": "([0-9a-f]{64})"/.exec(preview)![1]!;
+ const applied = await repairCli(engine, ['stuck-recovery', '--source', 'default', '--keep', 'prior', '--apply', '--expect', hash, '--yes', '--json']);
+ expect(applied).toContain('"resolved": 1');
+ expect(await getWriteRequestById(engine, d4.id)).toMatchObject({ state: 'failed', error_code: 'git_target_changed', recovery: null });
+ expect(await standing(engine, root)).toEqual({ row: 'First', head: 'First', disk: 'First', index: committed });
+ expect(git(root, 'rev-parse', 'HEAD')).toBe(head);
+ expect(git(root, 'status', '--porcelain')).toBe('');
+ expect(await publish(engine, ctx, page('Third'))).toMatchObject({ state: 'committed' });
+ expect(await standing(engine, root)).toEqual({ row: 'Third', head: 'Third', disk: 'Third', index: git(root, 'rev-parse', `HEAD:${FILE}`) });
+ }, { databaseUrl, setup }), 180_000);
+
test('a stale index entry from an interrupted door refresh is restored, and the receipt and notice name the path', () => managedBrain(async ({ engine, ctx, root }) => {
await committedPage(engine, ctx);
expect(await publish(engine, ctx, page('Second'))).toMatchObject({ state: 'committed' });
@@ -279,6 +299,19 @@ describe('door plumbing: the planned state', () => {
expect(git(root, 'status', '--porcelain')).toBe('');
});
+ test('a HEAD entry with a legacy group-writable mode (100664) is not a staged change; the write commits', async () => {
+ const root = repo({ 'notes/a.md': 'a\n' });
+ const blob = execFileSync('git', ['-C', root, 'hash-object', '-w', '--stdin'], { input: 'legacy\n', env, encoding: 'utf8' }).trim();
+ const tree = execFileSync('git', ['-C', root, 'hash-object', '-t', 'tree', '--literally', '-w', '--stdin'],
+ { input: Buffer.concat([Buffer.from('100664 legacy.md\0'), Buffer.from(blob, 'hex')]), env, encoding: 'utf8' }).trim();
+ git(root, 'update-ref', 'refs/heads/main', git(root, 'commit-tree', tree, '-p', 'HEAD', '-m', 'legacy mode'));
+ git(root, 'reset', '-q', '--hard');
+ expect(git(root, 'ls-files', '-s', '--', 'legacy.md')).toStartWith('100644 ');
+ expect(await publishAt(root, 'legacy.md', 'door\n')).toBe(git(root, 'rev-parse', 'HEAD'));
+ expect(git(root, 'show', 'HEAD:legacy.md')).toBe('door');
+ expect(git(root, 'status', '--porcelain')).toBe('');
+ });
+
test('a change staged after the check and before the index refresh is left staged; the refusal says the commit landed', async () => {
const root = repo({ 'notes/a.md': 'a\n', 'notes/b.md': 'b\n' });
let staged = '';